reamkit 1.15.1 → 1.15.3

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

@@ -1,4 +1,5 @@
 import { PdfValue } from './objects.js';
+/** The user-access permission flags (`/P`, §7.6.4.4.7); each defaults to allowed. */
 export interface PdfPermissions {
     /** Bit 3 — print the document (default true). */
     readonly printing?: boolean;
@@ -15,6 +16,7 @@ export interface PdfPermissions {
     /** Bit 11 — assemble (insert/rotate/delete pages) (default true). */
     readonly documentAssembly?: boolean;
 }
+/** Passwords and permissions for {@link preparePdfEncryption}. */
 export interface PdfEncryptOptions {
     /** Required to OPEN the document. Empty string = opens without a prompt. */
     readonly userPassword?: string;
@@ -22,13 +24,70 @@ export interface PdfEncryptOptions {
     readonly ownerPassword?: string;
     readonly permissions?: PdfPermissions;
 }
+/** The output of {@link preparePdfEncryption}: the file key plus the `/Encrypt` dictionary. */
 export interface PreparedEncryption {
+    /** 32-byte file encryption key (FEK) — encrypts every string/stream. */
     readonly fileKey: Uint8Array;
     readonly encryptDict: PdfValue;
 }
+/**
+ * Compute the `/P` permission integer (§7.6.4.4.7) from the high-level flags:
+ * bits 1–2 are reserved 0 and undefined bits are 1, so all-permissions is
+ * `0xFFFFFFFC` (-4 as int32); each disabled flag clears its bit.
+ *
+ * @param p The permission flags, or `undefined` for all-allowed.
+ * @returns The signed 32-bit `/P` value.
+ */
 export declare function permissionBits(p: PdfPermissions | undefined): number;
+/**
+ * AES-CBC decryption without padding, the inverse of the internal no-pad
+ * encrypt. Appends a crafted padding block so WebCrypto's PKCS7 unpad succeeds
+ * and returns exactly `data.length` plain bytes.
+ *
+ * @param key  The 16-byte AES key.
+ * @param iv   The initialization vector.
+ * @param data The ciphertext (a 16-byte multiple).
+ * @returns The decrypted bytes.
+ */
 export declare function aesCbcNoPadDecrypt(key: Uint8Array, iv: Uint8Array, data: Uint8Array): Promise<Uint8Array>;
+/**
+ * The iterated hash hardening of Algorithm 2.B (§7.6.4.3.4): SHA-256/384/512
+ * rounds interleaved with AES-CBC, run to the spec's stopping condition.
+ *
+ * @param password The (truncated) password bytes.
+ * @param salt     The validation or key salt.
+ * @param userData Additional hash input (the 48-byte `/U` for owner derivation,
+ *   empty otherwise).
+ * @returns The derived 32-byte key.
+ */
 export declare function hardHash(password: Uint8Array, salt: Uint8Array, userData: Uint8Array): Promise<Uint8Array>;
+/**
+ * Build the V5/R6 (AES-256) Standard-security-handler `/Encrypt` dictionary:
+ * derive `/U`, `/UE`, `/O`, `/OE` and `/Perms` (§7.6.4.4.8–.10, Algorithms
+ * 8–10) for a freshly-generated random file encryption key.
+ *
+ * @param options The passwords and permissions.
+ * @returns The file key and the `/Encrypt` dictionary ({@link PreparedEncryption}).
+ */
 export declare function preparePdfEncryption(options: PdfEncryptOptions): Promise<PreparedEncryption>;
+/**
+ * Decrypt AESV3 content (§7.6.3.3): split the leading 16-byte IV and
+ * AES-256-CBC-decrypt the remainder.
+ *
+ * @param fileKey The 32-byte file encryption key.
+ * @param data    The `IV ‖ ciphertext` bytes.
+ * @returns The decrypted plaintext.
+ */
 export declare function decryptBytes(fileKey: Uint8Array, data: Uint8Array): Promise<Uint8Array>;
+/**
+ * Recursively encrypt every string and stream in an object graph (AESV3). The
+ * `/Encrypt` dictionary itself is added AFTER this pass and never encrypted, and
+ * trailer `/ID` strings live outside the body. Strings come back as hex strings,
+ * since the cipher bytes are binary; numbers, booleans, names, refs, null and
+ * raw tokens pass through unchanged.
+ *
+ * @param value   The value to walk.
+ * @param fileKey The 32-byte file encryption key.
+ * @returns The value with its strings/streams replaced by their ciphertext.
+ */
 export declare function encryptObjectGraph(value: PdfValue, fileKey: Uint8Array): Promise<PdfValue>;

package/dist/esm/pdf/encryption.js

@@ -2,6 +2,14 @@ import { PdfHexString, PdfStream, dict, name } from "./objects.js";
 //#region src/pdf/encryption.ts
 var encoder = new TextEncoder();
 var subtle = globalThis.crypto.subtle;
+/**
+* Compute the `/P` permission integer (§7.6.4.4.7) from the high-level flags:
+* bits 1–2 are reserved 0 and undefined bits are 1, so all-permissions is
+* `0xFFFFFFFC` (-4 as int32); each disabled flag clears its bit.
+*
+* @param p The permission flags, or `undefined` for all-allowed.
+* @returns The signed 32-bit `/P` value.
+*/
 function permissionBits(p) {
 	let bits = -4;
 	const off = (bit) => bits &= ~(1 << bit - 1);
@@ -39,6 +47,16 @@ async function aesCbcNoPad(key, iv, data) {
 		iv
 	}, k, data)).slice(0, data.length);
 }
