@promptctl/rich-js 0.17.0 → 0.18.0

package/dist/core/protocol.js

@@ -1,101 +0,0 @@
-/**
- * Rendering protocol interfaces — Renderable, Measurable, RenderOptions.
- * [LAW:one-source-of-truth] These interfaces are the single authority for the rendering contract.
- */
-import { cellCount } from "./cells.js";
-import { DEFAULT_THEME } from "./style.js";
-/**
- * The style a `string | Style` stands for in this render.
- *
- * [LAW:single-enforcer] Every renderable resolves a style name here, at render
- * time, because only the render knows whose theme it is drawing for. Resolved
- * when a renderable was built instead, a name was fixed to the built-in
- * defaults before any `Console` could offer its theme, and `new Console({
- * theme })` changed nothing.
- */
-export function getStyle(options, style) {
-    return (options.theme ?? DEFAULT_THEME).resolve(style);
-}
-/**
- * The options a renderable should work from: the caller's, with `maxWidth`
- * parsed into an actual count of cells.
- *
- * [LAW:parse-dont-validate] The stamp has to travel, which is the whole reason
- * this returns options rather than a number. Parsing `options.maxWidth` into a
- * local leaves the caller's raw value sitting in `options` for whatever the
- * renderable forwards it to — and every renderable forwards it, to a child's
- * `render`, to `Measurement.get`, to a nested layout. `Columns` was fixed that
- * way first and still threw `Invalid array length` on a NaN width, because it
- * handed the unparsed original to `Measurement.get` and got a NaN column count
- * back. Replace the field, and nothing downstream can see the number the
- * caller actually wrote.
- *
- * [LAW:single-enforcer] This is the width checkpoint for the render contract.
- * There is no second one: a renderable that re-derives its own answer is how
- * `Panel`, `Table`, `Tree`, `Columns` and `Layout` came to disagree about what
- * a NaN width means — one collapsed to a cell of garbage, two threw, one
- * ignored the request and emitted its full natural width.
- */
-export function withCellWidth(options) {
-    return { ...options, maxWidth: cellCount(options.maxWidth) };
-}
-/**
- * The options a renderable should *lay out against*: `withCellWidth`, with an
- * unbounded offer resolved to the renderable's own natural width.
- *
- * [LAW:parse-dont-validate] `cellCount` cannot finish the job alone. It floors
- * a negative width and NaN to zero from the number alone, but `Infinity` is not
- * a quantity it can floor — the only finite answer is "as wide as this
- * renderable's content wants", which is a question about the renderable and not
- * about the number. So the parse is completed here, where the renderable is in
- * hand, and the stamped options travel exactly as `withCellWidth`'s do.
- *
- * [LAW:single-enforcer] One checkpoint for the whole rule, not one per
- * renderable. `Panel`, `Padding`, `Columns` and `Layout` each expand into the
- * width they are offered, and each independently reached `" ".repeat(Infinity)`
- * — Columns twice over, since its column *count* is derived from the width too
- * and `new Array(Infinity)` throws a different error again.
- *
- * The natural width comes from `measure`, which every one of them already
- * implements, and the recursion terminates because `measure` reports content
- * rather than the offer: `Panel.measure({maxWidth: Infinity})` is `{9, 9}` for
- * nine cells of content and frame, not `{9, Infinity}`.
- *
- * So this belongs at the top of `render` and never at the top of `measure`:
- * `measure` is the method being asked, and asking it through here would ask it
- * with itself. `measure` parses with `withCellWidth` and reports a natural
- * width of its own — that is the half of the contract that makes this half work.
- *
- * A `maximum` of `Infinity` means the renderable genuinely cannot answer. Two
- * ways in: it wraps a `Renderable` with no `measure`, so nothing in the tree
- * knows how wide the content wants to be; or something inside it asked for an
- * unbounded width of its own, as a `Table` column declared
- * `{ ratio: Infinity }` does. [LAW:no-silent-failure] Both are unanswerable
- * rather than zero, and saying so names the cause — where `String.repeat` and
- * `new Array` only ever name their own argument.
- */
-export function withBoundedWidth(options, self) {
-    const parsed = withCellWidth(options);
-    if (Number.isFinite(parsed.maxWidth))
-        return parsed;
-    const natural = self.measure(parsed).maximum;
-    if (!Number.isFinite(natural)) {
-        throw new RangeError("maxWidth is unbounded and this renderable has no natural width to fall " +
-            "back on: its content does not implement measure(), or something inside " +
-            "it asked for an unbounded width of its own. Render it at a finite " +
-            "width, or give the content a measure() that reports a finite maximum.");
-    }
-    return { ...parsed, maxWidth: cellCount(natural) };
-}
-export function isRenderable(obj) {
-    return (typeof obj === "object" &&
-        obj !== null &&
-        "render" in obj &&
-        typeof obj.render === "function");
-}
-export function isMeasurable(obj) {
-    return (typeof obj === "object" &&
-        obj !== null &&
-        "measure" in obj &&
-        typeof obj.measure === "function");
-}

