red/.planning/phases/05-pdf-fill-and-field-mapping/05-RESEARCH.md

# Phase 5: PDF Fill and Field Mapping - Research

**Researched:** 2026-03-19
**Domain:** PDF coordinate systems, drag-and-drop field placement, pdf-lib text fill, Next.js API routes
**Confidence:** HIGH

<phase_requirements>
## Phase Requirements

| ID | Description | Research Support |
|----|-------------|-----------------|
| DOC-04 | Agent can drag-and-drop to place signature fields on any page of a PDF document | dnd-kit free-position drag + react-pdf Page overlay pattern; coordinate conversion formula |
| DOC-05 | Agent can fill in text fields (property address, client names, dates, prices) before sending | pdf-lib `PDFDocument.load` + `page.drawText` + `form.flatten()`; server route POST handler |
| DOC-06 | Agent can assign a document to a specific client and initiate a signing request | DB schema adds `signatureFields` JSONB + `assignedClientId` + `status` transition; existing documents table extended |
</phase_requirements>

---

## Summary

Phase 5 has three tightly coupled problems: (1) the UI for placing signature fields on a rendered PDF, (2) the coordinate system translation between screen pixels and PDF user space, and (3) the server-side PDF mutation (fill text + embed signature placeholder rectangles) using a pure-JS PDF library.

The dominant stack for this problem domain is `react-pdf` (wojtekmaj) for rendering + `dnd-kit` for drag interaction + `pdf-lib` (or its maintained fork) for server-side PDF mutation. This combination is proven in the open source community and aligns with the libraries already in use in this codebase. The critical math is the Y-axis flip: PDF user space has bottom-left origin with Y increasing upward; DOM/screen space has top-left origin with Y increasing downward. Every stored coordinate must use PDF user space so that downstream signing and pdf-lib embedding work correctly.

The `pdf-lib` package (Hopding, v1.17.1) is unmaintained — last published 4 years ago. The actively maintained fork `@cantoo/pdf-lib` (v2.6.1, published 18 days ago) is a drop-in replacement with the same API and adds SVG support plus encrypted PDF support. Use `@cantoo/pdf-lib` instead of the original. The signature field approach is to store a plain colored rectangle overlay in the PDF using `pdf-lib`'s `page.drawRectangle` with a border (no AcroForm widget needed at this stage — Phase 6 will embed the actual signature image into that zone).

**Primary recommendation:** Use `dnd-kit` for drag-to-place, read `Page.onLoadSuccess` for scale, apply the Y-flip formula to store PDF-space coords in a JSONB column, and use `@cantoo/pdf-lib` on the server to draw text + rectangle overlays before transitioning document status to "Sent".

---

## Standard Stack

### Core
| Library | Version | Purpose | Why Standard |
|---------|---------|---------|--------------|
| `@dnd-kit/core` | ^6.x | Drag sensor, context, drag events | Lightweight, accessible, React 19 compatible; works with free-position canvas |
| `@dnd-kit/utilities` | ^3.x | `CSS.Translate.toString(transform)` helper | Reduces boilerplate in draggable style binding |
| `@cantoo/pdf-lib` | ^2.6.1 | Server-side PDF mutation: draw text, rectangles, flatten | Actively maintained fork of unmaintained `pdf-lib`; drop-in API replacement |
| `react-pdf` | ^10.4.1 | Already installed; renders PDF pages as canvases | Already in project; `Page.onLoadSuccess` exposes `originalWidth`/`originalHeight` needed for coordinate math |

### Supporting
| Library | Version | Purpose | When to Use |
|---------|---------|---------|-------------|
| `@pdf-lib/fontkit` | ^1.1.1 | Custom font embedding into pdf-lib | Needed only if non-Latin characters appear in text fields; Utah forms are English-only so Helvetica (built-in) suffices for Phase 5 |
| `drizzle-orm/pg-core` `jsonb()` | already installed | Store `signatureFields` array as JSONB | Native to existing Drizzle + Postgres stack |

