react-perf-recorder 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eugene
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,65 @@
+# react-perf-recorder
+
+Record why a React app re-renders, from the page itself: press **Rec**, use the app, press **Stop**. The report
+names the component that started each render cascade and why — the hook and its line of code, the store action and
+the keys it changed, the props that broke `memo` — and an agent reads the same recordings through an MCP server.
+
+It runs only in the Vite dev server and never ships to a build. React 18.2+ and 19.1+.
+
+## Install
+
+```sh
+npm i -D -E react-perf-recorder
+```
+
+```ts
+// vite.config.ts
+import { perfRecorder } from 'react-perf-recorder/vite';
+import { zustand } from 'react-perf-recorder/plugins/zustand';
+import { proxyMemoize } from 'react-perf-recorder/plugins/proxy-memoize';
+import { reactQuery } from 'react-perf-recorder/plugins/react-query';
+
+export default defineConfig({
+  plugins: [react(), perfRecorder({ plugins: [zustand(), proxyMemoize(), reactQuery()] })],
+});
+```
+
+Open the dev page: the panel sits in a corner. **Alt+Shift+R** starts and stops a recording, **Alt+Shift+S** picks
+an area of the page to record alone.
+
+## What you get
+
+- **The root to fix** — the component that started a cascade, with its reason (`state now`,
+  `store chat selectMessages SAME-CONTENT`, `context Theme`) and the hook chain down to the line.
+- **The way a render came down** — from the cause through each parent to the component, with the props each one
+  handed on; the link with equal props is where a `memo` stops the rest.
+- **Wasted renders** — those after which nothing in the DOM changed, and remounts.
+- **Causes** — the store action, query, timer, socket message or click behind each commit.
+- **A timeline** of actions and commits; a picked commit shows its cascade as a tree and outlines its components on
+  the page.
+- **Memos that miss** — a `useMemo` that recomputes on every render, and the dependency that moved.
+- **Before → after** — `↻ Repeat` reloads the page and does the same actions again, so a fix is measured.
+
+## With an assistant
+
+```sh
+npx react-perf-recorder init-claude
+```
+
+Adds a skill, an agent and the MCP server to the project. The agent records a scenario — or reads the one you
+recorded — and answers with the cascade root, the hook behind it and the file to change.
+
+## Docs
+
+- [The panel and the report](docs/panel.md)
+- [What a recording holds](docs/recording.md)
+- [Measuring a fix](docs/measuring-a-fix.md)
+- [Options](docs/options.md)
+- [MCP server, CLI and scripts](docs/mcp.md)
+- [Plugins](docs/plugins.md)
+- [How it works, and its limits](docs/how-it-works.md)
+- [Working on it](docs/contributing.md)
+
+## License
+
+MIT

package/claude/README.md

@@ -0,0 +1,10 @@
+# Claude Code files
+
+What is here is copied into a project by `npx react-perf-recorder init-claude`:
+
+- `skills/react-perf-recorder/` — how to record and how to read a recording;
+- `agents/perf-recorder.md` — an agent that records a scenario and answers with the cause and the numbers;
+- `mcp.json` — the MCP server entry, merged into the project's `.mcp.json`.
+
+The package's own `.claude/` links to these files, so working on the recorder uses the same skill everyone else
+gets.

package/claude/agents/perf-recorder.md

@@ -0,0 +1,44 @@
+---
+name: perf-recorder
+description: Finds why a React page re-renders and proves a fix with numbers. Records a scenario with react-perf-recorder — from the page load, from a scenario it drives, or from one the person recorded — and answers with the cascade root, the hook or store behind it, and the file and line to change. Use when a page feels slow, flashes on its own, or a change has to be shown to have helped.
+tools: mcp__react-perf-recorder, mcp__playwright, Read, Grep, Glob, Bash
+skills:
+  - react-perf-recorder
+model: sonnet
+---
+
+# Finding a re-render
+
+Work by the `react-perf-recorder` skill; open its references when you get to them.
+
+1. **Conditions from the caller**: the URL, what the page should do, whether they will record it themselves.
+   Nothing to reproduce means nothing to measure — ask. Pointed at a component ("this list", a file), read the file
+   and take the name it is exported under: that is what `scope` and `watch` take.
+2. **The recorder is on the page** — `window.__REACT_PERF_RECORDER__` or the panel in a corner. Not there in a
+   production build, and that is the answer.
+3. **Record** — the person's own recording (`wait_for_recording`) first; else `record_page`, one scenario, 3–12
+   seconds.
+4. **Read** — one `get_recording` summary; follow the hook chain to the app's own code, left of `[package]`. Open
+   another section only for what the summary left open.
+5. **Answer at the confidence the recording gives.** When it names the root, the reason and the `file:line`, that is
+   the answer — stop. Measure a fix only when the cause is a guess or numbers were asked for, by
+   `references/measuring-a-fix.md` — in a git worktree, so the person's working tree stays as it was.
+
+## Boundaries
+
+- About ten tool calls is the job; past fifteen, answer with what you have and what is left unchecked.
+- Read sections, not `recording.json`.
+- Do not commit, stage or switch branches.
+- Numbers go into the answer, never into a file of the repository.
+- Close the browser you opened, even when the run failed. Scratch files go to `.agent-artifacts/`, and you delete
+  yours.
+- One recording at a time: if the engine is busy, someone else is recording — say so.
+
+## What to answer
+
+- **The cause**: the cascade root, the reason with the hook or selector, `file:line`.
+- **The fix**: what to change and where; before and after numbers, or "not measured" and why.
+- **The conditions**: page, viewport, throttling, the data, how long it ran.
+- **What you did not check**, as a list.
+
+No retelling of the steps; thirty lines is plenty.

