@agent-scope/cli 1.9.0 → 1.11.0

package/dist/cli.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 
 // src/program.ts
-import { readFileSync as readFileSync6 } from "fs";
+import { readFileSync as readFileSync7 } from "fs";
 import { generateTest, loadTrace } from "@agent-scope/playwright";
-import { Command as Command6 } from "commander";
+import { Command as Command7 } from "commander";
 
 // src/browser.ts
 import { writeFileSync } from "fs";
@@ -255,9 +255,9 @@ function createRL() {
   });
 }
 async function ask(rl, question) {
-  return new Promise((resolve6) => {
+  return new Promise((resolve10) => {
     rl.question(question, (answer) => {
-      resolve6(answer.trim());
+      resolve10(answer.trim());
     });
   });
 }
@@ -406,7 +406,7 @@ function createInitCommand() {
 }
 
 // src/instrument/renders.ts
-import { resolve as resolve2 } from "path";
+import { resolve as resolve4 } from "path";
 import { BrowserPool } from "@agent-scope/render";
 import { Command as Command3 } from "commander";
 
@@ -957,8 +957,653 @@ function csvEscape(value) {
   return value;
 }
 
-// src/instrument/renders.ts
+// src/instrument/hooks.ts
+import { resolve as resolve2 } from "path";
+import { Command as Cmd } from "commander";
+import { chromium as chromium2 } from "playwright";
 var MANIFEST_PATH2 = ".reactscope/manifest.json";
+function buildHookInstrumentationScript() {
+  return `
+(function __scopeHooksInstrument() {
+  // Locate the React DevTools hook installed by the browser-entry bundle.
+  // We use a lighter approach: walk __REACT_DEVTOOLS_GLOBAL_HOOK__ renderers.
+  var hook = window.__REACT_DEVTOOLS_GLOBAL_HOOK__;
+  if (!hook) return { error: "No React DevTools hook found" };
+
+  var renderers = hook._renderers || hook.renderers;
+  if (!renderers || renderers.size === 0) return { error: "No React renderers registered" };
+
+  // Get the first renderer's fiber roots
+  var renderer = null;
+  if (renderers.forEach) {
+    renderers.forEach(function(r) { if (!renderer) renderer = r; });
+  } else {
+    renderer = Object.values(renderers)[0];
+  }
+
+  // Handle both our wrapped format {id, renderer, fiberRoots} and raw renderer
+  var fiberRoots;
+  if (renderer && renderer.fiberRoots) {
+    fiberRoots = renderer.fiberRoots;
+  } else {
+    return { error: "No fiber roots found" };
+  }
+
+  var rootFiber = null;
+  fiberRoots.forEach(function(r) { if (!rootFiber) rootFiber = r; });
+  if (!rootFiber) return { error: "No fiber root" };
+
+  var current = rootFiber.current;
+  if (!current) return { error: "No current fiber" };
+
+  // Walk fiber tree and collect hook data per component
+  var components = [];
+
+  function serializeValue(v) {
+    if (v === null) return null;
+    if (v === undefined) return undefined;
+    var t = typeof v;
+    if (t === "string" || t === "number" || t === "boolean") return v;
+    if (t === "function") return "[function " + (v.name || "anonymous") + "]";
+    if (Array.isArray(v)) {
+      try { return v.map(serializeValue); } catch(e) { return "[Array]"; }
+    }
+    if (t === "object") {
+      try {
+        var keys = Object.keys(v).slice(0, 5);
+        var out = {};
+        for (var k of keys) { out[k] = serializeValue(v[k]); }
+        if (Object.keys(v).length > 5) out["..."] = "(truncated)";
+        return out;
+      } catch(e) { return "[Object]"; }
+    }
+    return String(v);
+  }
+
+  // Hook node classifiers (mirrors hooks-extractor.ts logic)
+  var HookLayout = 0b00100;
+
+  function isEffectNode(node) {
+    var ms = node.memoizedState;
+    if (!ms || typeof ms !== "object") return false;
+    return typeof ms.create === "function" && "deps" in ms && typeof ms.tag === "number";
+  }
+
+  function isRefNode(node) {
+    if (node.queue != null) return false;
+    var ms = node.memoizedState;
+    if (!ms || typeof ms !== "object" || Array.isArray(ms)) return false;
+    var keys = Object.keys(ms);
+    return keys.length === 1 && keys[0] === "current";
+  }
+
+  function isMemoTuple(node) {
+    if (node.queue != null) return false;
+    var ms = node.memoizedState;
+    if (!Array.isArray(ms) || ms.length !== 2) return false;
+    return ms[1] === null || Array.isArray(ms[1]);
+  }
+
+  function isStateOrReducer(node) {
+    return node.queue != null &&
+      typeof node.queue === "object" &&
+      typeof node.queue.dispatch === "function";
+  }
+
+  function isReducer(node) {
+    if (!isStateOrReducer(node)) return false;
+    var q = node.queue;
+    if (typeof q.reducer === "function") return true;
+    var lrr = q.lastRenderedReducer;
+    if (typeof lrr !== "function") return false;
+    var name = lrr.name || "";
+    return name !== "basicStateReducer" && name !== "";
+  }
+
+  function classifyHookNode(node, index) {
+    var profile = { index: index, type: "custom" };
+
+    if (isEffectNode(node)) {
+      var effect = node.memoizedState;
+      profile.type = (effect.tag & HookLayout) ? "useLayoutEffect" : "useEffect";
+      profile.dependencyValues = effect.deps ? effect.deps.map(serializeValue) : null;
+      profile.cleanupPresence = typeof effect.destroy === "function";
+      profile.fireCount = 1; // We can only observe the mount; runtime tracking would need injection
+      profile.lastDuration = null;
+      return profile;
+    }
+
+    if (isRefNode(node)) {
+      var ref = node.memoizedState;
+      profile.type = "useRef";
+      profile.currentRefValue = serializeValue(ref.current);
+      profile.readCountDuringRender = 0; // static snapshot; read count requires instrumented wrapper
+      return profile;
+    }
+
+    if (isMemoTuple(node)) {
+      var tuple = node.memoizedState;
+      var val = tuple[0];
+      var deps = tuple[1];
+      profile.type = typeof val === "function" ? "useCallback" : "useMemo";
+      profile.currentValue = serializeValue(val);
+      profile.dependencyValues = deps ? deps.map(serializeValue) : null;
+      // recomputeCount cannot be known from a single snapshot; set to 0 for mount
+      profile.recomputeCount = 0;
+      // On mount, first render always computes \u2192 cacheHitRate is 0 (no prior hits)
+      profile.cacheHitRate = 0;
+      return profile;
+    }
+
+    if (isStateOrReducer(node)) {
+      if (isReducer(node)) {
+        profile.type = "useReducer";
+        profile.currentValue = serializeValue(node.memoizedState);
+        profile.updateCount = 0;
+        profile.actionTypesDispatched = [];
+        // stateTransitions: we record current state as first entry
+        profile.stateTransitions = [serializeValue(node.memoizedState)];
+      } else {
+        profile.type = "useState";
+        profile.currentValue = serializeValue(node.memoizedState);
+        profile.updateCount = 0;
+        profile.updateOrigins = [];
+      }
+      return profile;
+    }
+
+    // useContext: detected via _currentValue / _currentValue2 property (React context internals)
+    // Context consumers in React store the context VALUE in memoizedState directly, not
+    // via a queue. Context objects themselves have _currentValue.
+    // We check if memoizedState could be a context value by seeing if node has no queue
+    // and memoizedState is not an array and not an effect.
+    if (!node.queue && !isRefNode(node) && !isMemoTuple(node) && !isEffectNode(node)) {
+      profile.type = "custom";
+      profile.currentValue = serializeValue(node.memoizedState);
+      return profile;
+    }
+
+    return profile;
+  }
+
+  // Walk the fiber tree
+  var FunctionComponent = 0;
+  var ClassComponent = 1;
+  var ForwardRef = 11;
+  var MemoComponent = 14;
+  var SimpleMemoComponent = 15;
+  var HostRoot = 3;
+
+  function getFiberName(fiber) {
+    if (!fiber.type) return null;
+    if (typeof fiber.type === "string") return fiber.type;
+    if (typeof fiber.type === "function") return fiber.type.displayName || fiber.type.name || "Anonymous";
+    if (fiber.type.displayName) return fiber.type.displayName;
+    if (fiber.type.render) {
+      return fiber.type.render.displayName || fiber.type.render.name || "ForwardRef";
+    }
+    if (fiber.type.type) {
+      return (fiber.type.type.displayName || fiber.type.type.name || "Memo");
+    }
+    return "Unknown";
+  }
+
+  function isComponentFiber(fiber) {
+    var tag = fiber.tag;
+    return tag === FunctionComponent || tag === ClassComponent ||
+           tag === ForwardRef || tag === MemoComponent || tag === SimpleMemoComponent;
+  }
+
+  function walkFiber(fiber) {
+    if (!fiber) return;
+
+    if (isComponentFiber(fiber)) {
+      var name = getFiberName(fiber);
+      if (name) {
+        var hooks = [];
+        var hookNode = fiber.memoizedState;
+        var idx = 0;
+        while (hookNode !== null && hookNode !== undefined) {
+          hooks.push(classifyHookNode(hookNode, idx));
+          hookNode = hookNode.next;
+          idx++;
+        }
+
+        var source = null;
+        if (fiber._debugSource) {
+          source = { file: fiber._debugSource.fileName, line: fiber._debugSource.lineNumber };
+        }
+
+        if (hooks.length > 0) {
+          components.push({ name: name, source: source, hooks: hooks });
+        }
+      }
+    }
+
+    walkFiber(fiber.child);
+    walkFiber(fiber.sibling);
+  }
+
+  walkFiber(current.child);
+
+  return { components: components };
+})();
+`;
+}
+function analyzeHookFlags(hooks) {
+  const flags = /* @__PURE__ */ new Set();
+  for (const hook of hooks) {
+    if ((hook.type === "useEffect" || hook.type === "useLayoutEffect") && hook.dependencyValues !== void 0 && hook.dependencyValues === null) {
+      flags.add("EFFECT_EVERY_RENDER");
+    }
+    if ((hook.type === "useEffect" || hook.type === "useLayoutEffect") && hook.cleanupPresence === false && hook.dependencyValues === null) {
+      flags.add("MISSING_CLEANUP");
+    }
+    if ((hook.type === "useMemo" || hook.type === "useCallback") && hook.dependencyValues === null) {
+      flags.add("MEMO_INEFFECTIVE");
+    }
+    if ((hook.type === "useMemo" || hook.type === "useCallback") && hook.cacheHitRate !== void 0 && hook.cacheHitRate === 0 && hook.recomputeCount !== void 0 && hook.recomputeCount > 1) {
+      flags.add("MEMO_INEFFECTIVE");
+    }
+    if ((hook.type === "useState" || hook.type === "useReducer") && hook.updateCount !== void 0 && hook.updateCount > 10) {
+      flags.add("STATE_UPDATE_LOOP");
+    }
+  }
+  return [...flags];
+}
+async function runHooksProfiling(componentName, filePath, props) {
+  const browser = await chromium2.launch({ headless: true });
+  try {
+    const context = await browser.newContext();
+    const page = await context.newPage();
+    const htmlHarness = await buildComponentHarness(filePath, componentName, props, 1280);
+    await page.setContent(htmlHarness, { waitUntil: "load" });
+    await page.waitForFunction(
+      () => {
+        const w = window;
+        return w.__SCOPE_RENDER_COMPLETE__ === true;
+      },
+      { timeout: 15e3 }
+    );
+    const renderError = await page.evaluate(() => {
+      return window.__SCOPE_RENDER_ERROR__ ?? null;
+    });
+    if (renderError !== null) {
+      throw new Error(`Component render error: ${renderError}`);
+    }
+    const instrumentScript = buildHookInstrumentationScript();
+    const raw = await page.evaluate(instrumentScript);
+    const result = raw;
+    if (result.error) {
+      throw new Error(`Hook instrumentation failed: ${result.error}`);
+    }
+    const rawComponents = result.components ?? [];
+    const components = rawComponents.map((c) => ({
+      name: c.name,
+      source: c.source,
+      hooks: c.hooks,
+      flags: analyzeHookFlags(c.hooks)
+    }));
+    const allFlags = /* @__PURE__ */ new Set();
+    for (const comp of components) {
+      for (const flag of comp.flags) {
+        allFlags.add(flag);
+      }
+    }
+    return {
+      component: componentName,
+      components,
+      flags: [...allFlags]
+    };
+  } finally {
+    await browser.close();
+  }
+}
+function createInstrumentHooksCommand() {
+  const cmd = new Cmd("hooks").description(
+    "Profile per-hook-instance data for a component: update counts, cache hit rates, effect counts, and more"
+  ).argument("<component>", "Component name (must exist in the manifest)").option("--props <json>", "Inline props JSON passed to the component", "{}").option("--manifest <path>", "Path to manifest.json", MANIFEST_PATH2).option("--format <fmt>", "Output format: json|text (default: auto)", "json").option("--show-flags", "Show heuristic flags only (useful for CI checks)", false).action(
+    async (componentName, opts) => {
+      try {
+        const manifest = loadManifest(opts.manifest);
+        const descriptor = manifest.components[componentName];
+        if (descriptor === void 0) {
+          const available = Object.keys(manifest.components).slice(0, 5).join(", ");
+          throw new Error(
+            `Component "${componentName}" not found in manifest.
+Available: ${available}`
+          );
+        }
+        let props = {};
+        try {
+          props = JSON.parse(opts.props);
+        } catch {
+          throw new Error(`Invalid props JSON: ${opts.props}`);
+        }
+        const rootDir = process.cwd();
+        const filePath = resolve2(rootDir, descriptor.filePath);
+        process.stderr.write(`Instrumenting hooks for ${componentName}\u2026
+`);
+        const result = await runHooksProfiling(componentName, filePath, props);
+        if (opts.showFlags) {
+          if (result.flags.length === 0) {
+            process.stdout.write("No heuristic flags detected.\n");
+          } else {
+            for (const flag of result.flags) {
+              process.stdout.write(`${flag}
+`);
+            }
+          }
+          return;
+        }
+        process.stdout.write(`${JSON.stringify(result, null, 2)}
+`);
+      } catch (err) {
+        process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}
+`);
+        process.exit(1);
+      }
+    }
+  );
+  return cmd;
+}
+
+// src/instrument/profile.ts
+import { resolve as resolve3 } from "path";
+import { Command as Cmd2 } from "commander";
+import { chromium as chromium3 } from "playwright";
+var MANIFEST_PATH3 = ".reactscope/manifest.json";
+function buildProfilingSetupScript() {
+  return `
+(function __scopeProfileSetup() {
+  window.__scopeProfileData = {
+    commitCount: 0,
+    componentNames: new Set(),
+    fiberSnapshots: []
+  };
+
+  var hook = window.__REACT_DEVTOOLS_GLOBAL_HOOK__;
+  if (!hook) return { error: "No DevTools hook" };
+
+  // Wrap onCommitFiberRoot to count commits and collect component names
+  var origCommit = hook.onCommitFiberRoot.bind(hook);
+  hook.onCommitFiberRoot = function(rendererID, root, priorityLevel) {
+    origCommit(rendererID, root, priorityLevel);
+
+    window.__scopeProfileData.commitCount++;
+
+    // Walk the committed tree to collect re-rendered component names
+    var current = root && root.current;
+    if (!current) return;
+
+    function walkFiber(fiber) {
+      if (!fiber) return;
+      var tag = fiber.tag;
+      // FunctionComponent=0, ClassComponent=1, ForwardRef=11, Memo=14, SimpleMemo=15
+      if (tag === 0 || tag === 1 || tag === 11 || tag === 14 || tag === 15) {
+        var name = null;
+        if (fiber.type) {
+          if (typeof fiber.type === "function") name = fiber.type.displayName || fiber.type.name;
+          else if (fiber.type.displayName) name = fiber.type.displayName;
+          else if (fiber.type.render) name = fiber.type.render.displayName || fiber.type.render.name;
+          else if (fiber.type.type) name = fiber.type.type.displayName || fiber.type.type.name;
+        }
+        // Only count fibers with a positive actualDuration (actually re-rendered this commit)
+        if (name && typeof fiber.actualDuration === "number" && fiber.actualDuration >= 0) {
+          window.__scopeProfileData.componentNames.add(name);
+        }
+      }
+      walkFiber(fiber.child);
+      walkFiber(fiber.sibling);
+    }
+
+    var wip = root.current.alternate || root.current;
+    walkFiber(wip.child);
+  };
+
+  // Install PerformanceObserver for layout and paint timing
+  window.__scopeLayoutTime = 0;
+  window.__scopePaintTime = 0;
+  window.__scopeLayoutShifts = { count: 0, score: 0 };
+
+  try {
+    var observer = new PerformanceObserver(function(list) {
+      for (var entry of list.getEntries()) {
+        if (entry.entryType === "layout-shift") {
+          window.__scopeLayoutShifts.count++;
+          window.__scopeLayoutShifts.score += entry.value || 0;
+        }
+        if (entry.entryType === "longtask") {
+          window.__scopeLayoutTime += entry.duration || 0;
+        }
+        if (entry.entryType === "paint") {
+          window.__scopePaintTime += entry.startTime || 0;
+        }
+      }
+    });
+    observer.observe({ entryTypes: ["layout-shift", "longtask", "paint"] });
+  } catch(e) {
+    // PerformanceObserver may not be available in all Playwright contexts
+  }
+
+  return { ok: true };
+})();
+`;
+}
+function buildProfilingCollectScript() {
+  return `
+(function __scopeProfileCollect() {
+  var data = window.__scopeProfileData;
+  if (!data) return { error: "Profiling not set up" };
+
+  // Estimate wasted renders: use paint entries count as a heuristic for
+  // "components that re-rendered but their subtree output was likely unchanged".
+  // A more accurate method would require React's own wasted-render detection,
+  // which requires React Profiler API. We use a conservative estimate here.
+  var totalCommits = data.commitCount;
+  var uniqueNames = Array.from(data.componentNames);
+
+  // Wasted renders heuristic: if a component is in a subsequent commit (not the initial
+  // mount commit), it *may* have been wasted if it didn't actually need to re-render.
+  // For the initial snapshot we approximate: wastedRenders = max(0, totalCommits - 1) * 0.3
+  // This is a heuristic \u2014 real wasted render detection needs shouldComponentUpdate/React.memo tracing.
+  var wastedRenders = Math.max(0, Math.round((totalCommits - 1) * uniqueNames.length * 0.3));
+
+  return {
+    commitCount: totalCommits,
+    uniqueComponents: uniqueNames.length,
+    componentNames: uniqueNames,
+    wastedRenders: wastedRenders,
+    layoutTime: window.__scopeLayoutTime || 0,
+    paintTime: window.__scopePaintTime || 0,
+    layoutShifts: window.__scopeLayoutShifts || { count: 0, score: 0 }
+  };
+})();
+`;
+}
+async function replayInteraction(page, steps) {
+  for (const step of steps) {
+    switch (step.action) {
+      case "click":
+        if (step.target) {
+          await page.click(step.target, { timeout: 5e3 }).catch(() => {
+            process.stderr.write(`  \u26A0 click target "${step.target}" not found, skipping
+`);
+          });
+        }
+        break;
+      case "fill":
+        if (step.target && step.value !== void 0) {
+          await page.fill(step.target, step.value, { timeout: 5e3 }).catch(() => {
+            process.stderr.write(`  \u26A0 fill target "${step.target}" not found, skipping
+`);
+          });
+        }
+        break;
+      case "hover":
+        if (step.target) {
+          await page.hover(step.target, { timeout: 5e3 }).catch(() => {
+            process.stderr.write(`  \u26A0 hover target "${step.target}" not found, skipping
+`);
+          });
+        }
+        break;
+      case "press":
+        if (step.value) {
+          await page.keyboard.press(step.value);
+        }
+        break;
+      case "wait":
+        await page.waitForTimeout(step.delay ?? 500);
+        break;
+    }
+  }
+}
+function analyzeProfileFlags(totalRenders, wastedRenders, timing, layoutShifts) {
+  const flags = /* @__PURE__ */ new Set();
+  if (wastedRenders > 0 && wastedRenders / Math.max(1, totalRenders) > 0.3) {
+    flags.add("WASTED_RENDER");
+  }
+  if (totalRenders > 10) {
+    flags.add("HIGH_RENDER_COUNT");
+  }
+  if (layoutShifts.cumulativeScore > 0.1) {
+    flags.add("LAYOUT_SHIFT_DETECTED");
+  }
+  if (timing.js > 100) {
+    flags.add("SLOW_INTERACTION");
+  }
+  return [...flags];
+}
+async function runInteractionProfile(componentName, filePath, props, interaction) {
+  const browser = await chromium3.launch({ headless: true });
+  try {
+    const context = await browser.newContext();
+    const page = await context.newPage();
+    const htmlHarness = await buildComponentHarness(filePath, componentName, props, 1280);
+    await page.setContent(htmlHarness, { waitUntil: "load" });
+    await page.waitForFunction(
+      () => {
+        const w = window;
+        return w.__SCOPE_RENDER_COMPLETE__ === true;
+      },
+      { timeout: 15e3 }
+    );
+    const renderError = await page.evaluate(() => {
+      return window.__SCOPE_RENDER_ERROR__ ?? null;
+    });
+    if (renderError !== null) {
+      throw new Error(`Component render error: ${renderError}`);
+    }
+    const setupResult = await page.evaluate(buildProfilingSetupScript());
+    const setupData = setupResult;
+    if (setupData.error) {
+      throw new Error(`Profiling setup failed: ${setupData.error}`);
+    }
+    const jsStart = Date.now();
+    if (interaction.length > 0) {
+      process.stderr.write(`  Replaying ${interaction.length} interaction step(s)\u2026
+`);
+      await replayInteraction(page, interaction);
+      await page.waitForTimeout(300);
+    }
+    const jsDuration = Date.now() - jsStart;
+    const collected = await page.evaluate(buildProfilingCollectScript());
+    const profileData = collected;
+    if (profileData.error) {
+      throw new Error(`Profile collection failed: ${profileData.error}`);
+    }
+    const timing = {
+      js: jsDuration,
+      layout: profileData.layoutTime ?? 0,
+      paint: profileData.paintTime ?? 0
+    };
+    const layoutShifts = {
+      count: profileData.layoutShifts?.count ?? 0,
+      cumulativeScore: profileData.layoutShifts?.score ?? 0
+    };
+    const totalRenders = profileData.commitCount ?? 0;
+    const uniqueComponents = profileData.uniqueComponents ?? 0;
+    const wastedRenders = profileData.wastedRenders ?? 0;
+    const flags = analyzeProfileFlags(totalRenders, wastedRenders, timing, layoutShifts);
+    return {
+      component: componentName,
+      totalRenders,
+      uniqueComponents,
+      wastedRenders,
+      timing,
+      layoutShifts,
+      flags,
+      interaction
+    };
+  } finally {
+    await browser.close();
+  }
+}
+function createInstrumentProfileCommand() {
+  const cmd = new Cmd2("profile").description(
+    "Capture a full interaction-scoped performance profile: renders, timing, layout shifts"
+  ).argument("<component>", "Component name (must exist in the manifest)").option(
+    "--interaction <json>",
+    `Interaction steps JSON, e.g. '[{"action":"click","target":"button.primary"}]'`,
+    "[]"
+  ).option("--props <json>", "Inline props JSON passed to the component", "{}").option("--manifest <path>", "Path to manifest.json", MANIFEST_PATH3).option("--format <fmt>", "Output format: json|text (default: json)", "json").option("--show-flags", "Show heuristic flags only (useful for CI checks)", false).action(
+    async (componentName, opts) => {
+      try {
+        const manifest = loadManifest(opts.manifest);
+        const descriptor = manifest.components[componentName];
+        if (descriptor === void 0) {
+          const available = Object.keys(manifest.components).slice(0, 5).join(", ");
+          throw new Error(
+            `Component "${componentName}" not found in manifest.
+Available: ${available}`
+          );
+        }
+        let props = {};
+        try {
+          props = JSON.parse(opts.props);
+        } catch {
+          throw new Error(`Invalid props JSON: ${opts.props}`);
+        }
+        let interaction = [];
+        try {
+          interaction = JSON.parse(opts.interaction);
+          if (!Array.isArray(interaction)) {
+            throw new Error("Interaction must be a JSON array");
+          }
+        } catch {
+          throw new Error(`Invalid interaction JSON: ${opts.interaction}`);
+        }
+        const rootDir = process.cwd();
+        const filePath = resolve3(rootDir, descriptor.filePath);
+        process.stderr.write(`Profiling interaction for ${componentName}\u2026
+`);
+        const result = await runInteractionProfile(componentName, filePath, props, interaction);
+        if (opts.showFlags) {
+          if (result.flags.length === 0) {
+            process.stdout.write("No heuristic flags detected.\n");
+          } else {
+            for (const flag of result.flags) {
+              process.stdout.write(`${flag}
+`);
+            }
+          }
+          return;
+        }
+        process.stdout.write(`${JSON.stringify(result, null, 2)}
+`);
+      } catch (err) {
+        process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}
+`);
+        process.exit(1);
+      }
+    }
+  );
+  return cmd;
+}
+
+// src/instrument/renders.ts
+var MANIFEST_PATH4 = ".reactscope/manifest.json";
 function determineTrigger(event) {
   if (event.forceUpdate) return "force_update";
   if (event.stateChanged) return "state_change";
@@ -1203,7 +1848,7 @@ function buildInstrumentationScript() {
 `
   );
 }
-async function replayInteraction(page, steps) {
+async function replayInteraction2(page, steps) {
   for (const step of steps) {
     switch (step.action) {
       case "click":
@@ -1278,7 +1923,7 @@ async function shutdownPool() {
   }
 }
 async function analyzeRenders(options) {
-  const manifestPath = options.manifestPath ?? MANIFEST_PATH2;
+  const manifestPath = options.manifestPath ?? MANIFEST_PATH4;
   const manifest = loadManifest(manifestPath);
   const descriptor = manifest.components[options.componentName];
   if (descriptor === void 0) {
@@ -1289,7 +1934,7 @@ Available: ${available}`
     );
   }
   const rootDir = process.cwd();
