@sharedex/ui 0.0.0-stage → 0.9.0

package/dist/text/cycle/css.js

@@ -0,0 +1,158 @@
+// WordCycle's stylesheets: the structure (always, it also shows one word under reduced motion) and one motion sheet per
+// look, so a page ships only the looks it uses. Plain strings.
+import { LAYER_ORDER } from "../../backgrounds/runtime/rootCss.js";
+import { fromStart } from "../effects/ink/kit.js";
+export const CYCLE_LOOKS = ["slide", "flip", "blur", "box", "layout", "flap", "morph", "anagram", "shuffle", "strike", "focus"];
+const H = "[data-sx-cycle]";
+const at = (look, raw) => `:where(${H}[data-sx-cycle="${look}"] ${raw})`;
+const WORD = "[data-sx-cycle-word]";
+const ON = '[data-sx-cycle-state="on"]';
+const OFF = '[data-sx-cycle-state="off"]';
+const WAIT = '[data-sx-cycle-state="wait"]';
+const EASE = "var(--ease-sx-out, cubic-bezier(0.2, 0.7, 0.2, 1))";
+const T = "var(--sx-cycle-time)";
+/** Words that take turns share one grid cell: the stack is as wide as the longest, so nothing around it moves. */
+export const CYCLE_BASE_CSS = `${LAYER_ORDER}
+@layer components {
+  :where(${H}) { --sx-cycle-dir: 1; position: relative; }
+  :where(${H}:dir(rtl)) { --sx-cycle-dir: -1; }
+  :where(${H} [data-sx-text-read]) {
+    position: absolute;
+    inline-size: 1px;
+    block-size: 1px;
+    overflow: hidden;
+    clip-path: inset(50%);
+    white-space: nowrap;
+  }
+  :where(${H} [data-sx-cycle-stack]) { position: relative; display: inline-grid; vertical-align: bottom; white-space: nowrap; }
+  :where(${H} [data-sx-cycle-stack] > *) { grid-area: 1 / 1; justify-self: var(--sx-cycle-align, start); }
+  :where(${H} ${WORD}:not(${ON}), ${H} [data-sx-cycle-size]) { visibility: hidden; }
+  :where(${H} :is([data-sx-cycle-tile], [data-sx-cycle-letter])) { display: inline-block; white-space: pre; }
+  :where(${H} [data-sx-cycle-tiles]) { display: inline-flex; }
+  :where(${H} [data-sx-cycle-tile]) { display: inline-grid; }
+  :where(${H} [data-sx-cycle-tile] > *) { grid-area: 1 / 1; }
+  :where(${H} [data-sx-cycle-tile] > :not(${ON})) { visibility: hidden; }
+  :where(${H} :is([data-sx-cycle-line], [data-sx-cycle-box], [data-sx-cycle-frame], [data-sx-cycle-defs])) { display: none; }
+  :where(${H} [data-sx-cycle-reel]) { position: relative; display: inline-block; overflow: clip; vertical-align: bottom; }
+  :where(${H} [data-sx-cycle-reel] > [data-sx-cycle-letter-size]) { visibility: hidden; }
+  :where(${H} [data-sx-cycle-strip]) {
+    position: absolute;
+    inset-block-start: 0;
+    inset-inline: 0;
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    translate: 0 calc(var(--sx-cycle-k) * -1lh);
+  }
+  :where(${H}[data-sx-cycle="focus"] [data-sx-cycle-stack]) { display: inline; white-space: normal; }
+  :where(${H}[data-sx-cycle="focus"] ${WORD}) { visibility: visible; }
+  :where(${H}[data-sx-cycle="layout"] [data-sx-cycle-stack]) { overflow: clip; inline-size: var(--sx-cycle-w-px, auto); }
+}`;
+/**
+ * The leaving and waiting words become visible again for the motion, which fades them; the waiting ones jump. Scoped to
+ * the look: every look's sheet sits on the page together, and an unscoped rule hid the focus look's words.
+ */
+const shared = (look) => `  ${at(look, `${WORD}:is(${OFF}, ${WAIT})`)} { visibility: visible; opacity: 0; }
+  ${at(look, `${WORD}${WAIT}`)} { transition: none !important; }`;
+const word = (look, on, off, wait, extra = "") => `${shared(look)}
+  ${at(look, WORD)} { transition: translate ${T} ${EASE}, rotate ${T} ${EASE}, scale ${T} ${EASE}, opacity ${T} ${EASE}, filter ${T} ${EASE}; ${on} }
+  ${at(look, `${WORD}${OFF}`)} { ${off} }
+  ${at(look, `${WORD}${WAIT}`)} { ${wait} }${extra}`;
+/** The stack clips the words that slide out, with room for tall marks and descenders. */
+const CLIP = (look) => `
+  ${at(look, "[data-sx-cycle-stack]")} { overflow: clip; padding-block: 0.15em; margin-block: -0.15em; }`;
+export const CYCLE_LOOK_CSS = {
+    slide: word("slide", "translate: 0 0;", "translate: 0 -105%;", "translate: 0 105%;", CLIP("slide")),
+    flip: word("flip", "rotate: x 0deg;", "rotate: x -90deg;", "rotate: x 90deg;", `
+  ${at("flip", "[data-sx-cycle-stack]")} { perspective: 8em; }
+  ${at("flip", WORD)} { transform-origin: 50% 50% -0.5em; backface-visibility: hidden; }`),
+    blur: word("blur", "filter: blur(0); scale: 1;", "filter: blur(0.25em); scale: 1.05;", "filter: blur(0.25em); scale: 0.95;"),
+    // the box behind the word scales to the word's share of the widest (measured), so the layout never resizes
+    box: word("box", "translate: 0 0;", "translate: 0 -60%;", "translate: 0 60%;", `${CLIP("box")}
+  ${at("box", "[data-sx-cycle-stack]")} { padding-inline: 0.3em; margin-inline: -0.3em; }
+  ${at("box", "[data-sx-cycle-box]")} {
+    display: block;
+    position: absolute;
+    inset: 0;
+    border-radius: 0.2em;
+    background: var(--sx-cycle-color);
+    transform-origin: ${fromStartOrigin()};
+    scale: var(--sx-cycle-w, 1) 1;
+    transition: scale ${T} ${EASE};
+    z-index: -1;
+  }`),
+    // the one look that reflows the sentence: the stack's width follows the word (allowed in the test)
+    layout: word("layout", "translate: 0 0;", "translate: 0 -60%;", "translate: 0 60%;", `
+  ${at("layout", "[data-sx-cycle-stack]")} { transition: inline-size ${T} ${EASE}; padding-block: 0.15em; margin-block: -0.15em; }`),
+    // each letter on its own tile flips over, a step after the one before, like an airport board
+    flap: `  ${at("flap", "[data-sx-cycle-tile]")} {
+    perspective: 4em;
+    padding-inline: 0.06em;
+    margin-inline: 0.02em;
+    border-radius: 0.08em;
+    background: color-mix(in oklab, currentColor 12%, transparent);
+  }
+  ${at("flap", "[data-sx-cycle-tile] > *")} {
+    transition: rotate ${T} ${EASE} calc(var(--sx-i, 0) * 0.04s), opacity ${T} step-end calc(var(--sx-i, 0) * 0.04s);
+    backface-visibility: hidden;
+  }
+  ${at("flap", `[data-sx-cycle-tile] > ${ON}`)} { transition: rotate ${T} ${EASE} calc(var(--sx-i, 0) * 0.04s), opacity ${T} step-start calc(var(--sx-i, 0) * 0.04s); }
+  ${at("flap", `[data-sx-cycle-tile] > :is(${OFF}, ${WAIT})`)} { visibility: visible; opacity: 0; }
+  ${at("flap", `[data-sx-cycle-tile] > ${OFF}`)} { rotate: x -90deg; }
+  ${at("flap", `[data-sx-cycle-tile] > ${WAIT}`)} { rotate: x 90deg; transition: none; }`,
+    // words melt into each other: blurred, under a threshold filter that snaps the blur back into hard shapes
+    // a blur much past 0.15em thins small text below the threshold, and it vanishes mid-melt (found at 18px in WebKit)
+    morph: word("morph", "filter: blur(0);", "filter: blur(0.15em);", "filter: blur(0.15em);", `
+  ${at("morph", "[data-sx-cycle-stack]")} { filter: var(--sx-cycle-filter); }
+  ${at("morph", "[data-sx-cycle-defs]")} { display: block; position: absolute; inline-size: 0; block-size: 0; overflow: hidden; }`),
+    // letters move to their places in the next word (positions measured: FLIP), the rest fade
+    anagram: `  ${at("anagram", "[data-sx-cycle-letter]")} { transition: translate ${T} ${EASE}, opacity ${T} ${EASE}; }
+  ${at("anagram", "[data-sx-cycle-letter][data-sx-cycle-new]")} { opacity: 0; }
+  ${at("anagram", "[data-sx-cycle-letter][data-sx-cycle-jump]")} { transition: none; }`,
+    // each letter rolls through random ones and lands, a step after the one before
+    shuffle: word("shuffle", "", "", "", `
+  ${at("shuffle", `${WORD} [data-sx-cycle-strip]`)} { transition: translate calc(${T} * 1.6) cubic-bezier(0.3, 0, 0.2, 1) calc(var(--sx-i, 0) * 0.06s); }
+  ${at("shuffle", `${WORD}${WAIT} [data-sx-cycle-strip]`)} { translate: 0 0; transition: none; }`),
+    // the old word is struck through and fades; the new one writes in from the reading start
+    strike: `${shared("strike")}
+  ${at("strike", WORD)} { position: relative; transition: opacity ${T} ease ${T}, clip-path ${T} ${EASE} ${T}; clip-path: ${fromStart("1")}; }
+  ${at("strike", `${WORD}${WAIT}`)} { clip-path: ${fromStart("0")}; }
+  ${at("strike", `${WORD}${OFF}`)} { transition: opacity ${T} ease ${T}; }
+  ${at("strike", "[data-sx-cycle-line]")} {
+    display: block;
+    position: absolute;
+    inset-inline: -0.04em;
+    inset-block-start: 55%;
+    block-size: 0.07em;
+    background: currentColor;
+    transform-origin: ${fromStartOrigin()};
+    scale: 0 1;
+    transition: scale ${T} ${EASE};
+  }
+  ${at("strike", `${WORD}${OFF} [data-sx-cycle-line]`)} { scale: 1 1; }
+  ${at("strike", `${WORD}${WAIT} [data-sx-cycle-line]`)} { transition: none; }`,
+    // every word shows; the others blur, and four corners jump to frame the sharp one (positions measured from the
+    // reading start, so the corners mirror with the text)
+    focus: `  ${at("focus", WORD)} { transition: filter ${T} ${EASE}, opacity ${T} ${EASE}; }
+  :where(${H}[data-sx-cycle="focus"][data-sx-live] ${WORD}:not(${ON})) { filter: blur(var(--sx-cycle-blur)); opacity: 0.6; }
+  :where(${H}[data-sx-cycle="focus"][data-sx-live][data-sx-cycle-measured] [data-sx-cycle-frame]) { display: block; }
+  ${at("focus", "[data-sx-cycle-frame]")} { position: absolute; inset: 0; pointer-events: none; }
+  ${at("focus", "[data-sx-cycle-frame] > span")} {
+    position: absolute;
+    inset-block-start: 0;
+    inset-inline-start: 0;
+    inline-size: 0.35em;
+    block-size: 0.35em;
+    border: 0.08em solid var(--sx-cycle-color);
+    translate: calc(var(--x) * var(--sx-cycle-dir)) var(--y);
+    transition: translate ${T} ${EASE};
+  }
+  ${at("focus", '[data-sx-cycle-frame] > [data-c="0"]')} { --x: calc(var(--fx) - 0.15em); --y: calc(var(--fy) - 0.1em); border-inline-end: 0; border-block-end: 0; }
+  ${at("focus", '[data-sx-cycle-frame] > [data-c="1"]')} { --x: calc(var(--fx) + var(--fw) - 0.2em); --y: calc(var(--fy) - 0.1em); border-inline-start: 0; border-block-end: 0; }
+  ${at("focus", '[data-sx-cycle-frame] > [data-c="2"]')} { --x: calc(var(--fx) - 0.15em); --y: calc(var(--fy) + var(--fh) - 0.25em); border-inline-end: 0; border-block-start: 0; }
+  ${at("focus", '[data-sx-cycle-frame] > [data-c="3"]')} { --x: calc(var(--fx) + var(--fw) - 0.2em); --y: calc(var(--fy) + var(--fh) - 0.25em); border-inline-start: 0; border-block-start: 0; }`,
+};
+/** The reading start as a transform origin. */
+function fromStartOrigin() {
+    return "calc(50% - 50% * var(--sx-cycle-dir)) 50%";
+}

