@promptctl/rich-js 0.24.0 → 0.25.0

package/dist/host/app.js

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

package/dist/host/input.js

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

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export { cellLen, setCellSize, splitText, chopCells, cellFit, graphemes, asCellCol, asCodePoint, } from "./core/cells.js";
 export type { CellCol, CodeUnit, CodePoint } from "./core/cells.js";
 export { ColorRgba, ColorTable, ColorDepth, ColorSpec, ColorParseError, TerminalTheme, parseRgbHex, parseRgbaHex, parseHexColor, blendRgb, resolveColorSystem, detectColorSystem, resolveDestination, STANDARD_TABLE, EIGHT_BIT_TABLE, WINDOWS_TABLE, ANSI_COLOR_NAMES, } from "./core/color.js";
-export type { ColorSystemName, DetectColorOptions, Destination } from "./core/color.js";
+export type { ColorSystemName, DetectColorOptions, Destination, DestinationOptions } from "./core/color.js";
 export { Oklch, IDENTITY, INVERT_LIGHTNESS, isIdentityKey, } from "./core/oklch.js";
 export type { ThemeKey, OklchWeights } from "./core/oklch.js";
 export { Palette } from "./themes/palette.js";
@@ -14,21 +14,26 @@ export type { ThemeName } from "./themes/registry.js";
 export { transposePalette, themeKeyForRoot, isAnchored, ANCHORED_ROOTS, } from "./themes/transpose.js";
 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 type { ColorStop, RampMotion } from "./themes/ramp.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 type { Timed } from "./core/animation.js";
+export { tween } from "./core/tween.js";
+export { Timeline } from "./core/timeline.js";
+export type { View } from "./core/view.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";
-export type { StyleOptions, TextStyle, LayeredStyle } from "./core/style.js";
+export type { Attributes, Hold, StyleOptions, TextStyle, LayeredStyle } from "./core/style.js";
 export { Segment, ControlType, } from "./core/segment.js";
 export type { ControlCode } from "./core/segment.js";
 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, Presence, StyleErrorHandler, FrameHost, } 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,10 +60,20 @@ 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 { 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 { Effected, confined, drawnOf } from "./renderables/effect.js";
+export type { CellAttributes, CellColors, CellLook, Drawn, Effect, EffectCell, EffectedOptions, EffectFrame, Pair, Placed } from "./renderables/effect.js";
+export { ATTRIBUTE_DEFAULTS, EFFECT_CATALOGUE, EFFECT_CURVES, EFFECT_LIGHTS, blink, dissolveOut, fadeIn, gradient, onBeat, onColors, pulse, shimmer, sparkle, steppedInk, wheel, } from "./renderables/effects.js";
+export type { AttributeLoopName, Blink, ColorStep, Curve, EffectTarget, Field, Loop, LoopName, Touch, Transition, TransitionName } from "./renderables/effects.js";
+export { crossfade, wipe } from "./renderables/change.js";
+export type { Between, Change } from "./renderables/change.js";
+export { lifecycle, throughColors, throughGlyphs } from "./renderables/lifecycle.js";
+export type { Lifecycle, LifecycleOptions, Veil } from "./renderables/lifecycle.js";
+export { scroll } from "./renderables/scroll.js";
+export type { ScrollOptions } from "./renderables/scroll.js";
+export { GlyphEffected } from "./renderables/glyph-effect.js";
+export type { DrawnGlyphs, GlyphCell, GlyphEffect, GlyphEffectedOptions, GlyphFrame } from "./renderables/glyph-effect.js";
+export { GLYPH_DEFAULTS, GLYPH_EFFECT_CATALOGUE, backspace, caseWave, particles, scramble, scrambleOut, typewriter } from "./renderables/glyph-effects.js";
+export type { CaseWave, GlyphLoopName, GlyphTransition, GlyphTransitionName, Particles } from "./renderables/glyph-effects.js";
 export { Align } from "./renderables/align.js";
 export type { Alignment } from "./core/place.js";
 export { Padding } from "./renderables/padding.js";
@@ -77,9 +92,9 @@ 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 type { Frame, FramesOptions } from "./renderables/frames.js";
-export { Table, Column } from "./renderables/table.js";
+export { FrameSequence } from "./renderables/frames.js";
+export type { Frame } from "./renderables/frames.js";
+export { Table, type Column } from "./renderables/table.js";
 export type { TableOptions, ColumnOptions } from "./renderables/table.js";
 export { Tree } from "./renderables/tree.js";
 export type { TreeOptions } from "./renderables/tree.js";
@@ -88,7 +103,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, LiveView } from "./renderables/live.js";
+export type { LiveOptions } 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, 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,8 +78,13 @@ 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 { EFFECT_CATALOGUE, EFFECT_CURVES, EFFECT_LIGHTS, dissolveOut, fadeIn, onColors, pulse, shimmer, sparkle, steppedInk, wheel, } from "./renderables/effects.js";
+export { Effected, confined, drawnOf } from "./renderables/effect.js";
+export { ATTRIBUTE_DEFAULTS, EFFECT_CATALOGUE, EFFECT_CURVES, EFFECT_LIGHTS, blink, dissolveOut, fadeIn, gradient, onBeat, onColors, pulse, shimmer, sparkle, steppedInk, wheel, } from "./renderables/effects.js";
+export { crossfade, wipe } from "./renderables/change.js";
+export { lifecycle, throughColors, throughGlyphs } from "./renderables/lifecycle.js";
+export { scroll } from "./renderables/scroll.js";
+export { GlyphEffected } from "./renderables/glyph-effect.js";
+export { GLYPH_DEFAULTS, GLYPH_EFFECT_CATALOGUE, backspace, caseWave, particles, scramble, scrambleOut, typewriter } from "./renderables/glyph-effects.js";
 export { Align } from "./renderables/align.js";
 export { Padding } from "./renderables/padding.js";
 export { Viewport, ViewportPerKey, SCROLLBAR } from "./renderables/viewport.js";