### Alternatives Considered
| Instead of | Could Use | Tradeoff |
|------------|-----------|----------|
| `@cantoo/pdf-lib` | `pdf-lib` 1.17.1 | Original is unmaintained (4 years); `@cantoo/pdf-lib` is drop-in replacement with active fixes |
| `@cantoo/pdf-lib` | `pdfme` or PSPDFKit | pdfme is a full template system (overkill); PSPDFKit is commercial (violates "zero per month" goal) |
| `dnd-kit` | `react-draggable` | Both work; dnd-kit has better React 19 support, accessibility hooks, and modifier system for snapping |
| `dnd-kit` | `hello-pangea/dnd` | hello-pangea is better for list reordering, not free-canvas positioning |
| DB JSONB for field coords | Separate `document_fields` table | JSONB is simpler and queryable; fields for one document are always read together, no relational join needed |

**Installation:**
```bash
npm install @dnd-kit/core @dnd-kit/utilities @cantoo/pdf-lib
```

---

## Architecture Patterns

### Recommended Project Structure
```
src/
├── app/
│   └── portal/
│       └── (protected)/
│           └── documents/
│               └── [docId]/
│                   ├── page.tsx                    # Server component (existing, extend with edit UI)
│                   └── _components/
│                       ├── PdfViewer.tsx           # Existing — extend with overlay layer
│                       ├── PdfViewerWrapper.tsx    # Existing dynamic wrapper
│                       ├── FieldPlacer.tsx         # NEW: drag-and-drop overlay + field palette
│                       └── TextFillForm.tsx        # NEW: text field form (address, names, dates)
├── app/
│   └── api/
│       └── documents/
│           └── [id]/
│               ├── fields/
│               │   └── route.ts                   # NEW: GET/PUT signature field coordinates
│               └── prepare/
│                   └── route.ts                   # NEW: POST — fill text + burn sig rectangles, set status
├── lib/
│   └── db/
│       └── schema.ts                              # Extend documents table: signatureFields JSONB
└── lib/
    └── pdf/
        └── prepare-document.ts                    # NEW: pdf-lib server utility
```

### Pattern 1: Coordinate Conversion (Screen → PDF User Space)

**What:** Convert browser click/drop coordinates to PDF user-space coordinates (bottom-left origin, points).
**When to use:** Every time a signature field is placed or moved on the PDF overlay.

The `Page` component's `onLoadSuccess` callback provides `originalWidth` and `originalHeight` (in PDF points). The rendered canvas size can be read from `getBoundingClientRect()` on the page container ref.

```typescript
// Source: https://www.pdfscripting.com/public/PDF-Page-Coordinates.cfm
// and https://github.com/wojtekmaj/react-pdf/blob/main/packages/react-pdf/src/Page.tsx

interface PdfPageInfo {
  originalWidth: number;   // PDF points (e.g., 612 for US Letter)
  originalHeight: number;  // PDF points (e.g., 792 for US Letter)
  width: number;           // Rendered px = originalWidth * scale
  height: number;          // Rendered px = originalHeight * scale
  scale: number;
}

/**
 * Convert screen (DOM) coordinates to PDF user-space coordinates.
 * PDF origin is bottom-left; DOM origin is top-left — Y must be flipped.
 *
 * @param screenX   - X in pixels relative to the top-left of the rendered page
 * @param screenY   - Y in pixels relative to the top-left of the rendered page
 * @param pageInfo  - from Page onLoadSuccess callback
 * @returns { x, y } in PDF points with bottom-left origin
 */
function screenToPdfCoords(
  screenX: number,
  screenY: number,
  pageInfo: PdfPageInfo
): { x: number; y: number } {
  const { width: renderedW, height: renderedH, originalWidth, originalHeight } = pageInfo;
  const pdfX = (screenX / renderedW) * originalWidth;
  // Y-axis flip: PDF Y=0 is at the bottom; DOM Y=0 is at the top
  const pdfY = ((renderedH - screenY) / renderedH) * originalHeight;
  return { x: pdfX, y: pdfY };
}
```

### Pattern 2: Drag-and-Drop Field Placement with dnd-kit

**What:** Palette of draggable field tokens on the left; PDF page as the drop zone. On drop, compute PDF coordinates and store in state.
**When to use:** The primary agent interaction for placing signature fields.

