@promptctl/rich-js 0.18.0 → 0.19.0

package/dist/core/osc8.js

@@ -0,0 +1,78 @@
+/**
+ * The OSC 8 hyperlink wire grammar — which bytes may not appear inside a
+ * link, how a link becomes bytes, and how bytes are read back as a link.
+ *
+ * [LAW:one-source-of-truth] The producer (`segmentToString`, the one encoder
+ * every link reaches the wire through) opens a link with `osc8Open` and closes
+ * it with `OSC8_CLOSE`; every consumer that reads rendered bytes (a width measure, a
+ * test extracting URLs) matches them with `OSC8`; the data-model boundary
+ * (RichText) cleans URLs with `stripOscTerminators`. All four read the one
+ * terminator set below, so the bytes a sanitizer removes and the bytes a
+ * reader stops at cannot disagree.
+ *
+ * [LAW:locality-or-seam] This module depends only on `fnv1a`; every consumer
+ * imports downward.
+ *
+ * The `id=` parameter is what makes one link hover as one link. A terminal
+ * treats cells as the same hyperlink when they share BOTH the URI and the id
+ * (the OSC 8 spec, and VTE / iTerm2 / kitty / WezTerm alike); without an id,
+ * each open sequence is its own link. The encoder writes one OSC 8 pair per
+ * segment, as the reference does, so a link whose text spans several segments
+ * — a bold glyph beside plain text, a padded cell — is emitted as several
+ * pairs, and would highlight piecewise on hover.
+ *
+ * [LAW:types-are-the-program] The id is a pure function of the URI, so the
+ * byte stream stays a pure function of (style, text, destination): no counter,
+ * no construction-order dependence. The consequence is deliberate: two spans
+ * with the same URI hover as one link wherever they sit on screen, adjacent
+ * or not — a click on either does the same thing, so they ARE one link.
+ * Because terminals key on the (id, URI) PAIR, a hash collision between two
+ * different URIs merges nothing — the URIs still differ — so a 32-bit hash is
+ * exact, not approximate.
+ */
+import { fnv1a } from "./fnv1a.js";
+/**
+ * The bytes that prematurely terminate an OSC 8 sequence: ESC (`\x1b`, which
+ * begins ST `ESC \`), BEL (`\x07`), and the 8-bit ST (`\x9c`).
+ */
+const TERMINATORS = "\\x1b\\x07\\x9c";
+const TERMINATOR_RE = new RegExp(`[${TERMINATORS}]`, "g");
+/** Remove every byte that could break a URL out of its OSC 8 wrap. */
+export function stripOscTerminators(url) {
+    return url.replace(TERMINATOR_RE, "");
+}
+/**
+ * The bytes that open a hyperlink to `url`.
+ *
+ * [LAW:single-enforcer] Wire-byte trust boundary — the URL is sanitized at
+ * the one place it becomes an OSC 8 sequence, whichever upstream API attached
+ * it to the Style (RichText sanitizes at its data-model boundary too; a Style
+ * built directly with `new Style({ link })` reaches here unsanitized).
+ */
+export function osc8Open(url) {
+    const clean = stripOscTerminators(url);
+    // Hex digits are a legal `id=` value: no `:` or `;`.
+    return `\x1b]8;id=${fnv1a(clean)};${clean}\x1b\\`;
+}
+/** The bytes that close the current hyperlink. */
+export const OSC8_CLOSE = "\x1b]8;;\x1b\\";
+/**
+ * Matches one OSC 8 sequence — an open or a close — terminated by `ESC \`,
+ * BEL, or the 8-bit ST. Group 1 is the params, group 2 the URI; both are empty
+ * on a close. To read bytes back use `osc8Sequences`; this pattern is exported
+ * for composing into a larger one (a width measure's zero-width alternation).
+ */
+export const OSC8 = new RegExp(`\\x1b\\]8;([^;${TERMINATORS}]*);([^${TERMINATORS}]*)(?:\\x1b\\\\|\\x07|\\x9c)`);
+const OSC8_SCAN = new RegExp(OSC8.source, "g");
+/**
+ * Every OSC 8 sequence in `text`, in order — the typed way to read rendered
+ * bytes back.
+ */
+export function osc8Sequences(text) {
+    return [...text.matchAll(OSC8_SCAN)].map((m) => ({
+        index: m.index,
+        length: m[0].length,
+        params: m[1],
+        uri: m[2],
+    }));
+}

