@jasy/pdf 1.0.0-beta.2 → 1.0.0-beta.4

package/dist/renderer/text-renderer.js

@@ -3,42 +3,30 @@ 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 { MAX_SPACE_SHRINK, breakSegmentsIntoLines, } from "../text/line-breaker.js";
+import { lineBoxForSegmentLine } from "../text/line-metrics.js";
 import { runAdvance } from "../text/advance.js";
-import { visualRuns, visualRunsOf } from "../text/bidi.js";
+import { visualRunsOf } from "../text/bidi.js";
 import { skipInkSegments, strikethroughStroke, underlineStroke, } from "../text/text-decoration.js";
 import { quadToCubic } from "../vector/path.js";
+/** What a link says when read aloud (its `/Contents`): its pieces, a space where a line ended. */
+function spokenText(pieces) {
+    let out = "";
+    pieces.forEach((piece, i) => {
+        if (i > 0 && piece.y !== pieces[i - 1].y)
+            out += " ";
+        out += piece.text;
+    });
+    return out.replace(/\s+/g, " ").trim();
+}
 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, letterSpacing = 0, lineOptions = {}) {
-        // Plain string: every wrapped line gets the same box.
-        if (typeof content === "string") {
-            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's box comes from the fonts actually on it. `splitting` has to travel with
-        // them for the same reason `letterSpacing` does: it changes where a line ENDS, so leaving it out
-        // measures a paragraph at one line count and draws it at another.
-        const defaults = {
-            fontFamily,
-            fontSize,
-            fontStyle,
-            letterSpacing,
-            splitting: lineOptions.splitting,
-            ligatures: lineOptions.ligatures,
-        };
-        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, underline, strikethrough, skipInk, letterSpacing, direction, wordSpacing, textIndent, breakWord, hyphenate, ligatures, 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, breakWord, hyphenate, ligatures);
+    static async render(textElement, objectManager, scope) {
+        const { x, y, width, fontSize, color, spans, fontFamily, fontStyle, textAlignment, maxLines, overflow, lineHeight, underline, strikethrough, skipInk, letterSpacing, direction, wordSpacing, textIndent, ligatures, role, breaking, } = textElement.getProps();
+        // Component -> display list: the lines come from the one breaker, positioning stays here; the
+        // backend turns each run into BT/Tf/Td/Tj/ET.
+        const { runs, links, decorations, linkGroups } = TextRenderer._buildRuns(spans, breaking, fontSize, fontFamily, fontStyle, objectManager, width ?? Number.NaN, textAlignment, color, 
+        // Every run, decoration and link rect derives from this one absolute origin.
+        scope.origin.x + (x ?? 0), scope.origin.y + (y ?? 0), maxLines, overflow, lineHeight, underline, strikethrough, skipInk, letterSpacing, direction, wordSpacing, textIndent, ligatures);
         // 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.
@@ -47,6 +35,25 @@ export class TextRenderer {
             const key = objectManager.struct.openElement(textElement.structId, pdfRole);
             for (const run of runs)
                 run.tag = { role: pdfRole, key };
+            // An inline link is a /Link element inside the paragraph: it holds its own text and its
+            // annotations, which describe themselves by that text (PDF/UA 7.18.5). One cut by a page break
+            // stays ONE element: the next piece of the paragraph continues the link its last one ended in.
+            const struct = objectManager.struct;
+            const carried = struct.takeCarriedLink(textElement.structId);
+            linkGroups.forEach((group, i) => {
+                const continues = i === 0 && group.runs[0] === runs[0] && carried?.target === group.target;
+                const linkKey = continues ? carried.key : struct.addElement("Link", key);
+                for (const run of group.runs)
+                    run.tag = { role: "Link", key: linkKey };
+                const first = group.links[0];
+                const alt = spokenText(group.pieces) || (first.href ?? first.dest ?? "");
+                for (const link of group.links)
+                    Object.assign(link, { structKey: linkKey, alt });
+                const last = group.runs[group.runs.length - 1];
+                if (i === linkGroups.length - 1 && last === runs[runs.length - 1]) {
+                    struct.carryLink(textElement.structId, group.target, linkKey);
+                }
+            });
         }
         // 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.
@@ -224,11 +231,17 @@ 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, underline = false, strikethrough = false, skipInk = false, letterSpacing = 0, direction = "ltr", wordSpacing = 0, textIndent = 0, breakWord = false, hyphenate, ligatures = true) {
+    static _buildRuns(content, 
+    // How the text is broken - the element's own settings, the ones it was measured with.
+    breaking, 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, ligatures = true) {
         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 = [];
+        // The same links grouped as the reader meets them: consecutive runs of one target are ONE link,
+        // across a line break too, with the text they cover (for the structure tree).
+        const linkGroups = [];
+        let openLink;
         // 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 = [];
@@ -266,34 +279,41 @@ export class TextRenderer {
             // 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);
+            // A space as the breaker counts it: word-spacing included.
+            const spaceWidth = runAdvance(objectManager, " ", { fontFamily, fontSize, fontStyle }, letterSpacing) +
+                wordSpacing;
             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.
+         * Push one drawn piece and return the advance it took. When the spaces get more room (word-spacing,
+         * justification) 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.
+         * A SHAPED piece is split there too, each word shaped on its own (`shape`): no slice of its glyph
+         * list is correct, but neither a ligature nor Arabic joining crosses a space - and a word plus a
+         * space is what the breaker measured.
          */
-        const emitPiece = (piece, x, extra, style, runFont, spacing) => {
+        const emitPiece = (piece, shape, rtl, 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(" ")) {
+            if (extra === 0 || !piece.text.includes(" ")) {
                 push(x, piece.text, piece.glyphs);
                 return runAdvance(objectManager, piece.text, runFont, spacing);
             }
             const spaceWidth = runAdvance(objectManager, " ", runFont, spacing);
+            // A shaped piece holds its LOGICAL text: drawn right to left, its words come in reverse.
             const words = piece.text.split(" ");
+            if (piece.glyphs && rtl)
+                words.reverse();
             let pen = x;
             words.forEach((word, i) => {
                 if (word !== "") {
-                    push(pen, word);
+                    const drawn = piece.glyphs ? shape(word) : { text: word };
+                    push(pen, drawn.text, drawn.glyphs);
                     pen += runAdvance(objectManager, word, runFont, spacing);
                 }
                 if (i < words.length - 1)
@@ -361,62 +381,25 @@ export class TextRenderer {
             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, ligatures };
-        // --- Plain string: one run per wrapped line. ---
-        if (typeof content === "string") {
-            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,
-                splitting: { breakWord, hyphenate },
-                ligatures,
-            });
-            // 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 = 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, links, decorations };
-        }
-        // --- Segments: break into lines (shared breaker), then emit one run per segment.
+        // Break into lines (the one 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, isLast) => {
-            let x = initialX + alignmentOffset(line.width);
-            const extra = justifyExtra(line.segments.map((seg) => seg.content).join(""), line.width, isLast);
+        const pushLine = (line, lineY, isLast, indent) => {
+            // CSS `text-indent`: the FIRST line starts in, with that much less room.
+            let x = initialX + indent + alignmentOffset(line.width, indent);
+            // 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.segments.map((seg) => seg.content).join(""), line.width, isLast, indent);
             // 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) => {
+                // A blank line keeps its height (its box is sized from the piece), but there is nothing to draw.
+                if (part.text === "")
+                    return;
                 const segment = part.source;
                 const family = segment.fontFamily || fontFamily;
                 const size = segment.fontSize || fontSize;
@@ -429,21 +412,24 @@ export class TextRenderer {
                 // 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, {
+                const firstRun = runs.length;
+                const drawn = emitPiece(piece, (word) => shapedPiece({ text: word, logical: word, rtl: part.rtl }, family, style), part.rtl, x, extra, {
                     y: runY,
                     fontFamily: family,
                     fontStyle: style,
                     fontSize: size,
                     color: runColor,
                     ...(segLetterSpacing ? { letterSpacing: segLetterSpacing } : {}),
-                }, { fontFamily: family, fontSize: size, fontStyle: style }, segLetterSpacing);
+                }, 
+                // `ligatures` is part of the font: the advances must be the glyphs that are drawn.
+                { fontFamily: family, fontSize: size, fontStyle: style, ligatures }, 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({
+                    const link = {
                         type: "link",
                         x,
                         y: runY - v.ascent * size,
@@ -451,34 +437,38 @@ export class TextRenderer {
                         height: (v.ascent + v.descent) * size,
                         href: segment.href,
                         dest: segment.dest,
-                    });
+                    };
+                    links.push(link);
+                    const target = segment.href !== undefined ? `href:${segment.href}` : `dest:${segment.dest}`;
+                    if (openLink?.target !== target) {
+                        openLink = { target, group: { target, links: [], runs: [], pieces: [] } };
+                        linkGroups.push(openLink.group);
+                    }
+                    openLink.group.links.push(link);
+                    openLink.group.runs.push(...runs.slice(firstRun));
+                    openLink.group.pieces.push({ text: runText, y: runY });
+                }
+                else if (runText.trim() !== "") {
+                    openLink = undefined;
                 }
                 x += drawn;
             });
         };
         // 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,
-            splitting: { breakWord, hyphenate },
-            ligatures,
-        };
+        // The seam flips the whole thing to PDF space. The lines are broken with the element's own
+        // settings - the ones `textHeight` measured with - so measured equals drawn by construction.
+        const defaults = breaking;
         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),
-        ];
+        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);
+            // Only a line that WRAPPED is stretched: the end of a paragraph and the line before a `\n` keep
+            // their natural spacing (CSS). The last line of a piece continued on the next page wrapped.
+            const ends = line.end === "hard" || line.end === "end";
+            pushLine(line, top + box.baseline, ends, index === 0 ? textIndent : 0);
             top += box.height;
         });
