@promptctl/rich-js 0.18.0 → 0.18.1

package/dist/renderables/layout.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Layout — divides the screen into rectangular regions.
+ */
+import { Segment } from "../core/segment.js";
+import type { Renderable, Measurable, RenderOptions } from "../core/protocol.js";
+export interface LayoutOptions {
+    name?: string;
+    ratio?: number;
+    size?: number;
+    minimumSize?: number;
+    visible?: boolean;
+}
+export declare class Layout implements Renderable, Measurable {
+    name: string | undefined;
+    visible: boolean;
+    private _ratio;
+    private _size;
+    private _minimumSize;
+    private _renderable;
+    private _children;
+    private _splitDirection;
+    constructor(renderable?: Renderable | string, options?: LayoutOptions);
+    /**
+     * 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(): number;
+    set ratio(value: number);
+    get size(): number | undefined;
+    set size(value: number | undefined);
+    get minimumSize(): number;
+    set minimumSize(value: number);
+    get children(): Layout[];
+    /**
+     * 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.
+     */
+    private get _isLeaf();
+    splitColumn(...layouts: Layout[]): void;
+    splitRow(...layouts: Layout[]): void;
+    update(renderable: Renderable | string): void;
+    getByName(name: string): Layout | undefined;
+    render(rawOptions: RenderOptions): Iterable<Segment>;
+    private _renderColumn;
+    private _renderRow;
+    private _distributeSpace;
+    /**
+     * 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.
+     */
+    private _naturalWidth;
+    /**
+     * 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.
+     */
+    private _rowBudgetFor;
+    measure(rawOptions: RenderOptions): {
+        minimum: number;
+        maximum: number;
+    };
+}

package/dist/renderables/layout.js

@@ -0,0 +1,312 @@
+/**
+ * Layout — divides the screen into rectangular regions.
+ */
+import { Segment } from "../core/segment.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";
+/**
+ * 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;
+}
+/**
+ * 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;
+    visible;
+    _ratio;
+    _size;
+    _minimumSize;
+    _renderable;
+    _children;
+    _splitDirection;
+    constructor(renderable, options) {
+        if (renderable !== undefined) {
+            this._renderable = embed(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 = embed(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) {
+        // 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++) {
+            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: paneLines(child, { ...options, maxWidth: widths[i] }, region),
+        }));
+        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

@@ -0,0 +1,50 @@
+/**
+ * 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. 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";
+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 _overflow;
+    private _erase;
+    private _release;
+    private _writeCursorControl;
+}

package/dist/renderables/live.js

@@ -0,0 +1,175 @@
+/**
+ * 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. 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;
+    _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);
+            // 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;
+        // [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();
+            }
+        }
+        finally {
+            this._release();
+        }
+    }
+    update(renderable, options) {
+        if (renderable !== undefined) {
+            this._renderable = renderable;
+        }
+        if (options?.refresh) {
+            this.refresh();
+        }
+    }
+    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.
+        if (!this._started || !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 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;
+    }
+    // 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) {
+        this._console.file.write(show ? "\x1b[?25h" : "\x1b[?25l");
+    }
+}

package/dist/renderables/markdown.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 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(rawOptions: RenderOptions): Iterable<Segment>;
+    measure(options: RenderOptions): {
+        minimum: number;
+        maximum: number;
+    };
+}