package/dist/core/paint.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Painting frames over one another on a terminal: the bytes that take it,
+ * paint each frame over the last one in place, and hand it back — and, on an
+ * output that is not a terminal, the one frame that is left when it is handed
+ * back.
+ *
+ * [LAW:one-source-of-truth] Where the cursor rests between frames, and how
+ * many rows the next paint goes back over, is one fact, and a `SurfacePainter`
+ * is its only owner: `App` holds one, and so does `Live` on a terminal, so
+ * they cannot disagree about it. They once did: `Live` wrote a newline after its last row, and on a
+ * frame as tall as the terminal that newline scrolled the screen, so every
+ * refresh left the frame's top row behind in scrollback. The cursor rests on
+ * the last row, and the newline that ends it is written once, when the frame
+ * is handed back.
+ */
+import type { Destination } from "./color.js";
+import type { Height } from "./protocol.js";
+import { Segment } from "./segment.js";
+/**
+ * Where a frame is painted. `alternate` is the whole terminal, in the
+ * alternate screen buffer, so the rows printed before it are there again when
+ * it is handed back. `inline` starts at the cursor's line, as tall as the
+ * frame, and stays on the terminal when it is handed back.
+ */
+export type Surface = "alternate" | "inline";
+/** The terminal a frame is painted on, in cells. */
+export interface Screen {
+    readonly rows: number;
+    readonly cols: number;
+}
+/**
+ * A frame not yet drawn: the painter calls it when it is about to put the
+ * frame on the output, so one that never shows a frame never pays to draw it.
+ */
+export type FrameSource = () => Segment[][];
+/**
+ * What paints a run of frames on an output, from `take` to `handBack`.
+ */
+export interface Painter {
+    /** The budget a frame renders under, on a screen `screenRows` tall. */
+    height(screenRows: number): Height;
+    /** Take the output. */
+    take(): void;
+    /**
+     * Paint `frame` over the last frame. `frame` is already shaped to its
+     * height by whoever set its budget. An empty frame erases the last one.
+     */
+    paint(frame: FrameSource, screen: Screen, destination: Destination): void;
+    /**
+     * The bytes that write `text` while `frame` is the frame standing on the
+     * output, for the caller to write in one piece.
+     */
+    around(text: string, frame: FrameSource, screen: Screen, destination: Destination): string;
+    /** Hand the output back. The next `take` starts from wherever it then is. */
+    handBack(): void;
+}
+/**
+ * Paints frames on one surface of a terminal. It holds the last frame's own
+ * rows on the terminal — what the next paint goes back over — from `take` to
+ * `handBack`.
+ */
+export declare class SurfacePainter implements Painter {
+    private readonly write;
+    private readonly geometry;
+    private rows;
+    constructor(surface: Surface, write: (bytes: string) => void);
+    height(screenRows: number): Height;
+    /** Take the terminal: the surface entered, the cursor hidden. */
+    take(): void;
+    /**
+     * Paint `frame` over the last frame, leaving the cursor on its last row,
+     * and return it as painted. No row is wider than the screen, since one that
+     * soft-wrapped would push every row below it down a row the next paint does
+     * not go back over.
+     */
+    paint(frame: FrameSource, screen: Screen, destination: Destination): Segment[][];
+    /**
+     * The frame erased, `text` written, and `frame` painted again on the line
+     * under it — in one string, so no terminal ever shows the frame gone. The
+     * frame fills whole lines, so text that stops mid-line is ended before it.
+     */
+    around(text: string, frame: FrameSource, screen: Screen, destination: Destination): string;
+    private over;
+    /**
+     * Hand the terminal back: style reset, then the cursor shown on the
+     * program's next line, the surface left.
+     */
+    handBack(): void;
+}
+/**
+ * Paints on an output that is not a terminal — a file, a pipe, a CI log — as
+ * Rich's `Live` does: nothing while the frames change, since every one would
+ * stay there for good with the escape sequences that move over it as literal
+ * bytes, and the last frame once, printed as plain lines through `print`, when
+ * the output is handed back. What is written around the frame goes out as it
+ * was given. No frame is drawn but the one handed back.
+ */
+export declare class FinalFramePainter implements Painter {
+    private readonly print;
+    private last;
+    constructor(print: (frame: Segment[][]) => void);
+    height(screenRows: number): Height;
+    take(): void;
+    paint(frame: FrameSource): void;
+    around(text: string): string;
+    handBack(): void;
+}

