feat(pdf-server): rasterize imported annotations via annotationCanvasMap

Adds an 'imported' annotation type for anything in a loaded PDF that we
either don't model (Ink, Polygon, Caret, FileAttachment, ...) or can't
faithfully re-render (Stamp with an appearance stream, e.g. an image
signature). These now:
- Appear in the annotation panel as '<Subtype> (from PDF)'
- Render in our layer as a positioned div whose body is the per-
  annotation canvas pdf.js produced via page.render({annotationCanvasMap})
  - if pdf.js didn't divert it (no hasOwnCanvas), the box is transparent
    over the main-canvas pixel and just captures clicks
- Are selectable and draggable (resize/rotate disabled - bitmap would
  just stretch)
- Are skipped by addAnnotationDicts; getAnnotatedPdfBytes already
  filters baseline ids, so save leaves the original in the PDF.
  Move/delete are UI-only for now (documented).

Link (2) and Popup (16) are excluded - navigational/auxiliary, not
markup.

importPdfjsAnnotation tests added for unsupported-type and
appearance-stamp paths; computeDiff round-trip for 'imported'.

Author: ochafik

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

@@ -338,6 +338,8 @@ export function getAnnotationLabel(def: PdfAnnotationDef): string {
       return "Line";
     case "image":
       return "Image";
+    case "imported":
+      return `${def.subtype} (from PDF)`;
   }
 }
 
@@ -381,6 +383,8 @@ export function getAnnotationColor(def: PdfAnnotationDef): string {
       return "#333";
     case "image":
       return "#999";
+    case "imported":
+      return "#666";
   }
 }
 

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

@@ -590,6 +590,21 @@ body {
   user-select: none;
 }
 
+/* Annotation imported verbatim from the PDF (Stamp/Ink/etc. via
+ * annotationCanvasMap). The body is the rasterized appearance canvas;
+ * if pdf.js didn't divert it (no hasOwnCanvas), the box stays transparent
+ * over the main-canvas pixel and just captures clicks. */
+.annotation-imported {
+  position: absolute;
+  pointer-events: auto;
+  cursor: grab;
+  user-select: none;
+}
+.annotation-imported:hover {
+  outline: 1px dashed var(--accent, #2563eb);
+  outline-offset: 1px;
+}
+
 /* Selection visuals */
 .annotation-selected {
   outline: 2px solid var(--accent, #2563eb);

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

@@ -25,6 +25,7 @@ import {
   type LineAnnotation,
   type StampAnnotation,
   type ImageAnnotation,
+  type ImportedAnnotation,
   type NoteAnnotation,
   type FreetextAnnotation,
   cssColorToRgb,
@@ -1383,6 +1384,10 @@ const DRAGGABLE_TYPES = new Set<string>([
   "stamp",
   "note",
   "image",
+  // "imported" is draggable in the UI but the move does NOT persist to the
+  // PDF on save (addAnnotationDicts skips it). Resize/rotate stay disabled
+  // — the appearance bitmap would just stretch.
+  "imported",
 ]);
 
 function setupAnnotationInteraction(
@@ -1890,6 +1895,25 @@ function paintAnnotationsOnCanvas(
         }
         break;
       }
+
+      case "imported": {
+        const s = pdfRectToScreen(
+          { x: def.x, y: def.y, width: def.width, height: def.height },
+          viewport,
+        );
+        const bmp = annotationCanvasMap.get(def.pdfjsId);
+        ctx.save();
+        if (bmp) {
+          ctx.drawImage(bmp, s.left, s.top, s.width, s.height);
+        } else {
+          ctx.strokeStyle = "#666";
+          ctx.lineWidth = 1;
+          ctx.setLineDash([3, 3]);
+          ctx.strokeRect(s.left, s.top, s.width, s.height);
+        }
+        ctx.restore();
+        break;
+      }
     }
   }
 }
@@ -1987,6 +2011,8 @@ function renderAnnotation(
       return [renderLineAnnotation(def, viewport)];
     case "image":
       return [renderImageAnnotation(def, viewport)];
+    case "imported":
+      return [renderImportedAnnotation(def, viewport)];
   }
 }
 
@@ -2175,6 +2201,45 @@ function renderImageAnnotation(
   return el;
 }
 
