@promptctl/rich-js 0.24.0 → 0.25.0

package/dist/renderables/effects.js

@@ -1,7 +1,8 @@
 /**
  * The effect catalogue: shimmer, pulse, sparkle and wheel, which loop for as
- * long as they are drawn, and fade-in and dissolve-out, which run once and
- * are done. Each is an `Effect` for `Effected` (`./effect.ts`); the defaults
+ * long as they are drawn, fade-in and dissolve-out, which run once and are
+ * done, a blink and a bold pulse, which move an attribute on a beat, and a
+ * gradient, which lays a colour ramp across an element and may move it. Each is an `Effect` for `Effected` (`./effect.ts`); the defaults
  * in `EFFECT_CURVES` are the ones signed off by eye in the effects-feel demo
  * (`npm run effects-feel`), at 30 fps and at one frame a second, and
  * `EFFECT_CATALOGUE` makes every one of them at those, by name, one way.
@@ -13,7 +14,10 @@
  * 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
+ * loops hold still. Nor is `gradient` a light: it paints an ink rather than
+ * lighting it, so it may darken one, and a ramp scrolled across it jumps
+ * where the ramp wraps unless its ends are one colour. Of the list below it
+ * keeps the words. What makes the loops' motions familiar is what every
  * curve of theirs keeps:
  *
  * - Nothing jumps. Every curve is continuous in time, built from smooth
@@ -46,13 +50,15 @@
  * cards runs this file's own declarations as the program a visitor edits
  * (`examples/effects-playground/programs.ts`), on the published library.
  */
+import { Animation } from "../core/animation.js";
 import { ColorDepth, ColorRgba, ColorSpec, contrastRatio, relativeLuminance } from "../core/color.js";
 import { EASES, Phase, beat } from "../core/easing.js";
 import { fbm, hash, noise, smoothstep } from "../core/noise.js";
-import { Memo } from "../core/memo.js";
+import { Memo, WeakMemo } from "../core/memo.js";
 import { Oklch } from "../core/oklch.js";
+import { Style } from "../core/style.js";
 import { ensureContrast } from "../themes/colorMath.js";
-import { Effected, nextChangeOf, withNextChange } from "./effect.js";
+import { Effected } from "./effect.js";
 /** The contrast no touch takes a cell below, unless it rested below it: WCAG AA for body text. */
 const LEGIBLE = 4.5;
 /**
@@ -151,13 +157,11 @@ export function shares({ pairs, depth, theme }, colors, touch) {
  * drawing what an earlier one drew costs no settling.
  */
 export function onColors(loop, colors) {
-    const settled = new WeakMap();
+    const settled = new WeakMemo();
     const settle = (drawn) => {
         const lit = colors ?? drawn.colors;
         const key = [drawnKey(drawn), "|", ...lit].join(" ");
-        const memo = settled.get(drawn.theme) ?? new Memo();
-        settled.set(drawn.theme, memo);
-        return memo.get(key, () => shares(drawn, lit, loop.touch));
+        return settled.get(drawn.theme, () => new Memo()).get(key, () => shares(drawn, lit, loop.touch));
     };
     return stillOnSlots(atShares(loop, settle));
 }
