red/.planning/phases/16-multi-signer-ui/16-01-PLAN.md

---
phase: 16-multi-signer-ui
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
  - teressa-copeland-homes/src/app/portal/(protected)/documents/[docId]/page.tsx
  - teressa-copeland-homes/src/app/portal/(protected)/documents/[docId]/_components/DocumentPageClient.tsx
  - teressa-copeland-homes/src/app/portal/(protected)/documents/[docId]/_components/PdfViewerWrapper.tsx
autonomous: true
requirements: [MSIGN-01, MSIGN-02, MSIGN-03]

must_haves:
  truths:
    - "DocumentPageClient holds signers state and threads it to both PreparePanel and PdfViewerWrapper/FieldPlacer"
    - "DocumentPageClient holds unassignedFieldIds state for send-block validation highlighting"
    - "Server page reads documents.signers from DB and passes to DocumentPageClient as initialSigners prop"
    - "PdfViewerWrapper passes signers and unassignedFieldIds through to FieldPlacer"
  artifacts:
    - path: "teressa-copeland-homes/src/app/portal/(protected)/documents/[docId]/_components/DocumentPageClient.tsx"
      provides: "signers state, setSigners, unassignedFieldIds state, setUnassignedFieldIds — threaded to PreparePanel and PdfViewerWrapper"
      exports: ["DocumentPageClient"]
    - path: "teressa-copeland-homes/src/app/portal/(protected)/documents/[docId]/page.tsx"
      provides: "Server-side documents.signers fetch, passed as initialSigners to DocumentPageClient"
    - path: "teressa-copeland-homes/src/app/portal/(protected)/documents/[docId]/_components/PdfViewerWrapper.tsx"
      provides: "Passes signers and unassignedFieldIds props through to PdfViewer/FieldPlacer"
  key_links:
    - from: "page.tsx"
      to: "DocumentPageClient"
      via: "initialSigners prop from db.query.documents"
      pattern: "initialSigners=.*doc\\.signers"
    - from: "DocumentPageClient"
      to: "PdfViewerWrapper"
      via: "signers and unassignedFieldIds props"
      pattern: "signers=.*unassignedFieldIds="
    - from: "DocumentPageClient"
      to: "PreparePanel"
      via: "signers, onSignersChange, unassignedFieldIds, onUnassignedFieldIdsChange props"
      pattern: "signers=.*onSignersChange="
---

<objective>
Thread multi-signer state through the component tree so PreparePanel and FieldPlacer can consume signers data in Wave 2.

Purpose: Foundation wiring — DocumentPageClient is the state owner for signers (from Phase 14 schema) and unassignedFieldIds (for send-block validation). Without this, Wave 2 plans cannot receive or modify signer state.

Output: Updated DocumentPageClient with signers + unassignedFieldIds state; server page fetching documents.signers; PdfViewerWrapper passing new props through.
</objective>

<execution_context>
@$HOME/.claude/get-shit-done/workflows/execute-plan.md
@$HOME/.claude/get-shit-done/templates/summary.md
</execution_context>

<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@.planning/phases/16-multi-signer-ui/16-CONTEXT.md
@.planning/phases/16-multi-signer-ui/16-UI-SPEC.md

<interfaces>
<!-- Key types and contracts the executor needs. Extracted from codebase. -->

From src/lib/db/schema.ts:
```typescript
export interface DocumentSigner {
  email: string;
  color: string;
}

export interface SignatureFieldData {
  id: string;
  page: number;
  x: number;
  y: number;
  width: number;
  height: number;
  type?: SignatureFieldType;
  signerEmail?: string;
}

export function isClientVisibleField(field: SignatureFieldData): boolean;
export function getFieldType(field: SignatureFieldData): SignatureFieldType;
export function getSignerEmail(field: SignatureFieldData, fallbackEmail: string): string;
```

From DocumentPageClient.tsx (current props):
```typescript
interface DocumentPageClientProps {
  docId: string;
  docStatus: string;
  defaultEmail: string;
  clientName: string;
  agentDownloadUrl?: string | null;
  signedAt?: Date | null;
  clientPropertyAddress?: string | null;
}
```

From PdfViewerWrapper.tsx (current props):
```typescript
{
  docId: string;
  docStatus?: string;
  onFieldsChanged?: () => void;
  selectedFieldId?: string | null;
  textFillData?: Record<string, string>;
  onFieldSelect?: (fieldId: string | null) => void;
  onFieldValueChange?: (fieldId: string, value: string) => void;
  aiPlacementKey?: number;
}
```

