@jasy/pdf 1.0.0-alpha.1 → 1.0.0-alpha.3

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

@@ -1,8 +1,8 @@
-import { Color } from "../common/color";
-import { BoxConstraints, Offset, Size } from "../layout/box-constraints";
-import { Fragmentable, FragmentResult } from "../layout/fragmentation";
-import { LayoutContext, PDFElement, SizedElement, SizedPDFElement, WithChildren } from "./pdf-element";
-/** Per-side border colours. When set, each present side is stroked individually (sharp
+import { Color } from "../common/color.js";
+import { BoxConstraints, Offset, Size } from "../layout/box-constraints.js";
+import { Fragmentable, FragmentResult } from "../layout/fragmentation.js";
+import { LayoutContext, PDFElement, SizedElement, SizedPDFElement, WithChildren } from "./pdf-element.js";
+/** Per-side border colors. When set, each present side is stroked individually (sharp
  *  corners), instead of the uniform `color` border - this is what enables grid lines. */
 export interface SideBorders {
     top?: Color;
@@ -18,6 +18,11 @@ interface RectangleElementParams extends SizedElement, WithChildren {
     radius?: number;
     /** Individual side borders; overrides the uniform `color` border when present. */
     sideBorders?: SideBorders;
+    /** When true, this box is a positioning frame for `Positioned` descendants (CSS `relative`). */
+    relative?: boolean;
+    /** `"hidden"` crops children to the box (CSS `overflow: hidden`); `"visible"` (default) lets a
+     *  `Positioned` child spill over the edge. */
+    overflow?: "hidden" | "visible";
 }
 export declare class RectangleElement extends SizedPDFElement implements Fragmentable {
     private children;
@@ -26,8 +31,10 @@ export declare class RectangleElement extends SizedPDFElement implements Fragmen
     private borderWidth;
     private radius;
     private sideBorders?;
+    private relative;
+    private overflow;
     private sizeMemory;
-    constructor({ children, color, backgroundColor, borderWidth, width, height, radius, sideBorders, }: RectangleElementParams);
+    constructor({ children, color, backgroundColor, borderWidth, width, height, radius, sideBorders, relative, overflow, }: RectangleElementParams);
     /**
      * Splits the bordered box across pages (box-decoration-break: clone - every fragment
      * gets its own full border). The children stack is packed into the space left after
@@ -50,6 +57,7 @@ export declare class RectangleElement extends SizedPDFElement implements Fragmen
         borderWidth: number;
         radius: number;
         sideBorders: SideBorders | undefined;
+        overflow: "hidden" | "visible";
     };
 }
 export {};

package/dist/elements/rectangle-element.js

@@ -1,21 +1,20 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.RectangleElement = void 0;
-const color_1 = require("../common/color");
-const box_constraints_1 = require("../layout/box-constraints");
-const fragmentation_1 = require("../layout/fragmentation");
-const pdf_element_1 = require("./pdf-element");
-class RectangleElement extends pdf_element_1.SizedPDFElement {
-    constructor({ children = [], color = new color_1.Color(0, 0, 0), backgroundColor, borderWidth, width, height, radius, sideBorders, }) {
+import { Color } from "../common/color.js";
+import { BoxConstraints } from "../layout/box-constraints.js";
+import { packChildren } from "../layout/fragmentation.js";
+import { SizedPDFElement, } from "./pdf-element.js";
+export class RectangleElement extends SizedPDFElement {
+    constructor({ children = [], color = new Color(0, 0, 0), backgroundColor, borderWidth, width, height, radius, sideBorders, relative, overflow, }) {
         super({ x: 0, y: 0, width, height });
         this.children = [];
         this.children = children;
         this.color = color;
         this.backgroundColor = backgroundColor;
         // `?? 1` (not `|| 1`) so an explicit `0` means "no border" instead of snapping to 1.
-        this.borderWidth = borderWidth !== null && borderWidth !== void 0 ? borderWidth : 1;
-        this.radius = radius !== null && radius !== void 0 ? radius : 0;
+        this.borderWidth = borderWidth ?? 1;
+        this.radius = radius ?? 0;
         this.sideBorders = sideBorders;
+        this.relative = relative ?? false;
+        this.overflow = overflow ?? "visible";
         this.sizeMemory = { x: 0, y: 0, width, height };
     }
     /**
@@ -27,17 +26,16 @@ class RectangleElement extends pdf_element_1.SizedPDFElement {
      * box is sized by what it actually holds on each page.
      */
     fragment(maxHeight, width, ctx) {
-        var _a;
-        const boxWidth = (_a = this.sizeMemory.width) !== null && _a !== void 0 ? _a : width;
+        const boxWidth = this.sizeMemory.width ?? width;
         const innerWidth = Math.max(0, boxWidth - 2 * this.borderWidth);
         // Border-box: the content is inset by the border on top and bottom, so a fragment
         // holding `c` of content is `c + 2*border` tall. (Derived, not a fudge factor.)
         const innerMaxHeight = maxHeight - 2 * this.borderWidth;
-        const { fitted, remainder } = (0, fragmentation_1.packChildren)(this.children, innerMaxHeight, innerWidth, ctx);
+        const { fitted, remainder } = packChildren(this.children, innerMaxHeight, innerWidth, ctx);
         if (remainder.length === 0)
             return { fitted: this, remainder: null };
         const contentHeight = (kids) => kids.reduce((sum, child) => sum +
-            child.calculateLayout(box_constraints_1.BoxConstraints.loose(innerWidth, Infinity), { x: 0, y: 0 }, ctx)
+            child.calculateLayout(BoxConstraints.loose(innerWidth, Infinity), { x: 0, y: 0 }, ctx)
                 .height, 0);
         return {
             fitted: this.cloneWithChildren(fitted, contentHeight(fitted) + 2 * this.borderWidth),
@@ -56,10 +54,11 @@ class RectangleElement extends pdf_element_1.SizedPDFElement {
             borderWidth: this.borderWidth,
             radius: this.radius,
             sideBorders: this.sideBorders,
+            relative: this.relative,
+            overflow: this.overflow,
         });
     }
     calculateLayout(constraints, offset, ctx) {
-        var _a, _b, _c;
         // Width: an explicit size wins (clamped), else fill the offered box. (Without this a
         // fixed box would balloon to the parent's size.)
         this.width =
@@ -68,6 +67,9 @@ class RectangleElement extends pdf_element_1.SizedPDFElement {
                 : constraints.hasBoundedWidth
                     ? constraints.maxWidth
                     : this.width;
+        // Width shrink-wrap: no explicit width AND an unbounded region (e.g. a `Box` badge inside a
+        // `Positioned`). Resolved after the children are measured, just below.
+        const shrinkWrapWidth = this.sizeMemory.width === undefined && !constraints.hasBoundedWidth;
         // Height: explicit wins; otherwise FILL a bounded region (e.g. inside an Expanded) but
         // SHRINK-WRAP the content in an unbounded one (a note box in a stack). Shrink-wrap is
         // resolved after the children are measured, just below.
@@ -80,26 +82,47 @@ class RectangleElement extends pdf_element_1.SizedPDFElement {
                     : this.height;
         this.x = this.sizeMemory.x + offset.x;
         this.y = this.sizeMemory.y + offset.y;
+        // A `relative` box is a positioning frame: thread a fresh frame to the subtree so any
+        // `Positioned` descendant registers against it (out of flow), then drain it below once the
+        // box is sized. A plain box leaves `ctx` untouched -> byte-identical.
+        const frame = this.relative
+            ? { origin: { x: 0, y: 0 }, size: { width: 0, height: 0 }, place: [] }
+            : undefined;
+        const childCtx = frame ? { ...ctx, frame } : ctx;
         // Lay out children stacked inside the border (inset by the border width). Width is
         // finalized here; height is left unbounded so each child sizes to its own content.
-        const innerWidth = Math.max(0, ((_a = this.width) !== null && _a !== void 0 ? _a : 0) - 2 * this.borderWidth);
+        const innerWidth = shrinkWrapWidth
+            ? Infinity
+            : Math.max(0, (this.width ?? 0) - 2 * this.borderWidth);
+        let contentWidth = 0;
         let contentHeight = 0;
         let yCursor = this.y + this.borderWidth;
         for (const child of this.children) {
-            const childSize = child.calculateLayout(box_constraints_1.BoxConstraints.loose(innerWidth, Infinity), { x: this.x + this.borderWidth, y: yCursor }, ctx);
+            const childSize = child.calculateLayout(BoxConstraints.loose(innerWidth, Infinity), { x: this.x + this.borderWidth, y: yCursor }, childCtx);
             yCursor += childSize.height;
             contentHeight += childSize.height;
+            contentWidth = Math.max(contentWidth, childSize.width);
         }
+        // No explicit width and no bounded region: shrink-wrap to the widest child.
+        if (shrinkWrapWidth)
+            this.width = contentWidth + 2 * this.borderWidth;
         // No explicit height and no bounded region: the border hugs its content.
         if (shrinkWrapHeight)
             this.height = contentHeight + 2 * this.borderWidth;
+        // The box is sized now: place any out-of-flow `Positioned` descendants against its box.
+        if (frame) {
+            frame.origin = { x: this.x, y: this.y };
+            frame.size = { width: this.width ?? 0, height: this.height ?? 0 };
+            for (const place of frame.place)
+                place(frame, ctx);
+        }
         // Border-box model: width/height ARE the outer box (the rect we draw); the content
         // is inset by the border on every side. Report the honest box size - no phantom
         // border added on (that asymmetric "+border" was the source of the magic-3 fudge in
         // fragment). Top-left coordinates; the Y-flip happens at the IR -> backend seam.
         return {
-            width: (_b = this.width) !== null && _b !== void 0 ? _b : 0,
-            height: (_c = this.height) !== null && _c !== void 0 ? _c : 0,
+            width: this.width ?? 0,
+            height: this.height ?? 0,
         };
     }
     getProps() {
@@ -114,7 +137,7 @@ class RectangleElement extends pdf_element_1.SizedPDFElement {
             borderWidth: this.borderWidth,
             radius: this.radius,
             sideBorders: this.sideBorders,
+            overflow: this.overflow,
         };
     }
 }
-exports.RectangleElement = RectangleElement;

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

@@ -1,6 +1,6 @@
-import { BoxConstraints, Offset, Size } from "../layout/box-constraints";
-import { MainAlign, CrossAlign } from "../utils/flex-layout";
-import { LayoutContext, PDFElement, SizedPDFElement, WithChildren } from "./pdf-element";
+import { BoxConstraints, Offset, Size } from "../layout/box-constraints.js";
+import { MainAlign, CrossAlign } from "../utils/flex-layout.js";
+import { LayoutContext, PDFElement, SizedPDFElement, WithChildren } from "./pdf-element.js";
 interface RowElementParams extends WithChildren {
     /** Space inserted between children, in points. */
     gap?: number;

package/dist/elements/row-element.js

@@ -1,8 +1,5 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.RowElement = void 0;
-const flex_layout_1 = require("../utils/flex-layout");
-const pdf_element_1 = require("./pdf-element");
+import { FlexLayoutHelper, HORIZONTAL_AXIS } from "../utils/flex-layout.js";
+import { SizedPDFElement } from "./pdf-element.js";
 /**
  * Horizontal stack: the mirror of `ContainerElement` (Column). Children are laid out
  * left-to-right via the shared `FlexLayoutHelper` on the horizontal axis; fixed children
@@ -15,13 +12,13 @@ const pdf_element_1 = require("./pdf-element");
  * does not fit (handled by the parent's `packChildren`); synchronized cell splitting is a
  * Grid/Table concern.
  */
-class RowElement extends pdf_element_1.SizedPDFElement {
+export class RowElement extends SizedPDFElement {
     constructor({ children, gap, main, cross }) {
         super({ x: 0, y: 0 });
         this.children = children;
-        this.gap = gap !== null && gap !== void 0 ? gap : 0;
-        this.main = main !== null && main !== void 0 ? main : "start";
-        this.cross = cross !== null && cross !== void 0 ? cross : "stretch";
+        this.gap = gap ?? 0;
+        this.main = main ?? "start";
+        this.cross = cross ?? "stretch";
     }
     calculateLayout(constraints, offset, ctx) {
         this.x = offset.x;
@@ -32,7 +29,7 @@ class RowElement extends pdf_element_1.SizedPDFElement {
         const crossAvail = constraints.hasBoundedHeight ? constraints.maxHeight : Infinity;
         let result = { mainUsed: 0, crossUsed: 0 };
         if (this.children.length > 0) {
-            result = flex_layout_1.FlexLayoutHelper.layout(this.children, flex_layout_1.HORIZONTAL_AXIS, mainAvail, crossAvail, this.x, this.y, { gap: this.gap, main: this.main, cross: this.cross }, ctx);
+            result = FlexLayoutHelper.layout(this.children, HORIZONTAL_AXIS, mainAvail, crossAvail, this.x, this.y, { gap: this.gap, main: this.main, cross: this.cross }, ctx);
         }
         this.width = constraints.hasBoundedWidth ? constraints.maxWidth : result.mainUsed;
         this.height = constraints.hasBoundedHeight ? constraints.maxHeight : result.crossUsed;
@@ -51,4 +48,3 @@ class RowElement extends pdf_element_1.SizedPDFElement {
         };
     }
 }
-exports.RowElement = RowElement;

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

@@ -1,8 +1,9 @@
-import { Color } from "../common/color";
-import { FontStyle } from "../utils/pdf-object-manager";
-import { BoxConstraints, Offset, Size } from "../layout/box-constraints";
-import { Fragmentable, FragmentResult } from "../layout/fragmentation";
-import { HorizontalAlignment, LayoutContext, SizedPDFElement } from "./pdf-element";
+import { Color } from "../common/color.js";
+import { FontStyle } from "../utils/pdf-object-manager.js";
+import { BoxConstraints, Offset, Size } from "../layout/box-constraints.js";
+import { Fragmentable, FragmentResult } from "../layout/fragmentation.js";
+import { TextOverflow } from "../text/line-breaker.js";
+import { HorizontalAlignment, LayoutContext, SizedPDFElement } from "./pdf-element.js";
 export interface TextSegment {
     content: string;
     fontStyle?: FontStyle;
@@ -12,21 +13,39 @@ export interface TextSegment {
 }
 interface TextElementParams {
     id?: string;
-    fontSize: number;
+    /** Unset (undefined) inherits the cascaded size; see ResolvedTextStyle. */
+    fontSize?: number;
     fontFamily?: string;
     fontStyle?: FontStyle;
     content: string | TextSegment[];
     color?: Color;
     textAlignment?: HorizontalAlignment;
+    /** Cap the wrapped lines (default: unlimited / open-end). */
+    maxLines?: number;
+    /** What to do past `maxLines`: `"clip"` (default) drops them, `"ellipsis"` ends with "…". */
+    overflow?: TextOverflow;
+    /** Line-height multiplier: each line is `fontSize * lineHeight` tall (default `1`). */
+    lineHeight?: number;
 }
 export declare class TextElement extends SizedPDFElement implements Fragmentable {
+    private readonly rawFontSize?;
+    private readonly rawFontFamily?;
+    private readonly rawFontStyle?;
+    private readonly rawColor?;
+    private readonly rawTextAlignment?;
+    private readonly rawLineHeight?;
     private fontSize;
     private fontFamily;
     private fontStyle;
     private color;
-    private content;
     private textAlignment;
-    constructor({ fontSize, content, fontFamily, fontStyle, color, textAlignment, }: TextElementParams);
+    private lineHeight;
+    private content;
+    private maxLines?;
+    private overflow;
+    constructor({ fontSize, content, fontFamily, fontStyle, color, textAlignment, maxLines, overflow, lineHeight, }: TextElementParams);
+    private resolveStyle;
+    private applyStyle;
     /**
      * Splits the paragraph at line boxes (Slice 1). The lines that fit in `maxHeight` stay;
      * the rest become a remainder `TextElement` re-wrapped on the next page. If not even one
@@ -39,9 +58,13 @@ export declare class TextElement extends SizedPDFElement implements Fragmentable
     private cloneWithContent;
     calculateLayout(constraints: BoxConstraints, offset: Offset, ctx: LayoutContext): Size;
     /** The unwrapped single-line width of the content (used when width is unbounded, e.g. inside a Row).
-     *  Mirrors the renderer's advance EXACTLY: per-glyph, WITHOUT kerning. `getStringWidth` subtracts
-     *  kerning, so it under-reserves and the text would wrap inside its own natural-width box - the cause
-     *  of fixed Row children wrapping despite ample space. */
+     *  Must match the LINE-BREAKER's one-line measure EXACTLY - not just algebraically but BIT-for-bit,
+     *  so a text laid out at this width never re-wraps inside its own natural-width box. The breaker
+     *  accumulates `currentWidth += wordWidth + spaceWidth`, grouping the word and its trailing space
+     *  into one term; we must group the same way. Adding word and space as two separate steps is
+     *  algebraically equal but, because floating-point addition is not associative, drifts by a sub-ULP
+     *  - 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. */
     private naturalWidth;
     getProps(): {
         x: number;
@@ -54,6 +77,9 @@ export declare class TextElement extends SizedPDFElement implements Fragmentable
         color: Color;
         content: string | TextSegment[];
         textAlignment: HorizontalAlignment;
+        maxLines: number | undefined;
+        overflow: TextOverflow;
+        lineHeight: number;
     };
 }
 export {};

package/dist/elements/text-element.js

@@ -1,24 +1,36 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.TextElement = void 0;
-const color_1 = require("../common/color");
 // Import the renderer DIRECTLY, not via the "../renderer" barrel: the barrel pulls in
 // pdf-renderer (and every element) while this element module is still loading, which under
 // ESM (Vite/vitest, and the future framework bindings) duplicates the element classes and
 // breaks the constructor-keyed RendererRegistry. A direct import keeps the graph acyclic.
-const text_renderer_1 = require("../renderer/text-renderer");
-const pdf_object_manager_1 = require("../utils/pdf-object-manager");
-const line_breaker_1 = require("../text/line-breaker");
-const pdf_element_1 = require("./pdf-element");
-class TextElement extends pdf_element_1.SizedPDFElement {
-    constructor({ fontSize, content, fontFamily = "Helvetica", fontStyle = pdf_object_manager_1.FontStyle.Normal, color = new color_1.Color(0, 0, 0), textAlignment = pdf_element_1.HorizontalAlignment.left, }) {
+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 { SizedPDFElement } from "./pdf-element.js";
+export class TextElement extends SizedPDFElement {
+    constructor({ fontSize, content, fontFamily, fontStyle, color, textAlignment, maxLines, overflow = "clip", lineHeight, }) {
         super({ x: 0, y: 0 });
-        this.fontSize = fontSize;
-        this.fontFamily = fontFamily;
-        this.fontStyle = fontStyle;
-        this.color = color;
+        this.rawFontSize = fontSize;
+        this.rawFontFamily = fontFamily;
+        this.rawFontStyle = fontStyle;
+        this.rawColor = color;
+        this.rawTextAlignment = textAlignment;
+        this.rawLineHeight = lineHeight;
         this.content = content;
-        this.textAlignment = textAlignment;
+        this.maxLines = maxLines;
+        this.overflow = overflow;
+        this.applyStyle(DEFAULT_TEXT_STYLE);
+    }
+    // Resolve the author-set values against the cascade: explicit > inherited (ctx) > built-in default.
+    resolveStyle(ctx) {
+        this.applyStyle(ctx.textStyle ?? DEFAULT_TEXT_STYLE);
+    }
+    applyStyle(ts) {
+        this.fontSize = this.rawFontSize ?? ts.fontSize;
+        this.fontFamily = this.rawFontFamily ?? ts.fontFamily;
+        this.fontStyle = this.rawFontStyle ?? ts.fontStyle;
+        this.color = this.rawColor ?? ts.color;
+        this.textAlignment = this.rawTextAlignment ?? ts.textAlignment;
+        this.lineHeight = this.rawLineHeight ?? ts.lineHeight;
     }
     /**
      * Splits the paragraph at line boxes (Slice 1). The lines that fit in `maxHeight` stay;
@@ -27,6 +39,7 @@ class TextElement extends pdf_element_1.SizedPDFElement {
      * the whole element on for progress. Handles both plain strings and styled segments.
      */
     fragment(maxHeight, width, ctx) {
+        this.resolveStyle(ctx);
         return typeof this.content === "string"
             ? this.fragmentString(this.content, maxHeight, width, ctx)
             : this.fragmentSegments(this.content, maxHeight, width, ctx);
@@ -34,8 +47,8 @@ class TextElement extends pdf_element_1.SizedPDFElement {
     // Plain string: every wrapped line is `fontSize` tall (matches calculateTextHeight),
     // so `floor(maxHeight / fontSize)` lines fit.
     fragmentString(content, maxHeight, width, ctx) {
-        const lines = (0, line_breaker_1.wrapStringIntoLines)(content, this.fontFamily, this.fontSize, this.fontStyle, width, ctx.metrics);
-        const fittedLineCount = Math.floor(maxHeight / this.fontSize);
+        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));
         if (fittedLineCount <= 0)
             return { fitted: null, remainder: this };
         if (fittedLineCount >= lines.length)
@@ -48,17 +61,18 @@ class TextElement extends pdf_element_1.SizedPDFElement {
     // 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[].
     fragmentSegments(content, maxHeight, width, ctx) {
-        const lines = (0, line_breaker_1.breakSegmentsIntoLines)(content, {
+        const lines = breakSegmentsIntoLines(content, {
             fontFamily: this.fontFamily,
             fontSize: this.fontSize,
             fontStyle: this.fontStyle,
-        }, width, ctx.metrics);
+        }, width, ctx.metrics, this.maxLines, this.overflow);
         let used = 0;
         let fittedLineCount = 0;
         for (const line of lines) {
-            if (used + line.maxFontSize > maxHeight)
+            const lineBox = line.maxFontSize * this.lineHeight;
+            if (used + lineBox > maxHeight)
                 break;
-            used += line.maxFontSize;
+            used += lineBox;
             fittedLineCount++;
         }
         if (fittedLineCount <= 0)
@@ -66,8 +80,8 @@ class TextElement extends pdf_element_1.SizedPDFElement {
         if (fittedLineCount >= lines.length)
             return { fitted: this, remainder: null };
         return {
-            fitted: this.cloneWithContent((0, line_breaker_1.segmentLinesToSegments)(lines.slice(0, fittedLineCount))),
-            remainder: this.cloneWithContent((0, line_breaker_1.segmentLinesToSegments)(lines.slice(fittedLineCount))),
+            fitted: this.cloneWithContent(segmentLinesToSegments(lines.slice(0, fittedLineCount))),
+            remainder: this.cloneWithContent(segmentLinesToSegments(lines.slice(fittedLineCount))),
         };
     }
     // A copy carrying the same style but different (already-wrapped) content. Re-wrapping at
@@ -80,10 +94,13 @@ class TextElement extends pdf_element_1.SizedPDFElement {
             fontStyle: this.fontStyle,
             color: this.color,
             textAlignment: this.textAlignment,
+            maxLines: this.maxLines,
+            overflow: this.overflow,
+            lineHeight: this.lineHeight,
         });
     }
     calculateLayout(constraints, offset, ctx) {
-        var _a;
+        this.resolveStyle(ctx);
         this.x = offset.x;
         this.y = offset.y;
         // Bounded width (e.g. inside a Column) wraps to that width; an unbounded width
@@ -92,32 +109,38 @@ class TextElement extends pdf_element_1.SizedPDFElement {
         this.width = constraints.hasBoundedWidth
             ? constraints.maxWidth
             : this.naturalWidth(ctx.metrics);
-        const wrapWidth = (_a = this.width) !== null && _a !== void 0 ? _a : 0;
-        this.height = text_renderer_1.TextRenderer.calculateTextHeight(this.content, this.fontSize, this.fontFamily, this.fontStyle, ctx.metrics, wrapWidth);
+        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);
         // 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.
         return { width: wrapWidth, height: this.height };
     }
     /** The unwrapped single-line width of the content (used when width is unbounded, e.g. inside a Row).
-     *  Mirrors the renderer's advance EXACTLY: per-glyph, WITHOUT kerning. `getStringWidth` subtracts
-     *  kerning, so it under-reserves and the text would wrap inside its own natural-width box - the cause
-     *  of fixed Row children wrapping despite ample space. */
+     *  Must match the LINE-BREAKER's one-line measure EXACTLY - not just algebraically but BIT-for-bit,
+     *  so a text laid out at this width never re-wraps inside its own natural-width box. The breaker
+     *  accumulates `currentWidth += wordWidth + spaceWidth`, grouping the word and its trailing space
+     *  into one term; we must group the same way. Adding word and space as two separate steps is
+     *  algebraically equal but, because floating-point addition is not associative, drifts by a sub-ULP
+     *  - 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 advance = (text, family, size, style) => {
+        const oneLine = (text, family, size, style) => {
+            const words = text.split(" ");
+            const space = metrics.getCharWidth(" ", size, undefined, family, style);
             let width = 0;
-            for (const ch of text)
-                width += metrics.getCharWidth(ch, size, undefined, family, style);
+            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.
+                width += i < words.length - 1 ? w + space : w;
+            });
             return width;
         };
         if (typeof this.content === "string") {
-            return advance(this.content, this.fontFamily, this.fontSize, this.fontStyle);
+            return oneLine(this.content, this.fontFamily, this.fontSize, this.fontStyle);
         }
-        return this.content.reduce((sum, seg) => {
-            var _a, _b, _c;
-            return sum +
-                advance(seg.content, (_a = seg.fontFamily) !== null && _a !== void 0 ? _a : this.fontFamily, (_b = seg.fontSize) !== null && _b !== void 0 ? _b : this.fontSize, (_c = seg.fontStyle) !== null && _c !== void 0 ? _c : this.fontStyle);
-        }, 0);
+        return this.content.reduce((sum, seg) => sum +
+            oneLine(seg.content, seg.fontFamily ?? this.fontFamily, seg.fontSize ?? this.fontSize, seg.fontStyle ?? this.fontStyle), 0);
     }
     getProps() {
         return {
@@ -131,7 +154,9 @@ class TextElement extends pdf_element_1.SizedPDFElement {
             color: this.color,
             content: this.content,
             textAlignment: this.textAlignment,
+            maxLines: this.maxLines,
+            overflow: this.overflow,
+            lineHeight: this.lineHeight,
         };
     }
 }
-exports.TextElement = TextElement;

package/dist/index.d.ts

@@ -1,3 +1,3 @@
-export * from "./elements";
-export * from "./renderer";
-export * from "./api";
+export * from "./elements/index.js";
+export * from "./renderer/index.js";
+export * from "./api/index.js";

package/dist/index.js

@@ -1,21 +1,5 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./elements"), exports);
-__exportStar(require("./renderer"), exports);
-__exportStar(require("./api"), exports);
+export * from "./elements/index.js";
+export * from "./renderer/index.js";
+export * from "./api/index.js";
 // export * from './validator';
 // export * from './utils';

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

@@ -1,5 +1,5 @@
-import { Color } from "../common/color";
-import { FontStyle } from "../utils/pdf-object-manager";
+import { Color } from "../common/color.js";
+import { FontStyle } from "../utils/pdf-object-manager.js";
 /**
  * Display list - the seam between layout and the PDF backend.
  *
@@ -60,6 +60,8 @@ export interface Image {
     intrinsicHeight: number;
     data: string;
     imageType: string;
+    /** Flate-compressed DeviceGray alpha channel for a transparent PNG, embedded as the XObject's /SMask. */
+    smask?: string;
     /** cover/contain fits clip the placement to the element's original frame. */
     clip?: {
         x: number;
@@ -70,5 +72,22 @@ export interface Image {
     /** Corner radius in points for the image box; absent/0 = sharp corners. */
     radius?: number;
 }
+/**
+ * Pushes a clipping region (a rectangle, rounded when `radius` is set). Everything between this and
+ * the matching `ClipPop` is clipped to it - what a Box with `overflow: "hidden"` wraps its children
+ * in, so a `Positioned` child gets cropped at the box edge instead of spilling over.
+ */
+export interface ClipPush {
+    type: "clip-push";
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    radius?: number;
+}
+/** Closes the most recent `ClipPush` (restores the graphics state). */
+export interface ClipPop {
+    type: "clip-pop";
+}
 /** The closed set of primitives the PDF backend knows how to draw. */
-export type IRNode = TextRun | Rect | Line | Image;
+export type IRNode = TextRun | Rect | Line | Image | ClipPush | ClipPop;

package/dist/ir/display-list.js

@@ -1,2 +1 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
+export {};

package/dist/layout/box-constraints.js

@@ -1,6 +1,3 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.BoxConstraints = void 0;
 /**
  * The size constraints handed DOWN the tree during layout (Flutter's BoxConstraints
  * model). Pure geometry: a min/max range per axis, no position. An element receives a
@@ -15,7 +12,7 @@ exports.BoxConstraints = void 0;
  * remaining vertical space becomes a `maxHeight`, and "does this fit?" is a constraint
  * check, not a special case.
  */
-class BoxConstraints {
+export class BoxConstraints {
     constructor(minWidth = 0, maxWidth = Infinity, minHeight = 0, maxHeight = Infinity) {
         this.minWidth = minWidth;
         this.maxWidth = maxWidth;
@@ -28,7 +25,7 @@ class BoxConstraints {
     }
     /** Tight only on the axes given; the others stay unbounded (0..Infinity). */
     static tightFor({ width, height }) {
-        return new BoxConstraints(width !== null && width !== void 0 ? width : 0, width !== null && width !== void 0 ? width : Infinity, height !== null && height !== void 0 ? height : 0, height !== null && height !== void 0 ? height : Infinity);
+        return new BoxConstraints(width ?? 0, width ?? Infinity, height ?? 0, height ?? Infinity);
     }
     /** Caps each axis at `max` but allows anything down to zero (shrink-wrap). */
     static loose(maxWidth, maxHeight) {
@@ -70,4 +67,3 @@ 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)));
     }
 }
-exports.BoxConstraints = BoxConstraints;

package/dist/layout/fragmentation.d.ts

@@ -1,4 +1,4 @@
-import { LayoutContext, PDFElement } from "../elements/pdf-element";
+import { LayoutContext, PDFElement } from "../elements/pdf-element.js";
 /**
  * The result of splitting an element against a fragmentation region (a page, later a
  * column). `fitted` is the part that fits in the region; `remainder` describes what did
@@ -22,6 +22,13 @@ export interface Fragmentable {
     fragment(maxHeight: number, width: number, ctx: LayoutContext): FragmentResult;
 }
 export declare function isFragmentable(element: PDFElement): element is PDFElement & Fragmentable;
+/**
+ * What to do when an element is taller than the whole page region and cannot be broken. We always
+ * still place it (clipped) so pagination terminates - this only controls how loud we are about it:
+ * `"error"` throws (the default; an unbreakable overflow is almost always a layout bug), `"warn"`
+ * logs and clips, `"ignore"` clips silently.
+ */
+export type OverflowPolicy = "error" | "warn" | "ignore";
 /**
  * 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