@agent-scope/cli 1.7.0 → 1.9.0

package/dist/index.js

@@ -1,7 +1,8 @@
-import { readFileSync, existsSync, mkdirSync, writeFileSync } from 'fs';
-import { resolve, dirname } from 'path';
-import { generateManifest } from '@agent-scope/manifest';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, appendFileSync, readdirSync } from 'fs';
+import { join, resolve, dirname } from 'path';
+import * as readline from 'readline';
 import { Command } from 'commander';
+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';
@@ -9,7 +10,350 @@ import * as esbuild from 'esbuild';
 import { createRequire } from 'module';
 import { TokenResolver, validateTokenFile, TokenValidationError, parseTokenFileSync, TokenParseError } from '@agent-scope/tokens';
 
-// src/manifest-commands.ts
+// src/init/index.ts
+function hasConfigFile(dir, stem) {
+  if (!existsSync(dir)) return false;
+  try {
+    const entries = readdirSync(dir);
+    return entries.some((f) => f === stem || f.startsWith(`${stem}.`));
+  } catch {
+    return false;
+  }
+}
+function readSafe(path) {
+  try {
+    return readFileSync(path, "utf-8");
+  } catch {
+    return null;
+  }
+}
+function detectFramework(rootDir, packageDeps) {
+  if (hasConfigFile(rootDir, "next.config")) return "next";
+  if (hasConfigFile(rootDir, "vite.config")) return "vite";
+  if (hasConfigFile(rootDir, "remix.config")) return "remix";
+  if ("react-scripts" in packageDeps) return "cra";
+  return "unknown";
+}
+function detectPackageManager(rootDir) {
+  if (existsSync(join(rootDir, "bun.lock"))) return "bun";
+  if (existsSync(join(rootDir, "yarn.lock"))) return "yarn";
+  if (existsSync(join(rootDir, "pnpm-lock.yaml"))) return "pnpm";
+  if (existsSync(join(rootDir, "package-lock.json"))) return "npm";
+  return "npm";
+}
+function detectTypeScript(rootDir) {
+  const candidate = join(rootDir, "tsconfig.json");
+  if (existsSync(candidate)) {
+    return { typescript: true, tsconfigPath: candidate };
+  }
+  return { typescript: false, tsconfigPath: null };
+}
+var COMPONENT_DIRS = ["src/components", "src/app", "src/pages", "src/ui", "src/features", "src"];
+var COMPONENT_EXTS = [".tsx", ".jsx"];
+function detectComponentPatterns(rootDir, typescript) {
+  const patterns = [];
+  const ext = typescript ? "tsx" : "jsx";
+  const altExt = typescript ? "jsx" : "jsx";
+  for (const dir of COMPONENT_DIRS) {
+    const absDir = join(rootDir, dir);
+    if (!existsSync(absDir)) continue;
+    let hasComponents = false;
+    try {
+      const entries = readdirSync(absDir, { withFileTypes: true });
+      hasComponents = entries.some(
+        (e) => e.isFile() && COMPONENT_EXTS.some((x) => e.name.endsWith(x))
+      );
+      if (!hasComponents) {
+        hasComponents = entries.some(
+          (e) => e.isDirectory() && (() => {
+            try {
+              return readdirSync(join(absDir, e.name)).some(
+                (f) => COMPONENT_EXTS.some((x) => f.endsWith(x))
+              );
+            } catch {
+              return false;
+            }
+          })()
+        );
+      }
+    } catch {
+      continue;
+    }
+    if (hasComponents) {
+      patterns.push(`${dir}/**/*.${ext}`);
+      if (altExt !== ext) {
+        patterns.push(`${dir}/**/*.${altExt}`);
+      }
+    }
+  }
+  const unique = [...new Set(patterns)];
+  if (unique.length === 0) {
+    return [`**/*.${ext}`];
+  }
+  return unique;
+}
+var TAILWIND_STEMS = ["tailwind.config"];
+var CSS_EXTS = [".css", ".scss", ".sass", ".less"];
+var THEME_SUFFIXES = [".theme.ts", ".theme.js", ".theme.tsx"];
+var CSS_CUSTOM_PROPS_RE = /:root\s*\{[^}]*--[a-zA-Z]/;
+function detectTokenSources(rootDir) {
+  const sources = [];
+  for (const stem of TAILWIND_STEMS) {
+    if (hasConfigFile(rootDir, stem)) {
+      try {
+        const entries = readdirSync(rootDir);
+        const match = entries.find((f) => f === stem || f.startsWith(`${stem}.`));
+        if (match) {
+          sources.push({ kind: "tailwind-config", path: join(rootDir, match) });
+        }
+      } catch {
+      }
+    }
+  }
+  const srcDir = join(rootDir, "src");
+  const dirsToScan = existsSync(srcDir) ? [srcDir] : [];
+  for (const scanDir of dirsToScan) {
+    try {
+      const entries = readdirSync(scanDir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (entry.isFile() && CSS_EXTS.some((x) => entry.name.endsWith(x))) {
+          const filePath = join(scanDir, entry.name);
+          const content = readSafe(filePath);
+          if (content !== null && CSS_CUSTOM_PROPS_RE.test(content)) {
+            sources.push({ kind: "css-custom-properties", path: filePath });
+          }
+        }
+      }
+    } catch {
+    }
+  }
+  if (existsSync(srcDir)) {
+    try {
+      const entries = readdirSync(srcDir);
+      for (const entry of entries) {
+        if (THEME_SUFFIXES.some((s) => entry.endsWith(s))) {
+          sources.push({ kind: "theme-file", path: join(srcDir, entry) });
+        }
+      }
+    } catch {
+    }
+  }
+  return sources;
+}
+function detectProject(rootDir) {
+  const pkgPath = join(rootDir, "package.json");
+  let packageDeps = {};
+  const pkgContent = readSafe(pkgPath);
+  if (pkgContent !== null) {
+    try {
+      const pkg = JSON.parse(pkgContent);
+      packageDeps = {
+        ...pkg.dependencies,
+        ...pkg.devDependencies
+      };
+    } catch {
+    }
+  }
+  const framework = detectFramework(rootDir, packageDeps);
+  const { typescript, tsconfigPath } = detectTypeScript(rootDir);
+  const packageManager = detectPackageManager(rootDir);
+  const componentPatterns = detectComponentPatterns(rootDir, typescript);
+  const tokenSources = detectTokenSources(rootDir);
+  return {
+    framework,
+    typescript,
+    tsconfigPath,
+    componentPatterns,
+    tokenSources,
+    packageManager
+  };
+}
+function buildDefaultConfig(detected, tokenFile, outputDir) {
+  const include = detected.componentPatterns.length > 0 ? detected.componentPatterns : ["src/**/*.tsx"];
+  return {
+    components: {
+      include,
+      exclude: ["**/*.test.tsx", "**/*.stories.tsx"],
+      wrappers: { providers: [], globalCSS: [] }
+    },
+    render: {
+      viewport: { default: { width: 1280, height: 800 } },
+      theme: "light",
+      warmBrowser: true
+    },
+    tokens: {
+      file: tokenFile,
+      compliance: { threshold: 90 }
+    },
+    output: {
+      dir: outputDir,
+      sprites: { format: "png", cellPadding: 8, labelAxes: true },
+      json: { pretty: true }
+    },
+    ci: {
+      complianceThreshold: 90,
+      failOnA11yViolations: true,
+      failOnConsoleErrors: false,
+      baselinePath: `${outputDir}baseline/`
+    }
+  };
+}
+function createRL() {
+  return readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+}
+async function ask(rl, question) {
+  return new Promise((resolve6) => {
+    rl.question(question, (answer) => {
+      resolve6(answer.trim());
+    });
+  });
+}
+async function askWithDefault(rl, label, defaultValue) {
+  const answer = await ask(rl, `  ${label} [${defaultValue}]: `);
+  return answer.length > 0 ? answer : defaultValue;
+}
+function ensureGitignoreEntry(rootDir, entry) {
+  const gitignorePath = join(rootDir, ".gitignore");
+  if (existsSync(gitignorePath)) {
+    const content = readFileSync(gitignorePath, "utf-8");
+    const normalised = entry.replace(/\/$/, "");
+    const lines = content.split("\n").map((l) => l.trim());
+    if (lines.includes(entry) || lines.includes(normalised)) {
+      return;
+    }
+    const suffix = content.endsWith("\n") ? "" : "\n";
+    appendFileSync(gitignorePath, `${suffix}${entry}
+`);
+  } else {
+    writeFileSync(gitignorePath, `${entry}
+`);
+  }
+}
+function scaffoldConfig(rootDir, config) {
+  const path = join(rootDir, "reactscope.config.json");
+  writeFileSync(path, `${JSON.stringify(config, null, 2)}
+`);
+  return path;
+}
+function scaffoldTokenFile(rootDir, tokenFile) {
+  const path = join(rootDir, tokenFile);
+  if (!existsSync(path)) {
+    const stub = {
+      $schema: "https://raw.githubusercontent.com/FlatFilers/Scope/main/packages/tokens/schema.json",
+      tokens: {}
+    };
+    writeFileSync(path, `${JSON.stringify(stub, null, 2)}
+`);
+  }
+  return path;
+}
+function scaffoldOutputDir(rootDir, outputDir) {
+  const dirPath = join(rootDir, outputDir);
+  mkdirSync(dirPath, { recursive: true });
+  const keepPath = join(dirPath, ".gitkeep");
+  if (!existsSync(keepPath)) {
+    writeFileSync(keepPath, "");
+  }
+  return dirPath;
+}
+async function runInit(options) {
+  const rootDir = options.cwd ?? process.cwd();
+  const configPath = join(rootDir, "reactscope.config.json");
+  const created = [];
+  if (existsSync(configPath) && !options.force) {
+    const msg = "reactscope.config.json already exists. Run with --force to overwrite.";
+    process.stderr.write(`\u26A0\uFE0F  ${msg}
+`);
+    return { success: false, message: msg, created: [], skipped: true };
+  }
+  const detected = detectProject(rootDir);
+  const defaultTokenFile = "reactscope.tokens.json";
+  const defaultOutputDir = ".reactscope/";
+  let config = buildDefaultConfig(detected, defaultTokenFile, defaultOutputDir);
+  if (options.yes) {
+    process.stdout.write("\n\u{1F50D}  Detected project settings:\n");
+    process.stdout.write(`   Framework      : ${detected.framework}
+`);
+    process.stdout.write(`   TypeScript     : ${detected.typescript}
+`);
+    process.stdout.write(`   Include globs  : ${config.components.include.join(", ")}
+`);
+    process.stdout.write(`   Token file     : ${config.tokens.file}
+`);
+    process.stdout.write(`   Output dir     : ${config.output.dir}
+
+`);
+  } else {
+    const rl = createRL();
+    process.stdout.write("\n\u{1F680}  scope init \u2014 project configuration\n");
+    process.stdout.write("   Press Enter to accept the detected value shown in brackets.\n\n");
+    try {
+      process.stdout.write(`   Detected framework: ${detected.framework}
+`);
+      const includeRaw = await askWithDefault(
+        rl,
+        "Component include patterns (comma-separated)",
+        config.components.include.join(", ")
+      );
+      config.components.include = includeRaw.split(",").map((s) => s.trim()).filter(Boolean);
+      const excludeRaw = await askWithDefault(
+        rl,
+        "Component exclude patterns (comma-separated)",
+        config.components.exclude.join(", ")
+      );
+      config.components.exclude = excludeRaw.split(",").map((s) => s.trim()).filter(Boolean);
+      const tokenFile = await askWithDefault(rl, "Token file location", config.tokens.file);
+      config.tokens.file = tokenFile;
+      config.ci.baselinePath = `${config.output.dir}baseline/`;
+      const outputDir = await askWithDefault(rl, "Output directory", config.output.dir);
+      config.output.dir = outputDir.endsWith("/") ? outputDir : `${outputDir}/`;
+      config.ci.baselinePath = `${config.output.dir}baseline/`;
+      config = buildDefaultConfig(detected, config.tokens.file, config.output.dir);
+      config.components.include = includeRaw.split(",").map((s) => s.trim()).filter(Boolean);
+      config.components.exclude = excludeRaw.split(",").map((s) => s.trim()).filter(Boolean);
+    } finally {
+      rl.close();
+    }
+    process.stdout.write("\n");
+  }
+  const cfgPath = scaffoldConfig(rootDir, config);
+  created.push(cfgPath);
+  const tokPath = scaffoldTokenFile(rootDir, config.tokens.file);
+  created.push(tokPath);
+  const outDirPath = scaffoldOutputDir(rootDir, config.output.dir);
+  created.push(outDirPath);
+  ensureGitignoreEntry(rootDir, config.output.dir);
+  process.stdout.write("\u2705  Scope project initialised!\n\n");
+  process.stdout.write("   Created files:\n");
+  for (const p of created) {
+    process.stdout.write(`     ${p}
+`);
+  }
+  process.stdout.write("\n   Next steps: run `scope manifest` to scan your components.\n\n");
+  return {
+    success: true,
+    message: "Project initialised successfully.",
+    created,
+    skipped: false
+  };
+}
+function createInitCommand() {
+  return new Command("init").description("Initialise a Scope project \u2014 scaffold reactscope.config.json and friends").option("-y, --yes", "Accept all detected defaults without prompting", false).option("--force", "Overwrite existing reactscope.config.json if present", false).action(async (opts) => {
+    try {
+      const result = await runInit({ yes: opts.yes, force: opts.force });
+      if (!result.success && !result.skipped) {
+        process.exit(1);
+      }
+    } catch (err) {
+      process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}
+`);
+      process.exit(1);
+    }
+  });
+}
 
 // src/manifest-formatter.ts
 function isTTY() {
@@ -585,6 +929,471 @@ function csvEscape(value) {
   }
   return value;
 }
+
+// src/instrument/renders.ts
+var MANIFEST_PATH2 = ".reactscope/manifest.json";
+function determineTrigger(event) {
+  if (event.forceUpdate) return "force_update";
+  if (event.stateChanged) return "state_change";
+  if (event.propsChanged) return "props_change";
+  if (event.contextChanged) return "context_change";
+  if (event.hookDepsChanged) return "hook_dependency";
+  return "parent_rerender";
+}
+function isWastedRender(event) {
+  return !event.propsChanged && !event.stateChanged && !event.contextChanged && !event.memoized;
+}
+function buildCausalityChains(rawEvents) {
+  const result = [];
+  const componentLastRender = /* @__PURE__ */ new Map();
+  for (const raw of rawEvents) {
+    const trigger = determineTrigger(raw);
+    const wasted = isWastedRender(raw);
+    const chain = [];
+    let current = raw;
+    const visited = /* @__PURE__ */ new Set();
+    while (true) {
+      if (visited.has(current.component)) break;
+      visited.add(current.component);
+      const currentTrigger = determineTrigger(current);
+      chain.unshift({
+        component: current.component,
+        trigger: currentTrigger,
+        propsChanged: current.propsChanged,
+        stateChanged: current.stateChanged,
+        contextChanged: current.contextChanged
+      });
+      if (currentTrigger !== "parent_rerender" || current.parentComponent === null) {
+        break;
+      }
+      const parentEvent = componentLastRender.get(current.parentComponent);
+      if (parentEvent === void 0) break;
+      current = parentEvent;
+    }
+    const rootCause = chain[0];
+    const cascadeRenders = rawEvents.filter((e) => {
+      if (rootCause === void 0) return false;
+      return e.component !== rootCause.component && !e.stateChanged && !e.propsChanged;
+    });
+    result.push({
+      component: raw.component,
+      renderIndex: raw.renderIndex,
+      trigger,
+      propsChanged: raw.propsChanged,
+      stateChanged: raw.stateChanged,
+      contextChanged: raw.contextChanged,
+      memoized: raw.memoized,
+      wasted,
+      chain,
+      cascade: {
+        totalRendersTriggered: cascadeRenders.length,
+        uniqueComponents: new Set(cascadeRenders.map((e) => e.component)).size,
+        unchangedPropRenders: cascadeRenders.filter((e) => !e.propsChanged).length
+      }
+    });
+    componentLastRender.set(raw.component, raw);
+  }
+  return result;
+}
+function applyHeuristicFlags(renders) {
+  const flags = [];
+  const byComponent = /* @__PURE__ */ new Map();
+  for (const r of renders) {
+    if (!byComponent.has(r.component)) byComponent.set(r.component, []);
+    byComponent.get(r.component).push(r);
+  }
+  for (const [component, events] of byComponent) {
+    const wastedCount = events.filter((e) => e.wasted).length;
+    const totalCount = events.length;
+    if (wastedCount > 0) {
+      flags.push({
+        id: "WASTED_RENDER",
+        severity: "warning",
+        component,
+        detail: `${wastedCount}/${totalCount} renders were wasted \u2014 unchanged props/state/context, not memoized`,
+        data: { wastedCount, totalCount, wastedRatio: wastedCount / totalCount }
+      });
+    }
+    for (const event of events) {
+      if (event.cascade.totalRendersTriggered > 50) {
+        flags.push({
+          id: "RENDER_CASCADE",
+          severity: "warning",
+          component,
+          detail: `State change in ${component} triggered ${event.cascade.totalRendersTriggered} downstream re-renders`,
+          data: {
+            totalRendersTriggered: event.cascade.totalRendersTriggered,
+            uniqueComponents: event.cascade.uniqueComponents,
+            unchangedPropRenders: event.cascade.unchangedPropRenders
+          }
+        });
+        break;
+      }
+    }
+  }
+  return flags;
+}
+function buildInstrumentationScript() {
+  return (
+    /* js */
+    `
+(function installScopeRenderInstrumentation() {
+  window.__SCOPE_RENDER_EVENTS__ = [];
+  window.__SCOPE_RENDER_INDEX__ = 0;
+
+  var hook = window.__REACT_DEVTOOLS_GLOBAL_HOOK__;
+  if (!hook) return;
+
+  var originalOnCommit = hook.onCommitFiberRoot;
+  var renderedComponents = new Map(); // componentName -> { lastProps, lastState }
+
+  function extractName(fiber) {
+    if (!fiber) return 'Unknown';
+    var type = fiber.type;
+    if (!type) return 'Unknown';
+    if (typeof type === 'string') return type; // host element
+    if (typeof type === 'function') return type.displayName || type.name || 'Anonymous';
+    if (type.displayName) return type.displayName;
+    if (type.render && typeof type.render === 'function') {
+      return type.render.displayName || type.render.name || 'Anonymous';
+    }
+    return 'Anonymous';
+  }
+
+  function isMemoized(fiber) {
+    // MemoComponent = 14, SimpleMemoComponent = 15
+    return fiber.tag === 14 || fiber.tag === 15;
+  }
+
+  function isComponent(fiber) {
+    // FunctionComponent=0, ClassComponent=1, MemoComponent=14, SimpleMemoComponent=15
+    return fiber.tag === 0 || fiber.tag === 1 || fiber.tag === 14 || fiber.tag === 15;
+  }
+
+  function shallowEqual(a, b) {
+    if (a === b) return true;
+    if (!a || !b) return a === b;
+    var keysA = Object.keys(a);
+    var keysB = Object.keys(b);
+    if (keysA.length !== keysB.length) return false;
+    for (var i = 0; i < keysA.length; i++) {
+      var k = keysA[i];
+      if (k === 'children') continue; // ignore children prop
+      if (a[k] !== b[k]) return false;
+    }
+    return true;
+  }
+
+  function getParentComponentName(fiber) {
+    var parent = fiber.return;
+    while (parent) {
+      if (isComponent(parent)) {
+        var name = extractName(parent);
+        if (name && name !== 'Unknown' && !/^[a-z]/.test(name)) return name;
+      }
+      parent = parent.return;
+    }
+    return null;
+  }
+
+  function walkCommit(fiber) {
+    if (!fiber) return;
+
+    if (isComponent(fiber)) {
+      var name = extractName(fiber);
+      if (name && name !== 'Unknown' && !/^[a-z]/.test(name)) {
+        var memoized = isMemoized(fiber);
+        var currentProps = fiber.memoizedProps || {};
+        var prev = renderedComponents.get(name);
+
+        var propsChanged = true;
+        var stateChanged = false;
+        var contextChanged = false;
+        var hookDepsChanged = false;
+        var forceUpdate = false;
+
+        if (prev) {
+          propsChanged = !shallowEqual(prev.lastProps, currentProps);
+        }
+
+        // State: check memoizedState chain
+        var memoizedState = fiber.memoizedState;
+        if (prev && prev.lastStateSerialized !== undefined) {
+          try {
+            var stateSig = JSON.stringify(memoizedState ? memoizedState.memoizedState : null);
+            stateChanged = stateSig !== prev.lastStateSerialized;
+          } catch (_) {
+            stateChanged = false;
+          }
+        }
+
+        // Context: use _debugHookTypes or check dependencies
+        var deps = fiber.dependencies;
+        if (deps && deps.firstContext) {
+          contextChanged = true; // conservative: context dep present = may have changed
+        }
+
+        var stateSig;
+        try {
+          stateSig = JSON.stringify(memoizedState ? memoizedState.memoizedState : null);
+        } catch (_) {
+          stateSig = null;
+        }
+
+        renderedComponents.set(name, {
+          lastProps: currentProps,
+          lastStateSerialized: stateSig,
+        });
+
+        var parentName = getParentComponentName(fiber);
+
+        window.__SCOPE_RENDER_EVENTS__.push({
+          component: name,
+          renderIndex: window.__SCOPE_RENDER_INDEX__++,
+          propsChanged: prev ? propsChanged : false,
+          stateChanged: stateChanged,
+          contextChanged: contextChanged,
+          memoized: memoized,
+          parentComponent: parentName,
+          hookDepsChanged: hookDepsChanged,
+          forceUpdate: forceUpdate,
+        });
+      }
+    }
+
+    walkCommit(fiber.child);
+    walkCommit(fiber.sibling);
+  }
+
+  hook.onCommitFiberRoot = function(rendererID, root, priorityLevel) {
+    if (typeof originalOnCommit === 'function') {
+      originalOnCommit.call(hook, rendererID, root, priorityLevel);
+    }
+    var wipRoot = root && root.current && root.current.alternate;
+    if (wipRoot) walkCommit(wipRoot);
+  };
+})();
+`
+  );
+}
+async function replayInteraction(page, steps) {
+  for (const step of steps) {
+    switch (step.action) {
+      case "click":
+        if (step.target !== void 0) {
+          await page.click(step.target, { timeout: 5e3 }).catch(() => {
+          });
+        }
+        break;
+      case "type":
+        if (step.target !== void 0 && step.text !== void 0) {
+          await page.fill(step.target, step.text, { timeout: 5e3 }).catch(async () => {
+            await page.type(step.target, step.text, { timeout: 5e3 }).catch(() => {
+            });
+          });
+        }
+        break;
+      case "hover":
+        if (step.target !== void 0) {
+          await page.hover(step.target, { timeout: 5e3 }).catch(() => {
+          });
+        }
+        break;
+      case "blur":
+        if (step.target !== void 0) {
+          await page.locator(step.target).blur({ timeout: 5e3 }).catch(() => {
+          });
+        }
+        break;
+      case "focus":
+        if (step.target !== void 0) {
+          await page.focus(step.target, { timeout: 5e3 }).catch(() => {
+          });
+        }
+        break;
+      case "scroll":
+        if (step.target !== void 0) {
+          await page.locator(step.target).scrollIntoViewIfNeeded({ timeout: 5e3 }).catch(() => {
+          });
+        }
+        break;
+      case "wait": {
+        const timeout = step.timeout ?? 1e3;
+        if (step.condition === "idle") {
+          await page.waitForLoadState("networkidle", { timeout }).catch(() => {
+          });
+        } else {
+          await page.waitForTimeout(timeout);
+        }
+        break;
+      }
+    }
+  }
+}
+var _pool = null;
+async function getPool() {
+  if (_pool === null) {
+    _pool = new BrowserPool({
+      size: { browsers: 1, pagesPerBrowser: 2 },
+      viewportWidth: 1280,
+      viewportHeight: 800
+    });
+    await _pool.init();
+  }
+  return _pool;
+}
+async function shutdownPool() {
+  if (_pool !== null) {
+    await _pool.close();
+    _pool = null;
+  }
+}
+async function analyzeRenders(options) {
+  const manifestPath = options.manifestPath ?? MANIFEST_PATH2;
+  const manifest = loadManifest(manifestPath);
+  const descriptor = manifest.components[options.componentName];
+  if (descriptor === void 0) {
+    const available = Object.keys(manifest.components).slice(0, 5).join(", ");
+    throw new Error(
+      `Component "${options.componentName}" not found in manifest.
+Available: ${available}`
+    );
+  }
+  const rootDir = process.cwd();
+  const filePath = resolve(rootDir, descriptor.filePath);
+  const htmlHarness = await buildComponentHarness(filePath, options.componentName, {}, 1280);
+  const pool = await getPool();
+  const slot = await pool.acquire();
+  const { page } = slot;
+  const startMs = performance.now();
+  try {
+    await page.addInitScript(buildInstrumentationScript());
+    await page.setContent(htmlHarness, { waitUntil: "load" });
+    await page.waitForFunction(
+      () => window.__SCOPE_RENDER_COMPLETE__ === true,
+      { timeout: 15e3 }
+    );
+    await page.waitForTimeout(100);
+    await page.evaluate(() => {
+      window.__SCOPE_RENDER_EVENTS__ = [];
+      window.__SCOPE_RENDER_INDEX__ = 0;
+    });
+    await replayInteraction(page, options.interaction);
+    await page.waitForTimeout(200);
+    const interactionDurationMs = performance.now() - startMs;
+    const rawEvents = await page.evaluate(() => {
+      return window.__SCOPE_RENDER_EVENTS__ ?? [];
+    });
+    const renders = buildCausalityChains(rawEvents);
+    const flags = applyHeuristicFlags(renders);
+    const uniqueComponents = new Set(renders.map((r) => r.component)).size;
+    const wastedRenders = renders.filter((r) => r.wasted).length;
+    return {
+      component: options.componentName,
+      interaction: options.interaction,
+      summary: {
+        totalRenders: renders.length,
+        uniqueComponents,
+        wastedRenders,
+        interactionDurationMs: Math.round(interactionDurationMs)
+      },
+      renders,
+      flags
+    };
+  } finally {
+    pool.release(slot);
+  }
+}
+function formatRendersTable(result) {
+  const lines = [];
+  lines.push(`
+\u{1F50D} Re-render Analysis: ${result.component}`);
+  lines.push(`${"\u2500".repeat(60)}`);
+  lines.push(`Total renders:    ${result.summary.totalRenders}`);
+  lines.push(`Unique components: ${result.summary.uniqueComponents}`);
+  lines.push(`Wasted renders:   ${result.summary.wastedRenders}`);
+  lines.push(`Duration:         ${result.summary.interactionDurationMs}ms`);
+  lines.push("");
+  if (result.renders.length === 0) {
+    lines.push("No re-renders captured during interaction.");
+  } else {
+    lines.push("Re-renders:");
+    lines.push(
+      `${"#".padEnd(4)} ${"Component".padEnd(30)} ${"Trigger".padEnd(18)} ${"Wasted".padEnd(7)} ${"Chain Depth"}`
+    );
+    lines.push("\u2500".repeat(80));
+    for (const r of result.renders) {
+      const wasted = r.wasted ? "\u26A0 yes" : "no";
+      const idx = String(r.renderIndex).padEnd(4);
+      const comp = r.component.slice(0, 29).padEnd(30);
+      const trig = r.trigger.padEnd(18);
+      const w = wasted.padEnd(7);
+      const depth = r.chain.length;
+      lines.push(`${idx} ${comp} ${trig} ${w} ${depth}`);
+    }
+  }
+  if (result.flags.length > 0) {
+    lines.push("");
+    lines.push("Flags:");
+    for (const flag of result.flags) {
+      const icon = flag.severity === "error" ? "\u2717" : flag.severity === "warning" ? "\u26A0" : "\u2139";
+      lines.push(`  ${icon} [${flag.id}] ${flag.component}: ${flag.detail}`);
+    }
+  }
+  return lines.join("\n");
+}
+function createInstrumentRendersCommand() {
+  return new Command("renders").description("Trace re-render causality chains for a component during an interaction sequence").argument("<component>", "Component name to instrument (must be in manifest)").option(
+    "--interaction <json>",
+    `Interaction sequence JSON, e.g. '[{"action":"click","target":"button"}]'`,
+    "[]"
+  ).option("--json", "Output as JSON regardless of TTY", false).option("--manifest <path>", "Path to manifest.json", MANIFEST_PATH2).action(
+    async (componentName, opts) => {
+      let interaction = [];
+      try {
+        interaction = JSON.parse(opts.interaction);
+        if (!Array.isArray(interaction)) {
+          throw new Error("Interaction must be a JSON array");
+        }
+      } catch {
+        process.stderr.write(`Error: Invalid --interaction JSON: ${opts.interaction}
+`);
+        process.exit(1);
+      }
+      try {
+        process.stderr.write(
+          `Instrumenting ${componentName} (${interaction.length} interaction steps)\u2026
+`
+        );
+        const result = await analyzeRenders({
+          componentName,
+          interaction,
+          manifestPath: opts.manifest
+        });
+        await shutdownPool();
+        if (opts.json || !isTTY()) {
+          process.stdout.write(`${JSON.stringify(result, null, 2)}
+`);
+        } else {
+          process.stdout.write(`${formatRendersTable(result)}
+`);
+        }
+      } catch (err) {
+        await shutdownPool();
+        process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}
+`);
+        process.exit(1);
+      }
+    }
+  );
+}
+function createInstrumentCommand() {
+  const instrumentCmd = new Command("instrument").description(
+    "Structured instrumentation commands for React component analysis"
+  );
+  instrumentCmd.addCommand(createInstrumentRendersCommand());
+  return instrumentCmd;
+}
 var CONFIG_FILENAMES = [
   ".reactscope/config.json",
   ".reactscope/config.js",
@@ -702,24 +1511,24 @@ async function getCompiledCssForClasses(cwd, classes) {
 }
 
 // src/render-commands.ts
-var MANIFEST_PATH2 = ".reactscope/manifest.json";
+var MANIFEST_PATH3 = ".reactscope/manifest.json";
 var DEFAULT_OUTPUT_DIR = ".reactscope/renders";
-var _pool = null;
-async function getPool(viewportWidth, viewportHeight) {
-  if (_pool === null) {
-    _pool = new BrowserPool({
+var _pool2 = null;
+async function getPool2(viewportWidth, viewportHeight) {
+  if (_pool2 === null) {
+    _pool2 = new BrowserPool({
       size: { browsers: 1, pagesPerBrowser: 4 },
       viewportWidth,
       viewportHeight
     });
-    await _pool.init();
+    await _pool2.init();
   }
-  return _pool;
+  return _pool2;
 }
-async function shutdownPool() {
-  if (_pool !== null) {
-    await _pool.close();
-    _pool = null;
+async function shutdownPool2() {
+  if (_pool2 !== null) {
+    await _pool2.close();
+    _pool2 = null;
   }
 }
 function buildRenderer(filePath, componentName, viewportWidth, viewportHeight) {
@@ -730,7 +1539,7 @@ function buildRenderer(filePath, componentName, viewportWidth, viewportHeight) {
     _satori: satori,
     async renderCell(props, _complexityClass) {
       const startMs = performance.now();
-      const pool = await getPool(viewportWidth, viewportHeight);
+      const pool = await getPool2(viewportWidth, viewportHeight);
       const htmlHarness = await buildComponentHarness(
         filePath,
         componentName,
@@ -827,7 +1636,7 @@ function buildRenderer(filePath, componentName, viewportWidth, viewportHeight) {
   };
 }
 function registerRenderSingle(renderCmd) {
-  renderCmd.command("component <component>", { isDefault: true }).description("Render a single component to PNG or JSON").option("--props <json>", `Inline props JSON, e.g. '{"variant":"primary"}'`).option("--viewport <WxH>", "Viewport size e.g. 1280x720", "375x812").option("--theme <name>", "Theme name from the token system").option("-o, --output <path>", "Write PNG to file instead of stdout").option("--format <fmt>", "Output format: png or json (default: auto)").option("--manifest <path>", "Path to manifest.json", MANIFEST_PATH2).action(
+  renderCmd.command("component <component>", { isDefault: true }).description("Render a single component to PNG or JSON").option("--props <json>", `Inline props JSON, e.g. '{"variant":"primary"}'`).option("--viewport <WxH>", "Viewport size e.g. 1280x720", "375x812").option("--theme <name>", "Theme name from the token system").option("-o, --output <path>", "Write PNG to file instead of stdout").option("--format <fmt>", "Output format: png or json (default: auto)").option("--manifest <path>", "Path to manifest.json", MANIFEST_PATH3).action(
     async (componentName, opts) => {
       try {
         const manifest = loadManifest(opts.manifest);
@@ -866,7 +1675,7 @@ Available: ${available}`
             }
           }
         );
-        await shutdownPool();
+        await shutdownPool2();
         if (outcome.crashed) {
           process.stderr.write(`\u2717 Render failed: ${outcome.error.message}
 `);
@@ -914,7 +1723,7 @@ Available: ${available}`
           );
         }
       } catch (err) {
-        await shutdownPool();
+        await shutdownPool2();
         process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}
 `);
         process.exit(1);
@@ -926,7 +1735,7 @@ function registerRenderMatrix(renderCmd) {
   renderCmd.command("matrix <component>").description("Render a component across a matrix of prop axes").option("--axes <spec>", "Axis definitions e.g. 'variant:primary,secondary size:sm,md,lg'").option(
     "--contexts <ids>",
     "Composition context IDs, comma-separated (e.g. centered,rtl,sidebar)"
-  ).option("--stress <ids>", "Stress preset IDs, comma-separated (e.g. text.long,text.unicode)").option("--sprite <path>", "Write sprite sheet PNG to file").option("--format <fmt>", "Output format: json|png|html|csv (default: auto)").option("--concurrency <n>", "Max parallel renders", "8").option("--manifest <path>", "Path to manifest.json", MANIFEST_PATH2).action(
+  ).option("--stress <ids>", "Stress preset IDs, comma-separated (e.g. text.long,text.unicode)").option("--sprite <path>", "Write sprite sheet PNG to file").option("--format <fmt>", "Output format: json|png|html|csv (default: auto)").option("--concurrency <n>", "Max parallel renders", "8").option("--manifest <path>", "Path to manifest.json", MANIFEST_PATH3).action(
     async (componentName, opts) => {
       try {
         const manifest = loadManifest(opts.manifest);
@@ -999,7 +1808,7 @@ Available: ${available}`
           concurrency
         });
         const result = await matrix.render();
-        await shutdownPool();
+        await shutdownPool2();
         process.stderr.write(
           `Done. ${result.stats.totalCells} cells, avg ${result.stats.avgRenderTimeMs.toFixed(1)}ms
 `
@@ -1044,7 +1853,7 @@ Available: ${available}`
           process.stdout.write(formatMatrixCsv(componentName, result));
         }
       } catch (err) {
-        await shutdownPool();
+        await shutdownPool2();
         process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}
 `);
         process.exit(1);
@@ -1053,7 +1862,7 @@ Available: ${available}`
   );
 }
 function registerRenderAll(renderCmd) {
-  renderCmd.command("all").description("Render all components from the manifest").option("--concurrency <n>", "Max parallel renders", "4").option("--output-dir <dir>", "Output directory for renders", DEFAULT_OUTPUT_DIR).option("--manifest <path>", "Path to manifest.json", MANIFEST_PATH2).option("--format <fmt>", "Output format: json|png (default: png)", "png").action(
+  renderCmd.command("all").description("Render all components from the manifest").option("--concurrency <n>", "Max parallel renders", "4").option("--output-dir <dir>", "Output directory for renders", DEFAULT_OUTPUT_DIR).option("--manifest <path>", "Path to manifest.json", MANIFEST_PATH3).option("--format <fmt>", "Output format: json|png (default: png)", "png").action(
     async (opts) => {
       try {
         const manifest = loadManifest(opts.manifest);
@@ -1141,13 +1950,13 @@ function registerRenderAll(renderCmd) {
           workers.push(worker());
         }
         await Promise.all(workers);
-        await shutdownPool();
+        await shutdownPool2();
         process.stderr.write("\n");
         const summary = formatSummaryText(results, outputDir);
         process.stderr.write(`${summary}
 `);
       } catch (err) {
-        await shutdownPool();
+        await shutdownPool2();
         process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}
 `);
         process.exit(1);
@@ -1896,9 +2705,11 @@ function createProgram(options = {}) {
   program.addCommand(createManifestCommand());
   program.addCommand(createRenderCommand());
   program.addCommand(createTokensCommand());
+  program.addCommand(createInstrumentCommand());
+  program.addCommand(createInitCommand());
   return program;
 }
 
-export { createManifestCommand, createProgram, createTokensCommand, isTTY, matchGlob };
+export { createInitCommand, createManifestCommand, createProgram, createTokensCommand, isTTY, matchGlob, runInit };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map