what-devtools-mcp 0.8.3 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "what-devtools-mcp",
-  "version": "0.8.3",
+  "version": "0.10.0",
   "description": "MCP server bridging AI agents to live What Framework app state via WebSocket",
   "type": "module",
   "bin": {
@@ -9,6 +9,7 @@
   "exports": {
     ".": "./src/index.js",
     "./client": "./src/client.js",
+    "./vite": "./src/vite-plugin.js",
     "./vite-plugin": "./src/vite-plugin.js"
   },
   "files": [
@@ -16,7 +17,7 @@
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
-    "ws": "^8.0.0",
+    "ws": "^8.18.0",
     "zod": "^3.25.0"
   },
   "peerDependencies": {
@@ -29,5 +30,14 @@
     "model-context-protocol",
     "ai-debugging"
   ],
-  "license": "MIT"
+  "author": "ZVN DEV (https://zvndev.com)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/CelsianJs/what-framework"
+  },
+  "bugs": {
+    "url": "https://github.com/CelsianJs/what-framework/issues"
+  },
+  "homepage": "https://whatfw.com"
 }

package/src/bridge.js

@@ -33,9 +33,26 @@ export function createBridge({ port = 9229, host = '127.0.0.1' } = {}) {
   // Set WHAT_MCP_TOKEN to share the same token between bridge and Vite plugin.
   const authToken = process.env.WHAT_MCP_TOKEN || randomBytes(24).toString('hex');
 
+  // Only browser pages served from a loopback origin may talk to the bridge.
+  // This is the key defense against the "confused deputy" attack where a page
+  // on evil.com (open in the same browser as `what dev`) steals the token and
+  // drives set-signal/navigate/eval against the live app. Requests with no
+  // Origin header come from non-browser local processes (the MCP server's own
+  // client, curl) and are gated by the token instead. (AUDIT-2026-06-06 C6)
+  function isAllowedOrigin(origin) {
+    if (!origin) return true; // non-browser client; token is the gate
+    try {
+      const { hostname } = new URL(origin);
+      return hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '::1' || hostname === '[::1]';
+    } catch {
+      return false;
+    }
+  }
+
   const wss = new WebSocketServer({ host, port, verifyClient: ({ req }) => {
-    // Require a valid token query parameter to connect
+    // Require BOTH a loopback origin (defense in depth) AND a valid token.
     try {
+      if (!isAllowedOrigin(req.headers.origin)) return false;
       const url = new URL(req.url, `http://${host}:${port}`);
       return url.searchParams.get('token') === authToken;
     } catch {
@@ -54,8 +71,19 @@ export function createBridge({ port = 9229, host = '127.0.0.1' } = {}) {
 
   const discoveryPort = port + 1;
   const httpServer = createServer((req, res) => {
-    // CORS headers so the browser can fetch from any origin
-    res.setHeader('Access-Control-Allow-Origin', '*');
+    const origin = req.headers.origin;
+    // NEVER use a wildcard ACAO here — it would let any website read the token
+    // and then connect to the bridge. Echo the origin back only for loopback
+    // origins; reject token reads from any other origin. (AUDIT-2026-06-06 C6)
+    if (!isAllowedOrigin(origin)) {
+      res.writeHead(403);
+      res.end('Forbidden origin');
+      return;
+    }
+    if (origin) {
+      res.setHeader('Access-Control-Allow-Origin', origin);
+      res.setHeader('Vary', 'Origin');
+    }
     res.setHeader('Access-Control-Allow-Methods', 'GET');
     res.setHeader('Cache-Control', 'no-store');
 
@@ -86,7 +114,7 @@ export function createBridge({ port = 9229, host = '127.0.0.1' } = {}) {
   }
 
   console.error(`[what-devtools-mcp] Bridge listening on ws://${host}:${port}`);
-  console.error(`[what-devtools-mcp] Auth token: ${authToken}`);
+  console.error(`[what-devtools-mcp] Bridge started on port ${port} (auth enabled)`);
 
   wss.on('connection', (ws) => {
     browserSocket = ws;

package/src/client-commands.js

@@ -133,12 +133,14 @@ export async function handleExtendedCommand(command, args, devtools) {
 
       // Allow safe read-only expressions without the unsafe flag
       const code = (args.code || '').trim();
-      const isSafeRead = /^[\w.[\]'"]+$/.test(code) || // property access: document.title, window.innerWidth
-        /^typeof\s+\w+/.test(code) || // typeof checks
-        /^document\.(title|URL|readyState|visibilityState|characterSet|contentType)$/.test(code) ||
-        /^window\.(innerWidth|innerHeight|devicePixelRatio|screen\.\w+)$/.test(code) ||
-        /^navigator\.\w+$/.test(code) ||
-        /^location\.\w+$/.test(code);
+      // Strict safe-read: only allow dotted property access on known safe globals.
+      const SAFE_GLOBALS = new Set(['document', 'window', 'navigator', 'location', 'screen', 'performance', 'console']);
+      const segments = code.split('.');
+      const isSimpleIdent = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/;
+      const PROTO_DENYLIST = new Set(['constructor', 'prototype', '__proto__']);
+      const isSafeRead = segments.length >= 2 &&
+        SAFE_GLOBALS.has(segments[0]) &&
+        segments.every(s => isSimpleIdent.test(s) && !PROTO_DENYLIST.has(s));
 
       if (!evalEnabled && !isSafeRead) {
         return {
@@ -148,9 +150,11 @@ export async function handleExtendedCommand(command, args, devtools) {
 
       const start = performance.now();
       try {
-        // Use Function constructor to execute in global scope
+        // Execute the SAME validated string that passed the safe-read check
+        // above (not the untrimmed args.code) to avoid a validate-one/run-another
+        // mismatch. (AUDIT-2026-06-06 m10)
         // eslint-disable-next-line no-new-func
-        const fn = new Function(args.code);
+        const fn = new Function(code);
         const raw = fn();
         const elapsed = performance.now() - start;
         return {
@@ -293,6 +297,14 @@ export async function handleExtendedCommand(command, args, devtools) {
         return { error: 'No path provided' };
       }
 
+      // Validate URL — reject dangerous protocols (server-side + browser-side defense)
+      const trimmedPath = String(path).trim();
+      const normalizedUrl = trimmedPath.replace(/[\s\x00-\x1f]/g, '').toLowerCase();
+      const isRelativePath = /^[/.#?]/.test(trimmedPath) || !trimmedPath.includes(':');
+      if (!isRelativePath && !/^https?:/.test(normalizedUrl)) {
+        return { error: `Blocked navigation to unsafe URL: "${path}"` };
+      }
+
       try {
         // Prefer What Router's navigate() if available
         const core = window.__WHAT_CORE__;
@@ -539,14 +551,26 @@ export async function handleExtendedCommand(command, args, devtools) {
     // page-map — Structured map of the entire visible page
     // -------------------------------------------------------------------------
     case 'page-map': {
+      // Each category gets its own budget so a page with many landmarks
+      // doesn't starve out headings or components. Previous behaviour shared
+      // one `count` across all sections — a page with >maxElements landmarks
+      // returned headings: [] and components: [], which agents read as
+      // "the page has no headings / no components".
       const maxElements = args?.maxElements || 200;
-      let count = 0;
+      const perCategory = Math.max(50, Math.floor(maxElements / 2));
+
+      function rectOf(el) {
+        // Comment nodes / detached nodes have no rect; element walk handles that.
+        if (!el || el.nodeType !== 1) return { x: 0, y: 0, w: 0, h: 0 };
+        const r = el.getBoundingClientRect();
+        return { x: Math.round(r.x), y: Math.round(r.y), w: Math.round(r.width), h: Math.round(r.height) };
+      }
 
       // Landmarks
       const landmarks = [];
       const landmarkEls = document.querySelectorAll('[role], header, footer, nav, main, aside, section, article');
       for (const el of landmarkEls) {
-        if (count >= maxElements) break;
+        if (landmarks.length >= perCategory) break;
         const rect = el.getBoundingClientRect();
         if (rect.width === 0 && rect.height === 0) continue;
         landmarks.push({
@@ -554,16 +578,15 @@ export async function handleExtendedCommand(command, args, devtools) {
           role: el.getAttribute('role') || undefined,
           id: el.id || undefined,
           text: (el.textContent || '').trim().substring(0, 50),
-          rect: { x: Math.round(rect.x), y: Math.round(rect.y), w: Math.round(rect.width), h: Math.round(rect.height) },
+          rect: rectOf(el),
         });
-        count++;
       }
 
       // Interactive elements
       const interactives = [];
       const interactiveEls = document.querySelectorAll('button, a[href], input, select, textarea, [role=button], [role=link], [contenteditable]');
       for (const el of interactiveEls) {
-        if (count >= maxElements) break;
+        if (interactives.length >= perCategory) break;
         const rect = el.getBoundingClientRect();
         if (rect.width === 0 && rect.height === 0) continue;
         const label = el.getAttribute('aria-label') || el.textContent?.trim().substring(0, 40) || el.getAttribute('placeholder') || el.getAttribute('name') || '';
@@ -572,39 +595,41 @@ export async function handleExtendedCommand(command, args, devtools) {
           type: el.getAttribute('type') || undefined,
           label: label || '(unlabeled)',
           disabled: el.disabled || undefined,
-          rect: { x: Math.round(rect.x), y: Math.round(rect.y), w: Math.round(rect.width), h: Math.round(rect.height) },
+          rect: rectOf(el),
         });
-        count++;
       }
 
-      // Headings
+      // Headings — heading lists are nearly always small so we don't gate
+      // on visibility (some agents use display:none headings for SR-only nav).
       const headings = [];
       const headingEls = document.querySelectorAll('h1, h2, h3, h4, h5, h6');
       for (const el of headingEls) {
-        if (count >= maxElements) break;
+        if (headings.length >= perCategory) break;
+        const text = (el.textContent || '').trim().substring(0, 80);
+        if (!text) continue; // skip truly empty headings
         headings.push({
-          level: parseInt(el.tagName[1]),
-          text: (el.textContent || '').trim().substring(0, 80),
+          level: parseInt(el.tagName[1], 10),
+          text,
+          id: el.id || undefined,
         });
-        count++;
       }
 
-      // WhatFW component boundaries
+      // WhatFW component boundaries. Comment-node boundaries have no
+      // dimensions, so a strict zero-rect check was filtering everything
+      // out. Walk the registry once and emit every component, using the
+      // resolved element's rect when available.
       const components = [];
       const registries = devtools?._registries;
       if (registries?.components) {
         for (const [id, entry] of registries.components) {
-          if (count >= maxElements) break;
+          if (components.length >= perCategory) break;
           const compEl = getComponentElement(entry);
-          if (!compEl) continue;
-          const rect = compEl.getBoundingClientRect();
-          if (rect.width === 0 && rect.height === 0) continue;
           components.push({
             id,
             name: entry.name,
-            rect: { x: Math.round(rect.x), y: Math.round(rect.y), w: Math.round(rect.width), h: Math.round(rect.height) },
+            rect: compEl ? rectOf(compEl) : { x: 0, y: 0, w: 0, h: 0 },
+            hasElement: !!compEl,
           });
-          count++;
         }
       }
 
@@ -614,7 +639,7 @@ export async function handleExtendedCommand(command, args, devtools) {
         interactives,
         headings,
         components,
-        totalElements: count,
+        totalElements: landmarks.length + interactives.length + headings.length + components.length,
       };
     }
 

package/src/client.js

@@ -207,7 +207,24 @@ export function connectDevToolsMCP({ port = 9229, token = '' } = {}) {
         break;
       }
       case 'set-signal': {
-        const { signalId, value } = args || {};
+        const { signalId, value: rawValue } = args || {};
+        // Defense-in-depth: also coerce stringified-JSON here in case an
+        // older MCP server forwards the raw string. See tools.js coerceJsonValue.
+        let value = rawValue;
+        if (typeof rawValue === 'string') {
+          const t = rawValue.trim();
+          const first = t[0];
+          if (t.length > 0 && (
+            first === '{' || first === '[' ||
+            first === 't' || first === 'f' || first === 'n' ||
+            first === '-' || (first >= '0' && first <= '9')
+          )) {
+            try {
+              const parsed = JSON.parse(t);
+              if (typeof parsed !== 'string') value = parsed;
+            } catch {}
+          }
+        }
         const registries = devtools?._registries;
         if (registries?.signals) {
           const entry = registries.signals.get(signalId);

package/src/tools-agent.js

@@ -262,7 +262,7 @@ const LINT_RULES = [
             code: 'ERR_MISSING_CLEANUP',
             message: `Effect sets up ${resource} but does not return a cleanup function — memory leak risk.`,
             line,
-            suggestedFix: `Return a cleanup function: return () => remove${resource === 'event listener' ? 'EventListener(...)' : resource === 'interval' ? 'clearInterval(id)' : 'clearTimeout(id)'}`,
+            suggestedFix: `Return a cleanup function: return () => ${resource === 'event listener' ? 'removeEventListener(...)' : resource === 'interval' ? 'clearInterval(id)' : 'clearTimeout(id)'}`,
           });
         }
       }
@@ -431,6 +431,136 @@ const LINT_RULES = [
       return issues;
     },
   },
+  {
+    // -----------------------------------------------------------------------
+    // destructured-props-lose-reactivity
+    //
+    // What Framework components run ONCE — the function body is not re-run on
+    // prop change. The reactive props proxy auto-tracks reads via `props.foo`,
+    // but `const { foo } = props` snapshots the current value and detaches it
+    // from the proxy. Subsequent updates from the parent are invisible.
+    // -----------------------------------------------------------------------
+    id: 'destructured-props-lose-reactivity',
+    code: 'ERR_DESTRUCTURED_PROPS',
+    severity: 'warning',
+    test(code) {
+      const issues = [];
+      // Find component functions whose first param is `props` (any binding).
+      // We support both `function Foo(props) {` and `const Foo = (props) =>`.
+      const componentPatterns = [
+        /function\s+([A-Z]\w*)\s*\(\s*(\w+)\s*\)\s*\{/g,
+        /(?:const|let)\s+([A-Z]\w*)\s*=\s*\(\s*(\w+)\s*\)\s*=>/g,
+      ];
+      for (const pattern of componentPatterns) {
+        let compMatch;
+        while ((compMatch = pattern.exec(code)) !== null) {
+          const propsBinding = compMatch[2];
+          // Skip if the param is already destructured at the signature
+          // (that's a separate, more legible smell; we focus on body-level
+          // destructuring inside the component).
+          if (propsBinding === 'props' || /^[a-z]/.test(propsBinding)) {
+            // Walk forward and find the component body extent (braces).
+            const startIdx = compMatch.index + compMatch[0].length;
+            let braceDepth = 1;
+            let bodyEnd = startIdx;
+            for (let i = startIdx; i < code.length && braceDepth > 0; i++) {
+              if (code[i] === '{') braceDepth++;
+              if (code[i] === '}') braceDepth--;
+              bodyEnd = i;
+            }
+            const body = code.slice(startIdx, bodyEnd);
+            // Find: const|let { ... } = props (the actual binding name).
+            const destructPattern = new RegExp(
+              `(?:const|let)\\s*\\{([^}]+)\\}\\s*=\\s*${propsBinding}\\b`,
+              'g'
+            );
+            let dm;
+            while ((dm = destructPattern.exec(body)) !== null) {
+              const fields = dm[1].split(',').map(s => s.trim().split(/[:=]/)[0].trim()).filter(Boolean);
+              const line = code.slice(0, startIdx + dm.index).split('\n').length;
+              issues.push({
+                severity: 'warning',
+                code: 'ERR_DESTRUCTURED_PROPS',
+                message: `Destructuring '${propsBinding}' in the component body snapshots props and loses reactivity. Components run ONCE — '${propsBinding}.${fields[0] || 'foo'}' tracks via the props proxy, but '{ ${fields.join(', ')} } = ${propsBinding}' does not.`,
+                line,
+                suggestedFix: `Read props directly inside JSX or effects: \`${propsBinding}.${fields[0] || 'foo'}\` — or wrap each in an accessor: const ${fields[0] || 'foo'} = () => ${propsBinding}.${fields[0] || 'foo'}.`,
+              });
+            }
+          }
+        }
+      }
+      return issues;
+    },
+  },
+  {
+    // -----------------------------------------------------------------------
+    // module-scope-signal-missing-name
+    //
+    // Module-scope signals are global state. Without a debug name (second arg
+    // to signal()), they appear as `signal_42` in devtools and what_signals,
+    // making cross-tool debugging much harder. This is a hint, not an error.
+    // -----------------------------------------------------------------------
+    id: 'module-scope-signal-missing-name',
+    code: 'HINT_SIGNAL_MISSING_NAME',
+    severity: 'info',
+    test(code) {
+      const issues = [];
+      // Look for signal/computed declarations at the top level — i.e., not
+      // indented (or only minimally) and not inside a function. A simple but
+      // reliable heuristic: lines that match `^(?:export\s+)?(?:const|let)
+      // \s+\w+\s*=\s*(signal|computed)\s*\(` AND the opening call has only
+      // one argument (no comma at the same paren depth before the close).
+      const lines = code.split('\n');
+      const declRe = /^(?:export\s+)?(?:const|let)\s+(\w+)\s*=\s*(signal|computed)\s*\(/;
+      // Track simple brace depth so we skip signals declared inside a function.
+      let depth = 0;
+      for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        // Pre-line depth determines whether we're at module scope.
+        const wasModuleScope = depth === 0;
+        // Update depth after — we want to evaluate the line at its starting scope.
+        for (let j = 0; j < line.length; j++) {
+          if (line[j] === '{') depth++;
+          else if (line[j] === '}') depth = Math.max(0, depth - 1);
+        }
+        if (!wasModuleScope) continue;
+        const m = line.match(declRe);
+        if (!m) continue;
+        const sigName = m[1];
+        const kind = m[2];
+        // Reconstruct the full call args by walking parens forward.
+        const callStart = m.index + m[0].length; // position right after the opening '('
+        // The match is on `line` only; rebuild full call across lines.
+        let scan = code.indexOf(line, 0);
+        // Find absolute position of the opening paren of signal/computed(...)
+        const lineStart = code.split('\n').slice(0, i).join('\n').length + (i > 0 ? 1 : 0);
+        const openIdx = lineStart + callStart - 1; // points at the '('
+        // Walk to matching close.
+        let d = 1, j = openIdx + 1, commasAtDepth1 = 0;
+        for (; j < code.length && d > 0; j++) {
+          const ch = code[j];
+          if (ch === '(') d++;
+          else if (ch === ')') d--;
+          else if (ch === ',' && d === 1) commasAtDepth1++;
+          // Treat string literals naively — bail out of this check if we see a
+          // backtick, since template literals make this regex unreliable.
+        }
+        // For signal(), only one arg means no debug name.
+        // For computed(), arity is always 1 — skip; debug name is via .debugName?
+        if (kind === 'signal' && commasAtDepth1 === 0) {
+          issues.push({
+            severity: 'info',
+            code: 'HINT_SIGNAL_MISSING_NAME',
+            message: `Module-scope signal '${sigName}' has no debug name. It will appear as 'signal_N' in devtools and what_signals — agents and humans both find it harder to trace.`,
+            line: i + 1,
+            suggestedFix: `Add a debug name as the second argument: signal(<initial>, '${sigName}').`,
+          });
+        }
+        void scan;
+      }
+      return issues;
+    },
+  },
 ];
 
 // --- Scaffold Templates ---
@@ -641,7 +771,7 @@ export function registerAgentTools(server, bridge) {
     'Static analysis for What Framework code. Pass a code snippet, get back structured issues with fix suggestions. Works offline — no browser connection needed.',
     {
       code: z.string().describe('The What Framework code snippet to analyze'),
-      rules: z.array(z.string()).optional().describe('Specific rule IDs to run (default: all). Options: missing-signal-read, innerhtml-without-html, effect-writes-read-signal, missing-cleanup, signal-write-in-render, missing-key-in-for, prefer-computed-over-effect'),
+      rules: z.array(z.string()).optional().describe('Specific rule IDs to run (default: all). Options: missing-signal-read, innerhtml-without-html, effect-writes-read-signal, missing-cleanup, signal-write-in-render, missing-key-in-for, prefer-computed-over-effect, destructured-props-lose-reactivity, module-scope-signal-missing-name'),
     },
     async ({ code, rules: ruleFilter }) => {
       let rulesToRun = LINT_RULES;
@@ -896,7 +1026,13 @@ export function registerAgentTools(server, bridge) {
         ? `Performance concerns: ${issues.join('; ')}.`
         : `Healthy. ${signals.length} signals, ${effects.length} effects, ${components.length} components. ${memoryStr} estimated.`;
 
-      return ok({
+      // Suppress noisy "every signal has 1 subscriber" output — agents would
+      // chase it as a signal. Only emit largestSubscribers when at least one
+      // signal has 2+ subscribers worth investigating.
+      const maxSubs = largestSubscribers.length > 0
+        ? largestSubscribers[0].subscriberCount
+        : 0;
+      const result = {
         summary,
         counts: {
           signals: signals.length,
@@ -904,7 +1040,6 @@ export function registerAgentTools(server, bridge) {
           components: components.length,
         },
         hotEffects,
-        largestSubscribers,
         eventRate,
         memoryEstimate: memoryStr,
         memoryBytes: totalEstimate,
@@ -914,7 +1049,9 @@ export function registerAgentTools(server, bridge) {
           'Consider using batch() to group signal writes.',
           'Use computed() for derived values instead of effects.',
         ] : [],
-      });
+      };
+      if (maxSubs >= 2) result.largestSubscribers = largestSubscribers;
+      return ok(result);
     }
   );
 
@@ -996,4 +1133,152 @@ export function registerAgentTools(server, bridge) {
       });
     }
   );
+
+  // -----------------------------------------------------------------------
+  // Tool 6 — what_record_window
+  //
+  // Opens a sampling window (default 1s, max 30s), captures which effects
+  // re-ran during that window, and returns a ranked list — most-fired first.
+  //
+  // Differs from `what_perf` (cumulative runCount since boot) and from
+  // `what_watch` (raw event log). This one is the one-call "which effects
+  // re-ran during this action?" answer, which is what you want when
+  // profiling a single user interaction (drag-drop, button click, route
+  // change). Pair with `what_set_signal` or a user-driven action to scope
+  // the recording.
+  // -----------------------------------------------------------------------
+
+  server.tool(
+    'what_record_window',
+    'Sample which effects re-ran during a time window. Captures runCount before and after a configurable duration, then returns a ranked delta. Use this to identify which effects fire during a specific action (e.g., a drag, a click, or a route change). Default 1000ms.',
+    {
+      duration: z.number().optional().default(1000).describe('Sampling window in ms (default: 1000, max: 30000, min: 50)'),
+      topN: z.number().optional().default(20).describe('Maximum number of effects to return (default: 20)'),
+      includeZero: z.boolean().optional().default(false).describe('Include effects that did not re-run (default: false — only changed effects)'),
+    },
+    async ({ duration, topN, includeZero }) => {
+      if (!bridge.isConnected()) return noConnection('what_record_window');
+
+      const ms = Math.min(Math.max(duration ?? 1000, 50), 30000);
+      const limit = Math.min(Math.max(topN ?? 20, 1), 200);
+
+      // ---- Take baseline ----
+      let baseline;
+      try {
+        baseline = await (bridge.refreshSnapshot ? bridge.refreshSnapshot() : bridge.getSnapshot());
+      } catch {
+        baseline = bridge.getSnapshot();
+      }
+      if (!baseline) {
+        return errorResponse('No snapshot available for baseline.', [
+          'Refresh the browser page so the devtools client registers its state.',
+        ]);
+      }
+
+      const baselineRunCounts = new Map();
+      const baselineEffectMeta = new Map();
+      for (const e of baseline.effects || []) {
+        baselineRunCounts.set(e.id, e.runCount || 0);
+        baselineEffectMeta.set(e.id, {
+          id: e.id,
+          name: e.name || `effect_${e.id}`,
+          componentId: e.componentId,
+          depCount: (e.depSignalIds || e.deps || []).length,
+        });
+      }
+      const baselineEventCount = bridge.getEvents
+        ? bridge.getEvents(Date.now() - 1).length
+        : 0;
+      const startTs = Date.now();
+
+      // ---- Wait for the window ----
+      await new Promise((resolve) => setTimeout(resolve, ms));
+
+      // ---- Take post-window snapshot ----
+      let after;
+      try {
+        after = await (bridge.refreshSnapshot ? bridge.refreshSnapshot() : bridge.getSnapshot());
+      } catch {
+        after = bridge.getSnapshot();
+      }
+      if (!after) {
+        return errorResponse('No snapshot available after the recording window.', [
+          'The browser may have lost connection mid-recording.',
+        ]);
+      }
+
+      // ---- Compute delta ----
+      const ranked = [];
+      const newEffects = [];
+      const seen = new Set();
+      for (const e of after.effects || []) {
+        seen.add(e.id);
+        const before = baselineRunCounts.get(e.id);
+        const nowCount = e.runCount || 0;
+        if (before === undefined) {
+          // Effect was created during the window
+          newEffects.push({
+            id: e.id,
+            name: e.name || `effect_${e.id}`,
+            componentId: e.componentId,
+            runCount: nowCount,
+            depCount: (e.depSignalIds || e.deps || []).length,
+          });
+          continue;
+        }
+        const delta = nowCount - before;
+        if (delta > 0 || includeZero) {
+          ranked.push({
+            id: e.id,
+            name: e.name || baselineEffectMeta.get(e.id)?.name || `effect_${e.id}`,
+            componentId: e.componentId ?? baselineEffectMeta.get(e.id)?.componentId,
+            runs: delta,
+            totalRuns: nowCount,
+            depCount: (e.depSignalIds || e.deps || []).length,
+          });
+        }
+      }
+      const disposedDuring = [];
+      for (const [id, meta] of baselineEffectMeta) {
+        if (!seen.has(id)) disposedDuring.push(meta);
+      }
+
+      ranked.sort((a, b) => b.runs - a.runs);
+      const top = ranked.slice(0, limit);
+
+      const totalRuns = ranked.reduce((sum, e) => sum + e.runs, 0);
+      const distinctEffects = ranked.length;
+      const eventsDuring = bridge.getEvents
+        ? bridge.getEvents(startTs).length
+        : null;
+
+      const summary = totalRuns === 0
+        ? `No effects re-ran during the ${ms}ms window. App is idle (or no reactive state changed).`
+        : `${totalRuns} effect run${totalRuns !== 1 ? 's' : ''} across ${distinctEffects} distinct effect${distinctEffects !== 1 ? 's' : ''} in ${ms}ms.`;
+
+      const nextSteps = [];
+      if (top.length > 0 && top[0].runs >= 10) {
+        nextSteps.push(`Hot effect "${top[0].name}" ran ${top[0].runs} times — inspect with what_dependency_graph({effectId: ${top[0].id}, direction: "upstream"}).`);
+      }
+      if (newEffects.length > 5) {
+        nextSteps.push(`${newEffects.length} effects were created during the window — likely a re-mount cycle. Check what_diff_snapshot for component churn.`);
+      }
+      if (disposedDuring.length > 0 && newEffects.length > 0) {
+        nextSteps.push(`${disposedDuring.length} effects were disposed and ${newEffects.length} were created — component tree is being torn down and rebuilt.`);
+      }
+
+      return ok({
+        summary,
+        windowMs: ms,
+        totalRuns,
+        distinctEffects,
+        topEffects: top,
+        newEffectsCount: newEffects.length,
+        newEffects: newEffects.slice(0, limit),
+        disposedCount: disposedDuring.length,
+        eventsDuring,
+        nextSteps,
+      });
+    }
+  );
 }

package/src/tools-extended.js

@@ -70,6 +70,37 @@ export function registerExtendedTools(server, bridge) {
     };
   }
 
+  // ---------------------------------------------------------------------------
+  // Helper: framework-wide signal value preview policy.
+  //
+  // Goal: agents see the SAME shape across every tool that surfaces a signal
+  // value (what_signals, what_dependency_graph, what_signal_trace, …).
+  //
+  // Policy:
+  //   - Primitives (number/boolean/null/undefined): return as-is.
+  //   - Strings: full when small, truncated with ellipsis when long.
+  //   - Arrays/objects: full structure when its JSON stringification fits
+  //     under PREVIEW_LIMIT chars; otherwise return a truncated JSON string.
+  //
+  // Threshold chosen to fit "small list of small items" while protecting
+  // dep-graph topology output from token blow-ups on huge structures.
+  // ---------------------------------------------------------------------------
+  const PREVIEW_LIMIT = 100;
+  function previewSignalValue(raw) {
+    if (raw == null) return raw;
+    const t = typeof raw;
+    if (t === 'number' || t === 'boolean') return raw;
+    if (t === 'string') return raw.length > PREVIEW_LIMIT ? raw.slice(0, PREVIEW_LIMIT) + '…' : raw;
+    if (t === 'object') {
+      let json;
+      try { json = JSON.stringify(raw); } catch { return String(raw); }
+      if (json == null) return String(raw);
+      if (json.length <= PREVIEW_LIMIT) return raw;
+      return json.slice(0, PREVIEW_LIMIT) + '…';
+    }
+    return String(raw);
+  }
+
   // ---------------------------------------------------------------------------
   // Helper: get a fresh or cached snapshot
   // ---------------------------------------------------------------------------
@@ -353,16 +384,10 @@ export function registerExtendedTools(server, bridge) {
         const id = Number(idStr);
         if (type === 'signal') {
           const s = signalMap.get(id);
-          // Truncate values to avoid token waste — graph topology is what matters
-          const raw = s?.value;
-          let value;
-          if (raw == null) value = raw;
-          else if (typeof raw === 'string') value = raw.length > 80 ? raw.slice(0, 80) + '…' : raw;
-          else if (Array.isArray(raw)) value = `Array(${raw.length})`;
-          else if (typeof raw === 'object') {
-            const json = JSON.stringify(raw);
-            value = json.length > 80 ? json.slice(0, 80) + '…' : raw;
-          } else value = raw;
+          // Use the framework-wide value-preview policy — full values when
+          // small, truncated JSON when large. Keeps output consistent with
+          // what_signals so agents see the same shape across tools.
+          const value = previewSignalValue(s?.value);
           nodes.push({ type: 'signal', id, name: s?.name || `signal_${id}`, value });
         } else {
           const e = effectMap.get(id);
@@ -403,12 +428,15 @@ export function registerExtendedTools(server, bridge) {
     async ({ code, timeout }) => {
       // Allow safe read-only property access without the unsafe flag
       const trimmed = (code || '').trim();
-      const isSafeRead = /^[\w.[\]'"]+$/.test(trimmed) && !trimmed.includes('=') ||
-        /^document\.(title|URL|readyState|visibilityState|characterSet|contentType)$/.test(trimmed) ||
-        /^window\.(innerWidth|innerHeight|devicePixelRatio|outerWidth|outerHeight)$/.test(trimmed) ||
-        /^navigator\.(userAgent|language|platform|onLine|hardwareConcurrency)$/.test(trimmed) ||
-        /^location\.(href|hostname|pathname|protocol|port|origin)$/.test(trimmed) ||
-        /^screen\.(width|height|availWidth|availHeight|colorDepth)$/.test(trimmed);
+      // Strict safe-read: only allow dotted property access on known safe globals.
+      // Each segment must be a simple identifier (no brackets, quotes, or calls).
+      const SAFE_GLOBALS = new Set(['document', 'window', 'navigator', 'location', 'screen', 'performance', 'console']);
+      const segments = trimmed.split('.');
+      const isSimpleIdent = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/;
+      const PROTO_DENYLIST = new Set(['constructor', 'prototype', '__proto__']);
+      const isSafeRead = segments.length >= 2 &&
+        SAFE_GLOBALS.has(segments[0]) &&
+        segments.every(s => isSimpleIdent.test(s) && !PROTO_DENYLIST.has(s));
 
       if (!unsafeEvalEnabled && !isSafeRead) {
         return errorResponse(
@@ -833,8 +861,19 @@ export function registerExtendedTools(server, bridge) {
     async ({ path, replace }) => {
       if (!bridge.isConnected()) return noConnection('what_navigate');
 
+      // Validate URL — reject dangerous protocols
+      const trimmedPath = path.trim();
+      const normalized = trimmedPath.replace(/[\s\x00-\x1f]/g, '').toLowerCase();
+      const isRelative = /^[/.#?]/.test(trimmedPath) || !trimmedPath.includes(':');
+      if (!isRelative && !/^https?:/.test(normalized)) {
+        return errorResponse(`Blocked navigation to unsafe URL: "${path}"`, [
+          'Only relative paths (/foo, ./bar, #hash, ?query) and http(s) URLs are allowed.',
+          'javascript:, data:, and vbscript: URLs are rejected for security.',
+        ]);
+      }
+
       try {
-        const result = await bridge.sendCommand('navigate', { path, replace });
+        const result = await bridge.sendCommand('navigate', { path: trimmedPath, replace });
         if (result.error) {
           return errorResponse(result.error, [
             'Check that the path is valid.',
@@ -860,7 +899,7 @@ export function registerExtendedTools(server, bridge) {
 
   server.tool(
     'what_explain',
-    'Get a complete picture of a component: its signals with values, effects with deps and run counts, rendered DOM, and any errors. The "tell me everything about this component" tool.',
+    'Get a complete picture of a component: its signals with values, effects with deps and run counts, rendered DOM, and any errors. The "tell me everything about this component" tool. Component IDs are ephemeral — they change on mount/unmount, so re-query what_components after any signal write that may have remounted the tree.',
     {
       componentId: z.number().describe('Component ID to explain (from what_components)'),
       includeDOM: z.boolean().optional().default(true).describe('Include rendered DOM output (default: true)'),
@@ -937,8 +976,9 @@ export function registerExtendedTools(server, bridge) {
     {
       signalId: z.number().describe('Signal ID to trace (from what_signals)'),
       depth: z.number().optional().default(2).describe('Causal chain depth — how many levels of effect->signal->effect to trace (default: 2)'),
+      auto_watch_ms: z.number().optional().default(500).describe('If no recent writes were captured, briefly listen for events for this many ms before returning (default: 500, set to 0 to disable).'),
     },
-    async ({ signalId, depth }) => {
+    async ({ signalId, depth, auto_watch_ms }) => {
       const { snapshot, err } = await freshSnapshot('what_signal_trace');
       if (err) return err;
 
@@ -959,6 +999,21 @@ export function registerExtendedTools(server, bridge) {
         if (writers.error) writers = { recentWrites: [], totalWrites: 0, note: writers.error };
       } catch {}
 
+      // Auto-arm what_watch when no writes have been captured yet. The
+      // signal-writer ring buffer is populated by initEventTracking, which
+      // runs on first extended command. If the caller hits what_signal_trace
+      // first, the buffer is empty even though the browser is producing
+      // events. Listen briefly so the user gets a result on the first try
+      // instead of having to manually chain what_watch -> what_signal_trace.
+      const watchMs = Math.min(Math.max(Number(auto_watch_ms) || 0, 0), 5000);
+      if (watchMs > 0 && (!writers.recentWrites || writers.recentWrites.length === 0)) {
+        await new Promise(r => setTimeout(r, watchMs));
+        try {
+          const refetched = await bridge.sendCommand('get-signal-writers', { signalId }, 5000);
+          if (refetched && !refetched.error) writers = refetched;
+        } catch {}
+      }
+
       // Build causal chain
       // For each writer effect, find what signals it depends on
       const chain = [];

package/src/tools.js

@@ -126,6 +126,7 @@ export function registerTools(server, bridge) {
           { name: 'what_signal_trace', desc: 'Why did a signal change? Causal chain.' },
           { name: 'what_dependency_graph', desc: 'Reactive dependency graph' },
           { name: 'what_watch', desc: 'Observe events over a time window' },
+          { name: 'what_record_window', desc: 'Rank effects that re-ran during a recording window — what fired for this action?' },
           { name: 'what_set_signal', desc: 'Change a signal value in the live app' },
           { name: 'what_lint', desc: 'Static analysis for code (no browser needed)' },
           { name: 'what_scaffold', desc: 'Generate boilerplate (no browser needed)' },
@@ -285,7 +286,7 @@ export function registerTools(server, bridge) {
 
   server.tool(
     'what_components',
-    'List all mounted What Framework components',
+    'List all mounted What Framework components. Component IDs are ephemeral — they change on mount/unmount (view switches, conditional rendering, filters). Re-query this tool after any operation that may have remounted before using returned IDs.',
     {
       filter: z.string().optional().describe('Regex pattern to filter component names'),
     },
@@ -476,19 +477,28 @@ export function registerTools(server, bridge) {
       if (!bridge.isConnected()) return noConnection('what_errors');
       let errors = bridge.getErrors(since);
 
+      // Build a name->component lookup so we can attribute errors to a
+      // mounted component when the stack references one. Re-fetched each call
+      // because component IDs are ephemeral (mount/unmount cycles).
+      const knownComponents = (bridge.getSnapshot()?.components || [])
+        .map(c => ({ id: c.id, name: c.name }))
+        .filter(c => c.name && /^[A-Z]/.test(c.name));
+
       // Classify each error with structured codes and suggestions
       const classified = errors.map((err, idx) => {
         const msg = err.message || err.error || '';
+        const parsed = parseStack(err.stack, knownComponents);
         let classification = {
           id: `err_${idx}`,
           severity: 'error',
           code: 'ERR_RUNTIME',
           message: msg,
           timestamp: err.timestamp,
-          file: err.file || null,
-          line: err.line || null,
-          component: err.component || null,
-          suggestion: 'Check the stack trace and component context for more details.',
+          file: err.file || parsed.file || null,
+          line: err.line || parsed.line || null,
+          column: parsed.column || null,
+          component: err.component || parsed.component || null,
+          suggestion: inferSuggestion(msg),
           codeExample: null,
         };
 
@@ -612,12 +622,14 @@ export function registerTools(server, bridge) {
     'Set a signal value in the running app. Returns previous and new values.',
     {
       signalId: z.number().describe('The signal ID to update (from what_signals)'),
-      value: z.any().describe('The new value to set (JSON-compatible)'),
+      value: z.any().describe('The new value to set (JSON-compatible). Note: string values that look like numbers/booleans/JSON are auto-parsed (e.g. "42" becomes 42). Set rawString: true to keep the literal string.'),
+      rawString: z.boolean().optional().describe('When true, skip auto-coercion and write the value as-is (useful for string values like "42" that would otherwise be parsed as numbers)'),
     },
-    async ({ signalId, value }) => {
+    async ({ signalId, value, rawString }) => {
       if (!bridge.isConnected()) return noConnection('what_set_signal');
       try {
-        const result = await bridge.sendCommand('set-signal', { signalId, value });
+        const parsedValue = rawString ? value : coerceJsonValue(value);
+        const result = await bridge.sendCommand('set-signal', { signalId, value: parsedValue });
         if (result.error) return error(result.error);
 
         const summary = `Signal ${signalId} updated. Previous: ${JSON.stringify(result.previousValue)}, New: ${JSON.stringify(result.newValue ?? value)}`;
@@ -757,3 +769,147 @@ function error(message) {
     isError: true,
   };
 }
+
+/**
+ * Parse a JS error stack trace and extract:
+ *   - file/line/column of the topmost USER frame (skipping framework internals)
+ *   - component name matched against the live components registry
+ *
+ * Stack formats vary by engine. We handle V8/Chrome (the only target since
+ * the app runs in a browser):
+ *   "    at FunctionName (file.js:12:34)"
+ *   "    at file.js:12:34"
+ *
+ * Frames are skipped if they reference framework internals (what-framework,
+ * what-core, what-devtools, node_modules, vite/, /@id/, internal anonymous).
+ */
+function parseStack(stack, knownComponents = []) {
+  const out = { file: null, line: null, column: null, component: null };
+  if (!stack || typeof stack !== 'string') return out;
+
+  const lines = stack.split('\n');
+  const skipPatterns = [
+    /what-framework/,
+    /what-core/,
+    /what-devtools/,
+    /node_modules/,
+    /\/vite\//,
+    /\/@id\//,
+    /<anonymous>/,
+    /^Error[: ]/,
+  ];
+
+  const knownNames = new Set(knownComponents.map(c => c.name));
+
+  for (const rawLine of lines) {
+    const line = rawLine.trim();
+    if (!line.startsWith('at ')) continue;
+
+    // Try to match: at FunctionName (path:line:col)  OR  at path:line:col
+    const withFn = line.match(/^at\s+(.+?)\s+\((.+):(\d+):(\d+)\)$/);
+    const noFn = line.match(/^at\s+(.+):(\d+):(\d+)$/);
+
+    const fnName = withFn ? withFn[1] : null;
+    const path = withFn ? withFn[2] : noFn ? noFn[1] : null;
+    const ln = withFn ? Number(withFn[3]) : noFn ? Number(noFn[2]) : null;
+    const col = withFn ? Number(withFn[4]) : noFn ? Number(noFn[3]) : null;
+
+    if (!path) continue;
+
+    // Match component name from function frame against known components.
+    // Pulls out just the bare identifier, e.g. "TaskList" from "Object.TaskList"
+    // or "TaskList.handleClick".
+    if (!out.component && fnName) {
+      const tokens = fnName.split(/[.\s]/);
+      for (const tok of tokens) {
+        if (knownNames.has(tok)) { out.component = tok; break; }
+      }
+    }
+
+    // First non-skipped frame wins for file/line/column.
+    if (out.file == null) {
+      const skip = skipPatterns.some(re => re.test(path));
+      if (!skip) {
+        out.file = path;
+        out.line = ln;
+        out.column = col;
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * Infer a more specific suggestion from a runtime error message before any
+ * pattern-specific overrides apply. Catches common JS mistakes that the
+ * What-Framework-specific pattern matchers below don't cover.
+ */
+function inferSuggestion(msg) {
+  if (!msg) return 'Check the stack trace and component context for more details.';
+  // ReferenceError
+  if (/is not defined$/.test(msg)) {
+    const m = msg.match(/^(\w+) is not defined/);
+    const name = m?.[1] || 'identifier';
+    return `'${name}' is referenced before it is declared/imported. Check for a missing import or a typo. If it's a hook value, ensure the binding is in scope.`;
+  }
+  // TypeError: ... is not a function
+  if (/is not a function$/.test(msg)) {
+    const m = msg.match(/^(.+?) is not a function/);
+    const name = m?.[1] || 'value';
+    return `'${name}' is not callable. Common causes: a signal-returning value used like a non-signal, an undefined import, or a typo in the name. If '${name}' is a signal, you must call it with () to read its value.`;
+  }
+  // Cannot read properties of undefined/null
+  if (/Cannot read propert(?:y|ies) of (undefined|null)/.test(msg)) {
+    const m = msg.match(/Cannot read propert(?:y|ies) of (undefined|null) \(reading '(.+?)'\)/);
+    if (m) {
+      return `Tried to read '.${m[2]}' on ${m[1]}. Guard the access (e.g. \`value?.${m[2]}\`), or ensure the signal/prop has been initialised before this code runs.`;
+    }
+    return 'Tried to access a property on undefined/null. Add an optional-chain (`?.`) or null-check before the access.';
+  }
+  // Maximum call stack
+  if (/Maximum call stack/.test(msg)) {
+    return 'Infinite recursion detected. Usually an effect writes to a signal it reads — wrap the read in untrack(), or move the write into a different effect.';
+  }
+  // Assignment to constant variable
+  if (/Assignment to constant variable/.test(msg)) {
+    return 'Tried to reassign a `const`. Signals are constants — to update them, call them as functions: `mySignal(newValue)`, not `mySignal = newValue`.';
+  }
+  return 'Check the stack trace and component context for more details.';
+}
+
+/**
+ * Coerce a possibly-stringified JSON value into its native form.
+ *
+ * Agents and some MCP clients pass complex values as JSON-encoded strings
+ * (e.g. `'[{"id":1}]'` instead of `[{id: 1}]`). Without this, the receiver
+ * would store the literal string and downstream iteration/rendering breaks
+ * (mapArray iterates the string's chars, signals hold "42" instead of 42).
+ *
+ * Heuristic: only parse strings whose first non-whitespace char is one of
+ * `{ [ " t f n -` or 0-9. We intentionally do NOT parse arbitrary string
+ * content like "hello" because users may legitimately want to set a string
+ * value. Quoted JSON strings like `'"hello"'` and `'true'` etc are detected
+ * by JSON.parse succeeding on them; if the parse changes the type
+ * meaningfully (object/array/boolean/number/null), we accept it. For plain
+ * string content (`hello`), JSON.parse fails and we keep the original.
+ */
+function coerceJsonValue(value) {
+  if (typeof value !== 'string') return value;
+  const trimmed = value.trim();
+  if (trimmed.length === 0) return value;
+  const first = trimmed[0];
+  const looksLikeJson =
+    first === '{' || first === '[' || first === '"' ||
+    first === 't' || first === 'f' || first === 'n' ||
+    first === '-' || (first >= '0' && first <= '9');
+  if (!looksLikeJson) return value;
+  try {
+    const parsed = JSON.parse(trimmed);
+    // Only accept the parse if it changes the type to a non-string — keeps
+    // user-supplied strings intact while catching double-stringified payloads.
+    if (typeof parsed !== 'string') return parsed;
+    return value;
+  } catch {
+    return value;
+  }
+}

package/src/vite-plugin.js

@@ -32,23 +32,56 @@ function resolveToken(explicitToken) {
   return '';
 }
 
+// Virtual module id served via Vite's `\0` convention.
+// Resolved IDs starting with `\0` are hidden from the file system and recognised
+// by Vite as plugin-owned modules. We expose them to the browser via the
+// `/@id/<resolved-id>` URL convention so `<script src>` can request them.
+const VIRTUAL_BOOTSTRAP_ID = 'virtual:what-devtools-mcp/bootstrap';
+const RESOLVED_BOOTSTRAP_ID = '\0' + VIRTUAL_BOOTSTRAP_ID;
+// Vite encodes `\0` as `__x00__` in `/@id/` URLs — stable since Vite 2 (2021).
+const BROWSER_BOOTSTRAP_URL = '/@id/__x00__' + VIRTUAL_BOOTSTRAP_ID;
+
 export default function whatDevToolsMCP({ port = 9229, token = '' } = {}) {
   return {
     name: 'what-devtools-mcp',
     apply: 'serve',
-    transformIndexHtml(html) {
+
+    // Resolve the virtual module so Vite knows we own it.
+    resolveId(id) {
+      if (id === VIRTUAL_BOOTSTRAP_ID || id === RESOLVED_BOOTSTRAP_ID) {
+        return RESOLVED_BOOTSTRAP_ID;
+      }
+      return null;
+    },
+
+    // Load the bootstrap source. Because this is a real JS module that goes
+    // through Vite's transform pipeline, bare specifiers like `what-core` get
+    // properly rewritten to dev-server URLs — unlike inline <script type=module>
+    // tags injected via transformIndexHtml, which Vite does not transform.
+    load(id) {
+      if (id !== RESOLVED_BOOTSTRAP_ID) return null;
       const tokenValue = resolveToken(token);
-      return html.replace(
-        '</body>',
-        `<script type="module">
-import * as core from 'what-core';
-import { installDevTools } from 'what-devtools';
-import { connectDevToolsMCP } from 'what-devtools-mcp/client';
-installDevTools(core);
-connectDevToolsMCP({ port: ${port}, token: ${JSON.stringify(tokenValue)} });
-</script>
-</body>`
-      );
+      return [
+        `import * as core from 'what-core';`,
+        `import { installDevTools } from 'what-devtools';`,
+        `import { connectDevToolsMCP } from 'what-devtools-mcp/client';`,
+        `installDevTools(core);`,
+        `connectDevToolsMCP({ port: ${port}, token: ${JSON.stringify(tokenValue)} });`,
+      ].join('\n');
+    },
+
+    transformIndexHtml() {
+      // Inject a <script src> that points at the virtual module. The browser
+      // fetches `/@id/__x00__virtual:what-devtools-mcp/bootstrap`, Vite serves
+      // the transformed bootstrap (bare specifiers resolved), and everything
+      // loads correctly without "Failed to resolve module specifier" errors.
+      return [
+        {
+          tag: 'script',
+          attrs: { type: 'module', src: BROWSER_BOOTSTRAP_URL },
+          injectTo: 'body',
+        },
+      ];
     },
   };
 }