package/claude/mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "react-perf-recorder": {
+      "command": "node",
+      "args": ["node_modules/react-perf-recorder/dist/cli.js", "mcp"]
+    }
+  }
+}

package/claude/skills/react-perf-recorder/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: react-perf-recorder
+description: Record why a React app re-renders and read the recording — cascade roots, the hook or store behind each one, what scheduled the commit, renders that changed nothing. Use when a page feels slow, flashes on its own, or a fix has to be proved with before-and-after numbers.
+---
+
+# react-perf-recorder
+
+A dev-only Vite plugin that records React re-renders from the page. Recordings land in a folder
+(`.agent-artifacts/perf-recorder`, or `REACT_PERF_RECORDER_DIR`) and this session reads them through the
+`react-perf-recorder` MCP server.
+
+**Never write measured numbers into a file of the repository.** They are true for one machine and one moment;
+numbers belong in the answer.
+
+## Getting a recording
+
+| The situation                                        | What to do                                                                                              |
+| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| The person reproduces the problem in their browser   | Ask them to press **Rec**, do it, press **Stop**; meanwhile `wait_for_recording`, then `get_recording`. |
+| You drive the page                                   | `record_page` — one call, one recording; clicks and typing go in a `script` module.                     |
+| The problem is the page load                         | `record_page` with `fromLoad`, or the panel's `↺ Page load`.                                            |
+| Before and after a fix, nothing waits on the network | `record_page` with `replay: <id>` after the change → `compare_recordings`.                              |
+| Before and after a fix, actions wait on requests     | Two `record_page` runs with the same `script`; compare them yourself.                                   |
+
+About one component: pass the name it is exported under as `scope`. Details, sign-in and the traps of each route:
+`references/getting-a-recording.md`.
+
+## Reading it
+
+**One call usually holds the answer.** The default `summary` of `get_recording` has the totals, the cascade roots
+with their reason, hook chain and `file:line`, what scheduled the commits, the costliest actions, the memos that
+keep recomputing and the plugins' highlights. Read the file it points at; open another section only for what the
+summary leaves open — `components` for the way a render came down, `timeline` for one commit's cascade.
+
+No `react-perf-recorder` tools in this session? The server starts with the session; from a terminal the same data
+is `node node_modules/react-perf-recorder/dist/cli.js list`, `show latest --section roots`, and `pull` to wait for
+the next finished recording.
+
+## References
+
+- `references/getting-a-recording.md` — `record_page`, the area, sign-in, fast recordings.
+- `references/measuring-a-fix.md` — before and after: replay or script, a worktree for the change, reading the result.
+- `references/reading-a-recording.md` — roots, reasons, hook chains, components and their ways, memos.
+- `references/causes-and-actions.md` — what scheduled each commit, the person's actions, plugin sections, traps.
+- `references/panel.md` — the panel, for guiding a person who records it themselves.
+- `references/from-scripts.md` — the page API for a Playwright or CDP script.
+
+## Before you finish
+
+- The cause is not a guess: name the root, the reason and the `file:line` the recording gave you.
+- "This component does not re-render" is a claim only after `watch` or `components` says so.
+- Close the browser you opened, and say what you did not check.

package/claude/skills/react-perf-recorder/references/causes-and-actions.md