-  const filePath = resolve2(rootDir, descriptor.filePath);
+  const filePath = resolve4(rootDir, descriptor.filePath);
   const htmlHarness = await buildComponentHarness(filePath, options.componentName, {}, 1280);
   const pool = await getPool();
   const slot = await pool.acquire();
@@ -1307,7 +1952,7 @@ Available: ${available}`
       window.__SCOPE_RENDER_EVENTS__ = [];
       window.__SCOPE_RENDER_INDEX__ = 0;
     });
-    await replayInteraction(page, options.interaction);
+    await replayInteraction2(page, options.interaction);
     await page.waitForTimeout(200);
     const interactionDurationMs = performance.now() - startMs;
     const rawEvents = await page.evaluate(() => {
@@ -1376,7 +2021,7 @@ function createInstrumentRendersCommand() {
     "--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(
+  ).option("--json", "Output as JSON regardless of TTY", false).option("--manifest <path>", "Path to manifest.json", MANIFEST_PATH4).action(
     async (componentName, opts) => {
       let interaction = [];
       try {
@@ -1421,12 +2066,14 @@ function createInstrumentCommand() {
     "Structured instrumentation commands for React component analysis"
   );
   instrumentCmd.addCommand(createInstrumentRendersCommand());
+  instrumentCmd.addCommand(createInstrumentHooksCommand());
+  instrumentCmd.addCommand(createInstrumentProfileCommand());
   return instrumentCmd;
 }
 
 // src/render-commands.ts
 import { mkdirSync as mkdirSync3, writeFileSync as writeFileSync4 } from "fs";
-import { resolve as resolve4 } from "path";
+import { resolve as resolve6 } from "path";
 import {
   ALL_CONTEXT_IDS,
   ALL_STRESS_IDS,
@@ -1442,7 +2089,7 @@ import { Command as Command4 } from "commander";
 // src/tailwind-css.ts
 import { existsSync as existsSync4, readFileSync as readFileSync4 } from "fs";
 import { createRequire } from "module";
-import { resolve as resolve3 } from "path";
+import { resolve as resolve5 } from "path";
 var CONFIG_FILENAMES = [
   ".reactscope/config.json",
   ".reactscope/config.js",
@@ -1459,14 +2106,14 @@ var STYLE_ENTRY_CANDIDATES = [
 var TAILWIND_IMPORT = /@import\s+["']tailwindcss["']\s*;?/;
 var compilerCache = null;
 function getCachedBuild(cwd) {
-  if (compilerCache !== null && resolve3(compilerCache.cwd) === resolve3(cwd)) {
+  if (compilerCache !== null && resolve5(compilerCache.cwd) === resolve5(cwd)) {
     return compilerCache.build;
   }
   return null;
 }
 function findStylesEntry(cwd) {
   for (const name of CONFIG_FILENAMES) {
-    const p = resolve3(cwd, name);
+    const p = resolve5(cwd, name);
     if (!existsSync4(p)) continue;
     try {
       if (name.endsWith(".json")) {
@@ -1475,28 +2122,28 @@ function findStylesEntry(cwd) {
         const scope = data.scope;
         const entry = scope?.stylesEntry ?? data.stylesEntry;
         if (typeof entry === "string") {
-          const full = resolve3(cwd, entry);
+          const full = resolve5(cwd, entry);
           if (existsSync4(full)) return full;
         }
       }
     } catch {
     }
   }
-  const pkgPath = resolve3(cwd, "package.json");
+  const pkgPath = resolve5(cwd, "package.json");
   if (existsSync4(pkgPath)) {
     try {
       const raw = readFileSync4(pkgPath, "utf-8");
       const pkg = JSON.parse(raw);
       const entry = pkg.scope?.stylesEntry;
       if (typeof entry === "string") {
-        const full = resolve3(cwd, entry);
+        const full = resolve5(cwd, entry);
         if (existsSync4(full)) return full;
       }
     } catch {
     }
   }
   for (const candidate of STYLE_ENTRY_CANDIDATES) {
-    const full = resolve3(cwd, candidate);
+    const full = resolve5(cwd, candidate);
     if (existsSync4(full)) {
       try {
         const content = readFileSync4(full, "utf-8");
@@ -1514,7 +2161,7 @@ async function getTailwindCompiler(cwd) {
   if (entryPath === null) return null;
   let compile;
   try {
-    const require2 = createRequire(resolve3(cwd, "package.json"));
+    const require2 = createRequire(resolve5(cwd, "package.json"));
     const tailwind = require2("tailwindcss");
     const fn = tailwind.compile;
     if (typeof fn !== "function") return null;
@@ -1525,8 +2172,8 @@ async function getTailwindCompiler(cwd) {
   const entryContent = readFileSync4(entryPath, "utf-8");
   const loadStylesheet = async (id, base) => {
     if (id === "tailwindcss") {
-      const nodeModules = resolve3(cwd, "node_modules");
-      const tailwindCssPath = resolve3(nodeModules, "tailwindcss", "index.css");
+      const nodeModules = resolve5(cwd, "node_modules");
+      const tailwindCssPath = resolve5(nodeModules, "tailwindcss", "index.css");
       if (!existsSync4(tailwindCssPath)) {
         throw new Error(
           `Tailwind v4: tailwindcss package not found at ${tailwindCssPath}. Install with: npm install tailwindcss`
@@ -1535,10 +2182,10 @@ async function getTailwindCompiler(cwd) {
       const content = readFileSync4(tailwindCssPath, "utf-8");
       return { path: "virtual:tailwindcss/index.css", base, content };
     }
-    const full = resolve3(base, id);
+    const full = resolve5(base, id);
     if (existsSync4(full)) {
       const content = readFileSync4(full, "utf-8");
-      return { path: full, base: resolve3(full, ".."), content };
+      return { path: full, base: resolve5(full, ".."), content };
     }
     throw new Error(`Tailwind v4: could not load stylesheet: ${id} (base: ${base})`);
   };
@@ -1560,7 +2207,7 @@ async function getCompiledCssForClasses(cwd, classes) {
 }
 
 // src/render-commands.ts
-var MANIFEST_PATH3 = ".reactscope/manifest.json";
+var MANIFEST_PATH5 = ".reactscope/manifest.json";
 var DEFAULT_OUTPUT_DIR = ".reactscope/renders";
 var _pool2 = null;
 async function getPool2(viewportWidth, viewportHeight) {
@@ -1685,7 +2332,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_PATH3).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_PATH5).action(
     async (componentName, opts) => {
       try {
         const manifest = loadManifest(opts.manifest);
@@ -1707,7 +2354,7 @@ Available: ${available}`
         }
         const { width, height } = parseViewport(opts.viewport);
         const rootDir = process.cwd();
