@jasy/pdf 1.0.0-alpha.1 → 1.0.0-alpha.11

package/dist/text/line-breaker.js

@@ -1,8 +1,20 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.wrapStringIntoLines = wrapStringIntoLines;
-exports.breakSegmentsIntoLines = breakSegmentsIntoLines;
-exports.segmentLinesToSegments = segmentLinesToSegments;
+import { runAdvance } from "./advance.js";
+/**
+ * How far a JUSTIFIED line's spaces may be squeezed to keep one more word on it.
+ *
+ * A quarter, because our breaker is GREEDY: it will use the whole allowance every time that saves a
+ * line, so the limit has to be the tightest word space still worth reading - about three quarters of
+ * natural, the usual typographic floor. TeX allows a third, but its badness model rarely spends it.
+ * For reference, react-pdf reaches -19% in practice (measured: a 3.18pt space squeezed to 2.58pt),
+ * which this covers. Its packing can still differ by a word, because it spreads the squeeze over the
+ * CHARACTERS as well as the spaces.
+ *
+ * Only justified text uses it: under any other alignment a squeezed line would simply overflow.
+ */
+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 = "...";
 /**
  * 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).
@@ -11,79 +23,168 @@ exports.segmentLinesToSegments = segmentLinesToSegments;
  * rendering call this, so they can never disagree. Depends only on `FontMetrics`,
  * not the PDF byte writer - the future fragmentation pass can reuse it.
  */
