npm - react-perf-recorder - Versions diffs - 0.1.0 - Mend

react-perf-recorder 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (55) hide show

package/LICENSE +21 -0
package/README.md +65 -0
package/claude/README.md +10 -0
package/claude/agents/perf-recorder.md +44 -0
package/claude/mcp.json +8 -0
package/claude/skills/react-perf-recorder/SKILL.md +52 -0
package/claude/skills/react-perf-recorder/references/causes-and-actions.md +47 -0
package/claude/skills/react-perf-recorder/references/from-scripts.md +36 -0
package/claude/skills/react-perf-recorder/references/getting-a-recording.md +41 -0
package/claude/skills/react-perf-recorder/references/measuring-a-fix.md +42 -0
package/claude/skills/react-perf-recorder/references/panel.md +21 -0
package/claude/skills/react-perf-recorder/references/reading-a-recording.md +55 -0
package/dist/browser/chunk-7DJUCCWG.js +447 -0
package/dist/browser/chunk-NTY2W4HE.js +182 -0
package/dist/browser/client.d.ts +589 -0
package/dist/browser/client.js +7161 -0
package/dist/browser/index-BlkKhwHe.d.ts +585 -0
package/dist/browser/plugins/proxy-memoize.d.ts +7 -0
package/dist/browser/plugins/proxy-memoize.js +41 -0
package/dist/browser/plugins/react-query.d.ts +5 -0
package/dist/browser/plugins/react-query.js +74 -0
package/dist/browser/plugins/zustand.d.ts +11 -0
package/dist/browser/plugins/zustand.js +171 -0
package/dist/browser/runtime.d.ts +1 -0
package/dist/browser/runtime.js +12 -0
package/dist/cli.js +23119 -0
package/dist/engine.iife.js +3661 -0
package/dist/node/chunk-HS2BJBJX.js +170 -0
package/dist/node/plugin-api-zXFxjYba.d.cts +61 -0
package/dist/node/plugin-api-zXFxjYba.d.ts +61 -0
package/dist/node/plugins/proxy-memoize.cjs +214 -0
package/dist/node/plugins/proxy-memoize.d.cts +16 -0
package/dist/node/plugins/proxy-memoize.d.ts +16 -0
package/dist/node/plugins/proxy-memoize.js +51 -0
package/dist/node/plugins/react-query.cjs +32 -0
package/dist/node/plugins/react-query.d.cts +6 -0
package/dist/node/plugins/react-query.d.ts +6 -0
package/dist/node/plugins/react-query.js +7 -0
package/dist/node/plugins/zustand.cjs +247 -0
package/dist/node/plugins/zustand.d.cts +17 -0
package/dist/node/plugins/zustand.d.ts +17 -0
package/dist/node/plugins/zustand.js +61 -0
package/dist/node/vite.cjs +1262 -0
package/dist/node/vite.d.cts +103 -0
package/dist/node/vite.d.ts +103 -0
package/dist/node/vite.js +1072 -0
package/docs/contributing.md +24 -0
package/docs/how-it-works.md +34 -0
package/docs/mcp.md +62 -0
package/docs/measuring-a-fix.md +65 -0
package/docs/options.md +22 -0
package/docs/panel.md +59 -0
package/docs/plugins.md +57 -0
package/docs/recording.md +44 -0
package/package.json +139 -0

package/docs/contributing.md ADDED Viewed

