@piyawat37/performance-overlay 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,17 @@
-# Temporary Holding Version
+# React performance overlay
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A small, opt-in browser performance overlay. React 18 or 19 is a peer dependency.
+
+```tsx
+import { PerformanceOverlay } from "@env-platform/performance-overlay";
+import "@env-platform/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.
+
+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.
+
+Build with `npm install && npm run build` in this directory. Publish only after choosing and verifying the package name, scope, and registry.

package/dist/PerformanceOverlay.d.ts

@@ -0,0 +1,5 @@
+export type PerformanceOverlayProps = {
+    enabled?: boolean;
+    defaultOpen?: boolean;
+};
+export declare function PerformanceOverlay({ enabled, defaultOpen, }: PerformanceOverlayProps): import("react").JSX.Element | null;

package/dist/PerformanceOverlay.js

@@ -0,0 +1,53 @@
+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);
+    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" })] }))] }));
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export type { PerformanceOverlayProps } from "./PerformanceOverlay.js";
+export { PerformanceOverlay } from "./PerformanceOverlay.js";

package/dist/index.js

@@ -0,0 +1 @@
+export { PerformanceOverlay } from "./PerformanceOverlay.js";

package/dist/style.css

@@ -0,0 +1,47 @@
+.dev-performance {
+  position: fixed;
+  z-index: 2147483647;
+  right: 12px;
+  top: 12px;
+  width: min(230px, calc(100vw - 24px));
+  color: #f5f7fa;
+  background: #17202b;
+  border-radius: 8px;
+  box-shadow: 0 4px 16px #0004;
+  font:
+    12px / 1.5 system-ui,
+    sans-serif;
+}
+.dev-performance__toggle {
+  width: 100%;
+  padding: 8px 12px;
+  color: inherit;
+  background: transparent;
+  border: 0;
+  border-radius: inherit;
+  text-align: left;
+  font: inherit;
+  font-weight: 700;
+  cursor: pointer;
+}
+.dev-performance__toggle:focus-visible {
+  outline: 2px solid #8bc6ff;
+  outline-offset: 2px;
+}
+.dev-performance__body {
+  padding: 0 12px 10px;
+}
+.dev-performance__body div {
+  display: flex;
+  justify-content: space-between;
+  gap: 12px;
+  padding: 2px 0;
+}
+.dev-performance__body strong {
+  font-variant-numeric: tabular-nums;
+}
+.dev-performance__body small {
+  display: block;
+  margin-top: 8px;
+  color: #c5d1dc;
+}

package/package.json

@@ -1,6 +1,31 @@
 {
   "name": "@piyawat37/performance-overlay",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "A configurable client-side performance overlay for React applications",
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./style.css": "./dist/style.css"
+  },
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json && cp src/performance-overlay.css dist/style.css",
+    "prepare": "npm run build"
+  },
+  "peerDependencies": {
+    "react": ">=18 <20"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "typescript": "^5.9.3"
+  }
+}