@promptctl/rich-js 0.19.0 → 0.21.0

package/dist/renderables/effect.d.ts

@@ -2,11 +2,18 @@
  * 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, and a
- * time 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.
+ * 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.
+ *
+ * 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
+ * settled against (`onColors`, `./effects.ts`), so no caller derives it a
+ * second time from a render of its own.
  *
  * [LAW:no-ambient-temporal-coupling] `t` is a constructor argument, not a
  * clock read. Whoever draws frames builds the view for each frame's `t`, so
@@ -22,8 +29,9 @@
  *   cell (`Style.shiftedBy`), so hit testing still finds the owner.
  * - A cell whose colours come back unchanged keeps its original `ColorSpec`,
  *   and a segment whose every cell is unchanged is yielded as it was, so the
- *   identity effect is byte-identical. Neighbouring cells given equal colours
- *   stay one segment: a segment is cut only where the colours change.
+ *   identity effect is byte-identical. Neighbouring cells the output depth
+ *   writes alike stay one segment: a segment is cut only where the written
+ *   colours change, so two colours that land on one index are one run.
  * - New colours are built with `ColorSpec.fromRgba`, never parsed from a
  *   string, so no frame adds an entry to a parse cache.
  * - With no colour output (`colorSystem: null`) there is nothing for an
@@ -32,7 +40,8 @@
  * Positions are the child's own: row and column count from the top-left of
  * what the child drew, so a sweep crosses the element, not the screen.
  */
-import { type ColorRgba, type TerminalTheme } from "../core/color.js";
+import { type Anchor } from "../core/anchor.js";
+import { ColorDepth, type ColorRgba, type TerminalTheme } from "../core/color.js";
 import type { Measurable, Renderable, RenderOptions } from "../core/protocol.js";
 import { Segment } from "../core/segment.js";
 /**
@@ -45,17 +54,63 @@ export interface CellColors {
     readonly bg: ColorRgba;
 }
 /**
- * Where a cell is in the output of the renderable an effect wraps, and its
- * seed: a number in [0, 1) that is the same for that cell on every frame, for
- * an effect that varies cell by cell (a per-cell offset in time, a sparkle).
+ * Where a cell is in the output of the renderable an effect wraps, its seed:
+ * a number in [0, 1) that is the same for that cell on every frame, for an
+ * effect that varies cell by cell (a per-cell offset in time, a sparkle) —
+ * and which of its on-screen colours are the terminal's.
  */
 export interface EffectCell {
     readonly row: number;
     readonly col: number;
     readonly seed: number;
+    /**
+     * Whether the glyph's colour and the colour behind it, as the screen shows
+     * them, are the terminal's own: a slot the element's style leaves unset or
+     * sets to `default`. Such a colour is resolved through the theme, so its
+     * hex can equal one the element wrote; this is what tells them apart.
+     */
+    readonly terminal: {
+        readonly fg: boolean;
+        readonly bg: boolean;
+    };
+    /**
+     * Who drew the cell, and where it sits in their output, as
+     * `Segment.anchorAt` reads it off a frame: what tells one owner's cells
+     * from another's when their colours are alike (`confined`).
+     */
+    readonly anchor: Anchor | undefined;
 }
