# Live Document Preview — Design (HQ console)

**Status:** approved (founder, 2026-07-13, via ultracode design panel + brainstorm).
**Origin:** spec [14-SPEC-HQ-CONSOLE.md](../../14-SPEC-HQ-CONSOLE.md) §3 already promised a
"live PDF preview on letterhead" in the composer; this is that, designed properly and
extended to three cheap sibling surfaces.

## 1. The one idea that makes it safe

The preview must **never drift from what prints**. That is guaranteed *architecturally,
not by testing*: the preview shows the output of the **same** `documentHtml()` template
and the **same** `computeBill()` tax engine that the PDF uses — there is no second
renderer and no client-side money math. The browser renders that HTML directly in an
iframe (puppeteer only rasterizes the identical HTML for the actual PDF).

Winning approach = engineering-minimalist core (smallest correct change, one shared
compute path) + grafted UX pieces (server-truth totals strip, permissive preview,
no-blank swap). Chosen by a 2-judge panel (value judge 8.5 ux / cost judge 9 minimal →
minimal core carrying ux's high-value grafts).

## 2. Server: one new pure function + one route

**Refactor (no behavior change):** extract the compute block of `createDraft` in
`apps/hq/src/repos-documents.ts` into a pure `prepareDraft(db, input): { lines, totals,
payload }` that does **not** persist. `createDraft` calls `prepareDraft` then inserts —
so save and preview cannot diverge by construction.

**New route** `POST /api/documents/preview` (`requireAuth`, api.ts style):
- Body: the **exact** `DraftInput` shape `POST /api/documents` takes.
- Builds a synthetic **unsaved** `Doc` (`docNo: null` → template prints "DRAFT";
  `docDate: today`; `fy` via `fyOf`), runs `prepareDraft` + `documentHtml`.
- Returns `{ ok: true, html: string, totals: BillTotals, warnings: string[] }`.
- Persists nothing; writes no audit row (it is a read). Cost = a few SQLite reads +
  string templating (single-digit ms); no puppeteer, no browser contention.

**Permissive vs strict:** the preview endpoint is **permissive** — a line with no
price-book row and no manual rate computes at ₹0 and is reported in `warnings[]` (so
staff can keep typing); **`POST /api/documents` (save) stays strict** and still rejects
the same bad document. Preview forgives; save refuses.

**Fidelity test:** one golden test asserts the preview route and `renderPdf` consume
**string-identical** HTML for a fixture draft + a `prepareDraft`↔`createDraft`
deep-equal parity test (totals/payload). Guards anyone ever forking the template.

## 3. Client: the composer becomes a split view

`apps/hq-web/src/pages/NewDocument.tsx`, layout **"form + A4 paper fills the rest"**
(founder pick):

- **Left**, fixed ~600px, own scroll: the existing form. Its bottom gets a **sticky
  totals strip** — Taxable / (CGST+SGST *or* IGST) / Round-off / Payable — sourced from
  the **response's `totals`**, deleting the client-side subtotal reducer at
  `NewDocument.tsx:91` (the last client money math; its removal is the single biggest
  trust win — the IGST split now appears live for out-of-state clients).
- **Right**, fills remaining width, sticky under the header: grey backdrop + a white
  **A4 paper card** (210mm aspect, `transform: scale` to fit width) holding a
  **sandboxed `srcdoc` iframe** of the real template HTML.
- **Narrow (<800px, owner's phone):** single-column form; a pinned bottom bar always
  shows Payable + GST + a **Preview** button that opens the paper as a full-screen sheet
  (fixed-dimension wrapper + `transform: scale` — iOS Safari expands bare iframes).
  The totals bar never disappears at any width.

**Update mechanics:**
- A shared client helper `buildDraftBody()` (extracted from the save path) builds the
  request body, so preview and save POST **byte-identical** bodies.
- **Immediate** refire (0ms) on commit-shaped events (client pick, doctype radio,
  module/kind/pack select, add/remove line, field blur); **400ms trailing debounce** on
  keystrokes (qty/unit/description/content/terms).
- One in-flight request max: `AbortController` cancels superseded calls; a sequence
  guard drops stale responses; skip the POST entirely when the serialized body is
  unchanged.
- **Never blank the pane:** keep the previous paper visible, show a 2px shimmer + dim
  totals to 60% while in flight, then double-buffer swap (write into a hidden stacked
  iframe, restore `scrollTop`, 120ms cross-fade) — no white flash, no scroll jump.
  Changed totals cells pulse 250ms (cause→effect made visible).

**Empty/error states (client):** zero valid lines → real letterhead, empty table, ₹0
(never a mock); no client picked → muted "— pick a client —" block, totals shown with a
"split pending client" tag (18% total is invariant) that clears with a pulse on pick;
`warnings[]` price gaps → inline "No price — enter Unit ₹" + amber rate-cell flag;
server unreachable/400 → keep last good paper, slim "Preview paused — retrying" banner
with as-of timestamp, totals greyed (never present stale numbers as fresh);
`company.state_code` unset → actionable link to Settings → Company.

**Two honest screen/print deltas:** `@page` 14mm margins → the card draws 14mm padding
with a faint toggleable "Show print area" guide; pagination is puppeteer's → an
approximate dashed page-break line at ~269mm content height plus an on-demand "Exact PDF"
button (real puppeteer render) for the rare must-be-one-page quote. The ~5-line
`@media screen` paper styles live **inside templates.ts** (with a "page.pdf renders
print media" comment), not injected client-side, so the paper itself is template-owned;
only preview *chrome* (guides, pulses, tags) is client overlay.

## 4. Three cheap sibling surfaces (same round)

All reuse the one preview route/mechanism — each is S effort:
1. **Company profile editor** — live letterhead (header, GSTIN, bank box, signatory)
   rendered from a hardcoded sample doc as the owner edits `company.*`. Errors here
   corrupt *every* document, so seeing it matters.
2. **Module quote-content editor** (Modules page) — live render of how the "what's
   included" bullets actually print (the 10px grey `ul.line-content`), using a one-line
   sample doc. Today they're written blind.
3. **Reminder email preview** (manual queue / send) — the exact outgoing email (subject +
   body from the pure `reminderEmail(kind, ctx)`), via `GET /api/reminders/:id/preview`.
   Staff currently fire client-facing dunning mail unseen.

## 5. Deliberately NOT this round

Credit-note & receipt preview (mechanically derived, low value now); **store-product
surfaces** — documented as handoff to that workstream, not built here: Print Templates
visual editor (doc 09 explicitly specs it), Label Printing (already has a popup preview),
Price-list bulk revise, Schemes editor, WhatsApp/message-catalog text, and the **POS
printer-settings receipt preview** (high value — `packages/printing` already renders
42/32-col receipts as pure functions, so it's cheap when that team wants it).

## 6. Files

- `apps/hq/src/repos-documents.ts` — extract `prepareDraft`; `createDraft` calls it.
- `apps/hq/src/api.ts` — `POST /api/documents/preview`, `GET /api/reminders/:id/preview`.
- `apps/hq/src/templates.ts` — add `@media screen` paper styles + sample-doc helpers for
  company/quote-content previews.
- `apps/hq-web/src/pages/NewDocument.tsx` — split layout, totals strip, LivePreview.
- `apps/hq-web/src/components/LivePreview.tsx` — new: debounced fetch + double-buffer
  iframe (kept modest per YAGNI — a composer helper, generalized only if a 2nd/3rd
  surface proves the shape).
- `apps/hq-web/src/pages/CompanyProfile.tsx`, `Modules.tsx`, dashboard reminder queue —
  wire the sibling previews.
- Tests: string-identity golden + prepareDraft/createDraft parity + preview-permissive /
  save-strict divergence + route auth.

## 7. Success criteria

Staff draft a quotation and watch the letterhead build itself in under ~400ms per edit,
with GST (incl. IGST split for out-of-state) always shown by the server; the on-screen
paper is byte-identical to the PDF that later prints; no blank flashes; save remains
strict so bad drafts never persist; the same mechanism previews the company letterhead,
quote-content bullets, and reminder emails.