@promptctl/rich-js 0.28.0 → 0.29.0

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

@@ -29,36 +29,36 @@
  * 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 — and says it only for what the
- * output depends on. A number or a colour has no cells to carry a hold, and
+ * 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
@@ -67,7 +67,7 @@
  * 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.onHold`): a mark an
+ * 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
@@ -83,8 +83,8 @@
  * draw and never say they move. [LAW:no-silent-failure]
  */
 import { marked } from "@promptctl/go-template-js";
-import { Animation, frameTimeOf, holdOf, shownAt, stamp } from "../core/animation.js";
-import { Phase, beat, finiteTime, parseEase } from "../core/easing.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";
@@ -96,20 +96,20 @@ 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 `Hold` is not one.
+ * and a foreign token shaped like a `ValidityInterval` is not one.
  * [LAW:types-are-the-program]
  */
-class HoldMark {
-    hold;
+class ValidityMark {
+    validity;
     frame;
-    constructor(hold, frame) {
-        this.hold = hold;
+    constructor(validity, frame) {
+        this.validity = validity;
         this.frame = frame;
     }
 }
@@ -190,7 +190,7 @@ export function withAnimation(config, frame, options = {}) {
     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 HoldMark(holdOf(shown, t), at));
+        return marked(shown.value, new ValidityMark(validityOf(shown, t), at));
     };
     const startedAt = (start, animation) => Timeline.run(Timeline.play(start), animation);
     const framesFunc = {
@@ -205,20 +205,20 @@ export function withAnimation(config, frame, options = {}) {
     const steppedFunc = {
         fn: ((...tail) => {
             const steps = pairs("color", tail, (v) => asColor(v, "stepped"));
-            return drawn("stepped", Animation.map(beat(steps.map((s) => s.seconds)), (step) => steps[step].value.hex), frame());
+            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) => drawn("tween", startedAt(start, tween(from, to, { seconds, ease: parseEase(ease) })), frame())),
+        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) => drawn("loop", startedAt(start, Animation.continuous(Phase.loop(seconds))), frame())),
+        fn: ((seconds, start) => drawn("loop", startedAt(start, Animation.continuous(WrapMode.loop(seconds))), frame())),
         argTypes: ["float", "float"],
         arity: { kind: "exact" },
         returnType: "float",
@@ -242,10 +242,10 @@ export function withAnimation(config, frame, options = {}) {
     if (taken.length > 0) {
         throw new RangeError(`withAnimation registers ${taken.join(", ")}, already in config.funcs`);
     }
-    const holdMarks = (marks) => [...marks].filter((mark) => mark instanceof HoldMark);
+    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 `lastChange` and the sooner `nextChange`, so cells that read
+    // 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
@@ -256,12 +256,12 @@ export function withAnimation(config, frame, options = {}) {
         if (holds.length === 0)
             return fragment;
         const result = fragment.copy();
-        result.style = holds.reduce((style, mark) => layerStyle(style, stamp(mark.hold)), fragment.style);
+        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.onHold?.(mark.hold);
+            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.

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,10 +6,10 @@
  * 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
@@ -22,12 +22,12 @@
  *   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 +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 { 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,10 +6,10 @@
  * 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
@@ -22,12 +22,12 @@
  *   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
@@ -46,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 { 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

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

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

@@ -63,7 +63,7 @@
  * they are gone.
  */
 import { resolveColorRef } from "../themes/colorRef.js";
-import { parseEase } from "../core/easing.js";
+import { parseEasing } from "../core/easing.js";
 import { ColorRamp } from "../themes/ramp.js";
 import { computable } from "./color-funcs.js";
 /**
@@ -97,7 +97,7 @@ function colorStops(tail, palette) {
  *
  * `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
