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

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