@promptctl/rich-js 0.18.0 → 0.18.1

package/dist/core/export-lines.d.ts

@@ -0,0 +1,121 @@
+/**
+ * export-lines — recorded segments resolved against a `TerminalTheme` into the
+ * lines every exporter draws.
+ *
+ * The HTML and SVG exporters are two encodings of one picture, and this module
+ * is the picture. What a styled cell *looks like* — which colour its glyph is,
+ * whether its background is painted, which decorations it carries, where it
+ * links — is decided here, once, and an exporter decides only how to write
+ * that down. Before it existed the decision was made twice, by a CSS method
+ * on `Style` and by a private converter on `Console`, and the two had already
+ * disagreed: one honoured `underline2`, the other dropped it.
+ *
+ * [LAW:types-are-the-program] `ExportLook` has no `reverse`, `dim`, `conceal`
+ * or default colour, because all four are consumed by `resolveLook` and turned
+ * into plain RGB. An exporter holding a look cannot forget to swap a reversed
+ * run or to fade a dim one: there is nothing left in its hands to forget. That
+ * is the whole reason the representation is resolved rather than a `Style`
+ * handed through.
+ *
+ * Runs rather than a cell grid. A grid gives a wide character a phantom
+ * continuation cell every consumer must know to skip, and gives an HTML
+ * exporter — which lays text out by flowing it — nothing it needs. A run's
+ * column and cell width are `cellLen` of the text before it and of its own
+ * text; they are not stored, so they cannot disagree with the text
+ * [LAW:one-source-of-truth]. The SVG exporter, the one consumer that positions
+ * anything, derives them.
+ *
+ * Browser-safe by construction: this imports `color`, `style`, `segment` and
+ * nothing that touches the host, so `Console` can reach it from the main
+ * barrel and the fs half of exporting stays in `src/node/save.ts`.
+ */
+import { type ColorRgba, type TerminalTheme } from "./color.js";
+import { type Style } from "./style.js";
+import type { Segment } from "./segment.js";
+declare const _href: unique symbol;
+/**
+ * A link target that is safe to write into a published document.
+ *
+ * [LAW:parse-dont-validate] Only `parseHref` produces one, so an exporter that
+ * writes an `href` attribute from an `Href` cannot have skipped the check.
+ */
+export type Href = string & {
+    readonly [_href]: true;
+};
+/**
+ * Where a run's background comes from. `"canvas"` is the theme background
+ * showing through — nothing painted — and is distinct from a painted colour
+ * that happens to equal it, because `on default` and `on #000000` are
+ * different requests even over a black theme.
+ */
+export type Background = ColorRgba | "canvas";
+/** Everything an exporter needs to draw one run, and nothing left to resolve. */
+export interface ExportLook {
+    readonly foreground: ColorRgba;
+    readonly background: Background;
+    readonly bold: boolean;
+    readonly italic: boolean;
+    readonly underline: "none" | "single" | "double";
+    readonly strike: boolean;
+    readonly overline: boolean;
+    readonly blink: "none" | "slow" | "fast";
+    readonly outline: "none" | "frame" | "encircle";
+    readonly href: Href | null;
+}
+export interface ExportRun {
+    readonly text: string;
+    readonly look: ExportLook;
+}
+/** One terminal row, left to right. An empty array is a blank row. */
+export type ExportLine = readonly ExportRun[];
+/**
+ * `Style.link` as a link an export may write, or `null` when it may not.
+ *
+ * A refused link loses only its target: the run keeps its text and every other
+ * attribute, so nothing the terminal showed disappears from the export. The
+ * canonical `URL.href` is what comes back, since the parse is what vouches for
+ * it.
+ */
+export declare function parseHref(link: string): Href | null;
+/** What an unstyled cell shows under a theme: the canvas, and ink on it. */
+export interface ExportCanvas {
+    readonly background: ColorRgba;
+    readonly foreground: ColorRgba;
+}
+/**
+ * The ground every export is drawn on under `theme`.
+ *
+ * An exporter paints its page or window with this; `resolveLook` flattens
+ * every run over the same `background`, so a run showing the canvas and the
+ * page around it cannot come out different colours.
+ */
+export declare function exportCanvas(theme?: TerminalTheme): ExportCanvas;
+/**
+ * A `Style` as it appears on screen under `theme`.
+ *
+ * The order is the terminal's: colours resolve through the theme and lose
+ * their alpha — paper over the canvas, ink over the paper, as `toSgrCodes`
+ * flattens them — `reverse` swaps them, `dim` fades the glyph toward whatever
+ * background it ended up on, and `conceal` finally paints the glyph in that
+ * background. Every step after flattening works on opaque colour, so no
+ * exporter ever draws a translucent one. Text under `conceal` is still
+ * present, and still selectable, in both formats.
+ *
+ * The one difference from `toSgrCodes` is the substrate: a terminal cannot
+ * know what lies under its cells and assumes black, while an export draws its
+ * own canvas and flattens over that.
+ *
+ * `theme` omitted is `ColorSpec.getTruecolor`'s own fallback — black canvas,
+ * white ink, the standard ANSI table. Choosing it there rather than naming a
+ * preset here is what keeps `core/` from a third upward edge into `themes/`.
+ */
+export declare function resolveLook(style: Style, theme?: TerminalTheme): ExportLook;
+/**
+ * Recorded segments as terminal rows under `theme`.
+ *
+ * `"\n"` ends a row, so output that ends with a newline — every `print` does —
+ * has no empty row after it, and `"a\n\nb"` keeps its blank row. Callers pass
+ * the recording buffer, which already holds no control segments.
+ */
+export declare function exportLines(segments: Iterable<Segment>, theme?: TerminalTheme): ExportLine[];
+export {};

