@promptctl/rich-js 0.23.0 → 0.24.1

package/dist/renderables/effects.js

@@ -10,7 +10,11 @@
  * a slow glow, sunlight moving on water, the colours of daylight, fireflies, ink
  * blooming in water, mist lifting — because a motion the eye recognises
  * reads as calm and alive, where a motion it has to learn reads as a widget.
- * What makes those motions familiar is what every curve here keeps:
+ * One effect here is not ambience but a signal, and keeps none of this on
+ * purpose: `steppedInk` steps its ink through colours on a beat, the news
+ * that something is at its limit, and jumps from slot to slot where the
+ * loops hold still. What makes the loops' motions familiar is what every
+ * curve of theirs keeps:
  *
  * - Nothing jumps. Every curve is continuous in time, built from smooth
  *   noise (`core/noise.ts`) and smooth waveforms, so at one frame a second a cell
@@ -42,11 +46,13 @@
  * cards runs this file's own declarations as the program a visitor edits
  * (`examples/effects-playground/programs.ts`), on the published library.
  */
-import { ColorDepth, ColorRgba, contrastRatio } from "../core/color.js";
-import { EASES, Phase } from "../core/easing.js";
+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 { IDENTITY, Oklch } from "../core/oklch.js";
+import { Oklch } from "../core/oklch.js";
+import { ensureContrast } from "../themes/colorMath.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;
@@ -61,6 +67,16 @@ const LEVELS = 48;
 const STRENGTHS = Array.from({ length: LEVELS }, (_, i) => (i + 1) / LEVELS);
 /** What 8-bit rounding of an OKLCH round trip can cost a contrast ratio. */
 const ROUNDING = 0.01;