@@ -0,0 +1,24 @@
+# Working on it
+`npm test` runs the unit tests, `npm run test:e2e` the browser ones against the fixture app in
+`test/e2e/fixture-app`, on React 18 and 19. The fixture doubles as the demo:
+- `/app` — a small team chat with a store, a live feed, a polled query and a composer, with no bugs;
+- `/bug/<id>` — the same app with one seeded re-render bug each (`/bug/whole-object`), for the tests;
+- `/basics/<id>` — textbook mistakes on bare pages (`/basics/memo`, `/basics/state` …), the broken and the fixed
+  version side by side with renders and mounts counted on every row;
+- `/advanced/<id>` — harder ones: a chain of effects, a measurement, a heavy list, a query's fields.
+`/` lists the basics and the advanced cases. The e2e suite needs a dev server because the Vite plugin is half of
+what is under test.
+`npm run fixture` opens it by hand on http://localhost:5391; `npm run dev:pages` serves it as the project's site,
+under `/react-perf-recorder/` on http://localhost:5393, and `npm run build:pages` builds that site into `dist-pages`. Playwright starts its own copies of the server on 5391
+(React 18) and 5392 (React 19): stop yours first, or move the tests with `FIXTURE_PORT` / `FIXTURE_PORT_19`.
+`E2E_PROJECT=react18` runs one version only.
+`react-perf-recorder mcp --reload` restarts the MCP server whenever the CLI is rebuilt, for working on the server
+from a checkout.
+Commits follow [CLAUDE.md](../CLAUDE.md). Pushes to `dev` run type checks and unit tests; `main` runs the e2e suite
+too.

package/docs/how-it-works.md ADDED Viewed

@@ -0,0 +1,34 @@
+# How it works
+- Commits are caught by a setter on `FiberRoot.current`: React assigns it once per commit. The lanes of that commit
+  are the bits it took back off `pendingLanes`. The DevTools hook is left to its owners (react-grab, React DevTools).
+- A fiber rendered when its props, hook list or context dependencies changed since the last commit it was seen in;
+  untouched subtrees (`child === alternate.child`) are skipped.
+- A render's way down is a chain of links interned in one trie (parent → name → reason), so a render costs three map
+  lookups and no strings, whatever the chain's length.
+- Hook names come from re-running the component with a stand-in dispatcher, as React DevTools does — only on Stop,
+  only for components in the report, never inside a commit. It knows React 19's hooks too (`use`,
+  `useActionState`, `useOptimistic`, `useMemoCache`).
+- A component's file comes from the fiber on React 18 and from its owner stack on React 19, where the position is
+  the built module's: the dev server maps it back, and reads a memo's dependency array from the source.
+- Timers are wrapped once at page boot, so intervals started on mount are seen; a callback becomes a cause only when
+  React marked new work during it, and the cause goes to the components that work belongs to.
+- The app's `react-dom/client` is proxied so the recorder learns of a root the moment `createRoot` returns — that is
+  what makes recording from the page load possible.
+- Store and memoizer plugins replace `zustand` and `proxy-memoize` for the app's imports only, so libraries keep the
+  originals and memoization behaves the same.
+- The panel is a preact view in a shadow root on `<html>`, never the app's React; the outlines are drawn on one
+  canvas with `pointer-events: none`.
+## Limits
+- React 18.2+ and 19.1+, dev builds. React 19.0 dropped `_debugSource` before owner stacks landed in 19.1, so there
+  is no file for a component there; a recording made on it says so.
+- Store writes that did not lead to a commit in the area are not recorded — there is no store journal by design.
+- Two timers that update the same component between commits are attributed to the first of them.
+- Only the top level of a module is named: a `memo` inside a function keeps React's `Memo`.
+- StrictMode doubles render-time selector calls.
+- Hook names re-run the component: side effects in render run once more.
+- State names are known for the roots whose hooks are named at Stop (the top 30 inside the area, 10 outside), and
+  dependency names for the memos of the 15 components inspected; the rest keep their number. A dependency is named
+  only when the array is a literal in the app's code, and inside a custom hook only when it has one memo.

package/docs/mcp.md ADDED Viewed