```typescript
// Source: https://docs.dndkit.com/api-documentation/draggable/drag-overlay
'use client';
import {
  DndContext,
  useDraggable,
  useDroppable,
  DragEndEvent,
} from '@dnd-kit/core';
import { CSS } from '@dnd-kit/utilities';

// Stored shape of a placed field
interface SignatureField {
  id: string;
  page: number;       // 1-indexed
  x: number;          // PDF user-space points (bottom-left origin)
  y: number;          // PDF user-space points (bottom-left origin)
  width: number;      // PDF points
  height: number;     // PDF points
}

// In parent component:
function onDragEnd(event: DragEndEvent, pageInfo: PdfPageInfo, pageContainerRef: React.RefObject<HTMLDivElement>) {
  if (!event.over || !pageContainerRef.current) return;
  const containerRect = pageContainerRef.current.getBoundingClientRect();
  // event.delta gives displacement from start; for absolute drop position
  // use the dragged item's final position relative to the drop zone container
  const dropX = event.activatorEvent instanceof MouseEvent
    ? event.activatorEvent.clientX + event.delta.x - containerRect.left
    : 0;
  const dropY = event.activatorEvent instanceof MouseEvent
    ? event.activatorEvent.clientY + event.delta.y - containerRect.top
    : 0;
  const pdfCoords = screenToPdfCoords(dropX, dropY, pageInfo);
  // Persist new field to state / server action
}
```

### Pattern 3: Overlay Rendering (Stored Fields → Visual Position)

**What:** Render stored PDF-space fields back as absolutely-positioned div overlays on top of the `<Page>` canvas.
**When to use:** After loading the document and its stored fields.

```typescript
// Reverse mapping: PDF user-space → screen pixels for rendering
function pdfToScreenCoords(
  pdfX: number,
  pdfY: number,
  pageInfo: PdfPageInfo
): { left: number; top: number } {
  const { width: renderedW, height: renderedH, originalWidth, originalHeight } = pageInfo;
  const left = (pdfX / originalWidth) * renderedW;
  // Reverse Y flip
  const top = renderedH - (pdfY / originalHeight) * renderedH;
  return { left, top };
}

// In JSX (inside the <Page> wrapper div, position: relative):
{fields.map(field => {
  const { left, top } = pdfToScreenCoords(field.x, field.y, pageInfo);
  const widthPx = (field.width / pageInfo.originalWidth) * pageInfo.width;
  const heightPx = (field.height / pageInfo.originalHeight) * pageInfo.height;
  return (
    <div key={field.id} style={{
      position: 'absolute',
      left,
      top: top - heightPx,   // top is y of bottom-left corner; shift up by height
      width: widthPx,
      height: heightPx,
      border: '2px solid #2563eb',
      background: 'rgba(37,99,235,0.1)',
      pointerEvents: 'none',
    }} />
  );
})}
```

### Pattern 4: Server-Side PDF Preparation with pdf-lib

**What:** POST `/api/documents/[id]/prepare` — load the stored PDF, fill AcroForm text fields OR draw text directly, draw signature rectangles, flatten, overwrite the file.
**When to use:** When agent clicks "Prepare & Send" after filling text fields and placing signature fields.

```typescript
// Source: https://pdf-lib.js.org/ and https://github.com/Hopding/pdf-lib
// Uses @cantoo/pdf-lib (drop-in replacement API)
import { PDFDocument, StandardFonts, rgb } from '@cantoo/pdf-lib';
import { readFile, writeFile } from 'node:fs/promises';

export async function preparePdf(filePath: string, fillData: Record<string, string>, signatureFields: SignatureField[]) {
  const pdfBytes = await readFile(filePath);
  const pdfDoc = await PDFDocument.load(pdfBytes);
  const pages = pdfDoc.getPages();
  const helvetica = await pdfDoc.embedFont(StandardFonts.Helvetica);

  // Strategy A: fill existing AcroForm text fields by name
  try {
    const form = pdfDoc.getForm();
    for (const [fieldName, value] of Object.entries(fillData)) {
      try {
        const field = form.getTextField(fieldName);
        field.setText(value);
      } catch {
        // Field name not found — skip silently
      }
    }
    form.flatten();
  } catch {
    // No AcroForm — use Strategy B: draw text at known coordinates
  }

  // Strategy B (fallback or supplement): draw text directly on page
  // Used for custom fields or when no AcroForm exists
  // Coordinates come from Phase 5 UI or hardcoded known positions
  // (Implementation specific to this app's text field schema)

  // Draw signature field placeholders (visible rectangle for client to sign)
  for (const field of signatureFields) {
    const page = pages[field.page - 1]; // 0-indexed
    if (!page) continue;
    page.drawRectangle({
      x: field.x,
      y: field.y,
      width: field.width,
      height: field.height,
      borderColor: rgb(0.15, 0.39, 0.92),  // blue
      borderWidth: 1.5,
      color: rgb(0.85, 0.91, 0.99),        // light blue fill
    });
    page.drawText('Sign Here', {
      x: field.x + 4,
      y: field.y + 4,
      size: 8,
      font: helvetica,
      color: rgb(0.15, 0.39, 0.92),
    });
  }

  const modifiedBytes = await pdfDoc.save();
  await writeFile(filePath, modifiedBytes);
}
```

