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

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

@@ -1,32 +1,134 @@
-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 type { Direction } from "../text/bidi.js";
+import { type TextTransform } from "../text/text-style.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;
     fontColor?: Color;
     fontFamily?: string;
+    /** The rest of the family stack for THIS run; unset inherits the Text's own. */
+    fontFallback?: string[];
     fontSize?: number;
+    /** External URL: this segment becomes an inline hyperlink (a /Link annotation over its glyphs). */
+    href?: string;
+    /** Internal named destination (an `Anchor`): this segment links to it (a /GoTo /Link annotation). */
+    dest?: string;
+    /** Unset inherits the Text's own setting; `true`/`false` overrides it for this run only. */
+    underline?: boolean;
+    strikethrough?: boolean;
+    /** Extra space after every glyph, in points; unset inherits the Text's own value. */
+    letterSpacing?: number;
+    /**
+     * CSS `vertical-align`, for a footnote marker or a formula index. Shifts THIS run's baseline;
+     * it does not resize the text, and it does not change the line's height - set `fontSize` yourself
+     * for the smaller look a browser's `<sup>` gets from its default stylesheet.
+     */
+    verticalAlign?: VerticalTextAlign;
 }
+/** How far a run sits off the baseline, as a fraction of its font size (up is positive). */
+export declare const VERTICAL_TEXT_SHIFT: Record<VerticalTextAlign, number>;
+/** CSS `vertical-align`, the three values that mean something for a run of text. */
+export type VerticalTextAlign = "baseline" | "super" | "sub";
+/** Accessibility role for the tagged structure tree: a heading level or a paragraph (the default). */
+export type TextRole = "h1" | "h2" | "h3" | "h4" | "h5" | "h6" | "p";
 interface TextElementParams {
     id?: string;
-    fontSize: number;
+    /** Unset (undefined) inherits the cascaded size; see ResolvedTextStyle. */
+    fontSize?: number;
     fontFamily?: string;
+    /** The rest of the family stack, for code points `fontFamily` cannot draw. */
+    fontFallback?: string[];
     fontStyle?: FontStyle;
     content: string | TextSegment[];
     color?: Color;
     textAlignment?: HorizontalAlignment;
+    /** Cap the wrapped lines (default: unlimited / open-end). */
+    maxLines?: number;
+    /** Minimum lines that must stay behind at a page break (CSS `orphans`, default 2). */
+    orphans?: number;
+    /** Minimum lines that must carry over to the next page (CSS `widows`, default 2). */
+    widows?: number;
+    /** What to do past `maxLines`: `"clip"` (default) drops them, `"ellipsis"` ends with "…". */
+    overflow?: TextOverflow;
+    /** Line-height multiplier: each line is `fontSize * lineHeight` tall. Unset means the font's
+     *  natural line height (`ascent + descent + lineGap`), like CSS `line-height: normal`. */
+    lineHeight?: number;
+    /** Draw a line under the text, at the position and thickness the font declares. */
+    underline?: boolean;
+    /** Draw a line through the text, at half its x-height. */
+    strikethrough?: boolean;
+    /** Let the underline step around descenders. Needs an embedded font. */
+    skipInk?: boolean;
+    /** Extra space after every glyph, in points (CSS `letter-spacing`). Default 0. */
+    letterSpacing?: number;
+    /** Base writing direction (CSS `direction`); decides where a line starts. Default `"ltr"`. */
+    direction?: Direction;
+    /** CSS `text-transform`; applied before the text is measured or drawn. */
+    textTransform?: TextTransform;
+    /** CSS `word-spacing`, in points: extra advance at every space. */
+    wordSpacing?: number;
+    /** CSS `text-indent`, in points: how far the first line starts in. */
+    textIndent?: number;
+    /** Accessibility role for the tagged structure tree (heading level or paragraph; default `"p"`). */
+    role?: TextRole;
 }
 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 readonly rawUnderline?;
+    private readonly rawStrikethrough?;
+    private readonly rawSkipInk?;
+    private readonly rawLetterSpacing?;
+    private readonly rawDirection?;
+    private readonly rawFontFallback?;
+    private readonly rawTextTransform?;
+    private readonly rawWordSpacing?;
+    private readonly rawTextIndent?;
     private fontSize;
     private fontFamily;
     private fontStyle;
     private color;
-    private content;
     private textAlignment;