package/dist/core/render.d.ts

@@ -1,84 +0,0 @@
-/**
- * `renderToString` — stateless one-shot emission of a `Renderable` to a string
- * of ANSI-encoded text. Pure function: same inputs produce byte-identical
- * output. Does not write to `process.stdout` and does not require a `Console`
- * instance.
- *
- * Note on `colorSystem: "auto"`: the `"auto"` spec resolves via
- * `detectColorSystem`, which reads `process.env` and `process.stdout?.isTTY`
- * by default. Callers that want a fully deterministic render must either pass
- * an explicit `ColorDepth` enum / non-`"auto"` spec, or supply `env` and
- * `isTTY` in the options so detection does not consult ambient process state.
- *
- * [LAW:single-enforcer] The Segment-to-ANSI conversion lives in `segmentsToString`
- * and is the single way segments become wire bytes. `Console._writeSegments`,
- * `Live.refresh`, `Screen`'s frame paint, `renderToString`, and
- * `segmentToString` all delegate here, so terminal output, live frames, widget
- * frames, string export, and single-segment encoding agree by construction.
- *
- * [LAW:one-source-of-truth] What the encoding needs from where it writes
- * arrives as one `Destination` value. Each caller resolves its destination
- * once — spec, detection, and its own overrides — and hands it through whole,
- * so a depth is never paired with a link setting taken from somewhere else.
- *
- * [LAW:dataflow-not-control-flow] The same pipeline runs every render: collect
- * non-control non-empty pieces, partition by SGR-codes (SGR-runs), partition
- * each run by link (link-runs), emit one SGR open/close per run with link
- * open/close pairs sitting inside. Colour and hyperlinks are two facts about
- * the destination: `colorSystem === null` empties every piece's SGR-codes, and
- * `hyperlinks === false` empties every piece's link. A colour depth never
- * removes a link — a hyperlink is not a colour, and a NO_COLOR terminal still
- * follows OSC 8.
- *
- * [LAW:types-are-the-program] Adjacent same-style segments share an SGR wrap
- * because the SGR-codes string is the same group key for both — the
- * partitioning shape (data) encodes the byte structure; the emit walk is a
- * mechanical fold over it.
- */
-import { ColorDepth } from "./color.js";
-import type { Destination } from "./color.js";
-import type { Segment } from "./segment.js";
-import type { Renderable } from "./protocol.js";
-export interface RenderToStringOptions {
-    /** Cell width to render into. Default 80. */
-    width?: number;
-    /**
-     * Color encoding to emit. Accepts a string spec (`"auto"`, `"truecolor"`,
-     * `"256"`, `"ansi"`, `"none"`), a `ColorDepth` enum value, or `null` to
-     * strip SGR colors/attributes. Hyperlinks are `hyperlinks`' concern. Default
-     * truecolor.
-     */
-    colorSystem?: string | ColorDepth | null;
-    /**
-     * Environment to consult when `colorSystem` is `"auto"`. Defaults to
-     * `process.env`. Pass an explicit value to keep rendering deterministic.
-     */
-    env?: NodeJS.ProcessEnv;
-    /**
-     * Whether output is going to a TTY when `colorSystem` is `"auto"`. Defaults
-     * to `process.stdout?.isTTY`. Pass an explicit value to keep rendering
-     * deterministic.
-     */
-    isTTY?: boolean;
-    /** When true, forces `colorSystem` to `null` regardless of the explicit value. */
-    noColor?: boolean;
-    /**
-     * Whether OSC 8 hyperlinks are emitted. Independent of `colorSystem`: a
-     * null colour system strips SGR and keeps links. Default: what the
-     * destination takes — true for an explicit depth, detected under `"auto"`
-     * (no TTY or TERM=dumb: false). `false` with `colorSystem: null` is plain text.
-     */
-    hyperlinks?: boolean;
-}
-/**
- * Encodes a single segment as ANSI bytes for `destination`. Equivalent to
- * `segmentsToString([segment], destination)` — same SGR / OSC 8 layout.
- */
-export declare function segmentToString(segment: Segment, destination: Destination): string;
-/**
- * Encodes a sequence of segments as ANSI bytes for `destination`, coalescing
- * adjacent same-SGR segments under a single SGR open/close pair, with OSC 8
- * link pairs nested inside per same-link sub-run.
- */
-export declare function segmentsToString(segments: Iterable<Segment>, destination: Destination): string;
-export declare function renderToString(renderable: Renderable, options?: RenderToStringOptions): string;

