@jasy/pdf 1.0.0-beta.3 → 1.0.0-beta.5

package/dist/layout/fragmentation.d.ts

@@ -9,13 +9,15 @@ import { LayoutContext, PDFElement } from "../elements/pdf-element.js";
  * rest, so no information flows back UP after a break. This one-way flow is what keeps
  * fragmentation terminating (no overflow-cascade fixpoint).
  */
+export type ForcedBreak = boolean | "column";
 export interface FragmentResult {
     fitted: PDFElement | null;
     remainder: PDFElement | null;
-    /** The split ended at a FORCED page break (a `PageBreak`), not because the region filled up. The
-     *  remainder must start a fresh page, and an enclosing flow must stop packing too - so this bubbles
-     *  up through nested `fragment()` calls. Absent/false for an ordinary height-driven break. */
-    forceBreak?: boolean;
+    /** The split ended at a FORCED break, not because the region filled up: `true` for a page break (the
+     *  remainder starts a fresh page), `"column"` for a `ColumnBreak` in a Flow's Region (it starts the
+     *  next Region; the Flow consumes it). An enclosing flow stops packing too - so this bubbles up
+     *  through nested `fragment()` calls. Absent/false for an ordinary height-driven break. */
+    forceBreak?: ForcedBreak;
 }
 /**
  * An element that knows how to split itself across regions. Width is already finalized
@@ -33,13 +35,25 @@ export declare function isFragmentable(element: PDFElement): element is PDFEleme
  * logs and clips, `"ignore"` clips silently.
  */
 export type OverflowPolicy = "error" | "warn" | "ignore";
-export declare function reportOverflow(child: PDFElement, childHeight: number, maxHeight: number, policy: OverflowPolicy): void;
 /**
- * True if packing `children` will hit a forced cut: a child that IS a break, contains one deeper in its
- * subtree, or asks to break before/after itself. A flow container reports this from `hasForcedBreak` so
- * its parent fragments it (runs `packChildren`) instead of placing it whole and swallowing the cut.
+ * The context for content inset by `chrome` on every page (a border, padding, a repeated header): a
+ * fresh page gives it that much less room. Every element that shrinks the region for its children
+ * hands this down with it.
+ */
+export declare function insetContext(ctx: LayoutContext, chrome: number): LayoutContext;
+export declare function reportOverflow(child: PDFElement, childHeight: number, maxHeight: number, ctx: LayoutContext): void;
+/** Content cut off at the bottom, under the author's `onOverflow` policy. */
+export declare function reportClipped(about: PDFElement, detail: string, ctx: LayoutContext): void;
+/**
+ * True if packing `children` will hit a forced cut INSIDE them: a child that IS a break, contains one
+ * deeper in its subtree, or asks to break before/after itself. A flow container reports this from
+ * `hasForcedBreak` so its parent fragments it (runs `packChildren`) instead of placing it whole and
+ * swallowing the cut. A break before the FIRST child is not inside: the stack takes it as its own
+ * (`breaksBefore`), so it moves whole - which is what a `keepTogether` around it relies on.
  */
 export declare function childrenForceBreak(children: PDFElement[]): boolean;
