@promptctl/rich-js 0.18.0 → 0.18.1

package/dist/core/protocol.d.ts

@@ -0,0 +1,267 @@
+/**
+ * Rendering protocol interfaces — Renderable, Measurable, RenderOptions.
+ * [LAW:one-source-of-truth] These interfaces are the single authority for the rendering contract.
+ */
+import type { Segment } from "./segment.js";
+import { type Style, type StyleSyntaxError, type Theme } from "./style.js";
+import type { ColorDepth } from "./color.js";
+/**
+ * What becomes of a line still wider than its width once wrapping is done.
+ * `"fold"` breaks it across lines, `"crop"` cuts it at the edge, `"ellipsis"`
+ * cuts it and marks the cut. `"ignore"` is not a way of cutting: the line has
+ * no edge, so nothing wraps it and nothing cuts it, and it leaves at its
+ * natural width for whatever drew it to crop or not.
+ *
+ * `noWrap` is the other half of Rich's pair and is not `"ignore"`: it stops the
+ * wrapping and leaves the edge, so a line too wide is cut by the method here.
+ */
+export type OverflowMethod = "fold" | "crop" | "ellipsis" | "ignore";
+export interface RenderOptions {
+    /**
+     * The cells this renderable may occupy. A count of cells, so a non-negative
+     * integer — but the field is a plain `number` because it is public API and a
+     * caller can write anything into it. `withCellWidth` is where that becomes
+     * true rather than assumed; see its comment for why every renderable must
+     * call it rather than trusting this declaration.
+     */
+    maxWidth: number;
+    minWidth?: number;
+    /**
+     * The rows this renderable may occupy. Absent, nothing limits them.
+     */
+    height?: Height;
+    isTerminal?: boolean;
+    /**
+     * The output can draw only ASCII. Every glyph a renderable chooses — box
+     * lines, tree guides, a check mark — is resolved through `drawable`. Text
+     * the caller hands in is drawn as given. Absent means the output draws any
+     * glyph.
+     */
+    asciiOnly?: boolean;
+    justify?: "left" | "center" | "right" | "full";
+    overflow?: OverflowMethod;
+    noWrap?: boolean;
+    highlight?: unknown;
+    markup?: unknown;
+    /**
+     * The depth the output will be encoded at, `null` when it carries no colour.
+     * A renderable choosing between two ways of drawing something — the strip's
+     * arrow or its divider — decides on the colours the terminal will draw at
+     * this depth, which at 256 colours or fewer are not the colours it was
+     * handed. Absent means truecolor.
+     */
+    colorSystem?: ColorDepth | null;
+    /**
+     * The names a style string may use. A `Console` passes its own; absent, the
+     * built-in defaults apply. Read it through `getStyle` rather than directly.
+     */
+    theme?: Theme;
+    /**
+     * Called each time a render degrades a style string it cannot parse to
+     * unstyled, once per resolution — a style the render reads twice is reported
+     * twice. Absent, the failure passes silently. A handler that throws makes
+     * the render strict: the error leaves `render`.
+     */
+    onStyleError?: StyleErrorHandler;
+    /**
+     * Told of each owner that stamps its output (`core/anchor`) as it starts to
+     * render, so the calls arrive in document order: a container's children in
+     * the order it renders them, an owner before the owners nested in it. A
+     * container forwards it by passing its options on, which every container
+     * does. An owner rendered twice is told twice. A render made to measure is
+     * not drawing and is not told (`measuring`).
+     */
+    onDraw?: (owner: object) => void;
+}
+/**
+ * `chosen` as this output can draw it: `ascii` in its place when the output is
+ * ASCII-only and `chosen` spends a glyph outside ASCII, otherwise `chosen`
+ * itself. Choosing a glyph that is already ASCII (a rule of `=`, a MARKDOWN box)
+ * picks a frame the terminal can draw, so it is kept. A set of glyphs that must
+ * change together — a box grid, a spinner's frames, a scrollbar — passes
+ * `glyphs` to say which characters it spends, and is replaced whole.
+ *
+ * [LAW:single-enforcer] The one place that decides what `asciiOnly` replaces.
+ * `test/renderables/ascii-only.test.ts` renders every exported renderable to
+ * hold each of them to it.
+ */
+export declare function drawable(options: {
+    readonly asciiOnly?: boolean;
+}, chosen: string, ascii: string): string;
+export declare function drawable<T>(options: {
+    readonly asciiOnly?: boolean;
+}, chosen: T, ascii: T, glyphs: (value: T) => string): T;
+/**
+ * A vertical budget: a count of rows, and whether they are a region the
+ * renderable stands in or a ceiling it stays under.
+ *
+ * `exact: true` is a region — a `Layout` pane, a full-screen frame. The output
+ * is exactly `rows` tall. A renderable may fill the region — a layout divides
+ * it, a frame can stretch to its last row — or ignore it and emit its natural
+ * height; either way, whoever set the region shapes what comes back to it
+ * (`fitHeight`). Setting a region is a promise to shape, so no renderable pads
+ * or crops itself to one.
+ *
+ * `exact: false` is a ceiling — the terminal an inline print lands on. Content
+ * keeps its natural height beneath it, and nothing pads up to the ceiling.
+ * Output taller than the ceiling is its setter's to handle: an inline `Live`
+ * applies its `verticalOverflow`, and a print lets the terminal scroll it.
+ *
+ * A renderable passing its whole space to one child must forward the budget
+ * less the rows it draws itself, and of the same kind (`insetHeight`). One
+ * stacking several children must hand each the rows as a ceiling
+ * (`stackedHeight`): any one of them may use all of it, and none may claim it
+ * as its region. Forwarded unchanged, a layout nested in a panel fills the
+ * panel's whole region and the region's crop takes the panel's bottom border.
+ *
+ * [LAW:types-are-the-program] One field, because the fact is one count and one
+ * bit about it. As two numbers, `height` and `maxHeight`, it admitted a region
+ * taller than its ceiling and a region with no ceiling at all, and the one
+ * reader in the library resolved them `maxHeight ?? height` — the ceiling ahead
+ * of the region it contains.
+ *
+ * There is no vertical `Measurable`. A parent chooses widths from its
+ * children's measurements before any of them renders; nothing chooses rows
+ * that way, because a renderable's height is a consequence of the width it
+ * renders at. Rendering and counting the lines is the measurement.
+ */
+export interface Height {
+    readonly rows: number;
+    readonly exact: boolean;
+}
+/**
+ * The budget a renderable hands the one child filling its space: its own, less
+ * the `rows` it draws itself, and of the same kind.
+ */
+export declare function insetHeight(height: Height | undefined, rows: number): Height | undefined;
+/**
+ * The budget a renderable hands each of several children it stacks: its rows,
+ * as a ceiling.
+ */
+export declare function stackedHeight(height: Height | undefined): Height | undefined;
+/**
+ * The rows a region holds, parsed as a cell count, or `undefined` when there
+ * is no region to fill: a ceiling, no budget, or a region of `Infinity` rows,
+ * which names no count — as an unbounded width resolves to a natural one in
+ * `withBoundedWidth`.
+ */
+export declare function regionRows(height: Height | undefined): number | undefined;
+/**
+ * What came back from a child, held to the region `height` names — blank rows
+ * padded below, overflow cropped from the bottom — or left at its own height
+ * when `height` is no region. This is the shaping a region's setter owes.
+ */
+export declare function fitHeight(lines: Segment[][], height: Height | undefined): Segment[][];
+/**
+ * Receives a style error a render would otherwise absorb: the parse failure,
+ * and the whole style string it came from — the error names only the token
+ * that failed, and `"bold rd"` loses its `bold` too.
+ *
+ * [LAW:no-mode-explosion] Strict mode is not a second option beside this one.
+ * It is a handler that throws, so there is no "strict and a callback" state
+ * whose order anyone has to define.
+ */
+export type StyleErrorHandler = (error: StyleSyntaxError, style: string) => void;
+/**
+ * The style a `string | Style` stands for in this render: a name from the
+ * theme of whatever is drawing, otherwise a style definition. A string that is
+ * neither throws `StyleSyntaxError`. This is how a renderable that yields its
+ * own `Segment`s draws with a theme name, since a `Segment` takes a resolved
+ * `Style`. It is Rich's `console.get_style`, asked of the options because the
+ * options are where the theme travels.
+ *
+ * [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 declare function getStyle(options: RenderOptions, style: string | Style): 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 declare function withCellWidth(options: RenderOptions): RenderOptions;
+/**
+ * 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.
+ */
+/**
+ * `options` as a measurement is asked with. A `measure` that renders to learn
+ * its shape draws nothing on the frame, so it reports no owner to `onDraw` —
+ * one that did would put a widget in document order at the moment a
+ * container measured it, and keep one the frame then cropped away.
+ *
+ * [LAW:single-enforcer] Every measurement starts here: `Measurement.get` and
+ * `withBoundedWidth` ask through it, and each `measure` passes it on.
+ */
+export declare function measuring(options: RenderOptions): RenderOptions;
+export declare function withBoundedWidth(options: RenderOptions, self: Measurable): RenderOptions;
+export interface Renderable {
+    render(options: RenderOptions): Iterable<Segment>;
+}
+export interface Measurable {
+    measure(options: RenderOptions): {
+        minimum: number;
+        maximum: number;
+    };
+}
+/**
+ * What the wheel scrolls: an owner of anchors on the frame (`./anchor.ts`)
+ * that moves by lines. `canScrollBy` says whether `scrollBy` with the same
+ * `lines` would move it; one that would not passes the wheel outward.
+ */
+export interface Scrollable {
+    canScrollBy(lines: number): boolean;
+    scrollBy(lines: number): void;
+}
+export declare function isRenderable(obj: unknown): obj is Renderable;
+export declare function isMeasurable(obj: unknown): obj is Measurable;
+export declare function isScrollable(obj: object): obj is Scrollable;

