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

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

@@ -1,57 +1,32 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.PDFObjectManager = exports.FontStyle = void 0;
-const page_sizes_1 = require("../constants/page-sizes");
-const fs = __importStar(require("fs"));
-const path = __importStar(require("path"));
-const crypto_1 = require("crypto");
-const zlib_1 = require("zlib");
-const afm_parser_1 = require("./afm-parser");
-const ttf_parser_1 = require("./ttf-parser");
-const ttf_subsetter_1 = require("./ttf-subsetter");
+import { pageFormats, PageSize } from "../constants/page-sizes.js";
+import { STANDARD_AFM } from "../assets/font-data.js";
+import { md5, md5Hex } from "./md5.js";
+import { zlibSync } from "fflate";
+import { bytesFromLatin1, latin1FromBytes } from "./bytes.js";
+import { AFMParser } from "./afm-parser.js";
+import { mergeSpans, TTFParser } from "./ttf-parser.js";
+import { isWoff, woffToSfnt } from "./woff.js";
+import { subsetTTF } from "./ttf-subsetter.js";
+import { shapeRun } from "../text/shape.js";
+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";
+import { DestRegistry } from "./dest-registry.js";
+import { AcroFormCollector } from "../forms/acroform.js";
 // Enums come from the leaf config module (never in a cycle); the config type is
 // erased at runtime so it can come from the cyclic module safely.
