@promptctl/rich-js 0.18.1 → 0.20.0

package/dist/renderables/live.js

@@ -1,42 +1,71 @@
 /**
  * Live — animates a portion of the terminal by continuously re-rendering.
  *
- * Two modes:
- * - **Inline** (default): clears and redraws N lines in the current scroll
- *   region. Good for spinners/progress bars below other output.
+ * Two modes, each painting every frame over the last in place
+ * (`core/paint`):
+ * - **Inline** (default): the frame starts at the cursor's line and keeps its
+ *   own height. Good for spinners/progress bars below other output.
  * - **Alt-screen** (`altScreen: true`): enters the alternate screen buffer
- *   on start, cursor-homes on each refresh (no clear flicker), and restores
- *   the original buffer on stop. The screen is the frame's region, so a
- *   `Layout` fills it. Good for full-screen TUI apps.
+ *   on start and restores the original buffer on stop. The screen is the
+ *   frame's region, so a `Layout` fills it. Good for full-screen TUI apps.
+ *
+ * On a console that is not interactive — a file, a pipe, a CI log — neither
+ * mode paints: what is printed goes out plain, and the frame is written once,
+ * when the display stops, as Rich's `Live` does.
+ *
+ * Live is not built on `App`, though both take a terminal, paint a frame over
+ * the last and hand the terminal back. That much is the `Painter`'s, and both
+ * hold one. The rest differs in who owns what. An `App` owns its terminal: it
+ * starts and stops a `TerminalHost`, sets raw mode, reads keys and pointers,
+ * suspends, and builds its own `Console` from the host. A `Live` owns none of
+ * that. It draws into a `Console` its caller owns and goes on writing
+ * through — a sink that may be a file, whose every other write has to step
+ * around the frame (`Console.claimLiveRegion`) — and it reads no input. An
+ * `App` over that console would need a host that cannot start, stop, read or
+ * suspend, and a second owner of the console's writes.
  */
+import { frameRate, systemClock } from "../core/clock.js";
 import { Console } from "../core/console.js";
 import { Segment } from "../core/segment.js";
-import { segmentsToString } from "../core/render.js";
+import { FinalFramePainter, SurfacePainter } from "../core/paint.js";
 import { fitHeight } from "../core/protocol.js";
 export class Live {
     _renderable;
     _console;
-    _refreshPerSecond;
+    _rate;
+    _clock;
     _autoRefresh;
     _transient;
     _verticalOverflow;
-    _altScreen;
-    _timer;
-    _lastLineCount;
-    _started;
-    _firstRefresh;
+    _painter;
+    _stopTicking;
+    // [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;
-        this._console = options?.console ?? new Console({ forceTerminal: true });
-        this._refreshPerSecond = options?.refreshPerSecond ?? 4;
+        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._autoRefresh = options?.autoRefresh !== false;
         this._transient = options?.transient ?? false;
         this._verticalOverflow = options?.verticalOverflow ?? "ellipsis";
-        this._altScreen = options?.altScreen ?? false;
-        this._lastLineCount = 0;
-        this._started = false;
-        this._firstRefresh = true;
+        // [LAW:dataflow-not-control-flow] What the console is decides which
+        // painter Live holds; every frame then takes the same path through it.
+        // The final frame is a print, as in Rich, so a recording or a capture
+        // holds it with everything else the console wrote.
+        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
+     * above an inline frame. The alternate screen is all frame, and paints over it.
+     */
     get console() {
         return this._console;
     }
@@ -44,48 +73,45 @@ export class Live {
         return this._renderable;
     }
     start() {
-        if (this._started)
+        if (this._held !== null)
             return;
-        this._started = true;
-        this._firstRefresh = true;
-        const stream = this._console.file;
-        if (this._altScreen) {
-            stream.write("\x1b[?1049h"); // enter alt screen
-        }
-        this._writeCursorControl(false);
+        // 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._painter.take();
         if (this._autoRefresh) {
-            const interval = Math.floor(1000 / this._refreshPerSecond);
             // 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._timer = setInterval(() => {
+            this._stopTicking = this._clock.every(this._rate, () => {
                 try {
                     this.refresh();
                 }
                 catch (error) {
-                    this._release();
+                    this._release(held);
                     throw error;
                 }
-            }, interval);
+            });
         }
     }
     stop() {
-        if (!this._started)
+        const held = this._held;
+        if (held === null)
             return;
         // [LAW:no-silent-failure] A final frame that throws still propagates, and
         // the terminal is handed back on the way out.
         try {
             if (this._transient) {
-                this._console.file.write(this._erase());
-                this._lastLineCount = 0;
+                this._paint(() => []);
             }
             else {
                 this.refresh();
             }
         }
         finally {
-            this._release();
+            this._release(held);
         }
     }
     update(renderable, options) {
@@ -100,47 +126,39 @@ 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._started || !this._renderable)
+        if (this._held === null)
             return;
