fix(pdf-server): radio button + dropdown handling in fill_form and save

ochafik · ochafik · commit 7acc125a1040 · 2026-03-30T20:10:30.000+01:00
Three related bugs around non-text form fields:

Viewer fill_form (mcp-app.ts): writing a string to annotationStorage on
every radio widget trips pdf.js's inverted string coercion
(`value !== buttonValue` → true) — the first-rendered widget checks
itself and clears the rest, so whatever you ask for, you get the first
option. Fix: extract a setFieldInStorage() helper that writes
{value: true} only on the widget whose buttonValue matches, {value: false}
on siblings, matching pdf.js's own change handler. Also covers the
syncFormValuesToStorage() path (localStorage restore).

Save (pdf-annotations.ts): buildAnnotatedPdfBytes only knew about
getTextField/getCheckBox — dropdowns and radios threw in the try block
and fell through the catch, so they were silently dropped on save.
Fix: instanceof dispatch on getFieldMaybe(). For radios, accept either
the option label or a numeric buttonValue (indexed into getOptions()),
since the viewer stores the latter for PDFs with /Opt.

display_pdf output (server.ts): radio groups showed as N identical
`name [Btn]` lines with no way to tell them apart; dropdowns didn't
list their options. Fix: surface buttonValue as exportValue and the
options array from the annotation data already in hand.
diff --git a/examples/pdf-server/server.ts b/examples/pdf-server/server.ts
@@ -857,6 +857,10 @@ interface FormFieldInfo {
   y: number;
   width: number;
   height: number;
+  /** Radio button export value (buttonValue) — distinguishes widgets that share a field name. */
+  exportValue?: string;
+  /** Dropdown/listbox option values, as seen in the widget's `options` array. */
+  options?: string[];
 }
 
 /**
@@ -909,6 +913,16 @@ async function extractFormFieldInfo(
         // Convert to model coords (top-left origin): modelY = pageHeight - pdfY - height
         const modelY = pageHeight - y2;
 
+        // Choice widgets (combo/listbox) carry `options` as
+        // [{exportValue, displayValue}]. Expose export values — that's
+        // what fill_form needs.
+        let options: string[] | undefined;
+        if (Array.isArray(ann.options) && ann.options.length > 0) {
+          options = ann.options
+            .map((o: { exportValue?: string }) => o?.exportValue)
+            .filter((v: unknown): v is string => typeof v === "string");
+        }
+
         fields.push({
           name: fieldName,
           type: fieldType,
@@ -918,6 +932,12 @@ async function extractFormFieldInfo(
           width: Math.round(width),
           height: Math.round(height),
           ...(ann.alternativeText ? { label: ann.alternativeText } : undefined),
+          // Radio: buttonValue is the per-widget export value — the only
+          // thing distinguishing three `size [Btn]` lines from each other.
+          ...(ann.radioButton && ann.buttonValue != null
+            ? { exportValue: String(ann.buttonValue) }
+            : undefined),
+          ...(options?.length ? { options } : undefined),
         });
       }
     }
@@ -1327,6 +1347,14 @@ Set \`elicit_form_inputs\` to true to prompt the user to fill form fields before
               y: z.number(),
               width: z.number(),
               height: z.number(),
+              exportValue: z
+                .string()
+                .optional()
+                .describe("Radio button value — pass this to fill_form"),
+              options: z
+                .array(z.string())
+                .optional()
+                .describe("Dropdown/listbox option values"),
             }),
           )
           .optional()
@@ -1498,8 +1526,14 @@ URL: ${normalized}`,
           for (const f of fields) {
             const label = f.label ? ` "${f.label}"` : "";
             const nameStr = f.name || "(unnamed)";
+            // Radio: =<exportValue> tells the model what value to pass.
+            // Dropdown: options:[...] lists valid choices.
+            const exportSuffix = f.exportValue ? `=${f.exportValue}` : "";
+            const optsSuffix = f.options
+              ? ` options:[${f.options.join(", ")}]`
+              : "";
             lines.push(
-              `    ${nameStr}${label} [${f.type}] at (${f.x},${f.y}) ${f.width}×${f.height}`,
+              `    ${nameStr}${exportSuffix}${label} [${f.type}] at (${f.x},${f.y}) ${f.width}×${f.height}${optsSuffix}`,
             );
           }
         }
diff --git a/examples/pdf-server/src/mcp-app.ts b/examples/pdf-server/src/mcp-app.ts
@@ -2708,24 +2708,70 @@ async function buildFieldNameMap(
   log.info(`Built field name map: ${fieldNameToIds.size} fields`);
 }
 
+/**
+ * Set one form field's value in pdf.js's annotationStorage, in the format
+ * AnnotationLayer expects to READ when it re-renders.
+ *
+ * Radio buttons need per-widget booleans: pdf.js's RadioButtonWidgetAnnotation
+ * render() has inverted string coercion (`value !== buttonValue` → true for
+ * every NON-matching widget), so a string value on all widgets checks the
+ * first rendered one and clears the rest regardless of what you asked for.
+ * Match pdf.js's own change handler instead: `{value: true}` on the widget
+ * whose buttonValue matches, `{value: false}` on the siblings.
+ *
+ * Also patches the live DOM element for the current page so the user sees the
+ * change without waiting for a full re-render.
+ */
+function setFieldInStorage(name: string, value: string | boolean): void {
+  if (!pdfDocument) return;
+  const ids = fieldNameToIds.get(name);
+  if (!ids) return;
+  const storage = pdfDocument.annotationStorage;
+
+  // Radio group: at least one widget ID has a buttonValue recorded.
+  const isRadio = ids.some((id) => radioButtonValues.has(id));
+  if (isRadio) {
+    const want = String(value);
+    for (const id of ids) {
+      const checked = radioButtonValues.get(id) === want;
+      storage.setValue(id, { value: checked });
+      const el = formLayerEl.querySelector(
+        `input[data-element-id="${id}"]`,
+      ) as HTMLInputElement | null;
+      if (el) el.checked = checked;
+    }
+    return;
+  }
+
+  // Text / checkbox / select: same value on every widget (a field can have
+  // multiple widget annotations sharing one /V).
+  const storageValue = typeof value === "boolean" ? value : String(value);
+  for (const id of ids) {
+    storage.setValue(id, { value: storageValue });
+    const el = formLayerEl.querySelector(`[data-element-id="${id}"]`) as
+      | HTMLInputElement
+      | HTMLSelectElement
+      | HTMLTextAreaElement
+      | null;
+    if (!el) continue;
+    if (el instanceof HTMLInputElement && el.type === "checkbox") {
+      el.checked = !!value;
+    } else {
+      el.value = String(value);
+    }
+  }
+}
+
 /** Sync formFieldValues into pdfDocument.annotationStorage so AnnotationLayer renders pre-filled values.
  *  Skips values that match the PDF's baseline — those are already in storage
  *  in pdf.js's native format (which may differ from our string/bool repr,
  *  e.g. checkbox stores "Yes" not `true`). Overwriting with our normalised
  *  form can break the Reset button's ability to restore defaults. */
 function syncFormValuesToStorage(): void {
   if (!pdfDocument || fieldNameToIds.size === 0) return;
-  const storage = pdfDocument.annotationStorage;
   for (const [name, value] of formFieldValues) {
     if (pdfBaselineFormValues.get(name) === value) continue;
-    const ids = fieldNameToIds.get(name);
-    if (ids) {
-      for (const id of ids) {
-        storage.setValue(id, {
-          value: typeof value === "boolean" ? value : String(value),
-        });
-      }
-    }
+    setFieldInStorage(name, value);
   }
 }
 
