docs(phase-12): complete phase execution

.planning/REQUIREMENTS.md

@@ -92,7 +92,7 @@
 
 ### Document Preview
 
-- [ ] **PREV-01**: Agent sees a live filled preview of the fully-prepared document (text filled, signatures embedded) before sending to client
+- [x] **PREV-01**: Agent sees a live filled preview of the fully-prepared document (text filled, signatures embedded) before sending to client
 
 ## v2 Requirements
 
@@ -188,7 +188,7 @@ Which phases cover which requirements. Updated during roadmap creation.
 | INIT-02 | Phase 11.1 | Complete |
 | INIT-03 | Phase 11.1 | Complete |
 | INIT-04 | Phase 11.1 | Complete |
-| PREV-01 | Phase 12 | Pending |
+| PREV-01 | Phase 12 | Complete |
 | AI-01 | Phase 13 | Pending |
 | AI-02 | Phase 13 | Pending |
 

.planning/ROADMAP.md

@@ -259,7 +259,7 @@ Plans:
 
 Plans:
 - [ ] 12-01-PLAN.md — POST /api/documents/[id]/preview route (reuses preparePdf in preview mode, versioned path, staleness token), PreviewModal component with react-pdf rendering + ArrayBuffer copy
-- [ ] 12-02-PLAN.md — Send button gating logic (disabled until preview generated, re-disabled on field change) + full Phase 12 human verification checkpoint
+- [x] 12-02-PLAN.md — Send button gating logic (disabled until preview generated, re-disabled on field change) + full Phase 12 human verification checkpoint (completed 2026-03-21)
 
 ### Phase 13: AI Field Placement and Pre-fill
 **Goal**: Agent clicks one button and AI auto-places all field types on the PDF in correct positions and pre-fills text fields with known client and property data
@@ -297,5 +297,5 @@ Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 →
 | 10. Expanded Field Types End-to-End | v1.1 | 3/3 | Complete | 2026-03-21 |
 | 11. Agent Saved Signature and Signing Workflow | 3/3 | Complete    | 2026-03-21 | - |
 | 11.1. Agent and Client Initials (INSERTED) | 3/3 | Complete    | 2026-03-21 | - |
-| 12. Filled Document Preview | 2/2 | Complete   | 2026-03-21 | - |
+| 12. Filled Document Preview | 2/2 | Complete    | 2026-03-21 | - |
 | 13. AI Field Placement and Pre-fill | v1.1 | 0/4 | Not started | - |

.planning/STATE.md

@@ -3,7 +3,7 @@ gsd_state_version: 1.0
 milestone: v1.1
 milestone_name: Smart Document Preparation
 status: unknown
-last_updated: "2026-03-21T21:55:00Z"
+last_updated: "2026-03-21T22:01:55.827Z"
 progress:
   total_phases: 13
   completed_phases: 13

.planning/phases/12-filled-document-preview/12-VERIFICATION.md

