@agent-scope/cli 1.6.0 → 1.8.0

package/dist/cli.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 
 // src/program.ts
-import { readFileSync as readFileSync3 } from "fs";
+import { readFileSync as readFileSync4 } from "fs";
 import { generateTest, loadTrace } from "@agent-scope/playwright";
-import { Command as Command3 } from "commander";
+import { Command as Command5 } from "commander";
 
 // src/browser.ts
 import { writeFileSync } from "fs";
@@ -50,6 +50,125 @@ function writeReportToFile(report, outputPath, pretty) {
   writeFileSync(outputPath, json, "utf-8");
 }
 
+// src/instrument/renders.ts
+import { resolve as resolve2 } from "path";
+import { BrowserPool } from "@agent-scope/render";
+import { Command as Command2 } from "commander";
+
+// src/component-bundler.ts
+import { dirname } from "path";
+import * as esbuild from "esbuild";
+async function buildComponentHarness(filePath, componentName, props, viewportWidth, projectCss) {
+  const bundledScript = await bundleComponentToIIFE(filePath, componentName, props);
+  return wrapInHtml(bundledScript, viewportWidth, projectCss);
+}
+async function bundleComponentToIIFE(filePath, componentName, props) {
+  const propsJson = JSON.stringify(props).replace(/<\/script>/gi, "<\\/script>");
+  const wrapperCode = (
+    /* ts */
+    `
+import * as __scopeMod from ${JSON.stringify(filePath)};
+import { createRoot } from "react-dom/client";
+import { createElement } from "react";
+
+(function scopeRenderHarness() {
+  var Component =
+    __scopeMod["default"] ||
+    __scopeMod[${JSON.stringify(componentName)}] ||
+    (Object.values(__scopeMod).find(
+      function(v) { return typeof v === "function" && /^[A-Z]/.test(v.name || ""); }
+    ));
+
+  if (!Component) {
+    window.__SCOPE_RENDER_ERROR__ =
+      "No renderable component found. Checked: default, " +
+      ${JSON.stringify(componentName)} + ", and PascalCase named exports. " +
+      "Available exports: " + Object.keys(__scopeMod).join(", ");
+    window.__SCOPE_RENDER_COMPLETE__ = true;
+    return;
+  }
+
+  try {
+    var props = ${propsJson};
+    var rootEl = document.getElementById("scope-root");
+    if (!rootEl) {
+      window.__SCOPE_RENDER_ERROR__ = "#scope-root element not found";
+      window.__SCOPE_RENDER_COMPLETE__ = true;
+      return;
+    }
+    createRoot(rootEl).render(createElement(Component, props));
+    // Use requestAnimationFrame to let React flush the render
+    requestAnimationFrame(function() {
+      window.__SCOPE_RENDER_COMPLETE__ = true;
+    });
+  } catch (err) {
+    window.__SCOPE_RENDER_ERROR__ = err instanceof Error ? err.message : String(err);
+    window.__SCOPE_RENDER_COMPLETE__ = true;
+  }
+})();
+`
+  );
+  const result = await esbuild.build({
+    stdin: {
+      contents: wrapperCode,
+      // Resolve relative imports (within the component's dir)
+      resolveDir: dirname(filePath),
+      loader: "tsx",
+      sourcefile: "__scope_harness__.tsx"
+    },
+    bundle: true,
+    format: "iife",
+    write: false,
+    platform: "browser",
+    jsx: "automatic",
+    jsxImportSource: "react",
+    target: "es2020",
+    // Bundle everything — no externals
+    external: [],
+    define: {
+      "process.env.NODE_ENV": '"development"',
+      global: "globalThis"
+    },
+    logLevel: "silent",
+    // Suppress "React must be in scope" warnings from old JSX (we use automatic)
+    banner: {
+      js: "/* @agent-scope/cli component harness */"
+    }
+  });
+  if (result.errors.length > 0) {
+    const msg = result.errors.map((e) => `${e.text}${e.location ? ` (${e.location.file}:${e.location.line})` : ""}`).join("\n");
+    throw new Error(`esbuild failed to bundle component:
+${msg}`);
+  }
+  const outputFile = result.outputFiles?.[0];
+  if (outputFile === void 0 || outputFile.text.length === 0) {
+    throw new Error("esbuild produced no output");
+  }
+  return outputFile.text;
+}
+function wrapInHtml(bundledScript, viewportWidth, projectCss) {
+  const projectStyleBlock = projectCss != null && projectCss.length > 0 ? `<style id="scope-project-css">
+${projectCss.replace(/<\/style>/gi, "<\\/style>")}
+</style>` : "";
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=${viewportWidth}, initial-scale=1.0" />
+  <style>
+    *, *::before, *::after { box-sizing: border-box; }
+    html, body { margin: 0; padding: 0; background: #fff; font-family: system-ui, sans-serif; }
+    #scope-root { display: inline-block; min-width: 1px; min-height: 1px; }
+  </style>
+  ${projectStyleBlock}
+</head>
+<body>
+  <div id="scope-root" data-reactscope-root></div>
+  <script>${bundledScript}</script>
+</body>
+</html>`;
+}
+
 // src/manifest-commands.ts
 import { existsSync, mkdirSync, readFileSync, writeFileSync as writeFileSync2 } from "fs";
 import { resolve } from "path";
@@ -323,135 +442,6 @@ function createManifestCommand() {
   return manifestCmd;
 }
 
-// src/render-commands.ts
-import { mkdirSync as mkdirSync2, writeFileSync as writeFileSync3 } from "fs";
-import { resolve as resolve3 } from "path";
-import {
-  ALL_CONTEXT_IDS,
-  ALL_STRESS_IDS,
-  BrowserPool,
-  contextAxis,
-  RenderMatrix,
-  SatoriRenderer,
-  safeRender,
-  stressAxis
-} from "@agent-scope/render";
-import { Command as Command2 } from "commander";
-
-// src/component-bundler.ts
-import { dirname } from "path";
-import * as esbuild from "esbuild";
-async function buildComponentHarness(filePath, componentName, props, viewportWidth, projectCss) {
-  const bundledScript = await bundleComponentToIIFE(filePath, componentName, props);
-  return wrapInHtml(bundledScript, viewportWidth, projectCss);
-}
-async function bundleComponentToIIFE(filePath, componentName, props) {
-  const propsJson = JSON.stringify(props).replace(/<\/script>/gi, "<\\/script>");
-  const wrapperCode = (
-    /* ts */
-    `
-import * as __scopeMod from ${JSON.stringify(filePath)};
-import { createRoot } from "react-dom/client";
-import { createElement } from "react";
-
-(function scopeRenderHarness() {
-  var Component =
-    __scopeMod["default"] ||
-    __scopeMod[${JSON.stringify(componentName)}] ||
-    (Object.values(__scopeMod).find(
-      function(v) { return typeof v === "function" && /^[A-Z]/.test(v.name || ""); }
-    ));
-
-  if (!Component) {
-    window.__SCOPE_RENDER_ERROR__ =
-      "No renderable component found. Checked: default, " +
-      ${JSON.stringify(componentName)} + ", and PascalCase named exports. " +
-      "Available exports: " + Object.keys(__scopeMod).join(", ");
-    window.__SCOPE_RENDER_COMPLETE__ = true;
-    return;
-  }
-
-  try {
-    var props = ${propsJson};
-    var rootEl = document.getElementById("scope-root");
-    if (!rootEl) {
-      window.__SCOPE_RENDER_ERROR__ = "#scope-root element not found";
-      window.__SCOPE_RENDER_COMPLETE__ = true;
-      return;
-    }
-    createRoot(rootEl).render(createElement(Component, props));
-    // Use requestAnimationFrame to let React flush the render
-    requestAnimationFrame(function() {
-      window.__SCOPE_RENDER_COMPLETE__ = true;
-    });
-  } catch (err) {
-    window.__SCOPE_RENDER_ERROR__ = err instanceof Error ? err.message : String(err);
-    window.__SCOPE_RENDER_COMPLETE__ = true;
-  }
-})();
-`
-  );
-  const result = await esbuild.build({
-    stdin: {
-      contents: wrapperCode,
-      // Resolve relative imports (within the component's dir)
-      resolveDir: dirname(filePath),
-      loader: "tsx",
-      sourcefile: "__scope_harness__.tsx"
-    },
-    bundle: true,
-    format: "iife",
-    write: false,
-    platform: "browser",
-    jsx: "automatic",
-    jsxImportSource: "react",
-    target: "es2020",
-    // Bundle everything — no externals
-    external: [],
-    define: {
-      "process.env.NODE_ENV": '"development"',
-      global: "globalThis"
-    },
-    logLevel: "silent",
-    // Suppress "React must be in scope" warnings from old JSX (we use automatic)
-    banner: {
-      js: "/* @agent-scope/cli component harness */"
-    }
-  });
-  if (result.errors.length > 0) {
-    const msg = result.errors.map((e) => `${e.text}${e.location ? ` (${e.location.file}:${e.location.line})` : ""}`).join("\n");
-    throw new Error(`esbuild failed to bundle component:
-${msg}`);
-  }
-  const outputFile = result.outputFiles?.[0];
-  if (outputFile === void 0 || outputFile.text.length === 0) {
-    throw new Error("esbuild produced no output");
-  }
-  return outputFile.text;
-}
-function wrapInHtml(bundledScript, viewportWidth, projectCss) {
-  const projectStyleBlock = projectCss != null && projectCss.length > 0 ? `<style id="scope-project-css">
-${projectCss.replace(/<\/style>/gi, "<\\/style>")}
-</style>` : "";
-  return `<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8" />
-  <meta name="viewport" content="width=${viewportWidth}, initial-scale=1.0" />
-  <style>
-    *, *::before, *::after { box-sizing: border-box; }
-    html, body { margin: 0; padding: 0; background: #fff; font-family: system-ui, sans-serif; }
-    #scope-root { display: inline-block; min-width: 1px; min-height: 1px; }
-  </style>
-  ${projectStyleBlock}
-</head>
-<body>
-  <div id="scope-root" data-reactscope-root></div>
-  <script>${bundledScript}</script>
-</body>
-</html>`;
-}
-
 // src/render-formatter.ts
 function parseViewport(spec) {
   const lower = spec.toLowerCase();
@@ -568,54 +558,536 @@ function formatMatrixCsv(componentName, result) {
   return `${[headers.join(","), ...rows].join("\n")}
 `;
 }
-function renderProgressBar(completed, total, currentName, pct, barWidth = 20) {
-  const filled = Math.round(pct / 100 * barWidth);
-  const empty = barWidth - filled;
-  const bar = "=".repeat(Math.max(0, filled - 1)) + (filled > 0 ? ">" : "") + " ".repeat(empty);
-  const nameSlice = currentName.slice(0, 25).padEnd(25);
-  return `Rendering ${completed}/${total} ${nameSlice} [${bar}] ${pct}%`;
+function renderProgressBar(completed, total, currentName, pct, barWidth = 20) {
+  const filled = Math.round(pct / 100 * barWidth);
+  const empty = barWidth - filled;
+  const bar = "=".repeat(Math.max(0, filled - 1)) + (filled > 0 ? ">" : "") + " ".repeat(empty);
+  const nameSlice = currentName.slice(0, 25).padEnd(25);
+  return `Rendering ${completed}/${total} ${nameSlice} [${bar}] ${pct}%`;
+}
+function formatSummaryText(results, outputDir) {
+  const total = results.length;
+  const passed = results.filter((r) => r.success).length;
+  const failed = total - passed;
+  const successTimes = results.filter((r) => r.success).map((r) => r.renderTimeMs);
+  const avgMs = successTimes.length > 0 ? successTimes.reduce((a, b) => a + b, 0) / successTimes.length : 0;
+  const lines = [
+    "\u2500".repeat(60),
+    `Render Summary`,
+    "\u2500".repeat(60),
+    `  Total components : ${total}`,
+    `  Passed           : ${passed}`,
+    `  Failed           : ${failed}`,
+    `  Avg render time  : ${avgMs.toFixed(1)}ms`,
+    `  Output dir       : ${outputDir}`
+  ];
+  if (failed > 0) {
+    lines.push("", "  Failed components:");
+    for (const r of results) {
+      if (!r.success) {
+        lines.push(`    \u2717 ${r.name}: ${r.errorMessage ?? "unknown error"}`);
+      }
+    }
+  }
+  lines.push("\u2500".repeat(60));
+  return lines.join("\n");
+}
+function escapeHtml(str) {
+  return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#039;");
+}
+function csvEscape(value) {
+  if (value.includes(",") || value.includes('"') || value.includes("\n")) {
+    return `"${value.replace(/"/g, '""')}"`;
+  }
+  return value;
+}
+
+// src/instrument/renders.ts
+var MANIFEST_PATH2 = ".reactscope/manifest.json";
+function determineTrigger(event) {
+  if (event.forceUpdate) return "force_update";
+  if (event.stateChanged) return "state_change";
+  if (event.propsChanged) return "props_change";
+  if (event.contextChanged) return "context_change";
+  if (event.hookDepsChanged) return "hook_dependency";
+  return "parent_rerender";
+}
+function isWastedRender(event) {
+  return !event.propsChanged && !event.stateChanged && !event.contextChanged && !event.memoized;
+}
+function buildCausalityChains(rawEvents) {
+  const result = [];
+  const componentLastRender = /* @__PURE__ */ new Map();
+  for (const raw of rawEvents) {
+    const trigger = determineTrigger(raw);
+    const wasted = isWastedRender(raw);
+    const chain = [];
+    let current = raw;
+    const visited = /* @__PURE__ */ new Set();
+    while (true) {
+      if (visited.has(current.component)) break;
+      visited.add(current.component);
+      const currentTrigger = determineTrigger(current);
+      chain.unshift({
+        component: current.component,
+        trigger: currentTrigger,
+        propsChanged: current.propsChanged,
+        stateChanged: current.stateChanged,
+        contextChanged: current.contextChanged
+      });
+      if (currentTrigger !== "parent_rerender" || current.parentComponent === null) {
+        break;
+      }
+      const parentEvent = componentLastRender.get(current.parentComponent);
+      if (parentEvent === void 0) break;
+      current = parentEvent;
+    }
+    const rootCause = chain[0];
+    const cascadeRenders = rawEvents.filter((e) => {
+      if (rootCause === void 0) return false;
+      return e.component !== rootCause.component && !e.stateChanged && !e.propsChanged;
+    });
+    result.push({
+      component: raw.component,
+      renderIndex: raw.renderIndex,
+      trigger,
+      propsChanged: raw.propsChanged,
+      stateChanged: raw.stateChanged,
+      contextChanged: raw.contextChanged,
+      memoized: raw.memoized,
+      wasted,
+      chain,
+      cascade: {
+        totalRendersTriggered: cascadeRenders.length,
+        uniqueComponents: new Set(cascadeRenders.map((e) => e.component)).size,
+        unchangedPropRenders: cascadeRenders.filter((e) => !e.propsChanged).length
+      }
+    });
+    componentLastRender.set(raw.component, raw);
+  }
+  return result;
+}
+function applyHeuristicFlags(renders) {
+  const flags = [];
+  const byComponent = /* @__PURE__ */ new Map();
+  for (const r of renders) {
+    if (!byComponent.has(r.component)) byComponent.set(r.component, []);
+    byComponent.get(r.component).push(r);
+  }
+  for (const [component, events] of byComponent) {
+    const wastedCount = events.filter((e) => e.wasted).length;
+    const totalCount = events.length;
+    if (wastedCount > 0) {
+      flags.push({
+        id: "WASTED_RENDER",
+        severity: "warning",
+        component,
+        detail: `${wastedCount}/${totalCount} renders were wasted \u2014 unchanged props/state/context, not memoized`,
+        data: { wastedCount, totalCount, wastedRatio: wastedCount / totalCount }
+      });
+    }
+    for (const event of events) {
+      if (event.cascade.totalRendersTriggered > 50) {
+        flags.push({
+          id: "RENDER_CASCADE",
+          severity: "warning",
+          component,
+          detail: `State change in ${component} triggered ${event.cascade.totalRendersTriggered} downstream re-renders`,
+          data: {
+            totalRendersTriggered: event.cascade.totalRendersTriggered,
+            uniqueComponents: event.cascade.uniqueComponents,
+            unchangedPropRenders: event.cascade.unchangedPropRenders
+          }
+        });
+        break;
+      }
+    }
+  }
+  return flags;
+}
+function buildInstrumentationScript() {
+  return (
+    /* js */
+    `
+(function installScopeRenderInstrumentation() {
+  window.__SCOPE_RENDER_EVENTS__ = [];
+  window.__SCOPE_RENDER_INDEX__ = 0;
+
+  var hook = window.__REACT_DEVTOOLS_GLOBAL_HOOK__;
+  if (!hook) return;
+
+  var originalOnCommit = hook.onCommitFiberRoot;
+  var renderedComponents = new Map(); // componentName -> { lastProps, lastState }
+
+  function extractName(fiber) {
+    if (!fiber) return 'Unknown';
+    var type = fiber.type;
+    if (!type) return 'Unknown';
+    if (typeof type === 'string') return type; // host element
+    if (typeof type === 'function') return type.displayName || type.name || 'Anonymous';
+    if (type.displayName) return type.displayName;
+    if (type.render && typeof type.render === 'function') {
+      return type.render.displayName || type.render.name || 'Anonymous';
+    }
+    return 'Anonymous';
+  }
+
+  function isMemoized(fiber) {
+    // MemoComponent = 14, SimpleMemoComponent = 15
+    return fiber.tag === 14 || fiber.tag === 15;
+  }
+
+  function isComponent(fiber) {
+    // FunctionComponent=0, ClassComponent=1, MemoComponent=14, SimpleMemoComponent=15
+    return fiber.tag === 0 || fiber.tag === 1 || fiber.tag === 14 || fiber.tag === 15;
+  }
+
+  function shallowEqual(a, b) {
+    if (a === b) return true;
+    if (!a || !b) return a === b;
+    var keysA = Object.keys(a);
+    var keysB = Object.keys(b);
+    if (keysA.length !== keysB.length) return false;
+    for (var i = 0; i < keysA.length; i++) {
+      var k = keysA[i];
+      if (k === 'children') continue; // ignore children prop
+      if (a[k] !== b[k]) return false;
+    }
+    return true;
+  }
+
+  function getParentComponentName(fiber) {
+    var parent = fiber.return;
+    while (parent) {
+      if (isComponent(parent)) {
+        var name = extractName(parent);
+        if (name && name !== 'Unknown' && !/^[a-z]/.test(name)) return name;
+      }
+      parent = parent.return;
+    }
+    return null;
+  }
+
+  function walkCommit(fiber) {
+    if (!fiber) return;
+
+    if (isComponent(fiber)) {
+      var name = extractName(fiber);
+      if (name && name !== 'Unknown' && !/^[a-z]/.test(name)) {
+        var memoized = isMemoized(fiber);
+        var currentProps = fiber.memoizedProps || {};
+        var prev = renderedComponents.get(name);
+
+        var propsChanged = true;
+        var stateChanged = false;
+        var contextChanged = false;
+        var hookDepsChanged = false;
+        var forceUpdate = false;
+
+        if (prev) {
+          propsChanged = !shallowEqual(prev.lastProps, currentProps);
+        }
+
+        // State: check memoizedState chain
+        var memoizedState = fiber.memoizedState;
+        if (prev && prev.lastStateSerialized !== undefined) {
+          try {
+            var stateSig = JSON.stringify(memoizedState ? memoizedState.memoizedState : null);
+            stateChanged = stateSig !== prev.lastStateSerialized;
+          } catch (_) {
+            stateChanged = false;
+          }
+        }
+
+        // Context: use _debugHookTypes or check dependencies
+        var deps = fiber.dependencies;
+        if (deps && deps.firstContext) {
+          contextChanged = true; // conservative: context dep present = may have changed
+        }
+
+        var stateSig;
+        try {
+          stateSig = JSON.stringify(memoizedState ? memoizedState.memoizedState : null);
+        } catch (_) {
+          stateSig = null;
+        }
+
+        renderedComponents.set(name, {
+          lastProps: currentProps,
+          lastStateSerialized: stateSig,
+        });
+
+        var parentName = getParentComponentName(fiber);
+
+        window.__SCOPE_RENDER_EVENTS__.push({
+          component: name,
+          renderIndex: window.__SCOPE_RENDER_INDEX__++,
+          propsChanged: prev ? propsChanged : false,
+          stateChanged: stateChanged,
+          contextChanged: contextChanged,
+          memoized: memoized,
+          parentComponent: parentName,
+          hookDepsChanged: hookDepsChanged,
+          forceUpdate: forceUpdate,
+        });
+      }
+    }
+
+    walkCommit(fiber.child);
+    walkCommit(fiber.sibling);
+  }
+
+  hook.onCommitFiberRoot = function(rendererID, root, priorityLevel) {
+    if (typeof originalOnCommit === 'function') {
+      originalOnCommit.call(hook, rendererID, root, priorityLevel);
+    }
+    var wipRoot = root && root.current && root.current.alternate;
+    if (wipRoot) walkCommit(wipRoot);
+  };
+})();
+`
+  );
+}
+async function replayInteraction(page, steps) {
+  for (const step of steps) {
+    switch (step.action) {
+      case "click":
+        if (step.target !== void 0) {
+          await page.click(step.target, { timeout: 5e3 }).catch(() => {
+          });
+        }
+        break;
+      case "type":
+        if (step.target !== void 0 && step.text !== void 0) {
+          await page.fill(step.target, step.text, { timeout: 5e3 }).catch(async () => {
+            await page.type(step.target, step.text, { timeout: 5e3 }).catch(() => {
+            });
+          });
+        }
+        break;
+      case "hover":
+        if (step.target !== void 0) {
+          await page.hover(step.target, { timeout: 5e3 }).catch(() => {
+          });
+        }
+        break;
+      case "blur":
+        if (step.target !== void 0) {
+          await page.locator(step.target).blur({ timeout: 5e3 }).catch(() => {
+          });
+        }
+        break;
+      case "focus":
+        if (step.target !== void 0) {
+          await page.focus(step.target, { timeout: 5e3 }).catch(() => {
+          });
+        }
+        break;
+      case "scroll":
+        if (step.target !== void 0) {
+          await page.locator(step.target).scrollIntoViewIfNeeded({ timeout: 5e3 }).catch(() => {
+          });
+        }
+        break;
+      case "wait": {
+        const timeout = step.timeout ?? 1e3;
+        if (step.condition === "idle") {
+          await page.waitForLoadState("networkidle", { timeout }).catch(() => {
+          });
+        } else {
+          await page.waitForTimeout(timeout);
+        }
+        break;
+      }
+      default:
+        break;
+    }
+  }
+}
+var _pool = null;
+async function getPool() {
+  if (_pool === null) {
+    _pool = new BrowserPool({
+      size: { browsers: 1, pagesPerBrowser: 2 },
+      viewportWidth: 1280,
+      viewportHeight: 800
+    });
+    await _pool.init();
+  }
+  return _pool;
+}
+async function shutdownPool() {
+  if (_pool !== null) {
+    await _pool.close();
+    _pool = null;
+  }
+}
+async function analyzeRenders(options) {
+  const manifestPath = options.manifestPath ?? MANIFEST_PATH2;
+  const manifest = loadManifest(manifestPath);
+  const descriptor = manifest.components[options.componentName];
+  if (descriptor === void 0) {
+    const available = Object.keys(manifest.components).slice(0, 5).join(", ");
+    throw new Error(
+      `Component "${options.componentName}" not found in manifest.
+Available: ${available}`
+    );
+  }
+  const rootDir = process.cwd();
+  const filePath = resolve2(rootDir, descriptor.filePath);
+  const htmlHarness = await buildComponentHarness(filePath, options.componentName, {}, 1280);
+  const pool = await getPool();
+  const slot = await pool.acquire();
+  const { page } = slot;
+  const startMs = performance.now();
+  try {
+    await page.addInitScript(buildInstrumentationScript());
+    await page.setContent(htmlHarness, { waitUntil: "load" });
+    await page.waitForFunction(
+      () => window.__SCOPE_RENDER_COMPLETE__ === true,
+      { timeout: 15e3 }
+    );
+    await page.waitForTimeout(100);
+    await page.evaluate(() => {
+      window.__SCOPE_RENDER_EVENTS__ = [];
+      window.__SCOPE_RENDER_INDEX__ = 0;
+    });
+    await replayInteraction(page, options.interaction);
+    await page.waitForTimeout(200);
+    const interactionDurationMs = performance.now() - startMs;
+    const rawEvents = await page.evaluate(() => {
+      return window.__SCOPE_RENDER_EVENTS__ ?? [];
+    });
+    const renders = buildCausalityChains(rawEvents);
+    const flags = applyHeuristicFlags(renders);
+    const uniqueComponents = new Set(renders.map((r) => r.component)).size;
+    const wastedRenders = renders.filter((r) => r.wasted).length;
+    return {
+      component: options.componentName,
+      interaction: options.interaction,
+      summary: {
+        totalRenders: renders.length,
+        uniqueComponents,
+        wastedRenders,
+        interactionDurationMs: Math.round(interactionDurationMs)
+      },
+      renders,
+      flags
+    };
+  } finally {
+    pool.release(slot);
+  }
 }
