@jasy/pdf 1.0.0-alpha.11 → 1.0.0-alpha.12

package/dist/api/text.d.ts

@@ -3,6 +3,7 @@ import { TextOverflow } from "../text/line-breaker.js";
 import type { Direction } from "../text/bidi.js";
 import { ResolvedTextStyle, type TextTransform } from "../text/text-style.js";
 import { ColorInput } from "./color.js";
+import type { Hyphenator } from "../text/word-splitting.js";
 export type { TextOverflow };
 /** Text styling shared by `Text`, `Paragraph` and `span`. `bold`/`italic` are booleans
  *  (locked §7.3) and combine into one engine `FontStyle`. */
@@ -35,6 +36,13 @@ export interface TextStyle {
     wordSpacing?: number;
     /** CSS `text-indent`, in points: how far the FIRST line of a paragraph starts in. */
     textIndent?: number;
+    /** Split a word that is wider than its box, anywhere, no hyphen (CSS `overflow-wrap:
+     *  break-word`). The floor under `hyphenate`: an e-mail, an IBAN or an invoice number has no
+     *  valid hyphenation point anywhere. Off by default - a too-wide word overflows, as in CSS. */
+    breakWord?: boolean;
+    /** Language-aware splitting: given a word, return its parts. A hyphen is drawn at the break.
+     *  Pluggable, so no pattern data ships here: pass `hyphen`, `hyphenopoly`, or your own. */
+    hyphenate?: Hyphenator;
     /** CSS `vertical-align` for a SPAN: raises a footnote marker or lowers an index. It shifts the
      *  baseline only - pass a smaller `size` too if you want the browser's `<sup>` look. */
     verticalAlign?: VerticalTextAlign;
@@ -108,6 +116,13 @@ export interface TextDefaults {
     wordSpacing?: number;
     /** CSS `text-indent`, in points: how far the FIRST line of a paragraph starts in. */
     textIndent?: number;
+    /** Split a word that is wider than its box, anywhere, no hyphen (CSS `overflow-wrap:
+     *  break-word`). The floor under `hyphenate`: an e-mail, an IBAN or an invoice number has no
+     *  valid hyphenation point anywhere. Off by default - a too-wide word overflows, as in CSS. */
+    breakWord?: boolean;
+    /** Language-aware splitting: given a word, return its parts. A hyphen is drawn at the break.
+     *  Pluggable, so no pattern data ships here: pass `hyphen`, `hyphenopoly`, or your own. */
+    hyphenate?: Hyphenator;
 }
 /** 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

@@ -100,6 +100,8 @@ export function Text(content, opts = {}) {
         textTransform: opts.textTransform,
         wordSpacing: opts.wordSpacing,
         textIndent: opts.textIndent,
+        breakWord: opts.breakWord,
+        hyphenate: opts.hyphenate,
         role: opts.role,
     });
 }
@@ -142,5 +144,9 @@ export function toTextStyleOverride(opts) {
         style.wordSpacing = opts.wordSpacing;
     if (opts.textIndent !== undefined)
         style.textIndent = opts.textIndent;
+    if (opts.breakWord !== undefined)
+        style.breakWord = opts.breakWord;
+    if (opts.hyphenate !== undefined)
+        style.hyphenate = opts.hyphenate;
     return style;
 }

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

@@ -6,6 +6,7 @@ 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";
+import type { Hyphenator } from "../text/word-splitting.js";
 export interface TextSegment {
     content: string;
     fontStyle?: FontStyle;
@@ -74,6 +75,10 @@ interface TextElementParams {
     wordSpacing?: number;
     /** CSS `text-indent`, in points: how far the first line starts in. */
     textIndent?: number;
+    /** CSS `overflow-wrap: break-word` - split a word wider than its box, anywhere. */
+    breakWord?: boolean;
+    /** Language-aware splitting; a hyphen is drawn at the break. See text/word-splitting.ts. */
+    hyphenate?: Hyphenator;
     /** Accessibility role for the tagged structure tree (heading level or paragraph; default `"p"`). */
     role?: TextRole;
 }
@@ -93,6 +98,8 @@ export declare class TextElement extends SizedPDFElement implements Fragmentable
     private readonly rawTextTransform?;
     private readonly rawWordSpacing?;
     private readonly rawTextIndent?;
+    private readonly rawBreakWord?;
+    private readonly rawHyphenate?;
     private fontSize;
     private fontFamily;
     private fontStyle;
