@promptctl/rich-js 0.24.1 → 0.25.0

package/dist/core/timeline.js

@@ -32,11 +32,25 @@
  * why it is a search and not the ulp walk a sum on one clock takes. A value
  * moving at the mapped time changes at the host time itself.
  *
+ * A stagger — a Group's children pulsing in sequence, a light walking down
+ * a Table's rows — is the same map once per child: `stagger` runs each
+ * child's animation on a timeline playing from its index times the delay,
+ * and the group changes when the soonest child does, each child's answer
+ * carried onto the group's clock by `run`. Before its turn a child is asked
+ * for a time before 0, which is its own business: a loop is shifted in
+ * phase. Tree, Table, Group and Layout take the children's frames as they
+ * take any renderables, through `Animation.map`, so none of them knows a
+ * stagger exists. [LAW:composability] A lifecycle is not staggered here: it
+ * carries its turn as `entered`, on the host's clock its `leave` and `gone`
+ * take, so moving it onto a shifted clock would lose them
+ * ([LAW:one-source-of-truth] for when it arrives).
+ *
  * [LAW:no-ambient-temporal-coupling] Nothing here reads a clock. The host
  * time is an argument everywhere, and a timeline is built from one the host
  * hands in, so the same host time maps to the same animation time at one
  * sample a second or sixty.
  */
