@jasy/pdf 1.0.0-beta.3 → 1.0.0-beta.5

package/dist/text/line-metrics.d.ts

@@ -2,13 +2,14 @@
  * The vertical half of text layout: how tall a line box is, and where its baseline sits.
  *
  * One canonical answer, like `line-breaker.ts` is the one canonical answer for the horizontal
- * half. Measuring (`calculateTextHeight`), fragmenting (`TextElement.fragment`) and drawing
+ * half. Measuring (`textHeight`), fragmenting (`TextElement.fragment`) and drawing
  * (`TextRenderer._buildRuns`) all call in here, so they can never disagree about a line's height
  * again - the divergence that produced ISSUE-5.
  */
 import type { FontStyle } from "../utils/pdf-object-manager.js";
 import type { FontMetrics } from "../utils/font-metrics.js";
-import type { SegmentDefaults, SegmentLine } from "./line-breaker.js";
+import type { TextSegment } from "../elements/text-element.js";
+import { type SegmentDefaults, type SegmentLine, type TextOverflow } from "./line-breaker.js";
 /** A font's vertical metrics, as fractions of the em (so they scale by multiplying with fontSize). */
 export interface FontVerticals {
     /** Distance from the baseline up to the ascender. Positive. */
@@ -42,8 +43,12 @@ export interface LineBox {
  * exactly like CSS, and the author asked for it.
  */
 export declare function lineBoxFor(parts: LinePart[], lineHeight?: number): LineBox;
-/** The line box of a single-font line (the plain-string path). */
+/** The line box of a single-font line - what an empty line takes in the paragraph's own font. */
 export declare function lineBoxForString(metrics: FontMetrics, fontFamily: string, fontStyle: FontStyle, fontSize: number, lineHeight?: number): LineBox;
 /** The line box of a mixed-font line: the tallest ascent and the deepest descent on it win, so a
  *  big or a deep-descending span pushes the whole line apart rather than colliding with it. */
 export declare function lineBoxForSegmentLine(line: SegmentLine, defaults: SegmentDefaults, metrics: FontMetrics, lineHeight?: number): LineBox;
+/** How tall a text is at `maxWidth`: its lines, from the one breaker, each in its own line box. */
+export declare function textHeight(spans: TextSegment[], defaults: SegmentDefaults, maxWidth: number, metrics: FontMetrics, maxLines?: number, overflow?: TextOverflow, lineHeight?: number): number;
+/** How tall these lines stand, each in its own line box. */
+export declare function linesHeight(lines: SegmentLine[], defaults: SegmentDefaults, metrics: FontMetrics, lineHeight?: number): number;

package/dist/text/line-metrics.js

@@ -2,10 +2,11 @@
  * The vertical half of text layout: how tall a line box is, and where its baseline sits.
  *
  * One canonical answer, like `line-breaker.ts` is the one canonical answer for the horizontal
- * half. Measuring (`calculateTextHeight`), fragmenting (`TextElement.fragment`) and drawing
+ * half. Measuring (`textHeight`), fragmenting (`TextElement.fragment`) and drawing
  * (`TextRenderer._buildRuns`) all call in here, so they can never disagree about a line's height
  * again - the divergence that produced ISSUE-5.
  */
+import { breakSegmentsIntoLines, } from "./line-breaker.js";
 /**
  * The line box for a set of fonts sharing one line.
  *
@@ -34,7 +35,7 @@ export function lineBoxFor(parts, lineHeight) {
     const height = lineHeight === undefined ? content + gap : maxFontSize * lineHeight;
     return { height, baseline: (height - content) / 2 + ascent };
 }
-/** The line box of a single-font line (the plain-string path). */
+/** The line box of a single-font line - what an empty line takes in the paragraph's own font. */
 export function lineBoxForString(metrics, fontFamily, fontStyle, fontSize, lineHeight) {
     return lineBoxFor([{ verticals: metrics.getFontVerticals(fontFamily, fontStyle), fontSize }], lineHeight);
 }
@@ -55,3 +56,11 @@ export function lineBoxForSegmentLine(line, defaults, metrics, lineHeight) {
     }
     return lineBoxFor(parts, lineHeight);
 }
+/** How tall a text is at `maxWidth`: its lines, from the one breaker, each in its own line box. */
+export function textHeight(spans, defaults, maxWidth, metrics, maxLines, overflow, lineHeight) {
+    return linesHeight(breakSegmentsIntoLines(spans, defaults, maxWidth, metrics, maxLines, overflow), defaults, metrics, lineHeight);
+}
+/** How tall these lines stand, each in its own line box. */
+export function linesHeight(lines, defaults, metrics, lineHeight) {
+    return lines.reduce((total, line) => total + lineBoxForSegmentLine(line, defaults, metrics, lineHeight).height, 0);
+}

package/dist/text/pdf-text-string.d.ts

@@ -0,0 +1,21 @@
+/**
+ * PDF text strings - a title, a bookmark, alt text, a field value, an attachment's name - in both
+ * directions, from ONE table.
+ *
+ * A text string is PDFDocEncoding or UTF-16BE with a byte-order mark (PDF 2.0 adds UTF-8 with one).
+ * PDFDocEncoding is NOT Windows-1252: byte 0x96 is an en dash in Windows-1252 and "Œ" here, 0x80 is "€"
+ * there and "•" here. A writer that sends text through the Windows-1252 page encoder therefore shows
+ * "Preis – 5 €" as "Preis Œ 5 •".
+ */
+/** A text string's bytes: PDFDocEncoding when it can say everything, otherwise UTF-16BE with its BOM. */
+export declare function encodePdfText(text: string): Uint8Array;
+/** Name-tree order: keys sorted by their ENCODED bytes, which is what a reader searching the tree compares -
+ *  not JS string order, which disagrees as soon as one key is PDFDocEncoding and another UTF-16. */
+export declare function comparePdfText(a: string, b: string): number;
+/** A text string's meaning: UTF-16BE or UTF-8 by their byte-order mark, otherwise PDFDocEncoding. */
+export declare function decodePdfText(bytes: Uint8Array): string;
+/**
+ * Whether `text` can be written as a plain `(literal)` that the Windows-1252 page encoder turns into the
+ * same bytes PDFDocEncoding reads back: printable ASCII and the Latin-1 letters both encodings share.
+ */
+export declare function isPlainPdfText(text: string): boolean;

package/dist/text/pdf-text-string.js

@@ -0,0 +1,114 @@
+/**
+ * PDF text strings - a title, a bookmark, alt text, a field value, an attachment's name - in both
+ * directions, from ONE table.
+ *
+ * A text string is PDFDocEncoding or UTF-16BE with a byte-order mark (PDF 2.0 adds UTF-8 with one).
+ * PDFDocEncoding is NOT Windows-1252: byte 0x96 is an en dash in Windows-1252 and "Œ" here, 0x80 is "€"
+ * there and "•" here. A writer that sends text through the Windows-1252 page encoder therefore shows
+ * "Preis – 5 €" as "Preis Œ 5 •".
+ */
+/** PDFDocEncoding where it differs from Latin-1 (ISO 32000-1, Annex D); 0x9F and 0xAD are undefined. */
+const PDF_DOC = {
+    0x18: 0x02d8,
+    0x19: 0x02c7,
+    0x1a: 0x02c6,
+    0x1b: 0x02d9,
+    0x1c: 0x02dd,
+    0x1d: 0x02db,
+    0x1e: 0x02da,
+    0x1f: 0x02dc,
+    0x80: 0x2022,
+    0x81: 0x2020,
+    0x82: 0x2021,
+    0x83: 0x2026,
+    0x84: 0x2014,
+    0x85: 0x2013,
+    0x86: 0x0192,
+    0x87: 0x2044,
+    0x88: 0x2039,
+    0x89: 0x203a,
+    0x8a: 0x2212,
+    0x8b: 0x2030,
+    0x8c: 0x201e,
+    0x8d: 0x201c,
+    0x8e: 0x201d,
+    0x8f: 0x2018,
+    0x90: 0x2019,
+    0x91: 0x201a,
+    0x92: 0x2122,
+    0x93: 0xfb01,
+    0x94: 0xfb02,
+    0x95: 0x0141,
+    0x96: 0x0152,
+    0x97: 0x0160,
+    0x98: 0x0178,
+    0x99: 0x017d,
+    0x9a: 0x0131,
+    0x9b: 0x0142,
+    0x9c: 0x0153,
+    0x9d: 0x0161,
+    0x9e: 0x017e,
+    0xa0: 0x20ac,
+};
+const FROM_UNICODE = new Map(Object.entries(PDF_DOC).map(([byte, cp]) => [cp, Number(byte)]));
+/** Latin-1 code points that mean something else in PDFDocEncoding, or nothing. */
+const NOT_LATIN1 = new Set([...Object.keys(PDF_DOC).map(Number), 0x9f, 0xad]);
+/** A text string's bytes: PDFDocEncoding when it can say everything, otherwise UTF-16BE with its BOM. */
+export function encodePdfText(text) {
+    const doc = [];
+    for (const ch of text) {
+        const cp = ch.codePointAt(0);
+        const byte = cp <= 0xff && !NOT_LATIN1.has(cp) ? cp : FROM_UNICODE.get(cp);
+        if (byte === undefined)
+            return utf16be(text);
+        doc.push(byte);
+    }
+    return Uint8Array.from(doc);
+}
+function utf16be(text) {
+    const out = new Uint8Array(2 + text.length * 2);
+    out[0] = 0xfe;
+    out[1] = 0xff;
+    for (let i = 0; i < text.length; i++) {
+        const unit = text.charCodeAt(i);
+        out[2 + i * 2] = unit >> 8;
+        out[3 + i * 2] = unit & 0xff;
+    }
+    return out;
+}
+/** Name-tree order: keys sorted by their ENCODED bytes, which is what a reader searching the tree compares -
+ *  not JS string order, which disagrees as soon as one key is PDFDocEncoding and another UTF-16. */
+export function comparePdfText(a, b) {
+    const x = encodePdfText(a);
+    const y = encodePdfText(b);
+    for (let i = 0; i < Math.min(x.length, y.length); i++)
+        if (x[i] !== y[i])
+            return x[i] - y[i];
+    return x.length - y.length;
+}
+/** A text string's meaning: UTF-16BE or UTF-8 by their byte-order mark, otherwise PDFDocEncoding. */
+export function decodePdfText(bytes) {
+    if (bytes.length >= 2 && bytes[0] === 0xfe && bytes[1] === 0xff) {
+        return new TextDecoder("utf-16be").decode(bytes.subarray(2));
+    }
+    if (bytes.length >= 3 && bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf) {
+        return new TextDecoder().decode(bytes.subarray(3));
+    }
+    let s = "";
+    for (const byte of bytes)
+        s += String.fromCodePoint(PDF_DOC[byte] ?? byte);
+    return s;
+}
+/**
+ * Whether `text` can be written as a plain `(literal)` that the Windows-1252 page encoder turns into the
+ * same bytes PDFDocEncoding reads back: printable ASCII and the Latin-1 letters both encodings share.
+ */
+export function isPlainPdfText(text) {
+    for (let i = 0; i < text.length; i++) {
+        const c = text.charCodeAt(i);
+        const ascii = (c >= 0x20 && c <= 0x7e) || c === 0x09 || c === 0x0a || c === 0x0d;
+        if (!ascii && !(c >= 0xa1 && c <= 0xff && c !== 0xad))
+            return false;
+    }
+    return true;
+}

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

@@ -7,11 +7,11 @@
  * `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.
+ * `OS/2` table. Nothing is invented. The strikethrough sits at `xHeight / 2` - our rule, not
+ * Chrome's: on the font first measured Chrome's centre landed there too (0.260 em vs 0.262), on
+ * Liberation Sans and Noto Sans it sat 2-4 pt higher at 40 pt. The underline stroke is the font's
+ * `underlineThickness`, as Chrome draws it with `text-decoration-thickness: from-font`; its POSITION
+ * follows the font, where Chrome has an offset of its own.
  */
 /** A font's decoration metrics, as fractions of the em. */
 export interface FontDecoration {

package/dist/text/text-decoration.js

@@ -7,11 +7,11 @@
  * `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.
+ * `OS/2` table. Nothing is invented. The strikethrough sits at `xHeight / 2` - our rule, not
+ * Chrome's: on the font first measured Chrome's centre landed there too (0.260 em vs 0.262), on
+ * Liberation Sans and Noto Sans it sat 2-4 pt higher at 40 pt. The underline stroke is the font's
+ * `underlineThickness`, as Chrome draws it with `text-decoration-thickness: from-font`; its POSITION
+ * follows the font, where Chrome has an offset of its own.
  */
 /** The underline for a run whose baseline sits at `baselineY` (engine coords, y grows down). */
 export function underlineStroke(decoration, fontSize, baselineY) {

package/dist/text/word-splitting.d.ts

@@ -27,16 +27,29 @@ export interface WordSplitting {
     /** Split anywhere as a last resort, without a hyphen. CSS `overflow-wrap: break-word`. */
     breakWord?: boolean;
 }
+/** The hyphen actually drawn at a hyphenation break. U+002D, in every font we can encode. */
+export declare const HYPHEN = "-";
+/**
+ * One piece of a split word. `hyphen`: a hyphen was added at the break - it is not in the source.
+ * `source`: how many characters of the word the piece covers, which is where the next piece starts.
+ */
+export interface WordPiece {
+    text: string;
+    hyphen: boolean;
+    source: number;
+}
 /**
  * Splits `word` into pieces that each fit within `room`. Returns null when nothing applies - no
  * splitting configured, or the word fits anyway - and the caller keeps its current behaviour, so a
  * document that asks for neither is untouched.
  *
  * Every piece but the last is a finished line. The last is what carries on, so the caller keeps
- * filling it as usual.
+ * filling it as usual. A piece says how much of the source it covers: a split paragraph needs that to
+ * find where the next line starts, and the drawn text cannot tell (an added hyphen, a soft hyphen the
+ * hyphenator dropped).
  */
 export declare function splitLongWord(word: string, room: number, font: {
     fontFamily: string;
     fontSize: number;
     fontStyle: FontStyle;
-}, metrics: FontMetrics, letterSpacing: number, options: WordSplitting): string[] | null;
+}, metrics: FontMetrics, letterSpacing: number, options: WordSplitting): WordPiece[] | null;

