rerender-lens 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,15 +1,104 @@
 # Changelog
 
+## Unreleased
+
+- **Sessions.** Record, use the app, Stop; apply a fix; record again. The Sessions view compares
+  two sessions: avoidable re-renders per component with deltas, totals, wasted time, and which
+  suggested fixes went away. Summaries persist per origin; exports include them.
+- **Provider attribution.** A `useContext` change now names the component that renders the
+  Provider and, for object values, which keys changed. When only some keys changed the reason
+  and the Fixes view say so and suggest splitting the context or selecting slices.
+- **Children diffs.** Elements are serialized with their props, so a changed `children` prop
+  shows the differing leaf (`children[0].props.label`); re-created children get their own advice
+  and fix snippet (memoize or hoist them).
+- **Commit priority.** Every report carries the priority React gave the commit (discrete input,
+  continuous input, transition / async, low, idle); the Commits list and report show it. The
+  bridge `info()` also counts scheduled roots vs commits.
+- Not done: custom hook names for hook changes. React DevTools gets them by re-running the
+  component with a fake dispatcher; doing that from a commit hook is too invasive.
+- The panel outside DevTools: **Open side panel** shows it in Chrome's side panel next to the
+  page, **Open in window** in its own window (toolbar popup, or the new buttons in the DevTools
+  panel). Both use the background relay plus `chrome.scripting` instead of DevTools APIs, follow
+  the active tab unless pinned, and stack the layout when narrower than 720px. Firefox gets the
+  same page as a sidebar.
+- UI refresh: new palette and spacing in light and dark, icon toolbar with labels that collapse
+  in narrow layouts, segmented view switcher, a summary strip (renders, avoidable, wasted time,
+  top offender, best fix, all clickable), clearer selection and banners.
+- `selfDuration` is now the component's own render time; the previous value (the whole subtree)
+  moved to `treeDuration`. Children that bailed out contribute nothing, as in the Profiler.
+- `memoized` on every report (`React.memo` / `PureComponent`). Reports of unmemoized components
+  with avoidable prop changes explain that `React.memo` is needed as well; the panel's Fixes view
+  lists it first.
+- Bridge `info()` reports `source` (`page` or `extension`) and `injected`. The panel warns when the
+  page runs its own copy next to the injected one.
+- Extension: per-origin "Let React DevTools create the hook" toggle (popup and Settings). With it
+  on, the injector waits one task so React DevTools' own script can install the global hook first.
+- Elements sidebar: an element without a React component above it now says so instead of
+  "not running".
+- jsdom tests for `background.js`, `popup.js` and `sidebar.js` (shared fake `chrome`).
+- Panel source moved to TypeScript (`extension/src/panel.ts`); `npm run build` writes the
+  committed `extension/panel.js`, and CI fails when it is out of date.
+- Tree and live stream are virtualized (only the rows in view exist in the DOM); the stream now
+  keeps every buffered report instead of the last 300. `panel.html?demo&flood=5000` loads
+  synthetic data for scale testing.
+- Keyboard: `/` focuses search, `f` opens the Fix tab, `Esc` clears the page highlight. The
+  details tab is remembered per origin.
+- `different` object props show the differing leaves (`filters.page: 1 → 2`) without expanding
+  the whole value; the kind label names the first differing path.
+- Root-cause page: click a root cause in a commit to see every commit it started, the components
+  it re-rendered avoidably, and the fixes for them.
+
+## 0.2.0
+
+Library
+
+- Every report carries `commitId` (shared by the reports of one React commit) and, in dev
+  builds, `source` (`_debugSource` on React <= 18, parsed from `_debugStack` on React 19).
+- DevTools bridge protocol 2: `hello` carries library version, protocol, React renderers and
+  options; `pull(since)` for polling panels; `info()`, `configure()`, `getOptions()`,
+  `highlight(instanceId)`, `flashAvoidable(on)` (in-page overlay), `inspect(node)`.
+- `getRenderers()` / `isProductionReact()`: what react-dom registered on the DevTools hook.
+  `attach` wraps `hook.inject` so hooks created by react-refresh (Vite) are covered too.
+- `serializeOptions` / `deserializeOptions`, `VERSION`.
+- An IIFE build (`extension/vendor/rerender-lens.js`, global `RerenderLens`) for injection.
+
+Extension
+
+- Store-ready packaging: `npm run build:ext` writes Chrome, Edge and Firefox zips; the manifest
+  version follows `package.json`; CI uploads the zips; the release workflow publishes to the
+  Chrome Web Store when secrets are configured. Listing text and privacy policy in
+  `extension/store/`.
+- Zero-config mode: enable an origin from the toolbar popup or the panel's Settings and tick
+  *Inject the library*; the extension loads rerender-lens into the page before React.
+  Optional host permissions for non-local hosts; local development hosts are on by default.
+- Three-state status (no page / no library / connected with library and React versions),
+  protocol-mismatch and production-build warnings.
+- Polling fallback through `inspectedWindow.eval` when no content script is present.
+- New views: Offenders (sortable table), Commits (root causes, render cascade, contexts),
+  Fixes (ranked by avoidable re-renders removed, with snippets). Per-report Fix tab.
+- Hover-to-highlight and flash of avoidable renders in the page; "open source" links into the
+  Sources panel; Copy as Markdown; JSON export/import.
+- Settings drawer driving `configure()` live, persisted per origin; panel state (filters,
+  collapsed nodes, split width) persisted per origin.
+- Elements-panel sidebar for `$0`; toolbar badge with the avoidable count per tab.
+- Reports are batched per animation frame; malformed payloads are ignored.
+- Playwright end-to-end suite (`npm run e2e`) running Chromium with the extension against the
+  example app (relay, badge, injection, panel).
+
 ## 0.1.0
 
 Initial release.
 