From FieldPlacer.tsx (current props — FieldPlacerProps interface at line 155):
```typescript
interface FieldPlacerProps {
  docId: string;
  pageInfo: PageInfo | null;
  currentPage: number;
  children: React.ReactNode;
  readOnly?: boolean;
  onFieldsChanged?: () => void;
  selectedFieldId?: string | null;
  textFillData?: Record<string, string>;
  onFieldSelect?: (fieldId: string | null) => void;
  onFieldValueChange?: (fieldId: string, value: string) => void;
  aiPlacementKey?: number;
}
```

From PreparePanel.tsx (current props):
```typescript
interface PreparePanelProps {
  docId: string;
  defaultEmail: string;
  clientName: string;
  currentStatus: string;
  agentDownloadUrl?: string | null;
  signedAt?: Date | null;
  clientPropertyAddress?: string | null;
  previewToken: string | null;
  onPreviewTokenChange: (token: string | null) => void;
  textFillData: Record<string, string>;
  selectedFieldId: string | null;
  onQuickFill: (fieldId: string, value: string) => void;
  onAiAutoPlace: () => Promise<void>;
}
```

From server page.tsx:
```typescript
// doc fetched via db.query.documents.findFirst — has all document columns including signers
const doc = await db.query.documents.findFirst({ where: eq(documents.id, docId) });
// doc.signers is DocumentSigner[] | null (JSONB column from Phase 14)
```
</interfaces>
</context>

<tasks>

<task type="auto">
  <name>Task 1: Add signers prop to server page and thread state through DocumentPageClient</name>
  <read_first>
    - teressa-copeland-homes/src/app/portal/(protected)/documents/[docId]/page.tsx
    - teressa-copeland-homes/src/app/portal/(protected)/documents/[docId]/_components/DocumentPageClient.tsx
    - teressa-copeland-homes/src/lib/db/schema.ts (for DocumentSigner interface)
    - .planning/phases/16-multi-signer-ui/16-CONTEXT.md
    - .planning/phases/16-multi-signer-ui/16-UI-SPEC.md
  </read_first>
  <files>
    teressa-copeland-homes/src/app/portal/(protected)/documents/[docId]/page.tsx,
    teressa-copeland-homes/src/app/portal/(protected)/documents/[docId]/_components/DocumentPageClient.tsx
  </files>
  <action>
    **server page.tsx:**
    - `doc` is already fetched via `db.query.documents.findFirst` which returns all columns including `signers`. Pass `doc.signers` to DocumentPageClient as `initialSigners`:
      ```
      initialSigners={doc.signers ?? []}
      ```

    **DocumentPageClient.tsx:**
    - Import `DocumentSigner` from `@/lib/db/schema`
    - Add `initialSigners: DocumentSigner[]` to `DocumentPageClientProps`
    - Add state: `const [signers, setSigners] = useState<DocumentSigner[]>(initialSigners);`
    - Add state: `const [unassignedFieldIds, setUnassignedFieldIds] = useState<Set<string>>(new Set());`
    - Pass to PreparePanel: `signers={signers}`, `onSignersChange={setSigners}`, `unassignedFieldIds={unassignedFieldIds}`, `onUnassignedFieldIdsChange={setUnassignedFieldIds}`
    - Pass to PdfViewerWrapper: `signers={signers}`, `unassignedFieldIds={unassignedFieldIds}`
    - No other changes to existing props or callbacks
  </action>
  <verify>
    <automated>cd /Users/ccopeland/temp/red/teressa-copeland-homes && npx tsc --noEmit 2>&1 | head -30</automated>
  </verify>
  <acceptance_criteria>
    - `grep -n "initialSigners" teressa-copeland-homes/src/app/portal/(protected)/documents/[docId]/page.tsx` shows prop being passed
    - `grep -n "DocumentSigner" teressa-copeland-homes/src/app/portal/(protected)/documents/[docId]/_components/DocumentPageClient.tsx` shows import
    - `grep -n "signers={signers}" teressa-copeland-homes/src/app/portal/(protected)/documents/[docId]/_components/DocumentPageClient.tsx` shows props threaded to both PreparePanel and PdfViewerWrapper
    - `grep -n "unassignedFieldIds" teressa-copeland-homes/src/app/portal/(protected)/documents/[docId]/_components/DocumentPageClient.tsx` shows state and prop threading
    - `npx tsc --noEmit` passes
  </acceptance_criteria>
  <done>DocumentPageClient has signers + unassignedFieldIds state initialized from server; props threaded to PreparePanel and PdfViewerWrapper; TypeScript compiles cleanly</done>
