@promptctl/rich-js 0.23.0 → 0.24.1

package/dist/core/style.js

@@ -94,7 +94,26 @@ export class Style {
      * unequal, because they came from different places.
      */
     anchor;
+    /**
+     * When what this style's cells show next changes, in seconds on the
+     * timeline of whoever drew the frame — `t` itself for a cell drawn by
+     * something that moves every frame, and `Infinity`, the default, for one
+     * that never changes. It draws nothing. Whatever draws for a handed time
+     * stamps its cells with it (`Frames`, `Effected`), the stamp rides up
+     * through every container as the anchor does (`./anchor.ts`), and
+     * whoever holds the composed frame reads the soonest off it
+     * (`Segment.nextChange`), so a host knows when to draw again without
+     * asking each container. Two styles laid together change at the sooner.
+     */
+    nextChange;
     constructor(options = {}) {
+        const nextChange = options.nextChange ?? Number.POSITIVE_INFINITY;
+        // [LAW:parse-dont-validate] A time or never, settled where the style is
+        // made: NaN and -Infinity fail here, so no reader of a frame meets one.
+        if (!(nextChange > Number.NEGATIVE_INFINITY)) {
+            throw new RangeError(`Style nextChange must be a time in seconds or Infinity, got ${nextChange}`);
+        }
+        this.nextChange = nextChange;
         this.color = resolveColor(options.color);
         this.bgcolor = resolveBackground(options.bgcolor);
         this.bold = options.bold;
@@ -110,7 +129,8 @@ export class Style {
         this.frame = options.frame;
         this.encircle = options.encircle;
         this.overline = options.overline;
-        this.link = options.link;
+        // As the reference's `self._link`, read only for truth: an empty URL is no link.
+        this.link = options.link || undefined;
         this.meta = options.meta;
         this.anchor = options.anchor;
     }
@@ -132,7 +152,8 @@ export class Style {
             this.overline === undefined &&
             this.link === undefined &&
             this.meta === undefined &&
-            this.anchor === undefined);
+            this.anchor === undefined &&
+            this.nextChange === Number.POSITIVE_INFINITY);
     }
     get transparentBackground() {
         return this.bgcolor === undefined || this.bgcolor.isDefault;
@@ -204,6 +225,8 @@ export class Style {
                 ? { ...this.meta, ...other.meta }
                 : other.meta ?? this.meta,
             anchor: other.anchor ?? this.anchor,
+            // Cells under both change when either does: the sooner.
+            nextChange: Math.min(this.nextChange, other.nextChange),
         });
     }
     equals(other) {
@@ -225,7 +248,8 @@ export class Style {
             this.encircle === other.encircle &&
             this.overline === other.overline &&
             this.link === other.link &&
-            anchorsEqual(this.anchor, other.anchor));
+            anchorsEqual(this.anchor, other.anchor) &&
+            this.nextChange === other.nextChange);
     }
     /**
      * The colours this style puts on screen at `colorSystem`: each flattened
@@ -273,7 +297,11 @@ export class Style {
         ].join(";");
     }
     /**
-     * Serializes to a canonical string that round-trips through `Style.parse()`.
+     * The look as a canonical string that round-trips through `Style.parse()`:
+     * colours, attributes and the link, which is all a style string can spell.
+     * What a style carries beyond its look — `meta`, `anchor`, `nextChange` —
+     * has no spelling and is not here, so two styles that differ only there
+     * read alike; `equals` tells them apart.
      */
     toString() {
         if (this.isNull)
@@ -668,16 +696,28 @@ export const DEFAULT_STYLES = {
     "syntax.line_number.highlight": Style.parse("bold grey93 on grey27"),
     // Markdown
     "markdown.h1": Style.parse("bold underline"),
-    "markdown.h2": Style.parse("bold"),
-    "markdown.h3": Style.parse("bold dim"),
-    "markdown.h4": Style.parse("bold dim italic"),
+    "markdown.h2": Style.parse("underline magenta"),
+    "markdown.h3": Style.parse("bold magenta"),
+    "markdown.h4": Style.parse("italic magenta"),
+    "markdown.h5": Style.parse("italic"),
+    "markdown.h6": Style.parse("dim"),
     // A fixed cyan, not the theme's: `cyan` is dark enough on some themes to
     // sink into grey11. Bold, as Rich's is: at 16 colours a renderable draws it
     // without its pair (`groundedStyle`), and bold is what still marks code.
     "markdown.code": Style.parse("bold dark_turquoise on grey11"),
-    "markdown.hr": Style.parse("yellow"),
+    "markdown.em": Style.parse("italic"),
+    "markdown.strong": Style.parse("bold"),
+    "markdown.s": Style.parse("strike"),
+    "markdown.kbd": Style.parse("bold bright_yellow"),
+    "markdown.block_quote": Style.parse("magenta"),
+    "markdown.hr": Style.parse("dim"),
+    "markdown.item": NULL_STYLE,
+    "markdown.item.bullet": Style.parse("bold"),
+    "markdown.item.number": Style.parse("cyan"),
     "markdown.link": Style.parse("bright_blue"),
-    "markdown.link_url": Style.parse("blue"),
+    "markdown.link_url": Style.parse("underline blue"),
+    "markdown.table.border": Style.parse("cyan"),
+    "markdown.table.header": Style.parse("not bold cyan"),
     // Progress
     "progress.description": NULL_STYLE,
     "progress.percentage": Style.parse("magenta"),

package/dist/core/text.js

@@ -9,10 +9,20 @@ import { stripOscTerminators } from "./osc8.js";
 import { drawable, getStyle, withBoundedWidth } from "./protocol.js";
 // Every C0 control and DEL except \t and \n. Rich's `Text` strips only
 // `STRIP_CONTROL_CODES` (BEL, BS, VT, FF, CR); the rest of the set is the
-// port's extension, so no C0 byte of content can start an escape sequence or
-// move the cursor on the wire. C1 controls (U+0080–U+009F) pass, as in Rich.
-// [LAW:single-enforcer] Single place where control chars are sanitized
-const CONTROL_CHARS_RE = /[\x00-\x08\x0B-\x1F\x7F]/g;
+// port's extension, so no byte of content can start an escape sequence or move
+// the cursor on the wire: the C1 controls (U+0080–U+009F) go as well, since a
+// terminal reads U+009B as CSI and U+009D as OSC (TextInput refuses them for
+// the same reason). So do the format controls that hold state past the text,
+// also the port's extension: the bidi embeddings and overrides with their
+// closer PDF (U+202A–U+202E), the isolates with their closer PDI
+// (U+2066–U+2069), and the deprecated shaping and swapping switches
+// (U+206A–U+206F). An opener left unclosed in content reverses whatever is
+// drawn after it on the line, and a closer whose opener is gone closes
+// nothing of the text's own. The bidi marks (LRM, RLM, ALM) hold no state and
+// pass, since right-to-left text needs them.
+// [LAW:single-enforcer] Single place where control chars are sanitized: every
+// string that becomes part of a Text's characters passes here.
+const CONTROL_CHARS_RE = /[\x00-\x08\x0B-\x1F\x7F-\x9F\u202A-\u202E\u2066-\u206F]/g;
 export function stripControlChars(text) {
     return text.replace(CONTROL_CHARS_RE, "");
 }
@@ -73,7 +83,10 @@ function sanitizeStyleLink(style) {
  * [LAW:single-enforcer] Nor does a RichText keep an anchor (`./anchor.ts`). It
  * lays its text out anew, so a stamp naming where a cell sat in the output it
  * came from would name the wrong cell once it wraps, slices or overlaps; the
- * owner that renders the RichText is the one that stamps its cells.
+ * owner that renders the RichText is the one that stamps its cells. A
+ * `nextChange` stays: when a span's cells next change is true of them
+ * wherever the text lays them, so a frame appended into a line still says
+ * when it turns.
  */
 function admitStyle(style) {
     if (typeof style === "string")
@@ -470,10 +483,9 @@ export class RichText {
         return this;
     }
     pad(count, char) {
-        const c = char ?? " ";
-        const padding = c.repeat(count);
-        // Shift all spans to the right
-        this._spans = this._spans.map((s) => s.move(count));
+        const padding = stripControlChars(char ?? " ").repeat(count);
+        // Shift all spans right by what the left side gained.
+        this._spans = this._spans.map((s) => s.move(padding.length));
         this._text = padding + this._text + padding;
         return this;
     }
@@ -489,14 +501,13 @@ export class RichText {
         return this;
     }
     padLeft(count, char) {
-        const c = char ?? " ";
-        this._spans = this._spans.map((s) => s.move(count));
-        this._text = c.repeat(count) + this._text;
+        const padding = stripControlChars(char ?? " ").repeat(count);
+        this._spans = this._spans.map((s) => s.move(padding.length));
+        this._text = padding + this._text;
         return this;
     }
     padRight(count, char) {
-        const c = char ?? " ";
-        this._text += c.repeat(count);
+        this._text += stripControlChars(char ?? " ").repeat(count);
         return this;
     }
     setLength(length) {
@@ -555,7 +566,7 @@ export class RichText {
         // value, so width 0 and a marker wider than the width run the same walk
         // as every other call: what is drawn plus what is kept is `cells` wide.
         const cells = cellCount(width);
-        const marker = cellFit(options?.marker ?? "\u2026", cells);
+        const marker = cellFit(stripControlChars(options?.marker ?? "\u2026"), cells);
         const budget = asCellCol(cells - cellLen(marker));
         if (mode === "right") {
             this._cropRightTo(budget);

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
@@ -91,13 +91,11 @@ export class App {
     mouseHandlers = new Set();
     wheelHandlers = new Set();
     quitKeys;
-    input = new InputParser({
-        key: (press) => this.key(press),
-        mouse: (event) => this.mouse(event),
-    });
+    input;
     settle = () => { };
     constructor(options) {
         this.host = options.host;
+        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;
@@ -383,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/host/index.d.ts

@@ -1,5 +1,5 @@
 export { BrowserTerminalHost } from "./terminal-host.js";
-export type { TerminalHost, TerminalSize, DataHandler, ResizeHandler, ExitHandler, BrowserTerminalHostOptions, XtermTerminal, XtermDisposable, XtermResizeEvent, } from "./terminal-host.js";
+export type { TerminalHost, TerminalSize, DataHandler, InputChunks, ResizeHandler, ExitHandler, BrowserTerminalHostOptions, XtermTerminal, XtermDisposable, XtermResizeEvent, } from "./terminal-host.js";
 export { hostEnvironment } from "./host-environment.js";
 export { App } from "./app.js";
 export type { AppMouseEvent, AppOptions, AppPhase, Wheel } from "./app.js";