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

package/dist/svg/style.js

@@ -0,0 +1,144 @@
+import { Color } from "../common/color.js";
+import { toColor } from "../api/color.js";
+import { SvgParseError, SvgUnsupportedError } from "./errors.js";
+import { length, ratio } from "./units.js";
+export const isPaintRef = (paint) => paint !== undefined && !(paint instanceof Color);
+/** The colour a shape actually paints with: its raw colour, times the opacities that reached it. */
+export function paintAlpha(color, opacity) {
+    if (opacity >= 1)
+        return color;
+    const [r, g, b] = color.toArray();
+    return new Color(r, g, b, color.getAlpha() * opacity);
+}
+export const ROOT_STYLE = {
+    fill: new Color(0, 0, 0),
+    fillRule: "nonzero",
+    stroke: undefined,
+    color: new Color(0, 0, 0),
+    fillOpacity: 1,
+    strokeOpacity: 1,
+    opacity: 1,
+};
+/** Splits a `style=""` bag into declarations. It wins over both other sources, as in CSS. */
+function styleBag(value) {
+    if (typeof value !== "string")
+        return {};
+    const out = {};
+    for (const declaration of value.split(";")) {
+        const colon = declaration.indexOf(":");
+        if (colon === -1)
+            continue;
+        const property = declaration.slice(0, colon).trim();
+        if (property)
+            out[property] = declaration.slice(colon + 1).trim();
+    }
+    return out;
+}
+/**
+ * Reads a property from all three sources, in CSS order: a presentation attribute is the weakest, a
+ * matching `<style>` rule beats it, and the inline `style=""` bag beats both.
+ *
+ * Exported because anything that INSPECTS a property has to see the same value the style resolver
+ * would - `filter="url(#f)"` and `style="filter:url(#f)"` are the same instruction, and checking only
+ * the attribute lets the second one through unnoticed.
+ */
+export function cascadedReader(attributes, css = {}) {
+    const bag = styleBag(attributes["style"]);
+    return (name) => {
+        const value = bag[name] ?? css[name] ?? attributes[name];
+        return value === undefined ? undefined : String(value);
+    };
+}
+const dashNumbers = (list) => {
+    const found = list.match(/[+-]?(?:\d*\.\d+|\d+\.?)(?:[eE][+-]?\d+)?/g);
+    return found ? found.map(Number) : [];
+};
+/**
+ * A paint value. `none` is the absence of paint, which is NOT the same as transparent black - a shape
+ * with `fill="none"` and a stroke draws its outline only. A `url(#...)` reference means a gradient or
+ * pattern, which we do not resolve yet and therefore name.
+ */
+function paint(value, current) {
+    const v = value.trim();
+    if (v === "none")
+        return undefined;
+    if (v === "currentColor")
+        return current;
+    const reference = /^url\(\s*#([^)\s]+)\s*\)/.exec(v);
+    // A paint reference may name a fallback after it (`url(#g) red`), which is what a renderer uses
+    // when the reference is broken - so it is kept as the reference, and resolution decides.
+    if (reference)
+        return { ref: reference[1] };
+    if (v.startsWith("url(")) {
+        throw new SvgUnsupportedError(`the paint "${v}"`, "Only a `url(#id)` reference to a gradient is resolved.");
+    }
+    return svgColor(v);
+}
+/**
+ * A colour, with the value quoted in the message. `toColor` throws a bare `Unknown color: "x"`, which
+ * inside a 900-element logo says nothing about WHERE - and a malformed file reaches here with pieces
+ * of its own markup as the value, so the raw error is actively misleading.
+ */
+export function svgColor(value) {
+    try {
+        return toColor(value);
+    }
+    catch {
+        throw new SvgParseError(`"${value}" is not a colour this SVG can use - expected a name, #hex, rgb() or hsl().`);
+    }
+}
+/**
+ * Resolves one element's style against its parent's. Everything SVG inherits is inherited; `opacity`
+ * is the exception - it applies to the element itself, so it is MULTIPLIED down and folded into the
+ * paint of each leaf. That differs from a browser for a `<g opacity>` whose children OVERLAP (a real
+ * group needs one transparency group), and is the one approximation in this file.
+ */
+export function resolveStyle(parent, attributes, css = {}) {
+    const read = cascadedReader(attributes, css);
+    const color = read("color") !== undefined ? svgColor(read("color")) : parent.color;
+    // `Number("50%")` is NaN and `Number("")` is 0, both of which travel silently into the paint.
+    const opacity = parent.opacity * ratio(read("opacity"));
+    const fillValue = read("fill");
+    const strokeValue = read("stroke");
+    const dashValue = read("stroke-dasharray");
+    const strokePaint = strokeValue !== undefined ? paint(strokeValue, color) : parent.stroke?.color;
+    if (isPaintRef(strokePaint)) {
+        // PDF strokes with a colour, never with a shading; painting the outline solid would be a colour
+        // the file did not name.
+        throw new SvgUnsupportedError("a gradient on a stroke", "PDF strokes with a colour only. Use a solid stroke, or convert the outline to a filled shape.");
+    }
+    const parts = {
+        color: strokePaint,
+        width: length(read("stroke-width"), 'the "stroke-width" attribute', parent.stroke?.width ?? 1),
+        cap: read("stroke-linecap") ?? parent.stroke?.cap,
+        join: read("stroke-linejoin") ?? parent.stroke?.join,
+        miterLimit: length(read("stroke-miterlimit"), 'the "stroke-miterlimit" attribute', parent.stroke?.miterLimit ?? 4),
+        dash: dashValue !== undefined
+            ? dashValue.trim() === "none"
+                ? undefined
+                : dashNumbers(dashValue)
+            : parent.stroke?.dash,
+        dashOffset: length(read("stroke-dashoffset"), 'the "stroke-dashoffset" attribute', parent.stroke?.dashOffset ?? 0),
+    };
+    return {
+        fill: fillValue !== undefined ? paint(fillValue, color) : parent.fill,
+        fillRule: read("fill-rule") ?? parent.fillRule,
+        // A stroke with no colour or no width paints nothing; dropping it here keeps every consumer from
+        // having to ask twice.
+        stroke: parts.color && parts.width > 0
+            ? {
+                color: parts.color,
+                width: parts.width,
+                cap: parts.cap,
+                join: parts.join,
+                miterLimit: parts.miterLimit,
+                dash: parts.dash,
+                dashOffset: parts.dashOffset,
+            }
+            : undefined,
+        color,
+        fillOpacity: ratio(read("fill-opacity"), parent.fillOpacity),
+        strokeOpacity: ratio(read("stroke-opacity"), parent.strokeOpacity),
+        opacity,
+    };
+}

package/dist/svg/transform.d.ts

@@ -0,0 +1,13 @@
+import type { Affine } from "../utils/ttf-parser.js";
+/**
+ * The `transform` attribute. SVG's `matrix(a b c d e f)` is exactly the PDF `cm` operand and exactly
+ * our IR's `TransformPush.matrix`, both read in a top-left, y-down space - so a transform maps across
+ * with no sign flips. That is also why we keep transforms in the graphics state instead of baking them
+ * into the coordinates: a stroke inside a scaled group scales WITH it, which is what SVG specifies.
+ */
+export declare const IDENTITY: Affine;
+/** `a` then `b` - the matrix that applies `b` in the space `a` established. */
+export declare function multiply(a: Affine, b: Affine): Affine;
+export declare const isIdentity: (m: Affine) => boolean;
+/** Parses a whole `transform` attribute; several functions compose left to right, as in SVG. */
+export declare function parseTransform(value: string): Affine;

package/dist/svg/transform.js

@@ -0,0 +1,68 @@
+import { SvgParseError } from "./errors.js";
+/**
+ * The `transform` attribute. SVG's `matrix(a b c d e f)` is exactly the PDF `cm` operand and exactly
+ * our IR's `TransformPush.matrix`, both read in a top-left, y-down space - so a transform maps across
+ * with no sign flips. That is also why we keep transforms in the graphics state instead of baking them
+ * into the coordinates: a stroke inside a scaled group scales WITH it, which is what SVG specifies.
+ */
+export const IDENTITY = [1, 0, 0, 1, 0, 0];
+/** `a` then `b` - the matrix that applies `b` in the space `a` established. */
+export function multiply(a, b) {
+    return [
+        a[0] * b[0] + a[2] * b[1],
+        a[1] * b[0] + a[3] * b[1],
+        a[0] * b[2] + a[2] * b[3],
+        a[1] * b[2] + a[3] * b[3],
+        a[0] * b[4] + a[2] * b[5] + a[4],
+        a[1] * b[4] + a[3] * b[5] + a[5],
+    ];
+}
+export const isIdentity = (m) => m.every((n, i) => n === IDENTITY[i]);
+const TRANSFORM = /([a-zA-Z]+)\s*\(([^)]*)\)/g;
+const radians = (deg) => (deg * Math.PI) / 180;
+/** Numbers in an SVG list: separated by commas, whitespace, or nothing at all before a minus sign. */
+function numbers(list) {
+    const found = list.match(/[+-]?(?:\d*\.\d+|\d+\.?)(?:[eE][+-]?\d+)?/g);
+    return found ? found.map(Number) : [];
+}
+/** Parses a whole `transform` attribute; several functions compose left to right, as in SVG. */
+export function parseTransform(value) {
+    let out = IDENTITY;
+    TRANSFORM.lastIndex = 0;
+    let match;
+    while ((match = TRANSFORM.exec(value)) !== null) {
+        out = multiply(out, single(match[1], numbers(match[2])));
+    }
+    return out;
+}
+function single(name, a) {
+    switch (name) {
+        case "matrix":
+            if (a.length < 6)
+                throw new SvgParseError(`transform: matrix() needs six numbers`);
+            return [a[0], a[1], a[2], a[3], a[4], a[5]];
+        case "translate":
+            return [1, 0, 0, 1, a[0] ?? 0, a[1] ?? 0];
+        case "scale": {
+            const sx = a[0] ?? 1;
+            // One number scales both axes - the SVG rule, and a common source of squashed logos if missed.
+            return [sx, 0, 0, a[1] ?? sx, 0, 0];
+        }
+        case "rotate": {
+            const t = radians(a[0] ?? 0);
+            const [cos, sin] = [Math.cos(t), Math.sin(t)];
+            const r = [cos, sin, -sin, cos, 0, 0];
+            if (a.length < 3)
+                return r;
+            // rotate(angle cx cy) = translate(cx,cy) rotate(angle) translate(-cx,-cy).
+            const [cx, cy] = [a[1], a[2]];
+            return multiply(multiply([1, 0, 0, 1, cx, cy], r), [1, 0, 0, 1, -cx, -cy]);
+        }
+        case "skewX":
+            return [1, 0, Math.tan(radians(a[0] ?? 0)), 1, 0, 0];
+        case "skewY":
+            return [1, Math.tan(radians(a[0] ?? 0)), 0, 1, 0, 0];
+        default:
+            throw new SvgParseError(`transform: unknown function "${name}()"`);
+    }
+}

