@promptctl/rich-js 0.8.0 → 0.9.0

package/dist/core/text.js

@@ -2,40 +2,54 @@
  * RichText — styled text with spans. The primary text type for the library.
  */
 import { cellLen, cellCount } from "./cells.js";
+import { divideLine } from "./wrap.js";
 import { Segment } from "./segment.js";
 import { Style, NULL_STYLE, StyleSyntaxError } from "./style.js";
 import { stripOscTerminators } from "./sanitize.js";
+import { getStyle, withBoundedWidth } from "./protocol.js";
 // Strip control characters except \t and \n
 // [LAW:single-enforcer] Single place where control chars are sanitized
 const CONTROL_CHARS_RE = /[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g;
 function stripControlChars(text) {
     return text.replace(CONTROL_CHARS_RE, "");
 }
+const TRAILING_WHITESPACE_RE = /\s+$/;
 /**
- * The offsets a line of `lineWidth` cells is cut at to fold it into pieces of
- * at most `maxWidth`. Requires `maxWidth >= 1`: the caller answers the
- * zero-cell canvas, because "no cut fits" and "no cell fits" are different
- * facts and only one of them is a list of offsets.
+ * 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 foldCuts(lineWidth, maxWidth) {
-    const cuts = [];
-    for (let w = maxWidth; w < lineWidth; w += maxWidth)
-        cuts.push(w);
-    return cuts;
+function plainOf(line) {
+    return line.map((segment) => segment.text).join("");
 }
-// [LAW:single-enforcer] RichText is the *data-model* trust boundary for
-// link URLs — any Style carrying a link that enters a RichText is sanitized
-// in place, so callers that inspect `richText.style.link` or
-// `richText.spans[].style.link` see the same clean URL the renderer will
-// emit. Wire-byte safety is enforced separately in render.ts and style.ts
-// via the same shared `stripOscTerminators` helper (one rule, applied at
-// both seams). Together those layers guarantee the dirty bytes can neither
-// live in the in-memory model nor escape on the wire — even if a Style is
-// constructed and rendered via a path that bypasses RichText entirely.
-//
-// Co-located inside `resolveStyle` so any current or future RichText method
-// that normalizes a `string | Style` argument inherits sanitization
-// automatically; no per-callsite wrap to forget.
+/**
+ * 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 in render.ts and
+// style.ts through the same `stripOscTerminators`.
 function sanitizeStyleLink(style) {
     const link = style.link;
     if (!link)
@@ -45,28 +59,39 @@ function sanitizeStyleLink(style) {
         return style;
     return style.withLink(cleaned);
 }
-function resolveStyle(style) {
-    if (style === undefined)
-        return NULL_STYLE;
-    let resolved;
-    if (typeof style === "string") {
-        try {
-            resolved = Style.parse(style);
-        }
-        catch (err) {
-            // [LAW:single-enforcer] Styling is non-critical — an unrecognized style
-            // name (typo, missing theme key, bad concatenation) degrades to unstyled
-            // rather than crashing. Absorb only StyleSyntaxError at this trust
-            // boundary; other errors are genuine bugs and must surface.
-            if (err instanceof StyleSyntaxError)
-                return NULL_STYLE;
-            throw err;
-        }
-    }
-    else {
-        resolved = style;
-    }
-    return sanitizeStyleLink(resolved);
+/**
+ * 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` has
+ * one to sanitize here.
+ */
+function admitStyle(style) {
+    return style instanceof Style ? sanitizeStyleLink(style) : 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 `string | Style` stands for in this render.
+ *
+ * [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. A parsed string can carry a link, so the result is
+ * sanitized on the way out as well.
+ */
+function resolveStyle(options, style) {
+    try {
+        return sanitizeStyleLink(getStyle(options, style));
+    }
+    catch (err) {
+        if (err instanceof StyleSyntaxError)
+            return NULL_STYLE;
+        throw err;
+    }
 }
 // --- Span ---
 export class Span {
@@ -116,9 +141,9 @@ export class RichText {
     constructor(text, options) {
         this._text = text ? stripControlChars(text) : "";
         this._spans = [];
-        // [LAW:single-enforcer] `resolveStyle` is the boundary that sanitizes
+        // [LAW:single-enforcer] `admitStyle` is the boundary that sanitizes
         // any link URL crossing into a RichText; downstream trusts the invariant.
-        this._style = resolveStyle(options?.style);
+        this._style = admitStyle(options?.style ?? NULL_STYLE);
         this._justify = options?.justify;
         this._overflow = options?.overflow;
         this._end = options?.end ?? "\n";
@@ -147,14 +172,12 @@ export class RichText {
     get hasContent() {
         return this._text.length > 0;
     }
+    /** The base style every span layers over: a `Style`, or a name resolved at render. */
     get style() {
         return this._style;
     }
     set style(value) {
-        // [LAW:single-enforcer] The setter is the only entry that doesn't pass
-        // through `resolveStyle` (its argument is already a Style); sanitize
-        // directly so the boundary contract holds for every Style assignment.
-        this._style = sanitizeStyleLink(value);
+        this._style = admitStyle(value);
     }
     get justify() {
         return this._justify;
@@ -183,6 +206,14 @@ export class RichText {
     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")
@@ -199,16 +230,19 @@ export class RichText {
      * 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) {
+    edgeStyle(side, options) {
+        const base = this.resolvedStyle(options);
         if (this._text.length === 0)
-            return this._style;
+            return base;
         const pos = side === "left" ? 0 : this._text.length - 1;
-        let result = this._style;
+        let result = base;
         for (const span of this._spans) {
             if (span.start <= pos && pos < span.end) {
-                const spanStyle = typeof span.style === "string" ? Style.parse(span.style) : span.style;
-                result = result.add(spanStyle);
+                result = result.add(resolveStyle(options, span.style));
             }
         }
         return result;
@@ -229,12 +263,7 @@ export class RichText {
         const sanitized = stripControlChars(content);
         const start = this._text.length;
         this._text += sanitized;
-        if (style !== undefined) {
-            const resolved = resolveStyle(style);
-            if (!resolved.isNull) {
-                this._spans.push(new Span(start, this._text.length, resolved));
-            }
-        }
+        this._addSpan(start, this._text.length, style ?? "");
         return this;
     }
     contains(needle) {
@@ -270,10 +299,17 @@ export class RichText {
         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) {
+        if (isEmptyStyle(style))
+            return;
+        this._spans.push(new Span(start, end, admitStyle(style)));
+    }
     stylize(style, start, end) {
-        const resolved = resolveStyle(style);
-        if (resolved.isNull)
-            return this;
         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;
@@ -281,7 +317,7 @@ export class RichText {
             return this;
         const clampedStart = Math.max(0, s);
         const clampedEnd = Math.min(len, e);
-        this._spans.push(new Span(clampedStart, clampedEnd, resolved));
+        this._addSpan(clampedStart, clampedEnd, style);
         return this;
     }
     highlightRegex(pattern, style) {
@@ -304,7 +340,7 @@ export class RichText {
                         const posInMatch = match[0].indexOf(groupValue, searchFrom);
                         if (posInMatch >= 0) {
                             const groupStart = match.index + posInMatch;
-                            this._spans.push(new Span(groupStart, groupStart + groupValue.length, groupName));
+                            this._addSpan(groupStart, groupStart + groupValue.length, groupName);
                             searchFrom = posInMatch + groupValue.length;
                         }
                     }
@@ -312,19 +348,13 @@ export class RichText {
                 count++;
                 continue;
             }
-            const resolvedStyle = style !== undefined ? resolveStyle(style) : NULL_STYLE;
-            if (!resolvedStyle.isNull) {
-                this._spans.push(new Span(match.index, match.index + match[0].length, resolvedStyle));
-            }
+            this._addSpan(match.index, match.index + match[0].length, style ?? "");
             count++;
         }
         return count;
     }
     highlightWords(words, style, options) {
         const caseSensitive = options?.caseSensitive !== false;
-        const resolved = resolveStyle(style);
-        if (resolved.isNull)
-            return 0;
         let count = 0;
         for (const word of words) {
             if (word.length === 0)
@@ -334,7 +364,7 @@ export class RichText {
             const re = new RegExp(`\\b${escaped}\\b`, flags);
             let match;
             while ((match = re.exec(this._text)) !== null) {
-                this._spans.push(new Span(match.index, match.index + match[0].length, resolved));
+                this._addSpan(match.index, match.index + match[0].length, style);
                 count++;
             }
         }
@@ -657,9 +687,7 @@ export class RichText {
         for (const frag of fragments) {
             const start = result.length;
             result.append(frag.plain);
-            if (!frag.style.isNull) {
-                result.stylize(frag.style, start, result.length);
-            }
+            result.stylize(frag.style, start, result.length);
             for (const span of frag.spans) {
                 result.stylize(span.style, start + span.start, start + span.end);
             }
@@ -674,32 +702,47 @@ export class RichText {
                 yield new Segment(this._end);
             return;
         }
-        const allSegments = this._buildSegments(text);
+        const base = this.resolvedStyle(options);
+        const allSegments = this._buildSegments(text, base, options);
         const logicalLines = Segment.splitLines(allSegments);
-        // [LAW:parse-dont-validate] The one crossing for this renderable's width.
-        // Unparsed, a NaN width made `lineWidth <= maxWidth` false and every
-        // overflow arm a no-op, so the text emitted its full natural width and
-        // silently overflowed whatever asked for it.
-        const maxWidth = cellCount(options.maxWidth);
+        // [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 justify = this._justify ?? options.justify;
         const noWrap = this._noWrap || (options.noWrap ?? false);
+        // The width a line is cut to, which is not always the width it is
+        // justified in. `noWrap` means the line is not bounded at all: it leaves at
+        // its natural width and whatever asked for it decides about the overhang —
+        // `Console`'s soft wrap and `FlexStrip`'s too-wide fallback both want the
+        // text intact rather than cropped.
+        //
+        // [LAW:dataflow-not-control-flow] It reaches the pipeline as a width, not
+        // as a step to skip: an unbounded budget 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 budget = noWrap ? cellCount(Infinity) : maxWidth;
         const endsWithNewline = text.endsWith("\n");
         for (let index = 0; index < logicalLines.length; index += 1) {
             const line = logicalLines[index];
-            const lineWidth = Segment.getLineLength(line);
             const terminateLine = index < logicalLines.length - 1 || endsWithNewline;
-            if (noWrap || lineWidth <= maxWidth) {
-                // Line fits — apply justification
-                yield* this._justifyLine(line, maxWidth, justify);
-                if (terminateLine) {
+            // 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), budget, { fold: overflow === "fold" });
+            const wrapped = Segment.divide(line, cuts);
+            const placed = this._justifyLines(wrapped.map((piece) => [...this._fitLine(piece, budget, overflow)]), maxWidth, base, justify);
+            for (let piece = 0; piece < placed.length; piece += 1) {
+                yield* placed[piece];
+                if (piece < placed.length - 1 || terminateLine) {
                     yield Segment.line();
                 }
             }
-            else {
-                // Line too long — handle overflow
-                yield* this._overflowLine(line, lineWidth, maxWidth, overflow, terminateLine);
-            }
         }
         if (this._end && this._end !== "\n") {
             yield new Segment(this._end);
@@ -737,119 +780,214 @@ export class RichText {
             return text;
         return text.replace(/\t/g, " ".repeat(this._tabSize));
     }
-    _buildSegments(text) {
-        if (text.length === 0)
-            return [];
-        // Collect all unique boundary positions
+    /**
+     * 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, base, options) {
+        const clamp = (offset) => Math.max(0, Math.min(offset, text.length));
         const positions = new Set([0, text.length]);
         for (const span of this._spans) {
-            const start = Math.max(0, Math.min(span.start, text.length));
-            const end = Math.max(0, Math.min(span.end, text.length));
-            positions.add(start);
-            positions.add(end);
-        }
-        const sorted = [...positions].sort((a, b) => a - b);
-        const segments = [];
-        // [LAW:dataflow-not-control-flow] Always iterate all regions; empty ones produce nothing
-        for (let i = 0; i < sorted.length - 1; i++) {
-            const regionStart = sorted[i];
-            const regionEnd = sorted[i + 1];
-            const regionText = text.slice(regionStart, regionEnd);
-            if (regionText.length === 0)
-                continue;
-            // Combine base style with all active span styles
-            let style = this._style;
-            for (const span of this._spans) {
-                if (span.start <= regionStart && span.end >= regionEnd) {
-                    const spanStyle = resolveStyle(span.style);
-                    style = style.add(spanStyle);
-                }
+            positions.add(clamp(span.start));
+            positions.add(clamp(span.end));
+        }
+        const boundaries = [...positions].sort((a, b) => a - b);
+        // Every span edge is a boundary, so where a span's range opens is a lookup
+        // rather than a search.
+        const pieceAt = new Map(boundaries.map((position, piece) => [position, piece]));
+        const styles = boundaries.slice(0, -1).map(() => base);
+        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);
             }
-            segments.push(new Segment(regionText, style.isNull ? undefined : style));
         }
-        return segments;
+        return styles.map((style, piece) => new Segment(text.slice(boundaries[piece], boundaries[piece + 1]), style.isNull ? undefined : style));
     }
-    *_justifyLine(line, maxWidth, justify) {
-        const lineWidth = Segment.getLineLength(line);
-        const gap = maxWidth - lineWidth;
+    /**
+     * 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, justify)]);
+        }
+        return lines.map((line, index) => index === lines.length - 1 ? line : this._fillLine(line, 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.
+     */
+    *_justifyLine(line, maxWidth, 
+    // [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) {
         switch (justify) {
-            case "center": {
-                const leftPad = Math.floor(gap / 2);
+            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;
                 if (leftPad > 0)
                     yield new Segment(" ".repeat(leftPad));
-                yield* line;
+                yield* body;
                 const rightPad = gap - leftPad;
                 if (rightPad > 0)
                     yield new Segment(" ".repeat(rightPad));
                 break;
             }
-            case "right": {
-                if (gap > 0)
-                    yield new Segment(" ".repeat(gap));
-                yield* line;
-                break;
-            }
-            case "full": {
-                // Full justification: distribute spaces between words
-                // For now, fall through to left alignment
-                yield* line;
+            case "left":
+                yield* Segment.adjustLineLength(line, Math.max(maxWidth, Segment.getLineLength(line)));
                 break;
-            }
             default:
-                // "left" or undefined — just yield the line as-is
                 yield* line;
                 break;
         }
     }
-    *_overflowLine(line, lineWidth, maxWidth, overflow, terminateLine) {
-        switch (overflow) {
-            case "fold": {
-                // Split at maxWidth boundaries. A cell cannot be split, so a zero-cell
-                // canvas holds no piece of the line and the fold is one empty piece —
-                // the same thing `crop` and `ellipsis` yield there, which is what makes
-                // the three overflow modes agree at the bottom of the range instead of
-                // this loop stepping by zero forever. It did exactly that before:
-                // ~2^27 pushes and about a gigabyte before a `RangeError`, reachable
-                // from any `Columns` or `Layout` squeezed to no width at all.
-                const foldedLines = maxWidth === 0
-                    ? [Segment.adjustLineLength(line, 0, undefined, false)]
-                    : Segment.divide(line, foldCuts(lineWidth, maxWidth));
-                for (let index = 0; index < foldedLines.length; index += 1) {
-                    const fLine = foldedLines[index];
-                    yield* fLine;
-                    if (index < foldedLines.length - 1 || terminateLine) {
-                        yield Segment.line();
-                    }
-                }
-                break;
-            }
-            case "crop": {
-                const cropped = Segment.adjustLineLength(line, maxWidth, undefined, false);
-                yield* cropped;
-                if (terminateLine) {
-                    yield Segment.line();
-                }
-                break;
-            }
-            case "ellipsis": {
-                // 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.
-                yield* Segment.adjustLineLength(line, Math.max(0, maxWidth - 1), undefined, false);
-                // No cell to put it in at maxWidth 0, where every mode emits the bare
-                // line terminator.
-                if (maxWidth > 0)
-                    yield new Segment("\u2026");
-                if (terminateLine) {
-                    yield Segment.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, or a canvas
+     * with no cells at all. That is what makes the overflow method a last
+     * resort rather than the first thing a long cell meets.
+     */
+    *_fitLine(line, maxWidth, overflow) {
+        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("\u2026");
+            return;
+        }
+        yield* Segment.adjustLineLength(line, maxWidth, undefined, false);
     }
 }
 //# sourceMappingURL=text.js.map