@jasy/pdf 1.0.0-alpha.6 → 1.0.0-alpha.7

package/dist/renderer/text-renderer.js

@@ -3,28 +3,30 @@ import { HorizontalAlignment } from "../elements/pdf-element.js";
 import { isEmojiCodePoint } from "../text/emoji-codepoints.js";
 import { emojiImageNode } from "./emoji-image.js";
 import { wrapStringIntoLines, breakSegmentsIntoLines, } from "../text/line-breaker.js";
-// Distance from the top of a line down to its baseline, as a fraction of the font
-// size. ~0.683 is the standard-14 ascent ratio used to seat the first baseline.
-const BASELINE_RATIO = 683 / 1000;
+import { lineBoxForSegmentLine, lineBoxForString } from "../text/line-metrics.js";
+import { runAdvance } from "../text/advance.js";
+import { skipInkSegments, strikethroughStroke, underlineStroke, } from "../text/text-decoration.js";
 export class TextRenderer {
     // Measuring only needs metrics, not the full object manager. (The render pass below
     // still receives the manager because it also registers fonts/images.)
-    static calculateTextHeight(content, fontSize, fontFamily, fontStyle, objectManager, maxWidth, maxLines, overflow, lineHeight = 1) {
-        // Plain string: one line box (fontSize * lineHeight) per wrapped line.
+    static calculateTextHeight(content, fontSize, fontFamily, fontStyle, objectManager, maxWidth, maxLines, overflow, lineHeight, letterSpacing = 0) {
+        // Plain string: every wrapped line gets the same box.
         if (typeof content === "string") {
-            const lines = wrapStringIntoLines(content, fontFamily, fontSize, fontStyle, maxWidth, objectManager, maxLines, overflow);
-            return lines.length * fontSize * lineHeight;
+            const lines = wrapStringIntoLines(content, fontFamily, fontSize, fontStyle, maxWidth, objectManager, maxLines, overflow, letterSpacing);
+            const box = lineBoxForString(objectManager, fontFamily, fontStyle, fontSize, lineHeight);
+            return lines.length * box.height;
         }
-        // Segments: each line contributes its own (tallest-on-line) leading, scaled by lineHeight.
-        const lines = breakSegmentsIntoLines(content, { fontFamily, fontSize, fontStyle }, maxWidth, objectManager, maxLines, overflow);
-        return lines.reduce((total, line) => total + line.maxFontSize * lineHeight, 0);
+        // Segments: each line's box comes from the fonts actually on it.
+        const defaults = { fontFamily, fontSize, fontStyle, letterSpacing };
+        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, role, } = textElement.getProps();
+        const { x, y, width, fontSize, color, content, fontFamily, fontStyle, textAlignment, maxLines, overflow, lineHeight, underline, strikethrough, skipInk, letterSpacing, 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 } = TextRenderer._buildRuns(content, fontSize, fontFamily, fontStyle, objectManager, width ?? Number.NaN, textAlignment, color, x, y, maxLines, overflow, lineHeight);
+        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);
         // 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.
@@ -37,9 +39,11 @@ export class TextRenderer {
         // Color fonts (COLR/CPAL): expand each run's emoji into filled vector layers (or fetched images
         // for an image emoji source); plain runs and monochrome fonts pass straight through unchanged.
         const drawn = (await Promise.all(runs.map((run) => TextRenderer._expandColorGlyphs(run, objectManager)))).flat();
+        // Underline / strikethrough go on TOP of the glyphs (a strikethrough must), and stay untagged,
+        // so the structure tree treats them as artifacts rather than as text.
         // Inline hyperlinks (href spans) ride along as /Link annotations - they draw nothing, so order
         // vs the drawn runs does not matter; the page renderer peels them off into /Annots.
-        return links.length > 0 ? [...drawn, ...links] : drawn;
+        return [...drawn, ...decorations, ...links];
     }
     // Splits a text run into normal text sub-runs + filled `Path` layers for any COLR color glyphs,
     // walking code point by code point and advancing the pen by each glyph's width. Returns `[run]`
@@ -82,8 +86,10 @@ export class TextRenderer {
                 if (l)
                     [source, layers] = [fallback, l];
             }
-            // The advance matches measuring (getCharWidth applies the same emoji fallback).
-            const advance = om.getCharWidth(ch, run.fontSize, undefined, run.fontFamily, run.fontStyle);
+            // The advance matches measuring (getCharWidth applies the same emoji fallback), plus the run's
+            // letter-spacing so a spaced run's emoji sit where `Tc` advances them.
+            const advance = om.getCharWidth(ch, run.fontSize, undefined, run.fontFamily, run.fontStyle) +
+                (run.letterSpacing ?? 0);
             if (source && layers) {
                 flushPending();
                 const scale = run.fontSize / source.unitsPerEm;
@@ -209,11 +215,14 @@ 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 = 1) {
+    static _buildRuns(content, fontSize, fontFamily, fontStyle, objectManager, maxWidth, textAlignment, color, initialX, yPosition, maxLines, overflow, lineHeight, underline = false, strikethrough = false, skipInk = false, letterSpacing = 0) {
         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.
         const links = [];
+        // Underline / strikethrough strokes, one per decorated run (so a wrapped paragraph gets one
+        // per line, and a decorated span only spans its own glyphs).
+        const decorations = [];
         // Horizontal offset of a line of the given width under the current alignment.
         const alignmentOffset = (lineWidth) => {
             if (textAlignment === HorizontalAlignment.center)
@@ -222,39 +231,78 @@ export class TextRenderer {
                 return maxWidth - lineWidth;
             return 0;
         };
-        // Advance width WITHOUT kerning. This is how Tj moves the text cursor, so
-        // segments flowing after each other land here. (Standard-14 fonts carry no
-        // /Widths array; the viewer advances by the AFM widths - same source as below.)
-        const advanceNoKerning = (text, family, size, style) => {
-            let width = 0;
-            for (const ch of text) {
-                width += objectManager.getCharWidth(ch, size, undefined, family, style);
+        // The decoration strokes for one drawn run, at the geometry ITS OWN font declares. A mixed-size
+        // line therefore gets a thicker line under the bigger span, which is what a browser does too.
+        const decorate = (text, runX, runWidth, baselineY, family, style, size, runColor, wantsUnderline, wantsStrikethrough, runLetterSpacing) => {
+            if ((!wantsUnderline && !wantsStrikethrough) || runWidth <= 0)
+                return;
+            const metrics = objectManager.getFontDecoration(family, style);
+            const push = (from, to, stroke) => {
+                decorations.push({
+                    type: "line",
+                    x1: runX + from,
+                    y1: stroke.y,
+                    x2: runX + to,
+                    y2: stroke.y,
+                    stroke: runColor,
+                    strokeWidth: stroke.thickness,
+                });
+            };
+            if (wantsUnderline) {
+                const stroke = underlineStroke(metrics, size, baselineY);
+                for (const [from, to] of underlineSegments(text, runWidth, baselineY, size, family, style, stroke, runLetterSpacing)) {
+                    push(from, to, stroke);
+                }
+            }
+            // A strikethrough crosses the letters by definition, so it is never interrupted.
+            if (wantsStrikethrough) {
+                const stroke = strikethroughStroke(metrics, size, baselineY);
+                push(0, runWidth, stroke);
             }
-            return width;
         };
+        // The x-ranges the underline actually draws. Without `skipInk` that is the whole run; with it,
+        // the descenders are cut out of it (which needs the real outlines, i.e. an embedded font).
+        const underlineSegments = (text, runWidth, baselineY, size, family, style, stroke, runLetterSpacing) => {
+            if (!skipInk)
+                return [[0, runWidth]];
+            if (!objectManager.isCustomFont(family, style)) {
+                throw new Error(`skipInk needs an embedded font, but "${family}" is a standard-14 font whose glyph outlines ` +
+                    `live in the PDF viewer, not in the document - we cannot see where its ink is. Register a ` +
+                    `font (the document's \`fonts\` option) or drop \`skipInk\`.`);
+            }
+            // The band the stroke covers, in points from the baseline, y UP (so both values are negative).
+            const below = stroke.y - baselineY;
+            const half = stroke.thickness / 2;
+            const inkSpans = objectManager.getInkSpansInBand(text, size, family, style, -below + half, -below - half, runLetterSpacing);
+            return skipInkSegments(runWidth, inkSpans, stroke.thickness);
+        };
+        // The advance the viewer will use: plain glyph widths (a `Tj` never kerns) plus one
+        // `letterSpacing` per code point (the `Tc` operator), from the one shared `advance.ts` primitive.
+        const font = { fontFamily, fontSize, fontStyle };
         // --- Plain string: one run per wrapped line. ---
         if (typeof content === "string") {
-            const lines = wrapStringIntoLines(content, fontFamily, fontSize, fontStyle, maxWidth, objectManager, maxLines, overflow);
-            // yPosition is the top of the text box (top-left); seat line 0's baseline below it, then step
-            // DOWN by one line box (fontSize * lineHeight) per line. The lineHeight EXTRA leading is split
-            // half above / half below (CSS/Flutter "half-leading"), so the text sits centered in its line
-            // box instead of clinging to the top. At lineHeight 1 the half-leading is 0 -> byte-identical.
-            const halfLeading = (fontSize * (lineHeight - 1)) / 2;
-            const baseline = yPosition + halfLeading + fontSize * BASELINE_RATIO;
+            const lines = wrapStringIntoLines(content, fontFamily, fontSize, fontStyle, maxWidth, objectManager, maxLines, overflow, letterSpacing);
+            // 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.
+            const box = lineBoxForString(objectManager, fontFamily, fontStyle, fontSize, lineHeight);
             lines.forEach((line, index) => {
-                const lineWidth = objectManager.getStringWidth(line, fontFamily, fontSize, fontStyle);
+                const lineWidth = runAdvance(objectManager, line, font, letterSpacing);
+                const x = initialX + alignmentOffset(lineWidth);
+                const baseline = yPosition + box.baseline + box.height * index;
                 runs.push({
                     type: "text",
-                    x: initialX + alignmentOffset(lineWidth),
-                    y: baseline + fontSize * lineHeight * index,
+                    x,
+                    y: baseline,
                     text: line,
                     fontFamily,
                     fontStyle,
                     fontSize,
                     color,
+                    ...(letterSpacing ? { letterSpacing } : {}),
                 });
+                decorate(line, x, lineWidth, baseline, fontFamily, fontStyle, fontSize, color, underline, strikethrough, letterSpacing);
             });
-            return { runs, links };
+            return { runs, links, decorations };
         }
         // --- Segments: break into lines (shared breaker), then emit one run per segment.
         // Segment 0 starts at the aligned line origin; each following segment is offset by
@@ -267,7 +315,9 @@ export class TextRenderer {
                 const family = segment.fontFamily || fontFamily;
                 const size = segment.fontSize || fontSize;
                 const style = segment.fontStyle || fontStyle;
-                const advance = advanceNoKerning(segment.content, family, size, style);
+                const segLetterSpacing = segment.letterSpacing ?? letterSpacing;
+                const advance = runAdvance(objectManager, segment.content, { fontFamily: family, fontSize: size, fontStyle: style }, segLetterSpacing);
+                const runColor = segment.fontColor || color;
                 runs.push({
                     type: "text",
                     x,
@@ -276,18 +326,21 @@ export class TextRenderer {
                     fontFamily: family,
                     fontStyle: style,
                     fontSize: size,
-                    color: segment.fontColor || color,
+                    color: runColor,
+                    ...(segLetterSpacing ? { letterSpacing: segLetterSpacing } : {}),
                 });
-                // An href/to span becomes a /Link annotation over exactly this run's glyph box. `lineY` is the
-                // baseline; the box spans from the ascent (BASELINE_RATIO above it) down by the full size, so
-                // ascent + descent are covered. A span wrapped across lines yields one rect per line.
+                decorate(segment.content, x, advance, lineY, family, style, size, runColor, segment.underline ?? underline, segment.strikethrough ?? strikethrough, segLetterSpacing);
+                // An href/to span becomes a /Link annotation over exactly this run's glyph box: from its own
+                // ascent above the baseline down to its own descender. A span wrapped across lines yields
+                // one rect per line.
                 if (segment.href !== undefined || segment.dest !== undefined) {
+                    const v = objectManager.getFontVerticals(family, style);
                     links.push({
                         type: "link",
                         x,
-                        y: lineY - size * BASELINE_RATIO,
+                        y: lineY - v.ascent * size,
                         width: advance,
-                        height: size,
+                        height: (v.ascent + v.descent) * size,
                         href: segment.href,
                         dest: segment.dest,
                     });
@@ -295,23 +348,18 @@ export class TextRenderer {
                 x += advance;
             });
         };
-        // The overall tallest font seats the first baseline; each line then steps DOWN by
-        // its own leading. yPosition is the top of the text box (top-left); the seam flips
-        // the whole thing to PDF space.
-        let overallMaxFont = fontSize;
-        for (const segment of content) {
-            const size = segment.fontSize || fontSize;
-            if (size > overallMaxFont)
-                overallMaxFont = size;
-        }
-        let lineY = yPosition + overallMaxFont * BASELINE_RATIO;
-        for (const line of breakSegmentsIntoLines(content, { fontFamily, fontSize, fontStyle }, maxWidth, objectManager, maxLines, overflow)) {
-            // Half-leading: shift this line's baseline down by half its own extra leading, so the line
-            // sits centered in its box (CSS/Flutter). At lineHeight 1 the shift is 0 -> byte-identical.
-            const halfLeading = (line.maxFontSize * (lineHeight - 1)) / 2;
-            pushLine(line, lineY + halfLeading);
-            lineY += line.maxFontSize * lineHeight;
+        // yPosition is the top of the text box (top-left). Each line seats its own baseline inside its
+        // own box (tallest ascent / deepest descent ON THAT LINE), then the next line starts below it.
+        // 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 };
+        let top = yPosition;
+        for (const line of breakSegmentsIntoLines(content, defaults, maxWidth, objectManager, maxLines, overflow)) {
+            const box = lineBoxForSegmentLine(line, defaults, objectManager, lineHeight);
+            pushLine(line, top + box.baseline);
+            top += box.height;
         }
-        return { runs, links };
+        return { runs, links, decorations };
     }
 }

package/dist/text/advance.d.ts

@@ -0,0 +1,34 @@
+/**
+ * How wide a run of text is: the horizontal counterpart to `line-metrics.ts` (how tall a line is)
+ * and `line-breaker.ts` (where a line breaks). The ONE canonical answer to "how far does the pen
+ * move", so measuring and drawing can never disagree about it.
+ *
+ * An advance has three parts, each with its own PDF mechanism:
+ *
+ *     advance = sum(glyph widths)  +  sum(kerning)  +  n * letterSpacing
+ *                  /Widths             TJ array          Tc
+ *
+ * `letterSpacing` is added after EVERY code point, the last one included - exactly what the `Tc`
+ * operator does, and exactly what CSS `letter-spacing` does (which is why right-aligned spaced text
+ * looks a hair offset: a spacing hangs off the final glyph). Measuring `(n - 1)` spacings while `Tc`
+ * applies `n` would make every line draw one spacing wider than it was wrapped - text out of its box.
+ *
+ * Kerning is added ONLY when the document has it on (`metrics.kerningEnabled`), and then the backend
+ * emits a `TJ` with the same per-pair adjustments - so a measured advance always equals the drawn
+ * one. With kerning off, `getStringWidth` is the whole advance (its plain glyph sum), byte-identical
+ * to before. Folding kerning into the measurement while the output ignored it was the 2026-07-10 bug.
+ */
+import type { FontStyle } from "../utils/pdf-object-manager.js";
+import type { FontMetrics } from "../utils/font-metrics.js";
+/** The font a run is set in. */
+export interface RunFont {
+    fontFamily: string;
+    fontSize: number;
+    fontStyle: FontStyle;
+}
+/** Number of Unicode code points (not UTF-16 units): an astral char is ONE, so it takes one
+ *  letter-spacing, not two. Matches how `getStringWidth` iterates. */
+export declare function codePointCount(text: string): number;
+/** The advance of `text` in points: the plain glyph widths, plus kerning (if the document has it on),
+ *  plus one `letterSpacing` per code point. */
+export declare function runAdvance(metrics: FontMetrics, text: string, font: RunFont, letterSpacing?: number): number;

package/dist/text/advance.js

@@ -0,0 +1,42 @@
+/**
+ * How wide a run of text is: the horizontal counterpart to `line-metrics.ts` (how tall a line is)
+ * and `line-breaker.ts` (where a line breaks). The ONE canonical answer to "how far does the pen
+ * move", so measuring and drawing can never disagree about it.
+ *
+ * An advance has three parts, each with its own PDF mechanism:
+ *
+ *     advance = sum(glyph widths)  +  sum(kerning)  +  n * letterSpacing
+ *                  /Widths             TJ array          Tc
+ *
+ * `letterSpacing` is added after EVERY code point, the last one included - exactly what the `Tc`
+ * operator does, and exactly what CSS `letter-spacing` does (which is why right-aligned spaced text
+ * looks a hair offset: a spacing hangs off the final glyph). Measuring `(n - 1)` spacings while `Tc`
+ * applies `n` would make every line draw one spacing wider than it was wrapped - text out of its box.
+ *
+ * Kerning is added ONLY when the document has it on (`metrics.kerningEnabled`), and then the backend
+ * emits a `TJ` with the same per-pair adjustments - so a measured advance always equals the drawn
+ * one. With kerning off, `getStringWidth` is the whole advance (its plain glyph sum), byte-identical
+ * to before. Folding kerning into the measurement while the output ignored it was the 2026-07-10 bug.
+ */
+/** Number of Unicode code points (not UTF-16 units): an astral char is ONE, so it takes one
+ *  letter-spacing, not two. Matches how `getStringWidth` iterates. */
+export function codePointCount(text) {
+    let n = 0;
+    for (const _ of text)
+        n++;
+    return n;
+}
+/** The advance of `text` in points: the plain glyph widths, plus kerning (if the document has it on),
+ *  plus one `letterSpacing` per code point. */
+export function runAdvance(metrics, text, font, letterSpacing = 0) {
+    let advance = metrics.getStringWidth(text, font.fontFamily, font.fontSize, font.fontStyle);
+    if (letterSpacing !== 0)
+        advance += codePointCount(text) * letterSpacing;
+    if (metrics.kerningEnabled) {
+        let units = 0;
+        for (const k of metrics.getKernPairs(text, font.fontFamily, font.fontStyle))
+            units += k;
+        advance += (units / 1000) * font.fontSize; // kern units are em/1000
+    }
+    return advance;
+}

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

@@ -6,16 +6,17 @@ export interface SegmentDefaults {
     fontFamily: string;
     fontSize: number;
     fontStyle: FontStyle;
+    /** Extra space after every glyph, in points; a segment may override it. Default 0. */
+    letterSpacing?: number;
 }
 /** What happens to text beyond `maxLines`: `"clip"` drops it, `"ellipsis"` ends the last kept line
  *  with an ellipsis. Mirrors Flutter's `TextOverflow`. */
 export type TextOverflow = "clip" | "ellipsis";
-/** One laid-out line of segments. `maxFontSize` is the tallest font ON THIS LINE - its
- *  leading - matching how real engines (and this lib's plain-string path) space lines. */
+/** One laid-out line of segments. How TALL it is does not live here: the breaker owns the horizontal
+ *  half, `text/line-metrics.ts` owns the vertical one and derives the box from the fonts on the line. */
 export interface SegmentLine {
     segments: TextSegment[];
     width: number;
-    maxFontSize: number;
 }
 /**
  * Break a plain string into lines that each fit within `maxWidth`, splitting on
@@ -25,12 +26,12 @@ 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): string[];
+export declare function wrapStringIntoLines(text: string, fontFamily: string, fontSize: number, fontStyle: FontStyle, maxWidth: number, metrics: FontMetrics, maxLines?: number, overflow?: TextOverflow, letterSpacing?: number): string[];
 /**
- * Break styled segments into lines that fit within `maxWidth`. Same greedy
- * word-splitting as the string breaker, but each line records the tallest font on
- * THAT line as its leading (per-line, not a paragraph-global maximum). Single source
- * of truth: both height measurement and rendering call this.
+ * 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`
+ * later derives the line's height from. Single source of truth: both height measurement and
+ * rendering call this.
  */
 export declare function breakSegmentsIntoLines(segments: TextSegment[], defaults: SegmentDefaults, maxWidth: number, metrics: FontMetrics, maxLines?: number, overflow?: TextOverflow): SegmentLine[];
 /**

package/dist/text/line-breaker.js

@@ -1,3 +1,4 @@
+import { runAdvance } from "./advance.js";
 /** 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 = "...";
@@ -9,14 +10,17 @@ 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) {
+export function wrapStringIntoLines(text, fontFamily, fontSize, fontStyle, maxWidth, metrics, maxLines, overflow, letterSpacing = 0) {
     let currentLine = "";
     let currentWidth = 0;
     const lines = [];
+    const font = { fontFamily, fontSize, fontStyle };
     const words = text.split(" ");
     words.forEach((word, index) => {
-        const wordWidth = metrics.getStringWidth(word, fontFamily, fontSize, fontStyle);
-        const spaceWidth = metrics.getCharWidth(" ", fontSize, undefined, fontFamily, fontStyle);
+        // 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).
@@ -38,44 +42,41 @@ 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);
+        kept[last] = ellipsize(kept[last], fontFamily, fontSize, fontStyle, maxWidth, metrics, letterSpacing);
     }
     return kept;
 }
 /**
- * Break styled segments into lines that fit within `maxWidth`. Same greedy
- * word-splitting as the string breaker, but each line records the tallest font on
- * THAT line as its leading (per-line, not a paragraph-global maximum). Single source
- * of truth: both height measurement and rendering call this.
+ * 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`
+ * later derives the line's height from. Single source of truth: both height measurement and
+ * rendering call this.
  */
 export function breakSegmentsIntoLines(segments, defaults, maxWidth, metrics, maxLines, overflow) {
     const lines = [];
     let width = 0;
-    let maxFontSize = 0; // per line: starts at 0, grows to the tallest font on the line
     let lineSegments = [];
     let combined = "";
     segments.forEach((segment) => {
         const family = segment.fontFamily || defaults.fontFamily;
         const size = segment.fontSize || defaults.fontSize;
         const style = segment.fontStyle || defaults.fontStyle;
-        const spaceWidth = metrics.getCharWidth(" ", size, undefined, family, style);
+        const letterSpacing = segment.letterSpacing ?? defaults.letterSpacing ?? 0;
+        const font = { fontFamily: family, fontSize: size, fontStyle: style };
+        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 = "";
-        if (maxFontSize < size)
-            maxFontSize = size;
         words.forEach((word, wordIndex) => {
-            const wordWidth = metrics.getStringWidth(word, family, size, style);
+            const wordWidth = runAdvance(metrics, word, font, letterSpacing);
             // 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) {
-                lines.push({ segments: lineSegments, width, maxFontSize });
-                // Start the next line; its leading resets to the wrapping segment's size.
+                lines.push({ segments: lineSegments, width });
                 width = 0;
-                maxFontSize = size;
                 lineSegments = [];
                 combined = word;
                 width += wordWidth + spaceWidth;
@@ -92,7 +93,7 @@ export function breakSegmentsIntoLines(segments, defaults, maxWidth, metrics, ma
         });
     });
     if (lineSegments.length > 0) {
-        lines.push({ segments: lineSegments, width, maxFontSize });
+        lines.push({ segments: lineSegments, width });
     }
     // Open-end by default; cap only when maxLines is set.
     if (maxLines == null || lines.length <= maxLines)
@@ -123,8 +124,9 @@ 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) {
-    const fits = (s) => metrics.getStringWidth(s + ELLIPSIS, fontFamily, fontSize, fontStyle) <= maxWidth;
+function ellipsize(line, fontFamily, fontSize, fontStyle, maxWidth, metrics, letterSpacing = 0) {
+    const font = { fontFamily, fontSize, fontStyle };
+    const fits = (s) => runAdvance(metrics, s + ELLIPSIS, font, letterSpacing) <= maxWidth;
     if (fits(line))
         return line + ELLIPSIS;
     const words = line.split(" ");
@@ -150,11 +152,16 @@ function ellipsizeSegmentLine(line, defaults, maxWidth, metrics) {
     const segs = line.segments;
     if (segs.length === 0)
         return;
-    const widthOf = (seg) => metrics.getStringWidth(seg.content, seg.fontFamily || defaults.fontFamily, seg.fontSize || defaults.fontSize, seg.fontStyle || defaults.fontStyle);
+    const lsOf = (seg) => seg.letterSpacing ?? defaults.letterSpacing ?? 0;
+    const widthOf = (seg) => runAdvance(metrics, seg.content, {
+        fontFamily: seg.fontFamily || defaults.fontFamily,
+        fontSize: seg.fontSize || defaults.fontSize,
+        fontStyle: seg.fontStyle || defaults.fontStyle,
+    }, lsOf(seg));
     let prefix = 0;
     for (let i = 0; i < segs.length - 1; i++)
         prefix += widthOf(segs[i]);
     const last = segs[segs.length - 1];
-    last.content = ellipsize(last.content, last.fontFamily || defaults.fontFamily, last.fontSize || defaults.fontSize, last.fontStyle || defaults.fontStyle, maxWidth - prefix, metrics);
+    last.content = ellipsize(last.content, last.fontFamily || defaults.fontFamily, last.fontSize || defaults.fontSize, last.fontStyle || defaults.fontStyle, maxWidth - prefix, metrics, lsOf(last));
     line.width = prefix + widthOf(last);
 }

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

@@ -0,0 +1,49 @@
+/**
+ * The vertical half of text layout: how tall a line box is, and where its baseline sits.
+ *
+ * One canonical answer, like `line-breaker.ts` is the one canonical answer for the horizontal
+ * half. Measuring (`calculateTextHeight`), fragmenting (`TextElement.fragment`) and drawing
+ * (`TextRenderer._buildRuns`) all call in here, so they can never disagree about a line's height
+ * again - the divergence that produced ISSUE-5.
+ */
+import type { FontStyle } from "../utils/pdf-object-manager.js";
+import type { FontMetrics } from "../utils/font-metrics.js";
+import type { SegmentDefaults, SegmentLine } from "./line-breaker.js";
+/** A font's vertical metrics, as fractions of the em (so they scale by multiplying with fontSize). */
+export interface FontVerticals {
+    /** Distance from the baseline up to the ascender. Positive. */
+    ascent: number;
+    /** Distance from the baseline down to the descender. Positive (unlike the AFM/hhea sign). */
+    descent: number;
+    /** Extra leading the font asks for between two lines. Often 0 for a TrueType face. */
+    lineGap: number;
+}
+/** One font used on a line: its metrics and the size it is set at. */
+export interface LinePart {
+    verticals: FontVerticals;
+    fontSize: number;
+}
+/** A laid-out line box, in points, relative to the top of the box. */
+export interface LineBox {
+    /** Total height of the line box. Lines stack by this. */
+    height: number;
+    /** Distance from the top of the line box down to the baseline. */
+    baseline: number;
+}
+/**
+ * The line box for a set of fonts sharing one line.
+ *
+ * `lineHeight` is a multiplier of the font size, like CSS. Leave it `undefined` for the font's
+ * NATURAL line height (`ascent + descent + lineGap`), which is what CSS calls `line-height: normal`.
+ *
+ * Whatever is left over between the box and the font's content is split evenly above and below
+ * ("half-leading", as CSS and Flutter do), so the glyphs sit centred in their own box. An explicit
+ * `lineHeight` smaller than the content makes the leading negative and the glyphs overflow - again
+ * exactly like CSS, and the author asked for it.
+ */
+export declare function lineBoxFor(parts: LinePart[], lineHeight?: number): LineBox;
+/** The line box of a single-font line (the plain-string path). */
+export declare function lineBoxForString(metrics: FontMetrics, fontFamily: string, fontStyle: FontStyle, fontSize: number, lineHeight?: number): LineBox;
+/** The line box of a mixed-font line: the tallest ascent and the deepest descent on it win, so a
+ *  big or a deep-descending span pushes the whole line apart rather than colliding with it. */
+export declare function lineBoxForSegmentLine(line: SegmentLine, defaults: SegmentDefaults, metrics: FontMetrics, lineHeight?: number): LineBox;

package/dist/text/line-metrics.js

@@ -0,0 +1,57 @@
+/**
+ * The vertical half of text layout: how tall a line box is, and where its baseline sits.
+ *
+ * One canonical answer, like `line-breaker.ts` is the one canonical answer for the horizontal
+ * half. Measuring (`calculateTextHeight`), fragmenting (`TextElement.fragment`) and drawing
+ * (`TextRenderer._buildRuns`) all call in here, so they can never disagree about a line's height
+ * again - the divergence that produced ISSUE-5.
+ */
+/**
+ * The line box for a set of fonts sharing one line.
+ *
+ * `lineHeight` is a multiplier of the font size, like CSS. Leave it `undefined` for the font's
+ * NATURAL line height (`ascent + descent + lineGap`), which is what CSS calls `line-height: normal`.
+ *
+ * Whatever is left over between the box and the font's content is split evenly above and below
+ * ("half-leading", as CSS and Flutter do), so the glyphs sit centred in their own box. An explicit
+ * `lineHeight` smaller than the content makes the leading negative and the glyphs overflow - again
+ * exactly like CSS, and the author asked for it.
+ */
+export function lineBoxFor(parts, lineHeight) {
+    if (parts.length === 0)
+        return { height: 0, baseline: 0 };
+    let ascent = 0;
+    let descent = 0;
+    let gap = 0;
+    let maxFontSize = 0;
+    for (const { verticals, fontSize } of parts) {
+        ascent = Math.max(ascent, verticals.ascent * fontSize);
+        descent = Math.max(descent, verticals.descent * fontSize);
+        gap = Math.max(gap, verticals.lineGap * fontSize);
+        maxFontSize = Math.max(maxFontSize, fontSize);
+    }
+    const content = ascent + descent;
+    const height = lineHeight === undefined ? content + gap : maxFontSize * lineHeight;
+    return { height, baseline: (height - content) / 2 + ascent };
+}
+/** The line box of a single-font line (the plain-string path). */
+export function lineBoxForString(metrics, fontFamily, fontStyle, fontSize, lineHeight) {
+    return lineBoxFor([{ verticals: metrics.getFontVerticals(fontFamily, fontStyle), fontSize }], lineHeight);
+}
+/** The line box of a mixed-font line: the tallest ascent and the deepest descent on it win, so a
+ *  big or a deep-descending span pushes the whole line apart rather than colliding with it. */
+export function lineBoxForSegmentLine(line, defaults, metrics, lineHeight) {
+    const parts = line.segments.map((segment) => {
+        const fontFamily = segment.fontFamily ?? defaults.fontFamily;
+        const fontStyle = segment.fontStyle ?? defaults.fontStyle;
+        return {
+            verticals: metrics.getFontVerticals(fontFamily, fontStyle),
+            fontSize: segment.fontSize ?? defaults.fontSize,
+        };
+    });
+    // A line with no segments still occupies its default font's box (an empty paragraph keeps height).
+    if (parts.length === 0) {
+        return lineBoxForString(metrics, defaults.fontFamily, defaults.fontStyle, defaults.fontSize, lineHeight);
+    }
+    return lineBoxFor(parts, lineHeight);
+}