@jasy/pdf 1.0.0-alpha.9 → 1.0.0-beta.1

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.
  *
@@ -31,6 +32,9 @@ const ELLIPSIS = "...";
  * hypothetical: it is what split a footer sized to its own content.
  */
 export function singleLineWidth(text, font, metrics, letterSpacing = 0, wordSpacing = 0) {
+    // A hard break makes this several lines; the natural width is the widest of them.
+    if (text.includes("\n"))
+        return Math.max(...text.split("\n").map((p) => singleLineWidth(p, font, metrics, letterSpacing, wordSpacing)));
     const space = runAdvance(metrics, " ", font, letterSpacing) + wordSpacing;
     return text
         .split(" ")
@@ -39,50 +43,78 @@ 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 = {}, ligatures } = options;
     let currentLine = "";
     let currentWidth = 0;
     let gaps = 0; // spaces on the current line, which is what a justified line can squeeze
     const lines = [];
-    const font = { fontFamily, fontSize, fontStyle };
-    const words = text.split(" ");
-    words.forEach((word) => {
-        // Word and space advances come from the one shared primitive (`advance.ts`), the same one
-        // `naturalWidth` uses - so a bounded and an unbounded layout of the same text agree bit for bit.
-        const wordWidth = runAdvance(metrics, word, font, letterSpacing);
-        const spaceWidth = runAdvance(metrics, " ", font, letterSpacing) + wordSpacing;
-        // The FIRST line has the indent taken out of its room; every later one gets the full box.
-        const room = lines.length === 0 ? maxWidth - indent : maxWidth;
-        // Break before a word that won't fit - counting the SPACE that would join it, which the old test
-        // forgot. It went unnoticed on the first line, where the very first word added a space too many
-        // and cancelled the error out; after a break `currentWidth` is the bare word, so every following
-        // test was short by one space and the line could overrun its box by that much.
-        //
-        // 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).
-        const candidate = currentWidth + (spaceWidth + wordWidth);
-        if (currentLine === "") {
-            currentLine = word;
-            currentWidth = wordWidth;
-            gaps = 0;
-            // How much a JUSTIFIED line may be squeezed to keep one more word: the spaces already on the
-            // line plus the one that would join it, each giving up at most `shrink` of its width. Zero for
-            // every other alignment, where a squeezed line would simply overflow instead.
-            // ONE expression, used for the test AND for the running total. Adding the same three numbers in
-            // a different order gives a different last bit, and a line that lands exactly on `maxWidth` is
-            // then broken by that bit alone - which is how a footer sized to its own text wrapped.
-        }
-        else if (candidate - (gaps + 1) * spaceWidth * shrink > room) {
+    const font = { fontFamily, fontSize, fontStyle, ligatures };
+    // A `\n` is a HARD break: wrap each paragraph on its own, then cut. An EMPTY paragraph still has to
+    // produce a line, or a deliberate blank line between two blocks silently disappears.
+    text.split("\n").forEach((paragraph, paragraphIndex) => {
+        if (paragraphIndex > 0) {
             lines.push(currentLine.trim());
-            currentLine = word;
-            currentWidth = wordWidth;
+            currentLine = "";
+            currentWidth = 0;
             gaps = 0;
         }
-        else {
-            currentLine += " " + word;
-            currentWidth = candidate;
-            gaps += 1;
-        }
+        const words = paragraph.split(" ");
+        words.forEach((word) => {
+            // Word and space advances come from the one shared primitive (`advance.ts`), the same one
+            // `naturalWidth` uses - so a bounded and an unbounded layout of the same text agree bit for bit.
+            const wordWidth = runAdvance(metrics, word, font, letterSpacing);
+            const spaceWidth = runAdvance(metrics, " ", font, letterSpacing) + wordSpacing;
+            // The FIRST line has the indent taken out of its room; every later one gets the full box.
+            const room = lines.length === 0 ? maxWidth - indent : maxWidth;
+            // Break before a word that won't fit - counting the SPACE that would join it, which the old test
+            // forgot. It went unnoticed on the first line, where the very first word added a space too many
+            // and cancelled the error out; after a break `currentWidth` is the bare word, so every following
+            // test was short by one space and the line could overrun its box by that much.
+            //
+            // 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;
+                currentWidth = wordWidth;
+                gaps = 0;
+                // How much a JUSTIFIED line may be squeezed to keep one more word: the spaces already on the
+                // line plus the one that would join it, each giving up at most `shrink` of its width. Zero for
+                // every other alignment, where a squeezed line would simply overflow instead.
+                // ONE expression, used for the test AND for the running total. Adding the same three numbers in
+                // a different order gives a different last bit, and a line that lands exactly on `maxWidth` is
+                // then broken by that bit alone - which is how a footer sized to its own text wrapped.
+            }
+            else if (candidate - (gaps + 1) * spaceWidth * shrink > room) {
+                lines.push(currentLine.trim());
+                currentLine = word;
+                currentWidth = wordWidth;
+                gaps = 0;
+            }
+            else {
+                currentLine += " " + word;
+                currentWidth = candidate;
+                gaps += 1;
+            }
+        });
     });
     if (currentLine)
         lines.push(currentLine.trim());
@@ -94,7 +126,7 @@ export function wrapStringIntoLines(text, fontFamily, fontSize, fontStyle, maxWi
         const last = kept.length - 1;
         kept[last] = ellipsize(kept[last], fontFamily, fontSize, fontStyle, 
         // The same room that line was broken against: the first one lost the indent to it.
-        last === 0 ? maxWidth - indent : maxWidth, metrics, letterSpacing, wordSpacing);
+        last === 0 ? maxWidth - indent : maxWidth, metrics, letterSpacing, wordSpacing, ligatures);
     }
     return kept;
 }
