reamkit 1.15.0 → 1.15.2

package/dist/esm/pdf-reader/font.d.ts

@@ -1,4 +1,16 @@
 import { PdfDict } from '../pdf/objects.js';
 import { ContentFont } from './content.js';
 import { PdfFile } from './document.js';
+/**
+ * Build a {@link ContentFont} (the interpreter's decode + advance hooks) from a
+ * `/Font` dictionary (E-PDF EP2). Unicode comes from the `/ToUnicode` CMap;
+ * glyph advances from a simple font's `/Widths` (§9.6.2.1) or a composite
+ * `/Type0` font's descendant `/W` array (§9.7.4.3). A code with no `/ToUnicode`
+ * entry decodes to its Latin-1 character for a simple font, or to nothing for a
+ * composite one.
+ *
+ * @param file     The owning {@link PdfFile}, used to resolve indirect references.
+ * @param fontDict The `/Font` dictionary.
+ * @returns The decode/advance hooks plus the code width (1 or 2 bytes per code).
+ */
 export declare function buildContentFont(file: PdfFile, fontDict: PdfDict): ContentFont;

package/dist/esm/pdf-reader/font.js

@@ -1,6 +1,18 @@
 import { PDF_NULL, PdfName, PdfStream } from "../pdf/objects.js";
 import { parseToUnicodeCMap } from "./cmap.js";
 //#region src/pdf-reader/font.ts
