@piyawat37/performance-overlay 0.1.0 → 0.1.2

package/README.md

@@ -1,17 +1,58 @@
-# React performance overlay
+# Performance overlay
 
-A small, opt-in browser performance overlay. React 18 or 19 is a peer dependency.
+An opt-in browser diagnostic overlay for any JavaScript application, with a React 18/19 adapter. Import the component and styles in React:
 
 ```tsx
-import { PerformanceOverlay } from "@env-platform/performance-overlay";
-import "@env-platform/performance-overlay/style.css";
+import { PerformanceOverlay } from "@piyawat37/performance-overlay";
+import "@piyawat37/performance-overlay/style.css";
 
-// Vite example: the host app decides when the overlay is available.
 <PerformanceOverlay enabled={import.meta.env.DEV} />
 ```
 
-`enabled` defaults to `false`; when false, the component renders nothing and collects no measurements. Pass any boolean expression, such as a feature flag or an environment check supplied by the host bundler. `defaultOpen` defaults to `false` and sets the initial expanded state. The user can expand or collapse it; collection stops while collapsed.
+### JavaScript, Vue, Angular and other frameworks
 
-The overlay samples frame rate, JavaScript heap, DOM element count, and long tasks. Heap is a non-standard browser API, and long tasks are not available in every browser. FPS depends on display refresh rate and may be throttled in background tabs. These are diagnostic estimates, not CPU utilization. Measurements stay in the browser and include the overlay's own overhead. This package does not send data anywhere.
+The vanilla entry point does not depend on React. Import the stylesheet once using your bundler, mount after `document.body` is available, and destroy the overlay when your app or component is disposed:
 
-Build with `npm install && npm run build` in this directory. Publish only after choosing and verifying the package name, scope, and registry.
+```ts
+import { mountPerformanceOverlay } from "@piyawat37/performance-overlay/vanilla";
+import "@piyawat37/performance-overlay/style.css";
+
+const overlay = mountPerformanceOverlay({ enabled: import.meta.env.DEV });
+// Later: overlay.setEnabled(true) or overlay.setEnabled(false);
+// On teardown: overlay.destroy();
+```
+
+Use your own framework's environment flag instead of `import.meta.env.DEV` where applicable. Mount in the browser (for example Vue `onMounted` or Angular `ngAfterViewInit`), and call `destroy()` when unmounting. For custom integrations, `@piyawat37/performance-overlay/core` exports `observePerformance`, `snapshotDom`, `groupChildren`, `assess`, and threshold types. `observePerformance(callback)` returns a stop function. The React adapter keeps the original root import API. React and React DOM are optional peer dependencies; React applications must provide React.
+
+`enabled` defaults to `false`. When disabled or collapsed, sampling stops. `defaultOpen` sets the initial expanded state. Sampling pauses in a hidden tab. Measurements remain in the browser; nothing is sent elsewhere.
+
+The overlay shows OK, Watch, Investigate, or Unavailable, with suggested investigation steps for Watch and Investigate. It reports FPS, JavaScript heap, DOM element count, and the longest long task and number of long tasks in each sampling interval. A long task occupies the main thread for at least 50 ms; this count and duration are not CPU usage. The overlay cannot measure system CPU or GPU usage. Heap is a non-standard browser API, not total RAM; long tasks and heap are unavailable in some browsers. Sampling and the overlay itself add overhead.
+
+Default thresholds are **illustrative starting points**, not universal limits. FPS depends on display refresh rates, throttling and power modes; heap and DOM count depend on the app and hardware. Measure a baseline and adjust the thresholds for each app. A long task can be significant even when no critical status appears. Development builds can differ from production.
+
+| Metric | Watch | Investigate |
+| --- | --- | --- |
+| FPS | below 45 | 25 or below |
+| JS heap | 200 MB or more | 400 MB or more |
+| DOM elements | 1,500 or more | 3,000 or more |
+| Longest long task | 50 ms or more | 200 ms or more |
+
+Override thresholds with whole `{ warning, critical }` pairs. FPS is lower-is-worse; the others are higher-is-worse. Use finite positive values and make the critical threshold lower than warning for FPS, higher than warning for other metrics.
+
+```tsx
+<PerformanceOverlay
+  enabled={import.meta.env.DEV}
+  thresholds={{
+    fps: { warning: 45, critical: 25 },
+    heapMb: { warning: 300, critical: 600 },
+    nodes: { warning: 2000, critical: 4000 },
+    longTaskMs: { warning: 50, critical: 200 },
+  }}
+/>
+```
+
+To develop the package: `npm install`, `npm run build`, then `node --test test/*.test.mjs`.
+
+### Explore the DOM tree
+
+Select **Explore DOM tree** under DOM elements to capture a snapshot and navigate from `document body` through child groups. Siblings with the same tag, role and ID are grouped; counts include those elements and all their descendants. Each group shows its share of its parent group. Select **Explore** to drill down, a breadcrumb to go back, and **Highlight** to outline up to 50 connected and visible elements. Use **Refresh DOM scan** after the page changes. The overlay is excluded from counts. The snapshot counts hidden descendants and does not include shadow roots or iframe documents. A large group is a lead to investigate, not proof that it is slow.

