modern-pdf-lib 0.14.0 → 0.15.0

package/dist/index.mjs

@@ -1,9 +1,10 @@
 import { $ as colorToComponents, $t as setTextMatrix, A as beginMarkedContent, At as fill, B as radians, Bt as setLineJoin, C as AnnotationFlags, Ct as closeFillEvenOddAndStroke, D as createAnnotation, Dt as curveToInitial, E as buildAnnotationDict, Et as curveToFinal, F as endMarkedContent, Ft as moveTo, G as saveState, Gt as endText, H as restoreState, Ht as setMiterLimit, I as wrapInMarkedContent, It as rectangle, J as skew, Jt as nextLine, K as scale, Kt as moveText, L as concatMatrix, Lt as setDashPattern, M as beginMarkedContentWithProperties, Mt as fillEvenOdd, N as createMarkedContentScope, Nt as fillEvenOddAndStroke, O as beginArtifact, Ot as ellipsePath, P as endArtifact, Pt as lineTo, Q as cmyk, Qt as setLeading, R as degrees, Rt as setFlatness, S as parseSvgTransform, St as closeFillAndStroke, T as annotationFromDict, Tt as curveTo, U as rotate, Ut as stroke, V as radiansToDegrees, Vt as setLineWidth, W as rotationMatrix, Wt as beginText, X as applyFillColor, Xt as setFont, Y as translate, Yt as setCharacterSpacing, Z as applyStrokeColor, Zt as setFontSize, _ as drawSvgOnPage, _t as drawXObject, a as buildGradientObjects, an as showTextHex, at as setFillColorCmyk, b as parseSvgColor, bt as clipEvenOdd, c as radialGradient, ct as setFillingColor, d as getRedactionMarks, dt as setStrokeColorGray, en as setTextRenderingMode, et as componentsToColor, f as markForRedaction, ft as setStrokeColorRgb, g as endLayerContent, gt as drawImageXObject, h as beginLayerContent, ht as drawImageWithMatrix, i as wrapText, in as showTextArray, it as setFillColor, j as beginMarkedContentSequence, jt as fillAndStroke, k as beginArtifactWithType, kt as endPath, l as tilingPattern, lt as setStrokeColor, m as PdfLayerManager, mt as setStrokingColor, n as PdfPage, nn as setWordSpacing, nt as rgb, o as buildPatternObjects, on as showTextNextLine, ot as setFillColorGray, p as PdfLayer, pt as setStrokeColorSpace, q as setGraphicsState, qt as moveTextSetLeading, rn as showText, rt as setColorSpace, s as linearGradient, sn as showTextWithSpacing, st as setFillColorRgb, t as PageSizes, tn as setTextRise, tt as grayscale, u as applyRedactions, ut as setStrokeColorCmyk, v as svgToPdfOperators, vt as circlePath, w as PdfAnnotation, wt as closePath, x as parseSvgPath, xt as closeAndStroke, y as parseSvg, yt as clip, z as degreesToRadians, zt as setLineCap } from "./pdfPage-N1K2U3jI.mjs";
 import { a as formatPdfDate, c as PdfBool, d as PdfNull, f as PdfNumber, g as PdfString, h as PdfStream, i as buildPageTree, l as PdfDict, m as PdfRef, n as buildDocumentStructure, p as PdfObjectRegistry, r as buildInfoDict, s as PdfArray, t as buildCatalog, u as PdfName } from "./pdfCatalog-BB2Wnmud.mjs";
-import { n as isAvailable, t as deflateSync$1 } from "./libdeflateWasm-DlHgU5oy.mjs";
+import { n as isAvailable, t as deflateSync$1 } from "./libdeflateWasm-82loOtIV.mjs";
 import { i as subsetFont, n as computeSubsetTag, t as buildSubsetCmap } from "./fontSubset-ZpLoOZ2e.mjs";