package/dist/text/word-splitting.js

@@ -1,13 +1,15 @@
-import { runAdvance } from "./advance.js";
+import { runAdvance, SOFT_HYPHEN } from "./advance.js";
 /** The hyphen actually drawn at a hyphenation break. U+002D, in every font we can encode. */
-const HYPHEN = "-";
+export const HYPHEN = "-";
 /**
  * Splits `word` into pieces that each fit within `room`. Returns null when nothing applies - no
  * splitting configured, or the word fits anyway - and the caller keeps its current behaviour, so a
  * document that asks for neither is untouched.
  *
  * Every piece but the last is a finished line. The last is what carries on, so the caller keeps
- * filling it as usual.
+ * filling it as usual. A piece says how much of the source it covers: a split paragraph needs that to
+ * find where the next line starts, and the drawn text cannot tell (an added hyphen, a soft hyphen the
+ * hyphenator dropped).
  */
 export function splitLongWord(word, room, font, metrics, letterSpacing, options) {
     const { hyphenate, breakWord } = options;
@@ -19,23 +21,47 @@ export function splitLongWord(word, room, font, metrics, letterSpacing, options)
         return null;
     const width = (s) => runAdvance(metrics, s, font, letterSpacing);
     const pieces = [];
-    let rest = word;
+    let rest = word; // what is drawn
+    let restSource = word; // the same text as it stands in the source
     // Bounded by construction: every pass either emits a piece and shortens `rest`, or gives up.
     while (width(rest) > room) {
         // The layering: a linguistically valid split if one is offered and reaches far enough, otherwise
         // the blunt one - which is what an e-mail address or an IBAN needs, having no valid point at all.
         const head = (hyphenate ? longestHyphenatedPrefix(rest, room, width, hyphenate) : null) ??
             (breakWord ? longestPrefix(rest, room, width) : null);
-        // Nothing fits - not even one character, or hyphenation found nothing and break-word is off.
-        // Leave the remainder whole and let it overflow, exactly as before.
+        // Hyphenation found nothing and break-word is off, or one character is all that is left: leave the
+        // remainder whole and let it overflow.
         if (head === null)
             break;
-        pieces.push(head.text);
+        // A hyphenator that returns text other than the word is not splitting it: leave it whole.
+        const source = sourceLength(restSource, head.taken);
+        if (source === null)
+            break;
+        pieces.push({ text: head.text, hyphen: head.hyphen, source });
         rest = head.rest;
+        restSource = restSource.slice(source);
     }
     if (pieces.length === 0)
         return null;
-    return [...pieces, rest];
+    return [...pieces, { text: rest, hyphen: false, source: restSource.length }];
+}
+/**
+ * How many characters of `source` the drawn `prefix` covers, with a soft hyphen at the break. A
+ * hyphenator may drop the soft hyphens already in the text (the `hyphen` package does), so they are
+ * skipped; anything else that does not match is null.
+ */
+function sourceLength(source, prefix) {
+    let i = 0;
+    for (const char of prefix) {
+        while (source[i] === SOFT_HYPHEN && char !== SOFT_HYPHEN)
+            i++;
+        if (!source.startsWith(char, i))
+            return null;
+        i += char.length;
+    }
+    while (source[i] === SOFT_HYPHEN)
+        i++;
+    return i;
 }
 /** The longest prefix that fits, plus a hyphen - split only where the hyphenator allows. */
 function longestHyphenatedPrefix(word, room, width, hyphenate) {
@@ -49,7 +75,7 @@ function longestHyphenatedPrefix(word, room, width, hyphenate) {
         // The hyphen has to fit too, or the line it lands on overflows by exactly that hyphen.
         if (width(taken + HYPHEN) > room)
             break;
-        best = { text: taken + HYPHEN, rest: parts.slice(i + 1).join("") };
+        best = { text: taken + HYPHEN, taken, rest: parts.slice(i + 1).join(""), hyphen: true };
     }
     return best;
 }