package/dist/core/paint.js

@@ -0,0 +1,150 @@
+/**
+ * Painting frames over one another on a terminal: the bytes that take it,
+ * paint each frame over the last one in place, and hand it back — and, on an
+ * output that is not a terminal, the one frame that is left when it is handed
+ * back.
+ *
+ * [LAW:one-source-of-truth] Where the cursor rests between frames, and how
+ * many rows the next paint goes back over, is one fact, and a `SurfacePainter`
+ * is its only owner: `App` holds one, and so does `Live` on a terminal, so
+ * they cannot disagree about it. They once did: `Live` wrote a newline after its last row, and on a
+ * frame as tall as the terminal that newline scrolled the screen, so every
+ * refresh left the frame's top row behind in scrollback. The cursor rests on
+ * the last row, and the newline that ends it is written once, when the frame
+ * is handed back.
+ */
+import { segmentsToString } from "./render.js";
+import { Segment } from "./segment.js";
+const GEOMETRY = {
+    alternate: {
+        exact: true,
+        enter: "\x1b[?1049h",
+        // Leaving the buffer puts back the cursor the program had.
+        leave: "\x1b[?1049l",
+        home: () => "\x1b[H",
+        // The frame is every row of the screen, so there is nothing left under it
+        // — and after the terminal shrinks, painting the old count would scroll.
+        painted: (frameRows) => frameRows,
+        below: () => "",
+    },
+    inline: {
+        exact: false,
+        enter: "",
+        leave: "",
+        // After N rows written with N-1 newlines between them, the cursor is on
+        // the last. `ESC[0A` still moves a row on some terminals, so a one-row
+        // frame has no move at all.
+        home: (rows) => (rows > 1 ? `\x1b[${rows - 1}A` : ""),
+        // A shorter frame blanks the rows the last one left below it, as far as
+        // the screen still reaches after a shrink.
+        painted: (frameRows, lastRows, screenRows) => Math.max(frameRows, Math.min(lastRows, screenRows)),
+        // Where the program's next line belongs.
+        below: (rows) => (rows > 0 ? "\n" : ""),
+    },
+};
+// Each row starts at its line's first cell and is erased as it is reached,
+// rather than the frame cleared first, so no blank screen shows between two
+// frames. The erase leads its row: after a row that fills the width, the
+// cursor sits on its last cell, and an erase there would take it.
+const ROW_START = "\r\x1b[2K";
+const HIDE_CURSOR = "\x1b[?25l";
+const SHOW_CURSOR = "\x1b[?25h";
+const RESET_STYLE = "\x1b[0m";
+const fitRows = (frame, screen) => frame.map((line) => Segment.adjustLineLength(line, screen.cols, undefined, false));
+/**
+ * Paints frames on one surface of a terminal. It holds the last frame's own
+ * rows on the terminal — what the next paint goes back over — from `take` to
+ * `handBack`.
+ */
+export class SurfacePainter {
+    write;
+    geometry;
+    rows = 0;
+    constructor(surface, write) {
+        this.write = write;
+        this.geometry = GEOMETRY[surface];
+    }
+    height(screenRows) {
+        return { rows: screenRows, exact: this.geometry.exact };
+    }
+    /** Take the terminal: the surface entered, the cursor hidden. */
+    take() {
+        this.write(this.geometry.enter + HIDE_CURSOR);
+    }
+    /**
+     * Paint `frame` over the last frame, leaving the cursor on its last row,
+     * and return it as painted. No row is wider than the screen, since one that
+     * soft-wrapped would push every row below it down a row the next paint does
+     * not go back over.
+     */
+    paint(frame, screen, destination) {
+        const rows = fitRows(frame(), screen);
+        this.write(this.over(rows, screen, destination));
+        return rows;
+    }
+    /**
+     * The frame erased, `text` written, and `frame` painted again on the line
+     * under it — in one string, so no terminal ever shows the frame gone. The
+     * frame fills whole lines, so text that stops mid-line is ended before it.
+     */
+    around(text, frame, screen, destination) {
+        // Drawn before `over` moves the row count, so a frame that throws leaves
+        // the painter matching the terminal it left untouched.
+        const rows = fitRows(frame(), screen);
+        const erase = this.over([], screen, destination);
+        const ended = text.endsWith("\n") ? text : `${text}\n`;
+        return erase + ended + this.over(rows, screen, destination);
+    }
+    // The bytes that paint `rows` over the last frame. They go out in one
+    // string, so whatever takes the last frame away arrives with the new one.
+    over(rows, screen, destination) {
+        const painted = this.geometry.painted(rows.length, this.rows, screen.rows);
+        const body = Array.from({ length: painted }, (_, row) => ROW_START + segmentsToString(rows[row] ?? [], destination)).join("\n");
+        // Rows blanked below the frame are not the frame's: the cursor goes back
+        // up to its last row, so the next frame and the program's next line start
+        // from the frame's own height.
+        const blanked = painted - Math.max(rows.length, 1);
+        const back = blanked > 0 ? `\x1b[${blanked}A` : "";
+        const bytes = this.geometry.home(this.rows) + body + back;
+        this.rows = rows.length;
+        return bytes;
+    }
+    /**
+     * Hand the terminal back: style reset, then the cursor shown on the
+     * program's next line, the surface left.
+     */
+    handBack() {
+        this.write(RESET_STYLE + SHOW_CURSOR + this.geometry.below(this.rows) + this.geometry.leave);
+        this.rows = 0;
+    }
+}
+/**
+ * Paints on an output that is not a terminal — a file, a pipe, a CI log — as
+ * Rich's `Live` does: nothing while the frames change, since every one would
+ * stay there for good with the escape sequences that move over it as literal
+ * bytes, and the last frame once, printed as plain lines through `print`, when
+ * the output is handed back. What is written around the frame goes out as it
+ * was given. No frame is drawn but the one handed back.
+ */
+export class FinalFramePainter {
+    print;
+    last = () => [];
+    constructor(print) {
+        this.print = print;
+    }
+    height(screenRows) {
+        return { rows: screenRows, exact: false };
+    }
+    take() { }
+    paint(frame) {
+        this.last = frame;
+    }
+    around(text) {
+        return text;
+    }
+    handBack() {
+        const frame = this.last;
+        this.last = () => [];
+        this.print(frame());
+    }
+}

