react-dev-insight 1.0.0

package/README.md

@@ -0,0 +1,282 @@
+<div align="center">
+  <img src="https://raw.githubusercontent.com/santhoshkumar7300/react-dev-insight/main/assets/main-demo.gif" alt="React Dev Insight Demo" width="100%" />
+  
+  <br/>
+  
+  <h1>✨ React Dev Insight</h1>
+  
+  <p>
+    <strong>A lightning-fast, zero-overhead developer experience plugin for React.</strong>
+  </p>
+
+  <p>
+    <a href="https://www.npmjs.com/package/react-dev-insight"><img src="https://img.shields.io/npm/v/react-dev-insight?style=flat-square&color=2dd4bf" alt="NPM Version" /></a>
+    <a href="https://www.npmjs.com/package/react-dev-insight"><img src="https://img.shields.io/npm/dm/react-dev-insight?style=flat-square&color=6366f1" alt="NPM Downloads" /></a>
+    <a href="https://github.com/santhoshkumar7300/react-dev-insight/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/react-dev-insight?style=flat-square&color=ec4899" alt="License" /></a>
+    <img src="https://img.shields.io/badge/TypeScript-Ready-blue?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript Support" />
+  </p>
+</div>
+
+<br/>
+
+> **Stop guessing why your React app feels slow.**
+>
+> `react-dev-insight` is a lightweight, strictly development-only plugin that actively visualizes component rendering behavior right in your browser. Framed within a stunning modern glassmorphism UI, it transforms performance debugging from a terminal-diving chore into an intuitive, visual joy.
+
+---
+
+<br/>
+
+## 🌟 Why React Dev Insight?
+
+React performance debugging usually means reading through console logs or clicking through complex flame graphs. We built **React Dev Insight** to bring the insights directly to your UI.
+
+It runs passively while you build, instantly flagging anomalies, tracking render counts, and drawing the exact physical prop-drilling paths right on your screen.
+
+<br/>
+
+### Core Features
+
+- **💥 Visual Render Highlights:** See exactly _what_ renders and _when_ it renders with sleek, animated glowing boundaries.
+- **� The Cascade Trace (NEW):** Visually map out parent-to-child render cascading via glowing SVG bezier curves in real-time. Literally watch the chain reaction.
+- **🔍 Prop Diff Tooltips:** Hover over a highlight to instantly see the exact prop mutations that triggered the cycle.
+- **🚨 Thrash Detection:** Automatically flags components caught in frequent render loops (e.g., 3+ renders in <500ms) with a warning glow.
+- **🎛️ Glassmorphism Dashboard:** A beautiful, draggable floating control panel summarizing global render metrics and top offenders.
+- **🚀 Zero Production Bloat:** Aggressively tree-shakeable. In `NODE_ENV === 'production'`, it compiles down to absolutely nothing. Zero DOM bloat, zero overhead.
+
+<br/>
+
+---
+
+<br/>
+
+## 📸 See It In Action
+
+<div align="center">
+  <table>
+    <tr>
+      <td align="center">
+        <strong>Re-render Highlights</strong><br/><br/>
+        <img src="https://raw.githubusercontent.com/santhoshkumar7300/react-dev-insight/main/assets/rerender.gif" alt="Re-render Highlight" width="400"/>
+      </td>
+      <td align="center">
+        <strong>Render Badges</strong><br/><br/>
+        <img src="https://raw.githubusercontent.com/santhoshkumar7300/react-dev-insight/main/assets/badge.gif" alt="Render Badge" width="400"/>
+      </td>
+    </tr>
+    <tr>
+      <td align="center">
+        <br/><strong>Prop Diff Tooltip</strong><br/><br/>
+        <img src="https://raw.githubusercontent.com/santhoshkumar7300/react-dev-insight/main/assets/tooltip.gif" alt="Prop Diff Tooltip" width="400"/>
+      </td>
+      <td align="center">
+        <br/><strong>Mini Dashboard</strong><br/><br/>
+        <img src="https://raw.githubusercontent.com/santhoshkumar7300/react-dev-insight/main/assets/dashboard.gif" alt="Mini Dashboard" width="400"/>
+      </td>
+    </tr>
+  </table>
+</div>
+
+<br/>
+
+---
+
+<br/>
+
+## 📦 Installation
+
+```bash
+npm install react-dev-insight --save-dev
+```
+
+_(Also supports `yarn add -D` and `pnpm add -D`)_
+
+<br/>
+
+---
+
+<br/>
+
+## 🛠️ Usage
+
+### 1. The Global Provider
+
+Wrap your application root inside the `DevInsightProvider`.
+
+_Note: In production builds, this provider returns your `children` directly, causing zero performance or DOM overhead._
+
+```tsx
+import { DevInsightProvider } from "react-dev-insight";
+
+function App() {
+  return (
+    <DevInsightProvider>
+      <YourApp />
+    </DevInsightProvider>
+  );
+}
+```
+
+### 2. Tracking Components
+
+**Method A: `withDevInsight` HOC (Easiest)**
+
+Wrap any component to instantly track its render behavior.
+
+```tsx
+import React from "react";
+import { withDevInsight } from "react-dev-insight";
+
+const DashboardWidget = ({ data }) => {
+  return (
+    <div className="card">
+      <h3>{data.title}</h3>
+    </div>
+  );
+};
+
+// Optionally pass a custom display name for the dashboard leaderboard
+export default withDevInsight(DashboardWidget, "DashboardWidget");
+```
+
+**Method B: `useRenderTracker` Hook (Advanced)**
+
+For precise control, attach the returned `ref` to the outermost DOM element of your component.
+
+```tsx
+import React from "react";
+import { useRenderTracker } from "react-dev-insight";
+
+export const SettingsPanel = (props) => {
+  // Pass the component name, and the props to diff against
+  const ref = useRenderTracker<HTMLDivElement>("SettingsPanel", props);
+
+  return (
+    <div ref={ref} className="settings-container">
+      <h1>Settings</h1>
+    </div>
+  );
+};
+```
+
+<br/>
+
+---
+
+<br/>
+
+## 🧠 Performance Philosophy
+
+**"Do no harm."**
+
+Debugging tools shouldn't distort the very performance benchmarks they are trying to measure. `react-dev-insight` uses a completely decoupled architecture to ensure your app stays fast:
+
+1.  **O(1) Interception:** It intercepts props and state using ultra-fast shallow diffing and stores them in a memory-safe `WeakMap` to prevent memory leaks.
+2.  **Asynchronous Rendering:** The visual overlays are rendered in a topmost React `<Portal>` bound directly to `document.body`. We **never** pollute your application's DOM hierarchy with wrapper `div`s that break Grid or Flexbox layouts.
+3.  **Pure CSS Animations:** The glowing highlights and bounding boxes use hardware-accelerated CSS `transform` and `opacity` properties, offloading the work to the GPU and preventing main-thread blocking.
+
+<br/>
+
+---
+
+<br/>
+
+## 🆚 Comparisons
+
+### vs. `why-did-you-render`
+
+`why-did-you-render` is fantastic, but it forces you to dig through terminal logs to understand what happened. **React Dev Insight is a visual-first tool.** It brings the insights directly to your UI, making it instantly obvious which parts of your screen are thrashing.
+
+### vs. React DevTools Profiler
+
+The official Profiler is unmatched for deep-dive microscopic analysis. However, it requires you to actively record, click through flame graphs, and parse milliseconds. **React Dev Insight is passive and ambient.** Leave it running while you build, and it intuitively flags anomalies in real-time.
+
+<br/>
+
+---
+
+<br/>
+
+## 📚 API Reference
+
+### `<DevInsightProvider />`
+
+The outermost wrapper required to mount the visual overlay portal.
+
+- **Props:** `{ children: ReactNode }`
+
+### `withDevInsight(Component, [name])`
+
+A Higher-Order Component to track a specific React component.
+
+- **`Component`**: The React component to wrap.
+- **`name`** _(Optional)_: A string to identify the component in the dashboard. Defaults to the component's display name.
+
+### `useRenderTracker(name, props)`
+
+A hook for fine-grained tracking control.
+
+- **`name`**: String identifier for the component.
+- **`props`**: The component's props object (used for diffing).
+- **Returns**: A `React.RefObject` that _must_ be attached to the component's root DOM node.
+
+<br/>
+
+---
+
+<br/>
+
+## 🗺️ Roadmap
+
+- [ ] Support for tracking pure Context Consumer updates (bypassing props).
+- [ ] Integration with Next.js App Router RSCs (Client Boundaries).
+- [ ] Customizable theme injection (Dark/Light mode overriding).
+- [ ] Export render data to JSON format.
+
+<br/>
+
+---
+
+<br/>
+
+## 🤝 Contributing
+
+We welcome community contributions! Please read our [Contributing Guidelines](CONTRIBUTING.md) to get started.
+
+1.  Fork the repository.
+2.  Create a feature branch (`git checkout -b feature/amazing-feature`).
+3.  Commit your changes (`git commit -m 'feat: added something amazing'`).
+4.  Push to the branch (`git push origin feature/amazing-feature`).
+5.  Open a Pull Request.
+
+<br/>
+
+---
+
+<br/>
+
+## ❓ FAQ
+
+**Q: Will this slow down my production app?**
+A: **No.** The entire library is wrapped in strict `process.env.NODE_ENV !== 'production'` checks. When you run your production build, modern bundlers (Webpack, Vite, Rollup) will completely dead-code-eliminate the package.
+
+**Q: Why does the highlight box look misaligned?**
+A: Ensure you are attaching the `useRenderTracker` ref to the _outermost_ DOM element of your component. Text nodes or React Fragments without a physical bounding box cannot be traced visually.
+
+**Q: Does it support React 18 Concurrent Mode?**
+A: Yes! It includes specific debouncing logic to ignore Strict Mode double-invocations so your render counts remain perfectly accurate.
+
+<br/>
+
+---
+
+<br/>
+
+## 📄 License
+
+Distributed under the MIT License. See `LICENSE` for more information.
+
+<div align="center">
+  <br/>
+  Built with ❤️ for the React ecosystem.
+</div>

