@agent-scope/cli 1.18.0 → 1.19.0

package/dist/index.js

@@ -1,4 +1,4 @@
-import { existsSync, writeFileSync, readFileSync, mkdirSync, appendFileSync, readdirSync, rmSync, statSync, createReadStream } from 'fs';
+import { existsSync, writeFileSync, mkdirSync, readFileSync, statSync, appendFileSync, readdirSync, rmSync, createReadStream } from 'fs';
 import { resolve, join, extname, dirname } from 'path';
 import { generateManifest } from '@agent-scope/manifest';
 import { SpriteSheetGenerator, safeRender, BrowserPool, ALL_CONTEXT_IDS, contextAxis, stressAxis, ALL_STRESS_IDS, RenderMatrix, SatoriRenderer } from '@agent-scope/render';
@@ -94,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) {
@@ -501,6 +516,57 @@ async function getCompiledCssForClasses(cwd, classes) {
   if (deduped.length === 0) return null;
   return build3(deduped);
 }
+async function compileGlobalCssFile(cssFilePath, cwd) {
+  const { existsSync: existsSync16, readFileSync: readFileSync14 } = await import('fs');
+  const { createRequire: createRequire3 } = await import('module');
+  if (!existsSync16(cssFilePath)) return null;
+  const raw = readFileSync14(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
 var CI_EXIT = {
@@ -923,6 +989,157 @@ function createCiCommand() {
     }
   );
 }
+function collectSourceFiles(dir) {
+  if (!existsSync(dir)) return [];
+  const results = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory() && entry.name !== "node_modules" && entry.name !== ".reactscope") {
+      results.push(...collectSourceFiles(full));
+    } else if (entry.isFile() && /\.(tsx?|jsx?)$/.test(entry.name)) {
+      results.push(full);
+    }
+  }
+  return results;
+}
+function checkConfig(cwd) {
+  const configPath = resolve(cwd, "reactscope.config.json");
+  if (!existsSync(configPath)) {
+    return {
+      name: "config",
+      status: "error",
+      message: "reactscope.config.json not found \u2014 run `scope init`"
+    };
+  }
+  try {
+    JSON.parse(readFileSync(configPath, "utf-8"));
+    return { name: "config", status: "ok", message: "reactscope.config.json valid" };
+  } catch {
+    return { name: "config", status: "error", message: "reactscope.config.json is not valid JSON" };
+  }
+}
+function checkTokens(cwd) {
+  const configPath = resolve(cwd, "reactscope.config.json");
+  let tokensPath = resolve(cwd, "reactscope.tokens.json");
+  if (existsSync(configPath)) {
+    try {
+      const cfg = JSON.parse(readFileSync(configPath, "utf-8"));
+      if (cfg.tokens?.file) tokensPath = resolve(cwd, cfg.tokens.file);
+    } catch {
+    }
+  }
+  if (!existsSync(tokensPath)) {
+    return {
+      name: "tokens",
+      status: "warn",
+      message: `Token file not found at ${tokensPath} \u2014 run \`scope init\``
+    };
+  }
+  try {
+    const raw = JSON.parse(readFileSync(tokensPath, "utf-8"));
+    if (!raw.version) {
+      return { name: "tokens", status: "warn", message: "Token file is missing a `version` field" };
+    }
+    return { name: "tokens", status: "ok", message: "Token file valid" };
+  } catch {
+    return { name: "tokens", status: "error", message: "Token file is not valid JSON" };
+  }
+}
+function checkGlobalCss(cwd) {
+  const configPath = resolve(cwd, "reactscope.config.json");
+  let globalCss = [];
+  if (existsSync(configPath)) {
+    try {
+      const cfg = JSON.parse(readFileSync(configPath, "utf-8"));
+      globalCss = cfg.components?.wrappers?.globalCSS ?? [];
+    } catch {
+    }
+  }
+  if (globalCss.length === 0) {
+    return {
+      name: "globalCSS",
+      status: "warn",
+      message: "No globalCSS configured \u2014 Tailwind styles won't apply to renders. Add `components.wrappers.globalCSS` to reactscope.config.json"
+    };
+  }
+  const missing = globalCss.filter((f) => !existsSync(resolve(cwd, f)));
+  if (missing.length > 0) {
+    return {
+      name: "globalCSS",
+      status: "error",
+      message: `globalCSS file(s) not found: ${missing.join(", ")}`
+    };
+  }
+  return {
+    name: "globalCSS",
+    status: "ok",
+    message: `${globalCss.length} globalCSS file(s) present`
+  };
+}
+function checkManifest(cwd) {
+  const manifestPath = resolve(cwd, ".reactscope", "manifest.json");
+  if (!existsSync(manifestPath)) {
+    return {
+      name: "manifest",
+      status: "warn",
+      message: "Manifest not found \u2014 run `scope manifest generate`"
+    };
+  }
+  const manifestMtime = statSync(manifestPath).mtimeMs;
+  const sourceDir = resolve(cwd, "src");
+  const sourceFiles = collectSourceFiles(sourceDir);
+  const stale = sourceFiles.filter((f) => statSync(f).mtimeMs > manifestMtime);
+  if (stale.length > 0) {
+    return {
+      name: "manifest",
+      status: "warn",
+      message: `Manifest may be stale \u2014 ${stale.length} source file(s) modified since last generate. Run \`scope manifest generate\``
+    };
+  }
+  return { name: "manifest", status: "ok", message: "Manifest present and up to date" };
+}
+var ICONS = { ok: "\u2713", warn: "!", error: "\u2717" };
+function formatCheck(check) {
+  return `  [${ICONS[check.status]}] ${check.name.padEnd(12)} ${check.message}`;
+}
+function createDoctorCommand() {
+  return new Command("doctor").description("Check the health of your Scope setup (config, tokens, CSS, manifest)").option("--json", "Emit structured JSON output", false).action((opts) => {
+    const cwd = process.cwd();
+    const checks = [
+      checkConfig(cwd),
+      checkTokens(cwd),
+      checkGlobalCss(cwd),
+      checkManifest(cwd)
+    ];
+    const errors = checks.filter((c) => c.status === "error").length;
+    const warnings = checks.filter((c) => c.status === "warn").length;
+    if (opts.json) {
+      process.stdout.write(
+        `${JSON.stringify({ passed: checks.length - errors - warnings, warnings, errors, checks }, null, 2)}
+`
+      );
+      if (errors > 0) process.exit(1);
+      return;
+    }
+    process.stdout.write("\nScope Doctor\n");
+    process.stdout.write("\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n");
+    for (const check of checks) process.stdout.write(`${formatCheck(check)}
+`);
+    process.stdout.write("\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n");
+    if (errors > 0) {
+      process.stdout.write(`  ${errors} error(s), ${warnings} warning(s)
+
+`);
+      process.exit(1);
+    } else if (warnings > 0) {
+      process.stdout.write(`  ${warnings} warning(s) \u2014 everything works but could be better
+
+`);
+    } else {
+      process.stdout.write("  All checks passed!\n\n");
+    }
+  });
+}
 function hasConfigFile(dir, stem) {
   if (!existsSync(dir)) return false;
   try {
@@ -1004,6 +1221,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"];
@@ -1071,13 +1302,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) {
@@ -1086,7 +1319,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 } },
@@ -1117,9 +1350,9 @@ function createRL() {
   });
 }
 async function ask(rl, question) {
-  return new Promise((resolve18) => {
+  return new Promise((resolve19) => {
     rl.question(question, (answer) => {
-      resolve18(answer.trim());
+      resolve19(answer.trim());
     });
   });
 }
@@ -1144,18 +1377,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)}
 `);
@@ -1233,7 +1566,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);
@@ -1244,7 +1583,28 @@ async function runInit(options) {
     process.stdout.write(`     ${p}
 `);
   }
-  process.stdout.write("\n   Next steps: run `scope manifest` to scan your components.\n\n");
+  process.stdout.write("\n   Scanning components...\n");
+  try {
+    const manifestConfig = {
+      include: config.components.include,
+      rootDir
+    };
+    const manifest = await generateManifest(manifestConfig);
+    const manifestCount = Object.keys(manifest.components).length;
+    const manifestOutPath = join(rootDir, config.output.dir, "manifest.json");
+    mkdirSync(join(rootDir, config.output.dir), { recursive: true });
+    writeFileSync(manifestOutPath, `${JSON.stringify(manifest, null, 2)}
+`);
+    process.stdout.write(
+      `   Found ${manifestCount} component(s) \u2014 manifest written to ${manifestOutPath}
+`
+    );
+  } catch {
+    process.stdout.write(
+      "   (manifest generate skipped \u2014 run `scope manifest generate` manually)\n"
+    );
+  }
+  process.stdout.write("\n");
   return {
     success: true,
     message: "Project initialised successfully.",
@@ -1333,7 +1693,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);
@@ -1344,9 +1707,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);
         }
@@ -1373,6 +1738,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,
@@ -3057,6 +3443,17 @@ ${msg}`);
 }
 
 // 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;
