docs(13-03): complete AI Auto-place UI wire-up plan — violet button, aiPlacementKey, handleAiAutoPlace

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.planning/ROADMAP.md

@@ -316,4 +316,4 @@ Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 →
 | 11.1. Agent and Client Initials (INSERTED) | 3/3 | Complete    | 2026-03-21 | - |
 | 12. Filled Document Preview | 2/2 | Complete    | 2026-03-21 | - |
 | 12.1. Per-Field Text Editing and Quick-Fill (INSERTED) | 2/2 | Complete    | 2026-03-21 | - |
-| 13. AI Field Placement and Pre-fill | 2/4 | In Progress|  | - |
+| 13. AI Field Placement and Pre-fill | 3/4 | In Progress|  | - |

.planning/STATE.md

@@ -3,12 +3,12 @@ gsd_state_version: 1.0
 milestone: v1.1
 milestone_name: Smart Document Preparation
 status: unknown
-last_updated: "2026-03-21T23:05:00Z"
+last_updated: "2026-03-21T23:09:27.022Z"
 progress:
   total_phases: 15
   completed_phases: 14
   total_plans: 48
-  completed_plans: 46
+  completed_plans: 47
 ---
 
 # Project State
@@ -23,9 +23,9 @@ See: .planning/PROJECT.md (updated 2026-03-21)
 ## Current Position
 
 Phase: 13 (AI Field Placement and Pre-fill) — IN PROGRESS
-Plan: 2 of 4 complete — Plans 01-02 done; Plans 03-04 remaining
+Plan: 3 of 4 complete — Plans 01-03 done; Plan 04 remaining
-Status: Phase 13 Plan 02 complete — POST /api/documents/[id]/ai-prepare route implemented with full guard chain and AI pipeline orchestration; TypeScript compiles clean; ready for Plan 03 (UI button)
+Status: Phase 13 Plan 03 complete — AI Auto-place button wired into PreparePanel; aiPlacementKey threaded through PdfViewerWrapper to FieldPlacer; handleAiAutoPlace in DocumentPageClient; TypeScript compiles clean; ready for Plan 04 (E2E verification)
-Last activity: 2026-03-21 — Phase 13 Plan 02: ai-prepare route handler implemented, writes AI-placed fields to DB, status stays Draft.
+Last activity: 2026-03-21 — Phase 13 Plan 03: AI Auto-place UI button and client-side orchestration implemented.
 
 ## Accumulated Context
 
@@ -63,6 +63,7 @@ Progress: [█████████████] 100% (13/13 phases complete)
 | Phase 12.1-per-field-text-editing-and-quick-fill P01 | 3 | 2 tasks | 4 files |
 | Phase 12.1-per-field-text-editing-and-quick-fill P02 | 5 | 2 auto tasks + 1 human-verify checkpoint | 2 files modified + 1 deleted |
 | Phase 13-ai-field-placement-and-pre-fill P01 | 2 | 2 tasks | 5 files |
+| Phase 13-ai-field-placement-and-pre-fill P03 | 2 | 2 tasks | 5 files |
 
 ## Accumulated Context
 
@@ -127,6 +128,9 @@ Recent decisions affecting v1.1 work:
 - [Phase 13-02]: try/catch wraps extractPdfText + classifyFieldsWithAI together — single error boundary returns 500 with error message string
 - [Phase 13-02]: ai-prepare route does NOT change document status — stays Draft so agent can review and adjust AI-placed fields before prepare/send
 - [Phase 13-02]: Path traversal guard placed before AI calls — fail fast without expensive PDF extraction on invalid paths
+- [Phase 13-03]: aiPlacementKey integer incremented via setAiPlacementKey(k => k + 1) — functional update prevents stale closure issues
+- [Phase 13-03]: textFillData is MERGED not replaced — preserves manually typed values while AI values take precedence
+- [Phase 13-03]: AI button uses violet bg-violet-600 to visually distinguish from gray Preview and blue Prepare-and-Send
 
 ### Pending Todos
 
@@ -140,5 +144,5 @@ None yet.
 ## Session Continuity
 
 Last session: 2026-03-21
-Stopped at: Completed 13-ai-field-placement-and-pre-fill/13-02-PLAN.md — ai-prepare route implemented; Plan 02 of 4 done; ready for Plan 03 (UI button)
+Stopped at: Completed 13-ai-field-placement-and-pre-fill/13-03-PLAN.md — AI Auto-place button wired; Plan 03 of 4 done; ready for Plan 04 (E2E verification)
 Resume file: None

.planning/phases/13-ai-field-placement-and-pre-fill/13-03-SUMMARY.md

