rerender-lens 0.2.0 → 0.3.0

package/dist/index.cjs

@@ -147,6 +147,17 @@ function firstDifferentPath(a, b, path, depth = 0) {
 
 // src/report.ts
 var now = () => typeof performance !== "undefined" && typeof performance.now === "function" ? performance.now() : Date.now();
+var hookLabel = (c) => c.custom && c.custom.length ? `${c.custom.join(" \u203A ")} \u203A ${c.hook}#${c.index}` : `${c.hook} #${c.index}`;
+function storeAdvice(custom) {
+  const chain = custom ?? [];
+  if (chain.some((n) => /^useSelector$/.test(n)))
+    return "the Redux selector returns a new object on every call: return a stored slice, pass shallowEqual as the equality function, or memoize it with createSelector";
+  if (chain.some((n) => /^useAppSelector$/.test(n)))
+    return "the selector returns a new object on every call: return a stored slice, pass shallowEqual, or memoize it with createSelector";
+  if (chain.some((n) => /^use[A-Z]\w*Store$/.test(n) || n === "useStore" || n === "useBoundStore"))
+    return "the store selector returns a new object on every call: select a primitive, or wrap the selector with useShallow (Zustand) / an equality function";
+  return "getSnapshot returns a new reference with the same contents: cache the snapshot in the store and return the same object while the data is unchanged";
+}
 var isGenuine = (c) => c.kind === "different" || c.kind === "added" || c.kind === "removed";
 var isChildren = (change) => change.path === "children";
 function fixFor(change) {
@@ -222,10 +233,17 @@ 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 (isGenuine(c)) reasons.push(`${c.hook} #${c.index} changed.`);
+    } else if (isGenuine(c)) reasons.push(`${hookLabel(c)} changed.`);
     else if (isStateHook(c))
-      reasons.push(`${c.hook} #${c.index} 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.`);
-    else reasons.push(`${c.hook} #${c.index} returned a new reference that is deep-equal to the previous value: memoize the context/store value where it is produced.`);
+      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.`);
+    else if (c.hook === "useSyncExternalStore") reasons.push(`${hookLabel(c)} returned a new reference that is deep-equal to the previous value: ${storeAdvice(c.custom)}.`);
+    else reasons.push(`${hookLabel(c)} returned a new reference that is deep-equal to the previous value: memoize the context/store value where it is produced.`);
+  }
+  if (input.commitCause === "effect-after-commit") {
+    const who = input.updaters && input.updaters.length ? input.updaters.map((u) => `<${u}>`).join(", ") : "a component that rendered in it";
+    reasons.push(`this commit was scheduled right after commit #${input.afterCommit ?? "?"} by ${who}: an effect there set state (effect \u2192 setState loop). Derive the value during render or compute it before setting state.`);
+  } else if (input.commitCause === "suspense-resolved") {
+    reasons.push("this commit shows content that was suspended (a Suspense boundary resolved).");
   }
   const report = {
     component: input.component,
@@ -249,6 +267,13 @@ function buildReport(input) {
   if (input.treeDuration !== void 0) report.treeDuration = input.treeDuration;
   if (input.commitPriority) report.commitPriority = input.commitPriority;
   if (input.source) report.source = input.source;
+  if (input.hookState) report.hookState = input.hookState;
+  if (input.contexts) report.contexts = input.contexts;
+  if (input.state) report.state = input.state;
+  if (input.updaters && input.updaters.length) report.updaters = input.updaters;
+  if (input.commitCause) report.commitCause = input.commitCause;
+  if (input.afterCommit !== void 0) report.afterCommit = input.afterCommit;
+  if (input.key !== void 0) report.key = input.key;
   return report;
 }
 function describeTrigger(t) {
@@ -293,6 +318,9 @@ function printReport(report, options) {
     c.log(`${ch.path} (${KIND_LABEL[ch.kind]})`, { prev: ch.prev, next: ch.next });
   }
   c.log("props", report.props);
+  if (report.hookState && report.hookState.length) c.log("hooks", Object.fromEntries(report.hookState.map((h) => [h.path, h.value])));
+  if (report.contexts && report.contexts.length) c.log("contexts", Object.fromEntries(report.contexts.map((x) => [x.name, x.value])));
+  if (report.state) c.log("state", report.state);
   c.groupEnd();
 }
 
@@ -302,7 +330,7 @@ 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 };
+    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 };
     g[KEY] = s;
   }
   return s;
@@ -337,6 +365,171 @@ function dispatch(report, override) {
   }
 }
 
