npm - @agent-scope/cli - Versions diffs - 1.13.0 → 1.14.0 - Mend

@agent-scope/cli 1.13.0 → 1.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/dist/index.js CHANGED Viewed

@@ -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 { SpriteSheetGenerator, BrowserPool, safeRender, ALL_CONTEXT_IDS, contextAxis, stressAxis, ALL_STRESS_IDS, RenderMatrix, SatoriRenderer } from '@agent-scope/render';
 import * as esbuild from 'esbuild';
 import { generateManifest } from '@agent-scope/manifest';
 import { chromium } from 'playwright';
 import { loadTrace, generateTest, getBrowserEntryScript } from '@agent-scope/playwright';
 import { createRequire } from 'module';
-import { parseTokenFileSync, TokenResolver, ThemeResolver, exportTokens, validateTokenFile, TokenValidationError, TokenParseError, ComplianceEngine } from '@agent-scope/tokens';
+import { parseTokenFileSync, TokenResolver, ThemeResolver, exportTokens, validateTokenFile, TokenValidationError, TokenParseError, ComplianceEngine, ImpactAnalyzer } 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((resolve12) => {
+  return new Promise((resolve14) => {
     rl.question(question, (answer) => {
-      resolve12(answer.trim());
+      resolve14(answer.trim());
     });
   });
 }
@@ -356,7 +356,7 @@ function createInitCommand() {
 }
 async function buildComponentHarness(filePath, componentName, props, viewportWidth, projectCss) {
   const bundledScript = await bundleComponentToIIFE(filePath, componentName, props);
-  return wrapInHtml(bundledScript, viewportWidth);
+  return wrapInHtml(bundledScript, viewportWidth, projectCss);
 }
 async function bundleComponentToIIFE(filePath, componentName, props) {
   const propsJson = JSON.stringify(props).replace(/<\/script>/gi, "<\\/script>");
@@ -443,7 +443,9 @@ ${msg}`);
   return outputFile.text;
 }
 function wrapInHtml(bundledScript, viewportWidth, projectCss) {
-  const projectStyleBlock = "";
+  const projectStyleBlock = projectCss != null && projectCss.length > 0 ? `<style id="scope-project-css">
+${projectCss.replace(/<\/style>/gi, "<\\/style>")}
+</style>` : "";
   return `<!DOCTYPE html>
 <html lang="en">
 <head>
@@ -2807,8 +2809,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 = resolve(process.cwd(), opts.sprite);
           writeFileSync(spritePath, sheet.png);
@@ -2817,8 +2819,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 = resolve(process.cwd(), DEFAULT_OUTPUT_DIR);
           mkdirSync(dir, { recursive: true });
@@ -2835,8 +2837,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);
           }
@@ -3143,12 +3145,12 @@ async function runBaseline(options = {}) {
   mkdirSync(rendersDir, { recursive: true });
   let manifest;
   if (manifestPath !== void 0) {
-    const { readFileSync: readFileSync9 } = await import('fs');
+    const { readFileSync: readFileSync10 } = await import('fs');
     const absPath = resolve(rootDir, manifestPath);
     if (!existsSync(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 {
@@ -4060,10 +4062,178 @@ function buildStructuredReport(report) {
     route: report.route?.pattern ?? null
   };
 }
+var DEFAULT_STYLES_PATH = ".reactscope/compliance-styles.json";
+function loadStylesFile(stylesPath) {
+  const absPath = resolve(process.cwd(), stylesPath);
+  if (!existsSync(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 = readFileSync(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 TokenResolver(tokens);
+      const engine = new ComplianceEngine(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);
+    }
+  });
+}
 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 resolve(process.cwd(), fileFlag);
   }
@@ -4097,7 +4267,7 @@ Supported formats: ${SUPPORTED_FORMATS.join(", ")}
       }
       const format = opts.format;
       try {
-        const filePath = resolveTokenFilePath(opts.file);
+        const filePath = resolveTokenFilePath2(opts.file);
         if (!existsSync(filePath)) {
           throw new Error(
             `Token file not found at ${filePath}.
@@ -4161,6 +4331,311 @@ Available themes: ${themeNames.join(", ")}`
     }
   );
 }
+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 TokenResolver(tokens);
+        const engine = new ComplianceEngine(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);
+      }
+    }
+  );
+}
+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 BrowserPool({
+    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 TokenResolver(tokens);
+        const engine = new ComplianceEngine(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 ImpactAnalyzer(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 ?? resolve(process.cwd(), DEFAULT_OUTPUT_DIR2, `preview-${tokenLabel}.png`);
+        const outputDir = resolve(outputPath, "..");
+        mkdirSync(outputDir, { recursive: true });
+        writeFileSync(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";
@@ -4182,7 +4657,7 @@ function buildTable2(headers, rows) {
   );
   return [headerRow, divider, ...dataRows].join("\n");
 }
-function resolveTokenFilePath2(fileFlag) {
+function resolveTokenFilePath(fileFlag) {
   if (fileFlag !== void 0) {
     return resolve(process.cwd(), fileFlag);
   }
@@ -4245,7 +4720,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 = resolveTokenFilePath2(opts.file);
+      const filePath = resolveTokenFilePath(opts.file);
       const { tokens } = loadTokens(filePath);
       const resolver = new TokenResolver(tokens);
       const resolvedValue = resolver.resolve(tokenPath);
@@ -4271,7 +4746,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 = resolveTokenFilePath2(opts.file);
+        const filePath = resolveTokenFilePath(opts.file);
         const { tokens } = loadTokens(filePath);
         const resolver = new TokenResolver(tokens);
         const filtered = resolver.list(opts.type, category);
@@ -4301,7 +4776,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 = resolveTokenFilePath2(opts.file);
+        const filePath = resolveTokenFilePath(opts.file);
         const { tokens } = loadTokens(filePath);
         const resolver = new TokenResolver(tokens);
         const useJson = opts.format === "json" || opts.format !== "table" && !isTTY2();
@@ -4383,7 +4858,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 = resolveTokenFilePath2(opts.file);
+      const filePath = resolveTokenFilePath(opts.file);
       const absFilePath = filePath;
       const { tokens, rawFile } = loadTokens(absFilePath);
       const resolver = new TokenResolver(tokens);
@@ -4420,7 +4895,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 = resolveTokenFilePath2(opts.file);
+      const filePath = resolveTokenFilePath(opts.file);
       if (!existsSync(filePath)) {
         throw new Error(
           `Token file not found at ${filePath}.
@@ -4504,6 +4979,9 @@ function createTokensCommand() {
   registerResolve(tokensCmd);
   registerValidate(tokensCmd);
   tokensCmd.addCommand(createTokensExportCommand());
+  registerCompliance(tokensCmd);
+  registerImpact(tokensCmd);
+  registerPreview(tokensCmd);
   return tokensCmd;
 }
@@ -4604,6 +5082,6 @@ function createProgram(options = {}) {
   return program;
 }
-export { createInitCommand, createInstrumentCommand, createManifestCommand, createProgram, createTokensCommand, createTokensExportCommand, isTTY, matchGlob, resolveTokenFilePath, runInit };
+export { createInitCommand, createInstrumentCommand, createManifestCommand, createProgram, createTokensCommand, createTokensExportCommand, isTTY, matchGlob, resolveTokenFilePath2 as resolveTokenFilePath, runInit };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map