@promptctl/rich-js 0.17.0 → 0.18.1

package/dist/core/markup.js

@@ -18,7 +18,7 @@
  */
 import { cellLen } from "./cells.js";
 import { Style, StyleSyntaxError } from "./style.js";
-import { RichText, Span } from "./text.js";
+import { RichText, Span, stripControlChars } from "./text.js";
 import { emojiReplace } from "./emoji.js";
 // --- Tag ---
 export class Tag {
@@ -137,13 +137,32 @@ function excerpt(text, index) {
 // --- escape ---
 /**
  * Escapes markup characters so they render as literal text.
+ *
+ * [LAW:one-source-of-truth] The inverse of the two ways the parser reads a
+ * backslash run in front of a bracket, over the same `TAG_BODY`: before a tag
+ * the run is halved and an odd one left over escapes it, so the run is doubled
+ * and one added; before any other bracket one `\[` becomes `[`, so one
+ * backslash is added.
+ *
+ * No bracket in the output can open a tag, whatever it is joined to. A bracket
+ * whose tag the text ends before finishing — `[link=x` — is escaped as a tag,
+ * because the next fragment's `]` would finish it; when what follows is instead
+ * the caller's own tag, a backslash run in front of it renders doubled. A
+ * trailing run is doubled for the same reason: `escape("C:\\")` spliced before
+ * `[/bold]` would otherwise escape the closing tag, so at the very end of a
+ * string it renders doubled. The grammar cannot tell those cases apart, and
+ * both choices fail visibly rather than let input open or escape a tag.
+ *
+ * Rich's `escape` escapes only a finished tag and doubles only a trailing run
+ * of one, so input can drop a backslash, escape the closing tag after it, or
+ * open a tag across a join. All three are departures on purpose.
  */
 export function escape(text) {
-    return text.replace(/\[/g, "\\[");
+    return text
+        .replace(ESCAPE_RE, (_, run, live) => live === undefined ? `${run}\\[` : `${run}${run}\\[`)
+        .replace(TRAILING_RUN_RE, "$&$&");
 }
 // --- render ---
-// Fast path: if no `[` in text, skip parsing entirely
-const HAS_TAG_RE = /\[/;
 // [LAW:one-source-of-truth] The authority for this grammar is `RE_TAGS` in
 // `rich/markup.py`, and this is deliberately its expression rather than a
 // re-derivation, so the two can be read side by side; `[^[]*?` is lazy against
@@ -155,19 +174,48 @@ const HAS_TAG_RE = /\[/;
 // every `Console.print` with no error, and it omitted `@` and the punctuation
 // the reference admits, so `[a+b]` stayed literal (rich-markup-sec).
 // `markup-grammar.golden.txt` pins both directions.
-// The leading alternative handles an escaped bracket: \[
-const TAG_RE = /(?:\\\[)|(\[[a-z#/@][^[]*?\])/g;
-function parseTags(markup) {
-    const tags = [];
-    const re = new RegExp(TAG_RE.source, TAG_RE.flags);
-    let match;
-    while ((match = re.exec(markup)) !== null) {
-        // Escaped bracket
-        if (match[0] === "\\[")
-            continue;
-        const captured = match[1];
-        if (!captured)
+//
+// The leading group is the run of backslashes in front of the bracket, which
+// `tokenize` halves as `_parse` does: each pair is one literal backslash, and a
+// leftover odd one escapes the tag. An alternative that consumed any `\[` as an
+// escape could not tell "escaped tag" from "literal backslash, then a live tag",
+// so `\\[red]hi[/red]` lost its opening tag and died on the close
+// (rich-markup-nm1).
+//
+// A run is only ever matched from its first backslash — the lookbehind — which
+// is where a leftmost match starts anyway. Without it, a long run that no
+// bracket follows is re-scanned from every backslash in it: quadratic in the
+// run, on exactly the untrusted text `escape` is for.
+const TAG_BODY = String.raw `[a-z#/@][^[]*?\]`;
+const RUN = String.raw `(?<!\\)(\\*)`;
+const TAG_RE = new RegExp(String.raw `${RUN}(\[${TAG_BODY})`, "g");
+/**
+ * Every bracket and the run in front of it; the empty second group is set when
+ * a tag starts there or could, once more text is joined after the end. It is an
+ * alternation rather than `(…)?` because a quantified group may not match empty.
+ */
+const ESCAPE_RE = new RegExp(String.raw `${RUN}\[(?:(?=${TAG_BODY}|(?:[a-z#/@][^[\]]*)?$)()|)`, "g");
+const TRAILING_RUN_RE = /(?<!\\)\\+$/;
+function tokenize(markup) {
+    const tokens = [];
+    let position = 0;
+    for (const match of markup.matchAll(TAG_RE)) {
+        const run = match[1];
+        const captured = match[2];
+        let start = match.index;
+        const end = start + match[0].length;
+        if (start > position)
+            tokens.push({ kind: "text", text: markup.slice(position, start), start: position });
+        position = end;
+        const literal = Math.floor(run.length / 2);
+        if (literal > 0) {
+            tokens.push({ kind: "text", text: "\\".repeat(literal), start });
+            start += literal * 2;
+        }
+        if (run.length % 2 === 1) {
+            tokens.push({ kind: "text", text: captured, start });
             continue;
+        }
         const inner = captured.slice(1, -1); // Remove [ ]
         const isClose = inner.startsWith("/");
         const stylePart = isClose ? inner.slice(1) : inner;
@@ -183,26 +231,49 @@ function parseTags(markup) {
         // it was an explicit close of the empty style rather than an implicit one.
         const isImplicitClose = isClose && styleName === "";
         const isClosing = isClose && !isImplicitClose;
-        tags.push({
+        tokens.push({
+            kind: "tag",
             fullMatch: captured,
             isClosing,
             isImplicitClose,
             styleName,
             parameters,
-            start: match.index,
-            end: match.index + match[0].length,
+            start,
+            end,
         });
     }
-    return tags;
+    if (position < markup.length)
+        tokens.push({ kind: "text", text: markup.slice(position), start: position });
+    return tokens;
 }
-function wholeString(markup) {
-    return { source: markup, base: 0, enclosing: [] };
+function isTag(token) {
+    return token.kind === "tag";
+}
+/**
+ * The tokens that begin in `[from, to)` of the source. `tokenize` emits them in
+ * source order, so this is two binary searches and a slice: a string of many
+ * plugin pairs costs what it holds, not pairs × tokens.
+ */
+function within(tokens, from, to) {
+    return tokens.slice(firstAtOrAfter(tokens, from), firstAtOrAfter(tokens, to));
+}
+function firstAtOrAfter(tokens, offset) {
+    let low = 0;
+    let high = tokens.length;
+    while (low < high) {
+        const mid = (low + high) >>> 1;
+        if (tokens[mid].start < offset)
+            low = mid + 1;
+        else
+            high = mid;
+    }
+    return low;
 }
 /**
  * Parses the built-in style dialect — `[bold red]text[/bold red]` — into a
  * `RichText` with styled spans. Module-private on purpose: `renderMarkup` is
- * this module's one crossing, and it delegates straight here the moment a
- * string carries no paired plugin tag.
+ * this module's one crossing, and it hands every slice here once its plugin
+ * pairs are resolved.
  *
  * [LAW:single-enforcer] Exporting this is what let a caller bind to the inner
  * layer, and two of them did — `console.ts` and `prompt.ts` imported it as
@@ -219,69 +290,69 @@ function wholeString(markup) {
  * function names; an empty registry puts it in the data, where the one
  * boundary admits both.
  */
-function render(markup, origin, baseStyle, options) {
-    // Fast path: no brackets at all
-    if (!HAS_TAG_RE.test(markup)) {
-        let text = markup;
-        if (options?.emoji !== false) {
-            text = emojiReplace(text);
-        }
-        const result = new RichText(text);
-        if (baseStyle)
-            result.stylize(baseStyle);
-        return result;
-    }
-    const tags = parseTags(markup);
+function render(parts, origin, baseStyle, options) {
     const doEmoji = options?.emoji !== false;
     // Build plain text and track spans
     let plainText = "";
     const spans = [];
+    const spliced = [];
     const openStack = [];
-    const unparsable = (reason, tag) => new MarkupSyntaxError(reason, origin.source, origin.base + tag.start, [
+    const unparsable = (reason, tag) => new MarkupSyntaxError(reason, origin.source, tag.start, [
         ...origin.enclosing,
         ...openStack.map((opened) => opened.tag),
     ]);
-    let lastEnd = 0;
-    for (const tag of tags) {
-        // Add text before this tag
-        const textBefore = markup.slice(lastEnd, tag.start);
-        const processed = unescapeBrackets(doEmoji ? emojiReplace(textBefore) : textBefore);
-        plainText += processed;
-        if (tag.isImplicitClose) {
-            // [/] — close the most recent open tag
-            if (openStack.length === 0) {
-                // [/] 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)));
+    // [LAW:dataflow-not-control-flow] One stack across every part, so a style
+    // tag opened before a plugin pair is still open after it and its span covers
+    // the handler's output like any other run of text (rich-markup-cg6).
+    for (const part of parts) {
+        if (part.kind === "rendered") {
+            spliced.push({ at: plainText.length, text: part.text });
+            plainText += part.text.plain;
+            continue;
         }
-        else if (tag.isClosing) {
-            // [/style] — find and close matching open tag
-            const idx = findLastOpen(openStack, tag.styleName);
-            if (idx === -1) {
-                throw unparsable(`Closing tag ${tag.fullMatch} doesn't match any open tag`, tag);
+        for (const token of part.tokens) {
+            if (!isTag(token)) {
+                // A `\[` in front of a bracket no tag starts at is unescaped here, per
+                // text token, as the reference does; a tag's own escape was settled by
+                // `tokenize` against its backslash run.
+                const text = token.text.replace(/\\\[/g, "[");
+                // Text reaches `plainText` as `RichText` will hold it, so every offset
+                // counted along the way — a span, a splice point — indexes the text it
+                // lands on. Stripped only by the constructor, a control character
+                // shifted every style after it one cell right.
+                plainText += stripControlChars(doEmoji ? emojiReplace(text) : text);
+                continue;
+            }
+            const tag = token;
+            if (tag.isImplicitClose) {
+                // [/] — close the most recent open tag
+                if (openStack.length === 0) {
+                    throw unparsable(`Closing tag ${tag.fullMatch} has no open tag to close`, tag);
+                }
+                const opened = openStack.pop();
+                spans.push(new Span(opened.textStart, plainText.length, openTagStyle(opened)));
+            }
+            else if (tag.isClosing) {
+                // [/style] — find and close matching open tag
+                const idx = findLastOpen(openStack, tag.styleName);
+                if (idx === -1) {
+                    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)));
+                openStack.splice(idx, 1);
+            }
+            else {
+                // Opening tag
+                openStack.push({
+                    tag: tag.fullMatch,
+                    styleName: tag.styleName,
+                    parameters: tag.parameters,
+                    textStart: plainText.length,
+                });
             }
-            const opened = openStack[idx];
-            spans.push(new Span(opened.textStart, plainText.length, openTagStyle(opened)));
-            openStack.splice(idx, 1);
-        }
-        else {
-            // Opening tag
-            openStack.push({
-                tag: tag.fullMatch,
-                styleName: tag.styleName,
-                parameters: tag.parameters,
-                textStart: plainText.length,
-            });
         }
-        lastEnd = tag.end;
     }
-    // Add remaining text after last tag
-    const trailing = markup.slice(lastEnd);
-    const processedTrailing = unescapeBrackets(doEmoji ? emojiReplace(trailing) : trailing);
-    plainText += processedTrailing;
     // Auto-close what is still open, innermost first. The reference pops its
     // stack here (`while style_stack: start, tag = style_stack.pop()`), and
     // popping is what keeps every span in this list in the order its tag closed
@@ -322,6 +393,16 @@ function render(markup, origin, baseStyle, options) {
             result.stylize(style, span.start, span.end);
         }
     }
+    // A handler's own styles go down last — its base style, then its spans.
+    // Every style span that reaches into a handler's output encloses all of it —
+    // no tag of this walk sits inside a plugin pair — so each of these is the
+    // inner span, and inner repaints outer exactly as the sort above has it for
+    // tags.
+    for (const { at, text } of spliced) {
+        result.stylize(text.style, at, at + text.length);
+        for (const span of text.spans)
+            result.stylize(span.style, at + span.start, at + span.end);
+    }
     return result;
 }
 /**
@@ -339,19 +420,29 @@ function openTagStyle(opened) {
         ? `${opened.styleName} ${opened.parameters}`
         : opened.styleName;
 }
-function findLastOpen(stack, name) {
+/**
+ * Whether `[/name]` closes `opened`.
+ *
+ * [LAW:one-source-of-truth] Two walks ask this: the built-in parser closing a
+ * style, and the plugin pass keeping the same stack so it knows what `[/]`
+ * refers to. If they disagreed on which open tag `[/red on blue]` takes off
+ * the stack, they would disagree about what the next `[/]` closes.
+ */
+function closesByName(opened, name) {
     // Handle "on" in style names for closing: [/red on blue] should match [red on blue]
     const normalized = name.trim();
-    for (let i = stack.length - 1; i >= 0; i--) {
-        const entry = stack[i];
-        if (openTagStyle(entry) === normalized || entry.styleName === normalized)
+    return openTagStyle(opened) === normalized || opened.styleName === normalized;
+}
+function findLastOpen(stack, name) {
+    return findLastIndex(stack, (entry) => closesByName(entry, name));
+}
+function findLastIndex(items, match) {
+    for (let i = items.length - 1; i >= 0; i--) {
+        if (match(items[i]))
             return i;
     }
     return -1;
 }
-function unescapeBrackets(text) {
-    return text.replace(/\\\[/g, "[");
-}
 // [LAW:one-source-of-truth] The one answer to "what is a legal plugin tag
 // name?". Both sites that need it are derived from this fragment rather than
 // each carrying its own scanner: `register` anchors it to reject a name markup
@@ -483,124 +574,145 @@ function parsePluginAttrs(after) {
 /**
  * Plugin-aware markup render. Always returns a `RichText`. Built-in style
  * tags become spans; registered plugin tags are resolved by their handler,
- * whose returned `RichText` is appended (text + spans) into the output. The
- * recursion is over markup *slices* — between top-level plugin tag pairs and
- * inside each pair — and every recursion node returns a `RichText`, so the
- * append path is uniform.
+ * whose returned `RichText` stands in the output where its pair stood, under
+ * any style tag that encloses the pair. The recursion is into the inner slice
+ * of each plugin pair, and every recursion node returns a `RichText`.
  */
 export function renderMarkup(markup, options) {
-    return renderSlice(markup, wholeString(markup), options);
+    return renderSlice(tokenize(markup), { source: markup, enclosing: [] }, options);
 }
-function renderSlice(markup, origin, options) {
+function renderSlice(tokens, 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, 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, origin);
-    if (tagPairs.size === 0) {
-        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
-    // hand their inner slice (recursively) to a handler; both produce RichText,
-    // both get appended into one accumulator.
-    const out = new RichText("");
+    const { annotated, topLevel: tagPairs } = pairPluginTags(tokens.filter(isTag), registry, origin);
+    // [LAW:one-type-per-behavior] Each top-level plugin pair is resolved by its
+    // handler, and what it returns takes the pair's place in one built-in walk
+    // over the whole slice. Rendering the text between pairs as separate parses
+    // is what closed every style tag at a plugin boundary (rich-markup-cg6).
+    const parts = [];
     let cursor = 0;
     for (const [openIdx, closeIdx] of tagPairs) {
         const open = annotated[openIdx];
         const close = annotated[closeIdx];
-        if (open.start > cursor) {
-            out.append(render(markup.slice(cursor, open.start), offsetBy(origin, cursor), baseStyle, { emoji: doEmoji }));
-        }
-        const innerRaw = markup.slice(open.end, close.start);
-        const innerRichText = renderSlice(innerRaw, { ...offsetBy(origin, open.end), enclosing: [...origin.enclosing, open.fullMatch] }, options);
+        parts.push({ kind: "markup", tokens: within(tokens, cursor, open.start) });
+        const innerRaw = origin.source.slice(open.end, close.start);
+        // The base style is painted once, under the whole output, by the top of
+        // this recursion. Painted into `children` as well, it came back spliced in
+        // over every tag enclosing the pair.
+        const innerRichText = renderSlice(within(tokens, open.end, close.start), { ...origin, enclosing: [...origin.enclosing, open.fullMatch] }, { ...options, baseStyle: undefined });
         const handler = registry.get(open.pluginName);
-        out.append(handler({ attrs: open.attrs, children: innerRichText, raw: innerRaw }));
+        parts.push({ kind: "rendered", text: handler({ attrs: open.attrs, children: innerRichText, raw: innerRaw }) });
         cursor = close.end;
     }
-    if (cursor < markup.length) {
-        out.append(render(markup.slice(cursor), offsetBy(origin, cursor), baseStyle, { emoji: doEmoji }));
-    }
-    if (baseStyle)
-        out.stylize(baseStyle);
-    return out;
-}
-/** The origin of a sub-slice starting `offset` into the slice `origin` describes. */
-function offsetBy(origin, offset) {
-    return { ...origin, base: origin.base + offset };
+    parts.push({ kind: "markup", tokens: within(tokens, cursor, Infinity) });
+    return render(parts, origin, options?.baseStyle, { emoji: options?.emoji !== false });
 }
 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.
+    // recursive `renderSlice` call on the inner slice.
     const annotated = tags.map((t) => annotatePluginTag(t, registry));
+    // [LAW:one-source-of-truth] `[/]` closes the most recent open tag of *any*
+    // kind, so this walk keeps the one stack the built-in dialect keeps, style
+    // tags on it too; an implicit close pairs a plugin tag exactly when it is on
+    // top. A stack of plugin tags alone cannot say what `[/]` refers to, which is
+    // why `[shout]one[/]` used to leave its handler unfired (rich-markup-gfr).
+    //
+    // A pair's end closes everything opened inside it, because that is where the
+    // recursion's slice ends and the built-in walk closes what is left open. The
+    // stack drops them there too, so a later `[/]` means here what it means to
+    // the walk that renders it.
     const stack = [];
     const pairs = new Map();
+    // Each opener's closing tag, whichever tag closed it — its own or a pair's end.
+    const closedAt = new Map();
+    // Each tag a pair's end closed, with that pair's opening tag.
+    const closedByPair = new Map();
+    // Style tags closed inside a plugin tag they opened outside of, keyed by that
+    // plugin tag — a crossing only once the plugin tag turns out to pair.
+    const crossedInto = new Map();
+    const isOpener = (t) => !t.isClosing && !t.isImplicitClose;
+    const isPlugin = (idx) => annotated[idx].pluginName !== undefined;
+    const closes = (close) => (openIdx) => {
+        const open = annotated[openIdx];
+        if (close.isImplicitClose)
+            return true;
+        return close.pluginName !== undefined
+            ? open.pluginName === close.pluginName
+            : open.pluginName === undefined && closesByName(open, close.styleName);
+    };
+    // The tags open at a tag's position, as the built-in walk would report them.
+    const openAt = (caret) => annotated.flatMap((t, k) => (k < caret && isOpener(t) && (closedAt.get(k) ?? Infinity) >= caret ? [t.fullMatch] : []));
+    const crossing = (styleOpen, close, pairOpen) => new MarkupSyntaxError(`Closing tag ${annotated[close].fullMatch} closes ${annotated[styleOpen].fullMatch} ` +
+        `across the boundary of plugin tag ${annotated[pairOpen].fullMatch}: ` +
+        `a style tag must open and close on the same side of a plugin pair, ` +
+        `because the handler replaces the text inside it.`, origin.source, annotated[close].start, [...origin.enclosing, ...openAt(close)]);
     for (let i = 0; i < annotated.length; i++) {
         const t = annotated[i];
-        if (!t.pluginName)
-            continue;
-        if (t.isImplicitClose)
+        if (isOpener(t)) {
+            stack.push(i);
             continue;
-        if (t.isClosing) {
-            // Find matching open in stack.
-            for (let j = stack.length - 1; j >= 0; j--) {
-                const openIdx = stack[j];
-                if (annotated[openIdx].pluginName === t.pluginName) {
-                    pairs.set(openIdx, i);
-                    stack.splice(j, 1);
-                    break;
-                }
+        }
+        const j = findLastIndex(stack, closes(t));
+        if (j === -1) {
+            // [LAW:no-silent-failure] A closer that matches nothing reaches for the
+            // last tag before it that it could name, `[/]` and `[/name]` alike. If a
+            // pair's end closed that tag, the closer reaches across the pair, and
+            // saying so beats the built-in parser's "doesn't match any open tag";
+            // otherwise the built-in parser rejects it, with the location it reports.
+            let target = i - 1;
+            while (target >= 0 && !(isOpener(annotated[target]) && closes(t)(target)))
+                target--;
+            const pairOpen = closedByPair.get(target);
+            if (pairOpen === undefined)
+                continue;
+            if (t.pluginName === undefined)
+                throw crossing(target, i, pairOpen);
+            // Overlap is unrepresentable rather than unimplemented: a handler receives
+            // `children` as one contiguous slice, so a region straddling another
+            // pair's closing boundary has nothing to hand it. A style span may cross
+            // another style span because it annotates; a plugin pair may not because
+            // it replaces. The caret goes where nesting broke: the outer pair's end.
+            const inner = annotated[target];
+            const outer = annotated[pairOpen];
+            const caret = closedAt.get(pairOpen);
+            throw new MarkupSyntaxError(`Plugin tag [${inner.pluginName}] overlaps [${outer.pluginName}]: plugin tags must nest, ` +
+                `because a handler receives one contiguous slice. ` +
+                `Close [/${inner.pluginName}] before [/${outer.pluginName}].`, origin.source, annotated[caret].start, [...origin.enclosing, ...openAt(caret)]);
+        }
+        const openIdx = stack[j];
+        if (!isPlugin(openIdx)) {
+            for (const k of stack.slice(j + 1)) {
+                if (isPlugin(k) && !crossedInto.has(k))
+                    crossedInto.set(k, { styleOpen: openIdx, close: i });
             }
+            stack.splice(j, 1);
+            closedAt.set(openIdx, i);
+            continue;
         }
-        else {
-            stack.push(i);
+        const crossed = crossedInto.get(openIdx);
+        if (crossed !== undefined)
+            throw crossing(crossed.styleOpen, crossed.close, openIdx);
+        for (const k of stack.splice(j)) {
+            closedAt.set(k, i);
+            if (k !== openIdx)
+                closedByPair.set(k, openIdx);
         }
+        pairs.set(openIdx, i);
     }
-    // Filter pairs to top-level only. A pair that opens inside the current one is
-    // either contained — re-discovered when the recursion renders the outer
-    // pair's inner slice — or overlapping, and only its *closing* position tells
-    // the two apart. Testing the open position alone conflated them and dropped
-    // the overlapping pair, which orphaned its closing tag into the trailing
-    // slice, where the built-in parser blamed the wrong tag for the wrong reason.
+    // Pairs nest, so one is top-level exactly when it opens after the last
+    // top-level pair closed. Decided after the walk and not at each close: a
+    // plugin tag still on the stack there may never pair, and then encloses
+    // nothing.
     const topLevel = new Map();
-    let outerEnd = -1;
-    let outerOpenIdx = -1;
-    const sortedOpens = [...pairs.keys()].sort((a, b) => a - b);
-    for (const openIdx of sortedOpens) {
-        const closeIdx = pairs.get(openIdx);
-        if (annotated[openIdx].start < outerEnd) {
-            // [LAW:no-silent-failure] Overlap is unrepresentable here rather than
-            // unimplemented: a handler receives `children` as one contiguous slice,
-            // so a region straddling another pair's closing boundary has nothing to
-            // 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];
-                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.pluginName}] before [/${outer.pluginName}].`, origin.source, origin.base + caret, [...origin.enclosing, ...openAtCaret]);
-            }
+    let outerClose = -1;
+    for (const openIdx of [...pairs.keys()].sort((a, b) => a - b)) {
+        if (openIdx < outerClose)
             continue;
-        }
-        topLevel.set(openIdx, closeIdx);
-        outerOpenIdx = openIdx;
-        outerEnd = annotated[closeIdx].end;
+        outerClose = pairs.get(openIdx);
+        topLevel.set(openIdx, outerClose);
     }
     return { annotated, topLevel };
 }

package/dist/core/measure.d.ts

@@ -1,7 +1,7 @@
 /**
  * Measurement — min/max cell width calculation for renderables.
  */
-import type { Measurable, RenderOptions } from "./protocol.js";
+import { type Measurable, type RenderOptions } from "./protocol.js";
 export declare class Measurement {
     readonly minimum: number;
     readonly maximum: number;

package/dist/core/measure.js

@@ -1,6 +1,7 @@
 /**
  * Measurement — min/max cell width calculation for renderables.
  */
+import { measuring } from "./protocol.js";
 export class Measurement {
     minimum;
     maximum;
@@ -43,7 +44,7 @@ export class Measurement {
     static get(options, measurable) {
         if (options.maxWidth < 1)
             return new Measurement(0, 0);
-        const { minimum, maximum } = measurable.measure(options);
+        const { minimum, maximum } = measurable.measure(measuring(options));
         return new Measurement(minimum, Math.min(maximum, options.maxWidth)).normalize();
     }
 }

package/dist/core/place.d.ts

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