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

Documentation tree

adaptive-cache — createAdaptiveCacheSizer periodically resizes a PackedResourceCache from a navigator.storage.estimate()-style quo…
- adaptive-cache — createAdaptiveCacheSizer periodically resizes a PackedResourceCache from a navigator.storage.estimate()-style quo…
cache — cache.ts implements PackedResourceCache — an LRU + ref-count cache that owns the Blob-URL lifecycle for every unpac…
- cache — cache.ts implements PackedResourceCache — an LRU + ref-count cache that owns the Blob-URL lifecycle for every unpac…
content-address — Content-addressed URL builder and cache-invalidation helpers for packed archives. Each archive's canonical URL is deriv…
- content-address — Content-addressed URL builder and cache-invalidation helpers for packed archives. Each archive's canonical URL is deriv…
diagnostics — createDiagnosticsOverlay produces a development-time overlay that displays live cache statistics and a tail of recent…
- diagnostics — createDiagnosticsOverlay produces a development-time overlay that displays live cache statistics and a tail of recent…
encrypted-archive — Wire format for AES-256-GCM-encrypted packed archives served alongside unencrypted bundles. Adopts the stable magic pre…
- encrypted-archive — Wire format for AES-256-GCM-encrypted packed archives served alongside unencrypted bundles. Adopts the stable magic pre…
error-codes — error-codes.ts is the single source of truth for every error class and stable code emitted by `@suaveplan/packer-brow…
- error-codes — error-codes.ts is the single source of truth for every error class and stable code emitted by `@suaveplan/packer-brow…
flags — flags.ts resolves the @suaveplan/feature-flags FlagProvider used by PackedResourceManager to gate Cluster B / C…
- flags — flags.ts resolves the @suaveplan/feature-flags FlagProvider used by PackedResourceManager to gate Cluster B / C…
i18n — messages.ts is the English defaults catalog plus the resolver hook for every user-visible error message thrown by `@s…
- messages — messages.ts is the English defaults catalog plus the resolver hook for every user-visible error message thrown by `@s…
keyring — Defines the KeyringProvider contract for resolving symmetric AES-256-GCM keys at decrypt time. The contract is intent…
- keyring — Defines the KeyringProvider contract for resolving symmetric AES-256-GCM keys at decrypt time. The contract is intent…
loader — loader.ts is the fetch → verify → unpack → Blob-URL pipeline for packed resources. It is the only place in the packag…
- loader-helpers — Small free helpers extracted from loader.ts so the class stays under the 300-line hard cap. These functions carry no…
- loader-stream — Progressive entry-by-entry unpack helper that powers PackedResourceLoader.loadStream. Callers pass a list of packed-a…
- loader — loader.ts is the fetch → verify → unpack → Blob-URL pipeline for packed resources. It is the only place in the packag…
manager — manager.ts is the lifecycle façade that consumers interact with. It composes a PackedResourceCache and a `PackedRes…
- manager-helpers — 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 — Free-function implementation of PackedResourceManager.loadStream, factored out of manager.ts so the class stays und…
- manager — manager.ts is the lifecycle façade that consumers interact with. It composes a PackedResourceCache and a `PackedRes…
- tiny-emitter — Minimal generic typed event emitter used internally by PackedResourceManager. Factored out of manager.ts so the cla…
observability — observability.ts creates the OpenTelemetry instrument bundle for @suaveplan/packer-browser. The package emits four…
- observability — observability.ts creates the OpenTelemetry instrument bundle for @suaveplan/packer-browser. The package emits four…
prefetch — The prefetch module wraps the Chromium BackgroundFetchManager API so an application can preload an archive on idle…
- prefetch — The prefetch module wraps the Chromium BackgroundFetchManager API so an application can preload an archive on idle…
preload — generatePreloadHints derives an ordered list of <link rel="preload"> hints from a packed manifest, and `injectPrelo…
- preload — generatePreloadHints derives an ordered list of <link rel="preload"> hints from a packed manifest, and `injectPrelo…
range-response — RFC 7233 §2.1 single-range Response builder for packed-resource delivery from the Service Worker. Browsers ask for ra…
- range-response — RFC 7233 §2.1 single-range Response builder for packed-resource delivery from the Service Worker. Browsers ask for ra…
runtime — runtime.ts centralises the three injectable platform primitives (Clock, MonotonicClock, Rng) that every product…
- runtime — runtime.ts centralises the three injectable platform primitives (Clock, MonotonicClock, Rng) that every product…
service-worker — service-worker.ts is the production Service Worker entrypoint exposed via the /service-worker subpath. Its only pub…
- service-worker — service-worker.ts is the production Service Worker entrypoint exposed via the /service-worker subpath. Its only pub…
- sw-shim — sw-shim.ts provides createServiceWorkerShim(), a hand-rolled in-memory implementation of ServiceWorkerGlobalScope…
signature — signature.ts is the Ed25519 signature-verification gate run by the loader before any packed bytes are handed to `Unpa…
- signature — signature.ts is the Ed25519 signature-verification gate run by the loader before any packed bytes are handed to `Unpa…
singleton — singleton.ts exposes the module-level shared PackedResourceManager instance behind the `@suaveplan/packer-browser/s…
- singleton — singleton.ts exposes the module-level shared PackedResourceManager instance behind the `@suaveplan/packer-browser/s…
cross-origin — registerCrossOriginPackedResourceServiceWorker lets an application register a packed-resource Service Worker hosted o…
register-service-worker — register-service-worker.ts collects four lifecycle helpers exposed via the /utils subpath: `registerPackedResourceS…

Install

bun add @suaveplan/packer-browser

Quick start

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:

import { packedResourceManager } from "@suaveplan/packer-browser/singleton";
const url = await packedResourceManager.load("/banner.packed");

Modules

error-codes — PACKER_BROWSER_CODES + PackerBrowserError.
i18n/messages — MessageResolver catalog.
runtime/runtime — injectable Clock / Rng.
observability/observability — OTel counters + histogram.
flags/flags — @suaveplan/feature-flags slot.
signature/signature — verifyArchiveSignature (Ed25519).
cache/cache — PackedResourceCache LRU + ref-count.
loader/loader — PackedResourceLoader fetch / verify / unpack.
manager/manager — PackedResourceManager lifecycle façade + factory.
service-worker/service-worker — production SW entrypoint.
service-worker/sw-shim — hand-rolled ServiceWorkerGlobalScope shim for unit tests.
utils/register-service-worker — SW lifecycle helpers.
singleton — 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.