@jasy/pdf 1.0.0-alpha.8 → 1.0.0-beta.1

package/dist/svg/xml.js

@@ -0,0 +1,158 @@
+import { SvgParseError } from "./errors.js";
+const ENTITIES = {
+    amp: "&",
+    lt: "<",
+    gt: ">",
+    quot: '"',
+    apos: "'",
+};
+/** The five predefined entities plus numeric references; anything else is left as written. */
+function decodeEntities(text) {
+    if (!text.includes("&"))
+        return text;
+    return text.replace(/&(#x?[0-9a-fA-F]+|[a-zA-Z]+);/g, (whole, body) => {
+        if (body.startsWith("#")) {
+            const code = body.startsWith("#x")
+                ? parseInt(body.slice(2), 16)
+                : parseInt(body.slice(1), 10);
+            return Number.isFinite(code) && code >= 0 && code <= 0x10ffff
+                ? String.fromCodePoint(code)
+                : whole;
+        }
+        return ENTITIES[body] ?? whole;
+    });
+}
+const ATTRIBUTE = /([^\s=/>]+)\s*(?:=\s*("([^"]*)"|'([^']*)'|([^\s"'>]+)))?/g;
+function parseAttributes(text) {
+    const out = {};
+    ATTRIBUTE.lastIndex = 0;
+    let match;
+    while ((match = ATTRIBUTE.exec(text)) !== null) {
+        // A valueless attribute (`hidden`) is its own name, as in HTML; SVG has none, but it must not
+        // swallow the following one.
+        out[match[1]] = decodeEntities(match[3] ?? match[4] ?? match[5] ?? "");
+    }
+    return out;
+}
+/**
+ * Parses a document into its root elements. Text outside an element is dropped, which is what the
+ * whitespace between tags is.
+ *
+ * Mismatched closing tags are tolerated rather than fatal: real exports contain them, browsers
+ * recover, and a logo that draws is worth more than a purist error. An unclosed element simply ends
+ * at the end of the document.
+ */
+/**
+ * The index of the `>` that ends a tag, skipping any inside a quoted attribute value - `d="M0 0>10"`
+ * is legal XML, and a plain `indexOf(">")` would cut the tag in half there.
+ */
+function tagEnd(source, from) {
+    let quote = "";
+    for (let i = from + 1; i < source.length; i++) {
+        const ch = source[i];
+        if (quote) {
+            if (ch === quote)
+                quote = "";
+        }
+        else if (ch === '"' || ch === "'") {
+            quote = ch;
+        }
+        else if (ch === ">") {
+            return i;
+        }
+    }
+    return -1;
+}
+export function parseXml(source) {
+    const roots = [];
+    const stack = [];
+    let i = 0;
+    const push = (node) => {
+        if (stack.length === 0) {
+            if (node.type === "element")
+                roots.push(node);
+        }
+        else {
+            stack[stack.length - 1].children.push(node);
+        }
+    };
+    while (i < source.length) {
+        const open = source.indexOf("<", i);
+        if (open === -1)
+            break;
+        if (open > i) {
+            const raw = source.slice(i, open);
+            if (/\S/.test(raw))
+                push({ type: "text", value: decodeEntities(raw) });
+        }
+        // `<!-- -->`, `<![CDATA[ ]]>`, `<?xml ?>` and `<!DOCTYPE >` are skipped or unwrapped whole.
+        if (source.startsWith("<!--", open)) {
+            const end = source.indexOf("-->", open + 4);
+            i = end === -1 ? source.length : end + 3;
+            continue;
+        }
+        if (source.startsWith("<![CDATA[", open)) {
+            const end = source.indexOf("]]>", open + 9);
+            const value = source.slice(open + 9, end === -1 ? source.length : end);
+            if (value)
+                push({ type: "text", value });
+            i = end === -1 ? source.length : end + 3;
+            continue;
+        }
+        if (source.startsWith("<?", open)) {
+            const end = source.indexOf("?>", open + 2);
+            i = end === -1 ? source.length : end + 2;
+            continue;
+        }
+        if (source.startsWith("<!", open)) {
+            // A doctype may carry an internal subset in brackets, which can itself contain '>'.
+            let depth = 0;
+            let j = open + 2;
+            for (; j < source.length; j++) {
+                const ch = source[j];
+                if (ch === "[")
+                    depth++;
+                else if (ch === "]")
+                    depth--;
+                else if (ch === ">" && depth <= 0)
+                    break;
+            }
+            i = j + 1;
+            continue;
+        }
+        const close = tagEnd(source, open);
+        if (close === -1)
+            break;
+        const inner = source.slice(open + 1, close);
+        if (inner.startsWith("/")) {
+            const name = inner.slice(1).trim();
+            // Close the nearest matching ancestor. A stray closing tag with no match is ignored.
+            const at = stack.map((e) => e.tagName).lastIndexOf(name);
+            if (at !== -1)
+                stack.length = at;
+            i = close + 1;
+            continue;
+        }
+        const selfClosing = inner.trimEnd().endsWith("/");
+        const body = selfClosing ? inner.slice(0, inner.lastIndexOf("/")) : inner;
+        const nameEnd = body.search(/[\s/]/);
+        const tagName = (nameEnd === -1 ? body : body.slice(0, nameEnd)).trim();
+        if (tagName === "") {
+            i = close + 1;
+            continue;
+        }
+        const element = {
+            type: "element",
+            tagName,
+            attributes: nameEnd === -1 ? {} : parseAttributes(body.slice(nameEnd)),
+            children: [],
+        };
+        push(element);
+        if (!selfClosing)
+            stack.push(element);
+        i = close + 1;
+    }
+    if (roots.length === 0)
+        throw new SvgParseError("the file contains no XML elements at all.");
+    return roots;
+}