-- `init(React, options)` patches `createElement` and the state hooks; tracked components report every update.
+- `init(options)` observes React commits through the DevTools global hook and reports every
+  update of a tracked component. No patching, no wrappers: Fast Refresh, memo comparators,
+  forwardRef, classes and the automatic JSX runtime all work unchanged.
 - Change classification: `deep-equal`, `function`, `element`, `different`, `added`, `removed`.
 - Trigger classification: `props`, `parent`, `state`, `hooks`, `mixed`; `avoidable` flag.
-- Supports function components, `React.memo` (custom comparators preserved), `forwardRef`, `memo(forwardRef())`, class and `PureComponent` components.
-- `useWhyRerender(name, values)` hook for tracking one component without patching.
+- `parent` (nearest ancestor that rendered, and why), `owner`, `path`, `instanceId`,
+  `renderCount`, `selfDuration` on every report.
+- Hook state (`useState`, `useReducer`, `useSyncExternalStore`) and `useContext` diffs.
+- `useWhyRerender(name, values)` hook for tracking one component without `init`.
 - `createCollector()` with `assertNoAvoidable()` for tests; `combineNotifiers()`.
-- `createDevtoolsNotifier()` posting structured-clone-safe reports on `window` for a DevTools panel.
-- `rerender-lens/jsx-runtime` and `rerender-lens/jsx-dev-runtime` for the automatic JSX runtime.
-- StrictMode double-render is not reported.
+- `createDevtoolsNotifier()` posting structured-clone-safe reports on `window`.
+- `ignoreHotReload` and `maxReportsPerComponent` options.
+- Example Vite app with three deliberate re-render bugs.

package/README.md

@@ -1,16 +1,75 @@
 # rerender-lens
 
-Find avoidable React re-renders and learn exactly which prop, state or hook caused them.
-A modern alternative to `why-did-you-render`: TypeScript, structured reports you can assert on
-in tests, a hook for tracking a single component, and a bridge for a DevTools panel.
+Find avoidable React re-renders and see exactly what caused them: which prop, which state,
+which context, and which ancestor started the update.
 
+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.
+
+```
+▸ [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).
+    at App > ProductPage > ProductRow
 ```
-[rerender-lens] <ProductRow> avoidable re-render: 1 equal by value, 1 new function
-  - 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).
+
+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).
+
+## 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. 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.
+
+```ts
+import { init, createDevtoolsNotifier } from 'rerender-lens';
+init({ trackAllMemoized: true, silent: true, notifier: createDevtoolsNotifier() });
 ```
 