+// src/hookNames.ts
+var noop = () => {
+};
+function customHooksFromStack(stack, componentName, marker) {
+  const names = [];
+  let past = false;
+  for (const line of stack.split("\n")) {
+    const m = /^\s*at\s+(?:async\s+)?([^\s(]+)|^([^@\s]+)@/.exec(line);
+    const name = m ? (m[1] || m[2] || "").replace(/^Object\./, "").replace(/^Proxy\./, "") : "";
+    if (!name) continue;
+    if (!past) {
+      if (name.includes(marker)) past = true;
+      continue;
+    }
+    if (name === componentName || name.endsWith("." + componentName)) break;
+    if (/^use[A-Z0-9_]/.test(name)) names.push(name);
+    if (names.length > 8) break;
+  }
+  return names;
+}
+var cache = /* @__PURE__ */ new WeakMap();
+function makeDispatcher(fiber, componentName, out, marker) {
+  let node = fiber.memoizedState;
+  let index = 0;
+  const take = (count) => {
+    const first = node;
+    for (let i = 0; i < count && node; i++) node = node.next;
+    index += count;
+    return first;
+  };
+  const record = (primitive, count) => {
+    const stack = new Error().stack || "";
+    const chain = customHooksFromStack(stack, componentName, marker);
+    const start = index;
+    const first = take(count);
+    if (chain.length) for (let i = 0; i < count; i++) out.set(start + i, chain);
+    return first;
+  };
+  const memoized = (n) => n ? n.memoizedState : void 0;
+  const dispatcher = {};
+  const define = (name, impl) => {
+    const fn = { [marker + name]: (...a) => impl(...a) }[marker + name];
+    dispatcher[name] = fn;
+  };
+  define("useState", () => {
+    const n = record("useState", 1);
+    return [memoized(n), noop];
+  });
+  define("useReducer", () => {
+    const n = record("useReducer", 1);
+    return [memoized(n), noop];
+  });
+  define("useRef", (init2) => {
+    const n = record("useRef", 1);
+    return n ? n.memoizedState : { current: init2 };
+  });
+  define("useMemo", (fn) => {
+    const n = record("useMemo", 1);
+    const s = memoized(n);
+    return Array.isArray(s) ? s[0] : typeof fn === "function" ? fn() : void 0;
+  });
+  define("useCallback", (fn) => {
+    const n = record("useCallback", 1);
+    const s = memoized(n);
+    return Array.isArray(s) ? s[0] : fn;
+  });
+  for (const effect of ["useEffect", "useLayoutEffect", "useInsertionEffect", "useImperativeHandle"]) define(effect, () => void record(effect, 1));
+  define("useContext", (ctx) => {
+    record("useContext", 0);
+    const c = ctx;
+    return c ? c._currentValue : void 0;
+  });
+  define("useDebugValue", () => void record("useDebugValue", 0));
+  define("useSyncExternalStore", (_subscribe, getSnapshot) => {
+    const n = record("useSyncExternalStore", 2);
+    return n ? n.memoizedState : typeof getSnapshot === "function" ? getSnapshot() : void 0;
+  });
+  define("useTransition", () => {
+    record("useTransition", 2);
+    return [false, noop];
+  });
+  define("useDeferredValue", (v) => {
+    const n = record("useDeferredValue", 1);
+    return n ? n.memoizedState : v;
+  });
+  define("useId", () => {
+    const n = record("useId", 1);
+    return n ? n.memoizedState : "id";
+  });
+  define("useOptimistic", (v) => {
+    const n = record("useOptimistic", 1);
+    return [n ? n.memoizedState : v, noop];
+  });
+  for (const action of ["useActionState", "useFormState"]) {
+    define(action, (_fn, init2) => {
+      const n = record(action, 3);
+      return [n ? n.memoizedState : init2, noop, false];
+    });
+  }
+  define("useEffectEvent", (fn) => {
+    record("useEffectEvent", 1);
+    return fn;
+  });
+  define("useCacheRefresh", () => {
+    record("useCacheRefresh", 1);
+    return noop;
+  });
+  define("useHostTransitionStatus", () => ({ pending: false, data: null, method: null, action: null }));
+  define("useMemoCache", (size) => new Array(Number(size) || 0).fill(/* @__PURE__ */ Symbol.for("react.memo_cache_sentinel")));
+  define("use", (usable) => {
+    record("use", 0);
+    const u = usable;
+    if (u && typeof u.then === "function") {
+      if (u.status === "fulfilled") return u.value;
+      throw new Error("rerender-lens: cannot replay use() on a pending promise");
+    }
+    return u ? u._currentValue : void 0;
+  });
+  define("readContext", (ctx) => ctx?._currentValue);
+  return { dispatcher, nodesConsumed: () => index };
+}
+function renderFunctionOf(type) {
+  let t = type;
+  while (t && typeof t === "object" && t.type) t = t.type;
+  if (t && typeof t === "object" && typeof t.render === "function") return { fn: t.render, name: t.render.name || t.displayName || "Component" };
+  if (typeof t === "function") return { fn: t, name: t.name || "Component" };
+  return { fn: null, name: "Component" };
+}
+function resolveHookNames(fiber, ref) {
+  const type = fiber.type;
+  if (!type || !ref) return /* @__PURE__ */ new Map();
+  const cached = cache.get(type);
+  if (cached) return cached.byNode;
+  const result = { byNode: /* @__PURE__ */ new Map(), ok: false };
+  cache.set(type, result);
+  const { fn, name } = renderFunctionOf(type);
+  if (!fn) return result.byNode;
+  const useH = "H" in ref;
+  const marker = "__rl_";
+  const previous = useH ? ref.H : ref.current;
+  const { dispatcher, nodesConsumed } = makeDispatcher(fiber, name, result.byNode, marker);
+  const proxy = new Proxy(dispatcher, {
+    get(target, key) {
+      if (key in target) return target[key];
+      return () => void 0;
+    }
+  });
+  let total = 0;
+  for (let n = fiber.memoizedState; n && typeof n === "object" && "next" in n; n = n.next) total++;
+  try {
+    if (useH) ref.H = proxy;
+    else ref.current = proxy;
+    const secondArg = fiber.tag === 11 ? fiber.stateNode?.ref ?? null : void 0;
+    fn(fiber.memoizedProps ?? {}, secondArg);
+    result.ok = nodesConsumed() === total;
+    if (!result.ok) result.byNode.clear();
+  } catch {
+    result.byNode.clear();
+  } finally {
+    if (useH) ref.H = previous;
+    else ref.current = previous;
+  }
+  return result.byNode;
+}
+
 // src/fiber.ts
 var FunctionComponent = 0;
 var ClassComponent = 1;
@@ -344,10 +537,12 @@ var HostRoot = 3;
 var HostComponent = 5;
 var ContextProvider = 10;
 var ForwardRef = 11;
+var SuspenseComponent = 13;
 var MemoComponent = 14;
 var SimpleMemoComponent = 15;
 var PerformedWork = 1;
 var HOOK = "__REACT_DEVTOOLS_GLOBAL_HOOK__";
+var nowMs = () => typeof performance !== "undefined" && typeof performance.now === "function" ? performance.now() : Date.now();
 function ensureDevtoolsHook() {
   const g = globalThis;
   let hook = g[HOOK];
@@ -376,7 +571,9 @@ function ensureDevtoolsHook() {
   return hook;
 }
 var capturedRenderers = /* @__PURE__ */ new Map();
+var dispatcherRefs = /* @__PURE__ */ new Map();
 var INJECT_WRAPPED = /* @__PURE__ */ Symbol.for("rerender-lens.injectWrapped");
+var ATTACHED = /* @__PURE__ */ Symbol.for("rerender-lens.attached");
 function pickRenderer(r) {
   const info = r ?? {};
   return { version: info.version, bundleType: info.bundleType, rendererPackageName: info.rendererPackageName };
@@ -387,20 +584,45 @@ function wrapInject(hook) {
   const original = hook.inject;
   hook.inject = function(renderer) {
     const id = original.call(this, renderer);
-    capturedRenderers.set(typeof id === "number" ? id : capturedRenderers.size + 1, pickRenderer(renderer));
+    const key = typeof id === "number" ? id : capturedRenderers.size + 1;
+    capturedRenderers.set(key, pickRenderer(renderer));
+    const ref = renderer?.currentDispatcherRef;
+    if (ref && typeof ref === "object") dispatcherRefs.set(key, ref);
     return id;
   };
   h[INJECT_WRAPPED] = true;
 }
+function getDispatcherRef() {
+  for (const ref of dispatcherRefs.values()) return ref;
+  const g = globalThis;
+  const hook = g[HOOK];
+  let found = null;
+  if (hook && hook.renderers && typeof hook.renderers.forEach === "function") {
+    hook.renderers.forEach((r) => {
+      const ref = r?.currentDispatcherRef;
+      if (!found && ref && typeof ref === "object") found = ref;
+    });
+  }
+  return found;
+}
 function attach() {
   const hook = ensureDevtoolsHook();
   wrapInject(hook);
+  if (hook[ATTACHED]) return () => {
+  };
+  hook[ATTACHED] = true;
   const previous = hook.onCommitFiberRoot;
   const patched = function(id, root, priority, didError) {
+    const started = nowMs();
     try {
       onCommit(root, priorityLabel(priority));
     } catch (err) {
       warnOnce("commit", `failed to inspect a commit: ${String(err)}`);
+    } finally {
+      const spent = nowMs() - started;
+      const s = getState();
+      s.overheadMs += spent;
+      if (spent > s.maxCommitMs) s.maxCommitMs = spent;
     }
     if (typeof previous === "function") return previous.call(this, id, root, priority, didError);
   };
@@ -412,6 +634,7 @@ function attach() {
   };
   hook.onScheduleFiberRoot = patchedSchedule;
   return () => {
+    hook[ATTACHED] = false;
     if (hook.onCommitFiberRoot === patched) hook.onCommitFiberRoot = previous;
     if (hook.onScheduleFiberRoot === patchedSchedule) hook.onScheduleFiberRoot = previousSchedule;
   };
@@ -581,7 +804,7 @@ function ownerName(fiber) {
 }
 var isStateNode = (n) => !!n.queue && typeof n.queue.lastRenderedReducer === "function";
 var isStoreNode = (n) => !!n.queue && typeof n.queue.getSnapshot === "function";
-function hookLabel(node) {
+function hookLabel2(node) {
   if (isStoreNode(node)) return "useSyncExternalStore";
   if (isStateNode(node)) {
     const r = node.queue.lastRenderedReducer;
@@ -590,20 +813,43 @@ function hookLabel(node) {
   return "state";
 }
 var NODELESS_HOOKS = /* @__PURE__ */ new Set(["useContext", "useDebugValue", "use"]);
+function hookLabelsFor(fiber, first) {
+  const types = fiber._debugHookTypes?.filter((t) => !NODELESS_HOOKS.has(t));
+  let nodeCount = 0;
+  for (let n = first; n; n = n.next) nodeCount++;
+  return types && types.length === nodeCount ? types : null;
+}
+var isHookList = (v) => !!v && typeof v === "object" && "next" in v;
+function snapshotHooks(fiber) {
+  const out = [];
+  if (fiber.tag === ClassComponent) return out;
+  const first = fiber.memoizedState;
+  if (!isHookList(first)) return out;
+  const labels = hookLabelsFor(fiber, first);
+  let i = 0;
+  for (let n = first; n; n = n.next, i++) {
+    if (!isStateNode(n) && !isStoreNode(n)) continue;
+    const hook = labels?.[i] ?? hookLabel2(n);
+    out.push({ path: `${hook}#${i}`, hook, index: i, value: n.memoizedState });
+  }
+  return out;
+}
+function snapshotContexts(fiber) {
+  const out = [];
+  for (let d = fiber.dependencies?.firstContext ?? null; d; d = d.next) out.push({ name: d.context.displayName ?? "Context", value: d.memoizedValue });
+  return out;
+}
 function diffHooks(fiber, alt) {
   const out = [];
   if (fiber.tag === ClassComponent) return out;
   let a = alt.memoizedState;
   let b = fiber.memoizedState;
   if (!a || !b || typeof b !== "object" || !("next" in b)) return out;
-  const types = fiber._debugHookTypes?.filter((t) => !NODELESS_HOOKS.has(t));
-  let nodeCount = 0;
-  for (let n = b; n; n = n.next) nodeCount++;
-  const labels = types && types.length === nodeCount ? types : null;
+  const labels = hookLabelsFor(fiber, b);
   let i = 0;
   while (a && b) {
     if ((isStateNode(b) || isStoreNode(b)) && !Object.is(a.memoizedState, b.memoizedState)) {
-      const hook = labels?.[i] ?? hookLabel(b);
+      const hook = labels?.[i] ?? hookLabel2(b);
       out.push({
         path: `${hook}#${i}`,
         hook,
@@ -692,14 +938,14 @@ function analyze(fiber, alt, trackHooks) {
   const trigger = causes.length === 0 ? "parent" : causes.length === 1 ? causes[0] : "mixed";
   return { propChanges, stateChanges, hookChanges, trigger };
 }
-function nearestRenderedAncestor(fiber, cache, trackHooks) {
+function nearestRenderedAncestor(fiber, cache2, trackHooks) {
   let f = fiber.return;
   while (f && f.tag !== HostRoot) {
     if (isComponentTag(f.tag) && f.alternate && didRender(f)) {
-      let info = cache.get(f);
+      let info = cache2.get(f);
       if (info === void 0) {
         info = { name: fiberName(f), trigger: analyze(f, f.alternate, trackHooks).trigger };
-        cache.set(f, info);
+        cache2.set(f, info);
       }
       return info;
     }
@@ -707,6 +953,21 @@ function nearestRenderedAncestor(fiber, cache, trackHooks) {
   }
   return null;
 }
+function updatersOf(root) {
+  const set = root.memoizedUpdaters;
+  if (!set || typeof set.forEach !== "function") return [];
+  const names = [];
+  set.forEach((f) => {
+    const comp = nearestComponent(f);
+    if (comp) {
+      const name = fiberName(comp);
+      if (!names.includes(name)) names.push(name);
+    }
+  });
+  return names;
+}
+var lastCommit = null;
+var EFFECT_LOOP_WINDOW_MS = 50;
 function onCommit(root, commitPriority) {
   const s = getState();
   if (!s.enabled) return;
@@ -714,28 +975,53 @@ function onCommit(root, commitPriority) {
   const o = s.options;
   const trackHooks = o.trackHooks !== false;
   const rendered = [];
+  const renderedNames = /* @__PURE__ */ new Set();
   let hot = false;
+  let suspenseResolved = false;
   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);
     }
+    if (fiber.tag === SuspenseComponent && alt && alt.memoizedState !== null && fiber.memoizedState === null) suspenseResolved = true;
     if (!alt || fiber.child !== alt.child) {
       for (let c = fiber.child; c; c = c.sibling) stack.push(c);
     }
   }
   if (hot && o.ignoreHotReload !== false) return;
   rendered.reverse();
-  if (rendered.length === 0) return;
+  const at = nowMs();
+  const updaters = updatersOf(root);
+  let commitCause;
+  let afterCommit;
+  if (lastCommit && at - lastCommit.at < EFFECT_LOOP_WINDOW_MS && updaters.some((u) => lastCommit.rendered.has(u))) {
+    commitCause = "effect-after-commit";
+    afterCommit = lastCommit.id;
+  } else if (suspenseResolved) commitCause = "suspense-resolved";
+  if (rendered.length === 0) {
+    lastCommit = { id: s.nextCommitId, at, rendered: renderedNames };
+    return;
+  }
   const commitId = s.nextCommitId++;
+  lastCommit = { id: commitId, at, rendered: renderedNames };
+  const dispatcherRef = o.resolveHookNames ? getDispatcherRef() : null;
   const parentCache = /* @__PURE__ */ new Map();
   for (const fiber of rendered) {
     const alt = fiber.alternate;
     const a = analyze(fiber, alt, trackHooks);
     const durations = durationsOf(fiber);
+    let hookState = o.includeState !== false && trackHooks ? snapshotHooks(fiber) : void 0;
+    if (dispatcherRef && fiber.tag !== ClassComponent && (a.hookChanges.length || hookState && hookState.length)) {
+      const names = resolveHookNames(fiber, dispatcherRef);
+      if (names.size) {
+        for (const c of a.hookChanges) if (c.hook !== "useContext" && names.has(c.index)) c.custom = names.get(c.index);
+        if (hookState) hookState = hookState.map((h) => names.has(h.index) ? { ...h, custom: names.get(h.index) } : h);
+      }
+    }
     const report = buildReport({
       component: fiberName(fiber),
       instanceId: instanceId(fiber),
@@ -745,6 +1031,15 @@ function onCommit(root, commitPriority) {
       propChanges: a.propChanges,
       stateChanges: a.stateChanges,
       hookChanges: a.hookChanges,
+      ...o.includeState !== false ? {
+        hookState,
+        contexts: trackHooks ? snapshotContexts(fiber) : void 0,
+        state: fiber.tag === ClassComponent && fiber.memoizedState && typeof fiber.memoizedState === "object" ? fiber.memoizedState : void 0
+      } : {},
+      updaters,
+      commitCause,
+      afterCommit,
+      key: fiber.key === null || fiber.key === void 0 ? null : String(fiber.key),
       parent: a.trigger === "parent" ? nearestRenderedAncestor(fiber, parentCache, trackHooks) : null,
       owner: ownerName(fiber),
       path: componentPath(fiber),
@@ -857,6 +1152,201 @@ function useWhyRerender(name, values, options) {
   });
 }
 
+// src/fixes.ts
+var AVOIDABLE = /* @__PURE__ */ new Set(["deep-equal", "function", "element"]);
+var rootOf = (path) => path.split(/[.[]/)[0] || path;
+function fixesFor(r) {
+  const out = [];
+  const owner = r.owner || r.parent && r.parent.name || "?";
+  const changes = [...r.propChanges, ...r.stateChanges, ...r.hookChanges];
+  if (r.avoidable && (changes.length === 0 || r.memoized === false)) {
+    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.`
+    });
+  }
+  for (const c of r.propChanges) {
+    if (!AVOIDABLE.has(c.kind)) continue;
+    const root = rootOf(c.path);
+    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.` });
+    } 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}>.` });
+    } 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}>.` });
+    } 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}>.` });
+    }
+  }
+  for (const c of [...r.stateChanges, ...r.hookChanges]) {
+    const isContext = c.hook === "useContext";
+    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) {
+      out.push({
+        kind: "splitContext",
+        owner: providerOwner || `${ctxName}.Provider`,
+        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.`
+      });
+      continue;
+    }
+    if (!AVOIDABLE.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.` });
+    } 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) });
+    } 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).` });
+    }
+  }
+  return out;
+}
+var fixKey = (f) => `${f.kind}|${f.owner}|${f.prop || f.target}`;
+function rankFixes(reports) {
+  const byKey = /* @__PURE__ */ new Map();
+  for (const r of reports) {
+    if (!r.avoidable) continue;
+    for (const f of fixesFor(r)) {
+      const key = fixKey(f);
+      let agg = byKey.get(key);
+      if (!agg) {
+        agg = { ...f, key, count: 0, components: {} };
+        byKey.set(key, agg);
+      }
+      agg.count++;
+      agg.components[r.component] = (agg.components[r.component] || 0) + 1;
+    }
+  }
+  return [...byKey.values()].sort((a, b) => b.count - a.count || a.label.localeCompare(b.label));
+}
+function formatFixes(reports, limit = 10) {
+  const ranked = rankFixes(reports);
+  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`);
+  return lines.join("\n");
+}
+
+// src/sessions.ts
+function summarizeReports(reports, meta = {}) {
+  var _a;
+  const byComponent = {};
+  let avoidable = 0;
+  let wasted = 0;
+  for (const r of reports) {
+    const c = byComponent[_a = r.component] || (byComponent[_a] = { total: 0, avoidable: 0, wasted: 0 });
+    c.total++;
+    if (r.avoidable) {
+      c.avoidable++;
+      avoidable++;
+      if (typeof r.selfDuration === "number") {
+        c.wasted += r.selfDuration;
+        wasted += r.selfDuration;
+      }
+    }
+  }
+  return {
+    id: meta.id ?? `s${Date.now().toString(36)}`,
+    name: meta.name ?? "session",
+    startedAt: meta.startedAt ?? (reports[0]?.time ?? 0),
+    endedAt: meta.endedAt ?? (reports[reports.length - 1]?.time ?? null),
+    total: reports.length,
+    avoidable,
+    wasted,
+    byComponent,
+    fixes: rankFixes(reports).map((f) => ({ key: f.key, label: f.label, count: f.count }))
+  };
+}
+function compareSummaries(before, after) {
+  const names = /* @__PURE__ */ new Set([...Object.keys(before.byComponent), ...Object.keys(after.byComponent)]);
+  const rows = [];
+  for (const component of names) {
+    const b = before.byComponent[component]?.avoidable || 0;
+    const a = after.byComponent[component]?.avoidable || 0;
+    if (b || a) rows.push({ component, before: b, after: a, delta: a - b });
+  }
+  rows.sort((x, y) => x.delta - y.delta || y.before - x.before || x.component.localeCompare(y.component));
+  const afterKeys = new Set(after.fixes.map((f) => f.key));
+  const beforeKeys = new Set(before.fixes.map((f) => f.key));
+  return {
+    before,
+    after,
+    rows,
+    total: { before: before.total, after: after.total, delta: after.total - before.total },
+    avoidable: { before: before.avoidable, after: after.avoidable, delta: after.avoidable - before.avoidable },
+    wasted: { before: before.wasted, after: after.wasted, delta: after.wasted - before.wasted },
+    resolvedFixes: before.fixes.filter((f) => !afterKeys.has(f.key)),
+    newFixes: after.fixes.filter((f) => !beforeKeys.has(f.key)),
+    regressions: rows.filter((r) => r.delta > 0)
+  };
+}
+function formatComparison(c) {
+  const w = Math.max(14, ...c.rows.map((r) => r.component.length + 2));
+  const line = (label, b, a, d) => `${label.padEnd(w)} ${String(b).padStart(8)} ${String(a).padStart(8)} ${d.padStart(8)}`;
+  const delta = (n, suffix = "") => n === 0 ? "\xB10" : `${n > 0 ? "+" : ""}${Number.isInteger(n) ? n : n.toFixed(1)}${suffix}`;
+  const out = [line("avoidable", c.before.name.slice(0, 8), c.after.name.slice(0, 8), "\u0394"), line("all components", c.avoidable.before, c.avoidable.after, delta(c.avoidable.delta))];
+  if (c.wasted.before || c.wasted.after) out.push(line("wasted ms", c.wasted.before.toFixed(1), c.wasted.after.toFixed(1), delta(Number(c.wasted.delta.toFixed(1)))));
+  for (const r of c.rows) out.push(line(`<${r.component}>`, r.before, r.after, delta(r.delta)));
+  if (c.resolvedFixes.length) out.push("", "no longer needed:", ...c.resolvedFixes.map((f) => `  - ${f.label}`));
+  if (c.newFixes.length) out.push("", "new:", ...c.newFixes.map((f) => `  - ${f.label}`));
+  return out.join("\n");
+}
+function parseExport(data) {
+  if (Array.isArray(data)) return { reports: data, sessions: [], summary: null };
+  if (data && typeof data === "object") {
+    const d = data;
+    if (Array.isArray(d.reports)) return { reports: d.reports, sessions: Array.isArray(d.sessions) ? d.sessions : [], summary: null };
+    if (d.byComponent && typeof d.byComponent === "object") return { reports: [], sessions: [], summary: data };
+  }
+  throw new Error("not a rerender-lens export or session summary");
+}
+
+// src/budget.ts
+function avoidableCounts(reports) {
+  const counts2 = {};
+  for (const r of reports) if (r.avoidable) counts2[r.component] = (counts2[r.component] || 0) + 1;
+  return counts2;
+}
+function checkBudget(reports, budget) {
+  const b = typeof budget === "number" ? { "*": budget } : budget;
+  const fallback = typeof b["*"] === "number" ? b["*"] : 0;
+  const counts2 = avoidableCounts(reports);
+  const violations = [];
+  const slack = [];
+  const names = /* @__PURE__ */ new Set([...Object.keys(counts2), ...Object.keys(b).filter((k) => k !== "*")]);
+  for (const component of names) {
+    const allowed = typeof b[component] === "number" ? b[component] : fallback;
+    const avoidable = counts2[component] || 0;
+    if (avoidable > allowed) violations.push({ component, avoidable, allowed });
+    else if (avoidable < allowed) slack.push({ component, avoidable, allowed });
+  }
+  violations.sort((x, y) => y.avoidable - y.allowed - (x.avoidable - x.allowed));
+  return { ok: violations.length === 0, violations, slack, counts: counts2 };
+}
+function toBudget(reports) {
+  return { "*": 0, ...avoidableCounts(reports) };
+}
+function assertWithinBudget(reports, budget) {
+  const result = checkBudget(reports, budget);
+  if (result.ok) return result;
+  const lines = result.violations.map((v) => `  <${v.component}>: ${v.avoidable} avoidable re-render${v.avoidable === 1 ? "" : "s"} (budget ${v.allowed})`);
+  throw new Error(`Re-render budget exceeded:
+${lines.join("\n")}
+
+Fixes, most impact first:
+${formatFixes(reports)}`);
+}
+
 // src/notifiers.ts
 function createCollector() {
   const reports = [];
@@ -877,8 +1367,14 @@ function createCollector() {
       const lines = bad.map((r) => `  <${r.component}> render #${r.renderCount}:
 ${r.reasons.map((x) => `    - ${x}`).join("\n")}`);
       throw new Error(`${bad.length} avoidable re-render${bad.length === 1 ? "" : "s"} detected:
-${lines.join("\n")}`);
-    }
+${lines.join("\n")}
+
+Fixes, most impact first:
+${formatFixes(reports)}`);
+    },
+    fixes: () => rankFixes(reports),
+    summary: (name) => summarizeReports(reports, name ? { name } : {}),
+    assertWithinBudget: (budget) => assertWithinBudget(reports, budget)
   };
 }
 function combineNotifiers(...notifiers) {
@@ -976,11 +1472,12 @@ function flash(target, duration = 500) {
 }
 
 // src/version.ts
-var VERSION = "0.2.0" ;
+var VERSION = "0.3.0" ;
 
 // src/devtools.ts
 var DEVTOOLS_MARKER = "__rerenderLens";
 var PROTOCOL_VERSION = 2;
+var DEFAULT_CHANNEL = "rerender-lens";
 function serialize(value, maxDepth = 6, seen = /* @__PURE__ */ new WeakSet(), depth = 0) {
   if (value === null || value === void 0) return value;
   const t = typeof value;
@@ -1031,7 +1528,7 @@ var stringToMatcher = (s) => {
 };
 function serializeOptions(o) {
   const out = {};
-  const bools = ["trackAllMemoized", "trackAllComponents", "trackHooks", "logAll", "silent", "collapse", "ignoreHotReload"];
+  const bools = ["trackAllMemoized", "trackAllComponents", "trackHooks", "includeState", "resolveHookNames", "logAll", "silent", "collapse", "ignoreHotReload"];
   for (const k of bools) if (typeof o[k] === "boolean") out[k] = o[k];
   if (typeof o.maxReportsPerComponent === "number") out.maxReportsPerComponent = o.maxReportsPerComponent;
   if (o.include) out.include = o.include.map(matcherToString).filter((x) => x !== null);
@@ -1040,7 +1537,7 @@ function serializeOptions(o) {
 }
 function deserializeOptions(o) {
   const out = {};
-  const bools = ["trackAllMemoized", "trackAllComponents", "trackHooks", "logAll", "silent", "collapse", "ignoreHotReload"];
+  const bools = ["trackAllMemoized", "trackAllComponents", "trackHooks", "includeState", "resolveHookNames", "logAll", "silent", "collapse", "ignoreHotReload"];
   for (const k of bools) if (typeof o[k] === "boolean") out[k] = o[k];
   if (typeof o.maxReportsPerComponent === "number") out.maxReportsPerComponent = o.maxReportsPerComponent;
   if (Array.isArray(o.include)) out.include = o.include.filter((s) => typeof s === "string" && s).map(stringToMatcher);
@@ -1071,7 +1568,8 @@ function createDevtoolsNotifier(options = {}) {
     source,
     injected: typeof window !== "undefined" && typeof window.__RERENDER_LENS_INJECTED__ === "string",
     scheduled: getState().scheduled,
-    commits: getState().commits
+    commits: getState().commits,
+    overhead: { totalMs: getState().overheadMs, maxCommitMs: getState().maxCommitMs }
   });
   const bridge = {
     replay: () => {
@@ -1136,12 +1634,126 @@ function createDevtoolsNotifier(options = {}) {
     }
   };
   if (typeof window !== "undefined") window.__RERENDER_LENS_DEVTOOLS__ = bridge;
-  post("hello", info());
+  const runCommand = (data) => {
+    const reply = { __rerenderLensReply: true, id: data.id };
+    try {
+      switch (data.cmd) {
+        case "info":
+          reply.result = info();
+          break;
+        case "pull":
+          reply.result = bridge.pull(typeof data.arg === "number" ? data.arg : 0);
+          break;
+        case "replay":
+          bridge.replay();
+          reply.result = true;
+          break;
+        case "clear":
+          bridge.clear();
+          reply.result = true;
+          break;
+        case "configure":
+          reply.result = bridge.configure(data.arg ?? {});
+          break;
+        case "highlight":
+          reply.result = bridge.highlight(typeof data.arg === "number" ? data.arg : null);
+          break;
+        case "flash":
+          bridge.flashAvoidable(!!data.arg);
+          reply.result = true;
+          break;
+        default:
+          reply.error = `unknown command ${String(data.cmd)}`;
+      }
+    } catch (e) {
+      reply.error = String(e.message || e);
+    }
+    return reply;
+  };
+  const isCommand = (data) => !!data && typeof data === "object" && data.__rerenderLensCmd === true && typeof data.id === "string";
+  const envelope = (type, payload) => ({ [DEVTOOLS_MARKER]: true, version: PROTOCOL_VERSION, type, payload });
+  const sinks = [];
+  if (options.channel && typeof BroadcastChannel === "function") {
+    const name = typeof options.channel === "string" ? options.channel : DEFAULT_CHANNEL;
+    try {
+      const channel = new BroadcastChannel(name);
+      channel.onmessage = (event) => {
+        if (isCommand(event.data)) channel.postMessage(runCommand(event.data));
+      };
+      sinks.push((message) => {
+        try {
+          channel.postMessage(message);
+        } catch {
+        }
+      });
+    } catch {
+    }
+  }
+  const relayUrl = options.relay ?? (typeof window !== "undefined" ? window.__RERENDER_LENS_RELAY__ : void 0);
+  const ES = options.eventSource ?? (typeof EventSource === "function" ? EventSource : null);
+  if (relayUrl && ES && typeof fetch === "function") {
+    const base = relayUrl.replace(/\/$/, "");
+    let queue = [];
+    let scheduled = false;
+    const flush = () => {
+      scheduled = false;
+      const batch = queue;
+      queue = [];
+      fetch(`${base}/message`, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(batch), keepalive: true }).catch(() => {
+      });
+    };
+    const relaySend = (message) => {
+      queue.push(message);
+      if (!scheduled) {
+        scheduled = true;
+        setTimeout(flush, 0);
+      }
+    };
+    try {
+      const stream = new ES(`${base}/events?role=app`);
+      stream.onmessage = (event) => {
+        let parsed;
+        try {
+          parsed = JSON.parse(event.data);
+        } catch {
+          return;
+        }
+        for (const m of Array.isArray(parsed) ? parsed : [parsed]) if (isCommand(m)) relaySend(runCommand(m));
+      };
+      stream.onerror = () => {
+      };
+      sinks.push(relaySend);
+    } catch {
+    }
+  }
+  const postAll = (type, payload) => {
+    post(type, payload);
+    if (sinks.length) {
+      const message = envelope(type, payload);
+      for (const sink of sinks) sink(message);
+    }
+  };
+  if (sinks.length) {
+    const replay = bridge.replay;
+    const clear = bridge.clear;
+    bridge.replay = () => {
+      for (const sink of sinks) {
+        sink(envelope("hello", info()));
+        for (const e of buffer) sink(envelope("report", e.payload));
+      }
+      replay();
+    };
+    bridge.clear = () => {
+      clear();
+      for (const sink of sinks) sink(envelope("clear"));
+    };
+  }
+  postAll("hello", info());
   return (report) => {
     const payload = serialize(report, maxDepth);
     buffer.push({ seq: ++seq, instanceId: report.instanceId, payload });
     if (buffer.length > bufferSize) buffer.splice(0, buffer.length - bufferSize);
-    post("report", payload);
+    postAll("report", payload);
     if (flashOn && report.avoidable && report.instanceId) {
       const fiber = fiberById(report.instanceId);
       if (fiber) flash({ nodes: hostNodesOf(fiber), label: report.component });
@@ -1149,31 +1761,48 @@ function createDevtoolsNotifier(options = {}) {
   };
 }
 
+exports.DEFAULT_CHANNEL = DEFAULT_CHANNEL;
 exports.DEVTOOLS_MARKER = DEVTOOLS_MARKER;
 exports.MARKER = MARKER;
 exports.PROTOCOL_VERSION = PROTOCOL_VERSION;
 exports.VERSION = VERSION;
+exports.assertWithinBudget = assertWithinBudget;
+exports.avoidableCounts = avoidableCounts;
 exports.buildReport = buildReport;
+exports.checkBudget = checkBudget;
 exports.classify = classify;
 exports.combineNotifiers = combineNotifiers;
+exports.compareSummaries = compareSummaries;
 exports.configure = configure;
 exports.createCollector = createCollector;
 exports.createDevtoolsNotifier = createDevtoolsNotifier;
+exports.customHooksFromStack = customHooksFromStack;
 exports.deepEqual = deepEqual;
 exports.deserializeOptions = deserializeOptions;
 exports.diffRecords = diffRecords;
 exports.disable = disable;
 exports.ensureDevtoolsHook = ensureDevtoolsHook;
+exports.fixKey = fixKey;
+exports.fixesFor = fixesFor;
+exports.formatComparison = formatComparison;
+exports.formatFixes = formatFixes;
 exports.getDisplayName = getDisplayName;
 exports.getRenderers = getRenderers;
+exports.hookLabel = hookLabel;
 exports.init = init;
 exports.isEnabled = isEnabled;
 exports.isProductionReact = isProductionReact;
+exports.parseExport = parseExport;
 exports.printReport = printReport;
+exports.rankFixes = rankFixes;
+exports.resolveHookNames = resolveHookNames;
 exports.serialize = serialize;
 exports.serializeOptions = serializeOptions;
 exports.shouldTrack = shouldTrack;
+exports.storeAdvice = storeAdvice;
 exports.summarize = summarize;
+exports.summarizeReports = summarizeReports;
+exports.toBudget = toBudget;
 exports.track = track;
 exports.useWhyRerender = useWhyRerender;
 //# sourceMappingURL=index.cjs.map