@promptctl/rich-js 0.18.0 → 0.19.0

package/dist/core/protocol.d.ts

@@ -0,0 +1,305 @@
+/**
+ * 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 { ColorDepth } from "./color.js";
+import type { Highlighter } from "./highlighter.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;
+    /**
+     * Whether a string handed to a renderable — a cell, a label, a pane — is
+     * read as markup when it is drawn. Absent, it is, as a `Console`'s is unless
+     * told otherwise. A `Console` passes its own setting, and `print`'s.
+     */
+    markup?: boolean;
+    /**
+     * Whether a string handed to a renderable is highlighted when it is drawn,
+     * by `highlighter`. Absent, it is, as a `Console`'s is unless told
+     * otherwise. A `Console` passes its own setting, and `print`'s; a renderable
+     * that draws its strings plain, as Rich's `Panel`, `Table` and `Tree` do by
+     * default, sets it false for what it renders — Rich's
+     * `options.update(highlight=False)` — and a table column's `highlight` sets
+     * it either way. `activeHighlighter` is the one reading of the pair.
+     */
+    highlight?: boolean;
+    /**
+     * What highlights a string handed to a renderable, while `highlight` says
+     * to. A `Console` passes its highlighter whether or not its own `highlight`
+     * is on, as Rich's `render_str` reaches `console.highlighter`, so content
+     * that turns highlighting on finds the console's highlighter there. Absent,
+     * nothing highlights.
+     */
+    highlighter?: Highlighter;
+    /**
+     * 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;
+/**
+ * `style` as the depth the render is encoded at can draw it. A style that
+ * paints its own ground in fixed colours chose its ink and ground as a pair;
+ * at sixteen colours the writer rounds a fixed colour to an ANSI slot, which
+ * the terminal paints in its own theme's colour, and no pair of slots reads in
+ * every bundled theme. So where the depth would turn a fixed colour of the
+ * pair into a slot, the pair is dropped and the run is drawn on the
+ * terminal's own foreground and background, which its theme does make
+ * readable; its attributes still set it apart. A style whose colours are
+ * slots already (`white on blue`), or that paints no ground (`bold magenta`),
+ * was written for the terminal's own colours and is drawn as written. Rich
+ * draws a highlighted line number the same way below 256 colours
+ * (`Syntax._get_number_styles`).
+ */
+export declare function groundedStyle(options: RenderOptions, style: 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,183 @@
+/**
+ * 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);
+}
+/**
+ * `style` as the depth the render is encoded at can draw it. A style that
+ * paints its own ground in fixed colours chose its ink and ground as a pair;
+ * at sixteen colours the writer rounds a fixed colour to an ANSI slot, which
+ * the terminal paints in its own theme's colour, and no pair of slots reads in
+ * every bundled theme. So where the depth would turn a fixed colour of the
+ * pair into a slot, the pair is dropped and the run is drawn on the
+ * terminal's own foreground and background, which its theme does make
+ * readable; its attributes still set it apart. A style whose colours are
+ * slots already (`white on blue`), or that paints no ground (`bold magenta`),
+ * was written for the terminal's own colours and is drawn as written. Rich
+ * draws a highlighted line number the same way below 256 colours
+ * (`Syntax._get_number_styles`).
+ */
+export function groundedStyle(options, style) {
+    const drawn = style.drawnColors(options.colorSystem ?? undefined);
+    const lost = (written, shown) => written?.fixedValue !== undefined && shown?.fixedValue === undefined;
+    const pairLost = style.bgcolor !== undefined && (lost(style.color, drawn.color) || lost(style.bgcolor, drawn.bgcolor));
+    return pairLost ? style.withoutColor : 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,87 @@
+/**
+ * `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 `segmentToString`
+ * and is the single way a segment becomes wire bytes. `segmentsToString` is
+ * that encoding joined, and `Console._writeSegments`, `Painter` (every `Live`
+ * and `App` frame) and `renderToString` all go through it, so terminal output,
+ * live and app frames and string export 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.
+ *
+ * Every segment is written alone, exactly as Python Rich 9d8f9a3 writes it
+ * (`Console._render_buffer` calls `Style.render` per segment): its SGR codes
+ * open, its text, a reset, and an OSC 8 pair around all three when it carries
+ * a link. Two adjacent segments with equal codes are two runs, not one. That
+ * costs a reset and a reopen the terminal draws identically, and it is what
+ * lets a fixture generated from the reference hold any sequence of segments,
+ * rather than only those in which no two neighbours happen to share a style
+ * (rich-render-g5g8). The price of that is that where a renderable cuts its
+ * segments is now in the bytes, so a renderable pinned against the reference
+ * has to cut where the reference cuts, as `Box`'s rules and `Table`'s blank
+ * cell lines do. A link split across segments still hovers as one link,
+ * because every pair it becomes carries the id `osc8Open` derives from the URL.
+ *
+ * Colour and hyperlinks are two facts about the destination:
+ * `colorSystem === null` empties every segment's SGR codes, and
+ * `hyperlinks === false` drops every segment's link. A colour depth never
+ * removes a link — a hyperlink is not a colour, and a NO_COLOR terminal still
+ * follows OSC 8. This is where the port departs from the reference, whose
+ * `Style.render` returns bare text for a null colour system.
+ */
+import { ColorDepth } from "./color.js";
+import type { ColorSystemName, Destination } from "./color.js";
+import type { Env } from "./env.js";
+import type { Segment } from "./segment.js";
+import type { Renderable, RenderOptions } from "./protocol.js";
+export interface RenderToStringOptions extends Pick<RenderOptions, "asciiOnly" | "theme" | "onStyleError" | "highlight" | "highlighter"> {
+    /** Cell width to render into. Default 80. */
+    width?: number;
+    /**
+     * Color encoding to emit. Accepts a `ColorSystemName` (`"auto"`,
+     * `"truecolor"`, `"256"`, `"ansi"`, `"none"`), a `ColorDepth` enum value, or `null` to
+     * strip SGR colors/attributes. Hyperlinks are `hyperlinks`' concern. Default
+     * truecolor.
+     */
+    colorSystem?: ColorSystemName | ColorDepth | null;
+    /**
+     * Environment to consult when `colorSystem` is `"auto"`. Defaults to
+     * `process.env`. Pass an explicit value to keep rendering deterministic.
+     */
+    env?: Env;
+    /**
+     * 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 one segment as ANSI bytes for `destination`: the reference's
+ * `Style.render` for that segment, and nothing for a control segment.
+ */
+export declare function segmentToString(segment: Segment, destination: Destination): string;
+/** Encodes a sequence of segments as ANSI bytes for `destination`, one segment at a time. */
+export declare function segmentsToString(segments: Iterable<Segment>, destination: Destination): string;
+export declare function renderToString(renderable: Renderable, options?: RenderToStringOptions): string;