Initial Commit

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

@@ -0,0 +1,49 @@
+# 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.