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

package/dist/elements/container-element.js

@@ -1,13 +1,15 @@
 import { FlexLayoutHelper, VERTICAL_AXIS } from "../utils/flex-layout.js";
+import { resolveExtent } from "../layout/box-constraints.js";
 import { packChildren } from "../layout/fragmentation.js";
-import { SizedPDFElement, } from "./pdf-element.js";
+import { FlexiblePDFElement, SizedPDFElement, } from "./pdf-element.js";
 export class ContainerElement extends SizedPDFElement {
-    constructor({ x, y, width, height, children, gap, main, cross }) {
+    constructor({ x, y, width, height, children, gap, main, cross, widthFactor, heightFactor, }) {
         super({ x, y, width, height });
         this.children = children;
         this.gap = gap ?? 0;
         this.main = main ?? "start";
         this.cross = cross ?? "stretch";
+        this.requested = { width, height, widthFactor, heightFactor };
     }
     /**
      * Splits the vertical stack across pages. Children are measured against the content
@@ -35,27 +37,59 @@ export class ContainerElement extends SizedPDFElement {
         return new ContainerElement({
             x: this.x,
             y: this.y,
-            width: this.width,
-            height: this.height,
+            // Carry the requested WIDTH (a %-width column keeps its width on every page); the height is
+            // intentionally dropped so each fragment shrink-wraps to the content it actually holds.
+            width: this.requested.width,
+            widthFactor: this.requested.widthFactor,
             children,
             gap: this.gap,
             main: this.main,
             cross: this.cross,
         });
     }
+    relativeSizeFactor(horizontal) {
+        return horizontal ? this.requested.widthFactor : this.requested.heightFactor;
+    }
+    /**
+     * A Column stacks vertically, so a flex child of its OWN only ever needs a bounded height. But the need
+     * also propagates: a `Spacer` two levels down is just as unable to resolve against an infinite axis, so
+     * we ask the children too - on both axes, since a nested Row's `Spacer` needs a bounded WIDTH and a
+     * Column nested in a Row is exactly where that width goes missing.
+     *
+     * An explicit extent on an axis short-circuits it: the element already knows how big it is there, and
+     * with no flex descendant nothing needs distributing, so it keeps shrink-wrapping. That is what leaves
+     * every existing layout untouched.
+     */
+    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) {
-        // The container fills the width/height it is offered; when an axis is unbounded it
-        // shrink-wraps to its children instead (mirrors how Row shrink-wraps). Width unbounded
-        // happens for a Column nested in a Row (the Row offers its fixed children unbounded
-        // width); passing 0 there would collapse every child to width 0.
-        if (constraints.hasBoundedWidth)
-            this.width = constraints.maxWidth;
-        if (constraints.hasBoundedHeight)
-            this.height = constraints.maxHeight;
         this.x = offset.x;
         this.y = offset.y;
-        const crossAvail = constraints.hasBoundedWidth ? this.width : Infinity;
-        const mainAvail = constraints.hasBoundedHeight ? this.height : Infinity;
+        // Relative sizing: a pinned extent (fixed points or a fraction of the offered box, clamped into
+        // the constraints) wins; else fill a bounded axis; else stay `undefined` and shrink-wrap below.
+        // A Column nested in a Row gets unbounded width - passing 0 there would collapse children to 0.
+        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;
+        // Vertical stack: cross = width (children fill it), main = height (the stacking extent).
+        const crossAvail = boundedWidth ?? Infinity;
+        const mainAvail = boundedHeight ?? Infinity;
         let result = { mainUsed: 0, crossUsed: 0 };
         if (this.children) {
             // Vertical flex stack (main = height, cross = width). The shared helper measures
@@ -63,14 +97,12 @@ export class ContainerElement extends SizedPDFElement {
             // in source order.
             result = FlexLayoutHelper.layout(this.children, VERTICAL_AXIS, mainAvail, crossAvail, this.y, this.x, { gap: this.gap, main: this.main, cross: this.cross }, ctx);
         }
-        // Bounded: fill the offered extent. Unbounded: shrink to the children (height = the
-        // stack, width = the widest child). Top-left coordinates; the container draws nothing,
-        // and the Y-flip happens once at the IR -> backend seam.
-        const width = constraints.hasBoundedWidth ? this.width : result.crossUsed;
-        const height = constraints.hasBoundedHeight ? this.height : result.mainUsed;
-        this.width = width;
-        this.height = height;
-        return { width, height };
+        // Pinned/bounded axis takes that extent; an unbounded one shrink-wraps to the children (height =
+        // the stack, width = the widest child). Top-left coordinates; the container draws nothing, and
+        // the Y-flip happens once at the IR -> backend seam.
+        this.width = boundedWidth ?? result.crossUsed;
+        this.height = boundedHeight ?? result.mainUsed;
+        return { width: this.width, height: this.height };
     }
     getProps() {
         return {

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

@@ -19,6 +19,7 @@ export declare class CustomLocalImage extends CustomImage {
     private imagePath;
     private fileBuffer;
     private fileRawData;
+    private dims?;
     constructor(imagePath: string);
     init(): Promise<void>;
     getImageType(): Promise<string>;
@@ -36,6 +37,7 @@ export declare class CustomLocalImage extends CustomImage {
 export declare class CustomBytesImage extends CustomImage {
     private bytes;
     private fileRawData;
+    private dims?;
     constructor(bytes: Uint8Array);
     init(): Promise<void>;
     getImageType(): Promise<string>;
@@ -49,6 +51,10 @@ interface ImageElementParams {
     image: CustomImage;
     width?: number;
     height?: number;
+    /** Width as a fraction (0..1) of the offered width instead of a fixed `width` (relative sizing). */
+    widthFactor?: number;
+    /** Height as a fraction (0..1) of the offered height; see `widthFactor`. */
+    heightFactor?: number;
     fit?: BoxFit;
     /** Corner radius in points; rounds the image box (0 = sharp, default). */
     radius?: number;
@@ -57,10 +63,22 @@ interface ImageElementParams {
 }
 export declare class ImageElement extends SizedPDFElement {
     private image;
+    private widthFactor?;
+    private heightFactor?;
     private fit;
     private radius;
     private readonly alt?;
-    constructor({ image, width, height, fit, radius, alt }: ImageElementParams);
+    private requested;
+    private intrinsic?;
+    constructor({ image, width, height, widthFactor, heightFactor, fit, radius, alt, }: ImageElementParams);
+    /**
+     * Loads the image and records its intrinsic pixel size. Runs in the async pre-layout pass (layout
+     * itself is synchronous and cannot await jimp) so `calculateLayout` can turn a width-only image
+     * into a proportional box. Best-effort: a load failure leaves the size unresolved (the renderer
+     * surfaces the real error) and the image just keeps whatever explicit size it was given.
+     */
+    resolveIntrinsicSize(): Promise<void>;
+    relativeSizeFactor(horizontal: boolean): number | undefined;
     calculateLayout(constraints: BoxConstraints, offset: Offset, _ctx: LayoutContext): Size;
     getProps(): {
         x: number;

package/dist/elements/image-element.js

@@ -1,6 +1,7 @@
 import { getImageDimensions } from "../utils/image-helper.js";
 import { latin1FromBytes } from "../utils/bytes.js";
 import { readFileBytesAsync } from "../platform/node-fs.js";
+import { resolveExtent } from "../layout/box-constraints.js";
 import { SizedPDFElement } from "./pdf-element.js";
 // path.extname without node:path (browser-safe): the substring from the last dot, if it sits after the
 // last slash (so a dot in a directory name does not count). Enough for image file extensions.
@@ -24,6 +25,8 @@ export class CustomLocalImage extends CustomImage {
         this.imagePath = imagePath;
     }
     async init() {
+        if (this.fileBuffer)
+            return; // idempotent: the pre-layout size pass and the renderer both call init()
         try {
             // Loading image and convert it to base64
             await this.loadImage(this.imagePath);
@@ -59,13 +62,13 @@ export class CustomLocalImage extends CustomImage {
         return this.fileRawData;
     }
     async getImageDimensions() {
+        if (this.dims)
+            return this.dims; // reuse: the pre-layout size pass and the renderer both ask
         if (!this.fileBuffer) {
             throw new Error("You must first call the `loadAndConvertImage` method");
         }
-        // Since now (30.09.2024) we using "Jimp" - So we don't need our custom method to get the image dimension.
-        // But at the moment I let it still here...
-        const dimensions = await getImageDimensions(this.fileBuffer);
-        return dimensions;
+        this.dims = await getImageDimensions(this.fileBuffer);
+        return this.dims;
     }
 }
 /**
@@ -91,26 +94,64 @@ export class CustomBytesImage extends CustomImage {
         return this.fileRawData;
     }
     async getImageDimensions() {
-        return getImageDimensions(this.bytes);
+        if (!this.dims)
+            this.dims = await getImageDimensions(this.bytes); // reuse across pre-pass + render
+        return this.dims;
     }
 }
 export class ImageElement extends SizedPDFElement {
-    constructor({ image, width, height, fit = BoxFit.none, radius, alt }) {
+    constructor({ image, width, height, widthFactor, heightFactor, fit = BoxFit.none, radius, alt, }) {
+        // Seed this.width/height from the request so getProps() reflects it before layout; calculateLayout
+        // then reads `requested` (never the mutated fields) and overwrites these with the laid-out size.
         super({ x: 0, y: 0, width });
         this.image = image;
         this.height = height;
+        this.requested = { width, height };
+        this.widthFactor = widthFactor;
+        this.heightFactor = heightFactor;
         this.fit = fit;
         this.radius = radius ?? 0;
         this.alt = alt;
     }
+    /**
+     * Loads the image and records its intrinsic pixel size. Runs in the async pre-layout pass (layout
+     * itself is synchronous and cannot await jimp) so `calculateLayout` can turn a width-only image
+     * into a proportional box. Best-effort: a load failure leaves the size unresolved (the renderer
+     * surfaces the real error) and the image just keeps whatever explicit size it was given.
+     */
+    async resolveIntrinsicSize() {
+        try {
+            await this.image.init();
+            this.intrinsic = await this.image.getImageDimensions();
+        }
+        catch {
+            // leave intrinsic undefined - aspect derivation simply doesn't fire
+        }
+    }
+    relativeSizeFactor(horizontal) {
+        return horizontal ? this.widthFactor : this.heightFactor;
+    }
     calculateLayout(constraints, offset, _ctx) {
         this.x = offset.x;
         this.y = offset.y;
-        // A bounded axis overrides the intrinsic/explicit size; otherwise keep our own.
-        if (constraints.hasBoundedWidth)
-            this.width = constraints.maxWidth;
-        if (constraints.hasBoundedHeight)
-            this.height = constraints.maxHeight;
+        // Relative sizing: a fixed size or a fraction of the offered box (fraction only in a bounded axis).
+        // Read from `requested` (not this.width/height, which we overwrite below) so every pass re-resolves.
+        let w = resolveExtent(this.requested.width, this.widthFactor, constraints.maxWidth, constraints.hasBoundedWidth);
+        let h = resolveExtent(this.requested.height, this.heightFactor, constraints.maxHeight, constraints.hasBoundedHeight);
+        // Aspect auto-size: when the user pinned exactly ONE axis, derive the other from the intrinsic
+        // ratio (CSS `width: 50%; height: auto`). Only fires once the pre-pass resolved the pixel size.
+        if (this.intrinsic && this.intrinsic.width > 0 && this.intrinsic.height > 0) {
+            const ratio = this.intrinsic.width / this.intrinsic.height;
+            if (w !== undefined && h === undefined)
+                h = w / ratio;
+            else if (h !== undefined && w === undefined)
+                w = h * ratio;
+        }
+        // Fall back to the prior behavior for an unpinned axis: a bounded axis fills, otherwise keep the
+        // requested fixed size (or undefined). Read from `requested`, never the mutated this.width/height.
+        this.width = w ?? (constraints.hasBoundedWidth ? constraints.maxWidth : this.requested.width);
+        this.height =
+            h ?? (constraints.hasBoundedHeight ? constraints.maxHeight : this.requested.height);
         // Top-left coordinates; the fit logic (renderer) and the Y-flip (seam) run later.
         return { width: this.width ?? 0, height: this.height ?? 0 };
     }

package/dist/elements/index.d.ts

@@ -8,5 +8,11 @@ export * from "./layout/expanded-element.js";
 export * from "./layout/padding-element.js";
 export * from "./layout/default-text-style-element.js";
 export * from "./layout/positioned-element.js";
+export * from "./layout/link-element.js";
+export * from "./layout/bookmark-element.js";
+export * from "./layout/anchor-element.js";
+export * from "./layout/page-builder-element.js";
+export * from "./layout/rotated-element.js";
+export * from "./layout/rotated-box-element.js";
 export * from "./line-element.js";
 export * from "./row-element.js";

package/dist/elements/index.js

@@ -8,5 +8,11 @@ export * from "./layout/expanded-element.js";
 export * from "./layout/padding-element.js";
 export * from "./layout/default-text-style-element.js";
 export * from "./layout/positioned-element.js";
+export * from "./layout/link-element.js";
+export * from "./layout/bookmark-element.js";
+export * from "./layout/anchor-element.js";
+export * from "./layout/page-builder-element.js";
+export * from "./layout/rotated-element.js";
+export * from "./layout/rotated-box-element.js";
 export * from "./line-element.js";
 export * from "./row-element.js";

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

@@ -0,0 +1,23 @@
+import { PDFElement, LayoutContext } from "../pdf-element.js";
+import { BoxConstraints, Offset, Size } from "../../layout/box-constraints.js";
+/**
+ * Marks its child as a named jump target for an internal `Link({ to: name })`. Layout-transparent: it
+ * delegates `calculateLayout` to the child and records the child's top, which the renderer turns into an
+ * `Anchor` IR node (and PDFRenderer into a /Names /Dests entry). It draws nothing - the child renders
+ * exactly as it would on its own.
+ */
+export declare class AnchorElement extends PDFElement {
+    private name;
+    private child;
+    private y;
+    constructor({ name, child }: {
+        name: string;
+        child: PDFElement;
+    });
+    calculateLayout(constraints: BoxConstraints, offset: Offset, ctx: LayoutContext): Size;
+    getProps(): {
+        name: string;
+        child: PDFElement;
+        y: number;
+    };
+}

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

@@ -0,0 +1,27 @@
+import { PDFElement } from "../pdf-element.js";
+/**
+ * Marks its child as a named jump target for an internal `Link({ to: name })`. Layout-transparent: it
+ * delegates `calculateLayout` to the child and records the child's top, which the renderer turns into an
+ * `Anchor` IR node (and PDFRenderer into a /Names /Dests entry). It draws nothing - the child renders
+ * exactly as it would on its own.
+ */
+export class AnchorElement extends PDFElement {
+    constructor({ name, child }) {
+        super();
+        this.y = 0;
+        this.name = name;
+        this.child = child;
+    }
+    calculateLayout(constraints, offset, ctx) {
+        const size = this.child.calculateLayout(constraints, offset, ctx);
+        this.y = offset.y; // the child's top - the scroll target for a link that jumps here
+        return size;
+    }
+    getProps() {
+        return {
+            name: this.name,
+            child: this.child,
+            y: this.y,
+        };
+    }
+}

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

@@ -0,0 +1,27 @@
+import { PDFElement, LayoutContext } from "../pdf-element.js";
+import { BoxConstraints, Offset, Size } from "../../layout/box-constraints.js";
+/**
+ * Adds a document-outline entry (a bookmark) that jumps to its child. Layout-transparent: it delegates
+ * `calculateLayout` to the child and records the child's top, which the renderer turns into an `Outline`
+ * IR node (and PDFRenderer into a /Outlines tree entry). `title` is the label shown in the viewer's
+ * bookmark panel; `level` (1-based, default 1) nests it under the nearest preceding smaller level. It
+ * draws nothing - the child renders exactly as it would without the bookmark.
+ */
+export declare class BookmarkElement extends PDFElement {
+    private title;
+    private level;
+    private child;
+    private y;
+    constructor({ title, level, child }: {
+        title: string;
+        level?: number;
+        child: PDFElement;
+    });
+    calculateLayout(constraints: BoxConstraints, offset: Offset, ctx: LayoutContext): Size;
+    getProps(): {
+        title: string;
+        level: number;
+        child: PDFElement;
+        y: number;
+    };
+}

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

@@ -0,0 +1,30 @@
+import { PDFElement } from "../pdf-element.js";
+/**
+ * Adds a document-outline entry (a bookmark) that jumps to its child. Layout-transparent: it delegates
+ * `calculateLayout` to the child and records the child's top, which the renderer turns into an `Outline`
+ * IR node (and PDFRenderer into a /Outlines tree entry). `title` is the label shown in the viewer's
+ * bookmark panel; `level` (1-based, default 1) nests it under the nearest preceding smaller level. It
+ * draws nothing - the child renders exactly as it would without the bookmark.
+ */
+export class BookmarkElement extends PDFElement {
+    constructor({ title, level = 1, child }) {
+        super();
+        this.y = 0;
+        this.title = title;
+        this.level = level;
+        this.child = child;
+    }
+    calculateLayout(constraints, offset, ctx) {
+        const size = this.child.calculateLayout(constraints, offset, ctx);
+        this.y = offset.y; // the child's top - the scroll target for the bookmark
+        return size;
+    }
+    getProps() {
+        return {
+            title: this.title,
+            level: this.level,
+            child: this.child,
+            y: this.y,
+        };
+    }
+}

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

@@ -0,0 +1,33 @@
+import { PDFElement, LayoutContext } from "../pdf-element.js";
+import { BoxConstraints, Offset, Size } from "../../layout/box-constraints.js";
+/**
+ * Makes its child a clickable hyperlink. `href` is an external URL; `dest` is an internal named
+ * destination (an `Anchor` elsewhere in the document) - exactly one is set. Layout-transparent: it
+ * delegates `calculateLayout` to the child and records the resulting box, which the renderer turns into
+ * a `Link` IR node (and the page renderer into a /Link annotation). The link draws nothing itself -
+ * style the child (e.g. a blue Text) if you want it to look like a link.
+ */
+export declare class LinkElement extends PDFElement {
+    private href?;
+    private dest?;
+    private child;
+    private x;
+    private y;
+    private width;
+    private height;
+    constructor({ href, dest, child }: {
+        href?: string;
+        dest?: string;
+        child: PDFElement;
+    });
+    calculateLayout(constraints: BoxConstraints, offset: Offset, ctx: LayoutContext): Size;
+    getProps(): {
+        href: string | undefined;
+        dest: string | undefined;
+        child: PDFElement;
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}

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

@@ -0,0 +1,39 @@
+import { PDFElement } from "../pdf-element.js";
+/**
+ * Makes its child a clickable hyperlink. `href` is an external URL; `dest` is an internal named
+ * destination (an `Anchor` elsewhere in the document) - exactly one is set. Layout-transparent: it
+ * delegates `calculateLayout` to the child and records the resulting box, which the renderer turns into
+ * a `Link` IR node (and the page renderer into a /Link annotation). The link draws nothing itself -
+ * style the child (e.g. a blue Text) if you want it to look like a link.
+ */
+export class LinkElement extends PDFElement {
+    constructor({ href, dest, child }) {
+        super();
+        this.x = 0;
+        this.y = 0;
+        this.width = 0;
+        this.height = 0;
+        this.href = href;
+        this.dest = dest;
+        this.child = child;
+    }
+    calculateLayout(constraints, offset, ctx) {
+        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 {
+            href: this.href,
+            dest: this.dest,
+            child: this.child,
+            x: this.x,
+            y: this.y,
+            width: this.width,
+            height: this.height,
+        };
+    }
+}

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

@@ -0,0 +1,32 @@
+import { BoxConstraints, Offset, Size } from "../../layout/box-constraints.js";
+import { LayoutContext, PageInfo, PDFElement } from "../pdf-element.js";
+/**
+ * Builds its subtree from the page it lands on, so a header, a footer or plain body content can show
+ * `pageNumber` / `pageCount`. The closure runs on EVERY layout, because the numbers differ between the
+ * two driver passes: pagination has to size the element before the page total exists, so it builds
+ * against a provisional "1 of 1"; the render pass then rebuilds it with the real `PageInfo`.
+ *
+ * Two consequences, and neither is magic - both come from the same chicken-and-egg: the content decides
+ * the page count that the content displays.
+ *
+ * 1. In the flowing BODY the box is reserved by the provisional build, so a much wider final string
+ *    (`"9 of 10"` vs `"1 of 1"`) can paint slightly past it. Keep dynamic body content roughly constant
+ *    in width.
+ * 2. A header/footer is re-laid out per page, so its real height is honoured - but the BODY band was
+ *    already sized against the provisional build. A later page whose header is SHORTER simply gains
+ *    room (harmless). A later page whose header is TALLER shrinks the band its body was measured for,
+ *    and that body can overflow. So: a conditional header may shrink on later pages, never grow.
+ */
+export declare class PageBuilderElement extends PDFElement {
+    private composed?;
+    private readonly build;
+    constructor({ build }: {
+        build: (info: PageInfo) => PDFElement;
+    });
+    /** The real page info during the render pass; a provisional "1 of 1" while paginating. */
+    private infoFrom;
+    calculateLayout(constraints: BoxConstraints, offset: Offset, ctx: LayoutContext): Size;
+    getProps(): {
+        composed: PDFElement | undefined;
+    };
+}

package/dist/elements/layout/page-builder-element.js

@@ -0,0 +1,43 @@
+import { PDFElement } from "../pdf-element.js";
+import { resolvePageSize } from "../page-element.js";
+/**
+ * Builds its subtree from the page it lands on, so a header, a footer or plain body content can show
+ * `pageNumber` / `pageCount`. The closure runs on EVERY layout, because the numbers differ between the
+ * two driver passes: pagination has to size the element before the page total exists, so it builds
+ * against a provisional "1 of 1"; the render pass then rebuilds it with the real `PageInfo`.
+ *
+ * Two consequences, and neither is magic - both come from the same chicken-and-egg: the content decides
+ * the page count that the content displays.
+ *
+ * 1. In the flowing BODY the box is reserved by the provisional build, so a much wider final string
+ *    (`"9 of 10"` vs `"1 of 1"`) can paint slightly past it. Keep dynamic body content roughly constant
+ *    in width.
+ * 2. A header/footer is re-laid out per page, so its real height is honoured - but the BODY band was
+ *    already sized against the provisional build. A later page whose header is SHORTER simply gains
+ *    room (harmless). A later page whose header is TALLER shrinks the band its body was measured for,
+ *    and that body can overflow. So: a conditional header may shrink on later pages, never grow.
+ */
+export class PageBuilderElement extends PDFElement {
+    constructor({ build }) {
+        super();
+        this.build = build;
+    }
+    /** The real page info during the render pass; a provisional "1 of 1" while paginating. */
+    infoFrom(ctx) {
+        return (ctx.pageInfo ?? {
+            pageNumber: 1,
+            pageCount: 1,
+            pageSize: resolvePageSize(ctx.pageConfig),
+        });
+    }
+    calculateLayout(constraints, offset, ctx) {
+        this.composed = this.build(this.infoFrom(ctx));
+        return this.composed.calculateLayout(constraints, offset, ctx);
+    }
+    // Named `composed` (not `child`) like DeferredElement: the pre-layout image walk keys on `child`, and
+    // this subtree does not exist yet when it runs. So an Image inside a PageBuilder skips aspect-ratio
+    // pre-resolution - give it both width and height, exactly as inside a Deferred/Table subtree.
+    getProps() {
+        return { composed: this.composed };
+    }
+}

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

@@ -0,0 +1,35 @@
+import { PDFElement, LayoutContext } from "../pdf-element.js";
+import { BoxConstraints, Offset, Size } from "../../layout/box-constraints.js";
+/**
+ * Rotates its child by whole quarter-turns and, unlike `RotatedElement` (paint-only), makes the
+ * rotation LAYOUT-AWARE: for a 90 / 270 turn it SWAPS width and height, so the box reports the rotated
+ * footprint UP and siblings reflow around it. A tall text becomes a narrow vertical strip that actually
+ * reserves its narrow width and its long height - the "vertical label beside a table" case.
+ *
+ * `turns` is the number of 90-degree CLOCKWISE quarter-turns (like Flutter's `RotatedBox.quarterTurns`):
+ * 0 = none, 1 = 90, 2 = 180, 3 = 270. The child lays out with the box's constraints swapped, then it is
+ * placed centered on the box's center so a plain center-rotation (the shared renderer) maps it exactly
+ * onto the swapped box.
+ */
+export declare class RotatedBoxElement extends PDFElement {
+    private turns;
+    private child;
+    private x;
+    private y;
+    private width;
+    private height;
+    constructor({ turns, child }: {
+        turns: number;
+        child: PDFElement;
+    });
+    calculateLayout(constraints: BoxConstraints, offset: Offset, ctx: LayoutContext): Size;
+    /** Same shape as `RotatedElement` (angle + box), so both share `RotatedRenderer`. */
+    getProps(): {
+        angle: number;
+        child: PDFElement;
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}

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

@@ -0,0 +1,54 @@
+import { PDFElement } from "../pdf-element.js";
+import { BoxConstraints } from "../../layout/box-constraints.js";
+/**
+ * Rotates its child by whole quarter-turns and, unlike `RotatedElement` (paint-only), makes the
+ * rotation LAYOUT-AWARE: for a 90 / 270 turn it SWAPS width and height, so the box reports the rotated
+ * footprint UP and siblings reflow around it. A tall text becomes a narrow vertical strip that actually
+ * reserves its narrow width and its long height - the "vertical label beside a table" case.
+ *
+ * `turns` is the number of 90-degree CLOCKWISE quarter-turns (like Flutter's `RotatedBox.quarterTurns`):
+ * 0 = none, 1 = 90, 2 = 180, 3 = 270. The child lays out with the box's constraints swapped, then it is
+ * placed centered on the box's center so a plain center-rotation (the shared renderer) maps it exactly
+ * onto the swapped box.
+ */
+export class RotatedBoxElement extends PDFElement {
+    constructor({ turns, child }) {
+        super();
+        this.x = 0;
+        this.y = 0;
+        this.width = 0;
+        this.height = 0;
+        this.turns = ((Math.trunc(turns) % 4) + 4) % 4;
+        this.child = child;
+    }
+    calculateLayout(constraints, offset, ctx) {
+        const quarter = this.turns % 2 === 1; // 90 or 270: axes swap
+        // A quarter-turned child experiences the box's constraints with the axes swapped.
+        const childConstraints = quarter
+            ? new BoxConstraints(constraints.minHeight, constraints.maxHeight, constraints.minWidth, constraints.maxWidth)
+            : constraints;
+        // Measure the child to learn its natural size, then take that size swapped as our own box.
+        const child = this.child.calculateLayout(childConstraints, offset, ctx);
+        this.width = quarter ? child.height : child.width;
+        this.height = quarter ? child.width : child.height;
+        this.x = offset.x;
+        this.y = offset.y;
+        // Re-place the child CENTERED on the box center: a rotation around that center then maps the
+        // child's (w x h) box exactly onto our (swapped) box - so the shared renderer needs no special case.
+        const cx = this.x + this.width / 2;
+        const cy = this.y + this.height / 2;
+        this.child.calculateLayout(childConstraints, { x: cx - child.width / 2, y: cy - child.height / 2 }, ctx);
+        return { width: this.width, height: this.height };
+    }
+    /** Same shape as `RotatedElement` (angle + box), so both share `RotatedRenderer`. */
+    getProps() {
+        return {
+            angle: this.turns * 90,
+            child: this.child,
+            x: this.x,
+            y: this.y,
+            width: this.width,
+            height: this.height,
+        };
+    }
+}