Initial Commit

openspec/archive/2026-05-19-enhance-packer-browser-platform/tasks.md

@@ -0,0 +1,84 @@
+# Tasks — enhance-packer-browser-platform
+
+## 1. Spec authoring
+
+- [x] 1.1 Read `../suaveplan/enterprise/packer-browser.md` §4 items 3, 5, 7, 8, 9, 10
+- [x] 1.2 Read `openspec/specs/packer-browser/spec.md` (PACKER-BROWSER-1..16)
+- [x] 1.3 Read `openspec/AGENTS.md` Sections 13 and 14
+- [x] 1.4 Draft `proposal.md` with Source mapping + Affected dependents
+- [x] 1.5 Draft `specs/packer-browser/spec.md` carrying PACKER-BROWSER-17..22
+- [x] 1.6 Every requirement carries a `**Verified by:**` line at draft time
+
+## 2. Implementation — C-1 adaptive cache sizing
+
+- [ ] 2.1 Add `setMaxCacheSize(n: number)` to `PackedResourceCache`; mutating the ceiling triggers `evictLRU()` while size > ceiling.
+- [ ] 2.2 Implement `src/adaptive-cache/adaptive-cache.ts` exposing `createAdaptiveCacheSizer(opts)`.
+- [ ] 2.3 Wire `adaptiveCache` into `PackedResourceManagerOptions` + manager constructor; gate via `packer-browser.cache.adaptive` flag (default ON).
+- [ ] 2.4 Register the new flag in `registerDefaultFlags`.
+
+## 3. Implementation — C-2 preload hint generation
+
+- [ ] 3.1 Implement `src/preload/preload.ts` exposing `generatePreloadHints(manifest, opts)` and `injectPreloadHints(doc, hints)`.
+- [ ] 3.2 Re-export from `/utils` (legacy) and add new `/preload` subpath.
+- [ ] 3.3 Wire OTel counter increments on every hint emitted.
+
+## 4. Implementation — C-3 multi-origin SW helper
+
+- [ ] 4.1 Add `UNAUTHORIZED_ORIGIN` to `PACKER_BROWSER_CODES`.
+- [ ] 4.2 Implement `src/utils/cross-origin.ts` exposing `registerCrossOriginPackedResourceServiceWorker(opts)`.
+- [ ] 4.3 Re-export from `/utils` subpath barrel + root.
+
+## 5. Implementation — C-4 BackgroundFetch integration
+
+- [ ] 5.1 Add `prefetchSuccessTotal` + `prefetchFailureTotal` counters to observability bundle.
+- [ ] 5.2 Implement `src/prefetch/prefetch.ts` exposing `prefetchPackedArchive(archiveUrl, opts)` and `handleBackgroundFetchSuccess(event, opts)`.
+- [ ] 5.3 Add new `/prefetch` subpath export.
+
+## 6. Implementation — C-5 diagnostics dev overlay
+
+- [ ] 6.1 Implement `src/diagnostics/diagnostics.ts` exposing `createDiagnosticsOverlay(manager, opts)`.
+- [ ] 6.2 Add new `/diagnostics` subpath export.
+- [ ] 6.3 Subscribe to manager's `TinyEmitter` events; assert no manager mutation.
+
+## 7. Implementation — C-6 final subpath split + Playwright E2E
+
+- [ ] 7.1 Update `package.json` `exports`: add `./preload`, `./prefetch`, `./diagnostics`. Update `vite.config.ts` lib entries.
+- [ ] 7.2 Write Playwright spec files in `tests/e2e/` covering SW intercept, range 206, encrypted archive, content-addressed invalidation, preload injection, diagnostics mount/unmount.
+- [ ] 7.3 Document `bunx playwright install chromium` in README "Test plan" footer.
+
+## 8. Tests
+
+- [ ] 8.1 Unit tests per feature covering every scenario named in the spec delta
+- [ ] 8.2 Every `it(...)` carries `{ timeout: 5000 }` (or 30000 for genuinely async)
+- [ ] 8.3 100/100/100/100 coverage on touched files
+
+## 9. Documentation
+
+- [ ] 9.1 Sibling `.md` (≥200 words, basic + advanced examples) for every new implementation file
+- [ ] 9.2 README links every co-located `.md` under `## Modules`
+
+## 10. Pre-archive verification (the 5-gate triple)
+
+- [ ] 10.1 `bun run check` — Biome 0 errors / 0 warnings
+- [ ] 10.2 `bunx turbo lint typecheck test --filter=@suaveplan/packer-browser` — green
+- [ ] 10.3 `bunx turbo test:coverage --filter=@suaveplan/packer-browser` — 100/100/100/100
+- [ ] 10.4 `bun scripts/openspec-conformance.ts @suaveplan/packer-browser` — exit 0
+- [ ] 10.5 `bunx turbo build --filter=@suaveplan/packer-browser` — green
+
+## 11. Pre-archive 9-row checklist (AGENTS.md Section 13)
+
+- [ ] 11.1 Generics threaded; `expectTypeOf` assertions on every literal-type claim
+- [ ] 11.2 Zod schemas wired at every declared boundary (n/a for this change — no wire surface)
+- [ ] 11.3 Every error code in `error-codes.ts` thrown by at least one production path (incl. new `UNAUTHORIZED_ORIGIN`)
+- [ ] 11.4 Strict-mode behaviors tested both on and off (n/a — no strict-mode toggle introduced)
+- [ ] 11.5 OTel instruments emitted from production paths and asserted with a real in-memory `MeterProvider` (incl. new prefetch counters)
+- [ ] 11.6 Lifecycle dedup tested where claimed (adaptive sizer disposer)
+- [ ] 11.7 `AbortSignal` propagation tested on every async surface
+- [ ] 11.8 Subpath exports resolve to built artefacts; `sideEffects: false` preserved
+- [ ] 11.9 No retroactive tick
+
+## 12. Archive
+
+- [ ] 12.1 Fold spec delta into `openspec/specs/packer-browser/spec.md` (append PACKER-BROWSER-17..22; preserve 1..16)
+- [ ] 12.2 Move `openspec/changes/enhance-packer-browser-platform/` → `openspec/archive/<yyyy-mm-dd>-enhance-packer-browser-platform/`
+- [ ] 12.3 Refresh `MANIFEST.md` via `bun scripts/folder-reorg/generate-manifest.ts`