docs(06-03): complete signing page plan — SUMMARY, STATE, ROADMAP updated

- 06-03-SUMMARY.md created with decisions, deviations, file list - STATE.md advanced to Plan 3 complete; two new decisions recorded - ROADMAP.md phase 6 updated to 3/6 summaries complete
2026-03-20 11:32:40 -06:00
parent 90bd066016
commit a3026fb44f
4 changed files with 155 additions and 10 deletions
--- a/.planning/REQUIREMENTS.md
+++ b/.planning/REQUIREMENTS.md
@@ -44,7 +44,7 @@

 - [x] **SIGN-01**: Client receives an email with a unique link to sign the document (no account required)
 - [x] **SIGN-02**: Signing link expires after 72 hours and can only be used once
- [ ] **SIGN-03**: Client opens the link in any browser and sees the prepared PDF with signature fields highlighted
+- [x] **SIGN-03**: Client opens the link in any browser and sees the prepared PDF with signature fields highlighted
 - [ ] **SIGN-04**: Client can draw a freehand signature on a canvas (works on mobile and desktop)
 - [ ] **SIGN-05**: Client can save a default signature and click a signature field to apply it without redrawing
 - [ ] **SIGN-06**: Client sees a confirmation screen after successfully signing
@@ -127,7 +127,7 @@ Which phases cover which requirements. Updated during roadmap creation.
 | DOC-06 | Phase 5 | Complete |
 | SIGN-01 | Phase 6 | Complete |
 | SIGN-02 | Phase 6 | Complete |
-| SIGN-03 | Phase 6 | Pending |
+| SIGN-03 | Phase 6 | Complete |
 | SIGN-04 | Phase 6 | Pending |
 | SIGN-05 | Phase 6 | Pending |
 | SIGN-06 | Phase 6 | Pending |
--- a/.planning/ROADMAP.md
+++ b/.planning/ROADMAP.md
@@ -153,5 +153,5 @@ Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 → 7
 | 3. Agent Portal Shell | 4/4 | Complete   | 2026-03-19 |
 | 4. PDF Ingest | 4/4 | Complete   | 2026-03-20 |
 | 5. PDF Fill and Field Mapping | 3/4 | In Progress|  |
-| 6. Signing Flow | 2/6 | In Progress|  |
+| 6. Signing Flow | 3/6 | In Progress|  |
 | 7. Audit Trail and Download | 0/? | Not started | - |
--- a/.planning/STATE.md
+++ b/.planning/STATE.md
@@ -3,12 +3,12 @@ gsd_state_version: 1.0
 milestone: v1.0
 milestone_name: milestone
 status: unknown
-last_updated: "2026-03-20T17:30:55.130Z"
+last_updated: "2026-03-20T17:32:09.418Z"
 progress:
  total_phases: 6
  completed_phases: 5
  total_plans: 24
-  completed_plans: 20
+  completed_plans: 21
 ---

 # Project State
@@ -22,10 +22,10 @@ See: .planning/PROJECT.md (updated 2026-03-19)

 ## Current Position

-Phase: 6 of 7 (Signing Flow) — Plan 2 complete
-Plan: 06-02 (2 of 5 plans) — email delivery layer, signing request email, send API route
-Status: SigningRequestEmail.tsx + signing-mailer.tsx created, POST /api/documents/[id]/send live, document_prepared audit log wired in prepare route, npm run build passes cleanly.
-Last activity: 2026-03-20 — Phase 6 Plan 02: email delivery layer (React Email + nodemailer + send route)
+Phase: 6 of 7 (Signing Flow) — Plan 3 complete
+Plan: 06-03 (3 of 5 plans) — public signing page, PDF viewer, field overlays, audit route
+Status: /sign/[token] public route with server-side token validation (expired/used/pending states), react-pdf full-scroll PDF viewer with pulsing blue field overlays, sticky progress bar, GET /api/sign/[token] audit route, GET /api/sign/[token]/pdf streaming route — npm run build passes cleanly.
+Last activity: 2026-03-20 — Phase 6 Plan 03: signing page (server component + PDF viewer + progress bar)

 Progress: [████████░░] 87%

@@ -60,6 +60,7 @@ Progress: [████████░░] 87%
 | Phase 05-pdf-fill-and-field-mapping P03 | 3 | 2 tasks | 4 files |
 | Phase 06-signing-flow P01 | 2 | 2 tasks | 8 files |
 | Phase 06-signing-flow P02 | 2 | 2 tasks | 4 files |
+| Phase 06-signing-flow P03 | 3 | 2 tasks | 6 files |

 ## Accumulated Context