+/**
+* The iterated hash hardening of Algorithm 2.B (§7.6.4.3.4): SHA-256/384/512
+* rounds interleaved with AES-CBC, run to the spec's stopping condition.
+*
+* @param password The (truncated) password bytes.
+* @param salt     The validation or key salt.
+* @param userData Additional hash input (the 48-byte `/U` for owner derivation,
+*   empty otherwise).
+* @returns The derived 32-byte key.
+*/
 async function hardHash(password, salt, userData) {
 	let k = await sha("SHA-256", concat(password, salt, userData));
 	for (let round = 0;; round++) {
@@ -53,6 +71,14 @@ async function hardHash(password, salt, userData) {
 	}
 	return k.slice(0, 32);
 }
+/**
+* Build the V5/R6 (AES-256) Standard-security-handler `/Encrypt` dictionary:
+* derive `/U`, `/UE`, `/O`, `/OE` and `/Perms` (§7.6.4.4.8–.10, Algorithms
+* 8–10) for a freshly-generated random file encryption key.
+*
+* @param options The passwords and permissions.
+* @returns The file key and the `/Encrypt` dictionary ({@link PreparedEncryption}).
+*/
 async function preparePdfEncryption(options) {
 	const user = passwordBytes(options.userPassword ?? "");
 	const owner = passwordBytes(options.ownerPassword ?? options.userPassword ?? "");
@@ -118,6 +144,17 @@ async function encryptBytes(fileKey, data) {
 		iv
 	}, k, data)));
 }