package/dist/core/export-lines.js

@@ -0,0 +1,141 @@
+/**
+ * export-lines — recorded segments resolved against a `TerminalTheme` into the
+ * lines every exporter draws.
+ *
+ * The HTML and SVG exporters are two encodings of one picture, and this module
+ * is the picture. What a styled cell *looks like* — which colour its glyph is,
+ * whether its background is painted, which decorations it carries, where it
+ * links — is decided here, once, and an exporter decides only how to write
+ * that down. Before it existed the decision was made twice, by a CSS method
+ * on `Style` and by a private converter on `Console`, and the two had already
+ * disagreed: one honoured `underline2`, the other dropped it.
+ *
+ * [LAW:types-are-the-program] `ExportLook` has no `reverse`, `dim`, `conceal`
+ * or default colour, because all four are consumed by `resolveLook` and turned
+ * into plain RGB. An exporter holding a look cannot forget to swap a reversed
+ * run or to fade a dim one: there is nothing left in its hands to forget. That
+ * is the whole reason the representation is resolved rather than a `Style`
+ * handed through.
+ *
+ * Runs rather than a cell grid. A grid gives a wide character a phantom
+ * continuation cell every consumer must know to skip, and gives an HTML
+ * exporter — which lays text out by flowing it — nothing it needs. A run's
+ * column and cell width are `cellLen` of the text before it and of its own
+ * text; they are not stored, so they cannot disagree with the text
+ * [LAW:one-source-of-truth]. The SVG exporter, the one consumer that positions
+ * anything, derives them.
+ *
+ * Browser-safe by construction: this imports `color`, `style`, `segment` and
+ * nothing that touches the host, so `Console` can reach it from the main
+ * barrel and the fs half of exporting stays in `src/node/save.ts`.
+ */
+import { blendRgb, ColorSpec } from "./color.js";
+import { NULL_STYLE } from "./style.js";
+/**
+ * The URL schemes an export will link.
+ *
+ * A terminal hands an OSC 8 target to the user's opener; an exported page hands
+ * it to whoever loads the page, and exports are made to be published. A
+ * `javascript:` target that was inert in a terminal is script in a README. The
+ * list is an allowance, not a denylist, so a scheme nobody considered is
+ * refused rather than trusted.
+ */
+const LINKABLE_SCHEMES = new Set(["http:", "https:", "mailto:", "ftp:", "file:"]);
+/**
+ * `Style.link` as a link an export may write, or `null` when it may not.
+ *
+ * A refused link loses only its target: the run keeps its text and every other
+ * attribute, so nothing the terminal showed disappears from the export. The
+ * canonical `URL.href` is what comes back, since the parse is what vouches for
+ * it.
+ */
+export function parseHref(link) {
+    if (!URL.canParse(link))
+        return null;
+    const url = new URL(link);
+    return LINKABLE_SCHEMES.has(url.protocol) ? url.href : null;
+}
+/**
+ * How far a dim glyph moves toward its background — Rich's own factor, so an
+ * export of the same program matches the library this ports.
+ */
+const DIM_FADE = 0.4;
+const DEFAULT_COLOR = ColorSpec.default();
+/**
+ * The ground every export is drawn on under `theme`.
+ *
+ * An exporter paints its page or window with this; `resolveLook` flattens
+ * every run over the same `background`, so a run showing the canvas and the
+ * page around it cannot come out different colours.
+ */
+export function exportCanvas(theme) {
+    return {
+        background: DEFAULT_COLOR.getTruecolor(theme, false),
+        foreground: DEFAULT_COLOR.getTruecolor(theme, true),
+    };
+}
+/**
+ * A `Style` as it appears on screen under `theme`.
+ *
+ * The order is the terminal's: colours resolve through the theme and lose
+ * their alpha — paper over the canvas, ink over the paper, as `toSgrCodes`
+ * flattens them — `reverse` swaps them, `dim` fades the glyph toward whatever
+ * background it ended up on, and `conceal` finally paints the glyph in that
+ * background. Every step after flattening works on opaque colour, so no
+ * exporter ever draws a translucent one. Text under `conceal` is still
+ * present, and still selectable, in both formats.
+ *
+ * The one difference from `toSgrCodes` is the substrate: a terminal cannot
+ * know what lies under its cells and assumes black, while an export draws its
+ * own canvas and flattens over that.
+ *
+ * `theme` omitted is `ColorSpec.getTruecolor`'s own fallback — black canvas,
+ * white ink, the standard ANSI table. Choosing it there rather than naming a
+ * preset here is what keeps `core/` from a third upward edge into `themes/`.
+ */
+export function resolveLook(style, theme) {
+    const inkSpec = style.color ?? DEFAULT_COLOR;
+    const paperSpec = style.bgcolor ?? DEFAULT_COLOR;
+    const canvas = exportCanvas(theme).background;
+    // [LAW:single-enforcer] `flattenAlpha` is the one place alpha is composited.
+    const paper = paperSpec.flattenAlpha(canvas).getTruecolor(theme, false);
+    const ink = inkSpec.flattenAlpha(paper).getTruecolor(theme, true);
+    // A reversed run always paints: its background is the ink, which is never
+    // the canvas, even when the ink is the theme's default foreground.
+    const glyph = style.reverse ? paper : ink;
+    const ground = style.reverse ? ink : paper;
+    const background = style.reverse || !paperSpec.isDefault ? ground : "canvas";
+    const faded = style.dim ? blendRgb(glyph, ground, DIM_FADE) : glyph;
+    return {
+        foreground: style.conceal ? ground : faded,
+        background,
+        bold: style.bold === true,
+        italic: style.italic === true,
+        underline: style.underline2 ? "double" : style.underline ? "single" : "none",
+        strike: style.strike === true,
+        overline: style.overline === true,
+        blink: style.blink2 ? "fast" : style.blink ? "slow" : "none",
+        outline: style.encircle ? "encircle" : style.frame ? "frame" : "none",
+        href: style.link === undefined ? null : parseHref(style.link),
+    };
+}
+/**
+ * Recorded segments as terminal rows under `theme`.
+ *
+ * `"\n"` ends a row, so output that ends with a newline — every `print` does —
+ * has no empty row after it, and `"a\n\nb"` keeps its blank row. Callers pass
+ * the recording buffer, which already holds no control segments.
+ */
+export function exportLines(segments, theme) {
+    const rows = [[]];
+    for (const segment of segments) {
+        const look = resolveLook(segment.style ?? NULL_STYLE, theme);
+        segment.text.split("\n").forEach((piece, index) => {
+            if (index > 0)
+                rows.push([]);
+            if (piece.length > 0)
+                rows[rows.length - 1].push({ text: piece, look });
+        });
+    }
+    return rows[rows.length - 1].length === 0 ? rows.slice(0, -1) : rows;
+}