-        return { runs, links, decorations };
+        return { runs, links, decorations, linkGroups };
     }
 }

package/dist/svg/gradients.js

@@ -135,6 +135,11 @@ export function resolveSvgGradient(def, defs, commands) {
     ];
     const scale = Math.abs(matrix[0]);
     const extend = SPREAD[attributes["spreadMethod"] ?? "pad"] ?? "pad";
+    if (extend !== "pad") {
+        // A PDF shading only clamps its end colours; repeating or mirroring would need a tiling pattern.
+        // Drawn as `pad` it is a different picture - so it is named.
+        throw new SvgUnsupportedError(`spreadMethod="${extend}" on a gradient`, "Only pad (the default) is drawn. Expand the repeats into stops in your editor.");
+    }
     if (def.kind === "linear") {
         // Both anchors go through the transform, so a rotation or a shear lands correctly by itself.
         const [x0, y0] = point(px(num(attributes["x1"], 0)), py(num(attributes["y1"], 0)));

package/dist/svg/index.js

@@ -112,9 +112,14 @@ function rootMapping(root, target) {
  * it draws something the file did not describe: a drop-shadow logo as a hard silhouette. `clip-path`
  * used to be listed here; it is resolved now, which is the honest version of the same rule.
  */
+const MARKER_HINT = "Markers (arrowheads, dots on a line) are not drawn yet; expand them into shapes in your editor.";
 const REFUSED_ATTRIBUTES = {
     mask: "Masks are pixel operations; flatten the artwork in your editor instead.",
     filter: "Filters are pixel operations; rasterise that part to a PNG instead.",
+    marker: MARKER_HINT,
+    "marker-start": MARKER_HINT,
+    "marker-mid": MARKER_HINT,
+    "marker-end": MARKER_HINT,
 };
 function refuseAttributes(tagName, read) {
     for (const [name, hint] of Object.entries(REFUSED_ATTRIBUTES)) {
@@ -210,6 +215,10 @@ function walk(node, parentStyle, rules, clips, gradients, out, depth = 0) {
     // Everything below reads through the cascade, not the raw attributes: `filter="url(#f)"` and
     // `style="filter:url(#f)"` are the same instruction, and a `<style>` rule can set either.
     const read = cascadedReader(attributes, css);
+    // `display: none` takes the element out with everything inside it - nothing of it is drawn, so
+    // nothing of it can be unsupported either.
+    if (read("display")?.trim() === "none")
+        return;
     refuseAttributes(tagName, read);
     const style = resolveStyle(parentStyle, attributes, css);
     const transform = attributes["transform"]
@@ -248,7 +257,7 @@ function walk(node, parentStyle, rules, clips, gradients, out, depth = 0) {
         }
         // A shape with neither fill nor stroke, or with no geometry, paints nothing - and an empty Path
         // node would only cost bytes.
-        if (commands.length > 0 && (style.fill || style.stroke)) {
+        if (commands.length > 0 && style.visible && (style.fill || style.stroke)) {
             // A gradient is resolved HERE too, and for the same reason: in its default units its anchors
             // are fractions of the SHAPE's bounding box, which only exists at this point.
             const shapeAlpha = style.fillOpacity * style.opacity;

package/dist/svg/style.d.ts

@@ -30,6 +30,8 @@ export interface SvgStyle {
     fillOpacity: number;
     strokeOpacity: number;
     opacity: number;
+    /** `visibility` (inherits): a hidden shape paints nothing, but a child may set `visible` again. */
+    visible: boolean;
 }
 /** The colour a shape actually paints with: its raw colour, times the opacities that reached it. */
 export declare function paintAlpha(color: Color, opacity: number): Color;

package/dist/svg/style.js

@@ -18,6 +18,7 @@ export const ROOT_STYLE = {
     fillOpacity: 1,
     strokeOpacity: 1,
     opacity: 1,
+    visible: true,
 };
 /** Splits a `style=""` bag into declarations. It wins over both other sources, as in CSS. */
 function styleBag(value) {
@@ -140,5 +141,15 @@ export function resolveStyle(parent, attributes, css = {}) {
         fillOpacity: ratio(read("fill-opacity"), parent.fillOpacity),
         strokeOpacity: ratio(read("stroke-opacity"), parent.strokeOpacity),
         opacity,
+        visible: visibility(read("visibility"), parent.visible),
     };
 }
+/** `hidden` and `collapse` hide, `visible` shows, anything else (`inherit`, unset) keeps the parent's. */
+function visibility(value, parent) {
+    const v = value?.trim();
+    if (v === "hidden" || v === "collapse")
+        return false;
+    if (v === "visible")
+        return true;
+    return parent;
+}

package/dist/text/advance.d.ts

@@ -32,6 +32,10 @@ export interface RunFont {
 /** 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;
+/** U+00AD: "a line may break here, with a hyphen". Invisible wherever it does not. */
+export declare const SOFT_HYPHEN = "\u00AD";
+/** `text` as it is drawn: without its soft hyphens. */
+export declare function withoutSoftHyphens(text: string): string;
 /** The advance of `text` in points: the plain glyph widths, plus kerning (if the document has it on),
  *  plus one `letterSpacing` per code point. */
 export declare function runAdvance(metrics: FontMetrics, text: string, font: RunFont, letterSpacing?: number): number;

package/dist/text/advance.js

@@ -39,6 +39,12 @@ export function codePointCount(text) {
  * is thrown away when it flips; the same document can be rendered twice with different options.
  */
 const ADVANCE_CACHE = new WeakMap();
+/**
+ * The innermost map a `RunFont` resolves to, remembered on the font object itself. The breaker builds
+ * one font per run and asks for every word with it, so without this each word walks five maps of which
+ * four hold a single entry.
+ */
+const BY_FONT = new WeakMap();
 function baseAdvance(metrics, text, font) {
     let entry = ADVANCE_CACHE.get(metrics);
     const epoch = metrics.fontEpoch ?? 0;
@@ -49,6 +55,20 @@ function baseAdvance(metrics, text, font) {
         entry = { epoch, kerning, byFamily: new Map() };
         ADVANCE_CACHE.set(metrics, entry);
     }
+    // Same font object as last time, and the metrics entry has not been replaced: the map is already known.
+    // Its FIELDS are compared, not just its identity: a caller that reuses one object and changes the
+    // size on it would otherwise be handed the previous size's map.
+    const known = BY_FONT.get(font);
+    if (known?.entry === entry &&
+        known.family === font.fontFamily &&
+        known.size === font.fontSize &&
+        known.style === font.fontStyle &&
+        known.ligatures === font.ligatures) {
+        const seen = known.byText.get(text);
+        if (seen !== undefined)
+            return seen;
+        return measureAndStore(metrics, text, font, known.byText);
+    }
     let byStyle = entry.byFamily.get(font.fontFamily);
     if (!byStyle)
         entry.byFamily.set(font.fontFamily, (byStyle = new Map()));
@@ -61,9 +81,26 @@ function baseAdvance(metrics, text, font) {
     let byText = bySize.get(font.fontSize);
     if (!byText)
         bySize.set(font.fontSize, (byText = new Map()));
+    BY_FONT.set(font, {
+        entry,
+        family: font.fontFamily,
+        size: font.fontSize,
+        style: font.fontStyle,
+        ligatures: font.ligatures,
+        byText,
+    });
     const hit = byText.get(text);
     if (hit !== undefined)
         return hit;
+    return measureAndStore(metrics, text, font, byText);
+}
+/** The measurement itself, once a miss has found the map it belongs in. */
+function measureAndStore(metrics, text, font, byText) {
+    // A soft hyphen is never drawn where it stands (a break there draws a real hyphen instead), so it has
+    // no width - taken out BEFORE measuring, so the kerning pair across it is the one drawn. Here, on a
+    // cache miss, and not on every call: the stored width is the drawn one, keyed by the source text.
+    const key = text;
+    text = withoutSoftHyphens(text);
     let advance = metrics.getStringWidth(text, font.fontFamily, font.fontSize, font.fontStyle, font.ligatures);
     if (metrics.kerningEnabled) {
         let units = 0;
@@ -71,17 +108,25 @@ function baseAdvance(metrics, text, font) {
             units += k;
         advance += (units / 1000) * font.fontSize; // kern units are em/1000
     }
-    byText.set(text, advance);
+    byText.set(key, advance);
     return advance;
 }
+/** U+00AD: "a line may break here, with a hyphen". Invisible wherever it does not. */
+export const SOFT_HYPHEN = "\u00AD";
+/** `text` as it is drawn: without its soft hyphens. */
+export function withoutSoftHyphens(text) {
+    return text.includes(SOFT_HYPHEN) ? text.split(SOFT_HYPHEN).join("") : text;
+}
 /** 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 = baseAdvance(metrics, text, font);
     if (letterSpacing !== 0) {
-        // Per DRAWN glyph, which is what `Tc` applies to; only a ligature makes that differ.
-        const glyphs = metrics.shapedGlyphCount?.(text, font.fontFamily, font.fontStyle, font.ligatures) ??
-            codePointCount(text);
+        // Per DRAWN glyph, which is what `Tc` applies to; only a ligature makes that differ. A soft hyphen is
+        // not drawn.
+        const drawn = withoutSoftHyphens(text);
+        const glyphs = metrics.shapedGlyphCount?.(drawn, font.fontFamily, font.fontStyle, font.ligatures) ??
+            codePointCount(drawn);
         advance += glyphs * letterSpacing;
     }
     return advance;

package/dist/text/bidi.d.ts

@@ -29,5 +29,3 @@ export declare function visualRunsOf<T>(pieces: {
     text: string;
     source: T;
 }[], base?: Direction): AttributedRun<T>[];
-/** The same for one plain string. An empty string still yields one run, or a blank line would vanish. */
-export declare const visualRuns: (text: string, base?: Direction) => VisualRun[];

package/dist/text/bidi.js

@@ -82,13 +82,3 @@ export function visualRunsOf(pieces, base = "ltr") {
     flush();
     return runs;
 }
-/** The same for one plain string. An empty string still yields one run, or a blank line would vanish. */
-export const visualRuns = (text, base = "ltr") => {
-    if (text === "")
-        return [{ text, logical: text, rtl: false }];
-    return visualRunsOf([{ text, source: null }], base).map(({ text: t, logical, rtl }) => ({
-        text: t,
-        logical,
-        rtl,
-    }));
-};

package/dist/text/glyph-coverage.d.ts

@@ -10,6 +10,6 @@ export interface CoverageResult {
  * Replaces or removes what `fontFamily` cannot draw. Returns the input unchanged (and no allocation
  * beyond the scan) when everything is drawable, which is the overwhelmingly common case.
  */
-export declare function coverText(text: string, fontFamily: string, fontStyle: FontStyle, metrics: FontMetrics): CoverageResult;
+export declare function coverText(text: string, fontFamily: string, fontStyle: FontStyle, metrics: FontMetrics, emoji?: boolean): CoverageResult;
 /** `U+2713` - how a dropped code point is named to the caller. */
 export declare function formatCodePoint(cp: number): string;

package/dist/text/glyph-coverage.js

@@ -39,19 +39,23 @@ const EQUIVALENTS = {
  * Replaces or removes what `fontFamily` cannot draw. Returns the input unchanged (and no allocation
  * beyond the scan) when everything is drawable, which is the overwhelmingly common case.
  */
-export function coverText(text, fontFamily, fontStyle, metrics) {
+export function coverText(text, fontFamily, fontStyle, metrics, 
+// Whether colour emoji count as drawable: in `Text` they are drawn from the emoji source; a form
+// field's appearance has only its own font.
+emoji = true) {
     let out = null; // built only once something has to change
     const dropped = [];
     let index = 0;
     for (const char of text) {
         const cp = char.codePointAt(0);
-        // A space and a line break are handled by the breaker, never drawn as a glyph.
+        // A space, a line break and a soft hyphen are handled by the breaker, never drawn as a glyph.
         const drawable = cp === 0x20 ||
             cp === 0x0a ||
+            cp === 0xad ||
             metrics.hasGlyph(cp, fontFamily, fontStyle) ||
             // Colour emoji is drawn from a fallback font or an image, NOT from the text font - it is missing
             // there by design, and removing it would delete the very thing `Document({ emoji })` exists for.
-            metrics.rendersAsEmoji?.(cp, fontFamily, fontStyle) === true;
+            (emoji && metrics.rendersAsEmoji?.(cp, fontFamily, fontStyle) === true);
         if (!drawable) {
             if (out === null)
                 out = text.slice(0, index);

package/dist/text/hyphen-breaks.d.ts

@@ -0,0 +1,17 @@
+export declare const NO_BREAKS: readonly number[];
+/** Whether a word holds anything it may break after: a hyphen or a soft hyphen. */
+export declare const mayBreak: (word: string) => boolean;
+/**
+ * Where a word may break, as offsets into it - after a hyphen (U+002D) as UAX #14 has it: never before
+ * it, never before a digit ("CODE-2", "2026-10-16", "-5" stay whole), never after one that starts the
+ * word; and after a soft hyphen (U+00AD), the break its author marked.
+ */
+export declare function hyphenBreaks(word: string): number[];
+/**
+ * What the line ending at break `k` draws of `word`: everything before it, and at a soft hyphen a REAL
+ * hyphen in its place - the only time a soft hyphen shows. The breaker draws this; measuring it measures
+ * what is drawn.
+ */
+export declare function headAt(word: string, k: number): string;
+/** A word cut at its break opportunities: the pieces no line can split, as they are drawn. */
+export declare function hyphenPieces(word: string): string[];

package/dist/text/hyphen-breaks.js

@@ -0,0 +1,54 @@
+import { SOFT_HYPHEN } from "./advance.js";
+import { HYPHEN } from "./word-splitting.js";
+// Where a word MAY break inside itself - pure text rules, no font and no line. Filling lines is
+// `line-breaker.ts`; this only answers which offsets are allowed.
+export const NO_BREAKS = [];
+/** Whether a word holds anything it may break after: a hyphen or a soft hyphen. */
+export const mayBreak = (word) => word.includes("-") || word.includes(SOFT_HYPHEN);
+/**
+ * Where a word may break, as offsets into it - after a hyphen (U+002D) as UAX #14 has it: never before
+ * it, never before a digit ("CODE-2", "2026-10-16", "-5" stay whole), never after one that starts the
+ * word; and after a soft hyphen (U+00AD), the break its author marked.
+ */
+export function hyphenBreaks(word) {
+    const out = [];
+    for (let i = 1; i < word.length - 1; i++) {
+        const next = word[i + 1];
+        if (NO_BREAK_BEFORE.has(next))
+            continue;
+        if (word[i] === SOFT_HYPHEN) {
+            out.push(i + 1);
+            continue;
+        }
+        if (word[i] !== "-")
+            continue;
+        if (next === "-" || (next >= "0" && next <= "9"))
+            continue;
+        out.push(i + 1);
+    }
+    return out;
+}
+// UAX #14 never breaks before closing punctuation, a slash or a quote (LB13, LB19): "Lohn-, Gehalts-",
+// "(well-known)", "Ein-/Ausgang" stay together.
+const NO_BREAK_BEFORE = new Set(")]}!?,.:;/\"'«»‘’“”");
+/**
+ * What the line ending at break `k` draws of `word`: everything before it, and at a soft hyphen a REAL
+ * hyphen in its place - the only time a soft hyphen shows. The breaker draws this; measuring it measures
+ * what is drawn.
+ */
+export function headAt(word, k) {
+    if (word[k - 1] !== SOFT_HYPHEN)
+        return word.slice(0, k);
+    // A soft hyphen right after a real one adds nothing: "ab-" + "cd", not "ab--".
+    return word[k - 2] === "-" ? word.slice(0, k - 1) : word.slice(0, k - 1) + HYPHEN;
+}
+/** A word cut at its break opportunities: the pieces no line can split, as they are drawn. */
+export function hyphenPieces(word) {
+    const breaks = mayBreak(word) ? hyphenBreaks(word) : NO_BREAKS;
+    if (breaks.length === 0)
+        return [word];
+    return [0, ...breaks].map((from, k) => {
+        const to = breaks[k];
+        return to === undefined ? word.slice(from) : headAt(word, to).slice(from);
+    });
+}