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

package/dist/elements/text-element.js

@@ -5,9 +5,11 @@
 import { TextRenderer } from "../renderer/text-renderer.js";
 import { DEFAULT_TEXT_STYLE } from "../text/text-style.js";
 import { wrapStringIntoLines, breakSegmentsIntoLines, segmentLinesToSegments, } from "../text/line-breaker.js";
+import { lineBoxForSegmentLine, lineBoxForString } from "../text/line-metrics.js";
+import { runAdvance } from "../text/advance.js";
 import { SizedPDFElement } from "./pdf-element.js";
 export class TextElement extends SizedPDFElement {
-    constructor({ fontSize, content, fontFamily, fontStyle, color, textAlignment, maxLines, overflow = "clip", lineHeight, role, }) {
+    constructor({ fontSize, content, fontFamily, fontStyle, color, textAlignment, maxLines, overflow = "clip", lineHeight, underline, strikethrough, skipInk, letterSpacing, role, }) {
         super({ x: 0, y: 0 });
         this.role = role;
         this.rawFontSize = fontSize;
@@ -16,6 +18,10 @@ export class TextElement extends SizedPDFElement {
         this.rawColor = color;
         this.rawTextAlignment = textAlignment;
         this.rawLineHeight = lineHeight;
+        this.rawUnderline = underline;
+        this.rawStrikethrough = strikethrough;
+        this.rawSkipInk = skipInk;
+        this.rawLetterSpacing = letterSpacing;
         this.content = content;
         this.maxLines = maxLines;
         this.overflow = overflow;
@@ -32,6 +38,10 @@ export class TextElement extends SizedPDFElement {
         this.color = this.rawColor ?? ts.color;
         this.textAlignment = this.rawTextAlignment ?? ts.textAlignment;
         this.lineHeight = this.rawLineHeight ?? ts.lineHeight;
+        this.underline = this.rawUnderline ?? ts.underline;
+        this.strikethrough = this.rawStrikethrough ?? ts.strikethrough;
+        this.skipInk = this.rawSkipInk ?? ts.skipInk;
+        this.letterSpacing = this.rawLetterSpacing ?? ts.letterSpacing;
     }
     /**
      * Splits the paragraph at line boxes (Slice 1). The lines that fit in `maxHeight` stay;
@@ -45,11 +55,12 @@ export class TextElement extends SizedPDFElement {
             ? this.fragmentString(this.content, maxHeight, width, ctx)
             : this.fragmentSegments(this.content, maxHeight, width, ctx);
     }
-    // Plain string: every wrapped line is `fontSize` tall (matches calculateTextHeight),
-    // so `floor(maxHeight / fontSize)` lines fit.
+    // Plain string: every wrapped line gets the same box (the same one calculateTextHeight uses),
+    // so `floor(maxHeight / lineBox)` lines fit.
     fragmentString(content, maxHeight, width, ctx) {
-        const lines = wrapStringIntoLines(content, this.fontFamily, this.fontSize, this.fontStyle, width, ctx.metrics, this.maxLines, this.overflow);
-        const fittedLineCount = Math.floor(maxHeight / (this.fontSize * this.lineHeight));
+        const lines = wrapStringIntoLines(content, this.fontFamily, this.fontSize, this.fontStyle, width, ctx.metrics, this.maxLines, this.overflow, this.letterSpacing);
+        const box = lineBoxForString(ctx.metrics, this.fontFamily, this.fontStyle, this.fontSize, this.lineHeight);
+        const fittedLineCount = Math.floor(maxHeight / box.height);
         if (fittedLineCount <= 0)
             return { fitted: null, remainder: this };
         if (fittedLineCount >= lines.length)
@@ -59,18 +70,20 @@ export class TextElement extends SizedPDFElement {
             remainder: this.cloneWithContent(lines.slice(fittedLineCount).join(" ")),
         };
     }
-    // Styled segments: each line's height is its tallest font (maxFontSize), so pack lines
-    // by cumulative leading. Rebuild the fitted/remainder halves back into TextSegment[].
+    // Styled segments: each line's height comes from the fonts on it, so pack lines by cumulative
+    // box height. Rebuild the fitted/remainder halves back into TextSegment[].
     fragmentSegments(content, maxHeight, width, ctx) {
-        const lines = breakSegmentsIntoLines(content, {
+        const defaults = {
             fontFamily: this.fontFamily,
             fontSize: this.fontSize,
             fontStyle: this.fontStyle,
-        }, width, ctx.metrics, this.maxLines, this.overflow);
+            letterSpacing: this.letterSpacing,
+        };
+        const lines = breakSegmentsIntoLines(content, defaults, width, ctx.metrics, this.maxLines, this.overflow);
         let used = 0;
         let fittedLineCount = 0;
         for (const line of lines) {
-            const lineBox = line.maxFontSize * this.lineHeight;
+            const lineBox = lineBoxForSegmentLine(line, defaults, ctx.metrics, this.lineHeight).height;
             if (used + lineBox > maxHeight)
                 break;
             used += lineBox;
@@ -98,6 +111,10 @@ export class TextElement extends SizedPDFElement {
             maxLines: this.maxLines,
             overflow: this.overflow,
             lineHeight: this.lineHeight,
+            underline: this.underline,
+            strikethrough: this.strikethrough,
+            skipInk: this.skipInk,
+            letterSpacing: this.letterSpacing,
             role: this.role,
         }).adoptStructId(this); // a wrapped remainder is the SAME logical paragraph (one P across pages)
     }
@@ -112,7 +129,7 @@ export class TextElement extends SizedPDFElement {
             ? constraints.maxWidth
             : this.naturalWidth(ctx.metrics);
         const wrapWidth = this.width ?? 0;
-        this.height = TextRenderer.calculateTextHeight(this.content, this.fontSize, this.fontFamily, this.fontStyle, ctx.metrics, wrapWidth, this.maxLines, this.overflow, this.lineHeight);
+        this.height = TextRenderer.calculateTextHeight(this.content, this.fontSize, this.fontFamily, this.fontStyle, ctx.metrics, wrapWidth, this.maxLines, this.overflow, this.lineHeight, this.letterSpacing);
         // Top-left coordinates (y = top of the text box). The baseline offset and the
         // Y-flip are applied downstream (the line-builder positions baselines, the seam
         // flips to PDF), so the element stays coordinate-system-blind.
@@ -127,22 +144,24 @@ export class TextElement extends SizedPDFElement {
      *  - enough to tip a borderline string (e.g. "20 Jun 2026", wider than "04 Jul 2026" only because
      *  'n' beats 'l') one bit over its own width, dropping the last word onto a second line. */
     naturalWidth(metrics) {
-        const oneLine = (text, family, size, style) => {
+        const oneLine = (text, family, size, style, letterSpacing) => {
+            const font = { fontFamily: family, fontSize: size, fontStyle: style };
             const words = text.split(" ");
-            const space = metrics.getCharWidth(" ", size, undefined, family, style);
+            const space = runAdvance(metrics, " ", font, letterSpacing);
             let width = 0;
             words.forEach((word, i) => {
-                const w = metrics.getStringWidth(word, family, size, style);
-                // Group (word + space) as one term, exactly like the breaker - see the note above.
+                const w = runAdvance(metrics, word, font, letterSpacing);
+                // Group (word + space) as one term, exactly like the breaker - see the note above. Both use
+                // the same `runAdvance`, so the two agree bit for bit even with letterSpacing.
                 width += i < words.length - 1 ? w + space : w;
             });
             return width;
         };
         if (typeof this.content === "string") {
-            return oneLine(this.content, this.fontFamily, this.fontSize, this.fontStyle);
+            return oneLine(this.content, this.fontFamily, this.fontSize, this.fontStyle, this.letterSpacing);
         }
         return this.content.reduce((sum, seg) => sum +
-            oneLine(seg.content, seg.fontFamily ?? this.fontFamily, seg.fontSize ?? this.fontSize, seg.fontStyle ?? this.fontStyle), 0);
+            oneLine(seg.content, seg.fontFamily ?? this.fontFamily, seg.fontSize ?? this.fontSize, seg.fontStyle ?? this.fontStyle, seg.letterSpacing ?? this.letterSpacing), 0);
     }
     getProps() {
         return {
@@ -159,6 +178,10 @@ export class TextElement extends SizedPDFElement {
             maxLines: this.maxLines,
             overflow: this.overflow,
             lineHeight: this.lineHeight,
+            underline: this.underline,
+            strikethrough: this.strikethrough,
+            skipInk: this.skipInk,
+            letterSpacing: this.letterSpacing,
             role: this.role,
         };
     }

package/dist/ir/display-list.d.ts

@@ -35,6 +35,7 @@ export interface TextRun {
     fontStyle: FontStyle;
     fontSize: number;
     color: Color;
+    letterSpacing?: number;
     tag?: StructTag;
 }
 /** An axis-aligned rectangle. An absent `fill` or `stroke` means that part is not drawn. */
@@ -103,6 +104,64 @@ export interface ClipPush {
 export interface ClipPop {
     type: "clip-pop";
 }
+/**
+ * A hyperlink over a rectangle. Unlike every other IR node this draws NOTHING into the content stream -
+ * it becomes a PDF Link ANNOTATION on the page (`/Annots`), a side channel next to the drawing. Exactly
+ * one target is set: `href` is an external URL (a `/URI` action); `dest` is a named destination inside
+ * this document (a `/GoTo` action, resolved via the catalog `/Names /Dests` tree - see `Anchor`). The
+ * rect is the clickable region in top-left engine coords; the Y-flip converts it to PDF page space.
+ *
+ * NOTE: a Link inside a `TransformPush` is NOT yet rotated with it - the annotation rect lives in page
+ * space and ignores the content-stream matrix. Completing that is a planned follow-up (see todo.md).
+ */
+export interface Link {
+    type: "link";
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    href?: string;
+    dest?: string;
+}
+/**
+ * A named destination anchor - a jump TARGET for an internal `Link({ to })`. Like `Link` it draws
+ * NOTHING; it registers `name` -> (this page, `y`) in the catalog `/Names /Dests` name tree. `y` is the
+ * top of the target in top-left engine coords (the Y-flip turns it into the page-space scroll target).
+ */
+export interface Anchor {
+    type: "anchor";
+    y: number;
+    name: string;
+}
+/**
+ * A document-outline (bookmark) anchor. Like `Link` it draws NOTHING - it becomes an entry in the PDF
+ * outline tree (`/Outlines`), a side channel the viewer shows in its bookmark panel. `y` is the top of
+ * the target in top-left engine coords (the Y-flip turns it into the page-space scroll target); `level`
+ * (1-based) nests the entry under the nearest preceding entry of a smaller level.
+ */
+export interface Outline {
+    type: "outline";
+    y: number;
+    title: string;
+    level: number;
+}
+/**
+ * Pushes an affine transform (a `q` + `cm` in the content stream): everything between this and the
+ * matching `TransformPop` is painted through `matrix`. This is what `Rotated` wraps its child's nodes
+ * in, so a subtree draws rotated (or scaled/translated) around a pivot without touching its layout.
+ *
+ * `matrix` is `[a, b, c, d, e, f]` in the engine's TOP-LEFT coordinates - the same space every other IR
+ * node uses. The Y-flip at the IR -> backend seam converts it to PDF's bottom-left once per page, so
+ * producers stay coordinate-system-blind (they never see a flipped matrix).
+ */
+export interface TransformPush {
+    type: "transform-push";
+    matrix: [number, number, number, number, number, number];
+}
+/** Closes the most recent `TransformPush` (restores the graphics state). */
+export interface TransformPop {
+    type: "transform-pop";
+}
 /**
  * One drawing command of a `Path`, in absolute page coordinates. Curves are CUBIC because PDF
  * content streams have no quadratic operator - a producer converts TrueType quads to cubics before
@@ -168,4 +227,4 @@ export interface Path {
     tag?: StructTag;
 }
 /** The closed set of primitives the PDF backend knows how to draw. */
-export type IRNode = TextRun | Rect | Line | Image | ClipPush | ClipPop | Path;
+export type IRNode = TextRun | Rect | Line | Image | ClipPush | ClipPop | Path | Link | Outline | Anchor | TransformPush | TransformPop;

package/dist/layout/box-constraints.d.ts

@@ -44,6 +44,14 @@ export declare class BoxConstraints {
     /** Returns the constraints clamped to lie within `parent` (Flutter's enforce). */
     enforce(parent: BoxConstraints): BoxConstraints;
 }
+/**
+ * Resolves a sized element's extent on one axis (relative sizing). An explicit point size (`fixed`)
+ * always wins; otherwise a `factor` (0..1) of the offered extent, but ONLY when that axis is bounded -
+ * a fraction of an unbounded axis has no meaning (Flutter's FractionallySizedBox under unbounded
+ * constraints). Returns `undefined` to mean "no explicit extent", i.e. fill the box or shrink-wrap.
+ * Shared by every sized element so `width: "50%"` behaves identically across Box / Column / Row / Image.
+ */
+export declare function resolveExtent(fixed: number | undefined, factor: number | undefined, boundedMax: number, hasBounded: boolean): number | undefined;
 /** The size an element resolves to and returns UP the tree. */
 export interface Size {
     width: number;

package/dist/layout/box-constraints.js

@@ -67,3 +67,17 @@ export class BoxConstraints {
         return new BoxConstraints(Math.max(parent.minWidth, Math.min(this.minWidth, parent.maxWidth)), Math.max(parent.minWidth, Math.min(this.maxWidth, parent.maxWidth)), Math.max(parent.minHeight, Math.min(this.minHeight, parent.maxHeight)), Math.max(parent.minHeight, Math.min(this.maxHeight, parent.maxHeight)));
     }
 }
+/**
+ * Resolves a sized element's extent on one axis (relative sizing). An explicit point size (`fixed`)
+ * always wins; otherwise a `factor` (0..1) of the offered extent, but ONLY when that axis is bounded -
+ * a fraction of an unbounded axis has no meaning (Flutter's FractionallySizedBox under unbounded
+ * constraints). Returns `undefined` to mean "no explicit extent", i.e. fill the box or shrink-wrap.
+ * Shared by every sized element so `width: "50%"` behaves identically across Box / Column / Row / Image.
+ */
+export function resolveExtent(fixed, factor, boundedMax, hasBounded) {
+    if (fixed !== undefined)
+        return fixed;
+    if (factor !== undefined && hasBounded)
+        return boundedMax * factor;
+    return undefined;
+}

package/dist/layout/collect-images.d.ts

@@ -0,0 +1,9 @@
+import { PDFElement } from "../elements/pdf-element.js";
+import { ImageElement } from "../elements/image-element.js";
+/**
+ * Walks the element tree (via `getProps`, the same shallow-reflection style as the validator) and
+ * returns every `ImageElement`. A pre-layout pass uses this to resolve each image's intrinsic pixel
+ * size asynchronously: layout is synchronous and cannot await jimp, yet it needs the aspect ratio to
+ * give a width-only image its proportional height. Cheap - images are few and this runs once.
+ */
+export declare function collectImageElements(root: PDFElement): ImageElement[];

package/dist/layout/collect-images.js

@@ -0,0 +1,34 @@
+import { PDFElement, hasChildrenProp, hasChildProp } from "../elements/pdf-element.js";
+import { ImageElement } from "../elements/image-element.js";
+/**
+ * Walks the element tree (via `getProps`, the same shallow-reflection style as the validator) and
+ * returns every `ImageElement`. A pre-layout pass uses this to resolve each image's intrinsic pixel
+ * size asynchronously: layout is synchronous and cannot await jimp, yet it needs the aspect ratio to
+ * give a width-only image its proportional height. Cheap - images are few and this runs once.
+ */
+export function collectImageElements(root) {
+    const out = [];
+    const visit = (el) => {
+        if (el instanceof ImageElement)
+            out.push(el);
+        const props = el.getProps();
+        if (hasChildrenProp(props))
+            for (const c of props.children)
+                visit(c);
+        else if (hasChildProp(props))
+            visit(props.child);
+        // Wrappers that hold a subtree outside `children`/`child`: a Page's header/footer and a
+        // RepeatingHeaderElement's `body` (a Table with a header wraps its rows there). A
+        // DeferredElement's `composed` is null until layout runs, so it cannot be reached from this
+        // pre-layout pass; an image inside a deferred subtree just skips aspect pre-resolution.
+        const w = props;
+        if (w.header instanceof PDFElement)
+            visit(w.header);
+        if (w.footer instanceof PDFElement)
+            visit(w.footer);
+        if (w.body instanceof PDFElement)
+            visit(w.body);
+    };
+    visit(root);
+    return out;
+}

package/dist/layout/fragmentation.d.ts

@@ -12,6 +12,10 @@ import { LayoutContext, PDFElement } from "../elements/pdf-element.js";
 export interface FragmentResult {
     fitted: PDFElement | null;
     remainder: PDFElement | null;
+    /** The split ended at a FORCED page break (a `PageBreak`), not because the region filled up. The
+     *  remainder must start a fresh page, and an enclosing flow must stop packing too - so this bubbles
+     *  up through nested `fragment()` calls. Absent/false for an ordinary height-driven break. */
+    forceBreak?: boolean;
 }
 /**
  * An element that knows how to split itself across regions. Width is already finalized
@@ -29,6 +33,13 @@ export declare function isFragmentable(element: PDFElement): element is PDFEleme
  * logs and clips, `"ignore"` clips silently.
  */
 export type OverflowPolicy = "error" | "warn" | "ignore";
+export declare function reportOverflow(child: PDFElement, childHeight: number, maxHeight: number, policy: OverflowPolicy): void;
+/**
+ * True if packing `children` will hit a forced cut: a child that IS a break, contains one deeper in its
+ * subtree, or asks to break before/after itself. A flow container reports this from `hasForcedBreak` so
+ * its parent fragments it (runs `packChildren`) instead of placing it whole and swallowing the cut.
+ */
+export declare function childrenForceBreak(children: PDFElement[]): boolean;
 /**
  * Packs a vertical stack of children into `maxHeight`, in order. Children are measured
  * against `width` (unbounded height) and added until one would overflow; that straddling
@@ -46,4 +57,5 @@ export type OverflowPolicy = "error" | "warn" | "ignore";
 export declare function packChildren(children: PDFElement[], maxHeight: number, width: number, ctx: LayoutContext, gap?: number): {
     fitted: PDFElement[];
     remainder: PDFElement[];
+    forceBreak: boolean;
 };

package/dist/layout/fragmentation.js

@@ -10,7 +10,7 @@ export function isFragmentable(element) {
     const canFragment = element.canFragment;
     return typeof canFragment !== "function" || canFragment.call(element);
 }
-function reportOverflow(child, childHeight, maxHeight, policy) {
+export function reportOverflow(child, childHeight, maxHeight, policy) {
     if (policy === "ignore")
         return;
     const name = child.constructor.name.replace(/Element$/, "");
@@ -21,6 +21,14 @@ function reportOverflow(child, childHeight, maxHeight, policy) {
         throw new Error(`Layout overflow: ${detail}`);
     console.warn(`Layout overflow (clipped): ${detail}`);
 }
+/**
+ * True if packing `children` will hit a forced cut: a child that IS a break, contains one deeper in its
+ * subtree, or asks to break before/after itself. A flow container reports this from `hasForcedBreak` so
+ * its parent fragments it (runs `packChildren`) instead of placing it whole and swallowing the cut.
+ */
+export function childrenForceBreak(children) {
+    return children.some((child) => child.hasForcedBreak() || child.breaksBefore() || child.breaksAfter());
+}
 /**
  * Packs a vertical stack of children into `maxHeight`, in order. Children are measured
  * against `width` (unbounded height) and added until one would overflow; that straddling
@@ -39,30 +47,61 @@ export function packChildren(children, maxHeight, width, ctx, gap = 0) {
     const fitted = [];
     const remainder = [];
     let usedHeight = 0;
+    // Everything from index `from` onward spills to the next region; `broke` says whether the cut was
+    // a FORCED page break (so an enclosing flow stops too) rather than the region filling up.
+    const spill = (from, broke) => {
+        for (let j = from; j < children.length; j++)
+            remainder.push(children[j]);
+        return { fitted, remainder, forceBreak: broke };
+    };
     for (let i = 0; i < children.length; i++) {
         const child = children[i];
+        // A forced break: consume the marker (it draws nothing) and send everything after it to a fresh
+        // page, regardless of how much room is left.
+        if (child.isPageBreak())
+            return spill(i + 1, true);
+        // break-before: this child wants a fresh page. Honour it only if something is already on this region
+        // (CSS ignores break-before at the top of a page); that guard also prevents an empty page + a loop.
+        if (child.breaksBefore() && fitted.length > 0)
+            return spill(i, true);
         const childHeight = child.calculateLayout(BoxConstraints.loose(width, Infinity), { x: 0, y: 0 }, ctx).height;
         // A gap precedes every child except the first one placed in this region.
         const lead = fitted.length > 0 ? gap : 0;
-        if (usedHeight + lead + childHeight <= maxHeight) {
+        // Place whole only if it fits AND holds no forced break: a child that fits by height but contains
+        // a `PageBreak` (or a break-before/after) in its subtree must still be fragmented, or the break
+        // would be swallowed.
+        if (usedHeight + lead + childHeight <= maxHeight && !child.hasForcedBreak()) {
             fitted.push(child);
             usedHeight += lead + childHeight;
+            // break-after: everything after this child starts a fresh page.
+            if (child.breaksAfter())
+                return spill(i + 1, true);
             continue;
         }
-        // `child` straddles the boundary. Try to split it; otherwise place/defer it whole.
+        // `child` straddles the boundary, or carries a forced break. Split it; otherwise place/defer whole.
         const remaining = maxHeight - usedHeight - lead;
         let placedPart = false;
+        let childBroke = false;
         if (isFragmentable(child)) {
             const split = child.fragment(Math.max(0, remaining), width, ctx);
+            childBroke = split.forceBreak ?? false;
             if (split.fitted) {
                 fitted.push(split.fitted);
+                // The child fully fit and triggered no cut: it only reached this path because its subtree
+                // FLAGGED a possible break (hasForcedBreak) that turned out to be a no-op here - e.g. a
+                // break-before at the top of the region, which CSS ignores. Keep packing the siblings after
+                // it instead of spilling them, so break-before does not accidentally push later content away.
+                if (!split.remainder && !childBroke) {
+                    usedHeight += lead + childHeight;
+                    continue;
+                }
                 if (split.remainder)
                     remainder.push(split.remainder);
                 placedPart = true;
             }
         }
         if (!placedPart) {
-            if (fitted.length === 0) {
+            if (fitted.length === 0 && !childBroke) {
                 // Taller than the whole region and unsplittable: force it on (it overflows and is clipped)
                 // so the next region still advances - and surface it per the overflow policy.
                 reportOverflow(child, childHeight, maxHeight, ctx.onOverflow ?? "ignore");
@@ -72,9 +111,7 @@ export function packChildren(children, maxHeight, width, ctx, gap = 0) {
                 remainder.push(child);
             }
         }
-        for (let j = i + 1; j < children.length; j++)
-            remainder.push(children[j]);
-        break;
+        return spill(i + 1, childBroke);
     }
-    return { fitted, remainder };
+    return { fitted, remainder, forceBreak: false };
 }

package/dist/renderer/anchor-renderer.d.ts

@@ -0,0 +1,6 @@
+import { PDFObjectManager } from "../utils/pdf-object-manager.js";
+import { AnchorElement } from "../elements/layout/anchor-element.js";
+import { IRNode } from "../ir/display-list.js";
+export declare class AnchorRenderer {
+    static render(element: AnchorElement, objectManager: PDFObjectManager): Promise<IRNode[]>;
+}

package/dist/renderer/anchor-renderer.js

@@ -0,0 +1,11 @@
+import { RendererRegistry } from "../utils/renderer-registry.js";
+export class AnchorRenderer {
+    static async render(element, objectManager) {
+        const { name, child, y } = element.getProps();
+        const renderer = RendererRegistry.getRenderer(child);
+        const childNodes = renderer ? await renderer(child, objectManager) : [];
+        // The child draws normally; an Anchor IR node carries the name + scroll target for the page renderer
+        // to register as a named destination (it produces no content-stream ops itself).
+        return [...childNodes, { type: "anchor", y, name }];
+    }
+}

package/dist/renderer/bookmark-renderer.d.ts

@@ -0,0 +1,6 @@
+import { PDFObjectManager } from "../utils/pdf-object-manager.js";
+import { BookmarkElement } from "../elements/layout/bookmark-element.js";
+import { IRNode } from "../ir/display-list.js";
+export declare class BookmarkRenderer {
+    static render(element: BookmarkElement, objectManager: PDFObjectManager): Promise<IRNode[]>;
+}

package/dist/renderer/bookmark-renderer.js

@@ -0,0 +1,11 @@
+import { RendererRegistry } from "../utils/renderer-registry.js";
+export class BookmarkRenderer {
+    static async render(element, objectManager) {
+        const { title, level, child, y } = element.getProps();
+        const renderer = RendererRegistry.getRenderer(child);
+        const childNodes = renderer ? await renderer(child, objectManager) : [];
+        // The child draws normally; an Outline IR node carries the title + nesting + scroll target for the
+        // page renderer to collect into the /Outlines tree (it produces no content-stream ops itself).
+        return [...childNodes, { type: "outline", y, title, level }];
+    }
+}

package/dist/renderer/keep-together-renderer.d.ts

@@ -0,0 +1,10 @@
+import { KeepTogetherElement } from "../elements/layout/keep-together-element.js";
+import { PDFObjectManager } from "../utils/pdf-object-manager.js";
+import { IRNode } from "../ir/display-list.js";
+/**
+ * A `keepTogether` is layout-transparent: it just renders its child. All of its work happens in the
+ * layout pass (`fragment`), never here.
+ */
+export declare class KeepTogetherRenderer {
+    static render(group: KeepTogetherElement, objectManager: PDFObjectManager): Promise<IRNode[]>;
+}

package/dist/renderer/keep-together-renderer.js

@@ -0,0 +1,12 @@
+import { RendererRegistry } from "../utils/renderer-registry.js";
+/**
+ * A `keepTogether` is layout-transparent: it just renders its child. All of its work happens in the
+ * layout pass (`fragment`), never here.
+ */
+export class KeepTogetherRenderer {
+    static async render(group, objectManager) {
+        const { child } = group.getProps();
+        const renderer = RendererRegistry.getRenderer(child);
+        return renderer ? await renderer(child, objectManager) : [];
+    }
+}

package/dist/renderer/link-renderer.d.ts

@@ -0,0 +1,6 @@
+import { PDFObjectManager } from "../utils/pdf-object-manager.js";
+import { LinkElement } from "../elements/layout/link-element.js";
+import { IRNode } from "../ir/display-list.js";
+export declare class LinkRenderer {
+    static render(element: LinkElement, objectManager: PDFObjectManager): Promise<IRNode[]>;
+}

package/dist/renderer/link-renderer.js

@@ -0,0 +1,11 @@
+import { RendererRegistry } from "../utils/renderer-registry.js";
+export class LinkRenderer {
+    static async render(element, objectManager) {
+        const { href, dest, child, x, y, width, height } = element.getProps();
+        const renderer = RendererRegistry.getRenderer(child);
+        const childNodes = renderer ? await renderer(child, objectManager) : [];
+        // The child draws normally; a Link IR node carries the clickable rect + target (external href or
+        // internal dest) for the page renderer to emit as a /Link annotation (no content-stream ops itself).
+        return [...childNodes, { type: "link", x, y, width, height, href, dest }];
+    }
+}

package/dist/renderer/page-break-renderer.d.ts

@@ -0,0 +1,14 @@
+import { PDFObjectManager } from "../utils/pdf-object-manager.js";
+import { PageBreakElement } from "../elements/layout/page-break-element.js";
+import { IRNode } from "../ir/display-list.js";
+/**
+ * A `PageBreak` draws nothing - the pagination packer consumes it at the cut, so in a vertical flow it
+ * never reaches this pass. Reaching it therefore means the break was ineffective: it sat somewhere that
+ * does not paginate, like inside a horizontal `Row` (a row is one line, you cannot split it across
+ * pages - CSS and react-pdf ignore a forced break there too). We degrade to drawing nothing, but warn
+ * once so the mistake is not silent. This one choke-point catches every ineffective break; no element
+ * needs a special case.
+ */
+export declare class PageBreakRenderer {
+    static render(_element: PageBreakElement, _objectManager: PDFObjectManager): Promise<IRNode[]>;
+}

package/dist/renderer/page-break-renderer.js

@@ -0,0 +1,15 @@
+/**
+ * A `PageBreak` draws nothing - the pagination packer consumes it at the cut, so in a vertical flow it
+ * never reaches this pass. Reaching it therefore means the break was ineffective: it sat somewhere that
+ * does not paginate, like inside a horizontal `Row` (a row is one line, you cannot split it across
+ * pages - CSS and react-pdf ignore a forced break there too). We degrade to drawing nothing, but warn
+ * once so the mistake is not silent. This one choke-point catches every ineffective break; no element
+ * needs a special case.
+ */
+export class PageBreakRenderer {
+    static async render(_element, _objectManager) {
+        console.warn("PageBreak had no effect: it is not in a paginating flow (e.g. it is inside a Row, which is a " +
+            "single horizontal line). Put the break as a sibling in a Column to break after that content.");
+        return [];
+    }
+}

package/dist/renderer/page-builder-renderer.d.ts

@@ -0,0 +1,6 @@
+import { PDFObjectManager } from "../utils/pdf-object-manager.js";
+import { PageBuilderElement } from "../elements/layout/page-builder-element.js";
+import { IRNode } from "../ir/display-list.js";
+export declare class PageBuilderRenderer {
+    static render(element: PageBuilderElement, objectManager: PDFObjectManager): Promise<IRNode[]>;
+}

package/dist/renderer/page-builder-renderer.js

@@ -0,0 +1,11 @@
+import { RendererRegistry } from "../utils/renderer-registry.js";
+export class PageBuilderRenderer {
+    static async render(element, objectManager) {
+        // `composed` is whatever the closure built for THIS page during the render pass's layout.
+        const { composed } = element.getProps();
+        if (!composed)
+            return [];
+        const renderer = RendererRegistry.getRenderer(composed);
+        return renderer ? renderer(composed, objectManager) : [];
+    }
+}

package/dist/renderer/page-renderer.js

@@ -28,7 +28,8 @@ export class PageRenderer {
         // Accessible tagging: one struct context per page (allocates its StructParents index), threaded into
         // serialize so each drawable node is wrapped in marked content. Undefined = tagging off (byte-identical).
         const structCtx = objectManager.struct.enabled ? objectManager.struct.beginPage() : undefined;
-        const pageContent = PdfBackend.serialize(PdfBackend.flipY(nodes, height), objectManager, structCtx);
+        const flipped = PdfBackend.flipY(nodes, height);
+        const pageContent = PdfBackend.serialize(flipped, objectManager, structCtx);
         // Add the page content as a new object (FlateDecode-compressed when enabled). The /Length is
         // computed inside, with an explicit EOL before `endstream` (PDF/A clause 6.1.7.1).
         const contentObjectNumber = objectManager.addContentStream(pageContent);
@@ -67,14 +68,48 @@ export class PageRenderer {
             shadingReferences.push(`/${name} ${objectNumber} 0 R`);
         });
         const shadingCode = shadingReferences.length > 0 ? "/Shading <<\n" + shadingReferences.join("\n") + "\n>>\n" : "";
+        // Hyperlinks: a `Link` IR node drew nothing into the content stream - here its (already Y-flipped)
+        // rect + href become a /Link annotation object. `/Border [0 0 0]` hides the default visible frame;
+        // the URL is escaped like any PDF literal string. Refs are collected into the page's /Annots below.
+        const num = (n) => Number(n.toFixed(2));
+        const annotRefs = [];
+        for (const node of flipped) {
+            if (node.type !== "link")
+                continue;
+            const rect = `[${num(node.x)} ${num(node.y)} ${num(node.x + node.width)} ${num(node.y + node.height)}]`;
+            // Either an external URL (/URI) or an internal named destination (/GoTo, resolved via /Names /Dests).
+            // The Link IR guarantees exactly one is set; prefer `dest` when present.
+            const action = node.dest !== undefined
+                ? `/A << /S /GoTo /D (${PdfBackend.escapePdfString(node.dest)}) >>`
+                : `/A << /S /URI /URI (${PdfBackend.escapePdfString(node.href ?? "")}) >>`;
+            const annot = objectManager.addObject(`<< /Type /Annot /Subtype /Link /Rect ${rect} /Border [0 0 0] ${action} >>`);
+            annotRefs.push(`${annot} 0 R`);
+        }
+        const annotsCode = annotRefs.length > 0 ? ` /Annots [${annotRefs.join(" ")}]` : "";
         // Tagging only: /StructParents links this page's marked content to the ParentTree, /Tabs /S makes the
         // logical structure order the tab/reading order (a PDF/UA requirement).
         const structAttrs = structCtx ? ` /StructParents ${structCtx.structParents} /Tabs /S` : "";
-        const pageObject = `<< /Type /Page /Parent ${parentObjectNumber} 0 R /Contents ${contentObjectNumber} 0 R /Resources <<\n/Font <<\n${fontReferences.join("\n")}\n>>\n${imageCode}${extGStateCode}${shadingCode}>>\n/MediaBox [0 0 ${width} ${height}]${structAttrs} >>`;
+        const pageObject = `<< /Type /Page /Parent ${parentObjectNumber} 0 R /Contents ${contentObjectNumber} 0 R /Resources <<\n/Font <<\n${fontReferences.join("\n")}\n>>\n${imageCode}${extGStateCode}${shadingCode}>>\n/MediaBox [0 0 ${width} ${height}]${structAttrs}${annotsCode} >>`;
         // Add page as new object; register its object number with the struct tree (for /Pg refs), then return it.
         const pageObjNum = objectManager.addObject(pageObject);
         if (structCtx)
             objectManager.struct.setPageObject(structCtx.structParents, pageObjNum);
+        // Bookmarks + named destinations: an `Outline`/`Anchor` IR node drew nothing; record it now that the
+        // page's object number is known. `node.y` is already Y-flipped to the page-space scroll target.
+        // PDFRenderer builds /Outlines and /Names /Dests at the end.
+        for (const node of flipped) {
+            if (node.type === "outline") {
+                objectManager.outline.add({
+                    title: node.title,
+                    level: node.level,
+                    pageObjNum,
+                    top: node.y,
+                });
+            }
+            else if (node.type === "anchor") {
+                objectManager.dests.add(node.name, { pageObjNum, top: node.y });
+            }
+        }
         return pageObjNum;
     }
 }