@promptctl/rich-js 0.24.1 → 0.25.1

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,16 +14,18 @@ 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 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";
@@ -31,7 +33,7 @@ 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 { 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 { 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";
@@ -58,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, 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 { 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";
@@ -80,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, frameAt } 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";
@@ -91,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

@@ -78,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, 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 { 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";
@@ -90,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, frameAt } 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/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 { Composite, Renderable, Measurable, RenderOptions } from "../core/protocol.js";
+import type { Renderable, Measurable, RenderOptions } from "../core/protocol.js";
 import { type Alignment } from "../core/place.js";
-export declare class Align implements Renderable, Measurable, Composite {
+export declare class Align implements Renderable, Measurable {
     readonly renderable: Renderable;
     readonly align: Alignment;
     constructor(renderable: Renderable, align?: Alignment);
@@ -13,5 +13,4 @@ export declare class Align implements Renderable, Measurable, Composite {
         minimum: number;
         maximum: number;
     };
-    contents(): Iterable<Renderable>;
 }

package/dist/renderables/align.js

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

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

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

package/dist/renderables/columns.js

@@ -10,7 +10,7 @@
  */
 import { Measurement } from "../core/measure.js";
 import { normalizePadding } from "./padding.js";
-import { render, 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";
@@ -70,11 +70,6 @@ export class Columns {
         const options = withBoundedWidth(rawOptions, this);
         yield* render(this._grid(options), options);
     }
-    // The items, in the order they were given. Laid out column-first, the grid
-    // draws them in an order its width decides, and handed no column it has none.
-    contents() {
-        return this.renderables;
-    }
     measure(rawOptions) {
         // The maximum is the grid's, which reports its width before `expand`: a
         // stretch is what a Columns does with a width it is given, not a width it
@@ -89,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.d.ts

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

package/dist/renderables/constrain.js

@@ -21,9 +21,6 @@ export class Constrain {
         };
         yield* render(this.renderable, innerOptions);
     }
-    *contents() {
-        yield this.renderable;
-    }
     measure(options) {
         // Measured at the width it will be drawn at, as Rich's `update_width` does;
         // `Measurement.get` then holds the answer inside that offer.