modern-pdf-lib 0.13.0 → 0.14.1

package/dist/index.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
-const require_pdfPage = require('./pdfPage-BebMv6fN.cjs');
-const require_pdfCatalog = require('./pdfCatalog-y_XG8Hq1.cjs');
+const require_pdfPage = require('./pdfPage-DBfdinTR.cjs');
+const require_pdfCatalog = require('./pdfCatalog-COKoYQ8C.cjs');
 const require_libdeflateWasm = require('./libdeflateWasm-OkNoqBnO.cjs');
 const require_fontSubset = require('./fontSubset-pFc8Dueu.cjs');
 const require_pngEmbed = require('./pngEmbed-OYyOe_W0.cjs');
@@ -200,20 +200,19 @@ var PdfWriter = class {
 	*/
 	writeObjectStream(entries, xrefEntries) {
 		const serializedObjects = [];
-		new StringByteWriter();
 		for (const entry of entries) {
 			const objWriter = new StringByteWriter();
 			entry.object.serialize(objWriter);
 			serializedObjects.push(objWriter.toUint8Array());
 		}
-		let headerStr = "";
+		const headerParts = [];
 		let dataOffset = 0;
 		for (let i = 0; i < entries.length; i++) {
-			if (i > 0) headerStr += " ";
-			headerStr += `${entries[i].ref.objectNumber} ${dataOffset}`;
+			headerParts.push(`${entries[i].ref.objectNumber} ${dataOffset}`);
 			dataOffset += serializedObjects[i].length;
 			if (i < entries.length - 1) dataOffset += 1;
 		}
+		const headerStr = headerParts.join(" ");
 		const headerBytes = encoder$5.encode(headerStr + " ");
 		const firstOffset = headerBytes.length;
 		let totalDataLen = firstOffset;
@@ -3755,7 +3754,7 @@ const isDelimiter = /* @__PURE__ */ (() => {
 * `hexVal[b]` is the numeric value (0-15) of a hex character, or -1 if
 * the byte is not a valid hex digit.
 */
-const hexVal = /* @__PURE__ */ (() => {
+const hexVal$1 = /* @__PURE__ */ (() => {
 	const t = new Int8Array(256).fill(-1);
 	for (let i = 0; i <= 9; i++) t[CH_0 + i] = i;
 	for (let i = 0; i < 6; i++) {
@@ -4052,7 +4051,7 @@ var PdfLexer = class {
 		const d = this._data;
 		let pos = startPos + 1;
 		let depth = 1;
-		let result = "";
+		const parts = [];
 		while (pos < this.len && depth > 0) {
 			const c = d[pos];
 			if (c === CH_BACKSLASH) {
@@ -4061,35 +4060,35 @@ var PdfLexer = class {
 				const esc = d[pos];
 				switch (esc) {
 					case 110:
-						result += "\n";
+						parts.push("\n");
 						pos++;
 						break;
 					case 114:
-						result += "\r";
+						parts.push("\r");
 						pos++;
 						break;
 					case 116:
-						result += "	";
+						parts.push("	");
 						pos++;
 						break;
 					case 98:
-						result += "\b";
+						parts.push("\b");
 						pos++;
 						break;
 					case 102:
-						result += "\f";
+						parts.push("\f");
 						pos++;
 						break;
 					case CH_LPAREN:
-						result += "(";
+						parts.push("(");
 						pos++;
 						break;
 					case CH_RPAREN:
-						result += ")";
+						parts.push(")");
 						pos++;
 						break;
 					case CH_BACKSLASH:
-						result += "\\";
+						parts.push("\\");
 						pos++;
 						break;
 					case WS_LF:
@@ -4111,9 +4110,9 @@ var PdfLexer = class {
 									pos++;
 								}
 							}
-							result += String.fromCharCode(octal & 255);
+							parts.push(String.fromCharCode(octal & 255));
 						} else {
-							result += String.fromCharCode(esc);
+							parts.push(String.fromCharCode(esc));
 							pos++;
 						}
 						break;
@@ -4122,23 +4121,23 @@ var PdfLexer = class {
 			}
 			if (c === CH_LPAREN) {
 				depth++;
-				result += "(";
+				parts.push("(");
 				pos++;
 				continue;
 			}
 			if (c === CH_RPAREN) {
 				depth--;
-				if (depth > 0) result += ")";
+				if (depth > 0) parts.push(")");
 				pos++;
 				continue;
 			}
 			if (c === WS_CR) {
-				result += "\n";
+				parts.push("\n");
 				pos++;
 				if (pos < this.len && d[pos] === WS_LF) pos++;
 				continue;
 			}
-			result += String.fromCharCode(c);
+			parts.push(String.fromCharCode(c));
 			pos++;
 		}
 		if (depth !== 0) throw new PdfParseError({
@@ -4151,7 +4150,7 @@ var PdfLexer = class {
 		this.position = pos;
 		return {
 			type: TokenType$1.LiteralString,
-			value: result,
+			value: parts.join(""),
 			offset: startPos
 		};
 	}
@@ -4164,7 +4163,8 @@ var PdfLexer = class {
 	readHexString(startPos) {
 		const d = this._data;
 		let pos = startPos + 1;
-		let hex = "";
+		const bytes = [];
+		let hi = -1;
 		while (pos < this.len) {
 			const c = d[pos];
 			if (c === CH_GT) {
@@ -4175,27 +4175,26 @@ var PdfLexer = class {
 				pos++;
 				continue;
 			}
-			if (hexVal[c] === -1) throw new PdfParseError({
+			const v = hexVal$1[c];
+			if (v === -1) throw new PdfParseError({
 				message: `PdfLexer: invalid hex digit 0x${c.toString(16).padStart(2, "0")} at offset ${pos} in hex string starting at ${startPos}`,
 				offset: pos,
 				expected: "hex digit (0-9, a-f, A-F)",
 				actual: `0x${c.toString(16).padStart(2, "0")}`,
 				data: this._data
 			});
-			hex += String.fromCharCode(c);
+			if (hi === -1) hi = v;
+			else {
+				bytes.push(hi << 4 | v);
+				hi = -1;
+			}
 			pos++;
 		}
-		if (hex.length % 2 !== 0) hex += "0";
-		let result = "";
-		for (let i = 0; i < hex.length; i += 2) {
-			const hi = hexVal[hex.charCodeAt(i)];
-			const lo = hexVal[hex.charCodeAt(i + 1)];
-			result += String.fromCharCode(hi << 4 | lo);
-		}
+		if (hi !== -1) bytes.push(hi << 4);
 		this.position = pos;
 		return {
 			type: TokenType$1.HexString,
-			value: result,
+			value: String.fromCharCode.apply(null, bytes),
 			offset: startPos
 		};
 	}
@@ -4208,7 +4207,7 @@ var PdfLexer = class {
 	readName(startPos) {
 		const d = this._data;
 		let pos = startPos + 1;
-		let name = "/";
+		const parts = ["/"];
 		while (pos < this.len) {
 			const c = d[pos];
 			if (isWhitespace[c] || isDelimiter[c]) break;
@@ -4220,8 +4219,8 @@ var PdfLexer = class {
 					actual: "end of input",
 					data: this._data
 				});
-				const hi = hexVal[d[pos + 1]];
-				const lo = hexVal[d[pos + 2]];
+				const hi = hexVal$1[d[pos + 1]];
+				const lo = hexVal$1[d[pos + 2]];
 				if (hi === -1 || lo === -1) throw new PdfParseError({
 					message: `PdfLexer: invalid #XX escape in name at offset ${pos}`,
 					offset: pos,
@@ -4229,17 +4228,17 @@ var PdfLexer = class {
 					actual: `#${String.fromCharCode(d[pos + 1])}${String.fromCharCode(d[pos + 2])}`,
 					data: this._data
 				});
-				name += String.fromCharCode(hi << 4 | lo);
+				parts.push(String.fromCharCode(hi << 4 | lo));
 				pos += 3;
 				continue;
 			}
-			name += String.fromCharCode(c);
+			parts.push(String.fromCharCode(c));
 			pos++;
 		}
 		this.position = pos;
 		return {
 			type: TokenType$1.Name,
-			value: name,
+			value: parts.join(""),
 			offset: startPos
 		};
 	}
@@ -4354,10 +4353,7 @@ var PdfLexer = class {
 	* because it avoids the per-call overhead of the streaming decoder.
 	*/
 	bytesToAscii(from, to) {
-		const d = this._data;
-		let s = "";
-		for (let i = from; i < to; i++) s += String.fromCharCode(d[i]);
-		return s;
+		return String.fromCharCode.apply(null, this._data.subarray(from, to));
 	}
 };
 
@@ -5251,18 +5247,20 @@ var XrefParser = class {
 	parseTraditionalXref(offset) {
 		const entries = [];
 		let pos = offset;
-		const xrefTag = TEXT_DECODER$1.decode(this.data.subarray(pos, pos + 4));
-		if (xrefTag !== "xref") throw new PdfParseError({
-			message: `Invalid PDF: expected "xref" keyword at offset ${offset}, found "${xrefTag}".`,
-			offset,
-			expected: "\"xref\" keyword",
-			actual: `"${xrefTag}"`,
-			data: this.data
-		});
+		if (!this.isTraditionalXref(pos)) {
+			const xrefTag = TEXT_DECODER$1.decode(this.data.subarray(pos, pos + 4));
+			throw new PdfParseError({
+				message: `Invalid PDF: expected "xref" keyword at offset ${offset}, found "${xrefTag}".`,
+				offset,
+				expected: "\"xref\" keyword",
+				actual: `"${xrefTag}"`,
+				data: this.data
+			});
+		}
 		pos += 4;
 		pos = this.skipWhitespaceAt(pos);
 		while (pos < this.data.length) {
-			if (TEXT_DECODER$1.decode(this.data.subarray(pos, Math.min(pos + 7, this.data.length))).startsWith("trailer")) break;
+			if (this.matchesBytes(pos, 116, 114, 97, 105, 108, 101, 114)) break;
 			const headerLine = this.readLineAt(pos);
 			const headerMatch = headerLine.text.trim().match(/^(\d+)\s+(\d+)/);
 			if (!headerMatch) throw new PdfParseError({
@@ -5277,35 +5275,45 @@ var XrefParser = class {
 			pos = headerLine.nextPos;
 			for (let i = 0; i < count; i++) {
 				const objectNumber = firstObjNum + i;
-				const entryText = this.readXrefEntryAt(pos);
-				const entryMatch = entryText.text.trim().match(/^(\d{10})\s+(\d{5})\s+([fn])/);
-				if (!entryMatch) throw new PdfParseError({
-					message: `Invalid PDF: malformed xref entry at offset ${pos} for object ${objectNumber}: "${entryText.text.trim()}"`,
-					offset: pos,
-					expected: "xref entry \"OOOOOOOOOO GGGGG f/n\"",
-					actual: `"${entryText.text.trim()}"`,
-					data: this.data
-				});
-				const entryOffset = parseInt(entryMatch[1], 10);
-				const gen = parseInt(entryMatch[2], 10);
-				const marker = entryMatch[3];
-				entries.push({
-					objectNumber,
-					generationNumber: gen,
-					offset: entryOffset,
-					type: marker === "n" ? "in-use" : "free"
-				});
-				pos = entryText.nextPos;
+				const parsed = this.parseXrefEntryDirect(pos);
+				if (parsed) {
+					entries.push({
+						objectNumber,
+						generationNumber: parsed.gen,
+						offset: parsed.offset,
+						type: parsed.type
+					});
+					pos = parsed.nextPos;
+				} else {
+					const entryText = this.readXrefEntryAt(pos);
+					const entryMatch = entryText.text.trim().match(/^(\d{10})\s+(\d{5})\s+([fn])/);
+					if (!entryMatch) throw new PdfParseError({
+						message: `Invalid PDF: malformed xref entry at offset ${pos} for object ${objectNumber}: "${entryText.text.trim()}"`,
+						offset: pos,
+						expected: "xref entry \"OOOOOOOOOO GGGGG f/n\"",
+						actual: `"${entryText.text.trim()}"`,
+						data: this.data
+					});
+					entries.push({
+						objectNumber,
+						generationNumber: parseInt(entryMatch[2], 10),
+						offset: parseInt(entryMatch[1], 10),
+						type: entryMatch[3] === "n" ? "in-use" : "free"
+					});
+					pos = entryText.nextPos;
+				}
 			}
 		}
-		const trailerTag = TEXT_DECODER$1.decode(this.data.subarray(pos, pos + 7));
-		if (trailerTag !== "trailer") throw new PdfParseError({
-			message: `Invalid PDF: expected "trailer" keyword at offset ${pos}, found "${trailerTag}".`,
-			offset: pos,
-			expected: "\"trailer\" keyword",
-			actual: `"${trailerTag}"`,
-			data: this.data
-		});
+		if (!this.matchesBytes(pos, 116, 114, 97, 105, 108, 101, 114)) {
+			const trailerTag = TEXT_DECODER$1.decode(this.data.subarray(pos, pos + 7));
+			throw new PdfParseError({
+				message: `Invalid PDF: expected "trailer" keyword at offset ${pos}, found "${trailerTag}".`,
+				offset: pos,
+				expected: "\"trailer\" keyword",
+				actual: `"${trailerTag}"`,
+				data: this.data
+			});
+		}
 		pos += 7;
 		const trailerObj = this.objectParser.parseObjectAt(pos);
 		if (trailerObj.kind !== "dict") throw new PdfParseError({
@@ -5460,17 +5468,33 @@ var XrefParser = class {
 	*/
 	rebuildXrefFromScan() {
 		const entries = /* @__PURE__ */ new Map();
-		const fileText = TEXT_DECODER$1.decode(this.data);
-		const objPattern = /(\d+)\s+(\d+)\s+obj\b/g;
-		let match;
-		while ((match = objPattern.exec(fileText)) !== null) {
-			const objectNumber = parseInt(match[1], 10);
-			const gen = parseInt(match[2], 10);
-			const offset = match.index;
+		const d = this.data;
+		const len = d.length;
+		for (let i = 0; i < len - 2; i++) {
+			if (d[i] !== 111 || d[i + 1] !== 98 || d[i + 2] !== 106) continue;
+			if (i + 3 < len) {
+				const after = d[i + 3];
+				if (after > 32 && after !== 37 && after !== 40 && after !== 41 && after !== 47 && after !== 60 && after !== 62 && after !== 91 && after !== 93 && after !== 123 && after !== 125) continue;
+			}
+			let j = i - 1;
+			while (j >= 0 && (d[j] === 32 || d[j] === 10 || d[j] === 13 || d[j] === 9 || d[j] === 0)) j--;
+			const genEnd = j + 1;
+			while (j >= 0 && d[j] >= 48 && d[j] <= 57) j--;
+			const genStart = j + 1;
+			if (genStart >= genEnd) continue;
+			while (j >= 0 && (d[j] === 32 || d[j] === 10 || d[j] === 13 || d[j] === 9 || d[j] === 0)) j--;
+			const objEnd = j + 1;
+			while (j >= 0 && d[j] >= 48 && d[j] <= 57) j--;
+			const objStart = j + 1;
+			if (objStart >= objEnd) continue;
+			let objectNumber = 0;
+			for (let k = objStart; k < objEnd; k++) objectNumber = objectNumber * 10 + (d[k] - 48);
+			let gen = 0;
+			for (let k = genStart; k < genEnd; k++) gen = gen * 10 + (d[k] - 48);
 			entries.set(objectNumber, {
 				objectNumber,
 				generationNumber: gen,
-				offset,
+				offset: objStart,
 				type: "in-use"
 			});
 		}
@@ -5483,7 +5507,11 @@ var XrefParser = class {
 		});
 		let rootRef;
 		let infoRef;
-		const trailerIdx = fileText.lastIndexOf("trailer");
+		let trailerIdx = -1;
+		for (let i = len - 7; i >= 0; i--) if (d[i] === 116 && d[i + 1] === 114 && d[i + 2] === 97 && d[i + 3] === 105 && d[i + 4] === 108 && d[i + 5] === 101 && d[i + 6] === 114) {
+			trailerIdx = i;
+			break;
+		}
 		if (trailerIdx !== -1) try {
 			const trailerObj = this.objectParser.parseObjectAt(trailerIdx + 7);
 			if (trailerObj.kind === "dict") {
@@ -5524,6 +5552,48 @@ var XrefParser = class {
 	* Determine whether the data at the given offset starts with the
 	* "xref" keyword (indicating a traditional xref table).
 	*/
+	/**
+	* Check if the bytes at `pos` match the given byte values.
+	*/
+	matchesBytes(pos, ...bytes) {
+		if (pos + bytes.length > this.data.length) return false;
+		for (let i = 0; i < bytes.length; i++) if (this.data[pos + i] !== bytes[i]) return false;
+		return true;
+	}
+	/**
+	* Parse a standard xref entry directly from bytes, avoiding TextDecoder
+	* and regex. Returns null if the bytes don't form a valid entry.
+	*
+	* Standard format: `OOOOOOOOOO GGGGG f/n` (18 significant bytes)
+	*/
+	parseXrefEntryDirect(pos) {
+		const d = this.data;
+		if (pos + 18 > d.length) return null;
+		let offset = 0;
+		for (let k = 0; k < 10; k++) {
+			const b = d[pos + k];
+			if (b < 48 || b > 57) return null;
+			offset = offset * 10 + (b - 48);
+		}
+		if (d[pos + 10] !== 32) return null;
+		let gen = 0;
+		for (let k = 0; k < 5; k++) {
+			const b = d[pos + 11 + k];
+			if (b < 48 || b > 57) return null;
+			gen = gen * 10 + (b - 48);
+		}
+		if (d[pos + 16] !== 32) return null;
+		const marker = d[pos + 17];
+		if (marker !== 110 && marker !== 102) return null;
+		let nextPos = pos + 18;
+		while (nextPos < d.length && (d[nextPos] === 32 || d[nextPos] === 13 || d[nextPos] === 10)) nextPos++;
+		return {
+			offset,
+			gen,
+			type: marker === 110 ? "in-use" : "free",
+			nextPos
+		};
+	}
 	isTraditionalXref(offset) {
 		if (offset + 4 > this.data.length) return false;
 		return this.data[offset] === 120 && this.data[offset + 1] === 114 && this.data[offset + 2] === 101 && this.data[offset + 3] === 102;
@@ -6237,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) {
@@ -6321,10 +6452,12 @@ function computeOwnerPasswordValue(ownerPassword, userPassword, revision, keyLen
 	if (revision >= 3) for (let i = 0; i < 50; i++) hash = md5(hash.subarray(0, keyByteLength));
 	const rc4Key = hash.subarray(0, keyByteLength);
 	let encrypted = rc4(rc4Key, padPassword(userPassword));
-	if (revision >= 3) for (let i = 1; i <= 19; i++) {
+	if (revision >= 3) {
 		const modKey = new Uint8Array(rc4Key.length);
-		for (let j = 0; j < rc4Key.length; j++) modKey[j] = (rc4Key[j] ^ i) & 255;
-		encrypted = rc4(modKey, encrypted);
+		for (let i = 1; i <= 19; i++) {
+			for (let j = 0; j < rc4Key.length; j++) modKey[j] = (rc4Key[j] ^ i) & 255;
+			encrypted = rc4(modKey, encrypted);
+		}
 	}
 	return encrypted;
 }
@@ -6354,10 +6487,12 @@ function computeUserPasswordR2(fileKey) {
 */
 function computeUserPasswordR3R4(fileKey, fileId) {
 	let encrypted = rc4(fileKey, md5(concat$1(PASSWORD_PADDING, fileId)));
-	for (let i = 1; i <= 19; i++) {
+	{
 		const modKey = new Uint8Array(fileKey.length);
-		for (let j = 0; j < fileKey.length; j++) modKey[j] = (fileKey[j] ^ i) & 255;
-		encrypted = rc4(modKey, encrypted);
+		for (let i = 1; i <= 19; i++) {
+			for (let j = 0; j < fileKey.length; j++) modKey[j] = (fileKey[j] ^ i) & 255;
+			encrypted = rc4(modKey, encrypted);
+		}
 	}
 	const result = new Uint8Array(32);
 	result.set(encrypted.subarray(0, 16));
@@ -6423,9 +6558,17 @@ async function algorithm2B(password, salt, uKey) {
 	let K = await sha256(uKey ? concat$1(password, salt, uKey) : concat$1(password, salt));
 	let round = 0;
 	while (true) {
-		const K1block = uKey ? concat$1(password, K, uKey) : concat$1(password, K);
-		const K1 = new Uint8Array(K1block.length * 64);
-		for (let i = 0; i < 64; i++) K1.set(K1block, i * K1block.length);
+		const pLen = password.length;
+		const kLen = K.length;
+		const uLen = uKey ? uKey.length : 0;
+		const blockLen = pLen + kLen + uLen;
+		const K1 = new Uint8Array(blockLen * 64);
+		for (let i = 0; i < 64; i++) {
+			const base = i * blockLen;
+			K1.set(password, base);
+			K1.set(K, base + pLen);
+			if (uKey) K1.set(uKey, base + pLen + kLen);
+		}
 		const E = await aesEncryptCBCNoPad(K.subarray(0, 16), K.subarray(16, 32), K1);
 		let bigModVal = 0;
 		for (let i = 0; i < 16; i++) bigModVal = (bigModVal * 256 + E[i]) % 3;
@@ -6512,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).
@@ -6524,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).
@@ -6803,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;
@@ -6955,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);
@@ -6972,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.
@@ -8577,7 +8768,17 @@ const NS_PDFAID = "http://www.aiim.org/pdfa/ns/id/";
 * @internal
 */
 function escapeXml(str) {
-	return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
+	const parts = [];
+	for (let i = 0; i < str.length; i++) {
+		const c = str.charCodeAt(i);
+		if (c === 38) parts.push("&amp;");
+		else if (c === 60) parts.push("&lt;");
+		else if (c === 62) parts.push("&gt;");
+		else if (c === 34) parts.push("&quot;");
+		else if (c === 39) parts.push("&apos;");
+		else parts.push(str[i]);
+	}
+	return parts.join("");
 }
 /**
 * Format a Date as an ISO 8601 string for XMP.
@@ -9880,9 +10081,10 @@ function remapRef$1(sourceRef, context) {
 		context.refMap.set(sourceRef.objectNumber, placeholderRef);
 		return placeholderRef;
 	}
+	let streamHash;
 	if (sourceObj.kind === "stream") {
-		const hash = hashBytes(sourceObj.data);
-		const dedup = context.hashMap.get(hash);
+		streamHash = hashBytes(sourceObj.data);
+		const dedup = context.hashMap.get(streamHash);
 		if (dedup) {
 			context.refMap.set(sourceRef.objectNumber, dedup);
 			return dedup;
@@ -9892,10 +10094,7 @@ function remapRef$1(sourceRef, context) {
 	context.refMap.set(sourceRef.objectNumber, targetRef);
 	const clonedObj = deepClone$1(sourceObj, context);
 	context.targetRegistry.assign(targetRef, clonedObj);
-	if (sourceObj.kind === "stream") {
-		const hash = hashBytes(sourceObj.data);
-		context.hashMap.set(hash, targetRef);
-	}
+	if (streamHash !== void 0) context.hashMap.set(streamHash, targetRef);
 	return targetRef;
 }
 /**
@@ -10126,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 prepareForSigning(pdfBytes, signatureFieldName, placeholderSize = 8192) {
+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 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");
@@ -10159,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;
@@ -10174,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`;
@@ -10968,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,
@@ -14474,7 +14777,6 @@ function read2DMode(reader) {
 	if (bit === 1) {
 		bit = reader.readBit();
 		if (bit < 0) return Mode2D.EOL;
-		if (bit === 1) return Mode2D.HORIZONTAL;
 		if (bit === 0) return Mode2D.VERTICAL_MINUS_1;
 		return Mode2D.VERTICAL_PLUS_1;
 	}
@@ -17605,9 +17907,28 @@ function hexValue(ch) {
 * `~>` marks end-of-data.
 */
 function decodeASCII85(data) {
-	const result = [];
-	const group = [];
+	let out = new Uint8Array(Math.max(data.length * 4 / 5 | 0, 256));
+	let outPos = 0;
+	const group = new Uint8Array(5);
+	let groupLen = 0;
 	let i = 0;
+	function ensureOut(needed) {
+		if (outPos + needed > out.length) {
+			const newBuf = new Uint8Array(Math.max(out.length * 2, outPos + needed));
+			newBuf.set(out.subarray(0, outPos));
+			out = newBuf;
+		}
+	}
+	function decodeGroup(count) {
+		for (let k = count; k < 5; k++) group[k] = 84;
+		const val = group[0] * 85 * 85 * 85 * 85 + group[1] * 85 * 85 * 85 + group[2] * 85 * 85 + group[3] * 85 + group[4];
+		const numBytes = count === 5 ? 4 : count - 1;
+		ensureOut(numBytes);
+		if (numBytes >= 1) out[outPos++] = val >>> 24 & 255;
+		if (numBytes >= 2) out[outPos++] = val >>> 16 & 255;
+		if (numBytes >= 3) out[outPos++] = val >>> 8 & 255;
+		if (numBytes >= 4) out[outPos++] = val & 255;
+	}
 	while (i < data.length) {
 		const ch = data[i];
 		if (ch === 126) break;
@@ -17616,8 +17937,12 @@ function decodeASCII85(data) {
 			continue;
 		}
 		if (ch === 122) {
-			if (group.length > 0) throw new Error("ASCII85Decode: \"z\" inside a group");
-			result.push(0, 0, 0, 0);
+			if (groupLen > 0) throw new Error("ASCII85Decode: \"z\" inside a group");
+			ensureOut(4);
+			out[outPos++] = 0;
+			out[outPos++] = 0;
+			out[outPos++] = 0;
+			out[outPos++] = 0;
 			i++;
 			continue;
 		}
@@ -17625,24 +17950,15 @@ function decodeASCII85(data) {
 			i++;
 			continue;
 		}
-		group.push(ch - 33);
-		if (group.length === 5) {
-			const val = group[0] * 85 * 85 * 85 * 85 + group[1] * 85 * 85 * 85 + group[2] * 85 * 85 + group[3] * 85 + group[4];
-			result.push(val >>> 24 & 255, val >>> 16 & 255, val >>> 8 & 255, val & 255);
-			group.length = 0;
+		group[groupLen++] = ch - 33;
+		if (groupLen === 5) {
+			decodeGroup(5);
+			groupLen = 0;
 		}
 		i++;
 	}
-	if (group.length >= 2) {
-		const origLen = group.length;
-		while (group.length < 5) group.push(84);
-		const val = group[0] * 85 * 85 * 85 * 85 + group[1] * 85 * 85 * 85 + group[2] * 85 * 85 + group[3] * 85 + group[4];
-		const numBytes = origLen - 1;
-		if (numBytes >= 1) result.push(val >>> 24 & 255);
-		if (numBytes >= 2) result.push(val >>> 16 & 255);
-		if (numBytes >= 3) result.push(val >>> 8 & 255);
-	}
-	return new Uint8Array(result);
+	if (groupLen >= 2) decodeGroup(groupLen);
+	return out.subarray(0, outPos);
 }
 /**
 * Decode an LZWDecode stream.
@@ -17662,6 +17978,10 @@ function decodeLZW(data, parms) {
 }
 /**
 * Core LZW decompression.
+*
+* Uses a flat pooled buffer for the code table instead of per-entry
+* Uint8Array allocations, and a pre-allocated output buffer with
+* manual growth instead of `number[]` + push.
 */
 function lzwDecompress(data, earlyChange) {
 	const CLEAR_TABLE = 256;
@@ -17686,71 +18006,88 @@ function lzwDecompress(data, earlyChange) {
 		}
 		return result;
 	}
-	let table = [];
+	let tableBuf = new Uint8Array(65536);
+	const tableOff = new Int32Array(4096);
+	const tableLen = new Int32Array(4096);
+	let tableBufUsed = 256;
 	let codeSize = 9;
 	let nextCode = 258;
+	for (let i = 0; i < 256; i++) {
+		tableBuf[i] = i;
+		tableOff[i] = i;
+		tableLen[i] = 1;
+	}
 	function resetTable() {
-		table = [];
-		for (let i = 0; i < 256; i++) table[i] = new Uint8Array([i]);
-		table[256] = new Uint8Array(0);
-		table[257] = new Uint8Array(0);
+		tableBufUsed = 256;
 		nextCode = 258;
 		codeSize = 9;
 	}
-	resetTable();
-	const output = [];
-	let prevEntry = null;
+	let out = new Uint8Array(Math.max(data.length * 3, 4096));
+	let outPos = 0;
+	function ensureOut(needed) {
+		if (outPos + needed > out.length) {
+			const newBuf = new Uint8Array(Math.max(out.length * 2, outPos + needed));
+			newBuf.set(out.subarray(0, outPos));
+			out = newBuf;
+		}
+	}
+	function ensureTable(needed) {
+		if (tableBufUsed + needed > tableBuf.length) {
+			const newBuf = new Uint8Array(Math.max(tableBuf.length * 2, tableBufUsed + needed));
+			newBuf.set(tableBuf.subarray(0, tableBufUsed));
+			tableBuf = newBuf;
+		}
+	}
+	function writeEntry(code) {
+		const off = tableOff[code];
+		const len = tableLen[code];
+		ensureOut(len);
+		out.set(tableBuf.subarray(off, off + len), outPos);
+		outPos += len;
+	}
+	function addEntry(prevCode, firstByte) {
+		const prevOff = tableOff[prevCode];
+		const prevLen = tableLen[prevCode];
+		const newLen = prevLen + 1;
+		ensureTable(newLen);
+		tableBuf.set(tableBuf.subarray(prevOff, prevOff + prevLen), tableBufUsed);
+		tableBuf[tableBufUsed + prevLen] = firstByte;
+		tableOff[nextCode] = tableBufUsed;
+		tableLen[nextCode] = newLen;
+		tableBufUsed += newLen;
+		nextCode++;
+	}
 	let code = readBits(codeSize);
 	if (code === CLEAR_TABLE) {
 		resetTable();
 		code = readBits(codeSize);
 	}
-	if (code === EOD) return new Uint8Array(output);
-	let entry = table[code];
-	if (entry) {
-		for (const b of entry) output.push(b);
-		prevEntry = entry;
-	}
+	if (code === EOD) return new Uint8Array(0);
+	writeEntry(code);
+	let prevCode = code;
 	while (true) {
 		code = readBits(codeSize);
 		if (code === EOD) break;
 		if (code === CLEAR_TABLE) {
 			resetTable();
-			prevEntry = null;
 			code = readBits(codeSize);
 			if (code === EOD) break;
-			entry = table[code];
-			if (entry) {
-				for (const b of entry) output.push(b);
-				prevEntry = entry;
-			}
+			writeEntry(code);
+			prevCode = code;
 			continue;
 		}
-		if (code < nextCode && table[code]) {
-			entry = table[code];
-			for (const b of entry) output.push(b);
-			if (prevEntry) {
-				const newEntry = new Uint8Array(prevEntry.length + 1);
-				newEntry.set(prevEntry);
-				newEntry[prevEntry.length] = entry[0];
-				table[nextCode] = newEntry;
-				nextCode++;
-			}
+		if (code < nextCode) {
+			writeEntry(code);
+			addEntry(prevCode, tableBuf[tableOff[code]]);
 		} else {
-			if (!prevEntry) throw new Error("LZWDecode: invalid code sequence");
-			const newEntry = new Uint8Array(prevEntry.length + 1);
-			newEntry.set(prevEntry);
-			newEntry[prevEntry.length] = prevEntry[0];
-			for (const b of newEntry) output.push(b);
-			table[nextCode] = newEntry;
-			nextCode++;
-			entry = newEntry;
-		}
-		prevEntry = entry;
+			addEntry(prevCode, tableBuf[tableOff[prevCode]]);
+			writeEntry(nextCode - 1);
+		}
+		prevCode = code;
 		const threshold = (1 << codeSize) - earlyChange;
 		if (nextCode >= threshold && codeSize < 12) codeSize++;
 	}
-	return new Uint8Array(output);
+	return out.subarray(0, outPos);
 }
 /**
 * Decode a RunLengthDecode stream.
@@ -17882,7 +18219,6 @@ function embedPageAsFormXObject(page, sourceRegistry, targetRegistry, xObjectNam
 	const pageWidth = page.width;
 	const pageHeight = page.height;
 	const contentChunks = [];
-	new TextDecoder();
 	const originalRefs = page.getOriginalContentRefs();
 	for (const ref of originalRefs) {
 		const obj = sourceRegistry.resolve(ref);
@@ -18400,7 +18736,7 @@ var PdfDocument = class PdfDocument {
 	async embedTrueTypeFont(fontData, options) {
 		const embeddedFont = await embedFont(fontData);
 		const metrics = embeddedFont.metrics;
-		const psName = options?.customName || metrics.postScriptName || metrics.familyName || "CustomFont";
+		const psName = options?.customName ?? metrics.postScriptName ?? metrics.familyName ?? "CustomFont";
 		const existing = this.embeddedFonts.get(`__ttf__${psName}`);
 		if (existing) return existing;
 		this.fontCounter++;
@@ -18515,7 +18851,7 @@ var PdfDocument = class PdfDocument {
 	async embedCffFont(fontData, options) {
 		const embeddedFont = await embedFont(fontData);
 		const metrics = embeddedFont.metrics;
-		const psName = options?.customName || metrics.postScriptName || metrics.familyName || "CFFFont";
+		const psName = options?.customName ?? metrics.postScriptName ?? metrics.familyName ?? "CFFFont";
 		const existing = this.embeddedFonts.get(`__cff__${psName}`);
 		if (existing) return existing;
 		this.fontCounter++;
@@ -18747,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
@@ -18805,7 +19165,7 @@ var PdfDocument = class PdfDocument {
 	* @param pages  Array of PdfPage instances to embed.
 	* @returns      Array of {@link EmbeddedPdfPage} handles, one per input page.
 	*/
-	async embedPages(pages) {
+	embedPages(pages) {
 		return pages.map((page) => this.embedPage(page));
 	}
 	/** Set the document title. */
@@ -20337,8 +20697,8 @@ function compressStream(stream, level) {
 * @returns              The incremental save result.
 */
 async function saveDocumentIncremental(originalBytes, doc, options) {
-	const { buildDocumentStructure } = await Promise.resolve().then(() => require("./pdfCatalog-y_XG8Hq1.cjs")).then((n) => n.pdfCatalog_exports);
-	const { PdfPage: _PdfPage } = await Promise.resolve().then(() => require("./pdfPage-BebMv6fN.cjs")).then((n) => n.pdfPage_exports);
+	const { buildDocumentStructure } = await Promise.resolve().then(() => require("./pdfCatalog-COKoYQ8C.cjs")).then((n) => n.pdfCatalog_exports);
+	const { PdfPage: _PdfPage } = await Promise.resolve().then(() => require("./pdfPage-DBfdinTR.cjs")).then((n) => n.pdfPage_exports);
 	const registry = doc.getRegistry();
 	const structure = buildDocumentStructure(doc.getInternalPages().map((p) => p.finalize()), {
 		producer: doc.getProducer(),
@@ -21647,6 +22007,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
 /**
@@ -22445,6 +23060,19 @@ var TokenType = /* @__PURE__ */ function(TokenType) {
 	return TokenType;
 }(TokenType || {});
 /**
+* `hexVal[b]` is the numeric value (0-15) of a hex character, or -1 if
+* the byte is not a valid hex digit.
+*/
+const hexVal = /* @__PURE__ */ (() => {
+	const t = new Int8Array(256).fill(-1);
+	for (let i = 0; i <= 9; i++) t[48 + i] = i;
+	for (let i = 0; i < 6; i++) {
+		t[65 + i] = 10 + i;
+		t[97 + i] = 10 + i;
+	}
+	return t;
+})();
+/**
 * Combined lexer + parser for PDF content streams.
 *
 * Content streams are simpler than full PDF object syntax — there are no
@@ -22563,20 +23191,22 @@ var ContentStreamLexer = class {
 		}
 		const dataStart = this.pos;
 		let dataEnd = this.pos;
-		while (this.pos < this.data.length) {
-			if (this.isWhitespace(this.data[this.pos])) {
-				const wsPos = this.pos;
-				let probe = wsPos + 1;
-				if (probe + 1 < this.data.length && this.data[probe] === 69 && this.data[probe + 1] === 73) {
-					const afterEI = probe + 2;
-					if (afterEI >= this.data.length || this.isWhitespace(this.data[afterEI])) {
-						dataEnd = wsPos;
-						this.pos = afterEI;
-						break;
-					}
+		let searchFrom = this.pos;
+		while (searchFrom < this.data.length) {
+			const eIdx = this.data.indexOf(69, searchFrom);
+			if (eIdx === -1 || eIdx + 1 >= this.data.length) {
+				this.pos = this.data.length;
+				break;
+			}
+			if (eIdx > dataStart && this.isWhitespace(this.data[eIdx - 1]) && this.data[eIdx + 1] === 73) {
+				const afterEI = eIdx + 2;
+				if (afterEI >= this.data.length || this.isWhitespace(this.data[afterEI])) {
+					dataEnd = eIdx - 1;
+					this.pos = afterEI;
+					break;
 				}
 			}
-			this.pos++;
+			searchFrom = eIdx + 1;
 		}
 		return {
 			dict,
@@ -22644,7 +23274,7 @@ var ContentStreamLexer = class {
 	*/
 	readLiteralString() {
 		this.pos++;
-		let result = "";
+		const parts = [];
 		let depth = 1;
 		while (this.pos < this.data.length && depth > 0) {
 			const ch = this.data[this.pos];
@@ -22654,35 +23284,35 @@ var ContentStreamLexer = class {
 				const esc = this.data[this.pos];
 				switch (esc) {
 					case 110:
-						result += "\n";
+						parts.push("\n");
 						this.pos++;
 						break;
 					case 114:
-						result += "\r";
+						parts.push("\r");
 						this.pos++;
 						break;
 					case 116:
-						result += "	";
+						parts.push("	");
 						this.pos++;
 						break;
 					case 98:
-						result += "\b";
+						parts.push("\b");
 						this.pos++;
 						break;
 					case 102:
-						result += "\f";
+						parts.push("\f");
 						this.pos++;
 						break;
 					case 40:
-						result += "(";
+						parts.push("(");
 						this.pos++;
 						break;
 					case 41:
-						result += ")";
+						parts.push(")");
 						this.pos++;
 						break;
 					case 92:
-						result += "\\";
+						parts.push("\\");
 						this.pos++;
 						break;
 					case 10:
@@ -22710,29 +23340,29 @@ var ContentStreamLexer = class {
 									}
 								}
 							}
-							result += String.fromCharCode(octal & 255);
+							parts.push(String.fromCharCode(octal & 255));
 						} else {
-							result += String.fromCharCode(esc);
+							parts.push(String.fromCharCode(esc));
 							this.pos++;
 						}
 						break;
 				}
 			} else if (ch === 40) {
 				depth++;
-				result += "(";
+				parts.push("(");
 				this.pos++;
 			} else if (ch === 41) {
 				depth--;
-				if (depth > 0) result += ")";
+				if (depth > 0) parts.push(")");
 				this.pos++;
 			} else {
-				result += String.fromCharCode(ch);
+				parts.push(String.fromCharCode(ch));
 				this.pos++;
 			}
 		}
 		return {
 			type: TokenType.String,
-			value: result
+			value: parts.join("")
 		};
 	}
 	/**
@@ -22740,7 +23370,8 @@ var ContentStreamLexer = class {
 	*/
 	readHexString() {
 		this.pos++;
-		let hex = "";
+		const bytes = [];
+		let hi = -1;
 		while (this.pos < this.data.length) {
 			const ch = this.data[this.pos];
 			if (ch === 62) {
@@ -22751,18 +23382,22 @@ var ContentStreamLexer = class {
 				this.pos++;
 				continue;
 			}
-			hex += String.fromCharCode(ch);
+			const v = hexVal[ch];
+			if (v === -1) {
+				this.pos++;
+				continue;
+			}
+			if (hi === -1) hi = v;
+			else {
+				bytes.push(hi << 4 | v);
+				hi = -1;
+			}
 			this.pos++;
 		}
-		if (hex.length % 2 !== 0) hex += "0";
-		let result = "";
-		for (let i = 0; i < hex.length; i += 2) {
-			const byte = parseInt(hex.substring(i, i + 2), 16);
-			if (!isNaN(byte)) result += String.fromCharCode(byte);
-		}
+		if (hi !== -1) bytes.push(hi << 4);
 		return {
 			type: TokenType.HexString,
-			value: result
+			value: String.fromCharCode.apply(null, bytes)
 		};
 	}
 	/**
@@ -22770,27 +23405,25 @@ var ContentStreamLexer = class {
 	*/
 	readName() {
 		this.pos++;
-		let name = "/";
+		const parts = ["/"];
 		while (this.pos < this.data.length) {
 			const ch = this.data[this.pos];
 			if (this.isWhitespace(ch) || this.isDelimiter(ch)) break;
 			if (ch === 35 && this.pos + 2 < this.data.length) {
-				const hi = this.data[this.pos + 1];
-				const lo = this.data[this.pos + 2];
-				const hex = String.fromCharCode(hi) + String.fromCharCode(lo);
-				const code = parseInt(hex, 16);
-				if (!isNaN(code)) {
-					name += String.fromCharCode(code);
+				const hi = hexVal[this.data[this.pos + 1]];
+				const lo = hexVal[this.data[this.pos + 2]];
+				if (hi !== -1 && lo !== -1) {
+					parts.push(String.fromCharCode(hi << 4 | lo));
 					this.pos += 3;
 					continue;
 				}
 			}
-			name += String.fromCharCode(ch);
+			parts.push(String.fromCharCode(ch));
 			this.pos++;
 		}
 		return {
 			type: TokenType.Name,
-			value: require_pdfCatalog.PdfName.of(name)
+			value: require_pdfCatalog.PdfName.of(parts.join(""))
 		};
 	}
 	/**
@@ -22884,9 +23517,7 @@ var ContentStreamLexer = class {
 	* Decode a slice of the data as ASCII text.
 	*/
 	decodeAscii(start, end) {
-		let s = "";
-		for (let i = start; i < end; i++) s += String.fromCharCode(this.data[i]);
-		return s;
+		return String.fromCharCode.apply(null, this.data.subarray(start, end));
 	}
 };
 
@@ -23714,6 +24345,339 @@ function addTrailerId(data) {
 	return concatBytes(...parts);
 }
 
+//#endregion
+//#region src/assets/image/imageOptimize.ts
+/**
+* Downscale an image to fit within the specified dimensions.
+*
+* If the image is already smaller than the target dimensions, it is
+* returned unchanged.
+*
+* @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.
+*
+* @example
+* ```ts
+* const result = downscaleImage(rawImage, {
+*   maxWidth: 1024,
+*   maxHeight: 768,
+*   algorithm: 'bilinear',
+* });
+* ```
+*/
+function downscaleImage(image, options = {}) {
+	const target = computeTargetDimensions(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);
+	}
+}
+/**
+* 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,
+* });
+* ```
+*/
+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);
+		default: return {
+			data: image.pixels,
+			width: image.width,
+			height: image.height,
+			channels: image.channels,
+			format: "raw",
+			wasOptimized: false
+		};
+	}
+}
+/**
+* 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.
+*/
+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);
+}
+/**
+* Compute target dimensions from options, preserving aspect ratio.
+* @internal
+*/
+function computeTargetDimensions(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.
+* @internal
+*/
+/**
+* Recompress image data as JPEG.
+*
+* JPEG encoding in pure JS is complex (DCT, Huffman coding, quantization).
+* A full implementation requires either:
+*
+* 1. **WASM-based encoder** (preferred) -- compile libjpeg-turbo or mozjpeg
+*    to WASM, feed raw pixels, get JPEG bytes back.
+* 2. **Canvas API** (browser-only fallback) -- use `OffscreenCanvas` with
+*    `convertToBlob({ type: 'image/jpeg', quality })`.
+* 3. **Pure JS encoder** (last resort) -- very slow but works everywhere.
+*
+* Until a WASM encoder module is bundled, this function returns the input
+* data unchanged. The caller receives `format: 'raw'` and
+* `wasOptimized: false` to indicate that JPEG encoding was not applied.
+*
+* @param image   - The raw image pixel data.
+* @param quality - JPEG quality 1-100 (reserved for future use).
+* @returns         The input data as-is, marked as un-optimized.
+* @internal
+*/
+async function recompressJpeg(image, quality) {
+	return {
+		data: image.pixels,
+		width: image.width,
+		height: image.height,
+		channels: image.channels,
+		format: "raw",
+		wasOptimized: false
+	};
+}
+
 //#endregion
 //#region src/errors.ts
 /**
@@ -23921,6 +24885,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;
@@ -23928,6 +24893,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;
@@ -23947,6 +24913,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;
@@ -24033,6 +25000,7 @@ exports.decodePermissions = decodePermissions;
 exports.decodeStream = decodeStream;
 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;
@@ -24110,6 +25078,7 @@ exports.moveTextOp = require_pdfPage.moveText;
 exports.moveTextSetLeading = require_pdfPage.moveTextSetLeading;
 exports.moveToOp = require_pdfPage.moveTo;
 exports.nextLineOp = require_pdfPage.nextLine;
+exports.optimizeImage = optimizeImage;
 exports.parseContentStream = parseContentStream;
 exports.parseSvg = require_pdfPage.parseSvg;
 exports.parseSvgColor = require_pdfPage.parseSvgColor;
@@ -24125,6 +25094,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;