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

package/dist/text/text-decoration.js

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

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

@@ -0,0 +1,60 @@
+import { Color } from "../common/color.js";
+import { FontStyle } from "../utils/pdf-object-manager.js";
+import { HorizontalAlignment } from "../elements/pdf-element.js";
+import type { Direction } from "./bidi.js";
+/** CSS `text-transform`. `capitalize` upper-cases the first letter of every word, as CSS does. */
+export type TextTransform = "none" | "uppercase" | "lowercase" | "capitalize";
+/**
+ * Apply a `text-transform`. One place, so the measured text and the drawn text are the same string.
+ *
+ * `atWordStart` carries the capitalisation state ACROSS pieces: a word split over two spans
+ * (`span("hel") + span("lo")`) is still one word, and only its first letter is raised.
+ */
+export declare function applyTextTransform(text: string, transform: TextTransform, atWordStart?: boolean): {
+    text: string;
+    atWordStart: boolean;
+};
+/**
+ * The inheritable text properties - the same set CSS and Flutter cascade. A `Text` resolves each of
+ * its own (possibly unset) properties against the nearest cascaded style: explicit > inherited >
+ * built-in default. Box/layout properties (padding, border, width, ...) are deliberately NOT here -
+ * they never inherit, exactly as in CSS.
+ */
+export interface ResolvedTextStyle {
+    fontSize: number;
+    fontFamily: string;
+    /** The rest of the family stack: tried, in order, for a code point `fontFamily` cannot draw. */
+    fontFallback: string[];
+    fontStyle: FontStyle;
+    color: Color;
+    textAlignment: HorizontalAlignment;
+    /** Multiplier of the font size. `undefined` means the font's natural line height
+     *  (`ascent + descent + lineGap`), i.e. CSS `line-height: normal`. */
+    lineHeight?: number;
+    /** Draw a line under the text, at the position and thickness the font declares. */
+    underline: boolean;
+    /** Draw a line through the text, at half its x-height. */
+    strikethrough: boolean;
+    /** Let the underline step around descenders (CSS `text-decoration-skip-ink`). Needs an EMBEDDED
+     *  font: the standard-14 outlines live in the viewer, not in the AFM. */
+    skipInk: boolean;
+    /** Extra space after every glyph, in points (CSS `letter-spacing`). Default 0. */
+    letterSpacing: number;
+    /** Base writing direction (CSS `direction`). It decides where a line STARTS and how neutral
+     *  characters between two scripts resolve; the reordering itself follows Unicode UAX #9 either
+     *  way, so Hebrew inside an `ltr` paragraph still comes out right. */
+    direction: Direction;
+    /** CSS `text-transform`: recase the text before it is measured or drawn. */
+    textTransform: TextTransform;
+    /** CSS `word-spacing`, in points: extra advance at every space. Negative tightens. */
+    wordSpacing: number;
+    /** CSS `text-indent`, in points: how far the FIRST line of a paragraph starts in. */
+    textIndent: number;
+}
+/**
+ * The root of the cascade: what a `Text` falls back to when neither it nor any ancestor sets a
+ * property.
+ */
+export declare const DEFAULT_TEXT_STYLE: ResolvedTextStyle;
+/** Layers a partial override onto a complete style; an unset (undefined) field keeps the base. */
+export declare function mergeTextStyle(base: ResolvedTextStyle, override?: Partial<ResolvedTextStyle>): ResolvedTextStyle;

package/dist/text/text-style.js