@@ -4222,44 +4268,10 @@ async function processCommands(commands: PdfCommand[]): Promise<void> {
       case "fill_form":
         for (const field of cmd.fields) {
           formFieldValues.set(field.name, field.value);
-          // Set in PDF.js annotation storage and update DOM elements directly
-          if (pdfDocument) {
-            const ids = fieldNameToIds.get(field.name);
-            if (ids) {
-              for (const id of ids) {
-                pdfDocument.annotationStorage.setValue(id, {
-                  value:
-                    typeof field.value === "boolean"
-                      ? field.value
-                      : String(field.value),
-                });
-                // Update the live DOM element if it exists on the current page
-                const el = formLayerEl.querySelector(
-                  `[data-element-id="${id}"]`,
-                ) as
-                  | HTMLInputElement
-                  | HTMLSelectElement
-                  | HTMLTextAreaElement
-                  | null;
-                if (el) {
-                  if (
-                    el instanceof HTMLInputElement &&
-                    el.type === "checkbox"
-                  ) {
-                    el.checked = !!field.value;
-                  } else if (el instanceof HTMLSelectElement) {
-                    el.value = String(field.value);
-                  } else {
-                    el.value = String(field.value);
-                  }
-                }
-              }
-            } else {
-              log.info(
-                `fill_form: no annotation IDs for field "${field.name}"`,
-              );
-            }
+          if (!fieldNameToIds.has(field.name)) {
+            log.info(`fill_form: no annotation IDs for field "${field.name}"`);
           }
+          setFieldInStorage(field.name, field.value);
         }
         // Re-render to show updated form values (handles fields on other pages)
         renderPage();
diff --git a/examples/pdf-server/src/pdf-annotations.test.ts b/examples/pdf-server/src/pdf-annotations.test.ts
@@ -1031,6 +1031,81 @@ describe("buildAnnotatedPdfBytes", () => {
     const bytes2 = await doc.save();
     expect(bytes2.length).toBeGreaterThan(0);
   });
+
+  describe("form field persistence", () => {
+    // One fixture with every field type we support. pdf-lib's addOptionToPage
+    // writes radio buttonValues as numeric index strings ("0","1","2"), which
+    // is the stress case — the viewer stores those, but .select() wants labels.
+    let formPdfBytes: Uint8Array;
+    beforeAll(async () => {
+      const doc = await PDFDocument.create();
+      const page = doc.addPage([612, 792]);
+      const form = doc.getForm();
+      form.createTextField("name").addToPage(page, { x: 10, y: 700 });
+      form.createCheckBox("agree").addToPage(page, { x: 10, y: 660 });
+      const dd = form.createDropdown("country");
+      dd.addOptions(["USA", "UK", "Canada"]);
+      dd.addToPage(page, { x: 10, y: 620 });
+      const rg = form.createRadioGroup("size");
+      rg.addOptionToPage("small", page, { x: 10, y: 580 });
+      rg.addOptionToPage("medium", page, { x: 50, y: 580 });
+      rg.addOptionToPage("large", page, { x: 90, y: 580 });
+      formPdfBytes = await doc.save();
+    });
+
+    it("writes text, checkbox, dropdown, and radio (by label) in one pass", async () => {
+      const out = await buildAnnotatedPdfBytes(
+        formPdfBytes,
+        [],
+        new Map<string, string | boolean>([
+          ["name", "Alice"],
+          ["agree", true],
+          ["country", "Canada"],
+          ["size", "medium"],
+        ]),
+      );
+      const form = (await PDFDocument.load(out)).getForm();
+      expect(form.getTextField("name").getText()).toBe("Alice");
+      expect(form.getCheckBox("agree").isChecked()).toBe(true);
+      expect(form.getDropdown("country").getSelected()).toEqual(["Canada"]);
+      expect(form.getRadioGroup("size").getSelected()).toBe("medium");
+    });
+
+    it("maps numeric radio buttonValue to option label by index", async () => {
+      // The viewer stores what pdf.js reports as buttonValue ("2"), not the
+      // label. Save must translate or the radio is silently dropped.
+      const out = await buildAnnotatedPdfBytes(
+        formPdfBytes,
+        [],
+        new Map<string, string | boolean>([["size", "2"]]),
+      );
+      const form = (await PDFDocument.load(out)).getForm();
+      expect(form.getRadioGroup("size").getSelected()).toBe("large");
+    });
+
+    it("leaves radio unset when value is neither label nor valid index", async () => {
+      const out = await buildAnnotatedPdfBytes(
+        formPdfBytes,
+        [],
+        new Map<string, string | boolean>([["size", "bogus"]]),
+      );
+      const form = (await PDFDocument.load(out)).getForm();
+      expect(form.getRadioGroup("size").getSelected()).toBeUndefined();
+    });
+
+    it("skips unknown field names without throwing", async () => {
+      const out = await buildAnnotatedPdfBytes(
+        formPdfBytes,
+        [],
+        new Map<string, string | boolean>([
+          ["nonexistent", "x"],
+          ["name", "kept"],
+        ]),
+      );
+      const form = (await PDFDocument.load(out)).getForm();
+      expect(form.getTextField("name").getText()).toBe("kept");
+    });
+  });
 });
 
 // =============================================================================