@@ -64,9 +90,15 @@ function longestPrefix(word, room, width) {
         taken += char;
         count += 1;
     }
-    // Not even one character fits: the box is narrower than a single glyph. Splitting cannot help, and
-    // looping on it would never terminate.
-    if (count === 0 || count === chars.length)
+    if (count === chars.length)
         return null;
-    return { text: taken, rest: chars.slice(count).join("") };
+    // Not even one character fits - the box is narrower than a glyph: one character per line, as CSS
+    // `overflow-wrap` sets it. Each pass still takes one, so the loop ends.
+    if (count === 0) {
+        if (chars.length === 1)
+            return null;
+        taken = chars[0];
+        count = 1;
+    }
+    return { text: taken, taken, rest: chars.slice(count).join(""), hyphen: false };
 }

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

@@ -42,5 +42,7 @@ export declare class AFMParser {
      */
     decoration(): FontDecoration;
     getAdvanceWidth(charName: string): number;
+    /** The pair's kerning. The AFM keys its pairs by GLYPH name (`KPX T comma`), like its widths - so the
+     *  characters are named first, or only letter-letter pairs (where the two coincide) would ever hit. */
     getKerning(firstChar: string, secondChar: string): number;
 }

package/dist/utils/afm-parser.js

@@ -11,6 +11,13 @@ function glyphList() {
         if (parts.length >= 2)
             map[String.fromCharCode(parseInt(parts[0], 16))] = parts[1];
     }