package/dist/PerformanceOverlay.d.ts

@@ -1,5 +1,4 @@
-export type PerformanceOverlayProps = {
-    enabled?: boolean;
-    defaultOpen?: boolean;
-};
-export declare function PerformanceOverlay({ enabled, defaultOpen, }: PerformanceOverlayProps): import("react").JSX.Element | null;
+import type { OverlayOptions } from "./vanilla.js";
+export type PerformanceOverlayProps = OverlayOptions;
+/** React adapter for the framework-independent overlay. */
+export declare function PerformanceOverlay({ enabled, defaultOpen, thresholds }: PerformanceOverlayProps): null;

package/dist/PerformanceOverlay.js

@@ -1,53 +1,13 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useState } from "react";
-export function PerformanceOverlay({ enabled = false, defaultOpen = false, }) {
-    const [open, setOpen] = useState(defaultOpen);
-    const [sample, setSample] = useState(null);
+import { useEffect, useRef } from "react";
+import { mountPerformanceOverlay } from "./vanilla.js";
+/** React adapter for the framework-independent overlay. */
+export function PerformanceOverlay({ enabled = false, defaultOpen = false, thresholds }) {
+    const handle = useRef(null);
     useEffect(() => {
-        if (!enabled || !open)
-            return;
-        let frames = 0;
-        let frameId = 0;
-        let last = performance.now();
-        let longTasks = 0;
-        const tick = () => {
-            frames += 1;
-            frameId = requestAnimationFrame(tick);
-        };
-        frameId = requestAnimationFrame(tick);
-        let observer;
-        if (typeof PerformanceObserver !== "undefined" &&
-            PerformanceObserver.supportedEntryTypes?.includes("longtask")) {
-            observer = new PerformanceObserver((list) => {
-                longTasks += list.getEntries().length;
-            });
-            observer.observe({ entryTypes: ["longtask"] });
-        }
-        const timer = window.setInterval(() => {
-            const now = performance.now();
-            const memory = performance.memory;
-            setSample({
-                fps: Math.round((frames * 1000) / (now - last)),
-                heap: memory ? `${(memory.usedJSHeapSize / 1048576).toFixed(0)} MB` : "Unavailable",
-                nodes: document.getElementsByTagName("*").length,
-                longTasks,
-            });
-            frames = 0;
-            longTasks = 0;
-            last = now;
-        }, 1000);
-        return () => {
-            cancelAnimationFrame(frameId);
-            clearInterval(timer);
-            observer?.disconnect();
-        };
-    }, [enabled, open]);
-    if (!enabled)
-        return null;
-    return (_jsxs("aside", { className: "dev-performance", "aria-label": "Development performance monitor", children: [_jsx("button", { type: "button", className: "dev-performance__toggle", "aria-expanded": open, onClick: () => setOpen(!open), children: open ? "Hide performance" : "Performance" }), open && (_jsxs("div", { className: "dev-performance__body", children: [_jsxs("div", { children: [_jsx("span", { children: "Frame rate" }), _jsx("strong", { children: sample ? `${sample.fps} FPS` : "—" })] }), _jsxs("div", { children: [_jsx("span", { children: "JS heap" }), _jsx("strong", { children: sample?.heap ?? "—" })] }), _jsxs("div", { children: [_jsx("span", { children: "DOM elements" }), _jsx("strong", { children: sample?.nodes.toLocaleString() ?? "—" })] }), _jsxs("div", { children: [_jsx("span", { children: "Long tasks / sec" }), _jsx("strong", { children: sample
-                                    ? typeof PerformanceObserver !== "undefined" &&
-                                        PerformanceObserver.supportedEntryTypes?.includes("longtask")
-                                        ? sample.longTasks
-                                        : "Unavailable"
-                                    : "—" })] }), _jsx("small", { children: "Heap and long tasks depend on browser support" })] }))] }));
+        const overlay = mountPerformanceOverlay({ defaultOpen, thresholds });
+        handle.current = overlay;
+        return () => { handle.current = null; overlay.destroy(); };
+    }, [defaultOpen, thresholds]);
+    useEffect(() => { handle.current?.setEnabled(enabled); }, [enabled, defaultOpen, thresholds]);
+    return null;
 }

