Initial Commit

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

@@ -0,0 +1,87 @@
+# enhance-packer-browser-platform — Cluster C §4 platform enhancements
+
+**Package**: `@suaveplan/packer-browser`
+**Status**: PROPOSED
+**Type**: feature
+**Spec delta**: ./specs/packer-browser/spec.md
+
+## Why
+
+Cluster A (`2026-05-19-add-packer-browser-core`) shipped the production
+core (PACKER-BROWSER-1..12). Cluster B
+(`2026-05-19-enhance-packer-browser-streaming`) shipped the four streaming
+items (PACKER-BROWSER-13..16). The upstream audit
+(`../suaveplan/enterprise/packer-browser.md` §4) enumerates ten feature-rich
+enhancements; six remain after Clusters A + B: adaptive cache sizing,
+preload-hint generation, multi-origin SW helper, BackgroundFetch
+integration, diagnostics dev overlay, and the final subpath split + full
+Playwright E2E sweep. Cluster C closes all six so the package reaches
+parity with the upstream §4 list and the audit's §6 acceptance criteria.
+
+## What changes
+
+Pure additions. Cluster A/B public surface (PACKER-BROWSER-1..16) remains
+intact. Cluster C adds new exports, three new subpath entrypoints
+(`/diagnostics`, `/prefetch`, `/preload`), one new error code, and two new
+OTel counters; no removals.
+
+- ADDED: `createAdaptiveCacheSizer(opts)` — recurring `navigator.storage.estimate()`
+  poller that mutates the manager's cache ceiling. AbortSignal-aware, Clock-injected.
+- ADDED: `PackedResourceManagerOptions.adaptiveCache` — `{ enabled?, fraction?, intervalMs?, signal? }`.
+- ADDED: `PackedResourceCache.setMaxCacheSize(n)` — runtime ceiling mutator used by the adaptive sizer.
+- ADDED: `generatePreloadHints(manifest, opts)` and `injectPreloadHints(doc, hints)` at the new `/preload` subpath.
+- ADDED: `registerCrossOriginPackedResourceServiceWorker(opts)` at the existing `/utils` subpath; rejects with `PACKER_BROWSER.UNAUTHORIZED_ORIGIN` on mismatch.
+- ADDED: `PACKER_BROWSER_CODES.UNAUTHORIZED_ORIGIN` — new error code (8th total).
+- ADDED: `prefetchPackedArchive(archiveUrl, opts)` at the new `/prefetch` subpath using `BackgroundFetchManager`.
+- ADDED: `handleBackgroundFetchSuccess(event, opts)` SW helper.
+- ADDED: `PackerBrowserCounters.prefetchSuccessTotal` + `prefetchFailureTotal` — two new OTel counters.
+- ADDED: `createDiagnosticsOverlay(manager, opts)` at the new `/diagnostics` subpath.
+- ADDED: Subpath exports `./preload`, `./prefetch`, `./diagnostics` (total subpaths now 8 incl. `./package.json`).
+- ADDED: Playwright E2E specs covering SW intercept, range 206, encrypted archive end-to-end, content-addressed URL invalidation, preload injection, diagnostics mount/unmount.
+
+## Out of scope
+
+- React companion package (`@suaveplan/react-packer`) — distinct package, separate change.
+- Mutation testing harness — covered by separate cross-cutting work.
+- Multi-browser Playwright matrix (Firefox + WebKit projects). Cluster C
+  ships the spec coverage on the chromium project; multi-browser execution
+  awaits a `playwright install` step which is documented but not run by
+  default in the genesis CI.
+
+## Source mapping
+
+This change derives from `../suaveplan/enterprise/packer-browser.md`.
+
+| Requirement | Source lines | Notes |
+|---|---|---|
+| PACKER-BROWSER-17 — Adaptive cache sizing | L71-L71 | §4.3 adaptive cache via `navigator.storage.estimate()`; flag-gated, Clock-injected, AbortSignal-aware. |
+| PACKER-BROWSER-18 — Preload-hint generation | L73-L73 | §4.5 `<link rel="preload">` on SW install; pure helper + DOM injector. |
+| PACKER-BROWSER-19 — Multi-origin SW helper | L75-L75 | §4.7 CDN-origin SW; new `UNAUTHORIZED_ORIGIN` code; wraps Cluster A's `registerPackedResourceServiceWorker`. |
+| PACKER-BROWSER-20 — BackgroundFetch integration | L76-L76 | §4.8 prefetch via `BackgroundFetchManager`; new `prefetchSuccessTotal`/`prefetchFailureTotal` counters. |
+| PACKER-BROWSER-21 — Diagnostics dev overlay | L77-L77 | §4.9 live overlay; subscribe-only, no manager mutation, real DOM. |
+| PACKER-BROWSER-22 — Final subpath split + Playwright E2E | L78-L78 / §4.10, §5.8-5.9 | Adds `/preload`, `/prefetch`, `/diagnostics` subpaths and ships the E2E suite. |
+
+## Verification approach
+
+- `src/adaptive-cache/adaptive-cache.test.ts` — adaptive sizer + cache ceiling mutation.
+- `src/preload/preload.test.ts` — `generatePreloadHints` + `injectPreloadHints` against happy-dom.
+- `src/utils/cross-origin.test.ts` — origin allowlist + `UNAUTHORIZED_ORIGIN` error.
+- `src/prefetch/prefetch.test.ts` — `prefetchPackedArchive` + SW success handler against a `BackgroundFetchManager` shim.
+- `src/diagnostics/diagnostics.test.ts` — overlay mount/update/unmount + null-document fallback.
+- `src/error-codes.test.ts` — extended to assert `UNAUTHORIZED_ORIGIN` registration + production usage.
+- `src/observability/observability.test.ts` — extended to cover prefetch counters via real `MeterProvider`.
+- `tests/e2e/sw.spec.ts` + new specs in `tests/e2e/` — Playwright sweep.
+
+## Migration impact
+
+None — additive only. Cluster A/B public surface unchanged. Subpath additions are
+backwards-compatible.
+
+## Impact
+
+### Affected dependents
+
+Run `bunx turbo ls --filter=...@suaveplan/packer-browser` to enumerate. The
+package currently has no in-monorepo dependents on the `genesis` branch.
+
+- No dependents — verified by `grep -rln "@suaveplan/packer-browser" /home/paul/web/genesis/packages/ /home/paul/web/genesis/apps/`.