@promptctl/rich-js 0.9.0 → 0.11.0

package/dist/core/markup.js

@@ -14,8 +14,9 @@
  * (`[bold]a[italic]b[/bold]c[/italic]`) because a style is an annotation and
  * annotations may overlap freely; a plugin tag is a replacement whose handler
  * takes one contiguous `inner`, so an overlapping pair has no slice to hand it
- * and is rejected with a `MarkupError`.
+ * and is rejected with a `MarkupSyntaxError`.
  */
+import { cellLen } from "./cells.js";
 import { Style, StyleSyntaxError } from "./style.js";
 import { RichText, Span } from "./text.js";
 import { emojiReplace } from "./emoji.js";
@@ -45,6 +46,94 @@ export class MarkupError extends Error {
         this.name = "MarkupError";
     }
 }
+// --- MarkupSyntaxError ---
+/**
+ * A markup string that cannot be parsed, with where it went wrong.
+ *
+ * [LAW:types-are-the-program] A subclass rather than optional fields on
+ * `MarkupError`, because the parent is also what `MarkupRegistry.register`
+ * throws, and a registration has no source text to point into. Every error this
+ * class describes has a location, so none of its fields is optional and no
+ * caller has to ask whether one is present — `instanceof` is the only question.
+ *
+ * [LAW:one-source-of-truth] The constructor takes the facts the parser holds —
+ * the string, the offset of the offending tag, what was open — and derives
+ * `line`, `column` and the message from them, so the numbers a caller reads
+ * and the caret the message draws cannot disagree.
+ */
+export class MarkupSyntaxError extends MarkupError {
+    /** The problem alone, with no location, for callers building their own message. */
+    reason;
+    /** The whole markup string that failed, as the caller passed it. */
+    markup;
+    /** Index into `markup` of the tag the parser rejected. */
+    offset;
+    /** 1-based line of `offset`; lines are separated by `\n`. */
+    line;
+    /** 1-based column of `offset` within its line, in UTF-16 code units. */
+    column;
+    /**
+     * The opening tags still open at `offset`, outermost first, as written. For
+     * overlapping plugin tags, only plugin tags are named.
+     */
+    openTags;
+    constructor(reason, markup, offset, openTags) {
+        const lineStart = markup.lastIndexOf("\n", offset - 1) + 1;
+        const lineEnd = markup.indexOf("\n", offset);
+        const text = markup.slice(lineStart, lineEnd === -1 ? markup.length : lineEnd);
+        const line = countNewlines(markup.slice(0, lineStart)) + 1;
+        const column = offset - lineStart + 1;
+        const open = openTags.length > 0 ? openTags.join(" ") : "none";
+        super(`${printable(reason)} (line ${line}, column ${column})\n` +
+            `${excerpt(text, offset - lineStart)}\n` +
+            `Open tags: ${printable(open)}`);
+        this.name = "MarkupSyntaxError";
+        this.reason = reason;
+        this.markup = markup;
+        this.offset = offset;
+        this.line = line;
+        this.column = column;
+        this.openTags = openTags;
+    }
+}
+function countNewlines(text) {
+    return text.split("\n").length - 1;
+}
+// Code points shown either side of the error before the excerpt is cut and
+// marked with an ellipsis. Enough to recognise the surrounding tags on a line
+// that is long, templated, or machine-assembled, without printing all of it.
+const EXCERPT_CONTEXT = 30;
+/**
+ * `text` with each C0 control and DEL shown as one space.
+ *
+ * [LAW:single-enforcer] Every part of the message that quotes the caller's
+ * markup passes through here: the reason and the open tags quote tag text, and
+ * the tag grammar admits control characters, so an `ESC ]` inside a tag would
+ * otherwise open an OSC sequence in the terminal printing the error. In the
+ * excerpt it also keeps the caret aligned, since a control occupies no cell.
+ * The fields keep the text as written; only the message is made printable.
+ */
+function printable(text) {
+    return text.replace(/[\x00-\x1f\x7f]/g, " ");
+}
+/**
+ * Two lines: the source line around `index`, and a caret under it.
+ *
+ * The window is cut in code points, so a surrogate pair is never split, and the
+ * caret is placed by cell width, so a wide character before the error still
+ * leaves it under the right cell.
+ */
+function excerpt(text, index) {
+    const chars = Array.from(printable(text));
+    const at = Array.from(text.slice(0, index)).length;
+    const from = Math.max(0, at - EXCERPT_CONTEXT);
+    const to = Math.min(chars.length, at + EXCERPT_CONTEXT);
+    const head = from > 0 ? "…" : "";
+    const tail = to < chars.length ? "…" : "";
+    const before = head + chars.slice(from, at).join("");
+    const shown = before + chars.slice(at, to).join("") + tail;
+    return `  ${shown}\n  ${" ".repeat(cellLen(before))}^`;
+}
 // --- escape ---
 /**
  * Escapes markup characters so they render as literal text.
@@ -106,6 +195,9 @@ function parseTags(markup) {
     }
     return tags;
 }
+function wholeString(markup) {
+    return { source: markup, base: 0, enclosing: [] };
+}
 /**
  * Parses the built-in style dialect — `[bold red]text[/bold red]` — into a
  * `RichText` with styled spans. Module-private on purpose: `renderMarkup` is
@@ -127,7 +219,7 @@ function parseTags(markup) {
  * function names; an empty registry puts it in the data, where the one
  * boundary admits both.
  */
