---
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*