rerender-lens 0.4.0 → 0.7.0

package/dist/vitest.cjs

@@ -6,7 +6,7 @@ var fs = require('fs');
 var os = require('os');
 var path = require('path');
 
-// src/vitest.ts
+// src/runner-report.ts
 
 // src/diff.ts
 var REACT_ELEMENT = /* @__PURE__ */ Symbol.for("react.element");
@@ -130,6 +130,7 @@ function deepEqualObjects(a, b, seen) {
   }
   return false;
 }
+var AVOIDABLE_KINDS = /* @__PURE__ */ new Set(["deep-equal", "function", "element"]);
 function classify(prev, next) {
   if (typeof prev === "function" && typeof next === "function") {
     return prev.name === next.name && prev.toString() === next.toString() ? "function" : "different";
@@ -166,30 +167,30 @@ function diffRecords(prev, next, basePath = "") {
     if (Object.is(a, b)) continue;
     const kind = classify(a, b);
     if (kind === "different") {
-      changes.push({ path: diffBudgetExhausted() ? path : firstDifferentPath(a, b, path), kind, prev: a, next: b });
+      changes.push({ path: diffBudgetExhausted() ? path : firstDifferentPath(a, b, path) ?? path, kind, prev: a, next: b });
     } else {
       changes.push({ path, kind, prev: a, next: b });
     }
   }
   return changes;
 }
-function firstDifferentPath(a, b, path, depth = 0) {
-  if (depth > 8) return path;
+function firstDifferentPath(a, b, path = "", depth = 0) {
+  if (depth > 8) return path || "(value)";
   if (Array.isArray(a) && Array.isArray(b)) {
-    if (a.length !== b.length) return `${path}.length`;
+    if (a.length !== b.length) return path ? `${path}.length` : "length";
     for (let i = 0; i < a.length; i++) {
       if (!deepEqual(a[i], b[i])) return firstDifferentPath(a[i], b[i], joinPath(path, i), depth + 1);
     }
-    return path;
+    return null;
   }
   if (isPlainObject(a) && isPlainObject(b)) {
     const keys = /* @__PURE__ */ new Set([...Object.keys(a), ...Object.keys(b)]);
     for (const k of keys) {
       if (!deepEqual(a[k], b[k])) return firstDifferentPath(a[k], b[k], joinPath(path, k), depth + 1);
     }
-    return path;
+    return null;
   }
-  return path;
+  return deepEqual(a, b) ? null : path || "(value)";
 }
 
 // src/report.ts
@@ -207,10 +208,12 @@ function storeAdvice(custom) {
 }
 var isGenuine = (c) => c.kind === "different" || c.kind === "added" || c.kind === "removed";
 var isChildren = (change) => change.path === "children";
+var isRefObject = (change) => change.path === "ref" && change.kind === "deep-equal";
 function fixFor(change) {
   if (isChildren(change) && (change.kind === "element" || change.kind === "deep-equal")) {
     return `lift the children out of the parent's render: memoize them with useMemo, hoist static elements to module scope, or render them from a component that does not re-render`;
   }
+  if (isRefObject(change)) return `create the ref once with useRef (or createRef outside the render) and pass the same object every time`;
   switch (change.kind) {
     case "function":
       return `wrap it in useCallback (or hoist it out of the parent's render)`;
@@ -226,6 +229,7 @@ function describe(change) {
   if (isChildren(change) && (change.kind === "element" || change.kind === "deep-equal")) {
     return `children are new React elements with the same types and props on every render of the parent`;
   }
+  if (isRefObject(change)) return `prop "ref" is a new ref object on every render (React re-attaches it each time)`;
   switch (change.kind) {
     case "deep-equal":
       return `prop "${change.path}" is a new reference but deep-equal to the previous value`;
@@ -253,11 +257,21 @@ function buildReport(input) {
   if (causes.length === 0) trigger = "parent";
   else if (causes.length === 1) trigger = causes[0];
   else trigger = "mixed";
-  const avoidable = trigger === "parent";
+  const nothingChanged = input.propChanges.length === 0 && stateChanges.length === 0 && hookChanges.length === 0;
+  const cacheHit = input.compiled === true && trigger === "parent" && input.propChanges.length === 0;
+  const revealed = input.revealed === true && trigger === "parent";
+  const avoidable = trigger === "parent" && !cacheHit && !revealed;
   const reasons = [];
-  if (avoidable && input.propChanges.length === 0 && stateChanges.length === 0 && hookChanges.length === 0) {
+  const memoFix = input.classComponent ? `Make "${input.component}" extend PureComponent (or implement shouldComponentUpdate)` : `Wrap "${input.component}" in React.memo (or extend PureComponent)`;
+  if (cacheHit) {
+    reasons.push(`compiled by React Compiler: its output is memoized and the inputs did not change, so this render is cheap; nothing to fix.`);
+  } else if (revealed) {
+    reasons.push(
+      `re-rendered because the Suspense boundary above it switched from its fallback to content: React re-renders the content it kept hidden while the fallback was shown. A one-off; nothing to fix.`
+    );
+  } else if (avoidable && nothingChanged) {
     const who = input.parent ? `<${input.parent.name}> re-rendered (${describeTrigger(input.parent.trigger)})` : "its parent re-rendered";
-    reasons.push(`re-rendered with identical props because ${who}. Wrap "${input.component}" in React.memo (or extend PureComponent).`);
+    reasons.push(`re-rendered with identical props because ${who}. ${memoFix}.`);
   } else if (avoidable && input.parent) {
     reasons.push(`caused by <${input.parent.name}> re-rendering (${describeTrigger(input.parent.trigger)}).`);
   }
@@ -266,9 +280,9 @@ function buildReport(input) {
     reasons.push(fix ? `${describe(c)}: ${fix}.` : `${describe(c)}.`);
   }
   const memoized = input.memoized !== false;
-  if (avoidable && !memoized && input.propChanges.length > 0) {
+  if (avoidable && !memoized && !input.compiled && input.propChanges.length > 0) {
     reasons.push(
-      `"${input.component}" is not memoized, so fixing the props alone will not stop this re-render: also wrap it in React.memo (or extend PureComponent).`
+      `"${input.component}" is not memoized, so fixing the props alone will not stop this re-render: also ${input.classComponent ? "extend PureComponent (or implement shouldComponentUpdate)" : "wrap it in React.memo (or extend PureComponent)"}.`
     );
   }
   for (const c of stateChanges) {
@@ -280,6 +294,8 @@ function buildReport(input) {
       const where = c.provider && c.provider.component ? ` (provided by <${c.provider.component}>)` : "";
       const keys = c.changedKeys && typeof c.totalKeys === "number" && c.changedKeys.length > 0 && c.changedKeys.length < c.totalKeys ? `: only ${c.changedKeys.map((k) => `"${k}"`).join(", ")} of ${c.totalKeys} keys changed, yet every consumer re-renders. Split the context or memoize the slices consumers read` : "";
       reasons.push(`${c.path} changed${where}${keys}.`);
+    } else if (c.hook === "useDeferredValue" && isGenuine(c)) {
+      reasons.push(`${hookLabel(c)} caught up with its latest value: this is the deferred second render React schedules after the urgent one; nothing to fix.`);
     } else if (isGenuine(c)) reasons.push(`${hookLabel(c)} changed.`);
     else if (isStateHook(c))
       reasons.push(`${hookLabel(c)} was set to a value deep-equal to the current one (new reference, same contents): reuse the existing object or bail out before calling the setter.`);
@@ -310,6 +326,7 @@ function buildReport(input) {
     reasons,
     time: now()
   };
+  if (input.compiled) report.compiled = true;
   if (input.selfDuration !== void 0) report.selfDuration = input.selfDuration;
   if (input.treeDuration !== void 0) report.treeDuration = input.treeDuration;
   if (input.commitPriority) report.commitPriority = input.commitPriority;
@@ -347,10 +364,10 @@ var KIND_LABEL = {
 };
 function summarize(report) {
   const counts2 = /* @__PURE__ */ new Map();
-  for (const c of [...report.propChanges, ...report.stateChanges, ...report.hookChanges]) {
+  for (const c of [...report.propChanges || [], ...report.stateChanges || [], ...report.hookChanges || []]) {
     counts2.set(c.kind, (counts2.get(c.kind) ?? 0) + 1);
   }
-  const parts = [...counts2].map(([kind, n]) => `${n} ${KIND_LABEL[kind]}`);
+  const parts = [...counts2].map(([kind, n]) => `${n} ${KIND_LABEL[kind] || kind}`);
   if (parts.length === 0) parts.push("no changes");
   return parts.join(", ");
 }
@@ -372,16 +389,27 @@ function printReport(report, options) {
 }
 
 // src/state.ts
+var MAX_SEEN_COMPONENTS = 500;
 var KEY = /* @__PURE__ */ Symbol.for("rerender-lens.state");
 function getState() {
   const g = globalThis;
   let s = g[KEY];
   if (!s) {
-    s = { options: {}, enabled: false, printed: /* @__PURE__ */ new Map(), detach: null, nextInstanceId: 1, nextCommitId: 1, warnedOnce: /* @__PURE__ */ new Set(), scheduled: 0, commits: 0, overheadMs: 0, maxCommitMs: 0, truncated: 0 };
+    s = { options: {}, enabled: false, printed: /* @__PURE__ */ new Map(), detach: null, nextInstanceId: 1, nextCommitId: 1, warnedOnce: /* @__PURE__ */ new Set(), scheduled: 0, commits: 0, overheadMs: 0, maxCommitMs: 0, truncated: 0, seen: /* @__PURE__ */ new Set(), seenTracked: /* @__PURE__ */ new Set(), seenOverflow: false };
     g[KEY] = s;
   }
   return s;
 }
+function noteRendered(s, name, tracked) {
+  if (!s.seen.has(name)) {
+    if (s.seen.size >= MAX_SEEN_COMPONENTS) {
+      s.seenOverflow = true;
+      return;
+    }
+    s.seen.add(name);
+  }
+  if (tracked) s.seenTracked.add(name);
+}
 function warnOnce(key, message) {
   const s = getState();
   if (s.warnedOnce.has(key)) return;
@@ -459,6 +487,9 @@ function init(options = {}) {
   const s = getState();
   s.options = { ...options };
   s.printed.clear();
+  s.seen.clear();
+  s.seenTracked.clear();
+  s.seenOverflow = false;
   if (!s.enabled) {
     s.detach = attach();
     s.enabled = true;
@@ -474,6 +505,27 @@ function disable() {
 }
 
 // src/hookNames.ts
+var NODE_COUNT = {
+  useState: 1,
+  useReducer: 1,
+  useRef: 1,
+  useMemo: 1,
+  useCallback: 1,
+  useEffect: 1,
+  useLayoutEffect: 1,
+  useInsertionEffect: 1,
+  useImperativeHandle: 1,
+  useSyncExternalStore: 2,
+  useTransition: 2,
+  useDeferredValue: 1,
+  useId: 1,
+  useOptimistic: 1,
+  useActionState: 3,
+  useFormState: 3,
+  useEffectEvent: 1,
+  useCacheRefresh: 1
+};
+var BUILTIN_HOOKS = /* @__PURE__ */ new Set([...Object.keys(NODE_COUNT), "useContext", "useDebugValue", "use"]);
 var noop = () => {
 };
 function customHooksFromStack(stack, componentName, marker) {
@@ -488,7 +540,7 @@ function customHooksFromStack(stack, componentName, marker) {
       continue;
     }
     if (name === componentName || name.endsWith("." + componentName)) break;
-    if (/^use[A-Z0-9_]/.test(name)) names.push(name);
+    if (/^use[A-Z0-9_]/.test(name) && !BUILTIN_HOOKS.has(name)) names.push(name);
     if (names.length > 8) break;
   }
   return names;
@@ -772,6 +824,11 @@ function isMemoizedFiber(fiber) {
   }
   return false;
 }
+function isCompiledFiber(fiber) {
+  if (fiber.tag === ClassComponent) return false;
+  const cache2 = fiber.updateQueue?.memoCache;
+  return !!cache2 && Array.isArray(cache2.data);
+}
 function durationsOf(fiber) {
   if (typeof fiber.actualDuration !== "number") return null;
   const tree = fiber.actualDuration;
@@ -924,7 +981,8 @@ function diffHooks(fiber, alt) {
   const labels = hookLabelsFor(fiber, b);
   let i = 0;
   while (a && b) {
-    if ((isStateNode(b) || isStoreNode(b)) && !Object.is(a.memoizedState, b.memoizedState)) {
+    const deferred = labels?.[i] === "useDeferredValue";
+    if ((deferred || isStateNode(b) || isStoreNode(b)) && !Object.is(a.memoizedState, b.memoizedState)) {
       const hook = labels?.[i] ?? hookLabel2(b);
       out.push({
         path: `${hook}#${i}`,
@@ -958,6 +1016,10 @@ function diffContexts(fiber, alt) {
   let a = alt.dependencies?.firstContext ?? null;
   let b = fiber.dependencies?.firstContext ?? null;
   let i = 0;
+  if (b && !("memoizedValue" in b)) {
+    warnOnce("contextValues", "this React does not record context values on the fiber (React < 18): context changes are reported as plain parent re-renders.");
+    return out;
+  }
   while (a && b) {
     if (a.context === b.context && !Object.is(a.memoizedValue, b.memoizedValue)) {
       const name = b.context.displayName ?? "Context";
@@ -990,10 +1052,26 @@ function diffContexts(fiber, alt) {
   return out;
 }
 var isGenuine2 = (c) => c.kind === "different" || c.kind === "added" || c.kind === "removed";
+var isRefObject2 = (v) => {
+  if (typeof v !== "object" || v === null) return false;
+  const keys = Object.keys(v);
+  return keys.length === 1 && keys[0] === "current";
+};
+function diffProps(prev, next) {
+  if (prev === next) return [];
+  const pr = prev.ref;
+  const nr = next.ref;
+  if (pr !== nr && isRefObject2(pr) && isRefObject2(nr)) {
+    const { ref: _p, ...restPrev } = prev;
+    const { ref: _n, ...restNext } = next;
+    return [{ path: "ref", kind: "deep-equal", prev: pr, next: nr }, ...diffRecords(restPrev, restNext)];
+  }
+  return diffRecords(prev, next);
+}
 function analyze(fiber, alt, trackHooks) {
   const prevProps = alt.memoizedProps ?? {};
   const nextProps = fiber.memoizedProps ?? {};
-  const propChanges = prevProps === nextProps ? [] : diffRecords(prevProps, nextProps);
+  const propChanges = diffProps(prevProps, nextProps);
   let stateChanges = [];
   let hookChanges = [];
   if (fiber.tag === ClassComponent) {
@@ -1006,7 +1084,7 @@ function analyze(fiber, alt, trackHooks) {
   } else if (trackHooks) {
     hookChanges = [...diffHooks(fiber, alt), ...diffContexts(fiber, alt)];
   }
-  const isStateHook = (h) => h.hook !== "useContext" && h.hook !== "useSyncExternalStore";
+  const isStateHook = (h) => h.hook !== "useContext" && h.hook !== "useSyncExternalStore" && h.hook !== "useDeferredValue";
   const causes = [];
   if (propChanges.some(isGenuine2)) causes.push("props");
   if (stateChanges.some(isGenuine2) || hookChanges.some((h) => isStateHook(h) && isGenuine2(h))) causes.push("state");
@@ -1046,6 +1124,24 @@ var lastCommit = null;
 var EFFECT_LOOP_WINDOW_MS = 50;
 var MAX_REPORTS_PER_COMMIT = 200;
 var COMMIT_TIME_BUDGET_MS = 25;
+function isDeferredCatchUp(fiber) {
+  const types = fiber._debugHookTypes;
+  if (!types || !types.includes("useDeferredValue") || !fiber.alternate) return false;
+  const first = fiber.memoizedState;
+  if (!isHookList(first)) return false;
+  const labels = hookLabelsFor(fiber, first);
+  if (!labels) return false;
+  let a = fiber.alternate.memoizedState;
+  let b = first;
+  for (let i = 0; a && b; a = a.next, b = b.next, i++) {
+    if (labels[i] === "useDeferredValue" && !Object.is(a.memoizedState, b.memoizedState)) return true;
+  }
+  return false;
+}
+function isUnder(fiber, boundaries) {
+  for (let f = fiber.return; f && f.tag !== HostRoot; f = f.return) if (f.tag === SuspenseComponent && boundaries.includes(f)) return true;
+  return false;
+}
 function onCommit(root, commitPriority) {
   const s = getState();
   if (!s.enabled) return;
@@ -1055,17 +1151,20 @@ function onCommit(root, commitPriority) {
   const rendered = [];
   const renderedNames = /* @__PURE__ */ new Set();
   let hot = false;
-  let suspenseResolved = false;
+  let resolvedBoundaries = null;
   const stack = [root.current];
   while (stack.length) {
     const fiber = stack.pop();
     const alt = fiber.alternate;
     if (alt && isComponentTag(fiber.tag) && didRender(fiber)) {
       if (isHotSwapped(fiber, alt)) hot = true;
-      renderedNames.add(fiberName(fiber));
-      if (shouldTrack(fiberType(fiber), o)) rendered.push(fiber);
+      const name = fiberName(fiber);
+      renderedNames.add(name);
+      const tracked = shouldTrack(fiberType(fiber), o);
+      noteRendered(s, name, tracked);
+      if (tracked) rendered.push(fiber);
     }
-    if (fiber.tag === SuspenseComponent && alt && alt.memoizedState !== null && fiber.memoizedState === null) suspenseResolved = true;
+    if (fiber.tag === SuspenseComponent && alt && alt.memoizedState !== null && fiber.memoizedState === null) (resolvedBoundaries ?? (resolvedBoundaries = [])).push(fiber);
     if (!alt || fiber.child !== alt.child) {
       for (let c = fiber.child; c; c = c.sibling) stack.push(c);
     }
@@ -1077,10 +1176,10 @@ function onCommit(root, commitPriority) {
   let commitCause;
   let afterCommit;
   const inputDriven = commitPriority === "immediate" || commitPriority === "user-blocking";
-  if (!inputDriven && lastCommit && at - lastCommit.at < EFFECT_LOOP_WINDOW_MS && updaters.some((u) => lastCommit.rendered.has(u))) {
+  if (!inputDriven && lastCommit && at - lastCommit.at < EFFECT_LOOP_WINDOW_MS && updaters.some((u) => lastCommit.rendered.has(u)) && !rendered.some(isDeferredCatchUp)) {
     commitCause = "effect-after-commit";
     afterCommit = lastCommit.id;
-  } else if (suspenseResolved) commitCause = "suspense-resolved";
+  } else if (resolvedBoundaries) commitCause = "suspense-resolved";
   if (rendered.length === 0) {
     lastCommit = { id: s.nextCommitId, at, rendered: renderedNames };
     return;
@@ -1132,6 +1231,9 @@ function onCommit(root, commitPriority) {
         owner: ownerName(fiber),
         path: componentPath(fiber),
         memoized: isMemoizedFiber(fiber),
+        compiled: isCompiledFiber(fiber),
+        classComponent: fiber.tag === ClassComponent,
+        revealed: resolvedBoundaries !== null && a.trigger === "parent" && isUnder(fiber, resolvedBoundaries),
         selfDuration: durations ? durations.self : void 0,
         treeDuration: durations ? durations.tree : void 0,
         commitId,
@@ -1145,38 +1247,203 @@ function onCommit(root, commitPriority) {
   }
 }
 
+// src/causes.ts
+var isAncestorReport = (anc, r) => anc.path.length < r.path.length && r.path[anc.path.length] === anc.component && anc.path.every((p, i) => r.path[i] === p);
+var bump = (m, key, n = 1) => void m.set(key, (m.get(key) || 0) + n);
+function indexByComponent(reports) {
+  const index = /* @__PURE__ */ new Map();
+  for (const r of reports) {
+    const list = index.get(r.component);
+    if (list) list.push(r);
+    else index.set(r.component, [r]);
+  }
+  return index;
+}
+function rootCauseOf(r, commitReports, index = indexByComponent(commitReports)) {
+  let cur = r;
+  const seen = /* @__PURE__ */ new Set([r]);
+  while (cur.trigger === "parent" && cur.parent) {
+    const parent = cur.parent;
+    const candidates = index.get(parent.name);
+    const p = candidates && candidates.find((x) => isAncestorReport(x, cur));
+    if (!p || seen.has(p)) return { name: parent.name, trigger: parent.trigger, report: null };
+    seen.add(p);
+    cur = p;
+  }
+  return cur === r ? null : { name: cur.component, trigger: cur.trigger, report: cur };
+}
+function rootCausesOf(reports) {
+  const roots = /* @__PURE__ */ new Map();
+  const rootByReport = /* @__PURE__ */ new Map();
+  const index = indexByComponent(reports);
+  let avoidable = 0;
+  let wasted = 0;
+  for (const r of reports) {
+    if (!r.avoidable) continue;
+    avoidable++;
+    if (typeof r.selfDuration === "number") wasted += r.selfDuration;
+    const root = rootCauseOf(r, reports, index);
+    const name = root ? root.name : r.parent && r.parent.name || "(unknown)";
+    const trigger = root ? root.trigger : r.parent && r.parent.trigger || "parent";
+    rootByReport.set(r, name);
+    let agg = roots.get(name);
+    if (!agg) {
+      agg = { name, trigger, count: 0, components: /* @__PURE__ */ new Map() };
+      roots.set(name, agg);
+    }
+    agg.count++;
+    bump(agg.components, r.component);
+  }
+  return { roots: [...roots.values()].sort((a, b) => b.count - a.count), rootByReport, avoidable, wasted };
+}
+function groupByCommit(reports) {
+  const out = /* @__PURE__ */ new Map();
+  for (const r of reports) {
+    if (typeof r.commitId !== "number" || r.commitId <= 0) continue;
+    const list = out.get(r.commitId);
+    if (list) list.push(r);
+    else out.set(r.commitId, [r]);
+  }
+  return out;
+}
+function rankRootCauses(reports) {
+  const byName = /* @__PURE__ */ new Map();
+  for (const commit of groupByCommit(reports).values()) {
+    for (const root of rootCausesOf(commit).roots) {
+      let agg = byName.get(root.name);
+      if (!agg) {
+        agg = { name: root.name, trigger: root.trigger, commits: 0, count: 0, components: /* @__PURE__ */ new Map() };
+        byName.set(root.name, agg);
+      }
+      agg.commits++;
+      agg.count += root.count;
+      for (const [c, n] of root.components) bump(agg.components, c, n);
+    }
+  }
+  return [...byName.values()].sort((a, b) => b.count - a.count || b.commits - a.commits || a.name.localeCompare(b.name));
+}
+var plural = (n, word) => `${n} ${word}${n === 1 ? "" : "s"}`;
+function formatRootCauses(reports, limit = 5) {
+  const ranked = rankRootCauses(reports);
+  const lines = ranked.slice(0, limit).map((root, i) => `${String(i + 1).padStart(2)}. <${root.name}> (${root.trigger}) started ${plural(root.commits, "commit")}, ${plural(root.count, "avoidable re-render")}  (${[...root.components].map(([c, n]) => `<${c}>${n > 1 ? " x" + n : ""}`).join(", ")})`);
+  if (ranked.length > limit) lines.push(`    \u2026 ${ranked.length - limit} more`);
+  return lines.join("\n");
+}
+
 // src/fixes.ts
-var AVOIDABLE = /* @__PURE__ */ new Set(["deep-equal", "function", "element"]);
+var MAX_FIX_REPORTS = 50;
 var rootOf = (path) => path.split(/[.[]/)[0] || path;
+var identifier = (name) => /^[A-Za-z_$][\w$]*$/.test(name) ? name : "value";
+function shortValue(v, max = 60) {
+  let s;
+  try {
+    s = JSON.stringify(v);
+  } catch {
+    s = String(v);
+  }
+  if (s === void 0) s = String(v);
+  return s.length > max ? s.slice(0, max - 3) + "..." : s;
+}
 function fixesFor(r) {
   const out = [];
-  const owner = r.owner || r.parent && r.parent.name || "?";
-  const changes = [...r.propChanges, ...r.stateChanges, ...r.hookChanges];
+  const ownerName2 = r.owner || r.parent && r.parent.name || null;
+  const propChanges = r.propChanges || [];
+  const changes = [...propChanges, ...r.stateChanges || [], ...r.hookChanges || []];
   if (r.avoidable && (changes.length === 0 || r.memoized === false)) {
+    const identical = changes.length === 0;
     out.push({
       kind: "memo",
       owner: r.component,
       target: r.component,
       prop: null,
       label: `Wrap <${r.component}> in React.memo`,
-      detail: changes.length === 0 ? `<${r.component}> re-rendered with identical props because <${r.parent && r.parent.name || "its parent"}> re-rendered.` : `<${r.component}> is not memoized: fixing its props alone will not stop the re-render.`
+      detail: identical ? `<${r.component}> re-rendered with identical props because <${r.parent && r.parent.name || "its parent"}> re-rendered.` : `<${r.component}> is not memoized: fixing its props alone will not stop the re-render.`,
+      snippet: `// ${r.component}
+import { memo } from 'react';
+
+export const ${r.component} = memo(function ${r.component}(props) {
+  // ...
+});
+// class components: extend PureComponent instead`
     });
   }
-  for (const c of r.propChanges) {
-    if (!AVOIDABLE.has(c.kind)) continue;
+  for (const c of propChanges) {
+    if (!AVOIDABLE_KINDS.has(c.kind)) continue;
+    const owner = ownerName2 || "?";
     const root = rootOf(c.path);
+    const id = identifier(root);
     if (root === "children" && (c.kind === "element" || c.kind === "deep-equal")) {
-      out.push({ kind: "children", owner, target: r.component, prop: "children", label: `memoize children of <${r.component}> in <${owner}>`, detail: `<${owner}> re-creates the children of <${r.component}> on every render.` });
+      out.push({
+        kind: "children",
+        owner,
+        target: r.component,
+        prop: "children",
+        label: `memoize children of <${r.component}> in <${owner}>`,
+        detail: `<${owner}> re-creates the children of <${r.component}> on every render; they have the same types and props each time.`,
+        snippet: `// ${owner}
+import { useMemo } from 'react';
+
+const children = useMemo(() => (
+  <>{/* the same elements */}</>
+), [/* deps */]);
+
+<${r.component}>{children}</${r.component}>
+
+// static children: hoist them to module scope
+const STATIC = <em>hi</em>;`
+      });
     } else if (c.kind === "function") {
-      out.push({ kind: "useCallback", owner, target: r.component, prop: root, label: `useCallback(${root}) in <${owner}>`, detail: `prop "${c.path}" of <${r.component}> is a new function on every render of <${owner}>.` });
+      out.push({
+        kind: "useCallback",
+        owner,
+        target: r.component,
+        prop: root,
+        label: `useCallback(${root}) in <${owner}>`,
+        detail: `prop "${c.path}" of <${r.component}> is a new function on every render of <${owner}>.`,
+        snippet: `// ${owner}
+import { useCallback } from 'react';
+
+const ${id} = useCallback((/* args */) => {
+  // ...
+}, [/* deps */]);
+
+<${r.component} ${root}={${id}} />`
+      });
     } else if (c.kind === "element") {
-      out.push({ kind: "useMemoElement", owner, target: r.component, prop: root, label: `memoize element prop ${root} in <${owner}>`, detail: `prop "${c.path}" of <${r.component}> is a new element with the same type and props on every render of <${owner}>.` });
+      out.push({
+        kind: "useMemoElement",
+        owner,
+        target: r.component,
+        prop: root,
+        label: `memoize element prop ${root} in <${owner}>`,
+        detail: `prop "${c.path}" of <${r.component}> is a new element with the same type and props on every render of <${owner}>.`,
+        snippet: `// ${owner}
+import { useMemo } from 'react';
+
+const ${id} = useMemo(() => ${shortValue(c.next, 40)}, [/* deps */]);
+// or pass it as children from a component that does not re-render`
+      });
     } else {
-      out.push({ kind: "useMemo", owner, target: r.component, prop: root, label: `useMemo(${root}) in <${owner}>`, detail: `prop "${c.path}" of <${r.component}> is a new ${Array.isArray(c.next) ? "array" : "object"} with the same contents on every render of <${owner}>.` });
+      const isArray = Array.isArray(c.next);
+      out.push({
+        kind: "useMemo",
+        owner,
+        target: r.component,
+        prop: root,
+        label: `useMemo(${root}) in <${owner}>`,
+        detail: `prop "${c.path}" of <${r.component}> is a new ${isArray ? "array" : "object"} with the same contents on every render of <${owner}>.`,
+        snippet: `// ${owner}
+import { useMemo } from 'react';
+
+const ${id} = useMemo(() => (${shortValue(c.next, 80)}), [/* deps */]);
+
+// or, when it never changes, hoist it to module scope:
+const ${id.toUpperCase()} = ${shortValue(c.next, 80)};`
+      });
     }
   }
-  for (const c of [...r.stateChanges, ...r.hookChanges]) {
-    const isContext = c.hook === "useContext";
+  for (const c of [...r.stateChanges || [], ...r.hookChanges || []]) {
+    const isContext = c.hook === "useContext" || /^useContext/.test(c.path);
     const ctxName = isContext ? (/useContext\((.*)\)/.exec(c.path) || [])[1] || "Context" : "";
     const providerOwner = isContext && c.provider && c.provider.component ? c.provider.component : null;
     if (isContext && c.kind === "different" && c.changedKeys && typeof c.totalKeys === "number" && c.changedKeys.length > 0 && c.changedKeys.length < c.totalKeys) {
@@ -1186,20 +1453,63 @@ function fixesFor(r) {
         target: r.component,
         prop: ctxName,
         label: `split ${ctxName}${providerOwner ? ` in <${providerOwner}>` : ""}: only ${c.changedKeys.join(", ")} changed`,
-        detail: `${c.changedKeys.length} of ${c.totalKeys} keys changed in ${ctxName}, yet every consumer re-rendered.`
+        detail: `${c.changedKeys.map((k) => `"${k}"`).join(", ")} of ${c.totalKeys} keys changed in ${ctxName}, yet every consumer (like <${r.component}>) re-rendered. Consumers that read the other keys re-render for nothing.`,
+        snippet: `// ${providerOwner || "Provider"}
+// one context per independently-changing slice
+const ${identifier(ctxName)}Static = createContext(...);
+const ${identifier(ctxName)}${c.changedKeys.map((k) => k[0].toUpperCase() + k.slice(1)).join("")} = createContext(...);
+
+// or keep one context and let consumers select a slice:
+const ${c.changedKeys[0]} = useContextSelector(${ctxName}, (v) => v.${c.changedKeys[0]});`
       });
       continue;
     }
-    if (!AVOIDABLE.has(c.kind)) continue;
+    if (!AVOIDABLE_KINDS.has(c.kind)) continue;
     if (isContext) {
-      out.push({ kind: "contextValue", owner: providerOwner || `${ctxName}.Provider`, target: r.component, prop: ctxName, label: `memoize the ${ctxName} provider value${providerOwner ? ` in <${providerOwner}>` : ""}`, detail: `${ctxName} produced a new value that is deep-equal to the previous one.` });
+      out.push({
+        kind: "contextValue",
+        owner: providerOwner || `${ctxName}.Provider`,
+        target: r.component,
+        prop: ctxName,
+        label: `memoize the ${ctxName} provider value${providerOwner ? ` in <${providerOwner}>` : ""}`,
+        detail: `<${r.component}> re-rendered because ${ctxName} produced a new value that is deep-equal to the previous one${providerOwner ? ` (Provider rendered by <${providerOwner}>)` : ""}.`,
+        snippet: `// ${providerOwner || `where <${ctxName}.Provider> is rendered`}
+const value = useMemo(() => ({ /* ... */ }), [/* deps */]);
+<${ctxName}.Provider value={value}>`
+      });
     } else if (c.hook === "useSyncExternalStore") {
       const chain = c.custom || [];
       const redux = chain.some((n) => /^use(App)?Selector$/.test(n));
       const zustand = !redux && chain.some((n) => /^use[A-Z]\w*Store$/.test(n) || n === "useStore" || n === "useBoundStore");
-      out.push({ kind: "storeSnapshot", owner: r.component, target: r.component, prop: c.path, label: redux ? `memoize the selector in <${r.component}>` : zustand ? `useShallow in <${r.component}>` : `stable getSnapshot in <${r.component}>`, detail: storeAdvice(c.custom) });
+      const via = chain.length ? ` via ${chain.join(" \u203A ")}` : "";
+      out.push({
+        kind: "storeSnapshot",
+        owner: r.component,
+        target: r.component,
+        prop: c.path,
+        label: redux ? `memoize the selector in <${r.component}>` : zustand ? `useShallow in <${r.component}>` : `stable getSnapshot in <${r.component}>`,
+        detail: redux ? `the selector${via} returns a new object on every call, so the component re-renders on every store change.` : zustand ? `the store selector${via} returns a new object on every call, so the component re-renders on every store change.` : `${c.path}${via} returned a new reference with the same contents; getSnapshot must return a cached value.`,
+        snippet: redux ? `// ${r.component}
+import { shallowEqual } from 'react-redux';
+const slice = useSelector(selectSlice, shallowEqual);
+// or memoize: const selectSlice = createSelector([selectA, selectB], (a, b) => ({ a, b }));` : zustand ? `// ${r.component}
+import { useShallow } from 'zustand/react/shallow';
+const { a, b } = useStore(useShallow((s) => ({ a: s.a, b: s.b })));
+// or select a primitive: const a = useStore((s) => s.a);` : `// ${r.component}
+// getSnapshot must return the same reference while the data is unchanged
+const snapshot = useSyncExternalStore(subscribe, store.getSnapshot /* cached */);`
+      });
     } else {
-      out.push({ kind: "bailout", owner: r.component, target: r.component, prop: c.path, label: `bail out before setting ${c.path} in <${r.component}>`, detail: `${c.path} was set to a value deep-equal to the current one (new reference).` });
+      out.push({
+        kind: "bailout",
+        owner: r.component,
+        target: r.component,
+        prop: c.path,
+        label: `bail out before setting ${c.path} in <${r.component}>`,
+        detail: `${c.path} was set to a value deep-equal to the current one (new reference).`,
+        snippet: `// ${r.component}
+setState((prev) => (deepEqual(prev, next) ? prev : next));`
+      });
     }
   }
   return out;
@@ -1213,11 +1523,12 @@ function rankFixes(reports) {
       const key = fixKey(f);
       let agg = byKey.get(key);
       if (!agg) {
-        agg = { ...f, key, count: 0, components: {} };
+        agg = { ...f, key, count: 0, components: {}, reports: [] };
         byKey.set(key, agg);
       }
       agg.count++;
       agg.components[r.component] = (agg.components[r.component] || 0) + 1;
+      if (agg.reports.length < MAX_FIX_REPORTS) agg.reports.push(r);
     }
   }
   return [...byKey.values()].sort((a, b) => b.count - a.count || a.label.localeCompare(b.label));
@@ -1227,6 +1538,8 @@ function formatFixes(reports, limit = 10) {
   if (!ranked.length) return "No avoidable re-renders.";
   const lines = ranked.slice(0, limit).map((f, i) => `${String(i + 1).padStart(2)}. ${f.label}  (removes ${f.count}: ${Object.entries(f.components).map(([c, n]) => `<${c}>${n > 1 ? " x" + n : ""}`).join(", ")})`);
   if (ranked.length > limit) lines.push(`    \u2026 ${ranked.length - limit} more`);
+  const roots = formatRootCauses(reports, 5);
+  if (roots) lines.push("", "Root causes:", roots);
   return lines.join("\n");
 }
 
@@ -1325,7 +1638,7 @@ ${formatFixes(reports)}`);
   };
 }
 
-// src/vitest.ts
+// src/runner-report.ts
 var OUT_ENV = "RERENDER_LENS_OUT";
 function setupRerenderLens(options = {}, hooks = {}) {
   ensureDevtoolsHook();
@@ -1360,49 +1673,55 @@ function slim(r) {
     state: void 0
   };
 }
-var RerenderLensReporter = class {
+function createRunFile() {
+  const dir = path.join(os.tmpdir(), "rerender-lens");
+  fs.mkdirSync(dir, { recursive: true });
+  const file = path.join(dir, `run-${process.pid}-${Date.now()}.jsonl`);
+  fs.writeFileSync(file, "");
+  process.env[OUT_ENV] = file;
+  return file;
+}
+function finishRun(file, options = {}) {
+  const reports = readRun(file);
+  const log = options.write ?? ((line) => void process.stdout.write(line + "\n"));
+  const avoidable = reports.filter((r) => r.avoidable).length;
+  let error = null;
+  log("");
+  log(`rerender-lens: ${reports.length} report${reports.length === 1 ? "" : "s"}, ${avoidable} avoidable across the run`);
+  if (avoidable) log(formatFixes(reports, options.limit ?? 10));
+  if (options.exportTo) fs.writeFileSync(options.exportTo, JSON.stringify({ rerenderLens: true, version: 2, exportedAt: (/* @__PURE__ */ new Date()).toISOString(), reports }, null, 2));
+  if (options.budget) {
+    const budget = JSON.parse(fs.readFileSync(options.budget, "utf8"));
+    const result = checkBudget(reports, budget);
+    if (!result.ok) {
+      const lines = result.violations.map((v) => `  budget exceeded: <${v.component}> ${v.avoidable} avoidable (allowed ${v.allowed})`);
+      for (const line of lines) log(line);
+      error = new Error(`rerender-lens: re-render budget exceeded (${options.budget})
+${lines.join("\n")}`);
+    } else log(`  within budget (${options.budget})`);
+  }
+  try {
+    fs.rmSync(file, { force: true });
+  } catch {
+  }
+  if (process.env[OUT_ENV] === file) delete process.env[OUT_ENV];
+  return { reports, error };
+}
+var RunReporterCore = class {
   constructor(options = {}) {
     this.done = false;
     this.options = options;
-    const dir = path.join(os.tmpdir(), "rerender-lens");
-    fs.mkdirSync(dir, { recursive: true });
-    this.file = path.join(dir, `run-${process.pid}-${Date.now()}.jsonl`);
-    fs.writeFileSync(this.file, "");
-    process.env[OUT_ENV] = this.file;
+    this.file = createRunFile();
   }
-  onInit() {
+  /** Publish the path again (the runner may have replaced `process.env` since the constructor ran). */
+  arm() {
     process.env[OUT_ENV] = this.file;
   }
-  onTestRunEnd() {
-    this.finish();
-  }
-  /** Vitest < 3 name for the same event. */
-  onFinished() {
-    this.finish();
-  }
+  /** The run's result, or null when the run was already finished (runners fire two "done" events). */
   finish() {
-    if (this.done) return;
+    if (this.done) return null;
     this.done = true;
-    const reports = readRun(this.file);
-    const log = this.options.write ?? ((line) => void process.stdout.write(line + "\n"));
-    const avoidable = reports.filter((r) => r.avoidable).length;
-    log("");
-    log(`rerender-lens: ${reports.length} report${reports.length === 1 ? "" : "s"}, ${avoidable} avoidable across the run`);
-    if (avoidable) log(formatFixes(reports, this.options.limit ?? 10));
-    if (this.options.exportTo) fs.writeFileSync(this.options.exportTo, JSON.stringify({ rerenderLens: true, version: 2, exportedAt: (/* @__PURE__ */ new Date()).toISOString(), reports }, null, 2));
-    if (this.options.budget) {
-      const budget = JSON.parse(fs.readFileSync(this.options.budget, "utf8"));
-      const result = checkBudget(reports, budget);
-      if (!result.ok) {
-        for (const v of result.violations) log(`  budget exceeded: <${v.component}> ${v.avoidable} avoidable (allowed ${v.allowed})`);
-        process.exitCode = 1;
-      } else log(`  within budget (${this.options.budget})`);
-    }
-    try {
-      fs.rmSync(this.file, { force: true });
-    } catch {
-    }
-    if (process.env[OUT_ENV] === this.file) delete process.env[OUT_ENV];
+    return finishRun(this.file, this.options);
   }
 };
 function readRun(file) {
@@ -1419,6 +1738,27 @@ function readRun(file) {
   return out;
 }
 
+// src/vitest.ts
+var RerenderLensReporter = class {
+  constructor(options = {}) {
+    this.core = new RunReporterCore(options);
+  }
+  onInit() {
+    this.core.arm();
+  }
+  onTestRunEnd() {
+    this.finish();
+  }
+  /** Vitest < 3 name for the same event. */
+  onFinished() {
+    this.finish();
+  }
+  finish() {
+    const result = this.core.finish();
+    if (result?.error) process.exitCode = 1;
+  }
+};
+
 exports.OUT_ENV = OUT_ENV;
 exports.checkBudget = checkBudget;
 exports.default = RerenderLensReporter;