-/** A cell's colours at time `t`, in seconds. Return `colors` to leave it be. */
-export type Effect = (colors: CellColors, cell: EffectCell, t: number) => CellColors;
+/**
+ * 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.
+ */
+export interface Pair extends CellColors {
+    readonly terminal: EffectCell["terminal"];
+}
+/**
+ * The colours the element an effect wraps draws its words in, in one frame,
+ * as the screen shows them: what an effect that must keep the words legible
+ * is measured against. A word cell is one whose glyph is not blank and that a
+ * strip's joiner did not draw (`JOIN`): a seam's ink is the fill beside it,
+ * not words.
+ */
+export interface Drawn {
+    /** Every distinct ink and ground of a word cell. */
+    readonly pairs: readonly Pair[];
+    /** The colours the element sets itself in its word cells, by hex: never the terminal's, whatever its hex. */
+    readonly colors: ReadonlySet<string>;
+    /** Of `colors`, the ones a word cell has for its ground. */
+    readonly fills: ReadonlySet<string>;
+    /** The depth the frame is written at: below truecolor a moved colour lands on a palette colour. */
+    readonly depth: ColorDepth;
+    /** The terminal the frame is drawn on. */
+    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.
+ */
+export type Effect = (colors: CellColors, cell: EffectCell, t: number, drawn: Drawn) => CellColors;
 export interface EffectedOptions {
     /** The moment to draw, in seconds. */
     readonly t: number;
@@ -84,15 +139,33 @@ export declare class Effected implements Renderable, Measurable {
         maximum: number;
     };
     /**
-     * The style that draws a run's slot colours `to` where the segment drew
+     * 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`), so a colour moved a little
-     * off a theme slot or the default colour is still drawn as that one.
+     * 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.
      */
     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`).
+ */
+export declare function confined(effect: Effect, owner: 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
+ * output under an effect to read the contrast its words are left at.
+ */
+export declare function drawnOf(segments: Iterable<Segment>, depth: ColorDepth, theme: TerminalTheme): Drawn;

package/dist/renderables/effect.js

@@ -2,11 +2,18 @@
  * 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, and a
- * time 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.
+ * 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.
+ *
+ * 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
+ * settled against (`onColors`, `./effects.ts`), so no caller derives it a
+ * second time from a render of its own.
  *
  * [LAW:no-ambient-temporal-coupling] `t` is a constructor argument, not a
  * clock read. Whoever draws frames builds the view for each frame's `t`, so
@@ -22,8 +29,9 @@
  *   cell (`Style.shiftedBy`), so hit testing still finds the owner.
  * - A cell whose colours come back unchanged keeps its original `ColorSpec`,
  *   and a segment whose every cell is unchanged is yielded as it was, so the
- *   identity effect is byte-identical. Neighbouring cells given equal colours
- *   stay one segment: a segment is cut only where the colours change.
+ *   identity effect is byte-identical. Neighbouring cells the output depth
+ *   writes alike stay one segment: a segment is cut only where the written
+ *   colours change, so two colours that land on one index are one run.
  * - New colours are built with `ColorSpec.fromRgba`, never parsed from a
  *   string, so no frame adds an entry to a parse cache.
  * - With no colour output (`colorSystem: null`) there is nothing for an
@@ -32,11 +40,13 @@
  * Positions are the child's own: row and column count from the top-left of
  * what the child drew, so a sweep crosses the element, not the screen.
  */
+import { drawnBy, shiftAnchor } from "../core/anchor.js";
 import { cellLen, graphemes } from "../core/cells.js";
-import { ColorDepth, ColorSpec, SURFACE_BLACK } from "../core/color.js";
+import { ColorDepth, ColorSpec, SURFACE_BLACK, rgbDistance } from "../core/color.js";
 import { fnv1a } from "../core/fnv1a.js";
 import { Measurement } from "../core/measure.js";
 import { Segment } from "../core/segment.js";
+import { JOIN, colorsOwnedBy } from "../core/strip.js";
 import { Style } from "../core/style.js";
 export class Effected {
     renderable;
@@ -62,56 +72,59 @@ export class Effected {
         }
         // No depth named is no downgrade, as `drawnColors` reads it.
         const depth = options.colorSystem ?? ColorDepth.TRUECOLOR;
+        // [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);
         let row = 0;
         let col = 0;
-        for (const segment of segments) {
-            if (segment.isControl) {
+        for (const { segment, look } of looked) {
+            if (look === undefined) {
                 yield segment;
                 continue;
             }
-            const base = segment.style ?? Style.null();
-            // [LAW:single-enforcer] `drawnColors` is what the wire writes at this
-            // depth — alpha flattened, downgraded — and the theme resolves what it
-            // leaves to the terminal. A slot the effect leaves alone keeps the
-            // written spec, so it stays what the screen showed whatever moves
-            // beside it.
-            const wire = base.drawnColors(options.colorSystem ?? undefined);
-            const ink = (wire.color ?? DEFAULT).getTruecolor(this.theme, true);
-            const paper = (wire.bgcolor ?? DEFAULT).getTruecolor(this.theme, false);
-            const from = onScreen({ fg: ink, bg: paper }, base);
-            // Each grapheme's colours, merged into runs of equal colours as they
-            // come; `undefined` is a run left as the segment drew it.
+            const { style: base, wire, slots, pair } = look;
+            const { terminal } = pair;
+            const from = { fg: pair.fg, bg: pair.bg };
+            // [LAW:one-source-of-truth] A run is cells the wire writes alike: each
+            // cell is drawn at the output depth first and merged on the colours that
+            // writes, so two truecolors landing on one index stay one run. A cell
+            // the effect gave its neighbour's colours is drawn as that neighbour was.
             const runs = [];
+            // Cells into the segment, as `base.shiftedBy` counts them below.
+            let into = 0;
             for (const glyph of graphemes(segment.text)) {
-                let colors;
+                let colors = slots;
                 if (glyph === "\n") {
                     row++;
                     col = 0;
                 }
                 else {
-                    const to = this.effect(from, { row, col, seed: this.seed(row, col) }, this.t);
-                    colors = sameColors(to, from) ? undefined : to;
+                    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);
                     col += cellLen(glyph);
                 }
+                into += cellLen(glyph);
                 const last = runs[runs.length - 1];
-                if (last !== undefined && sameRun(last.colors, colors)) {
+                const writes = last !== undefined && sameColors(last.colors, colors) ? last.drawn : this.respec(wire, slots, colors, depth);
+                if (last !== undefined && writesAlike(last.drawn, writes)) {
                     last.text += glyph;
                     last.cells += cellLen(glyph);
+                    last.colors = colors;
                 }
                 else {
-                    runs.push({ text: glyph, cells: cellLen(glyph), colors });
+                    runs.push({ text: glyph, cells: cellLen(glyph), colors, drawn: writes });
                 }
             }
-            if (runs.every((run) => run.colors === undefined)) {
+            if (runs.every((run) => writesAlike(run.drawn, wire))) {
                 yield segment;
                 continue;
             }
             let offset = 0;
             for (const run of runs) {
                 const shifted = base.shiftedBy(offset);
-                // Back from the screen to the style's slots: the same swap undoes itself.
-                const slots = run.colors === undefined ? undefined : onScreen(run.colors, base);
-                const style = slots === undefined ? shifted : shifted.add(this.respec(wire, { fg: ink, bg: paper }, slots, depth));
+                const style = writesAlike(run.drawn, wire) ? shifted : shifted.add(Style.fromColor(run.drawn.color, run.drawn.bgcolor));
                 yield new Segment(run.text, style);
                 offset += run.cells;
             }
@@ -121,20 +134,26 @@ export class Effected {
         return Measurement.get(options, this.renderable);
     }
     /**
-     * The style that draws a run's slot colours `to` where the segment drew
+     * 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`), so a colour moved a little
-     * off a theme slot or the default colour is still drawn as that one.
+     * 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.
      */
     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) => sameColor(was, now) ? spec : ColorSpec.matchOn(now, depth, this.theme, foreground);