@@ -135,7 +135,7 @@ export function paletteFuncs(getPalette) {
     // value, the ease, and one stop, so the gate refuses a stopless call.
     // [LAW:types-are-the-program]
     const rampFunc = {
-        fn: ((value, ease, ...tail) => new ColorRamp(parseEase(ease), colorStops(tail, getPalette())).at(value)
+        fn: ((value, ease, ...tail) => new ColorRamp(parseEasing(ease), colorStops(tail, getPalette())).at(value)
             .hex),
         argTypes: ["float", "string"],
         arity: { kind: "alternating", minimum: 4 },

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

@@ -3,7 +3,7 @@
  *
  * [LAW:one-source-of-truth] The function inventory below mirrors the
  * string-syntax style vocabulary documented in `docs/style.md` — the two
- * colour slots (`fg`/`bg`), text attributes (positive + negated), short
+ * color slots (`fg`/`bg`), text attributes (positive + negated), short
  * aliases, and the hyperlink. Each registration is a templating-time analogue
  * of a piece of `Style.parse`, so a template fragment composed by these
  * functions round-trips through `Style` without semantic drift.
@@ -12,17 +12,17 @@
  * shape: child `RichText` in, `RichText` out. The styling difference
  * lives in a captured `Style` value (or constructor closure), not in
  * branches inside a single dispatch. That is why this file is mostly
- * factories — the data (the colour, the attribute name) is the
+ * factories — the data (the color, the attribute name) is the
  * variability; the operation is fixed.
  */
 import type { FuncMap } from "@promptctl/go-template-js";
 /**
- * Text-styling registrations: the two colour sinks (`fg`, `bg`), text
+ * Text-styling registrations: the two color sinks (`fg`, `bg`), text
  * attributes (canonical names, short aliases, and `not_*` negations), the
  * hyperlink cell-splitter (`link`), and the multi-attribute `style` spec.
  *
- * Colours themselves come from elsewhere: `colorFuncs()` for the palette-free
- * math, `paletteFuncs()` for naming a theme colour. This module only paints.
+ * Colors themselves come from elsewhere: `colorFuncs()` for the palette-free
+ * math, `paletteFuncs()` for naming a theme color. This module only paints.
  * [LAW:one-way-deps] — nothing here imports a palette.
  */
 export declare function richTextStyleFuncs(): FuncMap;

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

@@ -3,7 +3,7 @@
  *
  * [LAW:one-source-of-truth] The function inventory below mirrors the
  * string-syntax style vocabulary documented in `docs/style.md` — the two
- * colour slots (`fg`/`bg`), text attributes (positive + negated), short
+ * color slots (`fg`/`bg`), text attributes (positive + negated), short
  * aliases, and the hyperlink. Each registration is a templating-time analogue
  * of a piece of `Style.parse`, so a template fragment composed by these
  * functions round-trips through `Style` without semantic drift.
@@ -12,7 +12,7 @@
  * shape: child `RichText` in, `RichText` out. The styling difference
  * lives in a captured `Style` value (or constructor closure), not in
  * branches inside a single dispatch. That is why this file is mostly
- * factories — the data (the colour, the attribute name) is the
+ * factories — the data (the color, the attribute name) is the
  * variability; the operation is fixed.
  */
 import { Style, ATTRIBUTE_NAMES, ATTRIBUTE_SHORT_ALIASES, } from "../core/style.js";
@@ -26,26 +26,26 @@ function attrFunc(style) {
         returnType: "T",
     };
 }
-// --- Colour sinks ---
+// --- Color sinks ---
 //
-// `fg` and `bg` are the only two colour-applying functions, and they are the
-// terminal step of the colour pipeline: `color` names a colour, the functions
+// `fg` and `bg` are the only two color-applying functions, and they are the
+// terminal step of the color pipeline: `color` names a color, the functions
 // in `color-funcs.ts` transform it, these paint it onto text.
 //
 // [LAW:composability] They replace five separate families — one function per
-// ANSI colour name (`red`, `bright_blue`, …), `hex`, `rgb`, `color` (256-index),
-// and `on` (background). Every one of those encoded *which colour* in the
+// ANSI color name (`red`, `bright_blue`, …), `hex`, `rgb`, `color` (256-index),
+// and `on` (background). Every one of those encoded *which color* in the
 // function's identity, so the vocabulary could only grow by adding names, and
-// a colour computed at render time could not be applied at all. Here the colour
-// is an argument, so the sink admits every colour that exists and every colour
+// a color computed at render time could not be applied at all. Here the color
+// is an argument, so the sink admits every color that exists and every color
 // that will ever exist. Two functions, unbounded reach.
 //
 // [LAW:types-are-the-program] The slot accepts the full `ColorSpec.parse`
-// vocabulary, which is wider than the hex the colour math produces — and that
-// width is deliberate, not laxity. `#7aa2f7` is a *concrete* colour; `"red"`
+// vocabulary, which is wider than the hex the color math produces — and that
+// width is deliberate, not laxity. `#7aa2f7` is a *concrete* color; `"red"`
 // and `"color(42)"` are *symbolic* ones the terminal resolves against its own
-// theme. Only concrete colours can be darkened or blended, which is why the
-// colour-math functions take hex alone; but both kinds can be painted, so the
+// theme. Only concrete colors can be darkened or blended, which is why the
+// color-math functions take hex alone; but both kinds can be painted, so the
 // sink takes the union. The type of each slot is exactly the set of values that
 // slot can mean something for.
 function colorSinkFunc(slot) {
@@ -138,12 +138,12 @@ const linkFunc = {
 };
 // --- Public assembly ---
 /**
- * Text-styling registrations: the two colour sinks (`fg`, `bg`), text
+ * Text-styling registrations: the two color sinks (`fg`, `bg`), text
  * attributes (canonical names, short aliases, and `not_*` negations), the
  * hyperlink cell-splitter (`link`), and the multi-attribute `style` spec.
  *
- * Colours themselves come from elsewhere: `colorFuncs()` for the palette-free
- * math, `paletteFuncs()` for naming a theme colour. This module only paints.
+ * Colors themselves come from elsewhere: `colorFuncs()` for the palette-free
+ * math, `paletteFuncs()` for naming a theme color. This module only paints.
  * [LAW:one-way-deps] — nothing here imports a palette.
  */
 export function richTextStyleFuncs() {