@memlab/lens 1.0.2 → 1.0.3

package/README.md

@@ -1,63 +1,161 @@
 # MemLens
 
-## What is this?
+MemLens is a lightweight, in-browser lens for spotting memory issues in React apps. It detects and visualizes:
 
-MemLens is a debugging tool that helps identify memory leaks in React applications. It tracks:
+- Detached DOM elements still retained in memory
+- Unmounted React Fiber nodes that may indicate leaks
+- Event listener leaks (optional)
+- High-level DOM and heap usage stats (overlay header)
 
-- Detached DOM elements that are no longer connected to the document but still held in memory
-- Unmounted React Fiber nodes that haven't been properly cleaned up
-- Memory usage patterns and growth over time
+It can run as a one-line console snippet or as a small library you embed in dev builds.
 
-The tool provides:
+### Key features
 
-1. Real-time memory monitoring through the browser console
-2. Visual representation of problematic DOM elements and React components
-3. Memory usage statistics and trends
+- **Visual overlay**: Highlights detached DOM elements; interactive panel shows counts and the React component stack for the selected element
+- **React Fiber analysis**: Scans the fiber tree to attribute elements to components
+- **Event listener leak scan (opt-in)**: Groups leaked listeners by component and type
+- **Non-intrusive**: Uses a transparent overlay and avoids tracking its own UI
 
-This can help developers identify:
-- Components that aren't properly cleaned up
+### Browser support
 
-## How to Build?
+- Requires browsers with WeakRef/FinalizationRegistry support (e.g. modern Chrome, Edge, Safari, Firefox). In older browsers the tool may not function.
+
+---
+
+### Quick start
+
+#### Option A: Run from the browser console (CDN)
+
+Paste this in your app page:
+
+```js
+(() => {
+  const s = document.createElement('script');
+  s.src = 'https://unpkg.com/@memlab/lens/dist/memlens.run.bundle.min.js';
+  s.crossOrigin = 'anonymous';
+  document.head.appendChild(s);
+})();
+```
+
+This injects and starts MemLens with the interactive overlay.
+
+#### Option B: Run from the browser console (local build)
+
+Copy the contents of `packages/lens/dist/memlens.run.bundle.min.js` (or `packages/lens/dist/memlens.run.bundle.js`) and paste into the browser's web console. The overlay starts immediately.
+
+#### Option C: Programmatic scanner (UMD global)
+
+Load the library bundle and use the `MemLens` global:
+
+```html
+<script src="https://unpkg.com/@memlab/lens/dist/memlens.lib.bundle.min.js"></script>
+<script>
+  // Create a scanner (no overlay by default; use the run bundle for overlay)
+  const scan = MemLens.createReactMemoryScan({
+    isDevMode: true,
+    scanIntervalMs: 1000,
+    trackEventListenerLeaks: true, // optional
+  });
+
+  const unsubscribe = scan.subscribe((result) => {
+    console.log('[MemLens]', {
+      totalElements: result.totalElements,
+      detached: result.totalDetachedElements,
+      eventListenerLeaks: result.eventListenerLeaks,
+    });
+  });
+
+  scan.start();
+
+  // Later: scan.stop(); unsubscribe(); scan.dispose();
+</script>
+```
+
+Note: The visualization overlay is provided by the self-starting "run" bundle (Option A/B/D). The library bundle focuses on scanning APIs.
+
+#### Option D: Node/Puppeteer injection
+
+`@memlab/lens` exposes a helper to retrieve the self-starting bundle as a string for script injection:
+
+```js
+// Node
+const {getBundleContent} = require('@memlab/lens');
+
+// Puppeteer example
+await page.addScriptTag({content: getBundleContent()});
+```
+
+---
+
+### Overlay controls and interactions
+
+- **Toggle switch**: Show/hide all overlay rectangles
+- **Select/pin**: Click a rectangle to pin/unpin the current selection
+- **Hover**: Reveal the selection chain of related detached elements
+- **Component stack panel**: Shows the React component stack of the selected element
+- **Keyboard**: Press `D` to temporarily ignore the currently selected element in the overlay
+- **Widget**: The control widget is draggable
+
+Notes:
+- The overlay ignores its own UI elements and won’t count them as part of the page.
+- In dev mode, MemLens logs basic timing and scan stats to the console.
+
+---
+
+### Configuration (CreateOptions)
+
+```ts
+type CreateOptions = {
+  isDevMode?: boolean;                // enable console logs and dev-only behaviors
+  subscribers?: Array<(r) => void>;   // observers of each scan result
+  extensions?: Array<BasicExtension>; // e.g., DOMVisualizationExtension
+  scanIntervalMs?: number;            // default ~1000ms
+  trackEventListenerLeaks?: boolean;  // enable listener leak scanning
+};
+```
+
+Core API (`ReactMemoryScan`):
+- `start()`, `pause()`, `stop()`, `dispose()`
+- `subscribe(cb) => () => void`
+- `registerExtension(ext) => () => void`
+
+---
+
+### Build
 
 ```bash
+# from packages/lens
+npm run build
+# or
 webpack
 ```
 
