@agent-scope/cli 1.17.3 → 1.18.1

package/dist/index.cjs

@@ -6,14 +6,16 @@ var manifest = require('@agent-scope/manifest');
 var render = require('@agent-scope/render');
 var tokens = require('@agent-scope/tokens');
 var commander = require('commander');
-var esbuild = require('esbuild');
+var esbuild2 = require('esbuild');
 var module$1 = require('module');
 var readline = require('readline');
 var playwright = require('@agent-scope/playwright');
 var playwright$1 = require('playwright');
+var os = require('os');
 var http = require('http');
 var site = require('@agent-scope/site');
 
+var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
 function _interopNamespace(e) {
   if (e && e.__esModule) return e;
   var n = Object.create(null);
@@ -32,13 +34,13 @@ function _interopNamespace(e) {
   return Object.freeze(n);
 }
 
-var esbuild__namespace = /*#__PURE__*/_interopNamespace(esbuild);
+var esbuild2__namespace = /*#__PURE__*/_interopNamespace(esbuild2);
 var readline__namespace = /*#__PURE__*/_interopNamespace(readline);
 
 // src/ci/commands.ts
-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>");
@@ -74,7 +76,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;
@@ -86,7 +93,7 @@ import { createElement } from "react";
 })();
 `
   );
-  const result = await esbuild__namespace.build({
+  const result = await esbuild2__namespace.build({
     stdin: {
       contents: wrapperCode,
       // Resolve relative imports (within the component's dir)
@@ -111,6 +118,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) {
@@ -124,12 +146,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>
@@ -144,7 +165,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>`;
 }
@@ -507,16 +529,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(path.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 = path.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
@@ -1021,6 +1094,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) => fs.existsSync(path.join(rootDir, rel)));
+}
 var TAILWIND_STEMS = ["tailwind.config"];
 var CSS_EXTS = [".css", ".scss", ".sass", ".less"];
 var THEME_SUFFIXES = [".theme.ts", ".theme.js", ".theme.tsx"];
@@ -1088,13 +1175,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
   };
 }
 function buildDefaultConfig(detected, tokenFile, outputDir) {
@@ -1103,7 +1192,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 } },
@@ -1134,9 +1223,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());
     });
   });
 }
@@ -1161,18 +1250,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 = fs.readFileSync(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$1 = path.join(rootDir, "reactscope.config.json");
   fs.writeFileSync(path$1, `${JSON.stringify(config, null, 2)}
 `);
   return path$1;
 }
-function scaffoldTokenFile(rootDir, tokenFile) {
+function scaffoldTokenFile(rootDir, tokenFile, extractedTokens) {
   const path$1 = path.join(rootDir, tokenFile);
   if (!fs.existsSync(path$1)) {
     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 ?? {}
     };
     fs.writeFileSync(path$1, `${JSON.stringify(stub, null, 2)}
 `);
@@ -1250,7 +1439,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);
@@ -1350,7 +1545,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);
@@ -1361,9 +1559,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);
         }
@@ -1390,6 +1590,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,
@@ -2958,6 +3179,133 @@ function writeReportToFile(report, outputPath, pretty) {
   const json = pretty ? JSON.stringify(report, null, 2) : JSON.stringify(report);
   fs.writeFileSync(outputPath, json, "utf-8");
 }
+var SCOPE_EXTENSIONS = [".scope.tsx", ".scope.ts", ".scope.jsx", ".scope.js"];
+function findScopeFile(componentFilePath) {
+  const dir = path.dirname(componentFilePath);
+  const stem = componentFilePath.replace(/\.(tsx?|jsx?)$/, "");
+  const baseName = stem.slice(dir.length + 1);
+  for (const ext of SCOPE_EXTENSIONS) {
+    const candidate = path.join(dir, `${baseName}${ext}`);
+    if (fs.existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+async function loadScopeFile(scopeFilePath) {
+  const tmpDir = path.join(os.tmpdir(), `scope-file-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+  fs.mkdirSync(tmpDir, { recursive: true });
+  const outFile = path.join(tmpDir, "scope-file.cjs");
+  try {
+    const result = await esbuild2__namespace.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 = module$1.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href)));
+    delete req.cache[path.resolve(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 {
+      fs.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__namespace.build({
+    stdin: {
+      contents: wrapperEntry,
+      resolveDir: path.dirname(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 = path.resolve(cwd, "reactscope.config.json");
+  if (!fs.existsSync(configPath)) return [];
+  try {
+    const raw = fs.readFileSync(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;
@@ -2978,7 +3326,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 render.SatoriRenderer({
     defaultViewport: { width: viewportWidth, height: viewportHeight }
   });
@@ -2987,11 +3335,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;
@@ -3020,9 +3371,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]");
@@ -3082,8 +3433,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);
@@ -3103,72 +3483,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 = path.resolve(rootDir, descriptor.filePath);
-        const renderer = buildRenderer(filePath, componentName, width, height);
+        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 render.safeRender(
-          () => 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 render.safeRender(
+            () => 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 = path.resolve(process.cwd(), opts.output);
-          fs.writeFileSync(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 = path.resolve(process.cwd(), opts.output);
+            fs.writeFileSync(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 = path.resolve(process.cwd(), DEFAULT_OUTPUT_DIR);
-          fs.mkdirSync(dir, { recursive: true });
-          const outPath = path.resolve(dir, `${componentName}.png`);
-          fs.writeFileSync(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 = path.resolve(process.cwd(), DEFAULT_OUTPUT_DIR);
-          fs.mkdirSync(dir, { recursive: true });
-          const outPath = path.resolve(dir, `${componentName}.png`);
-          fs.writeFileSync(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 = path.resolve(process.cwd(), DEFAULT_OUTPUT_DIR);
+            fs.mkdirSync(dir, { recursive: true });
+            const outPath = path.resolve(dir, outFileName);
+            fs.writeFileSync(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)}
@@ -3179,7 +3583,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(
@@ -3198,21 +3605,47 @@ Available: ${available}`
         const { width, height } = { width: 375, height: 812 };
         const rootDir = process.cwd();
         const filePath = path.resolve(rootDir, descriptor.filePath);
-        const renderer = buildRenderer(filePath, componentName, width, height);
+        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) {
@@ -3331,7 +3764,8 @@ function registerRenderAll(renderCmd) {
           const descriptor = manifest.components[name];
           if (descriptor === void 0) return;
           const filePath = path.resolve(rootDir, descriptor.filePath);
-          const renderer = buildRenderer(filePath, name, 375, 812);
+          const allCssFiles = loadGlobalCssFilesFromConfig(process.cwd());
+          const renderer = buildRenderer(filePath, name, 375, 812, allCssFiles, process.cwd());
           const outcome = await render.safeRender(
             () => renderer.renderCell({}, descriptor.complexityClass),
             {
@@ -3597,12 +4031,12 @@ async function runBaseline(options = {}) {
   fs.mkdirSync(rendersDir, { recursive: true });
   let manifest$1;
   if (manifestPath !== void 0) {
-    const { readFileSync: readFileSync12 } = await import('fs');
+    const { readFileSync: readFileSync13 } = await import('fs');
     const absPath = path.resolve(rootDir, manifestPath);
     if (!fs.existsSync(absPath)) {
       throw new Error(`Manifest not found at ${absPath}.`);
     }
-    manifest$1 = JSON.parse(readFileSync12(absPath, "utf-8"));
+    manifest$1 = JSON.parse(readFileSync13(absPath, "utf-8"));
     process.stderr.write(`Loaded manifest from ${manifestPath}
 `);
   } else {
@@ -4963,10 +5397,20 @@ 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);
       }