@promptctl/rich-js 0.24.0 → 0.25.0

package/dist/renderables/viewport.js

@@ -1,6 +1,10 @@
 /**
- * Viewport — a fixed number of rows onto a taller renderable, scrolled by an
- * offset that cannot leave the content.
+ * Viewport — a scroll position: a fixed number of rows onto taller content,
+ * scrolled by an offset that cannot leave it. It holds the position, not the
+ * content: content is drawn through it with `showing` (or `showingLines`), so
+ * a view rebuilt every frame keeps one viewport under content it builds anew.
+ * [LAW:one-source-of-truth] That is the one way to draw through it, so no
+ * viewport is built around content it never draws.
  *
  * Its rows, under the `Height` contract in `../core/protocol.ts`: the region's
  * when it is given one; otherwise its own configured rows, or the content's
@@ -19,11 +23,18 @@
  * against exists before a render: the rows come from the budget the render is
  * handed, and the content's length from rendering it at the width it is handed.
  * So `scrollTo`, `scrollBy` and `ensureVisible` do not move anything when they
- * are called. Each queues a move, and the next render resolves the queue in
- * call order, clamping after every move, against the rows and length that
- * render found. Calling an operation before the first render, or three of them
+ * are called. Each queues a move, and the next render that draws the content
+ * resolves the queue in call order, clamping after every move, against the
+ * rows and length that render found. Calling an operation before the first render, or three of them
  * between two renders, is the same code path as calling one.
  *
+ * A render changes nothing (`State`, `../core/state.ts`), so the render draws
+ * the offset it resolved without keeping it, and hands the keeping to its pass
+ * (`afterPass`): once the frame has been drawn whole, the offset, the rows and
+ * length it was clamped against, and the followed range become the viewport's,
+ * and the moves it resolved leave the queue. A measurement, which draws
+ * nothing anyone sees, keeps nothing.
+ *
  * Every cell of its rows, gutter included, is stamped as its own
  * (`Segment.anchorLines`), around whatever anchors its content drew. So the
  * composed frame names the viewport under any of its cells however deep it is
@@ -35,7 +46,16 @@ import { Segment } from "../core/segment.js";
 import { Measurement } from "../core/measure.js";
 import { cellCount, cellLen } from "../core/cells.js";
 import { NULL_STYLE } from "../core/style.js";
-import { drawable, fitHeight, getStyle, regionRows, withBoundedWidth, withCellWidth, } from "../core/protocol.js";
+import { drawable, drawsNothing, fitHeight, getStyle, regionRows, withBoundedWidth, withCellWidth, } from "../core/protocol.js";
+import { afterPass, render } from "../core/protocol.js";
+import { ListState, State } from "../core/state.js";
+/** `content` drawn whole at the width `options` offers, as lines a viewport slices. */
+function drawnWhole(content) {
+    return (options) => {
+        const all = Segment.splitLines(render(content, options));
+        return { length: all.length, lines: (start, end) => all.slice(start, end) };
+    };
+}
 /** A heavy line for the thumb on a light line for the track. */
 export const SCROLLBAR = {
     thumb: { glyph: "┃", style: "scrollbar.thumb" },
@@ -47,30 +67,26 @@ const NO_SCROLLBAR = {
     track: { glyph: "", style: NULL_STYLE },
 };
 export class Viewport {
-    /**
-     * What the viewport shows. Replace it to show new content from the same
-     * scroll position — a view rebuilt every frame keeps one `Viewport`.
-     */
-    content;
     rows;
     scrollbar;
-    _offset = 0;
-    // Nothing rendered, nothing shown: no move can take until the first render.
-    _extent = { rows: 0, lines: 0 };
-    _moves = [];
-    // No range followed yet: NaN equals nothing, so the first `follow` moves.
-    _followed = { start: NaN, end: NaN, rows: NaN };
-    constructor(content, options = {}) {
-        this.content = content;
+    _scroll = new State({
+        offset: 0,
+        // Nothing rendered, nothing shown: no move can take until the first render.
+        extent: { rows: 0, lines: 0 },
+        // No range followed yet: NaN equals nothing, so the first range followed moves.
+        followed: { start: NaN, end: NaN, rows: NaN },
+    });
+    _moves = new ListState();
+    constructor(options = {}) {
         this.rows = options.rows;
         this.scrollbar = options.scrollbar ?? NO_SCROLLBAR;
     }
     /**
-     * The first content line the last render showed. A move requested since is
-     * not reflected until the next render resolves it.
+     * The first content line the last frame showed. A move requested since is
+     * not reflected until the next frame resolves it.
      */
     get offset() {
-        return this._offset;
+        return this._scroll.get().offset;
     }
     /** Scroll so `line` is the first line shown. */
     scrollTo(line) {
@@ -82,12 +98,13 @@ export class Viewport {
     }
     /**
      * Whether `scrollBy(lines)` would move the viewport from where the moves
-     * queued so far leave it, against the rows and length the last render
+     * queued so far leave it, against the rows and length the last frame
      * found.
      */
     canScrollBy(lines) {
-        const offset = this.resolve(this._extent);
-        return clampOffset(offset + lines, this._extent) !== offset;
+        const { scroll, moves } = this.asked();
+        const offset = resolve(scroll.offset, moves, scroll.extent);
+        return clampOffset(offset + lines, scroll.extent) !== offset;
     }
     /**
      * Scroll the least distance that shows lines `start` up to but not
@@ -96,23 +113,42 @@ export class Viewport {
      * the viewport shows its first line at the top.
      */
     ensureVisible(start, end) {
-        this._moves.push((offset, { rows }) => Math.min(start, Math.max(offset, end - rows)));
+        this._moves.push(bringIntoView({ start, end }));
+    }
+    /**
+     * `content` shown through this viewport from its scroll position. What it
+     * draws is anchored to this viewport, so the wheel finds it.
+     *
+     * `follow` is the lines of `content` to keep in view — a selection's — and
+     * is brought into view with `ensureVisible` when it differs from the range
+     * the last frame followed: when the selection moves, not on every frame,
+     * which would undo on its very render each scroll the mouse wheel queues. A
+     * followed range the last frame showed whole stays shown when the row count
+     * changes: the same lines can fall off the bottom of a viewport that got
+     * shorter. One the wheel had scrolled away from stays away. Absent, the
+     * range last followed stands.
+     *
+     * [LAW:effects-at-boundaries] What a frame drawing it resolves becomes the
+     * viewport's once that frame has been drawn whole, so it may be built and
+     * drawn inside a render — `ListView` draws its items to learn their lines
+     * and shows them this way.
+     */
+    showing(content, follow) {
+        return {
+            render: (options) => this.draw(content, drawnWhole(content), follow, options),
+            measure: (options) => this.measureOf(content, options),
+        };
     }
     /**
-     * `ensureVisible(start, end)`, when the range differs from the one the last
-     * `follow` named. A view rebuilt every frame calls this in every frame with
-     * its selection's lines, and the selection is brought into view when it
-     * moves — not on every frame, which would undo on its very render each
-     * scroll the mouse wheel queues. A followed range the last render showed
-     * whole stays shown when the row count changes: the same lines can fall off
-     * the bottom of a viewport that got shorter. One the wheel had scrolled
-     * away from stays away.
+     * `content` shown through this viewport as `showing` shows a renderable,
+     * drawing only the lines the frame shows: a frame costs the rows in view,
+     * not the content's whole length.
      */
-    follow(start, end) {
-        if (start === this._followed.start && end === this._followed.end)
-            return;
-        this._followed = { start, end, rows: NaN };
-        this.ensureVisible(start, end);
+    showingLines(content, follow) {
+        return {
+            render: (options) => this.draw(content, (o) => content.layout(o), follow, options),
+            measure: (options) => this.measureOf(content, options),
+        };
     }
     /**
      * The width its content renders at, out of `width`: what the scrollbar's
@@ -125,26 +161,48 @@ export class Viewport {
     get gutter() {
         return gutterWidth(this.scrollbar);
     }
-    *render(rawOptions) {
-        const { height, ...options } = withBoundedWidth(rawOptions, this);
+    /** The scroll, and the moves queued against it, as they stand. */
+    asked() {
+        return { scroll: this._scroll.get(), moves: this._moves.get() };
+    }
+    /**
+     * The offset `settled` resolves, with the scroll it leaves kept once the frame
+     * is drawn and the `resolved` moves gone from the queue.
+     * [LAW:effects-at-boundaries] Kept once the frame is drawn, never while it is.
+     * The resolved moves leave by identity, not by count: another frame drawing
+     * this viewport in the same pass may already have taken them, and a move
+     * queued since stays.
+     */
+    keep(settled, resolved) {
+        // Taken now: the queue is appended to in place, so `resolved` grows with it.
+        const taken = new Set(resolved);
+        afterPass(() => {
+            this._scroll.set(settled.scroll);
+            this._moves.set(this._moves.get().filter((move) => !taken.has(move)));
+        });
+        return settled.offset;
+    }
+    /** `content`, laid out by `layout`, drawn from the scroll and the moves queued against it, with `follow` followed. */
+    *draw(content, layout, follow, rawOptions) {
+        const { height, ...options } = withBoundedWidth(rawOptions, { measure: (o) => this.measureOf(content, o) });
         const gutter = this.gutter;
         const contentWidth = this.contentWidth(options.maxWidth);
-        const lines = Segment.splitLines(this.content.render({ ...options, maxWidth: contentWidth }));
-        const extent = { rows: viewRows(height, this.rows, lines.length), lines: lines.length };
-        const followed = this._followed;
-        const wasShown = followed.start >= this._offset && followed.end <= this._offset + this._extent.rows;
-        this._extent = extent;
-        if (!Number.isNaN(followed.rows) && followed.rows !== extent.rows && wasShown) {
-            this.ensureVisible(followed.start, followed.end);
-        }
-        if (!Number.isNaN(followed.start))
-            this._followed = { ...followed, rows: extent.rows };
-        this._offset = this.resolve(extent);
-        this._moves = [];
-        const shown = fitHeight(lines.slice(this._offset, this._offset + extent.rows), { rows: extent.rows, exact: true });
-        // [LAW:no-ambient-temporal-coupling] The thumb is drawn from the offset
-        // this render just resolved, not from `offset` as it stood before it.
-        const thumb = thumbRows(extent, this._offset);
+        const lines = layout({ ...options, maxWidth: contentWidth });
+        const asked = this.asked();
+        const { scroll, moves } = follow === undefined ? asked : following(asked, follow);
+        // [LAW:no-ambient-temporal-coupling] Content handed no column is held, not
+        // drawn, so this render learns its budget but not the content's length. It
+        // keeps nothing: the offset, the followed range and the queued moves wait
+        // for a frame that draws, and this one draws the scrollbar against the
+        // length the last one found.
+        const held = drawsNothing({ maxWidth: contentWidth });
+        const length = held ? scroll.extent.lines : lines.length;
+        const extent = { rows: viewRows(height, this.rows, length), lines: length };
+        const offset = held ? clampOffset(scroll.offset, extent) : this.keep(settle(scroll, moves, extent), asked.moves);
+        const shown = fitHeight(lines.lines(offset, offset + extent.rows), { rows: extent.rows, exact: true });
+        // The thumb is drawn from the offset this render resolved, not from the
+        // offset the last frame kept.
+        const thumb = thumbRows(extent, offset);
         // The content's cells and the gutter's drawn cells sum to the offer: a
         // gutter wider than the whole offer is drawn cropped to it.
         const drawn = Math.min(gutter, options.maxWidth);
@@ -168,26 +226,54 @@ export class Viewport {
             yield Segment.line();
         }
     }
-    /**
-     * [LAW:one-source-of-truth] Where the queued moves leave the offset against
-     * `extent`: what a render commits, and what `canScrollBy` asks from.
-     * [LAW:dataflow-not-control-flow] The offset is re-clamped with or without
-     * queued moves: content that shrank since the last render pulls it back.
-     */
-    resolve(extent) {
-        return this._moves.reduce((offset, move) => clampOffset(move(offset, extent), extent), clampOffset(this._offset, extent));
-    }
-    measure(rawOptions) {
+    measureOf(content, rawOptions) {
         // Its width is its content's and its gutter's. `withCellWidth` and not
         // `withBoundedWidth`: the bounded parse asks this very method for the
         // natural width.
         const options = withCellWidth(rawOptions);
         const gutter = this.gutter;
         const inner = { ...options, maxWidth: this.contentWidth(options.maxWidth) };
-        const content = Measurement.get(inner, this.content);
-        return new Measurement(content.minimum + gutter, content.maximum + gutter).withMaximum(options.maxWidth);
+        const measured = Measurement.get(inner, content);
+        return new Measurement(measured.minimum + gutter, measured.maximum + gutter).withMaximum(options.maxWidth);
     }
 }
+/** The move that scrolls the least distance showing `range`. */
+const bringIntoView = ({ start, end }) => (offset, { rows }) => Math.min(start, Math.max(offset, end - rows));
+/**
+ * `asked` with `range` followed: one that differs from the range last followed
+ * becomes the followed range, and a move brings it into view.
+ */
+function following(asked, range) {
+    const { followed } = asked.scroll;
+    if (range.start === followed.start && range.end === followed.end)
+        return asked;
+    return {
+        scroll: { ...asked.scroll, followed: { start: range.start, end: range.end, rows: NaN } },
+        moves: [...asked.moves, bringIntoView(range)],
+    };
+}
+/**
+ * Where a frame that drew the content against `extent` leaves the scroll: a
+ * followed range that was in view is kept in view if the rows changed, and the
+ * moves resolve into the offset.
+ */
+function settle(scroll, moves, extent) {
+    const { followed, offset } = scroll;
+    const wasShown = followed.start >= offset && followed.end <= offset + scroll.extent.rows;
+    const keepShown = !Number.isNaN(followed.rows) && followed.rows !== extent.rows && wasShown ? [bringIntoView(followed)] : [];
+    const settled = resolve(offset, [...moves, ...keepShown], extent);
+    const rows = Number.isNaN(followed.start) ? followed.rows : extent.rows;
+    return { scroll: { offset: settled, extent, followed: { ...followed, rows } }, offset: settled };
+}
+/**
+ * [LAW:one-source-of-truth] Where `moves` leave `offset` against `extent`: what
+ * a frame keeps, and what `canScrollBy` asks from.
+ * [LAW:dataflow-not-control-flow] The offset is re-clamped with or without
+ * queued moves: content that shrank since the last frame pulls it back.
+ */
+function resolve(offset, moves, extent) {
+    return moves.reduce((at, move) => clampOffset(move(at, extent), extent), clampOffset(offset, extent));
+}
 /**
  * One viewport per thing a pane shows, named by a key. The same viewport comes
  * back while the key holds, so its scroll position does too; a new key gets a
@@ -210,11 +296,9 @@ export class ViewportPerKey {
         return this.held.viewport;
     }
     fresh() {
-        // Empty until a view hands it content: the content is built where the frame is.
-        return new Viewport(EMPTY, this.options);
+        return new Viewport(this.options);
     }
 }
-const EMPTY = { *render() { } };
 const scrollbarGlyphs = ({ thumb, track }) => thumb.glyph + track.glyph;
 /** `scrollbar` in its own styles, drawn in ASCII. */
 function asciiScrollbar({ thumb, track }) {

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

@@ -4,13 +4,25 @@
  *
  * A host that builds its cells in templates — cc-candybar's statusline, say —
  * evaluates each template once per redraw and owns the clock that says when
- * that is. So the time is a capability the registration takes, the way
- * `richTextFuncs(drawnAt)` takes the drawn depth: `frameTime()` is read once
- * per call, when the template is evaluated, and nothing here reads a clock.
+ * that is. So the frame is a capability the registration takes, the way
+ * `richTextFuncs(drawnAt)` takes the drawn depth: `frame()` is read once per
+ * call, when the template is evaluated, and nothing here reads a clock.
  * [LAW:no-ambient-temporal-coupling] A host hands in the same `t` and gets
  * the same fragment back; a host that redraws once a second or sixty times
  * a second registers the same functions.
  *
+ * Every function draws its animation on a `Timeline` (`../core/timeline.ts`)
+ * the host hands in as a getter beside the time — playing from host time 0
+ * at rate 1, the host's own clock, when it hands none — so a daemon pauses,
+ * reverses, scrubs or speeds one session's animations by changing one value
+ * it holds, with nothing recompiled, as `paletteFuncs` follows a theme
+ * through its getter. The timeline is a map the drawing runs through, not a
+ * 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
+ * and the reader's preference for motion are read, for every function.
+ *
  * `frames <seconds> <frame> <seconds> <frame> …` is a `FrameSequence`
  * (`renderables/frames.ts`) in a template: the frame in progress at the
  * moment, as a fragment at the width of the widest. Its frames arrive as
@@ -25,13 +37,70 @@
  * 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]
+ *
+ * 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>
+ * <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
+ * 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
+ * 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
+ * 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.
  */
 import type { FuncMap } from "@promptctl/go-template-js";
+import type { RenderOptions } from "../core/protocol.js";
+import { Timeline } from "../core/timeline.js";
+/** What a registration is drawn on, beside the frame each evaluation is handed. */
+export interface AnimationFuncsOptions {
+    /** 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 —
+ * `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. 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"> {
+    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` and `stepped`, each drawn for the moment `frameTime`
- * reports when the template is evaluated: seconds on the host's own
- * timeline, from whatever zero it counts from. The functions exist whatever
- * `frameTime` returns, so a template compiles once and is evaluated at every
- * moment the host draws.
+ * 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.
+ * 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(frameTime: () => number): FuncMap;
+export declare function animationFuncs(frame: () => TemplateFrame, options?: AnimationFuncsOptions): FuncMap;

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

@@ -4,13 +4,25 @@
  *
  * A host that builds its cells in templates — cc-candybar's statusline, say —
  * evaluates each template once per redraw and owns the clock that says when
- * that is. So the time is a capability the registration takes, the way
- * `richTextFuncs(drawnAt)` takes the drawn depth: `frameTime()` is read once
- * per call, when the template is evaluated, and nothing here reads a clock.
+ * that is. So the frame is a capability the registration takes, the way
+ * `richTextFuncs(drawnAt)` takes the drawn depth: `frame()` is read once per
+ * call, when the template is evaluated, and nothing here reads a clock.
  * [LAW:no-ambient-temporal-coupling] A host hands in the same `t` and gets
  * the same fragment back; a host that redraws once a second or sixty times
  * a second registers the same functions.
  *
+ * Every function draws its animation on a `Timeline` (`../core/timeline.ts`)
+ * the host hands in as a getter beside the time — playing from host time 0
+ * at rate 1, the host's own clock, when it hands none — so a daemon pauses,
+ * reverses, scrubs or speeds one session's animations by changing one value
+ * it holds, with nothing recompiled, as `paletteFuncs` follows a theme
+ * through its getter. The timeline is a map the drawing runs through, not a
+ * 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
+ * and the reader's preference for motion are read, for every function.
+ *
  * `frames <seconds> <frame> <seconds> <frame> …` is a `FrameSequence`
  * (`renderables/frames.ts`) in a template: the frame in progress at the
  * moment, as a fragment at the width of the widest. Its frames arrive as
@@ -25,11 +37,49 @@
  * 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]
+ *
+ * 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>
+ * <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
+ * 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
+ * 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
+ * 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.
  */
-import { beat } from "../core/easing.js";
-import { FrameSequence } from "../renderables/frames.js";
+import { Animation, frameTimeOf, holdOf, shownAt } from "../core/animation.js";
+import { Phase, beat, finiteTime, parseEase } from "../core/easing.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 { 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 };
+}
+/** The host's own clock as a timeline: host time 0 at animation time 0, at rate 1. */
+const HOST_CLOCK = Timeline.play(0);
 /**
  * The `(seconds, value)` pairs a call spells, each value read through
  * `value`. The gate has typed every even slot as a float and every odd one
@@ -54,17 +104,59 @@ function pairs(what, tail, value) {
     return paired;
 }
 /**
- * Register `frames` and `stepped`, each drawn for the moment `frameTime`
- * reports when the template is evaluated: seconds on the host's own
- * timeline, from whatever zero it counts from. The functions exist whatever
- * `frameTime` returns, so a template compiles once and is evaluated at every
- * moment the host draws.
+ * Every glyph effect in the catalogue by the name a template spells it
+ * with, a transition as the effect it runs. [LAW:types-are-the-program]
+ * Keyed by both name types, so a name added to the catalogue does not
+ * compile until it is spelled here too.
+ */
+const GLYPH_EFFECTS = {
+    ...GLYPH_EFFECT_CATALOGUE.loops,
+    typewriter: (element) => GLYPH_EFFECT_CATALOGUE.transitions.typewriter(element).effect,
+    scramble: (element) => GLYPH_EFFECT_CATALOGUE.transitions.scramble(element).effect,
+    backspace: (element) => GLYPH_EFFECT_CATALOGUE.transitions.backspace(element).effect,
+    scrambleOut: (element) => GLYPH_EFFECT_CATALOGUE.transitions.scrambleOut(element).effect,
+};
+/**
+ * The gate a spelled glyph effect crosses: the name in, the effect's maker
+ * out, or a refusal naming every legal one. [LAW:parse-dont-validate]
+ */
+function glyphEffect(name) {
+    if (!Object.hasOwn(GLYPH_EFFECTS, name)) {
+        throw new RangeError(`unknown glyph effect ${JSON.stringify(name)}; expected one of ${Object.keys(GLYPH_EFFECTS).map((n) => JSON.stringify(n)).join(", ")}`);
+    }
+    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.
+ * 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(frameTime) {
+export function animationFuncs(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;
+    };
+    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 }));
-            return new FrameSequence(frames).text(frameTime());
+            const at = frame();
+            return textFrameAt(...drawing("frames", new FrameSequence(frames), at), at);
         }),
         argTypes: ["float", "liftable"],
         arity: { kind: "alternating", minimum: 2 },
@@ -73,11 +165,37 @@ export function animationFuncs(frameTime) {
     const steppedFunc = {
         fn: ((...tail) => {
             const steps = pairs("color", tail, (v) => asColor(v, "stepped"));
-            return steps[beat(steps.map((step) => step.seconds)).at(frameTime())].value.hex;
+            return steps[now("stepped", beat(steps.map((step) => step.seconds)))].value.hex;
         }),
         argTypes: ["float", "string"],
         arity: { kind: "alternating", minimum: 2 },
         returnType: "string",
     };
-    return { frames: framesFunc, stepped: steppedFunc };
+    const tweenFunc = {
+        fn: ((seconds, ease, start, from, to) => now("tween", startedAt(start, tween(from, to, { seconds, ease: parseEase(ease) })))),
+        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))))),
+        argTypes: ["float", "float"],
+        arity: { kind: "exact" },
+        returnType: "float",
+    };
+    const glyphsFunc = {
+        fn: ((name, start, child) => {
+            const make = glyphEffect(name);
+            const fragment = asFragment(child);
+            // One text, one seed: the element is named by what it says.
+            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);
+        }),
+        argTypes: ["string", "float", "liftable"],
+        arity: { kind: "exact" },
+        returnType: "T",
+    };
+    return { frames: framesFunc, stepped: steppedFunc, tween: tweenFunc, loop: loopFunc, glyphs: glyphsFunc };
 }

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

@@ -14,10 +14,10 @@
  * - `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(frameTime)` — `frames` and `stepped`, a fragment and a
- *   colour drawn for a moment. It is the only registration that knows the
- *   template is evaluated at a time, and the time is the host's to hand in
- *   (`./animation-funcs.ts`).
+ * - `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`).
  *
  * `createRichTextEngine()` wires up `richTextFuncs()` only — it cannot supply a
  * palette. Consumers that name theme colours call `paletteFuncs(getPalette)`
@@ -43,7 +43,7 @@ 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 } from "./animation-funcs.js";
+export { animationFuncs, templateFrame, type AnimationFuncsOptions, 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