@promptctl/rich-js 0.18.1 → 0.20.0

package/dist/core/pretty.js

@@ -16,16 +16,38 @@
  * once to probe it and again to place it, so a node at depth d was visited 2^d
  * times.
  */
-import { cellLen } from "./cells.js";
-import { RichText } from "./text.js";
+import { asCellCol, cellColToCodeUnitOffset, cellLen, graphemes, splitAtCells } from "./cells.js";
+import { divideLine } from "./wrap.js";
+import { Segment } from "./segment.js";
+import { RichText, stripControlChars } from "./text.js";
 import { ReprHighlighter } from "./highlighter.js";
+import { drawable } from "./protocol.js";
 const reprHighlighter = new ReprHighlighter();
+/**
+ * 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 const UNSEEN_DATA_BOUNDS = { maxLength: 100, maxDepth: 16, maxString: 1000 };
 const rootFrame = (maxWidth) => ({
     inset: 0,
+    margin: 0,
     level: 0,
     maxWidth,
     column: 0,
     reserve: 0,
+    hang: null,
     open: new WeakSet(),
 });
 /**
@@ -42,6 +64,148 @@ function lineColumn(column, text) {
     const lastNewline = text.lastIndexOf("\n");
     return lastNewline === -1 ? column + cellLen(text) : cellLen(text.slice(lastNewline + 1));
 }
+/** Text with no line break in it. */
+const flat = (text) => ({ text, margins: [], arrows: [] });
+/** A new line whose first `margin` cells are the structure's indent. */
+const newline = (margin) => ({ text: "\n" + " ".repeat(margin), margins: [margin], arrows: [] });
+/** What follows a Map entry's key. */
+const ARROW_TEXT = " => ";
+// [LAW:one-source-of-truth] the arrow's offset is read off its text, never kept beside it.
+const ARROW = { text: ARROW_TEXT, margins: [], arrows: [ARROW_TEXT.indexOf(">")] };
+/** An indent guide: one code unit, as the space it stands over is. */
+const GUIDE = "│";
+const placed = (lines, inset) => ({ ...lines, inset });
+const cat = (...parts) => {
+    // `+`, not `join`: a concatenation is left unflattened until it is read, and
+    // each level of the data would otherwise copy the whole of its subtree's text.
+    let text = "";
+    const arrows = [];
+    for (const part of parts) {
+        for (const arrow of part.arrows)
+            arrows.push(text.length + arrow);
+        text += part.text;
+    }
+    return { text, margins: parts.flatMap((part) => part.margins), arrows };
+};
+/**
+ * A container laid out across lines: `open`, each of `parts` on a line of its
+ * own at `inner`, and `close` back at `outer`.
+ *
+ * Here and `follow` rather than inline because the traversal recurses once per
+ * level of the data, and what its frames hold is what bounds the depth it
+ * reaches; assembling a piece is done once the recursion under it has returned.
+ */
+function expansion(lead, shape, parts, inner, outer) {
+    const lines = parts.map((part, i) => cat(flat(i === 0 ? "" : EXPAND_SEPARATOR), newline(inner), part));
+    return placed(cat(lead, flat(shape.open), ...lines, newline(outer), flat(shape.close)), outer);
+}
+/**
+ * `laid` and then `tail` after `out`. A value `_place` moved onto a line of its
+ * own leaves the text before it ending the line, and the space that was to
+ * separate them goes with it — spaces only, as a line break carries a margin.
+ */
+function follow(out, laid, tail) {
+    let end = out.text.length;
+    while (laid.text.startsWith("\n") && out.text[end - 1] === " ")
+        end--;
+    return cat({ ...out, text: out.text.slice(0, end) }, laid, tail);
+}
+/**
+ * `lines` as it is shown, where each run of guides is, and where each of its
+ * `arrows` landed. A line with nothing
+ * past its margin is blank, and loses the spaces its margin was written as.
+ * With a `guide`, each indent of every margin has one in its first cell, as
+ * the reference's `with_indent_guides` draws it, blank lines included, so the
+ * rule runs unbroken. [LAW:dataflow-not-control-flow] no guide is `null`, and
+ * the same pass runs either way.
+ *
+ * The guide offsets are counted over the text `RichText` will hold, which has
+ * its control characters stripped; counted over the raw text, every guide past
+ * a `\r` in a key or a `toString` would land one cell right. A margin is only
+ * ever spaces, so stripping cannot move one. An arrow is moved by the
+ * stripping of what precedes it, and by the blank lines dropped before it;
+ * never inside its own line, whose row is the line itself or the same line
+ * with guides over its margin. [LAW:types-are-the-program] that holds because
+ * the only guide is `GUIDE`, one code unit over one space.
+ */
+function drawMargins(lines, indent, guide) {
+    let raw = 0;
+    let kept = 0;
+    const stripped = lines.arrows.map((arrow) => {
+        kept += stripControlChars(lines.text.slice(raw, arrow)).length;
+        raw = arrow;
+        return kept;
+    });
+    const arrows = [];
+    // Each arrow before `end` in the stripped text is on the line that starts
+    // at `from` there and at `to` in what is shown.
+    const land = (from, to, end) => {
+        while (arrows.length < stripped.length && stripped[arrows.length] < end) {
+            arrows.push(to + stripped[arrows.length] - from);
+        }
+    };
+    const [first, ...rest] = stripControlChars(lines.text).split("\n");
+    const guides = [];
+    let offset = first.length;
+    let from = first.length;
+    land(0, 0, from);
+    const rows = rest.map((line, i) => {
+        const margin = lines.margins[i];
+        const content = line.slice(margin);
+        offset += 1;
+        from += 1;
+        if (guide !== null && margin > 0)
+            guides.push([offset, offset + margin]);
+        const row = guide === null
+            ? (content === "" ? "" : line)
+            : Array.from({ length: margin }, (_, cell) => (cell % indent === 0 ? guide : " ")).join("") + content;
+        land(from, offset, from + line.length);
+        offset += row.length;
+        from += line.length;
+        return row;
+    });
+    return { plain: [first, ...rows].join("\n"), guides, arrows };
+}
+/**
+ * The rows `line` becomes: the first holds what `stay` code units of it leave
+ * where the line starts, the rest are cut to `hangRoom` cells each.
+ *
+ * Every row but the first begins at a break, so whatever whitespace a break
+ * leaves on either side of it is the break's and not the text's, and a row of
+ * nothing else is no row at all. Each is then set in by the indent the line
+ * opened with, so a wrapped line of a multi-line `toString` stays under its own
+ * first word.
+ */
+function rowsOf(line, stay, hangRoom) {
+    const lead = line.slice(0, line.length - line.trimStart().length);
+    const rest = line.slice(stay);
+    const hung = splitAtCells(rest, divideLine(rest, asCellCol(hangRoom - cellLen(lead)), { fold: true }))
+        .map((row) => row.trim())
+        .filter((row) => row !== "")
+        .map((row) => lead + row);
+    return [line.slice(0, stay).trimEnd(), ...hung];
+}
+/**
+ * How many code units of `line` stay where it starts, with `room` cells left
+ * there.
+ *
+ * What stays is every whole word that fits. When not even the first does,
+ * `canHang` says whether a hanging line starts further left than here: if so,
+ * nothing stays and all of `line` moves there; if not, moving would gain
+ * nothing, and the first word is folded where it stands.
+ */
+function stayingLength(line, room, canHang) {
+    if (cellLen(line.trimEnd()) <= room)
+        return line.length;
+    const cut = (fold) => {
+        const first = divideLine(line, asCellCol(room), { fold })[0];
+        return first === undefined ? line.length : cellColToCodeUnitOffset(line, first);
+    };
+    const words = cut(false);
+    if (cellLen(line.slice(0, words).trimEnd()) <= room)
+        return words;
+    return canHang ? 0 : cut(true);
+}
 /**
  * The text, when it is a single line no wider than `budget` — otherwise `null`.
  *
@@ -51,8 +215,8 @@ function lineColumn(column, text) {
  * used to render as `{ m: Map {` — a one-line object with an expansion wedged
  * inside it and the closing brace back at column 0.
  */
