130 lines
11 KiB
Markdown
130 lines
11 KiB
Markdown
# @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.
|
|
|