### Pattern 5: Schema Extension for Field Storage

**What:** Add `signatureFields` JSONB column to the `documents` table.
**When to use:** Migration for Phase 5.

```typescript
// src/lib/db/schema.ts addition
import { jsonb } from 'drizzle-orm/pg-core';

// TypeScript type for stored field
export interface SignatureFieldData {
  id: string;
  page: number;
  x: number;
  y: number;
  width: number;
  height: number;
}

// Add to documents table:
export const documents = pgTable('documents', {
  // ... existing columns ...
  signatureFields: jsonb('signature_fields').$type<SignatureFieldData[]>(),
  assignedClientId: text('assigned_client_id'), // client to send to (may duplicate existing clientId — confirm at planning)
  textFillData: jsonb('text_fill_data').$type<Record<string, string>>(), // { propertyAddress, buyerName, etc. }
});
```

### Anti-Patterns to Avoid

- **Storing screen pixels in the database:** Always convert to PDF user-space before persisting. Screen pixels are resolution/zoom dependent; PDF points are absolute.
- **Assuming `originalHeight = page.view[3]`:** Some PDFs have non-standard mediaBox ordering. Use `Math.max(page.view[1], page.view[3])` for `originalHeight` to handle both orderings.
- **Using `form.flatten()` before adding rectangles:** Flatten removes form fields and ends AcroForm editing. Draw signature rectangles AFTER flattening text fields.
- **Using `pdf-lib` 1.17.1 (Hopding):** Unmaintained for 4 years. Use `@cantoo/pdf-lib` instead — same API, actively maintained.
- **Mutating the original file in place without backup:** The prepare step overwrites the stored PDF. Keep a copy strategy or store the "prepared" variant under a new file path to allow re-editing (discuss at planning).
- **Mixing `width` and `scale` props on `<Page>`:** If both are set, width is multiplied by scale — double scaling. Use only `scale` prop and let the component compute width.
- **Defining `devicePixelRatio` without capping it:** On retina displays, `window.devicePixelRatio` can be 3x, making canvas 9x as many pixels. Cap at `Math.min(2, window.devicePixelRatio)` for performance.

---

## Don't Hand-Roll

| Problem | Don't Build | Use Instead | Why |
|---------|-------------|-------------|-----|
| Drag sensor, keyboard fallback, accessibility | Custom mouse event listeners | `dnd-kit` `useDraggable`/`useDroppable` | WCAG 2.5.7 requires keyboard alternative; dnd-kit provides it |
| PDF byte manipulation, text drawing | Custom PDF writer | `@cantoo/pdf-lib` | PDF spec is 1000+ pages; correct font encoding, content streams, and AcroForm structure require expert implementation |
| Y-axis coordinate flip | Anything other than the formula | The formula: `pdfY = ((renderedH - screenY) / renderedH) * originalHeight` | There is one correct formula; any other approach introduces drift |
| JSONB type safety | Custom serialization | `drizzle-orm/pg-core` `jsonb().$type<T>()` | Already in the stack; provides TypeScript type safety on read |
| PDF rendering to canvas | Custom PDF.js integration | `react-pdf` (already installed) | Already in project; Page component provides `onLoadSuccess` with dimensions |

**Key insight:** The coordinate math is simple (four-line formula) but the failure mode (fields visually misplaced) is catastrophic and silent. Do the math correctly once, unit-test it against real Utah form dimensions (612×792 pts for Letter), and never re-derive it.

