@promptctl/rich-js 0.23.0 → 0.24.0

package/dist/renderables/embed.d.ts

@@ -82,6 +82,16 @@ export declare class InlineLabel {
      */
     text(options: RenderOptions, base?: TextStyle): RichText;
 }
+/**
+ * `text`, changed in place into a fragment of a line it shares, as Rich's
+ * `_title` reads one: its own end is not drawn, newlines become spaces so it
+ * stays on its line, and tabs are widened to their stops before anything
+ * measures it, so a cut to a border and the width a label asks for count
+ * the cells it will draw. [LAW:single-enforcer] The one reading of "set into
+ * a line", for a label read through the crossing above and for text a
+ * caller hands over already read (`Frames`).
+ */
+export declare function setIntoLine(text: RichText): RichText;
 /**
  * A label cut to `width` cells as Rich's `Text.truncate` cuts one: its plain
  * text set to the width less `marker` — a wide character the cut splits leaves

package/dist/renderables/embed.js

@@ -114,15 +114,23 @@ export class InlineLabel {
      * caller's cut. A string reads with `base` as its style, as `EmbeddedText.text` reads one.
      */
     text(options, base) {
-        const text = this._content.text(options, base);
-        // A fragment of the line, so its own end is not drawn, as Rich's `_title` clears it.
-        text.end = "";
-        text.plain = text.plain.replaceAll("\n", " ");
-        // Tabs widened before anything measures it, so a cut to the border and
-        // the width a title asks for count the cells the label will draw.
-        return text.expandTabs();
+        return setIntoLine(this._content.text(options, base));
     }
 }
+/**
+ * `text`, changed in place into a fragment of a line it shares, as Rich's
+ * `_title` reads one: its own end is not drawn, newlines become spaces so it
+ * stays on its line, and tabs are widened to their stops before anything
+ * measures it, so a cut to a border and the width a label asks for count
+ * the cells it will draw. [LAW:single-enforcer] The one reading of "set into
+ * a line", for a label read through the crossing above and for text a
+ * caller hands over already read (`Frames`).
+ */
+export function setIntoLine(text) {
+    text.end = "";
+    text.plain = text.plain.replaceAll("\n", " ");
+    return text.expandTabs();
+}
 /**
  * A label cut to `width` cells as Rich's `Text.truncate` cuts one: its plain
  * text set to the width less `marker` — a wide character the cut splits leaves

package/dist/renderables/frames.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Frames — content that changes on a beat: a sequence of frames, each held
+ * for its own seconds and looping, drawn as the one in progress at a time
+ * the host hands in.
+ *
+ * An effect moves a cell's colours and may never change a glyph
+ * (`./effect.ts`: "It changes how cells look, never which cells exist or who
+ * drew them"). A frame is the other kind of motion — what the element shows
+ * changes — so it is its own primitive and not a wider `Effect`, and the two
+ * compose by nesting: `new Effected(new Frames(…), …)` lights whichever frame
+ * is up.
+ *
+ * [LAW:no-ambient-temporal-coupling] `t` is an argument, as
+ * `Effected`'s is, never a clock read: whoever draws frames hands each one
+ * its time (`core/clock.ts`), so the same `t` draws the same bytes at one
+ * redraw a second or sixty. The host's rate is the host's. At sixty a frame
+ * shows for exactly its hold; at one a second a hold shorter than a second is
+ * skipped and a period of whole seconds freezes on one frame, and nothing
+ * here adapts to that — the beat is `core/easing.ts`'s, the one timing
+ * vocabulary, and a draw costs the same at `t = 0` and `t = 10⁶`.
+ *
+ * The sequence and the moment are two values, because only one of them
+ * changes from frame to frame. A `FrameSequence` is the frames prepared once
+ * — the beat, the one width, each frame set into a line and padded — and a
+ * `Frames` is that sequence at a `t`, whose work is one frame's — finding
+ * which, and copying it: a host holds the sequence and asks it for a frame,
+ * as `Spinner` holds its two, so a draw costs the same over ninety frames as
+ * over one. The sequence is a value the host keeps, not a memo here: nothing
+ * is looked up by key.
+ *
+ * The frame drawn is drawn until the next begins, and its cells say so: they
+ * are stamped with that moment (`Style.nextChange`), which rides up through
+ * every container to whoever holds the composed frame (`Segment.nextChange`),
+ * so a host drawing at `t` knows when to draw again, and one drawing slower
+ * than the frames turn can see that it is skipping them.
+ *
+ * Every frame is drawn at one width, the widest frame's, each padded on the
+ * right to it, so whatever sits beside the frames never moves as they turn;
+ * and the frame is a fragment of a line (`setIntoLine`), ending no line of
+ * its own, so it sits among other cells. Frames are `RichText`, each free to
+ * carry its own style, and read once, here: markup is a string's reading
+ * under the console that draws it, which a frame handed to a template
+ * binding has no console for, so the frame arrives read, as a `Group`'s
+ * children do.
+ */
+import { type Beat } from "../core/easing.js";
+import type { Measurable, Renderable, RenderOptions } from "../core/protocol.js";
+import type { Segment } from "../core/segment.js";
+import type { RichText } from "../core/text.js";
+/** One frame: what it shows, and how long it is held, in seconds. */
+export interface Frame {
+    readonly text: RichText;
+    readonly seconds: number;
+}
+/** A sequence of frames prepared to be drawn: built once, asked for the frame at a time. */
+export declare class FrameSequence {
+    /** Which frame is in progress when: the holds are the frames' seconds, in order. */
+    readonly beat: Beat;
+    /** The width every frame draws at: the widest frame's, in cells. */
+    readonly width: number;
+    private readonly _shown;
+    constructor(frames: readonly Frame[]);
+    /**
+     * The frame in progress at `t`, at `width` cells, ending no line: a copy,
+     * the caller's to change, its every cell — padding included — stamped with
+     * when it gives way to the next, `beat.end(t)`, so a blank frame among
+     * drawn ones still turns. [LAW:one-source-of-truth] The stamp is the one
+     * answer to when the frame changes, read off the cells
+     * (`Segment.nextChange`): a sequence of nothing has no cell to carry one,
+     * and a field saying a time would disagree with cells saying never.
+     * `beat.at` refuses a `t` that is not finite.
+     */
+    text(t: number): RichText;
+}
+export interface FramesOptions {
+    /** The moment to draw, in seconds. */
+    readonly t: number;
+}
+/** A sequence's frame in progress at one moment, as a renderable. */
+export declare class Frames implements Renderable, Measurable {
+    readonly sequence: FrameSequence;
+    readonly t: number;
+    private readonly _shown;
+    constructor(sequence: FrameSequence, options: FramesOptions);
+    render(options: RenderOptions): Iterable<Segment>;
+    /**
+     * One width both ways: a frame is one picture, never wrapped apart at a
+     * space or narrowed as the frames turn. Fitting it to the room is
+     * `Measurement.get`'s, as for every measurable.
+     */
+    measure(): {
+        minimum: number;
+        maximum: number;
+    };
+}