@@ -3077,7 +3474,7 @@ async function shutdownPool3() {
     _pool3 = null;
   }
 }
-function buildRenderer(filePath, componentName, viewportWidth, viewportHeight, wrapperScript) {
+function buildRenderer(filePath, componentName, viewportWidth, viewportHeight, globalCssFiles = [], projectCwd = process.cwd(), wrapperScript) {
   const satori = new SatoriRenderer({
     defaultViewport: { width: viewportWidth, height: viewportHeight }
   });
@@ -3086,13 +3483,13 @@ function buildRenderer(filePath, componentName, viewportWidth, viewportHeight, w
     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,
-        void 0,
-        // projectCss (handled separately)
+        projectCss ?? void 0,
         wrapperScript
       );
       const slot = await pool.acquire();
@@ -3121,10 +3518,10 @@ function buildRenderer(filePath, componentName, viewportWidth, viewportHeight, w
             }
           });
           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]");
@@ -3134,49 +3531,147 @@ function buildRenderer(filePath, componentName, viewportWidth, viewportHeight, w
             `Component "${componentName}" rendered with zero bounding box \u2014 it may be invisible or not mounted`
           );
         }
-        const PAD = 24;
-        const MIN_W = 320;
-        const MIN_H = 200;
+        const PAD = 8;
         const clipX = Math.max(0, boundingBox.x - PAD);
         const clipY = Math.max(0, boundingBox.y - PAD);
         const rawW = boundingBox.width + PAD * 2;
         const rawH = boundingBox.height + PAD * 2;
