@jasy/pdf 1.0.0-alpha.4 → 1.0.0-alpha.5

package/dist/renderer/image-renderer.js

@@ -2,9 +2,9 @@ import { BoxFit } from "../elements/image-element.js";
 import { bytesFromLatin1 } from "../utils/bytes.js";
 import { applyContainFit, applyCoverFit, applyFillFit, applyFitNone, decodePngToRgbFlate, } from "../utils/image-helper.js";
 export class ImageRenderer {
-    static async render(imageElement, _objectManager) {
+    static async render(imageElement, objectManager) {
         // Load the image and convert it in a binary string
-        let { x, y, width, height, image, fit, radius } = imageElement.getProps();
+        let { x, y, width, height, image, fit, radius, alt } = imageElement.getProps();
         await image.init(); // Load and initialize the image
         const imageType = await image.getImageType(); // For the moment we can handle `png` and `jpg/jpeg` files
         const fileData = await image.getFileData();
@@ -82,6 +82,14 @@ export class ImageRenderer {
                 }
                 : {}),
         };
+        // Accessible tagging: an image WITH alt text is a Figure; without, it stays untagged and the backend
+        // treats it as decoration (an Artifact). One struct element per image.
+        if (objectManager.struct.enabled && alt) {
+            node.tag = {
+                role: "Figure",
+                key: objectManager.struct.openElement(imageElement.structId, "Figure", { alt }),
+            };
+        }
         return [node];
     }
 }

package/dist/renderer/page-renderer.js

@@ -25,7 +25,10 @@ export class PageRenderer {
                 nodes.push(...(await renderer(element, objectManager)));
             }
         }
-        const pageContent = PdfBackend.serialize(PdfBackend.flipY(nodes, height), objectManager);
+        // Accessible tagging: one struct context per page (allocates its StructParents index), threaded into
+        // serialize so each drawable node is wrapped in marked content. Undefined = tagging off (byte-identical).
+        const structCtx = objectManager.struct.enabled ? objectManager.struct.beginPage() : undefined;
+        const pageContent = PdfBackend.serialize(PdfBackend.flipY(nodes, height), objectManager, structCtx);
         // Add the page content as a new object (FlateDecode-compressed when enabled). The /Length is
         // computed inside, with an explicit EOL before `endstream` (PDF/A clause 6.1.7.1).
         const contentObjectNumber = objectManager.addContentStream(pageContent);
@@ -58,8 +61,20 @@ export class PageRenderer {
         const extGStateCode = extGStateReferences.length > 0
             ? "/ExtGState <<\n" + extGStateReferences.join("\n") + "\n>>\n"
             : "";
-        const pageObject = `<< /Type /Page /Parent ${parentObjectNumber} 0 R /Contents ${contentObjectNumber} 0 R /Resources <<\n/Font <<\n${fontReferences.join("\n")}\n>>\n${imageCode}${extGStateCode}>>\n/MediaBox [0 0 ${width} ${height}] >>`;
-        // Add page as new object and return the page number
-        return objectManager.addObject(pageObject);
+        // - Gradient shadings (color-glyph fills), registered during serialize above
+        const shadingReferences = [];
+        objectManager.getAllShadingsRaw().forEach((objectNumber, name) => {
+            shadingReferences.push(`/${name} ${objectNumber} 0 R`);
+        });
+        const shadingCode = shadingReferences.length > 0 ? "/Shading <<\n" + shadingReferences.join("\n") + "\n>>\n" : "";
+        // Tagging only: /StructParents links this page's marked content to the ParentTree, /Tabs /S makes the
+        // logical structure order the tab/reading order (a PDF/UA requirement).
+        const structAttrs = structCtx ? ` /StructParents ${structCtx.structParents} /Tabs /S` : "";
+        const pageObject = `<< /Type /Page /Parent ${parentObjectNumber} 0 R /Contents ${contentObjectNumber} 0 R /Resources <<\n/Font <<\n${fontReferences.join("\n")}\n>>\n${imageCode}${extGStateCode}${shadingCode}>>\n/MediaBox [0 0 ${width} ${height}]${structAttrs} >>`;
+        // Add page as new object; register its object number with the struct tree (for /Pg refs), then return it.
+        const pageObjNum = objectManager.addObject(pageObject);
+        if (structCtx)
+            objectManager.struct.setPageObject(structCtx.structParents, pageObjNum);
+        return pageObjNum;
     }
 }

