suaveplan/openspec/archive/2026-05-19-add-react-packer/tasks.md

Tasks — Add @suaveplan/react-packer

Every checkbox MUST reflect work actually done in this change.

1. Spec authoring

• 1.1 Read ../suaveplan/packages/browser/packer-browser/src/hooks/usePackedResource.ts
• 1.2 Read ../suaveplan/enterprise/packer-browser.md §3.3
• 1.3 Read openspec/AGENTS.md §§0c, 2b, 6a, 7, 13, 14
• 1.4 Draft proposal.md from openspec/templates/proposal.md
• 1.5 Source-mapping table filled in (every requirement cites upstream lines OR an enterprise-md gap)
• 1.6 Draft specs/react-packer/spec.md from openspec/templates/spec-delta.md
• 1.7 Every requirement carries a **Verified by:** line with concrete planned it(...) titles

2. Implementation

• 2.1 Scaffold packages/data/react-packer/ (package.json, tsconfig, vite, vitest, playwright)
• 2.2 Add react-packer to scripts/folder-reorg/assignment.yml (data block, alphabetical between pagination and serialize)
• 2.3 src/error-codes/error-codes.ts — REACT_PACKER_CODES registry + ReactPackerError
• 2.4 src/types/react-packer.types.ts — UsePackedResourceOptions, UsePackedResourceReturn, UsePackedFontReturn, PackedResourceProviderValue
• 2.5 src/provider/packed-resource-provider/packed-resource-provider.tsx — context + usePackedResourceManager
• 2.6 src/hooks/use-packed-resource/use-packed-resource.ts — generic hook with AbortController, mounted-ref, reload counter
• 2.7 src/hooks/use-packed-image/use-packed-image.ts
• 2.8 src/hooks/use-packed-audio/use-packed-audio.ts
• 2.9 src/hooks/use-packed-video/use-packed-video.ts
• 2.10 src/hooks/use-packed-font/use-packed-font.ts — adds @font-face injection + fontLoaded
• 2.11 src/index.ts barrel — explicit named re-exports only
• 2.12 src/<feature>/index.ts feature barrels — explicit named re-exports (§6a)

3. Tests

• 3.1 src/error-codes/error-codes.test.ts
• 3.2 src/provider/packed-resource-provider/packed-resource-provider.test.tsx
• 3.3 src/hooks/use-packed-resource/use-packed-resource.test.tsx
• 3.4 src/hooks/use-packed-image/use-packed-image.test.tsx
• 3.5 src/hooks/use-packed-audio/use-packed-audio.test.tsx
• 3.6 src/hooks/use-packed-video/use-packed-video.test.tsx
• 3.7 src/hooks/use-packed-font/use-packed-font.test.tsx
• 3.8 Every it(...) carries { timeout: 5000 } (30000 where genuinely async)
• 3.9 Test files import from @suaveplan/testing/runner only (rule 11 / §7)
• 3.10 No mocks — real PackedResourceManager + real Response+Blob fixtures

4. Documentation

• 4.1 Sibling .md per implementation file (≥200 words, basic + advanced + API + impl notes)
• 4.2 Stories .stories.tsx per hook + provider
• 4.3 README.md at package root linking every co-located .md
• 4.4 Update CLAUDE.md package listing under data block alongside packer-browser
• 4.5 Update STATUS.md with new row

5. Pre-archive verification (the 5-gate triple)

• 5.1 bun run check — Biome 0 errors / 0 warnings
• 5.2 bunx turbo lint typecheck test --filter=@suaveplan/react-packer — green
• 5.3 bunx turbo test:coverage --filter=@suaveplan/react-packer — 100/100/100/100
• 5.4 bun scripts/openspec-conformance.ts @suaveplan/react-packer — exit 0
• 5.5 bunx turbo build --filter=@suaveplan/react-packer — green

6. Pre-archive 9-row checklist (AGENTS.md §13)

• 6.1 Generics threaded where appropriate; no inline shapes (rule 11)
• 6.2 No Zod boundaries declared (no untrusted inputs cross the hook surface — manager handles its own boundaries)
• 6.3 Every error code in REACT_PACKER_CODES thrown by at least one production path
• 6.4 AbortSignal propagation tested (pre-aborted + abort-on-unmount + abort-on-url-change)
• 6.5 OTel traces pass through unchanged (the manager owns them; hooks do not add counters per scope)
• 6.6 Lifecycle dedup tested — mounted-ref guard prevents setState after unmount
• 6.7 Singleton fallback resolves only when no provider is mounted
• 6.8 No retroactive tick — every box above reflects work in this change
• 6.9 Consumer sweep clean (no existing genesis consumers of @suaveplan/react-packer)

7. Archive

• 7.1 Fold spec delta into openspec/specs/react-packer/spec.md (NEW capability)
• 7.2 Move openspec/changes/add-react-packer/ → openspec/archive/<yyyy-mm-dd>-add-react-packer/
• 7.3 Refresh MANIFEST.md via bun scripts/folder-reorg/generate-manifest.ts