view-contracts 0.2.0 → 0.3.2

package/renderers/react/lowering/lowerToJsx.ts

@@ -96,9 +96,40 @@ function extraFlexStyle(entry: ElementMapEntry, props: Record<string, IrValue>):
   return `, ${parts.join(', ')}`;
 }
 
+function scrollOverflowLiteral(mode: string): { overflowX: string; overflowY: string } {
+  if (mode === 'horizontal') return { overflowX: 'auto', overflowY: 'hidden' };
+  if (mode === 'both') return { overflowX: 'auto', overflowY: 'auto' };
+  if (mode === 'none') return { overflowX: 'hidden', overflowY: 'hidden' };
+  return { overflowX: 'hidden', overflowY: 'auto' };
+}
+
 function styleAttr(entry: ElementMapEntry, props: Record<string, IrValue>): string {
   const base = collectStyleProps(props);
   const flex = extraFlexStyle(entry, props);
+  if (entry.scrollContainer) {
+    const scrollLit = propLiteral(props, 'scroll');
+    const axisLit = propLiteral(props, 'axis');
+    const literalMode = typeof scrollLit === 'string'
+      ? scrollLit
+      : typeof axisLit === 'string'
+        ? (axisLit === 'horizontal' ? 'horizontal' : 'vertical')
+        : undefined;
+    if (literalMode) {
+      const { overflowX, overflowY } = scrollOverflowLiteral(literalMode);
+      return `style={{ ...commonStyle(${base})${flex}, overflowX: '${overflowX}', overflowY: '${overflowY}' }}`;
+    }
+    const scroll = propExpr(props, 'scroll');
+    const axis = propExpr(props, 'axis');
+    const modeExpr = scroll
+      ?? (axis ? `(${axis} === 'horizontal' ? 'horizontal' : 'vertical')` : `'vertical'`);
+    return `style={{ ...commonStyle(${base})${flex}, ...(() => {
+      const __scroll = ${modeExpr};
+      if (__scroll === 'horizontal') return { overflowX: 'auto', overflowY: 'hidden' };
+      if (__scroll === 'both') return { overflowX: 'auto', overflowY: 'auto' };
+      if (__scroll === 'none') return { overflowX: 'hidden', overflowY: 'hidden' };
+      return { overflowX: 'hidden', overflowY: 'auto' };
+    })() }}`;
+  }
   if (entry.flexGrowProp && props[entry.flexGrowProp]) {
     const grow = propExpr(props, entry.flexGrowProp);
     return `style={{ ...commonStyle(${base})${flex}, flexGrow: ${grow} ?? 1 }}`;
@@ -119,22 +150,47 @@ function actionHandler(props: Record<string, IrValue>, event: 'onClick' | 'onSub
   return `onClick={() => { void dispatchAction(${expr}); }}`;
 }
 
-function classNameAttr(entry: ElementMapEntry, props: Record<string, IrValue>, headingLevel?: number): string {
+function componentToKebab(name: string): string {
+  return name.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase();
+}
+
+function variantClassSuffix(elementName: string, props: Record<string, IrValue>): string | undefined {
+  const variantLit = propLiteral(props, 'variant');
+  if (typeof variantLit === 'string') {
+    return ` vc-${componentToKebab(elementName)}--${variantLit}`;
+  }
+  const variant = propExpr(props, 'variant');
+  if (variant) return ` vc-${componentToKebab(elementName)}--\${${variant}}`;
+  return undefined;
+}
+
+function classNameAttr(
+  elementName: string,
+  entry: ElementMapEntry,
+  props: Record<string, IrValue>,
+  headingLevel?: number,
+): string {
   const base = entry.className ?? '';
   if (entry.tag === 'dynamic-heading' && headingLevel !== undefined) {
-    return `className="ui-heading ui-heading-${headingLevel}"`;
+    const levelClass = `${base} vc-heading-${headingLevel}`;
+    const variantSuffix = variantClassSuffix(elementName, props);
+    if (!variantSuffix) return `className="${levelClass}"`;
+    const variantLit = propLiteral(props, 'variant');
+    if (typeof variantLit === 'string') {
+      return `className="${levelClass}${variantSuffix}"`;
+    }
+    return `className={\`${levelClass}${variantSuffix}\`}`;
   }
-  if (entry.variantClass) {
+  const variantSuffix = variantClassSuffix(elementName, props);
+  if (variantSuffix) {
     const variantLit = propLiteral(props, 'variant');
     if (typeof variantLit === 'string') {
-      return `className="${base} ui-button-${variantLit}"`;
+      return `className="${base}${variantSuffix}"`;
     }
-    const variant = propExpr(props, 'variant');
-    if (variant) return `className={\`${base} ui-button-\${${variant} ?? 'secondary'}\`}`;
-    return `className="${base} ui-button-secondary"`;
+    return `className={\`${base}${variantSuffix}\`}`;
   }
   if (entry.wrapProp && propLiteral(props, entry.wrapProp) === true) {
-    return `className="${base} ui-wrap"`;
+    return `className="${base} vc-wrap"`;
   }
   if (entry.sizeClass && props.size) {
     const size = propExpr(props, 'size');
@@ -150,22 +206,22 @@ function emitFieldWrap(inner: string, props: Record<string, IrValue>, level: num
   const label = propExpr(props, 'label');
   const help = propExpr(props, 'help');
   const error = propExpr(props, 'error');
-  const lines = [`${indent(level)}<label className="ui-field">`];
+  const lines = [`${indent(level)}<label className="vc-field">`];
   if (typeof labelLit === 'string') {
-    lines.push(`${indent(level + 1)}<span className="ui-field-label">{${JSON.stringify(labelLit)}}</span>`);
+    lines.push(`${indent(level + 1)}<span className="vc-field-label">{${JSON.stringify(labelLit)}}</span>`);
   } else if (label) {
-    lines.push(`${indent(level + 1)}{${label} ? <span className="ui-field-label">{${label}}</span> : null}`);
+    lines.push(`${indent(level + 1)}{${label} ? <span className="vc-field-label">{${label}}</span> : null}`);
   }
   lines.push(`${indent(level + 1)}${inner}`);
   if (typeof helpLit === 'string') {
-    lines.push(`${indent(level + 1)}<span className="ui-field-help">{${JSON.stringify(helpLit)}}</span>`);
+    lines.push(`${indent(level + 1)}<span className="vc-field-help">{${JSON.stringify(helpLit)}}</span>`);
   } else if (help) {
-    lines.push(`${indent(level + 1)}{${help} ? <span className="ui-field-help">{${help}}</span> : null}`);
+    lines.push(`${indent(level + 1)}{${help} ? <span className="vc-field-help">{${help}}</span> : null}`);
   }
   if (typeof errorLit === 'string') {
-    lines.push(`${indent(level + 1)}<span className="ui-field-error">{${JSON.stringify(errorLit)}}</span>`);
+    lines.push(`${indent(level + 1)}<span className="vc-field-error">{${JSON.stringify(errorLit)}}</span>`);
   } else if (error) {
-    lines.push(`${indent(level + 1)}{${error} ? <span className="ui-field-error">{${error}}</span> : null}`);
+    lines.push(`${indent(level + 1)}{${error} ? <span className="vc-field-error">{${error}}</span> : null}`);
   }
   lines.push(`${indent(level)}</label>`);
   return lines.join('\n');
@@ -176,12 +232,59 @@ function emitCheckbox(props: Record<string, IrValue>, level: number): string {
   const label = propExpr(props, 'label') ?? '""';
   const checked = props.checked ? `defaultChecked={${propExpr(props, 'checked')}}` : '';
   const disabled = props.enabled ? `disabled={${propExpr(props, 'enabled')} === false}` : '';
-  return `${indent(level)}<label className="ui-check">
+  return `${indent(level)}<label className="vc-checkbox">
 ${indent(level + 1)}<input type="checkbox" name={${name}} ${checked} ${disabled} />
 ${indent(level + 1)}<span>{${label}}</span>
 ${indent(level)}</label>`;
 }
 
+function emitRadio(props: Record<string, IrValue>, level: number): string {
+  const name = propExpr(props, 'binding') ?? propExpr(props, 'name') ?? '""';
+  const value = propExpr(props, 'value') ?? '""';
+  const label = propExpr(props, 'label') ?? '""';
+  const checked = props.checked ? `defaultChecked={${propExpr(props, 'checked')}}` : '';
+  const disabled = props.enabled ? `disabled={${propExpr(props, 'enabled')} === false}` : '';
+  return `${indent(level)}<label className="vc-radio">
+${indent(level + 1)}<input type="radio" name={${name}} value={${value}} ${checked} ${disabled} />
+${indent(level + 1)}<span>{${label}}</span>
+${indent(level)}</label>`;
+}
+
+function emitSwitch(props: Record<string, IrValue>, level: number): string {
+  const name = propExpr(props, 'binding') ?? propExpr(props, 'name') ?? '""';
+  const label = propExpr(props, 'label') ?? '""';
+  const checked = props.checked ? `defaultChecked={${propExpr(props, 'checked')}}` : '';
+  const disabled = props.enabled ? `disabled={${propExpr(props, 'enabled')} === false}` : '';
+  return `${indent(level)}<label className="vc-switch">
+${indent(level + 1)}<input type="checkbox" role="switch" name={${name}} ${checked} ${disabled} />
+${indent(level + 1)}<span>{${label}}</span>
+${indent(level)}</label>`;
+}
+
+function emitIcon(node: IrComponentNode, entry: ElementMapEntry, level: number): string {
+  const props = node.props;
+  const hasAlt = props.alt !== undefined;
+  if (hasAlt) {
+    const attrs: string[] = [
+      classNameAttr(node.name, entry, props),
+      styleAttr(entry, props),
+      `src={${propExpr(props, 'name') ?? '""'}}`,
+      `alt={${propExpr(props, 'alt') ?? '""'}}`,
+    ];
+    if (props.id) attrs.push(`id={${propExpr(props, 'id')}}`);
+    return `${indent(level)}<img ${attrs.join(' ')} />`;
+  }
+
+  const attrs: string[] = [
+    classNameAttr(node.name, entry, props),
+    styleAttr(entry, props),
+    `aria-hidden`,
+  ];
+  if (props.id) attrs.push(`id={${propExpr(props, 'id')}}`);
+  if (props.name) attrs.push(`data-icon={${propExpr(props, 'name')}}`);
+  return `${indent(level)}<span ${attrs.join(' ')} />`;
+}
+
 function emitSelectOptions(props: Record<string, IrValue>, level: number): string {
   const options = props.options;
   if (!options || typeof options !== 'object' || !('kind' in options)) return '';
@@ -193,19 +296,42 @@ function emitSelectOptions(props: Record<string, IrValue>, level: number): strin
   return `${indent(level + 1)}{${expr}.map((option) => <option key={option.value} value={option.value}>{option.label}</option>)}`;
 }
 
-function emitVoidInput(entry: ElementMapEntry, props: Record<string, IrValue>, level: number): string {
-  const attrs: string[] = [classNameAttr(entry, props), styleAttr(entry, props)];
+function emitVoidInput(
+  elementName: string,
+  entry: ElementMapEntry,
+  props: Record<string, IrValue>,
+  level: number,
+): string {
+  const attrs: string[] = [classNameAttr(elementName, entry, props), styleAttr(entry, props)];
+  if (entry.ariaHidden) attrs.push('aria-hidden');
+  if (props.id) attrs.push(`id={${propExpr(props, 'id')}}`);
+  if (props.role) attrs.push(`role={${propExpr(props, 'role')}}`);
+  else if (entry.defaultRole) attrs.push(`role="${entry.defaultRole}"`);
+  if (entry.ariaLabel) {
+    if (props.ariaLabel) attrs.push(`aria-label={${propExpr(props, 'ariaLabel')}}`);
+    else if (props.label) attrs.push(`aria-label={${propExpr(props, 'label')}}`);
+    else if (props.title) attrs.push(`aria-label={${propExpr(props, 'title')}}`);
+  }
   if (props.name) attrs.push(`name={${propExpr(props, 'name')}}`);
   if (props.placeholder) attrs.push(`placeholder={${propExpr(props, 'placeholder')}}`);
   if (entry.inputType) attrs.push(`type={${propExpr(props, 'type') ?? JSON.stringify(entry.inputType)}}`);
   if (props.required) attrs.push(`required={${propExpr(props, 'required')}}`);
   if (props.readonly) attrs.push(`readOnly={${propExpr(props, 'readonly')}}`);
   if (props.enabled) attrs.push(`disabled={${propExpr(props, 'enabled')} === false}`);
-  if (props.rows) attrs.push(`rows={${propExpr(props, 'rows') ?? '4'}`);
+  if (entry.tag === 'img' && props.src) attrs.push(`src={${propExpr(props, 'src')}}`);
+  if (entry.tag === 'img' && props.alt) attrs.push(`alt={${propExpr(props, 'alt')}}`);
+  if (entry.tag === 'progress' && props.value) attrs.push(`value={${propExpr(props, 'value')}}`);
+  if (props.rows) attrs.push(`rows={${propExpr(props, 'rows') ?? '4'}}`);
   return `${indent(level)}<${entry.tag} ${attrs.join(' ')} />`;
 }
 
-function emitOpenTag(entry: ElementMapEntry, props: Record<string, IrValue>, tag: string, headingLevel?: number): string {
+function emitOpenTag(
+  elementName: string,
+  entry: ElementMapEntry,
+  props: Record<string, IrValue>,
+  tag: string,
+  headingLevel?: number,
+): string {
   const attrs: string[] = [];
   if (entry.ariaHidden) attrs.push('aria-hidden');
   if (props.id) attrs.push(`id={${propExpr(props, 'id')}}`);
@@ -223,7 +349,7 @@ function emitOpenTag(entry: ElementMapEntry, props: Record<string, IrValue>, tag
   if (entry.tag === 'button' && props.enabled) attrs.push(`disabled={${propExpr(props, 'enabled')} === false}`);
   if (entry.tag === 'a' && props.href) attrs.push(`href={${propExpr(props, 'href')}}`);
   if (entry.tag === 'button') attrs.push(`type={${propExpr(props, 'type') ?? '"button"'}}`);
-  attrs.push(classNameAttr(entry, props, headingLevel));
+  attrs.push(classNameAttr(elementName, entry, props, headingLevel));
   attrs.push(styleAttr(entry, props));
   return `<${tag} ${attrs.join(' ')}`;
 }
@@ -286,14 +412,43 @@ function lowerVocabularyElement(
     return visibilityGuard(emitCheckbox(props, level), props, level);
   }
 
+  if (node.name === 'Radio') {
+    return visibilityGuard(emitRadio(props, level), props, level);
+  }
+
+  if (node.name === 'Switch') {
+    return visibilityGuard(emitSwitch(props, level), props, level);
+  }
+
+  if (node.name === 'Icon') {
+    return visibilityGuard(emitIcon(node, entry, level), props, level);
+  }
+
+  if (node.name === 'Spinner') {
+    const attrs = [
+      classNameAttr(node.name, entry, props),
+      styleAttr(entry, props),
+      'aria-busy="true"',
+    ];
+    if (props.id) attrs.push(`id={${propExpr(props, 'id')}}`);
+    if (props.role) attrs.push(`role={${propExpr(props, 'role')}}`);
+    else if (entry.defaultRole) attrs.push(`role="${entry.defaultRole}"`);
+    return visibilityGuard(`${indent(level)}<div ${attrs.join(' ')} />`, props, level);
+  }
+
+  if (entry.fieldContainer) {
+    const inner = childContent || `${indent(level + 1)}<div />`;
+    return visibilityGuard(emitFieldWrap(inner, props, level), props, level);
+  }
+
   if (entry.fieldWrap) {
     const tag = entry.tag;
     let inner: string;
     if (entry.optionsProp && props[entry.optionsProp]) {
-      const open = emitOpenTag(entry, props, tag);
+      const open = emitOpenTag(node.name, entry, props, tag);
       inner = `${indent(level + 1)}${open}>\n${emitSelectOptions(props, level + 2)}\n${indent(level + 1)}</${tag}>`;
     } else {
-      inner = emitVoidInput(entry, props, level + 1);
+      inner = emitVoidInput(node.name, entry, props, level + 1);
     }
     return visibilityGuard(emitFieldWrap(inner, props, level), props, level);
   }
@@ -303,7 +458,7 @@ function lowerVocabularyElement(
     if (typeof levelLit === 'number') {
       const clamped = Math.min(6, Math.max(1, levelLit));
       const tag = `h${clamped}`;
-      const open = emitOpenTag(entry, props, tag, clamped);
+      const open = emitOpenTag(node.name, entry, props, tag, clamped);
       const body = childContent
         ? `${indent(level)}${open}>\n${childContent}\n${indent(level)}</${tag}>`
         : `${indent(level)}${open} />`;
@@ -311,17 +466,17 @@ function lowerVocabularyElement(
     }
     const levelExpr = propExpr(props, 'level') ?? '2';
     const inner = childContent
-      ? `${indent(level + 1)}{(() => { const __level = Math.min(6, Math.max(1, ${levelExpr} ?? 2)); const Tag = ('h' + __level) as keyof JSX.IntrinsicElements; return <Tag className={\`ui-heading ui-heading-\${__level}\`} style={commonStyle(${collectStyleProps(props)})}>{/* children below */}</Tag>; })()}`
+      ? `${indent(level + 1)}{(() => { const __level = Math.min(6, Math.max(1, ${levelExpr} ?? 2)); const Tag = ('h' + __level) as keyof JSX.IntrinsicElements; return <Tag className={\`vc-heading vc-heading-\${__level}\`} style={commonStyle(${collectStyleProps(props)})}>{/* children below */}</Tag>; })()}`
       : '';
-    return visibilityGuard(inner || `${indent(level)}<h2 ${classNameAttr(entry, props, 2)} ${styleAttr(entry, props)} />`, props, level);
+    return visibilityGuard(inner || `${indent(level)}<h2 ${classNameAttr(node.name, entry, props, 2)} ${styleAttr(entry, props)} />`, props, level);
   }
 
   const tag = entry.tag;
   if (entry.void) {
-    return visibilityGuard(`${indent(level)}${emitOpenTag(entry, props, tag)} />`, props, level);
+    return visibilityGuard(emitVoidInput(node.name, entry, props, level), props, level);
   }
 
-  const open = emitOpenTag(entry, props, tag);
+  const open = emitOpenTag(node.name, entry, props, tag);
   let body: string;
   if (!childContent && entry.optionsProp && props[entry.optionsProp]) {
     body = `${indent(level)}${open}>\n${emitSelectOptions(props, level + 1)}\n${indent(level)}</${tag}>`;

package/renderers/react/renderComponents.ts

@@ -2,10 +2,18 @@ import type { ViewIrDocument } from '../../src/ir/types.js';
 import { loadReactElementMap } from './elementMap.js';
 import { collectExtensionComponents, createNodeRenderer } from './lowering/lowerToJsx.js';
 
+export interface PreviewImportSpecifiers {
+  dispatch: string;
+  styleHelpers: string;
+  contracts: string;
+  extensions: string;
+}
+
 export interface RenderReactOptions {
   componentsImportFrom: string;
   allowlistExtra?: string[];
   elementMapPath?: string;
+  previewImports?: PreviewImportSpecifiers;
 }
 
 export async function renderReactComponent(
@@ -28,20 +36,27 @@ export async function renderReactComponent(
   collectExtensionComponents(doc.root, map, allowlistExtra, extensions);
   const extensionImports = [...extensions].sort();
 
+  const preview = options.previewImports;
+  const dispatchModule = preview?.dispatch ?? '../runtime/dispatch.js';
+  const styleModule = preview?.styleHelpers ?? '../components/style-helpers.js';
+  const contractsModule = preview?.contracts ?? '../contracts';
+  const componentsModule = preview?.extensions ?? options.componentsImportFrom;
+
   const imports: string[] = [
     `import type { ReactElement } from 'react';`,
-    `import { dispatchAction } from '../runtime/dispatch.js';`,
-    `import { commonStyle, mapAlign, mapJustify } from '../components/style-helpers.js';`,
-    `import type { ${doc.viewModel}, ActionDescriptor } from '../contracts';`,
+    `import { dispatchAction } from '${dispatchModule}';`,
+    `import { commonStyle, mapAlign, mapJustify } from '${styleModule}';`,
+    `import type { ${doc.viewModel}, ActionDescriptor } from '${contractsModule}';`,
   ];
   if (extensionImports.length > 0) {
-    imports.push(`import { ${extensionImports.join(', ')} } from '${options.componentsImportFrom}';`);
+    imports.push(`import { ${extensionImports.join(', ')} } from '${componentsModule}';`);
   }
 
-  return `/**
- * Auto-generated React component from ${doc.source}
- * DO NOT EDIT — regenerate with: view-contracts render react
- */
+  const headerComment = preview
+    ? `/**\n * Preview module — compiled live from ${doc.source}\n * Same lowering as generated/; not written to disk.\n */`
+    : `/**\n * Auto-generated React component from ${doc.source}\n * DO NOT EDIT — regenerate with: view-contracts render react\n */`;
+
+  return `${headerComment}
 ${imports.join('\n')}
 
 export function ${componentName}({ vm }: { vm: ${doc.viewModel} }): ReactElement {

package/renderers/react/renderRuntime.ts

@@ -1,17 +1,12 @@
-import { readFile, writeFile, mkdir, stat, cp, unlink } from 'node:fs/promises';
+import { readFile, writeFile, mkdir, stat, unlink } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import type { ViewContractsConfig } from '../../src/config.js';
-import { projectRoot } from '../../src/config.js';
-import { loadThemeCss } from '../../src/catalog/loadThemeCss.js';
-import { packageRoot } from '../../src/lib/packageRoot.js';
+import { projectRoot, requireDesignPaths } from '../../src/config.js';
+import { buildThemeCss } from '../../src/design/buildThemeCss.js';
+import { loadValidateDesign } from '../../src/design/index.js';
 import { renderTemplate } from '../../src/renderer/template.js';
-import { reactRuntimeDir, reactTemplatesDir } from './paths.js';
-
-const toolchainRoot = packageRoot();
-
-function toolchainSchemaDir(): string {
-  return resolve(toolchainRoot, 'src/generated/schema');
-}
+import { reactTemplatesDir } from './paths.js';
+import { rewriteExtensionImportsForGenerated, syncGeneratedRuntime } from './syncGeneratedRuntime.js';
 
 async function pathExists(target: string): Promise<boolean> {
   try {
@@ -22,42 +17,22 @@ async function pathExists(target: string): Promise<boolean> {
   }
 }
 
-function rewriteSchemaImports(content: string): string {
-  return content.split('../../../src/generated/schema/').join('./schema/');
-}
-
-async function copySchemaBundle(componentsDir: string): Promise<void> {
-  const schemaSrc = toolchainSchemaDir();
-  if (!(await pathExists(schemaSrc))) return;
-
-  const schemaDest = resolve(componentsDir, 'schema');
-  await cp(schemaSrc, schemaDest, { recursive: true });
-  for (const name of ['dsl-properties.ts', 'tokens.ts', 'schema-document.ts', 'index.ts'] as const) {
-    const file = resolve(schemaDest, name);
-    if (await pathExists(file)) {
-      await writeFile(file, rewriteSchemaImports(await readFile(file, 'utf-8')), 'utf-8');
-    }
-  }
-}
-
-async function copyStyleBundle(componentsDir: string): Promise<void> {
-  const runtimeSrc = reactRuntimeDir();
-  const style = rewriteSchemaImports(await readFile(resolve(runtimeSrc, 'style.ts'), 'utf-8'));
-  await writeFile(resolve(componentsDir, 'style.ts'), style, 'utf-8');
-
-  const types = rewriteSchemaImports(await readFile(resolve(runtimeSrc, 'types.ts'), 'utf-8'));
-  await writeFile(resolve(componentsDir, 'types.ts'), types, 'utf-8');
-}
-
-async function writeThemeCss(root: string, themeOut: string, templatesDir?: string): Promise<void> {
-  const runtimeTheme = resolve(reactRuntimeDir(), 'theme.css');
-  let css = await loadThemeCss(runtimeTheme);
-  const extensionsCss = resolve(root, 'src/theme.extensions.css');
-  if (await pathExists(extensionsCss)) {
-    css += `\n\n${await readFile(extensionsCss, 'utf-8')}`;
-  }
+async function writeThemeCss(
+  configPath: string,
+  themeOut: string,
+  config: ViewContractsConfig,
+  templatesDir?: string,
+): Promise<void> {
+  const css = await buildThemeCss(config, configPath);
   const content = await renderTemplate(reactTemplatesDir(templatesDir), 'theme.css.hbs', { themeCss: css });
   await writeFile(themeOut, content, 'utf-8');
+
+  const { tokensPath, themePath } = requireDesignPaths(config);
+  const { tokenIR, themeIR } = await loadValidateDesign(tokensPath, themePath);
+  const themeDir = resolve(config.generated.reactDir, '../theme');
+  await mkdir(themeDir, { recursive: true });
+  await writeFile(resolve(themeDir, 'tokens.json'), `${JSON.stringify(tokenIR, null, 2)}\n`, 'utf-8');
+  await writeFile(resolve(themeDir, 'theme.json'), `${JSON.stringify(themeIR, null, 2)}\n`, 'utf-8');
 }
 
 async function removeStaleGeneratedFiles(componentsDir: string): Promise<void> {
@@ -76,32 +51,16 @@ export async function renderReactRuntime(configPath: string, config: ViewContrac
     ? resolve(root, config.rendererTemplatesDir)
     : undefined;
   const templates = reactTemplatesDir(templatesDir);
-  const componentsDir = resolve(config.generated.reactDir, '../components');
-  const runtimeDir = resolve(config.generated.reactDir, '../runtime');
   const srcComponentsDir = resolve(root, 'src/components');
 
-  await mkdir(componentsDir, { recursive: true });
-  await mkdir(runtimeDir, { recursive: true });
-
+  const { componentsDir, runtimeDir } = await syncGeneratedRuntime(configPath, config, templatesDir);
   await removeStaleGeneratedFiles(componentsDir);
-  await copySchemaBundle(componentsDir);
-  await copyStyleBundle(componentsDir);
-  await writeFile(
-    resolve(componentsDir, 'style-helpers.ts'),
-    await renderTemplate(templates, 'style-helpers.ts.hbs', {}),
-    'utf-8',
-  );
-  await writeFile(
-    resolve(componentsDir, 'index.ts'),
-    await renderTemplate(templates, 'components-index.ts.hbs', {}),
-    'utf-8',
-  );
 
   for (const name of ['extensions.tsx', 'sample-types.ts'] as const) {
     const src = resolve(srcComponentsDir, name);
     let body = await readFile(src, 'utf-8');
-    if (name === 'sample-types.ts') {
-      body = body.replace("from './core.js'", "from './types.js'");
+    if (name === 'extensions.tsx') {
+      body = rewriteExtensionImportsForGenerated(body);
     }
     await writeFile(resolve(componentsDir, name), body, 'utf-8');
   }
@@ -117,17 +76,7 @@ export async function renderReactRuntime(configPath: string, config: ViewContrac
     'utf-8',
   );
 
-  await writeThemeCss(root, resolve(config.generated.reactDir, '../theme.css'), templatesDir);
-  await writeFile(
-    resolve(runtimeDir, 'types.ts'),
-    await renderTemplate(templates, 'runtime-types.ts.hbs', {}),
-    'utf-8',
-  );
-  await writeFile(
-    resolve(runtimeDir, 'dispatch.ts'),
-    await renderTemplate(templates, 'dispatch.ts.hbs', {}),
-    'utf-8',
-  );
+  await writeThemeCss(configPath, resolve(config.generated.reactDir, '../theme.css'), config, templatesDir);
 
   console.log(`  components → ${componentsDir}`);
   console.log(`  theme → ${resolve(config.generated.reactDir, '../theme.css')}`);

package/renderers/react/routes.yaml

@@ -10,7 +10,7 @@ react:
     screen:
       pattern: '{{projectRoot}}/generated/react/{{screenName}}.generated.tsx'
   preview:
-    entry: views/preview.entry.tsx
+    entry: .vite/preview-main.tsx
     generatedEntry: src/main.tsx
 
 swiftui:

package/renderers/react/runtime/style.ts

@@ -1,15 +1,16 @@
 import type { CSSProperties } from 'react';
-import type { Align, Clip, ContentAlign, FontWeight, Justify, Shadow } from '../../../src/generated/schema/tokens.js';
-import type { CommonProps } from './types.js';
+import type { LoweredStyleInput } from './types.js';
 
-export function mapAlign(value?: Align): string | undefined {
+/** Map flex alignment shorthand (from lowering) to CSS align-items / align-self values. */
+export function mapAlign(value?: string): string | undefined {
   if (!value) return undefined;
   if (value === 'start') return 'flex-start';
   if (value === 'end') return 'flex-end';
   return value;
 }
 
-export function mapJustify(value?: Justify | string): string | undefined {
+/** Map flex justification shorthand (from lowering) to CSS justify-content values. */
+export function mapJustify(value?: string): string | undefined {
   if (!value) return undefined;
   if (value === 'start') return 'flex-start';
   if (value === 'end') return 'flex-end';
@@ -23,13 +24,7 @@ function len(value: number): string {
   return `${value}px`;
 }
 
-const SHADOW: Record<Exclude<Shadow, 'none'>, string> = {
-  sm: '0 1px 3px rgba(15,23,42,0.08)',
-  md: '0 10px 30px rgba(15, 23, 42, 0.08)',
-  lg: '0 20px 40px rgba(15, 23, 42, 0.12)',
-};
-
-const CONTENT_ALIGN: Record<ContentAlign, string> = {
+const PLACE_ITEMS: Record<string, string> = {
   topStart: 'start start',
   top: 'center start',
   topEnd: 'end start',
@@ -41,18 +36,12 @@ const CONTENT_ALIGN: Record<ContentAlign, string> = {
   bottomEnd: 'end end',
 };
 
-function shadowStyle(shadow: Shadow | boolean | undefined): string | undefined {
-  if (shadow === true) return SHADOW.md;
-  if (!shadow || shadow === 'none') return undefined;
-  return SHADOW[shadow];
-}
-
 function fontSizeStyle(size: number | string | undefined): string | undefined {
   if (size === undefined) return undefined;
   return typeof size === 'number' ? len(size) : size;
 }
 
-export function commonStyle(props: CommonProps): CSSProperties {
+export function commonStyle(props: LoweredStyleInput): CSSProperties {
   const style: CSSProperties = {};
   if (typeof props.width === 'number') style.width = len(props.width);
   if (typeof props.minWidth === 'number') style.minWidth = len(props.minWidth);
@@ -63,34 +52,54 @@ export function commonStyle(props: CommonProps): CSSProperties {
   if (props.aspectRatio !== undefined) style.aspectRatio = String(props.aspectRatio);
   if (typeof props.weight === 'number') style.flexGrow = props.weight;
   if (typeof props.padding === 'number') style.padding = len(props.padding);
-  if (typeof (props as { margin?: number }).margin === 'number') style.margin = len((props as { margin: number }).margin);
+  if (typeof props.margin === 'number') style.margin = len(props.margin);
   if (typeof props.gap === 'number') style.gap = len(props.gap);
-  if (typeof props.radius === 'number') style.borderRadius = len(props.radius);
-  if (props.border) style.border = '1px solid var(--ui-border)';
-  const shadow = shadowStyle(props.shadow);
-  if (shadow) style.boxShadow = shadow;
-  if (props.opacity !== undefined) style.opacity = props.opacity;
-  if (props.clip && props.clip !== 'none') style.overflow = 'hidden';
-  if (props.background) style.background = `var(--ui-${props.background}, ${props.background})`;
-  if (props.foreground) style.color = `var(--ui-${props.foreground}, ${props.foreground})`;
-  if (props.textAlign) style.textAlign = props.textAlign === 'start' ? 'left' : props.textAlign === 'end' ? 'right' : 'center';
-  if (props.contentAlign) style.placeItems = CONTENT_ALIGN[props.contentAlign];
-  if ((props as { overflow?: string }).overflow) style.overflow = (props as { overflow: string }).overflow;
-  if (props.selfAlign) style.alignSelf = props.selfAlign === 'start' ? 'flex-start' : props.selfAlign === 'end' ? 'flex-end' : props.selfAlign;
+  if (props.textAlign) {
+    style.textAlign = props.textAlign === 'start' ? 'left' : props.textAlign === 'end' ? 'right' : props.textAlign as CSSProperties['textAlign'];
+  }
+  if (props.contentAlign) style.placeItems = PLACE_ITEMS[props.contentAlign];
+  if (props.overflow) style.overflow = props.overflow as CSSProperties['overflow'];
+  if (props.selfAlign) {
+    style.alignSelf = props.selfAlign === 'start' ? 'flex-start' : props.selfAlign === 'end' ? 'flex-end' : props.selfAlign;
+  }
   const fontSize = fontSizeStyle(props.size);
   if (fontSize) style.fontSize = fontSize;
   const fontWeight = typeof props.weight === 'string' ? props.weight : props.fontWeight;
-  if (fontWeight) style.fontWeight = fontWeight as FontWeight;
+  if (fontWeight) style.fontWeight = fontWeight;
   return style;
 }
 
-export function isHidden(props: CommonProps): boolean {
-  return props.visible === false;
+/** Preview vocabulary helper — lowered production JSX does not use visible. */
+export function isHidden(props: { visible?: boolean; hidden?: boolean }): boolean {
+  return props.hidden === true || props.visible === false;
 }
 
-/** Sample/extension helper — tone is not in ui-dsl.schema.json */
+/** Sample/extension helper for preview tone class names. */
 export function toneClass(tone: string | undefined): string {
   return tone ? `ui-tone-${tone}` : 'ui-tone-default';
 }
 
-export type { Clip, ContentAlign, Shadow };
+function componentToKebab(name: string): string {
+  return name.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase();
+}
+
+const DEFAULT_VARIANT_ALIASES = new Set(['default', 'muted']);
+
+/** Resolve theme variant name from variant or legacy tone prop. */
+export function resolveExtensionVariant(variant?: string, tone?: string): string {
+  const raw = variant ?? tone;
+  if (!raw || DEFAULT_VARIANT_ALIASES.has(raw)) return 'default';
+  return raw;
+}
+
+/** Build vc-* base + --variant modifier for themed extension components. */
+export function extensionClassName(
+  component: string,
+  options?: { variant?: string; tone?: string; extra?: string | false },
+): string {
+  const base = `vc-${componentToKebab(component)}`;
+  const variant = resolveExtensionVariant(options?.variant, options?.tone);
+  const parts = [base, `${base}--${variant}`];
+  if (options?.extra) parts.push(options.extra);
+  return parts.filter(Boolean).join(' ');
+}