@promptctl/rich-js 0.24.0 → 0.24.1

package/dist/core/timeline.d.ts

@@ -0,0 +1,84 @@
+/**
+ * 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.
+ *
+ * [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 type { Animation } from "./animation.js";
+/**
+ * A map from host time to animation time. Playing, it is `time` at `origin`
+ * moving `rate` animation seconds a host second; paused, it is `time` at
+ * every host time, with the rate it resumes at.
+ */
+export type Timeline = {
+    readonly playing: true;
+    /** The host time, in seconds, at which the animation time is `time`. */
+    readonly origin: number;
+    /** The animation time, in seconds, at `origin`. */
+    readonly time: number;
+    /** Animation seconds per host second; negative runs the animation backwards. Never zero: a held timeline is paused. */
+    readonly rate: number;
+} | {
+    readonly playing: false;
+    /** The animation time, in seconds, held at every host time. */
+    readonly time: number;
+    /** The rate the timeline resumes at. */
+    readonly rate: number;
+};
+export declare const Timeline: {
+    /** Playing from host time `origin`, at which the animation time is 0, at `rate` animation seconds a host second. */
+    play(origin: number, rate?: number): Timeline;
+    /** The animation time at host time `host`. */
+    at(timeline: Timeline, host: number): number;
+    /** `timeline` held at the animation time it maps `host` to. Pausing a paused timeline holds the same time. */
+    pause(timeline: Timeline, host: number): Timeline;
+    /** `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: Timeline, host: number): Timeline;
+    /** `timeline` with the animation at `time` at host time `host`, playing or held as it was. */
+    seek(timeline: Timeline, host: number, time: number): Timeline;
+    /** `timeline` at `rate` from host time `host` on, with no jump: the animation time at `host` is what it was. */
+    withRate(timeline: Timeline, host: number, rate: number): Timeline;
+    /**
+     * `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: 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.
+     */
+    run<T>(timeline: Timeline, animation: Animation<T>): Animation<T>;
+};

package/dist/core/timeline.js

