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

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

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

@@ -0,0 +1,50 @@
+/**
+ * Where an underline and a strikethrough sit, and how thick they are.
+ *
+ * These are GLYPH metrics, and they are deliberately NOT part of `FontVerticals` in
+ * `line-metrics.ts`, which holds LINE metrics. Confusing the two is exactly what produced ISSUE-5:
+ * the AFM's `Ascender` (the height of a `b`) was used to seat a baseline, a job that belongs to the
+ * `FontBBox`. Keep the two kinds of number in two places so they cannot be mixed up again.
+ *
+ * Every number here comes out of the font: the standard-14 AFM header, or a TrueType `post` +
+ * `OS/2` table. Nothing is invented. Verified against `google-chrome --headless --print-to-pdf` on
+ * the same font: Chrome's strikethrough centre lands on `xHeight / 2` (measured 0.260 em vs the
+ * font's 0.262), and its underline stroke with `text-decoration-thickness: from-font` is the font's
+ * `underlineThickness` (0.048 em vs 0.050). Chrome does NOT use the font's underline POSITION - it
+ * has its own offset - so we follow the font there and land within 0.02 em of it.
+ */
+/** A font's decoration metrics, as fractions of the em. */
+export interface FontDecoration {
+    /** Distance BELOW the baseline to the CENTRE of the underline stroke. Positive.
+     *  (The AFM defines it as "the distance from the baseline for centering underlining strokes";
+     *  FreeType reads TrueType's `post.underlinePosition` the same way.) */
+    underlinePosition: number;
+    /** Stroke thickness, used by both the underline and the strikethrough. */
+    underlineThickness: number;
+    /** Height of a lowercase `x` above the baseline. Sets where a strikethrough crosses. */
+    xHeight: number;
+    /** Height of a capital above the baseline. */
+    capHeight: number;
+}
+/** A decoration stroke: the y of its centre line, and how thick it is. Points, engine coords. */
+export interface DecorationStroke {
+    y: number;
+    thickness: number;
+}
+/** The underline for a run whose baseline sits at `baselineY` (engine coords, y grows down). */
+export declare function underlineStroke(decoration: FontDecoration, fontSize: number, baselineY: number): DecorationStroke;
+/**
+ * The strikethrough for a run whose baseline sits at `baselineY`. It crosses at half the x-height,
+ * which is what a browser does and what looks right: through the middle of the lowercase letters,
+ * not through the middle of the capitals.
+ */
+export declare function strikethroughStroke(decoration: FontDecoration, fontSize: number, baselineY: number): DecorationStroke;
+/**
+ * Cuts `[0, runWidth]` at every place the glyphs put ink, leaving the segments an underline should
+ * actually draw. `inkSpans` are x-intervals in points from the start of the run.
+ *
+ * This is CSS `text-decoration-skip-ink`, and it needs the real glyph outlines - so it only works
+ * for an embedded font. Segments narrower than the padding are dropped: a sliver of a line between
+ * two descenders reads as dirt, not as an underline.
+ */
+export declare function skipInkSegments(runWidth: number, inkSpans: Array<[number, number]>, thickness: number): Array<[number, number]>;

package/dist/text/text-decoration.js