@@ -0,0 +1,113 @@
+---
+phase: 12-filled-document-preview
+verified: 2026-03-21T22:00:00Z
+status: human_needed
+score: 4/4 must-haves verified
+re_verification: false
+human_verification:
+  - test: "Preview-gate-Send flow end-to-end"
+    expected: "Preview button opens a modal showing the fully-prepared PDF with embedded content; Send button is disabled before preview; Send re-enables after preview; text/field changes re-disable Send; no _preview_*.pdf lingers in uploads/ after preview"
+    why_human: "Visual/runtime behavior — modal rendering, PDF content accuracy, button state transitions, and file cleanup cannot be confirmed by static code analysis alone. The SUMMARY records human approval was obtained during Plan 02 execution, but this verification independently flags for confirmation."
+---
+
+# Phase 12: Filled Document Preview Verification Report
+
+**Phase Goal:** Agent sees a live filled preview of the fully-prepared document — with all text, signatures, and field stamps embedded — before the Send button becomes available
+**Verified:** 2026-03-21T22:00:00Z
+**Status:** human_needed (all automated checks pass; one human confirmation item noted)
+**Re-verification:** No — initial verification
+
+## Goal Achievement
+
+### Observable Truths (from ROADMAP Success Criteria)
+
+| # | Truth | Status | Evidence |
+|---|-------|--------|----------|
+| 1 | A "Preview" button is available on the document prepare page and opens a modal showing the fully-prepared PDF rendered with all embedded content | VERIFIED | `PreparePanel.tsx` line 196: `<button onClick={handlePreview} ...>` renders before Send; `handlePreview` calls `/api/documents/${docId}/preview`, stores ArrayBuffer in `previewBytes`, and sets `showPreview=true`; `PreviewModal` renders at line 219–221 with `file={pdfBytes}` passed to react-pdf `<Document>` |
+| 2 | The Send button is disabled until the agent has generated at least one preview of the current field state | VERIFIED | `PreparePanel.tsx` line 206: `disabled={loading \|\| previewToken === null \|\| parseEmails(recipients).length === 0}` — `previewToken` starts as `null` (lifted to `DocumentPageClient.tsx` line 25: `useState<string \| null>(null)`); only set to a non-null value at line 109 after a successful preview fetch |
+| 3 | If the agent changes any fields after previewing, the Send button is re-disabled until a fresh preview is generated (staleness detection) | VERIFIED | Two reset paths confirmed: (a) text fill change: `handleTextFillChange` in `PreparePanel.tsx` line 94 calls `onPreviewTokenChange(null)`; (b) field mutation: `FieldPlacer.tsx` calls `onFieldsChanged?.()` after all 4 `persistFields` invocations (lines 298, 482, 549, 660); `DocumentPageClient.tsx` `handleFieldsChanged` (line 27–29) calls `setPreviewToken(null)`, threading back through `PdfViewerWrapper` → `PdfViewer` → `FieldPlacer` |
+| 4 | The preview PDF uses a versioned path and does not overwrite the final prepared PDF (legal integrity of prepared document is preserved) | VERIFIED | `preview/route.ts` line 28: `doc.filePath.replace(/\.pdf$/, \`_preview_${Date.now()}.pdf\`)` — versioned timestamp suffix; `try/finally` at lines 65–72 calls `unlink(previewPath).catch(() => {})` ensuring temp file is deleted; route never writes to `_prepared.pdf` and makes no DB status updates |
+
+**Score:** 4/4 truths verified
+
+### Required Artifacts
+
+| Artifact | Expected | Status | Details |
+|----------|----------|--------|---------|
+| `src/app/api/documents/[id]/preview/route.ts` | POST route — generates preview PDF and returns bytes | VERIFIED | 73 lines; exports `POST`; auth-guarded; versioned temp path; mirrors 422 guards; `preparePdf` called in `try`; `readFile` returns bytes; `unlink` in `finally` |
+| `src/app/portal/(protected)/documents/[docId]/_components/PreviewModal.tsx` | Modal component rendering PDF from ArrayBuffer | VERIFIED | 92 lines; `'use client'`; accepts `{ pdfBytes: ArrayBuffer; onClose: () => void }`; configures `pdfjs.GlobalWorkerOptions.workerSrc` independently; `createPortal` to `document.body`; scroll-lock `useEffect`; `<Document file={pdfBytes}>` with Prev/Next/Close navigation |
+| `src/app/portal/(protected)/documents/[docId]/_components/PreparePanel.tsx` | Preview button, previewToken state, Send button gating, PreviewModal render | VERIFIED | `previewToken` and `onPreviewTokenChange` as props from `DocumentPageClient`; `handlePreview` fetch function; Preview button; Send button gated on `previewToken === null`; `handleTextFillChange` wrapper resets token; `PreviewModal` rendered conditionally |
+| `src/app/portal/(protected)/documents/[docId]/_components/FieldPlacer.tsx` | `onFieldsChanged` callback prop fired after every `persistFields` call | VERIFIED | `onFieldsChanged?: () => void` in `FieldPlacerProps` (line 158); called at lines 298 (drag-drop new field), 482 (move pointerup), 549 (resize pointerup), 660 (delete button) — all 4 mutation sites covered |
+| `src/app/portal/(protected)/documents/[docId]/_components/DocumentPageClient.tsx` | Client state bridge holding `previewToken`, forwarding `handleFieldsChanged` | VERIFIED | Created; holds `previewToken` state; `handleFieldsChanged` resets it to `null`; passes `onFieldsChanged={handleFieldsChanged}` to `PdfViewerWrapper` and `previewToken`/`onPreviewTokenChange` to `PreparePanel` |
+
+### Key Link Verification
+
+| From | To | Via | Status | Details |
+|------|----|-----|--------|---------|
+| `preview/route.ts` | `prepare-document.ts` | `import preparePdf` / `preparePdf(srcPath, previewPath, ...)` | WIRED | Line 6 import; line 66 call with all required params |
+| `PreviewModal.tsx` | `react-pdf Document` | `file={pdfBytes}` ArrayBuffer prop | WIRED | Line 81–84: `<Document file={pdfBytes} onLoadSuccess={...}>` |
+| `PreparePanel.tsx` | `PreviewModal.tsx` | `import { PreviewModal }` + conditional render | WIRED | Line 5 import; lines 219–221 conditional render on `showPreview && previewBytes` |
+| `PreparePanel.tsx` | `/api/documents/[id]/preview` | `fetch POST` in `handlePreview` | WIRED | Lines 101–105: `fetch(\`/api/documents/${docId}/preview\`, { method: 'POST', ... })` with `textFillData` in body |
+| `FieldPlacer.tsx` | `PreparePanel.tsx` (via `DocumentPageClient`) | `onFieldsChanged?.()` → `handleFieldsChanged` → `setPreviewToken(null)` | WIRED | Full chain: `FieldPlacer.onFieldsChanged` → `PdfViewer.onFieldsChanged` (line 72) → `PdfViewerWrapper.onFieldsChanged` (line 7) → `DocumentPageClient.handleFieldsChanged` (line 34) → `setPreviewToken(null)` |
+| `page.tsx` | `DocumentPageClient.tsx` | replaces old `PreparePanel+PdfViewerWrapper` siblings | WIRED | `page.tsx` line 7 imports `DocumentPageClient`; line 55–63 renders it with all required props |
+
+### Requirements Coverage
+
+| Requirement | Source Plan | Description | Status | Evidence |
+|-------------|------------|-------------|--------|----------|
+| PREV-01 | 12-01-PLAN.md, 12-02-PLAN.md | Agent sees a live filled preview of the fully-prepared document (text filled, signatures embedded) before sending to client | SATISFIED | All 4 ROADMAP success criteria verified above; preview API route generates a real `preparePdf` output (not a stub); modal renders it with react-pdf; Send button is gated on token; token resets on any field or text fill change |
+
+**Orphaned requirements:** None — REQUIREMENTS.md maps PREV-01 exclusively to Phase 12 and both plans claim it.
+
+### Anti-Patterns Found
+
+| File | Line | Pattern | Severity | Impact |
+|------|------|---------|----------|--------|
+| `PreparePanel.tsx` | 180 | `placeholder="email@example.com"` | Info | HTML textarea attribute — not a code stub; no impact |
+
+No blockers, no stubs, no TODO/FIXME/return null patterns found across all phase 12 files.
+
+### TypeScript Compilation
+
+```
+cd /Users/ccopeland/temp/red/teressa-copeland-homes && npx tsc --noEmit
+```
+
+**Result: Zero TypeScript errors project-wide.**
+
+### Human Verification Required
+
+#### 1. Preview-gate-Send flow end-to-end
+
+**Test:** Open a Draft document in the portal that has at least one field placed. Verify:
+1. "Prepare and Send" button is disabled/grayed out before Preview is clicked
+2. Click "Preview" — loading state appears briefly
+3. PreviewModal opens showing the PDF with embedded content (text fills at field positions, agent signature/initials if placed, placeholder outlines for client fields)
+4. Prev/Next navigation works across pages
+5. Close modal — "Prepare and Send" button is now enabled
+6. Change a text fill value — "Prepare and Send" goes back to disabled
+7. Click Preview again — modal shows updated content
+8. Drag/move/delete a placed field — "Prepare and Send" goes back to disabled
+9. Click Preview again — button re-enables
+10. Click "Prepare and Send" — signing email is sent normally
+11. After preview completes, no `_preview_*.pdf` files remain in `uploads/`
+
+**Expected:** All 11 steps pass
+
+**Why human:** Modal rendering, PDF content accuracy, button state visual feedback, and file cleanup behavior cannot be confirmed by static code analysis. The SUMMARY records that Task 3 human verification was obtained and "approved" during Plan 02 execution on 2026-03-21, which is the primary record of human sign-off.
+
+### Gaps Summary
+
+No gaps. All four ROADMAP success criteria are fully implemented and wired:
+
+1. The preview API route exists, is auth-guarded, generates a real preparePdf output (not a stub), and cleans up the temp file in try/finally.
+2. The PreviewModal is substantive — it has scroll lock, portal rendering, independent pdfjs worker config, and actual react-pdf Document/Page rendering from ArrayBuffer.
+3. PreparePanel has the Preview button, the gated Send button (`previewToken === null`), and resets the token on text fill changes.
+4. The full staleness detection chain is wired: field mutations in FieldPlacer call `onFieldsChanged?.()`, which threads through PdfViewer → PdfViewerWrapper → DocumentPageClient → `setPreviewToken(null)`.
+
+The one acknowledged gap (text fill UX redesign — per-field click-to-edit and quick-fill suggestions) is deferred to Phase 12.1 per plan decision. Current implementation draws fill values at placed field coordinates, which satisfies PREV-01. This gap is not a blocker for phase completion.
+
+---
+
+_Verified: 2026-03-21T22:00:00Z_
+_Verifier: Claude (gsd-verifier)_