---

## Common Pitfalls

### Pitfall 1: Y-Axis Inversion (Silent Correctness Bug)
**What goes wrong:** Signature fields appear in the wrong vertical position. At scale=1 the error is `originalHeight - 2*pdfY` points off — visually wrong but not obviously so until you look carefully.
**Why it happens:** DOM Y increases downward; PDF Y increases upward. Developers forget the flip and store raw screen Y.
**How to avoid:** Unit test the conversion: for a point clicked at the visual top of a US Letter page (screenY ≈ 0), the resulting pdfY should be ≈ 792 (near the top in PDF space). If pdfY ≈ 0, you forgot the flip.
**Warning signs:** Placed fields appear near the bottom of the document when you clicked near the top.

### Pitfall 2: Scale Factor Drift
**What goes wrong:** Fields placed at zoom 1.0 appear slightly offset when the PDF is zoomed to 1.5.
**Why it happens:** If `originalWidth`/`originalHeight` are read at one scale and screen coordinates at another, the ratio is wrong.
**How to avoid:** Always compute `pdfX = (screenX / renderedWidth) * originalWidth` using the CURRENT rendered dimensions from the container's `getBoundingClientRect()` at the moment of the drop event — not stale state from a previous render.
**Warning signs:** Fields appear correct immediately after placement but shift when zooming in/out.

### Pitfall 3: pdf-lib AcroForm Field Name Mismatch
**What goes wrong:** `form.getTextField('PropertyAddress')` throws — the actual field name in the Utah form PDF differs.
**Why it happens:** Utah real estate PDFs from utahrealestate.com often have internal field names like `Text1`, `Text2` rather than semantic names. The field names are not visible in the UI.
**How to avoid:** Enumerate all field names first: `pdfDoc.getForm().getFields().map(f => f.getName())`. Build the fill-data schema around actual names from the specific PDFs. Wrap `getTextField` in a try/catch and log misses.
**Warning signs:** No error, but text fields remain empty in the output PDF.

### Pitfall 4: Mutating the Only Copy of the PDF
**What goes wrong:** If prepare fails mid-way (corrupt PDF output), the original document is lost.
**Why it happens:** `writeFile(filePath, ...)` overwrites in place.
**How to avoid:** Write to a temp path first (`${filePath}.tmp`), verify the output is a valid PDF (check magic bytes `%PDF`), then `rename(tmpPath, filePath)`.
**Warning signs:** Document becomes unopenable after a failed prepare attempt.

### Pitfall 5: `originalHeight = 0` on Some PDFs
**What goes wrong:** `page.view[3]` is 0 for some PDFs with non-standard mediaBox ordering.
**Why it happens:** PDF spec allows specifying `[x1, y1, x2, y2]` where the first pair can be non-zero (e.g., `[0, 792, 612, 0]`).
**How to avoid:** `const originalHeight = Math.max(page.view[1], page.view[3])` and similarly for width.
**Warning signs:** Coordinate calculations produce infinity or 0 division.

### Pitfall 6: `@cantoo/pdf-lib` Import Path
**What goes wrong:** Code that imports from `pdf-lib` may not automatically resolve to the fork.
**Why it happens:** `@cantoo/pdf-lib` is a different package name, not an alias.
**How to avoid:** Install `@cantoo/pdf-lib` and update all imports. Do NOT install both `pdf-lib` and `@cantoo/pdf-lib` — they will conflict.
**Warning signs:** TypeScript reports duplicate default exports or type conflicts.

---

## Code Examples

### Reading Page Dimensions for Coordinate Math
```typescript
// Source: https://github.com/wojtekmaj/react-pdf/blob/main/packages/react-pdf/src/Page.tsx
// and https://github.com/wojtekmaj/react-pdf/discussions/1535
import { Page } from 'react-pdf';

const [pageInfo, setPageInfo] = useState<{
  originalWidth: number;
  originalHeight: number;
  width: number;
  height: number;
  scale: number;
} | null>(null);

<Page
  pageNumber={currentPage}
  scale={scale}
  onLoadSuccess={(page) => {
    setPageInfo({
      // Use Math.max to handle non-standard mediaBox
      originalWidth: Math.max(page.view[0], page.view[2]),
      originalHeight: Math.max(page.view[1], page.view[3]),
      width: page.width,    // rendered px
      height: page.height,  // rendered px
      scale: page.scale,
    });
  }}
/>
```