package/dist/core.d.ts

@@ -0,0 +1,13 @@
+export { assess, defaultThresholds } from "./thresholds.js";
+export type { OverlayThresholds, Threshold, Status } from "./thresholds.js";
+export { groupChildren, snapshotDom } from "./domTree.js";
+export type { DomGroup, DomSnapshot } from "./domTree.js";
+export type PerformanceSample = {
+    fps: number;
+    heapMb: number | null;
+    nodes: number;
+    longTasks: number | null;
+    maxTaskMs: number | null;
+};
+/** Starts sampling in the current document. Call the returned function to stop. */
+export declare function observePerformance(onSample: (sample: PerformanceSample) => void): () => void;

package/dist/core.js

@@ -0,0 +1,30 @@
+export { assess, defaultThresholds } from "./thresholds.js";
+export { groupChildren, snapshotDom } from "./domTree.js";
+/** Starts sampling in the current document. Call the returned function to stop. */
+export function observePerformance(onSample) {
+    let frames = 0;
+    let last = performance.now();
+    let longTasks = 0;
+    let maxTaskMs = 0;
+    let frameId = 0;
+    const tick = () => { frames++; frameId = requestAnimationFrame(tick); };
+    frameId = requestAnimationFrame(tick);
+    const supported = typeof PerformanceObserver !== "undefined" && PerformanceObserver.supportedEntryTypes?.includes("longtask");
+    const observer = supported ? new PerformanceObserver((list) => {
+        for (const entry of list.getEntries()) {
+            longTasks++;
+            maxTaskMs = Math.max(maxTaskMs, entry.duration);
+        }
+    }) : undefined;
+    observer?.observe({ entryTypes: ["longtask"] });
+    const timer = window.setInterval(() => {
+        const now = performance.now();
+        const memory = performance.memory;
+        onSample({ fps: Math.round(frames * 1000 / (now - last)), heapMb: memory ? memory.usedJSHeapSize / 1048576 : null, nodes: document.getElementsByTagName("*").length, longTasks: supported ? longTasks : null, maxTaskMs: supported ? maxTaskMs : null });
+        frames = 0;
+        longTasks = 0;
+        maxTaskMs = 0;
+        last = now;
+    }, 1000);
+    return () => { cancelAnimationFrame(frameId); clearInterval(timer); observer?.disconnect(); };
+}

package/dist/domTree.d.ts

@@ -0,0 +1,12 @@
+export type DomGroup = {
+    label: string;
+    elements: Element[];
+    count: number;
+    parentCount: number;
+};
+export type DomSnapshot = {
+    counts: Map<Element, number>;
+    roots: DomGroup[];
+};
+export declare function groupChildren(elements: Element[], counts: Map<Element, number>, parentCount: number): DomGroup[];
+export declare function snapshotDom(body: Element): DomSnapshot;