+/** The packer kept every child as it was - none came back as a piece of itself (a sized Flow). */
+export declare function packedUnchanged(children: PDFElement[], fitted: PDFElement[]): boolean;
 /**
  * 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
@@ -57,5 +71,5 @@ export declare function childrenForceBreak(children: PDFElement[]): boolean;
 export declare function packChildren(children: PDFElement[], maxHeight: number, width: number, ctx: LayoutContext, gap?: number): {
     fitted: PDFElement[];
     remainder: PDFElement[];
-    forceBreak: boolean;
+    forceBreak: ForcedBreak;
 };

package/dist/layout/fragmentation.js

@@ -1,4 +1,5 @@
 import { BoxConstraints } from "./box-constraints.js";
+import { diagnose, pageOf } from "../common/diagnostics.js";
 export function isFragmentable(element) {
     if (!("fragment" in element) ||
         typeof element.fragment !== "function") {
@@ -10,24 +11,50 @@ export function isFragmentable(element) {
     const canFragment = element.canFragment;
     return typeof canFragment !== "function" || canFragment.call(element);
 }
-export function reportOverflow(child, childHeight, maxHeight, policy) {
-    if (policy === "ignore")
-        return;
+/**
+ * The context for content inset by `chrome` on every page (a border, padding, a repeated header): a
+ * fresh page gives it that much less room. Every element that shrinks the region for its children
+ * hands this down with it.
+ */
+export function insetContext(ctx, chrome) {
+    if (ctx.pageBodyHeight === undefined || chrome === 0)
+        return ctx;
+    return { ...ctx, pageBodyHeight: ctx.pageBodyHeight - chrome };
+}
+export function reportOverflow(child, childHeight, maxHeight, ctx) {
     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}`);
-    console.warn(`Layout overflow (clipped): ${detail}`);
+    diagnose(ctx.diagnostics, {
+        code: "overflow-clipped",
+        severity: "warning",
+        message: `Layout overflow (clipped): ${detail}`,
+        about,
+        page: pageOf(ctx),
+        // `ignore` means "no console" - an `onDiagnostic` handler still hears of it.
+        fallback: policy === "ignore" ? "silent" : "warn",
+    });
 }
 /**
- * True if packing `children` will hit a forced cut: a child that IS a break, contains one deeper in its
- * subtree, or asks to break before/after itself. A flow container reports this from `hasForcedBreak` so
- * its parent fragments it (runs `packChildren`) instead of placing it whole and swallowing the cut.
+ * True if packing `children` will hit a forced cut INSIDE them: a child that IS a break, contains one
+ * deeper in its subtree, or asks to break before/after itself. A flow container reports this from
+ * `hasForcedBreak` so its parent fragments it (runs `packChildren`) instead of placing it whole and
+ * swallowing the cut. A break before the FIRST child is not inside: the stack takes it as its own
+ * (`breaksBefore`), so it moves whole - which is what a `keepTogether` around it relies on.
  */
 export function childrenForceBreak(children) {
-    return children.some((child) => child.hasForcedBreak() || child.breaksBefore() || child.breaksAfter());
+    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
@@ -60,17 +87,26 @@ 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)
             return spill(i, true);
-        const childHeight = child.calculateLayout(BoxConstraints.loose(width, Infinity), { x: 0, y: 0 }, ctx).height;
+        const childHeight = child.measure(BoxConstraints.loose(width, Infinity), ctx).height;
         // A gap precedes every child except the first one placed in this region.
         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.
@@ -82,8 +118,10 @@ export function packChildren(children, maxHeight, width, ctx, gap = 0) {
         const remaining = maxHeight - usedHeight - lead;
         let placedPart = false;
         let childBroke = false;
+        const below = ctx.belowContent || fitted.length > 0;
         if (isFragmentable(child)) {
-            const split = child.fragment(Math.max(0, remaining), width, ctx);
+            const childCtx = below && !ctx.belowContent ? { ...ctx, belowContent: true } : ctx;
+            const split = child.fragment(Math.max(0, remaining), width, childCtx);
             childBroke = split.forceBreak ?? false;
             if (split.fitted) {
                 fitted.push(split.fitted);
@@ -92,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)
@@ -101,10 +143,11 @@ export function packChildren(children, maxHeight, width, ctx, gap = 0) {
             }
         }
         if (!placedPart) {
-            if (fitted.length === 0 && !childBroke) {
-                // Taller than the whole region and unsplittable: force it on (it overflows and is clipped)
-                // so the next region still advances - and surface it per the overflow policy.
-                reportOverflow(child, childHeight, maxHeight, ctx.onOverflow ?? "ignore");
+            if (!below && !childBroke) {
+                // Taller than a whole fresh page and unsplittable: force it on (it overflows and is clipped)
+                // so the next region still advances - and surface it per the overflow policy. Below other
+                // content it simply waits for the next page.
+                reportOverflow(child, childHeight, maxHeight, ctx);
                 fitted.push(child);
             }
             else {

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

@@ -0,0 +1,53 @@
+import type { BoxConstraints, Size } from "./box-constraints.js";
+import type { LayoutContext } from "../elements/pdf-element.js";
+/**
+ * The layout cache - the one place a size is remembered. `PDFElement.measure` asks it before
+ * `computeSize` runs, and stores what `computeSize` returned.
+ *
+ * An element never changes after it is built, so its size is a pure function of its INPUTS: the
+ * constraints, plus the context fields listed in `Key` below. The same inputs again are answered from
+ * the element's own cache. That is what Flutter's dry-layout cache and Yoga's measure cache do; flex
+ * asks the same child the same question several times while it distributes space.
+ *
+ * What keeps it correct:
+ * - `computeSize` reads only the context fields in `Key`. A new field that can change a size is added
+ *   HERE. `frame`, `belowContent`, `pageBodyHeight` and `onOverflow` steer placement and page breaks,
+ *   never a size, so they are not part of it.
+ * - The page (`pageConfig`, `pageInfo`) is part of the key only for an element that
+ *   `dependsOnPage()`. Every page and both passes bring new page objects, so keying everything on them
+ *   would make the cache miss on each page.
+ * - Context values compare by IDENTITY. Code that derives one (a merged text style) returns the same
+ *   object for the same input, or every element below it misses.
+ * - `fontEpoch` moves when a font face is added, and kerning can be switched on the same metrics; both
+ *   change widths.
+ *
+ * The same key, without the constraints, decides when a subtree built at layout time can be reused
+ * (`BuiltFromContext`, below).
+ *
+ * Below this level sit value memos that are not size caches: glyph advances per font
+ * (`text/advance.ts`) and a Text's displayed content (`TextElement.display`).
+ */
+export declare const layoutCache: {
+    /** Off only in the test that renders every pinned document both ways and demands the same bytes. */
+    enabled: boolean;
+};
+/** One element's remembered sizes, oldest overwritten first. */
+export declare class SizeCache {
+    private entries;
+    private next;
+    get(constraints: BoxConstraints, ctx: LayoutContext, onPage: boolean): Size | undefined;
+    set(constraints: BoxConstraints, ctx: LayoutContext, onPage: boolean, size: Size): void;
+}
+/**
+ * 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> {
+    private readonly onPage;
+    private last?;
+    constructor(onPage: (value: T) => boolean);
+    get(ctx: LayoutContext, width: number, build: () => T): T;
+}

package/dist/layout/layout-cache.js

@@ -0,0 +1,110 @@
+/**
+ * The layout cache - the one place a size is remembered. `PDFElement.measure` asks it before
+ * `computeSize` runs, and stores what `computeSize` returned.
+ *
+ * An element never changes after it is built, so its size is a pure function of its INPUTS: the
+ * constraints, plus the context fields listed in `Key` below. The same inputs again are answered from
+ * the element's own cache. That is what Flutter's dry-layout cache and Yoga's measure cache do; flex
+ * asks the same child the same question several times while it distributes space.
+ *
+ * What keeps it correct:
+ * - `computeSize` reads only the context fields in `Key`. A new field that can change a size is added
+ *   HERE. `frame`, `belowContent`, `pageBodyHeight` and `onOverflow` steer placement and page breaks,
+ *   never a size, so they are not part of it.
+ * - The page (`pageConfig`, `pageInfo`) is part of the key only for an element that
+ *   `dependsOnPage()`. Every page and both passes bring new page objects, so keying everything on them
+ *   would make the cache miss on each page.
+ * - Context values compare by IDENTITY. Code that derives one (a merged text style) returns the same
+ *   object for the same input, or every element below it misses.
+ * - `fontEpoch` moves when a font face is added, and kerning can be switched on the same metrics; both
+ *   change widths.
+ *
+ * The same key, without the constraints, decides when a subtree built at layout time can be reused
+ * (`BuiltFromContext`, below).
+ *
+ * Below this level sit value memos that are not size caches: glyph advances per font
+ * (`text/advance.ts`) and a Text's displayed content (`TextElement.display`).
+ */
+export const layoutCache = {
+    /** Off only in the test that renders every pinned document both ways and demands the same bytes. */
+    enabled: true,
+};
+const contextKeyOf = (ctx, onPage) => ({
+    metrics: ctx.metrics,
+    fontEpoch: ctx.metrics?.fontEpoch ?? 0,
+    kerning: ctx.metrics?.kerningEnabled,
+    textStyle: ctx.textStyle,
+    pageConfig: onPage ? ctx.pageConfig : undefined,
+    pageInfo: onPage ? ctx.pageInfo : undefined,
+    boxPaddingBase: ctx.boxPaddingBase,
+});
+const sameContext = (a, b) => a.metrics === b.metrics &&
+    a.fontEpoch === b.fontEpoch &&
+    a.kerning === b.kerning &&
+    a.textStyle === b.textStyle &&
+    a.pageConfig === b.pageConfig &&
+    a.pageInfo === b.pageInfo &&
+    a.boxPaddingBase === b.boxPaddingBase;
+const keyOf = (c, ctx, onPage) => ({
+    minWidth: c.minWidth,
+    maxWidth: c.maxWidth,
+    minHeight: c.minHeight,
+    maxHeight: c.maxHeight,
+    context: contextKeyOf(ctx, onPage),
+});
+const sameKey = (a, b) => a.minWidth === b.minWidth &&
+    a.maxWidth === b.maxWidth &&
+    a.minHeight === b.minHeight &&
+    a.maxHeight === b.maxHeight &&
+    sameContext(a.context, b.context);
+/**
+ * How many different questions one element remembers. Flex asks a child at more than one width (its
+ * natural width, then its share), so one entry would evict itself.
+ */
+const ENTRIES = 4;
+/** One element's remembered sizes, oldest overwritten first. */
+export class SizeCache {
+    constructor() {
+        this.entries = [];
+        this.next = 0;
+    }
+    get(constraints, ctx, onPage) {
+        if (!layoutCache.enabled)
+            return undefined;
+        const key = keyOf(constraints, ctx, onPage);
+        const hit = this.entries.find((e) => sameKey(e.key, key));
+        // A copy: a caller that adjusts the size it was handed must not change the remembered one.
+        return hit && { ...hit.size };
+    }
+    set(constraints, ctx, onPage, size) {
+        const entry = { key: keyOf(constraints, ctx, onPage), size: { ...size } };
+        if (this.entries.length < ENTRIES)
+            this.entries.push(entry);
+        else
+            this.entries[this.next] = entry;
+        this.next = (this.next + 1) % ENTRIES;
+    }
+}
+/**
+ * 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, this.onPage(last.value))))
+            return last.value;
+        const value = build();
+        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/anchor-renderer.d.ts

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

package/dist/renderer/anchor-renderer.js

@@ -1,9 +1,10 @@
 import { RendererRegistry } from "../utils/renderer-registry.js";
 export class AnchorRenderer {
-    static async render(element, objectManager) {
-        const { name, child, y } = element.getProps();
-        const renderer = RendererRegistry.getRenderer(child);
-        const childNodes = await renderer(child, objectManager);
+    static async render(element, objectManager, scope) {
+        const { name, child, y: ownY } = element.getProps();
+        // Its own position is relative to `scope.origin`; the IR wants page coordinates.
+        const y = scope.origin.y + (ownY ?? 0);
+        const childNodes = await RendererRegistry.render(child, objectManager, scope);
         // The child draws normally; an Anchor IR node carries the name + scroll target for the page renderer
         // to register as a named destination (it produces no content-stream ops itself).
         return [...childNodes, { type: "anchor", y, name }];

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

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

package/dist/renderer/bookmark-renderer.js

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

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

@@ -1,3 +1,4 @@
+import type { RenderScope } from "../utils/renderer-registry.js";
 import { PDFObjectManager } from "../utils/pdf-object-manager.js";
 import { CanvasElement } from "../elements/canvas-element.js";
 import type { IRNode } from "../ir/display-list.js";
@@ -10,5 +11,5 @@ import type { IRNode } from "../ir/display-list.js";
  * past its own edge would otherwise bleed into the layout beside it.
  */
 export declare class CanvasRenderer {
-    static render(element: CanvasElement, objectManager: PDFObjectManager): Promise<IRNode[]>;
+    static render(element: CanvasElement, objectManager: PDFObjectManager, scope: RenderScope): Promise<IRNode[]>;
 }

package/dist/renderer/canvas-renderer.js

@@ -8,8 +8,11 @@ import { CanvasPainter } from "../canvas/painter.js";
  * past its own edge would otherwise bleed into the layout beside it.
  */
 export class CanvasRenderer {
-    static async render(element, objectManager) {
-        const { x, y, width, height, paint, alt } = element.getProps();
+    static async render(element, objectManager, scope) {
+        const { x: ownX, y: ownY, width, height, paint, alt } = 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);
         // The layout bounds are kept as plain numbers, and the painter and the callback each get their
         // OWN size object. Sharing one meant a callback that wrote to `size.width` moved the clip away
         // from the box layout had reserved - the drawing would then bleed into what sits beside it.

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/container-renderer.d.ts

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

package/dist/renderer/container-renderer.js

@@ -1,12 +1,13 @@
-import { RendererRegistry } from "../utils/renderer-registry.js";
+import { RendererRegistry, within } from "../utils/renderer-registry.js";
 export class ContainerRenderer {
-    static async render(containerElement, objectManager) {
-        const { children } = containerElement.getProps();
+    static async render(containerElement, objectManager, scope) {
+        const { x, y, children } = containerElement.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/default-text-style-renderer.d.ts

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

package/dist/renderer/default-text-style-renderer.js

@@ -2,9 +2,8 @@ import { RendererRegistry } from "../utils/renderer-registry.js";
 // Transparent wrapper: the text style was already resolved onto the descendants at layout time, so
 // the renderer just emits the child's display list (like PaddingRenderer).
 export class DefaultTextStyleRenderer {
-    static async render(element, objectManager) {
+    static async render(element, objectManager, scope) {
         const { child } = element.getProps();
-        const renderer = RendererRegistry.getRenderer(child);
-        return renderer(child, objectManager);
+        return RendererRegistry.render(child, objectManager, scope);
     }
 }

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

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

package/dist/renderer/deferred-renderer.js

@@ -1,10 +1,9 @@
 import { RendererRegistry } from "../utils/renderer-registry.js";
 export class DeferredRenderer {
-    static async render(element, objectManager) {
+    static async render(element, objectManager, scope) {
         const { composed } = element.getProps();
         if (!composed)
             return [];
-        const renderer = RendererRegistry.getRenderer(composed);
-        return renderer(composed, objectManager);
+        return RendererRegistry.render(composed, objectManager, scope);
     }
 }

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/expanded-renderer.d.ts

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

package/dist/renderer/expanded-renderer.js

@@ -1,8 +1,7 @@
 import { RendererRegistry } from "../utils/renderer-registry.js";
 export class ExpandedRenderer {
-    static async render(expandedElement, objectManager) {
+    static async render(expandedElement, objectManager, scope) {
         const { child } = expandedElement.getProps();
-        const renderer = RendererRegistry.getRenderer(child);
-        return renderer(child, objectManager);
+        return RendererRegistry.render(child, objectManager, scope);
     }
 }