-import { t as embedPng } from "./pngEmbed-DTOqgEUC.mjs";
+import { t as embedPng } from "./pngEmbed-gaJ9S2Dk.mjs";
 import { t as decompressSync } from "./fflateAdapter-DX0VqT5k.mjs";
+import { a as isJpegWasmReady, i as initJpegWasm, n as decodeJpegWasm, r as encodeJpegWasm } from "./bridge-C7U4E7St.mjs";
 import { deflateSync, inflateSync, unzlibSync } from "fflate";
 
 //#region src/core/pdfWriter.ts
@@ -4826,10 +4827,10 @@ async function tryLoadLibdeflate() {
 	if (libdeflateAttempted) return libdeflateEngine;
 	libdeflateAttempted = true;
 	try {
-		const { LibdeflateWasm: LibdeflateCtor, initDeflateWasm } = await import("./libdeflateWasm-DlHgU5oy.mjs").then((n) => n.r);
+		const { LibdeflateWasm: LibdeflateCtor, initDeflateWasm } = await import("./libdeflateWasm-82loOtIV.mjs").then((n) => n.r);
 		let customBytes;
 		try {
-			const { getWasmLoaderConfig } = await import("./loader-CQfoGFp9.mjs");
+			const { getWasmLoaderConfig } = await import("./loader-1VJXLlMZ.mjs");
 			customBytes = getWasmLoaderConfig().moduleBytes?.["libdeflate"];
 		} catch {}
 		await initDeflateWasm(customBytes);
@@ -6306,15 +6307,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) {
@@ -6593,11 +6655,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).
@@ -6605,23 +6689,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).
@@ -6884,6 +6980,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;
@@ -7036,6 +7141,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);
@@ -7053,7 +7161,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.
@@ -9881,7 +9991,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];
@@ -9973,7 +10083,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);
@@ -10215,23 +10325,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");
@@ -10248,9 +10408,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;
@@ -10263,11 +10435,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`;
@@ -11057,7 +11246,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,
@@ -18869,6 +19083,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
@@ -21769,6 +22007,261 @@ var PdfRedactAnnotation = class PdfRedactAnnotation extends PdfAnnotation {
 	}
 };
 
+//#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 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(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", 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 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(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", 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", PdfArray.of(rd.map(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 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(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", 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 PdfDict();
+		efStreamDict.set("/Type", PdfName.of("EmbeddedFile"));
+		if (this.mimeType) efStreamDict.set("/Subtype", PdfName.of(this.mimeType.replace("/", "#2F")));
+		const params = new PdfDict();
+		params.set("/Size", PdfNumber.of(this.fileData.length));
+		efStreamDict.set("/Params", params);
+		const efStream = new PdfStream(efStreamDict, this.fileData);
+		const efRef = registry.register(efStream);
+		const efDict = new PdfDict();
+		efDict.set("/F", efRef);
+		const fsDict = new PdfDict();
+		fsDict.set("/Type", PdfName.of("Filespec"));
+		fsDict.set("/F", PdfString.literal(this.fileName));
+		fsDict.set("/UF", PdfString.literal(this.fileName));
+		fsDict.set("/EF", efDict);
+		if (this.fileDescription) fsDict.set("/Desc", PdfString.literal(this.fileDescription));
+		const fsRef = registry.register(fsDict);
+		this.dict.set("/FS", fsRef);
+		return this.dict;
+	}
+};
+
 //#endregion
 //#region src/parser/textExtractor.ts
 /**
@@ -23853,66 +24346,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 import("./bridge-C7U4E7St.mjs").then((n) => n.t);
+	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 import("./bridge-C7U4E7St.mjs").then((n) => n.t);
+	const { decodeJpegWasm } = await import("./bridge-C7U4E7St.mjs").then((n) => n.t);
+	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", PdfName.of("/DCTDecode"));
+		if (img.colorSpace === "DeviceCMYK" && channels === 3) dict.set("/ColorSpace", PdfName.of("/DeviceRGB"));
+		if (channels === 1) dict.set("/ColorSpace", 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
@@ -24020,19 +25644,22 @@ 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(import("./libdeflateWasm-DlHgU5oy.mjs").then((n) => n.r).then(async ({ initDeflateWasm }) => {
+	if (options.deflate || options.deflateWasm) inits.push(import("./libdeflateWasm-82loOtIV.mjs").then((n) => n.r).then(async ({ initDeflateWasm }) => {
 		await initDeflateWasm(options.deflateWasm);
 	}));
-	if (options.png || options.pngWasm) inits.push(import("./pngEmbed-DTOqgEUC.mjs").then((n) => n.n).then(async ({ initPngWasm }) => {
+	if (options.png || options.pngWasm) inits.push(import("./pngEmbed-gaJ9S2Dk.mjs").then((n) => n.n).then(async ({ initPngWasm }) => {
 		await initPngWasm(options.pngWasm);
 	}));
 	if (options.fonts || options.fontWasm) inits.push(import("./fontSubset-ZpLoOZ2e.mjs").then((n) => n.r).then(async ({ initSubsetWasm }) => {
 		await initSubsetWasm(options.fontWasm);
 	}));
+	if (options.jpeg || options.jpegWasm) inits.push(import("./bridge-C7U4E7St.mjs").then((n) => n.t).then(async ({ initJpegWasm }) => {
+		await initJpegWasm(options.jpegWasm);
+	}));
 	await Promise.all(inits);
 	wasmInitialized = true;
 }
 
 //#endregion
-export { AnnotationFlags, BlendMode, ChangeTracker, CombedTextLayoutError, EmbeddedFont, EncryptedPdfError, ExceededMaxLengthError, FieldAlreadyExistsError, FieldExistsAsNonTerminalError, FieldFlags, FontNotEmbeddedError, ForeignPageError, ImageAlignment, InvalidFieldNamePartError, LineCapStyle, LineJoinStyle, MissingOnValueCheckError, NoSuchFieldError, PDFOperator, PageSizes, ParseSpeeds, PdfAnnotation, PdfArray, PdfBool, PdfButtonField, PdfCheckboxField, PdfCircleAnnotation, PdfDict, PdfDocument, PdfDropdownField, PdfEncryptionHandler, PdfField, PdfForm, PdfFreeTextAnnotation, PdfHighlightAnnotation, PdfInkAnnotation, PdfLayer, PdfLayerManager, PdfLineAnnotation, PdfLinkAnnotation, PdfListboxField, PdfName, PdfNull, PdfNumber, PdfObjectRegistry, PdfOutlineItem, PdfOutlineTree, PdfPage, PdfParseError, PdfPolyLineAnnotation, PdfPolygonAnnotation, PdfRadioGroup, PdfRedactAnnotation, PdfRef, PdfSignatureField, PdfSquareAnnotation, PdfSquigglyAnnotation, PdfStampAnnotation, PdfStream, PdfStreamWriter, PdfStrikeOutAnnotation, PdfString, PdfStructureElement, PdfStructureTree, PdfTextAnnotation, PdfTextField, PdfUnderlineAnnotation, PdfViewerPreferences, PdfWriter, RemovePageFromEmptyDocumentError, RichTextFieldReadError, StandardFonts, TextAlignment, TextRenderingMode, UnexpectedFieldTypeError, addWatermark, addWatermarkToPage, aesDecryptCBC, aesEncryptCBC, annotationFromDict, applyFillColor, applyRedactions, applyStrokeColor, asNumber, asPDFName, asPDFNumber, attachFile, base64Decode, base64Encode, beginArtifact, beginArtifactWithType, beginLayerContent, beginMarkedContent, beginMarkedContentSequence, beginMarkedContentWithProperties, beginText, buildAnnotationDict, buildCatalog, buildDocumentStructure, buildEmbeddedFilesNameTree, buildGradientObjects, buildInfoDict, buildPageTree, buildPatternObjects, buildPkcs7Signature, buildTimestampRequest, buildViewerPreferencesDict, buildXmpMetadata, checkAccessibility, circlePath, clipEvenOdd, clip as clipOp, closeAndStroke, closeFillAndStroke, closeFillEvenOddAndStroke, closePath as closePathOp, cmyk, colorToComponents, componentsToColor, computeFileEncryptionKey, computeFontSize, computeSignatureHash, concatMatrix, concatMatrix as concatTransformationMatrix, copyPages, createAnnotation, createMarkedContentScope, createPdf, createXmpStream, cropPage, curveToFinal, curveToInitial, curveTo as curveToOp, decodePermissions, decodeStream, degrees, degreesToRadians, drawImageWithMatrix, drawImageXObject, drawXObject as drawObject, drawXObject, drawSvgOnPage, ellipsePath, embedPageAsFormXObject, embedSignature, encodeContextTag, encodeInteger, encodeLength, encodeOID, encodeOctetString, encodePermissions, encodePrintableString, encodeSequence, encodeSet, encodeUTCTime, encodeUtf8String, endArtifact, endLayerContent, endMarkedContent, endPath as endPathOp, endText, enforcePdfA, extractMetrics, extractText, extractTextWithPositions, fillAndStroke as fillAndStrokeOp, fillEvenOdd, fillEvenOddAndStroke, fill as fillOp, findSignatures, formatHexContext, formatPdfDate, generateButtonAppearance, generateCheckboxAppearance, generateCircleAppearance, generateDropdownAppearance, generateFreeTextAppearance, generateHighlightAppearance, generateInkAppearance, generateLineAppearance, generateListboxAppearance, generateRadioAppearance, generateSignatureAppearance, generateSquareAppearance, generateSquigglyAppearance, generateStrikeOutAppearance, generateTextAppearance, generateUnderlineAppearance, getAttachments, getPageSize, getRedactionMarks, getSignatures, grayscale, initWasm, insertPage, isAccessible, isLinearized, isOpenTypeCFF, isTrueType, layoutCombedText, layoutMultilineText, layoutSinglelineText, lineTo as lineToOp, linearGradient, linearizePdf, loadPdf, markForRedaction, md5, mergePdfs, movePage, moveText as moveTextOp, moveTextSetLeading, moveTo as moveToOp, nextLine as nextLineOp, parseContentStream, parseSvg, parseSvgColor, parseSvgPath, parseSvgTransform, parseTimestampResponse, parseViewerPreferences, parseXmpMetadata, restoreState as popGraphicsState, restoreState, prepareForSigning, saveState as pushGraphicsState, saveState, radialGradient, radians, radiansToDegrees, rc4, rectangle as rectangleOp, removePage, removePages, requestTimestamp, resizePage, reversePages, rgb, rotateAllPages, rotate as rotateOp, rotatePage, rotationMatrix, saveDocumentIncremental, saveIncremental, scale as scaleOp, serializePdf, setCharacterSpacing as setCharacterSpacingOp, setCharacterSpacing as setCharacterSqueeze, setColorSpace, setDashPattern as setDashPatternOp, setFillColor, setFillColorCmyk, setFillColorGray, setFillColorRgb, setFillingColor, setFlatness, setFont as setFontAndSize, setFont as setFontOp, setFontSize as setFontSizeOp, setGraphicsState as setGraphicsStateOp, setLeading as setLeadingOp, setLeading as setLineHeight, setLineCap as setLineCapOp, setLineJoin as setLineJoinOp, setLineWidth as setLineWidthOp, setMiterLimit, setStrokeColor, setStrokeColorCmyk, setStrokeColorGray, setStrokeColorRgb, setStrokeColorSpace, setStrokingColor, setTextMatrix as setTextMatrixOp, setTextRenderingMode as setTextRenderingModeOp, setTextRise as setTextRiseOp, setWordSpacing as setWordSpacingOp, sha256, sha384, sha512, showTextArray, showTextHex, showTextNextLine, showText as showTextOp, showTextWithSpacing, signPdf, skew as skewOp, splitPdf, stroke as strokeOp, summarizeIssues, svgToPdfOperators, tilingPattern, translate as translateOp, validatePdfA, verifyOwnerPassword, verifySignature, verifySignatures, verifyUserPassword, wrapInMarkedContent };
+export { AnnotationFlags, BlendMode, ChangeTracker, CombedTextLayoutError, EmbeddedFont, EncryptedPdfError, ExceededMaxLengthError, FieldAlreadyExistsError, FieldExistsAsNonTerminalError, FieldFlags, FontNotEmbeddedError, ForeignPageError, ImageAlignment, InvalidFieldNamePartError, LineCapStyle, LineJoinStyle, MissingOnValueCheckError, NoSuchFieldError, PDFOperator, PageSizes, ParseSpeeds, PdfAnnotation, PdfArray, PdfBool, PdfButtonField, PdfCaretAnnotation, PdfCheckboxField, PdfCircleAnnotation, PdfDict, PdfDocument, PdfDropdownField, PdfEncryptionHandler, PdfField, PdfFileAttachmentAnnotation, PdfForm, PdfFreeTextAnnotation, PdfHighlightAnnotation, PdfInkAnnotation, PdfLayer, PdfLayerManager, PdfLineAnnotation, PdfLinkAnnotation, PdfListboxField, PdfName, PdfNull, PdfNumber, PdfObjectRegistry, PdfOutlineItem, PdfOutlineTree, PdfPage, PdfParseError, PdfPolyLineAnnotation, PdfPolygonAnnotation, PdfPopupAnnotation, PdfRadioGroup, PdfRedactAnnotation, PdfRef, PdfSignatureField, PdfSquareAnnotation, PdfSquigglyAnnotation, PdfStampAnnotation, PdfStream, PdfStreamWriter, PdfStrikeOutAnnotation, PdfString, PdfStructureElement, PdfStructureTree, PdfTextAnnotation, PdfTextField, PdfUnderlineAnnotation, PdfViewerPreferences, PdfWriter, RemovePageFromEmptyDocumentError, RichTextFieldReadError, StandardFonts, TextAlignment, TextRenderingMode, UnexpectedFieldTypeError, addWatermark, addWatermarkToPage, aesDecryptCBC, aesEncryptCBC, annotationFromDict, applyFillColor, applyRedactions, applyStrokeColor, asNumber, asPDFName, asPDFNumber, attachFile, base64Decode, base64Encode, beginArtifact, beginArtifactWithType, beginLayerContent, beginMarkedContent, beginMarkedContentSequence, beginMarkedContentWithProperties, beginText, buildAnnotationDict, buildCatalog, buildDocumentStructure, buildEmbeddedFilesNameTree, buildGradientObjects, buildInfoDict, buildPageTree, buildPatternObjects, buildPkcs7Signature, buildTimestampRequest, buildViewerPreferencesDict, buildXmpMetadata, checkAccessibility, circlePath, clipEvenOdd, clip as clipOp, closeAndStroke, closeFillAndStroke, closeFillEvenOddAndStroke, closePath as closePathOp, cmyk, colorToComponents, componentsToColor, computeFileEncryptionKey, computeFontSize, computeImageDpi, computeSignatureHash, computeTargetDimensions, concatMatrix, concatMatrix as concatTransformationMatrix, convertToGrayscale, copyPages, createAnnotation, createMarkedContentScope, createPdf, createXmpStream, cropPage, curveToFinal, curveToInitial, curveTo as curveToOp, decodeImageStream, decodeJpegWasm, decodePermissions, decodeStream, deduplicateImages, degrees, degreesToRadians, downscaleImage, drawImageWithMatrix, drawImageXObject, drawXObject as drawObject, drawXObject, drawSvgOnPage, ellipsePath, embedPageAsFormXObject, embedSignature, encodeContextTag, encodeInteger, encodeJpegWasm, encodeLength, encodeOID, encodeOctetString, encodePermissions, encodePrintableString, encodeSequence, encodeSet, encodeUTCTime, encodeUtf8String, endArtifact, endLayerContent, endMarkedContent, endPath as endPathOp, endText, enforcePdfA, estimateJpegQuality, extractImages, extractMetrics, extractText, extractTextWithPositions, fillAndStroke as fillAndStrokeOp, fillEvenOdd, fillEvenOddAndStroke, fill as fillOp, findSignatures, formatHexContext, formatPdfDate, generateButtonAppearance, generateCheckboxAppearance, generateCircleAppearance, generateDropdownAppearance, generateFreeTextAppearance, generateHighlightAppearance, generateInkAppearance, generateLineAppearance, generateListboxAppearance, generateRadioAppearance, generateSignatureAppearance, generateSquareAppearance, generateSquigglyAppearance, generateStrikeOutAppearance, generateTextAppearance, generateUnderlineAppearance, getAttachments, getPageSize, getRedactionMarks, getSignatures, grayscale, initJpegWasm, initWasm, insertPage, isAccessible, isGrayscaleImage, isJpegWasmReady, isLinearized, isOpenTypeCFF, isTrueType, layoutCombedText, layoutMultilineText, layoutSinglelineText, lineTo as lineToOp, linearGradient, linearizePdf, loadPdf, markForRedaction, md5, mergePdfs, movePage, moveText as moveTextOp, moveTextSetLeading, moveTo as moveToOp, nextLine as nextLineOp, optimizeAllImages, optimizeImage, parseContentStream, parseSvg, parseSvgColor, parseSvgPath, parseSvgTransform, parseTimestampResponse, parseViewerPreferences, parseXmpMetadata, restoreState as popGraphicsState, restoreState, prepareForSigning, saveState as pushGraphicsState, saveState, radialGradient, radians, radiansToDegrees, rc4, recompressImage, rectangle as rectangleOp, removePage, removePages, requestTimestamp, resizePage, reversePages, rgb, rotateAllPages, rotate as rotateOp, rotatePage, rotationMatrix, saveDocumentIncremental, saveIncremental, scale as scaleOp, serializePdf, setCharacterSpacing as setCharacterSpacingOp, setCharacterSpacing as setCharacterSqueeze, setColorSpace, setDashPattern as setDashPatternOp, setFillColor, setFillColorCmyk, setFillColorGray, setFillColorRgb, setFillingColor, setFlatness, setFont as setFontAndSize, setFont as setFontOp, setFontSize as setFontSizeOp, setGraphicsState as setGraphicsStateOp, setLeading as setLeadingOp, setLeading as setLineHeight, setLineCap as setLineCapOp, setLineJoin as setLineJoinOp, setLineWidth as setLineWidthOp, setMiterLimit, setStrokeColor, setStrokeColorCmyk, setStrokeColorGray, setStrokeColorRgb, setStrokeColorSpace, setStrokingColor, setTextMatrix as setTextMatrixOp, setTextRenderingMode as setTextRenderingModeOp, setTextRise as setTextRiseOp, setWordSpacing as setWordSpacingOp, sha256, sha384, sha512, showTextArray, showTextHex, showTextNextLine, showText as showTextOp, showTextWithSpacing, signPdf, skew as skewOp, splitPdf, stroke as strokeOp, summarizeIssues, svgToPdfOperators, tilingPattern, translate as translateOp, validatePdfA, verifyOwnerPassword, verifySignature, verifySignatures, verifyUserPassword, wrapInMarkedContent };
 //# sourceMappingURL=index.mjs.map