package/dist/domTree.js

@@ -0,0 +1,36 @@
+function label(element) {
+    const id = element.id ? `#${element.id}` : "";
+    const role = element.getAttribute("role");
+    return `${element.tagName.toLowerCase()}${id}${role ? ` [${role}]` : ""}`;
+}
+export function groupChildren(elements, counts, parentCount) {
+    const groups = new Map();
+    for (const parent of elements) {
+        for (const child of Array.from(parent.children)) {
+            const count = counts.get(child);
+            if (!count)
+                continue;
+            // Group siblings by tag and role; IDs remain separate to preserve identifiable targets.
+            const name = label(child);
+            const group = groups.get(name) ?? { label: name, elements: [], count: 0, parentCount };
+            group.elements.push(child);
+            group.count += count;
+            groups.set(name, group);
+        }
+    }
+    return Array.from(groups.values()).sort((a, b) => b.count - a.count);
+}
+export function snapshotDom(body) {
+    const all = Array.from(body.querySelectorAll("*"));
+    const counts = new Map();
+    for (let index = all.length - 1; index >= 0; index--) {
+        const element = all[index];
+        if (element.closest("[data-performance-overlay]"))
+            continue;
+        const count = (counts.get(element) ?? 0) + 1;
+        counts.set(element, count);
+        if (element.parentElement)
+            counts.set(element.parentElement, (counts.get(element.parentElement) ?? 0) + count);
+    }
+    return { counts, roots: groupChildren([body], counts, counts.get(body) ?? 0) };
+}

package/dist/index.d.ts

@@ -1,2 +1,4 @@
-export type { PerformanceOverlayProps } from "./PerformanceOverlay.js";
 export { PerformanceOverlay } from "./PerformanceOverlay.js";
+export type { PerformanceOverlayProps } from "./PerformanceOverlay.js";
+export { defaultThresholds } from "./thresholds.js";
+export type { OverlayThresholds, Threshold } from "./thresholds.js";

package/dist/index.js

@@ -1 +1,2 @@
 export { PerformanceOverlay } from "./PerformanceOverlay.js";
+export { defaultThresholds } from "./thresholds.js";

package/dist/style.css

@@ -45,3 +45,22 @@
   margin-top: 8px;
   color: #c5d1dc;
 }