package/dist/core/place.d.ts

@@ -0,0 +1,30 @@
+/**
+ * place — a renderable's output set down as one block inside a wider width.
+ *
+ * The block is placed, not its lines. The renderable is measured, drawn at the
+ * width it asked for and at its own height — a region's height is dropped, as
+ * the reference's `Align` drops it — and every line is padded to the widest, so the block is a
+ * rectangle; only then is the rectangle padded to the offered width. A
+ * multi-line paragraph keeps its own shape under `"center"` — `hi` over `hello`
+ * stays a 5-cell block, centred as one — where padding each line to the full
+ * width on its own would centre `hi` against the whole terminal. That is
+ * Rich's `Align`, and `test/core/console.test.ts` pins it against the
+ * reference's bytes.
+ *
+ * It lives in `core/` because `Console.print` places with it: Rich's `print`
+ * wraps what it prints in `Align` for the three alignments, and `console.ts`
+ * reaching for `renderables/align.ts` would be a third upward edge out of this
+ * layer. [LAW:one-way-deps] `Align` is this function behind the `Renderable`
+ * interface. [LAW:one-source-of-truth]
+ */
+import { Segment } from "./segment.js";
+import type { Renderable, RenderOptions } from "./protocol.js";
+export type Alignment = "left" | "center" | "right";
+/**
+ * `renderable`'s lines, the block they form placed by `align` in
+ * `options.maxWidth`. `options.maxWidth` must be finite: the spare cells are
+ * written out as spaces. A block wider than the offer — a line with nowhere to
+ * break, drawn by a renderable that does not cut its own — is left unpadded at
+ * its full width, for whatever holds it to crop or keep.
+ */
+export declare function placeBlock(renderable: Renderable, align: Alignment, options: RenderOptions): Segment[][];

