npm - @agent-scope/cli - Versions diffs - 1.17.3 → 1.18.1 - Mend

@agent-scope/cli 1.17.3 → 1.18.1

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/cli.js CHANGED Viewed

@@ -1,7 +1,7 @@
-#!/usr/bin/env node
+#!/usr/bin/env bun
 // src/program.ts
-import { readFileSync as readFileSync11 } from "fs";
+import { readFileSync as readFileSync12 } from "fs";
 import { generateTest, loadTrace } from "@agent-scope/playwright";
 import { Command as Command10 } from "commander";
@@ -61,9 +61,9 @@ import { Command } from "commander";
 // src/component-bundler.ts
 import { dirname } from "path";
 import * as esbuild from "esbuild";
-async function buildComponentHarness(filePath, componentName, props, viewportWidth, projectCss, preScript) {
+async function buildComponentHarness(filePath, componentName, props, viewportWidth, projectCss, wrapperScript) {
   const bundledScript = await bundleComponentToIIFE(filePath, componentName, props);
-  return wrapInHtml(bundledScript, viewportWidth, projectCss, preScript);
+  return wrapInHtml(bundledScript, viewportWidth, projectCss, wrapperScript);
 }
 async function bundleComponentToIIFE(filePath, componentName, props) {
   const propsJson = JSON.stringify(props).replace(/<\/script>/gi, "<\\/script>");
@@ -99,7 +99,12 @@ import { createElement } from "react";
       window.__SCOPE_RENDER_COMPLETE__ = true;
       return;
     }
-    createRoot(rootEl).render(createElement(Component, props));
+    // If a scope file wrapper was injected, use it to wrap the component
+    var Wrapper = (window).__SCOPE_WRAPPER__;
+    var element = Wrapper
+      ? createElement(Wrapper, null, createElement(Component, props))
+      : createElement(Component, props);
+    createRoot(rootEl).render(element);
     // Use requestAnimationFrame to let React flush the render
     requestAnimationFrame(function() {
       window.__SCOPE_RENDER_COMPLETE__ = true;
@@ -136,6 +141,21 @@ import { createElement } from "react";
     // Suppress "React must be in scope" warnings from old JSX (we use automatic)
     banner: {
       js: "/* @agent-scope/cli component harness */"
+    },
+    // CSS imports (e.g. `import './styles.css'`) are handled at the page level via
+    // globalCSS injection. Tell esbuild to treat CSS files as empty modules so
+    // components that import CSS directly (e.g. App.tsx) don't error during bundling.
+    loader: {
+      ".css": "empty",
+      ".svg": "dataurl",
+      ".png": "dataurl",
+      ".jpg": "dataurl",
+      ".jpeg": "dataurl",
+      ".gif": "dataurl",
+      ".webp": "dataurl",
+      ".ttf": "dataurl",
+      ".woff": "dataurl",
+      ".woff2": "dataurl"
     }
   });
   if (result.errors.length > 0) {
@@ -149,12 +169,11 @@ ${msg}`);
   }
   return outputFile.text;
 }
-function wrapInHtml(bundledScript, viewportWidth, projectCss, preScript) {
+function wrapInHtml(bundledScript, viewportWidth, projectCss, wrapperScript) {
   const projectStyleBlock = projectCss != null && projectCss.length > 0 ? `<style id="scope-project-css">
 ${projectCss.replace(/<\/style>/gi, "<\\/style>")}
 </style>` : "";
-  const preScriptBlock = preScript != null && preScript.length > 0 ? `<script>${preScript}</script>
-  ` : "";
+  const wrapperScriptBlock = wrapperScript != null && wrapperScript.length > 0 ? `<script id="scope-wrapper-script">${wrapperScript}</script>` : "";
   return `<!DOCTYPE html>
 <html lang="en">
 <head>
@@ -169,7 +188,8 @@ ${projectCss.replace(/<\/style>/gi, "<\\/style>")}
 </head>
 <body>
   <div id="scope-root" data-reactscope-root></div>
-  ${preScriptBlock}<script>${bundledScript}</script>
+  ${wrapperScriptBlock}
+  <script>${bundledScript}</script>
 </body>
 </html>`;
 }
@@ -537,16 +557,67 @@ async function getTailwindCompiler(cwd) {
     from: entryPath,
     loadStylesheet
   });
-  const build2 = result.build.bind(result);
-  compilerCache = { cwd, build: build2 };
-  return build2;
+  const build3 = result.build.bind(result);
+  compilerCache = { cwd, build: build3 };
+  return build3;
 }
 async function getCompiledCssForClasses(cwd, classes) {
-  const build2 = await getTailwindCompiler(cwd);
-  if (build2 === null) return null;
+  const build3 = await getTailwindCompiler(cwd);
+  if (build3 === null) return null;
   const deduped = [...new Set(classes)].filter(Boolean);
   if (deduped.length === 0) return null;
-  return build2(deduped);
+  return build3(deduped);
+}
+async function compileGlobalCssFile(cssFilePath, cwd) {
+  const { existsSync: existsSync15, readFileSync: readFileSync13 } = await import("fs");
+  const { createRequire: createRequire3 } = await import("module");
+  if (!existsSync15(cssFilePath)) return null;
+  const raw = readFileSync13(cssFilePath, "utf-8");
+  const needsCompile = /@tailwind|@import\s+['"]tailwindcss/.test(raw);
+  if (!needsCompile) {
+    return raw;
+  }
+  try {
+    const require2 = createRequire3(resolve(cwd, "package.json"));
+    let postcss;
+    let twPlugin;
+    try {
+      postcss = require2("postcss");
+      twPlugin = require2("tailwindcss");
+    } catch {
+      return raw;
+    }
+    let autoprefixerPlugin;
+    try {
+      autoprefixerPlugin = require2("autoprefixer");
+    } catch {
+      autoprefixerPlugin = null;
+    }
+    const plugins = autoprefixerPlugin ? [twPlugin, autoprefixerPlugin] : [twPlugin];
+    const result = await postcss(plugins).process(raw, {
+      from: cssFilePath,
+      to: cssFilePath
+    });
+    return result.css;
+  } catch (err) {
+    process.stderr.write(
+      `[scope/render] Warning: CSS compilation failed for ${cssFilePath}: ${err instanceof Error ? err.message : String(err)}
+`
+    );
+    return raw;
+  }
+}
+async function loadGlobalCss(globalCssFiles, cwd) {
+  if (globalCssFiles.length === 0) return null;
+  const parts = [];
+  for (const relPath of globalCssFiles) {
+    const absPath = resolve(cwd, relPath);
+    const css = await compileGlobalCssFile(absPath, cwd);
+    if (css !== null && css.trim().length > 0) {
+      parts.push(css);
+    }
+  }
+  return parts.length > 0 ? parts.join("\n") : null;
 }
 // src/ci/commands.ts
@@ -1060,6 +1131,20 @@ function detectComponentPatterns(rootDir, typescript) {
   }
   return unique;
 }
+var GLOBAL_CSS_CANDIDATES = [
+  "src/styles.css",
+  "src/index.css",
+  "src/global.css",
+  "src/globals.css",
+  "src/app.css",
+  "src/main.css",
+  "styles/globals.css",
+  "styles/global.css",
+  "styles/index.css"
+];
+function detectGlobalCSSFiles(rootDir) {
+  return GLOBAL_CSS_CANDIDATES.filter((rel) => existsSync3(join(rootDir, rel)));
+}
 var TAILWIND_STEMS = ["tailwind.config"];
 var CSS_EXTS = [".css", ".scss", ".sass", ".less"];
 var THEME_SUFFIXES = [".theme.ts", ".theme.js", ".theme.tsx"];
@@ -1127,13 +1212,15 @@ function detectProject(rootDir) {
   const packageManager = detectPackageManager(rootDir);
   const componentPatterns = detectComponentPatterns(rootDir, typescript);
   const tokenSources = detectTokenSources(rootDir);
+  const globalCSSFiles = detectGlobalCSSFiles(rootDir);
   return {
     framework,
     typescript,
     tsconfigPath,
     componentPatterns,
     tokenSources,
-    packageManager
+    packageManager,
+    globalCSSFiles
   };
 }
@@ -1145,7 +1232,7 @@ function buildDefaultConfig(detected, tokenFile, outputDir) {
     components: {
       include,
       exclude: ["**/*.test.tsx", "**/*.stories.tsx"],
-      wrappers: { providers: [], globalCSS: [] }
+      wrappers: { providers: [], globalCSS: detected.globalCSSFiles ?? [] }
     },
     render: {
       viewport: { default: { width: 1280, height: 800 } },
@@ -1176,9 +1263,9 @@ function createRL() {
   });
 }
 async function ask(rl, question) {
-  return new Promise((resolve17) => {
+  return new Promise((resolve18) => {
     rl.question(question, (answer) => {
-      resolve17(answer.trim());
+      resolve18(answer.trim());
     });
   });
 }
@@ -1203,18 +1290,118 @@ function ensureGitignoreEntry(rootDir, entry) {
 `);
   }
 }