-function wrapStringIntoLines(text, fontFamily, fontSize, fontStyle, maxWidth, metrics) {
+/**
+ * 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
+ * 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.
+ */
+export function singleLineWidth(text, font, metrics, letterSpacing = 0, wordSpacing = 0) {
+    // A hard break makes this several lines; the natural width is the widest of them.
+    if (text.includes("\n"))
+        return Math.max(...text.split("\n").map((p) => singleLineWidth(p, font, metrics, letterSpacing, wordSpacing)));
+    const space = runAdvance(metrics, " ", font, letterSpacing) + wordSpacing;
+    return text
+        .split(" ")
+        .reduce((width, word, i) => i === 0
+        ? runAdvance(metrics, word, font, letterSpacing)
+        : 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 } = 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 words = text.split(" ");
-    words.forEach((word, index) => {
-        const wordWidth = metrics.getStringWidth(word, fontFamily, fontSize, fontStyle);
-        const spaceWidth = metrics.getCharWidth(" ", fontSize, undefined, fontFamily, fontStyle);
-        if (currentWidth + wordWidth > maxWidth) {
+    const font = { fontFamily, fontSize, fontStyle };
+    // 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 = word;
-            currentWidth = wordWidth;
-        }
-        else {
-            currentLine += index === 0 ? word : " " + word;
-            currentWidth += wordWidth + spaceWidth;
+            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).
+            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());
-    return lines;
+    // 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);
+    }
+    return kept;
 }
 /**
- * Break styled segments into lines that fit within `maxWidth`. Same greedy
- * word-splitting as the string breaker, but each line records the tallest font on
- * THAT line as its leading (per-line, not a paragraph-global maximum). Single source
- * of truth: both height measurement and rendering call this.
+ * 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.
  */
-function breakSegmentsIntoLines(segments, defaults, maxWidth, metrics) {
+export function breakSegmentsIntoLines(segments, defaults, maxWidth, metrics, maxLines, overflow) {
     const lines = [];
     let width = 0;
-    let maxFontSize = 0; // per line: starts at 0, grows to the tallest font on the line
     let lineSegments = [];
     let combined = "";
     segments.forEach((segment) => {
         const family = segment.fontFamily || defaults.fontFamily;
         const size = segment.fontSize || defaults.fontSize;
         const style = segment.fontStyle || defaults.fontStyle;
-        const spaceWidth = metrics.getCharWidth(" ", size, undefined, family, style);
-        const words = segment.content.split(" ");
-        // 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(Object.assign(Object.assign({}, segment), { fontFamily: family, content: "" }));
-        combined = "";
-        if (maxFontSize < size)
-            maxFontSize = size;
-        words.forEach((word, wordIndex) => {
-            const wordWidth = metrics.getStringWidth(word, family, size, style);
-            if (width + wordWidth > maxWidth) {
-                lines.push({ segments: lineSegments, width, maxFontSize });
-                // Start the next line; its leading resets to the wrapping segment's size.
+        const letterSpacing = segment.letterSpacing ?? defaults.letterSpacing ?? 0;
+        const font = { fontFamily: family, fontSize: size, fontStyle: style };
+        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.
+        segment.content.split("\n").forEach((paragraph, paragraphIndex) => {
+            if (paragraphIndex > 0) {
+                lines.push({ segments: lineSegments, width });
                 width = 0;
-                maxFontSize = size;
                 lineSegments = [];
-                combined = word;
-                width += wordWidth + spaceWidth;
-                lineSegments.push(Object.assign(Object.assign({}, segment), { content: combined }));
             }
-            else {
-                combined += wordIndex === 0 ? word : " " + word;
-                width += wordWidth + spaceWidth;
-                if (lineSegments.length === 0) {
-                    lineSegments.push(Object.assign(Object.assign({}, segment), { fontFamily: family, content: combined }));
+            const words = paragraph.split(" ");
+            // 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: "" });
+            combined = "";
+            words.forEach((word, wordIndex) => {
+                const wordWidth = runAdvance(metrics, word, font, letterSpacing);
+                // 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;
+                // 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 });
                 }
-                lineSegments[lineSegments.length - 1].content = combined;
-            }
+                else {
+                    combined += wordIndex === 0 ? word : " " + word;
+                    width = candidate;
+                    if (lineSegments.length === 0) {
+                        lineSegments.push({ ...segment, fontFamily: family, content: combined });
+                    }
+                    lineSegments[lineSegments.length - 1].content = combined;
+                }
+            });
         });
     });
-    if (lineSegments.length > 0) {
-        lines.push({ segments: lineSegments, width, maxFontSize });
+    // 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.
+    if (lineSegments.some((seg) => seg.content !== "")) {
+        lines.push({ segments: lineSegments, width });
     }
-    return lines;
+    // 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[]`
@@ -92,10 +193,10 @@ function breakSegmentsIntoLines(segments, defaults, maxWidth, metrics) {
  * 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.
  */
-function segmentLinesToSegments(lines) {
+export function segmentLinesToSegments(lines) {
     const result = [];
     lines.forEach((line, lineIndex) => {
-        line.segments.forEach((segment) => result.push(Object.assign({}, segment)));
+        line.segments.forEach((segment) => result.push({ ...segment }));
         if (lineIndex < lines.length - 1) {
             const last = result[result.length - 1];
             if (last && !last.content.endsWith(" "))
@@ -104,3 +205,48 @@ function segmentLinesToSegments(lines) {
     });
     return result;
 }
+/** 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. */
+function ellipsize(line, fontFamily, fontSize, fontStyle, maxWidth, metrics, letterSpacing = 0, wordSpacing = 0) {
+    const font = { fontFamily, fontSize, fontStyle };
+    // Measured through `singleLineWidth`, so the ellipsised line is judged by the same sum that decides
+    // every other line - word-spacing included.
+    const fits = (s) => singleLineWidth(s + ELLIPSIS, font, metrics, letterSpacing, wordSpacing) <= maxWidth;
+    if (fits(line))
+        return line + ELLIPSIS;
+    const words = line.split(" ");
+    while (words.length > 1) {
+        words.pop();
+        if (fits(words.join(" ")))
+            return words.join(" ") + ELLIPSIS;
+    }
+    // Drop one code point at a time (not one UTF-16 unit) so an astral char is never split into a
+    // lone surrogate. `chars` is the code-point view; rebuild the string from its shrinking prefix.
+    const chars = [...(words[0] ?? "")];
+    while (chars.length > 1) {
+        chars.pop();
+        const single = chars.join("");
+        if (fits(single))
+            return single + ELLIPSIS;
+    }
+    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) {
+    const segs = line.segments;
+    if (segs.length === 0)
+        return;
+    const lsOf = (seg) => seg.letterSpacing ?? defaults.letterSpacing ?? 0;
+    const widthOf = (seg) => runAdvance(metrics, seg.content, {
+        fontFamily: seg.fontFamily || defaults.fontFamily,
+        fontSize: seg.fontSize || defaults.fontSize,
+        fontStyle: seg.fontStyle || defaults.fontStyle,
+    }, lsOf(seg));
+    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));
+    line.width = prefix + widthOf(last);
+}

package/dist/text/line-metrics.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The vertical half of text layout: how tall a line box is, and where its baseline sits.
+ *
+ * One canonical answer, like `line-breaker.ts` is the one canonical answer for the horizontal
+ * half. Measuring (`calculateTextHeight`), fragmenting (`TextElement.fragment`) and drawing
+ * (`TextRenderer._buildRuns`) all call in here, so they can never disagree about a line's height
+ * again - the divergence that produced ISSUE-5.
+ */
+import type { FontStyle } from "../utils/pdf-object-manager.js";
+import type { FontMetrics } from "../utils/font-metrics.js";
+import type { SegmentDefaults, SegmentLine } from "./line-breaker.js";
+/** A font's vertical metrics, as fractions of the em (so they scale by multiplying with fontSize). */
+export interface FontVerticals {
+    /** Distance from the baseline up to the ascender. Positive. */
+    ascent: number;
+    /** Distance from the baseline down to the descender. Positive (unlike the AFM/hhea sign). */
+    descent: number;
+    /** Extra leading the font asks for between two lines. Often 0 for a TrueType face. */
+    lineGap: number;
+}
+/** One font used on a line: its metrics and the size it is set at. */
+export interface LinePart {
+    verticals: FontVerticals;
+    fontSize: number;
+}
+/** A laid-out line box, in points, relative to the top of the box. */
+export interface LineBox {
+    /** Total height of the line box. Lines stack by this. */
+    height: number;
+    /** Distance from the top of the line box down to the baseline. */
+    baseline: number;
+}
+/**
+ * The line box for a set of fonts sharing one line.
+ *
+ * `lineHeight` is a multiplier of the font size, like CSS. Leave it `undefined` for the font's
+ * NATURAL line height (`ascent + descent + lineGap`), which is what CSS calls `line-height: normal`.
+ *
+ * Whatever is left over between the box and the font's content is split evenly above and below
+ * ("half-leading", as CSS and Flutter do), so the glyphs sit centred in their own box. An explicit
+ * `lineHeight` smaller than the content makes the leading negative and the glyphs overflow - again
+ * exactly like CSS, and the author asked for it.
+ */
+export declare function lineBoxFor(parts: LinePart[], lineHeight?: number): LineBox;
+/** The line box of a single-font line (the plain-string path). */
+export declare function lineBoxForString(metrics: FontMetrics, fontFamily: string, fontStyle: FontStyle, fontSize: number, lineHeight?: number): LineBox;
+/** The line box of a mixed-font line: the tallest ascent and the deepest descent on it win, so a
+ *  big or a deep-descending span pushes the whole line apart rather than colliding with it. */
+export declare function lineBoxForSegmentLine(line: SegmentLine, defaults: SegmentDefaults, metrics: FontMetrics, lineHeight?: number): LineBox;

package/dist/text/line-metrics.js

@@ -0,0 +1,57 @@
+/**
+ * The vertical half of text layout: how tall a line box is, and where its baseline sits.
+ *
+ * One canonical answer, like `line-breaker.ts` is the one canonical answer for the horizontal
+ * half. Measuring (`calculateTextHeight`), fragmenting (`TextElement.fragment`) and drawing
+ * (`TextRenderer._buildRuns`) all call in here, so they can never disagree about a line's height
+ * again - the divergence that produced ISSUE-5.
+ */
+/**
+ * The line box for a set of fonts sharing one line.
+ *
+ * `lineHeight` is a multiplier of the font size, like CSS. Leave it `undefined` for the font's
+ * NATURAL line height (`ascent + descent + lineGap`), which is what CSS calls `line-height: normal`.
+ *
+ * Whatever is left over between the box and the font's content is split evenly above and below
+ * ("half-leading", as CSS and Flutter do), so the glyphs sit centred in their own box. An explicit
+ * `lineHeight` smaller than the content makes the leading negative and the glyphs overflow - again
+ * exactly like CSS, and the author asked for it.
+ */
+export function lineBoxFor(parts, lineHeight) {
+    if (parts.length === 0)
+        return { height: 0, baseline: 0 };
+    let ascent = 0;
+    let descent = 0;
+    let gap = 0;
+    let maxFontSize = 0;
+    for (const { verticals, fontSize } of parts) {
+        ascent = Math.max(ascent, verticals.ascent * fontSize);
+        descent = Math.max(descent, verticals.descent * fontSize);
+        gap = Math.max(gap, verticals.lineGap * fontSize);
+        maxFontSize = Math.max(maxFontSize, fontSize);
+    }
+    const content = ascent + descent;
+    const height = lineHeight === undefined ? content + gap : maxFontSize * lineHeight;
+    return { height, baseline: (height - content) / 2 + ascent };
+}
+/** The line box of a single-font line (the plain-string path). */
+export function lineBoxForString(metrics, fontFamily, fontStyle, fontSize, lineHeight) {
+    return lineBoxFor([{ verticals: metrics.getFontVerticals(fontFamily, fontStyle), fontSize }], lineHeight);
+}
+/** The line box of a mixed-font line: the tallest ascent and the deepest descent on it win, so a
+ *  big or a deep-descending span pushes the whole line apart rather than colliding with it. */
+export function lineBoxForSegmentLine(line, defaults, metrics, lineHeight) {
+    const parts = line.segments.map((segment) => {
+        const fontFamily = segment.fontFamily ?? defaults.fontFamily;
+        const fontStyle = segment.fontStyle ?? defaults.fontStyle;
+        return {
+            verticals: metrics.getFontVerticals(fontFamily, fontStyle),
+            fontSize: segment.fontSize ?? defaults.fontSize,
+        };
+    });
+    // A line with no segments still occupies its default font's box (an empty paragraph keeps height).
+    if (parts.length === 0) {
+        return lineBoxForString(metrics, defaults.fontFamily, defaults.fontStyle, defaults.fontSize, lineHeight);
+    }
+    return lineBoxFor(parts, lineHeight);
+}

package/dist/text/orphans-widows.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Orphan and widow control for a paragraph split across a page break.
+ *
+ * An **orphan** is the first line of a paragraph left alone at the bottom of a page; a **widow** is
+ * the last line pushed alone to the top of the next. Both read as mistakes, and neither is prevented
+ * by splitting at line boxes - which is all the fragmenter does on its own.
+ *
+ * This is a correction of the split INDEX, not a second mechanism: the fragmenter works out how many
+ * lines fit, and this decides whether that number is acceptable.
+ */
+/** How many lines must stay behind / must carry over. Both default to 2, the CSS initial value. */
+export interface OrphanWidowRule {
+    orphans: number;
+    widows: number;
+}
+export declare const DEFAULT_ORPHANS = 2;
+export declare const DEFAULT_WIDOWS = 2;
+/**
+ * Correct a line count so the split leaves at least `orphans` lines behind and carries at least
+ * `widows` over. Returns 0 to mean "none of it fits here" - the caller then moves the whole paragraph
+ * on, exactly as it already does when not even one line fits.
+ *
+ * Terminating by construction: every answer is either the natural count, a SMALLER one, or 0. It
+ * never asks for more lines than fit, and the page driver's guard already handles a paragraph that
+ * does not fit on a whole page (it places it anyway rather than looping).
+ */
+export declare function adjustForOrphansWidows(fitted: number, total: number, { orphans, widows }: OrphanWidowRule): number;

package/dist/text/orphans-widows.js

@@ -0,0 +1,53 @@
+/**
+ * Orphan and widow control for a paragraph split across a page break.
+ *
+ * An **orphan** is the first line of a paragraph left alone at the bottom of a page; a **widow** is
+ * the last line pushed alone to the top of the next. Both read as mistakes, and neither is prevented
+ * by splitting at line boxes - which is all the fragmenter does on its own.
+ *
+ * This is a correction of the split INDEX, not a second mechanism: the fragmenter works out how many
+ * lines fit, and this decides whether that number is acceptable.
+ */
+export const DEFAULT_ORPHANS = 2;
+export const DEFAULT_WIDOWS = 2;
+/**
+ * Correct a line count so the split leaves at least `orphans` lines behind and carries at least
+ * `widows` over. Returns 0 to mean "none of it fits here" - the caller then moves the whole paragraph
+ * on, exactly as it already does when not even one line fits.
+ *
+ * Terminating by construction: every answer is either the natural count, a SMALLER one, or 0. It
+ * never asks for more lines than fit, and the page driver's guard already handles a paragraph that
+ * does not fit on a whole page (it places it anyway rather than looping).
+ */
+export function adjustForOrphansWidows(fitted, total, { orphans, widows }) {
+    // Both are LINE COUNTS and end up as a slice index, so anything but a positive whole number is
+    // meaningless: 0 or less silently disables the rule it belongs to, and a fraction would be truncated
+    // somewhere downstream rather than here. Named at the boundary instead.
+    check(orphans, "orphans");
+    check(widows, "widows");
+    if (fitted <= 0)
+        return 0; // nothing fits; the caller decides
+    if (fitted >= total)
+        return total; // no split needed, nothing to protect
+    // NOTE: an explicit "too short to satisfy both ends" rule (total < orphans + widows) sat here and was
+    // removed - it is unreachable. Either fewer lines stay than `orphans` allows, and the next check
+    // returns 0; or at least `orphans` stay, and then fewer than `widows` must carry, so the pull-back
+    // below lands under `orphans` and returns 0 as well. react-pdf spells the case out; we do not need to.
+    //
+    // Fewer lines would stay than an orphan is allowed to be.
+    if (fitted < orphans)
+        return 0;
+    // Fewer lines would carry over than a widow is allowed to be: pull the cut back so exactly `widows`
+    // go over - unless that would leave too few behind, in which case the paragraph moves whole.
+    if (total - fitted < widows) {
+        const pulled = total - widows;
+        return pulled >= orphans ? pulled : 0;
+    }
+    return fitted;
+}
+function check(value, name) {
+    if (!Number.isInteger(value) || value < 1) {
+        throw new Error(`Invalid ${name}: ${value}. It is a number of LINES, so it must be a whole number of at least 1 ` +
+            `(1 means no protection at that end).`);
+    }
+}

package/dist/text/shape.d.ts

@@ -0,0 +1,29 @@
+import type { GsubTable } from "../utils/gsub.js";
+/**
+ * SHAPING: code points in, the glyphs actually drawn out. Where the two halves meet - `arabic.ts`
+ * says WHICH positional form a letter takes, `gsub.ts` says which GLYPH that form is in this font.
+ *
+ * Not a string, because a ligature is one glyph for several code points. `codePoints` carries the
+ * origin so `ToUnicode` can still say what the glyph means.
+ */
+/** One drawn glyph, with the code points it came from. */
+export interface ShapedGlyph {
+    glyph: number;
+    /** Advance in FONT UNITS - the caller scales by fontSize / unitsPerEm, as everywhere else. */
+    advance: number;
+    /** The code points this glyph stands for; more than one only for a ligature. */
+    codePoints: number[];
+}
+/** The little a font has to answer for shaping - deliberately not the whole `TTFParser`. */
+export interface ShapingFont {
+    gsub(): GsubTable | undefined;
+    getGlyphIndex(codePoint: number): number;
+    getAdvanceWidth(glyph: number): number;
+}
+/**
+ * Shape a run, or `undefined` when there is nothing to do - so untouched documents keep their path.
+ *
+ * `rlig` (required ligatures - lam-alef, wrong when drawn apart) but not `liga`, which is
+ * discretionary and would change how existing Latin text looks.
+ */
+export declare function shapeRun(codePoints: readonly number[], font: ShapingFont): ShapedGlyph[] | undefined;

package/dist/text/shape.js

@@ -0,0 +1,67 @@
+import { joiningForms, needsJoining } from "./arabic.js";
+/** The features that realise the four positional forms, in the order a shaper applies them. */
+const FORM_FEATURES = {
+    isol: "isol",
+    init: "init",
+    medi: "medi",
+    fina: "fina",
+};
+/**
+ * Shape a run, or `undefined` when there is nothing to do - so untouched documents keep their path.
+ *
+ * `rlig` (required ligatures - lam-alef, wrong when drawn apart) but not `liga`, which is
+ * discretionary and would change how existing Latin text looks.
+ */
+export function shapeRun(codePoints, font) {
+    if (!needsJoining(codePoints))
+        return undefined;
+    const gsub = font.gsub();
+    if (!gsub || !gsub.hasScript("arab"))
+        return undefined;
+    const forms = joiningForms(codePoints);
+    let glyphs = codePoints.map((cp, i) => {
+        let glyph = font.getGlyphIndex(cp);
+        const form = forms[i];
+        if (form) {
+            // First lookup that covers the glyph wins. A missing `isol` is normal: the plain glyph already
+            // IS that form.
+            for (const lookup of gsub.lookups("arab", FORM_FEATURES[form])) {
+                const substituted = gsub.substituteSingle(lookup, glyph);
+                if (substituted !== null) {
+                    glyph = substituted;
+                    break;
+                }
+            }
+        }
+        return { glyph, advance: font.getAdvanceWidth(glyph), codePoints: [cp] };
+    });
+    glyphs = applyLigatures(glyphs, gsub, font);
+    return glyphs;
+}
+/** Collapse required ligatures, longest match first, carrying every component's code points along. */
+function applyLigatures(glyphs, gsub, font) {
+    const lookups = gsub.lookups("arab", "rlig");
+    if (lookups.length === 0)
+        return glyphs;
+    const ids = glyphs.map((g) => g.glyph);
+    const out = [];
+    for (let i = 0; i < glyphs.length;) {
+        let applied = false;
+        for (const lookup of lookups) {
+            const match = gsub.substituteLigature(lookup, ids, i);
+            if (!match)
+                continue;
+            out.push({
+                glyph: match.glyph,
+                advance: font.getAdvanceWidth(match.glyph),
+                codePoints: glyphs.slice(i, i + match.consumed).flatMap((g) => g.codePoints),
+            });
+            i += match.consumed;
+            applied = true;
+            break;
+        }
+        if (!applied)
+            out.push(glyphs[i++]);
+    }
+    return out;
+}

package/dist/text/text-decoration.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Where an underline and a strikethrough sit, and how thick they are.
+ *
+ * These are GLYPH metrics, and they are deliberately NOT part of `FontVerticals` in
+ * `line-metrics.ts`, which holds LINE metrics. Confusing the two is exactly what produced ISSUE-5:
+ * the AFM's `Ascender` (the height of a `b`) was used to seat a baseline, a job that belongs to the
+ * `FontBBox`. Keep the two kinds of number in two places so they cannot be mixed up again.
+ *
+ * Every number here comes out of the font: the standard-14 AFM header, or a TrueType `post` +
+ * `OS/2` table. Nothing is invented. Verified against `google-chrome --headless --print-to-pdf` on
+ * the same font: Chrome's strikethrough centre lands on `xHeight / 2` (measured 0.260 em vs the
+ * font's 0.262), and its underline stroke with `text-decoration-thickness: from-font` is the font's
+ * `underlineThickness` (0.048 em vs 0.050). Chrome does NOT use the font's underline POSITION - it
+ * has its own offset - so we follow the font there and land within 0.02 em of it.
+ */
+/** A font's decoration metrics, as fractions of the em. */
+export interface FontDecoration {
+    /** Distance BELOW the baseline to the CENTRE of the underline stroke. Positive.
+     *  (The AFM defines it as "the distance from the baseline for centering underlining strokes";
+     *  FreeType reads TrueType's `post.underlinePosition` the same way.) */
+    underlinePosition: number;
+    /** Stroke thickness, used by both the underline and the strikethrough. */
+    underlineThickness: number;
+    /** Height of a lowercase `x` above the baseline. Sets where a strikethrough crosses. */
+    xHeight: number;
+    /** Height of a capital above the baseline. */
+    capHeight: number;
+}
+/** A decoration stroke: the y of its centre line, and how thick it is. Points, engine coords. */
+export interface DecorationStroke {
+    y: number;
+    thickness: number;
+}
+/** The underline for a run whose baseline sits at `baselineY` (engine coords, y grows down). */
+export declare function underlineStroke(decoration: FontDecoration, fontSize: number, baselineY: number): DecorationStroke;
+/**
+ * The strikethrough for a run whose baseline sits at `baselineY`. It crosses at half the x-height,
+ * which is what a browser does and what looks right: through the middle of the lowercase letters,
+ * not through the middle of the capitals.
+ */
+export declare function strikethroughStroke(decoration: FontDecoration, fontSize: number, baselineY: number): DecorationStroke;
+/**
+ * Cuts `[0, runWidth]` at every place the glyphs put ink, leaving the segments an underline should
+ * actually draw. `inkSpans` are x-intervals in points from the start of the run.
+ *
+ * This is CSS `text-decoration-skip-ink`, and it needs the real glyph outlines - so it only works
+ * for an embedded font. Segments narrower than the padding are dropped: a sliver of a line between
+ * two descenders reads as dirt, not as an underline.
+ */
+export declare function skipInkSegments(runWidth: number, inkSpans: Array<[number, number]>, thickness: number): Array<[number, number]>;