+    // Windows-1252 characters the AGLFN leaves out, by the glyph WinAnsiEncoding draws them with
+    // (ISO 32000-1, Annex D). Unnamed, they were measured as "?" while the viewer drew the real glyph.
+    map["\u00a0"] = "space";
+    map["\u00ad"] = "hyphen";
+    map["\u00b2"] = "twosuperior";
+    map["\u00b3"] = "threesuperior";
+    map["\u00b9"] = "onesuperior";
     return (sharedGlyphMap = map);
 }
 /** One parser per standard-14 face for the whole process: the AFM data is a constant and a parsed
@@ -152,7 +159,9 @@ export class AFMParser {
     getAdvanceWidth(charName) {
         return this.advanceWidths[this.getGlyphName(charName)] || 0;
     }
+    /** The pair's kerning. The AFM keys its pairs by GLYPH name (`KPX T comma`), like its widths - so the
+     *  characters are named first, or only letter-letter pairs (where the two coincide) would ever hit. */
     getKerning(firstChar, secondChar) {
-        return this.kerningPairs[firstChar]?.[secondChar] ?? 0;
+        return this.kerningPairs[this.getGlyphName(firstChar)]?.[this.getGlyphName(secondChar)] ?? 0;
     }
 }

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

@@ -14,7 +14,7 @@ export declare class DestRegistry {
     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.
+     *  `/EmbeddedFiles`). Returns "" when empty. Names are sorted by their encoded bytes - 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;

