@libpdf/core 0.3.3 → 0.3.4

package/dist/index.d.mts

@@ -153,26 +153,37 @@ declare class PdfBool implements PdfPrimitive {
 //#endregion
 //#region src/objects/pdf-name.d.ts
 /**
- * PDF name object (interned).
+ * PDF name object (interned via WeakRef).
  *
  * In PDF: `/Type`, `/Page`, `/Length`
  *
- * Names are interned using an LRU cache to prevent unbounded memory growth.
- * `PdfName.of("Type") === PdfName.of("Type")` as long as both are in cache.
- * Use `.of()` to get or create instances.
+ * Names are interned using a WeakRef cache: as long as any live object
+ * (e.g. a PdfDict key) holds a strong reference to a PdfName, calling
+ * `PdfName.of()` with the same string returns the *same instance*.
+ * Once all strong references are dropped, the GC may collect the
+ * PdfName and a FinalizationRegistry cleans up the cache entry.
+ *
+ * This avoids the correctness bug of LRU-based caching, where eviction
+ * of a still-referenced name would break Map key identity in PdfDict.
  *
- * Common PDF names (Type, Page, etc.) are pre-cached and always available.
+ * Common PDF names (Type, Page, etc.) are held as static fields and
+ * therefore never collected.
  */
 declare class PdfName implements PdfPrimitive {
   readonly value: string;
   get type(): "name";
+  /** WeakRef cache for interning. Entries are cleaned up by the FinalizationRegistry. */
   private static cache;
+  /** Cleans up dead WeakRef entries from the cache when a PdfName is GC'd. */
+  private static registry;
   /**
-   * Pre-cached common names that should never be evicted.
-   * These are stored separately from the LRU cache.
+   * Pre-cached common names that are always available.
+   * These are stored as static readonly fields, so they always have
+   * strong references and their WeakRefs never die.
    */
   private static readonly permanentCache;
   static readonly Type: PdfName;
+  static readonly Subtype: PdfName;
   static readonly Page: PdfName;
   static readonly Pages: PdfName;
   static readonly Catalog: PdfName;
@@ -182,9 +193,21 @@ declare class PdfName implements PdfPrimitive {
   static readonly MediaBox: PdfName;
   static readonly Resources: PdfName;
   static readonly Contents: PdfName;
+  static readonly Annots: PdfName;
+  static readonly Root: PdfName;
+  static readonly Size: PdfName;
+  static readonly Info: PdfName;
+  static readonly Prev: PdfName;
+  static readonly ID: PdfName;
+  static readonly Encrypt: PdfName;
   static readonly Length: PdfName;
   static readonly Filter: PdfName;
   static readonly FlateDecode: PdfName;
+  static readonly Font: PdfName;
+  static readonly BaseFont: PdfName;
+  static readonly Encoding: PdfName;
+  static readonly XObject: PdfName;
+  static readonly Names: PdfName;
   /** Cached serialized form (e.g. "/Type"). Computed lazily on first toBytes(). */
   private cachedBytes;
   private constructor();
@@ -203,7 +226,9 @@ declare class PdfName implements PdfPrimitive {
    */
   static clearCache(): void;
   /**
-   * Get the current size of the LRU cache.
+   * Get the current number of entries in the WeakRef cache.
+   * This includes entries whose targets may have been GC'd but whose
+   * FinalizationRegistry callbacks haven't run yet.
    */
   static get cacheSize(): number;
   toBytes(writer: ByteWriter): void;

package/dist/index.mjs

@@ -11,7 +11,7 @@ import { createCMSECDSASignature } from "pkijs";
 import { base64 } from "@scure/base";
 
 //#region package.json
-var version = "0.3.3";
+var version = "0.3.4";
 
 //#endregion
 //#region src/objects/pdf-array.ts
@@ -334,32 +334,41 @@ function escapeName$1(name) {
 	return result;
 }
 /**
-* Default cache size for PdfName interning.
-* Can be overridden via PdfName.setCacheSize().
-*/
-const DEFAULT_NAME_CACHE_SIZE = 1e4;
-/**
-* PDF name object (interned).
+* PDF name object (interned via WeakRef).
 *
 * In PDF: `/Type`, `/Page`, `/Length`
 *
-* Names are interned using an LRU cache to prevent unbounded memory growth.
-* `PdfName.of("Type") === PdfName.of("Type")` as long as both are in cache.
-* Use `.of()` to get or create instances.
+* Names are interned using a WeakRef cache: as long as any live object
+* (e.g. a PdfDict key) holds a strong reference to a PdfName, calling
+* `PdfName.of()` with the same string returns the *same instance*.
+* Once all strong references are dropped, the GC may collect the
+* PdfName and a FinalizationRegistry cleans up the cache entry.
 *
-* Common PDF names (Type, Page, etc.) are pre-cached and always available.
+* This avoids the correctness bug of LRU-based caching, where eviction
+* of a still-referenced name would break Map key identity in PdfDict.
+*
+* Common PDF names (Type, Page, etc.) are held as static fields and
+* therefore never collected.
 */
 var PdfName = class PdfName {
 	get type() {
 		return "name";
 	}
-	static cache = new LRUCache({ max: DEFAULT_NAME_CACHE_SIZE });
+	/** WeakRef cache for interning. Entries are cleaned up by the FinalizationRegistry. */
+	static cache = /* @__PURE__ */ new Map();
+	/** Cleans up dead WeakRef entries from the cache when a PdfName is GC'd. */
+	static registry = new FinalizationRegistry((name) => {
+		const ref = PdfName.cache.get(name);
+		if (ref && ref.deref() === void 0) PdfName.cache.delete(name);
+	});
 	/**
-	* Pre-cached common names that should never be evicted.
-	* These are stored separately from the LRU cache.
+	* Pre-cached common names that are always available.
+	* These are stored as static readonly fields, so they always have
+	* strong references and their WeakRefs never die.
 	*/
 	static permanentCache = /* @__PURE__ */ new Map();
 	static Type = PdfName.createPermanent("Type");
+	static Subtype = PdfName.createPermanent("Subtype");
 	static Page = PdfName.createPermanent("Page");
 	static Pages = PdfName.createPermanent("Pages");
 	static Catalog = PdfName.createPermanent("Catalog");
@@ -369,9 +378,21 @@ var PdfName = class PdfName {
 	static MediaBox = PdfName.createPermanent("MediaBox");
 	static Resources = PdfName.createPermanent("Resources");
 	static Contents = PdfName.createPermanent("Contents");
+	static Annots = PdfName.createPermanent("Annots");
+	static Root = PdfName.createPermanent("Root");
+	static Size = PdfName.createPermanent("Size");
+	static Info = PdfName.createPermanent("Info");
+	static Prev = PdfName.createPermanent("Prev");
+	static ID = PdfName.createPermanent("ID");
+	static Encrypt = PdfName.createPermanent("Encrypt");
 	static Length = PdfName.createPermanent("Length");
 	static Filter = PdfName.createPermanent("Filter");
 	static FlateDecode = PdfName.createPermanent("FlateDecode");
+	static Font = PdfName.createPermanent("Font");
+	static BaseFont = PdfName.createPermanent("BaseFont");
+	static Encoding = PdfName.createPermanent("Encoding");
+	static XObject = PdfName.createPermanent("XObject");
+	static Names = PdfName.createPermanent("Names");
 	/** Cached serialized form (e.g. "/Type"). Computed lazily on first toBytes(). */
 	cachedBytes = null;
 	constructor(value) {
@@ -384,12 +405,15 @@ var PdfName = class PdfName {
 	static of(name) {
 		const permanent = PdfName.permanentCache.get(name);
 		if (permanent) return permanent;
-		let cached = PdfName.cache.get(name);
-		if (!cached) {
-			cached = new PdfName(name);
-			PdfName.cache.set(name, cached);
+		const ref = PdfName.cache.get(name);
+		if (ref) {
+			const existing = ref.deref();
+			if (existing) return existing;
 		}
-		return cached;
+		const instance$1 = new PdfName(name);
+		PdfName.cache.set(name, new WeakRef(instance$1));
+		PdfName.registry.register(instance$1, name);
+		return instance$1;
 	}
 	/**
 	* Clear the name cache.
@@ -403,7 +427,9 @@ var PdfName = class PdfName {
 		PdfName.cache.clear();
 	}
 	/**
-	* Get the current size of the LRU cache.
+	* Get the current number of entries in the WeakRef cache.
+	* This includes entries whose targets may have been GC'd but whose
+	* FinalizationRegistry callbacks haven't run yet.
 	*/
 	static get cacheSize() {
 		return PdfName.cache.size;
@@ -21240,13 +21266,14 @@ var WidgetAnnotation = class {
 	* @param state Optional state name for stateful widgets
 	*/
 	setNormalAppearance(stream, state) {
-		let ap = this.dict.getDict("AP");
+		const resolve = this.registry.resolve.bind(this.registry);
+		let ap = this.dict.getDict("AP", resolve);
 		if (!ap) {
 			ap = new PdfDict();
 			this.dict.set("AP", ap);
 		}
 		if (state) {
-			const nEntry = ap.get("N");
+			const nEntry = ap.get("N", resolve);
 			let nDict;
 			if (nEntry instanceof PdfDict && !(nEntry instanceof PdfStream)) nDict = nEntry;
 			else {
@@ -21283,7 +21310,7 @@ var WidgetAnnotation = class {
 	* For checkboxes/radios, this is the value when checked.
 	*/
 	getOnValue() {
-		const ap = this.dict.getDict("AP");
+		const ap = this.dict.getDict("AP", this.registry.resolve.bind(this.registry));
 		if (!ap) return null;
 		const resolve = this.registry.resolve.bind(this.registry);
 		const n = ap.get("N", resolve);
@@ -21300,7 +21327,7 @@ var WidgetAnnotation = class {
 	* @returns True if all states have appearance streams
 	*/
 	hasAppearancesForStates(states) {
-		const ap = this.dict.getDict("AP");
+		const ap = this.dict.getDict("AP", this.registry.resolve.bind(this.registry));
 		if (!ap) return false;
 		const resolve = this.registry.resolve.bind(this.registry);
 		const n = ap.get("N", resolve);
@@ -21315,9 +21342,10 @@ var WidgetAnnotation = class {
 	* Check if this widget has any normal appearance stream.
 	*/
 	hasNormalAppearance() {
-		const ap = this.dict.getDict("AP");
+		const resolve = this.registry.resolve.bind(this.registry);
+		const ap = this.dict.getDict("AP", resolve);
 		if (!ap) return false;
-		const n = ap.get("N");
+		const n = ap.get("N", resolve);
 		return n !== null && n !== void 0;
 	}
 	/**
@@ -21325,7 +21353,7 @@ var WidgetAnnotation = class {
 	* For stateful widgets (checkbox/radio), pass the state name.
 	*/
 	getNormalAppearance(state) {
-		const ap = this.dict.getDict("AP");
+		const ap = this.dict.getDict("AP", this.registry.resolve.bind(this.registry));
 		if (!ap) return null;
 		const resolve = this.registry.resolve.bind(this.registry);
 		const n = ap.get("N", resolve);
@@ -21343,7 +21371,7 @@ var WidgetAnnotation = class {
 	* Get rollover appearance stream (shown on mouse hover).
 	*/
 	getRolloverAppearance(state) {
-		const ap = this.dict.getDict("AP");
+		const ap = this.dict.getDict("AP", this.registry.resolve.bind(this.registry));
 		if (!ap) return null;
 		const resolve = this.registry.resolve.bind(this.registry);
 		const r = ap.get("R", resolve);
@@ -21361,7 +21389,7 @@ var WidgetAnnotation = class {
 	* Get down appearance stream (shown when clicked).
 	*/
 	getDownAppearance(state) {
-		const ap = this.dict.getDict("AP");
+		const ap = this.dict.getDict("AP", this.registry.resolve.bind(this.registry));
 		if (!ap) return null;
 		const resolve = this.registry.resolve.bind(this.registry);
 		const d = ap.get("D", resolve);
@@ -21379,7 +21407,7 @@ var WidgetAnnotation = class {
 	* Get border style.
 	*/
 	getBorderStyle() {
-		const bs = this.dict.getDict("BS");
+		const bs = this.dict.getDict("BS", this.registry.resolve.bind(this.registry));
 		if (!bs) return null;
 		const result = {
 			width: bs.getNumber("W")?.value ?? 1,
@@ -21728,7 +21756,7 @@ var TerminalField = class extends FormField {
 			this._widgets = [new WidgetAnnotation(this.dict, this.ref, this.registry)];
 			return this._widgets;
 		}
-		const kids = this.dict.getArray("Kids");
+		const kids = this.dict.getArray("Kids", this.registry.resolve.bind(this.registry));
 		if (!kids) {
 			this._widgets = [];
 			return this._widgets;
@@ -21757,7 +21785,7 @@ var TerminalField = class extends FormField {
 			this._widgets = [new WidgetAnnotation(this.dict, this.ref, this.registry)];
 			return;
 		}
-		const kids = this.dict.getArray("Kids");
+		const kids = this.dict.getArray("Kids", this.registry.resolve.bind(this.registry));
 		if (!kids) {
 			this._widgets = [];
 			return;
@@ -21794,7 +21822,7 @@ var TerminalField = class extends FormField {
 	*/
 	addWidget(widgetDict) {
 		const widgetRef = this.registry.register(widgetDict);
-		let kids = this.dict.getArray("Kids");
+		let kids = this.dict.getArray("Kids", this.registry.resolve.bind(this.registry));
 		if (!kids) {
 			kids = new PdfArray([]);
 			this.dict.set("Kids", kids);
@@ -21990,7 +22018,7 @@ var DropdownField = class extends TerminalField {
 	* Get available options.
 	*/
 	getOptions() {
-		return parseChoiceOptions(this.dict.getArray("Opt"));
+		return parseChoiceOptions(this.dict.getArray("Opt", this.registry.resolve.bind(this.registry)));
 	}
 	/**
 	* Get current value.
@@ -22066,14 +22094,14 @@ var ListBoxField = class extends TerminalField {
 	* Get available options.
 	*/
 	getOptions() {
-		return parseChoiceOptions(this.dict.getArray("Opt"));
+		return parseChoiceOptions(this.dict.getArray("Opt", this.registry.resolve.bind(this.registry)));
 	}
 	/**
 	* Get selected values.
 	* For multi-select, checks /I (indices) first, then /V.
 	*/
 	getValue() {
-		const indices = this.dict.getArray("I");
+		const indices = this.dict.getArray("I", this.registry.resolve.bind(this.registry));
 		if (indices && indices.length > 0) {
 			const options = this.getOptions();
 			const result = [];
@@ -22122,7 +22150,7 @@ var ListBoxField = class extends TerminalField {
 			const indices = values.map((v) => options.findIndex((o) => o.value === v)).filter((i) => i >= 0).sort((a, b) => a - b);
 			if (indices.length > 0) this.dict.set("I", PdfArray.of(...indices.map((i) => PdfNumber.of(i))));
 			else this.dict.delete("I");
-		}
+		} else this.dict.delete("I");
 		this.needsAppearanceUpdate = true;
 		this.applyChange();
 	}
@@ -22758,7 +22786,11 @@ var FormFlattener = class {
 	* This isolates the original page's graphics state from our additions.
 	*/
 	wrapAndAppendContent(page, newContent) {
-		const existing = page.get("Contents");
+		let existing = page.get("Contents");
+		if (existing instanceof PdfRef) {
+			const resolved = this.registry.resolve(existing);
+			if (resolved instanceof PdfArray) existing = resolved;
+		}
 		const prefixBytes = new Uint8Array([113, 10]);
 		const prefixStream = new PdfStream(new PdfDict(), prefixBytes);
 		const prefixRef = this.registry.register(prefixStream);
@@ -22994,7 +23026,7 @@ var AcroForm = class AcroForm {
 	*/
 	getFields() {
 		if (this.fieldsCache) return this.fieldsCache;
-		const fieldsArray = this.dict.getArray("Fields");
+		const fieldsArray = this.dict.getArray("Fields", this.registry.resolve.bind(this.registry));
 		if (!fieldsArray) return [];
 		const visited = /* @__PURE__ */ new Set();
 		const fields = this.collectFields(fieldsArray, visited, "");
@@ -23253,7 +23285,7 @@ var AcroForm = class AcroForm {
 				field.resolveWidgets();
 				fields.push(field);
 			} else {
-				const childKids = dict.getArray("Kids");
+				const childKids = dict.getArray("Kids", this.registry.resolve.bind(this.registry));
 				if (childKids) fields.push(...this.collectFields(childKids, visited, fullName));
 			}
 		}
@@ -23267,7 +23299,7 @@ var AcroForm = class AcroForm {
 	* - Its /Kids contain widgets (no /T) rather than child fields (have /T)
 	*/
 	isTerminalField(dict) {
-		const kids = dict.getArray("Kids");
+		const kids = dict.getArray("Kids", this.registry.resolve.bind(this.registry));
 		if (!kids || kids.length === 0) return true;
 		let firstKid = kids.at(0);
 		if (!firstKid) return true;
@@ -23326,7 +23358,7 @@ var AcroForm = class AcroForm {
 	* @param fieldRef Reference to the field dictionary
 	*/
 	addField(fieldRef) {
-		let fieldsArray = this.dict.getArray("Fields");
+		let fieldsArray = this.dict.getArray("Fields", this.registry.resolve.bind(this.registry));
 		if (!fieldsArray) {
 			fieldsArray = new PdfArray([]);
 			this.dict.set("Fields", fieldsArray);
@@ -23345,7 +23377,7 @@ var AcroForm = class AcroForm {
 	* @returns true if the field was found and removed, false otherwise
 	*/
 	removeField(fieldRef) {
-		const fieldsArray = this.dict.getArray("Fields");
+		const fieldsArray = this.dict.getArray("Fields", this.registry.resolve.bind(this.registry));
 		if (!fieldsArray) return false;
 		for (let i = 0; i < fieldsArray.length; i++) {
 			const item = fieldsArray.at(i);
@@ -32553,8 +32585,14 @@ var IndirectObjectParser = class {
 	*/
 	readStream(dict) {
 		this.skipStreamEOL();
-		const length = this.resolveLength(dict);
 		const startPos = this.scanner.position;
+		let length;
+		try {
+			length = this.resolveLength(dict);
+		} catch {
+			length = this.findEndStream(startPos);
+			if (length < 0) throw new ObjectParseError("Stream missing /Length and no endstream found");
+		}
 		const data = this.scanner.bytes.subarray(startPos, startPos + length);
 		this.scanner.moveTo(startPos + length);
 		this.skipOptionalEOL();
@@ -32604,6 +32642,43 @@ var IndirectObjectParser = class {
 		} else if (byte === LF) this.scanner.advance();
 	}
 	/**
+	* Scan forward from startPos looking for the "endstream" keyword.
+	* Returns the stream data length (excluding any EOL before endstream),
+	* or -1 if not found.
+	*/
+	findEndStream(startPos) {
+		const bytes = this.scanner.bytes;
+		const len = bytes.length;
+		const sig = [
+			101,
+			110,
+			100,
+			115,
+			116,
+			114,
+			101,
+			97,
+			109
+		];
+		const sigLen = sig.length;
+		for (let i = startPos; i <= len - sigLen; i++) {
+			let match = true;
+			for (let j = 0; j < sigLen; j++) if (bytes[i + j] !== sig[j]) {
+				match = false;
+				break;
+			}
+			if (match) {
+				let end = i;
+				if (end > startPos && bytes[end - 1] === LF) {
+					end--;
+					if (end > startPos && bytes[end - 1] === CR) end--;
+				} else if (end > startPos && bytes[end - 1] === CR) end--;
+				return end - startPos;
+			}
+		}
+		return -1;
+	}
+	/**
 	* Resolve the /Length value from the stream dict.
 	* Handles both direct values and indirect references.
 	*/
@@ -33048,10 +33123,12 @@ var XRefParser = class {
 	* Returns the byte offset where xref starts.
 	*/
 	findStartXRef() {
-		const len = this.scanner.bytes.length;
-		const searchStart = Math.max(0, len - 1024);
+		const bytes = this.scanner.bytes;
+		let effectiveEnd = bytes.length;
+		while (effectiveEnd > 0 && isWhitespace$1(bytes[effectiveEnd - 1])) effectiveEnd--;
+		const searchStart = Math.max(0, effectiveEnd - 1024);
 		let startxrefPos = -1;
-		for (let i = len - 9; i >= searchStart; i--) if (this.matchesAt(i, "startxref")) {
+		for (let i = effectiveEnd - 9; i >= searchStart; i--) if (this.matchesAt(i, "startxref")) {
 			startxrefPos = i;
 			break;
 		}
@@ -34631,7 +34708,7 @@ var NameTree = class {
 				console.warn(`NameTree: max depth (${MAX_DEPTH}) exceeded during lookup`);
 				return null;
 			}
-			const kids = node.getArray("Kids");
+			const kids = node.getArray("Kids", this.resolver);
 			if (!kids || kids.length === 0) return null;
 			let lo$1 = 0;
 			let hi$1 = kids.length - 1;
@@ -34666,7 +34743,7 @@ var NameTree = class {
 			}
 			if (!found) return null;
 		}
-		const names = node.getArray("Names");
+		const names = node.getArray("Names", this.resolver);
 		if (!names) return null;
 		const numPairs = Math.floor(names.length / 2);
 		let lo = 0;
@@ -34710,7 +34787,7 @@ var NameTree = class {
 				continue;
 			}
 			if (node.has("Kids")) {
-				const kids = node.getArray("Kids");
+				const kids = node.getArray("Kids", this.resolver);
 				if (kids) for (let i = 0; i < kids.length; i++) {
 					const kidRef = kids.at(i);
 					if (kidRef instanceof PdfRef) {
@@ -34728,7 +34805,7 @@ var NameTree = class {
 					});
 				}
 			} else if (node.has("Names")) {
-				const names = node.getArray("Names");
+				const names = node.getArray("Names", this.resolver);
 				if (names) for (let i = 0; i < names.length; i += 2) {
 					const key$1 = extractKey(names.at(i));
 					if (key$1 === null) continue;