@jasy/pdf 1.0.0-beta.3 → 1.0.0-beta.4

package/dist/text/line-breaker.js

@@ -1,5 +1,6 @@
-import { runAdvance } from "./advance.js";
-import { splitLongWord } from "./word-splitting.js";
+import { runAdvance, SOFT_HYPHEN, withoutSoftHyphens } from "./advance.js";
+import { HYPHEN, splitLongWord } from "./word-splitting.js";
+import { headAt, hyphenBreaks, mayBreak, NO_BREAKS } from "./hyphen-breaks.js";
 /**
  * How far a JUSTIFIED line's spaces may be squeezed to keep one more word on it.
  *
@@ -16,17 +17,11 @@ export const MAX_SPACE_SHRINK = 1 / 4;
 /** Three ASCII dots, NOT the "…" glyph (U+2026): plain dots encode in every font - standard-14
  *  (WinAnsi) and any embedded TTF - whereas U+2026 needs a glyph the font may not carry. */
 const ELLIPSIS = "...";
+/** The spaces that end a line: they hang past its edge, neither drawn nor in its width. */
+const TRAILING_SPACES = / +$/;
 /**
- * Break a plain string into lines that each fit within `maxWidth`, splitting on
- * spaces (greedy: a word stays on the current line unless it would overflow).
- *
- * Single source of truth for plain-string wrapping: both height measurement and
- * rendering call this, so they can never disagree. Depends only on `FontMetrics`,
- * not the PDF byte writer - the future fragmentation pass can reuse it.
- */
-/**
- * The width of `text` set as ONE line, accumulated in EXACTLY the order `wrapStringIntoLines` builds a
- * line: the first word, then `+ (space + word)` each time. The order matters because floating-point
+ * The width of `text` set as ONE line, accumulated in EXACTLY the order the breaker builds a line: the
+ * first word, then `+ (space + word)` each time. The order matters because floating-point
  * addition is not associative - a box sized by a differently-grouped sum can be one bit too small for
  * the very line the breaker then measures, and the text wraps inside a box made to fit it. That is not
  * hypothetical: it is what split a footer sized to its own content.
@@ -43,105 +38,163 @@ export function singleLineWidth(text, font, metrics, letterSpacing = 0, wordSpac
         : width + (space + runAdvance(metrics, word, font, letterSpacing)), 0);
 }
 export function wrapStringIntoLines(text, fontFamily, fontSize, fontStyle, maxWidth, metrics, maxLines, overflow, letterSpacing = 0, options = {}) {
-    const { wordSpacing = 0, indent = 0, shrink = 0, splitting = {}, ligatures } = options;
-    let currentLine = "";
-    let currentWidth = 0;
-    let gaps = 0; // spaces on the current line, which is what a justified line can squeeze
-    const lines = [];
-    const font = { fontFamily, fontSize, fontStyle, ligatures };
-    // A `\n` is a HARD break: wrap each paragraph on its own, then cut. An EMPTY paragraph still has to
-    // produce a line, or a deliberate blank line between two blocks silently disappears.
-    text.split("\n").forEach((paragraph, paragraphIndex) => {
-        if (paragraphIndex > 0) {
-            lines.push(currentLine.trim());
-            currentLine = "";
-            currentWidth = 0;
-            gaps = 0;
-        }
-        const words = paragraph.split(" ");
-        words.forEach((word) => {
-            // Word and space advances come from the one shared primitive (`advance.ts`), the same one
-            // `naturalWidth` uses - so a bounded and an unbounded layout of the same text agree bit for bit.
-            const wordWidth = runAdvance(metrics, word, font, letterSpacing);
-            const spaceWidth = runAdvance(metrics, " ", font, letterSpacing) + wordSpacing;
-            // The FIRST line has the indent taken out of its room; every later one gets the full box.
-            const room = lines.length === 0 ? maxWidth - indent : maxWidth;
-            // Break before a word that won't fit - counting the SPACE that would join it, which the old test
-            // forgot. It went unnoticed on the first line, where the very first word added a space too many
-            // and cancelled the error out; after a break `currentWidth` is the bare word, so every following
-            // test was short by one space and the line could overrun its box by that much.
-            //
-            // A single word wider than maxWidth still sits on its (empty) line and overflows, rather than
-            // pushing a phantom empty line before it (which would over-count the height by a line).
-            // A word too wide for the box, split into pieces that fit (hyphenation first, break-word as the
-            // floor). Every piece but the last closes a line; the last carries on as an ordinary word. Off by
-            // default, so a document that asks for neither reaches the untouched path below.
-            // The pieces land on lines that are NOT the first one whenever the current line is closed below,
-            // so they get the full box - `room` only loses the indent while we are genuinely still filling
-            // the indented first line.
-            const splitRoom = lines.length === 0 && currentLine === "" ? room : maxWidth;
-            const split = splitLongWord(word, splitRoom, font, metrics, letterSpacing, splitting);
-            if (split) {
-                if (currentLine !== "")
-                    lines.push(currentLine.trim());
-                for (const piece of split.slice(0, -1))
-                    lines.push(piece);
-                currentLine = split[split.length - 1];
-                currentWidth = runAdvance(metrics, currentLine, font, letterSpacing);
-                gaps = 0;
-                return;
-            }
-            const candidate = currentWidth + (spaceWidth + wordWidth);
-            if (currentLine === "") {
-                currentLine = word;
-                currentWidth = wordWidth;
-                gaps = 0;
-                // How much a JUSTIFIED line may be squeezed to keep one more word: the spaces already on the
-                // line plus the one that would join it, each giving up at most `shrink` of its width. Zero for
-                // every other alignment, where a squeezed line would simply overflow instead.
-                // ONE expression, used for the test AND for the running total. Adding the same three numbers in
-                // a different order gives a different last bit, and a line that lands exactly on `maxWidth` is
-                // then broken by that bit alone - which is how a footer sized to its own text wrapped.
-            }
-            else if (candidate - (gaps + 1) * spaceWidth * shrink > room) {
-                lines.push(currentLine.trim());
-                currentLine = word;
-                currentWidth = wordWidth;
-                gaps = 0;
-            }
-            else {
-                currentLine += " " + word;
-                currentWidth = candidate;
-                gaps += 1;
-            }
-        });
-    });
-    if (currentLine)
-        lines.push(currentLine.trim());
-    // Open-end by default; cap only when maxLines is set (the others get undefined → untouched).
-    if (maxLines == null || lines.length <= maxLines)
-        return lines;
-    const kept = lines.slice(0, maxLines);
-    if (overflow === "ellipsis") {
-        const last = kept.length - 1;
-        kept[last] = ellipsize(kept[last], fontFamily, fontSize, fontStyle, 
-        // The same room that line was broken against: the first one lost the indent to it.
-        last === 0 ? maxWidth - indent : maxWidth, metrics, letterSpacing, wordSpacing, ligatures);
-    }
-    return kept;
+    return breakStringIntoLines(text, fontFamily, fontSize, fontStyle, maxWidth, metrics, maxLines, overflow, letterSpacing, options).map((line) => line.text);
+}
+/** How a line that ends at break `k` of `word` ends: a soft hyphen adds a hyphen the source lacks. */
+const endAt = (word, k) => word[k - 1] === SOFT_HYPHEN && word[k - 2] !== "-" ? "hyphen" : "soft";
+/**
+ * `wrapStringIntoLines`, with each line's source offset and ending. The ONE breaking pass both share,
+ * so a line's position in the source can never disagree with the line itself.
+ */
+export function breakStringIntoLines(text, fontFamily, fontSize, fontStyle, maxWidth, metrics, maxLines, overflow, letterSpacing = 0, options = {}) {
+    // A string is one span: same breaker, same lines.
+    return breakSegmentsIntoLines([{ content: text }], { fontFamily, fontSize, fontStyle, letterSpacing, ...options }, maxWidth, metrics, maxLines, overflow).map((line) => ({
+        text: line.segments.map((segment) => segment.content).join(""),
+        start: line.start.offset,
+        end: line.end,
+    }));
 }
 /**
- * Break styled segments into lines that fit within `maxWidth`. Same greedy word-splitting as the
- * string breaker; each line keeps the segments that landed on it, which is what `line-metrics.ts`
- * later derives the line's height from. Single source of truth: both height measurement and
- * rendering call this.
+ * Break text - spans; a plain string is one - into lines that fit within `maxWidth`, greedily: a word
+ * stays on the current line unless it would overflow. Each line keeps the segments that landed on it,
+ * which is what `line-metrics.ts` derives the line's height from. The one breaker: measuring,
+ * fragmenting and drawing all call this.
  */
 export function breakSegmentsIntoLines(segments, defaults, maxWidth, metrics, maxLines, overflow) {
     const lines = [];
+    const { indent = 0, wordSpacing = 0, shrink = 0 } = defaults;
     let width = 0;
+    let gaps = 0; // spaces on the line, which is what a justified line can squeeze
     let lineSegments = [];
     let combined = "";
-    segments.forEach((segment) => {
+    let lineStart = { segment: 0, offset: 0 }; // where the current line begins
+    // Whether the line holds a word yet - an empty one too: a space is text as written, so a leading one
+    // and both of a double space count.
+    let open = false;
+    // Whether anything DRAWN is on the line. Only then does a word that does not fit start a new one:
+    // a line of spaces alone is empty, and closing it would push a blank line before the word.
+    let inked = false;
+    let ink = 0; // the line's width up to its last drawn glyph - the spaces after it hang
+    // A space that did not fit was not added (it hangs), so the line's text no longer shows that it ends
+    // in a break opportunity - this does.
+    let hung = false;
+    // An empty piece (what a span leaves after its `\n`) has nothing to draw, and its font must not size
+    // the line it lands on - a big span ending in `\n` made the next line as tall as itself. Only a blank
+    // line keeps one: it is what gives that line its height.
+    const close = (segs, lineWidth, end, glued = false) => {
+        let width = lineWidth;
+        let ends = end;
+        // A span boundary is a break too: a line that ends there right after a soft hyphen shows it as a real
+        // hyphen, exactly as a break inside a word does. Only when `glued` - the next piece follows with no
+        // space between; a line that breaks at a space ends there, and the soft hyphen stays invisible.
+        let lastIndex = segs.length - 1;
+        while (lastIndex >= 0 && segs[lastIndex].content === "")
+            lastIndex--;
+        const last = segs[lastIndex];
+        if (glued &&
+            last?.content.endsWith(SOFT_HYPHEN) &&
+            !withoutSoftHyphens(last.content).endsWith("-")) {
+            const font = {
+                fontFamily: last.fontFamily || defaults.fontFamily,
+                fontSize: last.fontSize || defaults.fontSize,
+                fontStyle: last.fontStyle || defaults.fontStyle,
+                ligatures: defaults.ligatures,
+            };
+            width += runAdvance(metrics, HYPHEN, font, last.letterSpacing ?? defaults.letterSpacing ?? 0);
+            segs = segs.map((seg, i) => i === lastIndex ? { ...seg, content: withoutSoftHyphens(seg.content) + HYPHEN } : seg);
+            ends = "hyphen";
+        }
+        // The spaces the line ends in hang: not drawn, and `width` (the ink) already stops before them.
+        for (let i = segs.length - 1; i >= 0; i--) {
+            const kept = segs[i].content.replace(TRAILING_SPACES, "");
+            if (kept !== segs[i].content)
+                segs = segs.map((seg, j) => (j === i ? { ...seg, content: kept } : seg));
+            if (kept !== "")
+                break;
+        }
+        // Soft hyphens leave the line here - a blank line's piece included.
+        const stripped = segs.map((seg) => seg.content.includes(SOFT_HYPHEN)
+            ? { ...seg, content: withoutSoftHyphens(seg.content) }
+            : seg);
+        const drawn = stripped.filter((seg) => seg.content !== "");
+        lines.push({
+            segments: drawn.length > 0 ? drawn : stripped.slice(0, 1),
+            width,
+            start: lineStart,
+            end: ends,
+        });
+    };
+    // Where each piece of the line begins in the source: a word that runs across a span boundary can move
+    // to the next line together with its earlier part, which then starts that line in an earlier span.
+    const origin = new WeakMap();
+    const started = (piece, from) => {
+        origin.set(piece, from);
+        return piece;
+    };
+    /** The width and ink of `pieces`, summed exactly as `placeWord` builds a line: word by word, a space
+     *  joining the words inside a piece, nothing between pieces. */
+    const measure = (pieces) => {
+        let total = 0;
+        let ink = 0;
+        let open = false;
+        for (const piece of pieces) {
+            const font = {
+                fontFamily: piece.fontFamily || defaults.fontFamily,
+                fontSize: piece.fontSize || defaults.fontSize,
+                fontStyle: piece.fontStyle || defaults.fontStyle,
+                ligatures: defaults.ligatures,
+            };
+            const spacing = piece.letterSpacing ?? defaults.letterSpacing ?? 0;
+            const space = runAdvance(metrics, " ", font, spacing) + wordSpacing;
+            piece.content.split(" ").forEach((word, i) => {
+                total = total + ((open && i > 0 ? space : 0) + runAdvance(metrics, word, font, spacing));
+                open = true;
+                if (word !== "")
+                    ink = total;
+            });
+        }
+        return { width: total, ink };
+    };
+    /**
+     * The line is full and the next word follows the line's last piece with NO space: it continues a word
+     * that began in an earlier span (`span("Rech") + span("nung")`). A span boundary is no break
+     * opportunity, so the break belongs at the last one before that word - a space, or a hyphen or soft
+     * hyphen ending a span - and the word's earlier part moves down with it. `null`: the line has none
+     * before it, and the word stays, as the same text in one string would.
+     */
+    const gluedTail = (next, afterSpace) => {
+        const pieces = lineSegments.slice(0, -1); // the last is the current span's own, still empty
+        const moved = [];
+        let following = next;
+        const inks = (keep) => keep.some((p) => withoutSoftHyphens(p.content).trim() !== "");
+        if (afterSpace)
+            return inks(pieces) ? { keep: pieces, moved, hyphen: false } : null;
+        for (let i = pieces.length - 1; i >= 0; i--) {
+            const piece = pieces[i];
+            const c = piece.content;
+            const soft = c.endsWith(SOFT_HYPHEN);
+            if (c.endsWith(" ") || soft || (c.endsWith("-") && !/^\d/.test(following))) {
+                const keep = pieces.slice(0, i + 1);
+                return inks(keep)
+                    ? { keep, moved, from: moved[0] && origin.get(moved[0]), hyphen: soft }
+                    : null;
+            }
+            const space = c.lastIndexOf(" ");
+            if (space >= 0) {
+                const from = origin.get(piece);
+                const head = started({ ...piece, content: c.slice(0, space + 1) }, from);
+                const tail = started({ ...piece, content: c.slice(space + 1) }, { segment: from.segment, offset: from.offset + space + 1 });
+                const keep = [...pieces.slice(0, i), head];
+                return inks(keep)
+                    ? { keep, moved: [tail, ...moved], from: origin.get(tail), hyphen: false }
+                    : null;
+            }
+            moved.unshift(piece);
+            following = c + following;
+        }
+        return null;
+    };
+    segments.forEach((segment, segmentIndex) => {
         const family = segment.fontFamily || defaults.fontFamily;
         const size = segment.fontSize || defaults.fontSize;
         const style = segment.fontStyle || defaults.fontStyle;
@@ -152,109 +205,242 @@ export function breakSegmentsIntoLines(segments, defaults, maxWidth, metrics, ma
             fontStyle: style,
             ligatures: defaults.ligatures,
         };
-        const spaceWidth = runAdvance(metrics, " ", font, letterSpacing);
-        // A `\n` inside a span is a HARD break, exactly as in the string path: close the line where it
-        // sits, whatever else was already on it, and start the next one with this segment's style.
+        const spaceWidth = runAdvance(metrics, " ", font, letterSpacing) + wordSpacing;
+        const at = (offset) => ({ segment: segmentIndex, offset });
+        // A `\n` is a HARD break: close the line where it sits, whatever else was already on it, and start
+        // the next one with this segment's style. An EMPTY paragraph still makes a line, or a deliberate
+        // blank line between two blocks silently disappears.
+        let paragraphStart = 0;
         segment.content.split("\n").forEach((paragraph, paragraphIndex) => {
             if (paragraphIndex > 0) {
-                lines.push({ segments: lineSegments, width });
+                close(lineSegments, ink, "hard");
                 width = 0;
+                gaps = 0;
+                open = false;
+                inked = false;
+                ink = 0;
+                hung = false;
                 lineSegments = [];
+                lineStart = at(paragraphStart);
             }
             const words = paragraph.split(" ");
+            let wordStart = paragraphStart;
             // Start this segment's piece empty; its content is filled word-by-word below. (Not
             // the original content - otherwise a segment whose FIRST word overflows would carry
             // its whole text into the line that just closed.)
-            lineSegments.push({ ...segment, fontFamily: family, content: "" });
+            lineSegments.push(started({ ...segment, fontFamily: family, content: "" }, at(paragraphStart)));
             combined = "";
-            words.forEach((word, wordIndex) => {
+            /** Close the line before a word whose earlier part (`glued.moved`) moves down with it. */
+            const carryOver = (glued, wordAt) => {
+                close(glued.keep, measure(glued.keep).ink, "soft", glued.hyphen);
+                const carried = measure(glued.moved);
+                lineSegments = [
+                    ...glued.moved,
+                    started({ ...segment, fontFamily: family, content: "" }, at(wordAt)),
+                ];
+                combined = "";
+                lineStart = glued.from;
+                width = carried.width;
+                ink = carried.ink;
+                gaps = 0;
+                open = true;
+                inked = true;
+            };
+            // One word, placed at source offset `wordAt`; `joined`: a space joins it to the word before.
+            const placeWord = (word, wordAt, joined) => {
+                const afterSpace = hung;
+                hung = false;
+                // The space before this word hung past the edge, so the line is full: the word starts the next
+                // one. It must not slip in behind the space it was written after, however narrow it is.
+                if (afterSpace && inked && word !== "") {
+                    close(lineSegments, ink, "soft");
+                    lineSegments = [started({ ...segment, fontFamily: family, content: "" }, at(wordAt))];
+                    combined = "";
+                    width = 0;
+                    gaps = 0;
+                    open = false;
+                    inked = false;
+                    ink = 0;
+                    lineStart = at(wordAt);
+                }
+                // Only a word that follows something on this line is joined to it by the space.
+                const joins = open && joined;
                 const wordWidth = runAdvance(metrics, word, font, letterSpacing);
-                // Same treatment as the string path: a word too wide for the box is split into pieces that fit.
-                // Each finished piece closes the line it sits on, keeping this segment's style.
-                const split = splitLongWord(word, maxWidth, font, metrics, letterSpacing, defaults.splitting ?? {});
+                // CSS `text-indent`: the FIRST line has the indent taken out of its room; the pieces of a split
+                // word land on the first line only when it is still empty.
+                const room = lines.length === 0 ? maxWidth - indent : maxWidth;
+                // How much a JUSTIFIED line may be squeezed to keep one more word: the spaces already on the
+                // line plus the one that would join it, each giving up at most `shrink` of its width. Zero for
+                // every other alignment, where a squeezed line would simply overflow instead.
+                const squeeze = (gaps + (joins ? 1 : 0)) * spaceWidth * shrink;
+                // A hyphen inside the word is a break opportunity, taken only when the whole word does not fit
+                // here - the same test, squeeze included, as below.
+                const fitsHere = (w) => !open ? w <= room : width + ((joins ? spaceWidth : 0) + w) - squeeze <= room;
+                const breaks = mayBreak(word) ? hyphenBreaks(word) : NO_BREAKS;
+                if (breaks.length > 0 && !fitsHere(wordWidth)) {
+                    const freshLine = (startAt) => {
+                        lineSegments = [started({ ...segment, fontFamily: family, content: "" }, at(startAt))];
+                        combined = "";
+                        width = 0;
+                        gaps = 0;
+                        open = false;
+                        inked = false;
+                        ink = 0;
+                        lineStart = at(startAt);
+                    };
+                    let head = 0;
+                    for (const k of breaks) {
+                        if (!fitsHere(runAdvance(metrics, headAt(word, k), font, letterSpacing)))
+                            break;
+                        head = k;
+                    }
+                    if (head > 0) {
+                        const part = headAt(word, head);
+                        const joiner = joins ? spaceWidth : 0;
+                        if (!open)
+                            lineStart = at(wordAt);
+                        width += joiner + runAdvance(metrics, part, font, letterSpacing);
+                        ink = width;
+                        combined += joins ? " " + part : part;
+                        if (lineSegments.length === 0)
+                            lineSegments.push(started({ ...segment, fontFamily: family, content: "" }, at(wordAt)));
+                        lineSegments[lineSegments.length - 1].content = combined;
+                        close(lineSegments, ink, endAt(word, head));
+                        freshLine(wordAt + head);
+                        placeWord(word.slice(head), wordAt + head, false);
+                        return;
+                    }
+                    if (inked) {
+                        const glued = joined ? undefined : gluedTail(word, afterSpace);
+                        if (glued && glued.moved.length > 0) {
+                            carryOver(glued, wordAt);
+                            placeWord(word, wordAt, false);
+                            return;
+                        }
+                        if (glued !== null) {
+                            close(lineSegments, ink, "soft", !joined);
+                            freshLine(wordAt);
+                            placeWord(word, wordAt, false);
+                            return;
+                        }
+                    }
+                    placeWord(headAt(word, breaks[0]), wordAt, joined);
+                    close(lineSegments, ink, endAt(word, breaks[0]));
+                    freshLine(wordAt + breaks[0]);
+                    placeWord(word.slice(breaks[0]), wordAt + breaks[0], false);
+                    return;
+                }
+                const splitRoom = lines.length === 0 && !open ? room : maxWidth;
+                // A word too wide for the box is split into pieces that fit (hyphenation first, break-word as
+                // the floor). Each finished piece closes the line it sits on, keeping this segment's style. Off
+                // by default, so a document that asks for neither never gets here.
+                const split = splitLongWord(word, splitRoom, font, metrics, letterSpacing, defaults.splitting ?? {});
                 if (split) {
-                    // Close whatever is already on the line FIRST. The pieces were measured against the full box,
-                    // not against what is left of this line - appending the first one put a line 80 wide into a
-                    // 50 box, and reported 50, which is exactly why it went unnoticed. The string path has always
-                    // pushed its current line before splitting; this is the same move.
-                    if (width > 0) {
-                        lines.push({ segments: lineSegments, width });
-                        lineSegments = [{ ...segment, fontFamily: family, content: "" }];
+                    // Close whatever is already on the line FIRST: the pieces were measured against the full box,
+                    // not against what is left of this line.
+                    if (inked) {
+                        close(lineSegments, ink, "soft", !joined);
+                        lineSegments = [started({ ...segment, fontFamily: family, content: "" }, at(wordAt))];
                         combined = "";
                     }
+                    // Each piece starts where the source text of the previous one ended.
+                    let pieceAt = wordAt;
                     for (const piece of split.slice(0, -1)) {
-                        lineSegments[lineSegments.length - 1].content = piece;
+                        lineSegments[lineSegments.length - 1].content = piece.text;
+                        lineStart = at(pieceAt);
                         // The width a line REPORTS is what alignment and line-metrics work from: measure it.
-                        lines.push({
-                            segments: lineSegments,
-                            width: runAdvance(metrics, piece, font, letterSpacing),
-                        });
-                        lineSegments = [{ ...segment, fontFamily: family, content: "" }];
+                        close(lineSegments, runAdvance(metrics, piece.text, font, letterSpacing), piece.hyphen ? "hyphen" : "split");
+                        pieceAt += piece.source;
+                        lineSegments = [started({ ...segment, fontFamily: family, content: "" }, at(pieceAt))];
                     }
-                    combined = split[split.length - 1];
+                    lineStart = at(pieceAt);
+                    combined = split[split.length - 1].text;
                     width = runAdvance(metrics, combined, font, letterSpacing);
+                    gaps = 0;
+                    open = true;
+                    inked = true;
+                    ink = width;
                     lineSegments[lineSegments.length - 1].content = combined;
                     return;
                 }
                 // A space joins this word to what precedes it only INSIDE a segment; segments butt together
                 // with nothing between them, which is what `span("a") + span("b")` draws.
-                const joiner = wordIndex > 0 ? spaceWidth : 0;
+                const joiner = joins ? spaceWidth : 0;
                 // ONE expression for the test and for the running total, grouped exactly as `singleLineWidth`
                 // groups it - see the note there. A width built any other way can be a bit off the one the box
                 // was sized with, and the text wraps inside a box made to hold it.
                 const candidate = width + (joiner + wordWidth);
-                // Same guard as the string path: don't open a phantom empty line for an over-wide first word -
-                // place it (overflowing) on the current empty line instead.
-                if (candidate > maxWidth && width > 0) {
-                    lines.push({ segments: lineSegments, width });
-                    width = wordWidth;
-                    lineSegments = [];
-                    combined = word;
-                    lineSegments.push({ ...segment, content: combined });
-                }
-                else {
-                    combined += wordIndex === 0 ? word : " " + word;
-                    width = candidate;
-                    if (lineSegments.length === 0) {
-                        lineSegments.push({ ...segment, fontFamily: family, content: combined });
+                // Break before a word that won't fit - counting the space that would join it. A word wider than
+                // the whole box still sits on its (empty) line and overflows, rather than pushing a phantom
+                // empty line before it.
+                if (candidate - squeeze > room && inked) {
+                    // A space that does not fit hangs past the edge, as in CSS. Closing the line on it would end
+                    // the paragraph's last line "soft" (stretched when justified) or push a blank line before `\n`.
+                    if (word === "") {
+                        hung = true;
+                        return;
                     }
-                    lineSegments[lineSegments.length - 1].content = combined;
+                    const glued = joined ? undefined : gluedTail(word, afterSpace);
+                    if (glued && glued.moved.length > 0) {
+                        carryOver(glued, wordAt);
+                        placeWord(word, wordAt, false);
+                        return;
+                    }
+                    // `null`: nowhere to break before this word - it stays on the line, below.
+                    if (glued !== null) {
+                        close(lineSegments, ink, "soft", !joined);
+                        lineStart = at(wordAt);
+                        width = wordWidth;
+                        gaps = 0;
+                        ink = wordWidth;
+                        inked = true;
+                        lineSegments = [];
+                        combined = word;
+                        lineSegments.push(started({ ...segment, content: combined }, at(wordAt)));
+                        return;
+                    }
+                }
+                combined += joins ? " " + word : word;
+                width = candidate;
+                if (joins)
+                    gaps += 1;
+                open = true;
+                if (word !== "") {
+                    ink = width;
+                    inked = true;
+                }
+                if (lineSegments.length === 0) {
+                    lineSegments.push(started({ ...segment, fontFamily: family, content: combined }, at(wordAt)));
                 }
+                lineSegments[lineSegments.length - 1].content = combined;
+            };
+            words.forEach((word, wordIndex) => {
+                const wordAt = wordStart;
+                wordStart += word.length + 1;
+                placeWord(word, wordAt, wordIndex > 0);
             });
+            paragraphStart += paragraph.length + 1;
         });
     });
-    // Only if something actually landed on it. The string path ends with `if (currentLine)`, so a text
-    // ending in `\n` is ONE line there - the two must not disagree about the same text. An empty
-    // paragraph in the MIDDLE still becomes a line; that one is pushed at the break, not here.
+    // Only if something actually landed on it: a text ending in `\n` is ONE line. An empty paragraph in
+    // the MIDDLE still becomes a line; that one is pushed at the break, not here.
     if (lineSegments.some((seg) => seg.content !== "")) {
-        lines.push({ segments: lineSegments, width });
+        close(lineSegments, ink, "end");
     }
     // Open-end by default; cap only when maxLines is set.
-    if (maxLines == null || lines.length <= maxLines)
-        return lines;
-    const kept = lines.slice(0, maxLines);
-    if (overflow === "ellipsis")
-        ellipsizeSegmentLine(kept[kept.length - 1], defaults, maxWidth, metrics);
-    return kept;
-}
-/**
- * Inverse of `breakSegmentsIntoLines`: flatten broken lines back into a `TextSegment[]`
- * that re-wraps to exactly those lines. The wrap consumed the space at each line break,
- * so re-insert one between lines (unless the piece already ends with one) - otherwise the
- * last word of a line and the first of the next would fuse ("a b" + "c d" -> "a bc d").
- * Used by text fragmentation to rebuild the fitted/remainder halves of a split paragraph.
- */
-export function segmentLinesToSegments(lines) {
-    const result = [];
-    lines.forEach((line, lineIndex) => {
-        line.segments.forEach((segment) => result.push({ ...segment }));
-        if (lineIndex < lines.length - 1) {
-            const last = result[result.length - 1];
-            if (last && !last.content.endsWith(" "))
-                last.content += " ";
+    let kept = lines;
+    if (maxLines != null && lines.length > maxLines) {
+        // The text ends at the cap, as far as this element goes: its last line is not a wrapped one.
+        kept = lines.slice(0, maxLines);
+        kept[kept.length - 1] = { ...kept[kept.length - 1], end: "end" };
+        if (overflow === "ellipsis") {
+            // The same room that line was broken against: the first one lost the indent to it.
+            const room = kept.length === 1 ? maxWidth - indent : maxWidth;
+            ellipsizeLine(kept[kept.length - 1], defaults, room, metrics);
         }
-    });
-    return result;
+    }
+    // A piece of a paragraph split across pages draws only its own lines.
+    return defaults.shownLines === undefined ? kept : kept.slice(0, defaults.shownLines);
 }
 /** Appends "…" to a single line, dropping trailing words (then characters) until the line plus the
  *  ellipsis fits `maxWidth`. Falls back to a bare "…" if not even one character fits. */
@@ -282,22 +468,24 @@ function ellipsize(line, fontFamily, fontSize, fontStyle, maxWidth, metrics, let
     }
     return ELLIPSIS;
 }
-/** Ellipsizes the LAST segment of a truncated segment line in place (within the width left by the
- *  segments before it) and recomputes the line width. */
-function ellipsizeSegmentLine(line, defaults, maxWidth, metrics) {
+/** Ellipsizes the LAST segment of a truncated line in place (within the width left by the segments
+ *  before it) and recomputes the line width. */
+function ellipsizeLine(line, defaults, maxWidth, metrics) {
     const segs = line.segments;
     if (segs.length === 0)
         return;
     const lsOf = (seg) => seg.letterSpacing ?? defaults.letterSpacing ?? 0;
-    const widthOf = (seg) => runAdvance(metrics, seg.content, {
+    // Summed word by word, as the breaker sums a line - one owner for a line's width.
+    const widthOf = (seg) => singleLineWidth(seg.content, {
         fontFamily: seg.fontFamily || defaults.fontFamily,
         fontSize: seg.fontSize || defaults.fontSize,
         fontStyle: seg.fontStyle || defaults.fontStyle,
-    }, lsOf(seg));
+        ligatures: defaults.ligatures,
+    }, metrics, lsOf(seg), defaults.wordSpacing);
     let prefix = 0;
     for (let i = 0; i < segs.length - 1; i++)
         prefix += widthOf(segs[i]);
     const last = segs[segs.length - 1];
-    last.content = ellipsize(last.content, last.fontFamily || defaults.fontFamily, last.fontSize || defaults.fontSize, last.fontStyle || defaults.fontStyle, maxWidth - prefix, metrics, lsOf(last));
+    last.content = ellipsize(last.content, last.fontFamily || defaults.fontFamily, last.fontSize || defaults.fontSize, last.fontStyle || defaults.fontStyle, maxWidth - prefix, metrics, lsOf(last), defaults.wordSpacing, defaults.ligatures);
     line.width = prefix + widthOf(last);
 }