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

package/dist/api/text.d.ts

@@ -1,4 +1,4 @@
-import { TextElement, TextSegment } from "../elements/text-element.js";
+import { TextElement, TextRole, TextSegment } from "../elements/text-element.js";
 import { TextOverflow } from "../text/line-breaker.js";
 import { ResolvedTextStyle } from "../text/text-style.js";
 import { ColorInput } from "./color.js";
@@ -11,6 +11,12 @@ export interface TextStyle {
     bold?: boolean;
     italic?: boolean;
     color?: ColorInput;
+    /** 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). */
@@ -23,6 +29,9 @@ export interface TextOptions extends TextStyle {
     /** Line-height multiplier (default `1`). `1.4` gives roomier body copy; each line is
      *  `size * lineHeight` tall. */
     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. */
+    role?: TextRole;
 }
 /**
  * An inline run for mixed-style `Text` (`Text([span("a", {bold:true}), span("b")])`). Each

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,14 @@ 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,
+        href: style.href,
+        dest: style.to,
     };
 }
 /**
@@ -38,11 +60,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 +79,7 @@ export function Text(content, opts = {}) {
         maxLines: opts.maxLines,
         overflow: opts.overflow,
         lineHeight: opts.lineHeight,
+        role: opts.role,
     });
 }
 /** `Text` with body-paragraph defaults (same options; a separate name reads as intent). */
@@ -63,7 +91,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) {

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

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

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

@@ -19,6 +19,7 @@ export declare class CustomLocalImage extends CustomImage {
     private imagePath;
     private fileBuffer;
     private fileRawData;
+    private dims?;
     constructor(imagePath: string);
     init(): Promise<void>;
     getImageType(): Promise<string>;
@@ -36,6 +37,7 @@ export declare class CustomLocalImage extends CustomImage {
 export declare class CustomBytesImage extends CustomImage {
     private bytes;
     private fileRawData;
+    private dims?;
     constructor(bytes: Uint8Array);
     init(): Promise<void>;
     getImageType(): Promise<string>;
@@ -49,15 +51,34 @@ 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;
+    /** Alternate text for accessibility (tagged PDF). With `alt` the image is a Figure; without, decoration. */
+    alt?: string;
 }
 export declare class ImageElement extends SizedPDFElement {
     private image;
+    private widthFactor?;
+    private heightFactor?;
     private fit;
     private radius;
-    constructor({ image, width, height, fit, radius }: ImageElementParams);
+    private readonly alt?;
+    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;
@@ -67,6 +88,7 @@ export declare class ImageElement extends SizedPDFElement {
         image: CustomImage;
         fit: BoxFit;
         radius: number;
+        alt: string | undefined;
     };
 }
 export {};

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,25 +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 }) {
+    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 };
     }
@@ -122,6 +164,7 @@ export class ImageElement extends SizedPDFElement {
             image: this.image,
             fit: this.fit,
             radius: this.radius,
+            alt: this.alt,
         };
     }
 }

package/dist/elements/index.d.ts

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

package/dist/elements/index.js

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

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

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

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

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

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

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

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

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

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

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

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

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