@jasy/pdf 1.0.0-alpha.1 → 1.0.0-alpha.10

package/dist/renderer/text-renderer.js

@@ -1,125 +1,473 @@
-"use strict";
-var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
-    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
-    return new (P || (P = Promise))(function (resolve, reject) {
-        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
-        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
-        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
-        step((generator = generator.apply(thisArg, _arguments || [])).next());
-    });
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.TextRenderer = void 0;
-const pdf_element_1 = require("../elements/pdf-element");
-const line_breaker_1 = require("../text/line-breaker");
-// 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;
-class TextRenderer {
+import { Color } from "../common/color.js";
+import { HorizontalAlignment } from "../elements/pdf-element.js";
+import { VERTICAL_TEXT_SHIFT } from "../elements/text-element.js";
+import { isEmojiCodePoint } from "../text/emoji-codepoints.js";
+import { emojiImageNode } from "./emoji-image.js";
+import { singleLineWidth, MAX_SPACE_SHRINK, wrapStringIntoLines, breakSegmentsIntoLines, } from "../text/line-breaker.js";
+import { lineBoxForSegmentLine, lineBoxForString } from "../text/line-metrics.js";
+import { runAdvance } from "../text/advance.js";
+import { visualRuns, visualRunsOf } from "../text/bidi.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) {
-        // Plain string: one line height per wrapped line.
+    static calculateTextHeight(content, fontSize, fontFamily, fontStyle, objectManager, maxWidth, maxLines, overflow, lineHeight, letterSpacing = 0, lineOptions = {}) {
+        // Plain string: every wrapped line gets the same box.
         if (typeof content === "string") {
-            const lines = (0, line_breaker_1.wrapStringIntoLines)(content, fontFamily, fontSize, fontStyle, maxWidth, objectManager);
-            return lines.length * fontSize;
+            const lines = wrapStringIntoLines(content, fontFamily, fontSize, fontStyle, maxWidth, objectManager, maxLines, overflow, letterSpacing, lineOptions);
+            const box = lineBoxForString(objectManager, fontFamily, fontStyle, fontSize, lineHeight);
+            return lines.length * box.height;
         }
-        // Segments: each line contributes its own (tallest-on-line) leading.
-        const lines = (0, line_breaker_1.breakSegmentsIntoLines)(content, { fontFamily, fontSize, fontStyle }, maxWidth, objectManager);
-        return lines.reduce((total, line) => total + line.maxFontSize, 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 render(textElement, objectManager) {
-        return __awaiter(this, void 0, void 0, function* () {
-            const { x, y, width, fontSize, color, content, fontFamily, fontStyle, textAlignment } = 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.
-            return TextRenderer._buildRuns(content, fontSize, fontFamily, fontStyle, objectManager, width !== null && width !== void 0 ? width : Number.NaN, textAlignment, color, x, y);
-        });
+    static async render(textElement, objectManager) {
+        const { x, y, width, fontSize, color, content, fontFamily, fontStyle, textAlignment, maxLines, overflow, lineHeight, underline, strikethrough, skipInk, letterSpacing, direction, wordSpacing, textIndent, 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, decorations } = TextRenderer._buildRuns(content, fontSize, fontFamily, fontStyle, objectManager, width ?? Number.NaN, textAlignment, color, x, y, maxLines, overflow, lineHeight, underline, strikethrough, skipInk, letterSpacing, direction, wordSpacing, textIndent);
+        // 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.
+        if (objectManager.struct.enabled) {
+            const pdfRole = role ? role.toUpperCase() : "P"; // "h1" -> "H1"; default paragraph
+            const key = objectManager.struct.openElement(textElement.structId, pdfRole);
+            for (const run of runs)
+                run.tag = { role: pdfRole, key };
+        }
+        // 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 [...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]`
+    // untouched when the font has no color glyphs (the common case).
+    static async _expandColorGlyphs(run, om) {
+        // The run's own font (if it's a color font) draws emoji directly; otherwise a document-level
+        // emoji source (`Document({ emoji })`) supplies them - a fallback FONT (color glyphs, native
+        // vector) or an IMAGE source (fetched emoji images) - for code points the run's font lacks, so
+        // `Text("Hallo 😅")` works in one string. No emoji source at all -> pass the run through.
+        const own = om.getColorFont(run.fontFamily, run.fontStyle);
+        const emojiName = om.getEmojiFont();
+        const fallback = emojiName && emojiName !== run.fontFamily
+            ? om.getColorFont(emojiName, run.fontStyle)
+            : undefined;
+        const imageSource = om.getEmojiImageSource();
+        if (!own && !fallback && !imageSource)
+            return [run];
+        // A SHAPED run cannot be split here: the sub-runs are cut by code point, while `glyphs` is a
+        // drawn-order list in which a ligature is one glyph for several code points - so no sub-run could
+        // be given the right slice, and inheriting the whole list would draw every glyph again per piece.
+        // Passed through whole instead: an emoji inside Arabic then comes from the text font rather than
+        // the emoji source (`todo.md`).
+        if (run.glyphs)
+            return [run];
+        const nodes = [];
+        let cursorX = run.x; // absolute x of the next glyph
+        let pending = ""; // run of consecutive non-color characters
+        let pendingX = run.x; // where that run started
+        const flushPending = () => {
+            if (pending) {
+                nodes.push({ ...run, x: pendingX, text: pending });
+                pending = "";
+            }
+        };
+        for (const ch of run.text) {
+            const cp = ch.codePointAt(0);
+            // Which color font renders this code point: the run's own font first, then the emoji fallback.
+            let source;
+            let layers = null;
+            if (own) {
+                const l = own.getColorGlyph(own.getGlyphIndex(cp));
+                if (l)
+                    [source, layers] = [own, l];
+            }
+            if (!layers && fallback) {
+                const l = fallback.getColorGlyph(fallback.getGlyphIndex(cp));
+                if (l)
+                    [source, layers] = [fallback, l];
+            }
+            // 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;
+                for (const layer of layers) {
+                    const commands = TextRenderer._glyphToPath(source.getGlyphPath(layer.glyphId), cursorX, run.y, scale, layer.transform);
+                    if (commands.length === 0)
+                        continue; // an empty layer outline draws nothing
+                    const paint = layer.paint;
+                    let fill;
+                    if (paint.type === "solid") {
+                        const c = paint.color;
+                        fill = c ? new Color(c.r, c.g, c.b, c.a / 255) : run.color; // null -> foreground
+                    }
+                    else {
+                        fill = TextRenderer._toGradient(paint, cursorX, run.y, scale, run.color, layer.transform);
+                    }
+                    nodes.push({ type: "path", commands, fill });
+                }
+            }
+            else if (imageSource && isEmojiCodePoint(cp)) {
+                // Image emoji source: fetch + embed a 1em square. The emoji breaks the text run either way;
+                // a failed fetch (offline/404) leaves a blank em gap (advance already applied) rather than
+                // drawing a broken glyph.
+                flushPending();
+                const node = await emojiImageNode(cp, imageSource, cursorX, run.y, run.fontSize);
+                if (node)
+                    nodes.push(node);
+            }
+            else {
+                if (!pending)
+                    pendingX = cursorX;
+                pending += ch;
+            }
+            cursorX += advance;
+        }
+        flushPending();
+        return nodes;
+    }
+    // Maps a glyph outline (font units, y-up) to absolute IR path commands at the pen origin, scaling
+    // by `scale` and flipping the axis into the engine's top-left space (the seam flips it once more
+    // to PDF space). TrueType quadratics become cubics: C1 = P0 + 2/3(C-P0), C2 = P1 + 2/3(C-P1).
+    static _glyphToPath(cmds, originX, baselineY, scale, transform) {
+        // Apply the layer's affine (font units) first, then scale to points, position at the pen origin
+        // and flip into engine space. `mapX`/`mapY` take BOTH glyph coords because an affine mixes them.
+        const [a, b, c, d, e, f] = transform ?? [1, 0, 0, 1, 0, 0];
+        const mapX = (gx, gy) => originX + (a * gx + c * gy + e) * scale;
+        const mapY = (gx, gy) => baselineY - (b * gx + d * gy + f) * scale;
+        const out = [];
+        let curX = 0;
+        let curY = 0;
+        for (const cmd of cmds) {
+            if (cmd.type === "M") {
+                curX = mapX(cmd.x, cmd.y);
+                curY = mapY(cmd.x, cmd.y);
+                out.push({ op: "m", x: curX, y: curY });
+            }
+            else if (cmd.type === "L") {
+                curX = mapX(cmd.x, cmd.y);
+                curY = mapY(cmd.x, cmd.y);
+                out.push({ op: "l", x: curX, y: curY });
+            }
+            else if (cmd.type === "Q") {
+                const ctrlX = mapX(cmd.cx, cmd.cy);
+                const ctrlY = mapY(cmd.cx, cmd.cy);
+                const endX = mapX(cmd.x, cmd.y);
+                const endY = mapY(cmd.x, cmd.y);
+                out.push({
+                    op: "c",
+                    x1: curX + (2 / 3) * (ctrlX - curX),
+                    y1: curY + (2 / 3) * (ctrlY - curY),
+                    x2: endX + (2 / 3) * (ctrlX - endX),
+                    y2: endY + (2 / 3) * (ctrlY - endY),
+                    x: endX,
+                    y: endY,
+                });
+                curX = endX;
+                curY = endY;
+            }
+            else {
+                out.push({ op: "z" });
+            }
+        }
+        return out;
+    }
+    // Maps a COLR v1 gradient paint (font-unit coordinates) into an IR `Gradient` positioned at the
+    // pen origin, using the SAME scale + baseline flip as the glyph outline so the gradient axis lines
+    // up with the shape. Radii scale uniformly (the em scale is uniform). A null stop color (the COLR
+    // "use foreground" sentinel) becomes the text color.
+    static _toGradient(paint, originX, baselineY, scale, foreground, transform) {
+        const [a, b, c, d, e, f] = transform ?? [1, 0, 0, 1, 0, 0];
+        const mapX = (gx, gy) => originX + (a * gx + c * gy + e) * scale;
+        const mapY = (gx, gy) => baselineY - (b * gx + d * gy + f) * scale;
+        // A radius has no single value under a general affine (a circle can shear into an ellipse); use
+        // the affine's geometric-mean scale sqrt(|det|) times the em scale - exact for uniform scaling.
+        const radiusScale = scale * Math.sqrt(Math.abs(a * d - b * c));
+        const stops = paint.stops.map((s) => ({
+            offset: s.offset,
+            color: s.color ? new Color(s.color.r, s.color.g, s.color.b, s.color.a / 255) : foreground,
+        }));
+        if (paint.type === "linearGradient") {
+            return {
+                type: "linear",
+                x0: mapX(paint.p0[0], paint.p0[1]),
+                y0: mapY(paint.p0[0], paint.p0[1]),
+                x1: mapX(paint.p1[0], paint.p1[1]),
+                y1: mapY(paint.p1[0], paint.p1[1]),
+                stops,
+                extend: paint.extend,
+            };
+        }
+        return {
+            type: "radial",
+            x0: mapX(paint.c0[0], paint.c0[1]),
+            y0: mapY(paint.c0[0], paint.c0[1]),
+            r0: paint.c0[2] * radiusScale,
+            x1: mapX(paint.c1[0], paint.c1[1]),
+            y1: mapY(paint.c1[0], paint.c1[1]),
+            r1: paint.c1[2] * radiusScale,
+            stops,
+            extend: paint.extend,
+        };
     }
     // 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) {
+    static _buildRuns(content, fontSize, fontFamily, fontStyle, objectManager, maxWidth, textAlignment, color, initialX, yPosition, maxLines, overflow, lineHeight, underline = false, strikethrough = false, skipInk = false, letterSpacing = 0, direction = "ltr", wordSpacing = 0, textIndent = 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 === pdf_element_1.HorizontalAlignment.center)
-                return (maxWidth - lineWidth) / 2;
-            if (textAlignment === pdf_element_1.HorizontalAlignment.right)
-                return maxWidth - lineWidth;
+        // `start` is the one alignment that depends on the direction, resolved at the single place
+        // alignment is consumed.
+        const align = textAlignment === HorizontalAlignment.start
+            ? direction === "rtl"
+                ? HorizontalAlignment.right
+                : HorizontalAlignment.left
+            : textAlignment;
+        const alignmentOffset = (lineWidth, indent = 0) => {
+            const room = maxWidth - indent;
+            if (align === HorizontalAlignment.center)
+                return (room - lineWidth) / 2;
+            if (align === HorizontalAlignment.right)
+                return room - 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);
+        /**
+         * Justification: how much extra to put in EACH space of a line so it reaches the full width.
+         * The LAST line of a paragraph keeps its natural spacing, as it does in CSS and in print - a
+         * justified last line is the classic sign of a broken text engine.
+         *
+         * Spaces are stretched by moving the pen, not by the `Tw` operator: `Tw` applies only to the
+         * single byte 32, so an embedded (Identity-H) font would ignore it entirely.
+         */
+        const justifyExtra = (line, naturalWidth, isLast, indent = 0) => {
+            if (align !== HorizontalAlignment.justify)
+                return 0;
+            const gaps = [...line].filter((c) => c === " ").length;
+            if (gaps === 0)
+                return 0;
+            const slack = maxWidth - indent - naturalWidth;
+            // Negative slack is real now: the breaker keeps a word when the line can be SQUEEZED to hold
+            // it, so justification has to deliver that squeeze. The floor is the same limit the breaker
+            // used, which is what stops a line it never promised from being crushed.
+            const spaceWidth = runAdvance(objectManager, " ", { fontFamily, fontSize, fontStyle }, letterSpacing);
+            const extra = Math.max(slack / gaps, -spaceWidth * MAX_SPACE_SHRINK);
+            // The last line is never STRETCHED - the rule print and CSS follow. It may still be SQUEEZED:
+            // the breaker was allowed to pack it that way, and drawing it loose would push it out of its box.
+            return isLast ? Math.min(0, extra) : extra;
+        };
+        /**
+         * Push one drawn piece and return the advance it took. When the line is justified the pen jumps an
+         * extra `extra` at every space, which means one run per word - the only way that works for an
+         * embedded font, whose spaces `Tw` cannot reach.
+         *
+         * A SHAPED piece is never split: its glyph list is in drawn order with ligatures merged, so no
+         * slice of it is correct. Such a piece keeps its natural spacing.
+         */
+        const emitPiece = (piece, x, extra, style, runFont, spacing) => {
+            const push = (at, text, glyphs) => {
+                runs.push({ type: "text", x: at, text, ...(glyphs ? { glyphs } : {}), ...style });
+            };
+            if (extra === 0 || piece.glyphs || !piece.text.includes(" ")) {
+                push(x, piece.text, piece.glyphs);
+                return runAdvance(objectManager, piece.text, runFont, spacing);
+            }
+            const spaceWidth = runAdvance(objectManager, " ", runFont, spacing);
+            const words = piece.text.split(" ");
+            let pen = x;
+            words.forEach((word, i) => {
+                if (word !== "") {
+                    push(pen, word);
+                    pen += runAdvance(objectManager, word, runFont, spacing);
+                }
+                if (i < words.length - 1)
+                    pen += spaceWidth + extra;
+            });
+            return pen - x;
+        };
+        // 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);
+            }
+        };
+        // 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\`.`);
             }
-            return width;
+            // 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);
+        };
+        /**
+         * One drawn piece of a line. SHAPING must see the run's LOGICAL text - a letter's form comes from
+         * its neighbours, and a reversed run has those swapped - so we shape that and then reverse the
+         * GLYPHS for an rtl run. A font that does not shape keeps the old path exactly: draw the visual
+         * text, no glyph list, byte-identical output.
+         */
+        const shapedPiece = (part, family, style) => {
+            const shaped = objectManager.shapeText(part.logical, family, style);
+            if (!shaped)
+                return { text: part.text };
+            const ordered = part.rtl ? [...shaped].reverse() : shaped;
+            return { text: part.logical, glyphs: ordered.map((g) => g.glyph) };
         };