-    constructor({ fontSize, content, fontFamily, fontStyle, color, textAlignment, }: TextElementParams);
+    private lineHeight?;
+    private underline;
+    private strikethrough;
+    private skipInk;
+    private letterSpacing;
+    private direction;
+    private fontFallback;
+    private resolved?;
+    private textTransform;
+    private wordSpacing;
+    private textIndent;
+    private content;
+    private maxLines?;
+    private orphans?;
+    private widows?;
+    private overflow;
+    private readonly role?;
+    constructor({ fontSize, content, fontFamily, fontStyle, color, textAlignment, maxLines, orphans, widows, overflow, lineHeight, underline, strikethrough, skipInk, letterSpacing, direction, fontFallback, textTransform, wordSpacing, textIndent, role, }: TextElementParams);
+    private resolveStyle;
+    /** Justified lines may be squeezed to keep a word; every other alignment gets no slack. Read by the
+     *  breaker in BOTH passes, or a measured line and a drawn one would disagree about where it ends. */
+    /**
+     * The content as it is measured AND drawn - `text-transform` applied. One place, so a recased
+     * paragraph can never be measured in one casing and drawn in another (`ABC` and `abc` are not the
+     * same width in most fonts).
+     */
+    private display;
+    /** The content with `text-transform` applied, and nothing else. */
+    private recased;
+    private lineOptions;
+    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
@@ -36,12 +138,18 @@ export declare class TextElement extends SizedPDFElement implements Fragmentable
     fragment(maxHeight: number, width: number, ctx: LayoutContext): FragmentResult;
     private fragmentString;
     private fragmentSegments;
+    /** The orphan/widow minimums for this paragraph; unset means the CSS default of 2 lines each. */
+    private breakRule;
     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 +162,19 @@ export declare class TextElement extends SizedPDFElement implements Fragmentable
         color: Color;
         content: string | TextSegment[];
         textAlignment: HorizontalAlignment;
+        maxLines: number | undefined;
+        orphans: number | undefined;
+        widows: number | undefined;
+        overflow: TextOverflow;
+        lineHeight: number | undefined;
+        underline: boolean;
+        strikethrough: boolean;
+        skipInk: boolean;
+        letterSpacing: number;
+        direction: Direction;
+        wordSpacing: number;
+        textIndent: number;
+        role: TextRole | undefined;
     };
 }
 export {};

package/dist/elements/text-element.js

