@promptctl/rich-js 0.23.0 → 0.24.0

package/dist/renderables/effect.d.ts

@@ -14,8 +14,9 @@
  * 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 the
+ * What the element draws (`Drawn`) — the cells the second stage will be
+ * handed, and the colours of its words — is measured here, in the render, off
+ * the 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.
@@ -33,8 +34,10 @@
  *   segment's link and meta and carries its anchor shifted to the run's first
  *   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 the output depth
+ *   and a segment whose every cell is unchanged is yielded with its look as
+ *   it was, so the identity effect is byte-identical; what it gains is when
+ *   the frame next changes (`Style.nextChange`), which writes no byte.
+ *   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
@@ -47,6 +50,7 @@
  */
 import { type Anchor } from "../core/anchor.js";
 import { ColorDepth, type ColorRgba, type TerminalTheme } from "../core/color.js";
+import type { Beat } from "../core/easing.js";
 import type { Measurable, Renderable, RenderOptions } from "../core/protocol.js";
 import { Segment } from "../core/segment.js";
 /**
@@ -78,6 +82,8 @@ export interface EffectCell {
         readonly fg: boolean;
         readonly bg: boolean;
     };
+    /** Whether the cell's style swaps its two slots, as `Pair.reverse` says: with `colors` and `terminal`, the cell's `Pair`. */
+    readonly reverse: 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
@@ -85,6 +91,8 @@ export interface EffectCell {
      */
     readonly anchor: Anchor | undefined;
 }
+/** Where a cell sits and who drew it: an `EffectCell` before it has a seed or colours. */
+export type Placed = Pick<EffectCell, "row" | "col" | "anchor">;
 /**
  * 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`
@@ -101,13 +109,24 @@ export interface Pair extends CellColors {
     readonly reverse: boolean;
 }
 /**
- * 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.
+ * What the element an effect wraps draws in one frame: the cells the effect
+ * is handed, and the colours the element draws its words in, 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 cell the element shows something in this frame — a glyph, a
+     * ground that is not the terminal's, or a line its style draws — where it
+     * sits and who drew it, listed before the second stage is handed any: what
+     * an effect spread over the element — a transition, which has its last cell
+     * settle as it ends — is spread over. A blank cell on the terminal's ground
+     * that draws no line is handed but not listed, since nothing in it shows.
+     * `confined` narrows it to the cells its owners drew. A call, so a frame
+     * whose effect does not ask lists none.
+     */
+    cells(): readonly Placed[];
     /** 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. */