@@ -109,13 +116,15 @@ export declare class TextElement extends SizedPDFElement implements Fragmentable
     private textTransform;
     private wordSpacing;
     private textIndent;
+    private breakWord;
+    private hyphenate?;
     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);
+    constructor({ fontSize, content, fontFamily, fontStyle, color, textAlignment, maxLines, orphans, widows, overflow, lineHeight, underline, strikethrough, skipInk, letterSpacing, direction, fontFallback, textTransform, wordSpacing, textIndent, breakWord, hyphenate, 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. */
@@ -181,6 +190,8 @@ export declare class TextElement extends SizedPDFElement implements Fragmentable
         direction: Direction;
         wordSpacing: number;
         textIndent: number;
+        breakWord: boolean;
+        hyphenate: Hyphenator | undefined;
         role: TextRole | undefined;
     };
 }

package/dist/elements/text-element.js

@@ -30,7 +30,7 @@ function finitePoints(value, name) {
     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, }) {
+    constructor({ fontSize, content, fontFamily, fontStyle, color, textAlignment, maxLines, orphans, widows, overflow = "clip", lineHeight, underline, strikethrough, skipInk, letterSpacing, direction, fontFallback, textTransform, wordSpacing, textIndent, breakWord, hyphenate, role, }) {
         super({ x: 0, y: 0 });
         this.role = role;
         this.rawFontSize = fontSize;
@@ -48,6 +48,8 @@ export class TextElement extends SizedPDFElement {
         this.rawTextTransform = textTransform;
         this.rawWordSpacing = finitePoints(wordSpacing, "wordSpacing");
         this.rawTextIndent = finitePoints(textIndent, "textIndent");
+        this.rawBreakWord = breakWord;
+        this.rawHyphenate = hyphenate;
         // Control characters have no glyph and would be DRAWN as .notdef boxes; `\n` survives
         // because the breaker treats it as a hard break. See text/whitespace.ts.
         this.content = normalizeContent(content);
@@ -131,6 +133,7 @@ export class TextElement extends SizedPDFElement {
         return {
             wordSpacing: this.wordSpacing,
             indent: this.textIndent,
+            splitting: { breakWord: this.breakWord, hyphenate: this.hyphenate },
             // Justified lines may be squeezed to keep a word; every other alignment gets no slack.
             shrink: this.textAlignment === HorizontalAlignment.justify ? MAX_SPACE_SHRINK : 0,
         };
@@ -151,6 +154,8 @@ export class TextElement extends SizedPDFElement {
         this.textTransform = this.rawTextTransform ?? ts.textTransform;
         this.wordSpacing = this.rawWordSpacing ?? ts.wordSpacing;
         this.textIndent = this.rawTextIndent ?? ts.textIndent;
+        this.breakWord = this.rawBreakWord ?? ts.breakWord;
+        this.hyphenate = this.rawHyphenate ?? ts.hyphenate;
     }
     /**
      * Splits the paragraph at line boxes (Slice 1). The lines that fit in `maxHeight` stay;
@@ -308,6 +313,8 @@ export class TextElement extends SizedPDFElement {
             direction: this.direction,
             wordSpacing: this.wordSpacing,
             textIndent: this.textIndent,
+            breakWord: this.breakWord,
+            hyphenate: this.hyphenate,
             role: this.role,
         };
     }

package/dist/renderer/text-renderer.js

@@ -18,17 +18,25 @@ export class TextRenderer {
             const box = lineBoxForString(objectManager, fontFamily, fontStyle, fontSize, lineHeight);
             return lines.length * box.height;
         }
-        // Segments: each line's box comes from the fonts actually on it.
-        const defaults = { fontFamily, fontSize, fontStyle, letterSpacing };
+        // Segments: each line's box comes from the fonts actually on it. `splitting` has to travel with
+        // them for the same reason `letterSpacing` does: it changes where a line ENDS, so leaving it out
+        // measures a paragraph at one line count and draws it at another.
+        const defaults = {
+            fontFamily,
+            fontSize,
+            fontStyle,
+            letterSpacing,
+            splitting: lineOptions.splitting,
+        };
         const lines = breakSegmentsIntoLines(content, defaults, maxWidth, objectManager, maxLines, overflow);
         return lines.reduce((total, line) => total + lineBoxForSegmentLine(line, defaults, objectManager, lineHeight).height, 0);
     }
     static async render(textElement, objectManager) {
-        const { x, y, width, fontSize, color, content, fontFamily, fontStyle, textAlignment, maxLines, overflow, lineHeight, underline, strikethrough, skipInk, letterSpacing, direction, wordSpacing, textIndent, role, } = textElement.getProps();
+        const { x, y, width, fontSize, color, content, fontFamily, fontStyle, textAlignment, maxLines, overflow, lineHeight, underline, strikethrough, skipInk, letterSpacing, direction, wordSpacing, textIndent, breakWord, hyphenate, role, } = textElement.getProps();
         // Component -> display list. Wrapping and positioning stay here; the backend
         // turns each run into BT/Tf/Td/Tj/ET. The wrapping algorithm is unchanged from
         // the original renderer - unifying it into the engine is Phase 3.
-        const { runs, links, decorations } = TextRenderer._buildRuns(content, fontSize, fontFamily, fontStyle, objectManager, width ?? Number.NaN, textAlignment, color, x, y, maxLines, overflow, lineHeight, underline, strikethrough, skipInk, letterSpacing, direction, wordSpacing, textIndent);
+        const { runs, links, decorations } = TextRenderer._buildRuns(content, fontSize, fontFamily, fontStyle, objectManager, width ?? Number.NaN, textAlignment, color, x, y, maxLines, overflow, lineHeight, underline, strikethrough, skipInk, letterSpacing, direction, wordSpacing, textIndent, breakWord, hyphenate);
         // Accessible tagging: this whole text block is one structure element (a paragraph P, or a heading
         // from `role`); each run's text lands under it. Emoji sub-nodes produced below stay untagged (drawn
         // as artifacts). Keyed by structId so a block split across pages stays one element.
@@ -224,7 +232,7 @@ export class TextRenderer {
     // Lay the content out into absolutely-positioned text runs. Glyph positions match
     // the previous hand-written operators exactly (verified by pixel-identical render);
     // only the output form changed from PDF strings to `TextRun`s.
-    static _buildRuns(content, fontSize, fontFamily, fontStyle, objectManager, maxWidth, textAlignment, color, initialX, yPosition, maxLines, overflow, lineHeight, underline = false, strikethrough = false, skipInk = false, letterSpacing = 0, direction = "ltr", wordSpacing = 0, textIndent = 0) {
+    static _buildRuns(content, fontSize, fontFamily, fontStyle, objectManager, maxWidth, textAlignment, color, initialX, yPosition, maxLines, overflow, lineHeight, underline = false, strikethrough = false, skipInk = false, letterSpacing = 0, direction = "ltr", wordSpacing = 0, textIndent = 0, breakWord = false, hyphenate) {
         const runs = [];
         // /Link annotation rects for any `href` spans, collected as we place segments. Empty for the
         // common (no-href) case, so plain text keeps producing exactly the runs it did before.
@@ -371,6 +379,7 @@ export class TextRenderer {
                 wordSpacing,
                 indent: textIndent,
                 shrink: align === HorizontalAlignment.justify ? MAX_SPACE_SHRINK : 0,
+                splitting: { breakWord, hyphenate },
             });
             // yPosition is the top of the text box (top-left). The line box seats its own baseline; lines
             // then stack by that box's height. Same numbers as calculateTextHeight, by construction.
@@ -457,7 +466,13 @@ export class TextRenderer {
         // The seam flips the whole thing to PDF space. `letterSpacing` MUST be in the defaults so a span
         // that does not override it wraps and aligns with the element's spacing - the same defaults the
         // measure path (calculateTextHeight) uses, or segmented spaced text mis-wraps (measured != drawn).
-        const defaults = { fontFamily, fontSize, fontStyle, letterSpacing };
+        const defaults = {
+            fontFamily,
+            fontSize,
+            fontStyle,
+            letterSpacing,
+            splitting: { breakWord, hyphenate },
+        };
         let top = yPosition;
         // Materialised, because justification has to know which line is the LAST one of the paragraph.
         const segmentLines = [

package/dist/text/line-breaker.d.ts

@@ -1,6 +1,7 @@
 import type { FontStyle } from "../utils/pdf-object-manager.js";
 import type { FontMetrics } from "../utils/font-metrics.js";
 import type { TextSegment } from "../elements/text-element.js";
+import { type WordSplitting } from "./word-splitting.js";
 /**
  * How far a JUSTIFIED line's spaces may be squeezed to keep one more word on it.
  *
@@ -22,6 +23,8 @@ export interface LineOptions {
     indent?: number;
     /** How far a justified line's spaces may be squeezed to keep one more word (0 = not justified). */
     shrink?: number;
+    /** How a word wider than its box is split - hyphenation, break-word, or neither (the default). */
+    splitting?: WordSplitting;
 }
 /** Default font for segments that don't override it. */
 export interface SegmentDefaults {
@@ -30,6 +33,8 @@ export interface SegmentDefaults {
     fontStyle: FontStyle;
     /** Extra space after every glyph, in points; a segment may override it. Default 0. */
     letterSpacing?: number;
+    /** Same knobs as the string path - see `LineOptions.splitting`. */
+    splitting?: WordSplitting;
 }
 /** What happens to text beyond `maxLines`: `"clip"` drops it, `"ellipsis"` ends the last kept line
  *  with an ellipsis. Mirrors Flutter's `TextOverflow`. */

package/dist/text/line-breaker.js

@@ -1,4 +1,5 @@
 import { runAdvance } from "./advance.js";
+import { splitLongWord } from "./word-splitting.js";
 /**
  * How far a JUSTIFIED line's spaces may be squeezed to keep one more word on it.
  *
@@ -42,7 +43,7 @@ export function singleLineWidth(text, font, metrics, letterSpacing = 0, wordSpac
         : width + (space + runAdvance(metrics, word, font, letterSpacing)), 0);
 }
 export function wrapStringIntoLines(text, fontFamily, fontSize, fontStyle, maxWidth, metrics, maxLines, overflow, letterSpacing = 0, options = {}) {
-    const { wordSpacing = 0, indent = 0, shrink = 0 } = options;
+    const { wordSpacing = 0, indent = 0, shrink = 0, splitting = {} } = options;
     let currentLine = "";
     let currentWidth = 0;
     let gaps = 0; // spaces on the current line, which is what a justified line can squeeze
@@ -72,6 +73,24 @@ export function wrapStringIntoLines(text, fontFamily, fontSize, fontStyle, maxWi
             //
             // A single word wider than maxWidth still sits on its (empty) line and overflows, rather than
             // pushing a phantom empty line before it (which would over-count the height by a line).
+            // A word too wide for the box, split into pieces that fit (hyphenation first, break-word as the
+            // floor). Every piece but the last closes a line; the last carries on as an ordinary word. Off by
+            // default, so a document that asks for neither reaches the untouched path below.
+            // The pieces land on lines that are NOT the first one whenever the current line is closed below,
+            // so they get the full box - `room` only loses the indent while we are genuinely still filling
+            // the indented first line.
+            const splitRoom = lines.length === 0 && currentLine === "" ? room : maxWidth;
+            const split = splitLongWord(word, splitRoom, font, metrics, letterSpacing, splitting);
+            if (split) {
+                if (currentLine !== "")
+                    lines.push(currentLine.trim());
+                for (const piece of split.slice(0, -1))
+                    lines.push(piece);
+                currentLine = split[split.length - 1];
+                currentWidth = runAdvance(metrics, currentLine, font, letterSpacing);
+                gaps = 0;
+                return;
+            }
             const candidate = currentWidth + (spaceWidth + wordWidth);
             if (currentLine === "") {
                 currentLine = word;
@@ -145,6 +164,33 @@ export function breakSegmentsIntoLines(segments, defaults, maxWidth, metrics, ma
             combined = "";
             words.forEach((word, wordIndex) => {
                 const wordWidth = runAdvance(metrics, word, font, letterSpacing);
+                // Same treatment as the string path: a word too wide for the box is split into pieces that fit.
+                // Each finished piece closes the line it sits on, keeping this segment's style.
+                const split = splitLongWord(word, maxWidth, font, metrics, letterSpacing, defaults.splitting ?? {});
+                if (split) {
+                    // Close whatever is already on the line FIRST. The pieces were measured against the full box,
+                    // not against what is left of this line - appending the first one put a line 80 wide into a
+                    // 50 box, and reported 50, which is exactly why it went unnoticed. The string path has always
+                    // pushed its current line before splitting; this is the same move.
+                    if (width > 0) {
+                        lines.push({ segments: lineSegments, width });
+                        lineSegments = [{ ...segment, fontFamily: family, content: "" }];
+                        combined = "";
+                    }
+                    for (const piece of split.slice(0, -1)) {
+                        lineSegments[lineSegments.length - 1].content = piece;
+                        // The width a line REPORTS is what alignment and line-metrics work from: measure it.
+                        lines.push({
+                            segments: lineSegments,
+                            width: runAdvance(metrics, piece, font, letterSpacing),
+                        });
+                        lineSegments = [{ ...segment, fontFamily: family, content: "" }];
+                    }
+                    combined = split[split.length - 1];
+                    width = runAdvance(metrics, combined, font, letterSpacing);
+                    lineSegments[lineSegments.length - 1].content = combined;
+                    return;
+                }
                 // A space joins this word to what precedes it only INSIDE a segment; segments butt together
                 // with nothing between them, which is what `span("a") + span("b")` draws.
                 const joiner = wordIndex > 0 ? spaceWidth : 0;

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

@@ -2,6 +2,7 @@ import { Color } from "../common/color.js";
 import { FontStyle } from "../utils/pdf-object-manager.js";
 import { HorizontalAlignment } from "../elements/pdf-element.js";
 import type { Direction } from "./bidi.js";
+import type { Hyphenator } from "./word-splitting.js";
 /** CSS `text-transform`. `capitalize` upper-cases the first letter of every word, as CSS does. */
 export type TextTransform = "none" | "uppercase" | "lowercase" | "capitalize";
 /**
@@ -50,6 +51,14 @@ export interface ResolvedTextStyle {
     wordSpacing: number;
     /** CSS `text-indent`, in points: how far the FIRST line of a paragraph starts in. */
     textIndent: number;
+    /** CSS `overflow-wrap: break-word`: split a word that is wider than its box, anywhere, no hyphen.
+     *  The floor under `hyphenate` - it is what handles an e-mail, an IBAN or an invoice number, which
+     *  have no valid hyphenation point anywhere. Default off: a too-wide word overflows, as in CSS. */
+    breakWord: boolean;
+    /** Language-aware word splitting: given a word, return its parts (`["Rechts", "schutz", ...]`). A
+     *  hyphen is drawn at the break. Pluggable on purpose - no pattern data ships in this package, so
+     *  there is no licence question and nothing is added to a bundle that never asks for it. */
+    hyphenate?: Hyphenator;
 }
 /**
  * The root of the cascade: what a `Text` falls back to when neither it nor any ancestor sets a

package/dist/text/text-style.js

@@ -54,6 +54,8 @@ export const DEFAULT_TEXT_STYLE = {
     textTransform: "none",
     wordSpacing: 0,
     textIndent: 0,
+    breakWord: false,
+    hyphenate: undefined,
 };
 /** Layers a partial override onto a complete style; an unset (undefined) field keeps the base. */
 export function mergeTextStyle(base, override) {
@@ -75,5 +77,7 @@ export function mergeTextStyle(base, override) {
         textTransform: override.textTransform ?? base.textTransform,
         wordSpacing: override.wordSpacing ?? base.wordSpacing,
         textIndent: override.textIndent ?? base.textIndent,
+        breakWord: override.breakWord ?? base.breakWord,
+        hyphenate: override.hyphenate ?? base.hyphenate,
     };
 }

package/dist/text/word-splitting.d.ts

@@ -0,0 +1,42 @@
+import type { FontStyle } from "../utils/pdf-object-manager.js";
+import type { FontMetrics } from "../utils/font-metrics.js";
+/**
+ * What to do with a word that is wider than the box it has to fit in.
+ *
+ * Until now: nothing. It stayed on its line and drew straight over whatever was beside it - which on an
+ * invoice means a mandatory field (§14 UStG) painted across its own label. CSS overflows too, so this
+ * was never a bug; it was a missing feature, and it is the one that bites in German.
+ *
+ * Two layers, and they are NOT alternatives - CSS stacks them the same way:
+ *
+ *   1. HYPHENATION splits a word at a linguistically valid point and marks it with a hyphen:
+ *      `Rechtsschutzver-` / `sicherungsgesellschaften`. It needs language knowledge, which is why it is
+ *      PLUGGABLE rather than bundled - no pattern data in this package, no licence question, nothing
+ *      added to a bundle that never asks for it.
+ *   2. BREAK-WORD is the floor: split wherever the box ends, no hyphen. It is what handles the things
+ *      hyphenation cannot touch - an e-mail address, an IBAN, an invoice number. Those are single
+ *      "words" with no valid point anywhere, and they are exactly what an invoice is full of.
+ *
+ * With both on, hyphenation is tried first and break-word catches what it cannot split.
+ */
+/** Splits one word into its hyphenation points, e.g. `["Rechts", "schutz", "ver", "siche", ...]`. */
+export type Hyphenator = (word: string) => string[];
+export interface WordSplitting {
+    /** Language-aware splitting, with a hyphen at the break. Supply `hyphen`, `hyphenopoly`, your own. */
+    hyphenate?: Hyphenator;
+    /** Split anywhere as a last resort, without a hyphen. CSS `overflow-wrap: break-word`. */
+    breakWord?: boolean;
+}
+/**
+ * Splits `word` into pieces that each fit within `room`. Returns null when nothing applies - no
+ * splitting configured, or the word fits anyway - and the caller keeps its current behaviour, so a
+ * document that asks for neither is untouched.
+ *
+ * Every piece but the last is a finished line. The last is what carries on, so the caller keeps
+ * filling it as usual.
+ */
+export declare function splitLongWord(word: string, room: number, font: {
+    fontFamily: string;
+    fontSize: number;
+    fontStyle: FontStyle;
+}, metrics: FontMetrics, letterSpacing: number, options: WordSplitting): string[] | null;

package/dist/text/word-splitting.js

@@ -0,0 +1,72 @@
+import { runAdvance } from "./advance.js";
+/** The hyphen actually drawn at a hyphenation break. U+002D, in every font we can encode. */
+const HYPHEN = "-";
+/**
+ * Splits `word` into pieces that each fit within `room`. Returns null when nothing applies - no
+ * splitting configured, or the word fits anyway - and the caller keeps its current behaviour, so a
+ * document that asks for neither is untouched.
+ *
+ * Every piece but the last is a finished line. The last is what carries on, so the caller keeps
+ * filling it as usual.
+ */
+export function splitLongWord(word, room, font, metrics, letterSpacing, options) {
+    const { hyphenate, breakWord } = options;
+    if (!hyphenate && !breakWord)
+        return null;
+    if (room <= 0)
+        return null;
+    if (runAdvance(metrics, word, font, letterSpacing) <= room)
+        return null;
+    const width = (s) => runAdvance(metrics, s, font, letterSpacing);
+    const pieces = [];
+    let rest = word;
+    // Bounded by construction: every pass either emits a piece and shortens `rest`, or gives up.
+    while (width(rest) > room) {
+        // The layering: a linguistically valid split if one is offered and reaches far enough, otherwise
+        // the blunt one - which is what an e-mail address or an IBAN needs, having no valid point at all.
+        const head = (hyphenate ? longestHyphenatedPrefix(rest, room, width, hyphenate) : null) ??
+            (breakWord ? longestPrefix(rest, room, width) : null);
+        // Nothing fits - not even one character, or hyphenation found nothing and break-word is off.
+        // Leave the remainder whole and let it overflow, exactly as before.
+        if (head === null)
+            break;
+        pieces.push(head.text);
+        rest = head.rest;
+    }
+    if (pieces.length === 0)
+        return null;
+    return [...pieces, rest];
+}
+/** The longest prefix that fits, plus a hyphen - split only where the hyphenator allows. */
+function longestHyphenatedPrefix(word, room, width, hyphenate) {
+    const parts = hyphenate(word);
+    if (parts.length < 2)
+        return null;
+    let taken = "";
+    let best = null;
+    for (let i = 0; i < parts.length - 1; i++) {
+        taken += parts[i];
+        // The hyphen has to fit too, or the line it lands on overflows by exactly that hyphen.
+        if (width(taken + HYPHEN) > room)
+            break;
+        best = { text: taken + HYPHEN, rest: parts.slice(i + 1).join("") };
+    }
+    return best;
+}
+/** The longest prefix that fits, split anywhere. Code points, so an astral character stays whole. */
+function longestPrefix(word, room, width) {
+    const chars = [...word];
+    let taken = "";
+    let count = 0;
+    for (const char of chars) {
+        if (width(taken + char) > room)
+            break;
+        taken += char;
+        count += 1;
+    }
+    // Not even one character fits: the box is narrower than a single glyph. Splitting cannot help, and
+    // looping on it would never terminate.
+    if (count === 0 || count === chars.length)
+        return null;
+    return { text: taken, rest: chars.slice(count).join("") };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jasy/pdf",
-  "version": "1.0.0-alpha.11",
+  "version": "1.0.0-alpha.12",
   "description": "Declarative, component-based PDF generation in pure TypeScript - Flutter-style components, real AFM font metrics, a hand-rolled PDF writer. No headless browser, no Java.",
   "keywords": [
     "declarative",
@@ -48,6 +48,7 @@
     "@jimp/types": "^1.6.0",
     "@types/node": "^25.9.3",
     "@vitest/coverage-v8": "^2.1.1",
+    "hyphen": "^1.14.1",
     "ncp": "^2.0.0",
     "oxfmt": "^0.55.0",
     "oxlint": "^1.70.0",