Bug: Missing resolver when reading indirect `/Fields` and `/Contents` references

[mutewinter]

Hey, ran into an issue when trying to fill the form fields in a tester PDF: 5E_CharacterSheet_Fillable.pdf. I debugged it with Opus 4.6 and it came up with a fix that works for me. Here's a report of what went wrong and how it was fixed, generated by the agent:

Version: @libpdf/core@0.3.3

In src/document/forms/acro-form.ts line 141:

const fieldsArray = this.dict.getArray("Fields");

getArray("Fields") is called without a resolver. When /Fields is stored as a PdfRef (indirect object), getArray returns undefined because the value's type is "ref", not "array". The method returns [] and the form appears empty.

FieldTree.load() in src/document/forms/field-tree.ts line 69 does it correctly:

const fieldsArray = dict.getArray("Fields", resolve);

Fix: Pass the resolver in AcroForm.getFields():

const fieldsArray = this.dict.getArray("Fields", this.registry.resolve.bind(this.registry));

Consumer workaround: Resolve the indirect /Fields ref before using the form:

function patchIndirectFields(form: PDFForm) {
  const acro = (form as any)._acroForm;
  for (const [key, val] of acro.dict.entries) {
    if (key.value === "Fields" && val.type === "ref") {
      const resolved = acro.registry.resolve(val);
      if (resolved?.type === "array") {
        acro.dict.set("Fields", resolved);
        acro.clearCache();
        form.reloadFields();
      }
      break;
    }
  }
}

Reproduction

Use the 5E_CharacterSheet_Fillable.pdf. Both its /Fields and page 2–3 /Contents entries are indirect references.

[mutewinter]

I also had an issue with flatten that I haven't validated that this is actually a fix for, so I'm just dropping it here in case this seems plausible as well. happy to ignore this or file it as a separate issue.

Bug 2: FormFlattener.wrapAndAppendContent() corrupts pages when /Contents is an indirect reference

In src/document/forms/form-flattener.ts lines 393-420:

private wrapAndAppendContent(page: PdfDict, newContent: Uint8Array): void {
  const existing = page.get("Contents");
  // ...
  if (!existing) {
    page.set("Contents", suffixRef);
  } else if (existing instanceof PdfArray) {
    const newArray = PdfArray.of(prefixRef, ...this.getArrayItems(existing), suffixRef);
    page.set("Contents", newArray);
  } else {
    // Single stream or ref - convert to array with prefix and suffix
    page.set("Contents", PdfArray.of(prefixRef, existing, suffixRef));
  }
}

When /Contents is a PdfRef pointing to a PdfArray of stream refs (an indirectly-stored contents array), the code hits the else branch and wraps the ref as-is: [prefixStream, ref-to-array, suffixStream]. This produces a contents array containing a nested array reference, which PDF viewers cannot interpret. All original page content (backgrounds, borders, artwork) disappears.

Fix: Resolve the existing value before checking its type:

let existing = page.get("Contents");
if (existing instanceof PdfRef) {
  existing = this.registry.resolve(existing);
}

Before

After

You can see the background image etc are gone.

[mutewinter]

Btw I'm using this local patch and it fixes both of the above issues for me:

diff --git a/dist/index.mjs b/dist/index.mjs
--- a/dist/index.mjs
+++ b/dist/index.mjs
@@ -22994,7 +22994,7 @@
 	*/
 	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, "");
@@ -22758,7 +22758,8 @@
 	* 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) existing = this.registry.resolve(existing) ?? existing;
 		const prefixBytes = new Uint8Array([113, 10]);
 		const prefixStream = new PdfStream(new PdfDict(), prefixBytes);
 		const prefixRef = this.registry.register(prefixStream);

[Mythie]

Awesome digging, I'll get this patched straight away.

The swap to resolving everything left a few stragglers 😓