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

package/dist/renderer/page-break-renderer.d.ts

@@ -0,0 +1,14 @@
+import { PDFObjectManager } from "../utils/pdf-object-manager.js";
+import { PageBreakElement } from "../elements/layout/page-break-element.js";
+import { IRNode } from "../ir/display-list.js";
+/**
+ * A `PageBreak` draws nothing - the pagination packer consumes it at the cut, so in a vertical flow it
+ * never reaches this pass. Reaching it therefore means the break was ineffective: it sat somewhere that
+ * does not paginate, like inside a horizontal `Row` (a row is one line, you cannot split it across
+ * pages - CSS and react-pdf ignore a forced break there too). We degrade to drawing nothing, but warn
+ * once so the mistake is not silent. This one choke-point catches every ineffective break; no element
+ * needs a special case.
+ */
+export declare class PageBreakRenderer {
+    static render(_element: PageBreakElement, _objectManager: PDFObjectManager): Promise<IRNode[]>;
+}

package/dist/renderer/page-break-renderer.js

@@ -0,0 +1,15 @@
+/**
+ * A `PageBreak` draws nothing - the pagination packer consumes it at the cut, so in a vertical flow it
+ * never reaches this pass. Reaching it therefore means the break was ineffective: it sat somewhere that
+ * does not paginate, like inside a horizontal `Row` (a row is one line, you cannot split it across
+ * pages - CSS and react-pdf ignore a forced break there too). We degrade to drawing nothing, but warn
+ * once so the mistake is not silent. This one choke-point catches every ineffective break; no element
+ * needs a special case.
+ */
+export class PageBreakRenderer {
+    static async render(_element, _objectManager) {
+        console.warn("PageBreak had no effect: it is not in a paginating flow (e.g. it is inside a Row, which is a " +
+            "single horizontal line). Put the break as a sibling in a Column to break after that content.");
+        return [];
+    }
+}

package/dist/renderer/page-renderer.js

