docs(19-01): complete template editor infrastructure plan

.planning/STATE.md

@@ -2,14 +2,14 @@
 gsd_state_version: 1.0
 milestone: v1.1
 milestone_name: Smart Document Preparation
-status: verifying
+status: executing
-stopped_at: Completed 18-02-PLAN.md — template CRUD API routes (GET, POST, PATCH, DELETE)
+stopped_at: Phase 19 plans verified and ready for execution
-last_updated: "2026-04-06T18:18:26.395Z"
+last_updated: "2026-04-06T19:06:35.220Z"
-last_activity: 2026-04-06
+last_activity: 2026-04-06 -- Phase 19 execution started
 progress:
-  total_phases: 20
+  total_phases: 21
   completed_phases: 19
-  total_plans: 60
+  total_plans: 63
   completed_plans: 59
   percent: 82
 ---
@@ -24,10 +24,10 @@ See: .planning/PROJECT.md (updated 2026-04-03)
 
 ## Current Position
 
-Phase: 18 (template-schema-and-crud-api) — EXECUTING
+Phase: 19 (template-editor-ui) — EXECUTING
-Plan: 2 of 2
+Plan: 1 of 3
-Status: Phase complete — ready for verification
+Status: Executing Phase 19
-Last activity: 2026-04-06
+Last activity: 2026-04-06 -- Phase 19 execution started
 
 ## Note on v1.1
 
@@ -230,6 +230,6 @@ None yet.
 
 ## Session Continuity
 
-Last session: 2026-04-06T18:18:26.391Z
+Last session: 2026-04-06T18:54:04.529Z
-Stopped at: Completed 18-02-PLAN.md — template CRUD API routes (GET, POST, PATCH, DELETE)
+Stopped at: Phase 19 plans verified and ready for execution
-Resume file: None
+Resume file: .planning/phases/19-template-editor-ui/19-01-PLAN.md

.planning/phases/19-template-editor-ui/19-01-SUMMARY.md

@@ -0,0 +1,81 @@
+---
+phase: 19-template-editor-ui
+plan: "01"
+subsystem: template-editor
+tags: [template, field-placer, api-routes, portal-nav]
+dependency_graph:
+  requires: [18-02]
+  provides: [template-mode props on FieldPlacer/PdfViewer/PdfViewerWrapper, three template API routes, Templates nav link]
+  affects: [FieldPlacer, PdfViewer, PdfViewerWrapper, PortalNav, /api/templates/[id]/]
+tech_stack:
+  added: []
+  patterns: [optional-prop-threading, seeds-forms-streaming, soft-delete-filter]
+key_files:
+  created:
+    - teressa-copeland-homes/src/app/api/templates/[id]/file/route.ts
+    - teressa-copeland-homes/src/app/api/templates/[id]/fields/route.ts
+    - teressa-copeland-homes/src/app/api/templates/[id]/ai-prepare/route.ts
+  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/_components/PortalNav.tsx
+decisions:
+  - "onPersist callback threads through FieldPlacer/PdfViewer/PdfViewerWrapper as optional prop — existing document callers pass no prop and behavior is unchanged"
+  - "fieldsUrl and fileUrl override default document API endpoints — enables template editor to redirect both field load and PDF source without forking components"
+  - "ai-prepare for templates passes null client context to classifyFieldsWithAI — templates have no pre-fill data by design (D-15)"
+  - "All three template routes use isNull(archivedAt) soft-delete filter consistent with Phase 18 pattern"
+metrics:
+  duration_minutes: 8
+  completed_date: "2026-04-06"
+  tasks_completed: 2
+  files_changed: 7
+---
+
+# Phase 19 Plan 01: Template Editor Infrastructure Summary
+
+Infrastructure additions that wire the FieldPlacer/PdfViewer component chain for template-mode operation: optional `onPersist`, `fieldsUrl`, and `fileUrl` props added non-breakingly, three new template API routes created, and Templates nav link added.
+
+## Tasks Completed
+
+### Task 1: Add onPersist + fieldsUrl props to FieldPlacer, fileUrl to PdfViewer/PdfViewerWrapper, and Templates to PortalNav
+
+- Added `onPersist?: (fields: SignatureFieldData[]) => Promise<void> | void` and `fieldsUrl?: string` to `FieldPlacerProps` interface
+- All 4 `persistFields` call sites (drag-drop, move, resize, delete) conditionally use `onPersist` when provided, falling back to `persistFields(docId, next)` otherwise
+- `loadFields` useEffect uses `fieldsUrl ?? /api/documents/${docId}/fields`; `fieldsUrl` added to dependency array
+- `PdfViewer` and `PdfViewerWrapper` accept and pass through all three new props; both `file` src and download `href` use `fileUrl ?? /api/documents/${docId}/file`
+- `PortalNav` navLinks array updated with `{ href: "/portal/templates", label: "Templates" }` between Clients and Profile
+- Commit: 57efd91
+
+### Task 2: Create three template API routes — file, fields, ai-prepare
+
+- `GET /api/templates/[id]/file` — loads `documentTemplates` with `formTemplate` relation, resolves path in `seeds/forms/`, path traversal guard, streams PDF with `Content-Type: application/pdf`
+- `GET /api/templates/[id]/fields` — returns `template.signatureFields ?? []`
+- `POST /api/templates/[id]/ai-prepare` — runs `extractBlanks` + `classifyFieldsWithAI(blanks, null)`, writes `signatureFields` + explicit `updatedAt: new Date()` to DB, returns `{ fields }`
+- All three routes: auth guard + `isNull(documentTemplates.archivedAt)` soft-delete filter
+- Commit: 275565c
+
+## Verification
+
+- `npx tsc --noEmit` — 0 errors after each task
+- `npm run build` — succeeds; all three new route paths appear in build output
+- All 7 grep checks passed (onPersist x4 sites, fieldsUrl, fileUrl x2, /portal/templates)
+
+## Deviations from Plan
+
+None — plan executed exactly as written.
+
+## Known Stubs
+
+None — all new routes are fully functional. Field loading and persisting have real implementations.
+
+## Self-Check: PASSED
+
+Files created:
+- /Users/ccopeland/temp/red/teressa-copeland-homes/src/app/api/templates/[id]/file/route.ts — FOUND
+- /Users/ccopeland/temp/red/teressa-copeland-homes/src/app/api/templates/[id]/fields/route.ts — FOUND
+- /Users/ccopeland/temp/red/teressa-copeland-homes/src/app/api/templates/[id]/ai-prepare/route.ts — FOUND
+
+Commits:
+- 57efd91 — feat(19-01): add onPersist, fieldsUrl, fileUrl props and Templates nav link
+- 275565c — feat(19-01): create template API routes — file, fields, ai-prepare