@@ -0,0 +1,47 @@
+# Causes, actions, plugins, traps
+
+## Causes
+
+What scheduled each commit, aimed at the components it actually updated:
+
+| Cause                                 | Means                                                                            |
+| ------------------------------------- | -------------------------------------------------------------------------------- |
+| `zustand:<action>`                    | a store write, with the keys it changed and a `SAME-CONTENT` mark                |
+| `react-query:fetch → success <key>`   | a query's events, one cause per query and commit, on its subscribers' commit     |
+| `core:input <event>`                  | the person's click, keystroke, scroll                                            |
+| `core:message WebSocket` / `Worker`   | a frame arrived                                                                  |
+| `core:timer setInterval <fn> @ src/…` | a timer, with the place it was started                                           |
+| `core:navigation push`                | a navigation                                                                     |
+| `core:effect @ src/hooks/useX.ts`     | a setState from an effect                                                        |
+| `core:update <fn> @ src/…`            | a plain call in the app's code; `(<package>)` when it came from inside a library |
+| `core:none`                           | React scheduled the work itself — rare, and worth a second look                  |
+
+A cause goes to the roots whose components it updated: a subscriber of `priceStore` gets
+`zustand:priceStore.setState`, not the action that landed in the same commit.
+
+## Actions
+
+`section: actions` cuts the recording into action → consequences: each action runs until the next one or a second
+of quiet. `reaction` is the commits during the person's event, `background` everything else (ticks, polling,
+deferred work). Typing gets renders per character, a click the input latency. Typed values are never recorded, only
+their length.
+
+## Plugin sections
+
+- `plugin:proxy-memoize` — calls and recomputes per selector; `evicting` means a `memoizeWithArgs` cache keeps
+  pushing out answers still in use. The fix is a memoized selector per row, not a bigger `size`. An unnamed selector
+  goes by where it was created: `memoize in Row · Messages.tsx`.
+- `plugin:zustand` — the stores it saw and the updates they made.
+- `plugin:react-query` — query events by kind and key.
+
+A plugin whose library is not on the page has `active: false` and is left out of the summary.
+
+## Traps
+
+- **HMR during a recording** makes wide react-refresh commits; it is noted in `warnings`, and the run is better
+  repeated.
+- **Store writes that led to no commit are not in the recording** — causes are attached to commits.
+- **Two timers that updated the same component between commits** are attributed to the first.
+- **One recording at a time**, panel or script: the second start gets an error naming the owner.
+- **StrictMode** doubles render-time selector calls.
+- **Highlights cost frame time**: a recording made with them on says so in `warnings`.

package/claude/skills/react-perf-recorder/references/from-scripts.md

@@ -0,0 +1,36 @@
+# Driving the recorder from a script
+
+The page carries the engine at `window.__REACT_PERF_RECORDER__.engine`, so a Playwright or CDP script can record
+without touching the panel. `docs/mcp.md` in the repository has the full API; this is what a measuring run
+needs.
+
+```js
+// Playwright: an `async (page) => {}` script
+await page.goto('http://localhost:5173/some/page');
+await page.getByTestId('ready').waitFor();
+
+const recording = await page.evaluate(async () => {
+  const { engine } = window.__REACT_PERF_RECORDER__;
+  engine.start({ source: 'script', label: 'tab switch', highlight: false });
+  document.querySelector('[data-testid="tab-orders"]').click();
+  await new Promise((r) => setTimeout(r, 1500));
+  return engine.stop(); // the Recording, and it is saved to the sessions folder too
+});
+```
+
+- `engine.record(ms, options)` is start, wait, stop in one call; `engine.last` keeps the last recording.
+- Options: `scope` (an area — `{ names: ['OrdersPanel', 'PositionTable'] }` or `{ selector }`), `watch` (component
+  names to follow), `zones` (named parts of the page, by selector), `label`, `highlight`, `sampleReasons` (fast),
+  `frames`, `hookNames`,
+  `prune`, `actions`, `bigCommit`, `timeline` (how many commits to keep), `meta`.
+- The answer carries `id`: read the whole thing later with `get_recording`, and compare two runs with
+  `compare_recordings`.
+- No engine on the page means the Vite plugin is not there — say so instead of measuring something else.
+
+**Conditions decide whether two runs can be compared.** Same viewport, same data, same CPU throttling, same
+account. Throttle through CDP (`Emulation.setCPUThrottlingRate`) if the machine is too fast to show the problem,
+and say in the answer what the conditions were.
+
+**A click under CPU throttling can hang** a Playwright call: it waits for the element to stop moving, and a page
+that re-renders constantly never does. Click from inside the page (`element.click()` in `evaluate`) or turn the
+throttling off for the click.