@@ -74,14 +74,20 @@ export class PageRenderer {
         const num = (n) => Number(n.toFixed(2));
         const annotRefs = [];
         for (const node of flipped) {
+            // A form field: build its Widget annotation + register it as an /AcroForm field (the logic lives in
+            // forms/acroform.ts), then reference it here in the page /Annots - the same side channel as a link.
+            if (node.type === "formfield") {
+                annotRefs.push(`${objectManager.acroform.addField(node, objectManager)} 0 R`);
+                continue;
+            }
             if (node.type !== "link")
                 continue;
             const rect = `[${num(node.x)} ${num(node.y)} ${num(node.x + node.width)} ${num(node.y + node.height)}]`;
             // Either an external URL (/URI) or an internal named destination (/GoTo, resolved via /Names /Dests).
             // The Link IR guarantees exactly one is set; prefer `dest` when present.
             const action = node.dest !== undefined
-                ? `/A << /S /GoTo /D (${PdfBackend.escapePdfString(node.dest)}) >>`
-                : `/A << /S /URI /URI (${PdfBackend.escapePdfString(node.href ?? "")}) >>`;
+                ? `/A << /S /GoTo /D ${objectManager.pdfString(node.dest)} >>`
+                : `/A << /S /URI /URI ${objectManager.pdfString(node.href ?? "")} >>`;
             const annot = objectManager.addObject(`<< /Type /Annot /Subtype /Link /Rect ${rect} /Border [0 0 0] ${action} >>`);
             annotRefs.push(`${annot} 0 R`);
         }

package/dist/renderer/pdf-backend.d.ts

@@ -39,6 +39,13 @@ export declare class PdfBackend {
      * text closes the string early and the remaining characters leak as raw operators.
      */
     static escapePdfString(text: string): string;
+    /**
+     * Builds the `[ ... ]` operand of a `TJ` from a run and its per-gap kern adjustments (em/1000, the
+     * sign the font declares - negative tightens). A `TJ` number moves the pen LEFT, so it is the
+     * NEGATED kern. Consecutive un-kerned glyphs stay in one encoded chunk, so `[(T) 40 (otal)]` rather
+     * than one chunk per glyph. `kerns[i]` is the adjustment AFTER code point `i`.
+     */
+    static kernedArray(text: string, kerns: number[], encode: (chunk: string) => string): string;
     /**
      * Returns the `/GSx gs` operator that selects a transparency state, or `""` when both
      * alphas are fully opaque. Opaque draws emit nothing here, so output stays

package/dist/renderer/pdf-backend.js

@@ -65,6 +65,9 @@ export class PdfBackend {
                 case "link":
                     // A link's clickable rect flips around its bottom edge, exactly like a rect.
                     return { ...node, y: pageHeight - node.y - node.height };
+                case "formfield":
+                    // A form field's box flips around its bottom edge, exactly like a link rect.
+                    return { ...node, y: pageHeight - node.y - node.height };
                 case "outline":
                     // An outline anchor is a single point (the target's top); flip it like a text baseline.
                     return { ...node, y: pageHeight - node.y };
@@ -137,6 +140,7 @@ export class PdfBackend {
                 node.type === "link" ||
                 node.type === "outline" ||
                 node.type === "anchor" ||
+                node.type === "formfield" ||
                 ops === "")
                 return ops;
             const { open, close } = struct.mark(node.tag);
@@ -152,6 +156,27 @@ export class PdfBackend {
     static escapePdfString(text) {
         return text.replace(/\\/g, "\\\\").replace(/\(/g, "\\(").replace(/\)/g, "\\)");
     }
+    /**
+     * Builds the `[ ... ]` operand of a `TJ` from a run and its per-gap kern adjustments (em/1000, the
+     * sign the font declares - negative tightens). A `TJ` number moves the pen LEFT, so it is the
+     * NEGATED kern. Consecutive un-kerned glyphs stay in one encoded chunk, so `[(T) 40 (otal)]` rather
+     * than one chunk per glyph. `kerns[i]` is the adjustment AFTER code point `i`.
+     */
+    static kernedArray(text, kerns, encode) {
+        const chars = [...text];
+        let out = "";
+        let chunk = chars[0] ?? "";
+        for (let i = 0; i < kerns.length; i++) {
+            if (kerns[i] === 0) {
+                chunk += chars[i + 1];
+            }
+            else {
+                out += encode(chunk) + ` ${-kerns[i]} `;
+                chunk = chars[i + 1];
+            }
+        }
+        return `[${out}${encode(chunk)}]`;
+    }
     /**
      * Returns the `/GSx gs` operator that selects a transparency state, or `""` when both
      * alphas are fully opaque. Opaque draws emit nothing here, so output stays
@@ -242,18 +267,31 @@ export class PdfBackend {
                 const font = isCustom
                     ? om.getCustomFontResource(node.fontFamily, node.fontStyle)
                     : om.registerFont(node.fontFamily, node.fontStyle);
-                const textOp = isCustom
-                    ? `<${om.encodeCustomText(node.fontFamily, node.text, node.fontStyle)}>`
-                    : `(${PdfBackend.escapePdfString(node.text)})`;
+                const encode = (t) => isCustom
+                    ? `<${om.encodeCustomText(node.fontFamily, t, node.fontStyle)}>`
+                    : `(${PdfBackend.escapePdfString(t)})`;
+                // Kerning (if the document has it on): a `TJ` array with the font's per-pair adjustments
+                // between glyph chunks, measured into the layout by the SAME numbers (runAdvance). A plain
+                // `Tj` when the run has no kerning, byte-identical.
+                const kerns = om.kerningEnabled
+                    ? om.getKernPairs(node.text, node.fontFamily, node.fontStyle)
+                    : [];
+                const showOp = kerns.some((k) => k !== 0)
+                    ? `${PdfBackend.kernedArray(node.text, kerns, encode)} TJ`
+                    : `${encode(node.text)} Tj`;
+                // letterSpacing is the `Tc` operator: extra advance after EVERY glyph (an embedded
+                // Identity-H font too - that is `Tw`, word spacing, which only touches single-byte code 32).
+                const spacing = node.letterSpacing ? `${node.letterSpacing.toFixed(3)} Tc\n` : "";
                 const block = `BT\n` +
                     `${node.color.toPDFColorString()} rg ` +
                     `/F${font.fontIndex} ${node.fontSize} Tf ` +
                     `${node.x.toFixed(3)} ${node.y.toFixed(3)} Td ` +
-                    `${textOp} Tj\n` +
+                    `${showOp}\n` +
                     `ET\n`;
-                // Transparent text gets an isolating q/Q + gs; opaque text is byte-identical.
                 const gs = PdfBackend.alphaPrefix(om, node.color.getAlpha(), 1);
-                return gs ? `q\n${gs}${block}Q\n` : block;
+                // `Tc` is graphics state and would leak into the next run, so isolate it in q/Q - the same
+                // reason transparent text is isolated. A run with neither stays byte-identical.
+                return gs || spacing ? `q\n${gs}${spacing}${block}Q\n` : block;
             }
             case "image": {
                 // The backend owns PDF resource creation: register the XObject (using the
@@ -323,6 +361,10 @@ export class PdfBackend {
             case "anchor":
                 // A named destination draws nothing - it becomes a /Names /Dests entry (built in PageRenderer/PDFRenderer).
                 return "";
+            case "formfield":
+                // A form field draws nothing in the content stream - it becomes a Widget /Annot + /AcroForm field
+                // (built in PageRenderer via forms/acroform.ts).
+                return "";
             default: {
                 // Exhaustiveness guard: if a new IRNode variant is added, this fails to compile.
                 const unknown = node;

package/dist/renderer/pdf-document-class.js

@@ -88,6 +88,9 @@ export class PDFDocument {
         }
         if (config)
             this._objectManager.changePDFConfig(config);
+        // Kerning is on by default at the document level (the `renderToBytes` path sets the same). A
+        // bare `PDFObjectManager` still defaults OFF, so unit tests keep predictable un-kerned metrics.
+        this._objectManager.setKerning(true);
     }
     get objectManager() {
         return this._objectManager;

package/dist/renderer/pdf-document-renderer.js

@@ -1,6 +1,6 @@
-import { layoutPageBands, PageElement, resolvePageSize, } from "../elements/page-element.js";
+import { layoutPageBands, pageFrame, PageElement, resolvePageSize, } from "../elements/page-element.js";
 import { BoxConstraints } from "../layout/box-constraints.js";
-import { isFragmentable } from "../layout/fragmentation.js";
+import { isFragmentable, reportOverflow } from "../layout/fragmentation.js";
 import { PageRenderer } from "./page-renderer.js";
 export class PDFDocumentRenderer {
     static async render(document, objectManager, ctx) {
@@ -66,13 +66,19 @@ export class PDFDocumentRenderer {
         }
         // Header/footer repeat on every physical page, so the body only ever flows into the
         // band between them. Resolve that band once (config is already merged by pass 1).
+        // The frame is a throwaway: this pass only wants the band HEIGHTS, and an out-of-flow child
+        // contributes none. It exists because a `Positioned` in a band demands one; pass 2 builds the
+        // real frame (in `PageElement`) and drains it.
         const pageCtx = {
             metrics: ctx.metrics,
             pageConfig: config,
             textStyle: ctx.textStyle,
             onOverflow: ctx.onOverflow,
+            frame: pageFrame(config),
         };
         const { bodyWidth: width, bodyHeight: height } = layoutPageBands(config, header, footer, pageCtx);
+        // A `keepTogether` group compares its height against a FULL fresh page (this band), so thread it in.
+        pageCtx.pageBodyHeight = height;
         const pages = [];
         let region = children[0];
         let isFirstRegion = true;
@@ -84,17 +90,30 @@ export class PDFDocumentRenderer {
             }
             // pageCtx, not the document ctx: a descendant that reads `pageConfig` while being measured (a
             // `PageBuilder` sizing its provisional build) must see THIS page's geometry, not the document default.
-            const { fitted, remainder } = region.fragment(height, width, pageCtx);
+            const { fitted, remainder, forceBreak } = region.fragment(height, width, pageCtx);
             // Everything fits on one page: keep the ORIGINAL page so output is unchanged. Measuring inside
             // fragment() left its children at the measuring origin; pass B lays the page out again, which
-            // restores their real positions (layout is deterministic).
-            if (isFirstRegion && remainder === null) {
+            // restores their real positions (layout is deterministic). A consumed trailing `PageBreak`
+            // (forceBreak with no remainder) is the exception: render the packed `fitted` instead, which no
+            // longer holds the break marker, so the original with the break does not leak into the render pass.
+            if (isFirstRegion && remainder === null && !forceBreak) {
                 pages.push({ kind: "whole", page });
                 break;
             }
-            if (fitted) {
-                pages.push({ kind: "fragment", config, content: fitted, header, footer });
+            // TERMINATION GUARANTEE. Every page here has the full body height, so `fitted === null` means
+            // nothing fit even on a whole page - the region did not get smaller. Advancing to the
+            // (identical) remainder would loop forever. So we stop: place the region whole (clipped to the
+            // page) and surface it per the overflow policy. A step that shrinks nothing ends the loop, for
+            // ANY region - an oversized unbreakable block, a future keep-together group, or an engine bug.
+            if (fitted === null) {
+                // Measure the region's true height for the message (rare path, so the extra pass is free);
+                // pass B lays it out again, so this mutation does not leak.
+                const needed = region.calculateLayout(BoxConstraints.loose(width, Infinity), { x: 0, y: 0 }, pageCtx).height;
+                reportOverflow(region, needed, height, pageCtx.onOverflow ?? "ignore");
+                pages.push({ kind: "fragment", config, content: region, header, footer });
+                break;
             }
+            pages.push({ kind: "fragment", config, content: fitted, header, footer });
             region = remainder;
             isFirstRegion = false;
         }

package/dist/renderer/pdf-renderer.js

@@ -26,7 +26,18 @@ import { LinkRenderer } from "./link-renderer.js";
 import { BookmarkElement } from "../elements/layout/bookmark-element.js";
 import { BookmarkRenderer } from "./bookmark-renderer.js";
 import { AnchorElement } from "../elements/layout/anchor-element.js";
+import { PageBreakElement } from "../elements/layout/page-break-element.js";
 import { AnchorRenderer } from "./anchor-renderer.js";
+import { PageBreakRenderer } from "./page-break-renderer.js";
+import { KeepTogetherElement } from "../elements/layout/keep-together-element.js";
+import { KeepTogetherRenderer } from "./keep-together-renderer.js";
+import { TextFieldElement } from "../elements/forms/text-field-element.js";
+import { CheckboxElement } from "../elements/forms/checkbox-element.js";
+import { RadioElement } from "../elements/forms/radio-element.js";
+import { ChoiceElement } from "../elements/forms/choice-element.js";
+import { PushButtonElement } from "../elements/forms/push-button-element.js";
+import { SignatureFieldElement } from "../elements/forms/signature-element.js";
+import { FormFieldRenderer } from "./form-field-renderer.js";
 import { PageBuilderElement } from "../elements/layout/page-builder-element.js";
 import { PageBuilderRenderer } from "./page-builder-renderer.js";
 import { RotatedElement } from "../elements/layout/rotated-element.js";
@@ -45,6 +56,14 @@ export class PDFRenderer {
         RendererRegistry.register(RectangleElement, RectangleRenderer.render);
         RendererRegistry.register(ExpandedElement, ExpandedRenderer.render);
         RendererRegistry.register(PaddingElement, PaddingRenderer.render);
+        RendererRegistry.register(PageBreakElement, PageBreakRenderer.render);
+        RendererRegistry.register(KeepTogetherElement, KeepTogetherRenderer.render);
+        RendererRegistry.register(TextFieldElement, FormFieldRenderer.render);
+        RendererRegistry.register(CheckboxElement, FormFieldRenderer.render);
+        RendererRegistry.register(RadioElement, FormFieldRenderer.render);
+        RendererRegistry.register(ChoiceElement, FormFieldRenderer.render);
+        RendererRegistry.register(PushButtonElement, FormFieldRenderer.render);
+        RendererRegistry.register(SignatureFieldElement, FormFieldRenderer.render);
         RendererRegistry.register(DefaultTextStyleElement, DefaultTextStyleRenderer.render);
         RendererRegistry.register(ImageElement, ImageRenderer.render);
         RendererRegistry.register(LineElement, LineRenderer.render);
@@ -118,8 +137,13 @@ export class PDFRenderer {
         const outlineCatalog = objectManager.outline.finalize(objectManager);
         if (outlineCatalog)
             catalogParts.push(outlineCatalog);
+        // Interactive form fields: emit the catalog /AcroForm dict collected as pages rendered. Returns ""
+        // (no-op) when no field was placed, so a plain document's catalog is unchanged.
+        const acroformCatalog = objectManager.acroform.finalize(objectManager);
+        if (acroformCatalog)
+            catalogParts.push(acroformCatalog);
         // Named destinations (internal-link targets): a /Dests entry in the shared /Names dict.
-        const destsNames = objectManager.dests.finalize();
+        const destsNames = objectManager.dests.finalize(objectManager);
         if (destsNames)
             namesParts.push(destsNames);
         // Emit the single /Names dict if either embedded files or destinations contributed to it.

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

@@ -4,7 +4,7 @@ import type { FontMetrics } from "../utils/font-metrics.js";
 import { IRNode } from "../ir/display-list.js";
 import { TextOverflow } from "../text/line-breaker.js";
 export declare class TextRenderer {
-    static calculateTextHeight(content: string | TextSegment[], fontSize: number, fontFamily: string, fontStyle: FontStyle, objectManager: FontMetrics, maxWidth: number, maxLines?: number, overflow?: TextOverflow, lineHeight?: number): number;
+    static calculateTextHeight(content: string | TextSegment[], fontSize: number, fontFamily: string, fontStyle: FontStyle, objectManager: FontMetrics, maxWidth: number, maxLines?: number, overflow?: TextOverflow, lineHeight?: number, letterSpacing?: number): number;
     static render(textElement: TextElement, objectManager: PDFObjectManager): Promise<IRNode[]>;
     private static _expandColorGlyphs;
     private static _glyphToPath;

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;