### Drizzle Schema with JSONB Fields
```typescript
// Source: https://orm.drizzle.team/docs/custom-types
// and https://wanago.io/2024/07/15/api-nestjs-json-drizzle-postgresql/
import { jsonb } from 'drizzle-orm/pg-core';

export interface SignatureFieldData {
  id: string;
  page: number;   // 1-indexed
  x: number;      // PDF user space, bottom-left origin, points
  y: number;      // PDF user space, bottom-left origin, points
  width: number;  // PDF points
  height: number; // PDF points
}

// In pgTable:
signatureFields: jsonb('signature_fields').$type<SignatureFieldData[]>(),
textFillData: jsonb('text_fill_data').$type<Record<string, string>>(),
```

### dnd-kit Draggable Field Token
```typescript
// Source: https://docs.dndkit.com/api-documentation/draggable/drag-overlay
import { useDraggable } from '@dnd-kit/core';
import { CSS } from '@dnd-kit/utilities';

function DraggableSignatureToken() {
  const { attributes, listeners, setNodeRef, transform, isDragging } = useDraggable({
    id: 'signature-field-token',
    data: { type: 'signature', width: 144, height: 36 }, // 2in x 0.5in in points
  });
  return (
    <div
      ref={setNodeRef}
      style={{
        transform: CSS.Translate.toString(transform),
        opacity: isDragging ? 0.5 : 1,
        cursor: 'grab',
      }}
      {...listeners}
      {...attributes}
    >
      Signature Field
    </div>
  );
}
```

### pdf-lib: Fill Text and Draw Signature Rectangle
```typescript
// Source: https://pdf-lib.js.org/ (using @cantoo/pdf-lib — drop-in replacement)
import { PDFDocument, StandardFonts, rgb } from '@cantoo/pdf-lib';

async function fillDocumentFields(
  pdfBytes: Uint8Array,
  textFields: Record<string, string>,
  sigFields: Array<{ page: number; x: number; y: number; width: number; height: number }>
): Promise<Uint8Array> {
  const pdfDoc = await PDFDocument.load(pdfBytes);
  const helvetica = await pdfDoc.embedFont(StandardFonts.Helvetica);
  const pages = pdfDoc.getPages();

  // Fill AcroForm fields if they exist
  try {
    const form = pdfDoc.getForm();
    for (const [name, value] of Object.entries(textFields)) {
      try { form.getTextField(name).setText(value); } catch { /* field not found */ }
    }
    form.flatten(); // Must happen BEFORE drawing rectangles
  } catch { /* No AcroForm — ignore */ }

  // Draw signature placeholders
  for (const field of sigFields) {
    const page = pages[field.page - 1];
    if (!page) continue;
    page.drawRectangle({
      x: field.x,
      y: field.y,
      width: field.width,
      height: field.height,
      borderColor: rgb(0.15, 0.39, 0.92),
      borderWidth: 1.5,
      color: rgb(0.90, 0.94, 0.99),
    });
    page.drawText('Sign Here', {
      x: field.x + 4,
      y: field.y + 4,
      size: 8,
      font: helvetica,
      color: rgb(0.15, 0.39, 0.92),
    });
  }

  return await pdfDoc.save();
}
```

---

## State of the Art

| Old Approach | Current Approach | When Changed | Impact |
|--------------|------------------|--------------|--------|
| `pdf-lib` 1.17.1 (Hopding) | `@cantoo/pdf-lib` 2.6.1 | Original abandoned ~2022 | Drop-in replacement; use fork to get bug fixes |
| Manual CDN worker URL for pdf.js | `new URL('pdfjs-dist/build/pdf.worker.min.mjs', import.meta.url)` | pdf.js v4+ / react-pdf v9+ | Already in project; no CDN required |
| `react-pdf` CommonJS | react-pdf v10 ESM-only | June 2024 (v10.0.0) | Already in project; `transpilePackages` in next.config.ts handles this |
| `useFormState` (React DOM) | `useActionState` (React 19) | React 19 / Next.js 15+ | Already established in project (STATE.md decision) |

