rerender-lens 0.4.0 → 0.7.0

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

@@ -0,0 +1,46 @@
+import { R as RenderReport, O as Options } from './types-DwNN5cWe.js';
+import { C as Collector } from './notifiers-CqQW0Eum.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/runner-report-CvpDg2zt.d.cts

@@ -0,0 +1,46 @@
+import { R as RenderReport, O as Options } from './types-DwNN5cWe.cjs';
+import { C as Collector } from './notifiers-B5poAEvE.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/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(", ");
 }
@@ -367,16 +383,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;
@@ -408,6 +435,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 +470,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 +770,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 +953,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 +988,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 +1024,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 +1056,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 +1096,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,17 +1123,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);
     }
@@ -1053,10 +1148,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 +1203,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,
@@ -1161,10 +1259,53 @@ function shouldTrack(type, o) {
   if (o.trackAllMemoized) return isMemo(type) || isPureClass(type);
   return false;
 }
+var ANONYMOUS = "Anonymous";
+function explainTracking(type, o) {
+  if (typeof type === "string")
+    return { tracked: false, name: type, memoized: false, reason: `<${type}> is a DOM element, not a React component; only components are tracked.` };
+  if (!isComponentLike(type))
+    return { tracked: false, name: ANONYMOUS, memoized: false, reason: "This is not a React component type, so it is never tracked." };
+  const name = getDisplayName(type);
+  const memo = isMemo(type);
+  const memoized = memo || isPureClass(type);
+  if (o.exclude?.some((m) => matches(m, name)))
+    return { tracked: false, name, memoized, reason: `<${name}> matches "exclude", which wins over every other rule.`, fix: `Remove "${name}" from the exclude list.` };
+  if (hasMarker(type)) return { tracked: true, name, memoized, reason: `<${name}> is marked with track() (the ${MARKER} static).` };
+  if (o.include?.some((m) => matches(m, name))) return { tracked: true, name, memoized, reason: `<${name}> matches "include".` };
+  if (o.trackAllComponents) return { tracked: true, name, memoized, reason: '"Track every component" is on, so every component is tracked.' };
+  if (o.trackAllMemoized && memoized)
+    return { tracked: true, name, memoized, reason: `<${name}> is ${memo ? "a React.memo component" : "a PureComponent"}, and "Track every React.memo and PureComponent" is on.` };
+  if (name === ANONYMOUS)
+    return {
+      tracked: false,
+      name,
+      memoized,
+      reason: 'This component has no display name, so "include" and "exclude" cannot address it.',
+      fix: "Give the function a name, set displayName, or mark it with track(fn, 'Name')."
+    };
+  if (o.trackAllMemoized)
+    return {
+      tracked: false,
+      name,
+      memoized,
+      reason: `"Track every React.memo and PureComponent" only covers React.memo components and PureComponent classes, and <${name}> is neither.`,
+      fix: `Add "${name}" to include, wrap it in React.memo, or turn on "Track every component".`
+    };
+  return {
+    tracked: false,
+    name,
+    memoized,
+    reason: `Nothing selects <${name}>: it is not marked with track(), no "include" pattern matches it, and neither "track every" option is on.`,
+    fix: `Add "${name}" to include, or turn on "Track every React.memo and PureComponent" / "Track every component".`
+  };
+}
 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;
@@ -1290,7 +1431,7 @@ function flash(target, duration = 500) {
 }
 
 // src/version.ts
-var VERSION = "0.4.0" ;
+var VERSION = "0.7.0" ;
 
 // src/devtools.ts
 var DEVTOOLS_MARKER = "__rerenderLens";
@@ -1416,6 +1557,18 @@ function createDevtoolsNotifier(options = {}) {
     target.postMessage(msg, "*");
   };
   const source = options.source ?? "page";
