rerender-lens 0.1.0 → 0.3.0

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
@@ -18,18 +77,75 @@ npm i -D rerender-lens
 
 Peer dependency: `react >= 16.8`. Tested with React 18 and 19.
 
-## Setup
+## One-line setup per bundler
 
-Create a file that runs **before anything else imports React components**, and import it first
-in your entry point. Development only.
+**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
 // 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 +156,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:
+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.
 
-```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" } }
-```
-
-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 +182,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 +196,20 @@ 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 |
+| `hookState`, `contexts`, `state` | current value of every state hook, every context read, and class `this.state` (off with `includeState: false`) |
+| `updaters` | components that scheduled the commit (`setState`, dispatch), from React's updater tracking |
+| `commitCause`, `afterCommit` | `effect-after-commit` (an effect of the previous commit set state) or `suspense-resolved` |
+| `key` | the element's `key`, when it has one |
+| `parent` | nearest ancestor that rendered in the same commit, and why |
+| `owner` | component that created the element (dev builds) |
+| `path` | component ancestry from the root |
+| `instanceId`, `renderCount` | stable per mounted instance |
+| `memoized` | `React.memo` / `PureComponent`: props alone decide whether it re-renders |
+| `selfDuration`, `treeDuration` | own render time, and with everything below that rendered (dev/profiling builds) |
+| `commitId` | shared by every report of one React commit |
+| `commitPriority` | `immediate` (clicks, keys), `user-blocking` (continuous input), `normal` (transitions, async), `low`, `idle` |
+| `source` | file, line and column where the element was created (dev builds) |
 | `reasons` | human-readable explanations with the fix |
 
 Change kinds:
@@ -107,37 +222,101 @@ 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.
+
+### 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
 
-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 +328,60 @@ 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)
+// '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? }): Notifier
-deepEqual(a, b), diffRecords(prev, next), classify(prev, next)   // the primitives
+createDevtoolsNotifier({ bufferSize?, target?, maxDepth?, flashAvoidable?, channel?, relay? }): Notifier
+getRenderers(), isProductionReact()       // what react-dom registered on the DevTools hook
+serializeOptions(o), deserializeOptions(o) // Options <-> JSON-safe form used by the bridge
+VERSION
+deepEqual(a, b), diffRecords(prev, next), classify(prev, next)
 ```
 
 `Options`:
@@ -187,45 +391,64 @@ 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 |
+| `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` |
 | `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 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
 
 | 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
 

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 };