@promptctl/rich-js 0.24.1 → 0.25.1

package/dist/renderables/glyph-effect.js

@@ -0,0 +1,237 @@
+/**
+ * GlyphEffected — a renderable whose finished cells' glyphs pass through a
+ * glyph effect at a moment `t`: the glyph half of `Effected` (`./effect.ts`),
+ * built to its contract.
+ *
+ * A glyph effect is the colour effect's two-stage shape with a glyph where
+ * the colours were: for the cells an element draws in a frame, an
+ * `Animation` (`../core/animation.ts`) of what is done to them. The first
+ * stage is handed every cell once a frame (`GlyphCell`), blanks included —
+ * rain and stars live there — and whether the output draws ASCII alone
+ * (`DrawnGlyphs`), and works out what holds for the whole frame:
+ * how many cells are typed, where a band is. The second, the function
+ * `at(t)` returns, maps each cell to the text it shows. A typewriter, a
+ * scramble, a wave of case changes and particles on blank cells are all this
+ * one shape (`./glyph-effects.ts`) [LAW:one-type-per-behavior].
+ *
+ * Colour and glyph are not two kinds of animation: each is an `Animation` of
+ * a per-cell map, and they differ only in what a cell is mapped to. The
+ * wrappers are two because the stages are handed different facts. A colour
+ * effect is settled against the depth, the terminal and the colours of the
+ * words (`Drawn`), and with no colour output there is nothing for it to
+ * change. A glyph effect needs none of that, and is written at every depth,
+ * with no colour too. Over one element the two compose by nesting:
+ * `new Effected(new GlyphEffected(child, glyphs, …), colours, …)` moves the
+ * colours of the glyphs the glyph effect left, since each wrapper measures
+ * what its child drew.
+ *
+ * A `GlyphEffected` is the element under its glyph effect over time, an
+ * `Animation<Renderable>` placed as an `Effected` is, its value at `t` the
+ * element through the effect at `t` (`Reglyphed`).
+ * [LAW:no-ambient-temporal-coupling] The time is the frame's, never a clock
+ * read, so the same time draws the same bytes at any frame rate.
+ *
+ * What a glyph effect may not do is the contract this module holds:
+ *
+ * - It changes what a cell shows, never which cells exist, where they are or
+ *   who drew them. The text it returns for a cell is exactly as many cells
+ *   wide (`cellLen`), carries no line break or control character, and does
+ *   not join the cell beside it into one grapheme cluster, or the render
+ *   throws naming the cell [LAW:single-enforcer]. So what sits beside the
+ *   element never moves, and a wide glyph is changed whole — blanked as two
+ *   spaces, scrambled as two one-cell glyphs — never cut.
+ * - A segment whose every glyph comes back as it was is yielded as it was,
+ *   so the identity effect is byte-identical. A changed segment keeps its
+ *   style whole, link, meta and anchor included; no cell has moved, so the
+ *   anchor's offsets are still true and hit testing still finds the owner.
+ * - Placed as a `GlyphEffected`, every cell carries the hold the frame is in
+ *   (`Style.hold`), under whatever the child said,
+ *   as under `Effected`; drawn as a `Reglyphed`, a value, none.
+ *
+ * Positions are the child's own: row and column count from the top-left of
+ * what the child drew.
+ */
+import { Animation, frameTimeOf, holdOf, shownAt, stampFrame } from "../core/animation.js";
+import { cellLen, graphemes } from "../core/cells.js";
+import { Measurement } from "../core/measure.js";
+import { render } from "../core/protocol.js";
+import { Segment } from "../core/segment.js";
+import { finiteTime } from "../core/easing.js";
+import { stripControlChars } from "../core/text.js";
+import { cellSeed, walkGlyphs } from "./effect.js";
+import { pattern } from "../core/pattern.js";
+/**
+ * A `GlyphEffected` at `t`, or an element through a glyph effect at a time an
+ * animation's `at` was handed: `renderable` with its cells' glyphs passed
+ * through `effect` at `t`, saying nothing of when that changes, as a
+ * `Recolored` is (`./effect.ts`). [LAW:one-type-per-behavior]
+ */
+export class Reglyphed {
+    renderable;
+    effect;
+    t;
+    key;
+    constructor(renderable, effect, options) {
+        this.renderable = renderable;
+        this.effect = effect;
+        this.t = finiteTime("GlyphEffected", options.t);
+        this.key = options.key;
+    }
+    render(options) {
+        return this.moved(options).segments;
+    }
+    /** The frame the effect draws at `t`, and the hold it says that is in. */
+    moved(options) {
+        const segments = [...render(this.renderable, options)];
+        const { placed, cells } = placeGlyphs(segments, this.key);
+        const animation = this.effect({ cells, asciiOnly: options.asciiOnly === true });
+        const frame = shownAt(animation, this.t, options);
+        const shown = showGlyphs(placed, frame.value);
+        const changed = segments.map((segment, i) => shown[i].every((text, j) => text === placed[i][j].glyph) ? segment : new Segment(shown[i].join(""), segment.style));
+        return { segments: changed, hold: holdOf(frame, this.t) };
+    }
+    measure(options) {
+        return Measurement.get(options, this.renderable);
+    }
+}
+/**
+ * `renderable` under a glyph effect over time, an `Animation<Renderable>`
+ * as an `Effected` is (`./effect.ts`): its own answer is `t`, and placed,
+ * its cells carry the glyph effect's exact hold at the frame's time and the
+ * output's `asciiOnly`, under whatever the element already said.
+ */
+export class GlyphEffected {
+    renderable;
+    effect;
+    key;
+    constructor(renderable, effect, options) {
+        this.renderable = renderable;
+        this.effect = effect;
+        this.key = options.key;
+    }
+    /** The element through the glyph effect at `t`, unstamped. */
+    at(t) {
+        return new Reglyphed(this.renderable, this.effect, { t, key: this.key });
+    }
+    nextChange(t) {
+        return t;
+    }
+    lastChange(t) {
+        return t;
+    }
+    /** The element under the glyph effect with its motion taken out. */
+    reduced() {
+        const { effect } = this;
+        return new GlyphEffected(this.renderable, (drawn) => effect(drawn).reduced(), this);
+    }
+    /** Drawn at the frame's time, its cells stamped with the glyph effect's exact hold there. */
+    render(options) {
+        const { segments, hold } = this.at(frameTimeOf(options)).moved(options);
+        return stampFrame(segments, hold);
+    }
+    measure(options) {
+        return Measurement.get(options, this.renderable);
+    }
+}
+/**
+ * Each segment's glyphs, each with its cell as the effect is handed it, and
+ * every cell in reading order. [LAW:one-source-of-truth] One walk, one count
+ * of reading order, for a rendered frame and a text alike.
+ */
+function placeGlyphs(segments, key) {
+    let index = 0;
+    const placed = walkGlyphs(segments).map((glyphs) => glyphs.map(({ glyph, cell }) => ({ glyph, cell: cell && { ...cell, glyph, index: index++, seed: cellSeed(key, cell.row, cell.col) } })));
+    return { placed, cells: placed.flatMap((glyphs) => glyphs.flatMap(({ cell }) => (cell === undefined ? [] : [cell]))) };
+}
+/** What `frame` shows for each placed glyph, held to the contract (`shows`, `standsApart`). */
+function showGlyphs(placed, frame) {
+    const shown = placed.map((glyphs) => glyphs.map(({ glyph, cell }) => (cell === undefined ? glyph : shows(frame, cell))));
+    standsApart(placed.flat(), shown.flat());
+    return shown;
+}
+/**
+ * `text` with its glyphs passed through `effect`, before any render: the
+ * glyph half of a template fragment (`../template-bindings/animation-funcs.ts`),
+ * which is spliced into a line and drawn under a theme it does not know yet,
+ * so it cannot be rendered to cells first as `Reglyphed` renders its child.
+ * The cells are the text's own lines, at its own columns; the contract is
+ * the one `Reglyphed` is held to, through the same checks, over the text's
+ * own glyphs: a neighbour spliced beside it later, a combining mark leading
+ * the next fragment say, is outside what either check can see. The text keeps
+ * its every style and span, each moved to where its glyphs now sit, and a
+ * frame that changes nothing hands the text back as it was. What it says of
+ * when it changes is the effect's, unstamped: whoever draws it at a time
+ * stamps it (`textFrameAt`).
+ */
+export function reglyphText(text, effect, options) {
+    const { placed, cells } = placeGlyphs([new Segment(text.plain)], options.key);
+    return Animation.map(effect({ cells, asciiOnly: options.asciiOnly }), (frame) => rewritten(text, placed[0], showGlyphs(placed, frame)[0]));
+}
+/**
+ * `text` with each of its `glyphs` written as `shown` says, every span moved
+ * with the glyphs it covers. An offset inside a glyph — a span edge between
+ * a letter and its mark — lands as far into the written glyph as it can.
+ */
+function rewritten(text, glyphs, shown) {
+    if (shown.every((s, i) => s === glyphs[i].glyph))
+        return text;
+    // Where each glyph starts, before and after, with one more entry for the end.
+    const from = [0];
+    const to = [0];
+    glyphs.forEach(({ glyph }, i) => {
+        from.push(from[i] + glyph.length);
+        to.push(to[i] + shown[i].length);
+    });
+    const moved = (offset) => {
+        let i = 0;
+        while (i + 1 < from.length && from[i + 1] <= offset)
+            i++;
+        return i === glyphs.length ? to[i] : to[i] + Math.min(offset - from[i], shown[i].length);
+    };
+    const result = text.blankCopy(shown.join(""));
+    for (const span of text.spans)
+        result.stylize(span.style, moved(span.start), moved(span.end));
+    return result;
+}
+/** Line breaks and tabs, which `stripControlChars` leaves for a text's own lines and which no cell may hold. */
+const BREAKS = pattern(/[\n\t]/);
+/**
+ * What `frame` shows in `cell`, held to the contract: as many cells wide as
+ * the glyph, with no line break or control character. [LAW:single-enforcer]
+ * The one place a glyph effect's output is checked; a breach throws, naming
+ * the cell and what it was turned into.
+ */
+function shows(frame, cell) {
+    const text = frame(cell);
+    if (text === cell.glyph)
+        return text;
+    if (cellLen(text) !== cellLen(cell.glyph) || BREAKS.test(text) || stripControlChars(text) !== text) {
+        throw new RangeError(`a glyph effect turned ${JSON.stringify(cell.glyph)} at row ${cell.row}, column ${cell.col} into ${JSON.stringify(text)}: ` +
+            `it must be ${cellLen(cell.glyph)} cell(s) wide, with no line break or control character`);
+    }
+    return text;
+}
+/**
+ * Every text `frame` changed, in `shown`, stands apart from the texts beside
+ * it on its line: joined to them, it splits into as many grapheme clusters as
+ * it and they do alone, or this throws naming the cell. Each text being as
+ * wide as its glyph is `shows`'s check; this is the half no one cell can
+ * see — a trailing zero-width joiner that fuses with the next emoji, or a
+ * leading combining mark that draws on the glyph before it, is right alone
+ * and wrong beside its neighbour. Only a changed text is asked, so a child
+ * that splits a cluster across its own segments is drawn as it drew it.
+ */
+function standsApart(placed, shown) {
+    // A line break is no cell, and nothing joins across it.
+    const beside = (j) => (placed[j]?.cell === undefined ? "" : shown[j]);
+    shown.forEach((text, i) => {
+        const { glyph, cell } = placed[i];
+        if (cell === undefined || text === glyph)
+            return;
+        const [before, after] = [beside(i - 1), beside(i + 1)];
+        if (graphemes(before + text + after).length !== graphemes(before).length + graphemes(text).length + graphemes(after).length) {
+            throw new RangeError(`a glyph effect turned ${JSON.stringify(glyph)} at row ${cell.row}, column ${cell.col} into ${JSON.stringify(text)}, ` +
+                `which joins the cell beside it into one character`);
+        }
+    });
+}

