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

Tasks — add-packer-browser-core (Cluster A migration of @suaveplan/packer-browser)

Every checkbox MUST reflect work actually done in this change. No retroactive ticking.

1. Spec authoring

• 1.1 Read ../suaveplan/enterprise/packer-browser.md end-to-end
• 1.2 Read openspec/specs/packer/spec.md (sibling reference) and the archived enterprise-packer-* change deltas
• 1.3 Read openspec/AGENTS.md §0a, §0c, §2b, §2c, §6a, §7, §13, §14
• 1.4 Draft proposal.md from openspec/templates/proposal.md with ## Source mapping, ## Out of scope, ## Parity Checklist, and ## Impact populated
• 1.5 Fill in ## Source mapping table — every requirement cites enterprise-audit line ranges OR appears in the "no source line" table
• 1.6 Draft specs/packer-browser/spec.md from openspec/templates/spec-delta.md
• 1.7 Every requirement in the spec delta carries a **Verified by:** line naming concrete it(...) titles

2. Implementation

• 2.1 Fix scripts/folder-reorg/assignment.yml — remove - packer-browser from bitpacker:, insert under data: between packer and pagination
• 2.2 Author package.json (workspace deps via workspace:^, externals via catalog: keys, no React, no bare versions)
• 2.3 Author tsconfig.lib.json (extends repo base, DOM + WebWorker libs)
• 2.4 Author vite.config.ts (multi-entry build for the 5 subpaths)
• 2.5 Author vitest.config.ts (via createTestConfig with happy-dom, fileParallelism: false)
• 2.6 Author playwright.config.ts (Chromium project, no parallelism)
• 2.7 src/error-codes.ts — PACKER_BROWSER_CODES (6 stable codes) + PACKER_BROWSER_ERROR_METADATA + PackerBrowserError extends SuaveplanError
• 2.8 src/i18n/messages.ts + messages.types.ts — PACKER_BROWSER_MESSAGES catalog + defaultPackerBrowserResolver + resolvePackerBrowserMessage
• 2.9 src/runtime/runtime.ts + runtime.types.ts — defaultClock, defaultRng, resolveRuntime, elapsedMs
• 2.10 src/observability/observability.ts + observability.types.ts — createPackerBrowserObservability exposing 3 counters + 1 histogram
• 2.11 src/flags/flags.ts — resolveFlagsProvider (MemoryProvider fallback)
• 2.12 src/signature/signature.ts — verifyArchiveSignature wrapping ed25519.verify
• 2.13 src/cache/cache.ts — PackedResourceCache (LRU + ref-count + Blob-URL bookkeeping, OTel-instrumented, Clock-driven timestamps)
• 2.14 src/loader/loader.ts — PackedResourceLoader (fetch via withRetry, signature verification, AbortSignal at every yield, Unpacker.unpack integration, histogram observation)
• 2.15 src/manager/manager.ts — PackedResourceManager lifecycle façade + createPackedResourceManager factory + event emitter; each file ≤ 300 LOC
• 2.16 src/service-worker/sw-shim.ts — hand-rolled createServiceWorkerShim() implementing ServiceWorkerGlobalScope, FetchEvent, ExtendableEvent, Cache, CacheStorage, Clients
• 2.17 src/service-worker/service-worker.ts — runPackedResourceServiceWorker(scope) registering install / activate / fetch / message handlers
• 2.18 src/utils/register-service-worker.ts — register / unregister / clearCache / getCacheStatus helpers
• 2.19 src/singleton.ts — module-singleton hosted at /singleton subpath
• 2.20 src/index.ts — explicit named re-exports (no export *); default surface excludes packedResourceManager
• 2.21 README.md — install / quick-start / modules

3. Tests (100% coverage, runner-neutral imports)

• 3.1 src/error-codes.test.ts covering PACKER-BROWSER-6
• 3.2 src/i18n/messages.test.ts covering PACKER-BROWSER-8
• 3.3 src/runtime/runtime.test.ts covering PACKER-BROWSER-9
• 3.4 src/observability/observability.test.ts covering PACKER-BROWSER-4
• 3.5 src/flags/flags.test.ts covering PACKER-BROWSER-11
• 3.6 src/signature/signature.test.ts covering PACKER-BROWSER-3
• 3.7 src/cache/cache.test.ts covering PACKER-BROWSER-1, -4, -9
• 3.8 src/loader/loader.test.ts covering PACKER-BROWSER-1, -3, -4, -6, -7, -10
• 3.9 src/manager/manager.test.ts covering PACKER-BROWSER-1, -5, -7, -11
• 3.10 src/singleton.test.ts covering PACKER-BROWSER-5
• 3.11 src/service-worker/sw-shim.test.ts covering PACKER-BROWSER-2
• 3.12 src/service-worker/service-worker.test.ts covering PACKER-BROWSER-2
• 3.13 src/utils/register-service-worker.test.ts covering PACKER-BROWSER-2
• 3.14 src/index.test.ts covering PACKER-BROWSER-12
• 3.15 Every it(...) carries { timeout: 5000 }; async-IO suites use { timeout: 30_000 }
• 3.16 Every test file imports from @suaveplan/testing/runner only (no direct vitest / bun:test imports)
• 3.17 tests/e2e/sw.spec.ts Playwright happy-path

4. Documentation

• 4.1 Sibling .md for every implementation .ts (≥200 words, Purpose / Features / Basic / Advanced / API Reference / Implementation Notes)
• 4.2 README.md links every co-located .md under ## Modules
• 4.3 Update root CLAUDE.md package listing to add the new package
• 4.4 Update STATUS.md — flip the packer-browser row to ✅ and move it into the data section table
• 4.5 Refresh MANIFEST.md via bun scripts/folder-reorg/generate-manifest.ts

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

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

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

• 6.1 Generics threaded; expectTypeOf assertions on every literal-type claim that affects the public surface
• 6.2 Zod schemas wired at every declared boundary (option-bundle validation deferred to Cluster B per audit; flagged in proposal)
• 6.3 Every error code in error-codes.ts thrown by at least one production path
• 6.4 Strict-mode behaviors tested both on and off (signature verify on / off; retry on / off; cache on / off)
• 6.5 OTel instruments emitted from production paths and asserted with a real in-memory MeterProvider
• 6.6 Lifecycle dedup tested where claimed (factory returns fresh instances; singleton returns stable reference)
• 6.7 No retroactive tick — every box above reflects work done in this change

7. Archive

• 7.1 Fold spec delta into openspec/specs/packer-browser/spec.md
• 7.2 Move openspec/changes/add-packer-browser-core/ → openspec/archive/<yyyy-mm-dd>-add-packer-browser-core/
• 7.3 Refresh MANIFEST.md after the move