@@ -1,24 +1,129 @@
-"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 { applyTextTransform } from "../text/text-style.js";
+import { splitByFont } from "../text/font-fallback.js";
+import { singleLineWidth, MAX_SPACE_SHRINK, wrapStringIntoLines, breakSegmentsIntoLines, segmentLinesToSegments, } from "../text/line-breaker.js";
+import { adjustForOrphansWidows, DEFAULT_ORPHANS, DEFAULT_WIDOWS, } from "../text/orphans-widows.js";
+import { lineBoxForSegmentLine, lineBoxForString } from "../text/line-metrics.js";
+import { HorizontalAlignment, SizedPDFElement } from "./pdf-element.js";
+/** How far a run sits off the baseline, as a fraction of its font size (up is positive). */
+export const VERTICAL_TEXT_SHIFT = {
+    baseline: 0,
+    super: 1 / 3,
+    sub: -1 / 5,
+};
+/**
+ * A measurement in points has to be a real number. A NaN or an Infinity would travel all the way into
+ * the content stream as a position - the backend refuses it there, but by then the message names a
+ * coordinate rather than the property that was wrong. Rejected here, where the caller can see it.
+ */
+function finitePoints(value, name) {
+    if (value !== undefined && !Number.isFinite(value)) {
+        throw new Error(`@jasy/pdf: Invalid ${name} ${value}: it must be a finite number of points.`);
+    }
+    return value;
+}
+export class TextElement extends SizedPDFElement {
+    constructor({ fontSize, content, fontFamily, fontStyle, color, textAlignment, maxLines, orphans, widows, overflow = "clip", lineHeight, underline, strikethrough, skipInk, letterSpacing, direction, fontFallback, textTransform, wordSpacing, textIndent, role, }) {
         super({ x: 0, y: 0 });
-        this.fontSize = fontSize;
-        this.fontFamily = fontFamily;
-        this.fontStyle = fontStyle;
-        this.color = color;
+        this.role = role;
+        this.rawFontSize = fontSize;
+        this.rawFontFamily = fontFamily;
+        this.rawFontStyle = fontStyle;
+        this.rawColor = color;
+        this.rawTextAlignment = textAlignment;
+        this.rawLineHeight = lineHeight;
+        this.rawUnderline = underline;
+        this.rawStrikethrough = strikethrough;
+        this.rawSkipInk = skipInk;
+        this.rawLetterSpacing = letterSpacing;
+        this.rawDirection = direction;
+        this.rawFontFallback = fontFallback;
+        this.rawTextTransform = textTransform;
+        this.rawWordSpacing = finitePoints(wordSpacing, "wordSpacing");
+        this.rawTextIndent = finitePoints(textIndent, "textIndent");
         this.content = content;
-        this.textAlignment = textAlignment;
+        this.maxLines = maxLines;
+        this.orphans = orphans;
+        this.widows = widows;
+        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);
+    }
+    /** Justified lines may be squeezed to keep a word; every other alignment gets no slack. Read by the
+     *  breaker in BOTH passes, or a measured line and a drawn one would disagree about where it ends. */
+    /**
+     * The content as it is measured AND drawn - `text-transform` applied. One place, so a recased
+     * paragraph can never be measured in one casing and drawn in another (`ABC` and `abc` are not the
+     * same width in most fonts).
+     */
+    display(metrics) {
+        const cased = this.recased();
+        // A SPAN may bring its own stack, so the element's being empty is not enough to skip the pass.
+        const anyStack = this.fontFallback.length > 0 ||
+            (typeof cased !== "string" && cased.some((seg) => (seg.fontFallback?.length ?? 0) > 0));
+        if (!anyStack || !metrics)
+            return cased;
+        // Font fallback turns the content into spans - one per family - which every later pass already
+        // knows how to handle. Nothing new downstream.
+        const pieces = typeof cased === "string" ? [{ content: cased }] : cased;
+        const out = [];
+        for (const seg of pieces) {
+            const runs = splitByFont(seg.content, seg.fontFamily ?? this.fontFamily, seg.fontFallback ?? this.fontFallback, seg.fontStyle ?? this.fontStyle, metrics);
+            if (!runs)
+                out.push(seg);
+            else
+                for (const run of runs)
+                    out.push({ ...seg, content: run.text, fontFamily: run.fontFamily });
+        }
+        return out;
+    }
+    /** The content with `text-transform` applied, and nothing else. */
+    recased() {
+        if (this.textTransform === "none")
+            return this.content;
+        if (typeof this.content === "string") {
+            return applyTextTransform(this.content, this.textTransform).text;
+        }
+        // The capitalisation state runs THROUGH the spans: `span("hel") + span("lo")` is one word.
+        let atWordStart = true;
+        return this.content.map((seg) => {
+            const done = applyTextTransform(seg.content, this.textTransform, atWordStart);
+            atWordStart = done.atWordStart;
+            return { ...seg, content: done.text };
+        });
+    }
+    lineOptions() {
+        return {
+            wordSpacing: this.wordSpacing,
+            indent: this.textIndent,
+            // Justified lines may be squeezed to keep a word; every other alignment gets no slack.
+            shrink: this.textAlignment === HorizontalAlignment.justify ? MAX_SPACE_SHRINK : 0,
+        };
+    }
+    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;
+        this.underline = this.rawUnderline ?? ts.underline;
+        this.strikethrough = this.rawStrikethrough ?? ts.strikethrough;
+        this.skipInk = this.rawSkipInk ?? ts.skipInk;
+        this.letterSpacing = this.rawLetterSpacing ?? ts.letterSpacing;
+        this.direction = this.rawDirection ?? ts.direction;
+        this.fontFallback = this.rawFontFallback ?? ts.fontFallback;
+        this.textTransform = this.rawTextTransform ?? ts.textTransform;
+        this.wordSpacing = this.rawWordSpacing ?? ts.wordSpacing;
+        this.textIndent = this.rawTextIndent ?? ts.textIndent;
     }
     /**
      * Splits the paragraph at line boxes (Slice 1). The lines that fit in `maxHeight` stay;
@@ -27,52 +132,70 @@ class TextElement extends pdf_element_1.SizedPDFElement {
      * the whole element on for progress. Handles both plain strings and styled segments.
      */
     fragment(maxHeight, width, ctx) {
-        return typeof this.content === "string"
-            ? this.fragmentString(this.content, maxHeight, width, ctx)
-            : this.fragmentSegments(this.content, maxHeight, width, ctx);
+        this.resolveStyle(ctx);
+        const content = this.display(ctx.metrics);
+        return typeof content === "string"
+            ? this.fragmentString(content, maxHeight, width, ctx)
+            : this.fragmentSegments(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 = (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, this.letterSpacing, this.lineOptions());
+        const box = lineBoxForString(ctx.metrics, this.fontFamily, this.fontStyle, this.fontSize, this.lineHeight);
+        const fittedLineCount = adjustForOrphansWidows(Math.floor(maxHeight / box.height), lines.length, this.breakRule());
         if (fittedLineCount <= 0)
             return { fitted: null, remainder: this };
         if (fittedLineCount >= lines.length)
             return { fitted: this, remainder: null };
         return {
             fitted: this.cloneWithContent(lines.slice(0, fittedLineCount).join(" ")),
-            remainder: this.cloneWithContent(lines.slice(fittedLineCount).join(" ")),
+            // A continuation is no longer the paragraph's FIRST line, so it carries no indent.
+            remainder: this.cloneWithContent(lines.slice(fittedLineCount).join(" "), 0),
         };
     }
-    // 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 = (0, line_breaker_1.breakSegmentsIntoLines)(content, {
+        const defaults = {
             fontFamily: this.fontFamily,
             fontSize: this.fontSize,
             fontStyle: this.fontStyle,
-        }, width, ctx.metrics);
+            letterSpacing: this.letterSpacing,
+            direction: this.direction,
+            wordSpacing: this.wordSpacing,
+            textIndent: this.textIndent,
+        };
+        const lines = breakSegmentsIntoLines(content, defaults, width, ctx.metrics, this.maxLines, this.overflow);
         let used = 0;
