rerender-lens 0.4.0 → 0.7.0

package/dist/cli.cjs

@@ -5,55 +5,212 @@ var fs = require('fs');
 var http = require('http');
 var path = require('path');
 var url = require('url');
+var crypto = require('crypto');
 
 // node_modules/tsup/assets/cjs_shims.js
 var getImportMetaUrl = () => typeof document === "undefined" ? new URL(`file:${__filename}`).href : document.currentScript && document.currentScript.tagName.toUpperCase() === "SCRIPT" ? document.currentScript.src : new URL("main.js", document.baseURI).href;
 var importMetaUrl = /* @__PURE__ */ getImportMetaUrl();
 
-// src/report.ts
-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";
+// src/diff.ts
+var AVOIDABLE_KINDS = /* @__PURE__ */ new Set(["deep-equal", "function", "element"]);
+
+// src/causes.ts
+var isAncestorReport = (anc, r) => anc.path.length < r.path.length && r.path[anc.path.length] === anc.component && anc.path.every((p, i) => r.path[i] === p);
+var bump = (m, key, n = 1) => void m.set(key, (m.get(key) || 0) + n);
+function indexByComponent(reports) {
+  const index = /* @__PURE__ */ new Map();
+  for (const r of reports) {
+    const list = index.get(r.component);
+    if (list) list.push(r);
+    else index.set(r.component, [r]);
+  }
+  return index;
+}
+function rootCauseOf(r, commitReports, index = indexByComponent(commitReports)) {
+  let cur = r;
+  const seen = /* @__PURE__ */ new Set([r]);
+  while (cur.trigger === "parent" && cur.parent) {
+    const parent = cur.parent;
+    const candidates = index.get(parent.name);
+    const p = candidates && candidates.find((x) => isAncestorReport(x, cur));
+    if (!p || seen.has(p)) return { name: parent.name, trigger: parent.trigger, report: null };
+    seen.add(p);
+    cur = p;
+  }
+  return cur === r ? null : { name: cur.component, trigger: cur.trigger, report: cur };
+}
+function rootCausesOf(reports) {
+  const roots = /* @__PURE__ */ new Map();
+  const rootByReport = /* @__PURE__ */ new Map();
+  const index = indexByComponent(reports);
+  let avoidable = 0;
+  let wasted = 0;
+  for (const r of reports) {
+    if (!r.avoidable) continue;
+    avoidable++;
+    if (typeof r.selfDuration === "number") wasted += r.selfDuration;
+    const root = rootCauseOf(r, reports, index);
+    const name = root ? root.name : r.parent && r.parent.name || "(unknown)";
+    const trigger = root ? root.trigger : r.parent && r.parent.trigger || "parent";
+    rootByReport.set(r, name);
+    let agg = roots.get(name);
+    if (!agg) {
+      agg = { name, trigger, count: 0, components: /* @__PURE__ */ new Map() };
+      roots.set(name, agg);
+    }
+    agg.count++;
+    bump(agg.components, r.component);
+  }
+  return { roots: [...roots.values()].sort((a, b) => b.count - a.count), rootByReport, avoidable, wasted };
+}
+function groupByCommit(reports) {
+  const out = /* @__PURE__ */ new Map();
+  for (const r of reports) {
+    if (typeof r.commitId !== "number" || r.commitId <= 0) continue;
+    const list = out.get(r.commitId);
+    if (list) list.push(r);
+    else out.set(r.commitId, [r]);
+  }
+  return out;
+}
+function rankRootCauses(reports) {
+  const byName = /* @__PURE__ */ new Map();
+  for (const commit of groupByCommit(reports).values()) {
+    for (const root of rootCausesOf(commit).roots) {
+      let agg = byName.get(root.name);
+      if (!agg) {
+        agg = { name: root.name, trigger: root.trigger, commits: 0, count: 0, components: /* @__PURE__ */ new Map() };
+        byName.set(root.name, agg);
+      }
+      agg.commits++;
+      agg.count += root.count;
+      for (const [c, n] of root.components) bump(agg.components, c, n);
+    }
+  }
+  return [...byName.values()].sort((a, b) => b.count - a.count || b.commits - a.commits || a.name.localeCompare(b.name));
+}
+var plural = (n, word) => `${n} ${word}${n === 1 ? "" : "s"}`;
+function formatRootCauses(reports, limit = 5) {
+  const ranked = rankRootCauses(reports);
+  const lines = ranked.slice(0, limit).map((root, i) => `${String(i + 1).padStart(2)}. <${root.name}> (${root.trigger}) started ${plural(root.commits, "commit")}, ${plural(root.count, "avoidable re-render")}  (${[...root.components].map(([c, n]) => `<${c}>${n > 1 ? " x" + n : ""}`).join(", ")})`);
+  if (ranked.length > limit) lines.push(`    \u2026 ${ranked.length - limit} more`);
+  return lines.join("\n");
 }
 
 // src/fixes.ts