package/dist/chunk-HH72HK3H.mjs

@@ -0,0 +1,110 @@
+// src/core/renderStore.ts
+var renderStore = /* @__PURE__ */ new WeakMap();
+function getRenderData(key) {
+  if (!renderStore.has(key)) {
+    renderStore.set(key, {
+      count: 0,
+      lastRenderTime: 0,
+      renderTimings: [],
+      prevProps: {},
+      changedProps: {},
+      isClient: typeof window !== "undefined",
+      elementRef: null,
+      cause: "mount",
+      isFrequent: false,
+      sourceRef: null
+    });
+  }
+  return renderStore.get(key);
+}
+function updateRenderData(key, data) {
+  const existing = getRenderData(key);
+  renderStore.set(key, { ...existing, ...data });
+}
+
+// src/core/diff.ts
+function shallowDiff(prevProps, nextProps) {
+  const changes = {};
+  const prevKeys = Object.keys(prevProps);
+  const nextKeys = Object.keys(nextProps);
+  const allKeys = /* @__PURE__ */ new Set([...prevKeys, ...nextKeys]);
+  for (const key of allKeys) {
+    if (key === "children") continue;
+    const oldVal = prevProps[key];
+    const newVal = nextProps[key];
+    if (!Object.is(oldVal, newVal)) {
+      changes[key] = { oldVal, newVal };
+    }
+  }
+  return changes;
+}
+
+// src/core/tracker.ts
+var listeners = /* @__PURE__ */ new Set();
+function subscribeToReRenders(listener) {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+var notifyTimeouts = /* @__PURE__ */ new WeakMap();
+function notifyListeners(ref, options, elementRef) {
+  const data = getRenderData(ref);
+  const eventData = {
+    name: options.componentName,
+    count: data.count,
+    changedProps: data.changedProps,
+    timestamp: data.lastRenderTime,
+    elementRef,
+    cause: data.cause,
+    isFrequent: data.isFrequent,
+    sourceRef: data.sourceRef
+  };
+  if (notifyTimeouts.has(ref)) {
+    clearTimeout(notifyTimeouts.get(ref));
+  }
+  const timeout = setTimeout(() => {
+    listeners.forEach((listener) => listener(ref, eventData));
+  }, 16);
+  notifyTimeouts.set(ref, timeout);
+}
+var lastTrackedRender = null;
+function trackRender(ref, props, options) {
+  if (process.env.NODE_ENV !== "development") return;
+  const data = getRenderData(ref);
+  const now = performance.now();
+  const changedProps = shallowDiff(data.prevProps, props);
+  const hasPropChanges = Object.keys(changedProps).length > 0;
+  if (data.count > 0 && !hasPropChanges && now - data.lastRenderTime < 10) {
+    return;
+  }
+  let cause = "mount";
+  if (data.count > 0) {
+    cause = hasPropChanges ? "props" : "state/context";
+  }
+  let sourceRef = null;
+  if (cause === "props" && lastTrackedRender && now - lastTrackedRender.timestamp < 10 && lastTrackedRender.ref !== ref) {
+    sourceRef = lastTrackedRender.ref;
+  }
+  lastTrackedRender = { ref, timestamp: now };
+  const newTimings = [...data.renderTimings, now].slice(-10);
+  let isFrequent = false;
+  if (newTimings.length >= 3) {
+    const timeSinceThirdLast = now - newTimings[newTimings.length - 3];
+    isFrequent = timeSinceThirdLast < 500;
+  }
+  updateRenderData(ref, {
+    count: data.count + 1,
+    lastRenderTime: now,
+    renderTimings: newTimings,
+    prevProps: { ...props },
+    changedProps,
+    cause,
+    isFrequent,
+    sourceRef
+  });
+}
+
+export { getRenderData, notifyListeners, renderStore, shallowDiff, subscribeToReRenders, trackRender, updateRenderData };
+//# sourceMappingURL=chunk-HH72HK3H.mjs.map
+//# sourceMappingURL=chunk-HH72HK3H.mjs.map

package/dist/chunk-HH72HK3H.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core/renderStore.ts","../src/core/diff.ts","../src/core/tracker.ts"],"names":[],"mappings":"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","file":"chunk-HH72HK3H.mjs","sourcesContent":["export type RenderCause = \"mount\" | \"props\" | \"state/context\" | \"unknown\";\n\nexport interface RenderData {\n  count: number;\n  lastRenderTime: number;\n  renderTimings: number[];\n  prevProps: Record<string, any>;\n  changedProps: Record<string, { oldVal: any; newVal: any }>;\n  isClient: boolean;\n  elementRef: HTMLElement | null;\n  cause: RenderCause;\n  isFrequent: boolean;\n  sourceRef: object | null;\n}\n\n// Global WeakMap to store render data per component instance without memory leaks.\n// Keys are the component's internal unique object reference or an instance id.\nexport const renderStore = new WeakMap<object, RenderData>();\n\nexport function getRenderData(key: object): RenderData {\n  if (!renderStore.has(key)) {\n    renderStore.set(key, {\n      count: 0,\n      lastRenderTime: 0,\n      renderTimings: [],\n      prevProps: {},\n      changedProps: {},\n      isClient: typeof window !== \"undefined\",\n      elementRef: null,\n      cause: \"mount\",\n      isFrequent: false,\n      sourceRef: null,\n    });\n  }\n  return renderStore.get(key)!;\n}\n\nexport function updateRenderData(key: object, data: Partial<RenderData>) {\n  const existing = getRenderData(key);\n  renderStore.set(key, { ...existing, ...data });\n}\n","export function shallowDiff(\n  prevProps: Record<string, any>,\n  nextProps: Record<string, any>,\n): Record<string, { oldVal: any; newVal: any }> {\n  const changes: Record<string, { oldVal: any; newVal: any }> = {};\n\n  const prevKeys = Object.keys(prevProps);\n  const nextKeys = Object.keys(nextProps);\n\n  const allKeys = new Set([...prevKeys, ...nextKeys]);\n\n  for (const key of allKeys) {\n    if (key === \"children\") continue;\n\n    const oldVal = prevProps[key];\n    const newVal = nextProps[key];\n\n    // Performance-safe exact match check (Object.is handles NaN and -0 properly)\n    if (!Object.is(oldVal, newVal)) {\n      // Don't flag function reference changes as heavily since they often change (e.g., inline arrow functions)\n      // but they are technically changed. We record them.\n      changes[key] = { oldVal, newVal };\n    }\n  }\n\n  return changes;\n}\n","import {\n  getRenderData,\n  renderStore,\n  updateRenderData,\n  RenderCause,\n} from \"./renderStore\";\nimport { shallowDiff } from \"./diff\";\n\nexport interface TrackerOptions {\n  componentName: string;\n}\n\n/**\n * Listener function that receives render metadata broadcasts.\n */\nexport type RenderListener = (\n  componentRef: object,\n  data: {\n    name: string;\n    count: number;\n    changedProps: Record<string, { oldVal: any; newVal: any }>;\n    timestamp: number;\n    elementRef: HTMLElement | null;\n    cause: RenderCause;\n    isFrequent: boolean;\n    sourceRef: object | null;\n  },\n) => void;\n\nconst listeners = new Set<RenderListener>();\n\n/**\n * Subscribes to global render events emitted by the tracker.\n * @returns An unsubscribe function.\n */\nexport function subscribeToReRenders(listener: RenderListener) {\n  listeners.add(listener);\n  return () => {\n    listeners.delete(listener);\n  };\n}\n\n// Map to handle debouncing of notifications\nconst notifyTimeouts = new WeakMap<object, ReturnType<typeof setTimeout>>();\n\n/**\n * Debounces and notifies all subscribed listeners of a component's render event.\n */\nexport function notifyListeners(\n  ref: object,\n  options: TrackerOptions,\n  elementRef: HTMLElement | null,\n) {\n  const data = getRenderData(ref);\n  const eventData = {\n    name: options.componentName,\n    count: data.count,\n    changedProps: data.changedProps,\n    timestamp: data.lastRenderTime,\n    elementRef,\n    cause: data.cause,\n    isFrequent: data.isFrequent,\n    sourceRef: data.sourceRef,\n  };\n\n  // Debouncing the broadcast slightly to avoid overwhelming the overlay\n  // especially in React 18 concurrent features.\n  if (notifyTimeouts.has(ref)) {\n    clearTimeout(notifyTimeouts.get(ref)!);\n  }\n\n  const timeout = setTimeout(() => {\n    listeners.forEach((listener) => listener(ref, eventData));\n  }, 16); // ~1 frame\n\n  notifyTimeouts.set(ref, timeout);\n}\n\n// Track the immediately preceding render in the current Javascript execution macrotask\n// This allows us to map out the render \"cascade\" tree (e.g. Parent -> Child)\nlet lastTrackedRender: { ref: object; timestamp: number } | null = null;\n\n/**\n * Synchronously tracks a component render, calculates prop diffs, and computes the cause.\n * Includes protection against React 18 Strict Mode double-invocations.\n */\nexport function trackRender(\n  ref: object,\n  props: Record<string, any>,\n  options: TrackerOptions,\n) {\n  if (process.env.NODE_ENV !== \"development\") return;\n\n  const data = getRenderData(ref);\n  const now = performance.now();\n\n  const changedProps = shallowDiff(data.prevProps, props);\n  const hasPropChanges = Object.keys(changedProps).length > 0;\n\n  // Mitigation for React 18 Strict Mode double-renders:\n  // If no props changed and the render happened within 10ms of the last one,\n  // it is almost certainly a strict-mode double invocation. Ignore it.\n  if (data.count > 0 && !hasPropChanges && now - data.lastRenderTime < 10) {\n    return;\n  }\n\n  let cause: RenderCause = \"mount\";\n  if (data.count > 0) {\n    cause = hasPropChanges ? \"props\" : \"state/context\";\n  }\n\n  // Check for rendering cascade (rendered within 5ms of another component)\n  let sourceRef: object | null = null;\n  if (\n    cause === \"props\" &&\n    lastTrackedRender &&\n    now - lastTrackedRender.timestamp < 10 &&\n    lastTrackedRender.ref !== ref\n  ) {\n    sourceRef = lastTrackedRender.ref;\n  }\n\n  lastTrackedRender = { ref, timestamp: now };\n\n  const newTimings = [...data.renderTimings, now].slice(-10); // Keep last 10\n\n  // Frequent render check: 3 renders within 500ms\n  let isFrequent = false;\n  if (newTimings.length >= 3) {\n    const timeSinceThirdLast = now - newTimings[newTimings.length - 3];\n    isFrequent = timeSinceThirdLast < 500;\n  }\n\n  // Update state for this component instance\n  updateRenderData(ref, {\n    count: data.count + 1,\n    lastRenderTime: now,\n    renderTimings: newTimings,\n    prevProps: { ...props },\n    changedProps,\n    cause,\n    isFrequent,\n    sourceRef,\n  });\n}\n"]}