@promptctl/rich-js 0.27.0 → 0.28.0

package/dist/renderables/effect.js

@@ -17,9 +17,10 @@
  * (`JoinedCell`, `../core/strip.ts`), the way the joiner drew it. Shimmer,
  * pulse, fade, dissolve and a blinking attribute 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.
+ * [LAW:one-type-per-behavior]; two effects stack as layers of one effect
+ * (`layered`, `./effects.ts`), each moving what the last left and recognising
+ * a cell by what the element drew (`EffectCell.pair`), or by nesting one
+ * wrapper in another, which measures the inner one's output instead.
  *
  * A cell's look is one value, its colours and its attributes together
  * (`CellLook`), rather than an attribute stage beside the colour one, so
@@ -69,60 +70,67 @@
  * what the child drew, so a sweep crosses the element, not the screen.
  */
 import { drawnBy, shiftAnchor } from "../core/anchor.js";
-import { Animation, frameTimeOf, holdOf, shownAt, stampFrame } from "../core/animation.js";
+import { Animation, holdOf, placedRender, shownAt } from "../core/animation.js";
 import { cellLen, graphemes } from "../core/cells.js";
-import { ColorDepth, ColorSpec, SURFACE_BLACK } from "../core/color.js";
+import { ColorDepth, ColorSpec, resolveTerminal, SURFACE_BLACK } from "../core/color.js";
 import { fnv1a } from "../core/fnv1a.js";
 import { Measurement } from "../core/measure.js";
 import { render } from "../core/protocol.js";
 import { Segment } from "../core/segment.js";
 import { JOIN, joinedCell } from "../core/strip.js";
-import { ATTRIBUTE_NAMES, Style } from "../core/style.js";
+import { ATTRIBUTE_NAMES, NEVER_CHANGES, Style } from "../core/style.js";
 import { finiteTime } from "../core/easing.js";
