first commit

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

@@ -0,0 +1,79 @@
+# `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.