-        return Style.fromColor(drawn(wire.color, from.fg, glyph, true), drawn(wire.bgcolor, from.bg, ground, false));
+        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) };
     }
     /** A cell's seed: FNV-1a of the key and the position, scaled into [0, 1). */
     seed(row, col) {
@@ -142,19 +161,73 @@ export class Effected {
     }
 }
 const DEFAULT = ColorSpec.default();
+/** Each of `segments` with how it is drawn at `depth` on `theme`; a control segment draws nothing. */
+function looks(segments, depth, theme) {
+    return [...segments].map((segment) => {
+        if (segment.isControl)
+            return { segment, look: undefined };
+        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 } } };
+    });
+}
+/** 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()];
+    // [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`).
+ */
+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 };
+    };
+}
+/**
+ * What `segments`, drawn at `depth` on `theme`, draw their words in, measured
+ * as `Effected` measures its child for every frame. Measure an element's
+ * output under an effect to read the contrast its words are left at.
+ */
+export function drawnOf(segments, depth, theme) {
+    return measured(looks(segments, depth, theme), 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(colors, style) {
-    return style.reverse === true ? { fg: colors.bg, bg: colors.fg } : colors;
+function onScreen(slots, style) {
+    return style.reverse === true ? { fg: slots.bg, bg: slots.fg } : slots;
 }
-function sameColor(a, b) {
-    return a.red === b.red && a.green === b.green && a.blue === b.blue && a.alpha === b.alpha;
+/**
+ * Whether two cells' colours are written alike. A slot with no colour is not
+ * the default colour: it writes nothing, so a style a container lays beneath
+ * (`Segment.applyStyle`) still shows through it, where `39`/`49` would not.
+ */
+function writesAlike(a, b) {
+    return slotWritesAlike(a.color, b.color, true) && slotWritesAlike(a.bgcolor, b.bgcolor, false);
+}
+function slotWritesAlike(a, b, foreground) {
+    return a === b || written(a, foreground) === written(b, foreground);
+}
+function written(spec, foreground) {
+    return spec?.getAnsiCodes(foreground).join(";") ?? "";
 }
 function sameColors(a, b) {
     return sameColor(a.fg, b.fg) && sameColor(a.bg, b.bg);
 }
-function sameRun(a, b) {
-    return a === undefined || b === undefined ? a === b : sameColors(a, b);
+function sameColor(a, b) {
+    return a.red === b.red && a.green === b.green && a.blue === b.blue && a.alpha === b.alpha;
 }

package/dist/renderables/effects.d.ts

@@ -0,0 +1,260 @@
+/**
+ * The effect catalogue: shimmer, pulse, sparkle and wheel, which loop for as
+ * 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.
+ *
+ * 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
+ * blooming in water, mist lifting — because a motion the eye recognises
+ * reads as calm and alive, where a motion it has to learn reads as a widget.
+ * What makes those motions familiar is what every curve here keeps:
+ *
+ * - Nothing jumps. Every curve is continuous in time, built from smooth
+ *   noise (`core/noise.ts`) and smooth waveforms, so at one frame a second a cell
+ *   moves a little and at thirty it glides.
+ * - Nothing repeats exactly. Rhythms are perturbed by slow noise, and each
+ *   breath, firefly's flash and pass of light is an event of its own, with
+ *   its own strength and moment, the way no breath or gust is the last one
+ *   again. A weaker event is a shorter one, so its strength costs nothing
+ *   in smoothness.
+ * - Neighbours move together. Variation is spatially coherent — patches,
+ *   filaments, fronts — never per-cell static.
+ * - Light only ever lights, and never takes the words away. Ink and the
+ *   fill under it both move toward the light and never darken, each by its
+ *   own share: the share a colour can take while every cell it is drawn in
+ *   still reads at its resting contrast or WCAG AA, whichever is lower. A
+ *   cell with contrast to spare glows brightly; one with none barely moves.
+ * - Elements are apart. Each sits at its own `z` in the noise, so two
+ *   elements under one effect do not move in lockstep.
+ *
+ * Colour moves are in OKLCH, where equal steps look equal. A curve's `ease`
+ * maps its intensity in [0, 1] — how strongly the effect acts on a cell at a
+ * moment — onto its swing, for the loops and the transitions alike.
+ *
+ * [LAW:no-ambient-temporal-coupling] No curve reads a clock; `t` is the
+ * effect's argument, so the frame owner decides when to sample.
+ *
+ * Every import below names something the package exports, but for `noise`
+ * and `Memo`, which the docs' effects playground page supplies itself: each of its
+ * cards runs this file's own declarations as the program a visitor edits
+ * (`examples/effects-playground/programs.ts`), on the published library.
+ */
+import { ColorRgba } from "../core/color.js";
+import { type Ease } from "../core/easing.js";
+import type { Drawn, Effect, EffectCell, Pair } 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;
+/** A looping effect: what it does to a colour, and where and when, how strongly. */
+export interface Loop {
+    readonly touch: Touch;
+    readonly field: Field;
+}
+/**
+ * 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
+ * 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
+ * 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.
+ *
+ * Colours are settled lightest first, each against every partner: one
+ * already settled at its share, one not yet settled as it is. So the lighter
+ * colour of a cell takes the light first and its darker partner spends
+ * whatever contrast is left — pale lettering lifting off a dark fill gives
+ * 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>;
+/**
+ * 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
+ * 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
+ * not the element's, whatever its hex, and takes no share.
+ *
+ * Settling shares is costly, so it is done once for each set of colours an
+ * element draws: make the effect once and draw it in every frame, and a frame
+ * drawing what an earlier one drew costs no settling.
+ */
+export declare function onColors(loop: Loop, colors?: ReadonlySet<string>): Effect;
+/**
+ * A loop as an `Effect` on colours by hex, each touched at the share
+ * `share` gives it of the cell's strength in a frame drawing what `Drawn`
+ * says; a colour it gives none, and one the terminal supplies, stays as it is.
+ */
+export declare function atShares(loop: Loop, share: (drawn: Drawn) => ReadonlyMap<string, number>): Effect;
+/** How the curves below are tuned: one period (or duration), ease and swing. */
+export interface Curve {
+    /** Seconds: a looping effect's period, a transition's duration. */
+    readonly seconds: number;
+    /** Intensity in [0, 1] to the fraction of `swing` applied. One that overshoots, as a CSS `cubic-bezier` may, saturates: an effect never acts past its swing. */
+    readonly ease: Ease;
+    /** How far the move goes at full intensity, in [0, 1]; what 1 means is the effect's. */
+    readonly swing: number;
+}
+/**
+ * Each effect's curve as it was signed off. Every loop's period is a prime
+ * number of seconds, so no two loops come back into step within a sitting.
+ * The periods are long on purpose: at one frame a second a loop's colour
+ * moves by no more than a just-noticeable step from one frame to the next.
+ */
+export declare const EFFECT_CURVES: {
+    readonly shimmer: {
+        readonly seconds: 109;
+        readonly ease: Ease;
+        readonly swing: 0.9;
+    };
+    readonly pulse: {
+        readonly seconds: 43;
+        readonly ease: Ease;
+        readonly swing: 0.85;
+    };
+    readonly sparkle: {
+        readonly seconds: 139;
+        readonly ease: Ease;
+        readonly swing: 0.95;
+    };
+    readonly wheel: {
+        readonly seconds: 907;
+        readonly ease: Ease;
+        readonly swing: 1;
+    };
+    readonly fade: {
+        readonly seconds: 20;
+        readonly ease: Ease;
+        readonly swing: 1;
+    };
+    readonly dissolve: {
+        readonly seconds: 30;
+        readonly ease: Ease;
+        readonly swing: 1;
+    };
+};
+/** The lights the loops were signed off casting, warm as sunlight and fireflies are. */
+export declare const EFFECT_LIGHTS: {
+    readonly sun: ColorRgba;
+    readonly firefly: ColorRgba;
+};
+/** How far a shimmer's light reaches either side of its centre, in columns, as signed off. */
+export declare const SHIMMER_WIDTH = 24;
+/**
+ * A colour under `glow`: the one way every light here falls. It moves `w` of
+ * the way toward the light's colour, and never below its own lightness —
+ * light can warm a colour and lift it, never darken it. A colour already
+ * lighter than the light only warms, and white, which has no warmer shade at
+ * its lightness, stays white.
+ */
+export declare function light(glow: ColorRgba): Touch;
+/**
+ * Pulse, as a gentle glow on one element of a screen: the colours handed to
+ * it, an element's own, warm into `light` and settle back, over and over, the
+ * way an indicator breathes while something is waiting. Swing: how far into
+ * the light it goes at the top of a beat, 0–1. The element glows as one —
+ * every cell it is drawn in at once — and the colours not handed to it, the
+ * rest of the screen, stay as they are, so what pulses is what was chosen.
+ * Each element keeps a time of its own, a little quicker or slower than
+ * another's by `z`, and no beat is quite the last: the rhythm wanders ahead
+ * and behind its metronome and each beat goes a little deeper or shallower
+ * than the one before. A beat starts and ends in rest, so `t = 0` draws the
+ * element untouched.
+ */
+export declare function pulse(curve: Curve, glow: ColorRgba, z: number): Loop;
+/**
+ * Shimmer, as sunlight moving across water. Swing: how far into `light` the
+ * brightest glint goes, 0–1. A soft band of light, `width` columns either
+ * side of its centre, crosses columns 0 to `span`, entering and leaving
+ * fully off the row, `STRIDE` columns in about three quarters of a period. Its passes
+ * come the way light comes and goes on water as clouds move: while the sun
+ * is out they are bright and follow close on one another, one sometimes
+ * catching the last; under cloud they thin to faint ones with the row still
+ * for a while between, and the light is never gone for long. Each crosses at its own unhurried pace, drifting a little ahead
+ * and behind as it goes. Inside a band the light is a faint glow broken
+ * into a glitter path — bright filaments where two ripples cross — carried
+ * on a slow current and re-forming as they go, so the glints dance while
+ * the band glides. Before the first pass enters, the row is untouched.
+ */
+export declare function shimmer(curve: Curve, span: number, width: number, glow: ColorRgba, z: number): Loop;
+/**
+ * Sparkle, as fireflies. Swing: how far into the firefly's `light` a glow
+ * goes at its brightest, 0–1. About one firefly to every eight columns of
+ * `span`, each keeping near a home of its own. A firefly flashes — kindles,
+ * drifts a few cells glowing, slowing as it fades — then flies on in the
+ * dark and flashes again somewhere a few cells off, the way fireflies at
+ * dusk are seen: a short lit stroke, then gone, each time a little
+ * elsewhere. Each keeps its own irregular time, now and then letting a turn
+ * pass dark, so most moments a few are lit, at different brightnesses. Its
+ * light is a soft halo several cells wide, brightest where it is, so as it
+ * drifts the glow slides between cells rather than hopping. `seconds` is a firefly's
+ * turn: its brightest flash, rise and fall, takes `FLASH` of it, and a
+ * dimmer one less.
+ */
+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.
+ */
+export type Visibility = (cell: EffectCell, t: number) => 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.
+ */
+export declare function veiled(visibility: Visibility, swing: number, ground: ColorRgba): 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.
+ */
+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`.
+ */
+export declare function fadeIn(curve: Curve, start: number, z: number, ground: ColorRgba): 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
+ * 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;
+/**
+ * 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
+ * sees a steady palette and an hour's absence a different one — each
+ * segment of the element at its own pace. Swing: how far the segments stray
+ * from one another, 0–1, 1 being half a turn apart. A segment is a fill of
+ * the element's own — one of `fills`, the colours it draws as a ground — and
+ * it turns at its own pace wherever it is drawn: as the ground of its cells,
+ * and as the ink of the seam glyph pointing out of it into the next, so a
+ * powerline cap keeps the colour of the cell it caps. An ink that is no fill
+ * turns with the ground it sits on, so a cell's words and fill turn
+ * together; on the terminal's ground, a run of text's ink is a segment of
+ * its own. A segment's stray is slow noise of its own, at `STRAY_PERIODS`,
+ * so no two keep step, and the row never shows one spread of hues twice.
+ * Lightness and chroma are kept, so the words read as they did; the turn
+ * only happens to the element's own colours (`Drawn.colors`), never the
+ * terminal's.
+ */
+export declare function wheel(curve: Curve, z: number): Effect;