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

package/dist/text/advance.js

@@ -0,0 +1,45 @@
+/**
+ * How wide a run of text is: the horizontal counterpart to `line-metrics.ts` (how tall a line is)
+ * and `line-breaker.ts` (where a line breaks). The ONE canonical answer to "how far does the pen
+ * move", so measuring and drawing can never disagree about it.
+ *
+ * An advance has three parts, each with its own PDF mechanism:
+ *
+ *     advance = sum(glyph widths)  +  sum(kerning)  +  n * letterSpacing
+ *                  /Widths             TJ array          Tc
+ *
+ * `letterSpacing` is added after EVERY code point, the last one included - exactly what the `Tc`
+ * operator does, and exactly what CSS `letter-spacing` does (which is why right-aligned spaced text
+ * looks a hair offset: a spacing hangs off the final glyph). Measuring `(n - 1)` spacings while `Tc`
+ * applies `n` would make every line draw one spacing wider than it was wrapped - text out of its box.
+ *
+ * Kerning is added ONLY when the document has it on (`metrics.kerningEnabled`), and then the backend
+ * emits a `TJ` with the same per-pair adjustments - so a measured advance always equals the drawn
+ * one. With kerning off, `getStringWidth` is the whole advance (its plain glyph sum), byte-identical
+ * to before. Folding kerning into the measurement while the output ignored it was the 2026-07-10 bug.
+ */
+/** Number of Unicode code points (not UTF-16 units): an astral char is ONE, so it takes one
+ *  letter-spacing, not two. Matches how `getStringWidth` iterates. */
+export function codePointCount(text) {
+    let n = 0;
+    for (const _ of text)
+        n++;
+    return n;
+}
+/** The advance of `text` in points: the plain glyph widths, plus kerning (if the document has it on),
+ *  plus one `letterSpacing` per code point. */
+export function runAdvance(metrics, text, font, letterSpacing = 0) {
+    let advance = metrics.getStringWidth(text, font.fontFamily, font.fontSize, font.fontStyle);
+    if (letterSpacing !== 0) {
+        // Per DRAWN glyph, which is what `Tc` applies to; only a ligature makes that differ.
+        const glyphs = metrics.shapedGlyphCount?.(text, font.fontFamily, font.fontStyle) ?? codePointCount(text);
+        advance += glyphs * letterSpacing;
+    }
+    if (metrics.kerningEnabled) {
+        let units = 0;
+        for (const k of metrics.getKernPairs(text, font.fontFamily, font.fontStyle))
+            units += k;
+        advance += (units / 1000) * font.fontSize; // kern units are em/1000
+    }
+    return advance;
+}

