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

package/dist/common/gradient.js

@@ -0,0 +1,97 @@
+import { toColor } from "./color-input.js";
+export const isGradientInput = (v) => typeof v === "object" && v !== null && "kind" in v && "stops" in v;
+/**
+ * A linear gradient. `linearGradient("#fff", "#000")` runs top to bottom; pass `{ angle }` for any
+ * other direction, and `{ color, at }` for a stop that is not evenly spaced.
+ */
+export function linearGradient(...args) {
+    const first = args[0];
+    if (args.length === 1 && typeof first === "object" && first !== null && "stops" in first) {
+        return { kind: "linear", angle: first.angle ?? 180, stops: first.stops };
+    }
+    return { kind: "linear", angle: 180, stops: args };
+}
+/** A radial gradient, centred by default and reaching the edges. */
+export function radialGradient(...args) {
+    const first = args[0];
+    if (args.length === 1 && typeof first === "object" && first !== null && "stops" in first) {
+        return {
+            kind: "radial",
+            center: first.center ?? [0.5, 0.5],
+            radius: first.radius ?? 0.5,
+            stops: first.stops,
+        };
+    }
+    return { kind: "radial", center: [0.5, 0.5], radius: 0.5, stops: args };
+}
+/**
+ * Spread the stops that carry no `at` evenly, first to last, the way CSS does - and check the pinned
+ * ones, because they end up in a PDF stitching function's `/Bounds`, which the format requires to be
+ * strictly increasing inside the domain. A bad offset there is not a wrong-looking gradient, it is a
+ * malformed file, so it is refused by name here rather than emitted.
+ */
+function toStops(stops) {
+    if (stops.length < 2) {
+        throw new Error("A gradient needs at least two colour stops.");
+    }
+    const last = stops.length - 1;
+    const out = stops.map((s, i) => {
+        const pinned = typeof s === "object" && s !== null && "at" in s;
+        const at = pinned ? s.at : i / last;
+        if (!Number.isFinite(at) || at < 0 || at > 1) {
+            throw new Error(`Invalid gradient stop position ${at}: it must be a number between 0 and 1.`);
+        }
+        return {
+            offset: at,
+            color: toColor(pinned ? s.color : s),
+        };
+    });
+    for (let i = 1; i < out.length; i++) {
+        if (out[i].offset <= out[i - 1].offset) {
+            throw new Error(`Gradient stops must move forward: stop ${i} sits at ${out[i].offset}, which is not after ` +
+                `${out[i - 1].offset}. (Two stops at the SAME position would be a hard colour edge in CSS; ` +
+                `PDF cannot express that in one shading, so it is refused rather than drawn wrongly.)`);
+        }
+    }
+    // A pinned first or last stop would otherwise be IGNORED - the shading's domain is always 0..1 and
+    // only the INTERIOR offsets reach /Bounds. Carrying the edge colour outwards is what CSS does.
+    if (out[0].offset > 0)
+        out.unshift({ offset: 0, color: out[0].color });
+    if (out[out.length - 1].offset < 1)
+        out.push({ offset: 1, color: out[out.length - 1].color });
+    return out;
+}
+/**
+ * Resolve a box-relative gradient against the box it paints, into the absolute page coordinates the
+ * IR wants. Called by the renderer, which is the first place the box's geometry is known.
+ *
+ * The angle follows CSS: 0 points to the top and it turns clockwise, so 90 goes to the right. The
+ * axis runs through the box centre and is scaled so it spans the box on that diagonal - which is why
+ * a 45-degree gradient reaches the corners rather than stopping short of them.
+ */
+export function resolveGradient(g, x, y, width, height) {
+    const stops = toStops(g.stops);
+    if (g.kind === "radial") {
+        const cx = x + g.center[0] * width;
+        const cy = y + g.center[1] * height;
+        const r = g.radius * Math.max(width, height);
+        return { type: "radial", x0: cx, y0: cy, r0: 0, x1: cx, y1: cy, r1: r, stops, extend: "pad" };
+    }
+    const rad = ((g.angle % 360) * Math.PI) / 180;
+    // CSS angles: 0 = up, clockwise. The engine lays out top-left down, so "up" is -y here.
+    const dx = Math.sin(rad);
+    const dy = -Math.cos(rad);
+    // Half the box's extent along the axis, so the line covers the whole box for any angle.
+    const half = (Math.abs(dx) * width + Math.abs(dy) * height) / 2;
+    const cx = x + width / 2;
+    const cy = y + height / 2;
+    return {
+        type: "linear",
+        x0: cx - dx * half,
+        y0: cy - dy * half,
+        x1: cx + dx * half,
+        y1: cy + dy * half,
+        stops,
+        extend: "pad",
+    };
+}

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