-function render(markup, baseStyle, options) {
+function render(markup, origin, baseStyle, options) {
     // Fast path: no brackets at all
     if (!HAS_TAG_RE.test(markup)) {
         let text = markup;
@@ -145,6 +237,10 @@ function render(markup, baseStyle, options) {
     let plainText = "";
     const spans = [];
     const openStack = [];
+    const unparsable = (reason, tag) => new MarkupSyntaxError(reason, origin.source, origin.base + tag.start, [
+        ...origin.enclosing,
+        ...openStack.map((opened) => opened.tag),
+    ]);
     let lastEnd = 0;
     for (const tag of tags) {
         // Add text before this tag
@@ -154,7 +250,9 @@ function render(markup, baseStyle, options) {
         if (tag.isImplicitClose) {
             // [/] — close the most recent open tag
             if (openStack.length === 0) {
-                throw new MarkupError("Closing tag [/] has nothing to close");
+                // [/] never closes a plugin tag, so an enclosing plugin tag can be open
+                // here while no style tag is.
+                throw unparsable(`Closing tag ${tag.fullMatch} has no open style tag to close`, tag);
             }
             const opened = openStack.pop();
             spans.push(new Span(opened.textStart, plainText.length, openTagStyle(opened)));
@@ -163,7 +261,7 @@ function render(markup, baseStyle, options) {
             // [/style] — find and close matching open tag
             const idx = findLastOpen(openStack, tag.styleName);
             if (idx === -1) {
-                throw new MarkupError(`Closing tag [/${tag.styleName}] doesn't match any open tag`);
+                throw unparsable(`Closing tag ${tag.fullMatch} doesn't match any open tag`, tag);
             }
             const opened = openStack[idx];
             spans.push(new Span(opened.textStart, plainText.length, openTagStyle(opened)));
@@ -172,6 +270,7 @@ function render(markup, baseStyle, options) {
         else {
             // Opening tag
             openStack.push({
+                tag: tag.fullMatch,
                 styleName: tag.styleName,
                 parameters: tag.parameters,
                 textStart: plainText.length,
@@ -390,20 +489,23 @@ function parsePluginAttrs(after) {
  * append path is uniform.
  */
 export function renderMarkup(markup, options) {
+    return renderSlice(markup, wholeString(markup), options);
+}
+function renderSlice(markup, origin, options) {
     const registry = options?.registry ?? globalMarkupRegistry;
     const baseStyle = options?.baseStyle;
     const doEmoji = options?.emoji !== false;
     // Fast path: no `[` at all → no possible tags.
     if (!HAS_TAG_RE.test(markup)) {
-        return render(markup, baseStyle, { emoji: doEmoji });
+        return render(markup, origin, baseStyle, { emoji: doEmoji });
     }
     const tags = parseTags(markup);
     // Pair each opening plugin tag with its matching closer up-front, so the
     // splice walk can just iterate top-level pairs in source order with no
     // nested-state book-keeping.
-    const { annotated, topLevel: tagPairs } = pairPluginTags(tags, registry);
+    const { annotated, topLevel: tagPairs } = pairPluginTags(tags, registry, origin);
     if (tagPairs.size === 0) {
-        return render(markup, baseStyle, { emoji: doEmoji });
+        return render(markup, origin, baseStyle, { emoji: doEmoji });
     }
     // [LAW:one-type-per-behavior] Always assemble a single RichText. Fragments
     // between plugin pairs are parsed by the built-in `render`, plugin pairs
@@ -415,22 +517,26 @@ export function renderMarkup(markup, options) {
         const open = annotated[openIdx];
         const close = annotated[closeIdx];
         if (open.start > cursor) {
-            out.append(render(markup.slice(cursor, open.start), baseStyle, { emoji: doEmoji }));
+            out.append(render(markup.slice(cursor, open.start), offsetBy(origin, cursor), baseStyle, { emoji: doEmoji }));
         }
         const innerRaw = markup.slice(open.end, close.start);
-        const innerRichText = renderMarkup(innerRaw, options);
+        const innerRichText = renderSlice(innerRaw, { ...offsetBy(origin, open.end), enclosing: [...origin.enclosing, open.fullMatch] }, options);
         const handler = registry.get(open.pluginName);
         out.append(handler({ attrs: open.attrs, children: innerRichText, raw: innerRaw }));
         cursor = close.end;
     }
     if (cursor < markup.length) {
-        out.append(render(markup.slice(cursor), baseStyle, { emoji: doEmoji }));
+        out.append(render(markup.slice(cursor), offsetBy(origin, cursor), baseStyle, { emoji: doEmoji }));
     }
     if (baseStyle)
         out.stylize(baseStyle);
     return out;
 }
-function pairPluginTags(tags, registry) {
+/** The origin of a sub-slice starting `offset` into the slice `origin` describes. */
+function offsetBy(origin, offset) {
+    return { ...origin, base: origin.base + offset };
+}
+function pairPluginTags(tags, registry, origin) {
     // Annotate tags with plugin info, then pair openers with closers. Only
     // top-level pairs are returned; inner pairs will be re-discovered by the
     // recursive `renderMarkup` call on the inner slice.
@@ -477,11 +583,18 @@ function pairPluginTags(tags, registry) {
             // hand it. A style span may overlap because it annotates; a plugin pair
             // may not because it replaces.
             if (annotated[closeIdx].end > outerEnd) {
-                const inner = annotated[openIdx].pluginName;
-                const outer = annotated[outerOpenIdx].pluginName;
-                throw new MarkupError(`Plugin tag [${inner}] overlaps [${outer}]: plugin tags must nest, ` +
+                const inner = annotated[openIdx];
+                const outer = annotated[outerOpenIdx];
+                // The caret goes under the outer pair's closing tag, the point where
+                // nesting breaks. This pass sees plugin tags only; of those, a pair is
+                // open there when it opens before that tag and closes at or after it.
+                const caret = annotated[pairs.get(outerOpenIdx)].start;
+                const openAtCaret = sortedOpens
+                    .filter((o) => annotated[o].start < caret && annotated[pairs.get(o)].start >= caret)
+                    .map((o) => annotated[o].fullMatch);
+                throw new MarkupSyntaxError(`Plugin tag [${inner.pluginName}] overlaps [${outer.pluginName}]: plugin tags must nest, ` +
                     `because a handler receives one contiguous slice. ` +
-                    `Close [/${inner}] before [/${outer}].`);
+                    `Close [/${inner.pluginName}] before [/${outer.pluginName}].`, origin.source, origin.base + caret, [...origin.enclosing, ...openAtCaret]);
             }
             continue;
         }
@@ -504,4 +617,3 @@ function annotatePluginTag(tag, registry) {
     const attrs = tag.isClosing ? {} : parsePluginAttrs(after);
     return { ...tag, pluginName: name, attrs };
 }
-//# sourceMappingURL=markup.js.map

package/dist/core/measure.d.ts

@@ -25,4 +25,3 @@ export declare class Measurement {
     static get(options: RenderOptions, measurable: Measurable): Measurement;
 }
 export declare function measureRenderables(options: RenderOptions, measurables: Measurable[]): Measurement;
-//# sourceMappingURL=measure.d.ts.map

package/dist/core/measure.js

@@ -59,4 +59,3 @@ export function measureRenderables(options, measurables) {
     }
     return new Measurement(minOfAll, maxOfAll);
 }
-//# sourceMappingURL=measure.js.map

package/dist/core/oklch.d.ts

@@ -125,4 +125,3 @@ export declare class Oklch {
      */
     private findInGamutChroma;
 }
-//# sourceMappingURL=oklch.d.ts.map

package/dist/core/oklch.js

@@ -262,4 +262,3 @@ export class Oklch {
         return lo;
     }
 }
-//# sourceMappingURL=oklch.js.map

package/dist/core/osc8.d.ts

@@ -0,0 +1,68 @@
+/**
+ * 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] Every producer (`segmentsToString`,
+ * `Style.render`) opens a link through `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 on nothing; 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.
+ *
+ * [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, colorSystem): 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.
+ */
+/** Remove every byte that could break a URL out of its OSC 8 wrap. */
+export declare function stripOscTerminators(url: string): string;
+/**
+ * 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 declare function osc8Open(url: string): string;
+/** The bytes that close the current hyperlink. */
+export declare const OSC8_CLOSE = "\u001B]8;;\u001B\\";
+/**
+ * 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 declare const OSC8: RegExp;
+/** One OSC 8 sequence found in rendered bytes. A close has `uri === ""`. */
+export interface Osc8Sequence {
+    /** Offset of the sequence in the scanned string. */
+    readonly index: number;
+    /** Length of the whole sequence, terminator included. */
+    readonly length: number;
+    /** The params field (`id=…`); empty on a close. */
+    readonly params: string;
+    /** The URI; empty on a close. */
+    readonly uri: string;
+}
+/**
+ * Every OSC 8 sequence in `text`, in order — the typed way to read rendered
+ * bytes back.
+ */
+export declare function osc8Sequences(text: string): Osc8Sequence[];

package/dist/core/osc8.js

@@ -0,0 +1,90 @@
+/**
+ * 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] Every producer (`segmentsToString`,
+ * `Style.render`) opens a link through `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 on nothing; 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.
+ *
+ * [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, colorSystem): 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.
+ */
+/**
+ * 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, "");
+}
+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`.
+ *
+ * [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);
+    return `\x1b]8;id=${linkId(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/pretty.d.ts

@@ -97,7 +97,27 @@ 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;
-    /** One position, with every value in it laid out. */
+    /**
+     * 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.
+     *
+     * 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;
     /** The one-line form of a value, or `null` when it will not fit `at.budget`. */
     private _oneLine;
@@ -119,4 +139,3 @@ export declare class Pretty implements Renderable, Measurable {
     private _slotOneLine;
     private _addIndentGuides;
 }
-//# sourceMappingURL=pretty.d.ts.map

package/dist/core/pretty.js

@@ -20,7 +20,28 @@ import { cellLen } from "./cells.js";
 import { RichText } from "./text.js";
 import { ReprHighlighter } from "./highlighter.js";
 const reprHighlighter = new ReprHighlighter();
-const rootFrame = (maxWidth) => ({ inset: 0, level: 0, maxWidth, open: new WeakSet() });
+const rootFrame = (maxWidth) => ({
+    inset: 0,
+    level: 0,
+    maxWidth,
+    column: 0,
+    reserve: 0,
+    open: new WeakSet(),
+});
+/**
+ * The column reached after `text` is appended to a line currently at `column`.
+ *
+ * A hole's formatted value can itself span multiple lines — a nested
+ * container that failed its own compact try. What comes after it (a Map
+ * entry's tail, the next hole) sits after `text`'s *last* line, not at
+ * `column + cellLen(text)`, so a multi-line insert resets the column to that
+ * last line's width instead of accumulating across lines that were never on
+ * the same row.
+ */
+function lineColumn(column, text) {
+    const lastNewline = text.lastIndexOf("\n");
+    return lastNewline === -1 ? column + cellLen(text) : cellLen(text.slice(lastNewline + 1));
+}
 /**
  * The text, when it is a single line no wider than `budget` — otherwise `null`.
  *
@@ -111,6 +132,15 @@ function describesItself(value) {
 }
 /** What joins a container's positions on one line. Its width is charged for, so it is named once. */
 const SEPARATOR = ", ";
+/**
+ * What joins a container's positions across lines, once it has expanded —
+ * `SEPARATOR` without the trailing space a newline already provides.
+ * rich-pretty-xms: named, and derived rather than a second hand-typed
+ * literal, so the width it costs a non-last slot's own compact try —
+ * reserved via `Frame.reserve` — cannot drift from what `_formatObject`
+ * actually joins with.
+ */
+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: [] }] : [];
 export class Pretty {
@@ -165,11 +195,15 @@ export class Pretty {
             return "undefined";
         switch (typeof value) {
             case "string": {
-                let str = value;
-                if (this.maxString !== undefined && str.length > this.maxString) {
-                    str = str.slice(0, this.maxString) + `+${value.length - this.maxString}`;
+                // 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(str);
+                return JSON.stringify(value.slice(0, this.maxString)) + `+${value.length - this.maxString}`;
             }
             case "number":
             case "bigint":
@@ -281,35 +315,76 @@ export class Pretty {
         const shape = this._shape(value, at.level, Infinity);
         if (shape.kind === "text")
             return shape.text;
-        const indentStr = " ".repeat(this.indent * at.inset);
         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
+            // starts on its line, which already includes whatever `_expandSlot`
+            // prepended for us (a key and its separator, a Map entry's `" => "`,
+            // ...); `at.reserve` is what a fixed piece of literal text — the rest
+            // of this hole's own tail, or the trailing `,` a non-last slot gets
+            // joined with — is known to cost right after, before this value's own
+            // text even starts. Deriving the budget from the indent alone assumed
+            // nothing precedes *or follows* the value on its line, which is only
+            // true at the root and for the last hole of an array's last element.
             const compact = this._joinOneLine(shape, {
                 level: at.level + 1,
-                budget: at.maxWidth - cellLen(indentStr),
+                budget: at.maxWidth - at.column - at.reserve,
                 open: at.open,
             });
             if (compact !== null)
                 return compact;
         }
+        const indentStr = " ".repeat(this.indent * at.inset);
         const innerIndent = " ".repeat(this.indent * (at.inset + 1));
-        const deeper = { inset: at.inset + 1, level: at.level + 1, maxWidth: at.maxWidth, open: at.open };
-        const parts = shape.slots.map((slot) => innerIndent + this._expandSlot(slot, deeper));
-        return shape.open + "\n" + parts.join(",\n") + "\n" + indentStr + shape.close;
+        // 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 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;
     }
-    /** One position, with every value in it laid out. */
+    /**
+     * 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.
+     *
+     * 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.
+     */
     _expandSlot(slot, at) {
         let out = slot.head;
-        for (const hole of slot.holes) {
+        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;
             try {
-                out += this._format(hole.read(), at);
+                const reserve = cellLen(hole.tail) + (i === lastHole ? at.reserve : 0);
+                text = this._format(hole.read(), { ...at, column: lineColumn(at.column, out), reserve });
             }
             catch (error) {
-                out += threw(error);
+                text = threw(error);
             }
-            out += hole.tail;
+            out += text + hole.tail;
         }
         return out;
     }
@@ -395,4 +470,3 @@ export class Pretty {
         }
     }
 }
-//# sourceMappingURL=pretty.js.map

package/dist/core/protocol.d.ts

@@ -3,7 +3,7 @@
  * [LAW:one-source-of-truth] These interfaces are the single authority for the rendering contract.
  */
 import type { Segment } from "./segment.js";
-import { type Style, type Theme } from "./style.js";
+import { type Style, type StyleSyntaxError, type Theme } from "./style.js";
 export interface RenderOptions {
     /**
      * The cells this renderable may occupy. A count of cells, so a non-negative
@@ -30,7 +30,24 @@ export interface RenderOptions {
      * built-in defaults apply. Read it through `getStyle` rather than directly.
      */
     theme?: Theme;
+    /**
+     * Called each time a render degrades a style string it cannot parse to
+     * unstyled, once per resolution — a style the render reads twice is reported
+     * twice. Absent, the failure passes silently. A handler that throws makes
+     * the render strict: the error leaves `render`.
+     */
+    onStyleError?: StyleErrorHandler;
 }
+/**
+ * Receives a style error a render would otherwise absorb: the parse failure,
+ * and the whole style string it came from — the error names only the token
+ * that failed, and `"bold rd"` loses its `bold` too.
+ *
+ * [LAW:no-mode-explosion] Strict mode is not a second option beside this one.
+ * It is a handler that throws, so there is no "strict and a callback" state
+ * whose order anyone has to define.
+ */
+export type StyleErrorHandler = (error: StyleSyntaxError, style: string) => void;
 /**
  * The style a `string | Style` stands for in this render.
  *
@@ -109,4 +126,3 @@ export interface Measurable {
 }
 export declare function isRenderable(obj: unknown): obj is Renderable;
 export declare function isMeasurable(obj: unknown): obj is Measurable;
-//# sourceMappingURL=protocol.d.ts.map