package/dist/text/arabic.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Arabic (and Syriac / N'Ko / Adlam) JOINING: which of the four positional forms each letter takes -
+ * the half of shaping Unicode owns. Runs on the LOGICAL string.
+ *
+ * Name the SIDES, not the neighbours: a letter is joined on its right when the preceding one can join
+ * forwards (type D or L), on its left when the following one can join backwards (D or R). Thinking in
+ * "previous/next" puts a final form where an initial belongs.
+ */
+export type JoiningType = "D" | "R" | "L" | "C" | "T" | "U";
+/** The four positional forms, named as the OpenType features that realise them. */
+export type JoiningForm = "isol" | "init" | "medi" | "fina";
+/** The joining type of one code point. `U` for everything the table does not mention. */
+export declare function joiningType(codePoint: number): JoiningType;
+/** Whether a run contains anything the joining pass would touch. Cheap, and false for Latin. */
+export declare function needsJoining(codePoints: readonly number[]): boolean;
+/**
+ * The positional form of every code point, or `null` where none applies (space, digit, mark).
+ * `C` (tatweel, ZWJ) counts when deciding a NEIGHBOUR's form but takes none itself.
+ */
+export declare function joiningForms(codePoints: readonly number[]): (JoiningForm | null)[];

package/dist/text/arabic.js

@@ -0,0 +1,101 @@
+/**
+ * Arabic (and Syriac / N'Ko / Adlam) JOINING: which of the four positional forms each letter takes -
+ * the half of shaping Unicode owns. Runs on the LOGICAL string.
+ *
+ * Name the SIDES, not the neighbours: a letter is joined on its right when the preceding one can join
+ * forwards (type D or L), on its left when the following one can join backwards (D or R). Thinking in
+ * "previous/next" puts a final form where an initial belongs.
+ */
+/**
+ * Joining types, from Unicode 17.0.0 `ArabicShaping.txt`, packed as `start,length,type` in hex.
+ * Anything not listed is `U` (non-joining), which is the standard's own default.
+ *
+ * `T` (transparent - combining marks) is mostly NOT in that file: the standard says an unlisted mark
+ * (category Mn/Me/Cf) is transparent, so those ranges are folded in from the character database.
+ */
+const PACKED = "300,6f,5 483,6,5 591,2c,5 5bf,0,5 5c1,1,5 5c4,1,5 5c7,0,5 610,a,5 61c,0,5 620,0,1 622,3,2" +
+    "  626,0,1 627,0,2 628,0,1 629,0,2 62a,4,1 62f,3,2 633,c,1 640,0,4 641,6,1 648,0,2 649,1,1 64b,14,5" +
+    "  66e,1,1 670,0,5 671,2,2 675,2,2 678,f,1 688,11,2 69a,25,1 6c0,0,2 6c1,1,1 6c3,8,2 6cc,0,1" +
+    "  6cd,0,2 6ce,0,1 6cf,0,2 6d0,1,1 6d2,1,2 6d5,0,2 6d6,6,5 6df,5,5 6e7,1,5 6ea,3,5 6ee,1,2 6fa,2,1" +
+    "  6ff,0,1 70f,0,5 710,0,2 711,0,5 712,2,1 715,4,2 71a,3,1 71e,0,2 71f,8,1 728,0,2 729,0,1 72a,0,2" +
+    "  72b,0,1 72c,0,2 72d,1,1 72f,0,2 730,1a,5 74d,0,2 74e,a,1 759,2,2 75c,e,1 76b,1,2 76d,3,1 771,0,2" +
+    "  772,0,1 773,1,2 775,2,1 778,1,2 77a,5,1 7a6,a,5 7ca,20,1 7eb,8,5 7fa,0,4 7fd,0,5 816,3,5 81b,8,5" +
+    "  825,2,5 829,4,5 840,0,2 841,4,1 846,1,2 848,0,1 849,0,2 84a,9,1 854,0,2 855,0,1 856,2,2 859,2,5" +
+    "  860,0,1 862,3,1 867,0,2 868,0,1 869,1,2 870,12,2 883,2,4 886,0,1 889,4,1 88e,0,2 88f,0,1 897,8,5" +
+    "  8a0,9,1 8aa,2,2 8ae,0,2 8af,1,1 8b1,1,2 8b3,5,1 8b9,0,2 8ba,e,1 8ca,17,5 8e3,1c,5 1807,0,1" +
+    "  180a,0,4 1820,58,1 1885,1,5 1887,21,1 18aa,0,1 200d,0,4 a840,31,1 a872,0,3 fe00,f,5 fe20,f,5" +
+    "  10ac0,4,1 10ac5,0,2 10ac7,0,2 10ac9,1,2 10acd,0,3 10ace,4,2 10ad3,3,1 10ad7,0,3 10ad8,4,1" +
+    "  10add,0,2 10ade,2,1 10ae1,0,2 10ae4,0,2 10aeb,3,1 10aef,0,2 10b80,0,1 10b81,0,2 10b82,0,1" +
+    "  10b83,2,2 10b86,2,1 10b89,0,2 10b8a,1,1 10b8c,0,2 10b8d,0,1 10b8e,1,2 10b90,0,1 10b91,0,2" +
+    "  10ba9,3,2 10bad,1,1 10d00,0,3 10d01,20,1 10d22,0,2 10d23,0,1 10ec2,0,2 10ec3,1,1 10ec6,1,1" +
+    "  10f30,2,1 10f33,0,2 10f34,10,1 10f51,2,1 10f54,0,2 10f70,3,1 10f74,1,2 10f76,b,1 10fb0,0,1" +
+    "  10fb2,1,1 10fb4,2,2 10fb8,0,1 10fb9,1,2 10fbb,1,1 10fbd,0,2 10fbe,1,1 10fc1,0,1 10fc2,1,2" +
+    "  10fc4,0,1 10fc9,0,2 10fca,0,1 10fcb,0,3 1e900,43,1 1e94b,0,5";
+const TYPES = ["U", "D", "R", "L", "C", "T"];
+// [start, end, typeIndex] triples, sorted by start - binary searched, so the table costs one lookup.
+const RANGES = PACKED.trim()
+    .split(/\s+/)
+    .map((entry) => {
+    const [start, length, type] = entry.split(",");
+    const from = parseInt(start, 16);
+    return [from, from + parseInt(length, 16), Number(type)];
+});
+/** The joining type of one code point. `U` for everything the table does not mention. */
+export function joiningType(codePoint) {
+    let lo = 0;
+    let hi = RANGES.length - 1;
+    while (lo <= hi) {
+        const mid = (lo + hi) >> 1;
+        const [from, to, type] = RANGES[mid];
+        if (codePoint < from)
+            hi = mid - 1;
+        else if (codePoint > to)
+            lo = mid + 1;
+        else
+            return TYPES[type];
+    }
+    return "U";
+}
+/** Whether a run contains anything the joining pass would touch. Cheap, and false for Latin. */
+export function needsJoining(codePoints) {
+    return codePoints.some((cp) => {
+        const t = joiningType(cp);
+        return t === "D" || t === "R" || t === "L" || t === "C";
+    });
+}
+/**
+ * The positional form of every code point, or `null` where none applies (space, digit, mark).
+ * `C` (tatweel, ZWJ) counts when deciding a NEIGHBOUR's form but takes none itself.
+ */
+export function joiningForms(codePoints) {
+    const types = codePoints.map(joiningType);
+    /** The nearest neighbour that is not transparent - a mark never breaks a join. */
+    const neighbour = (from, step) => {
+        for (let i = from + step; i >= 0 && i < types.length; i += step) {
+            if (types[i] !== "T")
+                return types[i];
+        }
+        return "U";
+    };
+    return types.map((type, i) => {
+        if (type !== "D" && type !== "R" && type !== "L")
+            return null;
+        const before = neighbour(i, -1);
+        const after = neighbour(i, +1);
+        const joinedRight = before === "D" || before === "L" || before === "C";
+        const joinedLeft = after === "D" || after === "R" || after === "C";
+        if (type === "D") {
+            if (joinedRight && joinedLeft)
+                return "medi";
+            if (joinedRight)
+                return "fina";
+            if (joinedLeft)
+                return "init";
+            return "isol";
+        }
+        // R joins only on its right; L (a handful of Syriac letters) only on its left.
+        if (type === "R")
+            return joinedRight ? "fina" : "isol";
+        return joinedLeft ? "init" : "isol";
+    });
+}

package/dist/text/bidi.d.ts

@@ -0,0 +1,33 @@
+export type Direction = "ltr" | "rtl";
+/** A piece of a line, already in the order it is drawn. */
+export interface VisualRun {
+    /** VISUAL order: hand it to the drawing code as it stands, left to right. */
+    text: string;
+    /**
+     * The same characters in LOGICAL order. SHAPING must use this: a letter's form comes from its
+     * neighbours, and reversing swaps them - shaping the visual text gives every letter the wrong form
+     * (measured: a word 8pt too wide). Shape this, then reverse the GLYPHS.
+     */
+    logical: string;
+    /** True when this run came out of right-to-left text - the caller may need it for alignment. */
+    rtl: boolean;
+}
+/** A run that remembers which input piece it came from, so a span keeps its font and colour. */
+export interface AttributedRun<T> extends VisualRun {
+    source: T;
+}
+/** Whether this text could be reordered at all. Cheap, and false for every Latin-only document. */
+export declare const needsBidi: (text: string) => boolean;
+/**
+ * Reorder one LINE of pieces into the runs to draw. The algorithm runs over the pieces JOINED, not
+ * each on its own, or a Hebrew span beside a Latin one would stay in source order. A run ends where
+ * the direction or the source piece changes.
+ *
+ * Line breaking happens before this, in logical order - what UAX #9 prescribes.
+ */
+export declare function visualRunsOf<T>(pieces: {
+    text: string;
+    source: T;
+}[], base?: Direction): AttributedRun<T>[];
+/** The same for one plain string. An empty string still yields one run, or a blank line would vanish. */
+export declare const visualRuns: (text: string, base?: Direction) => VisualRun[];

package/dist/text/bidi.js

@@ -0,0 +1,94 @@
+import bidiFactory from "bidi-js";
+/**
+ * Bidirectional text (UAX #9): one logical line in, the runs to draw left to right out. ORDERING
+ * only - joining letters into shapes is `text/shape.ts`.
+ *
+ * The whole seam to `bidi-js`: nothing outside this file knows it exists, so replacing it with our
+ * own is a change here alone (`todo.md`).
+ */
+const bidi = bidiFactory();
+// Every block whose script runs right to left, plus the explicit bidi control characters. Used only
+// as a fast path: no match and a left-to-right base means the algorithm cannot reorder anything.
+const RTL_OR_CONTROL = /[\u0590-\u08FF\u200F\u202B\u202E\u2067\uFB1D-\uFDFF\uFE70-\uFEFF]|[\uD802\uD803\uD83A\uD83B][\uDC00-\uDFFF]/;
+/** Whether this text could be reordered at all. Cheap, and false for every Latin-only document. */
+export const needsBidi = (text) => RTL_OR_CONTROL.test(text);
+const isHighSurrogate = (c) => c >= "\uD800" && c <= "\uDBFF";
+const isLowSurrogate = (c) => c >= "\uDC00" && c <= "\uDFFF";
+/**
+ * Reorder one LINE of pieces into the runs to draw. The algorithm runs over the pieces JOINED, not
+ * each on its own, or a Hebrew span beside a Latin one would stay in source order. A run ends where
+ * the direction or the source piece changes.
+ *
+ * Line breaking happens before this, in logical order - what UAX #9 prescribes.
+ */
+export function visualRunsOf(pieces, base = "ltr") {
+    const text = pieces.map((p) => p.text).join("");
+    // Verbatim - same count, same order, empty pieces included - so untouched documents stay
+    // byte-identical.
+    if (text === "" || (base === "ltr" && !needsBidi(text))) {
+        return pieces.map((p) => ({ ...p, logical: p.text, rtl: false }));
+    }
+    // Which piece each code unit came from, so a visual run can be traced back to its span.
+    const owner = new Int32Array(text.length);
+    let at = 0;
+    pieces.forEach((piece, index) => {
+        owner.fill(index, at, at + piece.text.length);
+        at += piece.text.length;
+    });
+    const levels = bidi.getEmbeddingLevels(text, base);
+    const order = bidi.getReorderedIndices(text, levels);
+    // `.levels`, NOT the result object the library's README passes: it indexes its argument directly,
+    // and given the object it silently returns an empty map - no bracket ever mirrored.
+    const mirrored = bidi.getMirroredCharactersMap(text, levels.levels);
+    const runs = [];
+    let current = []; // visual order, mirrored
+    let written = []; // the same run as the author wrote it
+    let currentRtl = false;
+    let currentOwner = -1;
+    const flush = () => {
+        if (current.length > 0) {
+            runs.push({
+                text: current.join(""),
+                // Tracked separately rather than un-reversing the visual text: that text has been MIRRORED,
+                // so a bracket would come back as its twin and shaping - and `ToUnicode` after it - would see
+                // a character the author never wrote.
+                logical: (currentRtl ? [...written].reverse() : written).join(""),
+                rtl: currentRtl,
+                source: pieces[currentOwner].source,
+            });
+            current = [];
+            written = [];
+        }
+    };
+    for (let k = 0; k < order.length; k++) {
+        const i = order[k];
+        const rtl = (levels.levels[i] & 1) === 1;
+        if (rtl !== currentRtl || owner[i] !== currentOwner)
+            flush();
+        currentRtl = rtl;
+        currentOwner = owner[i];
+        // A surrogate pair is two code units at one level, so reversing splits an astral character (an
+        // emoji in Hebrew text) into two broken halves. They arrive adjacent and swapped.
+        const next = k + 1 < order.length ? order[k + 1] : -1;
+        if (isLowSurrogate(text[i]) && next === i - 1 && isHighSurrogate(text[next])) {
+            current.push(text[next], text[i]);
+            written.push(text[next], text[i]);
+            k++;
+            continue;
+        }
+        current.push(mirrored.get(i) ?? text[i]);
+        written.push(text[i]);
+    }
+    flush();
+    return runs;
+}
+/** The same for one plain string. An empty string still yields one run, or a blank line would vanish. */
+export const visualRuns = (text, base = "ltr") => {
+    if (text === "")
+        return [{ text, logical: text, rtl: false }];
+    return visualRunsOf([{ text, source: null }], base).map(({ text: t, logical, rtl }) => ({
+        text: t,
+        logical,
+        rtl,
+    }));
+};

package/dist/text/emoji-codepoints.d.ts

@@ -0,0 +1 @@
+export declare function isEmojiCodePoint(codePoint: number): boolean;

package/dist/text/emoji-codepoints.js

@@ -0,0 +1,29 @@
+// Whether a code point is (very likely) an emoji, used ONLY by the image/CDN emoji source: unlike a
+// font source, there is no font to ask "do you have a color glyph for this?", so we decide from the
+// well-known emoji blocks. This is a curated, dependency-free subset - it covers the emoji people
+// actually type, not the full Unicode Emoji property list, and intentionally errs toward the common
+// blocks. A font source does NOT use this (it asks the font).
+// [lo, hi] inclusive ranges of the main emoji / pictograph blocks.
+const RANGES = [
+    [0x1f000, 0x1faff], // Mahjong/Dominoes/Cards, Misc Symbols & Pictographs, Emoticons, Transport,
+    //                     Supplemental Symbols & Pictographs, Symbols & Pictographs Extended-A (incl. flags)
+    [0x2190, 0x21ff], // Arrows
+    [0x2300, 0x23ff], // Misc Technical (⌚ ⏰ ⏳, media controls)
+    [0x2460, 0x24ff], // Enclosed Alphanumerics (Ⓜ)
+    [0x25a0, 0x25ff], // Geometric Shapes (▪ ◼ ⬛)
+    [0x2600, 0x27bf], // Misc Symbols + Dingbats (☀ ★ ✂ ✅ ✈ ✉ ✊ ✋)
+    [0x2900, 0x297f], // Supplemental Arrows-B (⤴ ⤵)
+    [0x2b00, 0x2bff], // Misc Symbols and Arrows (⭐ ⬅ ⬛)
+    [0x3000, 0x303f], // CJK Symbols and Punctuation (〰 〽)
+    [0x3200, 0x32ff], // Enclosed CJK Letters and Months (㊗ ㊙)
+];
+// Emoji-presentation singletons outside the ranges above.
+const SINGLES = new Set([0x00a9, 0x00ae, 0x203c, 0x2049, 0x2122, 0x2139, 0xfe0f]);
+export function isEmojiCodePoint(codePoint) {
+    if (SINGLES.has(codePoint))
+        return true;
+    for (const [lo, hi] of RANGES)
+        if (codePoint >= lo && codePoint <= hi)
+            return true;
+    return false;
+}

package/dist/text/font-fallback.d.ts

@@ -0,0 +1,25 @@
+import type { FontStyle } from "../utils/pdf-object-manager.js";
+import type { FontMetrics } from "../utils/font-metrics.js";
+/**
+ * Font FALLBACK: picking, per code point, the first family in a stack that can draw it.
+ *
+ * `Text({ font: ["Inter", "NotoSansCJK"] })` should just work for mixed-script text. Without this a
+ * code point the first family lacks comes out as `.notdef` - the empty box.
+ *
+ * The output is a list of pieces, each in ONE family, which is exactly the shape a styled `span`
+ * already has. So the fallback reuses the whole segment machinery - breaking, bidi, shaping and
+ * drawing all handle per-piece fonts already - instead of adding a second one beside it.
+ */
+/** A stretch of text that one family can draw. */
+export interface FontRun {
+    text: string;
+    fontFamily: string;
+}
+/**
+ * Split `text` into runs by family. Returns `undefined` when there is nothing to split - no stack, or
+ * the first family draws everything - so a document that never asks for a fallback keeps its old path.
+ *
+ * A code point that NO family in the stack can draw stays with the first one, which then draws its
+ * `.notdef`. That is what a browser does too: the fallback chain ends, and the missing glyph shows.
+ */
+export declare function splitByFont(text: string, fontFamily: string, fallback: readonly string[], fontStyle: FontStyle, metrics: FontMetrics): FontRun[] | undefined;

package/dist/text/font-fallback.js

@@ -0,0 +1,38 @@
+/**
+ * Split `text` into runs by family. Returns `undefined` when there is nothing to split - no stack, or
+ * the first family draws everything - so a document that never asks for a fallback keeps its old path.
+ *
+ * A code point that NO family in the stack can draw stays with the first one, which then draws its
+ * `.notdef`. That is what a browser does too: the fallback chain ends, and the missing glyph shows.
+ */
+export function splitByFont(text, fontFamily, fallback, fontStyle, metrics) {
+    if (fallback.length === 0)
+        return undefined;
+    const familyFor = (codePoint) => {
+        if (metrics.hasGlyph(codePoint, fontFamily, fontStyle))
+            return fontFamily;
+        for (const family of fallback) {
+            if (metrics.hasGlyph(codePoint, family, fontStyle))
+                return family;
+        }
+        return fontFamily; // nobody has it - the first family shows the missing glyph
+    };
+    const runs = [];
+    let current = "";
+    let currentFamily = fontFamily;
+    for (const ch of text) {
+        const family = familyFor(ch.codePointAt(0));
+        if (current !== "" && family !== currentFamily) {
+            runs.push({ text: current, fontFamily: currentFamily });
+            current = "";
+        }
+        currentFamily = family;
+        current += ch;
+    }
+    if (current !== "")
+        runs.push({ text: current, fontFamily: currentFamily });
+    // Nothing substituted - no runs at all (empty text), or one in the family we started with. Say so,
+    // and the caller keeps its cheaper path instead of being handed an empty list to draw.
+    const unchanged = runs.length === 0 || (runs.length === 1 && runs[0].fontFamily === fontFamily);
+    return unchanged ? undefined : runs;
+}

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

@@ -1,18 +1,44 @@
-import type { FontStyle } from "../utils/pdf-object-manager";
-import type { FontMetrics } from "../utils/font-metrics";
-import type { TextSegment } from "../elements/text-element";
+import type { FontStyle } from "../utils/pdf-object-manager.js";
+import type { FontMetrics } from "../utils/font-metrics.js";
+import type { TextSegment } from "../elements/text-element.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 declare const MAX_SPACE_SHRINK: number;
+/** The knobs that change where a line ENDS, beyond the font and the box. */
+export interface LineOptions {
+    /** Extra advance at every space (CSS `word-spacing`), in points. */
+    wordSpacing?: number;
+    /** How far the FIRST line starts in (CSS `text-indent`), in points - it has that much less room. */
+    indent?: number;
+    /** How far a justified line's spaces may be squeezed to keep one more word (0 = not justified). */
+    shrink?: number;
+}
 /** Default font for segments that don't override it. */
 export interface SegmentDefaults {
     fontFamily: string;
     fontSize: number;
     fontStyle: FontStyle;
+    /** Extra space after every glyph, in points; a segment may override it. Default 0. */
+    letterSpacing?: number;
 }
-/** One laid-out line of segments. `maxFontSize` is the tallest font ON THIS LINE - its
- *  leading - matching how real engines (and this lib's plain-string path) space lines. */
+/** What happens to text beyond `maxLines`: `"clip"` drops it, `"ellipsis"` ends the last kept line
+ *  with an ellipsis. Mirrors Flutter's `TextOverflow`. */
+export type TextOverflow = "clip" | "ellipsis";
+/** One laid-out line of segments. How TALL it is does not live here: the breaker owns the horizontal
+ *  half, `text/line-metrics.ts` owns the vertical one and derives the box from the fonts on the line. */
 export interface SegmentLine {
     segments: TextSegment[];
     width: number;
-    maxFontSize: number;
 }
 /**
  * Break a plain string into lines that each fit within `maxWidth`, splitting on
@@ -22,14 +48,26 @@ export interface SegmentLine {
  * rendering call this, so they can never disagree. Depends only on `FontMetrics`,
  * not the PDF byte writer - the future fragmentation pass can reuse it.
  */
-export declare function wrapStringIntoLines(text: string, fontFamily: string, fontSize: number, fontStyle: FontStyle, maxWidth: number, metrics: FontMetrics): string[];
 /**
- * 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.
+ * 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 declare function singleLineWidth(text: string, font: {
+    fontFamily: string;
+    fontSize: number;
+    fontStyle: FontStyle;
+}, metrics: FontMetrics, letterSpacing?: number, wordSpacing?: number): number;
+export declare function wrapStringIntoLines(text: string, fontFamily: string, fontSize: number, fontStyle: FontStyle, maxWidth: number, metrics: FontMetrics, maxLines?: number, overflow?: TextOverflow, letterSpacing?: number, options?: LineOptions): string[];
+/**
+ * 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.
  */
-export declare function breakSegmentsIntoLines(segments: TextSegment[], defaults: SegmentDefaults, maxWidth: number, metrics: FontMetrics): SegmentLine[];
+export declare function breakSegmentsIntoLines(segments: TextSegment[], defaults: SegmentDefaults, maxWidth: number, metrics: FontMetrics, maxLines?: number, overflow?: TextOverflow): SegmentLine[];
 /**
  * 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,