package/dist/svg/units.d.ts

@@ -0,0 +1,11 @@
+/** A plain number, with nothing else in the string. */
+export declare function strictNumber(text: string): number | undefined;
+/**
+ * A length in user units. `undefined` and `""` mean "not given" and return `fallback`; a resolvable
+ * absolute unit is converted; a relative one (`%`, `em`, `rem`, `ex`, `ch`, `vw`, …) is NAMED,
+ * because resolving it needs a font or a viewport that a shape attribute does not carry.
+ */
+export declare function length(value: string | undefined, where: string, fallback?: number): number;
+/** A 0..1 ratio, written as a number or a percentage, clamped - an opacity outside the range is a
+ *  malformed file, and CSS clamps rather than rejecting. */
+export declare function ratio(value: string | undefined, fallback?: number): number;

package/dist/svg/units.js

@@ -0,0 +1,73 @@
+import { SvgUnsupportedError } from "./errors.js";
+/**
+ * Reading NUMBERS out of an SVG.
+ *
+ * `Number.parseFloat` is the wrong tool on its own: it stops at the first character it cannot use and
+ * returns what it had, so `"10px"` is 10 and `"20abc"` is 20. That is convenient exactly once and
+ * wrong everywhere else - a length we silently misread draws a shape the file did not describe.
+ *
+ * So the rules here are explicit: a plain number is a number, `px` is the user unit and means the
+ * same thing, a percentage is only valid where a ratio is expected, and anything else is NAMED. In
+ * 10,819 real files, 53 use `px` on a shape attribute (we drew nothing for them) and one uses a
+ * percentage opacity.
+ */
+/** Absolute CSS units are defined against the user unit, which SVG pins to 1/96 inch. */
+const ABSOLUTE = {
+    px: 1,
+    pt: 96 / 72,
+    pc: 16,
+    in: 96,
+    cm: 96 / 2.54,
+    mm: 96 / 25.4,
+    q: 96 / 101.6,
+};
+const NUMBER = /^[+-]?(\d+\.?\d*|\.\d+)([eE][+-]?\d+)?$/;
+const WITH_UNIT = /^([+-]?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?)\s*([a-zA-Z%]+)$/;
+/** A plain number, with nothing else in the string. */
+export function strictNumber(text) {
+    const t = text.trim();
+    if (!NUMBER.test(t))
+        return undefined;
+    const n = Number(t);
+    // `1e400` matches the grammar and overflows to Infinity. A non-finite number reaches the content
+    // stream as the literal text `Infinity`, which viewers discard the rest of the page over.
+    return Number.isFinite(n) ? n : undefined;
+}
+/**
+ * A length in user units. `undefined` and `""` mean "not given" and return `fallback`; a resolvable
+ * absolute unit is converted; a relative one (`%`, `em`, `rem`, `ex`, `ch`, `vw`, …) is NAMED,
+ * because resolving it needs a font or a viewport that a shape attribute does not carry.
+ */
+export function length(value, where, fallback = 0) {
+    if (value === undefined || value.trim() === "")
+        return fallback;
+    const plain = strictNumber(value);
+    if (plain !== undefined)
+        return plain;
+    const parts = WITH_UNIT.exec(value.trim());
+    if (parts) {
+        const factor = ABSOLUTE[parts[2].toLowerCase()];
+        if (factor !== undefined) {
+            // The conversion itself can overflow (`1e308in`), and a non-finite number reaches the content
+            // stream as the literal text `Infinity`.
+            const converted = Number(parts[1]) * factor;
+            return Number.isFinite(converted) ? converted : fallback;
+        }
+        throw new SvgUnsupportedError(`the length "${value.trim()}" on ${where}`, "Only absolute units (px, pt, pc, in, cm, mm, q) and plain numbers are resolved.");
+    }
+    // Not a number at all: the file is malformed here. Treat it as absent rather than as zero-with-a-
+    // shrug, so a caller sees the same thing as for a missing attribute.
+    return fallback;
+}
+/** A 0..1 ratio, written as a number or a percentage, clamped - an opacity outside the range is a
+ *  malformed file, and CSS clamps rather than rejecting. */
+export function ratio(value, fallback = 1) {
+    if (value === undefined || value.trim() === "")
+        return fallback;
+    const t = value.trim();
+    const raw = t.endsWith("%") ? strictNumber(t.slice(0, -1)) : strictNumber(t);
+    if (raw === undefined)
+        return fallback;
+    const scaled = t.endsWith("%") ? raw / 100 : raw;
+    return Math.max(0, Math.min(1, scaled));
+}

