@agent-scope/cli 1.10.0 → 1.12.0

package/dist/index.js

@@ -2,13 +2,13 @@ import { existsSync, readFileSync, writeFileSync, mkdirSync, appendFileSync, rea
 import { join, resolve, dirname } from 'path';
 import * as readline from 'readline';
 import { Command } from 'commander';
+import { safeRender, ALL_CONTEXT_IDS, contextAxis, stressAxis, ALL_STRESS_IDS, RenderMatrix, BrowserPool, SatoriRenderer } from '@agent-scope/render';
+import * as esbuild from 'esbuild';
 import { generateManifest } from '@agent-scope/manifest';
-import { loadTrace, generateTest, getBrowserEntryScript } from '@agent-scope/playwright';
 import { chromium } from 'playwright';
-import { safeRender, ALL_CONTEXT_IDS, contextAxis, stressAxis, ALL_STRESS_IDS, RenderMatrix, SatoriRenderer, BrowserPool } from '@agent-scope/render';
-import * as esbuild from 'esbuild';
+import { loadTrace, generateTest, getBrowserEntryScript } from '@agent-scope/playwright';
 import { createRequire } from 'module';
-import { TokenResolver, validateTokenFile, TokenValidationError, parseTokenFileSync, TokenParseError, ComplianceEngine } from '@agent-scope/tokens';
+import { parseTokenFileSync, TokenResolver, ThemeResolver, exportTokens, validateTokenFile, TokenValidationError, TokenParseError, ComplianceEngine } from '@agent-scope/tokens';
 
 // src/init/index.ts
 function hasConfigFile(dir, stem) {
@@ -205,9 +205,9 @@ function createRL() {
   });
 }
 async function ask(rl, question) {
-  return new Promise((resolve7) => {
+  return new Promise((resolve11) => {
     rl.question(question, (answer) => {
-      resolve7(answer.trim());
+      resolve11(answer.trim());
     });
   });
 }
@@ -354,6 +354,114 @@ function createInitCommand() {
     }
   });
 }
