@jasy/pdf 1.0.0-alpha.8 → 1.0.0-alpha.9

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

@@ -1,6 +1,28 @@
 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";
+/**
+ * How far a JUSTIFIED line's spaces may be squeezed to keep one more word on it.
+ *
+ * A quarter, because our breaker is GREEDY: it will use the whole allowance every time that saves a
+ * line, so the limit has to be the tightest word space still worth reading - about three quarters of
+ * natural, the usual typographic floor. TeX allows a third, but its badness model rarely spends it.
+ * For reference, react-pdf reaches -19% in practice (measured: a 3.18pt space squeezed to 2.58pt),
+ * which this covers. Its packing can still differ by a word, because it spreads the squeeze over the
+ * CHARACTERS as well as the spaces.
+ *
+ * Only justified text uses it: under any other alignment a squeezed line would simply overflow.
+ */
+export declare const MAX_SPACE_SHRINK: number;
+/** The knobs that change where a line ENDS, beyond the font and the box. */
+export interface LineOptions {
+    /** Extra advance at every space (CSS `word-spacing`), in points. */
+    wordSpacing?: number;
+    /** How far the FIRST line starts in (CSS `text-indent`), in points - it has that much less room. */
+    indent?: number;
+    /** How far a justified line's spaces may be squeezed to keep one more word (0 = not justified). */
+    shrink?: number;
+}
 /** Default font for segments that don't override it. */
 export interface SegmentDefaults {
     fontFamily: string;
@@ -26,7 +48,19 @@ export interface SegmentLine {
  * rendering call this, so they can never disagree. Depends only on `FontMetrics`,
  * not the PDF byte writer - the future fragmentation pass can reuse it.
  */
-export declare function wrapStringIntoLines(text: string, fontFamily: string, fontSize: number, fontStyle: FontStyle, maxWidth: number, metrics: FontMetrics, maxLines?: number, overflow?: TextOverflow, letterSpacing?: number): string[];
+/**
+ * The width of `text` set as ONE line, accumulated in EXACTLY the order `wrapStringIntoLines` builds a
+ * line: the first word, then `+ (space + word)` each time. The order matters because floating-point
+ * addition is not associative - a box sized by a differently-grouped sum can be one bit too small for
+ * the very line the breaker then measures, and the text wraps inside a box made to fit it. That is not
+ * hypothetical: it is what split a footer sized to its own content.
+ */
+export declare function singleLineWidth(text: string, font: {
+    fontFamily: string;
+    fontSize: number;
+    fontStyle: FontStyle;
+}, metrics: FontMetrics, letterSpacing?: number, wordSpacing?: number): number;
+export declare function wrapStringIntoLines(text: string, fontFamily: string, fontSize: number, fontStyle: FontStyle, maxWidth: number, metrics: FontMetrics, maxLines?: number, overflow?: TextOverflow, letterSpacing?: number, options?: LineOptions): string[];
 /**
  * Break styled segments into lines that fit within `maxWidth`. Same greedy word-splitting as the
  * string breaker; each line keeps the segments that landed on it, which is what `line-metrics.ts`

package/dist/text/line-breaker.js

@@ -1,4 +1,17 @@
 import { runAdvance } from "./advance.js";
+/**
+ * How far a JUSTIFIED line's spaces may be squeezed to keep one more word on it.
+ *
+ * A quarter, because our breaker is GREEDY: it will use the whole allowance every time that saves a
+ * line, so the limit has to be the tightest word space still worth reading - about three quarters of
+ * natural, the usual typographic floor. TeX allows a third, but its badness model rarely spends it.
+ * For reference, react-pdf reaches -19% in practice (measured: a 3.18pt space squeezed to 2.58pt),
+ * which this covers. Its packing can still differ by a word, because it spreads the squeeze over the
+ * CHARACTERS as well as the spaces.
+ *
+ * Only justified text uses it: under any other alignment a squeezed line would simply overflow.
+ */
+export const MAX_SPACE_SHRINK = 1 / 4;
 /** Three ASCII dots, NOT the "…" glyph (U+2026): plain dots encode in every font - standard-14
  *  (WinAnsi) and any embedded TTF - whereas U+2026 needs a glyph the font may not carry. */
 const ELLIPSIS = "...";
@@ -10,28 +23,65 @@ const ELLIPSIS = "...";
  * rendering call this, so they can never disagree. Depends only on `FontMetrics`,
  * not the PDF byte writer - the future fragmentation pass can reuse it.
  */
-export function wrapStringIntoLines(text, fontFamily, fontSize, fontStyle, maxWidth, metrics, maxLines, overflow, letterSpacing = 0) {
+/**
+ * The width of `text` set as ONE line, accumulated in EXACTLY the order `wrapStringIntoLines` builds a
+ * line: the first word, then `+ (space + word)` each time. The order matters because floating-point
+ * addition is not associative - a box sized by a differently-grouped sum can be one bit too small for
+ * the very line the breaker then measures, and the text wraps inside a box made to fit it. That is not
+ * hypothetical: it is what split a footer sized to its own content.
+ */
+export function singleLineWidth(text, font, metrics, letterSpacing = 0, wordSpacing = 0) {
+    const space = runAdvance(metrics, " ", font, letterSpacing) + wordSpacing;
+    return text
+        .split(" ")
+        .reduce((width, word, i) => i === 0
+        ? runAdvance(metrics, word, font, letterSpacing)
+        : 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;
     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, index) => {
+    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);
-        // Break before a word that won't fit - but only once the line has content. A single word wider
-        // than maxWidth must sit on its (empty) line and overflow, not push a phantom empty line before
-        // it (which would over-count the height by a line and shift the text down at render).
-        if (currentWidth + wordWidth > maxWidth && currentLine !== "") {
+        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) {
             lines.push(currentLine.trim());
             currentLine = word;
             currentWidth = wordWidth;
+            gaps = 0;
         }
         else {
-            currentLine += index === 0 ? word : " " + word;
-            currentWidth += wordWidth + spaceWidth;
+            currentLine += " " + word;
+            currentWidth = candidate;
+            gaps += 1;
         }
     });
     if (currentLine)
@@ -42,7 +92,9 @@ export function wrapStringIntoLines(text, fontFamily, fontSize, fontStyle, maxWi
     const kept = lines.slice(0, maxLines);
     if (overflow === "ellipsis") {
         const last = kept.length - 1;
-        kept[last] = ellipsize(kept[last], fontFamily, fontSize, fontStyle, maxWidth, metrics, letterSpacing);
+        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);
     }
     return kept;
 }
@@ -72,19 +124,25 @@ export function breakSegmentsIntoLines(segments, defaults, maxWidth, metrics, ma
         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 (width + wordWidth > maxWidth && width > 0) {
+            if (candidate > maxWidth && width > 0) {
                 lines.push({ segments: lineSegments, width });
-                width = 0;
+                width = wordWidth;
                 lineSegments = [];
                 combined = word;
-                width += wordWidth + spaceWidth;
                 lineSegments.push({ ...segment, content: combined });
             }
             else {
                 combined += wordIndex === 0 ? word : " " + word;
-                width += wordWidth + spaceWidth;
+                width = candidate;
                 if (lineSegments.length === 0) {
                     lineSegments.push({ ...segment, fontFamily: family, content: combined });
                 }
@@ -124,9 +182,11 @@ 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) {
+function ellipsize(line, fontFamily, fontSize, fontStyle, maxWidth, metrics, letterSpacing = 0, wordSpacing = 0) {
     const font = { fontFamily, fontSize, fontStyle };
-    const fits = (s) => runAdvance(metrics, s + ELLIPSIS, font, letterSpacing) <= maxWidth;
+    // 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;
     if (fits(line))
         return line + ELLIPSIS;
     const words = line.split(" ");

package/dist/text/orphans-widows.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Orphan and widow control for a paragraph split across a page break.
+ *
+ * An **orphan** is the first line of a paragraph left alone at the bottom of a page; a **widow** is
+ * the last line pushed alone to the top of the next. Both read as mistakes, and neither is prevented
+ * by splitting at line boxes - which is all the fragmenter does on its own.
+ *
+ * This is a correction of the split INDEX, not a second mechanism: the fragmenter works out how many
+ * lines fit, and this decides whether that number is acceptable.
+ */
+/** How many lines must stay behind / must carry over. Both default to 2, the CSS initial value. */
+export interface OrphanWidowRule {
+    orphans: number;
+    widows: number;
+}
+export declare const DEFAULT_ORPHANS = 2;
+export declare const DEFAULT_WIDOWS = 2;
+/**
+ * Correct a line count so the split leaves at least `orphans` lines behind and carries at least
+ * `widows` over. Returns 0 to mean "none of it fits here" - the caller then moves the whole paragraph
+ * on, exactly as it already does when not even one line fits.
+ *
+ * Terminating by construction: every answer is either the natural count, a SMALLER one, or 0. It
+ * never asks for more lines than fit, and the page driver's guard already handles a paragraph that
+ * does not fit on a whole page (it places it anyway rather than looping).
+ */
+export declare function adjustForOrphansWidows(fitted: number, total: number, { orphans, widows }: OrphanWidowRule): number;

package/dist/text/orphans-widows.js

@@ -0,0 +1,53 @@
+/**
+ * Orphan and widow control for a paragraph split across a page break.
+ *
+ * An **orphan** is the first line of a paragraph left alone at the bottom of a page; a **widow** is
+ * the last line pushed alone to the top of the next. Both read as mistakes, and neither is prevented
+ * by splitting at line boxes - which is all the fragmenter does on its own.
+ *
+ * This is a correction of the split INDEX, not a second mechanism: the fragmenter works out how many
+ * lines fit, and this decides whether that number is acceptable.
+ */
+export const DEFAULT_ORPHANS = 2;
+export const DEFAULT_WIDOWS = 2;
+/**
+ * Correct a line count so the split leaves at least `orphans` lines behind and carries at least
+ * `widows` over. Returns 0 to mean "none of it fits here" - the caller then moves the whole paragraph
+ * on, exactly as it already does when not even one line fits.
+ *
+ * Terminating by construction: every answer is either the natural count, a SMALLER one, or 0. It
+ * never asks for more lines than fit, and the page driver's guard already handles a paragraph that
+ * does not fit on a whole page (it places it anyway rather than looping).
+ */
+export function adjustForOrphansWidows(fitted, total, { orphans, widows }) {
+    // Both are LINE COUNTS and end up as a slice index, so anything but a positive whole number is
+    // meaningless: 0 or less silently disables the rule it belongs to, and a fraction would be truncated
+    // somewhere downstream rather than here. Named at the boundary instead.
+    check(orphans, "orphans");
+    check(widows, "widows");
+    if (fitted <= 0)
+        return 0; // nothing fits; the caller decides
+    if (fitted >= total)
+        return total; // no split needed, nothing to protect
+    // NOTE: an explicit "too short to satisfy both ends" rule (total < orphans + widows) sat here and was
+    // removed - it is unreachable. Either fewer lines stay than `orphans` allows, and the next check
+    // returns 0; or at least `orphans` stay, and then fewer than `widows` must carry, so the pull-back
+    // below lands under `orphans` and returns 0 as well. react-pdf spells the case out; we do not need to.
+    //
+    // Fewer lines would stay than an orphan is allowed to be.
+    if (fitted < orphans)
+        return 0;
+    // Fewer lines would carry over than a widow is allowed to be: pull the cut back so exactly `widows`
+    // go over - unless that would leave too few behind, in which case the paragraph moves whole.
+    if (total - fitted < widows) {
+        const pulled = total - widows;
+        return pulled >= orphans ? pulled : 0;
+    }
+    return fitted;
+}
+function check(value, name) {
+    if (!Number.isInteger(value) || value < 1) {
+        throw new Error(`Invalid ${name}: ${value}. It is a number of LINES, so it must be a whole number of at least 1 ` +
+            `(1 means no protection at that end).`);
+    }
+}

package/dist/text/shape.d.ts

@@ -0,0 +1,29 @@
+import type { GsubTable } from "../utils/gsub.js";
+/**
+ * SHAPING: code points in, the glyphs actually drawn out. Where the two halves meet - `arabic.ts`
+ * says WHICH positional form a letter takes, `gsub.ts` says which GLYPH that form is in this font.
+ *
+ * Not a string, because a ligature is one glyph for several code points. `codePoints` carries the
+ * origin so `ToUnicode` can still say what the glyph means.
+ */
+/** One drawn glyph, with the code points it came from. */
+export interface ShapedGlyph {
+    glyph: number;
+    /** Advance in FONT UNITS - the caller scales by fontSize / unitsPerEm, as everywhere else. */
+    advance: number;
+    /** The code points this glyph stands for; more than one only for a ligature. */
+    codePoints: number[];
+}
+/** The little a font has to answer for shaping - deliberately not the whole `TTFParser`. */
+export interface ShapingFont {
+    gsub(): GsubTable | undefined;
+    getGlyphIndex(codePoint: number): number;
+    getAdvanceWidth(glyph: number): number;
+}
+/**
+ * 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.
+ */
+export declare function shapeRun(codePoints: readonly number[], font: ShapingFont): ShapedGlyph[] | undefined;

package/dist/text/shape.js

@@ -0,0 +1,67 @@
+import { joiningForms, needsJoining } from "./arabic.js";
+/** The features that realise the four positional forms, in the order a shaper applies them. */
+const FORM_FEATURES = {
+    isol: "isol",
+    init: "init",
+    medi: "medi",
+    fina: "fina",
+};
+/**
+ * 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.
+ */
+export function shapeRun(codePoints, font) {
+    if (!needsJoining(codePoints))
+        return undefined;
+    const gsub = font.gsub();
+    if (!gsub || !gsub.hasScript("arab"))
+        return undefined;
+    const forms = joiningForms(codePoints);
+    let glyphs = codePoints.map((cp, i) => {
+        let glyph = font.getGlyphIndex(cp);
+        const form = forms[i];
+        if (form) {
+            // First lookup that covers the glyph wins. A missing `isol` is normal: the plain glyph already
+            // IS that form.
+            for (const lookup of gsub.lookups("arab", FORM_FEATURES[form])) {
+                const substituted = gsub.substituteSingle(lookup, glyph);
+                if (substituted !== null) {
+                    glyph = substituted;
+                    break;
+                }
+            }
+        }
+        return { glyph, advance: font.getAdvanceWidth(glyph), codePoints: [cp] };
+    });
+    glyphs = applyLigatures(glyphs, gsub, font);
+    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");
+    if (lookups.length === 0)
+        return glyphs;
+    const ids = glyphs.map((g) => g.glyph);
+    const out = [];
+    for (let i = 0; i < glyphs.length;) {
+        let applied = false;
+        for (const lookup of lookups) {
+            const match = gsub.substituteLigature(lookup, ids, i);
+            if (!match)
+                continue;
+            out.push({
+                glyph: match.glyph,
+                advance: font.getAdvanceWidth(match.glyph),
+                codePoints: glyphs.slice(i, i + match.consumed).flatMap((g) => g.codePoints),
+            });
+            i += match.consumed;
+            applied = true;
+            break;
+        }
+        if (!applied)
+            out.push(glyphs[i++]);
+    }
+    return out;
+}

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

@@ -1,6 +1,19 @@
 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";
+/** CSS `text-transform`. `capitalize` upper-cases the first letter of every word, as CSS does. */
+export type TextTransform = "none" | "uppercase" | "lowercase" | "capitalize";
+/**
+ * Apply a `text-transform`. One place, so the measured text and the drawn text are the same string.
+ *
+ * `atWordStart` carries the capitalisation state ACROSS pieces: a word split over two spans
+ * (`span("hel") + span("lo")`) is still one word, and only its first letter is raised.
+ */
+export declare function applyTextTransform(text: string, transform: TextTransform, atWordStart?: boolean): {
+    text: string;
+    atWordStart: boolean;
+};
 /**
  * The inheritable text properties - the same set CSS and Flutter cascade. A `Text` resolves each of
  * its own (possibly unset) properties against the nearest cascaded style: explicit > inherited >
@@ -10,6 +23,8 @@ import { HorizontalAlignment } from "../elements/pdf-element.js";
 export interface ResolvedTextStyle {
     fontSize: number;
     fontFamily: string;
+    /** The rest of the family stack: tried, in order, for a code point `fontFamily` cannot draw. */
+    fontFallback: string[];
     fontStyle: FontStyle;
     color: Color;
     textAlignment: HorizontalAlignment;
@@ -25,6 +40,16 @@ export interface ResolvedTextStyle {
     skipInk: boolean;
     /** Extra space after every glyph, in points (CSS `letter-spacing`). Default 0. */
     letterSpacing: number;
+    /** Base writing direction (CSS `direction`). It decides where a line STARTS and how neutral
+     *  characters between two scripts resolve; the reordering itself follows Unicode UAX #9 either
+     *  way, so Hebrew inside an `ltr` paragraph still comes out right. */
+    direction: Direction;
+    /** CSS `text-transform`: recase the text before it is measured or drawn. */
+    textTransform: TextTransform;
+    /** CSS `word-spacing`, in points: extra advance at every space. Negative tightens. */
+    wordSpacing: number;
+    /** CSS `text-indent`, in points: how far the FIRST line of a paragraph starts in. */
+    textIndent: number;
 }
 /**
  * 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

@@ -1,6 +1,39 @@
 import { Color } from "../common/color.js";
 import { FontStyle } from "../utils/pdf-object-manager.js";
 import { HorizontalAlignment } from "../elements/pdf-element.js";
+/**
+ * Apply a `text-transform`. One place, so the measured text and the drawn text are the same string.
+ *
+ * `atWordStart` carries the capitalisation state ACROSS pieces: a word split over two spans
+ * (`span("hel") + span("lo")`) is still one word, and only its first letter is raised.
+ */
+export function applyTextTransform(text, transform, atWordStart = true) {
+    const ends = text === "" ? atWordStart : /\s$/u.test(text);
+    if (transform === "none")
+        return { text, atWordStart: ends };
+    if (transform === "uppercase")
+        return { text: text.toUpperCase(), atWordStart: ends };
+    if (transform === "lowercase")
+        return { text: text.toLowerCase(), atWordStart: ends };
+    // CSS raises the first typographic LETTER of every word. Punctuation is not one, so a leading
+    // bracket or quote does not consume the word start - `(hello)` becomes `(Hello)`, as in a browser.
+    let start = atWordStart;
+    let out = "";
+    for (const ch of text) {
+        if (/\s/u.test(ch)) {
+            out += ch;
+            start = true;
+        }
+        else if (start && /\p{L}|\p{N}/u.test(ch)) {
+            out += ch.toUpperCase();
+            start = false;
+        }
+        else {
+            out += ch;
+        }
+    }
+    return { text: out, atWordStart: start };
+}
 /**
  * The root of the cascade: what a `Text` falls back to when neither it nor any ancestor sets a
  * property.
@@ -8,14 +41,19 @@ import { HorizontalAlignment } from "../elements/pdf-element.js";
 export const DEFAULT_TEXT_STYLE = {
     fontSize: 12,
     fontFamily: "Helvetica",
+    fontFallback: [],
     fontStyle: FontStyle.Normal,
     color: new Color(0, 0, 0),
-    textAlignment: HorizontalAlignment.left,
+    textAlignment: HorizontalAlignment.start,
     lineHeight: undefined,
     underline: false,
     strikethrough: false,
     skipInk: false,
     letterSpacing: 0,
+    direction: "ltr",
+    textTransform: "none",
+    wordSpacing: 0,
+    textIndent: 0,
 };
 /** Layers a partial override onto a complete style; an unset (undefined) field keeps the base. */
 export function mergeTextStyle(base, override) {
@@ -24,6 +62,7 @@ export function mergeTextStyle(base, override) {
     return {
         fontSize: override.fontSize ?? base.fontSize,
         fontFamily: override.fontFamily ?? base.fontFamily,
+        fontFallback: override.fontFallback ?? base.fontFallback,
         fontStyle: override.fontStyle ?? base.fontStyle,
         color: override.color ?? base.color,
         textAlignment: override.textAlignment ?? base.textAlignment,
@@ -32,5 +71,9 @@ export function mergeTextStyle(base, override) {
         strikethrough: override.strikethrough ?? base.strikethrough,
         skipInk: override.skipInk ?? base.skipInk,
         letterSpacing: override.letterSpacing ?? base.letterSpacing,
+        direction: override.direction ?? base.direction,
+        textTransform: override.textTransform ?? base.textTransform,
+        wordSpacing: override.wordSpacing ?? base.wordSpacing,
+        textIndent: override.textIndent ?? base.textIndent,
     };
 }

package/dist/utils/flex-layout.d.ts

@@ -2,10 +2,8 @@ import { PDFElement, LayoutContext } from "../elements/pdf-element.js";
 import { BoxConstraints, Offset, Size } from "../layout/box-constraints.js";
 /** Distribution of the children ALONG the stacking (main) axis when there is leftover
  *  space and no flex child to absorb it. */
-export type MainAlign = "start" | "center" | "end" | "between" | "around";
-/** Position/size of each child ACROSS the cross axis. `stretch` fills the cross extent;
- *  the others place the child at its natural cross size. */
-export type CrossAlign = "start" | "center" | "end" | "stretch";
+export type { MainAlign, CrossAlign } from "../layout/alignment.js";
+import type { CrossAlign, MainAlign } from "../layout/alignment.js";
 /**
  * Maps the abstract MAIN/CROSS axes onto concrete width/height + x/y, so one flex
  * algorithm drives both a vertical Column (main = height) and a horizontal Row
@@ -42,6 +40,12 @@ export interface FlexOptions {
     gap?: number;
     main?: MainAlign;
     cross?: CrossAlign;
+    /** Lay the children out along the main axis backwards (CSS `row-reverse` / `column-reverse`). */
+    reverse?: boolean;
+    /** Let the children flow onto further lines when they do not fit (CSS `flex-wrap: wrap`). */
+    wrap?: boolean;
+    /** How the BLOCK of wrapped lines sits across the axis (CSS `align-content`). Default `start`. */
+    alignContent?: MainAlign;
 }
 export declare class FlexLayoutHelper {
     /**
@@ -53,8 +57,24 @@ export declare class FlexLayoutHelper {
      * extent occupied. Vertical with `gap 0`, `main start`, `cross stretch` reproduces the
      * previous Column layout exactly.
      */
+    /**
+     * Lays out the children along `axis`, on one line or several.
+     *
+     * Without `wrap` this is the single-line engine and nothing about it changed - the call goes
+     * straight through, which is what keeps every existing document byte-identical. With `wrap` the
+     * children are split into lines first and the SAME engine runs once per line.
+     */
     static layout(children: PDFElement[], axis: FlexAxis, mainAvail: number, crossAvail: number, mainStart: number, crossOrigin: number, options: FlexOptions, ctx: LayoutContext): {
         mainUsed: number;
         crossUsed: number;
     };
+    /**
+     * The wrapping path: split into lines, lay each one out, then place the lines across the axis.
+     *
+     * Lines are laid out TWICE - once to learn how tall each is, once at its final cross position. That
+     * is the same measure-then-place shape the single-line engine already uses, and it is what
+     * `alignContent` needs: the block of lines can only be centred once its total is known.
+     */
+    private static layoutWrapped;
+    private static layoutLine;
 }