-var AVOIDABLE = /* @__PURE__ */ new Set(["deep-equal", "function", "element"]);
+var MAX_FIX_REPORTS = 50;
 var rootOf = (path) => path.split(/[.[]/)[0] || path;
+var identifier = (name) => /^[A-Za-z_$][\w$]*$/.test(name) ? name : "value";
+function shortValue(v, max = 60) {
+  let s;
+  try {
+    s = JSON.stringify(v);
+  } catch {
+    s = String(v);
+  }
+  if (s === void 0) s = String(v);
+  return s.length > max ? s.slice(0, max - 3) + "..." : s;
+}
 function fixesFor(r) {
   const out = [];
-  const owner = r.owner || r.parent && r.parent.name || "?";
-  const changes = [...r.propChanges, ...r.stateChanges, ...r.hookChanges];
+  const ownerName = r.owner || r.parent && r.parent.name || null;
+  const propChanges = r.propChanges || [];
+  const changes = [...propChanges, ...r.stateChanges || [], ...r.hookChanges || []];
   if (r.avoidable && (changes.length === 0 || r.memoized === false)) {
+    const identical = changes.length === 0;
     out.push({
       kind: "memo",
       owner: r.component,
       target: r.component,
       prop: null,
       label: `Wrap <${r.component}> in React.memo`,
-      detail: changes.length === 0 ? `<${r.component}> re-rendered with identical props because <${r.parent && r.parent.name || "its parent"}> re-rendered.` : `<${r.component}> is not memoized: fixing its props alone will not stop the re-render.`
+      detail: identical ? `<${r.component}> re-rendered with identical props because <${r.parent && r.parent.name || "its parent"}> re-rendered.` : `<${r.component}> is not memoized: fixing its props alone will not stop the re-render.`,
+      snippet: `// ${r.component}
+import { memo } from 'react';
+
+export const ${r.component} = memo(function ${r.component}(props) {
+  // ...
+});
+// class components: extend PureComponent instead`
     });
   }
-  for (const c of r.propChanges) {
-    if (!AVOIDABLE.has(c.kind)) continue;
+  for (const c of propChanges) {
+    if (!AVOIDABLE_KINDS.has(c.kind)) continue;
+    const owner = ownerName || "?";
     const root = rootOf(c.path);
+    const id = identifier(root);
     if (root === "children" && (c.kind === "element" || c.kind === "deep-equal")) {
-      out.push({ kind: "children", owner, target: r.component, prop: "children", label: `memoize children of <${r.component}> in <${owner}>`, detail: `<${owner}> re-creates the children of <${r.component}> on every render.` });
+      out.push({
+        kind: "children",
+        owner,
+        target: r.component,
+        prop: "children",
+        label: `memoize children of <${r.component}> in <${owner}>`,
+        detail: `<${owner}> re-creates the children of <${r.component}> on every render; they have the same types and props each time.`,
+        snippet: `// ${owner}
+import { useMemo } from 'react';
+
+const children = useMemo(() => (
+  <>{/* the same elements */}</>
+), [/* deps */]);
+
+<${r.component}>{children}</${r.component}>
+
+// static children: hoist them to module scope
+const STATIC = <em>hi</em>;`
+      });
     } else if (c.kind === "function") {
-      out.push({ kind: "useCallback", owner, target: r.component, prop: root, label: `useCallback(${root}) in <${owner}>`, detail: `prop "${c.path}" of <${r.component}> is a new function on every render of <${owner}>.` });
+      out.push({
+        kind: "useCallback",
+        owner,
+        target: r.component,
+        prop: root,
+        label: `useCallback(${root}) in <${owner}>`,
+        detail: `prop "${c.path}" of <${r.component}> is a new function on every render of <${owner}>.`,
+        snippet: `// ${owner}
+import { useCallback } from 'react';
+
+const ${id} = useCallback((/* args */) => {
+  // ...
+}, [/* deps */]);
+
+<${r.component} ${root}={${id}} />`
+      });
     } else if (c.kind === "element") {
-      out.push({ kind: "useMemoElement", owner, target: r.component, prop: root, label: `memoize element prop ${root} in <${owner}>`, detail: `prop "${c.path}" of <${r.component}> is a new element with the same type and props on every render of <${owner}>.` });
+      out.push({
+        kind: "useMemoElement",
+        owner,
+        target: r.component,
+        prop: root,
+        label: `memoize element prop ${root} in <${owner}>`,
+        detail: `prop "${c.path}" of <${r.component}> is a new element with the same type and props on every render of <${owner}>.`,
+        snippet: `// ${owner}
+import { useMemo } from 'react';
+
+const ${id} = useMemo(() => ${shortValue(c.next, 40)}, [/* deps */]);
+// or pass it as children from a component that does not re-render`
+      });
     } else {
-      out.push({ kind: "useMemo", owner, target: r.component, prop: root, label: `useMemo(${root}) in <${owner}>`, detail: `prop "${c.path}" of <${r.component}> is a new ${Array.isArray(c.next) ? "array" : "object"} with the same contents on every render of <${owner}>.` });
+      const isArray = Array.isArray(c.next);
+      out.push({
+        kind: "useMemo",
+        owner,
+        target: r.component,
+        prop: root,
+        label: `useMemo(${root}) in <${owner}>`,
+        detail: `prop "${c.path}" of <${r.component}> is a new ${isArray ? "array" : "object"} with the same contents on every render of <${owner}>.`,
+        snippet: `// ${owner}
+import { useMemo } from 'react';
+
+const ${id} = useMemo(() => (${shortValue(c.next, 80)}), [/* deps */]);
+
+// or, when it never changes, hoist it to module scope:
+const ${id.toUpperCase()} = ${shortValue(c.next, 80)};`
+      });
     }
   }
-  for (const c of [...r.stateChanges, ...r.hookChanges]) {
-    const isContext = c.hook === "useContext";
+  for (const c of [...r.stateChanges || [], ...r.hookChanges || []]) {
+    const isContext = c.hook === "useContext" || /^useContext/.test(c.path);
     const ctxName = isContext ? (/useContext\((.*)\)/.exec(c.path) || [])[1] || "Context" : "";
     const providerOwner = isContext && c.provider && c.provider.component ? c.provider.component : null;
     if (isContext && c.kind === "different" && c.changedKeys && typeof c.totalKeys === "number" && c.changedKeys.length > 0 && c.changedKeys.length < c.totalKeys) {
@@ -63,20 +220,63 @@ function fixesFor(r) {
         target: r.component,
         prop: ctxName,
         label: `split ${ctxName}${providerOwner ? ` in <${providerOwner}>` : ""}: only ${c.changedKeys.join(", ")} changed`,
-        detail: `${c.changedKeys.length} of ${c.totalKeys} keys changed in ${ctxName}, yet every consumer re-rendered.`
+        detail: `${c.changedKeys.map((k) => `"${k}"`).join(", ")} of ${c.totalKeys} keys changed in ${ctxName}, yet every consumer (like <${r.component}>) re-rendered. Consumers that read the other keys re-render for nothing.`,
+        snippet: `// ${providerOwner || "Provider"}
+// one context per independently-changing slice
+const ${identifier(ctxName)}Static = createContext(...);
+const ${identifier(ctxName)}${c.changedKeys.map((k) => k[0].toUpperCase() + k.slice(1)).join("")} = createContext(...);
+
+// or keep one context and let consumers select a slice:
+const ${c.changedKeys[0]} = useContextSelector(${ctxName}, (v) => v.${c.changedKeys[0]});`
       });
       continue;
     }
-    if (!AVOIDABLE.has(c.kind)) continue;
+    if (!AVOIDABLE_KINDS.has(c.kind)) continue;
     if (isContext) {
-      out.push({ kind: "contextValue", owner: providerOwner || `${ctxName}.Provider`, target: r.component, prop: ctxName, label: `memoize the ${ctxName} provider value${providerOwner ? ` in <${providerOwner}>` : ""}`, detail: `${ctxName} produced a new value that is deep-equal to the previous one.` });
+      out.push({
+        kind: "contextValue",
+        owner: providerOwner || `${ctxName}.Provider`,
+        target: r.component,
+        prop: ctxName,
+        label: `memoize the ${ctxName} provider value${providerOwner ? ` in <${providerOwner}>` : ""}`,
+        detail: `<${r.component}> re-rendered because ${ctxName} produced a new value that is deep-equal to the previous one${providerOwner ? ` (Provider rendered by <${providerOwner}>)` : ""}.`,
+        snippet: `// ${providerOwner || `where <${ctxName}.Provider> is rendered`}
+const value = useMemo(() => ({ /* ... */ }), [/* deps */]);
+<${ctxName}.Provider value={value}>`
+      });
     } else if (c.hook === "useSyncExternalStore") {
       const chain = c.custom || [];
       const redux = chain.some((n) => /^use(App)?Selector$/.test(n));
       const zustand = !redux && chain.some((n) => /^use[A-Z]\w*Store$/.test(n) || n === "useStore" || n === "useBoundStore");
-      out.push({ kind: "storeSnapshot", owner: r.component, target: r.component, prop: c.path, label: redux ? `memoize the selector in <${r.component}>` : zustand ? `useShallow in <${r.component}>` : `stable getSnapshot in <${r.component}>`, detail: storeAdvice(c.custom) });
+      const via = chain.length ? ` via ${chain.join(" \u203A ")}` : "";
+      out.push({
+        kind: "storeSnapshot",
+        owner: r.component,
+        target: r.component,
+        prop: c.path,
+        label: redux ? `memoize the selector in <${r.component}>` : zustand ? `useShallow in <${r.component}>` : `stable getSnapshot in <${r.component}>`,
+        detail: redux ? `the selector${via} returns a new object on every call, so the component re-renders on every store change.` : zustand ? `the store selector${via} returns a new object on every call, so the component re-renders on every store change.` : `${c.path}${via} returned a new reference with the same contents; getSnapshot must return a cached value.`,
+        snippet: redux ? `// ${r.component}
+import { shallowEqual } from 'react-redux';
+const slice = useSelector(selectSlice, shallowEqual);
+// or memoize: const selectSlice = createSelector([selectA, selectB], (a, b) => ({ a, b }));` : zustand ? `// ${r.component}
+import { useShallow } from 'zustand/react/shallow';
+const { a, b } = useStore(useShallow((s) => ({ a: s.a, b: s.b })));
+// or select a primitive: const a = useStore((s) => s.a);` : `// ${r.component}
+// getSnapshot must return the same reference while the data is unchanged
+const snapshot = useSyncExternalStore(subscribe, store.getSnapshot /* cached */);`
+      });
     } else {
-      out.push({ kind: "bailout", owner: r.component, target: r.component, prop: c.path, label: `bail out before setting ${c.path} in <${r.component}>`, detail: `${c.path} was set to a value deep-equal to the current one (new reference).` });
+      out.push({
+        kind: "bailout",
+        owner: r.component,
+        target: r.component,
+        prop: c.path,
+        label: `bail out before setting ${c.path} in <${r.component}>`,
+        detail: `${c.path} was set to a value deep-equal to the current one (new reference).`,
+        snippet: `// ${r.component}
+setState((prev) => (deepEqual(prev, next) ? prev : next));`
+      });
     }
   }
   return out;
@@ -90,11 +290,12 @@ function rankFixes(reports) {
       const key = fixKey(f);
       let agg = byKey.get(key);
       if (!agg) {
-        agg = { ...f, key, count: 0, components: {} };
+        agg = { ...f, key, count: 0, components: {}, reports: [] };
         byKey.set(key, agg);
       }
       agg.count++;
       agg.components[r.component] = (agg.components[r.component] || 0) + 1;
+      if (agg.reports.length < MAX_FIX_REPORTS) agg.reports.push(r);
     }
   }
   return [...byKey.values()].sort((a, b) => b.count - a.count || a.label.localeCompare(b.label));
@@ -104,6 +305,8 @@ function formatFixes(reports, limit = 10) {
   if (!ranked.length) return "No avoidable re-renders.";
   const lines = ranked.slice(0, limit).map((f, i) => `${String(i + 1).padStart(2)}. ${f.label}  (removes ${f.count}: ${Object.entries(f.components).map(([c, n]) => `<${c}>${n > 1 ? " x" + n : ""}`).join(", ")})`);
   if (ranked.length > limit) lines.push(`    \u2026 ${ranked.length - limit} more`);
+  const roots = formatRootCauses(reports, 5);
+  if (roots) lines.push("", "Root causes:", roots);
   return lines.join("\n");
 }
 
@@ -206,6 +409,8 @@ function checkBudget(reports, budget) {
 function toBudget(reports) {
   return { "*": 0, ...avoidableCounts(reports) };
 }
+var MARKER = "__rerenderLens";
+var PROTOCOL = 2;
 var MIME = { ".html": "text/html; charset=utf-8", ".js": "text/javascript; charset=utf-8", ".css": "text/css; charset=utf-8" };
 function findPanelDir() {
   const here = path.dirname(url.fileURLToPath(importMetaUrl));
@@ -240,26 +445,55 @@ function createRelayServer(options = {}) {
   const host = options.host ?? "127.0.0.1";
   const panelDir = options.panelDir === void 0 ? findPanelDir() : options.panelDir;
   const keepAliveMs = options.keepAliveMs ?? 15e3;
-  const apps = /* @__PURE__ */ new Set();
+  const token = options.token || null;
+  const apps = /* @__PURE__ */ new Map();
   const panels = /* @__PURE__ */ new Set();
   let url = "";
-  const send = (targets, message) => {
-    const line = `data: ${JSON.stringify(message)}
+  let nextAppId = 1;
+  const connectUrl = () => token ? `${url}?token=${encodeURIComponent(token)}` : url;
+  const line = (message) => `data: ${JSON.stringify(message)}
 
 `;
-    for (const res of targets) {
+  const sendTo = (res, message) => {
+    try {
+      res.write(line(message));
+    } catch {
+      apps.delete(res);
+      panels.delete(res);
+    }
+  };
+  const send = (targets, message) => {
+    const text = line(message);
+    for (const res of [...targets]) {
       try {
-        res.write(line);
+        res.write(text);
       } catch {
-        targets.delete(res);
+        apps.delete(res);
+        panels.delete(res);
       }
     }
   };
-  const route = (message) => {
+  const appList = () => [...apps.values()];
+  const roster = () => ({ [MARKER]: true, version: PROTOCOL, type: "relay", payload: { apps: apps.size, list: appList() } });
+  const streamOf = (id) => {
+    for (const [res, app] of apps) if (app.id === id) return res;
+    return null;
+  };
+  const route = (message, from) => {
     if (!message || typeof message !== "object") return;
     const m = message;
-    if (m.__rerenderLensCmd === true) send(apps, m);
-    else if (m.__rerenderLens === true || m.__rerenderLensReply === true) send(panels, m);
+    if (m.__rerenderLensCmd === true) {
+      const target = typeof m.app === "string" ? streamOf(m.app) : null;
+      if (target) sendTo(target, m);
+      else send(apps.keys(), m);
+    } else if (m.__rerenderLens === true || m.__rerenderLensReply === true) {
+      send(panels, from ? { ...m, app: from.id } : m);
+    }
+  };
+  const authorized = (req, u) => {
+    if (!token) return true;
+    const given = u.searchParams.get("token") || (typeof req.headers["x-rerender-lens-token"] === "string" ? req.headers["x-rerender-lens-token"] : "");
+    return given === token;
   };
   const server = http.createServer(async (req, res) => {
     cors(res);
@@ -271,18 +505,26 @@ function createRelayServer(options = {}) {
     }
     if (u.pathname === "/" && req.method === "GET") {
       res.statusCode = 302;
-      res.setHeader("Location", `/panel.html?relay=${encodeURIComponent(url)}`);
+      res.setHeader("Location", `/panel.html?relay=${encodeURIComponent(connectUrl())}`);
       res.end();
       return;
     }
+    if (/^\/(events|message|status)$/.test(u.pathname) && !authorized(req, u)) {
+      res.statusCode = 401;
+      res.setHeader("Content-Type", "text/plain");
+      res.end("rerender-lens relay: this relay needs the token from the URL it printed (?token=...)");
+      return;
+    }
     if (u.pathname === "/events" && req.method === "GET") {
-      const role = u.searchParams.get("role") === "app" ? apps : panels;
+      const isApp = u.searchParams.get("role") === "app";
       res.statusCode = 200;
       res.setHeader("Content-Type", "text/event-stream");
       res.setHeader("Cache-Control", "no-store");
       res.setHeader("Connection", "keep-alive");
       res.write(": connected\n\n");
-      role.add(res);
+      const app = isApp ? { id: `a${nextAppId++}`, label: (u.searchParams.get("label") || req.headers.origin || "").slice(0, 120) || `app ${nextAppId - 1}` } : null;
+      if (app) apps.set(res, app);
+      else panels.add(res);
       const ping = setInterval(() => {
         try {
           res.write(": ping\n\n");
@@ -291,18 +533,29 @@ function createRelayServer(options = {}) {
       }, keepAliveMs);
       req.on("close", () => {
         clearInterval(ping);
-        role.delete(res);
+        apps.delete(res);
+        panels.delete(res);
       });
-      if (role === apps) {
-        send(panels, { __rerenderLens: true, version: 2, type: "relay", payload: { apps: apps.size } });
-        req.on("close", () => send(panels, { __rerenderLens: true, version: 2, type: "relay", payload: { apps: apps.size } }));
+      if (app) {
+        sendTo(res, { __rerenderLensRelay: true, version: PROTOCOL, app: app.id });
+        send(panels, roster());
+        req.on("close", () => send(panels, roster()));
+      } else {
+        sendTo(res, roster());
       }
       return;
     }
+    if (u.pathname === "/favicon.ico") {
+      res.statusCode = 204;
+      res.end();
+      return;
+    }
     if (u.pathname === "/message" && req.method === "POST") {
       try {
         const parsed = JSON.parse(await readBody(req) || "null");
-        for (const m of Array.isArray(parsed) ? parsed : [parsed]) route(m);
+        const sender = u.searchParams.get("app");
+        const from = sender ? appList().find((a) => a.id === sender) ?? void 0 : void 0;
+        for (const m of Array.isArray(parsed) ? parsed : [parsed]) route(m, from);
         res.statusCode = 204;
         res.end();
       } catch (e) {
@@ -315,7 +568,7 @@ function createRelayServer(options = {}) {
     if (u.pathname === "/status" && req.method === "GET") {
       res.statusCode = 200;
       res.setHeader("Content-Type", "application/json");
-      res.end(JSON.stringify({ ok: true, apps: apps.size, panels: panels.size }));
+      res.end(JSON.stringify({ ok: true, apps: apps.size, panels: panels.size, list: appList() }));
       return;
     }
     const file = u.pathname.replace(/^\//, "");
@@ -345,10 +598,12 @@ function createRelayServer(options = {}) {
       resolve({
         server,
         url,
+        connectUrl: connectUrl(),
         port,
         counts: () => ({ apps: apps.size, panels: panels.size }),
+        appList,
         close: () => new Promise((done) => {
-          for (const res of [...apps, ...panels]) res.end();
+          for (const res of [...apps.keys(), ...panels]) res.end();
           apps.clear();
           panels.clear();
           server.close(() => done());
@@ -357,8 +612,6 @@ function createRelayServer(options = {}) {
     });
   });
 }
-
-// src/cli.ts
 var read = (file) => JSON.parse(fs.readFileSync(file, "utf8"));
 function summaryOf(file) {
   const parsed = parseExport(read(file));
@@ -366,14 +619,20 @@ function summaryOf(file) {
   if (parsed.sessions.length && !parsed.reports.length) return parsed.sessions[parsed.sessions.length - 1];
   return summarizeReports(parsed.reports, { name: file.replace(/^.*[\\/]/, "").replace(/\.json$/, "") });
 }
+var isLoopback = (host) => host === "127.0.0.1" || host === "localhost" || host === "::1";
 async function panelCommand(args) {
   const flag = (name) => {
     const i = args.indexOf(name);
     return i >= 0 ? args[i + 1] ?? "" : null;
   };
-  const relay = await createRelayServer({ port: Number(flag("--port") || 4141), host: flag("--host") || "127.0.0.1" });
-  console.log(`rerender-lens panel: ${relay.url}/`);
-  console.log(`in the app: createDevtoolsNotifier({ relay: '${relay.url}' })  or  window.__RERENDER_LENS_RELAY__ = '${relay.url}'`);
+  const host = flag("--host") || "127.0.0.1";
+  const given = flag("--token");
+  const token = args.includes("--no-token") ? null : given || (isLoopback(host) ? null : randomToken());
+  const relay = await createRelayServer({ port: Number(flag("--port") || 4141), host, token: token ?? void 0 });
+  console.log(`rerender-lens panel: ${relay.connectUrl}/`);
+  console.log(`in the app: createDevtoolsNotifier({ relay: '${relay.connectUrl}' })  or  window.__RERENDER_LENS_RELAY__ = '${relay.connectUrl}'`);
+  if (token) console.log("The token in that URL is required: reports carry your app's prop, state and context values.");
+  else if (!isLoopback(host)) console.log(`WARNING: ${host} is reachable by other machines and --no-token was given: anyone who can reach this port can read every report.`);
   console.log("Ctrl+C to stop.");
   return new Promise((resolve) => {
     const stop = () => void relay.close().then(() => resolve(0));
@@ -382,6 +641,9 @@ async function panelCommand(args) {
     relay.server.once("close", () => resolve(0));
   });
 }
+function randomToken() {
+  return crypto.randomBytes(16).toString("base64url");
+}
 function main(argv) {
   const [cmd, ...args] = argv;
   if (cmd === "panel") return panelCommand(args).catch((e) => (console.error(e.message), 1));
@@ -399,6 +661,13 @@ function main(argv) {
         console.log(formatFixes(reports, Number(flag("--limit") || 20)));
         return 0;
       }
+      case "causes": {
+        const file = positional[0];
+        if (!file) throw new Error("usage: rerender-lens causes <export.json> [--limit N]");
+        const { reports } = parseExport(read(file));
+        console.log(formatRootCauses(reports, Number(flag("--limit") || 10)) || "No root causes: no avoidable re-renders, or the reports carry no commit ids.");
+        return 0;
+      }
       case "summary": {
         const file = positional[0];
         if (!file) throw new Error("usage: rerender-lens summary <export.json> [--out summary.json]");
@@ -442,7 +711,7 @@ ${cmp.regressions.length} component${cmp.regressions.length === 1 ? "" : "s"} re
         return 1;
       }
       default:
-        console.error("usage: rerender-lens <panel|fixes|summary|compare|budget> ...");
+        console.error("usage: rerender-lens <panel|fixes|causes|summary|compare|budget> ...");
         return cmd ? 1 : 0;
     }
   } catch (e) {