package/dist/utils/dest-registry.js

@@ -1,3 +1,4 @@
+import { comparePdfText } from "../text/pdf-text-string.js";
 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
@@ -17,13 +18,13 @@ export class DestRegistry {
         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.
+     *  `/EmbeddedFiles`). Returns "" when empty. Names are sorted by their encoded bytes - 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 entries = [...this.dests.keys()].sort(comparePdfText).map((name) => {
             const d = this.dests.get(name);
             return `${om.pdfString(name)} [${d.pageObjNum} 0 R /XYZ null ${num(d.top)} null]`;
         });

package/dist/utils/fetch-bytes.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Bytes from a URL, bounded - what a font and an image from a URL both go through.
+ *
+ * `fetch` is used directly: it is in every browser and in Node since 18, so this needs no platform
+ * port. A hung server must not hang a render, and a URL pointing at the wrong file (a video, a disk
+ * image) must not be read into memory in full before anyone notices: a timeout and a size ceiling that
+ * is enforced WHILE the body arrives.
+ */
+/** The error a caller wants its failures in - `FontUrlError`, `ImageUrlError`. */
+export type UrlErrorClass = new (message: string) => Error;
+export interface FetchLimits {
+    timeoutMs: number;
+    maxBytes: number;
+}
+/**
+ * Fetch `url` and hand back its body. Every failure is a `Fail` naming the URL and what it was meant
+ * to be (`what`: "font", "image"), never a raw network error a caller would not expect.
+ */
+export declare function fetchBytes(url: string, what: string, Fail: UrlErrorClass, limits: FetchLimits): Promise<Uint8Array>;