package/dist/core/place.js

@@ -0,0 +1,49 @@
+/**
+ * place — a renderable's output set down as one block inside a wider width.
+ *
+ * The block is placed, not its lines. The renderable is measured, drawn at the
+ * width it asked for and at its own height — a region's height is dropped, as
+ * the reference's `Align` drops it — and every line is padded to the widest, so the block is a
+ * rectangle; only then is the rectangle padded to the offered width. A
+ * multi-line paragraph keeps its own shape under `"center"` — `hi` over `hello`
+ * stays a 5-cell block, centred as one — where padding each line to the full
+ * width on its own would centre `hi` against the whole terminal. That is
+ * Rich's `Align`, and `test/core/console.test.ts` pins it against the
+ * reference's bytes.
+ *
+ * It lives in `core/` because `Console.print` places with it: Rich's `print`
+ * wraps what it prints in `Align` for the three alignments, and `console.ts`
+ * reaching for `renderables/align.ts` would be a third upward edge out of this
+ * layer. [LAW:one-way-deps] `Align` is this function behind the `Renderable`
+ * interface. [LAW:one-source-of-truth]
+ */
+import { Segment } from "./segment.js";
+import { Measurement } from "./measure.js";
+// The share of the spare cells that goes on the left; the rest go on the right.
+// Right-alignment pads no right side at all, which is the reference's choice
+// and not a zero: a line that ends at the edge carries no trailing blanks.
+const PADS = {
+    left: (spare) => [0, spare],
+    center: (spare) => [Math.floor(spare / 2), spare - Math.floor(spare / 2)],
+    right: (spare) => [spare, 0],
+};
+/**
+ * `renderable`'s lines, the block they form placed by `align` in
+ * `options.maxWidth`. `options.maxWidth` must be finite: the spare cells are
+ * written out as spaces. A block wider than the offer — a line with nowhere to
+ * break, drawn by a renderable that does not cut its own — is left unpadded at
+ * its full width, for whatever holds it to crop or keep.
+ */
+export function placeBlock(renderable, align, options) {
+    // A renderable that cannot say how wide it wants to be is offered all of it
+    // (`Measurement.get` answers for it), and the block is then only as wide as
+    // what it actually drew.
+    const width = Measurement.get(options, renderable).maximum;
+    const drawn = Segment.splitLines(renderable.render({ ...options, maxWidth: width, height: undefined }));
+    const [blockWidth, height] = Segment.getShape(drawn);
+    const [left, right] = PADS[align](Math.max(0, options.maxWidth - blockWidth));
+    return Segment.setShape(drawn, blockWidth, height).map((line) => [...pad(left), ...line, ...pad(right)]);
+}
+// [LAW:dataflow-not-control-flow] no spare room is a pad of no segments, not a
+// step skipped.
+const pad = (cells) => (cells > 0 ? [new Segment(" ".repeat(cells))] : []);