package/dist/svg/xml.d.ts

@@ -0,0 +1,24 @@
+/**
+ * A minimal XML reader for SVG.
+ *
+ * We used `svg-parser` first. It COERCES an attribute that looks numeric, so `id="58310095e0"` came
+ * back as the number 58310095 and `id="1e999"` as Infinity - the original string simply gone. That
+ * breaks the one thing it is needed for, resolving `url(#id)` references, and no amount of care on
+ * our side can undo it. An XML attribute is a string; this reader treats it as one.
+ *
+ * The scope is what SVG actually needs: elements, attributes, text, CDATA, comments, the XML
+ * declaration and a doctype. No entity expansion beyond the five predefined ones plus numeric
+ * references, no DTD processing, no namespace resolution (the caller strips prefixes itself).
+ */
+export interface XmlElement {
+    type: "element";
+    tagName: string;
+    attributes: Record<string, string>;
+    children: XmlNode[];
+}
+export interface XmlText {
+    type: "text";
+    value: string;
+}
+export type XmlNode = XmlElement | XmlText;
+export declare function parseXml(source: string): XmlElement[];

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,15 +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);
+    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) ?? codePointCount(text);
+        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/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,7 @@
 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.
  *
@@ -22,6 +23,10 @@ export interface LineOptions {
     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 {
@@ -30,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`. */