rerender-lens 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -2,6 +2,75 @@
 
 ## Unreleased
 
+- **`npx rerender-lens panel`.** A dependency-free relay (`rerender-lens/relay`) that serves the
+  panel and forwards messages between apps and panels over server-sent events and POST, so the
+  panel works for any app on any origin without the extension or Vite: Next.js, Webpack, a remote
+  dev box, a phone. `createDevtoolsNotifier({ relay })`, `window.__RERENDER_LENS_RELAY__`, or
+  `RERENDER_LENS_RELAY` / `NEXT_PUBLIC_RERENDER_LENS_RELAY` with `rerender-lens/setup`. Commands
+  (Settings, highlight, replay, clear) go back to the app; the panel re-attaches when an app
+  reloads.
+- **`rerender-lens/vitest`.** `setupFiles: ['rerender-lens/vitest/setup']` collects every test
+  file's reports; the reporter prints the run's ranked fixes, enforces a budget file, and can
+  write a panel-compatible export. `setupRerenderLens(options, { afterAll })` for custom options
+  and `failFast`.
+- **`rerender-lens/playwright`.** `installRerenderLens(page, options)` injects the library at
+  document start (the bundle now ships as `dist/rerender-lens.iife.js`); `pullReports`,
+  `clearReports`, `expectWithinBudget`.
+- A second copy of the library (another bundle on the same page) no longer wraps the hook
+  again, which doubled every report.
+
+## 0.3.0
+
+Highlights: the panel without the extension (Vite plugin `panel: true`), the `rerender-lens/vite`
+plugin and `rerender-lens/setup` entry, sessions with before/after comparison, custom hook names,
+updaters and effect-loop detection, full hook/context/state snapshots, CI budgets and a CLI, the
+side panel and window modes, and a UI refresh. Details, newest first:
+
+- **Panel without the extension.** `rerenderLens({ panel: true })` serves the panel from the Vite
+  dev server at `/__rerender-lens/`; the app publishes on a same-origin `BroadcastChannel`
+  (`createDevtoolsNotifier({ channel })`) and the panel sends commands back over it. The `panel/`
+  directory ships in the package. `pages` limits which HTML pages get the setup script.
+- **Overhead readout.** `info().overhead` reports the time the library spent inspecting commits
+  (total and worst commit); the panel shows it in the status tooltip.
+- **Panel polish.** Offenders and Fixes are windowed above 200 rows (sticky header, sortable);
+  an Offenders column chooser adds *Places* and *Last seen*; the search box takes `~text` to
+  search prop, hook, context and state values; per-component notes and a *Mute* toggle (muted
+  components leave the Fixes ranking and the summary strip, persisted per origin); roles and
+  ARIA states on the tree, lists, toast and settings dialog, Escape closes Settings.
+- **CI tooling.** `rankFixes` / `formatFixes`, `summarizeReports` / `compareSummaries`, and
+  `checkBudget` / `toBudget` / `assertWithinBudget` in the package; the collector gains
+  `fixes()`, `summary()` and `assertWithinBudget()`, and `assertNoAvoidable()` now ends with the
+  ranked fixes. A `rerender-lens` CLI (`fixes`, `summary --out`, `compare`, `budget --init`)
+  works on panel exports and session files and exits non-zero on regressions or violations.
+- **Source context.** The report shows the lines around where the element was created (DevTools
+  resources or a fetch of the module in side-panel mode).
+- **Shareable links.** *Copy link* puts the report into a `panel.html?report=…` URL (deflated when
+  the browser can); anyone with the extension opens it without the page.
+- **Custom hook names, opt-in** (`resolveHookNames`, also in Settings): hook changes and
+  snapshots read `useCounter › useCart › useState#0`. Like React DevTools, the library re-runs a
+  component type once with a stand-in dispatcher and reads the custom hooks off the call stack;
+  results are cached per type and a failing replay yields no names.
+- **Updaters.** Every report names the components that scheduled the commit (`updaters`, from
+  React's updater tracking), so the Commits view shows "set by <X>" even when X is untracked.
+- **Effect loops.** A commit scheduled right after the previous one by a component that rendered
+  in it is flagged `effect-after-commit` with the offending commit id; the report explains the
+  effect → setState pattern. Suspense boundaries resolving are labelled `suspense-resolved`.
+- **Store advice.** A `useSyncExternalStore` snapshot with equal contents now gets Redux
+  (`shallowEqual` / `createSelector`) or Zustand (`useShallow`) advice when the hook chain
+  identifies the store hook.
+- **Instances.** Reports carry the element `key`; the tree can group by instance
+  (`<Row key="a">`, `<Row #12>`) via the Instances toggle.
+- **`rerender-lens/vite`**: a Vite plugin that starts the library before React in dev, with the
+  DevTools notifier, from one line in `vite.config.ts`. **`rerender-lens/setup`**: a side-effect
+  entry for Next.js `instrumentation-client.ts`, Webpack entry arrays and the like.
+- CI lints the Firefox package with `web-ext lint`; `extension/store/QA.md` is the manual
+  checklist for what no test reaches. A docs site builds from the READMEs (`npm run build:docs`)
+  and deploys to GitHub Pages; `npm run docs:media` captures its screenshots and GIF.
+- **Full state on every report.** `hookState` (every `useState` / `useReducer` /
+  `useSyncExternalStore` value), `contexts` (every context the component reads) and, for class
+  components, `state`. The panel's report shows Hooks, State and Contexts in full, with the
+  changed entries as prev → next; the console prints them too. `includeState: false` turns it off
+  (also in the panel's Settings).
 - **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.

package/README.md

@@ -77,6 +77,67 @@ 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):
+
+```ts
+// vite.config.ts
+import { rerenderLens } from 'rerender-lens/vite';
+
+export default defineConfig({
+  plugins: [react(), rerenderLens({ trackAllMemoized: 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.
+
+**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:
+
+```ts
+// instrumentation-client.ts
+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):
+
+```sh
+npx rerender-lens panel          # http://127.0.0.1:4141/ serves the panel and relays messages
+```
+
+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'
+```
+
+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
 
 ```ts
