@promptctl/rich-js 0.24.1 → 0.25.0

package/dist/renderables/viewport.d.ts

@@ -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
@@ -24,6 +28,13 @@
  * 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
@@ -33,7 +44,25 @@
  */
 import { Segment } from "../core/segment.js";
 import type { Style } from "../core/style.js";
-import type { Composite, Measurable, Renderable, RenderOptions, Scrollable } from "../core/protocol.js";
+import type { Measurable, Renderable, RenderOptions, Scrollable } from "../core/protocol.js";
+/** Lines `start` up to but not including `end` of the content. */
+interface Range {
+    readonly start: number;
+    readonly end: number;
+}
+/**
+ * Content a viewport shows by the line: laid out at a width, it says how many
+ * lines it is and draws only the ones asked for. What a view too long to draw
+ * whole every frame — a textarea's rows — is shown as (`showingLines`).
+ */
+export interface Lines extends Measurable {
+    layout(options: RenderOptions): LaidLines;
+}
+/** Content laid out at one width: its length, and its lines `start` up to but not including `end`. */
+export interface LaidLines {
+    readonly length: number;
+    lines(start: number, end: number): Segment[][];
+}
 /** How one part of a scrollbar draws each row it covers. */
 export interface ScrollbarPart {
     readonly glyph: string;
@@ -60,22 +89,15 @@ export interface ViewportOptions {
     /** A scrollbar down the right edge. Absent, the content has the full width. */
     scrollbar?: Scrollbar;
 }
-export declare class Viewport implements Renderable, Measurable, Scrollable, Composite {
-    /**
-     * What the viewport shows. Replace it to show new content from the same
-     * scroll position — a view rebuilt every frame keeps one `Viewport`.
-     */
-    content: Renderable;
+export declare class Viewport implements Scrollable {
     readonly rows: number | undefined;
     readonly scrollbar: Scrollbar;
-    private _offset;
-    private _extent;
-    private _moves;
-    private _followed;
-    constructor(content: Renderable, options?: ViewportOptions);
+    private readonly _scroll;
+    private readonly _moves;
+    constructor(options?: ViewportOptions);
     /**
-     * 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(): number;
     /** Scroll so `line` is the first line shown. */
@@ -84,7 +106,7 @@ export declare class Viewport implements Renderable, Measurable, Scrollable, Com
     scrollBy(lines: number): void;
     /**
      * 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: number): boolean;
@@ -96,16 +118,30 @@ export declare class Viewport implements Renderable, Measurable, Scrollable, Com
      */
     ensureVisible(start: number, end: number): void;
     /**
-     * `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 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: Renderable, follow?: Range): Renderable & Measurable;
+    /**
+     * `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: number, end: number): void;
+    showingLines(content: Lines, follow?: Range): Renderable & Measurable;
     /**
      * The width its content renders at, out of `width`: what the scrollbar's
      * gutter leaves. Lines handed to `ensureVisible` are lines at this width.
@@ -113,26 +149,20 @@ export declare class Viewport implements Renderable, Measurable, Scrollable, Com
     contentWidth(width: number): number;
     /** The cells the scrollbar's gutter takes beside the content. */
     get gutter(): number;
-    contents(): Iterable<Renderable>;
-    render(rawOptions: RenderOptions): Iterable<Segment>;
-    /**
-     * What a render that drew the content found, made the viewport's: `extent`
-     * is the rows and length the next move is clamped against, a followed range
-     * that was in view is kept in view if the rows changed, and the queued moves
-     * resolve into the offset this returns.
-     */
-    private commit;
+    /** The scroll, and the moves queued against it, as they stand. */
+    private asked;
     /**
-     * [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.
+     * 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.
      */
-    private resolve;
-    measure(rawOptions: RenderOptions): {
-        minimum: number;
-        maximum: number;
-    };
+    private keep;
+    /** `content`, laid out by `layout`, drawn from the scroll and the moves queued against it, with `follow` followed. */
+    private draw;
+    private measureOf;
 }
 /**
  * One viewport per thing a pane shows, named by a key. The same viewport comes
@@ -150,3 +180,4 @@ export declare class ViewportPerKey {
     of(key: string): Viewport;
     private fresh;
 }
+export {};

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
@@ -24,6 +28,13 @@
  * 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
@@ -36,7 +47,15 @@ import { Measurement } from "../core/measure.js";
 import { cellCount, cellLen } from "../core/cells.js";
 import { NULL_STYLE } from "../core/style.js";
 import { drawable, drawsNothing, fitHeight, getStyle, regionRows, withBoundedWidth, withCellWidth, } from "../core/protocol.js";
-import { render } 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" },
@@ -48,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) {
@@ -83,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
@@ -97,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 }));
     }
     /**
-     * `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 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.
      */
-    follow(start, end) {
-        if (start === this._followed.start && end === this._followed.end)
-            return;
-        this._followed = { start, end, rows: NaN };
-        this.ensureVisible(start, end);
+    showing(content, follow) {
+        return {
+            render: (options) => this.draw(content, drawnWhole(content), follow, options),
+            measure: (options) => this.measureOf(content, options),
+        };
+    }
+    /**
+     * `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.
+     */
+    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
@@ -126,26 +161,47 @@ export class Viewport {
     get gutter() {
         return gutterWidth(this.scrollbar);
     }
-    *contents() {
-        yield this.content;
+    /** The scroll, and the moves queued against it, as they stand. */
+    asked() {
+        return { scroll: this._scroll.get(), moves: this._moves.get() };
     }
-    *render(rawOptions) {
-        const { height, ...options } = withBoundedWidth(rawOptions, this);
+    /**
+     * 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(render(this.content, { ...options, maxWidth: contentWidth }));
+        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
-        // commits nothing: the offset, the followed range and the queued moves wait
-        // for a render that draws, and this one draws the scrollbar against the
+        // 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 ? this._extent.lines : lines.length;
+        const length = held ? scroll.extent.lines : lines.length;
         const extent = { rows: viewRows(height, this.rows, length), lines: length };
-        const offset = held ? clampOffset(this._offset, extent) : this.commit(extent);
-        const shown = fitHeight(lines.slice(offset, offset + extent.rows), { rows: extent.rows, exact: true });
-        // The thumb is drawn from the offset this render resolved, not from
-        // `offset` as it stood before it.
+        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.
@@ -170,45 +226,54 @@ export class Viewport {
             yield Segment.line();
         }
     }
-    /**
-     * What a render that drew the content found, made the viewport's: `extent`
-     * is the rows and length the next move is clamped against, a followed range
-     * that was in view is kept in view if the rows changed, and the queued moves
-     * resolve into the offset this returns.
-     */
-    commit(extent) {
-        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 = [];
-        return this._offset;
-    }
-    /**
-     * [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
@@ -231,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;