+import { Animation } from "./animation.js";
 import { firstReaching } from "./easing.js";
 /** Throws, naming `what`, unless `seconds` is a finite number of seconds. */
 function finiteSeconds(what, seconds) {
@@ -81,7 +95,7 @@ function played(animation, { origin, time, rate }) {
         const sum = origin + (edge - time) / rate;
         return Number.isFinite(sum) ? firstReaching(sum, (host) => past(mapped(host), edge)) : sum;
     };
-    return {
+    return Animation.of({
         at: (host) => animation.at(mapped(hostTime(host))),
         nextChange(host) {
             const h = hostTime(host);
@@ -95,7 +109,8 @@ function played(animation, { origin, time, rate }) {
             const edge = behind(t);
             return edge === t ? h : Math.min(h, hostOf(edge));
         },
-    };
+        reduced: () => played(animation.reduced(), { playing: true, origin, time, rate }),
+    });
 }
 export const Timeline = {
     /** Playing from host time `origin`, at which the animation time is 0, at `rate` animation seconds a host second. */
@@ -128,17 +143,38 @@ export const Timeline = {
      * host time to, changing at the host moment the mapped time reaches the
      * animation's own answer — backwards, when it drops under where the value
      * began. Paused, the value never changes and never did. The value is the
-     * animation's own, on no clock: what a drawn value's cells say about when
-     * they change is stamped by whoever draws it at a host time
-     * (`../renderables/frames.ts`, `frameAt`), never carried in from here.
+     * animation's own, on no clock: placed, it is stamped at the frame's time
+     * (`placedRender`, `./animation.ts`) with this animation's answers, so a
+     * value's contents follow the frame's clock and not this map.
+     * Reduced, it is the animation reduced on the same timeline: what shows
+     * still follows the timeline, and only the motion is gone.
      */
     run(timeline, animation) {
         if (timeline.playing)
             return played(animation, timeline);
-        return {
+        return Animation.of({
             at: (host) => animation.at(Timeline.at(timeline, host)),
             nextChange: (host) => (hostTime(host), Number.POSITIVE_INFINITY),
             lastChange: (host) => (hostTime(host), Number.NEGATIVE_INFINITY),
-        };
+            reduced: () => Timeline.run(timeline, animation.reduced()),
+        });
+    },
+    /**
+     * Every one of `animations` at once, each on a timeline playing from its
+     * index times `delay` seconds after the earliest, their values in order, on
+     * a clock of the stagger's own from 0. It changes when the soonest of them
+     * does, on that clock (`Animation.all` of `run`s). A delay of 0 starts them
+     * together and a negative one starts the last at 0 and the first last.
+     * Reduced, the offsets are the cascade's choreography, which is motion: every
+     * child reduced at once, so from 0 everyone has arrived.
+     */
+    stagger(animations, delay) {
+        finiteSeconds("Timeline.stagger delay", delay);
+        const span = finiteSeconds("Timeline.stagger delay times the last index", Math.max(0, animations.length - 1) * delay);
+        // [LAW:dataflow-not-control-flow] Whichever way the cascade runs, every
+        // origin is shifted by the lowest of them, so the earliest child plays from 0.
+        const earliest = Math.min(0, span);
+        const cascade = Animation.all(animations.map((animation, i) => Timeline.run(Timeline.play(i * delay - earliest), animation)));
+        return Animation.of({ ...cascade, reduced: () => Animation.all(animations.map((animation) => animation.reduced())) });
     },
 };

package/dist/core/tween.d.ts

@@ -30,7 +30,7 @@
  * OKLCH, and a colour tween is a two-stop ramp over its seconds, not a
  * second blender. [LAW:one-source-of-truth]
  *
- * Tier 2 of `src/core/`: `./easing.ts` and `./animation.ts`, nothing else.
+ * Tier 6 of `src/core/`: `./easing.ts` and `./animation.ts`, nothing else.
  * [LAW:one-way-deps]
  */
 import { Animation } from "./animation.js";

package/dist/core/tween.js

@@ -30,7 +30,7 @@
  * OKLCH, and a colour tween is a two-stop ramp over its seconds, not a
  * second blender. [LAW:one-source-of-truth]
  *
- * Tier 2 of `src/core/`: `./easing.ts` and `./animation.ts`, nothing else.
+ * Tier 6 of `src/core/`: `./easing.ts` and `./animation.ts`, nothing else.
  * [LAW:one-way-deps]
  */
 import { Animation } from "./animation.js";
@@ -55,7 +55,7 @@ export function tween(from, to, timing) {
     const phase = Phase.once(0, seconds);
     if (from === to)
         return Animation.constant(from);
-    return {
+    return Animation.of({
         at(t) {
             const p = ease(phase(t));
             return (1 - p) * from + p * to;
@@ -65,5 +65,7 @@ export function tween(from, to, timing) {
         // `seconds`, or always was before it began.
         nextChange: (t) => (t < 0 ? 0 : t < seconds ? t : Number.POSITIVE_INFINITY),
         lastChange: (t) => (t < 0 ? Number.NEGATIVE_INFINITY : t < seconds ? t : seconds),
-    };
+        // A one-shot, reduced, cuts from where it starts to where it arrives.
+        reduced: () => Animation.cut(from, to),
+    });
 }

package/dist/core/view.d.ts

@@ -0,0 +1,92 @@
+/**
+ * View — what a host draws, and the frame it draws from it at a host time on
+ * its timeline: the lines, and what they say about when they change.
+ *
+ * A host — a `Live`, an `App` — reads its clock once a frame and draws its
+ * view for that moment. The view is a renderable, drawn as it is now (a
+ * table mutated in place between frames), at the time the host's `Timeline`
+ * (`./timeline.ts`) maps its clock to, written on the frame
+ * (`RenderOptions.frame`): every animation placed anywhere inside it draws
+ * at that time and stamps its cells with when it changes, on that clock
+ * (`placedRender`, `./animation.ts`). A program may hand a function for one
+ * instead, asked each frame so a view of its state is built from the state
+ * as it is then. It is handed no time, and `hostView` makes it the
+ * renderable it stands for, so a host holds one shape of view and draws it
+ * one way. [LAW:one-type-per-behavior]
+ *
+ * So a view says when it changes only through what it draws: what moves in
+ * it is an animation placed there — `Animation.continuous` for a value
+ * computed from the time — and never a time handed to the program.
+ * [LAW:one-source-of-truth] Pausing, reversing, scrubbing and speeding up
+ * what a host shows are changes to one value the host holds and not to
+ * anything it draws. What the drawn frame says about when it changes is on
+ * the timeline's clock, and `drawView` carries it back onto the host's by
+ * running the frame through the same timeline: the frame is a sample held
+ * for the intersection of its cells' holds (`Segment.lastChange`,
+ * `Segment.nextChange`) and the holds it was told that no cell carries
+ * (`RenderOptions.onHold`), and `Timeline.run` is the one place a hold is
+ * mapped onto host time, forwards, backwards or paused.
+ *
+ * What a host does with that is its own policy, and it reads it off the
+ * `DrawnView`. A view may also change without saying so — it reads state
+ * the host cannot see — so a host that polls for such a change, a `Live`'s
+ * auto-refresh, polls every frame.
+ *
+ * Tier 7 of `src/core/`: `./animation.ts`'s `Animation`, `./timeline.ts`,
+ * `./segment.ts`, `./protocol.ts` and `./style.ts`'s `Hold`, nothing else.
+ * [LAW:one-way-deps]
+ */
+import { type FrameHost, type Renderable, type RenderOptions } from "./protocol.js";
+import { Segment } from "./segment.js";
+import { Timeline } from "./timeline.js";
+/**
+ * What a host draws: a renderable — an animation of renderables among them,
+ * or anything holding one — or a function asked for one each frame.
+ */
+export type View = Renderable | (() => Renderable);
+/** `view` as the renderable a host holds: a function is asked each time it is drawn. */
+export declare function hostView(view: View): Renderable;
+/**
+ * A host's time, its clock read once: `now` on that clock; `epoch`, the
+ * moment on it the host began; and `timeline`, the map every view is drawn
+ * through. Handed none, a host's timeline starts as `Timeline.play(epoch)`,
+ * so a frame is drawn for the seconds since `epoch` until the timeline is
+ * paused, sought, re-rated or replaced.
+ */
+export interface HostTime {
+    readonly now: number;
+    readonly epoch: number;
+    readonly timeline: Timeline;
+}
+/**
+ * The time a frame drawn at `time` is drawn for, on the clock its cells are
+ * stamped on: the time the timeline maps `now` to. [LAW:single-enforcer]
+ * `drawView` draws at it and hands it to the frame as
+ * `RenderOptions.frame`, and a host reads it here for anything heard between
+ * frames — a key — so a moment a widget keeps and the frame it is compared
+ * against are on one clock.
+ */
+export declare function frameTime(time: HostTime): number;
+/** What a frame drawn at host time `t` says about when it changes. */
+export interface FrameSays {
+    /** The host time the frame was drawn at. */
+    readonly t: number;
+    /** The first host moment, never before `t`, at which the frame may stop showing this: `t` while it moves, `Infinity` once it never will. */
+    readonly nextChange: number;
+}
+/** A frame drawn from a view: its lines, and what it says. */
+export interface DrawnView extends FrameSays {
+    readonly lines: Segment[][];
+}
+/** What a frame not yet drawn at host time `t` says: nothing. */
+export declare const undrawn: (t: number) => FrameSays;
+/**
+ * `view` drawn by `drawnBy` at `time` under `options`, its lines shaped by
+ * `draw` — the host's own render under those options, with its height and
+ * overflow — and when the frame changes on the host's clock: the hold its
+ * cells say, carried back through the timeline. [LAW:one-source-of-truth]
+ * `options` is the one place the frame reads the reader's preference for
+ * motion, handed on to `draw` with the frame: the time it is drawn for
+ * (`frameTime`) and `drawnBy`, the host whose time that is.
+ */
+export declare function drawView(view: Renderable, time: HostTime, drawnBy: FrameHost, options: RenderOptions, draw: (renderable: Renderable, options: RenderOptions) => Segment[][]): DrawnView;

package/dist/core/view.js

@@ -0,0 +1,83 @@
+/**
+ * View — what a host draws, and the frame it draws from it at a host time on
+ * its timeline: the lines, and what they say about when they change.
+ *
+ * A host — a `Live`, an `App` — reads its clock once a frame and draws its
+ * view for that moment. The view is a renderable, drawn as it is now (a
+ * table mutated in place between frames), at the time the host's `Timeline`
+ * (`./timeline.ts`) maps its clock to, written on the frame
+ * (`RenderOptions.frame`): every animation placed anywhere inside it draws
+ * at that time and stamps its cells with when it changes, on that clock
+ * (`placedRender`, `./animation.ts`). A program may hand a function for one
+ * instead, asked each frame so a view of its state is built from the state
+ * as it is then. It is handed no time, and `hostView` makes it the
+ * renderable it stands for, so a host holds one shape of view and draws it
+ * one way. [LAW:one-type-per-behavior]
+ *
+ * So a view says when it changes only through what it draws: what moves in
+ * it is an animation placed there — `Animation.continuous` for a value
+ * computed from the time — and never a time handed to the program.
+ * [LAW:one-source-of-truth] Pausing, reversing, scrubbing and speeding up
+ * what a host shows are changes to one value the host holds and not to
+ * anything it draws. What the drawn frame says about when it changes is on
+ * the timeline's clock, and `drawView` carries it back onto the host's by
+ * running the frame through the same timeline: the frame is a sample held
+ * for the intersection of its cells' holds (`Segment.lastChange`,
+ * `Segment.nextChange`) and the holds it was told that no cell carries
+ * (`RenderOptions.onHold`), and `Timeline.run` is the one place a hold is
+ * mapped onto host time, forwards, backwards or paused.
+ *
+ * What a host does with that is its own policy, and it reads it off the
+ * `DrawnView`. A view may also change without saying so — it reads state
+ * the host cannot see — so a host that polls for such a change, a `Live`'s
+ * auto-refresh, polls every frame.
+ *
+ * Tier 7 of `src/core/`: `./animation.ts`'s `Animation`, `./timeline.ts`,
+ * `./segment.ts`, `./protocol.ts` and `./style.ts`'s `Hold`, nothing else.
+ * [LAW:one-way-deps]
+ */
+import { render } from "./protocol.js";
+import { Segment } from "./segment.js";
+import { Timeline } from "./timeline.js";
+/** `view` as the renderable a host holds: a function is asked each time it is drawn. */
+export function hostView(view) {
+    return typeof view === "function" ? { render: (options) => render(view(), options) } : view;
+}
+/**
+ * The time a frame drawn at `time` is drawn for, on the clock its cells are
+ * stamped on: the time the timeline maps `now` to. [LAW:single-enforcer]
+ * `drawView` draws at it and hands it to the frame as
+ * `RenderOptions.frame`, and a host reads it here for anything heard between
+ * frames — a key — so a moment a widget keeps and the frame it is compared
+ * against are on one clock.
+ */
+export function frameTime(time) {
+    return Timeline.at(time.timeline, time.now);
+}
+/** What a frame not yet drawn at host time `t` says: nothing. */
+export const undrawn = (t) => ({ t, nextChange: Number.POSITIVE_INFINITY });
+/** The hold of the frame `lines` draw, told `told` besides: the intersection of its cells' holds and it. */
+const frameHold = (lines, told) => lines.reduce((hold, row) => ({ lastChange: Math.max(hold.lastChange, Segment.lastChange(row)), nextChange: Math.min(hold.nextChange, Segment.nextChange(row)) }), told);
+/**
+ * `view` drawn by `drawnBy` at `time` under `options`, its lines shaped by
+ * `draw` — the host's own render under those options, with its height and
+ * overflow — and when the frame changes on the host's clock: the hold its
+ * cells say, carried back through the timeline. [LAW:one-source-of-truth]
+ * `options` is the one place the frame reads the reader's preference for
+ * motion, handed on to `draw` with the frame: the time it is drawn for
+ * (`frameTime`) and `drawnBy`, the host whose time that is.
+ */
+export function drawView(view, time, drawnBy, options, draw) {
+    const { now: host, timeline } = time;
+    let told = { lastChange: Number.NEGATIVE_INFINITY, nextChange: Number.POSITIVE_INFINITY };
+    const onHold = (hold) => {
+        told = { lastChange: Math.max(told.lastChange, hold.lastChange), nextChange: Math.min(told.nextChange, hold.nextChange) };
+    };
+    const lines = draw(view, { ...options, frame: { time: frameTime(time), host: drawnBy }, onHold });
+    const hold = frameHold(lines, told);
+    // The frame as the sample of the view it is, on the timeline's clock; the
+    // timeline says when the host's clock leaves its hold.
+    const sample = { at: () => lines, nextChange: () => hold.nextChange, lastChange: () => hold.lastChange, reduced: () => sample };
+    const nextChange = Timeline.run(timeline, sample).nextChange(host);
+    return { t: host, lines, nextChange };
+}

package/dist/host/app.d.ts

@@ -34,8 +34,10 @@ import { type Clock, type FrameRate } from "../core/clock.js";
 import { type ConsoleOptions } from "../core/console.js";
 import { Segment } from "../core/segment.js";
 import { type Surface } from "../core/paint.js";
-import { type Renderable } from "../core/protocol.js";
+import { type FrameHost } from "../core/protocol.js";
 import type { Unsubscribe } from "../core/subscription.js";
+import { Timeline } from "../core/timeline.js";
+import { type View } from "../core/view.js";
 import { type KeyPress, type ScreenMouseEvent } from "./input.js";
 import type { TerminalHost } from "./terminal-host.js";
 /**
@@ -44,7 +46,7 @@ import type { TerminalHost } from "./terminal-host.js";
  * the program; `stopped` has handed it back for good.
  */
 export type AppPhase = "idle" | "running" | "suspended" | "stopped";
-declare const DRAW_OPTIONS: readonly ["asciiOnly", "theme", "onStyleError", "markup", "highlight", "highlighter"];
+declare const DRAW_OPTIONS: readonly ["asciiOnly", "reducedMotion", "theme", "onStyleError", "markup", "highlight", "highlighter"];
 type DrawOption = (typeof DRAW_OPTIONS)[number];
 type DrawOptions = Readonly<Pick<ConsoleOptions, DrawOption>>;
 export interface AppOptions extends DrawOptions {
@@ -52,15 +54,28 @@ export interface AppOptions extends DrawOptions {
     readonly host: TerminalHost;
     readonly surface: Surface;
     /**
-     * The app's root renderable, asked for once per frame, so a view of the
-     * app's state is drawn from the state as it is at that frame. `t` is the
-     * frame's time in seconds on the app's `clock`, which is what an effect is
-     * sampled at.
+     * What the app draws: a renderable, or a function asked for one once per
+     * frame — so a view of the app's state is drawn from the state as it is at
+     * that frame. What moves in it is an `Animation` placed there, drawn at the
+     * frame's time on the app's `timeline`, which says when it changes, so the
+     * app knows when to paint again.
      */
-    readonly view: (t: number) => Renderable;
+    readonly view: View;
     /** What the app reads the time from and ticks on. The platform's, unless given. */
     readonly clock?: Clock;
-    /** How often the app paints while something is animating. 30 frames a second, unless given. */
+    /**
+     * The map from the clock to the time the view is drawn for (`Timeline`).
+     * Playing from 0 when the host is made, at the clock's pace, unless given
+     * — so a tween in the view starts when the host is made, not when the clock
+     * began; `app.timeline` reads and replaces it.
+     */
+    readonly timeline?: Timeline;
+    /**
+     * How often the app paints while what it shows moves every moment — a
+     * frame that says it moves. A frame held until a
+     * moment is painted at that moment, whatever the rate. 30 frames a second,
+     * unless given.
+     */
     readonly rate?: FrameRate;
     /**
      * The keys that stop the app, by `keyName`, heard before any `onKey`
@@ -87,14 +102,17 @@ type WheelTurn = Extract<ScreenMouseEvent, {
 }>;
 /** A pointer event `onMouse` hears: every one but the vertical wheel, which is `onWheel`'s. */
 export type AppMouseEvent = Exclude<ScreenMouseEvent, WheelTurn>;
-export declare class App {
+export declare class App implements FrameHost {
     private readonly host;
     private readonly surface;
     private readonly view;
-    private readonly clock;
+    private readonly _clock;
+    private readonly _epoch;
+    private _timeline;
     private _rate;
-    private readonly animations;
     private ticking;
+    private said;
+    private waking;
     private readonly console;
     private _phase;
     private _frame;
@@ -110,7 +128,18 @@ export declare class App {
     private settle;
     constructor(options: AppOptions);
     get phase(): AppPhase;
-    /** How often the app paints while something is animating. */
+    /** The clock the app reads the time from: where the host time a `Timeline` operation takes is read. */
+    get clock(): Clock;
+    /** The map from the clock to the time the view is drawn for. */
+    get timeline(): Timeline;
+    /**
+     * Replace the timeline and paint the frame for the time it now maps the
+     * clock's now to, so a seek shows where it sought, once. Paused, the frame
+     * then holds: nothing drawn for a held time changes, so the app waits on
+     * nothing until the timeline plays again, and paints when asked.
+     */
+    set timeline(timeline: Timeline);
+    /** How often the app paints while what it shows moves every moment. */
     get rate(): FrameRate;
     /**
      * Set how often the app paints: an animation under way goes on at the new
@@ -119,6 +148,14 @@ export declare class App {
     set rate(rate: FrameRate);
     /** The rows on screen now, as painted: what a pointer event lands on. */
     get frame(): readonly (readonly Segment[])[];
+    /**
+     * The time a frame drawn now is drawn for (`RenderOptions.frame`): the
+     * clock's now, through the timeline. What a moment heard
+     * between frames — a key — is stamped with, so it is on the clock the
+     * frame is.
+     */
+    get frameTime(): number;
+    private _time;
     /**
      * Take the terminal, paint the first frame, and resolve when the app stops
      * — or reject with the error a frame threw or `fail` was given, the terminal
@@ -137,15 +174,6 @@ export declare class App {
      * for as long as it ran.
      */
     refresh(): void;
-    /**
-     * Paint at the app's `rate` until the returned function is called: what an
-     * effect sampled at the frame's time asks for while it moves. The app ticks
-     * while anything is animating and it holds the terminal, and stops when
-     * nothing is, so a still app paints only when asked. The animation's first
-     * frame does not wait out an interval: at one frame every two seconds, that
-     * would hold its start off screen for two.
-     */
-    animate(): Unsubscribe;
     /**
      * Hand the terminal to whatever launched the program, and take it back and
      * repaint when that resumes it. What sends the app here is the app's own —

package/dist/host/app.js

@@ -35,6 +35,8 @@ import { Console } from "../core/console.js";
 import { Segment } from "../core/segment.js";
 import { SurfacePainter } from "../core/paint.js";
 import { fitHeight, render } from "../core/protocol.js";
+import { Timeline } from "../core/timeline.js";
+import { drawView, frameTime, hostView, undrawn } from "../core/view.js";
 import { hostEnvironment } from "./host-environment.js";
 import { InputParser, keyName, parseKeyName } from "./input.js";
 // [LAW:one-source-of-truth] How a frame draws — its glyphs, the style names
@@ -43,7 +45,7 @@ import { InputParser, keyName, parseKeyName } from "./input.js";
 // console declares them. This list is both the type and what is copied: the
 // host alone decides the console's size, colours and sink, so no other
 // property of the options object reaches it, whatever the object carries.
-const DRAW_OPTIONS = ["asciiOnly", "theme", "onStyleError", "markup", "highlight", "highlighter"];
+const DRAW_OPTIONS = ["asciiOnly", "reducedMotion", "theme", "onStyleError", "markup", "highlight", "highlighter"];
 function drawOptions(options) {
     const picked = {};
     const copy = (key) => {
@@ -71,12 +73,19 @@ export class App {
     host;
     surface;
     view;
-    clock;
+    _clock;
+    // The clock moment this app began: what its default timeline plays from,
+    // and what a renderable view is drawn for the time since (`HostTime`).
+    _epoch;
+    _timeline;
     _rate;
-    // What is animating now: one token per `animate()` not yet released.
-    animations = new Set();
     // The timer painting frames, and the rate it was started at.
     ticking = null;
+    // What the frame on screen says about when it changes, on the clock.
+    // Before a frame, nothing.
+    said = undrawn(0);
+    // The one wait for the frame's `nextChange`, armed after each frame.
+    waking = null;
     // [LAW:one-source-of-truth] The host is the console's whole environment:
     // its size, its colours, where bytes go. Every frame renders with this
     // console's options and is encoded for its destination.
@@ -98,8 +107,10 @@ export class App {
         this.input = new InputParser({ key: (press) => this.key(press), mouse: (event) => this.mouse(event) }, options.host.inputChunks);
         this.surface = options.surface;
         this.painter = new SurfacePainter(options.surface, (bytes) => this.host.write(bytes));
-        this.view = options.view;
-        this.clock = options.clock ?? systemClock();
+        this.view = hostView(options.view);
+        this._clock = options.clock ?? systemClock();
+        this._epoch = this._clock.now();
+        this._timeline = options.timeline ?? Timeline.play(this._epoch);
         this._rate = options.rate ?? DEFAULT_RATE;
         this.quitKeys = new Set((options.quitKeys ?? DEFAULT_QUIT_KEYS).map(parseKeyName));
         this.console = new Console({ ...drawOptions(options), environment: hostEnvironment(options.host) });
@@ -107,7 +118,25 @@ export class App {
     get phase() {
         return this._phase;
     }
-    /** How often the app paints while something is animating. */
+    /** The clock the app reads the time from: where the host time a `Timeline` operation takes is read. */
+    get clock() {
+        return this._clock;
+    }
+    /** The map from the clock to the time the view is drawn for. */
+    get timeline() {
+        return this._timeline;
+    }
+    /**
+     * Replace the timeline and paint the frame for the time it now maps the
+     * clock's now to, so a seek shows where it sought, once. Paused, the frame
+     * then holds: nothing drawn for a held time changes, so the app waits on
+     * nothing until the timeline plays again, and paints when asked.
+     */
+    set timeline(timeline) {
+        this._timeline = timeline;
+        this.refresh();
+    }
+    /** How often the app paints while what it shows moves every moment. */
     get rate() {
         return this._rate;
     }
@@ -123,6 +152,18 @@ export class App {
     get frame() {
         return this._frame;
     }
+    /**
+     * The time a frame drawn now is drawn for (`RenderOptions.frame`): the
+     * clock's now, through the timeline. What a moment heard
+     * between frames — a key — is stamped with, so it is on the clock the
+     * frame is.
+     */
+    get frameTime() {
+        return frameTime(this._time());
+    }
+    _time() {
+        return { now: this._clock.now(), epoch: this._epoch, timeline: this._timeline };
+    }
     /**
      * Take the terminal, paint the first frame, and resolve when the app stops
      * — or reject with the error a frame threw or `fail` was given, the terminal
@@ -187,24 +228,6 @@ export class App {
                 this.paint();
         });
     }
-    /**
-     * Paint at the app's `rate` until the returned function is called: what an
-     * effect sampled at the frame's time asks for while it moves. The app ticks
-     * while anything is animating and it holds the terminal, and stops when
-     * nothing is, so a still app paints only when asked. The animation's first
-     * frame does not wait out an interval: at one frame every two seconds, that
-     * would hold its start off screen for two.
-     */
-    animate() {
-        const animation = {};
-        this.animations.add(animation);
-        this.tick();
-        this.refresh();
-        return () => {
-            this.animations.delete(animation);
-            this.tick();
-        };
-    }
     /**
      * Hand the terminal to whatever launched the program, and take it back and
      * repaint when that resumes it. What sends the app here is the app's own —
@@ -350,19 +373,27 @@ export class App {
         }
     }
     // [LAW:single-enforcer] Whether the clock is ticking, and at what rate,
-    // follows from the phase, what is animating and the rate, and is brought
-    // in line with them here alone, after every change to any — so a timer
-    // runs exactly while a running app has something animating, at the rate
-    // the app has now, and none outlives the app.
+    // and whether a wake is armed for the frame's next change, follow from the
+    // phase, the rate and what the frame on screen says, and are brought in
+    // line with them here alone, after every change to any — so a timer runs
+    // exactly while a running app shows a frame that says it moves, at the
+    // rate the app has now, a wake is armed exactly while a running app shows
+    // a frame held until a moment, and none outlives the app.
+    // [LAW:one-source-of-truth] What the frame draws is the only thing that
+    // says whether the view moves.
     tick() {
-        const wanted = this._phase === "running" && this.animations.size > 0;
+        const running = this._phase === "running";
+        const { t, nextChange } = this.said;
+        const wanted = running && nextChange === t;
         if (this.ticking !== null && (!wanted || this.ticking.rate.perSecond !== this._rate.perSecond)) {
             this.ticking.stop();
             this.ticking = null;
         }
         if (wanted && this.ticking === null) {
-            this.ticking = { rate: this._rate, stop: this.clock.every(this._rate, () => this.paint()) };
+            this.ticking = { rate: this._rate, stop: this._clock.every(this._rate, () => this.paint()) };
         }
+        this.waking?.();
+        this.waking = running && t < nextChange && nextChange < Number.POSITIVE_INFINITY ? this._clock.at(nextChange, () => this.paint()) : null;
     }
     // [LAW:no-silent-failure] A frame that throws ends the app with that
     // error: the terminal is handed back, and `run` rejects with it.
@@ -380,13 +411,16 @@ export class App {
         const options = this.console.options;
         const height = this.painter.height(options.height.rows);
         // [LAW:no-ambient-temporal-coupling] The frame owner reads the clock,
-        // once a frame; the view is handed the time as data.
-        const lines = Segment.splitLines(render(this.view(this.clock.now()), { ...options, height }));
-        // The app set the budget, so the app shapes what comes back: no deeper
-        // than the terminal — a taller frame would scroll the rows the painter
-        // goes back over — and, as a region, exactly that deep.
-        const frame = this.painter.paint(() => fitHeight(lines.slice(0, height.rows), height), { rows: height.rows, cols: options.maxWidth }, this.console.destination);
+        // once a frame; the view is handed the time the timeline maps it to, as
+        // data, and what the frame says about when it changes comes back on the
+        // clock. The app set the budget, so the app shapes what comes back: no
+        // deeper than the terminal — a taller frame would scroll the rows the
+        // painter goes back over — and, as a region, exactly that deep.
+        const drawn = drawView(this.view, this._time(), this, { ...options, height }, (renderable, under) => fitHeight(Segment.splitLines(render(renderable, under)).slice(0, height.rows), height));
+        const frame = this.painter.paint(() => drawn.lines, { rows: height.rows, cols: options.maxWidth }, this.console.destination);
         this._frame = frame;
+        this.said = drawn;
+        this.tick();
         for (const handler of [...this.paintHandlers])
             handler(frame);
     }

package/dist/host/input.js

@@ -146,7 +146,6 @@ const M_LOWER = 0x6d; // m
 const UTF8_ENCODER = new TextEncoder();
 const UTF8_DECODER = new TextDecoder("utf-8");
 const ASCII_DECODER = new TextDecoder("ascii");
-const EMPTY_BYTES = new Uint8Array(0);
 /**
  * How long a `"split"` host's parser waits for the rest of an unfinished
  * escape sequence before reading it as the keys it already holds. Textual's
@@ -195,7 +194,7 @@ export class InputParser {
     // `Buffer` — node's Buffer extends Uint8Array, so Buffer chunks from
     // process.stdin satisfy this type, while a browser host can emit native
     // Uint8Array without depending on a Buffer global polyfill.
-    buffer = EMPTY_BYTES;
+    buffer = new Uint8Array(0);
     // [LAW:types-are-the-program] `setTimeout`/`clearTimeout` are universal
     // across node and browser; `setImmediate` is node-only.
     escTimer;
@@ -218,7 +217,7 @@ export class InputParser {
         this.cancelEscape();
         // The buffer is settled before the sink hears Escape, so a sink that
         // resets the parser on it (an app stopping) leaves nothing to drain.
-        this.buffer = concatBytes(escaped ? EMPTY_BYTES : this.buffer, next);
+        this.buffer = concatBytes(escaped ? new Uint8Array(0) : this.buffer, next);
         try {
             if (escaped)
                 this.sink.key(ESCAPE);
@@ -292,7 +291,7 @@ export class InputParser {
     /** Drop what is buffered and any held escape sequence: the parser as constructed. */
     reset() {
         this.cancelEscape();
-        this.buffer = EMPTY_BYTES;
+        this.buffer = new Uint8Array(0);
     }
     /** A lone ESC, the one hold a next chunk can settle before its bytes are read. */
     holdingEscape() {