@promptctl/rich-js 0.18.1 → 0.19.0

package/dist/core/measure.js

@@ -1,7 +1,7 @@
 /**
  * Measurement — min/max cell width calculation for renderables.
  */
-import { measuring } from "./protocol.js";
+import { isMeasurable, measuring } from "./protocol.js";
 export class Measurement {
     minimum;
     maximum;
@@ -40,20 +40,25 @@ export class Measurement {
     clamp(minWidth, maxWidth) {
         return new Measurement(Math.min(Math.max(this.minimum, minWidth), maxWidth), Math.min(Math.max(this.maximum, minWidth), maxWidth));
     }
-    // [LAW:single-enforcer] Single entry point for measuring a Measurable
-    static get(options, measurable) {
+    // [LAW:single-enforcer] Single entry point for measuring a renderable. One
+    // that cannot measure itself asks for the whole offer, as the reference's
+    // `Measurement.get` answers for it — so under an unbounded offer it asks for
+    // `Infinity`, and `withBoundedWidth` refuses rather than guessing a width.
+    static get(options, renderable) {
         if (options.maxWidth < 1)
             return new Measurement(0, 0);
-        const { minimum, maximum } = measurable.measure(measuring(options));
+        if (!isMeasurable(renderable))
+            return new Measurement(0, options.maxWidth);
+        const { minimum, maximum } = renderable.measure(measuring(options));
         return new Measurement(minimum, Math.min(maximum, options.maxWidth)).normalize();
     }
 }
-export function measureRenderables(options, measurables) {
-    if (measurables.length === 0)
+export function measureRenderables(options, renderables) {
+    if (renderables.length === 0)
         return new Measurement(0, 0);
     let minOfAll = 0;
     let maxOfAll = 0;
-    for (const m of measurables) {
+    for (const m of renderables) {
         const measurement = Measurement.get(options, m);
         minOfAll = Math.max(minOfAll, measurement.minimum);
         maxOfAll = Math.max(maxOfAll, measurement.maximum);

package/dist/core/memo.d.ts

@@ -0,0 +1,19 @@
+/**
+ * memo — a string-keyed memo with a size bound: the one cache shape for a
+ * pure computation whose keys a long-running host derives without end. A
+ * statusline daemon redrawing a time-varying colour parses a new hex string,
+ * matches a new RGB triple, measures a new cell, on every frame; a memo that
+ * never evicts grows by one entry per frame for the life of the process.
+ */
+export declare const MEMO_MAX = 4096;
+/**
+ * `get(key, compute)` returns the value remembered for `key`, computing and
+ * remembering it on a miss. Holds at most `MEMO_MAX` entries. `compute` must
+ * be a pure function of `key`, so a value recomputed after a clear is the one
+ * that was dropped.
+ */
+export declare class Memo<V extends NonNullable<unknown>> {
+    private readonly entries;
+    get size(): number;
+    get(key: string, compute: (key: string) => V): V;
+}

package/dist/core/memo.js

@@ -0,0 +1,34 @@
+/**
+ * memo — a string-keyed memo with a size bound: the one cache shape for a
+ * pure computation whose keys a long-running host derives without end. A
+ * statusline daemon redrawing a time-varying colour parses a new hex string,
+ * matches a new RGB triple, measures a new cell, on every frame; a memo that
+ * never evicts grows by one entry per frame for the life of the process.
+ */
+// [LAW:single-enforcer] The one size policy for every memo in the library.
+// Clearing at the cap rather than evicting least-recently-used: a refill costs
+// one recomputation per key, and a clear needs no bookkeeping on the hit path.
+export const MEMO_MAX = 4096;
+/**
+ * `get(key, compute)` returns the value remembered for `key`, computing and
+ * remembering it on a miss. Holds at most `MEMO_MAX` entries. `compute` must
+ * be a pure function of `key`, so a value recomputed after a clear is the one
+ * that was dropped.
+ */
+export class Memo {
+    entries = new Map();
+    get size() {
+        return this.entries.size;
+    }
+    get(key, compute) {
+        const remembered = this.entries.get(key);
+        if (remembered !== undefined)
+            return remembered;
+        // Computed before the clear, so a compute that throws costs no entries.
+        const value = compute(key);
+        if (this.entries.size >= MEMO_MAX)
+            this.entries.clear();
+        this.entries.set(key, value);
+        return value;
+    }
+}

package/dist/core/osc8.d.ts

@@ -2,7 +2,7 @@
  * 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 (`segmentsToString`, the one encoder
+ * [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
@@ -10,16 +10,16 @@
  * 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 on nothing; every consumer
+ * [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 coalescer can only share one OSC 8
- * pair across a run of identical SGR, so a link whose text changes style
- * mid-span — a bold glyph beside plain text, a padded cell — is emitted as
- * several pairs, and would highlight piecewise on hover.
+ * 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,

package/dist/core/osc8.js

@@ -2,7 +2,7 @@
  * 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 (`segmentsToString`, the one encoder
+ * [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
@@ -10,16 +10,16 @@
  * 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 on nothing; every consumer
+ * [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 coalescer can only share one OSC 8
- * pair across a run of identical SGR, so a link whose text changes style
- * mid-span — a bold glyph beside plain text, a padded cell — is emitted as
- * several pairs, and would highlight piecewise on hover.
+ * 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,
@@ -30,6 +30,7 @@
  * 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`).
@@ -40,20 +41,6 @@ const TERMINATOR_RE = new RegExp(`[${TERMINATORS}]`, "g");
 export function stripOscTerminators(url) {
     return url.replace(TERMINATOR_RE, "");
 }
-const utf8 = new TextEncoder();
-/**
- * FNV-1a, 32-bit, over the URL's UTF-8 bytes, as 8 lowercase hex digits — a
- * legal `id=` value (no `:`/`;`). UTF-8 rather than UTF-16 code units, so any
- * other runtime computing standard FNV-1a over the same URL gets the same id.
- */
-function linkId(url) {
-    let h = 0x811c9dc5;
-    for (const byte of utf8.encode(url)) {
-        h ^= byte;
-        h = Math.imul(h, 0x01000193);
-    }
-    return (h >>> 0).toString(16).padStart(8, "0");
-}
 /**
  * The bytes that open a hyperlink to `url`.
  *
@@ -64,7 +51,8 @@ function linkId(url) {
  */
 export function osc8Open(url) {
     const clean = stripOscTerminators(url);
-    return `\x1b]8;id=${linkId(clean)};${clean}\x1b\\`;
+    // 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\\";

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

@@ -18,7 +18,7 @@
  * interface. [LAW:one-source-of-truth]
  */
 import { Segment } from "./segment.js";
-import { type Renderable, type RenderOptions } from "./protocol.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

package/dist/core/place.js

@@ -19,7 +19,6 @@
  */
 import { Segment } from "./segment.js";
 import { Measurement } from "./measure.js";
-import { isMeasurable } from "./protocol.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.
@@ -36,11 +35,10 @@ const PADS = {
  * 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,
-    // and the block is then only as wide as what it actually drew.
-    const width = isMeasurable(renderable)
-        ? Measurement.get(options, renderable).maximum
-        : options.maxWidth;
+    // 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));

package/dist/core/pretty.d.ts

@@ -24,6 +24,11 @@ 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.
@@ -34,6 +39,11 @@ export interface PrettyOptions {
      * `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`.
@@ -43,9 +53,46 @@ export interface PrettyOptions {
      * `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;
@@ -55,6 +102,7 @@ export declare class Pretty implements Renderable, Measurable {
     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. */
@@ -72,6 +120,21 @@ export declare class Pretty implements Renderable, Measurable {
      * 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.
@@ -100,6 +163,24 @@ export declare class Pretty implements Renderable, Measurable {
     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.
      *
@@ -113,7 +194,8 @@ export declare class Pretty implements Renderable, Measurable {
      * 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.
+     * 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
@@ -122,6 +204,28 @@ export declare class Pretty implements Renderable, Measurable {
      * `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;
     /**
@@ -140,5 +244,4 @@ export declare class Pretty implements Renderable, Measurable {
     private _joinOneLine;
     /** One position on one line, or `null` when any value in it will not fit. */
     private _slotOneLine;
-    private _addIndentGuides;
 }