+        // 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 = (0, line_breaker_1.wrapStringIntoLines)(content, fontFamily, fontSize, fontStyle, maxWidth, objectManager);
-            // yPosition is the top of the text box (top-left); seat line 0's baseline below
-            // it, then step DOWN per line. The seam flips the whole thing to PDF space.
-            const baseline = yPosition + fontSize * BASELINE_RATIO;
+            const lines = wrapStringIntoLines(content, fontFamily, fontSize, fontStyle, maxWidth, objectManager, maxLines, overflow, letterSpacing, 
+            // The SAME knobs the measure pass used (`TextElement.lineOptions`), or a line would be
+            // measured one width and drawn another.
+            {
+                wordSpacing,
+                indent: textIndent,
+                shrink: align === HorizontalAlignment.justify ? MAX_SPACE_SHRINK : 0,
+            });
+            // 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);
-                runs.push({
-                    type: "text",
-                    x: initialX + alignmentOffset(lineWidth),
-                    y: baseline + fontSize * index,
-                    text: line,
-                    fontFamily,
-                    fontStyle,
-                    fontSize,
-                    color,
-                });
+                const lineWidth = singleLineWidth(line, font, objectManager, letterSpacing, wordSpacing);
+                // CSS `text-indent`: the FIRST line starts in, and had that much less room to fill.
+                const indent = index === 0 ? textIndent : 0;
+                let x = initialX + indent + alignmentOffset(lineWidth, indent);
+                const baseline = yPosition + box.baseline + box.height * index;
+                // Latin-only text in an `ltr` paragraph comes back as one unchanged piece.
+                // Word-spacing is a per-gap advance just like the justification slack, so it rides the same
+                // mechanism: `Tw` would reach only the single byte 32 and miss every embedded font.
+                const extra = wordSpacing + justifyExtra(line, lineWidth, index === lines.length - 1, indent);
+                for (const part of visualRuns(line, direction)) {
+                    const piece = shapedPiece(part, fontFamily, fontStyle);
+                    const partWidth = emitPiece(piece, x, extra, {
+                        y: baseline,
+                        fontFamily,
+                        fontStyle,
+                        fontSize,
+                        color,
+                        ...(letterSpacing ? { letterSpacing } : {}),
+                    }, font, letterSpacing);
+                    decorate(piece.text, x, partWidth, baseline, fontFamily, fontStyle, fontSize, color, underline, strikethrough, letterSpacing);
+                    x += partWidth;
+                }
             });