@@ -114,43 +146,87 @@ export function breakSegmentsIntoLines(segments, defaults, maxWidth, metrics, ma
         const size = segment.fontSize || defaults.fontSize;
         const style = segment.fontStyle || defaults.fontStyle;
         const letterSpacing = segment.letterSpacing ?? defaults.letterSpacing ?? 0;
-        const font = { fontFamily: family, fontSize: size, fontStyle: style };
+        const font = {
+            fontFamily: family,
+            fontSize: size,
+            fontStyle: style,
+            ligatures: defaults.ligatures,
+        };
         const spaceWidth = runAdvance(metrics, " ", font, letterSpacing);
-        const words = segment.content.split(" ");
-        // Start this segment's piece empty; its content is filled word-by-word below. (Not
-        // the original content - otherwise a segment whose FIRST word overflows would carry
-        // its whole text into the line that just closed.)
-        lineSegments.push({ ...segment, fontFamily: family, content: "" });
-        combined = "";
-        words.forEach((word, wordIndex) => {
-            const wordWidth = runAdvance(metrics, word, font, letterSpacing);
-            // 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;
-            // ONE expression for the test and for the running total, grouped exactly as `singleLineWidth`
-            // groups it - see the note there. A width built any other way can be a bit off the one the box
-            // was sized with, and the text wraps inside a box made to hold it.
-            const candidate = width + (joiner + wordWidth);
-            // Same guard as the string path: don't open a phantom empty line for an over-wide first word -
-            // place it (overflowing) on the current empty line instead.
-            if (candidate > maxWidth && width > 0) {
+        // A `\n` inside a span is a HARD break, exactly as in the string path: close the line where it
+        // sits, whatever else was already on it, and start the next one with this segment's style.
+        segment.content.split("\n").forEach((paragraph, paragraphIndex) => {
+            if (paragraphIndex > 0) {
                 lines.push({ segments: lineSegments, width });
-                width = wordWidth;
+                width = 0;
                 lineSegments = [];
-                combined = word;
-                lineSegments.push({ ...segment, content: combined });
             }
-            else {
-                combined += wordIndex === 0 ? word : " " + word;
-                width = candidate;
-                if (lineSegments.length === 0) {
-                    lineSegments.push({ ...segment, fontFamily: family, content: combined });
+            const words = paragraph.split(" ");
+            // Start this segment's piece empty; its content is filled word-by-word below. (Not
+            // the original content - otherwise a segment whose FIRST word overflows would carry
+            // its whole text into the line that just closed.)
+            lineSegments.push({ ...segment, fontFamily: family, content: "" });
+            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;
                 }
-                lineSegments[lineSegments.length - 1].content = combined;
-            }
+                // 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;
+                // ONE expression for the test and for the running total, grouped exactly as `singleLineWidth`
+                // groups it - see the note there. A width built any other way can be a bit off the one the box
+                // was sized with, and the text wraps inside a box made to hold it.
+                const candidate = width + (joiner + wordWidth);
+                // Same guard as the string path: don't open a phantom empty line for an over-wide first word -
+                // place it (overflowing) on the current empty line instead.
+                if (candidate > maxWidth && width > 0) {
+                    lines.push({ segments: lineSegments, width });
+                    width = wordWidth;
+                    lineSegments = [];
+                    combined = word;
+                    lineSegments.push({ ...segment, content: combined });
+                }
+                else {
+                    combined += wordIndex === 0 ? word : " " + word;
+                    width = candidate;
+                    if (lineSegments.length === 0) {
+                        lineSegments.push({ ...segment, fontFamily: family, content: combined });
+                    }
+                    lineSegments[lineSegments.length - 1].content = combined;
+                }
+            });
         });
     });