@@ -125,8 +144,36 @@ export interface Drawn {
  * [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.
+ *
+ * An effect that knows when its frame next changes says so in `nextChange`,
+ * asked with the same `t` and `drawn` its first stage is: a stepped one its
+ * next step's start, a transition `t` until it is done and `Infinity` after,
+ * a loop that holds every cell still at the frame's depth `Infinity` there.
+ * [LAW:types-are-the-program] The answer is a fact about the frame, so it is
+ * asked with everything the frame is drawn from; an answer asked with `t`
+ * alone could not say that a frame is still because of its depth. A plain
+ * function is an effect that moves every frame, and answers `t`
+ * (`nextChangeOf`): the one true answer for a frame nothing has promised to
+ * hold, so a loop needs no second shape.
  */
-export type Effect = (t: number, drawn: Drawn) => (colors: CellColors, cell: EffectCell) => CellColors;
+export interface Effect {
+    (t: number, drawn: Drawn): (colors: CellColors, cell: EffectCell) => CellColors;
+    /** When the frame drawn at `t` of `drawn` next changes, in seconds on `t`'s timeline, never before `t`; absent, every frame. */
+    readonly nextChange?: (t: number, drawn: Drawn) => number;
+}
+/**
+ * When `effect`'s frame at `t` of `drawn` next changes: what it says, or `t`
+ * for an effect that says nothing. [LAW:single-enforcer] The one reading of
+ * an absent `nextChange`, so no caller holds its own default.
+ */
+export declare function nextChangeOf(effect: Effect, t: number, drawn: Drawn): number;
+/**
+ * An effect drawing as `effect` does, with `nextChange` as its answer to when
+ * its frame next changes, in place of whatever `effect` answered; `effect`
+ * itself is left as it was. A composer whose answer depends on the inner
+ * effect's reads it with `nextChangeOf`, as `onBeat` and `confined` do.
+ */
+export declare function withNextChange(effect: Effect, nextChange: (t: number, drawn: Drawn) => number): Effect;
 export interface EffectedOptions {
     /** The moment to draw, in seconds. */
     readonly t: number;
@@ -150,6 +197,8 @@ export declare class Effected implements Renderable, Measurable {
     readonly theme: TerminalTheme;
     constructor(renderable: Renderable, effect: Effect, options: EffectedOptions);
     render(options: RenderOptions): Iterable<Segment>;
+    private _moved;
+    private _recolored;
     measure(options: RenderOptions): {
         minimum: number;
         maximum: number;
@@ -171,6 +220,25 @@ export declare class Effected implements Renderable, Measurable {
     /** A cell's seed: FNV-1a of the key and the position, scaled into [0, 1). */
     private seed;
 }
+/**
+ * `effect` sampled and held on `beat`: drawn at the moment the hold in
+ * progress began (`Beat.start`), so within a hold every frame is the frame
+ * at its start, and at each hold's start it moves on. A continuous effect
+ * given a short curve becomes one that steps — a `wheel` turning a sixth of
+ * a turn once a second — and at one redraw a second a hold shorter than a
+ * second is skipped, as frames are. [LAW:no-ambient-temporal-coupling] The
+ * held time is a function of `t`, so the same `t` draws the same bytes at
+ * any rate. The frame next changes at a hold's start, and only one the
+ * sampled effect has moved by: the first hold start at or after what it
+ * answers for the frame held now (`Beat.end`). An effect that moves every
+ * frame makes the beat's own answer, the end of this hold; one that is done
+ * and says never leaves the beat saying never too, since the hold after this
+ * one would draw the same frame. The answer is read off what the effect
+ * says, never off a comparison of frames: an effect that steps and is back
+ * on the same colour by the next hold still turns the beat there, an early
+ * answer the contract allows.
+ */
+export declare function onBeat(effect: Effect, beat: Beat): Effect;
 /**
  * `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

package/dist/renderables/effect.js

@@ -14,8 +14,9 @@
  * 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 the
+ * What the element draws (`Drawn`) — the cells the second stage will be
+ * handed, and the colours of its words — is measured here, in the render, off
+ * the 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.
@@ -33,8 +34,10 @@
  *   segment's link and meta and carries its anchor shifted to the run's first
  *   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 the output depth
+ *   and a segment whose every cell is unchanged is yielded with its look as
+ *   it was, so the identity effect is byte-identical; what it gains is when
+ *   the frame next changes (`Style.nextChange`), which writes no byte.
+ *   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
@@ -53,6 +56,23 @@ 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";
+/**
+ * When `effect`'s frame at `t` of `drawn` next changes: what it says, or `t`
+ * for an effect that says nothing. [LAW:single-enforcer] The one reading of
+ * an absent `nextChange`, so no caller holds its own default.
+ */
+export function nextChangeOf(effect, t, drawn) {
+    return effect.nextChange?.(t, drawn) ?? t;
+}
+/**
+ * An effect drawing as `effect` does, with `nextChange` as its answer to when
+ * its frame next changes, in place of whatever `effect` answered; `effect`
+ * itself is left as it was. A composer whose answer depends on the inner
+ * effect's reads it with `nextChangeOf`, as `onBeat` and `confined` do.
+ */
+export function withNextChange(effect, nextChange) {
+    return Object.assign((t, drawn) => effect(t, drawn), { nextChange });
+}
 export class Effected {
     renderable;
     effect;
@@ -69,21 +89,31 @@ export class Effected {
         this.key = options.key;
         this.theme = options.theme;
     }
-    *render(options) {
+    render(options) {
         const segments = this.renderable.render(options);
-        if (options.colorSystem === null) {
-            yield* segments;
-            return;
-        }
+        // With no colour output nothing the effect does is written, so the child
+        // is what is shown, and it changes when the child says it does.
+        if (options.colorSystem === null)
+            return segments;
+        return this._moved(segments, options);
+    }
+    *_moved(segments, options) {
         // 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.
+        // handed to the effect, off the same looks its cells are drawn from, and
+        // the one measure is what both stages and the effect's next change are
+        // asked with.
         const looked = looks(segments, 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) {
+        const walked = walk(looked);
+        const drawn = measured(looked, () => walked, depth, this.theme);
+        const frame = this.effect(this.t, drawn);
+        // What the effect draws at `t` is drawn until its next change, and the
+        // cells say so, under whatever the child already said (the sooner wins).
+        yield* Segment.applyStyle(this._recolored(walked, frame, depth), new Style({ nextChange: nextChangeOf(this.effect, this.t, drawn) }));
+    }
+    *_recolored(walked, frame, depth) {
+        for (const { segment, look, glyphs } of walked) {
             if (look === undefined) {
                 yield segment;
                 continue;
@@ -96,21 +126,9 @@ export class Effected {
             // 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 = slots;
-                if (glyph === "\n") {
-                    row++;
-                    col = 0;
-                }
-                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(frame(from, { row, col, seed: this.seed(row, col), terminal, anchor }), pair.reverse);
-                    col += cellLen(glyph);
-                }
-                into += cellLen(glyph);
+            for (const { glyph, cell } of glyphs) {
+                // Back from the screen to the style's slots: the same swap undoes itself.
+                const colors = cell === undefined ? slots : onScreen(frame(from, { ...cell, seed: this.seed(cell.row, cell.col), terminal, reverse: pair.reverse }), pair.reverse);
                 const last = runs[runs.length - 1];
                 const writes = last !== undefined && sameColors(last.colors, colors) ? last.drawn : this.respec(wire, slots, colors, depth);
                 if (last !== undefined && writesAlike(last.drawn, writes)) {
@@ -178,13 +196,92 @@ function looks(segments, depth, theme) {
         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) {
+/**
+ * Each glyph of `looked`, where its cell sits: rows and columns from the
+ * top-left of the output, a wide glyph one cell at its first column, and its
+ * anchor shifted to that column as `Style.shiftedBy` shifts a run's.
+ * [LAW:one-source-of-truth] The one walk: what `Drawn.cells` lists and what
+ * the render hands the effect are read off it.
+ */
+function walk(looked) {
+    let row = 0;
+    let col = 0;
+    return looked.map(({ segment, look }) => {
+        if (look === undefined)
+            return { segment, look, glyphs: [] };
+        const anchor = look.style.anchor;
+        // Cells into the segment, as `base.shiftedBy` counts them in the render.
+        let into = 0;
+        const glyphs = [...graphemes(segment.text)].map((glyph) => {
+            const cell = glyph === "\n" ? undefined : { row, col, anchor: anchor && shiftAnchor(anchor, into) };
+            [row, col] = glyph === "\n" ? [row + 1, 0] : [row, col + cellLen(glyph)];
+            into += cellLen(glyph);
+            return { glyph, cell };
+        });
+        return { segment, look, glyphs };
+    });
+}
+/** Whether `style` draws in its ink on a blank glyph: a line under, through or over it, or a frame round it. */
+function drawsLines(style) {
+    return [style.underline, style.underline2, style.strike, style.overline, style.frame, style.encircle].some((on) => on === true);
+}
+/**
+ * What `looked` draws: `Drawn`'s measure, taken once per frame. Its `cells`
+ * are listed off `walked` the first time they are asked for, since only an
+ * effect spread over the element asks, and a glyph walk is what measuring the
+ * words alone, a segment at a time, is spared (`drawnOf`).
+ */
+function measured(looked, walked, depth, theme) {
+    const ground = theme.backgroundColor.hex;
+    let listed;
+    const list = () => walked().flatMap(({ look, glyphs }) => {
+        if (look === undefined)
+            return [];
+        // A blank glyph shows its ground, and any line its style draws in its ink.
+        const blankShows = look.pair.bg.hex !== ground || drawsLines(look.style);
+        return glyphs.flatMap(({ glyph, cell }) => (cell !== undefined && (glyph.trim() !== "" || blankShows) ? [cell] : []));
+    });
     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.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 };
+    return {
+        cells: () => (listed ??= list()),
+        pairs,
+        colors: new Set([...own("fg"), ...own("bg")]),
+        fills: new Set(own("bg")),
+        depth,
+        theme,
+    };
+}
+/**
+ * `effect` sampled and held on `beat`: drawn at the moment the hold in
+ * progress began (`Beat.start`), so within a hold every frame is the frame
+ * at its start, and at each hold's start it moves on. A continuous effect
+ * given a short curve becomes one that steps — a `wheel` turning a sixth of
+ * a turn once a second — and at one redraw a second a hold shorter than a
+ * second is skipped, as frames are. [LAW:no-ambient-temporal-coupling] The
+ * held time is a function of `t`, so the same `t` draws the same bytes at
+ * any rate. The frame next changes at a hold's start, and only one the
+ * sampled effect has moved by: the first hold start at or after what it
+ * answers for the frame held now (`Beat.end`). An effect that moves every
+ * frame makes the beat's own answer, the end of this hold; one that is done
+ * and says never leaves the beat saying never too, since the hold after this
+ * one would draw the same frame. The answer is read off what the effect
+ * says, never off a comparison of frames: an effect that steps and is back
+ * on the same colour by the next hold still turns the beat there, an early
+ * answer the contract allows.
+ */
+export function onBeat(effect, beat) {
+    return withNextChange((t, drawn) => effect(beat.start(t), drawn), (t, drawn) => {
+        const moved = nextChangeOf(effect, beat.start(t), drawn);
+        if (moved === Number.POSITIVE_INFINITY)
+            return moved;
+        const end = beat.end(t);
+        // The hold boundaries after `t` are `end`, then each hold's end in turn;
+        // the frame turns at the first one the effect has moved by.
+        return moved <= end ? end : beat.start(moved) === moved ? moved : beat.end(moved);
+    });
 }
 /**
  * `effect` on the colours any of `owners` drew, itself or through an owner
@@ -199,16 +296,22 @@ function measured(looked, depth, theme) {
  */
 export function confined(effect, ...owners) {
     const confinedTo = new Set(owners);
-    return (t, drawn) => {
-        const frame = effect(t, drawn);
+    // [LAW:single-enforcer] One reading of which slots are owned, for the cells listed and the cells handed alike.
+    const ownedOf = (cell) => colorsOwnedBy(cell.anchor, confinedTo);
+    const any = ({ fg, bg }) => fg || bg;
+    // The frame as the effect sees it: the owners' cells alone. [LAW:one-source-of-truth] One narrowing, handed to both stages.
+    const owned = (drawn) => ({ ...drawn, cells: () => drawn.cells().filter((cell) => any(ownedOf(cell))) });
+    // The owners' cells change when the effect's frame does.
+    return withNextChange((t, drawn) => {
+        const frame = effect(t, owned(drawn));
         return (colors, cell) => {
-            const owned = colorsOwnedBy(cell.anchor, confinedTo);
-            if (!owned.fg && !owned.bg)
+            const owns = ownedOf(cell);
+            if (!any(owns))
                 return colors;
             const moved = frame(colors, cell);
-            return { fg: owned.fg ? moved.fg : colors.fg, bg: owned.bg ? moved.bg : colors.bg };
+            return { fg: owns.fg ? moved.fg : colors.fg, bg: owns.bg ? moved.bg : colors.bg };
         };
-    };
+    }, (t, drawn) => nextChangeOf(effect, t, owned(drawn)));
 }
 /**
  * What `segments`, drawn at `depth` on `theme`, draw their words in, measured
@@ -216,7 +319,8 @@ export function confined(effect, ...owners) {
  * 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);
+    const looked = looks(segments, depth, theme);
+    return measured(looked, () => walk(looked), depth, theme);
 }
 /**
  * A style's colour slots as the screen shows them, or the reverse: `reverse`

package/dist/renderables/effects.d.ts

@@ -10,7 +10,11 @@
  * 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:
+ * One effect here is not ambience but a signal, and keeps none of this on
+ * purpose: `steppedInk` steps its ink through colours on a beat, the news
+ * that something is at its limit, and jumps from slot to slot where the
+ * loops hold still. What makes the loops' motions familiar is what every
+ * curve of theirs 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
@@ -48,11 +52,12 @@ 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 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.
+ * How strongly a loop acts at a moment `t` on each cell of a frame drawing
+ * what `Drawn` says, 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;
+export type Field = (t: number, drawn: Drawn) => (cell: EffectCell) => number;
 /** A looping effect: what it does to a colour, and where and when, how strongly. */
 export interface Loop {
     readonly touch: Touch;
@@ -79,9 +84,10 @@ export declare function shares({ pairs, depth, theme }: Drawn, colors: ReadonlyS
  * 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 `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
+ * (`Drawn`), touched as `Effected` writes them at the frame's depth — at 256
+ * colours a touched colour lands on a colour the slot can write, and the
+ * contrast it spends is that colour's; on a sixteen-colour terminal nothing
+ * moves (`stillOnSlots`). `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
@@ -177,8 +183,9 @@ 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
+ * side of its centre, crosses the element from the first column a frame
+ * lists (`Drawn.cells`) to the last, entering and leaving fully off it,
+ * `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
@@ -188,11 +195,17 @@ export declare function pulse(curve: Curve, glow: ColorRgba, z: number): Loop;
  * 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;
+export declare function shimmer(curve: Curve, 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,
+ * goes at its brightest, 0–1. Fireflies keep to a lattice laid from the
+ * element's first column and top row as a frame lists its cells
+ * (`Drawn.cells`): one every `PER` columns along a row of the lattice, a row
+ * of the lattice every `ROWS` rows, each firefly near a home of its own.
+ * The lattice does not hang on how wide or deep the element is, so one that
+ * grows or shrinks at its last column or bottom row moves no firefly; one
+ * whose first column moves, as centred words that change length do, carries
+ * its fireflies with it. 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
@@ -203,13 +216,14 @@ export declare function shimmer(curve: Curve, span: number, width: number, glow:
  * 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;
+export declare function sparkle(curve: Curve, glow: ColorRgba, z: number): Loop;
 /**
- * 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.
+ * How much of each cell shows at `t` in a frame drawing what `Drawn` says: 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 `Effect` is. One
+ * outside [0, 1] is held to it.
  */
-export type Visibility = (t: number) => (cell: EffectCell) => number;
+export type Visibility = (t: number, drawn: Drawn) => (cell: EffectCell) => number;
 /**
  * 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
@@ -225,6 +239,8 @@ export declare function veiled(visibility: Visibility, swing: number): Effect;
  * 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.
+ * Until then the effect's frame changes every frame, and from then never:
+ * its `nextChange` is `done` read as a time. [LAW:one-source-of-truth]
  */
 export interface Transition {
     readonly effect: Effect;
@@ -259,19 +275,50 @@ export declare function dissolveOut(curve: Curve, z: number): Transition;
  * 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.
+ * A colour keeps its luminance as it turns (`hueTurned`), so every pair of
+ * words reads at the contrast it rested at; at 256 colours a turned colour
+ * lands on a colour the depth writes, one that keeps every pair of words it
+ * is drawn in at its floor (`floorOf`) — its resting contrast or WCAG AA,
+ * whichever is lower — as `shares` keeps the light's (`turnedBounds`). The
+ * turn only happens to the element's own colours (`Drawn.colors`), never the
+ * terminal's. On a sixteen-colour terminal nothing turns (`stillOnSlots`).
  */
 export declare function wheel(curve: Curve, z: number): Effect;
+/** One step of a signal: the ink it draws, and how long it is held, in seconds. */
+export interface ColorStep {
+    readonly color: ColorRgba;
+    readonly seconds: number;
+}
+/**
+ * A signal: every cell's ink stepping through `steps`' colours on a beat,
+ * one colour a hold, looping, for the time it is handed — a gauge's
+ * chevrons in bright changing colours. The ground is left as the cell draws
+ * it, and the words stay legible on it: each step's ink is written as the
+ * colour nearest the step's (OKLab's ΔE) that the depth draws and that
+ * reads on the cell's ground, as `Effected` writes it, at the cell's floor
+ * (`floorOf`) — its resting contrast or `LEGIBLE`, whichever is lower, the
+ * floor every loop here keeps. In truecolor that is the step itself, or its
+ * hue and chroma at the lightness nearest it that reaches the floor
+ * (`ensureContrast`, the one slide a template's `readableOn` makes too);
+ * below truecolor, the nearest of the colours the depth has an index for, so on a
+ * sixteen-colour terminal it steps from slot to slot, the one effect here
+ * that does (`stillOnSlots`). A cell whose ground no offered colour reads
+ * on keeps the ink it rested in.
+ *
+ * The search is settled once for each ink, ground and step, so a frame
+ * inside a step redoes none, and nor does a later pass of the beat: at sixty
+ * frames a second a one-second step is sixty identical frames, and the
+ * frame says it changes next when the step ends (`Beat.end`).
+ * [LAW:no-ambient-temporal-coupling] The beat is `core/easing.ts`'s, and
+ * nothing here reads a clock.
+ */
+export declare function steppedInk(steps: readonly ColorStep[]): 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.
+ * What a catalogue effect is made for: the element it is drawn on, at `z` in
+ * the noise, so two elements under one effect do not move in lockstep. How
+ * wide the element is, the effect reads off each frame (`Drawn.cells`).
  */
 export interface EffectTarget {
-    readonly span: number;
     readonly z: number;
 }
 /** The names of the effects that loop. */