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

package/dist/renderer/text-renderer.js

@@ -1,18 +1,20 @@
 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 { wrapStringIntoLines, breakSegmentsIntoLines, } from "../text/line-breaker.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, maxLines, overflow, lineHeight, letterSpacing = 0) {
+    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);
+            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;
         }
@@ -22,11 +24,11 @@ export class TextRenderer {
         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, role, } = textElement.getProps();
+        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);
+        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.
@@ -61,6 +63,13 @@ export class TextRenderer {
         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
@@ -215,7 +224,7 @@ 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) {
+    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.
@@ -224,13 +233,74 @@ export class TextRenderer {
         // 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)
-                return (maxWidth - lineWidth) / 2;
-            if (textAlignment === 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;
         };
+        /**
+         * 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) => {
@@ -276,31 +346,58 @@ export class TextRenderer {
             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 = wrapStringIntoLines(content, fontFamily, fontSize, fontStyle, maxWidth, objectManager, maxLines, overflow, letterSpacing);
+            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 = runAdvance(objectManager, line, font, letterSpacing);
-                const x = initialX + alignmentOffset(lineWidth);
+                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;
-                runs.push({
-                    type: "text",
-                    x,
-                    y: baseline,
-                    text: line,
-                    fontFamily,
-                    fontStyle,
-                    fontSize,
-                    color,
-                    ...(letterSpacing ? { letterSpacing } : {}),
-                });
-                decorate(line, x, lineWidth, baseline, fontFamily, fontStyle, fontSize, color, underline, strikethrough, letterSpacing);
+                // 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 };
         }
@@ -309,27 +406,34 @@ export class TextRenderer {
         // 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;
                 const segLetterSpacing = segment.letterSpacing ?? letterSpacing;
-                const advance = runAdvance(objectManager, segment.content, { fontFamily: family, fontSize: size, fontStyle: style }, segLetterSpacing);
+                const piece = shapedPiece(part, family, style);
+                const runText = piece.text;
                 const runColor = segment.fontColor || color;
-                runs.push({
-                    type: "text",
-                    x,
-                    y: lineY,
-                    text: segment.content,
+                // `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: runColor,
                     ...(segLetterSpacing ? { letterSpacing: segLetterSpacing } : {}),
-                });
-                decorate(segment.content, x, advance, lineY, family, style, size, runColor, segment.underline ?? underline, segment.strikethrough ?? strikethrough, 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.
@@ -338,14 +442,14 @@ export class TextRenderer {
                     links.push({
                         type: "link",
                         x,
-                        y: lineY - v.ascent * size,
-                        width: advance,
+                        y: runY - v.ascent * size,
+                        width: drawn,
                         height: (v.ascent + v.descent) * size,
                         href: segment.href,
                         dest: segment.dest,
                     });
                 }
-                x += advance;
+                x += drawn;
             });
         };
         // yPosition is the top of the text box (top-left). Each line seats its own baseline inside its
@@ -355,11 +459,15 @@ export class TextRenderer {
         // 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)) {
+        // 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);
+            pushLine(line, top + box.baseline, index === segmentLines.length - 1);
             top += box.height;
-        }
+        });
         return { runs, links, decorations };
     }
 }

package/dist/text/advance.js

@@ -30,8 +30,11 @@ export function codePointCount(text) {
  *  plus one `letterSpacing` per code point. */
 export function runAdvance(metrics, text, font, letterSpacing = 0) {
     let advance = metrics.getStringWidth(text, font.fontFamily, font.fontSize, font.fontStyle);
-    if (letterSpacing !== 0)
-        advance += codePointCount(text) * letterSpacing;
+    if (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) ?? codePointCount(text);
+        advance += glyphs * letterSpacing;
+    }
     if (metrics.kerningEnabled) {
         let units = 0;
         for (const k of metrics.getKernPairs(text, font.fontFamily, font.fontStyle))

package/dist/text/arabic.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Arabic (and Syriac / N'Ko / Adlam) JOINING: which of the four positional forms each letter takes -
+ * the half of shaping Unicode owns. Runs on the LOGICAL string.
+ *
+ * Name the SIDES, not the neighbours: a letter is joined on its right when the preceding one can join
+ * forwards (type D or L), on its left when the following one can join backwards (D or R). Thinking in
+ * "previous/next" puts a final form where an initial belongs.
+ */
+export type JoiningType = "D" | "R" | "L" | "C" | "T" | "U";
+/** The four positional forms, named as the OpenType features that realise them. */
+export type JoiningForm = "isol" | "init" | "medi" | "fina";
+/** The joining type of one code point. `U` for everything the table does not mention. */
+export declare function joiningType(codePoint: number): JoiningType;
+/** Whether a run contains anything the joining pass would touch. Cheap, and false for Latin. */
+export declare function needsJoining(codePoints: readonly number[]): boolean;
+/**
+ * The positional form of every code point, or `null` where none applies (space, digit, mark).
+ * `C` (tatweel, ZWJ) counts when deciding a NEIGHBOUR's form but takes none itself.
+ */
+export declare function joiningForms(codePoints: readonly number[]): (JoiningForm | null)[];

package/dist/text/arabic.js

@@ -0,0 +1,101 @@
+/**
+ * Arabic (and Syriac / N'Ko / Adlam) JOINING: which of the four positional forms each letter takes -
+ * the half of shaping Unicode owns. Runs on the LOGICAL string.
+ *
+ * Name the SIDES, not the neighbours: a letter is joined on its right when the preceding one can join
+ * forwards (type D or L), on its left when the following one can join backwards (D or R). Thinking in
+ * "previous/next" puts a final form where an initial belongs.
+ */
+/**
+ * Joining types, from Unicode 17.0.0 `ArabicShaping.txt`, packed as `start,length,type` in hex.
+ * Anything not listed is `U` (non-joining), which is the standard's own default.
+ *
+ * `T` (transparent - combining marks) is mostly NOT in that file: the standard says an unlisted mark
+ * (category Mn/Me/Cf) is transparent, so those ranges are folded in from the character database.
+ */
+const PACKED = "300,6f,5 483,6,5 591,2c,5 5bf,0,5 5c1,1,5 5c4,1,5 5c7,0,5 610,a,5 61c,0,5 620,0,1 622,3,2" +
+    "  626,0,1 627,0,2 628,0,1 629,0,2 62a,4,1 62f,3,2 633,c,1 640,0,4 641,6,1 648,0,2 649,1,1 64b,14,5" +
+    "  66e,1,1 670,0,5 671,2,2 675,2,2 678,f,1 688,11,2 69a,25,1 6c0,0,2 6c1,1,1 6c3,8,2 6cc,0,1" +
+    "  6cd,0,2 6ce,0,1 6cf,0,2 6d0,1,1 6d2,1,2 6d5,0,2 6d6,6,5 6df,5,5 6e7,1,5 6ea,3,5 6ee,1,2 6fa,2,1" +
+    "  6ff,0,1 70f,0,5 710,0,2 711,0,5 712,2,1 715,4,2 71a,3,1 71e,0,2 71f,8,1 728,0,2 729,0,1 72a,0,2" +
+    "  72b,0,1 72c,0,2 72d,1,1 72f,0,2 730,1a,5 74d,0,2 74e,a,1 759,2,2 75c,e,1 76b,1,2 76d,3,1 771,0,2" +
+    "  772,0,1 773,1,2 775,2,1 778,1,2 77a,5,1 7a6,a,5 7ca,20,1 7eb,8,5 7fa,0,4 7fd,0,5 816,3,5 81b,8,5" +
+    "  825,2,5 829,4,5 840,0,2 841,4,1 846,1,2 848,0,1 849,0,2 84a,9,1 854,0,2 855,0,1 856,2,2 859,2,5" +
+    "  860,0,1 862,3,1 867,0,2 868,0,1 869,1,2 870,12,2 883,2,4 886,0,1 889,4,1 88e,0,2 88f,0,1 897,8,5" +
+    "  8a0,9,1 8aa,2,2 8ae,0,2 8af,1,1 8b1,1,2 8b3,5,1 8b9,0,2 8ba,e,1 8ca,17,5 8e3,1c,5 1807,0,1" +
+    "  180a,0,4 1820,58,1 1885,1,5 1887,21,1 18aa,0,1 200d,0,4 a840,31,1 a872,0,3 fe00,f,5 fe20,f,5" +
+    "  10ac0,4,1 10ac5,0,2 10ac7,0,2 10ac9,1,2 10acd,0,3 10ace,4,2 10ad3,3,1 10ad7,0,3 10ad8,4,1" +
+    "  10add,0,2 10ade,2,1 10ae1,0,2 10ae4,0,2 10aeb,3,1 10aef,0,2 10b80,0,1 10b81,0,2 10b82,0,1" +
+    "  10b83,2,2 10b86,2,1 10b89,0,2 10b8a,1,1 10b8c,0,2 10b8d,0,1 10b8e,1,2 10b90,0,1 10b91,0,2" +
+    "  10ba9,3,2 10bad,1,1 10d00,0,3 10d01,20,1 10d22,0,2 10d23,0,1 10ec2,0,2 10ec3,1,1 10ec6,1,1" +
+    "  10f30,2,1 10f33,0,2 10f34,10,1 10f51,2,1 10f54,0,2 10f70,3,1 10f74,1,2 10f76,b,1 10fb0,0,1" +
+    "  10fb2,1,1 10fb4,2,2 10fb8,0,1 10fb9,1,2 10fbb,1,1 10fbd,0,2 10fbe,1,1 10fc1,0,1 10fc2,1,2" +
+    "  10fc4,0,1 10fc9,0,2 10fca,0,1 10fcb,0,3 1e900,43,1 1e94b,0,5";
+const TYPES = ["U", "D", "R", "L", "C", "T"];
+// [start, end, typeIndex] triples, sorted by start - binary searched, so the table costs one lookup.
+const RANGES = PACKED.trim()
+    .split(/\s+/)
+    .map((entry) => {
+    const [start, length, type] = entry.split(",");
+    const from = parseInt(start, 16);
+    return [from, from + parseInt(length, 16), Number(type)];
+});
+/** The joining type of one code point. `U` for everything the table does not mention. */
+export function joiningType(codePoint) {
+    let lo = 0;
+    let hi = RANGES.length - 1;
+    while (lo <= hi) {
+        const mid = (lo + hi) >> 1;
+        const [from, to, type] = RANGES[mid];
+        if (codePoint < from)
+            hi = mid - 1;
+        else if (codePoint > to)
+            lo = mid + 1;
+        else
+            return TYPES[type];
+    }
+    return "U";
+}
+/** Whether a run contains anything the joining pass would touch. Cheap, and false for Latin. */
+export function needsJoining(codePoints) {
+    return codePoints.some((cp) => {
+        const t = joiningType(cp);
+        return t === "D" || t === "R" || t === "L" || t === "C";
+    });
+}
+/**
+ * The positional form of every code point, or `null` where none applies (space, digit, mark).
+ * `C` (tatweel, ZWJ) counts when deciding a NEIGHBOUR's form but takes none itself.
+ */
+export function joiningForms(codePoints) {
+    const types = codePoints.map(joiningType);
+    /** The nearest neighbour that is not transparent - a mark never breaks a join. */
+    const neighbour = (from, step) => {
+        for (let i = from + step; i >= 0 && i < types.length; i += step) {
+            if (types[i] !== "T")
+                return types[i];
+        }
+        return "U";
+    };
+    return types.map((type, i) => {
+        if (type !== "D" && type !== "R" && type !== "L")
+            return null;
+        const before = neighbour(i, -1);
+        const after = neighbour(i, +1);
+        const joinedRight = before === "D" || before === "L" || before === "C";
+        const joinedLeft = after === "D" || after === "R" || after === "C";
+        if (type === "D") {
+            if (joinedRight && joinedLeft)
+                return "medi";
+            if (joinedRight)
+                return "fina";
+            if (joinedLeft)
+                return "init";
+            return "isol";
+        }
+        // R joins only on its right; L (a handful of Syriac letters) only on its left.
+        if (type === "R")
+            return joinedRight ? "fina" : "isol";
+        return joinedLeft ? "init" : "isol";
+    });
+}

package/dist/text/bidi.d.ts

@@ -0,0 +1,33 @@
+export type Direction = "ltr" | "rtl";
+/** A piece of a line, already in the order it is drawn. */
+export interface VisualRun {
+    /** VISUAL order: hand it to the drawing code as it stands, left to right. */
+    text: string;
+    /**
+     * The same characters in LOGICAL order. SHAPING must use this: a letter's form comes from its
+     * neighbours, and reversing swaps them - shaping the visual text gives every letter the wrong form
+     * (measured: a word 8pt too wide). Shape this, then reverse the GLYPHS.
+     */
+    logical: string;
+    /** True when this run came out of right-to-left text - the caller may need it for alignment. */
+    rtl: boolean;
+}
+/** A run that remembers which input piece it came from, so a span keeps its font and colour. */
+export interface AttributedRun<T> extends VisualRun {
+    source: T;
+}
+/** Whether this text could be reordered at all. Cheap, and false for every Latin-only document. */
+export declare const needsBidi: (text: string) => boolean;
+/**
+ * Reorder one LINE of pieces into the runs to draw. The algorithm runs over the pieces JOINED, not
+ * each on its own, or a Hebrew span beside a Latin one would stay in source order. A run ends where
+ * the direction or the source piece changes.
+ *
+ * Line breaking happens before this, in logical order - what UAX #9 prescribes.
+ */
+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

@@ -0,0 +1,94 @@
+import bidiFactory from "bidi-js";
+/**
+ * Bidirectional text (UAX #9): one logical line in, the runs to draw left to right out. ORDERING
+ * only - joining letters into shapes is `text/shape.ts`.
+ *
+ * The whole seam to `bidi-js`: nothing outside this file knows it exists, so replacing it with our
+ * own is a change here alone (`todo.md`).
+ */
+const bidi = bidiFactory();
+// Every block whose script runs right to left, plus the explicit bidi control characters. Used only
+// as a fast path: no match and a left-to-right base means the algorithm cannot reorder anything.
+const RTL_OR_CONTROL = /[\u0590-\u08FF\u200F\u202B\u202E\u2067\uFB1D-\uFDFF\uFE70-\uFEFF]|[\uD802\uD803\uD83A\uD83B][\uDC00-\uDFFF]/;
+/** Whether this text could be reordered at all. Cheap, and false for every Latin-only document. */
+export const needsBidi = (text) => RTL_OR_CONTROL.test(text);
+const isHighSurrogate = (c) => c >= "\uD800" && c <= "\uDBFF";
+const isLowSurrogate = (c) => c >= "\uDC00" && c <= "\uDFFF";
+/**
+ * Reorder one LINE of pieces into the runs to draw. The algorithm runs over the pieces JOINED, not
+ * each on its own, or a Hebrew span beside a Latin one would stay in source order. A run ends where
+ * the direction or the source piece changes.
+ *
+ * Line breaking happens before this, in logical order - what UAX #9 prescribes.
+ */
+export function visualRunsOf(pieces, base = "ltr") {
+    const text = pieces.map((p) => p.text).join("");
+    // Verbatim - same count, same order, empty pieces included - so untouched documents stay
+    // byte-identical.
+    if (text === "" || (base === "ltr" && !needsBidi(text))) {
+        return pieces.map((p) => ({ ...p, logical: p.text, rtl: false }));
+    }
+    // Which piece each code unit came from, so a visual run can be traced back to its span.
+    const owner = new Int32Array(text.length);
+    let at = 0;
+    pieces.forEach((piece, index) => {
+        owner.fill(index, at, at + piece.text.length);
+        at += piece.text.length;
+    });
+    const levels = bidi.getEmbeddingLevels(text, base);
+    const order = bidi.getReorderedIndices(text, levels);
+    // `.levels`, NOT the result object the library's README passes: it indexes its argument directly,
+    // and given the object it silently returns an empty map - no bracket ever mirrored.
+    const mirrored = bidi.getMirroredCharactersMap(text, levels.levels);
+    const runs = [];
+    let current = []; // visual order, mirrored
+    let written = []; // the same run as the author wrote it
+    let currentRtl = false;
+    let currentOwner = -1;
+    const flush = () => {
+        if (current.length > 0) {
+            runs.push({
+                text: current.join(""),
+                // Tracked separately rather than un-reversing the visual text: that text has been MIRRORED,
+                // so a bracket would come back as its twin and shaping - and `ToUnicode` after it - would see
+                // a character the author never wrote.
+                logical: (currentRtl ? [...written].reverse() : written).join(""),
+                rtl: currentRtl,
+                source: pieces[currentOwner].source,
+            });
+            current = [];
+            written = [];
+        }
+    };
+    for (let k = 0; k < order.length; k++) {
+        const i = order[k];
+        const rtl = (levels.levels[i] & 1) === 1;
+        if (rtl !== currentRtl || owner[i] !== currentOwner)
+            flush();
+        currentRtl = rtl;
+        currentOwner = owner[i];
+        // A surrogate pair is two code units at one level, so reversing splits an astral character (an
+        // emoji in Hebrew text) into two broken halves. They arrive adjacent and swapped.
+        const next = k + 1 < order.length ? order[k + 1] : -1;
+        if (isLowSurrogate(text[i]) && next === i - 1 && isHighSurrogate(text[next])) {
+            current.push(text[next], text[i]);
+            written.push(text[next], text[i]);
+            k++;
+            continue;
+        }
+        current.push(mirrored.get(i) ?? text[i]);
+        written.push(text[i]);
+    }
+    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/font-fallback.d.ts

@@ -0,0 +1,25 @@
+import type { FontStyle } from "../utils/pdf-object-manager.js";
+import type { FontMetrics } from "../utils/font-metrics.js";
+/**
+ * Font FALLBACK: picking, per code point, the first family in a stack that can draw it.
+ *
+ * `Text({ font: ["Inter", "NotoSansCJK"] })` should just work for mixed-script text. Without this a
+ * code point the first family lacks comes out as `.notdef` - the empty box.
+ *
+ * The output is a list of pieces, each in ONE family, which is exactly the shape a styled `span`
+ * already has. So the fallback reuses the whole segment machinery - breaking, bidi, shaping and
+ * drawing all handle per-piece fonts already - instead of adding a second one beside it.
+ */
+/** A stretch of text that one family can draw. */
+export interface FontRun {
+    text: string;
+    fontFamily: string;
+}
+/**
+ * Split `text` into runs by family. Returns `undefined` when there is nothing to split - no stack, or
+ * the first family draws everything - so a document that never asks for a fallback keeps its old path.
+ *
+ * A code point that NO family in the stack can draw stays with the first one, which then draws its
+ * `.notdef`. That is what a browser does too: the fallback chain ends, and the missing glyph shows.
+ */
+export declare function splitByFont(text: string, fontFamily: string, fallback: readonly string[], fontStyle: FontStyle, metrics: FontMetrics): FontRun[] | undefined;

package/dist/text/font-fallback.js

@@ -0,0 +1,38 @@
+/**
+ * Split `text` into runs by family. Returns `undefined` when there is nothing to split - no stack, or
+ * the first family draws everything - so a document that never asks for a fallback keeps its old path.
+ *
+ * A code point that NO family in the stack can draw stays with the first one, which then draws its
+ * `.notdef`. That is what a browser does too: the fallback chain ends, and the missing glyph shows.
+ */
+export function splitByFont(text, fontFamily, fallback, fontStyle, metrics) {
+    if (fallback.length === 0)
+        return undefined;
+    const familyFor = (codePoint) => {
+        if (metrics.hasGlyph(codePoint, fontFamily, fontStyle))
+            return fontFamily;
+        for (const family of fallback) {
+            if (metrics.hasGlyph(codePoint, family, fontStyle))
+                return family;
+        }
+        return fontFamily; // nobody has it - the first family shows the missing glyph
+    };
+    const runs = [];
+    let current = "";
+    let currentFamily = fontFamily;
+    for (const ch of text) {
+        const family = familyFor(ch.codePointAt(0));
+        if (current !== "" && family !== currentFamily) {
+            runs.push({ text: current, fontFamily: currentFamily });
+            current = "";
+        }
+        currentFamily = family;
+        current += ch;
+    }
+    if (current !== "")
+        runs.push({ text: current, fontFamily: currentFamily });
+    // Nothing substituted - no runs at all (empty text), or one in the family we started with. Say so,
+    // and the caller keeps its cheaper path instead of being handed an empty list to draw.
+    const unchanged = runs.length === 0 || (runs.length === 1 && runs[0].fontFamily === fontFamily);
+    return unchanged ? undefined : runs;
+}