-## Install
+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.
+
+## Install the package
 
 ```sh
 npm i -D rerender-lens
@@ -20,16 +79,12 @@ Peer dependency: `react >= 16.8`. Tested with React 18 and 19.
 
 ## Setup
 
-Create a file that runs **before anything else imports React components**, and import it first
-in your entry point. Development only.
-
 ```ts
 // src/rerender-lens.ts
-import React from 'react';                 // default import, not `import * as React`
 import { init } from 'rerender-lens';
 
 if (import.meta.env.DEV) {
-  init(React, { trackAllMemoized: true });
+  init({ trackAllMemoized: true });
 }
 ```
 
@@ -40,31 +95,16 @@ import { createRoot } from 'react-dom/client';
 ...
 ```
 
-### Automatic JSX runtime (Vite, Next, TS `react-jsx`)
-
-With the automatic runtime the compiler never calls `React.createElement`, so also point
-`jsxImportSource` at this package in development:
-
-```ts
-// vite.config.ts
-export default defineConfig(({ mode }) => ({
-  esbuild: mode === 'development' ? { jsxImportSource: 'rerender-lens' } : undefined,
-  plugins: [react({ jsxImportSource: mode === 'development' ? 'rerender-lens' : 'react' })],
-}));
-```
-
-```jsonc
-// tsconfig.json (or a tsconfig.dev.json)
-{ "compilerOptions": { "jsx": "react-jsx", "jsxImportSource": "rerender-lens" } }
-```
+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.
 
-Anything still using `React.createElement` (the classic runtime, `React.cloneElement` of a new
-element, libraries) is covered by `init` alone.
+No `jsxImportSource`, no default-import requirement, no Babel plugin.
 
 ## Choosing what to track
 
 ```ts
-init(React, {
+init({
   trackAllMemoized: true,        // every React.memo and PureComponent
   include: [/^Grid/, 'Sidebar'], // by display name: string, RegExp or predicate
   exclude: ['DevOverlay'],
@@ -81,7 +121,8 @@ 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.
+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
 
@@ -94,7 +135,16 @@ Every update of a tracked component produces a `RenderReport`:
 | `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`, `useContext`, `useSyncExternalStore` values that changed |
+| `hookChanges` | `useState`, `useReducer`, `useSyncExternalStore` and `useContext` values that changed; context entries carry `provider` (who renders it) and `changedKeys` / `totalKeys` for object values |
+| `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:
@@ -107,37 +157,36 @@ Change kinds:
 | `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, the parent re-rendered.
+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 to the console; pass `logAll: true` to print
-every report. The `notifier` always receives every report.
+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 React from 'react';
 import { init, disable, createCollector } from 'rerender-lens';
 
 const collector = createCollector();
-beforeAll(() => init(React, { trackAllMemoized: true, silent: true, notifier: collector.notifier }));
+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 with every component and reason
+  collector.assertNoAvoidable(); // throws listing every component and reason
   // or: expect(collector.avoidable).toHaveLength(0)
 });
 ```
 
-Import order matters here too: `init` must run before the modules under test read
-`React.useState` etc. A `setupFiles` entry in Vitest/Jest is the usual place.
+In Vitest or Jest, call `ensureDevtoolsHook()` (or `init`) from a `setupFiles` entry so the hook
+exists before `react-dom` is imported by your tests.
 
 ## Track a single component from the inside
 
-No patching, works anywhere, including inside library packages or Storybook:
+Works anywhere without `init`, for example inside library packages or Storybook:
 
 ```ts
 import { useWhyRerender } from 'rerender-lens';
@@ -149,35 +198,52 @@ function Row(props: RowProps) {
 }
 ```
 