package/dist/text/effects/decode/decodeBinary.d.ts

@@ -0,0 +1,5 @@
+import type { TextEffect } from "../../types.js";
+import { type DecodeOptions } from "./kit.js";
+export type DecodeBinaryOptions = Omit<DecodeOptions, "characters">;
+/** The text decodes out of 0s and 1s as it enters the screen. It carries code: the page needs `"use client"`. */
+export declare function decodeBinary(options?: DecodeBinaryOptions): TextEffect;

package/dist/text/effects/decode/decodeBinary.js

@@ -0,0 +1,5 @@
+import { defineDecode } from "./kit.js";
+/** The text decodes out of 0s and 1s as it enters the screen. It carries code: the page needs `"use client"`. */
+export function decodeBinary(options = {}) {
+    return defineDecode("decodeBinary", { ...options, characters: "01" }, { duration: 1.4, onEnter: true, onHover: false });
+}

package/dist/text/effects/decode/decodeBinary.schema.d.ts

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

package/dist/text/effects/decode/decodeBinary.schema.js

@@ -0,0 +1,11 @@
+import { defineSchema } from "../../../schema/define.js";
+export const DECODE_BINARY_SCHEMA = defineSchema()({
+    id: "decodeBinary",
+    family: "text",
+    factory: "decodeBinary",
+    fields: {
+        duration: { kind: "number", label: "Duration", min: 0.2, max: 4, step: 0.05, unit: "s", default: 1.4 },
+        fps: { kind: "integer", label: "Changes per second", min: 6, max: 60, default: 24, advanced: true },
+        from: { kind: "choice", label: "Settles first", values: ["start", "end", "centre", "random"], labels: { start: "Reading start", end: "Reading end", centre: "Middle out", random: "Shuffled" }, default: "start" },
+    },
+});

