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

package/dist/api/structure.d.ts

@@ -151,6 +151,13 @@ export interface RenderOptions {
     /** What to do when content is taller than a page and cannot break: `"error"` throws (default),
      *  `"warn"` logs and clips, `"ignore"` clips silently. It is always clipped either way. */
     onOverflow?: OverflowPolicy;
+    /**
+     * Called once, after the render, with the characters no font could draw - they were removed rather
+     * than emitted as `.notdef`, which PDF/A forbids. Deliberately a callback and not a policy: a
+     * missing tick mark must never stop an invoice from being produced, but the application should be
+     * able to SAY which character went missing, where a server log would never be read.
+     */
+    onMissingGlyphs?: (characters: string[]) => void;
     /** Encrypt the PDF with a password (AES-256, the newest standard). NOT compatible with PDF/A
      *  (ZUGFeRD invoices) - encrypting one throws, since PDF/A forbids encryption. */
     encrypt?: EncryptOptions;

package/dist/api/structure.js

@@ -143,10 +143,14 @@ export async function renderPdf(doc, options) {
     // A throwaway PDFDocument whose build() yields this tree, reusing the engine's standard
     // font registration + config handling (the constructor does both). Custom fonts are
     // registered here, before layout/render, so both the metrics and the backend see them.
+    // Captured so the caller can be told what had to be dropped: `render()` is static and builds its own
+    // instance, so this is the only place the object manager surfaces.
+    let manager;
     const Anon = class extends PDFDocument {
         constructor() {
             super(config);
             const om = this.objectManager;
+            manager = om;
             om.setCompress(options?.compress !== false); // FlateDecode streams by default
             om.setOverflowPolicy(options?.onOverflow ?? "error");
             om.setKerning(options?.kerning !== false); // on by default (experimental); `kerning:false` opts out
@@ -207,7 +211,11 @@ export async function renderPdf(doc, options) {
             return doc;
         }
     };
-    return Anon.render();
+    const pdf = await Anon.render();
+    const missing = manager?.getMissingGlyphs() ?? [];
+    if (missing.length > 0)
+        options?.onMissingGlyphs?.(missing.map((cp) => String.fromCodePoint(cp)));
+    return pdf;
 }
 /** Renders a `Document(...)` tree to PDF bytes (e.g. for a download / save dialog). */
 export async function renderToBytes(doc, options) {

package/dist/elements/text-element.d.ts

@@ -125,6 +125,13 @@ export declare class TextElement extends SizedPDFElement implements Fragmentable
      * same width in most fonts).
      */
     private display;
+    /**
+     * Drops or substitutes whatever the RESOLVED font cannot draw. Runs last, after the fallback stack
+     * has had its say, and before anything is measured - a character removed at draw time only would
+     * make the measured line and the drawn one disagree. A font that draws everything gets its input
+     * back unchanged, so an ordinary document is byte-identical.
+     */
+    private covered;
     /** The content with `text-transform` applied, and nothing else. */
     private recased;
     private lineOptions;

package/dist/elements/text-element.js

@@ -10,6 +10,8 @@ import { singleLineWidth, MAX_SPACE_SHRINK, wrapStringIntoLines, breakSegmentsIn
 import { adjustForOrphansWidows, DEFAULT_ORPHANS, DEFAULT_WIDOWS, } from "../text/orphans-widows.js";
 import { lineBoxForSegmentLine, lineBoxForString } from "../text/line-metrics.js";
 import { HorizontalAlignment, SizedPDFElement } from "./pdf-element.js";
+import { normalizeContent } from "../text/whitespace.js";
+import { coverText } from "../text/glyph-coverage.js";
 /** How far a run sits off the baseline, as a fraction of its font size (up is positive). */
 export const VERTICAL_TEXT_SHIFT = {
     baseline: 0,
@@ -46,7 +48,9 @@ export class TextElement extends SizedPDFElement {
         this.rawTextTransform = textTransform;
         this.rawWordSpacing = finitePoints(wordSpacing, "wordSpacing");
         this.rawTextIndent = finitePoints(textIndent, "textIndent");
-        this.content = content;
+        // Control characters have no glyph and would be DRAWN as .notdef boxes; `\n` survives
+        // because the breaker treats it as a hard break. See text/whitespace.ts.
+        this.content = normalizeContent(content);
         this.maxLines = maxLines;
         this.orphans = orphans;
         this.widows = widows;
@@ -69,8 +73,10 @@ export class TextElement extends SizedPDFElement {
         // A SPAN may bring its own stack, so the element's being empty is not enough to skip the pass.
         const anyStack = this.fontFallback.length > 0 ||
             (typeof cased !== "string" && cased.some((seg) => (seg.fontFallback?.length ?? 0) > 0));
-        if (!anyStack || !metrics)
+        if (!metrics)
             return cased;
+        if (!anyStack)
+            return this.covered(cased, metrics);
         // Font fallback turns the content into spans - one per family - which every later pass already
         // knows how to handle. Nothing new downstream.
         const pieces = typeof cased === "string" ? [{ content: cased }] : cased;
@@ -83,7 +89,28 @@ export class TextElement extends SizedPDFElement {
                 for (const run of runs)
                     out.push({ ...seg, content: run.text, fontFamily: run.fontFamily });
         }
-        return out;
+        return this.covered(out, metrics);
+    }
+    /**
+     * Drops or substitutes whatever the RESOLVED font cannot draw. Runs last, after the fallback stack
+     * has had its say, and before anything is measured - a character removed at draw time only would
+     * make the measured line and the drawn one disagree. A font that draws everything gets its input
+     * back unchanged, so an ordinary document is byte-identical.
+     */
+    covered(content, metrics) {
+        const report = (dropped) => metrics.reportMissingGlyph?.(dropped);
+        if (typeof content === "string") {
+            const { text, dropped } = coverText(content, this.fontFamily, this.fontStyle, metrics);
+            if (dropped.length > 0)
+                report(dropped);
+            return text;
+        }
+        return content.map((seg) => {
+            const { text, dropped } = coverText(seg.content, seg.fontFamily ?? this.fontFamily, seg.fontStyle ?? this.fontStyle, metrics);
+            if (dropped.length > 0)
+                report(dropped);
+            return text === seg.content ? seg : { ...seg, content: text };
+        });
     }
     /** The content with `text-transform` applied, and nothing else. */
     recased() {

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.js

@@ -31,6 +31,9 @@ const ELLIPSIS = "...";
  * 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(" ")
@@ -45,44 +48,54 @@ export function wrapStringIntoLines(text, fontFamily, fontSize, fontStyle, maxWi
     let gaps = 0; // spaces on the current line, which is what a justified line can squeeze
     const lines = [];
     const font = { fontFamily, fontSize, fontStyle };
-    const words = text.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) {
+    // 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;
+            currentLine = "";
+            currentWidth = 0;
             gaps = 0;
         }
-        else {
-            currentLine += " " + word;
-            currentWidth = candidate;
-            gaps += 1;
-        }
+        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());
@@ -116,41 +129,53 @@ export function breakSegmentsIntoLines(segments, defaults, maxWidth, metrics, ma
         const letterSpacing = segment.letterSpacing ?? defaults.letterSpacing ?? 0;
         const font = { fontFamily: family, fontSize: size, fontStyle: style };
         const spaceWidth = runAdvance(metrics, " ", font, letterSpacing);
-        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({ ...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) {
+        // 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 = wordWidth;
+                width = 0;
                 lineSegments = [];
-                combined = word;
-                lineSegments.push({ ...segment, content: combined });
             }
-            else {
-                combined += wordIndex === 0 ? word : " " + word;
-                width = candidate;
-                if (lineSegments.length === 0) {
-                    lineSegments.push({ ...segment, fontFamily: family, content: combined });
+            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) {
+    // 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 });
     }
     // Open-end by default; cap only when maxLines is set.

package/dist/text/whitespace.d.ts

@@ -0,0 +1,4 @@
+import type { TextSegment } from "../elements/text-element.js";
+export declare function normalizeWhitespace(text: string): string;
+/** The same, for content that may already be split into styled spans. */
+export declare function normalizeContent(content: string | TextSegment[]): string | TextSegment[];

package/dist/text/whitespace.js

@@ -0,0 +1,43 @@
+/**
+ * A character with no glyph is still ENCODED and DRAWN: it comes out as the font's .notdef box, and
+ * veraPDF rejects the file for referencing .notdef (ISO 19005-3, 6.2.11.8). A `\n` in an invoice
+ * description was the first case we hit; zero-width characters are the same fault and arrive far more
+ * quietly - a paste out of Word or a web page carries them routinely.
+ *
+ * So nothing invisible survives into the breaker except `\n`, and that only because the breaker treats
+ * it as a hard break. The mapping follows a browser's `white-space: normal` apart from `\n`: CSS
+ * collapses that to a space, while a text COMPONENT breaks on it - Flutter's `Text` and react-pdf both
+ * do, and it is what anyone writing `"a\nb"` expects.
+ */
+/**
+ * Everything that MEANS a line break, matched as a WHOLE so a two-character ending never becomes two
+ * breaks. `\n\r` is in here beside `\r\n` because it is what a mistyped CRLF looks like, and a stray
+ * blank line is a worse answer than reading it as the one break it was meant to be. U+2028/U+2029 are
+ * Unicode's own line and paragraph separators.
+ */
+const LINE_BREAKS = /\r\n|\n\r|\r|\u2028|\u2029/g;
+/**
+ * Invisible and inert: a zero-width space and a byte-order mark carry no meaning we act on, so they are
+ * dropped rather than drawn. C0, C1 and DEL likewise.
+ *
+ * Deliberately NOT here: U+200C/U+200D (zero-width non-joiner and joiner) drive Arabic shaping and
+ * emoji sequences, and U+200E/U+200F (the bidi marks) drive `text/bidi.ts`. Dropping those would
+ * silently change how correct text is laid out - worse than the box they can still leave behind in a
+ * run that neither shapes nor reorders.
+ */
+// oxlint-disable-next-line no-control-regex -- matching control characters is the whole point here.
+const UNPRINTABLE = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F-\u009F\u200B\uFEFF]/g;
+export function normalizeWhitespace(text) {
+    return (text
+        // Every spelling of a break becomes `\n` first, so the breaker only ever sees one form.
+        .replace(LINE_BREAKS, "\n")
+        // A tab is collapsible whitespace; a PDF text operator has no tab stops to advance to.
+        .replace(/\t/g, " ")
+        .replace(UNPRINTABLE, ""));
+}
+/** The same, for content that may already be split into styled spans. */
+export function normalizeContent(content) {
+    if (typeof content === "string")
+        return normalizeWhitespace(content);
+    return content.map((seg) => ({ ...seg, content: normalizeWhitespace(seg.content) }));
+}

package/dist/utils/font-metrics.d.ts

@@ -25,6 +25,12 @@ export interface FontMetrics {
     getKernPairs(text: string, fontFamily: string, fontStyle: FontStyle): number[];
     /** Whether this family can draw the code point at all - what picks a face out of a fallback stack. */
     hasGlyph(codePoint: number, fontFamily: string, fontStyle: FontStyle): boolean;
+    /** Whether the document draws this code point as colour emoji rather than from the text font - it
+     *  is missing from that font on purpose, so glyph coverage must not touch it. */
+    rendersAsEmoji?(codePoint: number, fontFamily: string, fontStyle: FontStyle): boolean;
+    /** Told when a code point had to be removed because no font could draw it. Optional: a metrics
+     *  object used only for measuring (a test double) has nothing to report to. */
+    reportMissingGlyph?(codePoints: number[]): void;
     /** How many glyphs the run will DRAW, when a ligature made that differ from its code-point count.
      *  Absent or `undefined` means "the same", which is every Latin run. */
     shapedGlyphCount?(text: string, fontFamily?: string, fontStyle?: FontStyle): number | undefined;

package/dist/utils/pdf-object-manager.d.ts

@@ -65,6 +65,16 @@ export declare class PDFObjectManager implements FontMetrics {
     addObject(content: string): number;
     replaceObject(objectNumber: number, content: string): void;
     setCompress(on: boolean): void;
+    /**
+     * Code points no font in the document could draw, so they were removed rather than emitted as
+     * `.notdef` (which PDF/A forbids). Collected here because this object is the one thing threaded
+     * through BOTH passes; the caller gets them back with the bytes, so an application can say which
+     * character went missing instead of a server log nobody reads.
+     */
+    private readonly missingGlyphs;
+    reportMissingGlyph(codePoints: number[]): void;
+    /** The dropped code points, in the order first seen. Empty for a document that hit none. */
+    getMissingGlyphs(): number[];
     setOverflowPolicy(policy: OverflowPolicy): void;
     getOverflowPolicy(): OverflowPolicy;
     private encToken;
@@ -142,6 +152,13 @@ export declare class PDFObjectManager implements FontMetrics {
      * Used to pick a family out of a fallback stack, per code point.
      */
     hasGlyph(codePoint: number, fontFamily: string, fontStyle?: FontStyle): boolean;
+    /**
+     * Whether the document draws this code point through the colour-emoji path instead of the text
+     * font - a fallback emoji FONT, or an image source (`Document({ emoji })`). Such a code point is
+     * missing from the text font ON PURPOSE, so glyph coverage must leave it alone. Mirrors exactly
+     * what `getCharWidth` measures it as, or a dropped emoji would have been measured and not drawn.
+     */
+    rendersAsEmoji(codePoint: number, fontFamily: string, fontStyle: FontStyle): boolean;
     private colorRenders;
     getCustomFontResource(name: string, style?: FontStyle): FontIndexes | undefined;
     /** How many glyphs a run draws - its code-point count unless a ligature merged some. `letterSpacing`

package/dist/utils/pdf-object-manager.js

@@ -189,6 +189,15 @@ export class PDFObjectManager {
         // Interactive form fields (AcroForm). Empty unless a form field was placed; then finalize() emits the
         // catalog /AcroForm dict and each field's widget lands in its page /Annots.
         this._acroform = new AcroFormCollector();
+        // Overflow policy for unbreakable content taller than a page region (default "error"); the renderer
+        // seeds it into the layout-context root so packChildren can act on it.
+        /**
+         * Code points no font in the document could draw, so they were removed rather than emitted as
+         * `.notdef` (which PDF/A forbids). Collected here because this object is the one thing threaded
+         * through BOTH passes; the caller gets them back with the bytes, so an application can say which
+         * character went missing instead of a server log nobody reads.
+         */
+        this.missingGlyphs = new Set();
         // Whether to kern. Document-level: measuring (via `runAdvance`, which reads this off the metrics)
         // and drawing (the backend emits a `TJ`) both consult it, so they can never disagree. OFF while the
         // embedded-font path (kern/GPOS) is unbuilt - a standard-14-only kerning would set the 14 system
@@ -216,8 +225,14 @@ export class PDFObjectManager {
     setCompress(on) {
         this.compress = on;
     }
-    // Overflow policy for unbreakable content taller than a page region (default "error"); the renderer
-    // seeds it into the layout-context root so packChildren can act on it.
+    reportMissingGlyph(codePoints) {
+        for (const cp of codePoints)
+            this.missingGlyphs.add(cp);
+    }
+    /** The dropped code points, in the order first seen. Empty for a document that hit none. */
+    getMissingGlyphs() {
+        return [...this.missingGlyphs];
+    }
     setOverflowPolicy(policy) {
         this.overflowPolicy = policy;
     }
@@ -694,6 +709,23 @@ endstream`;
             return ttf.getGlyphIndex(codePoint) !== 0;
         return isWindows1252(codePoint);
     }
+    /**
+     * Whether the document draws this code point through the colour-emoji path instead of the text
+     * font - a fallback emoji FONT, or an image source (`Document({ emoji })`). Such a code point is
+     * missing from the text font ON PURPOSE, so glyph coverage must leave it alone. Mirrors exactly
+     * what `getCharWidth` measures it as, or a dropped emoji would have been measured and not drawn.
+     */
+    rendersAsEmoji(codePoint, fontFamily, fontStyle) {
+        const ttf = this.getCustomFont(fontFamily, fontStyle);
+        if (ttf && this.colorRenders(ttf, codePoint))
+            return true;
+        if (this.emojiFontName && this.emojiFontName !== fontFamily) {
+            const emoji = this.getColorFont(this.emojiFontName, fontStyle);
+            if (emoji && this.colorRenders(emoji, codePoint))
+                return true;
+        }
+        return this.emojiImage !== undefined && isEmojiCodePoint(codePoint);
+    }
     colorRenders(ttf, codePoint) {
         return ttf.getColorGlyph(ttf.getGlyphIndex(codePoint)) !== null;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jasy/pdf",
-  "version": "1.0.0-alpha.10",
+  "version": "1.0.0-alpha.11",
   "description": "Declarative, component-based PDF generation in pure TypeScript - Flutter-style components, real AFM font metrics, a hand-rolled PDF writer. No headless browser, no Java.",
   "keywords": [
     "declarative",