+function extractTailwindTokens(tokenSources) {
+  const tailwindSource = tokenSources.find((s) => s.kind === "tailwind-config");
+  if (!tailwindSource) return null;
+  try {
+    let parseBlock2 = function(block) {
+      const result = {};
+      const lineRe = /['"]?(\w[\w.-]*|\d+)['"]?\s*:\s*['"]?(#[0-9a-fA-F]{3,8}|\d+(?:px|rem|em|%)|[\w-]+(?:\/[\w]+)?)['"]?/g;
+      for (const m of block.matchAll(lineRe)) {
+        if (m[1] !== void 0 && m[2] !== void 0) {
+          result[m[1]] = m[2];
+        }
+      }
+      return result;
+    };
+    var parseBlock = parseBlock2;
+    const raw = readFileSync4(tailwindSource.path, "utf-8");
+    const tokens = {};
+    const colorsKeyIdx = raw.indexOf("colors:");
+    if (colorsKeyIdx !== -1) {
+      const colorsBraceStart = raw.indexOf("{", colorsKeyIdx);
+      if (colorsBraceStart !== -1) {
+        let colorDepth = 0;
+        let colorsBraceEnd = -1;
+        for (let ci = colorsBraceStart; ci < raw.length; ci++) {
+          if (raw[ci] === "{") colorDepth++;
+          else if (raw[ci] === "}") {
+            colorDepth--;
+            if (colorDepth === 0) {
+              colorsBraceEnd = ci;
+              break;
+            }
+          }
+        }
+        if (colorsBraceEnd > colorsBraceStart) {
+          const colorSection = raw.slice(colorsBraceStart + 1, colorsBraceEnd);
+          const scaleRe = /(\w+)\s*:\s*\{([^}]+)\}/g;
+          const colorTokens = {};
+          for (const sm of colorSection.matchAll(scaleRe)) {
+            if (sm[1] === void 0 || sm[2] === void 0) continue;
+            const scaleName = sm[1];
+            const scaleValues = parseBlock2(sm[2]);
+            if (Object.keys(scaleValues).length > 0) {
+              const scaleTokens = {};
+              for (const [step, hex] of Object.entries(scaleValues)) {
+                scaleTokens[step] = { value: hex, type: "color" };
+              }
+              colorTokens[scaleName] = scaleTokens;
+            }
+          }
+          if (Object.keys(colorTokens).length > 0) {
+            tokens["color"] = colorTokens;
+          }
+        }
+      }
+    }
+    const spacingMatch = raw.match(/spacing\s*:\s*\{([\s\S]*?)\n\s*\}/);
+    if (spacingMatch?.[1] !== void 0) {
+      const spacingValues = parseBlock2(spacingMatch[1]);
+      if (Object.keys(spacingValues).length > 0) {
+        const spacingTokens = {};
+        for (const [key, val] of Object.entries(spacingValues)) {
+          spacingTokens[key] = { value: val, type: "dimension" };
+        }
+        tokens["spacing"] = spacingTokens;
+      }
+    }
+    const fontFamilyMatch = raw.match(/fontFamily\s*:\s*\{([\s\S]*?)\n\s*\}/);
+    if (fontFamilyMatch?.[1] !== void 0) {
+      const fontFamilyRe = /(\w+)\s*:\s*\[\s*['"]([^'"]+)['"]/g;
+      const fontTokens = {};
+      for (const fm of fontFamilyMatch[1].matchAll(fontFamilyRe)) {
+        if (fm[1] !== void 0 && fm[2] !== void 0) {
+          fontTokens[fm[1]] = { value: fm[2], type: "fontFamily" };
+        }
+      }
+      if (Object.keys(fontTokens).length > 0) {
+        tokens["font"] = fontTokens;
+      }
+    }
+    const borderRadiusMatch = raw.match(/borderRadius\s*:\s*\{([\s\S]*?)\n\s*\}/);
+    if (borderRadiusMatch?.[1] !== void 0) {
+      const radiusValues = parseBlock2(borderRadiusMatch[1]);
+      if (Object.keys(radiusValues).length > 0) {
+        const radiusTokens = {};
+        for (const [key, val] of Object.entries(radiusValues)) {
+          radiusTokens[key] = { value: val, type: "dimension" };
+        }
+        tokens["radius"] = radiusTokens;
+      }
+    }
+    return Object.keys(tokens).length > 0 ? tokens : null;
+  } catch {
+    return null;
+  }
+}
 function scaffoldConfig(rootDir, config) {
   const path = join2(rootDir, "reactscope.config.json");
   writeFileSync3(path, `${JSON.stringify(config, null, 2)}
 `);
   return path;
 }
-function scaffoldTokenFile(rootDir, tokenFile) {
+function scaffoldTokenFile(rootDir, tokenFile, extractedTokens) {
   const path = join2(rootDir, tokenFile);
   if (!existsSync4(path)) {
     const stub = {
       $schema: "https://raw.githubusercontent.com/FlatFilers/Scope/main/packages/tokens/schema.json",
-      tokens: {}
+      version: "1.0.0",
+      meta: {
+        name: "Design Tokens",
+        lastUpdated: (/* @__PURE__ */ new Date()).toISOString().split("T")[0]
+      },
+      tokens: extractedTokens ?? {}
     };
     writeFileSync3(path, `${JSON.stringify(stub, null, 2)}
 `);
@@ -1292,7 +1479,13 @@ async function runInit(options) {
   }
   const cfgPath = scaffoldConfig(rootDir, config);
   created.push(cfgPath);
-  const tokPath = scaffoldTokenFile(rootDir, config.tokens.file);
+  const extractedTokens = extractTailwindTokens(detected.tokenSources);
+  if (extractedTokens !== null) {
+    const tokenGroupCount = Object.keys(extractedTokens).length;
+    process.stdout.write(`   Extracted ${tokenGroupCount} token group(s) from Tailwind config
+`);
+  }
+  const tokPath = scaffoldTokenFile(rootDir, config.tokens.file, extractedTokens ?? void 0);
   created.push(tokPath);
   const outDirPath = scaffoldOutputDir(rootDir, config.output.dir);
   created.push(outDirPath);
@@ -1404,7 +1597,10 @@ Available: ${available}${hint}`
   });
 }
 function registerQuery(manifestCmd) {
-  manifestCmd.command("query").description("Query components by attributes").option("--context <name>", "Find components consuming a context").option("--hook <name>", "Find components using a specific hook").option("--complexity <class>", "Filter by complexity class: simple or complex").option("--side-effects", "Find components with any side effects", false).option("--has-fetch", "Find components with fetch calls", false).option("--format <fmt>", "Output format: json or table (default: auto-detect)").option("--manifest <path>", "Path to manifest.json", MANIFEST_PATH).action(
+  manifestCmd.command("query").description("Query components by attributes").option("--context <name>", "Find components consuming a context").option("--hook <name>", "Find components using a specific hook").option("--complexity <class>", "Filter by complexity class: simple or complex").option("--side-effects", "Find components with any side effects", false).option("--has-fetch", "Find components with fetch calls", false).option(
+    "--has-prop <spec>",
+    "Find components with a prop matching name or name:type (e.g. 'loading' or 'variant:union')"
+  ).option("--composed-by <name>", "Find components that compose the named component").option("--format <fmt>", "Output format: json or table (default: auto-detect)").option("--manifest <path>", "Path to manifest.json", MANIFEST_PATH).action(
     (opts) => {
       try {
         const manifest = loadManifest(opts.manifest);
@@ -1415,9 +1611,11 @@ function registerQuery(manifestCmd) {
         if (opts.complexity !== void 0) queryParts.push(`complexity=${opts.complexity}`);
         if (opts.sideEffects) queryParts.push("side-effects");
         if (opts.hasFetch) queryParts.push("has-fetch");
+        if (opts.hasProp !== void 0) queryParts.push(`has-prop=${opts.hasProp}`);
+        if (opts.composedBy !== void 0) queryParts.push(`composed-by=${opts.composedBy}`);
         if (queryParts.length === 0) {
           process.stderr.write(
-            "No query flags specified. Use --context, --hook, --complexity, --side-effects, or --has-fetch.\n"
+            "No query flags specified. Use --context, --hook, --complexity, --side-effects, --has-fetch, --has-prop, or --composed-by.\n"
           );
           process.exit(1);
         }
@@ -1444,6 +1642,27 @@ function registerQuery(manifestCmd) {
         if (opts.hasFetch) {
           entries = entries.filter(([, d]) => d.sideEffects.fetches.length > 0);
         }
+        if (opts.hasProp !== void 0) {
+          const spec = opts.hasProp;
+          const colonIdx = spec.indexOf(":");
+          const propName = colonIdx >= 0 ? spec.slice(0, colonIdx) : spec;
+          const propType = colonIdx >= 0 ? spec.slice(colonIdx + 1) : void 0;
+          entries = entries.filter(([, d]) => {
+            const props = d.props;
+            if (!props || !(propName in props)) return false;
+            if (propType !== void 0) {
+              return props[propName]?.type === propType;
+            }
+            return true;
+          });
+        }
+        if (opts.composedBy !== void 0) {
+          const targetName = opts.composedBy;
+          entries = entries.filter(([, d]) => {
+            const composedBy = d.composedBy;
+            return composedBy !== void 0 && composedBy.includes(targetName);
+          });
+        }
         const rows = entries.map(([name, d]) => ({
           name,
           file: d.filePath,
@@ -2996,8 +3215,8 @@ function createInstrumentCommand() {
 }
 // src/render-commands.ts
-import { mkdirSync as mkdirSync3, writeFileSync as writeFileSync5 } from "fs";
-import { resolve as resolve8 } from "path";
+import { existsSync as existsSync7, mkdirSync as mkdirSync4, readFileSync as readFileSync6, writeFileSync as writeFileSync5 } from "fs";
+import { resolve as resolve9 } from "path";
 import {
   ALL_CONTEXT_IDS,
   ALL_STRESS_IDS,
@@ -3009,6 +3228,140 @@ import {
   stressAxis
 } from "@agent-scope/render";
 import { Command as Command6 } from "commander";
+// src/scope-file.ts
+import { existsSync as existsSync6, mkdirSync as mkdirSync3, rmSync } from "fs";
+import { createRequire as createRequire2 } from "module";
+import { tmpdir } from "os";
+import { dirname as dirname2, join as join3, resolve as resolve8 } from "path";
+import * as esbuild2 from "esbuild";
+var SCOPE_EXTENSIONS = [".scope.tsx", ".scope.ts", ".scope.jsx", ".scope.js"];
+function findScopeFile(componentFilePath) {
+  const dir = dirname2(componentFilePath);
+  const stem = componentFilePath.replace(/\.(tsx?|jsx?)$/, "");
+  const baseName = stem.slice(dir.length + 1);
+  for (const ext of SCOPE_EXTENSIONS) {
+    const candidate = join3(dir, `${baseName}${ext}`);
+    if (existsSync6(candidate)) return candidate;
+  }
+  return null;
+}
+async function loadScopeFile(scopeFilePath) {
+  const tmpDir = join3(tmpdir(), `scope-file-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+  mkdirSync3(tmpDir, { recursive: true });
+  const outFile = join3(tmpDir, "scope-file.cjs");
+  try {
+    const result = await esbuild2.build({
+      entryPoints: [scopeFilePath],
+      bundle: true,
+      format: "cjs",
+      platform: "node",
+      target: "node18",
+      outfile: outFile,
+      write: true,
+      jsx: "automatic",
+      jsxImportSource: "react",
+      // Externalize React — we don't need to execute JSX, just extract plain data
+      external: ["react", "react-dom", "react/jsx-runtime"],
+      define: {
+        "process.env.NODE_ENV": '"development"'
+      },
+      logLevel: "silent"
+    });
+    if (result.errors.length > 0) {
+      const msg = result.errors.map((e) => `${e.text}${e.location ? ` (${e.location.file}:${e.location.line})` : ""}`).join("\n");
+      throw new Error(`Failed to bundle scope file ${scopeFilePath}:
+${msg}`);
+    }
+    const req = createRequire2(import.meta.url);
+    delete req.cache[resolve8(outFile)];
+    const mod = req(outFile);
+    const scenarios = extractScenarios(mod, scopeFilePath);
+    const hasWrapper = typeof mod.wrapper === "function" || typeof mod.default?.wrapper === "function";
+    return { filePath: scopeFilePath, scenarios, hasWrapper };
+  } finally {
+    try {
+      rmSync(tmpDir, { recursive: true, force: true });
+    } catch {
+    }
+  }
+}
+async function loadScopeFileForComponent(componentFilePath) {
+  const scopeFilePath = findScopeFile(componentFilePath);
+  if (scopeFilePath === null) return null;
+  return loadScopeFile(scopeFilePath);
+}
+function extractScenarios(mod, filePath) {
+  const raw = mod.scenarios ?? mod.default?.scenarios;
+  if (raw === void 0) return {};
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    console.warn(`[scope] ${filePath}: "scenarios" export is not a plain object \u2014 ignoring.`);
+    return {};
+  }
+  const result = {};
+  for (const [name, props] of Object.entries(raw)) {
+    if (typeof props !== "object" || props === null || Array.isArray(props)) {
+      console.warn(`[scope] ${filePath}: scenario "${name}" is not a plain object \u2014 skipping.`);
+      continue;
+    }
+    result[name] = props;
+  }
+  return result;
+}
+async function buildWrapperScript(scopeFilePath) {
+  const wrapperEntry = (
+    /* ts */
+    `
+import * as __scopeMod from ${JSON.stringify(scopeFilePath)};
+// Expose the wrapper on window so the harness can access it
+var wrapper =
+  __scopeMod.wrapper ??
+  (__scopeMod.default && __scopeMod.default.wrapper) ??
+  null;
+window.__SCOPE_WRAPPER__ = wrapper;
+`
+  );
+  const result = await esbuild2.build({
+    stdin: {
+      contents: wrapperEntry,
+      resolveDir: dirname2(scopeFilePath),
+      loader: "tsx",
+      sourcefile: "__scope_wrapper_entry__.tsx"
+    },
+    bundle: true,
+    format: "iife",
+    platform: "browser",
+    target: "es2020",
+    write: false,
+    jsx: "automatic",
+    jsxImportSource: "react",
+    external: [],
+    define: {
+      "process.env.NODE_ENV": '"development"',
+      global: "globalThis"
+    },
+    logLevel: "silent"
+  });
+  if (result.errors.length > 0) {
+    const msg = result.errors.map((e) => `${e.text}${e.location ? ` (${e.location.file}:${e.location.line})` : ""}`).join("\n");
+    throw new Error(`Failed to build wrapper script from ${scopeFilePath}:
+${msg}`);
+  }
+  return result.outputFiles?.[0]?.text ?? "";
+}
+// src/render-commands.ts
+function loadGlobalCssFilesFromConfig(cwd) {
+  const configPath = resolve9(cwd, "reactscope.config.json");
+  if (!existsSync7(configPath)) return [];
+  try {
+    const raw = readFileSync6(configPath, "utf-8");
+    const cfg = JSON.parse(raw);
+    return cfg.components?.wrappers?.globalCSS ?? [];
+  } catch {
+    return [];
+  }
+}
 var MANIFEST_PATH6 = ".reactscope/manifest.json";
 var DEFAULT_OUTPUT_DIR = ".reactscope/renders";
 var _pool3 = null;
@@ -3029,7 +3382,7 @@ async function shutdownPool3() {
     _pool3 = null;
   }
 }
-function buildRenderer(filePath, componentName, viewportWidth, viewportHeight) {
+function buildRenderer(filePath, componentName, viewportWidth, viewportHeight, globalCssFiles = [], projectCwd = process.cwd(), wrapperScript) {
   const satori = new SatoriRenderer({
     defaultViewport: { width: viewportWidth, height: viewportHeight }
   });
@@ -3038,11 +3391,14 @@ function buildRenderer(filePath, componentName, viewportWidth, viewportHeight) {
     async renderCell(props, _complexityClass) {
       const startMs = performance.now();
       const pool = await getPool3(viewportWidth, viewportHeight);
+      const projectCss = await loadGlobalCss(globalCssFiles, projectCwd);
       const htmlHarness = await buildComponentHarness(
         filePath,
         componentName,
         props,
-        viewportWidth
+        viewportWidth,
+        projectCss ?? void 0,
+        wrapperScript
       );
       const slot = await pool.acquire();
       const { page } = slot;
@@ -3071,9 +3427,9 @@ function buildRenderer(filePath, componentName, viewportWidth, viewportHeight) {
           });
           return [...set];
         });
-        const projectCss = await getCompiledCssForClasses(rootDir, classes);
-        if (projectCss != null && projectCss.length > 0) {
-          await page.addStyleTag({ content: projectCss });
+        const projectCss2 = await getCompiledCssForClasses(rootDir, classes);
+        if (projectCss2 != null && projectCss2.length > 0) {
+          await page.addStyleTag({ content: projectCss2 });
         }
         const renderTimeMs = performance.now() - startMs;
         const rootLocator = page.locator("[data-reactscope-root]");
@@ -3133,8 +3489,37 @@ function buildRenderer(filePath, componentName, viewportWidth, viewportHeight) {
     }
   };
 }
+function buildScenarioMap(opts, scopeData) {
+  if (opts.scenario !== void 0) {
+    if (scopeData === null) {
+      throw new Error(`--scenario "${opts.scenario}" requires a .scope file next to the component`);
+    }
+    const props = scopeData.scenarios[opts.scenario];
+    if (props === void 0) {
+      const available = Object.keys(scopeData.scenarios).join(", ") || "(none)";
+      throw new Error(
+        `Scenario "${opts.scenario}" not found in scope file.
+Available: ${available}`
+      );
+    }
+    return { [opts.scenario]: props };
+  }
+  if (opts.props !== void 0) {
+    let parsed;
+    try {
+      parsed = JSON.parse(opts.props);
+    } catch {
+      throw new Error(`Invalid props JSON: ${opts.props}`);
+    }
+    return { __default__: parsed };
+  }
+  if (scopeData !== null && Object.keys(scopeData.scenarios).length > 0) {
+    return scopeData.scenarios;
+  }
+  return { __default__: {} };
+}
 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_PATH6).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("--scenario <name>", "Run a named scenario from the component's .scope file").option("--viewport <WxH>", "Viewport size e.g. 1280x720", "375x812").option("--theme <name>", "Theme name from the token system").option("-o, --output <path>", "Write PNG to file instead of stdout").option("--format <fmt>", "Output format: png or json (default: auto)").option("--manifest <path>", "Path to manifest.json", MANIFEST_PATH6).action(
     async (componentName, opts) => {
       try {
         const manifest = loadManifest(opts.manifest);
@@ -3154,72 +3539,96 @@ Available: ${available}`
             throw new Error(`Invalid props JSON: ${opts.props}`);
           }
         }
+        if (descriptor.props !== void 0) {
+          const propDefs = descriptor.props;
+          for (const [propName, propDef] of Object.entries(propDefs)) {
+            if (propName in props) continue;
+            if (!propDef.required && propDef.default !== void 0) continue;
+            if (propDef.type === "node" || propDef.type === "string") {
+              props[propName] = propName === "children" ? componentName : propName;
+            } else if (propDef.type === "union" && propDef.values && propDef.values.length > 0) {
+              props[propName] = propDef.values[0];
+            } else if (propDef.type === "boolean") {
+              props[propName] = false;
+            } else if (propDef.type === "number") {
+              props[propName] = 0;
+            }
+          }
+        }
         const { width, height } = parseViewport(opts.viewport);
         const rootDir = process.cwd();
-        const filePath = resolve8(rootDir, descriptor.filePath);
-        const renderer = buildRenderer(filePath, componentName, width, height);
+        const filePath = resolve9(rootDir, descriptor.filePath);
+        const scopeData = await loadScopeFileForComponent(filePath);
+        const wrapperScript = scopeData?.hasWrapper === true ? await buildWrapperScript(scopeData.filePath) : void 0;
+        const scenarios = buildScenarioMap(opts, scopeData);
+        const globalCssFiles = loadGlobalCssFilesFromConfig(rootDir);
+        const renderer = buildRenderer(
+          filePath,
+          componentName,
+          width,
+          height,
+          globalCssFiles,
+          rootDir,
+          wrapperScript
+        );
         process.stderr.write(
           `Rendering ${componentName} [${descriptor.complexityClass}] at ${width}\xD7${height}\u2026
 `
         );
-        const outcome = await safeRender2(
-          () => renderer.renderCell(props, descriptor.complexityClass),
-          {
-            props,
-            sourceLocation: {
-              file: descriptor.filePath,
-              line: descriptor.loc.start,
-              column: 0
+        const fmt2 = resolveSingleFormat(opts.format);
+        let anyFailed = false;
+        for (const [scenarioName, props2] of Object.entries(scenarios)) {
+          const isNamed = scenarioName !== "__default__";
+          const label = isNamed ? `${componentName}:${scenarioName}` : componentName;
+          const outcome = await safeRender2(
+            () => renderer.renderCell(props2, descriptor.complexityClass),
+            {
+              props: props2,
+              sourceLocation: {
+                file: descriptor.filePath,
+                line: descriptor.loc.start,
+                column: 0
+              }
             }
-          }
-        );
-        await shutdownPool3();
-        if (outcome.crashed) {
-          process.stderr.write(`\u2717 Render failed: ${outcome.error.message}
+          );
+          if (outcome.crashed) {
+            process.stderr.write(`\u2717 ${label} render failed: ${outcome.error.message}
 `);
-          const hintList = outcome.error.heuristicFlags.join(", ");
-          if (hintList.length > 0) {
-            process.stderr.write(`  Hints: ${hintList}
+            const hintList = outcome.error.heuristicFlags.join(", ");
+            if (hintList.length > 0) {
+              process.stderr.write(`  Hints: ${hintList}
 `);
+            }
+            anyFailed = true;
+            continue;
           }
-          process.exit(1);
-        }
-        const result = outcome.result;
-        if (opts.output !== void 0) {
-          const outPath = resolve8(process.cwd(), opts.output);
-          writeFileSync5(outPath, result.screenshot);
-          process.stdout.write(
-            `\u2713 ${componentName} \u2192 ${opts.output} (${result.width}\xD7${result.height}, ${result.renderTimeMs.toFixed(0)}ms)
+          const result = outcome.result;
+          const outFileName = isNamed ? `${componentName}-${scenarioName}.png` : `${componentName}.png`;
+          if (opts.output !== void 0 && !isNamed) {
+            const outPath = resolve9(process.cwd(), opts.output);
+            writeFileSync5(outPath, result.screenshot);
+            process.stdout.write(
+              `\u2713 ${label} \u2192 ${opts.output} (${result.width}\xD7${result.height}, ${result.renderTimeMs.toFixed(0)}ms)
 `
-          );
-          return;
-        }
-        const fmt2 = resolveSingleFormat(opts.format);
-        if (fmt2 === "json") {
-          const json = formatRenderJson(componentName, props, result);
-          process.stdout.write(`${JSON.stringify(json, null, 2)}
+            );
+          } else if (fmt2 === "json") {
+            const json = formatRenderJson(label, props2, result);
+            process.stdout.write(`${JSON.stringify(json, null, 2)}
 `);
-        } else if (fmt2 === "file") {
-          const dir = resolve8(process.cwd(), DEFAULT_OUTPUT_DIR);
-          mkdirSync3(dir, { recursive: true });
-          const outPath = resolve8(dir, `${componentName}.png`);
-          writeFileSync5(outPath, result.screenshot);
-          const relPath = `${DEFAULT_OUTPUT_DIR}/${componentName}.png`;
-          process.stdout.write(
-            `\u2713 ${componentName} \u2192 ${relPath} (${result.width}\xD7${result.height}, ${result.renderTimeMs.toFixed(0)}ms)
-`
-          );
-        } else {
-          const dir = resolve8(process.cwd(), DEFAULT_OUTPUT_DIR);
-          mkdirSync3(dir, { recursive: true });
-          const outPath = resolve8(dir, `${componentName}.png`);
-          writeFileSync5(outPath, result.screenshot);
-          const relPath = `${DEFAULT_OUTPUT_DIR}/${componentName}.png`;
-          process.stdout.write(
-            `\u2713 ${componentName} \u2192 ${relPath} (${result.width}\xD7${result.height}, ${result.renderTimeMs.toFixed(0)}ms)
+          } else {
+            const dir = resolve9(process.cwd(), DEFAULT_OUTPUT_DIR);
+            mkdirSync4(dir, { recursive: true });
+            const outPath = resolve9(dir, outFileName);
+            writeFileSync5(outPath, result.screenshot);
+            const relPath = `${DEFAULT_OUTPUT_DIR}/${outFileName}`;
+            process.stdout.write(
+              `\u2713 ${label} \u2192 ${relPath} (${result.width}\xD7${result.height}, ${result.renderTimeMs.toFixed(0)}ms)
 `
-          );
+            );
+          }
         }
+        await shutdownPool3();
+        if (anyFailed) process.exit(1);
       } catch (err) {
         await shutdownPool3();
         process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}
@@ -3230,7 +3639,10 @@ Available: ${available}`
   );
 }
 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(
+  renderCmd.command("matrix <component>").description("Render a component across a matrix of prop axes").option(
+    "--axes <spec>",
+    `Axis definitions: key:v1,v2 space-separated OR JSON object e.g. 'variant:primary,ghost size:sm,lg' or '{"variant":["primary","ghost"],"size":["sm","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_PATH6).action(
@@ -3248,22 +3660,48 @@ Available: ${available}`
         const concurrency = Math.max(1, parseInt(opts.concurrency, 10) || 8);
         const { width, height } = { width: 375, height: 812 };
         const rootDir = process.cwd();
-        const filePath = resolve8(rootDir, descriptor.filePath);
-        const renderer = buildRenderer(filePath, componentName, width, height);
+        const filePath = resolve9(rootDir, descriptor.filePath);
+        const matrixCssFiles = loadGlobalCssFilesFromConfig(rootDir);
+        const renderer = buildRenderer(
+          filePath,
+          componentName,
+          width,
+          height,
+          matrixCssFiles,
+          rootDir
+        );
         const axes = [];
         if (opts.axes !== void 0) {
-          const axisSpecs = opts.axes.trim().split(/\s+/);
-          for (const spec of axisSpecs) {
-            const colonIdx = spec.indexOf(":");
-            if (colonIdx < 0) {
-              throw new Error(`Invalid axis spec "${spec}". Expected format: name:val1,val2,...`);
+          const axesRaw = opts.axes.trim();
+          if (axesRaw.startsWith("{")) {
+            let parsed;
+            try {
+              parsed = JSON.parse(axesRaw);
+            } catch {
+              throw new Error(`Invalid JSON in --axes: ${axesRaw}`);
             }
-            const name = spec.slice(0, colonIdx);
-            const values = spec.slice(colonIdx + 1).split(",").map((v) => v.trim());
-            if (name.length === 0 || values.length === 0) {
-              throw new Error(`Invalid axis spec "${spec}"`);
+            for (const [name, vals] of Object.entries(parsed)) {
+              if (!Array.isArray(vals)) {
+                throw new Error(`Axis "${name}" must be an array of values in JSON format`);
+              }
+              axes.push({ name, values: vals.map(String) });
+            }
+          } else {
+            const axisSpecs = axesRaw.split(/\s+/);
+            for (const spec of axisSpecs) {
+              const colonIdx = spec.indexOf(":");
+              if (colonIdx < 0) {
+                throw new Error(
+                  `Invalid axis spec "${spec}". Expected format: name:val1,val2,...`
+                );
+              }
+              const name = spec.slice(0, colonIdx);
+              const values = spec.slice(colonIdx + 1).split(",").map((v) => v.trim());
+              if (name.length === 0 || values.length === 0) {
+                throw new Error(`Invalid axis spec "${spec}"`);
+              }
+              axes.push({ name, values });
             }
-            axes.push({ name, values });
           }
         }
         if (opts.contexts !== void 0) {
@@ -3315,7 +3753,7 @@ Available: ${available}`
           const { SpriteSheetGenerator: SpriteSheetGenerator2 } = await import("@agent-scope/render");
           const gen = new SpriteSheetGenerator2();
           const sheet = await gen.generate(result);
-          const spritePath = resolve8(process.cwd(), opts.sprite);
+          const spritePath = resolve9(process.cwd(), opts.sprite);
           writeFileSync5(spritePath, sheet.png);
           process.stderr.write(`Sprite sheet saved to ${spritePath}
 `);
@@ -3325,9 +3763,9 @@ Available: ${available}`
           const { SpriteSheetGenerator: SpriteSheetGenerator2 } = await import("@agent-scope/render");
           const gen = new SpriteSheetGenerator2();
           const sheet = await gen.generate(result);
-          const dir = resolve8(process.cwd(), DEFAULT_OUTPUT_DIR);
-          mkdirSync3(dir, { recursive: true });
-          const outPath = resolve8(dir, `${componentName}-matrix.png`);
+          const dir = resolve9(process.cwd(), DEFAULT_OUTPUT_DIR);
+          mkdirSync4(dir, { recursive: true });
+          const outPath = resolve9(dir, `${componentName}-matrix.png`);
           writeFileSync5(outPath, sheet.png);
           const relPath = `${DEFAULT_OUTPUT_DIR}/${componentName}-matrix.png`;
           process.stdout.write(
@@ -3371,8 +3809,8 @@ function registerRenderAll(renderCmd) {
           return;
         }
         const concurrency = Math.max(1, parseInt(opts.concurrency, 10) || 4);
-        const outputDir = resolve8(process.cwd(), opts.outputDir);
-        mkdirSync3(outputDir, { recursive: true });
+        const outputDir = resolve9(process.cwd(), opts.outputDir);
+        mkdirSync4(outputDir, { recursive: true });
         const rootDir = process.cwd();
         process.stderr.write(`Rendering ${total} components (concurrency: ${concurrency})\u2026
 `);
@@ -3381,8 +3819,9 @@ function registerRenderAll(renderCmd) {
         const renderOne = async (name) => {
           const descriptor = manifest.components[name];
           if (descriptor === void 0) return;
-          const filePath = resolve8(rootDir, descriptor.filePath);
-          const renderer = buildRenderer(filePath, name, 375, 812);
+          const filePath = resolve9(rootDir, descriptor.filePath);
+          const allCssFiles = loadGlobalCssFilesFromConfig(process.cwd());
+          const renderer = buildRenderer(filePath, name, 375, 812, allCssFiles, process.cwd());
           const outcome = await safeRender2(
             () => renderer.renderCell({}, descriptor.complexityClass),
             {
@@ -3404,7 +3843,7 @@ function registerRenderAll(renderCmd) {
               success: false,
               errorMessage: outcome.error.message
             });
-            const errPath = resolve8(outputDir, `${name}.error.json`);
+            const errPath = resolve9(outputDir, `${name}.error.json`);
             writeFileSync5(
               errPath,
               JSON.stringify(
@@ -3422,9 +3861,9 @@ function registerRenderAll(renderCmd) {
           }
           const result = outcome.result;
           results.push({ name, renderTimeMs: result.renderTimeMs, success: true });
-          const pngPath = resolve8(outputDir, `${name}.png`);
+          const pngPath = resolve9(outputDir, `${name}.png`);
           writeFileSync5(pngPath, result.screenshot);
-          const jsonPath = resolve8(outputDir, `${name}.json`);
+          const jsonPath = resolve9(outputDir, `${name}.json`);
           writeFileSync5(jsonPath, JSON.stringify(formatRenderJson(name, {}, result), null, 2));
           if (isTTY()) {
             process.stdout.write(
@@ -3497,8 +3936,8 @@ function createRenderCommand() {
 }
 // src/report/baseline.ts
-import { existsSync as existsSync6, mkdirSync as mkdirSync4, rmSync, writeFileSync as writeFileSync6 } from "fs";
-import { resolve as resolve9 } from "path";
+import { existsSync as existsSync8, mkdirSync as mkdirSync5, rmSync as rmSync2, writeFileSync as writeFileSync6 } from "fs";
+import { resolve as resolve10 } from "path";
 import { generateManifest as generateManifest3 } from "@agent-scope/manifest";
 import { BrowserPool as BrowserPool4, safeRender as safeRender3 } from "@agent-scope/render";
 import { ComplianceEngine as ComplianceEngine2, TokenResolver as TokenResolver2 } from "@agent-scope/tokens";
@@ -3647,20 +4086,20 @@ async function runBaseline(options = {}) {
   } = options;
   const startTime = performance.now();
   const rootDir = process.cwd();
-  const baselineDir = resolve9(rootDir, outputDir);
-  const rendersDir = resolve9(baselineDir, "renders");
-  if (existsSync6(baselineDir)) {
-    rmSync(baselineDir, { recursive: true, force: true });
+  const baselineDir = resolve10(rootDir, outputDir);
+  const rendersDir = resolve10(baselineDir, "renders");
+  if (existsSync8(baselineDir)) {
+    rmSync2(baselineDir, { recursive: true, force: true });
   }
-  mkdirSync4(rendersDir, { recursive: true });
+  mkdirSync5(rendersDir, { recursive: true });
   let manifest;
   if (manifestPath !== void 0) {
-    const { readFileSync: readFileSync12 } = await import("fs");
-    const absPath = resolve9(rootDir, manifestPath);
-    if (!existsSync6(absPath)) {
+    const { readFileSync: readFileSync13 } = await import("fs");
+    const absPath = resolve10(rootDir, manifestPath);
+    if (!existsSync8(absPath)) {
       throw new Error(`Manifest not found at ${absPath}.`);
     }
-    manifest = JSON.parse(readFileSync12(absPath, "utf-8"));
+    manifest = JSON.parse(readFileSync13(absPath, "utf-8"));
     process.stderr.write(`Loaded manifest from ${manifestPath}
 `);
   } else {
@@ -3670,7 +4109,7 @@ async function runBaseline(options = {}) {
     process.stderr.write(`Found ${count} components.
 `);
   }
-  writeFileSync6(resolve9(baselineDir, "manifest.json"), JSON.stringify(manifest, null, 2), "utf-8");
+  writeFileSync6(resolve10(baselineDir, "manifest.json"), JSON.stringify(manifest, null, 2), "utf-8");
   let componentNames = Object.keys(manifest.components);
   if (componentsGlob !== void 0) {
     componentNames = componentNames.filter((name) => matchGlob(componentsGlob, name));
@@ -3691,7 +4130,7 @@ async function runBaseline(options = {}) {
       auditedAt: (/* @__PURE__ */ new Date()).toISOString()
     };
     writeFileSync6(
-      resolve9(baselineDir, "compliance.json"),
+      resolve10(baselineDir, "compliance.json"),
       JSON.stringify(emptyReport, null, 2),
       "utf-8"
     );
@@ -3712,7 +4151,7 @@ async function runBaseline(options = {}) {
   const renderOne = async (name) => {
     const descriptor = manifest.components[name];
     if (descriptor === void 0) return;
-    const filePath = resolve9(rootDir, descriptor.filePath);
+    const filePath = resolve10(rootDir, descriptor.filePath);
     const outcome = await safeRender3(
       () => renderComponent2(filePath, name, {}, viewportWidth, viewportHeight),
       {
@@ -3731,7 +4170,7 @@ async function runBaseline(options = {}) {
     }
     if (outcome.crashed) {
       failureCount++;
-      const errPath = resolve9(rendersDir, `${name}.error.json`);
+      const errPath = resolve10(rendersDir, `${name}.error.json`);
       writeFileSync6(
         errPath,
         JSON.stringify(
@@ -3749,10 +4188,10 @@ async function runBaseline(options = {}) {
       return;
     }
     const result = outcome.result;
-    writeFileSync6(resolve9(rendersDir, `${name}.png`), result.screenshot);
+    writeFileSync6(resolve10(rendersDir, `${name}.png`), result.screenshot);
     const jsonOutput = formatRenderJson(name, {}, result);
     writeFileSync6(
-      resolve9(rendersDir, `${name}.json`),
+      resolve10(rendersDir, `${name}.json`),
       JSON.stringify(jsonOutput, null, 2),
       "utf-8"
     );
@@ -3780,7 +4219,7 @@ async function runBaseline(options = {}) {
   const engine = new ComplianceEngine2(resolver);
   const batchReport = engine.auditBatch(computedStylesMap);
   writeFileSync6(
-    resolve9(baselineDir, "compliance.json"),
+    resolve10(baselineDir, "compliance.json"),
     JSON.stringify(batchReport, null, 2),
     "utf-8"
   );
@@ -3823,22 +4262,22 @@ function registerBaselineSubCommand(reportCmd) {
 }
 // src/report/diff.ts
-import { existsSync as existsSync7, readFileSync as readFileSync6, writeFileSync as writeFileSync7 } from "fs";
-import { resolve as resolve10 } from "path";
+import { existsSync as existsSync9, readFileSync as readFileSync7, writeFileSync as writeFileSync7 } from "fs";
+import { resolve as resolve11 } from "path";
 import { generateManifest as generateManifest4 } from "@agent-scope/manifest";
 import { BrowserPool as BrowserPool5, safeRender as safeRender4 } from "@agent-scope/render";
 import { ComplianceEngine as ComplianceEngine3, TokenResolver as TokenResolver3 } from "@agent-scope/tokens";
 var DEFAULT_BASELINE_DIR2 = ".reactscope/baseline";
 function loadBaselineCompliance(baselineDir) {
-  const compliancePath = resolve10(baselineDir, "compliance.json");
-  if (!existsSync7(compliancePath)) return null;
-  const raw = JSON.parse(readFileSync6(compliancePath, "utf-8"));
+  const compliancePath = resolve11(baselineDir, "compliance.json");
+  if (!existsSync9(compliancePath)) return null;
+  const raw = JSON.parse(readFileSync7(compliancePath, "utf-8"));
   return raw;
 }
 function loadBaselineRenderJson2(baselineDir, componentName) {
-  const jsonPath = resolve10(baselineDir, "renders", `${componentName}.json`);
-  if (!existsSync7(jsonPath)) return null;
-  return JSON.parse(readFileSync6(jsonPath, "utf-8"));
+  const jsonPath = resolve11(baselineDir, "renders", `${componentName}.json`);
+  if (!existsSync9(jsonPath)) return null;
+  return JSON.parse(readFileSync7(jsonPath, "utf-8"));
 }
 var _pool5 = null;
 async function getPool5(viewportWidth, viewportHeight) {
@@ -4005,19 +4444,19 @@ async function runDiff(options = {}) {
   } = options;
   const startTime = performance.now();
   const rootDir = process.cwd();
-  const baselineDir = resolve10(rootDir, baselineDirRaw);
-  if (!existsSync7(baselineDir)) {
+  const baselineDir = resolve11(rootDir, baselineDirRaw);
+  if (!existsSync9(baselineDir)) {
     throw new Error(
       `Baseline directory not found at "${baselineDir}". Run \`scope report baseline\` first to create a baseline snapshot.`
     );
   }
-  const baselineManifestPath = resolve10(baselineDir, "manifest.json");
-  if (!existsSync7(baselineManifestPath)) {
+  const baselineManifestPath = resolve11(baselineDir, "manifest.json");
+  if (!existsSync9(baselineManifestPath)) {
     throw new Error(
       `Baseline manifest.json not found at "${baselineManifestPath}". The baseline directory may be incomplete \u2014 re-run \`scope report baseline\`.`
     );
   }
-  const baselineManifest = JSON.parse(readFileSync6(baselineManifestPath, "utf-8"));
+  const baselineManifest = JSON.parse(readFileSync7(baselineManifestPath, "utf-8"));
   const baselineCompliance = loadBaselineCompliance(baselineDir);
   const baselineComponentNames = new Set(Object.keys(baselineManifest.components));
   process.stderr.write(
@@ -4026,11 +4465,11 @@ async function runDiff(options = {}) {
   );
   let currentManifest;
   if (manifestPath !== void 0) {
-    const absPath = resolve10(rootDir, manifestPath);
-    if (!existsSync7(absPath)) {
+    const absPath = resolve11(rootDir, manifestPath);
+    if (!existsSync9(absPath)) {
       throw new Error(`Manifest not found at "${absPath}".`);
     }
-    currentManifest = JSON.parse(readFileSync6(absPath, "utf-8"));
+    currentManifest = JSON.parse(readFileSync7(absPath, "utf-8"));
     process.stderr.write(`Loaded manifest from ${manifestPath}
 `);
   } else {
@@ -4063,7 +4502,7 @@ async function runDiff(options = {}) {
   const renderOne = async (name) => {
     const descriptor = currentManifest.components[name];
     if (descriptor === void 0) return;
-    const filePath = resolve10(rootDir, descriptor.filePath);
+    const filePath = resolve11(rootDir, descriptor.filePath);
     const outcome = await safeRender4(
       () => renderComponent3(filePath, name, {}, viewportWidth, viewportHeight),
       {
@@ -4303,8 +4742,8 @@ function registerDiffSubCommand(reportCmd) {
 }
 // src/report/pr-comment.ts
-import { existsSync as existsSync8, readFileSync as readFileSync7, writeFileSync as writeFileSync8 } from "fs";
-import { resolve as resolve11 } from "path";
+import { existsSync as existsSync10, readFileSync as readFileSync8, writeFileSync as writeFileSync8 } from "fs";
+import { resolve as resolve12 } from "path";
 var STATUS_BADGE = {
   added: "\u2705 added",
   removed: "\u{1F5D1}\uFE0F removed",
@@ -4387,13 +4826,13 @@ function formatPrComment(diff) {
   return lines.join("\n");
 }
 function loadDiffResult(filePath) {
-  const abs = resolve11(filePath);
-  if (!existsSync8(abs)) {
+  const abs = resolve12(filePath);
+  if (!existsSync10(abs)) {
     throw new Error(`DiffResult file not found: ${abs}`);
   }
   let raw;
   try {
-    raw = readFileSync7(abs, "utf-8");
+    raw = readFileSync8(abs, "utf-8");
   } catch (err) {
     throw new Error(
       `Failed to read DiffResult file: ${err instanceof Error ? err.message : String(err)}`
@@ -4420,7 +4859,7 @@ function registerPrCommentSubCommand(reportCmd) {
       const diff = loadDiffResult(opts.input);
       const comment = formatPrComment(diff);
       if (opts.output !== void 0) {
-        writeFileSync8(resolve11(opts.output), comment, "utf-8");
+        writeFileSync8(resolve12(opts.output), comment, "utf-8");
         process.stderr.write(`PR comment written to ${opts.output}
 `);
       } else {
@@ -4715,9 +5154,9 @@ function buildStructuredReport(report) {
 }
 // src/site-commands.ts
-import { createReadStream, existsSync as existsSync9, statSync } from "fs";
+import { createReadStream, existsSync as existsSync11, statSync } from "fs";
 import { createServer } from "http";
-import { extname, join as join3, resolve as resolve12 } from "path";
+import { extname, join as join4, resolve as resolve13 } from "path";
 import { buildSite } from "@agent-scope/site";
 import { Command as Command7 } from "commander";
 var MIME_TYPES = {
@@ -4735,16 +5174,16 @@ function registerBuild(siteCmd) {
   siteCmd.command("build").description("Build a static HTML gallery from .reactscope/ output").option("-i, --input <path>", "Path to .reactscope input directory", ".reactscope").option("-o, --output <path>", "Output directory for generated site", ".reactscope/site").option("--base-path <path>", "Base URL path prefix for subdirectory deployment", "/").option("--compliance <path>", "Path to compliance batch report JSON").option("--title <text>", "Site title", "Scope \u2014 Component Gallery").action(
     async (opts) => {
       try {
-        const inputDir = resolve12(process.cwd(), opts.input);
-        const outputDir = resolve12(process.cwd(), opts.output);
-        if (!existsSync9(inputDir)) {
+        const inputDir = resolve13(process.cwd(), opts.input);
+        const outputDir = resolve13(process.cwd(), opts.output);
+        if (!existsSync11(inputDir)) {
           throw new Error(
             `Input directory not found: ${inputDir}
 Run \`scope manifest generate\` and \`scope render\` first.`
           );
         }
-        const manifestPath = join3(inputDir, "manifest.json");
-        if (!existsSync9(manifestPath)) {
+        const manifestPath = join4(inputDir, "manifest.json");
+        if (!existsSync11(manifestPath)) {
           throw new Error(
             `Manifest not found at ${manifestPath}
 Run \`scope manifest generate\` first.`
@@ -4757,7 +5196,7 @@ Run \`scope manifest generate\` first.`
           outputDir,
           basePath: opts.basePath,
           ...opts.compliance !== void 0 && {
-            compliancePath: resolve12(process.cwd(), opts.compliance)
+            compliancePath: resolve13(process.cwd(), opts.compliance)
           },
           title: opts.title
         });
@@ -4780,8 +5219,8 @@ function registerServe(siteCmd) {
       if (Number.isNaN(port) || port < 1 || port > 65535) {
         throw new Error(`Invalid port: ${opts.port}`);
       }
-      const serveDir = resolve12(process.cwd(), opts.dir);
-      if (!existsSync9(serveDir)) {
+      const serveDir = resolve13(process.cwd(), opts.dir);
+      if (!existsSync11(serveDir)) {
         throw new Error(
           `Serve directory not found: ${serveDir}
 Run \`scope site build\` first.`
@@ -4790,13 +5229,13 @@ Run \`scope site build\` first.`
       const server = createServer((req, res) => {
         const rawUrl = req.url ?? "/";
         const urlPath = decodeURIComponent(rawUrl.split("?")[0] ?? "/");
-        const filePath = join3(serveDir, urlPath.endsWith("/") ? `${urlPath}index.html` : urlPath);
+        const filePath = join4(serveDir, urlPath.endsWith("/") ? `${urlPath}index.html` : urlPath);
         if (!filePath.startsWith(serveDir)) {
           res.writeHead(403, { "Content-Type": "text/plain" });
           res.end("Forbidden");
           return;
         }
-        if (existsSync9(filePath) && statSync(filePath).isFile()) {
+        if (existsSync11(filePath) && statSync(filePath).isFile()) {
           const ext = extname(filePath).toLowerCase();
           const contentType = MIME_TYPES[ext] ?? "application/octet-stream";
           res.writeHead(200, { "Content-Type": contentType });
@@ -4804,7 +5243,7 @@ Run \`scope site build\` first.`
           return;
         }
         const htmlPath = `${filePath}.html`;
-        if (existsSync9(htmlPath) && statSync(htmlPath).isFile()) {
+        if (existsSync11(htmlPath) && statSync(htmlPath).isFile()) {
           res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
           createReadStream(htmlPath).pipe(res);
           return;
@@ -4846,8 +5285,8 @@ function createSiteCommand() {
 }
 // src/tokens/commands.ts
-import { existsSync as existsSync12, readFileSync as readFileSync10 } from "fs";
-import { resolve as resolve16 } from "path";
+import { existsSync as existsSync14, readFileSync as readFileSync11 } from "fs";
+import { resolve as resolve17 } from "path";
 import {
   parseTokenFileSync as parseTokenFileSync2,
   TokenParseError,
@@ -4858,23 +5297,23 @@ import {
 import { Command as Command9 } from "commander";
 // src/tokens/compliance.ts
-import { existsSync as existsSync10, readFileSync as readFileSync8 } from "fs";
-import { resolve as resolve13 } from "path";
+import { existsSync as existsSync12, readFileSync as readFileSync9 } from "fs";
+import { resolve as resolve14 } from "path";
 import {
   ComplianceEngine as ComplianceEngine4,
   TokenResolver as TokenResolver4
 } from "@agent-scope/tokens";
 var DEFAULT_STYLES_PATH = ".reactscope/compliance-styles.json";
 function loadStylesFile(stylesPath) {
-  const absPath = resolve13(process.cwd(), stylesPath);
-  if (!existsSync10(absPath)) {
+  const absPath = resolve14(process.cwd(), stylesPath);
+  if (!existsSync12(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 = readFileSync8(absPath, "utf-8");
+  const raw = readFileSync9(absPath, "utf-8");
   let parsed;
   try {
     parsed = JSON.parse(raw);
@@ -5034,8 +5473,8 @@ function registerCompliance(tokensCmd) {
 }
 // src/tokens/export.ts
-import { existsSync as existsSync11, readFileSync as readFileSync9, writeFileSync as writeFileSync9 } from "fs";
-import { resolve as resolve14 } from "path";
+import { existsSync as existsSync13, readFileSync as readFileSync10, writeFileSync as writeFileSync9 } from "fs";
+import { resolve as resolve15 } from "path";
 import {
   exportTokens,
   parseTokenFileSync,
@@ -5048,21 +5487,21 @@ var CONFIG_FILE = "reactscope.config.json";
 var SUPPORTED_FORMATS = ["css", "ts", "scss", "tailwind", "flat-json", "figma"];
 function resolveTokenFilePath2(fileFlag) {
   if (fileFlag !== void 0) {
-    return resolve14(process.cwd(), fileFlag);
+    return resolve15(process.cwd(), fileFlag);
   }
-  const configPath = resolve14(process.cwd(), CONFIG_FILE);
-  if (existsSync11(configPath)) {
+  const configPath = resolve15(process.cwd(), CONFIG_FILE);
+  if (existsSync13(configPath)) {
     try {
-      const raw = readFileSync9(configPath, "utf-8");
+      const raw = readFileSync10(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 resolve14(process.cwd(), file);
+        return resolve15(process.cwd(), file);
       }
     } catch {
     }
   }
-  return resolve14(process.cwd(), DEFAULT_TOKEN_FILE);
+  return resolve15(process.cwd(), DEFAULT_TOKEN_FILE);
 }
 function createTokensExportCommand() {
   return new Command8("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(
@@ -5071,23 +5510,33 @@ function createTokensExportCommand() {
   ).action(
     (opts) => {
       if (!SUPPORTED_FORMATS.includes(opts.format)) {
+        const FORMAT_ALIASES = {
+          json: "flat-json",
+          "json-flat": "flat-json",
+          javascript: "ts",
+          js: "ts",
+          sass: "scss",
+          tw: "tailwind"
+        };
+        const hint = FORMAT_ALIASES[opts.format.toLowerCase()];
         process.stderr.write(
           `Error: unsupported format "${opts.format}".
 Supported formats: ${SUPPORTED_FORMATS.join(", ")}
-`
+` + (hint ? `Did you mean "${hint}"?
+` : "")
         );
         process.exit(1);
       }
       const format = opts.format;
       try {
         const filePath = resolveTokenFilePath2(opts.file);
-        if (!existsSync11(filePath)) {
+        if (!existsSync13(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 = readFileSync9(filePath, "utf-8");
+        const raw = readFileSync10(filePath, "utf-8");
         const { tokens, rawFile } = parseTokenFileSync(raw);
         let themesMap;
         if (opts.theme !== void 0) {
@@ -5126,7 +5575,7 @@ Available themes: ${themeNames.join(", ")}`
           themes: themesMap
         });
         if (opts.out !== void 0) {
-          const outPath = resolve14(process.cwd(), opts.out);
+          const outPath = resolve15(process.cwd(), opts.out);
           writeFileSync9(outPath, output, "utf-8");
           process.stderr.write(`Exported ${tokens.length} tokens to ${outPath}
 `);
@@ -5241,8 +5690,8 @@ ${formatImpactSummary(report)}
 }
 // src/tokens/preview.ts
-import { mkdirSync as mkdirSync5, writeFileSync as writeFileSync10 } from "fs";
-import { resolve as resolve15 } from "path";
+import { mkdirSync as mkdirSync6, writeFileSync as writeFileSync10 } from "fs";
+import { resolve as resolve16 } from "path";
 import { BrowserPool as BrowserPool6, SpriteSheetGenerator } from "@agent-scope/render";
 import { ComplianceEngine as ComplianceEngine6, ImpactAnalyzer as ImpactAnalyzer2, TokenResolver as TokenResolver7 } from "@agent-scope/tokens";
 var DEFAULT_STYLES_PATH3 = ".reactscope/compliance-styles.json";
@@ -5423,9 +5872,9 @@ function registerPreview(tokensCmd) {
         });
         const spriteResult = await generator.generate(matrixResult);
         const tokenLabel = tokenPath.replace(/\./g, "-");
-        const outputPath = opts.output ?? resolve15(process.cwd(), DEFAULT_OUTPUT_DIR2, `preview-${tokenLabel}.png`);
-        const outputDir = resolve15(outputPath, "..");
-        mkdirSync5(outputDir, { recursive: true });
+        const outputPath = opts.output ?? resolve16(process.cwd(), DEFAULT_OUTPUT_DIR2, `preview-${tokenLabel}.png`);
+        const outputDir = resolve16(outputPath, "..");
+        mkdirSync6(outputDir, { recursive: true });
         writeFileSync10(outputPath, spriteResult.png);
         const useJson = opts.format === "json" || opts.format !== "text" && !isTTY();
         if (useJson) {
@@ -5485,30 +5934,30 @@ function buildTable2(headers, rows) {
 }
 function resolveTokenFilePath(fileFlag) {
   if (fileFlag !== void 0) {
-    return resolve16(process.cwd(), fileFlag);
+    return resolve17(process.cwd(), fileFlag);
   }
-  const configPath = resolve16(process.cwd(), CONFIG_FILE2);
-  if (existsSync12(configPath)) {
+  const configPath = resolve17(process.cwd(), CONFIG_FILE2);
+  if (existsSync14(configPath)) {
     try {
-      const raw = readFileSync10(configPath, "utf-8");
+      const raw = readFileSync11(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 resolve16(process.cwd(), file);
+        return resolve17(process.cwd(), file);
       }
     } catch {
     }
   }
-  return resolve16(process.cwd(), DEFAULT_TOKEN_FILE2);
+  return resolve17(process.cwd(), DEFAULT_TOKEN_FILE2);
 }
 function loadTokens(absPath) {
-  if (!existsSync12(absPath)) {
+  if (!existsSync14(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 = readFileSync10(absPath, "utf-8");
+  const raw = readFileSync11(absPath, "utf-8");
   return parseTokenFileSync2(raw);
 }
 function getRawValue(node, segments) {
@@ -5722,13 +6171,13 @@ function registerValidate(tokensCmd) {
   ).option("--file <path>", "Path to token file (overrides config)").option("--format <fmt>", "Output format: json or text (default: auto-detect)").action((opts) => {
     try {
       const filePath = resolveTokenFilePath(opts.file);
-      if (!existsSync12(filePath)) {
+      if (!existsSync14(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 = readFileSync10(filePath, "utf-8");
+      const raw = readFileSync11(filePath, "utf-8");
       const useJson = opts.format === "json" || opts.format !== "text" && !isTTY2();
       const errors = [];
       let parsed;
@@ -5886,7 +6335,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 = readFileSync11(tracePath, "utf-8");
+    const raw = readFileSync12(tracePath, "utf-8");
     const trace = loadTrace(raw);
     const source = generateTest(trace, {
       description: opts.description,