@0x1f320.sh/why-did-you-render-mcp 1.0.0-dev.1 → 1.0.0-dev.10

package/README.md

@@ -1,5 +1,9 @@
 # why-did-you-render-mcp
 
+[![npm version](https://img.shields.io/npm/v/@0x1f320.sh/why-did-you-render-mcp.svg?style=flat&colorA=000000&colorB=000000)](https://www.npmjs.com/package/@0x1f320.sh/why-did-you-render-mcp)
+[![CI](https://img.shields.io/github/actions/workflow/status/0x1f320/why-did-you-render-mcp/ci.yml?style=flat&colorA=000000&colorB=000000)](https://github.com/0x1f320/why-did-you-render-mcp/actions/workflows/ci.yml)
+[![license](https://img.shields.io/npm/l/@0x1f320.sh/why-did-you-render-mcp?style=flat&colorA=000000&colorB=000000)](https://www.npmjs.com/package/@0x1f320.sh/why-did-you-render-mcp)
+
 An [MCP](https://modelcontextprotocol.io/) server that bridges [why-did-you-render](https://github.com/welldone-software/why-did-you-render) data from the browser to coding agents. It captures unnecessary React re-render reports in real time and exposes them as MCP tools, so agents can diagnose and fix performance issues without manual browser inspection.
 
 ## How It Works
@@ -39,10 +43,8 @@ import whyDidYouRender from "@welldone-software/why-did-you-render";
 import { buildOptions } from "@0x1f320.sh/why-did-you-render-mcp/client";
 
 if (process.env.NODE_ENV === "development") {
-  const { notifier } = buildOptions();
-
   whyDidYouRender(React, {
-    notifier,
+    ...buildOptions(),
     trackAllPureComponents: true,
   });
 }
@@ -59,31 +61,99 @@ const { notifier } = buildOptions({
 
 ### 2. Add the MCP server to your agent
 
-Add the server to your MCP client configuration. For example, in Claude Desktop's `claude_desktop_config.json`:
+<details>
+<summary>Claude Code</summary>
+
+```sh
+claude mcp add why-did-you-render -- npx -y @0x1f320.sh/why-did-you-render-mcp
+```
+
+</details>
+
+<details>
+<summary>Claude Desktop</summary>
+
+```sh
+claude mcp add-json why-did-you-render '{"command":"npx","args":["-y","@0x1f320.sh/why-did-you-render-mcp"]}' -s user
+```
+
+Or manually edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) / `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
 
 ```json
 {
   "mcpServers": {
     "why-did-you-render": {
       "command": "npx",
-      "args": ["@0x1f320.sh/why-did-you-render-mcp"]
+      "args": ["-y", "@0x1f320.sh/why-did-you-render-mcp"]
     }
   }
 }
 ```
 
-Or if you installed it globally:
+</details>
+
+<details>
+<summary>Cursor</summary>
+
+```sh
+cursor --add-mcp '{"name":"why-did-you-render","command":"npx","args":["-y","@0x1f320.sh/why-did-you-render-mcp"]}'
+```
+
+Or add to `.cursor/mcp.json` in your project:
 
 ```json
 {
   "mcpServers": {
     "why-did-you-render": {
-      "command": "why-did-you-render-mcp"
+      "command": "npx",
+      "args": ["-y", "@0x1f320.sh/why-did-you-render-mcp"]
     }
   }
 }
 ```
 
+</details>
+
+<details>
+<summary>Windsurf</summary>
+
+Add to `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "why-did-you-render": {
+      "command": "npx",
+      "args": ["-y", "@0x1f320.sh/why-did-you-render-mcp"]
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary>VS Code (GitHub Copilot)</summary>
+
+```sh
+code --add-mcp '{"name":"why-did-you-render","command":"npx","args":["-y","@0x1f320.sh/why-did-you-render-mcp"]}'
+```
+
+Or add to `.vscode/mcp.json` in your project:
+
+```json
+{
+  "servers": {
+    "why-did-you-render": {
+      "command": "npx",
+      "args": ["-y", "@0x1f320.sh/why-did-you-render-mcp"]
+    }
+  }
+}
+```
+
+</details>
+
 ### 3. Start your dev server and interact with the app
 
 Once both the MCP server and your React dev server are running, interact with your app in the browser. The agent can now query re-render data using the MCP tools below.
@@ -94,11 +164,20 @@ Once both the MCP server and your React dev server are running, interact with yo
 | --- | --- |
 | `get_unnecessary_renders` | Returns all captured unnecessary re-renders. Optionally filter by `component` name. |
 | `get_render_summary` | Returns a summary of re-renders grouped by component with counts. |
+| `get_commits` | Lists React commit IDs that have recorded render data. Use these IDs with `get_renders_by_commit`. |
+| `get_renders_by_commit` | Returns all unnecessary re-renders for a specific React commit ID. |
 | `get_projects` | Lists all active projects (identified by their origin URL). |
 | `clear_renders` | Clears all stored render data. Optionally scope to a specific project. |
 
 When multiple projects are active, tools accept an optional `project` parameter (the browser's origin URL, e.g. `http://localhost:3000`). If omitted and only one project exists, it is auto-selected.
 
+### Commit-level grouping
+
+Each render report is tagged with a React **commit ID**, allowing agents to inspect which components re-rendered together in the same commit. The client tracks commits by hooking into `__REACT_DEVTOOLS_GLOBAL_HOOK__.onCommitFiberRoot`, which React calls synchronously once per commit. A typical workflow:
+
+1. Call `get_commits` to list available commit IDs
+2. Call `get_renders_by_commit` with a specific ID to see all renders in that commit
+
 ## Architecture
 
 ```
@@ -117,6 +196,7 @@ Browser (project-b) ──┤
 - **Multiple MCP instances** can run simultaneously. Only the first instance starts the WebSocket server; others gracefully skip. All instances share the same JSONL data directory.
 - **Multi-project support** — Each project is identified by `location.origin`. Render data is stored in per-project JSONL files.
 - **No daemon required** — Each MCP instance is independent. The WebSocket server is opportunistically claimed by whichever instance starts first.
+- **Value dictionary deduplication** — Render reports often repeat the same `prevValue`/`nextValue` objects across thousands of entries. Each JSONL file stores a content-addressed dictionary on its first line, mapping xxhash-wasm hashes to unique values. Render lines reference them via `@@ref:<hash>` sentinels instead of inlining the full object, dramatically reducing file size. Reads hydrate refs transparently.
 
 ## Configuration
 

package/dist/client/index.cjs

@@ -1,14 +1,116 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 //#region src/client/utils/describe-value.ts
+const MAX_DEPTH = 8;
+const REACT_ELEMENT_SYMBOL = Symbol.for("react.element");
+const REACT_TRANSITIONAL_ELEMENT_SYMBOL = Symbol.for("react.transitional.element");
+const REACT_MEMO_TYPE = Symbol.for("react.memo");
+const REACT_FORWARD_REF_TYPE = Symbol.for("react.forward_ref");
+function isReactElement(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const v = value;
+	return v.$$typeof === REACT_ELEMENT_SYMBOL || v.$$typeof === REACT_TRANSITIONAL_ELEMENT_SYMBOL || v.$$typeof === 60103;
+}
+function resolveComponentInfo(type) {
+	let memo = false;
+	let forwardRef = false;
+	let current = type;
+	for (let i = 0; i < 5; i++) {
+		if (typeof current !== "object" || current === null) break;
+		const wrapper = current;
+		if (wrapper.$$typeof === REACT_MEMO_TYPE) {
+			memo = true;
+			current = wrapper.type;
+		} else if (wrapper.$$typeof === REACT_FORWARD_REF_TYPE) {
+			forwardRef = true;
+			current = wrapper.render;
+		} else break;
+	}
+	let name = "Unknown";
+	if (typeof current === "string") name = current;
+	else if (typeof current === "function") name = current.displayName || current.name || "Anonymous";
+	return {
+		name,
+		memo,
+		forwardRef
+	};
+}
+function serializeReactElement(el, seen, depth) {
+	const component = resolveComponentInfo(el.type);
+	const props = {};
+	if (el.props && typeof el.props === "object") for (const key of Object.keys(el.props)) {
+		if (key === "children") continue;
+		props[key] = serialize(el.props[key], seen, depth + 1);
+	}
+	return {
+		type: "react-node",
+		component,
+		props
+	};
+}
+function serialize(value, seen, depth) {
+	if (value === null) return null;
+	if (value === void 0) return null;
+	if (typeof value === "function") return {
+		type: "function",
+		name: value.name || "anonymous"
+	};
+	if (typeof value === "boolean") return value;
+	if (typeof value === "number") {
+		if (Number.isNaN(value)) return "NaN";
+		if (!Number.isFinite(value)) return value > 0 ? "Infinity" : "-Infinity";
+		if (Object.is(value, -0)) return "-0";
+		return value;
+	}
+	if (typeof value === "string") return value;
+	if (typeof value === "bigint") return value.toString();
+	if (typeof value === "symbol") return value.toString();
+	if (seen.has(value)) return "[Circular]";
+	if (depth >= MAX_DEPTH) return "[MaxDepth]";
+	seen.add(value);
+	if (isReactElement(value)) return serializeReactElement(value, seen, depth);
+	if (Array.isArray(value)) return value.map((item) => serialize(item, seen, depth + 1));
+	const ctorName = Object.getPrototypeOf(value)?.constructor?.name;
+	if (ctorName && ctorName !== "Object") {
+		if (value instanceof Date) return value.toISOString();
+		if (value instanceof RegExp) return String(value);
+		if (value instanceof Map) {
+			const entries = {};
+			for (const [k, v] of value.entries()) entries[String(k)] = serialize(v, seen, depth + 1);
+			return {
+				type: "Map",
+				entries
+			};
+		}
+		if (value instanceof Set) return {
+			type: "Set",
+			values: [...value].map((v) => serialize(v, seen, depth + 1))
+		};
+		if (value instanceof Promise) return "Promise";
+		if (value instanceof Error) return {
+			type: "Error",
+			name: value.name,
+			message: value.message
+		};
+		if (typeof Node !== "undefined" && value instanceof Node && value instanceof Element) {
+			const attrs = {};
+			for (const attr of value.attributes) attrs[attr.name] = attr.value;
+			return {
+				type: "dom",
+				tagName: value.tagName.toLowerCase(),
+				attrs
+			};
+		}
+		return {
+			type: "class",
+			name: ctorName
+		};
+	}
+	const result = {};
+	for (const key of Object.keys(value)) result[key] = serialize(value[key], seen, depth + 1);
+	return result;
+}
 function describeValue(value) {
-	if (value === null) return "null";
-	if (value === void 0) return "undefined";
-	if (typeof value === "function") return `function ${value.name || "anonymous"}`;
-	if (typeof value !== "object") return String(value);
-	if (Array.isArray(value)) return `Array(${value.length})`;
-	const name = Object.getPrototypeOf(value)?.constructor?.name;
-	if (name && name !== "Object") return name;
-	return "Object";
+	return serialize(value, /* @__PURE__ */ new WeakSet(), 0);
 }
 //#endregion
 //#region src/client/utils/sanitize-differences.ts
@@ -33,40 +135,95 @@ function sanitizeReason(reason) {
 //#endregion
 //#region src/client/index.ts
 const DEFAULT_WS_URL = "ws://localhost:4649";
+const PREFIX_STYLE = "color: #38bdf8; font-weight: bold";
+const RESET_STYLE = "color: inherit; font-weight: normal";
+function log(message) {
+	console.log(`%c[WDYR MCP]%c ${message}`, PREFIX_STYLE, RESET_STYLE);
+}
+function patchDevToolsHook(onCommit) {
+	if (!globalThis.__REACT_DEVTOOLS_GLOBAL_HOOK__) globalThis.__REACT_DEVTOOLS_GLOBAL_HOOK__ = {
+		supportsFiber: true,
+		inject() {},
+		onCommitFiberRoot() {},
+		onCommitFiberUnmount() {}
+	};
+	const hook = globalThis.__REACT_DEVTOOLS_GLOBAL_HOOK__;
+	const original = hook.onCommitFiberRoot.bind(hook);
+	hook.onCommitFiberRoot = (...args) => {
+		onCommit();
+		return original(...args);
+	};
+}
 function buildOptions(opts) {
 	const wsUrl = opts?.wsUrl ?? DEFAULT_WS_URL;
 	const projectId = opts?.projectId ?? globalThis.location?.origin ?? "default";
+	const MAX_QUEUE_SIZE = 1e3;
+	const BASE_DELAY = 1e3;
+	const MAX_DELAY = 3e4;
 	let ws = null;
 	let queue = [];
+	let commitId = 0;
+	let retryDelay = BASE_DELAY;
+	patchDevToolsHook(() => {
+		commitId++;
+	});
 	function connect() {
 		ws = new WebSocket(wsUrl);
 		ws.addEventListener("open", () => {
+			log(`Connected to ${wsUrl}`);
+			retryDelay = BASE_DELAY;
 			for (const msg of queue) ws?.send(JSON.stringify(msg));
 			queue = [];
 		});
 		ws.addEventListener("close", () => {
 			ws = null;
-			setTimeout(connect, 1e3);
+			setTimeout(connect, retryDelay);
+			retryDelay = Math.min(retryDelay * 2, MAX_DELAY);
 		});
 		ws.addEventListener("error", () => {
+			log(`Connection failed (${wsUrl}). Retrying in ${retryDelay / 1e3}s...`);
 			ws?.close();
 		});
 	}
 	connect();
 	function send(msg) {
 		if (ws?.readyState === WebSocket.OPEN) ws.send(JSON.stringify(msg));
-		else queue.push(msg);
+		else {
+			if (queue.length >= MAX_QUEUE_SIZE) queue.shift();
+			queue.push(msg);
+		}
 	}
-	return { notifier(info) {
+	let pendingBatch = null;
+	let flushScheduled = false;
+	function flushBatch() {
+		flushScheduled = false;
+		if (!pendingBatch || pendingBatch.reports.length === 0) return;
 		send({
-			type: "render",
+			type: "render-batch",
 			projectId,
-			payload: {
-				displayName: info.displayName,
-				reason: sanitizeReason(info.reason),
-				hookName: info.hookName
-			}
+			commitId: pendingBatch.commitId,
+			payload: pendingBatch.reports
 		});
+		pendingBatch = null;
+	}
+	return { notifier(info) {
+		const report = {
+			displayName: info.displayName,
+			reason: sanitizeReason(info.reason),
+			hookName: info.hookName
+		};
+		if (pendingBatch && pendingBatch.commitId === commitId) pendingBatch.reports.push(report);
+		else {
+			if (pendingBatch) flushBatch();
+			pendingBatch = {
+				commitId,
+				reports: [report]
+			};
+		}
+		if (!flushScheduled) {
+			flushScheduled = true;
+			queueMicrotask(flushBatch);
+		}
 	} };
 }
 //#endregion

package/dist/client/index.d.cts

@@ -1,6 +1,7 @@
 import { UpdateInfo } from "@welldone-software/why-did-you-render";
 
 //#region src/client/index.d.ts
+sideEffect();
 interface ClientOptions {
   wsUrl?: string;
   projectId?: string;

package/dist/client/index.d.ts

@@ -1,6 +1,7 @@
 import { UpdateInfo } from "@welldone-software/why-did-you-render";
 
 //#region src/client/index.d.ts
+sideEffect();
 interface ClientOptions {
   wsUrl?: string;
   projectId?: string;

package/dist/client/index.js

@@ -1,13 +1,115 @@
 //#region src/client/utils/describe-value.ts
+const MAX_DEPTH = 8;
+const REACT_ELEMENT_SYMBOL = Symbol.for("react.element");
+const REACT_TRANSITIONAL_ELEMENT_SYMBOL = Symbol.for("react.transitional.element");
+const REACT_MEMO_TYPE = Symbol.for("react.memo");
+const REACT_FORWARD_REF_TYPE = Symbol.for("react.forward_ref");
+function isReactElement(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const v = value;
+	return v.$$typeof === REACT_ELEMENT_SYMBOL || v.$$typeof === REACT_TRANSITIONAL_ELEMENT_SYMBOL || v.$$typeof === 60103;
+}
+function resolveComponentInfo(type) {
+	let memo = false;
+	let forwardRef = false;
+	let current = type;
+	for (let i = 0; i < 5; i++) {
+		if (typeof current !== "object" || current === null) break;
+		const wrapper = current;
+		if (wrapper.$$typeof === REACT_MEMO_TYPE) {
+			memo = true;
+			current = wrapper.type;
+		} else if (wrapper.$$typeof === REACT_FORWARD_REF_TYPE) {
+			forwardRef = true;
+			current = wrapper.render;
+		} else break;
+	}
+	let name = "Unknown";
+	if (typeof current === "string") name = current;
+	else if (typeof current === "function") name = current.displayName || current.name || "Anonymous";
+	return {
+		name,
+		memo,
+		forwardRef
+	};
+}
+function serializeReactElement(el, seen, depth) {
+	const component = resolveComponentInfo(el.type);
+	const props = {};
+	if (el.props && typeof el.props === "object") for (const key of Object.keys(el.props)) {
+		if (key === "children") continue;
+		props[key] = serialize(el.props[key], seen, depth + 1);
+	}
+	return {
+		type: "react-node",
+		component,
+		props
+	};
+}
+function serialize(value, seen, depth) {
+	if (value === null) return null;
+	if (value === void 0) return null;
+	if (typeof value === "function") return {
+		type: "function",
+		name: value.name || "anonymous"
+	};
+	if (typeof value === "boolean") return value;
+	if (typeof value === "number") {
+		if (Number.isNaN(value)) return "NaN";
+		if (!Number.isFinite(value)) return value > 0 ? "Infinity" : "-Infinity";
+		if (Object.is(value, -0)) return "-0";
+		return value;
+	}
+	if (typeof value === "string") return value;
+	if (typeof value === "bigint") return value.toString();
+	if (typeof value === "symbol") return value.toString();
+	if (seen.has(value)) return "[Circular]";
+	if (depth >= MAX_DEPTH) return "[MaxDepth]";
+	seen.add(value);
+	if (isReactElement(value)) return serializeReactElement(value, seen, depth);
+	if (Array.isArray(value)) return value.map((item) => serialize(item, seen, depth + 1));
+	const ctorName = Object.getPrototypeOf(value)?.constructor?.name;
+	if (ctorName && ctorName !== "Object") {
+		if (value instanceof Date) return value.toISOString();
+		if (value instanceof RegExp) return String(value);
+		if (value instanceof Map) {
+			const entries = {};
+			for (const [k, v] of value.entries()) entries[String(k)] = serialize(v, seen, depth + 1);
+			return {
+				type: "Map",
+				entries
+			};
+		}
+		if (value instanceof Set) return {
+			type: "Set",
+			values: [...value].map((v) => serialize(v, seen, depth + 1))
+		};
+		if (value instanceof Promise) return "Promise";
+		if (value instanceof Error) return {
+			type: "Error",
+			name: value.name,
+			message: value.message
+		};
+		if (typeof Node !== "undefined" && value instanceof Node && value instanceof Element) {
+			const attrs = {};
+			for (const attr of value.attributes) attrs[attr.name] = attr.value;
+			return {
+				type: "dom",
+				tagName: value.tagName.toLowerCase(),
+				attrs
+			};
+		}
+		return {
+			type: "class",
+			name: ctorName
+		};
+	}
+	const result = {};
+	for (const key of Object.keys(value)) result[key] = serialize(value[key], seen, depth + 1);
+	return result;
+}
 function describeValue(value) {
-	if (value === null) return "null";
-	if (value === void 0) return "undefined";
-	if (typeof value === "function") return `function ${value.name || "anonymous"}`;
-	if (typeof value !== "object") return String(value);
-	if (Array.isArray(value)) return `Array(${value.length})`;
-	const name = Object.getPrototypeOf(value)?.constructor?.name;
-	if (name && name !== "Object") return name;
-	return "Object";
+	return serialize(value, /* @__PURE__ */ new WeakSet(), 0);
 }
 //#endregion
 //#region src/client/utils/sanitize-differences.ts
@@ -32,40 +134,95 @@ function sanitizeReason(reason) {
 //#endregion
 //#region src/client/index.ts
 const DEFAULT_WS_URL = "ws://localhost:4649";
+const PREFIX_STYLE = "color: #38bdf8; font-weight: bold";
+const RESET_STYLE = "color: inherit; font-weight: normal";
+function log(message) {
+	console.log(`%c[WDYR MCP]%c ${message}`, PREFIX_STYLE, RESET_STYLE);
+}
+function patchDevToolsHook(onCommit) {
+	if (!globalThis.__REACT_DEVTOOLS_GLOBAL_HOOK__) globalThis.__REACT_DEVTOOLS_GLOBAL_HOOK__ = {
+		supportsFiber: true,
+		inject() {},
+		onCommitFiberRoot() {},
+		onCommitFiberUnmount() {}
+	};
+	const hook = globalThis.__REACT_DEVTOOLS_GLOBAL_HOOK__;
+	const original = hook.onCommitFiberRoot.bind(hook);
+	hook.onCommitFiberRoot = (...args) => {
+		onCommit();
+		return original(...args);
+	};
+}
 function buildOptions(opts) {
 	const wsUrl = opts?.wsUrl ?? DEFAULT_WS_URL;
 	const projectId = opts?.projectId ?? globalThis.location?.origin ?? "default";
+	const MAX_QUEUE_SIZE = 1e3;
+	const BASE_DELAY = 1e3;
+	const MAX_DELAY = 3e4;
 	let ws = null;
 	let queue = [];
+	let commitId = 0;
+	let retryDelay = BASE_DELAY;
+	patchDevToolsHook(() => {
+		commitId++;
+	});
 	function connect() {
 		ws = new WebSocket(wsUrl);
 		ws.addEventListener("open", () => {
+			log(`Connected to ${wsUrl}`);
+			retryDelay = BASE_DELAY;
 			for (const msg of queue) ws?.send(JSON.stringify(msg));
 			queue = [];
 		});
 		ws.addEventListener("close", () => {
 			ws = null;
-			setTimeout(connect, 1e3);
+			setTimeout(connect, retryDelay);
+			retryDelay = Math.min(retryDelay * 2, MAX_DELAY);
 		});
 		ws.addEventListener("error", () => {
+			log(`Connection failed (${wsUrl}). Retrying in ${retryDelay / 1e3}s...`);
 			ws?.close();
 		});
 	}
 	connect();
 	function send(msg) {
 		if (ws?.readyState === WebSocket.OPEN) ws.send(JSON.stringify(msg));
-		else queue.push(msg);
+		else {
+			if (queue.length >= MAX_QUEUE_SIZE) queue.shift();
+			queue.push(msg);
+		}
 	}
-	return { notifier(info) {
+	let pendingBatch = null;
+	let flushScheduled = false;
+	function flushBatch() {
+		flushScheduled = false;
+		if (!pendingBatch || pendingBatch.reports.length === 0) return;
 		send({
-			type: "render",
+			type: "render-batch",
 			projectId,
-			payload: {
-				displayName: info.displayName,
-				reason: sanitizeReason(info.reason),
-				hookName: info.hookName
-			}
+			commitId: pendingBatch.commitId,
+			payload: pendingBatch.reports
 		});
+		pendingBatch = null;
+	}
+	return { notifier(info) {
+		const report = {
+			displayName: info.displayName,
+			reason: sanitizeReason(info.reason),
+			hookName: info.hookName
+		};
+		if (pendingBatch && pendingBatch.commitId === commitId) pendingBatch.reports.push(report);
+		else {
+			if (pendingBatch) flushBatch();
+			pendingBatch = {
+				commitId,
+				reports: [report]
+			};
+		}
+		if (!flushScheduled) {
+			flushScheduled = true;
+			queueMicrotask(flushBatch);
+		}
 	} };
 }
 //#endregion

package/dist/server/index.js

@@ -2,14 +2,107 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, unlinkSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import xxhash from "xxhash-wasm";
 import { WebSocketServer } from "ws";
+//#region src/server/store/utils/value-dict.ts
+const DICT_KEY = "@@dict";
+const REF_PREFIX = "@@ref:";
+let h64ToString;
+const ready = xxhash().then((api) => {
+	h64ToString = api.h64ToString;
+});
+function ensureReady() {
+	return ready;
+}
+function hashValue(value) {
+	return h64ToString(JSON.stringify(value));
+}
+function shouldDehydrate(value) {
+	return typeof value === "object" && value !== null;
+}
+function dehydrateDiffs(diffs, dict) {
+	if (!diffs) return false;
+	return diffs.map((d) => {
+		let { prevValue, nextValue } = d;
+		if (shouldDehydrate(prevValue)) {
+			const hash = hashValue(prevValue);
+			dict[hash] ??= prevValue;
+			prevValue = `${REF_PREFIX}${hash}`;
+		}
+		if (shouldDehydrate(nextValue)) {
+			const hash = hashValue(nextValue);
+			dict[hash] ??= nextValue;
+			nextValue = `${REF_PREFIX}${hash}`;
+		}
+		return prevValue === d.prevValue && nextValue === d.nextValue ? d : {
+			...d,
+			prevValue,
+			nextValue
+		};
+	});
+}
+function dehydrate(render, dict) {
+	const { propsDifferences, stateDifferences, hookDifferences } = render.reason;
+	const newProps = dehydrateDiffs(propsDifferences, dict);
+	const newState = dehydrateDiffs(stateDifferences, dict);
+	const newHooks = dehydrateDiffs(hookDifferences, dict);
+	if (newProps === propsDifferences && newState === stateDifferences && newHooks === hookDifferences) return render;
+	return {
+		...render,
+		reason: {
+			propsDifferences: newProps,
+			stateDifferences: newState,
+			hookDifferences: newHooks
+		}
+	};
+}
+function hydrateDiffs(diffs, dict) {
+	if (!diffs) return false;
+	return diffs.map((d) => {
+		let { prevValue, nextValue } = d;
+		if (typeof prevValue === "string" && prevValue.startsWith(REF_PREFIX)) prevValue = dict[prevValue.slice(6)] ?? prevValue;
+		if (typeof nextValue === "string" && nextValue.startsWith(REF_PREFIX)) nextValue = dict[nextValue.slice(6)] ?? nextValue;
+		return prevValue === d.prevValue && nextValue === d.nextValue ? d : {
+			...d,
+			prevValue,
+			nextValue
+		};
+	});
+}
+function hydrate(render, dict) {
+	const { propsDifferences, stateDifferences, hookDifferences } = render.reason;
+	const newProps = hydrateDiffs(propsDifferences, dict);
+	const newState = hydrateDiffs(stateDifferences, dict);
+	const newHooks = hydrateDiffs(hookDifferences, dict);
+	if (newProps === propsDifferences && newState === stateDifferences && newHooks === hookDifferences) return render;
+	return {
+		...render,
+		reason: {
+			propsDifferences: newProps,
+			stateDifferences: newState,
+			hookDifferences: newHooks
+		}
+	};
+}
+//#endregion
 //#region src/server/store/utils/read-jsonl.ts
 function readJsonl(file) {
 	if (!existsSync(file)) return [];
-	return readFileSync(file, "utf-8").split("\n").filter(Boolean).map((line) => JSON.parse(line));
+	const lines = readFileSync(file, "utf-8").split("\n").filter(Boolean);
+	if (lines.length === 0) return [];
+	let dict;
+	let startIdx = 0;
+	const first = JSON.parse(lines[0]);
+	if ("@@dict" in first) {
+		dict = first[DICT_KEY];
+		startIdx = 1;
+	}
+	const renders = lines.slice(startIdx).map((l) => JSON.parse(l));
+	if (!dict) return renders;
+	return renders.map((r) => hydrate(r, dict));
 }
 //#endregion
 //#region src/server/store/utils/sanitize-project-id.ts
@@ -23,54 +116,90 @@ function toResult(stored) {
 		project: stored.projectId,
 		displayName: stored.displayName,
 		reason: stored.reason,
-		...stored.hookName != null && { hookName: stored.hookName }
+		...stored.hookName != null && { hookName: stored.hookName },
+		...stored.commitId != null && { commitId: stored.commitId }
 	};
 }
 //#endregion
 //#region src/server/store/render-store.ts
 const FLUSH_DELAY_MS = 200;
+const NOCOMMIT = "nocommit";
 var RenderStore = class {
 	dir;
 	buffers = /* @__PURE__ */ new Map();
 	timers = /* @__PURE__ */ new Map();
+	dicts = /* @__PURE__ */ new Map();
+	bufferMeta = /* @__PURE__ */ new Map();
 	constructor(dir) {
 		this.dir = dir ?? join(homedir(), ".wdyr-mcp", "renders");
 		mkdirSync(this.dir, { recursive: true });
 	}
-	addRender(report, projectId) {
+	addRender(report, projectId, commitId) {
 		const stored = {
 			...report,
-			projectId
+			projectId,
+			...commitId != null && { commitId }
 		};
-		let buf = this.buffers.get(projectId);
+		const bk = this.bufferKey(projectId, commitId);
+		let buf = this.buffers.get(bk);
 		if (!buf) {
 			buf = [];
-			this.buffers.set(projectId, buf);
+			this.buffers.set(bk, buf);
+			this.bufferMeta.set(bk, {
+				projectId,
+				commitId
+			});
 		}
 		buf.push(stored);
-		const existing = this.timers.get(projectId);
+		const existing = this.timers.get(bk);
 		if (existing) clearTimeout(existing);
-		this.timers.set(projectId, setTimeout(() => this.flush(projectId), FLUSH_DELAY_MS));
+		this.timers.set(bk, setTimeout(() => {
+			this.flushAsync(projectId, commitId).catch((err) => console.error(`[wdyr-mcp] flush error for ${bk}:`, err));
+		}, FLUSH_DELAY_MS));
 	}
-	flush(projectId) {
-		if (projectId) this.flushProject(projectId);
-		else for (const id of this.buffers.keys()) this.flushProject(id);
+	async flushAsync(projectId, commitId) {
+		await ensureReady();
+		this.flush(projectId, commitId);
 	}
-	flushProject(projectId) {
-		const buf = this.buffers.get(projectId);
+	flush(projectId, commitId) {
+		if (projectId != null && commitId !== void 0) this.flushBuffer(this.bufferKey(projectId, commitId));
+		else if (projectId != null) for (const bk of this.bufferKeysForProject(projectId)) this.flushBuffer(bk);
+		else for (const bk of [...this.buffers.keys()]) this.flushBuffer(bk);
+	}
+	flushBuffer(bk) {
+		const buf = this.buffers.get(bk);
 		if (!buf || buf.length === 0) return;
-		const lines = buf.map((s) => JSON.stringify(s)).join("\n");
-		appendFileSync(this.projectFile(projectId), `${lines}\n`);
+		const meta = this.bufferMeta.get(bk);
+		if (!meta) return;
+		let dict = this.dicts.get(bk);
+		if (!dict) {
+			dict = {};
+			this.dicts.set(bk, dict);
+		}
+		const dehydrated = buf.map((r) => dehydrate(r, dict));
+		const file = this.commitFile(meta.projectId, meta.commitId);
+		const existingLines = this.readDataLines(file);
+		const newLines = dehydrated.map((r) => JSON.stringify(r));
+		const allDataLines = [...existingLines, ...newLines];
+		writeFileSync(file, `${(Object.keys(dict).length > 0 ? [JSON.stringify({ [DICT_KEY]: dict }), ...allDataLines] : allDataLines).join("\n")}\n`);
 		buf.length = 0;
-		const timer = this.timers.get(projectId);
+		const timer = this.timers.get(bk);
 		if (timer) {
 			clearTimeout(timer);
-			this.timers.delete(projectId);
+			this.timers.delete(bk);
 		}
 	}
+	readDataLines(file) {
+		if (!existsSync(file)) return [];
+		return readFileSync(file, "utf-8").split("\n").filter((line) => {
+			if (!line) return false;
+			if (line.startsWith(`{"@@dict"`)) return false;
+			return true;
+		});
+	}
 	getAllRenders(projectId) {
 		this.flush(projectId);
-		if (projectId) return readJsonl(this.projectFile(projectId)).map(toResult);
+		if (projectId) return this.projectFiles(projectId).flatMap((f) => readJsonl(join(this.dir, f)).map(toResult));
 		return this.jsonlFiles().flatMap((f) => readJsonl(join(this.dir, f)).map(toResult));
 	}
 	getRendersByComponent(componentName, projectId) {
@@ -78,32 +207,65 @@ var RenderStore = class {
 	}
 	clearRenders(projectId) {
 		if (projectId) {
-			this.buffers.delete(projectId);
-			const timer = this.timers.get(projectId);
-			if (timer) {
-				clearTimeout(timer);
-				this.timers.delete(projectId);
+			for (const bk of this.bufferKeysForProject(projectId)) {
+				this.buffers.delete(bk);
+				this.dicts.delete(bk);
+				this.bufferMeta.delete(bk);
+				const timer = this.timers.get(bk);
+				if (timer) {
+					clearTimeout(timer);
+					this.timers.delete(bk);
+				}
 			}
-			const file = this.projectFile(projectId);
-			if (existsSync(file)) unlinkSync(file);
+			for (const f of this.projectFiles(projectId)) unlinkSync(join(this.dir, f));
 		} else {
-			for (const [id, timer] of this.timers) clearTimeout(timer);
+			for (const [, timer] of this.timers) clearTimeout(timer);
 			this.buffers.clear();
 			this.timers.clear();
+			this.dicts.clear();
+			this.bufferMeta.clear();
 			for (const f of this.jsonlFiles()) unlinkSync(join(this.dir, f));
 		}
 	}
 	getProjects() {
 		this.flush();
 		const projects = /* @__PURE__ */ new Set();
+		const seen = /* @__PURE__ */ new Set();
 		for (const f of this.jsonlFiles()) {
-			const firstLine = readFileSync(join(this.dir, f), "utf-8").split("\n")[0];
-			if (!firstLine) continue;
-			const stored = JSON.parse(firstLine);
-			projects.add(stored.projectId);
+			const parsed = this.parseFilename(f);
+			if (!parsed) continue;
+			if (seen.has(parsed.projectSanitized)) continue;
+			seen.add(parsed.projectSanitized);
+			const lines = readFileSync(join(this.dir, f), "utf-8").split("\n");
+			for (const line of lines) {
+				if (!line) continue;
+				const obj = JSON.parse(line);
+				if ("@@dict" in obj) continue;
+				projects.add(obj.projectId);
+				break;
+			}
 		}
 		return [...projects];
 	}
+	getCommitIds(projectId) {
+		this.flush(projectId);
+		const files = projectId ? this.projectFiles(projectId) : this.jsonlFiles();
+		const ids = /* @__PURE__ */ new Set();
+		for (const f of files) {
+			const parsed = this.parseFilename(f);
+			if (parsed?.commitId != null) ids.add(parsed.commitId);
+		}
+		return [...ids].sort((a, b) => a - b);
+	}
+	getRendersByCommit(commitId, projectId) {
+		if (projectId) {
+			this.flush(projectId, commitId);
+			return readJsonl(this.commitFile(projectId, commitId)).map(toResult);
+		}
+		this.flush();
+		const suffix = `_commit_${commitId}.jsonl`;
+		return this.jsonlFiles().filter((f) => f.endsWith(suffix)).flatMap((f) => readJsonl(join(this.dir, f)).map(toResult));
+	}
 	getSummary(projectId) {
 		const renders = this.getAllRenders(projectId);
 		const summary = {};
@@ -114,8 +276,33 @@ var RenderStore = class {
 		}
 		return summary;
 	}
-	projectFile(projectId) {
-		return join(this.dir, `${sanitizeProjectId(projectId)}.jsonl`);
+	bufferKey(projectId, commitId) {
+		return `${projectId}\0${commitId ?? NOCOMMIT}`;
+	}
+	bufferKeysForProject(projectId) {
+		const prefix = `${projectId}\0`;
+		return [...this.buffers.keys()].filter((bk) => bk.startsWith(prefix));
+	}
+	commitFile(projectId, commitId) {
+		const sanitized = sanitizeProjectId(projectId);
+		const suffix = commitId != null ? `_commit_${commitId}` : `_${NOCOMMIT}`;
+		return join(this.dir, `${sanitized}${suffix}.jsonl`);
+	}
+	projectFiles(projectId) {
+		const prefix = sanitizeProjectId(projectId);
+		return readdirSync(this.dir).filter((f) => f.startsWith(prefix) && f.endsWith(".jsonl"));
+	}
+	parseFilename(filename) {
+		if (!filename.endsWith(".jsonl")) return null;
+		const base = filename.slice(0, -6);
+		const commitMatch = base.match(/^(.+)_commit_(\d+)$/);
+		if (commitMatch) return {
+			projectSanitized: commitMatch[1],
+			commitId: Number(commitMatch[2])
+		};
+		const nocommitMatch = base.match(/^(.+)_nocommit$/);
+		if (nocommitMatch) return { projectSanitized: nocommitMatch[1] };
+		return { projectSanitized: base };
 	}
 	jsonlFiles() {
 		return readdirSync(this.dir).filter((f) => f.endsWith(".jsonl"));
@@ -156,7 +343,7 @@ function textResult(text) {
 }
 //#endregion
 //#region src/server/tools/clear-renders.ts
-function register$3(server) {
+function register$5(server) {
 	server.registerTool("clear_renders", {
 		title: "Clear Renders",
 		description: "Clears collected render data. If multiple projects are active and no project is specified, the tool will ask you to disambiguate.",
@@ -169,8 +356,23 @@ function register$3(server) {
 	});
 }
 //#endregion
+//#region src/server/tools/get-commits.ts
+function register$4(server) {
+	server.registerTool("get_commits", {
+		title: "Get Commits",
+		description: "Returns a list of React commit IDs that have recorded render data for a project. Use these IDs with get_renders_by_commit to inspect individual commits.",
+		inputSchema: { project: z.string().optional().describe("Project identifier (the browser's origin URL, e.g. http://localhost:3000). Omit to auto-detect.") }
+	}, async ({ project }) => {
+		const resolved = resolveProject(project);
+		if (resolved.error) return textResult(resolved.error);
+		const commitIds = store.getCommitIds(resolved.projectId);
+		if (commitIds.length === 0) return textResult("No commits recorded yet. Make sure the browser is connected and triggering re-renders.");
+		return textResult(JSON.stringify(commitIds));
+	});
+}
+//#endregion
 //#region src/server/tools/get-projects.ts
-function register$2(server) {
+function register$3(server) {
 	server.registerTool("get_projects", {
 		title: "Get Projects",
 		description: "Returns a list of project identifiers (browser origin URLs) that have recorded render data.",
@@ -183,7 +385,7 @@ function register$2(server) {
 }
 //#endregion
 //#region src/server/tools/get-render-summary.ts
-function register$1(server) {
+function register$2(server) {
 	server.registerTool("get_render_summary", {
 		title: "Get Render Summary",
 		description: "Returns a summary of unnecessary re-renders grouped by component name with counts. If multiple projects are active and no project is specified, the tool will ask you to disambiguate.",
@@ -202,6 +404,26 @@ function register$1(server) {
 	});
 }
 //#endregion
+//#region src/server/tools/get-renders-by-commit.ts
+function register$1(server) {
+	server.registerTool("get_renders_by_commit", {
+		title: "Get Renders by Commit",
+		description: "Returns all unnecessary re-renders for a specific React commit ID. Use get_commits first to discover available commit IDs.",
+		inputSchema: {
+			commitId: z.number().describe("The React commit ID to filter by."),
+			component: z.string().optional().describe("Filter by component name. Omit to get all renders."),
+			project: z.string().optional().describe("Project identifier (the browser's origin URL, e.g. http://localhost:3000). Omit to auto-detect.")
+		}
+	}, async ({ commitId, component, project }) => {
+		const resolved = resolveProject(project);
+		if (resolved.error) return textResult(resolved.error);
+		let renders = store.getRendersByCommit(commitId, resolved.projectId);
+		if (component) renders = renders.filter((r) => r.displayName === component);
+		if (renders.length === 0) return textResult(component ? `No renders recorded for component "${component}" in commit ${commitId}.` : `No renders recorded for commit ${commitId}.`);
+		return textResult(JSON.stringify(renders, null, 2));
+	});
+}
+//#endregion
 //#region src/server/tools/get-unnecessary-renders.ts
 function register(server) {
 	server.registerTool("get_unnecessary_renders", {
@@ -223,9 +445,11 @@ function register(server) {
 //#region src/server/tools/index.ts
 function registerTools(server) {
 	register(server);
-	register$1(server);
 	register$2(server);
+	register$4(server);
+	register$1(server);
 	register$3(server);
+	register$5(server);
 }
 //#endregion
 //#region src/server/liveness.ts
@@ -300,11 +524,10 @@ function createWsServer(port) {
 		ws.on("message", (raw) => {
 			try {
 				const msg = JSON.parse(String(raw));
-				if (msg.type === "render") {
-					const projectId = msg.projectId ?? "default";
-					heartbeat.setProjectId(ws, projectId);
-					store.addRender(msg.payload, projectId);
-				}
+				const projectId = msg.projectId ?? "default";
+				heartbeat.setProjectId(ws, projectId);
+				if (msg.type === "render") store.addRender(msg.payload, projectId, msg.commitId);
+				else if (msg.type === "render-batch") for (const report of msg.payload) store.addRender(report, projectId, msg.commitId);
 			} catch {
 				console.error("[wdyr-mcp] invalid message received");
 			}
@@ -327,10 +550,22 @@ const server = new McpServer({
 });
 registerTools(server);
 async function main() {
-	createWsServer(Number(process.env.WDYR_WS_PORT) || DEFAULT_WS_PORT);
+	const wss = createWsServer(Number(process.env.WDYR_WS_PORT) || DEFAULT_WS_PORT);
 	const transport = new StdioServerTransport();
 	await server.connect(transport);
 	console.error("[wdyr-mcp] MCP server running on stdio");
+	let shuttingDown = false;
+	async function shutdown() {
+		if (shuttingDown) return;
+		shuttingDown = true;
+		console.error("[wdyr-mcp] Shutting down…");
+		wss?.close();
+		await server.close();
+		process.exit(0);
+	}
+	process.stdin.on("end", shutdown);
+	process.on("SIGTERM", shutdown);
+	process.on("SIGINT", shutdown);
 }
 main().catch((error) => {
 	console.error("[wdyr-mcp] Fatal error:", error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@0x1f320.sh/why-did-you-render-mcp",
-  "version": "1.0.0-dev.1",
+  "version": "1.0.0-dev.10",
   "type": "module",
   "description": "MCP server that collects why-did-you-render data from browser and exposes it to coding agents",
   "license": "MIT",
@@ -50,10 +50,13 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.1",
     "ws": "^8.18.0",
+    "xxhash-wasm": "^1.1.0",
     "zod": "^3.24.4"
   },
   "devDependencies": {
     "@biomejs/biome": "^1.9.4",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
     "@types/node": "^22.14.1",
     "@types/ws": "^8.18.0",
     "@vitest/coverage-v8": "^4.1.2",