@@ -176,20 +180,75 @@ function drawnKey({ depth, pairs }) {
 function pairKey({ fg, bg, terminal, reverse }) {
     return `${fg.hex}/${bg.hex}/${terminal.fg}/${terminal.bg}/${reverse}`;
 }
+/**
+ * A ramp laid across the element: each lit cell's ink is the colour `ramp`
+ * shows at `t` at the cell's column, the element's leftmost cell reading
+ * the ramp's first stop and its rightmost its last, each at its cell's
+ * centre — or, where that colour would not read on the cell's ground, the
+ * nearest that does (`legibleInks`, as `steppedInk` writes its steps). A
+ * ramp that moves (`ColorRamp.moving`) scrolls along the element and turns
+ * its hues, and the frame changes when the ramp does — every frame for a
+ * loop, never again once a tween settles; a still one is
+ * `Animation.constant(ramp)`. Lit cells are those whose ink is one of
+ * `colors`, named as a style names them (`"#a6e3a1"`, `"bright_green"`),
+ * opaque, and matched as the screen shows them at the frame's depth — so
+ * below truecolor every ink that lands on the same palette colour is lit —
+ * by default every colour the element sets itself — never an ink the terminal supplies: a
+ * rule's line by its colour and not its title, a panel's border and not its
+ * 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
+ * hold as drawn.
+ */
+export function gradient(ramp, colors) {
+    const legible = legibleInks();
+    // [LAW:parse-dont-validate] Parsed at the call, so a misspelt colour fails
+    // where it was written and not on some later frame.
+    const named = colors?.map(opaqueInk);
+    // [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 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) });
+        });
+    });
+}
+/**
+ * `spec` parsed as an ink `gradient` lights. Opaque only: a translucent ink
+ * is drawn over the ground of each cell it is in, so it shows as no one
+ * colour to match, and naming one is refused here.
+ */
+function opaqueInk(spec) {
+    const parsed = ColorSpec.parse(spec);
+    if (parsed.value !== undefined && parsed.value.alpha < 1)
+        throw new RangeError(`gradient lights opaque colours, and ${spec} is translucent`);
+    return parsed;
+}
 /**
  * A loop as an `Effect` on colours by hex, each touched at the share
  * `share` gives it of the cell's strength in a frame drawing what `Drawn`
  * says; a colour it gives none, and one the terminal supplies, stays as it is.
  */
 export function atShares(loop, share) {
-    return (t, drawn) => {
+    return (drawn) => {
         const shared = share(drawn);
-        const field = loop.field(t, drawn);
-        return ({ fg, bg }, cell) => {
-            const w = Math.round(clamp01(field(cell)) * LEVELS) / LEVELS;
-            const moved = (color, terminal) => touchedAt(loop.touch, color, (terminal ? 0 : (shared.get(color.hex) ?? 0)) * w);
-            return { fg: moved(fg, cell.terminal.fg), bg: moved(bg, cell.terminal.bg) };
-        };
+        return Animation.continuous((t) => {
+            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) };
+            };
+        });
     };
 }
 /**
@@ -197,7 +256,7 @@ export function atShares(loop, share) {
  * 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]
- * `onColors` and `wheel` draw through this, so every loop in the catalogue
+ * `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
  * Rich's does; nor does `steppedInk`, a signal, which steps slot to slot.
@@ -205,7 +264,7 @@ export function atShares(loop, share) {
  * loop on such a terminal draws it once.
  */
 function stillOnSlots(loop) {
-    return withNextChange((t, drawn) => (onlySlots(drawn.depth) ? (colors) => colors : loop(t, drawn)), (t, drawn) => (onlySlots(drawn.depth) ? Number.POSITIVE_INFINITY : nextChangeOf(loop, t, drawn)));
+    return (drawn) => (onlySlots(drawn.depth) ? Animation.constant((look) => look) : loop(drawn));
 }
 /** Whether `depth` writes nothing between the slots it has: the sixteen, at either sixteen-colour depth, or none. */
 function onlySlots(depth) {
@@ -228,12 +287,21 @@ function touchedAt(touch, color, w) {
     return w === 0 ? color : touch(color, w);
 }
 /** Throws, naming the field, unless `curve` has a positive, finite `seconds` and a `swing` in [0, 1]. */
-function requireCurve(curve) {
+export function requireCurve(curve) {
     if (!(Number.isFinite(curve.seconds) && curve.seconds > 0))
         throw new RangeError(`curve: seconds must be a positive number of seconds, got ${curve.seconds}`);
     if (!(curve.swing >= 0 && curve.swing <= 1))
         throw new RangeError(`curve: swing must be in [0, 1], got ${curve.swing}`);
 }
+/**
+ * Throws, naming `what`, unless `z` is a finite place in the noise. Noise at
+ * a place that is not a number is not a number, which no effect could tell
+ * from a dim cell or an empty sky. [LAW:no-silent-failure]
+ */
+export function requireZ(what, z) {
+    if (!Number.isFinite(z))
+        throw new RangeError(`${what} z must be a finite place in the noise, got ${z}`);
+}
 /**
  * Each effect's curve as it was signed off. Every loop's period is a prime
  * number of seconds, so no two loops come back into step within a sitting.
@@ -337,6 +405,7 @@ const FLASH = [[0.24, 1], [0.6, 0]];
  */
 export function pulse(curve, glow, z) {
     requireCurve(curve);
+    requireZ("pulse", z);
     // How much quicker or slower than `curve.seconds` this element beats.
     const rate = 0.9 + 0.2 * hash(z, 3.1);
     // How far, in beats, the rhythm wanders ahead and behind its metronome. Noise's
@@ -383,6 +452,7 @@ const bump = (d) => (Math.abs(d) >= 1 ? 0 : (1 - d * d) ** 3);
  */
 export function shimmer(curve, width, glow, z) {
     requireCurve(curve);
+    requireZ("shimmer", z);
     const P = curve.seconds;
     // Passes are events on slots of half a period. Whether slot `j` holds one,
     // and how bright, is the sky's: slow noise over the slots, so sunny and
@@ -470,6 +540,7 @@ export function shimmer(curve, width, glow, z) {
  */
 export function sparkle(curve, glow, z) {
     requireCurve(curve);
+    requireZ("sparkle", z);
     // The columns a firefly has to itself along a row of the lattice, and the
     // rows between two rows of it: more than a halo's reach, so a one-row
     // element is lit by one row of fireflies.
@@ -554,41 +625,87 @@ export function sparkle(curve, glow, z) {
  * hiding — 1 reaches fully invisible. A cell wholly shown is returned as it was.
  */
 export function veiled(visibility, swing) {
-    return (t, drawn) => {
-        const { theme } = drawn;
-        const shows = visibility(t, drawn);
+    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(theme.backgroundColor);
-        return (colors, cell) => {
-            const hidden = swing * (1 - clamp01(shows(cell)));
-            if (hidden === 0)
-                return colors;
-            const bg = blend(Oklch.fromRgba(colors.bg), ground, hidden);
-            return { fg: blend(Oklch.fromRgba(colors.fg), bg, hidden).toRgba(), bg: bg.toRgba() };
-        };
+        const ground = Oklch.fromRgba(drawn.theme.backgroundColor);
+        return Animation.continuous((t) => {
+            const shows = visibility(t, drawn);
+            return (look, cell) => {
+                const hidden = swing * (1 - clamp01(shows(cell)));
+                if (hidden === 0)
+                    return look;
+                const bg = blend(Oklch.fromRgba(look.bg), ground, hidden);
+                return { ...look, fg: blend(Oklch.fromRgba(look.fg), bg, hidden).toRgba(), bg: bg.toRgba() };
+            };
+        });
     };
 }
 /**
  * Where each cell falls in a transition's order, in [0, 1]: smooth noise over
  * the element, so neighbouring cells arrive or leave together, in patches
  * with soft edges, as ink spreads or mist thins. `z` places the element in
- * the noise. A cell's place never changes, so it is worked out once.
+ * the noise.
  */
 function order(z) {
-    const places = new Map();
-    return (cell) => {
-        const at = `${cell.row}:${cell.col}`;
-        // The noise is read through slower noise, so the patches reach out in
-        // curling tendrils rather than sitting as round blots.
-        const place = places.get(at) ??
-            clamp01(0.5 + 1.1 * fbm(cell.col * 0.09 + 1.4 * noise(cell.col * 0.035, cell.row * 0.2 + 2.6, z + 0.5), cell.row * 0.45, z, 3));
-        places.set(at, place);
-        return place;
-    };
+    // The noise is read through slower noise, so the patches reach out in
+    // curling tendrils rather than sitting as round blots.
+    return (cell) => clamp01(0.5 + 1.1 * fbm(cell.col * 0.09 + 1.4 * noise(cell.col * 0.035, cell.row * 0.2 + 2.6, z + 0.5), cell.row * 0.45, z, 3));
 }
-function transition(curve, effect) {
-    const done = (t) => t >= curve.seconds;
-    return { effect: withNextChange(effect, (t) => (done(t) ? Number.POSITIVE_INFINITY : t)), done };
+/**
+ * An effect that runs once: a fade-in or a dissolve-out over its curve's
+ * `seconds` from `t = 0`, its own clock as every effect's is — the caller
+ * draws it at the time since it began. `done(t)` is true from the moment
+ * every cell has arrived or gone, so the caller knows when to stop drawing an
+ * element that is leaving, or to drop the effect from one that has arrived.
+ *
+ * `schedule` is when its frame next changes on that clock, whatever the
+ * element draws: what a caller drawing the transition inside an animation —
+ * a lifecycle — says its frame does, since the frame it hands over carries
+ * no word of its own (`stampFrame`, `../core/animation.ts`). Until done it changes
+ * every frame, or on each hold of a beat (`onBeat`), and from then never.
+ * [LAW:one-source-of-truth] `done` is that schedule read as a fact — done
+ * from the first moment it never changes again — so no transition carries
+ * two answers to when it is over.
+ */
+export class Transition {
+    effect;
+    schedule;
+    constructor(effect, schedule) {
+        this.effect = effect;
+        this.schedule = schedule;
+    }
+    done(t) {
+        return this.schedule.nextChange(t) === Number.POSITIVE_INFINITY;
+    }
+}
+/**
+ * `effect` run once over `seconds` as a `Transition`: what it draws until it
+ * is done, then held. [LAW:single-enforcer] The one rule for when a
+ * transition is done and what it answers after, for a colour effect and a
+ * 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));
+    const ran = new Transition((drawn) => {
+        const moving = effect(drawn);
+        return Animation.of({
+            at: (t) => moving.at(t),
+            nextChange: (t) => (ran.done(t) ? Number.POSITIVE_INFINITY : moving.nextChange(t)),
+            // Done, the frame settled when the transition did; until then it is the effect's.
+            lastChange: (t) => (ran.done(t) ? schedule.lastChange(t) : moving.lastChange(t)),
+            // A one-shot, reduced, cuts from its start to its end, whatever the effect it runs would hold as a loop.
+            reduced: () => Animation.cut(moving.at(0), moving.at(seconds)),
+        });
+    }, schedule);
+    return ran;
+}
+export function onBeat(stepped, beat) {
+    // [LAW:types-are-the-program] An effect is a function and a transition an object: the representation is the discriminator.
+    if (typeof stepped === "function")
+        return (drawn) => Animation.onBeat(stepped(drawn), beat);
+    const { effect, schedule } = stepped;
+    return new Transition((drawn) => Animation.onBeat(effect(drawn), beat), Animation.onBeat(schedule, beat));
 }
 /**
  * Of a transition's `seconds`, how long each cell's own change takes. Under
@@ -596,7 +713,7 @@ function transition(curve, effect) {
  */
 const OWN = 0.45;
 /**
- * Each cell's own change in a transition, in a frame listing `cells`: a cell
+ * Each cell's own change in a transition, in the frame at `t` listing `cells`: a cell
  * starts as far through the time the others leave it as its `place` falls
  * between the element's first and last, so on any element, however little of
  * the order its cells span, the first starts at 0 and the last settles at
@@ -604,32 +721,27 @@ const OWN = 0.45;
  * `seconds` alone. An element whose cells all share one place has no order to
  * stagger, and its change takes the whole of `seconds`.
  *
- * A cell's change is settled in the first frame that lists it and kept, as
- * its place is, so an element whose cells change while it moves — a label
- * that gains a column as it leaves — spreads only its new cells over the
- * order it has then, and never sends a cell that has gone back to a later
- * start. [LAW:no-ambient-temporal-coupling] The transition owns that record;
- * it is why a transition is made for one element.
+ * [LAW:no-ambient-temporal-coupling] Worked out from the frame alone, so
+ * the same `t` over the same cells draws the same bytes whatever was drawn
+ * before — after a seek, in reverse, at any rate — and one transition is
+ * safe on any number of elements. An element that gains cells as it moves is
+ * spread over the order it has in each frame, so a cell already moving may
+ * move its start — back to unmoved, if a new cell comes first. Nothing
+ * steadier is there to spread over: the order's whole range would start a
+ * small element late and end it early, and the cells a frame hands reach
+ * across a wide frame's blank margin.
  */
 function ownChange(curve, place) {
-    const changes = new Map();
-    const key = (cell) => `${cell.row}:${cell.col}`;
-    return (cells) => {
+    return (t, cells) => {
         const [first, last] = extent(cells.map(place));
         const stagger = (last > first ? 1 - OWN : 0) * curve.seconds;
         // One phase a frame, shifted per cell, so no cell builds its own.
         const change = Phase.once(0, curve.seconds - stagger);
         // A share of the way from the first place to the last, held to the order for a cell the frame does not list.
-        const settled = (cell) => {
+        return (cell) => {
             const along = last > first ? clamp01((place(cell) - first) / (last - first)) : 0;
-            return { along, progress: (t) => change(t - along * stagger) };
+            return { along, progress: change(t - along * stagger) };
         };
-        for (const cell of cells) {
-            const at = key(cell);
-            changes.set(at, changes.get(at) ?? settled(cell));
-        }
-        // A cell the frame hands but does not list shows nothing yet, so it is timed for this frame alone.
-        return (cell) => changes.get(key(cell)) ?? settled(cell);
     };
 }
 /** The least and greatest of `values`; of none, a frame with no cell to place, both 0. */
@@ -649,10 +761,11 @@ function extent(values) {
  */
 export function fadeIn(curve, z) {
     requireCurve(curve);
+    requireZ("fadeIn", z);
     const risen = ownChange(curve, order(1.7 + z));
-    return transition(curve, veiled((t, drawn) => {
-        const of = risen(drawn.cells());
-        return (cell) => curve.ease(of(cell).progress(t));
+    return transition(curve.seconds, veiled((t, drawn) => {
+        const of = risen(t, drawn.cells());
+        return (cell) => curve.ease(of(cell).progress);
     }, curve.swing));
 }
 /**
@@ -675,14 +788,15 @@ const DISSOLVE_SHAPE = { depth: 0.4, from: 0.5, to: 0.95, maskFrom: 0.35, maskTo
  */
 export function dissolveOut(curve, z) {
     requireCurve(curve);
+    requireZ("dissolveOut", z);
     const eddy = order(9.3 + z);
     const faded = ownChange(curve, order(4.2 + z));
     const { depth, from, to, maskFrom, maskTo, late } = DISSOLVE_SHAPE;
-    return transition(curve, veiled((t, drawn) => {
-        const of = faded(drawn.cells());
+    return transition(curve.seconds, veiled((t, drawn) => {
+        const of = faded(t, drawn.cells());
         return (cell) => {
             const { along, progress } = of(cell);
-            const gone = curve.ease(progress(t));
+            const gone = curve.ease(progress);
             const q = clamp01((gone - from) / (to - from));
             const back = depth * smoothstep(maskFrom, maskTo, eddy(cell)) * (1 - late + late * along) * Math.sin(Math.PI * q) ** 2;
             return 1 - gone + back;
@@ -723,6 +837,7 @@ const STRAY = 180;
  */
 export function wheel(curve, z) {
     requireCurve(curve);
+    requireZ("wheel", z);
     const P = curve.seconds;
     // A segment's seed, from the colour it is.
     const seed = (hex) => hash(Number.parseInt(hex.slice(1), 16) * 1e-4, 17.3 + z);
@@ -734,8 +849,8 @@ export function wheel(curve, z) {
         return (360 * t) / P + curve.swing * STRAY * ((stray(s, t) - stray(s, 0)) / 1.5);
     };
     // A turned colour's bounds rest on what a frame draws, never on `t`: settled once for each.
-    const settled = new WeakMap();
-    return stillOnSlots((t, drawn) => {
+    const settled = new WeakMemo();
+    return stillOnSlots((drawn) => {
         const { colors, fills, depth, theme } = 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);
@@ -743,30 +858,30 @@ export function wheel(curve, z) {
         const segmentOf = (color, other, theirs) => (fills.has(color.hex) || !theirs ? color.hex : other.hex);
         // A colour as it turns with a segment: written one way wherever it is drawn in a frame.
         const keyOf = (color, segment) => `${color.hex} ${segment}`;
-        const memo = settled.get(theme) ?? new Memo();
-        settled.set(theme, memo);
-        const bounds = memo.get(drawnKey(drawn), () => turnedBounds(drawn.pairs, depth, (pair, side) => {
+        const bounds = settled.get(theme, () => 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], segmentOf(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 written = new Map();
-        const choose = (color, segment) => {
-            const turn = hueTurned(color, turned(segment, t));
-            return nearestWithin(turn.looks, color, depth === ColorDepth.TRUECOLOR ? turn.either.map(measured) : indexed, bounds.get(keyOf(color, segment)) ?? UNBOUNDED);
-        };
-        const write = (color, segment) => {
-            const found = written.get(keyOf(color, segment)) ?? choose(color, segment);
-            written.set(keyOf(color, segment), 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, segmentOf(color, other, theirs)) : color);
-            return { fg: turn(shown.fg, mine.fg, shown.bg, mine.bg), bg: turn(shown.bg, mine.bg, shown.fg, mine.fg) };
-        };
+        return Animation.continuous((t) => {
+            const written = new Map();
+            const choose = (color, segment) => {
+                const turn = hueTurned(color, turned(segment, t));
+                return nearestWithin(turn.looks, color, depth === ColorDepth.TRUECOLOR ? turn.either.map(measured) : indexed, bounds.get(keyOf(color, segment)) ?? UNBOUNDED);
+            };
+            const write = (color, segment) => {
+                const found = written.get(keyOf(color, segment)) ?? choose(color, segment);
+                written.set(keyOf(color, segment), 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, segmentOf(color, other, theirs)) : color);
+                return { ...shown, fg: turn(shown.fg, mine.fg, shown.bg, mine.bg), bg: turn(shown.bg, mine.bg, shown.fg, mine.fg) };
+            };
+        });
     });
 }
 /**
@@ -844,12 +959,9 @@ function turnedBounds(pairs, depth, turnedAs) {
 }
 const measured = (color) => ({ color, looks: Oklch.fromRgba(color), stop: stop(color) });
 /** `ColorSpec.indexed`'s colours, measured once for each theme and depth. */
-const measuredMemo = new WeakMap();
+const measuredMemo = new WeakMemo();
 function measuredIndexed(depth, theme) {
-    const indexed = ColorSpec.indexed(depth, theme);
-    const listed = measuredMemo.get(indexed) ?? indexed.map(([, color]) => measured(color));
-    measuredMemo.set(indexed, listed);
-    return listed;
+    return measuredMemo.get(ColorSpec.indexed(depth, theme), (indexed) => indexed.map(([, color]) => measured(color)));
 }
 /**
  * The colour that looks nearest `color` (OKLab's ΔE): `rest`, or one of
@@ -887,10 +999,11 @@ function nearestOf(color, offered) {
  * 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
+ * The search is settled once for each ground and step — below truecolor,
+ * which colours read on a ground once for that ground — 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`).
+ * frame changes when the beat does: the signal is the beat mapped to inks.
  * [LAW:no-ambient-temporal-coupling] The beat is `core/easing.ts`'s, and
  * nothing here reads a clock.
  */
@@ -899,32 +1012,78 @@ export function steppedInk(steps) {
     // A copy, as `beat` keeps of the holds: what the signal plays stays what
     // `steps` said whatever the caller does to its array.
     const inks = steps.map((step) => step.color);
-    const settled = new WeakMap();
-    return withNextChange((t, { depth, theme }) => {
-        const step = inks[rhythm.at(t)];
-        const memo = settled.get(theme) ?? new Memo();
-        settled.set(theme, memo);
-        return (colors, cell) => {
-            const pair = { ...colors, terminal: cell.terminal, reverse: cell.reverse };
-            return { fg: memo.get(`${depth} ${pairKey(pair)} ${step.hex}`, () => legibleInk(step, pair, depth, theme)), bg: colors.bg };
+    const legible = legibleInks();
+    return (drawn) => {
+        const inkOn = legible(drawn);
+        return Animation.map(rhythm, (i) => {
+            const step = inks[i];
+            return (look, cell) => ({ ...look, fg: inkOn(step, look, cell) });
+        });
+    };
+}
+/**
+ * `legibleInk` for the frame `Drawn` describes, of an ink on a cell's look:
+ * 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
+ * here — `steppedInk`'s steps and `gradient`'s ramp alike — so none of them
+ * leaves a word unreadable. Below truecolor which of the depth's colours
+ * read on a pair does not depend on the ink, so it is settled once for each
+ * pair: a ramp, whose every frame offers inks no frame offered before,
+ * then costs a nearest-colour scan a cell, not a contrast test of the whole
+ * palette.
+ */
+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 };
+            const key = `${depth} ${pairKey(pair)}`;
+            const legibleOf = (offered) => legibleAmong(pair, offered, depth, theme);
+            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)));
+                return nearestOf(ink, offered)?.color ?? pair.fg;
+            });
         };
-    }, (t) => rhythm.end(t));
+    };
 }
 /**
- * The colour nearest `step` the depth writes that reads on `pair`'s ground
- * at `pair`'s floor, as `Effected` writes it (`shows`), or `pair`'s own ink
- * when none does. [LAW:one-source-of-truth] Measured the way `shares` and
- * `wheel` measure: the written colours, at the catalogue's floor.
+ * Of `offered`, the colours that read on `pair`'s ground at `pair`'s floor,
+ * as `Effected` writes them (`shows`). [LAW:one-source-of-truth] Measured the
+ * 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 legibleInk(step, pair, depth, theme) {
+function legibleAmong(pair, offered, depth, theme) {
     const floor = floorOf(pair, depth);
-    const offered = depth === ColorDepth.TRUECOLOR ? [step, ensureContrast(step, pair.bg, floor)].map(measured) : measuredIndexed(depth, theme);
-    const reads = ({ color }) => {
+    return offered.filter(({ color }) => {
         const shown = Effected.shows(pair, { fg: color, bg: pair.bg }, depth, theme);
         return contrastRatio(shown.fg, shown.bg) >= floor;
-    };
-    return nearestOf(step, offered.filter(reads))?.color ?? pair.fg;
+    });
+}
+/**
+ * `spec.attribute` blinking: off, the cell as drawn, so that hold's frame is
+ * the identity and writes the element's own bytes; on, the attribute set.
+ * It changes when its beat does, at a hold's end, and never between.
+ * A blink and a bold pulse are this one function at two specs
+ * (`ATTRIBUTE_DEFAULTS`) [LAW:one-type-per-behavior].
+ */
+export function blink({ attribute, off, on }) {
+    const rhythm = beat([off, on]);
+    const frames = [(look) => look, (look) => ({ ...look, attributes: { ...look.attributes, [attribute]: true } })];
+    return () => Animation.map(rhythm, (i) => frames[i]);
 }
+/**
+ * Each attribute effect's spec: a blink hides the words for half of each
+ * second, as a terminal's own blink does, and a bold pulse holds them bold
+ * for the last three tenths of each second.
+ */
+export const ATTRIBUTE_DEFAULTS = {
+    blink: { attribute: "conceal", off: 0.5, on: 0.5 },
+    boldPulse: { attribute: "bold", off: 0.7, on: 0.3 },
+};
 /**
  * Every effect in the catalogue by its name in `EFFECT_CURVES`, each made the
  * one way: for an element, at its signed-off curve unless handed another,
@@ -947,4 +1106,8 @@ export const EFFECT_CATALOGUE = {
         fade: (element, curve = EFFECT_CURVES.fade) => fadeIn(curve, element.z),
         dissolve: (element, curve = EFFECT_CURVES.dissolve) => dissolveOut(curve, element.z),
     },
+    attributes: {
+        blink: () => blink(ATTRIBUTE_DEFAULTS.blink),
+        boldPulse: () => blink(ATTRIBUTE_DEFAULTS.boldPulse),
+    },
 };

package/dist/renderables/embed.d.ts

@@ -89,7 +89,7 @@ export declare class InlineLabel {
  * measures it, so a cut to a border and the width a label asks for count
  * the cells it will draw. [LAW:single-enforcer] The one reading of "set into
  * a line", for a label read through the crossing above and for text a
- * caller hands over already read (`Frames`).
+ * caller hands over already read (`FrameSequence`).
  */
 export declare function setIntoLine(text: RichText): RichText;
 /**