suaveplan/openspec/changes/enterprise-react-pdf-preview/proposal.md

Proposal — @suaveplan/react-pdf-preview (deferred)

• Status: STUB (deferred from enterprise-pdf Chunk E)
• Spec delta: not yet authored — see Why / What below.
• Depends on: @suaveplan/pdf@0.1.0 (Chunks A–E, shipped).

Why

The upstream @suaveplan/pdf ships a pdf-preview React 19 component (/mnt/s/web/suaveplan/packages/server/pdf/src/components/pdf-preview/) that renders a Document AST as a live HTML preview, scaled to a configurable viewport, with synchronised scrolling and printable hard-page boundaries. The genesis @suaveplan/pdf package is deliberately server-tier (no React/DOM peer deps) — the preview must land in a sibling React-tier package so consumers can opt in without inflating the server bundle.

What

Create @suaveplan/react-pdf-preview at packages/devtools/docs/react-pdf-preview/ (React 19 peer-dep only, consumes @suaveplan/pdf via workspace:^). Land:

• PdfPreview React component rendering a Document<TData> via the layout engine into HTML primitives (no canvas — accessibility wins).
• usePdfPreview hook returning page-by-page render slots + scaling helpers.
• Storybook stories: default + scaled + paginated + dark-mode + printable-overlay variants.
• Playwright E2E spec exercising scroll-to-page, scale toggle, and PDF download.
• 100 / 100 / 100 / 100 Istanbul coverage + 100% docs coverage.

Out of scope

• Replacing the server-tier renderer — the React preview consumes the same Document AST produced by createDocument / template factories.
• Browser-tier PDF.js binding — that's a separate adapter package (@suaveplan/pdf-viewer) tracked elsewhere.
• Native (iOS / Android) preview — a future React Native package.

Acceptance criteria

• Package builds, lints, typechecks, tests, and ships with 100/100/100/100 coverage.
• Every exported symbol carries a co-located .md and a story.
• E2E spec passes against a staging Storybook deployment.
• @suaveplan/pdf remains React-free — the preview consumes its public surface only.