+.dev-performance { width: min(320px, calc(100vw - 24px)); max-height: calc(100vh - 24px); overflow-y: auto; }
+.dev-performance__body .dev-performance__metric { display: block; padding: 6px 0; border-top: 1px solid #536170; }
+.dev-performance__body .dev-performance__line { display: flex; }
+.dev-performance__status { font-weight: 700; }
+.dev-performance__status--ok { color: #8ce5b0; }
+.dev-performance__status--warning { color: #ffdb8a; }
+.dev-performance__status--critical { color: #ffaaaa; }
+.dev-performance__status--unavailable { color: #c5d1dc; }
+.dev-performance__body p { margin: 4px 0; color: #f5f7fa; }
+.dev-performance__body .dev-performance__inspector { display: block; padding: 0; }
+.dev-performance__inspector button { display: block; width: 100%; margin-top: 5px; padding: 6px 8px; border: 1px solid #718297; border-radius: 4px; color: #f5f7fa; background: #26394a; font: inherit; text-align: left; overflow-wrap: anywhere; cursor: pointer; }
+.dev-performance__inspector button:hover, .dev-performance__inspector button[aria-pressed="true"] { background: #38546b; }
+.dev-performance__inspector button:focus-visible { outline: 2px solid #8bc6ff; outline-offset: 2px; }
+.dev-performance__highlight { position: fixed; z-index: 2147483646; box-sizing: border-box; border: 3px solid #ffbd45; background: #ffbd4533; pointer-events: none; }
+.dev-performance__body .dev-performance__path { display: flex; flex-wrap: wrap; justify-content: flex-start; gap: 4px; padding: 4px 0; }
+.dev-performance__path button { display: inline-block; width: auto; margin: 0; }
+.dev-performance__body .dev-performance__group { display: block; border-top: 1px solid #536170; padding: 8px 0; overflow-wrap: anywhere; }
+.dev-performance__body .dev-performance__actions { display: flex; justify-content: flex-start; gap: 6px; padding: 0; }
+.dev-performance__actions button { width: auto; }

package/dist/thresholds.d.ts

@@ -0,0 +1,14 @@
+export type Threshold = {
+    warning: number;
+    critical: number;
+};
+export type OverlayThresholds = {
+    fps: Threshold;
+    heapMb: Threshold;
+    nodes: Threshold;
+    longTaskMs: Threshold;
+};
+export type Status = "ok" | "warning" | "critical" | "unavailable";
+/** Starting points only; tune them for the app, devices and workload. */
+export declare const defaultThresholds: OverlayThresholds;
+export declare function assess(value: number | null, threshold: Threshold, lowerIsWorse?: boolean): Status;

package/dist/thresholds.js

@@ -0,0 +1,16 @@
+/** Starting points only; tune them for the app, devices and workload. */
+export const defaultThresholds = {
+    fps: { warning: 45, critical: 25 },
+    heapMb: { warning: 200, critical: 400 },
+    nodes: { warning: 1500, critical: 3000 },
+    longTaskMs: { warning: 50, critical: 200 },
+};
+export function assess(value, threshold, lowerIsWorse = false) {
+    if (value === null || !Number.isFinite(value))
+        return "unavailable";
+    if (lowerIsWorse ? value <= threshold.critical : value >= threshold.critical)
+        return "critical";
+    if (lowerIsWorse ? value < threshold.warning : value >= threshold.warning)
+        return "warning";
+    return "ok";
+}

package/dist/vanilla.d.ts

@@ -0,0 +1,12 @@
+import type { OverlayThresholds } from "./core.js";
+export type OverlayOptions = {
+    enabled?: boolean;
+    defaultOpen?: boolean;
+    thresholds?: Partial<OverlayThresholds>;
+};
+export type OverlayHandle = {
+    setEnabled(enabled: boolean): void;
+    destroy(): void;
+};
+/** Mount an overlay in any browser app. Import the package stylesheet separately. */
+export declare function mountPerformanceOverlay(options?: OverlayOptions): OverlayHandle;

package/dist/vanilla.js

@@ -0,0 +1,166 @@
+import { assess, defaultThresholds, groupChildren, observePerformance, snapshotDom } from "./core.js";
+/** Mount an overlay in any browser app. Import the package stylesheet separately. */
+export function mountPerformanceOverlay(options = {}) {
+    let enabled = options.enabled ?? false;
+    let open = options.defaultOpen ?? false;
+    let destroyed = false;
+    let stopSampling;
+    let sample = null;
+    let snapshot = null;
+    let path = [];
+    let highlighted = null;
+    let boxes = [];
+    const limits = { ...defaultThresholds, ...options.thresholds };
+    const root = document.createElement("aside");
+    root.className = "dev-performance";
+    root.setAttribute("data-performance-overlay", "");
+    root.setAttribute("aria-label", "Development performance monitor");
+    const toggle = document.createElement("button");
+    toggle.type = "button";
+    toggle.className = "dev-performance__toggle";
+    const body = document.createElement("div");
+    body.className = "dev-performance__body";
+    const metrics = document.createElement("div");
+    const inspector = document.createElement("div");
+    inspector.className = "dev-performance__inspector";
+    const note = document.createElement("small");
+    note.textContent = "Indicative thresholds, not CPU/GPU usage. FPS varies by device; heap and task support vary by browser.";
+    body.append(metrics, inspector, note);
+    root.append(toggle, body);
+    const button = (text, action) => {
+        const el = document.createElement("button");
+        el.type = "button";
+        el.textContent = text;
+        el.addEventListener("click", action);
+        return el;
+    };
+    const clearHighlights = () => { boxes.forEach((box) => box.remove()); boxes = []; highlighted = null; };
+    const updateHighlights = () => {
+        boxes.forEach((box) => box.remove());
+        boxes = [];
+        if (!highlighted)
+            return;
+        for (const element of highlighted.elements.filter((item) => item.isConnected).slice(0, 50)) {
+            const rect = element.getBoundingClientRect();
+            if (!rect.width || !rect.height)
+                continue;
+            const box = document.createElement("div");
+            box.className = "dev-performance__highlight";
+            box.setAttribute("data-performance-overlay", "");
+            box.setAttribute("aria-hidden", "true");
+            Object.assign(box.style, { top: `${rect.top}px`, left: `${rect.left}px`, width: `${rect.width}px`, height: `${rect.height}px` });
+            document.body.append(box);
+            boxes.push(box);
+        }
+    };
+    const renderInspector = () => {
+        inspector.replaceChildren(button(snapshot ? "Refresh DOM scan" : "Explore DOM tree", () => { clearHighlights(); path = []; snapshot = snapshotDom(document.body); renderInspector(); }));
+        if (!snapshot)
+            return;
+        const info = document.createElement("p");
+        info.textContent = "Choose a group to explore its children. Counts include each element and its descendants. Large groups may not be slow.";
+        inspector.append(info);
+        const crumbs = document.createElement("div");
+        crumbs.className = "dev-performance__path";
+        crumbs.setAttribute("aria-label", "DOM path");
+        crumbs.append(button("document body", () => { path = []; clearHighlights(); renderInspector(); }));
+        path.forEach((group, index) => crumbs.append(button(`› ${group.label}${group.elements.length > 1 ? ` × ${group.elements.length}` : ""}`, () => { path = path.slice(0, index + 1); clearHighlights(); renderInspector(); })));
+        inspector.append(crumbs);
+        const current = path[path.length - 1];
+        const groups = current ? groupChildren(current.elements, snapshot.counts, current.count) : snapshot.roots;
+        if (current) {
+            const count = document.createElement("p");
+            count.textContent = `${current.count.toLocaleString()} elements · ${current.elements.length.toLocaleString()} matching nodes`;
+            inspector.append(count);
+        }
+        if (!groups.length) {
+            const empty = document.createElement("p");
+            empty.textContent = "No child elements in this snapshot.";
+            inspector.append(empty);
+        }
+        for (const group of groups) {
+            const row = document.createElement("div");
+            row.className = "dev-performance__group";
+            const label = document.createElement("strong");
+            label.textContent = `${group.label}${group.elements.length > 1 ? ` × ${group.elements.length}` : ""}`;
+            const count = document.createElement("span");
+            count.textContent = `${group.count.toLocaleString()} elements · ${group.parentCount ? Math.round(group.count / group.parentCount * 100) : 0}% of parent`;
+            const actions = document.createElement("div");
+            actions.className = "dev-performance__actions";
+            actions.append(button("Highlight", () => { clearHighlights(); highlighted = group; const first = group.elements.find((item) => item.isConnected && item.getBoundingClientRect().width > 0 && item.getBoundingClientRect().height > 0); first?.scrollIntoView({ block: "nearest", inline: "nearest" }); updateHighlights(); renderInspector(); }), button("Explore", () => { clearHighlights(); path.push(group); renderInspector(); }));
+            row.append(label, document.createElement("br"), count, actions);
+            inspector.append(row);
+        }
+        if (highlighted) {
+            const msg = document.createElement("p");
+            msg.textContent = "Highlighting up to 50 connected elements. ";
+            msg.append(button("Clear highlight", () => { clearHighlights(); renderInspector(); }));
+            inspector.append(msg);
+        }
+    };
+    const renderMetrics = () => {
+        const rows = [
+            { label: "Frame rate", value: sample ? `${sample.fps} FPS` : "—", status: assess(sample?.fps ?? null, limits.fps, true), advice: "Check Performance recording for slow frames, rendering and animations. Compare with this device’s refresh rate." },
+            { label: "JS heap", value: sample?.heapMb != null ? `${sample.heapMb.toFixed(0)} MB` : "Unavailable", status: assess(sample?.heapMb ?? null, limits.heapMb), advice: "Compare heap snapshots after repeating the same action; inspect retained objects and detached DOM nodes." },
+            { label: "DOM elements", value: sample ? sample.nodes.toLocaleString() : "—", status: assess(sample?.nodes ?? null, limits.nodes), advice: "Inspect large lists, tables and hidden content; consider pagination or virtualization." },
+            { label: "Longest task / sec", value: sample?.maxTaskMs != null ? `${sample.maxTaskMs.toFixed(0)} ms (${sample.longTasks})` : "Unavailable", status: assess(sample?.maxTaskMs ?? null, limits.longTaskMs), advice: "Record Performance and inspect the longest main-thread tasks and scripts." },
+        ];
+        rows.forEach((row, index) => {
+            let item = metrics.children.item(index);
+            if (!item) {
+                item = document.createElement("div");
+                item.className = "dev-performance__metric";
+                const line = document.createElement("div");
+                line.className = "dev-performance__line";
+                line.append(document.createElement("span"), document.createElement("strong"));
+                const status = document.createElement("span");
+                const advice = document.createElement("p");
+                advice.className = "dev-performance__advice";
+                item.append(line, status, advice);
+                if (index === 2)
+                    item.append(inspector);
+                metrics.append(item);
+            }
+            const line = item.children[0];
+            line.children[0].textContent = row.label;
+            line.children[1].textContent = row.value;
+            const status = item.children[1];
+            status.className = `dev-performance__status dev-performance__status--${row.status}`;
+            status.textContent = row.status === "ok" ? "OK" : row.status === "warning" ? "Watch" : row.status === "critical" ? "Investigate" : "Unavailable";
+            const advice = item.children[2];
+            advice.textContent = row.advice;
+            advice.hidden = row.status !== "warning" && row.status !== "critical";
+        });
+    };
+    const sync = () => {
+        stopSampling?.();
+        stopSampling = undefined;
+        if (!enabled || !open || document.hidden) {
+            sample = null;
+            clearHighlights();
+        }
+        if (enabled && open && !document.hidden)
+            stopSampling = observePerformance((next) => { sample = next; renderMetrics(); });
+        root.hidden = !enabled;
+        toggle.textContent = open ? "Hide performance" : "Performance";
+        toggle.setAttribute("aria-expanded", String(open));
+        body.hidden = !open;
+        renderMetrics();
+    };
+    toggle.addEventListener("click", () => { open = !open; sync(); });
+    const visibility = () => sync();
+    document.addEventListener("visibilitychange", visibility);
+    window.addEventListener("scroll", updateHighlights, true);
+    window.addEventListener("resize", updateHighlights);
+    document.body.append(root);
+    renderInspector();
+    sync();
+    return {
+        setEnabled(value) { if (!destroyed && enabled !== value) {
+            enabled = value;
+            sync();
+        } },
+        destroy() { if (destroyed)
+            return; destroyed = true; stopSampling?.(); clearHighlights(); document.removeEventListener("visibilitychange", visibility); window.removeEventListener("scroll", updateHighlights, true); window.removeEventListener("resize", updateHighlights); root.remove(); },
+    };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@piyawat37/performance-overlay",
-  "version": "0.1.0",
-  "description": "A configurable client-side performance overlay for React applications",
+  "version": "0.1.2",
+  "description": "A framework-independent browser performance overlay with a React adapter",
   "type": "module",
   "files": [
     "dist",
@@ -12,7 +12,15 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
-    "./style.css": "./dist/style.css"
+    "./style.css": "./dist/style.css",
+    "./vanilla": {
+      "types": "./dist/vanilla.d.ts",
+      "import": "./dist/vanilla.js"
+    },
+    "./core": {
+      "types": "./dist/core.d.ts",
+      "import": "./dist/core.js"
+    }
   },
   "sideEffects": [
     "**/*.css"
@@ -22,10 +30,23 @@
     "prepare": "npm run build"
   },
   "peerDependencies": {
-    "react": ">=18 <20"
+    "react": ">=18 <20",
+    "react-dom": ">=18 <20"
   },
   "devDependencies": {
     "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "jsdom": "^31.0.0",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1",
     "typescript": "^5.9.3"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
   }
 }