@promptctl/rich-js 0.16.0 → 0.18.0

package/dist/renderables/layout.js

@@ -1,315 +0,0 @@
-/**
- * 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 { Measurement } from "../core/measure.js";
-import { cellCount } from "../core/cells.js";
-/**
- * A share weight, not a cell count: fractions divide space meaningfully, so
- * this parses where `cellCount` would floor. A weight that cannot name a share
- * — negative, NaN, infinite — reads as zero, which already means "this pane
- * does not grow" and is filtered out before any division. That is what makes
- * every ratio reaching `_distributeSpace` and `_rowBudgetFor` positive.
- */
-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;
-}
-export class Layout {
-    name;
-    visible;
-    _ratio;
-    _size;
-    _minimumSize;
-    _renderable;
-    _children;
-    _splitDirection;
-    constructor(renderable, options) {
-        if (renderable !== undefined) {
-            this._renderable = toRenderable(renderable);
-        }
-        this.name = options?.name;
-        this.ratio = options?.ratio ?? 1;
-        this.size = options?.size;
-        this.minimumSize = options?.minimumSize ?? 1;
-        this.visible = options?.visible !== false;
-        this._children = [];
-        this._splitDirection = undefined;
-    }
-    /**
-     * The three declared numbers, parsed on assignment rather than at the
-     * constructor. All three are public and a caller reaches them long after
-     * construction — `layout.getByName("pane")!.ratio = -1` walked straight past a
-     * constructor-only parse and put a negative weight back into the division that
-     * `_rowBudgetFor` and `_distributeSpace` are written to trust.
-     *
-     * [LAW:parse-dont-validate] The setter is the border, so the guarantee holds
-     * for the object's whole lifetime and nothing downstream re-checks. `size` and
-     * `minimumSize` are cell counts; `ratio` is a share weight and keeps its
-     * fractions. Absence is preserved rather than parsed: an undefined `size`
-     * selects a flex pane, and `cellCount` would read it as a declared zero.
-     */
-    get ratio() {
-        return this._ratio;
-    }
-    set ratio(value) {
-        this._ratio = growthRatio(value);
-    }
-    get size() {
-        return this._size;
-    }
-    set size(value) {
-        this._size = value === undefined ? undefined : cellCount(value);
-    }
-    get minimumSize() {
-        return this._minimumSize;
-    }
-    set minimumSize(value) {
-        this._minimumSize = cellCount(value);
-    }
-    get children() {
-        return this._children;
-    }
-    /**
-     * Whether this layout draws `_renderable` or its children.
-     *
-     * [LAW:one-source-of-truth] `render` and `_naturalWidth` must answer this the
-     * same way. Asked separately they did not: `_naturalWidth` read it off the
-     * *visible* children, so a layout holding content and a single hidden child
-     * reported that content's width while `render` emitted nothing at all, and a
-     * fit-mode `Panel` framed twelve cells of air.
-     */
-    get _isLeaf() {
-        return this._children.length === 0;
-    }
-    splitColumn(...layouts) {
-        this._children = layouts;
-        this._splitDirection = "column";
-    }
-    splitRow(...layouts) {
-        this._children = layouts;
-        this._splitDirection = "row";
-    }
-    update(renderable) {
-        this._renderable = toRenderable(renderable);
-    }
-    getByName(name) {
-        if (this.name === name)
-            return this;
-        for (const child of this._children) {
-            const found = child.getByName(name);
-            if (found)
-                return found;
-        }
-        return undefined;
-    }
-    *render(rawOptions) {
-        if (!this.visible)
-            return;
-        // Parsed once at the top of the layout rather than at the row split below,
-        // because a column split forwards the width to its children untouched and
-        // would otherwise hand each of them the caller's raw number.
-        const options = withBoundedWidth(rawOptions, this);
-        if (this._isLeaf) {
-            // Cropped rather than forwarded: a leaf hands its content the offer and
-            // content is free to ignore it, and a pane wider than the region it was
-            // given is the one thing a layout may never emit — in a row split it
-            // overwrites the pane beside it. The row path already crops each share,
-            // so this is the same rule at the one place that skipped it.
-            if (this._renderable) {
-                yield* Segment.cropLines(this._renderable.render(options), options.maxWidth);
-            }
-            return;
-        }
-        const visibleChildren = this._children.filter((c) => c.visible);
-        if (visibleChildren.length === 0)
-            return;
-        if (this._splitDirection === "row") {
-            yield* this._renderRow(visibleChildren, options);
-        }
-        else {
-            yield* this._renderColumn(visibleChildren, options);
-        }
-    }
-    *_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);
-        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);
-        }
-    }
-    *_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`.
-        const widths = this._distributeSpace(children, options.maxWidth);
-        const cells = children.map((child, i) => ({
-            width: widths[i],
-            lines: Segment.splitLines([
-                ...child.render({ ...options, maxWidth: widths[i] }),
-            ]),
-        }));
-        yield* Segment.mergeHorizontal(cells);
-    }
-    _distributeSpace(children, totalSpace) {
-        const sizes = new Array(children.length).fill(0);
-        let remaining = totalSpace;
-        // Children that do not grow are paid first: a declared `size`, and equally
-        // a `ratio` of 0, which is the caller saying this pane stays at its
-        // `minimumSize`. Left in the ratio pass below, a zero-ratio child divided
-        // by its own ratio and drew its minimum out of a budget the shares had
-        // already spent — three panes of `zzz`/`aaaaa`/`bbbbb` consumed
-        // `3 + 2*floor(T/2)` cells out of `T`, which no `T` satisfies, and the row
-        // only came out right at 16 because the `Math.min(remaining, ...)` below
-        // happened to clip the last share to the right number.
-        const growing = [];
-        for (let i = 0; i < children.length; i++) {
-            const child = children[i];
-            if (child.size !== undefined) {
-                sizes[i] = Math.min(child.size, remaining);
-            }
-            else if (child.ratio === 0) {
-                sizes[i] = Math.min(child.minimumSize, remaining);
-            }
-            else {
-                growing.push(i);
-                continue;
-            }
-            remaining -= sizes[i];
-        }
-        // Distribute what is left by ratio. Each child's share comes off one
-        // budget and is bounded by what that budget still holds: `minimumSize` is
-        // what a child asks for, `remaining` is what there is to give, and the
-        // second beats the first. Applied without that bound — as
-        // `Math.max(minimumSize, share)` alone — every child claimed its whole
-        // minimum out of a budget that could not cover one of them, so two
-        // children of a Layout asked to fit one cell merged into a two-cell row.
-        if (growing.length > 0 && remaining > 0) {
-            const budget = remaining;
-            // Every ratio in here is positive — `growthRatio` parses the rest to zero
-            // at the constructor and zero is filtered out above — which is what makes
-            // the division safe and `_rowBudgetFor`'s inverse of it finite.
-            const totalRatio = growing.reduce((s, idx) => s + children[idx].ratio, 0);
-            for (const idx of growing) {
-                const child = children[idx];
-                const share = Math.floor(budget * child.ratio / totalRatio);
-                const allocated = Math.min(remaining, Math.max(child.minimumSize, share));
-                sizes[idx] = allocated;
-                remaining -= allocated;
-            }
-        }
-        return sizes;
-    }
-    /**
-     * The width this layout would take if nothing constrained it: its content's
-     * for a leaf, its children's laid out the way the split lays them out.
-     *
-     * A `size` counts only across a row, which is the one direction in which it
-     * is a width — down a column the same field is a height, and reading it as a
-     * width there would report a two-line pane as two cells wide.
-     */
-    _naturalWidth(options) {
-        if (!this.visible)
-            return 0;
-        if (this._isLeaf) {
-            if (this._renderable === undefined)
-                return 0;
-            // A leaf whose content cannot measure itself has no width of its own to
-            // report, so it reports the offer — unbounded included, which is where
-            // `withBoundedWidth` says so rather than inventing a number.
-            return isMeasurable(this._renderable)
-                ? Measurement.get(options, this._renderable).maximum
-                : options.maxWidth;
-        }
-        const visible = this._children.filter((c) => c.visible);
-        if (visible.length === 0)
-            return 0;
-        const widths = visible.map((c) => c._naturalWidth(options));
-        if (this._splitDirection === "row")
-            return this._rowBudgetFor(visible, widths);
-        // Accumulated, not spread: a column split holds as many children as a caller
-        // made, and `Math.max(...widths)` passes one argument per child, so a
-        // generated dashboard deep enough overruns the engine's argument limit and
-        // throws out of `measure()`.
-        let widest = 0;
-        for (const width of widths)
-            widest = Math.max(widest, width);
-        return widest;
-    }
-    /**
-     * The budget at which `_distributeSpace` gives every child of a row at least
-     * the width it wants — the inverse of the ratio rule above, and the reason
-     * this is not the sum of those widths.
-     *
-     * [LAW:one-source-of-truth] A growing child receives `floor(budget * ratio /
-     * totalRatio)`, so to receive `want` cells it needs the budget to reach
-     * `want * totalRatio / ratio`, and one budget serves them all: the row needs
-     * the largest demand, never their total. Summed instead, a 1:1 split of
-     * "left" and "right" reported 9 and then rendered "right" into the 4 cells
-     * that `floor(9/2)` actually hands it.
-     *
-     * The panes that do not grow are paid first here for the same reason they
-     * are paid first there — and it is the reason this divides by no zero: a
-     * `ratio` of 0 never reaches the division, because a pane that does not grow
-     * demands nothing of a budget for growing.
-     */
-    _rowBudgetFor(children, widths) {
-        const growing = children.filter((c) => c.size === undefined && c.ratio !== 0);
-        const totalRatio = growing.reduce((sum, c) => sum + c.ratio, 0);
-        let pinned = 0;
-        let budget = 0;
-        for (const [i, child] of children.entries()) {
-            if (child.size !== undefined) {
-                pinned += child.size;
-            }
-            else if (child.ratio === 0) {
-                pinned += child.minimumSize;
-            }
-            else {
-                const want = Math.max(child.minimumSize, widths[i]);
-                budget = Math.max(budget, Math.ceil(want * totalRatio / child.ratio));
-            }
-        }
-        return pinned + budget;
-    }
-    measure(rawOptions) {
-        // `minimumSize` is what this layout asks for and the ceiling is what it was
-        // offered; the ceiling wins. Unclamped, a layout measured into no width
-        // reported the range 1..0 — a floor above its own ceiling, which the parent
-        // that asked cannot divide.
-        //
-        // The ceiling alone was not the answer either: a layout that reported the
-        // whole offer as its maximum told every parent it wanted all of it, so
-        // `Panel` in fit mode drew its frame at the full console width around a
-        // layout of two short panes, and an unbounded offer came back unbounded.
-        const parsed = withCellWidth(rawOptions);
-        const maximum = Math.min(this._naturalWidth(parsed), parsed.maxWidth);
-        return { minimum: Math.min(this.minimumSize, maximum), maximum };
-    }
-}

package/dist/renderables/live.d.ts

@@ -1,47 +0,0 @@
-/**
- * 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.
- * - **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.
- */
-import { Console } from "../core/console.js";
-import type { Renderable } from "../core/protocol.js";
-export interface LiveOptions {
-    refreshPerSecond?: number;
-    autoRefresh?: boolean;
-    transient?: boolean;
-    console?: Console;
-    verticalOverflow?: "crop" | "ellipsis" | "visible";
-    /** When true, Live enters the alternate screen buffer on start() and
-     *  restores the original on stop(). Refresh uses cursor-home instead of
-     *  cursor-up-and-clear, eliminating flicker for full-screen layouts. */
-    altScreen?: boolean;
-}
-export declare class Live {
-    private _renderable;
-    private _console;
-    private _refreshPerSecond;
-    private _autoRefresh;
-    private _transient;
-    private _verticalOverflow;
-    private _altScreen;
-    private _timer;
-    private _lastLineCount;
-    private _started;
-    private _firstRefresh;
-    constructor(renderable?: Renderable, options?: LiveOptions);
-    get console(): Console;
-    get renderable(): Renderable | undefined;
-    start(): void;
-    stop(): void;
-    update(renderable?: Renderable, options?: {
-        refresh?: boolean;
-    }): void;
-    refresh(): void;
-    private _clearLast;
-    private _writeCursorControl;
-}

package/dist/renderables/live.js

@@ -1,131 +0,0 @@
-/**
- * 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.
- * - **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.
- */
-import { Console } from "../core/console.js";
-import { Segment } from "../core/segment.js";
-import { segmentsToString } from "../core/render.js";
-export class Live {
-    _renderable;
-    _console;
-    _refreshPerSecond;
-    _autoRefresh;
-    _transient;
-    _verticalOverflow;
-    _altScreen;
-    _timer;
-    _lastLineCount;
-    _started;
-    _firstRefresh;
-    constructor(renderable, options) {
-        this._renderable = renderable;
-        this._console = options?.console ?? new Console({ forceTerminal: true });
-        this._refreshPerSecond = options?.refreshPerSecond ?? 4;
-        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;
-    }
-    get console() {
-        return this._console;
-    }
-    get renderable() {
-        return this._renderable;
-    }
-    start() {
-        if (this._started)
-            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);
-        if (this._autoRefresh) {
-            const interval = Math.floor(1000 / this._refreshPerSecond);
-            this._timer = setInterval(() => this.refresh(), interval);
-        }
-    }
-    stop() {
-        if (!this._started)
-            return;
-        this._started = false;
-        if (this._timer) {
-            clearInterval(this._timer);
-            this._timer = undefined;
-        }
-        if (!this._transient) {
-            this.refresh();
-        }
-        else {
-            this._clearLast();
-        }
-        this._writeCursorControl(true);
-        if (this._altScreen) {
-            this._console.file.write("\x1b[0m\x1b[?1049l"); // reset attrs + exit alt screen
-        }
-    }
-    update(renderable, options) {
-        if (renderable !== undefined) {
-            this._renderable = renderable;
-        }
-        if (options?.refresh) {
-            this.refresh();
-        }
-    }
-    refresh() {
-        if (!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: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
-        // honor `colorSystem === null` (NO_COLOR, dumb terminal) the same way.
-        const colorSystem = this._console.colorSystem;
-        const output = displayLines
-            .map((line) => segmentsToString(line, colorSystem))
-            .join("\n");
-        this._console.file.write(output + "\n");
-        this._lastLineCount = 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;
-        }
-    }
-    _writeCursorControl(show) {
-        this._console.file.write(show ? "\x1b[?25h" : "\x1b[?25l");
-    }
-}

package/dist/renderables/markdown.d.ts

@@ -1,24 +0,0 @@
-/**
- * Markdown — renders Markdown content to the terminal.
- * Uses built-in parsing (no external dependency).
- */
-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;
-    inlineCodeStyle?: string | Style;
-    hyperlinks?: boolean;
-    justify?: "left" | "center" | "right" | "full";
-}
-export declare class Markdown implements Renderable, Measurable {
-    readonly markdown: string;
-    readonly inlineCodeStyle: string | Style;
-    readonly hyperlinks: boolean;
-    constructor(markdown: string, options?: MarkdownOptions);
-    render(options: RenderOptions): Iterable<Segment>;
-    measure(options: RenderOptions): {
-        minimum: number;
-        maximum: number;
-    };
-}