rerender-lens 0.4.0 → 0.5.0

package/README.md

@@ -1,449 +1,280 @@
 # rerender-lens
 
-Find avoidable React re-renders and see exactly what caused them: which prop, which state,
-which context, and which ancestor started the update.
+Find avoidable React re-renders and see exactly what caused them: which prop, state or context,
+which ancestor started the cascade, and the fix.
 
-It reads the fiber tree after every commit through the same global hook React DevTools uses.
-Nothing in React is patched or wrapped, so it works with Fast Refresh, `React.memo` comparators,
-`forwardRef`, class components, the automatic JSX runtime, and any bundler.
+It reads the fiber tree after each commit through the same global hook React DevTools uses.
+Nothing in React is patched, so it works with Fast Refresh, `React.memo`, `forwardRef`, class
+components and any bundler.
 
 ```
 ▸ [rerender-lens] <ProductRow> avoidable re-render: 1 equal by value, 1 new function
     - caused by <ProductPage> re-rendering (its state changed).
-    - prop "style" is a new reference but deep-equal to the previous value: memoize the object with useMemo, or hoist it to module scope if it is constant.
-    - prop "onSelect" is a new function instance on every render: wrap it in useCallback (or hoist it out of the parent's render).
+    - prop "style" is a new reference but deep-equal to the previous value: memoize it with useMemo, or hoist it.
+    - prop "onSelect" is a new function instance on every render: wrap it in useCallback.
     at App > ProductPage > ProductRow
 ```
 
-Two ways to use it: the **DevTools extension** (a "Re-renders" panel next to Elements and
-Console, no app code needed) or the **npm package** (console output, test assertions, and the
-bridge the extension reads).
+## Pick a way in
 
