modern-pdf-lib 0.12.1 → 0.13.0

package/dist/index.cjs

@@ -1,9 +1,9 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
-const require_pdfPage = require('./pdfPage-BMGFx7Xd.cjs');
+const require_pdfPage = require('./pdfPage-BebMv6fN.cjs');
 const require_pdfCatalog = require('./pdfCatalog-y_XG8Hq1.cjs');
-const require_libdeflateWasm = require('./libdeflateWasm-DeU6cupL.cjs');
+const require_libdeflateWasm = require('./libdeflateWasm-OkNoqBnO.cjs');
 const require_fontSubset = require('./fontSubset-pFc8Dueu.cjs');
-const require_pngEmbed = require('./pngEmbed-1RWu6KsO.cjs');
+const require_pngEmbed = require('./pngEmbed-OYyOe_W0.cjs');
 const require_fflateAdapter = require('./fflateAdapter-AHC_S3cb.cjs');
 let fflate = require("fflate");
 
@@ -3236,7 +3236,7 @@ function extractMetricsWasm(fontData) {
 * Tracks which glyphs have been used so that subsetting can be
 * performed at save time, and provides text measurement methods.
 *
-* Create via {@link embedFont}.
+* Create via `PdfDocument.embedFont()`.
 */
 var EmbeddedFont = class {
 	/** The raw font file bytes. */
@@ -3581,6 +3581,53 @@ function findTable(data, tag) {
 	}
 }
 
+//#endregion
+//#region src/parser/parseError.ts
+/**
+* @module parser/parseError
+* Structured error class for PDF parsing failures.
+* @packageDocumentation
+*/
+var PdfParseError = class extends Error {
+	name = "PdfParseError";
+	offset;
+	expected;
+	actual;
+	hexContext;
+	constructor(options) {
+		const hexCtx = options.data ? formatHexContext(options.data, options.offset) : "";
+		const parts = [options.message];
+		if (options.expected) parts.push(`  Expected: ${options.expected}`);
+		if (options.actual) parts.push(`  Got: ${options.actual}`);
+		if (hexCtx) parts.push(`  Context:\n${hexCtx}`);
+		super(parts.join("\n"), options.cause ? { cause: options.cause } : void 0);
+		this.offset = options.offset;
+		this.expected = options.expected ?? "";
+		this.actual = options.actual ?? "";
+		this.hexContext = hexCtx;
+	}
+};
+function formatHexContext(data, offset, windowSize = 16) {
+	const start = Math.max(0, offset - windowSize);
+	const end = Math.min(data.length, offset + windowSize);
+	const slice = data.subarray(start, end);
+	const hexParts = [];
+	const asciiParts = [];
+	for (let i = 0; i < slice.length; i++) {
+		const byte = slice[i];
+		const isErrorByte = start + i === offset;
+		const hex = byte.toString(16).padStart(2, "0");
+		hexParts.push(isErrorByte ? `[${hex}]` : ` ${hex} `);
+		asciiParts.push(byte >= 32 && byte <= 126 ? String.fromCharCode(byte) : ".");
+	}
+	return [
+		`    Offset ${start}:`,
+		`    Hex:   ${hexParts.join("")}`,
+		`    ASCII: ${asciiParts.join(" ")}`,
+		`    Error at offset ${offset} (marked with [])`
+	].join("\n");
+}
+
 //#endregion
 //#region src/parser/lexer.ts
 /**
@@ -3736,7 +3783,7 @@ const hexVal = /* @__PURE__ */ (() => {
 */
 var PdfLexer = class {
 	/** The raw PDF bytes being tokenized. */
-	data;
+	_data;
 	/** Total length of the input (cached for hot loops). */
 	len;
 	/** Current read position (byte offset). */
@@ -3759,11 +3806,20 @@ var PdfLexer = class {
 	*              must not mutate it while the lexer is in use.
 	*/
 	constructor(data) {
-		this.data = data;
+		this._data = data;
 		this.len = data.length;
 		this.position = 0;
 	}
 	/**
+	* Public accessor for the raw PDF byte buffer.
+	*
+	* This allows other parsers (e.g. object parser, xref parser) to
+	* include hex-context dumps in structured error messages.
+	*/
+	get rawData() {
+		return this._data;
+	}
+	/**
 	* Consume and return the next token.
 	*
 	* Returns a token with `type === TokenType.EOF` when the input is
@@ -3799,8 +3855,14 @@ var PdfLexer = class {
 	* @throws        If there are not enough bytes remaining.
 	*/
 	readStreamData(length) {
-		if (this.position + length > this.len) throw new Error(`PdfLexer.readStreamData: requested ${length} bytes at offset ${this.position}, but only ${this.len - this.position} remain`);
-		const slice = this.data.subarray(this.position, this.position + length);
+		if (this.position + length > this.len) throw new PdfParseError({
+			message: `PdfLexer.readStreamData: requested ${length} bytes at offset ${this.position}, but only ${this.len - this.position} remain`,
+			offset: this.position,
+			expected: `${length} bytes available`,
+			actual: `${this.len - this.position} bytes remaining`,
+			data: this._data
+		});
+		const slice = this._data.subarray(this.position, this.position + length);
 		this.position += length;
 		return slice;
 	}
@@ -3813,7 +3875,13 @@ var PdfLexer = class {
 	* @throws        If the offset is out of range.
 	*/
 	seek(offset) {
-		if (offset < 0 || offset > this.len) throw new RangeError(`PdfLexer.seek: offset ${offset} is outside [0, ${this.len}]`);
+		if (offset < 0 || offset > this.len) throw new PdfParseError({
+			message: `PdfLexer.seek: offset ${offset} is outside [0, ${this.len}]`,
+			offset,
+			expected: `offset in range [0, ${this.len}]`,
+			actual: `${offset}`,
+			data: this._data
+		});
 		this.position = offset;
 		this.peeked = null;
 	}
@@ -3826,7 +3894,7 @@ var PdfLexer = class {
 	*/
 	byteAt(offset) {
 		if (offset < 0 || offset >= this.len) return -1;
-		return this.data[offset];
+		return this._data[offset];
 	}
 	/**
 	* Return the total length of the input buffer (in bytes).
@@ -3842,7 +3910,7 @@ var PdfLexer = class {
 	* extracting stream data.
 	*/
 	skipWhitespace() {
-		const d = this.data;
+		const d = this._data;
 		let pos = this.position;
 		while (pos < this.len) {
 			const b = d[pos];
@@ -3876,7 +3944,7 @@ var PdfLexer = class {
 			value: null,
 			offset: this.position
 		};
-		const d = this.data;
+		const d = this._data;
 		const startPos = this.position;
 		const b = d[startPos];
 		if (b === CH_LBRACKET) {
@@ -3916,7 +3984,13 @@ var PdfLexer = class {
 				};
 			}
 			this.position++;
-			throw new Error(`PdfLexer: unexpected '>' at offset ${startPos} (expected '>>' for dict end)`);
+			throw new PdfParseError({
+				message: `PdfLexer: unexpected '>' at offset ${startPos} (expected '>>' for dict end)`,
+				offset: startPos,
+				expected: "'>>' (dict end delimiter)",
+				actual: "'>' (lone angle bracket)",
+				data: this._data
+			});
 		}
 		if (b === CH_LPAREN) return this.readLiteralString(startPos);
 		if (b === CH_SLASH) return this.readName(startPos);
@@ -3931,7 +4005,7 @@ var PdfLexer = class {
 	* `-.002`, `+.5`). Scientific notation is **not** permitted.
 	*/
 	readNumber(startPos) {
-		const d = this.data;
+		const d = this._data;
 		let pos = startPos;
 		let hasSign = false;
 		let hasDot = false;
@@ -3975,7 +4049,7 @@ var PdfLexer = class {
 	* parentheses.
 	*/
 	readLiteralString(startPos) {
-		const d = this.data;
+		const d = this._data;
 		let pos = startPos + 1;
 		let depth = 1;
 		let result = "";
@@ -4067,7 +4141,13 @@ var PdfLexer = class {
 			result += String.fromCharCode(c);
 			pos++;
 		}
-		if (depth !== 0) throw new Error(`PdfLexer: unterminated literal string starting at offset ${startPos}`);
+		if (depth !== 0) throw new PdfParseError({
+			message: `PdfLexer: unterminated literal string starting at offset ${startPos}`,
+			offset: startPos,
+			expected: "closing ')' for literal string",
+			actual: "end of input",
+			data: this._data
+		});
 		this.position = pos;
 		return {
 			type: TokenType$1.LiteralString,
@@ -4082,7 +4162,7 @@ var PdfLexer = class {
 	* odd, a trailing `0` is assumed (per spec SS 7.3.4.3).
 	*/
 	readHexString(startPos) {
-		const d = this.data;
+		const d = this._data;
 		let pos = startPos + 1;
 		let hex = "";
 		while (pos < this.len) {
@@ -4095,7 +4175,13 @@ var PdfLexer = class {
 				pos++;
 				continue;
 			}
-			if (hexVal[c] === -1) throw new Error(`PdfLexer: invalid hex digit 0x${c.toString(16).padStart(2, "0")} at offset ${pos} in hex string starting at ${startPos}`);
+			if (hexVal[c] === -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);
 			pos++;
 		}
@@ -4120,17 +4206,29 @@ var PdfLexer = class {
 	* **includes** the leading `/`.
 	*/
 	readName(startPos) {
-		const d = this.data;
+		const d = this._data;
 		let pos = startPos + 1;
 		let name = "/";
 		while (pos < this.len) {
 			const c = d[pos];
 			if (isWhitespace[c] || isDelimiter[c]) break;
 			if (c === CH_HASH) {
-				if (pos + 2 >= this.len) throw new Error(`PdfLexer: incomplete #XX escape in name at offset ${pos}`);
+				if (pos + 2 >= this.len) throw new PdfParseError({
+					message: `PdfLexer: incomplete #XX escape in name at offset ${pos}`,
+					offset: pos,
+					expected: "two hex digits after # in name",
+					actual: "end of input",
+					data: this._data
+				});
 				const hi = hexVal[d[pos + 1]];
 				const lo = hexVal[d[pos + 2]];
-				if (hi === -1 || lo === -1) throw new Error(`PdfLexer: invalid #XX escape in name at offset ${pos}`);
+				if (hi === -1 || lo === -1) throw new PdfParseError({
+					message: `PdfLexer: invalid #XX escape in name at offset ${pos}`,
+					offset: pos,
+					expected: "valid hex digits after # in name",
+					actual: `#${String.fromCharCode(d[pos + 1])}${String.fromCharCode(d[pos + 2])}`,
+					data: this._data
+				});
 				name += String.fromCharCode(hi << 4 | lo);
 				pos += 3;
 				continue;
@@ -4152,7 +4250,7 @@ var PdfLexer = class {
 	* available for callers that want to preserve them.
 	*/
 	readComment(startPos) {
-		const d = this.data;
+		const d = this._data;
 		let pos = startPos + 1;
 		const begin = pos;
 		while (pos < this.len) {
@@ -4177,7 +4275,7 @@ var PdfLexer = class {
 	* handle them.
 	*/
 	readKeyword(startPos) {
-		const d = this.data;
+		const d = this._data;
 		let pos = startPos;
 		while (pos < this.len) {
 			const c = d[pos];
@@ -4256,7 +4354,7 @@ var PdfLexer = class {
 	* because it avoids the per-call overhead of the streaming decoder.
 	*/
 	bytesToAscii(from, to) {
-		const d = this.data;
+		const d = this._data;
 		let s = "";
 		for (let i = from; i < to; i++) s += String.fromCharCode(d[i]);
 		return s;
@@ -4332,13 +4430,31 @@ var PdfObjectParser = class {
 	*/
 	parseIndirectObject() {
 		const objNumToken = this.lexer.nextToken();
-		if (objNumToken.type !== TokenType$1.Number || !Number.isInteger(objNumToken.value)) throw new Error(`PdfObjectParser.parseIndirectObject: expected integer object number at offset ${objNumToken.offset}, got ${TokenType$1[objNumToken.type]} (${String(objNumToken.value)})`);
+		if (objNumToken.type !== TokenType$1.Number || !Number.isInteger(objNumToken.value)) throw new PdfParseError({
+			message: `PdfObjectParser.parseIndirectObject: expected integer object number at offset ${objNumToken.offset}, got ${TokenType$1[objNumToken.type]} (${String(objNumToken.value)})`,
+			offset: objNumToken.offset,
+			expected: "integer object number",
+			actual: `${TokenType$1[objNumToken.type]} (${String(objNumToken.value)})`,
+			data: this.lexer.rawData
+		});
 		const objNum = objNumToken.value;
 		const genNumToken = this.lexer.nextToken();
-		if (genNumToken.type !== TokenType$1.Number || !Number.isInteger(genNumToken.value)) throw new Error(`PdfObjectParser.parseIndirectObject: expected integer generation number at offset ${genNumToken.offset}, got ${TokenType$1[genNumToken.type]} (${String(genNumToken.value)})`);
+		if (genNumToken.type !== TokenType$1.Number || !Number.isInteger(genNumToken.value)) throw new PdfParseError({
+			message: `PdfObjectParser.parseIndirectObject: expected integer generation number at offset ${genNumToken.offset}, got ${TokenType$1[genNumToken.type]} (${String(genNumToken.value)})`,
+			offset: genNumToken.offset,
+			expected: "integer generation number",
+			actual: `${TokenType$1[genNumToken.type]} (${String(genNumToken.value)})`,
+			data: this.lexer.rawData
+		});
 		const genNum = genNumToken.value;
 		const objKw = this.lexer.nextToken();
-		if (objKw.type !== TokenType$1.ObjKeyword) throw new Error(`PdfObjectParser.parseIndirectObject: expected 'obj' keyword at offset ${objKw.offset}, got ${TokenType$1[objKw.type]} (${String(objKw.value)})`);
+		if (objKw.type !== TokenType$1.ObjKeyword) throw new PdfParseError({
+			message: `PdfObjectParser.parseIndirectObject: expected 'obj' keyword at offset ${objKw.offset}, got ${TokenType$1[objKw.type]} (${String(objKw.value)})`,
+			offset: objKw.offset,
+			expected: "'obj' keyword",
+			actual: `${TokenType$1[objKw.type]} (${String(objKw.value)})`,
+			data: this.lexer.rawData
+		});
 		return this.parseIndirectObjectBody(objNum, genNum);
 	}
 	/**
@@ -4383,8 +4499,20 @@ var PdfObjectParser = class {
 			case TokenType$1.Name: return require_pdfCatalog.PdfName.of(token.value);
 			case TokenType$1.ArrayStart: return this.parseArray();
 			case TokenType$1.DictStart: return this.parseDictOrStream();
-			case TokenType$1.EOF: throw new Error(`PdfObjectParser: unexpected end of input at offset ${token.offset}`);
-			default: throw new Error(`PdfObjectParser: unexpected token ${TokenType$1[token.type]} (${String(token.value)}) at offset ${token.offset}`);
+			case TokenType$1.EOF: throw new PdfParseError({
+				message: `PdfObjectParser: unexpected end of input at offset ${token.offset}`,
+				offset: token.offset,
+				expected: "a PDF object (number, string, name, array, dict, etc.)",
+				actual: "end of input",
+				data: this.lexer.rawData
+			});
+			default: throw new PdfParseError({
+				message: `PdfObjectParser: unexpected token ${TokenType$1[token.type]} (${String(token.value)}) at offset ${token.offset}`,
+				offset: token.offset,
+				expected: "a PDF object (number, string, name, array, dict, etc.)",
+				actual: `${TokenType$1[token.type]} (${String(token.value)})`,
+				data: this.lexer.rawData
+			});
 		}
 	}
 	/**
@@ -4430,7 +4558,13 @@ var PdfObjectParser = class {
 			if (this.lexer.peekToken().type === TokenType$1.StreamKeyword) finalObject = this.readStream(object);
 		}
 		const endToken = this.lexer.nextToken();
-		if (endToken.type !== TokenType$1.EndObjKeyword) throw new Error(`PdfObjectParser: expected 'endobj' for object ${objNum} ${genNum} at offset ${endToken.offset}, got ${TokenType$1[endToken.type]} (${String(endToken.value)})`);
+		if (endToken.type !== TokenType$1.EndObjKeyword) throw new PdfParseError({
+			message: `PdfObjectParser: expected 'endobj' for object ${objNum} ${genNum} at offset ${endToken.offset}, got ${TokenType$1[endToken.type]} (${String(endToken.value)})`,
+			offset: endToken.offset,
+			expected: `'endobj' keyword for object ${objNum} ${genNum}`,
+			actual: `${TokenType$1[endToken.type]} (${String(endToken.value)})`,
+			data: this.lexer.rawData
+		});
 		this.registry.registerWithRef(ref, finalObject);
 		return {
 			ref,
@@ -4450,7 +4584,13 @@ var PdfObjectParser = class {
 				this.lexer.nextToken();
 				break;
 			}
-			if (peek.type === TokenType$1.EOF) throw new Error(`PdfObjectParser: unterminated array at offset ${peek.offset}`);
+			if (peek.type === TokenType$1.EOF) throw new PdfParseError({
+				message: `PdfObjectParser: unterminated array at offset ${peek.offset}`,
+				offset: peek.offset,
+				expected: "']' to close array",
+				actual: "end of input",
+				data: this.lexer.rawData
+			});
 			items.push(this.parseObject());
 		}
 		return new require_pdfCatalog.PdfArray(items);
@@ -4479,9 +4619,21 @@ var PdfObjectParser = class {
 				this.lexer.nextToken();
 				break;
 			}
-			if (peek.type === TokenType$1.EOF) throw new Error(`PdfObjectParser: unterminated dictionary at offset ${peek.offset}`);
+			if (peek.type === TokenType$1.EOF) throw new PdfParseError({
+				message: `PdfObjectParser: unterminated dictionary at offset ${peek.offset}`,
+				offset: peek.offset,
+				expected: "'>>' to close dictionary",
+				actual: "end of input",
+				data: this.lexer.rawData
+			});
 			const keyToken = this.lexer.nextToken();
-			if (keyToken.type !== TokenType$1.Name) throw new Error(`PdfObjectParser: expected name as dictionary key at offset ${keyToken.offset}, got ${TokenType$1[keyToken.type]} (${String(keyToken.value)})`);
+			if (keyToken.type !== TokenType$1.Name) throw new PdfParseError({
+				message: `PdfObjectParser: expected name as dictionary key at offset ${keyToken.offset}, got ${TokenType$1[keyToken.type]} (${String(keyToken.value)})`,
+				offset: keyToken.offset,
+				expected: "name token as dictionary key",
+				actual: `${TokenType$1[keyToken.type]} (${String(keyToken.value)})`,
+				data: this.lexer.rawData
+			});
 			const key = keyToken.value;
 			const value = this.parseObject();
 			dict.set(key, value);
@@ -4500,13 +4652,25 @@ var PdfObjectParser = class {
 	*/
 	readStream(dict) {
 		const streamKw = this.lexer.nextToken();
-		if (streamKw.type !== TokenType$1.StreamKeyword) throw new Error(`PdfObjectParser.readStream: expected 'stream' keyword at offset ${streamKw.offset}, got ${TokenType$1[streamKw.type]}`);
+		if (streamKw.type !== TokenType$1.StreamKeyword) throw new PdfParseError({
+			message: `PdfObjectParser.readStream: expected 'stream' keyword at offset ${streamKw.offset}, got ${TokenType$1[streamKw.type]}`,
+			offset: streamKw.offset,
+			expected: "'stream' keyword",
+			actual: `${TokenType$1[streamKw.type]}`,
+			data: this.lexer.rawData
+		});
 		this.skipStreamEol();
 		const length = this.resolveStreamLength(dict);
 		const data = this.lexer.readStreamData(length);
 		this.skipEndstreamWhitespace();
 		const endKw = this.lexer.nextToken();
-		if (endKw.type !== TokenType$1.EndStreamKeyword) throw new Error(`PdfObjectParser.readStream: expected 'endstream' keyword at offset ${endKw.offset}, got ${TokenType$1[endKw.type]} (${String(endKw.value)})`);
+		if (endKw.type !== TokenType$1.EndStreamKeyword) throw new PdfParseError({
+			message: `PdfObjectParser.readStream: expected 'endstream' keyword at offset ${endKw.offset}, got ${TokenType$1[endKw.type]} (${String(endKw.value)})`,
+			offset: endKw.offset,
+			expected: "'endstream' keyword",
+			actual: `${TokenType$1[endKw.type]} (${String(endKw.value)})`,
+			data: this.lexer.rawData
+		});
 		return new require_pdfCatalog.PdfStream(dict, data);
 	}
 	/**
@@ -4551,18 +4715,42 @@ var PdfObjectParser = class {
 	*/
 	resolveStreamLength(dict) {
 		const lengthObj = dict.get("/Length");
-		if (lengthObj === void 0) throw new Error("PdfObjectParser.resolveStreamLength: stream dictionary is missing /Length");
+		if (lengthObj === void 0) throw new PdfParseError({
+			message: "PdfObjectParser.resolveStreamLength: stream dictionary is missing /Length",
+			offset: this.lexer.position,
+			expected: "/Length entry in stream dictionary",
+			actual: "no /Length entry",
+			data: this.lexer.rawData
+		});
 		if (lengthObj.kind === "number") return lengthObj.value;
 		if (lengthObj.kind === "ref") {
 			const ref = lengthObj;
 			const resolved = this.registry.resolve(ref);
 			if (resolved !== void 0) {
-				if (resolved.kind !== "number") throw new Error(`PdfObjectParser.resolveStreamLength: /Length reference ${ref.objectNumber} ${ref.generationNumber} R resolved to ${resolved.kind}, expected number`);
+				if (resolved.kind !== "number") throw new PdfParseError({
+					message: `PdfObjectParser.resolveStreamLength: /Length reference ${ref.objectNumber} ${ref.generationNumber} R resolved to ${resolved.kind}, expected number`,
+					offset: this.lexer.position,
+					expected: "number for /Length reference",
+					actual: `${resolved.kind}`,
+					data: this.lexer.rawData
+				});
 				return resolved.value;
 			}
-			throw new Error(`PdfObjectParser.resolveStreamLength: /Length reference ${ref.objectNumber} ${ref.generationNumber} R is not yet resolved in the registry. Parse the referenced object first.`);
+			throw new PdfParseError({
+				message: `PdfObjectParser.resolveStreamLength: /Length reference ${ref.objectNumber} ${ref.generationNumber} R is not yet resolved in the registry. Parse the referenced object first.`,
+				offset: this.lexer.position,
+				expected: "resolved /Length reference",
+				actual: `unresolved reference ${ref.objectNumber} ${ref.generationNumber} R`,
+				data: this.lexer.rawData
+			});
 		}
-		throw new Error(`PdfObjectParser.resolveStreamLength: /Length must be a number or indirect reference, got ${lengthObj.kind}`);
+		throw new PdfParseError({
+			message: `PdfObjectParser.resolveStreamLength: /Length must be a number or indirect reference, got ${lengthObj.kind}`,
+			offset: this.lexer.position,
+			expected: "number or indirect reference for /Length",
+			actual: `${lengthObj.kind}`,
+			data: this.lexer.rawData
+		});
 	}
 };
 
@@ -4643,10 +4831,10 @@ async function tryLoadLibdeflate() {
 	if (libdeflateAttempted) return libdeflateEngine;
 	libdeflateAttempted = true;
 	try {
-		const { LibdeflateWasm: LibdeflateCtor, initDeflateWasm } = await Promise.resolve().then(() => require("./libdeflateWasm-DeU6cupL.cjs")).then((n) => n.libdeflateWasm_exports);
+		const { LibdeflateWasm: LibdeflateCtor, initDeflateWasm } = await Promise.resolve().then(() => require("./libdeflateWasm-OkNoqBnO.cjs")).then((n) => n.libdeflateWasm_exports);
 		let customBytes;
 		try {
-			const { getWasmLoaderConfig } = await Promise.resolve().then(() => require("./loader-DWwMj8jZ.cjs"));
+			const { getWasmLoaderConfig } = await Promise.resolve().then(() => require("./loader-_fqS-TmT.cjs"));
 			customBytes = getWasmLoaderConfig().moduleBytes?.["libdeflate"];
 		} catch {}
 		await initDeflateWasm(customBytes);
@@ -4764,9 +4952,19 @@ function stringToLatin1Bytes(str) {
 */
 function extractTrailer(dict) {
 	const sizeVal = numVal$2(dict.get("/Size"));
-	if (sizeVal === void 0) throw new Error("Invalid PDF: trailer dictionary missing /Size entry");
+	if (sizeVal === void 0) throw new PdfParseError({
+		message: "Invalid PDF: trailer dictionary missing /Size entry",
+		offset: 0,
+		expected: "/Size entry in trailer dictionary",
+		actual: "no /Size entry"
+	});
 	const rootRef = refVal(dict.get("/Root"));
-	if (rootRef === void 0) throw new Error("Invalid PDF: trailer dictionary missing /Root entry");
+	if (rootRef === void 0) throw new PdfParseError({
+		message: "Invalid PDF: trailer dictionary missing /Root entry",
+		offset: 0,
+		expected: "/Root entry in trailer dictionary",
+		actual: "no /Root entry"
+	});
 	const trailer = {
 		size: sizeVal,
 		rootRef
@@ -4805,7 +5003,12 @@ async function decodeStream$1(streamData, dict) {
 		const arr = filter;
 		if (arr.length > 0 && arr.items[0].kind === "name") filterName = arr.items[0].value;
 	}
-	if (filterName !== "/FlateDecode") throw new Error(`Unsupported xref stream filter: ${filterName ?? "unknown"}. Only /FlateDecode is supported for cross-reference streams.`);
+	if (filterName !== "/FlateDecode") throw new PdfParseError({
+		message: `Unsupported xref stream filter: ${filterName ?? "unknown"}. Only /FlateDecode is supported for cross-reference streams.`,
+		offset: 0,
+		expected: "/FlateDecode filter",
+		actual: `${filterName ?? "unknown"} filter`
+	});
 	let decompressed = await decompress(streamData);
 	const decodeParms = dict.get("/DecodeParms");
 	if (decodeParms !== void 0 && decodeParms.kind === "dict") {
@@ -4939,11 +5142,30 @@ var XrefParser = class {
 		const startPos = this.data.length - searchWindow;
 		const tail = TEXT_DECODER$1.decode(this.data.subarray(startPos, this.data.length));
 		const idx = tail.lastIndexOf("startxref");
-		if (idx === -1) throw new Error("Invalid PDF: could not find \"startxref\" marker in the last 2048 bytes. The file may be truncated or corrupt.");
-		const match = tail.substring(idx + 9).trim().match(/^(\d+)/);
-		if (!match) throw new Error("Invalid PDF: \"startxref\" found but no valid offset follows it.");
+		if (idx === -1) throw new PdfParseError({
+			message: "Invalid PDF: could not find \"startxref\" marker in the last 2048 bytes. The file may be truncated or corrupt.",
+			offset: startPos,
+			expected: "\"startxref\" marker near end of file",
+			actual: "no \"startxref\" found",
+			data: this.data
+		});
+		const afterKeyword = tail.substring(idx + 9).trim();
+		const match = afterKeyword.match(/^(\d+)/);
+		if (!match) throw new PdfParseError({
+			message: "Invalid PDF: \"startxref\" found but no valid offset follows it.",
+			offset: startPos + idx,
+			expected: "decimal offset after \"startxref\"",
+			actual: `"${afterKeyword.substring(0, 20)}"`,
+			data: this.data
+		});
 		const offset = parseInt(match[1], 10);
-		if (offset < 0 || offset >= this.data.length) throw new Error(`Invalid PDF: startxref offset ${offset} is out of range (file size: ${this.data.length}).`);
+		if (offset < 0 || offset >= this.data.length) throw new PdfParseError({
+			message: `Invalid PDF: startxref offset ${offset} is out of range (file size: ${this.data.length}).`,
+			offset: startPos + idx,
+			expected: `offset in range [0, ${this.data.length})`,
+			actual: `${offset}`,
+			data: this.data
+		});
 		return offset;
 	}
 	/**
@@ -4996,7 +5218,13 @@ var XrefParser = class {
 			const prevVal = numVal$2(trailerDict.get("/Prev"));
 			currentOffset = prevVal !== void 0 && prevVal >= 0 ? prevVal : void 0;
 		}
-		if (primaryTrailer === void 0) throw new Error("Invalid PDF: could not extract a valid trailer from the cross-reference structure.");
+		if (primaryTrailer === void 0) throw new PdfParseError({
+			message: "Invalid PDF: could not extract a valid trailer from the cross-reference structure.",
+			offset: startOffset,
+			expected: "valid trailer dictionary in cross-reference structure",
+			actual: "no valid trailer found",
+			data: this.data
+		});
 		return {
 			entries,
 			trailer: primaryTrailer
@@ -5024,14 +5252,26 @@ var XrefParser = class {
 		const entries = [];
 		let pos = offset;
 		const xrefTag = TEXT_DECODER$1.decode(this.data.subarray(pos, pos + 4));
-		if (xrefTag !== "xref") throw new Error(`Invalid PDF: expected "xref" keyword at offset ${offset}, found "${xrefTag}".`);
+		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
+		});
 		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;
 			const headerLine = this.readLineAt(pos);
 			const headerMatch = headerLine.text.trim().match(/^(\d+)\s+(\d+)/);
-			if (!headerMatch) throw new Error(`Invalid PDF: malformed xref subsection header at offset ${pos}: "${headerLine.text.trim()}"`);
+			if (!headerMatch) throw new PdfParseError({
+				message: `Invalid PDF: malformed xref subsection header at offset ${pos}: "${headerLine.text.trim()}"`,
+				offset: pos,
+				expected: "xref subsection header \"firstObjNum count\"",
+				actual: `"${headerLine.text.trim()}"`,
+				data: this.data
+			});
 			const firstObjNum = parseInt(headerMatch[1], 10);
 			const count = parseInt(headerMatch[2], 10);
 			pos = headerLine.nextPos;
@@ -5039,7 +5279,13 @@ var XrefParser = class {
 				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 Error(`Invalid PDF: malformed xref entry at offset ${pos} for object ${objectNumber}: "${entryText.text.trim()}"`);
+				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];
@@ -5053,10 +5299,22 @@ var XrefParser = class {
 			}
 		}
 		const trailerTag = TEXT_DECODER$1.decode(this.data.subarray(pos, pos + 7));
-		if (trailerTag !== "trailer") throw new Error(`Invalid PDF: expected "trailer" keyword at offset ${pos}, found "${trailerTag}".`);
+		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
+		});
 		pos += 7;
 		const trailerObj = this.objectParser.parseObjectAt(pos);
-		if (trailerObj.kind !== "dict") throw new Error(`Invalid PDF: expected dictionary after "trailer" keyword at offset ${pos}, got ${trailerObj.kind}.`);
+		if (trailerObj.kind !== "dict") throw new PdfParseError({
+			message: `Invalid PDF: expected dictionary after "trailer" keyword at offset ${pos}, got ${trailerObj.kind}.`,
+			offset: pos,
+			expected: "dictionary after \"trailer\" keyword",
+			actual: `${trailerObj.kind}`,
+			data: this.data
+		});
 		return {
 			entries,
 			trailerDict: trailerObj
@@ -5075,22 +5333,58 @@ var XrefParser = class {
 	*/
 	async parseXrefStream(offset) {
 		const { object } = this.objectParser.parseIndirectObjectAt(offset);
-		if (object.kind !== "stream") throw new Error(`Invalid PDF: expected stream object at offset ${offset} for xref stream, got ${object.kind}.`);
+		if (object.kind !== "stream") throw new PdfParseError({
+			message: `Invalid PDF: expected stream object at offset ${offset} for xref stream, got ${object.kind}.`,
+			offset,
+			expected: "stream object for xref stream",
+			actual: `${object.kind}`,
+			data: this.data
+		});
 		const stream = object;
 		const dict = stream.dict;
 		const typeObj = dict.get("/Type");
-		if (typeObj === void 0 || typeObj.kind !== "name" || typeObj.value !== "/XRef") throw new Error(`Invalid PDF: cross-reference stream at offset ${offset} does not have /Type /XRef.`);
+		if (typeObj === void 0 || typeObj.kind !== "name" || typeObj.value !== "/XRef") throw new PdfParseError({
+			message: `Invalid PDF: cross-reference stream at offset ${offset} does not have /Type /XRef.`,
+			offset,
+			expected: "/Type /XRef in cross-reference stream dictionary",
+			actual: typeObj ? `${typeObj.kind}` : "no /Type entry",
+			data: this.data
+		});
 		const wObj = dict.get("/W");
-		if (wObj === void 0 || wObj.kind !== "array") throw new Error("Invalid PDF: cross-reference stream missing /W (field widths) array.");
+		if (wObj === void 0 || wObj.kind !== "array") throw new PdfParseError({
+			message: "Invalid PDF: cross-reference stream missing /W (field widths) array.",
+			offset,
+			expected: "/W array in cross-reference stream",
+			actual: wObj ? `${wObj.kind}` : "no /W entry",
+			data: this.data
+		});
 		const wArr = wObj;
-		if (wArr.length < 3) throw new Error("Invalid PDF: cross-reference stream /W array must have at least 3 elements.");
+		if (wArr.length < 3) throw new PdfParseError({
+			message: "Invalid PDF: cross-reference stream /W array must have at least 3 elements.",
+			offset,
+			expected: "/W array with at least 3 elements",
+			actual: `/W array with ${wArr.length} element(s)`,
+			data: this.data
+		});
 		const w0 = numVal$2(wArr.items[0]) ?? 0;
 		const w1 = numVal$2(wArr.items[1]) ?? 0;
 		const w2 = numVal$2(wArr.items[2]) ?? 0;
 		const entryWidth = w0 + w1 + w2;
-		if (entryWidth === 0) throw new Error("Invalid PDF: cross-reference stream /W widths sum to 0.");
+		if (entryWidth === 0) throw new PdfParseError({
+			message: "Invalid PDF: cross-reference stream /W widths sum to 0.",
+			offset,
+			expected: "non-zero sum of /W widths",
+			actual: "0",
+			data: this.data
+		});
 		const size = numVal$2(dict.get("/Size"));
-		if (size === void 0) throw new Error("Invalid PDF: cross-reference stream missing /Size.");
+		if (size === void 0) throw new PdfParseError({
+			message: "Invalid PDF: cross-reference stream missing /Size.",
+			offset,
+			expected: "/Size entry in cross-reference stream",
+			actual: "no /Size entry",
+			data: this.data
+		});
 		let subsections;
 		const indexObj = dict.get("/Index");
 		if (indexObj !== void 0 && indexObj.kind === "array") {
@@ -5180,7 +5474,13 @@ var XrefParser = class {
 				type: "in-use"
 			});
 		}
-		if (entries.size === 0) throw new Error("Invalid PDF: could not find any indirect objects during recovery scan. The file may not be a valid PDF.");
+		if (entries.size === 0) throw new PdfParseError({
+			message: "Invalid PDF: could not find any indirect objects during recovery scan. The file may not be a valid PDF.",
+			offset: 0,
+			expected: "at least one \"N G obj\" pattern in file",
+			actual: "no indirect objects found",
+			data: this.data
+		});
 		let rootRef;
 		let infoRef;
 		const trailerIdx = fileText.lastIndexOf("trailer");
@@ -5203,7 +5503,13 @@ var XrefParser = class {
 				}
 			}
 		} catch {}
-		if (rootRef === void 0) throw new Error("Invalid PDF: recovery scan could not locate the document catalog (/Root). The file appears to be severely corrupt.");
+		if (rootRef === void 0) throw new PdfParseError({
+			message: "Invalid PDF: recovery scan could not locate the document catalog (/Root). The file appears to be severely corrupt.",
+			offset: 0,
+			expected: "document catalog (/Type /Catalog) in recovery scan",
+			actual: "no /Root or /Catalog found",
+			data: this.data
+		});
 		const trailer = {
 			size: (entries.size > 0 ? entries.keys().reduce((max, n) => Math.max(max, n), 0) : 0) + 1,
 			rootRef
@@ -6916,7 +7222,13 @@ var PdfDocumentParser = class {
 	* @param data  The raw PDF file bytes as a Uint8Array.
 	*/
 	constructor(data) {
-		if (data.length < 8) throw new Error("Invalid PDF: file is too short to contain a valid PDF header.");
+		if (data.length < 8) throw new PdfParseError({
+			message: "Invalid PDF: file is too short to contain a valid PDF header.",
+			offset: 0,
+			expected: "at least 8 bytes for a valid PDF header",
+			actual: `${data.length} bytes`,
+			data
+		});
 		this.data = data;
 	}
 	/**
@@ -6967,7 +7279,14 @@ var PdfDocumentParser = class {
 			const { object } = this.objectParser.parseIndirectObjectAt(entry.offset);
 			resolved = object;
 		} catch (err) {
-			throw new Error(`Failed to parse indirect object ${objNum} ${entry.generationNumber} at offset ${entry.offset}`, { cause: err });
+			throw new PdfParseError({
+				message: `Failed to parse indirect object ${objNum} ${entry.generationNumber} at offset ${entry.offset}`,
+				offset: entry.offset,
+				expected: `valid indirect object ${objNum} ${entry.generationNumber}`,
+				actual: "parse failure",
+				data: this.data,
+				cause: err instanceof Error ? err : void 0
+			});
 		}
 		this.objectCache.set(objNum, resolved);
 		return resolved;
@@ -6991,7 +7310,13 @@ var PdfDocumentParser = class {
 		const encryptRef = this.trailer.encryptRef;
 		this.encryptDictObjNum = encryptRef.objectNumber;
 		const encryptObj = this.resolveRef(encryptRef);
-		if (encryptObj.kind !== "dict") throw new Error("Invalid PDF: /Encrypt entry is not a dictionary.");
+		if (encryptObj.kind !== "dict") throw new PdfParseError({
+			message: "Invalid PDF: /Encrypt entry is not a dictionary.",
+			offset: 0,
+			expected: "dictionary for /Encrypt entry",
+			actual: `${encryptObj.kind}`,
+			data: this.data
+		});
 		const encryptDict = encryptObj;
 		const fileId = this.trailer.id?.[0] ?? new Uint8Array(0);
 		const passwordsToTry = [];
@@ -7006,8 +7331,21 @@ var PdfDocumentParser = class {
 		} catch (err) {
 			lastError = err instanceof Error ? err : new Error(String(err));
 		}
-		if (password !== void 0) throw new Error(`Failed to decrypt PDF: the provided password is incorrect. ${lastError?.message ?? ""}`);
-		else throw new Error("This PDF is encrypted and requires a password. Pass { password: \"...\" } in the options to decrypt it.");
+		if (password !== void 0) throw new PdfParseError({
+			message: `Failed to decrypt PDF: the provided password is incorrect. ${lastError?.message ?? ""}`,
+			offset: 0,
+			expected: "valid decryption password",
+			actual: "incorrect password",
+			data: this.data,
+			cause: lastError
+		});
+		else throw new PdfParseError({
+			message: "This PDF is encrypted and requires a password. Pass { password: \"...\" } in the options to decrypt it.",
+			offset: 0,
+			expected: "unencrypted PDF or password option",
+			actual: "encrypted PDF without password",
+			data: this.data
+		});
 	}
 	/**
 	* Decrypt all resolved objects in the object cache.
@@ -7103,7 +7441,12 @@ var PdfDocumentParser = class {
 	* @throws           If the page index is out of range.
 	*/
 	getPageDict(pageIndex) {
-		if (pageIndex < 0 || pageIndex >= this.flattenedPages.length) throw new Error(`Page index ${pageIndex} is out of range. The document has ${this.flattenedPages.length} page(s).`);
+		if (pageIndex < 0 || pageIndex >= this.flattenedPages.length) throw new PdfParseError({
+			message: `Page index ${pageIndex} is out of range. The document has ${this.flattenedPages.length} page(s).`,
+			offset: 0,
+			expected: `page index in range [0, ${this.flattenedPages.length})`,
+			actual: `${pageIndex}`
+		});
 		return this.flattenedPages[pageIndex].dict;
 	}
 	/**
@@ -7123,16 +7466,34 @@ var PdfDocumentParser = class {
 	validateHeader() {
 		const header = TEXT_DECODER.decode(this.data.subarray(0, Math.min(1024, this.data.length)));
 		const pdfIdx = header.indexOf("%PDF-");
-		if (pdfIdx === -1 || pdfIdx > 1024) throw new Error("Invalid PDF: file does not start with \"%PDF-\" header. This may not be a PDF file.");
+		if (pdfIdx === -1 || pdfIdx > 1024) throw new PdfParseError({
+			message: "Invalid PDF: file does not start with \"%PDF-\" header. This may not be a PDF file.",
+			offset: 0,
+			expected: "\"%PDF-\" header near start of file",
+			actual: "no \"%PDF-\" marker found",
+			data: this.data
+		});
 		const versionMatch = header.substring(pdfIdx).match(/%PDF-(\d+\.\d+)/);
-		if (!versionMatch) throw new Error("Invalid PDF: could not parse version from header.");
+		if (!versionMatch) throw new PdfParseError({
+			message: "Invalid PDF: could not parse version from header.",
+			offset: pdfIdx,
+			expected: "\"%PDF-X.Y\" version string",
+			actual: `"${header.substring(pdfIdx, pdfIdx + 10)}"`,
+			data: this.data
+		});
 		this.pdfVersion = versionMatch[1];
 		const majorMinor = this.pdfVersion.split(".");
 		const major = parseInt(majorMinor[0], 10);
 		const minor = parseInt(majorMinor[1], 10);
 		if (major === 1 && minor >= 0 && minor <= 9) return;
 		if (major === 2 && minor >= 0) return;
-		throw new Error(`Unsupported PDF version: ${this.pdfVersion}. Expected PDF 1.0-1.9 or 2.0+.`);
+		throw new PdfParseError({
+			message: `Unsupported PDF version: ${this.pdfVersion}. Expected PDF 1.0-1.9 or 2.0+.`,
+			offset: 0,
+			expected: "PDF version 1.0-1.9 or 2.0+",
+			actual: `PDF version ${this.pdfVersion}`,
+			data: this.data
+		});
 	}
 	/**
 	* Resolve the document catalog dictionary from the trailer's /Root
@@ -7140,12 +7501,24 @@ var PdfDocumentParser = class {
 	*/
 	resolveCatalog() {
 		const rootObj = this.resolveRef(this.trailer.rootRef);
-		if (rootObj.kind !== "dict") throw new Error(`Invalid PDF: /Root (catalog) at object ${this.trailer.rootRef.objectNumber} is not a dictionary (got ${rootObj.kind}).`);
+		if (rootObj.kind !== "dict") throw new PdfParseError({
+			message: `Invalid PDF: /Root (catalog) at object ${this.trailer.rootRef.objectNumber} is not a dictionary (got ${rootObj.kind}).`,
+			offset: 0,
+			expected: "dictionary for /Root (catalog)",
+			actual: `${rootObj.kind}`,
+			data: this.data
+		});
 		const catalog = rootObj;
 		const typeObj = catalog.get("/Type");
 		if (typeObj !== void 0 && typeObj.kind === "name") {
 			const typeName = typeObj.value;
-			if (typeName !== "/Catalog") throw new Error(`Invalid PDF: /Root dictionary has /Type "${typeName}", expected "/Catalog".`);
+			if (typeName !== "/Catalog") throw new PdfParseError({
+				message: `Invalid PDF: /Root dictionary has /Type "${typeName}", expected "/Catalog".`,
+				offset: 0,
+				expected: "/Type /Catalog in /Root dictionary",
+				actual: `/Type "${typeName}"`,
+				data: this.data
+			});
 		}
 		return catalog;
 	}
@@ -7159,9 +7532,21 @@ var PdfDocumentParser = class {
 	*/
 	resolvePageTree(catalog) {
 		const pagesRef = catalog.get("/Pages");
-		if (pagesRef === void 0) throw new Error("Invalid PDF: catalog dictionary missing /Pages entry.");
+		if (pagesRef === void 0) throw new PdfParseError({
+			message: "Invalid PDF: catalog dictionary missing /Pages entry.",
+			offset: 0,
+			expected: "/Pages entry in catalog dictionary",
+			actual: "no /Pages entry",
+			data: this.data
+		});
 		const pagesObj = this.resolveObject(pagesRef);
-		if (pagesObj.kind !== "dict") throw new Error(`Invalid PDF: /Pages entry is not a dictionary (got ${pagesObj.kind}).`);
+		if (pagesObj.kind !== "dict") throw new PdfParseError({
+			message: `Invalid PDF: /Pages entry is not a dictionary (got ${pagesObj.kind}).`,
+			offset: 0,
+			expected: "dictionary for /Pages entry",
+			actual: `${pagesObj.kind}`,
+			data: this.data
+		});
 		const pages = [];
 		this.traversePageTree(pagesObj, {}, pages, /* @__PURE__ */ new Set());
 		return pages;
@@ -7198,7 +7583,13 @@ var PdfDocumentParser = class {
 		}
 		if (typeName === "/Page") {
 			const mediaBox = currentInherited.mediaBox;
-			if (mediaBox === void 0) throw new Error("Invalid PDF: /Page node has no /MediaBox (not even inherited).");
+			if (mediaBox === void 0) throw new PdfParseError({
+				message: "Invalid PDF: /Page node has no /MediaBox (not even inherited).",
+				offset: 0,
+				expected: "/MediaBox on page node or inherited from parent",
+				actual: "no /MediaBox found",
+				data: this.data
+			});
 			result.push({
 				dict: node,
 				mediaBox,
@@ -7210,7 +7601,13 @@ var PdfDocumentParser = class {
 		const kidsObj = node.get("/Kids");
 		if (kidsObj === void 0) return;
 		const kids = this.resolveObject(kidsObj);
-		if (kids.kind !== "array") throw new Error(`Invalid PDF: /Pages /Kids is not an array (got ${kids.kind}).`);
+		if (kids.kind !== "array") throw new PdfParseError({
+			message: `Invalid PDF: /Pages /Kids is not an array (got ${kids.kind}).`,
+			offset: 0,
+			expected: "array for /Pages /Kids",
+			actual: `${kids.kind}`,
+			data: this.data
+		});
 		const kidsArr = kids;
 		for (let i = 0; i < kidsArr.length; i++) {
 			const kidRef = kidsArr.items[i];
@@ -7246,22 +7643,53 @@ var PdfDocumentParser = class {
 			return require_pdfCatalog.PdfNull.instance;
 		}
 		const containerEntry = this.xrefEntries.get(containerNum);
-		if (containerEntry === void 0 || containerEntry.type !== "in-use") throw new Error(`Invalid PDF: object stream ${containerNum} referenced by compressed object ${entry.objectNumber} not found in xref table.`);
+		if (containerEntry === void 0 || containerEntry.type !== "in-use") throw new PdfParseError({
+			message: `Invalid PDF: object stream ${containerNum} referenced by compressed object ${entry.objectNumber} not found in xref table.`,
+			offset: 0,
+			expected: `in-use xref entry for object stream ${containerNum}`,
+			actual: containerEntry ? `${containerEntry.type} entry` : "no entry",
+			data: this.data
+		});
 		let containerObj;
 		try {
 			const { object } = this.objectParser.parseIndirectObjectAt(containerEntry.offset);
 			containerObj = object;
 		} catch (err) {
-			throw new Error(`Failed to parse object stream ${containerNum} at offset ${containerEntry.offset}`, { cause: err });
+			throw new PdfParseError({
+				message: `Failed to parse object stream ${containerNum} at offset ${containerEntry.offset}`,
+				offset: containerEntry.offset,
+				expected: `valid object stream ${containerNum}`,
+				actual: "parse failure",
+				data: this.data,
+				cause: err instanceof Error ? err : void 0
+			});
 		}
-		if (containerObj.kind !== "stream") throw new Error(`Invalid PDF: object ${containerNum} expected to be an object stream but is ${containerObj.kind}.`);
+		if (containerObj.kind !== "stream") throw new PdfParseError({
+			message: `Invalid PDF: object ${containerNum} expected to be an object stream but is ${containerObj.kind}.`,
+			offset: containerEntry.offset,
+			expected: "stream object for object stream",
+			actual: `${containerObj.kind}`,
+			data: this.data
+		});
 		const containerStream = containerObj;
 		const containerDict = containerStream.dict;
 		const typeObj = containerDict.get("/Type");
-		if (typeObj === void 0 || typeObj.kind !== "name" || typeObj.value !== "/ObjStm") throw new Error(`Invalid PDF: object ${containerNum} is not an object stream (/Type /ObjStm).`);
+		if (typeObj === void 0 || typeObj.kind !== "name" || typeObj.value !== "/ObjStm") throw new PdfParseError({
+			message: `Invalid PDF: object ${containerNum} is not an object stream (/Type /ObjStm).`,
+			offset: containerEntry.offset,
+			expected: "/Type /ObjStm in object stream dictionary",
+			actual: typeObj ? `${typeObj.kind}` : "no /Type entry",
+			data: this.data
+		});
 		const n = numVal$1(containerDict.get("/N"));
 		const first = numVal$1(containerDict.get("/First"));
-		if (n === void 0 || first === void 0) throw new Error(`Invalid PDF: object stream ${containerNum} missing /N or /First entries.`);
+		if (n === void 0 || first === void 0) throw new PdfParseError({
+			message: `Invalid PDF: object stream ${containerNum} missing /N or /First entries.`,
+			offset: containerEntry.offset,
+			expected: "/N and /First entries in object stream",
+			actual: `${n === void 0 ? "no /N" : "/N present"}, ${first === void 0 ? "no /First" : "/First present"}`,
+			data: this.data
+		});
 		const decompressedData = this.decompressStreamSync(containerStream);
 		const headerTokens = TEXT_DECODER.decode(decompressedData.subarray(0, first)).trim().split(/\s+/);
 		const objEntries = [];
@@ -7658,7 +8086,7 @@ function undoPngPredictorSync(data, columns) {
 * string.
 *
 * This is the primary entry point for parsing existing PDFs. It creates
-* a {@link PdfDocumentParser}, runs the full parse pipeline, and returns
+* a `PdfDocumentParser`, runs the full parse pipeline, and returns
 * a populated {@link PdfDocument}.
 *
 * @param data     The PDF data as a `Uint8Array`, `ArrayBuffer`, or a
@@ -14212,6 +14640,9 @@ function packBits(pixels, columns, blackIs1) {
 /**
 * Decode JBIG2Decode stream data.
 *
+* Uses the pure-JS decoder (synchronous).  For optional WASM
+* acceleration, use {@link decodeJBIG2Async}.
+*
 * @param data  - The JBIG2-encoded content stream bytes.
 * @param parms - Optional `/DecodeParms` dictionary.  May contain a
 *                `/JBIG2Globals` key with a PdfDict/stream holding
@@ -17536,6 +17967,93 @@ function embedPageAsFormXObject(page, sourceRegistry, targetRegistry, xObjectNam
 	};
 }
 
+//#endregion
+//#region src/core/pdfDocumentEmbed.ts
+/**
+* @module core/pdfDocumentEmbed
+*
+* Pure helper functions for font CMap generation and image format
+* validation/parsing.  Extracted from {@link pdfDocument} to keep the
+* PdfDocument class focused on high-level document management.
+*/
+/**
+* Build a /ToUnicode CMap from a font's cmap table.
+* Maps glyph IDs (used as CIDs with Identity-H) to Unicode codepoints.
+*
+* @param cmapTable  Mapping from Unicode codepoint to glyph ID.
+* @returns          A CMap string suitable for a PDF /ToUnicode stream.
+*/
+function buildToUnicodeCmap(cmapTable) {
+	const gidToUnicode = /* @__PURE__ */ new Map();
+	for (const [codepoint, gid] of cmapTable) if (!gidToUnicode.has(gid)) gidToUnicode.set(gid, codepoint);
+	const entries = gidToUnicode.entries().toArray().sort((a, b) => a[0] - b[0]);
+	const lines = [];
+	lines.push("/CIDInit /ProcSet findresource begin");
+	lines.push("12 dict begin");
+	lines.push("begincmap");
+	lines.push("/CIDSystemInfo");
+	lines.push("<< /Registry (Adobe)");
+	lines.push("/Ordering (UCS)");
+	lines.push("/Supplement 0");
+	lines.push(">> def");
+	lines.push("/CMapName /Adobe-Identity-UCS def");
+	lines.push("/CMapType 2 def");
+	lines.push("1 begincodespacerange");
+	lines.push("<0000> <FFFF>");
+	lines.push("endcodespacerange");
+	const CHUNK_SIZE = 100;
+	for (let i = 0; i < entries.length; i += CHUNK_SIZE) {
+		const chunk = entries.slice(i, i + CHUNK_SIZE);
+		lines.push(`${chunk.length} beginbfchar`);
+		for (const [gid, codepoint] of chunk) {
+			const gidHex = gid.toString(16).padStart(4, "0").toUpperCase();
+			const uniHex = codepoint.toString(16).padStart(4, "0").toUpperCase();
+			lines.push(`<${gidHex}> <${uniHex}>`);
+		}
+		lines.push("endbfchar");
+	}
+	lines.push("endcmap");
+	lines.push("CMapName currentdict /CMap defineresource pop");
+	lines.push("end");
+	lines.push("end");
+	return lines.join("\n");
+}
+/**
+* Validate a JPEG file signature (SOI marker).
+*
+* @param data  The raw file bytes.
+* @throws      If the data is too short or the SOI marker is invalid.
+*/
+function validateJpegSignature(data) {
+	if (data.length < 2 || data[0] !== 255 || data[1] !== 216) throw new Error("Invalid JPEG: bad SOI marker");
+}
+/**
+* Parse width, height, and component count from a JPEG's SOF marker.
+*
+* @param data  The raw JPEG file bytes.
+* @returns     Width, height, and number of color components.
+*/
+function parseJpegDimensions(data) {
+	validateJpegSignature(data);
+	const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+	let offset = 2;
+	while (offset < data.length - 1) {
+		if (data[offset] !== 255) throw new Error("Invalid JPEG: expected marker");
+		const marker = data[offset + 1];
+		if (marker >= 192 && marker <= 195 || marker >= 197 && marker <= 199 || marker >= 201 && marker <= 203 || marker >= 205 && marker <= 207) {
+			const height = view.getUint16(offset + 5, false);
+			return {
+				width: view.getUint16(offset + 7, false),
+				height,
+				components: data[offset + 9]
+			};
+		}
+		const segmentLength = view.getUint16(offset + 2, false);
+		offset += 2 + segmentLength;
+	}
+	throw new Error("Invalid JPEG: SOF marker not found");
+}
+
 //#endregion
 //#region src/core/pdfDocument.ts
 /**
@@ -17939,7 +18457,7 @@ var PdfDocument = class PdfDocument {
 		cidFontDict.set("/DW", require_pdfCatalog.PdfNumber.of(Math.round(metrics.defaultWidth * scale)));
 		cidFontDict.set("/CIDToGIDMap", require_pdfCatalog.PdfName.of("Identity"));
 		const cidFontRef = this.registry.register(cidFontDict);
-		const toUnicodeCmapStr = this.buildToUnicodeCmap(metrics.cmapTable);
+		const toUnicodeCmapStr = buildToUnicodeCmap(metrics.cmapTable);
 		const toUnicodeStream = require_pdfCatalog.PdfStream.fromString(toUnicodeCmapStr);
 		const toUnicodeRef = this.registry.register(toUnicodeStream);
 		const type0Dict = new require_pdfCatalog.PdfDict();
@@ -18056,7 +18574,7 @@ var PdfDocument = class PdfDocument {
 		cidFontDict.set("/W", wArray);
 		cidFontDict.set("/DW", require_pdfCatalog.PdfNumber.of(Math.round(metrics.defaultWidth * scale)));
 		const cidFontRef = this.registry.register(cidFontDict);
-		const toUnicodeCmapStr = this.buildToUnicodeCmap(metrics.cmapTable);
+		const toUnicodeCmapStr = buildToUnicodeCmap(metrics.cmapTable);
 		const toUnicodeStream = require_pdfCatalog.PdfStream.fromString(toUnicodeCmapStr);
 		const toUnicodeRef = this.registry.register(toUnicodeStream);
 		const type0Dict = new require_pdfCatalog.PdfDict();
@@ -18102,46 +18620,6 @@ var PdfDocument = class PdfDocument {
 		return fontRef;
 	}
 	/**
-	* Build a /ToUnicode CMap from the font's cmap table.
-	* Maps glyph IDs (used as CIDs with Identity-H) to Unicode codepoints.
-	* @internal
-	*/
-	buildToUnicodeCmap(cmapTable) {
-		const gidToUnicode = /* @__PURE__ */ new Map();
-		for (const [codepoint, gid] of cmapTable) if (!gidToUnicode.has(gid)) gidToUnicode.set(gid, codepoint);
-		const entries = gidToUnicode.entries().toArray().sort((a, b) => a[0] - b[0]);
-		const lines = [];
-		lines.push("/CIDInit /ProcSet findresource begin");
-		lines.push("12 dict begin");
-		lines.push("begincmap");
-		lines.push("/CIDSystemInfo");
-		lines.push("<< /Registry (Adobe)");
-		lines.push("/Ordering (UCS)");
-		lines.push("/Supplement 0");
-		lines.push(">> def");
-		lines.push("/CMapName /Adobe-Identity-UCS def");
-		lines.push("/CMapType 2 def");
-		lines.push("1 begincodespacerange");
-		lines.push("<0000> <FFFF>");
-		lines.push("endcodespacerange");
-		const CHUNK_SIZE = 100;
-		for (let i = 0; i < entries.length; i += CHUNK_SIZE) {
-			const chunk = entries.slice(i, i + CHUNK_SIZE);
-			lines.push(`${chunk.length} beginbfchar`);
-			for (const [gid, codepoint] of chunk) {
-				const gidHex = gid.toString(16).padStart(4, "0").toUpperCase();
-				const uniHex = codepoint.toString(16).padStart(4, "0").toUpperCase();
-				lines.push(`<${gidHex}> <${uniHex}>`);
-			}
-			lines.push("endbfchar");
-		}
-		lines.push("endcmap");
-		lines.push("CMapName currentdict /CMap defineresource pop");
-		lines.push("end");
-		lines.push("end");
-		return lines.join("\n");
-	}
-	/**
 	* Embed a PNG image.
 	*
 	* Fully decodes the PNG (including filter reconstruction and alpha
@@ -18810,6 +19288,79 @@ var PdfDocument = class PdfDocument {
 		addWatermark(this, options);
 	}
 	/**
+	* Create a soft mask Form XObject that can be used with
+	* {@link PdfPage.applySoftMask}.
+	*
+	* The builder callback receives a {@link SoftMaskBuilder} with methods
+	* for generating grayscale content where white (`1`) represents fully
+	* opaque regions and black (`0`) represents fully transparent regions.
+	*
+	* The returned {@link SoftMaskRef} is passed to
+	* {@link PdfPage.applySoftMask} to activate the mask for subsequent
+	* drawing operations on that page.
+	*
+	* @param width    Width of the mask in points.
+	* @param height   Height of the mask in points.
+	* @param builder  Callback that draws the mask content.
+	* @returns        A reference to the soft mask Form XObject.
+	*
+	* @example
+	* ```ts
+	* const mask = doc.createSoftMask(200, 200, (b) => {
+	*   // White background = fully opaque
+	*   b.drawRectangle(0, 0, 200, 200, 1);
+	*   // Black circle = fully transparent hole
+	*   b.drawCircle(100, 100, 80, 0);
+	* });
+	* page.applySoftMask(mask);
+	* page.drawRectangle({ x: 50, y: 50, width: 200, height: 200, color: rgb(1, 0, 0) });
+	* page.clearSoftMask();
+	* ```
+	*/
+	createSoftMask(width, height, builder) {
+		const maskOps = [];
+		const kappa = .5522847498;
+		builder({
+			drawRectangle(x, y, w, h, gray) {
+				maskOps.push(`${gray} g`);
+				maskOps.push(`${x} ${y} ${w} ${h} re`);
+				maskOps.push("f");
+			},
+			drawCircle(cx, cy, r, gray) {
+				maskOps.push(`${gray} g`);
+				const ox = r * kappa;
+				const oy = r * kappa;
+				maskOps.push(`${cx - r} ${cy} m`);
+				maskOps.push(`${cx - r} ${cy + oy} ${cx - ox} ${cy + r} ${cx} ${cy + r} c`);
+				maskOps.push(`${cx + ox} ${cy + r} ${cx + r} ${cy + oy} ${cx + r} ${cy} c`);
+				maskOps.push(`${cx + r} ${cy - oy} ${cx + ox} ${cy - r} ${cx} ${cy - r} c`);
+				maskOps.push(`${cx - ox} ${cy - r} ${cx - r} ${cy - oy} ${cx - r} ${cy} c`);
+				maskOps.push("f");
+			},
+			pushRawOperators(ops) {
+				maskOps.push(ops);
+			}
+		});
+		const groupDict = new require_pdfCatalog.PdfDict();
+		groupDict.set("/S", require_pdfCatalog.PdfName.of("Transparency"));
+		groupDict.set("/CS", require_pdfCatalog.PdfName.of("DeviceGray"));
+		const formDict = new require_pdfCatalog.PdfDict();
+		formDict.set("/Type", require_pdfCatalog.PdfName.of("XObject"));
+		formDict.set("/Subtype", require_pdfCatalog.PdfName.of("Form"));
+		formDict.set("/BBox", require_pdfCatalog.PdfArray.fromNumbers([
+			0,
+			0,
+			width,
+			height
+		]));
+		formDict.set("/Group", groupDict);
+		const stream = require_pdfCatalog.PdfStream.fromString(maskOps.join("\n"), formDict);
+		return {
+			_tag: "softMask",
+			ref: this.registry.register(stream)
+		};
+	}
+	/**
 	* Apply all pending redactions across all pages.
 	*
 	* Redaction marks are added to individual pages using
@@ -19044,30 +19595,6 @@ var PdfDocument = class PdfDocument {
 function createPdf() {
 	return new PdfDocument();
 }
-/**
-* Parse width, height, and component count from a JPEG's SOF marker.
-* @internal
-*/
-function parseJpegDimensions(data) {
-	if (data.length < 2 || data[0] !== 255 || data[1] !== 216) throw new Error("Invalid JPEG: bad SOI marker");
-	const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
-	let offset = 2;
-	while (offset < data.length - 1) {
-		if (data[offset] !== 255) throw new Error("Invalid JPEG: expected marker");
-		const marker = data[offset + 1];
-		if (marker >= 192 && marker <= 195 || marker >= 197 && marker <= 199 || marker >= 201 && marker <= 203 || marker >= 205 && marker <= 207) {
-			const height = view.getUint16(offset + 5, false);
-			return {
-				width: view.getUint16(offset + 7, false),
-				height,
-				components: data[offset + 9]
-			};
-		}
-		const segmentLength = view.getUint16(offset + 2, false);
-		offset += 2 + segmentLength;
-	}
-	throw new Error("Invalid JPEG: SOF marker not found");
-}
 
 //#endregion
 //#region src/utils/pdfValueHelpers.ts
@@ -19811,7 +20338,7 @@ function compressStream(stream, level) {
 */
 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-BMGFx7Xd.cjs")).then((n) => n.pdfPage_exports);
+	const { PdfPage: _PdfPage } = await Promise.resolve().then(() => require("./pdfPage-BebMv6fN.cjs")).then((n) => n.pdfPage_exports);
 	const registry = doc.getRegistry();
 	const structure = buildDocumentStructure(doc.getInternalPages().map((p) => p.finalize()), {
 		producer: doc.getProducer(),
@@ -23355,10 +23882,10 @@ async function initWasm(options) {
 	if (options === void 0 || typeof options === "string" || options instanceof URL) return;
 	if (wasmInitialized) return;
 	const inits = [];
-	if (options.deflate || options.deflateWasm) inits.push(Promise.resolve().then(() => require("./libdeflateWasm-DeU6cupL.cjs")).then((n) => n.libdeflateWasm_exports).then(async ({ initDeflateWasm }) => {
+	if (options.deflate || options.deflateWasm) inits.push(Promise.resolve().then(() => require("./libdeflateWasm-OkNoqBnO.cjs")).then((n) => n.libdeflateWasm_exports).then(async ({ initDeflateWasm }) => {
 		await initDeflateWasm(options.deflateWasm);
 	}));
-	if (options.png || options.pngWasm) inits.push(Promise.resolve().then(() => require("./pngEmbed-1RWu6KsO.cjs")).then((n) => n.pngEmbed_exports).then(async ({ initPngWasm }) => {
+	if (options.png || options.pngWasm) inits.push(Promise.resolve().then(() => require("./pngEmbed-OYyOe_W0.cjs")).then((n) => n.pngEmbed_exports).then(async ({ initPngWasm }) => {
 		await initPngWasm(options.pngWasm);
 	}));
 	if (options.fonts || options.fontWasm) inits.push(Promise.resolve().then(() => require("./fontSubset-pFc8Dueu.cjs")).then((n) => n.fontSubset_exports).then(async ({ initSubsetWasm }) => {
@@ -23417,6 +23944,7 @@ exports.PdfObjectRegistry = require_pdfCatalog.PdfObjectRegistry;
 exports.PdfOutlineItem = PdfOutlineItem;
 exports.PdfOutlineTree = PdfOutlineTree;
 exports.PdfPage = require_pdfPage.PdfPage;
+exports.PdfParseError = PdfParseError;
 exports.PdfPolyLineAnnotation = PdfPolyLineAnnotation;
 exports.PdfPolygonAnnotation = PdfPolygonAnnotation;
 exports.PdfRadioGroup = PdfRadioGroup;
@@ -23468,8 +23996,10 @@ exports.buildAnnotationDict = require_pdfPage.buildAnnotationDict;
 exports.buildCatalog = require_pdfCatalog.buildCatalog;
 exports.buildDocumentStructure = require_pdfCatalog.buildDocumentStructure;
 exports.buildEmbeddedFilesNameTree = buildEmbeddedFilesNameTree;
+exports.buildGradientObjects = require_pdfPage.buildGradientObjects;
 exports.buildInfoDict = require_pdfCatalog.buildInfoDict;
 exports.buildPageTree = require_pdfCatalog.buildPageTree;
+exports.buildPatternObjects = require_pdfPage.buildPatternObjects;
 exports.buildPkcs7Signature = buildPkcs7Signature;
 exports.buildTimestampRequest = buildTimestampRequest;
 exports.buildViewerPreferencesDict = buildViewerPreferencesDict;
@@ -23536,6 +24066,7 @@ exports.fillEvenOdd = require_pdfPage.fillEvenOdd;
 exports.fillEvenOddAndStroke = require_pdfPage.fillEvenOddAndStroke;
 exports.fillOp = require_pdfPage.fill;
 exports.findSignatures = findSignatures;
+exports.formatHexContext = formatHexContext;
 exports.formatPdfDate = require_pdfCatalog.formatPdfDate;
 exports.generateButtonAppearance = generateButtonAppearance;
 exports.generateCheckboxAppearance = generateCheckboxAppearance;
@@ -23568,6 +24099,7 @@ exports.layoutCombedText = layoutCombedText;
 exports.layoutMultilineText = layoutMultilineText;
 exports.layoutSinglelineText = layoutSinglelineText;
 exports.lineToOp = require_pdfPage.lineTo;
+exports.linearGradient = require_pdfPage.linearGradient;
 exports.linearizePdf = linearizePdf;
 exports.loadPdf = loadPdf;
 exports.markForRedaction = require_pdfPage.markForRedaction;
@@ -23589,6 +24121,7 @@ exports.parseXmpMetadata = parseXmpMetadata;
 exports.popGraphicsState = require_pdfPage.restoreState;
 exports.prepareForSigning = prepareForSigning;
 exports.pushGraphicsState = require_pdfPage.saveState;
+exports.radialGradient = require_pdfPage.radialGradient;
 exports.radians = require_pdfPage.radians;
 exports.radiansToDegrees = require_pdfPage.radiansToDegrees;
 exports.rc4 = rc4;
@@ -23653,6 +24186,7 @@ exports.splitPdf = splitPdf;
 exports.strokeOp = require_pdfPage.stroke;
 exports.summarizeIssues = summarizeIssues;
 exports.svgToPdfOperators = require_pdfPage.svgToPdfOperators;
+exports.tilingPattern = require_pdfPage.tilingPattern;
 exports.translateOp = require_pdfPage.translate;
 exports.validatePdfA = validatePdfA;
 exports.verifyOwnerPassword = verifyOwnerPassword;