@@ -0,0 +1,62 @@
+/**
+ * Where an underline and a strikethrough sit, and how thick they are.
+ *
+ * These are GLYPH metrics, and they are deliberately NOT part of `FontVerticals` in
+ * `line-metrics.ts`, which holds LINE metrics. Confusing the two is exactly what produced ISSUE-5:
+ * the AFM's `Ascender` (the height of a `b`) was used to seat a baseline, a job that belongs to the
+ * `FontBBox`. Keep the two kinds of number in two places so they cannot be mixed up again.
+ *
+ * Every number here comes out of the font: the standard-14 AFM header, or a TrueType `post` +
+ * `OS/2` table. Nothing is invented. Verified against `google-chrome --headless --print-to-pdf` on
+ * the same font: Chrome's strikethrough centre lands on `xHeight / 2` (measured 0.260 em vs the
+ * font's 0.262), and its underline stroke with `text-decoration-thickness: from-font` is the font's
+ * `underlineThickness` (0.048 em vs 0.050). Chrome does NOT use the font's underline POSITION - it
+ * has its own offset - so we follow the font there and land within 0.02 em of it.
+ */
+/** The underline for a run whose baseline sits at `baselineY` (engine coords, y grows down). */
+export function underlineStroke(decoration, fontSize, baselineY) {
+    return {
+        y: baselineY + decoration.underlinePosition * fontSize,
+        thickness: decoration.underlineThickness * fontSize,
+    };
+}
+/**
+ * The strikethrough for a run whose baseline sits at `baselineY`. It crosses at half the x-height,
+ * which is what a browser does and what looks right: through the middle of the lowercase letters,
+ * not through the middle of the capitals.
+ */
+export function strikethroughStroke(decoration, fontSize, baselineY) {
+    return {
+        y: baselineY - (decoration.xHeight / 2) * fontSize,
+        thickness: decoration.underlineThickness * fontSize,
+    };
+}
+/**
+ * Horizontal breathing room left on each side of a descender that interrupts an underline. Unlike
+ * everything else in this file this is a DESIGN choice, not a number read from the font - so it is
+ * expressed in the one quantity the font does give us, the stroke thickness.
+ */
+const SKIP_INK_PADDING = 1.0;
+/**
+ * Cuts `[0, runWidth]` at every place the glyphs put ink, leaving the segments an underline should
+ * actually draw. `inkSpans` are x-intervals in points from the start of the run.
+ *
+ * This is CSS `text-decoration-skip-ink`, and it needs the real glyph outlines - so it only works
+ * for an embedded font. Segments narrower than the padding are dropped: a sliver of a line between
+ * two descenders reads as dirt, not as an underline.
+ */
+export function skipInkSegments(runWidth, inkSpans, thickness) {
+    const pad = SKIP_INK_PADDING * thickness;
+    const segments = [];
+    let cursor = 0;
+    for (const [start, end] of inkSpans) {
+        const gapStart = Math.max(0, start - pad);
+        const gapEnd = Math.min(runWidth, end + pad);
+        if (gapStart > cursor + pad)
+            segments.push([cursor, gapStart]);
+        cursor = Math.max(cursor, gapEnd);
+    }
+    if (runWidth > cursor + pad)
+        segments.push([cursor, runWidth]);
+    return segments;
+}

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

@@ -13,12 +13,22 @@ export interface ResolvedTextStyle {
     fontStyle: FontStyle;
     color: Color;
     textAlignment: HorizontalAlignment;
-    lineHeight: number;
+    /** Multiplier of the font size. `undefined` means the font's natural line height
+     *  (`ascent + descent + lineGap`), i.e. CSS `line-height: normal`. */
+    lineHeight?: number;
+    /** Draw a line under the text, at the position and thickness the font declares. */
+    underline: boolean;
+    /** Draw a line through the text, at half its x-height. */
+    strikethrough: boolean;
+    /** Let the underline step around descenders (CSS `text-decoration-skip-ink`). Needs an EMBEDDED
+     *  font: the standard-14 outlines live in the viewer, not in the AFM. */
+    skipInk: boolean;
+    /** Extra space after every glyph, in points (CSS `letter-spacing`). Default 0. */
+    letterSpacing: number;
 }
 /**
  * The root of the cascade: what a `Text` falls back to when neither it nor any ancestor sets a
- * property. These MUST match the historical `Text` defaults so a document that sets nothing renders
- * byte-for-byte as before.
+ * property.
  */
 export declare const DEFAULT_TEXT_STYLE: ResolvedTextStyle;
 /** Layers a partial override onto a complete style; an unset (undefined) field keeps the base. */

package/dist/text/text-style.js