@@ -0,0 +1,79 @@
+import { Color } from "../common/color.js";
+import { FontStyle } from "../utils/pdf-object-manager.js";
+import { HorizontalAlignment } from "../elements/pdf-element.js";
+/**
+ * Apply a `text-transform`. One place, so the measured text and the drawn text are the same string.
+ *
+ * `atWordStart` carries the capitalisation state ACROSS pieces: a word split over two spans
+ * (`span("hel") + span("lo")`) is still one word, and only its first letter is raised.
+ */
+export function applyTextTransform(text, transform, atWordStart = true) {
+    const ends = text === "" ? atWordStart : /\s$/u.test(text);
+    if (transform === "none")
+        return { text, atWordStart: ends };
+    if (transform === "uppercase")
+        return { text: text.toUpperCase(), atWordStart: ends };
+    if (transform === "lowercase")
+        return { text: text.toLowerCase(), atWordStart: ends };
+    // CSS raises the first typographic LETTER of every word. Punctuation is not one, so a leading
+    // bracket or quote does not consume the word start - `(hello)` becomes `(Hello)`, as in a browser.
+    let start = atWordStart;
+    let out = "";
+    for (const ch of text) {
+        if (/\s/u.test(ch)) {
+            out += ch;
+            start = true;
+        }
+        else if (start && /\p{L}|\p{N}/u.test(ch)) {
+            out += ch.toUpperCase();
+            start = false;
+        }
+        else {
+            out += ch;
+        }
+    }
+    return { text: out, atWordStart: start };
+}
+/**
+ * The root of the cascade: what a `Text` falls back to when neither it nor any ancestor sets a
+ * property.
+ */
+export const DEFAULT_TEXT_STYLE = {
+    fontSize: 12,
+    fontFamily: "Helvetica",
+    fontFallback: [],
+    fontStyle: FontStyle.Normal,
+    color: new Color(0, 0, 0),
+    textAlignment: HorizontalAlignment.start,
+    lineHeight: undefined,
+    underline: false,
+    strikethrough: false,
+    skipInk: false,
+    letterSpacing: 0,
+    direction: "ltr",
+    textTransform: "none",
+    wordSpacing: 0,
+    textIndent: 0,
+};
+/** Layers a partial override onto a complete style; an unset (undefined) field keeps the base. */
+export function mergeTextStyle(base, override) {
+    if (!override)
+        return base;
+    return {
+        fontSize: override.fontSize ?? base.fontSize,
+        fontFamily: override.fontFamily ?? base.fontFamily,
+        fontFallback: override.fontFallback ?? base.fontFallback,
+        fontStyle: override.fontStyle ?? base.fontStyle,
+        color: override.color ?? base.color,
+        textAlignment: override.textAlignment ?? base.textAlignment,
+        lineHeight: override.lineHeight ?? base.lineHeight,
+        underline: override.underline ?? base.underline,
+        strikethrough: override.strikethrough ?? base.strikethrough,
+        skipInk: override.skipInk ?? base.skipInk,
+        letterSpacing: override.letterSpacing ?? base.letterSpacing,
+        direction: override.direction ?? base.direction,
+        textTransform: override.textTransform ?? base.textTransform,
+        wordSpacing: override.wordSpacing ?? base.wordSpacing,
+        textIndent: override.textIndent ?? base.textIndent,
+    };
+}

package/dist/text/whitespace.d.ts

@@ -0,0 +1,4 @@
+import type { TextSegment } from "../elements/text-element.js";
+export declare function normalizeWhitespace(text: string): string;
+/** The same, for content that may already be split into styled spans. */
+export declare function normalizeContent(content: string | TextSegment[]): string | TextSegment[];

package/dist/text/whitespace.js