package/dist/text/effects/decode/decodeHover.d.ts

@@ -0,0 +1,8 @@
+import type { TextEffect } from "../../types.js";
+import { type DecodeOptions } from "./kit.js";
+export type DecodeHoverOptions = DecodeOptions;
+/**
+ * On hover or keyboard focus (of the text, or the link or button around it), the letters scramble and settle back.
+ * Mouse and keyboard only: on a touch screen the text stays as it is. It carries code: the page needs `"use client"`.
+ */
+export declare function decodeHover(options?: DecodeHoverOptions): TextEffect;

package/dist/text/effects/decode/decodeHover.js

@@ -0,0 +1,8 @@
+import { defineDecode } from "./kit.js";
+/**
+ * On hover or keyboard focus (of the text, or the link or button around it), the letters scramble and settle back.
+ * Mouse and keyboard only: on a touch screen the text stays as it is. It carries code: the page needs `"use client"`.
+ */
+export function decodeHover(options = {}) {
+    return defineDecode("decodeHover", options, { duration: 0.6, onEnter: false, onHover: true });
+}

package/dist/text/effects/decode/decodeHover.schema.d.ts

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

package/dist/text/effects/decode/decodeHover.schema.js

@@ -0,0 +1,12 @@
+import { defineSchema } from "../../../schema/define.js";
+export const DECODE_HOVER_SCHEMA = defineSchema()({
+    id: "decodeHover",
+    family: "text",
+    factory: "decodeHover",
+    fields: {
+        characters: { kind: "text", label: "Characters", placeholder: "ABC123#%", autoNote: "the text's own letters, so it stays in its script" },
+        duration: { kind: "number", label: "Duration", min: 0.2, max: 4, step: 0.05, unit: "s", default: 0.6 },
+        fps: { kind: "integer", label: "Changes per second", min: 6, max: 60, default: 24, advanced: true },
+        from: { kind: "choice", label: "Settles first", values: ["start", "end", "centre", "random"], labels: { start: "Reading start", end: "Reading end", centre: "Middle out", random: "Shuffled" }, default: "start" },
+    },
+});