+        this._paint(() => this._frame());
+    }
+    _frame() {
+        if (!this._renderable)
+            return [];
         // [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
         // under them as a ceiling. Live set the budget, so Live shapes what comes
         // back — its overflow policy, then `fitHeight`, which pads only a region.
         const options = this._console.options;
-        const height = { rows: options.height.rows, exact: this._altScreen };
+        const height = this._painter.height(options.height.rows);
         const lines = Segment.splitLines(this._renderable.render({ ...options, height }));
-        const displayLines = fitHeight(this._overflow(lines, height.rows), height);
-        // [LAW:single-enforcer] Per-line encoding routes through the same
-        // tree-coalescer `Console._writeSegments` uses, so Live frames coalesce
-        // adjacent same-style segments into shared SGR pairs on the wire and
-        // encode for the console's own destination.
-        // The alternate screen is not erased between frames — the cursor only goes
-        // home — so each of its rows is erased before it is drawn, or a shorter
-        // frame leaves the last one's rows and line tails showing. The erase comes
-        // first because the cursor is then at the row's start; after a row that
-        // fills the width it would take the last cell. An inline frame's rows are
-        // erased by `_erase`.
-        const lead = this._altScreen ? "\x1b[2K" : "";
-        const destination = this._console.destination;
-        const output = displayLines
-            .map((line) => lead + segmentsToString(line, destination))
-            .join("\n");
-        // [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
-        // the same write as the new one — so a render that throws leaves the last
-        // good frame showing. The first alternate-screen frame clears the buffer
-        // it walked into; after that the cursor only goes home.
-        const replace = this._altScreen ? (this._firstRefresh ? "\x1b[2J\x1b[H" : "\x1b[H") : this._erase();
-        // Inline, the newline leaves the cursor under the frame, where `_erase`
-        // counts up from. On the alternate screen the next frame starts from home,
-        // and a newline after a full-height frame's last row scrolls its first row
-        // off the top.
-        this._console.file.write(replace + (this._altScreen ? output : output + "\n"));
-        this._firstRefresh = false;
-        // What `_erase` erases: an inline frame's rows. An alternate-screen frame
-        // is erased by leaving the buffer.
-        this._lastLineCount = this._altScreen ? 0 : displayLines.length;
+        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
+    // writes, so a render that throws writes nothing.
+    _stepAround(text) {
+        return this._painter.around(text, () => this._frame(), 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
+    // the same write as the new one — so a render that throws leaves the last
+    // good frame showing.
+    _paint(frame) {
+        this._painter.paint(frame, this._screen(), this._console.destination);
+    }
+    _screen() {
+        const { height, maxWidth } = this._console.options;
+        return { rows: height.rows, cols: maxWidth };
     }
     // Lines past `rows`: dropped, with the last kept row replaced by an ellipsis,
     // or left for the terminal to scroll.
@@ -153,23 +171,18 @@ export class Live {
         }
         return kept;
     }
-    // Cursor-up and erase-line for each row of the last inline frame.
-    _erase() {
-        return "\x1b[1A\x1b[2K".repeat(this._lastLineCount);
-    }
     // [LAW:single-enforcer] The one way the terminal is handed back — the timer
     // stopped, the cursor shown, the alternate screen left — whether `stop()`
     // ran or a frame threw with no caller to run it.
-    _release() {
-        this._started = false;
-        clearInterval(this._timer);
-        this._timer = undefined;
-        this._writeCursorControl(true);
-        if (this._altScreen) {
-            this._console.file.write("\x1b[0m\x1b[?1049l"); // reset attrs + exit alt screen
-        }
-    }
-    _writeCursorControl(show) {
-        this._console.file.write(show ? "\x1b[?25h" : "\x1b[?25l");
+    _release(held) {
+        held();
+        this._held = null;
+        this._stopTicking?.();
+        this._stopTicking = undefined;
+        this._painter.handBack();
     }
 }
+// A drawn frame as a renderable, each row a line, for the console to print.
+function linesOf(frame) {
+    return { render: () => frame.flatMap((row) => [...row, Segment.line()]) };
+}

package/dist/renderables/markdown.d.ts

@@ -1,20 +1,33 @@
 /**
  * Markdown — renders Markdown content to the terminal.
  * Uses built-in parsing (no external dependency).
+ *
+ * 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.
  */
 import { Segment } from "../core/segment.js";
 import { Style } from "../core/style.js";
 import type { Renderable, Measurable, RenderOptions } from "../core/protocol.js";
 export interface MarkdownOptions {
-    codeTheme?: string;
+    /** The style of `inline code`: a theme name or a style definition. Default `markdown.code`. */
     inlineCodeStyle?: string | Style;
+    /**
+     * Whether a link's text is the link. `false` writes the URL after the text
+     * in parentheses, for a reader who cannot click it. Default `true`.
+     */
     hyperlinks?: boolean;
-    justify?: "left" | "center" | "right" | "full";
+    /** How body text — paragraphs, list items, quotes — is placed in its width. Default `"left"`; headings keep their own. */
+    justify?: Justify;
 }
+type Justify = NonNullable<RenderOptions["justify"]>;
 export declare class Markdown implements Renderable, Measurable {
     readonly markdown: string;
     readonly inlineCodeStyle: string | Style;
     readonly hyperlinks: boolean;
+    readonly justify: Justify;
     constructor(markdown: string, options?: MarkdownOptions);
     render(rawOptions: RenderOptions): Iterable<Segment>;
     measure(options: RenderOptions): {
@@ -22,3 +35,4 @@ export declare class Markdown implements Renderable, Measurable {
         maximum: number;
     };
 }
+export {};