@@ -0,0 +1,116 @@
+---
+phase: 13-ai-field-placement-and-pre-fill
+plan: "03"
+subsystem: ui
+tags: [react, nextjs, typescript, ai, field-placement]
+
+# Dependency graph
+requires:
+  - phase: 13-01
+    provides: AI field placement utilities (aiCoordsToPagePdfSpace, classifyFieldsWithAI, extractPdfText)
+  - phase: 13-02
+    provides: POST /api/documents/[id]/ai-prepare route that writes AI-placed fields to DB and returns textFillData
+
+provides:
+  - "AI Auto-place Fields" violet button in PreparePanel for Draft documents
+  - aiPlacementKey prop on FieldPlacer that triggers loadFields re-fetch when incremented
+  - aiPlacementKey threaded through PdfViewerWrapper and PdfViewer
+  - handleAiAutoPlace in DocumentPageClient that calls ai-prepare route, merges textFillData, increments key, resets preview
+affects:
+  - 13-04
+
+# Tech tracking
+tech-stack:
+  added: []
+  patterns:
+    - aiPlacementKey integer state as a cache-busting trigger for FieldPlacer re-fetch
+    - Merge pattern for AI textFillData (AI values take precedence over existing manual values)
+    - Callback-prop pattern for async operations from child to parent (onAiAutoPlace)
+
+key-files:
+  created: []
+  modified:
+    - teressa-copeland-homes/src/app/portal/(protected)/documents/[docId]/_components/FieldPlacer.tsx
+    - teressa-copeland-homes/src/app/portal/(protected)/documents/[docId]/_components/PdfViewer.tsx
+    - teressa-copeland-homes/src/app/portal/(protected)/documents/[docId]/_components/PdfViewerWrapper.tsx
+    - teressa-copeland-homes/src/app/portal/(protected)/documents/[docId]/_components/PreparePanel.tsx
+    - teressa-copeland-homes/src/app/portal/(protected)/documents/[docId]/_components/DocumentPageClient.tsx
+
+key-decisions:
+  - "aiPlacementKey integer incremented via setAiPlacementKey(k => k + 1) — functional update prevents stale closure issues"
+  - "textFillData is MERGED not replaced — {...prev, ...aiTextFill} preserves manually typed values while AI values take precedence"
+  - "previewToken reset to null after AI placement — agent must re-preview after AI changes fields"
+  - "AI button uses violet (#7c3aed / bg-violet-600) to visually distinguish from gray Preview and blue Prepare-and-Send"
+  - "Error from ai-prepare route is thrown in handleAiAutoPlace and caught by PreparePanel's handleAiAutoPlaceClick — surfaced via existing result state"
+
+patterns-established:
+  - "aiPlacementKey pattern: integer state in parent (DocumentPageClient), threaded as prop down through PdfViewerWrapper -> PdfViewer -> FieldPlacer, added to useEffect dependency array for re-fetch"
+
+requirements-completed: [AI-01, AI-02]
+
+# Metrics
+duration: 2min
+completed: 2026-03-21
+---
+
+# Phase 13 Plan 03: AI Field Placement UI Wire-up Summary
+
+**Violet "AI Auto-place Fields" button in PreparePanel triggers POST /api/documents/[id]/ai-prepare, merges pre-fill data, and re-fetches DB fields via aiPlacementKey cache-busting prop threaded through PdfViewerWrapper to FieldPlacer**
+
+## Performance
+
+- **Duration:** 2 min
+- **Started:** 2026-03-21T23:06:18Z
+- **Completed:** 2026-03-21T23:08:27Z
+- **Tasks:** 2
+- **Files modified:** 5
+
+## Accomplishments
+- FieldPlacer accepts `aiPlacementKey` prop and includes it in the loadFields useEffect dependency array, triggering a re-fetch whenever AI places fields
+- PdfViewer and PdfViewerWrapper thread `aiPlacementKey` through the component chain from DocumentPageClient to FieldPlacer
+- PreparePanel has "AI Auto-place Fields" violet button with dedicated aiLoading state, error display via existing result state, and disabled during any loading
+- DocumentPageClient orchestrates handleAiAutoPlace: calls ai-prepare route, merges AI pre-fills into textFillData, increments aiPlacementKey, resets previewToken
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: Add aiPlacementKey prop to FieldPlacer and thread through PdfViewerWrapper** - `3e11eef` (feat)
+2. **Task 2: Add AI Auto-place button to PreparePanel and wire DocumentPageClient handler** - `bfdaee1` (feat)
+
+**Plan metadata:** (docs commit — see below)
+
+## Files Created/Modified
+- `teressa-copeland-homes/src/app/portal/(protected)/documents/[docId]/_components/FieldPlacer.tsx` - Added aiPlacementKey prop, added to loadFields useEffect deps
+- `teressa-copeland-homes/src/app/portal/(protected)/documents/[docId]/_components/PdfViewer.tsx` - Added aiPlacementKey prop, passes to FieldPlacer
+- `teressa-copeland-homes/src/app/portal/(protected)/documents/[docId]/_components/PdfViewerWrapper.tsx` - Added aiPlacementKey prop, passes to PdfViewer
+- `teressa-copeland-homes/src/app/portal/(protected)/documents/[docId]/_components/PreparePanel.tsx` - Added onAiAutoPlace prop, aiLoading state, handleAiAutoPlaceClick, violet AI button above Preview
+- `teressa-copeland-homes/src/app/portal/(protected)/documents/[docId]/_components/DocumentPageClient.tsx` - Added aiPlacementKey state, handleAiAutoPlace callback, wired both to PdfViewerWrapper and PreparePanel
+
+## Decisions Made
+- aiPlacementKey uses functional update `setAiPlacementKey(k => k + 1)` to avoid stale closure issues
+- textFillData merges via `{...prev, ...aiTextFill}` — AI values take precedence; manual edits for other fields are preserved
+- AI button is violet (#7c3aed / bg-violet-600) to visually distinguish from gray Preview button and blue Prepare-and-Send
+- Error thrown by handleAiAutoPlace is caught in PreparePanel's handleAiAutoPlaceClick and displayed via the existing `result` state
+
+## Deviations from Plan
+
+None - plan executed exactly as written.
+
+## Issues Encountered
+
+None.
+
+## User Setup Required
+
+None - no external service configuration required.
+
+## Next Phase Readiness
+
+- All client-side AI wiring complete: button, loading state, error display, field re-fetch, textFillData merge, preview reset
+- Phase 13 Plan 04 (E2E human verification) is ready — agent can now test the full AI placement flow in the browser
+- Existing functionality unchanged: drag-and-drop, click-to-edit, quick-fill, preview, prepare-and-send all unaffected
+
+---
+*Phase: 13-ai-field-placement-and-pre-fill*
+*Completed: 2026-03-21*