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

@@ -4,18 +4,19 @@ import { generateManifest } from '@agent-scope/manifest';
 import { SpriteSheetGenerator, safeRender, BrowserPool, ALL_CONTEXT_IDS, contextAxis, stressAxis, ALL_STRESS_IDS, RenderMatrix, SatoriRenderer } from '@agent-scope/render';
 import { TokenResolver, ComplianceEngine, parseTokenFileSync, ThemeResolver, exportTokens, validateTokenFile, TokenValidationError, TokenParseError, ImpactAnalyzer } from '@agent-scope/tokens';
 import { Command } from 'commander';
-import * as esbuild from 'esbuild';
+import * as esbuild2 from 'esbuild';
 import { createRequire } from 'module';
 import * as readline from 'readline';
 import { loadTrace, generateTest, getBrowserEntryScript } from '@agent-scope/playwright';
 import { chromium } from 'playwright';
+import { tmpdir } from 'os';
 import { createServer } from 'http';
 import { buildSite } from '@agent-scope/site';
 // 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>");
@@ -51,7 +52,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;
@@ -63,7 +69,7 @@ import { createElement } from "react";
 })();
 `
   );
-  const result = await esbuild.build({
+  const result = await esbuild2.build({
     stdin: {
       contents: wrapperCode,
       // Resolve relative imports (within the component's dir)
@@ -88,6 +94,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) {
@@ -101,12 +122,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>
@@ -121,7 +141,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>`;
 }
@@ -484,16 +505,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
@@ -998,6 +1070,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) => existsSync(join(rootDir, rel)));
+}
 var TAILWIND_STEMS = ["tailwind.config"];
 var CSS_EXTS = [".css", ".scss", ".sass", ".less"];
 var THEME_SUFFIXES = [".theme.ts", ".theme.js", ".theme.tsx"];
@@ -1065,13 +1151,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) {
@@ -1080,7 +1168,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 } },
@@ -1111,9 +1199,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());
     });
   });
 }
@@ -1138,18 +1226,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 = 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 = join(rootDir, "reactscope.config.json");
   writeFileSync(path, `${JSON.stringify(config, null, 2)}
 `);
   return path;
 }
-function scaffoldTokenFile(rootDir, tokenFile) {
+function scaffoldTokenFile(rootDir, tokenFile, extractedTokens) {
   const path = join(rootDir, tokenFile);
   if (!existsSync(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 ?? {}
     };
     writeFileSync(path, `${JSON.stringify(stub, null, 2)}
 `);
@@ -1227,7 +1415,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);
@@ -1327,7 +1521,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);
@@ -1338,9 +1535,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);
         }
@@ -1367,6 +1566,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,
@@ -2935,6 +3155,133 @@ function writeReportToFile(report, outputPath, pretty) {
   const json = pretty ? JSON.stringify(report, null, 2) : JSON.stringify(report);
   writeFileSync(outputPath, json, "utf-8");
 }
+var SCOPE_EXTENSIONS = [".scope.tsx", ".scope.ts", ".scope.jsx", ".scope.js"];
+function findScopeFile(componentFilePath) {
+  const dir = dirname(componentFilePath);
+  const stem = componentFilePath.replace(/\.(tsx?|jsx?)$/, "");
+  const baseName = stem.slice(dir.length + 1);
+  for (const ext of SCOPE_EXTENSIONS) {
+    const candidate = join(dir, `${baseName}${ext}`);
+    if (existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+async function loadScopeFile(scopeFilePath) {
+  const tmpDir = join(tmpdir(), `scope-file-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+  mkdirSync(tmpDir, { recursive: true });
+  const outFile = join(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 = createRequire(import.meta.url);
+    delete req.cache[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 {
+      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: 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 = resolve(cwd, "reactscope.config.json");
+  if (!existsSync(configPath)) return [];
+  try {
+    const raw = 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;
@@ -2955,7 +3302,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 }
   });
@@ -2964,11 +3311,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;
@@ -2997,9 +3347,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]");
@@ -3059,8 +3409,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);
@@ -3080,72 +3459,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 = 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 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 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 = resolve(process.cwd(), opts.output);
-          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 = resolve(process.cwd(), opts.output);
+            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 = resolve(process.cwd(), DEFAULT_OUTPUT_DIR);
-          mkdirSync(dir, { recursive: true });
-          const outPath = resolve(dir, `${componentName}.png`);
-          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 = resolve(process.cwd(), DEFAULT_OUTPUT_DIR);
-          mkdirSync(dir, { recursive: true });
-          const outPath = resolve(dir, `${componentName}.png`);
-          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 = resolve(process.cwd(), DEFAULT_OUTPUT_DIR);
+            mkdirSync(dir, { recursive: true });
+            const outPath = resolve(dir, outFileName);
+            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)}
@@ -3156,7 +3559,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(
@@ -3175,21 +3581,47 @@ Available: ${available}`
         const { width, height } = { width: 375, height: 812 };
         const rootDir = process.cwd();
         const filePath = 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) {
@@ -3308,7 +3740,8 @@ function registerRenderAll(renderCmd) {
           const descriptor = manifest.components[name];
           if (descriptor === void 0) return;
           const filePath = 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 safeRender(
             () => renderer.renderCell({}, descriptor.complexityClass),
             {
@@ -3574,12 +4007,12 @@ async function runBaseline(options = {}) {
   mkdirSync(rendersDir, { recursive: true });
   let manifest;
   if (manifestPath !== void 0) {
-    const { readFileSync: readFileSync12 } = await import('fs');
+    const { readFileSync: readFileSync13 } = await import('fs');
     const absPath = resolve(rootDir, manifestPath);
     if (!existsSync(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 {
@@ -4940,10 +5373,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);
       }