rerender-lens 0.4.0 → 0.5.0

package/dist/runner-report-B8Sc3FZO.d.cts

@@ -0,0 +1,46 @@
+import { R as RenderReport, O as Options } from './types-DW5-N2XH.cjs';
+import { C as Collector } from './notifiers-DwKlvv4H.cjs';
+
+/** Environment variable carrying the path of the run's JSONL file from the reporter to the workers. */
+declare const OUT_ENV = "RERENDER_LENS_OUT";
+interface SetupOptions extends Omit<Options, 'notifier'> {
+    /** Also fail each test file that recorded avoidable re-renders (default false: the reporter decides). */
+    failFast?: boolean;
+}
+/** How the setup ties into the test runner (`{ afterAll }` from the runner's globals). */
+interface SetupHooks {
+    afterAll?: (fn: () => void) => void;
+    /** Path of the current test file, for the reporter's output. */
+    testPath?: () => string | undefined;
+}
+interface LensSetup {
+    collector: Collector;
+    /** Append this file's reports to the shared output and clear the collector; registered with `afterAll` when given. */
+    flush(): void;
+}
+/**
+ * Call from a setup file. Creates the DevTools hook before react-dom loads, starts the library with
+ * a collector, and appends this file's reports to the shared output when it ends. The collector is
+ * returned for per-test assertions (`assertNoAvoidable`, `assertWithinBudget`).
+ */
+declare function setupRerenderLens(options?: SetupOptions, hooks?: SetupHooks): LensSetup;
+interface ReporterOptions {
+    /** Path to a budget JSON (`{ "*": 0, "Row": 2 }`). When set, the run fails on violations. */
+    budget?: string;
+    /** Print at most this many fixes. Default 10. */
+    limit?: number;
+    /** Also write the collected reports here as a panel-compatible export (`Sessions > Import`). */
+    exportTo?: string;
+    /** Where the lines go. Default `process.stdout`. */
+    write?: (line: string) => void;
+}
+interface RunResult {
+    /** Every report of the run, from every worker. */
+    reports: RenderReport[];
+    /** Set when a budget file was given and exceeded; the run must fail. */
+    error: Error | null;
+}
+/** Reports from every worker of a run. */
+declare function readRun(file: string): RenderReport[];
+
+export { type LensSetup as L, OUT_ENV as O, type ReporterOptions as R, type SetupHooks as S, type RunResult as a, type SetupOptions as b, readRun as r, setupRerenderLens as s };

package/dist/runner-report-CW8X5RwK.d.ts

@@ -0,0 +1,46 @@
+import { R as RenderReport, O as Options } from './types-DW5-N2XH.js';
+import { C as Collector } from './notifiers-FNzKHs0a.js';
+
+/** Environment variable carrying the path of the run's JSONL file from the reporter to the workers. */
+declare const OUT_ENV = "RERENDER_LENS_OUT";
+interface SetupOptions extends Omit<Options, 'notifier'> {
+    /** Also fail each test file that recorded avoidable re-renders (default false: the reporter decides). */
+    failFast?: boolean;
+}
+/** How the setup ties into the test runner (`{ afterAll }` from the runner's globals). */
+interface SetupHooks {
+    afterAll?: (fn: () => void) => void;
+    /** Path of the current test file, for the reporter's output. */
+    testPath?: () => string | undefined;
+}
+interface LensSetup {
+    collector: Collector;
+    /** Append this file's reports to the shared output and clear the collector; registered with `afterAll` when given. */
+    flush(): void;
+}
+/**
+ * Call from a setup file. Creates the DevTools hook before react-dom loads, starts the library with
+ * a collector, and appends this file's reports to the shared output when it ends. The collector is
+ * returned for per-test assertions (`assertNoAvoidable`, `assertWithinBudget`).
+ */
+declare function setupRerenderLens(options?: SetupOptions, hooks?: SetupHooks): LensSetup;
+interface ReporterOptions {
+    /** Path to a budget JSON (`{ "*": 0, "Row": 2 }`). When set, the run fails on violations. */
+    budget?: string;
+    /** Print at most this many fixes. Default 10. */
+    limit?: number;
+    /** Also write the collected reports here as a panel-compatible export (`Sessions > Import`). */
+    exportTo?: string;
+    /** Where the lines go. Default `process.stdout`. */
+    write?: (line: string) => void;
+}
+interface RunResult {
+    /** Every report of the run, from every worker. */
+    reports: RenderReport[];
+    /** Set when a budget file was given and exceeded; the run must fail. */
+    error: Error | null;
+}
+/** Reports from every worker of a run. */
+declare function readRun(file: string): RenderReport[];
+
+export { type LensSetup as L, OUT_ENV as O, type ReporterOptions as R, type SetupHooks as S, type RunResult as a, type SetupOptions as b, readRun as r, setupRerenderLens as s };

package/dist/setup.cjs

@@ -161,30 +161,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
@@ -202,10 +202,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)`;
@@ -221,6 +223,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`;
@@ -248,11 +251,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)}).`);
   }
@@ -261,9 +274,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) {
@@ -275,6 +288,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.`);
@@ -305,6 +320,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;
@@ -342,10 +358,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(", ");
 }
@@ -408,6 +424,27 @@ function dispatch(report, override) {
 }
 
 // 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) {
@@ -422,7 +459,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;
@@ -722,6 +759,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;
@@ -900,7 +942,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}`,
@@ -934,6 +977,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";
@@ -966,10 +1013,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) {
@@ -982,7 +1045,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");
@@ -1022,6 +1085,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;
@@ -1031,7 +1112,7 @@ 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();
@@ -1041,7 +1122,7 @@ function onCommit(root, commitPriority) {
       renderedNames.add(fiberName(fiber));
       if (shouldTrack(fiberType(fiber), o)) 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);
     }
@@ -1053,10 +1134,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;
@@ -1108,6 +1189,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,
@@ -1290,7 +1374,7 @@ function flash(target, duration = 500) {
 }
 
 // src/version.ts
-var VERSION = "0.4.0" ;
+var VERSION = "0.5.0" ;
 
 // src/devtools.ts
 var DEVTOOLS_MARKER = "__rerenderLens";
@@ -1623,15 +1707,16 @@ function createDevtoolsNotifier(options = {}) {
 }
 
 // src/setup.ts
-var env = (key) => {
+var read = (get) => {
   try {
-    return typeof process !== "undefined" && process && process.env ? process.env[key] : void 0;
+    return get();
   } catch {
     return void 0;
   }
 };
-if (env("NODE_ENV") !== "production" && typeof window !== "undefined" && !window.__RERENDER_LENS_DEVTOOLS__) {
-  const relay = env("RERENDER_LENS_RELAY") || env("NEXT_PUBLIC_RERENDER_LENS_RELAY");
+var production = read(() => process.env.NODE_ENV) === "production";
+if (!production && typeof window !== "undefined" && !window.__RERENDER_LENS_DEVTOOLS__) {
+  const relay = read(() => process.env.RERENDER_LENS_RELAY) || read(() => process.env.NEXT_PUBLIC_RERENDER_LENS_RELAY);
   init({ trackAllMemoized: true, notifier: createDevtoolsNotifier(relay ? { relay } : {}) });
 }
 //# sourceMappingURL=setup.cjs.map