@@ -0,0 +1,144 @@
+/**
+ * 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.
+ *
+ * [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 { 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 {
+        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));
+        },
+    };
+}
+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: 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.
+     */
+    run(timeline, animation) {
+        if (timeline.playing)
+            return played(animation, timeline);
+        return {
+            at: (host) => animation.at(Timeline.at(timeline, host)),
+            nextChange: (host) => (hostTime(host), Number.POSITIVE_INFINITY),
+            lastChange: (host) => (hostTime(host), Number.NEGATIVE_INFINITY),
+        };
+    },
+};

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 2 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,69 @@
+/**
+ * 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 2 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 {
+        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),
+    };
+}

package/dist/host/app.js

@@ -34,7 +34,7 @@ import { frameRate, systemClock } from "../core/clock.js";
 import { Console } from "../core/console.js";
 import { Segment } from "../core/segment.js";
 import { SurfacePainter } from "../core/paint.js";
-import { fitHeight } from "../core/protocol.js";
+import { fitHeight, render } from "../core/protocol.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
@@ -381,7 +381,7 @@ export class App {
         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(this.view(this.clock.now()).render({ ...options, height }));
+        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.

package/dist/index.d.ts

@@ -15,8 +15,11 @@ export { transposePalette, themeKeyForRoot, isAnchored, ANCHORED_ROOTS, } from "
 export { lighten, darken, relativeLuminance, contrastRatio, contrastFor, ensureContrast, ensureDrawn, drawnColour, } from "./themes/colorMath.js";
 export { ColorRamp } from "./themes/ramp.js";
 export type { ColorStop } from "./themes/ramp.js";
-export { EASES, Phase, beat, cubicBezier, parseEase, steps } from "./core/easing.js";
-export type { Beat, Ease, StepPosition } from "./core/easing.js";
+export { EASES, Phase, beat, cubicBezier, parseEase, spring, steps } from "./core/easing.js";
+export type { Beat, Ease, SpringOptions, StepPosition, Timing } from "./core/easing.js";
+export { Animation } from "./core/animation.js";
+export { tween } from "./core/tween.js";
+export { Timeline } from "./core/timeline.js";
 export { frameRate, systemClock } from "./core/clock.js";
 export type { Clock, FrameRate } from "./core/clock.js";
 export { Style, StyleSyntaxError, StyleStack, Theme, NULL_STYLE, DEFAULT_STYLES, } from "./core/style.js";
@@ -27,8 +30,8 @@ export type { Anchor } from "./core/anchor.js";
 export { Box } from "./core/box.js";
 export type { EdgeChars, ContentChars, RowLevel, SubstituteOptions } from "./core/box.js";
 export { ASCII, ASCII2, ASCII_DOUBLE_HEAD, SQUARE, SQUARE_DOUBLE_HEAD, MINIMAL, MINIMAL_HEAVY_HEAD, MINIMAL_DOUBLE_HEAD, SIMPLE, SIMPLE_HEAD, SIMPLE_HEAVY, HORIZONTALS, ROUNDED, HEAVY, HEAVY_EDGE, HEAVY_HEAD, DOUBLE, DOUBLE_EDGE, MARKDOWN, } from "./core/box.js";
-export { isRenderable, isMeasurable, withCellWidth, withBoundedWidth, insetHeight, stackedHeight, regionRows, fitHeight, getStyle, } from "./core/protocol.js";
-export type { RenderOptions, OverflowMethod, Height, Renderable, Measurable, StyleErrorHandler, } from "./core/protocol.js";
+export { render, isRenderable, isMeasurable, withCellWidth, withBoundedWidth, insetHeight, stackedHeight, regionRows, fitHeight, getStyle, } from "./core/protocol.js";
+export type { RenderOptions, OverflowMethod, Height, Renderable, Measurable, Composite, Presence, StyleErrorHandler, } from "./core/protocol.js";
 export type { Unsubscribe } from "./core/subscription.js";
 export { Measurement, measureRenderables } from "./core/measure.js";
 export { Span, RichText } from "./core/text.js";
@@ -55,8 +58,8 @@ export { Console } from "./core/console.js";
 export type { ConsoleOptions, ConsoleSink, ConsoleStream, ConsoleEnvironment, LiveRegion, PrintOptions, } from "./core/console.js";
 export type { Env } from "./core/env.js";
 export { Constrain } from "./renderables/constrain.js";
-export { Effected, confined, drawnOf, nextChangeOf, onBeat, withNextChange } from "./renderables/effect.js";
-export type { CellColors, Drawn, Effect, EffectCell, EffectedOptions, Pair, Placed } from "./renderables/effect.js";
+export { Effected, confined, drawnOf, onBeat } from "./renderables/effect.js";
+export type { CellColors, Drawn, Effect, EffectCell, EffectedOptions, EffectFrame, Pair, Placed } from "./renderables/effect.js";
 export { EFFECT_CATALOGUE, EFFECT_CURVES, EFFECT_LIGHTS, dissolveOut, fadeIn, onColors, pulse, shimmer, sparkle, steppedInk, wheel, } from "./renderables/effects.js";
 export type { ColorStep, Curve, EffectTarget, Field, Loop, LoopName, Touch, Transition, TransitionName } from "./renderables/effects.js";
 export { Align } from "./renderables/align.js";
@@ -77,7 +80,7 @@ export { ProgressBar } from "./renderables/progressBar.js";
 export type { ProgressBarOptions } from "./renderables/progressBar.js";
 export { Spinner } from "./renderables/spinner.js";
 export type { SpinnerOptions } from "./renderables/spinner.js";
-export { FrameSequence, Frames } from "./renderables/frames.js";
+export { FrameSequence, Frames, frameAt } from "./renderables/frames.js";
 export type { Frame, FramesOptions } from "./renderables/frames.js";
 export { Table, Column } from "./renderables/table.js";
 export type { TableOptions, ColumnOptions } from "./renderables/table.js";

package/dist/index.js

@@ -29,7 +29,16 @@ export { lighten, darken, relativeLuminance, contrastRatio, contrastFor, ensureC
 export { ColorRamp } from "./themes/ramp.js";
 // Progress in [0, 1]: phases turn seconds into it, eases reshape it. One
 // vocabulary for ramps and time-based effects alike, CSS's names throughout.
-export { EASES, Phase, beat, cubicBezier, parseEase, steps } from "./core/easing.js";
+export { EASES, Phase, beat, cubicBezier, parseEase, spring, steps } from "./core/easing.js";
+// A value for a time, and when it next changes: the one type every kind of
+// motion is an instance of — beats, frame sequences, spinners, effects.
+export { Animation } from "./core/animation.js";
+// A number eased from one value to another over seconds, then held: the
+// value animation a fill, a counter or a width moves by instead of jumping.
+export { tween } from "./core/tween.js";
+// The map from the host's clock to the time an animation is asked for:
+// pause, reverse, scrub and speed, once, above every kind of motion.
+export { Timeline } from "./core/timeline.js";
 // The time source and timer whoever draws frames is handed, and the one
 // parser of the rate it ticks at.
 export { frameRate, systemClock } from "./core/clock.js";
@@ -38,7 +47,7 @@ export { Segment, ControlType, } from "./core/segment.js";
 export { Box } from "./core/box.js";
 export { ASCII, ASCII2, ASCII_DOUBLE_HEAD, SQUARE, SQUARE_DOUBLE_HEAD, MINIMAL, MINIMAL_HEAVY_HEAD, MINIMAL_DOUBLE_HEAD, SIMPLE, SIMPLE_HEAD, SIMPLE_HEAVY, HORIZONTALS, ROUNDED, HEAVY, HEAVY_EDGE, HEAVY_HEAD, DOUBLE, DOUBLE_EDGE, MARKDOWN, } from "./core/box.js";
 // Protocol
-export { isRenderable, isMeasurable, withCellWidth, withBoundedWidth, insetHeight, stackedHeight, regionRows, fitHeight, getStyle, } from "./core/protocol.js";
+export { render, isRenderable, isMeasurable, withCellWidth, withBoundedWidth, insetHeight, stackedHeight, regionRows, fitHeight, getStyle, } from "./core/protocol.js";
 // Measurement
 export { Measurement, measureRenderables } from "./core/measure.js";
 // Text
@@ -69,7 +78,7 @@ export { SPINNERS, DEFAULT_SPINNER } from "./core/spinnerData.js";
 export { Console } from "./core/console.js";
 // Renderables
 export { Constrain } from "./renderables/constrain.js";
-export { Effected, confined, drawnOf, nextChangeOf, onBeat, withNextChange } from "./renderables/effect.js";
+export { Effected, confined, drawnOf, onBeat } from "./renderables/effect.js";
 export { EFFECT_CATALOGUE, EFFECT_CURVES, EFFECT_LIGHTS, dissolveOut, fadeIn, onColors, pulse, shimmer, sparkle, steppedInk, wheel, } from "./renderables/effects.js";
 export { Align } from "./renderables/align.js";
 export { Padding } from "./renderables/padding.js";
@@ -81,7 +90,7 @@ export { Panel } from "./renderables/panel.js";
 export { Group } from "./renderables/group.js";
 export { ProgressBar } from "./renderables/progressBar.js";
 export { Spinner } from "./renderables/spinner.js";
-export { FrameSequence, Frames } from "./renderables/frames.js";
+export { FrameSequence, Frames, frameAt } from "./renderables/frames.js";
 export { Table, Column } from "./renderables/table.js";
 export { Tree } from "./renderables/tree.js";
 export { Columns } from "./renderables/columns.js";

package/dist/renderables/align.d.ts

@@ -2,9 +2,9 @@
  * Align — wraps a renderable and places its output horizontally, as one block.
  */
 import { Segment } from "../core/segment.js";
