feat(react): /react-doctor umbrella skill + in-house browser core + debug job

.agents/skills/react-doctor

@@ -0,0 +1 @@
+../../skills/react-doctor

.changeset/browser-eval-errors-geometry.md

@@ -0,0 +1,5 @@
+---
+"react-doctor": patch
+---
+
+Make `browser eval` and `browser eval --profile` self-reporting about what an action did to the page. A driven action that triggers a page-side error (a `console.error` or an uncaught throw) now appends an "Errors during eval" section instead of failing silently, so a broken interaction surfaces without hand-wiring a console hook. `--profile` (and the `browser_profile` MCP tool) now reports page geometry alongside memory — viewport size, devicePixelRatio, scroll offset, and how far the page scrolled while the action ran — so "did the element move, or did the page scroll under me?" is answerable from the output. Page scroll delta only prints when the viewport actually moved.

.changeset/browser-eval-snapshot-ergonomics.md

@@ -0,0 +1,5 @@
+---
+"react-doctor": patch
+---
+
+Make `browser eval` the one primitive for driving a page: when an expression just acts (returns nothing), it now hands back the resulting accessibility tree, so a single call both drives the page and shows the new state — no follow-up `snapshot`. Multi-statement source works without hand-wrapping it in an async IIFE, and a page-context `ReferenceError` (`window is not defined`) now explains that `eval` runs in Node with the Playwright `page` in scope and to reach page globals through `page.evaluate(() => …)`. The same applies to the `browser_eval` MCP tool. Locating stays pure Playwright — `browser snapshot`, or `page.locator(...).ariaSnapshot()` inside `eval` for a subtree.

.changeset/react-browser-debug-skill.md

@@ -0,0 +1,5 @@
+---
+"react-doctor": patch
+---
+
+Add the `browser`, `debug`, and `mcp` commands behind the unified `/react-doctor` skill. `browser` drives a real Chrome over CDP (attaching to your running session, launching a dedicated persistent profile only as a fallback): `open` a page, `eval` a Playwright expression, `snapshot` the accessibility tree, and `screenshot`. Adding `--profile` to `eval` records the whole runtime picture in one pass while the expression runs — console, network, performance (long animation frames with per-script attribution, LCP, CLS, plus a DevTools timeline roll-up of forced style-recalc/layout/hit-test/paint cost), an axe-core accessibility audit, a React render profile (slowest commits, hottest components by self time, unnecessary re-render counts), and a Chrome DevTools CPU profile via V8's sampling profiler over CDP (the hottest JS functions ranked by self time). It also writes the raw DevTools timeline trace to a file (`--out`, default `react-doctor-trace.json`) that loads in the DevTools Performance panel. `debug` runs an NDJSON logging server the debug job posts runtime evidence to. `mcp` runs a Model Context Protocol server over stdio that exposes the doctor scan and the browser/debug jobs as MCP tools, so any MCP-capable agent can run `react-doctor mcp` and call `doctor_scan`, the `browser_*` tools (`browser_eval` takes a `profile: true` argument that captures every signal together), and the `debug_*` log server directly.

.gitignore