+/**
+ * The contrast no loop draws `pair` below at `depth`: its resting contrast or
+ * `LEGIBLE`, whichever is lower, less what truecolor's rounding can cost.
+ * Below truecolor every colour written is one the depth holds exactly, so
+ * there is nothing to forgive. [LAW:one-source-of-truth] The floor `shares`
+ * settles the light against and `wheel` writes its turn above.
+ */
+function floorOf(pair, depth) {
+    return Math.min(contrastRatio(pair.fg, pair.bg), LEGIBLE) - (depth === ColorDepth.TRUECOLOR ? ROUNDING : 0);
+}
 const SIDES = ["fg", "bg"];
 /**
  * How much of `touch` each of `colors` (hex) can take: the largest share in
@@ -86,8 +102,6 @@ export function shares({ pairs, depth, theme }, colors, touch) {
         const hex = own(pair, side);
         return hex === undefined ? [] : [[hex, pair[side]]];
     })));
-    // Below truecolor every colour written is one the depth holds exactly, so only truecolor's rounding has a cost to forgive.
-    const slack = depth === ColorDepth.TRUECOLOR ? ROUNDING : 0;
     // A colour no pair writes keeps no word legible, so nothing bounds its share:
     // a frame drawing a lit colour only under blanks and seams, or not at all,
     // is a frame like any other.
@@ -104,7 +118,7 @@ export function shares({ pairs, depth, theme }, colors, touch) {
         });
         // [LAW:one-source-of-truth] A pair reads in the colours `Effected` writes it in, touched at each side's share.
         const holds = (share) => facing.every(([pair, mine, theirs]) => {
-            const floor = Math.min(contrastRatio(pair.fg, pair.bg), LEGIBLE) - slack;
+            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);
@@ -124,9 +138,10 @@ export function shares({ pairs, depth, theme }, colors, touch) {
  * A loop as an `Effect` on the element's own colours, by hex, wherever a cell
  * shows them, each touched at its share of the cell's strength: the share
  * `shares` settles for it against the pairs the element draws its words in
- * (`Drawn`), touched as `Effected` writes them at the frame's depth — below
- * truecolor a touched colour lands on a colour the slot can write, and the
- * contrast it spends is that colour's. `colors` are the ones lit, by default every colour the element
+ * (`Drawn`), touched as `Effected` writes them at the frame's depth — at 256
+ * colours a touched colour lands on a colour the slot can write, and the
+ * contrast it spends is that colour's; on a sixteen-colour terminal nothing
+ * moves (`stillOnSlots`). `colors` are the ones lit, by default every colour the element
  * sets itself. A powerline strip's fill is the ground of its cells and the
  * ink of the seam glyphs between them, so the arrow moves with the cell it
  * points out of. A colour the terminal supplies (`EffectCell.terminal`) is
@@ -140,12 +155,27 @@ export function onColors(loop, colors) {
     const settled = new WeakMap();
     const settle = (drawn) => {
         const lit = colors ?? drawn.colors;
-        const key = [drawn.depth, ...drawn.pairs.map(({ fg, bg, terminal, reverse }) => `${fg.hex}/${bg.hex}/${terminal.fg}/${terminal.bg}/${reverse}`), "|", ...lit].join(" ");
+        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 atShares(loop, settle);
+    return stillOnSlots(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 }) {
+    return [depth, ...pairs.map(pairKey)].join(" ");
+}
+/**
+ * A pair as a key: two pairs the screen shows alike, from slots alike, are
+ * one — the spelling `Drawn.pairs` is made distinct by (`./effect.ts`), and
+ * what every memo here over a frame's pairs is keyed on. Spelled here rather
+ * than imported: a playground card runs this file on the published library
+ * (header), and a name this file imports from `./effect.js` is one the
+ * package exports.
+ */
+function pairKey({ fg, bg, terminal, reverse }) {
+    return `${fg.hex}/${bg.hex}/${terminal.fg}/${terminal.bg}/${reverse}`;
 }
 /**
  * A loop as an `Effect` on colours by hex, each touched at the share
@@ -153,16 +183,45 @@ export function onColors(loop, colors) {
  * 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);
-        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 ({ 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) };
+            };
+        });
     };
 }
+/**
+ * `loop` as drawn at the frame's depth: 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]
+ * `onColors` and `wheel` 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.
+ * 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((colors) => colors) : loop(drawn));
+}
+/** Whether `depth` writes nothing between the slots it has: the sixteen, at either sixteen-colour depth, or none. */
+function onlySlots(depth) {
+    switch (depth) {
+        case ColorDepth.DEFAULT:
+        case ColorDepth.STANDARD:
+        case ColorDepth.WINDOWS:
+            return true;
+        case ColorDepth.EIGHT_BIT:
+        case ColorDepth.TRUECOLOR:
+            return false;
+    }
+}
 /**
  * `color` under `touch` at strength `w`, and at strength 0 the colour itself,
  * exactly: an OKLCH round trip can land a step off, and at 16 colours a step
@@ -313,8 +372,9 @@ const bump = (d) => (Math.abs(d) >= 1 ? 0 : (1 - d * d) ** 3);
 /**
  * Shimmer, as sunlight moving across water. Swing: how far into `light` the
  * brightest glint goes, 0–1. A soft band of light, `width` columns either
- * side of its centre, crosses columns 0 to `span`, entering and leaving
- * fully off the row, `STRIDE` columns in about three quarters of a period. Its passes
+ * side of its centre, crosses the element from the first column a frame
+ * lists (`Drawn.cells`) to the last, entering and leaving fully off it,
+ * `STRIDE` columns in about three quarters of a period. Its passes
  * come the way light comes and goes on water as clouds move: while the sun
  * is out they are bright and follow close on one another, one sometimes
  * catching the last; under cloud they thin to faint ones with the row still
@@ -324,26 +384,26 @@ const bump = (d) => (Math.abs(d) >= 1 ? 0 : (1 - d * d) ** 3);
  * on a slow current and re-forming as they go, so the glints dance while
  * the band glides. Before the first pass enters, the row is untouched.
  */
