@jasy/pdf 1.0.0-alpha.6 → 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. */

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/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/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/pdf-backend.d.ts

@@ -39,6 +39,13 @@ export declare class PdfBackend {
      * text closes the string early and the remaining characters leak as raw operators.
      */
     static escapePdfString(text: string): string;
+    /**
+     * Builds the `[ ... ]` operand of a `TJ` from a run and its per-gap kern adjustments (em/1000, the
+     * sign the font declares - negative tightens). A `TJ` number moves the pen LEFT, so it is the
+     * NEGATED kern. Consecutive un-kerned glyphs stay in one encoded chunk, so `[(T) 40 (otal)]` rather
+     * than one chunk per glyph. `kerns[i]` is the adjustment AFTER code point `i`.
+     */
+    static kernedArray(text: string, kerns: number[], encode: (chunk: string) => string): string;
     /**
      * Returns the `/GSx gs` operator that selects a transparency state, or `""` when both
      * alphas are fully opaque. Opaque draws emit nothing here, so output stays

package/dist/renderer/pdf-backend.js

@@ -152,6 +152,27 @@ export class PdfBackend {
     static escapePdfString(text) {
         return text.replace(/\\/g, "\\\\").replace(/\(/g, "\\(").replace(/\)/g, "\\)");
     }
+    /**
+     * Builds the `[ ... ]` operand of a `TJ` from a run and its per-gap kern adjustments (em/1000, the
+     * sign the font declares - negative tightens). A `TJ` number moves the pen LEFT, so it is the
+     * NEGATED kern. Consecutive un-kerned glyphs stay in one encoded chunk, so `[(T) 40 (otal)]` rather
+     * than one chunk per glyph. `kerns[i]` is the adjustment AFTER code point `i`.
+     */
+    static kernedArray(text, kerns, encode) {
+        const chars = [...text];
+        let out = "";
+        let chunk = chars[0] ?? "";
+        for (let i = 0; i < kerns.length; i++) {
+            if (kerns[i] === 0) {
+                chunk += chars[i + 1];
+            }
+            else {
+                out += encode(chunk) + ` ${-kerns[i]} `;
+                chunk = chars[i + 1];
+            }
+        }
+        return `[${out}${encode(chunk)}]`;
+    }
     /**
      * Returns the `/GSx gs` operator that selects a transparency state, or `""` when both
      * alphas are fully opaque. Opaque draws emit nothing here, so output stays
@@ -242,18 +263,31 @@ export class PdfBackend {
                 const font = isCustom
                     ? om.getCustomFontResource(node.fontFamily, node.fontStyle)
                     : om.registerFont(node.fontFamily, node.fontStyle);
-                const textOp = isCustom
-                    ? `<${om.encodeCustomText(node.fontFamily, node.text, node.fontStyle)}>`
-                    : `(${PdfBackend.escapePdfString(node.text)})`;
+                const encode = (t) => isCustom
+                    ? `<${om.encodeCustomText(node.fontFamily, t, node.fontStyle)}>`
+                    : `(${PdfBackend.escapePdfString(t)})`;
+                // Kerning (if the document has it on): a `TJ` array with the font's per-pair adjustments
+                // between glyph chunks, measured into the layout by the SAME numbers (runAdvance). A plain
+                // `Tj` when the run has no kerning, byte-identical.
+                const kerns = om.kerningEnabled
+                    ? om.getKernPairs(node.text, node.fontFamily, node.fontStyle)
+                    : [];
+                const showOp = kerns.some((k) => k !== 0)
+                    ? `${PdfBackend.kernedArray(node.text, kerns, encode)} TJ`
+                    : `${encode(node.text)} Tj`;
+                // letterSpacing is the `Tc` operator: extra advance after EVERY glyph (an embedded
+                // Identity-H font too - that is `Tw`, word spacing, which only touches single-byte code 32).
+                const spacing = node.letterSpacing ? `${node.letterSpacing.toFixed(3)} Tc\n` : "";
                 const block = `BT\n` +
                     `${node.color.toPDFColorString()} rg ` +
                     `/F${font.fontIndex} ${node.fontSize} Tf ` +
                     `${node.x.toFixed(3)} ${node.y.toFixed(3)} Td ` +
-                    `${textOp} Tj\n` +
+                    `${showOp}\n` +
                     `ET\n`;
-                // Transparent text gets an isolating q/Q + gs; opaque text is byte-identical.
                 const gs = PdfBackend.alphaPrefix(om, node.color.getAlpha(), 1);
-                return gs ? `q\n${gs}${block}Q\n` : block;
+                // `Tc` is graphics state and would leak into the next run, so isolate it in q/Q - the same
+                // reason transparent text is isolated. A run with neither stays byte-identical.
+                return gs || spacing ? `q\n${gs}${spacing}${block}Q\n` : block;
             }
             case "image": {
                 // The backend owns PDF resource creation: register the XObject (using the

package/dist/renderer/pdf-document-class.js

@@ -88,6 +88,9 @@ export class PDFDocument {
         }
         if (config)
             this._objectManager.changePDFConfig(config);
+        // Kerning is on by default at the document level (the `renderToBytes` path sets the same). A
+        // bare `PDFObjectManager` still defaults OFF, so unit tests keep predictable un-kerned metrics.
+        this._objectManager.setKerning(true);
     }
     get objectManager() {
         return this._objectManager;

package/dist/renderer/pdf-document-renderer.js

@@ -1,6 +1,6 @@
-import { layoutPageBands, PageElement, resolvePageSize, } from "../elements/page-element.js";
+import { layoutPageBands, pageFrame, PageElement, resolvePageSize, } from "../elements/page-element.js";
 import { BoxConstraints } from "../layout/box-constraints.js";
-import { isFragmentable } from "../layout/fragmentation.js";
+import { isFragmentable, reportOverflow } from "../layout/fragmentation.js";
 import { PageRenderer } from "./page-renderer.js";
 export class PDFDocumentRenderer {
     static async render(document, objectManager, ctx) {
@@ -66,13 +66,19 @@ export class PDFDocumentRenderer {
         }
         // Header/footer repeat on every physical page, so the body only ever flows into the
         // band between them. Resolve that band once (config is already merged by pass 1).
+        // The frame is a throwaway: this pass only wants the band HEIGHTS, and an out-of-flow child
+        // contributes none. It exists because a `Positioned` in a band demands one; pass 2 builds the
+        // real frame (in `PageElement`) and drains it.
         const pageCtx = {
             metrics: ctx.metrics,
             pageConfig: config,
             textStyle: ctx.textStyle,
             onOverflow: ctx.onOverflow,
+            frame: pageFrame(config),
         };
         const { bodyWidth: width, bodyHeight: height } = layoutPageBands(config, header, footer, pageCtx);
+        // A `keepTogether` group compares its height against a FULL fresh page (this band), so thread it in.
+        pageCtx.pageBodyHeight = height;
         const pages = [];
         let region = children[0];
         let isFirstRegion = true;
@@ -84,17 +90,30 @@ export class PDFDocumentRenderer {
             }
             // pageCtx, not the document ctx: a descendant that reads `pageConfig` while being measured (a
             // `PageBuilder` sizing its provisional build) must see THIS page's geometry, not the document default.
-            const { fitted, remainder } = region.fragment(height, width, pageCtx);
+            const { fitted, remainder, forceBreak } = region.fragment(height, width, pageCtx);
             // Everything fits on one page: keep the ORIGINAL page so output is unchanged. Measuring inside
             // fragment() left its children at the measuring origin; pass B lays the page out again, which
-            // restores their real positions (layout is deterministic).
-            if (isFirstRegion && remainder === null) {
+            // restores their real positions (layout is deterministic). A consumed trailing `PageBreak`
+            // (forceBreak with no remainder) is the exception: render the packed `fitted` instead, which no
+            // longer holds the break marker, so the original with the break does not leak into the render pass.
+            if (isFirstRegion && remainder === null && !forceBreak) {
                 pages.push({ kind: "whole", page });
                 break;
             }
-            if (fitted) {
-                pages.push({ kind: "fragment", config, content: fitted, header, footer });
+            // TERMINATION GUARANTEE. Every page here has the full body height, so `fitted === null` means
+            // nothing fit even on a whole page - the region did not get smaller. Advancing to the
+            // (identical) remainder would loop forever. So we stop: place the region whole (clipped to the
+            // page) and surface it per the overflow policy. A step that shrinks nothing ends the loop, for
+            // ANY region - an oversized unbreakable block, a future keep-together group, or an engine bug.
+            if (fitted === null) {
+                // Measure the region's true height for the message (rare path, so the extra pass is free);
+                // pass B lays it out again, so this mutation does not leak.
+                const needed = region.calculateLayout(BoxConstraints.loose(width, Infinity), { x: 0, y: 0 }, pageCtx).height;
+                reportOverflow(region, needed, height, pageCtx.onOverflow ?? "ignore");
+                pages.push({ kind: "fragment", config, content: region, header, footer });
+                break;
             }
+            pages.push({ kind: "fragment", config, content: fitted, header, footer });
             region = remainder;
             isFirstRegion = false;
         }

package/dist/renderer/pdf-renderer.js

@@ -26,7 +26,11 @@ import { LinkRenderer } from "./link-renderer.js";
 import { BookmarkElement } from "../elements/layout/bookmark-element.js";
 import { BookmarkRenderer } from "./bookmark-renderer.js";
 import { AnchorElement } from "../elements/layout/anchor-element.js";
+import { PageBreakElement } from "../elements/layout/page-break-element.js";
 import { AnchorRenderer } from "./anchor-renderer.js";
+import { PageBreakRenderer } from "./page-break-renderer.js";
+import { KeepTogetherElement } from "../elements/layout/keep-together-element.js";
+import { KeepTogetherRenderer } from "./keep-together-renderer.js";
 import { PageBuilderElement } from "../elements/layout/page-builder-element.js";
 import { PageBuilderRenderer } from "./page-builder-renderer.js";
 import { RotatedElement } from "../elements/layout/rotated-element.js";
@@ -45,6 +49,8 @@ export class PDFRenderer {
         RendererRegistry.register(RectangleElement, RectangleRenderer.render);
         RendererRegistry.register(ExpandedElement, ExpandedRenderer.render);
         RendererRegistry.register(PaddingElement, PaddingRenderer.render);
+        RendererRegistry.register(PageBreakElement, PageBreakRenderer.render);
+        RendererRegistry.register(KeepTogetherElement, KeepTogetherRenderer.render);
         RendererRegistry.register(DefaultTextStyleElement, DefaultTextStyleRenderer.render);
         RendererRegistry.register(ImageElement, ImageRenderer.render);
         RendererRegistry.register(LineElement, LineRenderer.render);

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

@@ -4,7 +4,7 @@ import type { FontMetrics } from "../utils/font-metrics.js";
 import { IRNode } from "../ir/display-list.js";
 import { TextOverflow } from "../text/line-breaker.js";
 export declare class TextRenderer {
-    static calculateTextHeight(content: string | TextSegment[], fontSize: number, fontFamily: string, fontStyle: FontStyle, objectManager: FontMetrics, maxWidth: number, maxLines?: number, overflow?: TextOverflow, lineHeight?: number): number;
+    static calculateTextHeight(content: string | TextSegment[], fontSize: number, fontFamily: string, fontStyle: FontStyle, objectManager: FontMetrics, maxWidth: number, maxLines?: number, overflow?: TextOverflow, lineHeight?: number, letterSpacing?: number): number;
     static render(textElement: TextElement, objectManager: PDFObjectManager): Promise<IRNode[]>;
     private static _expandColorGlyphs;
     private static _glyphToPath;