package/dist/utils/fetch-bytes.js

@@ -0,0 +1,79 @@
+/**
+ * Bytes from a URL, bounded - what a font and an image from a URL both go through.
+ *
+ * `fetch` is used directly: it is in every browser and in Node since 18, so this needs no platform
+ * port. A hung server must not hang a render, and a URL pointing at the wrong file (a video, a disk
+ * image) must not be read into memory in full before anyone notices: a timeout and a size ceiling that
+ * is enforced WHILE the body arrives.
+ */
+/**
+ * Fetch `url` and hand back its body. Every failure is a `Fail` naming the URL and what it was meant
+ * to be (`what`: "font", "image"), never a raw network error a caller would not expect.
+ */
+export async function fetchBytes(url, what, Fail, limits) {
+    let response;
+    try {
+        response = await fetch(url, { signal: AbortSignal.timeout(limits.timeoutMs) });
+    }
+    catch (e) {
+        const why = e?.name === "TimeoutError" || e?.name === "AbortError"
+            ? `it did not respond within ${limits.timeoutMs} ms`
+            : String(e?.message ?? e);
+        throw new Fail(`could not fetch the ${what} at ${url}: ${why}`);
+    }
+    if (!response.ok) {
+        throw new Fail(`the ${what} at ${url} could not be fetched: HTTP ${response.status}`);
+    }
+    // Everything past here still talks to the network, so a failure mid-body must not escape as a raw
+    // TypeError - a caller catching its own error class would miss it.
+    try {
+        return await readBounded(response, url, what, Fail, limits.maxBytes);
+    }
+    catch (e) {
+        if (e instanceof Fail)
+            throw e;
+        throw new Fail(`the ${what} at ${url} could not be read: ${String(e?.message ?? e)}`);
+    }
+}
+/** Read the body with a running ceiling, so an oversized response is dropped WHILE it arrives. */
+async function readBounded(response, url, what, Fail, maxBytes) {
+    // `Content-Length` is the cheap early exit; a server may omit or misstate it, so it is a hint only
+    // and the real ceiling is enforced below while reading.
+    const declared = Number(response.headers?.get?.("content-length") ?? NaN);
+    if (Number.isFinite(declared) && declared > maxBytes) {
+        throw new Fail(`the ${what} at ${url} is ${declared} bytes; the limit is ${maxBytes}`);
+    }
+    const body = response.body;
+    if (!body?.getReader) {
+        // No streaming body (an older runtime, or a stubbed response): fall back to reading it whole and
+        // checking afterwards. Weaker, but never worse than not checking at all.
+        const whole = new Uint8Array(await response.arrayBuffer());
+        if (whole.length > maxBytes) {
+            throw new Fail(`the ${what} at ${url} is larger than the ${maxBytes} byte limit`);
+        }
+        return whole;
+    }
+    const reader = body.getReader();
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        total += value.length;
+        if (total > maxBytes) {
+            await reader.cancel();
+            throw new Fail(`the ${what} at ${url} is larger than the ${maxBytes} byte limit`);
+        }
+        chunks.push(value);
+    }
+    if (chunks.length === 1)
+        return chunks[0];
+    const out = new Uint8Array(total);
+    let at = 0;
+    for (const c of chunks) {
+        out.set(c, at);
+        at += c.length;
+    }
+    return out;
+}