-        const clipW = Math.max(rawW, MIN_W);
-        const clipH = Math.max(rawH, MIN_H);
-        const safeW = Math.min(clipW, viewportWidth - clipX);
-        const safeH = Math.min(clipH, viewportHeight - clipY);
+        const safeW = Math.min(rawW, viewportWidth - clipX);
+        const safeH = Math.min(rawH, viewportHeight - clipY);
         const screenshot = await page.screenshot({
           clip: { x: clipX, y: clipY, width: safeW, height: safeH },
           type: "png"
         });
+        const STYLE_PROPS = [
+          "display",
+          "width",
+          "height",
+          "color",
+          "backgroundColor",
+          "fontSize",
+          "fontFamily",
+          "fontWeight",
+          "lineHeight",
+          "padding",
+          "paddingTop",
+          "paddingRight",
+          "paddingBottom",
+          "paddingLeft",
+          "margin",
+          "marginTop",
+          "marginRight",
+          "marginBottom",
+          "marginLeft",
+          "gap",
+          "borderRadius",
+          "borderWidth",
+          "borderColor",
+          "borderStyle",
+          "boxShadow",
+          "opacity",
+          "position",
+          "flexDirection",
+          "alignItems",
+          "justifyContent",
+          "overflow"
+        ];
+        const _domResult = await page.evaluate(
+          (args) => {
+            let count = 0;
+            const styles = {};
+            function captureStyles(el, id, propList) {
+              const computed = window.getComputedStyle(el);
+              const out = {};
+              for (const prop of propList) {
+                const val = computed[prop] ?? "";
+                if (val && val !== "none" && val !== "normal" && val !== "auto") out[prop] = val;
+              }
+              styles[id] = out;
+            }
+            function walk(node) {
+              if (node.nodeType === Node.TEXT_NODE) {
+                return {
+                  tag: "#text",
+                  attrs: {},
+                  text: node.textContent?.trim() ?? "",
+                  children: []
+                };
+              }
+              const el = node;
+              const id = count++;
+              captureStyles(el, id, args.props);
+              const attrs = {};
+              for (const attr of Array.from(el.attributes)) {
+                attrs[attr.name] = attr.value;
+              }
+              const children = Array.from(el.childNodes).filter(
+                (n) => n.nodeType === Node.ELEMENT_NODE || n.nodeType === Node.TEXT_NODE && (n.textContent?.trim() ?? "").length > 0
+              ).map(walk);
+              return { tag: el.tagName.toLowerCase(), attrs, nodeId: id, children };
+            }
+            const root = document.querySelector(args.sel);
+            if (!root)
+              return {
+                tree: { tag: "div", attrs: {}, children: [] },
+                elementCount: 0,
+                nodeStyles: {}
+              };
+            return { tree: walk(root), elementCount: count, nodeStyles: styles };
+          },
+          { sel: "[data-reactscope-root] > *", props: STYLE_PROPS }
+        );
+        const domTree = _domResult?.tree ?? { tag: "div", attrs: {}, children: [] };
+        const elementCount = _domResult?.elementCount ?? 0;
+        const nodeStyles = _domResult?.nodeStyles ?? {};
         const computedStyles = {};