-        let fittedLineCount = 0;
+        let packed = 0;
         for (const line of lines) {
-            if (used + line.maxFontSize > maxHeight)
+            const lineBox = lineBoxForSegmentLine(line, defaults, ctx.metrics, this.lineHeight).height;
+            if (used + lineBox > maxHeight)
                 break;
-            used += line.maxFontSize;
-            fittedLineCount++;
+            used += lineBox;
+            packed++;
         }
+        const fittedLineCount = adjustForOrphansWidows(packed, lines.length, this.breakRule());
         if (fittedLineCount <= 0)
             return { fitted: null, remainder: this };
         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)), 0),
+        };
+    }
+    /** The orphan/widow minimums for this paragraph; unset means the CSS default of 2 lines each. */
+    breakRule() {
+        return {
+            orphans: this.orphans ?? DEFAULT_ORPHANS,
+            widows: this.widows ?? DEFAULT_WIDOWS,
         };
     }
     // A copy carrying the same style but different (already-wrapped) content. Re-wrapping at
     // the same width reproduces exactly those lines (greedy is deterministic).
-    cloneWithContent(content) {
+    cloneWithContent(content, indent = this.textIndent) {
         return new TextElement({
             content,
             fontSize: this.fontSize,
@@ -80,44 +203,59 @@ class TextElement extends pdf_element_1.SizedPDFElement {
             fontStyle: this.fontStyle,
             color: this.color,
             textAlignment: this.textAlignment,
-        });
+            maxLines: this.maxLines,
+            orphans: this.orphans,
+            widows: this.widows,
+            overflow: this.overflow,
+            lineHeight: this.lineHeight,
+            underline: this.underline,
+            strikethrough: this.strikethrough,
+            skipInk: this.skipInk,
+            letterSpacing: this.letterSpacing,
+            direction: this.direction,
+            wordSpacing: this.wordSpacing,
+            textIndent: indent,
+            role: this.role,
+        }).adoptStructId(this); // a wrapped remainder is the SAME logical paragraph (one P across pages)
     }
     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
         // (e.g. inside a Row) means the text takes its natural single-line width and does
         // not wrap. Columns always bound the width, so this leaves their layout untouched.
+        this.resolved = this.display(ctx.metrics);
         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.resolved, this.fontSize, this.fontFamily, this.fontStyle, ctx.metrics, wrapWidth, this.maxLines, this.overflow, this.lineHeight, this.letterSpacing, this.lineOptions());
         // 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) => {