-import type { Renderable, Measurable, RenderOptions } from "../core/protocol.js";
+import type { Composite, Renderable, Measurable, RenderOptions } from "../core/protocol.js";
 import { type Alignment } from "../core/place.js";
-export declare class Align implements Renderable, Measurable {
+export declare class Align implements Renderable, Measurable, Composite {
     readonly renderable: Renderable;
     readonly align: Alignment;
     constructor(renderable: Renderable, align?: Alignment);
@@ -13,4 +13,5 @@ export declare class Align implements Renderable, Measurable {
         minimum: number;
         maximum: number;
     };
+    contents(): Iterable<Renderable>;
 }

package/dist/renderables/align.js

@@ -23,4 +23,7 @@ export class Align {
     measure(options) {
         return Measurement.get(options, this.renderable);
     }
+    *contents() {
+        yield this.renderable;
+    }
 }

package/dist/renderables/columns.d.ts

@@ -10,7 +10,7 @@
  */
 import type { Segment } from "../core/segment.js";
 import type { PaddingDimensions } from "./padding.js";
-import type { Renderable, Measurable, RenderOptions } from "../core/protocol.js";
+import type { Composite, Renderable, Measurable, RenderOptions } from "../core/protocol.js";
 export interface ColumnsOptions {
     expand?: boolean;
     equal?: boolean;
@@ -18,7 +18,7 @@ export interface ColumnsOptions {
     padding?: PaddingDimensions;
     columnFirst?: boolean;
 }
-export declare class Columns implements Renderable, Measurable {
+export declare class Columns implements Renderable, Measurable, Composite {
     renderables: (Renderable & Partial<Measurable>)[];
     readonly expand: boolean;
     readonly equal: boolean;
@@ -27,6 +27,7 @@ export declare class Columns implements Renderable, Measurable {
     private readonly padding;
     constructor(items?: Iterable<unknown>, options?: ColumnsOptions);
     render(rawOptions: RenderOptions): Iterable<Segment>;
+    contents(): Iterable<Renderable>;
     measure(rawOptions: RenderOptions): {
         minimum: number;
         maximum: number;

package/dist/renderables/columns.js

@@ -10,7 +10,7 @@
  */
 import { Measurement } from "../core/measure.js";
 import { normalizePadding } from "./padding.js";
-import { withBoundedWidth, withCellWidth } from "../core/protocol.js";
+import { render, withBoundedWidth, withCellWidth } from "../core/protocol.js";
 import { cellCount } from "../core/cells.js";
 import { EmbeddedText, embed } from "./embed.js";
 import { Constrain } from "./constrain.js";
@@ -68,7 +68,12 @@ export class Columns {
         // single column is laid out. An unbounded width reaches the same place by
         // the same route, which is why the parse here is the bounded one.
         const options = withBoundedWidth(rawOptions, this);
-        yield* this._grid(options).render(options);
+        yield* render(this._grid(options), options);
+    }
+    // The items, in the order they were given. Laid out column-first, the grid
+    // draws them in an order its width decides, and handed no column it has none.
+    contents() {
+        return this.renderables;
     }
     measure(rawOptions) {
         // The maximum is the grid's, which reports its width before `expand`: a

package/dist/renderables/constrain.d.ts

@@ -2,12 +2,13 @@
  * Constrain — wraps a renderable and constrains its maximum width.
  */
 import { Segment } from "../core/segment.js";
-import type { Renderable, Measurable, RenderOptions } from "../core/protocol.js";
-export declare class Constrain implements Renderable, Measurable {
+import type { Composite, Renderable, Measurable, RenderOptions } from "../core/protocol.js";
+export declare class Constrain implements Renderable, Measurable, Composite {
     readonly renderable: Renderable;
     readonly width: number | undefined;
     constructor(renderable: Renderable, width?: number);
     render(options: RenderOptions): Iterable<Segment>;
+    contents(): Iterable<Renderable>;
     measure(options: RenderOptions): {
         minimum: number;
         maximum: number;

package/dist/renderables/constrain.js

@@ -2,6 +2,7 @@
  * Constrain — wraps a renderable and constrains its maximum width.
  */
 import { Measurement } from "../core/measure.js";
+import { render } from "../core/protocol.js";
 export class Constrain {
     renderable;
     width;
@@ -18,7 +19,10 @@ export class Constrain {
             ...options,
             maxWidth: constrainedWidth,
         };
-        yield* this.renderable.render(innerOptions);
+        yield* render(this.renderable, innerOptions);
+    }
+    *contents() {
+        yield this.renderable;
     }
     measure(options) {
         // Measured at the width it will be drawn at, as Rich's `update_width` does;