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

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 {
@@ -8,28 +9,33 @@ export declare enum BoxFit {
     fill = "FILL"
 }
 export declare abstract class CustomImage {
-    abstract init(): void | Promise<void>;
+    /** Loads the image. `fresh`: a new render begins - a load that failed in an earlier one is tried again. */
+    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
@@ -43,10 +49,38 @@ 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 {
+    constructor(message: string);
+}
+/** How long an image from a URL may take, and how large it may be - a raster image and an SVG alike. */
+export declare const IMAGE_FETCH_LIMITS: {
+    timeoutMs: number;
+    maxBytes: number;
+};
+/** Whether an image source string is an address to fetch rather than a file path. */
+export declare const isImageUrl: (src: string) => boolean;
+/**
+ * An image from a URL - `http(s):` or a `data:` URL - fetched in the async pass before layout, with
+ * the same timeout and size ceiling as a font. What it IS comes from its bytes, never from the
+ * address, so `.../photo?id=7` works. A dead link stops the render with an `ImageUrlError` naming it.
+ */
+export declare class CustomUrlImage extends CustomImage {
+    private readonly url;
+    private loading?;
+    private loaded?;
+    private failed;
+    constructor(url: string);
+    init(fresh?: boolean): Promise<void>;
+    private load;
+    private image;
+    getImageType(): Promise<string>;
+    getFileData(): string;
+    getImageDimensions(): Promise<ImageDimensions>;
+    dimensionsNow(): ImageDimensions | undefined;
 }
 interface ImageElementParams {
     image: CustomImage;
@@ -67,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;
 }
@@ -79,21 +116,32 @@ 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 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 extent on one axis, clamped by its min/max; unknown before the pre-pass. */
+    private ownExtent;
     getProps(): {
         x: number;
         y: number;
@@ -102,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,8 +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 { extentSpecs, resolveSize, } from "../layout/box-constraints.js";
+import { readFileBytes } from "../platform/node-fs.js";
+import { fetchBytes } from "../utils/fetch-bytes.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) {
@@ -18,23 +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 {
-            // Loading image and convert it to base64
-            await this.loadImage(this.imagePath);
+            this.fileBuffer = readFileBytes(imagePath);
         }
-        catch (error) {
-            console.error("Error loading image:", error);
+        catch (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,23 +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("You must first call the `loadAndConvertImage` method");
-        }
-        this.dims = await getImageDimensions(this.fileBuffer);
+        this.dims ?? (this.dims = readImageDimensions(this.fileBuffer)); // reuse across layout + render
         return this.dims;
     }
 }
@@ -94,13 +106,77 @@ 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;
+    }
+}
+/** Thrown when an image could not be fetched or is not one we can embed. Always says which URL. */
+export class ImageUrlError extends Error {
+    constructor(message) {
+        super(`@jasy/pdf: ${message}`);
+    }
+}
+/** How long an image from a URL may take, and how large it may be - a raster image and an SVG alike. */
+export const IMAGE_FETCH_LIMITS = { timeoutMs: 15000, maxBytes: 32 * 1024 * 1024 };
+/** Whether an image source string is an address to fetch rather than a file path. */
+export const isImageUrl = (src) => /^(https?:|data:)/i.test(src.trim());
+/**
+ * An image from a URL - `http(s):` or a `data:` URL - fetched in the async pass before layout, with
+ * the same timeout and size ceiling as a font. What it IS comes from its bytes, never from the
+ * address, so `.../photo?id=7` works. A dead link stops the render with an `ImageUrlError` naming it.
+ */
+export class CustomUrlImage extends CustomImage {
+    constructor(url) {
+        super();
+        this.url = url;
+        this.failed = false;
+    }
+    // One fetch per render, however often it is asked: the pre-layout size pass and the renderer both
+    // call init(). A failure sticks for that render only - the next one asks again (`fresh`).
+    async init(fresh = false) {
+        if (fresh && this.failed)
+            this.loading = undefined;
+        this.loading ?? (this.loading = this.load().then((image) => ((this.failed = false), image), (e) => {
+            this.failed = true;
+            throw e;
+        }));
+        this.loaded = await this.loading;
+    }
+    async load() {
+        const bytes = await fetchBytes(this.url, "image", ImageUrlError, IMAGE_FETCH_LIMITS);
+        const jpeg = bytes[0] === 0xff && bytes[1] === 0xd8;
+        const png = bytes[0] === 0x89 && bytes[1] === 0x50 && bytes[2] === 0x4e && bytes[3] === 0x47;
+        if (!jpeg && !png) {
+            // An error page answers with a 200 often enough to name it rather than fail deep inside.
+            const looksLikeMarkup = new TextDecoder().decode(bytes.subarray(0, 64)).trimStart()[0] === "<";
+            throw new ImageUrlError(`the file at ${this.url} is ${looksLikeMarkup ? "markup (an HTML page, or an SVG - pass that to Svg(url))" : "not an image we can embed"} - jasy embeds PNG and JPEG`);
+        }
+        return new CustomBytesImage(bytes);
+    }
+    image() {
+        if (!this.loaded)
+            throw new Error("@jasy/pdf: an image was measured before it was loaded");
+        return this.loaded;
+    }
+    getImageType() {
+        return this.image().getImageType();
+    }
+    getFileData() {
+        return this.image().getFileData();
+    }
+    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 });
@@ -112,29 +188,68 @@ 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();
-            this.intrinsic = await this.image.getImageDimensions();
+            await this.image.init(true); // a render begins here
+            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.
+        this.width = size.width;
+        this.height = size.height;
+        return { width: size.width ?? 0, height: size.height ?? 0 };
+    }
+    computeSize(constraints) {
+        const size = this.sizeFor(constraints);
+        return { width: size.width ?? 0, height: size.height ?? 0 };
+    }
+    /** 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.
         const specs = extentSpecs({
@@ -144,31 +259,36 @@ 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));
         }
-        // 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 ?? (bounds.hasBoundedWidth ? bounds.maxWidth : this.requested.width);
-        this.height = h ?? (bounds.hasBoundedHeight ? bounds.maxHeight : this.requested.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
+                : (this.requested.width ?? this.ownExtent(bounds, "width")));
+        const height = h ??
+            (bounds.hasBoundedHeight
+                ? 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: this.width ?? 0, height: this.height ?? 0 };
+        return { width, height, guessed };
+    }
+    /** The image's own extent on one axis, clamped by its min/max; unknown before the pre-pass. */
+    ownExtent(bounds, axis) {
+        const own = this.ownSize()?.[axis];
+        if (own === undefined)
+            return undefined;
+        return axis === "width" ? bounds.constrainWidth(own) : bounds.constrainHeight(own);
     }
     getProps() {
         return {
@@ -179,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/anchor-element.d.ts

@@ -1,20 +1,18 @@
-import { PDFElement, LayoutContext } from "../pdf-element.js";
-import { BoxConstraints, Offset, Size } from "../../layout/box-constraints.js";
+import { PDFElement } from "../pdf-element.js";
+import { ProxyElement } from "./proxy-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.
+ * Marks its child as a named jump target for an internal `Link({ to: name })`. Layout-transparent (a
+ * `ProxyElement`); the renderer turns the child's top into an `Anchor` IR node (and PDFRenderer into a
+ * /Names /Dests entry). It draws nothing. Split across pages, only the first piece is the target - a
+ * name must lead to one place.
  */
-export declare class AnchorElement extends PDFElement {
+export declare class AnchorElement extends ProxyElement {
     private name;
-    private child;
-    private y;
     constructor({ name, child }: {
         name: string;
         child: PDFElement;
     });
-    calculateLayout(constraints: BoxConstraints, offset: Offset, ctx: LayoutContext): Size;
+    protected rewrap(child: PDFElement, continued: boolean): PDFElement;
     getProps(): {
         name: string;
         child: PDFElement;

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

@@ -1,27 +1,19 @@
-import { PDFElement } from "../pdf-element.js";
+import { ProxyElement } from "./proxy-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.
+ * Marks its child as a named jump target for an internal `Link({ to: name })`. Layout-transparent (a
+ * `ProxyElement`); the renderer turns the child's top into an `Anchor` IR node (and PDFRenderer into a
+ * /Names /Dests entry). It draws nothing. Split across pages, only the first piece is the target - a
+ * name must lead to one place.
  */
-export class AnchorElement extends PDFElement {
+export class AnchorElement extends ProxyElement {
     constructor({ name, child }) {
-        super();
-        this.y = 0;
+        super(child);
         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;
+    rewrap(child, continued) {
+        return continued ? child : new AnchorElement({ name: this.name, child });
     }
     getProps() {
-        return {
-            name: this.name,
-            child: this.child,
-            y: this.y,
-        };
+        return { name: this.name, child: this.child, y: this.y };
     }
 }

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

@@ -1,23 +1,21 @@
-import { PDFElement, LayoutContext } from "../pdf-element.js";
-import { BoxConstraints, Offset, Size } from "../../layout/box-constraints.js";
+import { PDFElement } from "../pdf-element.js";
+import { ProxyElement } from "./proxy-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.
+ * Adds a document-outline entry (a bookmark) that jumps to its child. Layout-transparent (a
+ * `ProxyElement`); the renderer turns the child's top 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. Split across pages,
+ * only the first piece carries the entry - a chapter is listed once.
  */
-export declare class BookmarkElement extends PDFElement {
+export declare class BookmarkElement extends ProxyElement {
     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;
+    protected rewrap(child: PDFElement, continued: boolean): PDFElement;
     getProps(): {
         title: string;
         level: number;

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

@@ -1,30 +1,21 @@
-import { PDFElement } from "../pdf-element.js";
+import { ProxyElement } from "./proxy-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.
+ * Adds a document-outline entry (a bookmark) that jumps to its child. Layout-transparent (a
+ * `ProxyElement`); the renderer turns the child's top 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. Split across pages,
+ * only the first piece carries the entry - a chapter is listed once.
  */
-export class BookmarkElement extends PDFElement {
+export class BookmarkElement extends ProxyElement {
     constructor({ title, level = 1, child }) {
-        super();
-        this.y = 0;
+        super(child);
         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;
+    rewrap(child, continued) {
+        return continued ? child : new BookmarkElement({ title: this.title, level: this.level, child });
     }
     getProps() {
-        return {
-            title: this.title,
-            level: this.level,
-            child: this.child,
-            y: this.y,
-        };
+        return { title: this.title, level: this.level, child: this.child, y: this.y };
     }
 }