suaveplan/openspec/changes/enterprise-react-pdf/tasks.md

Tasks: enterprise-react-pdf

Change ID: enterprise-react-pdf Package: @suaveplan/react-pdf Target path: react/media/react-pdf Prerequisite packages on Verdaccio: @suaveplan/error, @suaveplan/react-translate

---

0. Pre-flight (non-negotiable)

• 0.1 Confirm clean working tree (git status reports nothing) and no in-flight worktrees with uncommitted work (git worktree list then git status in each)
• 0.2 If any worktrees exist under .claude/worktrees/, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (git worktree remove) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
• 0.3 Confirm the package set in MANIFEST.md matches find packages -maxdepth 3 -name package.json count. Drift here means a prior change archived without regenerating the manifest.

1. Scaffold

• Create directory tree. Write package.json at 0.1.0, tsconfig.json, vitest.config.ts, scripts.
• Dependencies: @suaveplan/error workspace:^, @suaveplan/react-translate workspace:^, pdfjs-dist catalog:documents, zod catalog:forms, tslib catalog:build.

---

2. Error codes and types

• Define PdfError; codes: PDF_LOAD_FAILED, PDF_RENDER_FAILED.
• Define PdfViewerProps (with mode?: 'native' | 'pdfjs'), PdfToolbarProps, NativePdfViewerProps, PdfJsViewerProps.

---

3. PdfToolbar

• Props: currentPage, totalPages, onPageChange(n), zoom, onZoomChange(z).
• Bug fix: totalPages accepts 0 and displays "–" (not "0 pages") when page count is unknown.
• useTranslation for all button aria-labels and display strings.
• Write test + stories (known-pages, unknown-pages, zoomed, playground) + md.

---

4. NativePdfViewer

• Renders <object type="application/pdf"> with fallback. Passes #page=N fragment.
• totalPages is always null (browser does not expose it); PdfToolbar shows "–".
• Write test + md.

---

5. PdfJsViewer

• Loads PDF via pdfjs-dist getDocument(url); reads pdf.numPages.
• Renders current page on <canvas> with correct devicePixelRatio scaling.
• Text layer: PDFPageView.renderTextLayer() for screen reader access.
• onPageChange(n) re-renders page.
• Throws PdfError(PDF_LOAD_FAILED) on getDocument failure; PdfError(PDF_RENDER_FAILED) on render failure.
• Write pdf-js-viewer.test.tsx (≤500 lines): load PDF (DI-injected mock pdfjs-dist), page count read, page navigation, error states. { timeout: 10000 }.
• Write pdf-js-viewer.md.

---

6. PdfViewer (composite)

• mode: 'native' | 'pdfjs' prop (default 'pdfjs'); renders correct tier + PdfToolbar.
• Write test + stories (native, pdfjs, loading, error, playground) + md.

---

7. E2E

• e2e/pdf.spec.ts — Playwright:
  • Render PdfViewer in pdfjs mode with a test PDF, verify page count displayed.
  • Click Next in toolbar, verify current page increments.
  • Render in native mode, verify <object> element present.

---

8. Verify and publish

• bunx turbo lint typecheck test --filter=@suaveplan/react-pdf — green.
• bunx turbo test:coverage --filter=@suaveplan/react-pdf — 100%.
• bun scripts/publish.ts --package @suaveplan/react-pdf.
• Archive change folder.