first commit

2026-05-29 08:20:56 +01:00
commit 949299f58d
6368 changed files with 527176 additions and 0 deletions
--- a/docs/foundation/data/packer-browser/README.md
+++ b/docs/foundation/data/packer-browser/README.md
@@ -0,0 +1,129 @@
+# @suaveplan/packer-browser - Browser runtime for @suaveplan/packer — Service Worker interceptor, PackedResourceManager (LRU + Blob-URL bookkeeping), signed-manifest verification, OTel metrics, AbortSignal-aware loader. No React.
+
+Browser-tier runtime for `@suaveplan/packer` archives. Ships a Service Worker
+interceptor, a `PackedResourceManager` (LRU + Blob-URL bookkeeping +
+ref-count + OTel metrics), Ed25519 archive-signature verification, and
+lifecycle helpers for registering / clearing / inspecting the SW cache. No
+React runtime dependency — React hooks land in the companion
+`@suaveplan/react-packer` package.
+
+<!-- begin:auto-docs -->
+## Documentation tree
+
+- [adaptive-cache](./src/adaptive-cache/adaptive-cache.md) — `createAdaptiveCacheSizer` periodically resizes a `PackedResourceCache` from a `navigator.storage.estimate()`-style quo…
+  - [adaptive-cache](./src/adaptive-cache/adaptive-cache.md) — `createAdaptiveCacheSizer` periodically resizes a `PackedResourceCache` from a `navigator.storage.estimate()`-style quo…
+- [cache](./src/cache/cache.md) — `cache.ts` implements `PackedResourceCache` — an LRU + ref-count cache that owns the Blob-URL lifecycle for every unpac…
+  - [cache](./src/cache/cache.md) — `cache.ts` implements `PackedResourceCache` — an LRU + ref-count cache that owns the Blob-URL lifecycle for every unpac…
+- [content-address](./src/content-address/content-address.md) — Content-addressed URL builder and cache-invalidation helpers for packed archives. Each archive's canonical URL is deriv…
+  - [content-address](./src/content-address/content-address.md) — Content-addressed URL builder and cache-invalidation helpers for packed archives. Each archive's canonical URL is deriv…
+- [diagnostics](./src/diagnostics/diagnostics.md) — `createDiagnosticsOverlay` produces a development-time overlay that displays live cache statistics and a tail of recent…
+  - [diagnostics](./src/diagnostics/diagnostics.md) — `createDiagnosticsOverlay` produces a development-time overlay that displays live cache statistics and a tail of recent…
+- [encrypted-archive](./src/encrypted-archive/encrypted-archive.md) — Wire format for AES-256-GCM-encrypted packed archives served alongside unencrypted bundles. Adopts the stable magic pre…
+  - [encrypted-archive](./src/encrypted-archive/encrypted-archive.md) — Wire format for AES-256-GCM-encrypted packed archives served alongside unencrypted bundles. Adopts the stable magic pre…
+- [error-codes](./src/error-codes/error-codes.md) — `error-codes.ts` is the single source of truth for every error class and stable code emitted by `@suaveplan/packer-brow…
+  - [error-codes](./src/error-codes/error-codes.md) — `error-codes.ts` is the single source of truth for every error class and stable code emitted by `@suaveplan/packer-brow…
+- [flags](./src/flags/flags.md) — `flags.ts` resolves the `@suaveplan/feature-flags` `FlagProvider` used by `PackedResourceManager` to gate Cluster B / C…
+  - [flags](./src/flags/flags.md) — `flags.ts` resolves the `@suaveplan/feature-flags` `FlagProvider` used by `PackedResourceManager` to gate Cluster B / C…
+- [i18n](./src/i18n/messages.md) — `messages.ts` is the English defaults catalog plus the resolver hook for every user-visible error message thrown by `@s…
+  - [messages](./src/i18n/messages.md) — `messages.ts` is the English defaults catalog plus the resolver hook for every user-visible error message thrown by `@s…
+- [keyring](./src/keyring/keyring.md) — Defines the `KeyringProvider` contract for resolving symmetric AES-256-GCM keys at decrypt time. The contract is intent…
+  - [keyring](./src/keyring/keyring.md) — Defines the `KeyringProvider` contract for resolving symmetric AES-256-GCM keys at decrypt time. The contract is intent…
+- [loader](./src/loader/loader.md) — `loader.ts` is the fetch → verify → unpack → Blob-URL pipeline for packed resources. It is the only place in the packag…
+  - [loader-helpers](./src/loader/loader-helpers.md) — Small free helpers extracted from `loader.ts` so the class stays under the 300-line hard cap. These functions carry no…
+  - [loader-stream](./src/loader/loader-stream.md) — Progressive entry-by-entry unpack helper that powers `PackedResourceLoader.loadStream`. Callers pass a list of packed-a…
+  - [loader](./src/loader/loader.md) — `loader.ts` is the fetch → verify → unpack → Blob-URL pipeline for packed resources. It is the only place in the packag…
+- [manager](./src/manager/manager.md) — `manager.ts` is the lifecycle façade that consumers interact with. It composes a `PackedResourceCache` and a `PackedRes…
+  - [manager-helpers](./src/manager/manager-helpers.md) — Small free helpers extracted from `manager.ts` to keep the class file under CLAUDE.md §3's 300-line hard cap. Both help…
+  - [manager-stream](./src/manager/manager-stream.md) — Free-function implementation of `PackedResourceManager.loadStream`, factored out of `manager.ts` so the class stays und…
+  - [manager](./src/manager/manager.md) — `manager.ts` is the lifecycle façade that consumers interact with. It composes a `PackedResourceCache` and a `PackedRes…
+  - [tiny-emitter](./src/manager/tiny-emitter.md) — Minimal generic typed event emitter used internally by `PackedResourceManager`. Factored out of `manager.ts` so the cla…
+- [observability](./src/observability/observability.md) — `observability.ts` creates the OpenTelemetry instrument bundle for `@suaveplan/packer-browser`. The package emits four…
+  - [observability](./src/observability/observability.md) — `observability.ts` creates the OpenTelemetry instrument bundle for `@suaveplan/packer-browser`. The package emits four…
+- [prefetch](./src/prefetch/prefetch.md) — The `prefetch` module wraps the Chromium `BackgroundFetchManager` API so an application can preload an archive on idle…
+  - [prefetch](./src/prefetch/prefetch.md) — The `prefetch` module wraps the Chromium `BackgroundFetchManager` API so an application can preload an archive on idle…
+- [preload](./src/preload/preload.md) — `generatePreloadHints` derives an ordered list of `<link rel="preload">` hints from a packed manifest, and `injectPrelo…
+  - [preload](./src/preload/preload.md) — `generatePreloadHints` derives an ordered list of `<link rel="preload">` hints from a packed manifest, and `injectPrelo…
+- [range-response](./src/range-response/range-response.md) — RFC 7233 §2.1 single-range `Response` builder for packed-resource delivery from the Service Worker. Browsers ask for ra…
+  - [range-response](./src/range-response/range-response.md) — RFC 7233 §2.1 single-range `Response` builder for packed-resource delivery from the Service Worker. Browsers ask for ra…
+- [runtime](./src/runtime/runtime.md) — `runtime.ts` centralises the three injectable platform primitives (`Clock`, `MonotonicClock`, `Rng`) that every product…
+  - [runtime](./src/runtime/runtime.md) — `runtime.ts` centralises the three injectable platform primitives (`Clock`, `MonotonicClock`, `Rng`) that every product…
+- [service-worker](./src/service-worker/service-worker.md) — `service-worker.ts` is the production Service Worker entrypoint exposed via the `/service-worker` subpath. Its only pub…
+  - [service-worker](./src/service-worker/service-worker.md) — `service-worker.ts` is the production Service Worker entrypoint exposed via the `/service-worker` subpath. Its only pub…
+  - [sw-shim](./src/service-worker/sw-shim.md) — `sw-shim.ts` provides `createServiceWorkerShim()`, a hand-rolled in-memory implementation of `ServiceWorkerGlobalScope`…
+- [signature](./src/signature/signature.md) — `signature.ts` is the Ed25519 signature-verification gate run by the loader before any packed bytes are handed to `Unpa…
+  - [signature](./src/signature/signature.md) — `signature.ts` is the Ed25519 signature-verification gate run by the loader before any packed bytes are handed to `Unpa…
+- [singleton](./src/singleton/singleton.md) — `singleton.ts` exposes the module-level shared `PackedResourceManager` instance behind the `@suaveplan/packer-browser/s…
+  - [singleton](./src/singleton/singleton.md) — `singleton.ts` exposes the module-level shared `PackedResourceManager` instance behind the `@suaveplan/packer-browser/s…
+- [cross-origin](./src/utils/cross-origin.md) — `registerCrossOriginPackedResourceServiceWorker` lets an application register a packed-resource Service Worker hosted o…
+- [register-service-worker](./src/utils/register-service-worker.md) — `register-service-worker.ts` collects four lifecycle helpers exposed via the `/utils` subpath: `registerPackedResourceS…
+<!-- end:auto-docs -->
+
+## Install
+
+```bash
+bun add @suaveplan/packer-browser
+```
+
+## Quick start
+
+```ts
+import {
+    createPackedResourceManager,
+    registerPackedResourceServiceWorker,
+} from "@suaveplan/packer-browser";
+
+await registerPackedResourceServiceWorker({ scriptUrl: "/sw.js" });
+const manager = createPackedResourceManager();
+
+const blobUrl = await manager.load("/banner.packed");
+imgEl.src = blobUrl;
+```
+
+For a global shared instance, import from the `/singleton` subpath:
+
+```ts
+import { packedResourceManager } from "@suaveplan/packer-browser/singleton";
+const url = await packedResourceManager.load("/banner.packed");
+```
+
+## Modules
+
+- [`error-codes`](./src/error-codes.md) — `PACKER_BROWSER_CODES` + `PackerBrowserError`.
+- [`i18n/messages`](./src/i18n/messages.md) — `MessageResolver` catalog.
+- [`runtime/runtime`](./src/runtime/runtime.md) — injectable `Clock` / `Rng`.
+- [`observability/observability`](./src/observability/observability.md) — OTel counters + histogram.
+- [`flags/flags`](./src/flags/flags.md) — `@suaveplan/feature-flags` slot.
+- [`signature/signature`](./src/signature/signature.md) — `verifyArchiveSignature` (Ed25519).
+- [`cache/cache`](./src/cache/cache.md) — `PackedResourceCache` LRU + ref-count.
+- [`loader/loader`](./src/loader/loader.md) — `PackedResourceLoader` fetch / verify / unpack.
+- [`manager/manager`](./src/manager/manager.md) — `PackedResourceManager` lifecycle façade + factory.
+- [`service-worker/service-worker`](./src/service-worker/service-worker.md) — production SW entrypoint.
+- [`service-worker/sw-shim`](./src/service-worker/sw-shim.md) — hand-rolled `ServiceWorkerGlobalScope` shim for unit tests.
+- [`utils/register-service-worker`](./src/utils/register-service-worker.md) — SW lifecycle helpers.
+- [`singleton`](./src/singleton.md) — module-singleton hosted at `/singleton` subpath.
+
+## Subpath exports
+
+- `.` — full default surface (excludes the module singleton).
+- `./manager` — `PackedResourceManager`, factory, types.
+- `./service-worker` — `runPackedResourceServiceWorker` + `createServiceWorkerShim`.
+- `./utils` — `register` / `unregister` / `clearServiceWorkerCache` / `getServiceWorkerCacheStatus`.
+- `./singleton` — eagerly-constructed shared `packedResourceManager`.
+
+## Scope
+
+Cluster A delivers the production-quality core: manager split, OTel
+metrics, signed-manifest verification, `AbortSignal` propagation,
+injected `Clock`/`Rng`, retry on the source-pull, feature-flag slot,
+unit-tested SW with a real shim, and the five §3 subpath exports.
+
+Cluster B and C add progressive streaming, range-request SW, adaptive
+cache sizing, encrypted-archive keyring, content-addressed versioned
+URLs, BackgroundFetch, multi-origin SW helpers, and the diagnostics
+overlay. See the design proposal for
+the full out-of-scope list.
+
+## License
+
+MIT.
+