-function formatSummaryText(results, outputDir) {
-  const total = results.length;
-  const passed = results.filter((r) => r.success).length;
-  const failed = total - passed;
-  const successTimes = results.filter((r) => r.success).map((r) => r.renderTimeMs);
-  const avgMs = successTimes.length > 0 ? successTimes.reduce((a, b) => a + b, 0) / successTimes.length : 0;
-  const lines = [
-    "\u2500".repeat(60),
-    `Render Summary`,
-    "\u2500".repeat(60),
-    `  Total components : ${total}`,
-    `  Passed           : ${passed}`,
-    `  Failed           : ${failed}`,
-    `  Avg render time  : ${avgMs.toFixed(1)}ms`,
-    `  Output dir       : ${outputDir}`
-  ];
-  if (failed > 0) {
-    lines.push("", "  Failed components:");
-    for (const r of results) {
-      if (!r.success) {
-        lines.push(`    \u2717 ${r.name}: ${r.errorMessage ?? "unknown error"}`);
-      }
+function formatRendersTable(result) {
+  const lines = [];
+  lines.push(`
+\u{1F50D} Re-render Analysis: ${result.component}`);
+  lines.push(`${"\u2500".repeat(60)}`);
+  lines.push(`Total renders:    ${result.summary.totalRenders}`);
+  lines.push(`Unique components: ${result.summary.uniqueComponents}`);
+  lines.push(`Wasted renders:   ${result.summary.wastedRenders}`);
+  lines.push(`Duration:         ${result.summary.interactionDurationMs}ms`);
+  lines.push("");
+  if (result.renders.length === 0) {
+    lines.push("No re-renders captured during interaction.");
+  } else {
+    lines.push("Re-renders:");
+    lines.push(
+      `${"#".padEnd(4)} ${"Component".padEnd(30)} ${"Trigger".padEnd(18)} ${"Wasted".padEnd(7)} ${"Chain Depth"}`
+    );
+    lines.push("\u2500".repeat(80));
+    for (const r of result.renders) {
+      const wasted = r.wasted ? "\u26A0 yes" : "no";
+      const idx = String(r.renderIndex).padEnd(4);
+      const comp = r.component.slice(0, 29).padEnd(30);
+      const trig = r.trigger.padEnd(18);
+      const w = wasted.padEnd(7);
+      const depth = r.chain.length;
+      lines.push(`${idx} ${comp} ${trig} ${w} ${depth}`);
+    }
+  }
+  if (result.flags.length > 0) {
+    lines.push("");
+    lines.push("Flags:");
+    for (const flag of result.flags) {
+      const icon = flag.severity === "error" ? "\u2717" : flag.severity === "warning" ? "\u26A0" : "\u2139";
+      lines.push(`  ${icon} [${flag.id}] ${flag.component}: ${flag.detail}`);
     }
   }
-  lines.push("\u2500".repeat(60));
   return lines.join("\n");
 }
-function escapeHtml(str) {
-  return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#039;");
+function createInstrumentRendersCommand() {
+  return new Command2("renders").description("Trace re-render causality chains for a component during an interaction sequence").argument("<component>", "Component name to instrument (must be in manifest)").option(
+    "--interaction <json>",
+    `Interaction sequence JSON, e.g. '[{"action":"click","target":"button"}]'`,
+    "[]"
+  ).option("--json", "Output as JSON regardless of TTY", false).option("--manifest <path>", "Path to manifest.json", MANIFEST_PATH2).action(
+    async (componentName, opts) => {
+      let interaction = [];
+      try {
+        interaction = JSON.parse(opts.interaction);
+        if (!Array.isArray(interaction)) {
+          throw new Error("Interaction must be a JSON array");
+        }
+      } catch {
+        process.stderr.write(`Error: Invalid --interaction JSON: ${opts.interaction}
+`);
+        process.exit(1);
+      }
+      try {
+        process.stderr.write(
+          `Instrumenting ${componentName} (${interaction.length} interaction steps)\u2026
+`
+        );
+        const result = await analyzeRenders({
+          componentName,
+          interaction,
+          manifestPath: opts.manifest
+        });
+        await shutdownPool();
+        if (opts.json || !isTTY()) {
+          process.stdout.write(`${JSON.stringify(result, null, 2)}
+`);
+        } else {
+          process.stdout.write(`${formatRendersTable(result)}
+`);
+        }
+      } catch (err) {
+        await shutdownPool();
+        process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}
+`);
+        process.exit(1);
+      }
+    }
+  );
 }
-function csvEscape(value) {
-  if (value.includes(",") || value.includes('"') || value.includes("\n")) {
-    return `"${value.replace(/"/g, '""')}"`;
-  }
-  return value;
+function createInstrumentCommand() {
+  const instrumentCmd = new Command2("instrument").description(
+    "Structured instrumentation commands for React component analysis"
+  );
+  instrumentCmd.addCommand(createInstrumentRendersCommand());
+  return instrumentCmd;
 }
 
+// src/render-commands.ts
+import { mkdirSync as mkdirSync2, writeFileSync as writeFileSync3 } from "fs";
+import { resolve as resolve4 } from "path";
+import {
+  ALL_CONTEXT_IDS,
+  ALL_STRESS_IDS,
+  BrowserPool as BrowserPool2,
+  contextAxis,
+  RenderMatrix,
+  SatoriRenderer,
+  safeRender,
+  stressAxis
+} from "@agent-scope/render";
+import { Command as Command3 } from "commander";
+
 // src/tailwind-css.ts
 import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
 import { createRequire } from "module";
-import { resolve as resolve2 } from "path";
+import { resolve as resolve3 } from "path";
 var CONFIG_FILENAMES = [
   ".reactscope/config.json",
   ".reactscope/config.js",
@@ -632,14 +1104,14 @@ var STYLE_ENTRY_CANDIDATES = [
 var TAILWIND_IMPORT = /@import\s+["']tailwindcss["']\s*;?/;
 var compilerCache = null;
 function getCachedBuild(cwd) {
-  if (compilerCache !== null && resolve2(compilerCache.cwd) === resolve2(cwd)) {
+  if (compilerCache !== null && resolve3(compilerCache.cwd) === resolve3(cwd)) {
     return compilerCache.build;
   }
   return null;
 }
 function findStylesEntry(cwd) {
   for (const name of CONFIG_FILENAMES) {
-    const p = resolve2(cwd, name);
+    const p = resolve3(cwd, name);
     if (!existsSync2(p)) continue;
     try {
       if (name.endsWith(".json")) {
@@ -648,28 +1120,28 @@ function findStylesEntry(cwd) {
         const scope = data.scope;
         const entry = scope?.stylesEntry ?? data.stylesEntry;
         if (typeof entry === "string") {
-          const full = resolve2(cwd, entry);
+          const full = resolve3(cwd, entry);
           if (existsSync2(full)) return full;
         }
       }
     } catch {
     }
   }
-  const pkgPath = resolve2(cwd, "package.json");
+  const pkgPath = resolve3(cwd, "package.json");
   if (existsSync2(pkgPath)) {
     try {
       const raw = readFileSync2(pkgPath, "utf-8");
       const pkg = JSON.parse(raw);
       const entry = pkg.scope?.stylesEntry;
       if (typeof entry === "string") {
-        const full = resolve2(cwd, entry);
+        const full = resolve3(cwd, entry);
         if (existsSync2(full)) return full;
       }
     } catch {
     }
   }
   for (const candidate of STYLE_ENTRY_CANDIDATES) {
-    const full = resolve2(cwd, candidate);
+    const full = resolve3(cwd, candidate);
     if (existsSync2(full)) {
       try {
         const content = readFileSync2(full, "utf-8");
@@ -687,7 +1159,7 @@ async function getTailwindCompiler(cwd) {
   if (entryPath === null) return null;
   let compile;
   try {
-    const require2 = createRequire(resolve2(cwd, "package.json"));
+    const require2 = createRequire(resolve3(cwd, "package.json"));
     const tailwind = require2("tailwindcss");
     const fn = tailwind.compile;
     if (typeof fn !== "function") return null;
@@ -698,8 +1170,8 @@ async function getTailwindCompiler(cwd) {
   const entryContent = readFileSync2(entryPath, "utf-8");
   const loadStylesheet = async (id, base) => {
     if (id === "tailwindcss") {
-      const nodeModules = resolve2(cwd, "node_modules");
-      const tailwindCssPath = resolve2(nodeModules, "tailwindcss", "index.css");
+      const nodeModules = resolve3(cwd, "node_modules");
+      const tailwindCssPath = resolve3(nodeModules, "tailwindcss", "index.css");
       if (!existsSync2(tailwindCssPath)) {
         throw new Error(
           `Tailwind v4: tailwindcss package not found at ${tailwindCssPath}. Install with: npm install tailwindcss`
@@ -708,10 +1180,10 @@ async function getTailwindCompiler(cwd) {
       const content = readFileSync2(tailwindCssPath, "utf-8");
       return { path: "virtual:tailwindcss/index.css", base, content };
     }
-    const full = resolve2(base, id);
+    const full = resolve3(base, id);
     if (existsSync2(full)) {
       const content = readFileSync2(full, "utf-8");
-      return { path: full, base: resolve2(full, ".."), content };
+      return { path: full, base: resolve3(full, ".."), content };
     }
     throw new Error(`Tailwind v4: could not load stylesheet: ${id} (base: ${base})`);
   };
@@ -733,24 +1205,24 @@ async function getCompiledCssForClasses(cwd, classes) {
 }
 
 // src/render-commands.ts
-var MANIFEST_PATH2 = ".reactscope/manifest.json";
+var MANIFEST_PATH3 = ".reactscope/manifest.json";
 var DEFAULT_OUTPUT_DIR = ".reactscope/renders";
-var _pool = null;
-async function getPool(viewportWidth, viewportHeight) {
-  if (_pool === null) {
-    _pool = new BrowserPool({
+var _pool2 = null;
+async function getPool2(viewportWidth, viewportHeight) {
+  if (_pool2 === null) {
+    _pool2 = new BrowserPool2({
       size: { browsers: 1, pagesPerBrowser: 4 },
       viewportWidth,
       viewportHeight
     });
-    await _pool.init();
+    await _pool2.init();
   }
-  return _pool;
+  return _pool2;
 }
-async function shutdownPool() {
-  if (_pool !== null) {
-    await _pool.close();
-    _pool = null;
+async function shutdownPool2() {
+  if (_pool2 !== null) {
+    await _pool2.close();
+    _pool2 = null;
   }
 }
 function buildRenderer(filePath, componentName, viewportWidth, viewportHeight) {
@@ -761,7 +1233,7 @@ function buildRenderer(filePath, componentName, viewportWidth, viewportHeight) {
     _satori: satori,
     async renderCell(props, _complexityClass) {
       const startMs = performance.now();
-      const pool = await getPool(viewportWidth, viewportHeight);
+      const pool = await getPool2(viewportWidth, viewportHeight);
       const htmlHarness = await buildComponentHarness(
         filePath,
         componentName,
@@ -858,7 +1330,7 @@ function buildRenderer(filePath, componentName, viewportWidth, viewportHeight) {
   };
 }
 function registerRenderSingle(renderCmd) {
-  renderCmd.command("component <component>", { isDefault: true }).description("Render a single component to PNG or JSON").option("--props <json>", `Inline props JSON, e.g. '{"variant":"primary"}'`).option("--viewport <WxH>", "Viewport size e.g. 1280x720", "375x812").option("--theme <name>", "Theme name from the token system").option("-o, --output <path>", "Write PNG to file instead of stdout").option("--format <fmt>", "Output format: png or json (default: auto)").option("--manifest <path>", "Path to manifest.json", MANIFEST_PATH2).action(
+  renderCmd.command("component <component>", { isDefault: true }).description("Render a single component to PNG or JSON").option("--props <json>", `Inline props JSON, e.g. '{"variant":"primary"}'`).option("--viewport <WxH>", "Viewport size e.g. 1280x720", "375x812").option("--theme <name>", "Theme name from the token system").option("-o, --output <path>", "Write PNG to file instead of stdout").option("--format <fmt>", "Output format: png or json (default: auto)").option("--manifest <path>", "Path to manifest.json", MANIFEST_PATH3).action(
     async (componentName, opts) => {
       try {
         const manifest = loadManifest(opts.manifest);
@@ -880,7 +1352,7 @@ Available: ${available}`
         }
         const { width, height } = parseViewport(opts.viewport);
         const rootDir = process.cwd();
-        const filePath = resolve3(rootDir, descriptor.filePath);
+        const filePath = resolve4(rootDir, descriptor.filePath);
         const renderer = buildRenderer(filePath, componentName, width, height);
         process.stderr.write(
           `Rendering ${componentName} [${descriptor.complexityClass}] at ${width}\xD7${height}\u2026
@@ -897,7 +1369,7 @@ Available: ${available}`
             }
           }
         );
-        await shutdownPool();
+        await shutdownPool2();
         if (outcome.crashed) {
           process.stderr.write(`\u2717 Render failed: ${outcome.error.message}
 `);
@@ -910,7 +1382,7 @@ Available: ${available}`
         }
         const result = outcome.result;
         if (opts.output !== void 0) {
-          const outPath = resolve3(process.cwd(), opts.output);
+          const outPath = resolve4(process.cwd(), opts.output);
           writeFileSync3(outPath, result.screenshot);
           process.stdout.write(
             `\u2713 ${componentName} \u2192 ${opts.output} (${result.width}\xD7${result.height}, ${result.renderTimeMs.toFixed(0)}ms)
@@ -924,9 +1396,9 @@ Available: ${available}`
           process.stdout.write(`${JSON.stringify(json, null, 2)}
 `);
         } else if (fmt === "file") {
-          const dir = resolve3(process.cwd(), DEFAULT_OUTPUT_DIR);
+          const dir = resolve4(process.cwd(), DEFAULT_OUTPUT_DIR);
           mkdirSync2(dir, { recursive: true });
-          const outPath = resolve3(dir, `${componentName}.png`);
+          const outPath = resolve4(dir, `${componentName}.png`);
           writeFileSync3(outPath, result.screenshot);
           const relPath = `${DEFAULT_OUTPUT_DIR}/${componentName}.png`;
           process.stdout.write(
@@ -934,9 +1406,9 @@ Available: ${available}`
 `
           );
         } else {
-          const dir = resolve3(process.cwd(), DEFAULT_OUTPUT_DIR);
+          const dir = resolve4(process.cwd(), DEFAULT_OUTPUT_DIR);
           mkdirSync2(dir, { recursive: true });
-          const outPath = resolve3(dir, `${componentName}.png`);
+          const outPath = resolve4(dir, `${componentName}.png`);
           writeFileSync3(outPath, result.screenshot);
           const relPath = `${DEFAULT_OUTPUT_DIR}/${componentName}.png`;
           process.stdout.write(
@@ -945,7 +1417,7 @@ Available: ${available}`
           );
         }
       } catch (err) {
-        await shutdownPool();
+        await shutdownPool2();
         process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}
 `);
         process.exit(1);
@@ -957,7 +1429,7 @@ function registerRenderMatrix(renderCmd) {
   renderCmd.command("matrix <component>").description("Render a component across a matrix of prop axes").option("--axes <spec>", "Axis definitions e.g. 'variant:primary,secondary size:sm,md,lg'").option(
     "--contexts <ids>",
     "Composition context IDs, comma-separated (e.g. centered,rtl,sidebar)"
-  ).option("--stress <ids>", "Stress preset IDs, comma-separated (e.g. text.long,text.unicode)").option("--sprite <path>", "Write sprite sheet PNG to file").option("--format <fmt>", "Output format: json|png|html|csv (default: auto)").option("--concurrency <n>", "Max parallel renders", "8").option("--manifest <path>", "Path to manifest.json", MANIFEST_PATH2).action(
+  ).option("--stress <ids>", "Stress preset IDs, comma-separated (e.g. text.long,text.unicode)").option("--sprite <path>", "Write sprite sheet PNG to file").option("--format <fmt>", "Output format: json|png|html|csv (default: auto)").option("--concurrency <n>", "Max parallel renders", "8").option("--manifest <path>", "Path to manifest.json", MANIFEST_PATH3).action(
     async (componentName, opts) => {
       try {
         const manifest = loadManifest(opts.manifest);
@@ -972,7 +1444,7 @@ Available: ${available}`
         const concurrency = Math.max(1, parseInt(opts.concurrency, 10) || 8);
         const { width, height } = { width: 375, height: 812 };
         const rootDir = process.cwd();
-        const filePath = resolve3(rootDir, descriptor.filePath);
+        const filePath = resolve4(rootDir, descriptor.filePath);
         const renderer = buildRenderer(filePath, componentName, width, height);
         const axes = [];
         if (opts.axes !== void 0) {
@@ -1030,7 +1502,7 @@ Available: ${available}`
           concurrency
         });
         const result = await matrix.render();
-        await shutdownPool();
+        await shutdownPool2();
         process.stderr.write(
           `Done. ${result.stats.totalCells} cells, avg ${result.stats.avgRenderTimeMs.toFixed(1)}ms
 `
@@ -1039,7 +1511,7 @@ Available: ${available}`
           const { SpriteSheetGenerator } = await import("@agent-scope/render");
           const gen = new SpriteSheetGenerator();
           const sheet = await gen.generate(result);
-          const spritePath = resolve3(process.cwd(), opts.sprite);
+          const spritePath = resolve4(process.cwd(), opts.sprite);
           writeFileSync3(spritePath, sheet.png);
           process.stderr.write(`Sprite sheet saved to ${spritePath}
 `);
@@ -1049,9 +1521,9 @@ Available: ${available}`
           const { SpriteSheetGenerator } = await import("@agent-scope/render");
           const gen = new SpriteSheetGenerator();
           const sheet = await gen.generate(result);
-          const dir = resolve3(process.cwd(), DEFAULT_OUTPUT_DIR);
+          const dir = resolve4(process.cwd(), DEFAULT_OUTPUT_DIR);
           mkdirSync2(dir, { recursive: true });
-          const outPath = resolve3(dir, `${componentName}-matrix.png`);
+          const outPath = resolve4(dir, `${componentName}-matrix.png`);
           writeFileSync3(outPath, sheet.png);
           const relPath = `${DEFAULT_OUTPUT_DIR}/${componentName}-matrix.png`;
           process.stdout.write(
@@ -1075,7 +1547,7 @@ Available: ${available}`
           process.stdout.write(formatMatrixCsv(componentName, result));
         }
       } catch (err) {
-        await shutdownPool();
+        await shutdownPool2();
         process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}
 `);
         process.exit(1);
@@ -1084,7 +1556,7 @@ Available: ${available}`
   );
 }
 function registerRenderAll(renderCmd) {
-  renderCmd.command("all").description("Render all components from the manifest").option("--concurrency <n>", "Max parallel renders", "4").option("--output-dir <dir>", "Output directory for renders", DEFAULT_OUTPUT_DIR).option("--manifest <path>", "Path to manifest.json", MANIFEST_PATH2).option("--format <fmt>", "Output format: json|png (default: png)", "png").action(
+  renderCmd.command("all").description("Render all components from the manifest").option("--concurrency <n>", "Max parallel renders", "4").option("--output-dir <dir>", "Output directory for renders", DEFAULT_OUTPUT_DIR).option("--manifest <path>", "Path to manifest.json", MANIFEST_PATH3).option("--format <fmt>", "Output format: json|png (default: png)", "png").action(
     async (opts) => {
       try {
         const manifest = loadManifest(opts.manifest);
@@ -1095,7 +1567,7 @@ function registerRenderAll(renderCmd) {
           return;
         }
         const concurrency = Math.max(1, parseInt(opts.concurrency, 10) || 4);
-        const outputDir = resolve3(process.cwd(), opts.outputDir);
+        const outputDir = resolve4(process.cwd(), opts.outputDir);
         mkdirSync2(outputDir, { recursive: true });
         const rootDir = process.cwd();
         process.stderr.write(`Rendering ${total} components (concurrency: ${concurrency})\u2026
@@ -1105,7 +1577,7 @@ function registerRenderAll(renderCmd) {
         const renderOne = async (name) => {
           const descriptor = manifest.components[name];
           if (descriptor === void 0) return;
-          const filePath = resolve3(rootDir, descriptor.filePath);
+          const filePath = resolve4(rootDir, descriptor.filePath);
           const renderer = buildRenderer(filePath, name, 375, 812);
           const outcome = await safeRender(
             () => renderer.renderCell({}, descriptor.complexityClass),
@@ -1128,7 +1600,7 @@ function registerRenderAll(renderCmd) {
               success: false,
               errorMessage: outcome.error.message
             });
-            const errPath = resolve3(outputDir, `${name}.error.json`);
+            const errPath = resolve4(outputDir, `${name}.error.json`);
             writeFileSync3(
               errPath,
               JSON.stringify(
@@ -1146,9 +1618,9 @@ function registerRenderAll(renderCmd) {
           }
           const result = outcome.result;
           results.push({ name, renderTimeMs: result.renderTimeMs, success: true });
-          const pngPath = resolve3(outputDir, `${name}.png`);
+          const pngPath = resolve4(outputDir, `${name}.png`);
           writeFileSync3(pngPath, result.screenshot);
-          const jsonPath = resolve3(outputDir, `${name}.json`);
+          const jsonPath = resolve4(outputDir, `${name}.json`);
           writeFileSync3(jsonPath, JSON.stringify(formatRenderJson(name, {}, result), null, 2));
           if (isTTY()) {
             process.stdout.write(
@@ -1172,13 +1644,13 @@ function registerRenderAll(renderCmd) {
           workers.push(worker());
         }
         await Promise.all(workers);
-        await shutdownPool();
+        await shutdownPool2();
         process.stderr.write("\n");
         const summary = formatSummaryText(results, outputDir);
         process.stderr.write(`${summary}
 `);
       } catch (err) {
-        await shutdownPool();
+        await shutdownPool2();
         process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}
 `);
         process.exit(1);
@@ -1211,7 +1683,7 @@ function resolveMatrixFormat(formatFlag, spriteAlreadyWritten) {
   return "json";
 }
 function createRenderCommand() {
-  const renderCmd = new Command2("render").description(
+  const renderCmd = new Command3("render").description(
     "Render components to PNG or JSON via esbuild + BrowserPool"
   );
   registerRenderSingle(renderCmd);
@@ -1499,9 +1971,363 @@ function buildStructuredReport(report) {
   };
 }
 
+// src/tokens/commands.ts
+import { existsSync as existsSync3, readFileSync as readFileSync3 } from "fs";
+import { resolve as resolve5 } from "path";
+import {
+  parseTokenFileSync,
+  TokenParseError,
+  TokenResolver,
+  TokenValidationError,
+  validateTokenFile
+} from "@agent-scope/tokens";
+import { Command as Command4 } from "commander";
+var DEFAULT_TOKEN_FILE = "reactscope.tokens.json";
+var CONFIG_FILE = "reactscope.config.json";
+function isTTY2() {
+  return process.stdout.isTTY === true;
+}
+function pad3(value, width) {
+  return value.length >= width ? value.slice(0, width) : value + " ".repeat(width - value.length);
+}
+function buildTable2(headers, rows) {
+  const colWidths = headers.map(
+    (h, i) => Math.max(h.length, ...rows.map((r) => (r[i] ?? "").length))
+  );
+  const divider = colWidths.map((w) => "-".repeat(w)).join("  ");
+  const headerRow = headers.map((h, i) => pad3(h, colWidths[i] ?? 0)).join("  ");
+  const dataRows = rows.map(
+    (row2) => row2.map((cell, i) => pad3(cell ?? "", colWidths[i] ?? 0)).join("  ")
+  );
+  return [headerRow, divider, ...dataRows].join("\n");
+}
+function resolveTokenFilePath(fileFlag) {
+  if (fileFlag !== void 0) {
+    return resolve5(process.cwd(), fileFlag);
+  }
+  const configPath = resolve5(process.cwd(), CONFIG_FILE);
+  if (existsSync3(configPath)) {
+    try {
+      const raw = readFileSync3(configPath, "utf-8");
+      const config = JSON.parse(raw);
+      if (typeof config === "object" && config !== null && "tokens" in config && typeof config.tokens === "object" && config.tokens !== null && typeof config.tokens?.file === "string") {
+        const file = config.tokens.file;
+        return resolve5(process.cwd(), file);
+      }
+    } catch {
+    }
+  }
+  return resolve5(process.cwd(), DEFAULT_TOKEN_FILE);
+}
+function loadTokens(absPath) {
+  if (!existsSync3(absPath)) {
+    throw new Error(
+      `Token file not found at ${absPath}.
+Create a reactscope.tokens.json file or use --file to specify a path.`
+    );
+  }
+  const raw = readFileSync3(absPath, "utf-8");
+  return parseTokenFileSync(raw);
+}
+function getRawValue(node, segments) {
+  const [head, ...rest] = segments;
+  if (head === void 0) return null;
+  const child = node[head];
+  if (child === void 0 || child === null) return null;
+  if (rest.length === 0) {
+    if (typeof child === "object" && !Array.isArray(child) && "value" in child) {
+      const v = child.value;
+      return typeof v === "string" || typeof v === "number" ? v : null;
+    }
+    return null;
+  }
+  if (typeof child === "object" && !Array.isArray(child)) {
+    return getRawValue(child, rest);
+  }
+  return null;
+}
+function buildResolutionChain(startPath, rawTokens) {
+  const chain = [];
+  const seen = /* @__PURE__ */ new Set();
+  let current = startPath;
+  while (!seen.has(current)) {
+    seen.add(current);
+    const rawValue = getRawValue(rawTokens, current.split("."));
+    if (rawValue === null) break;
+    chain.push({ path: current, rawValue: String(rawValue) });
+    const refMatch = /^\{([^}]+)\}$/.exec(String(rawValue));
+    if (refMatch === null) break;
+    current = refMatch[1] ?? "";
+  }
+  return chain;
+}
+function registerGet2(tokensCmd) {
+  tokensCmd.command("get <path>").description("Resolve a token path to its computed value").option("--file <path>", "Path to token file (overrides config)").option("--format <fmt>", "Output format: json or text (default: auto-detect)").action((tokenPath, opts) => {
+    try {
+      const filePath = resolveTokenFilePath(opts.file);
+      const { tokens } = loadTokens(filePath);
+      const resolver = new TokenResolver(tokens);
+      const resolvedValue = resolver.resolve(tokenPath);
+      const useJson = opts.format === "json" || opts.format !== "text" && !isTTY2();
+      if (useJson) {
+        const token = tokens.find((t) => t.path === tokenPath);
+        process.stdout.write(
+          `${JSON.stringify({ path: tokenPath, value: token?.value, resolvedValue, type: token?.type }, null, 2)}
+`
+        );
+      } else {
+        process.stdout.write(`${resolvedValue}
+`);
+      }
+    } catch (err) {
+      process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}
+`);
+      process.exit(1);
+    }
+  });
+}
+function registerList2(tokensCmd) {
+  tokensCmd.command("list [category]").description("List tokens, optionally filtered by category or type").option("--type <type>", "Filter by token type (color, dimension, fontFamily, etc.)").option("--file <path>", "Path to token file (overrides config)").option("--format <fmt>", "Output format: json or table (default: auto-detect)").action(
+    (category, opts) => {
+      try {
+        const filePath = resolveTokenFilePath(opts.file);
+        const { tokens } = loadTokens(filePath);
+        const resolver = new TokenResolver(tokens);
+        const filtered = resolver.list(opts.type, category);
+        const useJson = opts.format === "json" || opts.format !== "table" && !isTTY2();
+        if (useJson) {
+          process.stdout.write(`${JSON.stringify(filtered, null, 2)}
+`);
+        } else {
+          if (filtered.length === 0) {
+            process.stdout.write("No tokens found.\n");
+            return;
+          }
+          const headers = ["PATH", "VALUE", "RESOLVED", "TYPE"];
+          const rows = filtered.map((t) => [t.path, String(t.value), t.resolvedValue, t.type]);
+          process.stdout.write(`${buildTable2(headers, rows)}
+`);
+        }
+      } catch (err) {
+        process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}
+`);
+        process.exit(1);
+      }
+    }
+  );
+}
+function registerSearch(tokensCmd) {
+  tokensCmd.command("search <value>").description("Find which token(s) match a computed value (supports fuzzy color matching)").option("--type <type>", "Restrict search to a specific token type").option("--fuzzy", "Return nearest match even if no exact match exists", false).option("--file <path>", "Path to token file (overrides config)").option("--format <fmt>", "Output format: json or table (default: auto-detect)").action(
+    (value, opts) => {
+      try {
+        const filePath = resolveTokenFilePath(opts.file);
+        const { tokens } = loadTokens(filePath);
+        const resolver = new TokenResolver(tokens);
+        const useJson = opts.format === "json" || opts.format !== "table" && !isTTY2();
+        const typesToSearch = opts.type ? [opts.type] : [
+          "color",
+          "dimension",
+          "fontFamily",
+          "fontWeight",
+          "number",
+          "shadow",
+          "duration",
+          "cubicBezier"
+        ];
+        const exactMatches = [];
+        const nearestMatches = [];
+        for (const type of typesToSearch) {
+          const exact = resolver.match(value, type);
+          if (exact !== null) {
+            exactMatches.push({
+              path: exact.token.path,
+              resolvedValue: exact.token.resolvedValue,
+              type: exact.token.type,
+              exact: true,
+              distance: 0
+            });
+          }
+        }
+        if (exactMatches.length === 0 && opts.fuzzy) {
+          for (const type of typesToSearch) {
+            const typeTokens = tokens.filter((t) => t.type === type);
+            if (typeTokens.length === 0) continue;
+            try {
+              const near = resolver.nearest(value, type);
+              nearestMatches.push({
+                path: near.token.path,
+                resolvedValue: near.token.resolvedValue,
+                type: near.token.type,
+                exact: near.exact,
+                distance: near.distance
+              });
+            } catch {
+            }
+          }
+          nearestMatches.sort((a, b) => a.distance - b.distance);
+          nearestMatches.splice(3);
+        }
+        const results = exactMatches.length > 0 ? exactMatches : nearestMatches;
+        if (useJson) {
+          process.stdout.write(`${JSON.stringify(results, null, 2)}
+`);
+        } else {
+          if (results.length === 0) {
+            process.stdout.write(
+              `No tokens found matching "${value}".
+Tip: use --fuzzy for nearest-match search.
+`
+            );
+            return;
+          }
+          const headers = ["PATH", "RESOLVED VALUE", "TYPE", "MATCH", "DISTANCE"];
+          const rows = results.map((r) => [
+            r.path,
+            r.resolvedValue,
+            r.type,
+            r.exact ? "exact" : "nearest",
+            r.exact ? "\u2014" : r.distance.toFixed(2)
+          ]);
+          process.stdout.write(`${buildTable2(headers, rows)}
+`);
+        }
+      } catch (err) {
+        process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}
+`);
+        process.exit(1);
+      }
+    }
+  );
+}
+function registerResolve(tokensCmd) {
+  tokensCmd.command("resolve <path>").description("Show the full resolution chain for a token").option("--file <path>", "Path to token file (overrides config)").option("--format <fmt>", "Output format: json or text (default: auto-detect)").action((tokenPath, opts) => {
+    try {
+      const filePath = resolveTokenFilePath(opts.file);
+      const absFilePath = filePath;
+      const { tokens, rawFile } = loadTokens(absFilePath);
+      const resolver = new TokenResolver(tokens);
+      resolver.resolve(tokenPath);
+      const chain = buildResolutionChain(tokenPath, rawFile.tokens);
+      const useJson = opts.format === "json" || opts.format !== "text" && !isTTY2();
+      if (useJson) {
+        process.stdout.write(`${JSON.stringify({ path: tokenPath, chain }, null, 2)}
+`);
+      } else {
+        if (chain.length === 0) {
+          process.stdout.write(`Token "${tokenPath}" not found.
+`);
+          return;
+        }
+        const parts = chain.map((step, i) => {
+          if (i < chain.length - 1) {
+            return `${step.path} \u2192 ${step.rawValue}`;
+          }
+          return step.rawValue;
+        });
+        process.stdout.write(`${parts.join("\n  ")}
+`);
+      }
+    } catch (err) {
+      process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}
+`);
+      process.exit(1);
+    }
+  });
+}
+function registerValidate(tokensCmd) {
+  tokensCmd.command("validate").description(
+    "Validate the token file for errors (circular refs, missing refs, type mismatches)"
+  ).option("--file <path>", "Path to token file (overrides config)").option("--format <fmt>", "Output format: json or text (default: auto-detect)").action((opts) => {
+    try {
+      const filePath = resolveTokenFilePath(opts.file);
+      if (!existsSync3(filePath)) {
+        throw new Error(
+          `Token file not found at ${filePath}.
+Create a reactscope.tokens.json file or use --file to specify a path.`
+        );
+      }
+      const raw = readFileSync3(filePath, "utf-8");
+      const useJson = opts.format === "json" || opts.format !== "text" && !isTTY2();
+      const errors = [];
+      let parsed;
+      try {
+        parsed = JSON.parse(raw);
+      } catch (err) {
+        errors.push({
+          code: "PARSE_ERROR",
+          message: `Failed to parse token file as JSON: ${String(err)}`
+        });
+        outputValidationResult(filePath, errors, useJson);
+        process.exit(1);
+      }
+      try {
+        validateTokenFile(parsed);
+      } catch (err) {
+        if (err instanceof TokenValidationError) {
+          for (const e of err.errors) {
+            errors.push({ code: e.code, path: e.path, message: e.message });
+          }
+          outputValidationResult(filePath, errors, useJson);
+          process.exit(1);
+        }
+        throw err;
+      }
+      try {
+        parseTokenFileSync(raw);
+      } catch (err) {
+        if (err instanceof TokenParseError) {
+          errors.push({ code: err.code, path: err.path, message: err.message });
+        } else {
+          errors.push({ code: "UNKNOWN", message: String(err) });
+        }
+        outputValidationResult(filePath, errors, useJson);
+        process.exit(1);
+      }
+      outputValidationResult(filePath, errors, useJson);
+    } catch (err) {
+      process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}
+`);
+      process.exit(1);
+    }
+  });
+}
+function outputValidationResult(filePath, errors, useJson) {
+  const valid = errors.length === 0;
+  if (useJson) {
+    process.stdout.write(`${JSON.stringify({ valid, file: filePath, errors }, null, 2)}
+`);
+  } else {
+    if (valid) {
+      process.stdout.write(`\u2713 Token file is valid: ${filePath}
+`);
+    } else {
+      process.stderr.write(`\u2717 Token file has ${errors.length} error(s): ${filePath}
+
+`);
+      for (const e of errors) {
+        const pathPrefix = e.path ? ` [${e.path}]` : "";
+        process.stderr.write(`  ${e.code}${pathPrefix}: ${e.message}
+`);
+      }
+      process.exit(1);
+    }
+  }
+}
+function createTokensCommand() {
+  const tokensCmd = new Command4("tokens").description(
+    "Query and validate design tokens from a reactscope.tokens.json file"
+  );
+  registerGet2(tokensCmd);
+  registerList2(tokensCmd);
+  registerSearch(tokensCmd);
+  registerResolve(tokensCmd);
+  registerValidate(tokensCmd);
+  return tokensCmd;
+}
+
 // src/program.ts
 function createProgram(options = {}) {
-  const program2 = new Command3("scope").version(options.version ?? "0.1.0").description("Scope \u2014 React instrumentation toolkit");
+  const program2 = new Command5("scope").version(options.version ?? "0.1.0").description("Scope \u2014 React instrumentation toolkit");
   program2.command("capture <url>").description("Capture a React component tree from a live URL and output as JSON").option("-o, --output <path>", "Write JSON to file instead of stdout").option("--pretty", "Pretty-print JSON output (default: minified)", false).option("--timeout <ms>", "Max wait time for React to mount (ms)", "10000").option("--wait <ms>", "Additional wait after page load before capture (ms)", "0").action(
     async (url, opts) => {
       try {
@@ -1574,7 +2400,7 @@ function createProgram(options = {}) {
     }
   );
   program2.command("generate").description("Generate a Playwright test from a Scope trace file").argument("<trace>", "Path to a serialized Scope trace (.json)").option("-o, --output <path>", "Output file path", "scope.spec.ts").option("-d, --description <text>", "Test description").action((tracePath, opts) => {
-    const raw = readFileSync3(tracePath, "utf-8");
+    const raw = readFileSync4(tracePath, "utf-8");
     const trace = loadTrace(raw);
     const source = generateTest(trace, {
       description: opts.description,
@@ -1585,6 +2411,8 @@ function createProgram(options = {}) {
   });
   program2.addCommand(createManifestCommand());
   program2.addCommand(createRenderCommand());
+  program2.addCommand(createTokensCommand());
+  program2.addCommand(createInstrumentCommand());
   return program2;
 }