# `diagnostics` — development-time overlay for the packed-resource manager

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->

## Purpose

`createDiagnosticsOverlay` produces a development-time overlay that
displays live cache statistics and a tail of recent events from a
`PackedResourceManager`. The overlay is subscribe-only — it never
mutates the manager — and renders a single `<div>` with inline styles
so it can be dropped onto any page without a stylesheet.

This module is PACKER-BROWSER-21's production surface. It is
feature-detected: when the runtime has no `document`, `mount` returns a
safe no-op disposer so the helper can be imported unconditionally from
universal code paths.

## Features

- Live cache size from `manager.getCache().size()`
- Hit / miss counters with a rolling hit-ratio
- Bounded event ring (default 50) over `load`, `error`, `cacheHit`,
  `cacheMiss`, `cacheEvict`
- Subscribe-only — no manager state is mutated
- Disposer removes the element and unsubscribes every listener
- Mountable into a custom `ParentNode`

## Usage: Basic

```ts
import { createDiagnosticsOverlay } from "@suaveplan/packer-browser/diagnostics";
import { createPackedResourceManager } from "@suaveplan/packer-browser";

const manager = createPackedResourceManager();
const overlay = createDiagnosticsOverlay(manager);
const dispose = overlay.mount(); // attaches to document.body
// On teardown:
dispose();
```

## Usage: Advanced

```ts
const overlay = createDiagnosticsOverlay(manager, {
    historyLimit: 200,
    now: () => performance.now(),
    document: shadowRoot.ownerDocument,
});
const dispose = overlay.mount(shadowRoot);
console.log(overlay.getSnapshot());
```

## API Reference

- `createDiagnosticsOverlay(manager, opts?): DiagnosticsOverlay`
  - `opts.document?: Document` — DOM injection.
  - `opts.historyLimit?: number` — ring size. Default `50`.
  - `opts.now?: () => number` — clock for event timestamps. Default `Date.now`.

- `DiagnosticsOverlay.mount(parent?: ParentNode): () => void` — returns
  a disposer that removes the element and unsubscribes.
- `DiagnosticsOverlay.getSnapshot(): DiagnosticsSnapshot` — read-only.

## Implementation Notes

- The overlay subscribes to the manager's `TinyEmitter` events
  immediately on construction, BEFORE `mount` is called, so callers
  who only want the snapshot (no DOM) can still observe events. The
  disposer returned from `mount` is responsible for unsubscribing.
- The rendered element carries `data-packer-browser-diagnostics` so
  tests can locate it without relying on inline class hooks.
- Hits and misses are counted on the overlay side (not from the
  manager's OTel counters) so the helper does not require an
  observability bundle.
- The overlay never calls `manager.load`, `manager.preload`, or
  `manager.release`; the only manager surface it reads is `getCache()`
  and the `on(...)` subscriber.