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

package/dist/forms/appearance.d.ts

@@ -1,6 +1,17 @@
 import type { FieldAlign, FieldStyle } from "./field.js";
 import type { FontMetrics } from "../utils/font-metrics.js";
 import type { FontStyle } from "../utils/pdf-object-manager.js";
+/**
+ * The font an appearance draws its text in: its resource name inside the appearance stream's own
+ * /Resources, and how a string becomes a `Tj` operand in it. One object, so the caller that picks the
+ * font also decides its encoding - a WinAnsi literal for Helvetica, glyph ids for an embedded font.
+ */
+export interface FaceFont {
+    res: string;
+    encode(text: string): string;
+}
+/** The standard Helvetica (`/Helv`) a field's /DA names: WinAnsi literal strings. */
+export declare const HELV: FaceFont;
 /** The unchecked appearance: just the box. */
 export declare function checkboxOff(w: number, h: number, style: FieldStyle): string;
 /** The checked appearance: the box plus a vector checkmark (font-free, so it renders everywhere). */
@@ -12,16 +23,16 @@ export declare function radioOn(w: number, h: number, style: FieldStyle): string
 /**
  * A push button's face: the box plus its caption, centred. The caller measures the caption (this module
  * stays free of font metrics and the writer) and passes `captionWidth` in points and `capHeight` as an em
- * fraction; the baseline is placed so the CAPITALS sit optically centred, not the em box. `fontRes` is
- * the font's resource name inside the appearance stream's own /Resources.
+ * fraction; the baseline is placed so the CAPITALS sit optically centred, not the em box. `font` is
+ * what the caption is drawn in.
  */
-export declare function pushButtonFace(w: number, h: number, style: FieldStyle, caption: string, captionWidth: number, capHeight: number, fontRes: string, size: number): string;
+export declare function pushButtonFace(w: number, h: number, style: FieldStyle, caption: string, captionWidth: number, capHeight: number, font: FaceFont, size: number): string;
 /**
  * An EMPTY signature field: the box, a signing rule across the lower third, and an optional hint centred
  * just above it. This is the placeholder look - once someone actually signs, the signing tool replaces
  * this appearance with its own.
  */
-export declare function signatureFace(w: number, h: number, style: FieldStyle, label: string, labelWidth: number, fontRes: string, size: number): string;
+export declare function signatureFace(w: number, h: number, style: FieldStyle, label: string, labelWidth: number, font: FaceFont, size: number): string;
 /** One pre-measured line of field text. The caller owns wrapping + measuring, so this module stays free
  *  of font metrics (and can be reused verbatim when filling an existing PDF). */
 /**
@@ -50,9 +61,9 @@ export interface FieldLine {
  * single line sits optically centred; a multi-line field stacks from the top, both measured off the
  * font's cap height rather than a guessed ratio.
  */
-export declare function textFieldFace(w: number, h: number, style: FieldStyle, lines: FieldLine[], capHeight: number, size: number, fontRes: string, multiline: boolean, align?: FieldAlign): string;
+export declare function textFieldFace(w: number, h: number, style: FieldStyle, lines: FieldLine[], capHeight: number, size: number, font: FaceFont, multiline: boolean, align?: FieldAlign): string;
 /**
  * A list box, baked: the visible options stacked from the top, with a highlight behind the selected
  * ones. A combo box (dropdown) uses `textFieldFace` instead - it shows only its current value.
  */
-export declare function listBoxFace(w: number, h: number, style: FieldStyle, lines: FieldLine[], capHeight: number, size: number, fontRes: string, align?: FieldAlign): string;
+export declare function listBoxFace(w: number, h: number, style: FieldStyle, lines: FieldLine[], capHeight: number, size: number, font: FaceFont, align?: FieldAlign): string;

package/dist/forms/appearance.js

@@ -1,5 +1,7 @@
 import { escPdf, num2, pdfColor } from "./pdf.js";
 import { wrapStringIntoLines } from "../text/line-breaker.js";