package/dist/core/protocol.js

@@ -0,0 +1,163 @@
+/**
+ * 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";
+const ASCII_TEXT = /^[\x00-\x7F]*$/;
+export function drawable(options, chosen, ascii, glyphs = String) {
+    return options.asciiOnly === true && !ASCII_TEXT.test(glyphs(chosen)) ? ascii : chosen;
+}
+/**
+ * The budget a renderable hands the one child filling its space: its own, less
+ * the `rows` it draws itself, and of the same kind.
+ */
+export function insetHeight(height, rows) {
+    return height && { rows: cellCount(height.rows - rows), exact: height.exact };
+}
+/**
+ * The budget a renderable hands each of several children it stacks: its rows,
+ * as a ceiling.
+ */
+export function stackedHeight(height) {
+    return height && { rows: cellCount(height.rows), exact: false };
+}
+/**
+ * The rows a region holds, parsed as a cell count, or `undefined` when there
+ * is no region to fill: a ceiling, no budget, or a region of `Infinity` rows,
+ * which names no count — as an unbounded width resolves to a natural one in
+ * `withBoundedWidth`.
+ */
+export function regionRows(height) {
+    return height?.exact && height.rows !== Infinity ? cellCount(height.rows) : undefined;
+}
+/**
+ * What came back from a child, held to the region `height` names — blank rows
+ * padded below, overflow cropped from the bottom — or left at its own height
+ * when `height` is no region. This is the shaping a region's setter owes.
+ */
+export function fitHeight(lines, height) {
+    const rows = regionRows(height) ?? lines.length;
+    const fitted = lines.slice(0, rows);
+    while (fitted.length < rows)
+        fitted.push([]);
+    return fitted;
+}
+/**
+ * The style a `string | Style` stands for in this render: a name from the
+ * theme of whatever is drawing, otherwise a style definition. A string that is
+ * neither throws `StyleSyntaxError`. This is how a renderable that yields its
+ * own `Segment`s draws with a theme name, since a `Segment` takes a resolved
+ * `Style`. It is Rich's `console.get_style`, asked of the options because the
+ * options are where the theme travels.
+ *
+ * [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.
+ */
+/**
+ * `options` as a measurement is asked with. A `measure` that renders to learn
+ * its shape draws nothing on the frame, so it reports no owner to `onDraw` —
+ * one that did would put a widget in document order at the moment a
+ * container measured it, and keep one the frame then cropped away.
+ *
+ * [LAW:single-enforcer] Every measurement starts here: `Measurement.get` and
+ * `withBoundedWidth` ask through it, and each `measure` passes it on.
+ */
+export function measuring(options) {
+    return { ...options, onDraw: undefined };
+}
+export function withBoundedWidth(options, self) {
+    const parsed = withCellWidth(options);
+    if (Number.isFinite(parsed.maxWidth))
+        return parsed;
+    const natural = self.measure(measuring(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");
+}
+export function isScrollable(obj) {
+    return ("canScrollBy" in obj &&
+        typeof obj.canScrollBy === "function" &&
+        "scrollBy" in obj &&
+        typeof obj.scrollBy === "function");
+}

package/dist/core/render.d.ts

@@ -0,0 +1,84 @@
+/**
+ * `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, RenderOptions } from "./protocol.js";
+export interface RenderToStringOptions extends Pick<RenderOptions, "asciiOnly" | "onStyleError"> {
+    /** 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

@@ -0,0 +1,145 @@
+/**
+ * `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,
+        asciiOnly: options?.asciiOnly ?? false,
+        onStyleError: options?.onStyleError,
+        // [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);
+}