+  const trackingSummary = () => {
+    const s = getState();
+    const o = s.options;
+    return {
+      mode: o.trackAllComponents ? "all" : o.trackAllMemoized ? "memoized" : "marked",
+      include: (o.include ?? []).map(matcherToString).filter((x) => x !== null),
+      exclude: (o.exclude ?? []).map(matcherToString).filter((x) => x !== null),
+      renderedCount: s.seen.size,
+      trackedCount: s.seenTracked.size,
+      overflow: s.seenOverflow
+    };
+  };
   const info = () => ({
     count: buffer.length,
     library: VERSION,
@@ -1429,7 +1582,8 @@ function createDevtoolsNotifier(options = {}) {
     scheduled: getState().scheduled,
     commits: getState().commits,
     overhead: { totalMs: getState().overheadMs, maxCommitMs: getState().maxCommitMs },
-    truncated: getState().truncated
+    truncated: getState().truncated,
+    tracking: trackingSummary()
   });
   const bridge = {
     replay: () => {
@@ -1475,6 +1629,10 @@ function createDevtoolsNotifier(options = {}) {
     flashAvoidable: (on) => {
       flashOn = !!on;
     },
+    explain: (target2) => {
+      const comp = typeof target2 === "number" ? fiberById(target2) : nearestComponent(fiberForNode(target2));
+      return comp ? explainTracking(fiberType(comp), getState().options) : null;
+    },
     inspect: (node) => {
       const comp = nearestComponent(fiberForNode(node));
       if (!comp) return null;
@@ -1489,6 +1647,7 @@ function createDevtoolsNotifier(options = {}) {
         component: fiberName(comp),
         instanceId: id,
         tracked: shouldTrack(fiberType(comp), getState().options),
+        tracking: explainTracking(fiberType(comp), getState().options),
         path,
         reports: id === null ? [] : buffer.filter((e) => e.instanceId === id).slice(-20).map((e) => e.payload)
       };
@@ -1523,6 +1682,9 @@ function createDevtoolsNotifier(options = {}) {
           bridge.flashAvoidable(!!data.arg);
           reply.result = true;
           break;
+        case "explain":
+          reply.result = bridge.explain(data.arg);
+          break;
         default:
           reply.error = `unknown command ${String(data.cmd)}`;
       }
@@ -1531,6 +1693,7 @@ function createDevtoolsNotifier(options = {}) {
     }
     return reply;
   };
+  const isRelayGreeting = (data) => !!data && typeof data === "object" && data.__rerenderLensRelay === true && typeof data.app === "string";
   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 = [];
@@ -1553,14 +1716,20 @@ function createDevtoolsNotifier(options = {}) {
   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(/\/$/, "");
+    const [rawBase, relayQuery = ""] = relayUrl.split("?");
+    const base = (rawBase ?? "").replace(/\/$/, "");
+    const relayToken = new URLSearchParams(relayQuery).get("token");
+    const auth = relayToken ? `token=${encodeURIComponent(relayToken)}` : "";
     let queue = [];
     let scheduled = false;
+    let appId = null;
     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 params = [appId ? `app=${encodeURIComponent(appId)}` : "", auth].filter(Boolean).join("&");
+      const to = `${base}/message${params ? `?${params}` : ""}`;
+      fetch(to, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(batch), keepalive: true }).catch(() => {
       });
     };
     const relaySend = (message) => {
@@ -1571,7 +1740,8 @@ function createDevtoolsNotifier(options = {}) {
       }
     };
     try {
-      const stream = new ES(`${base}/events?role=app`);
+      const label = typeof location !== "undefined" ? `${location.host}${location.pathname}`.slice(0, 120) : "";
+      const stream = new ES(`${base}/events?role=app${label ? `&label=${encodeURIComponent(label)}` : ""}${auth ? `&${auth}` : ""}`);
       stream.onmessage = (event) => {
         let parsed;
         try {
@@ -1579,7 +1749,10 @@ function createDevtoolsNotifier(options = {}) {
         } catch {
           return;
         }
-        for (const m of Array.isArray(parsed) ? parsed : [parsed]) if (isCommand(m)) relaySend(runCommand(m));
+        for (const m of Array.isArray(parsed) ? parsed : [parsed]) {
+          if (isRelayGreeting(m)) appId = m.app;
+          else if (isCommand(m)) relaySend(runCommand(m));
+        }
       };
       stream.onerror = () => {
       };
@@ -1623,15 +1796,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