@@ -15,8 +15,7 @@ review-*.md
 /.agents/*
 !/.agents/skills/
 /.agents/skills/*
-!/.agents/skills/react-doctor/
-!/.agents/skills/react-doctor/**
+!/.agents/skills/react-doctor
 !/.agents/skills/rule-research/
 !/.agents/skills/rule-research/**
 !/.agents/skills/rule-writing/
@@ -46,3 +45,8 @@ review-*.md
 /scripts/print-batch-input.mjs
 /scripts/rule-prompts/
 /rules.json
+
+# Local-only artifacts written by `react-doctor browser` (timeline trace,
+# screenshot) when run from the repo root during development.
+/react-doctor-trace.json
+/react-doctor-screenshot.png

packages/browser/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@react-doctor/browser",
+  "version": "0.5.4",
+  "private": true,
+  "description": "Internal: React Doctor's browser driver. Attaches to a running Chrome over CDP (or launches one) and keeps the page open across commands, backing the debug and design jobs.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && cross-env NODE_ENV=production vp pack",
+    "typecheck": "tsc --noEmit",
+    "test": "vp test run"
+  },
+  "dependencies": {
+    "axe-core": "^4.10.2",
+    "playwright-core": "^1.49.1"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "esbuild": "^0.25.12",
+    "react-devtools-inline": "^6.1.5"
+  },
+  "engines": {
+    "node": "^20.19.0 || >=22.13.0"
+  }
+}

packages/browser/src/analyze-cpu-profile.ts

@@ -0,0 +1,97 @@
+import { MAX_PROFILE_FUNCTIONS } from "./constants.js";
+import type { CpuProfileAnalysis } from "./types.js";
+import { roundToHundredths } from "./utils/round.js";
+
+interface CpuProfileCallFrame {
+  functionName: string;
+  url: string;
+  lineNumber: number;
+}
+
+interface CpuProfileNode {
+  id: number;
+  callFrame: CpuProfileCallFrame;
+  hitCount?: number;
+}
+
+// The shape of `Profiler.stop`'s `profile` (a structural subset of CDP's
+// Protocol.Profiler.Profile), the same JSON DevTools writes to a `.cpuprofile`.
+export interface CdpCpuProfile {
+  nodes: CpuProfileNode[];
+  startTime: number;
+  endTime: number;
+  samples?: number[];
+  timeDeltas?: number[];
+}
+
+// A function's display key: V8's synthetic frames ("(idle)", "(program)",
+// "(garbage collector)", "(root)") have no url and are kept as-is so the
+// percentages still add up to the wall time the profile covered.
+const labelFor = (callFrame: CpuProfileCallFrame): { name: string; url: string | null } => {
+  const name = callFrame.functionName || "(anonymous)";
+  const url = callFrame.url ? `${callFrame.url}:${callFrame.lineNumber + 1}` : null;
+  return { name, url };
+};
+
+// Fold a CDP CPU profile into self-time-per-function: each sample attributes its
+// paired time delta to the function on top of the stack at that sample. This
+// approximates the self-time DevTools' bottom-up view shows — where JS wall time
+// went (attribution can shift by up to one sample interval) — without the raw
+// node tree. Totals still sum to the wall time the profile covered.
+export const analyzeCpuProfile = (profile: CdpCpuProfile): CpuProfileAnalysis => {
+  const durationMs = (profile.endTime - profile.startTime) / 1000;
+  const samples = profile.samples ?? [];
+  const timeDeltas = profile.timeDeltas ?? [];
+
+  const nodeById = new Map<number, CpuProfileNode>();
+  for (const node of profile.nodes) nodeById.set(node.id, node);
+
+  // Accumulate self time (microseconds) by function key, summing same-named
+  // frames so a function split across optimization tiers reads as one row.
+  interface SelfTimeAccumulator {
+    functionName: string;
+    url: string | null;
+    selfUs: number;
+  }
+  const accumulatorByKey = new Map<string, SelfTimeAccumulator>();
+  const addSelfTime = (node: CpuProfileNode | undefined, microseconds: number): void => {
+    if (!node) return;
+    const { name, url } = labelFor(node.callFrame);
+    const key = `${name}@${url ?? ""}`;
+    const existing = accumulatorByKey.get(key);
+    if (existing) {
+      existing.selfUs += microseconds;
+      return;
+    }
+    accumulatorByKey.set(key, { functionName: name, url, selfUs: microseconds });
+  };
+
+  if (samples.length > 0 && timeDeltas.length === samples.length) {
+    for (let index = 0; index < samples.length; index += 1) {
+      addSelfTime(nodeById.get(samples[index]), timeDeltas[index]);
+    }
+  } else {
+    // No sample stream (rare): fall back to hitCount, scaling the node's share of
+    // total hits across the measured duration.
+    const totalHits = profile.nodes.reduce((sum, node) => sum + (node.hitCount ?? 0), 0) || 1;
+    const durationUs = durationMs * 1000;
+    for (const node of profile.nodes) {
+      addSelfTime(node, ((node.hitCount ?? 0) / totalHits) * durationUs);
+    }
+  }
+
+  const topFunctions = [...accumulatorByKey.values()]
+    .map((accumulator) => {
+      const selfMs = accumulator.selfUs / 1000;
+      return {
+        functionName: accumulator.functionName,
+        url: accumulator.url,
+        selfMs: roundToHundredths(selfMs),
+        selfPercent: durationMs > 0 ? roundToHundredths((selfMs / durationMs) * 100) : 0,
+      };
+    })
+    .sort((a, b) => b.selfMs - a.selfMs)
+    .slice(0, MAX_PROFILE_FUNCTIONS);
+
+  return { durationMs: roundToHundredths(durationMs), sampleCount: samples.length, topFunctions };
+};

packages/browser/src/analyze-timeline-trace.ts

@@ -0,0 +1,50 @@
+import type { TimelineAnalysis, TimelinePhaseStat } from "./types.js";
+import { roundToHundredths } from "./utils/round.js";
+
+// CDP types trace events loosely (string maps), so we narrow `name`/`dur`
+// ourselves. Complete events (`ph: "X"`) carry a microsecond `dur`; the rest of
+// the event shape is written to the trace file verbatim but ignored here.
+interface TraceEvent {
+  name?: unknown;
+  dur?: unknown;
+}
+
+// Trace event names that represent a forced/scheduled reflow phase. `Layout` and
+// `UpdateLayoutTree` (style recalc) are the cost of reading layout on a dirty
+// page; `HitTest` is what `elementsFromPoint` triggers; `Paint` follows both.
+const PHASE_BY_EVENT_NAME: Record<string, keyof TimelineAnalysis> = {
+  UpdateLayoutTree: "styleRecalc",
+  RecalculateStyles: "styleRecalc",
+  Layout: "layout",
+  HitTest: "hitTest",
+  Paint: "paint",
+};
+
+const emptyPhase = (): TimelinePhaseStat => ({ totalMs: 0, count: 0, longestMs: 0 });
+
+// Roll a Chrome DevTools timeline trace up into per-phase wall time, so the
+// native style/layout/hit-test cost a forced reflow incurs is a number in the
+// perf report rather than something you can only see in the trace file.
+export const analyzeTimelineTrace = (events: TraceEvent[]): TimelineAnalysis => {
+  const phases: TimelineAnalysis = {
+    styleRecalc: emptyPhase(),
+    layout: emptyPhase(),
+    hitTest: emptyPhase(),
+    paint: emptyPhase(),
+  };
+  for (const event of events) {
+    if (typeof event.name !== "string" || typeof event.dur !== "number") continue;
+    const phaseKey = PHASE_BY_EVENT_NAME[event.name];
+    if (!phaseKey) continue;
+    const durationMs = event.dur / 1000;
+    const phase = phases[phaseKey];
+    phase.totalMs += durationMs;
+    phase.count += 1;
+    if (durationMs > phase.longestMs) phase.longestMs = durationMs;
+  }
+  for (const phase of Object.values(phases)) {
+    phase.totalMs = roundToHundredths(phase.totalMs);
+    phase.longestMs = roundToHundredths(phase.longestMs);
+  }
+  return phases;
+};

packages/browser/src/browser-environment-error.ts

@@ -0,0 +1,16 @@
+// A browser failure caused by the machine's environment, not a react-doctor bug:
+// no Google Chrome to launch, the optional `playwright-core` dependency not
+// installed, or no debuggable Chrome to attach to. The CLI renders these as a
+// plain, actionable message and keeps them out of crash reporting (Sentry + the
+// error-rate metric) — see the CLI's `isExpectedUserError`. The message is the
+// fix instruction; throw sites phrase it for the user.
+export class BrowserEnvironmentError extends Error {
+  override readonly name = "BrowserEnvironmentError";
+
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+  }
+}
+
+export const isBrowserEnvironmentError = (error: unknown): error is BrowserEnvironmentError =>
+  error instanceof BrowserEnvironmentError;

packages/browser/src/close-launched-browser.ts

@@ -0,0 +1,26 @@
+import { CONNECT_TIMEOUT_MS } from "./constants.js";
+import { clearLaunchedEndpoint } from "./utils/clear-launched-endpoint.js";
+import { loadPlaywright } from "./utils/load-playwright.js";
+import { readLaunchedEndpoint } from "./utils/read-launched-endpoint.js";
+
+// Terminate the persistent Chrome we launched. `dispose()` only disconnects (the
+// persistent model keeps the page alive across commands), so this is the one path
+// that actually stops it — the cleanup a headless instance needs since there's no
+// window to quit. It targets ONLY our recorded endpoint, never a browser the user
+// started, so it can't kill their Chrome. Returns whether it closed anything.
+export const closeLaunchedBrowser = async (): Promise<boolean> => {
+  const endpoint = readLaunchedEndpoint();
+  if (!endpoint) return false;
+  const { chromium } = await loadPlaywright();
+  const browser = await chromium
+    .connectOverCDP(endpoint, { timeout: CONNECT_TIMEOUT_MS })
+    .catch(() => null);
+  // Couldn't attach: the instance may just be briefly unreachable, so keep the
+  // endpoint rather than orphaning a still-running Chrome we've now forgotten. A
+  // genuinely dead endpoint is harmless — the next launch overwrites it.
+  if (!browser) return false;
+  const cdpSession = await browser.newBrowserCDPSession();
+  await cdpSession.send("Browser.close").catch(() => {});
+  clearLaunchedEndpoint();
+  return true;
+};