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

package/dist/renderer/bookmark-renderer.js

@@ -0,0 +1,11 @@
+import { RendererRegistry } from "../utils/renderer-registry.js";
+export class BookmarkRenderer {
+    static async render(element, objectManager) {
+        const { title, level, child, y } = element.getProps();
+        const renderer = RendererRegistry.getRenderer(child);
+        const childNodes = renderer ? await renderer(child, objectManager) : [];
+        // The child draws normally; an Outline IR node carries the title + nesting + scroll target for the
+        // page renderer to collect into the /Outlines tree (it produces no content-stream ops itself).
+        return [...childNodes, { type: "outline", y, title, level }];
+    }
+}

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

@@ -0,0 +1,6 @@
+import { PDFObjectManager } from "../utils/pdf-object-manager.js";
+import { LinkElement } from "../elements/layout/link-element.js";
+import { IRNode } from "../ir/display-list.js";
+export declare class LinkRenderer {
+    static render(element: LinkElement, objectManager: PDFObjectManager): Promise<IRNode[]>;
+}

package/dist/renderer/link-renderer.js

@@ -0,0 +1,11 @@
+import { RendererRegistry } from "../utils/renderer-registry.js";
+export class LinkRenderer {
+    static async render(element, objectManager) {
+        const { href, dest, child, x, y, width, height } = element.getProps();
+        const renderer = RendererRegistry.getRenderer(child);
+        const childNodes = renderer ? await renderer(child, objectManager) : [];
+        // The child draws normally; a Link IR node carries the clickable rect + target (external href or
+        // internal dest) for the page renderer to emit as a /Link annotation (no content-stream ops itself).
+        return [...childNodes, { type: "link", x, y, width, height, href, dest }];
+    }
+}

package/dist/renderer/page-builder-renderer.d.ts

@@ -0,0 +1,6 @@
+import { PDFObjectManager } from "../utils/pdf-object-manager.js";
+import { PageBuilderElement } from "../elements/layout/page-builder-element.js";
+import { IRNode } from "../ir/display-list.js";
+export declare class PageBuilderRenderer {
+    static render(element: PageBuilderElement, objectManager: PDFObjectManager): Promise<IRNode[]>;
+}

package/dist/renderer/page-builder-renderer.js

@@ -0,0 +1,11 @@
+import { RendererRegistry } from "../utils/renderer-registry.js";
+export class PageBuilderRenderer {
+    static async render(element, objectManager) {
+        // `composed` is whatever the closure built for THIS page during the render pass's layout.
+        const { composed } = element.getProps();
+        if (!composed)
+            return [];
+        const renderer = RendererRegistry.getRenderer(composed);
+        return renderer ? renderer(composed, objectManager) : [];
+    }
+}

package/dist/renderer/page-renderer.js

@@ -28,7 +28,8 @@ export class PageRenderer {
         // 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);
+        const flipped = PdfBackend.flipY(nodes, height);
+        const pageContent = PdfBackend.serialize(flipped, 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);
@@ -67,14 +68,48 @@ export class PageRenderer {
             shadingReferences.push(`/${name} ${objectNumber} 0 R`);
         });
         const shadingCode = shadingReferences.length > 0 ? "/Shading <<\n" + shadingReferences.join("\n") + "\n>>\n" : "";
+        // Hyperlinks: a `Link` IR node drew nothing into the content stream - here its (already Y-flipped)
+        // rect + href become a /Link annotation object. `/Border [0 0 0]` hides the default visible frame;
+        // the URL is escaped like any PDF literal string. Refs are collected into the page's /Annots below.
+        const num = (n) => Number(n.toFixed(2));
+        const annotRefs = [];
+        for (const node of flipped) {
+            if (node.type !== "link")
+                continue;
+            const rect = `[${num(node.x)} ${num(node.y)} ${num(node.x + node.width)} ${num(node.y + node.height)}]`;
+            // Either an external URL (/URI) or an internal named destination (/GoTo, resolved via /Names /Dests).
+            // The Link IR guarantees exactly one is set; prefer `dest` when present.
+            const action = node.dest !== undefined
+                ? `/A << /S /GoTo /D (${PdfBackend.escapePdfString(node.dest)}) >>`
+                : `/A << /S /URI /URI (${PdfBackend.escapePdfString(node.href ?? "")}) >>`;
+            const annot = objectManager.addObject(`<< /Type /Annot /Subtype /Link /Rect ${rect} /Border [0 0 0] ${action} >>`);
+            annotRefs.push(`${annot} 0 R`);
+        }
+        const annotsCode = annotRefs.length > 0 ? ` /Annots [${annotRefs.join(" ")}]` : "";
         // 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} >>`;
