@agent-scope/cli 1.13.0 → 1.14.0

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/program.ts
-import { readFileSync as readFileSync8 } from "fs";
+import { readFileSync as readFileSync9 } from "fs";
 import { generateTest, loadTrace } from "@agent-scope/playwright";
 import { Command as Command8 } from "commander";
 
@@ -255,9 +255,9 @@ function createRL() {
   });
 }
 async function ask(rl, question) {
-  return new Promise((resolve12) => {
+  return new Promise((resolve14) => {
     rl.question(question, (answer) => {
-      resolve12(answer.trim());
+      resolve14(answer.trim());
     });
   });
 }
@@ -2874,8 +2874,8 @@ Available: ${available}`
 `
         );
         if (opts.sprite !== void 0) {
-          const { SpriteSheetGenerator } = await import("@agent-scope/render");
-          const gen = new SpriteSheetGenerator();
+          const { SpriteSheetGenerator: SpriteSheetGenerator2 } = await import("@agent-scope/render");
+          const gen = new SpriteSheetGenerator2();
           const sheet = await gen.generate(result);
           const spritePath = resolve7(process.cwd(), opts.sprite);
           writeFileSync4(spritePath, sheet.png);
@@ -2884,8 +2884,8 @@ Available: ${available}`
         }
         const fmt = resolveMatrixFormat(opts.format, opts.sprite !== void 0);
         if (fmt === "file") {
-          const { SpriteSheetGenerator } = await import("@agent-scope/render");
-          const gen = new SpriteSheetGenerator();
+          const { SpriteSheetGenerator: SpriteSheetGenerator2 } = await import("@agent-scope/render");
+          const gen = new SpriteSheetGenerator2();
           const sheet = await gen.generate(result);
           const dir = resolve7(process.cwd(), DEFAULT_OUTPUT_DIR);
           mkdirSync3(dir, { recursive: true });
@@ -2902,8 +2902,8 @@ Available: ${available}`
         } else if (fmt === "png") {
           if (opts.sprite !== void 0) {
           } else {
-            const { SpriteSheetGenerator } = await import("@agent-scope/render");
-            const gen = new SpriteSheetGenerator();
+            const { SpriteSheetGenerator: SpriteSheetGenerator2 } = await import("@agent-scope/render");
+            const gen = new SpriteSheetGenerator2();
             const sheet = await gen.generate(result);
             process.stdout.write(sheet.png);
           }
@@ -3217,12 +3217,12 @@ async function runBaseline(options = {}) {
   mkdirSync4(rendersDir, { recursive: true });
   let manifest;
   if (manifestPath !== void 0) {
-    const { readFileSync: readFileSync9 } = await import("fs");
+    const { readFileSync: readFileSync10 } = await import("fs");
     const absPath = resolve8(rootDir, manifestPath);
     if (!existsSync5(absPath)) {
       throw new Error(`Manifest not found at ${absPath}.`);
     }
-    manifest = JSON.parse(readFileSync9(absPath, "utf-8"));
+    manifest = JSON.parse(readFileSync10(absPath, "utf-8"));
     process.stderr.write(`Loaded manifest from ${manifestPath}
 `);
   } else {
@@ -4144,47 +4144,223 @@ function buildStructuredReport(report) {
 }
 
 // src/tokens/commands.ts
-import { existsSync as existsSync8, readFileSync as readFileSync7 } from "fs";
-import { resolve as resolve11 } from "path";
+import { existsSync as existsSync9, readFileSync as readFileSync8 } from "fs";
+import { resolve as resolve13 } from "path";
 import {
   parseTokenFileSync as parseTokenFileSync2,
   TokenParseError,
-  TokenResolver as TokenResolver4,
+  TokenResolver as TokenResolver7,
   TokenValidationError,
   validateTokenFile
 } from "@agent-scope/tokens";
 import { Command as Command7 } from "commander";
 
-// src/tokens/export.ts
-import { existsSync as existsSync7, readFileSync as readFileSync6, writeFileSync as writeFileSync7 } from "fs";
+// src/tokens/compliance.ts
+import { existsSync as existsSync7, readFileSync as readFileSync6 } from "fs";
 import { resolve as resolve10 } from "path";
+import {
+  ComplianceEngine as ComplianceEngine3,
+  TokenResolver as TokenResolver3
+} from "@agent-scope/tokens";
+var DEFAULT_STYLES_PATH = ".reactscope/compliance-styles.json";
+function loadStylesFile(stylesPath) {
+  const absPath = resolve10(process.cwd(), stylesPath);
+  if (!existsSync7(absPath)) {
+    throw new Error(
+      `Compliance styles file not found at ${absPath}.
+Run \`scope render all\` first to generate component styles, or use --styles to specify a path.
+Expected format: { "ComponentName": { colors: {}, spacing: {}, typography: {}, borders: {}, shadows: {} } }`
+    );
+  }
+  const raw = readFileSync6(absPath, "utf-8");
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`Failed to parse compliance styles file as JSON: ${String(err)}`);
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new Error(
+      `Compliance styles file must be a JSON object mapping component names to ComputedStyles.`
+    );
+  }
+  return parsed;
+}
+function categoryForProperty(property) {
+  const lower = property.toLowerCase();
+  if (lower.includes("shadow")) return "shadow";
+  if (lower.includes("color") || lower === "background" || lower === "fill" || lower === "stroke")
+    return "color";
+  if (lower.includes("padding") || lower.includes("margin") || lower === "gap" || lower === "width" || lower === "height" || lower === "top" || lower === "right" || lower === "bottom" || lower === "left")
+    return "spacing";
+  if (lower.includes("border")) return "border";
+  if (lower.includes("font") || lower.includes("line") || lower.includes("letter") || lower === "texttransform" || lower === "textdecoration")
+    return "typography";
+  return "spacing";
+}
+function buildCategorySummary(batch) {
+  const cats = {
+    color: { total: 0, onSystem: 0, offSystem: 0, compliance: 1 },
+    spacing: { total: 0, onSystem: 0, offSystem: 0, compliance: 1 },
+    typography: { total: 0, onSystem: 0, offSystem: 0, compliance: 1 },
+    border: { total: 0, onSystem: 0, offSystem: 0, compliance: 1 },
+    shadow: { total: 0, onSystem: 0, offSystem: 0, compliance: 1 }
+  };
+  for (const report of Object.values(batch.components)) {
+    for (const [property, result] of Object.entries(report.properties)) {
+      const cat = categoryForProperty(property);
+      const summary = cats[cat];
+      if (summary === void 0) continue;
+      summary.total++;
+      if (result.status === "on_system") {
+        summary.onSystem++;
+      } else {
+        summary.offSystem++;
+      }
+    }
+  }
+  for (const summary of Object.values(cats)) {
+    summary.compliance = summary.total === 0 ? 1 : summary.onSystem / summary.total;
+  }
+  return cats;
+}
+function collectOffenders(batch, limit = 10) {
+  const offenders = [];
+  const componentEntries = Object.entries(batch.components).map(([name, report]) => ({
+    name,
+    report,
+    offSystemCount: report.offSystem
+  }));
+  componentEntries.sort((a, b) => b.offSystemCount - a.offSystemCount);
+  for (const { name, report, offSystemCount } of componentEntries) {
+    if (offSystemCount === 0) continue;
+    for (const [property, result] of Object.entries(report.properties)) {
+      if (result.status !== "OFF_SYSTEM") continue;
+      offenders.push({
+        component: name,
+        property,
+        value: result.value,
+        nearestToken: result.nearest?.token ?? "\u2014",
+        nearestValue: result.nearest?.value ?? "\u2014",
+        offSystemCount
+      });
+      if (offenders.length >= limit) break;
+    }
+    if (offenders.length >= limit) break;
+  }
+  return offenders;
+}
+function formatPct(n) {
+  return `${Math.round(n * 100)}%`;
+}
+function truncate(s, max) {
+  return s.length > max ? `${s.slice(0, max - 1)}\u2026` : s;
+}
+function formatComplianceReport(batch, threshold) {
+  const pct = Math.round(batch.aggregateCompliance * 100);
+  const lines = [];
+  const thresholdLabel = threshold !== void 0 ? pct >= threshold ? " \u2713 (pass)" : ` \u2717 (below threshold ${threshold}%)` : "";
+  lines.push(`Overall compliance score: ${pct}%${thresholdLabel}`);
+  lines.push("");
+  const cats = buildCategorySummary(batch);
+  const catEntries = Object.entries(cats).filter(([, s]) => s.total > 0);
+  if (catEntries.length > 0) {
+    lines.push("By category:");
+    const catWidth = Math.max(...catEntries.map(([k]) => k.length));
+    for (const [cat, summary] of catEntries) {
+      const label = cat.padEnd(catWidth);
+      lines.push(
+        `  ${label}  ${formatPct(summary.compliance).padStart(4)} (${summary.offSystem} off-system value${summary.offSystem !== 1 ? "s" : ""})`
+      );
+    }
+    lines.push("");
+  }
+  const offenders = collectOffenders(batch);
+  if (offenders.length > 0) {
+    lines.push("Top off-system offenders (sorted by count):");
+    const nameWidth = Math.max(9, ...offenders.map((o) => o.component.length));
+    const propWidth = Math.max(8, ...offenders.map((o) => o.property.length));
+    const valWidth = Math.max(5, ...offenders.map((o) => truncate(o.value, 40).length));
+    for (const offender of offenders) {
+      const name = offender.component.padEnd(nameWidth);
+      const prop = offender.property.padEnd(propWidth);
+      const val = truncate(offender.value, 40).padEnd(valWidth);
+      const nearest = `${offender.nearestToken} (${truncate(offender.nearestValue, 30)})`;
+      lines.push(`  ${name}  ${prop}: ${val}  \u2192 nearest: ${nearest}`);
+    }
+  } else {
+    lines.push("No off-system values detected. \u{1F389}");
+  }
+  return lines.join("\n");
+}
+function registerCompliance(tokensCmd) {
+  tokensCmd.command("compliance").description("Aggregate token compliance report across all components (Token Spec \xA73.3 format)").option("--file <path>", "Path to token file (overrides config)").option("--styles <path>", `Path to compliance styles JSON (default: ${DEFAULT_STYLES_PATH})`).option("--threshold <n>", "Exit code 1 if compliance score is below this percentage (0-100)").option("--format <fmt>", "Output format: json or text (default: auto-detect)").action((opts) => {
+    try {
+      const tokenFilePath = resolveTokenFilePath(opts.file);
+      const { tokens } = loadTokens(tokenFilePath);
+      const resolver = new TokenResolver3(tokens);
+      const engine = new ComplianceEngine3(resolver);
+      const stylesPath = opts.styles ?? DEFAULT_STYLES_PATH;
+      const stylesFile = loadStylesFile(stylesPath);
+      const componentMap = /* @__PURE__ */ new Map();
+      for (const [name, styles] of Object.entries(stylesFile)) {
+        componentMap.set(name, styles);
+      }
+      if (componentMap.size === 0) {
+        process.stderr.write(`Warning: No components found in styles file at ${stylesPath}
+`);
+      }
+      const batch = engine.auditBatch(componentMap);
+      const useJson = opts.format === "json" || opts.format !== "text" && !isTTY();
+      const threshold = opts.threshold !== void 0 ? Number.parseInt(opts.threshold, 10) : void 0;
+      if (useJson) {
+        process.stdout.write(`${JSON.stringify(batch, null, 2)}
+`);
+      } else {
+        process.stdout.write(`${formatComplianceReport(batch, threshold)}
+`);
+      }
+      if (threshold !== void 0 && Math.round(batch.aggregateCompliance * 100) < threshold) {
+        process.exit(1);
+      }
+    } catch (err) {
+      process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}
+`);
+      process.exit(1);
+    }
+  });
+}
+
+// src/tokens/export.ts
+import { existsSync as existsSync8, readFileSync as readFileSync7, writeFileSync as writeFileSync7 } from "fs";
+import { resolve as resolve11 } from "path";
 import {
   exportTokens,
   parseTokenFileSync,
   ThemeResolver,
-  TokenResolver as TokenResolver3
+  TokenResolver as TokenResolver4
 } from "@agent-scope/tokens";
 import { Command as Command6 } from "commander";
 var DEFAULT_TOKEN_FILE = "reactscope.tokens.json";
 var CONFIG_FILE = "reactscope.config.json";
 var SUPPORTED_FORMATS = ["css", "ts", "scss", "tailwind", "flat-json", "figma"];
-function resolveTokenFilePath(fileFlag) {
+function resolveTokenFilePath2(fileFlag) {
   if (fileFlag !== void 0) {
-    return resolve10(process.cwd(), fileFlag);
+    return resolve11(process.cwd(), fileFlag);
   }
-  const configPath = resolve10(process.cwd(), CONFIG_FILE);
-  if (existsSync7(configPath)) {
+  const configPath = resolve11(process.cwd(), CONFIG_FILE);
+  if (existsSync8(configPath)) {
     try {
-      const raw = readFileSync6(configPath, "utf-8");
+      const raw = readFileSync7(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 resolve10(process.cwd(), file);
+        return resolve11(process.cwd(), file);
       }
     } catch {
     }
   }
-  return resolve10(process.cwd(), DEFAULT_TOKEN_FILE);
+  return resolve11(process.cwd(), DEFAULT_TOKEN_FILE);
 }
 function createTokensExportCommand() {
   return new Command6("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(
@@ -4202,14 +4378,14 @@ Supported formats: ${SUPPORTED_FORMATS.join(", ")}
       }
       const format = opts.format;
       try {
-        const filePath = resolveTokenFilePath(opts.file);
-        if (!existsSync7(filePath)) {
+        const filePath = resolveTokenFilePath2(opts.file);
+        if (!existsSync8(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 = readFileSync6(filePath, "utf-8");
+        const raw = readFileSync7(filePath, "utf-8");
         const { tokens, rawFile } = parseTokenFileSync(raw);
         let themesMap;
         if (opts.theme !== void 0) {
@@ -4220,7 +4396,7 @@ Create a reactscope.tokens.json file or use --file to specify a path.`
 Available themes: ${available}`
             );
           }
-          const baseResolver = new TokenResolver3(tokens);
+          const baseResolver = new TokenResolver4(tokens);
           const themeResolver = ThemeResolver.fromTokenFile(
             baseResolver,
             rawFile
@@ -4248,7 +4424,7 @@ Available themes: ${themeNames.join(", ")}`
           themes: themesMap
         });
         if (opts.out !== void 0) {
-          const outPath = resolve10(process.cwd(), opts.out);
+          const outPath = resolve11(process.cwd(), opts.out);
           writeFileSync7(outPath, output, "utf-8");
           process.stderr.write(`Exported ${tokens.length} tokens to ${outPath}
 `);
@@ -4267,6 +4443,324 @@ Available themes: ${themeNames.join(", ")}`
   );
 }
 
+// src/tokens/impact.ts
+import {
+  ComplianceEngine as ComplianceEngine4,
+  ImpactAnalyzer,
+  TokenResolver as TokenResolver5
+} from "@agent-scope/tokens";
+var DEFAULT_STYLES_PATH2 = ".reactscope/compliance-styles.json";
+var SEVERITY_EMOJI = {
+  none: "\u25CB",
+  subtle: "\u25D4",
+  moderate: "\u25D1",
+  significant: "\u25CF"
+};
+function formatImpactReport(report) {
+  const lines = [];
+  const newValueSuffix = report.newValue !== report.oldValue ? `  \u2192  ${report.newValue}` : "";
+  lines.push(`Token: ${report.tokenPath}  (${report.oldValue})${newValueSuffix}`);
+  if (report.components.length === 0) {
+    lines.push("");
+    lines.push("No components reference this token.");
+    return lines.join("\n");
+  }
+  lines.push("");
+  const nameWidth = Math.max(9, ...report.components.map((c) => c.name.length));
+  const propWidth = Math.max(
+    8,
+    ...report.components.flatMap((c) => c.affectedProperties.map((p) => p.length))
+  );
+  for (const comp of report.components) {
+    for (const property of comp.affectedProperties) {
+      const name = comp.name.padEnd(nameWidth);
+      const prop = property.padEnd(propWidth);
+      const severityIcon2 = SEVERITY_EMOJI[comp.severity] ?? "?";
+      lines.push(`  ${name}  ${prop}  ${severityIcon2} ${comp.severity}`);
+    }
+  }
+  lines.push("");
+  const countLabel = `${report.affectedComponentCount} component${report.affectedComponentCount !== 1 ? "s" : ""}`;
+  const severityIcon = SEVERITY_EMOJI[report.overallSeverity] ?? "?";
+  lines.push(
+    `${countLabel} affected \u2014 overall severity: ${severityIcon} ${report.overallSeverity}`
+  );
+  if (report.colorDelta !== void 0) {
+    lines.push(`Color delta: \u0394E ${report.colorDelta.toFixed(2)}`);
+  }
+  return lines.join("\n");
+}
+function formatImpactSummary(report) {
+  if (report.components.length === 0) {
+    return `No components reference token "${report.tokenPath}".`;
+  }
+  const parts = report.components.map(
+    (c) => `${c.name} (${c.affectedProperties.length} element${c.affectedProperties.length !== 1 ? "s" : ""})`
+  );
+  return `\u2192 ${parts.join(", ")}`;
+}
+function registerImpact(tokensCmd) {
+  tokensCmd.command("impact <path>").description("List all components and elements that consume a given token (Token Spec \xA74.3)").option("--file <path>", "Path to token file (overrides config)").option("--styles <path>", `Path to compliance styles JSON (default: ${DEFAULT_STYLES_PATH2})`).option("--new-value <value>", "Proposed new value \u2014 report visual severity of the change").option("--format <fmt>", "Output format: json or text (default: auto-detect)").action(
+    (tokenPath, opts) => {
+      try {
+        const tokenFilePath = resolveTokenFilePath(opts.file);
+        const { tokens } = loadTokens(tokenFilePath);
+        const resolver = new TokenResolver5(tokens);
+        const engine = new ComplianceEngine4(resolver);
+        const stylesPath = opts.styles ?? DEFAULT_STYLES_PATH2;
+        const stylesFile = loadStylesFile(stylesPath);
+        const componentMap = new Map(Object.entries(stylesFile));
+        const batchReport = engine.auditBatch(componentMap);
+        const complianceReports = new Map(Object.entries(batchReport.components));
+        const analyzer = new ImpactAnalyzer(resolver, complianceReports);
+        const currentValue = resolver.resolve(tokenPath);
+        const newValue = opts.newValue ?? currentValue;
+        const report = analyzer.impactOf(tokenPath, newValue);
+        const useJson = opts.format === "json" || opts.format !== "text" && !isTTY();
+        if (useJson) {
+          process.stdout.write(`${JSON.stringify(report, null, 2)}
+`);
+        } else {
+          process.stdout.write(`${formatImpactReport(report)}
+`);
+          if (isTTY()) {
+            process.stdout.write(`
+${formatImpactSummary(report)}
+`);
+          }
+        }
+      } catch (err) {
+        process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}
+`);
+        process.exit(1);
+      }
+    }
+  );
+}
+
+// src/tokens/preview.ts
+import { mkdirSync as mkdirSync5, writeFileSync as writeFileSync8 } from "fs";
+import { resolve as resolve12 } from "path";
+import { BrowserPool as BrowserPool6, SpriteSheetGenerator } from "@agent-scope/render";
+import { ComplianceEngine as ComplianceEngine5, ImpactAnalyzer as ImpactAnalyzer2, TokenResolver as TokenResolver6 } from "@agent-scope/tokens";
+var DEFAULT_STYLES_PATH3 = ".reactscope/compliance-styles.json";
+var DEFAULT_MANIFEST_PATH = ".reactscope/manifest.json";
+var DEFAULT_OUTPUT_DIR2 = ".reactscope/previews";
+async function renderComponentWithCssOverride(filePath, componentName, cssOverride, vpWidth, vpHeight, timeoutMs) {
+  const htmlHarness = await buildComponentHarness(
+    filePath,
+    componentName,
+    {},
+    // no props
+    vpWidth,
+    cssOverride
+    // injected as <style>
+  );
+  const pool = new BrowserPool6({
+    size: { browsers: 1, pagesPerBrowser: 1 },
+    viewportWidth: vpWidth,
+    viewportHeight: vpHeight
+  });
+  await pool.init();
+  const slot = await pool.acquire();
+  const { page } = slot;
+  try {
+    await page.setContent(htmlHarness, { waitUntil: "load" });
+    await page.waitForFunction(
+      () => {
+        const w = window;
+        return w.__SCOPE_RENDER_COMPLETE__ === true;
+      },
+      { timeout: timeoutMs }
+    );
+    const rootLocator = page.locator("[data-reactscope-root]");
+    const bb = await rootLocator.boundingBox();
+    const PAD = 16;
+    const MIN_W = 320;
+    const MIN_H = 120;
+    const clipX = Math.max(0, (bb?.x ?? 0) - PAD);
+    const clipY = Math.max(0, (bb?.y ?? 0) - PAD);
+    const rawW = (bb?.width ?? MIN_W) + PAD * 2;
+    const rawH = (bb?.height ?? MIN_H) + PAD * 2;
+    const clipW = Math.min(Math.max(rawW, MIN_W), vpWidth - clipX);
+    const clipH = Math.min(Math.max(rawH, MIN_H), vpHeight - clipY);
+    const screenshot = await page.screenshot({
+      clip: { x: clipX, y: clipY, width: clipW, height: clipH },
+      type: "png"
+    });
+    return { screenshot, width: Math.round(clipW), height: Math.round(clipH) };
+  } finally {
+    pool.release(slot);
+    await pool.close().catch(() => void 0);
+  }
+}
+function registerPreview(tokensCmd) {
+  tokensCmd.command("preview <path>").description("Render before/after sprite sheet for components affected by a token change").requiredOption("--new-value <value>", "The proposed new resolved value for the token").option("--sprite", "Output a PNG sprite sheet (default when TTY)", false).option("-o, --output <path>", "Output PNG path (default: .reactscope/previews/<token>.png)").option("--file <path>", "Path to token file (overrides config)").option("--styles <path>", `Path to compliance styles JSON (default: ${DEFAULT_STYLES_PATH3})`).option("--manifest <path>", "Path to manifest.json", DEFAULT_MANIFEST_PATH).option("--format <fmt>", "Output format: json or text (default: auto-detect)").option("--timeout <ms>", "Browser timeout per render (ms)", "10000").option("--viewport-width <px>", "Viewport width in pixels", "1280").option("--viewport-height <px>", "Viewport height in pixels", "720").action(
+    async (tokenPath, opts) => {
+      try {
+        const tokenFilePath = resolveTokenFilePath(opts.file);
+        const { tokens } = loadTokens(tokenFilePath);
+        const resolver = new TokenResolver6(tokens);
+        const engine = new ComplianceEngine5(resolver);
+        const stylesPath = opts.styles ?? DEFAULT_STYLES_PATH3;
+        const stylesFile = loadStylesFile(stylesPath);
+        const componentMap = new Map(Object.entries(stylesFile));
+        const batchReport = engine.auditBatch(componentMap);
+        const complianceReports = new Map(Object.entries(batchReport.components));
+        const analyzer = new ImpactAnalyzer2(resolver, complianceReports);
+        const currentValue = resolver.resolve(tokenPath);
+        const impactReport = analyzer.impactOf(tokenPath, opts.newValue);
+        if (impactReport.components.length === 0) {
+          process.stdout.write(
+            `No components reference token "${tokenPath}". Nothing to preview.
+`
+          );
+          return;
+        }
+        const affectedNames = impactReport.components.map((c) => c.name);
+        process.stderr.write(
+          `Rendering ${affectedNames.length} component(s): ${affectedNames.join(", ")}
+`
+        );
+        const manifest = loadManifest(opts.manifest);
+        const vpWidth = Number.parseInt(opts.viewportWidth, 10);
+        const vpHeight = Number.parseInt(opts.viewportHeight, 10);
+        const timeout = Number.parseInt(opts.timeout, 10);
+        const tokenCssVar = `--token-${tokenPath.replace(/\./g, "-")}`;
+        const beforeCss = `:root { ${tokenCssVar}: ${currentValue}; }`;
+        const afterCss = `:root { ${tokenCssVar}: ${opts.newValue}; }`;
+        const renders = [];
+        for (const componentName of affectedNames) {
+          const descriptor = manifest.components[componentName];
+          if (descriptor === void 0) {
+            process.stderr.write(
+              `Warning: "${componentName}" not found in manifest \u2014 skipping
+`
+            );
+            continue;
+          }
+          process.stderr.write(`  Rendering ${componentName} (before)...
+`);
+          const before = await renderComponentWithCssOverride(
+            descriptor.filePath,
+            componentName,
+            beforeCss,
+            vpWidth,
+            vpHeight,
+            timeout
+          );
+          process.stderr.write(`  Rendering ${componentName} (after)...
+`);
+          const after = await renderComponentWithCssOverride(
+            descriptor.filePath,
+            componentName,
+            afterCss,
+            vpWidth,
+            vpHeight,
+            timeout
+          );
+          renders.push({ name: componentName, before, after });
+        }
+        if (renders.length === 0) {
+          process.stderr.write(
+            "Warning: No components could be rendered (all missing from manifest).\n"
+          );
+          return;
+        }
+        const cellW = Math.max(...renders.flatMap((r) => [r.before.width, r.after.width]));
+        const cellH = Math.max(...renders.flatMap((r) => [r.before.height, r.after.height]));
+        const cells = renders.flatMap((r, colIdx) => [
+          {
+            props: { version: "before", component: r.name },
+            result: {
+              screenshot: r.before.screenshot,
+              width: cellW,
+              height: cellH,
+              renderTimeMs: 0,
+              computedStyles: {}
+            },
+            index: colIdx * 2,
+            axisIndices: [0, colIdx]
+          },
+          {
+            props: { version: "after", component: r.name },
+            result: {
+              screenshot: r.after.screenshot,
+              width: cellW,
+              height: cellH,
+              renderTimeMs: 0,
+              computedStyles: {}
+            },
+            index: colIdx * 2 + 1,
+            axisIndices: [1, colIdx]
+          }
+        ]);
+        const matrixResult = {
+          cells,
+          axes: [
+            { name: "component", values: renders.map((r) => r.name) },
+            { name: "version", values: ["before", "after"] }
+          ],
+          axisLabels: [renders.map((r) => r.name), ["before", "after"]],
+          rows: 2,
+          cols: renders.length,
+          stats: {
+            totalCells: cells.length,
+            totalRenderTimeMs: 0,
+            avgRenderTimeMs: 0,
+            minRenderTimeMs: 0,
+            maxRenderTimeMs: 0,
+            wallClockTimeMs: 0
+          }
+        };
+        const generator = new SpriteSheetGenerator({
+          cellPadding: 8,
+          borderWidth: 1,
+          labelHeight: 32,
+          labelWidth: 120
+        });
+        const spriteResult = await generator.generate(matrixResult);
+        const tokenLabel = tokenPath.replace(/\./g, "-");
+        const outputPath = opts.output ?? resolve12(process.cwd(), DEFAULT_OUTPUT_DIR2, `preview-${tokenLabel}.png`);
+        const outputDir = resolve12(outputPath, "..");
+        mkdirSync5(outputDir, { recursive: true });
+        writeFileSync8(outputPath, spriteResult.png);
+        const useJson = opts.format === "json" || opts.format !== "text" && !isTTY();
+        if (useJson) {
+          process.stdout.write(
+            `${JSON.stringify(
+              {
+                tokenPath,
+                oldValue: currentValue,
+                newValue: opts.newValue,
+                outputPath,
+                width: spriteResult.width,
+                height: spriteResult.height,
+                components: renders.map((r) => r.name),
+                cells: spriteResult.coordinates.length
+              },
+              null,
+              2
+            )}
+`
+          );
+        } else {
+          process.stdout.write(
+            `Preview written to ${outputPath} (${spriteResult.width}\xD7${spriteResult.height}px)
+`
+          );
+          process.stdout.write(`Components: ${renders.map((r) => r.name).join(", ")}
+`);
+        }
+      } 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";
@@ -4287,32 +4781,32 @@ function buildTable2(headers, rows) {
   );
   return [headerRow, divider, ...dataRows].join("\n");
 }
-function resolveTokenFilePath2(fileFlag) {
+function resolveTokenFilePath(fileFlag) {
   if (fileFlag !== void 0) {
-    return resolve11(process.cwd(), fileFlag);
+    return resolve13(process.cwd(), fileFlag);
   }
-  const configPath = resolve11(process.cwd(), CONFIG_FILE2);
-  if (existsSync8(configPath)) {
+  const configPath = resolve13(process.cwd(), CONFIG_FILE2);
+  if (existsSync9(configPath)) {
     try {
-      const raw = readFileSync7(configPath, "utf-8");
+      const raw = readFileSync8(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 resolve11(process.cwd(), file);
+        return resolve13(process.cwd(), file);
       }
     } catch {
     }
   }
-  return resolve11(process.cwd(), DEFAULT_TOKEN_FILE2);
+  return resolve13(process.cwd(), DEFAULT_TOKEN_FILE2);
 }
 function loadTokens(absPath) {
-  if (!existsSync8(absPath)) {
+  if (!existsSync9(absPath)) {
     throw new Error(
       `Token file not found at ${absPath}.
 Create a reactscope.tokens.json file or use --file to specify a path.`
     );
   }
-  const raw = readFileSync7(absPath, "utf-8");
+  const raw = readFileSync8(absPath, "utf-8");
   return parseTokenFileSync2(raw);
 }
 function getRawValue(node, segments) {
@@ -4350,9 +4844,9 @@ function buildResolutionChain(startPath, rawTokens) {
 function registerGet2(tokensCmd) {
   tokensCmd.command("get <path>").description("Resolve a token path to its computed value").option("--file <path>", "Path to token file (overrides config)").option("--format <fmt>", "Output format: json or text (default: auto-detect)").action((tokenPath, opts) => {
     try {
-      const filePath = resolveTokenFilePath2(opts.file);
+      const filePath = resolveTokenFilePath(opts.file);
       const { tokens } = loadTokens(filePath);
-      const resolver = new TokenResolver4(tokens);
+      const resolver = new TokenResolver7(tokens);
       const resolvedValue = resolver.resolve(tokenPath);
       const useJson = opts.format === "json" || opts.format !== "text" && !isTTY2();
       if (useJson) {
@@ -4376,9 +4870,9 @@ function registerList2(tokensCmd) {
   tokensCmd.command("list [category]").description("List tokens, optionally filtered by category or type").option("--type <type>", "Filter by token type (color, dimension, fontFamily, etc.)").option("--file <path>", "Path to token file (overrides config)").option("--format <fmt>", "Output format: json or table (default: auto-detect)").action(
     (category, opts) => {
       try {
-        const filePath = resolveTokenFilePath2(opts.file);
+        const filePath = resolveTokenFilePath(opts.file);
         const { tokens } = loadTokens(filePath);
-        const resolver = new TokenResolver4(tokens);
+        const resolver = new TokenResolver7(tokens);
         const filtered = resolver.list(opts.type, category);
         const useJson = opts.format === "json" || opts.format !== "table" && !isTTY2();
         if (useJson) {
@@ -4406,9 +4900,9 @@ function registerSearch(tokensCmd) {
   tokensCmd.command("search <value>").description("Find which token(s) match a computed value (supports fuzzy color matching)").option("--type <type>", "Restrict search to a specific token type").option("--fuzzy", "Return nearest match even if no exact match exists", false).option("--file <path>", "Path to token file (overrides config)").option("--format <fmt>", "Output format: json or table (default: auto-detect)").action(
     (value, opts) => {
       try {
-        const filePath = resolveTokenFilePath2(opts.file);
+        const filePath = resolveTokenFilePath(opts.file);
         const { tokens } = loadTokens(filePath);
-        const resolver = new TokenResolver4(tokens);
+        const resolver = new TokenResolver7(tokens);
         const useJson = opts.format === "json" || opts.format !== "table" && !isTTY2();
         const typesToSearch = opts.type ? [opts.type] : [
           "color",
@@ -4488,10 +4982,10 @@ Tip: use --fuzzy for nearest-match search.
 function registerResolve(tokensCmd) {
   tokensCmd.command("resolve <path>").description("Show the full resolution chain for a token").option("--file <path>", "Path to token file (overrides config)").option("--format <fmt>", "Output format: json or text (default: auto-detect)").action((tokenPath, opts) => {
     try {
-      const filePath = resolveTokenFilePath2(opts.file);
+      const filePath = resolveTokenFilePath(opts.file);
       const absFilePath = filePath;
       const { tokens, rawFile } = loadTokens(absFilePath);
-      const resolver = new TokenResolver4(tokens);
+      const resolver = new TokenResolver7(tokens);
       resolver.resolve(tokenPath);
       const chain = buildResolutionChain(tokenPath, rawFile.tokens);
       const useJson = opts.format === "json" || opts.format !== "text" && !isTTY2();
@@ -4525,14 +5019,14 @@ function registerValidate(tokensCmd) {
     "Validate the token file for errors (circular refs, missing refs, type mismatches)"
   ).option("--file <path>", "Path to token file (overrides config)").option("--format <fmt>", "Output format: json or text (default: auto-detect)").action((opts) => {
     try {
-      const filePath = resolveTokenFilePath2(opts.file);
-      if (!existsSync8(filePath)) {
+      const filePath = resolveTokenFilePath(opts.file);
+      if (!existsSync9(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 = readFileSync7(filePath, "utf-8");
+      const raw = readFileSync8(filePath, "utf-8");
       const useJson = opts.format === "json" || opts.format !== "text" && !isTTY2();
       const errors = [];
       let parsed;
@@ -4609,6 +5103,9 @@ function createTokensCommand() {
   registerResolve(tokensCmd);
   registerValidate(tokensCmd);
   tokensCmd.addCommand(createTokensExportCommand());
+  registerCompliance(tokensCmd);
+  registerImpact(tokensCmd);
+  registerPreview(tokensCmd);
   return tokensCmd;
 }
 
@@ -4687,7 +5184,7 @@ function createProgram(options = {}) {
     }
   );
   program2.command("generate").description("Generate a Playwright test from a Scope trace file").argument("<trace>", "Path to a serialized Scope trace (.json)").option("-o, --output <path>", "Output file path", "scope.spec.ts").option("-d, --description <text>", "Test description").action((tracePath, opts) => {
-    const raw = readFileSync8(tracePath, "utf-8");
+    const raw = readFileSync9(tracePath, "utf-8");
     const trace = loadTrace(raw);
     const source = generateTest(trace, {
       description: opts.description,