+async function buildComponentHarness(filePath, componentName, props, viewportWidth, projectCss) {
+  const bundledScript = await bundleComponentToIIFE(filePath, componentName, props);
+  return wrapInHtml(bundledScript, viewportWidth);
+}
+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 = "";
+  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-formatter.ts
 function isTTY() {
@@ -621,168 +729,20 @@ function createManifestCommand() {
   registerGenerate(manifestCmd);
   return manifestCmd;
 }
-async function browserCapture(options) {
-  const { url, timeout = 1e4, wait = 0 } = options;
-  const browser = await chromium.launch({ headless: true });
-  try {
-    const context = await browser.newContext();
-    const page = await context.newPage();
-    await page.addInitScript({ content: getBrowserEntryScript() });
-    await page.goto(url, {
-      waitUntil: "networkidle",
-      timeout: timeout + 5e3
-    });
-    await page.waitForFunction(
-      () => {
-        return typeof window.__SCOPE_CAPTURE__ === "function" && (document.readyState === "complete" || document.readyState === "interactive");
-      },
-      { timeout }
-    );
-    if (wait > 0) {
-      await page.waitForTimeout(wait);
-    }
-    const raw = await page.evaluate(async () => {
-      const win = window;
-      if (typeof win.__SCOPE_CAPTURE__ !== "function") {
-        throw new Error("Scope runtime not injected");
-      }
-      return win.__SCOPE_CAPTURE__();
-    });
-    if (raw !== null && typeof raw === "object" && "error" in raw && typeof raw.error === "string") {
-      throw new Error(`Scope capture failed: ${raw.error}`);
-    }
-    const report = { ...raw, route: null };
-    return { report };
-  } finally {
-    await browser.close();
-  }
-}
-function writeReportToFile(report, outputPath, pretty) {
-  const json = pretty ? JSON.stringify(report, null, 2) : JSON.stringify(report);
-  writeFileSync(outputPath, json, "utf-8");
-}
-async function buildComponentHarness(filePath, componentName, props, viewportWidth, projectCss) {
-  const bundledScript = await bundleComponentToIIFE(filePath, componentName, props);
-  return wrapInHtml(bundledScript, viewportWidth);
-}
-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}`);
+// src/render-formatter.ts
+function parseViewport(spec) {
+  const lower = spec.toLowerCase();
+  const match = /^(\d+)[x×](\d+)$/.exec(lower);
+  if (!match) {
+    throw new Error(`Invalid viewport "${spec}". Expected format: WIDTHxHEIGHT (e.g. 1280x720)`);
   }
-  const outputFile = result.outputFiles?.[0];
-  if (outputFile === void 0 || outputFile.text.length === 0) {
-    throw new Error("esbuild produced no output");
+  const width = parseInt(match[1] ?? "0", 10);
+  const height = parseInt(match[2] ?? "0", 10);
+  if (width <= 0 || height <= 0) {
+    throw new Error(`Viewport dimensions must be positive integers, got: ${spec}`);
   }
-  return outputFile.text;
-}
-function wrapInHtml(bundledScript, viewportWidth, projectCss) {
-  const projectStyleBlock = "";
-  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();
-  const match = /^(\d+)[x×](\d+)$/.exec(lower);
-  if (!match) {
-    throw new Error(`Invalid viewport "${spec}". Expected format: WIDTHxHEIGHT (e.g. 1280x720)`);
-  }
-  const width = parseInt(match[1] ?? "0", 10);
-  const height = parseInt(match[2] ?? "0", 10);
-  if (width <= 0 || height <= 0) {
-    throw new Error(`Viewport dimensions must be positive integers, got: ${spec}`);
-  }
-  return { width, height };
+  return { width, height };
 }
 function formatRenderJson(componentName, props, result) {
   return {
@@ -917,21 +877,1011 @@ function formatSummaryText(results, outputDir) {
       }
     }
   }
-  lines.push("\u2500".repeat(60));
+  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;
+}
+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 chromium.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 Command("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 = resolve(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;
+}
+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 chromium.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 Command("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 = resolve(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;
+}
+var MANIFEST_PATH4 = ".reactscope/manifest.json";
+var DEFAULT_VIEWPORT_WIDTH = 375;
+var DEFAULT_VIEWPORT_HEIGHT = 812;
+var _pool = null;
+async function getPool() {
+  if (_pool === null) {
+    _pool = new BrowserPool({
+      size: { browsers: 1, pagesPerBrowser: 1 },
+      viewportWidth: DEFAULT_VIEWPORT_WIDTH,
+      viewportHeight: DEFAULT_VIEWPORT_HEIGHT
+    });
+    await _pool.init();
+  }
+  return _pool;
+}
+async function shutdownPool() {
+  if (_pool !== null) {
+    await _pool.close();
+    _pool = null;
+  }
+}
+function mapNodeType(node) {
+  if (node.type === "forward_ref") return "forwardRef";
+  if (node.type === "host") return "host";
+  const name = node.name;
+  if (name.endsWith(".Provider") || name === "Provider") return "context.provider";
+  if (name.endsWith(".Consumer") || name === "Consumer") return "context.consumer";
+  return node.type;
+}
+function flattenSerializedValue(sv) {
+  if (sv === null || sv === void 0) return null;
+  const v = sv;
+  switch (v.type) {
+    case "null":
+    case "undefined":
+      return null;
+    case "string":
+    case "number":
+    case "boolean":
+      return v.value;
+    case "object": {
+      if (!Array.isArray(v.entries)) return {};
+      const result = {};
+      for (const entry of v.entries) {
+        result[entry.key] = flattenSerializedValue(entry.value);
+      }
+      return result;
+    }
+    case "array": {
+      if (!Array.isArray(v.items)) return [];
+      return v.items.map(flattenSerializedValue);
+    }
+    case "function":
+      return "[Function]";
+    case "symbol":
+      return `[Symbol: ${v.description ?? ""}]`;
+    case "circular":
+      return "[Circular]";
+    case "truncated":
+      return `[Truncated: ${v.preview ?? ""}]`;
+    default:
+      return v.preview ?? null;
+  }
+}
+function flattenHookState(hooks) {
+  const result = {};
+  for (let i = 0; i < hooks.length; i++) {
+    const hook = hooks[i];
+    if (hook === void 0) continue;
+    const key = hook.name !== null && hook.name !== void 0 ? hook.name : `${hook.type}[${i}]`;
+    result[key] = flattenSerializedValue(hook.value);
+  }
+  return result;
+}
+function extractContextNames(contexts) {
+  const names = contexts.map((c) => c.contextName ?? "Unknown").filter((name, idx, arr) => arr.indexOf(name) === idx);
+  return names;
+}
+function anyContextChanged(contexts) {
+  return contexts.some((c) => c.didTriggerRender);
+}
+function convertToInstrumentNode(node, depth = 0) {
+  const contexts = extractContextNames(node.context);
+  const contextChanged = anyContextChanged(node.context);
+  const state = flattenHookState(node.state);
+  const propsFlat = flattenSerializedValue(node.props);
+  const props = propsFlat !== null && typeof propsFlat === "object" && !Array.isArray(propsFlat) ? propsFlat : {};
+  return {
+    component: node.name,
+    type: mapNodeType(node),
+    renderCount: node.renderCount,
+    lastRenderDuration: node.renderDuration,
+    memoized: node.type === "memo",
+    // memoSkipped requires tracking bail-outs across commits — not available from
+    // a single-shot capture. Defaulted to 0.
+    memoSkipped: 0,
+    props,
+    // propsChanged is not tracked in a single-shot capture — would need a diff
+    // between two renders. Defaulted to false.
+    propsChanged: false,
+    state,
+    stateChanged: false,
+    contextChanged,
+    contexts,
+    depth,
+    children: node.children.map((child) => convertToInstrumentNode(child, depth + 1))
+  };
+}
+function filterByContext(node, contextName) {
+  const filteredChildren = node.children.map((child) => filterByContext(child, contextName)).filter((c) => c !== null);
+  const selfMatches = node.contexts.some((c) => c.toLowerCase() === contextName.toLowerCase());
+  if (!selfMatches && filteredChildren.length === 0) return null;
+  return { ...node, children: filteredChildren };
+}
+function filterWastedRenders(node) {
+  const filteredChildren = node.children.map((child) => filterWastedRenders(child)).filter((c) => c !== null);
+  const isWasted = !node.propsChanged && !node.stateChanged && !node.contextChanged && !node.memoized && node.renderCount > 1;
+  if (!isWasted && filteredChildren.length === 0) return null;
+  return { ...node, children: filteredChildren };
+}
+function sortTree(node, sortBy) {
+  const sortedChildren = node.children.map((child) => sortTree(child, sortBy)).sort((a, b) => {
+    if (sortBy === "renderCount") return b.renderCount - a.renderCount;
+    return a.depth - b.depth;
+  });
+  return { ...node, children: sortedChildren };
+}
+function annotateProviderDepth(node, providerDepth = 0) {
+  const isProvider = node.type === "context.provider";
+  const childProviderDepth = isProvider ? providerDepth + 1 : providerDepth;
+  return {
+    ...node,
+    _providerDepth: providerDepth,
+    children: node.children.map((child) => annotateProviderDepth(child, childProviderDepth))
+  };
+}
+function limitNodes(root, limit) {
+  let remaining = limit;
+  const clip = (node) => {
+    if (remaining <= 0) return null;
+    remaining--;
+    const clippedChildren = [];
+    for (const child of node.children) {
+      const clipped = clip(child);
+      if (clipped !== null) clippedChildren.push(clipped);
+    }
+    return { ...node, children: clippedChildren };
+  };
+  return clip(root) ?? root;
+}
+var BRANCH = "\u251C\u2500\u2500 ";
+var LAST_BRANCH = "\u2514\u2500\u2500 ";
+var VERTICAL = "\u2502   ";
+var EMPTY = "    ";
+function buildTTYLabel(node, showProviderDepth) {
+  const parts = [node.component];
+  switch (node.type) {
+    case "memo":
+      parts.push("[memo]");
+      break;
+    case "forwardRef":
+      parts.push("[forwardRef]");
+      break;
+    case "class":
+      parts.push("[class]");
+      break;
+    case "context.provider":
+      parts.push("[provider]");
+      break;
+    case "context.consumer":
+      parts.push("[consumer]");
+      break;
+  }
+  if (node.renderCount > 0) {
+    const durationStr = node.lastRenderDuration > 0 ? ` ${node.lastRenderDuration.toFixed(2)}ms` : "";
+    parts.push(`(renders:${node.renderCount}${durationStr})`);
+  }
+  if (node.contexts.length > 0) {
+    parts.push(`[ctx:${node.contexts.join(",")}]`);
+  }
+  if (showProviderDepth) {
+    const pd = node._providerDepth;
+    if (pd !== void 0 && pd > 0) {
+      parts.push(`[pd:${pd}]`);
+    }
+  }
+  return parts.join(" ");
+}
+function renderTTYNode(node, prefix, isLast, showProviderDepth, lines) {
+  if (node.type === "host") {
+    for (let i = 0; i < node.children.length; i++) {
+      const child = node.children[i];
+      if (child !== void 0) {
+        renderTTYNode(child, prefix, i === node.children.length - 1, showProviderDepth, lines);
+      }
+    }
+    return;
+  }
+  const connector = isLast ? LAST_BRANCH : BRANCH;
+  lines.push(`${prefix}${connector}${buildTTYLabel(node, showProviderDepth)}`);
+  const nextPrefix = prefix + (isLast ? EMPTY : VERTICAL);
+  for (let i = 0; i < node.children.length; i++) {
+    const child = node.children[i];
+    if (child !== void 0) {
+      renderTTYNode(child, nextPrefix, i === node.children.length - 1, showProviderDepth, lines);
+    }
+  }
+}
+function formatInstrumentTree(root, showProviderDepth = false) {
+  const lines = [];
+  if (root.type !== "host") {
+    lines.push(buildTTYLabel(root, showProviderDepth));
+    for (let i = 0; i < root.children.length; i++) {
+      const child = root.children[i];
+      if (child !== void 0) {
+        renderTTYNode(child, "", i === root.children.length - 1, showProviderDepth, lines);
+      }
+    }
+  } else {
+    for (let i = 0; i < root.children.length; i++) {
+      const child = root.children[i];
+      if (child !== void 0) {
+        renderTTYNode(child, "", i === root.children.length - 1, showProviderDepth, lines);
+      }
+    }
+  }
   return lines.join("\n");
 }
-function escapeHtml(str) {
-  return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#039;");
+async function runInstrumentTree(options) {
+  const { componentName, filePath } = options;
+  const pool = await getPool();
+  const slot = await pool.acquire();
+  const { page } = slot;
+  try {
+    await page.addInitScript({ content: getBrowserEntryScript() });
+    const htmlHarness = await buildComponentHarness(
+      filePath,
+      componentName,
+      {},
+      DEFAULT_VIEWPORT_WIDTH
+    );
+    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(
+      () => window.__SCOPE_RENDER_ERROR__ ?? null
+    );
+    if (renderError !== null) {
+      throw new Error(`Component render error: ${renderError}`);
+    }
+    const captureJson = await page.evaluate(async () => {
+      const w = window;
+      if (typeof w.__SCOPE_CAPTURE_JSON__ !== "function") {
+        throw new Error("__SCOPE_CAPTURE_JSON__ not available \u2014 Scope runtime not injected");
+      }
+      return w.__SCOPE_CAPTURE_JSON__({ lightweight: false });
+    });
+    const captureResult = JSON.parse(captureJson);
+    const componentTree = captureResult.tree;
+    if (componentTree === void 0 || componentTree === null) {
+      throw new Error(`No component tree found for "${componentName}"`);
+    }
+    let instrumentRoot = convertToInstrumentNode(componentTree, 0);
+    if (options.usesContext !== void 0) {
+      const filtered = filterByContext(instrumentRoot, options.usesContext);
+      instrumentRoot = filtered !== null ? filtered : { ...instrumentRoot, children: [] };
+    }
+    if (options.wastedRenders === true) {
+      const filtered = filterWastedRenders(instrumentRoot);
+      instrumentRoot = filtered !== null ? filtered : { ...instrumentRoot, children: [] };
+    }
+    if (options.sortBy !== void 0) {
+      instrumentRoot = sortTree(instrumentRoot, options.sortBy);
+    }
+    if (options.providerDepth === true) {
+      instrumentRoot = annotateProviderDepth(instrumentRoot, 0);
+    }
+    if (options.limit !== void 0 && options.limit > 0) {
+      instrumentRoot = limitNodes(instrumentRoot, options.limit);
+    }
+    return instrumentRoot;
+  } finally {
+    pool.release(slot);
+  }
 }
-function csvEscape(value) {
-  if (value.includes(",") || value.includes('"') || value.includes("\n")) {
-    return `"${value.replace(/"/g, '""')}"`;
+function createInstrumentTreeCommand() {
+  return new Command("tree").description("Render a component via BrowserPool and output a structured instrumentation tree").argument("<component>", "Component name to instrument (must exist in the manifest)").option("--sort-by <field>", "Sort nodes by field: renderCount | depth").option("--limit <n>", "Limit output to the first N nodes (depth-first)").option("--uses-context <name>", "Filter to components that use a specific context").option("--provider-depth", "Annotate each node with its context-provider nesting depth", false).option(
+    "--wasted-renders",
+    "Filter to components with wasted renders (no prop/state/context changes, not memoized)",
+    false
+  ).option("--format <fmt>", "Output format: json | tree (default: auto)").option("--manifest <path>", "Path to manifest.json", MANIFEST_PATH4).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}`
+        );
+      }
+      if (opts.sortBy !== void 0) {
+        const allowed = ["renderCount", "depth"];
+        if (!allowed.includes(opts.sortBy)) {
+          throw new Error(
+            `Unknown --sort-by value "${opts.sortBy}". Allowed: ${allowed.join(", ")}`
+          );
+        }
+      }
+      const rootDir = process.cwd();
+      const filePath = resolve(rootDir, descriptor.filePath);
+      process.stderr.write(`Instrumenting ${componentName}\u2026
+`);
+      const instrumentRoot = await runInstrumentTree({
+        componentName,
+        filePath,
+        sortBy: opts.sortBy,
+        limit: opts.limit !== void 0 ? Math.max(1, parseInt(opts.limit, 10)) : void 0,
+        usesContext: opts.usesContext,
+        providerDepth: opts.providerDepth,
+        wastedRenders: opts.wastedRenders
+      });
+      await shutdownPool();
+      const fmt = resolveFormat2(opts.format);
+      if (fmt === "json") {
+        process.stdout.write(`${JSON.stringify(instrumentRoot, null, 2)}
+`);
+      } else {
+        const tree = formatInstrumentTree(instrumentRoot, opts.providerDepth ?? false);
+        process.stdout.write(`${tree}
+`);
+      }
+    } catch (err) {
+      await shutdownPool();
+      process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}
+`);
+      process.exit(1);
+    }
+  });
+}
+function resolveFormat2(formatFlag) {
+  if (formatFlag !== void 0) {
+    const lower = formatFlag.toLowerCase();
+    if (lower !== "json" && lower !== "tree") {
+      throw new Error(`Unknown format "${formatFlag}". Allowed: json, tree`);
+    }
+    return lower;
   }
-  return value;
+  return isTTY() ? "tree" : "json";
 }
 
 // src/instrument/renders.ts
