@promptctl/rich-js 0.26.0 → 0.28.0

package/dist/renderables/effects.js

@@ -87,7 +87,7 @@ const SIDES = ["fg", "bg"];
  * 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.
@@ -99,7 +99,7 @@ const SIDES = ["fg", "bg"];
  * the fill room to glow — and a darker colour left as it is always holds,
  * because its lighter partner was settled against exactly that.
  */
-export function shares({ pairs, depth, theme }, colors, touch) {
+export function shares({ pairs, depth, terminal }, colors, touch) {
     // [LAW:one-source-of-truth] A slot shows a subject colour, by hex, only
     // where the element writes it: the reading `onColors` lights by.
     const own = (pair, side) => (pair.terminal[side] ? undefined : pair[side].hex);
@@ -126,7 +126,7 @@ export function shares({ pairs, depth, theme }, colors, touch) {
             const floor = floorOf(pair, depth);
             const at = (side, w) => touchedAt(touch, pair[side], (side === mine ? share : theirs) * w);
             return STRENGTHS.every((w) => {
-                const shown = Effected.shows(pair, { fg: at("fg", w), bg: at("bg", w) }, depth, theme);
+                const shown = Effected.shows(pair, { fg: at("fg", w), bg: at("bg", w) }, depth, terminal);
                 return contrastRatio(shown.fg, shown.bg) >= floor;
             });
         });
@@ -146,10 +146,10 @@ export function shares({ pairs, depth, theme }, colors, touch) {
  * (`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
@@ -158,12 +158,13 @@ export function shares({ pairs, depth, theme }, colors, touch) {
  */
 export function onColors(loop, colors) {
     const settled = new WeakMemo();
+    const litIn = (drawn) => colors ?? drawn.colors;
     const settle = (drawn) => {
-        const lit = colors ?? drawn.colors;
+        const lit = litIn(drawn);
         const key = [drawnKey(drawn), "|", ...lit].join(" ");
-        return settled.get(drawn.theme, () => new Memo()).get(key, () => shares(drawn, lit, loop.touch));
+        return settled.get(drawn.terminal, () => new Memo()).get(key, () => shares(drawn, lit, loop.touch));
     };
-    return stillOnSlots(atShares(loop, settle));
+    return stillWhereNothingMoves(SIDES, litIn, atShares(loop, settle));
 }
 /** What a frame draws, as a key: its depth and its pairs, which its `colors` and `fills` are read off. */
 function drawnKey({ depth, pairs }) {
@@ -198,7 +199,7 @@ function pairKey({ fg, bg, terminal, reverse }) {
  * 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 function gradient(ramp, colors) {
@@ -209,16 +210,16 @@ export function gradient(ramp, colors) {
     // [LAW:one-source-of-truth] A colour named as a style spells it is lit
     // wherever a cell shows it, so it is resolved as `Effected` resolves a
     // cell's ink: drawn at the frame's depth, then read on its terminal.
-    const shown = (spec, { depth, theme }) => (Style.fromColor(spec).drawnColors(depth).color ?? ColorSpec.default()).getTruecolor(theme, true).hex;
-    return stillOnSlots((drawn) => {
-        const lit = named === undefined ? drawn.colors : new Set(named.map((spec) => shown(spec, drawn)));
+    const shown = (spec, { depth, terminal }) => (Style.fromColor(spec).drawnColors(depth).color ?? ColorSpec.default()).getTruecolor(terminal, true).hex;
+    const litIn = (drawn) => (named === undefined ? drawn.colors : new Set(named.map((spec) => shown(spec, drawn))));
+    return stillWhereNothingMoves(["fg"], litIn, (drawn, lit) => {
         const inkOn = legible(drawn);
         const [left, right] = extent(drawn.cells().map((cell) => cell.col));
         return Animation.map(ramp, (now) => {
             const first = now.stops[0].at;
             const span = now.stops[now.stops.length - 1].at - first;
             const along = (col) => now.at(first + (span * (col - left + 0.5)) / (right - left + 1));
-            return (look, cell) => (cell.terminal.fg || !lit.has(look.fg.hex) ? look : { ...look, fg: inkOn(along(cell.col), look, cell) });
+            return (look, { col, pair }) => (pair.terminal.fg || !lit.has(pair.fg.hex) ? look : { ...look, fg: inkOn(along(col), pair) });
         });
     });
 }
@@ -245,17 +246,20 @@ export function atShares(loop, share) {
             const field = loop.field(t, drawn);
             return (look, cell) => {
                 const w = Math.round(clamp01(field(cell)) * LEVELS) / LEVELS;
-                const moved = (color, terminal) => touchedAt(loop.touch, color, (terminal ? 0 : (shared.get(color.hex) ?? 0)) * w);
-                return { ...look, fg: moved(look.fg, cell.terminal.fg), bg: moved(look.bg, cell.terminal.bg) };
+                // [LAW:one-source-of-truth] A share belongs to the colour the element drew; the touch falls on what is there now.
+                const moved = (side) => touchedAt(loop.touch, look[side], (cell.pair.terminal[side] ? 0 : (shared.get(cell.pair[side].hex) ?? 0)) * w);
+                return { ...look, fg: moved("fg"), bg: moved("bg") };
             };
         });
     };
 }
 /**
- * `loop` as drawn at the frame's depth: where the depth writes only the
+ * `loop` as drawn at the frame's depth and on the colours it moves on `sides`
+ * (`litIn`): where the depth writes only the
  * sixteen ANSI slots, or no colour, a move that shows at all is a jump to
  * another slot, and a light on an element never jumps — so there it
- * holds every cell still, and anywhere else it moves. [LAW:single-enforcer]
+ * holds every cell still, as it does where no cell that shows anything has
+ * one of those colours of its own there, and anywhere else it moves. [LAW:single-enforcer]
  * `onColors`, `wheel` and `gradient` draw through this, so every loop in the catalogue
  * meets the sixteen-colour terminal here. `atShares` does not: a progress
  * bar's pulse is the news that work is going on, and flashes a slot as
@@ -263,8 +267,12 @@ export function atShares(loop, share) {
  * A frame held still never changes, and says so, so a host drawing the
  * loop on such a terminal draws it once.
  */
-function stillOnSlots(loop) {
-    return (drawn) => (onlySlots(drawn.depth) ? Animation.constant((look) => look) : loop(drawn));
+function stillWhereNothingMoves(sides, litIn, loop) {
+    return (drawn) => {
+        const lit = litIn(drawn);
+        const shows = ({ pair }) => sides.some((side) => !pair.terminal[side] && lit.has(pair[side].hex));
+        return onlySlots(drawn.depth) || !drawn.cells().some(shows) ? Animation.constant((look) => look) : loop(drawn, lit);
+    };
 }
 /** Whether `depth` writes nothing between the slots it has: the sixteen, at either sixteen-colour depth, or none. */
 function onlySlots(depth) {
@@ -618,7 +626,7 @@ export function sparkle(curve, glow, z) {
 }
 /**
  * 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
@@ -627,7 +635,7 @@ export function sparkle(curve, glow, z) {
 export function veiled(visibility, swing) {
     return (drawn) => {
         // [LAW:one-source-of-truth] The ground is the terminal `Effected` draws on, never a second one handed here.
-        const ground = Oklch.fromRgba(drawn.theme.backgroundColor);
+        const ground = Oklch.fromRgba(drawn.terminal.backgroundColor);
         return Animation.continuous((t) => {
             const shows = visibility(t, drawn);
             return (look, cell) => {
@@ -675,7 +683,7 @@ export class Transition {
         this.schedule = schedule;
     }
     done(t) {
-        return this.schedule.nextChange(t) === Number.POSITIVE_INFINITY;
+        return Animation.done(this.schedule, t);
     }
 }
 /**
@@ -685,8 +693,13 @@ export class Transition {
  * glyph effect (`./glyph-effects.ts`) alike.
  */
 export function transition(seconds, effect) {
-    // Moving every frame until `seconds`, then never: the sequence carries the switch.
-    const schedule = Animation.sequence(Animation.continuous(() => undefined), seconds, Animation.constant(undefined));
+    // Moving every frame until `seconds`, then never: the sequence carries the switch. [LAW:one-source-of-truth]
+    // Reduced, a one-shot cuts from its start to its end at 0, and its schedule says so too, the one word on
+    // when the reduced frames change, so a half that lends this schedule to its frames tells the same hold.
+    const schedule = Animation.of({
+        ...Animation.sequence(Animation.continuous(() => undefined), seconds, Animation.constant(undefined)),
+        reduced: () => Animation.cut(undefined, undefined),
+    });
     const ran = new Transition((drawn) => {
         const moving = effect(drawn);
         return Animation.of({
@@ -948,7 +961,7 @@ function segmentsOf(drawn) {
  * 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 function wheel(curve, z) {
     requireCurve(curve);
@@ -967,23 +980,23 @@ export function wheel(curve, z) {
     const turned = (place, t) => (360 * t) / P + curve.swing * STRAY * ((stray(place, t) - stray(place, 0)) / 1.5);
     // A turned colour's bounds rest on what a frame draws, never on `t`: settled once for each.
     const settled = new WeakMemo();
-    return stillOnSlots((drawn) => {
-        const { colors, fills, depth, theme } = drawn;
+    return stillWhereNothingMoves(SIDES, ({ colors }) => colors, (drawn) => {
+        const { colors, fills, depth, terminal } = drawn;
         // Whether a slot shows one of the element's colours: never the terminal's, whatever its hex.
-        const own = (terminal, color) => !terminal && colors.has(color.hex);
+        const own = (supplied, color) => !supplied && colors.has(color.hex);
         // The colour an own colour is bounded with, under which its bounds are
         // kept: itself if a fill or beside no own colour, else the ground beside
         // it. Where it turns is `segmentsOf`'s, not this.
         const boundWith = (color, other, theirs) => (fills.has(color.hex) || !theirs ? color.hex : other.hex);
         // The bounds a colour turns within, by the colour it is bounded with: one bound for every place a frame writes it at.
         const keyOf = (color, bound) => `${color.hex} ${bound}`;
-        const bounds = settled.get(theme, () => new Memo()).get(drawnKey(drawn), () => turnedBounds(drawn.pairs, depth, (pair, side) => {
+        const bounds = settled.get(terminal, () => new Memo()).get(drawnKey(drawn), () => turnedBounds(drawn.pairs, depth, (pair, side) => {
             const other = side === "fg" ? "bg" : "fg";
             return own(pair.terminal[side], pair[side]) ? keyOf(pair[side], boundWith(pair[side], pair[other], own(pair.terminal[other], pair[other]))) : undefined;
         }));
         // 256 colours writes a turned colour as one it has an index for; truecolor
         // as one of the two either side of its luminance.
-        const indexed = measuredIndexed(depth, theme);
+        const indexed = measuredIndexed(depth, terminal);
         // Where each cell's colours turn, read off the frame's listing once.
         const placeOf = segmentsOf(drawn);
         return Animation.continuous((t) => {
@@ -992,20 +1005,26 @@ export function wheel(curve, z) {
             // key is the bounds' key with the place, so one entry never serves
             // two bounds.
             const written = new Map();
-            const choose = (color, bound, place) => {
+            // The bounds are measured from the colour the element drew; a layer
+            // beneath may have lit it, so they travel with it, and a lit colour
+            // turns round its own luminance rather than snapping back unturned.
+            const choose = (color, rested, bound, place) => {
                 const turn = hueTurned(color, turned(place, t));
-                return nearestWithin(turn.looks, color, depth === ColorDepth.TRUECOLOR ? turn.either.map(measured) : indexed, bounds.get(keyOf(color, bound)) ?? UNBOUNDED);
+                const { lo, hi } = bounds.get(keyOf(rested, bound)) ?? UNBOUNDED;
+                const lit = stop(color) - stop(rested);
+                return nearestWithin(turn.looks, color, depth === ColorDepth.TRUECOLOR ? turn.either.map(measured) : indexed, { lo: lo + lit, hi: hi + lit });
             };
-            const write = (color, bound, place) => {
-                const key = `${keyOf(color, bound)} ${place.row}:${place.centre}`;
-                const found = written.get(key) ?? choose(color, bound, place);
+            const write = (color, rested, bound, place) => {
+                const key = `${color.hex} ${keyOf(rested, bound)} ${place.row}:${place.centre}`;
+                const found = written.get(key) ?? choose(color, rested, bound, place);
                 written.set(key, found);
                 return found;
             };
             return (shown, cell) => {
-                const mine = { fg: own(cell.terminal.fg, shown.fg), bg: own(cell.terminal.bg, shown.bg) };
-                const turn = (color, ours, other, theirs) => ours ? write(color, boundWith(color, other, theirs), placeOf(cell, color.hex)) : color;
-                return { ...shown, fg: turn(shown.fg, mine.fg, shown.bg, mine.bg), bg: turn(shown.bg, mine.bg, shown.fg, mine.fg) };
+                const { pair } = cell;
+                const mine = { fg: own(pair.terminal.fg, pair.fg), bg: own(pair.terminal.bg, pair.bg) };
+                const turn = (side, other) => mine[side] ? write(shown[side], pair[side], boundWith(pair[side], pair[other], mine[other]), placeOf(cell, pair[side].hex)) : shown[side];
+                return { ...shown, fg: turn("fg", "bg"), bg: turn("bg", "fg") };
             };
         });
     });
@@ -1022,10 +1041,16 @@ export function wheel(curve, z) {
  * off (`touchedAt`).
  */
 function hueTurned(color, degrees) {
-    if (degrees === 0)
-        return { looks: color, either: [color] };
+    return degrees === 0 ? { looks: color, either: [color] } : atLuminance(color, degrees, relativeLuminance(color));
+}
+/** `color` with its chroma taken out. */
+function greyOf(color) {
+    const { l, h, alpha } = Oklch.fromRgba(color);
+    return new Oklch(l, 0, h, alpha).toRgba();
+}
+/** `color` turned `degrees` round the hue circle and brought to `luminance`: the two 8-bit colours either side of it. */
+function atLuminance(color, degrees, luminance) {
     const from = Oklch.fromRgba(color);
-    const luminance = relativeLuminance(color);
     const at = (l) => new Oklch(l, from.c, from.h + degrees, from.alpha).toRgba();
     let [dim, bright] = [0, 1];
     for (let i = 0; i < 24; i++) {
@@ -1085,10 +1110,10 @@ function turnedBounds(pairs, depth, turnedAs) {
     return new Map([...bounds].map(([key, { lo, hi }]) => [key, hi - lo < ROUNDING_GAP ? STILL : { lo, hi }]));
 }
 const measured = (color) => ({ color, looks: Oklch.fromRgba(color), stop: stop(color) });
-/** `ColorSpec.indexed`'s colours, measured once for each theme and depth. */
+/** `ColorSpec.indexed`'s colours, measured once for each terminal and depth. */
 const measuredMemo = new WeakMemo();
-function measuredIndexed(depth, theme) {
-    return measuredMemo.get(ColorSpec.indexed(depth, theme), (indexed) => indexed.map(([, color]) => measured(color)));
+function measuredIndexed(depth, terminal) {
+    return measuredMemo.get(ColorSpec.indexed(depth, terminal), (indexed) => indexed.map(([, color]) => measured(color)));
 }
 /**
  * The colour that looks nearest `color` (OKLab's ΔE): `rest`, or one of
@@ -1110,6 +1135,120 @@ function nearestOf(color, offered) {
     }
     return best?.[0];
 }
+/** What a stop's float arithmetic can cost: a pair at its floor sits exactly on its bound. */
+const MEASURE = 1e-9;
+/**
+ * The stops a colour written at `depth` can land on: everything between black
+ * and white in truecolor, and otherwise what the depth has an index for, so a
+ * sixteen-colour terminal's reach is its slots.
+ */
+function reachOf(depth, terminal) {
+    return depth === ColorDepth.TRUECOLOR ? [0, Math.log(21)] : extent(measuredIndexed(depth, terminal).map((candidate) => candidate.stop));
+}
+/**
+ * Where each ground of `pairs` may land so that every ink drawn on it keeps
+ * room to read on the side of it the ink rested on: a light ink caps its ground
+ * at the floor below the lightest the depth writes, a dark one bars it from the
+ * floor above the darkest. Where a ground rests is always within: a depth also
+ * writes the terminal's own colour, which at sixteen colours lies past its
+ * terminal's reach, and a ground no layer moved comes back as it was. These are
+ * what the depth's reach leaves, so a ground any one effect moves is inside them.
+ */
+function groundBounds(pairs, depth, terminal) {
+    const [bottom, top] = reachOf(depth, terminal);
+    const bounds = new Map();
+    for (const pair of pairs) {
+        const [gap, rests] = [Math.log(floorOf(pair, depth)), stop(pair.bg)];
+        const { lo, hi } = bounds.get(pair.bg.hex) ?? UNBOUNDED;
+        bounds.set(pair.bg.hex, stop(pair.fg) >= rests ? { lo, hi: Math.min(hi, Math.max(rests, top - gap)) } : { lo: Math.max(lo, Math.min(rests, bottom + gap)), hi });
+    }
+    return bounds;
+}
+/**
+ * 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 function layered(...effects) {
+    const settled = new WeakMemo();
+    return (drawn) => {
+        const { depth, terminal } = drawn;
+        const grounds = settled.get(terminal, () => new Memo()).get(drawnKey(drawn), () => groundBounds(drawn.pairs, depth, terminal));
+        const words = new Set(drawn.pairs.map(pairKey));
+        const offered = depth === ColorDepth.TRUECOLOR ? undefined : measuredIndexed(depth, terminal);
+        // `color` as itself if it is within the first of `bounds`, else the nearest
+        // colour the depth writes there, else the same of the next; as itself where
+        // none has any. In truecolor that is its hue at the bound's luminance, or a
+        // grey there: a colour keeps its chroma only so near black or white, and a
+        // bound may be at either. `rested` is always offered, since a depth also
+        // writes the terminal's own colour, which it has no index for, and the
+        // colour a pair rested in is the one a bound was measured from.
+        const landing = (color, rested, ...bounds) => {
+            const at = stop(color);
+            for (const { lo, hi } of bounds) {
+                const inside = (stop) => stop >= lo - MEASURE && stop <= hi + MEASURE;
+                if (inside(at))
+                    return color;
+                const aim = 0.05 * Math.exp(Math.min(hi, Math.max(lo, at))) - 0.05;
+                const found = nearestOf(color, [measured(rested), ...(offered ?? [color, greyOf(color)].flatMap((from) => atLuminance(from, 0, aim).either.map(measured)))].filter(({ stop }) => inside(stop)));
+                if (found !== undefined)
+                    return found.color;
+            }
+            return color;
+        };
+        const floored = (pair, moved) => {
+            // [LAW:single-enforcer] Every measure below reads the colours as `Effected`
+            // writes them: rounded to the depth, and a translucent one laid on what is
+            // beneath it, so a colour that passes here cannot draw as one that fails.
+            const ground = landing(Effected.shows(pair, moved, depth, terminal).bg, pair.bg, grounds.get(pair.bg.hex) ?? UNBOUNDED);
+            const { fg } = Effected.shows(pair, { fg: moved.fg, bg: ground }, depth, terminal);
+            const floor = floorOf(pair, depth);
+            if (!words.has(pairKey(pair)) || contrastRatio(fg, ground) >= floor)
+                return { fg, bg: ground };
+            const gap = Math.log(floor);
+            const [above, below] = [{ lo: stop(ground) + gap, hi: Infinity }, { lo: -Infinity, hi: stop(ground) - gap }];
+            // The side it stands on, not the one it rested on: a painter's ink may
+            // stand across the ground, and aiming it back would strobe it there and
+            // back each time a move took it under the floor.
+            const [near, far] = stop(fg) >= stop(ground) ? [above, below] : [below, above];
+            return { fg: landing(fg, pair.fg, near, far), bg: ground };
+        };
+        return Animation.map(Animation.all(effects.map((effect) => effect(drawn))), (frames) => {
+            // A colour pair lands once a frame, wherever it falls. [LAW:one-source-of-truth]
+            const landed = new Map();
+            return (look, cell) => {
+                const moved = frames.reduce((under, frame) => frame(under, cell), look);
+                const key = `${pairKey(cell.pair)} ${moved.fg.hex} ${moved.bg.hex}`;
+                const colors = landed.get(key) ?? floored(cell.pair, moved);
+                landed.set(key, colors);
+                return { ...moved, ...colors };
+            };
+        });
+    };
+}
 /**
  * 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
@@ -1123,7 +1262,7 @@ function nearestOf(color, offered) {
  * (`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,
@@ -1144,12 +1283,12 @@ export function steppedInk(steps) {
         const inkOn = legible(drawn);
         return Animation.map(rhythm, (i) => {
             const step = inks[i];
-            return (look, cell) => ({ ...look, fg: inkOn(step, look, cell) });
+            return (look, { pair }) => ({ ...look, fg: inkOn(step, pair) });
         });
     };
 }
 /**
- * `legibleInk` for the frame `Drawn` describes, of an ink on a cell's look:
+ * `legibleInk` for the frame `Drawn` describes, of an ink on a cell's pair:
  * settled once for each terminal, depth, pair and ink, so a frame drawing
  * what an earlier one drew redoes no search. [LAW:single-enforcer] Every
  * effect that writes an ink of the caller's choosing writes it through
@@ -1162,16 +1301,15 @@ export function steppedInk(steps) {
  */
 function legibleInks() {
     const settled = new WeakMemo();
-    return ({ depth, theme }) => {
-        const memo = settled.get(theme, () => ({ inks: new Memo(), readable: new Memo() }));
-        return (ink, look, cell) => {
-            const pair = { fg: look.fg, bg: look.bg, terminal: cell.terminal, reverse: cell.reverse };
+    return ({ depth, terminal }) => {
+        const memo = settled.get(terminal, () => ({ inks: new Memo(), readable: new Memo() }));
+        return (ink, pair) => {
             const key = `${depth} ${pairKey(pair)}`;
-            const legibleOf = (offered) => legibleAmong(pair, offered, depth, theme);
+            const legibleOf = (offered) => legibleAmong(pair, offered, depth, terminal);
             return memo.inks.get(`${key} ${ink.hex}`, () => {
                 const offered = depth === ColorDepth.TRUECOLOR
                     ? legibleOf([ink, ensureContrast(ink, pair.bg, floorOf(pair, depth))].map(measured))
-                    : memo.readable.get(key, () => legibleOf(measuredIndexed(depth, theme)));
+                    : memo.readable.get(key, () => legibleOf(measuredIndexed(depth, terminal)));
                 return nearestOf(ink, offered)?.color ?? pair.fg;
             });
         };
@@ -1183,10 +1321,10 @@ function legibleInks() {
  * way `shares` and `wheel` measure: the written colours, at the catalogue's
  * floor. An ink none of them is nearest stays `pair`'s own.
  */
-function legibleAmong(pair, offered, depth, theme) {
+function legibleAmong(pair, offered, depth, terminal) {
     const floor = floorOf(pair, depth);
     return offered.filter(({ color }) => {
-        const shown = Effected.shows(pair, { fg: color, bg: pair.bg }, depth, theme);
+        const shown = Effected.shows(pair, { fg: color, bg: pair.bg }, depth, terminal);
         return contrastRatio(shown.fg, shown.bg) >= floor;
     });
 }

package/dist/renderables/frames.d.ts

@@ -46,7 +46,7 @@
  */
 import { Animation } from "../core/animation.js";
 import { type Beat } from "../core/easing.js";
-import type { Motion, RenderOptions } from "../core/protocol.js";
+import type { RenderOptions } from "../core/protocol.js";
 import type { Segment } from "../core/segment.js";
 import { RichText } from "../core/text.js";
 /** One frame: what it shows, and how long it is held, in seconds. */
@@ -86,12 +86,3 @@ export declare class FrameSequence implements Animation<RichText> {
         maximum: number;
     };
 }
-/**
- * The text frame `animation` shows at host time `t` under `motion`
- * (`shownAt`), copied and stamped with the hold it is in there: what the
- * template `frames` and `glyphs` functions, which know the reader's
- * preference before any render, splice into a line. The stamp is on the
- * base style, which an empty text still draws as its one piece of no width,
- * and on a copy, since an animation may hand back the one `RichText` it holds.
- */
-export declare function textFrameAt(animation: Animation<RichText>, t: number, motion: Motion): RichText;

package/dist/renderables/frames.js

@@ -44,9 +44,8 @@
  * binding has no console for, so the frame arrives read, as a `Group`'s
  * children do.
  */
-import { Animation, holdOf, placedRender, shownAt, stamp } from "../core/animation.js";
+import { Animation, placedRender } from "../core/animation.js";
 import { beat } from "../core/easing.js";
-import { layerStyle } from "../core/style.js";
 import { setIntoLine } from "./embed.js";
 /** A sequence of frames prepared to be drawn: built once, asked for the frame at a time. */
 export class FrameSequence {
@@ -102,17 +101,3 @@ export class FrameSequence {
         return { minimum: this.width, maximum: this.width };
     }
 }
-/**
- * The text frame `animation` shows at host time `t` under `motion`
- * (`shownAt`), copied and stamped with the hold it is in there: what the
- * template `frames` and `glyphs` functions, which know the reader's
- * preference before any render, splice into a line. The stamp is on the
- * base style, which an empty text still draws as its one piece of no width,
- * and on a copy, since an animation may hand back the one `RichText` it holds.
- */
-export function textFrameAt(animation, t, motion) {
-    const shown = shownAt(animation, t, motion);
-    const stamped = shown.value.copy();
-    stamped.style = layerStyle(stamped.style, stamp(holdOf(shown, t)));
-    return stamped;
-}

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

@@ -51,11 +51,11 @@
  * Positions are the child's own: row and column count from the top-left of
  * what the child drew.
  */
-import { Animation } from "../core/animation.js";
+import { Animation, type Moves } from "../core/animation.js";
 import type { Measurable, Renderable, RenderOptions } from "../core/protocol.js";
 import { Segment } from "../core/segment.js";
 import { type RichText } from "../core/text.js";
-import { type Moved, type Placed } from "./effect.js";
+import { type Placed } from "./effect.js";
 /**
  * A cell of the element a glyph effect wraps: the glyph it shows, where it
  * sits and who drew it, its place in reading order among the cells handed
@@ -95,20 +95,18 @@ export interface GlyphEffectedOptions {
 /**
  * A `GlyphEffected` at `t`, or an element through a glyph effect at a time an
  * animation's `at` was handed: `renderable` with its cells' glyphs passed
- * through `effect` at `t`, saying nothing of when that changes, as a
- * `Recolored` is (`./effect.ts`). [LAW:one-type-per-behavior]
+ * through `effect` at `t`, telling the hold it drew in as a `Recolored` does
+ * (`RenderOptions.onMoved`, `./effect.ts`). [LAW:one-type-per-behavior]
  */
 export declare class Reglyphed implements Renderable, Measurable {
     readonly renderable: Renderable;
     readonly effect: GlyphEffect;
-    readonly t: number;
+    private readonly _t;
     readonly key: string;
     constructor(renderable: Renderable, effect: GlyphEffect, options: GlyphEffectedOptions & {
         readonly t: number;
     });
     render(options: RenderOptions): Iterable<Segment>;
-    /** The frame the effect draws at `t`, and the hold it says that is in. */
-    moved(options: RenderOptions): Moved;
     measure(options: RenderOptions): {
         minimum: number;
         maximum: number;
@@ -116,9 +114,10 @@ export declare class Reglyphed implements Renderable, Measurable {
 }
 /**
  * `renderable` under a glyph effect over time, an `Animation<Renderable>`
- * as an `Effected` is (`./effect.ts`): its own answer is `t`, and placed,
- * its cells carry the glyph effect's exact hold at the frame's time and the
- * output's `asciiOnly`, under whatever the element already said.
+ * as an `Effected` is (`./effect.ts`): with nothing drawn its answer is `t`,
+ * and placed, on its own or as a part of any combinator, it says the glyph
+ * effect's exact hold at that time and the output's `asciiOnly`, which the
+ * frame's drawing told (`Moves`).
  */
 export declare class GlyphEffected implements Animation<Renderable> {
     readonly renderable: Renderable;
@@ -127,8 +126,8 @@ export declare class GlyphEffected implements Animation<Renderable> {
     constructor(renderable: Renderable, effect: GlyphEffect, options: GlyphEffectedOptions);
     /** The element through the glyph effect at `t`, unstamped. */
     at(t: number): Reglyphed;
-    nextChange(t: number): number;
-    lastChange(t: number): number;
+    nextChange(t: number, moves?: Moves): number;
+    lastChange(t: number, moves?: Moves): number;
     /** The element under the glyph effect with its motion taken out. */
     reduced(): GlyphEffected;
     /** Drawn at the frame's time, its cells stamped with the glyph effect's exact hold there. */
@@ -150,7 +149,7 @@ export declare class GlyphEffected implements Animation<Renderable> {
  * its every style and span, each moved to where its glyphs now sit, and a
  * frame that changes nothing hands the text back as it was. What it says of
  * when it changes is the effect's, unstamped: whoever draws it at a time
- * stamps it (`textFrameAt`).
+ * stamps it (`placed`), or marks it for the engine to (the template `glyphs`).
  */
 export declare function reglyphText(text: RichText, effect: GlyphEffect, options: {
     readonly key: string;