@@ -136,6 +197,10 @@ Every update of a tracked component produces a `RenderReport`:
 | `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 |
@@ -184,6 +249,71 @@ test('typing in the search box does not re-render the grid rows', async () => {
 In Vitest or Jest, call `ensureDevtoolsHook()` (or `init`) from a `setupFiles` entry so the hook
 exists before `react-dom` is imported by your tests.
 
+### Vitest, whole suite
+
+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:
+
+```ts
+// vitest.config.ts
+test: {
+  setupFiles: ['rerender-lens/vitest/setup'],
+  reporters: ['default', ['rerender-lens/vitest', { budget: 'rerender-budget.json', exportTo: 'rerender-lens.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:
+
+```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
+```
+
+### 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
+});
+```
+
+`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
+
+```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()
+```
+
+The `rerender-lens` CLI does the same with files from the extension (Export) or from `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 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)
+```
+
 ## Track a single component from the inside
 
 Works anywhere without `init`, for example inside library packages or Storybook:
@@ -236,10 +366,18 @@ 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 }
+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? }): 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
@@ -254,6 +392,8 @@ deepEqual(a, b), diffRecords(prev, next), classify(prev, next)
 | `trackAllComponents` | `false` | track everything (noisy) |
 | `include` / `exclude` | | display-name matchers |
 | `trackHooks` | `true` | diff hook state and contexts |
+| `includeState` | `true` | put every hook, context and class state value on each report |
+| `resolveHookNames` | `false` | label hooks with the custom hooks that own them (`useCart › useState#0`); re-runs each component type once |
 | `logAll` | `false` | print non-avoidable reports too |
 | `silent` | `false` | never print; notifier still runs |
 | `notifier` | | receives every `RenderReport` |