package/claude/skills/react-perf-recorder/references/getting-a-recording.md

@@ -0,0 +1,41 @@
+# Getting a recording
+
+## The person records
+
+Ask them to press **Rec** (or **Alt+Shift+R**), do the thing, press **Stop**. Call `wait_for_recording` meanwhile
+(two minutes by default), then `get_recording`. Their recording is worth more than one you stage: it is the thing
+that annoyed them. `references/panel.md` has what to tell them about the panel.
+
+## You record: `record_page`
+
+It opens the page in a browser of its own, records and returns the session id. It needs the dev server up and
+`playwright` in the project — not a dependency of this package; its absence is an answer, then ask for a recording
+from the panel.
+
+- `ms` — 3–12 seconds of one scenario; `fromLoad` records the page load from its first commit.
+- `script` — a module with `export default async (page) => {…}`, run while recording: clicks, typing. Wait for what
+  shows the result (a list, a spinner gone), not for a time.
+- `scope: 'MessageList'` — only what renders inside that component; a render from above is kept as an outside root
+  with its reason. Read the component's file and take the name it is exported under. An area not on the page
+  answers with the names that are.
+- `watch: ['MessageList']` — the whole page recorded, that component's renders counted and attributed on top.
+- `sample: true` — about twice as fast on lists of thousands: parent-caused reasons are a sample (`sampled` on a
+  component), counts are exact, no ways or commit cascades are kept.
+- `viewport`, `throttle` (CPU slowdown) — keep them the same across runs that will be compared.
+
+## Before and after
+
+`references/measuring-a-fix.md`: replay or script, a worktree for the change, and how to read the comparison.
+
+## Behind a sign-in
+
+In this order:
+
+1. `via` — a link that signs the browser in (a debug URL with a token, a magic link). It is opened first, not
+   recorded, and nothing about it is stored.
+2. A session saved once by `react-perf-recorder login <url>` — a real browser for a real sign-in, or
+   `--for <selector>` / `--wait <ms>` when the link signs in by itself — used by default from then on.
+3. `cdp` — a browser the person already has open and signed in. It is theirs and is never closed.
+
+A page that redirects to a login says so instead of recording the login form; then ask the person to record from
+the panel. A token never reaches a recording: every URL a session keeps is masked.

package/claude/skills/react-perf-recorder/references/measuring-a-fix.md

