react-memory-leak-detector 0.1.0

package/README.md

@@ -0,0 +1,183 @@
+# react-memory-leak-detector
+
+Live memory-leak detection for React components and hooks. No heap snapshot required.
+
+A babel plugin tags every component and hook with a uniquely-named marker, and a runtime tracker uses `WeakRef` + `FinalizationRegistry` to warn you, **live in the console**, the moment a component is unmounted but still retained by some closure / event listener / timer / subscription.
+
+Dev-only. Zero impact on production bundles.
+
+## How it works
+
+1. The babel plugin injects a uniquely-named `_heap_` marker into every component/hook — searchable as `ComponentName$Heap` in Chrome DevTools heap snapshots.
+2. The runtime tracker wraps each marker in a `WeakRef` and registers it with a `FinalizationRegistry`. A sweep every 2s checks which markers are still reachable.
+3. To know _when_ a component actually unmounts, the babel plugin also injects a **synthetic `useEffect`** into every component and hook:
+
+   ```js
+   __heap_useEffect(() => {
+     window.__heapTracker?.markMounted(_heap_);
+     return () => window.__heapTracker?.markUnmounted(_heap_);
+   }, []);
+   ```
+
+   Imported under a renamed alias so it can't collide with user code. A mount counter handles React StrictMode's double-invoke correctly.
+
+4. If a `_heap_` is still reachable in JS ≥10s after its component unmounted, something is leaking it → console warning.
+
+## Setup & Installation
+
+```bash
+npm install --save-dev react-memory-leak-detector
+```
+
+This package provides two pieces that must be configured:
+
+1. The **Babel Plugin** (`react-memory-leak-detector/babel-plugin`) to inject the tracking markers.
+2. The **Runtime** (`react-memory-leak-detector/runtime`) to collect data and warn you in the console.
+
+### 1. Add the Babel Plugin
+
+You only want this plugin active in development environments.
+
+**Vite + `@vitejs/plugin-react`**
+Vite uses esbuild by default, but its official React plugin exposes Babel configuration:
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import heapMarkers from "react-memory-leak-detector/babel-plugin";
+
+export default defineConfig(({ mode }) => {
+  return {
+    plugins: [
+      react({
+        babel: {
+          plugins:
+            mode === "development"
+              ? [
+                  [
+                    heapMarkers,
+                    {
+                      /* options */
+                    },
+                  ],
+                ]
+              : [],
+        },
+      }),
+    ],
+  };
+});
+```
+
+**Webpack / Next.js / standard Babel**
+Add the plugin to your `.babelrc`, `babel.config.js`, or Webpack `babel-loader` options for the development environment.
+
+```json
+// .babelrc
+{
+  "env": {
+    "development": {
+      "plugins": ["react-memory-leak-detector/babel-plugin"]
+    }
+  }
+}
+```
+
+### 2. Import the Runtime
+
+Inject the runtime into the very beginning of your application (e.g., `src/index.tsx`, `src/main.tsx`, or `_app.tsx`). The runtime must be dynamically imported or guarded so it does not end up in your production bundle.
+
+**For Webpack / Next.js:**
+
+```js
+// src/index.tsx
+if (process.env.NODE_ENV === "development") {
+  import("react-memory-leak-detector/runtime");
+}
+```
+
+**For Vite:**
+
+```js
+// src/main.tsx
+if (import.meta.env.DEV) {
+  import("react-memory-leak-detector/runtime");
+The tracker installs `window.__heapTracker` on dev page load. You'll see:
+
+```
+
+[heap-leak] tracker installed. Run window.\_\_heapTracker.report() for a live table.
+
+```
+
+Warnings fire automatically as `console.warn`, debounced to once per 30s per component:
+
+```
+
+[heap-leak] Suspected leak: GapsByPriorityCard — 1 instance(s) unmounted >10s ago still retained (live 1 total)
+
+````
+
+Manual API:
+
+| Call                               | Purpose                                                                                                                       |
+| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `window.__heapTracker.report()`    | `console.table` of every component with live instances; also returns the array.                                               |
+| `window.__heapTracker.configure()` | Configure runtime options. Example: `configure({ logging: false })` disables all console outputs while continuing tracking.   |
+| `window.__heapTracker.sweep()`     | Force an immediate sweep (otherwise runs every 2s).                                                                           |
+| `window.__heapTracker.forceGc()`   | `window.gc?.()` + re-sweep. Needs Chrome started with `--js-flags="--expose-gc"`. Use it to confirm a flag isn't just GC lag. |
+
+Once a component shows up as stale, take a heap snapshot and search `ComponentName$Heap` → **Retainers** tab to find the offending closure.
+
+## `live` vs `stale`
+
+Both count `_heap_` instances still reachable in JS:
+
+- **`live`** — total reachable instances. Includes currently-mounted, recently-unmounted (GC pending), and leaked.
+- **`stale`** ⊆ `live` — only those where `markUnmounted` fired ≥10s ago. These are the leak suspects.
+
+The leak signal is purely **`stale`**; `live` is context.
+
+| Scenario                             | live | stale |
+| ------------------------------------ | ---- | ----- |
+| 80 cards on screen                   | 80   | 0     |
+| Just navigated away, <10s ago        | 0–80 | 0     |
+| Unmounted but listener still holds 1 | 1+   | 1+    |
+
+## Plugin options
+
+```ts
+heapMarkers({
+  include: /\.[tj]sx?$/, // file path regex
+  excludeNames: [/^useTranslation$/], // names that skip ALL instrumentation
+  excludeUnmountTracking: [], // names that keep the heap marker but skip
+  // the synthetic useEffect (use for components
+  // managed by <Activity mode="hidden">)
+  trackHooks: true, // when false, only components are instrumented
+  skipServerComponents: false, // when true, skip files without "use client"
+  logging: true, // when false, disables automatic console warnings
+  leakAgeMs: 10000, // time in ms before an unmounted component is considered leaked
+  suspectThreshold: 1, // minimum number of stale instances before warning
+  sweepIntervalMs: 2000, // how often the GC sweep checks for leaks
+  warnCooldownMs: 30000, // how long to wait before warning about the SAME component again
+});
+````
+
+All options are optional with sensible defaults.
+
+## Compatibility
+
+| React feature                             | Status                                     |
+| ----------------------------------------- | ------------------------------------------ |
+| React 17 / 18 function components & hooks | ✅                                         |
+| React 18 concurrent, Suspense, StrictMode | ✅                                         |
+| SSR (effects no-op server-side)           | ✅                                         |
+| React Compiler                            | ✅ likely; warrants a CI snapshot test     |
+| `<Activity mode="hidden">`                | ⚠️ use `excludeUnmountTracking` to opt out |
+| React Server Components                   | ⚠️ use `skipServerComponents: true`        |
+| Class components                          | ❌ not instrumented (PRs welcome)          |
+
+## License
+
+MIT

package/babel-plugin.js

@@ -0,0 +1,681 @@
+/**
+ * Babel plugin: babel-plugin-heap-markers
+ *
+ * Automatically injects a named marker instance into React functional components
+ * so they become identifiable in Chrome DevTools heap snapshots.
+ *
+ * How it works:
+ * 1. At the top of each component body, injects a useRef-stabilized marker
+ *    that survives across renders (one per component instance, not per
+ *    render — otherwise the unmount effect's `[]` deps would only ever
+ *    track render-1's marker and miss leaks anchored to later-render
+ *    closures):
+ *      var _heap_ref_ = __heap_useRef(null);
+ *      if (_heap_ref_.current === null) {
+ *        _heap_ref_.current = new (function ComponentName$Heap() {})();
+ *        window.__heapTracker?.track(_heap_ref_.current, "ComponentName");
+ *      }
+ *      var _heap_ = _heap_ref_.current;
+ *
+ * 2. Into every nested closure (arrows, function expressions), injects:
+ *      _heap_ && 0;
+ *    This forces V8 to capture _heap_ in the closure's scope chain.
+ *    (We use `_heap_ && 0` instead of `void _heap_` because esbuild
+ *    strips void expressions as dead code.)
+ *
+ * If a closure leaks (e.g., useEffect without cleanup), the closure retains
+ * _heap_, which retains the ComponentName$Heap instance. In heap snapshots:
+ * - Search for "ComponentName$Heap" to find the leaked component
+ * - Check "Retainers" to see the ACTUAL closure causing the leak
+ *
+ * Targets:
+ * - Named function declarations:   function MyComponent() { ... }
+ * - Const arrow functions:          const MyComponent = () => { ... }
+ * - Const function expressions:     const MyComponent = function() { ... }
+ * - memo-wrapped:                   const MyComponent = memo(() => { ... })
+ * - forwardRef-wrapped:             const MyComponent = forwardRef((props, ref) => { ... })
+ * - Custom hooks (any file):        function useMyHook() { ... }
+ * - Custom hooks (arrow):           const useMyHook = () => { ... }
+ *
+ * Components: only .tsx/.jsx files, PascalCase names, must contain JSX.
+ * Hooks: any .ts/.tsx/.js/.jsx file, use* prefix, no JSX required.
+ *
+ * Strategy:
+ * Instead of using a nested bodyPath.traverse() (which can silently fail in
+ * Babel's visitor context), this plugin uses Babel's normal visitor pattern:
+ * - Phase 1: FunctionDeclaration/VariableDeclarator visitors detect components,
+ *   inject the marker, and register the component function node in a WeakSet.
+ * - Phase 2: ArrowFunctionExpression/FunctionExpression visitors run on EVERY
+ *   nested function. They check if _heap_ exists in the parent scope chain
+ *   and inject `_heap_ && 0` if so. Component-level and marker functions are
+ *   skipped via the WeakSet.
+ */
+/**
+ * Plugin options:
+ *   include                  — RegExp matched against the file path. Files not
+ *                              matching are skipped entirely.
+ *                              Default: /\.[tj]sx?$/ (JS/TS/JSX/TSX).
+ *   excludeNames             — Array of RegExp matched against the component
+ *                              or hook identifier. A match skips ALL
+ *                              instrumentation for that one function.
+ *                              Default: [].
+ *   excludeUnmountTracking   — Array of RegExp matched against the identifier.
+ *                              A match keeps the $Heap marker + track() call
+ *                              (still searchable in heap snapshots) but skips
+ *                              the synthetic useEffect that drives live
+ *                              detection. Use this for components managed by
+ *                              <Activity mode="hidden">, where cleanup fires
+ *                              while the fiber is still alive — otherwise the
+ *                              tracker would false-positive.
+ *                              Default: [].
+ *   trackHooks               — When false, custom hooks (use* names) are NOT
+ *                              instrumented; only components are.
+ *                              Default: true.
+ *   skipServerComponents     — When true, files that don't begin with the
+ *                              "use client" directive are skipped entirely.
+ *                              Needed in React Server Components projects:
+ *                              server components can't call useEffect, so
+ *                              injecting it would crash at module-load time.
+ *                              Default: false.
+ *   logging                  — When false, disables console warnings at runtime
+ *                              while still tracking.
+ *                              Default: true.
+ *
+ * Components additionally require a .jsx/.tsx extension and a JSX element in
+ * the body — that's structural, not a config option.
+ */
+module.exports = function babelPluginHeapMarkers({ types: t }, options = {}) {
+  const {
+    include = /\.[tj]sx?$/,
+    excludeNames = [],
+    excludeUnmountTracking = [],
+    trackHooks = true,
+    skipServerComponents = false,
+    logging = true,
+    leakAgeMs = 10000,
+    suspectThreshold = 1,
+    sweepIntervalMs = 2000,
+    warnCooldownMs = 30000,
+  } = options;
+
+  // Track function nodes that ARE components or hooks (don't inject _heap_ && 0 into them)
+  const instrumentedFunctions = new WeakSet();
+  // Track function nodes that are marker constructors (don't inject _heap_ && 0)
+  const markerConstructors = new WeakSet();
+
+  function isPascalCase(name) {
+    return /^[A-Z]\w*$/.test(name);
+  }
+
+  function isCustomHook(name) {
+    // Matches use + uppercase letter: useEffect, useMyHook, etc.
+    // Excludes bare "use"
+    return /^use[A-Z]/.test(name);
+  }
+
+  function isExcludedName(name) {
+    return excludeNames.some((re) => re.test(name));
+  }
+
+  function isExcludedFromUnmountTracking(name) {
+    return excludeUnmountTracking.some((re) => re.test(name));
+  }
+
+  function isReactFile(filename) {
+    // Components must live in JSX/TSX files. We narrow the user's `include`
+    // to JSX extensions for component detection only.
+    return (
+      /\.[tj]sx$/.test(filename || "") && include.test(filename || "")
+    );
+  }
+
+  function isJSOrTSFile(filename) {
+    return include.test(filename || "");
+  }
+
+  function containsJSX(nodePath) {
+    let found = false;
+    nodePath.traverse({
+      JSXElement(path) {
+        found = true;
+        path.stop();
+      },
+      JSXFragment(path) {
+        found = true;
+        path.stop();
+      },
+    });
+    return found;
+  }
+
+  /**
+   * Resolves the inner function path from a variable initializer.
+   * Handles direct arrow/function expressions and common wrappers
+   * like memo() and forwardRef().
+   */
+  function resolveComponentFunction(initPath) {
+    if (
+      initPath.isArrowFunctionExpression() ||
+      initPath.isFunctionExpression()
+    ) {
+      return initPath;
+    }
+
+    // Handle memo(() => {}), forwardRef(() => {}),
+    // React.memo(() => {}), React.forwardRef(() => {})
+    if (initPath.isCallExpression()) {
+      const callee = initPath.get("callee");
+      let calleeName = null;
+
+      if (callee.isIdentifier()) {
+        calleeName = callee.node.name;
+      } else if (
+        callee.isMemberExpression() &&
+        callee.get("property").isIdentifier()
+      ) {
+        calleeName = callee.get("property").node.name;
+      }
+
+      if (calleeName === "memo" || calleeName === "forwardRef") {
+        const args = initPath.get("arguments");
+        if (args.length > 0) {
+          const firstArg = args[0];
+          if (
+            firstArg.isArrowFunctionExpression() ||
+            firstArg.isFunctionExpression()
+          ) {
+            return firstArg;
+          }
+          // Handle memo(forwardRef(() => {}))
+          if (firstArg.isCallExpression()) {
+            return resolveComponentFunction(firstArg);
+          }
+        }
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Ensures the function has a block body (converts expression arrows).
+   * Returns the block body path.
+   */
+  function ensureBlockBody(fnPath) {
+    const body = fnPath.get("body");
+    if (!body.isBlockStatement()) {
+      // Arrow with expression body: () => <div />
+      // Convert to: () => { return <div />; }
+      body.replaceWith(t.blockStatement([t.returnStatement(body.node)]));
+    }
+    return fnPath.get("body");
+  }
+
+  // Local aliases we import from React under renamed names so they can't
+  // collide with anything a user might define in the same file.
+  const USE_EFFECT_ALIAS = "__heap_useEffect";
+  const USE_REF_ALIAS = "__heap_useRef";
+
+  /**
+   * Builds: window.__heapTracker && window.__heapTracker.<method>(_heap_)
+   */
+  function buildTrackerMemberCall(method, args = [t.identifier("_heap_")]) {
+    return t.expressionStatement(
+      t.logicalExpression(
+        "&&",
+        t.binaryExpression(
+          "!==",
+          t.unaryExpression("typeof", t.identifier("window"), true),
+          t.stringLiteral("undefined")
+        ),
+        t.logicalExpression(
+          "&&",
+          t.memberExpression(
+            t.identifier("window"),
+            t.identifier("__heapTracker")
+          ),
+          t.callExpression(
+            t.memberExpression(
+              t.memberExpression(
+                t.identifier("window"),
+                t.identifier("__heapTracker")
+              ),
+              t.identifier(method)
+            ),
+            args
+          )
+        )
+      )
+    );
+  }
+
+  /**
+   * Builds the unmount-detection useEffect:
+   *
+   *   __heap_useEffect(() => {
+   *     window.__heapTracker && window.__heapTracker.markMounted(_heap_);
+   *     return () => {
+   *       window.__heapTracker && window.__heapTracker.markUnmounted(_heap_);
+   *     };
+   *   }, []);
+   *
+   * StrictMode double-invokes effects; the tracker handles that with a mount
+   * counter, so we don't need any extra guards here.
+   */
+  function buildUnmountEffect() {
+    const cleanup = t.arrowFunctionExpression(
+      [],
+      t.blockStatement([buildTrackerMemberCall("markUnmounted")])
+    );
+    const effectBody = t.arrowFunctionExpression(
+      [],
+      t.blockStatement([
+        buildTrackerMemberCall("markMounted"),
+        t.returnStatement(cleanup),
+      ])
+    );
+    return t.expressionStatement(
+      t.callExpression(t.identifier(USE_EFFECT_ALIAS), [
+        effectBody,
+        t.arrayExpression([]),
+      ])
+    );
+  }
+
+  /**
+   * Injects a heap marker declaration at the top of the component body,
+   * plus the live-tracker registration and (unless opted out) an
+   * unmount-detecting useEffect.
+   *
+   * The marker is stabilized across renders via useRef: it's created once
+   * on first render and reused on every subsequent render. Without this,
+   * `var _heap_ = new (...)()` would re-run every render and only render-1's
+   * marker would receive markMounted/markUnmounted (the effect has `[]` deps),
+   * so leaks from later renders' closures would never trigger a live warning.
+   *
+   * Generates:
+   *   var _heap_ref_ = __heap_useRef(null);
+   *   if (_heap_ref_.current === null) {
+   *     _heap_ref_.current = new (function ComponentName$Heap() {})();
+   *     typeof window !== "undefined" && window.__heapTracker
+   *       && window.__heapTracker.track(_heap_ref_.current, "ComponentName");
+   *   }
+   *   var _heap_ = _heap_ref_.current;
+   *   __heap_useEffect(() => {
+   *     window.__heapTracker && window.__heapTracker.markMounted(_heap_);
+   *     return () =>
+   *       window.__heapTracker && window.__heapTracker.markUnmounted(_heap_);
+   *   }, []);
+   *
+   * `_heap_` keeps its original identifier so the Phase-2 `_heap_ && 0`
+   * injector continues to capture the (now stable) marker into nested
+   * closures unchanged.
+   *
+   * The marker constructor is registered in markerConstructors WeakSet so
+   * the FunctionExpression visitor skips it. Closures inside the useEffect
+   * get processed by Phase-2 normally — harmless.
+   */
+  function injectMarkerVariable(bodyPath, componentName, state) {
+    const markerName = `${componentName}$Heap`;
+
+    // Build the named function expression node
+    const markerFnExpr = t.functionExpression(
+      t.identifier(markerName), // named constructor — searchable in heap
+      [], // no params
+      t.blockStatement([]) // empty body
+    );
+
+    // Register the marker constructor so it gets skipped by the FunctionExpression visitor
+    markerConstructors.add(markerFnExpr);
+
+    // var _heap_ref_ = __heap_useRef(null);
+    const refDeclaration = t.variableDeclaration("var", [
+      t.variableDeclarator(
+        t.identifier("_heap_ref_"),
+        t.callExpression(t.identifier(USE_REF_ALIAS), [t.nullLiteral()])
+      ),
+    ]);
+
+    // _heap_ref_.current
+    const refCurrent = () =>
+      t.memberExpression(
+        t.identifier("_heap_ref_"),
+        t.identifier("current")
+      );
+
+    // _heap_ref_.current = new (function ComponentName$Heap() {})();
+    const assignMarker = t.expressionStatement(
+      t.assignmentExpression(
+        "=",
+        refCurrent(),
+        t.newExpression(markerFnExpr, [])
+      )
+    );
+
+    // typeof window !== "undefined" && window.__heapTracker
+    //   && window.__heapTracker.track(_heap_ref_.current, "ComponentName");
+    const trackerCall = buildTrackerMemberCall("track", [
+      refCurrent(),
+      t.stringLiteral(componentName),
+    ]);
+
+    // if (_heap_ref_.current === null) { _heap_ref_.current = new …; track(); }
+    const initBlock = t.ifStatement(
+      t.binaryExpression("===", refCurrent(), t.nullLiteral()),
+      t.blockStatement([assignMarker, trackerCall])
+    );
+
+    // var _heap_ = _heap_ref_.current;
+    const heapAlias = t.variableDeclaration("var", [
+      t.variableDeclarator(t.identifier("_heap_"), refCurrent()),
+    ]);
+
+    const statements = [refDeclaration, initBlock, heapAlias];
+    // eslint-disable-next-line no-param-reassign
+    state.needsHeapUseRefImport = true;
+
+    // Skip the lifecycle effect for components opted out via
+    // excludeUnmountTracking (e.g. those managed by <Activity mode="hidden">,
+    // whose cleanup fires while the fiber is still alive — would cause false
+    // positives). The marker + track() still happen, so the component remains
+    // searchable in heap snapshots.
+    if (!isExcludedFromUnmountTracking(componentName)) {
+      statements.push(buildUnmountEffect());
+      // eslint-disable-next-line no-param-reassign
+      state.needsHeapUseEffectImport = true;
+    }
+
+    // Prepend at the top of the component body
+    bodyPath.unshiftContainer("body", statements);
+  }
+
+  /**
+   * Injects `_heap_ && 0` at the top of a nested closure's body.
+   * Handles both block-body and expression-body arrows.
+   *
+   * We use `_heap_ && 0` instead of `void _heap_` because Vite's esbuild
+   * pass strips `void expr` as dead code, removing the closure capture.
+   * `_heap_ && 0` is a no-op at runtime but esbuild preserves it.
+   */
+  function injectVoidHeap(fnPath) {
+    const captureExpr = t.expressionStatement(
+      t.logicalExpression("&&", t.identifier("_heap_"), t.numericLiteral(0))
+    );
+
+    if (fnPath.isArrowFunctionExpression()) {
+      const body = fnPath.get("body");
+      if (body.isBlockStatement()) {
+        body.unshiftContainer("body", captureExpr);
+      } else {
+        // Expression body: () => expr  →  () => { _heap_ && 0; return expr; }
+        body.replaceWith(
+          t.blockStatement([captureExpr, t.returnStatement(body.node)])
+        );
+      }
+    } else {
+      // FunctionExpression or FunctionDeclaration — always block body
+      fnPath.get("body").unshiftContainer("body", captureExpr);
+    }
+  }
+
+  /**
+   * Checks if this function path is nested inside a component that has _heap_.
+   * Uses findParent to walk up the AST — this is independent of Babel's scope
+   * system, which may not reflect dynamically injected bindings.
+   *
+   * Returns true if an ancestor function is in the componentFunctions WeakSet.
+   */
+  function shouldInjectVoidHeap(fnPath) {
+    // Don't inject into instrumented functions (components/hooks) themselves
+    if (instrumentedFunctions.has(fnPath.node)) return false;
+    // Don't inject into marker constructors
+    if (markerConstructors.has(fnPath.node)) return false;
+
+    // Walk up the AST to find a parent component or hook function
+    const parentInstrumented = fnPath.findParent(
+      (p) =>
+        (p.isFunctionDeclaration() ||
+          p.isArrowFunctionExpression() ||
+          p.isFunctionExpression() ||
+          p.isObjectMethod() ||
+          p.isClassMethod()) &&
+        instrumentedFunctions.has(p.node)
+    );
+
+    return parentInstrumented !== null;
+  }
+
+  return {
+    name: "babel-plugin-heap-markers",
+    visitor: {
+      // ─── Phase 0: Per-file setup and (on exit) import management ───
+      Program: {
+        enter(programPath, state) {
+          /* eslint-disable no-param-reassign */
+          state.fileImportsReact = programPath.node.body.some(
+            (node) =>
+              t.isImportDeclaration(node) &&
+              node.source.value === "react" &&
+              node.importKind !== "type"
+          );
+          state.needsHeapUseEffectImport = false;
+          state.needsHeapUseRefImport = false;
+
+          // When skipServerComponents is on, instrument only files that have
+          // a top-level "use client" directive. Server components can't call
+          // useEffect; injecting it would crash at module-load time.
+          if (skipServerComponents) {
+            const directives = programPath.node.directives || [];
+            const hasUseClient = directives.some(
+              (d) => d.value && d.value.value === "use client"
+            );
+            state.skipFile = !hasUseClient;
+          } else {
+            state.skipFile = false;
+          }
+          /* eslint-enable no-param-reassign */
+        },
+        exit(programPath, state) {
+          const emitsConfig =
+            logging === false ||
+            leakAgeMs !== 10000 ||
+            suspectThreshold !== 1 ||
+            sweepIntervalMs !== 2000 ||
+            warnCooldownMs !== 30000;
+
+          if (emitsConfig && !state.skipFile) {
+            const configAst = t.ifStatement(
+              t.binaryExpression(
+                "!==",
+                t.unaryExpression("typeof", t.identifier("window")),
+                t.stringLiteral("undefined")
+              ),
+              t.blockStatement([
+                t.expressionStatement(
+                  t.assignmentExpression(
+                    "=",
+                    t.memberExpression(t.identifier("window"), t.identifier("__heapTrackerOptions")),
+                    t.objectExpression([
+                      t.objectProperty(t.identifier("logging"), t.booleanLiteral(logging)),
+                      t.objectProperty(t.identifier("leakAgeMs"), t.numericLiteral(leakAgeMs)),
+                      t.objectProperty(t.identifier("suspectThreshold"), t.numericLiteral(suspectThreshold)),
+                      t.objectProperty(t.identifier("sweepIntervalMs"), t.numericLiteral(sweepIntervalMs)),
+                      t.objectProperty(t.identifier("warnCooldownMs"), t.numericLiteral(warnCooldownMs)),
+                    ])
+                  )
+                ),
+                t.expressionStatement(
+                  t.logicalExpression(
+                    "&&",
+                    t.memberExpression(t.identifier("window"), t.identifier("__heapTracker")),
+                    t.callExpression(
+                      t.memberExpression(
+                        t.memberExpression(t.identifier("window"), t.identifier("__heapTracker")),
+                        t.identifier("configure")
+                      ),
+                      [t.memberExpression(t.identifier("window"), t.identifier("__heapTrackerOptions"))]
+                    )
+                  )
+                )
+              ])
+            );
+            programPath.unshiftContainer("body", configAst);
+          }
+
+          const specifiers = [];
+          if (state.needsHeapUseRefImport) {
+            specifiers.push(
+              t.importSpecifier(
+                t.identifier(USE_REF_ALIAS),
+                t.identifier("useRef")
+              )
+            );
+          }
+          if (state.needsHeapUseEffectImport) {
+            specifiers.push(
+              t.importSpecifier(
+                t.identifier(USE_EFFECT_ALIAS),
+                t.identifier("useEffect")
+              )
+            );
+          }
+          if (specifiers.length === 0) return;
+
+          // Try to attach to an existing react import. Skip ones that use a
+          // namespace specifier (`import * as React from "react"`) — you can't
+          // mix `* as X` with named specifiers in the same declaration.
+          // Also skip type-only imports (`import type {...} from "react"`),
+          // which Babel's TS transform strips wholesale, taking our added
+          // value specifiers with them.
+          const reuseTarget = programPath.node.body.find(
+            (node) =>
+              t.isImportDeclaration(node) &&
+              node.source.value === "react" &&
+              node.importKind !== "type" &&
+              !node.specifiers.some((s) => t.isImportNamespaceSpecifier(s))
+          );
+
+          if (reuseTarget) {
+            reuseTarget.specifiers.push(...specifiers);
+          } else {
+            programPath.unshiftContainer(
+              "body",
+              t.importDeclaration(specifiers, t.stringLiteral("react"))
+            );
+          }
+        },
+      },
+
+      // ─── Phase 1: Detect components and inject marker declarations ───
+
+      // Handle: function MyComponent() { ... }
+      // Handle: export default function MyComponent() { ... }
+      // Handle: function useMyHook() { ... }
+      FunctionDeclaration(fnPath, state) {
+        if (state.skipFile) return;
+        // The injected marker uses useRef + useEffect, so files that don't
+        // import React can't be instrumented. Also filters out `use*`-named
+        // utilities in non-React files that aren't actually hooks.
+        if (!state.fileImportsReact) return;
+        const name = fnPath.node.id?.name;
+        if (!name) return;
+        if (isExcludedName(name)) return;
+
+        // Custom hooks: any .ts/.tsx/.js/.jsx file, use* prefix
+        if (trackHooks && isCustomHook(name) && isJSOrTSFile(state.filename)) {
+          instrumentedFunctions.add(fnPath.node);
+          injectMarkerVariable(fnPath.get("body"), name, state);
+          return;
+        }
+
+        // Components: .tsx/.jsx only, PascalCase, must contain JSX
+        if (!isReactFile(state.filename)) return;
+        if (!isPascalCase(name)) return;
+        if (!containsJSX(fnPath)) return;
+
+        instrumentedFunctions.add(fnPath.node);
+        injectMarkerVariable(fnPath.get("body"), name, state);
+      },
+
+      // Handle: const MyComponent = () => { ... }
+      // Handle: const MyComponent = memo(() => { ... })
+      // Handle: const MyComponent = forwardRef((props, ref) => { ... })
+      // Handle: const useMyHook = () => { ... }
+      VariableDeclarator(varPath, state) {
+        if (state.skipFile) return;
+        if (!state.fileImportsReact) return;
+        const name = varPath.node.id?.name;
+        if (!name) return;
+        if (isExcludedName(name)) return;
+
+        const isHook = isCustomHook(name) && trackHooks;
+        const isComponent = isPascalCase(name);
+        if (!isHook && !isComponent) return;
+
+        // Hooks can be in any JS/TS file; components only in JSX/TSX
+        if (isHook && !isJSOrTSFile(state.filename)) return;
+        if (!isHook && !isReactFile(state.filename)) return;
+
+        const init = varPath.get("init");
+        // For hooks, the init can be a direct arrow/function (no memo/forwardRef wrapper)
+        let fnPath;
+        if (isHook) {
+          fnPath =
+            init.isArrowFunctionExpression() || init.isFunctionExpression()
+              ? init
+              : null;
+        } else {
+          fnPath = resolveComponentFunction(init);
+        }
+        if (!fnPath) return;
+
+        // Only components need JSX check; hooks don't
+        if (!isHook && !containsJSX(fnPath)) return;
+
+        instrumentedFunctions.add(fnPath.node);
+        const bodyPath = ensureBlockBody(fnPath);
+        injectMarkerVariable(bodyPath, name, state);
+      },
+
+      // ─── Phase 2: Inject void _heap_ into nested closures ───
+      //
+      // These visitors run on EVERY arrow/function expression in the file.
+      // Babel's depth-first traversal ensures that by the time we visit
+      // a nested closure, the parent component's marker has already been
+      // injected (because VariableDeclarator/FunctionDeclaration visitors
+      // run on the parent node first in the enter phase).
+
+      ArrowFunctionExpression(fnPath, state) {
+        if (state.skipFile) return;
+        if (!isJSOrTSFile(state.filename)) return;
+        if (shouldInjectVoidHeap(fnPath)) {
+          injectVoidHeap(fnPath);
+        }
+      },
+
+      FunctionExpression(fnPath, state) {
+        if (state.skipFile) return;
+        if (!isJSOrTSFile(state.filename)) return;
+        if (shouldInjectVoidHeap(fnPath)) {
+          injectVoidHeap(fnPath);
+        }
+      },
+
+      ObjectMethod(fnPath, state) {
+        if (state.skipFile) return;
+        if (!isJSOrTSFile(state.filename)) return;
+        if (shouldInjectVoidHeap(fnPath)) {
+          injectVoidHeap(fnPath);
+        }
+      },
+
+      ClassMethod(fnPath, state) {
+        if (state.skipFile) return;
+        if (!isJSOrTSFile(state.filename)) return;
+        if (shouldInjectVoidHeap(fnPath)) {
+          injectVoidHeap(fnPath);
+        }
+      },
+    },
+  };
+};

package/dist/runtime.d.ts

@@ -0,0 +1,35 @@
+declare let _config: {
+    logging: boolean;
+    leakAgeMs: number;
+    suspectThreshold: number;
+    sweepIntervalMs: number;
+    warnCooldownMs: number;
+};
+declare function configure(options: Partial<typeof _config>): void;
+declare function track(instance: object, componentName: string): void;
+declare function markMounted(instance: object): void;
+declare function markUnmounted(instance: object): void;
+declare function sweep(): void;
+type ReportRow = {
+    component: string;
+    live: number;
+    stale: number;
+    lastRenderSecsAgo: number;
+};
+declare function report(): ReportRow[];
+declare function forceGc(): void;
+declare const api: {
+    track: typeof track;
+    markMounted: typeof markMounted;
+    markUnmounted: typeof markUnmounted;
+    sweep: typeof sweep;
+    report: typeof report;
+    forceGc: typeof forceGc;
+    configure: typeof configure;
+};
+declare global {
+    interface Window {
+        __heapTracker?: typeof api;
+    }
+}
+export {};

package/dist/runtime.js

@@ -0,0 +1,184 @@
+// Live memory-leak detector runtime. Companion to ../babel-plugin.js.
+//
+// The babel plugin injects `var _heap_ = new (function Foo$Heap(){})()` into
+// every component/hook in dev. This module wraps each marker in a WeakRef and
+// a FinalizationRegistry. A marker that survives well past its render means
+// some closure is still retaining it — i.e. a leak.
+//
+// Importing this module installs `window.__heapTracker` and starts the sweep
+// loop. Intended to be loaded once at app boot in dev. See README.md.
+let _config = {
+    logging: true,
+    leakAgeMs: 10_000,
+    suspectThreshold: 1,
+    sweepIntervalMs: 2_000,
+    warnCooldownMs: 30_000,
+};
+if (typeof window !== "undefined" && window.__heapTrackerOptions) {
+    Object.assign(_config, window.__heapTrackerOptions);
+}
+function configure(options) {
+    const oldInterval = _config.sweepIntervalMs;
+    Object.assign(_config, options);
+    if (options.sweepIntervalMs && options.sweepIntervalMs !== oldInterval) {
+        if (intervalId !== null) {
+            clearInterval(intervalId);
+            intervalId = null;
+            startSweepLoop();
+        }
+    }
+}
+const live = new Set();
+const stats = new Map();
+const instanceToEntry = new WeakMap();
+const registry = new FinalizationRegistry((entry) => {
+    live.delete(entry);
+});
+function getStats(name) {
+    let s = stats.get(name);
+    if (!s) {
+        s = { lastRegisteredAt: 0, lastWarnedAt: 0 };
+        stats.set(name, s);
+    }
+    return s;
+}
+function track(instance, componentName) {
+    const now = Date.now();
+    const entry = {
+        ref: new WeakRef(instance),
+        componentName,
+        createdAt: now,
+        mountCount: 0,
+        unmountedAt: null,
+    };
+    live.add(entry);
+    instanceToEntry.set(instance, entry);
+    registry.register(instance, entry);
+    const s = getStats(componentName);
+    s.lastRegisteredAt = now;
+}
+// Called by injected useEffect body on mount. StrictMode double-invokes the
+// effect (run → cleanup → run), so we counter-track instead of just flipping
+// a flag — unmountedAt is only set when the counter actually returns to 0.
+function markMounted(instance) {
+    const entry = instanceToEntry.get(instance);
+    if (!entry)
+        return;
+    entry.mountCount += 1;
+    entry.unmountedAt = null;
+}
+function markUnmounted(instance) {
+    const entry = instanceToEntry.get(instance);
+    if (!entry)
+        return;
+    if (entry.mountCount === 0)
+        return;
+    entry.mountCount -= 1;
+    if (entry.mountCount === 0)
+        entry.unmountedAt = Date.now();
+}
+function bucketLiveEntries() {
+    const now = Date.now();
+    const perName = new Map();
+    live.forEach((entry) => {
+        if (!entry.ref.deref()) {
+            live.delete(entry);
+            return;
+        }
+        let bucket = perName.get(entry.componentName);
+        if (!bucket) {
+            bucket = { stale: 0, live: 0 };
+            perName.set(entry.componentName, bucket);
+        }
+        bucket.live += 1;
+        if (entry.unmountedAt != null &&
+            now - entry.unmountedAt >= _config.leakAgeMs) {
+            bucket.stale += 1;
+        }
+    });
+    return perName;
+}
+function sweep() {
+    const now = Date.now();
+    const perName = bucketLiveEntries();
+    perName.forEach((bucket, name) => {
+        const s = getStats(name);
+        const cooldownPassed = now - s.lastWarnedAt > _config.warnCooldownMs;
+        if (bucket.stale >= _config.suspectThreshold && cooldownPassed) {
+            s.lastWarnedAt = now;
+            if (_config.logging) {
+                // eslint-disable-next-line no-console
+                console.warn(`[heap-leak] Suspected leak: ${name} — ${bucket.stale} instance(s) unmounted >${_config.leakAgeMs / 1000}s ago still retained (live ${bucket.live} total)`);
+            }
+        }
+    });
+}
+function report() {
+    const now = Date.now();
+    const perName = bucketLiveEntries();
+    const rows = [];
+    perName.forEach((bucket, name) => {
+        const s = getStats(name);
+        rows.push({
+            component: name,
+            live: bucket.live,
+            stale: bucket.stale,
+            lastRenderSecsAgo: Number(((now - s.lastRegisteredAt) / 1000).toFixed(1)),
+        });
+    });
+    rows.sort((a, b) => b.stale - a.stale || b.live - a.live);
+    if (_config.logging) {
+        // eslint-disable-next-line no-console
+        console.table(rows);
+    }
+    return rows;
+}
+function forceGc() {
+    const w = window;
+    if (typeof w.gc === "function") {
+        w.gc();
+        if (_config.logging) {
+            // eslint-disable-next-line no-console
+            console.info("[heap-leak] window.gc() invoked; re-sweeping.");
+        }
+    }
+    else {
+        if (_config.logging) {
+            // eslint-disable-next-line no-console
+            console.info('[heap-leak] window.gc not available. Start Chrome with --js-flags="--expose-gc" to enable.');
+        }
+    }
+    sweep();
+}
+const api = {
+    track,
+    markMounted,
+    markUnmounted,
+    sweep,
+    report,
+    forceGc,
+    configure,
+};
+if (typeof window !== "undefined") {
+    window.__heapTracker = api;
+}
+let intervalId = null;
+function startSweepLoop() {
+    if (typeof document === "undefined")
+        return;
+    if (intervalId !== null)
+        return;
+    intervalId = setInterval(() => {
+        if (typeof document !== "undefined" &&
+            document.visibilityState === "visible")
+            sweep();
+    }, _config.sweepIntervalMs);
+}
+if (typeof window !== "undefined") {
+    startSweepLoop();
+    if (_config.logging) {
+        // eslint-disable-next-line no-console
+        console.info("[heap-leak] tracker installed. Run window.__heapTracker.report() for a live table.");
+    }
+}
+export {};

package/dist/src/runtime.d.ts

@@ -0,0 +1,26 @@
+declare function track(instance: object, componentName: string): void;
+declare function markMounted(instance: object): void;
+declare function markUnmounted(instance: object): void;
+declare function sweep(): void;
+type ReportRow = {
+    component: string;
+    live: number;
+    stale: number;
+    lastRenderSecsAgo: number;
+};
+declare function report(): ReportRow[];
+declare function forceGc(): void;
+declare const api: {
+    track: typeof track;
+    markMounted: typeof markMounted;
+    markUnmounted: typeof markUnmounted;
+    sweep: typeof sweep;
+    report: typeof report;
+    forceGc: typeof forceGc;
+};
+declare global {
+    interface Window {
+        __heapTracker?: typeof api;
+    }
+}
+export {};

package/dist/src/runtime.js

@@ -0,0 +1,148 @@
+// Live memory-leak detector runtime. Companion to ../babel-plugin.js.
+//
+// The babel plugin injects `var _heap_ = new (function Foo$Heap(){})()` into
+// every component/hook in dev. This module wraps each marker in a WeakRef and
+// a FinalizationRegistry. A marker that survives well past its render means
+// some closure is still retaining it — i.e. a leak.
+//
+// Importing this module installs `window.__heapTracker` and starts the sweep
+// loop. Intended to be loaded once at app boot in dev. See README.md.
+const LEAK_AGE_MS = 10_000;
+const SUSPECT_THRESHOLD = 1;
+const SWEEP_INTERVAL_MS = 2_000;
+const WARN_COOLDOWN_MS = 30_000;
+const live = new Set();
+const stats = new Map();
+const instanceToEntry = new WeakMap();
+const registry = new FinalizationRegistry((entry) => {
+    live.delete(entry);
+});
+function getStats(name) {
+    let s = stats.get(name);
+    if (!s) {
+        s = { lastRegisteredAt: 0, lastWarnedAt: 0 };
+        stats.set(name, s);
+    }
+    return s;
+}
+function track(instance, componentName) {
+    const now = Date.now();
+    const entry = {
+        ref: new WeakRef(instance),
+        componentName,
+        createdAt: now,
+        mountCount: 0,
+        unmountedAt: null,
+    };
+    live.add(entry);
+    instanceToEntry.set(instance, entry);
+    registry.register(instance, entry);
+    const s = getStats(componentName);
+    s.lastRegisteredAt = now;
+}
+// Called by injected useEffect body on mount. StrictMode double-invokes the
+// effect (run → cleanup → run), so we counter-track instead of just flipping
+// a flag — unmountedAt is only set when the counter actually returns to 0.
+function markMounted(instance) {
+    const entry = instanceToEntry.get(instance);
+    if (!entry)
+        return;
+    entry.mountCount += 1;
+    entry.unmountedAt = null;
+}
+function markUnmounted(instance) {
+    const entry = instanceToEntry.get(instance);
+    if (!entry)
+        return;
+    if (entry.mountCount === 0)
+        return;
+    entry.mountCount -= 1;
+    if (entry.mountCount === 0)
+        entry.unmountedAt = Date.now();
+}
+function bucketLiveEntries() {
+    const now = Date.now();
+    const perName = new Map();
+    live.forEach((entry) => {
+        if (!entry.ref.deref()) {
+            live.delete(entry);
+            return;
+        }
+        let bucket = perName.get(entry.componentName);
+        if (!bucket) {
+            bucket = { stale: 0, live: 0 };
+            perName.set(entry.componentName, bucket);
+        }
+        bucket.live += 1;
+        if (entry.unmountedAt != null && now - entry.unmountedAt >= LEAK_AGE_MS) {
+            bucket.stale += 1;
+        }
+    });
+    return perName;
+}
+function sweep() {
+    const now = Date.now();
+    const perName = bucketLiveEntries();
+    perName.forEach((bucket, name) => {
+        const s = getStats(name);
+        const cooldownPassed = now - s.lastWarnedAt > WARN_COOLDOWN_MS;
+        if (bucket.stale >= SUSPECT_THRESHOLD && cooldownPassed) {
+            s.lastWarnedAt = now;
+            // eslint-disable-next-line no-console
+            console.warn(`[heap-leak] Suspected leak: ${name} — ${bucket.stale} instance(s) unmounted >${LEAK_AGE_MS / 1000}s ago still retained (live ${bucket.live} total)`);
+        }
+    });
+}
+function report() {
+    const now = Date.now();
+    const perName = bucketLiveEntries();
+    const rows = [];
+    perName.forEach((bucket, name) => {
+        const s = getStats(name);
+        rows.push({
+            component: name,
+            live: bucket.live,
+            stale: bucket.stale,
+            lastRenderSecsAgo: Number(((now - s.lastRegisteredAt) / 1000).toFixed(1)),
+        });
+    });
+    rows.sort((a, b) => b.stale - a.stale || b.live - a.live);
+    // eslint-disable-next-line no-console
+    console.table(rows);
+    return rows;
+}
+function forceGc() {
+    const w = window;
+    if (typeof w.gc === "function") {
+        w.gc();
+        // eslint-disable-next-line no-console
+        console.info("[heap-leak] window.gc() invoked; re-sweeping.");
+    }
+    else {
+        // eslint-disable-next-line no-console
+        console.info('[heap-leak] window.gc not available. Start Chrome with --js-flags="--expose-gc" to enable.');
+    }
+    sweep();
+}
+const api = { track, markMounted, markUnmounted, sweep, report, forceGc };
+if (typeof window !== "undefined") {
+    window.__heapTracker = api;
+}
+let intervalId = null;
+function startSweepLoop() {
+    if (typeof document === "undefined")
+        return;
+    if (intervalId !== null)
+        return;
+    intervalId = setInterval(() => {
+        if (typeof document !== "undefined" &&
+            document.visibilityState === "visible")
+            sweep();
+    }, SWEEP_INTERVAL_MS);
+}
+if (typeof window !== "undefined") {
+    startSweepLoop();
+    // eslint-disable-next-line no-console
+    console.info("[heap-leak] tracker installed. Run window.__heapTracker.report() for a live table.");
+}
+export {};

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "react-memory-leak-detector",
+  "version": "0.1.0",
+  "description": "Stop hunting memory leaks with heap snapshots. This babel plugin tags every React component and hook with a uniquely-named marker, then a runtime tracker uses WeakRef + FinalizationRegistry to warn you, live in the console, the moment something leaks.",
+  "keywords": [
+    "react",
+    "memory-leak",
+    "leak-detection",
+    "heap-snapshot",
+    "babel-plugin",
+    "devtools",
+    "weakref",
+    "finalizationregistry",
+    "debugging"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test": "jest"
+  },
+  "exports": {
+    "./babel-plugin": "./babel-plugin.js",
+    "./runtime": "./dist/runtime.js"
+  },
+  "files": [
+    "babel-plugin.js",
+    "dist/",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mvladm14/react-memory-leak-detector.git"
+  },
+  "license": "MIT",
+  "author": "mvladm14",
+  "peerDependencies": {
+    "react": ">=16.8.0"
+  },
+  "engines": {
+    "node": ">=16"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.29.0",
+    "jest": "^30.4.2",
+    "typescript": "^6.0.3"
+  }
+}