@@ -81,8 +95,8 @@ 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 { Table, Column } from "./renderables/table.js";
+export { FrameSequence } from "./renderables/frames.js";
+export { Table } from "./renderables/table.js";
 export { Tree } from "./renderables/tree.js";
 export { Columns } from "./renderables/columns.js";
 export { FlexStrip } from "./renderables/flexStrip.js";

package/dist/node/traceback.js

@@ -29,6 +29,7 @@
  */
 import { Console } from "../core/console.js";
 import { Traceback } from "../renderables/traceback.js";
+import { State } from "../core/state.js";
 /**
  * The handler currently registered, or a no-op standing in for "none yet".
  *
@@ -41,7 +42,7 @@ import { Traceback } from "../renderables/traceback.js";
  * unregistered listener does nothing, so the first call needs no null check
  * and no "have we installed yet" branch. There is no absent case to handle.
  */
-let installed = () => { };
+const installed = new State(() => { });
 /**
  * An unhandled rejection, raised as the uncaught exception it becomes when
  * nobody listens — its reason unwrapped, which node's own conversion would
@@ -90,9 +91,9 @@ export function installTraceback(options) {
             process.exit(1);
         });
     };
-    process.off("uncaughtException", installed);
+    process.off("uncaughtException", installed.get());
     process.off("unhandledRejection", escalate);
     process.on("uncaughtException", report);
     process.on("unhandledRejection", escalate);
-    installed = report;
+    installed.set(report);
 }

package/dist/renderables/change.d.ts

@@ -0,0 +1,42 @@
+/**
+ * A change from one renderable to another in the same slot — a status that
+ * goes from "building" to "done", a number that becomes a different number —
+ * drawn as a crossfade or a wipe instead of a cut.
+ *
+ * Both are one shape [LAW:one-type-per-behavior]: how far each cell is through
+ * the change at `t`, from 0, the old renderable as drawn, to 1, the new one as
+ * drawn. A cell under a half shows the old one and from a half the new one,
+ * veiled toward the terminal's ground by how near the half it is (`veiled`,
+ * `./effects.ts`), so every cell passes through the ground and none jumps from
+ * one glyph to another. A crossfade has every cell at one place in the change;
+ * a wipe sends a front across the element's columns with the new renderable
+ * behind it.
+ *
+ * The change is drawn at the new renderable's size from its first frame: the
+ * old one is cut or padded to the new one's rows, so what sits beside the
+ * element moves once, at the cut, and never while the change runs. Once done
+ * it is the new renderable itself, byte for byte, and never changes again.
+ *
+ * [LAW:no-ambient-temporal-coupling] Pure in `t`: nothing is kept from one
+ * frame to the next, so the same `t` draws the same bytes at any frame rate.
+ */
+import { Animation } from "../core/animation.js";
+import type { TerminalTheme } from "../core/color.js";
+import type { Renderable } from "../core/protocol.js";
+import { type Curve, type Transition } from "./effects.js";
+/** What a change is between: the renderable drawn until now, the one drawn from now on, and the terminal whose ground the change passes through. */
+export interface Between {
+    readonly from: Renderable;
+    readonly to: Renderable;
+    readonly theme: TerminalTheme;
+}
+/** A change from one renderable to another: what it draws at each moment, from `t = 0` on its own clock. */
+export type Change = (between: Between) => Animation<Renderable>;
+/** A crossfade: the old renderable fades to the terminal's ground and the new one rises from it, every cell together, over `curve`. */
+export declare function crossfade(curve: Curve): Transition<Change>;
+/**
+ * A wipe: a front crossing the element's columns from left to right over
+ * `curve`, the new renderable behind it, the old one ahead of it, and the
+ * cells within `edge` columns of it passing through the terminal's ground.
+ */
+export declare function wipe(curve: Curve, edge?: number): Transition<Change>;

