@promptctl/rich-js 0.18.0 → 0.19.0

package/README.md

@@ -342,7 +342,7 @@ console.print(new Greeting());
 
 ```typescript
 const console = new Console({
-  colorSystem: "truecolor", // null | "auto" | "standard" | "256" | "truecolor" | "windows"
+  colorSystem: "truecolor", // null | "auto" | "none" | "ansi" | "256" | "truecolor"
   width: 120,               // override terminal width
   stderr: true,             // write to stderr
   record: true,             // record output for export
@@ -354,14 +354,15 @@ const console = new Console({
 When `record: true`, export output after the fact:
 
 ```typescript
-import { saveHtml } from "@promptctl/rich-js/node/save";
+import { SOLARIZED_LIGHT, SVG_EXPORT_THEME } from "@promptctl/rich-js";
+import { saveSvg } from "@promptctl/rich-js/node/save";
 
-const text = console.exportText();
-const html = console.exportHtml();
-saveHtml(console, "output.html");
+const text = console.exportText({ clear: false });
+const html = console.exportHtml({ theme: SOLARIZED_LIGHT, clear: false });
+saveSvg(console, "output.svg", { theme: SVG_EXPORT_THEME });
 ```
 
-`saveText` / `saveHtml` live on the `node/save` subpath because they import `node:fs`; the main barrel stays browser-safe.
+`saveText`, `saveHtml` and `saveSvg` live on the `node/save` subpath because they import `node:fs`; the main barrel stays browser-safe. The [console guide](https://brandon-fryslie.github.io/rich-js/master/console#exporting) covers what each export draws, the themes it takes, and when it clears the recording.
 
 ## Demos
 
@@ -384,8 +385,9 @@ npm run demo
 | `npm run demo-inputs` | rich-config | The widgets — checkbox, toggle, slider, dropdown, text input, button — driving a theme and palette viewer. |
 | `npm run demo:dropdown` | dropdown-demo | Three `Dropdown` widgets: a plain one, one filtered as you type, and one whose options change every few seconds. |
 | `npm run template-bindings` | rich-template-bindings | Type a template on the left and watch it render on the right. |
-| `npm run themes-and-color-studio` | themes-and-color-studio | A printed tour of colours, palettes, bundled themes, and contrast. Prints once and exits; set `EXPORT_HTML=out.html` to save it as HTML too. |
+| `npm run themes-and-color-studio` | themes-and-color-studio | A printed tour of colours, palettes, bundled themes, and contrast. Prints once and exits; set any of `EXPORT_HTML=out.html`, `EXPORT_SVG=out.svg` and `EXPORT_TEXT=out.txt` to also save it to each file named. |
 | `npm run strip` | rich-strip | Every built-in `Joiner`, printed side by side. Prints once and exits. |
+| `npm run effects-feel` | effects-feel | Shimmer, pulse, drift, sparkle, fade-in and dissolve-out on a powerline strip and a run of text, at a frame rate, colour depth and ground you choose. A demo for agreeing how the effects feel; `npm run effects-feel -- --help` lists the flags. |
 | `npm run markup-plugins` | rich-markup-plugins | Custom markup tags registered through `MarkupRegistry`. Prints once and exits. |
 | `npm run viewport` | rich-viewport | A cursor walking a list taller than its window, kept in view by `Viewport.ensureVisible`. |
 

package/dist/core/anchor.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Anchor — where a cell sat in the output of the thing that drew it.
+ *
+ * A widget nested inside a `Layout` cell inside a `Panel` does not know where
+ * it lands on screen, and nothing can tell it before it renders: `Align`
+ * centres each line only after rendering it, so the lines of one widget can
+ * start at different columns, and a `Viewport` shows whichever of its
+ * content's rows its offset selects. An origin handed down through the render
+ * options would be a number each container has to compute before it knows
+ * the answer, and one more thing every container must forward correctly.
+ *
+ * So the position travels up instead, on the cells themselves. The owner
+ * stamps each segment of its output with its row and column there
+ * (`Segment.anchorLines`), the stamp rides on the segment's `Style`, which
+ * every container already carries through untouched, and whoever holds the
+ * composed frame reads any cell's owner and position straight off it
+ * (`Segment.anchorAt`). Containers do nothing, so no container can get it
+ * wrong.
+ *
+ * [LAW:single-enforcer] Two things can falsify a stamp. Cutting a segment in
+ * two starts the right half at a later column than the stamp names:
+ * `Segment.splitCells` is where a segment is cut, and it shifts the right
+ * half's anchor (`shiftAnchor`); a crop that keeps the left half keeps a stamp
+ * that is already true. Laying the text out again moves every cell: a
+ * `RichText` does that, so it admits no anchor (`admitStyle` in `./text.ts`),
+ * and the owner that renders it stamps what it draws.
+ */
+/**
+ * The position of a segment's first cell in its owner's output, and the
+ * anchor that segment carried before this owner stamped it — the owner nested
+ * inside this one, if any. Innermost last: follow `inner` to reach the owner
+ * that drew the cell itself.
+ */
+export interface Anchor {
+    /** The thing that drew this cell, compared by identity. */
+    readonly owner: object;
+    readonly row: number;
+    readonly col: number;
+    readonly inner: Anchor | undefined;
+}
+/**
+ * The anchor of the cell `cells` to the right of the one `anchor` names, at
+ * every level of the nesting — each level names the same cell.
+ */
+export declare function shiftAnchor(anchor: Anchor, cells: number): Anchor;

package/dist/core/anchor.js

@@ -0,0 +1,39 @@
+/**
+ * Anchor — where a cell sat in the output of the thing that drew it.
+ *
+ * A widget nested inside a `Layout` cell inside a `Panel` does not know where
+ * it lands on screen, and nothing can tell it before it renders: `Align`
+ * centres each line only after rendering it, so the lines of one widget can
+ * start at different columns, and a `Viewport` shows whichever of its
+ * content's rows its offset selects. An origin handed down through the render
+ * options would be a number each container has to compute before it knows
+ * the answer, and one more thing every container must forward correctly.
+ *
+ * So the position travels up instead, on the cells themselves. The owner
+ * stamps each segment of its output with its row and column there
+ * (`Segment.anchorLines`), the stamp rides on the segment's `Style`, which
+ * every container already carries through untouched, and whoever holds the
+ * composed frame reads any cell's owner and position straight off it
+ * (`Segment.anchorAt`). Containers do nothing, so no container can get it
+ * wrong.
+ *
+ * [LAW:single-enforcer] Two things can falsify a stamp. Cutting a segment in
+ * two starts the right half at a later column than the stamp names:
+ * `Segment.splitCells` is where a segment is cut, and it shifts the right
+ * half's anchor (`shiftAnchor`); a crop that keeps the left half keeps a stamp
+ * that is already true. Laying the text out again moves every cell: a
+ * `RichText` does that, so it admits no anchor (`admitStyle` in `./text.ts`),
+ * and the owner that renders it stamps what it draws.
+ */
+/**
+ * The anchor of the cell `cells` to the right of the one `anchor` names, at
+ * every level of the nesting — each level names the same cell.
+ */
+export function shiftAnchor(anchor, cells) {
+    return {
+        owner: anchor.owner,
+        row: anchor.row,
+        col: anchor.col + cells,
+        inner: anchor.inner && shiftAnchor(anchor.inner, cells),
+    };
+}

package/dist/core/ansi.d.ts

@@ -0,0 +1,65 @@
+/**
+ * ANSI bytes back into styled text — a port of Rich's `AnsiDecoder`
+ * (rich/ansi.py) and `Text.from_ansi`.
+ *
+ * The rendering pipeline runs one way, `Style` → SGR bytes; this runs it
+ * backwards, for output some program already wrote: a capture of an example's
+ * own `new Console()`, a CLI's output shown inside a Panel, a log replayed into
+ * a Table cell.
+ *
+ * [LAW:types-are-the-program] Every colour decodes to the `ColorSpec` its
+ * escape names — `31` the standard colour 1, `38;5;n` palette index n,
+ * `38;2;r;g;b` that truecolor — and none is resolved to RGB here. A standard
+ * colour is a slot in whatever theme draws it, so one captured run exports
+ * correctly under a light theme and a dark one; resolved here, dark mode would
+ * show light mode's colours. Resolution belongs to `export-lines`.
+ *
+ * [LAW:types-are-the-program] The link is decoder state of its own, beside
+ * the SGR style, not a field of it: a terminal ends a hyperlink only at an OSC
+ * 8 close, and an SGR reset inside the link leaves it open. Rich keeps the
+ * link in the SGR style, so its reset drops it.
+ *
+ * Carriage returns are the other departure, and the same argument. Rich splits
+ * lines with Python's `splitlines`, which also breaks at `\r`, so its `a\rb`
+ * is two lines. Here a line ends only at `\n`, and `\r` returns to the first
+ * column, so later text overwrites earlier text character by character:
+ * `50%\r100%` is `100%`, `Downloading\rDone` is `Doneloading`, and `done\r`
+ * is still `done`. Columns are counted in characters, not cells, so a wide
+ * character overwritten by a narrow one is where this and a terminal differ.
+ * Erase in line (`\x1b[K`) is honoured for the same reason, because a redraw
+ * is usually `\r\x1b[K` and the old text must not show through a shorter new
+ * one.
+ *
+ * Everything else follows Rich: malformed SGR parameters are skipped rather
+ * than refused, and every other escape is dropped. It is not a terminal
+ * emulator — any other cursor movement is dropped, not performed.
+ *
+ * Tier 5 of `src/core/`: it builds `RichText`, so it sits above `text`, and
+ * `RichText` cannot offer a `fromAnsi` static without importing upward.
+ */
+import { RichText } from "./text.js";
+import type { RichTextOptions } from "./text.js";
+/**
+ * A stateful decoder: the style an escape sets carries on across lines, and
+ * across calls, as it does on a terminal. Use one decoder per stream and hand
+ * it whole lines, so output read a line at a time decodes as it would have
+ * all at once. It buffers nothing: a chunk cut mid-line or mid-escape decodes
+ * as the line it appears to be.
+ */
+export declare class AnsiDecoder {
+    private sgr;
+    private link;
+    /** One `RichText` per line of `ansi`; a final newline ends a line rather than starting one. */
+    decode(ansi: string): RichText[];
+    /**
+     * One line of output, holding no `\n`, written the way a terminal writes
+     * it: `\r` returns to the first column, and text overwrites from there.
+     */
+    decodeLine(line: string): RichText;
+}
+/**
+ * `ansi` as one `RichText`, its lines joined by `\n` — Rich's
+ * `Text.from_ansi`. `options` describe the result the way they describe any
+ * `RichText`.
+ */
+export declare function decodeAnsi(ansi: string, options?: RichTextOptions): RichText;

package/dist/core/ansi.js

@@ -0,0 +1,231 @@
+/**
+ * ANSI bytes back into styled text — a port of Rich's `AnsiDecoder`
+ * (rich/ansi.py) and `Text.from_ansi`.
+ *
+ * The rendering pipeline runs one way, `Style` → SGR bytes; this runs it
+ * backwards, for output some program already wrote: a capture of an example's
+ * own `new Console()`, a CLI's output shown inside a Panel, a log replayed into
+ * a Table cell.
+ *
+ * [LAW:types-are-the-program] Every colour decodes to the `ColorSpec` its
+ * escape names — `31` the standard colour 1, `38;5;n` palette index n,
+ * `38;2;r;g;b` that truecolor — and none is resolved to RGB here. A standard
+ * colour is a slot in whatever theme draws it, so one captured run exports
+ * correctly under a light theme and a dark one; resolved here, dark mode would
+ * show light mode's colours. Resolution belongs to `export-lines`.
+ *
+ * [LAW:types-are-the-program] The link is decoder state of its own, beside
+ * the SGR style, not a field of it: a terminal ends a hyperlink only at an OSC
+ * 8 close, and an SGR reset inside the link leaves it open. Rich keeps the
+ * link in the SGR style, so its reset drops it.
+ *
+ * Carriage returns are the other departure, and the same argument. Rich splits
+ * lines with Python's `splitlines`, which also breaks at `\r`, so its `a\rb`
+ * is two lines. Here a line ends only at `\n`, and `\r` returns to the first
+ * column, so later text overwrites earlier text character by character:
+ * `50%\r100%` is `100%`, `Downloading\rDone` is `Doneloading`, and `done\r`
+ * is still `done`. Columns are counted in characters, not cells, so a wide
+ * character overwritten by a narrow one is where this and a terminal differ.
+ * Erase in line (`\x1b[K`) is honoured for the same reason, because a redraw
+ * is usually `\r\x1b[K` and the old text must not show through a shorter new
+ * one.
+ *
+ * Everything else follows Rich: malformed SGR parameters are skipped rather
+ * than refused, and every other escape is dropped. It is not a terminal
+ * emulator — any other cursor movement is dropped, not performed.
+ *
+ * Tier 5 of `src/core/`: it builds `RichText`, so it sits above `text`, and
+ * `RichText` cannot offer a `fromAnsi` static without importing upward.
+ */
+import { ColorSpec } from "./color.js";
+import { osc8Sequences } from "./osc8.js";
+import { ATTRIBUTE_NAMES, ATTRIBUTE_SGR, NULL_STYLE, Style } from "./style.js";
+import { RichText } from "./text.js";
+/**
+ * Every escape but OSC 8, which `osc8Sequences` reads before this runs. In
+ * order: a carriage return; an SGR sequence (group 1, its parameters — a
+ * private marker such as the `>` of `\x1b[>4;2m` makes it some other CSI);
+ * erase in line (group 2, its mode); any other CSI sequence; any other string
+ * escape — OSC, DCS, APC, PM, SOS — run to the terminators OSC 8 accepts or
+ * cut off by the end of the line; any other escape, ECMA-48's intermediates
+ * and one final byte (`\x1b(B`, `\x1b)0`, `\x1b#8`, `\x1bc`). Only the first
+ * three become tokens.
+ */
+const ESCAPE = /\r|\x1b\[([0-9;:]*)m|\x1b\[([012]?)K|\x1b\[[0-?]*[ -/]*[@-~]|\x1b[\]P_^X][\s\S]*?(?:\x07|\x1b\\|\x9c|$)|\x1b[ -/]*[0-~]/g;
+function* escapeTokens(bytes) {
+    let at = 0;
+    for (const match of bytes.matchAll(ESCAPE)) {
+        if (match.index > at)
+            yield { kind: "text", text: bytes.slice(at, match.index) };
+        if (match[0] === "\r")
+            yield { kind: "return" };
+        if (match[1] !== undefined)
+            yield { kind: "sgr", params: match[1] };
+        if (match[2] !== undefined)
+            yield { kind: "erase", mode: (match[2] || "0") };
+        at = match.index + match[0].length;
+    }
+    if (at < bytes.length)
+        yield { kind: "text", text: bytes.slice(at) };
+}
+// [LAW:one-source-of-truth] OSC 8 is read by the reader `osc8.ts` owns, so
+// the terminators a link may end with cannot differ between writing and
+// reading it back.
+function* tokens(line) {
+    let at = 0;
+    for (const sequence of osc8Sequences(line)) {
+        yield* escapeTokens(line.slice(at, sequence.index));
+        yield { kind: "link", uri: sequence.uri };
+        at = sequence.index + sequence.length;
+    }
+    yield* escapeTokens(line.slice(at));
+}
+function adding(options) {
+    const added = new Style(options);
+    return (style) => style.add(added);
+}
+function next(rest) {
+    const step = rest.next();
+    return step.done ? undefined : step.value;
+}
+/**
+ * `5;n` or `2;r;g;b`, the arguments of `38` and `48`. A sequence cut short
+ * names no colour, and the codes it did consume are spent, as in Rich.
+ */
+function extendedColor(rest) {
+    const kind = next(rest);
+    if (kind === 5) {
+        const n = next(rest);
+        return n === undefined ? undefined : ColorSpec.fromAnsi(n);
+    }
+    if (kind === 2) {
+        const [r, g, b] = [next(rest), next(rest), next(rest)];
+        return b === undefined ? undefined : ColorSpec.fromRgb(r, g, b);
+    }
+    return undefined;
+}
+// [LAW:dataflow-not-control-flow] Every code is an operation on the style,
+// reset included; a code this table does not name is the identity.
+const SGR_OPS = new Map([
+    [0, () => NULL_STYLE],
+    // [LAW:one-source-of-truth] The codes that turn an attribute on are the
+    // ones `Style.toSgrCodes` writes; only the codes that turn one off are ours.
+    ...ATTRIBUTE_NAMES.map((name) => [ATTRIBUTE_SGR[name], adding({ [name]: true })]),
+    [22, adding({ bold: false, dim: false })],
+    [23, adding({ italic: false })],
+    // ECMA-48: 24 is "neither singly nor doubly underlined", 25 "steady" at
+    // either speed. Rich's table clears only the first of each pair.
+    [24, adding({ underline: false, underline2: false })],
+    [25, adding({ blink: false, blink2: false })],
+    [27, adding({ reverse: false })],
+    [28, adding({ conceal: false })],
+    [29, adding({ strike: false })],
+    [38, (style, rest) => style.add(new Style({ color: extendedColor(rest) }))],
+    [39, adding({ color: ColorSpec.default() })],
+    [48, (style, rest) => style.add(new Style({ bgcolor: extendedColor(rest) }))],
+    [49, adding({ bgcolor: ColorSpec.default() })],
+    // Underline colour has no field on Style; its arguments are still spent, or
+    // `58;2;1;2;3` would read on as bold, dim and italic.
+    [58, (style, rest) => (extendedColor(rest), style)],
+    [54, adding({ frame: false, encircle: false })],
+    [55, adding({ overline: false })],
+    ...Array.from({ length: 8 }, (_, n) => [
+        [30 + n, adding({ color: ColorSpec.fromAnsi(n) })],
+        [40 + n, adding({ bgcolor: ColorSpec.fromAnsi(n) })],
+        [90 + n, adding({ color: ColorSpec.fromAnsi(n + 8) })],
+        [100 + n, adding({ bgcolor: ColorSpec.fromAnsi(n + 8) })],
+    ]).flat(),
+]);
+const identity = (style) => style;
+/**
+ * `params` applied to `style`. An empty parameter is 0 and one above 255 is
+ * 255; one that is not a number — a colon sub-parameter — is skipped, as in
+ * Rich.
+ */
+function applySgr(style, params) {
+    const codes = params
+        .split(";")
+        .filter((code) => /^\d*$/.test(code))
+        .map((code) => Math.min(255, Number(code)))
+        .values();
+    let result = style;
+    for (const code of codes)
+        result = (SGR_OPS.get(code) ?? identity)(result, codes);
+    return result;
+}
+const BLANK = [" ", NULL_STYLE];
+/** Erase in line: the cells before the cursor go blank, the ones from it on go. */
+function erase(cells, column, mode) {
+    if (mode !== "0")
+        cells.fill(BLANK, 0, Math.min(column + 1, cells.length));
+    if (mode !== "1")
+        cells.length = Math.min(column, cells.length);
+}
+/**
+ * A stateful decoder: the style an escape sets carries on across lines, and
+ * across calls, as it does on a terminal. Use one decoder per stream and hand
+ * it whole lines, so output read a line at a time decodes as it would have
+ * all at once. It buffers nothing: a chunk cut mid-line or mid-escape decodes
+ * as the line it appears to be.
+ */
+export class AnsiDecoder {
+    sgr = NULL_STYLE;
+    link = undefined;
+    /** One `RichText` per line of `ansi`; a final newline ends a line rather than starting one. */
+    decode(ansi) {
+        return (ansi.match(/[^\n]*\n|[^\n]+/g) ?? []).map((line) => this.decodeLine(line.replace(/\r?\n$/, "")));
+    }
+    /**
+     * One line of output, holding no `\n`, written the way a terminal writes
+     * it: `\r` returns to the first column, and text overwrites from there.
+     */
+    decodeLine(line) {
+        const cells = [];
+        let column = 0;
+        for (const token of tokens(line)) {
+            switch (token.kind) {
+                case "text": {
+                    const style = this.sgr.withLink(this.link);
+                    for (const char of token.text)
+                        cells[column++] = [char, style];
+                    break;
+                }
+                case "return":
+                    column = 0;
+                    break;
+                case "erase":
+                    erase(cells, column, token.mode);
+                    break;
+                case "sgr":
+                    this.sgr = applySgr(this.sgr, token.params);
+                    break;
+                case "link":
+                    this.link = token.uri === "" ? undefined : token.uri;
+                    break;
+            }
+        }
+        const runs = [];
+        for (const [char, style] of cells) {
+            const last = runs.at(-1);
+            if (last?.[1].equals(style))
+                last[0] += char;
+            else
+                runs.push([char, style]);
+        }
+        return RichText.assemble(runs);
+    }
+}
+/**
+ * `ansi` as one `RichText`, its lines joined by `\n` — Rich's
+ * `Text.from_ansi`. `options` describe the result the way they describe any
+ * `RichText`.
+ */
+export function decodeAnsi(ansi, options) {
+    const result = new RichText("", options);
+    new AnsiDecoder().decode(ansi).forEach((line, index) => {
+        if (index > 0)
+            result.append("\n");
+        result.append(line);
+    });
+    return result;
+}

package/dist/core/box.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Box-drawing character sets for borders and table grids.
+ *
+ * A style is declared as an 8x4 character grid — one line per row a table can
+ * draw, one column per position within that row:
+ *
+ *     ┌─┬┐   top border
+ *     │ ││   header content
+ *     ├─┼┤   header separator
+ *     │ ││   body content
+ *     ├─┼┤   row separator
+ *     ├─┼┤   footer separator
+ *     │ ││   footer content
+ *     └─┴┘   bottom border
+ *
+ * [LAW:one-source-of-truth] The grid is the shape the reference implementation
+ * (Python Rich's `box.py`) publishes these glyphs in, so a constant below can
+ * be diffed against it character for character. The eighteen named fields this
+ * replaced were a second, differently-shaped map of the same territory, and it
+ * had drifted: seven of the nineteen constants carried wrong glyphs, and the
+ * field named `mid` held the reference's line 3 while the reference's `mid_*`
+ * is line 4 — so reading the reference name-for-name swapped a separator for a
+ * content row. Named row fields are gone for that reason; a row is reached by
+ * what it is (`getRow`, `getContentChars`), never by a name that can be
+ * mismatched to a line.
+ */
+import { Segment } from "./segment.js";
+import type { Style } from "./style.js";
+/** A rule spanning the table: the top and bottom borders, and every separator. */
+export interface EdgeChars {
+    left: string;
+    horizontal: string;
+    cross: string;
+    right: string;
+}
+/**
+ * The verticals framing a row of cells. A content line of the grid has no
+ * horizontal of its own — its fill column is a placeholder the cells occupy.
+ */
+export interface ContentChars {
+    left: string;
+    vertical: string;
+    right: string;
+}
+export type RowLevel = "head" | "row" | "foot" | "mid";
+export interface SubstituteOptions {
+    asciiOnly?: boolean;
+    safe?: boolean;
+}
+export declare class Box {
+    readonly top: EdgeChars;
+    readonly bottom: EdgeChars;
+    private readonly grid;
+    private readonly headContent;
+    private readonly headSeparator;
+    private readonly bodyContent;
+    private readonly rowSeparator;
+    private readonly footSeparator;
+    private readonly footContent;
+    /**
+     * [LAW:parse-dont-validate] The one crossing between a grid string and box
+     * glyphs. A `Box` cannot exist without eight rows of four characters, so no
+     * consumer below ever re-checks the shape of the data it reads.
+     */
+    constructor(grid: string);
+    /**
+     * Renders the top border row for given column widths.
+     */
+    getTop(widths: readonly number[], style?: Style, edge?: boolean): Segment[];
+    /**
+     * Renders the separator drawn *above* a row at `level` — the head separator
+     * under the header, the row separator between body rows, the foot separator
+     * above the footer.
+     */
+    getRow(widths: readonly number[], level: RowLevel, style?: Style, edge?: boolean): Segment[];
+    /**
+     * The verticals that frame a content row at `level` — the counterpart to
+     * `getRow`, which draws the separator between two such rows.
+     */
+    getContentChars(level: RowLevel): ContentChars;
+    /**
+     * Renders the bottom border row.
+     */
+    getBottom(widths: readonly number[], style?: Style, edge?: boolean): Segment[];
+    /**
+     * The box to draw with when the platform cannot render this one as written.
+     *
+     * `asciiOnly` gives up a box that spends non-ASCII glyphs for `ASCII`, and
+     * leaves the four already-ASCII styles as they are — a caller that chose
+     * MARKDOWN or ASCII_DOUBLE_HEAD asked for that frame and it is already
+     * drawable, so answering with `ASCII` would trade a frame the terminal
+     * supports for a different one it equally supports. `safe` squares off the
+     * rounded corners a legacy Windows terminal draws as blanks.
+     */
+    substitute(options?: SubstituteOptions): Box;
+    private safeSubstitute;
+    /**
+     * The nearest box that spends no special glyphs on a header — what a table
+     * with `showHeader: false` draws with. A box whose head row already matches
+     * its body is its own answer, so this is the identity for fourteen of the
+     * nineteen shipped styles.
+     *
+     * It stands beside `substitute` rather than joining it because the two ask
+     * unrelated questions: `substitute` asks what the *platform* can draw, this
+     * asks what the *table* contains. Nothing correlates them, so a caller that
+     * wants both wants both, and a shared options bag would only multiply the
+     * combinations either one has to reason about. [LAW:no-mode-explosion]
+     *
+     * [LAW:types-are-the-program] The relation is keyed on the grid, not on
+     * object identity as the reference's dict is. A `Box` is wholly determined by
+     * its grid — that is what the constructor takes and all eight rows derive
+     * from — so two boxes with one grid must answer this alike. Identity keying
+     * would say otherwise the moment a box arrived by any route but the shipped
+     * constant, and `safeSubstitute` above builds exactly such a box: a fresh
+     * instance carrying an unchanged grid.
+     */
+    plainHeaded(): Box;
+    /**
+     * [LAW:dataflow-not-control-flow] Every full-width rule the box can draw is
+     * this one join; which rule it is arrives as four characters, not a branch.
+     * The rule is one segment, as the reference's `get_top` is one string, so
+     * its bytes are one styled run.
+     */
+    private getEdge;
+    private getRowChars;
+}
+export declare const ASCII: Box;
+export declare const ASCII2: Box;
+export declare const ASCII_DOUBLE_HEAD: Box;
+export declare const SQUARE: Box;
+export declare const SQUARE_DOUBLE_HEAD: Box;
+export declare const MINIMAL: Box;
+export declare const MINIMAL_HEAVY_HEAD: Box;
+export declare const MINIMAL_DOUBLE_HEAD: Box;
+export declare const SIMPLE: Box;
+export declare const SIMPLE_HEAD: Box;
+export declare const SIMPLE_HEAVY: Box;
+export declare const HORIZONTALS: Box;
+export declare const ROUNDED: Box;
+export declare const HEAVY: Box;
+export declare const HEAVY_EDGE: Box;
+export declare const HEAVY_HEAD: Box;
+export declare const DOUBLE: Box;
+export declare const DOUBLE_EDGE: Box;
+export declare const MARKDOWN: Box;