@astryxdesign/cli 0.0.0-bootstrap.0 → 0.1.0-canary.08d4cf4

package/src/commands/build-theme.mjs

@@ -0,0 +1,874 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file theme build command — Compile a defineTheme file to CSS
+ *
+ * Takes a theme file that uses defineTheme() and outputs:
+ * - A CSS file with token overrides and component styles
+ * - An updated JS module that references the built className
+ *
+ * Usage:
+ *   npx astryx theme build ./src/themes/ocean.ts
+ *   npx astryx theme build ./src/themes/ocean.ts --out ./dist/ocean.css
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {pathToFileURL, fileURLToPath} from 'node:url';
+import {createJiti} from 'jiti';
+import {getRunPrefix} from '../utils/package-manager.mjs';
+import {sanitizeName, PathSafetyError} from '../utils/path-safety.mjs';
+import {jsonOut, humanLog} from '../lib/json.mjs';
+import {cliError} from '../lib/cli-error.mjs';
+import {ERROR_CODES} from '../lib/error-codes.mjs';
+
+// Import shared theme processing from core. `astryx theme build` MUST produce the
+// exact same CSS as the `<Theme>` runtime, so it has exactly one generation
+// path: core's generator. There is no in-CLI fallback implementation — if this
+// import fails, the build fails (see the ERR_CORE_NOT_FOUND guard in the theme
+// action). A built, resolvable `@astryxdesign/core` is a hard requirement.
+let _defineTheme = null;
+let _generateThemeRulesSplit = null;
+let _generateOnMediaCSS = null;
+let _coreImportError = null;
+try {
+  const coreTheme = await import('@astryxdesign/core/theme');
+  _defineTheme = coreTheme.defineTheme;
+  _generateThemeRulesSplit = coreTheme.generateThemeRulesSplit;
+  _generateOnMediaCSS = coreTheme.generateOnMediaCSS;
+} catch (e) {
+  // Capture the reason so the theme action can surface a precise, actionable
+  // error. We don't throw here: this module is imported eagerly by the CLI
+  // entrypoint for every command, and a throw at load time would break
+  // unrelated commands (the entry wraps loads in try/catch and degrades the
+  // command to a stub). The hard failure happens when `theme build` runs.
+  _coreImportError = e;
+}
+
+/**
+ * Build a @generated attribution header for generated files.
+ * @param {string} sourceFile - Relative path to the source theme file
+ * @param {'css'|'js'|'ts'} lang - File language (determines comment syntax)
+ * @param {string} [command] - The full CLI command used to generate this file
+ */
+function generatedHeader(sourceFile, lang = 'js', command) {
+  const timestamp = new Date().toISOString();
+  const body = [
+    `@generated by \`astryx theme build\` — do not edit manually.`,
+    `Source: ${sourceFile}`,
+  ];
+  if (command) {
+    body.push(`Command: ${command}`);
+  }
+  body.push(`Generated: ${timestamp}`);
+  if (lang === 'css') {
+    return `/*\n * ${body.join('\n * ')}\n */\n\n`;
+  }
+  return `/**\n * ${body.join('\n * ')}\n */\n\n`;
+}
+
+/**
+ * Convert a theme name to a valid JS identifier.
+ * e.g. 'default-minimal' → 'defaultMinimal', 'ocean' → 'ocean'
+ */
+function toIdentifier(name) {
+  return name.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+}
+
+/**
+ * Convert a kebab-case component name to PascalCase.
+ * e.g. 'button' → 'Button', 'progress-bar' → 'ProgressBar', 'avatar-status-dot' → 'AvatarStatusDot'
+ */
+function toPascalCase(name) {
+  return name
+    .split('-')
+    .map(part => part.charAt(0).toUpperCase() + part.slice(1))
+    .join('');
+}
+
+/**
+ * Load known built-in values for a component's visual props from its .doc.mjs file.
+ * Parses the type string (e.g. "'info' | 'warning' | 'error' | 'success'") to extract values.
+ * Returns a map of { propName: string[] } for props that are visual (listed in theming targets).
+ */
+async function loadKnownValues(componentName) {
+  // Resolve core src relative to the CLI package, not cwd (which may be a theme package)
+  const cliDir = path.dirname(fileURLToPath(import.meta.url));
+  const coreSrc = path.resolve(cliDir, '../../../core/src');
+  if (!fs.existsSync(coreSrc)) return {};
+  // Map component name to directory (e.g. 'banner' → 'Banner', 'dropdownmenu' → 'DropdownMenu')
+  const dirs = fs.readdirSync(coreSrc, { withFileTypes: true })
+    .filter(d => d.isDirectory())
+    .map(d => d.name);
+  const dir = dirs.find(d => d.toLowerCase() === componentName.toLowerCase()
+    || d.toLowerCase().replace(/[^a-z]/g, '') === componentName.toLowerCase());
+  if (!dir) return {};
+
+  const docPath = path.join(coreSrc, dir, `${dir}.doc.mjs`);
+  if (!fs.existsSync(docPath)) return {};
+
+  try {
+    const docModule = await import(pathToFileURL(docPath).href);
+    const doc = docModule.docs;
+    if (!doc?.theming?.targets) return {};
+
+    // Collect all props — from doc.props or doc.components[].props
+    const allProps = [];
+    if (doc.props) allProps.push(...doc.props);
+    if (doc.components) {
+      for (const comp of doc.components) {
+        if (comp.props) allProps.push(...comp.props);
+      }
+    }
+    if (allProps.length === 0) return {};
+
+    // Collect visual prop names from theming targets
+    const visualProps = new Set();
+    for (const target of doc.theming.targets) {
+      if (target.visualProps) {
+        for (const vp of target.visualProps) visualProps.add(vp);
+      }
+    }
+
+    // Extract values from prop type strings
+    const result = {};
+    for (const prop of allProps) {
+      if (!visualProps.has(prop.name)) continue;
+      if (!prop.type || typeof prop.type !== 'string') continue;
+
+      // Parse union type: "'info' | 'warning' | 'error' | 'success'" → ['info', 'warning', 'error', 'success']
+      const matches = prop.type.match(/'([^']+)'/g);
+      if (matches) {
+        result[prop.name] = matches.map(m => m.replace(/'/g, ''));
+      }
+    }
+    return result;
+  } catch {
+    return {};
+  }
+}
+
+// Cache for loaded known values
+const _knownValuesCache = new Map();
+async function getKnownValues(componentName) {
+  if (!_knownValuesCache.has(componentName)) {
+    _knownValuesCache.set(componentName, await loadKnownValues(componentName));
+  }
+  return _knownValuesCache.get(componentName);
+}
+
+/**
+ * Generate TypeScript declaration content with module augmentation for custom
+ * component prop values found in the theme's `components` keys. Reads known
+ * values from doc files to filter out base prop values.
+ *
+ * Interface naming convention: Astryx + PascalCase(component) + PascalCase(prop) + Map
+ *   banner + status → XDSBannerStatusMap
+ *   button + variant → XDSButtonVariantMap
+ *
+ * @param {object} themeDef - Theme definition (resolved by defineTheme)
+ * @returns {Promise<string|null>} TypeScript declaration content, or null if no augmentations needed
+ */
+async function generateVariantDeclarationsAsync(themeDef) {
+  if (!themeDef.components || Object.keys(themeDef.components).length === 0) {
+    return null;
+  }
+
+  // Collect custom values: { component: { prop: [value, ...] } }
+  const customValues = {};
+
+  for (const [component, rules] of Object.entries(themeDef.components)) {
+    const knownForComponent = await getKnownValues(component);
+
+    for (const key of Object.keys(rules)) {
+      if (key === 'base') continue;
+
+      const pairs = key.split('+');
+      for (const pair of pairs) {
+        const colonIdx = pair.indexOf(':');
+        if (colonIdx === -1) continue;
+        const prop = pair.slice(0, colonIdx);
+        const value = pair.slice(colonIdx + 1);
+
+        // Skip known built-in values
+        const knownForProp = knownForComponent[prop];
+        if (knownForProp && knownForProp.includes(value)) continue;
+
+        if (!customValues[component]) customValues[component] = {};
+        if (!customValues[component][prop]) customValues[component][prop] = new Set();
+        customValues[component][prop].add(value);
+      }
+    }
+  }
+
+  // Check if we found any custom values
+  const hasCustom = Object.values(customValues).some(
+    props => Object.values(props).some(values => values.size > 0)
+  );
+  if (!hasCustom) return null;
+
+  const sections = ['// Generated by astryx theme build', 'export {};', ''];
+
+  for (const [component, props] of Object.entries(customValues)) {
+    for (const [prop, values] of Object.entries(props)) {
+      if (values.size === 0) continue;
+
+      const pascal = toPascalCase(component);
+      const propPascal = prop.charAt(0).toUpperCase() + prop.slice(1);
+      const modulePath = `@astryxdesign/core/${pascal}`;
+      const interfaceName = `XDS${pascal}${propPascal}Map`;
+
+      sections.push(`declare module '${modulePath}' {`);
+      sections.push(`  interface ${interfaceName} {`);
+      for (const v of values) {
+        sections.push(`    '${v}': true;`);
+      }
+      sections.push('  }');
+      sections.push('}');
+      sections.push('');
+    }
+  }
+
+  return sections.join('\n');
+}
+
+/**
+ * Resolve a token value — [light, dark] tuple becomes light-dark()
+ */
+function resolveTokenValue(value) {
+  if (Array.isArray(value)) {
+    return `light-dark(${value[0]}, ${value[1]})`;
+  }
+  return value;
+}
+
+// Theme @scope selector helpers. Keep the `astryx` literal in sync with
+// packages/core/src/naming.ts (NAMESPACE) and generateThemeRules.ts.
+// Theme scopes to data-astryx-theme; the static build path must match.
+const themeScopeStart = name => `[data-astryx-theme="${name}"]`;
+const THEME_SCOPE_TO = `[data-astryx-theme]`;
+
+/**
+ * Import a theme module using jiti and find the defineTheme() result.
+ * Returns the resolved DefinedTheme object.
+ */
+async function importThemeModule(filePath) {
+  const jiti = createJiti(import.meta.url, {
+    moduleCache: false,
+    jsx: true,
+  });
+
+  const mod = await jiti.import(filePath, {default: true});
+
+  if (isThemeObject(mod)) return mod;
+
+  if (mod && typeof mod === 'object') {
+    for (const value of Object.values(mod)) {
+      if (isThemeObject(value)) return value;
+    }
+  }
+
+  throw new Error(
+    `Could not find a defineTheme() result in ${filePath}.\n` +
+    `Expected an export like: export const myTheme = defineTheme({ name: '...', tokens: {...} })`,
+  );
+}
+
+function isThemeObject(value) {
+  return (
+    value &&
+    typeof value === 'object' &&
+    typeof value.name === 'string' &&
+    value.tokens &&
+    typeof value.tokens === 'object'
+  );
+}
+
+/**
+ * Extract the theme definition from a JS/TS file.
+ * Tries jiti first (full TS support), falls back to regex+eval.
+ */
+async function extractThemeDefinition(filePath) {
+  try {
+    return await importThemeModule(filePath);
+  } catch (jitiError) {
+    try {
+      return extractThemeDefinitionLegacy(filePath);
+    } catch {
+      throw new Error(
+        `Failed to load theme from ${filePath}: ${jitiError.message}\n` +
+        `Make sure all imports in the theme file are resolvable.`,
+      );
+    }
+  }
+}
+
+/**
+ * Fallback extraction via regex + eval.
+ * Only works for plain object literals — can't follow imports or variables.
+ */
+function extractThemeDefinitionLegacy(filePath) {
+  const content = fs.readFileSync(filePath, 'utf8');
+
+  const defineMatch = content.match(/defineTheme\s*\(\s*({[\s\S]*?})\s*\)/);
+  if (!defineMatch) {
+    const defaultMatch = content.match(/export\s+default\s+({[\s\S]*?});/);
+    if (!defaultMatch) {
+      throw new Error(
+        `Could not find defineTheme() call or default export in ${filePath}.\n` +
+        `Expected: defineTheme({ name: '...', tokens: {...} })`,
+      );
+    }
+     
+    return eval(`(${defaultMatch[1]})`);
+  }
+
+  let objStr = defineMatch[1];
+  objStr = objStr.replace(/\s+as\s+const/g, '');
+  objStr = objStr.replace(/icons:\s*[a-zA-Z_][a-zA-Z0-9_]*/g, 'icons: undefined');
+
+  try {
+     
+    return eval(`(${objStr})`);
+  } catch (e) {
+    throw new Error(
+      `Failed to parse theme definition in ${filePath}: ${e.message}\n` +
+      `Make sure the defineTheme() argument is a plain object literal.`,
+      {cause: e},
+    );
+  }
+}
+
+/**
+ * Extract icon import info from a theme source file.
+ * Returns { importPath, exportName } or null if no icons.
+ *
+ * Looks for patterns like:
+ *   import { defaultIconRegistry } from './icons';
+ *   icons: defaultIconRegistry,
+ */
+function extractIconInfo(filePath) {
+  const content = fs.readFileSync(filePath, 'utf8');
+
+  // Find the icons field in defineTheme
+  const iconsMatch = content.match(/icons:\s*([a-zA-Z_][a-zA-Z0-9_]*)/);
+  if (!iconsMatch) return null;
+
+  const varName = iconsMatch[1];
+
+  // Find the import for that variable
+  const importRegex = new RegExp(
+    `import\\s*{[^}]*\\b${varName}\\b[^}]*}\\s*from\\s*['"]([^'"]+)['"]`,
+  );
+  const importMatch = content.match(importRegex);
+  if (!importMatch) return null;
+
+  return {
+    exportName: varName,
+    importPath: importMatch[1],
+  };
+}
+
+/**
+ * Generate a minimal JS module for a built theme.
+ * Includes the theme name, marker, and re-exports the icon registry.
+ * All styling is in the CSS file.
+ */
+function generateBuiltModule(themeDef, iconInfo) {
+  const iconImport = iconInfo
+    ? `import { ${iconInfo.exportName} } from '${iconInfo.importPath}';\n`
+    : '';
+  const iconsField = iconInfo ? `  icons: ${iconInfo.exportName},` : '';
+  const iconReExport = iconInfo
+    ? `\nexport { ${iconInfo.exportName} };\n`
+    : '';
+
+  // Resolve token values — tuples become light-dark() strings
+  const resolvedTokens = {};
+  if (themeDef.tokens) {
+    for (const [key, value] of Object.entries(themeDef.tokens)) {
+      resolvedTokens[key] = resolveTokenValue(value);
+    }
+  }
+
+  const tokensStr = JSON.stringify(resolvedTokens, null, 2)
+    .split('\n')
+    .map((line, i) => (i === 0 ? line : '  ' + line))
+    .join('\n');
+
+  return `${iconImport}/**
+ * ${themeDef.name} theme — built by \`${getRunPrefix()} astryx theme build\`
+ * Import the CSS file alongside this module:
+ *
+ *   import { ${toIdentifier(themeDef.name)}Theme } from './${themeDef.name}';
+ *   import './${themeDef.name}.css';
+ */
+export const ${toIdentifier(themeDef.name)}Theme = {
+  name: '${themeDef.name}',
+  __built: true,
+  tokens: ${tokensStr},
+${iconsField}
+};
+${iconReExport}`;
+}
+
+/**
+ * Generate TypeScript declarations for a built theme module.
+ */
+function generateBuiltTypes(themeDef, iconInfo) {
+  const iconType = iconInfo
+    ? `import type { IconRegistry } from '@astryxdesign/core/Icon';
+export declare const ${iconInfo.exportName}: IconRegistry;
+`
+    : '';
+  return `import type { DefinedTheme } from '@astryxdesign/core/theme';
+${iconType}export declare const ${toIdentifier(themeDef.name)}Theme: DefinedTheme;
+`;
+}
+
+// =============================================================================
+// Component validation
+// =============================================================================
+
+/**
+ * Known Astryx component names and their visual props.
+ * Used to warn on typos in defineTheme component overrides.
+ */
+const KNOWN_COMPONENTS = {
+  appshell: ['position'],
+  aspectratio: [],
+  avatar: ['size'],
+  badge: ['variant', 'color'],
+  banner: ['container', 'status'],
+  breadcrumbs: ['variant'],
+  button: ['variant', 'size'],
+  calendar: [],
+  card: [],
+  center: [],
+  checkboxinput: [],
+  collapsible: [],
+  dateinput: [],
+  dialog: ['variant', 'position'],
+  divider: ['variant', 'orientation'],
+  dropdownmenu: [],
+  'empty-state': [],
+  field: [],
+  formlayout: [],
+  grid: ['align'],
+  heading: ['level'],
+  icon: ['size', 'color'],
+  kbd: [],
+  layer: [],
+  layout: [],
+  link: ['color'],
+  list: ['type', 'density'],
+  mobilenav: [],
+  moremenu: [],
+  navicon: [],
+  numberinput: [],
+  pagination: ['variant'],
+  progressbar: ['variant', 'size'],
+  radiolist: ['orientation'],
+  section: ['variant'],
+  selector: ['type', 'size', 'color'],
+  sidenav: [],
+  skeleton: [],
+  slider: ['orientation'],
+  spinner: ['size'],
+  stack: [],
+  statusdot: ['variant', 'size'],
+  switch: [],
+  table: [],
+  tablist: ['type'],
+  text: ['type', 'color'],
+  textarea: [],
+  textinput: [],
+  timeinput: [],
+  token: ['color'],
+  tokenizer: [],
+  topnav: [],
+  typeahead: ['type', 'size', 'color'],
+};
+
+/**
+ * Validate component overrides in a theme definition.
+ * Warns on unknown component names and unknown prop names.
+ * Returns array of warning strings.
+ */
+function validateComponentOverrides(themeDef) {
+  const warnings = [];
+  if (!themeDef.components) return warnings;
+
+  for (const [component, rules] of Object.entries(themeDef.components)) {
+    // Check component name
+    if (!(component in KNOWN_COMPONENTS)) {
+      const similar = Object.keys(KNOWN_COMPONENTS)
+        .filter((k) => {
+          if (k.includes(component) || component.includes(k)) return true;
+          // Levenshtein distance 1-2 for short names
+          if (Math.abs(k.length - component.length) <= 2) {
+            let diff = 0;
+            const longer = k.length >= component.length ? k : component;
+            const shorter = k.length < component.length ? k : component;
+            let j = 0;
+            for (let i = 0; i < longer.length && diff <= 2; i++) {
+              if (longer[i] !== shorter[j]) diff++;
+              else j++;
+            }
+            diff += shorter.length - j;
+            return diff <= 2;
+          }
+          return false;
+        })
+        .slice(0, 3);
+      const hint = similar.length > 0 ? ` Did you mean: ${similar.join(', ')}?` : '';
+      warnings.push(`Unknown component "${component}".${hint}`);
+      continue;
+    }
+
+    // Check prop names in prop:value keys
+    const knownProps = KNOWN_COMPONENTS[component];
+    for (const key of Object.keys(rules)) {
+      if (key === 'base') continue;
+
+      // Parse prop:value pairs (e.g. 'variant:secondary' or 'variant:destructive+size:sm')
+      const pairs = key.split('+');
+      for (const pair of pairs) {
+        const [prop] = pair.split(':');
+        if (prop && !knownProps.includes(prop)) {
+          const hint =
+            knownProps.length > 0
+              ? ` Known props: ${knownProps.join(', ')}`
+              : ' This component has no variant props.';
+          warnings.push(
+            `Unknown prop "${prop}" on component "${component}".${hint}`,
+          );
+        }
+      }
+    }
+  }
+
+  return warnings;
+}
+
+/**
+ * Validate that themes don't set private (--_*) CSS custom properties directly.
+ * Private vars are internal implementation details managed by the derived var
+ * expansion pipeline. Theme authors should write standard CSS properties
+ * (e.g. borderRadius, padding) instead.
+ *
+ * Returns array of error strings.
+ */
+function validatePrivateVars(themeDef) {
+  const errors = [];
+  if (!themeDef.components) return errors;
+
+  for (const [component, rules] of Object.entries(themeDef.components)) {
+    for (const [key, styles] of Object.entries(rules)) {
+      for (const prop of Object.keys(styles)) {
+        if (typeof prop === 'string' && prop.startsWith('--_')) {
+          errors.push(
+            `Component "${component}" (${key}) sets private var "${prop}". ` +
+            `Private vars (--_*) are internal — use standard CSS properties ` +
+            `(e.g. borderRadius, padding) instead. The pipeline expands them automatically.`,
+          );
+        }
+      }
+    }
+  }
+
+  return errors;
+}
+
+export function registerTheme(program) {
+  const theme = program
+    .command('theme')
+    .description('Theme tools — build, export, and manage themes')
+    .action((options, cmd) => {
+      // Parent group has no default behaviour. If the user passed an
+      // unknown subcommand (e.g. `astryx theme bogus`), Commander hands it to
+      // us as a positional in cmd.args — exit 1 with a clear error.
+      const extras = (cmd && cmd.args) || [];
+      if (extras.length > 0) {
+        const unknown = String(extras[0]);
+        const known = (theme.commands || []).map((c) => c.name());
+        const suggestions = known.map((name) => ({name, reason: 'available subcommand'}));
+        cliError(`unknown subcommand 'theme ${unknown}'`, {suggestions, code: ERROR_CODES.ERR_UNKNOWN_SUBCOMMAND});
+        return;
+      }
+      // Bare `astryx theme` — show the subcommand list. Exit 0 (help is success).
+      theme.help();
+    });
+
+  theme
+    .command('build <file>')
+    .description('Compile a defineTheme file to CSS + JS')
+    .option('-o, --out <path>', 'Output CSS file path')
+    .action(async (file, options) => {
+      const filePath = path.resolve(process.cwd(), file);
+      const json = program.opts().json || false;
+
+      if (!fs.existsSync(filePath)) {
+        cliError(`File not found: ${filePath}`, {code: ERROR_CODES.ERR_FILE_NOT_FOUND});
+        return;
+      }
+
+      if (!json) humanLog(`\nBuilding theme from ${path.relative(process.cwd(), filePath)}...`);
+
+      // Extract theme definition
+      let themeDef;
+      try {
+        themeDef = await extractThemeDefinition(filePath);
+      } catch (e) {
+        cliError(e.message, {code: ERROR_CODES.ERR_THEME_LOAD});
+        return;
+      }
+
+      if (!themeDef.name) {
+        cliError('Theme must have a name property.', {code: ERROR_CODES.ERR_THEME_INVALID});
+        return;
+      }
+
+      // Path-safety: the theme name is used to derive output filenames
+      // (e.g. `${name}.css`, `${name}.js`). Reject names containing path
+      // separators or traversal markers — `../../escaped` would otherwise
+      // write JS modules outside the input directory.
+      try {
+        sanitizeName(themeDef.name, {label: 'theme name'});
+      } catch (err) {
+        if (err instanceof PathSafetyError) {
+          cliError(err.message, {code: ERROR_CODES.ERR_PATH_TRAVERSAL});
+          return;
+        }
+        throw err;
+      }
+
+      // Validate component overrides
+      const warnings = validateComponentOverrides(themeDef);
+      const warningMessages = [];
+      for (const w of warnings) {
+        warningMessages.push(w);
+        if (!json) console.warn(`  ⚠ ${w}`);
+      }
+
+      // Validate no private vars are set directly
+      const privateVarErrors = validatePrivateVars(themeDef);
+      for (const e of privateVarErrors) {
+        warningMessages.push(e);
+        if (!json) console.error(`  ✗ ${e}`);
+      }
+      if (privateVarErrors.length > 0 && !json) {
+        console.error(`\n  ${privateVarErrors.length} private var error(s). Use standard CSS properties instead.`);
+      }
+
+      // Generate CSS via core's shared generator — the SINGLE source of truth.
+      // `astryx theme build` and the `<Theme>` runtime MUST emit identical CSS, so
+      // there is exactly one generation path: @astryxdesign/core/theme. If core could not
+      // be imported, fail hard rather than silently producing divergent output.
+      if (!_defineTheme || !_generateThemeRulesSplit) {
+        cliError(
+          'Could not load @astryxdesign/core/theme — `astryx theme build` requires a ' +
+            'built, resolvable @astryxdesign/core so it emits the same CSS as the ' +
+            'runtime <Theme>. Build @astryxdesign/core first (e.g. `pnpm -F @astryxdesign/core ' +
+            'build`)' +
+            (_coreImportError ? `.\n  Import error: ${_coreImportError.message}` : '.'),
+          {code: ERROR_CODES.ERR_CORE_NOT_FOUND},
+        );
+      }
+
+      let css;
+      let resolvedTheme;
+      {
+        // jiti returns an already-resolved theme; legacy eval returns raw input.
+        const isAlreadyResolved =
+          !themeDef.typography && !themeDef.motion && !themeDef.radius;
+        if (isAlreadyResolved) {
+          resolvedTheme = themeDef;
+        } else {
+          resolvedTheme = _defineTheme({
+            name: themeDef.name,
+            typography: themeDef.typography,
+            motion: themeDef.motion,
+            radius: themeDef.radius,
+            tokens: themeDef.tokens,
+            components: themeDef.components,
+          });
+        }
+        const scopeSelector = themeScopeStart(themeDef.name);
+        const scopeTo = THEME_SCOPE_TO;
+
+        const {component, prose} = _generateThemeRulesSplit(resolvedTheme);
+        const cssParts = [];
+        // Prose element defaults always ship — the `<Theme>` runtime
+        // (generateThemeCSS) always emits them, so the build must too, or the
+        // CLI output would diverge from runtime. They go in @layer reset
+        // (zero-specificity :where()) so component/Markdown StyleX always wins.
+        if (prose.length > 0) {
+          const proseInner = prose.join('\n\n');
+          cssParts.push(
+            `@layer reset {\n@scope (${scopeSelector}) to (${scopeTo}) {\n${proseInner}\n}\n}`,
+          );
+        }
+        if (component.length > 0) {
+          const componentInner = component.join('\n\n');
+          const componentScope = `@scope (${scopeSelector}) to (${scopeTo}) {\n${componentInner}\n}`;
+          const colorSchemeDecl = componentScope.includes('light-dark(')
+            ? '  :root { color-scheme: light dark; }\n\n'
+            : '';
+          cssParts.push(
+            `@layer astryx-theme {\n${colorSchemeDecl}${componentScope}\n}`,
+          );
+        }
+        // On-media rules (MediaTheme dark/light surface overrides)
+        if (_generateOnMediaCSS) {
+          const onMediaCss = _generateOnMediaCSS(resolvedTheme);
+          if (onMediaCss) {
+            cssParts.push(`@layer astryx-theme {\n${onMediaCss}\n}`);
+          }
+        }
+        if (cssParts.length === 0) {
+          if (!json) humanLog('No overrides found — nothing to build.');
+          return;
+        }
+        css = cssParts.join('\n\n') + '\n';
+      }
+
+      // Source path relative to cwd — used in @generated headers
+      const sourceRelative = path.relative(process.cwd(), filePath);
+      const buildCommand = `astryx theme build ${sourceRelative}${options.out ? ' --out ' + path.relative(process.cwd(), path.resolve(process.cwd(), options.out)) : ''}`;
+
+      // Determine output path
+      const outPath = options.out
+        ? path.resolve(process.cwd(), options.out)
+        : filePath.replace(/\.(ts|tsx|js|jsx|mjs)$/, '.css');
+
+      const displayTheme = resolvedTheme || themeDef;
+      const tokenCount = displayTheme.tokens ? Object.keys(displayTheme.tokens).length : 0;
+      const componentCount = displayTheme.components ? Object.keys(displayTheme.components).length : 0;
+      const size = (Buffer.byteLength(css) / 1024).toFixed(1);
+
+      // Compute all output paths up front so we can validate them as a
+      // group BEFORE writing anything. Previously the CSS would be written
+      // first; if the JS write failed (e.g. ENOENT, permission), the CSS
+      // was left as orphaned half-built output. Stage-then-commit avoids
+      // that.
+      const outDir = path.dirname(outPath);
+      const baseName = themeDef.name;
+      const jsPath = path.join(outDir, `${baseName}.js`);
+      const dtsPath = path.join(outDir, `${baseName}.d.ts`);
+
+      const iconInfo = extractIconInfo(filePath);
+
+      // Generate all file contents in memory first.
+      const cssContent = generatedHeader(sourceRelative, 'css', buildCommand) + css;
+      const jsContent = generatedHeader(sourceRelative, 'js', buildCommand) + generateBuiltModule(resolvedTheme || themeDef, iconInfo);
+      const dtsContent = generatedHeader(sourceRelative, 'ts', buildCommand) + generateBuiltTypes(themeDef, iconInfo);
+
+      // Type augmentation .d.ts if theme has custom prop values
+      const augmentationSource = resolvedTheme || themeDef;
+      const variantDecl = await generateVariantDeclarationsAsync(augmentationSource);
+      const variantDtsPath = variantDecl ? path.join(outDir, `${baseName}.variants.d.ts`) : null;
+      const variantContent = variantDecl
+        ? generatedHeader(sourceRelative, 'ts', buildCommand) + variantDecl
+        : null;
+
+      // Atomic-ish write: stage every file as `<dest>.tmp`, then rename
+      // each into place. If any stage step fails we clean up partials and
+      // exit; if a rename fails mid-way we still have the originals (or
+      // nothing) — never a half-built output set.
+      const writes = [
+        {dest: outPath, content: cssContent},
+        {dest: jsPath, content: jsContent},
+        {dest: dtsPath, content: dtsContent},
+      ];
+      if (variantDtsPath) {
+        writes.push({dest: variantDtsPath, content: variantContent});
+      }
+
+      fs.mkdirSync(outDir, {recursive: true});
+      const staged = [];
+      try {
+        for (const w of writes) {
+          const tmp = `${w.dest}.${process.pid}.tmp`;
+          fs.writeFileSync(tmp, w.content);
+          staged.push({tmp, dest: w.dest});
+        }
+        for (const s of staged) {
+          fs.renameSync(s.tmp, s.dest);
+        }
+      } catch (err) {
+        // Roll back any temp files we managed to create.
+        for (const s of staged) {
+          try { fs.rmSync(s.tmp, {force: true}); } catch { /* best-effort */ }
+        }
+        const msg = `Failed to write theme outputs: ${err.message}`;
+        cliError(msg, {code: ERROR_CODES.ERR_WRITE_FAILED});
+        return;
+      }
+
+      if (!json) {
+        humanLog(`\n✓ ${path.relative(process.cwd(), outPath)}`);
+        humanLog(`  ${tokenCount} token overrides, ${componentCount} component overrides`);
+        humanLog(`  ${size} KB`);
+        humanLog(`✓ ${path.relative(process.cwd(), jsPath)}`);
+        humanLog(`✓ ${path.relative(process.cwd(), dtsPath)}`);
+        if (variantDtsPath) {
+          const augCount = (variantDecl.match(/': true;/g) || []).length;
+          humanLog(`✓ ${path.relative(process.cwd(), variantDtsPath)} (${augCount} type augmentations)`);
+        }
+      }
+
+      if (json) {
+        return jsonOut('theme.build', {
+          name: themeDef.name,
+          tokenCount,
+          componentCount,
+          sizeKB: parseFloat(size),
+          outputs: {
+            css: path.relative(process.cwd(), outPath),
+            js: path.relative(process.cwd(), jsPath),
+            dts: path.relative(process.cwd(), dtsPath),
+            ...(variantDecl ? {variantsDts: path.relative(process.cwd(), variantDtsPath)} : {}),
+          },
+          warnings: warningMessages,
+        });
+      }
+
+      // Print install instructions
+      const relDir = path.relative(process.cwd(), outDir);
+      // When the output dir is the cwd, relDir is empty — avoid emitting a
+      // double-slash import path like './/<name>'. Build a './<relDir>/'
+      // prefix that collapses to './' when relDir is empty.
+      const importPrefix = relDir ? `./${relDir}/` : './';
+      const exportName = `${toIdentifier(baseName)}Theme`;
+      humanLog(`
+Install in your app:
+
+  import { ${exportName} } from '${importPrefix}${baseName}';
+  import '${importPrefix}${baseName}.css';
+
+  <Theme theme={${exportName}}>
+    <App />
+  </Theme>
+
+Or with a <link> tag:
+
+  import { ${exportName} } from '${importPrefix}${baseName}';
+
+  <link rel="stylesheet" href="${importPrefix}${baseName}.css" />
+  <Theme theme={${exportName}}>
+    <App />
+  </Theme>
+`);
+
+      // Print font declaration warnings (derived from typography roles)
+      if (resolvedTheme && resolvedTheme.fonts && resolvedTheme.fonts.length > 0) {
+        humanLog(`\n⚠ Theme "${themeDef.name}" requires fonts not included in the build:`);
+        for (const font of resolvedTheme.fonts) {
+          humanLog(`  ${font.family} — add to your document <head>:`);
+          humanLog(`  <link rel="stylesheet" href="${font.url}" />`);
+        }
+        humanLog('');
+      }
+    });
+}