package/dist/text/advance.d.ts

@@ -25,6 +25,9 @@ export interface RunFont {
     fontFamily: string;
     fontSize: number;
     fontStyle: FontStyle;
+    /** Whether this run gets the font's ligatures. Part of the FONT, because it changes which glyphs are
+     *  drawn and therefore how wide the run is - measuring without it would not match the drawing. */
+    ligatures?: boolean;
 }
 /** 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. */

package/dist/text/advance.js

@@ -29,12 +29,16 @@ export function codePointCount(text) {
 /** 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)
-        advance += codePointCount(text) * letterSpacing;
+    let advance = metrics.getStringWidth(text, font.fontFamily, font.fontSize, font.fontStyle, font.ligatures);
+    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, font.ligatures) ??
+            codePointCount(text);
+        advance += glyphs * letterSpacing;
+    }
     if (metrics.kerningEnabled) {
         let units = 0;
-        for (const k of metrics.getKernPairs(text, font.fontFamily, font.fontStyle))
+        for (const k of metrics.getKernPairs(text, font.fontFamily, font.fontStyle, font.ligatures))
             units += k;
         advance += (units / 1000) * font.fontSize; // kern units are em/1000
     }

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/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/glyph-coverage.d.ts

@@ -0,0 +1,15 @@
+import type { FontMetrics } from "../utils/font-metrics.js";
+import type { FontStyle } from "../utils/pdf-object-manager.js";
+export interface CoverageResult {
+    /** The text as it can actually be drawn. */
+    text: string;
+    /** Code points that had to go - empty for every document that never hits this. */
+    dropped: number[];
+}
+/**
+ * Replaces or removes what `fontFamily` cannot draw. Returns the input unchanged (and no allocation
+ * beyond the scan) when everything is drawable, which is the overwhelmingly common case.
+ */
+export declare function coverText(text: string, fontFamily: string, fontStyle: FontStyle, metrics: FontMetrics): CoverageResult;
+/** `U+2713` - how a dropped code point is named to the caller. */
+export declare function formatCodePoint(cp: number): string;

package/dist/text/glyph-coverage.js