-var MANIFEST_PATH2 = ".reactscope/manifest.json";
+var MANIFEST_PATH5 = ".reactscope/manifest.json";
 function determineTrigger(event) {
   if (event.forceUpdate) return "force_update";
   if (event.stateChanged) return "state_change";
@@ -1176,7 +2126,7 @@ function buildInstrumentationScript() {
 `
   );
 }
-async function replayInteraction(page, steps) {
+async function replayInteraction2(page, steps) {
   for (const step of steps) {
     switch (step.action) {
       case "click":
@@ -1230,26 +2180,26 @@ async function replayInteraction(page, steps) {
     }
   }
 }
-var _pool = null;
-async function getPool() {
-  if (_pool === null) {
-    _pool = new BrowserPool({
+var _pool2 = null;
+async function getPool2() {
+  if (_pool2 === null) {
+    _pool2 = new BrowserPool({
       size: { browsers: 1, pagesPerBrowser: 2 },
       viewportWidth: 1280,
       viewportHeight: 800
     });
-    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;
   }
 }
 async function analyzeRenders(options) {
-  const manifestPath = options.manifestPath ?? MANIFEST_PATH2;
+  const manifestPath = options.manifestPath ?? MANIFEST_PATH5;
   const manifest = loadManifest(manifestPath);
   const descriptor = manifest.components[options.componentName];
   if (descriptor === void 0) {
@@ -1262,7 +2212,7 @@ Available: ${available}`
   const rootDir = process.cwd();
   const filePath = resolve(rootDir, descriptor.filePath);
   const htmlHarness = await buildComponentHarness(filePath, options.componentName, {}, 1280);
-  const pool = await getPool();
+  const pool = await getPool2();
   const slot = await pool.acquire();
   const { page } = slot;
   const startMs = performance.now();
@@ -1278,7 +2228,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(() => {
@@ -1347,7 +2297,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_PATH5).action(
     async (componentName, opts) => {
       let interaction = [];
       try {
@@ -1370,7 +2320,7 @@ function createInstrumentRendersCommand() {
           interaction,
           manifestPath: opts.manifest
         });
-        await shutdownPool();
+        await shutdownPool2();
         if (opts.json || !isTTY()) {
           process.stdout.write(`${JSON.stringify(result, null, 2)}
 `);
@@ -1379,7 +2329,7 @@ function createInstrumentRendersCommand() {
 `);
         }
       } catch (err) {
-        await shutdownPool();
+        await shutdownPool2();
         process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}
 `);
         process.exit(1);
@@ -1392,8 +2342,51 @@ function createInstrumentCommand() {
     "Structured instrumentation commands for React component analysis"
   );
   instrumentCmd.addCommand(createInstrumentRendersCommand());
+  instrumentCmd.addCommand(createInstrumentHooksCommand());
+  instrumentCmd.addCommand(createInstrumentProfileCommand());
+  instrumentCmd.addCommand(createInstrumentTreeCommand());
   return instrumentCmd;
 }
+async function browserCapture(options) {
+  const { url, timeout = 1e4, wait = 0 } = options;
+  const browser = await chromium.launch({ headless: true });
+  try {
+    const context = await browser.newContext();
+    const page = await context.newPage();
+    await page.addInitScript({ content: getBrowserEntryScript() });
+    await page.goto(url, {
+      waitUntil: "networkidle",
+      timeout: timeout + 5e3
+    });
+    await page.waitForFunction(
+      () => {
+        return typeof window.__SCOPE_CAPTURE__ === "function" && (document.readyState === "complete" || document.readyState === "interactive");
+      },
+      { timeout }
+    );
+    if (wait > 0) {
+      await page.waitForTimeout(wait);
+    }
+    const raw = await page.evaluate(async () => {
+      const win = window;
+      if (typeof win.__SCOPE_CAPTURE__ !== "function") {
+        throw new Error("Scope runtime not injected");
+      }
+      return win.__SCOPE_CAPTURE__();
+    });
+    if (raw !== null && typeof raw === "object" && "error" in raw && typeof raw.error === "string") {
+      throw new Error(`Scope capture failed: ${raw.error}`);
+    }
+    const report = { ...raw, route: null };
+    return { report };
+  } finally {
+    await browser.close();
+  }
+}
+function writeReportToFile(report, outputPath, pretty) {
+  const json = pretty ? JSON.stringify(report, null, 2) : JSON.stringify(report);
+  writeFileSync(outputPath, json, "utf-8");
+}
 var CONFIG_FILENAMES = [
   ".reactscope/config.json",
   ".reactscope/config.js",
@@ -1511,24 +2504,24 @@ async function getCompiledCssForClasses(cwd, classes) {
 }
 
 // src/render-commands.ts
-var MANIFEST_PATH3 = ".reactscope/manifest.json";
+var MANIFEST_PATH6 = ".reactscope/manifest.json";
 var DEFAULT_OUTPUT_DIR = ".reactscope/renders";
-var _pool2 = null;
-async function getPool2(viewportWidth, viewportHeight) {
-  if (_pool2 === null) {
-    _pool2 = new BrowserPool({
+var _pool3 = null;
+async function getPool3(viewportWidth, viewportHeight) {
+  if (_pool3 === null) {
+    _pool3 = new BrowserPool({
       size: { browsers: 1, pagesPerBrowser: 4 },
       viewportWidth,
       viewportHeight
     });
-    await _pool2.init();
+    await _pool3.init();
   }
-  return _pool2;
+  return _pool3;
 }
-async function shutdownPool2() {
-  if (_pool2 !== null) {
-    await _pool2.close();
-    _pool2 = null;
+async function shutdownPool3() {
+  if (_pool3 !== null) {
+    await _pool3.close();
+    _pool3 = null;
   }
 }
 function buildRenderer(filePath, componentName, viewportWidth, viewportHeight) {
@@ -1539,7 +2532,7 @@ function buildRenderer(filePath, componentName, viewportWidth, viewportHeight) {
     _satori: satori,
     async renderCell(props, _complexityClass) {
       const startMs = performance.now();
-      const pool = await getPool2(viewportWidth, viewportHeight);
+      const pool = await getPool3(viewportWidth, viewportHeight);
       const htmlHarness = await buildComponentHarness(
         filePath,
         componentName,
@@ -1636,7 +2629,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_PATH6).action(
     async (componentName, opts) => {
       try {
         const manifest = loadManifest(opts.manifest);
@@ -1675,7 +2668,7 @@ Available: ${available}`
             }
           }
         );
-        await shutdownPool2();
+        await shutdownPool3();
         if (outcome.crashed) {
           process.stderr.write(`\u2717 Render failed: ${outcome.error.message}
 `);
@@ -1723,7 +2716,7 @@ Available: ${available}`
           );
         }
       } catch (err) {
-        await shutdownPool2();
+        await shutdownPool3();
         process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}
 `);
         process.exit(1);
@@ -1735,7 +2728,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_PATH6).action(
     async (componentName, opts) => {
       try {
         const manifest = loadManifest(opts.manifest);
@@ -1808,7 +2801,7 @@ Available: ${available}`
           concurrency
         });
         const result = await matrix.render();
-        await shutdownPool2();
+        await shutdownPool3();
         process.stderr.write(
           `Done. ${result.stats.totalCells} cells, avg ${result.stats.avgRenderTimeMs.toFixed(1)}ms
 `
@@ -1853,7 +2846,7 @@ Available: ${available}`
           process.stdout.write(formatMatrixCsv(componentName, result));
         }
       } catch (err) {
-        await shutdownPool2();
+        await shutdownPool3();
         process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}
 `);
         process.exit(1);
@@ -1862,7 +2855,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_PATH6).option("--format <fmt>", "Output format: json|png (default: png)", "png").action(
     async (opts) => {
       try {
         const manifest = loadManifest(opts.manifest);
@@ -1950,13 +2943,13 @@ function registerRenderAll(renderCmd) {
           workers.push(worker());
         }
         await Promise.all(workers);
-        await shutdownPool2();
+        await shutdownPool3();
         process.stderr.write("\n");
         const summary = formatSummaryText(results, outputDir);
         process.stderr.write(`${summary}
 `);
       } catch (err) {
-        await shutdownPool2();
+        await shutdownPool3();
         process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}
 `);
         process.exit(1);
@@ -1998,26 +2991,26 @@ function createRenderCommand() {
   return renderCmd;
 }
 var DEFAULT_BASELINE_DIR = ".reactscope/baseline";
-var _pool3 = null;
-async function getPool3(viewportWidth, viewportHeight) {
-  if (_pool3 === null) {
-    _pool3 = new BrowserPool({
+var _pool4 = null;
+async function getPool4(viewportWidth, viewportHeight) {
+  if (_pool4 === null) {
+    _pool4 = new BrowserPool({
       size: { browsers: 1, pagesPerBrowser: 4 },
       viewportWidth,
       viewportHeight
     });
-    await _pool3.init();
+    await _pool4.init();
   }
-  return _pool3;
+  return _pool4;
 }
-async function shutdownPool3() {
-  if (_pool3 !== null) {
-    await _pool3.close();
-    _pool3 = null;
+async function shutdownPool4() {
+  if (_pool4 !== null) {
+    await _pool4.close();
+    _pool4 = null;
   }
 }
 async function renderComponent(filePath, componentName, props, viewportWidth, viewportHeight) {
-  const pool = await getPool3(viewportWidth, viewportHeight);
+  const pool = await getPool4(viewportWidth, viewportHeight);
   const htmlHarness = await buildComponentHarness(filePath, componentName, props, viewportWidth);
   const slot = await pool.acquire();
   const { page } = slot;
@@ -2150,12 +3143,12 @@ async function runBaseline(options = {}) {
   mkdirSync(rendersDir, { recursive: true });
   let manifest;
   if (manifestPath !== void 0) {
-    const { readFileSync: readFileSync7 } = await import('fs');
+    const { readFileSync: readFileSync8 } = await import('fs');
     const absPath = resolve(rootDir, manifestPath);
     if (!existsSync(absPath)) {
       throw new Error(`Manifest not found at ${absPath}.`);
     }
-    manifest = JSON.parse(readFileSync7(absPath, "utf-8"));
+    manifest = JSON.parse(readFileSync8(absPath, "utf-8"));
     process.stderr.write(`Loaded manifest from ${manifestPath}
 `);
   } else {
@@ -2267,7 +3260,7 @@ async function runBaseline(options = {}) {
     workers.push(worker());
   }
   await Promise.all(workers);
-  await shutdownPool3();
+  await shutdownPool4();
   if (isTTY()) {
     process.stderr.write("\n");
   }
@@ -2318,10 +3311,10 @@ function registerBaselineSubCommand(reportCmd) {
 }
 
 // src/tree-formatter.ts
-var BRANCH = "\u251C\u2500\u2500 ";
-var LAST_BRANCH = "\u2514\u2500\u2500 ";
-var VERTICAL = "\u2502   ";
-var EMPTY = "    ";
+var BRANCH2 = "\u251C\u2500\u2500 ";
+var LAST_BRANCH2 = "\u2514\u2500\u2500 ";
+var VERTICAL2 = "\u2502   ";
+var EMPTY2 = "    ";
 function buildLabel(node, options) {
   const parts = [node.name];
   if (node.type === "memo") {
@@ -2368,19 +3361,19 @@ function renderNode(node, prefix, isLast, depth, options, lines) {
     }
     return;
   }
-  const connector = isLast ? LAST_BRANCH : BRANCH;
+  const connector = isLast ? LAST_BRANCH2 : BRANCH2;
   const label = buildLabel(node, options);
   lines.push(`${prefix}${connector}${label}`);
   if (options.maxDepth !== void 0 && depth >= options.maxDepth) {
     const childCount = countVisibleDescendants(node, options);
     if (childCount > 0) {
-      const nextPrefix2 = prefix + (isLast ? EMPTY : VERTICAL);
-      lines.push(`${nextPrefix2}${LAST_BRANCH}\u2026 (${childCount} more)`);
+      const nextPrefix2 = prefix + (isLast ? EMPTY2 : VERTICAL2);
+      lines.push(`${nextPrefix2}${LAST_BRANCH2}\u2026 (${childCount} more)`);
     }
     return;
   }
   const visibleChildren = getVisibleChildren(node, options);
-  const nextPrefix = prefix + (isLast ? EMPTY : VERTICAL);
+  const nextPrefix = prefix + (isLast ? EMPTY2 : VERTICAL2);
   for (let i = 0; i < visibleChildren.length; i++) {
     const child = visibleChildren[i];
     if (child !== void 0) {
@@ -2422,7 +3415,7 @@ function formatTree(root, options = {}) {
     if (options.maxDepth === 0) {
       const childCount = countVisibleDescendants(root, options);
       if (childCount > 0) {
-        lines.push(`${LAST_BRANCH}\u2026 (${childCount} more)`);
+        lines.push(`${LAST_BRANCH2}\u2026 (${childCount} more)`);
       }
     } else {
       const visibleChildren = getVisibleChildren(root, options);
@@ -2596,6 +3589,109 @@ function buildStructuredReport(report) {
 }
 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 resolve(process.cwd(), fileFlag);
+  }
+  const configPath = resolve(process.cwd(), CONFIG_FILE);
+  if (existsSync(configPath)) {
+    try {
+      const raw = readFileSync(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 resolve(process.cwd(), file);
+      }
+    } catch {
+    }
+  }
+  return resolve(process.cwd(), DEFAULT_TOKEN_FILE);
+}
+function createTokensExportCommand() {
+  return new Command("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 (!existsSync(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 = readFileSync(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 TokenResolver(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 = resolve(process.cwd(), opts.out);
+          writeFileSync(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;
 }
@@ -2613,11 +3709,11 @@ function buildTable2(headers, rows) {
   );
   return [headerRow, divider, ...dataRows].join("\n");
 }
-function resolveTokenFilePath(fileFlag) {
+function resolveTokenFilePath2(fileFlag) {
   if (fileFlag !== void 0) {
     return resolve(process.cwd(), fileFlag);
   }
-  const configPath = resolve(process.cwd(), CONFIG_FILE);
+  const configPath = resolve(process.cwd(), CONFIG_FILE2);
   if (existsSync(configPath)) {
     try {
       const raw = readFileSync(configPath, "utf-8");
@@ -2629,7 +3725,7 @@ function resolveTokenFilePath(fileFlag) {
     } catch {
     }
   }
-  return resolve(process.cwd(), DEFAULT_TOKEN_FILE);
+  return resolve(process.cwd(), DEFAULT_TOKEN_FILE2);
 }
 function loadTokens(absPath) {
   if (!existsSync(absPath)) {
@@ -2676,7 +3772,7 @@ 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 resolvedValue = resolver.resolve(tokenPath);
@@ -2702,7 +3798,7 @@ 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 filtered = resolver.list(opts.type, category);
@@ -2732,7 +3828,7 @@ 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 useJson = opts.format === "json" || opts.format !== "table" && !isTTY2();
@@ -2814,7 +3910,7 @@ 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);
@@ -2851,7 +3947,7 @@ 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);
+      const filePath = resolveTokenFilePath2(opts.file);
       if (!existsSync(filePath)) {
         throw new Error(
           `Token file not found at ${filePath}.
@@ -2934,6 +4030,7 @@ function createTokensCommand() {
   registerSearch(tokensCmd);
   registerResolve(tokensCmd);
   registerValidate(tokensCmd);
+  tokensCmd.addCommand(createTokensExportCommand());
   return tokensCmd;
 }
 
@@ -3033,6 +4130,6 @@ function createProgram(options = {}) {
   return program;
 }
 
-export { createInitCommand, createManifestCommand, createProgram, createTokensCommand, isTTY, matchGlob, runInit };
+export { createInitCommand, createInstrumentCommand, createManifestCommand, createProgram, createTokensCommand, createTokensExportCommand, isTTY, matchGlob, resolveTokenFilePath, runInit };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map