package/dist/renderables/change.js

@@ -0,0 +1,112 @@
+/**
+ * A change from one renderable to another in the same slot — a status that
+ * goes from "building" to "done", a number that becomes a different number —
+ * drawn as a crossfade or a wipe instead of a cut.
+ *
+ * Both are one shape [LAW:one-type-per-behavior]: how far each cell is through
+ * the change at `t`, from 0, the old renderable as drawn, to 1, the new one as
+ * drawn. A cell under a half shows the old one and from a half the new one,
+ * veiled toward the terminal's ground by how near the half it is (`veiled`,
+ * `./effects.ts`), so every cell passes through the ground and none jumps from
+ * one glyph to another. A crossfade has every cell at one place in the change;
+ * a wipe sends a front across the element's columns with the new renderable
+ * behind it.
+ *
+ * The change is drawn at the new renderable's size from its first frame: the
+ * old one is cut or padded to the new one's rows, so what sits beside the
+ * element moves once, at the cut, and never while the change runs. Once done
+ * it is the new renderable itself, byte for byte, and never changes again.
+ *
+ * [LAW:no-ambient-temporal-coupling] Pure in `t`: nothing is kept from one
+ * frame to the next, so the same `t` draws the same bytes at any frame rate.
+ */
+import { Animation } from "../core/animation.js";
+import { Measurement } from "../core/measure.js";
+import { render } from "../core/protocol.js";
+import { Segment } from "../core/segment.js";
+import { Recolored } from "./effect.js";
+import { requireCurve, transition, veiled } from "./effects.js";
+const clamp01 = (x) => Math.min(1, Math.max(0, x));
+/** How much of a cell `p` of the way through a change shows: all of it at either end, none at the half, where the old gives way to the new. */
+const shows = (p) => Math.abs(2 * p - 1);
+/** The change over `curve`, each cell as far through it as `progress` says. */
+function change(curve, progress) {
+    requireCurve(curve);
+    return transition(curve.seconds, ({ from, to, theme }) => Animation.sequence(Animation.continuous((t) => new ChangeFrame(from, to, theme, progress, t, curve.swing)), curve.seconds, Animation.constant(to)));
+}
+/** A crossfade: the old renderable fades to the terminal's ground and the new one rises from it, every cell together, over `curve`. */
+export function crossfade(curve) {
+    return change(curve, (t) => {
+        const p = clamp01(curve.ease(clamp01(t / curve.seconds)));
+        return () => p;
+    });
+}
+/** How many columns a wipe's front is soft over at its default: each cell passes through the ground as the front crosses it. */
+const WIPE_EDGE = 6;
+/**
+ * A wipe: a front crossing the element's columns from left to right over
+ * `curve`, the new renderable behind it, the old one ahead of it, and the
+ * cells within `edge` columns of it passing through the terminal's ground.
+ */
+export function wipe(curve, edge = WIPE_EDGE) {
+    if (!(Number.isFinite(edge) && edge > 0))
+        throw new RangeError(`wipe: edge must be a positive number of columns, got ${edge}`);
+    return change(curve, (t, width) => {
+        // The front starts `edge` columns before the first cell turns and ends with the last one turned.
+        const front = curve.ease(clamp01(t / curve.seconds)) * (width + edge);
+        return (_row, col) => clamp01((front - col) / edge);
+    });
+}
+/** One frame of a change at `t`: `from` and `to` spliced cell by cell, each veiled by how near the half its cell is. */
+class ChangeFrame {
+    from;
+    to;
+    theme;
+    progress;
+    t;
+    swing;
+    constructor(from, to, theme, progress, t, swing) {
+        this.from = from;
+        this.to = to;
+        this.theme = theme;
+        this.progress = progress;
+        this.t = t;
+        this.swing = swing;
+    }
+    render(options) {
+        const before = Segment.splitLines(render(this.from, options));
+        const drawn = [...render(this.to, options)];
+        const after = Segment.splitLines(drawn);
+        // [LAW:one-source-of-truth] The new renderable's rows are the shape of every frame, its last row ending as it ends.
+        const lengths = after.map((line) => Segment.getLineLength(line));
+        const ended = drawn.filter((segment) => !segment.isControl).at(-1)?.text.endsWith("\n") ?? false;
+        const width = Math.max(0, ...lengths);
+        const at = this.progress(this.t, width);
+        const rows = after.flatMap((line, row) => [
+            ...splice(Segment.adjustLineLength(before[row] ?? [], lengths[row]), line, (col) => at(row, col) >= 0.5),
+            ...(row < after.length - 1 || ended ? [Segment.line()] : []),
+        ]);
+        // The frame says nothing of when it changes: the change's own animation says it moves every frame.
+        const veil = veiled(() => (cell) => shows(at(cell.row, cell.col)), this.swing);
+        return render(new Recolored({ render: () => rows }, veil, { t: this.t, key: "change", theme: this.theme }), options);
+    }
+    measure(options) {
+        return Measurement.get(options, this.to);
+    }
+}
+/**
+ * One row from two of the same width, each column from `after` where `isAfter`
+ * says and from `before` elsewhere. Cut at every column the side changes, so
+ * a wide glyph a cut falls in is blanked (`Segment.divide`), never halved.
+ */
+function splice(before, after, isAfter) {
+    const width = Segment.getLineLength(after);
+    const cuts = [];
+    for (let col = 1; col < width; col++)
+        if (isAfter(col) !== isAfter(col - 1))
+            cuts.push(col);
+    const from = Segment.divide(before, cuts);
+    const to = Segment.divide(after, cuts);
+    const starts = [0, ...cuts];
+    return starts.flatMap((start, i) => (isAfter(start) ? (to[i] ?? []) : (from[i] ?? [])));
+}