-## Chrome extension
-
-The extension adds a **Re-renders** panel to DevTools: a component tree with avoidable counts,
-why each component rendered, which ancestor started the cascade, the props and hooks that
-changed, and the fix as a snippet you can copy. Other views rank components by wasted renders
-(Offenders), group renders by React commit with their root cause (Commits), and rank every fix
-by how many re-renders it removes (Fixes). It also gives you an Elements-panel sidebar for the
-selected node, a badge with the avoidable count of the tab, hover-to-highlight in the page, and
-"open source" links into the Sources panel.
-
-### Install
-
-Until the Web Store listing is live, install it unpacked:
-
-1. Download `rerender-lens-chrome-<version>.zip` from the
-   [latest release](https://github.com/NexaLeaf/rerender-lens/releases) and unzip it, or build it
-   from a clone with `npm install && npm run build` and use the `extension/` folder.
-2. Open `chrome://extensions`, turn on **Developer mode**, click **Load unpacked**, pick the folder.
-3. Open your app, open DevTools, pick the **Re-renders** tab.
-
-Edge loads the same folder from `edge://extensions`. Firefox 128+ uses the `firefox` zip from the
-release, via `about:debugging`.
-
-### Connect a page
-
-Local development hosts (`localhost`, `127.0.0.1`, `*.localhost`, `*.local`) work out of the box.
-Any other site: click the toolbar icon and **Enable on this site** (a one-time host permission
-for that origin only).
-
-Then pick one of two modes:
-
-- **Inject the library** (no app code): tick *Inject the library* in the toolbar popup or in the
-  panel's Settings and reload. The extension loads rerender-lens into the page before React,
-  tracking every `React.memo` / `PureComponent` by default, without the hook/context/state
-  snapshots (*Include state* in Settings turns them on; they are the costliest part on big
-  apps). Change what is tracked from Settings; the choice is saved per origin.
-- **The page runs the library**: install the package and pass the DevTools notifier (see below).
-  This is the way to go when you also want console output or want to commit the setup.
+| You have | Do this | You get |
+| --- | --- | --- |
+| Any React app, no code changes | Install the [DevTools extension](#devtools-extension) | A **Re-renders** panel in DevTools |
+| A Vite app | `rerenderLens()` in `vite.config.ts` | Console output, the panel at `/__rerender-lens/`, no extension needed |
+| Next.js, Webpack, anything else | `import 'rerender-lens/setup'` + `npx rerender-lens panel` | The same panel in any browser tab |
+| Tests | `rerender-lens/vitest`, `rerender-lens/jest` or `rerender-lens/playwright` | Failing tests and CI budgets for avoidable re-renders |
+
+## DevTools extension
+
+Adds a **Re-renders** tab: the component tree with avoidable counts, why each component rendered,
+the props and hooks that changed, and the fix as a snippet. Other views rank components by wasted
+renders (Offenders), group renders by React commit with their root cause (Commits), rank every fix
+by how many re-renders it removes (Fixes), and compare a recording before and after a fix
+(Sessions). Also: an Elements-panel sidebar, a badge with the tab's avoidable count, hover to
+highlight in the page, "open source" links, and the same panel next to the page (side panel) or
+in its own window.
+
+**Install** (until the Web Store listing is live): download `rerender-lens-chrome-<version>.zip`
+from the [latest release](https://github.com/NexaLeaf/rerender-lens/releases), unzip it, open
+`chrome://extensions`, turn on *Developer mode*, *Load unpacked*, pick the folder. Edge loads the
+same folder; Firefox 128+ uses the `firefox` zip via `about:debugging`.
+
+**Connect a page.** Local hosts (`localhost`, `127.0.0.1`, `*.localhost`, `*.local`) work out of
+the box; for any other site click the toolbar icon and *Enable on this site*. Then either tick
+*Inject the library* (the extension loads rerender-lens before React; no app code) or let the page
+run the library itself:
 
 ```ts
 import { init, createDevtoolsNotifier } from 'rerender-lens';
 init({ trackAllMemoized: true, silent: true, notifier: createDevtoolsNotifier() });
 ```
 
-Production React builds are detected and flagged (names may be minified, hooks unlabeled). If
-React DevTools is also installed and its Components tab comes up empty with injection on, tick
-*Let React DevTools create the hook* for that origin.
-
-`extension/README.md` has the details: keyboard shortcuts, how the transport works, Firefox and
-Edge packaging, and the store listing.
+Injection tracks every `memo` / `PureComponent` and leaves the hook/context/state snapshots off
+(*Include state* in Settings turns them on; they are the costliest part on large apps). Settings
+are saved per origin. Details, shortcuts and packaging: [`extension/README.md`](extension/README.md).
 
-## Install the package
-
-```sh
-npm i -D rerender-lens
-```
-
-Peer dependency: `react >= 16.8`. Tested with React 18 and 19.
-
-## One-line setup per bundler
-
-**Vite** (recommended for Vite users: no extension injection, no permissions, one line):
+## Vite
 
 ```ts
 // vite.config.ts
 import { rerenderLens } from 'rerender-lens/vite';
-
-export default defineConfig({
-  plugins: [react(), rerenderLens({ trackAllMemoized: true })],
-});
+export default defineConfig({ plugins: [react(), rerenderLens({ trackAllMemoized: true, panel: true })] });
 ```
 
-The plugin injects a module before your entry in dev (`vite build` is untouched) that calls
-`init` with your options plus the DevTools notifier. Matchers can be strings or RegExps;
-`devtools: false` skips the bridge, `applyInBuild: true` keeps it in builds, `pages: ['/']`
-limits which HTML pages get it.
+Dev only (`vite build` is untouched). `panel: true` serves the panel at
+`http://localhost:5173/__rerender-lens/`; the app and the panel talk over a same-origin
+`BroadcastChannel`, so no extension is needed. `pages: ['/']` limits which HTML pages get the
+setup script; `devtools: false` skips the bridge.
 
-**No extension at all**: add `panel: true` and open `http://localhost:5173/__rerender-lens/` in a
-second tab. The dev server serves the same panel the extension uses; the app publishes reports on
-a same-origin `BroadcastChannel` and the panel sends settings and highlight commands back over it.
-Panel state lives in `localStorage`. (`channel` renames the channel, `panel: '/some/path/'` moves
-the mount.)
-
-**Next.js** (App or Pages router): run it before React from the client instrumentation file:
+## Next.js, Webpack, anything
 
 ```ts
-// instrumentation-client.ts
+// Next.js: instrumentation-client.ts        // Webpack / Rspack: entry: ['rerender-lens/setup', './src/index.tsx']
 import 'rerender-lens/setup';
 ```
 
-**Webpack / Rspack / others**: put the setup entry first:
-
-```js
-entry: ['rerender-lens/setup', './src/index.tsx'],
-```
-
-`rerender-lens/setup` is a side-effect module that calls
-`init({ trackAllMemoized: true, notifier: createDevtoolsNotifier() })` unless
-`process.env.NODE_ENV === 'production'` or the page already runs the library. Use `configure()`
-afterwards to change options, or the extension's Settings.
-
-**The panel for any app, no extension, no Vite** (Next.js, Webpack, a remote dev box, a phone):
+The setup entry starts the library with every `memo` / `PureComponent` tracked, outside
+production builds. To see the panel without the extension:
 
 ```sh
-npx rerender-lens panel          # http://127.0.0.1:4141/ serves the panel and relays messages
+npx rerender-lens panel           # http://127.0.0.1:4141/  (--port, --host 0.0.0.0 for another machine)
 ```
 
-Point the app at it and open the printed URL in any browser:
-
-```ts
-init({ trackAllMemoized: true, notifier: createDevtoolsNotifier({ relay: 'http://127.0.0.1:4141' }) });
-// or, with rerender-lens/setup: RERENDER_LENS_RELAY=http://127.0.0.1:4141 (NEXT_PUBLIC_RERENDER_LENS_RELAY for Next.js)
-// or, before the app loads: window.__RERENDER_LENS_RELAY__ = 'http://127.0.0.1:4141'
-```
+and point the app at it with `RERENDER_LENS_RELAY=http://127.0.0.1:4141`
+(`NEXT_PUBLIC_RERENDER_LENS_RELAY` for Next.js), `createDevtoolsNotifier({ relay })`, or
+`window.__RERENDER_LENS_RELAY__` set before the app loads. Settings, highlight and replay travel
+back to the app; several apps or panels can share one relay.
 
-The app streams commands in over server-sent events and posts hello, reports and replies back; the
-panel connects the same way (`panel.html?relay=…`), so Settings, highlight and replay all work.
-Several apps or panels can share one relay; the panel re-attaches when an app reloads.
-`--port` and `--host` change where it listens (`--host 0.0.0.0` for another machine).
-
-## Setup
+## Manual setup
 
 ```ts
-// src/rerender-lens.ts
 import { init } from 'rerender-lens';
-
-if (import.meta.env.DEV) {
-  init({ trackAllMemoized: true });
-}
-```
-
-```ts
-// src/main.tsx
-import './rerender-lens';
-import { createRoot } from 'react-dom/client';
-...
-```
-
-Import the setup file before `react-dom`. React DOM looks for the DevTools hook once, when its
-module loads; `init` creates the hook if nothing else did. If the React DevTools extension is
-installed, or Vite's Fast Refresh preamble runs, the hook already exists and order does not matter.
-
-No `jsxImportSource`, no default-import requirement, no Babel plugin.
-
-## Choosing what to track
-
-```ts
-init({
-  trackAllMemoized: true,        // every React.memo and PureComponent
-  include: [/^Grid/, 'Sidebar'], // by display name: string, RegExp or predicate
-  exclude: ['DevOverlay'],
-});
-```
-
-Or mark a component:
-
-```ts
-import { track } from 'rerender-lens';
-
-export const ProductRow = track(function ProductRow(props: Props) { ... });
-export default track(memo(Sidebar));
-export const Cell = track((props: CellProps) => ..., 'Cell'); // name for anonymous arrows
-```
-
-Marking sets the static `rerenderLens = true`; you can also set it by hand. `configure()`
-changes any option at runtime without remounting anything.
-
-## What a report contains
-
-Every update of a tracked component produces a `RenderReport`:
-
-| Field | Meaning |
-| --- | --- |
-| `component` | display name |
-| `trigger` | `props`, `parent`, `state`, `hooks` or `mixed` |
-| `avoidable` | `true` when nothing genuinely changed |
-| `propChanges` | one entry per changed prop with `path`, `kind`, `prev`, `next` |
-| `stateChanges` | class components: `this.state` diff |
-| `hookChanges` | `useState`, `useReducer`, `useSyncExternalStore` and `useContext` values that changed; context entries carry `provider` (who renders it) and `changedKeys` / `totalKeys` for object values |
-| `hookState`, `contexts`, `state` | current value of every state hook, every context read, and class `this.state` (off with `includeState: false`) |
-| `updaters` | components that scheduled the commit (`setState`, dispatch), from React's updater tracking |
-| `commitCause`, `afterCommit` | `effect-after-commit` (an effect of the previous commit set state) or `suspense-resolved` |
-| `key` | the element's `key`, when it has one |
-| `parent` | nearest ancestor that rendered in the same commit, and why |
-| `owner` | component that created the element (dev builds) |
-| `path` | component ancestry from the root |
-| `instanceId`, `renderCount` | stable per mounted instance |
-| `memoized` | `React.memo` / `PureComponent`: props alone decide whether it re-renders |
-| `selfDuration`, `treeDuration` | own render time, and with everything below that rendered (dev/profiling builds) |
-| `commitId` | shared by every report of one React commit |
-| `commitPriority` | `immediate` (clicks, keys), `user-blocking` (continuous input), `normal` (transitions, async), `low`, `idle` |
-| `source` | file, line and column where the element was created (dev builds) |
-| `reasons` | human-readable explanations with the fix |
-
-Change kinds:
-
-| `kind` | Means | Fix |
-| --- | --- | --- |
-| `deep-equal` | new reference, same contents | `useMemo`, or hoist a constant |
-| `function` | new function, same body | `useCallback` |
-| `element` | new element, same type and props | `useMemo` the element or pass it as `children` |
-| `different` | a real change | none needed |
-| `added` / `removed` | key appeared or disappeared | usually a real change |
-
-A `parent` trigger with no changes at all means: identical props, an ancestor re-rendered.
-Wrap the component in `React.memo`.
-
-By default only avoidable re-renders are printed; pass `logAll: true` to print every report.
-The `notifier` always receives every report.
-
-## Use in tests
-
-```ts
-import { init, disable, createCollector } from 'rerender-lens';
-
-const collector = createCollector();
-beforeAll(() => init({ trackAllMemoized: true, silent: true, notifier: collector.notifier }));
-afterAll(disable);
-beforeEach(collector.clear);
-
-test('typing in the search box does not re-render the grid rows', async () => {
-  render(<ProductPage />);
-  await user.type(screen.getByRole('searchbox'), 'abc');
-  collector.assertNoAvoidable(); // throws listing every component and reason
-  // or: expect(collector.avoidable).toHaveLength(0)
-});
+if (import.meta.env.DEV) init({ trackAllMemoized: true, include: [/^Grid/, 'Sidebar'], exclude: ['DevOverlay'] });
 ```
 
-In Vitest or Jest, call `ensureDevtoolsHook()` (or `init`) from a `setupFiles` entry so the hook
-exists before `react-dom` is imported by your tests.
+Import it before `react-dom` (React looks for the DevTools hook once, when it loads). Mark single
+components with `track(Comp)` or `Comp.rerenderLens = true`; `configure()` changes options at
+runtime. Inside a library or Storybook, `useWhyRerender('Row', { ...props, theme })` reports one
+component without `init`.
 
-### Vitest, whole suite
+## Tests and CI
 
-Two config lines collect every avoidable re-render across the run and print the ranked fixes at
-the end; a budget file turns it into a gate:
+**Vitest**, whole suite, two config lines:
 
 ```ts
-// vitest.config.ts
 test: {
   setupFiles: ['rerender-lens/vitest/setup'],
-  reporters: ['default', ['rerender-lens/vitest', { budget: 'rerender-budget.json', exportTo: 'rerender-lens.json' }]],
+  reporters: ['default', ['rerender-lens/vitest', { budget: 'rerender-budget.json' }]],
 }
 ```
 
-The setup entry starts the library (all memoized components, silent) in every test file and hands
-the file's reports to the reporter; the reporter prints `rerender-lens: N reports, M avoidable`
-with the fixes, fails the run on budget violations, and can write a panel-compatible export
-(`Sessions > Import` in the extension). For other options, or per-test assertions, write your own
-setup file:
+The reporter prints the run's ranked fixes and root causes, fails on budget violations, and can
+write a panel-compatible export. Custom options: `setupRerenderLens(options, { afterAll })`.
 
-```ts
-import { afterAll } from 'vitest';
-import { setupRerenderLens } from 'rerender-lens/vitest';
-export const lens = setupRerenderLens({ include: [/^Grid/], failFast: true }, { afterAll });
-// lens.collector.assertNoAvoidable() inside a test
+**Jest**, the same two lines (`setupFilesAfterEnv`, not `setupFiles`: the hook needs `afterAll`):
+
+```js
+// jest.config.js
+module.exports = {
+  testEnvironment: 'jsdom',
+  setupFilesAfterEnv: ['rerender-lens/jest/setup'],
+  reporters: ['default', ['rerender-lens/jest', { budget: 'rerender-budget.json' }]],
+};
 ```
 
-### Playwright, real browser
+Same options and same output as the Vitest reporter; a budget violation fails the run.
+
+**Playwright**, real browser:
 
 ```ts
 import { installRerenderLens, pullReports, expectWithinBudget } from 'rerender-lens/playwright';
-
-test('search does not re-render the grid', async ({ page }) => {
-  await installRerenderLens(page, { include: ['ProductRow'] }); // before goto: runs before React
-  await page.goto('/products');
-  await page.getByRole('searchbox').fill('abc');
-  expectWithinBudget(await pullReports(page), { '*': 0 });     // throws with the ranked fixes
-});
+await installRerenderLens(page, { include: ['ProductRow'] }); // before page.goto
+await page.goto('/products');
+expectWithinBudget(await pullReports(page), { '*': 0 });     // throws with the ranked fixes
 ```
 
-`installRerenderLens` injects the same bundle the extension uses at document start, so it works on
-any build the browser can load (production builds are flagged; names may be minified). Pass
-`relay: 'http://127.0.0.1:4141'` to watch the run in the panel, `clearReports(page)` between
-scenarios.
-
-### Budgets and comparisons in CI
+**Any test runner**, per test:
 
 ```ts
-// allow known offenders, fail on anything new or worse
-collector.assertWithinBudget(JSON.parse(readFileSync('rerender-budget.json', 'utf8')));
-// produce the baseline once: writeFileSync('rerender-budget.json', JSON.stringify(toBudget(collector.reports)))
-collector.fixes();            // ranked fixes, most re-renders removed first
-collector.summary('after');   // a session summary, comparable with compareSummaries()
+const collector = createCollector();
+beforeAll(() => init({ trackAllMemoized: true, silent: true, notifier: collector.notifier }));
+test('search does not re-render the rows', () => { /* ... */ collector.assertNoAvoidable(); });
 ```
 
-The `rerender-lens` CLI does the same with files from the extension (Export) or from `summary()`:
+**CLI**, on a panel export or a session summary:
 
 ```sh
-npx rerender-lens fixes export.json                 # ranked fixes
-npx rerender-lens summary export.json --out before.json
-npx rerender-lens compare before.json after.json    # per-component deltas; exit 1 on regressions
+npx rerender-lens fixes export.json                        # ranked fixes, then root causes
+npx rerender-lens causes export.json                       # which component started each cascade
 npx rerender-lens budget export.json --init > rerender-budget.json
-npx rerender-lens budget export.json rerender-budget.json   # exit 1 when a component exceeds its budget
-npx rerender-lens panel [--port 4141] [--host 127.0.0.1]     # the panel + relay for any app (see above)
+npx rerender-lens budget export.json rerender-budget.json  # exit 1 when a component exceeds its budget
+npx rerender-lens summary export.json --out before.json && npx rerender-lens compare before.json after.json
 ```
 
-## Track a single component from the inside
-
-Works anywhere without `init`, for example inside library packages or Storybook:
-
-```ts
-import { useWhyRerender } from 'rerender-lens';
+## What a report says
 
-function Row(props: RowProps) {
-  const theme = useContext(ThemeContext);
-  useWhyRerender('Row', { ...props, theme });
-  ...
-}
-```
+Every re-render of a tracked component is a `RenderReport`. The fields you will read:
 
-Pass whatever values you want compared.
-
-## DevTools bridge
-
-```ts
-import { createDevtoolsNotifier } from 'rerender-lens';
-
-init({ trackAllMemoized: true, silent: true, notifier: createDevtoolsNotifier() });
-```
-
-Each report is serialized (functions become `ƒ name`, elements `<Type>`, cycles cut) and posted
-on `window` as `{ __rerenderLens: true, version: 2, type: 'report', payload }`. Reports go on
-`window` only after a listener announced itself (`{ __rerenderLensReady: true }`, which the
-extension's content script posts) or after `replay()`, so a page nobody inspects pays no
-structured clone per report. Values are bounded: 100 entries per array/object/Map/Set, depth 4
-by default (`maxDepth`), 20k nodes per report. The last 300 reports are buffered. The bridge
-at `window.__RERENDER_LENS_DEVTOOLS__` exposes:
-
-| Method | |
+| Field | Meaning |
 | --- | --- |
-| `replay()` / `clear()` | re-post or drop the buffer |
-| `pull(since)` | reports newer than a sequence number, for panels that poll instead of listening |
-| `info()` | library version, protocol, React renderers (version, dev/prod), current options |
-| `configure(options)` / `getOptions()` | change options at runtime; matchers as strings (`"/^Grid/"`) |
-| `highlight(instanceId)` / `flashAvoidable(on)` | outline a component's DOM in the page, or flash avoidable renders |
-| `inspect(node)` | component, instance id and recent reports for a DOM node (DevTools `$0`) |
+| `component`, `path`, `owner` | display name, ancestry from the root, who created the element |
+| `trigger` | `props`, `parent`, `state`, `hooks` or `mixed` |
+| `avoidable` | `true` when nothing genuinely changed |
+| `propChanges`, `stateChanges`, `hookChanges` | what changed: `path`, `kind`, `prev`, `next`; context entries name the provider and the changed keys |
+| `hookState`, `contexts`, `state` | every hook, context and class state value (`includeState`) |
+| `parent`, `updaters` | the ancestor that rendered in the same commit and why; the components that scheduled the commit |
+| `commitId`, `commitPriority`, `commitCause` | one id per React commit; discrete input / transition / idle; `effect-after-commit` or `suspense-resolved` |
+| `selfDuration`, `treeDuration`, `source` | render time (dev/profiling builds); file, line and column of the element |
+| `reasons` | the explanations with the fix, as printed |
 
-The DevTools extension consumes this (see [Chrome extension](#chrome-extension) above); with
-injection enabled it needs no `init` call at all.
+| `kind` | Means | Fix |
+| --- | --- | --- |
+| `deep-equal` | new reference, same contents | `useMemo`, or hoist a constant |
+| `function` | new function, same body | `useCallback` |
+| `element` | new element, same type and props | `useMemo` the element or pass it as `children` |
+| `different` | a real change | none |
 
-Every report also carries `commitId` (shared by all reports of one React commit) and, in dev
-builds, `source` (where the element was created).
+A `parent` trigger with no changes means identical props and an ancestor re-rendered: wrap the
+component in `React.memo`.
 
-## API
+## What counts as avoidable
 
-```ts
-init(options?): () => void              // returns disable
-configure(options): void                // merge options at runtime
-disable(): void
-isEnabled(): boolean
-track(component, name?): component
-ensureDevtoolsHook(): hook              // create the global hook early (test setup files)
-// 'rerender-lens/vite': rerenderLens(options), renderSetupModule(options)
-// 'rerender-lens/setup': side-effect entry (init with defaults outside production)
-// 'rerender-lens/relay': createRelayServer({ port?, host? }) — what `rerender-lens panel` runs
-// 'rerender-lens/playwright': installRerenderLens(page, options?), pullReports(page), clearReports(page), expectWithinBudget(reports, budget)
-// 'rerender-lens/vitest': setupRerenderLens(options?, { afterAll }), default reporter ({ budget?, exportTo?, limit? }); 'rerender-lens/vitest/setup'
-useWhyRerender(name, values, options?)
-createCollector(): { reports, avoidable, notifier, clear, assertNoAvoidable, fixes, summary, assertWithinBudget }
-rankFixes(reports), formatFixes(reports)          // ranked fixes
-summarizeReports(reports), compareSummaries(a, b), formatComparison(c), parseExport(json)
-checkBudget(reports, budget), toBudget(reports), assertWithinBudget(reports, budget)
-combineNotifiers(...notifiers): Notifier
-createDevtoolsNotifier({ bufferSize?, target?, maxDepth?, flashAvoidable?, channel?, relay? }): Notifier
-getRenderers(), isProductionReact()       // what react-dom registered on the DevTools hook
-serializeOptions(o), deserializeOptions(o) // Options <-> JSON-safe form used by the bridge
-VERSION
-deepEqual(a, b), diffRecords(prev, next), classify(prev, next)
-```
+`avoidable` is true when the render produced no genuine change in props, state or hooks *and*
+nothing about the situation explains the render away. The rules, on the shapes modern apps produce
+(each row is a test in `test/modern.test.ts` and a card on the example's `/modern.html`):
 
-`Options`:
+| Situation | Verdict | Why / fix |
+| --- | --- | --- |
+| Parent re-rendered, identical props, plain function or class component | avoidable, `parent` | wrap in `React.memo`; classes: extend `PureComponent` or implement `shouldComponentUpdate` |
+| Same, but the component is compiled by React Compiler (`compiled: true`) | **not avoidable** | React still calls it, but its output comes from the memo cache and the render is cheap; a compiled app re-renders every component on a parent update and flagging them all would be noise. A new-but-equal prop (`deep-equal`, `function`, `element`) still misses the cache and stays avoidable, with the upstream fix and no `React.memo` advice |
+| `memo` / `PureComponent` / `shouldComponentUpdate → false` with equal props | no report | React bailed out; the component never rendered |
+| Inline object, array or element prop (`deep-equal`, `element`) | avoidable | `useMemo`, hoist constants, pass static elements as `children` from a stable parent |
+| Inline callback or render prop (`function`), e.g. `renderItem={(x) => …}` on a memo list | avoidable | `useCallback` or hoist it. **Limitation:** functions are compared by name and source, so a new closure with the same text that captures a *changed* value is still `function` and counted as avoidable, even though its output differs |
+| `ref` is a new `{ current }` object on every render (React 19 keeps `ref` in props; forwardRef and memo see it) | avoidable, `deep-equal` on `ref` | `useRef` (or `createRef` outside the render); `.current` is ignored because React mutates it when it re-attaches the ref. An inline callback ref is `function`: `useCallback` |
+| `useSyncExternalStore` / store selector returning a new object with equal contents | avoidable, hook `deep-equal` | store-specific advice: return a stored slice, `shallowEqual` / `createSelector` (Redux), `useShallow` (Zustand), or cache the snapshot. A selector returning a primitive does not render at all |
+| `useState`/`setState` with a value deep-equal to the current one | avoidable | reuse the existing object or bail out before calling the setter |
+| A genuine prop, state, context or store change | not avoidable (`props` / `state` / `hooks` / `mixed`) | the change is listed with its path |
+| `startTransition(() => setState(…))` | parent: `state` at `commitPriority: 'normal'`, not avoidable; memo children with equal props: no report | nothing to fix |
+| Content revealed by a Suspense boundary (`use(promise)` resolved, `React.lazy` loaded) | **not avoidable**, `commitCause: 'suspense-resolved'` | React re-renders the content it kept hidden while the fallback was shown; the component that suspended has a genuinely new promise (`props`). Components outside the boundary in the same commit keep the usual verdict |
+| The deferred second render of `useDeferredValue` (dev builds) | not avoidable, `hooks` with a `useDeferredValue` change | React's catch-up render; it is also never mistaken for an effect → setState loop. `useId` and a stable deferred input add no hook changes |
+| Mount, StrictMode's double render, a Fast Refresh commit | no report | never reported (StrictMode is one commit) |
+
+## Options
 
 | Option | Default | |
 | --- | --- | --- |
 | `trackAllMemoized` | `false` | track every `memo` / `PureComponent` |
 | `trackAllComponents` | `false` | track everything (noisy) |
-| `include` / `exclude` | | display-name matchers |
+| `include` / `exclude` | | display-name matchers: string, RegExp or predicate |
 | `trackHooks` | `true` | diff hook state and contexts |
-| `includeState` | `true` (`false` when injected by the extension) | put every hook, context and class state value on each report; the costliest option on large trees |
-| `resolveHookNames` | `false` | label hooks with the custom hooks that own them (`useCart › useState#0`); re-runs each component type once |
+| `includeState` | `true` (`false` when injected) | put every hook, context and class state value on each report; the costliest option on large trees |
+| `resolveHookNames` | `false` | label hooks with the custom hooks that own them (`useCart › useState#0`) |
 | `logAll` | `false` | print non-avoidable reports too |
-| `silent` | `false` | never print; notifier still runs |
+| `silent` | `false` | never print; the notifier still runs |
 | `notifier` | | receives every `RenderReport` |
-| `collapse` | `true` | `console.groupCollapsed` vs `console.group` |
-| `console` | `console` | sink for printing |
 | `ignoreHotReload` | `true` | skip commits caused by Fast Refresh |
 | `maxReportsPerComponent` | `0` | stop printing a component after N reports |
+| `collapse`, `console` | `true`, `console` | console group style and sink |
 
-## How it works, and the caveats that follow
-
-- After each commit, the fiber tree is walked from the root, skipping subtrees React bailed out
-  of. A component counts as re-rendered when React set its `PerformedWork` flag. Props, class
-  state, hook state nodes and context dependencies are compared against the fiber's alternate.
-- Hook labels come from React's dev-only hook type list when it maps one-to-one onto the state
-  nodes; otherwise nodes are labelled by inspection (`useState`, `useReducer`,
-  `useSyncExternalStore`, or `state` for internal nodes of `useTransition` and friends).
-- A commit in which Fast Refresh swapped a component's code is skipped entirely
-  (`ignoreHotReload`). The edited component's children re-render with identical props during
-  that commit, which would otherwise look like avoidable re-renders.
-- The mount render is never reported. StrictMode's double render happens inside one commit and
-  is reported once.
-- Everything runs during React's commit callback, synchronously. It is meant for development;
-  keep it out of production builds.
-- Fiber field names have been stable since React 16.9 (`flags` was `effectTag` before 17; both
-  are handled). Future React versions may change internals; the walk is wrapped so a failure
-  logs one warning instead of breaking the app.
-
-## Example app
-
-`examples/vite-react/scale.html?rows=3000` is the scale test: thousands of memoized cells that all
-re-render avoidably, sharing one large context value and a typed-array prop. Its readout shows
-the library's own cost per commit and how many reports the per-commit cap skipped.
-
-`examples/vite-react` has three deliberate bugs. From the repo root:
+## API
 
-```sh
-npm install
-npm --prefix examples/vite-react install
-npm run dev:example
+```ts
+init(options?): () => void          configure(options)   disable()   isEnabled()
+track(component, name?)             useWhyRerender(name, values, options?)
+ensureDevtoolsHook()                // create the global hook early (test setup files)
+createCollector()                   // { reports, avoidable, notifier, clear, assertNoAvoidable, assertWithinBudget, fixes, summary }
+createDevtoolsNotifier({ bufferSize?, target?, maxDepth?, flashAvoidable?, channel?, relay? })
+rankFixes, formatFixes, rankRootCauses, formatRootCauses, analyzeCommit, rootCauseOf
+summarizeReports, compareSummaries, formatComparison, parseExport
+checkBudget, toBudget, assertWithinBudget
+combineNotifiers, getRenderers, isProductionReact, serializeOptions, deserializeOptions, VERSION
+// rerender-lens/vite       rerenderLens(options)
+// rerender-lens/setup      side-effect entry
+// rerender-lens/relay      createRelayServer({ port?, host? })
+// rerender-lens/vitest     setupRerenderLens(options?, { afterAll }), default reporter; rerender-lens/vitest/setup
+// rerender-lens/playwright installRerenderLens(page, options?), pullReports, clearReports, expectWithinBudget
 ```
 
-`http://localhost:5199/` runs the library through the Vite plugin (console, extension, and the
-built-in panel at `http://localhost:5199/__rerender-lens/`). `http://localhost:5199/plain.html`
-is the same app without the library, for trying the extension's *Inject the library* mode.
-`src/rerender-lens.ts` shows the manual setup for apps without the plugin.
+The bridge at `window.__RERENDER_LENS_DEVTOOLS__` (`replay`, `clear`, `pull`, `info`, `configure`,
+`highlight`, `flashAvoidable`, `inspect`) is what the extension and the panels talk to. Reports are
+serialized with bounds (100 entries per container, depth 4, 20k nodes per report) and posted on
+`window` only once a listener announced itself, so a page nobody inspects pays nothing per report.
+
+## How it works
+
+- After each commit the fiber tree is walked from the root, skipping subtrees React bailed out
+  of. A component rendered when React set its `PerformedWork` flag; props, class state, hook
+  nodes and context reads are compared with the fiber's alternate.
+- Work per commit is bounded: equality is memoized across the commit and gives up on values too
+  large to walk, at most 200 components are reported per commit (the rest is counted in
+  `info().truncated`), and a commit stops after 25 ms.
+- A commit in which Fast Refresh swapped a component's code is skipped. Mounts are never reported;
+  StrictMode's double render is one commit and reports once.
+- Development only: everything runs inside React's commit callback. Production builds are
+  detected and flagged (names may be minified).
+- Fiber fields have been stable since React 16.9; the walk is wrapped so a change in React logs
+  one warning instead of breaking the app.
+
+The suite runs on React 19, 18 and 17 in CI. What each version gives you:
+
+| | React 19 | React 18 | React 17 |
+| --- | --- | --- | --- |
+| Props, state, parent attribution, avoidable verdicts, `memo` / `forwardRef` / classes | yes | yes | yes |
+| Context changes (`useContext`, provider attribution) | yes | yes | no: React only records the value a component read from a context from 18 on, so a context change looks like a plain parent re-render (the library says so once) |
+| `updaters` (who scheduled the commit) and effect-loop detection | yes | yes | no: React's updater tracking starts at 18 |
+| `useSyncExternalStore`, `useTransition`, `useDeferredValue`, `useId` | yes | yes | not in React 17 |
+| `use()`, `ref` as a prop, React Compiler output | yes | no | no |
+
+## Examples
+
+`examples/vite-react` has three deliberate bugs and the built-in panel; `scale.html?rows=3000` is
+the scale test with a readout of the library's own cost. `examples/next` is the same app in
+Next.js, started from `instrumentation-client.ts` and reporting to the relay panel.
+
+```sh
+npm install && npm --prefix examples/vite-react install
+npm run dev:example          # http://localhost:5199/  and  /__rerender-lens/
+```
 
 ## Migrating from why-did-you-render
 
@@ -453,11 +284,10 @@ is the same app without the library, for trying the extension's *Inject the libr
 | `trackAllPureComponents` | `trackAllMemoized` |
 | `Comp.whyDidYouRender = true` | `track(Comp)` or `Comp.rerenderLens = true` |
 | `include` / `exclude` (RegExp[]) | same, plus strings and predicates |
-| `trackHooks` | same |
 | `logOnDifferentValues` | `logAll` |
-| `logOwnerReasons` | always on: `parent` and `owner` fields |
-| `notifier` (`{ Component, prevProps, ... }`) | `notifier` (`RenderReport`) |
-| `jsxImportSource: '@welldone-software/why-did-you-render'` | not needed |
+| `logOwnerReasons` | always on: `parent` and `owner` |
+| `notifier({ Component, prevProps, ... })` | `notifier(report: RenderReport)` |
+| `jsxImportSource` | not needed |
 
 ## License