@promptctl/rich-js 0.18.0 → 0.19.0

package/dist/core/text.js

@@ -0,0 +1,1097 @@
+/**
+ * RichText — styled text with spans. The primary text type for the library.
+ */
+import { cellLen, cellCount, cellFit, cellFitEnd, asCellCol, expandTabs, parseTabSize } from "./cells.js";
+import { divideLine, wordWidths } from "./wrap.js";
+import { Segment } from "./segment.js";
+import { Style, NULL_STYLE, StyleSyntaxError } from "./style.js";
+import { stripOscTerminators } from "./osc8.js";
+import { drawable, getStyle, withBoundedWidth } from "./protocol.js";
+// Every C0 control and DEL except \t and \n. Rich's `Text` strips only
+// `STRIP_CONTROL_CODES` (BEL, BS, VT, FF, CR); the rest of the set is the
+// port's extension, so no C0 byte of content can start an escape sequence or
+// move the cursor on the wire. C1 controls (U+0080–U+009F) pass, as in Rich.
+// [LAW:single-enforcer] Single place where control chars are sanitized
+const CONTROL_CHARS_RE = /[\x00-\x08\x0B-\x1F\x7F]/g;
+export function stripControlChars(text) {
+    return text.replace(CONTROL_CHARS_RE, "");
+}
+const TRAILING_WHITESPACE_RE = /\s+$/;
+/**
+ * The plain text of one line of segments, in the coordinate system
+ * `divideLine` and `Segment.divide` share: cell offsets into the styled line
+ * are cell offsets into this string. [LAW:one-source-of-truth] for that
+ * correspondence — the offsets are found in this text and applied to the
+ * segments it came from.
+ */
+function plainOf(line) {
+    return line.map((segment) => segment.text).join("");
+}
+/**
+ * The cells of trailing whitespace on a wrapped line.
+ *
+ * A wrap cuts before a word, so the line it closes ends with the whitespace
+ * that followed *its* last word — padding the break created, not content the
+ * author wrote. Measuring it is what lets the overflow method tell "this line
+ * was cut" from "this line ends in spaces" and stamp an ellipsis only on the
+ * first, and what keeps a centred line from drifting half a space off true.
+ *
+ * Asked of the line's text rather than walked back through its segments,
+ * because where a line ends is a fact about the characters and not about how
+ * they were split. Walking the segments made it a fact about both: it read a
+ * segment with no trailing whitespace as content and stopped there, which an
+ * empty segment also looks like — and a crop leaves one behind. A styled line
+ * whose last cells were cropped therefore reported no hanging whitespace at
+ * all and was centred as though it were content to the edge, so a span landing
+ * anywhere in a wrap's whitespace un-centred the line it closed.
+ */
+function hangingWhitespace(line) {
+    return cellLen(TRAILING_WHITESPACE_RE.exec(plainOf(line))?.[0] ?? "");
+}
+// [LAW:single-enforcer] RichText is the data-model trust boundary for link
+// URLs: a `Style` is sanitized as it enters (`admitStyle`), and the `Style` a
+// stored string resolves to is sanitized as it leaves for a render
+// (`resolveStyle`). Wire-byte safety is enforced separately by `osc8Open`
+// (core/osc8.ts), which every link producer calls and which applies the same
+// `stripOscTerminators`.
+function sanitizeStyleLink(style) {
+    const link = style.link;
+    if (!link)
+        return style;
+    const cleaned = stripOscTerminators(link);
+    if (cleaned === link)
+        return style;
+    return style.withLink(cleaned);
+}
+/**
+ * A style as a RichText keeps it: as given. A name stays a name because what
+ * it stands for depends on the theme of the render that draws it, which no
+ * RichText knows when the name arrives — the reference stores span styles the
+ * same way. A string holds no link until it is parsed, so only a `Style` —
+ * alone or laid over a name — has one to sanitize here.
+ *
+ * [LAW:single-enforcer] Nor does a RichText keep an anchor (`./anchor.ts`). It
+ * lays its text out anew, so a stamp naming where a cell sat in the output it
+ * came from would name the wrong cell once it wraps, slices or overlaps; the
+ * owner that renders the RichText is the one that stamps its cells.
+ */
+function admitStyle(style) {
+    if (typeof style === "string")
+        return style;
+    if (style instanceof Style)
+        return admitDefined(style);
+    return { under: style.under, over: admitDefined(style.over) };
+}
+function admitDefined(style) {
+    return sanitizeStyleLink(style.anchor ? style.withAnchor(undefined) : style);
+}
+/** A style that adds nothing: the empty definition, or a null `Style`. */
+function isEmptyStyle(style) {
+    return style instanceof Style ? style.isNull : style === "";
+}
+/**
+ * The style a stored `TextStyle` stands for in this render.
+ *
+ * A parsed string can carry a link, so the result is sanitized on the way out
+ * as well.
+ */
+export function resolveStyle(options, style) {
+    const resolved = style instanceof Style ? style
+        : typeof style === "string" ? resolveDefinition(options, style)
+            : resolveDefinition(options, style.under).add(style.over);
+    return sanitizeStyleLink(resolved);
+}
+/**
+ * [LAW:single-enforcer] Styling is non-critical — an unrecognized style name
+ * (typo, missing theme key, bad concatenation) degrades to unstyled rather
+ * than crashing, as the reference's `Text.render` resolves with a null
+ * default. Absorb only StyleSyntaxError here; other errors are genuine bugs
+ * and must surface. The render's `onStyleError` hears about each one first,
+ * and a handler that throws turns the degrade into a failure.
+ */
+function resolveDefinition(options, style) {
+    try {
+        return getStyle(options, style);
+    }
+    catch (err) {
+        if (!(err instanceof StyleSyntaxError))
+            throw err;
+        options.onStyleError?.(err, style);
+        return NULL_STYLE;
+    }
+}
+// --- Span ---
+export class Span {
+    start;
+    end;
+    style;
+    constructor(start, end, style) {
+        this.start = start;
+        this.end = end;
+        this.style = style;
+    }
+    get hasLength() {
+        return this.end > this.start;
+    }
+    toString() {
+        return `Span(${this.start}, ${this.end})`;
+    }
+    split(offset) {
+        if (offset <= this.start || offset >= this.end)
+            return [this, undefined];
+        return [
+            new Span(this.start, offset, this.style),
+            new Span(offset, this.end, this.style),
+        ];
+    }
+    move(delta) {
+        return new Span(this.start + delta, this.end + delta, this.style);
+    }
+    rightCrop(offset) {
+        if (offset >= this.end)
+            return this;
+        return new Span(this.start, Math.min(this.end, offset), this.style);
+    }
+    extend(count) {
+        return new Span(this.start, this.end + count, this.style);
+    }
+}
+export class RichText {
+    _text;
+    _spans;
+    _style;
+    _justify;
+    _overflow;
+    _end;
+    _tabSize;
+    _noWrap;
+    constructor(text, options) {
+        this._text = text ? stripControlChars(text) : "";
+        this._spans = [];
+        // [LAW:single-enforcer] `admitStyle` is the boundary that sanitizes
+        // any link URL crossing into a RichText; downstream trusts the invariant.
+        this._style = admitStyle(options?.style ?? NULL_STYLE);
+        this._justify = options?.justify;
+        this._overflow = options?.overflow;
+        this._end = options?.end ?? "\n";
+        this._tabSize = parseTabSize(options?.tabSize ?? 8);
+        this._noWrap = options?.noWrap ?? false;
+    }
+    // --- Properties ---
+    get plain() {
+        return this._text;
+    }
+    set plain(value) {
+        const sanitized = stripControlChars(value);
+        this._text = sanitized;
+        // Trim spans that extend beyond new length
+        const len = sanitized.length;
+        this._spans = this._spans
+            .map((s) => (s.end > len ? new Span(s.start, Math.min(s.end, len), s.style) : s))
+            .filter((s) => s.start < len);
+    }
+    get length() {
+        return this._text.length;
+    }
+    /**
+     * The cells of the plain text with each tab widened to its stop counted from
+     * this text's own column 0, as `render` widens it — so it is the drawn width
+     * of a one-line text set at a stop. A deliberate departure from Rich, whose
+     * `Text.cell_len` counts a tab as no cells, so everything sized by it — a
+     * truncation, an alignment, a header's remaining width — decided on a width
+     * no render draws.
+     */
+    get cellLength() {
+        return cellLen(expandTabs(this._text, this._tabSize).text);
+    }
+    get hasContent() {
+        return this._text.length > 0;
+    }
+    /** The base style every span layers over, resolved at render unless it is a `Style`. */
+    get style() {
+        return this._style;
+    }
+    set style(value) {
+        this._style = admitStyle(value);
+    }
+    get justify() {
+        return this._justify;
+    }
+    set justify(value) {
+        this._justify = value;
+    }
+    get overflow() {
+        return this._overflow;
+    }
+    set overflow(value) {
+        this._overflow = value;
+    }
+    get end() {
+        return this._end;
+    }
+    set end(value) {
+        this._end = value;
+    }
+    get noWrap() {
+        return this._noWrap;
+    }
+    set noWrap(value) {
+        this._noWrap = value;
+    }
+    get spans() {
+        return this._spans;
+    }
+    /**
+     * This text's own style, spans aside, as the render drawing it resolves it.
+     * A name the render's theme does not define resolves to no style, because
+     * text forgives a missing name.
+     */
+    resolvedStyle(options) {
+        return resolveStyle(options, this._style);
+    }
+    /**
+     * The style of the cell-column at the named edge — base style merged with
+     * any spans covering the leftmost (side="left") or rightmost (side="right")
+     * character.
+     *
+     * [LAW:locality-or-seam] Used by `Joiner`s to paint the transition between
+     * adjacent `Strip` items. Joiners only ever need the column adjacent to
+     * them, so the cell type exposes that column rather than constraining its
+     * interior to be uniform. For RichText with uniform styling, both edges
+     * return the same style; for RichText with edge variation, each edge
+     * accurately reports the column the joiner actually meets.
+     *
+     * Position is by character index (not cell column). For wide-character
+     * text, the last character occupies the rightmost cell column — the bg
+     * of that character covers both columns, so character-index lookup gives
+     * the correct edge color.
+     *
+     * Takes the render's options because the edge is reported as it will be
+     * drawn, and a style name draws as whatever the render's theme says.
+     */
+    edgeStyle(side, options) {
+        const base = this.resolvedStyle(options);
+        if (this._text.length === 0)
+            return base;
+        const pos = side === "left" ? 0 : this._text.length - 1;
+        let result = base;
+        for (const span of this._spans) {
+            if (span.start <= pos && pos < span.end) {
+                result = result.add(resolveStyle(options, span.style));
+            }
+        }
+        return result;
+    }
+    // --- Content Operations ---
+    append(content, style) {
+        if (content instanceof RichText) {
+            if (style !== undefined) {
+                throw new Error("Style argument must not be provided when appending RichText");
+            }
+            const offset = this._text.length;
+            this._text += content._text;
+            // Its base style becomes a span under its own spans, as the reference's
+            // `append` does, so appended text looks as it did alone.
+            this._addSpan(offset, this._text.length, content._style);
+            for (const span of content._spans) {
+                this._spans.push(span.move(offset));
+            }
+            return this;
+        }
+        const sanitized = stripControlChars(content);
+        const start = this._text.length;
+        this._text += sanitized;
+        this._addSpan(start, this._text.length, style ?? "");
+        return this;
+    }
+    contains(needle) {
+        const searchText = needle instanceof RichText ? needle._text : needle;
+        return this._text.includes(searchText);
+    }
+    at(index) {
+        const resolved = index < 0 ? this._text.length + index : index;
+        const char = this._text[resolved];
+        if (char === undefined)
+            return new RichText("");
+        return this.slice(resolved, resolved + 1);
+    }
+    slice(start, end) {
+        const text = this._text;
+        const len = text.length;
+        const s = start ?? 0;
+        const e = end ?? len;
+        const resolvedStart = s < 0 ? Math.max(0, len + s) : Math.min(s, len);
+        const resolvedEnd = e < 0 ? Math.max(0, len + e) : Math.min(e, len);
+        if (resolvedStart >= resolvedEnd) {
+            return this.blankCopy();
+        }
+        const slicedText = text.slice(resolvedStart, resolvedEnd);
+        const result = this.blankCopy(slicedText);
+        for (const span of this._spans) {
+            const spanStart = Math.max(span.start, resolvedStart) - resolvedStart;
+            const spanEnd = Math.min(span.end, resolvedEnd) - resolvedStart;
+            if (spanStart < spanEnd) {
+                result._spans.push(new Span(spanStart, spanEnd, span.style));
+            }
+        }
+        return result;
+    }
+    // --- Styling Operations ---
+    /**
+     * The one way a span enters this text. [LAW:single-enforcer] An empty style
+     * adds nothing, as the reference's `if style:` has it, and every other style
+     * is admitted as given.
+     */
+    _addSpan(start, end, style) {
+        const admitted = admitStyle(style);
+        if (isEmptyStyle(admitted))
+            return;
+        this._spans.push(new Span(start, end, admitted));
+    }
+    stylize(style, start, end) {
+        const len = this._text.length;
+        const s = start !== undefined ? (start < 0 ? len + start : start) : 0;
+        const e = end !== undefined ? (end < 0 ? len + end : end) : len;
+        if (s >= e || s >= len || e <= 0)
+            return this;
+        const clampedStart = Math.max(0, s);
+        const clampedEnd = Math.min(len, e);
+        this._addSpan(clampedStart, clampedEnd, style);
+        return this;
+    }
+    highlightRegex(pattern, style) {
+        const text = this._text;
+        let count = 0;
+        // Ensure global flag
+        const flags = pattern.flags.includes("g") ? pattern.flags : pattern.flags + "g";
+        const re = new RegExp(pattern.source, flags);
+        let match;
+        while ((match = re.exec(text)) !== null) {
+            if (match[0].length === 0) {
+                re.lastIndex++;
+                continue;
+            }
+            // Named capture groups are applied as style names
+            if (match.groups) {
+                let searchFrom = 0;
+                for (const [groupName, groupValue] of Object.entries(match.groups)) {
+                    if (groupValue !== undefined) {
+                        const posInMatch = match[0].indexOf(groupValue, searchFrom);
+                        if (posInMatch >= 0) {
+                            const groupStart = match.index + posInMatch;
+                            this._addSpan(groupStart, groupStart + groupValue.length, groupName);
+                            searchFrom = posInMatch + groupValue.length;
+                        }
+                    }
+                }
+                count++;
+                continue;
+            }
+            this._addSpan(match.index, match.index + match[0].length, style ?? "");
+            count++;
+        }
+        return count;
+    }
+    highlightWords(words, style, options) {
+        const caseSensitive = options?.caseSensitive !== false;
+        let count = 0;
+        for (const word of words) {
+            if (word.length === 0)
+                continue;
+            const escaped = word.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+            const flags = caseSensitive ? "g" : "gi";
+            const re = new RegExp(`\\b${escaped}\\b`, flags);
+            let match;
+            while ((match = re.exec(this._text)) !== null) {
+                this._addSpan(match.index, match.index + match[0].length, style);
+                count++;
+            }
+        }
+        return count;
+    }
+    // --- Copy Operations ---
+    copy() {
+        const result = new RichText(this._text, {
+            style: this._style,
+            justify: this._justify,
+            overflow: this._overflow,
+            end: this._end,
+            tabSize: this._tabSize,
+            noWrap: this._noWrap,
+        });
+        result._spans = this._spans.slice();
+        return result;
+    }
+    blankCopy(text) {
+        return new RichText(text ?? "", {
+            style: this._style,
+            justify: this._justify,
+            overflow: this._overflow,
+            end: this._end,
+            tabSize: this._tabSize,
+            noWrap: this._noWrap,
+        });
+    }
+    // --- Splitting ---
+    split(separator) {
+        const sep = separator ?? "\n";
+        const text = this._text;
+        const parts = [];
+        let start = 0;
+        while (true) {
+            const idx = text.indexOf(sep, start);
+            if (idx === -1) {
+                parts.push(this.slice(start));
+                break;
+            }
+            parts.push(this.slice(start, idx));
+            start = idx + sep.length;
+        }
+        return parts;
+    }
+    divide(offsets) {
+        if (offsets.length === 0)
+            return [this.copy()];
+        const parts = [];
+        let prev = 0;
+        for (const offset of offsets) {
+            parts.push(this.slice(prev, offset));
+            prev = offset;
+        }
+        parts.push(this.slice(prev));
+        return parts;
+    }
+    // --- Whitespace Operations ---
+    rstrip() {
+        const trimmed = this._text.replace(/\s+$/, "");
+        if (trimmed.length < this._text.length) {
+            this.plain = trimmed;
+        }
+        return this;
+    }
+    pad(count, char) {
+        const c = char ?? " ";
+        const padding = c.repeat(count);
+        // Shift all spans to the right
+        this._spans = this._spans.map((s) => s.move(count));
+        this._text = padding + this._text + padding;
+        return this;
+    }
+    /**
+     * Each tab widened to the next tab stop, in place, as Rich's
+     * `Text.expand_tabs` widens it: spans move with the characters they style, so
+     * the text measures what it will draw.
+     */
+    expandTabs() {
+        const expanded = expandTabs(this._text, this._tabSize);
+        this._spans = this._spans.map((s) => new Span(expanded.offsetOf(s.start), expanded.offsetOf(s.end), s.style));
+        this._text = expanded.text;
+        return this;
+    }
+    padLeft(count, char) {
+        const c = char ?? " ";
+        this._spans = this._spans.map((s) => s.move(count));
+        this._text = c.repeat(count) + this._text;
+        return this;
+    }
+    padRight(count, char) {
+        const c = char ?? " ";
+        this._text += c.repeat(count);
+        return this;
+    }
+    setLength(length) {
+        if (this._text.length < length) {
+            this._text += " ".repeat(length - this._text.length);
+        }
+        else if (this._text.length > length) {
+            this.plain = this._text.slice(0, length);
+        }
+        return this;
+    }
+    extendStyle(count) {
+        const oldLen = this._text.length;
+        this._text += " ".repeat(count);
+        // Extend existing spans to cover new spaces
+        this._spans = this._spans.map((s) => s.end === oldLen ? s.extend(count) : s);
+        return this;
+    }
+    // --- Truncation ---
+    /**
+     * Truncate to a fixed cell-column width, in one of three modes.
+     *
+     * - `mode: "right"` (default) \u2014 drop characters from the right; append
+     *   `marker` (if any) at the cut.
+     * - `mode: "left"` \u2014 drop characters from the left; prepend `marker` at
+     *   the cut.
+     * - `mode: "middle"` \u2014 keep equal halves from both ends; place `marker`
+     *   in the middle.
+     *
+     * Marker default is `"\u2026"`. Pass `marker: ""` for raw cropping without an
+     * indicator glyph. A marker wider than `width` is itself cut to the glyphs
+     * that fit, and the text takes whatever cells that leaves — all of them, when
+     * not one glyph of the marker fits — so the result is never wider than asked.
+     * Every cut, marker and text alike, falls between grapheme clusters.
+     *
+     * Spans are preserved through the cut: characters that survive keep their
+     * styling; the marker (if any) is inserted as plain text with no span.
+     * Use `stylize(...)` on the result to color the marker if needed.
+     *
+     * Text that fits comes back untouched. Text that is cut has its tabs widened
+     * to their stops first, as `expandTabs` widens them, so the width cut to is
+     * the width drawn.
+     *
+     * [LAW:dataflow-not-control-flow] mode/marker/width all flow as values;
+     * the walk is the same shape regardless. No "if truncated then rebuild"
+     * branch \u2014 the unchanged path just early-returns when content fits.
+     */
+    truncate(width, options) {
+        if (this.cellLength <= width)
+            return this;
+        // [LAW:one-source-of-truth] Cut what is drawn: once a tab is spaces, a cell
+        // of the plain text is a cell of the output, so the cut lands where it looks.
+        this.expandTabs();
+        const mode = options?.mode ?? "right";
+        // [LAW:dataflow-not-control-flow] the marker is fitted to the width as a
+        // value, so width 0 and a marker wider than the width run the same walk
+        // as every other call: what is drawn plus what is kept is `cells` wide.
+        const cells = cellCount(width);
+        const marker = cellFit(options?.marker ?? "\u2026", cells);
+        const budget = asCellCol(cells - cellLen(marker));
+        if (mode === "right") {
+            this._cropRightTo(budget);
+            if (marker)
+                this._text += marker;
+            return this;
+        }
+        if (mode === "left") {
+            this._cropLeftTo(budget);
+            if (marker) {
+                this._spans = this._spans.map((s) => s.move(marker.length));
+                this._text = marker + this._text;
+            }
+            return this;
+        }
+        // middle
+        const leftBudget = asCellCol(Math.floor(budget / 2));
+        const rightBudget = asCellCol(budget - leftBudget);
+        // Find the char-index ranges to keep from each side.
+        const leftEndCharIdx = cellFit(this._text, leftBudget).length;
+        const rightStartCharIdx = this._text.length - cellFitEnd(this._text, rightBudget).length;
+        const leftText = this._text.slice(0, leftEndCharIdx);
+        const rightText = this._text.slice(rightStartCharIdx);
+        const droppedStart = leftEndCharIdx;
+        const droppedEnd = rightStartCharIdx;
+        const shift = marker.length - (droppedEnd - droppedStart);
+        // Spans falling entirely before the drop stay; entirely after shift by
+        // (marker.length - dropped chars); spans crossing the drop are clipped.
+        const newSpans = [];
+        for (const s of this._spans) {
+            if (s.end <= droppedStart) {
+                newSpans.push(s);
+            }
+            else if (s.start >= droppedEnd) {
+                newSpans.push(s.move(shift));
+            }
+            else {
+                // crosses \u2014 clip to left side and to right side as two spans
+                if (s.start < droppedStart) {
+                    newSpans.push(new Span(s.start, droppedStart, s.style));
+                }
+                if (s.end > droppedEnd) {
+                    newSpans.push(new Span(droppedEnd + shift, s.end + shift, s.style));
+                }
+            }
+        }
+        this._text = leftText + marker + rightText;
+        this._spans = newSpans;
+        return this;
+    }
+    _cropRightTo(targetWidth) {
+        this.plain = cellFit(this._text, targetWidth);
+    }
+    _cropLeftTo(targetWidth) {
+        const charIdx = this._text.length - cellFitEnd(this._text, targetWidth).length;
+        // Shift spans left by charIdx; clip spans that started before.
+        const shift = -charIdx;
+        this._spans = this._spans
+            .map((s) => {
+            if (s.end <= charIdx)
+                return undefined;
+            const newStart = Math.max(0, s.start + shift);
+            const newEnd = s.end + shift;
+            return new Span(newStart, newEnd, s.style);
+        })
+            .filter((s) => s !== undefined);
+        this._text = this._text.slice(charIdx);
+    }
+    // --- Alignment ---
+    align(justify, width) {
+        const currentWidth = this.cellLength;
+        if (currentWidth >= width)
+            return this;
+        // Padded to `width`, the text claims that width only while its tab stops
+        // hold: widened now, padding on either side cannot move them.
+        this.expandTabs();
+        const gap = width - currentWidth;
+        switch (justify) {
+            case "left":
+                this.padRight(gap);
+                break;
+            case "right":
+                this.padLeft(gap);
+                break;
+            case "center": {
+                const leftPad = Math.floor(gap / 2);
+                const rightPad = gap - leftPad;
+                this.padLeft(leftPad);
+                this.padRight(rightPad);
+                break;
+            }
+        }
+        return this;
+    }
+    // --- Suffix Removal ---
+    removeSuffix(suffix) {
+        if (this._text.endsWith(suffix)) {
+            this.plain = this._text.slice(0, -suffix.length);
+        }
+        return this;
+    }
+    // --- Token Appending ---
+    appendTokens(tokens) {
+        for (const [text, style] of tokens) {
+            this.append(text, style);
+        }
+        return this;
+    }
+    // --- Static Factories ---
+    static assemble(parts, options) {
+        const result = new RichText("", { style: options?.style });
+        for (const part of parts) {
+            if (typeof part === "string") {
+                result.append(part);
+            }
+            else if (part instanceof RichText) {
+                result.append(part);
+            }
+            else {
+                const [text, style] = part;
+                result.append(text, style);
+            }
+        }
+        return result;
+    }
+    static styled(text, style) {
+        const result = new RichText(text);
+        result.stylize(style);
+        return result;
+    }
+    /**
+     * Concatenate a sequence of `RichText` fragments into a single `RichText`,
+     * flattening each fragment's wrapping `style` onto a span over that
+     * fragment's range so downstream rendering preserves the original styling.
+     *
+     * Designed for the template engine's `RichText[]` output: a top-level
+     * `{{ red "x" }}{{ blue "y" }}` evaluates to two fragments — one with
+     * wrapping `style = red`, one with `blue` — and consumers that want a
+     * single styled string for downstream rendering need both styles
+     * preserved as spans on the concatenated result, which is what `append()`
+     * does with each fragment.
+     *
+     * Empty input → empty `RichText` with `end: ""`. Caller can override
+     * `end` (defaults to `""` — the engine-output case rarely wants a
+     * trailing newline added by the container).
+     */
+    static fromFragments(fragments, options) {
+        const result = new RichText("", { end: options?.end ?? "" });
+        for (const frag of fragments)
+            result.append(frag);
+        return result;
+    }
+    // --- Renderable ---
+    *render(options) {
+        const expanded = expandTabs(this._text, this._tabSize);
+        const base = this.resolvedStyle(options);
+        const { segments: allSegments, covered } = this._buildSegments(expanded, base, options);
+        const spanFree = spanFreeLines(allSegments, covered);
+        // Rich wraps the lines of `split(allow_blank=True)`: n line breaks make
+        // n + 1 lines, the last one blank when the text ends in a break, and that
+        // blank line is justified like any other. `Segment.splitLines` is Rich's
+        // `Segment.split_lines`, which drops a trailing empty line, so the text is
+        // handed to it closed by one more break — the dropped line is then always
+        // that one, and every line the text has comes back.
+        allSegments.push(Segment.line());
+        const logicalLines = Segment.splitLines(allSegments);
+        // [LAW:single-enforcer] The one crossing for this renderable's width, and
+        // the call every other renderable already makes. A bare `cellCount` stood
+        // here doing half of it: it caught a NaN width, which had made every
+        // overflow arm a no-op, but passed an unbounded one through to `justify`,
+        // which pads — and `" ".repeat(Infinity)` throws.
+        const maxWidth = cellCount(withBoundedWidth(options, this).maxWidth);
+        const overflow = this._overflow ?? options.overflow ?? "fold";
+        const noWrap = this._noWrap || (options.noWrap ?? false);
+        // Two widths, and they are the reference's `no_wrap` and `"ignore"` told
+        // apart. `edge` is where a line is cut: gone under `"ignore"`, so the line
+        // leaves at its natural width and whatever drew it decides about the
+        // overhang. `wrapAt` is where a line may break: gone under `noWrap` too,
+        // which keeps one line per line and still cuts it at the edge by the
+        // overflow method — Rich's `Text.wrap` truncates its no-wrap arm.
+        //
+        // [LAW:dataflow-not-control-flow] Each reaches the pipeline as a width, not
+        // as a step to skip: an unbounded width has no edge to break at, so
+        // `divideLine` finds no cuts and `_fitLine` finds nothing past the edge,
+        // and every line runs the same three steps. `Infinity` is already this
+        // library's spelling of an unbounded width offer — `withBoundedWidth` in
+        // protocol.ts parses one on the way in.
+        const edge = overflow === "ignore" ? cellCount(Infinity) : maxWidth;
+        const wrapAt = noWrap ? cellCount(Infinity) : edge;
+        // A line with no edge has no width to be justified in, so under `"ignore"`
+        // it is not justified — the reference's `Text.wrap` returns that arm before
+        // `justify`. `undefined` is the placement that leaves a line as it is.
+        const justify = overflow === "ignore" ? undefined : this._justify ?? options.justify;
+        // One cell either way, so the marker's stand-in leaves the cut where it was.
+        const ellipsis = drawable(options, "\u2026", ".");
+        for (let index = 0; index < logicalLines.length; index += 1) {
+            const line = logicalLines[index];
+            const free = spanFree[index];
+            const terminateLine = index < logicalLines.length - 1;
+            // Wrap first, overflow last — the reference's order, and the reason a
+            // long sentence grows a table row while an unbreakable word in the same
+            // column still ellipsizes.
+            const cuts = divideLine(plainOf(line), wrapAt, { fold: overflow === "fold" });
+            const wrapped = Segment.divide(line, cuts);
+            const placed = this._justifyLines(wrapped.map((piece, at) => ({
+                segments: [...this._fitLine(piece, edge, overflow, ellipsis)],
+                free: (cell) => free(at === 0 ? cell : cuts[at - 1] + cell),
+            })), maxWidth, base, justify);
+            for (let piece = 0; piece < placed.length; piece += 1) {
+                yield* placed[piece];
+                if (piece < placed.length - 1 || terminateLine) {
+                    yield Segment.line();
+                }
+            }
+        }
+        // [LAW:single-enforcer] The one place `end` is emitted, for empty and
+        // non-empty text alike — the pre-fix code checked it once for empty text
+        // (truthy) and again for non-empty text (truthy and not the default
+        // "\n"), which gave `end` two meanings depending on whether the text was
+        // empty (rich-text-5ai).
+        if (this._end) {
+            yield new Segment(this._end);
+        }
+    }
+    // --- Measurable ---
+    measure(options) {
+        const lines = expandTabs(this._text, this._tabSize).text.split("\n");
+        const maxLineWidth = lines.reduce((widest, line) => Math.max(widest, cellLen(line)), 0);
+        // [LAW:one-source-of-truth] The minimum is the widest piece the wrapper
+        // never breaks, asked of the wrapper — so a line's indent, which wraps
+        // with its first word, counts toward it. Rich splits on whitespace here
+        // and drops the indent, then wraps with it kept: a container sized by
+        // that minimum cuts the word it was meant to hold whole. Text with no word
+        // at all is all whitespace, and as in Rich its whole width is the minimum.
+        const widths = lines.flatMap(wordWidths);
+        const maxWordWidth = widths.length > 0 ? widths.reduce((widest, w) => Math.max(widest, w), 0) : maxLineWidth;
+        // Parsed for the same reason `render` parses it: an unparsed NaN ceiling
+        // makes both `Math.min` calls NaN, and a range of NaN..NaN is one no parent
+        // layout can divide.
+        const ceiling = cellCount(options.maxWidth);
+        return {
+            minimum: Math.min(maxWordWidth, ceiling),
+            maximum: Math.min(maxLineWidth, ceiling),
+        };
+    }
+    // --- Internal ---
+    /**
+     * The rendered text cut at every span edge, each piece carrying the base
+     * style plus every span covering it.
+     *
+     * Walked span-first rather than piece-first, and that direction is the whole
+     * performance argument. The pieces are cut at the span edges themselves, so
+     * a span covers a piece exactly when it covers the piece's first character —
+     * which makes each span's run of pieces a contiguous range it can be written
+     * into once, instead of a question every piece asks of every span. The
+     * piece-first form charged `spans x pieces`, and the pieces are themselves
+     * cut by the spans, so anything styling densely paid the square in ordinary
+     * use: 8,000 one-character spans took 211ms where 1,000 took 3.2ms. Every
+     * `Highlighter` over a large value reaches that, and so does `Pretty`, whose
+     * indent guides emit a span per indent character.
+     *
+     * Span-first is also what keeps the composition honest, for free. `Style.add`
+     * is order-dependent and the last writer wins, so the pieces have to fold
+     * their styles in `_spans` order — which iterating `_spans` is, and which a
+     * sweep ordered by position would have had to reconstruct.
+     *
+     * [LAW:dataflow-not-control-flow] A span covering nothing — empty, reversed,
+     * or entirely past the text — still cuts the text where its edges land, as it
+     * always did, and then folds into no piece at all: its range comes out empty
+     * and no case handles it.
+     */
+    _buildSegments({ text, offsetOf }, base, options) {
+        // A span is written against the text as given; `offsetOf` moves its edges
+        // past every tab that widened before them.
+        const clamp = (offset) => Math.max(0, Math.min(offsetOf(offset), text.length));
+        // The text's own start and end are always the outer boundaries, even when
+        // they are one offset: empty text is one empty piece, as Rich's
+        // `Text.render` yields `Segment("")` for it. That piece writes no bytes,
+        // and it is what makes empty text one line to everything that splits a
+        // render into lines — a panel's body, a table cell — where Rich draws one.
+        const inner = new Set();
+        for (const span of this._spans) {
+            inner.add(clamp(span.start));
+            inner.add(clamp(span.end));
+        }
+        inner.delete(0);
+        inner.delete(text.length);
+        const boundaries = [0, ...[...inner].sort((a, b) => a - b), text.length];
+        // Every span edge is a boundary, so where a span's range opens is a lookup
+        // rather than a search. Where two boundaries share an offset — empty
+        // text's start and end — the first wins, so the offset names the piece
+        // that opens there rather than the one past the last.
+        const pieceAt = new Map(boundaries.map((position, piece) => [position, piece]).reverse());
+        const styles = boundaries.slice(0, -1).map(() => base);
+        const covered = styles.map(() => false);
+        for (const span of this._spans) {
+            const end = clamp(span.end);
+            const style = resolveStyle(options, span.style);
+            const opensAt = pieceAt.get(clamp(span.start));
+            for (let piece = opensAt; boundaries[piece] < end; piece++) {
+                styles[piece] = styles[piece].add(style);
+                covered[piece] = true;
+            }
+        }
+        const segments = styles.map((style, piece) => new Segment(text.slice(boundaries[piece], boundaries[piece + 1]), style.isNull ? undefined : style));
+        return { segments, covered };
+    }
+    /**
+     * The pieces one logical line wrapped into, each placed in a canvas
+     * `maxWidth` wide, as Rich's `Lines.justify` places them — pinned block for
+     * block against the reference in `test/core/text-justify.test.ts`.
+     *
+     * It is handed the whole wrapped line because `full` is the one mode a
+     * piece cannot answer alone: the reference leaves a paragraph's last line
+     * ragged, so where the piece sits decides its answer where the other three
+     * modes need only the piece itself. The set that decides "last" is this one
+     * and not the whole render — `Text.wrap` calls `Lines.justify` once per
+     * *logical* line — and `Segment.divide` already handed it over whole.
+     */
+    _justifyLines(lines, maxWidth, base, justify) {
+        if (justify !== "full") {
+            return lines.map((line) => [...this._justifyLine(line, maxWidth, base, justify)]);
+        }
+        return lines.map(({ segments }, index) => index === lines.length - 1 ? segments : this._fillLine(segments, maxWidth, base));
+    }
+    /**
+     * One line placed in a canvas `maxWidth` wide.
+     *
+     * Centre and right align on the line's *content*. The whitespace a wrap
+     * leaves on the end of the line it closed is the break's own padding, not
+     * text, and aligning around it pushes the text half a gap off true — a
+     * centred title that wraps drifts left on every line that happens to end in
+     * a space. Left keeps that whitespace, because there it is already on the
+     * side the padding goes.
+     *
+     * `undefined` is not `"left"`: it is Rich's `"default"`, which places the
+     * line without padding it at all. That distinction is what lets a soft-wrapped
+     * `Console.print` leave its lines at their natural width.
+     *
+     * The padding is drawn in the text's base style, as the reference pads
+     * inside the `Text` it justifies: a title "on red" fills its row in red.
+     */
+    *_justifyLine({ segments: line, free }, maxWidth, base, 
+    // [LAW:types-are-the-program] `full` is absent rather than ignored: it
+    // needs the lines either side of this one, so the type refuses it here
+    // instead of a branch quietly rendering it as `left`, which is the bug
+    // this signature replaces (rich-justify-0cr.1).
+    justify) {
+        const padStyle = base.isNull ? undefined : base;
+        switch (justify) {
+            case "center":
+            case "right": {
+                const body = Segment.adjustLineLength(line, Segment.getLineLength(line) - hangingWhitespace(line), undefined, false);
+                const gap = Math.max(maxWidth - Segment.getLineLength(body), 0);
+                const leftPad = justify === "center" ? Math.floor(gap / 2) : gap;
+                yield* padded(body, free, leftPad, gap - leftPad, padStyle);
+                break;
+            }
+            case "left":
+                yield* padded(line, free, 0, Math.max(maxWidth - Segment.getLineLength(line), 0), padStyle);
+                break;
+            default:
+                yield* line;
+                break;
+        }
+    }
+    /**
+     * One line of a wrapped paragraph, its gaps widened until it fills the
+     * canvas — what `justify: "full"` promises, and what the reference's
+     * `Lines.justify` does to every line of a paragraph but the last.
+     *
+     * Slack goes in a cell at a time, starting at the rightmost gap and walking
+     * left, round and round until the line is full. That order is the
+     * reference's own, and what it decides is where an odd cell lands when the
+     * slack will not divide evenly: the right-hand gaps take it.
+     *
+     * The words come from the line's *text* split on a single space, with the
+     * blank a trailing separator leaves behind dropped — `Text.split` and
+     * `String.prototype.split` agree on that list, empty words and all. Two
+     * consequences read as bugs until you know whose they are: a run of n
+     * spaces is n gaps rather than one, so spacing an author widened stretches
+     * instead of collapsing, and the whitespace a wrap left hanging is a gap
+     * like the rest, which is why a filled line does not keep it. Both are
+     * pinned in `text-justify.golden.txt`, by the `uneven` and `sentence`
+     * blocks respectively.
+     */
+    _fillLine(line, maxWidth, base) {
+        const plain = plainOf(line);
+        const words = plain.split(" ");
+        if (plain.endsWith(" "))
+            words.pop();
+        const gaps = words.length - 1;
+        const spaces = new Array(gaps).fill(1);
+        let filled = words.reduce((total, word) => total + cellLen(word), 0) + gaps;
+        for (let turn = 0; filled < maxWidth && gaps > 0; turn = (turn + 1) % gaps) {
+            spaces[gaps - 1 - turn] += 1;
+            filled += 1;
+        }
+        // Cut at both edges of every gap, so a word is an even piece and the
+        // separator that followed it is the odd piece after it. Measured in cells
+        // because that is the coordinate system `Segment.divide` reads, which a
+        // line of wide glyphs is the only thing that notices.
+        const cuts = [];
+        let edge = 0;
+        for (let index = 0; index < words.length; index += 1) {
+            edge += cellLen(words[index]);
+            cuts.push(edge);
+            edge += 1;
+            if (index < gaps)
+                cuts.push(edge);
+        }
+        const pieces = Segment.divide(line, cuts);
+        // A widened gap takes the style the words either side of it agree on, and
+        // the line's own where they disagree — the reference reads that off the
+        // character each side turns towards the gap, which is the offset `at` is
+        // given here. A word with no characters turns none and answers with the
+        // line's style, which is what two adjacent separators leave between them.
+        const edgeStyle = (word, at) => word.filter((segment) => segment.hasText).at(at)?.style ?? base;
+        const result = [];
+        for (let index = 0; index < words.length; index += 1) {
+            result.push(...pieces[index * 2]);
+            if (index < gaps) {
+                const before = edgeStyle(pieces[index * 2], -1);
+                const after = edgeStyle(pieces[index * 2 + 2], 0);
+                const style = before.equals(after) ? before : base;
+                result.push(new Segment(" ".repeat(spaces[index]), style.isNull ? undefined : style));
+            }
+        }
+        return result;
+    }
+    /**
+     * One wrapped line cut to the canvas.
+     *
+     * Everything reaching here already survived wrapping, so the only text still
+     * too wide is text no break could help: a word longer than the canvas under
+     * a non-folding overflow method, a glyph wider than the budget, a canvas
+     * with no cells at all, or a `noWrap` line, which no break was allowed to
+     * help. That is what makes the overflow method a last resort rather than the
+     * first thing a long cell meets. `"fold"` has nothing left to fold here and
+     * cuts as `"crop"` does, as the reference's `truncate` does.
+     */
+    *_fitLine(line, maxWidth, overflow, ellipsis) {
+        const lineWidth = Segment.getLineLength(line);
+        const contentWidth = lineWidth - hangingWhitespace(line);
+        // Whitespace hanging past the edge is the wrap's own padding: cropping it
+        // away is not truncation, so it earns no marker. Without this an ellipsis
+        // landed on any break that fell a space past the column — the common case
+        // in a table, not an edge one.
+        if (contentWidth <= maxWidth) {
+            yield* Segment.adjustLineLength(line, Math.min(lineWidth, maxWidth), undefined, false);
+            return;
+        }
+        // The marker takes the last cell and the text keeps the rest. At maxWidth 1
+        // that is zero cells of text and the marker alone, which is the honest
+        // rendering of "all of this was cut"; the `maxWidth > 1` guard that used to
+        // stand here emitted no line at all, so every table column squeezed to a
+        // single cell rendered blank rather than truncated — `ellipsis` being the
+        // default column overflow, a hard-squeezed table looked like an empty frame.
+        //
+        // At maxWidth 0 there is no cell to put the marker in, so every method
+        // yields the same bare empty line. Agreement there is what keeps a
+        // `Columns` or `Layout` squeezed to no width at all from rendering
+        // three different kinds of nothing.
+        if (overflow === "ellipsis" && maxWidth > 0) {
+            yield* Segment.adjustLineLength(line, maxWidth - 1, undefined, false);
+            yield new Segment(ellipsis);
+            return;
+        }
+        yield* Segment.adjustLineLength(line, maxWidth, undefined, false);
+    }
+}
+/**
+ * For each logical line of a render, whether the cell at an offset is covered
+ * by no span. `covered` is `_buildSegments`'s answer per piece; a piece split
+ * by a line break answers for both halves.
+ */
+function spanFreeLines(segments, covered) {
+    // Per line, the cell each run ends at and whether that run is span-free.
+    const lines = [[]];
+    segments.forEach((segment, piece) => {
+        segment.text.split("\n").forEach((part, at) => {
+            if (at > 0)
+                lines.push([]);
+            const runs = lines.at(-1);
+            runs.push({ end: (runs.at(-1)?.end ?? 0) + cellLen(part), free: !covered[piece] });
+        });
+    });
+    return lines.map((runs) => (cell) => {
+        let lo = 0;
+        let hi = runs.length;
+        while (lo < hi) {
+            const mid = (lo + hi) >> 1;
+            if (runs[mid].end <= cell)
+                lo = mid + 1;
+            else
+                hi = mid;
+        }
+        return runs[lo].free;
+    });
+}
+/**
+ * A line with `left` and `right` cells of padding in `style` either side.
+ *
+ * The reference pads inside the `Text` it justifies and cuts its output at
+ * span edges, so a pad and the run of the line beside it that no span covers
+ * are one piece, and Rich emits them as one segment; a run a span covers stays
+ * its own segment even when its style draws the same as the pad
+ * (rich-table-qj6i). A span-free run is drawn in `style` alone, which is what
+ * makes the joined segment's style exact.
+ */
+function* padded(drawn, free, left, right, style) {
+    if (left + right === 0)
+        return yield* drawn;
+    // An empty piece writes no bytes, and at an edge it would take the join that
+    // belongs to the run behind it.
+    const line = drawn.filter((segment) => segment.text !== "");
+    const pad = (cells) => " ".repeat(cells);
+    const width = Segment.getLineLength(line);
+    // A line with no cells has no run to join; the pads alone are its one piece.
+    if (width === 0)
+        return yield new Segment(pad(left + right), style);
+    const last = line.length - 1;
+    // A zero-width segment has no cell of its own to ask about, so it never
+    // joins: merged on its neighbour's answer it would lose its own style.
+    const head = left > 0 && line[0].cellLength > 0 && free(0);
+    const tail = right > 0 && line[last].cellLength > 0 && free(width - 1);
+    const from = head ? 1 : 0;
+    const to = tail ? last : last + 1;
+    // One run joined on both sides: the pads and it are one piece.
+    if (from > to) {
+        yield new Segment(pad(left) + line[0].text + pad(right), style);
+        return;
+    }
+    if (left > 0)
+        yield new Segment(pad(left) + (head ? line[0].text : ""), style);
+    yield* line.slice(from, to);
+    if (right > 0)
+        yield new Segment((tail ? line[last].text : "") + pad(right), style);
+}