@sharedex/ui 0.0.0-stage → 0.9.0

package/dist/text/type/Typewriter.js

@@ -0,0 +1,107 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useEffect, useRef } from "react";
+import { styleHref } from "../../backgrounds/hosts/CssHost.js";
+import { motionOnly } from "../../transitions/progress.js";
+import { reducedMotion, watchOnScreen } from "../runtime/onScreen.js";
+import { loopsPaused, onLoopsPaused } from "../runtime/loops.js";
+import { graphemes } from "../split.js";
+import { TYPE_BASE_CSS, TYPE_MOTION_CSS } from "./css.js";
+import { typeFrame } from "./timeline.js";
+const seconds = (n) => `${Number(n.toFixed(3))}s`;
+/**
+ * Types text out letter by letter, line after line.
+ *
+ * ```tsx
+ * <h1>We build <Typewriter lines={["websites", "apps", "brands"]} erase /></h1>
+ * ```
+ *
+ * Every line is in the HTML, stacked in one place, so search engines read them all and the box keeps the size of the
+ * longest: nothing around it moves as it types. Screen readers read the lines once, not every letter. Arabic is typed
+ * letter by letter and joins up as it goes, as real typing does. Under reduced motion it shows the first line.
+ */
+export function Typewriter({ lines, mode = "js", erase = false, loop = lines.length > 1, speed = 14, pause = 1.6, delay = 0, caret = true, preset, start = "inView", as: Tag = "span", className, style, }) {
+    const ref = useRef(null);
+    const first = lines[0] ?? "";
+    const key = JSON.stringify([lines, erase, loop, speed, pause, delay, start]);
+    useEffect(() => {
+        const el = ref.current;
+        if (!el)
+            return;
+        el.setAttribute("data-sx-live", "");
+        const mark = (on) => {
+            if (on)
+                el.setAttribute("data-sx-on", "");
+            else
+                el.removeAttribute("data-sx-on");
+        };
+        const node = el.querySelector("[data-sx-type-text]")?.firstChild;
+        // the CSS mode needs nothing but the on-screen mark (the caret pauses without it)
+        if (mode === "css" || !node || reducedMotion())
+            return watchOnScreen(el, mark);
+        const letters = lines.map((l) => graphemes(l));
+        const timing = { speed, eraseSpeed: speed * 2.2, pause, gap: 0.35, erase, loop };
+        let visible = false;
+        let started = start === "mount";
+        let elapsed = -delay;
+        let last = 0;
+        let frame = 0;
+        let shown = "";
+        const write = (text) => {
+            if (text !== shown)
+                node.nodeValue = shown = text;
+        };
+        const tick = (now) => {
+            frame = 0;
+            if (!visible || loopsPaused())
+                return;
+            elapsed += Math.min(0.1, (now - last) / 1000);
+            last = now;
+            if (elapsed >= 0) {
+                const f = typeFrame(letters.map((l) => l.length), elapsed, timing);
+                write((letters[f.line] ?? []).slice(0, f.shown).join(""));
+                el.setAttribute("data-sx-type-phase", f.phase);
+                if (f.done)
+                    return el.removeAttribute("data-sx-type-phase");
+            }
+            frame = requestAnimationFrame(tick);
+        };
+        const run = () => {
+            if (frame || !visible || !started || loopsPaused())
+                return;
+            last = performance.now();
+            frame = requestAnimationFrame(tick);
+        };
+        write("");
+        const stopScreen = watchOnScreen(el, (on) => {
+            mark(on);
+            visible = on;
+            started || (started = on);
+            run();
+        });
+        // the page-wide pause (usePauseLoops): picks up where it stopped
+        const stopPause = onLoopsPaused(run);
+        return () => {
+            stopScreen();
+            stopPause();
+            cancelAnimationFrame(frame);
+            node.nodeValue = first;
+            el.removeAttribute("data-sx-type-phase");
+        };
+        // the lines and timing are in `key`
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [key, mode]);
+    const n = graphemes(first).length;
+    const vars = mode === "css"
+        ? {
+            "--sx-type-n": Math.max(1, n),
+            "--sx-type-time": seconds(Math.max(1, n) / speed),
+            "--sx-type-delay": seconds(delay),
+            "--sx-type-repeat": erase ? "infinite" : "1",
+            "--sx-type-direction": erase ? "alternate" : "normal",
+            ...style,
+        }
+        : style;
+    const shownLines = mode === "css" ? [first] : lines;
+    return (_jsxs(_Fragment, { children: [_jsx("style", { href: styleHref("type-base", TYPE_BASE_CSS), precedence: "sx", children: TYPE_BASE_CSS }), _jsx("style", { href: styleHref("type-motion", motionOnly(TYPE_MOTION_CSS)), precedence: "sx", children: motionOnly(TYPE_MOTION_CSS) }), _jsxs(Tag, { ref: ref, "data-sx-type": "", "data-sx-type-mode": mode, "data-sx-type-preset": preset, className: className, style: vars, children: [_jsx("span", { "data-sx-text-read": "", children: shownLines.join(", ") }), _jsxs("span", { "data-sx-type-box": "", "aria-hidden": true, children: [shownLines.map((line, i) => (_jsxs("span", { "data-sx-type-size": "", children: [preset === "terminal" ? "$ " : null, line, caret ? _jsx("span", { "data-sx-type-caret": "" }) : null] }, i))), _jsxs("span", { "data-sx-type-live": "", children: [preset === "terminal" ? _jsx("span", { "data-sx-type-prompt": "", children: "$ " }) : null, _jsxs("span", { "data-sx-type-run": "", children: [_jsx("span", { "data-sx-type-text": "", children: first }), caret ? _jsx("span", { "data-sx-type-caret": "" }) : null] })] })] })] })] }));
+}

package/dist/text/type/Typewriter.schema.d.ts

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

package/dist/text/type/Typewriter.schema.js

@@ -0,0 +1,33 @@
+import { defineSchema } from "../../schema/define.js";
+// Typewriter's props as a form. The lines are the page's content, written by the page.
+export const TYPEWRITER_SCHEMA = defineSchema()({
+    id: "typewriter",
+    family: "typewriter",
+    factory: "Typewriter",
+    code: ["lines", "as", "className", "style"],
+    fields: {
+        mode: {
+            kind: "choice", label: "Runs on", values: ["js", "css"],
+            labels: { js: "Script: any font, every line", css: "CSS only: first line, monospace font" },
+            default: "js",
+            help: "The CSS mode needs no script but types only the first line, and only in a monospace font.",
+        },
+        erase: { kind: "boolean", label: "Erase before the next line", default: false },
+        loop: {
+            kind: "boolean", label: "Start again after the last line",
+            autoNote: "on with several lines, off with one", autoValue: true,
+        },
+        speed: { kind: "number", label: "Typing speed", min: 4, max: 40, step: 1, unit: "letters/s", default: 14 },
+        pause: { kind: "number", label: "A full line stays", min: 0.3, max: 5, step: 0.1, unit: "s", default: 1.6 },
+        delay: { kind: "number", label: "Wait before typing", min: 0, max: 5, step: 0.1, unit: "s", default: 0 },
+        caret: { kind: "boolean", label: "Show the caret", default: true },
+        preset: {
+            kind: "choice", label: "Style", values: ["terminal"], labels: { terminal: "Terminal: monospace, $ prompt, block caret" },
+            autoNote: "plain: the page's font and a thin caret",
+        },
+        start: {
+            kind: "choice", label: "Starts", values: ["inView", "mount"],
+            labels: { inView: "When it comes on screen", mount: "As soon as the page loads" }, default: "inView",
+        },
+    },
+});

package/dist/text/type/css.d.ts

@@ -0,0 +1,9 @@
+/** Every line in one grid cell (the box is the longest line's size, so nothing jumps); the typing on top. */
+export declare const TYPE_BASE_CSS = "@layer theme, base, components, utilities;\n@layer components {\n  :where([data-sx-type]) { --sx-type-dir: 1; position: relative; }\n  :where([data-sx-type]:dir(rtl)) { --sx-type-dir: -1; }\n  :where([data-sx-type] [data-sx-text-read]) {\n    position: absolute;\n    inline-size: 1px;\n    block-size: 1px;\n    overflow: hidden;\n    clip-path: inset(50%);\n    white-space: nowrap;\n  }\n  :where([data-sx-type] [data-sx-type-box]) { display: inline-grid; vertical-align: top; }\n  :where([data-sx-type] [data-sx-type-box] > *) { grid-area: 1 / 1; }\n  :where([data-sx-type] [data-sx-type-size]) { visibility: hidden; }\n  :where([data-sx-type] [data-sx-type-caret]) {\n    display: inline-block;\n    inline-size: 0.08em;\n    block-size: 1.05em;\n    margin-inline-start: 0.06em;\n    vertical-align: -0.12em;\n    background: currentColor;\n  }\n  :where([data-sx-type][data-sx-type-preset=\"terminal\"]) { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; }\n  :where([data-sx-type][data-sx-type-preset=\"terminal\"] [data-sx-type-caret]) { inline-size: 0.6em; }\n  :where([data-sx-type] [data-sx-type-prompt]) { opacity: 0.6; }\n  :where([data-sx-type][data-sx-type-mode=\"css\"]) { white-space: nowrap; }\n  :where([data-sx-type][data-sx-type-mode=\"css\"] [data-sx-type-run]) { display: inline-block; position: relative; }\n  :where([data-sx-type][data-sx-type-mode=\"css\"] [data-sx-type-caret]) { position: absolute; inset-inline-start: 0; inset-block-start: 0.05em; }\n}";
+/**
+ * Motion. The caret blinks while it waits (solid while typing) and only on screen. The JS mode's typed line waits hidden
+ * until the script runs (so the full line doesn't flash before it is typed). The CSS mode clips the line from the
+ * reading start one letter at a time and moves the caret one `ch` per letter: both run on the compositor, the box never
+ * resizes, and it is why the mode needs a monospace font.
+ */
+export declare const TYPE_MOTION_CSS: string;

package/dist/text/type/css.js

@@ -0,0 +1,66 @@
+// Typewriter's stylesheets: the structure (always) and the motion (only when motion is welcome). Plain strings.
+import { LAYER_ORDER } from "../../backgrounds/runtime/rootCss.js";
+import { fromStart } from "../effects/ink/kit.js";
+import { holdUntilLive } from "../runtime/onScreen.js";
+const HOST = "[data-sx-type]";
+/** Every line in one grid cell (the box is the longest line's size, so nothing jumps); the typing on top. */
+export const TYPE_BASE_CSS = `${LAYER_ORDER}
+@layer components {
+  :where(${HOST}) { --sx-type-dir: 1; position: relative; }
+  :where(${HOST}:dir(rtl)) { --sx-type-dir: -1; }
+  :where(${HOST} [data-sx-text-read]) {
+    position: absolute;
+    inline-size: 1px;
+    block-size: 1px;
+    overflow: hidden;
+    clip-path: inset(50%);
+    white-space: nowrap;
+  }
+  :where(${HOST} [data-sx-type-box]) { display: inline-grid; vertical-align: top; }
+  :where(${HOST} [data-sx-type-box] > *) { grid-area: 1 / 1; }
+  :where(${HOST} [data-sx-type-size]) { visibility: hidden; }
+  :where(${HOST} [data-sx-type-caret]) {
+    display: inline-block;
+    inline-size: 0.08em;
+    block-size: 1.05em;
+    margin-inline-start: 0.06em;
+    vertical-align: -0.12em;
+    background: currentColor;
+  }
+  :where(${HOST}[data-sx-type-preset="terminal"]) { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; }
+  :where(${HOST}[data-sx-type-preset="terminal"] [data-sx-type-caret]) { inline-size: 0.6em; }
+  :where(${HOST} [data-sx-type-prompt]) { opacity: 0.6; }
+  :where(${HOST}[data-sx-type-mode="css"]) { white-space: nowrap; }
+  :where(${HOST}[data-sx-type-mode="css"] [data-sx-type-run]) { display: inline-block; position: relative; }
+  :where(${HOST}[data-sx-type-mode="css"] [data-sx-type-caret]) { position: absolute; inset-inline-start: 0; inset-block-start: 0.05em; }
+}`;
+/**
+ * Motion. The caret blinks while it waits (solid while typing) and only on screen. The JS mode's typed line waits hidden
+ * until the script runs (so the full line doesn't flash before it is typed). The CSS mode clips the line from the
+ * reading start one letter at a time and moves the caret one `ch` per letter: both run on the compositor, the box never
+ * resizes, and it is why the mode needs a monospace font.
+ */
+export const TYPE_MOTION_CSS = `@layer components {
+  @keyframes sx-type-blink { 0%, 49% { opacity: 1; } 50%, 100% { opacity: 0; } }
+  :where(${HOST} [data-sx-type-caret]) { animation: sx-type-blink 1s step-end infinite; }
+  :where(${HOST}[data-sx-type-phase="type"] [data-sx-type-caret], ${HOST}[data-sx-type-phase="erase"] [data-sx-type-caret]) { animation: none; }
+  :where(${HOST}[data-sx-live]:not([data-sx-on]) [data-sx-type-caret]) { animation-play-state: paused; }
+${holdUntilLive(`${HOST}[data-sx-type-mode="js"]`, "[data-sx-type-live]", "sx-type-wait")}
+  @keyframes sx-type-css {
+    from { clip-path: ${fromStart("0")}; }
+    to { clip-path: ${fromStart("1")}; }
+  }
+  @keyframes sx-type-css-caret {
+    from { translate: 0 0; }
+    to { translate: calc(var(--sx-type-n) * 1ch * var(--sx-type-dir)) 0; }
+  }
+  :where(${HOST}[data-sx-type-mode="css"] [data-sx-type-text]) {
+    display: inline-block;
+    animation: sx-type-css var(--sx-type-time) steps(var(--sx-type-n), end) var(--sx-type-delay) both var(--sx-type-repeat) var(--sx-type-direction);
+  }
+  :where(${HOST}[data-sx-type-mode="css"] [data-sx-type-caret]) {
+    animation: sx-type-css-caret var(--sx-type-time) steps(var(--sx-type-n), end) var(--sx-type-delay) both var(--sx-type-repeat) var(--sx-type-direction),
+      sx-type-blink 1s step-end infinite;
+  }
+  :where([data-sx-loops-paused] ${HOST} [data-sx-type-text], [data-sx-loops-paused] ${HOST} [data-sx-type-caret]) { animation-play-state: paused; }
+}`;

package/dist/text/type/timeline.d.ts

@@ -0,0 +1,24 @@
+export interface TypeTiming {
+    /** Letters typed per second. */
+    readonly speed: number;
+    /** Letters deleted per second, with `erase`. */
+    readonly eraseSpeed: number;
+    /** Seconds a full line stays before the next one. */
+    readonly pause: number;
+    /** Seconds of nothing between one line and the next. */
+    readonly gap: number;
+    /** Delete each line letter by letter before the next; without it the next line replaces it at once. */
+    readonly erase: boolean;
+    /** Start again after the last line; without it the last line stays. */
+    readonly loop: boolean;
+}
+export interface TypeFrame {
+    readonly line: number;
+    /** Letters of that line that show. */
+    readonly shown: number;
+    readonly phase: "type" | "hold" | "erase" | "gap";
+    /** Nothing will change any more. */
+    readonly done: boolean;
+}
+/** The typewriter `t` seconds after it started, for lines of these lengths (in letters). */
+export declare function typeFrame(lengths: readonly number[], t: number, o: TypeTiming): TypeFrame;

package/dist/text/type/timeline.js

@@ -0,0 +1,41 @@
+// Where a typewriter is at a moment: which line, how many of its letters show. Pure; tested.
+/** The typewriter `t` seconds after it started, for lines of these lengths (in letters). */
+export function typeFrame(lengths, t, o) {
+    const count = lengths.length;
+    if (count === 0)
+        return { line: 0, shown: 0, phase: "hold", done: true };
+    const segs = lengths.map((n) => ({
+        n,
+        type: n / o.speed,
+        hold: o.pause,
+        erase: o.erase ? n / o.eraseSpeed : 0,
+        gap: o.gap,
+    }));
+    const span = (i) => {
+        const s = segs[i];
+        return s.type + s.hold + s.erase + s.gap;
+    };
+    const cycle = segs.reduce((sum, _, i) => sum + span(i), 0);
+    // without a loop the last line types, then stays
+    const last = count - 1;
+    const end = cycle - span(last) + segs[last].type;
+    if (!o.loop && t >= end)
+        return { line: last, shown: lengths[last], phase: "hold", done: true };
+    let at = o.loop && cycle > 0 ? t % cycle : t;
+    for (let i = 0; i < count; i++) {
+        const s = segs[i];
+        if (at < s.type)
+            return { line: i, shown: Math.min(s.n, Math.floor(at * o.speed) + 1), phase: "type", done: false };
+        at -= s.type;
+        if (at < s.hold)
+            return { line: i, shown: s.n, phase: "hold", done: false };
+        at -= s.hold;
+        if (at < s.erase)
+            return { line: i, shown: Math.max(0, s.n - Math.floor(at * o.eraseSpeed) - 1), phase: "erase", done: false };
+        at -= s.erase;
+        if (at < s.gap)
+            return { line: i, shown: 0, phase: "gap", done: false };
+        at -= s.gap;
+    }
+    return { line: last, shown: lengths[last], phase: "hold", done: !o.loop };
+}

package/dist/text/types.d.ts

@@ -0,0 +1,142 @@
+import type { SvgElement } from "../backgrounds/types.js";
+/** The atlas's groups. */
+export declare const TEXT_GROUPS: readonly ["split", "type", "scramble", "scroll", "fill", "stroke", "hover", "glitch", "depth", "num"];
+export type TextGroup = (typeof TEXT_GROUPS)[number];
+/**
+ * When an effect fires: entering the screen, following the scroll, under the pointer, on a tap or click (it works on a
+ * touch screen too), all the time, or on a new value.
+ */
+export type TextFires = "enter" | "scroll" | "hover" | "tap" | "loop" | "value";
+/** What it is built with. */
+export type TextTech = "css" | "svg" | "js" | "canvas" | "webgl";
+/** The lowest device tier that runs it (same scale as backgrounds, transitions and buttons). */
+export type TextTier = "all" | "mid" | "high";
+/** What the text is cut into. Each level holds the next: lines hold words, words hold letters. */
+export type TextSplit = "lines" | "words" | "chars";
+/**
+ * The channels of a text. Two effects can't write the same one.
+ * - `enter`: the arrival. `translate`, `rotate`, `scale`, `opacity`, `filter` on the pieces the entrance moves.
+ * - `move`: `transform` on the letters (hover and loop effects). It composes with the entrance's individual properties.
+ * - `paint`: the letters' fill (the paint spans' background and colour), or a drawing that stands in for the text.
+ * - `stroke`: their outline.
+ * - `shadow`: shadows and glows behind them.
+ * - `font`: the letters' weight and width (`font-weight`, `font-stretch`), which the pointer effects change.
+ */
+export type TextClaim = "enter" | "move" | "paint" | "stroke" | "shadow" | "font";
+/** The order pieces play in: from the reading start, the end, the middle out, the edges in, or shuffled. */
+export type TextOrder = "start" | "end" | "centre" | "edges" | "random";
+/** CSS custom properties, written inline on the text element. Names start with `--sx-text-<id>-`. */
+export type TextVars = Readonly<Record<`--${string}`, string | number>>;
+/**
+ * A generated span over or behind the text. Hidden from screen readers. What it holds:
+ * - `copy`: the text again (a glow behind it, a filled copy revealed over it);
+ * - `window`: a window that slides across a copy of the text, the copy sliding back so it stays put (a shine band);
+ * - `svgText`: the text drawn as SVG on one line (`"draw"`: an outline to stroke in; `"cutout"`: a cover with the text cut
+ *   out, over what sits below it);
+ * - `svg`: SVG elements (a hand-drawn circle, handwriting);
+ * - `nodes`: empty spans with their own inline vars (sparkles);
+ * - `video`: a muted looping video, played only while the text is on screen.
+ */
+export interface TextLayer {
+    /** Tells an effect's layers apart in its CSS (`data-sx-text-part`). */
+    readonly part?: string;
+    /** `"over"` (default) sits above the text, `"under"` behind it. */
+    readonly slot?: "over" | "under";
+    readonly copy?: boolean;
+    readonly window?: boolean;
+    readonly svgText?: "draw" | "cutout";
+    readonly svg?: {
+        readonly viewBox?: string;
+        readonly preserveAspectRatio?: string;
+        /**
+         * Drawn in a 100 x 100 box and stretched to the text until `Text` sizes it in px: each path keeps its unscaled `d`
+         * in `data-sx-text-fit` (absolute x, y pairs only), and the host gets `data-sx-text-fitted` once it is sized.
+         */
+        readonly fit?: boolean;
+        readonly children: readonly SvgElement[];
+    };
+    readonly nodes?: readonly TextVars[];
+    readonly video?: {
+        readonly src: string;
+        readonly poster?: string;
+    };
+}
+/** Plain flags `Text` reads. */
+export interface TextNeeds {
+    /** What the effect moves. `Text` cuts the text to the finest level any effect asks for. */
+    readonly split?: TextSplit;
+    /** The order the pieces of `split` play in: each gets `--sx-o`, its place in that order (0 first). */
+    readonly order?: TextOrder;
+    /** The seed of a `random` order and of `scatter`: the same seed gives the same result on the server and the client. */
+    readonly seed?: number;
+    /** `--sx-ra`, `--sx-rb`, `--sx-rc` on each piece of `split`: seeded numbers in [-1, 1] (where a letter flies in from). */
+    readonly scatter?: boolean;
+    /** A `data-sx-text-cover` span inside each piece of `split` (a bar over a word). */
+    readonly cover?: boolean;
+    /** At most this many letters: past it, a letter split drops to words (atlas rule 2). */
+    readonly maxPieces?: number;
+    /** It plays when the text enters the screen: `Text` marks it `data-sx-in` then. */
+    readonly inView?: boolean;
+    /**
+     * It paints the letters: `Text` wraps the text (or each piece) in a `data-sx-text-paint` span and writes where each
+     * sits in the whole (`--sx-tx`, `--sx-ty`) and the whole's size (`--sx-tw`, `--sx-th`), so one fill runs across pieces
+     * that move on their own.
+     */
+    readonly paint?: boolean;
+    /** It runs without end: `Text` marks it `data-sx-text-on` while it is on screen, and the effect pauses otherwise. */
+    readonly loop?: boolean;
+    /**
+     * Its program takes over the text as soon as it runs: `Text` renders `data-sx-text-wait` on the server, the program
+     * removes it, and the effect's CSS keeps the text hidden while it is there (with a fail-safe).
+     */
+    readonly wait?: boolean;
+    /**
+     * It follows the scroll: `Text` marks it `data-sx-text-scroll` (the base sheet gives it a view timeline,
+     * `--sx-text-view`) and starts the JS fallback where a native timeline can't run (`--sx-p`, `--sx-pc`).
+     */
+    readonly scroll?: boolean;
+    /** A `data-sx-text-inner` span around the whole text inside the show (what a pinned word scales or slides). */
+    readonly inner?: boolean;
+    /** It reads the pointer (`--sx-text-x`, `--sx-text-y` in px, `--sx-text-px`, `--sx-text-py` 0 to 1). Mouse only. */
+    readonly pointer?: boolean;
+}
+/**
+ * Code an effect brings with it (a canvas). Only an effect that can't be CSS has one; it makes a page need `"use client"`,
+ * and a page without it downloads none of it.
+ */
+export interface TextProgram {
+    /** Starts it on the text element. `text` is its plain text, if it has one. Returns what stops it. */
+    readonly attach: (el: HTMLElement, text: string | undefined) => () => void;
+    /** Stable string of the options: `Text` restarts it only when this or the text changes. */
+    readonly signature: string;
+}
+export interface TextMeta {
+    /** The factory's name in the barrel (`enterRise`, `inkShiny` …). */
+    readonly id: string;
+    readonly label: string;
+    readonly group: TextGroup;
+    readonly fires: readonly TextFires[];
+    readonly tech: TextTech;
+    readonly tier: TextTier;
+    /** It shows on a touch screen: it needs no mouse. */
+    readonly touch: boolean;
+    /** One line for the docs table. */
+    readonly description: string;
+}
+/** One effect on a text: plain data (unless it has a `program`), so a Server Component can pass it to `Text`. */
+export interface TextEffect {
+    /** The `data-sx-text` value its stylesheet is keyed on: its registry id. */
+    readonly id: string;
+    readonly tier: TextTier;
+    /** Its motion: shipped only when motion is welcome. */
+    readonly css: string;
+    /** Its look (a fill, an outline): shipped always, with or without motion or scripts. */
+    readonly lookCss?: string;
+    readonly vars: TextVars;
+    readonly layers: readonly TextLayer[];
+    readonly claims: readonly TextClaim[];
+    readonly needs: TextNeeds;
+    readonly program?: TextProgram;
+    /** What a weaker device wears instead (every `mid` / `high` effect has one). Its id ends in `-lite`. */
+    readonly fallback?: TextEffect;
+}

package/dist/text/types.js

@@ -0,0 +1,5 @@
+// ---------------------------------------------------------------------------
+// Text effect descriptors and their metadata. See ./CLAUDE.md.
+// ---------------------------------------------------------------------------
+/** The atlas's groups. */
+export const TEXT_GROUPS = ["split", "type", "scramble", "scroll", "fill", "stroke", "hover", "glitch", "depth", "num"];

package/dist/three.d.ts

@@ -0,0 +1,16 @@
+export { liquidGlass } from "./backgrounds/effects/three/liquidGlass.js";
+export type { LiquidGlassOptions } from "./backgrounds/effects/three/liquidGlass.js";
+export { glassShapes } from "./backgrounds/effects/three/glassShapes.js";
+export type { GlassShapesOptions } from "./backgrounds/effects/three/glassShapes.js";
+export { chrome } from "./backgrounds/effects/three/chrome.js";
+export type { ChromeOptions } from "./backgrounds/effects/three/chrome.js";
+export { spectralGhost } from "./backgrounds/effects/three/spectralGhost.js";
+export type { SpectralGhostOptions } from "./backgrounds/effects/three/spectralGhost.js";
+export { wovenLight } from "./backgrounds/effects/three/wovenLight.js";
+export type { WovenLightOptions } from "./backgrounds/effects/three/wovenLight.js";
+export { neonTubes } from "./backgrounds/effects/three/neonTubes.js";
+export type { NeonTubesOptions } from "./backgrounds/effects/three/neonTubes.js";
+export { Text3D } from "./text/three/Text3D.js";
+export type { Text3DProps } from "./text/three/Text3D.js";
+export { threeProgram, disposeTree, colour, roomEnvironment, backdropTexture, aimPoint } from "./backgrounds/effects/three/kit.js";
+export type { ThreeScene, ThreeContext } from "./backgrounds/effects/three/kit.js";

package/dist/three.js

@@ -0,0 +1,17 @@
+// ---------------------------------------------------------------------------
+// @sharedex/ui/three: the background effects built on Three.js. A separate
+// entry so nobody installs or downloads Three.js unless they import from
+// here; `three` is an optional peer dependency. Each factory returns an
+// ordinary WebGL effect: use it in <Background.Root> / <Background.Layer>
+// from the main entry like any other.
+// ---------------------------------------------------------------------------
+export { liquidGlass } from "./backgrounds/effects/three/liquidGlass.js";
+export { glassShapes } from "./backgrounds/effects/three/glassShapes.js";
+export { chrome } from "./backgrounds/effects/three/chrome.js";
+export { spectralGhost } from "./backgrounds/effects/three/spectralGhost.js";
+export { wovenLight } from "./backgrounds/effects/three/wovenLight.js";
+export { neonTubes } from "./backgrounds/effects/three/neonTubes.js";
+// 3D text: real extruded letters, the HTML text (with a CSS extruded shadow) wherever they can't run
+export { Text3D } from "./text/three/Text3D.js";
+// for writing your own Three.js effects on the same runtime
+export { threeProgram, disposeTree, colour, roomEnvironment, backdropTexture, aimPoint } from "./backgrounds/effects/three/kit.js";

package/dist/ticker/Ticker.d.ts

@@ -0,0 +1,62 @@
+import { type MotionValue } from "motion/react";
+export interface TickerProps<T> {
+    readonly items: readonly T[];
+    /** Renders one item. Items may be any size; the Ticker measures the whole set. */
+    readonly children: (item: T, index: number) => React.ReactNode;
+    /**
+     * px per second. Positive moves the items towards the reading start (left in
+     * LTR, right in RTL, up when vertical), negative towards the end. `0`: only
+     * `offset` and drag move it. Default `60`.
+     */
+    readonly velocity?: number;
+    /** Default `"x"`. A vertical ticker needs a height from `className` / `style`. */
+    readonly axis?: "x" | "y";
+    /** px between items, also between the last item and the next copy's first. Default `24`. */
+    readonly gap?: number;
+    /**
+     * An outside driver, px towards the start, added to the time-driven travel.
+     * Page scroll for bands that move with the page: `offset={scrollY}`, and
+     * `useTransform(scrollY, (v) => -v)` for one that runs the other way.
+     */
+    readonly offset?: MotionValue<number>;
+    /** Drag to move it, with a glide on release. Default `false`. */
+    readonly drag?: boolean;
+    /**
+     * Speed factor while the pointer is over it or focus is inside it: `0`
+     * pauses, `0.3` slows it down. The change eases in. Default `1` (no change).
+     */
+    readonly hoverSpeed?: number;
+    /**
+     * Scrolling the page speeds it up: its speed grows by this much per screen height a second of scrolling, and
+     * scrolling up slows it or runs it the other way (Magic UI's Scroll Based Velocity). Default `0` (off).
+     */
+    readonly scrollBoost?: number;
+    /** Fade both edges over this many px (or a CSS length such as `"10%"`). `true`: 48 px. */
+    readonly fade?: boolean | number | string;
+    readonly className?: string;
+    readonly style?: React.CSSProperties;
+    /** Label for the region, read by screen readers. */
+    readonly "aria-label"?: string;
+}
+/**
+ * A continuous marquee. The item set is rendered as many times as it takes to
+ * cover the viewport plus one set (`tickerCopies`), and one number, the
+ * offset, moves the whole track. The track's translation is the offset modulo
+ * the set's length (`tickerShift`), so it runs forever with no reset you can
+ * see: when copy 1 has moved to where copy 0 was, the picture is identical.
+ *
+ * The offset is the sum of the Ticker's own travel (time at `velocity`, plus
+ * drag and its glide) and the optional outside `offset`. One write per frame:
+ * the track's `transform`, set directly, never through React.
+ *
+ * - **Measuring:** one `ResizeObserver` watches the viewport and the first
+ *   set (which carries the trailing gap as padding, so its length is exactly
+ *   one period).
+ * - **Cost:** the time loop runs only while the Ticker is on screen, has a
+ *   speed, and reduced motion is off.
+ * - **Reduced motion:** still. Time and the outside offset stop; drag, which
+ *   the user does themselves, still works.
+ * - **Copies** after the first are `aria-hidden` and `inert`, so screen readers
+ *   read the items once and links are tabbed to once.
+ */
+export declare function Ticker<T>({ items, children, velocity, axis, gap, offset, drag, hoverSpeed, scrollBoost, fade, className, style, "aria-label": ariaLabel, }: TickerProps<T>): import("react").JSX.Element;