@@ -0,0 +1,62 @@
+# MCP server, CLI and scripts
+## MCP server
+`npx react-perf-recorder init-claude` registers it in `.mcp.json` (with a skill and an agent in `.claude/`; `--force`
+overwrites them). By hand:
+```json
+{ "mcpServers": { "react-perf-recorder": { "command": "node", "args": ["node_modules/react-perf-recorder/dist/cli.js", "mcp"] } } }
+```
+| Tool                 |                                                                                                                                                                                                                                           |
+| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `list_recordings`    | Newest first, with status, area, commits, renders, the top root                                                                                                                                                                           |
+| `get_recording`      | `id` (`latest`, `latest-1`), `section`: `summary` (default), `actions`, `roots`, `outside`, `causes`, `components` (with ways), `timeline` (with each commit's cascade), `memos`, `frames`, `plugins`, `plugin:<name>`…; `hooks: 'short'` |
+| `record_page`        | Opens a page in a browser of its own, records it and returns the session id. `ms`, `scope`, `watch`, `script`, `replay` (a recording id: do its actions again), `sample`, `fromLoad`, `viewport`, `throttle`, `state`, `cdp`, `via`       |
+| `wait_for_recording` | Blocks until the person finishes a recording (`until: 'done'`) or starts one                                                                                                                                                              |
+| `compare_recordings` | Before/after: totals, roots, causes, the same actions, plugin metrics; warns when the runs differ                                                                                                                                         |
+The sessions folder comes from `--dir`, then `REACT_PERF_RECORDER_DIR`, then `./.agent-artifacts/perf-recorder`.
+`record_page` needs the dev server running and `playwright` installed in the project — it is never a dependency of
+this package. `scope: 'MessageList'` records one component by the name it is exported under; an area that is not
+mounted answers with the names that are.
+A page behind a sign-in:
+- `via` opens a link that signs the browser in first — a debug URL with a token, a magic link — and records the page
+  after it;
+- `react-perf-recorder login <url>` keeps a session for later runs: a real browser to sign in by hand, or
+  `--for <selector>` / `--wait <ms>` when the link signs in by itself;
+- `cdp: 'http://localhost:9222'` records in a browser you already have open and signed in; it is never closed.
+A page that redirects to a login says so instead of recording the login form. A token never reaches a recording.
+## CLI
+```text
+react-perf-recorder mcp            MCP server over stdio  [--reload: restart when the CLI is rebuilt]
+react-perf-recorder list           sessions, newest first  [--limit 20]
+react-perf-recorder show [id]      one session  [--section summary|roots|components|…] [--top 10]
+react-perf-recorder pull           wait for the next finished recording and print its summary
+react-perf-recorder record <url>   record a page  [--ms] [--scope] [--watch] [--script] [--from-load] [--via] …
+react-perf-recorder login <url>    keep a signed-in session for later recordings
+react-perf-recorder init-claude    copy the skill and the agent, register the MCP server  [--force]
+```
+## From scripts
+The page exposes the engine as `window.__REACT_PERF_RECORDER__.engine`:
+```js
+const rec = await engine.record(10_000, { source: 'script:my-check', scope: { selector: '[data-testid="orders"]' }, watch: ['OrderRow'] });
+rec.id; // saved session id
+```
+`engine.start()` / `engine.stop()`; `scope: { selector, component?, level? } | { names: [...] }`, `zones`,
+`highlight: false` for timing runs, `sampleReasons: true` for fast recordings. `window.__REACT_PERF_RECORDER__.format`
+prints reasons and hook chains the way the panel and the MCP server do. A page with nothing to record — a landing
+page, docs — can call `window.__REACT_PERF_RECORDER__.panel?.suppress(true)` on mount and `suppress(false)` on
+unmount: the panel, its outlines and shortcuts are gone for that page only, and nothing is remembered. Pages without the Vite plugin can load
+`react-perf-recorder/engine.iife.js` (core only: no plugins, no saving).

package/docs/measuring-a-fix.md ADDED Viewed

@@ -0,0 +1,65 @@
+# Measuring a fix
+A before/after says whether a change helped, and by how much. It is two recordings of the same scenario, one on the
+code as it was and one on the change, set side by side.
+## The route
+1. **Record the problem.** From the panel (**● Rec**, or **↺ Page load** for a page load) or with `record_page`.
+   Keep its id.
+2. **Make the change** — in a separate worktree when the project is a git repository (below).
+3. **Do the same scenario again.**
+   - The actions happen in the page (tabs, filters, typing, modals, store updates): **↻ Repeat** in the panel, or
+     `record_page` with `replay: <id>`. It reloads the page and does the same clicks and typing at the same pace.
+   - The actions wait on requests (server search, paging, saving): a replay does not wait for data. Write a `script`
+     that waits for what shows the data is there, and run it with `record_page` on both sides.
+4. **Compare.** The panel sets a second recording of the same page and area against the one before it;
+   `compare_recordings` does the same for any two ids.
+5. **Put back what was not kept.** A fix that is not taken leaves no trace: remove the worktree, or revert the file.
+## A separate worktree
+The working tree may hold changes that are not yours, and a change made in it for a measurement is easy to leave
+behind. With git, make the fix in a worktree instead and run a second dev server from it:
+```sh
+git worktree add --detach ../app-fix
+cd ../app-fix && npm ci
+REACT_PERF_RECORDER_DIR=/abs/path/to/app/.agent-artifacts/perf-recorder npm run dev -- --port 5174
+```
+- **One sessions folder for both.** `REACT_PERF_RECORDER_DIR` points the second server at the first one's folder,
+  so `compare_recordings` finds both recordings. A project with `outDir` in its config overrides the variable; set
+  the same absolute path there.
+- **The same page on the other port.** A replay takes the recording's URL; pass `url` with the second port.
+- **The worktree starts from the last commit**, without the working tree's uncommitted changes. When they touch the
+  page, record "before" in the worktree too, before the change, so the two sides differ by the fix alone.
+- Both versions run at once: before and after can be recorded in turn, and again, without switching code.
+- `--detach` makes no branch; commit the fix from the worktree only once it is kept.
+- `git worktree remove ../app-fix` when done.
+## A fair comparison
+- **The same conditions**: viewport, CPU throttling, data, account, area. `compare_recordings` warns when the
+  viewport, page, area, conditions or duration differ.
+- **Outlines off** on both sides. Drawing them costs frame time; a comparison with them on one side says so.
+- **Renders over milliseconds.** Render counts repeat from run to run; timings move with the machine, other tabs and
+  the garbage collector. Compare timings only between runs made one after another, and say so.
+- **Expect a little noise.** A feed tick or a poll landing on a keystroke adds a render to one run and not the other:
+  ±1 render on an action is noise. A clear result moves more than that, or moves the same way twice.
+- **Watch the recording, not only the totals**: a fix can move work from one root to another. The roots that
+  appeared and those that are gone say where it went.
+## Reading the result
+`compare_recordings` gives:
+- **totals** per second and per commit — renders, wasted renders, commits;
+- **roots**: new, gone, and changed by renders per second; `match: 'name'` finds a root the fix moved in the tree;
+- **the same actions** side by side: the median of each time it was done, per character for typing, so the runs need
+  not match click for click;
+- **causes** and **plugin metrics**, e.g. a selector's recomputes;
+- **warnings** — read them first: a comparison that warns about the page, the area or partial data is not one.
+The answer names the change, the scenario and the conditions, then the numbers that moved and by how much — and what
+could have moved them besides the change.

package/docs/options.md ADDED Viewed

@@ -0,0 +1,22 @@
+# Options
+`perfRecorder({ … })` in `vite.config.ts`:
+| Option       | Default                                                                                  |                                                                                                                                                              |
+| ------------ | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `plugins`    | `[]`                                                                                     | [Plugins](plugins.md): `zustand()`, `proxyMemoize()`, `reactQuery()`, or your own                                                                            |
+| `outDir`     | `REACT_PERF_RECORDER_DIR`, then `.agent-artifacts/perf-recorder`                         | Sessions folder, relative to the root or absolute                                                                                                            |
+| `enabled`    | dev server only, not under Vitest                                                        |                                                                                                                                                              |
+| `maxBytes`   | 64 MB                                                                                    | Largest request, the final recording included                                                                                                                |
+| `retain`     | `{ sessions: 100, bytes: 500 MB }`                                                       | Oldest sessions go first                                                                                                                                     |
+| `actions`    | `{ values: false, secretSelector: '[data-rpr-secret]' }`                                 | `values: true` records typed values; passwords and one-time codes never                                                                                      |
+| `components` | `{ include: ['src/**/*.{tsx,jsx}'], wrappers: ['memo', 'forwardRef', 'createContext'] }` | Adds `displayName` to `const X = memo(…)` and contexts. `wrapperPattern` is only for names an app leaves empty: `^(Anonymous\|ForwardRef\|Memo)$` by default |
+| `panel`      | `{ corner: 'bottom-left', highlight: true, shortcuts }`                                  | `false` — engine only                                                                                                                                        |
+| `engine`     | `{ bigCommit: 150, timelineLimit: 5000, maxDurationMs: 600000, timers: true }`           | `timers: false` leaves `setTimeout`, `setInterval` and `requestAnimationFrame` unwrapped, and timer causes out                                               |
+Plugin options:
+- `zustand({ devtools })` — `devtools: false` does not listen to the devtools middleware, so a store update reads
+  `<store>.setState` with the keys it changed instead of the action's name.
+- `proxyMemoize({ functions, module, include, exclude })` — `functions` defaults to `['memoize', 'memoizeWithArgs']`.
+- `reactQuery()` — finds the `QueryClientProvider` on the page by itself, also one that mounts late.

package/docs/panel.md ADDED Viewed

@@ -0,0 +1,59 @@
+# The panel and the report
+## The panel
+The panel is one row. **● Rec** records; **↺ Page load** reloads the page and records from its first render (the
+area and the followed components survive the reload; `?rpr=rec` does the same from a link). **■ Stop** ends it.
+Next to them is the area. **⌖ Pick** chooses the part of the page to record — with no area it opens the tree of the
+whole app; a click on the page takes the component under the cursor and opens the tree around it. In the tree `↑`/`↓`
+move, `→` goes inside, `←` goes up, `Enter` keeps the area, `Esc` puts back the one before. Once an area is picked,
+its name opens the tree again, `⧉` copies it as text for an assistant (component, file and line, path, DOM, the
+`scope` for scripts), and `×` goes back to the whole app. `◎` in the tree follows a component by name through the
+recording. While recording the area cannot change, and Pick is hidden.
+In the header:
+- **highlights** outlines renders inside the area on the page, while recording and between recordings — green for a
+  few in a row, yellow for often, red for all the time, grey where the DOM did not change, dashed for a mount. A
+  recording made with it on says so, since drawing costs frame time.
+- **fast** (off by default) works out the reason of a parent-caused render for 50 instances of a component a
+  commit, not all of them: about half the cost on lists of thousands. Counts stay exact; ways and cascade trees are
+  not recorded.
+Drag the panel by its header, or the dot it collapses to; it sticks to the nearest edge. In automated browsers
+(`navigator.webdriver`) the panel is hidden unless the URL has `?rpr=panel`.
+## The report
+After Stop the report leads with the answer: commits, renders, wasted renders (after which the DOM did not change),
+the slowest action, and the root to fix — the one whose renders changed nothing most often — opened on its reason,
+hook chain and line. Then warnings, actions, the other roots, and:
+- **Timeline** — tracks over one axis: actions, commits, and a lane per root. A bar is a commit, as wide as React
+  took and as tall as it rendered, coloured by its cause; the causes above are the legend and light up their
+  commits. Drag across the overview to zoom, drag the tracks to move, the wheel zooms at the pointer. A picked
+  commit shows its causes, its roots with their reasons, and its **cascade** as a tree — who rendered whom, through
+  which props, the busiest branch first — and outlines its components on the page; the live outlines step aside until
+  **Show all**. A picked action lights up every commit it caused and says what it cost.
+- **Components** — every component's renders, and the **ways** its renders came down from their roots: the cause,
+  the root and why it rendered, then the props each parent handed on, one link a line. A link with equal props is
+  marked: a `memo` there stops the rest of the way.
+- **Memos that miss** — a `useMemo` or `useCallback` that recomputed on at least half of its renders, how often it
+  kept its value, the dependency that moved by its name in the code, whether it moved to a new object with the same
+  content, and the line.
+- **Plugins** — what the store, query and memoizer plugins saw; a library that is not on the page is left out.
+The bottom bar keeps the id, **Copy id**, **↻ Repeat**, **Download**, **⤢ Wide** and **Dismiss** in reach however far
+the report is scrolled.
+## Before → after
+A second recording of the same page and area is set against the one before it: the same actions side by side, as
+renders per time each was done (per character for typing), so the runs need not match click for click.
+**↻ Repeat** makes them match anyway: it reloads the page and does the report's actions again at their pace — the
+clicks, the keys, as many characters as were typed — while recording. Events are dispatched the way the browser
+dispatches a person's, so React schedules the work as it did the first time; a step whose element is gone stops
+the replay and says which. For scenarios whose network timing matters, record two scripted runs instead —
+[Measuring a fix](measuring-a-fix.md) has the whole route, a worktree for the change, and how to read the result.

package/docs/plugins.md ADDED Viewed

@@ -0,0 +1,57 @@
+# Plugins
+Three come with the package: `zustand()` names stores and their actions, `proxyMemoize()` counts memoized selectors'
+calls and recomputes, `reactQuery()` turns query cache events into causes. A plugin whose library is not on the page
+is left out of the report.
+A plugin has two optional halves: build hooks for the dev server and a runtime module for the page.
+```ts
+import { definePerfRecorderPlugin } from 'react-perf-recorder/vite';
+export const myStore = () =>
+  definePerfRecorderPlugin({
+    name: 'my-store',
+    vite: {
+      transform(code, id) {
+        /* … */
+      },
+    }, // resolveId / load / transform / config, dev server only
+    runtime: { module: '/src/dev/myStorePlugin.ts', options: { verbose: false } },
+  });
+```
+```ts
+// src/dev/myStorePlugin.ts
+import { definePlugin } from 'react-perf-recorder/runtime';
+export default definePlugin((options: { verbose: boolean }) => ({
+  name: 'my-store',
+  setup(ctx) {}, // at page boot, before the app
+  describe(fn, kind, next) {
+    return null; // a label for a store selector or a store
+  },
+  start(session) {}, // session.emitCause({ type, changes }) queues a cause for the next commit
+  commit(session) {}, // after each commit of a recording: find what mounted late; keep it cheap
+  stop(session) {
+    // active: false when the library is not on the page; the report then leaves the plugin out
+    return { version: 1, active: true, highlights: [], metrics: {} };
+  },
+  conditions() {
+    return { account: 'demo' };
+  },
+}));
+```
+A cause emitted with `aim: true` after the store told React goes only to the components it updated. A library that
+tells React from a timer of its own, as react-query does, lists its packages (`packages: ['@tanstack/query-core']`)
+and emits with `waitForTimer: true`: the event waits for that timer and goes to the components it updated;
+`merge: key` folds the events of one key into one (`fetch → success ["presence"]`).
+Helpers for build halves: `proxyModule` replaces a module for the app's imports only, `findDeclarations` +
+`appendLines` name `const X = factory(…)` declarations without shifting lines, `createFilter` matches app files.
+**A reselect plugin would be** `proxyModule('reselect')` exporting
+`createSelector = instrument(original.createSelector, 'createSelector', 'lastFunction')` from a runtime module with
+`createMemoInstrumentation()`, plus `findDeclarations(code, ['createSelector'])` for names — the same shape as the
+proxy-memoize plugin.

package/docs/recording.md ADDED Viewed

@@ -0,0 +1,44 @@
+# What a recording holds
+- **Cascade roots** — a component that rendered while its parent did not: where a render started, how many renders
+  it pulled (`perHit`), how many instances fired at once. A component whose parent handed it the same props
+  (`children` passed through, equal props to `memo`) is a root of its own.
+- **Reasons**
+  - `state now`, `store useChatStore selectPrice`, `context Theme`, `props: value | same: style, onClick`;
+  - `SAME-CONTENT` — a new reference with the same content, almost always a subscription bug rather than new data;
+  - hook chains, with `[package]` where the app's hooks hand over to a library:
+    `useOrderForm › [react-hook-form] useController › useFormState › State @ src/Form.tsx:48`.
+- **Per-component reasons**, renders a parent caused included: `parent: props equal` (a `memo` would skip it),
+  `parent: props price | same: style` (what broke `memo`).
+- **Ways and cascades** — for each component, up to three ways its renders came down from a root, up to 20 links
+  each; for each commit, its cascade as a tree (the 30 busiest links and those above them).
+- **The app's components apart from the packages'** — told by the file of the element a component rendered, so a UI
+  kit's components are found without naming them. The app's lead the report; the picker tree hides package internals
+  and providers behind checkboxes.
+- **The page load** — recording can start before the first commit.
+- **Wasted renders and mounts** — renders that changed nothing in the DOM; a component declared inside a render or
+  an unstable `key` remounts its subtree every time.
+- **Causes** — what scheduled each commit, aimed at the components it updated: store actions with the keys they
+  changed, query events (one per query and commit: `fetch → success ["presence"]`), timers
+  (`timer setInterval useCountdown @ src/hooks/useCountdown.ts`), socket and worker messages, navigations, input.
+  What none of them explains is read off the stack when React is told: `core:effect @ src/hooks/useSync.ts`.
+- **User actions** — clicks, typing (length only; secrets never), keys, scroll; each with the element, its component
+  and file, and the commits it led to. The recording is cut into action → consequences segments: renders per typed
+  character, reaction vs background, input latency.
+- **An area** — only what renders inside the picked component; renders from above are kept as outside roots.
+- **Memos** that keep recomputing, long animation frames with their scripts, commit lanes, memoized selectors' calls
+  and recomputes.
+## Sessions
+`<outDir>/<id>/`:
+- `session.json` — `status: recording | done | interrupted`, page, area, conditions;
+- `events.ndjson` — streamed while recording, every ~2 s;
+- `recording.json` — written on Stop (`schema: react-perf-recorder/recording`).
+A session whose page reloads or closes mid-recording stays readable: the MCP server rebuilds a partial recording
+from its events. Hook names, components, ways and plugin sections exist only in the final recording.
+Every URL a session keeps — the page, its conditions, each navigation — has tokens masked first, in the path, the
+query and the fragment.

package/package.json ADDED Viewed

@@ -0,0 +1,139 @@
+{
+  "name": "react-perf-recorder",
+  "version": "0.1.0",
+  "description": "Record React re-renders in the browser: cascade roots, hook-level reasons, store causes and user actions, saved as sessions an agent reads over MCP",
+  "license": "MIT",
+  "author": "Eugene",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deadrime/react-perf-recorder.git"
+  },
+  "homepage": "https://deadrime.github.io/react-perf-recorder/",
+  "bugs": {
+    "url": "https://github.com/deadrime/react-perf-recorder/issues"
+  },
+  "keywords": [
+    "react",
+    "re-render",
+    "performance",
+    "profiler",
+    "vite",
+    "vite-plugin",
+    "mcp",
+    "claude",
+    "zustand",
+    "react-query",
+    "devtools"
+  ],
+  "type": "module",
+  "files": [
+    "dist",
+    "claude",
+    "docs/*.md"
+  ],
+  "bin": {
+    "react-perf-recorder": "dist/cli.js"
+  },
+  "exports": {
+    "./vite": {
+      "types": "./dist/node/vite.d.ts",
+      "import": "./dist/node/vite.js",
+      "require": "./dist/node/vite.cjs"
+    },
+    "./plugins/zustand": {
+      "types": "./dist/node/plugins/zustand.d.ts",
+      "import": "./dist/node/plugins/zustand.js",
+      "require": "./dist/node/plugins/zustand.cjs"
+    },
+    "./plugins/proxy-memoize": {
+      "types": "./dist/node/plugins/proxy-memoize.d.ts",
+      "import": "./dist/node/plugins/proxy-memoize.js",
+      "require": "./dist/node/plugins/proxy-memoize.cjs"
+    },
+    "./plugins/react-query": {
+      "types": "./dist/node/plugins/react-query.d.ts",
+      "import": "./dist/node/plugins/react-query.js",
+      "require": "./dist/node/plugins/react-query.cjs"
+    },
+    "./plugins/zustand/runtime": {
+      "types": "./dist/browser/plugins/zustand.d.ts",
+      "import": "./dist/browser/plugins/zustand.js"
+    },
+    "./plugins/proxy-memoize/runtime": {
+      "types": "./dist/browser/plugins/proxy-memoize.d.ts",
+      "import": "./dist/browser/plugins/proxy-memoize.js"
+    },
+    "./plugins/react-query/runtime": {
+      "types": "./dist/browser/plugins/react-query.d.ts",
+      "import": "./dist/browser/plugins/react-query.js"
+    },
+    "./runtime": {
+      "types": "./dist/browser/runtime.d.ts",
+      "import": "./dist/browser/runtime.js"
+    },
+    "./client": {
+      "types": "./dist/browser/client.d.ts",
+      "import": "./dist/browser/client.js"
+    },
+    "./engine.iife.js": "./dist/engine.iife.js",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:19": "vitest run --config vitest.react19.config.ts",
+    "test:matrix": "npm run test && npm run test:19 && npm run test:e2e",
+    "test:e2e": "playwright test",
+    "fixture": "vite --config test/e2e/fixture-app/vite.config.ts",
+    "dev:pages": "vite --config test/e2e/fixture-app/vite.pages.config.ts",
+    "build:pages": "NODE_ENV=development vite build --config test/e2e/fixture-app/vite.pages.config.ts",
+    "fixture:19": "RPR_REACT=19 FIXTURE_PORT=5392 vite --config test/e2e/fixture-app/vite.config.ts",
+    "format": "prettier --write .",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build"
+  },
+  "dependencies": {
+    "@babel/parser": "^7.29.9"
+  },
+  "peerDependencies": {
+    "react": "^18.2.0 || >=19.1.0",
+    "vite": ">=5 <8"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "vite": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=18.18"
+  },
+  "devDependencies": {
+    "@jridgewell/trace-mapping": "0.3.31",
+    "@modelcontextprotocol/sdk": "1.30.0",
+    "@playwright/test": "1.53.2",
+    "@tanstack/react-query": "5.81.5",
+    "@types/node": "22.14.0",
+    "@types/react": "18.3.23",
+    "@types/react-dom": "18.3.7",
+    "@vitejs/plugin-react-swc": "3.10.2",
+    "happy-dom": "20.8.9",
+    "marked": "18.0.14",
+    "preact": "10.29.8",
+    "prettier": "2.8.8",
+    "proxy-memoize": "3.0.1",
+    "react": "18.3.1",
+    "react-dom": "18.3.1",
+    "react-hook-form": "7.78.0",
+    "react-router-dom": "6.30.3",
+    "tsup": "8.5.1",
+    "typescript": "5.9.3",
+    "vite": "6.4.1",
+    "vitest": "4.1.2",
+    "zod": "3.25.67",
+    "zustand": "4.5.7"
+  }
+}