-const pdf_config_1 = require("../renderer/pdf-config");
-var FontStyle;
+import { ColorMode, Orientation } from "../renderer/pdf-config.js";
+export var FontStyle;
 (function (FontStyle) {
     FontStyle["Normal"] = "normal";
     FontStyle["Bold"] = "bold";
     FontStyle["Italic"] = "italic";
     FontStyle["BoldItalic"] = "boldItalic";
-})(FontStyle || (exports.FontStyle = FontStyle = {}));
+})(FontStyle || (FontStyle = {}));
+// Escapes a string into a valid PDF /Name token. A raw space or delimiter in a /Name (e.g. a font
+// family like "Great Vibes" or "Times New Roman") breaks the dictionary, so such chars become #XX.
+const pdfName = (s) => s.replace(/[^\x21-\x7e]|[#()<>[\]{}/%]/g, (c) => "#" + c.charCodeAt(0).toString(16).toUpperCase().padStart(2, "0"));
 // Suffix appended to an embedded font's PDF /BaseFont so each style variant of a family keeps
 // a distinct name (the variants are otherwise selected by the font resource, not the name).
 const STYLE_SUFFIX = {
@@ -152,7 +127,19 @@ class FontManager {
         return `${fontName}-${fontStyle}`;
     }
 }
-class PDFObjectManager {
+export class PDFObjectManager {
+    get struct() {
+        return this._struct;
+    }
+    get outline() {
+        return this._outline;
+    }
+    get dests() {
+        return this._dests;
+    }
+    get acroform() {
+        return this._acroform;
+    }
     constructor(pageSize) {
         this.objects = [];
         this.objectPositions = [];
@@ -160,24 +147,64 @@ class PDFObjectManager {
         this.fonts = new FontManager(); // Stores the fonts
         this.images = new ImageManager(); // Stores the images (object numbers and names)
         this.extGStates = new ExtGStateManager(); // Transparency states
-        this.pageFormat = page_sizes_1.pageFormats[page_sizes_1.PageSize.A4];
+        this.shadings = new Map(); // gradient resource name -> object number
+        this.pageFormat = pageFormats[PageSize.A4];
         this.afmParsers = [];
         // Embedded TrueType fonts, keyed by the name the user registers them under. When a font
         // name is in here the metric/emission paths take the TTF branch instead of the AFM one.
+        // Nested by family, then by style. The flat `${name}-${style}` key it replaced had to be BUILT on
+        // every lookup, and the lookups happen once per character - the string allocation alone was a third
+        // of a custom-font render. `customFontEmit` below keeps the flat key: it is touched once per face.
         this.customFonts = new Map();
+        // Memoised getFontVerticals answers, family -> style -> metrics. Cleared when a font registers.
+        this.verticalsCache = new Map();
+        // Same, for getFontDecoration.
+        this.decorationCache = new Map();
         // 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 = [];
         // PDF header version (PDF/A-3 needs 1.7) and whether to write a trailer /ID (PDF/A needs one).
-        // Both default to the pre-PDF/A behaviour, so a normal document stays byte-identical.
+        // Both default to the pre-PDF/A behavior, so a normal document stays byte-identical.
         this.pdfVersion = "1.4";
         this.documentId = false;
         this.compress = false;
+        this.overflowPolicy = "error";
+        this.encJobs = [];
+        this.strJobs = [];
+        // Accessible (PDF/UA) tagging, off by default (byte-identical output); the API turns it on.
+        this._struct = new StructTree();
+        // Document outline (bookmarks). Empty unless a `Bookmark` was placed; then finalize() emits /Outlines.
+        this._outline = new OutlineBuilder();
+        // Named destinations (internal-link jump targets). Empty unless an `Anchor` was placed; then it emits
+        // a /Names /Dests tree.
+        this._dests = new DestRegistry();
+        // 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
+        // fonts finer than a user's own font, which is worse than none. Flip to on when GPOS lands.
+        this.kerningEnabled = false;
         if (pageSize)
-            this.pageFormat = page_sizes_1.pageFormats[pageSize];
+            this.pageFormat = pageFormats[pageSize];
         this.fillConfigWithStandardValues();
     }
     // Adds an object and returns its number
@@ -198,40 +225,108 @@ class PDFObjectManager {
     setCompress(on) {
         this.compress = on;
     }
+    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;
+    }
+    getOverflowPolicy() {
+        return this.overflowPolicy;
+    }
+    // A unique, binary-safe placeholder for a stream's bytes, swapped for ciphertext in finalizeEncryption().
+    encToken(id) {
+        return `
JENC:${id}
`;
+    }
+    // The same trick for a literal STRING. A separate marker because the two are swapped differently: a
+    // stream keeps its delimiters and only the payload changes, a string is replaced whole by a hex one.
+    strToken(id) {
+        return `\x00\x02JSTR:${id}\x02\x00`;
+    }
+    /**
+     * The single choke-point every literal string in an OBJECT goes through - a field's `/T` and `/V`, a
+     * bookmark `/Title`, a link `/URI`, an `/Alt` text, a destination name.
+     *
+     * Without a security handler this is the escaped literal we have always written, so output stays
+     * byte-identical. With one, the raw bytes are registered for the finalize pass and a placeholder takes
+     * their place: ISO 32000-1 7.6.2 requires ALL strings and streams to be encrypted, and the ones missed
+     * here were exactly the values a password is supposed to protect (ISSUE-7).
+     *
+     * A string INSIDE a content stream needs none of this - the stream is enciphered as a whole.
+     */
+    pdfString(text) {
+        if (!this.security) {
+            return `(${text.replace(/\\/g, "\\\\").replace(/\(/g, "\\(").replace(/\)/g, "\\)")})`;
+        }
+        // Encrypt the bytes the unencrypted path would have written, so a viewer decrypts to the same value.
+        // No escaping is applied: the result is emitted as a HEX string, which has no escapes to get wrong.
+        const bytes = new Uint8Array(getArrayBuffer(text));
+        const id = this.strJobs.push(bytes) - 1;
+        return this.strToken(id);
+    }
+    // The single encryption choke-point every stream emitter routes through (stream(), registerImage). Without
+    // a security handler: the bytes as a latin1 string + their length. With one: register the raw bytes for the
+    // finalize pass and return a placeholder + the pre-computable encrypted length (16-byte IV + PKCS#7 padding).
+    streamPayload(bytes) {
+        if (!this.security)
+            return { body: latin1FromBytes(bytes), length: bytes.length };
+        const id = this.encJobs.push(bytes) - 1;
+        return { body: this.encToken(id), length: 16 + (Math.floor(bytes.length / 16) + 1) * 16 };
+    }
     // Builds a stream object body: `<< extraDict /Length n >> stream … endstream`, FlateDecode-compressed
-    // when enabled AND it actually helps (tiny streams aren't inflated). Binary bytes ride as a latin1
-    // string - the final encoder passes 0x00-0xFF through unchanged.
+    // when enabled AND it actually helps (tiny streams aren't inflated). The payload rides through
+    // streamPayload, so it is encrypted uniformly when a security handler is set.
     stream(extraDict, data) {
         const head = extraDict ? extraDict + " " : "";
+        let body = data;
+        let filter = "";
         if (this.compress) {
-            const z = (0, zlib_1.deflateSync)(data);
+            const z = zlibSync(data);
             if (z.length < data.length) {
-                return `<< ${head}/Filter /FlateDecode /Length ${z.length} >>\nstream\n${z.toString("latin1")}\nendstream`;
+                body = z;
+                filter = "/Filter /FlateDecode ";
             }
         }
-        return `<< ${head}/Length ${data.length} >>\nstream\n${data.toString("latin1")}\nendstream`;
+        const p = this.streamPayload(body);
+        return `<< ${head}${filter}/Length ${p.length} >>\nstream\n${p.body}\nendstream`;
     }
     // Adds a page content stream (compressed when enabled). The caller passes the raw operator string.
+    // Bytes go through the Windows-1252 encoder (NOT a latin1 low-byte cast): a Tj literal may carry a
+    // CP1252 char like "…"/"—"/"€" whose codepoint is > 0xFF, and latin1 would mangle it (… -> "&").
+    // For every char <= 0xFF the encoder passes the byte through, so existing streams stay byte-identical.
     addContentStream(content) {
-        return this.addObject(this.stream("", Buffer.from(content, "latin1")));
+        return this.addObject(this.stream("", new Uint8Array(getArrayBuffer(content))));
+    }
+    // A Form XObject: a self-contained content stream with its own /BBox (+ optional /Resources). Used for
+    // form-field appearance streams (/AP). Routes through the same choke-point as page content, so
+    // compression and encryption apply. Returns the object number.
+    addFormXObject(bbox, content, resources) {
+        const dict = `/Type /XObject /Subtype /Form /BBox ${bbox}` +
+            (resources ? ` /Resources << ${resources} >>` : "");
+        return this.addObject(this.stream(dict, new Uint8Array(getArrayBuffer(content))));
     }
     changePDFConfig(config) {
-        this.pdfConfig = Object.assign(Object.assign({}, this.pdfConfig), config);
+        this.pdfConfig = { ...this.pdfConfig, ...config };
     }
     getPDFConfig() {
         return this.pdfConfig;
     }
     fillConfigWithStandardValues() {
         this.pdfConfig = {
-            orientation: pdf_config_1.Orientation.portrait,
+            orientation: Orientation.portrait,
             defaultFont: {
                 fontFamily: "Helvetica",
                 fontSize: 12,
                 fontStyle: FontStyle.Normal,
             },
-            pageSize: page_sizes_1.PageSize.A4,
+            pageSize: PageSize.A4,
             margin: { left: 72, top: 72, bottom: 72, right: 72 },
-            colorMode: pdf_config_1.ColorMode.color,
+            colorMode: ColorMode.color,
         };
     }
     // Calculates the total length of the document in bytes (for XRef)
@@ -240,10 +335,8 @@ class PDFObjectManager {
         for (let i = 0; i < this.objects.length; i++) {
             const obj = this.objects[i];
             const objectContent = `${i + 1} 0 obj\n${obj}\nendobj\n`;
-            // Convert the object content into a buffer with the correct encoding
-            const encodedContent = Buffer.from(objectContent, "binary");
-            // Add the actual byte length to the total length
-            length += encodedContent.length;
+            // The body is a latin1/binary string (every char <= 0xFF), so its length IS its byte length.
+            length += objectContent.length;
         }
         return length;
     }
@@ -256,7 +349,25 @@ class PDFObjectManager {
         return this.parentObjectNumber;
     }
     // Registers an image
-    registerImage(width, height, imageType, imageData) {
+    registerImage(width, height, imageType, imageData, smaskData) {
+        // A transparent PNG carries its alpha as a separate DeviceGray /SMask image the viewer composites with.
+        let smaskEntry = "";
+        if (smaskData) {
+            const s = this.streamPayload(bytesFromLatin1(smaskData));
+            const smaskObject = `<< /Type /XObject
+    /Subtype /Image
+    /Width ${width}
+    /Height ${height}
+    /ColorSpace /DeviceGray
+    /BitsPerComponent 8
+    /Filter /FlateDecode
+    /Length ${s.length} >>
+stream
+${s.body}
+endstream`;
+            smaskEntry = `    /SMask ${this.addObject(smaskObject)} 0 R\n`;
+        }
+        const img = this.streamPayload(bytesFromLatin1(imageData));
         const imageObject = `<< /Type /XObject
     /Subtype /Image
     /Width ${width}
@@ -264,9 +375,9 @@ class PDFObjectManager {
     /ColorSpace /DeviceRGB
     /BitsPerComponent 8
     /Filter /${imageType}
-    /Length ${imageData.length} >>
+${smaskEntry}    /Length ${img.length} >>
 stream
-${imageData} 
+${img.body}
 endstream`;
         // Add the image and its object number to the image manager - return the object number
         const imageObjectNumber = this.addObject(imageObject);
@@ -278,13 +389,11 @@ endstream`;
     // `relationship` is the /AFRelationship (e.g. "Data" for the ZUGFeRD factur-x.xml). Binary bytes
     // ride as a latin1 string, like images/fonts (the final encoder passes 0x00-0xFF through).
     attachFile(name, data, opts = {}) {
-        var _a, _b;
-        const subtype = ((_a = opts.mimeType) !== null && _a !== void 0 ? _a : "application/octet-stream").replace(/\//g, "#2F");
+        const subtype = (opts.mimeType ?? "application/octet-stream").replace(/\//g, "#2F");
         const embedded = this.addObject(this.stream(`/Type /EmbeddedFile /Subtype /${subtype} /Params << /Size ${data.length} >>`, data));
-        const escaped = (s) => s.replace(/\\/g, "\\\\").replace(/\(/g, "\\(").replace(/\)/g, "\\)");
-        const desc = opts.description ? ` /Desc (${escaped(opts.description)})` : "";
-        const filespec = this.addObject(`<< /Type /Filespec /F (${escaped(name)}) /UF (${escaped(name)}) ` +
-            `/AFRelationship /${(_b = opts.relationship) !== null && _b !== void 0 ? _b : "Unspecified"}${desc} ` +
+        const desc = opts.description ? ` /Desc ${this.pdfString(opts.description)}` : "";
+        const filespec = this.addObject(`<< /Type /Filespec /F ${this.pdfString(name)} /UF ${this.pdfString(name)} ` +
+            `/AFRelationship /${opts.relationship ?? "Unspecified"}${desc} ` +
             `/EF << /F ${embedded} 0 R /UF ${embedded} 0 R >> >>`);
         this.attachments.push({ name, filespec });
     }
@@ -302,11 +411,10 @@ endstream`;
     // Embeds an ICC profile and a PDF/A /OutputIntent that points at it (catalog /OutputIntents).
     // `icc` are the raw profile bytes (an RGB profile, /N 3 - e.g. sRGB).
     setOutputIntent(icc, opts = {}) {
-        var _a, _b;
         const profile = this.addObject(this.stream("/N 3", icc));
         this.outputIntent = this.addObject(`<< /Type /OutputIntent /S /GTS_PDFA1 ` +
-            `/OutputConditionIdentifier (${(_a = opts.identifier) !== null && _a !== void 0 ? _a : "sRGB"}) ` +
-            `/Info (${(_b = opts.info) !== null && _b !== void 0 ? _b : "sRGB IEC61966-2.1"}) /DestOutputProfile ${profile} 0 R >>`);
+            `/OutputConditionIdentifier ${this.pdfString(opts.identifier ?? "sRGB")} ` +
+            `/Info ${this.pdfString(opts.info ?? "sRGB IEC61966-2.1")} /DestOutputProfile ${profile} 0 R >>`);
     }
     getOutputIntent() {
         return this.outputIntent;
@@ -331,6 +439,43 @@ endstream`;
     enableDocumentId() {
         this.documentId = true;
     }
+    // Turn on encryption: the handler encrypts every stream and supplies the /Encrypt dict. Forces a trailer
+    // /ID (encrypted PDFs require one) and PDF 2.0 (AES-256 R6). PDF/A forbids encryption - guarded at finalize.
+    setSecurityHandler(handler) {
+        this.security = handler;
+        this.documentId = true;
+        this.setPdfVersion("2.0");
+    }
+    // One async pass at the very end: refuse to encrypt a PDF/A document, then encrypt every registered stream
+    // (swap each placeholder for its ciphertext) and add the /Encrypt object the trailer references.
+    async finalizeEncryption() {
+        if (!this.security)
+            return;
+        if (this.outputIntent !== undefined || this.attachments.length > 0) {
+            throw new Error("@jasy/pdf: cannot encrypt a PDF/A document - PDF/A forbids encryption.");
+        }
+        for (let id = 0; id < this.encJobs.length; id++) {
+            const ciphertext = latin1FromBytes(await this.security.encrypt(this.encJobs[id]));
+            const token = this.encToken(id);
+            const idx = this.objects.findIndex((o) => o.includes(token));
+            // Function replacement: a string replacement would interpret `$&`/`$\``/... in the random ciphertext.
+            if (idx >= 0)
+                this.objects[idx] = this.objects[idx].replace(token, () => ciphertext);
+        }
+        // Strings: the same idea, but a string is replaced WHOLE - `(text)` becomes `<ciphertext>`. Hex,
+        // because the ciphertext is binary and a hex string has no escape rules to get wrong.
+        for (let id = 0; id < this.strJobs.length; id++) {
+            const cipher = await this.security.encrypt(this.strJobs[id]);
+            const hex = Array.from(cipher, (b) => b.toString(16).padStart(2, "0").toUpperCase()).join("");
+            const token = this.strToken(id);
+            const idx = this.objects.findIndex((o) => o.includes(token));
+            if (idx >= 0)
+                this.objects[idx] = this.objects[idx].replace(token, () => `<${hex}>`);
+        }
+        // Added LAST on purpose: the /Encrypt dictionary's own strings must stay in the clear (7.6.2), and
+        // they would otherwise be swept up by the pass above.
+        this.encryptObjNum = this.addObject(`<< ${this.security.encryptDict()} >>`);
+    }
     // Registers (or reuses) a transparency graphics state and returns its resource name
     // (e.g. "GS1"). `fillAlpha` -> /ca, `strokeAlpha` -> /CA. Deduped by the alpha pair.
     registerExtGState(fillAlpha, strokeAlpha) {
@@ -349,25 +494,73 @@ endstream`;
     getAllExtGStatesRaw() {
         return this.extGStates.getAll();
     }
+    // Registers a gradient as a PDF shading (+ its color-stop function) and returns the resource name
+    // (e.g. "Sh1"). Used to fill a color-glyph layer with a COLR v1 gradient. Not deduped: each layer
+    // carries page-absolute coordinates, so two calls rarely match.
+    registerShading(g) {
+        const fn = this.buildShadingFunction(g.stops);
+        const n = (x) => x.toFixed(3);
+        const coords = g.type === "linear"
+            ? `${n(g.x0)} ${n(g.y0)} ${n(g.x1)} ${n(g.y1)}`
+            : `${n(g.x0)} ${n(g.y0)} ${n(g.r0)} ${n(g.x1)} ${n(g.y1)} ${n(g.r1)}`;
+        const shadingType = g.type === "linear" ? 2 : 3;
+        // PDF shadings extend by clamping the end colors; "repeat"/"reflect" would need a tiling pattern,
+        // so we approximate them as clamp (pad) for now - correct for the common pad case.
+        const objectNumber = this.addObject(`<< /ShadingType ${shadingType} /ColorSpace /DeviceRGB /Coords [${coords}] ` +
+            `/Function ${fn} 0 R /Extend [true true] >>`);
+        const name = `Sh${this.shadings.size + 1}`;
+        this.shadings.set(name, objectNumber);
+        return name;
+    }
+    // Builds the PDF function mapping t in [0,1] to a color along the stops. Two stops collapse to one
+    // exponential (linear) function; more stops stitch one linear piece per interval (FunctionType 3).
+    buildShadingFunction(stops) {
+        const c = (i) => stops[i].color.toPDFColorString(); // "r g b" in 0..1
+        // Malformed / empty color line: fall back to opaque black instead of indexing an empty array.
+        if (stops.length === 0) {
+            return this.addObject("<< /FunctionType 2 /Domain [0 1] /C0 [0 0 0] /C1 [0 0 0] /N 1 >>");
+        }
+        if (stops.length <= 2) {
+            const c0 = c(0);
+            const c1 = c(stops.length - 1);
+            return this.addObject(`<< /FunctionType 2 /Domain [0 1] /C0 [${c0}] /C1 [${c1}] /N 1 >>`);
+        }
+        const pieces = [];
+        for (let i = 0; i < stops.length - 1; i++) {
+            pieces.push(this.addObject(`<< /FunctionType 2 /Domain [0 1] /C0 [${c(i)}] /C1 [${c(i + 1)}] /N 1 >>`));
+        }
+        const functions = pieces.map((p) => `${p} 0 R`).join(" ");
+        const bounds = stops
+            .slice(1, -1)
+            .map((s) => s.offset.toFixed(4))
+            .join(" ");
+        const encode = pieces.map(() => "0 1").join(" ");
+        return this.addObject(`<< /FunctionType 3 /Domain [0 1] /Functions [${functions}] /Bounds [${bounds}] /Encode [${encode}] >>`);
+    }
+    // Returns all registered gradient shadings (name -> object number) for the page /Resources.
+    getAllShadingsRaw() {
+        return this.shadings;
+    }
     // Registers a font
     registerFont(fontName, fontStyle = FontStyle.Normal, fullName = fontName) {
         if (this.fonts.hasFont(fontName, fontStyle)) {
             return this.fonts.getFont(fontName, fontStyle); // Already exists? Return it!
         }
-        const afmFilePath = path.resolve(__dirname, "../", `assets/${fullName}.afm`);
-        if (fs.existsSync(afmFilePath)) {
-            const data = fs.readFileSync(afmFilePath, "utf-8");
+        this.verticalsCache.delete(fontName);
+        this.decorationCache.delete(fontName);
+        const data = STANDARD_AFM[fullName];
+        if (data !== undefined) {
             this.afmParsers.push({
                 fontName,
                 fontStyle,
                 fullFontName: fullName,
-                parser: new afm_parser_1.AFMParser(data),
+                parser: new AFMParser(data),
             });
         }
         const resourceNumber = this.objects.length + 1; // New resource number
         const fontNumber = this.fonts.getLastFontIndex() + 1; // New font index number
         this.fonts.addFont(fontName, fontNumber, resourceNumber, fontStyle); // Store it
-        const fontObject = `<</BaseFont/${fullName}/Type/Font\n/Encoding/WinAnsiEncoding\n/Subtype/Type1>>`;
+        const fontObject = `<</BaseFont/${pdfName(fullName)}/Type/Font\n/Encoding/WinAnsiEncoding\n/Subtype/Type1>>`;
         this.addObject(fontObject);
         return {
             fontIndex: fontNumber,
@@ -380,10 +573,19 @@ endstream`;
     // metrics and emits its PDF font objects. All variants share the family `name`; bold/italic are
     // separate .ttf files registered under the same name with a different style.
     registerCustomFont(name, data, style = FontStyle.Normal) {
-        const key = this.customKey(name, style);
-        if (this.customFonts.has(key))
+        let byStyle = this.customFonts.get(name);
+        if (!byStyle) {
+            byStyle = new Map();
+            this.customFonts.set(name, byStyle);
+        }
+        if (byStyle.has(style))
             return;
-        this.customFonts.set(key, new ttf_parser_1.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.
+        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(),
         // so a registered-but-never-rendered face - e.g. a bundled family the document doesn't touch -
         // costs nothing in the output. The metrics above are still available for layout immediately.
@@ -406,6 +608,7 @@ endstream`;
         this.fonts.addFont(name, this.fonts.getLastFontIndex() + 1, type0, style, name, true);
         this.customFontEmit.set(key, {
             pdfName: name + STYLE_SUFFIX[style],
+            ttf: this.customFonts.get(name).get(style), // `style` is already resolved, so this exists
             fontFile,
             descriptor,
             cidFont,
@@ -418,20 +621,18 @@ endstream`;
     // tagged "ABCDEF+" as PDF/A requires for subsets. Call once, after the render pass, before output.
     finalizeCustomFonts() {
         for (const [key, e] of this.customFontEmit) {
-            const ttf = this.customFonts.get(key);
+            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));
         }
     }
     // A deterministic 6-uppercase-letter subset tag (PDF/A wants the "TAG+FontName" form).
     subsetTag(pdfName, used) {
-        const h = (0, crypto_1.createHash)("md5")
-            .update(pdfName + [...used].sort((a, b) => a - b).join(","))
-            .digest();
+        const h = md5(new TextEncoder().encode(pdfName + [...used].sort((a, b) => a - b).join(",")));
         let tag = "";
         for (let i = 0; i < 6; i++)
             tag += String.fromCharCode(65 + (h[i] % 26));
@@ -443,22 +644,91 @@ endstream`;
     // The variant to actually use for (name, style): the requested style if registered, else the
     // family's Normal as a clean fallback (e.g. bold chosen but no bold file), else undefined when
     // `name` is not a custom family at all.
+    //
+    // This runs once per CHARACTER (getCharWidth -> getCustomFont), and every paragraph is measured
+    // several times (layout, pagination, drawing), so it is the hottest function in the whole renderer.
+    // The size check is what keeps a standard-14 document from paying for a feature it never uses: with
+    // no custom font registered, neither lookup could ever hit, so there is nothing to look up.
     resolveCustomStyle(name, style = FontStyle.Normal) {
-        if (!name)
+        if (this.customFonts.size === 0 || !name)
+            return undefined;
+        const byStyle = this.customFonts.get(name);
+        if (!byStyle)
             return undefined;
-        if (this.customFonts.has(this.customKey(name, style)))
+        if (byStyle.has(style))
             return style;
-        if (this.customFonts.has(this.customKey(name, FontStyle.Normal)))
-            return FontStyle.Normal;
-        return undefined;
+        return byStyle.has(FontStyle.Normal) ? FontStyle.Normal : undefined;
     }
+    // The same lookup as above, but returning the font itself in ONE map walk instead of resolving the
+    // style and then looking the font up again under a freshly built key.
     getCustomFont(name, style = FontStyle.Normal) {
-        const resolved = this.resolveCustomStyle(name, style);
-        return resolved ? this.customFonts.get(this.customKey(name, resolved)) : undefined;
+        if (this.customFonts.size === 0 || !name)
+            return undefined;
+        const byStyle = this.customFonts.get(name);
+        if (!byStyle)
+            return undefined;
+        return byStyle.get(style) ?? byStyle.get(FontStyle.Normal);
     }
     isCustomFont(name, style = FontStyle.Normal) {
         return !!this.resolveCustomStyle(name, style);
     }
+    // The parsed font for a color-capable custom family (COLR/CPAL), for drawing emoji as vector
+    // layers. Returns undefined for standard-14 fonts, unknown names, or fonts with no color glyphs -
+    // the caller then draws normal monochrome text.
+    getColorFont(name, style = FontStyle.Normal) {
+        const ttf = this.getCustomFont(name, style);
+        return ttf?.hasColorGlyphs() ? ttf : undefined;
+    }
+    // The document's color-emoji fallback font: a code point the current text font can't color-render
+    // is drawn from this font's color glyphs instead (so `Text("Hallo 😅")` works in one string). Set
+    // via `Document({ emoji })`; must name a registered color font.
+    setEmojiFont(name) {
+        this.emojiFontName = name;
+    }
+    getEmojiFont() {
+        return this.emojiFontName;
+    }
+    // Alternative color-emoji source: raster images (a CDN like Twemoji, react-pdf style). The renderer
+    // fetches `${url}${hexCodePoint}.${format}` per emoji and embeds it. The font source is preferred
+    // (native vector); this exists for parity + as an escape hatch.
+    setEmojiImageSource(url, format) {
+        this.emojiImage = { url, format };
+    }
+    getEmojiImageSource() {
+        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;
+    }
     // The page font resource for the resolved variant - same resolution as getCustomFont, so the
     // selected Type0 object and the emitted glyph ids always come from the SAME font file.
     getCustomFontResource(name, style = FontStyle.Normal) {
@@ -468,6 +738,53 @@ 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) {
+        return this.shapeText(text, fontFamily, fontStyle)?.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) {
+        const resolved = this.resolveCustomStyle(fontFamily, fontStyle);
+        if (!resolved)
+            return undefined;
+        const key = `${this.customKey(fontFamily, resolved)}\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) ?? 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) {
@@ -475,27 +792,38 @@ endstream`;
         if (!resolved)
             return "";
         this.ensureEmitted(name, resolved);
-        const key = this.customKey(name, resolved);
-        const ttf = this.customFonts.get(key);
-        const used = this.customFontEmit.get(key).used;
+        // 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.
+        const shaped = this.shapeText(text, name, style);
+        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;
     }
     // The SUBSET font program (only the used glyphs' outlines). Binary bytes survive as a latin1
     // string - the final Windows-1252 encoder passes 0x00-0xFF through unchanged (see getArrayBuffer).
     buildFontFile2(ttf, used) {
-        const bytes = (0, ttf_subsetter_1.subsetTTF)(ttf.getData(), used);
+        const bytes = subsetTTF(ttf.getData(), used);
         // /Length1 is the UNCOMPRESSED font-program length (required even when FlateDecode'd).
         return this.stream(`/Length1 ${bytes.length}`, bytes);
     }
     buildFontDescriptor(name, ttf, fontFile) {
         const [x0, y0, x1, y1] = ttf.bbox;
-        return (`<< /Type /FontDescriptor /FontName /${name} /Flags 4 ` +
+        return (`<< /Type /FontDescriptor /FontName /${pdfName(name)} /Flags 4 ` +
             `/FontBBox [${x0} ${y0} ${x1} ${y1}] /ItalicAngle 0 ` +
             `/Ascent ${ttf.ascent} /Descent ${ttf.descent} /CapHeight ${ttf.ascent} /StemV 80 ` +
             `/FontFile2 ${fontFile} 0 R >>`);
@@ -506,26 +834,33 @@ endstream`;
         const all = ttf.glyphWidths();
         const w = [...used]
             .sort((a, b) => a - b)
-            .map((g) => { var _a; return `${g} [${(_a = all[g]) !== null && _a !== void 0 ? _a : 1000}]`; })
+            .map((g) => `${g} [${all[g] ?? 1000}]`)
             .join(" ");
-        return (`<< /Type /Font /Subtype /CIDFontType2 /BaseFont /${name} ` +
-            `/CIDSystemInfo << /Registry (Adobe) /Ordering (Identity) /Supplement 0 >> ` +
+        return (`<< /Type /Font /Subtype /CIDFontType2 /BaseFont /${pdfName(name)} ` +
+            `/CIDSystemInfo << /Registry ${this.pdfString("Adobe")} /Ordering ${this.pdfString("Identity")} /Supplement 0 >> ` +
             `/FontDescriptor ${descriptor} 0 R /CIDToGIDMap /Identity ` +
             `/DW 1000 /W [${w}] >>`);
     }
     // 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` +
@@ -533,34 +868,159 @@ endstream`;
             `/CMapName /Adobe-Identity-UCS def\n/CMapType 2 def\n` +
             `1 begincodespacerange\n<0000> <FFFF>\nendcodespacerange\n${blocks.join("\n")}\n` +
             `endcmap\nCMapName currentdict /CMap defineresource pop\nend\nend`;
-        return this.stream("", Buffer.from(body, "latin1"));
+        return this.stream("", bytesFromLatin1(body));
     }
     buildType0(name, cidFont, toUnicode) {
-        return (`<< /Type /Font /Subtype /Type0 /BaseFont /${name} /Encoding /Identity-H ` +
+        return (`<< /Type /Font /Subtype /Type0 /BaseFont /${pdfName(name)} /Encoding /Identity-H ` +
             `/DescendantFonts [${cidFont} 0 R] /ToUnicode ${toUnicode} 0 R >>`);
     }
+    // The vertical metrics of a face, in em fractions - what seats the baseline and sizes the line
+    // box (see text/line-metrics.ts). An embedded font answers from its own `hhea`; a standard-14
+    // font from its AFM header. Nothing here is guessed: both numbers come out of the font data.
+    //
+    // Asked once per LINE (not per character), but a long document has a lot of lines and the
+    // standard-14 lookup below is a linear scan, so the answer is memoised per face. Registering a
+    // font clears the cache - a name can go from standard-14 to embedded.
+    getFontVerticals(fontFamily, fontStyle) {
+        let byStyle = this.verticalsCache.get(fontFamily);
+        const hit = byStyle?.get(fontStyle);
+        if (hit)
+            return hit;
+        const ttf = this.getCustomFont(fontFamily, fontStyle);
+        const verticals = ttf
+            ? {
+                ascent: ttf.ascent / 1000,
+                descent: -ttf.descent / 1000, // hhea writes the descent negative
+                lineGap: ttf.lineGap / 1000,
+            }
+            : this.getAVMParserByFont(undefined, fontFamily, fontStyle).parser.verticals();
+        if (!byStyle) {
+            byStyle = new Map();
+            this.verticalsCache.set(fontFamily, byStyle);
+        }
+        byStyle.set(fontStyle, verticals);
+        return verticals;
+    }
+    // Underline / strikethrough geometry of a face, in em fractions. Same shape as getFontVerticals:
+    // an embedded font answers from its `post`/`OS/2` tables, a standard-14 one from its AFM header,
+    // and the answer is memoised per face because it is asked once per decorated run.
+    getFontDecoration(fontFamily, fontStyle) {
+        let byStyle = this.decorationCache.get(fontFamily);
+        const hit = byStyle?.get(fontStyle);
+        if (hit)
+            return hit;
+        const ttf = this.getCustomFont(fontFamily, fontStyle);
+        const decoration = ttf
+            ? ttf.decoration()
+            : this.getAVMParserByFont(undefined, fontFamily, fontStyle).parser.decoration();
+        if (!byStyle) {
+            byStyle = new Map();
+            this.decorationCache.set(fontFamily, byStyle);
+        }
+        byStyle.set(fontStyle, decoration);
+        return decoration;
+    }
+    setKerning(enabled) {
+        this.kerningEnabled = enabled;
+    }
+    /**
+     * The kerning adjustment for each adjacent code-point pair of `text`, in em/1000 (the sign the
+     * font declares: negative tightens). Length is `codePointCount - 1`. Zero at any pair next to a
+     * space - letters are never kerned against a space, which also keeps a per-word measure equal to a
+     * whole-line one (the space pairs contribute nothing either way).
+     *
+     * 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) {
+        const chars = [...text];
+        if (chars.length < 2)
+            return [];
+        // A shaped run does not kern here: these pairs are keyed by the UNSHAPED glyphs, and the `TJ`
+        // path would re-shape each chunk on its own, turning every letter isolated. Arabic kerning is in
+        // GPOS, applied during shaping - not built (`todo.md`).
+        if (this.shapeText(text, fontFamily, fontStyle))
+            return [];
+        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);
+        const parser = ttf
+            ? undefined
+            : this.getAVMParserByFont(undefined, fontFamily, fontStyle).parser;
+        for (let i = 0; i < chars.length - 1; i++) {
+            const a = chars[i];
+            const b = chars[i + 1];
+            if (a === " " || b === " ") {
+                out.push(0);
+            }
+            else if (ttf) {
+                out.push(ttf.getKerning(ttf.getGlyphIndex(a.codePointAt(0)), ttf.getGlyphIndex(b.codePointAt(0))));
+            }
+            else {
+                out.push(parser.getKerning(a, b));
+            }
+        }
+        return out;
+    }
+    /**
+     * 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").
+     *
+     * `bandTop` / `bandBottom` are in points relative to the baseline, y UP (so both negative under
+     * it). Only an EMBEDDED font can answer: the standard-14 outlines live in the viewer, not here.
+     * Callers must check `isCustomFont` first rather than treat an empty result as "no descenders".
+     */
+    getInkSpansInBand(text, fontSize, fontFamily, fontStyle, bandTop, bandBottom, letterSpacing = 0) {
+        const ttf = this.getCustomFont(fontFamily, fontStyle);
+        if (!ttf)
+            return [];
+        const scale = fontSize / ttf.unitsPerEm;
+        const spans = [];
+        let pen = 0;
+        for (const ch of text) {
+            const codePoint = ch.codePointAt(0);
+            if (codePoint !== undefined) {
+                for (const [x0, x1] of ttf.inkSpansInBand(codePoint, bandTop / scale, bandBottom / scale)) {
+                    spans.push([pen + x0 * scale, pen + x1 * scale]);
+                }
+            }
+            // The pen advances by the glyph AND its letter-spacing, so the ink of the next glyph lands
+            // where `Tc` actually draws it - otherwise the skipped gaps drift under the wrong letters.
+            pen += this.getCharWidth(ch, fontSize, undefined, fontFamily, fontStyle) + letterSpacing;
+        }
+        return mergeSpans(spans);
+    }
     // Returns the current width of a text, included kernings
     getStringWidth(text, fontFamily, fontSize, fontStyle) {
+        // 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);
+        if (shaped) {
+            const ttf = this.getCustomFont(fontFamily, fontStyle);
+            return shaped.reduce((w, g) => w + ttf.unitsToPoints(g.advance, fontSize), 0);
+        }
         let width = 0;
-        // We must calculate each sign
-        for (let i = 0; i < text.length; i++) {
-            const char = text[i];
-            const nextChar = text[i + 1] || null;
-            // Get signs width
-            const charWidth = this.getCharWidth(char, fontSize, undefined, fontFamily, fontStyle);
-            width += charWidth;
-            // If a next sign available calculate the kerning
-            if (nextChar) {
-                const kerning = this.getKerning(char, nextChar, undefined, fontFamily, fontStyle);
-                width += kerning * fontSize; // Kerning must be scaled with the font size
-            }
+        // 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
+        // on code points; for BMP text this is one unit each, so the result is unchanged.
+        //
+        // NO KERNING. We write a run as a single `Tj`, and a viewer advances that by the font's plain
+        // widths - PDF never kerns on its own; a producer has to say so with a `TJ` array. Folding the
+        // AFM's kerning into the MEASUREMENT while the OUTPUT ignores it made every kerned string draw
+        // wider than its box: "AVATAR Wave" at 40pt by 19pt, "Total" at 11pt by 5.7%. Measured must equal
+        // drawn. The AFM kerning pairs stay parsed (`getKerning`) for the day we emit `TJ` - see the
+        // "real kerning" item in todo.md, which must cover embedded fonts too (`kern`/`GPOS`).
+        for (const char of text) {
+            width += this.getCharWidth(char, fontSize, undefined, fontFamily, fontStyle);
         }
         return width;
     }
-    getCharCode(char) {
-        return char.charCodeAt(0).toString();
-    }
     getAVMParserByFont(fullFontName, fontName, fontStyle) {
+        // A non-string family means font bytes were passed where a name belongs - hint at the fix instead of
+        // stringifying the byte blob into an unreadable "parser not found".
+        for (const name of [fullFontName, fontName])
+            if (name != null && typeof name !== "string")
+                throw new Error(`Font family must be a string name, got ${typeof name}. Register font bytes via the document \`fonts\` map (or addFont) and reference them by name.`);
         if (!fullFontName && (!fontName || !fontStyle)) {
             throw new Error("No font family is given. Please set a full font name or a font with font style");
         }
@@ -577,26 +1037,40 @@ endstream`;
     }
     // Methode zur Berechnung der Zeichenbreite anhand der Schriftgröße
     getCharWidth(char, fontSize, fullFontName, fontName, fontStyle) {
-        const ttf = this.getCustomFont(fullFontName !== null && fullFontName !== void 0 ? fullFontName : fontName, fontStyle);
+        const name = fullFontName ?? fontName;
+        const ttf = this.getCustomFont(name, fontStyle);
+        // Color-emoji fallback: a code point the current font can't color-render is measured with the
+        // emoji font's advance (matching the renderer, which draws it from that font). Guarded on
+        // emojiFontName so a normal document's measuring stays byte-identical.
+        if (this.emojiFontName && this.emojiFontName !== name) {
+            const cp = char.codePointAt(0);
+            if (cp !== undefined && !(ttf && this.colorRenders(ttf, cp))) {
+                const emoji = this.getColorFont(this.emojiFontName, fontStyle);
+                if (emoji && this.colorRenders(emoji, cp))
+                    return emoji.getCharWidth(char, fontSize);
+            }
+        }
+        // Image emoji source: an emoji code point is drawn as a 1em-square image, so it advances one em.
+        if (this.emojiImage) {
+            const cp = char.codePointAt(0);
+            if (cp !== undefined && isEmojiCodePoint(cp) && !(ttf && this.colorRenders(ttf, cp))) {
+                return fontSize;
+            }
+        }
         if (ttf)
             return ttf.getCharWidth(char, fontSize);
         const currentParser = this.getAVMParserByFont(fullFontName, fontName, fontStyle);
-        const advanceWidth = currentParser.parser.getAdvanceWidth(char);
-        // Normally we got still zero. TODO: Return a alternative width like the "space"
+        let advanceWidth = currentParser.parser.getAdvanceWidth(char);
+        // A character a standard font cannot represent (not in Windows-1252) is drawn as "?" by the
+        // encoder; measure it as "?" too so the width matches the glyph - graceful instead of a crash.
         if (!advanceWidth) {
-            throw new Error(`Kein Metrik-Eintrag für Zeichen: ${char} ${this.getCharCode(char)}`);
+            advanceWidth =
+                currentParser.parser.getAdvanceWidth("?") || currentParser.parser.getAdvanceWidth(" ");
         }
         // Width of the character multiplied by the font size (scaled proportionally)
         return (advanceWidth / 1000) * fontSize;
     }
     // Method to get the kerning, if available, between two signs
-    getKerning(char, nextChar, fullFontName, fontName, fontStyle) {
-        // TrueType kerning (the kern/GPOS tables) is not wired up yet - no kerning for custom fonts.
-        if (this.getCustomFont(fullFontName !== null && fullFontName !== void 0 ? fullFontName : fontName, fontStyle))
-            return 0;
-        const currentParser = this.getAVMParserByFont(fullFontName, fontName, fontStyle);
-        return currentParser.parser.getKerning(char, nextChar) / 1000;
-    }
     // Returns all fonts
     getAllFontsRaw() {
         return this.fonts.getAllFonts();
@@ -632,14 +1106,14 @@ endstream`;
         const root = this.objects.findIndex((f) => f.toLowerCase().includes("catalog")) + 1;
         // A fresh document uses the same hash for both /ID strings; they only diverge on an update.
         const id = this.documentId ? ` /ID [${this.contentId()} ${this.contentId()}]` : "";
-        return `trailer\n<< /Size ${objectCount + 1} /Root ${root} 0 R${id} >>\nstartxref\n${startxref}\n%%EOF`;
+        const enc = this.encryptObjNum ? ` /Encrypt ${this.encryptObjNum} 0 R` : "";
+        return `trailer\n<< /Size ${objectCount + 1} /Root ${root} 0 R${id}${enc} >>\nstartxref\n${startxref}\n%%EOF`;
     }
     contentId() {
-        return `<${(0, crypto_1.createHash)("md5").update(this.objects.join("")).digest("hex").toUpperCase()}>`;
+        return `<${md5Hex(new TextEncoder().encode(this.objects.join(""))).toUpperCase()}>`;
     }
     // Returns the number of objects
     getObjectCount() {
         return this.objects.length;
     }
 }
-exports.PDFObjectManager = PDFObjectManager;