@promptctl/rich-js 0.24.0 → 0.25.0

package/dist/core/timeline.js

@@ -0,0 +1,180 @@
+/**
+ * Timeline — the map from the host's clock to the time an animation is
+ * asked for: playback control, and nothing else.
+ *
+ * Every animation is a pure function of its time (`./animation.ts`), so
+ * pausing, reversing, scrubbing and speeding one up are not things done to
+ * it but a change in which time it is asked for. A timeline is that map, as
+ * a value: an animation time at a host time, a rate — animation seconds per
+ * host second, negative running it backwards — and whether it is held. Each
+ * operation is a value in and a value out, so a paused timeline resumed at a
+ * new host time is one that maps that host time to the time it froze at, and
+ * two hosts holding equal timelines ask every animation for the same time.
+ *
+ * A paused timeline carries no host anchor: it maps every host time to the
+ * one time it holds, so there is no origin for it to be wrong about.
+ * [LAW:types-are-the-program]
+ *
+ * `run` is an animation on host time. Its `nextChange` is the host moment
+ * the mapped time reaches the animation's own answer, which is what
+ * `Spinner`'s speed scaled its holds for before this existed: an answer a
+ * host reads is on the host's timeline, and a beat over scaled time answers
+ * on the scaled one. Run backwards, the host next sees a change when the
+ * mapped time drops under where the value began — the animation's
+ * `lastChange` — so a reversed loop turns exactly at its hold boundaries,
+ * and a reversed one-shot changes at its switch and never before its start.
+ * Paused, nothing changes: never, and never did. The host moment is the
+ * first host float the map carries past the edge, searched out from the sum
+ * `origin + (edge - time) / rate` (`firstReaching`): a host float is a step
+ * of `rate` on the animation's clock, so the floats between that sum and
+ * the first one past the edge are as many as the two clocks' resolutions
+ * are apart — unbounded, far from the origin or at a slow rate — which is
+ * 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) {
+    if (!Number.isFinite(seconds))
+        throw new RangeError(`${what} must be a finite number of seconds, got ${seconds}`);
+    return seconds;
+}
+/** [LAW:single-enforcer] A host time is a finite number of seconds, refused once, at every operation that takes one. */
+const hostTime = (host) => finiteSeconds("Timeline host time", host);
+/**
+ * [LAW:parse-dont-validate] A rate is a finite number other than zero,
+ * settled where it is given: a rate of zero would be a second way to hold a
+ * timeline still, and `pause` is the one.
+ */
+function playbackRate(rate) {
+    if (!Number.isFinite(rate) || rate === 0)
+        throw new RangeError(`Timeline rate must be finite and not zero, got ${rate}`);
+    return rate;
+}
+/** `timeline` with `time` at host time `host`, at `rate`, held as it was. A paused timeline keeps no origin, and refuses a host time it cannot use all the same. */
+function anchored(timeline, host, time, rate) {
+    const origin = hostTime(host);
+    return timeline.playing ? { playing: true, origin, time, rate } : { playing: false, time, rate };
+}
+/** `animation` asked at the time `playing` maps each host time to, saying on host time when it changes. */
+function played(animation, { origin, time, rate }) {
+    const mapped = (host) => time + rate * (host - origin);
+    const forward = rate > 0;
+    // Forwards, the host next sees the animation's own next change, and the
+    // value began when the animation says it did; backwards, it next sees a
+    // change where the value began, and the value began where the animation
+    // says it ends. A hold is `[lastChange, nextChange)`, so the far side of
+    // an edge is at it going up and strictly under it coming down.
+    const ahead = forward ? (t) => animation.nextChange(t) : (t) => animation.lastChange(t);
+    const behind = forward ? (t) => animation.lastChange(t) : (t) => animation.nextChange(t);
+    const past = forward ? (t, edge) => t >= edge : (t, edge) => t < edge;
+    // The first host moment the map carries past `edge`, an animation time.
+    // An edge at infinity, or one so far off at this rate that no host float
+    // reaches it, is never reached, forwards or backwards: the sum's own sign
+    // says which, as a host moment past either end of the host's clock.
+    const hostOf = (edge) => {
+        const sum = origin + (edge - time) / rate;
+        return Number.isFinite(sum) ? firstReaching(sum, (host) => past(mapped(host), edge)) : sum;
+    };
+    return Animation.of({
+        at: (host) => animation.at(mapped(hostTime(host))),
+        nextChange(host) {
+            const h = hostTime(host);
+            const t = mapped(h);
+            const edge = ahead(t);
+            return edge === t ? h : Math.max(h, hostOf(edge));
+        },
+        lastChange(host) {
+            const h = hostTime(host);
+            const t = mapped(h);
+            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. */
+    play(origin, rate = 1) {
+        return { playing: true, origin: finiteSeconds("Timeline.play origin", origin), time: 0, rate: playbackRate(rate) };
+    },
+    /** The animation time at host time `host`. */
+    at(timeline, host) {
+        const h = hostTime(host);
+        return timeline.playing ? timeline.time + timeline.rate * (h - timeline.origin) : timeline.time;
+    },
+    /** `timeline` held at the animation time it maps `host` to. Pausing a paused timeline holds the same time. */
+    pause(timeline, host) {
+        return { playing: false, time: Timeline.at(timeline, host), rate: timeline.rate };
+    },
+    /** `timeline` playing from `host` at the animation time it maps `host` to, at its rate. Resuming a playing timeline is the same map. */
+    resume(timeline, host) {
+        return { playing: true, origin: hostTime(host), time: Timeline.at(timeline, host), rate: timeline.rate };
+    },
+    /** `timeline` with the animation at `time` at host time `host`, playing or held as it was. */
+    seek(timeline, host, time) {
+        return anchored(timeline, host, finiteSeconds("Timeline.seek time", time), timeline.rate);
+    },
+    /** `timeline` at `rate` from host time `host` on, with no jump: the animation time at `host` is what it was. */
+    withRate(timeline, host, rate) {
+        return anchored(timeline, host, Timeline.at(timeline, host), playbackRate(rate));
+    },
+    /**
+     * `animation` on host time: its value at the time `timeline` maps each
+     * 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: 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 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

@@ -0,0 +1,49 @@
+/**
+ * Tween — a value eased from one number to another over seconds, then held:
+ * the animation a progress bar's fill, a counter or a width is handed so it
+ * moves to its new value instead of jumping. The first `Animation` of a
+ * value that is never drawn as cells, so its `nextChange` is its only way of
+ * saying when to look again (`./animation.ts`).
+ *
+ * The value at `t` is the `Timing`'s ease of the way from `from` to `to`
+ * through `Phase.once(0, seconds)`: `from` at `t ≤ 0` whenever the ease
+ * starts at 0, as every built-in does but `step-start` and the steps that
+ * jump at the start of their interval, which show their first jump before
+ * the tween begins, as `ColorRamp.at` does; `to` from `seconds` on. It is
+ * the one-shot phase every effect transition reads time
+ * through, so there is no second rule about when a one-shot begins: it
+ * begins at 0 on its own clock, and starting it later is `Animation.sequence`'s
+ * or a `Timeline`'s job. [LAW:single-enforcer] An ease that overshoots is
+ * shown as it is — a count eased by `back-out` passes its target and comes
+ * back, which is what the curve is for — and lands exactly on `to`, because
+ * every built-in ease is exactly 1 at 1 and the blend is `(1 − p)·from +
+ * p·to`, exact at both ends where `from + (to − from)·p` is not.
+ *
+ * A tween keeps nothing between calls, so retargeting is not a mutation: a
+ * tween whose target changes at `t₁` is the old tween until `t₁`, then a new
+ * one from the old one's value there — `Animation.sequence(old, t₁,
+ * tween(old.at(t₁), to, timing))` — and starts from where it is because
+ * that is where it was built from. [LAW:no-ambient-temporal-coupling]
+ *
+ * Over colours it is a `ColorRamp` read over time (`../themes/ramp.ts`,
+ * `over`): the ramp is already the one place two colours are blended, in
+ * OKLCH, and a colour tween is a two-stop ramp over its seconds, not a
+ * second blender. [LAW:one-source-of-truth]
+ *
+ * Tier 6 of `src/core/`: `./easing.ts` and `./animation.ts`, nothing else.
+ * [LAW:one-way-deps]
+ */
+import { Animation } from "./animation.js";
+import { type Timing } from "./easing.js";
+/**
+ * `from` eased to `to` over `timing`, as an `Animation<number>`: moving from
+ * 0 to `timing.seconds` on its own clock, the ease of 0 before (`from`, for
+ * every ease that starts at 0), `to` after, and so
+ * seen at its end, never mid-way, by a host whose frames are further apart
+ * than it is long. `from` and `to` must be finite; the seconds are checked
+ * where every one-shot's are, in `Phase.once`. A tween to where it already
+ * is is `Animation.constant(from)`, decided here once: the blend would land
+ * one ulp off `from` at some `p`, and a value that never moves is one that
+ * never changes, so a host is told not to look again. [LAW:parse-dont-validate]
+ */
+export declare function tween(from: number, to: number, timing: Timing): Animation<number>;

package/dist/core/tween.js

@@ -0,0 +1,71 @@
+/**
+ * Tween — a value eased from one number to another over seconds, then held:
+ * the animation a progress bar's fill, a counter or a width is handed so it
+ * moves to its new value instead of jumping. The first `Animation` of a
+ * value that is never drawn as cells, so its `nextChange` is its only way of
+ * saying when to look again (`./animation.ts`).
+ *
+ * The value at `t` is the `Timing`'s ease of the way from `from` to `to`
+ * through `Phase.once(0, seconds)`: `from` at `t ≤ 0` whenever the ease
+ * starts at 0, as every built-in does but `step-start` and the steps that
+ * jump at the start of their interval, which show their first jump before
+ * the tween begins, as `ColorRamp.at` does; `to` from `seconds` on. It is
+ * the one-shot phase every effect transition reads time
+ * through, so there is no second rule about when a one-shot begins: it
+ * begins at 0 on its own clock, and starting it later is `Animation.sequence`'s
+ * or a `Timeline`'s job. [LAW:single-enforcer] An ease that overshoots is
+ * shown as it is — a count eased by `back-out` passes its target and comes
+ * back, which is what the curve is for — and lands exactly on `to`, because
+ * every built-in ease is exactly 1 at 1 and the blend is `(1 − p)·from +
+ * p·to`, exact at both ends where `from + (to − from)·p` is not.
+ *
+ * A tween keeps nothing between calls, so retargeting is not a mutation: a
+ * tween whose target changes at `t₁` is the old tween until `t₁`, then a new
+ * one from the old one's value there — `Animation.sequence(old, t₁,
+ * tween(old.at(t₁), to, timing))` — and starts from where it is because
+ * that is where it was built from. [LAW:no-ambient-temporal-coupling]
+ *
+ * Over colours it is a `ColorRamp` read over time (`../themes/ramp.ts`,
+ * `over`): the ramp is already the one place two colours are blended, in
+ * OKLCH, and a colour tween is a two-stop ramp over its seconds, not a
+ * second blender. [LAW:one-source-of-truth]
+ *
+ * Tier 6 of `src/core/`: `./easing.ts` and `./animation.ts`, nothing else.
+ * [LAW:one-way-deps]
+ */
+import { Animation } from "./animation.js";
+import { Phase } from "./easing.js";
+/**
+ * `from` eased to `to` over `timing`, as an `Animation<number>`: moving from
+ * 0 to `timing.seconds` on its own clock, the ease of 0 before (`from`, for
+ * every ease that starts at 0), `to` after, and so
+ * seen at its end, never mid-way, by a host whose frames are further apart
+ * than it is long. `from` and `to` must be finite; the seconds are checked
+ * where every one-shot's are, in `Phase.once`. A tween to where it already
+ * is is `Animation.constant(from)`, decided here once: the blend would land
+ * one ulp off `from` at some `p`, and a value that never moves is one that
+ * never changes, so a host is told not to look again. [LAW:parse-dont-validate]
+ */
+export function tween(from, to, timing) {
+    for (const [name, v] of [["from", from], ["to", to]]) {
+        if (!Number.isFinite(v))
+            throw new RangeError(`tween ${name} must be finite, got ${v}`);
+    }
+    const { ease, seconds } = timing;
+    const phase = Phase.once(0, seconds);
+    if (from === to)
+        return Animation.constant(from);
+    return Animation.of({
+        at(t) {
+            const p = ease(phase(t));
+            return (1 - p) * from + p * to;
+        },
+        // Before it begins the value is held until 0; while it moves, every
+        // frame; from `seconds` on, never again — and it became what it is at
+        // `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 —