package/dist/utils/flex-layout.d.ts

@@ -1,7 +1,7 @@
 import { PDFElement, LayoutContext } from "../elements/pdf-element.js";
 import { BoxConstraints, Offset, Size } from "../layout/box-constraints.js";
-/** Distribution of the children ALONG the stacking (main) axis when there is leftover
- *  space and no flex child to absorb it. */
+/** `layout` places every child (one `calculateLayout` each); `measure` only sizes, with no side effects. */
+export type FlexMode = "layout" | "measure";
 export type { MainAlign, CrossAlign } from "../layout/alignment.js";
 import type { CrossAlign, MainAlign } from "../layout/alignment.js";
 /**
@@ -29,9 +29,10 @@ export interface FlexAxis {
      * unbounded main axis and shrink-wraps as before.
      */
     measureConstraints(crossAvail: number, mainMax?: number): BoxConstraints;
-    /** Constraints for a flex child (fills the cross axis like a stretched child). */
+    /** Constraints for a flex child: its main extent is SET (it fills its share, whatever size it asked
+     *  for), across it is an ordinary child. */
     flexConstraints(mainExtent: number, crossAvail: number): BoxConstraints;
-    /** Absolute offset for a child at main position `mainPos`, cross position `crossPos`. */
+    /** Offset (from the stack's top-left) of a child at main position `mainPos`, cross `crossPos`. */
     offsetAt(mainPos: number, crossPos: number): Offset;
 }
 export declare const VERTICAL_AXIS: FlexAxis;
@@ -48,15 +49,6 @@ export interface FlexOptions {
     alignContent?: MainAlign;
 }
 export declare class FlexLayoutHelper {
-    /**
-     * Lays out a flex line along `axis`, IN SOURCE ORDER, and places every child.
-     * Fixed children take their natural main extent; flex (`ExpandedElement`) children
-     * split the leftover main space by their `flex`. `gap` is inserted between children.
-     * `main` distributes any leftover when there is no flex child; `cross` positions/sizes
-     * each child across the line. Returns the total main extent consumed and the cross
-     * extent occupied. Vertical with `gap 0`, `main start`, `cross stretch` reproduces the
-     * previous Column layout exactly.
-     */
     /**
      * Lays out the children along `axis`, on one line or several.
      *
@@ -64,9 +56,10 @@ export declare class FlexLayoutHelper {
      * straight through, which is what keeps every existing document byte-identical. With `wrap` the
      * children are split into lines first and the SAME engine runs once per line.
      */
-    static layout(children: PDFElement[], axis: FlexAxis, mainAvail: number, crossAvail: number, mainStart: number, crossOrigin: number, options: FlexOptions, ctx: LayoutContext): {
+    static layout(children: PDFElement[], axis: FlexAxis, mainAvail: number, crossAvail: number, options: FlexOptions, ctx: LayoutContext, mode?: FlexMode): {
         mainUsed: number;
         crossUsed: number;
+        widestLine?: number;
     };
     /**
      * The wrapping path: split into lines, lay each one out, then place the lines across the axis.
@@ -76,5 +69,14 @@ export declare class FlexLayoutHelper {
      * `alignContent` needs: the block of lines can only be centred once its total is known.
      */
     private static layoutWrapped;
+    /**
+     * Lays out ONE flex line along `axis` and places every child. Fixed children take their natural main
+     * extent; flex children split the leftover by their `flex`; `gap` goes between children. `main`
+     * distributes leftover when nothing flexes; `cross` positions or stretches each child across the line.
+     * Returns the main extent consumed and the cross extent occupied.
+     *
+     * The steps run in this order, and the order is part of the result: `leftover` is taken after the
+     * shrink and before the share, and the main-axis spacing reads exactly that value.
+     */
     private static layoutLine;
 }