package/dist/text/effects/decode/decodeReveal.d.ts

@@ -0,0 +1,11 @@
+import type { TextEffect } from "../../types.js";
+import { type DecodeOptions } from "./kit.js";
+export interface DecodeRevealOptions extends DecodeOptions {
+    /** `"hover"`: play again on hover and keyboard focus (Magic UI's Hyper Text). Default `"none"`. */
+    readonly replay?: "none" | "hover";
+}
+/**
+ * The text shows scrambled until it enters the screen, then decodes into the real words. Without scripts, or under
+ * reduced motion, it is plain text. It carries code: the page needs `"use client"`.
+ */
+export declare function decodeReveal(options?: DecodeRevealOptions): TextEffect;

package/dist/text/effects/decode/decodeReveal.js

@@ -0,0 +1,9 @@
+import { defineDecode } from "./kit.js";
+/**
+ * The text shows scrambled until it enters the screen, then decodes into the real words. Without scripts, or under
+ * reduced motion, it is plain text. It carries code: the page needs `"use client"`.
+ */
+export function decodeReveal(options = {}) {
+    const { replay, ...rest } = options;
+    return defineDecode("decodeReveal", rest, { duration: 1.2, onEnter: true, onHover: replay === "hover" });
+}

package/dist/text/effects/decode/decodeReveal.schema.d.ts

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