@@ -3,8 +3,7 @@ import { FontStyle } from "../utils/pdf-object-manager.js";
 import { HorizontalAlignment } from "../elements/pdf-element.js";
 /**
  * The root of the cascade: what a `Text` falls back to when neither it nor any ancestor sets a
- * property. These MUST match the historical `Text` defaults so a document that sets nothing renders
- * byte-for-byte as before.
+ * property.
  */
 export const DEFAULT_TEXT_STYLE = {
     fontSize: 12,
@@ -12,7 +11,11 @@ export const DEFAULT_TEXT_STYLE = {
     fontStyle: FontStyle.Normal,
     color: new Color(0, 0, 0),
     textAlignment: HorizontalAlignment.left,
-    lineHeight: 1,
+    lineHeight: undefined,
+    underline: false,
+    strikethrough: false,
+    skipInk: false,
+    letterSpacing: 0,
 };
 /** Layers a partial override onto a complete style; an unset (undefined) field keeps the base. */
 export function mergeTextStyle(base, override) {
@@ -25,5 +28,9 @@ export function mergeTextStyle(base, override) {
         color: override.color ?? base.color,
         textAlignment: override.textAlignment ?? base.textAlignment,
         lineHeight: override.lineHeight ?? base.lineHeight,
+        underline: override.underline ?? base.underline,
+        strikethrough: override.strikethrough ?? base.strikethrough,
+        skipInk: override.skipInk ?? base.skipInk,
+        letterSpacing: override.letterSpacing ?? base.letterSpacing,
     };
 }

package/dist/utils/afm-parser.d.ts

@@ -1,12 +1,46 @@
+import type { FontVerticals } from "../text/line-metrics.js";
+import type { FontDecoration } from "../text/text-decoration.js";
 export declare class AFMParser {
     private advanceWidths;
     private kerningPairs;
     private glyphMap;
+    private bbox;
+    private cachedVerticals?;
+    private underlinePosition;
+    private underlineThickness;
+    private capHeight;
+    private xHeight;
+    private cachedDecoration?;
     constructor(afmData: string);
     private loadGlyphList;
     private getGlyphName;
     private parseAFMData;
     private parseCharMetrics;
+    /**
+     * The font's LINE metrics, as fractions of the em: how far a line box must reach above and below
+     * the baseline. Taken from the `FontBBox`.
+     *
+     * Not from the AFM's `Ascender` / `Descender` lines, and that distinction is the whole point.
+     * `Ascender 718` is a GLYPH metric - the height of `b`, `d`, `h` - and for Helvetica it happens to
+     * equal the cap height. The line-metric equivalent is TrueType's `hhea.ascent`, which is much
+     * taller because it has to clear the accented capitals: Arial declares 0.905 where its caps reach
+     * 0.716. That surplus above the caps (0.189) is about as large as the descent below the baseline
+     * (0.212), which is exactly why capitals look vertically centred in a browser.
+     *
+     * Helvetica's `FontBBox` is `-166 -225 1000 931`: 0.931 up, 0.225 down - within a hair of Arial's
+     * hhea numbers. So the bbox IS the standard-14 line metric, and there is no leftover slack to
+     * call a lineGap. (Seating the baseline at `Ascender` instead put every capital too high; see
+     * ISSUE-5.)
+     */
+    verticals(): FontVerticals;
+    /**
+     * The font's decoration metrics (underline / strikethrough), as fractions of the em.
+     *
+     * Symbol and ZapfDingbats declare no `CapHeight`/`XHeight` - they have no lowercase letters. For
+     * those the bbox top is the only height the font gives us, so the capitals reach it and a
+     * strikethrough crosses at half of that. Still read from the font, not guessed.
+     */
+    decoration(): FontDecoration;
     getAdvanceWidth(charName: string): number;
     getKerning(firstChar: string, secondChar: string): number;
 }

package/dist/utils/afm-parser.js

@@ -4,6 +4,15 @@ export class AFMParser {
         this.advanceWidths = {};
         this.kerningPairs = {};
         this.glyphMap = {};
+        // The font's bounding box in glyph space (1000 units / em), from the AFM header. This - not the
+        // `Ascender` line - is what a line box is built from; see `verticals()`.
+        this.bbox = [0, 0, 0, 0];
+        // Glyph metrics from the AFM header, for underline / strikethrough. All 14 standard fonts carry
+        // the underline pair; Symbol and ZapfDingbats have no CapHeight/XHeight (they have no lowercase).
+        this.underlinePosition = 0; // negative, as the AFM writes it: below the baseline
+        this.underlineThickness = 0;
+        this.capHeight = 0;
+        this.xHeight = 0;
         this.parseAFMData(afmData);
         this.loadGlyphList();
     }
@@ -45,6 +54,22 @@ export class AFMParser {
                     this.advanceWidths[charName] = wx;
                 }
             }
