# 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.