package/dist/core/render.js

@@ -1,145 +0,0 @@
-/**
- * `renderToString` — stateless one-shot emission of a `Renderable` to a string
- * of ANSI-encoded text. Pure function: same inputs produce byte-identical
- * output. Does not write to `process.stdout` and does not require a `Console`
- * instance.
- *
- * Note on `colorSystem: "auto"`: the `"auto"` spec resolves via
- * `detectColorSystem`, which reads `process.env` and `process.stdout?.isTTY`
- * by default. Callers that want a fully deterministic render must either pass
- * an explicit `ColorDepth` enum / non-`"auto"` spec, or supply `env` and
- * `isTTY` in the options so detection does not consult ambient process state.
- *
- * [LAW:single-enforcer] The Segment-to-ANSI conversion lives in `segmentsToString`
- * and is the single way segments become wire bytes. `Console._writeSegments`,
- * `Live.refresh`, `Screen`'s frame paint, `renderToString`, and
- * `segmentToString` all delegate here, so terminal output, live frames, widget
- * frames, string export, and single-segment encoding agree by construction.
- *
- * [LAW:one-source-of-truth] What the encoding needs from where it writes
- * arrives as one `Destination` value. Each caller resolves its destination
- * once — spec, detection, and its own overrides — and hands it through whole,
- * so a depth is never paired with a link setting taken from somewhere else.
- *
- * [LAW:dataflow-not-control-flow] The same pipeline runs every render: collect
- * non-control non-empty pieces, partition by SGR-codes (SGR-runs), partition
- * each run by link (link-runs), emit one SGR open/close per run with link
- * open/close pairs sitting inside. Colour and hyperlinks are two facts about
- * the destination: `colorSystem === null` empties every piece's SGR-codes, and
- * `hyperlinks === false` empties every piece's link. A colour depth never
- * removes a link — a hyperlink is not a colour, and a NO_COLOR terminal still
- * follows OSC 8.
- *
- * [LAW:types-are-the-program] Adjacent same-style segments share an SGR wrap
- * because the SGR-codes string is the same group key for both — the
- * partitioning shape (data) encodes the byte structure; the emit walk is a
- * mechanical fold over it.
- */
-import { ColorDepth, resolveDestination } from "./color.js";
-import { OSC8_CLOSE, osc8Open } from "./osc8.js";
-const DEFAULT_WIDTH = 80;
-function segmentToPiece(segment, destination) {
-    if (segment.isControl)
-        return undefined;
-    if (segment.text.length === 0)
-        return undefined;
-    const style = segment.style;
-    if (!style || style.isNull) {
-        return { text: segment.text, sgrCodes: "", link: undefined };
-    }
-    // [LAW:one-type-per-behavior] Colour depth governs SGR only; hyperlinks are
-    // their own fact. Coupling them let a colour setting delete every control.
-    return {
-        text: segment.text,
-        sgrCodes: destination.colorSystem === null ? "" : style.toSgrCodes(destination.colorSystem),
-        link: destination.hyperlinks ? style.link : undefined,
-    };
-}
-/**
- * Encodes a single segment as ANSI bytes for `destination`. Equivalent to
- * `segmentsToString([segment], destination)` — same SGR / OSC 8 layout.
- */
-export function segmentToString(segment, destination) {
-    return segmentsToString([segment], destination);
-}
-/**
- * Encodes a sequence of segments as ANSI bytes for `destination`, coalescing
- * adjacent same-SGR segments under a single SGR open/close pair, with OSC 8
- * link pairs nested inside per same-link sub-run.
- */
-export function segmentsToString(segments, destination) {
-    const pieces = [];
-    for (const s of segments) {
-        const p = segmentToPiece(s, destination);
-        if (p)
-            pieces.push(p);
-    }
-    if (pieces.length === 0)
-        return "";
-    // [LAW:dataflow-not-control-flow] One linear chunk accumulator for the
-    // entire output; SGR / OSC 8 boundaries and piece texts all push into it
-    // in order. No per-link-run intermediate string, no quadratic `+=` chains.
-    const parts = [];
-    let i = 0;
-    while (i < pieces.length) {
-        const sgr = pieces[i].sgrCodes;
-        let j = i + 1;
-        while (j < pieces.length && pieces[j].sgrCodes === sgr)
-            j++;
-        if (sgr.length > 0)
-            parts.push(`\x1b[${sgr}m`);
-        let k = i;
-        while (k < j) {
-            const link = pieces[k].link;
-            let l = k + 1;
-            while (l < j && pieces[l].link === link)
-                l++;
-            if (link) {
-                parts.push(osc8Open(link));
-                for (let m = k; m < l; m++)
-                    parts.push(pieces[m].text);
-                parts.push(OSC8_CLOSE);
-            }
-            else {
-                for (let m = k; m < l; m++)
-                    parts.push(pieces[m].text);
-            }
-            k = l;
-        }
-        if (sgr.length > 0)
-            parts.push("\x1b[0m");
-        i = j;
-    }
-    return parts.join("");
-}
-export function renderToString(renderable, options) {
-    const width = options?.width ?? DEFAULT_WIDTH;
-    // [LAW:dataflow-not-control-flow] An absent spec is truecolor; an explicit
-    // `null` stays null (`??` would collapse it).
-    // [LAW:single-enforcer] Specs resolve through `resolveDestination`.
-    const detectOptions = {};
-    if (options?.env !== undefined)
-        detectOptions.env = options.env;
-    if (options?.isTTY !== undefined)
-        detectOptions.isTTY = options.isTTY;
-    const rawSpec = options?.colorSystem;
-    const resolved = resolveDestination(rawSpec === undefined ? ColorDepth.TRUECOLOR : rawSpec, detectOptions);
-    // [LAW:single-enforcer] This call's overrides are applied here, once, to
-    // make the one destination everything below is drawn for. `noColor` is a
-    // colour choice, so it overrides the depth and leaves hyperlinks to the
-    // destination; an explicit `hyperlinks` overrides what the destination takes.
-    const destination = {
-        colorSystem: options?.noColor ? null : resolved.colorSystem,
-        hyperlinks: options?.hyperlinks ?? resolved.hyperlinks,
-    };
-    const renderOptions = {
-        maxWidth: width,
-        isTerminal: false,
-        encoding: "utf-8",
-        asciiOnly: false,
-        // [LAW:one-source-of-truth] The depth the segments below are encoded at,
-        // so a renderable measures what this very call will draw.
-        colorSystem: destination.colorSystem,
-    };
-    return segmentsToString(renderable.render(renderOptions), destination);
-}