+/**
+ * Per-annotation appearance bitmaps from page.render(). Keyed by pdf.js
+ * annotation id (e.g. "118R"). Populated for the current page only —
+ * cleared at the start of each renderPage().
+ */
+const annotationCanvasMap = new Map<string, HTMLCanvasElement>();
+
+function renderImportedAnnotation(
+  def: ImportedAnnotation,
+  viewport: { width: number; height: number; scale: number },
+): HTMLElement {
+  const screen = pdfRectToScreen(
+    { x: def.x, y: def.y, width: def.width, height: def.height },
+    viewport,
+  );
+  const el = document.createElement("div");
+  el.className = "annotation-imported";
+  el.style.left = `${screen.left}px`;
+  el.style.top = `${screen.top}px`;
+  el.style.width = `${screen.width}px`;
+  el.style.height = `${screen.height}px`;
+  el.title = `${def.subtype} (from PDF)`;
+
+  // page.render() may or may not have produced a separate canvas for this
+  // annotation (hasOwnCanvas depends on the PDF's flags). When it did, use
+  // it as a pixel-faithful body; when it didn't, the appearance is on the
+  // main canvas already, so leave the box transparent — it still captures
+  // clicks for select/delete.
+  const canvas = annotationCanvasMap.get(def.pdfjsId);
+  if (canvas) {
+    canvas.style.width = "100%";
+    canvas.style.height = "100%";
+    canvas.style.display = "block";
+    canvas.style.pointerEvents = "none";
+    el.appendChild(canvas);
+  }
+  return el;
+}
+
 // =============================================================================
 // Annotation CRUD
 // =============================================================================
