@promptctl/rich-js 0.27.0 → 0.29.0

package/dist/renderables/progressBar.js

@@ -20,7 +20,7 @@ const HALF_BAR_LEFT = "╺";
  */
 const PULSE_CURVE = { ...EFFECT_CURVES.shimmer, seconds: 5 };
 const PULSE_REACH = 10;
-/** Rich's pulse back where the back style names no colour. */
+/** Rich's pulse back where the back style names no color. */
 const PULSE_BACK = ColorSpec.fromRgba(new ColorRgba(0, 0, 0));
 export class ProgressBar {
     // Rich's ProgressBar is updated after it is built: `bar.completed = n`.
@@ -70,31 +70,34 @@ export class ProgressBar {
             return;
         }
         const depth = options.colorSystem ?? ColorDepth.TRUECOLOR;
-        // Rich's pulse resolves its colours on the terminal a depth assumes, as
-        // `get_truecolor` does with no theme; so does this.
-        const theme = resolveTerminal(undefined, depth);
-        // Rich writes the pulse's back as a colour of its own, black where the
-        // back style names none, so the light always has the bar's colour to fall
+        // Rich's pulse resolves its colors on the terminal a depth assumes, as
+        // `get_truecolor` does with no theme; so does this with none named.
+        const terminal = resolveTerminal(options.terminal, depth);
+        // Rich writes the pulse's back as a color of its own, black where the
+        // back style names none, so the light always has the bar's color to fall
         // on: one the terminal supplies takes no light.
         const style = getStyle(options, this.style);
-        const ink = style.color?.isDefault === false ? style.color : ColorSpec.fromRgba((style.color ?? PULSE_BACK).getTruecolor(theme, true));
+        const ink = style.color?.isDefault === false ? style.color : ColorSpec.fromRgba((style.color ?? PULSE_BACK).getTruecolor(terminal, true));
         const back = style.add(Style.fromColor(ink));
         // [LAW:no-ambient-temporal-coupling] The moment is the frame's; the bar
         // only says what it looks like then. An empty track, lit by the shimmer.
         const track = { render: (o) => this.track(o, width, 0, back) };
-        yield* render(new Effected(track, this.pulseEffect(options, back, depth, theme), { key: "progress-bar", theme }), options);
+        yield* render(new Effected(track, this.pulseEffect(options, back), { key: "progress-bar" }), options);
     }
     /**
-     * The shimmer over this bar's back colour as `Effected` sees it drawn at
-     * `depth`, toward `bar.pulse`. A bar has no words to keep legible, so its
-     * back takes the whole of the light.
+     * The shimmer over this bar's back color as `Effected` sees it drawn,
+     * toward `bar.pulse`. A bar has no words to keep legible, so its back takes
+     * the whole of the light.
      */