package/dist/core/highlighter.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Highlighters — apply styled spans to RichText based on pattern matching.
+ */
+import { RichText } from "./text.js";
+export declare abstract class Highlighter {
+    abstract highlight(text: RichText): void;
+    call(input: string): RichText;
+}
+export declare class NullHighlighter extends Highlighter {
+    highlight(_text: RichText): void;
+}
+export declare class RegexHighlighter extends Highlighter {
+    static highlights: (string | RegExp)[];
+    /** Style applied to matches. When ending with "." it acts as a namespace
+     *  prefix: named groups become `baseStyle + groupName` (e.g. "repr." + "url"
+     *  → "repr.url"). Otherwise it's used as a literal style for all matches
+     *  (e.g. "bold red" applies "bold red" to every named group). */
+    static baseStyle: string;
+    highlight(text: RichText): void;
+}
+export declare class ReprHighlighter extends RegexHighlighter {
+    static baseStyle: string;
+    static highlights: RegExp[];
+}
+export declare class JSONHighlighter extends RegexHighlighter {
+    static baseStyle: string;
+    static highlights: string[];
+    highlight(text: RichText): void;
+}
+export declare class ISO8601Highlighter extends RegexHighlighter {
+    static baseStyle: string;
+    static highlights: RegExp[];
+}

