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

package/dist/api/descriptor.js

@@ -1,5 +1,5 @@
 import { Text, Paragraph, span } from "./text.js";
-import { Column, Row, Box, Padding, Spacer, Expanded, Positioned, Link, Anchor, Bookmark, Rotated, RotatedBox, } from "./layout.js";
+import { Column, Row, Box, Padding, Spacer, PageBreak, keepTogether, Expanded, Positioned, Link, Anchor, Bookmark, Rotated, RotatedBox, } from "./layout.js";
 import { Divider, Image } from "./content.js";
 import { Page, Document, DefaultTextStyle } from "./structure.js";
 import { PageNumber, PageCount } from "./page-builder.js";
@@ -85,6 +85,8 @@ const REGISTRY = {
     padding: (props, children) => Padding(props.insets ?? 0, elementChildren(children)[0]),
     expanded: (props, children) => Expanded(props, elementChildren(children)[0]),
     spacer: (props) => Spacer(props?.flex),
+    "page-break": () => PageBreak(),
+    "keep-together": (_props, children) => keepTogether(elementChildren(children)),
     divider: (props) => Divider(props),
     image: (props) => Image(props.src, props),
     text: (props, children) => Text(textContent(children), props),

package/dist/api/layout.d.ts

@@ -1,8 +1,7 @@
-import { ContainerElement } from "../elements/container-element.js";
-import { RowElement } from "../elements/row-element.js";
-import { RectangleElement } from "../elements/rectangle-element.js";
 import { ExpandedElement } from "../elements/layout/expanded-element.js";
 import { PaddingElement } from "../elements/layout/padding-element.js";
+import { PageBreakElement } from "../elements/layout/page-break-element.js";
+import { KeepTogetherElement } from "../elements/layout/keep-together-element.js";
 import { PositionedElement, PositionedInsets } from "../elements/layout/positioned-element.js";
 import { LinkElement } from "../elements/layout/link-element.js";
 import { BookmarkElement } from "../elements/layout/bookmark-element.js";
@@ -28,13 +27,28 @@ export interface StackOptions {
      *  axis (`height: "50%"` only resolves where the parent bounds the height). */
     width?: SizeInput;
     height?: SizeInput;
+    /** Start this stack on a fresh page (CSS `break-before: page`, react-pdf's `break`). Ignored at the
+     *  top of a page. */
+    breakBefore?: boolean;
+    /** Start everything after this stack on a fresh page (CSS `break-after: page`). */
+    breakAfter?: boolean;
+    /** Try to keep this stack on one page (CSS `break-inside: avoid`). If it does not fit here but would
+     *  fit on a fresh page, it moves there whole; if it is taller than a whole page, it splits anyway. */
+    keepTogether?: boolean;
 }
 /** A vertical stack. `Column(children)` or `Column(opts, children)`. */
-export declare function Column(children: PDFElement[]): ContainerElement;
-export declare function Column(opts: StackOptions, children: PDFElement[]): ContainerElement;
+export declare function Column(children: PDFElement[]): PDFElement;
+export declare function Column(opts: StackOptions, children: PDFElement[]): PDFElement;
 /** A horizontal stack. `Row(children)` or `Row(opts, children)`. */
-export declare function Row(children: PDFElement[]): RowElement;
-export declare function Row(opts: StackOptions, children: PDFElement[]): RowElement;
+export declare function Row(children: PDFElement[]): PDFElement;
+export declare function Row(opts: StackOptions, children: PDFElement[]): PDFElement;
+/**
+ * Keep a group of elements on ONE page (CSS `break-inside: avoid`). `keepTogether([...])` stacks the
+ * children in a `Column` and refuses to split them across a page break - unless they do not fit on a
+ * fresh page at all, in which case they split anyway (so pagination always terminates). Equivalent to
+ * the `keepTogether` prop on `Box`/`Column`/`Row`.
+ */
+export declare function keepTogether(children: PDFElement[]): KeepTogetherElement;
 /** A bordered / filled box that wraps its children (locked §4). */
 export interface BoxOptions {
     /** Border (stroke) color. A box has a border only when `border` or `borderWidth` is set. */
@@ -65,22 +79,35 @@ export interface BoxOptions {
     /** `"hidden"` crops children to the box (rounded corners included); `"visible"` (default) lets a
      *  `Positioned` child spill over the edge. */
     overflow?: "hidden" | "visible";
+    /** Start this box on a fresh page (CSS `break-before: page`, react-pdf's `break`). Ignored at the top
+     *  of a page. */
+    breakBefore?: boolean;
+    /** Start everything after this box on a fresh page (CSS `break-after: page`). */
+    breakAfter?: boolean;
+    /** Try to keep this box on one page (CSS `break-inside: avoid`). Moves whole to a fresh page if it
+     *  would fit there; splits anyway if it is taller than a whole page. */
+    keepTogether?: boolean;
 }
 /**
  * A box: maps to a `RectangleElement` (fill + border + radius) whose children are stacked
  * inside it, optionally inset by `padding` (a `PaddingElement` wrapping a `Column` of the
  * children). With no `border`/`borderWidth` the box has no outline (`borderWidth` 0).
  */
-export declare function Box(children: PDFElement[]): RectangleElement;
-export declare function Box(opts: BoxOptions, children: PDFElement[]): RectangleElement;
+export declare function Box(children: PDFElement[]): PDFElement;
+export declare function Box(opts: BoxOptions, children: PDFElement[]): PDFElement;
 /** Insets a single child by `padding` (a number / `{x,y}` / `{top,…}` / 4-tuple). */
 export declare function Padding(padding: Insets, child: PDFElement): PaddingElement;
 /**
- * Places a child OUT OF FLOW, relative to the nearest enclosing `relative` Box. Two ways, pick per
- * axis: pin to EDGES - `Positioned({ top, left, right, bottom }, child)`, where a negative value
- * pokes into / out of the corner (a badge, a tab, a ribbon) and pinning both sides stretches; or
- * ANCHOR + nudge - `Positioned({ h: "center", v: "end", x: -10, y: -8 }, child)`, i.e. centered /
- * end-aligned with a pixel offset. An edge wins over an anchor on the same axis.
+ * Places a child OUT OF FLOW, relative to the nearest enclosing `relative` Box - or, with none, to
+ * the page's content box. Two ways, pick per axis: pin to EDGES - `Positioned({ top, left, right,
+ * bottom }, child)`, where a negative value pokes into / out of the corner (a badge, a tab, a
+ * ribbon) and pinning both sides stretches; or ANCHOR + nudge - `Positioned({ h: "center", v: "end",
+ * x: -10, y: -8 }, child)`, i.e. centered / end-aligned with a pixel offset. An edge wins over an
+ * anchor on the same axis.
+ *
+ * A `Positioned` in a `Page`'s `header` or `footer` repeats on EVERY page and takes no space in the
+ * band, which is how you draw a watermark, a draft stamp or a corner ribbon across a document. It
+ * anchors to the page, not to the band, so `bottom: 0` is the foot of the page.
  */
 export declare function Positioned(opts: PositionedInsets, child: PDFElement): PositionedElement;
 /**
@@ -137,6 +164,12 @@ export declare function RotatedBox(opts: {
  * and `b` to the edges. `flex` weights it against other flex children (default 1).
  */
 export declare function Spacer(flex?: number): ExpandedElement;
+/**
+ * A forced page break. Put it in a `Column` (or any vertical flow) and everything AFTER it starts on
+ * a fresh page, no matter how much space is left: `Column([intro, PageBreak(), chapterTwo])`. It takes
+ * no space and draws nothing. Works nested, and a break wins over `keepTogether`.
+ */
+export declare function PageBreak(): PageBreakElement;
 export interface ExpandedOptions {
     /** Share of the leftover space vs other flex children (default 1). */
     flex?: number;

package/dist/api/layout.js

@@ -3,6 +3,8 @@ import { RowElement } from "../elements/row-element.js";
 import { RectangleElement } from "../elements/rectangle-element.js";
 import { ExpandedElement } from "../elements/layout/expanded-element.js";
 import { PaddingElement } from "../elements/layout/padding-element.js";
+import { PageBreakElement } from "../elements/layout/page-break-element.js";
+import { KeepTogetherElement } from "../elements/layout/keep-together-element.js";
 import { PositionedElement } from "../elements/layout/positioned-element.js";
 import { LinkElement } from "../elements/layout/link-element.js";
 import { BookmarkElement } from "../elements/layout/bookmark-element.js";
@@ -24,25 +26,44 @@ function stackSize(opts) {
 const DEFAULT_CROSS = "start";
 export function Column(a, b) {
     const { opts, children } = splitArgs(a, b);
-    return new ContainerElement({
+    return maybeKeepTogether(opts, new ContainerElement({
         x: 0,
         y: 0,
         children,
         gap: opts.gap,
         main: opts.justify, // undefined → engine default `start` (matches §5)
         cross: opts.align ?? DEFAULT_CROSS,
+        breakBefore: opts.breakBefore,
+        breakAfter: opts.breakAfter,
         ...stackSize(opts),
-    });
+    }));
 }
 export function Row(a, b) {
     const { opts, children } = splitArgs(a, b);
-    return new RowElement({
+    return maybeKeepTogether(opts, new RowElement({
         children,
         gap: opts.gap,
         main: opts.justify,
         cross: opts.align ?? DEFAULT_CROSS,
+        breakBefore: opts.breakBefore,
+        breakAfter: opts.breakAfter,
         ...stackSize(opts),
-    });
+    }));
+}
+/** Wraps `element` in a `keepTogether` group when the `keepTogether` option is set; otherwise returns it
+ *  unchanged (byte-identical). Shared by the `Box`/`Column`/`Row` prop shortcut. */
+function maybeKeepTogether(opts, element) {
+    return opts.keepTogether ? new KeepTogetherElement({ child: element }) : element;
+}
+/**
+ * Keep a group of elements on ONE page (CSS `break-inside: avoid`). `keepTogether([...])` stacks the
+ * children in a `Column` and refuses to split them across a page break - unless they do not fit on a
+ * fresh page at all, in which case they split anyway (so pagination always terminates). Equivalent to
+ * the `keepTogether` prop on `Box`/`Column`/`Row`.
+ */
+export function keepTogether(children) {
+    const child = children.length === 1 ? children[0] : Column(children);
+    return new KeepTogetherElement({ child });
 }
 export function Box(a, b) {
     const { opts, children } = splitArgs(a, b);
@@ -66,7 +87,7 @@ export function Box(a, b) {
     // A point size fills `width`/`height`; a percentage fills `widthFactor`/`heightFactor`.
     const w = opts.width !== undefined ? toDimension(opts.width) : undefined;
     const h = opts.height !== undefined ? toDimension(opts.height) : undefined;
-    return new RectangleElement({
+    return maybeKeepTogether(opts, new RectangleElement({
         x: 0,
         y: 0,
         children: content,
@@ -88,18 +109,25 @@ export function Box(a, b) {
             : undefined,
         relative: opts.relative,
         overflow: opts.overflow,
-    });
+        breakBefore: opts.breakBefore,
+        breakAfter: opts.breakAfter,
+    }));
 }
 /** Insets a single child by `padding` (a number / `{x,y}` / `{top,…}` / 4-tuple). */
 export function Padding(padding, child) {
     return new PaddingElement({ margin: toEdges(padding), child });
 }
 /**
- * Places a child OUT OF FLOW, relative to the nearest enclosing `relative` Box. Two ways, pick per
- * axis: pin to EDGES - `Positioned({ top, left, right, bottom }, child)`, where a negative value
- * pokes into / out of the corner (a badge, a tab, a ribbon) and pinning both sides stretches; or
- * ANCHOR + nudge - `Positioned({ h: "center", v: "end", x: -10, y: -8 }, child)`, i.e. centered /
- * end-aligned with a pixel offset. An edge wins over an anchor on the same axis.
+ * Places a child OUT OF FLOW, relative to the nearest enclosing `relative` Box - or, with none, to
+ * the page's content box. Two ways, pick per axis: pin to EDGES - `Positioned({ top, left, right,
+ * bottom }, child)`, where a negative value pokes into / out of the corner (a badge, a tab, a
+ * ribbon) and pinning both sides stretches; or ANCHOR + nudge - `Positioned({ h: "center", v: "end",
+ * x: -10, y: -8 }, child)`, i.e. centered / end-aligned with a pixel offset. An edge wins over an
+ * anchor on the same axis.
+ *
+ * A `Positioned` in a `Page`'s `header` or `footer` repeats on EVERY page and takes no space in the
+ * band, which is how you draw a watermark, a draft stamp or a corner ribbon across a document. It
+ * anchors to the page, not to the band, so `bottom: 0` is the foot of the page.
  */
 export function Positioned(opts, child) {
     return new PositionedElement({ child, ...opts });
@@ -161,6 +189,14 @@ export function RotatedBox(opts, child) {
 export function Spacer(flex = 1) {
     return new ExpandedElement({ flex, child: Column([]) });
 }
+/**
+ * A forced page break. Put it in a `Column` (or any vertical flow) and everything AFTER it starts on
+ * a fresh page, no matter how much space is left: `Column([intro, PageBreak(), chapterTwo])`. It takes
+ * no space and draws nothing. Works nested, and a break wins over `keepTogether`.
+ */
+export function PageBreak() {
+    return new PageBreakElement();
+}
 export function Expanded(a, b) {
     const isOptsForm = b !== undefined;
     const opts = (isOptsForm ? a : {});

package/dist/api/structure.d.ts

@@ -132,6 +132,11 @@ export interface RenderOptions {
     standardFonts?: boolean;
     /** FlateDecode-compress the streams (default true). Set false for a greppable, uncompressed PDF. */
     compress?: boolean;
+    /** Kern the text - ON by default (still labelled experimental while we validate against react-pdf).
+     *  Emits `TJ` adjustments from the font's own pairs: standard-14 (AFM), embedded `kern` table, and
+     *  embedded `GPOS` Type 2, so every font path kerns. Set `false` to opt out (byte-identical to the
+     *  pre-kerning output). Verified against headless Chrome and measured == drawn to the thousandth. */
+    kerning?: boolean;
     /** What to do when content is taller than a page and cannot break: `"error"` throws (default),
      *  `"warn"` logs and clips, `"ignore"` clips silently. It is always clipped either way. */
     onOverflow?: OverflowPolicy;

package/dist/api/structure.js

@@ -137,6 +137,7 @@ export async function renderPdf(doc, options) {
             const om = this.objectManager;
             om.setCompress(options?.compress !== false); // FlateDecode streams by default
             om.setOverflowPolicy(options?.onOverflow ?? "error");
+            om.setKerning(options?.kerning !== false); // on by default (experimental); `kerning:false` opts out
             for (const [name, value] of Object.entries(fonts)) {
                 if (isFontBytes(value)) {
                     om.registerCustomFont(name, value);

package/dist/api/text.d.ts

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

package/dist/api/text.js

@@ -50,6 +50,9 @@ export function span(text, style = {}) {
             ? toFontStyle(style.bold, style.italic)
             : undefined,
         fontColor: style.color !== undefined ? toColor(style.color) : undefined,
+        underline: style.underline,
+        strikethrough: style.strikethrough,
+        letterSpacing: style.letterSpacing,
         href: style.href,
         dest: style.to,
     };
@@ -79,6 +82,10 @@ export function Text(content, opts = {}) {
         maxLines: opts.maxLines,
         overflow: opts.overflow,
         lineHeight: opts.lineHeight,
+        underline: opts.underline,
+        strikethrough: opts.strikethrough,
+        skipInk: opts.skipInk,
+        letterSpacing: opts.letterSpacing,
         role: opts.role,
     });
 }
@@ -103,5 +110,13 @@ export function toTextStyleOverride(opts) {
         style.textAlignment = ALIGN[opts.align];
     if (opts.lineHeight !== undefined)
         style.lineHeight = opts.lineHeight;
+    if (opts.underline !== undefined)
+        style.underline = opts.underline;
+    if (opts.strikethrough !== undefined)
+        style.strikethrough = opts.strikethrough;
+    if (opts.skipInk !== undefined)
+        style.skipInk = opts.skipInk;
+    if (opts.letterSpacing !== undefined)
+        style.letterSpacing = opts.letterSpacing;
     return style;
 }

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

@@ -12,14 +12,22 @@ interface ContainerElementParams extends SizedElement, WithChildren {
     /** Width/height as a fraction (0..1) of the offered box instead of `width`/`height` (relative sizing). */
     widthFactor?: number;
     heightFactor?: number;
+    /** Start this stack on a fresh page (CSS `break-before: page`). */
+    breakBefore?: boolean;
+    /** Start everything after this stack on a fresh page (CSS `break-after: page`). */
+    breakAfter?: boolean;
 }
 export declare class ContainerElement extends SizedPDFElement implements Fragmentable {
     private children;
     private gap;
     private main;
     private cross;
+    private breakBefore;
+    private breakAfter;
     private requested;
-    constructor({ x, y, width, height, children, gap, main, cross, widthFactor, heightFactor, }: ContainerElementParams);
+    constructor({ x, y, width, height, children, gap, main, cross, widthFactor, heightFactor, breakBefore, breakAfter, }: ContainerElementParams);
+    breaksBefore(): boolean;
+    breaksAfter(): boolean;
     /**
      * Splits the vertical stack across pages. Children are measured against the content
      * width and packed until one would exceed `maxHeight`. That straddling child is itself
@@ -31,6 +39,7 @@ export declare class ContainerElement extends SizedPDFElement implements Fragmen
      * Flex children make the container absorb the leftover space, so it never overflows -
      * in that case we don't fragment and hand the whole container back as `fitted`.
      */
+    hasForcedBreak(): boolean;
     fragment(maxHeight: number, width: number, ctx: LayoutContext): FragmentResult;
     private cloneWithChildren;
     relativeSizeFactor(horizontal: boolean): number | undefined;

package/dist/elements/container-element.js

@@ -1,15 +1,23 @@
 import { FlexLayoutHelper, VERTICAL_AXIS } from "../utils/flex-layout.js";
 import { resolveExtent } from "../layout/box-constraints.js";
-import { packChildren } from "../layout/fragmentation.js";
+import { childrenForceBreak, packChildren, } from "../layout/fragmentation.js";
 import { FlexiblePDFElement, SizedPDFElement, } from "./pdf-element.js";
 export class ContainerElement extends SizedPDFElement {
-    constructor({ x, y, width, height, children, gap, main, cross, widthFactor, heightFactor, }) {
+    constructor({ x, y, width, height, children, gap, main, cross, widthFactor, heightFactor, breakBefore, breakAfter, }) {
         super({ x, y, width, height });
         this.children = children;
         this.gap = gap ?? 0;
         this.main = main ?? "start";
         this.cross = cross ?? "stretch";
         this.requested = { width, height, widthFactor, heightFactor };
+        this.breakBefore = breakBefore ?? false;
+        this.breakAfter = breakAfter ?? false;
+    }
+    breaksBefore() {
+        return this.breakBefore;
+    }
+    breaksAfter() {
+        return this.breakAfter;
     }
     /**
      * Splits the vertical stack across pages. Children are measured against the content
@@ -22,18 +30,27 @@ export class ContainerElement extends SizedPDFElement {
      * Flex children make the container absorb the leftover space, so it never overflows -
      * in that case we don't fragment and hand the whole container back as `fitted`.
      */
+    hasForcedBreak() {
+        return childrenForceBreak(this.children);
+    }
     fragment(maxHeight, width, ctx) {
-        const { fitted, remainder } = packChildren(this.children, maxHeight, width, ctx, this.gap);
-        // Fits as one region: hand the whole container back so the page renders unchanged
-        // (its normal layout distributes flex / fills the page).
-        if (remainder.length === 0)
+        const { fitted, remainder, forceBreak } = packChildren(this.children, maxHeight, width, ctx, this.gap);
+        // Fits as one region with no forced cut: hand the whole container back so the page renders
+        // unchanged (its normal layout distributes flex / fills the page). A forced break is excluded
+        // here even when nothing follows it (a trailing `PageBreak`): return the packed children, which
+        // no longer hold the consumed break marker, so it does not leak into the render pass.
+        if (remainder.length === 0 && !forceBreak)
             return { fitted: this, remainder: null };
         return {
             fitted: this.cloneWithChildren(fitted),
-            remainder: this.cloneWithChildren(remainder),
+            // Only the CONTINUATION carries `breakAfter`, so a stack that splits across pages still breaks
+            // after its LAST fragment (not after the first one). `breakBefore` is dropped on both: it was
+            // already honoured by the parent before this stack was ever fragmented.
+            remainder: remainder.length === 0 ? null : this.cloneWithChildren(remainder, this.breakAfter),
+            forceBreak,
         };
     }
-    cloneWithChildren(children) {
+    cloneWithChildren(children, breakAfter = false) {
         return new ContainerElement({
             x: this.x,
             y: this.y,
@@ -45,6 +62,7 @@ export class ContainerElement extends SizedPDFElement {
             gap: this.gap,
             main: this.main,
             cross: this.cross,
+            breakAfter,
         });
     }
     relativeSizeFactor(horizontal) {

package/dist/elements/index.d.ts

@@ -6,6 +6,8 @@ export * from "./rectangle-element.js";
 export * from "./image-element.js";
 export * from "./layout/expanded-element.js";
 export * from "./layout/padding-element.js";
+export * from "./layout/page-break-element.js";
+export * from "./layout/keep-together-element.js";
 export * from "./layout/default-text-style-element.js";
 export * from "./layout/positioned-element.js";
 export * from "./layout/link-element.js";

package/dist/elements/index.js

@@ -6,6 +6,8 @@ export * from "./rectangle-element.js";
 export * from "./image-element.js";
 export * from "./layout/expanded-element.js";
 export * from "./layout/padding-element.js";
+export * from "./layout/page-break-element.js";
+export * from "./layout/keep-together-element.js";
 export * from "./layout/default-text-style-element.js";
 export * from "./layout/positioned-element.js";
 export * from "./layout/link-element.js";

package/dist/elements/layout/keep-together-element.d.ts

@@ -0,0 +1,42 @@
+import { BoxConstraints, Offset, Size } from "../../layout/box-constraints.js";
+import { Fragmentable, FragmentResult } from "../../layout/fragmentation.js";
+import { LayoutContext, PDFElement } from "../pdf-element.js";
+/**
+ * A layout-TRANSPARENT wrapper that tries to keep its content on ONE page (CSS `break-inside: avoid`).
+ * It delegates all layout and rendering to its child, so the visual result is byte-identical to the
+ * unwrapped content; only pagination behaves differently.
+ *
+ * The rule, decided in `fragment`:
+ *   1. Fits in the space offered here           -> place it whole.
+ *   2. Does not fit here but fits on a FRESH    -> veto the split: defer the whole group to the next
+ *      full page                                   page (`fitted: null`), so it lands together there.
+ *   3. Taller than a whole page                 -> drop the veto and split normally. A group that can
+ *                                                  never fit on one page must break, or pagination
+ *                                                  could not terminate. Inner `keepTogether`s survive
+ *                                                  this (they are separate elements, re-evaluated when
+ *                                                  the child splits) - graceful degrade, outer->inner.
+ *
+ * A forced page break inside the group (a `PageBreak`, or a `breakBefore`/`breakAfter`) contradicts
+ * keeping it together: the break wins (CSS behaves the same), and we WARN once rather than silently
+ * swallowing either intent.
+ */
+export declare class KeepTogetherElement extends PDFElement implements Fragmentable {
+    private child;
+    private warnedBreakConflict;
+    constructor({ child }: {
+        child: PDFElement;
+    });
+    calculateLayout(constraints: BoxConstraints, offset: Offset, ctx: LayoutContext): Size;
+    relativeSizeFactor(horizontal: boolean): number | undefined;
+    needsBoundedMain(horizontal: boolean): boolean;
+    hasForcedBreak(): boolean;
+    breaksBefore(): boolean;
+    breaksAfter(): boolean;
+    fragment(maxHeight: number, width: number, ctx: LayoutContext): FragmentResult;
+    /** Delegate the actual split to the child, unwrapping - once we have decided to break the group, the
+     *  pieces just flow (any INNER keepTogether lives in the child subtree and still vetoes there). */
+    private splitChild;
+    getProps(): {
+        child: PDFElement;
+    };
+}

package/dist/elements/layout/keep-together-element.js

@@ -0,0 +1,85 @@
+import { BoxConstraints } from "../../layout/box-constraints.js";
+import { isFragmentable } from "../../layout/fragmentation.js";
+import { PDFElement } from "../pdf-element.js";
+/**
+ * A layout-TRANSPARENT wrapper that tries to keep its content on ONE page (CSS `break-inside: avoid`).
+ * It delegates all layout and rendering to its child, so the visual result is byte-identical to the
+ * unwrapped content; only pagination behaves differently.
+ *
+ * The rule, decided in `fragment`:
+ *   1. Fits in the space offered here           -> place it whole.
+ *   2. Does not fit here but fits on a FRESH    -> veto the split: defer the whole group to the next
+ *      full page                                   page (`fitted: null`), so it lands together there.
+ *   3. Taller than a whole page                 -> drop the veto and split normally. A group that can
+ *                                                  never fit on one page must break, or pagination
+ *                                                  could not terminate. Inner `keepTogether`s survive
+ *                                                  this (they are separate elements, re-evaluated when
+ *                                                  the child splits) - graceful degrade, outer->inner.
+ *
+ * A forced page break inside the group (a `PageBreak`, or a `breakBefore`/`breakAfter`) contradicts
+ * keeping it together: the break wins (CSS behaves the same), and we WARN once rather than silently
+ * swallowing either intent.
+ */
+export class KeepTogetherElement extends PDFElement {
+    constructor({ child }) {
+        super();
+        this.warnedBreakConflict = false;
+        this.child = child;
+    }
+    calculateLayout(constraints, offset, ctx) {
+        return this.child.calculateLayout(constraints, offset, ctx);
+    }
+    // Transparent: forward the sizing hints the flex parent reads, so a %-sized or Spacer-holding child
+    // keeps working when it is wrapped (the wrapper must not swallow these).
+    relativeSizeFactor(horizontal) {
+        return this.child.relativeSizeFactor(horizontal);
+    }
+    needsBoundedMain(horizontal) {
+        return this.child.needsBoundedMain(horizontal);
+    }
+    // Transparent to break control: a break-before/after on the wrapped element still applies to the group
+    // as a whole, and an inner forced break still forces the parent to fragment us (so `fragment` runs).
+    hasForcedBreak() {
+        return this.child.hasForcedBreak();
+    }
+    breaksBefore() {
+        return this.child.breaksBefore();
+    }
+    breaksAfter() {
+        return this.child.breaksAfter();
+    }
+    fragment(maxHeight, width, ctx) {
+        // Contradiction: a forced break inside the group beats keeping it together. Split at the break by
+        // delegating to the child (which honours it), and say so once - never keep such a group whole.
+        if (this.child.hasForcedBreak()) {
+            if (!this.warnedBreakConflict) {
+                this.warnedBreakConflict = true;
+                console.warn("keepTogether contains a forced page break (PageBreak / breakBefore / breakAfter). The break " +
+                    "wins and the group is split. Remove the break, or the keepTogether, to resolve this.");
+            }
+            return this.splitChild(maxHeight, width, ctx);
+        }
+        const natural = this.child.calculateLayout(BoxConstraints.loose(width, Infinity), { x: 0, y: 0 }, ctx).height;
+        // 1. Fits in the offered space: keep whole.
+        if (natural <= maxHeight)
+            return { fitted: this, remainder: null };
+        // 2. Would fit on a fresh full page: veto the split, defer the whole group to the next page. Only
+        //    reachable in a PARTIAL region (something is already on this page); alone on a full page,
+        //    `maxHeight` IS the page body, so `natural > maxHeight` means case 3, never this.
+        const pageBody = ctx.pageBodyHeight ?? maxHeight;
+        if (natural <= pageBody)
+            return { fitted: null, remainder: this };
+        // 3. Bigger than a whole page: it can never be kept together, so split it.
+        return this.splitChild(maxHeight, width, ctx);
+    }
+    /** Delegate the actual split to the child, unwrapping - once we have decided to break the group, the
+     *  pieces just flow (any INNER keepTogether lives in the child subtree and still vetoes there). */
+    splitChild(maxHeight, width, ctx) {
+        if (!isFragmentable(this.child))
+            return { fitted: null, remainder: this };
+        return this.child.fragment(maxHeight, width, ctx);
+    }
+    getProps() {
+        return { child: this.child };
+    }
+}

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

@@ -15,6 +15,9 @@ export declare class PaddingElement extends SizedPDFElement implements Fragmenta
      * child can't be split, the whole padding moves on as the remainder.
      */
     fragment(maxHeight: number, width: number, ctx: LayoutContext): FragmentResult;
+    hasForcedBreak(): boolean;
+    breaksBefore(): boolean;
+    breaksAfter(): boolean;
     private cloneWithChild;
     calculateLayout(constraints: BoxConstraints, offset: Offset, ctx: LayoutContext): Size;
     getProps(): {

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

@@ -25,8 +25,20 @@ export class PaddingElement extends SizedPDFElement {
         return {
             fitted: split.fitted ? this.cloneWithChild(split.fitted) : null,
             remainder: split.remainder ? this.cloneWithChild(split.remainder) : null,
+            forceBreak: split.forceBreak,
         };
     }
+    hasForcedBreak() {
+        return this.child.hasForcedBreak();
+    }
+    // Padding is a transparent single-child wrapper, so a break-before/after on the wrapped element must
+    // still be seen by the parent packer at this boundary (otherwise it is swallowed).
+    breaksBefore() {
+        return this.child.breaksBefore();
+    }
+    breaksAfter() {
+        return this.child.breaksAfter();
+    }
     cloneWithChild(child) {
         return new PaddingElement({ margin: this.margin, child });
     }

package/dist/elements/layout/page-break-element.d.ts

@@ -0,0 +1,17 @@
+import { BoxConstraints, Offset, Size } from "../../layout/box-constraints.js";
+import { LayoutContext, PDFElement } from "../pdf-element.js";
+/**
+ * A forced page break. Placed in a flow (a `Column`/`Row`/`Box`), it makes everything AFTER it start
+ * on a fresh page, no matter how much space is left. It takes zero space and draws nothing - the
+ * pagination packer consumes it at the cut, so it never reaches the render pass.
+ *
+ * Nesting works: a break deep inside a container is honoured because the packer fragments any child
+ * whose subtree `hasForcedBreak()`, and the resulting `forceBreak` bubbles up so the outer flow stops
+ * too. A break wins over a `keepTogether` (a forced break cannot be avoided) - CSS behaves the same.
+ */
+export declare class PageBreakElement extends PDFElement {
+    calculateLayout(_constraints: BoxConstraints, _offset: Offset, _ctx: LayoutContext): Size;
+    isPageBreak(): boolean;
+    hasForcedBreak(): boolean;
+    getProps(): Record<string, never>;
+}