package/dist/text/effects/decode/decodeReveal.schema.js

@@ -0,0 +1,13 @@
+import { defineSchema } from "../../../schema/define.js";
+export const DECODE_REVEAL_SCHEMA = defineSchema()({
+    id: "decodeReveal",
+    family: "text",
+    factory: "decodeReveal",
+    fields: {
+        characters: { kind: "text", label: "Characters", placeholder: "ABC123#%", autoNote: "the text's own letters, so it stays in its script" },
+        duration: { kind: "number", label: "Duration", min: 0.2, max: 4, step: 0.05, unit: "s", default: 1.2 },
+        fps: { kind: "integer", label: "Changes per second", min: 6, max: 60, default: 24, advanced: true },
+        from: { kind: "choice", label: "Settles first", values: ["start", "end", "centre", "random"], labels: { start: "Reading start", end: "Reading end", centre: "Middle out", random: "Shuffled" }, default: "start" },
+        replay: { kind: "choice", label: "Replay", values: ["none", "hover"], labels: { none: "Never", hover: "On hover" }, default: "none" },
+    },
+});

package/dist/text/effects/decode/frame.d.ts

@@ -0,0 +1,10 @@
+/** Which letters settle first: from the reading start, the end, the middle out, or in a shuffle. */
+export type DecodeFrom = "start" | "end" | "centre" | "random";
+/** Each letter's turn to settle, 0 (first) to below 1 (last), for `n` letters. */
+export declare function decodeRanks(n: number, from: DecodeFrom, seed?: number): number[];
+/**
+ * `text` at progress `p` (0 to 1): letters whose rank is below `p` show as they are, the rest are drawn from `pool`.
+ * White space always stays, so words keep their shape. `pool` defaults to the text's own letters, so it stays in the
+ * text's script.
+ */
+export declare function decodeFrame(text: string, p: number, random: () => number, ranks: readonly number[], pool?: string): string;

package/dist/text/effects/decode/frame.js

@@ -0,0 +1,40 @@
+// What a decoding text shows at progress `p`: settled letters, the rest random. Pure; tested.
+import { rng } from "../../../backgrounds/runtime/rng.js";
+import { graphemes } from "../../split.js";
+/** Each letter's turn to settle, 0 (first) to below 1 (last), for `n` letters. */
+export function decodeRanks(n, from, seed = 1) {
+    if (n === 0)
+        return [];
+    const mid = (n - 1) / 2;
+    switch (from) {
+        case "end":
+            return Array.from({ length: n }, (_, i) => (n - 1 - i) / n);
+        case "centre":
+            return Array.from({ length: n }, (_, i) => (mid === 0 ? 0 : Math.abs(i - mid) / (mid + 1)));
+        case "random": {
+            const r = rng(seed);
+            const order = Array.from({ length: n }, (_, i) => i);
+            for (let i = n - 1; i > 0; i--) {
+                const j = Math.floor(r() * (i + 1));
+                [order[i], order[j]] = [order[j], order[i]];
+            }
+            const ranks = new Array(n);
+            order.forEach((letter, place) => (ranks[letter] = place / n));
+            return ranks;
+        }
+        default:
+            return Array.from({ length: n }, (_, i) => i / n);
+    }
+}
+/**
+ * `text` at progress `p` (0 to 1): letters whose rank is below `p` show as they are, the rest are drawn from `pool`.
+ * White space always stays, so words keep their shape. `pool` defaults to the text's own letters, so it stays in the
+ * text's script.
+ */
+export function decodeFrame(text, p, random, ranks, pool) {
+    const letters = graphemes(text);
+    const chars = graphemes(pool ?? text).filter((c) => c.trim());
+    if (chars.length === 0)
+        return text;
+    return letters.map((c, i) => (!c.trim() || (ranks[i] ?? 1) < p ? c : chars[Math.floor(random() * chars.length)])).join("");
+}

package/dist/text/effects/decode/kit.d.ts

@@ -0,0 +1,23 @@
+import type { TextEffect } from "../../types.js";
+import type { DecodeFrom } from "./frame.js";
+import { type DecodeSettings } from "./play.js";
+export interface DecodeOptions {
+    /** The characters it shuffles through. Default the text's own, so it stays in the text's script. */
+    readonly characters?: string;
+    /** Seconds until the text has settled. */
+    readonly duration?: number;
+    /** Changes per second. Default `24`. */
+    readonly fps?: number;
+    /** Which letters settle first. Default `"start"`. */
+    readonly from?: DecodeFrom;
+}
+/**
+ * The copy sits over the text, the same size, and shows only while playing. The real text then hides with
+ * `visibility`, so an entrance's opacity animation can't bring it back over the frames. While a script is about to take
+ * over (`data-sx-text-wait`, from the server), the text waits hidden, and shows on its own after the fail-safe.
+ */
+export declare function decodeCss(id: string): string;
+/** A decode effect: its stylesheet, its copy layer and its program. It carries code: the page needs `"use client"`. */
+export declare function defineDecode(id: string, options: DecodeOptions, settings: Omit<DecodeSettings, keyof DecodeOptions | "duration" | "fps" | "from"> & {
+    readonly duration: number;
+}): TextEffect;

