reamkit 1.15.0 → 1.15.2

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

@@ -1,4 +1,14 @@
 //#region src/pdf-reader/ccitt.ts
+/**
+* Decode a CCITT Group 3 / Group 4 fax stream into a packed 1-bit-per-pixel
+* bitmap.
+*
+* @param data   The raw fax codestream (any wrapping filters already stripped).
+* @param params The `/CCITTFaxDecode` parameters.
+* @returns The packed bitmap (`rowBytes × rows`, bit 1 = black, MSB first), or
+*   `undefined` when the stream cannot be decoded (e.g. Group 3 2-D, or nothing
+*   decoded at all).
+*/
 function decodeCcitt(data, params) {
 	const { k, columns, rows, byteAlign } = params;
 	if (k > 0) return void 0;
@@ -136,6 +146,11 @@ var BitReader = class {
 		}
 	}
 };
+/**
+* T.4 white-run modified-Huffman codes as `[run, bit-string]` (terminating runs
+* 0..63, make-up runs multiples of 64). Exported so the test can build an
+* independent encoder and validate the codes form a valid prefix set.
+*/
 var WHITE_CODES = [
 	[0, "00110101"],
 	[1, "000111"],

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

@@ -1,5 +1,17 @@
+/** A parsed `/ToUnicode` CMap: the code→Unicode mapping and the code width. */
 export interface ToUnicode {
+    /** Character code → Unicode string (a single code may map to a ligature). */
     readonly map: ReadonlyMap<number, string>;
+    /** Whether character codes are one or two bytes wide (from `codespacerange`). */
     readonly codeBytes: 1 | 2;
 }
+/**
+ * Parse a `/ToUnicode` CMap (ISO 32000-1 §9.10.3) into a code→Unicode map. Reads
+ * the `codespacerange` (code width), `bfchar` (single codes) and `bfrange`
+ * (contiguous ranges, scalar or array destination) blocks; everything else is
+ * ignored.
+ *
+ * @param bytes The decoded CMap stream.
+ * @returns The mapping plus the declared code width (1 or 2 bytes).
+ */
 export declare function parseToUnicodeCMap(bytes: Uint8Array): ToUnicode;

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

@@ -1,6 +1,15 @@
 import { Lexer } from "./lexer.js";
 //#region src/pdf-reader/cmap.ts
 var MAX_RANGE = 65536;
+/**
+* Parse a `/ToUnicode` CMap (ISO 32000-1 §9.10.3) into a code→Unicode map. Reads
+* the `codespacerange` (code width), `bfchar` (single codes) and `bfrange`
+* (contiguous ranges, scalar or array destination) blocks; everything else is
+* ignored.
+*
+* @param bytes The decoded CMap stream.
+* @returns The mapping plus the declared code width (1 or 2 bytes).
+*/
 function parseToUnicodeCMap(bytes) {
 	const lexer = new Lexer(bytes);
 	const map = /* @__PURE__ */ new Map();

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

@@ -1,23 +1,57 @@
 import { ShapeGradient } from '../core/vector.js';
+/**
+ * A page font as the interpreter needs it (built from the font dictionaries in
+ * EP2b): how wide each code is, and how a run of codes decodes to Unicode. An
+ * unmapped font falls back to Latin-1 with a half-em advance so text still
+ * surfaces.
+ */
 export interface ContentFont {
+    /** Bytes per character code: simple fonts read 1 byte/code, Type0 reads 2. */
     readonly bytesPerCode: 1 | 2;
+    /** Decode a sequence of character codes to a Unicode string. */
     decode: (codes: ReadonlyArray<number>) => string;
+    /** Glyph advance for one code, in 1000-unit text space. */
     width: (code: number) => number;
 }
+/**
+ * One positioned text run emitted by a show operator: its decoded text, the
+ * glyph origin in page space and the effective font size — the raw material a
+ * later stage groups into lines and paragraphs.
+ */
 export interface TextRun {
     readonly text: string;
+    /** Glyph origin x in page space (points). */
     readonly x: number;
+    /** Glyph origin y in page space (points). */
     readonly y: number;
     readonly fontSizePt: number;
     readonly fontKey: string;
+    /**
+     * The marked-content id of the enclosing `BDC` sequence (§14.6), if any — the
+     * link from this text to the structure element that owns it (E-PDF EP3).
+     */
     readonly mcid?: number;
+    /**
+     * A `/Link` annotation whose `/Rect` covers this run's origin attaches its URI
+     * here (E-PDF EP8), so the reconstructed run carries the hyperlink.
+     */
     readonly href?: string;
 }
+/**
+ * A painted XObject (`/Name Do`, §8.8) — an image or form. The CTM maps the unit
+ * square to page space, so it carries both the placement and the size; the
+ * `mcid` links the paint to its structure element (a `/Figure`, E-PDF EP6).
+ */
 export interface ImagePlacement {
+    /** XObject resource name (no leading slash). */
     readonly name: string;
     readonly ctm: Matrix;
     readonly mcid?: number;
 }
+/**
+ * One segment of a painted path (E-PDF EP10/EP11), in page space (y-up): a
+ * `move`/`line`/`cubic` Bézier point or a subpath `close`.
+ */
 export type PathSeg = {
     readonly op: 'move';
     readonly x: number;
@@ -37,20 +71,55 @@ export type PathSeg = {
 } | {
     readonly op: 'close';
 };
+/**
+ * A painted path emitted by the path-painting operators (§8.5.3), captured in
+ * page space (y-up). The optional fields record only what the paint mode set:
+ * a fill colour/gradient (EP10/EP16c) and/or a stroke colour + width (EP11),
+ * plus the enclosing structure id.
+ */
 export interface VectorPlacement {
     readonly segs: ReadonlyArray<PathSeg>;
+    /** Fill colour (6-hex), present iff the path is filled (`f` / `F` / `f*` / `B` / `b`). */
     readonly fillHex?: string;
+    /** Shading pattern, present iff filled with one (EP16c). */
     readonly gradient?: ShapeGradient;
+    /** Stroke colour (6-hex), present iff the path is stroked (`S` / `s` / `B` / `b`) — EP11. */
     readonly strokeHex?: string;
+    /** Stroke width in page-space points — EP11. */
     readonly lineWidth?: number;
     readonly mcid?: number;
 }
+/** Everything {@link interpretContent} extracts from one page's content stream. */
 export interface InterpretResult {
     readonly texts: Array<TextRun>;
     readonly images: Array<ImagePlacement>;
     readonly vectors: Array<VectorPlacement>;
 }
+/**
+ * 2D affine matrix `[a b c d e f]`, row-vector convention (`[x y 1] · M`):
+ * ```
+ * ⎡a b 0⎤
+ * ⎢c d 0⎥
+ * ⎣e f 1⎦
+ * ```
+ */
 export type Matrix = readonly [number, number, number, number, number, number];
+/** The identity {@link Matrix} (no transform). */
 export declare const IDENTITY: Matrix;
+/** Compose two {@link Matrix matrices}: `a` applied first, then `b`. */
 export declare function multiply(a: Matrix, b: Matrix): Matrix;
+/**
+ * Walk a page's decoded content stream (§9.4) and extract its positioned text,
+ * painted XObjects and painted paths. Tracks the graphics state (CTM via
+ * `q`/`Q`/`cm`) and text state (text/line matrices, font, size, spacing), and
+ * emits one {@link TextRun} per show operator (`Tj` / `TJ` / `'` / `"`) in page
+ * space (points).
+ *
+ * @param bytes      The page's decoded content-stream bytes.
+ * @param fonts      Page fonts by resource key (`Tf` name), for decoding + widths;
+ *                   an unmapped key falls back to Latin-1 with a half-em advance.
+ * @param initialCtm The starting CTM mapping user space to page space.
+ * @param shadings   Shading patterns by name, selected by `scn`/`sc` (EP16c).
+ * @returns The extracted text runs, image placements and vector paths.
+ */
 export declare function interpretContent(bytes: Uint8Array, fonts: ReadonlyMap<string, ContentFont>, initialCtm?: Matrix, shadings?: ReadonlyMap<string, ShapeGradient>): InterpretResult;

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

@@ -1,6 +1,7 @@
 import { PDF_NULL, PdfHexString, PdfName } from "../pdf/objects.js";
 import { Lexer } from "./lexer.js";
 //#region src/pdf-reader/content.ts
+/** The identity {@link Matrix} (no transform). */
 var IDENTITY = [
 	1,
 	0,
@@ -9,6 +10,7 @@ var IDENTITY = [
 	0,
 	0
 ];
+/** Compose two {@link Matrix matrices}: `a` applied first, then `b`. */
 function multiply(a, b) {
 	return [
 		a[0] * b[0] + a[1] * b[2],
@@ -51,6 +53,20 @@ function initialState() {
 		fillGradient: void 0
 	};
 }
+/**
+* Walk a page's decoded content stream (§9.4) and extract its positioned text,
+* painted XObjects and painted paths. Tracks the graphics state (CTM via
+* `q`/`Q`/`cm`) and text state (text/line matrices, font, size, spacing), and
+* emits one {@link TextRun} per show operator (`Tj` / `TJ` / `'` / `"`) in page
+* space (points).
+*
+* @param bytes      The page's decoded content-stream bytes.
+* @param fonts      Page fonts by resource key (`Tf` name), for decoding + widths;
+*                   an unmapped key falls back to Latin-1 with a half-em advance.
+* @param initialCtm The starting CTM mapping user space to page space.
+* @param shadings   Shading patterns by name, selected by `scn`/`sc` (EP16c).
+* @returns The extracted text runs, image placements and vector paths.
+*/
 function interpretContent(bytes, fonts, initialCtm = IDENTITY, shadings = /* @__PURE__ */ new Map()) {
 	const runs = [];
 	const images = [];

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

@@ -1,4 +1,9 @@
+/**
+ * RC4 stream cipher (§7.6.2). Symmetric, so the same call both encrypts and
+ * decrypts; used by the legacy V1/V2/V4 Standard security handlers.
+ */
 export declare function rc4(key: Uint8Array, data: Uint8Array): Uint8Array;
+/** MD5 digest (RFC 1321) → 16 bytes; the key-derivation hash for V1/V2/V4. */
 export declare function md5(input: Uint8Array): Uint8Array;
 export declare function sha256(input: Uint8Array): Uint8Array;
 export declare function sha512(input: Uint8Array): Uint8Array;

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

@@ -1,4 +1,8 @@
 //#region src/pdf-reader/crypto.ts
+/**
+* RC4 stream cipher (§7.6.2). Symmetric, so the same call both encrypts and
+* decrypts; used by the legacy V1/V2/V4 Standard security handlers.
+*/
 function rc4(key, data) {
 	const s = new Uint8Array(256);
 	for (let i = 0; i < 256; i++) s[i] = i;
@@ -85,6 +89,7 @@ var MD5_S = [
 	21
 ];
 var MD5_K = Array.from({ length: 64 }, (_, i) => Math.floor(Math.abs(Math.sin(i + 1)) * 4294967296));
+/** MD5 digest (RFC 1321) → 16 bytes; the key-derivation hash for V1/V2/V4. */
 function md5(input) {
 	const len = input.length;
 	const withOne = (len + 8 >> 6) + 1;

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

@@ -1,5 +1,22 @@
 import { PdfDict, PdfValue } from '../pdf/objects.js';
+/** Decrypts the strings and streams of an encrypted PDF, per indirect object. */
 export interface Decryptor {
+    /**
+     * Decrypt one value with its owning object's number and generation (which seed
+     * the per-object key). Recurses into arrays and dictionaries.
+     */
     decrypt: (value: PdfValue, objNum: number, gen: number) => PdfValue;
 }
+/**
+ * Build a {@link Decryptor} from the `/Encrypt` dictionary and the file `/ID`
+ * (ISO 32000 §7.6.3 / ISO 32000-2 §7.6.4). Derives the file key for the
+ * handler's revision — R6/V5 via `/UE` (AES-256), else the legacy MD5 key — and
+ * picks the cipher (RC4, AES-128 `/AESV2`, AES-256 `/AESV3`).
+ *
+ * @param encrypt  The `/Encrypt` dictionary.
+ * @param idArray  The trailer `/ID` array (its first element seeds the legacy key).
+ * @param password The user password (EP14); the empty string opens permissions-only encryption.
+ * @returns A decryptor, or `undefined` for a non-Standard filter, an unencrypting
+ *          crypt filter, or a password that fails key validation.
+ */
 export declare function buildDecryptor(encrypt: PdfDict, idArray: PdfValue | undefined, password?: string): Decryptor | undefined;

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

@@ -43,6 +43,18 @@ var AES_SALT = Uint8Array.from([
 ]);
 var ZERO16 = new Uint8Array(16);
 var EMPTY = new Uint8Array(0);
+/**
+* Build a {@link Decryptor} from the `/Encrypt` dictionary and the file `/ID`
+* (ISO 32000 §7.6.3 / ISO 32000-2 §7.6.4). Derives the file key for the
+* handler's revision — R6/V5 via `/UE` (AES-256), else the legacy MD5 key — and
+* picks the cipher (RC4, AES-128 `/AESV2`, AES-256 `/AESV3`).
+*
+* @param encrypt  The `/Encrypt` dictionary.
+* @param idArray  The trailer `/ID` array (its first element seeds the legacy key).
+* @param password The user password (EP14); the empty string opens permissions-only encryption.
+* @returns A decryptor, or `undefined` for a non-Standard filter, an unencrypting
+*          crypt filter, or a password that fails key validation.
+*/
 function buildDecryptor(encrypt, idArray, password = "") {
 	const filter = encrypt.get("Filter");
 	if (!(filter instanceof PdfName) || filter.value !== "Standard") return void 0;

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

@@ -1,10 +1,20 @@
 import { PdfArray, PdfDict, PdfValue, PdfStream } from '../pdf/objects.js';
+/** A PDF rectangle `[llx, lly, urx, ury]` in default user-space units (§7.9.5). */
 export type Rectangle = readonly [number, number, number, number];
+/** A resolved leaf page: its dictionary plus its inherited `/MediaBox` and `/Resources`. */
 export interface PdfPage {
     readonly dict: PdfDict;
     readonly mediaBox: Rectangle;
     readonly resources: PdfDict | undefined;
 }
+/**
+ * The document layer (E-PDF EP1/EP7): wraps a whole PDF byte buffer and exposes
+ * its objects — the cross-reference table (classic `xref` + `trailer` and
+ * cross-reference streams), cached indirect-reference resolution (including
+ * objects packed inside object streams), the page tree (walked with attribute
+ * inheritance), and stream decoding (FlateDecode + predictors). A brute-force
+ * object scan recovers files whose xref is broken. Construct via {@link PdfFile.parse}.
+ */
 export declare class PdfFile {
     private readonly buf;
     private readonly xref;
@@ -14,17 +24,60 @@ export declare class PdfFile {
     private decryptor;
     private encryptObjNum;
     private constructor();
+    /**
+     * Parse a whole PDF byte buffer: read the cross-reference chain (or brute-force
+     * recover a broken one) and initialize decryption from `/Encrypt` (§7.6).
+     *
+     * @param bytes    The complete PDF file bytes.
+     * @param password The user password for an encrypted source (EP14); the empty
+     *                 string opens permissions-only encryption.
+     * @returns A ready-to-query {@link PdfFile}.
+     */
     static parse(bytes: Uint8Array, password?: string): PdfFile;
+    /**
+     * Build the decryptor from `/Encrypt` (§7.6). Runs before any other object is
+     * resolved, so the `/Encrypt` dictionary itself is read in the clear; its object
+     * is then never decrypted.
+     */
     private initEncryption;
+    /** Resolve a stream's `/Length` when it is an indirect reference. */
     private readonly lengthResolver;
+    /**
+     * Dereference one level: a `PdfRef` becomes the object it points at (parsed and
+     * cached); any other value is returned unchanged. Decrypts each resolved
+     * string/stream (§7.6) except the `/Encrypt` dictionary itself, and guards
+     * against self-referential cycles.
+     */
     resolve(value: PdfValue): PdfValue;
+    /** Decode (once) the members of an object stream (§7.5.7) and return objNum → value. */
     private objectFromStream;
+    /** Resolve `dict[key]` in one step (look up then dereference). */
     get(dict: PdfDict, key: string): PdfValue;
+    /** The document catalog (`/Root`), or an empty dict when it cannot be resolved. */
     get catalog(): PdfDict;
+    /**
+     * The document is encrypted but no decryptor could be built (an unsupported
+     * handler, or a wrong/missing user password) — its content is unreadable.
+     */
     get encryptionUnsupported(): boolean;
+    /** The leaf pages, in document order, each with its inherited `/MediaBox` and `/Resources`. */
     pages(): Array<PdfPage>;
+    /**
+     * Recurse the `/Pages` tree, accumulating leaf pages into `out` with inherited
+     * `/MediaBox` and `/Resources`. Bounded by `MAX_PAGES` and a `seen` set (cycle
+     * guard).
+     */
     private walkPageTree;
+    /**
+     * A page's concatenated, decoded content stream bytes (`/Contents` may be a
+     * single stream or an array of streams joined with a separator, per §7.8.2).
+     */
     pageContent(page: PdfPage): Uint8Array;
+    /**
+     * Decode a stream's bytes, applying its `/Filter` chain (FlateDecode + any
+     * `/Predictor` supported; unknown filters pass through undecoded).
+     */
     streamData(stream: PdfStream): Uint8Array;
 }
+/** Re-export for callers that walk a resolved dict's array values. */
 export type { PdfArray };

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

@@ -13,6 +13,14 @@ var DEFAULT_MEDIA_BOX = [
 ];
 var MAX_PAGES = 5e4;
 var MAX_OBJSTM_N = 2e5;
+/**
+* The document layer (E-PDF EP1/EP7): wraps a whole PDF byte buffer and exposes
+* its objects — the cross-reference table (classic `xref` + `trailer` and
+* cross-reference streams), cached indirect-reference resolution (including
+* objects packed inside object streams), the page tree (walked with attribute
+* inheritance), and stream decoding (FlateDecode + predictors). A brute-force
+* object scan recovers files whose xref is broken. Construct via {@link PdfFile.parse}.
+*/
 var PdfFile = class PdfFile {
 	cache = /* @__PURE__ */ new Map();
 	objStmCache = /* @__PURE__ */ new Map();
@@ -23,6 +31,15 @@ var PdfFile = class PdfFile {
 		this.xref = xref;
 		this.trailer = trailer;
 	}
+	/**
+	* Parse a whole PDF byte buffer: read the cross-reference chain (or brute-force
+	* recover a broken one) and initialize decryption from `/Encrypt` (§7.6).
+	*
+	* @param bytes    The complete PDF file bytes.
+	* @param password The user password for an encrypted source (EP14); the empty
+	*                 string opens permissions-only encryption.
+	* @returns A ready-to-query {@link PdfFile}.
+	*/
 	static parse(bytes, password = "") {
 		let xref = /* @__PURE__ */ new Map();
 		let trailer = /* @__PURE__ */ new Map();
@@ -46,6 +63,11 @@ var PdfFile = class PdfFile {
 		file.initEncryption(password);
 		return file;
 	}
+	/**
+	* Build the decryptor from `/Encrypt` (§7.6). Runs before any other object is
+	* resolved, so the `/Encrypt` dictionary itself is read in the clear; its object
+	* is then never decrypted.
+	*/
 	initEncryption(password) {
 		const encVal = this.trailer.get("Encrypt");
 		if (encVal === void 0) return;
@@ -55,10 +77,17 @@ var PdfFile = class PdfFile {
 		const id = this.trailer.get("ID");
 		this.decryptor = buildDecryptor(enc, Array.isArray(id) ? id : void 0, password);
 	}
+	/** Resolve a stream's `/Length` when it is an indirect reference. */
 	lengthResolver = (r) => {
 		const n = this.resolve(r);
 		return typeof n === "number" ? n : void 0;
 	};
+	/**
+	* Dereference one level: a `PdfRef` becomes the object it points at (parsed and
+	* cached); any other value is returned unchanged. Decrypts each resolved
+	* string/stream (§7.6) except the `/Encrypt` dictionary itself, and guards
+	* against self-referential cycles.
+	*/
 	resolve(value) {
 		if (!(value instanceof PdfRef)) return value;
 		const cached = this.cache.get(value.id);
@@ -77,6 +106,7 @@ var PdfFile = class PdfFile {
 		this.cache.set(value.id, result);
 		return result;
 	}
+	/** Decode (once) the members of an object stream (§7.5.7) and return objNum → value. */
 	objectFromStream(streamObj) {
 		const cached = this.objStmCache.get(streamObj);
 		if (cached) return cached;
@@ -96,22 +126,34 @@ var PdfFile = class PdfFile {
 		for (const member of objStmHeader(data, numOf(this.resolve(stream.dict.get("N") ?? PDF_NULL)))) out.set(member.id, parseObject(new Lexer(data, first + member.off), this.lengthResolver));
 		return out;
 	}
+	/** Resolve `dict[key]` in one step (look up then dereference). */
 	get(dict, key) {
 		return this.resolve(dict.get(key) ?? PDF_NULL);
 	}
+	/** The document catalog (`/Root`), or an empty dict when it cannot be resolved. */
 	get catalog() {
 		const root = this.resolve(this.trailer.get("Root") ?? PDF_NULL);
 		return root instanceof Map ? root : /* @__PURE__ */ new Map();
 	}
+	/**
+	* The document is encrypted but no decryptor could be built (an unsupported
+	* handler, or a wrong/missing user password) — its content is unreadable.
+	*/
 	get encryptionUnsupported() {
 		return this.trailer.get("Encrypt") !== void 0 && this.decryptor === void 0;
 	}
+	/** The leaf pages, in document order, each with its inherited `/MediaBox` and `/Resources`. */
 	pages() {
 		const out = [];
 		const root = this.get(this.catalog, "Pages");
 		if (root instanceof Map) this.walkPageTree(root, {}, out, /* @__PURE__ */ new Set());
 		return out;
 	}
+	/**
+	* Recurse the `/Pages` tree, accumulating leaf pages into `out` with inherited
+	* `/MediaBox` and `/Resources`. Bounded by `MAX_PAGES` and a `seen` set (cycle
+	* guard).
+	*/
 	walkPageTree(node, inherited, out, seen) {
 		if (out.length >= MAX_PAGES || seen.has(node)) return;
 		seen.add(node);
@@ -137,6 +179,10 @@ var PdfFile = class PdfFile {
 			resources
 		});
 	}
+	/**
+	* A page's concatenated, decoded content stream bytes (`/Contents` may be a
+	* single stream or an array of streams joined with a separator, per §7.8.2).
+	*/
 	pageContent(page) {
 		const contents = this.get(page.dict, "Contents");
 		const streams = [];
@@ -147,6 +193,10 @@ var PdfFile = class PdfFile {
 		}
 		return concatWithSpaces(streams.map((s) => this.streamData(s)));
 	}
+	/**
+	* Decode a stream's bytes, applying its `/Filter` chain (FlateDecode + any
+	* `/Predictor` supported; unknown filters pass through undecoded).
+	*/
 	streamData(stream) {
 		let data = stream.data;
 		const filter = this.resolve(stream.dict.get("Filter") ?? PDF_NULL);

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

@@ -1,19 +1,68 @@
-import { BodyElement } from '../core/document-model/index.js';
+import { BodyElement, SectionProperties } from '../core/document-model/index.js';
 import { FlowDoc } from '../core/ir/flow.js';
 import { Loss, ResourceStore } from '../core/ir/index.js';
 import { PdfImage } from './images.js';
+import { PdfPage } from './document.js';
 import { PdfVector } from './vector.js';
+/**
+ * A reconstruction's document plus the losses incurred reading it (e.g. an
+ * undecodable image colour space) — surfaced through the reader's `LossReport`.
+ */
 export interface Reconstruction {
     readonly doc: FlowDoc;
     readonly losses: ReadonlyArray<Loss>;
 }
+/**
+ * Build a paragraph {@link BodyElement} from a single plain-text string,
+ * optionally at the given outline (heading) level. Empty text yields a
+ * paragraph with no runs. The link-free counterpart of {@link paragraphFromRuns}.
+ */
 export declare function paragraphBlock(text: string, outlineLevel?: number): BodyElement;
+/** One piece of reconstructed text, carrying any hyperlink (E-PDF EP8). */
 export interface TextSpan {
     readonly text: string;
     readonly href?: string;
 }
+/**
+ * Build a paragraph {@link BodyElement} from positioned {@link TextSpan}s,
+ * coalescing consecutive spans that share an `href` into one run (so a link
+ * survives as its own run) and squashing whitespace. With no hrefs this
+ * collapses to a single run — the same shape {@link paragraphBlock} produces.
+ */
 export declare function paragraphFromRuns(spans: ReadonlyArray<TextSpan>, outlineLevel?: number): BodyElement;
+/**
+ * Store a {@link PdfImage}'s bytes (content-addressed dedup) and build the image
+ * {@link BodyElement} that references them, sized in points from the placement
+ * CTM. `alt` becomes the block's alt text when given.
+ */
 export declare function imageBlock(image: PdfImage, resources: ResourceStore, alt?: string): BodyElement;
+/** Collapse losses sharing a `detail` message (the same colour space dropped on many pages). */
 export declare function dedupeLosses(losses: ReadonlyArray<Loss>): Array<Loss>;
+/**
+ * Turn a lifted {@link PdfVector} path (filled EP10 / stroked EP11) into a
+ * custom-geometry shape {@link BodyElement}. Page-space points (y-up) become
+ * path-space (bbox-relative, y-down); the shape is sized from the bounding box
+ * (plus the stroke thickness) and placed in flow order by the caller. A fill
+ * becomes a solid fill, a stroke becomes the outline.
+ */
 export declare function shapeBlock(v: PdfVector): BodyElement;
-export declare function buildFlowDoc(body: ReadonlyArray<BodyElement>, resources?: ResourceStore): FlowDoc;
+/**
+ * Derive the {@link SectionProperties} geometry from the source pages so a
+ * reconstructed PDF re-renders at its real page size and orientation rather than
+ * the layout engine's `A4` default — without it an `A3` source paginates onto
+ * several `A4` pages, a wide/landscape page is letterboxed, and so on. PDF
+ * user-space units are points, matching `Pt`, so the `MediaBox` extents map
+ * straight to the page size. Uses the first {@link PdfPage}'s box (the
+ * near-universal uniform-size case); a PDF whose pages differ in size reflows to
+ * this single geometry — a known approximation, still far better than a fixed
+ * `A4`. Returns `undefined` when there is no usable first-page box.
+ */
+export declare function sectionFromPdfPages(pages: ReadonlyArray<PdfPage>): SectionProperties | undefined;
+/**
+ * Assemble the final {@link FlowDoc} for a reconstruction: the body elements
+ * with their styles resolved against the empty style sheet, the lifted-image
+ * resource store, and the optional page {@link SectionProperties}. Shared by
+ * both reconstruction paths (the tagged fast-path EP3 and the heuristic layout
+ * path EP4).
+ */
+export declare function buildFlowDoc(body: ReadonlyArray<BodyElement>, resources?: ResourceStore, section?: SectionProperties): FlowDoc;

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

@@ -3,6 +3,11 @@ import { ResourceStore } from "../core/ir/resources.js";
 import { EMPTY_STYLE_SHEET, resolveBodyStyles } from "../core/style-cascade/resolver.js";
 import "../core/style-cascade/index.js";
 //#region src/pdf-reader/flow-build.ts
+/**
+* Build a paragraph {@link BodyElement} from a single plain-text string,
+* optionally at the given outline (heading) level. Empty text yields a
+* paragraph with no runs. The link-free counterpart of {@link paragraphFromRuns}.
+*/
 function paragraphBlock(text, outlineLevel) {
 	return {
 		kind: "paragraph",
@@ -15,6 +20,12 @@ function paragraphBlock(text, outlineLevel) {
 		}
 	};
 }
+/**
+* Build a paragraph {@link BodyElement} from positioned {@link TextSpan}s,
+* coalescing consecutive spans that share an `href` into one run (so a link
+* survives as its own run) and squashing whitespace. With no hrefs this
+* collapses to a single run — the same shape {@link paragraphBlock} produces.
+*/
 function paragraphFromRuns(spans, outlineLevel) {
 	const merged = [];
 	for (const s of spans) {
@@ -46,6 +57,11 @@ function paragraphFromRuns(spans, outlineLevel) {
 		}
 	};
 }
+/**
+* Store a {@link PdfImage}'s bytes (content-addressed dedup) and build the image
+* {@link BodyElement} that references them, sized in points from the placement
+* CTM. `alt` becomes the block's alt text when given.
+*/
 function imageBlock(image, resources, alt) {
 	return {
 		kind: "image",
@@ -58,11 +74,19 @@ function imageBlock(image, resources, alt) {
 		}
 	};
 }
+/** Collapse losses sharing a `detail` message (the same colour space dropped on many pages). */
 function dedupeLosses(losses) {
 	const byDetail = /* @__PURE__ */ new Map();
 	for (const loss of losses) if (!byDetail.has(loss.detail)) byDetail.set(loss.detail, loss);
 	return [...byDetail.values()];
 }
+/**
+* Turn a lifted {@link PdfVector} path (filled EP10 / stroked EP11) into a
+* custom-geometry shape {@link BodyElement}. Page-space points (y-up) become
+* path-space (bbox-relative, y-down); the shape is sized from the bounding box
+* (plus the stroke thickness) and placed in flow order by the caller. A fill
+* becomes a solid fill, a stroke becomes the outline.
+*/
 function shapeBlock(v) {
 	const w = v.maxX - v.minX;
 	const h = v.maxY - v.minY;
@@ -124,14 +148,55 @@ function shapeBlock(v) {
 		}
 	};
 }
-function buildFlowDoc(body, resources = new ResourceStore()) {
+/**
+* Derive the {@link SectionProperties} geometry from the source pages so a
+* reconstructed PDF re-renders at its real page size and orientation rather than
+* the layout engine's `A4` default — without it an `A3` source paginates onto
+* several `A4` pages, a wide/landscape page is letterboxed, and so on. PDF
+* user-space units are points, matching `Pt`, so the `MediaBox` extents map
+* straight to the page size. Uses the first {@link PdfPage}'s box (the
+* near-universal uniform-size case); a PDF whose pages differ in size reflows to
+* this single geometry — a known approximation, still far better than a fixed
+* `A4`. Returns `undefined` when there is no usable first-page box.
+*/
+function sectionFromPdfPages(pages) {
+	const box = pages[0]?.mediaBox;
+	if (!box) return void 0;
+	const width = Math.abs(box[2] - box[0]);
+	const height = Math.abs(box[3] - box[1]);
+	if (!(width > 0 && height > 0)) return void 0;
+	return {
+		pageSize: {
+			width: pt(width),
+			height: pt(height),
+			orientation: width > height ? "landscape" : "portrait"
+		},
+		margins: {
+			top: pt(0),
+			right: pt(0),
+			bottom: pt(0),
+			left: pt(0)
+		},
+		headers: [],
+		footers: []
+	};
+}
+/**
+* Assemble the final {@link FlowDoc} for a reconstruction: the body elements
+* with their styles resolved against the empty style sheet, the lifted-image
+* resource store, and the optional page {@link SectionProperties}. Shared by
+* both reconstruction paths (the tagged fast-path EP3 and the heuristic layout
+* path EP4).
+*/
+function buildFlowDoc(body, resources = new ResourceStore(), section) {
 	return {
 		kind: "flow",
 		body: resolveBodyStyles([...body], EMPTY_STYLE_SHEET),
 		sections: [],
+		...section ? { section } : {},
 		styles: EMPTY_STYLE_SHEET,
 		resources
 	};
 }
 //#endregion
-export { buildFlowDoc, dedupeLosses, imageBlock, paragraphBlock, paragraphFromRuns, shapeBlock };
+export { buildFlowDoc, dedupeLosses, imageBlock, paragraphBlock, paragraphFromRuns, sectionFromPdfPages, shapeBlock };