package/dist/renderables/glyph-effects.d.ts

@@ -0,0 +1,147 @@
+/**
+ * The glyph effect catalogue: a typewriter and a scramble, which run once and
+ * are done, each with its way out for an element leaving (`backspace`,
+ * `scrambleOut`), and a wave of case changes, rain and stars, which loop for as
+ * long as they are drawn. Each is a `GlyphEffect` for `GlyphEffected`
+ * (`./glyph-effect.ts`), built as the colour catalogue's are
+ * (`./effects.ts`): one function each over the one shape, made by name, one
+ * way, at the defaults in `GLYPH_DEFAULTS` (`GLYPH_EFFECT_CATALOGUE`).
+ *
+ * Where a colour loop glides, a glyph cannot: a cell shows one glyph or
+ * another, so every loop here moves in steps, on a `beat`, and says when its
+ * next step is. The transitions are `Transition`s by the one rule the
+ * colour transitions follow (`transition`): they move every frame until
+ * their seconds are up, and never after.
+ *
+ * [LAW:no-ambient-temporal-coupling] No effect reads a clock, and what a cell
+ * shows at `t` is worked out from `t` alone, so a draw costs the same at
+ * `t = 0` and `t = 10⁶`, and a host drawing once a second and one drawing
+ * sixty times show the same cell at every `t` they share. What is random is
+ * `hash` (`../core/noise.ts`) of where a cell is and which step it is in.
+ */
+import { type Timing } from "../core/easing.js";
+import { type EffectTarget, type Transition } from "./effects.js";
+import type { GlyphEffect } from "./glyph-effect.js";
+/** A glyph effect that runs once, and says when it is done. */
+export type GlyphTransition = Transition<GlyphEffect>;
+/**
+ * A typewriter: the element's text blank until it is typed, in reading
+ * order, the last cell at `timing.seconds`. The ease shapes the pace, so
+ * `ease-out` types fast and slows to the end. The spaces between words are
+ * typed too, as a typewriter's are; the margins a renderable pads its text
+ * with are not text, so no second is spent on them.
+ */
+export declare function typewriter(timing: Timing): GlyphTransition;
+/**
+ * A scramble that resolves: a cell of the element's text shows glyphs drawn
+ * at random, a new one each flicker, until it resolves to its own, in reading
+ * order, the last at `timing.seconds`. A wide glyph scrambles as two one-cell
+ * glyphs. A blank stays blank, so the words keep their shape while their
+ * letters churn.
+ */
+export declare function scramble(timing: Timing, z: number): GlyphTransition;
+/**
+ * A typewriter backwards, for an element leaving: its text whole, then erased
+ * from its last cell to its first, the first at `timing.seconds`, so the
+ * element ends blank and nothing is left to vanish when it goes.
+ */
+export declare function backspace(timing: Timing): GlyphTransition;
+/**
+ * A scramble that decays, for an element leaving: its text whole, then each
+ * cell, in reading order, churning through random glyphs for a while before
+ * it is blank, the last blank at `timing.seconds`. A blank stays blank, as in
+ * `scramble`, so the words keep their shape until they are gone.
+ */
+export declare function scrambleOut(timing: Timing, z: number): GlyphTransition;
+/** How a case wave moves: a step, in seconds, for the band to move one column, and how many columns wide it is. */
+export interface CaseWave {
+    readonly step: number;
+    readonly width: number;
+}
+/**
+ * A wave of case changes: a band `width` columns wide crosses the element
+ * left to right, one column a `step`, and every cell inside it shows its
+ * glyph's case swapped. It starts again once it has left the last column,
+ * so a pass takes the element's columns and the band's, a step each. `z`
+ * sets how far into its pass the band is at `t = 0`.
+ */
+export declare function caseWave({ step, width }: CaseWave, z: number): GlyphEffect;
+/** Particles over the blank cells of an element: what they look like, how many, and how they move. */
+export interface Particles {
+    /** The glyphs a particle may be, each one cell wide. */
+    readonly glyphs: string;
+    /** What it may be on an output that draws ASCII alone, each one cell wide. */
+    readonly ascii: string;
+    /** The share of blank cells holding a particle at any step, in [0, 1]. */
+    readonly density: number;
+    /** How long a step holds, in seconds. */
+    readonly step: number;
+    /** How many rows every particle falls each step, a whole number, since a glyph moves a cell at a time; 0 holds them where they are. */
+    readonly drift: number;
+    /** How many steps a particle lasts before the field is drawn afresh; `Infinity`, never. */
+    readonly life: number;
+}
+/**
+ * Particles on the element's blank cells: rain falling, stars coming and
+ * going. A particle is never drawn over a glyph, so it passes behind the
+ * words. Which cells hold one is `hash` of the cell's column, where it was at
+ * the step's start (its row less what the field has fallen) and which life
+ * of the field this is, so a field that falls carries each particle down a
+ * row a step, and one that holds still draws a fresh field each life.
+ */
+export declare function particles(spec: Particles, z: number): GlyphEffect;
+/** The names of the glyph effects that loop. */
+export type GlyphLoopName = "wave" | "rain" | "stars";
+/** The names of the glyph effects that run once. */
+export type GlyphTransitionName = "typewriter" | "scramble" | "backspace" | "scrambleOut";
+/** Each catalogue glyph effect's defaults, as first drawn in `examples/glyph-effects`. */
+export declare const GLYPH_DEFAULTS: {
+    readonly typewriter: {
+        readonly seconds: 2;
+        readonly ease: import("../core/easing.js").Ease;
+    };
+    readonly scramble: {
+        readonly seconds: 2.5;
+        readonly ease: import("../core/easing.js").Ease;
+    };
+    readonly backspace: {
+        readonly seconds: 1.5;
+        readonly ease: import("../core/easing.js").Ease;
+    };
+    readonly scrambleOut: {
+        readonly seconds: 2.5;
+        readonly ease: import("../core/easing.js").Ease;
+    };
+    readonly wave: {
+        readonly step: 0.06;
+        readonly width: 3;
+    };
+    readonly rain: {
+        readonly glyphs: "│╎";
+        readonly ascii: "|:";
+        readonly density: 0.06;
+        readonly step: 0.08;
+        readonly drift: 1;
+        readonly life: number;
+    };
+    readonly stars: {
+        readonly glyphs: "·+*";
+        readonly ascii: ".+*";
+        readonly density: 0.04;
+        readonly step: 1.5;
+        readonly drift: 0;
+        readonly life: 1;
+    };
+};
+/**
+ * Every glyph effect in the catalogue by name, each made the one way: for an
+ * element, at `z` in the noise so two elements under one effect do not move
+ * in lockstep, at its defaults. A transition takes another timing in place
+ * of its own. [LAW:types-are-the-program] Keyed by the two name types, as
+ * `EFFECT_CATALOGUE` is, so a picker walking a section's names offers an
+ * effect added here with no change of its own.
+ */
+export declare const GLYPH_EFFECT_CATALOGUE: {
+    readonly loops: Readonly<Record<GlyphLoopName, (element: EffectTarget) => GlyphEffect>>;
+    readonly transitions: Readonly<Record<GlyphTransitionName, (element: EffectTarget, timing?: Timing) => GlyphTransition>>;
+};