package/dist/core/highlighter.js

@@ -0,0 +1,124 @@
+/**
+ * Highlighters — apply styled spans to RichText based on pattern matching.
+ */
+import { RichText } from "./text.js";
+// --- Base ---
+export class Highlighter {
+    call(input) {
+        const text = new RichText(input);
+        this.highlight(text);
+        return text;
+    }
+}
+// --- NullHighlighter ---
+export class NullHighlighter extends Highlighter {
+    highlight(_text) {
+        // No-op
+    }
+}
+// --- RegexHighlighter ---
+export class RegexHighlighter extends Highlighter {
+    static highlights = [];
+    /** Style applied to matches. When ending with "." it acts as a namespace
+     *  prefix: named groups become `baseStyle + groupName` (e.g. "repr." + "url"
+     *  → "repr.url"). Otherwise it's used as a literal style for all matches
+     *  (e.g. "bold red" applies "bold red" to every named group). */
+    static baseStyle = "";
+    highlight(text) {
+        const ctor = this.constructor;
+        const baseStyle = ctor.baseStyle;
+        // Namespace mode: "repr." + groupName → "repr.url"
+        // Literal mode: "bold red" → applied directly to every match
+        const isNamespace = baseStyle.endsWith(".");
+        for (const pattern of ctor.highlights) {
+            const re = pattern instanceof RegExp
+                ? new RegExp(pattern.source, pattern.flags.includes("g") ? pattern.flags : pattern.flags + "g")
+                : new RegExp(pattern, "g");
+            let match;
+            while ((match = re.exec(text.plain)) !== null) {
+                if (match[0].length === 0) {
+                    re.lastIndex++;
+                    continue;
+                }
+                if (match.groups) {
+                    let searchFrom = 0;
+                    for (const [groupName, groupValue] of Object.entries(match.groups)) {
+                        if (groupValue !== undefined) {
+                            const posInMatch = match[0].indexOf(groupValue, searchFrom);
+                            if (posInMatch >= 0) {
+                                const start = match.index + posInMatch;
+                                const style = isNamespace
+                                    ? `${baseStyle}${groupName}`
+                                    : baseStyle || groupName;
+                                text.stylize(style, start, start + groupValue.length);
+                                searchFrom = posInMatch + groupValue.length;
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+}
+// --- ReprHighlighter ---
+// [LAW:one-type-per-behavior] All repr patterns use the same RegexHighlighter mechanism
+export class ReprHighlighter extends RegexHighlighter {
+    static baseStyle = "repr.";
+    static highlights = [
+        // URLs
+        /(?<url>https?:\/\/[^\s<>"']+)/g,
+        // UUIDs
+        /(?<uuid>[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})/gi,
+        // Quoted strings
+        /(?<str>'[^']*'|"[^"]*")/g,
+        // Booleans
+        /(?<bool>\btrue\b|\bfalse\b)/g,
+        // None/null/undefined
+        /(?<none>\bnull\b|\bundefined\b|\bNone\b)/g,
+        // Numbers (integers and floats)
+        /(?<number>(?<!\w)-?(?:0x[0-9a-f]+|\d+(?:\.\d+)?(?:e[+-]?\d+)?)(?!\w))/gi,
+    ];
+}
+// --- JSONHighlighter ---
+// A JSON string as Python Rich 9d8f9a3 matches one, `b` bytes prefix included:
+// an opening quote with no backslash or word character before it, through the
+// first quote with no backslash before it, so an escaped quote stays inside.
+const JSON_STR = String.raw `(?<![\\\w])(?<str>b?".*?(?<!\\)")`;
+export class JSONHighlighter extends RegexHighlighter {
+    static baseStyle = "json.";
+    // [LAW:dataflow-not-control-flow] One alternation, scanned once, as Rich's
+    // `_combine_regex` joins it. A token claims its characters where the scan
+    // meets it, so the `true` and `12` inside `"true 12"` belong to the string.
+    static highlights = [
+        [
+            String.raw `(?<brace>[\{\[\(\)\]\}])`,
+            String.raw `\b(?<bool_true>true)\b|\b(?<bool_false>false)\b|\b(?<null>null)\b`,
+            String.raw `(?<number>(?<!\w)\-?[0-9]+\.?[0-9]*(e[\-\+]?\d+?)?\b|0x[0-9a-fA-F]*)`,
+            JSON_STR,
+        ].join("|"),
+    ];
+    // A string followed by a colon is also a key. Its `json.key` span comes after
+    // its `json.str` span, so the key style lands on top. Each string is found on
+    // its own and then checked for a colon. One `string(?=:)` pattern would get
+    // this wrong: its lazy body can stretch past a value's closing quote to the
+    // next key's, marking `"b", "c"` in `{"a": "b", "c": 1}` as one key.
+    highlight(text) {
+        super.highlight(text);
+        const colon = /[ \n\r\t]*:/y;
+        for (const { index, 0: str } of text.plain.matchAll(new RegExp(JSON_STR, "g"))) {
+            const end = index + str.length;
+            colon.lastIndex = end;
+            if (colon.test(text.plain))
+                text.stylize("json.key", index, end);
+        }
+    }
+}
+// --- ISO8601Highlighter ---
+export class ISO8601Highlighter extends RegexHighlighter {
+    static baseStyle = "iso8601.";
+    static highlights = [
+        /(?<date>\d{4}-\d{2}-\d{2})/g,
+        /(?<time>\d{2}:\d{2}:\d{2}(?:\.\d+)?)/g,
+        /(?<timezone>[+-]\d{2}:\d{2}|Z)/g,
+    ];
+}

package/dist/core/json.d.ts

@@ -0,0 +1,27 @@
+/**
+ * JSON — renders JSON data with syntax highlighting and pretty-printing.
+ *
+ * Lives in `core/` for the reason `pretty.ts` does, argued in its header: it
+ * turns foreign input into `RichText`, composes no other renderable, and
+ * imports core primitives only. `Console.printJson` delegates here, so this is
+ * where the console can reach it without an upward edge. [LAW:one-way-deps]
+ */
+import { Segment } from "./segment.js";
+import { RichText } from "./text.js";
+import type { Renderable, Measurable, RenderOptions } from "./protocol.js";
+export interface JSONOptions {
+    indent?: number;
+    sortKeys?: boolean;
+    highlight?: boolean;
+}
+export declare class JSONRenderable implements Renderable, Measurable {
+    readonly text: RichText;
+    private constructor();
+    static fromString(jsonString: string, options?: JSONOptions): JSONRenderable;
+    static fromData(data: unknown, options?: JSONOptions): JSONRenderable;
+    render(options: RenderOptions): Iterable<Segment>;
+    measure(options: RenderOptions): {
+        minimum: number;
+        maximum: number;
+    };
+}

package/dist/core/json.js

@@ -0,0 +1,53 @@
+/**
+ * JSON — renders JSON data with syntax highlighting and pretty-printing.
+ *
+ * Lives in `core/` for the reason `pretty.ts` does, argued in its header: it
+ * turns foreign input into `RichText`, composes no other renderable, and
+ * imports core primitives only. `Console.printJson` delegates here, so this is
+ * where the console can reach it without an upward edge. [LAW:one-way-deps]
+ */
+import { RichText } from "./text.js";
+import { JSONHighlighter } from "./highlighter.js";
+const highlighter = new JSONHighlighter();
+export class JSONRenderable {
+    text;
+    constructor(text) {
+        this.text = text;
+    }
+    static fromString(jsonString, options) {
+        const indent = options?.indent ?? 2;
+        const sortKeys = options?.sortKeys ?? false;
+        // Parse and re-serialize for consistent formatting
+        const data = JSON.parse(jsonString);
+        return JSONRenderable.fromData(data, { ...options, indent, sortKeys });
+    }
+    static fromData(data, options) {
+        const indent = options?.indent ?? 2;
+        const sortKeys = options?.sortKeys ?? false;
+        const doHighlight = options?.highlight !== false;
+        const replacer = sortKeys
+            ? (_key, value) => {
+                if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+                    const sorted = {};
+                    for (const k of Object.keys(value).sort()) {
+                        sorted[k] = value[k];
+                    }
+                    return sorted;
+                }
+                return value;
+            }
+            : undefined;
+        const jsonStr = JSON.stringify(data, replacer, indent);
+        const text = new RichText(jsonStr, { end: "" });
+        if (doHighlight) {
+            highlighter.highlight(text);
+        }
+        return new JSONRenderable(text);
+    }
+    *render(options) {
+        yield* this.text.render(options);
+    }
+    measure(options) {
+        return this.text.measure(options);
+    }
+}

package/dist/core/markup.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Markup — BBCode-inspired markup parser for inline styling.
+ * Parses `[bold red]text[/bold red]` into RichText with styled spans.
+ *
+ * Plugin tags ([LAW:locality-or-seam]): a `MarkupRegistry` lets consumers
+ * register tag handlers without forking the parser. When the parser sees
+ * `[name attrs...]inner[/name]` and `name` is registered, it parses attrs,
+ * recursively renders the inner markup as a child Renderable, and calls the
+ * handler — splicing the handler's returned Renderable into the output. The
+ * built-in style dialect and the plugin dialect are routed by the registry,
+ * which is the single trust boundary between them.
+ *
+ * Plugin pairs must nest. The built-in dialect admits non-strict nesting
+ * (`[bold]a[italic]b[/bold]c[/italic]`) because a style is an annotation and
+ * annotations may overlap freely; a plugin tag is a replacement whose handler
+ * takes one contiguous `inner`, so an overlapping pair has no slice to hand it
+ * and is rejected with a `MarkupSyntaxError`.
+ */
+import { Style } from "./style.js";
+import { RichText } from "./text.js";
+export declare class Tag {
+    readonly name: string;
+    readonly parameters: string | undefined;
+    constructor(name: string, parameters?: string);
+    toString(): string;
+    get markup(): string;
+}
+export declare class MarkupError extends Error {
+    constructor(message: string);
+}
+/**
+ * A markup string that cannot be parsed, with where it went wrong.
+ *
+ * [LAW:types-are-the-program] A subclass rather than optional fields on
+ * `MarkupError`, because the parent is also what `MarkupRegistry.register`
+ * throws, and a registration has no source text to point into. Every error this
+ * class describes has a location, so none of its fields is optional and no
+ * caller has to ask whether one is present — `instanceof` is the only question.
+ *
+ * [LAW:one-source-of-truth] The constructor takes the facts the parser holds —
+ * the string, the offset of the offending tag, what was open — and derives
+ * `line`, `column` and the message from them, so the numbers a caller reads
+ * and the caret the message draws cannot disagree.
+ */
+export declare class MarkupSyntaxError extends MarkupError {
+    /** The problem alone, with no location, for callers building their own message. */
+    readonly reason: string;
+    /** The whole markup string that failed, as the caller passed it. */
+    readonly markup: string;
+    /** Index into `markup` of the tag the parser rejected. */
+    readonly offset: number;
+    /** 1-based line of `offset`; lines are separated by `\n`. */
+    readonly line: number;
+    /** 1-based column of `offset` within its line, in UTF-16 code units. */
+    readonly column: number;
+    /**
+     * The opening tags still open at `offset`, outermost first, as written. For
+     * overlapping plugin tags, only plugin tags are named.
+     */
+    readonly openTags: readonly string[];
+    constructor(reason: string, markup: string, offset: number, openTags: readonly string[]);
+}
+/**
+ * Escapes markup characters so they render as literal text.
+ *
+ * [LAW:one-source-of-truth] The inverse of the two ways the parser reads a
+ * backslash run in front of a bracket, over the same `TAG_BODY`: before a tag
+ * the run is halved and an odd one left over escapes it, so the run is doubled
+ * and one added; before any other bracket one `\[` becomes `[`, so one
+ * backslash is added.
+ *
+ * No bracket in the output can open a tag, whatever it is joined to. A bracket
+ * whose tag the text ends before finishing — `[link=x` — is escaped as a tag,
+ * because the next fragment's `]` would finish it; when what follows is instead
+ * the caller's own tag, a backslash run in front of it renders doubled. A
+ * trailing run is doubled for the same reason: `escape("C:\\")` spliced before
+ * `[/bold]` would otherwise escape the closing tag, so at the very end of a
+ * string it renders doubled. The grammar cannot tell those cases apart, and
+ * both choices fail visibly rather than let input open or escape a tag.
+ *
+ * Rich's `escape` escapes only a finished tag and doubles only a trailing run
+ * of one, so input can drop a backslash, escape the closing tag after it, or
+ * open a tag across a join. All three are departures on purpose.
+ */
+export declare function escape(text: string): string;
+export interface MarkupTagContext {
+    /** Parsed `key=value` attributes from the opening tag. */
+    attrs: Record<string, string>;
+    /**
+     * Inner markup, already parsed (registry-aware) into a `RichText`. It carries
+     * no `baseStyle`: that is painted once, under the whole output, so it sits
+     * beneath whatever the handler returns.
+     */
+    children: RichText;
+    /** Raw inner markup text (between the opening tag's `]` and the closing tag's `[`). */
+    raw: string;
+}
+export type MarkupTagHandler = (ctx: MarkupTagContext) => RichText;
+export declare class MarkupRegistry {
+    private readonly _handlers;
+    register(name: string, handler: MarkupTagHandler): void;
+    unregister(name: string): void;
+    has(name: string): boolean;
+    get(name: string): MarkupTagHandler | undefined;
+}
+export declare const globalMarkupRegistry: MarkupRegistry;
+export interface RenderMarkupOptions {
+    registry?: MarkupRegistry;
+    baseStyle?: string | Style;
+    emoji?: boolean;
+}
+/**
+ * Plugin-aware markup render. Always returns a `RichText`. Built-in style
+ * tags become spans; registered plugin tags are resolved by their handler,
+ * whose returned `RichText` stands in the output where its pair stood, under
+ * any style tag that encloses the pair. The recursion is into the inner slice
+ * of each plugin pair, and every recursion node returns a `RichText`.
+ */
+export declare function renderMarkup(markup: string, options?: RenderMarkupOptions): RichText;