package/dist/core/pretty.d.ts

@@ -0,0 +1,247 @@
+/**
+ * Pretty — formats JavaScript data structures with highlighting.
+ *
+ * Lives in `core/` beside `markup` and `emoji` because it does their job: turn
+ * foreign input into `RichText`. It composes no other renderable — the trait
+ * every file in `renderables/` shares and this one does not — and its imports
+ * are core primitives only. `Console.print` accepts `unknown` and must turn any
+ * of it into something renderable, so the formatter has to sit where `console`
+ * can reach it without an upward edge. [LAW:one-way-deps]
+ *
+ * Two traversals share this file, and the split is the whole design. `_format`
+ * lays a value out across lines; `_oneLine` answers only "does this fit on one
+ * line, and if so what is it?". They meet at `_shape`, which describes a
+ * container without committing to either layout. One traversal answering both
+ * questions is what made this formatter exponential: every child was rendered
+ * once to probe it and again to place it, so a node at depth d was visited 2^d
+ * times.
+ */
+import { Segment } from "./segment.js";
+import { RichText } from "./text.js";
+import type { Highlighter } from "./highlighter.js";
+import type { Renderable, Measurable, RenderOptions } from "./protocol.js";
+export interface PrettyOptions {
+    indent?: number;
+    expandAll?: boolean;
+    maxLength?: number;
+    /**
+     * How many characters of a string to show before cutting it, counting the
+     * rest after the closing quote. A character is a grapheme cluster, not a
+     * UTF-16 code unit: `"😀😀"` is two, though its `length` is four.
+     */
+    maxString?: number;
+    /**
+     * How many levels of nesting to descend before eliding. Unbounded by default.
+     *
+     * `Console.print` supplies a bound because it formats whatever it is handed;
+     * a caller constructing a `Pretty` has seen their data and can say what they
+     * want. Past the cap a container renders as `[...]`, `{...}`, `Map {...}` or
+     * `Set {...}` — visible, so the reader knows the value continues.
+     */
+    maxDepth?: number;
+    /**
+     * Draw a `│` in the first cell of each level of indent. Off by default, as
+     * the reference's is, and never drawn on an ASCII-only console, where the
+     * reference draws none.
+     */
+    indentGuides?: boolean;
+    /**
+     * Who colours the formatted text. Defaults to a `ReprHighlighter`.
+     *
+     * Passed rather than imported so a caller's choice survives. `Console.print`
+     * routes data arguments through here, and its `highlight` flag and custom
+     * `highlighter` have to reach the output the same way they reach a printed
+     * string — a `Pretty` reaching for its own singleton would silently outrank
+     * both. `NullHighlighter` is the "none" case.
+     *
+     * It reads each `Map` entry's `=>` as `= `: the arrow is this formatter's
+     * punctuation, not the data's, and its `>` would close a repr tag opened by
+     * any `<` before it.
+     */
+    highlighter?: Highlighter;
+}
+/**
+ * What a value is bounded by when whoever formats it has not seen it:
+ * `Console.print`'s data arguments, and a thrown value `Traceback` reports.
+ *
+ * Such a caller has to assume nothing about the value's size, in any of the
+ * three ways a value can be large. Unbounded, a buffer emits a line per byte, a
+ * deeply nested object descends until the stack gives out, and a single
+ * response body assigned to a field arrives in full — each of them a line that
+ * costs megabytes or hangs the terminal. All three bounds announce themselves
+ * in the output (`... +N`, `{...}`, `+N` after the closing quote), so this
+ * truncates visibly and never silently. [LAW:no-silent-failure]
+ *
+ * A caller constructing a `Pretty` has seen their data and gets no defaults;
+ * these belong to the paths that format what they were handed, not to the
+ * formatter.
+ */
+export declare const UNSEEN_DATA_BOUNDS: {
+    readonly maxLength: 100;
+    readonly maxDepth: 16;
+    readonly maxString: 1000;
+};
+/**
+ * Whether `Pretty` lays a value out as a container — brackets and positions —
+ * rather than spelling it as one piece of text. Emptiness and the depth cap do
+ * not enter into it; `[]` is still a container that happens to print on one
+ * line. This is Python Rich's `is_expandable`, and `Console.print` reads it to
+ * give a container lines of its own.
+ *
+ * A value whose reflection throws is not one, as in the reference's
+ * `_safe_isinstance`: `Pretty` then formats it as text, and the throw reaches
+ * the output as `threw`'s marker rather than taking the print down.
+ */
+export declare function isExpandable(value: unknown): boolean;
+export declare class Pretty implements Renderable, Measurable {
+    readonly data: unknown;
+    readonly indent: number;
+    readonly expandAll: boolean;
+    readonly maxLength: number | undefined;
+    readonly maxString: number | undefined;
+    readonly maxDepth: number;
+    readonly indentGuides: boolean;
+    readonly highlighter: Highlighter;
+    private readonly cutStrings;
+    constructor(data: unknown, options?: PrettyOptions);
+    render(options: RenderOptions): Iterable<Segment>;
+    /** The value laid out for `options.maxWidth` and highlighted: the text this renders. */
+    toText(options: RenderOptions): RichText;
+    measure(_options: RenderOptions): {
+        minimum: number;
+        maximum: number;
+    };
+    /**
+     * The text a value shows without being reflected on, or `null` when it is an
+     * object and the shape arms own it.
+     *
+     * Every kind answered here renders the same wherever it sits — no
+     * indentation, no width to fit — which is why one method serves both
+     * traversals.
+     */
+    private _scalar;
+    /**
+     * `value` cut to `max` grapheme clusters, with the rest counted after the
+     * closing quote.
+     *
+     * The unit is the cluster of the value, counted before `JSON.stringify`
+     * escapes it. A code unit cut can keep half a surrogate pair, which
+     * JSON.stringify prints as a `\ud83d` escape; a code point cut can keep half
+     * a flag or a ZWJ family. Either way the kept prefix shows something the
+     * value never held, and the dropped count is in a unit nobody can see.
+     *
+     * Counting clusters reads the whole string, and the traversals ask for the
+     * same scalar once per probe at every level above it, so the answer is
+     * memoised per value.
+     */
+    private _cutString;
+    /**
+     * A container, or the text standing in for one that is empty or past the
+     * depth cap.
+     *
+     * `positions` is a thunk because both of those answers are reachable from
+     * `size` alone, and reaching a position is not free: a `Map` or `Set` reaches
+     * its own through an iterator, so enumerating one only to elide it drains a
+     * container to print `Set {...}`. `size` also says how many positions were
+     * dropped, which is where the elision marker comes from — one derivation, so
+     * the count and the bound cannot disagree.
+     */
+    private _container;
+    /**
+     * The brackets and positions of an object, layout-free. See `Shape`.
+     *
+     * `bound` is the most positions the caller could ever use. Laying out passes
+     * `Infinity`, because it prints every position it is handed. A probe passes
+     * what is left of its line, which is already more positions than a fitting
+     * one could hold — `SEPARATOR` charges two cells apiece, so a container with
+     * more positions than `budget` overruns however narrow its contents are.
+     * Reaching past it only ever feeds a join that returns `null`, and reaching a
+     * position is what drains a `Map` or `Set`.
+     */
+    private _shape;
+    /** The laid-out form of a value, expanded across lines wherever one line will not do. */
+    private _format;
+    /** The arms for a non-null object, with `value` already on the open path. */
+    private _formatObject;
+    /**
+     * Where a container starts: where it stands, or — when its opener will not
+     * fit after what precedes it on its line and will fit on a hanging line —
+     * that hanging line, with `lead` the break that reaches it.
+     *
+     * This is `_place`'s rule for one-piece text, with `open` as the first word:
+     * a bracket is a literal no cut can shorten, so moving is the only way it
+     * fits. A container moved there is on a line of that indent, its children
+     * and closer included, so it reads as its key's value rather than its key's
+     * sibling. It moves only to fit: past the edge, the hanging line has no more
+     * room than this one.
+     */
+    private _opening;
+    /**
+     * `at` on a line that starts at `inset`. The one place a hang is derived: a
+     * line's continuation rows and its children both sit one indent past it.
+     */
+    private _onLine;
+    /**
+     * One position, with every value in it laid out.
+     *
+     * `at.column` is where `slot.head` begins. Rather than hand-tracking a
+     * second, parallel "column so far" alongside `out` — two values a future
+     * edit could update out of step, silently reintroducing a stale-budget bug
+     * of the same shape this file just fixed — each hole derives its own
+     * column fresh from `out` via `lineColumn`, the one place "text just
+     * emitted" becomes "column now". [LAW:one-source-of-truth] `out` is
+     * already the complete record; `column` is a read of it, not a second copy
+     * of the same fact. `_joinOneLine`'s probe sibling tracks the analogous
+     * thing via `budget` shrinking instead, because a probe already discards
+     * anything that overruns and so never needs to know where a multi-line
+     * insert's last line ends. Where that line *starts* is the one fact `out`
+     * cannot give back, so it comes from each piece's `Laid.inset` instead.
+     *
+     * Each hole's `reserve` is its own `tail` plus, only for the slot's last
+     * hole, whatever `at.reserve` already asked this whole slot to leave room
+     * for (`_formatObject`'s trailing `,`). An earlier hole's tail is never
+     * folded into a later hole's reserve — it is spent, not carried, the moment
+     * `out` grows past it.
+     */
+    private _expandSlot;
+    /**
+     * Text that is one piece — a scalar, a value that spells itself, a marker —
+     * set down at `at.column` on a line this formatter owns.
+     *
+     * A container that will not fit expands; one piece of text has no structure
+     * to expand into, so it wraps, and the wrap is laid out here rather than left
+     * to `RichText`. Left there, it broke at the console's edge and resumed at
+     * column 0 — under the enclosing key, or under nothing — which is the
+     * structure a reader of nested data relies on, broken. So every line after the
+     * first hangs at `at.hang`, a line of the value's own (`Error`'s message, a
+     * multi-line `toString`) as much as a wrapped one, and each is cut to the
+     * width left there. Every row of the last line also leaves `at.reserve`, as a
+     * container's compact try does, for the `,` or `" => "` that follows it.
+     *
+     * The first line is where the text already stands. When not even its first
+     * word fits there, it starts on a hanging line instead — the only case that
+     * moves it, and one taken only when that line starts further left and so has
+     * more room; otherwise the word is folded where it stands. A Map value after
+     * a long key is the case: `[1, 2, 3, 10] =>` ends the line and `"v"` hangs
+     * beneath it, where it used to wrap to column 0.
+     */
+    private _place;
+    /** The one-line form of a value, or `null` when it will not fit `at.budget`. */
+    private _oneLine;
+    /**
+     * A container's positions on one line, or `null` as soon as they overrun.
+     *
+     * The budget is spent as it goes and each position is asked for only what is
+     * left, so a subtree that has already outgrown the line is abandoned where it
+     * outgrew it rather than formatted in full and then measured.
+     *
+     * The brackets are charged before anything is read, and that ordering is what
+     * bounds the traversal: a budget checked only against the finished text still
+     * reads the whole subtree to produce text it then throws away. Charged first,
+     * every level costs at least the two cells of its own brackets, so a probe
+     * descends at most `budget / 2` levels however deep the data goes.
+     */
+    private _joinOneLine;
+    /** One position on one line, or `null` when any value in it will not fit. */
+    private _slotOneLine;
+}