+/**
+* Recursively encrypt every string and stream in an object graph (AESV3). The
+* `/Encrypt` dictionary itself is added AFTER this pass and never encrypted, and
+* trailer `/ID` strings live outside the body. Strings come back as hex strings,
+* since the cipher bytes are binary; numbers, booleans, names, refs, null and
+* raw tokens pass through unchanged.
+*
+* @param value   The value to walk.
+* @param fileKey The 32-byte file encryption key.
+* @returns The value with its strings/streams replaced by their ciphertext.
+*/
 async function encryptObjectGraph(value, fileKey) {
 	if (typeof value === "string") return new PdfHexString(await encryptBytes(fileKey, encoder.encode(value)));
 	if (value instanceof PdfHexString) return new PdfHexString(await encryptBytes(fileKey, value.bytes));

package/dist/esm/pdf/icc-profile.d.ts

@@ -1 +1,9 @@
+/**
+ * Synthesise a minimal valid ICC v2 matrix/TRC RGB display profile from scratch
+ * (no external `.icc` asset), for use as a PDF/A-1b `OutputIntent`'s
+ * `DestOutputProfile`. Colorimetrically "sRGB-ish"; PDF/A validators check
+ * structural validity (version, class, required tags) rather than exact colour.
+ *
+ * @returns The encoded ICC profile bytes.
+ */
 export declare function buildSrgbIccProfile(): Uint8Array;

package/dist/esm/pdf/icc-profile.js

@@ -74,6 +74,14 @@ function buildCurveGamma(gamma) {
 function align4(n) {
 	return n + 3 & -4;
 }
+/**
+* Synthesise a minimal valid ICC v2 matrix/TRC RGB display profile from scratch
+* (no external `.icc` asset), for use as a PDF/A-1b `OutputIntent`'s
+* `DestOutputProfile`. Colorimetrically "sRGB-ish"; PDF/A validators check
+* structural validity (version, class, required tags) rather than exact colour.
+*
+* @returns The encoded ICC profile bytes.
+*/
 function buildSrgbIccProfile() {
 	const desc = buildTextDescription(DESC);
 	const wtpt = buildXYZ(D50.x, D50.y, D50.z);

package/dist/esm/pdf/image-xobject.d.ts

@@ -3,10 +3,29 @@ import { PdfDocument } from './writer.js';
 import { EmbedImageOptions, PreparedImage } from '../core/images.js';
 export { detectImageFormat, prepareImage } from '../core/images.js';
 export type { EmbedImageOptions, ImageFormat, PreparedImage } from '../core/images.js';
+/** A reference to an embedded image XObject plus its pixel dimensions. */
 export interface EmbeddedImage {
+    /** Indirect reference to the image XObject, for a page's `/XObject` resources. */
     readonly ref: PdfRef;
     readonly widthPx: number;
     readonly heightPx: number;
 }
+/**
+ * Create the PDF image-XObject objects from an already-prepared image (ISO
+ * 32000-1 §8.9.5), emitting an `/SMask` soft-mask object first when present.
+ * The decode/validate work happens earlier in `prepareImage`; this only writes
+ * the objects.
+ *
+ * @param prepared The decoded, ready-to-emit image stream.
+ * @returns The image reference and its pixel dimensions.
+ */
 export declare function addImage(doc: PdfDocument, prepared: PreparedImage): EmbeddedImage;
+/**
+ * Decode raw image `bytes` and embed them in one step — a convenience over
+ * `prepareImage` + {@link addImage}.
+ *
+ * @param bytes   The raw image file bytes (PNG/JPEG/…).
+ * @param options Decode/embed options.
+ * @returns The image reference and its pixel dimensions.
+ */
 export declare function embedImage(doc: PdfDocument, bytes: Uint8Array, options?: EmbedImageOptions): EmbeddedImage;

package/dist/esm/pdf/image-xobject.js

@@ -1,6 +1,15 @@
 import { name, stream } from "./objects.js";
 import "../core/images.js";
 //#region src/pdf/image-xobject.ts
+/**
+* Create the PDF image-XObject objects from an already-prepared image (ISO
+* 32000-1 §8.9.5), emitting an `/SMask` soft-mask object first when present.
+* The decode/validate work happens earlier in `prepareImage`; this only writes
+* the objects.
+*
+* @param prepared The decoded, ready-to-emit image stream.
+* @returns The image reference and its pixel dimensions.
+*/
 function addImage(doc, prepared) {
 	let smaskRef;
 	if (prepared.smaskData) smaskRef = doc.add(stream({

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

@@ -1,32 +1,72 @@
+/** The PDF `null` object (§7.3.9), modelled as a unique symbol. */
 export declare const PDF_NULL: unique symbol;
+/** The type of the PDF `null` object, {@link PDF_NULL}. */
 export type PdfNull = typeof PDF_NULL;
+/** A PDF name object (§7.3.5), e.g. `/Type` — the leading slash is added on serialization. */
 export declare class PdfName {
     readonly value: string;
+    /** @param value The name's text, without the leading `/`. */
     constructor(value: string);
 }
+/** An indirect reference (§7.3.10), written `id gen R`. */
 export declare class PdfRef {
     readonly id: number;
     readonly generation: number;
+    /**
+     * @param id         The referenced object number.
+     * @param generation The generation number (0 for freshly written objects).
+     */
     constructor(id: number, generation?: number);
 }
+/** A PDF stream object (§7.3.8): a dictionary plus its raw byte payload. */
 export declare class PdfStream {
     readonly dict: PdfDict;
     readonly data: Uint8Array;
+    /**
+     * @param dict The stream dictionary (`/Length` is filled in on serialization).
+     * @param data The raw stream bytes.
+     */
     constructor(dict: PdfDict, data: Uint8Array);
 }
+/**
+ * A PDF hex string (§7.3.4.3), written as `<HEXBYTES>` and decoding to raw
+ * bytes. Used for `/Info` entries containing non-ASCII text: the bytes are
+ * UTF-16BE with a leading BOM, the PDF-standard form for Unicode strings.
+ */
 export declare class PdfHexString {
     readonly bytes: Uint8Array;
+    /** @param bytes The raw bytes to emit as hex. */
     constructor(bytes: Uint8Array);
 }
+/**
+ * A verbatim token emitted exactly as given — no escaping, no quoting. Used for
+ * the signature `/ByteRange` placeholder, a fixed-width array overwritten in
+ * place after the byte offsets are known (ISO 32000 §12.8.1).
+ */
 export declare class PdfRawToken {
     readonly token: string;
+    /** @param token The literal text to emit unchanged. */
     constructor(token: string);
 }
+/** A PDF dictionary (§7.3.7): an ordered map from name keys to {@link PdfValue}s. */
 export type PdfDict = Map<string, PdfValue>;
+/** A PDF array (§7.3.6) of {@link PdfValue}s. */
 export type PdfArray = Array<PdfValue>;
+/** Any PDF object value (§7.3): the union of all the primitive and composite object types. */
 export type PdfValue = PdfNull | boolean | number | string | PdfName | PdfHexString | PdfRawToken | PdfArray | PdfDict | PdfRef | PdfStream;
+/** Construct a {@link PdfName} from its text (without the leading `/`). */
 export declare const name: (v: string) => PdfName;
+/** Construct a {@link PdfRef} to object `id` at generation `gen` (default 0). */
 export declare const ref: (id: number, gen?: number) => PdfRef;
+/** Construct a {@link PdfDict} from a plain object of name → value entries. */
 export declare const dict: (entries: Record<string, PdfValue>) => PdfDict;
+/** Construct a {@link PdfStream} from a dictionary literal plus its byte payload. */
 export declare const stream: (entries: Record<string, PdfValue>, data: Uint8Array) => PdfStream;
+/**
+ * Build a PDF Unicode string (UTF-16BE with BOM) suitable for `/Info` or
+ * document-level text metadata. Accepts arbitrary Unicode input.
+ *
+ * @param s The text to encode.
+ * @returns A {@link PdfHexString} holding the BOM-prefixed UTF-16BE bytes.
+ */
 export declare const unicodeString: (s: string) => PdfHexString;

package/dist/esm/pdf/objects.js

@@ -1,36 +1,72 @@
 //#region src/pdf/objects.ts
+/** The PDF `null` object (§7.3.9), modelled as a unique symbol. */
 var PDF_NULL = Symbol("PDF_NULL");
+/** A PDF name object (§7.3.5), e.g. `/Type` — the leading slash is added on serialization. */
 var PdfName = class {
+	/** @param value The name's text, without the leading `/`. */
 	constructor(value) {
 		this.value = value;
 	}
 };
+/** An indirect reference (§7.3.10), written `id gen R`. */
 var PdfRef = class {
+	/**
+	* @param id         The referenced object number.
+	* @param generation The generation number (0 for freshly written objects).
+	*/
 	constructor(id, generation = 0) {
 		this.id = id;
 		this.generation = generation;
 	}
 };
+/** A PDF stream object (§7.3.8): a dictionary plus its raw byte payload. */
 var PdfStream = class {
+	/**
+	* @param dict The stream dictionary (`/Length` is filled in on serialization).
+	* @param data The raw stream bytes.
+	*/
 	constructor(dict, data) {
 		this.dict = dict;
 		this.data = data;
 	}
 };
+/**
+* A PDF hex string (§7.3.4.3), written as `<HEXBYTES>` and decoding to raw
+* bytes. Used for `/Info` entries containing non-ASCII text: the bytes are
+* UTF-16BE with a leading BOM, the PDF-standard form for Unicode strings.
+*/
 var PdfHexString = class {
+	/** @param bytes The raw bytes to emit as hex. */
 	constructor(bytes) {
 		this.bytes = bytes;
 	}
 };
+/**
+* A verbatim token emitted exactly as given — no escaping, no quoting. Used for
+* the signature `/ByteRange` placeholder, a fixed-width array overwritten in
+* place after the byte offsets are known (ISO 32000 §12.8.1).
+*/
 var PdfRawToken = class {
+	/** @param token The literal text to emit unchanged. */
 	constructor(token) {
 		this.token = token;
 	}
 };
+/** Construct a {@link PdfName} from its text (without the leading `/`). */
 var name = (v) => new PdfName(v);
+/** Construct a {@link PdfRef} to object `id` at generation `gen` (default 0). */
 var ref = (id, gen = 0) => new PdfRef(id, gen);
+/** Construct a {@link PdfDict} from a plain object of name → value entries. */
 var dict = (entries) => new Map(Object.entries(entries));
+/** Construct a {@link PdfStream} from a dictionary literal plus its byte payload. */
 var stream = (entries, data) => new PdfStream(dict(entries), data);
+/**
+* Build a PDF Unicode string (UTF-16BE with BOM) suitable for `/Info` or
+* document-level text metadata. Accepts arbitrary Unicode input.
+*
+* @param s The text to encode.
+* @returns A {@link PdfHexString} holding the BOM-prefixed UTF-16BE bytes.
+*/
 var unicodeString = (s) => {
 	const codepoints = [];
 	for (const ch of s) codepoints.push(ch.codePointAt(0));

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

@@ -1,3 +1,21 @@
 import { PdfValue } from './objects.js';
+/**
+ * Serialize a single PDF value to its textual representation (ISO 32000-1 §7.3).
+ *
+ * @param v The value to serialize.
+ * @returns The serialized string.
+ * @throws Error on a non-finite number, or a {@link PdfStream} (which must be an
+ *   indirect object, not inlined).
+ */
 export declare function serializeValue(v: PdfValue): string;
+/**
+ * Serialize a value as a complete `id gen obj … endobj` indirect object
+ * (§7.3.10). Streams are emitted with their raw payload; everything else is
+ * inlined via {@link serializeValue}.
+ *
+ * @param id         The object number.
+ * @param generation The generation number.
+ * @param value      The object value.
+ * @returns The encoded indirect-object bytes.
+ */
 export declare function serializeIndirectObject(id: number, generation: number, value: PdfValue): Uint8Array;

package/dist/esm/pdf/serialize.js

@@ -8,6 +8,14 @@ var formatNumber = (n) => {
 	if (Number.isInteger(n)) return String(n);
 	return n.toFixed(6).replace(/0+$/, "").replace(/\.$/, "");
 };
+/**
+* Serialize a single PDF value to its textual representation (ISO 32000-1 §7.3).
+*
+* @param v The value to serialize.
+* @returns The serialized string.
+* @throws Error on a non-finite number, or a {@link PdfStream} (which must be an
+*   indirect object, not inlined).
+*/
 function serializeValue(v) {
 	if (v === PDF_NULL) return "null";
 	if (typeof v === "boolean") return v ? "true" : "false";
@@ -34,6 +42,16 @@ function serializeDict(d) {
 	for (const [k, v] of d) entries.push(`/${escapeName(k)} ${serializeValue(v)}`);
 	return `<<${entries.join(" ")}>>`;
 }
+/**
+* Serialize a value as a complete `id gen obj … endobj` indirect object
+* (§7.3.10). Streams are emitted with their raw payload; everything else is
+* inlined via {@link serializeValue}.
+*
+* @param id         The object number.
+* @param generation The generation number.
+* @param value      The object value.
+* @returns The encoded indirect-object bytes.
+*/
 function serializeIndirectObject(id, generation, value) {
 	if (value instanceof PdfStream) return serializeStreamObject(id, generation, value);
 	const body = `${id} ${generation} obj\n${serializeValue(value)}\nendobj\n`;

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

@@ -7,6 +7,22 @@ interface Bbox {
     readonly maxX: number;
     readonly maxY: number;
 }
+/**
+ * The local-space bounding box of a shape's paths (y-up).
+ *
+ * @returns The bounding box, or `undefined` for an empty/degenerate shape (where
+ *   no gradient can be placed).
+ */
 export declare function shapeBbox(shape: VectorShape): Bbox | undefined;
+/**
+ * Build the PatternType-2 shading pattern object (axial or radial) for a
+ * DrawingML gradient (EP16b) and add it to `doc`. The pattern's `/Matrix` is the
+ * shape's CTM and the shading `/Coords` are in the shape's local space.
+ *
+ * @param gradient The gradient fill (kind, angle, colour stops).
+ * @param bbox     The shape's local-space bounding box, from {@link shapeBbox}.
+ * @param ctm      The shape's current transformation matrix, used as `/Matrix`.
+ * @returns A reference to the `/Pattern` object, for a `/Pattern cs /Pn scn` fill.
+ */
 export declare function buildGradientPattern(doc: PdfDocument, gradient: ShapeGradient, bbox: Bbox, ctm: readonly [number, number, number, number, number, number]): PdfRef;
 export {};

package/dist/esm/pdf/shading.js

@@ -1,5 +1,11 @@
 import { dict, name, ref } from "./objects.js";
 //#region src/pdf/shading.ts
+/**
+* The local-space bounding box of a shape's paths (y-up).
+*
+* @returns The bounding box, or `undefined` for an empty/degenerate shape (where
+*   no gradient can be placed).
+*/
 function shapeBbox(shape) {
 	let minX = Infinity;
 	let minY = Infinity;
@@ -24,6 +30,16 @@ function shapeBbox(shape) {
 		maxY
 	} : void 0;
 }
+/**
+* Build the PatternType-2 shading pattern object (axial or radial) for a
+* DrawingML gradient (EP16b) and add it to `doc`. The pattern's `/Matrix` is the
+* shape's CTM and the shading `/Coords` are in the shape's local space.
+*
+* @param gradient The gradient fill (kind, angle, colour stops).
+* @param bbox     The shape's local-space bounding box, from {@link shapeBbox}.
+* @param ctm      The shape's current transformation matrix, used as `/Matrix`.
+* @returns A reference to the `/Pattern` object, for a `/Pattern cs /Pn scn` fill.
+*/
 function buildGradientPattern(doc, gradient, bbox, ctm) {
 	const fnRef = doc.add(buildRamp(gradient.stops));
 	const shading = gradient.kind === "radial" ? radialShading(bbox, fnRef) : axialShading(gradient.angle ?? 0, bbox, fnRef);

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

@@ -1,25 +1,61 @@
 import { PdfDict, PdfRef } from './objects.js';
 import { PdfDocument } from './writer.js';
+/** The signature-dictionary metadata stamped at placeholder time by {@link addSignaturePlaceholder}. */
 export interface SignaturePlaceholder {
     readonly reason?: string;
     readonly location?: string;
+    /** Signer name recorded in the dictionary (`/Name`). */
     readonly name?: string;
     readonly contactInfo?: string;
+    /** Claimed signing time (→ `/M` and the CMS `signingTime` attribute). */
     readonly signingTime?: Date;
+    /** Signature field name (default `"Signature1"`). */
     readonly fieldName?: string;
+    /** Bytes reserved for the `/Contents` signature hole (default 8192). */
     readonly reserveBytes?: number;
 }
+/** The signing key material consumed by {@link signPdf}. */
 export interface SignerCredentials {
+    /** Signer's X.509 certificate (DER). */
     readonly certificate: Uint8Array;
+    /**
+     * WebCrypto private key. An RSASSA-PKCS1-v1_5 key (default) or — when
+     * `algorithm` is `'ecdsa'` — an ECDSA key (P-256/P-384/P-521).
+     */
     readonly privateKey: CryptoKey;
+    /** Signature algorithm of the key (default `'rsa'`). */
     readonly algorithm?: 'rsa' | 'ecdsa';
+    /** Optional chain certificates (DER) to embed alongside the signer cert. */
     readonly extraCertificates?: ReadonlyArray<Uint8Array>;
     readonly signingTime?: Date;
 }
+/** Converter convenience: everything needed to emit a placeholder and sign in one call. */
 export interface SignatureOptions extends SignaturePlaceholder, SignerCredentials {
 }
+/**
+ * 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).
+ */
 export declare function addSignaturePlaceholder(doc: PdfDocument, ph: SignaturePlaceholder, pageRef: PdfRef): {
     readonly fieldRef: PdfRef;
     readonly acroForm: PdfDict;
 };
+/**
+ * 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.
+ */
 export declare function signPdf(pdf: Uint8Array, cred: SignerCredentials): Promise<Uint8Array>;

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}`);