-        const filePath = resolve4(rootDir, descriptor.filePath);
+        const filePath = resolve6(rootDir, descriptor.filePath);
         const renderer = buildRenderer(filePath, componentName, width, height);
         process.stderr.write(
           `Rendering ${componentName} [${descriptor.complexityClass}] at ${width}\xD7${height}\u2026
@@ -1737,7 +2384,7 @@ Available: ${available}`
         }
         const result = outcome.result;
         if (opts.output !== void 0) {
-          const outPath = resolve4(process.cwd(), opts.output);
+          const outPath = resolve6(process.cwd(), opts.output);
           writeFileSync4(outPath, result.screenshot);
           process.stdout.write(
             `\u2713 ${componentName} \u2192 ${opts.output} (${result.width}\xD7${result.height}, ${result.renderTimeMs.toFixed(0)}ms)
@@ -1751,9 +2398,9 @@ Available: ${available}`
           process.stdout.write(`${JSON.stringify(json, null, 2)}
 `);
         } else if (fmt === "file") {
-          const dir = resolve4(process.cwd(), DEFAULT_OUTPUT_DIR);
+          const dir = resolve6(process.cwd(), DEFAULT_OUTPUT_DIR);
           mkdirSync3(dir, { recursive: true });
-          const outPath = resolve4(dir, `${componentName}.png`);
+          const outPath = resolve6(dir, `${componentName}.png`);
           writeFileSync4(outPath, result.screenshot);
           const relPath = `${DEFAULT_OUTPUT_DIR}/${componentName}.png`;
           process.stdout.write(
@@ -1761,9 +2408,9 @@ Available: ${available}`
 `
           );
         } else {
-          const dir = resolve4(process.cwd(), DEFAULT_OUTPUT_DIR);
+          const dir = resolve6(process.cwd(), DEFAULT_OUTPUT_DIR);
           mkdirSync3(dir, { recursive: true });
-          const outPath = resolve4(dir, `${componentName}.png`);
+          const outPath = resolve6(dir, `${componentName}.png`);
           writeFileSync4(outPath, result.screenshot);
           const relPath = `${DEFAULT_OUTPUT_DIR}/${componentName}.png`;
           process.stdout.write(
@@ -1784,7 +2431,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_PATH3).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_PATH5).action(
     async (componentName, opts) => {
       try {
         const manifest = loadManifest(opts.manifest);
@@ -1799,7 +2446,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 = resolve4(rootDir, descriptor.filePath);
+        const filePath = resolve6(rootDir, descriptor.filePath);
         const renderer = buildRenderer(filePath, componentName, width, height);
         const axes = [];
         if (opts.axes !== void 0) {
@@ -1866,7 +2513,7 @@ Available: ${available}`
           const { SpriteSheetGenerator } = await import("@agent-scope/render");
           const gen = new SpriteSheetGenerator();
           const sheet = await gen.generate(result);
-          const spritePath = resolve4(process.cwd(), opts.sprite);
+          const spritePath = resolve6(process.cwd(), opts.sprite);
           writeFileSync4(spritePath, sheet.png);
           process.stderr.write(`Sprite sheet saved to ${spritePath}
 `);
@@ -1876,9 +2523,9 @@ Available: ${available}`
           const { SpriteSheetGenerator } = await import("@agent-scope/render");
           const gen = new SpriteSheetGenerator();
           const sheet = await gen.generate(result);
-          const dir = resolve4(process.cwd(), DEFAULT_OUTPUT_DIR);
+          const dir = resolve6(process.cwd(), DEFAULT_OUTPUT_DIR);
           mkdirSync3(dir, { recursive: true });
-          const outPath = resolve4(dir, `${componentName}-matrix.png`);
+          const outPath = resolve6(dir, `${componentName}-matrix.png`);
           writeFileSync4(outPath, sheet.png);
           const relPath = `${DEFAULT_OUTPUT_DIR}/${componentName}-matrix.png`;
           process.stdout.write(
@@ -1911,7 +2558,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_PATH3).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_PATH5).option("--format <fmt>", "Output format: json|png (default: png)", "png").action(
     async (opts) => {
       try {
         const manifest = loadManifest(opts.manifest);
@@ -1922,7 +2569,7 @@ function registerRenderAll(renderCmd) {
           return;
         }
         const concurrency = Math.max(1, parseInt(opts.concurrency, 10) || 4);
-        const outputDir = resolve4(process.cwd(), opts.outputDir);
+        const outputDir = resolve6(process.cwd(), opts.outputDir);
         mkdirSync3(outputDir, { recursive: true });
         const rootDir = process.cwd();
         process.stderr.write(`Rendering ${total} components (concurrency: ${concurrency})\u2026
@@ -1932,7 +2579,7 @@ function registerRenderAll(renderCmd) {
         const renderOne = async (name) => {
           const descriptor = manifest.components[name];
           if (descriptor === void 0) return;
-          const filePath = resolve4(rootDir, descriptor.filePath);
+          const filePath = resolve6(rootDir, descriptor.filePath);
           const renderer = buildRenderer(filePath, name, 375, 812);
           const outcome = await safeRender(
             () => renderer.renderCell({}, descriptor.complexityClass),
@@ -1955,7 +2602,7 @@ function registerRenderAll(renderCmd) {
               success: false,
               errorMessage: outcome.error.message
             });
-            const errPath = resolve4(outputDir, `${name}.error.json`);
+            const errPath = resolve6(outputDir, `${name}.error.json`);
             writeFileSync4(
               errPath,
               JSON.stringify(
@@ -1973,9 +2620,9 @@ function registerRenderAll(renderCmd) {
           }
           const result = outcome.result;
           results.push({ name, renderTimeMs: result.renderTimeMs, success: true });
-          const pngPath = resolve4(outputDir, `${name}.png`);
+          const pngPath = resolve6(outputDir, `${name}.png`);
           writeFileSync4(pngPath, result.screenshot);
-          const jsonPath = resolve4(outputDir, `${name}.json`);
+          const jsonPath = resolve6(outputDir, `${name}.json`);
           writeFileSync4(jsonPath, JSON.stringify(formatRenderJson(name, {}, result), null, 2));
           if (isTTY()) {
             process.stdout.write(
@@ -2047,6 +2694,332 @@ function createRenderCommand() {
   return renderCmd;
 }
 
+// src/report/baseline.ts
+import { existsSync as existsSync5, mkdirSync as mkdirSync4, rmSync, writeFileSync as writeFileSync5 } from "fs";
+import { resolve as resolve7 } from "path";
+import { generateManifest as generateManifest2 } from "@agent-scope/manifest";
+import { BrowserPool as BrowserPool3, safeRender as safeRender2 } from "@agent-scope/render";
+import { ComplianceEngine, TokenResolver } from "@agent-scope/tokens";
+var DEFAULT_BASELINE_DIR = ".reactscope/baseline";
+var _pool3 = null;
+async function getPool3(viewportWidth, viewportHeight) {
+  if (_pool3 === null) {
+    _pool3 = new BrowserPool3({
+      size: { browsers: 1, pagesPerBrowser: 4 },
+      viewportWidth,
+      viewportHeight
+    });
+    await _pool3.init();
+  }
+  return _pool3;
+}
+async function shutdownPool3() {
+  if (_pool3 !== null) {
+    await _pool3.close();
+    _pool3 = null;
+  }
+}
+async function renderComponent(filePath, componentName, props, viewportWidth, viewportHeight) {
+  const pool = await getPool3(viewportWidth, viewportHeight);
+  const htmlHarness = await buildComponentHarness(filePath, componentName, props, viewportWidth);
+  const slot = await pool.acquire();
+  const { page } = slot;
+  try {
+    await page.setContent(htmlHarness, { waitUntil: "load" });
+    await page.waitForFunction(
+      () => {
+        const w = window;
+        return w.__SCOPE_RENDER_COMPLETE__ === true;
+      },
+      { timeout: 15e3 }
+    );
+    const renderError = await page.evaluate(() => {
+      return window.__SCOPE_RENDER_ERROR__ ?? null;
+    });
+    if (renderError !== null) {
+      throw new Error(`Component render error: ${renderError}`);
+    }
+    const rootDir = process.cwd();
+    const classes = await page.evaluate(() => {
+      const set = /* @__PURE__ */ new Set();
+      document.querySelectorAll("[class]").forEach((el) => {
+        for (const c of el.className.split(/\s+/)) {
+          if (c) set.add(c);
+        }
+      });
+      return [...set];
+    });
+    const projectCss = await getCompiledCssForClasses(rootDir, classes);
+    if (projectCss != null && projectCss.length > 0) {
+      await page.addStyleTag({ content: projectCss });
+    }
+    const startMs = performance.now();
+    const rootLocator = page.locator("[data-reactscope-root]");
+    const boundingBox = await rootLocator.boundingBox();
+    if (boundingBox === null || boundingBox.width === 0 || boundingBox.height === 0) {
+      throw new Error(
+        `Component "${componentName}" rendered with zero bounding box \u2014 it may be invisible or not mounted`
+      );
+    }
+    const PAD = 24;
+    const MIN_W = 320;
+    const MIN_H = 200;
+    const clipX = Math.max(0, boundingBox.x - PAD);
+    const clipY = Math.max(0, boundingBox.y - PAD);
+    const rawW = boundingBox.width + PAD * 2;
+    const rawH = boundingBox.height + PAD * 2;
+    const clipW = Math.max(rawW, MIN_W);
+    const clipH = Math.max(rawH, MIN_H);
+    const safeW = Math.min(clipW, viewportWidth - clipX);
+    const safeH = Math.min(clipH, viewportHeight - clipY);
+    const screenshot = await page.screenshot({
+      clip: { x: clipX, y: clipY, width: safeW, height: safeH },
+      type: "png"
+    });
+    const computedStylesRaw = {};
+    const styles = await page.evaluate((sel) => {
+      const el = document.querySelector(sel);
+      if (el === null) return {};
+      const computed = window.getComputedStyle(el);
+      const out = {};
+      for (const prop of [
+        "display",
+        "width",
+        "height",
+        "color",
+        "backgroundColor",
+        "fontSize",
+        "fontFamily",
+        "padding",
+        "margin"
+      ]) {
+        out[prop] = computed.getPropertyValue(prop);
+      }
+      return out;
+    }, "[data-reactscope-root] > *");
+    computedStylesRaw["[data-reactscope-root] > *"] = styles;
+    const renderTimeMs = performance.now() - startMs;
+    return {
+      screenshot,
+      width: Math.round(safeW),
+      height: Math.round(safeH),
+      renderTimeMs,
+      computedStyles: computedStylesRaw
+    };
+  } finally {
+    pool.release(slot);
+  }
+}
+function extractComputedStyles(computedStylesRaw) {
+  const flat = {};
+  for (const styles of Object.values(computedStylesRaw)) {
+    Object.assign(flat, styles);
+  }
+  const colors = {};
+  const spacing = {};
+  const typography = {};
+  const borders = {};
+  const shadows = {};
+  for (const [prop, value] of Object.entries(flat)) {
+    if (prop === "color" || prop === "backgroundColor") {
+      colors[prop] = value;
+    } else if (prop === "padding" || prop === "margin") {
+      spacing[prop] = value;
+    } else if (prop === "fontSize" || prop === "fontFamily" || prop === "fontWeight" || prop === "lineHeight") {
+      typography[prop] = value;
+    } else if (prop === "borderRadius" || prop === "borderWidth") {
+      borders[prop] = value;
+    } else if (prop === "boxShadow") {
+      shadows[prop] = value;
+    }
+  }
+  return { colors, spacing, typography, borders, shadows };
+}
+async function runBaseline(options = {}) {
+  const {
+    outputDir = DEFAULT_BASELINE_DIR,
+    componentsGlob,
+    manifestPath,
+    viewportWidth = 375,
+    viewportHeight = 812
+  } = options;
+  const startTime = performance.now();
+  const rootDir = process.cwd();
+  const baselineDir = resolve7(rootDir, outputDir);
+  const rendersDir = resolve7(baselineDir, "renders");
+  if (existsSync5(baselineDir)) {
+    rmSync(baselineDir, { recursive: true, force: true });
+  }
+  mkdirSync4(rendersDir, { recursive: true });
+  let manifest;
+  if (manifestPath !== void 0) {
+    const { readFileSync: readFileSync8 } = await import("fs");
+    const absPath = resolve7(rootDir, manifestPath);
+    if (!existsSync5(absPath)) {
+      throw new Error(`Manifest not found at ${absPath}.`);
+    }
+    manifest = JSON.parse(readFileSync8(absPath, "utf-8"));
+    process.stderr.write(`Loaded manifest from ${manifestPath}
+`);
+  } else {
+    process.stderr.write("Scanning for React components\u2026\n");
+    manifest = await generateManifest2({ rootDir });
+    const count = Object.keys(manifest.components).length;
+    process.stderr.write(`Found ${count} components.
+`);
+  }
+  writeFileSync5(resolve7(baselineDir, "manifest.json"), JSON.stringify(manifest, null, 2), "utf-8");
+  let componentNames = Object.keys(manifest.components);
+  if (componentsGlob !== void 0) {
+    componentNames = componentNames.filter((name) => matchGlob(componentsGlob, name));
+    process.stderr.write(
+      `Filtered to ${componentNames.length} components matching "${componentsGlob}".
+`
+    );
+  }
+  const total = componentNames.length;
+  if (total === 0) {
+    process.stderr.write("No components to baseline.\n");
+    const emptyReport = {
+      components: {},
+      totalProperties: 0,
+      totalOnSystem: 0,
+      totalOffSystem: 0,
+      aggregateCompliance: 1,
+      auditedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    writeFileSync5(
+      resolve7(baselineDir, "compliance.json"),
+      JSON.stringify(emptyReport, null, 2),
+      "utf-8"
+    );
+    return {
+      baselineDir,
+      componentCount: 0,
+      failureCount: 0,
+      wallClockMs: performance.now() - startTime
+    };
+  }
+  process.stderr.write(`Rendering ${total} components\u2026
+`);
+  const computedStylesMap = /* @__PURE__ */ new Map();
+  let completed = 0;
+  let failureCount = 0;
+  const CONCURRENCY = 4;
+  let nextIdx = 0;
+  const renderOne = async (name) => {
+    const descriptor = manifest.components[name];
+    if (descriptor === void 0) return;
+    const filePath = resolve7(rootDir, descriptor.filePath);
+    const outcome = await safeRender2(
+      () => renderComponent(filePath, name, {}, viewportWidth, viewportHeight),
+      {
+        props: {},
+        sourceLocation: {
+          file: descriptor.filePath,
+          line: descriptor.loc.start,
+          column: 0
+        }
+      }
+    );
+    completed++;
+    const pct = Math.round(completed / total * 100);
+    if (isTTY()) {
+      process.stderr.write(`${renderProgressBar(completed, total, name, pct)}\r`);
+    }
+    if (outcome.crashed) {
+      failureCount++;
+      const errPath = resolve7(rendersDir, `${name}.error.json`);
+      writeFileSync5(
+        errPath,
+        JSON.stringify(
+          {
+            component: name,
+            errorMessage: outcome.error.message,
+            heuristicFlags: outcome.error.heuristicFlags,
+            propsAtCrash: outcome.error.propsAtCrash
+          },
+          null,
+          2
+        ),
+        "utf-8"
+      );
+      return;
+    }
+    const result = outcome.result;
+    writeFileSync5(resolve7(rendersDir, `${name}.png`), result.screenshot);
+    const jsonOutput = formatRenderJson(name, {}, result);
+    writeFileSync5(
+      resolve7(rendersDir, `${name}.json`),
+      JSON.stringify(jsonOutput, null, 2),
+      "utf-8"
+    );
+    computedStylesMap.set(name, extractComputedStyles(result.computedStyles));
+  };
+  const worker = async () => {
+    while (nextIdx < componentNames.length) {
+      const i = nextIdx++;
+      const name = componentNames[i];
+      if (name !== void 0) {
+        await renderOne(name);
+      }
+    }
+  };
+  const workers = [];
+  for (let w = 0; w < Math.min(CONCURRENCY, total); w++) {
+    workers.push(worker());
+  }
+  await Promise.all(workers);
+  await shutdownPool3();
+  if (isTTY()) {
+    process.stderr.write("\n");
+  }
+  const resolver = new TokenResolver([]);
+  const engine = new ComplianceEngine(resolver);
+  const batchReport = engine.auditBatch(computedStylesMap);
+  writeFileSync5(
+    resolve7(baselineDir, "compliance.json"),
+    JSON.stringify(batchReport, null, 2),
+    "utf-8"
+  );
+  const wallClockMs = performance.now() - startTime;
+  const successCount = total - failureCount;
+  process.stderr.write(
+    `
+Baseline complete: ${successCount}/${total} components rendered` + (failureCount > 0 ? ` (${failureCount} failed)` : "") + ` in ${(wallClockMs / 1e3).toFixed(1)}s
+`
+  );
+  process.stderr.write(`Snapshot saved to ${baselineDir}
+`);
+  return { baselineDir, componentCount: total, failureCount, wallClockMs };
+}
+function registerBaselineSubCommand(reportCmd) {
+  reportCmd.command("baseline").description("Capture a baseline snapshot (manifest + renders + compliance) for later diffing").option(
+    "-o, --output <dir>",
+    "Output directory for the baseline snapshot",
+    DEFAULT_BASELINE_DIR
+  ).option("--components <glob>", "Glob pattern to baseline a subset of components").option("--manifest <path>", "Path to an existing manifest.json to use instead of regenerating").option("--viewport <WxH>", "Viewport size, e.g. 1280x720", "375x812").action(
+    async (opts) => {
+      try {
+        const [wStr, hStr] = opts.viewport.split("x");
+        const viewportWidth = Number.parseInt(wStr ?? "375", 10);
+        const viewportHeight = Number.parseInt(hStr ?? "812", 10);
+        await runBaseline({
+          outputDir: opts.output,
+          componentsGlob: opts.components,
+          manifestPath: opts.manifest,
+          viewportWidth,
+          viewportHeight
+        });
+      } catch (err) {
+        process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}
+`);
+        process.exit(1);
+      }
+    }
+  );
+}
+
 // src/tree-formatter.ts
 var BRANCH = "\u251C\u2500\u2500 ";
 var LAST_BRANCH = "\u2514\u2500\u2500 ";
@@ -2327,18 +3300,132 @@ function buildStructuredReport(report) {
 }
 
 // src/tokens/commands.ts
-import { existsSync as existsSync5, readFileSync as readFileSync5 } from "fs";
-import { resolve as resolve5 } from "path";
+import { existsSync as existsSync7, readFileSync as readFileSync6 } from "fs";
+import { resolve as resolve9 } from "path";
 import {
-  parseTokenFileSync,
+  parseTokenFileSync as parseTokenFileSync2,
   TokenParseError,
-  TokenResolver,
+  TokenResolver as TokenResolver3,
   TokenValidationError,
   validateTokenFile
 } from "@agent-scope/tokens";
+import { Command as Command6 } from "commander";
+
+// src/tokens/export.ts
+import { existsSync as existsSync6, readFileSync as readFileSync5, writeFileSync as writeFileSync6 } from "fs";
+import { resolve as resolve8 } from "path";
+import {
+  exportTokens,
+  parseTokenFileSync,
+  ThemeResolver,
+  TokenResolver as TokenResolver2
+} from "@agent-scope/tokens";
 import { Command as Command5 } from "commander";
 var DEFAULT_TOKEN_FILE = "reactscope.tokens.json";
 var CONFIG_FILE = "reactscope.config.json";
+var SUPPORTED_FORMATS = ["css", "ts", "scss", "tailwind", "flat-json", "figma"];
+function resolveTokenFilePath(fileFlag) {
+  if (fileFlag !== void 0) {
+    return resolve8(process.cwd(), fileFlag);
+  }
+  const configPath = resolve8(process.cwd(), CONFIG_FILE);
+  if (existsSync6(configPath)) {
+    try {
+      const raw = readFileSync5(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 resolve8(process.cwd(), file);
+      }
+    } catch {
+    }
+  }
+  return resolve8(process.cwd(), DEFAULT_TOKEN_FILE);
+}
+function createTokensExportCommand() {
+  return new Command5("export").description("Export design tokens to a downstream format").requiredOption("--format <fmt>", `Output format: ${SUPPORTED_FORMATS.join(", ")}`).option("--file <path>", "Path to token file (overrides config)").option("--out <path>", "Write output to file instead of stdout").option("--prefix <prefix>", "CSS/SCSS: prefix for variable names (e.g. 'scope')").option("--selector <selector>", "CSS: custom root selector (default: ':root')").option(
+    "--theme <name>",
+    "Include theme overrides for the named theme (applies to css, ts, scss, tailwind, figma)"
+  ).action(
+    (opts) => {
+      if (!SUPPORTED_FORMATS.includes(opts.format)) {
+        process.stderr.write(
+          `Error: unsupported format "${opts.format}".
+Supported formats: ${SUPPORTED_FORMATS.join(", ")}
+`
+        );
+        process.exit(1);
+      }
+      const format = opts.format;
+      try {
+        const filePath = resolveTokenFilePath(opts.file);
+        if (!existsSync6(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 = readFileSync5(filePath, "utf-8");
+        const { tokens, rawFile } = parseTokenFileSync(raw);
+        let themesMap;
+        if (opts.theme !== void 0) {
+          if (!rawFile.themes || !(opts.theme in rawFile.themes)) {
+            const available = rawFile.themes ? Object.keys(rawFile.themes).join(", ") : "none";
+            throw new Error(
+              `Theme "${opts.theme}" not found in token file.
+Available themes: ${available}`
+            );
+          }
+          const baseResolver = new TokenResolver2(tokens);
+          const themeResolver = ThemeResolver.fromTokenFile(
+            baseResolver,
+            rawFile
+          );
+          const themeNames = themeResolver.listThemes();
+          if (!themeNames.includes(opts.theme)) {
+            throw new Error(
+              `Theme "${opts.theme}" could not be resolved.
+Available themes: ${themeNames.join(", ")}`
+            );
+          }
+          const themedTokens = themeResolver.buildThemedTokens(opts.theme);
+          const overrideMap = /* @__PURE__ */ new Map();
+          for (const themedToken of themedTokens) {
+            const baseToken = tokens.find((t) => t.path === themedToken.path);
+            if (baseToken !== void 0 && themedToken.resolvedValue !== baseToken.resolvedValue) {
+              overrideMap.set(themedToken.path, themedToken.resolvedValue);
+            }
+          }
+          themesMap = /* @__PURE__ */ new Map([[opts.theme, overrideMap]]);
+        }
+        const output = exportTokens(tokens, format, {
+          prefix: opts.prefix,
+          rootSelector: opts.selector,
+          themes: themesMap
+        });
+        if (opts.out !== void 0) {
+          const outPath = resolve8(process.cwd(), opts.out);
+          writeFileSync6(outPath, output, "utf-8");
+          process.stderr.write(`Exported ${tokens.length} tokens to ${outPath}
+`);
+        } else {
+          process.stdout.write(output);
+          if (!output.endsWith("\n")) {
+            process.stdout.write("\n");
+          }
+        }
+      } catch (err) {
+        process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}
+`);
+        process.exit(1);
+      }
+    }
+  );
+}
+
+// src/tokens/commands.ts
+var DEFAULT_TOKEN_FILE2 = "reactscope.tokens.json";
+var CONFIG_FILE2 = "reactscope.config.json";
 function isTTY2() {
   return process.stdout.isTTY === true;
 }
@@ -2356,33 +3443,33 @@ function buildTable2(headers, rows) {
   );
   return [headerRow, divider, ...dataRows].join("\n");
 }
-function resolveTokenFilePath(fileFlag) {
+function resolveTokenFilePath2(fileFlag) {
   if (fileFlag !== void 0) {
-    return resolve5(process.cwd(), fileFlag);
+    return resolve9(process.cwd(), fileFlag);
   }
-  const configPath = resolve5(process.cwd(), CONFIG_FILE);
-  if (existsSync5(configPath)) {
+  const configPath = resolve9(process.cwd(), CONFIG_FILE2);
+  if (existsSync7(configPath)) {
     try {
-      const raw = readFileSync5(configPath, "utf-8");
+      const raw = readFileSync6(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);
+        return resolve9(process.cwd(), file);
       }
     } catch {
     }
   }
-  return resolve5(process.cwd(), DEFAULT_TOKEN_FILE);
+  return resolve9(process.cwd(), DEFAULT_TOKEN_FILE2);
 }
 function loadTokens(absPath) {
-  if (!existsSync5(absPath)) {
+  if (!existsSync7(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 = readFileSync5(absPath, "utf-8");
-  return parseTokenFileSync(raw);
+  const raw = readFileSync6(absPath, "utf-8");
+  return parseTokenFileSync2(raw);
 }
 function getRawValue(node, segments) {
   const [head, ...rest] = segments;
@@ -2419,9 +3506,9 @@ function buildResolutionChain(startPath, rawTokens) {
 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 filePath = resolveTokenFilePath2(opts.file);
       const { tokens } = loadTokens(filePath);
-      const resolver = new TokenResolver(tokens);
+      const resolver = new TokenResolver3(tokens);
       const resolvedValue = resolver.resolve(tokenPath);
       const useJson = opts.format === "json" || opts.format !== "text" && !isTTY2();
       if (useJson) {
@@ -2445,9 +3532,9 @@ 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 filePath = resolveTokenFilePath2(opts.file);
         const { tokens } = loadTokens(filePath);
-        const resolver = new TokenResolver(tokens);
+        const resolver = new TokenResolver3(tokens);
         const filtered = resolver.list(opts.type, category);
         const useJson = opts.format === "json" || opts.format !== "table" && !isTTY2();
         if (useJson) {
@@ -2475,9 +3562,9 @@ 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 filePath = resolveTokenFilePath2(opts.file);
         const { tokens } = loadTokens(filePath);
-        const resolver = new TokenResolver(tokens);
+        const resolver = new TokenResolver3(tokens);
         const useJson = opts.format === "json" || opts.format !== "table" && !isTTY2();
         const typesToSearch = opts.type ? [opts.type] : [
           "color",
@@ -2557,10 +3644,10 @@ Tip: use --fuzzy for nearest-match search.
 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 filePath = resolveTokenFilePath2(opts.file);
       const absFilePath = filePath;
       const { tokens, rawFile } = loadTokens(absFilePath);
-      const resolver = new TokenResolver(tokens);
+      const resolver = new TokenResolver3(tokens);
       resolver.resolve(tokenPath);
       const chain = buildResolutionChain(tokenPath, rawFile.tokens);
       const useJson = opts.format === "json" || opts.format !== "text" && !isTTY2();
@@ -2594,14 +3681,14 @@ function registerValidate(tokensCmd) {
     "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 (!existsSync5(filePath)) {
+      const filePath = resolveTokenFilePath2(opts.file);
+      if (!existsSync7(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 = readFileSync5(filePath, "utf-8");
+      const raw = readFileSync6(filePath, "utf-8");
       const useJson = opts.format === "json" || opts.format !== "text" && !isTTY2();
       const errors = [];
       let parsed;
@@ -2628,7 +3715,7 @@ Create a reactscope.tokens.json file or use --file to specify a path.`
         throw err;
       }
       try {
-        parseTokenFileSync(raw);
+        parseTokenFileSync2(raw);
       } catch (err) {
         if (err instanceof TokenParseError) {
           errors.push({ code: err.code, path: err.path, message: err.message });
@@ -2669,7 +3756,7 @@ function outputValidationResult(filePath, errors, useJson) {
   }
 }
 function createTokensCommand() {
-  const tokensCmd = new Command5("tokens").description(
+  const tokensCmd = new Command6("tokens").description(
     "Query and validate design tokens from a reactscope.tokens.json file"
   );
   registerGet2(tokensCmd);
@@ -2677,12 +3764,13 @@ function createTokensCommand() {
   registerSearch(tokensCmd);
   registerResolve(tokensCmd);
   registerValidate(tokensCmd);
+  tokensCmd.addCommand(createTokensExportCommand());
   return tokensCmd;
 }
 
 // src/program.ts
 function createProgram(options = {}) {
-  const program2 = new Command6("scope").version(options.version ?? "0.1.0").description("Scope \u2014 React instrumentation toolkit");
+  const program2 = new Command7("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 {
@@ -2755,7 +3843,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 = readFileSync6(tracePath, "utf-8");
+    const raw = readFileSync7(tracePath, "utf-8");
     const trace = loadTrace(raw);
     const source = generateTest(trace, {
       description: opts.description,
@@ -2769,6 +3857,10 @@ function createProgram(options = {}) {
   program2.addCommand(createTokensCommand());
   program2.addCommand(createInstrumentCommand());
   program2.addCommand(createInitCommand());
+  const existingReportCmd = program2.commands.find((c) => c.name() === "report");
+  if (existingReportCmd !== void 0) {
+    registerBaselineSubCommand(existingReportCmd);
+  }
   return program2;
 }