@promptctl/rich-js 0.23.0 → 0.24.1

package/dist/host/input.d.ts

@@ -9,17 +9,28 @@
  *
  * [LAW:dataflow-not-control-flow] The same parse pipeline runs for every
  * input chunk: append → consume one event at a time until the buffer can't
- * yield more. The byte's value, not a side-mode, decides which event is
- * emitted. There is no "are we mid-sequence" mode flag — the buffer head
- * carries all the state we need, so a UTF-8 character or an escape sequence
- * split across two chunks is completed by the second.
+ * yield more. The byte's value decides which event is emitted; there is no
+ * "are we mid-sequence" mode flag — the buffer head carries that state, so on
+ * a host whose chunks can split a key, a UTF-8 character or an escape
+ * sequence split across two chunks is completed by the second. What a chunk
+ * end means is the host's `InputChunks`, the one input to the parser that is
+ * not a byte, and it decides only what becomes of an unfinished ESC.
  *
- * Lone-ESC handling: a bare `\x1b` is ambiguous (escape key vs. start of a
- * CSI sequence). When the buffer is drained but ends with a lone ESC, the
- * parser defers emission via setTimeout(0). A next chunk opening with `[` or
- * `O` extends the sequence; any other next chunk emits the ESC as Escape
- * first. `flush()` drains it synchronously.
+ * An unfinished escape sequence is ambiguous: `ESC` alone is the Escape key
+ * or the start of a sequence, and `ESC [` is Alt+[ or the start of a CSI.
+ * Only the host's `InputChunks` and the clock can settle it. On a
+ * `"whole-keys"` host a chunk ends on a key boundary, so an ESC still waiting
+ * at a chunk's end opened nothing: it is Escape, and what followed it is read
+ * again on its own. On a `"split"` host a read can end anywhere, so the
+ * parser holds the unfinished sequence for the escape delay — ncurses'
+ * ESCDELAY, tmux's escape-time — and, when nothing has extended it by then,
+ * settles it by the same whole-keys rule. `ESC ESC` is held too, since the
+ * byte after it decides whether it is Alt on a sequence or one Escape. A held
+ * lone ESC is also settled early by a next chunk that opens with anything but
+ * `[` or `O`, because a busy worker can queue the next key behind it.
+ * `flush()` settles the hold synchronously.
  */
+import type { InputChunks } from "./terminal-host.js";
 /** A key as the terminal reported it: plain data, with no say over who hears it. */
 export interface KeyPress {
     readonly key: string;
@@ -63,18 +74,31 @@ export interface InputSink {
  * one place a program hands names in, rather than binding a key that never fires.
  */
 export declare function parseKeyName(name: string): string;
+/**
+ * How long a `"split"` host's parser waits for the rest of an unfinished
+ * escape sequence before reading it as the keys it already holds. Textual's
+ * ESCAPE_DELAY and vim's `ttimeoutlen` default to the same: long enough for
+ * the rest of a sequence a read split (over ssh, say) to arrive, short
+ * enough that Escape does not feel late.
+ */
+export declare const ESCAPE_DELAY_MS = 100;
 export declare class InputParser {
     private readonly sink;
+    private readonly chunks;
     private buffer;
     private escTimer;
-    constructor(sink: InputSink);
+    constructor(sink: InputSink, chunks: InputChunks);
     /** Feed a chunk of bytes (or a string of them) into the parser. */
     feed(chunk: Uint8Array | string): void;
-    /** Force any pending lone ESC out of the buffer. */
+    private drainAndHold;
+    private hold;
+    private settleChunk;
+    private drainFully;
+    /** Settle a held escape sequence now, as the end of a whole-key chunk. */
     flush(): void;
-    /** Drop what is buffered and any pending lone ESC: the parser as constructed. */
+    /** Drop what is buffered and any held escape sequence: the parser as constructed. */
     reset(): void;
-    /** The parser's one hold: a lone ESC that may yet open a sequence. */
+    /** A lone ESC, the one hold a next chunk can settle before its bytes are read. */
     private holdingEscape;
     private cancelEscape;
     private drain;

package/dist/host/input.js

@@ -9,16 +9,26 @@
  *
  * [LAW:dataflow-not-control-flow] The same parse pipeline runs for every
  * input chunk: append → consume one event at a time until the buffer can't
- * yield more. The byte's value, not a side-mode, decides which event is
- * emitted. There is no "are we mid-sequence" mode flag — the buffer head
- * carries all the state we need, so a UTF-8 character or an escape sequence
- * split across two chunks is completed by the second.
+ * yield more. The byte's value decides which event is emitted; there is no
+ * "are we mid-sequence" mode flag — the buffer head carries that state, so on
+ * a host whose chunks can split a key, a UTF-8 character or an escape
+ * sequence split across two chunks is completed by the second. What a chunk
+ * end means is the host's `InputChunks`, the one input to the parser that is
+ * not a byte, and it decides only what becomes of an unfinished ESC.
  *
- * Lone-ESC handling: a bare `\x1b` is ambiguous (escape key vs. start of a
- * CSI sequence). When the buffer is drained but ends with a lone ESC, the
- * parser defers emission via setTimeout(0). A next chunk opening with `[` or
- * `O` extends the sequence; any other next chunk emits the ESC as Escape
- * first. `flush()` drains it synchronously.
+ * An unfinished escape sequence is ambiguous: `ESC` alone is the Escape key
+ * or the start of a sequence, and `ESC [` is Alt+[ or the start of a CSI.
+ * Only the host's `InputChunks` and the clock can settle it. On a
+ * `"whole-keys"` host a chunk ends on a key boundary, so an ESC still waiting
+ * at a chunk's end opened nothing: it is Escape, and what followed it is read
+ * again on its own. On a `"split"` host a read can end anywhere, so the
+ * parser holds the unfinished sequence for the escape delay — ncurses'
+ * ESCDELAY, tmux's escape-time — and, when nothing has extended it by then,
+ * settles it by the same whole-keys rule. `ESC ESC` is held too, since the
+ * byte after it decides whether it is Alt on a sequence or one Escape. A held
+ * lone ESC is also settled early by a next chunk that opens with anything but
+ * `[` or `O`, because a busy worker can queue the next key behind it.
+ * `flush()` settles the hold synchronously.
  */
 /**
  * The one name a key goes by — what a keymap is keyed by and what
@@ -137,6 +147,14 @@ const UTF8_ENCODER = new TextEncoder();
 const UTF8_DECODER = new TextDecoder("utf-8");
 const ASCII_DECODER = new TextDecoder("ascii");
 const EMPTY_BYTES = new Uint8Array(0);
+/**
+ * How long a `"split"` host's parser waits for the rest of an unfinished
+ * escape sequence before reading it as the keys it already holds. Textual's
+ * ESCAPE_DELAY and vim's `ttimeoutlen` default to the same: long enough for
+ * the rest of a sequence a read split (over ssh, say) to arrive, short
+ * enough that Escape does not feel late.
+ */
+export const ESCAPE_DELAY_MS = 100;
 // Concatenate two byte arrays into a fresh Uint8Array. Replaces
 // `Buffer.concat([...])` so the parser holds no node-specific globals.
 function concatBytes(a, b) {
@@ -149,8 +167,30 @@ function concatBytes(a, b) {
     merged.set(b, a.length);
     return merged;
 }
+// Alt on a printable byte: the glyph the terminal sent, with meta held.
+function altKey(byte) {
+    return { key: String.fromCharCode(byte), character: "", shift: false, ctrl: false, meta: true };
+}
+// ECMA-48: an escape sequence is built of bytes 0x20–0x7E after its ESC, so
+// any other byte (ESC itself, a control, a UTF-8 byte) ends one unfinished.
+function inSequence(byte) {
+    return byte >= 0x20 && byte <= 0x7e;
+}
+// [LAW:one-source-of-truth] An escape sequence that opened no key — ended
+// before its final byte (at a whole-key chunk's end, at the escape delay, or at
+// a byte that cannot belong to it), or an SS3 no terminal sends — is reissued
+// as the keys it holds, as Textual reissues one. `ESC ESC` is one Escape, as a
+// terminal that double-sends it means, whatever followed it; `ESC [` / `ESC O`
+// alone is the whole key Alt+[ / Alt+O; any other ESC is Escape. What followed
+// the Escape is read again on its own.
+function reissue(sequence) {
+    if (sequence[1] === ESC)
+        return { bytes: 2, event: ESCAPE };
+    return sequence.length === 2 ? { bytes: 2, event: altKey(sequence[1]) } : { bytes: 1, event: ESCAPE };
+}
 export class InputParser {
     sink;
+    chunks;
     // [LAW:types-are-the-program] The parse buffer is `Uint8Array`, not
     // `Buffer` — node's Buffer extends Uint8Array, so Buffer chunks from
     // process.stdin satisfy this type, while a browser host can emit native
@@ -159,12 +199,17 @@ export class InputParser {
     // [LAW:types-are-the-program] `setTimeout`/`clearTimeout` are universal
     // across node and browser; `setImmediate` is node-only.
     escTimer;
-    constructor(sink) {
+    constructor(sink, chunks) {
         this.sink = sink;
+        this.chunks = chunks;
     }
     /** Feed a chunk of bytes (or a string of them) into the parser. */
     feed(chunk) {
         const next = typeof chunk === "string" ? UTF8_ENCODER.encode(chunk) : chunk;
+        if (this.chunks === "whole-keys") {
+            this.buffer = concatBytes(this.buffer, next);
+            return this.settleChunk();
+        }
         // A held lone ESC waits only for the rest of a split CSI/SS3 introducer.
         // Any other next chunk means Escape was its own key, even when the hold
         // timer has not run yet: a busy worker can queue the next key ahead of it,
@@ -179,32 +224,77 @@ export class InputParser {
                 this.sink.key(ESCAPE);
         }
         finally {
+            this.drainAndHold();
+        }
+    }
+    drainAndHold() {
+        try {
+            this.drainFully();
+        }
+        finally {
+            this.hold();
+        }
+    }
+    // [LAW:no-ambient-temporal-coupling] Whatever drain leaves at an ESC is an
+    // unfinished sequence, and the escape delay is what tells one whose rest is
+    // still in flight from one that stalled: a stalled `ESC [` held for good
+    // would read the next key as its final byte (rich-host-input-gnl7). The delay
+    // counts time the program could have read the rest in: node runs an expired
+    // timer before it reads input queued behind a long frame, so the delay's end
+    // settles the hold only after one more turn of the event loop has read what
+    // was waiting. The parser holds one timer, so arming it replaces any other.
+    hold() {
+        this.cancelEscape();
+        if (this.buffer[0] !== ESC)
+            return;
+        this.escTimer = setTimeout(() => {
+            this.escTimer = setTimeout(() => this.flush(), 0);
+        }, ESCAPE_DELAY_MS);
+    }
+    // A whole-key chunk has ended, so an ESC still at the buffer head opens no
+    // sequence, and is read as `reissue` reads it. Each key is taken off the
+    // buffer before the sink hears it, so no byte of one chunk outlives it.
+    settleChunk() {
+        try {
+            this.drainFully();
+        }
+        finally {
+            if (this.buffer[0] === ESC) {
+                const { bytes, event } = reissue(this.buffer);
+                this.buffer = this.buffer.subarray(bytes);
+                try {
+                    this.sink.key(event);
+                }
+                finally {
+                    this.settleChunk();
+                }
+            }
+        }
+    }
+    // Drain, and when a handler throws, read the rest of the buffer in full
+    // before the throw goes on, so a throwing handler strands no key behind it.
+    drainFully() {
+        let drained = false;
+        try {
             this.drain();
+            drained = true;
         }
-        // [LAW:dataflow-not-control-flow] If a lone ESC remains, defer emission
-        // until the next macrotask so a follow-up chunk can extend it. Only a lone
-        // one: a sequence split after `ESC [` waits for its rest, however late.
-        if (this.holdingEscape()) {
-            this.escTimer = setTimeout(() => {
-                this.escTimer = undefined;
-                this.flush();
-            }, 0);
+        finally {
+            if (!drained)
+                this.drainFully();
         }
     }
-    /** Force any pending lone ESC out of the buffer. */
+    /** Settle a held escape sequence now, as the end of a whole-key chunk. */
     flush() {
         this.cancelEscape();
-        if (this.holdingEscape()) {
-            this.buffer = EMPTY_BYTES;
-            this.sink.key(ESCAPE);
-        }
+        this.settleChunk();
     }
-    /** Drop what is buffered and any pending lone ESC: the parser as constructed. */
+    /** Drop what is buffered and any held escape sequence: the parser as constructed. */
     reset() {
         this.cancelEscape();
         this.buffer = EMPTY_BYTES;
     }
-    /** The parser's one hold: a lone ESC that may yet open a sequence. */
+    /** A lone ESC, the one hold a next chunk can settle before its bytes are read. */
     holdingEscape() {
         return this.buffer.length === 1 && this.buffer[0] === ESC;
     }
@@ -218,7 +308,7 @@ export class InputParser {
             if (result.kind === "incomplete")
                 return;
             this.buffer = this.buffer.subarray(result.bytes);
-            if (result.kind === "key")
+            if (result.kind === "key" || result.kind === "reissued")
                 this.sink.key(result.event);
             else if (result.kind === "mouse")
                 this.sink.mouse(result.event);
@@ -291,30 +381,28 @@ export class InputParser {
         // ESC O X → SS3 (F1–F4 / arrows on some terms)
         if (b1 === O_BYTE)
             return this.consumeSS3(buf);
-        // ESC ESC [ … / ESC ESC O … → Alt on a key the terminal sends as a
-        // sequence (macOS Terminal and iTerm send Option+Up as `ESC ESC [ A`): the
-        // inner sequence, with meta held.
-        if (b1 === ESC && buf.length > 2 && (buf[2] === LBRACKET || buf[2] === O_BYTE)) {
-            // A pointer report is never Alt-prefixed (SGR carries modifiers in its
-            // button byte), so before anything but a key the first ESC is Escape.
-            const inner = this.consumeEscape(buf.subarray(1));
-            if (inner.kind === "incomplete")
-                return inner;
-            if (inner.kind === "key") {
-                return { kind: "key", bytes: inner.bytes + 1, event: { ...inner.event, meta: true } };
-            }
-            return { kind: "key", bytes: 1, event: ESCAPE };
-        }
-        // ESC ESC → escape key (some terminals double-send). Consume BOTH bytes
-        // so the user sees one escape event, not two. Without this, the second
-        // ESC remained in the buffer and produced a second escape via the
-        // lone-ESC flush path.
         if (b1 === ESC) {
-            return {
-                kind: "key",
-                bytes: 2,
-                event: ESCAPE,
-            };
+            // The byte after `ESC ESC` decides what it opens, so a read that ends
+            // between them leaves it unfinished, held like any other.
+            if (buf.length === 2)
+                return { kind: "incomplete" };
+            // ESC ESC [ … / ESC ESC O … → Alt on a key the terminal sends as a
+            // sequence (macOS Terminal and iTerm send Option+Up as `ESC ESC [ A`):
+            // the inner sequence, with meta held.
+            if (buf[2] === LBRACKET || buf[2] === O_BYTE) {
+                const inner = this.consumeEscape(buf.subarray(1));
+                if (inner.kind === "incomplete")
+                    return inner;
+                if (inner.kind === "key") {
+                    return { kind: "key", bytes: inner.bytes + 1, event: { ...inner.event, meta: true } };
+                }
+                // A pointer report is never Alt-prefixed (SGR carries modifiers in its
+                // button byte): the second ESC is the report's, and the first is Escape.
+                if (inner.kind !== "reissued")
+                    return { kind: "key", bytes: 1, event: ESCAPE };
+            }
+            // `ESC ESC` before a byte that opens no key opened none itself.
+            return { kind: "reissued", ...reissue(buf) };
         }
         // ESC <named> / ESC <printable> → Alt-modified key.
         // Terminals encode Alt+<key> as the literal byte preceded by ESC, so
@@ -352,12 +440,7 @@ export class InputParser {
         // The key is the glyph the terminal sent, as for Alt+`>`: the glyph
         // already carries shift, so Alt+G is `meta+G` and never `meta+shift+g`.
         if (b1 >= 0x20 && b1 <= 0x7e) {
-            const ch = String.fromCharCode(b1);
-            return {
-                kind: "key",
-                bytes: 2,
-                event: ({ key: ch, character: "", shift: false, ctrl: false, meta: true }),
-            };
+            return { kind: "key", bytes: 2, event: altKey(b1) };
         }
         // ESC <control byte> is read as Escape, then the Ctrl chord — never as
         // Alt+Ctrl. The bytes cannot tell the two apart, and Escape then Ctrl+C
@@ -372,10 +455,13 @@ export class InputParser {
     consumeSS3(buf) {
         if (buf.length < 3)
             return { kind: "incomplete" };
+        if (!inSequence(buf[2]))
+            return { kind: "reissued", ...reissue(buf.subarray(0, 2)) };
         const final = String.fromCharCode(buf[2]);
         const name = SS3_KEYS[final];
+        // No terminal reports in SS3, so an unknown final was typed: Escape, then O.
         if (!name)
-            return { kind: "skip", bytes: 3 };
+            return { kind: "reissued", ...reissue(buf.subarray(0, 3)) };
         return {
             kind: "key",
             bytes: 3,
@@ -418,6 +504,8 @@ export class InputParser {
                         event: decodeMouseFromCb(cb, col, row, b === M_UPPER),
                     };
                 }
+                if (!inSequence(b))
+                    return { kind: "reissued", ...reissue(buf.subarray(0, i)) };
             }
             return { kind: "incomplete" };
         }
@@ -430,6 +518,8 @@ export class InputParser {
                 const final = String.fromCharCode(b);
                 return decodeCSI(params, final, i + 1);
             }
+            if (!inSequence(b))
+                return { kind: "reissued", ...reissue(buf.subarray(0, i)) };
             params += String.fromCharCode(b);
         }
         return { kind: "incomplete" };

package/dist/host/terminal-host.d.ts

@@ -43,6 +43,13 @@ export interface TerminalSize {
     readonly rows: number;
 }
 export type DataHandler = (chunk: Uint8Array | string) => void;
+/**
+ * Where a host's input chunks may end. `"whole-keys"`: every chunk ends on a
+ * key boundary, so no escape sequence is ever split across two (xterm.js
+ * emits one key, or one paste, per event). `"split"`: a chunk may end
+ * anywhere, as a read from a tty can.
+ */
+export type InputChunks = "whole-keys" | "split";
 export type ResizeHandler = (size: TerminalSize) => void;
 export type ExitHandler = () => void;
 export interface TerminalHost {
@@ -60,6 +67,14 @@ export interface TerminalHost {
      * runtime's parser accepts either.
      */
     onData(handler: DataHandler): Unsubscribe;
+    /**
+     * Where `onData`'s chunks may end. The parser holds an unfinished escape
+     * sequence open for its rest, for the escape delay, only on a host whose
+     * chunks can split one; a whole-keys host settles each chunk as it arrives,
+     * because a busy worker there reads a queued next key before any timer
+     * runs (rich-host-input-ab9n).
+     */
+    readonly inputChunks: InputChunks;
     /**
      * Subscribe to terminal resize events. The handler fires with the new
      * size after a resize is observed.
@@ -176,6 +191,7 @@ export declare class BrowserTerminalHost implements TerminalHost {
     private dataSubscription;
     private resizeSubscription;
     readonly passWheel: (lines: number) => void;
+    readonly inputChunks = "whole-keys";
     constructor(options: BrowserTerminalHostOptions);
     get isTTY(): boolean;
     get writesToTerminal(): boolean;

package/dist/host/terminal-host.js

@@ -47,6 +47,7 @@ export class BrowserTerminalHost {
     dataSubscription;
     resizeSubscription;
     passWheel;
+    inputChunks = "whole-keys";
     constructor(options) {
         this.terminal = options.terminal;
         this.passWheel = options.passWheel;

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, cubicBezier, parseEase, steps } from "./core/easing.js";
-export type { 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,14 +30,14 @@ 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";
 export type { RichTextOptions } from "./core/text.js";
-export { Strip, CellJoiner, SEAM_MIN_DELTA_E, JOINERS, joinerNamed, gradientJoiner, } from "./core/strip.js";
-export type { StyledRenderable, Joiner, JoinContext, JoinShape, JoinCell, CellColor, Paint } from "./core/strip.js";
+export { Strip, CellJoiner, SEAM_MIN_DELTA_E, SEAMS, CAPS, JOINERS, joinerNamed, gradientSeam, } from "./core/strip.js";
+export type { StyledRenderable, Joiner, JoinContext, JoinSeam, JoinCaps, SeamForm, CapsForm, SeamCell, JoinCell, CellColor, Paint, JoinerSpec, } from "./core/strip.js";
 export { renderToString, segmentToString, segmentsToString, } from "./core/render.js";
 export type { RenderToStringOptions } from "./core/render.js";
 export { OSC8, osc8Sequences } from "./core/osc8.js";
@@ -55,10 +58,10 @@ 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 } from "./renderables/effect.js";
-export type { CellColors, Drawn, Effect, EffectCell, EffectedOptions, Pair } from "./renderables/effect.js";
-export { EFFECT_CATALOGUE, EFFECT_CURVES, EFFECT_LIGHTS, dissolveOut, fadeIn, onColors, pulse, shimmer, sparkle, wheel, } from "./renderables/effects.js";
-export type { Curve, EffectTarget, Field, Loop, LoopName, Touch, Transition, TransitionName } from "./renderables/effects.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";
 export type { Alignment } from "./core/place.js";
 export { Padding } from "./renderables/padding.js";
@@ -77,6 +80,8 @@ 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, 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";
 export { Tree } from "./renderables/tree.js";
@@ -86,7 +91,7 @@ export type { ColumnsOptions } from "./renderables/columns.js";
 export { FlexStrip } from "./renderables/flexStrip.js";
 export type { FlexStripOptions, FlexAlign } from "./renderables/flexStrip.js";
 export { Live } from "./renderables/live.js";
-export type { LiveOptions } from "./renderables/live.js";
+export type { LiveOptions, LiveView } from "./renderables/live.js";
 export { Status } from "./renderables/status.js";
 export type { StatusOptions } from "./renderables/status.js";
 export { Progress, TextColumn, BarColumn, TaskProgressColumn, TimeRemainingColumn, TimeElapsedColumn, SpinnerColumn, MofNCompleteColumn, track, } from "./renderables/progress.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, 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,13 +47,13 @@ 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
 export { Span, RichText } from "./core/text.js";
 // Strip + Joiner
-export { Strip, CellJoiner, SEAM_MIN_DELTA_E, JOINERS, joinerNamed, gradientJoiner, } from "./core/strip.js";
+export { Strip, CellJoiner, SEAM_MIN_DELTA_E, SEAMS, CAPS, JOINERS, joinerNamed, gradientSeam, } from "./core/strip.js";
 // renderToString — stateless one-shot emission
 export { renderToString, segmentToString, segmentsToString, } from "./core/render.js";
 // OSC 8 hyperlink wire grammar — for consumers that read rendered bytes back
@@ -69,8 +78,8 @@ 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 } from "./renderables/effect.js";
-export { EFFECT_CATALOGUE, EFFECT_CURVES, EFFECT_LIGHTS, dissolveOut, fadeIn, onColors, pulse, shimmer, sparkle, wheel, } from "./renderables/effects.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";
 export { Viewport, ViewportPerKey, SCROLLBAR } from "./renderables/viewport.js";
@@ -81,6 +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, 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/node/terminal-host.d.ts

@@ -27,7 +27,7 @@
  * `setRawMode` in the runtime or in a demo, take a `TerminalHost` parameter
  * instead. The seam is already here.
  */
-import type { DataHandler, ExitHandler, ResizeHandler, TerminalHost, TerminalSize } from "../host/terminal-host.js";
+import type { DataHandler, ExitHandler, InputChunks, ResizeHandler, TerminalHost, TerminalSize } from "../host/terminal-host.js";
 import type { Unsubscribe } from "../core/subscription.js";
 import type { Env } from "../core/env.js";
 /**
@@ -42,6 +42,12 @@ interface NodeReadable {
     resume?(): unknown;
     pause?(): unknown;
     readonly isTTY?: boolean;
+    /**
+     * Set by a stream that delivers whole keys — the docs site's simulated
+     * stdin forwards xterm.js's events one to one. Node's own stdin is a tty
+     * read and sets nothing, so it is `"split"`.
+     */
+    readonly inputChunks?: InputChunks;
 }
 interface NodeWritable {
     write(chunk: string | Uint8Array): unknown;
@@ -98,6 +104,7 @@ export declare class NodeTerminalHost implements TerminalHost {
     private readonly stdout;
     private readonly process;
     readonly env: Env;
+    readonly inputChunks: InputChunks;
     private readonly dataHandlers;
     private readonly resizeHandlers;
     private dataListener;

package/dist/node/terminal-host.js

@@ -45,6 +45,7 @@ export class NodeTerminalHost {
     stdout;
     process;
     env;
+    inputChunks;
     dataHandlers = new Set();
     resizeHandlers = new Set();
     dataListener;
@@ -55,6 +56,7 @@ export class NodeTerminalHost {
         this.stdout = options.stdout ?? process.stdout;
         this.env = options.env ?? process.env;
         this.process = options.process ?? process;
+        this.inputChunks = this.stdin.inputChunks ?? "split";
     }
     get isTTY() {
         return !!this.stdin.isTTY && this.writesToTerminal;

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;