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

package/dist/renderer/page-renderer.js

@@ -25,7 +25,11 @@ 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 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);
@@ -58,8 +62,54 @@ 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" : "";
+        // 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}${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

@@ -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,21 @@ 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. */
+    /**
+     * 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
      * 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,45 @@ 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 };
+                }
+                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;
@@ -51,9 +91,58 @@ 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. */
+    /**
+     * 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);
+            // 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;
+        })
+            .join("");
     }
     /**
      * Escapes a string for a PDF literal string `( ... )`. The backslash must be doubled
@@ -189,8 +278,51 @@ 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`;
+            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

@@ -19,7 +19,22 @@ 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 { 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) {
@@ -36,6 +51,13 @@ export class PDFRenderer {
         RendererRegistry.register(RepeatingHeaderElement, RepeatingHeaderRenderer.render);
         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).
@@ -48,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);
@@ -63,12 +90,41 @@ 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.
+        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 >>");
+        }
+        // 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/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;
 }