-export function shimmer(curve, span, width, glow, z) {
+export function shimmer(curve, width, glow, z) {
     requireCurve(curve);
     const P = curve.seconds;
-    const across = span + 2 * width;
     // 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
     // cloudy spells each last a few periods, and a pass is likelier and
     // brighter the clearer the sky.
     const SLOT = P / 2;
     const sky = (j) => smoothstep(-0.4, 0.4, noise(j / 7, 3.3, 5.5 + z));
-    // Pass `j` at `t`: how bright its band is and where its centre stands, off
-    // the row before it sets off and once it is done. It sets off somewhere in
-    // the first `SETS_OFF` of its slot and carries its centre `STRIDE` columns
-    // in `LEAST` to `LEAST + SPREAD` periods, give or take its drift, and every
-    // one is off the row `UP` slots after its own began.
+    // Pass `j` at `t`, over a crossing `across` columns long — the element's
+    // and the band's either side: how bright its band is and where its centre
+    // stands from the element's first column, off the element before it sets
+    // off and once it is done. It sets off somewhere in the first `SETS_OFF`
+    // of its slot and carries its centre `STRIDE` columns in `LEAST` to
+    // `LEAST + SPREAD` periods, give or take its drift, so a pass's centre moves
+    // at the same pace however long the crossing.
     const SETS_OFF = 0.7;
     const LEAST = 0.51;
     const SPREAD = 0.4;
-    const UP = SETS_OFF + ((LEAST + SPREAD) * P * across) / STRIDE / SLOT;
-    const pass = (j, t) => {
+    const pass = (j, t, across) => {
         const clear = sky(j);
         // Even under cloud about one slot in three holds a pass, a faint one, so a
         // still spell lasts a period or so, the way a cloud's shadow does, and
@@ -353,29 +413,35 @@ export function shimmer(curve, span, width, glow, z) {
         const crossing = ((P * across) / STRIDE) * (LEAST + SPREAD * hash(j, 5.5 + z));
         const q = clamp01((t - (j + SETS_OFF * hash(j, 6.5 + z)) * SLOT) / crossing);
         // It drifts ahead and behind on slow noise, by nothing at either edge of
-        // the row and never enough to turn it back.
+        // the element and never enough to turn it back.
         const centre = q * across - width + 0.06 * across * Math.sin(Math.PI * q) * noise(q, 2.7, j + z);
         return { strength, centre };
     };
-    // The passes on the row at `t`; the first slot is 0, so before it there are none.
-    const passing = (t) => {
+    // The passes on the element at `t`, every one off it `up` slots after its
+    // own began; the first slot is 0, so before it there are none.
+    const passing = (t, across) => {
+        const up = SETS_OFF + ((LEAST + SPREAD) * P * across) / STRIDE / SLOT;
         const last = Math.floor(t / SLOT);
         const passes = [];
-        for (let j = Math.max(0, Math.ceil(last - UP)); j <= last; j++)
-            passes.push(pass(j, t));
+        for (let j = Math.max(0, Math.ceil(last - up)); j <= last; j++)
+            passes.push(pass(j, t, across));
         return passes;
     };
     // A ripple's crest: a Gaussian ridge, 1 where the field crosses zero and in
     // (0, 1] for any noise, smooth throughout, so a crest sliding through a cell
     // lights it smoothly.
     const ripple = (a, b, c) => Math.exp(-((noise(a, b, c) / 0.8) ** 2));
-    const field = (t) => {
-        const passes = passing(t);
+    const field = (t, drawn) => {
+        // [LAW:one-source-of-truth] The element is as wide as the cells its frame
+        // lists, never as a width its caller states: a padded, wrapped or
+        // confined element is crossed where it shows.
+        const [left, right] = extent(drawn.cells().map((cell) => cell.col));
+        const passes = passing(t, right - left + 1 + 2 * width);
         return (cell) => {
             // Where two passes overlap the brighter wins, so light never doubles up.
             let lit = 0;
             for (const { strength, centre } of passes)
-                lit = Math.max(lit, strength * bump((cell.col - centre) / width));
+                lit = Math.max(lit, strength * bump((cell.col - left - centre) / width));
             const row = cell.row + z;
             const current = 0.8 * noise(cell.col * 0.05, row * 0.3 + 1.3, t * 0.02);
             const caustic = (ripple(cell.col * 0.21 + current, row * 0.9, t * 0.022) * ripple(cell.col * 0.33 + 9.1 - current, row * 0.7, t * 0.018 + 4.2)) **
@@ -387,8 +453,14 @@ export function shimmer(curve, span, width, glow, z) {
 }
 /**
  * Sparkle, as fireflies. Swing: how far into the firefly's `light` a glow
- * goes at its brightest, 0–1. About one firefly to every eight columns of
- * `span`, each keeping near a home of its own. A firefly flashes — kindles,
+ * goes at its brightest, 0–1. Fireflies keep to a lattice laid from the
+ * element's first column and top row as a frame lists its cells
+ * (`Drawn.cells`): one every `PER` columns along a row of the lattice, a row
+ * of the lattice every `ROWS` rows, each firefly near a home of its own.
+ * The lattice does not hang on how wide or deep the element is, so one that
+ * grows or shrinks at its last column or bottom row moves no firefly; one
+ * whose first column moves, as centred words that change length do, carries
+ * its fireflies with it. A firefly flashes — kindles,
  * drifts a few cells glowing, slowing as it fades — then flies on in the
  * dark and flashes again somewhere a few cells off, the way fireflies at
  * dusk are seen: a short lit stroke, then gone, each time a little
@@ -399,53 +471,78 @@ export function shimmer(curve, span, width, glow, z) {
  * turn: its brightest flash, rise and fall, takes `FLASH` of it, and a
  * dimmer one less.
  */
-export function sparkle(curve, span, glow, z) {
+export function sparkle(curve, glow, z) {
     requireCurve(curve);
-    const count = Math.max(3, Math.round(span / 8));
+    // 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.
+    const PER = 8;
+    const ROWS = 3;
     const HALO = 5;
     // How far from home a flash may begin, and how far the brightest drifts while lit.
     const HOP = 5;
     const GLIDE = 5;
     const TURN = curve.seconds;
-    const homes = Array.from({ length: count }, (_, i) => ({
-        home: (i + 0.5 + 0.7 * noise(i * 1.7 + 0.2, 0.3, 0.5 + z)) * (span / count),
-        z: i * 4.9 + 0.3 + z,
+    // How far from its slot's middle a firefly's light can reach a cell: its
+    // home's jitter, a hop, a glide, its wander, and its halo; across rows,
+    // its wander and its halo, which counts a row as two columns.
+    const REACH = 0.7 * PER + HOP + GLIDE + 1.5 + HALO;
+    const REACH_ROWS = 0.6 + HALO / 2;
+    // The firefly of slot `i` along lattice row `k` at `t`, from the element's
+    // first column and top row: where it is, and how bright. Flash `n` is one
+    // event: whether it comes, how bright, when in its turn and where are its
+    // own. Between flashes the firefly is dark, so where it moves to is never
+    // seen moving.
+    const firefly = (i, k, t, left, top) => {
+        const id = i * 4.9 + k * 31.7 + 0.3 + z;
+        const home = i + 0.5 + 0.7 * noise(i * 1.7 + 0.2, 0.3 + k * 2.9, 0.5 + z);
         // Out of step with every other firefly from the first moment.
-        offset: hash(i, 0.7 + z) * TURN,
-    }));
-    // Where every firefly is at `t`, and how bright.
-    const fliesAt = (t) => homes.map((fly) => {
-        // Flash `n` is one event: whether it comes, how bright, when in
-        // its turn and where are its own. Between flashes the firefly
-        // is dark, so where it moves to is never seen moving.
-        const u = t + fly.offset;
+        const u = t + hash(i + k * 1013, 0.7 + z) * TURN;
         const n = Math.floor(u / TURN);
         // A dark turn is a flash with no light: it keeps its length, so
         // every flash is timed alike.
-        const lit = hash(n, fly.z + 1) < 0.15 ? 0 : 1;
-        const k = 0.5 + 0.5 * hash(n, fly.z + 2);
-        const at = hash(n, fly.z + 3) * (1 - lasts(FLASH, k));
+        const lit = hash(n, id + 1) < 0.15 ? 0 : 1;
+        const strength = 0.5 + 0.5 * hash(n, id + 2);
+        const at = hash(n, id + 3) * (1 - lasts(FLASH, strength));
         const s = u / TURN - n - at;
         // While it glows it drifts a few cells one way or the other, as
         // fast as it is bright: quickest at its height, slowing as it
         // fades — the lit stroke a firefly draws on the dusk. A brighter
         // flash lasts longer and draws a longer stroke at the same pace.
         return {
-            x: fly.home +
-                HOP * (2 * hash(n, fly.z + 4) - 1) +
-                GLIDE * k * (2 * hash(n, fly.z + 5) - 1) * given(FLASH, s, k) +
-                1.5 * noise(fly.z, 0.1, t * 0.035),
-            y: 0.6 * noise(fly.z, 2.2, t * 0.035),
-            glow: lit * swell(FLASH, s, k),
+            x: left +
+                home * PER +
+                HOP * (2 * hash(n, id + 4) - 1) +
+                GLIDE * strength * (2 * hash(n, id + 5) - 1) * given(FLASH, s, strength) +
+                1.5 * noise(id, 0.1, t * 0.035),
+            y: top + k * ROWS + 0.6 * noise(id, 2.2, t * 0.035),
+            glow: lit * swell(FLASH, s, strength),
         };
-    });
-    const field = (t) => {
-        const flies = fliesAt(t);
+    };
+    const field = (t, drawn) => {
+        // [LAW:one-source-of-truth] The element is where its frame lists cells,
+        // never a width its caller states: a padded, wrapped or confined element
+        // has its fireflies over it. Its extent only bounds which slots are
+        // worked out; where each firefly is never depends on it.
+        const cells = drawn.cells();
+        const [left, right] = extent(cells.map((cell) => cell.col));
+        const [top, bottom] = extent(cells.map((cell) => cell.row));
+        const slot = (col) => (col - left) / PER - 0.5;
+        const band = (row) => (row - top) / ROWS;
+        const [i0, i1] = [Math.ceil(slot(left - REACH)), Math.floor(slot(right + REACH))];
+        const [k0, k1] = [Math.ceil(band(top - REACH_ROWS)), Math.floor(band(bottom + REACH_ROWS))];
+        const flies = Array.from({ length: k1 - k0 + 1 }, (_, k) => Array.from({ length: i1 - i0 + 1 }, (_, i) => firefly(i0 + i, k0 + k, t, left, top)));
         return (cell) => {
-            // Where two halos overlap the brighter wins, so light never doubles up.
+            // A cell is asked only of the fireflies whose light can reach it, and
+            // where two halos overlap the brighter wins, so light never doubles up.
             let shine = 0;
-            for (const fly of flies)
-                shine = Math.max(shine, fly.glow * bump(Math.hypot(cell.col - fly.x, 2 * (cell.row - fly.y)) / HALO));
+            const [ia, ib] = [Math.max(i0, Math.ceil(slot(cell.col - REACH))), Math.min(i1, Math.floor(slot(cell.col + REACH)))];
+            const [ka, kb] = [Math.max(k0, Math.ceil(band(cell.row - REACH_ROWS))), Math.min(k1, Math.floor(band(cell.row + REACH_ROWS)))];
+            for (let k = ka; k <= kb; k++)
+                for (let i = ia; i <= ib; i++) {
+                    const fly = flies[k - k0][i - i0];
+                    shine = Math.max(shine, fly.glow * bump(Math.hypot(cell.col - fly.x, 2 * (cell.row - fly.y)) / HALO));
+                }
             return curve.swing * curve.ease(shine);
         };
     };
@@ -460,17 +557,19 @@ export function sparkle(curve, span, glow, z) {
  * hiding — 1 reaches fully invisible. A cell wholly shown is returned as it was.
  */
 export function veiled(visibility, swing) {
-    return (t, { theme }) => {
-        const shows = visibility(t);
+    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 (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() };
+            };
+        });
     };
 }
 /**
@@ -492,7 +591,19 @@ function order(z) {
     };
 }
 function transition(curve, effect) {
-    return { effect, done: (t) => t >= curve.seconds };
+    const done = (t) => t >= curve.seconds;
+    return {
+        effect: (drawn) => {
+            const moving = effect(drawn);
+            return {
+                at: (t) => moving.at(t),
+                nextChange: (t) => (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) => (done(t) ? curve.seconds : moving.lastChange(t)),
+            };
+        },
+        done,
+    };
 }
 /**
  * Of a transition's `seconds`, how long each cell's own change takes. Under
@@ -500,15 +611,51 @@ function transition(curve, effect) {
  */
 const OWN = 0.45;
 /**
- * Each cell's progress through its own change in a transition, in [0, 1]: a
- * cell `place` along the order starts that share of the way through the time
- * the others leave it, and takes `OWN` of `seconds`.
+ * Each cell's own change in a transition, in a frame 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
+ * `seconds`. [LAW:one-source-of-truth] That is what lets `done` read
+ * `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.
  */
 function ownChange(curve, place) {
-    const own = curve.seconds * OWN;
-    // One phase, shifted per cell, so no cell builds its own each frame.
-    const change = Phase.once(0, own);
-    return (t) => (cell) => change(t - place(cell) * (curve.seconds - own));
+    const changes = new Map();
+    const key = (cell) => `${cell.row}:${cell.col}`;
+    return (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) => {
+            const along = last > first ? clamp01((place(cell) - first) / (last - first)) : 0;
+            return { along, progress: (t) => 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. */
+function extent(values) {
+    let lo = values[0] ?? 0;
+    let hi = lo;
+    for (const v of values) {
+        lo = Math.min(lo, v);
+        hi = Math.max(hi, v);
+    }
+    return [lo, hi];
 }
 /**
  * Fade-in, as ink blooming in water: patches of the element surface first
@@ -518,9 +665,9 @@ function ownChange(curve, place) {
 export function fadeIn(curve, z) {
     requireCurve(curve);
     const risen = ownChange(curve, order(1.7 + z));
-    return transition(curve, veiled((t) => {
-        const at = risen(t);
-        return (cell) => curve.ease(at(cell));
+    return transition(curve, veiled((t, drawn) => {
+        const of = risen(drawn.cells());
+        return (cell) => curve.ease(of(cell).progress(t));
     }, curve.swing));
 }
 /**
@@ -543,16 +690,16 @@ const DISSOLVE_SHAPE = { depth: 0.4, from: 0.5, to: 0.95, maskFrom: 0.35, maskTo
  */
 export function dissolveOut(curve, z) {
     requireCurve(curve);
-    const place = order(4.2 + z);
     const eddy = order(9.3 + z);
-    const faded = ownChange(curve, place);
+    const faded = ownChange(curve, order(4.2 + z));
     const { depth, from, to, maskFrom, maskTo, late } = DISSOLVE_SHAPE;
-    return transition(curve, veiled((t) => {
-        const at = faded(t);
+    return transition(curve, veiled((t, drawn) => {
+        const of = faded(drawn.cells());
         return (cell) => {
-            const gone = curve.ease(at(cell));
+            const { along, progress } = of(cell);
+            const gone = curve.ease(progress(t));
             const q = clamp01((gone - from) / (to - from));
-            const back = depth * smoothstep(maskFrom, maskTo, eddy(cell)) * (1 - late + late * place(cell)) * Math.sin(Math.PI * q) ** 2;
+            const back = depth * smoothstep(maskFrom, maskTo, eddy(cell)) * (1 - late + late * along) * Math.sin(Math.PI * q) ** 2;
             return 1 - gone + back;
         };
     }, curve.swing));
@@ -581,9 +728,13 @@ const STRAY = 180;
  * together; on the terminal's ground, a run of text's ink is a segment of
  * its own. A segment's stray is slow noise of its own, at `STRAY_PERIODS`,
  * so no two keep step, and the row never shows one spread of hues twice.
- * Lightness and chroma are kept, so the words read as they did; the turn
- * only happens to the element's own colours (`Drawn.colors`), never the
- * terminal's.
+ * A colour keeps its luminance as it turns (`hueTurned`), so every pair of
+ * words reads at the contrast it rested at; at 256 colours a turned colour
+ * lands on a colour the depth writes, one that keeps every pair of words it
+ * is drawn in at its floor (`floorOf`) — its resting contrast or WCAG AA,
+ * whichever is lower — as `shares` keeps the light's (`turnedBounds`). The
+ * turn only happens to the element's own colours (`Drawn.colors`), never the
+ * terminal's. On a sixteen-colour terminal nothing turns (`stillOnSlots`).
  */
 export function wheel(curve, z) {
     requireCurve(curve);
@@ -597,13 +748,201 @@ export function wheel(curve, z) {
         const s = seed(hex);
         return (360 * t) / P + curve.swing * STRAY * ((stray(s, t) - stray(s, 0)) / 1.5);
     };
-    return (t, { colors, fills }) => (shown, cell) => {
+    // A turned colour's bounds rest on what a frame draws, never on `t`: settled once for each.
+    const settled = new WeakMap();
+    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 = { fg: !cell.terminal.fg && colors.has(shown.fg.hex), bg: !cell.terminal.bg && colors.has(shown.bg.hex) };
-        // An own colour turns with its segment: itself if a fill or beside no own colour, else the one beside it.
-        const turn = (color, mine, other, theirs) => !mine ? color : Oklch.fromRgba(color).applyKey({ ...IDENTITY, hueShift: turned(fills.has(color.hex) || !theirs ? color.hex : other.hex, t) }).toRgba();
-        return { fg: turn(shown.fg, own.fg, shown.bg, own.bg), bg: turn(shown.bg, own.bg, shown.fg, own.fg) };
+        const own = (terminal, color) => !terminal && colors.has(color.hex);
+        // The segment an own colour turns with: itself if a fill or beside no own colour, else the one beside it.
+        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 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);
+        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 { fg: turn(shown.fg, mine.fg, shown.bg, mine.bg), bg: turn(shown.bg, mine.bg, shown.fg, mine.fg) };
+            };
+        });
+    });
+}
+/**
+ * `color` turned `degrees` round the hue circle at its own relative
+ * luminance, and at its own chroma where the gamut has it. WCAG contrast is
+ * a ratio of luminances, so a pair of colours each turned this way reads at
+ * the contrast it did; one turned at its OKLCH lightness instead does not,
+ * since equal lightness is not equal luminance across hues. The lightness
+ * is found by bisection, as `ensureContrastToward` finds one, and 8-bit
+ * rounding lands the luminance between two colours, so both are kept. At 0
+ * degrees the colour itself, exactly: an OKLCH round trip can land a step
+ * off (`touchedAt`).
+ */
+function hueTurned(color, degrees) {
+    if (degrees === 0)
+        return { looks: color, either: [color] };
+    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++) {
+        const mid = (dim + bright) / 2;
+        [dim, bright] = relativeLuminance(at(mid)) < luminance ? [mid, bright] : [dim, mid];
+    }
+    return { looks: at(bright), either: [at(dim), at(bright)] };
+}
+/**
+ * Where a colour sits on WCAG's contrast scale: the log of its contrast with
+ * black. Two colours' contrast ratio is `exp` of the gap between their
+ * stops, so a contrast to keep is a distance a colour may move.
+ */
+const stop = (color) => Math.log(contrastRatio(color, new ColorRgba(0, 0, 0)));
+const UNBOUNDED = { lo: -Infinity, hi: Infinity };
+/** Bounds that admit no turn: the colour is written as it rests. */
+const STILL = { lo: Infinity, hi: -Infinity };
+/**
+ * The widest 8-bit rounding parts `hueTurned`'s two colours, in stops. They
+ * are one point of the hue rounded two ways, so they differ by at most a
+ * step in each channel, and a channel of a colour that dark or light can
+ * take a step only so large: worst near a luminance of 0.05, at 3.03% of
+ * contrast. Bounds at least this wide admit one of the two whatever the
+ * hue; narrower, a colour would turn at some hues and snap back to rest at
+ * the next, so it holds still.
+ */
+const ROUNDING_GAP = Math.log(1.031);
+/**
+ * How far each turned colour's luminance may land from the one it rests at,
+ * keyed as `turnedAs` keys each side of a pair — none for a side that holds
+ * still — so that every pair of `pairs` reads at its floor (`floorOf`) at
+ * `depth` however each of its colours lands within its bounds. Bounds
+ * narrower than `ROUNDING_GAP` are `STILL`.
+ *
+ * A pair's contrast to spare above its floor, as a gap between stops, is
+ * shared out evenly between its sides that turn: the lighter may land that
+ * much darker, the darker that much lighter, and never further. So a colour
+ * written once for every pair it is drawn in is bounded by each of them at
+ * once, and a frame writes it one way wherever it falls. A pair whose floor
+ * is 1:1 holds however it is drawn, and bounds nothing.
+ */
+function turnedBounds(pairs, depth, turnedAs) {
+    const bounds = new Map();
+    for (const pair of pairs.filter((pair) => floorOf(pair, depth) > 1)) {
+        const spare = Math.log(contrastRatio(pair.fg, pair.bg)) - Math.log(floorOf(pair, depth));
+        const share = spare / SIDES.filter((side) => turnedAs(pair, side) !== undefined).length;
+        for (const side of SIDES) {
+            const key = turnedAs(pair, side);
+            if (key === undefined)
+                continue;
+            const [mine, theirs] = [stop(pair[side]), stop(pair[side === "fg" ? "bg" : "fg"])];
+            const { lo, hi } = bounds.get(key) ?? UNBOUNDED;
+            bounds.set(key, mine >= theirs ? { lo: Math.max(lo, mine - share), hi } : { lo, hi: Math.min(hi, mine + share) });
+        }
+    }
+    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. */
+const measuredMemo = new WeakMap();
+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;
+}
+/**
+ * The colour that looks nearest `color` (OKLab's ΔE): `rest`, or one of
+ * `candidates` whose luminance is within `bounds`. `rest` is what the bounds
+ * are measured from, so it is always offered; ties go to it, then to the
+ * earlier.
+ */
+function nearestWithin(color, rest, candidates, { lo, hi }) {
+    return nearestOf(color, [measured(rest), ...candidates.filter(({ stop }) => stop >= lo && stop <= hi)]).color;
+}
+/** Of `offered`, the one that looks nearest `color` (OKLab's ΔE), ties to the earlier; none when nothing is offered. */
+function nearestOf(color, offered) {
+    const looks = Oklch.fromRgba(color);
+    let best;
+    for (const candidate of offered) {
+        const apart = looks.deltaE(candidate.looks);
+        if (best === undefined || apart < best[1])
+            best = [candidate, apart];
+    }
+    return best?.[0];
+}
+/**
+ * A signal: every cell's ink stepping through `steps`' colours on a beat,
+ * one colour a hold, looping, for the time it is handed — a gauge's
+ * chevrons in bright changing colours. The ground is left as the cell draws
+ * it, and the words stay legible on it: each step's ink is written as the
+ * colour nearest the step's (OKLab's ΔE) that the depth draws and that
+ * reads on the cell's ground, as `Effected` writes it, at the cell's floor
+ * (`floorOf`) — its resting contrast or `LEGIBLE`, whichever is lower, the
+ * floor every loop here keeps. In truecolor that is the step itself, or its
+ * hue and chroma at the lightness nearest it that reaches the floor
+ * (`ensureContrast`, the one slide a template's `readableOn` makes too);
+ * below truecolor, the nearest of the colours the depth has an index for, so on a
+ * sixteen-colour terminal it steps from slot to slot, the one effect here
+ * that does (`stillOnSlots`). A cell whose ground no offered colour reads
+ * on keeps the ink it rested in.
+ *
+ * The search is settled once for each ink, ground and step, so a frame
+ * inside a step redoes none, and nor does a later pass of the beat: at sixty
+ * frames a second a one-second step is sixty identical frames, and the
+ * frame 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.
+ */
+export function steppedInk(steps) {
+    const rhythm = beat(steps.map((step) => step.seconds));
+    // 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 ({ depth, theme }) => {
+        const memo = settled.get(theme) ?? new Memo();
+        settled.set(theme, memo);
+        return Animation.map(rhythm, (i) => {
+            const step = inks[i];
+            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 };
+            };
+        });
+    };
+}
+/**
+ * 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.
+ */
+function legibleInk(step, pair, 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 }) => {
+        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;
 }
 /**
  * Every effect in the catalogue by its name in `EFFECT_CURVES`, each made the
@@ -618,9 +957,9 @@ export function wheel(curve, z) {
  */
 export const EFFECT_CATALOGUE = {
     loops: {
-        shimmer: (element, curve = EFFECT_CURVES.shimmer) => onColors(shimmer(curve, element.span, SHIMMER_WIDTH, EFFECT_LIGHTS.sun, element.z)),
+        shimmer: (element, curve = EFFECT_CURVES.shimmer) => onColors(shimmer(curve, SHIMMER_WIDTH, EFFECT_LIGHTS.sun, element.z)),
         pulse: (element, curve = EFFECT_CURVES.pulse) => onColors(pulse(curve, EFFECT_LIGHTS.sun, element.z)),
-        sparkle: (element, curve = EFFECT_CURVES.sparkle) => onColors(sparkle(curve, element.span, EFFECT_LIGHTS.firefly, element.z)),
+        sparkle: (element, curve = EFFECT_CURVES.sparkle) => onColors(sparkle(curve, EFFECT_LIGHTS.firefly, element.z)),
         wheel: (element, curve = EFFECT_CURVES.wheel) => wheel(curve, element.z),
     },
     transitions: {