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

package/dist/layout/fragmentation.js

@@ -22,18 +22,21 @@ export function insetContext(ctx, chrome) {
     return { ...ctx, pageBodyHeight: ctx.pageBodyHeight - chrome };
 }
 export function reportOverflow(child, childHeight, maxHeight, ctx) {
-    const policy = ctx.onOverflow ?? "ignore";
     const name = child.constructor.name.replace(/Element$/, "");
-    const detail = `${name} is ${Math.round(childHeight)}pt tall but the page region is only ` +
+    reportClipped(child, `${name} is ${Math.round(childHeight)}pt tall but the page region is only ` +
         `${Math.round(maxHeight)}pt and it cannot be broken - reduce its size, give it a bounded ` +
-        `height, or let it split across pages.`;
+        `height, or let it split across pages.`, ctx);
+}
+/** Content cut off at the bottom, under the author's `onOverflow` policy. */
+export function reportClipped(about, detail, ctx) {
+    const policy = ctx.onOverflow ?? "ignore";
     if (policy === "error")
         throw new Error(`Layout overflow: ${detail}`);
     diagnose(ctx.diagnostics, {
         code: "overflow-clipped",
         severity: "warning",
         message: `Layout overflow (clipped): ${detail}`,
-        about: child,
+        about,
         page: pageOf(ctx),
         // `ignore` means "no console" - an `onDiagnostic` handler still hears of it.
         fallback: policy === "ignore" ? "silent" : "warn",
@@ -49,6 +52,10 @@ export function reportOverflow(child, childHeight, maxHeight, ctx) {
 export function childrenForceBreak(children) {
     return children.some((child, i) => child.hasForcedBreak() || (i > 0 && child.breaksBefore()) || child.breaksAfter());
 }
+/** The packer kept every child as it was - none came back as a piece of itself (a sized Flow). */
+export function packedUnchanged(children, fitted) {
+    return fitted.length === children.length && fitted.every((child, i) => child === children[i]);
+}
 /**
  * Packs a vertical stack of children into `maxHeight`, in order. Children are measured
  * against `width` (unbounded height) and added until one would overflow; that straddling
@@ -80,6 +87,13 @@ export function packChildren(children, maxHeight, width, ctx, gap = 0) {
         // page, regardless of how much room is left.
         if (child.isPageBreak())
             return spill(i + 1, true);
+        // A column break cuts a Flow's Region; anywhere else it stays in place, draws nothing, and warns.
+        if (child.isColumnBreak()) {
+            if (ctx.inFlowRegion)
+                return spill(i + 1, "column");
+            fitted.push(child);
+            continue;
+        }
         // break-before: this child wants a fresh page. Honour it only if something is already on this region
         // (CSS ignores break-before at the top of a page); that guard also prevents an empty page + a loop.
         if (child.breaksBefore() && fitted.length > 0)
@@ -89,8 +103,10 @@ export function packChildren(children, maxHeight, width, ctx, gap = 0) {
         const lead = fitted.length > 0 ? gap : 0;
         // Place whole only if it fits AND holds no forced break: a child that fits by height but contains
         // a `PageBreak` (or a break-before/after) in its subtree must still be fragmented, or the break
-        // would be swallowed.
-        if (usedHeight + lead + childHeight <= maxHeight && !child.hasForcedBreak()) {
+        // would be swallowed. A region-sized child (a Flow) has no height of its own to fit by.
+        if (usedHeight + lead + childHeight <= maxHeight &&
+            !child.hasForcedBreak() &&
+            !child.needsRegion()) {
             fitted.push(child);
             usedHeight += lead + childHeight;
             // break-after: everything after this child starts a fresh page.
@@ -114,7 +130,11 @@ export function packChildren(children, maxHeight, width, ctx, gap = 0) {
                 // break-before at the top of the region, which CSS ignores. Keep packing the siblings after
                 // it instead of spilling them, so break-before does not accidentally push later content away.
                 if (!split.remainder && !childBroke) {
-                    usedHeight += lead + childHeight;
+                    // A region-sized child comes back as a different, sized piece: count what it holds.
+                    const placed = split.fitted === child
+                        ? childHeight
+                        : split.fitted.measure(BoxConstraints.loose(width, Infinity), ctx).height;
+                    usedHeight += lead + placed;
                     continue;
                 }
                 if (split.remainder)

package/dist/layout/layout-cache.d.ts

@@ -39,15 +39,15 @@ export declare class SizeCache {
     set(constraints: BoxConstraints, ctx: LayoutContext, onPage: boolean, size: Size): void;
 }
 /**
- * A subtree an element builds from the context at layout time (`Deferred`: a table whose `auto`
- * columns are measured from its cells and fitted to its width). It is built again only when the
- * context key or the width changes - the size rules and the one constraint building reads. Whether the
- * page belongs to the key is decided by what was built: a subtree without a `PageBuilder` is the same
- * on every page.
+ * What an element builds from the context at layout time: a subtree (`Deferred`: a table whose `auto`
+ * columns are measured from its cells and fitted to its width), or a Text's lines. It is built again
+ * only when the context key or the width changes - the size rules and the one constraint building
+ * reads. Whether the page belongs to the key is decided by what was built (`onPage`): a subtree
+ * without a `PageBuilder` is the same on every page.
  */
-export declare class BuiltFromContext<T extends {
-    dependsOnPage(): boolean;
-}> {
+export declare class BuiltFromContext<T> {
+    private readonly onPage;
     private last?;
+    constructor(onPage: (value: T) => boolean);
     get(ctx: LayoutContext, width: number, build: () => T): T;
 }

package/dist/layout/layout-cache.js

@@ -86,22 +86,25 @@ export class SizeCache {
     }
 }
 /**
- * A subtree an element builds from the context at layout time (`Deferred`: a table whose `auto`
- * columns are measured from its cells and fitted to its width). It is built again only when the
- * context key or the width changes - the size rules and the one constraint building reads. Whether the
- * page belongs to the key is decided by what was built: a subtree without a `PageBuilder` is the same
- * on every page.
+ * What an element builds from the context at layout time: a subtree (`Deferred`: a table whose `auto`
+ * columns are measured from its cells and fitted to its width), or a Text's lines. It is built again
+ * only when the context key or the width changes - the size rules and the one constraint building
+ * reads. Whether the page belongs to the key is decided by what was built (`onPage`): a subtree
+ * without a `PageBuilder` is the same on every page.
  */
 export class BuiltFromContext {
+    constructor(onPage) {
+        this.onPage = onPage;
+    }
     get(ctx, width, build) {
         const last = this.last;
         if (layoutCache.enabled &&
             last &&
             last.width === width &&
-            sameContext(last.key, contextKeyOf(ctx, last.value.dependsOnPage())))
+            sameContext(last.key, contextKeyOf(ctx, this.onPage(last.value))))
             return last.value;
         const value = build();
-        this.last = { key: contextKeyOf(ctx, value.dependsOnPage()), width, value };
+        this.last = { key: contextKeyOf(ctx, this.onPage(value)), width, value };
         return value;
     }
 }

package/dist/platform/browser-fs.d.ts

@@ -1,2 +1 @@
-export declare function readFileBytes(_path: string): Uint8Array;
-export declare function readFileBytesAsync(_path: string): Promise<Uint8Array>;
+export declare function readFileBytes(path: string): Uint8Array;

package/dist/platform/browser-fs.js

@@ -1,9 +1,6 @@
 // Browser stand-in for platform/node-fs.ts (selected by the package.json "browser" field). The browser has
 // no file paths, so loading from one throws a clear, actionable error - pass bytes instead.
-const hint = "needs Node. In the browser pass bytes (Uint8Array / ArrayBuffer) instead - e.g. import the file as a URL and fetch() it, or register a font from its bytes.";
-export function readFileBytes(_path) {
-    throw new Error(`Loading a font from a file path ${hint}`);
-}
-export function readFileBytesAsync(_path) {
-    throw new Error(`Loading an image from a file path ${hint}`);
+export function readFileBytes(path) {
+    throw new Error(`Loading "${path}" from a file path needs Node. In the browser pass the bytes (a Uint8Array) ` +
+        "instead - e.g. import the file as a URL and fetch() it.");
 }

package/dist/platform/node-fs.d.ts

@@ -1,2 +1 @@
 export declare function readFileBytes(path: string): Uint8Array;
-export declare function readFileBytesAsync(path: string): Promise<Uint8Array>;

package/dist/platform/node-fs.js

@@ -1,10 +1,6 @@
 // Node implementation of the platform file reads. In a browser bundle this whole module is swapped for
 // platform/browser-fs.ts via the package.json "browser" field, so `node:fs` never reaches the browser.
 import { readFileSync } from "node:fs";
-import { readFile } from "node:fs/promises";
 export function readFileBytes(path) {
     return readFileSync(path);
 }
-export function readFileBytesAsync(path) {
-    return readFile(path);
-}

package/dist/renderer/column-break-renderer.d.ts

@@ -0,0 +1,8 @@
+import type { RenderScope } from "../utils/renderer-registry.js";
+import { PDFObjectManager } from "../utils/pdf-object-manager.js";
+import { ColumnBreakElement } from "../elements/layout/column-break-element.js";
+import { IRNode } from "../ir/display-list.js";
+/** A `ColumnBreak` that reaches this pass was nowhere a Flow could break at it - it had no effect. */
+export declare class ColumnBreakRenderer {
+    static render(element: ColumnBreakElement, objectManager: PDFObjectManager, _scope: RenderScope): Promise<IRNode[]>;
+}

package/dist/renderer/column-break-renderer.js

@@ -0,0 +1,15 @@
+/** A `ColumnBreak` that reaches this pass was nowhere a Flow could break at it - it had no effect. */
+export class ColumnBreakRenderer {
+    static async render(element, objectManager, _scope) {
+        objectManager.diagnostics.report({
+            code: "column-break-ignored",
+            severity: "warning",
+            message: "ColumnBreak had no effect: it breaks only where a Flow's content runs down a Region - not " +
+                "outside a Flow, and not in a Row or a table row, which never break. To start a new page, " +
+                "use PageBreak.",
+            about: element,
+            page: element.page,
+        });
+        return [];
+    }
+}

package/dist/renderer/emoji-image.js

@@ -1,5 +1,5 @@
 import { CustomBytesImage } from "../elements/image-element.js";
-import { decodePngToRgbFlate } from "../utils/image-helper.js";
+import { decodePngToRgbFlate, jpegColor } from "../utils/image-helper.js";
 import { bytesFromLatin1 } from "../utils/bytes.js";
 // Per-URL fetch cache (process-wide): an emoji image is fetched once, however many times it appears.
 const cache = new Map();
@@ -48,6 +48,7 @@ export async function emojiImageNode(codePoint, source, x, baselineY, em) {
     // JPEG embeds raw; PNG is decoded to DeviceRGB + an /SMask alpha channel (transparency).
     let data = fileData;
     let smask;
+    const color = imageType === "DCTDecode" ? jpegColor(bytesFromLatin1(fileData)) : undefined;
     if (imageType === "FlateDecode") {
         const decoded = await decodePngToRgbFlate(bytesFromLatin1(fileData));
         data = decoded.data;
@@ -63,6 +64,7 @@ export async function emojiImageNode(codePoint, source, x, baselineY, em) {
         intrinsicHeight: dims.height,
         data,
         imageType,
+        ...(color ? { color } : {}),
         ...(smask ? { smask } : {}),
     };
 }

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

@@ -0,0 +1,16 @@
+import { FlowElement, FlowPieceElement } from "../elements/layout/flow-element.js";
+import { RegionElement } from "../elements/layout/region-element.js";
+import { PDFObjectManager } from "../utils/pdf-object-manager.js";
+import { IRNode } from "../ir/display-list.js";
+import { type RenderScope } from "../utils/renderer-registry.js";
+/** A Flow draws the page it made (laid out in place, in a box with a height). */
+export declare class FlowRenderer {
+    static render(flow: FlowElement, objectManager: PDFObjectManager, scope: RenderScope): Promise<IRNode[]>;
+}
+/** One page of a Flow: its template, whose Regions draw what they hold. */
+export declare class FlowPieceRenderer {
+    static render(piece: FlowPieceElement, objectManager: PDFObjectManager, scope: RenderScope): Promise<IRNode[]>;
+}
+export declare class RegionRenderer {
+    static render(region: RegionElement, objectManager: PDFObjectManager, scope: RenderScope): Promise<IRNode[]>;
+}

package/dist/renderer/flow-renderer.js

@@ -0,0 +1,21 @@
+import { RendererRegistry, within } from "../utils/renderer-registry.js";
+/** A Flow draws the page it made (laid out in place, in a box with a height). */
+export class FlowRenderer {
+    static async render(flow, objectManager, scope) {
+        const { x, y, piece } = flow.getProps();
+        return piece ? RendererRegistry.render(piece, objectManager, within(scope, { x, y })) : [];
+    }
+}
+/** One page of a Flow: its template, whose Regions draw what they hold. */
+export class FlowPieceRenderer {
+    static async render(piece, objectManager, scope) {
+        const { x, y, child } = piece.getProps();
+        return RendererRegistry.render(child, objectManager, within(scope, { x, y }));
+    }
+}
+export class RegionRenderer {
+    static async render(region, objectManager, scope) {
+        const { x, y, child } = region.getProps();
+        return child ? RendererRegistry.render(child, objectManager, within(scope, { x, y })) : [];
+    }
+}

package/dist/renderer/image-renderer.js

@@ -1,18 +1,20 @@
 import { BoxFit } from "../elements/image-element.js";
 import { bytesFromLatin1 } from "../utils/bytes.js";
-import { applyContainFit, applyCoverFit, applyFillFit, applyFitNone, decodePngToRgbFlate, } from "../utils/image-helper.js";
+import { applyContainFit, applyCoverFit, applyFillFit, applyFitNone, decodePngToRgbFlate, jpegColor, naturalSize, } from "../utils/image-helper.js";
 import { isRounded } from "../ir/display-list.js";
 export class ImageRenderer {
     static async render(imageElement, objectManager, scope) {
         // Load the image and convert it in a binary string
-        let { x: ownX, y: ownY, width, height, image, fit, radius, alt } = imageElement.getProps();
+        const { x: ownX, y: ownY, width, height, image, fit, radius, align, alt, } = imageElement.getProps();
         // Its own position is relative to `scope.origin`; the IR wants page coordinates.
-        let x = scope.origin.x + (ownX ?? 0);
-        let y = scope.origin.y + (ownY ?? 0);
+        const x = scope.origin.x + (ownX ?? 0);
+        const y = scope.origin.y + (ownY ?? 0);
         await image.init(); // Load and initialize the image
         const imageType = await image.getImageType(); // For the moment we can handle `png` and `jpg/jpeg` files
         const fileData = await image.getFileData();
         const dimensions = await image.getImageDimensions();
+        // Laid out at its own size in points; the pixels only describe the XObject.
+        const own = naturalSize(dimensions);
         if (!fileData) {
             throw new Error("File data cannot be `null`");
         }
@@ -20,71 +22,46 @@ export class ImageRenderer {
         // so decode it to raw DeviceRGB samples that the FlateDecode XObject path expects.
         let embedData = fileData;
         let smask;
+        // A JPEG is embedded as it is, so it keeps the color space it was saved in; a PNG becomes RGB.
+        const color = imageType === "DCTDecode" ? jpegColor(bytesFromLatin1(fileData)) : undefined;
         if (imageType === "FlateDecode") {
             const decoded = await decodePngToRgbFlate(bytesFromLatin1(fileData));
             embedData = decoded.data;
             smask = decoded.smask;
         }
-        // Now we check the `fit` property and changing the dimensions of the image
-        // Optionally we must add an overflow container
-        let mustCreateOverflowContainer = false;
-        const containerDimensions = JSON.parse(JSON.stringify({ x, y, width, height })); // Deep clone images dimensions
-        switch (fit) {
-            case BoxFit.cover:
-                mustCreateOverflowContainer = true;
-                const fitCoverResult = applyCoverFit(dimensions.width, dimensions.height, width ?? 0, height ?? 0);
-                x += fitCoverResult.offsetX;
-                y += fitCoverResult.offsetY;
-                width = fitCoverResult.width;
-                height = fitCoverResult.height;
-                break;
-            case BoxFit.contain:
-                mustCreateOverflowContainer = true;
-                const fitContainResult = applyContainFit(dimensions.width, dimensions.height, width ?? 0, height ?? 0);
-                x += fitContainResult.offsetX;
-                y += fitContainResult.offsetY;
-                width = fitContainResult.width;
-                height = fitContainResult.height;
-                break;
-            case BoxFit.none:
-                const fitNoneResult = applyFitNone(dimensions.width, dimensions.height, width ?? 0, height ?? 0);
-                x += fitNoneResult.offsetX;
-                y += fitNoneResult.offsetY;
-                width = fitNoneResult.width;
-                height = fitNoneResult.height;
-                break;
-            case BoxFit.fill:
-                const fitFillResult = applyFillFit(width ?? 0, height ?? 0);
-                width = fitFillResult.width;
-                height = fitFillResult.height;
-        }
-        // A radius rounds the image BOX (the element frame), so it clips to that frame too -
-        // independent of the cover/contain overflow clip.
-        const wantsClip = mustCreateOverflowContainer || isRounded(radius);
+        // The box laid out for it; `fit` decides what is drawn in it and where.
+        const box = {
+            x,
+            y,
+            width: width ?? own.width,
+            height: height ?? own.height,
+        };
+        const fitted = fit === BoxFit.cover
+            ? applyCoverFit(own.width, own.height, box.width, box.height, align)
+            : fit === BoxFit.contain
+                ? applyContainFit(own.width, own.height, box.width, box.height, align)
+                : fit === BoxFit.none
+                    ? applyFitNone(own.width, own.height, box.width, box.height, align)
+                    : applyFillFit(box.width, box.height);
+        // Anything but `fill` may leave the box, so it is clipped to it; a radius rounds the box too.
+        const wantsClip = fit !== BoxFit.fill || isRounded(radius);
         // The fitted geometry becomes a display-list primitive; the backend registers
         // the XObject and emits the placement (+ clip, rounded when a radius is set).
         const node = {
             type: "image",
-            x,
-            y,
-            width: width,
-            height: height,
+            x: x + fitted.offsetX,
+            y: y + fitted.offsetY,
+            width: fitted.width,
+            height: fitted.height,
             intrinsicWidth: dimensions.width,
             intrinsicHeight: dimensions.height,
             data: embedData,
             imageType,
+            ...(color ? { color } : {}),
+            ...(dimensions.orientation ? { orientation: dimensions.orientation } : {}),
             ...(smask ? { smask } : {}),
             ...(radius ? { radius } : {}),
-            ...(wantsClip
-                ? {
-                    clip: {
-                        x: containerDimensions.x,
-                        y: containerDimensions.y,
-                        width: containerDimensions.width,
-                        height: containerDimensions.height,
-                    },
-                }
-                : {}),
+            ...(wantsClip ? { clip: box } : {}),
         };
         // Accessible tagging: an image WITH alt text is a Figure; without, it stays untagged and the backend
         // treats it as decoration (an Artifact). One struct element per image.

package/dist/renderer/index.d.ts

@@ -10,3 +10,5 @@ export * from "./line-renderer.js";
 export * from "./row-renderer.js";
 export * from "./svg-renderer.js";
 export * from "./canvas-renderer.js";
+export * from "./flow-renderer.js";
+export * from "./column-break-renderer.js";

package/dist/renderer/index.js

@@ -10,3 +10,5 @@ export * from "./line-renderer.js";
 export * from "./row-renderer.js";
 export * from "./svg-renderer.js";
 export * from "./canvas-renderer.js";
+export * from "./flow-renderer.js";
+export * from "./column-break-renderer.js";

package/dist/renderer/page-renderer.js

@@ -3,6 +3,7 @@ import { resolvePageContentBox } from "../elements/page-element.js";
 import { RendererRegistry } from "../utils/renderer-registry.js";
 import { Orientation } from "./pdf-config.js";
 import { PdfBackend } from "./pdf-backend.js";
+import { PositionedRenderer } from "./positioned-renderer.js";
 export class PageRenderer {
     static async render(page, objectManager) {
         const { children, config, header, footer } = page.getProps();
@@ -26,10 +27,8 @@ export class PageRenderer {
         // Collect the whole page as a display list (top-left coordinates), flip it to PDF
         // coordinates at this one seam, then serialize once. Serializing registers the
         // fonts/images used below, so it must run before the resource section.
-        const nodes = [];
-        for (const element of renderables) {
-            nodes.push(...(await RendererRegistry.render(element, objectManager, scope)));
-        }
+        // The page is the outermost stacking context: header, body and footer share one paint order.
+        const nodes = await PositionedRenderer.paintStacked(renderables, objectManager, scope);
         // 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;

package/dist/renderer/pdf-backend.js

@@ -1,5 +1,6 @@
 import { isRounded, } from "../ir/display-list.js";
 import { Color } from "../common/color.js";
+import { ORIENTATION_MATRIX } from "../utils/image-helper.js";
 /**
  * PDF backend - turns display-list primitives into content-stream operators.
  *
@@ -416,8 +417,14 @@ export class PdfBackend {
             case "image": {
                 // The backend owns PDF resource creation: register the XObject (using the
                 // source pixel dimensions) and then place it with a scaling matrix.
-                const ref = om.registerImage(node.intrinsicWidth, node.intrinsicHeight, node.imageType, node.data, node.smask);
-                const draw = `q\n${node.width} 0 0 ${node.height} ${node.x} ${node.y} cm\n` + `/IM${ref} Do\nQ\n`;
+                const ref = om.registerImage(node.intrinsicWidth, node.intrinsicHeight, node.imageType, node.data, node.smask, node.color);
+                // The placement scales the unit square to the box; an orientation turns the pixels inside it.
+                const upright = node.orientation
+                    ? `${ORIENTATION_MATRIX[node.orientation].join(" ")} cm\n`
+                    : "";
+                const draw = `q\n${node.width} 0 0 ${node.height} ${node.x} ${node.y} cm\n` +
+                    upright +
+                    `/IM${ref} Do\nQ\n`;
                 if (!node.clip)
                     return draw;
                 // Clip to the frame (re … W n); rounded when a radius is set. The rectangular

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

@@ -102,7 +102,8 @@ export class PDFDocumentRenderer {
             // restores their real positions (layout is deterministic). A consumed trailing `PageBreak`
             // (forceBreak with no remainder) is the exception: render the packed `fitted` instead, which no
             // longer holds the break marker, so the original with the break does not leak into the render pass.
-            if (isFirstRegion && remainder === null && !forceBreak) {
+            // So is a region that came back as a sized piece (a Flow): it is drawn as it was paginated.
+            if (isFirstRegion && remainder === null && !forceBreak && fitted === region) {
                 pages.push({ kind: "whole", page });
                 break;
             }

package/dist/renderer/pdf-renderer.js

@@ -43,6 +43,11 @@ import { SignatureFieldElement } from "../elements/forms/signature-element.js";
 import { FormFieldRenderer } from "./form-field-renderer.js";
 import { PageBuilderElement } from "../elements/layout/page-builder-element.js";
 import { PageBuilderRenderer } from "./page-builder-renderer.js";
+import { FlowElement, FlowPieceElement } from "../elements/layout/flow-element.js";
+import { RegionElement } from "../elements/layout/region-element.js";
+import { FlowPieceRenderer, FlowRenderer, RegionRenderer } from "./flow-renderer.js";
+import { ColumnBreakElement } from "../elements/layout/column-break-element.js";
+import { ColumnBreakRenderer } from "./column-break-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";
@@ -78,6 +83,10 @@ export class PDFRenderer {
         RendererRegistry.register(BookmarkElement, BookmarkRenderer.render);
         RendererRegistry.register(AnchorElement, AnchorRenderer.render);
         RendererRegistry.register(PageBuilderElement, PageBuilderRenderer.render);
+        RendererRegistry.register(FlowElement, FlowRenderer.render);
+        RendererRegistry.register(FlowPieceElement, FlowPieceRenderer.render);
+        RendererRegistry.register(RegionElement, RegionRenderer.render);
+        RendererRegistry.register(ColumnBreakElement, ColumnBreakRenderer.render);
         RendererRegistry.register(RotatedElement, RotatedRenderer.render);
         RendererRegistry.register(RotatedBoxElement, RotatedRenderer.render);
         let pdfContent = "";

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

@@ -1,11 +1,23 @@
 import { PDFObjectManager } from "../utils/pdf-object-manager.js";
 import { PositionedElement } from "../elements/layout/positioned-element.js";
+import type { PDFElement } from "../elements/pdf-element.js";
 import { type RenderScope } from "../utils/renderer-registry.js";
 import { IRNode } from "../ir/display-list.js";
 export declare class PositionedRenderer {
     /**
-     * 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.
+     * Rendered at its own place in the tree, from its frame: the child was laid out relative to the
+     * frame's top-left, not to the flow it sits in. Without a `zIndex` that place is also where it paints.
+     * With one it hands its drawing to the nearest stacking context (`paintStacked`), which sorts it - so
+     * tagging and everything else registered while rendering still sees the tree it stands in.
      */
     static render(positionedElement: PositionedElement, objectManager: PDFObjectManager, scope: RenderScope): Promise<IRNode[]>;
+    /**
+     * Paints the children of a stacking context (a frame, a clipping Box, a rotation, the page): the
+     * `Positioned` below it with a negative `zIndex` first, then the children in tree order, then the
+     * positive ones - lowest first, ties in tree order. Without a `zIndex` below it, this is the children
+     * in order.
+     */
+    static paintStacked(children: readonly PDFElement[], objectManager: PDFObjectManager, scope: RenderScope): Promise<IRNode[]>;
+    /** Children in tree order - what any element that is not a stacking context draws. */
+    static paintInOrder(children: readonly PDFElement[], objectManager: PDFObjectManager, scope: RenderScope): Promise<IRNode[]>;
 }

package/dist/renderer/positioned-renderer.js

@@ -1,11 +1,47 @@
 import { RendererRegistry } from "../utils/renderer-registry.js";
 export class PositionedRenderer {
     /**
-     * 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.
+     * Rendered at its own place in the tree, from its frame: the child was laid out relative to the
+     * frame's top-left, not to the flow it sits in. Without a `zIndex` that place is also where it paints.
+     * With one it hands its drawing to the nearest stacking context (`paintStacked`), which sorts it - so
+     * tagging and everything else registered while rendering still sees the tree it stands in.
      */
     static async render(positionedElement, objectManager, scope) {
-        const { child } = positionedElement.getProps();
-        return RendererRegistry.render(child, objectManager, { ...scope, origin: scope.frame });
+        const { child, zIndex } = positionedElement.getProps();
+        const render = () => RendererRegistry.render(child, objectManager, { ...scope, origin: scope.frame });
+        if (zIndex === 0 || !scope.stacked)
+            return render();
+        // Its place in the stack is taken BEFORE its child renders: a nested Positioned with the same
+        // zIndex hands its drawing in during that, and must come after its outer one, in tree order.
+        const entry = { zIndex, nodes: [] };
+        scope.stacked.push(entry);
+        entry.nodes = await render();
+        return [];
+    }
+    /**
+     * Paints the children of a stacking context (a frame, a clipping Box, a rotation, the page): the
+     * `Positioned` below it with a negative `zIndex` first, then the children in tree order, then the
+     * positive ones - lowest first, ties in tree order. Without a `zIndex` below it, this is the children
+     * in order.
+     */
+    static async paintStacked(children, objectManager, scope) {
+        const stacked = [];
+        const flow = await PositionedRenderer.paintInOrder(children, objectManager, {
+            ...scope,
+            stacked,
+        });
+        stacked.sort((a, b) => a.zIndex - b.zIndex); // stable: ties keep tree order
+        return [
+            ...stacked.filter((s) => s.zIndex < 0).flatMap((s) => s.nodes),
+            ...flow,
+            ...stacked.filter((s) => s.zIndex > 0).flatMap((s) => s.nodes),
+        ];
+    }
+    /** Children in tree order - what any element that is not a stacking context draws. */
+    static async paintInOrder(children, objectManager, scope) {
+        const nodes = [];
+        for (const child of children)
+            nodes.push(...(await RendererRegistry.render(child, objectManager, scope)));
+        return nodes;
     }
 }

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

@@ -1,6 +1,6 @@
 import { PDFObjectManager } from "../utils/pdf-object-manager.js";
 import { RectangleElement } from "../elements/rectangle-element.js";
-import { type RenderScope } from "../utils/renderer-registry.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, scope: RenderScope): Promise<IRNode[]>;

package/dist/renderer/rectangle-renderer.js

@@ -1,5 +1,5 @@
-import { RendererRegistry } from "../utils/renderer-registry.js";
-import { isGradientInput, resolveGradient } from "../api/gradient.js";
+import { PositionedRenderer } from "./positioned-renderer.js";
+import { isGradientInput, resolveGradient } from "../common/gradient.js";
 export class RectangleRenderer {
     static async render(rectangleElement, objectManager, scope) {
         const { x: ownX, y: ownY, width, height, children, color, backgroundColor, borderWidth, radius, sideBorders, overflow, relative, } = rectangleElement.getProps();
@@ -46,11 +46,16 @@ export class RectangleRenderer {
         }
         // 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 };
+        const childScope = {
+            ...scope,
+            origin: { x, y },
+            frame: relative ? { x, y } : scope.frame,
+        };
+        // A frame or a clip paints its own `zIndex` order; any other box draws its children as they come.
         if (children)
-            for (const child of children) {
-                nodes.push(...(await RendererRegistry.render(child, objectManager, childScope)));
-            }
+            nodes.push(...(rectangleElement.isStackingContext()
+                ? await PositionedRenderer.paintStacked(children, objectManager, childScope)
+                : await PositionedRenderer.paintInOrder(children, objectManager, childScope)));
         if (clip)
             nodes.push({ type: "clip-pop" });
         return nodes;

package/dist/renderer/rotated-renderer.js

@@ -1,4 +1,5 @@
-import { RendererRegistry, within } from "../utils/renderer-registry.js";
+import { within } from "../utils/renderer-registry.js";
+import { PositionedRenderer } from "./positioned-renderer.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.
@@ -25,7 +26,7 @@ export class RotatedRenderer {
             cy - sin * cx - cos * cy,
         ];
         // The child is placed relative to the box top-left.
-        const childNodes = await RendererRegistry.render(child, objectManager, within(scope, { x: ownX, y: ownY }));
+        const childNodes = await PositionedRenderer.paintStacked([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" }];
     }