reamkit 1.15.0 → 1.15.2

package/dist/esm/pdf/signature.js

@@ -11,6 +11,16 @@ function pad2(n) {
 function pdfDate(d) {
 	return `D:${d.getUTCFullYear()}${pad2(d.getUTCMonth() + 1)}${pad2(d.getUTCDate())}${pad2(d.getUTCHours())}${pad2(d.getUTCMinutes())}${pad2(d.getUTCSeconds())}+00'00'`;
 }
+/**
+* Add an (invisible) signature field plus its signature dictionary to a document
+* being built (§12.8). The dictionary carries placeholder `/ByteRange` and
+* `/Contents` that {@link signPdf} fills later.
+*
+* @param ph      The signature metadata and reserved-bytes size.
+* @param pageRef The page the (zero-size) widget annotation belongs to.
+* @returns The field ref (attach to the page's `/Annots`) and the `/AcroForm`
+*   dictionary (attach to the catalog).
+*/
 function addSignaturePlaceholder(doc, ph, pageRef) {
 	const reserve = ph.reserveBytes ?? DEFAULT_RESERVE_BYTES;
 	const sigEntries = {
@@ -78,6 +88,18 @@ function toHex(bytes) {
 	for (const b of bytes) s += HEX[b >> 4] + HEX[b & 15];
 	return s;
 }
+/**
+* Sign a PDF that already carries a signature placeholder (from
+* {@link addSignaturePlaceholder}). Computes the real `/ByteRange`, hashes the
+* covered bytes (SHA-256), builds the detached PKCS#7/CMS, and writes it into
+* the reserved `/Contents` hole — leaving every other byte untouched.
+*
+* @param pdf  The placeholder-bearing PDF bytes.
+* @param cred The signer's certificate, key and algorithm.
+* @returns A new byte array with the real ByteRange and signature spliced in.
+* @throws Error when no placeholder is found, it is malformed, WebCrypto is
+*   unavailable, or the signature exceeds the reserved `/Contents` size.
+*/
 async function signPdf(pdf, cred) {
 	const out = pdf.slice();
 	const brKey = indexOfAscii(out, `/ByteRange ${BYTE_RANGE_PLACEHOLDER}`);

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

@@ -1,37 +1,101 @@
 import { PdfRef } from './objects.js';
 import { PdfDocument } from './writer.js';
+/**
+ * Standard structure types (ISO 32000-1 Table 333/337). Every type here is
+ * recognised without a `/RoleMap`, so the builder never emits one.
+ */
 export type StructType = 'Document' | 'Part' | 'Sect' | 'H1' | 'H2' | 'H3' | 'H4' | 'H5' | 'H6' | 'P' | 'L' | 'LI' | 'Lbl' | 'LBody' | 'Table' | 'TR' | 'TH' | 'TD' | 'Caption' | 'Figure' | 'Link' | 'Note' | 'Span';
 interface Mcref {
     readonly pageIndex: number;
     readonly mcid: number;
 }
+/** One node in the logical structure tree: a {@link StructType} plus its children, marked-content and attributes. */
 export declare class StructNode {
     readonly id: number;
     type: StructType;
     readonly children: Array<StructNode>;
     readonly mcrefs: Array<Mcref>;
+    /**
+     * §14.7.4.3 object references (`/OBJR` kids) — e.g. a Link element pointing at
+     * its link annotation. The annotation's own `/StructParent` entry is recorded
+     * via {@link StructTreeBuilder.addAnnotParent}.
+     */
     readonly objrs: Array<{
         readonly annotRef: PdfRef;
         readonly pageIndex: number;
     }>;
     parent: StructNode | null;
     ref: PdfRef | null;
+    /** Alternate text (`/Alt`, §14.9.4) — required on Figure for PDF/A-1a. */
     alt: string | null;
+    /** Natural language (`/Lang`) when it differs from the document default. */
     lang: string | null;
+    /**
+     * §14.8.5.2 Table attribute (emitted via a `/A` attribute object on the cell):
+     * `/Scope` on a TH (Row/Column) so assistive tech binds headers to data cells.
+     */
     scope: 'Row' | 'Column' | null;
+    /** §14.8.5.2 — `/ColSpan` when the cell spans more than one column (gridSpan). */
     colSpan: number | null;
+    /** §14.8.5.2 — `/RowSpan` when the cell spans more than one row (vertical merge). */
     rowSpan: number | null;
+    /**
+     * @param id   The node's index, used for deterministic id assignment and `/ID`.
+     * @param type The structure type (mutable, so the renderer can retag).
+     */
     constructor(id: number, type: StructType);
 }
+/**
+ * Builds the tagged-PDF logical structure tree (ISO 32000-1 §14.7–14.8): a
+ * `/StructTreeRoot` over a tree of {@link StructNode}s, tied back to page
+ * marked-content via MCRs and the `/ParentTree`. A generic emitter — the
+ * structure-type mapping policy lives in the renderer. Object ids are assigned by
+ * a deterministic pre-order DFS so identical input yields byte-identical output.
+ */
 export declare class StructTreeBuilder {
     private readonly nodes;
+    /** The root logical element (the single `/Document` under `/StructTreeRoot`). */
     readonly root: StructNode;
     constructor();
+    /**
+     * Create a node of `type` as the last child of `parent`.
+     *
+     * @param parent The parent node, or `null` for a free node (only the root is
+     *   created that way).
+     * @returns The new node.
+     */
     create(type: StructType, parent: StructNode | null): StructNode;
+    /**
+     * Look up a node by its id.
+     *
+     * @throws Error if no node has that id.
+     */
     node(id: number): StructNode;
+    /**
+     * Record that marked content `mcid` on page `pageIndex` is the content of node
+     * `nodeId`. Called from the emit phase as MCIDs are assigned.
+     */
     addMcref(nodeId: number, pageIndex: number, mcid: number): void;
+    /**
+     * §14.7.4.4: an annotation's `/StructParent` key maps DIRECTLY to its owning
+     * `/StructElem` in the parent tree (a scalar entry, unlike the per-page MCID
+     * arrays). The emit phase allocates keys above the page indices.
+     */
     private readonly annotParents;
+    /**
+     * Register that annotation parent-tree key `key` resolves to node `nodeId`.
+     *
+     * @see StructTreeBuilder.annotParents
+     */
     addAnnotParent(key: number, nodeId: number): void;
+    /**
+     * Emit the `/StructTreeRoot`, every `/StructElem`, and the `/ParentTree`. Must
+     * run after all pages are added (so `pageRefs` is complete) and after every
+     * {@link StructTreeBuilder.addMcref} call.
+     *
+     * @param pageRefs The page object references, indexed by page number.
+     * @returns A reference to the `/StructTreeRoot`, for the catalog.
+     */
     emit(doc: PdfDocument, pageRefs: ReadonlyArray<PdfRef>): PdfRef;
 }
 export {};

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

@@ -1,27 +1,60 @@
 import { PDF_NULL, dict, name, unicodeString } from "./objects.js";
 //#region src/pdf/struct-tree.ts
+/** One node in the logical structure tree: a {@link StructType} plus its children, marked-content and attributes. */
 var StructNode = class {
 	children = [];
 	mcrefs = [];
+	/**
+	* §14.7.4.3 object references (`/OBJR` kids) — e.g. a Link element pointing at
+	* its link annotation. The annotation's own `/StructParent` entry is recorded
+	* via {@link StructTreeBuilder.addAnnotParent}.
+	*/
 	objrs = [];
 	parent = null;
 	ref = null;
+	/** Alternate text (`/Alt`, §14.9.4) — required on Figure for PDF/A-1a. */
 	alt = null;
+	/** Natural language (`/Lang`) when it differs from the document default. */
 	lang = null;
+	/**
+	* §14.8.5.2 Table attribute (emitted via a `/A` attribute object on the cell):
+	* `/Scope` on a TH (Row/Column) so assistive tech binds headers to data cells.
+	*/
 	scope = null;
+	/** §14.8.5.2 — `/ColSpan` when the cell spans more than one column (gridSpan). */
 	colSpan = null;
+	/** §14.8.5.2 — `/RowSpan` when the cell spans more than one row (vertical merge). */
 	rowSpan = null;
+	/**
+	* @param id   The node's index, used for deterministic id assignment and `/ID`.
+	* @param type The structure type (mutable, so the renderer can retag).
+	*/
 	constructor(id, type) {
 		this.id = id;
 		this.type = type;
 	}
 };
+/**
+* Builds the tagged-PDF logical structure tree (ISO 32000-1 §14.7–14.8): a
+* `/StructTreeRoot` over a tree of {@link StructNode}s, tied back to page
+* marked-content via MCRs and the `/ParentTree`. A generic emitter — the
+* structure-type mapping policy lives in the renderer. Object ids are assigned by
+* a deterministic pre-order DFS so identical input yields byte-identical output.
+*/
 var StructTreeBuilder = class {
 	nodes = [];
+	/** The root logical element (the single `/Document` under `/StructTreeRoot`). */
 	root;
 	constructor() {
 		this.root = this.create("Document", null);
 	}
+	/**
+	* Create a node of `type` as the last child of `parent`.
+	*
+	* @param parent The parent node, or `null` for a free node (only the root is
+	*   created that way).
+	* @returns The new node.
+	*/
 	create(type, parent) {
 		const node = new StructNode(this.nodes.length, type);
 		node.parent = parent;
@@ -29,24 +62,51 @@ var StructTreeBuilder = class {
 		this.nodes.push(node);
 		return node;
 	}
+	/**
+	* Look up a node by its id.
+	*
+	* @throws Error if no node has that id.
+	*/
 	node(id) {
 		const n = this.nodes[id];
 		if (!n) throw new Error(`Unknown struct node id ${id}`);
 		return n;
 	}
+	/**
+	* Record that marked content `mcid` on page `pageIndex` is the content of node
+	* `nodeId`. Called from the emit phase as MCIDs are assigned.
+	*/
 	addMcref(nodeId, pageIndex, mcid) {
 		this.node(nodeId).mcrefs.push({
 			pageIndex,
 			mcid
 		});
 	}
+	/**
+	* §14.7.4.4: an annotation's `/StructParent` key maps DIRECTLY to its owning
+	* `/StructElem` in the parent tree (a scalar entry, unlike the per-page MCID
+	* arrays). The emit phase allocates keys above the page indices.
+	*/
 	annotParents = [];
+	/**
+	* Register that annotation parent-tree key `key` resolves to node `nodeId`.
+	*
+	* @see StructTreeBuilder.annotParents
+	*/
 	addAnnotParent(key, nodeId) {
 		this.annotParents.push({
 			key,
 			nodeId
 		});
 	}
+	/**
+	* Emit the `/StructTreeRoot`, every `/StructElem`, and the `/ParentTree`. Must
+	* run after all pages are added (so `pageRefs` is complete) and after every
+	* {@link StructTreeBuilder.addMcref} call.
+	*
+	* @param pageRefs The page object references, indexed by page number.
+	* @returns A reference to the `/StructTreeRoot`, for the catalog.
+	*/
 	emit(doc, pageRefs) {
 		const order = [];
 		const walk = (n) => {

package/dist/esm/pdf/styled-page-emitter.d.ts

@@ -2,12 +2,45 @@ import { LaidOutPdfDocument, StyledRenderOptions } from '../layout/styled-layout
 import { PdfDocument } from './writer.js';
 import { PdfEncryptOptions } from './encryption.js';
 type EmitOptions = Pick<StyledRenderOptions, 'attachments' | 'info' | 'language' | 'pdfUA' | 'signaturePlaceholder'>;
+/**
+ * The emit phase: turn a laid-out document into PDF objects (ISO 32000) and
+ * serialize it. The counterpart of `layoutStyledDocument` (the seam of
+ * ir-design §7 / oop-design §4.1); it sees only the laid-out document plus the
+ * output-side options, never the layout options. Fonts and images embed first
+ * (the object order the pre-split renderer produced), pages replay their
+ * `PageItem`s, then the catalog assembles the OutputIntent / XMP / struct-tree /
+ * attachments as required.
+ *
+ * @returns The serialized PDF bytes.
+ */
 export declare function emitStyledPdf(laid: LaidOutPdfDocument, options: EmitOptions, doc: PdfDocument): Uint8Array;
+/**
+ * The encrypted build (ISO 32000 §7.6): assemble as usual, encrypt every
+ * collected object with the derived file key, then add the (plaintext)
+ * `/Encrypt` dictionary and emit with a file `/ID`. Asynchronous because
+ * WebCrypto is.
+ *
+ * @param encrypt The encryption parameters (handler revision, permissions,
+ *                passwords) used to prepare the file key and `/Encrypt` dict.
+ * @returns The serialized, encrypted PDF bytes.
+ */
 export declare function emitStyledPdfEncrypted(laid: LaidOutPdfDocument, options: EmitOptions, doc: PdfDocument, encrypt: PdfEncryptOptions): Promise<Uint8Array>;
+/**
+ * Per-page tagging state threaded into `emitPageContent` when emitting a tagged
+ * PDF (ISO 32000-1 §14.7).
+ */
 export interface PageTagging {
+    /** The running MCID counter, reset per page. */
     next: number;
+    /** Whether any tagged marked content was emitted (so the page gets `/StructParents`). */
     assigned: boolean;
+    /** Tie an assigned MCID back to its structure node. */
     record: (structId: number, mcid: number) => void;
+    /**
+     * The marked-content tag for a structure node — its structure type, so the
+     * `BDC` tag matches the `StructElem` `/S` (§14.7.2: a heading is `/H1`, a
+     * cell's paragraph `/P`, …), not a hardcoded `/P`.
+     */
     tagFor: (structId: number) => string;
 }
 export {};

package/dist/esm/pdf/styled-page-emitter.js

@@ -15,10 +15,31 @@ import { addSignaturePlaceholder } from "./signature.js";
 import { buildXmpPacket } from "./xmp.js";
 //#region src/pdf/styled-page-emitter.ts
 var encoder = new TextEncoder();
+/**
+* The emit phase: turn a laid-out document into PDF objects (ISO 32000) and
+* serialize it. The counterpart of `layoutStyledDocument` (the seam of
+* ir-design §7 / oop-design §4.1); it sees only the laid-out document plus the
+* output-side options, never the layout options. Fonts and images embed first
+* (the object order the pre-split renderer produced), pages replay their
+* `PageItem`s, then the catalog assembles the OutputIntent / XMP / struct-tree /
+* attachments as required.
+*
+* @returns The serialized PDF bytes.
+*/
 function emitStyledPdf(laid, options, doc) {
 	const a = assembleStyledPdf(laid, options, doc);
 	return doc.build(a.catalogRef, a.infoRef, a.buildOptions);
 }
+/**
+* The encrypted build (ISO 32000 §7.6): assemble as usual, encrypt every
+* collected object with the derived file key, then add the (plaintext)
+* `/Encrypt` dictionary and emit with a file `/ID`. Asynchronous because
+* WebCrypto is.
+*
+* @param encrypt The encryption parameters (handler revision, permissions,
+*                passwords) used to prepare the file key and `/Encrypt` dict.
+* @returns The serialized, encrypted PDF bytes.
+*/
 async function emitStyledPdfEncrypted(laid, options, doc, encrypt) {
 	const a = assembleStyledPdf(laid, options, doc);
 	const prepared = await preparePdfEncryption(encrypt);

package/dist/esm/pdf/styled-page-renderer.d.ts

@@ -1,6 +1,24 @@
 import { BodyElement } from '../core/document-model/index.js';
 import { StyledRenderOptions } from '../layout/styled-layout.js';
+/**
+ * Render a body to a PDF: lay it out, then emit it over a fresh
+ * {@link PdfDocument}. The byte-stable synchronous path.
+ *
+ * @throws Error when `options.encrypt` is set — encryption requires the async
+ *         {@link renderStyledPdfEncrypted} path (WebCrypto).
+ */
 export declare function renderStyledPdf(body: ReadonlyArray<BodyElement>, options: StyledRenderOptions): Uint8Array;
+/**
+ * The encrypting variant of {@link renderStyledPdf} (ISO 32000 §7.6; async
+ * because WebCrypto is). Validates the standing conflicts here so every
+ * converter shares them: PDF/A forbids `/Encrypt` (ISO 19005), signatures +
+ * encryption is out of scope in v1, and PDF/UA requires assistive technology to
+ * keep extraction access (bit 10, forced on here). With no `options.encrypt` it
+ * falls through to the plain {@link renderStyledPdf}.
+ *
+ * @throws Error when `options.pdfA` is set (PDF/A forbids encryption) or when a
+ *         signature placeholder is combined with encryption.
+ */
 export declare function renderStyledPdfEncrypted(body: ReadonlyArray<BodyElement>, options: StyledRenderOptions): Promise<Uint8Array>;
 export * from '../layout/page-doc.js';
 export * from '../layout/styled-layout.js';

package/dist/esm/pdf/styled-page-renderer.js

@@ -3,10 +3,28 @@ import { layoutStyledDocument } from "../layout/styled-layout.js";
 import "../layout/page-doc.js";
 import { emitStyledPdf, emitStyledPdfEncrypted } from "./styled-page-emitter.js";
 //#region src/pdf/styled-page-renderer.ts
+/**
+* Render a body to a PDF: lay it out, then emit it over a fresh
+* {@link PdfDocument}. The byte-stable synchronous path.
+*
+* @throws Error when `options.encrypt` is set — encryption requires the async
+*         {@link renderStyledPdfEncrypted} path (WebCrypto).
+*/
 function renderStyledPdf(body, options) {
 	if (options.encrypt) throw new Error("PDF encryption requires the async conversion path (WebCrypto)");
 	return emitStyledPdf(layoutStyledDocument(body, options), options, new PdfDocument());
 }
+/**
+* The encrypting variant of {@link renderStyledPdf} (ISO 32000 §7.6; async
+* because WebCrypto is). Validates the standing conflicts here so every
+* converter shares them: PDF/A forbids `/Encrypt` (ISO 19005), signatures +
+* encryption is out of scope in v1, and PDF/UA requires assistive technology to
+* keep extraction access (bit 10, forced on here). With no `options.encrypt` it
+* falls through to the plain {@link renderStyledPdf}.
+*
+* @throws Error when `options.pdfA` is set (PDF/A forbids encryption) or when a
+*         signature placeholder is combined with encryption.
+*/
 async function renderStyledPdfEncrypted(body, options) {
 	const encrypt = options.encrypt;
 	if (!encrypt) return renderStyledPdf(body, options);

package/dist/esm/pdf/text-encoding.d.ts

@@ -1,2 +1,18 @@
+/**
+ * Encode text as WinAnsiEncoding (CP-1252) bytes (ISO 32000-1 §D.2). Latin-1 is
+ * passed through; the CP-1252 high range (smart quotes, dashes, €, …) is
+ * remapped; anything else becomes `?`.
+ *
+ * @param text The string to encode.
+ * @returns One byte per code point.
+ */
 export declare function encodeWinAnsi(text: string): Uint8Array;
+/**
+ * Encode text as a PDF literal string body (ISO 32000-1 §7.3.4.2): WinAnsi
+ * bytes with `(`, `)` and `\` backslash-escaped. The result is ready to be
+ * wrapped in `(` … `)` within a content stream.
+ *
+ * @param text The string to encode.
+ * @returns The escaped bytes (without the surrounding parentheses).
+ */
 export declare function encodeLiteralBytes(text: string): Uint8Array;

package/dist/esm/pdf/text-page-renderer.d.ts

@@ -1,7 +1,9 @@
 import { ParsedTtf } from '../core/font/index.js';
+/** A font for {@link renderPlainTextPdf}: an already-parsed TTF or its raw bytes. */
 export type FontInput = ParsedTtf | {
     readonly bytes: Uint8Array;
 };
+/** Options for {@link renderPlainTextPdf}; every layout dimension defaults (A4, 72pt margins, 12pt text). */
 export interface TextRenderOptions {
     readonly font: FontInput;
     readonly pageWidth?: number;
@@ -11,6 +13,15 @@ export interface TextRenderOptions {
     readonly marginTop?: number;
     readonly marginBottom?: number;
     readonly fontSize?: number;
+    /** Baseline-to-baseline distance in points; defaults to `1.2 × fontSize`. */
     readonly lineHeight?: number;
 }
+/**
+ * Render plain-text paragraphs to a single-font PDF, paginating greedily with
+ * real TTF metrics and embedding the subset font.
+ *
+ * @param paragraphs One string per paragraph; empty strings become blank lines.
+ * @param options    The font plus optional page geometry and type size.
+ * @returns The encoded PDF bytes.
+ */
 export declare function renderPlainTextPdf(paragraphs: ReadonlyArray<string>, options: TextRenderOptions): Uint8Array;

package/dist/esm/pdf/vector-graphics.d.ts

@@ -1,4 +1,16 @@
 import { VectorShape } from '../core/vector.js';
 export type { PathSegment, StrokeStyle, VectorPath, VectorShape } from '../core/vector.js';
 export { PathBuilder } from '../core/vector.js';
+/**
+ * Emit a {@link VectorShape} as PDF content-stream operators (ISO 32000 §8.5),
+ * wrapped in a `q`/`Q` save-restore with the shape's transform as the CTM. The
+ * subpaths are painted with a single operator, so the winding rule is decided
+ * once (even-odd if any subpath asks).
+ *
+ * @param shape       The shape to draw.
+ * @param patternName When set, the fill is this named shading pattern from the
+ *   page's `/Pattern` resources (a gradient, EP16b) rather than a solid colour;
+ *   only used if the shape actually carries a `fillGradient`.
+ * @returns The content-stream operator lines.
+ */
 export declare function emitVectorShape(shape: VectorShape, patternName?: string): Array<string>;

package/dist/esm/pdf/vector-graphics.js

@@ -1,5 +1,17 @@
 import "../core/vector.js";
 //#region src/pdf/vector-graphics.ts
+/**
+* Emit a {@link VectorShape} as PDF content-stream operators (ISO 32000 §8.5),
+* wrapped in a `q`/`Q` save-restore with the shape's transform as the CTM. The
+* subpaths are painted with a single operator, so the winding rule is decided
+* once (even-odd if any subpath asks).
+*
+* @param shape       The shape to draw.
+* @param patternName When set, the fill is this named shading pattern from the
+*   page's `/Pattern` resources (a gradient, EP16b) rather than a solid colour;
+*   only used if the shape actually carries a `fillGradient`.
+* @returns The content-stream operator lines.
+*/
 function emitVectorShape(shape, patternName) {
 	const out = [];
 	out.push("q");

package/dist/esm/pdf/writer.d.ts

@@ -1,12 +1,51 @@
 import { PdfValue, PdfRef } from './objects.js';
+/** Options for {@link PdfDocument.build}. */
 export interface BuildOptions {
+    /** PDF header version, e.g. `"1.7"` (default) or `"1.4"` (PDF/A-1). */
     readonly version?: string;
+    /**
+     * When true, emit a `/ID` array in the trailer (required by PDF/A). The two
+     * identifiers are a deterministic hash of the file body — no `Date`/random,
+     * so the same input always yields the same bytes.
+     */
     readonly id?: boolean;
+    /**
+     * The `/Encrypt` dictionary's ref (§7.6.2) — emitted in the trailer. The
+     * referenced object must be added AFTER {@link PdfDocument.encryptAll} so it
+     * stays plaintext.
+     */
     readonly encrypt?: PdfRef;
 }
+/**
+ * Collects indirect objects and emits a complete PDF file (ISO 32000-1 §7.5):
+ * header (§7.5.2), body of indirect objects (§7.5.3), cross-reference table
+ * (§7.5.4) and trailer (§7.5.5).
+ */
 export declare class PdfDocument {
     private readonly objects;
+    /**
+     * Append `value` as a new indirect object.
+     *
+     * @param value The object to add.
+     * @returns An indirect reference to it (generation 0).
+     */
     add(value: PdfValue): PdfRef;
+    /**
+     * Encrypt every string and stream in every object added so far (§7.6). The
+     * `/Encrypt` dictionary itself must be added AFTER this pass so it stays
+     * plaintext.
+     *
+     * @param fileKey The document encryption key.
+     */
     encryptAll(fileKey: Uint8Array): Promise<void>;
+    /**
+     * Serialize the whole document to bytes: header, body, cross-reference table
+     * and trailer.
+     *
+     * @param root    Reference to the document catalog (`/Root`).
+     * @param info    Optional reference to the `/Info` dictionary.
+     * @param options Header version, `/ID` emission, and `/Encrypt` reference.
+     * @returns The complete PDF file bytes.
+     */
     build(root: PdfRef, info?: PdfRef, options?: BuildOptions): Uint8Array;
 }

package/dist/esm/pdf/writer.js

@@ -11,8 +11,19 @@ var BINARY_MARKER = new Uint8Array([
 	211,
 	10
 ]);
+/**
+* Collects indirect objects and emits a complete PDF file (ISO 32000-1 §7.5):
+* header (§7.5.2), body of indirect objects (§7.5.3), cross-reference table
+* (§7.5.4) and trailer (§7.5.5).
+*/
 var PdfDocument = class {
 	objects = [];
+	/**
+	* Append `value` as a new indirect object.
+	*
+	* @param value The object to add.
+	* @returns An indirect reference to it (generation 0).
+	*/
 	add(value) {
 		const id = this.objects.length + 1;
 		this.objects.push({
@@ -21,9 +32,25 @@ var PdfDocument = class {
 		});
 		return new PdfRef(id);
 	}
+	/**
+	* Encrypt every string and stream in every object added so far (§7.6). The
+	* `/Encrypt` dictionary itself must be added AFTER this pass so it stays
+	* plaintext.
+	*
+	* @param fileKey The document encryption key.
+	*/
 	async encryptAll(fileKey) {
 		for (const obj of this.objects) obj.value = await encryptObjectGraph(obj.value, fileKey);
 	}
+	/**
+	* Serialize the whole document to bytes: header, body, cross-reference table
+	* and trailer.
+	*
+	* @param root    Reference to the document catalog (`/Root`).
+	* @param info    Optional reference to the `/Info` dictionary.
+	* @param options Header version, `/ID` emission, and `/Encrypt` reference.
+	* @returns The complete PDF file bytes.
+	*/
 	build(root, info, options = {}) {
 		const parts = [];
 		const offsets = new Array(this.objects.length + 1).fill(0);

package/dist/esm/pdf/xmp.d.ts

@@ -1,14 +1,30 @@
+/** The document metadata projected into an XMP packet by {@link buildXmpPacket}. */
 export interface XmpInput {
     readonly title?: string;
     readonly author?: string;
     readonly subject?: string;
     readonly keywords?: string;
+    /** Application that created the doc (`xmp:CreatorTool`). */
     readonly creator?: string;
     readonly producer?: string;
     readonly createDate?: Date;
     readonly modifyDate?: Date;
+    /**
+     * PDF/A identifier: part 1 (ISO 19005-1) / 2 / 3; conformance level
+     * `'A'` (tagged) / `'B'` (visual) / `'U'` (Unicode — parts 2/3 only).
+     */
     readonly pdfaPart?: '1' | '2' | '3';
+    /** PDF/UA identification (ISO 14289-1) — `pdfuaid:part`. */
     readonly pdfuaPart?: '1';
     readonly pdfaConformance?: 'A' | 'B' | 'U';
 }
+/**
+ * Build an XMP metadata packet (ISO 16684-1) for the document `/Metadata`
+ * stream, emitting only the sections the supplied {@link XmpInput} populates
+ * (PDF/A and PDF/UA identifiers, Dublin Core, XMP basic, Adobe PDF). For PDF/A
+ * the standard properties must agree with the `/Info` dictionary.
+ *
+ * @param input The metadata to project.
+ * @returns The UTF-8 encoded XMP packet bytes.
+ */
 export declare function buildXmpPacket(input: XmpInput): Uint8Array;

package/dist/esm/pdf/xmp.js

@@ -6,6 +6,15 @@ function xmpDate(d) {
 	const pad = (n, w = 2) => String(n).padStart(w, "0");
 	return `${pad(d.getUTCFullYear(), 4)}-${pad(d.getUTCMonth() + 1)}-${pad(d.getUTCDate())}T${pad(d.getUTCHours())}:${pad(d.getUTCMinutes())}:${pad(d.getUTCSeconds())}Z`;
 }
+/**
+* Build an XMP metadata packet (ISO 16684-1) for the document `/Metadata`
+* stream, emitting only the sections the supplied {@link XmpInput} populates
+* (PDF/A and PDF/UA identifiers, Dublin Core, XMP basic, Adobe PDF). For PDF/A
+* the standard properties must agree with the `/Info` dictionary.
+*
+* @param input The metadata to project.
+* @returns The UTF-8 encoded XMP packet bytes.
+*/
 function buildXmpPacket(input) {
 	const props = [];
 	if (input.pdfaPart) props.push(`      <rdf:Description rdf:about="" xmlns:pdfaid="http://www.aiim.org/pdfa/ns/id/">`, `        <pdfaid:part>${input.pdfaPart}</pdfaid:part>`, `        <pdfaid:conformance>${input.pdfaConformance ?? "B"}</pdfaid:conformance>`, `      </rdf:Description>`);

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

@@ -1,14 +1,39 @@
+/**
+ * The `/CCITTFaxDecode` parameters that drive {@link decodeCcitt} (ISO 32000-1
+ * §7.4.6), pulled from the filter's `/DecodeParms`.
+ */
 export interface CcittParams {
+    /** `/K` — `<0` Group 4, `0` Group 3 1-D, `>0` Group 3 2-D (unsupported). */
     readonly k: number;
+    /** `/Columns` (pixels per row). */
     readonly columns: number;
+    /** `/Rows` (or the image `/Height`) — the row count to decode. */
     readonly rows: number;
+    /** `/EncodedByteAlign` — pad each row to a byte boundary. */
     readonly byteAlign: boolean;
 }
+/**
+ * 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).
+ */
 export declare function decodeCcitt(data: Uint8Array, params: CcittParams): Uint8Array | undefined;
+/** A decoded T.6 two-dimensional mode code: pass, horizontal, or vertical V(d). */
 export interface Mode {
     readonly kind: 'pass' | 'horizontal' | 'vertical';
+    /** Vertical offset (−3..3); meaningful only when `kind` is `'vertical'`. */
     readonly d: number;
 }
+/**
+ * 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.
+ */
 export declare const WHITE_CODES: ReadonlyArray<readonly [number, string]>;
 export declare const BLACK_CODES: ReadonlyArray<readonly [number, string]>;
 export declare const SHARED_MAKEUP: ReadonlyArray<readonly [number, string]>;