@@ -63,6 +63,7 @@ export declare class ContainerElement extends SizedPDFElement implements Fragmen
     fragment(maxHeight: number, width: number, ctx: LayoutContext): FragmentResult;
     private cloneWithChildren;
     relativeSizeFactor(horizontal: boolean): number | undefined;
+    maxExtent(horizontal: boolean): number;
     /**
      * 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
@@ -74,6 +75,8 @@ export declare class ContainerElement extends SizedPDFElement implements Fragmen
      * every existing layout untouched.
      */
     needsBoundedMain(horizontal: boolean): boolean;
+    /** A height of its own is a region already; without one, a region-sized child needs the page's. */
+    needsRegion(): boolean;
     /** A Column stacks vertically, so widths overlap and heights add up. */
     minIntrinsicMain(horizontal: boolean, ctx: LayoutContext): number;
     calculateLayout(constraints: BoxConstraints, offset: Offset, ctx: LayoutContext): Size;

package/dist/elements/container-element.js

@@ -3,8 +3,8 @@ import { flexibleOf } from "../layout/flex-item.js";
 import { FlexLayoutHelper, VERTICAL_AXIS, } from "../utils/flex-layout.js";
 import { stackMinIntrinsic, withDeclaredExtent } from "../layout/min-intrinsic.js";
 import { BoxConstraints, extentSpecs, resolveSize, } from "../layout/box-constraints.js";