-    pulseEffect(options, back, depth, theme) {
-        const ink = back.drawnColors(depth).color ?? ColorSpec.default();
-        const glow = getStyle(options, "bar.pulse").drawnColors(depth).color ?? ColorSpec.default();
-        const loop = shimmer(PULSE_CURVE, PULSE_REACH, glow.getTruecolor(theme, true), 0);
-        const whole = new Map([[ink.getTruecolor(theme, true).hex, 1]]);
-        return atShares(loop, () => whole);
+    pulseEffect(options, back) {
+        return (drawn) => {
+            const { depth, terminal } = drawn;
+            const ink = back.drawnColors(depth).color ?? ColorSpec.default();
+            const glow = getStyle(options, "bar.pulse").drawnColors(depth).color ?? ColorSpec.default();
+            const loop = shimmer(PULSE_CURVE, PULSE_REACH, glow.getTruecolor(terminal, true), 0);
+            const whole = new Map([[ink.getTruecolor(terminal, true).hex, 1]]);
+            return atShares(loop, () => whole)(drawn);
+        };
     }
     /** Rich 9d8f9a3 `__rich_console__`: the fill is counted in half cells, and a total of zero is a bar already full. */
     completeHalves(width) {
@@ -114,7 +117,7 @@ export class ProgressBar {
             yield new Segment(bar.repeat(barCount), fillStyle);
         if (halfBarCount)
             yield new Segment(drawable(options, HALF_BAR_RIGHT, " "), fillStyle);
-        // The back is drawn in colour alone, so an output with none leaves it blank.
+        // The back is drawn in color alone, so an output with none leaves it blank.
         if (options.colorSystem === null)
             return;
         let remaining = width - barCount - halfBarCount;

package/dist/renderables/prompt.d.ts

@@ -29,7 +29,7 @@ import { RichText } from "../core/text.js";
  * on, and resolves with the raw user response. Implementations decide where
  * the input comes from (stdin readline, network, in-memory queue, etc.); the
  * console is what the prompt is drawn with, as Rich's `Console.input` draws
- * it — its theme, its colours, the target it writes to.
+ * it — its theme, its colors, the target it writes to.
  *
  * [LAW:effects-at-boundaries] The prompt arrives as a `RichText`, not bytes:
  * encoding it is the console's job, and the console arrives with it.

package/dist/renderables/scroll.d.ts

@@ -5,7 +5,7 @@
  *
  * [LAW:one-type-per-behavior] A marquee, a scroll and a slide are one window
  * and differ only in the motion handed in: the offset along each axis is an
- * `Animation<number>`, so a marquee is a looping `Phase` scaled to the span
+ * `Animation<number>`, so a marquee is a looping `WrapMode` scaled to the span
  * it crosses and a slide-in is a `tween` to 0, and when the window next
  * changes is `Animation.all`'s answer over the two. Nothing here knows which
  * one it is drawing.

package/dist/renderables/scroll.js

@@ -5,7 +5,7 @@
  *
  * [LAW:one-type-per-behavior] A marquee, a scroll and a slide are one window
  * and differ only in the motion handed in: the offset along each axis is an
- * `Animation<number>`, so a marquee is a looping `Phase` scaled to the span
+ * `Animation<number>`, so a marquee is a looping `WrapMode` scaled to the span
  * it crosses and a slide-in is a `tween` to 0, and when the window next
  * changes is `Animation.all`'s answer over the two. Nothing here knows which
  * one it is drawing.
@@ -91,8 +91,8 @@ class ScrollFrame {
         // [LAW:one-source-of-truth] What the window shows is cut from the whole content, so it may change
         // when anything in the content does — a row above the slot entering pushes every row down, and run
         // backwards, leaving it pulls them up. The cut throws away the cells that hold rode on, so it is
-        // told to the frame (`RenderOptions.onHold`).
-        options.onHold?.({ lastChange: Segment.lastChange(drawn), nextChange: Segment.nextChange(drawn) });
+        // told to the frame (`RenderOptions.onValidity`).
+        options.onValidity?.({ validFrom: Segment.validFrom(drawn), validUntil: Segment.validUntil(drawn) });
         for (let r = 0; r < this.height; r++) {
             const line = lines[this.row + r] ?? [];
             const shown = Segment.divide(line, [start, start + width - blank])[1] ?? [];

package/dist/renderables/spinner.d.ts

@@ -75,8 +75,8 @@ export declare class Spinner implements Animation<Renderable & Measurable> {
     private readonly _ascii;
     /**
      * The spinner drawn at the frame's time, its cells saying the hold it is in
-     * on the host's clock (`stampFrame`) — exactly, for the frames the output
-     * draws, where `nextChange` must answer for both. Under reduced motion it
+     * on the host's clock (`stampValidityFrame`) — exactly, for the frames the output
+     * draws, where `validUntil` must answer for both. Under reduced motion it
      * is the spinner reduced, which never turns (`shownAt`).
      */
     private readonly _placed;
@@ -109,9 +109,9 @@ export declare class Spinner implements Animation<Renderable & Measurable> {
      * output keeps its own interval. An early answer, on the output that draws
      * the other one, which the contract allows; the drawn cells carry the exact one.
      */
-    nextChange(t: number): number;
+    validUntil(t: number): number;
     /** When the spinner drawn at `t` began to be drawn: the later of its two sequences' answers, by the same argument. */
-    lastChange(t: number): number;
+    validFrom(t: number): number;
     private _render;
     /**
      * The frame in progress and the label as one text, as Rich's

package/dist/renderables/spinner.js

@@ -46,7 +46,7 @@
  * frame forever, which a paused timeline is and a rate is not, and the
  * timeline refuses it.
  */
-import { Animation, frameTimeOf, holdOf, shownAt, stampFrame } from "../core/animation.js";
+import { Animation, frameTimeOf, validityOf, shownAt, stampValidityFrame } from "../core/animation.js";
 import { Segment } from "../core/segment.js";
 import { NULL_STYLE } from "../core/style.js";
 import { RichText } from "../core/text.js";
@@ -88,8 +88,8 @@ export class Spinner {
     _ascii;
     /**
      * The spinner drawn at the frame's time, its cells saying the hold it is in
-     * on the host's clock (`stampFrame`) — exactly, for the frames the output
-     * draws, where `nextChange` must answer for both. Under reduced motion it
+     * on the host's clock (`stampValidityFrame`) — exactly, for the frames the output
+     * draws, where `validUntil` must answer for both. Under reduced motion it
      * is the spinner reduced, which never turns (`shownAt`).
      */
     _placed;
@@ -113,7 +113,7 @@ export class Spinner {
         this._placed = this._frame((played, options) => {
             const t = frameTimeOf(options);
             const shown = shownAt(played, t, options);
-            return { value: shown.value, hold: holdOf(shown, t) };
+            return { value: shown.value, validity: validityOf(shown, t) };
         });
     }
     get frames() {
@@ -150,9 +150,9 @@ export class Spinner {
         const drawn = (options) => drawable(options, this._named, this._ascii, sequenceGlyphs);
         return {
             render: (options) => {
-                const { value, hold } = choose(drawn(options).played, options);
+                const { value, validity } = choose(drawn(options).played, options);
                 const segments = this._render(value, options);
-                return hold === undefined ? segments : stampFrame(segments, hold);
+                return validity === undefined ? segments : stampValidityFrame(segments, validity);
             },
             // Measured at the frames' one width, the widest frame's, so a column
             // holding it never narrows as it turns, and never offered less than
@@ -172,12 +172,12 @@ export class Spinner {
      * output keeps its own interval. An early answer, on the output that draws
      * the other one, which the contract allows; the drawn cells carry the exact one.
      */
-    nextChange(t) {
-        return Math.min(this._named.played.nextChange(t), this._ascii.played.nextChange(t));
+    validUntil(t) {
+        return Math.min(this._named.played.validUntil(t), this._ascii.played.validUntil(t));
     }
     /** When the spinner drawn at `t` began to be drawn: the later of its two sequences' answers, by the same argument. */
-    lastChange(t) {
-        return Math.max(this._named.played.lastChange(t), this._ascii.played.lastChange(t));
+    validFrom(t) {
+        return Math.max(this._named.played.validFrom(t), this._ascii.played.validFrom(t));
     }
     *_render(frame, options) {
         yield* render(this._line(frame, options), options);

package/dist/renderables/syntax.d.ts

@@ -2,10 +2,10 @@
  * Syntax — renders source code with basic syntax highlighting.
  * Uses built-in tokenization (no external dependency).
  *
- * Colours are names in the console's theme (`syntax.keyword`,
+ * Colors are names in the console's theme (`syntax.keyword`,
  * `syntax.line_number`, …), not a per-instance palette: a theme is how every
  * other renderable here is restyled, and a second styling vocabulary on this
- * one class would be a second answer to "what colour is a keyword".
+ * one class would be a second answer to "what color is a keyword".
  */
 import { Segment } from "../core/segment.js";
 import { type Measurable, type Renderable, type RenderOptions } from "../core/protocol.js";

package/dist/renderables/syntax.js

@@ -2,12 +2,13 @@
  * Syntax — renders source code with basic syntax highlighting.
  * Uses built-in tokenization (no external dependency).
  *
- * Colours are names in the console's theme (`syntax.keyword`,
+ * Colors are names in the console's theme (`syntax.keyword`,
  * `syntax.line_number`, …), not a per-instance palette: a theme is how every
  * other renderable here is restyled, and a second styling vocabulary on this
- * one class would be a second answer to "what colour is a keyword".
+ * one class would be a second answer to "what color is a keyword".
  */
-import { cellLen, expandTabs, parseTabSize } from "../core/cells.js";
+import { escaped } from "../core/bidi.js";
+import { cellLen, expandTabs, parseTabSize, unicodeEscape } from "../core/cells.js";
 import { Segment } from "../core/segment.js";
 import { RichText } from "../core/text.js";
 import { drawable, groundedStyle, getStyle, withBoundedWidth, withCellWidth, } from "../core/protocol.js";
@@ -89,7 +90,11 @@ export class Syntax {
         this.wordWrap = options?.wordWrap ?? false;
         const tabSize = parseTabSize(options?.tabSize ?? 4);
         this.tabSize = tabSize;
-        this._lines = expandTabs(code, tabSize).text.split("\n");
+        // Code on show: what the wire would drop is escaped, and an explicit bidi
+        // control with it. That is the Trojan Source attack: the order and the lines on
+        // screen differing from what the compiler reads. A joiner stays, since a Persian
+        // comment or an emoji string needs it. Only a CRLF's CR goes, with its line ending.
+        this._lines = expandTabs(escaped(code.replace(/\r\n/g, "\n"), unicodeEscape), tabSize).text.split("\n");
     }
     /**
      * The lines shown, as a 0-based half-open slice of `_lines`, and the number

package/dist/renderables/table.js

@@ -6,7 +6,7 @@ import { Segment } from "../core/segment.js";
 import { NULL_STYLE } from "../core/style.js";
 import { HEAVY_HEAD } from "../core/box.js";
 import { RichText } from "../core/text.js";
-import { EmbeddedText, embed, present } from "./embed.js";
+import { EmbeddedText, embed, mounted } from "./embed.js";
 import { Padding, normalizePadding } from "./padding.js";
 import { exactWeights, ratioDistribute, ratioReduce } from "./ratio.js";
 import { getStyle, render, stackedHeight, withBoundedWidth, withCellWidth } from "../core/protocol.js";
@@ -367,9 +367,9 @@ export class Table {
         // An empty title draws no row, as the reference's `if self.title` draws
         // none; markup that styles nothing is a title, and draws a blank one.
         const titleVal = options?.title;
-        this._title = present(titleVal) ? new EmbeddedText(titleVal) : undefined;
+        this._title = mounted(titleVal) ? new EmbeddedText(titleVal) : undefined;
         const captionVal = options?.caption;
-        this._caption = present(captionVal) ? new EmbeddedText(captionVal) : undefined;
+        this._caption = mounted(captionVal) ? new EmbeddedText(captionVal) : undefined;
         // A declared width is the table's size, not a ceiling on it: the
         // reference's `expand` is `self._expand or self.width is not None`, and a
         // port that sized to content inside it drew Rich code narrower than Rich.
@@ -454,11 +454,12 @@ export class Table {
         // that is all it styles: the reference reads it as `table_style` for the
         // frame and nowhere else, so a cell is untouched by it.
         const borderStyle = getStyle(options, this.style).add(getStyle(options, this.borderStyle));
-        const border = borderStyle.isNull ? undefined : borderStyle;
         // The one division of the width every row below is measured against.
         const outerWidth = this._outerWidth(options);
         const geometry = this._geometry(options, outerWidth);
         const edge = geometry.edge === 1;
+        // Only an edge closes a frame: without one, a table's rules are not a border.
+        const border = box && edge ? box.frame(borderStyle) : borderStyle.isNull ? undefined : borderStyle;
         // Title
         if (this._title) {
             yield* this._renderTitle(options, this._title, geometry.totalWidth, this.titleStyle, this.titleJustify);

package/dist/renderables/traceback.d.ts

@@ -13,7 +13,7 @@
  * an inspector session pausing on exceptions — would have to pause on every
  * throw, caught ones included, to serve `new Traceback(caughtError)`, and it
  * cannot exist in a browser at all. Nor is there a `width` or `theme`: those
- * sized and coloured a source-code excerpt this renderer does not produce.
+ * sized and colored a source-code excerpt this renderer does not produce.
  */
 import { Segment } from "../core/segment.js";
 import { type Renderable, type RenderOptions } from "../core/protocol.js";

package/dist/renderables/traceback.js

@@ -13,7 +13,7 @@
  * an inspector session pausing on exceptions — would have to pause on every
  * throw, caught ones included, to serve `new Traceback(caughtError)`, and it
  * cannot exist in a browser at all. Nor is there a `width` or `theme`: those
- * sized and coloured a source-code excerpt this renderer does not produce.
+ * sized and colored a source-code excerpt this renderer does not produce.
  */
 import { Segment } from "../core/segment.js";
 import { RichText } from "../core/text.js";

package/dist/renderables/tree.js

@@ -18,15 +18,15 @@ const ASCII_GUIDES = { fork: "+-- ", end: "`-- ", continue: "|   ", space: "
  * The guide attributes a glyph set stands for, switched off on the guide itself
  * as Rich's `remove_guide_styles` does: a bold guide is drawn heavy, not bold.
  */
-const REMOVE_GUIDE_STYLES = new Style({ bold: false, underline2: false });
+const REMOVE_GUIDE_STYLES = new Style({ bold: false, doubleUnderline: false });
 const guideGlyphs = (glyphs) => Object.values(glyphs).join("");
 /**
  * The glyphs a column of guide is drawn with, read off its resolved guide style
- * as Rich does: heavy when bold, double when underline2, light otherwise — and
+ * as Rich does: heavy when bold, double when doubleUnderline, light otherwise — and
  * ASCII whenever the terminal cannot draw the chosen set.
  */
 function glyphsFor(options, style) {
-    const weight = style.bold === true ? HEAVY_GUIDES : style.underline2 === true ? DOUBLE_GUIDES : LIGHT_GUIDES;
+    const weight = style.bold === true ? HEAVY_GUIDES : style.doubleUnderline === true ? DOUBLE_GUIDES : LIGHT_GUIDES;
     return drawable(options, weight, ASCII_GUIDES, guideGlyphs);
 }
 /** A row a label is known to draw, unread. */

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

@@ -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,78 +29,109 @@
  * 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 type { FuncMap } from "@promptctl/go-template-js";
+import { type EngineConfig } from "@promptctl/go-template-js";
 import type { RenderOptions } from "../core/protocol.js";
+import type { RichText } from "../core/text.js";
 import { Timeline } from "../core/timeline.js";
-/** What a registration is drawn on, beside the frame each evaluation is handed. */
-export interface AnimationFuncsOptions {
+/** What the animation functions are drawn on, beside the frame each evaluation is handed. */
+export interface AnimationOptions {
     /** The timeline to draw on, read once per call; the frame's own time when omitted. */
     readonly timeline?: () => Timeline;
 }
 /**
  * The frame a template is evaluated for, in the fields a render's options
- * carry under the same names: `time` in seconds, `onHold`, told when what a
- * function drew there changes, and the reader's preferences —
+ * carry under the same names: `time` in seconds, `onValidity`, told the hold of
+ * an animated value the output may depend on with no cell to carry it — one
+ * a decision read, whichever arm it took, a writing function's input, a
+ * throwing action's (the engine's `decided`) — and the reader's preferences,
  * `reducedMotion`, and `asciiOnly`, which the glyphs an effect picks for
  * itself go through. They arrive with every frame and nowhere else, so a
  * template drawn in an `App` is drawn as the app's preferences say.
  * [LAW:one-source-of-truth]
  *
- * `time` is on the clock `AnimationFuncsOptions.timeline` maps from, and
- * `onHold` hears on that clock. A host outside rich-js hands its own clock's
+ * `time` is on the clock `AnimationOptions.timeline` maps from, and
+ * `onValidity` hears on that clock. A host outside rich-js hands its own clock's
  * time. Inside a rich-js frame the time is the frame's, which its host's
  * timeline has already mapped, so a template drawn there registers no
  * `timeline` and is handed `templateFrame(options)`.
  */
-export interface TemplateFrame extends Pick<RenderOptions, "onHold" | "reducedMotion" | "asciiOnly"> {
+export interface TemplateFrame extends Pick<RenderOptions, "onValidity" | "reducedMotion" | "asciiOnly"> {
     readonly time: number;
 }
 /** The frame a renderable is drawn in, as the frame a template it evaluates there is drawn for. */
 export declare function templateFrame(options: RenderOptions): TemplateFrame;
 /**
- * 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 declare function animationFuncs(frame: () => TemplateFrame, options?: AnimationFuncsOptions): FuncMap;
+export declare function withAnimation(config: EngineConfig<RichText>, frame: () => TemplateFrame, options?: AnimationOptions): EngineConfig<RichText>;