+            if (line.startsWith("UnderlinePosition ")) {
+                this.underlinePosition = parseFloat(line.slice(18));
+            }
+            if (line.startsWith("UnderlineThickness ")) {
+                this.underlineThickness = parseFloat(line.slice(19));
+            }
+            if (line.startsWith("CapHeight ")) {
+                this.capHeight = parseFloat(line.slice(10));
+            }
+            if (line.startsWith("XHeight ")) {
+                this.xHeight = parseFloat(line.slice(8));
+            }
+            if (line.startsWith("FontBBox ")) {
+                const [x0, y0, x1, y1] = line.slice(9).trim().split(/\s+/).map(parseFloat);
+                this.bbox = [x0, y0, x1, y1];
+            }
             if (line.startsWith("KPX")) {
                 const parts = line.split(/\s+/);
                 const firstChar = parts[1];
@@ -74,6 +99,48 @@ export class AFMParser {
         }
         return null;
     }
+    /**
+     * The font's LINE metrics, as fractions of the em: how far a line box must reach above and below
+     * the baseline. Taken from the `FontBBox`.
+     *
+     * Not from the AFM's `Ascender` / `Descender` lines, and that distinction is the whole point.
+     * `Ascender 718` is a GLYPH metric - the height of `b`, `d`, `h` - and for Helvetica it happens to
+     * equal the cap height. The line-metric equivalent is TrueType's `hhea.ascent`, which is much
+     * taller because it has to clear the accented capitals: Arial declares 0.905 where its caps reach
+     * 0.716. That surplus above the caps (0.189) is about as large as the descent below the baseline
+     * (0.212), which is exactly why capitals look vertically centred in a browser.
+     *
+     * Helvetica's `FontBBox` is `-166 -225 1000 931`: 0.931 up, 0.225 down - within a hair of Arial's
+     * hhea numbers. So the bbox IS the standard-14 line metric, and there is no leftover slack to
+     * call a lineGap. (Seating the baseline at `Ascender` instead put every capital too high; see
+     * ISSUE-5.)
+     */
+    verticals() {
+        if (this.cachedVerticals)
+            return this.cachedVerticals;
+        const [, yMin, , yMax] = this.bbox;
+        this.cachedVerticals = { ascent: yMax / 1000, descent: -yMin / 1000, lineGap: 0 };
+        return this.cachedVerticals;
+    }
+    /**
+     * The font's decoration metrics (underline / strikethrough), as fractions of the em.
+     *
+     * Symbol and ZapfDingbats declare no `CapHeight`/`XHeight` - they have no lowercase letters. For
+     * those the bbox top is the only height the font gives us, so the capitals reach it and a
+     * strikethrough crosses at half of that. Still read from the font, not guessed.
+     */
+    decoration() {
+        if (this.cachedDecoration)
+            return this.cachedDecoration;
+        const capHeight = this.capHeight || this.bbox[3];
+        this.cachedDecoration = {
+            underlinePosition: -this.underlinePosition / 1000, // AFM writes it negative (below the baseline)
+            underlineThickness: this.underlineThickness / 1000,
+            capHeight: capHeight / 1000,
+            xHeight: (this.xHeight || capHeight / 2) / 1000,
+        };
+        return this.cachedDecoration;
+    }
     getAdvanceWidth(charName) {
         return this.advanceWidths[this.getGlyphName(charName)] || 0;
     }

package/dist/utils/dest-registry.d.ts

@@ -1,3 +1,4 @@
+import type { PDFObjectManager } from "./pdf-object-manager.js";
 interface Dest {
     pageObjNum: number;
     top: number;
@@ -13,7 +14,9 @@ export declare class DestRegistry {
     add(name: string, dest: Dest): void;
     get isEmpty(): boolean;
     /** The `/Dests << /Names [ ... ] >>` fragment for the catalog `/Names` dictionary (merged with any
-     *  `/EmbeddedFiles`). Returns "" when empty. Names are sorted lexically - a name tree requires it. */
-    finalize(): string;
+     *  `/EmbeddedFiles`). Returns "" when empty. Names are sorted lexically - a name tree requires it.
+     *  Takes the object manager only so the names go through its string choke-point and get encrypted
+     *  with everything else. */
+    finalize(om: PDFObjectManager): string;
 }
 export {};