-            return runs;
+            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
         // the previous segment's kerning-free advance. Each line drops by its OWN leading
         // (tallest font on that line), so mixed-font lines space correctly and the drawn
         // height matches the measured height.
-        const pushLine = (line, lineY) => {
+        const pushLine = (line, lineY, isLast) => {
             let x = initialX + alignmentOffset(line.width);
-            line.segments.forEach((segment) => {
+            const extra = justifyExtra(line.segments.map((seg) => seg.content).join(""), line.width, isLast);
+            // Across span boundaries, so a Hebrew span is ordered against its neighbours rather than inside
+            // itself. Each run keeps the segment it came from, and with it that span's style.
+            const ordered = visualRunsOf(line.segments.map((segment) => ({ text: segment.content, source: segment })), direction);
+            ordered.forEach((part) => {
+                const segment = part.source;
                 const family = segment.fontFamily || fontFamily;
                 const size = segment.fontSize || fontSize;
                 const style = segment.fontStyle || fontStyle;
-                runs.push({
-                    type: "text",
-                    x,
-                    y: lineY,
-                    text: segment.content,
+                const segLetterSpacing = segment.letterSpacing ?? letterSpacing;
+                const piece = shapedPiece(part, family, style);
+                const runText = piece.text;
+                const runColor = segment.fontColor || color;
+                // `vertical-align`: this run alone leaves the line's baseline. Its own decoration and link box
+                // ride along, since both are placed from the same y.
+                const shift = VERTICAL_TEXT_SHIFT[segment.verticalAlign ?? "baseline"] * size;
+                const runY = lineY - shift;
+                const drawn = emitPiece(piece, x, extra, {
+                    y: runY,
                     fontFamily: family,
                     fontStyle: style,
                     fontSize: size,
-                    color: segment.fontColor || color,
-                });
-                x += advanceNoKerning(segment.content, family, size, style);
+                    color: runColor,
+                    ...(segLetterSpacing ? { letterSpacing: segLetterSpacing } : {}),
+                }, { fontFamily: family, fontSize: size, fontStyle: style }, segLetterSpacing);
+                decorate(runText, x, drawn, runY, 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: runY - v.ascent * size,
+                        width: drawn,
+                        height: (v.ascent + v.descent) * size,
+                        href: segment.href,
+                        dest: segment.dest,
+                    });
+                }
+                x += drawn;
             });
         };
-        // 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 (0, line_breaker_1.breakSegmentsIntoLines)(content, { fontFamily, fontSize, fontStyle }, maxWidth, objectManager)) {
-            pushLine(line, lineY);
-            lineY += line.maxFontSize;
-        }
-        return runs;
+        // 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;
+        // Materialised, because justification has to know which line is the LAST one of the paragraph.
+        const segmentLines = [
+            ...breakSegmentsIntoLines(content, defaults, maxWidth, objectManager, maxLines, overflow),
+        ];
+        segmentLines.forEach((line, index) => {
+            const box = lineBoxForSegmentLine(line, defaults, objectManager, lineHeight);
+            pushLine(line, top + box.baseline, index === segmentLines.length - 1);
+            top += box.height;
+        });
+        return { runs, links, decorations };
     }
 }
-exports.TextRenderer = TextRenderer;

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;