@promptctl/rich-js 0.27.0 → 0.29.0

package/dist/template-bindings/animation-funcs.js

@@ -20,7 +20,7 @@
  * number the time is turned into first: a frame's stamp says when it changes
  * on the host's clock, which only `Timeline.run` can carry it back onto —
  * paused, never; backwards, at the hold it is about to drop under.
- * [LAW:single-enforcer] `drawing` is the one place the time, the timeline
+ * [LAW:single-enforcer] `drawn` is the one place the time, the timeline
  * and the reader's preference for motion are read, for every function.
  *
  * `frames <seconds> <frame> <seconds> <frame> …` is a `FrameSequence`
@@ -29,54 +29,89 @@
  * arguments on every evaluation, so the sequence is prepared on every one:
  * a template has nowhere to keep it, and keeping it here would be the memo
  * keyed on the arguments that `FrameSequence` is instead of. `stepped <seconds>
- * <color> <seconds> <color> …` is the colour in progress at the moment, a
- * colour value like every colour function's (`./color-funcs.ts`), so it
- * nests where a colour goes — `fg (stepped …)`, `readableOn (stepped …) $bg
+ * <color> <seconds> <color> …` is the color in progress at the moment, a
+ * color value like every color function's (`./color-funcs.ts`), so it
+ * nests where a color goes — `fg (stepped …)`, `ensureContrast (stepped …) $bg
  * 4.5` — and the ground it must read on is the template's to name, as it
- * is for any colour. Either argument list is one float/value cycle end to
+ * is for any color. Either argument list is one float/value cycle end to
  * end, so the engine's `alternating` gate types every slot and lifts each
  * string frame to a fragment; the pairing — a trailing hold with no frame or
- * colour — is parsed in `pairs`, once. [LAW:types-are-the-program]
+ * color — is parsed in `pairs`, once. [LAW:types-are-the-program]
  *
  * The rest start at a moment the template names, on the timeline's clock —
  * a field of the host's state, the moment a value changed — and each is the
  * animation `Timeline.play(start)` runs, so a start is a timeline like any
  * other and nothing here offsets a time by hand. `tween <seconds> <ease>
  * <start> <from> <to>` is a number eased from one value to another and held
- * (`core/tween.ts`), its ease spelled by name (`parseEase`); `loop <seconds>
+ * (`core/tween.ts`), its ease spelled by name (`parseEasing`); `loop <seconds>
  * <start>` is the way through a period, 0 to 1 and round again — two
  * cells started a step apart are a stagger. Each is a number, so it goes
- * wherever a number goes: a colour tween is `ramp (tween …) "linear" 0 $from
+ * wherever a number goes: a color tween is `ramp (tween …) "linear" 0 $from
  * 1 $to` and a ramp scrolling is `ramp (loop …) …`, because `ColorRamp` is
- * the one place two colours are blended and a colour tween is a two-stop
+ * the one place two colors are blended and a color tween is a two-stop
  * ramp read over time (`ColorRamp.over`). [LAW:one-source-of-truth] A
  * second blender here would be a second answer to what lies between two
- * colours. `glyphs <name> <start> <fragment>` is the fragment through a
+ * colors. `glyphs <name> <start> <fragment>` is the fragment through a
  * glyph effect from the catalogue (`GLYPH_EFFECT_CATALOGUE`), at its
  * defaults, before any render (`reglyphText`). Every argument list is an
  * exact arity of typed slots, so a slot of the wrong kind fails at the gate.
  *
  * Every function says when what it drew changes, so a host paints a
- * template while it moves and not after. `frames` and `glyphs` stamp the
- * fragment they draw (`textFrameAt`), covering its own glyphs. A number or a
- * colour carries no cells to stamp, so `tween`, `loop` and `stepped` tell
- * their hold to the frame instead (`TemplateFrame.onHold`), as a placed
- * animation of no cells does (`RenderOptions.onHold`). Nothing here claims
- * a moment it does not know.
+ * template while it moves and not after — and says it only for what the
+ * output depends on. A number or a color has no cells to carry a hold, and
+ * a fragment's cells lose theirs the moment it is flattened (`printf "%s"`),
+ * so no function stamps cells or tells the frame itself. Each marks its
+ * return with the hold its value is in (`marked`, the engine's evaluation
+ * provenance), and the engine carries the mark beside the value into every
+ * variable, dot and function the value passes through, reporting it where
+ * the output depends on it. `emitted` is where a template's cells take a
+ * hold: every fragment the template emits, stamped with the holds of the
+ * marked values its action read. `decided` is the route for a hold no cell
+ * can carry, told to the frame (`TemplateFrame.onValidity`): a mark an
+ * `if`/`with`/`range` consumed, whichever arm it took, because the frame may
+ * show cells for it later and must say when without a cell to say it on, as
+ * a placed animation of no cells does (`placed`) — and, by the same rule, a
+ * mark a writing function or a throwing action read; `EngineConfig.decided`
+ * is the authority on when it is called. A mark bound somewhere nobody reads
+ * is reported nowhere, so a value a template computes and never draws or
+ * decides on tells the frame nothing (rich-animation-27tq.0gd). Early, never
+ * late: an emission may carry a hold it did not strictly need, and a hold
+ * the output depends on is never dropped. [LAW:single-enforcer]
+ *
+ * The functions and the two hooks go into the host's engine config together,
+ * by `withAnimation`: the functions wired without the hooks would compile,
+ * draw and never say they move. [LAW:no-silent-failure]
  */
