docs(12.1-02): complete state bridge plan; awaiting human-verify checkpoint

- Create 12.1-02-SUMMARY.md: selectedFieldId + textFillData state lifting; QuickFillPanel replacing TextFillForm
- Update STATE.md: position at checkpoint Task 3 (human verification); 3 new decisions logged
- Update ROADMAP.md: phase 12.1 progress (2/2 SUMMARYs)
- Mark TXTF-02 complete in REQUIREMENTS.md

.planning/REQUIREMENTS.md

@@ -97,7 +97,7 @@
 ### Per-Field Text Editing
 
 - [x] **TXTF-01**: Agent can click a placed text field box on the PDF to select it and type a value for that specific field — each text field holds its own independent value (keyed by field ID)
-- [ ] **TXTF-02**: When a text field is selected, PreparePanel shows quick-fill suggestion buttons (Client Name, Property Address, Client Email) that insert the corresponding value into the selected field
+- [x] **TXTF-02**: When a text field is selected, PreparePanel shows quick-fill suggestion buttons (Client Name, Property Address, Client Email) that insert the corresponding value into the selected field
 - [x] **TXTF-03**: Text fill values entered per-field appear correctly embedded in the preview PDF and the final prepared PDF; the staleness token resets on any text field value change
 
 ## v2 Requirements
@@ -196,7 +196,7 @@ Which phases cover which requirements. Updated during roadmap creation.
 | INIT-04 | Phase 11.1 | Complete |
 | PREV-01 | Phase 12 | Complete |
 | TXTF-01 | Phase 12.1 | Complete |
-| TXTF-02 | Phase 12.1 | Pending |
+| TXTF-02 | Phase 12.1 | Complete |
 | TXTF-03 | Phase 12.1 | Complete |
 | AI-01 | Phase 13 | Pending |
 | AI-02 | Phase 13 | Pending |

.planning/ROADMAP.md

@@ -164,7 +164,7 @@ Plans:
 - [x] **Phase 11: Agent Saved Signature and Signing Workflow** - Draw once, save, apply to agent signature fields during document preparation before sending to client (completed 2026-03-21)
 - [x] **Phase 11.1: Agent and Client Initials (INSERTED)** - Agent draws initials once, saves to profile, places agent-initials fields (embedded at prepare time); client-initials fields already wired via existing 'initials' type (completed 2026-03-21)
 - [x] **Phase 12: Filled Document Preview** - Agent sees a live filled preview of the fully-prepared document before the Send button is available (completed 2026-03-21)
-- [ ] **Phase 12.1: Per-Field Text Editing and Quick-Fill (INSERTED)** - Agent clicks a text field box to edit its value inline; PreparePanel shows quick-fill suggestions (client name, address, etc.) when a field is selected; text fill data is keyed by field ID
+- [x] **Phase 12.1: Per-Field Text Editing and Quick-Fill (INSERTED)** - Agent clicks a text field box to edit its value inline; PreparePanel shows quick-fill suggestions (client name, address, etc.) when a field is selected; text fill data is keyed by field ID (completed 2026-03-21)
 - [ ] **Phase 13: AI Field Placement and Pre-fill** - One-click AI auto-placement of all field types plus pre-fill of text fields from client profile data
 
 ## Phase Details
@@ -315,5 +315,5 @@ Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 →
 | 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.1. Per-Field Text Editing and Quick-Fill (INSERTED) | 1/2 | In Progress|  | - |
+| 12.1. Per-Field Text Editing and Quick-Fill (INSERTED) | 2/2 | Complete   | 2026-03-21 | - |
 | 13. AI Field Placement and Pre-fill | v1.1 | 0/4 | Not started | - |

.planning/STATE.md

@@ -23,9 +23,9 @@ See: .planning/PROJECT.md (updated 2026-03-21)
 ## Current Position
 
 Phase: 12.1 (Per-Field Text Editing and Quick Fill)
-Plan: 1 of 2 in phase 12.1 — COMPLETE
+Plan: 2 of 2 in phase 12.1 — AWAITING HUMAN VERIFICATION (checkpoint Task 3)
-Status: Phase 12.1 Plan 01 complete — field-ID-keyed text fill in preparePdf; click-to-select inline input in FieldPlacer; prop chain PdfViewerWrapper->PdfViewer->FieldPlacer ready for Plan 02 wiring
+Status: Phase 12.1 Plan 02 automated tasks complete — selectedFieldId + textFillData lifted to DocumentPageClient; QuickFillPanel in PreparePanel; TextFillForm deleted; awaiting human browser verification of full per-field text editing and quick-fill flow
-Last activity: 2026-03-21 — Phase 12.1 Plan 01 complete: Strategy A/B removed from preparePdf; UUID-keyed text drawing; optional text-edit props threaded through component chain; click-to-select inline input interaction in FieldPlacer.
+Last activity: 2026-03-21 — Phase 12.1 Plan 02: state bridge wired in DocumentPageClient; TextFillForm replaced with QuickFillPanel; handleFieldValueChange and handleQuickFill both reset previewToken; zero TSC errors.
 
 ## Accumulated Context
 
