doc(lens): update lens README and tutorial

Summary: This diff updates the MemLens package README file.

Differential Revision: D80422996

fbshipit-source-id: e15e40732d4009b5341244f8061918b12c71ee4d

Author: JacksonGL

README.md

@@ -190,7 +190,7 @@ memlab.run({scenario});
 
 ## Visual Debugging for Memory Leaks in Browser
 
-Check out this [tutorial page](https://facebook.github.io/memlab/docs/guides/visually-debug-memory-leaks-with-memlens)
+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.
 

packages/lens/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.

website/docs/guides/06-visually-debug-leaks-with-memlens.mdx

@@ -5,7 +5,8 @@ id: 'visually-debug-memory-leaks-with-memlens'
 # Visual Debugging for Memory Leaks
 
 Memory Lens (MemLens) is a utility tool that helps visually debug memory leaks
-in web browsers. It highlights leaking components with an overlay,
+in web browsers. It highlights detached DOM elements still retained in memory
+and leaking React components with an overlay,
 allowing you to identify leaked elements right after interactions and
 trace their retainer paths in the browser’s DevTools using memory IDs
 annotated by MemLens.