+/** The standard Helvetica (`/Helv`) a field's /DA names: WinAnsi literal strings. */
+export const HELV = { res: "Helv", encode: (text) => `(${escPdf(text)})` };
 // Appearance streams (/AP): the actual drawn content of a field's box, in the field's OWN coordinate
 // space (bottom-left origin, [0 0 w h]). Shared between CREATE (bake the field's look now) and, later,
 // FILL-existing (regenerate a field's look after setting its value). This is why it is its own module.
@@ -63,34 +65,34 @@ export function radioOn(w, h, style) {
 /**
  * A push button's face: the box plus its caption, centred. The caller measures the caption (this module
  * stays free of font metrics and the writer) and passes `captionWidth` in points and `capHeight` as an em
- * fraction; the baseline is placed so the CAPITALS sit optically centred, not the em box. `fontRes` is
- * the font's resource name inside the appearance stream's own /Resources.
+ * fraction; the baseline is placed so the CAPITALS sit optically centred, not the em box. `font` is
+ * what the caption is drawn in.
  */
-export function pushButtonFace(w, h, style, caption, captionWidth, capHeight, fontRes, size) {
+export function pushButtonFace(w, h, style, caption, captionWidth, capHeight, font, size) {
     // Baseline placed so the CAPITALS sit optically centred in the box, not the em square.
     const y = (h - capHeight * size) / 2;
-    const caption_ = caption ? centredText(w, h, style, caption, captionWidth, y, fontRes, size) : "";
+    const caption_ = caption ? centredText(w, h, style, caption, captionWidth, y, font, size) : "";
     return `${box(w, h, style)}\n${caption_}`;
 }
 /** One centred, clipped text run inside a field box. Clipping means an over-long caption is cut at the
  *  border instead of bleeding across the page. Shared by the push button and the signature placeholder. */
-function centredText(w, h, style, text, textWidth, baselineY, fontRes, size) {
+function centredText(w, h, style, text, textWidth, baselineY, font, size) {
     return (`q 0 0 ${num2(w)} ${num2(h)} re W n ` +
-        `BT /${fontRes} ${num2(size)} Tf ${pdfColor(style.color)} rg ` +
-        `${num2((w - textWidth) / 2)} ${num2(baselineY)} Td (${escPdf(text)}) Tj ET Q`);
+        `BT /${font.res} ${num2(size)} Tf ${pdfColor(style.color)} rg ` +
+        `${num2((w - textWidth) / 2)} ${num2(baselineY)} Td ${font.encode(text)} Tj ET Q`);
 }
 /**
  * An EMPTY signature field: the box, a signing rule across the lower third, and an optional hint centred
  * just above it. This is the placeholder look - once someone actually signs, the signing tool replaces
  * this appearance with its own.
  */
-export function signatureFace(w, h, style, label, labelWidth, fontRes, size) {
+export function signatureFace(w, h, style, label, labelWidth, font, size) {
     const ruleY = h * 0.3;
     const inset = w * 0.08;
     const stroke = style.border ?? style.color;
     const rule = `${pdfColor(stroke)} RG ${num2(Math.max(0.5, style.borderWidth * 0.75))} w ` +
         `${num2(inset)} ${num2(ruleY)} m ${num2(w - inset)} ${num2(ruleY)} l S`;
-    const hint = label ? centredText(w, h, style, label, labelWidth, ruleY + 6, fontRes, size) : "";
+    const hint = label ? centredText(w, h, style, label, labelWidth, ruleY + 6, font, size) : "";
     return `${box(w, h, style)}\n${rule}\n${hint}`;
 }
 // Horizontal padding inside a field box, on top of the border - the same small inset Acrobat leaves so
@@ -147,11 +149,11 @@ function alignX(boxWidth, pad, width, align = "left") {
  * visibly shift on first click. The measurement matches: `getStringWidth` is the plain glyph sum, so
  * measured still equals drawn.
  */
-function textBlock(lines, style, size, fontRes) {
+function textBlock(lines, style, size, font) {
     const runs = lines
-        .map((l) => `1 0 0 1 ${num2(l.x)} ${num2(l.y)} Tm (${escPdf(l.text)}) Tj`)
+        .map((l) => `1 0 0 1 ${num2(l.x)} ${num2(l.y)} Tm ${font.encode(l.text)} Tj`)
         .join("\n");
-    return `BT /${fontRes} ${num2(size)} Tf ${pdfColor(style.color)} rg\n${runs}\nET`;
+    return `BT /${font.res} ${num2(size)} Tf ${pdfColor(style.color)} rg\n${runs}\nET`;
 }
 /** Everything a field draws is clipped to its own box, so a long value is cut at the frame rather than
  *  bleeding across the page. */
@@ -163,7 +165,7 @@ function clipped(w, h, ops) {
  * single line sits optically centred; a multi-line field stacks from the top, both measured off the
  * font's cap height rather than a guessed ratio.
  */
-export function textFieldFace(w, h, style, lines, capHeight, size, fontRes, multiline, align = "left") {
+export function textFieldFace(w, h, style, lines, capHeight, size, font, multiline, align = "left") {
     const face = box(w, h, style);
     if (lines.length === 0)
         return face;
@@ -176,13 +178,13 @@ export function textFieldFace(w, h, style, lines, capHeight, size, fontRes, mult
         // Single line: centre the capitals in the box.
         y: multiline ? h - pad - capHeight * size - i * lineHeight : (h - capHeight * size) / 2,
     }));
-    return `${face}\n${clipped(w, h, textBlock(placed, style, size, fontRes))}`;
+    return `${face}\n${clipped(w, h, textBlock(placed, style, size, font))}`;
 }
 /**
  * A list box, baked: the visible options stacked from the top, with a highlight behind the selected
  * ones. A combo box (dropdown) uses `textFieldFace` instead - it shows only its current value.
  */
-export function listBoxFace(w, h, style, lines, capHeight, size, fontRes, align = "left") {
+export function listBoxFace(w, h, style, lines, capHeight, size, font, align = "left") {
     const pad = FIELD_PAD + style.borderWidth;
     const lineHeight = size * 1.15;
     const rowTop = (i) => h - pad - (i + 1) * lineHeight;
@@ -199,6 +201,6 @@ export function listBoxFace(w, h, style, lines, capHeight, size, fontRes, align
         // Baseline inside the row: lift it off the row bottom by the slack under the capitals.
         y: rowTop(i) + (lineHeight - capHeight * size) / 2,
     }));
-    const inner = [highlights, textBlock(placed, style, size, fontRes)].filter(Boolean).join("\n");
+    const inner = [highlights, textBlock(placed, style, size, font)].filter(Boolean).join("\n");
     return `${box(w, h, style)}\n${clipped(w, h, inner)}`;
 }

package/dist/ir/display-list.d.ts

@@ -9,8 +9,8 @@ import type { FormFieldSpec, FieldStyle } from "../forms/field.js";
  * are intentionally "dumb": absolute geometry + semantic style, with no PDF
  * operators, no font indices, and no object numbers - those are the backend's job.
  *
- * Coordinates are in PDF points (1/72"). Which origin they use is still the
- * producer's concern for now; centralizing the Y-flip at this seam is Phase 3.
+ * Coordinates are in PDF points (1/72") with the engine's top-left origin. The Y-flip to PDF's
+ * bottom-left happens once per page, at this seam (`PdfBackend.flipY`).
  */
 /**
  * Structure tag for accessible (PDF/UA) tagging. `role` is the PDF structure type the content maps to
@@ -140,6 +140,9 @@ export interface Link {
     height: number;
     href?: string;
     dest?: string;
+    /** Accessible tagging only: the `/Link` structure element the annotation belongs to, and its text. */
+    structKey?: number;
+    alt?: string;
 }
 /**
  * A named destination anchor - a jump TARGET for an internal `Link({ to })`. Like `Link` it draws
@@ -177,6 +180,13 @@ export interface FormFieldNode {
     height: number;
     field: FormFieldSpec;
     style: FieldStyle;
+    /** Accessible tagging only: the `/Form` structure element the widget belongs to. */
+    structKey?: number;
+    /** The font the field's text inherits; its baked appearance draws in it when it is embedded. */
+    font?: {
+        family: string;
+        style: FontStyle;
+    };
 }
 /**
  * Pushes an affine transform (a `q` + `cm` in the content stream): everything between this and the

package/dist/layout/box-constraints.d.ts

@@ -84,6 +84,11 @@ export interface SizingParams {
     /** width / height. Derives whichever axis is left open; see `resolveSize`. */
     aspectRatio?: number;
 }
+/**
+ * The width rules of a box, for a piece of it split across pages: it keeps how wide it may be, and
+ * its height comes from what it holds on that page (CSS `box-decoration-break: clone`).
+ */
+export declare function widthRules(s: SizingParams): SizingParams;
 /** Split `SizingParams` into the per-axis form `resolveSize` takes. */
 export declare function extentSpecs(p: SizingParams): {
     width: ExtentSpec;

package/dist/layout/box-constraints.js

@@ -91,6 +91,20 @@ export function resolveExtent(fixed, factor, boundedMax, hasBounded) {
         return boundedMax * factor;
     return undefined;
 }
+/**
+ * The width rules of a box, for a piece of it split across pages: it keeps how wide it may be, and
+ * its height comes from what it holds on that page (CSS `box-decoration-break: clone`).
+ */
+export function widthRules(s) {
+    return {
+        width: s.width,
+        widthFactor: s.widthFactor,
+        minWidth: s.minWidth,
+        maxWidth: s.maxWidth,
+        minWidthFactor: s.minWidthFactor,
+        maxWidthFactor: s.maxWidthFactor,
+    };
+}
 /** Split `SizingParams` into the per-axis form `resolveSize` takes. */
 export function extentSpecs(p) {
     return {

package/dist/layout/collect-images.d.ts

@@ -1,9 +1,11 @@
 import { PDFElement } from "../elements/pdf-element.js";
 import { ImageElement } from "../elements/image-element.js";
+import { SvgElement } from "../elements/svg-element.js";
 /**
  * Walks the element tree (via `getProps`, the same shallow-reflection style as the validator) and
- * returns every `ImageElement`. A pre-layout pass uses this to resolve each image's intrinsic pixel
- * size asynchronously: layout is synchronous and cannot await jimp, yet it needs the aspect ratio to
- * give a width-only image its proportional height. Cheap - images are few and this runs once.
+ * returns every image - a bitmap, or an SVG (which needs this only when it comes from a URL). A
+ * pre-layout pass uses this to resolve each one's intrinsic size asynchronously: layout is synchronous
+ * and cannot await a decoder or a fetch, yet it needs the aspect ratio to give a width-only image its
+ * proportional height. Cheap - images are few and this runs once.
  */
-export declare function collectImageElements(root: PDFElement): ImageElement[];
+export declare function collectImageElements(root: PDFElement): (ImageElement | SvgElement)[];

package/dist/layout/collect-images.js

@@ -1,15 +1,17 @@
 import { PDFElement, hasChildrenProp, hasChildProp } from "../elements/pdf-element.js";
 import { ImageElement } from "../elements/image-element.js";
+import { SvgElement } from "../elements/svg-element.js";
 /**
  * Walks the element tree (via `getProps`, the same shallow-reflection style as the validator) and
- * returns every `ImageElement`. A pre-layout pass uses this to resolve each image's intrinsic pixel
- * size asynchronously: layout is synchronous and cannot await jimp, yet it needs the aspect ratio to
- * give a width-only image its proportional height. Cheap - images are few and this runs once.
+ * returns every image - a bitmap, or an SVG (which needs this only when it comes from a URL). A
+ * pre-layout pass uses this to resolve each one's intrinsic size asynchronously: layout is synchronous
+ * and cannot await a decoder or a fetch, yet it needs the aspect ratio to give a width-only image its
+ * proportional height. Cheap - images are few and this runs once.
  */
 export function collectImageElements(root) {
     const out = [];
     const visit = (el) => {
-        if (el instanceof ImageElement)
+        if (el instanceof ImageElement || el instanceof SvgElement)
             out.push(el);
         const props = el.getProps();
         if (hasChildrenProp(props))

package/dist/layout/flex-item.d.ts

@@ -0,0 +1,9 @@
+import { FlexiblePDFElement, PDFElement } from "../elements/pdf-element.js";
+import type { CrossAlign } from "./alignment.js";
+/** The `Expanded`/`Spacer` that makes this child flexible, if any. */
+export declare function flexibleOf(child: PDFElement): FlexiblePDFElement | undefined;
+export declare function alignSelfOf(child: PDFElement): CrossAlign | undefined;
+/** CSS `order`, 0 when unset. */
+export declare function orderOf(child: PDFElement): number;
+/** CSS `flex-shrink`, 1 when unset (the CSS default). */
+export declare function flexShrinkOf(child: PDFElement): number;

package/dist/layout/flex-item.js

@@ -0,0 +1,39 @@
+import { FlexiblePDFElement } from "../elements/pdf-element.js";
+/**
+ * How a Row or Column sees a child as a flex item. A wrapper that only marks its child (a `Link`, an
+ * `Anchor`, a `DefaultTextStyle` - see `PDFElement.proxied`) is looked through, as CSS
+ * `display: contents` is: an `Expanded`, `alignSelf`, `order` or `flexShrink` inside it acts as if the
+ * wrapper were not there. A value set on the wrapper itself wins over one set inside it.
+ */
+/** The child, then each element it is transparent for, outermost first. */
+function* itemChain(child) {
+    for (let el = child; el; el = el.proxied())
+        yield el;
+}
+/** The `Expanded`/`Spacer` that makes this child flexible, if any. */
+export function flexibleOf(child) {
+    for (const el of itemChain(child))
+        if (el instanceof FlexiblePDFElement)
+            return el;
+    return undefined;
+}
+export function alignSelfOf(child) {
+    for (const el of itemChain(child))
+        if (el.alignSelf !== undefined)
+            return el.alignSelf;
+    return undefined;
+}
+/** CSS `order`, 0 when unset. */
+export function orderOf(child) {
+    for (const el of itemChain(child))
+        if (el.order !== undefined)
+            return el.order;
+    return 0;
+}
+/** CSS `flex-shrink`, 1 when unset (the CSS default). */
+export function flexShrinkOf(child) {
+    for (const el of itemChain(child))
+        if (el.flexShrink !== undefined)
+            return el.flexShrink;
+    return 1;
+}

package/dist/layout/fragmentation.d.ts

@@ -33,11 +33,19 @@ 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;
+/**
+ * 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;
 /**

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,43 @@ 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 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 ` +
         `${Math.round(maxHeight)}pt and it cannot be broken - reduce its size, give it a bounded ` +
         `height, or let it split across pages.`;
     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: child,
+        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());
 }
 /**
  * Packs a vertical stack of children into `maxHeight`, in order. Children are measured
@@ -64,7 +84,7 @@ export function packChildren(children, maxHeight, width, ctx, gap = 0) {
         // (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
@@ -82,8 +102,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);
@@ -101,10 +123,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;
+}
+/**
+ * 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.
+ */
+export declare class BuiltFromContext<T extends {
+    dependsOnPage(): boolean;
+}> {
+    private last?;
+    get(ctx: LayoutContext, width: number, build: () => T): T;
+}

package/dist/layout/layout-cache.js

@@ -0,0 +1,107 @@
+/**
+ * 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;
+    }
+}
+/**
+ * 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.
+ */
+export class BuiltFromContext {
+    get(ctx, width, build) {
+        const last = this.last;
+        if (layoutCache.enabled &&
+            last &&
+            last.width === width &&
+            sameContext(last.key, contextKeyOf(ctx, last.value.dependsOnPage())))
+            return last.value;
+        const value = build();
+        this.last = { key: contextKeyOf(ctx, value.dependsOnPage()), width, value };
+        return value;
+    }
+}

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[]>;
 }