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

package/dist/utils/gsub.js

@@ -0,0 +1,178 @@
+import { u16, u32, i16, latin1FromBytes } from "./bytes.js";
+const EXTENSION = 7;
+/** A coverage table may not expand past this: a glyph id is a uint16, so no honest one can. */
+const MAX_COVERAGE_ENTRIES = 65536;
+export class GsubTable {
+    constructor(data, base) {
+        this.data = data;
+        this.base = base;
+        this.lookupCache = new Map();
+        this.coverageCache = new Map();
+        this.scriptList = base + u16(data, base + 4);
+        this.featureList = base + u16(data, base + 6);
+        this.lookupList = base + u16(data, base + 8);
+    }
+    /** Whether the font carries this script at all - `arab` is the question the shaper asks. */
+    hasScript(script) {
+        return this.scriptOffset(script) !== undefined;
+    }
+    /** A feature's lookup indices, under the script's DEFAULT language system - Arabic shaping features
+     *  are script-wide, so a language-specific override would only add typographic niceties. */
+    lookups(script, feature) {
+        const scriptOff = this.scriptOffset(script);
+        if (scriptOff === undefined)
+            return [];
+        // The default LangSys is optional; fall back to the first named one - a font declaring only
+        // `ARA ` still shapes Arabic.
+        const defaultOff = u16(this.data, scriptOff);
+        const langSys = defaultOff !== 0
+            ? scriptOff + defaultOff
+            : u16(this.data, scriptOff + 2) > 0
+                ? // The first LangSysRecord is at +4 and is tag(4) + offset(2), so its offset is at +8.
+                    scriptOff + u16(this.data, scriptOff + 8)
+                : undefined;
+        if (langSys === undefined)
+            return [];
+        const out = [];
+        const count = u16(this.data, langSys + 4);
+        for (let i = 0; i < count; i++) {
+            const featureIndex = u16(this.data, langSys + 6 + i * 2);
+            const record = this.featureList + 2 + featureIndex * 6;
+            if (latin1FromBytes(this.data.subarray(record, record + 4)) !== feature)
+                continue;
+            const featureOff = this.featureList + u16(this.data, record + 4);
+            const lookupCount = u16(this.data, featureOff + 2);
+            for (let j = 0; j < lookupCount; j++)
+                out.push(u16(this.data, featureOff + 4 + j * 2));
+        }
+        return out;
+    }
+    /** Type 1: substitute one glyph. `null` when no subtable covers it - the feature does not apply. */
+    substituteSingle(lookupIndex, glyph) {
+        const lookup = this.lookup(lookupIndex);
+        if (!lookup || lookup.type !== 1)
+            return null;
+        for (const sub of lookup.subtables) {
+            const coverage = this.coverage(sub + u16(this.data, sub + 2));
+            const index = coverage.get(glyph);
+            if (index === undefined)
+                continue;
+            // Format 1 shifts every covered glyph by one delta; format 2 lists a replacement per glyph.
+            return u16(this.data, sub) === 1
+                ? (glyph + i16(this.data, sub + 4)) & 0xffff
+                : u16(this.data, sub + 6 + index * 2);
+        }
+        return null;
+    }
+    /**
+     * Type 4: collapse a run of glyphs into one, starting at `at`. Longest match wins, as the spec
+     * requires - a three-glyph ligature beats the two-glyph one that starts the same way.
+     */
+    substituteLigature(lookupIndex, glyphs, at) {
+        const lookup = this.lookup(lookupIndex);
+        if (!lookup || lookup.type !== 4)
+            return null;
+        let best = null;
+        for (const sub of lookup.subtables) {
+            const coverage = this.coverage(sub + u16(this.data, sub + 2));
+            const setIndex = coverage.get(glyphs[at]);
+            if (setIndex === undefined)
+                continue;
+            const set = sub + u16(this.data, sub + 6 + setIndex * 2);
+            const ligatureCount = u16(this.data, set);
+            for (let i = 0; i < ligatureCount; i++) {
+                const lig = set + u16(this.data, set + 2 + i * 2);
+                const components = u16(this.data, lig + 2); // includes the glyph coverage already matched
+                if (at + components > glyphs.length)
+                    continue;
+                let matches = true;
+                for (let c = 1; c < components && matches; c++) {
+                    matches = glyphs[at + c] === u16(this.data, lig + 2 + c * 2);
+                }
+                if (matches && (best === null || components > best.consumed)) {
+                    best = { glyph: u16(this.data, lig), consumed: components };
+                }
+            }
+        }
+        return best;
+    }
+    /** The type of a lookup, for reporting what a font needs that we do not do. */
+    lookupType(lookupIndex) {
+        return this.lookup(lookupIndex)?.type;
+    }
+    scriptOffset(script) {
+        const count = u16(this.data, this.scriptList);
+        for (let i = 0; i < count; i++) {
+            const record = this.scriptList + 2 + i * 6;
+            if (latin1FromBytes(this.data.subarray(record, record + 4)) === script) {
+                return this.scriptList + u16(this.data, record + 4);
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Resolve a lookup, unwrapping type 7 (extension) - which exists only because the 16-bit offsets
+     * elsewhere cannot reach far enough in a big font. Callers never learn it was wrapped.
+     */
+    lookup(index) {
+        const cached = this.lookupCache.get(index);
+        if (cached !== undefined)
+            return cached;
+        let result = null;
+        if (index < u16(this.data, this.lookupList)) {
+            const off = this.lookupList + u16(this.data, this.lookupList + 2 + index * 2);
+            const type = u16(this.data, off);
+            const count = u16(this.data, off + 4);
+            const subtables = [];
+            let realType = type;
+            for (let i = 0; i < count; i++) {
+                const sub = off + u16(this.data, off + 6 + i * 2);
+                if (type === EXTENSION) {
+                    realType = u16(this.data, sub + 2);
+                    subtables.push(sub + u32(this.data, sub + 4));
+                }
+                else {
+                    subtables.push(sub);
+                }
+            }
+            result = { type: realType, subtables };
+        }
+        this.lookupCache.set(index, result);
+        return result;
+    }
+    /** Coverage table -> glyph id to its INDEX in the table, which is how subtables address glyphs. */
+    coverage(off) {
+        const cached = this.coverageCache.get(off);
+        if (cached)
+            return cached;
+        const map = new Map();
+        const count = u16(this.data, off + 2);
+        if (u16(this.data, off) === 1) {
+            for (let i = 0; i < count; i++)
+                map.set(u16(this.data, off + 4 + i * 2), i);
+        }
+        else {
+            // Format 2 is RANGES, and a malformed file can claim far more glyphs than any font holds. Such
+            // a table is refused whole rather than expanded - the feature then simply does not apply.
+            let total = 0;
+            for (let i = 0; i < count; i++) {
+                const record = off + 4 + i * 6;
+                const start = u16(this.data, record);
+                const end = u16(this.data, record + 2);
+                if (end < start)
+                    continue; // an inverted range covers nothing
+                total += end - start + 1;
+                if (total > MAX_COVERAGE_ENTRIES)
+                    return this.cacheCoverage(off, new Map());
+                const startIndex = u16(this.data, record + 4);
+                for (let g = start; g <= end; g++)
+                    map.set(g, startIndex + (g - start));
+            }
+        }
+        return this.cacheCoverage(off, map);
+    }
+    cacheCoverage(off, map) {
+        this.coverageCache.set(off, map);
+        return map;
+    }
+}

package/dist/utils/inflate.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Inflating with a ceiling, so a hostile or mistaken input cannot exhaust memory.
+ *
+ * Used by BOTH sides: the reader inflating a PDF stream, and the font path unpacking a WOFF table.
+ * It lives in `utils/` for exactly that reason - the generate path must not import from `edit/`.
+ *
+ * fflate's `unzlibSync(data, { out })` is NOT usable for this: it truncates silently instead of failing.
+ * Hence the streamed form - input in slices, so the total can be checked while it grows.
+ */
+/** Thrown when a stream expands past the ceiling; distinct from a stream that simply will not decode. */
+export declare class PdfStreamTooLargeError extends Error {
+    readonly limit: number;
+    constructor(limit: number, message: string);
+}
+export declare const DEFAULT_MAX_STREAM_SIZE: number;
+export declare function inflateBounded(data: Uint8Array, limit: number): Uint8Array;

package/dist/utils/inflate.js

@@ -0,0 +1,52 @@
+import { Unzlib, unzlibSync } from "fflate";
+/**
+ * Inflating with a ceiling, so a hostile or mistaken input cannot exhaust memory.
+ *
+ * Used by BOTH sides: the reader inflating a PDF stream, and the font path unpacking a WOFF table.
+ * It lives in `utils/` for exactly that reason - the generate path must not import from `edit/`.
+ *
+ * fflate's `unzlibSync(data, { out })` is NOT usable for this: it truncates silently instead of failing.
+ * Hence the streamed form - input in slices, so the total can be checked while it grows.
+ */
+/** Thrown when a stream expands past the ceiling; distinct from a stream that simply will not decode. */
+export class PdfStreamTooLargeError extends Error {
+    constructor(limit, message) {
+        super(`@jasy/pdf: ${message}`);
+        this.limit = limit;
+    }
+}
+export const DEFAULT_MAX_STREAM_SIZE = 64 * 1024 * 1024;
+/** Only the granularity of the check: fflate buffers internally, so the abort lands one block past. */
+const INPUT_SLICE = 16 * 1024;
+/** DEFLATE's maximum expansion (a 258-byte match in its shortest encoding). A format property. */
+const MAX_DEFLATE_RATIO = 1032;
+export function inflateBounded(data, limit) {
+    // Too small to reach the ceiling even at maximum compression, so checking as it grows is pointless.
+    // Nearly every stream in a real PDF lands here, which is why the guard costs nothing.
+    if (data.length <= limit / MAX_DEFLATE_RATIO)
+        return unzlibSync(data);
+    const parts = [];
+    let total = 0;
+    const inflater = new Unzlib();
+    inflater.ondata = (chunk) => {
+        total += chunk.length;
+        if (total > limit) {
+            throw new PdfStreamTooLargeError(limit, `a stream in this PDF expands past the ${limit} byte limit for a single stream; if the file is ` +
+                `genuinely that large, raise it with { maxStreamSize }`);
+        }
+        parts.push(chunk);
+    };
+    for (let at = 0; at < data.length; at += INPUT_SLICE) {
+        const end = Math.min(at + INPUT_SLICE, data.length);
+        inflater.push(data.subarray(at, end), end >= data.length);
+    }
+    if (parts.length === 1)
+        return parts[0];
+    const out = new Uint8Array(total);
+    let at = 0;
+    for (const part of parts) {
+        out.set(part, at);
+        at += part.length;
+    }
+    return out;
+}

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

@@ -1,5 +1,6 @@
 import type { OverflowPolicy } from "../layout/fragmentation.js";
 import { TTFParser } from "./ttf-parser.js";
+import { type ShapedGlyph } from "../text/shape.js";
 import type { SecurityHandler } from "../crypto/security-handler.js";
 import type { Gradient } from "../ir/display-list.js";
 import type { FontVerticals } from "../text/line-metrics.js";
@@ -39,6 +40,8 @@ export declare class PDFObjectManager implements FontMetrics {
     private verticalsCache;
     private decorationCache;
     private customFontEmit;
+    private shapeCache;
+    private shapedOrigins;
     private attachments;
     private xmpMetadata?;
     private outputIntent?;
@@ -62,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;
@@ -133,9 +146,34 @@ export declare class PDFObjectManager implements FontMetrics {
         url: string;
         format: string;
     } | undefined;
+    /**
+     * Whether a family can draw this code point at all. An embedded face answers from its `cmap`; a
+     * standard-14 one can only draw what Windows-1252 encodes, which is what its `/Widths` array covers.
+     * 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;
-    encodeCustomText(name: string, text: string, style?: FontStyle): string;
+    /** How many glyphs a run draws - its code-point count unless a ligature merged some. `letterSpacing`
+     *  is per glyph (`Tc`), so this is what it multiplies. */
+    shapedGlyphCount(text: string, fontFamily?: string, fontStyle?: FontStyle, ligatures?: boolean): number | undefined;
+    /**
+     * The shaped glyphs of a run, or undefined when nothing needed shaping. The ONE place shaping is
+     * decided, so measuring and drawing cannot disagree. Memoised: a paragraph is measured several
+     * times (layout, pagination, drawing).
+     */
+    shapeText(text: string, fontFamily?: string, fontStyle?: FontStyle, features?: readonly string[]): ShapedGlyph[] | undefined;
+    /** Hex Identity-H for glyphs the producer already resolved (a shaped run), which cannot be given as
+     *  text. Recording each keeps it in the subset. */
+    registerGlyphs(name: string, glyphs: readonly number[], style?: FontStyle): string;
+    encodeCustomText(name: string, text: string, style?: FontStyle, shape?: boolean): string;
     private buildFontFile2;
     private buildFontDescriptor;
     private buildCIDFont;
@@ -154,7 +192,10 @@ export declare class PDFObjectManager implements FontMetrics {
      * Standard-14 answers from the AFM `KPX` pairs. An embedded font has no kerning yet (its `kern` /
      * `GPOS` tables are unparsed), so it returns zeros - never a wrong value, just no adjustment.
      */
-    getKernPairs(text: string, fontFamily: string, fontStyle: FontStyle): number[];
+    /** Kerning between adjacent GLYPHS - what a shaped run needs, and what the backend already holds.
+     *  Same lookup as the character path; `getKerning` is keyed by glyph id either way. */
+    getGlyphKernPairs(glyphs: readonly number[], fontFamily: string, fontStyle: FontStyle): number[];
+    getKernPairs(text: string, fontFamily: string, fontStyle: FontStyle, ligatures?: boolean): number[];
     /**
      * Where the glyphs of `text` put ink inside a horizontal band, as x-intervals in POINTS measured
      * from the start of the run. This is what an underline steps around ("skip-ink").
@@ -164,7 +205,7 @@ export declare class PDFObjectManager implements FontMetrics {
      * Callers must check `isCustomFont` first rather than treat an empty result as "no descenders".
      */
     getInkSpansInBand(text: string, fontSize: number, fontFamily: string, fontStyle: FontStyle, bandTop: number, bandBottom: number, letterSpacing?: number): Array<[number, number]>;
-    getStringWidth(text: string, fontFamily: string, fontSize: number, fontStyle: FontStyle): number;
+    getStringWidth(text: string, fontFamily: string, fontSize: number, fontStyle: FontStyle, ligatures?: boolean): number;
     private getAVMParserByFont;
     getCharWidth(char: string, fontSize: number, fullFontName?: string, fontName?: string, fontStyle?: FontStyle): number;
     getAllFontsRaw(): Map<string, FontIndexes>;

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

@@ -5,8 +5,17 @@ import { zlibSync } from "fflate";
 import { bytesFromLatin1, latin1FromBytes } from "./bytes.js";
 import { AFMParser } from "./afm-parser.js";
 import { mergeSpans, TTFParser } from "./ttf-parser.js";
+import { WoffError, isWoff, woffToSfnt } from "./woff.js";
+import { isWoff2 } from "./woff2.js";
 import { subsetTTF } from "./ttf-subsetter.js";
-import { getArrayBuffer } from "./utf8-to-windows1252-encoder.js";
+import { shapeRun } from "../text/shape.js";
+/** What Latin text is shaped with unless a run says otherwise: the ligatures a font's designer
+ *  drew for it. On by default like kerning - CSS, browsers and every other renderer do the same,
+ *  and nobody should have to know the word to get text that is set properly. */
+const LATIN_FEATURES = ["liga"];
+/** What a run is shaped with. Arabic joining is unconditional; this is only the Latin part. */
+const features = (ligatures) => (ligatures ? LATIN_FEATURES : []);
+import { getArrayBuffer, isWindows1252 } from "./utf8-to-windows1252-encoder.js";
 import { isEmojiCodePoint } from "../text/emoji-codepoints.js";
 import { StructTree } from "./struct-tree.js";
 import { OutlineBuilder } from "./outline.js";
@@ -161,6 +170,11 @@ export class PDFObjectManager {
         // Per-registered face: the reserved font-object numbers + the glyph ids actually used. The font
         // program is subsetted and the objects filled in by finalizeCustomFonts(), after the render pass.
         this.customFontEmit = new Map();
+        // Shaped runs, keyed by font + text; `null` means "asked, and there was nothing to shape".
+        this.shapeCache = new Map();
+        // Per font, glyph -> the code points it stands for. A shaped glyph is often absent from the cmap (a
+        // ligature) or maps back to a presentation form, so `ToUnicode` cannot come from the cmap alone.
+        this.shapedOrigins = new Map();
         // Embedded file attachments (their /Filespec object numbers + display names). Referenced from
         // the catalog's /Names/EmbeddedFiles + /AF. Drives ZUGFeRD's embedded factur-x.xml.
         this.attachments = [];
@@ -182,6 +196,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
@@ -209,8 +232,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;
     }
@@ -558,7 +587,18 @@ endstream`;
         }
         if (byStyle.has(style))
             return;
-        byStyle.set(style, new TTFParser(data));
+        // A WOFF is the same sfnt behind a small wrapper, so it is unpacked HERE - the one place every
+        // font path meets (a file, raw bytes, a URL, a browser upload) - and TTFParser never learns a
+        // second container format.
+        // WOFF2 cannot be unwrapped here: its Brotli decoder is imported lazily, which makes it async,
+        // and this is a synchronous constructor path. `renderPdf` unwraps it one step earlier - so the
+        // only way to arrive here still packed is by calling the engine directly.
+        if (isWoff2(data)) {
+            throw new WoffError("a WOFF2 font reached the object manager still packed. Pass it through " +
+                "renderToBytes(doc, { fonts }) or doc.addFont(...) - unpacking WOFF2 needs Brotli, which " +
+                "is loaded asynchronously, so it happens one step earlier in renderPdf.");
+        }
+        byStyle.set(style, new TTFParser(isWoff(data) ? woffToSfnt(data) : data));
         this.verticalsCache.delete(name); // this family now answers from the .ttf, not from an AFM
         this.decorationCache.delete(name);
         // Emission (the PDF font objects + page resource) is DEFERRED to first use via ensureEmitted(),
@@ -595,13 +635,13 @@ endstream`;
     // Fills the reserved font objects with a SUBSET of each font (only the glyphs the document used),
     // tagged "ABCDEF+" as PDF/A requires for subsets. Call once, after the render pass, before output.
     finalizeCustomFonts() {
-        for (const e of this.customFontEmit.values()) {
+        for (const [key, e] of this.customFontEmit) {
             const ttf = e.ttf;
             const base = `${this.subsetTag(e.pdfName, e.used)}+${e.pdfName}`;
             this.replaceObject(e.fontFile, this.buildFontFile2(ttf, e.used));
             this.replaceObject(e.descriptor, this.buildFontDescriptor(base, ttf, e.fontFile));
             this.replaceObject(e.cidFont, this.buildCIDFont(base, ttf, e.descriptor, e.used));
-            this.replaceObject(e.toUnicode, this.buildToUnicode(ttf, e.used));
+            this.replaceObject(e.toUnicode, this.buildToUnicode(ttf, e.used, this.shapedOrigins.get(key)));
             this.replaceObject(e.type0, this.buildType0(base, e.cidFont, e.toUnicode));
         }
     }
@@ -673,6 +713,34 @@ endstream`;
         return this.emojiImage;
     }
     // Whether `ttf` has a COLOR glyph for a code point (i.e. it would render it as color emoji).
+    /**
+     * Whether a family can draw this code point at all. An embedded face answers from its `cmap`; a
+     * standard-14 one can only draw what Windows-1252 encodes, which is what its `/Widths` array covers.
+     * Used to pick a family out of a fallback stack, per code point.
+     */
+    hasGlyph(codePoint, fontFamily, fontStyle = FontStyle.Normal) {
+        const ttf = this.getCustomFont(fontFamily, fontStyle);
+        if (ttf)
+            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;
     }
@@ -685,9 +753,56 @@ endstream`;
         this.ensureEmitted(name, resolved);
         return this.fonts.getFont(name, resolved);
     }
+    /** How many glyphs a run draws - its code-point count unless a ligature merged some. `letterSpacing`
+     *  is per glyph (`Tc`), so this is what it multiplies. */
+    shapedGlyphCount(text, fontFamily, fontStyle, ligatures = true) {
+        return this.shapeText(text, fontFamily, fontStyle, features(ligatures))?.length;
+    }
+    /**
+     * The shaped glyphs of a run, or undefined when nothing needed shaping. The ONE place shaping is
+     * decided, so measuring and drawing cannot disagree. Memoised: a paragraph is measured several
+     * times (layout, pagination, drawing).
+     */
+    shapeText(text, fontFamily, fontStyle = FontStyle.Normal, features = LATIN_FEATURES) {
+        const resolved = this.resolveCustomStyle(fontFamily, fontStyle);
+        if (!resolved)
+            return undefined;
+        const key = `${this.customKey(fontFamily, resolved)}\u0000${features.join(",")}\u0000${text}`;
+        const cached = this.shapeCache.get(key);
+        if (cached !== undefined)
+            return cached ?? undefined;
+        const ttf = this.customFonts.get(fontFamily).get(resolved);
+        const shaped = shapeRun([...text].map((c) => c.codePointAt(0)), ttf, features) ?? null;
+        this.shapeCache.set(key, shaped);
+        if (shaped) {
+            // Recorded at shaping time - the only moment the glyph and its code points are known together.
+            const fontKey = this.customKey(fontFamily, resolved);
+            let origins = this.shapedOrigins.get(fontKey);
+            if (!origins)
+                this.shapedOrigins.set(fontKey, (origins = new Map()));
+            for (const g of shaped)
+                origins.set(g.glyph, g.codePoints);
+        }
+        return shaped ?? undefined;
+    }
+    /** Hex Identity-H for glyphs the producer already resolved (a shaped run), which cannot be given as
+     *  text. Recording each keeps it in the subset. */
+    registerGlyphs(name, glyphs, style = FontStyle.Normal) {
+        const resolved = this.resolveCustomStyle(name, style);
+        if (!resolved)
+            return "";
+        this.ensureEmitted(name, resolved);
+        const emit = this.customFontEmit.get(this.customKey(name, resolved));
+        let out = "";
+        for (const g of glyphs) {
+            emit.used.add(g);
+            out += g.toString(16).padStart(4, "0").toUpperCase();
+        }
+        return out;
+    }
     // Encodes text as a hex Identity-H string for an embedded font's Tj operator: each codepoint
     // becomes its 2-byte glyph id (CID == GID under /CIDToGIDMap /Identity).
-    encodeCustomText(name, text, style = FontStyle.Normal) {
+    encodeCustomText(name, text, style = FontStyle.Normal, shape = true) {
         const resolved = this.resolveCustomStyle(name, style);
         if (!resolved)
             return "";
@@ -695,11 +810,24 @@ endstream`;
         // Once per text run, not per character: the flat key is fine here.
         const emit = this.customFontEmit.get(this.customKey(name, resolved));
         const { ttf, used } = emit;
+        const hex4 = (gid) => gid.toString(16).padStart(4, "0").toUpperCase();
+        // The SAME shaped run the measuring path used, so the glyphs drawn are the glyphs measured.
+        // `shape: false` is for a caller that has ALREADY decided the run is unshaped - the renderer puts
+        // shaped glyphs in the IR node, so the backend's text path is the unshaped one by definition.
+        const shaped = shape ? this.shapeText(text, name, style) : undefined;
+        if (shaped) {
+            let out = "";
+            for (const g of shaped) {
+                used.add(g.glyph);
+                out += hex4(g.glyph);
+            }
+            return out;
+        }
         let hex = "";
         for (const ch of text) {
             const gid = ttf.getGlyphIndex(ch.codePointAt(0));
             used.add(gid); // record the glyph so the subset keeps it
-            hex += gid.toString(16).padStart(4, "0").toUpperCase();
+            hex += hex4(gid);
         }
         return hex;
     }
@@ -732,17 +860,24 @@ endstream`;
     }
     // Maps glyph id -> Unicode so the text stays copy-/searchable (rendering doesn't need it). Only
     // the used glyphs are listed, to match the subset.
-    buildToUnicode(ttf, used) {
+    buildToUnicode(ttf, used, shapedOrigins = new Map()) {
         const hex4 = (n) => n.toString(16).padStart(4, "0").toUpperCase();
+        // A code point above the BMP needs its surrogate PAIR here - a `bfchar` destination is UTF-16BE.
+        const utf16 = (code) => code > 0xffff
+            ? hex4(0xd800 + ((code - 0x10000) >> 10)) + hex4(0xdc00 + ((code - 0x10000) & 0x3ff))
+            : hex4(code);
         const rev = ttf.reverseCmap();
+        // A SHAPED glyph wins: it is often absent from the cmap (a ligature) or maps back to a
+        // presentation form rather than the letter that was written (a joining form), so the reverse
+        // cmap alone would make copied text wrong.
         const entries = [...used]
             .sort((a, b) => a - b)
-            .filter((g) => rev.has(g))
-            .map((g) => [g, rev.get(g)]);
+            .filter((g) => shapedOrigins.has(g) || rev.has(g))
+            .map((g) => [g, shapedOrigins.get(g) ?? [rev.get(g)]]);
         const blocks = [];
         for (let i = 0; i < entries.length; i += 100) {
             const block = entries.slice(i, i + 100);
-            const lines = block.map(([gid, code]) => `<${hex4(gid)}> <${hex4(code)}>`);
+            const lines = block.map(([gid, codes]) => `<${hex4(gid)}> <${codes.map(utf16).join("")}>`);
             blocks.push(`${block.length} beginbfchar\n${lines.join("\n")}\nendbfchar`);
         }
         const body = `/CIDInit /ProcSet findresource begin\n12 dict begin\nbegincmap\n` +
@@ -814,10 +949,30 @@ endstream`;
      * Standard-14 answers from the AFM `KPX` pairs. An embedded font has no kerning yet (its `kern` /
      * `GPOS` tables are unparsed), so it returns zeros - never a wrong value, just no adjustment.
      */
-    getKernPairs(text, fontFamily, fontStyle) {
+    /** Kerning between adjacent GLYPHS - what a shaped run needs, and what the backend already holds.
+     *  Same lookup as the character path; `getKerning` is keyed by glyph id either way. */
+    getGlyphKernPairs(glyphs, fontFamily, fontStyle) {
+        const ttf = this.getCustomFont(fontFamily, fontStyle);
+        if (!ttf)
+            return [];
+        const pairs = [];
+        for (let i = 0; i < glyphs.length - 1; i++) {
+            pairs.push(ttf.getKerning(glyphs[i], glyphs[i + 1]));
+        }
+        return pairs;
+    }
+    getKernPairs(text, fontFamily, fontStyle, ligatures = true) {
         const chars = [...text];
         if (chars.length < 2)
             return [];
+        // A shaped run kerns over its SHAPED glyphs, not its characters: after shaping there may be fewer
+        // glyphs than code points (a ligature), and the pairs that matter are the ones actually drawn.
+        // `getKerning` is keyed by glyph id anyway, so this is the same lookup - and the backend now emits
+        // a `TJ` over glyph chunks, which is what used to be missing. One adjustment per adjacent DRAWN
+        // pair, either path, so `runAdvance` measures exactly what is drawn.
+        const shaped = this.shapeText(text, fontFamily, fontStyle, features(ligatures));
+        if (shaped)
+            return this.getGlyphKernPairs(shaped.map((g) => g.glyph), fontFamily, fontStyle);
         const out = [];
         // An embedded font kerns by GLYPH id (kern table / GPOS); a standard-14 one by character (AFM).
         const ttf = this.getCustomFont(fontFamily, fontStyle);
@@ -868,7 +1023,14 @@ endstream`;
         return mergeSpans(spans);
     }
     // Returns the current width of a text, included kernings
-    getStringWidth(text, fontFamily, fontSize, fontStyle) {
+    getStringWidth(text, fontFamily, fontSize, fontStyle, ligatures = true) {
+        // Shaping first: a joined run is narrower than the same letters apart, so measuring the unshaped
+        // form while drawing the shaped one would break every line. Both sides ask `shapeText`.
+        const shaped = this.shapeText(text, fontFamily, fontStyle, features(ligatures));
+        if (shaped) {
+            const ttf = this.getCustomFont(fontFamily, fontStyle);
+            return shaped.reduce((w, g) => w + ttf.unitsToPoints(g.advance, fontSize), 0);
+        }
         let width = 0;
         // Iterate code points, not UTF-16 units: an astral char (emoji, CJK-ext) is a surrogate pair,
         // and indexing by unit would measure each half as its own (zero-width) "char". The spread splits

package/dist/utils/renderer-registry.d.ts

@@ -1,6 +1,18 @@
+/**
+ * Thrown when an element reaches the render pass with no registered renderer.
+ *
+ * This used to return undefined and every call site skipped the element silently, so a whole document
+ * could serialize to an empty content stream and still be a valid PDF - a blank page, no warning
+ * (ISSUE-11). The registry is keyed on the CONSTRUCTOR, which makes it the one place in the engine that
+ * two loaded copies of the library break: elements built by copy A are invisible to copy B.
+ */
+export declare class MissingRendererError extends Error {
+    readonly elementName: string;
+    constructor(elementName: string);
+}
 export declare class RendererRegistry {
     private static renderers;
     static register(elementClass: Function, renderer: Function): void;
-    static getRenderer(element: object): Function | undefined;
+    static getRenderer(element: object): Function;
     static isRendererAsync(renderer: Function): boolean;
 }