@promptctl/rich-js 0.21.0 → 0.23.0

package/dist/core/color.d.ts

@@ -259,6 +259,15 @@ export declare class ColorSpec {
      * on a ground (`flattenAlpha`).
      */
     static matchOn(value: ColorRgba, depth: ColorDepth, theme: TerminalTheme, foreground: boolean): ColorSpec;
+    /**
+     * The spec a slot is written in once its colour moves from `was`, what its
+     * written spec draws on `theme`, to the opaque `now`: `matchOn`'s — or
+     * none, where the written spec is as near `now` as that match. A move the
+     * depth cannot show is no move, so below truecolor a colour moved a little
+     * off any colour the depth can write — a theme slot, the default colour,
+     * the cube — keeps the spec it was written in.
+     */
+    static matchMove(was: ColorRgba, now: ColorRgba, depth: ColorDepth, theme: TerminalTheme, foreground: boolean): ColorSpec | undefined;
     /**
      * Parse a color string. Memoized (`Memo`): a string parsed again while
      * remembered returns the same instance.

package/dist/core/color.js

@@ -624,6 +624,18 @@ export class ColorSpec {
         ];
         return candidates.reduce((best, next) => (rgbDistance(next[1], value) < rgbDistance(best[1], value) ? next : best))[0];
     }
+    /**
+     * The spec a slot is written in once its colour moves from `was`, what its
+     * written spec draws on `theme`, to the opaque `now`: `matchOn`'s — or
+     * none, where the written spec is as near `now` as that match. A move the
+     * depth cannot show is no move, so below truecolor a colour moved a little
+     * off any colour the depth can write — a theme slot, the default colour,
+     * the cube — keeps the spec it was written in.
+     */
+    static matchMove(was, now, depth, theme, foreground) {
+        const match = ColorSpec.matchOn(now, depth, theme, foreground);
+        return rgbDistance(was, now) <= rgbDistance(match.getTruecolor(theme, foreground), now) ? undefined : match;
+    }
     /**
      * Parse a color string. Memoized (`Memo`): a string parsed again while
      * remembered returns the same instance.

package/dist/core/strip.d.ts

@@ -77,11 +77,11 @@ export interface Joiner<T extends StyledRenderable = StyledRenderable> {
  */
 export declare const JOIN: object;
 /**
- * Which of a cell's two colours on screen are `owner`'s: both, for a cell
- * `owner` drew, itself or through an owner nested in its output; for a cell a
- * `CellJoiner` drew, the sides shown in `owner`'s colour.
+ * Which of a cell's two colours on screen are one of `owners`': both, for a
+ * cell one of them drew, itself or through an owner nested in its output; for
+ * a cell a `CellJoiner` drew, the sides shown in one of their colours.
  */
-export declare function colorsOwnedBy(anchor: Anchor | undefined, owner: object): {
+export declare function colorsOwnedBy(anchor: Anchor | undefined, owners: ReadonlySet<object>): {
     readonly fg: boolean;
     readonly bg: boolean;
 };

package/dist/core/strip.js

@@ -59,16 +59,18 @@ class ColorOwners {
     }
 }
 /**
- * Which of a cell's two colours on screen are `owner`'s: both, for a cell
- * `owner` drew, itself or through an owner nested in its output; for a cell a
- * `CellJoiner` drew, the sides shown in `owner`'s colour.
+ * Which of a cell's two colours on screen are one of `owners`': both, for a
+ * cell one of them drew, itself or through an owner nested in its output; for
+ * a cell a `CellJoiner` drew, the sides shown in one of their colours.
  */
-export function colorsOwnedBy(anchor, owner) {
+export function colorsOwnedBy(anchor, owners) {
     for (let level = anchor; level; level = level.inner) {
-        if (level.owner === owner)
+        if (owners.has(level.owner))
             return { fg: true, bg: true };
-        if (level.owner instanceof ColorOwners)
-            return { fg: level.owner.fg === owner, bg: level.owner.bg === owner };
+        if (level.owner instanceof ColorOwners) {
+            const { fg, bg } = level.owner;
+            return { fg: fg !== null && owners.has(fg), bg: bg !== null && owners.has(bg) };
+        }
     }
     return { fg: false, bg: false };
 }

package/dist/index.d.ts

@@ -57,8 +57,8 @@ export type { Env } from "./core/env.js";
 export { Constrain } from "./renderables/constrain.js";
 export { Effected, confined, drawnOf } from "./renderables/effect.js";
 export type { CellColors, Drawn, Effect, EffectCell, EffectedOptions, Pair } from "./renderables/effect.js";
-export { EFFECT_CURVES, EFFECT_LIGHTS, SHIMMER_WIDTH, dissolveOut, fadeIn, onColors, pulse, shimmer, sparkle, wheel, } from "./renderables/effects.js";
-export type { Curve, Field, Loop, Touch, Transition } from "./renderables/effects.js";
+export { EFFECT_CATALOGUE, EFFECT_CURVES, EFFECT_LIGHTS, dissolveOut, fadeIn, onColors, pulse, shimmer, sparkle, wheel, } from "./renderables/effects.js";
+export type { Curve, EffectTarget, Field, Loop, LoopName, Touch, Transition, TransitionName } from "./renderables/effects.js";
 export { Align } from "./renderables/align.js";
 export type { Alignment } from "./core/place.js";
 export { Padding } from "./renderables/padding.js";

package/dist/index.js

@@ -70,7 +70,7 @@ export { Console } from "./core/console.js";
 // Renderables
 export { Constrain } from "./renderables/constrain.js";
 export { Effected, confined, drawnOf } from "./renderables/effect.js";
-export { EFFECT_CURVES, EFFECT_LIGHTS, SHIMMER_WIDTH, dissolveOut, fadeIn, onColors, pulse, shimmer, sparkle, wheel, } from "./renderables/effects.js";
+export { EFFECT_CATALOGUE, EFFECT_CURVES, EFFECT_LIGHTS, dissolveOut, fadeIn, onColors, pulse, shimmer, sparkle, wheel, } from "./renderables/effects.js";
 export { Align } from "./renderables/align.js";
 export { Padding } from "./renderables/padding.js";
 export { Viewport, ViewportPerKey, SCROLLBAR } from "./renderables/viewport.js";

package/dist/renderables/effect.d.ts

@@ -2,16 +2,21 @@
  * Effected — a renderable whose finished cells' colours pass through an
  * effect at a moment `t`.
  *
- * An effect is one pure function: a cell's colours, where the cell is, a time,
- * and what the element draws in that frame in, the cell's new colours out.
- * Shimmer, pulse, fade and dissolve are all this one shape, differing by what
- * the function does with its inputs [LAW:one-type-per-behavior]; two effects
- * stack by nesting one wrapper in another, which is the same as calling one
- * after the other but for what the outer one measures: the inner one's output.
+ * An effect is one pure function in two stages: a time and what the element
+ * draws in that frame in, a function of the frame out; and into that, a
+ * cell's colours and where the cell is, the cell's new colours out. Whatever
+ * holds for the whole frame is worked out in the first stage, once, and every
+ * cell of the frame is handed to the second, but for those a wrapper keeps
+ * back: `confined` hands over only the cells its owners drew, so a second
+ * stage never counts on seeing them all. Shimmer, pulse, fade and
+ * dissolve are all this one shape, differing by what the function does with
+ * its inputs [LAW:one-type-per-behavior]; two effects stack by nesting one
+ * wrapper in another, which is the same as calling one after the other but
+ * for what the outer one measures: the inner one's output.
  *
  * What the element draws (`Drawn`) is measured here, in the render, off the
- * same reading of each segment its cells are drawn from, and handed to every
- * cell of the frame alike. It is what an effect keeping words legible is
+ * same reading of each segment its cells are drawn from, and handed to the
+ * effect's first stage, once a frame. It is what an effect keeping words legible is
  * settled against (`onColors`, `./effects.ts`), so no caller derives it a
  * second time from a render of its own.
  *
@@ -81,11 +86,19 @@ export interface EffectCell {
     readonly anchor: Anchor | undefined;
 }
 /**
- * A cell's ink and ground as the screen shows them, and which of the two are
- * the terminal's: what an `Effect` is handed for that cell.
+ * A cell's ink and ground as the screen shows them, which of the two are the
+ * terminal's, and whether its style swaps them (`reverse`): what an `Effect`
+ * is handed for that cell.
  */
 export interface Pair extends CellColors {
     readonly terminal: EffectCell["terminal"];
+    /**
+     * Whether the ink is written in the style's ground slot and the ground in
+     * its ink slot. Below truecolor the slot decides what a moved colour can
+     * land on: a slot set to `default` draws the terminal's foreground in one
+     * and its background in the other.
+     */
+    readonly reverse: boolean;
 }
 /**
  * The colours the element an effect wraps draws its words in, in one frame,
@@ -107,10 +120,13 @@ export interface Drawn {
     readonly theme: TerminalTheme;
 }
 /**
- * A cell's colours at time `t`, in seconds, in a frame whose element draws
- * `drawn`. Return `colors` to leave it be.
+ * The frame at time `t`, in seconds, whose element draws `drawn`: each cell's
+ * colours in that frame. Return `colors` to leave a cell be.
+ * [LAW:types-are-the-program] Per-frame work is the outer stage, so it runs
+ * once a frame by the shape of the call, never by a cache asking whether this
+ * cell's frame is the last one's.
  */
-export type Effect = (colors: CellColors, cell: EffectCell, t: number, drawn: Drawn) => CellColors;
+export type Effect = (t: number, drawn: Drawn) => (colors: CellColors, cell: EffectCell) => CellColors;
 export interface EffectedOptions {
     /** The moment to draw, in seconds. */
     readonly t: number;
@@ -138,31 +154,35 @@ export declare class Effected implements Renderable, Measurable {
         minimum: number;
         maximum: number;
     };
+    /**
+     * The colours the screen shows for `pair` once it is drawn moved to `to`,
+     * both as the screen shows them, at `depth` on `theme`: what an effect
+     * moving a pair's colours leaves its words reading in.
+     * [LAW:one-source-of-truth] Read through `movedSpecs`, the one writer a
+     * moved slot is written with.
+     */
+    static shows(pair: Pair, to: CellColors, depth: ColorDepth, theme: TerminalTheme): CellColors;
     /**
      * The specs that draw a cell's slot colours `to` where the segment drew
-     * `from` with `wire`: a slot the effect left alone keeps its written spec,
-     * and a moved one is laid on what is beneath it — the ground on
-     * `SURFACE_BLACK`, the glyph on that ground, as the writer lays any
-     * translucent colour (`Style.drawnColors`) — then drawn in the colour nearest it at `depth`
-     * that the terminal shows (`ColorSpec.matchOn`). A move the depth cannot
-     * show is no move: where the written spec is as near the moved colour as
-     * that match, the slot keeps it, so below truecolor a colour moved a little
-     * off any colour it can write — a theme slot, the default colour, the cube —
-     * is still drawn as that one.
+     * `from` with `wire`: each moved slot in the spec `movedSpecs` writes it
+     * in, the rest as `wire` wrote them.
      */
     private respec;
     /** A cell's seed: FNV-1a of the key and the position, scaled into [0, 1). */
     private seed;
 }
 /**
- * `effect` on the colours `owner` drew, itself or through an owner nested in
- * its output, and every other colour left as it is: one item of a strip whose
- * items share a fill, one widget of a screen. A seam cell shows its two
- * neighbours side by side, a powerline arrow in the fill it points out of
- * over the fill it points into, so each side moves with its own item
- * (`colorsOwnedBy`, `../core/strip.ts`).
+ * `effect` on the colours any of `owners` drew, itself or through an owner
+ * nested in its output, and every other colour left as it is: one item of a
+ * strip whose items share a fill, the items of a row one other item stands
+ * apart from, one widget of a screen. A seam cell shows its two neighbours
+ * side by side, a powerline arrow in the fill it points out of over the fill
+ * it points into, so each side moves with its own item (`colorsOwnedBy`,
+ * `../core/strip.ts`). A cell none of them drew is never handed to the
+ * effect, so confining one effect to many owners costs one call a cell, not
+ * one for each owner.
  */
-export declare function confined(effect: Effect, owner: object): Effect;
+export declare function confined(effect: Effect, ...owners: readonly object[]): Effect;
 /**
  * What `segments`, drawn at `depth` on `theme`, draw their words in, measured
  * as `Effected` measures its child for every frame. Measure an element's

package/dist/renderables/effect.js

@@ -2,16 +2,21 @@
  * Effected — a renderable whose finished cells' colours pass through an
  * effect at a moment `t`.
  *
- * An effect is one pure function: a cell's colours, where the cell is, a time,
- * and what the element draws in that frame in, the cell's new colours out.
- * Shimmer, pulse, fade and dissolve are all this one shape, differing by what
- * the function does with its inputs [LAW:one-type-per-behavior]; two effects
- * stack by nesting one wrapper in another, which is the same as calling one
- * after the other but for what the outer one measures: the inner one's output.
+ * An effect is one pure function in two stages: a time and what the element
+ * draws in that frame in, a function of the frame out; and into that, a
+ * cell's colours and where the cell is, the cell's new colours out. Whatever
+ * holds for the whole frame is worked out in the first stage, once, and every
+ * cell of the frame is handed to the second, but for those a wrapper keeps
+ * back: `confined` hands over only the cells its owners drew, so a second
+ * stage never counts on seeing them all. Shimmer, pulse, fade and
+ * dissolve are all this one shape, differing by what the function does with
+ * its inputs [LAW:one-type-per-behavior]; two effects stack by nesting one
+ * wrapper in another, which is the same as calling one after the other but
+ * for what the outer one measures: the inner one's output.
  *
  * What the element draws (`Drawn`) is measured here, in the render, off the
- * same reading of each segment its cells are drawn from, and handed to every
- * cell of the frame alike. It is what an effect keeping words legible is
+ * same reading of each segment its cells are drawn from, and handed to the
+ * effect's first stage, once a frame. It is what an effect keeping words legible is
  * settled against (`onColors`, `./effects.ts`), so no caller derives it a
  * second time from a render of its own.
  *
@@ -42,7 +47,7 @@
  */
 import { drawnBy, shiftAnchor } from "../core/anchor.js";
 import { cellLen, graphemes } from "../core/cells.js";
-import { ColorDepth, ColorSpec, SURFACE_BLACK, rgbDistance } from "../core/color.js";
+import { ColorDepth, ColorSpec, SURFACE_BLACK } from "../core/color.js";
 import { fnv1a } from "../core/fnv1a.js";
 import { Measurement } from "../core/measure.js";
 import { Segment } from "../core/segment.js";
@@ -75,7 +80,7 @@ export class Effected {
         // [LAW:one-source-of-truth] The frame is measured before any cell is
         // handed to the effect, off the same looks its cells are drawn from.
         const looked = looks(segments, depth, this.theme);
-        const drawn = measured(looked, depth, this.theme);
+        const frame = this.effect(this.t, measured(looked, depth, this.theme));
         let row = 0;
         let col = 0;
         for (const { segment, look } of looked) {
@@ -102,7 +107,7 @@ export class Effected {
                 else {
                     const anchor = base.anchor && shiftAnchor(base.anchor, into);
                     // Back from the screen to the style's slots: the same swap undoes itself.
-                    colors = onScreen(this.effect(from, { row, col, seed: this.seed(row, col), terminal, anchor }, this.t, drawn), base);
+                    colors = onScreen(frame(from, { row, col, seed: this.seed(row, col), terminal, anchor }), pair.reverse);
                     col += cellLen(glyph);
                 }
                 into += cellLen(glyph);
@@ -133,27 +138,26 @@ export class Effected {
     measure(options) {
         return Measurement.get(options, this.renderable);
     }
+    /**
+     * The colours the screen shows for `pair` once it is drawn moved to `to`,
+     * both as the screen shows them, at `depth` on `theme`: what an effect
+     * moving a pair's colours leaves its words reading in.
+     * [LAW:one-source-of-truth] Read through `movedSpecs`, the one writer a
+     * moved slot is written with.
+     */
+    static shows(pair, to, depth, theme) {
+        const from = onScreen(pair, pair.reverse);
+        const moved = movedSpecs(from, onScreen(to, pair.reverse), depth, theme);
+        return onScreen({ fg: moved.fg?.getTruecolor(theme, true) ?? from.fg, bg: moved.bg?.getTruecolor(theme, false) ?? from.bg }, pair.reverse);
+    }
     /**
      * The specs that draw a cell's slot colours `to` where the segment drew
-     * `from` with `wire`: a slot the effect left alone keeps its written spec,
-     * and a moved one is laid on what is beneath it — the ground on
-     * `SURFACE_BLACK`, the glyph on that ground, as the writer lays any
-     * translucent colour (`Style.drawnColors`) — then drawn in the colour nearest it at `depth`
-     * that the terminal shows (`ColorSpec.matchOn`). A move the depth cannot
-     * show is no move: where the written spec is as near the moved colour as
-     * that match, the slot keeps it, so below truecolor a colour moved a little
-     * off any colour it can write — a theme slot, the default colour, the cube —
-     * is still drawn as that one.
+     * `from` with `wire`: each moved slot in the spec `movedSpecs` writes it
+     * in, the rest as `wire` wrote them.
      */
     respec(wire, from, to, depth) {
-        // [LAW:one-source-of-truth] The writer's surface, so one translucent colour draws one way in a frame.
-        const ground = to.bg.compositeOver(SURFACE_BLACK);
-        const glyph = to.fg.compositeOver(ground);
-        const drawn = (spec, was, now, foreground) => {
-            const match = ColorSpec.matchOn(now, depth, this.theme, foreground);
-            return rgbDistance(was, now) <= rgbDistance(match.getTruecolor(this.theme, foreground), now) ? spec : match;
-        };
-        return { color: drawn(wire.color, from.fg, glyph, true), bgcolor: drawn(wire.bgcolor, from.bg, ground, false) };
+        const moved = movedSpecs(from, to, depth, this.theme);
+        return { color: moved.fg ?? wire.color, bgcolor: moved.bg ?? wire.bgcolor };
     }
     /** A cell's seed: FNV-1a of the key and the position, scaled into [0, 1). */
     seed(row, col) {
@@ -169,31 +173,41 @@ function looks(segments, depth, theme) {
         const style = segment.style ?? Style.null();
         const wire = style.drawnColors(depth);
         const slots = { fg: (wire.color ?? DEFAULT).getTruecolor(theme, true), bg: (wire.bgcolor ?? DEFAULT).getTruecolor(theme, false) };
-        const terminal = onScreen({ fg: wire.color?.isDefault ?? true, bg: wire.bgcolor?.isDefault ?? true }, style);
-        return { segment, look: { style, wire, slots, pair: { ...onScreen(slots, style), terminal } } };
+        const reverse = style.reverse === true;
+        const terminal = onScreen({ fg: wire.color?.isDefault ?? true, bg: wire.bgcolor?.isDefault ?? true }, reverse);
+        return { segment, look: { style, wire, slots, pair: { ...onScreen(slots, reverse), terminal, reverse } } };
     });
 }
 /** What `looked` draws its words in: `Drawn`'s measure, taken once per frame. */
 function measured(looked, depth, theme) {
     const words = looked.flatMap(({ segment, look }) => (look !== undefined && segment.text.trim() !== "" && !drawnBy(look.style.anchor, JOIN) ? [look.pair] : []));
-    const pairs = [...new Map(words.map((pair) => [`${pair.fg.hex}/${pair.bg.hex}/${pair.terminal.fg}/${pair.terminal.bg}`, pair])).values()];
+    const pairs = [...new Map(words.map((pair) => [`${pair.fg.hex}/${pair.bg.hex}/${pair.terminal.fg}/${pair.terminal.bg}/${pair.reverse}`, pair])).values()];
     // [LAW:one-source-of-truth] A slot the terminal fills is no colour of the element's, whatever its hex.
     const own = (slot) => pairs.flatMap((pair) => (pair.terminal[slot] ? [] : [pair[slot].hex]));
     return { pairs, colors: new Set([...own("fg"), ...own("bg")]), fills: new Set(own("bg")), depth, theme };
 }
 /**
- * `effect` on the colours `owner` drew, itself or through an owner nested in
- * its output, and every other colour left as it is: one item of a strip whose
- * items share a fill, one widget of a screen. A seam cell shows its two
- * neighbours side by side, a powerline arrow in the fill it points out of
- * over the fill it points into, so each side moves with its own item
- * (`colorsOwnedBy`, `../core/strip.ts`).
+ * `effect` on the colours any of `owners` drew, itself or through an owner
+ * nested in its output, and every other colour left as it is: one item of a
+ * strip whose items share a fill, the items of a row one other item stands
+ * apart from, one widget of a screen. A seam cell shows its two neighbours
+ * side by side, a powerline arrow in the fill it points out of over the fill
+ * it points into, so each side moves with its own item (`colorsOwnedBy`,
+ * `../core/strip.ts`). A cell none of them drew is never handed to the
+ * effect, so confining one effect to many owners costs one call a cell, not
+ * one for each owner.
  */
-export function confined(effect, owner) {
-    return (colors, cell, t, drawn) => {
-        const owned = colorsOwnedBy(cell.anchor, owner);
-        const moved = effect(colors, cell, t, drawn);
-        return { fg: owned.fg ? moved.fg : colors.fg, bg: owned.bg ? moved.bg : colors.bg };
+export function confined(effect, ...owners) {
+    const confinedTo = new Set(owners);
+    return (t, drawn) => {
+        const frame = effect(t, drawn);
+        return (colors, cell) => {
+            const owned = colorsOwnedBy(cell.anchor, confinedTo);
+            if (!owned.fg && !owned.bg)
+                return colors;
+            const moved = frame(colors, cell);
+            return { fg: owned.fg ? moved.fg : colors.fg, bg: owned.bg ? moved.bg : colors.bg };
+        };
     };
 }
 /**
@@ -208,8 +222,22 @@ export function drawnOf(segments, depth, theme) {
  * A style's colour slots as the screen shows them, or the reverse: `reverse`
  * swaps glyph and ground, and swapping twice is where you started.
  */
-function onScreen(slots, style) {
-    return style.reverse === true ? { fg: slots.bg, bg: slots.fg } : slots;
+function onScreen(slots, reverse) {
+    return reverse ? { fg: slots.bg, bg: slots.fg } : slots;
+}
+/**
+ * The specs a cell's slots are written in once their colours move from
+ * `from`, what the written specs draw, to `to`: each laid on what is beneath
+ * it — the ground on `SURFACE_BLACK`, the glyph on that ground, as the writer
+ * lays any translucent colour (`Style.drawnColors`) — then matched at `depth`
+ * (`ColorSpec.matchMove`). A slot the depth shows no move in has none, and
+ * keeps the spec it was written in.
+ */
+function movedSpecs(from, to, depth, theme) {
+    // [LAW:one-source-of-truth] The writer's surface, so one translucent colour draws one way in a frame.
+    const ground = to.bg.compositeOver(SURFACE_BLACK);
+    const glyph = to.fg.compositeOver(ground);
+    return { fg: ColorSpec.matchMove(from.fg, glyph, depth, theme, true), bg: ColorSpec.matchMove(from.bg, ground, depth, theme, false) };
 }
 /**
  * Whether two cells' colours are written alike. A slot with no colour is not

package/dist/renderables/effects.d.ts

@@ -3,7 +3,8 @@
  * long as they are drawn, and fade-in and dissolve-out, which run once and
  * are done. Each is an `Effect` for `Effected` (`./effect.ts`); the defaults
  * in `EFFECT_CURVES` are the ones signed off by eye in the effects-feel demo
- * (`npm run effects-feel`), at 30 fps and at one frame a second.
+ * (`npm run effects-feel`), at 30 fps and at one frame a second, and
+ * `EFFECT_CATALOGUE` makes every one of them at those, by name, one way.
  *
  * Each effect is something a first-time observer already knows from life —
  * a slow glow, sunlight moving on water, the colours of daylight, fireflies, ink
@@ -43,11 +44,15 @@
  */
 import { ColorRgba } from "../core/color.js";
 import { type Ease } from "../core/easing.js";
-import type { Drawn, Effect, EffectCell, Pair } from "./effect.js";
+import { type Drawn, type Effect, type EffectCell } from "./effect.js";
 /** What a loop does to one colour at strength `w` in [0, 1]: at 0, nothing. */
 export type Touch = (color: ColorRgba, w: number) => ColorRgba;
-/** How strongly a loop acts on a cell at a moment, in [0, 1]; `onColors` holds a field outside it to it. */
-export type Field = (cell: EffectCell, t: number) => number;
+/**
+ * How strongly a loop acts at a moment `t` on each cell, in [0, 1]; `onColors`
+ * holds a field outside it to it. Staged as `Effect` is: what holds for the
+ * whole moment is worked out once, then every cell is asked.
+ */
+export type Field = (t: number) => (cell: EffectCell) => number;
 /** A looping effect: what it does to a colour, and where and when, how strongly. */
 export interface Loop {
     readonly touch: Touch;
@@ -55,9 +60,10 @@ export interface Loop {
 }
 /**
  * How much of `touch` each of `colors` (hex) can take: the largest share in
- * [0, 1] at which every pair in `pairs` that shows it, touched at the same
+ * [0, 1] at which every pair `drawn` shows it in, touched at the same
  * strength, still reads at its resting contrast or `LEGIBLE`, whichever is
- * lower. A colour in a pair but not in `colors` takes none, and so does one
+ * lower, in the colours `Effected` writes it in at `drawn`'s depth and theme.
+ * A colour in a pair but not in `colors` takes none, and so does one
  * the terminal supplies, whatever its hex, as in `onColors`. One of `colors`
  * no pair writes has nothing to be measured against, and takes it all.
  *
@@ -68,14 +74,14 @@ export interface Loop {
  * the fill room to glow — and a darker colour left as it is always holds,
  * because its lighter partner was settled against exactly that.
  */
-export declare function shares(pairs: readonly Pair[], colors: ReadonlySet<string>, touch: Touch): Map<string, number>;
+export declare function shares({ pairs, depth, theme }: Drawn, colors: ReadonlySet<string>, touch: Touch): Map<string, number>;
 /**
  * A loop as an `Effect` on the element's own colours, by hex, wherever a cell
  * shows them, each touched at its share of the cell's strength: the share
  * `shares` settles for it against the pairs the element draws its words in
- * (`Drawn`), touched as the frame's depth writes them — at 256 colours a
- * touched colour lands on the cube, and the contrast it spends is the cube
- * colour's. `colors` are the ones lit, by default every colour the element
+ * (`Drawn`), touched as `Effected` writes them at the frame's depth — below
+ * truecolor a touched colour lands on a colour the slot can write, and the
+ * contrast it spends is that colour's. `colors` are the ones lit, by default every colour the element
  * sets itself. A powerline strip's fill is the ground of its cells and the
  * ink of the seam glyphs between them, so the arrow moves with the cell it
  * points out of. A colour the terminal supplies (`EffectCell.terminal`) is
@@ -199,46 +205,46 @@ export declare function shimmer(curve: Curve, span: number, width: number, glow:
  */
 export declare function sparkle(curve: Curve, span: number, glow: ColorRgba, z: number): Loop;
 /**
- * How much of a cell shows at `t`: 1 is the cell as drawn, 0 is the cell gone
- * to the terminal's ground. Read per cell, so cells can arrive or leave apart. One
- * outside [0, 1] is held to it.
+ * How much of each cell shows at `t`: 1 is the cell as drawn, 0 is the cell
+ * gone to the terminal's ground. Read per cell, so cells can arrive or leave
+ * apart, and staged as `Field` is. One outside [0, 1] is held to it.
  */
-export type Visibility = (cell: EffectCell, t: number) => number;
+export type Visibility = (t: number) => (cell: EffectCell) => number;
 /**
- * A cell mixed toward the terminal's `ground` by how hidden it is: its fill
- * toward the ground, and its ink toward that fill, so an element with fills
- * of its own — a powerline strip — arrives and leaves whole, fill and words
- * together, never as bare coloured blocks. Invisible is ink and fill equal
- * to the ground. `swing` scales the hiding — 1 reaches fully invisible. A
- * cell wholly shown is returned as it was.
+ * A cell mixed toward the ground of the terminal the frame is drawn on
+ * (`Drawn.theme`) by how hidden it is: its fill toward the ground, and its ink
+ * toward that fill, so an element with fills of its own — a powerline strip —
+ * arrives and leaves whole, fill and words together, never as bare coloured
+ * blocks. Invisible is ink and fill equal to the ground. `swing` scales the
+ * hiding — 1 reaches fully invisible. A cell wholly shown is returned as it was.
  */
-export declare function veiled(visibility: Visibility, swing: number, ground: ColorRgba): Effect;
+export declare function veiled(visibility: Visibility, swing: number): Effect;
 /**
- * An effect that runs once: a fade-in or a dissolve-out from its start time
- * over its curve's `seconds`. `done(t)` is true from the moment every cell
- * has arrived or gone, so the caller knows when to stop drawing an element
- * that is leaving, or to drop the effect from one that has arrived.
+ * An effect that runs once: a fade-in or a dissolve-out over its curve's
+ * `seconds` from `t = 0`, its own clock as every effect's is — the caller
+ * draws it at the time since it began. `done(t)` is true from the moment
+ * every cell has arrived or gone, so the caller knows when to stop drawing an
+ * element that is leaving, or to drop the effect from one that has arrived.
  */
 export interface Transition {
     readonly effect: Effect;
     done(t: number): boolean;
 }
 /**
- * Fade-in starting at `start`, as ink blooming in water: patches of the
- * element surface first and the rest follows outward from them, each cell
- * rising smoothly over its own part of the duration. Whole at
- * `start + seconds`.
+ * Fade-in, as ink blooming in water: patches of the element surface first
+ * and the rest follows outward from them, each cell rising smoothly over its
+ * own part of the duration. Whole at `seconds`.
  */
-export declare function fadeIn(curve: Curve, start: number, z: number, ground: ColorRgba): Transition;
+export declare function fadeIn(curve: Curve, z: number): Transition;
 /**
- * Dissolve-out starting at `start`, as mist lifting: the element thins in
- * drifting patches, each cell fading smoothly over its own part of the
- * duration, until nothing is left at `start + seconds`. Mist does not lift
+ * Dissolve-out, as mist lifting: the element thins in drifting patches, each
+ * cell fading smoothly over its own part of the duration, until nothing is
+ * left at `seconds`. Mist does not lift
  * in one breath: towards the end, patches of what is left — the later a cell
  * goes, the likelier — rise back part way, as the last of it eddies, before
  * they thin away for good.
  */
-export declare function dissolveOut(curve: Curve, start: number, z: number, ground: ColorRgba): Transition;
+export declare function dissolveOut(curve: Curve, z: number): Transition;
 /**
  * Wheel, as the colour of daylight going round: every hue turning the whole
  * way round once a period — far too slowly to be seen moving, so a glance
@@ -258,3 +264,32 @@ export declare function dissolveOut(curve: Curve, start: number, z: number, grou
  * terminal's.
  */
 export declare function wheel(curve: Curve, z: number): Effect;
+/**
+ * What a catalogue effect is made for: the element it is drawn on, as wide as
+ * `span` columns — how far a shimmer crosses, how many fireflies keep to it —
+ * and at `z` in the noise, so two elements under one effect do not move in
+ * lockstep.
+ */
+export interface EffectTarget {
+    readonly span: number;
+    readonly z: number;
+}
+/** The names of the effects that loop. */
+export type LoopName = "shimmer" | "pulse" | "sparkle" | "wheel";
+/** The names of the effects that run once. */
+export type TransitionName = "fade" | "dissolve";
+/**
+ * Every effect in the catalogue by its name in `EFFECT_CURVES`, each made the
+ * one way: for an element, at its signed-off curve unless handed another,
+ * with the light and the width it was signed off with. A loop comes lit on
+ * the element's own colours (`onColors`); a transition comes as itself, to
+ * be told when it is done. [LAW:types-are-the-program] Keyed by the two
+ * name types, which `EFFECT_CURVES` is held to as well: a curve signed off
+ * does not compile until it is named a loop or a transition, and then not
+ * until it has an entry here making one. A picker walking a section's names
+ * offers an effect added here with no change of its own.
+ */
+export declare const EFFECT_CATALOGUE: {
+    readonly loops: Readonly<Record<LoopName, (element: EffectTarget, curve?: Curve) => Effect>>;
+    readonly transitions: Readonly<Record<TransitionName, (element: EffectTarget, curve?: Curve) => Transition>>;
+};

package/dist/renderables/effects.js

@@ -3,7 +3,8 @@
  * long as they are drawn, and fade-in and dissolve-out, which run once and
  * are done. Each is an `Effect` for `Effected` (`./effect.ts`); the defaults
  * in `EFFECT_CURVES` are the ones signed off by eye in the effects-feel demo
- * (`npm run effects-feel`), at 30 fps and at one frame a second.
+ * (`npm run effects-feel`), at 30 fps and at one frame a second, and
+ * `EFFECT_CATALOGUE` makes every one of them at those, by name, one way.
  *
  * Each effect is something a first-time observer already knows from life —
  * a slow glow, sunlight moving on water, the colours of daylight, fireflies, ink
@@ -41,11 +42,12 @@
  * cards runs this file's own declarations as the program a visitor edits
  * (`examples/effects-playground/programs.ts`), on the published library.
  */
-import { ColorRgba, ColorSpec, contrastRatio } from "../core/color.js";
+import { ColorDepth, ColorRgba, contrastRatio } from "../core/color.js";
 import { EASES, Phase } from "../core/easing.js";
 import { fbm, hash, noise, smoothstep } from "../core/noise.js";
 import { Memo } from "../core/memo.js";
 import { IDENTITY, Oklch } from "../core/oklch.js";
+import { Effected } from "./effect.js";
 /** The contrast no touch takes a cell below, unless it rested below it: WCAG AA for body text. */
 const LEGIBLE = 4.5;
 /**
@@ -59,11 +61,13 @@ const LEVELS = 48;
 const STRENGTHS = Array.from({ length: LEVELS }, (_, i) => (i + 1) / LEVELS);
 /** What 8-bit rounding of an OKLCH round trip can cost a contrast ratio. */
 const ROUNDING = 0.01;
+const SIDES = ["fg", "bg"];
 /**
  * How much of `touch` each of `colors` (hex) can take: the largest share in
- * [0, 1] at which every pair in `pairs` that shows it, touched at the same
+ * [0, 1] at which every pair `drawn` shows it in, touched at the same
  * strength, still reads at its resting contrast or `LEGIBLE`, whichever is
- * lower. A colour in a pair but not in `colors` takes none, and so does one
+ * lower, in the colours `Effected` writes it in at `drawn`'s depth and theme.
+ * A colour in a pair but not in `colors` takes none, and so does one
  * the terminal supplies, whatever its hex, as in `onColors`. One of `colors`
  * no pair writes has nothing to be measured against, and takes it all.
  *
@@ -74,28 +78,38 @@ const ROUNDING = 0.01;
  * the fill room to glow — and a darker colour left as it is always holds,
  * because its lighter partner was settled against exactly that.
  */
-export function shares(pairs, colors, touch) {
+export function shares({ pairs, depth, theme }, colors, touch) {
     // [LAW:one-source-of-truth] A slot shows a subject colour, by hex, only
     // where the element writes it: the reading `onColors` lights by.
-    const sides = pairs.map(({ fg, bg, terminal }) => [
-        { color: fg, own: terminal.fg ? undefined : fg.hex },
-        { color: bg, own: terminal.bg ? undefined : bg.hex },
-    ]);
-    const rgba = new Map(sides.flat().flatMap(({ color, own }) => (own === undefined ? [] : [[own, color]])));
+    const own = (pair, side) => (pair.terminal[side] ? undefined : pair[side].hex);
+    const rgba = new Map(pairs.flatMap((pair) => SIDES.flatMap((side) => {
+        const hex = own(pair, side);
+        return hex === undefined ? [] : [[hex, pair[side]]];
+    })));
+    // Below truecolor every colour written is one the depth holds exactly, so only truecolor's rounding has a cost to forgive.
+    const slack = depth === ColorDepth.TRUECOLOR ? ROUNDING : 0;
     // A colour no pair writes keeps no word legible, so nothing bounds its share:
     // a frame drawing a lit colour only under blanks and seams, or not at all,
     // is a frame like any other.
     const settled = new Map([...colors].filter((hex) => !rgba.has(hex)).map((hex) => [hex, 1]));
     const lightness = (hex) => Oklch.fromRgba(rgba.get(hex)).l;
     for (const hex of [...colors].filter((hex) => rgba.has(hex)).sort((a, b) => lightness(b) - lightness(a))) {
-        const partners = sides.flatMap(([fg, bg]) => {
-            const partner = fg.own === hex ? bg : bg.own === hex ? fg : undefined;
-            return partner === undefined ? [] : [[partner.color, partner.own === undefined ? 0 : (settled.get(partner.own) ?? 0)]];
+        // Each pair showing the colour, with the side it shows it on and the share its partner takes.
+        const facing = pairs.flatMap((pair) => {
+            const mine = SIDES.find((side) => own(pair, side) === hex);
+            if (mine === undefined)
+                return [];
+            const partner = own(pair, mine === "fg" ? "bg" : "fg");
+            return [[pair, mine, partner === undefined ? 0 : (settled.get(partner) ?? 0)]];
         });
-        const color = rgba.get(hex);
-        const holds = (share) => partners.every(([partner, theirs]) => {
-            const floor = Math.min(contrastRatio(color, partner), LEGIBLE);
-            return STRENGTHS.every((w) => contrastRatio(touchedAt(touch, color, share * w), touchedAt(touch, partner, theirs * w)) >= floor - ROUNDING);
+        // [LAW:one-source-of-truth] A pair reads in the colours `Effected` writes it in, touched at each side's share.
+        const holds = (share) => facing.every(([pair, mine, theirs]) => {
+            const floor = Math.min(contrastRatio(pair.fg, pair.bg), LEGIBLE) - slack;
+            const at = (side, w) => touchedAt(touch, pair[side], (side === mine ? share : theirs) * w);
+            return STRENGTHS.every((w) => {
+                const shown = Effected.shows(pair, { fg: at("fg", w), bg: at("bg", w) }, depth, theme);
+                return contrastRatio(shown.fg, shown.bg) >= floor;
+            });
         });
         let [lo, hi] = holds(1) ? [1, 1] : [0, 1];
         for (let i = 0; i < 20 && hi - lo > 1e-3; i++) {
@@ -110,9 +124,9 @@ export function shares(pairs, colors, touch) {
  * A loop as an `Effect` on the element's own colours, by hex, wherever a cell
  * shows them, each touched at its share of the cell's strength: the share
  * `shares` settles for it against the pairs the element draws its words in
- * (`Drawn`), touched as the frame's depth writes them — at 256 colours a
- * touched colour lands on the cube, and the contrast it spends is the cube
- * colour's. `colors` are the ones lit, by default every colour the element
+ * (`Drawn`), touched as `Effected` writes them at the frame's depth — below
+ * truecolor a touched colour lands on a colour the slot can write, and the
+ * contrast it spends is that colour's. `colors` are the ones lit, by default every colour the element
  * sets itself. A powerline strip's fill is the ground of its cells and the
  * ink of the seam glyphs between them, so the arrow moves with the cell it
  * points out of. A colour the terminal supplies (`EffectCell.terminal`) is
@@ -126,11 +140,10 @@ export function onColors(loop, colors) {
     const settled = new WeakMap();
     const settle = (drawn) => {
         const lit = colors ?? drawn.colors;
-        const key = [drawn.depth, ...drawn.pairs.map(({ fg, bg, terminal }) => `${fg.hex}/${bg.hex}/${terminal.fg}/${terminal.bg}`), "|", ...lit].join(" ");
+        const key = [drawn.depth, ...drawn.pairs.map(({ fg, bg, terminal, reverse }) => `${fg.hex}/${bg.hex}/${terminal.fg}/${terminal.bg}/${reverse}`), "|", ...lit].join(" ");
         const memo = settled.get(drawn.theme) ?? new Memo();
         settled.set(drawn.theme, memo);
-        const asWritten = (color, w) => ColorSpec.fromRgba(loop.touch(color, w)).downgrade(drawn.depth).getTruecolor(drawn.theme);
-        return memo.get(key, () => shares(drawn.pairs, lit, asWritten));
+        return memo.get(key, () => shares(drawn, lit, loop.touch));
     };
     return atShares(loop, settle);
 }
@@ -140,14 +153,14 @@ export function onColors(loop, colors) {
  * says; a colour it gives none, and one the terminal supplies, stays as it is.
  */
 export function atShares(loop, share) {
-    // Every cell of a frame is handed the same `Drawn`, so its shares are looked up once a frame.
-    let frame = { drawn: undefined, share: new Map() };
-    return ({ fg, bg }, cell, t, drawn) => {
-        if (frame.drawn !== drawn)
-            frame = { drawn, share: share(drawn) };
-        const w = Math.round(clamp01(loop.field(cell, t)) * LEVELS) / LEVELS;
-        const moved = (color, terminal) => touchedAt(loop.touch, color, (terminal ? 0 : (frame.share.get(color.hex) ?? 0)) * w);
-        return { fg: moved(fg, cell.terminal.fg), bg: moved(bg, cell.terminal.bg) };
+    return (t, drawn) => {
+        const shared = share(drawn);
+        const field = loop.field(t);
+        return ({ fg, bg }, cell) => {
+            const w = Math.round(clamp01(field(cell)) * LEVELS) / LEVELS;
+            const moved = (color, terminal) => touchedAt(loop.touch, color, (terminal ? 0 : (shared.get(color.hex) ?? 0)) * w);
+            return { fg: moved(fg, cell.terminal.fg), bg: moved(bg, cell.terminal.bg) };
+        };
     };
 }
 /**
@@ -276,14 +289,15 @@ export function pulse(curve, glow, z) {
     const WANDER = 0.1;
     const wander = (t) => WANDER * noise(t / (3 * curve.seconds), 0.5, 0.5 + z);
     const start = wander(0);
-    const field = (_cell, t) => {
+    const field = (t) => {
         const beats = (rate * t) / curve.seconds + wander(t) - start;
         const n = Math.floor(beats);
         // Each beat's own depth, 70% to the whole of the swing; it changes where
         // the beat is at rest, so nothing jumps.
         const depth = 0.7 + 0.3 * smoothstep(-0.5, 0.5, noise(n * 0.37, 2.1, z));
         const beat = 0.5 - 0.5 * Math.cos(2 * Math.PI * (beats - n));
-        return curve.swing * curve.ease(depth * beat);
+        const level = curve.swing * curve.ease(depth * beat);
+        return () => level;
     };
     return { touch: light(glow), field };
 }
@@ -343,35 +357,31 @@ export function shimmer(curve, span, width, glow, z) {
         const centre = q * across - width + 0.06 * across * Math.sin(Math.PI * q) * noise(q, 2.7, j + z);
         return { strength, centre };
     };
-    // The passes on the row at one moment: a frame asks for the same moment
-    // once per cell, so they are worked out once per moment.
-    let passing = { t: Number.NaN, passes: [] };
-    // Where two passes overlap the brighter wins, so light never doubles up;
-    // the first slot is 0, so before it nothing is lit.
-    const band = (col, t) => {
-        if (passing.t !== t) {
-            const last = Math.floor(t / SLOT);
-            const passes = [];
-            for (let j = Math.max(0, Math.ceil(last - UP)); j <= last; j++)
-                passes.push(pass(j, t));
-            passing = { t, passes };
-        }
-        let lit = 0;
-        for (const { strength, centre } of passing.passes)
-            lit = Math.max(lit, strength * bump((col - centre) / width));
-        return lit;
+    // The passes on the row at `t`; the first slot is 0, so before it there are none.
+    const passing = (t) => {
+        const last = Math.floor(t / SLOT);
+        const passes = [];
+        for (let j = Math.max(0, Math.ceil(last - UP)); j <= last; j++)
+            passes.push(pass(j, t));
+        return passes;
     };
     // A ripple's crest: a Gaussian ridge, 1 where the field crosses zero and in
     // (0, 1] for any noise, smooth throughout, so a crest sliding through a cell
     // lights it smoothly.
     const ripple = (a, b, c) => Math.exp(-((noise(a, b, c) / 0.8) ** 2));
-    const field = (cell, t) => {
-        const lit = band(cell.col, t);
-        const row = cell.row + z;
-        const current = 0.8 * noise(cell.col * 0.05, row * 0.3 + 1.3, t * 0.02);
-        const caustic = (ripple(cell.col * 0.21 + current, row * 0.9, t * 0.022) * ripple(cell.col * 0.33 + 9.1 - current, row * 0.7, t * 0.018 + 4.2)) **
-            2;
-        return curve.swing * curve.ease(lit * (0.1 + 0.6 * caustic));
+    const field = (t) => {
+        const passes = passing(t);
+        return (cell) => {
+            // Where two passes overlap the brighter wins, so light never doubles up.
+            let lit = 0;
+            for (const { strength, centre } of passes)
+                lit = Math.max(lit, strength * bump((cell.col - centre) / width));
+            const row = cell.row + z;
+            const current = 0.8 * noise(cell.col * 0.05, row * 0.3 + 1.3, t * 0.02);
+            const caustic = (ripple(cell.col * 0.21 + current, row * 0.9, t * 0.022) * ripple(cell.col * 0.33 + 9.1 - current, row * 0.7, t * 0.018 + 4.2)) **
+                2;
+            return curve.swing * curve.ease(lit * (0.1 + 0.6 * caustic));
+        };
     };
     return { touch: light(glow), field };
 }
@@ -403,67 +413,64 @@ export function sparkle(curve, span, glow, z) {
         // Out of step with every other firefly from the first moment.
         offset: hash(i, 0.7 + z) * TURN,
     }));
-    // Where every firefly is and how bright at one moment: a frame asks for
-    // the same moment once per cell, so it is worked out once per moment.
-    let flown = { t: Number.NaN, flies: [] };
-    const fliesAt = (t) => {
-        if (flown.t !== t) {
-            flown = {
-                t,
-                flies: homes.map((fly) => {
-                    // Flash `n` is one event: whether it comes, how bright, when in
-                    // its turn and where are its own. Between flashes the firefly
-                    // is dark, so where it moves to is never seen moving.
-                    const u = t + fly.offset;
-                    const n = Math.floor(u / TURN);
-                    // A dark turn is a flash with no light: it keeps its length, so
-                    // every flash is timed alike.
-                    const lit = hash(n, fly.z + 1) < 0.15 ? 0 : 1;
-                    const k = 0.5 + 0.5 * hash(n, fly.z + 2);
-                    const at = hash(n, fly.z + 3) * (1 - lasts(FLASH, k));
-                    const s = u / TURN - n - at;
-                    // While it glows it drifts a few cells one way or the other, as
-                    // fast as it is bright: quickest at its height, slowing as it
-                    // fades — the lit stroke a firefly draws on the dusk. A brighter
-                    // flash lasts longer and draws a longer stroke at the same pace.
-                    return {
-                        x: fly.home +
-                            HOP * (2 * hash(n, fly.z + 4) - 1) +
-                            GLIDE * k * (2 * hash(n, fly.z + 5) - 1) * given(FLASH, s, k) +
-                            1.5 * noise(fly.z, 0.1, t * 0.035),
-                        y: 0.6 * noise(fly.z, 2.2, t * 0.035),
-                        glow: lit * swell(FLASH, s, k),
-                    };
-                }),
-            };
-        }
-        return flown.flies;
-    };
-    const field = (cell, t) => {
-        // Where two halos overlap the brighter wins, so light never doubles up.
-        let shine = 0;
-        for (const fly of fliesAt(t))
-            shine = Math.max(shine, fly.glow * bump(Math.hypot(cell.col - fly.x, 2 * (cell.row - fly.y)) / HALO));
-        return curve.swing * curve.ease(shine);
+    // Where every firefly is at `t`, and how bright.
+    const fliesAt = (t) => homes.map((fly) => {
+        // Flash `n` is one event: whether it comes, how bright, when in
+        // its turn and where are its own. Between flashes the firefly
+        // is dark, so where it moves to is never seen moving.
+        const u = t + fly.offset;
+        const n = Math.floor(u / TURN);
+        // A dark turn is a flash with no light: it keeps its length, so
+        // every flash is timed alike.
+        const lit = hash(n, fly.z + 1) < 0.15 ? 0 : 1;
+        const k = 0.5 + 0.5 * hash(n, fly.z + 2);
+        const at = hash(n, fly.z + 3) * (1 - lasts(FLASH, k));
+        const s = u / TURN - n - at;
+        // While it glows it drifts a few cells one way or the other, as
+        // fast as it is bright: quickest at its height, slowing as it
+        // fades — the lit stroke a firefly draws on the dusk. A brighter
+        // flash lasts longer and draws a longer stroke at the same pace.
+        return {
+            x: fly.home +
+                HOP * (2 * hash(n, fly.z + 4) - 1) +
+                GLIDE * k * (2 * hash(n, fly.z + 5) - 1) * given(FLASH, s, k) +
+                1.5 * noise(fly.z, 0.1, t * 0.035),
+            y: 0.6 * noise(fly.z, 2.2, t * 0.035),
+            glow: lit * swell(FLASH, s, k),
+        };
+    });
+    const field = (t) => {
+        const flies = fliesAt(t);
+        return (cell) => {
+            // Where two halos overlap the brighter wins, so light never doubles up.
+            let shine = 0;
+            for (const fly of flies)
+                shine = Math.max(shine, fly.glow * bump(Math.hypot(cell.col - fly.x, 2 * (cell.row - fly.y)) / HALO));
+            return curve.swing * curve.ease(shine);
+        };
     };
     return { touch: light(glow), field };
 }
 /**
- * A cell mixed toward the terminal's `ground` by how hidden it is: its fill
- * toward the ground, and its ink toward that fill, so an element with fills
- * of its own — a powerline strip — arrives and leaves whole, fill and words
- * together, never as bare coloured blocks. Invisible is ink and fill equal
- * to the ground. `swing` scales the hiding — 1 reaches fully invisible. A
- * cell wholly shown is returned as it was.
+ * A cell mixed toward the ground of the terminal the frame is drawn on
+ * (`Drawn.theme`) by how hidden it is: its fill toward the ground, and its ink
+ * toward that fill, so an element with fills of its own — a powerline strip —
+ * arrives and leaves whole, fill and words together, never as bare coloured
+ * blocks. Invisible is ink and fill equal to the ground. `swing` scales the
+ * hiding — 1 reaches fully invisible. A cell wholly shown is returned as it was.
  */
-export function veiled(visibility, swing, ground) {
-    const to = Oklch.fromRgba(ground);
-    return (colors, cell, t) => {
-        const hidden = swing * (1 - clamp01(visibility(cell, t)));
-        if (hidden === 0)
-            return colors;
-        const bg = blend(Oklch.fromRgba(colors.bg), to, hidden);
-        return { fg: blend(Oklch.fromRgba(colors.fg), bg, hidden).toRgba(), bg: bg.toRgba() };
+export function veiled(visibility, swing) {
+    return (t, { theme }) => {
+        const shows = visibility(t);
+        // [LAW:one-source-of-truth] The ground is the terminal `Effected` draws on, never a second one handed here.
+        const ground = Oklch.fromRgba(theme.backgroundColor);
+        return (colors, cell) => {
+            const hidden = swing * (1 - clamp01(shows(cell)));
+            if (hidden === 0)
+                return colors;
+            const bg = blend(Oklch.fromRgba(colors.bg), ground, hidden);
+            return { fg: blend(Oklch.fromRgba(colors.fg), bg, hidden).toRgba(), bg: bg.toRgba() };
+        };
     };
 }
 /**
@@ -484,9 +491,8 @@ function order(z) {
         return place;
     };
 }
-function transition(curve, start, effect) {
-    const end = start + curve.seconds;
-    return { effect, done: (t) => t >= end };
+function transition(curve, effect) {
+    return { effect, done: (t) => t >= curve.seconds };
 }
 /**
  * Of a transition's `seconds`, how long each cell's own change takes. Under
@@ -494,26 +500,28 @@ function transition(curve, start, effect) {
  */
 const OWN = 0.45;
 /**
- * Each cell's progress through its own change in a transition starting at
- * `start`, in [0, 1]: a cell `place` along the order starts that share of the
- * way through the time the others leave it, and takes `OWN` of `seconds`.
+ * Each cell's progress through its own change in a transition, in [0, 1]: a
+ * cell `place` along the order starts that share of the way through the time
+ * the others leave it, and takes `OWN` of `seconds`.
  */
-function ownChange(curve, start, place) {
+function ownChange(curve, place) {
     const own = curve.seconds * OWN;
     // One phase, shifted per cell, so no cell builds its own each frame.
-    const change = Phase.once(start, own);
-    return (cell, t) => change(t - place(cell) * (curve.seconds - own));
+    const change = Phase.once(0, own);
+    return (t) => (cell) => change(t - place(cell) * (curve.seconds - own));
 }
 /**
- * Fade-in starting at `start`, as ink blooming in water: patches of the
- * element surface first and the rest follows outward from them, each cell
- * rising smoothly over its own part of the duration. Whole at
- * `start + seconds`.
+ * Fade-in, as ink blooming in water: patches of the element surface first
+ * and the rest follows outward from them, each cell rising smoothly over its
+ * own part of the duration. Whole at `seconds`.
  */
-export function fadeIn(curve, start, z, ground) {
+export function fadeIn(curve, z) {
     requireCurve(curve);
-    const risen = ownChange(curve, start, order(1.7 + z));
-    return transition(curve, start, veiled((cell, t) => curve.ease(risen(cell, t)), curve.swing, ground));
+    const risen = ownChange(curve, order(1.7 + z));
+    return transition(curve, veiled((t) => {
+        const at = risen(t);
+        return (cell) => curve.ease(at(cell));
+    }, curve.swing));
 }
 /**
  * The rebound of a dissolve, every constant that makes it feel as it does —
@@ -526,25 +534,28 @@ export function fadeIn(curve, start, z, ground) {
  */
 const DISSOLVE_SHAPE = { depth: 0.4, from: 0.5, to: 0.95, maskFrom: 0.35, maskTo: 0.75, late: 0.6 };
 /**
- * Dissolve-out starting at `start`, as mist lifting: the element thins in
- * drifting patches, each cell fading smoothly over its own part of the
- * duration, until nothing is left at `start + seconds`. Mist does not lift
+ * Dissolve-out, as mist lifting: the element thins in drifting patches, each
+ * cell fading smoothly over its own part of the duration, until nothing is
+ * left at `seconds`. Mist does not lift
  * in one breath: towards the end, patches of what is left — the later a cell
  * goes, the likelier — rise back part way, as the last of it eddies, before
  * they thin away for good.
  */
-export function dissolveOut(curve, start, z, ground) {
+export function dissolveOut(curve, z) {
     requireCurve(curve);
     const place = order(4.2 + z);
     const eddy = order(9.3 + z);
-    const faded = ownChange(curve, start, place);
+    const faded = ownChange(curve, place);
     const { depth, from, to, maskFrom, maskTo, late } = DISSOLVE_SHAPE;
-    return transition(curve, start, veiled((cell, t) => {
-        const gone = curve.ease(faded(cell, t));
-        const q = clamp01((gone - from) / (to - from));
-        const back = depth * smoothstep(maskFrom, maskTo, eddy(cell)) * (1 - late + late * place(cell)) * Math.sin(Math.PI * q) ** 2;
-        return 1 - gone + back;
-    }, curve.swing, ground));
+    return transition(curve, veiled((t) => {
+        const at = faded(t);
+        return (cell) => {
+            const gone = curve.ease(at(cell));
+            const q = clamp01((gone - from) / (to - from));
+            const back = depth * smoothstep(maskFrom, maskTo, eddy(cell)) * (1 - late + late * place(cell)) * Math.sin(Math.PI * q) ** 2;
+            return 1 - gone + back;
+        };
+    }, curve.swing));
 }
 /**
  * The periods, in seconds, of the two noises a segment's stray from the
@@ -586,7 +597,7 @@ export function wheel(curve, z) {
         const s = seed(hex);
         return (360 * t) / P + curve.swing * STRAY * ((stray(s, t) - stray(s, 0)) / 1.5);
     };
-    return (shown, cell, t, { colors, fills }) => {
+    return (t, { colors, fills }) => (shown, cell) => {
         // Whether a slot shows one of the element's colours: never the terminal's, whatever its hex.
         const own = { fg: !cell.terminal.fg && colors.has(shown.fg.hex), bg: !cell.terminal.bg && colors.has(shown.bg.hex) };
         // An own colour turns with its segment: itself if a fill or beside no own colour, else the one beside it.
@@ -594,3 +605,26 @@ export function wheel(curve, z) {
         return { fg: turn(shown.fg, own.fg, shown.bg, own.bg), bg: turn(shown.bg, own.bg, shown.fg, own.fg) };
     };
 }
+/**
+ * Every effect in the catalogue by its name in `EFFECT_CURVES`, each made the
+ * one way: for an element, at its signed-off curve unless handed another,
+ * with the light and the width it was signed off with. A loop comes lit on
+ * the element's own colours (`onColors`); a transition comes as itself, to
+ * be told when it is done. [LAW:types-are-the-program] Keyed by the two
+ * name types, which `EFFECT_CURVES` is held to as well: a curve signed off
+ * does not compile until it is named a loop or a transition, and then not
+ * until it has an entry here making one. A picker walking a section's names
+ * offers an effect added here with no change of its own.
+ */
+export const EFFECT_CATALOGUE = {
+    loops: {
+        shimmer: (element, curve = EFFECT_CURVES.shimmer) => onColors(shimmer(curve, element.span, SHIMMER_WIDTH, EFFECT_LIGHTS.sun, element.z)),
+        pulse: (element, curve = EFFECT_CURVES.pulse) => onColors(pulse(curve, EFFECT_LIGHTS.sun, element.z)),
+        sparkle: (element, curve = EFFECT_CURVES.sparkle) => onColors(sparkle(curve, element.span, EFFECT_LIGHTS.firefly, element.z)),
+        wheel: (element, curve = EFFECT_CURVES.wheel) => wheel(curve, element.z),
+    },
+    transitions: {
+        fade: (element, curve = EFFECT_CURVES.fade) => fadeIn(curve, element.z),
+        dissolve: (element, curve = EFFECT_CURVES.dissolve) => dissolveOut(curve, element.z),
+    },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@promptctl/rich-js",
-  "version": "0.21.0",
+  "version": "0.23.0",
   "description": "Rich text and beautiful formatting in the terminal — a TypeScript port of Python's Rich",
   "repository": {
     "type": "git",