@@ -3166,11 +3231,21 @@ async function renderPage() {
     // Set --scale-factor so CSS font-size/transform rules work correctly.
     textLayerEl.style.setProperty("--scale-factor", `${scale}`);
 
-    // Render canvas - track the task so we can cancel it
+    // Render canvas - track the task so we can cancel it.
+    //
+    // annotationCanvasMap: pdf.js diverts annotations whose appearance needs
+    // its own bitmap (Stamp/Ink/FreeText/etc. with hasOwnCanvas) into
+    // per-id canvases instead of compositing onto the main canvas.
+    // renderImportedAnnotation() pulls from this map so those annotations
+    // become movable DOM elements with pixel-faithful visuals — instead of
+    // unselectable canvas pixels (the old "ghost annotation" problem) or
+    // our lossy text-label re-render.
+    annotationCanvasMap.clear();
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const renderTask = (page.render as any)({
       canvasContext: ctx,
       viewport,
+      annotationCanvasMap,
     });
     currentRenderTask = renderTask;
 

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

@@ -549,6 +549,76 @@ describe("importPdfjsAnnotation", () => {
     expect(result!.page).toBe(2);
   });
 
+  it("imports an unsupported subtype as 'imported' (placement only)", () => {
+    // annotationType 15 = Ink, not in PDFJS_TYPE_MAP. We keep it as a
+    // placement-only "imported" record so it's listed in the panel and
+    // rendered from annotationCanvasMap instead of being dropped.
+    const ann = {
+      annotationType: 15,
+      subtype: "Ink",
+      id: "200R",
+      rect: [100, 200, 180, 260],
+    };
+    const result = importPdfjsAnnotation(ann, 3, 0);
+    expect(result).not.toBeNull();
+    expect(result!.type).toBe("imported");
+    expect(result!.page).toBe(3);
+    expect((result as any).pdfjsId).toBe("200R");
+    expect((result as any).subtype).toBe("Ink");
+    expect((result as any).width).toBeCloseTo(80);
+    expect((result as any).height).toBeCloseTo(60);
+  });
+
+  it("imports an appearance-stream stamp as 'imported' (not text-label)", () => {
+    // A Stamp with hasAppearance carries a custom visual (e.g. an image
+    // signature) that our text-label StampAnnotation can't reproduce.
+    const ann = {
+      annotationType: 13,
+      subtype: "Stamp",
+      id: "118R",
+      rect: [420, 760, 514, 792],
+      hasAppearance: true,
+      contentsObj: { str: "DRAFT" },
+    };
+    const result = importPdfjsAnnotation(ann, 1, 0);
+    expect(result!.type).toBe("imported");
+    expect((result as any).pdfjsId).toBe("118R");
+    expect((result as any).subtype).toBe("Stamp");
+  });
+
+  it("computeDiff: 'imported' present in both baseline and current → no diff", () => {
+    const imp: PdfAnnotationDef = {
+      type: "imported",
+      id: "pdf-118R",
+      page: 1,
+      x: 420,
+      y: 760,
+      width: 94,
+      height: 32,
+      pdfjsId: "118R",
+      subtype: "Stamp",
+    };
+    const diff = computeDiff([imp], [imp], new Map());
+    expect(diff.added).toHaveLength(0);
+    expect(diff.removed).toHaveLength(0);
+  });
+
+  it("computeDiff: deleting an 'imported' annotation lists it in removed", () => {
+    const imp: PdfAnnotationDef = {
+      type: "imported",
+      id: "pdf-118R",
+      page: 1,
+      x: 420,
+      y: 760,
+      width: 94,
+      height: 32,
+      pdfjsId: "118R",
+      subtype: "Stamp",
+    };
+    const diff = computeDiff([imp], [], new Map());
+    expect(diff.removed).toEqual(["pdf-118R"]);
+  });
+
   it("imports a note (Text) annotation", () => {
     const ann = {
       annotationType: 1,

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

@@ -130,6 +130,32 @@ export interface ImageAnnotation extends AnnotationBase {
   aspect?: "preserve" | "ignore";
 }
 
+/**
+ * An annotation that already exists in the loaded PDF and that we render
+ * verbatim from its appearance stream (via pdf.js's annotationCanvasMap)
+ * rather than re-modeling it with one of our shape types.
+ *
+ * Covers two cases:
+ *  - subtypes we don't model (Ink, Polygon, Caret, FileAttachment, …)
+ *  - subtypes we *could* model but whose appearance carries information
+ *    our model would drop (e.g. Stamp with an image signature)
+ *
+ * The rasterized canvas is supplied at render time by mcp-app.ts; this
+ * struct only carries placement and identity. Coords are PDF user-space
+ * (origin bottom-left), matching the other rect-shaped types.
+ */
+export interface ImportedAnnotation extends AnnotationBase {
+  type: "imported";
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  /** pdf.js getAnnotations() id (e.g. "118R") — key into annotationCanvasMap. */
+  pdfjsId: string;
+  /** Original PDF /Subtype (e.g. "Stamp", "Ink") for the panel label. */
+  subtype: string;
+}
+
 export type PdfAnnotationDef =
   | HighlightAnnotation
   | UnderlineAnnotation
@@ -140,7 +166,8 @@ export type PdfAnnotationDef =
   | LineAnnotation
   | FreetextAnnotation
   | StampAnnotation
-  | ImageAnnotation;
+  | ImageAnnotation
+  | ImportedAnnotation;
 
 // =============================================================================
 // Coordinate Conversion (model ↔ internal PDF coords)
@@ -174,6 +201,7 @@ export function convertFromModelCoords(
     case "rectangle":
     case "circle":
     case "image":
+    case "imported":
       return { ...def, y: pageHeight - def.y - def.height };
     case "line":
       return {
@@ -374,6 +402,7 @@ export function defaultColor(type: PdfAnnotationDef["type"]): string {
     case "stamp":
       return "#cc0000";
     case "image":
+    case "imported":
       return "#00000000";
   }
 }
@@ -495,6 +524,11 @@ export async function addAnnotationDicts(
   const pages = pdfDoc.getPages();
 
   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.)
+    if (def.type === "imported") continue;
+
     const pageIdx = def.page - 1;
     if (pageIdx < 0 || pageIdx >= pages.length) continue;
     const page = pages[pageIdx];
@@ -1023,14 +1057,44 @@ export function importPdfjsAnnotation(
   pageNum: number,
   index: number,
 ): PdfAnnotationDef | null {
-  const ourType = PDFJS_TYPE_MAP[ann.annotationType];
-  if (!ourType) return null;
-
-  // Skip form widgets (they're handled separately by AnnotationLayer)
-  if (ann.annotationType === 20) return null;
+  // Skip form widgets (they're handled separately by AnnotationLayer) and
+  // auxiliary types that aren't user-visible markup:
+  //   2 = Link (navigational, AnnotationLayer handles the click target)
+  //  16 = Popup (the speech-bubble UI for a parent annotation, not content)
+  if (
+    ann.annotationType === 20 ||
+    ann.annotationType === 2 ||
+    ann.annotationType === 16
+  ) {
+    return null;
+  }
 
   const id = makeAnnotationId(ann, pageNum, index);
   const color = pdfjsColorToHex(ann.color);
+  const ourType = PDFJS_TYPE_MAP[ann.annotationType];
+
+  // Anything we don't model — and stamps whose visual is an appearance
+  // stream we can't reproduce as a text label — are kept as "imported":
+  // a placement-only record that the renderer fills with the rasterized
+  // appearance from pdf.js's annotationCanvasMap. This keeps Ink, Polygon,
+  // image-signature stamps, etc. visible AND selectable in our layer.
+  const importAsBitmap =
+    !ourType || (ourType === "stamp" && ann.hasAppearance);
+  if (importAsBitmap) {
+    if (!ann.rect) return null;
+    const r = pdfjsRectToRect(ann.rect);
+    return {
+      type: "imported",
+      id,
+      page: pageNum,
+      x: r.x,
+      y: r.y,
+      width: r.width,
+      height: r.height,
+      pdfjsId: String(ann.id ?? ""),
+      subtype: String(ann.subtype ?? `type${ann.annotationType}`),
+    };
+  }
 
   switch (ourType) {
     case "highlight":