@promptctl/rich-js 0.20.0 → 0.22.0

package/dist/renderables/effects.js

@@ -3,7 +3,8 @@
  * 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
  * 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.
+ * (`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.
  *
  * Each effect is something a first-time observer already knows from life —
  * a slow glow, sunlight moving on water, the colours of daylight, fireflies, ink
@@ -36,15 +37,17 @@
  * [LAW:no-ambient-temporal-coupling] No curve reads a clock; `t` is the
  * effect's argument, so the frame owner decides when to sample.
  *
- * Every import below names something the package exports, but for `noise`,
- * which the docs' effects playground page supplies itself: each of its
+ * Every import below names something the package exports, but for `noise`
+ * and `Memo`, which the docs' effects playground page supplies itself: each of its
  * cards runs this file's own declarations as the program a visitor edits
  * (`examples/effects-playground/programs.ts`), on the published library.
  */
-import { ColorRgba, contrastRatio } from "../core/color.js";
+import { ColorDepth, ColorRgba, contrastRatio } from "../core/color.js";
 import { EASES, Phase } 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 { 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;
 /**
@@ -58,13 +61,15 @@ 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;
+const SIDES = ["fg", "bg"];
 /**
  * How much of `touch` each of `colors` (hex) can take: the largest share in
- * [0, 1] at which every pair in `pairs` that shows it, touched at the same
+ * [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. A colour in a pair but not in `colors` takes none, and so does one
+ * lower, in the colours `Effected` writes it in at `drawn`'s depth and theme.
+ * 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 throws.
+ * no pair writes has nothing to be measured against, and takes it all.
  *
  * Colours are settled lightest first, each against every partner: one
  * already settled at its share, one not yet settled as it is. So the lighter
@@ -73,28 +78,38 @@ const ROUNDING = 0.01;
  * 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, colors, touch) {
+export function shares({ pairs, depth, theme }, 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 sides = pairs.map(({ fg, bg, terminal }) => [
-        { color: fg, own: terminal.fg ? undefined : fg.hex },
-        { color: bg, own: terminal.bg ? undefined : bg.hex },
-    ]);
-    const rgba = new Map(sides.flat().flatMap(({ color, own }) => (own === undefined ? [] : [[own, color]])));
-    const unpaired = [...colors].filter((hex) => !rgba.has(hex));
-    if (unpaired.length > 0)
-        throw new RangeError(`shares: ${unpaired.join(", ")} written in no pair, so nothing to keep legible against`);
+    const own = (pair, side) => (pair.terminal[side] ? undefined : pair[side].hex);
+    const rgba = new Map(pairs.flatMap((pair) => SIDES.flatMap((side) => {
+        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.
+    const settled = new Map([...colors].filter((hex) => !rgba.has(hex)).map((hex) => [hex, 1]));
     const lightness = (hex) => Oklch.fromRgba(rgba.get(hex)).l;
-    const settled = new Map();
-    for (const hex of [...colors].sort((a, b) => lightness(b) - lightness(a))) {
-        const partners = sides.flatMap(([fg, bg]) => {
-            const partner = fg.own === hex ? bg : bg.own === hex ? fg : undefined;
-            return partner === undefined ? [] : [[partner.color, partner.own === undefined ? 0 : (settled.get(partner.own) ?? 0)]];
+    for (const hex of [...colors].filter((hex) => rgba.has(hex)).sort((a, b) => lightness(b) - lightness(a))) {
+        // Each pair showing the colour, with the side it shows it on and the share its partner takes.
+        const facing = pairs.flatMap((pair) => {
+            const mine = SIDES.find((side) => own(pair, side) === hex);
+            if (mine === undefined)
+                return [];
+            const partner = own(pair, mine === "fg" ? "bg" : "fg");
+            return [[pair, mine, partner === undefined ? 0 : (settled.get(partner) ?? 0)]];
         });
-        const color = rgba.get(hex);
-        const holds = (share) => partners.every(([partner, theirs]) => {
-            const floor = Math.min(contrastRatio(color, partner), LEGIBLE);
-            return STRENGTHS.every((w) => contrastRatio(touchedAt(touch, color, share * w), touchedAt(touch, partner, theirs * w)) >= floor - ROUNDING);
+        // [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 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);
+                return contrastRatio(shown.fg, shown.bg) >= floor;
+            });
         });
         let [lo, hi] = holds(1) ? [1, 1] : [0, 1];
         for (let i = 0; i < 20 && hi - lo > 1e-3; i++) {
@@ -106,18 +121,46 @@ export function shares(pairs, colors, touch) {
     return settled;
 }
 /**
- * A loop as an `Effect` on a subject's own colours, by hex, wherever a cell
- * shows them, each touched at its share of the cell's strength. 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 not the subject's, whatever
- * its hex, and takes no share.
+ * 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
+ * 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
+ * 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
+ * element draws: make the effect once and draw it in every frame, and a frame
+ * drawing what an earlier one drew costs no settling.
+ */
+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 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);
+}
+/**
+ * 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 onColors(share, loop) {
-    return ({ fg, bg }, cell, t) => {
-        const w = Math.round(clamp01(loop.field(cell, t)) * LEVELS) / LEVELS;
-        const moved = (color, terminal) => touchedAt(loop.touch, color, (terminal ? 0 : (share.get(color.hex) ?? 0)) * w);
-        return { fg: moved(fg, cell.terminal.fg), bg: moved(bg, cell.terminal.bg) };
+export function atShares(loop, share) {
+    return (t, 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) };
+        };
     };
 }
 /**
@@ -246,14 +289,15 @@ export function pulse(curve, glow, z) {
     const WANDER = 0.1;
     const wander = (t) => WANDER * noise(t / (3 * curve.seconds), 0.5, 0.5 + z);
     const start = wander(0);
-    const field = (_cell, t) => {
+    const field = (t) => {
         const beats = (rate * t) / curve.seconds + wander(t) - start;
         const n = Math.floor(beats);
         // Each beat's own depth, 70% to the whole of the swing; it changes where
         // the beat is at rest, so nothing jumps.
         const depth = 0.7 + 0.3 * smoothstep(-0.5, 0.5, noise(n * 0.37, 2.1, z));
         const beat = 0.5 - 0.5 * Math.cos(2 * Math.PI * (beats - n));
-        return curve.swing * curve.ease(depth * beat);
+        const level = curve.swing * curve.ease(depth * beat);
+        return () => level;
     };
     return { touch: light(glow), field };
 }
@@ -313,35 +357,31 @@ export function shimmer(curve, span, width, glow, z) {
         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 one moment: a frame asks for the same moment
-    // once per cell, so they are worked out once per moment.
-    let passing = { t: Number.NaN, passes: [] };
-    // Where two passes overlap the brighter wins, so light never doubles up;
-    // the first slot is 0, so before it nothing is lit.
-    const band = (col, t) => {
-        if (passing.t !== t) {
-            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));
-            passing = { t, passes };
-        }
-        let lit = 0;
-        for (const { strength, centre } of passing.passes)
-            lit = Math.max(lit, strength * bump((col - centre) / width));
-        return lit;
+    // The passes on the row at `t`; the first slot is 0, so before it there are none.
+    const passing = (t) => {
+        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));
+        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 = (cell, t) => {
-        const lit = band(cell.col, t);
-        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)) **
-            2;
-        return curve.swing * curve.ease(lit * (0.1 + 0.6 * caustic));
+    const field = (t) => {
+        const passes = passing(t);
+        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));
+            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)) **
+                2;
+            return curve.swing * curve.ease(lit * (0.1 + 0.6 * caustic));
+        };
     };
     return { touch: light(glow), field };
 }
@@ -373,67 +413,64 @@ export function sparkle(curve, span, glow, z) {
         // Out of step with every other firefly from the first moment.
         offset: hash(i, 0.7 + z) * TURN,
     }));
-    // Where every firefly is and how bright at one moment: a frame asks for
-    // the same moment once per cell, so it is worked out once per moment.
-    let flown = { t: Number.NaN, flies: [] };
-    const fliesAt = (t) => {
-        if (flown.t !== t) {
-            flown = {
-                t,
-                flies: 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 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 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),
-                    };
-                }),
-            };
-        }
-        return flown.flies;
-    };
-    const field = (cell, t) => {
-        // Where two halos overlap the brighter wins, so light never doubles up.
-        let shine = 0;
-        for (const fly of fliesAt(t))
-            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);
+    // 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 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 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),
+        };
+    });
+    const field = (t) => {
+        const flies = fliesAt(t);
+        return (cell) => {
+            // 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));
+            return curve.swing * curve.ease(shine);
+        };
     };
     return { touch: light(glow), field };
 }
 /**
- * A cell mixed toward the terminal's `ground` 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 hiding — 1 reaches fully invisible. A
- * cell wholly shown is returned as it was.
+ * 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
+ * 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
+ * hiding — 1 reaches fully invisible. A cell wholly shown is returned as it was.
  */
-export function veiled(visibility, swing, ground) {
-    const to = Oklch.fromRgba(ground);
-    return (colors, cell, t) => {
-        const hidden = swing * (1 - clamp01(visibility(cell, t)));
-        if (hidden === 0)
-            return colors;
-        const bg = blend(Oklch.fromRgba(colors.bg), to, hidden);
-        return { fg: blend(Oklch.fromRgba(colors.fg), bg, hidden).toRgba(), bg: bg.toRgba() };
+export function veiled(visibility, swing) {
+    return (t, { theme }) => {
+        const shows = visibility(t);
+        // [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() };
+        };
     };
 }
 /**
@@ -454,9 +491,8 @@ function order(z) {
         return place;
     };
 }
-function transition(curve, start, effect) {
-    const end = start + curve.seconds;
-    return { effect, done: (t) => t >= end };
+function transition(curve, effect) {
+    return { effect, done: (t) => t >= curve.seconds };
 }
 /**
  * Of a transition's `seconds`, how long each cell's own change takes. Under
@@ -464,26 +500,28 @@ function transition(curve, start, effect) {
  */
 const OWN = 0.45;
 /**
- * Each cell's progress through its own change in a transition starting at
- * `start`, 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 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`.
  */
-function ownChange(curve, start, place) {
+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(start, own);
-    return (cell, t) => change(t - place(cell) * (curve.seconds - own));
+    const change = Phase.once(0, own);
+    return (t) => (cell) => change(t - place(cell) * (curve.seconds - own));
 }
 /**
- * Fade-in starting at `start`, as ink blooming in water: patches of the
- * element surface first and the rest follows outward from them, each cell
- * rising smoothly over its own part of the duration. Whole at
- * `start + seconds`.
+ * Fade-in, as ink blooming in water: patches of the element surface first
+ * and the rest follows outward from them, each cell rising smoothly over its
+ * own part of the duration. Whole at `seconds`.
  */
-export function fadeIn(curve, start, z, ground) {
+export function fadeIn(curve, z) {
     requireCurve(curve);
-    const risen = ownChange(curve, start, order(1.7 + z));
-    return transition(curve, start, veiled((cell, t) => curve.ease(risen(cell, t)), curve.swing, ground));
+    const risen = ownChange(curve, order(1.7 + z));
+    return transition(curve, veiled((t) => {
+        const at = risen(t);
+        return (cell) => curve.ease(at(cell));
+    }, curve.swing));
 }
 /**
  * The rebound of a dissolve, every constant that makes it feel as it does —
@@ -496,25 +534,28 @@ export function fadeIn(curve, start, z, ground) {
  */
 const DISSOLVE_SHAPE = { depth: 0.4, from: 0.5, to: 0.95, maskFrom: 0.35, maskTo: 0.75, late: 0.6 };
 /**
- * Dissolve-out starting at `start`, as mist lifting: the element thins in
- * drifting patches, each cell fading smoothly over its own part of the
- * duration, until nothing is left at `start + seconds`. Mist does not lift
+ * Dissolve-out, as mist lifting: the element thins in drifting patches, each
+ * cell fading smoothly over its own part of the duration, until nothing is
+ * left at `seconds`. Mist does not lift
  * in one breath: towards the end, patches of what is left — the later a cell
  * goes, the likelier — rise back part way, as the last of it eddies, before
  * they thin away for good.
  */
-export function dissolveOut(curve, start, z, ground) {
+export function dissolveOut(curve, z) {
     requireCurve(curve);
     const place = order(4.2 + z);
     const eddy = order(9.3 + z);
-    const faded = ownChange(curve, start, place);
+    const faded = ownChange(curve, place);
     const { depth, from, to, maskFrom, maskTo, late } = DISSOLVE_SHAPE;
-    return transition(curve, start, veiled((cell, t) => {
-        const gone = curve.ease(faded(cell, 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;
-        return 1 - gone + back;
-    }, curve.swing, ground));
+    return transition(curve, veiled((t) => {
+        const at = faded(t);
+        return (cell) => {
+            const gone = curve.ease(at(cell));
+            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;
+            return 1 - gone + back;
+        };
+    }, curve.swing));
 }
 /**
  * The periods, in seconds, of the two noises a segment's stray from the
@@ -541,9 +582,10 @@ const STRAY = 180;
  * 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 `colors`, the element's own, never the terminal's.
+ * only happens to the element's own colours (`Drawn.colors`), never the
+ * terminal's.
  */
-export function wheel(curve, colors, fills, z) {
+export function wheel(curve, z) {
     requireCurve(curve);
     const P = curve.seconds;
     // A segment's seed, from the colour it is.
@@ -555,11 +597,34 @@ export function wheel(curve, colors, fills, z) {
         const s = seed(hex);
         return (360 * t) / P + curve.swing * STRAY * ((stray(s, t) - stray(s, 0)) / 1.5);
     };
-    return (drawn, cell, t) => {
+    return (t, { colors, fills }) => (shown, cell) => {
         // 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(drawn.fg.hex), bg: !cell.terminal.bg && colors.has(drawn.bg.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(drawn.fg, own.fg, drawn.bg, own.bg), bg: turn(drawn.bg, own.bg, drawn.fg, own.fg) };
+        return { fg: turn(shown.fg, own.fg, shown.bg, own.bg), bg: turn(shown.bg, own.bg, shown.fg, own.fg) };
     };
 }
+/**
+ * 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,
+ * with the light and the width it was signed off with. A loop comes lit on
+ * the element's own colours (`onColors`); a transition comes as itself, to
+ * be told when it is done. [LAW:types-are-the-program] Keyed by the two
+ * name types, which `EFFECT_CURVES` is held to as well: a curve signed off
+ * does not compile until it is named a loop or a transition, and then not
+ * until it has an entry here making one. A picker walking a section's names
+ * offers an effect added here with no change of its own.
+ */
+export const EFFECT_CATALOGUE = {
+    loops: {
+        shimmer: (element, curve = EFFECT_CURVES.shimmer) => onColors(shimmer(curve, element.span, 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)),
+        wheel: (element, curve = EFFECT_CURVES.wheel) => wheel(curve, element.z),
+    },
+    transitions: {
+        fade: (element, curve = EFFECT_CURVES.fade) => fadeIn(curve, element.z),
+        dissolve: (element, curve = EFFECT_CURVES.dissolve) => dissolveOut(curve, element.z),
+    },
+};

package/dist/renderables/flexStrip.d.ts

@@ -17,7 +17,7 @@
  */
 import { Segment } from "../core/segment.js";
 import type { Renderable, Measurable, RenderOptions } from "../core/protocol.js";
-import type { Joiner, StyledRenderable } from "../core/strip.js";
+import { type Joiner, type StyledRenderable } from "../core/strip.js";
 export type FlexAlign = "left" | "center" | "right" | "justify";
 export interface FlexStripOptions<T extends StyledRenderable> {
     /** Joiner used between items within a line, and at line endpoints. */

package/dist/renderables/flexStrip.js

@@ -16,6 +16,7 @@
  * FlexStrip reuses it verbatim. There is no second concept of "join."
  */
 import { Segment } from "../core/segment.js";
+import { drawItem, drawJoin } from "../core/strip.js";
 function renderToBlock(r, options) {
     const segments = [...r.render(options)];
     let width = 0;
@@ -63,10 +64,10 @@ export class FlexStrip {
         const joiner = this.joiner;
         // Pre-render every item and every joiner form we might need. Doing this
         // up-front turns packing into a pure data computation over widths.
-        const itemBlocks = items.map((it) => renderToBlock(it, options));
-        const startCap = (i) => joiner ? renderToBlock(joiner.join(null, items[i]), options) : EMPTY_BLOCK;
-        const endCap = (i) => joiner ? renderToBlock(joiner.join(items[i], null), options) : EMPTY_BLOCK;
-        const midJoin = (i, j) => joiner ? renderToBlock(joiner.join(items[i], items[j]), options) : EMPTY_BLOCK;
+        const itemBlocks = items.map((it) => renderToBlock(drawItem(it), options));
+        const startCap = (i) => joiner ? renderToBlock(drawJoin(joiner, null, items[i], { index: i }), options) : EMPTY_BLOCK;
+        const endCap = (i) => joiner ? renderToBlock(drawJoin(joiner, items[i], null, { index: i + 1 }), options) : EMPTY_BLOCK;
+        const midJoin = (i, j) => joiner ? renderToBlock(drawJoin(joiner, items[i], items[j], { index: j }), options) : EMPTY_BLOCK;
         const lines = [];
         let line = null;
         const gapBlock = gap > 0
@@ -177,23 +178,23 @@ export class FlexStrip {
         for (let i = 0; i < items.length; i++) {
             const itemWidth = renderToBlock(items[i], options).width;
             const sc = this.joiner
-                ? renderToBlock(this.joiner.join(null, items[i]), options).width
+                ? renderToBlock(drawJoin(this.joiner, null, items[i], { index: i }), options).width
                 : 0;
             const ec = this.joiner
-                ? renderToBlock(this.joiner.join(items[i], null), options).width
+                ? renderToBlock(drawJoin(this.joiner, items[i], null, { index: i + 1 }), options).width
                 : 0;
             minimum = Math.max(minimum, itemWidth + sc + ec);
             maximum += itemWidth;
             if (i > 0) {
                 maximum += this.gap * 2;
                 if (this.joiner) {
-                    maximum += renderToBlock(this.joiner.join(items[i - 1], items[i]), options).width;
+                    maximum += renderToBlock(drawJoin(this.joiner, items[i - 1], items[i], { index: i }), options).width;
                 }
             }
         }
         if (this.joiner) {
-            maximum += renderToBlock(this.joiner.join(null, items[0]), options).width;
-            maximum += renderToBlock(this.joiner.join(items[items.length - 1], null), options).width;
+            maximum += renderToBlock(drawJoin(this.joiner, null, items[0], { index: 0 }), options).width;
+            maximum += renderToBlock(drawJoin(this.joiner, items[items.length - 1], null, { index: items.length }), options).width;
         }
         return { minimum, maximum };
     }

package/dist/renderables/progressBar.js

@@ -7,7 +7,7 @@ import { Segment } from "../core/segment.js";
 import { Style } from "../core/style.js";
 import { drawable, getStyle } from "../core/protocol.js";
 import { Effected } from "./effect.js";
-import { EFFECT_CURVES, onColors, shimmer } from "./effects.js";
+import { EFFECT_CURVES, atShares, shimmer } from "./effects.js";
 const BAR = "━";
 const ASCII_BAR = "-";
 const HALF_BAR_RIGHT = "╸";
@@ -70,7 +70,8 @@ export class ProgressBar {
         const ink = back.drawnColors(depth).color ?? ColorSpec.default();
         const glow = getStyle(options, "bar.pulse").drawnColors(depth).color ?? ColorSpec.default();
         const loop = shimmer(PULSE_CURVE, width, PULSE_REACH, glow.getTruecolor(theme, true), 0);
-        return onColors(new Map([[ink.getTruecolor(theme, true).hex, 1]]), loop);
+        const whole = new Map([[ink.getTruecolor(theme, true).hex, 1]]);
+        return atShares(loop, () => whole);
     }
     /** Rich 9d8f9a3 `__rich_console__`: the fill is counted in half cells, and a total of zero is a bar already full. */
     completeHalves(width) {

package/dist/widgets/hit.js

@@ -11,6 +11,7 @@
  * answer "what is under the pointer", so the answer cannot disagree with what
  * the user sees. Z-order is paint order — whoever painted a cell last owns it.
  */
+import { drawnBy } from "../core/anchor.js";
 import { Segment } from "../core/segment.js";
 import { isScrollable } from "../core/protocol.js";
 import { WidgetBase } from "./widget-base.js";
@@ -72,10 +73,7 @@ export function originOf(frame, widget) {
  * or through a widget nested in its output.
  */
 export function drew(frame, widget, x, y) {
-    for (let a = Segment.anchorAt(frame, x, y); a; a = a.inner)
-        if (a.owner === widget)
-            return true;
-    return false;
+    return drawnBy(Segment.anchorAt(frame, x, y), widget);
 }
 /**
  * Where `widget`'s footprint sits in `frame`: the cell its row 0, column 0