@@ -291,9 +431,10 @@ 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.
+`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.
 
 ## Migrating from why-did-you-render
 

package/dist/budget-COBu7jBU.d.cts

@@ -0,0 +1,64 @@
+import { R as RenderReport } from './types-BzUEVkxJ.cjs';
+
+/**
+ * Concrete fixes derived from reports, ranked by how many avoidable re-renders each one removes.
+ * The same logic drives the extension's Fixes view; here it is typed on `RenderReport` for tests,
+ * CI budgets and the CLI. Pure.
+ */
+
+type FixKind = 'memo' | 'useCallback' | 'useMemo' | 'useMemoElement' | 'children' | 'contextValue' | 'splitContext' | 'storeSnapshot' | 'bailout';
+interface Fix {
+    kind: FixKind;
+    /** Where the change goes (the component that must be edited, or `<Ctx>.Provider`). */
+    owner: string;
+    /** The component whose re-render this removes. */
+    target: string;
+    prop: string | null;
+    label: string;
+    detail: string;
+}
+interface RankedFix extends Fix {
+    key: string;
+    /** Avoidable re-renders this fix removes. */
+    count: number;
+    components: Record<string, number>;
+}
+declare function fixesFor(r: RenderReport): Fix[];
+declare const fixKey: (f: Fix) => string;
+/** Every fix across `reports`, most re-renders removed first. */
+declare function rankFixes(reports: RenderReport[]): RankedFix[];
+/** Multi-line text for a test failure or a CI log. */
+declare function formatFixes(reports: RenderReport[], limit?: number): string;
+
+/**
+ * Re-render budgets for CI: a JSON baseline of allowed avoidable re-renders per component, checked
+ * against a collector's reports (like a bundle-size budget). Pure; reading and writing the file is
+ * up to the test runner (`fs`), so this works in Node and in the browser.
+ */
+
+/** `{ "*": 0, "ProductRow": 3 }`: max avoidable re-renders per component; `*` is the default. */
+type Budget = Record<string, number>;
+interface BudgetViolation {
+    component: string;
+    avoidable: number;
+    allowed: number;
+}
+interface BudgetResult {
+    ok: boolean;
+    violations: BudgetViolation[];
+    /** Components with headroom left, so budgets can be tightened. */
+    slack: {
+        component: string;
+        avoidable: number;
+        allowed: number;
+    }[];
+    counts: Record<string, number>;
+}
+declare function avoidableCounts(reports: RenderReport[]): Record<string, number>;
+declare function checkBudget(reports: RenderReport[], budget: Budget | number): BudgetResult;
+/** A budget that exactly matches the current counts (the baseline to commit). */
+declare function toBudget(reports: RenderReport[]): Budget;
+/** Throws with the violations and the ranked fixes; use it from a test. */
+declare function assertWithinBudget(reports: RenderReport[], budget: Budget | number): BudgetResult;
+
+export { type Budget as B, type Fix as F, type RankedFix as R, type BudgetResult as a, type BudgetViolation as b, checkBudget as c, type FixKind as d, assertWithinBudget as e, formatFixes as f, avoidableCounts as g, fixKey as h, fixesFor as i, rankFixes as r, toBudget as t };

package/dist/budget-LkNjGtRc.d.ts

@@ -0,0 +1,64 @@
+import { R as RenderReport } from './types-BzUEVkxJ.js';
+
+/**
+ * Concrete fixes derived from reports, ranked by how many avoidable re-renders each one removes.
+ * The same logic drives the extension's Fixes view; here it is typed on `RenderReport` for tests,
+ * CI budgets and the CLI. Pure.
+ */
+
+type FixKind = 'memo' | 'useCallback' | 'useMemo' | 'useMemoElement' | 'children' | 'contextValue' | 'splitContext' | 'storeSnapshot' | 'bailout';
+interface Fix {
+    kind: FixKind;
+    /** Where the change goes (the component that must be edited, or `<Ctx>.Provider`). */
+    owner: string;
+    /** The component whose re-render this removes. */
+    target: string;
+    prop: string | null;
+    label: string;
+    detail: string;
+}
+interface RankedFix extends Fix {
+    key: string;
+    /** Avoidable re-renders this fix removes. */
+    count: number;
+    components: Record<string, number>;
+}
+declare function fixesFor(r: RenderReport): Fix[];
+declare const fixKey: (f: Fix) => string;
+/** Every fix across `reports`, most re-renders removed first. */
+declare function rankFixes(reports: RenderReport[]): RankedFix[];
+/** Multi-line text for a test failure or a CI log. */
+declare function formatFixes(reports: RenderReport[], limit?: number): string;
+
+/**
+ * Re-render budgets for CI: a JSON baseline of allowed avoidable re-renders per component, checked
+ * against a collector's reports (like a bundle-size budget). Pure; reading and writing the file is
+ * up to the test runner (`fs`), so this works in Node and in the browser.
+ */
+
+/** `{ "*": 0, "ProductRow": 3 }`: max avoidable re-renders per component; `*` is the default. */
+type Budget = Record<string, number>;
+interface BudgetViolation {
+    component: string;
+    avoidable: number;
+    allowed: number;
+}
+interface BudgetResult {
+    ok: boolean;
+    violations: BudgetViolation[];
+    /** Components with headroom left, so budgets can be tightened. */
+    slack: {
+        component: string;
+        avoidable: number;
+        allowed: number;
+    }[];
+    counts: Record<string, number>;
+}
+declare function avoidableCounts(reports: RenderReport[]): Record<string, number>;
+declare function checkBudget(reports: RenderReport[], budget: Budget | number): BudgetResult;
+/** A budget that exactly matches the current counts (the baseline to commit). */
+declare function toBudget(reports: RenderReport[]): Budget;
+/** Throws with the violations and the ranked fixes; use it from a test. */
+declare function assertWithinBudget(reports: RenderReport[], budget: Budget | number): BudgetResult;
+
+export { type Budget as B, type Fix as F, type RankedFix as R, type BudgetResult as a, type BudgetViolation as b, checkBudget as c, type FixKind as d, assertWithinBudget as e, formatFixes as f, avoidableCounts as g, fixKey as h, fixesFor as i, rankFixes as r, toBudget as t };