@promptctl/rich-js 0.17.0 → 0.18.1

package/dist/renderables/columns.js

@@ -3,25 +3,9 @@
  */
 import { Segment } from "../core/segment.js";
 import { Measurement } from "../core/measure.js";
-import { RichText } from "../core/text.js";
-import { isMeasurable, withBoundedWidth, withCellWidth } from "../core/protocol.js";
+import { isMeasurable, stackedHeight, withBoundedWidth, withCellWidth } from "../core/protocol.js";
 import { cellCount } from "../core/cells.js";
-function toRenderable(item) {
-    // [LAW:single-enforcer] A `RichText` passed directly implements `render`
-    // and would otherwise leave through the passthrough arm below untouched,
-    // keeping its default `end: "\n"` (rich-text-5ai) — the same gap the code
-    // review found in table.ts's `toRenderable`. A column item is a row
-    // fragment, not a printed unit, same as every other embedding site.
-    if (item instanceof RichText) {
-        const copy = item.copy();
-        copy.end = "";
-        return copy;
-    }
-    if (typeof item === "object" && item !== null && "render" in item) {
-        return item;
-    }
-    return new RichText(String(item ?? ""), { end: "" });
-}
+import { embed } from "./embed.js";
 export class Columns {
     renderables;
     expand;
@@ -30,7 +14,7 @@ export class Columns {
     columnFirst;
     gutterWidth;
     constructor(items, options) {
-        this.renderables = items ? [...items].map(toRenderable) : [];
+        this.renderables = items ? [...items].map(embed) : [];
         this.expand = options?.expand ?? false;
         this.equal = options?.equal ?? false;
         // A declared column width is a cell count like any other, and it reaches
@@ -70,7 +54,7 @@ export class Columns {
                 const lines = item === undefined
                     ? []
                     : Segment.splitLines([
-                        ...item.render({ ...options, maxWidth: width }),
+                        ...item.render({ ...options, maxWidth: width, height: stackedHeight(options.height) }),
                     ]);
                 return { lines, width };
             });

package/dist/renderables/embed.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The one crossing where content a caller hands a renderable — a table cell, a
+ * panel's body, title or subtitle, a tree label, a column item, a layout pane,
+ * a rule's title — becomes something that renderable can lay out.
+ * [LAW:single-enforcer]
+ *
+ * Each of those sites used to build its own `RichText` straight from the
+ * constructor, which does not parse markup, so `[red]Solo[/red]` reached the
+ * terminal with its tags intact. Table cells were fixed on their own first; the
+ * rest kept the defect until the rule moved here.
+ *
+ * Markup is parsed because Rich parses it: every one of these positions
+ * reaches the wire through Rich's `render_str`, and a console's markup is on by
+ * default. Rich's `render_str` also honours `Console(markup=False)` and runs the
+ * console's highlighter; this crossing does neither, because the console's
+ * settings do not reach it (rich-markup-3sw).
+ *
+ * `end` is cleared because embedded text is a fragment rather than a printed
+ * line; left at the default `"\n"` it draws a trailing blank row. A `RichText`
+ * is copied first, since clearing in place would reach back into the caller's
+ * object.
+ */
+import type { Measurable, Renderable, RenderOptions } from "../core/protocol.js";
+import { Segment } from "../core/segment.js";
+import type { Style } from "../core/style.js";
+import { RichText } from "../core/text.js";
+/**
+ * Caller content as the text an embedding site lays out, `end` cleared. A
+ * string is the only kind of content that can contain markup, so it is the only
+ * kind parsed; any other value is its `String` form as written, so an object's
+ * `[object Object]` is not eaten as a tag.
+ */
+export declare function embeddedText(content: unknown): RichText;
+/**
+ * Caller content as something an embedding site can render. A non-text
+ * `Renderable` (a nested `Panel` or `Table`) passes through: it carries no
+ * `end` to clear and no markup to parse. Everything else is `embeddedText`.
+ */
+export declare function embed(content: unknown): Renderable & Partial<Measurable>;
+/**
+ * Caller content set into a line it shares with other drawing — a panel's
+ * title or subtitle in its border, a rule's title — as one line of segments:
+ * a space either side, its own styles over `base`. The caller cuts it to the
+ * room it has with `Segment.adjustLineLength`, which is cell-aware.
+ *
+ * Content with no text is no label at all, not two spaces: an absent title, an
+ * empty string, an empty `RichText` and markup that styles nothing all draw
+ * the plain line, as Rich's do (an empty `Text` is falsy there).
+ */
+export declare function inlineLabel(content: unknown, options: RenderOptions, base: Style | undefined): Segment[];

package/dist/renderables/embed.js

@@ -0,0 +1,71 @@
+/**
+ * The one crossing where content a caller hands a renderable — a table cell, a
+ * panel's body, title or subtitle, a tree label, a column item, a layout pane,
+ * a rule's title — becomes something that renderable can lay out.
+ * [LAW:single-enforcer]
+ *
+ * Each of those sites used to build its own `RichText` straight from the
+ * constructor, which does not parse markup, so `[red]Solo[/red]` reached the
+ * terminal with its tags intact. Table cells were fixed on their own first; the
+ * rest kept the defect until the rule moved here.
+ *
+ * Markup is parsed because Rich parses it: every one of these positions
+ * reaches the wire through Rich's `render_str`, and a console's markup is on by
+ * default. Rich's `render_str` also honours `Console(markup=False)` and runs the
+ * console's highlighter; this crossing does neither, because the console's
+ * settings do not reach it (rich-markup-3sw).
+ *
+ * `end` is cleared because embedded text is a fragment rather than a printed
+ * line; left at the default `"\n"` it draws a trailing blank row. A `RichText`
+ * is copied first, since clearing in place would reach back into the caller's
+ * object.
+ */
+import { renderMarkup } from "../core/markup.js";
+import { Segment } from "../core/segment.js";
+import { RichText } from "../core/text.js";
+/**
+ * Caller content as the text an embedding site lays out, `end` cleared. A
+ * string is the only kind of content that can contain markup, so it is the only
+ * kind parsed; any other value is its `String` form as written, so an object's
+ * `[object Object]` is not eaten as a tag.
+ */
+export function embeddedText(content) {
+    const text = content instanceof RichText
+        ? content.copy()
+        : typeof content === "string"
+            ? renderMarkup(content)
+            : new RichText(String(content ?? ""));
+    text.end = "";
+    return text;
+}
+/**
+ * Caller content as something an embedding site can render. A non-text
+ * `Renderable` (a nested `Panel` or `Table`) passes through: it carries no
+ * `end` to clear and no markup to parse. Everything else is `embeddedText`.
+ */
+export function embed(content) {
+    if (!(content instanceof RichText) && typeof content === "object" && content !== null && "render" in content) {
+        return content;
+    }
+    return embeddedText(content);
+}
+/**
+ * Caller content set into a line it shares with other drawing — a panel's
+ * title or subtitle in its border, a rule's title — as one line of segments:
+ * a space either side, its own styles over `base`. The caller cuts it to the
+ * room it has with `Segment.adjustLineLength`, which is cell-aware.
+ *
+ * Content with no text is no label at all, not two spaces: an absent title, an
+ * empty string, an empty `RichText` and markup that styles nothing all draw
+ * the plain line, as Rich's do (an empty `Text` is falsy there).
+ */
+export function inlineLabel(content, options, base) {
+    // The label leaves at its natural width, `"ignore"`, because the caller does
+    // the cutting; the label's own overflow method would cut it first, and to a
+    // width no one measured. `"ignore"` also leaves it unjustified, so its spaces
+    // stay where `pad` put them.
+    const bare = embeddedText(content);
+    const text = bare.plain === "" ? bare : bare.pad(1);
+    text.overflow = "ignore";
+    return [...Segment.applyStyle(text.render(options), base)];
+}

package/dist/renderables/group.js

@@ -2,14 +2,16 @@
  * Group — renders multiple renderables in sequence.
  * No visual chrome — purely a container.
  */
+import { stackedHeight } from "../core/protocol.js";
 export class Group {
     renderables;
     constructor(...renderables) {
         this.renderables = renderables;
     }
     *render(options) {
+        const memberOptions = { ...options, height: stackedHeight(options.height) };
         for (const renderable of this.renderables) {
-            yield* renderable.render(options);
+            yield* renderable.render(memberOptions);
         }
     }
 }

package/dist/renderables/layout.js

@@ -2,8 +2,8 @@
  * Layout — divides the screen into rectangular regions.
  */
 import { Segment } from "../core/segment.js";
-import { RichText } from "../core/text.js";
-import { isMeasurable, withBoundedWidth, withCellWidth } from "../core/protocol.js";
+import { embed } from "./embed.js";
+import { fitHeight, isMeasurable, regionRows, stackedHeight, withBoundedWidth, withCellWidth, } from "../core/protocol.js";
 import { Measurement } from "../core/measure.js";
 import { cellCount } from "../core/cells.js";
 /**
@@ -16,23 +16,18 @@ import { cellCount } from "../core/cells.js";
 function growthRatio(ratio) {
     return Number.isFinite(ratio) && ratio > 0 ? ratio : 0;
 }
-// [LAW:single-enforcer] A leaf's content is a pane, not a printed unit — the
-// same reason panel.ts and table.ts clear `end` on a `RichText` they embed.
-// The string branch already built one with `end: ""`; a `RichText` passed
-// directly needs the same treatment, or it keeps its default `end: "\n"`
-// (rich-text-5ai code review) and draws a trailing blank row through
-// `Segment.cropLines`, which — unlike table.ts's `splitLines`-based cell
-// rendering — does not normalize a trailing empty line away.
-function toRenderable(renderable) {
-    if (typeof renderable === "string") {
-        return new RichText(renderable, { end: "" });
-    }
-    if (renderable instanceof RichText) {
-        const copy = renderable.copy();
-        copy.end = "";
-        return copy;
-    }
-    return renderable;
+/**
+ * A pane rendered into a region of `rows` and held to exactly that many lines,
+ * or — with `rows` undefined — rendered under the layout's own budget, as a
+ * ceiling, at its natural height.
+ *
+ * [LAW:single-enforcer] The region's setter shapes it (`fitHeight`). Forwarded
+ * unshaped, a pane whose content ran short pulled every pane below it up, and
+ * one that ran long pushed them down.
+ */
+function paneLines(pane, options, rows) {
+    const height = rows === undefined ? stackedHeight(options.height) : { rows, exact: true };
+    return fitHeight(Segment.splitLines(pane.render({ ...options, height })), height);
 }
 export class Layout {
     name;
@@ -45,7 +40,7 @@ export class Layout {
     _splitDirection;
     constructor(renderable, options) {
         if (renderable !== undefined) {
-            this._renderable = toRenderable(renderable);
+            this._renderable = embed(renderable);
         }
         this.name = options?.name;
         this.ratio = options?.ratio ?? 1;
@@ -110,7 +105,7 @@ export class Layout {
         this._splitDirection = "row";
     }
     update(renderable) {
-        this._renderable = toRenderable(renderable);
+        this._renderable = embed(renderable);
     }
     getByName(name) {
         if (this.name === name)
@@ -151,29 +146,31 @@ export class Layout {
         }
     }
     *_renderColumn(children, options) {
-        // Vertical stacking: each child gets full width, proportional height
-        const totalHeight = options.maxHeight ?? options.height ?? 24;
-        const heights = this._distributeSpace(children, totalHeight);
+        // Each pane gets full width and its share of the region. With no region —
+        // a ceiling, or no budget at all — a pane's share is its declared `size`,
+        // and a pane without one takes its content's height.
+        const region = regionRows(options.height);
+        const shares = region === undefined
+            ? children.map((child) => child.size)
+            : this._distributeSpace(children, region);
         for (let i = 0; i < children.length; i++) {
-            const child = children[i];
-            const childOptions = {
-                ...options,
-                maxHeight: heights[i],
-                height: heights[i],
-            };
-            yield* child.render(childOptions);
+            for (const line of paneLines(children[i], options, shares[i])) {
+                yield* line;
+                yield Segment.line();
+            }
         }
     }
     *_renderRow(children, options) {
         // Horizontal side-by-side: divide the requested width once, then merge
         // child lines. The budget arrives parsed from `render` — unparsed, a NaN
         // width made every share NaN and the merge threw `Invalid array length`.
+        // Every pane stands in the whole region, and with none the merge pads the
+        // row to its tallest pane.
         const widths = this._distributeSpace(children, options.maxWidth);
+        const region = regionRows(options.height);
         const cells = children.map((child, i) => ({
             width: widths[i],
-            lines: Segment.splitLines([
-                ...child.render({ ...options, maxWidth: widths[i] }),
-            ]),
+            lines: paneLines(child, { ...options, maxWidth: widths[i] }, region),
         }));
         yield* Segment.mergeHorizontal(cells);
     }

package/dist/renderables/live.d.ts

@@ -6,10 +6,11 @@
  *   region. 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. Good for full-screen TUI apps.
+ *   the original buffer on stop. The screen is the frame's region, so a
+ *   `Layout` fills it. Good for full-screen TUI apps.
  */
 import { Console } from "../core/console.js";
-import type { Renderable } from "../core/protocol.js";
+import { type Renderable } from "../core/protocol.js";
 export interface LiveOptions {
     refreshPerSecond?: number;
     autoRefresh?: boolean;
@@ -42,6 +43,8 @@ export declare class Live {
         refresh?: boolean;
     }): void;
     refresh(): void;
-    private _clearLast;
+    private _overflow;
+    private _erase;
+    private _release;
     private _writeCursorControl;
 }

package/dist/renderables/live.js

@@ -6,11 +6,13 @@
  *   region. 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. Good for full-screen TUI apps.
+ *   the original buffer on stop. The screen is the frame's region, so a
+ *   `Layout` fills it. Good for full-screen TUI apps.
  */
 import { Console } from "../core/console.js";
 import { Segment } from "../core/segment.js";
 import { segmentsToString } from "../core/render.js";
+import { fitHeight } from "../core/protocol.js";
 export class Live {
     _renderable;
     _console;
@@ -53,26 +55,37 @@ export class Live {
         this._writeCursorControl(false);
         if (this._autoRefresh) {
             const interval = Math.floor(1000 / this._refreshPerSecond);
-            this._timer = setInterval(() => this.refresh(), interval);
+            // 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(() => {
+                try {
+                    this.refresh();
+                }
+                catch (error) {
+                    this._release();
+                    throw error;
+                }
+            }, interval);
         }
     }
     stop() {
         if (!this._started)
             return;
-        this._started = false;
-        if (this._timer) {
-            clearInterval(this._timer);
-            this._timer = undefined;
-        }
-        if (!this._transient) {
-            this.refresh();
+        // [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;
+            }
+            else {
+                this.refresh();
+            }
         }
-        else {
-            this._clearLast();
-        }
-        this._writeCursorControl(true);
-        if (this._altScreen) {
-            this._console.file.write("\x1b[0m\x1b[?1049l"); // reset attrs + exit alt screen
+        finally {
+            this._release();
         }
     }
     update(renderable, options) {
@@ -84,45 +97,76 @@ export class Live {
         }
     }
     refresh() {
-        if (!this._renderable)
+        // 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)
             return;
-        if (this._altScreen) {
-            // Alt-screen mode: cursor home (first refresh clears the buffer)
-            this._console.file.write(this._firstRefresh ? "\x1b[2J\x1b[H" : "\x1b[H");
-            this._firstRefresh = false;
-        }
-        else {
-            // Inline mode: erase previous output
-            this._clearLast();
-        }
-        const segments = [...this._renderable.render(this._console.options)];
-        const lines = Segment.splitLines(segments);
-        const maxHeight = this._console.height;
-        let displayLines = lines;
-        if (this._verticalOverflow !== "visible" && lines.length > maxHeight) {
-            displayLines = lines.slice(0, maxHeight);
-            if (this._verticalOverflow === "ellipsis" && displayLines.length > 0) {
-                displayLines[displayLines.length - 1] = [new Segment("...")];
-            }
-        }
+        // [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 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) => segmentsToString(line, destination))
+            .map((line) => lead + segmentsToString(line, destination))
             .join("\n");
-        this._console.file.write(output + "\n");
-        this._lastLineCount = displayLines.length;
+        // [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;
     }
-    _clearLast() {
-        if (this._lastLineCount > 0) {
-            const stream = this._console.file;
-            for (let i = 0; i < this._lastLineCount; i++) {
-                stream.write("\x1b[1A\x1b[2K");
-            }
-            this._lastLineCount = 0;
+    // Lines past `rows`: dropped, with the last kept row replaced by an ellipsis,
+    // or left for the terminal to scroll.
+    _overflow(lines, rows) {
+        if (this._verticalOverflow === "visible" || lines.length <= rows)
+            return lines;
+        const kept = lines.slice(0, rows);
+        if (this._verticalOverflow === "ellipsis" && kept.length > 0) {
+            kept[kept.length - 1] = [new Segment("...")];
+        }
+        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) {

package/dist/renderables/markdown.d.ts

@@ -16,7 +16,7 @@ export declare class Markdown implements Renderable, Measurable {
     readonly inlineCodeStyle: string | Style;
     readonly hyperlinks: boolean;
     constructor(markdown: string, options?: MarkdownOptions);
-    render(options: RenderOptions): Iterable<Segment>;
+    render(rawOptions: RenderOptions): Iterable<Segment>;
     measure(options: RenderOptions): {
         minimum: number;
         maximum: number;

package/dist/renderables/markdown.js

@@ -6,7 +6,7 @@ import { Segment } from "../core/segment.js";
 import { Style } from "../core/style.js";
 import { RichText } from "../core/text.js";
 import { Rule } from "./rule.js";
-import { getStyle } from "../core/protocol.js";
+import { drawable, getStyle, stackedHeight } from "../core/protocol.js";
 function tokenize(markdown) {
     const lines = markdown.split("\n");
     const tokens = [];
@@ -124,7 +124,9 @@ export class Markdown {
         this.inlineCodeStyle = options?.inlineCodeStyle ?? "markdown.code";
         this.hyperlinks = options?.hyperlinks !== false;
     }
-    *render(options) {
+    *render(rawOptions) {
+        // Every block below is one of a stack.
+        const options = { ...rawOptions, height: stackedHeight(rawOptions.height) };
         const tokens = tokenize(this.markdown);
         for (const token of tokens) {
             switch (token.type) {
@@ -156,7 +158,7 @@ export class Markdown {
                     break;
                 }
                 case "list_item": {
-                    const bullet = token.ordered ? `${token.index}. ` : "  • ";
+                    const bullet = token.ordered ? `${token.index}. ` : drawable(options, "  • ", "  * ");
                     yield new Segment(bullet);
                     const text = applyInlineStyles(token.text);
                     yield* text.render({ ...options, maxWidth: options.maxWidth - bullet.length });
@@ -164,7 +166,7 @@ export class Markdown {
                 }
                 case "blockquote": {
                     const quoteStyle = Style.parse("dim italic");
-                    yield new Segment("▎ ", getStyle(options, "markdown.hr"));
+                    yield new Segment(drawable(options, "▎ ", "| "), getStyle(options, "markdown.hr"));
                     const text = applyInlineStyles(token.text);
                     yield* Segment.applyStyle([...text.render(options)], quoteStyle);
                     yield Segment.line();

package/dist/renderables/padding.js

@@ -5,7 +5,7 @@ import { Segment } from "../core/segment.js";
 import { cellCount } from "../core/cells.js";
 import { NULL_STYLE } from "../core/style.js";
 import { Measurement } from "../core/measure.js";
-import { getStyle, isMeasurable, withBoundedWidth, withCellWidth } from "../core/protocol.js";
+import { fitHeight, getStyle, insetHeight, isMeasurable, withBoundedWidth, withCellWidth } from "../core/protocol.js";
 /**
  * Parses the shapes a caller may write padding in — one number, a vertical/
  * horizontal pair, or all four sides — into the four-sided form every
@@ -91,9 +91,10 @@ export class Padding {
         const innerOptions = {
             ...options,
             maxWidth: geometry.contentWidth,
+            height: insetHeight(options.height, this.top + this.bottom),
         };
         const segments = [...this.renderable.render(innerOptions)];
-        const lines = Segment.splitLines(segments);
+        const lines = fitHeight(Segment.splitLines(segments), innerOptions.height);
         const resolved = getStyle(options, this.style);
         const style = resolved.isNull ? undefined : resolved;
         // Zero-length spans need no branch to suppress: the wire boundary drops