+/**
+* Build a {@link ContentFont} (the interpreter's decode + advance hooks) from a
+* `/Font` dictionary (E-PDF EP2). Unicode comes from the `/ToUnicode` CMap;
+* glyph advances from a simple font's `/Widths` (§9.6.2.1) or a composite
+* `/Type0` font's descendant `/W` array (§9.7.4.3). A code with no `/ToUnicode`
+* entry decodes to its Latin-1 character for a simple font, or to nothing for a
+* composite one.
+*
+* @param file     The owning {@link PdfFile}, used to resolve indirect references.
+* @param fontDict The `/Font` dictionary.
+* @returns The decode/advance hooks plus the code width (1 or 2 bytes per code).
+*/
 function buildContentFont(file, fontDict) {
 	const isType0 = asName(file.resolve(fontDict.get("Subtype") ?? PDF_NULL)) === "Type0";
 	let toUnicode = /* @__PURE__ */ new Map();

package/dist/esm/pdf-reader/image-decode.d.ts

@@ -1,15 +1,36 @@
 import { PdfFile } from './document.js';
 import { PdfStream } from '../pdf/objects.js';
+/**
+ * The result of {@link decodePdfImage}: either a decoded standalone raster file
+ * (with pixel dimensions and an optional `degraded` note for a partial loss,
+ * e.g. a JPEG's alpha dropped) or a typed failure carrying the loss severity and
+ * a human-readable reason.
+ */
 export type DecodedImage = {
     readonly ok: true;
     readonly bytes: Uint8Array;
     readonly format: 'png' | 'jpeg' | 'jpeg2000';
     readonly widthPx: number;
     readonly heightPx: number;
+    /** A partial loss note (e.g. a JPEG's alpha dropped). */
     readonly degraded?: string;
 } | {
     readonly ok: false;
     readonly severity: 'dropped' | 'degraded';
     readonly detail: string;
 };
+/**
+ * Decode a PDF image XObject (ISO 32000-1 §8.9) into a standalone raster file
+ * the FlowDoc resource store can hold. JPEG (`/DCTDecode`) and JPEG 2000
+ * (`/JPXDecode`) pass through verbatim — only the filters layered before them
+ * are stripped; everything else is decoded to raw samples and re-wrapped as PNG.
+ * Supports DeviceGray/RGB/CMYK, CalGray/CalRGB, ICCBased (by `/N`) and Indexed
+ * colour spaces; Flate, LZW (EP12), RunLength, ASCII85, ASCIIHex and CCITT
+ * Group 4 / Group 3 1-D fax (EP15) filters; PNG/TIFF predictors; bit depths
+ * 1/2/4/8/16; and an `/SMask` folded in as the PNG alpha channel. Unsupported
+ * inputs (stencil `/ImageMask`, Separation/DeviceN/Lab, JBIG2, CCITT Group 3
+ * 2-D) return a typed failure so the caller records a loss.
+ *
+ * @returns The decoded image, or `{ ok: false }` with the loss severity and reason.
+ */
 export declare function decodePdfImage(file: PdfFile, stream: PdfStream): DecodedImage;

package/dist/esm/pdf-reader/image-decode.js

@@ -5,6 +5,20 @@ import { encodePng } from "./png-encode.js";
 import { unzlibSync } from "fflate";
 //#region src/pdf-reader/image-decode.ts
 var MAX_PIXELS = 4e7;
+/**
+* Decode a PDF image XObject (ISO 32000-1 §8.9) into a standalone raster file
+* the FlowDoc resource store can hold. JPEG (`/DCTDecode`) and JPEG 2000
+* (`/JPXDecode`) pass through verbatim — only the filters layered before them
+* are stripped; everything else is decoded to raw samples and re-wrapped as PNG.
+* Supports DeviceGray/RGB/CMYK, CalGray/CalRGB, ICCBased (by `/N`) and Indexed
+* colour spaces; Flate, LZW (EP12), RunLength, ASCII85, ASCIIHex and CCITT
+* Group 4 / Group 3 1-D fax (EP15) filters; PNG/TIFF predictors; bit depths
+* 1/2/4/8/16; and an `/SMask` folded in as the PNG alpha channel. Unsupported
+* inputs (stencil `/ImageMask`, Separation/DeviceN/Lab, JBIG2, CCITT Group 3
+* 2-D) return a typed failure so the caller records a loss.
+*
+* @returns The decoded image, or `{ ok: false }` with the loss severity and reason.
+*/
 function decodePdfImage(file, stream) {
 	const d = stream.dict;
 	const width = intOf(file.get(d, "Width")) || intOf(file.get(d, "W"));

package/dist/esm/pdf-reader/images.d.ts

@@ -1,16 +1,35 @@
 import { Loss } from '../core/ir/index.js';
 import { PdfFile, PdfPage } from './document.js';
+/**
+ * One raster image lifted off a page (E-PDF EP6): the standalone image file
+ * (`png`/`jpeg`/`jpeg2000`), its page-space rectangle (computed from the CTM
+ * that maps the unit square) and the enclosing marked-content id so the tagged
+ * path can attach it to a `/Figure`.
+ */
 export interface PdfImage {
     readonly bytes: Uint8Array;
     readonly format: 'png' | 'jpeg' | 'jpeg2000';
+    /** Display size in page points (from the CTM). */
     readonly widthPt: number;
     readonly heightPt: number;
+    /** Page-space lower-left corner (points, y-up). */
     readonly x: number;
     readonly y: number;
+    /** Enclosing marked-content id, if the placement was inside a `/Figure`. */
     readonly mcid?: number;
 }
+/** The images lifted off one page plus any losses for images that could not be reconstructed. */
 export interface PageImages {
     readonly images: Array<PdfImage>;
     readonly losses: Array<Loss>;
 }
+/**
+ * Lift the raster images off a page (E-PDF EP6). Runs the content interpreter
+ * (EP2) for its `Do` placements, resolves each name against the page's
+ * `/Resources` `/XObject`, and either decodes an `/Image` (via `decodePdfImage`)
+ * or recurses into a `/Form` XObject — composing the form's `/Matrix` onto the
+ * placement CTM, depth-guarded against cyclic forms. Each surviving image
+ * carries its page-space rectangle and enclosing structure id. Unsupported
+ * images become {@link Loss} entries rather than broken pictures.
+ */
 export declare function collectPageImages(file: PdfFile, page: PdfPage): PageImages;

package/dist/esm/pdf-reader/images.js

@@ -6,6 +6,15 @@ import { decodePdfImage } from "./image-decode.js";
 var NO_FONTS = /* @__PURE__ */ new Map();
 var MAX_FORM_DEPTH = 12;
 var MAX_IMAGES = 4096;
+/**
+* Lift the raster images off a page (E-PDF EP6). Runs the content interpreter
+* (EP2) for its `Do` placements, resolves each name against the page's
+* `/Resources` `/XObject`, and either decodes an `/Image` (via `decodePdfImage`)
+* or recurses into a `/Form` XObject — composing the form's `/Matrix` onto the
+* placement CTM, depth-guarded against cyclic forms. Each surviving image
+* carries its page-space rectangle and enclosing structure id. Unsupported
+* images become {@link Loss} entries rather than broken pictures.
+*/
 function collectPageImages(file, page) {
 	const images = [];
 	const lossByDetail = /* @__PURE__ */ new Map();

package/dist/esm/pdf-reader/layout.d.ts

@@ -1,3 +1,18 @@
 import { PdfFile } from './document.js';
 import { Reconstruction } from './flow-build.js';
+/**
+ * Heuristically reconstruct an untagged PDF into a {@link Reconstruction}
+ * (E-PDF EP4). With no structure tree there is only positioned content, so
+ * reading order is recovered the way a human eye does: split a clean two-column
+ * page at its central gutter (EP17), then within each column cluster runs
+ * sharing a baseline into lines, order each line left-to-right inserting spaces
+ * across gaps, group lines into paragraphs by their vertical spacing, and
+ * interleave the column's images and filled vector paths (EP10) by their top
+ * edge. Each run's `href` is carried through as a span so links survive, and a
+ * font size well above the document median is guessed as a heading. The result
+ * is inherently approximate.
+ *
+ * @param file The PDF to reconstruct.
+ * @returns The reconstructed {@link FlowDoc} plus any read-time losses.
+ */
 export declare function reconstructByLayout(file: PdfFile): Reconstruction;

package/dist/esm/pdf-reader/layout.js

@@ -1,9 +1,24 @@
 import { ResourceStore } from "../core/ir/resources.js";
-import { buildFlowDoc, dedupeLosses, imageBlock, paragraphFromRuns, shapeBlock } from "./flow-build.js";
+import { buildFlowDoc, dedupeLosses, imageBlock, paragraphFromRuns, sectionFromPdfPages, shapeBlock } from "./flow-build.js";
 import { collectPageImages } from "./images.js";
 import { extractPageText } from "./text.js";
 import { collectPageVectors } from "./vector.js";
 //#region src/pdf-reader/layout.ts
+/**
+* Heuristically reconstruct an untagged PDF into a {@link Reconstruction}
+* (E-PDF EP4). With no structure tree there is only positioned content, so
+* reading order is recovered the way a human eye does: split a clean two-column
+* page at its central gutter (EP17), then within each column cluster runs
+* sharing a baseline into lines, order each line left-to-right inserting spaces
+* across gaps, group lines into paragraphs by their vertical spacing, and
+* interleave the column's images and filled vector paths (EP10) by their top
+* edge. Each run's `href` is carried through as a span so links survive, and a
+* font size well above the document median is guessed as a heading. The result
+* is inherently approximate.
+*
+* @param file The PDF to reconstruct.
+* @returns The reconstructed {@link FlowDoc} plus any read-time losses.
+*/
 function reconstructByLayout(file) {
 	const pages = file.pages();
 	const pageRuns = pages.map((page) => extractPageText(file, page));
@@ -45,7 +60,7 @@ function reconstructByLayout(file) {
 		for (const block of blocks) body.push(block.el);
 	});
 	return {
-		doc: buildFlowDoc(body, resources),
+		doc: buildFlowDoc(body, resources, sectionFromPdfPages(pages)),
 		losses: dedupeLosses(losses)
 	};
 }

package/dist/esm/pdf-reader/lexer.d.ts

@@ -1,3 +1,8 @@
+/**
+ * One COS lexical token (ISO 32000-1 §7.2/§7.3): a number, name, string (literal
+ * or hex), an array/dictionary delimiter, a bare keyword (`obj` / `R` / `stream`
+ * / `true` / …), or end-of-input.
+ */
 export type Token = {
     readonly kind: 'num';
     readonly value: number;
@@ -24,20 +29,58 @@ export type Token = {
 } | {
     readonly kind: 'eof';
 };
+/**
+ * COS lexer (ISO 32000-1 §7.2/§7.3): scans a PDF byte buffer into a stream of
+ * {@link Token}s. The parser drives it with look-ahead to recover the object
+ * grammar. `pos` is the public cursor; callers (and the parser's rewind logic)
+ * read and assign it directly.
+ */
 export declare class Lexer {
     private readonly buf;
     pos: number;
+    /**
+     * @param buf The PDF byte buffer to tokenize.
+     * @param pos The starting byte offset (defaults to the start of the buffer).
+     */
     constructor(buf: Uint8Array, pos?: number);
+    /** The length of the underlying byte buffer. */
     get length(): number;
+    /** The byte at index `i`, or −1 when out of range. */
     byteAt(i: number): number;
+    /** §7.2.3 — skip whitespace and `%`-to-end-of-line comments. */
     skipWhitespace(): void;
+    /** Read and consume the next {@link Token} from the current position. */
     nextToken(): Token;
+    /** Read a numeric token (optional sign, digits and a decimal point). */
     private readNumber;
+    /** Read a `/Name` token, decoding `#XX` hex escapes (§7.3.5). */
     private readName;
+    /** Read a bare keyword token: a run of regular bytes (`obj`, `R`, `true`, …). */
     private readKeyword;
+    /** Read a `<…>` hex string (§7.3.4.3); an odd trailing digit takes a low nibble of 0. */
     private readHexString;
+    /**
+     * Read a `(…)` literal string (§7.3.4.2): handles nested parentheses, backslash
+     * escapes and octal codes. The bytes are decoded latin1.
+     */
     private readLiteralString;
+    /**
+     * First index of an ASCII `needle` at or after `from` (−1 if none). Used to find
+     * `endstream` when a stream's `/Length` is missing or an unresolved reference.
+     */
     indexOfAscii(needle: string, from: number): number;
+    /**
+     * §7.3.8.1 — read a stream's raw bytes. `pos` must sit right after the `stream`
+     * keyword. The keyword is followed by CRLF (or a lone LF); the data then runs
+     * for `length` bytes, or — when the length is unknown — up to `endstream`.
+     * Leaves `pos` at the `endstream` keyword.
+     */
     readStreamBody(length: number | undefined): Uint8Array;
 }
+/**
+ * Bytes → a Latin-1 (ISO-8859-1) string: each byte becomes the code point of the
+ * same value, so the string round-trips back to the exact bytes. PDF text in
+ * strings is decoded to Unicode later (via the font's `/ToUnicode`); at the COS
+ * layer a string is just bytes.
+ */
 export declare function latin1(bytes: Uint8Array): string;

package/dist/esm/pdf-reader/lexer.js

@@ -14,18 +14,31 @@ function hexVal(b) {
 	if (b >= 97 && b <= 102) return b - 97 + 10;
 	return -1;
 }
+/**
+* COS lexer (ISO 32000-1 §7.2/§7.3): scans a PDF byte buffer into a stream of
+* {@link Token}s. The parser drives it with look-ahead to recover the object
+* grammar. `pos` is the public cursor; callers (and the parser's rewind logic)
+* read and assign it directly.
+*/
 var Lexer = class {
 	pos;
+	/**
+	* @param buf The PDF byte buffer to tokenize.
+	* @param pos The starting byte offset (defaults to the start of the buffer).
+	*/
 	constructor(buf, pos = 0) {
 		this.buf = buf;
 		this.pos = pos;
 	}
+	/** The length of the underlying byte buffer. */
 	get length() {
 		return this.buf.length;
 	}
+	/** The byte at index `i`, or −1 when out of range. */
 	byteAt(i) {
 		return i >= 0 && i < this.buf.length ? this.buf[i] : -1;
 	}
+	/** §7.2.3 — skip whitespace and `%`-to-end-of-line comments. */
 	skipWhitespace() {
 		const buf = this.buf;
 		while (this.pos < buf.length) {
@@ -37,6 +50,7 @@ var Lexer = class {
 			} else break;
 		}
 	}
+	/** Read and consume the next {@link Token} from the current position. */
 	nextToken() {
 		this.skipWhitespace();
 		const buf = this.buf;
@@ -77,6 +91,7 @@ var Lexer = class {
 		this.pos++;
 		return this.nextToken();
 	}
+	/** Read a numeric token (optional sign, digits and a decimal point). */
 	readNumber() {
 		const buf = this.buf;
 		const start = this.pos;
@@ -93,6 +108,7 @@ var Lexer = class {
 			value: Number.isFinite(value) ? value : 0
 		};
 	}
+	/** Read a `/Name` token, decoding `#XX` hex escapes (§7.3.5). */
 	readName() {
 		const buf = this.buf;
 		this.pos++;
@@ -117,6 +133,7 @@ var Lexer = class {
 			value: latin1(Uint8Array.from(out))
 		};
 	}
+	/** Read a bare keyword token: a run of regular bytes (`obj`, `R`, `true`, …). */
 	readKeyword() {
 		const buf = this.buf;
 		const start = this.pos;
@@ -126,6 +143,7 @@ var Lexer = class {
 			value: latin1(buf.subarray(start, this.pos))
 		};
 	}
+	/** Read a `<…>` hex string (§7.3.4.3); an odd trailing digit takes a low nibble of 0. */
 	readHexString() {
 		const buf = this.buf;
 		this.pos++;
@@ -149,6 +167,10 @@ var Lexer = class {
 			bytes: Uint8Array.from(out)
 		};
 	}
+	/**
+	* Read a `(…)` literal string (§7.3.4.2): handles nested parentheses, backslash
+	* escapes and octal codes. The bytes are decoded latin1.
+	*/
 	readLiteralString() {
 		const buf = this.buf;
 		this.pos++;
@@ -212,6 +234,10 @@ var Lexer = class {
 			value: latin1(Uint8Array.from(out))
 		};
 	}
+	/**
+	* First index of an ASCII `needle` at or after `from` (−1 if none). Used to find
+	* `endstream` when a stream's `/Length` is missing or an unresolved reference.
+	*/
 	indexOfAscii(needle, from) {
 		const buf = this.buf;
 		const n = needle.length;
@@ -221,6 +247,12 @@ var Lexer = class {
 		}
 		return -1;
 	}
+	/**
+	* §7.3.8.1 — read a stream's raw bytes. `pos` must sit right after the `stream`
+	* keyword. The keyword is followed by CRLF (or a lone LF); the data then runs
+	* for `length` bytes, or — when the length is unknown — up to `endstream`.
+	* Leaves `pos` at the `endstream` keyword.
+	*/
 	readStreamBody(length) {
 		const buf = this.buf;
 		if (buf[this.pos] === 13 && buf[this.pos + 1] === 10) this.pos += 2;
@@ -241,6 +273,12 @@ var Lexer = class {
 		return buf.subarray(start, dataEnd);
 	}
 };
+/**
+* Bytes → a Latin-1 (ISO-8859-1) string: each byte becomes the code point of the
+* same value, so the string round-trips back to the exact bytes. PDF text in
+* strings is decoded to Unicode later (via the font's `/ToUnicode`); at the COS
+* layer a string is just bytes.
+*/
 function latin1(bytes) {
 	let s = "";
 	for (const b of bytes) s += String.fromCharCode(b);

package/dist/esm/pdf-reader/parser.d.ts

@@ -1,10 +1,25 @@
 import { Lexer } from './lexer.js';
 import { PdfValue, PdfRef } from '../pdf/objects.js';
+/**
+ * Resolves an indirect-reference `/Length` to its numeric value. When a stream's
+ * `/Length` is an indirect reference it cannot be resolved while parsing the
+ * object in isolation; the document layer passes a resolver. Without one the
+ * parser falls back to scanning for `endstream`.
+ */
 export type LengthResolver = (ref: PdfRef) => number | undefined;
+/** A parsed `N G obj … endobj` definition: its id, generation and contained value. */
 export interface IndirectObject {
     readonly id: number;
     readonly generation: number;
     readonly value: PdfValue;
 }
+/** Parse one object value at the lexer's current position. */
 export declare function parseObject(lexer: Lexer, resolveLength?: LengthResolver): PdfValue;
+/**
+ * Parse an `N G obj … endobj` definition (the lexer must sit at the leading
+ * integer).
+ *
+ * @returns The {@link IndirectObject} (id, generation and contained value), or
+ *          `undefined` when the `N G obj` header does not parse.
+ */
 export declare function parseIndirectObject(lexer: Lexer, resolveLength?: LengthResolver): IndirectObject | undefined;

package/dist/esm/pdf-reader/parser.js

@@ -1,8 +1,16 @@
 import { PDF_NULL, PdfHexString, PdfName, PdfRef, PdfStream } from "../pdf/objects.js";
 //#region src/pdf-reader/parser.ts
+/** Parse one object value at the lexer's current position. */
 function parseObject(lexer, resolveLength) {
 	return parseValue(lexer, lexer.nextToken(), resolveLength);
 }
+/**
+* Parse an `N G obj … endobj` definition (the lexer must sit at the leading
+* integer).
+*
+* @returns The {@link IndirectObject} (id, generation and contained value), or
+*          `undefined` when the `N G obj` header does not parse.
+*/
 function parseIndirectObject(lexer, resolveLength) {
 	const idTok = lexer.nextToken();
 	if (idTok.kind !== "num") return void 0;

package/dist/esm/pdf-reader/png-encode.d.ts

@@ -1,2 +1,11 @@
+/** A PNG colour type: `gray` = 1ch, `rgb` = 3ch, `gray-alpha` = 2ch, `rgba` = 4ch. */
 export type PngColor = 'gray' | 'rgb' | 'gray-alpha' | 'rgba';
+/**
+ * Wrap raw 8-bit samples into a minimal PNG file (RFC 2083): a single `IDAT`
+ * with filter-none scanlines, no interlacing, colour types 0/2/4/6. Produces a
+ * format every writer already embeds — `detectImageFormat` recognises this
+ * output (the HTML data-URI and docx media paths both rely on it).
+ *
+ * @param samples Row-major, 8-bit, `CHANNELS[color]` interleaved values per pixel.
+ */
 export declare function encodePng(width: number, height: number, color: PngColor, samples: Uint8Array): Uint8Array;

package/dist/esm/pdf-reader/png-encode.js

@@ -22,6 +22,14 @@ var SIGNATURE = Uint8Array.from([
 	26,
 	10
 ]);
+/**
+* Wrap raw 8-bit samples into a minimal PNG file (RFC 2083): a single `IDAT`
+* with filter-none scanlines, no interlacing, colour types 0/2/4/6. Produces a
+* format every writer already embeds — `detectImageFormat` recognises this
+* output (the HTML data-URI and docx media paths both rely on it).
+*
+* @param samples Row-major, 8-bit, `CHANNELS[color]` interleaved values per pixel.
+*/
 function encodePng(width, height, color, samples) {
 	const stride = width * CHANNELS[color];
 	const raw = new Uint8Array(height * (stride + 1));

package/dist/esm/pdf-reader/predictor.d.ts

@@ -1,7 +1,16 @@
+/** The `/DecodeParms` that parameterize a `/Predictor` (ISO 32000-1 §7.4.4.4). */
 export interface PredictorParams {
     readonly predictor: number;
     readonly colors: number;
     readonly bitsPerComponent: number;
     readonly columns: number;
 }
+/**
+ * Reverse a stream's `/Predictor` (ISO 32000-1 §7.4.4.4) after FlateDecode. Undoes
+ * a PNG predictor (`/Predictor` ≥ 10, each row prefixed with a filter-type byte:
+ * None/Sub/Up/Average/Paeth) or TIFF horizontal differencing (`/Predictor` 2,
+ * 8-bit components only). Shared by image XObjects (image-decode.ts) and
+ * cross-reference / object streams (document.ts). A `/Predictor` < 2, or
+ * unsupported parameters, returns the data unchanged.
+ */
 export declare function reversePredictor(data: Uint8Array, p: PredictorParams): Uint8Array;

package/dist/esm/pdf-reader/predictor.js

@@ -1,4 +1,12 @@
 //#region src/pdf-reader/predictor.ts
+/**
+* Reverse a stream's `/Predictor` (ISO 32000-1 §7.4.4.4) after FlateDecode. Undoes
+* a PNG predictor (`/Predictor` ≥ 10, each row prefixed with a filter-type byte:
+* None/Sub/Up/Average/Paeth) or TIFF horizontal differencing (`/Predictor` 2,
+* 8-bit components only). Shared by image XObjects (image-decode.ts) and
+* cross-reference / object streams (document.ts). A `/Predictor` < 2, or
+* unsupported parameters, returns the data unchanged.
+*/
 function reversePredictor(data, p) {
 	if (p.predictor < 2) return data;
 	const bpp = Math.max(1, Math.ceil(p.colors * p.bitsPerComponent / 8));

package/dist/esm/pdf-reader/reader.d.ts

@@ -1,4 +1,20 @@
 import { DocumentReader, ReadResult } from '../core/ir/adapters.js';
 import { FlowDoc } from '../core/ir/flow.js';
+/**
+ * Parse PDF bytes into a {@link FlowDoc} (E-PDF EP5): reconstruct via the tagged
+ * structure tree when present (EP3), else the layout heuristic (EP4), lifting
+ * raster images back into reading order (EP6). Records losses for encryption that
+ * could not be opened, heuristic (untagged) reconstruction, and the vector
+ * regions that are not reconstructed (clipping paths, bare `sh` shadings).
+ *
+ * @param bytes    The complete PDF file bytes.
+ * @param password The user password for an encrypted source; the empty string
+ *                 opens permissions-only encryption.
+ * @returns The reconstructed FlowDoc and its accumulated {@link Loss} report.
+ */
 export declare function readPdf(bytes: Uint8Array, password?: string): ReadResult<FlowDoc>;
+/**
+ * The `pdfReader` adapter: a {@link DocumentReader} that sniffs the `%PDF-`
+ * header and parses the bytes into a {@link FlowDoc} (E-PDF EP5).
+ */
 export declare const pdfReader: DocumentReader<FlowDoc>;

package/dist/esm/pdf-reader/reader.js

@@ -8,6 +8,18 @@ function sniffPdf(bytes) {
 	for (let i = 0; i <= limit; i++) if (bytes[i] === 37 && bytes[i + 1] === 80 && bytes[i + 2] === 68 && bytes[i + 3] === 70 && bytes[i + 4] === 45) return true;
 	return false;
 }
+/**
+* Parse PDF bytes into a {@link FlowDoc} (E-PDF EP5): reconstruct via the tagged
+* structure tree when present (EP3), else the layout heuristic (EP4), lifting
+* raster images back into reading order (EP6). Records losses for encryption that
+* could not be opened, heuristic (untagged) reconstruction, and the vector
+* regions that are not reconstructed (clipping paths, bare `sh` shadings).
+*
+* @param bytes    The complete PDF file bytes.
+* @param password The user password for an encrypted source; the empty string
+*                 opens permissions-only encryption.
+* @returns The reconstructed FlowDoc and its accumulated {@link Loss} report.
+*/
 function readPdf(bytes, password = "") {
 	const file = PdfFile.parse(bytes, password);
 	const losses = [];
@@ -34,6 +46,10 @@ function readPdf(bytes, password = "") {
 		losses
 	};
 }
+/**
+* The `pdfReader` adapter: a {@link DocumentReader} that sniffs the `%PDF-`
+* header and parses the bytes into a {@link FlowDoc} (E-PDF EP5).
+*/
 var pdfReader = {
 	id: "pdf",
 	produces: "flow",

package/dist/esm/pdf-reader/shading.d.ts

@@ -1,3 +1,13 @@
 import { ShapeGradient } from '../core/vector.js';
 import { PdfFile, PdfPage } from './document.js';
+/**
+ * Resolve a page's `/Pattern` resources into gradient fills (E-PDF EP16c, ISO
+ * 32000-1 §8.7.4.5). Every `PatternType` 2 (shading) pattern is evaluated — its
+ * `/Shading` type 2 (axial) or 3 (radial) plus the `/Function` colour stops —
+ * and keyed by resource name; the interpreter looks the name up when a shape is
+ * filled with `/Pattern cs /Pn scn`. The bare `sh` operator (clip-bounded) is
+ * not captured.
+ *
+ * @returns A map from pattern resource name to its {@link ShapeGradient}.
+ */
 export declare function buildShadingMap(file: PdfFile, page: PdfPage): Map<string, ShapeGradient>;

package/dist/esm/pdf-reader/shading.js

@@ -1,5 +1,15 @@
 import { PDF_NULL, PdfStream } from "../pdf/objects.js";
 //#region src/pdf-reader/shading.ts
+/**
+* Resolve a page's `/Pattern` resources into gradient fills (E-PDF EP16c, ISO
+* 32000-1 §8.7.4.5). Every `PatternType` 2 (shading) pattern is evaluated — its
+* `/Shading` type 2 (axial) or 3 (radial) plus the `/Function` colour stops —
+* and keyed by resource name; the interpreter looks the name up when a shape is
+* filled with `/Pattern cs /Pn scn`. The bare `sh` operator (clip-bounded) is
+* not captured.
+*
+* @returns A map from pattern resource name to its {@link ShapeGradient}.
+*/
 function buildShadingMap(file, page) {
 	const out = /* @__PURE__ */ new Map();
 	if (!page.resources) return out;

package/dist/esm/pdf-reader/struct-tree.d.ts

@@ -1,14 +1,38 @@
 import { PdfFile } from './document.js';
+/** A marked-content reference: a page index plus an MCID on that page. */
 export interface StructMcid {
+    /** Zero-based page index the MCID lives on. */
     readonly page: number;
     readonly mcid: number;
 }
+/**
+ * One node of the recovered logical structure tree (ISO 32000-1 §14.7): a
+ * `/StructElem`'s role, its own marked-content references (the text it owns) and
+ * its child elements.
+ */
 export interface StructNode {
+    /** The `/S` role name (`Document`, `P`, `H1`, `Table`, `TR`, `TD`, `L`, `LI`, …). */
     readonly type: string;
+    /** The element's own marked content, linking it to interpreter-extracted text (EP2). */
     readonly mcids: ReadonlyArray<StructMcid>;
     readonly children: ReadonlyArray<StructNode>;
+    /** `/Alt` — alternate text (figures). */
     readonly alt?: string;
+    /** `/A /Table /ColSpan` on a table cell. */
     readonly colSpan?: number;
+    /** `/A /Table /RowSpan` on a table cell. */
     readonly rowSpan?: number;
 }
+/**
+ * Read the `/StructTreeRoot` (ISO 32000-1 §14.7) into a {@link StructNode} tree,
+ * recovering reading order and roles. Walks each `/StructElem`'s `/K` children —
+ * resolving nested elements, bare-integer and `/MCR` marked-content references
+ * (carrying the owning page), and skipping `/OBJR` object references (no text) —
+ * guards against cycles and pathological size, and lifts `/Alt` plus table cell
+ * `/ColSpan`/`/RowSpan`. Multiple top-level roots are wrapped in a synthetic
+ * `Document` node.
+ *
+ * @returns The structure-tree root, or `undefined` when the catalog has no
+ *          `/StructTreeRoot` (an untagged PDF).
+ */
 export declare function readStructTree(file: PdfFile): StructNode | undefined;

package/dist/esm/pdf-reader/struct-tree.js

@@ -1,6 +1,18 @@
 import { PDF_NULL, PdfName } from "../pdf/objects.js";
 //#region src/pdf-reader/struct-tree.ts
 var MAX_NODES = 2e5;
+/**
+* Read the `/StructTreeRoot` (ISO 32000-1 §14.7) into a {@link StructNode} tree,
+* recovering reading order and roles. Walks each `/StructElem`'s `/K` children —
+* resolving nested elements, bare-integer and `/MCR` marked-content references
+* (carrying the owning page), and skipping `/OBJR` object references (no text) —
+* guards against cycles and pathological size, and lifts `/Alt` plus table cell
+* `/ColSpan`/`/RowSpan`. Multiple top-level roots are wrapped in a synthetic
+* `Document` node.
+*
+* @returns The structure-tree root, or `undefined` when the catalog has no
+*          `/StructTreeRoot` (an untagged PDF).
+*/
 function readStructTree(file) {
 	const stRoot = file.get(file.catalog, "StructTreeRoot");
 	if (!(stRoot instanceof Map)) return void 0;

package/dist/esm/pdf-reader/tagged.d.ts

@@ -1,3 +1,16 @@
 import { PdfFile } from './document.js';
 import { Reconstruction } from './flow-build.js';
+/**
+ * Reconstruct a {@link Reconstruction} from a tagged PDF's logical structure
+ * (E-PDF EP3 — the honest inverse of the tagged PDF Ream writes). Walks the
+ * structure tree ({@link readStructTree}), pulls each element's text from the
+ * per-page MCID → text map the content interpreter produced (EP2), and rebuilds
+ * headings (`H1`–`H6` → outline level), paragraphs, tables (`Table` → `TR` →
+ * `TH`/`TD`), list items (each `LI` → label + body) and figures (EP6 — each
+ * `/Figure`'s MCID resolves to a lifted image carrying its `/Alt`). Images no
+ * `/Figure` claims are appended in page + top-down order so nothing is lost.
+ *
+ * @returns The reconstructed document and image losses, or `undefined` when the
+ *          PDF carries no structure tree or yields no body content.
+ */
 export declare function reconstructTaggedPdf(file: PdfFile): Reconstruction | undefined;