-        const styles = await page.evaluate((sel) => {
-          const el = document.querySelector(sel);
-          if (el === null) return {};
-          const computed = window.getComputedStyle(el);
-          const out = {};
-          for (const prop of [
-            "display",
-            "width",
-            "height",
-            "color",
-            "backgroundColor",
-            "fontSize",
-            "fontFamily",
-            "padding",
-            "margin"
-          ]) {
-            out[prop] = computed.getPropertyValue(prop);
+        if (nodeStyles[0]) computedStyles["[data-reactscope-root] > *"] = nodeStyles[0];
+        for (const [nodeId, styles] of Object.entries(nodeStyles)) {
+          computedStyles[`#node-${nodeId}`] = styles;
+        }
+        const dom = {
+          tree: domTree,
+          elementCount,
+          boundingBox: {
+            x: boundingBox.x,
+            y: boundingBox.y,
+            width: boundingBox.width,
+            height: boundingBox.height
           }
-          return out;
-        }, "[data-reactscope-root] > *");
-        computedStyles["[data-reactscope-root] > *"] = styles;
+        };
+        const a11yInfo = await page.evaluate((sel) => {
+          const wrapper = document.querySelector(sel);
+          const el = wrapper?.firstElementChild ?? wrapper;
+          if (!el) return { role: "generic", name: "" };
+          return {
+            role: el.getAttribute("role") ?? el.tagName.toLowerCase() ?? "generic",
+            name: el.getAttribute("aria-label") ?? el.getAttribute("aria-labelledby") ?? el.textContent?.trim().slice(0, 100) ?? ""
+          };
+        }, "[data-reactscope-root]") ?? {
+          role: "generic",
+          name: ""
+        };
+        const imgViolations = await page.evaluate((sel) => {
+          const container = document.querySelector(sel);
+          if (!container) return [];
+          const issues = [];
+          container.querySelectorAll("img").forEach((img) => {
+            if (!img.alt) issues.push("Image missing accessible name");
+          });
+          return issues;
+        }, "[data-reactscope-root]") ?? [];
+        const accessibility = {
+          role: a11yInfo.role,
+          name: a11yInfo.name,
+          violations: imgViolations
+        };
         return {
           screenshot,
           width: Math.round(safeW),
           height: Math.round(safeH),
           renderTimeMs,
-          computedStyles
+          computedStyles,
+          dom,
+          accessibility
         };
       } finally {
         pool.release(slot);
@@ -3226,26 +3721,64 @@ function registerRenderSingle(renderCmd) {
 Available: ${available}`
           );
         }
+        let props = {};
+        if (opts.props !== void 0) {
+          try {
+            props = JSON.parse(opts.props);
+          } catch {
+            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 scopeData = await loadScopeFileForComponent(filePath);
         const wrapperScript = scopeData?.hasWrapper === true ? await buildWrapperScript(scopeData.filePath) : void 0;
         const scenarios = buildScenarioMap(opts, scopeData);
-        const renderer = buildRenderer(filePath, componentName, width, height, wrapperScript);
+        const globalCssFiles = loadGlobalCssFilesFromConfig(rootDir);
+        if (globalCssFiles.length === 0) {
+          process.stderr.write(
+            "warning: No globalCSS files configured. Tailwind/CSS styles will not be applied to renders.\n  Add `components.wrappers.globalCSS` to reactscope.config.json\n"
+          );
+        }
+        const renderer = buildRenderer(
+          filePath,
+          componentName,
+          width,
+          height,
+          globalCssFiles,
+          rootDir,
+          wrapperScript
+        );
         process.stderr.write(
           `Rendering ${componentName} [${descriptor.complexityClass}] at ${width}\xD7${height}\u2026
 `
         );
         const fmt2 = resolveSingleFormat(opts.format);
         let anyFailed = false;
-        for (const [scenarioName, props] of Object.entries(scenarios)) {
+        for (const [scenarioName, props2] of Object.entries(scenarios)) {
           const isNamed = scenarioName !== "__default__";
           const label = isNamed ? `${componentName}:${scenarioName}` : componentName;
           const outcome = await safeRender(
-            () => renderer.renderCell(props, descriptor.complexityClass),
+            () => renderer.renderCell(props2, descriptor.complexityClass),
             {
-              props,
+              props: props2,
               sourceLocation: {
                 file: descriptor.filePath,
                 line: descriptor.loc.start,
@@ -3274,7 +3807,7 @@ Available: ${available}`
 `
             );
           } else if (fmt2 === "json") {
-            const json = formatRenderJson(label, props, result);
+            const json = formatRenderJson(label, props2, result);
             process.stdout.write(`${JSON.stringify(json, null, 2)}
 `);
           } else {
@@ -3301,7 +3834,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(
@@ -3320,21 +3856,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}`);
+            }
+            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) });
             }
