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

package/dist/elements/layout/rotated-element.d.ts

@@ -0,0 +1,32 @@
+import { PDFElement, LayoutContext } from "../pdf-element.js";
+import { BoxConstraints, Offset, Size } from "../../layout/box-constraints.js";
+/**
+ * Rotates its single child at PAINT time only (like Flutter's `Transform.rotate`): the child lays out
+ * in its normal, axis-aligned box and the element reports that same box UP, so siblings never reflow
+ * around the rotated shape. Only the drawing is rotated, around the box's center, by the renderer.
+ *
+ * Layout-transparent: it delegates `calculateLayout` to the child and just records the resulting box,
+ * which the renderer needs as the pivot. Not `Fragmentable` on purpose - a rotated subtree is atomic
+ * w.r.t. pagination (it moves whole to the next page rather than splitting mid-rotation).
+ */
+export declare class RotatedElement extends PDFElement {
+    private angle;
+    private child;
+    private x;
+    private y;
+    private width;
+    private height;
+    constructor({ angle, child }: {
+        angle: number;
+        child: PDFElement;
+    });
+    calculateLayout(constraints: BoxConstraints, offset: Offset, ctx: LayoutContext): Size;
+    getProps(): {
+        angle: number;
+        child: PDFElement;
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}

package/dist/elements/layout/rotated-element.js

@@ -0,0 +1,41 @@
+import { PDFElement } from "../pdf-element.js";
+/**
+ * Rotates its single child at PAINT time only (like Flutter's `Transform.rotate`): the child lays out
+ * in its normal, axis-aligned box and the element reports that same box UP, so siblings never reflow
+ * around the rotated shape. Only the drawing is rotated, around the box's center, by the renderer.
+ *
+ * Layout-transparent: it delegates `calculateLayout` to the child and just records the resulting box,
+ * which the renderer needs as the pivot. Not `Fragmentable` on purpose - a rotated subtree is atomic
+ * w.r.t. pagination (it moves whole to the next page rather than splitting mid-rotation).
+ */
+export class RotatedElement extends PDFElement {
+    constructor({ angle, child }) {
+        super();
+        this.x = 0;
+        this.y = 0;
+        this.width = 0;
+        this.height = 0;
+        this.angle = angle;
+        this.child = child;
+    }
+    calculateLayout(constraints, offset, ctx) {
+        // Delegate entirely to the child, then record its box (position + size) as our own - the
+        // rotation does not change what space we take, only how the child is painted.
+        const size = this.child.calculateLayout(constraints, offset, ctx);
+        this.x = offset.x;
+        this.y = offset.y;
+        this.width = size.width;
+        this.height = size.height;
+        return size;
+    }
+    getProps() {
+        return {
+            angle: this.angle,
+            child: this.child,
+            x: this.x,
+            y: this.y,
+            width: this.width,
+            height: this.height,
+        };
+    }
+}

package/dist/elements/page-element.d.ts

@@ -20,6 +20,14 @@ interface PDFPageParams extends WithChildren {
     /** Laid out at the BOTTOM of the content box, repeated on every physical page. */
     footer?: PDFElement;
 }
+/**
+ * The full page (media box) size in points, orientation applied. This is what a `PageBuilder` sees as
+ * `pageSize`; `resolvePageContentBox` below then subtracts the margins.
+ */
+export declare function resolvePageSize(config: PDFPageConfig): {
+    width: number;
+    height: number;
+};
 /**
  * The content box of a page (inside the margins, orientation applied) for a fully
  * resolved config. Single source of truth, shared by `PageElement` layout and the page

package/dist/elements/page-element.js

@@ -1,7 +1,18 @@
-import { pageFormats } from "../constants/page-sizes.js";
+import { pageFormats, PageSize } from "../constants/page-sizes.js";
 import { Orientation } from "../renderer/pdf-config.js";
 import { BoxConstraints } from "../layout/box-constraints.js";
 import { PDFElement } from "./pdf-element.js";
+/**
+ * The full page (media box) size in points, orientation applied. This is what a `PageBuilder` sees as
+ * `pageSize`; `resolvePageContentBox` below then subtracts the margins.
+ */
+export function resolvePageSize(config) {
+    // Defaults to A4 when the config is not fully resolved, matching what PageRenderer does for the MediaBox.
+    const [pageW, pageH] = config.customSize ?? pageFormats[config.pageSize ?? PageSize.A4];
+    return config.orientation === Orientation.landscape
+        ? { width: pageH, height: pageW }
+        : { width: pageW, height: pageH };
+}
 /**
  * The content box of a page (inside the margins, orientation applied) for a fully
  * resolved config. Single source of truth, shared by `PageElement` layout and the page
@@ -63,6 +74,7 @@ export class PageElement extends PDFElement {
             pageConfig: this.config,
             textStyle: ctx.textStyle,
             onOverflow: ctx.onOverflow,
+            pageInfo: ctx.pageInfo, // the render pass supplies it; absent during pagination
         };
         // Place the header/footer bands; the body gets the region left in between (the whole
         // content box when there is neither - byte-identical to a plain page).

package/dist/elements/pdf-element.d.ts

@@ -23,9 +23,25 @@ export interface PositioningFrame {
         size: Size;
     }, ctx: LayoutContext) => void>;
 }
+/**
+ * What a `PageBuilder` learns about the page it landed on. `pageNumber` is 1-based and counts PHYSICAL
+ * pages across the whole document (a logical `Page` that overflows contributes several); `pageCount` is
+ * the document's final physical page total. `pageSize` is the media box in points, orientation applied.
+ */
+export interface PageInfo {
+    pageNumber: number;
+    pageCount: number;
+    pageSize: {
+        width: number;
+        height: number;
+    };
+}
 export interface LayoutContext {
     metrics: FontMetrics;
     pageConfig: PDFPageConfig;
+    /** The page a `PageBuilder` is being laid out on. Only the render pass knows the real numbers, so
+     *  during pagination this is absent and a `PageBuilder` builds against a provisional "1 of 1". */
+    pageInfo?: PageInfo;
     /** The nearest enclosing positioning frame, if any (set by a `relative` Box). */
     frame?: PositioningFrame;
     /** The cascaded text style descendants inherit (CSS/Flutter-style). Seeded at the document root
@@ -49,6 +65,21 @@ export declare abstract class PDFElement {
      * happens once at the IR -> backend seam.
      */
     abstract calculateLayout(constraints: BoxConstraints, offset: Offset, ctx: LayoutContext): Size;
+    /**
+     * The relative-size fraction (0..1) this element asked for on the given axis, if any (`horizontal` =
+     * width). A flex parent reads it to resolve a percentage child against its OWN main size - e.g. a
+     * `Box({ width: "50%" })` inside a Row, where the child otherwise gets an unbounded main axis and the
+     * fraction would have nothing to resolve against. Default: the element is not relatively sized.
+     */
+    relativeSizeFactor(_horizontal: boolean): number | undefined;
+    /**
+     * Whether this element needs a BOUNDED extent on the given axis to lay itself out (`true` for a
+     * horizontal axis = width). A flex parent measures its fixed children with an unbounded main axis, so
+     * they keep their natural size; but a stack holding an `Expanded`/`Spacer` has no leftover space to
+     * distribute unless it is told how much main axis it may occupy. Such a stack answers `true` here and
+     * the parent hands it the line's bounded main extent instead of `Infinity`. Default: no.
+     */
+    needsBoundedMain(_horizontal: boolean): boolean;
 }
 export declare abstract class SizedPDFElement extends PDFElement {
     protected x: number;

package/dist/elements/pdf-element.js

@@ -14,6 +14,25 @@ export class PDFElement {
         this._structId = from._structId;
         return this;
     }
+    /**
+     * The relative-size fraction (0..1) this element asked for on the given axis, if any (`horizontal` =
+     * width). A flex parent reads it to resolve a percentage child against its OWN main size - e.g. a
+     * `Box({ width: "50%" })` inside a Row, where the child otherwise gets an unbounded main axis and the
+     * fraction would have nothing to resolve against. Default: the element is not relatively sized.
+     */
+    relativeSizeFactor(_horizontal) {
+        return undefined;
+    }
+    /**
+     * Whether this element needs a BOUNDED extent on the given axis to lay itself out (`true` for a
+     * horizontal axis = width). A flex parent measures its fixed children with an unbounded main axis, so
+     * they keep their natural size; but a stack holding an `Expanded`/`Spacer` has no leftover space to
+     * distribute unless it is told how much main axis it may occupy. Such a stack answers `true` here and
+     * the parent hands it the line's bounded main extent instead of `Infinity`. Default: no.
+     */
+    needsBoundedMain(_horizontal) {
+        return false;
+    }
 }
 export class SizedPDFElement extends PDFElement {
     constructor(data) {

package/dist/elements/rectangle-element.d.ts

@@ -23,6 +23,11 @@ interface RectangleElementParams extends SizedElement, WithChildren {
     /** `"hidden"` crops children to the box (CSS `overflow: hidden`); `"visible"` (default) lets a
      *  `Positioned` child spill over the edge. */
     overflow?: "hidden" | "visible";
+    /** Width as a fraction (0..1) of the offered width, instead of a fixed `width` (CSS `50%`). Only
+     *  resolves in a bounded region; an explicit `width` wins over it. */
+    widthFactor?: number;
+    /** Height as a fraction (0..1) of the offered height; see `widthFactor`. */
+    heightFactor?: number;
 }
 export declare class RectangleElement extends SizedPDFElement implements Fragmentable {
     private children;
@@ -34,7 +39,7 @@ export declare class RectangleElement extends SizedPDFElement implements Fragmen
     private relative;
     private overflow;
     private sizeMemory;
-    constructor({ children, color, backgroundColor, borderWidth, width, height, radius, sideBorders, relative, overflow, }: RectangleElementParams);
+    constructor({ children, color, backgroundColor, borderWidth, width, height, radius, sideBorders, relative, overflow, widthFactor, heightFactor, }: RectangleElementParams);
     /**
      * Splits the bordered box across pages (box-decoration-break: clone - every fragment
      * gets its own full border). The children stack is packed into the space left after
@@ -45,6 +50,11 @@ export declare class RectangleElement extends SizedPDFElement implements Fragmen
      */
     fragment(maxHeight: number, width: number, ctx: LayoutContext): FragmentResult;
     private cloneWithChildren;
+    relativeSizeFactor(horizontal: boolean): number | undefined;
+    /** A box has no flex children of its own, but it must not swallow the need of the stack inside it: a
+     *  `Spacer` in a box can only resolve if the box itself was given a bounded extent to pass down. With an
+     *  explicit size on an axis the box already knows its extent there and asks for nothing. */
+    needsBoundedMain(horizontal: boolean): boolean;
     calculateLayout(constraints: BoxConstraints, offset: Offset, ctx: LayoutContext): Size;
     getProps(): {
         x: number;

package/dist/elements/rectangle-element.js

@@ -1,9 +1,9 @@
 import { Color } from "../common/color.js";
-import { BoxConstraints } from "../layout/box-constraints.js";
+import { BoxConstraints, resolveExtent } from "../layout/box-constraints.js";
 import { packChildren } from "../layout/fragmentation.js";
 import { SizedPDFElement, } from "./pdf-element.js";
 export class RectangleElement extends SizedPDFElement {
-    constructor({ children = [], color = new Color(0, 0, 0), backgroundColor, borderWidth, width, height, radius, sideBorders, relative, overflow, }) {
+    constructor({ children = [], color = new Color(0, 0, 0), backgroundColor, borderWidth, width, height, radius, sideBorders, relative, overflow, widthFactor, heightFactor, }) {
         super({ x: 0, y: 0, width, height });
         this.children = [];
         this.children = children;
@@ -15,7 +15,7 @@ export class RectangleElement extends SizedPDFElement {
         this.sideBorders = sideBorders;
         this.relative = relative ?? false;
         this.overflow = overflow ?? "visible";
-        this.sizeMemory = { x: 0, y: 0, width, height };
+        this.sizeMemory = { x: 0, y: 0, width, height, widthFactor, heightFactor };
     }
     /**
      * Splits the bordered box across pages (box-decoration-break: clone - every fragment
@@ -26,7 +26,10 @@ export class RectangleElement extends SizedPDFElement {
      * box is sized by what it actually holds on each page.
      */
     fragment(maxHeight, width, ctx) {
-        const boxWidth = this.sizeMemory.width ?? width;
+        // A percentage width resolves against the region width the page driver hands us, so a
+        // paginating %-box keeps its fraction on every page.
+        const boxWidth = this.sizeMemory.width ??
+            (this.sizeMemory.widthFactor !== undefined ? width * this.sizeMemory.widthFactor : width);
         const innerWidth = Math.max(0, boxWidth - 2 * this.borderWidth);
         // Border-box: the content is inset by the border on top and bottom, so a fragment
         // holding `c` of content is `c + 2*border` tall. (Derived, not a fudge factor.)
@@ -47,6 +50,9 @@ export class RectangleElement extends SizedPDFElement {
             x: 0,
             y: 0,
             width: this.sizeMemory.width,
+            widthFactor: this.sizeMemory.widthFactor,
+            // A split box is sized by its per-page content (height passed in), so the height factor
+            // is intentionally dropped here - box-decoration-break, same as an explicit height.
             height,
             children,
             color: this.color,
@@ -58,25 +64,43 @@ export class RectangleElement extends SizedPDFElement {
             overflow: this.overflow,
         });
     }
+    relativeSizeFactor(horizontal) {
+        return horizontal ? this.sizeMemory.widthFactor : this.sizeMemory.heightFactor;
+    }
+    /** A box has no flex children of its own, but it must not swallow the need of the stack inside it: a
+     *  `Spacer` in a box can only resolve if the box itself was given a bounded extent to pass down. With an
+     *  explicit size on an axis the box already knows its extent there and asks for nothing. */
+    needsBoundedMain(horizontal) {
+        const requested = horizontal
+            ? [this.sizeMemory.width, this.sizeMemory.widthFactor]
+            : [this.sizeMemory.height, this.sizeMemory.heightFactor];
+        if (requested.some((v) => v !== undefined))
+            return false;
+        return this.children.some((c) => c.needsBoundedMain(horizontal));
+    }
     calculateLayout(constraints, offset, ctx) {
+        // An explicit extent is a fixed point size or a fraction of the offered box (relative sizing);
+        // the fraction only resolves in a bounded region. `undefined` = fill / shrink-wrap below.
+        const explicitWidth = resolveExtent(this.sizeMemory.width, this.sizeMemory.widthFactor, constraints.maxWidth, constraints.hasBoundedWidth);
+        const explicitHeight = resolveExtent(this.sizeMemory.height, this.sizeMemory.heightFactor, constraints.maxHeight, constraints.hasBoundedHeight);
         // Width: an explicit size wins (clamped), else fill the offered box. (Without this a
         // fixed box would balloon to the parent's size.)
         this.width =
-            this.sizeMemory.width !== undefined
-                ? constraints.constrainWidth(this.sizeMemory.width)
+            explicitWidth !== undefined
+                ? constraints.constrainWidth(explicitWidth)
                 : constraints.hasBoundedWidth
                     ? constraints.maxWidth
                     : this.width;
         // Width shrink-wrap: no explicit width AND an unbounded region (e.g. a `Box` badge inside a
         // `Positioned`). Resolved after the children are measured, just below.
-        const shrinkWrapWidth = this.sizeMemory.width === undefined && !constraints.hasBoundedWidth;
+        const shrinkWrapWidth = explicitWidth === undefined && !constraints.hasBoundedWidth;
         // Height: explicit wins; otherwise FILL a bounded region (e.g. inside an Expanded) but
         // SHRINK-WRAP the content in an unbounded one (a note box in a stack). Shrink-wrap is
         // resolved after the children are measured, just below.
-        const shrinkWrapHeight = this.sizeMemory.height === undefined && !constraints.hasBoundedHeight;
+        const shrinkWrapHeight = explicitHeight === undefined && !constraints.hasBoundedHeight;
         this.height =
-            this.sizeMemory.height !== undefined
-                ? constraints.constrainHeight(this.sizeMemory.height)
+            explicitHeight !== undefined
+                ? constraints.constrainHeight(explicitHeight)
                 : constraints.hasBoundedHeight
                     ? constraints.maxHeight
                     : this.height;
@@ -89,16 +113,28 @@ export class RectangleElement extends SizedPDFElement {
             ? { origin: { x: 0, y: 0 }, size: { width: 0, height: 0 }, place: [] }
             : undefined;
         const childCtx = frame ? { ...ctx, frame } : ctx;
-        // Lay out children stacked inside the border (inset by the border width). Width is
-        // finalized here; height is left unbounded so each child sizes to its own content.
+        // Lay out children stacked inside the border (inset by the border width). Width is finalized here;
+        // height is left unbounded so each child sizes to its own content - EXCEPT for a child that cannot
+        // lay itself out without a bound (a stack holding an `Expanded`/`Spacer`). That one gets the height
+        // still free inside the box, so its flex child has real leftover space instead of an infinite one.
         const innerWidth = shrinkWrapWidth
             ? Infinity
             : Math.max(0, (this.width ?? 0) - 2 * this.borderWidth);
+        const innerHeight = shrinkWrapHeight
+            ? Infinity
+            : Math.max(0, (this.height ?? 0) - 2 * this.borderWidth);
         let contentWidth = 0;
         let contentHeight = 0;
         let yCursor = this.y + this.borderWidth;
         for (const child of this.children) {
-            const childSize = child.calculateLayout(BoxConstraints.loose(innerWidth, Infinity), { x: this.x + this.borderWidth, y: yCursor }, childCtx);
+            const consumed = yCursor - (this.y + this.borderWidth);
+            // Same rule the flex helper applies: a child gets a finite main extent when it cannot lay itself
+            // out without one - a stack holding an `Expanded`/`Spacer`, or a child sized as a percentage of us.
+            const needsBound = child.needsBoundedMain(false) || child.relativeSizeFactor(false) !== undefined;
+            const childHeight = needsBound
+                ? Math.max(0, innerHeight - consumed) // Infinity - consumed stays Infinity, as it should
+                : Infinity;
+            const childSize = child.calculateLayout(BoxConstraints.loose(innerWidth, childHeight), { x: this.x + this.borderWidth, y: yCursor }, childCtx);
             yCursor += childSize.height;
             contentHeight += childSize.height;
             contentWidth = Math.max(contentWidth, childSize.width);

package/dist/elements/row-element.d.ts

@@ -8,6 +8,11 @@ interface RowElementParams extends WithChildren {
     main?: MainAlign;
     /** Vertical alignment of each child (cross axis); defaults to `stretch`. */
     cross?: CrossAlign;
+    /** Width/height as points (fixed) or a fraction (0..1) of the offered box (relative sizing). */
+    width?: number;
+    height?: number;
+    widthFactor?: number;
+    heightFactor?: number;
 }
 /**
  * Horizontal stack: the mirror of `ContainerElement` (Column). Children are laid out
@@ -26,7 +31,12 @@ export declare class RowElement extends SizedPDFElement {
     private gap;
     private main;
     private cross;
-    constructor({ children, gap, main, cross }: RowElementParams);
+    private requested;
+    constructor({ children, gap, main, cross, width, height, widthFactor, heightFactor, }: RowElementParams);
+    relativeSizeFactor(horizontal: boolean): number | undefined;
+    /** The mirror of `ContainerElement`: a Row's OWN flex child needs a bounded width, and the need of any
+     *  descendant propagates on both axes (see the Column for the reasoning). */
+    needsBoundedMain(horizontal: boolean): boolean;
     calculateLayout(constraints: BoxConstraints, offset: Offset, ctx: LayoutContext): Size;
     getProps(): {
         x: number;

package/dist/elements/row-element.js

@@ -1,5 +1,6 @@
+import { resolveExtent } from "../layout/box-constraints.js";
 import { FlexLayoutHelper, HORIZONTAL_AXIS } from "../utils/flex-layout.js";
-import { SizedPDFElement } from "./pdf-element.js";
+import { FlexiblePDFElement, SizedPDFElement, } from "./pdf-element.js";
 /**
  * Horizontal stack: the mirror of `ContainerElement` (Column). Children are laid out
  * left-to-right via the shared `FlexLayoutHelper` on the horizontal axis; fixed children
@@ -13,26 +14,54 @@ import { SizedPDFElement } from "./pdf-element.js";
  * Grid/Table concern.
  */
 export class RowElement extends SizedPDFElement {
-    constructor({ children, gap, main, cross }) {
+    constructor({ children, gap, main, cross, width, height, widthFactor, heightFactor, }) {
         super({ x: 0, y: 0 });
         this.children = children;
         this.gap = gap ?? 0;
         this.main = main ?? "start";
         this.cross = cross ?? "stretch";
+        this.requested = { width, height, widthFactor, heightFactor };
+    }
+    relativeSizeFactor(horizontal) {
+        return horizontal ? this.requested.widthFactor : this.requested.heightFactor;
+    }
+    /** The mirror of `ContainerElement`: a Row's OWN flex child needs a bounded width, and the need of any
+     *  descendant propagates on both axes (see the Column for the reasoning). */
+    needsBoundedMain(horizontal) {
+        const requested = horizontal
+            ? [this.requested.width, this.requested.widthFactor]
+            : [this.requested.height, this.requested.heightFactor];
+        if (requested.some((v) => v !== undefined))
+            return false;
+        const ownFlexChild = horizontal && this.children.some((c) => c instanceof FlexiblePDFElement);
+        return ownFlexChild || this.children.some((c) => c.needsBoundedMain(horizontal));
     }
     calculateLayout(constraints, offset, ctx) {
         this.x = offset.x;
         this.y = offset.y;
-        // Width fills the offered space (flex children split the leftover); height is the
-        // tallest child unless the parent bounds it.
-        const mainAvail = constraints.hasBoundedWidth ? constraints.maxWidth : Infinity;
-        const crossAvail = constraints.hasBoundedHeight ? constraints.maxHeight : Infinity;
+        // Relative sizing: a pinned extent (fixed or a fraction of the offered box, clamped) wins; else
+        // width fills the offered space (flex children split the leftover) and height is the tallest child.
+        const explicitWidth = resolveExtent(this.requested.width, this.requested.widthFactor, constraints.maxWidth, constraints.hasBoundedWidth);
+        const explicitHeight = resolveExtent(this.requested.height, this.requested.heightFactor, constraints.maxHeight, constraints.hasBoundedHeight);
+        const boundedWidth = explicitWidth !== undefined
+            ? constraints.constrainWidth(explicitWidth)
+            : constraints.hasBoundedWidth
+                ? constraints.maxWidth
+                : undefined;
+        const boundedHeight = explicitHeight !== undefined
+            ? constraints.constrainHeight(explicitHeight)
+            : constraints.hasBoundedHeight
+                ? constraints.maxHeight
+                : undefined;
+        // Horizontal stack: main = width (children fill it), cross = height (children can stretch to it).
+        const mainAvail = boundedWidth ?? Infinity;
+        const crossAvail = boundedHeight ?? Infinity;
         let result = { mainUsed: 0, crossUsed: 0 };
         if (this.children.length > 0) {
             result = FlexLayoutHelper.layout(this.children, HORIZONTAL_AXIS, mainAvail, crossAvail, this.x, this.y, { gap: this.gap, main: this.main, cross: this.cross }, ctx);
         }
-        this.width = constraints.hasBoundedWidth ? constraints.maxWidth : result.mainUsed;
-        this.height = constraints.hasBoundedHeight ? constraints.maxHeight : result.crossUsed;
+        this.width = boundedWidth ?? result.mainUsed;
+        this.height = boundedHeight ?? result.crossUsed;
         return { width: this.width, height: this.height };
     }
     getProps() {

package/dist/elements/text-element.d.ts

@@ -10,6 +10,10 @@ export interface TextSegment {
     fontColor?: Color;
     fontFamily?: string;
     fontSize?: number;
+    /** External URL: this segment becomes an inline hyperlink (a /Link annotation over its glyphs). */
+    href?: string;
+    /** Internal named destination (an `Anchor`): this segment links to it (a /GoTo /Link annotation). */
+    dest?: string;
 }
 /** Accessibility role for the tagged structure tree: a heading level or a paragraph (the default). */
 export type TextRole = "h1" | "h2" | "h3" | "h4" | "h5" | "h6" | "p";

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

@@ -103,6 +103,64 @@ export interface ClipPush {
 export interface ClipPop {
     type: "clip-pop";
 }
+/**
+ * A hyperlink over a rectangle. Unlike every other IR node this draws NOTHING into the content stream -
+ * it becomes a PDF Link ANNOTATION on the page (`/Annots`), a side channel next to the drawing. Exactly
+ * one target is set: `href` is an external URL (a `/URI` action); `dest` is a named destination inside
+ * this document (a `/GoTo` action, resolved via the catalog `/Names /Dests` tree - see `Anchor`). The
+ * rect is the clickable region in top-left engine coords; the Y-flip converts it to PDF page space.
+ *
+ * NOTE: a Link inside a `TransformPush` is NOT yet rotated with it - the annotation rect lives in page
+ * space and ignores the content-stream matrix. Completing that is a planned follow-up (see todo.md).
+ */
+export interface Link {
+    type: "link";
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    href?: string;
+    dest?: string;
+}
+/**
+ * A named destination anchor - a jump TARGET for an internal `Link({ to })`. Like `Link` it draws
+ * NOTHING; it registers `name` -> (this page, `y`) in the catalog `/Names /Dests` name tree. `y` is the
+ * top of the target in top-left engine coords (the Y-flip turns it into the page-space scroll target).
+ */
+export interface Anchor {
+    type: "anchor";
+    y: number;
+    name: string;
+}
+/**
+ * A document-outline (bookmark) anchor. Like `Link` it draws NOTHING - it becomes an entry in the PDF
+ * outline tree (`/Outlines`), a side channel the viewer shows in its bookmark panel. `y` is the top of
+ * the target in top-left engine coords (the Y-flip turns it into the page-space scroll target); `level`
+ * (1-based) nests the entry under the nearest preceding entry of a smaller level.
+ */
+export interface Outline {
+    type: "outline";
+    y: number;
+    title: string;
+    level: number;
+}
+/**
+ * Pushes an affine transform (a `q` + `cm` in the content stream): everything between this and the
+ * matching `TransformPop` is painted through `matrix`. This is what `Rotated` wraps its child's nodes
+ * in, so a subtree draws rotated (or scaled/translated) around a pivot without touching its layout.
+ *
+ * `matrix` is `[a, b, c, d, e, f]` in the engine's TOP-LEFT coordinates - the same space every other IR
+ * node uses. The Y-flip at the IR -> backend seam converts it to PDF's bottom-left once per page, so
+ * producers stay coordinate-system-blind (they never see a flipped matrix).
+ */
+export interface TransformPush {
+    type: "transform-push";
+    matrix: [number, number, number, number, number, number];
+}
+/** Closes the most recent `TransformPush` (restores the graphics state). */
+export interface TransformPop {
+    type: "transform-pop";
+}
 /**
  * One drawing command of a `Path`, in absolute page coordinates. Curves are CUBIC because PDF
  * content streams have no quadratic operator - a producer converts TrueType quads to cubics before
@@ -168,4 +226,4 @@ export interface Path {
     tag?: StructTag;
 }
 /** The closed set of primitives the PDF backend knows how to draw. */
-export type IRNode = TextRun | Rect | Line | Image | ClipPush | ClipPop | Path;
+export type IRNode = TextRun | Rect | Line | Image | ClipPush | ClipPop | Path | Link | Outline | Anchor | TransformPush | TransformPop;

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

@@ -44,6 +44,14 @@ export declare class BoxConstraints {
     /** Returns the constraints clamped to lie within `parent` (Flutter's enforce). */
     enforce(parent: BoxConstraints): BoxConstraints;
 }
+/**
+ * Resolves a sized element's extent on one axis (relative sizing). An explicit point size (`fixed`)
+ * always wins; otherwise a `factor` (0..1) of the offered extent, but ONLY when that axis is bounded -
+ * a fraction of an unbounded axis has no meaning (Flutter's FractionallySizedBox under unbounded
+ * constraints). Returns `undefined` to mean "no explicit extent", i.e. fill the box or shrink-wrap.
+ * Shared by every sized element so `width: "50%"` behaves identically across Box / Column / Row / Image.
+ */
+export declare function resolveExtent(fixed: number | undefined, factor: number | undefined, boundedMax: number, hasBounded: boolean): number | undefined;
 /** The size an element resolves to and returns UP the tree. */
 export interface Size {
     width: number;

package/dist/layout/box-constraints.js

@@ -67,3 +67,17 @@ export class BoxConstraints {
         return new BoxConstraints(Math.max(parent.minWidth, Math.min(this.minWidth, parent.maxWidth)), Math.max(parent.minWidth, Math.min(this.maxWidth, parent.maxWidth)), Math.max(parent.minHeight, Math.min(this.minHeight, parent.maxHeight)), Math.max(parent.minHeight, Math.min(this.maxHeight, parent.maxHeight)));
     }
 }
+/**
+ * Resolves a sized element's extent on one axis (relative sizing). An explicit point size (`fixed`)
+ * always wins; otherwise a `factor` (0..1) of the offered extent, but ONLY when that axis is bounded -
+ * a fraction of an unbounded axis has no meaning (Flutter's FractionallySizedBox under unbounded
+ * constraints). Returns `undefined` to mean "no explicit extent", i.e. fill the box or shrink-wrap.
+ * Shared by every sized element so `width: "50%"` behaves identically across Box / Column / Row / Image.
+ */
+export function resolveExtent(fixed, factor, boundedMax, hasBounded) {
+    if (fixed !== undefined)
+        return fixed;
+    if (factor !== undefined && hasBounded)
+        return boundedMax * factor;
+    return undefined;
+}

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

@@ -0,0 +1,9 @@
+import { PDFElement } from "../elements/pdf-element.js";
+import { ImageElement } from "../elements/image-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.
+ */
+export declare function collectImageElements(root: PDFElement): ImageElement[];

package/dist/layout/collect-images.js

@@ -0,0 +1,34 @@
+import { PDFElement, hasChildrenProp, hasChildProp } from "../elements/pdf-element.js";
+import { ImageElement } from "../elements/image-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.
+ */
+export function collectImageElements(root) {
+    const out = [];
+    const visit = (el) => {
+        if (el instanceof ImageElement)
+            out.push(el);
+        const props = el.getProps();
+        if (hasChildrenProp(props))
+            for (const c of props.children)
+                visit(c);
+        else if (hasChildProp(props))
+            visit(props.child);
+        // Wrappers that hold a subtree outside `children`/`child`: a Page's header/footer and a
+        // RepeatingHeaderElement's `body` (a Table with a header wraps its rows there). A
+        // DeferredElement's `composed` is null until layout runs, so it cannot be reached from this
+        // pre-layout pass; an image inside a deferred subtree just skips aspect pre-resolution.
+        const w = props;
+        if (w.header instanceof PDFElement)
+            visit(w.header);
+        if (w.footer instanceof PDFElement)
+            visit(w.footer);
+        if (w.body instanceof PDFElement)
+            visit(w.body);
+    };
+    visit(root);
+    return out;
+}

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

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

package/dist/renderer/anchor-renderer.js

@@ -0,0 +1,11 @@
+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 = renderer ? await renderer(child, objectManager) : [];
+        // 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

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