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

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

@@ -22,6 +22,16 @@ export declare class PdfBackend {
      *  `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. */
+    /**
+     * Every number reaching the backend must be finite. A non-finite coordinate is a layout bug, but
+     * silence turns it into a corrupt PDF: `Infinity` is written into the operator stream verbatim, and a
+     * viewer then discards everything from that point on - including the footer, which is drawn last. That
+     * failure is invisible until somebody opens the file, so we refuse instead.
+     *
+     * Checks the node's numbers, not the serialized text: a document containing the WORD "Infinity" is
+     * perfectly legal and must not trip this.
+     */
+    private static assertFinite;
     static serialize(nodes: IRNode[], om: PDFObjectManager, struct?: PageStructContext): string;
     /**
      * Escapes a string for a PDF literal string `( ... )`. The backslash must be doubled
@@ -29,6 +39,13 @@ export declare class PdfBackend {
      * text closes the string early and the remaining characters leak as raw operators.
      */
     static escapePdfString(text: string): string;
+    /**
+     * Builds the `[ ... ]` operand of a `TJ` from a run and its per-gap kern adjustments (em/1000, the
+     * sign the font declares - negative tightens). A `TJ` number moves the pen LEFT, so it is the
+     * NEGATED kern. Consecutive un-kerned glyphs stay in one encoded chunk, so `[(T) 40 (otal)]` rather
+     * than one chunk per glyph. `kerns[i]` is the adjustment AFTER code point `i`.
+     */
+    static kernedArray(text: string, kerns: number[], encode: (chunk: string) => string): string;
     /**
      * Returns the `/GSx gs` operator that selects a transparency state, or `""` when both
      * alphas are fully opaque. Opaque draws emit nothing here, so output stays

package/dist/renderer/pdf-backend.js

@@ -62,6 +62,28 @@ export class PdfBackend {
                         : { ...node.fill, y0: pageHeight - node.fill.y0, y1: pageHeight - node.fill.y1 };
                     return { ...node, commands, fill };
                 }
+                case "link":
+                    // A link's clickable rect flips around its bottom edge, exactly like a rect.
+                    return { ...node, y: pageHeight - node.y - node.height };
+                case "outline":
+                    // An outline anchor is a single point (the target's top); flip it like a text baseline.
+                    return { ...node, y: pageHeight - node.y };
+                case "anchor":
+                    // A named-destination anchor is a single point (the target's top), flipped like a baseline.
+                    return { ...node, y: pageHeight - node.y };
+                case "transform-push": {
+                    // The child nodes are flipped from top-left to bottom-left by F = [1,0,0,-1,0,H] (F is its
+                    // own inverse). For a matrix authored in top-left space to act correctly on them, conjugate
+                    // it by that flip: M_pdf = F · M · F. Worked out for [a,b,c,d,e,f] with H = pageHeight:
+                    const [a, b, c, d, e, f] = node.matrix;
+                    const H = pageHeight;
+                    return {
+                        ...node,
+                        matrix: [a, -b, -c, d, H * c + e, H - H * d - f],
+                    };
+                }
+                case "transform-pop":
+                    return node; // no coordinates to flip
                 default: {
                     const unknown = node;
                     return unknown;
@@ -73,11 +95,49 @@ export class PdfBackend {
      *  `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. */
+    /**
+     * Every number reaching the backend must be finite. A non-finite coordinate is a layout bug, but
+     * silence turns it into a corrupt PDF: `Infinity` is written into the operator stream verbatim, and a
+     * viewer then discards everything from that point on - including the footer, which is drawn last. That
+     * failure is invisible until somebody opens the file, so we refuse instead.
+     *
+     * Checks the node's numbers, not the serialized text: a document containing the WORD "Infinity" is
+     * perfectly legal and must not trip this.
+     */
+    static assertFinite(node) {
+        const finite = (value) => {
+            if (typeof value === "number")
+                return Number.isFinite(value);
+            if (Array.isArray(value))
+                return value.every(finite);
+            if (value !== null && typeof value === "object")
+                return Object.values(value).every(finite);
+            return true;
+        };
+        if (!finite(node)) {
+            throw new Error(`Layout produced a non-finite number on a "${node.type}" node, refusing to emit a corrupt ` +
+                `content stream. This is a bug in an element's calculateLayout (a size resolved to Infinity ` +
+                `or NaN), not in your document.`);
+        }
+    }
     static serialize(nodes, om, struct) {
         return nodes
             .map((node) => {
+            PdfBackend.assertFinite(node);
             const ops = PdfBackend.serializeNode(node, om);
-            if (!struct || node.type === "clip-push" || node.type === "clip-pop" || ops === "")
+            // Two kinds of node skip the marked-content wrapper, both because they carry no tag and never
+            // draw: GRAPHICS-STATE nodes (clip / transform push+pop) only save/restore state around the
+            // drawables they enclose, and SIDE-CHANNEL nodes (link, outline, anchor) become annotations /
+            // catalog entries instead of content-stream operators.
+            if (!struct ||
+                node.type === "clip-push" ||
+                node.type === "clip-pop" ||
+                node.type === "transform-push" ||
+                node.type === "transform-pop" ||
+                node.type === "link" ||
+                node.type === "outline" ||
+                node.type === "anchor" ||
+                ops === "")
                 return ops;
             const { open, close } = struct.mark(node.tag);
             return open + ops + close;
@@ -92,6 +152,27 @@ export class PdfBackend {
     static escapePdfString(text) {
         return text.replace(/\\/g, "\\\\").replace(/\(/g, "\\(").replace(/\)/g, "\\)");
     }
+    /**
+     * Builds the `[ ... ]` operand of a `TJ` from a run and its per-gap kern adjustments (em/1000, the
+     * sign the font declares - negative tightens). A `TJ` number moves the pen LEFT, so it is the
+     * NEGATED kern. Consecutive un-kerned glyphs stay in one encoded chunk, so `[(T) 40 (otal)]` rather
+     * than one chunk per glyph. `kerns[i]` is the adjustment AFTER code point `i`.
+     */
+    static kernedArray(text, kerns, encode) {
+        const chars = [...text];
+        let out = "";
+        let chunk = chars[0] ?? "";
+        for (let i = 0; i < kerns.length; i++) {
+            if (kerns[i] === 0) {
+                chunk += chars[i + 1];
+            }
+            else {
+                out += encode(chunk) + ` ${-kerns[i]} `;
+                chunk = chars[i + 1];
+            }
+        }
+        return `[${out}${encode(chunk)}]`;
+    }
     /**
      * Returns the `/GSx gs` operator that selects a transparency state, or `""` when both
      * alphas are fully opaque. Opaque draws emit nothing here, so output stays
@@ -182,18 +263,31 @@ export class PdfBackend {
                 const font = isCustom
                     ? om.getCustomFontResource(node.fontFamily, node.fontStyle)
                     : om.registerFont(node.fontFamily, node.fontStyle);
-                const textOp = isCustom
-                    ? `<${om.encodeCustomText(node.fontFamily, node.text, node.fontStyle)}>`
-                    : `(${PdfBackend.escapePdfString(node.text)})`;
+                const encode = (t) => isCustom
+                    ? `<${om.encodeCustomText(node.fontFamily, t, node.fontStyle)}>`
+                    : `(${PdfBackend.escapePdfString(t)})`;
+                // Kerning (if the document has it on): a `TJ` array with the font's per-pair adjustments
+                // between glyph chunks, measured into the layout by the SAME numbers (runAdvance). A plain
+                // `Tj` when the run has no kerning, byte-identical.
+                const kerns = om.kerningEnabled
+                    ? om.getKernPairs(node.text, node.fontFamily, node.fontStyle)
+                    : [];
+                const showOp = kerns.some((k) => k !== 0)
+                    ? `${PdfBackend.kernedArray(node.text, kerns, encode)} TJ`
+                    : `${encode(node.text)} Tj`;
+                // letterSpacing is the `Tc` operator: extra advance after EVERY glyph (an embedded
+                // Identity-H font too - that is `Tw`, word spacing, which only touches single-byte code 32).
+                const spacing = node.letterSpacing ? `${node.letterSpacing.toFixed(3)} Tc\n` : "";
                 const block = `BT\n` +
                     `${node.color.toPDFColorString()} rg ` +
                     `/F${font.fontIndex} ${node.fontSize} Tf ` +
                     `${node.x.toFixed(3)} ${node.y.toFixed(3)} Td ` +
-                    `${textOp} Tj\n` +
+                    `${showOp}\n` +
                     `ET\n`;
-                // Transparent text gets an isolating q/Q + gs; opaque text is byte-identical.
                 const gs = PdfBackend.alphaPrefix(om, node.color.getAlpha(), 1);
-                return gs ? `q\n${gs}${block}Q\n` : block;
+                // `Tc` is graphics state and would leak into the next run, so isolate it in q/Q - the same
+                // reason transparent text is isolated. A run with neither stays byte-identical.
+                return gs || spacing ? `q\n${gs}${spacing}${block}Q\n` : block;
             }
             case "image": {
                 // The backend owns PDF resource creation: register the XObject (using the
@@ -247,6 +341,22 @@ export class PdfBackend {
             }
             case "clip-pop":
                 return `Q\n`;
+            case "transform-push": {
+                // Save the graphics state, then apply the affine; everything until transform-pop paints through it.
+                const f = (n) => n.toFixed(3);
+                return `q\n${node.matrix.map(f).join(" ")} cm\n`;
+            }
+            case "transform-pop":
+                return `Q\n`;
+            case "link":
+                // A link draws nothing in the content stream - it becomes a page /Annot (built in PageRenderer).
+                return "";
+            case "outline":
+                // An outline anchor draws nothing - it becomes a /Outlines entry (built in PageRenderer/PDFRenderer).
+                return "";
+            case "anchor":
+                // A named destination draws nothing - it becomes a /Names /Dests entry (built in PageRenderer/PDFRenderer).
+                return "";
             default: {
                 // Exhaustiveness guard: if a new IRNode variant is added, this fails to compile.
                 const unknown = node;

package/dist/renderer/pdf-document-class.js

@@ -88,6 +88,9 @@ export class PDFDocument {
         }
         if (config)
             this._objectManager.changePDFConfig(config);
+        // Kerning is on by default at the document level (the `renderToBytes` path sets the same). A
+        // bare `PDFObjectManager` still defaults OFF, so unit tests keep predictable un-kerned metrics.
+        this._objectManager.setKerning(true);
     }
     get objectManager() {
         return this._objectManager;

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

@@ -4,16 +4,25 @@ import { PDFObjectManager } from "../utils/pdf-object-manager.js";
 export declare class PDFDocumentRenderer {
     static render(document: PDFDocumentElement, objectManager: PDFObjectManager, ctx: LayoutContext): Promise<number>;
     /**
-     * Renders one logical page, paginating it into one or more physical pages.
+     * The page geometry a physical page will use. `PageElement.calculateLayout` has already folded the
+     * document defaults into every page's config by the time we get here (`PDFRenderer` lays the document
+     * out before it calls us, and it is our only caller). Merging again is therefore a no-op today - it is
+     * here so this stays correct BY CONSTRUCTION rather than by call order: were that order ever changed,
+     * an unmerged config would otherwise make `resolvePageSize` fall back to A4 and quietly report the
+     * wrong page size.
+     */
+    private static configOf;
+    /**
+     * Splits one logical page into the physical pages it will occupy, without rendering.
      *
-     * Slice 0 only auto-paginates the common shape - a page whose single child is a
-     * fragmentation context (a Container). Anything else renders as a single page on the
-     * unchanged path, so non-overflowing documents stay byte-identical to pre-Slice-0.
+     * Only the common shape auto-paginates - a page whose single child is a fragmentation context
+     * (a Container). Anything else stays a single page on the unchanged path, so non-overflowing
+     * documents keep producing byte-identical output.
      */
-    private static renderLogicalPage;
+    private static paginateLogicalPage;
     /**
-     * Lays out one fragment on a fresh page of the same geometry and renders it. The
-     * header/footer are attached to every physical page so they repeat; `PageElement`
+     * Lays out one physical page and renders it. A fragment gets a fresh `PageElement` of the same
+     * geometry; the header/footer are attached to every physical page so they repeat, and `PageElement`
      * re-places them and the body in the band between.
      */
     private static renderPhysicalPage;

package/dist/renderer/pdf-document-renderer.js

@@ -1,21 +1,36 @@
-import { layoutPageBands, PageElement } from "../elements/page-element.js";
+import { layoutPageBands, pageFrame, PageElement, resolvePageSize, } from "../elements/page-element.js";
 import { BoxConstraints } from "../layout/box-constraints.js";
-import { isFragmentable } from "../layout/fragmentation.js";
+import { isFragmentable, reportOverflow } from "../layout/fragmentation.js";
 import { PageRenderer } from "./page-renderer.js";
 export class PDFDocumentRenderer {
     static async render(document, objectManager, ctx) {
-        const pageNumbers = [];
         // Add the pages object first... we need its object number (resources). The count is
         // a placeholder; it is replaced below with the real (post-pagination) page count.
         const pagesObject = `<< /Type /Pages /Kids [] /Count ${document.getProps().children.length} >>`;
         const pagesObjectNumber = objectManager.addObject(pagesObject);
         // Now set the given object number all its childs
         objectManager.setParentObjectNumber(pagesObjectNumber);
-        // The page driver: each logical PageElement may produce SEVERAL physical PDF pages
-        // when its content overflows (Slice 0: whole children reflow to the next page).
-        for (let page of document.getProps().children) {
-            const numbers = await PDFDocumentRenderer.renderLogicalPage(page, objectManager, ctx);
-            pageNumbers.push(...numbers);
+        // Pass A - paginate the whole document WITHOUT drawing anything. Fragmentation is synchronous and
+        // pure (`{ fitted, remainder }`), so the full list of physical pages can be settled up front. Only
+        // then is the total page count known, which is what page numbers in a header/footer need.
+        const physicalPages = [];
+        for (const page of document.getProps().children) {
+            physicalPages.push(...PDFDocumentRenderer.paginateLogicalPage(page, ctx));
+        }
+        // Pass B - draw them, in order, so the emitted page objects keep their previous numbering. Each page
+        // is laid out again with its own PageInfo, which is how a `PageBuilder` anywhere in the tree (header,
+        // footer or body) learns its final page number and the now-known document total.
+        const pageNumbers = [];
+        for (const [index, physical] of physicalPages.entries()) {
+            const pageInfo = {
+                pageNumber: index + 1,
+                pageCount: physicalPages.length,
+                pageSize: resolvePageSize(PDFDocumentRenderer.configOf(physical, ctx)),
+            };
+            pageNumbers.push(await PDFDocumentRenderer.renderPhysicalPage(physical, objectManager, {
+                ...ctx,
+                pageInfo,
+            }));
         }
         // We must update the pages object with the real physical page numbers and count.
         const updatedPagesObject = `<< /Type /Pages /Kids [${pageNumbers
@@ -26,65 +41,101 @@ export class PDFDocumentRenderer {
         return pagesObjectNumber;
     }
     /**
-     * Renders one logical page, paginating it into one or more physical pages.
+     * The page geometry a physical page will use. `PageElement.calculateLayout` has already folded the
+     * document defaults into every page's config by the time we get here (`PDFRenderer` lays the document
+     * out before it calls us, and it is our only caller). Merging again is therefore a no-op today - it is
+     * here so this stays correct BY CONSTRUCTION rather than by call order: were that order ever changed,
+     * an unmerged config would otherwise make `resolvePageSize` fall back to A4 and quietly report the
+     * wrong page size.
+     */
+    static configOf(physical, ctx) {
+        const config = physical.kind === "whole" ? physical.page.getProps().config : physical.config;
+        return { ...ctx.pageConfig, ...config };
+    }
+    /**
+     * Splits one logical page into the physical pages it will occupy, without rendering.
      *
-     * Slice 0 only auto-paginates the common shape - a page whose single child is a
-     * fragmentation context (a Container). Anything else renders as a single page on the
-     * unchanged path, so non-overflowing documents stay byte-identical to pre-Slice-0.
+     * Only the common shape auto-paginates - a page whose single child is a fragmentation context
+     * (a Container). Anything else stays a single page on the unchanged path, so non-overflowing
+     * documents keep producing byte-identical output.
      */
-    static async renderLogicalPage(page, objectManager, ctx) {
+    static paginateLogicalPage(page, ctx) {
         const { children, config, header, footer } = page.getProps();
         if (children.length !== 1 || !isFragmentable(children[0])) {
-            return [await PageRenderer.render(page, objectManager)];
+            return [{ kind: "whole", page }];
         }
         // Header/footer repeat on every physical page, so the body only ever flows into the
         // band between them. Resolve that band once (config is already merged by pass 1).
+        // The frame is a throwaway: this pass only wants the band HEIGHTS, and an out-of-flow child
+        // contributes none. It exists because a `Positioned` in a band demands one; pass 2 builds the
+        // real frame (in `PageElement`) and drains it.
         const pageCtx = {
             metrics: ctx.metrics,
             pageConfig: config,
             textStyle: ctx.textStyle,
             onOverflow: ctx.onOverflow,
+            frame: pageFrame(config),
         };
         const { bodyWidth: width, bodyHeight: height } = layoutPageBands(config, header, footer, pageCtx);
-        const numbers = [];
+        // A `keepTogether` group compares its height against a FULL fresh page (this band), so thread it in.
+        pageCtx.pageBodyHeight = height;
+        const pages = [];
         let region = children[0];
         let isFirstRegion = true;
         while (region) {
             if (!isFragmentable(region)) {
                 // A non-fragmentable remainder is placed whole on its own page.
-                numbers.push(await PDFDocumentRenderer.renderPhysicalPage(config, region, header, footer, objectManager, ctx));
+                pages.push({ kind: "fragment", config, content: region, header, footer });
                 break;
             }
-            const { fitted, remainder } = region.fragment(height, width, ctx);
-            // Everything fits on one page: render the ORIGINAL page so output is unchanged.
-            // Measuring inside fragment() laid the children out at the origin to size them, so
-            // re-run the page layout first to restore their real positions (deterministic).
-            if (isFirstRegion && remainder === null) {
-                page.calculateLayout(new BoxConstraints(), { x: 0, y: 0 }, ctx);
-                numbers.push(await PageRenderer.render(page, objectManager));
+            // pageCtx, not the document ctx: a descendant that reads `pageConfig` while being measured (a
+            // `PageBuilder` sizing its provisional build) must see THIS page's geometry, not the document default.
+            const { fitted, remainder, forceBreak } = region.fragment(height, width, pageCtx);
+            // Everything fits on one page: keep the ORIGINAL page so output is unchanged. Measuring inside
+            // fragment() left its children at the measuring origin; pass B lays the page out again, which
+            // restores their real positions (layout is deterministic). A consumed trailing `PageBreak`
+            // (forceBreak with no remainder) is the exception: render the packed `fitted` instead, which no
+            // longer holds the break marker, so the original with the break does not leak into the render pass.
+            if (isFirstRegion && remainder === null && !forceBreak) {
+                pages.push({ kind: "whole", page });
                 break;
             }
-            if (fitted) {
-                numbers.push(await PDFDocumentRenderer.renderPhysicalPage(config, fitted, header, footer, objectManager, ctx));
+            // TERMINATION GUARANTEE. Every page here has the full body height, so `fitted === null` means
+            // nothing fit even on a whole page - the region did not get smaller. Advancing to the
+            // (identical) remainder would loop forever. So we stop: place the region whole (clipped to the
+            // page) and surface it per the overflow policy. A step that shrinks nothing ends the loop, for
+            // ANY region - an oversized unbreakable block, a future keep-together group, or an engine bug.
+            if (fitted === null) {
+                // Measure the region's true height for the message (rare path, so the extra pass is free);
+                // pass B lays it out again, so this mutation does not leak.
+                const needed = region.calculateLayout(BoxConstraints.loose(width, Infinity), { x: 0, y: 0 }, pageCtx).height;
+                reportOverflow(region, needed, height, pageCtx.onOverflow ?? "ignore");
+                pages.push({ kind: "fragment", config, content: region, header, footer });
+                break;
             }
+            pages.push({ kind: "fragment", config, content: fitted, header, footer });
             region = remainder;
             isFirstRegion = false;
         }
-        return numbers;
+        return pages;
     }
     /**
-     * Lays out one fragment on a fresh page of the same geometry and renders it. The
-     * header/footer are attached to every physical page so they repeat; `PageElement`
+     * Lays out one physical page and renders it. A fragment gets a fresh `PageElement` of the same
+     * geometry; the header/footer are attached to every physical page so they repeat, and `PageElement`
      * re-places them and the body in the band between.
      */
-    static async renderPhysicalPage(config, content, header, footer, objectManager, ctx) {
-        const physicalPage = new PageElement({
-            config,
-            header,
-            footer,
-            children: [content],
+    static async renderPhysicalPage(physical, objectManager, ctx) {
+        if (physical.kind === "whole") {
+            physical.page.calculateLayout(new BoxConstraints(), { x: 0, y: 0 }, ctx);
+            return PageRenderer.render(physical.page, objectManager);
+        }
+        const page = new PageElement({
+            config: physical.config,
+            header: physical.header,
+            footer: physical.footer,
+            children: [physical.content],
         });
-        physicalPage.calculateLayout(new BoxConstraints(), { x: 0, y: 0 }, ctx);
-        return PageRenderer.render(physicalPage, objectManager);
+        page.calculateLayout(new BoxConstraints(), { x: 0, y: 0 }, ctx);
+        return PageRenderer.render(page, objectManager);
     }
 }

package/dist/renderer/pdf-renderer.js

@@ -21,7 +21,24 @@ 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 { LinkElement } from "../elements/layout/link-element.js";
+import { LinkRenderer } from "./link-renderer.js";
+import { BookmarkElement } from "../elements/layout/bookmark-element.js";
+import { BookmarkRenderer } from "./bookmark-renderer.js";
+import { AnchorElement } from "../elements/layout/anchor-element.js";
+import { PageBreakElement } from "../elements/layout/page-break-element.js";
+import { AnchorRenderer } from "./anchor-renderer.js";
+import { PageBreakRenderer } from "./page-break-renderer.js";
+import { KeepTogetherElement } from "../elements/layout/keep-together-element.js";
+import { KeepTogetherRenderer } from "./keep-together-renderer.js";
+import { PageBuilderElement } from "../elements/layout/page-builder-element.js";
+import { PageBuilderRenderer } from "./page-builder-renderer.js";
+import { RotatedElement } from "../elements/layout/rotated-element.js";
+import { RotatedBoxElement } from "../elements/layout/rotated-box-element.js";
+import { RotatedRenderer } from "./rotated-renderer.js";
+import { PdfBackend } from "./pdf-backend.js";
 import { BoxConstraints } from "../layout/box-constraints.js";
+import { collectImageElements } from "../layout/collect-images.js";
 import { DEFAULT_TEXT_STYLE, mergeTextStyle } from "../text/text-style.js";
 export class PDFRenderer {
     static async render(document, objectManager) {
@@ -32,6 +49,8 @@ export class PDFRenderer {
         RendererRegistry.register(RectangleElement, RectangleRenderer.render);
         RendererRegistry.register(ExpandedElement, ExpandedRenderer.render);
         RendererRegistry.register(PaddingElement, PaddingRenderer.render);
+        RendererRegistry.register(PageBreakElement, PageBreakRenderer.render);
+        RendererRegistry.register(KeepTogetherElement, KeepTogetherRenderer.render);
         RendererRegistry.register(DefaultTextStyleElement, DefaultTextStyleRenderer.render);
         RendererRegistry.register(ImageElement, ImageRenderer.render);
         RendererRegistry.register(LineElement, LineRenderer.render);
@@ -39,6 +58,12 @@ export class PDFRenderer {
         RendererRegistry.register(DeferredElement, DeferredRenderer.render);
         RendererRegistry.register(PositionedElement, PositionedRenderer.render);
         RendererRegistry.register(StructGroup, StructGroupRenderer.render);
+        RendererRegistry.register(LinkElement, LinkRenderer.render);
+        RendererRegistry.register(BookmarkElement, BookmarkRenderer.render);
+        RendererRegistry.register(AnchorElement, AnchorRenderer.render);
+        RendererRegistry.register(PageBuilderElement, PageBuilderRenderer.render);
+        RendererRegistry.register(RotatedElement, RotatedRenderer.render);
+        RendererRegistry.register(RotatedBoxElement, RotatedRenderer.render);
         let pdfContent = "";
         // Header: version line + the PDF/A binary marker (the object manager owns it so its length
         // matches the xref offset calculation).
@@ -51,6 +76,11 @@ export class PDFRenderer {
             textStyle: mergeTextStyle(DEFAULT_TEXT_STYLE, document.getDefaultTextStyle()),
             onOverflow: objectManager.getOverflowPolicy(),
         };
+        // Pre-layout: resolve every image's intrinsic pixel size (async), so the synchronous layout can
+        // give a width-only image a proportional height. init() is idempotent, so the renderer reuses it.
+        const images = collectImageElements(document);
+        if (images.length > 0)
+            await Promise.all(images.map((img) => img.resolveIntrinsicSize()));
         document.calculateLayout(new BoxConstraints(), { x: 0, y: 0 }, ctx);
         // Render pages and contents (the driver paginates overflowing pages).
         await PDFDocumentRenderer.render(document, objectManager, ctx);
@@ -66,11 +96,20 @@ export class PDFRenderer {
         if (outputIntent) {
             catalogParts.push(`/OutputIntents [${outputIntent} 0 R]`);
         }
+        // The catalog has exactly one /Names dict; embedded files and named destinations are two entries in
+        // it, so collect both and emit the /Names once (below).
+        const namesParts = [];
         const attachments = objectManager.getAttachments();
         if (attachments.length > 0) {
-            const names = attachments.map((a) => `(${a.name}) ${a.filespec} 0 R`).join(" ");
+            // The name-tree key is a PDF literal string, so it needs the same escaping the /Filespec's /F and
+            // /UF get in attachFile(). Unescaped, a ")" or "\" in a file name closes the string early and the
+            // rest of it leaks out as raw operators.
+            const names = attachments
+                .map((a) => `(${PdfBackend.escapePdfString(a.name)}) ${a.filespec} 0 R`)
+                .join(" ");
             const af = attachments.map((a) => `${a.filespec} 0 R`).join(" ");
-            catalogParts.push(`/AF [${af}]`, `/Names << /EmbeddedFiles << /Names [${names}] >> >>`);
+            catalogParts.push(`/AF [${af}]`);
+            namesParts.push(`/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.
@@ -80,6 +119,18 @@ export class PDFRenderer {
             // PDF/UA requires the viewer to show the document title (not the file name).
             catalogParts.push("/ViewerPreferences << /DisplayDocTitle true >>");
         }
+        // Document outline (bookmarks): emit the /Outlines tree collected during page rendering. Returns
+        // "" (no-op) when no Bookmark was placed, so a plain document's catalog is unchanged.
+        const outlineCatalog = objectManager.outline.finalize(objectManager);
+        if (outlineCatalog)
+            catalogParts.push(outlineCatalog);
+        // Named destinations (internal-link targets): a /Dests entry in the shared /Names dict.
+        const destsNames = objectManager.dests.finalize();
+        if (destsNames)
+            namesParts.push(destsNames);
+        // Emit the single /Names dict if either embedded files or destinations contributed to it.
+        if (namesParts.length > 0)
+            catalogParts.push(`/Names << ${namesParts.join(" ")} >>`);
         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/rotated-renderer.d.ts

@@ -0,0 +1,7 @@
+import { PDFObjectManager } from "../utils/pdf-object-manager.js";
+import { RotatedElement } from "../elements/layout/rotated-element.js";
+import { RotatedBoxElement } from "../elements/layout/rotated-box-element.js";
+import { IRNode } from "../ir/display-list.js";
+export declare class RotatedRenderer {
+    static render(element: RotatedElement | RotatedBoxElement, objectManager: PDFObjectManager): Promise<IRNode[]>;
+}

package/dist/renderer/rotated-renderer.js

@@ -0,0 +1,29 @@
+import { RendererRegistry } from "../utils/renderer-registry.js";
+export class RotatedRenderer {
+    // Both `Rotated` (paint-only) and `RotatedBox` (layout-aware quarter-turns) expose the same
+    // `{ angle, child, x, y, width, height }` and rotate the child around the box center - shared here.
+    static async render(element, objectManager) {
+        const { angle, child, x, y, width, height } = element.getProps();
+        // Rotate around the box CENTER, in the engine's top-left coordinates (the IR->backend seam flips
+        // the matrix to PDF space per page). A positive angle reads clockwise on the page.
+        const cx = x + width / 2;
+        const cy = y + height / 2;
+        const theta = (angle * Math.PI) / 180;
+        const cos = Math.cos(theta);
+        const sin = Math.sin(theta);
+        // M = T(cx,cy) · R(theta) · T(-cx,-cy) as a PDF cm [a,b,c,d,e,f]: the linear part is the rotation,
+        // the translation keeps the center fixed.
+        const matrix = [
+            cos,
+            sin,
+            -sin,
+            cos,
+            cx - cos * cx + sin * cy,
+            cy - sin * cx - cos * cy,
+        ];
+        const renderer = RendererRegistry.getRenderer(child);
+        const childNodes = renderer ? await renderer(child, objectManager) : [];
+        // Wrap the child's drawing between a push (apply the matrix) and a pop (restore).
+        return [{ type: "transform-push", matrix }, ...childNodes, { type: "transform-pop" }];
+    }
+}

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

@@ -4,7 +4,7 @@ import type { FontMetrics } from "../utils/font-metrics.js";
 import { IRNode } from "../ir/display-list.js";
 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 calculateTextHeight(content: string | TextSegment[], fontSize: number, fontFamily: string, fontStyle: FontStyle, objectManager: FontMetrics, maxWidth: number, maxLines?: number, overflow?: TextOverflow, lineHeight?: number, letterSpacing?: number): number;
     static render(textElement: TextElement, objectManager: PDFObjectManager): Promise<IRNode[]>;
     private static _expandColorGlyphs;
     private static _glyphToPath;