@@ -0,0 +1,43 @@
+/**
+ * A character with no glyph is still ENCODED and DRAWN: it comes out as the font's .notdef box, and
+ * veraPDF rejects the file for referencing .notdef (ISO 19005-3, 6.2.11.8). A `\n` in an invoice
+ * description was the first case we hit; zero-width characters are the same fault and arrive far more
+ * quietly - a paste out of Word or a web page carries them routinely.
+ *
+ * So nothing invisible survives into the breaker except `\n`, and that only because the breaker treats
+ * it as a hard break. The mapping follows a browser's `white-space: normal` apart from `\n`: CSS
+ * collapses that to a space, while a text COMPONENT breaks on it - Flutter's `Text` and react-pdf both
+ * do, and it is what anyone writing `"a\nb"` expects.
+ */
+/**
+ * Everything that MEANS a line break, matched as a WHOLE so a two-character ending never becomes two
+ * breaks. `\n\r` is in here beside `\r\n` because it is what a mistyped CRLF looks like, and a stray
+ * blank line is a worse answer than reading it as the one break it was meant to be. U+2028/U+2029 are
+ * Unicode's own line and paragraph separators.
+ */
+const LINE_BREAKS = /\r\n|\n\r|\r|\u2028|\u2029/g;
+/**
+ * Invisible and inert: a zero-width space and a byte-order mark carry no meaning we act on, so they are
+ * dropped rather than drawn. C0, C1 and DEL likewise.
+ *
+ * Deliberately NOT here: U+200C/U+200D (zero-width non-joiner and joiner) drive Arabic shaping and
+ * emoji sequences, and U+200E/U+200F (the bidi marks) drive `text/bidi.ts`. Dropping those would
+ * silently change how correct text is laid out - worse than the box they can still leave behind in a
+ * run that neither shapes nor reorders.
+ */
+// oxlint-disable-next-line no-control-regex -- matching control characters is the whole point here.
+const UNPRINTABLE = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F-\u009F\u200B\uFEFF]/g;
+export function normalizeWhitespace(text) {
+    return (text
+        // Every spelling of a break becomes `\n` first, so the breaker only ever sees one form.
+        .replace(LINE_BREAKS, "\n")
+        // A tab is collapsible whitespace; a PDF text operator has no tab stops to advance to.
+        .replace(/\t/g, " ")
+        .replace(UNPRINTABLE, ""));
+}
+/** The same, for content that may already be split into styled spans. */
+export function normalizeContent(content) {
+    if (typeof content === "string")
+        return normalizeWhitespace(content);
+    return content.map((seg) => ({ ...seg, content: normalizeWhitespace(seg.content) }));
+}

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

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

package/dist/utils/afm-parser.js