</task>

<task type="auto">
  <name>Task 2: Thread signers and unassignedFieldIds through PdfViewerWrapper to FieldPlacer</name>
  <read_first>
    - teressa-copeland-homes/src/app/portal/(protected)/documents/[docId]/_components/PdfViewerWrapper.tsx
    - teressa-copeland-homes/src/app/portal/(protected)/documents/[docId]/_components/PdfViewer.tsx (to understand its prop interface — it wraps FieldPlacer)
    - teressa-copeland-homes/src/app/portal/(protected)/documents/[docId]/_components/FieldPlacer.tsx (lines 155-167 for FieldPlacerProps)
    - teressa-copeland-homes/src/lib/db/schema.ts (for DocumentSigner type)
    - .planning/phases/16-multi-signer-ui/16-UI-SPEC.md
  </read_first>
  <files>
    teressa-copeland-homes/src/app/portal/(protected)/documents/[docId]/_components/PdfViewerWrapper.tsx,
    teressa-copeland-homes/src/app/portal/(protected)/documents/[docId]/_components/PdfViewer.tsx,
    teressa-copeland-homes/src/app/portal/(protected)/documents/[docId]/_components/FieldPlacer.tsx
  </files>
  <action>
    **PdfViewerWrapper.tsx:**
    - Import `DocumentSigner` from `@/lib/db/schema`
    - Add optional props: `signers?: DocumentSigner[]`, `unassignedFieldIds?: Set<string>`
    - Pass both through to `<PdfViewer signers={signers} unassignedFieldIds={unassignedFieldIds} ... />`

    **PdfViewer.tsx:**
    - Add same optional props to PdfViewer's prop interface: `signers?: DocumentSigner[]`, `unassignedFieldIds?: Set<string>`
    - Pass both through to `<FieldPlacer signers={signers} unassignedFieldIds={unassignedFieldIds} ... />`

    **FieldPlacer.tsx:**
    - Import `DocumentSigner` from `@/lib/db/schema`
    - Add to FieldPlacerProps: `signers?: DocumentSigner[]`, `unassignedFieldIds?: Set<string>`
    - Destructure in component function signature (default `signers = []`, `unassignedFieldIds = new Set()`)
    - Do NOT implement rendering changes yet (that is Plan 03) — just accept the props

    All three files: add the two new optional props and pass them through. No rendering or behavioral changes.
  </action>
  <verify>
    <automated>cd /Users/ccopeland/temp/red/teressa-copeland-homes && npx tsc --noEmit 2>&1 | head -30</automated>
  </verify>
  <acceptance_criteria>
    - `grep -n "signers" teressa-copeland-homes/src/app/portal/(protected)/documents/[docId]/_components/PdfViewerWrapper.tsx` shows prop accepted and passed through
    - `grep -n "signers" teressa-copeland-homes/src/app/portal/(protected)/documents/[docId]/_components/FieldPlacer.tsx` shows signers in FieldPlacerProps
    - `grep -n "unassignedFieldIds" teressa-copeland-homes/src/app/portal/(protected)/documents/[docId]/_components/FieldPlacer.tsx` shows unassignedFieldIds in FieldPlacerProps
    - `npx tsc --noEmit` passes
  </acceptance_criteria>
  <done>signers and unassignedFieldIds props flow from DocumentPageClient through PdfViewerWrapper and PdfViewer into FieldPlacer; TypeScript compiles cleanly</done>
</task>

</tasks>

<verification>
- `npx tsc --noEmit` passes with no errors
- `grep -rn "signers" teressa-copeland-homes/src/app/portal/(protected)/documents/` confirms signers threaded through page.tsx -> DocumentPageClient -> PdfViewerWrapper -> PdfViewer -> FieldPlacer AND DocumentPageClient -> PreparePanel
- `grep -rn "unassignedFieldIds" teressa-copeland-homes/src/app/portal/(protected)/documents/` confirms unassignedFieldIds threaded through the same paths
</verification>

<success_criteria>
- DocumentPageClient has `signers` and `unassignedFieldIds` state
- Server page passes `initialSigners` from `doc.signers`
- Both PreparePanel and FieldPlacer (via PdfViewerWrapper chain) receive signers and unassignedFieldIds as props
- TypeScript compiles with no errors
</success_criteria>

<output>
After completion, create `.planning/phases/16-multi-signer-ui/16-01-SUMMARY.md`
</output>