package/dist/renderables/frames.js

@@ -0,0 +1,106 @@
+/**
+ * Frames — content that changes on a beat: a sequence of frames, each held
+ * for its own seconds and looping, drawn as the one in progress at a time
+ * the host hands in.
+ *
+ * An effect moves a cell's colours and may never change a glyph
+ * (`./effect.ts`: "It changes how cells look, never which cells exist or who
+ * drew them"). A frame is the other kind of motion — what the element shows
+ * changes — so it is its own primitive and not a wider `Effect`, and the two
+ * compose by nesting: `new Effected(new Frames(…), …)` lights whichever frame
+ * is up.
+ *
+ * [LAW:no-ambient-temporal-coupling] `t` is an argument, as
+ * `Effected`'s is, never a clock read: whoever draws frames hands each one
+ * its time (`core/clock.ts`), so the same `t` draws the same bytes at one
+ * redraw a second or sixty. The host's rate is the host's. At sixty a frame
+ * shows for exactly its hold; at one a second a hold shorter than a second is
+ * skipped and a period of whole seconds freezes on one frame, and nothing
+ * here adapts to that — the beat is `core/easing.ts`'s, the one timing
+ * vocabulary, and a draw costs the same at `t = 0` and `t = 10⁶`.
+ *
+ * The sequence and the moment are two values, because only one of them
+ * changes from frame to frame. A `FrameSequence` is the frames prepared once
+ * — the beat, the one width, each frame set into a line and padded — and a
+ * `Frames` is that sequence at a `t`, whose work is one frame's — finding
+ * which, and copying it: a host holds the sequence and asks it for a frame,
+ * as `Spinner` holds its two, so a draw costs the same over ninety frames as
+ * over one. The sequence is a value the host keeps, not a memo here: nothing
+ * is looked up by key.
+ *
+ * The frame drawn is drawn until the next begins, and its cells say so: they
+ * are stamped with that moment (`Style.nextChange`), which rides up through
+ * every container to whoever holds the composed frame (`Segment.nextChange`),
+ * so a host drawing at `t` knows when to draw again, and one drawing slower
+ * than the frames turn can see that it is skipping them.
+ *
+ * Every frame is drawn at one width, the widest frame's, each padded on the
+ * right to it, so whatever sits beside the frames never moves as they turn;
+ * and the frame is a fragment of a line (`setIntoLine`), ending no line of
+ * its own, so it sits among other cells. Frames are `RichText`, each free to
+ * carry its own style, and read once, here: markup is a string's reading
+ * under the console that draws it, which a frame handed to a template
+ * binding has no console for, so the frame arrives read, as a `Group`'s
+ * children do.
+ */
+import { beat } from "../core/easing.js";
+import { Style } from "../core/style.js";
+import { setIntoLine } from "./embed.js";
+/** A sequence of frames prepared to be drawn: built once, asked for the frame at a time. */
+export class FrameSequence {
+    /** Which frame is in progress when: the holds are the frames' seconds, in order. */
+    beat;
+    /** The width every frame draws at: the widest frame's, in cells. */
+    width;
+    // Each frame as it draws: a line fragment padded to `width`, made once.
+    _shown;
+    constructor(frames) {
+        this.beat = beat(frames.map((frame) => frame.seconds));
+        const texts = frames.map((frame) => setIntoLine(frame.text.copy()));
+        const widths = texts.map((text) => text.cellLength);
+        this.width = Math.max(...widths);
+        this._shown = texts.map((text, i) => {
+            // One picture: a slot narrower than the frame crops it, never folds
+            // or wraps it onto a second line, which `Frames.measure` says it cannot take.
+            text.noWrap = true;
+            text.overflow = "crop";
+            return text.padRight(this.width - widths[i]);
+        });
+    }
+    /**
+     * The frame in progress at `t`, at `width` cells, ending no line: a copy,
+     * the caller's to change, its every cell — padding included — stamped with
+     * when it gives way to the next, `beat.end(t)`, so a blank frame among
+     * drawn ones still turns. [LAW:one-source-of-truth] The stamp is the one
+     * answer to when the frame changes, read off the cells
+     * (`Segment.nextChange`): a sequence of nothing has no cell to carry one,
+     * and a field saying a time would disagree with cells saying never.
+     * `beat.at` refuses a `t` that is not finite.
+     */
+    text(t) {
+        return this._shown[this.beat.at(t)].copy().stylize(new Style({ nextChange: this.beat.end(t) }));
+    }
+}
+/** A sequence's frame in progress at one moment, as a renderable. */
+export class Frames {
+    sequence;
+    t;
+    // The frame `t` lands on, found once, here, so a bad time fails at construction.
+    _shown;
+    constructor(sequence, options) {
+        this.sequence = sequence;
+        this.t = options.t;
+        this._shown = sequence.text(options.t);
+    }
+    render(options) {
+        return this._shown.render(options);
+    }
+    /**
+     * One width both ways: a frame is one picture, never wrapped apart at a
+     * space or narrowed as the frames turn. Fitting it to the room is
+     * `Measurement.get`'s, as for every measurable.
+     */
+    measure() {
+        return { minimum: this.sequence.width, maximum: this.sequence.width };
+    }
+}

