first commit

docs/foundation/data/packer-browser/src/singleton/singleton.md

@@ -0,0 +1,67 @@
+# `singleton`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+`singleton.ts` exposes the module-level shared
+`PackedResourceManager` instance behind the
+`@suaveplan/packer-browser/singleton` subpath. The default `.`
+entrypoint deliberately **omits** this export so consumers that build
+their own manager (e.g. with a custom `fetch`, observability bundle,
+or feature-flag provider) pay zero import-time cost for the global
+instance. Adopters that want a shared instance opt in explicitly.
+
+## Features
+
+- Eager construction at module load via `createPackedResourceManager()`
+  with platform defaults — `globalThis.fetch`, `URL.revokeObjectURL`,
+  no-op OTel providers, empty `MemoryProvider` flags.
+- Stable reference across imports — every consumer that imports the
+  symbol receives the same `PackedResourceManager` instance.
+- Lives at its own subpath so tree-shaking eliminates the singleton
+  (and its constructor cost) from bundles that do not import it.
+
+## Usage: Basic
+
+```ts
+import { packedResourceManager } from "@suaveplan/packer-browser/singleton";
+
+const blobUrl = await packedResourceManager.load("/banner.packed");
+img.src = blobUrl;
+```
+
+## Usage: Advanced
+
+```ts
+// In a tab that already loaded the singleton elsewhere, re-importing
+// returns the same instance and any registered listeners still fire.
+import { packedResourceManager } from "@suaveplan/packer-browser/singleton";
+
+const seen = new Set<string>();
+packedResourceManager.on("cacheHit", ({ url }) => seen.add(url));
+
+await packedResourceManager.load("/a.packed");
+await packedResourceManager.load("/a.packed");
+// seen now contains "/a.packed" — both calls observed the same
+// instance and its in-memory cache.
+```
+
+## API Reference
+
+- `packedResourceManager: PackedResourceManager` — module-singleton
+  instance constructed via
+  `createPackedResourceManager()` with no options.
+
+## Implementation Notes
+
+The construction call runs at import time, which means importing the
+subpath has a side effect: instantiating the cache, the loader, and
+the no-op OTel bundle. Packages declaring `sideEffects: false` are
+still tree-shake-safe at the consumer because the side effect is
+contained to this one module — bundlers (rollup, esbuild) drop the
+entire file when no symbol is imported from it. Adopters who need a
+zero-side-effect import are expected to use
+`createPackedResourceManager` from the default entry instead.