-import { Animation, frameTimeOf, holdOf, shownAt } from "../core/animation.js";
-import { Phase, beat, finiteTime, parseEase } from "../core/easing.js";
+import { marked } from "@promptctl/go-template-js";
+import { Animation, frameTimeOf, validityOf, shownAt, stampValidity } from "../core/animation.js";
+import { WrapMode, stepSequence, finiteTime, parseEasing } from "../core/easing.js";
+import { layerStyle } from "../core/style.js";
 import { Timeline } from "../core/timeline.js";
 import { tween } from "../core/tween.js";
 import { cellSeed } from "../renderables/effect.js";
 import { reglyphText } from "../renderables/glyph-effect.js";
 import { GLYPH_EFFECT_CATALOGUE } from "../renderables/glyph-effects.js";
-import { FrameSequence, textFrameAt } from "../renderables/frames.js";
+import { FrameSequence } from "../renderables/frames.js";
 import { asColor } from "./color-funcs.js";
 import { asFragment } from "./helpers.js";
 /** The frame a renderable is drawn in, as the frame a template it evaluates there is drawn for. */
 export function templateFrame(options) {
-    return { time: frameTimeOf(options), onHold: options.onHold, reducedMotion: options.reducedMotion, asciiOnly: options.asciiOnly };
+    return { time: frameTimeOf(options), onValidity: options.onValidity, reducedMotion: options.reducedMotion, asciiOnly: options.asciiOnly };
+}
+/**
+ * The mark a function puts on its return: the hold its value is in, and the
+ * frame it was drawn for, which is the one `decided` tells. Only the two
+ * hooks here read one; a consumer's own marks pass through them untouched,
+ * and a foreign token shaped like a `ValidityInterval` is not one.
+ * [LAW:types-are-the-program]
+ */
+class ValidityMark {
+    validity;
+    frame;
+    constructor(validity, frame) {
+        this.validity = validity;
+        this.frame = frame;
+    }
 }
 /** The host's own clock as a timeline: host time 0 at animation time 0, at rate 1. */
 const HOST_CLOCK = Timeline.play(0);
@@ -127,36 +162,41 @@ function glyphEffect(name) {
     return GLYPH_EFFECTS[name];
 }
 /**
- * Register `frames`, `stepped`, `tween`, `loop` and `glyphs`, each drawn for
- * the frame `frame` reports when the template is evaluated — its time in
- * seconds, from whatever zero the host counts from — through
- * `options.timeline`, and each telling that frame when what it drew changes.
+ * `config` with `frames`, `stepped`, `tween`, `loop` and `glyphs` registered
+ * beside its own functions, each drawn for the frame `frame` reports when
+ * the template is evaluated — its time in seconds, from whatever zero the
+ * host counts from — through `options.timeline`, and each marking its
+ * return with the hold it is in there; and with the two hooks that carry
+ * those holds to the cells (`emitted`) and the frame (`decided`) installed
+ * over any `config` already has, which still hear everything they did. One
+ * call, so the functions and the hooks that report for them cannot be wired
+ * apart: the functions alone would compile, draw, and never say they move.
+ * [LAW:types-are-the-program] [LAW:no-silent-failure] [LAW:composability]
+ * A `config` that already has one of the five names is refused, which is
+ * also what a second `withAnimation` over its own result meets: its template
+ * calls would otherwise reach these with no word said.
+ *
  * The functions exist whatever `frame` returns, so a template compiles once
  * and is evaluated at every moment the host draws. In a frame that says
  * `reducedMotion` each draws its animation reduced (`Animation.reduced`): a
  * loop at its start, a one-shot cut from where it starts to where it arrives
  * when it starts.
  */