package/dist/text/effects/decode/kit.js

@@ -0,0 +1,34 @@
+// What the decode effects share: the copy layer that shows the frames, and how options become a program.
+import { FAIL_SAFE, SHOW, at, defineText, hostOf, layerOf } from "../kit.js";
+import { attachDecode } from "./play.js";
+/**
+ * The copy sits over the text, the same size, and shows only while playing. The real text then hides with
+ * `visibility`, so an entrance's opacity animation can't bring it back over the frames. While a script is about to take
+ * over (`data-sx-text-wait`, from the server), the text waits hidden, and shows on its own after the fail-safe.
+ */
+export function decodeCss(id) {
+    const host = hostOf(id);
+    return `  ${at(`${host} ${layerOf(id)}`)} { overflow: hidden; }
+  ${at(`${host}[data-sx-text-playing] ${layerOf(id)}`)} { display: block; }
+  ${at(`${host}[data-sx-text-playing] ${SHOW}`)} { visibility: hidden; }
+  @keyframes sx-text-${id}-wait { from, to { visibility: hidden; } }
+  @media (scripting: enabled) {
+    ${at(`${host}[data-sx-text-wait] ${SHOW}`)} { animation: sx-text-${id}-wait ${FAIL_SAFE} step-end; }
+  }`;
+}
+/** A decode effect: its stylesheet, its copy layer and its program. It carries code: the page needs `"use client"`. */
+export function defineDecode(id, options, settings) {
+    const s = {
+        ...settings,
+        ...(options.characters !== undefined ? { characters: options.characters } : {}),
+        duration: options.duration ?? settings.duration,
+        fps: options.fps ?? 24,
+        from: options.from ?? "start",
+    };
+    return defineText(id, decodeCss(id), {
+        layers: [{ copy: true }],
+        claims: ["paint"],
+        needs: s.onEnter ? { inView: true, wait: true } : {},
+        program: { attach: (el, text) => attachDecode(el, id, text, s), signature: JSON.stringify(s) },
+    });
+}

package/dist/text/effects/decode/play.d.ts

@@ -0,0 +1,13 @@
+import { type DecodeFrom } from "./frame.js";
+export interface DecodeSettings {
+    readonly characters?: string;
+    readonly duration: number;
+    readonly fps: number;
+    readonly from: DecodeFrom;
+    /** Play when the text enters the screen (and show it scrambled until then). */
+    readonly onEnter: boolean;
+    /** Play again on hover and keyboard focus. */
+    readonly onHover: boolean;
+}
+/** Starts it on the text element. Returns what stops it. */
+export declare function attachDecode(el: HTMLElement, id: string, text: string | undefined, s: DecodeSettings): () => void;

package/dist/text/effects/decode/play.js