package/dist/core/segment.d.ts

@@ -1,142 +0,0 @@
-/**
- * Segment — the atomic rendering unit. Every piece of styled terminal output
- * is represented as a Segment: (text, style?, control?).
- */
-import { type CellCol } from "./cells.js";
-import { Style } from "./style.js";
-export declare enum ControlType {
-    BELL = "bell",
-    CARRIAGE_RETURN = "carriage_return",
-    HOME = "home",
-    CLEAR = "clear",
-    SHOW_CURSOR = "show_cursor",
-    HIDE_CURSOR = "hide_cursor",
-    ENABLE_ALT_SCREEN = "enable_alt_screen",
-    DISABLE_ALT_SCREEN = "disable_alt_screen",
-    CURSOR_UP = "cursor_up",
-    CURSOR_DOWN = "cursor_down",
-    CURSOR_FORWARD = "cursor_forward",
-    CURSOR_BACKWARD = "cursor_backward",
-    CURSOR_MOVE_TO_COLUMN = "cursor_move_to_column",
-    CURSOR_MOVE_TO = "cursor_move_to",
-    ERASE_IN_LINE = "erase_in_line",
-    SET_WINDOW_TITLE = "set_window_title"
-}
-export type ControlCode = [ControlType, ...unknown[]];
-export declare class Segment {
-    readonly text: string;
-    readonly style: Style | undefined;
-    readonly control: ControlCode[] | undefined;
-    constructor(text: string, style?: Style, control?: ControlCode[]);
-    get cellLength(): number;
-    get hasText(): boolean;
-    get isControl(): boolean;
-    /**
-     * Splits at a cell position. Returns [left, right].
-     */
-    splitCells(position: CellCol): [Segment, Segment];
-    private static _line;
-    static line(): Segment;
-    /**
-     * Yields segments with combined styles.
-     */
-    static applyStyle(segments: Iterable<Segment>, style?: Style, postStyle?: Style): Iterable<Segment>;
-    /**
-     * Filters segments by control status.
-     */
-    static filterControl(segments: Iterable<Segment>, isControl: boolean): Iterable<Segment>;
-    /**
-     * Splits segments at newlines. Yields arrays of segments per line.
-     */
-    static splitLines(segments: Iterable<Segment>): Segment[][];
-    /**
-     * Adjusts a line of segments to exactly `width` cells.
-     */
-    static adjustLineLength(line: Segment[], width: number, style?: Style, pad?: boolean): Segment[];
-    /**
-     * Crops a renderable's output so no line exceeds `width`, leaving short lines
-     * alone and the line structure exactly as it arrived.
-     *
-     * [LAW:single-enforcer] `adjustLineLength` is where a width is enforced, but
-     * it takes one line and a container holding arbitrary content has a stream of
-     * them. Without this step the container has to trust content to honour the
-     * offer, and content that ignores it overflows the region — which is how a
-     * `Layout` leaf and a `Tree` label came to emit forty cells into a one-cell
-     * offer while `Panel` and `Padding`, which split and adjust, did not.
-     *
-     * One segment in, one segment out, shortening text and nothing else — so the
-     * line structure that arrives is the line structure that leaves. Two earlier
-     * shapes of this both decided how many lines there were and both were wrong:
-     * built on `splitLines`, which cannot tell `"abc"` from `"abc\n"`, it invented
-     * a trailing newline and dropped the row of an empty `Tree` label entirely,
-     * running its guides into the next row; rebuilt to accumulate lines, it
-     * dropped the zero-width-but-present line `RichText` emits at an offer of 0,
-     * and a row split rendered nothing at all. A crop shortens; it does not count.
-     *
-     * A wide glyph the edge cuts through leaves a space in the cell it would have
-     * half-filled, so a cropped line still reaches the edge — the reference's
-     * `set_cell_size`, which `splitText` already is. An unbounded `width` crops
-     * nothing, and a segment the crop did not change leaves as itself.
-     */
-    static cropLines(segments: Iterable<Segment>, width: number): Iterable<Segment>;
-    /**
-     * Returns total cell width of a line. Ignores control segments.
-     */
-    static getLineLength(line: Segment[]): number;
-    /**
-     * Returns [width, height] of a set of lines.
-     */
-    static getShape(lines: Segment[][]): [number, number];
-    /**
-     * Composes cells side by side into full lines. Each cell contributes its
-     * own lines cropped/padded to its declared width; a cell shorter than the
-     * tallest is filled with blank space so the grid stays aligned. Adjacent
-     * cells are separated by a gutter of spaces, and each merged row ends with a
-     * line break. This is the single side-by-side merge used by every horizontal
-     * layout (Columns grid rows, Layout row splits).
-     */
-    static mergeHorizontal(cells: readonly {
-        readonly lines: Segment[][];
-        readonly width: number;
-    }[], gutter?: number): Iterable<Segment>;
-    /**
-     * Merges contiguous segments with the same style.
-     */
-    static simplify(segments: Iterable<Segment>): Iterable<Segment>;
-    /**
-     * Yields segments with links removed.
-     */
-    static stripLinks(segments: Iterable<Segment>): Iterable<Segment>;
-    /**
-     * Yields segments with all styles removed.
-     */
-    static stripStyles(segments: Iterable<Segment>): Iterable<Segment>;
-    /**
-     * Yields segments with colors removed but attributes preserved.
-     */
-    static removeColor(segments: Iterable<Segment>): Iterable<Segment>;
-    /**
-     * Divides segments at cell positions. Yields arrays of segments for each section.
-     */
-    static divide(segments: Segment[], cuts: number[]): Segment[][];
-    /**
-     * Pads below to fill height.
-     */
-    static alignTop(lines: Segment[][], width: number, height: number, style: Style): Segment[][];
-    /**
-     * Pads above to fill height. Content at bottom.
-     */
-    static alignBottom(lines: Segment[][], width: number, height: number, style: Style): Segment[][];
-    /**
-     * Pads above and below. Content in middle.
-     */
-    static alignMiddle(lines: Segment[][], width: number, height: number, style: Style): Segment[][];
-    /**
-     * Forces lines to exactly width x height.
-     */
-    static setShape(lines: Segment[][], width: number, height: number, style?: Style): Segment[][];
-    /**
-     * Splits segments into lines and adjusts each to exactly `width` cells.
-     */
-    static splitAndCropLines(segments: Iterable<Segment>, width: number, pad?: boolean, includeNewLines?: boolean, style?: Style): Segment[][];
-}