-function fitOneLine(text, budget) {
-    return text.includes("\n") || cellLen(text) > budget ? null : text;
+function fitOneLine(lines, budget) {
+    return lines.text.includes("\n") || cellLen(lines.text) > budget ? null : lines;
 }
 /**
  * The elements of an indexed sequence, or `null` for anything that isn't one.
@@ -72,11 +236,78 @@ function fitOneLine(text, budget) {
 function indexedElements(value) {
     if (Array.isArray(value))
         return value;
-    if (ArrayBuffer.isView(value) && !(value instanceof DataView)) {
+    if (typedArrayName(value) !== undefined)
         return value;
-    }
     return null;
 }
+/*
+ * Brand checks: what a value *is*, asked of the internal slot that makes it
+ * one rather than of its prototype chain.
+ *
+ * `Pretty` reflects on values it did not create, and some were created in
+ * another realm — a `vm` context, an iframe — whose `Map`, `DataView` and
+ * `Object.prototype` are not this realm's. `instanceof` and prototype identity
+ * answer "no" to every one of them, so a `Map` printed `[object Map]` and a
+ * `DataView` printed as an empty array. Every built-in method reads its
+ * receiver's slot and not its prototype, which is what makes these
+ * realm-independent: the platform's own brand check, borrowed from this realm
+ * and applied to a value from any.
+ */
+// %TypedArray%.prototype[Symbol.toStringTag]: a typed array's name, and
+// `undefined` for every other receiver, `DataView` included — the spec's brand
+// check for the family, and the one that never throws.
+const typedArrayTag = Object.getOwnPropertyDescriptor(Object.getPrototypeOf(Uint8Array.prototype), Symbol.toStringTag)?.get;
+function typedArrayName(value) {
+    return typedArrayTag?.call(value);
+}
+/**
+ * Is `value` a `Map` (or a `Set`), from this realm or any other?
+ *
+ * Three kinds of evidence, each the only one that sees some collection.
+ * `instanceof` sees this realm's, a `Proxy` around one included. The
+ * platform's `Symbol.toStringTag` names the kind in every realm and passes
+ * through a `Proxy` — a reactive store made in an iframe — that has neither
+ * this realm's prototype nor the slot; if such a proxy will not hand over its
+ * entries, reading them throws and prints as `[Threw: …]`, never as an empty
+ * collection. The slot sees a subclass from another realm that renamed its
+ * tag: `has` throws on any receiver without one. A plain object has no tag at
+ * all, so it is never asked — a throw costs a stack trace, too dear to pay for
+ * every object printed.
+ */
+function isCollection(value, kind) {
+    if (value instanceof kind)
+        return true;
+    const tag = value[Symbol.toStringTag];
+    if (typeof tag !== "string")
+        return false;
+    if (tag === kind.name)
+        return true;
+    try {
+        kind.prototype.has.call(value, undefined);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isMap(value) {
+    return isCollection(value, Map);
+}
+function isSet(value) {
+    return isCollection(value, Set);
+}
+/**
+ * Is `fn` the default `toString` of the realm that made it? A function's
+ * prototype is its realm's `Function.prototype`, whose own prototype is that
+ * realm's `Object.prototype` — two fixed steps from the function to the
+ * default it is compared with, so no chain is walked and no identity with this
+ * realm's is asked for.
+ */
+function isRealmDefaultToString(fn) {
+    const realmFunctionPrototype = Object.getPrototypeOf(fn);
+    return (realmFunctionPrototype !== null &&
+        Object.getPrototypeOf(realmFunctionPrototype)?.toString === fn);
+}
 /**
  * The first `limit` items of a sequence, pulled and no more.
  *
@@ -108,7 +339,9 @@ function take(source, limit) {
  * lazily-computed field is unusable on the objects it is most wanted for.
  */
 function threw(error) {
-    return `[Threw: ${error instanceof Error ? error.message : String(error)}]`;
+    // An `Error` from any realm carries its `message` as a string.
+    const message = error?.message;
+    return `[Threw: ${typeof message === "string" ? message : String(error)}]`;
 }
 /**
  * Does this value carry its own string form, or must we reflect on its keys?
@@ -122,13 +355,84 @@ function threw(error) {
  *
  * Both clauses are load-bearing. The identity check separates the two
  * populations; the `typeof` check is what makes `Object.create(null)` — which
- * has no `toString` at all — reflect rather than throw.
+ * has no `toString` at all — reflect rather than throw. The default is the one
+ * of the realm that made the `toString`, not this one's: an object from a `vm`
+ * context inherits a `toString` that is a different function and the same
+ * non-answer.
  */
 function describesItself(value) {
     const asRecord = value;
     return (typeof asRecord[Symbol.toPrimitive] === "function" ||
         (typeof asRecord.toString === "function" &&
-            asRecord.toString !== Object.prototype.toString));
+            !isRealmDefaultToString(asRecord.toString)));
+}
+/**
+ * The name of an object the platform names but reflection cannot read — a
+ * promise, a weak collection, a `WeakRef`, an `ArrayBuffer`, a generator — or
+ * `null` when there is no such name or there are keys to show instead. Their
+ * state lives in internal slots, so `Object.keys` finds nothing and the keys
+ * form would print `{}`, which reads as an empty object. `Symbol.toStringTag` is
+ * the kind the platform declares for each, and a subclass and an object from
+ * another realm still carry it, so no list of built-ins is kept here. A
+ * constructor named otherwise than its tag is named both ways, `Task [Promise]`,
+ * in the shape Node's `util.inspect` uses.
+ */
+function opaqueName(value) {
+    const tag = value[Symbol.toStringTag];
+    if (typeof tag !== "string" || Object.keys(value).length > 0)
+        return null;
+    const named = Object.getPrototypeOf(value)?.constructor?.name;
+    return typeof named === "string" && named !== "" && named !== tag ? `${named} [${tag}]` : tag;
+}
+function formOf(value) {
+    const elements = indexedElements(value);
+    if (elements !== null)
+        return { kind: "indexed", elements };
+    if (isMap(value))
+        return { kind: "map", map: value };
+    if (isSet(value))
+        return { kind: "set", set: value };
+    // Below the Array/Map/Set arms deliberately: an array also overrides
+    // `toString`, but "1,2,3" is a poorer answer than the structural form.
+    if (describesItself(value))
+        return { kind: "self" };
+    // Below `self`, so a promise subclass that spells itself keeps its spelling.
+    const opaque = opaqueName(value);
+    if (opaque !== null)
+        return { kind: "opaque", text: `${opaque} {}` };
+    return { kind: "keys", record: value };
+}
+// Which forms have positions to lay out, and which are one piece of text.
+// [LAW:types-are-the-program] Keyed by every kind, so a new form cannot reach
+// `isExpandable` without someone deciding which it is.
+const LAID_OUT = {
+    indexed: true,
+    map: true,
+    set: true,
+    keys: true,
+    opaque: false,
+    self: false,
+};
+/**
+ * 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 function isExpandable(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    try {
+        return LAID_OUT[formOf(value).kind];
+    }
+    catch {
+        return false;
+    }
 }
 /** What joins a container's positions on one line. Its width is charged for, so it is named once. */
 const SEPARATOR = ", ";
@@ -142,7 +446,27 @@ const SEPARATOR = ", ";
  */
 const EXPAND_SEPARATOR = SEPARATOR.trimEnd();
 /** The marker for positions the bound dropped, or nothing when it dropped none. */
-const elided = (dropped) => dropped > 0 ? [{ head: `... +${dropped}`, holes: [] }] : [];
+const elided = (dropped) => dropped > 0 ? [{ head: `... +${dropped}`, join: "", holes: [] }] : [];
+/**
+ * A key `Pretty._key` may leave bare. The bare form refuses a default-ignorable code point, which prints as
+ * nothing, so `"a\ufe0f"` cannot pass for `a`; `ID_Continue` admits several.
+ * An index is at most 15 digits: every such literal is a safe integer and
+ * names itself, where `99999999999999999999` would name `1e20`'s key.
+ */
+const BARE_KEY = /^(?![^]*\p{Default_Ignorable_Code_Point})(?:[\p{ID_Start}$_][\p{ID_Continue}$]*|0|[1-9]\d{0,14})$/u;
+/**
+ * What Python's `str.isprintable` refuses \u2014 control, format, private-use,
+ * unassigned, and every separator but the space \u2014 which Rich's repr escapes
+ * and JSON.stringify leaves raw past C0. Raw, DEL vanishes in `RichText`, a C1
+ * byte reaches the terminal as a control, and a format character hides or
+ * reorders what is around it.
+ */
+const UNPRINTABLE = /(?! )[\p{Cc}\p{Cf}\p{Co}\p{Cn}\p{Zl}\p{Zp}\p{Zs}]/gu;
+/** `value` in double quotes, every character that does not print escaped. */
+const quoted = (value) => JSON.stringify(value).replace(UNPRINTABLE, (c) => {
+    const hex = c.codePointAt(0).toString(16).padStart(4, "0");
+    return hex.length > 4 ? `\\u{${hex}}` : `\\u${hex}`;
+});
 export class Pretty {
     data;
     indent;
@@ -152,6 +476,8 @@ export class Pretty {
     maxDepth;
     indentGuides;
     highlighter;
+    // [LAW:no-shared-mutable-globals] A private memo, written only by `_cutString`.
+    cutStrings = new Map();
     constructor(data, options) {
         this.data = data;
         this.indent = options?.indent ?? 4;
@@ -159,24 +485,40 @@ export class Pretty {
         this.maxLength = options?.maxLength;
         this.maxString = options?.maxString;
         this.maxDepth = options?.maxDepth ?? Infinity;
-        this.indentGuides = options?.indentGuides !== false;
+        this.indentGuides = options?.indentGuides ?? false;
         this.highlighter = options?.highlighter ?? reprHighlighter;
     }
     *render(options) {
+        // `toText` has no `end`, for callers that set it inside a line; rendered,
+        // a `Pretty` is a block of its own, as the reference's is.
         yield* this.toText(options).render(options);
+        yield Segment.line();
     }
     /** The value laid out for `options.maxWidth` and highlighted: the text this renders. */
     toText(options) {
-        const formatted = this._format(this.data, rootFrame(options.maxWidth));
-        const text = new RichText(formatted, { end: "" });
-        this.highlighter.highlight(text);
-        if (this.indentGuides) {
-            this._addIndentGuides(text);
+        const laid = this._format(this.data, rootFrame(options.maxWidth));
+        // The reference draws no guide at all on an ASCII-only console, so there is
+        // no ASCII glyph to fall back to: `null` is none.
+        const guide = this.indentGuides ? drawable(options, GUIDE, null, (g) => g ?? "") : null;
+        const { plain, guides, arrows } = drawMargins(laid, this.indent, guide);
+        // The highlighter reads the text with each arrow's `>` a space — of the
+        // repr patterns only the tag's reads a `>` — and the text then shows it
+        // again: one code unit for one, so every span lands where it was found.
+        let reading = "";
+        let from = 0;
+        for (const arrow of arrows) {
+            reading += plain.slice(from, arrow) + " ";
+            from = arrow + 1;
         }
+        const text = new RichText(reading + plain.slice(from), { end: "" });
+        this.highlighter.highlight(text);
+        text.plain = plain;
+        for (const [start, end] of guides)
+            text.stylize("repr.indent", start, end);
         return text;
     }
     measure(_options) {
-        const formatted = this._format(this.data, rootFrame(_options.maxWidth));
+        const formatted = this._format(this.data, rootFrame(_options.maxWidth)).text;
         const lines = formatted.split("\n");
         let max = 0;
         for (const line of lines) {
@@ -198,17 +540,8 @@ export class Pretty {
         if (value === undefined)
             return "undefined";
         switch (typeof value) {
-            case "string": {
-                // The dropped count is an annotation about the value, not part of it,
-                // so it goes after the closing quote — the way `maxLength`'s `... +N`
-                // sits beside the kept entries rather than inside the last one. Inside
-                // the quotes it reads as content, and copying it out yields a string
-                // the program never held.
-                if (this.maxString === undefined || value.length <= this.maxString) {
-                    return JSON.stringify(value);
-                }
-                return JSON.stringify(value.slice(0, this.maxString)) + `+${value.length - this.maxString}`;
-            }
+            case "string":
+                return this._string(value);
             case "number":
             case "bigint":
             case "boolean":
@@ -220,6 +553,58 @@ export class Pretty {
         }
         return null;
     }
+    /**
+     * `value` quoted, and cut to `maxString` when it is longer.
+     *
+     * The dropped count is an annotation about the value, not part of it, so it
+     * goes after the closing quote — the way `maxLength`'s `... +N` sits beside
+     * the kept entries rather than inside the last one. Inside the quotes it
+     * reads as content, and copying it out yields a string the program never
+     * held.
+     *
+     * A cluster is at least one code unit, so a string no longer than the cap in
+     * code units is within it in clusters, and needs no segmenting.
+     */
+    _string(value) {
+        if (this.maxString === undefined || value.length <= this.maxString)
+            return quoted(value);
+        return this._cutString(value, this.maxString);
+    }
+    /**
+     * A key as an object literal would spell it: bare when it is a name or an
+     * index, which reads as itself, and quoted as a string otherwise. Rich reprs
+     * every key; printed raw, `"a b"` was indistinguishable from two words and a
+     * `\r` in one was dropped by `RichText`, so the key shown was not the key held.
+     * Quoting only what needs it keeps the JavaScript reading `{ a: 1 }`. A
+     * quoted key is a string and `maxString` cuts it; a bare one is a name.
+     */
+    _key(key) {
+        return BARE_KEY.test(key) ? key : this._string(key);
+    }
+    /**
+     * `value` cut to `max` grapheme clusters, with the rest counted after the
+     * closing quote.
+     *
+     * The unit is the cluster of the value, counted before `quoted` 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.
+     */
+    _cutString(value, max) {
+        let cut = this.cutStrings.get(value);
+        if (cut === undefined) {
+            const clusters = graphemes(value);
+            cut = clusters.length <= max
+                ? quoted(value)
+                : quoted(clusters.slice(0, max).join("")) + `+${clusters.length - max}`;
+            this.cutStrings.set(value, cut);
+        }
+        return cut;
+    }
     /**
      * A container, or the text standing in for one that is empty or past the
      * depth cap.
@@ -255,51 +640,57 @@ export class Pretty {
         // and `slice` reads a negative end as counting from the far end — it would
         // keep all but the last few keys where the other arms take none.
         const cap = Math.max(0, Math.min(this.maxLength ?? Infinity, bound));
-        const elements = indexedElements(value);
-        if (elements !== null) {
-            return this._container("[", "]", "", elements.length, level, () => {
-                // Positions rather than values: each index is read in its own slot, so
-                // one throwing accessor costs its own slot, not the whole sequence.
-                const shown = Math.min(elements.length, cap);
-                return Array.from({ length: shown }, (_, i) => ({
+        const form = formOf(value);
+        switch (form.kind) {
+            case "indexed": {
+                const { elements } = form;
+                return this._container("[", "]", "", elements.length, level, () => {
+                    // Positions rather than values: each index is read in its own slot, so
+                    // one throwing accessor costs its own slot, not the whole sequence.
+                    const shown = Math.min(elements.length, cap);
+                    return Array.from({ length: shown }, (_, i) => ({
+                        head: "",
+                        join: "",
+                        holes: [{ read: () => elements[i], tail: flat("") }],
+                    }));
+                });
+            }
+            case "map":
+                return this._container("Map {", "}", " ", form.map.size, level, () => take(form.map.entries(), cap).map(([k, v]) => ({
                     head: "",
-                    holes: [{ read: () => elements[i], tail: "" }],
-                }));
-            });
-        }
-        if (value instanceof Map) {
-            return this._container("Map {", "}", " ", value.size, level, () => take(value.entries(), cap).map(([k, v]) => ({
-                head: "",
-                holes: [{ read: () => k, tail: " => " }, { read: () => v, tail: "" }],
-            })));
-        }
-        if (value instanceof Set) {
-            return this._container("Set {", "}", " ", value.size, level, () => take(value, cap).map((v) => ({
-                head: "",
-                holes: [{ read: () => v, tail: "" }],
-            })));
+                    join: "",
+                    holes: [{ read: () => k, tail: ARROW }, { read: () => v, tail: flat("") }],
+                })));
+            case "set":
+                return this._container("Set {", "}", " ", form.set.size, level, () => take(form.set, cap).map((v) => ({
+                    head: "",
+                    join: "",
+                    holes: [{ read: () => v, tail: flat("") }],
+                })));
+            case "opaque":
+                return { kind: "text", text: form.text };
+            case "self":
+                return { kind: "text", text: String(value) };
+            case "keys": {
+                // No self-description, so the keys are the whole story.
+                const { record } = form;
+                const keys = Object.keys(record);
+                return this._container("{", "}", " ", keys.length, level, () => keys.slice(0, cap).map((k) => ({
+                    head: this._key(k),
+                    join: ": ",
+                    holes: [{ read: () => record[k], tail: flat("") }],
+                })));
+            }
         }
-        // Objects that answer the display question themselves. Sits below the
-        // Array/Map/Set arms deliberately: an array also overrides `toString`, but
-        // "1,2,3" is a poorer answer than the structural form above.
-        if (describesItself(value))
-            return { kind: "text", text: String(value) };
-        // Plain objects — no self-description, so the keys are the whole story.
-        const obj = value;
-        const keys = Object.keys(obj);
-        return this._container("{", "}", " ", keys.length, level, () => keys.slice(0, cap).map((k) => ({
-            head: `${k}: `,
-            holes: [{ read: () => obj[k], tail: "" }],
-        })));
     }
     /** The laid-out form of a value, expanded across lines wherever one line will not do. */
     _format(value, at) {
         const scalar = this._scalar(value);
         if (scalar !== null)
-            return scalar;
+            return this._place(scalar, at);
         const object = value;
         if (at.open.has(object))
-            return "[Circular]";
+            return this._place("[Circular]", at);
         at.open.add(object);
         try {
             return this._formatObject(object, at);
@@ -308,17 +699,23 @@ export class Pretty {
             // The container's *shape* would not be read — `Object.keys`, an iterator,
             // `toString`. Nothing can be enumerated, so the whole container degrades;
             // a value that merely would not be read degrades alone, in its own slot.
-            return threw(error);
+            return this._place(threw(error), at);
         }
         finally {
             at.open.delete(object);
         }
     }
     /** The arms for a non-null object, with `value` already on the open path. */
-    _formatObject(value, at) {
-        const shape = this._shape(value, at.level, Infinity);
+    _formatObject(value, from) {
+        const shape = this._shape(value, from.level, Infinity);
         if (shape.kind === "text")
-            return shape.text;
+            return this._place(shape.text, from);
+        // Chosen before the compact try, because the choice cannot change its
+        // answer where it stands: a line the opener will not fit on cannot hold the
+        // one-line form it starts. One pass at the chosen line, and not a second
+        // call per move — this method runs once per level of the data, and a
+        // thousand levels is within what it is asked to lay out.
+        const { lead, at } = this._opening(from, shape.open);
         if (!this.expandAll) {
             // rich-pretty-xms: budget from `at.column` and `at.reserve`, not from
             // `at.inset` alone. `at.column` is where *this* value's text actually
@@ -336,20 +733,48 @@ export class Pretty {
                 open: at.open,
             });
             if (compact !== null)
-                return compact;
+                return placed(cat(lead, compact), at.inset);
         }
-        const indentStr = " ".repeat(this.indent * at.inset);
-        const innerIndent = " ".repeat(this.indent * (at.inset + 1));
+        const innerIndent = at.inset + this.indent;
         // Every non-last slot gets `EXPAND_SEPARATOR` appended right after it
         // below, on the same line as whatever its own last character was — the
         // last slot doesn't. Two frames, not one per slot: `reserve` is the only
         // field that varies, and it only ever takes these two values.
-        const base = { inset: at.inset + 1, level: at.level + 1, maxWidth: at.maxWidth, column: cellLen(innerIndent), open: at.open };
+        const base = this._onLine({ ...at, level: at.level + 1, column: innerIndent, margin: innerIndent }, innerIndent);
         const midFrame = { ...base, reserve: cellLen(EXPAND_SEPARATOR) };
         const lastFrame = { ...base, reserve: 0 };
         const lastSlot = shape.slots.length - 1;
-        const parts = shape.slots.map((slot, i) => innerIndent + this._expandSlot(slot, i === lastSlot ? lastFrame : midFrame));
-        return shape.open + "\n" + parts.join(EXPAND_SEPARATOR + "\n") + "\n" + indentStr + shape.close;
+        const parts = shape.slots.map((slot, i) => this._expandSlot(slot, i === lastSlot ? lastFrame : midFrame));
+        return expansion(lead, shape, parts, innerIndent, at.inset);
+    }
+    /**
+     * 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.
+     */
+    _opening(at, open) {
+        const width = cellLen(open);
+        if (at.hang === null || at.column + width <= at.maxWidth || at.hang + width > at.maxWidth) {
+            return { lead: flat(""), at };
+        }
+        return {
+            lead: newline(at.hang),
+            at: { ...this._onLine(at, at.hang), column: at.hang },
+        };
+    }
+    /**
+     * `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.
+     */
+    _onLine(at, inset) {
+        return { ...at, inset, hang: inset + this.indent };
     }
     /**
      * One position, with every value in it laid out.
@@ -364,7 +789,8 @@ export class Pretty {
      * 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
@@ -373,42 +799,92 @@ export class Pretty {
      * `out` grows past it.
      */
     _expandSlot(slot, at) {
-        let out = slot.head;
+        // A key is one piece of text, placed like any other: one wider than its
+        // line wraps under its slot rather than running on to column 0. Only a slot
+        // with no values has its `at.reserve` land right after the head; a value
+        // may move below it.
+        const head = this._place(slot.head, { ...at, reserve: cellLen(slot.join) + (slot.holes.length === 0 ? at.reserve : 0) });
+        let out = cat(head, flat(slot.join));
+        let inset = head.inset;
         const lastHole = slot.holes.length - 1;
         for (let i = 0; i < slot.holes.length; i++) {
             const hole = slot.holes[i];
             // This is the read that costs the least when it fails: neighbours are
             // unaffected, so `{ a: 1, b: [Threw: …], c: 3 }` still shows everything
             // that could be read.
-            let text;
+            const reserve = cellLen(hole.tail.text) + (i === lastHole ? at.reserve : 0);
+            const here = { ...this._onLine(at, inset), column: lineColumn(at.column, out.text), reserve };
+            let laid;
             try {
-                const reserve = cellLen(hole.tail) + (i === lastHole ? at.reserve : 0);
-                text = this._format(hole.read(), { ...at, column: lineColumn(at.column, out), reserve });
+                laid = this._format(hole.read(), here);
             }
             catch (error) {
-                text = threw(error);
+                laid = this._place(threw(error), here);
             }
-            out += text + hole.tail;
+            out = follow(out, laid, hole.tail);
+            inset = laid.inset;
         }
         return out;
     }
+    /**
+     * 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.
+     */
+    _place(text, at) {
+        // At the root nothing precedes the text that this formatter wrote, so none
+        // of its lines has indent that is the structure's.
+        if (at.hang === null)
+            return placed({ text, margins: text.split("\n").slice(1).map(() => 0), arrows: [] }, at.inset);
+        // A hanging row needs a cell to stand in. One indent past the slot has none
+        // when the value sits one indent from the edge, and a row put there anyway
+        // overruns the width and wraps to column 0 — so rows start where the value
+        // began instead, and the first word folds where it stands.
+        const hang = at.maxWidth - at.hang - at.reserve > 0 ? at.hang : Math.min(at.hang, at.column);
+        const lines = text.split("\n");
+        const last = lines.length - 1;
+        const room = (i, column) => at.maxWidth - column - (i === last ? at.reserve : 0);
+        const [first, ...rows] = lines.flatMap((line, i) => i === 0
+            ? rowsOf(line, stayingLength(line, room(0, at.column), at.column > hang), room(0, hang))
+            : rowsOf(line, stayingLength(line, room(i, hang), false), room(i, hang)));
+        // A row hangs past its slot's margin, not at a margin of its own: the
+        // cells between are the value's, and a guide there would sit inside it.
+        const hung = rows.map((row) => cat(newline(at.margin), flat(row === "" ? "" : " ".repeat(hang - at.margin) + row)));
+        return placed(cat(flat(first), ...hung), rows.length === 0 ? at.inset : hang);
+    }
     /** The one-line form of a value, or `null` when it will not fit `at.budget`. */
     _oneLine(value, at) {
         const scalar = this._scalar(value);
         if (scalar !== null)
-            return fitOneLine(scalar, at.budget);
+            return fitOneLine(flat(scalar), at.budget);
         const object = value;
         if (at.open.has(object))
-            return fitOneLine("[Circular]", at.budget);
+            return fitOneLine(flat("[Circular]"), at.budget);
         at.open.add(object);
         try {
             const shape = this._shape(object, at.level, at.budget);
             if (shape.kind === "text")
-                return fitOneLine(shape.text, at.budget);
+                return fitOneLine(flat(shape.text), at.budget);
             return this._joinOneLine(shape, { level: at.level + 1, budget: at.budget, open: at.open });
         }
         catch (error) {
-            return fitOneLine(threw(error), at.budget);
+            return fitOneLine(flat(threw(error)), at.budget);
         }
         finally {
             at.open.delete(object);
@@ -433,44 +909,34 @@ export class Pretty {
             return null;
         const pieces = [];
         for (const slot of shape.slots) {
-            used += pieces.length > 0 ? cellLen(SEPARATOR) : 0;
+            if (pieces.length > 0) {
+                used += cellLen(SEPARATOR);
+                pieces.push(flat(SEPARATOR));
+            }
             const piece = this._slotOneLine(slot, { ...at, budget: at.budget - used });
             if (piece === null)
                 return null;
-            used += cellLen(piece);
+            used += cellLen(piece.text);
             pieces.push(piece);
         }
-        return shape.open + shape.pad + pieces.join(SEPARATOR) + shape.pad + shape.close;
+        return cat(flat(shape.open + shape.pad), ...pieces, flat(shape.pad + shape.close));
     }
     /** One position on one line, or `null` when any value in it will not fit. */
     _slotOneLine(slot, at) {
-        let out = slot.head;
+        let out = flat(slot.head + slot.join);
         for (const hole of slot.holes) {
-            const left = at.budget - cellLen(out);
+            const left = at.budget - cellLen(out.text);
             let text;
             try {
                 text = this._oneLine(hole.read(), { ...at, budget: left });
             }
             catch (error) {
-                text = fitOneLine(threw(error), left);
+                text = fitOneLine(flat(threw(error)), left);
             }
             if (text === null)
                 return null;
-            out += text + hole.tail;
+            out = cat(out, text, hole.tail);
         }
         return fitOneLine(out, at.budget);
     }
-    _addIndentGuides(text) {
-        const lines = text.plain.split("\n");
-        let offset = 0;
-        for (const line of lines) {
-            const leadingSpaces = line.length - line.trimStart().length;
-            for (let i = 0; i < leadingSpaces; i += this.indent) {
-                if (i + offset < text.length) {
-                    text.stylize("repr.indent", offset + i, offset + i + 1);
-                }
-            }
-            offset += line.length + 1; // +1 for newline
-        }
-    }
 }