-            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}"`);
+          } 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) {
@@ -3448,16 +4010,31 @@ function registerRenderAll(renderCmd) {
         process.stderr.write(`Rendering ${total} components (concurrency: ${concurrency})\u2026
 `);
         const results = [];
+        const complianceStylesMap = {};
         let completed = 0;
         const renderOne = async (name) => {
           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 scopeData = await loadScopeFileForComponent(filePath);
+          const scenarioEntries = scopeData !== null ? Object.entries(scopeData.scenarios) : [];
+          const defaultEntry = scenarioEntries.find(([k]) => k === "default") ?? scenarioEntries[0];
+          const renderProps = defaultEntry !== void 0 ? defaultEntry[1] : {};
+          const wrapperScript = scopeData?.hasWrapper === true ? await buildWrapperScript(scopeData.filePath) : void 0;
+          const renderer = buildRenderer(
+            filePath,
+            name,
+            375,
+            812,
+            allCssFiles,
+            process.cwd(),
+            wrapperScript
+          );
           const outcome = await safeRender(
-            () => renderer.renderCell({}, descriptor.complexityClass),
+            () => renderer.renderCell(renderProps, descriptor.complexityClass),
             {
-              props: {},
+              props: renderProps,
               sourceLocation: {
                 file: descriptor.filePath,
                 line: descriptor.loc.start,
@@ -3497,6 +4074,77 @@ function registerRenderAll(renderCmd) {
           writeFileSync(pngPath, result.screenshot);
           const jsonPath = resolve(outputDir, `${name}.json`);
           writeFileSync(jsonPath, JSON.stringify(formatRenderJson(name, {}, result), null, 2));
+          const rawStyles = result.computedStyles["[data-reactscope-root] > *"] ?? {};
+          const compStyles = {
+            colors: {},
+            spacing: {},
+            typography: {},
+            borders: {},
+            shadows: {}
+          };
+          for (const [prop, val] of Object.entries(rawStyles)) {
+            if (!val || val === "none" || val === "") continue;
+            const lower = prop.toLowerCase();
+            if (lower.includes("color") || lower.includes("background")) {
+              compStyles.colors[prop] = val;
+            } else if (lower.includes("padding") || lower.includes("margin") || lower.includes("gap") || lower.includes("width") || lower.includes("height")) {
+              compStyles.spacing[prop] = val;
+            } else if (lower.includes("font") || lower.includes("lineheight") || lower.includes("letterspacing") || lower.includes("texttransform")) {
+              compStyles.typography[prop] = val;
+            } else if (lower.includes("border") || lower.includes("radius") || lower.includes("outline")) {
+              compStyles.borders[prop] = val;
+            } else if (lower.includes("shadow")) {
+              compStyles.shadows[prop] = val;
+            }
+          }
+          complianceStylesMap[name] = compStyles;
+          if (scopeData !== null && Object.keys(scopeData.scenarios).length >= 2) {
+            try {
+              const scenarioEntries2 = Object.entries(scopeData.scenarios);
+              const scenarioAxis = {
+                name: "scenario",
+                values: scenarioEntries2.map(([k]) => k)
+              };
+              const scenarioPropsMap = Object.fromEntries(scenarioEntries2);
+              const matrixRenderer = buildRenderer(
+                filePath,
+                name,
+                375,
+                812,
+                allCssFiles,
+                process.cwd(),
+                wrapperScript
+              );
+              const wrappedRenderer = {
+                _satori: matrixRenderer._satori,
+                async renderCell(props, cc) {
+                  const scenarioName = props.scenario;
+                  const realProps = scenarioName !== void 0 ? scenarioPropsMap[scenarioName] ?? props : props;
+                  return matrixRenderer.renderCell(realProps, cc ?? "simple");
+                }
+              };
+              const matrix = new RenderMatrix(wrappedRenderer, [scenarioAxis], {
+                concurrency: 2
+              });
+              const matrixResult = await matrix.render();
+              const matrixCells = matrixResult.cells.map((cell) => ({
+                axisValues: [scenarioEntries2[cell.axisIndices[0] ?? 0]?.[0] ?? ""],
+                screenshot: cell.result.screenshot.toString("base64"),
+                width: cell.result.width,
+                height: cell.result.height,
+                renderTimeMs: cell.result.renderTimeMs
+              }));
+              const existingJson = JSON.parse(readFileSync(jsonPath, "utf-8"));
+              existingJson.cells = matrixCells;
+              existingJson.axisLabels = [scenarioAxis.values];
+              writeFileSync(jsonPath, JSON.stringify(existingJson, null, 2));
+            } catch (matrixErr) {
+              process.stderr.write(
+                `  [warn] Matrix render for ${name} failed: ${matrixErr instanceof Error ? matrixErr.message : String(matrixErr)}
+`
+              );
+            }
+          }
           if (isTTY()) {
             process.stdout.write(
               `\u2713 ${name} \u2192 ${opts.outputDir}/${name}.png (${result.width}\xD7${result.height}, ${result.renderTimeMs.toFixed(0)}ms)
@@ -3520,6 +4168,14 @@ function registerRenderAll(renderCmd) {
         }
         await Promise.all(workers);
         await shutdownPool3();
+        const compStylesPath = resolve(
+          resolve(process.cwd(), opts.outputDir),
+          "..",
+          "compliance-styles.json"
+        );
+        writeFileSync(compStylesPath, JSON.stringify(complianceStylesMap, null, 2));
+        process.stderr.write(`[scope/render] \u2713 Wrote compliance-styles.json
+`);
         process.stderr.write("\n");
         const summary = formatSummaryText(results, outputDir);
         process.stderr.write(`${summary}
@@ -3719,12 +4375,12 @@ async function runBaseline(options = {}) {
   mkdirSync(rendersDir, { recursive: true });
   let manifest;
   if (manifestPath !== void 0) {
-    const { readFileSync: readFileSync12 } = await import('fs');
+    const { readFileSync: readFileSync14 } = 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(readFileSync14(absPath, "utf-8"));
     process.stderr.write(`Loaded manifest from ${manifestPath}
 `);
   } else {
@@ -5085,10 +5741,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);
       }
@@ -5902,6 +6568,7 @@ function createProgram(options = {}) {
   program.addCommand(createInstrumentCommand());
   program.addCommand(createInitCommand());
   program.addCommand(createCiCommand());
+  program.addCommand(createDoctorCommand());
   const existingReportCmd = program.commands.find((c) => c.name() === "report");
   if (existingReportCmd !== void 0) {
     registerBaselineSubCommand(existingReportCmd);
@@ -5912,6 +6579,6 @@ function createProgram(options = {}) {
   return program;
 }
 
-export { CI_EXIT, createCiCommand, createInitCommand, createInstrumentCommand, createManifestCommand, createProgram, createTokensCommand, createTokensExportCommand, formatCiReport, isTTY, matchGlob, resolveTokenFilePath2 as resolveTokenFilePath, runCi, runInit };
+export { CI_EXIT, createCiCommand, createDoctorCommand, createInitCommand, createInstrumentCommand, createManifestCommand, createProgram, createTokensCommand, createTokensExportCommand, formatCiReport, isTTY, matchGlob, resolveTokenFilePath2 as resolveTokenFilePath, runCi, runInit };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map