diff --git a/examples/pdf-server/src/pdf-annotations.ts b/examples/pdf-server/src/pdf-annotations.ts
@@ -18,6 +18,10 @@ import {
   PDFString,
   PDFHexString,
   StandardFonts,
+  PDFTextField,
+  PDFCheckBox,
+  PDFDropdown,
+  PDFRadioGroup,
 } from "pdf-lib";
 
 // =============================================================================
@@ -810,26 +814,45 @@ export async function buildAnnotatedPdfBytes(
   // Add proper PDF annotation objects
   await addAnnotationDicts(pdfDoc, annotations);
 
-  // Apply form fills
+  // Apply form fills. Dispatch on actual field type — getTextField(name) throws
+  // for dropdowns/radios, so the old try/catch silently dropped those on save.
   if (formFields.size > 0) {
     try {
       const form = pdfDoc.getForm();
       for (const [name, value] of formFields) {
-        try {
-          if (typeof value === "boolean") {
-            const checkbox = form.getCheckBox(name);
-            if (value) checkbox.check();
-            else checkbox.uncheck();
+        const field = form.getFieldMaybe(name);
+        if (!field) continue;
+
+        if (field instanceof PDFCheckBox) {
+          if (value) field.check();
+          else field.uncheck();
+        } else if (field instanceof PDFRadioGroup) {
+          // The viewer stores pdf.js's buttonValue, which for PDFs with an
+          // /Opt array is a numeric index ("0","1","2") rather than the
+          // option label pdf-lib's select() expects. Try the label first,
+          // then fall back to indexing into getOptions().
+          const opts = field.getOptions();
+          const s = String(value);
+          if (opts.includes(s)) {
+            field.select(s);
           } else {
-            const textField = form.getTextField(name);
-            textField.setText(value);
+            const idx = Number(s);
+            if (Number.isInteger(idx) && idx >= 0 && idx < opts.length) {
+              field.select(opts[idx]);
+            }
+            // else: value is neither label nor index — leave unset
           }
-        } catch {
-          // Field not found or wrong type — skip
+        } else if (field instanceof PDFDropdown) {
+          // select() auto-enables edit mode for values outside getOptions(),
+          // so this works for both enumerated and free-text combos.
+          field.select(String(value));
+        } else if (field instanceof PDFTextField) {
+          field.setText(String(value));
         }
+        // PDFButton, PDFOptionList, PDFSignature: no fill_form support yet
       }
     } catch {
-      // Form not available — skip
+      // pdfDoc.getForm() throws if the PDF has no AcroForm
     }
   }
 