package/dist/renderables/glyph-effects.js

@@ -0,0 +1,283 @@
+/**
+ * The glyph effect catalogue: a typewriter and a scramble, which run once and
+ * are done, each with its way out for an element leaving (`backspace`,
+ * `scrambleOut`), and a wave of case changes, rain and stars, which loop for as
+ * long as they are drawn. Each is a `GlyphEffect` for `GlyphEffected`
+ * (`./glyph-effect.ts`), built as the colour catalogue's are
+ * (`./effects.ts`): one function each over the one shape, made by name, one
+ * way, at the defaults in `GLYPH_DEFAULTS` (`GLYPH_EFFECT_CATALOGUE`).
+ *
+ * Where a colour loop glides, a glyph cannot: a cell shows one glyph or
+ * another, so every loop here moves in steps, on a `beat`, and says when its
+ * next step is. The transitions are `Transition`s by the one rule the
+ * colour transitions follow (`transition`): they move every frame until
+ * their seconds are up, and never after.
+ *
+ * [LAW:no-ambient-temporal-coupling] No effect reads a clock, and what a cell
+ * shows at `t` is worked out from `t` alone, so a draw costs the same at
+ * `t = 0` and `t = 10⁶`, and a host drawing once a second and one drawing
+ * sixty times show the same cell at every `t` they share. What is random is
+ * `hash` (`../core/noise.ts`) of where a cell is and which step it is in.
+ */
+import { Animation } from "../core/animation.js";
+import { cellLen, graphemes } from "../core/cells.js";
+import { EASES, Phase, beat, positiveSeconds, settled } from "../core/easing.js";
+import { hash } from "../core/noise.js";
+import { drawable, isAscii } from "../core/protocol.js";
+import { inked } from "./effect.js";
+import { requireZ, transition } from "./effects.js";
+/** `glyph` as blank: as many spaces as it is cells wide. */
+function blank(glyph) {
+    return " ".repeat(cellLen(glyph));
+}
+/**
+ * The text among `cells`: each row from its first inked glyph to its last,
+ * the blanks between words in it and the margins round it not, as a
+ * typewriter types and not as a renderable pads. A glyph no cell wide — a
+ * byte-order mark, a mark a child split from its letter — takes no time and
+ * is no place in it. Each cell's place, in reading order, by `index`, and
+ * how many places there are.
+ */
+function text(cells) {
+    const ends = new Map();
+    for (const cell of cells.filter((c) => inked(c.glyph)))
+        ends.set(cell.row, { first: ends.get(cell.row)?.first ?? cell.index, last: cell.index });
+    const place = new Map();
+    for (const cell of cells) {
+        const row = ends.get(cell.row);
+        if (row !== undefined && cell.index >= row.first && cell.index <= row.last && cellLen(cell.glyph) > 0)
+            place.set(cell.index, place.size);
+    }
+    return { length: place.size, place };
+}
+/** Of `n` cells, how many have arrived at eased progress `p`, an ease that overshoots held to the cells there are. */
+function arrived(n, p) {
+    return Math.min(n, Math.max(0, Math.floor(n * p)));
+}
+/**
+ * Steps of `seconds`, counted from 0 on the animation's own clock: for a
+ * `frame` of each step, the animation holding it through the step and
+ * changing at its end, and reduced, `still`. [LAW:one-source-of-truth] The step and its two ends
+ * are a `beat`'s, the one timing vocabulary, so a step boundary is the moment
+ * the change shows. The beat is made once, for every frame drawn on it.
+ */
+function stepped(seconds) {
+    const pace = beat([seconds]);
+    return (frame, still) => Animation.of({
+        at: (t) => frame(Math.round(pace.lastChange(t) / seconds)),
+        nextChange: (t) => pace.nextChange(t),
+        lastChange: (t) => pace.lastChange(t),
+        reduced: () => Animation.constant(still),
+    });
+}
+/** Every cell its own glyph: a glyph loop with its motion taken out — the text as written, no wave, no rain. */
+const AS_WRITTEN = (cell) => cell.glyph;
+/**
+ * A typewriter: the element's text blank until it is typed, in reading
+ * order, the last cell at `timing.seconds`. The ease shapes the pace, so
+ * `ease-out` types fast and slows to the end. The spaces between words are
+ * typed too, as a typewriter's are; the margins a renderable pads its text
+ * with are not text, so no second is spent on them.
+ */
+export function typewriter(timing) {
+    const phase = Phase.once(0, timing.seconds);
+    // Settled, so the last cell is typed at the seconds whatever ease was handed.
+    const ease = settled(timing.ease);
+    return transition(timing.seconds, ({ cells }) => {
+        const { length, place } = text(cells);
+        return Animation.continuous((t) => {
+            const typed = arrived(length, ease(phase(t)));
+            // A margin has no place, and is blank already.
+            return (cell) => ((place.get(cell.index) ?? -1) < typed ? cell.glyph : blank(cell.glyph));
+        });
+    });
+}
+/** What a scrambled cell shows: one-cell glyphs, none that reads as a blank. */
+const SCRAMBLE_GLYPHS = [..."ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789#$%&*+<=>?@"];
+/** How long a scrambled glyph holds before the next, in seconds. */
+const FLICKER = 1 / 15;
+/**
+ * A scramble that resolves: a cell of the element's text shows glyphs drawn
+ * at random, a new one each flicker, until it resolves to its own, in reading
+ * order, the last at `timing.seconds`. A wide glyph scrambles as two one-cell
+ * glyphs. A blank stays blank, so the words keep their shape while their
+ * letters churn.
+ */
+export function scramble(timing, z) {
+    requireZ("scramble", z);
+    const phase = Phase.once(0, timing.seconds);
+    // Settled, so the last cell resolves at the seconds whatever ease was handed.
+    const ease = settled(timing.ease);
+    const flicker = stepped(FLICKER)((step) => step, 0);
+    return transition(timing.seconds, ({ cells }) => {
+        const { length, place } = text(cells);
+        return Animation.continuous((t) => {
+            const resolved = arrived(length, ease(phase(t)));
+            const step = flicker.at(t);
+            return (cell) => (!inked(cell.glyph) || (place.get(cell.index) ?? -1) < resolved ? cell.glyph : churned(cell, z, step));
+        });
+    });
+}
+/** `cell` scrambled at flicker `step`: a random one-cell glyph for each cell it is wide. */
+function churned(cell, z, step) {
+    const pick = (i) => SCRAMBLE_GLYPHS[Math.floor(hash(cell.seed * 7919 + i, z + step * 0.618) * SCRAMBLE_GLYPHS.length)];
+    return Array.from({ length: cellLen(cell.glyph) }, (_, i) => pick(i)).join("");
+}
+/**
+ * A typewriter backwards, for an element leaving: its text whole, then erased
+ * from its last cell to its first, the first at `timing.seconds`, so the
+ * element ends blank and nothing is left to vanish when it goes.
+ */
+export function backspace(timing) {
+    const phase = Phase.once(0, timing.seconds);
+    // Settled, so the first cell is erased at the seconds whatever ease was handed.
+    const ease = settled(timing.ease);
+    return transition(timing.seconds, ({ cells }) => {
+        const { length, place } = text(cells);
+        return Animation.continuous((t) => {
+            const kept = length - arrived(length, ease(phase(t)));
+            // A margin has no place, and is blank already.
+            return (cell) => ((place.get(cell.index) ?? -1) < kept ? cell.glyph : blank(cell.glyph));
+        });
+    });
+}
+/** Of a `scrambleOut`'s seconds, the share each cell churns for between its own glyph and its blank. */
+const CHURN = 0.3;
+/**
+ * A scramble that decays, for an element leaving: its text whole, then each
+ * cell, in reading order, churning through random glyphs for a while before
+ * it is blank, the last blank at `timing.seconds`. A blank stays blank, as in
+ * `scramble`, so the words keep their shape until they are gone.
+ */
+export function scrambleOut(timing, z) {
+    requireZ("scrambleOut", z);
+    const phase = Phase.once(0, timing.seconds);
+    // Settled, so the last cell is blank at the seconds whatever ease was handed.
+    const ease = settled(timing.ease);
+    const flicker = stepped(FLICKER)((step) => step, 0);
+    return transition(timing.seconds, ({ cells }) => {
+        const { length, place } = text(cells);
+        return Animation.continuous((t) => {
+            const p = ease(phase(t));
+            // Two fronts in reading order, a churn's share of the seconds apart: past the first a cell churns, past the second it is blank.
+            const churning = arrived(length, p / (1 - CHURN));
+            const gone = arrived(length, (p - CHURN) / (1 - CHURN));
+            const step = flicker.at(t);
+            return (cell) => {
+                // A margin or a glyph no cell wide has no place, and neither front reaches it.
+                const at = place.get(cell.index) ?? Number.POSITIVE_INFINITY;
+                if (at < gone)
+                    return blank(cell.glyph);
+                return !inked(cell.glyph) || at >= churning ? cell.glyph : churned(cell, z, step);
+            };
+        });
+    });
+}
+/**
+ * `glyph` with its case swapped, or as it is if the swap would change how
+ * wide it is (`ß` upper-cases to `SS`), since a cell never changes width.
+ */
+function swapCase(glyph) {
+    const swapped = [...glyph].map((ch) => (ch === ch.toUpperCase() ? ch.toLowerCase() : ch.toUpperCase())).join("");
+    return cellLen(swapped) === cellLen(glyph) ? swapped : glyph;
+}
+/**
+ * A wave of case changes: a band `width` columns wide crosses the element
+ * left to right, one column a `step`, and every cell inside it shows its
+ * glyph's case swapped. It starts again once it has left the last column,
+ * so a pass takes the element's columns and the band's, a step each. `z`
+ * sets how far into its pass the band is at `t = 0`.
+ */
+export function caseWave({ step, width }, z) {
+    positiveSeconds("caseWave step", step);
+    if (!(Number.isInteger(width) && width > 0))
+        throw new RangeError(`caseWave width must be a positive whole number of columns, got ${width}`);
+    requireZ("caseWave", z);
+    const steps = stepped(step);
+    return ({ cells }) => {
+        const columns = cells.reduce((most, cell) => Math.max(most, cell.col + cellLen(cell.glyph)), 0);
+        const span = columns + width;
+        const start = Math.floor(hash(z, 2.3) * span);
+        return steps((s) => {
+            // The column just past the band's right edge; it enters at the left.
+            const lead = (((s + start) % span) + span) % span;
+            // A wide glyph is in the band if any of its columns is.
+            return (cell) => (cell.col < lead && cell.col + cellLen(cell.glyph) > lead - width ? swapCase(cell.glyph) : cell.glyph);
+        }, AS_WRITTEN);
+    };
+}
+/**
+ * Particles on the element's blank cells: rain falling, stars coming and
+ * going. A particle is never drawn over a glyph, so it passes behind the
+ * words. Which cells hold one is `hash` of the cell's column, where it was at
+ * the step's start (its row less what the field has fallen) and which life
+ * of the field this is, so a field that falls carries each particle down a
+ * row a step, and one that holds still draws a fresh field each life.
+ */
+export function particles(spec, z) {
+    const oneCell = (set) => {
+        const glyphs = graphemes(set);
+        if (glyphs.length === 0 || glyphs.some((glyph) => cellLen(glyph) !== 1))
+            throw new RangeError(`particles needs one-cell glyphs, got ${JSON.stringify(set)}`);
+        return glyphs;
+    };
+    const [glyphs, ascii] = [oneCell(spec.glyphs), oneCell(spec.ascii)];
+    if (!isAscii(spec.ascii))
+        throw new RangeError(`particles ascii must be ASCII, got ${JSON.stringify(spec.ascii)}`);
+    if (!(spec.density >= 0 && spec.density <= 1))
+        throw new RangeError(`particles density must be in [0, 1], got ${spec.density}`);
+    if (!Number.isInteger(spec.drift))
+        throw new RangeError(`particles drift must be a whole number of rows, got ${spec.drift}`);
+    if (!(spec.life > 0))
+        throw new RangeError(`particles life must be a positive number of steps, got ${spec.life}`);
+    positiveSeconds("particles step", spec.step);
+    requireZ("particles", z);
+    const steps = stepped(spec.step);
+    return ({ asciiOnly }) => {
+        const drawn = drawable({ asciiOnly }, glyphs, ascii, (set) => set.join(""));
+        return steps((s) => {
+            const life = Number.isFinite(spec.life) ? Math.floor(s / spec.life) : 0;
+            const fallen = spec.drift * s;
+            return (cell) => {
+                // A particle takes a blank cell, never ink, nor a glyph no cell wide.
+                if (inked(cell.glyph) || cellLen(cell.glyph) === 0)
+                    return cell.glyph;
+                const from = cell.row - fallen;
+                const field = z + 1.37 * cell.col + 0.71 * life;
+                // A particle is one cell; a wide blank keeps the rest of its width blank.
+                return hash(from, field) < spec.density ? drawn[Math.floor(hash(from, field + 3.1) * drawn.length)] + blank(cell.glyph).slice(1) : cell.glyph;
+            };
+        }, AS_WRITTEN);
+    };
+}
+/** Each catalogue glyph effect's defaults, as first drawn in `examples/glyph-effects`. */
+export const GLYPH_DEFAULTS = {
+    typewriter: { seconds: 2, ease: EASES.linear },
+    scramble: { seconds: 2.5, ease: EASES["ease-in"] },
+    backspace: { seconds: 1.5, ease: EASES.linear },
+    scrambleOut: { seconds: 2.5, ease: EASES["ease-out"] },
+    wave: { step: 0.06, width: 3 },
+    rain: { glyphs: "│╎", ascii: "|:", density: 0.06, step: 0.08, drift: 1, life: Number.POSITIVE_INFINITY },
+    stars: { glyphs: "·+*", ascii: ".+*", density: 0.04, step: 1.5, drift: 0, life: 1 },
+};
+/**
+ * Every glyph effect in the catalogue by name, each made the one way: for an
+ * element, at `z` in the noise so two elements under one effect do not move
+ * in lockstep, at its defaults. A transition takes another timing in place
+ * of its own. [LAW:types-are-the-program] Keyed by the two name types, as
+ * `EFFECT_CATALOGUE` is, so a picker walking a section's names offers an
+ * effect added here with no change of its own.
+ */
+export const GLYPH_EFFECT_CATALOGUE = {
+    loops: {
+        wave: (element) => caseWave(GLYPH_DEFAULTS.wave, element.z),
+        rain: (element) => particles(GLYPH_DEFAULTS.rain, element.z),
+        stars: (element) => particles(GLYPH_DEFAULTS.stars, element.z),
+    },
+    transitions: {
+        typewriter: (_element, timing = GLYPH_DEFAULTS.typewriter) => typewriter(timing),
+        scramble: (element, timing = GLYPH_DEFAULTS.scramble) => scramble(timing, element.z),
+        backspace: (_element, timing = GLYPH_DEFAULTS.backspace) => backspace(timing),
+        scrambleOut: (element, timing = GLYPH_DEFAULTS.scrambleOut) => scrambleOut(timing, element.z),
+    },
+};