@jasy/pdf 1.0.0-beta.2 → 1.0.0-beta.4

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

@@ -18,7 +18,7 @@ export class PDFDocumentRenderer {
         // `Page` element produces one run of sheets, so the run's length is that section's total.
         const section = [];
         for (const page of document.getProps().children) {
-            const sheets = PDFDocumentRenderer.paginateLogicalPage(page, ctx);
+            const sheets = PDFDocumentRenderer.paginateLogicalPage(page, ctx, physicalPages.length + 1);
             sheets.forEach((_, i) => section.push({ number: i + 1, total: sheets.length }));
             physicalPages.push(...sheets);
         }
@@ -47,17 +47,11 @@ export class PDFDocumentRenderer {
         objectManager.replaceObject(pagesObjectNumber, updatedPagesObject);
         return pagesObjectNumber;
     }
-    /**
-     * 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.
-     */
+    /** The page geometry a physical page will use: resolved, never read back from an earlier layout. */
     static configOf(physical, ctx) {
-        const config = physical.kind === "whole" ? physical.page.getProps().config : physical.config;
-        return { ...ctx.pageConfig, ...config };
+        return physical.kind === "whole"
+            ? physical.page.resolveConfig(ctx.pageConfig)
+            : physical.config;
     }
     /**
      * Splits one logical page into the physical pages it will occupy, without rendering.
@@ -66,13 +60,15 @@ export class PDFDocumentRenderer {
      * (a Container). Anything else stays a single page on the unchanged path, so non-overflowing
      * documents keep producing byte-identical output.
      */
-    static paginateLogicalPage(page, ctx) {
-        const { children, config, header, footer } = page.getProps();
+    static paginateLogicalPage(page, ctx, firstPage) {
+        const { children, header, footer } = page.getProps();
+        // Resolved here, not read back from an earlier layout pass that happened to merge it.
+        const config = page.resolveConfig(ctx.pageConfig);
         if (children.length !== 1 || !isFragmentable(children[0])) {
             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).
+        // band between them. Resolve that band once.
         // 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.
@@ -81,7 +77,9 @@ export class PDFDocumentRenderer {
             pageConfig: config,
             textStyle: ctx.textStyle,
             onOverflow: ctx.onOverflow,
+            diagnostics: ctx.diagnostics,
             frame: pageFrame(config),
+            paginatingPage: firstPage, // the bands are laid out here once, for the first sheet
         };
         const { bodyWidth: width, bodyHeight: height } = layoutPageBands(config, header, footer, pageCtx);
         // A `keepTogether` group compares its height against a FULL fresh page (this band), so thread it in.
@@ -97,6 +95,7 @@ export class PDFDocumentRenderer {
             }
             // 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.
+            pageCtx.paginatingPage = firstPage + pages.length;
             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
@@ -115,8 +114,8 @@ export class PDFDocumentRenderer {
             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");
+                const needed = region.measure(BoxConstraints.loose(width, Infinity), pageCtx).height;
+                reportOverflow(region, needed, height, pageCtx);
                 pages.push({ kind: "fragment", config, content: region, header, footer });
                 break;
             }

package/dist/renderer/pdf-renderer.js

@@ -1,3 +1,4 @@
+import { comparePdfText } from "../text/pdf-text-string.js";
 import { PDFDocumentRenderer } from "./pdf-document-renderer.js";
 import { RendererRegistry } from "../utils/renderer-registry.js";
 import { DefaultTextStyleElement, ExpandedElement, ImageElement, LineElement, CanvasElement, PaddingElement, SvgElement, TextElement, } from "../elements/index.js";
@@ -45,8 +46,6 @@ 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 {
@@ -85,21 +84,21 @@ export class PDFRenderer {
         // Header: version line + the PDF/A binary marker (the object manager owns it so its length
         // matches the xref offset calculation).
         pdfContent += objectManager.getHeader();
-        // Layout pass: thread the context explicitly. The seed page config is the document
-        // default; each PageElement overrides it for its own subtree.
+        // The layout context, threaded explicitly. The seed page config is the document default; each
+        // PageElement overrides it for its own subtree.
         const ctx = {
             metrics: objectManager,
             pageConfig: objectManager.getPDFConfig(),
             textStyle: mergeTextStyle(DEFAULT_TEXT_STYLE, document.getDefaultTextStyle()),
             onOverflow: objectManager.getOverflowPolicy(),
+            diagnostics: objectManager.diagnostics,
         };
         // 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).
+        // Paginate, then lay out and render page by page (the driver does both; nothing is laid out before).
         await PDFDocumentRenderer.render(document, objectManager, ctx);
         // Add the catalog. XMP metadata (/Metadata) and embedded files (/AF + /Names/EmbeddedFiles)
         // are added only when present; with neither, the catalog is byte-identical to before.
@@ -118,11 +117,12 @@ export class PDFRenderer {
         const namesParts = [];
         const attachments = objectManager.getAttachments();
         if (attachments.length > 0) {
-            // 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`)
+            // The name-tree key is a text string like the /Filespec's /F and /UF, so it goes through the same
+            // choke point - encoded and, in an encrypted file, enciphered. A name tree is SORTED by its keys
+            // (a reader may search it), so the keys are ordered by their bytes first.
+            const names = [...attachments]
+                .sort((a, b) => comparePdfText(a.name, b.name))
+                .map((a) => `${objectManager.pdfString(a.name)} ${a.filespec} 0 R`)
                 .join(" ");
             const af = attachments.map((a) => `${a.filespec} 0 R`).join(" ");
             catalogParts.push(`/AF [${af}]`);

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

@@ -1,6 +1,11 @@
 import { PDFObjectManager } from "../utils/pdf-object-manager.js";
 import { PositionedElement } from "../elements/layout/positioned-element.js";
+import { type RenderScope } from "../utils/renderer-registry.js";
 import { IRNode } from "../ir/display-list.js";
 export declare class PositionedRenderer {
-    static render(positionedElement: PositionedElement, objectManager: PDFObjectManager): Promise<IRNode[]>;
+    /**
+     * Drawn at its own place in the tree (tree order is paint order), from its frame: the child was laid
+     * out relative to the frame's top-left, not to the flow it sits in.
+     */
+    static render(positionedElement: PositionedElement, objectManager: PDFObjectManager, scope: RenderScope): Promise<IRNode[]>;
 }

package/dist/renderer/positioned-renderer.js

@@ -1,10 +1,11 @@
 import { RendererRegistry } from "../utils/renderer-registry.js";
 export class PositionedRenderer {
-    static async render(positionedElement, objectManager) {
-        // The child was already placed (by the frame) during layout; just emit its IR. It is drawn
-        // after the frame's flow content, so it paints on top.
+    /**
+     * Drawn at its own place in the tree (tree order is paint order), from its frame: the child was laid
+     * out relative to the frame's top-left, not to the flow it sits in.
+     */
+    static async render(positionedElement, objectManager, scope) {
         const { child } = positionedElement.getProps();
-        const renderer = RendererRegistry.getRenderer(child);
-        return renderer(child, objectManager);
+        return RendererRegistry.render(child, objectManager, { ...scope, origin: scope.frame });
     }
 }

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

@@ -1,8 +1,9 @@
 import { PDFObjectManager } from "../utils/pdf-object-manager.js";
 import { RectangleElement } from "../elements/rectangle-element.js";
+import { type RenderScope } from "../utils/renderer-registry.js";
 import { IRNode } from "../ir/display-list.js";
 export declare class RectangleRenderer {
-    static render(rectangleElement: RectangleElement, objectManager: PDFObjectManager): Promise<IRNode[]>;
+    static render(rectangleElement: RectangleElement, objectManager: PDFObjectManager, scope: RenderScope): Promise<IRNode[]>;
     /** One `line` node per present side, along the box edges (top-left coordinates). */
     private static sideLines;
 }

package/dist/renderer/rectangle-renderer.js

@@ -1,8 +1,11 @@
 import { RendererRegistry } from "../utils/renderer-registry.js";
 import { isGradientInput, resolveGradient } from "../api/gradient.js";
 export class RectangleRenderer {
-    static async render(rectangleElement, objectManager) {
-        const { x, y, width, height, children, color, backgroundColor, borderWidth, radius, sideBorders, overflow, } = rectangleElement.getProps();
+    static async render(rectangleElement, objectManager, scope) {
+        const { x: ownX, y: ownY, width, height, children, color, backgroundColor, borderWidth, radius, sideBorders, overflow, relative, } = rectangleElement.getProps();
+        // Its own position is relative to `scope.origin`; the IR wants page coordinates.
+        const x = scope.origin.x + (ownX ?? 0);
+        const y = scope.origin.y + (ownY ?? 0);
         const h = height;
         const nodes = [];
         // A gradient is written box-relative (an angle and stops); this is the first place the box is
@@ -41,10 +44,12 @@ export class RectangleRenderer {
         if (clip) {
             nodes.push({ type: "clip-push", x, y, width, height: h, ...(radius ? { radius } : {}) });
         }
+        // Its children are placed relative to its own top-left; a `relative` box is also the frame its
+        // `Positioned` descendants were placed against.
+        const childScope = { origin: { x, y }, frame: relative ? { x, y } : scope.frame };
         if (children)
             for (const child of children) {
-                const renderer = RendererRegistry.getRenderer(child);
-                nodes.push(...(await renderer(child, objectManager)));
+                nodes.push(...(await RendererRegistry.render(child, objectManager, childScope)));
             }
         if (clip)
             nodes.push({ type: "clip-pop" });

package/dist/renderer/repeating-header-renderer.d.ts

@@ -1,6 +1,7 @@
 import { PDFObjectManager } from "../utils/pdf-object-manager.js";
 import { RepeatingHeaderElement } from "../elements/layout/repeating-header-element.js";
+import { type RenderScope } from "../utils/renderer-registry.js";
 import { IRNode } from "../ir/display-list.js";
 export declare class RepeatingHeaderRenderer {
-    static render(element: RepeatingHeaderElement, objectManager: PDFObjectManager): Promise<IRNode[]>;
+    static render(element: RepeatingHeaderElement, objectManager: PDFObjectManager, scope: RenderScope): Promise<IRNode[]>;
 }

package/dist/renderer/repeating-header-renderer.js

@@ -1,11 +1,12 @@
-import { RendererRegistry } from "../utils/renderer-registry.js";
+import { RendererRegistry, within } from "../utils/renderer-registry.js";
 export class RepeatingHeaderRenderer {
-    static async render(element, objectManager) {
-        const { header, body } = element.getProps();
+    static async render(element, objectManager, scope) {
+        const { x, y, header, body } = element.getProps();
         const nodes = [];
+        // Header and body are placed relative to its own top-left.
+        const inner = within(scope, { x, y });
         for (const child of [header, body]) {
-            const renderer = RendererRegistry.getRenderer(child);
-            nodes.push(...(await renderer(child, objectManager)));
+            nodes.push(...(await RendererRegistry.render(child, objectManager, inner)));
         }
         return nodes;
     }

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

@@ -1,7 +1,8 @@
 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 { type RenderScope } from "../utils/renderer-registry.js";
 import { IRNode } from "../ir/display-list.js";
 export declare class RotatedRenderer {
-    static render(element: RotatedElement | RotatedBoxElement, objectManager: PDFObjectManager): Promise<IRNode[]>;
+    static render(element: RotatedElement | RotatedBoxElement, objectManager: PDFObjectManager, scope: RenderScope): Promise<IRNode[]>;
 }

package/dist/renderer/rotated-renderer.js

@@ -1,9 +1,12 @@
-import { RendererRegistry } from "../utils/renderer-registry.js";
+import { RendererRegistry, within } 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();
+    static async render(element, objectManager, scope) {
+        const { angle, child, x: ownX, y: ownY, width, height } = element.getProps();
+        // Its own position is relative to `scope.origin`; the IR wants page coordinates.
+        const x = scope.origin.x + (ownX ?? 0);
+        const y = scope.origin.y + (ownY ?? 0);
         // 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;
@@ -21,8 +24,8 @@ export class RotatedRenderer {
             cx - cos * cx + sin * cy,
             cy - sin * cx - cos * cy,
         ];
-        const renderer = RendererRegistry.getRenderer(child);
-        const childNodes = await renderer(child, objectManager);
+        // The child is placed relative to the box top-left.
+        const childNodes = await RendererRegistry.render(child, objectManager, within(scope, { x: ownX, y: ownY }));
         // 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/row-renderer.d.ts

@@ -1,6 +1,7 @@
 import { PDFObjectManager } from "../utils/pdf-object-manager.js";
 import { RowElement } from "../elements/row-element.js";
+import { type RenderScope } from "../utils/renderer-registry.js";
 import { IRNode } from "../ir/display-list.js";
 export declare class RowRenderer {
-    static render(rowElement: RowElement, objectManager: PDFObjectManager): Promise<IRNode[]>;
+    static render(rowElement: RowElement, objectManager: PDFObjectManager, scope: RenderScope): Promise<IRNode[]>;
 }

package/dist/renderer/row-renderer.js

@@ -1,12 +1,13 @@
-import { RendererRegistry } from "../utils/renderer-registry.js";
+import { RendererRegistry, within } from "../utils/renderer-registry.js";
 export class RowRenderer {
-    static async render(rowElement, objectManager) {
-        const { children } = rowElement.getProps();
+    static async render(rowElement, objectManager, scope) {
+        const { x, y, children } = rowElement.getProps();
         const nodes = [];
+        // Its children are placed relative to its own top-left.
+        const inner = within(scope, { x, y });
         if (children)
             for (const child of children) {
-                const renderer = RendererRegistry.getRenderer(child);
-                nodes.push(...(await renderer(child, objectManager)));
+                nodes.push(...(await RendererRegistry.render(child, objectManager, inner)));
             }
         return nodes;
     }

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

@@ -1,10 +1,11 @@
 import { StructGroup } from "../elements/layout/struct-group.js";
 import { PDFObjectManager } from "../utils/pdf-object-manager.js";
 import { IRNode } from "../ir/display-list.js";
+import { type RenderScope } 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 declare class StructGroupRenderer {
-    static render(group: StructGroup, objectManager: PDFObjectManager): Promise<IRNode[]>;
+    static render(group: StructGroup, objectManager: PDFObjectManager, scope: RenderScope): Promise<IRNode[]>;
 }

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

@@ -4,11 +4,10 @@ import { RendererRegistry } from "../utils/renderer-registry.js";
  * tagging off it is fully transparent - just the child's IR.
  */
 export class StructGroupRenderer {
-    static async render(group, objectManager) {
+    static async render(group, objectManager, scope) {
         const { role, child } = group.getProps();
         const renderChild = async () => {
-            const renderer = RendererRegistry.getRenderer(child);
-            return renderer(child, objectManager);
+            return RendererRegistry.render(child, objectManager, scope);
         };
         if (!objectManager.struct.enabled)
             return renderChild();

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

@@ -1,3 +1,4 @@
+import type { RenderScope } from "../utils/renderer-registry.js";
 import { PDFObjectManager } from "../utils/pdf-object-manager.js";
 import { SvgElement } from "../elements/svg-element.js";
 import type { IRNode } from "../ir/display-list.js";
@@ -7,5 +8,5 @@ import type { IRNode } from "../ir/display-list.js";
  * that colour emoji already draw through carries it.
  */
 export declare class SvgRenderer {
-    static render(element: SvgElement, objectManager: PDFObjectManager): Promise<IRNode[]>;
+    static render(element: SvgElement, objectManager: PDFObjectManager, scope: RenderScope): Promise<IRNode[]>;
 }

package/dist/renderer/svg-renderer.js

@@ -5,8 +5,14 @@ import { svgToIr } from "../svg/index.js";
  * that colour emoji already draw through carries it.
  */
 export class SvgRenderer {
-    static async render(element, objectManager) {
-        const { x, y, width, height, source, alt } = element.getProps();
+    static async render(element, objectManager, scope) {
+        await element.load(); // an SVG from a URL; already done when the pre-layout pass reached it
+        const { x: ownX, y: ownY, width, height, source, alt } = element.getProps();
+        if (source === undefined)
+            throw new Error("@jasy/pdf: an SVG was drawn before it was loaded");
+        // Its own position is relative to `scope.origin`; the IR wants page coordinates.
+        const x = scope.origin.x + (ownX ?? 0);
+        const y = scope.origin.y + (ownY ?? 0);
         const nodes = svgToIr(source, {
             x: x ?? 0,
             y: y ?? 0,

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

@@ -1,11 +1,9 @@
-import { TextElement, TextSegment } from "../elements/text-element.js";
-import { FontStyle, PDFObjectManager } from "../utils/pdf-object-manager.js";
-import type { FontMetrics } from "../utils/font-metrics.js";
+import type { RenderScope } from "../utils/renderer-registry.js";
+import { TextElement } from "../elements/text-element.js";
+import { PDFObjectManager } from "../utils/pdf-object-manager.js";
 import { IRNode } from "../ir/display-list.js";
-import { type LineOptions, 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, letterSpacing?: number, lineOptions?: LineOptions): number;
-    static render(textElement: TextElement, objectManager: PDFObjectManager): Promise<IRNode[]>;
+    static render(textElement: TextElement, objectManager: PDFObjectManager, scope: RenderScope): Promise<IRNode[]>;
     private static _expandColorGlyphs;
     private static _glyphToPath;
     private static _toGradient;