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/.

5.2 KiB Raw Blame History