@@ -0,0 +1,79 @@
+// Plays a decode on a text: frames are written into the effect's copy layer (its text node, never `textContent`: React
+// still owns that node), while `data-sx-text-playing` hides the real text, which keeps the size and stays readable by
+// screen readers. Only the decode effects import this, so a page without one downloads none of it.
+import { decodeFrame, decodeRanks } from "./frame.js";
+import { graphemes } from "../../split.js";
+/** Starts it on the text element. Returns what stops it. */
+export function attachDecode(el, id, text, s) {
+    const node = el.querySelector(`[data-sx-text-layer="${id}"]`)?.firstChild;
+    if (text === undefined || !node || window.matchMedia("(prefers-reduced-motion: reduce)").matches) {
+        el.removeAttribute("data-sx-text-wait");
+        return () => { };
+    }
+    const ranks = decodeRanks(graphemes(text).length, s.from, text.length);
+    let frame = 0;
+    const show = (p) => {
+        node.nodeValue = decodeFrame(text, p, Math.random, ranks, s.characters);
+    };
+    const stop = () => {
+        cancelAnimationFrame(frame);
+        frame = 0;
+        node.nodeValue = text;
+        el.removeAttribute("data-sx-text-playing");
+    };
+    const play = () => {
+        if (frame)
+            return;
+        const start = performance.now();
+        let last = -Infinity;
+        el.setAttribute("data-sx-text-playing", "");
+        el.removeAttribute("data-sx-text-wait");
+        const tick = (now) => {
+            const p = (now - start) / (s.duration * 1000);
+            if (p >= 1)
+                return stop();
+            if (now - last >= 1000 / s.fps) {
+                last = now;
+                show(p);
+            }
+            frame = requestAnimationFrame(tick);
+        };
+        frame = requestAnimationFrame(tick);
+    };
+    const cleanups = [];
+    if (s.onEnter) {
+        // scrambled until it is on screen; Text marks it data-sx-in then
+        if (el.hasAttribute("data-sx-in"))
+            play();
+        else {
+            show(0);
+            el.setAttribute("data-sx-text-playing", "");
+            const mo = new MutationObserver(() => {
+                if (el.hasAttribute("data-sx-in")) {
+                    mo.disconnect();
+                    el.removeAttribute("data-sx-text-playing");
+                    play();
+                }
+            });
+            mo.observe(el, { attributes: true, attributeFilter: ["data-sx-in"] });
+            cleanups.push(() => mo.disconnect());
+        }
+    }
+    if (s.onHover) {
+        // the text, or the link or button around it
+        const target = el.closest("a, button, [tabindex]") ?? el;
+        const onFocus = () => target.matches(":focus-visible") && play();
+        if (window.matchMedia("(hover: hover) and (pointer: fine)").matches)
+            target.addEventListener("pointerenter", play);
+        target.addEventListener("focus", onFocus);
+        cleanups.push(() => {
+            target.removeEventListener("pointerenter", play);
+            target.removeEventListener("focus", onFocus);
+        });
+    }
+    el.removeAttribute("data-sx-text-wait");
+    return () => {
+        cleanups.forEach((c) => c());
+        stop();
+    };
+}

package/dist/text/effects/enter/enterAssemble.d.ts

@@ -0,0 +1,12 @@
+import type { TextEffect } from "../../types.js";
+import { type EnterOptions } from "./kit.js";
+export interface EnterAssembleOptions extends EnterOptions {
+    /** How far away the pieces start, in em. Default `2.5`. */
+    readonly spread?: number;
+    /** How far they can be turned, in degrees. Default `120`. */
+    readonly turn?: number;
+    /** Where each piece starts: the same seed gives the same scatter on the server and in the browser. Default `1`. */
+    readonly seed?: number;
+}
+/** Letters fly in from scattered places and turns and come together into the text: a shatter played backwards. */
+export declare function enterAssemble(options?: EnterAssembleOptions): TextEffect;

package/dist/text/effects/enter/enterAssemble.js

@@ -0,0 +1,15 @@
+import { enter, v, varName } from "../kit.js";
+import { defineEnter } from "./kit.js";
+const ID = "enterAssemble";
+const CSS = enter(ID, {
+    from: `opacity: 0; translate: calc(var(--sx-ra, 0) * ${v(ID, "spread")}) calc(var(--sx-rb, 0) * ${v(ID, "spread")}); rotate: calc(var(--sx-rc, 0) * ${v(ID, "turn")});`,
+});
+/** Letters fly in from scattered places and turns and come together into the text: a shatter played backwards. */
+export function enterAssemble(options = {}) {
+    return defineEnter(ID, CSS, { stagger: 0.02, ...options }, {
+        by: "chars",
+        duration: 1,
+        vars: { [varName(ID, "spread")]: `${options.spread ?? 2.5}em`, [varName(ID, "turn")]: `${options.turn ?? 120}deg` },
+        needs: { scatter: true, seed: options.seed ?? 1 },
+    });
+}

package/dist/text/effects/enter/enterAssemble.schema.d.ts

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

package/dist/text/effects/enter/enterAssemble.schema.js

@@ -0,0 +1,15 @@
+import { seedField, textByField, textEnterFields, textFromField } from "../../../schema/common.js";
+import { defineSchema } from "../../../schema/define.js";
+export const ENTER_ASSEMBLE_SCHEMA = defineSchema()({
+    id: "enterAssemble",
+    family: "text",
+    factory: "enterAssemble",
+    fields: {
+        by: textByField("chars"),
+        ...textEnterFields({ duration: 1, stagger: 0.02 }),
+        from: textFromField(),
+        spread: { kind: "number", label: "Scatter", min: 0, max: 10, step: 0.1, unit: "em", default: 2.5 },
+        turn: { kind: "number", label: "Turn", min: 0, max: 360, step: 5, unit: "°", default: 120 },
+        seed: seedField(1),
+    },
+});

