@promptctl/rich-js 0.23.0 → 0.24.1

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

@@ -28,9 +28,13 @@ import { frameRate, systemClock } from "../core/clock.js";
 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";
+import { fitHeight, render } 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(render(renderable, { ...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-parse.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Markdown's parse, with no dependency: a source read into blocks, then the
+ * text of each block read into inlines — the two passes markdown-it, Rich's
+ * parser, makes. Nothing here reads a `RenderOptions`, so a `Markdown` parses
+ * its source once, when it is made, as Rich's does, and every render after
+ * only walks the tokens.
+ *
+ * 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. A table, which
+ * CommonMark has none of, and an HTML block are read as markdown-it reads
+ * them.
+ */
+/** Where a table column's cells sit, from the colons on its delimiter cell. None is GFM's no alignment, which Rich leaves to its column: left. */
+export type CellAlign = "left" | "center" | "right" | undefined;
+interface TableColumn<Text> {
+    readonly header: Text;
+    readonly align: CellAlign;
+}
+/** A heading's level: an ATX heading's count of `#`s, or 1 and 2 for a setext heading's `=` and `-`. */
+export type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
+/**
+ * A block, its text as `Text`: the source's own text after the block pass,
+ * and that text read into inlines after the inline pass, which is what
+ * `parseMarkdown` hands back. `Mark` is what the block pass keeps besides:
+ * none, once the inline pass has dropped its marks.
+ */
+export type MdToken<Text = readonly Inline[], Mark = never> = {
+    type: "heading";
+    level: HeadingLevel;
+    text: Text;
+} | {
+    type: "paragraph";
+    text: Text;
+} | {
+    type: "code_block";
+    code: string;
+} | {
+    type: "hr";
+}
+/** `start` is an ordered list's first number, as its source writes it; a bullet list has none. Each item is its blocks. */
+ | {
+    type: "list";
+    start: number | undefined;
+    items: readonly (readonly MdToken<Text, Mark>[])[];
+} | {
+    type: "blockquote";
+    children: readonly MdToken<Text, Mark>[];
+}
+/** Each row holds one cell per column: a short row filled out with empty cells, a long one cut. */
+ | {
+    type: "table";
+    columns: readonly TableColumn<Text>[];
+    rows: readonly (readonly Text[])[];
+}
+/** Kept, though nothing draws it, as Rich exits it like any other block. */
+ | {
+    type: "html_block";
+} | Mark;
+/** The element markdown-it makes of a pair of delimiters. */
+type EmphasisTag = "em" | "strong" | "s";
+/**
+ * CommonMark's inlines, as one block's text reads: a code span, emphasis or a
+ * link holding inlines of its own, an autolink, an image, inline HTML, a line
+ * ending, and text — a backslash escape and a character reference already the
+ * characters they stand for. Emphasis is named by the element markdown-it
+ * makes of it, GFM's strikethrough `s` among them.
+ */
+export type Inline = {
+    kind: "text";
+    text: string;
+} | {
+    kind: "code";
+    code: string;
+} | {
+    kind: "emphasis";
+    tag: EmphasisTag;
+    children: readonly Inline[];
+} | {
+    kind: "link";
+    children: readonly Inline[];
+    url: string;
+}
+/** `text` is the URL as written, normalized as markdown-it shows it, never read as Markdown. */
+ | {
+    kind: "autolink";
+    text: string;
+    url: string;
+}
+/** `alt` is as written, never read as Markdown. */
+ | {
+    kind: "image";
+    alt: string;
+    src: string;
+}
+/** `content` is the tag as written, markdown-it's `html_inline` content. */
+ | {
+    kind: "html";
+    content: string;
+}
+/** markdown-it's `softbreak` and `hardbreak`: tokens of their own, never joined to the text beside them. */
+ | {
+    kind: "softbreak";
+} | {
+    kind: "hardbreak";
+};
+/** `source` read as Markdown: its blocks, and the text in each read into inlines. A line ends at `\r\n`, `\r` or `\n`, as markdown-it normalizes them. */
+export declare function parseMarkdown(source: string): MdToken[];
+export {};