-## How to Test?
+### Test
 
-1. Install Playwright
+1) Install Playwright dependencies (first time):
 
 ```bash
 npx playwright install
 npx playwright install-deps
 ```
 
-2. Run the test
+2) Run tests:
 
 ```bash
 npm run test:e2e
 ```
 
-3. Test manually by copying and pasting the content of `dist/run.bundle.js`
-into web console
-
-
-## TODO List
- * Note that document.querySelectorAll('*') only captures DOM elements on the DOM tree
-   * So the DOM tree scanning and component name analysis must be done in a frequent interval (every 10s or so)
- * Extensible framework for tracking additional metadata
- * Auto diffing and counting detached Element and unmounted Fiber nodes
-   * being able to summarize the leaked components that was not reported (this can reduce the report overhead)
- * Improve the DOM visualizer - only visualize the common ancestors of the detached DOM elements and unmounted fiber nodes
- * Improving the scanning efficiency so that the overhead is minimal in production environment
- * Improve the fiber tree traversal efficiency (there are redundant traversals right now)
- * Not only keep track of detached DOM elements, but also keep track of unmounted fiber nodes in WeakMap and WeakSet
- * DOM visualizer is leaking canvas DOM elements after each scan
- * Monitor event listener leaks?
- * Real-time memory usage graphs
- * Real-time component count and other react memory scan obtained stats graphs
- * Component re-render heat maps
- * Interactive component tree navigation
- * Browser extension integration
- * centralized config file
- * centralized exception handling
+3) Manual test: open `src/tests/manual/todo-list/todo-with-run.bundle.html` in a browser, or copy/paste `dist/memlens.run.bundle.js` to the DevTools console on any React page.
+
+---
+
+### Learn more
+
+Please check out this
+[tutorial page](https://facebook.github.io/memlab/docs/guides/visually-debug-memory-leaks-with-memlens)
+on how to use MemLens (a debugging utility) to visualize memory leaks in the
+browser for easier memory debugging.
+
+### License
+
+MIT © Meta Platforms, Inc.

package/dist/core/react-memory-scan.d.ts

@@ -21,6 +21,7 @@ export default class ReactMemoryScan {
     start(): void;
     pause(): void;
     stop(): void;
+    dispose(): void;
     recordBoundingRectangles(elementRefs: Array<WeakRef<Element>>): void;
     getDetachedDOMInfo(): Array<DOMElementInfo>;
     isDevMode(): boolean;

package/dist/extensions/dom-visualization-extension.d.ts

@@ -14,4 +14,5 @@ export declare class DOMVisualizationExtension extends BasicExtension {
     #private;
     constructor(scanner: ReactMemoryScan);
     afterScan(_analysisResult: AnalysisResult): void;
+    cleanup(): void;
 }

package/dist/index.js

@@ -36,25 +36,15 @@ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (
 }) : function(o, v) {
     o["default"] = v;
 });
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
 Object.defineProperty(exports, "__esModule", ({ value: true }));
-exports.getBundleContent = getBundleContent;
+exports.getBundleContent = void 0;
 /**
  * Copyright (c) Meta Platforms, Inc. and affiliates.
  *
@@ -70,6 +60,7 @@ function getBundleContent() {
     const bundlePath = path.join(__dirname, 'memlens.run.bundle.min.js');
     return fs.readFileSync(bundlePath, 'utf-8');
 }
+exports.getBundleContent = getBundleContent;
 
 
 /***/ })