-import { childrenForceBreak, packChildren, } from "../layout/fragmentation.js";
-import { SizedPDFElement, } from "./pdf-element.js";
+import { childrenForceBreak, packChildren, packedUnchanged, } from "../layout/fragmentation.js";
+import { SizedPDFElement, withPaddingBase, } from "./pdf-element.js";
 export class ContainerElement extends SizedPDFElement {
     constructor({ x, y, width, height, children, gap, main, cross, reverse, wrap, alignContent, breakBefore, breakAfter, ...sizing }) {
         super({ x, y, width, height });
@@ -45,13 +45,14 @@ export class ContainerElement extends SizedPDFElement {
         // Pack at the width the column is drawn at: its own rules (fixed, %, min/max) resolved against the
         // region, the same sizing path as `measure`. A narrower column has taller children.
         const ownWidth = this.measure(BoxConstraints.loose(width, Infinity), ctx).width;
-        const { fitted, remainder, forceBreak } = packChildren(this.children, maxHeight, ownWidth, ctx, this.gap);
+        const { fitted, remainder, forceBreak } = packChildren(this.children, maxHeight, ownWidth, withPaddingBase(ctx, undefined), this.gap);
         // Fits as one region with no forced cut: hand the whole container back so the page renders
         // unchanged (its normal layout distributes flex / fills the page). A forced break is excluded
         // here even when nothing follows it (a trailing `PageBreak`): return the packed children, which
         // no longer hold the consumed break marker, so it does not leak into the render pass.
-        if (remainder.length === 0 && !forceBreak)
+        if (remainder.length === 0 && !forceBreak && packedUnchanged(this.children, fitted)) {
             return { fitted: this, remainder: null };
+        }
         // Nothing fit below the content above: move on whole, not as an empty shell left behind.
         if (fitted.length === 0 && !forceBreak)
             return { fitted: null, remainder: this };
@@ -84,6 +85,9 @@ export class ContainerElement extends SizedPDFElement {
     relativeSizeFactor(horizontal) {
         return horizontal ? this.requested.widthFactor : this.requested.heightFactor;
     }
+    maxExtent(horizontal) {
+        return (horizontal ? this.requested.maxWidth : this.requested.maxHeight) ?? Infinity;
+    }
     /**
      * 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
@@ -103,6 +107,12 @@ export class ContainerElement extends SizedPDFElement {
         const ownFlexChild = !horizontal && this.children.some((c) => flexibleOf(c) !== undefined);
         return ownFlexChild || this.children.some((c) => c.needsBoundedMain(horizontal));
     }
+    /** A height of its own is a region already; without one, a region-sized child needs the page's. */
+    needsRegion() {
+        if (this.requested.height !== undefined || this.requested.heightFactor !== undefined)
+            return false;
+        return this.children.some((c) => c.needsRegion());
+    }
     /** A Column stacks vertically, so widths overlap and heights add up. */
     minIntrinsicMain(horizontal, ctx) {
         const content = stackMinIntrinsic(this.children, this.gap, !horizontal, horizontal, ctx, this.wrap);
@@ -153,7 +163,9 @@ export class ContainerElement extends SizedPDFElement {
                 reverse: this.reverse,
                 wrap: this.wrap,
                 alignContent: this.alignContent,
-            }, ctx, mode);
+            }, 
+            // A Row's width is for its own children; these resolve against this column, what it offers.
+            withPaddingBase(ctx, undefined), mode);
         }
         // 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

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

@@ -1,4 +1,5 @@
 import type { Radii } from "../ir/display-list.js";
+import { type FitAlign, type ImageDimensions } from "../utils/image-helper.js";
 import { BoxConstraints, Offset, Size } from "../layout/box-constraints.js";
 import { LayoutContext, SizedPDFElement } from "./pdf-element.js";
 export declare enum BoxFit {
@@ -12,25 +13,29 @@ export declare abstract class CustomImage {
     abstract init(fresh?: boolean): void | Promise<void>;
     abstract getImageType(): string | Promise<string>;
     abstract getFileData(): string | Promise<string>;
-    abstract getImageDimensions(): Promise<{
-        width: number;
-        height: number;
-    }>;
+    abstract getImageDimensions(): Promise<ImageDimensions>;
+    /**
+     * Its dimensions if its bytes are already in hand (bytes, a local file), else `undefined` - then the
+     * async pass before layout fetches them. Reading a header from memory is all this may do: layout
+     * asks it, so an image built during layout (in a `PageBuilder`, a table cell) knows its size too.
+     */
+    dimensionsNow(): ImageDimensions | undefined;
 }
+/**
+ * An image from a file path (Node). The file is read HERE, when the image is named - like an SVG or a
+ * font file - so a wrong path fails on the line that named it, and layout never waits on a disk.
+ */
 export declare class CustomLocalImage extends CustomImage {
     private imagePath;
     private fileBuffer;
     private fileRawData;
     private dims?;
     constructor(imagePath: string);
-    init(): Promise<void>;
+    init(): void;
     getImageType(): Promise<string>;
-    private loadImage;
+    dimensionsNow(): ImageDimensions | undefined;
     getFileData(): string;
-    getImageDimensions(): Promise<{
-        width: number;
-        height: number;
-    }>;
+    getImageDimensions(): Promise<ImageDimensions>;
 }
 /**
  * An image straight from raw bytes (a browser upload / fetch, no filesystem). The PDF filter is sniffed
@@ -44,10 +49,8 @@ export declare class CustomBytesImage extends CustomImage {
     init(): Promise<void>;
     getImageType(): Promise<string>;
     getFileData(): string;
-    getImageDimensions(): Promise<{
-        width: number;
-        height: number;
-    }>;
+    getImageDimensions(): Promise<ImageDimensions>;
+    dimensionsNow(): ImageDimensions | undefined;
 }
 /** Thrown when an image could not be fetched or is not one we can embed. Always says which URL. */
 export declare class ImageUrlError extends Error {
@@ -76,10 +79,8 @@ export declare class CustomUrlImage extends CustomImage {
     private image;
     getImageType(): Promise<string>;
     getFileData(): string;
-    getImageDimensions(): Promise<{
-        width: number;
-        height: number;
-    }>;
+    getImageDimensions(): Promise<ImageDimensions>;
+    dimensionsNow(): ImageDimensions | undefined;
 }
 interface ImageElementParams {
     image: CustomImage;
@@ -100,9 +101,12 @@ interface ImageElementParams {
     maxHeightFactor?: number;
     /** width / height; overrides the image's OWN ratio (CSS `aspect-ratio`), `fit` then places it. */
     aspectRatio?: number;
+    /** How the image fills its box (CSS `object-fit`); `fill` by default, as in CSS. */
     fit?: BoxFit;
     /** Corner radius in points - one number or per corner; rounds the image box (0 = sharp, default). */
     radius?: number | Radii;
+    /** Where the image sits in its box when `fit` leaves space or cuts it: 0 = start, 1 = end per axis. */
+    align?: FitAlign;
     /** Alternate text for accessibility (tagged PDF). With `alt` the image is a Figure; without, decoration. */
     alt?: string;
 }
@@ -112,25 +116,31 @@ export declare class ImageElement extends SizedPDFElement {
     private heightFactor?;
     private fit;
     private radius;
+    private align?;
     private readonly alt?;
     private requested;
     /** min/max/aspectRatio, kept as given so every layout pass re-resolves them. */
     private sizing;
     private intrinsic?;
-    constructor({ image, width, height, widthFactor, heightFactor, fit, radius, alt, ...sizing }: ImageElementParams);
+    constructor({ image, width, height, widthFactor, heightFactor, fit, radius, align, alt, ...sizing }: 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.
+     * Fetches what layout cannot wait for (an image from a URL) and records its own size. Runs in the
+     * async pass before layout; an image whose bytes are in hand has nothing to fetch. Best-effort: a
+     * failed fetch leaves the size unresolved (the renderer surfaces the real error) and the image keeps
+     * whatever explicit size it was given.
      */
     resolveIntrinsicSize(): Promise<void>;
+    /** Its own size in points: known now, or resolved by the pass before layout; `undefined` if neither. */
+    private ownSize;
     relativeSizeFactor(horizontal: boolean): number | undefined;
-    calculateLayout(constraints: BoxConstraints, offset: Offset, _ctx: LayoutContext): Size;
+    calculateLayout(constraints: BoxConstraints, offset: Offset, ctx: LayoutContext): Size;
     protected computeSize(constraints: BoxConstraints): Size;
-    /** Its size under these constraints - the one computation both `measure` and layout use. */
+    /** Its size was needed from the file and the file had not been read: say so, rather than draw it wrong. */
+    private reportUnsized;
+    /** Its size under these constraints - the one computation both `measure` and layout use. `guessed`:
+     *  a side that would have followed the file's own size did not, because that size was unknown. */
     private sizeFor;
-    /** The image's own pixel extent on one axis, clamped by its min/max; unknown before the pre-pass. */
+    /** The image's own extent on one axis, clamped by its min/max; unknown before the pre-pass. */
     private ownExtent;
     getProps(): {
         x: number;
@@ -140,6 +150,7 @@ export declare class ImageElement extends SizedPDFElement {
         image: CustomImage;
         fit: BoxFit;
         radius: number | Radii;
+        align: FitAlign | undefined;
         alt: string | undefined;
     };
 }

package/dist/elements/image-element.js

@@ -1,9 +1,10 @@
-import { getImageDimensions } from "../utils/image-helper.js";
+import { readImageDimensions, naturalSize, } from "../utils/image-helper.js";
 import { latin1FromBytes } from "../utils/bytes.js";
-import { readFileBytesAsync } from "../platform/node-fs.js";
+import { readFileBytes } from "../platform/node-fs.js";
 import { fetchBytes } from "../utils/fetch-bytes.js";
-import { extentSpecs, resolveSize, } from "../layout/box-constraints.js";
+import { extentSpecs, resolveSize, sizeAtOwnRatio, } from "../layout/box-constraints.js";
 import { SizedPDFElement } from "./pdf-element.js";
+import { diagnose, pageOf } from "../common/diagnostics.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.
 function extname(p) {
@@ -19,22 +20,41 @@ export var BoxFit;
     BoxFit["fill"] = "FILL";
 })(BoxFit || (BoxFit = {}));
 export class CustomImage {
+    /**
+     * Its dimensions if its bytes are already in hand (bytes, a local file), else `undefined` - then the
+     * async pass before layout fetches them. Reading a header from memory is all this may do: layout
+     * asks it, so an image built during layout (in a `PageBuilder`, a table cell) knows its size too.
+     */
+    dimensionsNow() {
+        return undefined;
+    }
 }
+/** Dimensions read from bytes in hand; a format we cannot read is `undefined` here - the render names it. */
+function headerOf(bytes) {
+    try {
+        return readImageDimensions(bytes);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * An image from a file path (Node). The file is read HERE, when the image is named - like an SVG or a
+ * font file - so a wrong path fails on the line that named it, and layout never waits on a disk.
+ */
 export class CustomLocalImage extends CustomImage {
     constructor(imagePath) {
         super();
         this.imagePath = imagePath;
-    }
-    async init() {
-        if (this.fileBuffer)
-            return; // idempotent: the pre-layout size pass and the renderer both call init()
         try {
-            await this.loadImage(this.imagePath);
+            this.fileBuffer = readFileBytes(imagePath);
         }
         catch (e) {
-            throw new Error(`@jasy/pdf: could not read the image at ${this.imagePath}: ${String(e?.message ?? e)}`);
+            throw new Error(`@jasy/pdf: could not read the image at ${imagePath}: ${String(e?.message ?? e)}`);
         }
+        this.fileRawData = latin1FromBytes(this.fileBuffer);
     }
+    init() { }
     async getImageType() {
         const ext = extname(this.imagePath).toLowerCase();
         switch (ext) {
@@ -51,22 +71,15 @@ export class CustomLocalImage extends CustomImage {
                 throw new Error(`Unsupported image format: ${ext}`);
         }
     }
-    async loadImage(imagePath) {
-        const result = await readFileBytesAsync(imagePath);
-        //const result = await convertImageToGrayscaleBuffer(imagePath);
-        this.fileBuffer = result;
-        this.fileRawData = latin1FromBytes(result);
-        return result;
+    dimensionsNow() {
+        this.dims ?? (this.dims = headerOf(this.fileBuffer));
+        return this.dims;
     }
     getFileData() {
         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("@jasy/pdf: an image was measured before it was loaded");
-        this.dims = await getImageDimensions(this.fileBuffer);
+        this.dims ?? (this.dims = readImageDimensions(this.fileBuffer)); // reuse across layout + render
         return this.dims;
     }
 }
@@ -93,8 +106,11 @@ export class CustomBytesImage extends CustomImage {
         return this.fileRawData;
     }
     async getImageDimensions() {
-        if (!this.dims)
-            this.dims = await getImageDimensions(this.bytes); // reuse across pre-pass + render
+        this.dims ?? (this.dims = readImageDimensions(this.bytes)); // reuse across layout + render
+        return this.dims;
+    }
+    dimensionsNow() {
+        this.dims ?? (this.dims = headerOf(this.bytes));
         return this.dims;
     }
 }
@@ -155,9 +171,12 @@ export class CustomUrlImage extends CustomImage {
     getImageDimensions() {
         return this.image().getImageDimensions();
     }
+    dimensionsNow() {
+        return this.loaded?.dimensionsNow();
+    }
 }
 export class ImageElement extends SizedPDFElement {
-    constructor({ image, width, height, widthFactor, heightFactor, fit = BoxFit.none, radius, alt, ...sizing }) {
+    constructor({ image, width, height, widthFactor, heightFactor, fit = BoxFit.fill, radius, align, alt, ...sizing }) {
         // 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 });
@@ -169,28 +188,42 @@ export class ImageElement extends SizedPDFElement {
         this.sizing = sizing;
         this.fit = fit;
         this.radius = radius ?? 0;
+        this.align = align;
         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.
+     * Fetches what layout cannot wait for (an image from a URL) and records its own size. Runs in the
+     * async pass before layout; an image whose bytes are in hand has nothing to fetch. Best-effort: a
+     * failed fetch leaves the size unresolved (the renderer surfaces the real error) and the image keeps
+     * whatever explicit size it was given.
      */
     async resolveIntrinsicSize() {
+        if (this.ownSize())
+            return;
         try {
             await this.image.init(true); // a render begins here
-            this.intrinsic = await this.image.getImageDimensions();
+            this.intrinsic = naturalSize(await this.image.getImageDimensions());
         }
         catch {
             // leave intrinsic undefined - aspect derivation simply doesn't fire
         }
     }
+    /** Its own size in points: known now, or resolved by the pass before layout; `undefined` if neither. */
+    ownSize() {
+        if (!this.intrinsic) {
+            const dims = this.image.dimensionsNow();
+            if (dims)
+                this.intrinsic = naturalSize(dims);
+        }
+        return this.intrinsic;
+    }
     relativeSizeFactor(horizontal) {
         return horizontal ? this.widthFactor : this.heightFactor;
     }
-    calculateLayout(constraints, offset, _ctx) {
+    calculateLayout(constraints, offset, ctx) {
         const size = this.sizeFor(constraints);
+        if (size.guessed)
+            this.reportUnsized(ctx);
         this.x = offset.x;
         this.y = offset.y;
         // Kept as resolved, `undefined` included: the renderer reads an unset axis differently from 0.
@@ -202,7 +235,20 @@ export class ImageElement extends SizedPDFElement {
         const size = this.sizeFor(constraints);
         return { width: size.width ?? 0, height: size.height ?? 0 };
     }
-    /** Its size under these constraints - the one computation both `measure` and layout use. */
+    /** Its size was needed from the file and the file had not been read: say so, rather than draw it wrong. */
+    reportUnsized(ctx) {
+        diagnose(ctx.diagnostics, {
+            code: "image-unsized",
+            severity: "warning",
+            message: "An image's own size was not known when it was laid out - an image from a URL that is first " +
+                "built in a PageBuilder cannot be fetched before layout. Its open side fills what it is " +
+                "offered. Give it a width and a height, or create it outside the PageBuilder.",
+            about: this,
+            page: pageOf(ctx),
+        });
+    }
+    /** Its size under these constraints - the one computation both `measure` and layout use. `guessed`:
+     *  a side that would have followed the file's own size did not, because that size was unknown. */
     sizeFor(constraints) {
         // 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.
@@ -213,28 +259,19 @@ export class ImageElement extends SizedPDFElement {
             widthFactor: this.widthFactor,
             heightFactor: this.heightFactor,
         });
-        // An explicit `aspectRatio` wins over the image's own, as it does in CSS - and only it may size a
-        // box with NEITHER axis pinned. Left to the intrinsic ratio that would change what an unsized image
-        // has always done here (fill both axes and let `fit` sort it out).
+        // An explicit `aspectRatio` wins over the image's own.
         const resolved = resolveSize(specs.width, specs.height, this.sizing.aspectRatio, constraints);
         let w = resolved.width;
         let h = resolved.height;
         const bounds = resolved.constraints;
-        // Aspect auto-size: when exactly ONE axis is pinned, derive the other from the intrinsic ratio
-        // (CSS `width: 50%; height: auto`). Only fires once the pre-pass resolved the pixel size.
-        if (this.sizing.aspectRatio === undefined &&
-            this.intrinsic &&
-            this.intrinsic.width > 0 &&
-            this.intrinsic.height > 0) {
-            const ratio = this.intrinsic.width / this.intrinsic.height;
-            if (w !== undefined && h === undefined)
-                h = bounds.constrainHeight(w / ratio);
-            else if (h !== undefined && w === undefined)
-                w = bounds.constrainWidth(h * ratio);
+        // Its own ratio fills an open axis, once the pre-pass resolved its own size.
+        const own = this.ownSize();
+        if (this.sizing.aspectRatio === undefined && own && own.width > 0 && own.height > 0) {
+            ({ width: w, height: h } = sizeAtOwnRatio(w, h, own, bounds));
         }
-        // An unpinned axis: a bounded one fills; an unbounded one takes the image's own extent (1px = 1pt) -
-        // what `fit: none` (the default) draws there, so the layout reserves exactly what is drawn. Read from
-        // `requested`, never the mutated this.width/height.
+        const guessed = own === undefined && (w === undefined || h === undefined);
+        // Still unpinned (no intrinsic size known): a bounded axis fills; an unbounded one takes the image's
+        // own extent (`naturalSize`). Read from `requested`, never the mutated this.width/height.
         const width = w ??
             (bounds.hasBoundedWidth
                 ? bounds.maxWidth
@@ -244,11 +281,11 @@ export class ImageElement extends SizedPDFElement {
                 ? bounds.maxHeight
                 : (this.requested.height ?? this.ownExtent(bounds, "height")));
         // Top-left coordinates; the fit logic (renderer) and the Y-flip (seam) run later.
-        return { width, height };
+        return { width, height, guessed };
     }
-    /** The image's own pixel extent on one axis, clamped by its min/max; unknown before the pre-pass. */
+    /** The image's own extent on one axis, clamped by its min/max; unknown before the pre-pass. */
     ownExtent(bounds, axis) {
-        const own = this.intrinsic?.[axis];
+        const own = this.ownSize()?.[axis];
         if (own === undefined)
             return undefined;
         return axis === "width" ? bounds.constrainWidth(own) : bounds.constrainHeight(own);
@@ -262,6 +299,7 @@ export class ImageElement extends SizedPDFElement {
             image: this.image,
             fit: this.fit,
             radius: this.radius,
+            align: this.align,
             alt: this.alt,
         };
     }

package/dist/elements/index.d.ts

@@ -20,6 +20,9 @@ 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/flow-element.js";
+export * from "./layout/region-element.js";
+export * from "./layout/column-break-element.js";
 export * from "./layout/rotated-element.js";
 export * from "./layout/rotated-box-element.js";
 export * from "./line-element.js";

package/dist/elements/index.js

@@ -20,6 +20,9 @@ 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/flow-element.js";
+export * from "./layout/region-element.js";
+export * from "./layout/column-break-element.js";
 export * from "./layout/rotated-element.js";
 export * from "./layout/rotated-box-element.js";
 export * from "./line-element.js";

package/dist/elements/layout/column-break-element.d.ts

@@ -0,0 +1,17 @@
+import { BoxConstraints, Offset, Size } from "../../layout/box-constraints.js";
+import { LayoutContext, PDFElement } from "../pdf-element.js";
+/**
+ * A forced break to the next Region of a `Flow` - from the last one, the next page's first. Always of
+ * the innermost Flow; several skip several. It takes no space and draws nothing: the packer of a Region
+ * consumes it, so reaching the render pass means it sat outside one, which is reported there.
+ */
+export declare class ColumnBreakElement extends PDFElement {
+    /** The page it was last laid out on - only so an ineffective break can name it. */
+    page?: number;
+    calculateLayout(_constraints: BoxConstraints, _offset: Offset, ctx: LayoutContext): Size;
+    protected computeSize(): Size;
+    isColumnBreak(): boolean;
+    /** So a container around it is packed (and the break found) instead of placed whole. */
+    hasForcedBreak(): boolean;
+    getProps(): Record<string, never>;
+}

package/dist/elements/layout/column-break-element.js

@@ -0,0 +1,26 @@
+import { PDFElement } from "../pdf-element.js";
+import { pageOf } from "../../common/diagnostics.js";
+/**
+ * A forced break to the next Region of a `Flow` - from the last one, the next page's first. Always of
+ * the innermost Flow; several skip several. It takes no space and draws nothing: the packer of a Region
+ * consumes it, so reaching the render pass means it sat outside one, which is reported there.
+ */
+export class ColumnBreakElement extends PDFElement {
+    calculateLayout(_constraints, _offset, ctx) {
+        this.page = pageOf(ctx);
+        return { width: 0, height: 0 };
+    }
+    computeSize() {
+        return { width: 0, height: 0 };
+    }
+    isColumnBreak() {
+        return true;
+    }
+    /** So a container around it is packed (and the break found) instead of placed whole. */
+    hasForcedBreak() {
+        return true;
+    }
+    getProps() {
+        return {};
+    }
+}

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

@@ -8,9 +8,16 @@ import { LayoutContext, PDFElement } from "../pdf-element.js";
  */
 export declare class DeferredElement extends PDFElement implements Fragmentable {
     private resolve;
+    private readonly sources;
     private composed?;
     private built;
-    constructor(resolve: (ctx: LayoutContext, width: number) => PDFElement);
+    /**
+     * `sources`: the elements the subtree will be built from (a table's cells), so the async pass before
+     * layout can reach what is not built yet - an image from a URL in a cell.
+     */
+    constructor(resolve: (ctx: LayoutContext, width: number) => PDFElement, sources?: readonly PDFElement[]);
+    /** A copy builds a subtree of its own, from copies, so even element cells it holds are its own. */
+    clone(): this;
     /** The subtree for this context and width: built once, and again only when one of them changes. */
     private subtree;
     private build;
@@ -23,5 +30,6 @@ export declare class DeferredElement extends PDFElement implements Fragmentable
     layoutChildren(): readonly PDFElement[];
     getProps(): {
         composed: PDFElement | undefined;
+        sources: readonly PDFElement[];
     };
 }