-    if (lineSegments.length > 0) {
+    // Only if something actually landed on it. The string path ends with `if (currentLine)`, so a text
+    // ending in `\n` is ONE line there - the two must not disagree about the same text. An empty
+    // paragraph in the MIDDLE still becomes a line; that one is pushed at the break, not here.
+    if (lineSegments.some((seg) => seg.content !== "")) {
         lines.push({ segments: lineSegments, width });
     }
     // Open-end by default; cap only when maxLines is set.
@@ -182,8 +258,8 @@ export function segmentLinesToSegments(lines) {
 }
 /** Appends "…" to a single line, dropping trailing words (then characters) until the line plus the
  *  ellipsis fits `maxWidth`. Falls back to a bare "…" if not even one character fits. */
-function ellipsize(line, fontFamily, fontSize, fontStyle, maxWidth, metrics, letterSpacing = 0, wordSpacing = 0) {
-    const font = { fontFamily, fontSize, fontStyle };
+function ellipsize(line, fontFamily, fontSize, fontStyle, maxWidth, metrics, letterSpacing = 0, wordSpacing = 0, ligatures) {
+    const font = { fontFamily, fontSize, fontStyle, ligatures };
     // Measured through `singleLineWidth`, so the ellipsised line is judged by the same sum that decides
     // every other line - word-spacing included.
     const fits = (s) => singleLineWidth(s + ELLIPSIS, font, metrics, letterSpacing, wordSpacing) <= maxWidth;

package/dist/text/shape.d.ts

@@ -23,7 +23,7 @@ export interface ShapingFont {
 /**
  * Shape a run, or `undefined` when there is nothing to do - so untouched documents keep their path.
  *
- * `rlig` (required ligatures - lam-alef, wrong when drawn apart) but not `liga`, which is
- * discretionary and would change how existing Latin text looks.
+ * Arabic always applies `rlig` - lam-alef is wrong when drawn apart. Latin applies whatever `features`
+ * asks for, which is `liga` today; the list is the seam a general `fontFeatures` would use.
  */
-export declare function shapeRun(codePoints: readonly number[], font: ShapingFont): ShapedGlyph[] | undefined;
+export declare function shapeRun(codePoints: readonly number[], font: ShapingFont, features?: readonly string[]): ShapedGlyph[] | undefined;

package/dist/text/shape.js

@@ -9,14 +9,18 @@ const FORM_FEATURES = {
 /**
  * Shape a run, or `undefined` when there is nothing to do - so untouched documents keep their path.
  *
- * `rlig` (required ligatures - lam-alef, wrong when drawn apart) but not `liga`, which is
- * discretionary and would change how existing Latin text looks.
+ * Arabic always applies `rlig` - lam-alef is wrong when drawn apart. Latin applies whatever `features`
+ * asks for, which is `liga` today; the list is the seam a general `fontFeatures` would use.
  */
-export function shapeRun(codePoints, font) {
-    if (!needsJoining(codePoints))
-        return undefined;
+export function shapeRun(codePoints, font, features = []) {
     const gsub = font.gsub();
-    if (!gsub || !gsub.hasScript("arab"))
+    if (!gsub)
+        return undefined;
+    if (!needsJoining(codePoints)) {
+        // Latin: no joining, only the substitutions the caller asked for.
+        return features.length > 0 ? shapeLatin(codePoints, font, gsub, features) : undefined;
+    }
+    if (!gsub.hasScript("arab"))
         return undefined;
     const forms = joiningForms(codePoints);
     let glyphs = codePoints.map((cp, i) => {
@@ -35,12 +39,32 @@ export function shapeRun(codePoints, font) {
         }
         return { glyph, advance: font.getAdvanceWidth(glyph), codePoints: [cp] };
     });
-    glyphs = applyLigatures(glyphs, gsub, font);
+    glyphs = applyLigatures(glyphs, gsub, font, "arab", "rlig");
     return glyphs;
 }
-/** Collapse required ligatures, longest match first, carrying every component's code points along. */
-function applyLigatures(glyphs, gsub, font) {
-    const lookups = gsub.lookups("arab", "rlig");
+/**
+ * Latin: no joining, only ligatures. Returns undefined when the font offers none, so a document that
+ * asks for them but uses a font without them keeps the plain path and stays byte-identical.
+ */
+function shapeLatin(codePoints, font, gsub, features) {
+    if (!gsub.hasScript("latn"))
+        return undefined;
+    const wanted = features.filter((f) => gsub.lookups("latn", f).length > 0);
+    if (wanted.length === 0)
+        return undefined;
+    const plain = codePoints.map((cp) => {
+        const glyph = font.getGlyphIndex(cp);
+        return { glyph, advance: font.getAdvanceWidth(glyph), codePoints: [cp] };
+    });
+    let shaped = plain;
+    for (const feature of wanted)
+        shaped = applyLigatures(shaped, gsub, font, "latn", feature);
+    // Nothing merged: hand back undefined so the caller measures and draws the untouched run.
+    return shaped.length === plain.length ? undefined : shaped;
+}
+/** Collapse ligatures, longest match first, carrying every component's code points along. */
+function applyLigatures(glyphs, gsub, font, script, feature) {
+    const lookups = gsub.lookups(script, feature);
     if (lookups.length === 0)
         return glyphs;
     const ids = glyphs.map((g) => g.glyph);

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,18 @@ export interface ResolvedTextStyle {
     wordSpacing: number;
     /** CSS `text-indent`, in points: how far the FIRST line of a paragraph starts in. */
     textIndent: number;
+    /** The ligatures the font's designer drew (`fi`, `fl`, `ffi`), from its GSUB. ON, like kerning: CSS,
+     *  browsers and every other renderer apply them, and nobody should need the word to get text set
+     *  properly. `false` opts a document, a subtree or one `Text` out. Embedded fonts only. */
+    ligatures: boolean;
+    /** 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,9 @@ export const DEFAULT_TEXT_STYLE = {
     textTransform: "none",
     wordSpacing: 0,
     textIndent: 0,
+    ligatures: true,
+    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 +78,8 @@ export function mergeTextStyle(base, override) {
         textTransform: override.textTransform ?? base.textTransform,
         wordSpacing: override.wordSpacing ?? base.wordSpacing,
         textIndent: override.textIndent ?? base.textIndent,
+        ligatures: override.ligatures ?? base.ligatures,
+        breakWord: override.breakWord ?? base.breakWord,
+        hyphenate: override.hyphenate ?? base.hyphenate,
     };
 }

package/dist/text/whitespace.d.ts

@@ -0,0 +1,4 @@
+import type { TextSegment } from "../elements/text-element.js";
+export declare function normalizeWhitespace(text: string): string;
+/** The same, for content that may already be split into styled spans. */
+export declare function normalizeContent(content: string | TextSegment[]): string | TextSegment[];

package/dist/text/whitespace.js

@@ -0,0 +1,43 @@
+/**
+ * A character with no glyph is still ENCODED and DRAWN: it comes out as the font's .notdef box, and
+ * veraPDF rejects the file for referencing .notdef (ISO 19005-3, 6.2.11.8). A `\n` in an invoice
+ * description was the first case we hit; zero-width characters are the same fault and arrive far more
+ * quietly - a paste out of Word or a web page carries them routinely.
+ *
+ * So nothing invisible survives into the breaker except `\n`, and that only because the breaker treats
+ * it as a hard break. The mapping follows a browser's `white-space: normal` apart from `\n`: CSS
+ * collapses that to a space, while a text COMPONENT breaks on it - Flutter's `Text` and react-pdf both
+ * do, and it is what anyone writing `"a\nb"` expects.
+ */
+/**
+ * Everything that MEANS a line break, matched as a WHOLE so a two-character ending never becomes two
+ * breaks. `\n\r` is in here beside `\r\n` because it is what a mistyped CRLF looks like, and a stray
+ * blank line is a worse answer than reading it as the one break it was meant to be. U+2028/U+2029 are
+ * Unicode's own line and paragraph separators.
+ */
+const LINE_BREAKS = /\r\n|\n\r|\r|\u2028|\u2029/g;
+/**
+ * Invisible and inert: a zero-width space and a byte-order mark carry no meaning we act on, so they are
+ * dropped rather than drawn. C0, C1 and DEL likewise.
+ *
+ * Deliberately NOT here: U+200C/U+200D (zero-width non-joiner and joiner) drive Arabic shaping and
+ * emoji sequences, and U+200E/U+200F (the bidi marks) drive `text/bidi.ts`. Dropping those would
+ * silently change how correct text is laid out - worse than the box they can still leave behind in a
+ * run that neither shapes nor reorders.
+ */
+// oxlint-disable-next-line no-control-regex -- matching control characters is the whole point here.
+const UNPRINTABLE = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F-\u009F\u200B\uFEFF]/g;
+export function normalizeWhitespace(text) {
+    return (text
+        // Every spelling of a break becomes `\n` first, so the breaker only ever sees one form.
+        .replace(LINE_BREAKS, "\n")
+        // A tab is collapsible whitespace; a PDF text operator has no tab stops to advance to.
+        .replace(/\t/g, " ")
+        .replace(UNPRINTABLE, ""));
+}
+/** The same, for content that may already be split into styled spans. */
+export function normalizeContent(content) {
+    if (typeof content === "string")
+        return normalizeWhitespace(content);
+    return content.map((seg) => ({ ...seg, content: normalizeWhitespace(seg.content) }));
+}

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("") };
+}