package/dist/text/effects/enter/enterBlur.d.ts

@@ -0,0 +1,8 @@
+import type { TextEffect } from "../../types.js";
+import { type EnterOptions } from "./kit.js";
+export interface EnterBlurOptions extends EnterOptions {
+    /** How blurred each piece starts, in px. Default `10`. */
+    readonly blur?: number;
+}
+/** Pieces come into focus from a blur. Blur costs the graphics chip: at most 60 letters, longer text moves by the word. */
+export declare function enterBlur(options?: EnterBlurOptions): TextEffect;

package/dist/text/effects/enter/enterBlur.js

@@ -0,0 +1,13 @@
+import { enter, v, varName } from "../kit.js";
+import { defineEnter } from "./kit.js";
+const ID = "enterBlur";
+const CSS = enter(ID, { from: `opacity: 0; filter: blur(${v(ID, "blur")}); translate: 0 0.15em;` });
+/** Pieces come into focus from a blur. Blur costs the graphics chip: at most 60 letters, longer text moves by the word. */
+export function enterBlur(options = {}) {
+    return defineEnter(ID, CSS, options, {
+        by: "words",
+        duration: 0.7,
+        vars: { [varName(ID, "blur")]: `${options.blur ?? 10}px` },
+        needs: { maxPieces: 60 },
+    });
+}

package/dist/text/effects/enter/enterBlur.schema.d.ts

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

package/dist/text/effects/enter/enterBlur.schema.js

@@ -0,0 +1,13 @@
+import { textByField, textEnterFields, textFromField } from "../../../schema/common.js";
+import { defineSchema } from "../../../schema/define.js";
+export const ENTER_BLUR_SCHEMA = defineSchema()({
+    id: "enterBlur",
+    family: "text",
+    factory: "enterBlur",
+    fields: {
+        by: textByField("words"),
+        ...textEnterFields({ duration: 0.7 }),
+        from: textFromField(),
+        blur: { kind: "number", label: "Blur", min: 0, max: 30, step: 1, unit: "px", default: 10 },
+    },
+});

package/dist/text/effects/enter/enterBounce.d.ts

@@ -0,0 +1,8 @@
+import type { TextEffect } from "../../types.js";
+import { type EnterOptions } from "./kit.js";
+export interface EnterBounceOptions extends EnterOptions {
+    /** How far below each piece starts, in em. Default `1`. */
+    readonly distance?: number;
+}
+/** Letters pull up past their place and settle back, one after another. */
+export declare function enterBounce(options?: EnterBounceOptions): TextEffect;

package/dist/text/effects/enter/enterBounce.js

@@ -0,0 +1,8 @@
+import { SPRING, enter, v, varName } from "../kit.js";
+import { defineEnter } from "./kit.js";
+const ID = "enterBounce";
+const CSS = enter(ID, { from: `opacity: 0; translate: 0 ${v(ID, "distance")};`, ease: SPRING });
+/** Letters pull up past their place and settle back, one after another. */
+export function enterBounce(options = {}) {
+    return defineEnter(ID, CSS, options, { by: "chars", duration: 0.8, vars: { [varName(ID, "distance")]: `${options.distance ?? 1}em` } });
+}

package/dist/text/effects/enter/enterBounce.schema.d.ts

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

package/dist/text/effects/enter/enterBounce.schema.js

@@ -0,0 +1,13 @@
+import { textByField, textEnterFields, textFromField } from "../../../schema/common.js";
+import { defineSchema } from "../../../schema/define.js";
+export const ENTER_BOUNCE_SCHEMA = defineSchema()({
+    id: "enterBounce",
+    family: "text",
+    factory: "enterBounce",
+    fields: {
+        by: textByField("chars"),
+        ...textEnterFields({ duration: 0.8 }),
+        from: textFromField(),
+        distance: { kind: "number", label: "Distance", min: 0, max: 3, step: 0.05, unit: "em", default: 1 },
+    },
+});

package/dist/text/effects/enter/enterBox.d.ts

@@ -0,0 +1,8 @@
+import type { TextEffect } from "../../types.js";
+import { type EnterTiming } from "./kit.js";
+export interface EnterBoxOptions extends Omit<EnterTiming, "stagger" | "from"> {
+    /** The box's colour. Default the theme's primary. */
+    readonly color?: string;
+}
+/** A block of colour wipes across the text and away again, leaving the text behind it. */
+export declare function enterBox(options?: EnterBoxOptions): TextEffect;