package/dist/renderables/live.d.ts

@@ -27,10 +27,26 @@
 import { type Clock } from "../core/clock.js";
 import { Console } from "../core/console.js";
 import { type Renderable } from "../core/protocol.js";
+/**
+ * What a Live draws: a renderable, or a view asked for one each frame with
+ * the frame's time in seconds on the Live's clock, as an `App`'s view is
+ * (`host/app.ts`). A renderable is the view that is the same at every `t` —
+ * a table mutated in place between frames — and a function is what a frame
+ * drawn for a time needs: `(t) => spinner.at(t)`.
+ * [LAW:no-ambient-temporal-coupling] The Live reads its clock once a frame
+ * and hands the time down as data, so nothing it draws reads one.
+ */
+export type LiveView = Renderable | ((t: number) => Renderable);
 export interface LiveOptions {
-    /** Frames a second while auto-refreshing: positive and finite, fractional included. */
+    /**
+     * How often the auto-refresh draws on its own, in frames a second:
+     * positive and finite, fractional included. The next frame comes a frame
+     * interval after the last one drawn, a `refresh()` of your own included,
+     * or sooner when that frame's content says it changes sooner
+     * (`Segment.nextChange`).
+     */
     refreshPerSecond?: number;
-    /** What the auto-refresh ticks on. The platform's, unless given. */
+    /** What the auto-refresh waits on. The platform's, unless given. */
     clock?: Clock;
     autoRefresh?: boolean;
     transient?: boolean;
@@ -42,7 +58,7 @@ export interface LiveOptions {
     altScreen?: boolean;
 }
 export declare class Live {
-    private _renderable;
+    private _view;
     private _console;
     private readonly _rate;
     private readonly _clock;
@@ -50,21 +66,21 @@ export declare class Live {
     private _transient;
     private _verticalOverflow;
     private readonly _painter;
-    private _stopTicking;
+    private _waking;
     private _held;
-    constructor(renderable?: Renderable, options?: LiveOptions);
+    constructor(view?: LiveView, options?: LiveOptions);
     /**
      * The console to print through while this Live runs: what it prints lands
      * above an inline frame. The alternate screen is all frame, and paints over it.
      */
     get console(): Console;
-    get renderable(): Renderable | undefined;
     start(): void;
     stop(): void;
-    update(renderable?: Renderable, options?: {
+    update(view?: LiveView, options?: {
         refresh?: boolean;
     }): void;
     refresh(): void;
+    private _wake;
     private _frame;
     private _stepAround;
     private _paint;

package/dist/renderables/live.js

@@ -29,8 +29,12 @@ import { Console } from "../core/console.js";
 import { Segment } from "../core/segment.js";
 import { FinalFramePainter, SurfacePainter } from "../core/paint.js";
 import { fitHeight } from "../core/protocol.js";
+// [LAW:parse-dont-validate] The one shape Live holds: a renderable becomes
+// the view that answers it at every t, where it is given, so no frame asks
+// which it was.
+const viewOf = (view) => view === undefined || typeof view === "function" ? view : () => view;
 export class Live {
-    _renderable;
+    _view;
     _console;
     _rate;
     _clock;
@@ -38,13 +42,14 @@ export class Live {
     _transient;
     _verticalOverflow;
     _painter;
-    _stopTicking;
+    // The one wait for the next auto-refresh frame, armed after each frame.
+    _waking;
     // [LAW:one-source-of-truth] The console's live region, held from `start()`
     // to the hand-back — which is what "started" means, so there is no separate
     // flag to disagree with it.
     _held;
-    constructor(renderable, options) {
-        this._renderable = renderable;
+    constructor(view, options) {
+        this._view = viewOf(view);
         this._console = options?.console ?? new Console();
         // [LAW:parse-dont-validate] Parsed whether or not it auto-refreshes, so a
         // rate that could never tick is refused where it is given.
@@ -69,9 +74,6 @@ export class Live {
     get console() {
         return this._console;
     }
-    get renderable() {
-        return this._renderable;
-    }
     start() {
         if (this._held !== null)
             return;
@@ -80,21 +82,9 @@ export class Live {
         const held = this._console.claimLiveRegion({ around: (text) => this._stepAround(text) });
         this._held = held;
         this._painter.take();
-        if (this._autoRefresh) {
-            // No caller is on the stack to run `stop()` for a frame that throws
-            // here, and in Node the throw ends the process — so the terminal is
-            // handed back first, and the error then goes on to wherever an uncaught
-            // one goes.
-            this._stopTicking = this._clock.every(this._rate, () => {
-                try {
-                    this.refresh();
-                }
-                catch (error) {
-                    this._release(held);
-                    throw error;
-                }
-            });
-        }
+        // Nothing is drawn yet, so nothing has said when it changes: the first
+        // auto-refresh frame comes at the rate, from now.
+        this._wake(held, { t: this._clock.now(), nextChange: Number.POSITIVE_INFINITY });
     }
     stop() {
         const held = this._held;
@@ -114,9 +104,9 @@ export class Live {
             this._release(held);
         }
     }
-    update(renderable, options) {
-        if (renderable !== undefined) {
-            this._renderable = renderable;
+    update(view, options) {
+        if (view !== undefined) {
+            this._view = viewOf(view);
         }
         if (options?.refresh) {
             this.refresh();
@@ -126,13 +116,57 @@ export class Live {
         // A frame is drawn only while this Live holds the terminal, as in Rich:
         // before `start()` or after the hand-back it would land on a screen that
         // belongs to someone else — the main buffer, under the user's own output.
-        if (this._held === null)
+        const held = this._held;
+        if (held === null)
+            return;
+        // [LAW:no-ambient-temporal-coupling] The frame says when what it shows
+        // next changes; the next auto-refresh frame is then, or at the rate,
+        // whichever is sooner. The painter decides whether this frame is drawn
+        // now — a final-frame painter draws nothing before the hand-back — and a
+        // frame not drawn has said nothing.
+        let said;
+        this._paint(() => {
+            const { t, lines } = this._frame();
+            said = { t, nextChange: lines.reduce((soonest, row) => Math.min(soonest, Segment.nextChange(row)), Number.POSITIVE_INFINITY) };
+            return lines;
+        });
+        this._wake(held, said ?? { t: this._clock.now(), nextChange: Number.POSITIVE_INFINITY });
+    }
+    // Arm the one wait for the next auto-refresh frame while `held`: at the
+    // frame's `nextChange` when that is before the rate's next frame, else at
+    // the rate — both measured from the frame's own `t`, never from a second
+    // reading of the clock, so the rate does not stretch by what a frame cost
+    // to draw, and a change that fell due while it was drawn is drawn at once
+    // (`Clock.at` fires now for a time already past). Content that changes
+    // every frame answers `t` itself, and is drawn at the rate.
+    _wake(held, { t, nextChange }) {
+        this._waking?.();
+        this._waking = undefined;
+        if (!this._autoRefresh)
             return;
-        this._paint(() => this._frame());
+        const at = Math.min(t + this._rate.interval, nextChange > t ? nextChange : Number.POSITIVE_INFINITY);
+        // No caller is on the stack to run `stop()` for a frame that throws
+        // here, and in Node the throw ends the process — so the terminal is
+        // handed back first, and the error then goes on to wherever an uncaught
+        // one goes.
+        this._waking = this._clock.at(at, () => {
+            try {
+                this.refresh();
+            }
+            catch (error) {
+                this._release(held);
+                throw error;
+            }
+        });
     }
+    // The frame at the clock's now, with that time: the one the view was handed, and the one the next wake is measured from.
     _frame() {
-        if (!this._renderable)
-            return [];
+        // [LAW:effects-at-boundaries] One read of the clock a frame, handed to
+        // the view as the frame's time.
+        const t = this._clock.now();
+        if (!this._view)
+            return { t, lines: [] };
+        const renderable = this._view(t);
         // [LAW:dataflow-not-control-flow] Both modes render under the terminal's
         // rows and differ only in what those rows are: the alternate screen is a
         // region the frame stands in, and an inline frame keeps its natural height
@@ -140,14 +174,14 @@ export class Live {
         // back — its overflow policy, then `fitHeight`, which pads only a region.
         const options = this._console.options;
         const height = this._painter.height(options.height.rows);
-        const lines = Segment.splitLines(this._renderable.render({ ...options, height }));
-        return fitHeight(this._overflow(lines, height.rows), height);
+        const lines = Segment.splitLines(renderable.render({ ...options, height }));
+        return { t, lines: fitHeight(this._overflow(lines, height.rows), height) };
     }
     // What the console writes goes where the frame was, and the frame is painted
     // again under it, as Rich's render hook does — in the bytes the console
     // writes, so a render that throws writes nothing.
     _stepAround(text) {
-        return this._painter.around(text, () => this._frame(), this._screen(), this._console.destination);
+        return this._painter.around(text, () => this._frame().lines, this._screen(), this._console.destination);
     }
     // [LAW:effects-at-boundaries] The frame is fully rendered before a byte
     // reaches the terminal, and whatever takes the last frame away goes out in
@@ -177,8 +211,8 @@ export class Live {
     _release(held) {
         held();
         this._held = null;
-        this._stopTicking?.();
-        this._stopTicking = undefined;
+        this._waking?.();
+        this._waking = undefined;
         this._painter.handBack();
     }
 }

package/dist/renderables/markdown.d.ts

@@ -5,8 +5,11 @@
  * Block structure is read as CommonMark reads it: a blockquote and a list
  * item are both containers, their lines tokenized as Markdown of their own
  * once the container's marker or indentation is cut off, and drawn beside a
- * gutter — the quote's bar, the item's marker then its hang. Where CommonMark
- * leaves the drawing open, Rich's is followed.
+ * gutter — the quote's bar, the item's marker then its hang. A table, which
+ * CommonMark has none of, and an HTML block are read as markdown-it — Rich's
+ * parser — reads them. Where CommonMark leaves the drawing open, Rich's is
+ * followed: HTML, a block of it or a tag inline, is drawn as Rich draws it,
+ * not at all.
  */
 import { Segment } from "../core/segment.js";
 import { Style } from "../core/style.js";