package/dist/renderer/pdf-backend.d.ts

@@ -1,5 +1,6 @@
 import { IRNode } from "../ir/display-list.js";
 import { PDFObjectManager } from "../utils/pdf-object-manager.js";
+import type { PageStructContext } from "../utils/struct-tree.js";
 /**
  * PDF backend - turns display-list primitives into content-stream operators.
  *
@@ -17,8 +18,11 @@ export declare class PdfBackend {
      * directly. (image is migrated in a later slice and still arrives pre-flipped.)
      */
     static flipY(nodes: IRNode[], pageHeight: number): IRNode[];
-    /** Serialize a whole display list into one content stream (page-level entry point). */
-    static serialize(nodes: IRNode[], om: PDFObjectManager): string;
+    /** Serialize a whole display list into one content stream (page-level entry point). When a
+     *  `PageStructContext` is given (accessible tagging on), each drawable node is wrapped in a marked-content
+     *  sequence (`/Role <</MCID n>> BDC … EMC`, or `/Artifact` when untagged); graphics-state and empty nodes
+     *  pass through untouched, so untagged output stays byte-identical. */
+    static serialize(nodes: IRNode[], om: PDFObjectManager, struct?: PageStructContext): string;
     /**
      * Escapes a string for a PDF literal string `( ... )`. The backslash must be doubled
      * first, then the parentheses that delimit the string. Without this, a ")" in the

package/dist/renderer/pdf-backend.js

@@ -1,3 +1,4 @@
+import { Color } from "../common/color.js";
 /**
  * PDF backend - turns display-list primitives into content-stream operators.
  *
@@ -44,6 +45,23 @@ export class PdfBackend {
                     return { ...node, y: pageHeight - node.y - node.height };
                 case "clip-pop":
                     return node;
+                case "path": {
+                    // Flip every point's y directly (like a line endpoint); `z` carries no coordinates.
+                    const commands = node.commands.map((c) => {
+                        if (c.op === "z")
+                            return c;
+                        if (c.op === "c") {
+                            return { ...c, y1: pageHeight - c.y1, y2: pageHeight - c.y2, y: pageHeight - c.y };
+                        }
+                        return { ...c, y: pageHeight - c.y };
+                    });
+                    // A gradient fill carries its own page-space anchor points; flip their y too (radii and
+                    // x stay). A solid Color fill has no geometry.
+                    const fill = node.fill instanceof Color
+                        ? node.fill
+                        : { ...node.fill, y0: pageHeight - node.fill.y0, y1: pageHeight - node.fill.y1 };
+                    return { ...node, commands, fill };
+                }
                 default: {
                     const unknown = node;
                     return unknown;
@@ -51,9 +69,20 @@ export class PdfBackend {
             }
         });
     }
-    /** Serialize a whole display list into one content stream (page-level entry point). */
-    static serialize(nodes, om) {
-        return nodes.map((node) => PdfBackend.serializeNode(node, om)).join("");
+    /** Serialize a whole display list into one content stream (page-level entry point). When a
+     *  `PageStructContext` is given (accessible tagging on), each drawable node is wrapped in a marked-content
+     *  sequence (`/Role <</MCID n>> BDC … EMC`, or `/Artifact` when untagged); graphics-state and empty nodes
+     *  pass through untouched, so untagged output stays byte-identical. */
+    static serialize(nodes, om, struct) {
+        return nodes
+            .map((node) => {
+            const ops = PdfBackend.serializeNode(node, om);
+            if (!struct || node.type === "clip-push" || node.type === "clip-pop" || ops === "")
+                return ops;
+            const { open, close } = struct.mark(node.tag);
+            return open + ops + close;
+        })
+            .join("");
     }
     /**
      * Escapes a string for a PDF literal string `( ... )`. The backslash must be doubled
@@ -189,6 +218,33 @@ export class PdfBackend {
                     : `${node.x} ${node.y} ${node.width} ${node.height} re`;
                 return `q\n${path}\nW n\n`;
             }
+            case "path": {
+                // A filled vector path (one color-glyph layer). Emit the subpath ops, then either a solid
+                // nonzero fill (a Color) or, for a gradient, clip to the path and paint a shading inside it.
+                const f = (n) => n.toFixed(3);
+                let path = "";
+                for (const c of node.commands) {
+                    if (c.op === "m")
+                        path += `${f(c.x)} ${f(c.y)} m\n`;
+                    else if (c.op === "l")
+                        path += `${f(c.x)} ${f(c.y)} l\n`;
+                    else if (c.op === "c")
+                        path += `${f(c.x1)} ${f(c.y1)} ${f(c.x2)} ${f(c.y2)} ${f(c.x)} ${f(c.y)} c\n`;
+                    else
+                        path += `h\n`;
+                }
+                if (!(node.fill instanceof Color)) {
+                    // Gradient: clip to the path (W n keeps it as the clip without painting it), then paint
+                    // the registered shading across that clip. The q/Q isolates the clip. Note: per-stop alpha
+                    // is not represented (a DeviceRGB shading has no alpha channel - that would need a soft-mask
+                    // group); COLR gradient stops are opaque in real fonts, so they render correctly.
+                    const shading = om.registerShading(node.fill);
+                    return `q\n${path}W n\n/${shading} sh\nQ\n`;
+                }
+                const body = `${node.fill.toPDFColorString()} rg\n${path}f\n`;
+                const gs = PdfBackend.alphaPrefix(om, node.fill.getAlpha(), 1);
+                return gs ? `q\n${gs}${body}Q\n` : body;
+            }
             case "clip-pop":
                 return `Q\n`;
             default: {

package/dist/renderer/pdf-renderer.js

@@ -19,6 +19,8 @@ import { DeferredElement } from "../elements/layout/deferred-element.js";
 import { DeferredRenderer } from "./deferred-renderer.js";
 import { PositionedElement } from "../elements/layout/positioned-element.js";
 import { PositionedRenderer } from "./positioned-renderer.js";
+import { StructGroup } from "../elements/layout/struct-group.js";
+import { StructGroupRenderer } from "./struct-group-renderer.js";
 import { BoxConstraints } from "../layout/box-constraints.js";
 import { DEFAULT_TEXT_STYLE, mergeTextStyle } from "../text/text-style.js";
 export class PDFRenderer {
@@ -36,6 +38,7 @@ export class PDFRenderer {
         RendererRegistry.register(RepeatingHeaderElement, RepeatingHeaderRenderer.render);
         RendererRegistry.register(DeferredElement, DeferredRenderer.render);
         RendererRegistry.register(PositionedElement, PositionedRenderer.render);
+        RendererRegistry.register(StructGroup, StructGroupRenderer.render);
         let pdfContent = "";
         // Header: version line + the PDF/A binary marker (the object manager owns it so its length
         // matches the xref offset calculation).
@@ -69,6 +72,14 @@ export class PDFRenderer {
             const af = attachments.map((a) => `${a.filespec} 0 R`).join(" ");
             catalogParts.push(`/AF [${af}]`, `/Names << /EmbeddedFiles << /Names [${names}] >> >>`);
         }
+        // Accessible tagging: finalize the structure tree (emits StructTreeRoot + StructElems + ParentTree) and
+        // fold /MarkInfo + /StructTreeRoot + /Lang into the catalog. Returns "" (no-op) when tagging is off.
+        const structCatalog = objectManager.struct.finalize(objectManager);
+        if (structCatalog) {
+            catalogParts.push(structCatalog);
+            // PDF/UA requires the viewer to show the document title (not the file name).
+            catalogParts.push("/ViewerPreferences << /DisplayDocTitle true >>");
+        }
         const catalogObject = `<< ${catalogParts.join(" ")} >>`;
         objectManager.addObject(catalogObject);
         // Now that the render pass has revealed which glyphs each embedded font uses, fill the reserved

package/dist/renderer/struct-group-renderer.d.ts

@@ -0,0 +1,10 @@
+import { StructGroup } from "../elements/layout/struct-group.js";
+import { PDFObjectManager } from "../utils/pdf-object-manager.js";
+import { IRNode } from "../ir/display-list.js";
+/**
+ * Renders a StructGroup: opens its structure element, renders the child under it, closes it. With accessible
+ * tagging off it is fully transparent - just the child's IR.
+ */
+export declare class StructGroupRenderer {
+    static render(group: StructGroup, objectManager: PDFObjectManager): Promise<IRNode[]>;
+}

package/dist/renderer/struct-group-renderer.js

@@ -0,0 +1,24 @@
+import { RendererRegistry } from "../utils/renderer-registry.js";
+/**
+ * Renders a StructGroup: opens its structure element, renders the child under it, closes it. With accessible
+ * tagging off it is fully transparent - just the child's IR.
+ */
+export class StructGroupRenderer {
+    static async render(group, objectManager) {
+        const { role, child } = group.getProps();
+        const renderChild = async () => {
+            const renderer = RendererRegistry.getRenderer(child);
+            return renderer ? await renderer(child, objectManager) : [];
+        };
+        if (!objectManager.struct.enabled)
+            return renderChild();
+        const key = objectManager.struct.openElement(group.structId, role);
+        objectManager.struct.push(key);
+        try {
+            return await renderChild();
+        }
+        finally {
+            objectManager.struct.pop(); // keep the parent stack balanced even if a child throws
+        }
+    }
+}

package/dist/renderer/text-renderer.d.ts

@@ -6,5 +6,8 @@ import { TextOverflow } from "../text/line-breaker.js";
 export declare class TextRenderer {
     static calculateTextHeight(content: string | TextSegment[], fontSize: number, fontFamily: string, fontStyle: FontStyle, objectManager: FontMetrics, maxWidth: number, maxLines?: number, overflow?: TextOverflow, lineHeight?: number): number;
     static render(textElement: TextElement, objectManager: PDFObjectManager): Promise<IRNode[]>;
+    private static _expandColorGlyphs;
+    private static _glyphToPath;
+    private static _toGradient;
     private static _buildRuns;
 }

package/dist/renderer/text-renderer.js

@@ -1,4 +1,7 @@
+import { Color } from "../common/color.js";
 import { HorizontalAlignment } from "../elements/pdf-element.js";
+import { isEmojiCodePoint } from "../text/emoji-codepoints.js";
+import { emojiImageNode } from "./emoji-image.js";
 import { wrapStringIntoLines, breakSegmentsIntoLines, } from "../text/line-breaker.js";
 // Distance from the top of a line down to its baseline, as a fraction of the font
 // size. ~0.683 is the standard-14 ascent ratio used to seat the first baseline.
@@ -17,11 +20,188 @@ export class TextRenderer {
         return lines.reduce((total, line) => total + line.maxFontSize * lineHeight, 0);
     }
     static async render(textElement, objectManager) {
-        const { x, y, width, fontSize, color, content, fontFamily, fontStyle, textAlignment, maxLines, overflow, lineHeight, } = textElement.getProps();
+        const { x, y, width, fontSize, color, content, fontFamily, fontStyle, textAlignment, maxLines, overflow, lineHeight, role, } = textElement.getProps();
         // Component -> display list. Wrapping and positioning stay here; the backend
         // turns each run into BT/Tf/Td/Tj/ET. The wrapping algorithm is unchanged from
         // the original renderer - unifying it into the engine is Phase 3.
-        return TextRenderer._buildRuns(content, fontSize, fontFamily, fontStyle, objectManager, width ?? Number.NaN, textAlignment, color, x, y, maxLines, overflow, lineHeight);
+        const runs = TextRenderer._buildRuns(content, fontSize, fontFamily, fontStyle, objectManager, width ?? Number.NaN, textAlignment, color, x, y, maxLines, overflow, lineHeight);
+        // Accessible tagging: this whole text block is one structure element (a paragraph P, or a heading
+        // from `role`); each run's text lands under it. Emoji sub-nodes produced below stay untagged (drawn
+        // as artifacts). Keyed by structId so a block split across pages stays one element.
+        if (objectManager.struct.enabled) {
+            const pdfRole = role ? role.toUpperCase() : "P"; // "h1" -> "H1"; default paragraph
+            const key = objectManager.struct.openElement(textElement.structId, pdfRole);
+            for (const run of runs)
+                run.tag = { role: pdfRole, key };
+        }
+        // Color fonts (COLR/CPAL): expand each run's emoji into filled vector layers (or fetched images
+        // for an image emoji source); plain runs and monochrome fonts pass straight through unchanged.
+        return (await Promise.all(runs.map((run) => TextRenderer._expandColorGlyphs(run, objectManager)))).flat();
+    }
+    // Splits a text run into normal text sub-runs + filled `Path` layers for any COLR color glyphs,
+    // walking code point by code point and advancing the pen by each glyph's width. Returns `[run]`
+    // untouched when the font has no color glyphs (the common case).
+    static async _expandColorGlyphs(run, om) {
+        // The run's own font (if it's a color font) draws emoji directly; otherwise a document-level
+        // emoji source (`Document({ emoji })`) supplies them - a fallback FONT (color glyphs, native
+        // vector) or an IMAGE source (fetched emoji images) - for code points the run's font lacks, so
+        // `Text("Hallo 😅")` works in one string. No emoji source at all -> pass the run through.
+        const own = om.getColorFont(run.fontFamily, run.fontStyle);
+        const emojiName = om.getEmojiFont();
+        const fallback = emojiName && emojiName !== run.fontFamily
+            ? om.getColorFont(emojiName, run.fontStyle)
+            : undefined;
+        const imageSource = om.getEmojiImageSource();
+        if (!own && !fallback && !imageSource)
+            return [run];
+        const nodes = [];
+        let cursorX = run.x; // absolute x of the next glyph
+        let pending = ""; // run of consecutive non-color characters
+        let pendingX = run.x; // where that run started
+        const flushPending = () => {
+            if (pending) {
+                nodes.push({ ...run, x: pendingX, text: pending });
+                pending = "";
+            }
+        };
+        for (const ch of run.text) {
+            const cp = ch.codePointAt(0);
+            // Which color font renders this code point: the run's own font first, then the emoji fallback.
+            let source;
+            let layers = null;
+            if (own) {
+                const l = own.getColorGlyph(own.getGlyphIndex(cp));
+                if (l)
+                    [source, layers] = [own, l];
+            }
+            if (!layers && fallback) {
+                const l = fallback.getColorGlyph(fallback.getGlyphIndex(cp));
+                if (l)
+                    [source, layers] = [fallback, l];
+            }
+            // The advance matches measuring (getCharWidth applies the same emoji fallback).
+            const advance = om.getCharWidth(ch, run.fontSize, undefined, run.fontFamily, run.fontStyle);
+            if (source && layers) {
+                flushPending();
+                const scale = run.fontSize / source.unitsPerEm;
+                for (const layer of layers) {
+                    const commands = TextRenderer._glyphToPath(source.getGlyphPath(layer.glyphId), cursorX, run.y, scale, layer.transform);
+                    if (commands.length === 0)
+                        continue; // an empty layer outline draws nothing
+                    const paint = layer.paint;
+                    let fill;
+                    if (paint.type === "solid") {
+                        const c = paint.color;
+                        fill = c ? new Color(c.r, c.g, c.b, c.a / 255) : run.color; // null -> foreground
+                    }
+                    else {
+                        fill = TextRenderer._toGradient(paint, cursorX, run.y, scale, run.color, layer.transform);
+                    }
+                    nodes.push({ type: "path", commands, fill });
+                }
+            }
+            else if (imageSource && isEmojiCodePoint(cp)) {
+                // Image emoji source: fetch + embed a 1em square. The emoji breaks the text run either way;
+                // a failed fetch (offline/404) leaves a blank em gap (advance already applied) rather than
+                // drawing a broken glyph.
+                flushPending();
+                const node = await emojiImageNode(cp, imageSource, cursorX, run.y, run.fontSize);
+                if (node)
+                    nodes.push(node);
+            }
+            else {
+                if (!pending)
+                    pendingX = cursorX;
+                pending += ch;
+            }
+            cursorX += advance;
+        }
+        flushPending();
+        return nodes;
+    }
+    // Maps a glyph outline (font units, y-up) to absolute IR path commands at the pen origin, scaling
+    // by `scale` and flipping the axis into the engine's top-left space (the seam flips it once more
+    // to PDF space). TrueType quadratics become cubics: C1 = P0 + 2/3(C-P0), C2 = P1 + 2/3(C-P1).
+    static _glyphToPath(cmds, originX, baselineY, scale, transform) {
+        // Apply the layer's affine (font units) first, then scale to points, position at the pen origin
+        // and flip into engine space. `mapX`/`mapY` take BOTH glyph coords because an affine mixes them.
+        const [a, b, c, d, e, f] = transform ?? [1, 0, 0, 1, 0, 0];
+        const mapX = (gx, gy) => originX + (a * gx + c * gy + e) * scale;
+        const mapY = (gx, gy) => baselineY - (b * gx + d * gy + f) * scale;
+        const out = [];
+        let curX = 0;
+        let curY = 0;
+        for (const cmd of cmds) {
+            if (cmd.type === "M") {
+                curX = mapX(cmd.x, cmd.y);
+                curY = mapY(cmd.x, cmd.y);
+                out.push({ op: "m", x: curX, y: curY });
+            }
+            else if (cmd.type === "L") {
+                curX = mapX(cmd.x, cmd.y);
+                curY = mapY(cmd.x, cmd.y);
+                out.push({ op: "l", x: curX, y: curY });
+            }
+            else if (cmd.type === "Q") {
+                const ctrlX = mapX(cmd.cx, cmd.cy);
+                const ctrlY = mapY(cmd.cx, cmd.cy);
+                const endX = mapX(cmd.x, cmd.y);
+                const endY = mapY(cmd.x, cmd.y);
+                out.push({
+                    op: "c",
+                    x1: curX + (2 / 3) * (ctrlX - curX),
+                    y1: curY + (2 / 3) * (ctrlY - curY),
+                    x2: endX + (2 / 3) * (ctrlX - endX),
+                    y2: endY + (2 / 3) * (ctrlY - endY),
+                    x: endX,
+                    y: endY,
+                });
+                curX = endX;
+                curY = endY;
+            }
+            else {
+                out.push({ op: "z" });
+            }
+        }
+        return out;
+    }
+    // Maps a COLR v1 gradient paint (font-unit coordinates) into an IR `Gradient` positioned at the
+    // pen origin, using the SAME scale + baseline flip as the glyph outline so the gradient axis lines
+    // up with the shape. Radii scale uniformly (the em scale is uniform). A null stop color (the COLR
+    // "use foreground" sentinel) becomes the text color.
+    static _toGradient(paint, originX, baselineY, scale, foreground, transform) {
+        const [a, b, c, d, e, f] = transform ?? [1, 0, 0, 1, 0, 0];
+        const mapX = (gx, gy) => originX + (a * gx + c * gy + e) * scale;
+        const mapY = (gx, gy) => baselineY - (b * gx + d * gy + f) * scale;
+        // A radius has no single value under a general affine (a circle can shear into an ellipse); use
+        // the affine's geometric-mean scale sqrt(|det|) times the em scale - exact for uniform scaling.
+        const radiusScale = scale * Math.sqrt(Math.abs(a * d - b * c));
+        const stops = paint.stops.map((s) => ({
+            offset: s.offset,
+            color: s.color ? new Color(s.color.r, s.color.g, s.color.b, s.color.a / 255) : foreground,
+        }));
+        if (paint.type === "linearGradient") {
+            return {
+                type: "linear",
+                x0: mapX(paint.p0[0], paint.p0[1]),
+                y0: mapY(paint.p0[0], paint.p0[1]),
+                x1: mapX(paint.p1[0], paint.p1[1]),
+                y1: mapY(paint.p1[0], paint.p1[1]),
+                stops,
+                extend: paint.extend,
+            };
+        }
+        return {
+            type: "radial",
+            x0: mapX(paint.c0[0], paint.c0[1]),
+            y0: mapY(paint.c0[0], paint.c0[1]),
+            r0: paint.c0[2] * radiusScale,
+            x1: mapX(paint.c1[0], paint.c1[1]),
+            y1: mapY(paint.c1[0], paint.c1[1]),
+            r1: paint.c1[2] * radiusScale,
+            stops,
+            extend: paint.extend,
+        };
     }
     // Lay the content out into absolutely-positioned text runs. Glyph positions match
     // the previous hand-written operators exactly (verified by pixel-identical render);

package/dist/text/emoji-codepoints.d.ts

@@ -0,0 +1 @@
+export declare function isEmojiCodePoint(codePoint: number): boolean;

package/dist/text/emoji-codepoints.js

@@ -0,0 +1,29 @@
+// Whether a code point is (very likely) an emoji, used ONLY by the image/CDN emoji source: unlike a
+// font source, there is no font to ask "do you have a color glyph for this?", so we decide from the
+// well-known emoji blocks. This is a curated, dependency-free subset - it covers the emoji people
+// actually type, not the full Unicode Emoji property list, and intentionally errs toward the common
+// blocks. A font source does NOT use this (it asks the font).
+// [lo, hi] inclusive ranges of the main emoji / pictograph blocks.
+const RANGES = [
+    [0x1f000, 0x1faff], // Mahjong/Dominoes/Cards, Misc Symbols & Pictographs, Emoticons, Transport,
+    //                     Supplemental Symbols & Pictographs, Symbols & Pictographs Extended-A (incl. flags)
+    [0x2190, 0x21ff], // Arrows
+    [0x2300, 0x23ff], // Misc Technical (⌚ ⏰ ⏳, media controls)
+    [0x2460, 0x24ff], // Enclosed Alphanumerics (Ⓜ)
+    [0x25a0, 0x25ff], // Geometric Shapes (▪ ◼ ⬛)
+    [0x2600, 0x27bf], // Misc Symbols + Dingbats (☀ ★ ✂ ✅ ✈ ✉ ✊ ✋)
+    [0x2900, 0x297f], // Supplemental Arrows-B (⤴ ⤵)
+    [0x2b00, 0x2bff], // Misc Symbols and Arrows (⭐ ⬅ ⬛)
+    [0x3000, 0x303f], // CJK Symbols and Punctuation (〰 〽)
+    [0x3200, 0x32ff], // Enclosed CJK Letters and Months (㊗ ㊙)
+];
+// Emoji-presentation singletons outside the ranges above.
+const SINGLES = new Set([0x00a9, 0x00ae, 0x203c, 0x2049, 0x2122, 0x2139, 0xfe0f]);
+export function isEmojiCodePoint(codePoint) {
+    if (SINGLES.has(codePoint))
+        return true;
+    for (const [lo, hi] of RANGES)
+        if (codePoint >= lo && codePoint <= hi)
+            return true;
+    return false;
+}

package/dist/text/line-breaker.js

@@ -133,9 +133,12 @@ function ellipsize(line, fontFamily, fontSize, fontStyle, maxWidth, metrics) {
         if (fits(words.join(" ")))
             return words.join(" ") + ELLIPSIS;
     }
-    let single = words[0] ?? "";
-    while (single.length > 1) {
-        single = single.slice(0, -1);
+    // Drop one code point at a time (not one UTF-16 unit) so an astral char is never split into a
+    // lone surrogate. `chars` is the code-point view; rebuild the string from its shrinking prefix.
+    const chars = [...(words[0] ?? "")];
+    while (chars.length > 1) {
+        chars.pop();
+        const single = chars.join("");
         if (fits(single))
             return single + ELLIPSIS;
     }

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

@@ -1,5 +1,8 @@
 import type { OverflowPolicy } from "../layout/fragmentation.js";
+import { TTFParser } from "./ttf-parser.js";
 import type { SecurityHandler } from "../crypto/security-handler.js";
+import type { Gradient } from "../ir/display-list.js";
+import { StructTree } from "./struct-tree.js";
 import type { PDFConfig } from "../renderer/pdf-document-class.js";
 import type { FontMetrics } from "./font-metrics.js";
 interface FontIndexes {
@@ -21,6 +24,9 @@ export declare class PDFObjectManager implements FontMetrics {
     private fonts;
     private images;
     private extGStates;
+    private shadings;
+    private emojiFontName?;
+    private emojiImage?;
     private pdfConfig;
     pageFormat: [number, number];
     private afmParsers;
@@ -36,6 +42,8 @@ export declare class PDFObjectManager implements FontMetrics {
     private security?;
     private encJobs;
     private encryptObjNum?;
+    private _struct;
+    get struct(): StructTree;
     constructor();
     addObject(content: string): number;
     replaceObject(objectNumber: number, content: string): void;
@@ -77,6 +85,9 @@ export declare class PDFObjectManager implements FontMetrics {
     finalizeEncryption(): Promise<void>;
     registerExtGState(fillAlpha: number, strokeAlpha: number): string;
     getAllExtGStatesRaw(): Map<string, number>;
+    registerShading(g: Gradient): string;
+    private buildShadingFunction;
+    getAllShadingsRaw(): Map<string, number>;
     registerFont(fontName: string, fontStyle?: FontStyle, fullName?: string): FontIndexes;
     registerCustomFont(name: string, data: Uint8Array, style?: FontStyle): void;
     private ensureEmitted;
@@ -86,6 +97,15 @@ export declare class PDFObjectManager implements FontMetrics {
     private resolveCustomStyle;
     private getCustomFont;
     isCustomFont(name?: string, style?: FontStyle): boolean;
+    getColorFont(name: string, style?: FontStyle): TTFParser | undefined;
+    setEmojiFont(name: string): void;
+    getEmojiFont(): string | undefined;
+    setEmojiImageSource(url: string, format: string): void;
+    getEmojiImageSource(): {
+        url: string;
+        format: string;
+    } | undefined;
+    private colorRenders;
     getCustomFontResource(name: string, style?: FontStyle): FontIndexes | undefined;
     encodeCustomText(name: string, text: string, style?: FontStyle): string;
     private buildFontFile2;
@@ -94,7 +114,6 @@ export declare class PDFObjectManager implements FontMetrics {
     private buildToUnicode;
     private buildType0;
     getStringWidth(text: string, fontFamily: string, fontSize: number, fontStyle: FontStyle): number;
-    private getCharCode;
     private getAVMParserByFont;
     getCharWidth(char: string, fontSize: number, fullFontName?: string, fontName?: string, fontStyle?: FontStyle): number;
     private getKerning;

package/dist/utils/struct-tree.d.ts

@@ -0,0 +1,44 @@
+import type { StructTag } from "../ir/display-list.js";
+import type { PDFObjectManager } from "./pdf-object-manager.js";
+/** Per-page tagging context: hands out page-local MCIDs and links them to their StructElem. */
+export declare class PageStructContext {
+    readonly structParents: number;
+    private readonly tree;
+    private mcid;
+    constructor(structParents: number, tree: StructTree);
+    /** Marked-content delimiters for one drawable node. Tagged content gets an MCID linked to its (already
+     *  registered) StructElem; untagged content becomes an Artifact (decoration, skipped by assistive tech). */
+    mark(tag?: StructTag): {
+        open: string;
+        close: string;
+    };
+}
+/** Builds the PDF structure tree for accessible tagging. One instance per document (held by the object manager). */
+export declare class StructTree {
+    enabled: boolean;
+    lang: string;
+    title?: string;
+    private counter;
+    private structParentsCounter;
+    private elems;
+    private byStructId;
+    private stack;
+    private pageObjByStructParents;
+    /** Register a structure element for a logical element (keyed by its stable `structId`, so a paragraph or
+     *  table split across pages resolves to the SAME element - MCIDs then accrue from every page). Its parent
+     *  is the currently-open container, else the Document. Containers also push()/pop() around their children. */
+    openElement(structId: number, role: string, opts?: {
+        alt?: string;
+    }): number;
+    push(key: number): void;
+    pop(): void;
+    /** Begin a page: allocates its StructParents index (its slot in the ParentTree). */
+    beginPage(): PageStructContext;
+    /** Tie a page's StructParents index to its now-known page object number (for /Pg references). */
+    setPageObject(structParents: number, pageObjNum: number): void;
+    /** Link a page-local MCID to an element (called by the backend while serializing). */
+    linkMarkedContent(key: number, structParents: number, mcid: number): void;
+    /** Emit the struct-tree objects and return the catalog additions (`/MarkInfo`, `/StructTreeRoot`, `/Lang`).
+     *  A no-op returning "" when disabled or nothing was tagged, so a plain document stays byte-identical. */
+    finalize(om: PDFObjectManager): string;
+}