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

Tasks — enhance-packer-browser-platform

1. Spec authoring

• 1.1 Read ../suaveplan/enterprise/packer-browser.md §4 items 3, 5, 7, 8, 9, 10
• 1.2 Read openspec/specs/packer-browser/spec.md (PACKER-BROWSER-1..16)
• 1.3 Read openspec/AGENTS.md Sections 13 and 14
• 1.4 Draft proposal.md with Source mapping + Affected dependents
• 1.5 Draft specs/packer-browser/spec.md carrying PACKER-BROWSER-17..22
• 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