@@ -1,23 +1,23 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.AFMParser = void 0;
-const fs_1 = __importDefault(require("fs"));
-const path_1 = __importDefault(require("path"));
-class AFMParser {
+import { AGL } from "../assets/font-data.js";
+export class AFMParser {
     constructor(afmData) {
         this.advanceWidths = {};
         this.kerningPairs = {};
         this.glyphMap = {};
+        // The font's bounding box in glyph space (1000 units / em), from the AFM header. This - not the
+        // `Ascender` line - is what a line box is built from; see `verticals()`.
+        this.bbox = [0, 0, 0, 0];
+        // Glyph metrics from the AFM header, for underline / strikethrough. All 14 standard fonts carry
+        // the underline pair; Symbol and ZapfDingbats have no CapHeight/XHeight (they have no lowercase).
+        this.underlinePosition = 0; // negative, as the AFM writes it: below the baseline
+        this.underlineThickness = 0;
+        this.capHeight = 0;
+        this.xHeight = 0;
         this.parseAFMData(afmData);
         this.loadGlyphList();
     }
     loadGlyphList() {
-        const afmFilePath = path_1.default.resolve(__dirname, "../", "assets/agl.txt");
-        const fileContent = fs_1.default.readFileSync(afmFilePath, "utf-8");
-        const lines = fileContent.split("\n");
+        const lines = AGL.split("\n");
         for (const line of lines) {
             const parts = line.trim().split(";");
             if (parts.length >= 2) {
@@ -34,6 +34,7 @@ class AFMParser {
         return this.glyphMap[char] || char;
     }
     parseAFMData(afmData) {
+        var _a;
         const lines = afmData.split("\n");
         let inCharMetrics = false;
         for (let line of lines) {
@@ -53,13 +54,31 @@ class AFMParser {
                     this.advanceWidths[charName] = wx;
                 }
             }
+            if (line.startsWith("UnderlinePosition ")) {
+                this.underlinePosition = parseFloat(line.slice(18));
+            }
+            if (line.startsWith("UnderlineThickness ")) {
+                this.underlineThickness = parseFloat(line.slice(19));
+            }
+            if (line.startsWith("CapHeight ")) {
+                this.capHeight = parseFloat(line.slice(10));
+            }
+            if (line.startsWith("XHeight ")) {
+                this.xHeight = parseFloat(line.slice(8));
+            }
+            if (line.startsWith("FontBBox ")) {
+                const [x0, y0, x1, y1] = line.slice(9).trim().split(/\s+/).map(parseFloat);
+                this.bbox = [x0, y0, x1, y1];
+            }
             if (line.startsWith("KPX")) {
                 const parts = line.split(/\s+/);
                 const firstChar = parts[1];
                 const secondChar = parts[2];
                 const kerning = parseFloat(parts[3]);
-                const pair = `${firstChar}-${secondChar}`;
-                this.kerningPairs[pair] = kerning;
+                // Nested by first glyph, then second. A flat `${a}-${b}` key would have to be BUILT on every
+                // lookup, and getKerning runs once per adjacent character pair - that string allocation was a
+                // quarter of a standard-font render.
+                ((_a = this.kerningPairs)[firstChar] ?? (_a[firstChar] = {}))[secondChar] = kerning;
             }
         }
     }
@@ -80,12 +99,52 @@ class AFMParser {
         }
         return null;
     }
+    /**
+     * The font's LINE metrics, as fractions of the em: how far a line box must reach above and below
+     * the baseline. Taken from the `FontBBox`.
+     *
+     * Not from the AFM's `Ascender` / `Descender` lines, and that distinction is the whole point.
+     * `Ascender 718` is a GLYPH metric - the height of `b`, `d`, `h` - and for Helvetica it happens to
+     * equal the cap height. The line-metric equivalent is TrueType's `hhea.ascent`, which is much
+     * taller because it has to clear the accented capitals: Arial declares 0.905 where its caps reach
+     * 0.716. That surplus above the caps (0.189) is about as large as the descent below the baseline
+     * (0.212), which is exactly why capitals look vertically centred in a browser.
+     *
+     * Helvetica's `FontBBox` is `-166 -225 1000 931`: 0.931 up, 0.225 down - within a hair of Arial's
+     * hhea numbers. So the bbox IS the standard-14 line metric, and there is no leftover slack to
+     * call a lineGap. (Seating the baseline at `Ascender` instead put every capital too high; see
+     * ISSUE-5.)
+     */
+    verticals() {
+        if (this.cachedVerticals)
+            return this.cachedVerticals;
+        const [, yMin, , yMax] = this.bbox;
+        this.cachedVerticals = { ascent: yMax / 1000, descent: -yMin / 1000, lineGap: 0 };
+        return this.cachedVerticals;
+    }
+    /**
+     * The font's decoration metrics (underline / strikethrough), as fractions of the em.
+     *
+     * Symbol and ZapfDingbats declare no `CapHeight`/`XHeight` - they have no lowercase letters. For
+     * those the bbox top is the only height the font gives us, so the capitals reach it and a
+     * strikethrough crosses at half of that. Still read from the font, not guessed.
+     */
+    decoration() {
+        if (this.cachedDecoration)
+            return this.cachedDecoration;
+        const capHeight = this.capHeight || this.bbox[3];
+        this.cachedDecoration = {
+            underlinePosition: -this.underlinePosition / 1000, // AFM writes it negative (below the baseline)
+            underlineThickness: this.underlineThickness / 1000,
+            capHeight: capHeight / 1000,
+            xHeight: (this.xHeight || capHeight / 2) / 1000,
+        };
+        return this.cachedDecoration;
+    }
     getAdvanceWidth(charName) {
         return this.advanceWidths[this.getGlyphName(charName)] || 0;
     }
     getKerning(firstChar, secondChar) {
-        const pair = `${firstChar}-${secondChar}`;
-        return this.kerningPairs[pair] || 0;
+        return this.kerningPairs[firstChar]?.[secondChar] ?? 0;
     }
 }
-exports.AFMParser = AFMParser;

package/dist/utils/bytes.d.ts

@@ -0,0 +1,24 @@
+/**
+ * A `Uint8Array` → a latin1 (ISO-8859-1) string: each byte 0x00-0xFF maps 1:1 to the same code point.
+ * This matches `Buffer.toString("latin1")` exactly. NOTE: do NOT use `TextDecoder("latin1")` here - per
+ * the encoding spec that label is really windows-1252, which mangles 0x80-0x9F; we need a true 1:1 pass
+ * so arbitrary binary (e.g. a compressed stream) rides through unchanged. The PDF body is assembled as
+ * such a binary string and the final encoder passes 0x00-0xFF through.
+ */
+export declare function latin1FromBytes(bytes: Uint8Array): string;
+/**
+ * A latin1 (ISO-8859-1) string → a `Uint8Array`: each char's low byte. Matches `Buffer.from(str,
+ * "latin1")` / `"binary"`. Use for the binary strings the engine assembles char-by-char (CMaps, object
+ * bodies) before they become a stream.
+ */
+export declare function bytesFromLatin1(str: string): Uint8Array;
+export declare function u8(b: Uint8Array, o: number): number;
+export declare function u16(b: Uint8Array, o: number): number;
+export declare function u32(b: Uint8Array, o: number): number;
+export declare function i16(b: Uint8Array, o: number): number;
+export declare function wu16(b: Uint8Array, value: number, offset: number): void;
+export declare function wu32(b: Uint8Array, value: number, offset: number): void;
+export declare function wi16(b: Uint8Array, value: number, offset: number): void;
+export declare function writeLatin1(b: Uint8Array, str: string, offset: number): void;
+/** Concatenate Uint8Arrays into one (mirrors Buffer.concat). */
+export declare function concatBytes(parts: Uint8Array[]): Uint8Array;

package/dist/utils/bytes.js

@@ -0,0 +1,76 @@
+// Byte helpers for an isomorphic engine (Node + browser). Kept tiny + dependency-free; as the engine
+// moves off Node-only APIs, the Node `Buffer` conveniences are replaced by these.
+/**
+ * A `Uint8Array` → a latin1 (ISO-8859-1) string: each byte 0x00-0xFF maps 1:1 to the same code point.
+ * This matches `Buffer.toString("latin1")` exactly. NOTE: do NOT use `TextDecoder("latin1")` here - per
+ * the encoding spec that label is really windows-1252, which mangles 0x80-0x9F; we need a true 1:1 pass
+ * so arbitrary binary (e.g. a compressed stream) rides through unchanged. The PDF body is assembled as
+ * such a binary string and the final encoder passes 0x00-0xFF through.
+ */
+export function latin1FromBytes(bytes) {
+    let out = "";
+    const CHUNK = 0x8000; // chunk the apply() to stay under the argument-count limit on big streams
+    for (let i = 0; i < bytes.length; i += CHUNK) {
+        out += String.fromCharCode.apply(null, bytes.subarray(i, i + CHUNK));
+    }
+    return out;
+}
+/**
+ * A latin1 (ISO-8859-1) string → a `Uint8Array`: each char's low byte. Matches `Buffer.from(str,
+ * "latin1")` / `"binary"`. Use for the binary strings the engine assembles char-by-char (CMaps, object
+ * bodies) before they become a stream.
+ */
+export function bytesFromLatin1(str) {
+    const u8a = new Uint8Array(str.length);
+    for (let i = 0; i < str.length; i++)
+        u8a[i] = str.charCodeAt(i) & 0xff;
+    return u8a;
+}
+// Big-endian integer reads from a Uint8Array (TrueType + PDF are big-endian), mirroring
+// Buffer.readUInt8 / readUInt16BE / readUInt32BE / readInt16BE without needing a Buffer.
+export function u8(b, o) {
+    return b[o];
+}
+export function u16(b, o) {
+    return (b[o] << 8) | b[o + 1];
+}
+export function u32(b, o) {
+    // Multiply the top byte (a left shift by 24 would go negative in 32-bit signed math).
+    return b[o] * 0x1000000 + ((b[o + 1] << 16) | (b[o + 2] << 8) | b[o + 3]);
+}
+export function i16(b, o) {
+    const v = (b[o] << 8) | b[o + 1];
+    return v & 0x8000 ? v - 0x10000 : v;
+}
+// Big-endian integer + latin1-string writes into a Uint8Array, mirroring Buffer.writeUInt16BE /
+// writeUInt32BE / writeInt16BE / write(str, off, len, "latin1"). Arg order matches Buffer: (value, offset).
+export function wu16(b, value, offset) {
+    b[offset] = (value >>> 8) & 0xff;
+    b[offset + 1] = value & 0xff;
+}
+export function wu32(b, value, offset) {
+    b[offset] = (value >>> 24) & 0xff;
+    b[offset + 1] = (value >>> 16) & 0xff;
+    b[offset + 2] = (value >>> 8) & 0xff;
+    b[offset + 3] = value & 0xff;
+}
+export function wi16(b, value, offset) {
+    wu16(b, value & 0xffff, offset);
+}
+export function writeLatin1(b, str, offset) {
+    for (let i = 0; i < str.length; i++)
+        b[offset + i] = str.charCodeAt(i) & 0xff;
+}
+/** Concatenate Uint8Arrays into one (mirrors Buffer.concat). */
+export function concatBytes(parts) {
+    let len = 0;
+    for (const p of parts)
+        len += p.length;
+    const out = new Uint8Array(len);
+    let off = 0;
+    for (const p of parts) {
+        out.set(p, off);
+        off += p.length;
+    }
+    return out;
+}

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

@@ -0,0 +1,22 @@
+import type { PDFObjectManager } from "./pdf-object-manager.js";
+interface Dest {
+    pageObjNum: number;
+    top: number;
+}
+/**
+ * Collects named destinations - the jump targets an internal `Link({ to })` points at, declared with
+ * `Anchor({ name })`. `finalize` emits the `/Dests` name-tree fragment for the catalog `/Names` dict, or
+ * "" when no anchor was placed. Names are strings the viewer resolves at click time, so a link can point
+ * at an anchor on a later (not-yet-rendered) page without any forward-reference bookkeeping.
+ */
+export declare class DestRegistry {
+    private dests;
+    add(name: string, dest: Dest): void;
+    get isEmpty(): boolean;
+    /** The `/Dests << /Names [ ... ] >>` fragment for the catalog `/Names` dictionary (merged with any
+     *  `/EmbeddedFiles`). Returns "" when empty. Names are sorted lexically - a name tree requires it.
+     *  Takes the object manager only so the names go through its string choke-point and get encrypted
+     *  with everything else. */
+    finalize(om: PDFObjectManager): string;
+}
+export {};

package/dist/utils/dest-registry.js

@@ -0,0 +1,32 @@
+const num = (n) => (Number.isFinite(n) ? Number(n.toFixed(2)) : 0);
+/**
+ * Collects named destinations - the jump targets an internal `Link({ to })` points at, declared with
+ * `Anchor({ name })`. `finalize` emits the `/Dests` name-tree fragment for the catalog `/Names` dict, or
+ * "" when no anchor was placed. Names are strings the viewer resolves at click time, so a link can point
+ * at an anchor on a later (not-yet-rendered) page without any forward-reference bookkeeping.
+ */
+export class DestRegistry {
+    constructor() {
+        // Keyed by name so a duplicate name resolves to its last definition (last anchor wins).
+        this.dests = new Map();
+    }
+    add(name, dest) {
+        this.dests.set(name, dest);
+    }
+    get isEmpty() {
+        return this.dests.size === 0;
+    }
+    /** The `/Dests << /Names [ ... ] >>` fragment for the catalog `/Names` dictionary (merged with any
+     *  `/EmbeddedFiles`). Returns "" when empty. Names are sorted lexically - a name tree requires it.
+     *  Takes the object manager only so the names go through its string choke-point and get encrypted
+     *  with everything else. */
+    finalize(om) {
+        if (this.dests.size === 0)
+            return "";
+        const entries = [...this.dests.keys()].sort().map((name) => {
+            const d = this.dests.get(name);
+            return `${om.pdfString(name)} [${d.pageObjNum} 0 R /XYZ null ${num(d.top)} null]`;
+        });
+        return `/Dests << /Names [ ${entries.join(" ")} ] >>`;
+    }
+}