@promptctl/rich-js 0.24.0 → 0.25.0

package/dist/renderables/live.js

@@ -28,33 +28,41 @@ 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";
-// [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;
+import { fitHeight, render } from "../core/protocol.js";
+import { Timeline } from "../core/timeline.js";
+import { drawView, frameTime, hostView, undrawn } from "../core/view.js";
+import { State } from "../core/state.js";
+// Nothing: what a Live made with no view draws until `update` gives it one.
+const NOTHING = { render: () => [] };
 export class Live {
     _view;
     _console;
     _rate;
     _clock;
+    // The clock moment this host began: what its default timeline plays from,
+    // and what a renderable view is drawn for the time since (`HostTime`).
+    _epoch;
+    _timeline;
     _autoRefresh;
     _transient;
     _verticalOverflow;
     _painter;
-    // The one wait for the next auto-refresh frame, armed after each frame.
-    _waking;
+    // The one wait for the next auto-refresh frame, armed after each frame, and
+    // the clock moment it is due at.
+    _waking = new State(undefined);
     // [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;
+    _held = new State(null);
     constructor(view, options) {
-        this._view = viewOf(view);
+        this._view = new State(hostView(view ?? NOTHING));
         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.
         this._rate = frameRate(options?.refreshPerSecond ?? 4);
         this._clock = options?.clock ?? systemClock();
+        this._epoch = this._clock.now();
+        this._timeline = new State(options?.timeline ?? Timeline.play(this._epoch));
         this._autoRefresh = options?.autoRefresh !== false;
         this._transient = options?.transient ?? false;
         this._verticalOverflow = options?.verticalOverflow ?? "ellipsis";
@@ -65,7 +73,6 @@ export class Live {
         this._painter = this._console.isInteractive
             ? new SurfacePainter(options?.altScreen ? "alternate" : "inline", (bytes) => void this._console.file.write(bytes))
             : new FinalFramePainter((frame) => this._console.print(linesOf(frame)));
-        this._held = null;
     }
     /**
      * The console to print through while this Live runs: what it prints lands
@@ -74,20 +81,45 @@ export class Live {
     get console() {
         return this._console;
     }
+    /** The clock the auto-refresh waits on: 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.get();
+    }
+    /** The time a frame drawn now is drawn for: the clock's now, through the timeline. */
+    get frameTime() {
+        return frameTime(this._time());
+    }
+    _time() {
+        return { now: this._clock.now(), epoch: this._epoch, timeline: this._timeline.get() };
+    }
+    /**
+     * Replace the timeline and draw 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 — the auto-refresh waits on nothing until the timeline plays
+     * again — while `refresh()` and `update(…, { refresh: true })` still draw.
+     */
+    set timeline(timeline) {
+        this._timeline.set(timeline);
+        this.refresh();
+    }
     start() {
-        if (this._held !== null)
+        if (this._held.get() !== null)
             return;
         // Claimed before a byte is written, so a console another Live is running
         // on refuses this one with the terminal untouched.
         const held = this._console.claimLiveRegion({ around: (text) => this._stepAround(text) });
-        this._held = held;
+        this._held.set(held);
         this._painter.take();
         // 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 });
+        this._wake(held, undrawn(this._clock.now()));
     }
     stop() {
-        const held = this._held;
+        const held = this._held.get();
         if (held === null)
             return;
         // [LAW:no-silent-failure] A final frame that throws still propagates, and
@@ -106,17 +138,29 @@ export class Live {
     }
     update(view, options) {
         if (view !== undefined) {
-            this._view = viewOf(view);
+            this._view.set(hostView(view));
         }
         if (options?.refresh) {
             this.refresh();
+            return;
+        }
+        const held = this._held.get();
+        if (view !== undefined && held !== null) {
+            // The last wake was armed for what the old view said; a new view has
+            // said nothing yet, so the auto-refresh draws it by the rate's next
+            // frame from now — sooner if the wake already armed is, and never
+            // later, so updates faster than the rate do not put the frame off.
+            const now = this._clock.now();
+            const waking = this._waking.get();
+            if (waking === undefined || waking.at > now + this._rate.interval)
+                this._wake(held, undrawn(now));
         }
     }
     refresh() {
         // 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.
-        const held = this._held;
+        const held = this._held.get();
         if (held === null)
             return;
         // [LAW:no-ambient-temporal-coupling] The frame says when what it shows
@@ -126,30 +170,33 @@ export class Live {
         // 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;
+            const drawn = this._frame();
+            said = drawn;
+            return drawn.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.
+        this._wake(held, said ?? undrawn(this._clock.now()));
+    }
+    // Arm the one wait for the next auto-refresh frame while `held`, from what
+    // the frame says: at its `nextChange` when it holds until a moment sooner
+    // than the rate, and at the rate otherwise — every view is drawn from state
+    // that may change without saying so, which the auto-refresh polls, as
+    // Rich's does, a paused timeline's included. Every moment is 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).
     _wake(held, { t, nextChange }) {
-        this._waking?.();
-        this._waking = undefined;
+        this._waking.get()?.stop();
+        this._waking.set(undefined);
+        const rate = t + this._rate.interval;
+        const at = nextChange <= t ? rate : Math.min(nextChange, rate);
         if (!this._autoRefresh)
             return;
-        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, () => {
+        const stop = this._clock.at(at, () => {
             try {
                 this.refresh();
             }
@@ -158,15 +205,13 @@ export class Live {
                 throw error;
             }
         });
+        this._waking.set({ at, stop });
     }
-    // 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.
+    // The frame at the clock's now, drawn for the time the timeline maps it to,
+    // with when it next changes on the clock: what the next wake is measured from.
     _frame() {
         // [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
@@ -174,8 +219,10 @@ 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(renderable.render({ ...options, height }));
-        return { t, lines: fitHeight(this._overflow(lines, height.rows), height) };
+        return drawView(this._view.get(), this._time(), this, { ...options, height }, (renderable, drawn) => {
+            const lines = Segment.splitLines(render(renderable, drawn));
+            return 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
@@ -210,9 +257,9 @@ export class Live {
     // ran or a frame threw with no caller to run it.
     _release(held) {
         held();
-        this._held = null;
-        this._waking?.();
-        this._waking = undefined;
+        this._held.set(null);
+        this._waking.get()?.stop();
+        this._waking.set(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> = Readonly<{
+    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 = Readonly<{
+    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 {};