-Pass whatever values you want compared. Reports use the notifier from `init` when it was
-called, or the `options` third argument.
+Pass whatever values you want compared.
 
 ## DevTools bridge
 
 ```ts
 import { createDevtoolsNotifier } from 'rerender-lens';
 
-init(React, { trackAllMemoized: true, silent: true, notifier: createDevtoolsNotifier() });
+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: 1, type: 'report', payload }`. The last 300
-reports are buffered; `window.__RERENDER_LENS_DEVTOOLS__.replay()` re-posts them and `.clear()`
-drops them. Any extension or in-page panel can consume this.
+on `window` as `{ __rerenderLens: true, version: 2, type: 'report', payload }`. The last 300
+reports are buffered. The bridge at `window.__RERENDER_LENS_DEVTOOLS__` exposes:
+
+| Method | |
+| --- | --- |
+| `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`) |
+
+The DevTools extension consumes this (see [Chrome extension](#chrome-extension) above); with
+injection enabled it needs no `init` call at all.
+
+Every report also carries `commitId` (shared by all reports of one React commit) and, in dev
+builds, `source` (where the element was created).
 
 ## API
 
 ```ts
-init(React, options?): () => void         // returns disable
-configure(options): void                  // merge options at runtime
-disable(): void                           // restore React
+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)
 useWhyRerender(name, values, options?)
 createCollector(): { reports, avoidable, notifier, clear, assertNoAvoidable }
 combineNotifiers(...notifiers): Notifier
-createDevtoolsNotifier({ bufferSize?, target?, maxDepth? }): Notifier
-deepEqual(a, b), diffRecords(prev, next), classify(prev, next)   // the primitives
+createDevtoolsNotifier({ bufferSize?, target?, maxDepth?, flashAvoidable? }): 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)
 ```
 
 `Options`:
@@ -187,45 +253,61 @@ deepEqual(a, b), diffRecords(prev, next), classify(prev, next)   // the primitiv
 | `trackAllMemoized` | `false` | track every `memo` / `PureComponent` |
 | `trackAllComponents` | `false` | track everything (noisy) |
 | `include` / `exclude` | | display-name matchers |
-| `trackHooks` | `true` | capture and diff hook values |
+| `trackHooks` | `true` | diff hook state and contexts |
 | `logAll` | `false` | print non-avoidable reports too |
 | `silent` | `false` | never print; 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 |
 
 ## How it works, and the caveats that follow
 
-- `init` replaces `React.createElement` with one that maps a tracked component type to a cached
-  wrapper. The wrapper renders the original, keeps the previous props and hook values in a ref,
-  and diffs them on the next render. Class components get a subclass whose `componentDidUpdate`
-  diffs `props` and `state` and then calls yours.
-- Hook values are captured by patching `React.useState`, `useReducer`, `useContext` and
-  `useSyncExternalStore`. This only reaches code that reads those functions **after** `init`
-  ran, which is why the setup file must be imported first. With `import * as React`, the
-  namespace is read-only in most bundlers; pass the default import.
-- A wrapper is a different element type from the original, so the first time a component
-  becomes tracked (or stops being tracked after `configure`) it remounts. Decide tracking at
-  startup; use `configure` for reporting options.
-- The mount render is never reported. Under `StrictMode` the duplicate dev render is detected
-  (same props object, same hook values) and skipped.
-- `trackHooks: false` disables state-triggered reports for function components, because the
-  wrapper then cannot distinguish a state update from a StrictMode re-invocation.
-- Diffing is structural and happens during render. It is meant for development; do not enable
-  it in production builds.
+- 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` has three deliberate bugs. From the repo root:
+
+```sh
+npm install
+npm --prefix examples/vite-react install
+npm run dev:example
+```
+
+`http://localhost:5199/` runs the library itself and reports to the console and the extension.
+`http://localhost:5199/plain.html` is the same app without the library, for trying the
+extension's *Inject the library* mode.
 
 ## Migrating from why-did-you-render
 
 | why-did-you-render | rerender-lens |
 | --- | --- |
-| `whyDidYouRender(React, opts)` | `init(React, opts)` |
+| `whyDidYouRender(React, opts)` | `init(opts)` |
 | `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'` | `jsxImportSource: 'rerender-lens'` |
+| `jsxImportSource: '@welldone-software/why-did-you-render'` | not needed |
 
 ## License