@@ -61,6 +61,7 @@ Progress: [█████████████] 100% (13/13 phases complete)
 | Phase 12-filled-document-preview P01 | 5 | 2 tasks | 2 files |
 | Phase 12-filled-document-preview P02 | 25 | 3 tasks (2 auto + 1 human-verify) | 8 files |
 | 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 |
 
 ## Accumulated Context
 
@@ -113,6 +114,9 @@ Recent decisions affecting v1.1 work:
 - [Phase Phase 12.1-01]: preparePdf text fill is now keyed by SignatureFieldData.id (UUID) — direct lookup replaces positional sort; AcroForm Strategy A and Strategy B top-of-page fallback both removed
 - [Phase Phase 12.1-01]: FieldPlacer click-to-select uses onClick (fires only on no-drag clicks due to MouseSensor distance:5 threshold) — onPointerDown move handler is preserved and unaffected
 - [Phase Phase 12.1-01]: data-no-move attribute on the inline input onPointerDown stops move handler activation — consistent with existing delete button and resize handle pattern
+- [Phase 12.1-02]: textFillData starts as {} in DocumentPageClient — NOT seeded from clientPropertyAddress; old label-keyed seeding ({ propertyAddress: clientPropertyAddress }) is removed; quick-fill makes it trivial to insert the value once a field is selected
+- [Phase 12.1-02]: handleFieldValueChange and handleQuickFill are separate useCallback functions that both call setPreviewToken(null) — satisfies TXTF-03 staleness reset on every text change
+- [Phase 12.1-02]: defaultEmail reused for Client Email quick-fill button — already a PreparePanel prop (used for recipients pre-fill); no new prop needed (per research Pitfall 3)
 
 ### Pending Todos
 
@@ -126,5 +130,5 @@ None yet.
 ## Session Continuity
 
 Last session: 2026-03-21
-Stopped at: Completed 12.1-per-field-text-editing-and-quick-fill/12.1-01-PLAN.md (Phase 12.1 Plan 01 complete — UUID-keyed text fill, click-to-select inline input, prop chain ready)
+Stopped at: Checkpoint Task 3 in 12.1-per-field-text-editing-and-quick-fill/12.1-02-PLAN.md — awaiting human browser verification of per-field text editing and quick-fill end-to-end flow
 Resume file: None

.planning/phases/12.1-per-field-text-editing-and-quick-fill/12.1-02-SUMMARY.md