@@ -0,0 +1,77 @@
+/**
+ * A code point the chosen font cannot draw becomes glyph 0 - which IS `.notdef`, and referencing it is
+ * forbidden by PDF/A (ISO 19005-3, 6.2.11.8). So an invoice carrying a "✓" in its description is a
+ * conforming file right up until someone validates it.
+ *
+ * The check has to be DYNAMIC, against the font actually resolved: which characters are missing is a
+ * property of that font, not of Unicode. `@jasy/e-invoice` embeds Liberation, and its gaps look
+ * arbitrary from the outside - "→" draws, "⇒" does not; "₴" draws, "₽" does not.
+ *
+ * What we do about it, in this order:
+ *   1. The font has it        -> keep, untouched. This is every ordinary document, unchanged.
+ *   2. A plain equivalent MEANS the same and the font has THAT -> substitute.
+ *   3. Otherwise              -> drop it, and report it, so the application can say which character
+ *                                went missing instead of shipping a box or a broken file.
+ */
+/**
+ * Substitutes that keep the meaning. Deliberately tiny: only where dropping would CHANGE the text
+ * rather than thin it. `E‑Rechnung` with a non-breaking hyphen must not become `ERechnung`.
+ *
+ * Not a list of "what Word pastes" - most of that (quotes, dashes, the ellipsis) is in WinAnsi and in
+ * every normal font, so it never reaches rule 3. Entries earn their place by being measured, not
+ * guessed: each one is a code point seen missing from a real embedded font.
+ */
+const EQUIVALENTS = {
+    0x2010: "-", // hyphen
+    0x2011: "-", // non-breaking hyphen - the one that turns E‑Rechnung into ERechnung
+    0x2012: "-", // figure dash
+    0x2015: "-", // horizontal bar
+    0x2007: " ", // figure space
+    0x2008: " ", // punctuation space
+    0x2009: " ", // thin space
+    0x200a: " ", // hair space
+    0x202f: " ", // narrow no-break space
+    0x2032: "'", // prime
+    0x2033: '"', // double prime
+    0x02bc: "'", // modifier letter apostrophe
+};
+/**
+ * Replaces or removes what `fontFamily` cannot draw. Returns the input unchanged (and no allocation
+ * beyond the scan) when everything is drawable, which is the overwhelmingly common case.
+ */
+export function coverText(text, fontFamily, fontStyle, metrics) {
+    let out = null; // built only once something has to change
+    const dropped = [];
+    let index = 0;
+    for (const char of text) {
+        const cp = char.codePointAt(0);
+        // A space and a line break are handled by the breaker, never drawn as a glyph.
+        const drawable = cp === 0x20 ||
+            cp === 0x0a ||
+            metrics.hasGlyph(cp, fontFamily, fontStyle) ||
+            // Colour emoji is drawn from a fallback font or an image, NOT from the text font - it is missing
+            // there by design, and removing it would delete the very thing `Document({ emoji })` exists for.
+            metrics.rendersAsEmoji?.(cp, fontFamily, fontStyle) === true;
+        if (!drawable) {
+            if (out === null)
+                out = text.slice(0, index);
+            const equivalent = EQUIVALENTS[cp];
+            if (equivalent !== undefined &&
+                metrics.hasGlyph(equivalent.codePointAt(0), fontFamily, fontStyle)) {
+                out += equivalent;
+            }
+            else {
+                dropped.push(cp);
+            }
+        }
+        else if (out !== null) {
+            out += char;
+        }
+        index += char.length;
+    }
+    return out === null ? { text, dropped } : { text: out, dropped };
+}
+/** `U+2713` - how a dropped code point is named to the caller. */
+export function formatCodePoint(cp) {
+    return "U+" + cp.toString(16).toUpperCase().padStart(4, "0");
+}

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

@@ -1,6 +1,33 @@
 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";
+import { type WordSplitting } from "./word-splitting.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;
+    /** How a word wider than its box is split - hyphenation, break-word, or neither (the default). */
+    splitting?: WordSplitting;
+    /** Whether the run gets the font's ligatures. Changes which glyphs are drawn, hence the width. */
+    ligatures?: boolean;
+}
 /** Default font for segments that don't override it. */
 export interface SegmentDefaults {
     fontFamily: string;
@@ -8,6 +35,9 @@ export interface SegmentDefaults {
     fontStyle: FontStyle;
     /** Extra space after every glyph, in points; a segment may override it. Default 0. */
     letterSpacing?: number;
+    /** Same knobs as the string path - see `LineOptions.splitting`. */
+    splitting?: WordSplitting;
+    ligatures?: boolean;
 }
 /** What happens to text beyond `maxLines`: `"clip"` drops it, `"ellipsis"` ends the last kept line
  *  with an ellipsis. Mirrors Flutter's `TextOverflow`. */
@@ -26,7 +56,19 @@ 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, maxLines?: number, overflow?: TextOverflow, letterSpacing?: number): string[];
+/**
+ * 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`