**Deprecated/outdated:**
- `pdf-lib` direct import: Unmaintained; replace with `@cantoo/pdf-lib`
- CDN pdf.js worker URL: Already replaced in project with `import.meta.url` pattern
- Storing screen-pixel coordinates in database: Must always convert to PDF user space before persist

---

## Open Questions

1. **Prepared PDF file path strategy**
   - What we know: Currently documents are stored at `uploads/clients/{clientId}/{docId}.pdf`
   - What's unclear: Should Phase 5 overwrite the original (lossy — can't re-edit) or write to a separate `_prepared.pdf` path (preserves original for re-editing)?
   - Recommendation: Write to a new path `uploads/clients/{clientId}/{docId}_prepared.pdf` and store it in a new `preparedFilePath` column — keeps the original editable. Decide at planning.

2. **Text field schema — agent input form**
   - What we know: DOC-05 requires filling in "property address, client names, dates, prices"
   - What's unclear: Are these always the same fields across all Utah forms, or variable per form template?
   - Recommendation: Build a generic key/value text fill form (agent types field labels and values). Store as `textFillData JSONB`. Phase 5 does not need to pre-define field names — agent provides them.

3. **AcroForm field names in Utah forms**
   - What we know: Utah real estate PDFs from utahrealestate.com may or may not have named AcroForm fields
   - What's unclear: Phase 4 loaded them but never inspected AcroForm structure
   - Recommendation: Add an enumeration step: `GET /api/documents/[id]/fields` that reads the PDF and returns discovered AcroForm field names. Agent uses this to map their fill data. Fall back to `drawText` at hardcoded positions if no AcroForm.

4. **DOC-06 "initiate a signing request" scope boundary**
   - What we know: DOC-06 says "assign to a client and initiate signing request"
   - What's unclear: Does "initiate" mean setting status to "Sent" + calling the email API (Phase 6 work), or just status transition + persisting data?
   - Recommendation: Phase 5 ends at: prepared PDF is saved, `signatureFields` and `textFillData` are persisted, document `status` transitions from `Draft` to `Sent` (or a new `Prepared` status). Actual email sending is Phase 6. Clarify the status enum at planning.

---

## Sources

### Primary (HIGH confidence)
- `react-pdf` GitHub (wojtekmaj/react-pdf) — `Page.onLoadSuccess`, `originalWidth`/`originalHeight`, v10 breaking changes
- `pdf-lib.js.org` official docs — `PDFDocument.load`, `drawText`, `drawRectangle`, `getForm().flatten()`
- `docs.dndkit.com` — `useDraggable`, `useDroppable`, `DragEndEvent`, `CSS.Translate.toString`
- `orm.drizzle.team/docs/custom-types` — `jsonb().$type<T>()` API

### Secondary (MEDIUM confidence)
- npmjs.com/package/@cantoo/pdf-lib — confirmed v2.6.1, published 18 days ago, active maintenance
- github.com/Hopding/pdf-lib/issues/1423 — confirmed abandonment of original pdf-lib
- pdfscripting.com/public/PDF-Page-Coordinates.cfm — PDF user space coordinate specification
- github.com/wojtekmaj/react-pdf/discussions/1632 — scaling issue on custom canvas over react-pdf page

### Tertiary (LOW confidence — needs validation)
- Final absolute drop position calculation via `event.delta` in dnd-kit `onDragEnd` — community patterns, verify against actual dnd-kit behavior during implementation
- `@cantoo/pdf-lib` full API parity with original pdf-lib — stated drop-in but specific edge cases not verified

---

## Metadata

**Confidence breakdown:**
- Standard stack: HIGH — confirmed by official docs and npm registry
- Architecture: HIGH — derived from project conventions (STATE.md) and verified library APIs
- Coordinate math: HIGH — PDF spec is authoritative; formula verified from multiple official sources
- Pitfalls: MEDIUM-HIGH — most verified from official GitHub issues and docs; drop position calculation is MEDIUM (community patterns)

**Research date:** 2026-03-19
**Valid until:** 2026-04-19 (pdf-lib fork is active; dnd-kit is stable; react-pdf is stable)