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

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

(no submodules)

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

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

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.