@piyawat37/performance-overlay 0.1.0 → 0.1.1

package/README.md

@@ -1,17 +1,39 @@
 # React performance overlay
 
-A small, opt-in browser performance overlay. React 18 or 19 is a peer dependency.
+An opt-in browser diagnostic overlay for React 18 and 19. Import the component and styles:
 
 ```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.
+`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 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 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.
 
-Build with `npm install && npm run build` in this directory. Publish only after choosing and verifying the package name, scope, and registry.
+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`.

package/dist/PerformanceOverlay.d.ts

@@ -1,5 +1,7 @@
+import type { OverlayThresholds } from "./thresholds.js";
 export type PerformanceOverlayProps = {
     enabled?: boolean;
     defaultOpen?: boolean;
+    thresholds?: Partial<OverlayThresholds>;
 };
-export declare function PerformanceOverlay({ enabled, defaultOpen, }: PerformanceOverlayProps): import("react").JSX.Element | null;
+export declare function PerformanceOverlay({ enabled, defaultOpen, thresholds }: PerformanceOverlayProps): import("react").JSX.Element | null;

package/dist/PerformanceOverlay.js

@@ -1,53 +1,60 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useState } from "react";
-export function PerformanceOverlay({ enabled = false, defaultOpen = false, }) {
+import { assess, defaultThresholds } from "./thresholds.js";
+const advice = {
+    fps: "Check Performance recording for slow frames, rendering and animations. Compare with this device’s refresh rate.",
+    heap: "Compare heap snapshots after repeating the same action; inspect retained objects and detached DOM nodes.",
+    nodes: "Inspect large lists, tables and hidden content; consider pagination or virtualization.",
+    tasks: "Record Performance and inspect the longest main-thread tasks, scripts and React renders.",
+};
+export function PerformanceOverlay({ enabled = false, defaultOpen = false, thresholds }) {
     const [open, setOpen] = useState(defaultOpen);
     const [sample, setSample] = useState(null);
+    const [visible, setVisible] = useState(() => typeof document === "undefined" || !document.hidden);
+    const limits = { ...defaultThresholds, ...thresholds };
     useEffect(() => {
-        if (!enabled || !open)
+        const update = () => setVisible(!document.hidden);
+        document.addEventListener("visibilitychange", update);
+        return () => document.removeEventListener("visibilitychange", update);
+    }, []);
+    useEffect(() => {
+        if (!enabled || !open || !visible) {
+            setSample(null);
             return;
+        }
         let frames = 0;
-        let frameId = 0;
         let last = performance.now();
         let longTasks = 0;
-        const tick = () => {
-            frames += 1;
-            frameId = requestAnimationFrame(tick);
-        };
+        let maxTaskMs = 0;
+        let frameId = 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 supported = typeof PerformanceObserver !== "undefined" && PerformanceObserver.supportedEntryTypes?.includes("longtask");
+        const observer = supported ? new PerformanceObserver((list) => {
+            for (const entry of list.getEntries()) {
+                longTasks += 1;
+                maxTaskMs = Math.max(maxTaskMs, entry.duration);
+            }
+        }) : undefined;
+        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,
-            });
+            setSample({ 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();
-        };
-    }, [enabled, open]);
+        return () => { cancelAnimationFrame(frameId); clearInterval(timer); observer?.disconnect(); };
+    }, [enabled, open, visible]);
     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 rows = [
+        { key: "fps", label: "Frame rate", value: sample ? `${sample.fps} FPS` : "—", status: assess(sample?.fps ?? null, limits.fps, true) },
+        { key: "heap", label: "JS heap", value: sample?.heapMb != null ? `${sample.heapMb.toFixed(0)} MB` : "Unavailable", status: assess(sample?.heapMb ?? null, limits.heapMb) },
+        { key: "nodes", label: "DOM elements", value: sample ? sample.nodes.toLocaleString() : "—", status: assess(sample?.nodes ?? null, limits.nodes) },
+        { key: "tasks", label: "Longest task / sec", value: sample?.maxTaskMs != null ? `${sample.maxTaskMs.toFixed(0)} ms (${sample.longTasks})` : "Unavailable", status: assess(sample?.maxTaskMs ?? null, limits.longTaskMs) },
+    ];
+    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: [!visible && _jsx("p", { children: "Paused while this tab is hidden." }), rows.map((row) => _jsxs("div", { className: "dev-performance__metric", children: [_jsxs("div", { className: "dev-performance__line", children: [_jsx("span", { children: row.label }), _jsx("strong", { children: row.value })] }), _jsx("span", { className: `dev-performance__status dev-performance__status--${row.status}`, children: row.status === "ok" ? "OK" : row.status === "warning" ? "Watch" : row.status === "critical" ? "Investigate" : "Unavailable" }), (row.status === "warning" || row.status === "critical") && _jsx("p", { children: advice[row.key] })] }, row.key)), _jsx("small", { children: "Indicative thresholds, not CPU/GPU usage. FPS varies by device; heap and task support vary by browser." })] })] }));
 }

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,12 @@
   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; }

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@piyawat37/performance-overlay",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "A configurable client-side performance overlay for React applications",
   "type": "module",
   "files": [