-            let width = 0;
-            for (const ch of text)
-                width += metrics.getCharWidth(ch, size, undefined, family, style);
-            return width;
-        };
-        if (typeof this.content === "string") {
-            return advance(this.content, this.fontFamily, this.fontSize, this.fontStyle);
+        // The breaker's own sum, to the last bit - see `singleLineWidth`.
+        const oneLine = (text, family, size, style, letterSpacing) => singleLineWidth(text, { fontFamily: family, fontSize: size, fontStyle: style }, metrics, letterSpacing, this.wordSpacing);
+        // The FIRST line starts `textIndent` in, so an unbounded box has to be that much wider.
+        const indent = Math.max(0, this.textIndent);
+        const content = this.display(metrics);
+        if (typeof content === "string") {
+            return (indent +
+                oneLine(content, this.fontFamily, this.fontSize, this.fontStyle, this.letterSpacing));
         }
-        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 content.reduce((sum, seg) => sum +
+            oneLine(seg.content, seg.fontFamily ?? this.fontFamily, seg.fontSize ?? this.fontSize, seg.fontStyle ?? this.fontStyle, seg.letterSpacing ?? this.letterSpacing), indent);
     }
     getProps() {
         return {
@@ -129,9 +267,21 @@ class TextElement extends pdf_element_1.SizedPDFElement {
             fontFamily: this.fontFamily,
             fontStyle: this.fontStyle,
             color: this.color,
-            content: this.content,
+            content: this.resolved ?? this.content,
             textAlignment: this.textAlignment,
+            maxLines: this.maxLines,
+            orphans: this.orphans,
+            widows: this.widows,
+            overflow: this.overflow,
+            lineHeight: this.lineHeight,
+            underline: this.underline,
+            strikethrough: this.strikethrough,
+            skipInk: this.skipInk,
+            letterSpacing: this.letterSpacing,
+            direction: this.direction,
+            wordSpacing: this.wordSpacing,
+            textIndent: this.textIndent,
+            role: this.role,
         };
     }
 }
-exports.TextElement = TextElement;

package/dist/forms/acroform.d.ts

@@ -0,0 +1,63 @@
+import type { PDFObjectManager } from "../utils/pdf-object-manager.js";
+import type { FormFieldNode } from "../ir/display-list.js";
+/**
+ * Collects the document's form fields as pages render, then emits the catalog `/AcroForm` dictionary at
+ * finalize. Mirrors `OutlineBuilder` / `DestRegistry`: a no-op returning "" when no field was placed, so
+ * a document without a form stays byte-identical.
+ */
+export declare class AcroFormCollector {
+    private fieldRefs;
+    private radioGroups;
+    private needAppearances;
+    private helvNum?;
+    private zadbNum?;
+    private hasSignature;
+    private usedNames;
+    private bake;
+    /** Turn appearance baking off (`renderToBytes(doc, { fieldAppearances: false })`). */
+    setBakeAppearances(on: boolean): void;
+    /** The size to draw a value at. A field may ask for `0` - the PDF convention for "auto-size"; we then
+     *  fit the capitals comfortably inside the box, which is what a viewer's auto-size does. */
+    private drawSize;
+    /** Measure one line for the appearance generator. */
+    private line;
+    /** Bake a text field's value into an appearance stream; returns the XObject number. */
+    private bakeText;
+    /** Bake a choice field: a combo shows its current value on one line, a list box shows its options
+     *  with the selected rows highlighted. */
+    private bakeChoice;
+    get isEmpty(): boolean;
+    private helv;
+    /**
+     * ZapfDingbats, the font a check mark lives in. Needed even though we bake the appearance ourselves:
+     * a viewer told to regenerate (`/NeedAppearances`, which filling a form sets) redraws a check box from
+     * its `/DA`, and the conventional `/DA` for one names `/ZaDb`. Without the matching `/DR` entry the
+     * viewer cannot resolve the font - poppler says "Unknown font tag 'ZaDb'" and draws no check at all.
+     * No encoding: ZapfDingbats brings its own.
+     */
+    private zadb;
+    /**
+     * A field name is its identity: two fields sharing one are ONE field to every viewer, showing the same
+     * value in both places and overwriting each other as the reader types. The format allows it and says
+     * nothing, so the mistake surfaces only when someone fills the form. Named here instead.
+     *
+     * A radio GROUP is the exception - its buttons deliberately share a name, which is what makes them
+     * mutually exclusive - so it never comes through here.
+     */
+    private claimName;
+    /** Emit the widget object for one form-field IR node, register it as a field, and return its object
+     *  number so the PageRenderer can add it to that page's /Annots. */
+    addField(node: FormFieldNode, om: PDFObjectManager): number;
+    /** A push button (/Btn, Pushbutton flag): no value, an optional action, and a baked caption. The
+     *  caption is measured here (the appearance module stays free of font metrics) and drawn into an
+     *  appearance stream that carries its own font resource. */
+    private buildPushButtonWidget;
+    /** A radio button: one KID widget of its group's shared field. The group field is reserved on first
+     *  sight (and added to /Fields); each button adds itself to that field's /Kids. Returns the kid widget
+     *  number, which goes into the PAGE /Annots (the parent field does not). */
+    private addRadio;
+    /** A signature field (/Sig): an EMPTY placeholder with a baked "sign here" face. No /V - an unsigned
+     *  field has no value; a signing tool fills that in (and replaces this appearance) later. */
+    private buildSignatureWidget;
+    finalize(om: PDFObjectManager): string;
+}