feat(pdf-server): strip deleted baseline annotations from /Annots on save

buildAnnotatedPdfBytes takes a removedRefs list and walks each page's
/Annots array (backwards) removing matching PDFRef entries.
getAnnotatedPdfBytes computes that list from baseline annotations no
longer in annotationMap, parsing the ref back from our id via
parseAnnotationRef (handles both pdf-<num>-<gen> and pdf-<num>R).

Panel: removed baseline annotations now stay listed as crossed-out cards
with a revert button (mirrors cleared form fields), so the user can see
and undo the pending deletion before save commits it.

Author: ochafik

examples/pdf-server/src/annotation-panel.ts

@@ -289,10 +289,23 @@ function panelFieldNames(): Set<string> {
   return new Set([...formFieldValues.keys(), ...pdfBaselineFormValues.keys()]);
 }
 
+/** Baseline annotations the user has deleted. Shown crossed-out in the panel
+ *  (mirroring cleared form fields) so they can be reverted, and so save knows
+ *  to strip their refs from /Annots. */
+function removedBaselineAnnotations(): PdfAnnotationDef[] {
+  return deps
+    .state()
+    .pdfBaselineAnnotations.filter((a) => !annotationMap.has(a.id));
+}
+
 /** Total count of annotations + form fields for the sidebar badge.
  *  Uses the union so cleared baseline items still contribute. */
 function sidebarItemCount(): number {
-  return annotationMap.size + panelFieldNames().size;
+  return (
+    annotationMap.size +
+    removedBaselineAnnotations().length +
+    panelFieldNames().size
+  );
 }
 
 export function updateAnnotationsBadge(): void {
@@ -429,6 +442,14 @@ export function renderAnnotationPanel(): void {
     byPage.get(page)!.push(tracked);
   }
 
+  // Removed baseline annotations: still listed (crossed-out) so they can be
+  // reverted before save strips them from the file.
+  const removedByPage = new Map<number, PdfAnnotationDef[]>();
+  for (const def of removedBaselineAnnotations()) {
+    if (!removedByPage.has(def.page)) removedByPage.set(def.page, []);
+    removedByPage.get(def.page)!.push(def);
+  }
+
   // Group form fields by page — iterate the UNION so cleared baseline
   // fields remain visible (crossed out) with a per-item revert button.
   const fieldsByPage = new Map<number, string[]>();
@@ -445,7 +466,11 @@ export function renderAnnotationPanel(): void {
   }
 
   // Collect all pages that have annotations or form fields
-  const allPages = new Set([...byPage.keys(), ...fieldsByPage.keys()]);
+  const allPages = new Set([
+    ...byPage.keys(),
+    ...removedByPage.keys(),
+    ...fieldsByPage.keys(),
+  ]);
   const sortedPages = [...allPages].sort((a, b) => a - b);
 
   // Sort annotations within each page by Y position (descending = top-first in PDF coords)
@@ -470,8 +495,9 @@ export function renderAnnotationPanel(): void {
     const sectionKey = `page-${pageNum}`;
     const isOpen = panelState.openAccordionSection === sectionKey;
     const annotations = byPage.get(pageNum) ?? [];
+    const removed = removedByPage.get(pageNum) ?? [];
     const fields = fieldsByPage.get(pageNum) ?? [];
-    const itemCount = annotations.length + fields.length;
+    const itemCount = annotations.length + removed.length + fields.length;
 
     appendAccordionSection(
       `Page ${pageNum} (${itemCount})`,
@@ -487,6 +513,10 @@ export function renderAnnotationPanel(): void {
         for (const tracked of annotations) {
           body.appendChild(createAnnotationCard(tracked));
         }
+        // Then removed baseline annotations (crossed-out, revertable)
+        for (const def of removed) {
+          body.appendChild(createRemovedAnnotationCard(def));
+        }
       },
     );
   }
@@ -652,6 +682,55 @@ function createAnnotationCard(tracked: TrackedAnnotation): HTMLElement {
   return card;
 }
 
+/**
+ * Card for a baseline annotation the user deleted: crossed-out, no select/
+ * navigate (it has no DOM on the page anymore), revert button puts it back
+ * into `annotationMap` so it renders again and save leaves it in the file.
+ */
+function createRemovedAnnotationCard(def: PdfAnnotationDef): HTMLElement {
+  const card = document.createElement("div");
+  card.className = "annotation-card annotation-card-cleared";
+  card.dataset.annotationId = def.id;
+
+  const row = document.createElement("div");
+  row.className = "annotation-card-row";
+
+  const swatch = document.createElement("div");
+  swatch.className = "annotation-card-swatch annotation-card-swatch-cleared";
+  swatch.innerHTML = `<svg width="10" height="10" viewBox="0 0 10 10" stroke="${getAnnotationColor(def)}" stroke-width="1.5" stroke-linecap="round"><path d="M2 2l6 6M8 2L2 8"/></svg>`;
+  row.appendChild(swatch);
+
+  const typeLabel = document.createElement("span");
+  typeLabel.className = "annotation-card-type";
+  typeLabel.textContent = getAnnotationLabel(def);
+  row.appendChild(typeLabel);
+
+  const preview = getAnnotationPreview(def);
+  if (preview) {
+    const previewEl = document.createElement("span");
+    previewEl.className = "annotation-card-preview";
+    previewEl.textContent = preview;
+    row.appendChild(previewEl);
+  }
+
+  const revertBtn = document.createElement("button");
+  revertBtn.className = "annotation-card-delete";
+  revertBtn.title = "Restore annotation from file";
+  revertBtn.innerHTML = REVERT_SVG;
+  revertBtn.addEventListener("click", (e) => {
+    e.stopPropagation();
+    annotationMap.set(def.id, { def: { ...def }, elements: [] });
+    updateAnnotationsBadge();
+    renderAnnotationPanel();
+    deps.renderPage();
+    deps.persistAnnotations();
+  });
+  row.appendChild(revertBtn);
+
+  card.appendChild(row);
+  return card;
+}
+
 /** Revert one field to its PDF-stored baseline value. */
 function revertFieldToBaseline(name: string): void {
   const base = pdfBaselineFormValues.get(name);

examples/pdf-server/src/mcp-app.ts

@@ -35,6 +35,7 @@ import {
   computeDiff,
   isDiffEmpty,
   buildAnnotatedPdfBytes,
+  parseAnnotationRef,
   importPdfjsAnnotation,
   uint8ArrayToBase64,
   convertFromModelCoords,
@@ -2922,19 +2923,29 @@ async function buildFieldNameMap(
       if (!widgetIds) continue; // no widget → not rendered anyway
 
       // Type comes from getFieldObjects (widget annot data doesn't have it).
-      // Value comes from the widget annotation (fall back to field-dict if
-      // the widget didn't expose one).
+      // Value: prefer the AcroForm field-tree value over the widget's
+      // fieldValue. pdf-lib's save() can leave a page widget pointing at a
+      // stale /V while the field tree has the new one (seen with comb text
+      // fields), and getAnnotations() reads the widget. If the two disagree
+      // we push the field-tree value into annotationStorage so the rendered
+      // input matches what's actually in /AcroForm.
       const type = fieldArr.find((f) => f.type)?.type;
-      const raw = widgetFieldValues.has(name)
-        ? widgetFieldValues.get(name)
-        : fieldArr.find((f) => f.value != null)?.value;
+      const fieldTreeRaw = fieldArr.find((f) => f.value != null)?.value;
+      const widgetRaw = widgetFieldValues.get(name);
+      const raw = fieldTreeRaw ?? widgetRaw;
       const v = normaliseFieldValue(type, raw);
       if (v !== null) {
         pdfBaselineFormValues.set(name, v);
         // Seed current state from baseline so the panel shows it. A
         // restored localStorage diff (applied in restoreAnnotations) will
         // overwrite specific fields the user changed.
         if (!formFieldValues.has(name)) formFieldValues.set(name, v);
+        // Widget out of sync with field tree → force storage so
+        // AnnotationLayer renders the field-tree value, not the stale
+        // widget. (syncFormValuesToStorage skips baseline==current.)
+        if (fieldTreeRaw != null && fieldTreeRaw !== widgetRaw) {
+          setFieldInStorage(name, v);
+        }
       }
 
       // Skip parent entries with no concrete id (radio groups: the /T tree
@@ -3036,6 +3047,14 @@ async function getAnnotatedPdfBytes(): Promise<Uint8Array> {
     }
   }
 
+  // Baseline annotations the user deleted: strip their refs from /Annots so
+  // they don't reappear on reload. Ids without a recoverable ref (page-index
+  // fallback) can't be removed by-ref and are skipped.
+  const removedRefs = pdfBaselineAnnotations
+    .filter((a) => !annotationMap.has(a.id))
+    .map((a) => parseAnnotationRef(a.id))
+    .filter((r): r is NonNullable<typeof r> => r !== null);
+
   // Only write fields that actually changed vs. what's already in the PDF.
   // Unchanged fields are no-ops at best, and at worst trip pdf-lib edge
   // cases (max-length text, missing /Yes appearance, …) on fields the user
@@ -3060,6 +3079,7 @@ async function getAnnotatedPdfBytes(): Promise<Uint8Array> {
     fullBytes as Uint8Array,
     annotations,
     formFieldsOut,
+    removedRefs,
   );
 }
 

examples/pdf-server/src/pdf-annotations.test.ts

@@ -10,6 +10,7 @@ import {
   defaultColor,
   importPdfjsAnnotation,
   buildAnnotatedPdfBytes,
+  parseAnnotationRef,
   base64ToUint8Array,
   uint8ArrayToBase64,
   convertFromModelCoords,
@@ -788,6 +789,29 @@ describe("base64 helpers", () => {
 // PDF Annotation Dict Creation (integration test with pdf-lib)
 // =============================================================================
 
+describe("parseAnnotationRef", () => {
+  it("parses pdf-<num>-<gen> ids", () => {
+    expect(parseAnnotationRef("pdf-118-0")).toEqual({
+      objectNumber: 118,
+      generationNumber: 0,
+    });
+    expect(parseAnnotationRef("pdf-5-2")).toEqual({
+      objectNumber: 5,
+      generationNumber: 2,
+    });
+  });
+  it("parses pdf-<num>R ids (pdf.js string id, gen=0)", () => {
+    expect(parseAnnotationRef("pdf-118R")).toEqual({
+      objectNumber: 118,
+      generationNumber: 0,
+    });
+  });
+  it("returns null for page-index fallback ids", () => {
+    expect(parseAnnotationRef("pdf-1-idx-3")).toBeNull();
+    expect(parseAnnotationRef("user-abc")).toBeNull();
+  });
+});
+
 describe("buildAnnotatedPdfBytes", () => {
   let blankPdfBytes: Uint8Array;
 
@@ -808,6 +832,53 @@ describe("buildAnnotatedPdfBytes", () => {
     expect(header).toBe("%PDF-");
   });
 
+  it("strips removedRefs entries from each page's /Annots array", async () => {
+    // Seed: add two highlights, save, capture their object refs.
+    const seeded = await buildAnnotatedPdfBytes(
+      blankPdfBytes,
+      [
+        {
+          type: "highlight",
+          id: "h1",
+          page: 1,
+          rects: [{ x: 72, y: 700, width: 100, height: 12 }],
+          color: "#ffff00",
+        },
+        {
+          type: "highlight",
+          id: "h2",
+          page: 1,
+          rects: [{ x: 72, y: 680, width: 100, height: 12 }],
+          color: "#ffff00",
+        },
+      ],
+      new Map(),
+    );
+    const seededDoc = await PDFDocument.load(seeded);
+    const annots = seededDoc.getPage(0).node.Annots()!;
+    expect(annots.size()).toBe(2);
+    const ref0 = annots.get(0) as unknown as {
+      objectNumber: number;
+      generationNumber: number;
+    };
+
+    // Now remove the first one by ref.
+    const stripped = await buildAnnotatedPdfBytes(seeded, [], new Map(), [
+      { objectNumber: ref0.objectNumber, generationNumber: ref0.generationNumber },
+    ]);
+    const strippedDoc = await PDFDocument.load(stripped);
+    const remaining = strippedDoc.getPage(0).node.Annots();
+    expect(remaining?.size() ?? 0).toBe(1);
+  });
+
+  it("removedRefs ignores refs not present in /Annots", async () => {
+    const out = await buildAnnotatedPdfBytes(blankPdfBytes, [], new Map(), [
+      { objectNumber: 9999, generationNumber: 0 },
+    ]);
+    const doc = await PDFDocument.load(out);
+    expect(doc.getPage(0).node.Annots()?.size() ?? 0).toBe(0);
+  });
+
   it("adds highlight annotation to PDF", async () => {
     const annotations: PdfAnnotationDef[] = [
       {

examples/pdf-server/src/pdf-annotations.ts

@@ -525,8 +525,8 @@ export async function addAnnotationDicts(
 
   for (const def of annotations) {
     // "imported" annotations are already in the source PDF — never
-    // re-serialize them. (Moving/deleting one is UI-only for now; a future
-    // pass can rewrite the page's /Annots array to drop the original ref.)
+    // re-serialize them. Deletion is handled by buildAnnotatedPdfBytes'
+    // removedRefs strip; moving an imported annotation is still UI-only.
     if (def.type === "imported") continue;
 
     const pageIdx = def.page - 1;
@@ -870,17 +870,62 @@ function setButtonGroupValue(
   }
 }
 
+/**
+ * Recover the PDF object reference from an annotation id assigned by
+ * `makeAnnotationId`. Handles both `pdf-<num>-<gen>` (from `ann.ref`) and
+ * `pdf-<num>R` (from pdf.js's string `ann.id`, gen always 0). Returns null for
+ * page-index fallback ids — those have no stable ref to remove by.
+ */
+export function parseAnnotationRef(
+  id: string,
+): { objectNumber: number; generationNumber: number } | null {
+  let m = /^pdf-(\d+)-(\d+)$/.exec(id);
+  if (m) return { objectNumber: +m[1], generationNumber: +m[2] };
+  m = /^pdf-(\d+)R$/.exec(id);
+  if (m) return { objectNumber: +m[1], generationNumber: 0 };
+  return null;
+}
+
 /**
  * Build annotated PDF bytes from the original document.
- * Applies user annotations and form fills, returns Uint8Array of the new PDF.
+ * Applies user annotations and form fills, removes baseline annotations the
+ * user deleted, returns Uint8Array of the new PDF.
  */
 export async function buildAnnotatedPdfBytes(
   pdfBytes: Uint8Array,
   annotations: PdfAnnotationDef[],
   formFields: Map<string, string | boolean>,
+  removedRefs: { objectNumber: number; generationNumber: number }[] = [],
 ): Promise<Uint8Array> {
   const pdfDoc = await PDFDocument.load(pdfBytes, { ignoreEncryption: true });
 
+  // Strip baseline annotations the user deleted. We match on object number +
+  // generation against each page's /Annots array entries (PDFRef). We don't
+  // know which page they were on, so scan every page — /Annots arrays are
+  // small and this only runs at save time.
+  if (removedRefs.length > 0) {
+    const wanted = new Set(
+      removedRefs.map((r) => `${r.objectNumber} ${r.generationNumber}`),
+    );
+    for (const page of pdfDoc.getPages()) {
+      const annots = page.node.Annots();
+      if (!annots) continue;
+      // Walk backwards so .remove(idx) doesn't shift unprocessed entries.
+      for (let i = annots.size() - 1; i >= 0; i--) {
+        const ref = annots.get(i) as {
+          objectNumber?: number;
+          generationNumber?: number;
+        };
+        if (
+          ref?.objectNumber !== undefined &&
+          wanted.has(`${ref.objectNumber} ${ref.generationNumber ?? 0}`)
+        ) {
+          annots.remove(i);
+        }
+      }
+    }
+  }
+
   // Add proper PDF annotation objects
   await addAnnotationDicts(pdfDoc, annotations);