+        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}${annotsCode} >>`;
         // 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);
+        // Bookmarks + named destinations: an `Outline`/`Anchor` IR node drew nothing; record it now that the
+        // page's object number is known. `node.y` is already Y-flipped to the page-space scroll target.
+        // PDFRenderer builds /Outlines and /Names /Dests at the end.
+        for (const node of flipped) {
+            if (node.type === "outline") {
+                objectManager.outline.add({
+                    title: node.title,
+                    level: node.level,
+                    pageObjNum,
+                    top: node.y,
+                });
+            }
+            else if (node.type === "anchor") {
+                objectManager.dests.add(node.name, { pageObjNum, top: node.y });
+            }
+        }
         return pageObjNum;
     }
 }

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

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;
@@ -247,6 +307,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-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, PageElement, resolvePageSize, } from "../elements/page-element.js";
 import { BoxConstraints } from "../layout/box-constraints.js";
 import { isFragmentable } 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,16 +41,28 @@ 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).
@@ -46,45 +73,50 @@ export class PDFDocumentRenderer {
             onOverflow: ctx.onOverflow,
         };
         const { bodyWidth: width, bodyHeight: height } = layoutPageBands(config, header, footer, pageCtx);
-        const numbers = [];
+        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).
+            // 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 } = 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).
             if (isFirstRegion && remainder === null) {
-                page.calculateLayout(new BoxConstraints(), { x: 0, y: 0 }, ctx);
-                numbers.push(await PageRenderer.render(page, objectManager));
+                pages.push({ kind: "whole", page });
                 break;
             }
             if (fitted) {
-                numbers.push(await PDFDocumentRenderer.renderPhysicalPage(config, fitted, header, footer, objectManager, ctx));
+                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,20 @@ 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 { AnchorRenderer } from "./anchor-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) {
@@ -39,6 +52,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 +70,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 +90,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 +113,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.js

@@ -24,7 +24,7 @@ export class TextRenderer {
         // 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.
-        const runs = TextRenderer._buildRuns(content, fontSize, fontFamily, fontStyle, objectManager, width ?? Number.NaN, textAlignment, color, x, y, maxLines, overflow, lineHeight);
+        const { runs, links } = 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.
@@ -36,7 +36,10 @@ export class TextRenderer {
         }
         // 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();
+        const drawn = (await Promise.all(runs.map((run) => TextRenderer._expandColorGlyphs(run, objectManager)))).flat();
+        // Inline hyperlinks (href spans) ride along as /Link annotations - they draw nothing, so order
+        // vs the drawn runs does not matter; the page renderer peels them off into /Annots.
+        return links.length > 0 ? [...drawn, ...links] : drawn;
     }
     // 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]`
@@ -208,6 +211,9 @@ export class TextRenderer {
     // only the output form changed from PDF strings to `TextRun`s.
     static _buildRuns(content, fontSize, fontFamily, fontStyle, objectManager, maxWidth, textAlignment, color, initialX, yPosition, maxLines, overflow, lineHeight = 1) {
         const runs = [];
+        // /Link annotation rects for any `href` spans, collected as we place segments. Empty for the
+        // common (no-href) case, so plain text keeps producing exactly the runs it did before.
+        const links = [];
         // Horizontal offset of a line of the given width under the current alignment.
         const alignmentOffset = (lineWidth) => {
             if (textAlignment === HorizontalAlignment.center)
@@ -248,7 +254,7 @@ export class TextRenderer {
                     color,
                 });
             });
-            return runs;
+            return { runs, links };
         }
         // --- Segments: break into lines (shared breaker), then emit one run per segment.
         // Segment 0 starts at the aligned line origin; each following segment is offset by
@@ -261,6 +267,7 @@ export class TextRenderer {
                 const family = segment.fontFamily || fontFamily;
                 const size = segment.fontSize || fontSize;
                 const style = segment.fontStyle || fontStyle;
+                const advance = advanceNoKerning(segment.content, family, size, style);
                 runs.push({
                     type: "text",
                     x,
@@ -271,7 +278,21 @@ export class TextRenderer {
                     fontSize: size,
                     color: segment.fontColor || color,
                 });
-                x += advanceNoKerning(segment.content, family, size, style);
+                // An href/to span becomes a /Link annotation over exactly this run's glyph box. `lineY` is the
+                // baseline; the box spans from the ascent (BASELINE_RATIO above it) down by the full size, so
+                // ascent + descent are covered. A span wrapped across lines yields one rect per line.
+                if (segment.href !== undefined || segment.dest !== undefined) {
+                    links.push({
+                        type: "link",
+                        x,
+                        y: lineY - size * BASELINE_RATIO,
+                        width: advance,
+                        height: size,
+                        href: segment.href,
+                        dest: segment.dest,
+                    });
+                }
+                x += advance;
             });
         };
         // The overall tallest font seats the first baseline; each line then steps DOWN by
@@ -291,6 +312,6 @@ export class TextRenderer {
             pushLine(line, lineY + halfLeading);
             lineY += line.maxFontSize * lineHeight;
         }
-        return runs;
+        return { runs, links };
     }
 }