modern-pdf-lib 0.14.0 → 0.15.0

package/dist/index.cjs

@@ -1,10 +1,11 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 const require_pdfPage = require('./pdfPage-DBfdinTR.cjs');
 const require_pdfCatalog = require('./pdfCatalog-COKoYQ8C.cjs');
-const require_libdeflateWasm = require('./libdeflateWasm-OkNoqBnO.cjs');
+const require_libdeflateWasm = require('./libdeflateWasm-Enus0G1k.cjs');
 const require_fontSubset = require('./fontSubset-pFc8Dueu.cjs');
-const require_pngEmbed = require('./pngEmbed-OYyOe_W0.cjs');
+const require_pngEmbed = require('./pngEmbed-10m4CfBU.cjs');
 const require_fflateAdapter = require('./fflateAdapter-AHC_S3cb.cjs');
+const require_bridge = require('./bridge-DUcJFVsk.cjs');
 let fflate = require("fflate");
 
 //#region src/core/pdfWriter.ts
@@ -4827,10 +4828,10 @@ async function tryLoadLibdeflate() {
 	if (libdeflateAttempted) return libdeflateEngine;
 	libdeflateAttempted = true;
 	try {
-		const { LibdeflateWasm: LibdeflateCtor, initDeflateWasm } = await Promise.resolve().then(() => require("./libdeflateWasm-OkNoqBnO.cjs")).then((n) => n.libdeflateWasm_exports);
+		const { LibdeflateWasm: LibdeflateCtor, initDeflateWasm } = await Promise.resolve().then(() => require("./libdeflateWasm-Enus0G1k.cjs")).then((n) => n.libdeflateWasm_exports);
 		let customBytes;
 		try {
-			const { getWasmLoaderConfig } = await Promise.resolve().then(() => require("./loader-_fqS-TmT.cjs"));
+			const { getWasmLoaderConfig } = await Promise.resolve().then(() => require("./loader-CKlBOHma.cjs"));
 			customBytes = getWasmLoaderConfig().moduleBytes?.["libdeflate"];
 		} catch {}
 		await initDeflateWasm(customBytes);
@@ -6307,15 +6308,76 @@ function padPassword(password) {
 	return result;
 }
 /**
-* Truncate a UTF-8 password to 127 bytes for R=5/R=6 (SASLprep would
-* be ideal but we approximate with simple truncation as most PDF
-* libraries do).
+* Prepare a password for R=5/R=6 (AES-256) using SASLprep (RFC 4013).
+*
+* ISO 32000-2 SS7.6.3.1 requires SASLprep normalization for passwords
+* used with encryption revision 5 and 6.  The steps are:
+*
+* 1. Map: Convert non-ASCII space characters to U+0020, remove
+*    "commonly mapped to nothing" characters (RFC 3454 B.1).
+* 2. Normalize: Apply Unicode NFKC normalization.
+* 3. Prohibit: Reject characters from RFC 3454 prohibited tables.
+* 4. Bidi: Check bidirectional string rules.
+*
+* The result is truncated to 127 UTF-8 bytes per the PDF spec.
 */
 function preparePasswordV5(password) {
-	const encoded = new TextEncoder().encode(password);
+	const prepared = saslprep(password);
+	const encoded = new TextEncoder().encode(prepared);
 	return encoded.length > 127 ? encoded.subarray(0, 127) : encoded;
 }
 /**
+* Simplified SASLprep (RFC 4013) profile of stringprep (RFC 3454).
+*
+* Covers the mapping, normalization, and prohibited-character steps
+* needed for PDF password preparation.  Bidi checking is omitted
+* since PDF passwords are typically LTR and the spec allows
+* implementations to skip it.
+*
+* @internal
+*/
+function saslprep(input) {
+	let mapped = "";
+	for (const ch of input) {
+		const cp = ch.codePointAt(0);
+		if (isMappedToNothing(cp)) continue;
+		if (isNonAsciiSpace(cp)) {
+			mapped += " ";
+			continue;
+		}
+		mapped += ch;
+	}
+	const normalized = mapped.normalize("NFKC");
+	for (const ch of normalized) {
+		const cp = ch.codePointAt(0);
+		if (isProhibited(cp)) throw new Error(`Password contains prohibited character U+${cp.toString(16).toUpperCase().padStart(4, "0")} (SASLprep)`);
+	}
+	return normalized;
+}
+/** RFC 3454 Table B.1 — Commonly mapped to nothing. */
+function isMappedToNothing(cp) {
+	return cp === 173 || cp === 6150 || cp === 8203 || cp === 8288 || cp === 65279 || cp === 847 || cp === 6155 || cp === 6156 || cp === 6157 || cp === 8204 || cp === 8205 || cp >= 65024 && cp <= 65039;
+}
+/** RFC 3454 Table C.1.2 — Non-ASCII space characters. */
+function isNonAsciiSpace(cp) {
+	return cp === 160 || cp === 5760 || cp === 8192 || cp === 8193 || cp === 8194 || cp === 8195 || cp === 8196 || cp === 8197 || cp === 8198 || cp === 8199 || cp === 8200 || cp === 8201 || cp === 8202 || cp === 8239 || cp === 8287 || cp === 12288;
+}
+/**
+* RFC 3454 prohibited tables (C.2.1, C.2.2, C.3, C.4, C.5, C.6, C.7, C.8, C.9).
+* Simplified to the ranges most likely to appear in passwords.
+*/
+function isProhibited(cp) {
+	if (cp <= 31 || cp === 127) return true;
+	if (cp >= 128 && cp <= 159 || cp === 1757 || cp === 1807 || cp === 6158 || cp >= 8204 && cp <= 8205 || cp >= 8232 && cp <= 8233 || cp >= 8288 && cp <= 8291 || cp >= 8298 && cp <= 8303 || cp === 65279 || cp >= 65529 && cp <= 65532 || cp >= 119155 && cp <= 119162) return true;
+	if (cp >= 57344 && cp <= 63743 || cp >= 983040 && cp <= 1048573 || cp >= 1048576 && cp <= 1114109) return true;
+	if (cp >= 64976 && cp <= 65007 || (cp & 65535) === 65534 || (cp & 65535) === 65535) return true;
+	if (cp >= 55296 && cp <= 57343) return true;
+	if (cp === 65529 || cp === 65530 || cp === 65531 || cp === 65532) return true;
+	if (cp === 832 || cp === 833 || cp === 8206 || cp === 8207 || cp >= 8234 && cp <= 8238 || cp >= 8298 && cp <= 8303) return true;
+	if (cp === 917505 || cp >= 917536 && cp <= 917631) return true;
+	return false;
+}
+/**
 * Concatenate multiple Uint8Arrays into one.
 */
 function concat$1(...arrays) {
@@ -6594,11 +6656,33 @@ async function computeEncryptionKeyR6(password, dict, isOwner) {
 	}
 }
 /**
+* LRU cache for file encryption keys.
+*
+* Keyed on a hash derived from password + encryption dict parameters,
+* so re-opening the same PDF with the same password skips the expensive
+* key derivation (especially for R=6 which runs 64+ rounds of AES+SHA).
+*/
+const fileKeyCache = /* @__PURE__ */ new Map();
+const FILE_KEY_CACHE_MAX = 32;
+/**
+* Build a cache key string from the inputs that uniquely identify
+* a key derivation result.
+*/
+function buildCacheKey(password, dict, fileId) {
+	const oHex = Array.from(dict.ownerKey.subarray(0, 16), (b) => b.toString(16).padStart(2, "0")).join("");
+	const uHex = Array.from(dict.userKey.subarray(0, 16), (b) => b.toString(16).padStart(2, "0")).join("");
+	const fHex = Array.from(fileId.subarray(0, 16), (b) => b.toString(16).padStart(2, "0")).join("");
+	return `${dict.revision}:${dict.permissions}:${password}:${oHex}:${uHex}:${fHex}`;
+}
+/**
 * Compute the file encryption key from a password and encryption dict.
 *
 * Tries the password as both user and owner password. Returns the key
 * on the first successful match, or throws if neither works.
 *
+* Results are cached so that re-opening the same PDF with the same
+* password skips the expensive key derivation.
+*
 * @param password  The password to try.
 * @param dict      Encryption dictionary values.
 * @param fileId    The first element of the /ID array (unused for R>=5).
@@ -6606,23 +6690,35 @@ async function computeEncryptionKeyR6(password, dict, isOwner) {
 * @throws          If the password is incorrect.
 */
 async function computeFileEncryptionKey(password, dict, fileId) {
+	const ck = buildCacheKey(password, dict, fileId);
+	const cached = fileKeyCache.get(ck);
+	if (cached) return cached.slice();
+	let result;
 	if (dict.revision >= 6) {
 		const userKey = await computeEncryptionKeyR6(password, dict, false);
-		if (userKey) return userKey;
-		const ownerKey = await computeEncryptionKeyR6(password, dict, true);
-		if (ownerKey) return ownerKey;
-		throw new Error("Incorrect password for R=6 encryption");
-	}
-	if (dict.revision === 5) {
+		if (userKey) result = userKey;
+		else {
+			const ownerKey = await computeEncryptionKeyR6(password, dict, true);
+			if (ownerKey) result = ownerKey;
+			else throw new Error("Incorrect password for R=6 encryption");
+		}
+	} else if (dict.revision === 5) {
 		const userKey = await computeEncryptionKeyR5(password, dict, false);
-		if (userKey) return userKey;
-		const ownerKey = await computeEncryptionKeyR5(password, dict, true);
-		if (ownerKey) return ownerKey;
-		throw new Error("Incorrect password for R=5 encryption");
-	}
-	if (await verifyUserPassword(password, dict, fileId)) return computeEncryptionKeyR2R4(password, dict, fileId);
-	if (await verifyOwnerPassword(password, dict, fileId)) return computeEncryptionKeyR2R4Bytes(recoverUserKeyFromOwner(password, dict), dict, fileId);
-	throw new Error("Incorrect password");
+		if (userKey) result = userKey;
+		else {
+			const ownerKey = await computeEncryptionKeyR5(password, dict, true);
+			if (ownerKey) result = ownerKey;
+			else throw new Error("Incorrect password for R=5 encryption");
+		}
+	} else if (await verifyUserPassword(password, dict, fileId)) result = computeEncryptionKeyR2R4(password, dict, fileId);
+	else if (await verifyOwnerPassword(password, dict, fileId)) result = computeEncryptionKeyR2R4Bytes(recoverUserKeyFromOwner(password, dict), dict, fileId);
+	else throw new Error("Incorrect password");
+	if (fileKeyCache.size >= FILE_KEY_CACHE_MAX) {
+		const firstKey = fileKeyCache.keys().next().value;
+		if (firstKey !== void 0) fileKeyCache.delete(firstKey);
+	}
+	fileKeyCache.set(ck, result.slice());
+	return result;
 }
 /**
 * Compute encryption key from raw password bytes (already padded/recovered).
@@ -6885,6 +6981,15 @@ var PdfEncryptionHandler = class PdfEncryptionHandler {
 	perms;
 	/** The file ID (first element of /ID array). */
 	fileId;
+	/**
+	* Cache for per-object derived keys (V=1-4 only).
+	* Key: `(objNum << 16) | genNum` — unique integer per object.
+	* Value: the derived encryption key.
+	*
+	* Avoids recomputing MD5(fileKey + objNum + genNum [+ sAlT]) for
+	* every string and stream in the same object.
+	*/
+	objectKeyCache = /* @__PURE__ */ new Map();
 	constructor(params) {
 		this.fileKey = params.fileKey;
 		this.version = params.version;
@@ -7037,6 +7142,9 @@ var PdfEncryptionHandler = class PdfEncryptionHandler {
 	*/
 	deriveObjectKey(objNum, genNum) {
 		if (this.version === 5) return this.fileKey;
+		const cacheKey = objNum << 16 | genNum;
+		const cached = this.objectKeyCache.get(cacheKey);
+		if (cached) return cached;
 		const extra = this.useAes ? 4 : 0;
 		const input = new Uint8Array(this.fileKey.length + 5 + extra);
 		input.set(this.fileKey, 0);
@@ -7054,7 +7162,9 @@ var PdfEncryptionHandler = class PdfEncryptionHandler {
 		}
 		const hash = md5(input);
 		const keyLen = Math.min(this.keyLengthBits / 8 + 5, 16);
-		return hash.subarray(0, keyLen);
+		const key = hash.subarray(0, keyLen);
+		this.objectKeyCache.set(cacheKey, key);
+		return key;
 	}
 	/**
 	* Encrypt raw data for a specific object.
@@ -9882,7 +9992,7 @@ function isAccessible(issues) {
 * @param data  The bytes to hash.
 * @returns     A hex string hash.
 */
-function hashBytes(data) {
+function hashBytes$1(data) {
 	let hash = 2166136261;
 	for (let i = 0; i < data.length; i++) {
 		hash ^= data[i];
@@ -9974,7 +10084,7 @@ function remapRef$1(sourceRef, context) {
 	}
 	let streamHash;
 	if (sourceObj.kind === "stream") {
-		streamHash = hashBytes(sourceObj.data);
+		streamHash = hashBytes$1(sourceObj.data);
 		const dedup = context.hashMap.get(streamHash);
 		if (dedup) {
 			context.refMap.set(sourceRef.objectNumber, dedup);
@@ -10216,23 +10326,73 @@ function findStringForward(data, needle, startOffset) {
 	return -1;
 }
 /**
-* Prepare a PDF for signing by appending a signature dictionary
-* via incremental update.
-*
-* This function:
-* 1. Appends a new signature field and value to the PDF
-* 2. Inserts an empty `/Contents` placeholder of the specified size
-* 3. Computes the `/ByteRange` that excludes the `/Contents` value
+* Build a PDF content stream for a visible signature appearance.
 *
-* The resulting PDF bytes can be hashed (excluding the placeholder gap)
-* and the hash can be signed.
+* Renders a bordered rectangle with optional background color and
+* text lines rendered in Helvetica.
 *
-* @param pdfBytes           The original PDF file bytes.
-* @param signatureFieldName The name for the signature field.
-* @param placeholderSize    Size in bytes for the signature. Default 8192.
-* @returns                  The prepared PDF and ByteRange info.
+* @internal
+*/
+function buildSignatureAppearanceStream(options) {
+	const [, , w, h] = options.rect;
+	const fontSize = options.fontSize ?? 10;
+	const borderWidth = options.borderWidth ?? 1;
+	const borderColor = options.borderColor ?? [
+		0,
+		0,
+		0
+	];
+	const bgColor = options.backgroundColor;
+	const lines = options.textLines;
+	const ops = [];
+	ops.push("q");
+	if (bgColor) {
+		ops.push(`${n$5(bgColor[0])} ${n$5(bgColor[1])} ${n$5(bgColor[2])} rg`);
+		ops.push(`0 0 ${n$5(w)} ${n$5(h)} re`);
+		ops.push("f");
+	}
+	if (borderWidth > 0) {
+		ops.push(`${n$5(borderColor[0])} ${n$5(borderColor[1])} ${n$5(borderColor[2])} RG`);
+		ops.push(`${n$5(borderWidth)} w`);
+		const bw2 = borderWidth / 2;
+		ops.push(`${n$5(bw2)} ${n$5(bw2)} ${n$5(w - borderWidth)} ${n$5(h - borderWidth)} re`);
+		ops.push("S");
+	}
+	if (lines.length > 0) {
+		const margin = borderWidth + 4;
+		const lineHeight = fontSize * 1.2;
+		ops.push("BT");
+		ops.push(`/F1 ${n$5(fontSize)} Tf`);
+		ops.push("0 0 0 rg");
+		const startY = h - margin - fontSize;
+		for (let i = 0; i < lines.length; i++) {
+			const y = startY - i * lineHeight;
+			if (y < margin) break;
+			ops.push(`${n$5(margin)} ${n$5(y)} Td`);
+			ops.push(`(${escapePdfString(lines[i])}) Tj`);
+			ops.push(`${n$5(-margin)} ${n$5(-y)} Td`);
+		}
+		ops.push("ET");
+	}
+	ops.push("Q");
+	return ops.join("\n");
+}
+/**
+* Escape a string for use inside a PDF literal string `(...)`.
+* @internal
+*/
+function escapePdfString(str) {
+	return str.replace(/\\/g, "\\\\").replace(/\(/g, "\\(").replace(/\)/g, "\\)");
+}
+/**
+* Format a number for PDF operators (max 6 decimal places, no trailing zeros).
+* @internal
 */
-function prepareForSigning(pdfBytes, signatureFieldName, placeholderSize = 8192) {
+function n$5(value) {
+	if (Number.isInteger(value)) return value.toString();
+	return value.toFixed(6).replace(/\.?0+$/, "");
+}
+function prepareForSigning(pdfBytes, signatureFieldName, placeholderSize = 8192, appearance) {
 	const pdfStr = decoder$4.decode(pdfBytes);
 	const startxrefIdx = pdfStr.lastIndexOf("startxref");
 	if (startxrefIdx === -1) throw new Error("Cannot find startxref in PDF — file may be corrupted");
@@ -10249,9 +10409,21 @@ function prepareForSigning(pdfBytes, signatureFieldName, placeholderSize = 8192)
 	const infoMatch = pdfStr.match(/\/Info\s+(\d+)\s+(\d+)\s+R/);
 	const sigValueObjNum = originalSize;
 	const sigFieldObjNum = originalSize + 1;
-	const newSize = originalSize + 2;
+	let apStreamObjNum = -1;
+	let newSize = originalSize + 2;
+	if (appearance) {
+		apStreamObjNum = newSize;
+		newSize++;
+	}
 	const sigDictStr = buildSignatureDictString(placeholderSize, signatureFieldName);
-	const sigFieldDict = `<< /Type /Annot /Subtype /Widget /FT /Sig /T (${signatureFieldName}) /V ${sigValueObjNum} 0 R /F 132 /Rect [0 0 0 0] >>`;
+	let rectStr = "0 0 0 0";
+	if (appearance) {
+		const [x, y, w, h] = appearance.rect;
+		rectStr = `${x} ${y} ${x + w} ${y + h}`;
+	}
+	let sigFieldDict = `<< /Type /Annot /Subtype /Widget /FT /Sig /T (${signatureFieldName}) /V ${sigValueObjNum} 0 R /F 132 /Rect [${rectStr}]`;
+	if (appearance && apStreamObjNum >= 0) sigFieldDict += ` /AP << /N ${apStreamObjNum} 0 R >>`;
+	sigFieldDict += " >>";
 	let appendix = "\n";
 	const objOffsets = /* @__PURE__ */ new Map();
 	const sigValueStart = pdfBytes.length + encoder$3.encode(appendix).length;
@@ -10264,11 +10436,28 @@ function prepareForSigning(pdfBytes, signatureFieldName, placeholderSize = 8192)
 	appendix += `${sigFieldObjNum} 0 obj\n`;
 	appendix += sigFieldDict;
 	appendix += `\nendobj\n`;
+	let apStreamStart = -1;
+	if (appearance && apStreamObjNum >= 0) {
+		apStreamStart = pdfBytes.length + encoder$3.encode(appendix).length;
+		objOffsets.set(apStreamObjNum, apStreamStart);
+		const apContent = buildSignatureAppearanceStream(appearance);
+		const [, , w, h] = appearance.rect;
+		appendix += `${apStreamObjNum} 0 obj\n`;
+		appendix += `<< /Type /XObject /Subtype /Form /BBox [0 0 ${w} ${h}]`;
+		appendix += ` /Resources << /Font << /F1 << /Type /Font /Subtype /Type1 /BaseFont /Helvetica >> >> >>`;
+		appendix += ` /Length ${apContent.length} >>\n`;
+		appendix += `stream\n`;
+		appendix += apContent;
+		appendix += `\nendstream\n`;
+		appendix += `endobj\n`;
+	}
 	const xrefOffset = pdfBytes.length + encoder$3.encode(appendix).length;
+	const objCount = appearance ? 3 : 2;
 	appendix += "xref\n";
-	appendix += `${sigValueObjNum} 2\n`;
+	appendix += `${sigValueObjNum} ${objCount}\n`;
 	appendix += `${sigValueStart.toString().padStart(10, "0")} 00000 n \n`;
 	appendix += `${sigFieldStart.toString().padStart(10, "0")} 00000 n \n`;
+	if (appearance && apStreamStart >= 0) appendix += `${apStreamStart.toString().padStart(10, "0")} 00000 n \n`;
 	appendix += "trailer\n";
 	appendix += "<<\n";
 	appendix += `/Size ${newSize}\n`;
@@ -11058,7 +11247,32 @@ function parsePkcs7ForCert(pkcs7Bytes) {
 */
 async function signPdf(pdfBytes, fieldName, options) {
 	const hashAlgorithm = options.hashAlgorithm ?? "SHA-256";
-	const { preparedPdf, byteRange } = prepareForSigning(pdfBytes, fieldName, 8192);
+	let prepareAppearance;
+	if (options.appearance) {
+		const ap = options.appearance;
+		let textLines = ap.text;
+		if (!textLines) {
+			textLines = [];
+			try {
+				const { subjectCN } = extractIssuerAndSerial(options.certificate);
+				if (subjectCN) textLines.push(`Signed by: ${subjectCN}`);
+			} catch {
+				textLines.push("Digitally Signed");
+			}
+			if (options.reason) textLines.push(`Reason: ${options.reason}`);
+			if (options.location) textLines.push(`Location: ${options.location}`);
+			textLines.push(`Date: ${(/* @__PURE__ */ new Date()).toISOString().substring(0, 10)}`);
+		}
+		prepareAppearance = {
+			rect: ap.rect,
+			textLines,
+			fontSize: ap.fontSize,
+			backgroundColor: ap.backgroundColor,
+			borderColor: ap.borderColor,
+			borderWidth: ap.borderWidth
+		};
+	}
+	const { preparedPdf, byteRange } = prepareForSigning(pdfBytes, fieldName, 8192, prepareAppearance);
 	return embedSignature(preparedPdf, await buildPkcs7Signature(await computeSignatureHash(preparedPdf, byteRange.byteRange, hashAlgorithm), {
 		signerInfo: {
 			certificate: options.certificate,
@@ -18870,6 +19084,30 @@ var PdfDocument = class PdfDocument {
 		return imageRef;
 	}
 	/**
+	* Embed an image, auto-detecting the format from file headers.
+	*
+	* Inspects the first bytes to determine whether the data is PNG or JPEG,
+	* then delegates to {@link embedPng} or {@link embedJpeg} accordingly.
+	*
+	* @param imageData  Raw image file bytes (PNG or JPEG).
+	* @returns          An {@link ImageRef} to pass to `page.drawImage()`.
+	* @throws           If the image format cannot be detected.
+	*
+	* @example
+	* ```ts
+	* const bytes = new Uint8Array(await readFile('photo.jpg'));
+	* const image = await pdf.embedImage(bytes);
+	* page.drawImage(image, { x: 50, y: 400, width: 200, height: 150 });
+	* ```
+	*/
+	async embedImage(imageData) {
+		const data = imageData instanceof ArrayBuffer ? new Uint8Array(imageData) : imageData;
+		if (data.length < 4) throw new Error("Image data too short to detect format");
+		if (data[0] === 137 && data[1] === 80 && data[2] === 78 && data[3] === 71) return this.embedPng(data);
+		if (data[0] === 255 && data[1] === 216 && data[2] === 255) return this.embedJpeg(data);
+		throw new Error(`Unsupported image format. Expected PNG (89 50 4E 47) or JPEG (FF D8 FF), got ${Array.from(data.subarray(0, 4)).map((b) => b.toString(16).padStart(2, "0")).join(" ")}.`);
+	}
+	/**
 	* Embed pages from another PDF as Form XObjects.
 	*
 	* Each embedded page is turned into a self-contained Form XObject that
@@ -21770,6 +22008,261 @@ var PdfRedactAnnotation = class PdfRedactAnnotation extends require_pdfPage.PdfA
 	}
 };
 
+//#endregion
+//#region src/annotation/types/popupAnnotation.ts
+/**
+* @module annotation/types/popupAnnotation
+*
+* Popup annotation — a floating window that displays the text of its
+* parent annotation (typically a text/sticky note annotation).
+*
+* Popup annotations have no appearance of their own; the PDF viewer
+* renders them as a resizable window near the parent annotation.
+*
+* Reference: PDF 1.7 spec, Section 12.5.6.14 (Popup Annotations).
+*/
+/**
+* A popup annotation (subtype /Popup).
+*
+* Displays a floating window containing the text of its parent
+* annotation. The parent annotation references this popup via its
+* `/Popup` entry, and this popup references its parent via `/Parent`.
+*/
+var PdfPopupAnnotation = class PdfPopupAnnotation extends require_pdfPage.PdfAnnotation {
+	constructor(dict) {
+		super("Popup", dict);
+	}
+	/**
+	* Create a new popup annotation.
+	*
+	* @param options.open  Whether the popup is initially open. Default: false.
+	* @param options.parent  Reference to the parent annotation (set after registration).
+	*/
+	static create(options) {
+		const annot = new PdfPopupAnnotation(require_pdfPage.buildAnnotationDict("Popup", options));
+		if (options.open !== void 0) annot.setOpen(options.open);
+		return annot;
+	}
+	/**
+	* Create a PdfPopupAnnotation from an existing dictionary.
+	*/
+	static fromDict(dict, _resolver) {
+		return new PdfPopupAnnotation(dict);
+	}
+	/** Whether the popup is initially open. */
+	isOpen() {
+		const obj = this.dict.get("/Open");
+		if (obj && obj.kind === "bool") return obj.value;
+		return false;
+	}
+	/** Set the initial open state. */
+	setOpen(open) {
+		this.dict.set("/Open", require_pdfCatalog.PdfBool.of(open));
+	}
+	/**
+	* Set the parent annotation reference.
+	* The parent is the annotation whose text this popup displays.
+	*/
+	setParent(parentRef) {
+		this.dict.set("/Parent", parentRef);
+	}
+	/** Get the parent annotation reference, if set. */
+	getParent() {
+		const obj = this.dict.get("/Parent");
+		if (obj && obj.kind === "ref") return obj;
+	}
+};
+
+//#endregion
+//#region src/annotation/types/caretAnnotation.ts
+/**
+* @module annotation/types/caretAnnotation
+*
+* Caret annotation — marks a text insertion point in the document.
+*
+* A caret annotation indicates where text should be inserted. It is
+* typically used in document review workflows to suggest additions.
+* The annotation renders as a caret (^) symbol at the specified
+* location.
+*
+* Reference: PDF 1.7 spec, Section 12.5.6.11 (Caret Annotations).
+*/
+/**
+* A caret annotation (subtype /Caret).
+*
+* Marks an insertion point in the text. Used in review workflows
+* to indicate where new content should be added.
+*/
+var PdfCaretAnnotation = class PdfCaretAnnotation extends require_pdfPage.PdfAnnotation {
+	constructor(dict) {
+		super("Caret", dict);
+	}
+	/**
+	* Create a new caret annotation.
+	*
+	* @param options.symbol  The caret symbol. Default: 'None'.
+	* @param options.caretRect  The inner rectangle (RD) that describes
+	*   the difference between the annotation rect and the actual caret
+	*   position. Format: [left, bottom, right, top] insets.
+	*/
+	static create(options) {
+		const annot = new PdfCaretAnnotation(require_pdfPage.buildAnnotationDict("Caret", options));
+		if (options.symbol !== void 0) annot.setSymbol(options.symbol);
+		if (options.caretRect !== void 0) annot.setCaretRect(options.caretRect);
+		return annot;
+	}
+	/**
+	* Create a PdfCaretAnnotation from an existing dictionary.
+	*/
+	static fromDict(dict, _resolver) {
+		return new PdfCaretAnnotation(dict);
+	}
+	/** Get the caret symbol. Defaults to 'None'. */
+	getSymbol() {
+		const obj = this.dict.get("/Sy");
+		if (obj && obj.kind === "name") {
+			if ((obj.value.startsWith("/") ? obj.value.slice(1) : obj.value) === "P") return "P";
+		}
+		return "None";
+	}
+	/** Set the caret symbol. */
+	setSymbol(symbol) {
+		this.dict.set("/Sy", require_pdfCatalog.PdfName.of(symbol));
+	}
+	/**
+	* Get the inner rectangle differences (RD entry).
+	* Returns [left, bottom, right, top] insets from the annotation rect.
+	*/
+	getCaretRect() {
+		const obj = this.dict.get("/RD");
+		if (obj && obj.kind === "array" && obj.items.length === 4) return obj.items.map((item) => {
+			if (item.kind === "number") return item.value;
+			return 0;
+		});
+	}
+	/** Set the inner rectangle differences (RD entry). */
+	setCaretRect(rd) {
+		this.dict.set("/RD", require_pdfCatalog.PdfArray.of(rd.map(require_pdfCatalog.PdfNumber.of)));
+	}
+};
+
+//#endregion
+//#region src/annotation/types/fileAttachmentAnnotation.ts
+/**
+* @module annotation/types/fileAttachmentAnnotation
+*
+* File attachment annotation — embeds a file as an inline annotation
+* on a page, displayed as a clickable icon.
+*
+* Unlike document-level attachments (via `attachFile()`), file attachment
+* annotations are positioned on a specific page and rendered as an icon
+* that users can click to open or save the embedded file.
+*
+* Reference: PDF 1.7 spec, Section 12.5.6.15 (File Attachment Annotations).
+*/
+/**
+* A file attachment annotation (subtype /FileAttachment).
+*
+* Embeds a file directly in the annotation, rendered as a clickable
+* icon on the page. When the user clicks the icon, the PDF viewer
+* allows them to open or save the embedded file.
+*/
+var PdfFileAttachmentAnnotation = class PdfFileAttachmentAnnotation extends require_pdfPage.PdfAnnotation {
+	/** The raw file data to embed. */
+	fileData;
+	/** The filename to display. */
+	fileName;
+	/** Optional MIME type. */
+	mimeType;
+	/** Optional file description. */
+	fileDescription;
+	constructor(dict) {
+		super("FileAttachment", dict);
+	}
+	/**
+	* Create a new file attachment annotation.
+	*
+	* @param options.file       The file data to embed.
+	* @param options.fileName   The filename (e.g., 'invoice.xml').
+	* @param options.mimeType   Optional MIME type (e.g., 'application/xml').
+	* @param options.description Optional description of the file.
+	* @param options.icon       Icon to display. Default: 'GraphPushPin'.
+	*/
+	static create(options) {
+		const annot = new PdfFileAttachmentAnnotation(require_pdfPage.buildAnnotationDict("FileAttachment", options));
+		annot.fileData = options.file;
+		annot.fileName = options.fileName;
+		annot.mimeType = options.mimeType;
+		annot.fileDescription = options.description;
+		if (options.icon !== void 0) annot.setIcon(options.icon);
+		return annot;
+	}
+	/**
+	* Create a PdfFileAttachmentAnnotation from an existing dictionary.
+	*/
+	static fromDict(dict, _resolver) {
+		return new PdfFileAttachmentAnnotation(dict);
+	}
+	/** Get the icon name. Defaults to 'GraphPushPin'. */
+	getIcon() {
+		const obj = this.dict.get("/Name");
+		if (obj && obj.kind === "name") {
+			const val = obj.value.startsWith("/") ? obj.value.slice(1) : obj.value;
+			if ([
+				"GraphPushPin",
+				"PaperclipTag",
+				"Paperclip",
+				"Tag"
+			].includes(val)) return val;
+		}
+		return "GraphPushPin";
+	}
+	/** Set the icon name. */
+	setIcon(icon) {
+		this.dict.set("/Name", require_pdfCatalog.PdfName.of(icon));
+	}
+	/** Get the filename, if set. */
+	getFileName() {
+		const fs = this.dict.get("/FS");
+		if (fs && fs.kind === "dict") {
+			const uf = fs.get("/UF");
+			if (uf && uf.kind === "string") return uf.value;
+			const f = fs.get("/F");
+			if (f && f.kind === "string") return f.value;
+		}
+		return this.fileName;
+	}
+	/**
+	* Build the file specification dictionary and register the embedded
+	* file stream. Call this before serializing the annotation.
+	*
+	* @param registry  The document's object registry.
+	* @returns  The annotation dict with `/FS` referencing the file.
+	*/
+	buildFileSpec(registry) {
+		if (!this.fileData || !this.fileName) return this.dict;
+		const efStreamDict = new require_pdfCatalog.PdfDict();
+		efStreamDict.set("/Type", require_pdfCatalog.PdfName.of("EmbeddedFile"));
+		if (this.mimeType) efStreamDict.set("/Subtype", require_pdfCatalog.PdfName.of(this.mimeType.replace("/", "#2F")));
+		const params = new require_pdfCatalog.PdfDict();
+		params.set("/Size", require_pdfCatalog.PdfNumber.of(this.fileData.length));
+		efStreamDict.set("/Params", params);
+		const efStream = new require_pdfCatalog.PdfStream(efStreamDict, this.fileData);
+		const efRef = registry.register(efStream);
+		const efDict = new require_pdfCatalog.PdfDict();
+		efDict.set("/F", efRef);
+		const fsDict = new require_pdfCatalog.PdfDict();
+		fsDict.set("/Type", require_pdfCatalog.PdfName.of("Filespec"));
+		fsDict.set("/F", require_pdfCatalog.PdfString.literal(this.fileName));
+		fsDict.set("/UF", require_pdfCatalog.PdfString.literal(this.fileName));
+		fsDict.set("/EF", efDict);
+		if (this.fileDescription) fsDict.set("/Desc", require_pdfCatalog.PdfString.literal(this.fileDescription));
+		const fsRef = registry.register(fsDict);
+		this.dict.set("/FS", fsRef);
+		return this.dict;
+	}
+};
+
 //#endregion
 //#region src/parser/textExtractor.ts
 /**
@@ -23854,66 +24347,1197 @@ function addTrailerId(data) {
 }
 
 //#endregion
-//#region src/errors.ts
+//#region src/assets/image/imageOptimize.ts
 /**
-* @module errors
+* Downscale an image to fit within the specified dimensions.
 *
-* Typed error classes for common failure modes in the modern-pdf library.
-* Each error class extends the native `Error` and carries a descriptive
-* `name` so callers can use `instanceof` checks or `error.name` comparisons.
+* If the image is already smaller than the target dimensions, it is
+* returned unchanged.
 *
-* All constructors accept an optional `ErrorOptions` parameter to support
-* error chaining via the standard `{ cause }` option (ES2022+).
+* @param image   - The raw image pixel data.
+* @param options - Downscaling options (target dimensions, algorithm).
+* @returns The downscaled image, or the original if no scaling needed.
 *
-* These match the pdf-lib error hierarchy for API compatibility.
-*/
-/**
-* Thrown when attempting to load or manipulate an encrypted PDF without
-* providing the correct password.
+* @example
+* ```ts
+* const result = downscaleImage(rawImage, {
+*   maxWidth: 1024,
+*   maxHeight: 768,
+*   algorithm: 'bilinear',
+* });
+* ```
 */
-var EncryptedPdfError = class extends Error {
-	name = "EncryptedPdfError";
-	constructor(message = "The PDF is encrypted. Please provide a password.", options) {
-		super(message, options);
+function downscaleImage(image, options = {}) {
+	const target = computeTargetDimensions$1(image.width, image.height, options);
+	if (target.width >= image.width && target.height >= image.height) return image;
+	switch (options.algorithm ?? "bilinear") {
+		case "nearest": return resampleNearest(image, target.width, target.height);
+		case "bilinear": return resampleBilinear(image, target.width, target.height);
+		case "lanczos": return resampleLanczos(image, target.width, target.height);
+		default: return resampleBilinear(image, target.width, target.height);
 	}
-};
+}
 /**
-* Thrown when a font operation requires an embedded font but none has been
-* registered or the font reference is invalid.
+* Recompress raw image pixel data using the specified format.
+*
+* @param image   - The raw image pixel data.
+* @param options - Recompression options (format, quality).
+* @returns The compressed image data.
+*
+* @example
+* ```ts
+* const result = await recompressImage(rawImage, {
+*   format: 'deflate',
+*   compressionLevel: 9,
+* });
+* ```
 */
-var FontNotEmbeddedError = class extends Error {
-	name = "FontNotEmbeddedError";
-	constructor(fontName, options) {
-		super(fontName ? `The font "${fontName}" has not been embedded in this document.` : "No font has been embedded. Call doc.embedFont() first.", options);
+async function recompressImage(image, options = {}) {
+	switch (options.format ?? "deflate") {
+		case "deflate": return recompressDeflate(image, options.compressionLevel ?? 6);
+		case "jpeg": return recompressJpeg(image, options.quality ?? 85, options.progressive ?? false, options.chromaSubsampling ?? "4:2:0");
+		default: return {
+			data: image.pixels,
+			width: image.width,
+			height: image.height,
+			channels: image.channels,
+			format: "raw",
+			wasOptimized: false
+		};
 	}
-};
+}
 /**
-* Thrown when attempting to use a page from a different document without
-* first copying it.
+* Run the full image optimization pipeline: downscale then recompress.
+*
+* @param image   - The raw image pixel data.
+* @param options - Combined optimization options.
+* @returns The optimized result.
 */
-var ForeignPageError = class extends Error {
-	name = "ForeignPageError";
-	constructor(options) {
-		super("The page belongs to a different document. Use doc.copyPages() to import pages from another document before adding them.", options);
-	}
-};
+async function optimizeImage(image, options = {}) {
+	if (options.skipBelowBytes && image.pixels.length < options.skipBelowBytes) return {
+		data: image.pixels,
+		width: image.width,
+		height: image.height,
+		channels: image.channels,
+		format: "raw",
+		wasOptimized: false
+	};
+	return recompressImage(downscaleImage(image, options), options);
+}
 /**
-* Thrown when attempting to remove a page from a document that has no pages.
+* Standard JPEG luminance quantization table (Table K.1 from JPEG spec)
+* at quality 50, scaled to quality 100 = all-ones.
+* @internal
 */
-var RemovePageFromEmptyDocumentError = class extends Error {
-	name = "RemovePageFromEmptyDocumentError";
-	constructor(options) {
-		super("Cannot remove a page from a document with no pages.", options);
-	}
-};
+const STANDARD_LUMINANCE_QT = [
+	16,
+	11,
+	10,
+	16,
+	24,
+	40,
+	51,
+	61,
+	12,
+	12,
+	14,
+	19,
+	26,
+	58,
+	60,
+	55,
+	14,
+	13,
+	16,
+	24,
+	40,
+	57,
+	69,
+	56,
+	14,
+	17,
+	22,
+	29,
+	51,
+	87,
+	80,
+	62,
+	18,
+	22,
+	37,
+	56,
+	68,
+	109,
+	103,
+	77,
+	24,
+	35,
+	55,
+	64,
+	81,
+	104,
+	113,
+	92,
+	49,
+	64,
+	78,
+	87,
+	103,
+	121,
+	120,
+	101,
+	72,
+	92,
+	95,
+	98,
+	112,
+	100,
+	103,
+	99
+];
 /**
-* Thrown when looking up a form field by name that does not exist.
-*/
-var NoSuchFieldError = class extends Error {
-	name = "NoSuchFieldError";
-	constructor(fieldName, options) {
-		super(`No form field named "${fieldName}" exists in this document.`, options);
-	}
+* Estimate the JPEG quality level (1–100) from the quantization tables
+* embedded in a JPEG file.
+*
+* Parses the DQT (Define Quantization Table, marker 0xFFDB) segments
+* from the raw JPEG bytes and compares the table values against the
+* standard JPEG luminance quantization table to estimate the quality
+* factor that was used during encoding.
+*
+* If no DQT marker is found, returns `undefined`.
+*
+* @param jpegBytes - Raw JPEG file bytes.
+* @returns Estimated quality 1–100, or `undefined` if no DQT is found.
+*
+* @example
+* ```ts
+* import { estimateJpegQuality } from 'modern-pdf-lib';
+*
+* const quality = estimateJpegQuality(jpegBytes);
+* if (quality !== undefined) {
+*   console.log(`Estimated JPEG quality: ${quality}`);
+* }
+* ```
+*/
+function estimateJpegQuality(jpegBytes) {
+	if (jpegBytes.length < 2 || jpegBytes[0] !== 255 || jpegBytes[1] !== 216) return;
+	let offset = 2;
+	let bestTable;
+	while (offset < jpegBytes.length - 1) {
+		if (jpegBytes[offset] !== 255) {
+			offset++;
+			continue;
+		}
+		const marker = jpegBytes[offset + 1];
+		if (marker === 255) {
+			offset++;
+			continue;
+		}
+		if (marker === 0 || marker === 1 || marker >= 208 && marker <= 217) {
+			offset += 2;
+			continue;
+		}
+		if (marker === 218) break;
+		if (offset + 3 >= jpegBytes.length) break;
+		const segLen = jpegBytes[offset + 2] << 8 | jpegBytes[offset + 3];
+		if (marker === 219) {
+			let pos = offset + 4;
+			const segEnd = offset + 2 + segLen;
+			while (pos < segEnd && pos + 1 < jpegBytes.length) {
+				const pqTq = jpegBytes[pos];
+				const precision = pqTq >> 4 & 15;
+				const tableId = pqTq & 15;
+				pos++;
+				const tableSize = 64 * (precision === 0 ? 1 : 2);
+				if (pos + tableSize > jpegBytes.length) break;
+				const table = [];
+				for (let i = 0; i < 64; i++) if (precision === 0) table.push(jpegBytes[pos + i]);
+				else table.push(jpegBytes[pos + i * 2] << 8 | jpegBytes[pos + i * 2 + 1]);
+				pos += tableSize;
+				if (tableId === 0 || !bestTable) bestTable = table;
+			}
+		}
+		offset += 2 + segLen;
+	}
+	if (!bestTable) return void 0;
+	let totalRatio = 0;
+	let count = 0;
+	for (let i = 0; i < 64; i++) {
+		const std = STANDARD_LUMINANCE_QT[i];
+		const actual = bestTable[i];
+		if (std === 0 || actual === 0) continue;
+		const scaleFactor = actual * 100 / std;
+		totalRatio += scaleFactor;
+		count++;
+	}
+	if (count === 0) return void 0;
+	const avgScale = totalRatio / count;
+	let quality;
+	if (avgScale < 100) quality = (200 - avgScale) / 2;
+	else quality = 5e3 / avgScale;
+	return Math.max(1, Math.min(100, Math.round(quality)));
+}
+/**
+* Compute target dimensions from options, preserving aspect ratio.
+* @internal
+*/
+function computeTargetDimensions$1(srcWidth, srcHeight, options) {
+	let targetWidth = srcWidth;
+	let targetHeight = srcHeight;
+	if (options.targetDpi && options.printWidth && options.printHeight) {
+		const printWidthInches = options.printWidth / 72;
+		const printHeightInches = options.printHeight / 72;
+		const dpiWidth = Math.round(printWidthInches * options.targetDpi);
+		const dpiHeight = Math.round(printHeightInches * options.targetDpi);
+		targetWidth = Math.min(targetWidth, dpiWidth);
+		targetHeight = Math.min(targetHeight, dpiHeight);
+	}
+	if (options.maxWidth && targetWidth > options.maxWidth) {
+		const scale = options.maxWidth / targetWidth;
+		targetWidth = options.maxWidth;
+		targetHeight = Math.round(targetHeight * scale);
+	}
+	if (options.maxHeight && targetHeight > options.maxHeight) {
+		const scale = options.maxHeight / targetHeight;
+		targetHeight = options.maxHeight;
+		targetWidth = Math.round(targetWidth * scale);
+	}
+	targetWidth = Math.max(1, targetWidth);
+	targetHeight = Math.max(1, targetHeight);
+	return {
+		width: targetWidth,
+		height: targetHeight
+	};
+}
+/**
+* Nearest-neighbor resampling.
+* @internal
+*/
+function resampleNearest(src, dstWidth, dstHeight) {
+	const channels = src.channels;
+	const dst = new Uint8Array(dstWidth * dstHeight * channels);
+	const xRatio = src.width / dstWidth;
+	const yRatio = src.height / dstHeight;
+	for (let y = 0; y < dstHeight; y++) {
+		const srcY = Math.min(Math.floor(y * yRatio), src.height - 1);
+		for (let x = 0; x < dstWidth; x++) {
+			const srcX = Math.min(Math.floor(x * xRatio), src.width - 1);
+			const srcIdx = (srcY * src.width + srcX) * channels;
+			const dstIdx = (y * dstWidth + x) * channels;
+			for (let c = 0; c < channels; c++) dst[dstIdx + c] = src.pixels[srcIdx + c];
+		}
+	}
+	return {
+		pixels: dst,
+		width: dstWidth,
+		height: dstHeight,
+		channels,
+		bitsPerChannel: src.bitsPerChannel
+	};
+}
+/**
+* Bilinear interpolation resampling.
+* @internal
+*/
+function resampleBilinear(src, dstWidth, dstHeight) {
+	const channels = src.channels;
+	const dst = new Uint8Array(dstWidth * dstHeight * channels);
+	const xRatio = (src.width - 1) / Math.max(1, dstWidth - 1);
+	const yRatio = (src.height - 1) / Math.max(1, dstHeight - 1);
+	for (let y = 0; y < dstHeight; y++) {
+		const srcYf = y * yRatio;
+		const srcY0 = Math.floor(srcYf);
+		const srcY1 = Math.min(srcY0 + 1, src.height - 1);
+		const yFrac = srcYf - srcY0;
+		for (let x = 0; x < dstWidth; x++) {
+			const srcXf = x * xRatio;
+			const srcX0 = Math.floor(srcXf);
+			const srcX1 = Math.min(srcX0 + 1, src.width - 1);
+			const xFrac = srcXf - srcX0;
+			const dstIdx = (y * dstWidth + x) * channels;
+			for (let c = 0; c < channels; c++) {
+				const topLeft = src.pixels[(srcY0 * src.width + srcX0) * channels + c];
+				const topRight = src.pixels[(srcY0 * src.width + srcX1) * channels + c];
+				const bottomLeft = src.pixels[(srcY1 * src.width + srcX0) * channels + c];
+				const bottomRight = src.pixels[(srcY1 * src.width + srcX1) * channels + c];
+				const top = topLeft + (topRight - topLeft) * xFrac;
+				const value = top + (bottomLeft + (bottomRight - bottomLeft) * xFrac - top) * yFrac;
+				dst[dstIdx + c] = Math.round(Math.max(0, Math.min(255, value)));
+			}
+		}
+	}
+	return {
+		pixels: dst,
+		width: dstWidth,
+		height: dstHeight,
+		channels,
+		bitsPerChannel: src.bitsPerChannel
+	};
+}
+/**
+* Lanczos kernel function.
+*
+* Computes the Lanczos windowed sinc value for a given distance `x`
+* and window size `a`. For Lanczos-3, `a = 3`.
+*
+* @param x - Distance from the center sample.
+* @param a - Window radius (3 for Lanczos-3).
+* @returns   The kernel weight.
+* @internal
+*/
+function lanczos(x, a = 3) {
+	if (x === 0) return 1;
+	if (Math.abs(x) >= a) return 0;
+	const pix = Math.PI * x;
+	return Math.sin(pix) / pix * (Math.sin(pix / a) / (pix / a));
+}
+/**
+* Lanczos-3 resampling.
+*
+* Uses a 6-tap (a=3) windowed sinc filter in both dimensions for
+* high-quality downscaling. This is the best quality option but
+* also the slowest.
+*
+* @internal
+*/
+function resampleLanczos(src, dstWidth, dstHeight) {
+	const channels = src.channels;
+	const a = 3;
+	const dst = new Uint8Array(dstWidth * dstHeight * channels);
+	const xRatio = src.width / dstWidth;
+	const yRatio = src.height / dstHeight;
+	for (let y = 0; y < dstHeight; y++) {
+		const srcYf = (y + .5) * yRatio - .5;
+		for (let x = 0; x < dstWidth; x++) {
+			const srcXf = (x + .5) * xRatio - .5;
+			const dstIdx = (y * dstWidth + x) * channels;
+			const sum = new Float64Array(channels);
+			let weightSum = 0;
+			const yStart = Math.floor(srcYf) - a + 1;
+			const yEnd = Math.floor(srcYf) + a;
+			const xStart = Math.floor(srcXf) - a + 1;
+			const xEnd = Math.floor(srcXf) + a;
+			for (let sy = yStart; sy <= yEnd; sy++) {
+				const wy = lanczos(srcYf - sy, a);
+				if (wy === 0) continue;
+				const clampedY = Math.max(0, Math.min(src.height - 1, sy));
+				for (let sx = xStart; sx <= xEnd; sx++) {
+					const wx = lanczos(srcXf - sx, a);
+					if (wx === 0) continue;
+					const w = wx * wy;
+					const clampedX = Math.max(0, Math.min(src.width - 1, sx));
+					const srcIdx = (clampedY * src.width + clampedX) * channels;
+					for (let c = 0; c < channels; c++) sum[c] = (sum[c] ?? 0) + src.pixels[srcIdx + c] * w;
+					weightSum += w;
+				}
+			}
+			if (weightSum > 0) for (let c = 0; c < channels; c++) dst[dstIdx + c] = Math.round(Math.max(0, Math.min(255, sum[c] / weightSum)));
+		}
+	}
+	return {
+		pixels: dst,
+		width: dstWidth,
+		height: dstHeight,
+		channels,
+		bitsPerChannel: src.bitsPerChannel
+	};
+}
+/**
+* Recompress image data using deflate (for PDF FlateDecode).
+* @internal
+*/
+async function recompressDeflate(image, level) {
+	if (typeof CompressionStream !== "undefined") {
+		const cs = new CompressionStream("deflate");
+		const writer = cs.writable.getWriter();
+		const reader = cs.readable.getReader();
+		const chunks = [];
+		writer.write(new Uint8Array(image.pixels)).catch(() => {});
+		writer.close().catch(() => {});
+		while (true) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			chunks.push(value);
+		}
+		const totalLength = chunks.reduce((sum, c) => sum + c.length, 0);
+		const result = new Uint8Array(totalLength);
+		let pos = 0;
+		for (const chunk of chunks) {
+			result.set(chunk, pos);
+			pos += chunk.length;
+		}
+		return {
+			data: result,
+			width: image.width,
+			height: image.height,
+			channels: image.channels,
+			format: "deflate",
+			wasOptimized: true
+		};
+	}
+	try {
+		const { deflateSync } = await import("fflate");
+		return {
+			data: deflateSync(image.pixels, { level }),
+			width: image.width,
+			height: image.height,
+			channels: image.channels,
+			format: "deflate",
+			wasOptimized: true
+		};
+	} catch {
+		return {
+			data: image.pixels,
+			width: image.width,
+			height: image.height,
+			channels: image.channels,
+			format: "raw",
+			wasOptimized: false
+		};
+	}
+}
+/**
+* Recompress image data as JPEG.
+*
+* Uses the JPEG WASM encoder when available (initialized via
+* `initJpegWasm()` or `initWasm({ jpeg: true })`).  When WASM is not
+* loaded, returns the input data unchanged with `wasOptimized: false`.
+*
+* @param image   - The raw image pixel data.
+* @param quality - JPEG quality 1–100.
+* @param progressive - Encode as progressive JPEG (default: false).
+* @param chromaSubsampling - Chroma subsampling mode (default: '4:2:0').
+* @returns The JPEG-encoded result, or raw data if WASM is unavailable.
+* @internal
+*/
+async function recompressJpeg(image, quality, progressive = false, chromaSubsampling = "4:2:0") {
+	const { encodeJpegWasm, isJpegWasmReady } = await Promise.resolve().then(() => require("./bridge-DUcJFVsk.cjs")).then((n) => n.bridge_exports);
+	if (isJpegWasmReady()) {
+		let pixels = image.pixels;
+		let channels = image.channels;
+		if (image.channels === 4 && image.colorSpace === "cmyk") {
+			pixels = convertCmykToRgb(image.pixels, image.width, image.height);
+			channels = 3;
+		}
+		const jpegBytes = encodeJpegWasm(pixels, image.width, image.height, channels, quality, progressive, chromaSubsampling);
+		if (jpegBytes) return {
+			data: jpegBytes,
+			width: image.width,
+			height: image.height,
+			channels,
+			format: "jpeg",
+			wasOptimized: true
+		};
+	}
+	return {
+		data: image.pixels,
+		width: image.width,
+		height: image.height,
+		channels: image.channels,
+		format: "raw",
+		wasOptimized: false
+	};
+}
+/**
+* Convert CMYK pixel data to RGB.
+*
+* Uses the standard CMYK→RGB formula (inverted CMYK, Adobe convention):
+* ```
+* R = 255 × (1 − C/255) × (1 − K/255)
+* G = 255 × (1 − M/255) × (1 − K/255)
+* B = 255 × (1 − Y/255) × (1 − K/255)
+* ```
+*
+* @param pixels  - CMYK pixel data (4 bytes per pixel, row-major).
+* @param width   - Image width.
+* @param height  - Image height.
+* @returns RGB pixel data (3 bytes per pixel).
+* @internal
+*/
+function convertCmykToRgb(pixels, width, height) {
+	const pixelCount = width * height;
+	const rgb = new Uint8Array(pixelCount * 3);
+	for (let i = 0; i < pixelCount; i++) {
+		const c = pixels[i * 4] / 255;
+		const m = pixels[i * 4 + 1] / 255;
+		const y = pixels[i * 4 + 2] / 255;
+		const k = pixels[i * 4 + 3] / 255;
+		rgb[i * 3] = Math.round(255 * (1 - c) * (1 - k));
+		rgb[i * 3 + 1] = Math.round(255 * (1 - m) * (1 - k));
+		rgb[i * 3 + 2] = Math.round(255 * (1 - y) * (1 - k));
+	}
+	return rgb;
+}
+
+//#endregion
+//#region src/assets/image/imageExtract.ts
+/**
+* Resolve the color space name from a `/ColorSpace` entry.
+* Handles both simple names (`/DeviceRGB`) and array forms
+* (`[/ICCBased ...]`, `[/Indexed /DeviceRGB ...]`).
+* @internal
+*/
+function resolveColorSpace(csEntry, registry) {
+	if (!csEntry) return "DeviceRGB";
+	if (csEntry.kind === "ref") {
+		const resolved = registry.resolve(csEntry);
+		if (!resolved) return "DeviceRGB";
+		return resolveColorSpace(resolved, registry);
+	}
+	if (csEntry.kind === "name") return csEntry.value.replace(/^\//, "");
+	if (csEntry.kind === "array") {
+		const arr = csEntry;
+		const first = arr.items[0];
+		if (first && first.kind === "name") {
+			const csName = first.value.replace(/^\//, "");
+			if (csName === "ICCBased") {
+				const profileRef = arr.items[1];
+				if (profileRef && profileRef.kind === "ref") {
+					const profile = registry.resolve(profileRef);
+					if (profile && profile.kind === "stream") {
+						const n = profile.dict.get("/N");
+						if (n && n.kind === "number") {
+							const channels = n.value;
+							if (channels === 1) return "DeviceGray";
+							if (channels === 3) return "DeviceRGB";
+							if (channels === 4) return "DeviceCMYK";
+						}
+					}
+				}
+				return "DeviceRGB";
+			}
+			if (csName === "Indexed") return "Indexed";
+			return csName;
+		}
+	}
+	return "DeviceRGB";
+}
+/**
+* Determine the number of channels from a color space name.
+* @internal
+*/
+function channelsFromColorSpace(colorSpace) {
+	switch (colorSpace) {
+		case "DeviceGray":
+		case "CalGray": return 1;
+		case "DeviceCMYK": return 4;
+		case "Indexed": return 1;
+		default: return 3;
+	}
+}
+/**
+* Extract all image XObjects from a PDF document.
+*
+* Walks every page's `/Resources /XObject` dictionary and collects
+* metadata for each image XObject found.
+*
+* @param doc - A parsed `PdfDocument`.
+* @returns An array of `ImageInfo` objects, one per image XObject.
+*
+* @example
+* ```ts
+* import { loadPdf, extractImages } from 'modern-pdf-lib';
+*
+* const doc = await loadPdf(pdfBytes);
+* const images = extractImages(doc);
+*
+* for (const img of images) {
+*   console.log(`${img.name}: ${img.width}x${img.height} ${img.colorSpace} (${img.compressedSize} bytes)`);
+* }
+* ```
+*/
+function extractImages(doc) {
+	const images = [];
+	const seenRefs = /* @__PURE__ */ new Set();
+	const pages = doc.getPages();
+	for (let pageIndex = 0; pageIndex < pages.length; pageIndex++) {
+		const page = pages[pageIndex];
+		const resources = page.getOriginalResources();
+		if (!resources) continue;
+		let xObjDict;
+		const xObjEntry = resources.get("/XObject");
+		if (!xObjEntry) continue;
+		if (xObjEntry.kind === "dict") xObjDict = xObjEntry;
+		else if (xObjEntry.kind === "ref") {
+			const resolved = page.getRegistry().resolve(xObjEntry);
+			if (resolved && resolved.kind === "dict") xObjDict = resolved;
+		}
+		if (!xObjDict) continue;
+		const registry = page.getRegistry();
+		for (const [name, value] of xObjDict) {
+			let ref;
+			let stream;
+			if (value.kind === "ref") {
+				ref = value;
+				if (seenRefs.has(ref.objectNumber)) continue;
+				const resolved = registry.resolve(ref);
+				if (resolved && resolved.kind === "stream") stream = resolved;
+			} else if (value.kind === "stream") stream = value;
+			if (!stream || !ref) continue;
+			const subtype = stream.dict.get("/Subtype");
+			if (!subtype || subtype.kind !== "name") continue;
+			if (subtype.value !== "/Image") continue;
+			const widthObj = stream.dict.get("/Width");
+			const heightObj = stream.dict.get("/Height");
+			const bpcObj = stream.dict.get("/BitsPerComponent");
+			const width = widthObj && widthObj.kind === "number" ? widthObj.value : 0;
+			const height = heightObj && heightObj.kind === "number" ? heightObj.value : 0;
+			const bitsPerComponent = bpcObj && bpcObj.kind === "number" ? bpcObj.value : 8;
+			const colorSpace = resolveColorSpace(stream.dict.get("/ColorSpace"), registry);
+			const channels = channelsFromColorSpace(colorSpace);
+			const { filters } = getStreamFilters(stream.dict);
+			seenRefs.add(ref.objectNumber);
+			images.push({
+				stream,
+				ref,
+				name,
+				pageIndex,
+				width,
+				height,
+				bitsPerComponent,
+				colorSpace,
+				channels,
+				filters,
+				compressedSize: stream.data.length
+			});
+		}
+	}
+	return images;
+}
+/**
+* Decode image stream data into raw pixels.
+*
+* For DCTDecode (JPEG) streams, returns the raw JPEG bytes (not decoded
+* to pixels) since JPEG decoding requires the WASM module.
+*
+* For FlateDecode and other filters, fully decodes the stream.
+*
+* @param imageInfo - An `ImageInfo` from `extractImages()`.
+* @returns The decoded stream data.
+*/
+function decodeImageStream(imageInfo) {
+	if (imageInfo.filters.length === 0) return imageInfo.stream.data;
+	return decodeStream(imageInfo.stream.data, imageInfo.filters, null);
+}
+
+//#endregion
+//#region src/assets/image/grayscaleDetect.ts
+/**
+* @module assets/image/grayscaleDetect
+*
+* Grayscale detection and conversion for image optimization.
+*
+* Detects RGB images where all pixels are effectively grayscale
+* (R ≈ G ≈ B) and converts them to single-channel grayscale,
+* reducing data size by ~66%.
+*
+* No Buffer — uses Uint8Array exclusively.
+*/
+/**
+* Check whether an RGB/RGBA image is effectively grayscale.
+*
+* Scans all pixels and checks if R, G, and B channels are within
+* `tolerance` of each other. If ≥99% of pixels pass, the image
+* is considered grayscale.
+*
+* @param pixels    - Raw pixel data (row-major, channel-interleaved).
+* @param width     - Image width in pixels.
+* @param height    - Image height in pixels.
+* @param channels  - Number of channels: 3 (RGB) or 4 (RGBA).
+* @param tolerance - Maximum allowed difference between R, G, and B
+*                    values for a pixel to be considered gray.
+*                    Default: `2`.
+* @returns `true` if the image is effectively grayscale.
+*
+* @example
+* ```ts
+* import { isGrayscaleImage, convertToGrayscale } from 'modern-pdf-lib';
+*
+* if (isGrayscaleImage(pixels, width, height, 3)) {
+*   const grayPixels = convertToGrayscale(pixels, width, height, 3);
+*   // grayPixels has 1 byte per pixel instead of 3
+* }
+* ```
+*/
+function isGrayscaleImage(pixels, width, height, channels, tolerance = 2) {
+	const pixelCount = width * height;
+	const maxNonGray = Math.floor(pixelCount * .01);
+	let nonGrayCount = 0;
+	for (let i = 0; i < pixelCount; i++) {
+		const r = pixels[i * channels];
+		const g = pixels[i * channels + 1];
+		const b = pixels[i * channels + 2];
+		if (Math.max(r, g, b) - Math.min(r, g, b) > tolerance) {
+			nonGrayCount++;
+			if (nonGrayCount > maxNonGray) return false;
+		}
+	}
+	return true;
+}
+/**
+* Convert an RGB/RGBA image to single-channel grayscale.
+*
+* Uses the ITU-R BT.601 luma formula:
+* ```
+* gray = 0.299 × R + 0.587 × G + 0.114 × B
+* ```
+*
+* The alpha channel (if present) is discarded.
+*
+* @param pixels   - Raw pixel data (row-major, channel-interleaved).
+* @param width    - Image width in pixels.
+* @param height   - Image height in pixels.
+* @param channels - Number of channels: 3 (RGB) or 4 (RGBA).
+* @returns Grayscale pixel data (1 byte per pixel).
+*/
+function convertToGrayscale(pixels, width, height, channels) {
+	const pixelCount = width * height;
+	const gray = new Uint8Array(pixelCount);
+	for (let i = 0; i < pixelCount; i++) {
+		const r = pixels[i * channels];
+		const g = pixels[i * channels + 1];
+		const b = pixels[i * channels + 2];
+		gray[i] = Math.round(.299 * r + .587 * g + .114 * b);
+	}
+	return gray;
+}
+
+//#endregion
+//#region src/assets/image/batchOptimize.ts
+/** Minimum image size to bother optimizing (10 KB). */
+const SMALL_IMAGE_THRESHOLD = 10240;
+/**
+* Optimize all images in a PDF document by recompressing them as JPEG.
+*
+* Walks every image XObject in the document, decodes its pixel data,
+* recompresses it as JPEG using the WASM encoder (if available), and
+* replaces the stream data in-place when the result is smaller.
+*
+* **Requires the JPEG WASM module to be initialized** via
+* `initJpegWasm()` or `initWasm({ jpeg: true })`.  Without it,
+* no images will be optimized (all will be skipped).
+*
+* @param doc     - A parsed `PdfDocument` (from `loadPdf()`).
+* @param options - Optimization settings.
+* @returns A report summarizing the optimization results.
+*
+* @example
+* ```ts
+* import { loadPdf, initWasm, optimizeAllImages } from 'modern-pdf-lib';
+*
+* await initWasm({ jpeg: true });
+*
+* const doc = await loadPdf(pdfBytes);
+* const report = await optimizeAllImages(doc);
+*
+* console.log(`Optimized ${report.optimizedImages} of ${report.totalImages} images`);
+* console.log(`Savings: ${report.savings.toFixed(1)}%`);
+*
+* const optimizedBytes = await doc.save();
+* ```
+*/
+async function optimizeAllImages(doc, options = {}) {
+	const quality = options.quality ?? 80;
+	const minSavingsPercent = options.minSavingsPercent ?? 10;
+	const skipSmall = options.skipSmallImages ?? false;
+	const progressive = options.progressive ?? false;
+	const chromaSubsampling = options.chromaSubsampling ?? "4:2:0";
+	const { encodeJpegWasm, isJpegWasmReady } = await Promise.resolve().then(() => require("./bridge-DUcJFVsk.cjs")).then((n) => n.bridge_exports);
+	const { decodeJpegWasm } = await Promise.resolve().then(() => require("./bridge-DUcJFVsk.cjs")).then((n) => n.bridge_exports);
+	const images = extractImages(doc);
+	const perImage = [];
+	let totalOriginal = 0;
+	let totalNew = 0;
+	let optimizedCount = 0;
+	for (const img of images) {
+		totalOriginal += img.compressedSize;
+		if (!isJpegWasmReady()) {
+			perImage.push({
+				name: img.name,
+				pageIndex: img.pageIndex,
+				originalSize: img.compressedSize,
+				newSize: img.compressedSize,
+				skipped: true,
+				reason: "JPEG WASM encoder not initialized"
+			});
+			totalNew += img.compressedSize;
+			continue;
+		}
+		if (skipSmall && img.compressedSize < SMALL_IMAGE_THRESHOLD) {
+			perImage.push({
+				name: img.name,
+				pageIndex: img.pageIndex,
+				originalSize: img.compressedSize,
+				newSize: img.compressedSize,
+				skipped: true,
+				reason: `Below size threshold (${SMALL_IMAGE_THRESHOLD} bytes)`
+			});
+			totalNew += img.compressedSize;
+			continue;
+		}
+		if (img.bitsPerComponent !== 8) {
+			perImage.push({
+				name: img.name,
+				pageIndex: img.pageIndex,
+				originalSize: img.compressedSize,
+				newSize: img.compressedSize,
+				skipped: true,
+				reason: `Unsupported bits per component: ${img.bitsPerComponent}`
+			});
+			totalNew += img.compressedSize;
+			continue;
+		}
+		if (img.colorSpace === "Indexed") {
+			perImage.push({
+				name: img.name,
+				pageIndex: img.pageIndex,
+				originalSize: img.compressedSize,
+				newSize: img.compressedSize,
+				skipped: true,
+				reason: "Indexed color space not suitable for JPEG"
+			});
+			totalNew += img.compressedSize;
+			continue;
+		}
+		let pixels;
+		let channels = img.channels;
+		try {
+			if (img.filters[0] === "DCTDecode") {
+				const decoded = decodeJpegWasm(img.stream.data);
+				if (!decoded) {
+					perImage.push({
+						name: img.name,
+						pageIndex: img.pageIndex,
+						originalSize: img.compressedSize,
+						newSize: img.compressedSize,
+						skipped: true,
+						reason: "Failed to decode existing JPEG"
+					});
+					totalNew += img.compressedSize;
+					continue;
+				}
+				pixels = decoded.pixels;
+				channels = decoded.channels;
+			} else pixels = decodeImageStream(img);
+		} catch {
+			perImage.push({
+				name: img.name,
+				pageIndex: img.pageIndex,
+				originalSize: img.compressedSize,
+				newSize: img.compressedSize,
+				skipped: true,
+				reason: "Failed to decode image stream"
+			});
+			totalNew += img.compressedSize;
+			continue;
+		}
+		const expectedLen = img.width * img.height * channels;
+		if (pixels.length !== expectedLen) {
+			perImage.push({
+				name: img.name,
+				pageIndex: img.pageIndex,
+				originalSize: img.compressedSize,
+				newSize: img.compressedSize,
+				skipped: true,
+				reason: `Pixel data length mismatch: got ${pixels.length}, expected ${expectedLen}`
+			});
+			totalNew += img.compressedSize;
+			continue;
+		}
+		if (channels === 4 && img.colorSpace === "DeviceCMYK") {
+			const rgb = new Uint8Array(img.width * img.height * 3);
+			for (let i = 0; i < img.width * img.height; i++) {
+				const c = pixels[i * 4] / 255;
+				const m = pixels[i * 4 + 1] / 255;
+				const y = pixels[i * 4 + 2] / 255;
+				const k = pixels[i * 4 + 3] / 255;
+				rgb[i * 3] = Math.round(255 * (1 - c) * (1 - k));
+				rgb[i * 3 + 1] = Math.round(255 * (1 - m) * (1 - k));
+				rgb[i * 3 + 2] = Math.round(255 * (1 - y) * (1 - k));
+			}
+			pixels = rgb;
+			channels = 3;
+		}
+		if (options.autoGrayscale && (channels === 3 || channels === 4)) {
+			if (isGrayscaleImage(pixels, img.width, img.height, channels)) {
+				pixels = convertToGrayscale(pixels, img.width, img.height, channels);
+				channels = 1;
+			}
+		}
+		const jpegBytes = encodeJpegWasm(pixels, img.width, img.height, channels, quality, progressive, chromaSubsampling);
+		if (!jpegBytes) {
+			perImage.push({
+				name: img.name,
+				pageIndex: img.pageIndex,
+				originalSize: img.compressedSize,
+				newSize: img.compressedSize,
+				skipped: true,
+				reason: "JPEG encoding failed"
+			});
+			totalNew += img.compressedSize;
+			continue;
+		}
+		const savingsPercent = (img.compressedSize - jpegBytes.length) / img.compressedSize * 100;
+		if (savingsPercent < minSavingsPercent) {
+			perImage.push({
+				name: img.name,
+				pageIndex: img.pageIndex,
+				originalSize: img.compressedSize,
+				newSize: img.compressedSize,
+				skipped: true,
+				reason: `Savings ${savingsPercent.toFixed(1)}% below threshold ${minSavingsPercent}%`
+			});
+			totalNew += img.compressedSize;
+			continue;
+		}
+		img.stream.data = jpegBytes;
+		img.stream.syncLength();
+		const dict = img.stream.dict;
+		dict.set("/Filter", require_pdfCatalog.PdfName.of("/DCTDecode"));
+		if (img.colorSpace === "DeviceCMYK" && channels === 3) dict.set("/ColorSpace", require_pdfCatalog.PdfName.of("/DeviceRGB"));
+		if (channels === 1) dict.set("/ColorSpace", require_pdfCatalog.PdfName.of("/DeviceGray"));
+		dict.delete("/DecodeParms");
+		if (img.colorSpace === "DeviceCMYK") dict.delete("/Decode");
+		optimizedCount++;
+		perImage.push({
+			name: img.name,
+			pageIndex: img.pageIndex,
+			originalSize: img.compressedSize,
+			newSize: jpegBytes.length,
+			skipped: false
+		});
+		totalNew += jpegBytes.length;
+	}
+	const overallSavings = totalOriginal > 0 ? (totalOriginal - totalNew) / totalOriginal * 100 : 0;
+	return {
+		totalImages: images.length,
+		optimizedImages: optimizedCount,
+		originalTotalBytes: totalOriginal,
+		optimizedTotalBytes: totalNew,
+		savings: overallSavings,
+		perImage
+	};
+}
+
+//#endregion
+//#region src/assets/image/deduplicateImages.ts
+/**
+* Compute a fast FNV-1a hash of a byte array.
+*
+* This is used instead of SHA-256 because:
+* 1. It's synchronous (no need for crypto.subtle)
+* 2. It's fast for large buffers
+* 3. We only need collision resistance within a single document
+*
+* Returns a 64-char hex string (two 32-bit hashes concatenated).
+* @internal
+*/
+function hashBytes(data) {
+	let h1 = 2166136261;
+	for (let i = 0; i < data.length; i++) {
+		h1 ^= data[i];
+		h1 = Math.imul(h1, 16777619);
+	}
+	let h2 = 16777619;
+	for (let i = data.length - 1; i >= 0; i--) {
+		h2 ^= data[i];
+		h2 = Math.imul(h2, 2166136261);
+	}
+	const h3 = data.length * 2654435769 | 0;
+	return (h1 >>> 0).toString(16).padStart(8, "0") + (h2 >>> 0).toString(16).padStart(8, "0") + (h3 >>> 0).toString(16).padStart(8, "0");
+}
+/**
+* Deduplicate identical images in a PDF document.
+*
+* Scans all image XObjects, hashes their compressed stream data (plus
+* dimensions and filter), and replaces duplicate references in page
+* resource dictionaries with the canonical (first-seen) copy.
+*
+* This operation modifies the document in-place. Duplicate streams
+* are not removed from the object registry (they become unreferenced
+* and will be omitted on save if the writer supports garbage collection).
+*
+* @param doc - A parsed `PdfDocument` (from `loadPdf()`).
+* @returns A report summarizing deduplication results.
+*
+* @example
+* ```ts
+* import { loadPdf, deduplicateImages } from 'modern-pdf-lib';
+*
+* const doc = await loadPdf(pdfBytes);
+* const report = await deduplicateImages(doc);
+*
+* console.log(`Removed ${report.duplicatesRemoved} duplicate images`);
+* console.log(`Saved ~${(report.bytesSaved / 1024).toFixed(0)} KB`);
+*
+* const optimizedBytes = await doc.save();
+* ```
+*/
+function deduplicateImages(doc) {
+	const images = extractImages(doc);
+	const hashToCanonical = /* @__PURE__ */ new Map();
+	const duplicates = [];
+	for (const img of images) {
+		const key = `${img.width}x${img.height}:${img.filters.join(",")}:` + hashBytes(img.stream.data);
+		const existing = hashToCanonical.get(key);
+		if (existing) duplicates.push({
+			image: img,
+			canonicalRef: existing.ref
+		});
+		else hashToCanonical.set(key, {
+			ref: img.ref,
+			size: img.compressedSize
+		});
+	}
+	let bytesSaved = 0;
+	for (const { image, canonicalRef } of duplicates) {
+		const page = doc.getPages()[image.pageIndex];
+		if (!page) continue;
+		const resources = page.getOriginalResources();
+		if (!resources) continue;
+		const xObjEntry = resources.get("/XObject");
+		if (!xObjEntry) continue;
+		let xObjDict;
+		if (xObjEntry.kind === "dict") xObjDict = xObjEntry;
+		else if (xObjEntry.kind === "ref") {
+			const resolved = page.getRegistry().resolve(xObjEntry);
+			if (resolved && resolved.kind === "dict") xObjDict = resolved;
+		}
+		if (!xObjDict) continue;
+		xObjDict.set(image.name, canonicalRef);
+		bytesSaved += image.compressedSize;
+	}
+	return {
+		totalImages: images.length,
+		uniqueImages: hashToCanonical.size,
+		duplicatesRemoved: duplicates.length,
+		bytesSaved
+	};
+}
+
+//#endregion
+//#region src/assets/image/dpiAnalyze.ts
+/**
+* Compute the effective DPI of an image given its pixel dimensions
+* and display dimensions in points.
+*
+* PDF uses 72 points per inch, so:
+* ```
+* DPI = imagePixels / (displayPoints / 72)
+* ```
+*
+* @param imageWidth    - Image width in pixels.
+* @param imageHeight   - Image height in pixels.
+* @param displayWidth  - Display width in PDF points (1/72 inch).
+* @param displayHeight - Display height in PDF points (1/72 inch).
+* @returns DPI information.
+*
+* @example
+* ```ts
+* import { computeImageDpi } from 'modern-pdf-lib';
+*
+* // A 3000×2000 image displayed at 4.17×2.78 inches (300×200 points)
+* const dpi = computeImageDpi(3000, 2000, 300, 200);
+* console.log(dpi.effectiveDpi); // 720
+* ```
+*/
+function computeImageDpi(imageWidth, imageHeight, displayWidth, displayHeight) {
+	const xDpi = displayWidth > 0 ? imageWidth / displayWidth * 72 : Infinity;
+	const yDpi = displayHeight > 0 ? imageHeight / displayHeight * 72 : Infinity;
+	return {
+		xDpi,
+		yDpi,
+		effectiveDpi: Math.min(xDpi, yDpi)
+	};
+}
+/**
+* Compute the target pixel dimensions for downscaling an image
+* to a maximum DPI at a given display size.
+*
+* @param imageWidth    - Current image width in pixels.
+* @param imageHeight   - Current image height in pixels.
+* @param displayWidth  - Display width in PDF points.
+* @param displayHeight - Display height in PDF points.
+* @param maxDpi        - Maximum allowed DPI.
+* @returns Target dimensions, or the original dimensions if no
+*          downscaling is needed.
+*/
+function computeTargetDimensions(imageWidth, imageHeight, displayWidth, displayHeight, maxDpi) {
+	const dpi = computeImageDpi(imageWidth, imageHeight, displayWidth, displayHeight);
+	if (dpi.effectiveDpi <= maxDpi || !isFinite(dpi.effectiveDpi)) return {
+		width: imageWidth,
+		height: imageHeight,
+		downscaled: false
+	};
+	const scale = maxDpi / dpi.effectiveDpi;
+	return {
+		width: Math.max(1, Math.round(imageWidth * scale)),
+		height: Math.max(1, Math.round(imageHeight * scale)),
+		downscaled: true
+	};
+}
+
+//#endregion
+//#region src/errors.ts
+/**
+* @module errors
+*
+* Typed error classes for common failure modes in the modern-pdf library.
+* Each error class extends the native `Error` and carries a descriptive
+* `name` so callers can use `instanceof` checks or `error.name` comparisons.
+*
+* All constructors accept an optional `ErrorOptions` parameter to support
+* error chaining via the standard `{ cause }` option (ES2022+).
+*
+* These match the pdf-lib error hierarchy for API compatibility.
+*/
+/**
+* Thrown when attempting to load or manipulate an encrypted PDF without
+* providing the correct password.
+*/
+var EncryptedPdfError = class extends Error {
+	name = "EncryptedPdfError";
+	constructor(message = "The PDF is encrypted. Please provide a password.", options) {
+		super(message, options);
+	}
+};
+/**
+* Thrown when a font operation requires an embedded font but none has been
+* registered or the font reference is invalid.
+*/
+var FontNotEmbeddedError = class extends Error {
+	name = "FontNotEmbeddedError";
+	constructor(fontName, options) {
+		super(fontName ? `The font "${fontName}" has not been embedded in this document.` : "No font has been embedded. Call doc.embedFont() first.", options);
+	}
+};
+/**
+* Thrown when attempting to use a page from a different document without
+* first copying it.
+*/
+var ForeignPageError = class extends Error {
+	name = "ForeignPageError";
+	constructor(options) {
+		super("The page belongs to a different document. Use doc.copyPages() to import pages from another document before adding them.", options);
+	}
+};
+/**
+* Thrown when attempting to remove a page from a document that has no pages.
+*/
+var RemovePageFromEmptyDocumentError = class extends Error {
+	name = "RemovePageFromEmptyDocumentError";
+	constructor(options) {
+		super("Cannot remove a page from a document with no pages.", options);
+	}
+};
+/**
+* Thrown when looking up a form field by name that does not exist.
+*/
+var NoSuchFieldError = class extends Error {
+	name = "NoSuchFieldError";
+	constructor(fieldName, options) {
+		super(`No form field named "${fieldName}" exists in this document.`, options);
+	}
 };
 /**
 * Thrown when a form field is accessed via the wrong typed getter
@@ -24021,15 +25645,18 @@ async function initWasm(options) {
 	if (options === void 0 || typeof options === "string" || options instanceof URL) return;
 	if (wasmInitialized) return;
 	const inits = [];
-	if (options.deflate || options.deflateWasm) inits.push(Promise.resolve().then(() => require("./libdeflateWasm-OkNoqBnO.cjs")).then((n) => n.libdeflateWasm_exports).then(async ({ initDeflateWasm }) => {
+	if (options.deflate || options.deflateWasm) inits.push(Promise.resolve().then(() => require("./libdeflateWasm-Enus0G1k.cjs")).then((n) => n.libdeflateWasm_exports).then(async ({ initDeflateWasm }) => {
 		await initDeflateWasm(options.deflateWasm);
 	}));
-	if (options.png || options.pngWasm) inits.push(Promise.resolve().then(() => require("./pngEmbed-OYyOe_W0.cjs")).then((n) => n.pngEmbed_exports).then(async ({ initPngWasm }) => {
+	if (options.png || options.pngWasm) inits.push(Promise.resolve().then(() => require("./pngEmbed-10m4CfBU.cjs")).then((n) => n.pngEmbed_exports).then(async ({ initPngWasm }) => {
 		await initPngWasm(options.pngWasm);
 	}));
 	if (options.fonts || options.fontWasm) inits.push(Promise.resolve().then(() => require("./fontSubset-pFc8Dueu.cjs")).then((n) => n.fontSubset_exports).then(async ({ initSubsetWasm }) => {
 		await initSubsetWasm(options.fontWasm);
 	}));
+	if (options.jpeg || options.jpegWasm) inits.push(Promise.resolve().then(() => require("./bridge-DUcJFVsk.cjs")).then((n) => n.bridge_exports).then(async ({ initJpegWasm }) => {
+		await initJpegWasm(options.jpegWasm);
+	}));
 	await Promise.all(inits);
 	wasmInitialized = true;
 }
@@ -24060,6 +25687,7 @@ exports.PdfAnnotation = require_pdfPage.PdfAnnotation;
 exports.PdfArray = require_pdfCatalog.PdfArray;
 exports.PdfBool = require_pdfCatalog.PdfBool;
 exports.PdfButtonField = PdfButtonField;
+exports.PdfCaretAnnotation = PdfCaretAnnotation;
 exports.PdfCheckboxField = PdfCheckboxField;
 exports.PdfCircleAnnotation = PdfCircleAnnotation;
 exports.PdfDict = require_pdfCatalog.PdfDict;
@@ -24067,6 +25695,7 @@ exports.PdfDocument = PdfDocument;
 exports.PdfDropdownField = PdfDropdownField;
 exports.PdfEncryptionHandler = PdfEncryptionHandler;
 exports.PdfField = PdfField;
+exports.PdfFileAttachmentAnnotation = PdfFileAttachmentAnnotation;
 exports.PdfForm = PdfForm;
 exports.PdfFreeTextAnnotation = PdfFreeTextAnnotation;
 exports.PdfHighlightAnnotation = PdfHighlightAnnotation;
@@ -24086,6 +25715,7 @@ exports.PdfPage = require_pdfPage.PdfPage;
 exports.PdfParseError = PdfParseError;
 exports.PdfPolyLineAnnotation = PdfPolyLineAnnotation;
 exports.PdfPolygonAnnotation = PdfPolygonAnnotation;
+exports.PdfPopupAnnotation = PdfPopupAnnotation;
 exports.PdfRadioGroup = PdfRadioGroup;
 exports.PdfRedactAnnotation = PdfRedactAnnotation;
 exports.PdfRef = require_pdfCatalog.PdfRef;
@@ -24156,9 +25786,12 @@ exports.colorToComponents = require_pdfPage.colorToComponents;
 exports.componentsToColor = require_pdfPage.componentsToColor;
 exports.computeFileEncryptionKey = computeFileEncryptionKey;
 exports.computeFontSize = computeFontSize;
+exports.computeImageDpi = computeImageDpi;
 exports.computeSignatureHash = computeSignatureHash;
+exports.computeTargetDimensions = computeTargetDimensions;
 exports.concatMatrix = require_pdfPage.concatMatrix;
 exports.concatTransformationMatrix = require_pdfPage.concatMatrix;
+exports.convertToGrayscale = convertToGrayscale;
 exports.copyPages = copyPages;
 exports.createAnnotation = require_pdfPage.createAnnotation;
 exports.createMarkedContentScope = require_pdfPage.createMarkedContentScope;
@@ -24168,10 +25801,14 @@ exports.cropPage = cropPage;
 exports.curveToFinal = require_pdfPage.curveToFinal;
 exports.curveToInitial = require_pdfPage.curveToInitial;
 exports.curveToOp = require_pdfPage.curveTo;
+exports.decodeImageStream = decodeImageStream;
+exports.decodeJpegWasm = require_bridge.decodeJpegWasm;
 exports.decodePermissions = decodePermissions;
 exports.decodeStream = decodeStream;
+exports.deduplicateImages = deduplicateImages;
 exports.degrees = require_pdfPage.degrees;
 exports.degreesToRadians = require_pdfPage.degreesToRadians;
+exports.downscaleImage = downscaleImage;
 exports.drawImageWithMatrix = require_pdfPage.drawImageWithMatrix;
 exports.drawImageXObject = require_pdfPage.drawImageXObject;
 exports.drawObject = require_pdfPage.drawXObject;
@@ -24182,6 +25819,7 @@ exports.embedPageAsFormXObject = embedPageAsFormXObject;
 exports.embedSignature = embedSignature;
 exports.encodeContextTag = encodeContextTag;
 exports.encodeInteger = encodeInteger;
+exports.encodeJpegWasm = require_bridge.encodeJpegWasm;
 exports.encodeLength = encodeLength;
 exports.encodeOID = encodeOID;
 exports.encodeOctetString = encodeOctetString;
@@ -24197,6 +25835,8 @@ exports.endMarkedContent = require_pdfPage.endMarkedContent;
 exports.endPathOp = require_pdfPage.endPath;
 exports.endText = require_pdfPage.endText;
 exports.enforcePdfA = enforcePdfA;
+exports.estimateJpegQuality = estimateJpegQuality;
+exports.extractImages = extractImages;
 exports.extractMetrics = extractMetrics;
 exports.extractText = extractText;
 exports.extractTextWithPositions = extractTextWithPositions;
@@ -24228,9 +25868,12 @@ exports.getPageSize = getPageSize;
 exports.getRedactionMarks = require_pdfPage.getRedactionMarks;
 exports.getSignatures = getSignatures;
 exports.grayscale = require_pdfPage.grayscale;
+exports.initJpegWasm = require_bridge.initJpegWasm;
 exports.initWasm = initWasm;
 exports.insertPage = insertPage;
 exports.isAccessible = isAccessible;
+exports.isGrayscaleImage = isGrayscaleImage;
+exports.isJpegWasmReady = require_bridge.isJpegWasmReady;
 exports.isLinearized = isLinearized;
 exports.isOpenTypeCFF = isOpenTypeCFF;
 exports.isTrueType = isTrueType;
@@ -24249,6 +25892,8 @@ exports.moveTextOp = require_pdfPage.moveText;
 exports.moveTextSetLeading = require_pdfPage.moveTextSetLeading;
 exports.moveToOp = require_pdfPage.moveTo;
 exports.nextLineOp = require_pdfPage.nextLine;
+exports.optimizeAllImages = optimizeAllImages;
+exports.optimizeImage = optimizeImage;
 exports.parseContentStream = parseContentStream;
 exports.parseSvg = require_pdfPage.parseSvg;
 exports.parseSvgColor = require_pdfPage.parseSvgColor;
@@ -24264,6 +25909,7 @@ exports.radialGradient = require_pdfPage.radialGradient;
 exports.radians = require_pdfPage.radians;
 exports.radiansToDegrees = require_pdfPage.radiansToDegrees;
 exports.rc4 = rc4;
+exports.recompressImage = recompressImage;
 exports.rectangleOp = require_pdfPage.rectangle;
 exports.removePage = removePage;
 exports.removePages = removePages;