-export function animationFuncs(frame, options = {}) {
+export function withAnimation(config, frame, options = {}) {
     const timeline = options.timeline ?? (() => HOST_CLOCK);
-    // `animation` on this call's timeline, and the time of `at`, the frame it
-    // is drawn in, read once a call so a value and its hold are one frame's.
-    const drawing = (what, animation, at) => [Timeline.run(timeline(), animation), finiteTime(what, at.time)];
-    // What a value animation shows now, under the reader's preference, its
-    // hold told to the frame: a value has no cells to carry it.
-    const now = (what, animation) => {
-        const at = frame();
-        const [drawn, t] = drawing(what, animation, at);
-        const shown = shownAt(drawn, t, at);
-        at.onHold?.(holdOf(shown, t));
-        return shown.value;
+    // What `animation`, on this call's timeline, shows in the frame `at`,
+    // under the reader's preference, marked with how long for: the time is
+    // read once a call so a value and its hold are one frame's.
+    const drawn = (what, animation, at) => {
+        const t = finiteTime(what, at.time);
+        const shown = shownAt(Timeline.run(timeline(), animation), t, at);
+        return marked(shown.value, new ValidityMark(validityOf(shown, t), at));
     };
     const startedAt = (start, animation) => Timeline.run(Timeline.play(start), animation);
     const framesFunc = {
         fn: ((...tail) => {
             const frames = pairs("frame", tail, asFragment).map(({ seconds, value }) => ({ seconds, text: value }));
-            const at = frame();
-            return textFrameAt(...drawing("frames", new FrameSequence(frames), at), at);
+            return drawn("frames", new FrameSequence(frames), frame());
         }),
         argTypes: ["float", "liftable"],
         arity: { kind: "alternating", minimum: 2 },
@@ -165,20 +205,20 @@ export function animationFuncs(frame, options = {}) {
     const steppedFunc = {
         fn: ((...tail) => {
             const steps = pairs("color", tail, (v) => asColor(v, "stepped"));
-            return steps[now("stepped", beat(steps.map((step) => step.seconds)))].value.hex;
+            return drawn("stepped", Animation.map(stepSequence(steps.map((s) => s.seconds)), (step) => steps[step].value.hex), frame());
         }),
         argTypes: ["float", "string"],
         arity: { kind: "alternating", minimum: 2 },
         returnType: "string",
     };
     const tweenFunc = {
-        fn: ((seconds, ease, start, from, to) => now("tween", startedAt(start, tween(from, to, { seconds, ease: parseEase(ease) })))),
+        fn: ((seconds, ease, start, from, to) => drawn("tween", startedAt(start, tween(from, to, { seconds, ease: parseEasing(ease) })), frame())),
         argTypes: ["float", "string", "float", "float", "float"],
         arity: { kind: "exact" },
         returnType: "float",
     };
     const loopFunc = {
-        fn: ((seconds, start) => now("loop", startedAt(start, Animation.continuous(Phase.loop(seconds))))),
+        fn: ((seconds, start) => drawn("loop", startedAt(start, Animation.continuous(WrapMode.loop(seconds))), frame())),
         argTypes: ["float", "float"],
         arity: { kind: "exact" },
         returnType: "float",
@@ -191,11 +231,54 @@ export function animationFuncs(frame, options = {}) {
             const key = fragment.plain;
             const at = frame();
             const reglyphed = reglyphText(fragment, make({ z: cellSeed(key, 0, 0) }), { key, asciiOnly: at.asciiOnly === true });
-            return textFrameAt(...drawing("glyphs", startedAt(start, reglyphed), at), at);
+            return drawn("glyphs", startedAt(start, reglyphed), at);
         }),
         argTypes: ["string", "float", "liftable"],
         arity: { kind: "exact" },
         returnType: "T",
     };
-    return { frames: framesFunc, stepped: steppedFunc, tween: tweenFunc, loop: loopFunc, glyphs: glyphsFunc };
+    const funcs = { frames: framesFunc, stepped: steppedFunc, tween: tweenFunc, loop: loopFunc, glyphs: glyphsFunc };
+    const taken = Object.keys(funcs).filter((name) => Object.hasOwn(config.funcs ?? {}, name));
+    if (taken.length > 0) {
+        throw new RangeError(`withAnimation registers ${taken.join(", ")}, already in config.funcs`);
+    }
+    const holdMarks = (marks) => [...marks].filter((mark) => mark instanceof ValidityMark);
+    // The holds among `marks` layered onto the fragment's base style, which an
+    // empty text still draws as its one piece of no width: `Style.add` keeps
+    // the later `validFrom` and the sooner `validUntil`, so cells that read
+    // two animated values are in the intersection of their holds, as two
+    // styles laid together are anywhere. A fragment no hold reaches is handed
+    // back as it came — the engine calls this for every emission — and one a
+    // hold reaches is a copy, since the engine may hand the one fragment a
+    // scope holds to more than one emission.
+    const held = (fragment, marks) => {
+        const holds = holdMarks(marks);
+        if (holds.length === 0)
+            return fragment;
+        const result = fragment.copy();
+        result.style = holds.reduce((style, mark) => layerStyle(style, stampValidity(mark.validity)), fragment.style);
+        return result;
+    };
+    const told = (marks) => {
+        for (const mark of holdMarks(marks))
+            mark.frame.onValidity?.(mark.validity);
+    };
+    // The hooks `config` brought run first and hear everything they did; a
+    // consumer that stamps or listens on its own loses nothing to this binding.
+    const emitted = config.emitted ?? ((fragment) => fragment);
+    const decided = config.decided ?? (() => { });
+    return {
+        ...config,
+        funcs: { ...config.funcs, ...funcs },
+        emitted: (fragment, marks) => held(emitted(fragment, marks), marks),
+        // `finally`: a consumer hook that throws still leaves the frame told its holds.
+        decided: (marks) => {
+            try {
+                decided(marks);
+            }
+            finally {
+                told(marks);
+            }
+        },
+    };
 }

package/dist/template-bindings/color-funcs.d.ts

@@ -44,9 +44,9 @@
  * No precision is given up: `darken`, `blendRgb`, and `contrastFor` already
  * take and return 8-bit `ColorRgba`. The one caveat is OKLCH: each of the
  * axis functions below round-trips sRGB→OKLCH→sRGB, so chaining three or more
- * of them quantizes visibly. Compose two, or reach for `transposePalette` when
+ * of them quantizes visibly. Compose two, or reach for `adjustPalette` when
  * a whole palette needs adapting — the same caveat that already applies to
- * chained transpositions.
+ * chained adjustments.
  *
  * ### Palette-free on purpose
  *
@@ -66,23 +66,23 @@ import { ColorDepth, type ColorRgba, type TerminalTheme } from "../core/color.js
  * same one — a palette name passed where a color belongs (`darken "primary" 2`)
  * — and an author who reads "wrap it: darken (color "primary")" is corrected in
  * one step, where "expected #RRGGBB" leaves them guessing. What it parses
- * must then be a colour these functions can compute with (`computable`).
+ * must then be a color these functions can compute with (`computable`).
  * [LAW:no-silent-failure]
  */
 export declare function asColor(value: string, func: string): ColorRgba;
 /**
- * A colour the colour functions can compute with. A fully transparent one — a
- * theme's "no background", `#00000000` — has no colour of its own: what shows
+ * A color the color functions can compute with. A fully transparent one — a
+ * theme's "no background", `#00000000` — has no color of its own: what shows
  * through it is whatever surface it lands on, which a template cannot know.
  * Darkening, mixing or contrasting it would answer for a surface nobody named,
- * so it is refused here, for every colour function and every `ramp` stop.
+ * so it is refused here, for every color function and every `ramp` stop.
  * [LAW:single-enforcer]
  */
-export declare function computable(colour: ColorRgba, func: string, written: string): ColorRgba;
+export declare function computable(color: ColorRgba, func: string, written: string): ColorRgba;
 /**
- * Where `readableOn`'s text will be drawn: the depth the output is encoded at,
- * and the terminal that draws it when that is known. At sixteen colours a
- * terminal paints each slot in its own theme's colour, so the floor is measured
+ * Where `ensureContrast`'s text will be drawn: the depth the output is encoded at,
+ * and the terminal that draws it when that is known. At sixteen colors a
+ * terminal paints each slot in its own theme's color, so the floor is measured
  * in `terminal`'s sixteen; without one, in the VGA defaults (the Windows
  * console's at `WINDOWS`). Both are facts about the one place the text lands,
  * so they arrive together.
@@ -92,11 +92,11 @@ export interface DrawnAt {
     readonly terminal?: TerminalTheme;
 }
 /**
- * The `readableOn` binding, measuring where `drawnAt` says the text lands when
+ * The `ensureContrast` binding, measuring where `drawnAt` says the text lands when
  * it is evaluated — a consumer that renders to a per-call destination
  * registers its own.
  */
-export declare const readableOnFunc: (drawnAt: () => DrawnAt) => TemplateFunc;
+export declare const ensureContrastFunc: (drawnAt: () => DrawnAt) => TemplateFunc;
 /**
  * The palette-free color vocabulary: every function takes colors and returns a
  * color, so they compose by nesting.
@@ -106,7 +106,7 @@ export declare const readableOnFunc: (drawnAt: () => DrawnAt) => TemplateFunc;
  * | `darken c n` / `lighten c n` | slide HSL lightness by N 10% levels |
  * | `mix a b pct` | blend `a` toward `b` by `pct`% (0 → `a`, 100 → `b`) |
  * | `contrastOn bg` | black or white, whichever is readable on `bg` |
- * | `readableOn fg bg ratio` | `fg` nudged in OKLCH lightness until it clears `ratio` on `bg`, hue preserved |
+ * | `ensureContrast fg bg ratio` | `fg` nudged in OKLCH lightness until it clears `ratio` on `bg`, hue preserved |
  * | `shiftHue c deg` | rotate hue in OKLCH |
  * | `scaleChroma c f` | multiply chroma (0 → gray, 1 → identity) |
  * | `scaleLightness c f` | multiply lightness (1 → identity, -1 → invert) |
@@ -116,7 +116,7 @@ export declare const readableOnFunc: (drawnAt: () => DrawnAt) => TemplateFunc;
  * `richTextStyleFuncs()`'s `fg`/`bg` to paint them onto text.
  *
  * @param drawnAt where the text will be drawn — the depth, and the terminal
- *   when known — read on every `readableOn` evaluation so a host that learns
+ *   when known — read on every `ensureContrast` evaluation so a host that learns
  *   its destination per render passes one getter; defaults to truecolor.
  */
 export declare function colorFuncs(drawnAt?: () => DrawnAt): FuncMap;

package/dist/template-bindings/color-funcs.js

@@ -44,9 +44,9 @@
  * No precision is given up: `darken`, `blendRgb`, and `contrastFor` already
  * take and return 8-bit `ColorRgba`. The one caveat is OKLCH: each of the
  * axis functions below round-trips sRGB→OKLCH→sRGB, so chaining three or more
- * of them quantizes visibly. Compose two, or reach for `transposePalette` when
+ * of them quantizes visibly. Compose two, or reach for `adjustPalette` when
  * a whole palette needs adapting — the same caveat that already applies to
- * chained transpositions.
+ * chained adjustments.
  *
  * ### Palette-free on purpose
  *
@@ -67,13 +67,13 @@ import { darken, contrastFor, ensureContrast } from "../themes/colorMath.js";
  * same one — a palette name passed where a color belongs (`darken "primary" 2`)
  * — and an author who reads "wrap it: darken (color "primary")" is corrected in
  * one step, where "expected #RRGGBB" leaves them guessing. What it parses
- * must then be a colour these functions can compute with (`computable`).
+ * must then be a color these functions can compute with (`computable`).
  * [LAW:no-silent-failure]
  */
 export function asColor(value, func) {
-    let colour;
+    let color;
     try {
-        colour = parseHexColor(value.trim());
+        color = parseHexColor(value.trim());
     }
     catch (cause) {
         if (!(cause instanceof ColorParseError))
@@ -81,24 +81,24 @@ export function asColor(value, func) {
         throw new TypeError(`${func} expected a color (#RRGGBB or #RRGGBBAA), got ${JSON.stringify(value)}` +
             ` — to use a palette name here, wrap it: ${func} (color ${JSON.stringify(value)}) …`, { cause });
     }
-    return computable(colour, func, JSON.stringify(value));
+    return computable(color, func, JSON.stringify(value));
 }
 /**
- * A colour the colour functions can compute with. A fully transparent one — a
- * theme's "no background", `#00000000` — has no colour of its own: what shows
+ * A color the color functions can compute with. A fully transparent one — a
+ * theme's "no background", `#00000000` — has no color of its own: what shows
  * through it is whatever surface it lands on, which a template cannot know.
  * Darkening, mixing or contrasting it would answer for a surface nobody named,
- * so it is refused here, for every colour function and every `ramp` stop.
+ * so it is refused here, for every color function and every `ramp` stop.
  * [LAW:single-enforcer]
  */
-export function computable(colour, func, written) {
-    if (colour.alpha === 0) {
-        throw new RangeError(`${func} got ${written}, which is fully transparent: it draws no colour of its own, ` +
-            `so there is nothing to compute with — use the colour of the surface it sits on, e.g. (color "background")`);
+export function computable(color, func, written) {
+    if (color.alpha === 0) {
+        throw new RangeError(`${func} got ${written}, which is fully transparent: it draws no color of its own, ` +
+            `so there is nothing to compute with — use the color of the surface it sits on, e.g. (color "background")`);
     }
-    return colour;
+    return color;
 }
-// [LAW:single-enforcer] Every colour function is fixed-arity, so the engine's
+// [LAW:single-enforcer] Every color function is fixed-arity, so the engine's
 // arity gate refuses a missing or surplus argument before the body runs.
 function colorFunc(argTypes, fn) {
     return { fn, argTypes, arity: { kind: "exact" }, returnType: "string" };
@@ -147,7 +147,7 @@ const mixFunc = colorFunc(["string", "string", "float"], ((fromHex, towardHex, p
 //
 // Two different questions, so two functions rather than one with a flag:
 // `contrastOn` asks "what is maximally readable here" (black or white, WCAG
-// relative-luminance cutoff); `readableOn` asks "keep this color recognizably
+// relative-luminance cutoff); `ensureContrast` asks "keep this color recognizably
 // itself, but guarantee it clears `ratio`" — it slides OKLCH lightness and
 // preserves hue, so a blue on dark blue becomes a lighter blue rather than
 // white.
@@ -168,19 +168,19 @@ const RATIO_RANGE = {
 const contrastOnFunc = colorFunc(["string"], ((bgHex) => contrastFor(asColor(bgHex, "contrastOn")).hex));
 const TRUECOLOR = { depth: ColorDepth.TRUECOLOR };
 /**
- * The `readableOn` binding, measuring where `drawnAt` says the text lands when
+ * The `ensureContrast` binding, measuring where `drawnAt` says the text lands when
  * it is evaluated — a consumer that renders to a per-call destination
  * registers its own.
  */
-export const readableOnFunc = (drawnAt) => colorFunc(["string", "string", "float"], ((fgHex, bgHex, ratio) => {
+export const ensureContrastFunc = (drawnAt) => colorFunc(["string", "string", "float"], ((fgHex, bgHex, ratio) => {
     const { depth, terminal } = drawnAt();
-    return ensureContrast(asColor(fgHex, "readableOn"), asColor(bgHex, "readableOn"), asAmount(ratio, "readableOn", "ratio", RATIO_RANGE), depth, undefined, terminal).hex;
+    return ensureContrast(asColor(fgHex, "ensureContrast"), asColor(bgHex, "ensureContrast"), asAmount(ratio, "ensureContrast", "ratio", RATIO_RANGE), depth, undefined, terminal).hex;
 }));
 // --- OKLCH axes ---
 //
-// [LAW:one-source-of-truth] One function per `ThemeKey` axis, and the table is
-// keyed BY the axis so the compiler proves it total: add a field to `ThemeKey`
-// and this object stops satisfying `Record<keyof ThemeKey, string>` until a
+// [LAW:one-source-of-truth] One function per `ColorAdjustment` axis, and the table is
+// keyed BY the axis so the compiler proves it total: add a field to `ColorAdjustment`
+// and this object stops satisfying `Record<keyof ColorAdjustment, string>` until a
 // binding name is chosen for it. The same derive-registrations-from-the-real-
 // inventory trick `attributeFuncs()` uses over `ATTRIBUTE_NAMES`.
 //
@@ -218,7 +218,7 @@ function oklchAxisFuncs() {
  * | `darken c n` / `lighten c n` | slide HSL lightness by N 10% levels |
  * | `mix a b pct` | blend `a` toward `b` by `pct`% (0 → `a`, 100 → `b`) |
  * | `contrastOn bg` | black or white, whichever is readable on `bg` |
- * | `readableOn fg bg ratio` | `fg` nudged in OKLCH lightness until it clears `ratio` on `bg`, hue preserved |
+ * | `ensureContrast fg bg ratio` | `fg` nudged in OKLCH lightness until it clears `ratio` on `bg`, hue preserved |
  * | `shiftHue c deg` | rotate hue in OKLCH |
  * | `scaleChroma c f` | multiply chroma (0 → gray, 1 → identity) |
  * | `scaleLightness c f` | multiply lightness (1 → identity, -1 → invert) |
@@ -228,7 +228,7 @@ function oklchAxisFuncs() {
  * `richTextStyleFuncs()`'s `fg`/`bg` to paint them onto text.
  *
  * @param drawnAt where the text will be drawn — the depth, and the terminal
- *   when known — read on every `readableOn` evaluation so a host that learns
+ *   when known — read on every `ensureContrast` evaluation so a host that learns
  *   its destination per render passes one getter; defaults to truecolor.
  */
 export function colorFuncs(drawnAt = () => TRUECOLOR) {
@@ -237,7 +237,7 @@ export function colorFuncs(drawnAt = () => TRUECOLOR) {
         lighten: lightenFunc,
         mix: mixFunc,
         contrastOn: contrastOnFunc,
-        readableOn: readableOnFunc(drawnAt),
+        ensureContrast: ensureContrastFunc(drawnAt),
         ...oklchAxisFuncs(),
     };
 }

package/dist/template-bindings/index.d.ts

@@ -6,26 +6,28 @@
  * functions. The split between the two exported registrations is exactly the
  * split between what needs a theme and what does not:
  *
- * - `richTextFuncs()` — the colour sinks (`fg`/`bg`), the palette-free colour
+ * - `richTextFuncs()` — the color sinks (`fg`/`bg`), the palette-free color
  *   math (`darken`, `mix`, `contrastOn`, the OKLCH axes …), text attributes,
  *   and `link`. Needs no configuration; safe to register unconditionally. A
- *   consumer with no theme system still gets the complete colour vocabulary by
+ *   consumer with no theme system still gets the complete color vocabulary by
  *   feeding it hex literals.
  * - `paletteFuncs(getPalette)` — `color` and `ramp`, the two functions that
  *   resolve a palette name. This is the *only* registration that knows a
  *   palette exists. [LAW:one-way-deps]
- * - `animationFuncs(frame)` — `frames`, `stepped`, `tween`, `loop` and
- *   `glyphs`, drawn for a moment on a timeline. It is the only registration
- *   that knows the template is evaluated at a time, and the time and the
- *   timeline are the host's to hand in (`./animation-funcs.ts`).
+ * - `withAnimation(config, frame)` — the engine config with `frames`,
+ *   `stepped`, `tween`, `loop` and `glyphs` registered, drawn for a moment on
+ *   a timeline, and the two engine hooks their holds reach the frame through
+ *   installed beside them. It is the only registration that knows the
+ *   template is evaluated at a time, and the time and the timeline are the
+ *   host's to hand in (`./animation-funcs.ts`).
  *
  * `createRichTextEngine()` wires up `richTextFuncs()` only — it cannot supply a
- * palette. Consumers that name theme colours call `paletteFuncs(getPalette)`
+ * palette. Consumers that name theme colors call `paletteFuncs(getPalette)`
  * and merge it into their own engine config.
  *
- * Colours compose by nesting, like every other function:
+ * Colors compose by nesting, like every other function:
  * `{{ fg (darken (color "primary") 2) (bold "x") }}`. There is no second
- * markup grammar and no colour-spec mini-language — the template *is* the
+ * markup grammar and no color-spec mini-language — the template *is* the
  * composition mechanism.
  *
  * Fragment type: `RichText`. Chosen because it is the library's primary
@@ -42,14 +44,14 @@ import { Segment } from "../core/segment.js";
 import type { RenderOptions } from "../core/protocol.js";
 import { type DrawnAt } from "./color-funcs.js";
 export { paletteFuncs } from "./palette-funcs.js";
-export { colorFuncs, readableOnFunc, type DrawnAt } from "./color-funcs.js";
-export { animationFuncs, templateFrame, type AnimationFuncsOptions, type TemplateFrame } from "./animation-funcs.js";
+export { colorFuncs, ensureContrastFunc, type DrawnAt } from "./color-funcs.js";
+export { withAnimation, templateFrame, type AnimationOptions, type TemplateFrame } from "./animation-funcs.js";
 /**
- * Funcs registered by the rich-js binding — the colour sinks, the palette-free
- * colour math, text attributes, and the `link` cell-splitter. Nothing here
+ * Funcs registered by the rich-js binding — the color sinks, the palette-free
+ * color math, text attributes, and the `link` cell-splitter. Nothing here
  * needs a theme; the two that do (`color`, `ramp`) ship separately via
  * `paletteFuncs(getPalette)`, merged consumer-side. `drawnAt` is forwarded to
- * `colorFuncs` — the depth `readableOn` measures at, truecolor when omitted.
+ * `colorFuncs` — the depth `ensureContrast` measures at, truecolor when omitted.
  *
  * `FuncMap` is not parameterised over `T` in `@promptctl/go-template-js` — the engine's
  * `T` lives on the `Engine`/`EngineConfig`, and per-function input/output

package/dist/template-bindings/index.js

@@ -6,26 +6,28 @@
  * functions. The split between the two exported registrations is exactly the
  * split between what needs a theme and what does not:
  *
- * - `richTextFuncs()` — the colour sinks (`fg`/`bg`), the palette-free colour
+ * - `richTextFuncs()` — the color sinks (`fg`/`bg`), the palette-free color
  *   math (`darken`, `mix`, `contrastOn`, the OKLCH axes …), text attributes,
  *   and `link`. Needs no configuration; safe to register unconditionally. A
- *   consumer with no theme system still gets the complete colour vocabulary by
+ *   consumer with no theme system still gets the complete color vocabulary by
  *   feeding it hex literals.
  * - `paletteFuncs(getPalette)` — `color` and `ramp`, the two functions that
  *   resolve a palette name. This is the *only* registration that knows a
  *   palette exists. [LAW:one-way-deps]
- * - `animationFuncs(frame)` — `frames`, `stepped`, `tween`, `loop` and
- *   `glyphs`, drawn for a moment on a timeline. It is the only registration
- *   that knows the template is evaluated at a time, and the time and the
- *   timeline are the host's to hand in (`./animation-funcs.ts`).
+ * - `withAnimation(config, frame)` — the engine config with `frames`,
+ *   `stepped`, `tween`, `loop` and `glyphs` registered, drawn for a moment on
+ *   a timeline, and the two engine hooks their holds reach the frame through
+ *   installed beside them. It is the only registration that knows the
+ *   template is evaluated at a time, and the time and the timeline are the
+ *   host's to hand in (`./animation-funcs.ts`).
  *
  * `createRichTextEngine()` wires up `richTextFuncs()` only — it cannot supply a
- * palette. Consumers that name theme colours call `paletteFuncs(getPalette)`
+ * palette. Consumers that name theme colors call `paletteFuncs(getPalette)`
  * and merge it into their own engine config.
  *
- * Colours compose by nesting, like every other function:
+ * Colors compose by nesting, like every other function:
  * `{{ fg (darken (color "primary") 2) (bold "x") }}`. There is no second
- * markup grammar and no colour-spec mini-language — the template *is* the
+ * markup grammar and no color-spec mini-language — the template *is* the
  * composition mechanism.
  *
  * Fragment type: `RichText`. Chosen because it is the library's primary
@@ -44,14 +46,14 @@ import { render } from "../core/protocol.js";
 import { richTextStyleFuncs } from "./style-funcs.js";
 import { colorFuncs } from "./color-funcs.js";
 export { paletteFuncs } from "./palette-funcs.js";
-export { colorFuncs, readableOnFunc } from "./color-funcs.js";
-export { animationFuncs, templateFrame } from "./animation-funcs.js";
+export { colorFuncs, ensureContrastFunc } from "./color-funcs.js";
+export { withAnimation, templateFrame } from "./animation-funcs.js";
 /**
- * Funcs registered by the rich-js binding — the colour sinks, the palette-free
- * colour math, text attributes, and the `link` cell-splitter. Nothing here
+ * Funcs registered by the rich-js binding — the color sinks, the palette-free
+ * color math, text attributes, and the `link` cell-splitter. Nothing here
  * needs a theme; the two that do (`color`, `ramp`) ship separately via
  * `paletteFuncs(getPalette)`, merged consumer-side. `drawnAt` is forwarded to
- * `colorFuncs` — the depth `readableOn` measures at, truecolor when omitted.
+ * `colorFuncs` — the depth `ensureContrast` measures at, truecolor when omitted.
  *
  * `FuncMap` is not parameterised over `T` in `@promptctl/go-template-js` — the engine's
  * `T` lives on the `Engine`/`EngineConfig`, and per-function input/output
@@ -84,6 +86,7 @@ export function richTextFuncs(drawnAt) {
 export function createRichTextEngine() {
     return createEngine({
         fromString: (s) => new RichText(s),
+        isT: (v) => v instanceof RichText,
         toString: (rt) => rt.plain,
         funcs: richTextFuncs(),
     });

package/dist/template-bindings/palette-funcs.d.ts

@@ -69,7 +69,7 @@ import type { Palette } from "../themes/palette.js";
  *
  * `color` resolves a palette variable name to its hex string — `#RRGGBB`, or
  * `#00000000` for a theme's "no background", which `bg` paints as no
- * background and the colour functions refuse — and passes
+ * background and the color functions refuse — and passes
  * an already-literal color through unchanged. That second half is not a
  * convenience — it makes `color` **idempotent**, which is what lets consumers
  * apply it unconditionally to any author-written color string without first
@@ -83,7 +83,7 @@ import type { Palette } from "../themes/palette.js";
  * @example
  * ```ts
  * const engine = createEngine({
- *   fromString: (s) => new RichText(s),
+ *   fromString: (s) => new RichText(s), isT: (v) => v instanceof RichText,
  *   toString: (rt) => rt.plain,
  *   funcs: {
  *     ...richTextFuncs(),