# `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.