@@ -125,6 +126,8 @@ Recent decisions affecting current work:
 - [Phase 06-signing-flow]: Sender address hardcoded as teressa@teressacopelandhomes.com — matches brand identity requirement in CONTEXT.md
 - [Phase 06-signing-flow]: sendMail failure triggers 502 without DB status update — document stays in current state if email delivery fails
 - [Phase 06-signing-flow]: Status update in send/route.ts guarded by status=Draft — prevents downgrading Sent/Signed documents
+- [Phase 06-signing-flow]: SigningPageClientWrapper uses dynamic import (ssr:false) — react-pdf requires browser APIs that cannot run server-side
+- [Phase 06-signing-flow]: PDF served via /api/sign/[token]/pdf (token-authenticated) not /api/documents/[id]/file (agent-authenticated) — signing page is public

 ### Pending Todos

@@ -141,5 +144,5 @@ None yet.
 ## Session Continuity

 Last session: 2026-03-20
-Stopped at: Completed 06-02-PLAN.md — branded email component, signing mailer, send API route, document_prepared audit logging
+Stopped at: Completed 06-03-PLAN.md — signing page, PDF viewer, field overlays, progress bar, audit route
 Resume file: None
--- a/.planning/phases/06-signing-flow/06-03-SUMMARY.md
+++ b/.planning/phases/06-signing-flow/06-03-SUMMARY.md
@@ -0,0 +1,142 @@
+---
+phase: 06-signing-flow
+plan: "03"
+subsystem: ui
+tags: [react-pdf, pdfjs, signing, jwt, audit, overlay, animation, next-app-router]
+
+# Dependency graph
+requires:
+  - phase: 06-signing-flow/06-01
+    provides: verifySigningToken(), logAuditEvent(), signingTokens table, SignatureFieldData schema
+
+provides:
+  - /sign/[token] public route with three states (expired/used/pending)
+  - Server component token validation before any UI renders
+  - SigningPageClient: full-scroll react-pdf viewer + pulsing blue field overlays + sticky progress bar
+  - SigningProgressBar: sticky bottom bar with X/Y count + jump-to-next + submit button
+  - GET /api/sign/[token]: token validation data route + audit event logging
+  - GET /api/sign/[token]/pdf: token-authenticated PDF streaming route
+
+affects: [06-04, 06-05]
+
+# Tech tracking
+tech-stack:
+  added: []
+  patterns:
+    - react-pdf used with dynamic import (ssr:false) via SigningPageClientWrapper — prevents SSR crashes from browser-only canvas/worker APIs
+    - PDF coordinate conversion: screenTop = renderedH - (field.y * scaleY) - (field.height * scaleY); origin flip from PDF bottom-left to screen top-left
+    - CSS keyframes injected via <style> tag inside client component for pulse-border animation
+    - Token-authenticated PDF serving via /api/sign/[token]/pdf — no agent auth, signed token grants file access
+    - Path traversal guard on PDF file serving (checks for .. in stored relative path)
+
+key-files:
+  created:
+    - teressa-copeland-homes/src/app/api/sign/[token]/route.ts
+    - teressa-copeland-homes/src/app/api/sign/[token]/pdf/route.ts
+    - teressa-copeland-homes/src/app/sign/[token]/page.tsx
+    - teressa-copeland-homes/src/app/sign/[token]/_components/SigningPageClient.tsx
+    - teressa-copeland-homes/src/app/sign/[token]/_components/SigningPageClientWrapper.tsx
+    - teressa-copeland-homes/src/app/sign/[token]/_components/SigningProgressBar.tsx
+  modified: []
+
+key-decisions:
+  - "SigningPageClientWrapper uses dynamic import (ssr:false) — react-pdf uses browser APIs (canvas, pdfjs worker) that cannot run server-side"
+  - "PDF served via /api/sign/[token]/pdf (token-authenticated) not /api/documents/[id]/file (agent-authenticated) — signing page is public, agent route requires session"
+  - "ErrorPage function defined in page.tsx for inline use — no separate file needed, three small JSX blocks"
+  - "onFieldClick prop is a no-op stub in this plan — modal capture wired in Plan 04"
+
+patterns-established:
+  - "Signing page validates token at server component level before rendering any client component — no canvas flash on expired/used/invalid tokens"
+  - "PDF coordinate conversion: pdfY (bottom-left origin) -> screenTop = renderedH - pdfY*scaleY - fieldH*scaleY"
+  - "Token-authenticated file routes use verifySigningToken() with no usedAt check — viewing is idempotent, submission check is separate"
+
+requirements-completed: [SIGN-02, SIGN-03, LEGAL-01]
+
+# Metrics
+duration: 3min
+completed: 2026-03-20
+---
+
+# Phase 6 Plan 03: Signing Page Summary
+
+**Public /sign/[token] route with server-side token enforcement (expired/used/pending states), react-pdf full-scroll viewer, pulsing blue signature field overlays, and sticky progress bar**
+
+## Performance
+
+- **Duration:** 3 min
+- **Started:** 2026-03-20T17:28:18Z
+- **Completed:** 2026-03-20T17:30:54Z
+- **Tasks:** 2
+- **Files modified:** 6
+
+## Accomplishments
+
+- Server component validates JWT + one-time-use before rendering any signing UI — no canvas flash on invalid tokens
+- GET /api/sign/[token] returns expired/used/pending JSON with link_opened + document_viewed audit events logged
+- Full-scroll react-pdf viewer with absolutely-positioned pulsing blue overlay divs on each signature field
+- Sticky progress bar shows "X of Y signatures complete" with jump-to-next scroll and submit button
+- GET /api/sign/[token]/pdf streams prepared PDF authenticated by signing token (no agent session required)
+- npm run build passes cleanly with /sign/[token], /api/sign/[token], /api/sign/[token]/pdf all visible as dynamic routes
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: GET /api/sign/[token] route — token validation + audit logging** - `e1306da` (feat)
+2. **Task 2: Signing page server component + client PDF viewer + progress bar** - `dcf503d` (feat)
+
+**Plan metadata:** (docs commit — see below)
+
+## Files Created/Modified
+
+- `teressa-copeland-homes/src/app/api/sign/[token]/route.ts` - Public GET route: validates JWT, checks one-time-use, logs audit events, returns expired/used/pending JSON
+- `teressa-copeland-homes/src/app/api/sign/[token]/pdf/route.ts` - Token-authenticated PDF streaming route; path traversal guard on stored relative path
+- `teressa-copeland-homes/src/app/sign/[token]/page.tsx` - Server component: validates token + DB lookups before rendering any client UI; inline ErrorPage for three error states
+- `teressa-copeland-homes/src/app/sign/[token]/_components/SigningPageClient.tsx` - Client PDF viewer: react-pdf Document+Page all pages, pulsing overlay divs, coordinate conversion, signaturesRef for Plan 04
+- `teressa-copeland-homes/src/app/sign/[token]/_components/SigningPageClientWrapper.tsx` - Dynamic import wrapper (ssr:false) for react-pdf browser requirement
+- `teressa-copeland-homes/src/app/sign/[token]/_components/SigningProgressBar.tsx` - Sticky progress bar with jump-to-next and submit button
+
+## Decisions Made
+
+- `SigningPageClientWrapper` created with `dynamic(..., { ssr: false })` — react-pdf requires browser APIs (HTMLCanvasElement, pdfjs worker). Direct import from server component would crash at SSR time.
+- PDF file served via `/api/sign/[token]/pdf` rather than the existing `/api/documents/[id]/file` — the existing file route requires an authenticated agent session; the signing page is intentionally public and authenticates via the signing token.
+- `onFieldClick` is a no-op stub in this plan. Plan 04 will wire up the signature modal and populate `signaturesRef`.
+- `ErrorPage` inlined in `page.tsx` — three simple JSX blocks, not worth a separate file.
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 2 - Missing Critical] Added SigningPageClientWrapper for SSR-safe dynamic import**
+- **Found during:** Task 2 (server component + PDF viewer)
+- **Issue:** `SigningPageClient` uses `pdfjs.GlobalWorkerOptions.workerSrc = new URL(import.meta.url)` and react-pdf canvas APIs — these cannot run in Next.js SSR. Directly importing the client component from the server page.tsx would throw at build/render time.
+- **Fix:** Created `SigningPageClientWrapper.tsx` as a `'use client'` component that wraps `SigningPageClient` in `next/dynamic(..., { ssr: false })`. `page.tsx` imports the wrapper instead.
+- **Files modified:** `SigningPageClientWrapper.tsx` (new), `page.tsx` (imports wrapper not client directly)
+- **Verification:** `npm run build` passes, no SSR errors
+- **Committed in:** `dcf503d` (Task 2 commit)
+
+---
+
+**Total deviations:** 1 auto-fixed (Rule 2 — missing critical SSR guard)
+**Impact on plan:** Necessary for correctness — react-pdf cannot render server-side. The wrapper is a thin file with no behavior change. No scope creep.
+
+## Issues Encountered
+
+None.
+
+## User Setup Required
+
+None — no external service configuration required for this plan.
+
+## Next Phase Readiness
+
+Phase 6 signing page is visually complete and compiles cleanly:
+- /sign/[token] renders correct error states (expired/used/invalid) server-side before any JS runs
+- Valid tokens render the branded header, full-scroll PDF viewer, pulsing field overlays, and sticky progress bar
+- GET /api/sign/[token] logs audit events; GET /api/sign/[token]/pdf streams the prepared PDF
+- Plan 04 can import `SigningPageClient` and wire up `onFieldClick` + the signature modal + submission POST
+- Plan 04 can populate `signaturesRef.current` with captured signatures and call `setSignedFields`
+
+---
+*Phase: 06-signing-flow*
+*Completed: 2026-03-20*