package/dist/renderables/columns.d.ts

@@ -19,7 +19,7 @@ export interface ColumnsOptions {
     columnFirst?: boolean;
 }
 export declare class Columns implements Renderable, Measurable {
-    renderables: (Renderable & Partial<Measurable>)[];
+    readonly renderables: readonly (Renderable & Partial<Measurable>)[];
     readonly expand: boolean;
     readonly equal: boolean;
     readonly colWidth: number | undefined;

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 { measure, 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,7 @@ 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);
     }
     measure(rawOptions) {
         // The maximum is the grid's, which reports its width before `expand`: a
@@ -84,7 +84,7 @@ export class Columns {
         const parsed = withCellWidth(rawOptions);
         if (this.renderables.length === 0)
             return { minimum: 0, maximum: 0 };
-        const { maximum } = this._grid(parsed).measure(parsed);
+        const { maximum } = measure(this._grid(parsed), parsed);
         return { minimum: Math.min(1, maximum), maximum };
     }
     /**

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,7 @@ export class Constrain {
             ...options,
             maxWidth: constrainedWidth,
         };
-        yield* this.renderable.render(innerOptions);
+        yield* render(this.renderable, innerOptions);
     }
     measure(options) {
         // Measured at the width it will be drawn at, as Rich's `update_width` does;