@@ -0,0 +1,101 @@
+---
+phase: 12.1-per-field-text-editing-and-quick-fill
+plan: 02
+subsystem: document-editor, state-management
+tags: [text-fill, quick-fill, state-lifting, ux, react]
+dependency_graph:
+  requires:
+    - 12.1-01 (prop chain PdfViewerWrapper->PdfViewer->FieldPlacer, click-to-select inline input)
+  provides:
+    - selectedFieldId + textFillData shared state in DocumentPageClient
+    - QuickFillPanel in PreparePanel sidebar (Client Name / Property Address / Client Email)
+    - previewToken staleness reset on every text value change
+  affects:
+    - teressa-copeland-homes/src/app/portal/(protected)/documents/[docId]/_components/DocumentPageClient.tsx
+    - teressa-copeland-homes/src/app/portal/(protected)/documents/[docId]/_components/PreparePanel.tsx
+    - teressa-copeland-homes/src/app/portal/(protected)/documents/[docId]/_components/TextFillForm.tsx (deleted)
+tech_stack:
+  added: []
+  patterns:
+    - state-lifting (selectedFieldId + textFillData lifted to DocumentPageClient for cross-component sync)
+    - callback prop pattern (handleFieldValueChange and handleQuickFill passed down as props)
+    - conditional sidebar panel (QuickFillPanel only visible when selectedFieldId non-null)
+key_files:
+  created: []
+  modified:
+    - teressa-copeland-homes/src/app/portal/(protected)/documents/[docId]/_components/DocumentPageClient.tsx
+    - teressa-copeland-homes/src/app/portal/(protected)/documents/[docId]/_components/PreparePanel.tsx
+  deleted:
+    - teressa-copeland-homes/src/app/portal/(protected)/documents/[docId]/_components/TextFillForm.tsx
+decisions:
+  - "[Phase 12.1-02]: textFillData starts as {} in DocumentPageClient — NOT seeded from clientPropertyAddress; old label-keyed seeding ({ propertyAddress: clientPropertyAddress }) is removed; quick-fill makes it trivial to insert the value once a field is selected"
+  - "[Phase 12.1-02]: handleFieldValueChange and handleQuickFill are separate useCallback functions that both call setPreviewToken(null) — satisfies TXTF-03 staleness reset on every text change"
+  - "[Phase 12.1-02]: defaultEmail reused for Client Email quick-fill button — already a PreparePanel prop (used for recipients pre-fill); no new prop needed (per research Pitfall 3)"
+metrics:
+  duration_minutes: 5
+  completed_date: "2026-03-21"
+  tasks_completed: 2
+  files_modified: 2
+  files_deleted: 1
+---
+
+# Phase 12.1 Plan 02: Per-Field Text Editing State Bridge Summary
+
+**One-liner:** selectedFieldId and textFillData lifted to DocumentPageClient; TextFillForm replaced with QuickFillPanel (Client Name / Property Address / Client Email) in PreparePanel; previewToken staleness reset wired to both text-change callbacks.
+
+## Tasks Completed
+
+| # | Task | Commit | Files |
+|---|------|--------|-------|
+| 1 | Extend DocumentPageClient with selectedFieldId + textFillData shared state | f395819 | DocumentPageClient.tsx |
+| 2 | Replace TextFillForm with QuickFillPanel in PreparePanel; delete TextFillForm.tsx | d2ebb2c | PreparePanel.tsx, TextFillForm.tsx (deleted) |
+
+## What Was Built
+
+### Task 1: DocumentPageClient shared state bridge
+
+Extended `DocumentPageClient.tsx` from 51 lines to 71 lines:
+
+- **Added** `selectedFieldId` state (`useState<string | null>(null)`) — tracks which text field box is currently selected
+- **Added** `textFillData` state (`useState<Record<string, string>>({})`) — UUID-keyed map of text values; starts empty (no legacy label seeding)
+- **Added** `handleFieldValueChange(fieldId, value)` callback — updates textFillData and resets previewToken to null (TXTF-03)
+- **Added** `handleQuickFill(fieldId, value)` callback — same as handleFieldValueChange but semantically separate for quick-fill button clicks
+- **Passed** all 4 new props to `PdfViewerWrapper`: `selectedFieldId`, `textFillData`, `onFieldSelect={setSelectedFieldId}`, `onFieldValueChange={handleFieldValueChange}`
+- **Passed** 3 new props to `PreparePanel`: `textFillData`, `selectedFieldId`, `onQuickFill={handleQuickFill}`
+
+### Task 2: PreparePanel QuickFillPanel + TextFillForm deletion
+
+Overhauled `PreparePanel.tsx`:
+
+- **Removed** `textFillData` local state (seeded with `{ propertyAddress: clientPropertyAddress }` — label-keyed broken pattern)
+- **Removed** `handleTextFillChange` function
+- **Removed** `TextFillForm` import and JSX block
+- **Added** 3 new props to `PreparePanelProps`: `textFillData: Record<string, string>`, `selectedFieldId: string | null`, `onQuickFill: (fieldId: string, value: string) => void`
+- **Added** QuickFillPanel JSX: conditionally renders when `selectedFieldId` is non-null — shows Client Name, Property Address (if set), and Client Email quick-fill buttons; idle state shows "Click a text field on the document to edit or quick-fill it."
+- **Updated** `handlePreview` and `handlePrepare` — both now use `textFillData` from props (not local state); JSON body unchanged
+- **Deleted** `TextFillForm.tsx` — generic label/value row form no longer used anywhere
+
+## Deviations from Plan
+
+None — plan executed exactly as written.
+
+## Verification
+
+- `npx tsc --noEmit` passes with zero errors
+- No import or reference to `TextFillForm` anywhere in the codebase
+- `PreparePanel` has `textFillData`, `selectedFieldId`, `onQuickFill` in props interface
+- `DocumentPageClient` has `selectedFieldId` and `textFillData` state variables
+- Both `handleFieldValueChange` and `handleQuickFill` call `setPreviewToken(null)`
+- `handlePreview` and `handlePrepare` use `textFillData` from props
+
+## Checkpoint: Awaiting Human Verification
+
+Task 3 is a `checkpoint:human-verify` gate. The automated work is complete. Human browser verification of the full per-field text editing and quick-fill flow is required before this plan can be marked complete.
+
+## Self-Check: PASSED
+
+- [x] `DocumentPageClient.tsx` exists and modified — contains `selectedFieldId`, `textFillData`, `handleFieldValueChange`, `handleQuickFill`
+- [x] `PreparePanel.tsx` exists and modified — contains `onQuickFill`, `selectedFieldId`, `textFillData` props; no TextFillForm
+- [x] `TextFillForm.tsx` deleted — file does not exist
+- [x] Commit f395819 exists (Task 1)
+- [x] Commit d2ebb2c exists (Task 2)