@@ -0,0 +1,42 @@
+# Measuring a fix
+
+Two recordings of one scenario — the code as it was, and the change — then `compare_recordings`. Do it when the cause
+is a guess or numbers were asked for; a recording that names the root, reason and `file:line` is an answer already.
+
+## Route
+
+1. The recording with the problem — the person's, or `record_page`. Keep its id.
+2. The change, in a git worktree when there is git (below); otherwise in place, and put back afterwards.
+3. The same scenario on the change:
+   - actions that happen in the page — `record_page` with `replay: <id>`;
+   - actions that wait on requests — a `script` that waits for the data (the list, the spinner gone), run on both
+     sides; a replay does not wait for data.
+4. `compare_recordings` with `before: <id>`, `after: <new id>`.
+5. A change that is not kept leaves nothing behind: `git worktree remove`, or the file as it was.
+
+## Worktree
+
+The working tree may hold someone else's changes; do not edit it for a measurement.
+
+```sh
+git worktree add --detach ../<app>-fix && cd ../<app>-fix && npm ci
+REACT_PERF_RECORDER_DIR=<abs path of the first checkout>/.agent-artifacts/perf-recorder npm run dev -- --port <other port>
+```
+
+- `--detach`: no branch is made, and none is switched to.
+- The worktree is the last commit, without uncommitted changes. When `git status` shows changes to files the page
+  uses, record "before" in the worktree as well, before editing, so the sides differ by the fix alone.
+- The variable puts both servers' sessions in the folder the MCP server reads; an `outDir` in the project's config
+  overrides it — then set the same absolute path there.
+- `record_page` on the second port: `url` with that port, also for a replay (it takes the recording's URL).
+- Stop that dev server and remove the worktree when done, even when the run failed.
+
+## Fair, and read right
+
+- Same viewport, throttling, data, account and area on both sides; `record_page` keeps outlines off.
+- Compare renders, not milliseconds — timings move with the machine. ±1 render on an action is noise (a feed tick or
+  a poll landing on a keystroke); a result is clear when it moves more, or the same way on a second run.
+- Read `warnings` first: a different page, area or a partial side makes it no comparison.
+- Roots that appeared and those that are gone say whether the work went away or moved; `match: 'name'` finds a root
+  the fix moved in the tree.
+- The answer: the change, the scenario, the conditions, the numbers that moved, and what else could have moved them.

package/claude/skills/react-perf-recorder/references/panel.md

@@ -0,0 +1,21 @@
+# The panel
+
+What to tell a person who records it themselves.
+
+- **Alt+Shift+R** records and stops, **Alt+Shift+S** picks an area. **↺ Page load** reloads and records from the
+  first render.
+- **⌖ Pick** — click an element, or a row of the tree it opens, and it becomes the area, with the component tree
+  open around it. `↑`/`↓` move, `→` goes in, `←` goes up, `Enter` keeps it, `Esc` puts the old one back. The page
+  does not react to clicks while the picker is open. `×` goes back to the whole app.
+- **⧉** copies the area as text for a chat: component, file and line, path, DOM, and the `scope` for a script — what
+  a person sends instead of "that panel on the right".
+- **highlights** outlines renders inside the area, live. Off for timing runs: a recording made with it on carries a
+  warning, and `compare_recordings` complains when only one side had it.
+- **fast** records lists of thousands at about half the cost; reasons of parent-caused renders are then a sample.
+- **◎** in a tree row follows a component by name through the recording.
+- While recording, the panel names the roots leading so far; after Stop it shows the report and `saved <id>`.
+- In the report, a commit picked on the timeline shows its cascade as a tree and outlines its components on the page;
+  **↻ Repeat** reloads and does the same actions again, for a before → after.
+
+The panel is hidden in automated browsers (`navigator.webdriver`) unless the URL has `?rpr=panel`; the shortcuts
+work either way.

package/claude/skills/react-perf-recorder/references/reading-a-recording.md

@@ -0,0 +1,55 @@
+# Reading a recording
+
+In the order a diagnosis needs: who started the cascade, why it rendered, how it reached the component, and how much
+of it was wasted. What scheduled the commit: `causes-and-actions.md`.
+
+## Roots
+
+A **cascade root** is a component that rendered while its parent did not — where a render started. `hits` is how
+many commits it started, `cascade` the renders it pulled, `perHit` the renders per commit, `instances` how many
+copies fired at once. `outsideRoots` are roots above the recorded area that reached into it.
+
+`noDomChange` (per root) and `rendersWithoutDom` (in totals) count renders after which the DOM did not change —
+waste with no argument attached. `mounts` other than zero on a page that only changes text means remounting: a
+component declared inside a render, or an unstable `key`.
+
+## Reasons
+
+- `state now` (the name the code gives it; `#2` when it is not known), `external store #3 [useStore] selectPrice`,
+  `context Theme`, `props: value | same: style, onClick`;
+- `SAME-CONTENT` — a new reference with the same content: almost always a subscription that asks for more than it
+  shows, not new data;
+- `bailout: state set to the same value` — React called the component and threw the result away.
+
+**The hook chain** turns the reason into the code that owns it:
+
+```
+state #2 SAME-CONTENT · useSLTPInput › [react-hook-form] useController › useFormState › State
+  @ src/order/SLTPInput.tsx:48   const { fieldState } = useController(…)
+```
+
+`[package]` is the border: to its left the app's own hooks — where a fix goes — to its right the library's insides.
+In an `external store` reason, `[useStore]` names the store and what follows is the selector.
+
+## Components and their ways
+
+`section: components` has a reason per component, parent-caused renders included:
+
+- `parent: props price | same: style, onClick` — what broke `memo`, and which props were only new references;
+- `parent: props equal` — a `memo` would have skipped this render;
+- `chains` — up to three ways its renders came down, as `way`: the root's leading cause, the root and its reason,
+  then the props each parent handed on:
+  `react-query:fetch ["presence"] › Stats · state online › Line · prop online › Badge · prop count`. The first link
+  with `props equal` is where a `memo` stops the rest of the way. Up to 20 links; none in fast recordings.
+
+`section: timeline` gives a commit whose roots rendered anyone a `cascade`: that commit's tree as indented lines,
+busiest branch first — who rendered whom, through which props.
+
+`library` / `wrapper` mark a package's component and an unnamed one (`Anonymous`, `Memo`); the app's own come first.
+
+## Memos
+
+`memos` names a `useMemo` or `useCallback` that recomputed on at least half of its renders: which dependency moved
+(by its name in the code when it can be read), whether into the same content, and the line. "A new object with the
+same content every time" is a dependency written in render: make it once — a constant, or its own `useMemo` — rather
+than adding another memo.