-/** What drew nothing the effect can change: held forever, as far as the effect says. */
-const UNMOVED = { lastChange: Number.NEGATIVE_INFINITY, nextChange: Number.POSITIVE_INFINITY };
+/**
+ * The hold an effect drawn at `t` tells: its animation's there, or held for
+ * good over no cell, since it changes how cells look and never which exist.
+ * What drew none says for itself when it will (a lifecycle not yet entered).
+ */
+export function holdOver(anyCell, shown, t) {
+    return anyCell ? holdOf(shown, t) : NEVER_CHANGES;
+}
 /**
  * An `Effected` at `t`, or an element through an effect at a time an
  * animation's `at` was handed — a lifecycle's time since it entered: `renderable`
- * with its cells' looks passed through `effect` at `t`, saying nothing of
- * when that changes, since whatever placed the animation stamps its hold.
- * [LAW:one-type-per-behavior]
+ * with its cells' looks passed through `effect` at `t`. Its cells say nothing
+ * of when that changes, since `t` is not the frame's clock: it tells the hold
+ * it drew in (`RenderOptions.onMoved`), and whatever placed the animation
+ * carries that onto the frame's and stamps it. [LAW:one-type-per-behavior]
  */
 export class Recolored {
     renderable;
     effect;
-    t;
+    _t;
     key;
-    theme;
     constructor(renderable, effect, options) {
         this.renderable = renderable;
         this.effect = effect;
-        this.t = finiteTime("Effected", options.t);
+        this._t = finiteTime("Effected", options.t);
         this.key = options.key;
-        this.theme = options.theme;
     }
     render(options) {
-        return this.moved(options).segments;
-    }
-    /** The frame the effect draws at `t`, and the hold it says that is in. */
-    moved(options) {
         const segments = render(this.renderable, options);
         // 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, hold: UNMOVED };
+        if (options.colorSystem === null) {
+            options.onMoved?.(this._t, this.key, NEVER_CHANGES);
+            return segments;
+        }
         // No depth named is no downgrade, as `drawnColors` reads it.
         const depth = options.colorSystem ?? ColorDepth.TRUECOLOR;
+        // [LAW:one-source-of-truth] Every colour below resolves on the frame's
+        // terminal, so two effects in a frame cannot disagree.
+        const terminal = resolveTerminal(options.terminal, depth);
         // [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, and
         // the one measure is what the effect's animation is made from.
-        const looked = looks(segments, depth, this.theme);
+        const looked = looks(segments, depth, terminal);
         const walked = walk(looked);
-        const animation = this.effect(measured(looked, () => walked, depth, this.theme));
-        const shown = shownAt(animation, this.t, options);
-        return { segments: this._recolored(walked, shown.value, depth), hold: holdOf(shown, this.t) };
+        const drawn = measured(looked, () => walked, depth, terminal);
+        const shown = shownAt(this.effect(drawn), this._t, options);
+        options.onMoved?.(this._t, this.key, holdOver(walked.some(({ glyphs }) => glyphs.some(({ cell }) => cell !== undefined)), shown, this._t));
+        return this._recolored(walked, shown.value, drawn);
     }
-    *_recolored(walked, frame, depth) {
+    *_recolored(walked, frame, drawn) {
         // [LAW:one-source-of-truth] Every cell but a join cell that follows its
         // neighbours is painted first, so that cell is resolved from the cells
         // beside it as the effect left them, wherever in the frame they fall.
@@ -133,8 +141,7 @@ export class Recolored {
             if (joined?.follows === true)
                 return { joined };
             const from = { fg: look.pair.fg, bg: look.pair.bg, attributes: look.attributes };
-            const { terminal, reverse } = look.pair;
-            return { painted: glyphs.map(({ cell }) => (cell === undefined ? from : returned(frame(from, { ...cell, seed: cellSeed(this.key, cell.row, cell.col), terminal, reverse })))) };
+            return { painted: glyphs.map(({ cell }) => (cell === undefined ? from : returned(frame(from, { ...cell, seed: cellSeed(this.key, cell.row, cell.col), pair: look.pair })))) };
         });
         const beside = edgesBeside(walked, drawings);
         for (const [i, { segment, look, glyphs }] of walked.entries()) {
@@ -142,13 +149,13 @@ export class Recolored {
             if (look === undefined || drawing === undefined)
                 yield segment;
             else if ("joined" in drawing)
-                yield this._rejoined(segment, look, drawing.joined, glyphs, beside, frame, depth);
+                yield this._rejoined(segment, look, drawing.joined, glyphs, beside, frame, drawn);
             else
-                yield* this._repainted(segment, look, glyphs, drawing.painted, depth);
+                yield* this._repainted(segment, look, glyphs, drawing.painted, drawn);
         }
     }
     /** `segment`'s cells drawn in the looks the effect painted them. */
-    *_repainted(segment, look, glyphs, moved, depth) {
+    *_repainted(segment, look, glyphs, moved, drawn) {
         const { style: base, wire, slots, pair, attributes } = look;
         // [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
@@ -161,7 +168,7 @@ export class Recolored {
             // Back from the screen to the style's slots: the same swap undoes itself.
             const colors = onScreen(now, pair.reverse);
             const last = runs[runs.length - 1];
-            const writes = last !== undefined && sameColors(last.colors, colors) ? last.drawn : this.respec(wire, slots, colors, depth);
+            const writes = last !== undefined && sameColors(last.colors, colors) ? last.drawn : this.respec(wire, slots, colors, drawn);
             if (last !== undefined && writesAlike(last.drawn, writes) && sameAttributes(last.attributes, now.attributes)) {
                 last.text += glyph;
                 last.cells += cellLen(glyph);
@@ -191,13 +198,13 @@ export class Recolored {
      * nothing of keeps the edge the cell was drawn from, so with neither moved
      * the cell is as it was drawn.
      */
-    _rejoined(segment, look, joined, glyphs, beside, frame, depth) {
+    _rejoined(segment, look, joined, glyphs, beside, frame, measure) {
+        const { depth, terminal } = measure;
         const cells = glyphs.flatMap(({ cell }) => (cell === undefined ? [] : [cell]));
         // A join cell that draws no cell shows nothing an effect could move.
         const [at] = cells;
         if (at === undefined)
             return segment;
-        const { theme } = this;
         // [LAW:one-source-of-truth] A moved edge is the spec the depth writes its
         // slot in, the spec the joiner reads of an item drawn so: a palette slot
         // stays that slot, which the lift tells apart by number, never an RGB read
@@ -209,12 +216,12 @@ export class Recolored {
         const edgeOf = (spec, foreground) => {
             if (!spec?.isDefault)
                 return spec;
-            const own = ColorSpec.fromRgba(spec.getTruecolor(theme, foreground));
+            const own = ColorSpec.fromRgba(spec.getTruecolor(terminal, foreground));
             terminals.add(own);
             return own;
         };
         const moved = (from, to) => {
-            const specs = movedSpecs(from, to, depth, theme);
+            const specs = movedSpecs(from, to, depth, terminal);
             return specs.fg === undefined && specs.bg === undefined ? undefined : { color: edgeOf(specs.fg, true), bgcolor: edgeOf(specs.bg, false) };
         };
         // [LAW:one-source-of-truth] A neighbour the frame shows no cell of beside
@@ -228,9 +235,9 @@ export class Recolored {
         // comes here [LAW:no-silent-failure].
         const unseen = (edge) => {
             const wire = edge.drawnColors(depth);
-            const slots = { fg: (wire.color ?? DEFAULT).getTruecolor(theme, true), bg: (wire.bgcolor ?? DEFAULT).getTruecolor(theme, false) };
-            const terminal = { fg: wire.color?.isDefault ?? true, bg: wire.bgcolor?.isDefault ?? true };
-            return moved(slots, returned(frame({ ...slots, attributes: cellAttributes(edge) }, { ...at, seed: cellSeed(this.key, at.row, at.col), terminal, reverse: false })));
+            const slots = { fg: (wire.color ?? DEFAULT).getTruecolor(terminal, true), bg: (wire.bgcolor ?? DEFAULT).getTruecolor(terminal, false) };
+            const own = { fg: wire.color?.isDefault ?? true, bg: wire.bgcolor?.isDefault ?? true };
+            return moved(slots, returned(frame({ ...slots, attributes: cellAttributes(edge) }, { ...at, seed: cellSeed(this.key, at.row, at.col), pair: { ...slots, terminal: own, reverse: false } })));
         };
         const moveOf = (side) => {
             const read = joined.reads[side];
@@ -256,7 +263,7 @@ export class Recolored {
         const was = joined.style;
         const drawn = colors.drawnColors(depth);
         const { wire, slots } = look;
-        const rounded = this.respec(wire, slots, { fg: colors.color?.getTruecolor(theme, true) ?? slots.fg, bg: colors.bgcolor?.getTruecolor(theme, false) ?? slots.bg }, depth);
+        const rounded = this.respec(wire, slots, { fg: colors.color?.getTruecolor(terminal, true) ?? slots.fg, bg: colors.bgcolor?.getTruecolor(terminal, false) ?? slots.bg }, measure);
         const written = (now, before, wrote, drew, round) => {
             if (sameSpec(now, before))
                 return wrote;
@@ -280,42 +287,39 @@ export class Recolored {
      * `from` with `wire`: each moved slot in the spec `movedSpecs` writes it
      * in, the rest as `wire` wrote them.
      */
-    respec(wire, from, to, depth) {
-        const moved = movedSpecs(from, to, depth, this.theme);
+    respec(wire, from, to, { depth, terminal }) {
+        const moved = movedSpecs(from, to, depth, terminal);
         return { color: moved.fg ?? wire.color, bgcolor: moved.bg ?? wire.bgcolor };
     }
 }
 /**
  * `renderable` under `effect` over time: an `Animation<Renderable>` whose
  * value at `t` is the element through the effect at `t`, placed wherever a
- * renderable goes. Its own answer to when it changes is `t`, at every time:
- * an `Effect` is made from what the element draws, so with nothing drawn
- * nothing can say more — early, never false. Placed, it says exactly: its
- * cells carry the effect's own hold at the frame's time and the output's
- * depth (`stampFrame`), under whatever the element already said, so at a
- * depth that shows no motion a loop says it never changes there and the
- * host sleeps.
+ * renderable goes. An `Effect` is made from what the element draws, so with
+ * nothing drawn its answer to when it changes is `t`, at every time: early,
+ * never false. Placed, on its own or as a part of any combinator, it says
+ * exactly: the frame's drawing told the effect's hold at that time and the
+ * output's depth (`Moves`), so at a depth that shows no motion a loop says it
+ * never changes there and the host sleeps.
  */
 export class Effected {
     renderable;
     effect;
     key;
-    theme;
     constructor(renderable, effect, options) {
         this.renderable = renderable;
         this.effect = effect;
         this.key = options.key;
-        this.theme = options.theme;
     }
     /** The element through the effect at `t`, unstamped. */
     at(t) {
-        return new Recolored(this.renderable, this.effect, { t, key: this.key, theme: this.theme });
+        return new Recolored(this.renderable, this.effect, { t, key: this.key });
     }
-    nextChange(t) {
-        return t;
+    nextChange(t, moves) {
+        return moves?.(t, this.key)?.nextChange ?? t;
     }
-    lastChange(t) {
-        return t;
+    lastChange(t, moves) {
+        return moves?.(t, this.key)?.lastChange ?? t;
     }
     /** The element under the effect with its motion taken out. */
     reduced() {
@@ -324,23 +328,22 @@ export class Effected {
     }
     /** Drawn at the frame's time, its cells stamped with the effect's exact hold there. */
     render(options) {
-        const { segments, hold } = this.at(frameTimeOf(options)).moved(options);
-        return stampFrame(segments, hold);
+        return placedRender(this, options);
     }
     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
+     * both as the screen shows them, at `depth` on `terminal`: 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) {
+    static shows(pair, to, depth, terminal) {
         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);
+        const moved = movedSpecs(from, onScreen(to, pair.reverse), depth, terminal);
+        return onScreen({ fg: moved.fg?.getTruecolor(terminal, true) ?? from.fg, bg: moved.bg?.getTruecolor(terminal, false) ?? from.bg }, pair.reverse);
     }
 }
 /**
@@ -352,17 +355,17 @@ export function cellSeed(key, row, col) {
     return Number.parseInt(fnv1a(`${key}:${row}:${col}`), 16) / 0x1_0000_0000;
 }
 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) {
+/** Each of `segments` with how it is drawn at `depth` on `terminal`; a control segment draws nothing. */
+function looks(segments, depth, terminal) {
     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 slots = { fg: (wire.color ?? DEFAULT).getTruecolor(terminal, true), bg: (wire.bgcolor ?? DEFAULT).getTruecolor(terminal, false) };
         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 }, attributes: cellAttributes(style), seam: drawnBy(style.anchor, JOIN) } };
+        const own = onScreen({ fg: wire.color?.isDefault ?? true, bg: wire.bgcolor?.isDefault ?? true }, reverse);
+        return { segment, look: { style, wire, slots, pair: { ...onScreen(slots, reverse), terminal: own, reverse }, attributes: cellAttributes(style), seam: drawnBy(style.anchor, JOIN) } };
     });
 }
 /**
@@ -381,10 +384,11 @@ export function walkGlyphs(segments) {
         if (segment.isControl)
             return [];
         const anchor = segment.style?.anchor;
+        const boxFrame = segment.style?.boxFrame;
         // Cells into the segment, as `base.shiftedBy` counts them in the render.
         let into = 0;
         return [...graphemes(segment.text)].map((glyph) => {
-            const cell = glyph === "\n" ? undefined : { row, col, anchor: anchor && shiftAnchor(anchor, into) };
+            const cell = glyph === "\n" ? undefined : { row, col, anchor: anchor && shiftAnchor(anchor, into), boxFrame };
             const width = cellLen(glyph);
             [row, col] = glyph === "\n" ? [row + 1, 0] : [row, col + width];
             into += width;
@@ -451,12 +455,12 @@ function drawsLines(style) {
 /**
  * What `looked` draws: `Drawn`'s measure, taken once per frame. Its `all`
  * and `cells` are listed off `walked` the first time either is asked for,
- * since only an effect spread over the element or turning its runs asks, and
+ * since an effect on attributes alone never 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;
+function measured(looked, walked, depth, terminal) {
+    const ground = terminal.backgroundColor.hex;
     // [LAW:one-source-of-truth] One listing, each cell with whether it shows; `all` and `cells` are read off it.
     let everything;
     const list = () => walked().flatMap(({ look, glyphs }) => {
@@ -480,7 +484,7 @@ function measured(looked, walked, depth, theme) {
         colors: new Set([...own("fg"), ...own("bg")]),
         fills: new Set(own("bg")),
         depth,
-        theme,
+        terminal,
     };
 }
 /**
@@ -503,18 +507,24 @@ export function confined(effect, ...owners) {
         return false;
     };
     // The frame as the effect sees it: the owners' cells alone. [LAW:one-source-of-truth] One narrowing, handed to both stages.
-    const narrowed = (drawn) => ({ ...drawn, all: () => drawn.all().filter(owned), cells: () => drawn.cells().filter(owned) });
+    const narrowed = (drawn) => {
+        let all;
+        let cells;
+        return { ...drawn, all: () => (all ??= drawn.all().filter(owned)), cells: () => (cells ??= drawn.cells().filter(owned)) };
+    };
     // The owners' cells change when the effect's frame does.
     return (drawn) => Animation.map(effect(narrowed(drawn)), (frame) => (look, cell) => (owned(cell) ? frame(look, cell) : look));
 }
 /**
- * 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.
+ * What `segments`, drawn at `depth` on `terminal`, draw their words in, measured
+ * as `Effected` measures its child for every frame, so `options.terminal` means
+ * here what it means on a frame. Measure an element's output under an effect to
+ * read the contrast its words are left at.
  */
-export function drawnOf(segments, depth, theme) {
-    const looked = looks(segments, depth, theme);
-    return measured(looked, () => walk(looked), depth, theme);
+export function drawnOf(segments, depth, terminal) {
+    const on = resolveTerminal(terminal, depth);
+    const looked = looks(segments, depth, on);
+    return measured(looked, () => walk(looked), depth, on);
 }
 /**
  * A style's colour slots as the screen shows them, or the reverse: `reverse`
@@ -531,11 +541,11 @@ function onScreen(slots, reverse) {
  * (`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) {
+function movedSpecs(from, to, depth, terminal) {
     // [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) };
+    return { fg: ColorSpec.matchMove(from.fg, glyph, depth, terminal, true), bg: ColorSpec.matchMove(from.bg, ground, depth, terminal, false) };
 }
 /**
  * Whether two cells' colours are written alike. A slot with no colour is not

package/dist/renderables/effects.d.ts

@@ -73,7 +73,7 @@ export interface Loop {
  * How much of `touch` each of `colors` (hex) can take: the largest share in
  * [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, in the colours `Effected` writes it in at `drawn`'s depth and theme.
+ * lower, in the colours `Effected` writes it in at `drawn`'s depth and terminal.
  * 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.
@@ -85,7 +85,7 @@ 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, depth, theme }: Drawn, colors: ReadonlySet<string>, touch: Touch): Map<string, number>;
+export declare function shares({ pairs, depth, terminal }: 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
@@ -93,10 +93,10 @@ export declare function shares({ pairs, depth, theme }: Drawn, colors: ReadonlyS
  * (`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
+ * moves (`stillWhereNothingMoves`). `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
+ * points out of. A colour the terminal supplies (`Pair.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
@@ -122,7 +122,7 @@ export declare function onColors(loop: Loop, colors?: ReadonlySet<string>): Effe
  * body. The element is where its frame lists
  * cells, as the fireflies read it, so a padded or confined element has the
  * ramp across what it shows. On a sixteen-colour terminal nothing moves
- * (`stillOnSlots`): a gradient there is jumps between slots, and the cells
+ * (`stillWhereNothingMoves`): a gradient there is jumps between slots, and the cells
  * hold as drawn.
  */
 export declare function gradient(ramp: Animation<ColorRamp>, colors?: readonly string[]): Effect;
@@ -264,7 +264,7 @@ export declare function sparkle(curve: Curve, glow: ColorRgba, z: number): Loop;
 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
+ * (`Drawn.terminal`) 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
@@ -360,9 +360,38 @@ export declare function dissolveOut(curve: Curve, z: number): Transition;
  * 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`).
+ * terminal's. On a sixteen-colour terminal nothing turns (`stillWhereNothingMoves`).
  */
 export declare function wheel(curve: Curve, z: number): Effect;
+/**
+ * Several effects on one element, as one effect: each layer is handed the look
+ * the one before it left and the same cell, so later layers are on top, and each
+ * recognises a cell by what the element drew (`EffectCell.pair`), never by the
+ * colour it is handed. A hue a layer turned onto another of the element's
+ * colours is not mistaken for it, and turns once. It changes when the soonest
+ * layer does, and with no layers it leaves every cell as drawn.
+ *
+ * Every word reads at its floor (`floorOf`), whatever the layers did and in
+ * whatever order. Each loop proves that for colours as the element drew them,
+ * and a colour another layer moved voids the proof: light lands at another
+ * luminance on a turned hue. So once the layers have moved a cell, its ground
+ * lands where its inks can still read (`groundBounds`), a function of the colour
+ * alone so one fill stays one fill, and an ink that does not read on it slides
+ * to the luminance that does, on the side of the ground it stands on while that
+ * side has room. A layer that takes an ink across its ground crosses it here too:
+ * nothing reads at the crossing, so the word jumps it. [LAW:single-enforcer]
+ * Both are measured as `Effected` writes them, and both hand back what they were
+ * given where it already holds, so a layer that proved its own floor is drawn as
+ * it would be alone. A frame that takes a ground past its bounds is the one
+ * exception, whatever its ink reads: a swap of ink and ground lands at the floor,
+ * since a bound cannot ask what one cell's ink does without splitting a fill.
+ * The floor outranks a colour being the terminal's: a terminal
+ * ink is moved here where a ground under it left it unreadable. The rule is the
+ * same for one layer as for five: a veil (`veiled`, or a transition's `effect`)
+ * stops at the floor here, so a transition goes in an `Effected` around this
+ * one, as a lifecycle places it.
+ */
+export declare function layered(...effects: readonly Effect[]): Effect;
 /** One step of a signal: the ink it draws, and how long it is held, in seconds. */
 export interface ColorStep {
     readonly color: ColorRgba;
@@ -381,7 +410,7 @@ export interface ColorStep {
  * (`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
+ * that does (`stillWhereNothingMoves`). A cell whose ground no offered colour reads
  * on keeps the ink it rested in.
  *
  * The search is settled once for each ground and step — below truecolor,