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

package/dist/api/text.d.ts

@@ -11,6 +11,23 @@ export interface TextStyle {
     bold?: boolean;
     italic?: boolean;
     color?: ColorInput;
+    /** Draw a line under the text. Its position and thickness come from the font, not from a guess.
+     *  A `Link` is NOT underlined automatically - say so if you want it. */
+    underline?: boolean;
+    /** Draw a line through the text, at half its x-height (where a browser puts it). */
+    strikethrough?: boolean;
+    /** Let the underline step around descenders, like a browser (`text-decoration-skip-ink`). Needs an
+     *  EMBEDDED font - the standard-14 outlines live in the viewer, so we cannot see where their ink
+     *  is. Asking for it with a standard font is an error, not a silent no-op. */
+    skipInk?: boolean;
+    /** Extra space after every glyph, in points (CSS `letter-spacing`). Negative tightens. Default 0. */
+    letterSpacing?: number;
+    /** External URL - makes this run an inline hyperlink (a /Link annotation over its glyphs). On a
+     *  `span` it links just that run; on a whole `Text` (plain string) it links the whole text. */
+    href?: string;
+    /** Internal jump target - the `name` of an `Anchor` elsewhere in the document (like `href`, but a
+     *  same-document /GoTo instead of a URL). Use for a clickable table of contents / cross-reference. */
+    to?: string;
 }
 export interface TextOptions extends TextStyle {
     /** Text-internal alignment (left/center/right) - independent of a parent's `cross` (§5). */
@@ -20,8 +37,9 @@ export interface TextOptions extends TextStyle {
     maxLines?: number;
     /** What happens past `maxLines`: `"clip"` (default) cuts hard, `"ellipsis"` ends with "…". */
     overflow?: TextOverflow;
-    /** Line-height multiplier (default `1`). `1.4` gives roomier body copy; each line is
-     *  `size * lineHeight` tall. */
+    /** Line-height multiplier: each line is `size * lineHeight` tall. Unset means the font's own
+     *  natural line height (`ascent + descent + lineGap`), like CSS `line-height: normal` - which is
+     *  what you want for body copy. `1` gives exactly one em, which most faces overflow slightly. */
     lineHeight?: number;
     /** Accessibility role for the tagged structure tree (only when rendered with `accessible`): a heading
      *  level `"h1"`..`"h6"` or `"p"` (default). Purely semantic - it does not change the visual style. */
@@ -50,6 +68,10 @@ export interface TextDefaults {
     color?: ColorInput;
     align?: "left" | "center" | "right";
     lineHeight?: number;
+    underline?: boolean;
+    strikethrough?: boolean;
+    skipInk?: boolean;
+    letterSpacing?: number;
 }
 /** Maps the `Text`-style option names onto a partial engine `ResolvedTextStyle` (only the set
  *  fields), for seeding the inheritance cascade. */

package/dist/api/text.js

@@ -17,6 +17,26 @@ const ALIGN = {
     center: HorizontalAlignment.center,
     right: HorizontalAlignment.right,
 };
+/**
+ * Validates a font `size` (a number of points). Rejects anything that would silently become a NaN
+ * height deep in layout - notably `Document({ size: "A4" })`, where `"A4"` is the PAGE size and belongs
+ * on `Page`, not a font size. `undefined` passes through (unset = inherit the cascade).
+ */
+function toFontSize(size) {
+    if (size === undefined)
+        return undefined;
+    if (typeof size !== "number" || !Number.isFinite(size) || size <= 0) {
+        // Quote a string so "A4" reads as a string; show a bare number/NaN as-is (JSON turns NaN into null).
+        const shown = typeof size === "string" ? JSON.stringify(size) : String(size);
+        // The Page-vs-font-size mix-up only happens with a string like "A4"; for a plain bad number
+        // (NaN, negative, 0) the hint would just be noise, so keep the message generic there.
+        const hint = typeof size === "string"
+            ? ` Note: the page size goes on Page({ size: "A4" }), not on Document or Text.`
+            : "";
+        throw new Error(`Invalid font size ${shown} (expected a positive number of points).${hint}`);
+    }
+    return size;
+}
 /**
  * An inline run for mixed-style `Text` (`Text([span("a", {bold:true}), span("b")])`). Each
  * field overrides the enclosing `Text`'s defaults for just this run; omitted fields inherit.
@@ -24,12 +44,17 @@ const ALIGN = {
 export function span(text, style = {}) {
     return {
         content: text,
-        fontSize: style.size,
+        fontSize: toFontSize(style.size),
         fontFamily: style.font,
         fontStyle: style.bold !== undefined || style.italic !== undefined
             ? toFontStyle(style.bold, style.italic)
             : undefined,
         fontColor: style.color !== undefined ? toColor(style.color) : undefined,
+        underline: style.underline,
+        strikethrough: style.strikethrough,
+        letterSpacing: style.letterSpacing,
+        href: style.href,
+        dest: style.to,
     };
 }
 /**
@@ -38,11 +63,16 @@ export function span(text, style = {}) {
  * text-internal `align`.
  */
 export function Text(content, opts = {}) {
+    // A plain string given an `href`/`to` becomes a single link span, so `Text("jasy.dev", { href })` (or
+    // `{ to }`) is a whole-text link (inline links use `span(...)`). This routes through the styled-segment
+    // path, which lays a single default-font segment out identically - only the /Link annotation is added.
+    const isLink = opts.href !== undefined || opts.to !== undefined;
+    const body = typeof content === "string" && isLink ? [span(content, opts)] : content;
     // Unset properties are left undefined so they inherit the cascaded TextStyle (Document default /
     // built-in). Only bold/italic that the caller actually set become an explicit FontStyle.
     return new TextElement({
-        content,
-        fontSize: opts.size,
+        content: body,
+        fontSize: toFontSize(opts.size),
         fontFamily: opts.font,
         fontStyle: opts.bold !== undefined || opts.italic !== undefined
             ? toFontStyle(opts.bold, opts.italic)
@@ -52,6 +82,10 @@ export function Text(content, opts = {}) {
         maxLines: opts.maxLines,
         overflow: opts.overflow,
         lineHeight: opts.lineHeight,
+        underline: opts.underline,
+        strikethrough: opts.strikethrough,
+        skipInk: opts.skipInk,
+        letterSpacing: opts.letterSpacing,
         role: opts.role,
     });
 }
@@ -64,7 +98,7 @@ export function Paragraph(content, opts = {}) {
 export function toTextStyleOverride(opts) {
     const style = {};
     if (opts.size !== undefined)
-        style.fontSize = opts.size;
+        style.fontSize = toFontSize(opts.size);
     if (opts.font !== undefined)
         style.fontFamily = opts.font;
     if (opts.bold !== undefined || opts.italic !== undefined) {
@@ -76,5 +110,13 @@ export function toTextStyleOverride(opts) {
         style.textAlignment = ALIGN[opts.align];
     if (opts.lineHeight !== undefined)
         style.lineHeight = opts.lineHeight;
+    if (opts.underline !== undefined)
+        style.underline = opts.underline;
+    if (opts.strikethrough !== undefined)
+        style.strikethrough = opts.strikethrough;
+    if (opts.skipInk !== undefined)
+        style.skipInk = opts.skipInk;
+    if (opts.letterSpacing !== undefined)
+        style.letterSpacing = opts.letterSpacing;
     return style;
 }

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

@@ -9,13 +9,25 @@ interface ContainerElementParams extends SizedElement, WithChildren {
     main?: MainAlign;
     /** Horizontal alignment of each child (cross axis); defaults to `stretch`. */
     cross?: CrossAlign;
+    /** Width/height as a fraction (0..1) of the offered box instead of `width`/`height` (relative sizing). */
+    widthFactor?: number;
+    heightFactor?: number;
+    /** Start this stack on a fresh page (CSS `break-before: page`). */
+    breakBefore?: boolean;
+    /** Start everything after this stack on a fresh page (CSS `break-after: page`). */
+    breakAfter?: boolean;
 }
 export declare class ContainerElement extends SizedPDFElement implements Fragmentable {
     private children;
     private gap;
     private main;
     private cross;
-    constructor({ x, y, width, height, children, gap, main, cross }: ContainerElementParams);
+    private breakBefore;
+    private breakAfter;
+    private requested;
+    constructor({ x, y, width, height, children, gap, main, cross, widthFactor, heightFactor, breakBefore, breakAfter, }: ContainerElementParams);
+    breaksBefore(): boolean;
+    breaksAfter(): boolean;
     /**
      * Splits the vertical stack across pages. Children are measured against the content
      * width and packed until one would exceed `maxHeight`. That straddling child is itself
@@ -27,8 +39,21 @@ export declare class ContainerElement extends SizedPDFElement implements Fragmen
      * Flex children make the container absorb the leftover space, so it never overflows -
      * in that case we don't fragment and hand the whole container back as `fitted`.
      */
+    hasForcedBreak(): boolean;
     fragment(maxHeight: number, width: number, ctx: LayoutContext): FragmentResult;
     private cloneWithChildren;
+    relativeSizeFactor(horizontal: boolean): number | undefined;
+    /**
+     * 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: boolean): boolean;
     calculateLayout(constraints: BoxConstraints, offset: Offset, ctx: LayoutContext): Size;
     getProps(): ContainerElementParams;
 }

package/dist/elements/container-element.js

@@ -1,13 +1,23 @@
 import { FlexLayoutHelper, VERTICAL_AXIS } from "../utils/flex-layout.js";
-import { packChildren } from "../layout/fragmentation.js";
-import { SizedPDFElement, } from "./pdf-element.js";
+import { resolveExtent } from "../layout/box-constraints.js";
+import { childrenForceBreak, packChildren, } from "../layout/fragmentation.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, breakBefore, breakAfter, }) {
         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 };
+        this.breakBefore = breakBefore ?? false;
+        this.breakAfter = breakAfter ?? false;
+    }
+    breaksBefore() {
+        return this.breakBefore;
+    }
+    breaksAfter() {
+        return this.breakAfter;
     }
     /**
      * Splits the vertical stack across pages. Children are measured against the content
@@ -20,42 +30,84 @@ export class ContainerElement extends SizedPDFElement {
      * Flex children make the container absorb the leftover space, so it never overflows -
      * in that case we don't fragment and hand the whole container back as `fitted`.
      */
+    hasForcedBreak() {
+        return childrenForceBreak(this.children);
+    }
     fragment(maxHeight, width, ctx) {
-        const { fitted, remainder } = packChildren(this.children, maxHeight, width, ctx, this.gap);
-        // Fits as one region: hand the whole container back so the page renders unchanged
-        // (its normal layout distributes flex / fills the page).
-        if (remainder.length === 0)
+        const { fitted, remainder, forceBreak } = packChildren(this.children, maxHeight, width, ctx, 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)
             return { fitted: this, remainder: null };
         return {
             fitted: this.cloneWithChildren(fitted),
-            remainder: this.cloneWithChildren(remainder),
+            // Only the CONTINUATION carries `breakAfter`, so a stack that splits across pages still breaks
+            // after its LAST fragment (not after the first one). `breakBefore` is dropped on both: it was
+            // already honoured by the parent before this stack was ever fragmented.
+            remainder: remainder.length === 0 ? null : this.cloneWithChildren(remainder, this.breakAfter),
+            forceBreak,
         };
     }
-    cloneWithChildren(children) {
+    cloneWithChildren(children, breakAfter = false) {
         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,
+            breakAfter,
         });
     }
+    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 +115,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

@@ -6,7 +6,15 @@ export * from "./rectangle-element.js";
 export * from "./image-element.js";
 export * from "./layout/expanded-element.js";
 export * from "./layout/padding-element.js";
+export * from "./layout/page-break-element.js";
+export * from "./layout/keep-together-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

@@ -6,7 +6,15 @@ export * from "./rectangle-element.js";
 export * from "./image-element.js";
 export * from "./layout/expanded-element.js";
 export * from "./layout/padding-element.js";
+export * from "./layout/page-break-element.js";
+export * from "./layout/keep-together-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,
+        };
+    }
+}