view-contracts 0.3.3 → 0.3.5

package/renderers/react/renderComponents.ts

@@ -1,6 +1,12 @@
 import type { ViewIrDocument } from '../../src/ir/types.js';
+import { resolve } from 'node:path';
 import { loadReactElementMap } from './elementMap.js';
-import { collectExtensionComponents, createNodeRenderer } from './lowering/lowerToJsx.js';
+import {
+  collectExtensionComponents,
+  collectViewRefComponents,
+  createNodeRenderer,
+} from './lowering/lowerToJsx.js';
+import type { IrComponentNode, IrNode } from '../../src/ir/types.js';
 
 export interface PreviewImportSpecifiers {
   dispatch: string;
@@ -10,24 +16,71 @@ export interface PreviewImportSpecifiers {
 }
 
 export interface RenderReactOptions {
-  componentsImportFrom: string;
+  runtimeImportFrom: string;
+  extensionsImportFrom: string;
+  contractsImportFrom: string;
   allowlistExtra?: string[];
   elementMapPath?: string;
   previewImports?: PreviewImportSpecifiers;
+  /** When set, viewRef nodes import from these paths instead of sibling .generated.js files. */
+  viewRefImportFrom?: Map<string, string>;
+  /** When true, omit viewRef import lines (partials defined in the same module). */
+  inlineViewRefs?: boolean;
+  /** @deprecated Use runtimeImportFrom */
+  componentsImportFrom?: string;
 }
 
-export async function renderReactComponent(
+function componentExportName(doc: ViewIrDocument): string {
+  if (doc.isPartial) return doc.exportName;
+  const baseName = doc.exportName.replace(/View$/, '') || doc.exportName;
+  return baseName.charAt(0).toUpperCase() + baseName.slice(1);
+}
+
+function requireComponentRoot(root: IrNode, source: string): IrComponentNode {
+  if (root.kind !== 'component') {
+    throw new Error(`View IR root must be a component node (${source})`);
+  }
+  return root;
+}
+
+function extractContractTypeNames(propsType: string | undefined): string[] {
+  if (!propsType) return [];
+  const matches = propsType.match(/\b[A-Z][A-Za-z0-9]*ViewModel\b/g);
+  return matches ? [...new Set(matches)] : [];
+}
+
+function partialFunctionParams(doc: ViewIrDocument): string {
+  if (!doc.propsType) return '';
+  const match = doc.propsType.match(/^\{\s*([^}]+)\s*\}$/);
+  if (!match) return `props: ${doc.propsType}`;
+  const inner = match[1].trim();
+  const propNames = inner.split(',').map((part) => part.split(':')[0]!.trim());
+  return `{ ${propNames.join(', ')} }: ${doc.propsType}`;
+}
+
+/** Root-level `{cond ? ...}` from visibilityGuard is invalid inside `return (...)` — wrap in fragment. */
+function formatComponentReturn(body: string): string {
+  const trimmed = body.trimStart();
+  if (trimmed.startsWith('{')) {
+    return `return (\n    <>${body}\n    </>\n  );`;
+  }
+  return `return (\n${body}\n  );`;
+}
+
+function stripModulePreamble(source: string): string {
+  let rest = source.replace(/^\/\*\*[\s\S]*?\*\/\s*/, '');
+  rest = rest.replace(/^import\s[^\n]+\n/gm, '');
+  return rest.trimStart();
+}
+
+async function buildRenderedModule(
   doc: ViewIrDocument,
   options: RenderReactOptions,
 ): Promise<string> {
   const map = await loadReactElementMap(options.elementMapPath);
   const allowlistExtra = options.allowlistExtra ?? [];
-  const baseName = doc.exportName.replace(/View$/, '') || doc.exportName;
-  const componentName = baseName.charAt(0).toUpperCase() + baseName.slice(1);
-  const root = doc.root.kind === 'component' ? doc.root : null;
-  if (!root) {
-    throw new Error(`View IR root must be a component node (${doc.source})`);
-  }
+  const componentName = componentExportName(doc);
+  const root = requireComponentRoot(doc.root, doc.source);
 
   const renderNode = createNodeRenderer(map, allowlistExtra);
   const body = renderNode(root, 2);
@@ -36,37 +89,76 @@ export async function renderReactComponent(
   collectExtensionComponents(doc.root, map, allowlistExtra, extensions);
   const extensionImports = [...extensions].sort();
 
+  const viewRefs = new Set<string>();
+  collectViewRefComponents(doc.root, viewRefs);
+  const viewRefImports = [...viewRefs].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 runtimeModule = preview?.dispatch ?? options.runtimeImportFrom;
+  const contractsModule = preview?.contracts ?? options.contractsImportFrom;
+  const extensionsModule = preview?.extensions ?? options.extensionsImportFrom;
+
+  const contractTypes = new Set<string>();
+  if (doc.isPartial) {
+    for (const typeName of extractContractTypeNames(doc.propsType)) {
+      contractTypes.add(typeName);
+    }
+  } else {
+    contractTypes.add(doc.viewModel);
+  }
+
+  const imports: string[] = [`import type { ReactElement } from 'react';`];
+  imports.push(`import { dispatchAction } from '${runtimeModule}';`);
+
+  const typeImports = [...contractTypes].sort();
+  const typeImportList = typeImports.length > 0
+    ? `${typeImports.join(', ')}, ActionDescriptor`
+    : 'ActionDescriptor';
+  imports.push(`import type { ${typeImportList} } from '${contractsModule}';`);
 
-  const imports: string[] = [
-    `import type { ReactElement } from 'react';`,
-    `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 '${componentsModule}';`);
+    imports.push(`import { ${extensionImports.join(', ')} } from '${extensionsModule}';`);
+  }
+
+  for (const refName of viewRefImports) {
+    if (options.inlineViewRefs) continue;
+    const importFrom = options.viewRefImportFrom?.get(refName)
+      ?? `./${refName}.generated.js`;
+    imports.push(`import { ${refName} } from '${importFrom}';`);
   }
 
   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 */`;
 
+  if (doc.isPartial) {
+    const fnParams = partialFunctionParams(doc);
+
+    return `${headerComment}
+${imports.join('\n')}
+
+export function ${componentName}(${fnParams}): ReactElement {
+  ${formatComponentReturn(body)}
+}
+`;
+  }
+
   return `${headerComment}
 ${imports.join('\n')}
 
 export function ${componentName}({ vm }: { vm: ${doc.viewModel} }): ReactElement {
-  return (
-${body}
-  );
+  ${formatComponentReturn(body)}
 }
 `;
 }
 
+export async function renderReactComponent(
+  doc: ViewIrDocument,
+  options: RenderReactOptions,
+): Promise<string> {
+  return buildRenderedModule(doc, options);
+}
+
 export async function renderReactFromIr(
   doc: ViewIrDocument,
   outputPath: string,
@@ -74,7 +166,71 @@ export async function renderReactFromIr(
 ): Promise<void> {
   const { writeFile, mkdir } = await import('node:fs/promises');
   const { dirname } = await import('node:path');
-  const content = await renderReactComponent(doc, options);
+  const content = await buildRenderedModule(doc, options);
   await mkdir(dirname(outputPath), { recursive: true });
   await writeFile(outputPath, content, 'utf-8');
 }
+
+/** Render screen + partial modules for preview (single file, no cross-imports). */
+export async function renderReactPreviewBundle(
+  screen: ViewIrDocument,
+  partials: ViewIrDocument[],
+  options: RenderReactOptions,
+): Promise<string> {
+  const inlineOptions: RenderReactOptions = { ...options, inlineViewRefs: true };
+
+  const partialModules = await Promise.all(
+    partials.map((partial) => renderReactComponent(partial, inlineOptions)),
+  );
+  const screenModule = await renderReactComponent(screen, inlineOptions);
+
+  const stripImports = stripModulePreamble;
+
+  const map = await loadReactElementMap(options.elementMapPath);
+  const allowlistExtra = options.allowlistExtra ?? [];
+  const extensions = new Set<string>();
+  collectExtensionComponents(screen.root, map, allowlistExtra, extensions);
+  for (const partial of partials) {
+    collectExtensionComponents(partial.root, map, allowlistExtra, extensions);
+  }
+
+  const preview = options.previewImports;
+  const runtimeModule = preview?.dispatch ?? options.runtimeImportFrom;
+  const contractsModule = preview?.contracts ?? options.contractsImportFrom;
+  const extensionsModule = preview?.extensions ?? options.extensionsImportFrom;
+
+  const contractTypes = new Set<string>([screen.viewModel]);
+  for (const partial of partials) {
+    for (const typeName of extractContractTypeNames(partial.propsType)) {
+      contractTypes.add(typeName);
+    }
+  }
+
+  const imports: string[] = [
+    `import type { ReactElement } from 'react';`,
+    `import { dispatchAction } from '${runtimeModule}';`,
+    `import type { ${[...contractTypes].sort().join(', ')}, ActionDescriptor } from '${contractsModule}';`,
+  ];
+  const extensionImports = [...extensions].sort();
+  if (extensionImports.length > 0) {
+    imports.push(`import { ${extensionImports.join(', ')} } from '${extensionsModule}';`);
+  }
+
+  const headerComment = preview
+    ? `/**\n * Preview module — compiled live from ${screen.source}\n * Same lowering as generated/; not written to disk.\n */`
+    : '';
+
+  const partialBodies = partialModules.map(stripImports);
+  const screenBody = stripImports(screenModule);
+
+  return `${headerComment}
+${imports.join('\n')}
+
+${partialBodies.join('\n\n')}
+
+${screenBody}`;
+}
+
+export function partialReactOutputPath(reactDir: string, partial: ViewIrDocument): string {
+  return resolve(reactDir, 'components', `${partial.exportName}.generated.tsx`);
+}

package/renderers/react/renderRuntime.ts

@@ -1,12 +1,11 @@
-import { readFile, writeFile, mkdir, stat, unlink } from 'node:fs/promises';
-import { resolve } from 'node:path';
+import { writeFile, stat, unlink, rm } from 'node:fs/promises';
+import { relative, resolve } from 'node:path';
 import type { ViewContractsConfig } from '../../src/config.js';
-import { projectRoot, requireDesignPaths } from '../../src/config.js';
+import { projectRoot } 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 { reactTemplatesDir } from './paths.js';
-import { rewriteExtensionImportsForGenerated, syncGeneratedRuntime } from './syncGeneratedRuntime.js';
+import { removeLegacyReactRuntimeLayout, writeGeneratedRuntimeBundle } from './syncGeneratedRuntime.js';
 
 async function pathExists(target: string): Promise<boolean> {
   try {
@@ -26,58 +25,52 @@ async function writeThemeCss(
   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> {
-  for (const name of ['ui-components.tsx', 'core.ts', 'actionRuntime.ts', 'shared.tsx', 'shared.ts'] as const) {
-    const target = resolve(componentsDir, name);
-    if (await pathExists(target)) {
-      await unlink(target);
+async function removeLegacyGeneratedRootArtifacts(reactDir: string): Promise<void> {
+  const generatedRoot = resolve(reactDir, '..');
+  for (const name of ['theme.css', 'contracts.ts', 'view-bridge.generated.ts'] as const) {
+    const legacy = resolve(generatedRoot, name);
+    if (await pathExists(legacy)) {
+      await unlink(legacy);
     }
   }
 }
 
+async function writeExtensionsReExport(configPath: string, config: ViewContractsConfig): Promise<string> {
+  const root = projectRoot(configPath);
+  const reactDir = config.generated.reactDir;
+  const extensionsSrc = resolve(root, 'src/components/extensions.tsx');
+  let rel = relative(reactDir, extensionsSrc).replace(/\\/g, '/');
+  if (!rel.startsWith('.')) rel = `./${rel}`;
+  const importPath = rel.replace(/\.tsx?$/, '.js');
+  const outPath = resolve(reactDir, 'extensions.generated.ts');
+  await writeFile(
+    outPath,
+    `/** Auto-generated extension re-export — DO NOT EDIT */\nexport * from '${importPath}';\n`,
+    'utf-8',
+  );
+  return outPath;
+}
+
 /** Emit standalone generated runtime (no preview vocabulary copy; no @view-contracts imports). */
 export async function renderReactRuntime(configPath: string, config: ViewContractsConfig): Promise<void> {
   const root = projectRoot(configPath);
   const templatesDir = config.rendererTemplatesDir
     ? resolve(root, config.rendererTemplatesDir)
     : undefined;
-  const templates = reactTemplatesDir(templatesDir);
-  const srcComponentsDir = resolve(root, 'src/components');
+  const reactDir = config.generated.reactDir;
 
-  const { componentsDir, runtimeDir } = await syncGeneratedRuntime(configPath, config, templatesDir);
-  await removeStaleGeneratedFiles(componentsDir);
+  await removeLegacyGeneratedRootArtifacts(reactDir);
+  await removeLegacyReactRuntimeLayout(reactDir);
 
-  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 === 'extensions.tsx') {
-      body = rewriteExtensionImportsForGenerated(body);
-    }
-    await writeFile(resolve(componentsDir, name), body, 'utf-8');
-  }
-
-  const handlersSrc = resolve(root, 'src/runtime/handlers.ts');
-  const handlersBody = (await readFile(handlersSrc, 'utf-8')).replace(
-    /export async function handleAppAction\(action:\s*\{[\s\S]*?\}\)/,
-    'export async function handleAppAction(action: DispatchableAction)',
-  );
-  await writeFile(
-    resolve(runtimeDir, 'handlers.ts'),
-    await renderTemplate(templates, 'handlers.ts.hbs', { handlersBody }),
-    'utf-8',
-  );
+  const { runtimePath } = await writeGeneratedRuntimeBundle(configPath, config, templatesDir);
+  const extensionsPath = await writeExtensionsReExport(configPath, config);
 
-  await writeThemeCss(configPath, resolve(config.generated.reactDir, '../theme.css'), config, templatesDir);
+  const themeOut = resolve(reactDir, 'theme.css');
+  await writeThemeCss(configPath, themeOut, config, templatesDir);
 
-  console.log(`  components → ${componentsDir}`);
-  console.log(`  theme → ${resolve(config.generated.reactDir, '../theme.css')}`);
+  console.log(`  react/runtime → ${runtimePath}`);
+  console.log(`  react/extensions → ${extensionsPath}`);
+  console.log(`  react/theme → ${themeOut}`);
 }

package/renderers/react/routes.yaml

@@ -3,8 +3,8 @@
 
 react:
   description: Production React via compile-time IR lowering + template-emitted runtime
-  importFrom: '../components/index.js'
-  themeCss: theme.css
+  importFrom: './runtime.js'
+  themeCss: react/theme.css
   templates: renderers/react/templates
   outputs:
     screen:

package/renderers/react/runtime/index.ts

@@ -1,5 +1,5 @@
 /** Preview/toolchain React runtime primitives — not copied to generated/. */
 export * from './types.js';
-export { commonStyle, isHidden, toneClass, mapAlign, mapJustify } from './style.js';
+export { isHidden, toneClass, extensionClassName, resolveExtensionVariant } from './style.js';
 export { registerPreviewActions, clearPreviewActions, dispatchPreviewAction } from './actionRuntime.js';
 export { registerActionHandler, dispatchAction } from './dispatch.js';

package/renderers/react/runtime/style.ts

@@ -1,7 +1,4 @@
-import type { CSSProperties } from 'react';
-import type { LoweredStyleInput } from './types.js';
-
-/** Map flex alignment shorthand (from lowering) to CSS align-items / align-self values. */
+/** Map flex alignment shorthand to CSS align-items / align-self values. */
 export function mapAlign(value?: string): string | undefined {
   if (!value) return undefined;
   if (value === 'start') return 'flex-start';
@@ -9,7 +6,7 @@ export function mapAlign(value?: string): string | undefined {
   return value;
 }
 
-/** Map flex justification shorthand (from lowering) to CSS justify-content values. */
+/** Map flex justification shorthand to CSS justify-content values. */
 export function mapJustify(value?: string): string | undefined {
   if (!value) return undefined;
   if (value === 'start') return 'flex-start';
@@ -20,56 +17,7 @@ export function mapJustify(value?: string): string | undefined {
   return value;
 }
 
-function len(value: number): string {
-  return `${value}px`;
-}
-
-const PLACE_ITEMS: Record<string, string> = {
-  topStart: 'start start',
-  top: 'center start',
-  topEnd: 'end start',
-  start: 'start center',
-  center: 'center center',
-  end: 'end center',
-  bottomStart: 'start end',
-  bottom: 'center end',
-  bottomEnd: 'end end',
-};
-
-function fontSizeStyle(size: number | string | undefined): string | undefined {
-  if (size === undefined) return undefined;
-  return typeof size === 'number' ? len(size) : size;
-}
-
-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);
-  if (typeof props.maxWidth === 'number') style.maxWidth = len(props.maxWidth);
-  if (typeof props.height === 'number') style.height = len(props.height);
-  if (typeof props.minHeight === 'number') style.minHeight = len(props.minHeight);
-  if (typeof props.maxHeight === 'number') style.maxHeight = len(props.maxHeight);
-  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.margin === 'number') style.margin = len(props.margin);
-  if (typeof props.gap === 'number') style.gap = len(props.gap);
-  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;
-  return style;
-}
-
-/** Preview vocabulary helper — lowered production JSX does not use visible. */
+/** Preview vocabulary helper — production lowered JSX uses visibility guards instead. */
 export function isHidden(props: { visible?: boolean; hidden?: boolean }): boolean {
   return props.hidden === true || props.visible === false;
 }

package/renderers/react/runtime/theme.css

@@ -27,7 +27,7 @@ button, input, textarea, select { font: inherit; }
 .ui-tone-warning { color: var(--ui-warning); }
 .ui-tone-danger { color: var(--ui-danger); }
 
-.vc-button { border: 0; border-radius: 10px; padding: 10px 14px; font-weight: 700; cursor: pointer; }
+.vc-button { border: 0; cursor: pointer; }
 
 .vc-form { display: flex; flex-direction: column; }
 .vc-field { display: flex; flex-direction: column; gap: 6px; }

package/renderers/react/runtime/types.ts

@@ -10,30 +10,6 @@ export type DispatchableAction = ViewAction;
 /** Action binding from lowered views or hand-written extensions. */
 export type Action = ViewAction;
 
-/**
- * Style props passed to commonStyle() by the React lowering pass.
- * Numeric dimensions are logical units; commonStyle maps them to px.
- */
-export interface LoweredStyleInput {
-  width?: number | string;
-  minWidth?: number | string;
-  maxWidth?: number | string;
-  height?: number | string;
-  minHeight?: number | string;
-  maxHeight?: number | string;
-  aspectRatio?: number | string;
-  weight?: number | string;
-  padding?: number | string;
-  margin?: number;
-  gap?: number | string;
-  textAlign?: string;
-  contentAlign?: string;
-  selfAlign?: string;
-  overflow?: string;
-  size?: number | string;
-  fontWeight?: string;
-}
-
 export interface Option {
   label: string;
   value: string;

package/renderers/react/style/foldLiterals.ts

@@ -0,0 +1,129 @@
+/**
+ * Pure compile-time style folding from literal DSL prop values.
+ * Used by lowering (static JSX) and preview vocabulary stubs only.
+ */
+import { mapAlign, mapJustify } from '../runtime/style.js';
+
+export type FoldedCss = Record<string, string | number>;
+
+function len(value: number): string {
+  return `${value}px`;
+}
+
+const PLACE_ITEMS: Record<string, string> = {
+  topStart: 'start start',
+  top: 'center start',
+  topEnd: 'end start',
+  start: 'start center',
+  center: 'center center',
+  end: 'end center',
+  bottomStart: 'start end',
+  bottom: 'center end',
+  bottomEnd: 'end end',
+};
+
+const SHADOW_PRESETS: Record<string, string> = {
+  none: 'none',
+  sm: 'var(--ui-shadow-sm, 0 1px 2px rgba(0,0,0,0.05))',
+  md: 'var(--ui-shadow)',
+  lg: 'var(--ui-shadow-lg, 0 10px 15px rgba(0,0,0,0.1))',
+};
+
+function tokenRefToCssVar(value: string): string | undefined {
+  const match = value.match(/^\{([^}]+)\}$/);
+  if (!match) return undefined;
+  return `var(--${match[1]!.replace(/\./g, '-')})`;
+}
+
+export function foldLiteralsToCss(literals: Record<string, unknown>): FoldedCss {
+  const style: FoldedCss = {};
+  const width = literals.width;
+  if (typeof width === 'number') style.width = len(width);
+  else if (typeof width === 'string' && width !== 'wrap' && width !== 'fill') style.width = width;
+
+  if (typeof literals.minWidth === 'number') style.minWidth = len(literals.minWidth);
+  if (typeof literals.maxWidth === 'number') style.maxWidth = len(literals.maxWidth);
+  if (typeof literals.height === 'number') style.height = len(literals.height);
+  if (typeof literals.minHeight === 'number') style.minHeight = len(literals.minHeight);
+  if (typeof literals.maxHeight === 'number') style.maxHeight = len(literals.maxHeight);
+  if (literals.aspectRatio !== undefined) style.aspectRatio = String(literals.aspectRatio);
+
+  const weight = literals.weight;
+  if (typeof weight === 'number') style.flexGrow = weight;
+
+  if (typeof literals.padding === 'number') style.padding = len(literals.padding);
+  if (typeof literals.margin === 'number') style.margin = len(literals.margin);
+  if (typeof literals.gap === 'number') style.gap = len(literals.gap);
+
+  const textAlign = literals.textAlign;
+  if (typeof textAlign === 'string') {
+    style.textAlign = textAlign === 'start' ? 'left' : textAlign === 'end' ? 'right' : textAlign;
+  }
+
+  const contentAlign = literals.contentAlign;
+  if (typeof contentAlign === 'string' && contentAlign in PLACE_ITEMS) {
+    style.placeItems = PLACE_ITEMS[contentAlign]!;
+  }
+
+  if (typeof literals.overflow === 'string') style.overflow = literals.overflow;
+
+  const selfAlign = literals.selfAlign;
+  if (typeof selfAlign === 'string') {
+    style.alignSelf = selfAlign === 'start' ? 'flex-start' : selfAlign === 'end' ? 'flex-end' : selfAlign;
+  }
+
+  const size = literals.size;
+  if (typeof size === 'number') style.fontSize = len(size);
+  else if (typeof size === 'string') style.fontSize = size;
+
+  const fontWeight = typeof weight === 'string' ? weight : literals.fontWeight;
+  if (typeof fontWeight === 'string') style.fontWeight = fontWeight;
+
+  const background = literals.background;
+  if (typeof background === 'string') style.background = tokenRefToCssVar(background) ?? background;
+
+  const foreground = literals.foreground;
+  if (typeof foreground === 'string') style.color = tokenRefToCssVar(foreground) ?? foreground;
+
+  const radius = literals.radius;
+  if (typeof radius === 'number') style.borderRadius = len(radius);
+  else if (typeof radius === 'string') style.borderRadius = tokenRefToCssVar(radius) ?? radius;
+
+  const shadow = literals.shadow;
+  if (shadow === true) style.boxShadow = 'var(--ui-shadow)';
+  else if (shadow === false) style.boxShadow = 'none';
+  else if (typeof shadow === 'string') {
+    style.boxShadow = SHADOW_PRESETS[shadow] ?? tokenRefToCssVar(shadow) ?? shadow;
+  }
+
+  const border = literals.border;
+  if (typeof border === 'string') style.border = tokenRefToCssVar(border) ?? border;
+
+  if (typeof literals.opacity === 'number') style.opacity = literals.opacity;
+
+  const clip = literals.clip;
+  if (typeof clip === 'string') style.overflow = clip === 'hidden' ? 'hidden' : clip;
+
+  const align = literals.align;
+  if (typeof align === 'string') {
+    const mapped = mapAlign(align);
+    if (mapped) style.alignItems = mapped;
+  }
+
+  const justify = literals.justify;
+  if (typeof justify === 'string') {
+    const mapped = mapJustify(justify);
+    if (mapped) style.justifyContent = mapped;
+  }
+
+  return style;
+}
+
+export function foldedStyleToJsx(style: FoldedCss): string {
+  const entries = Object.entries(style);
+  if (entries.length === 0) return '';
+  const body = entries
+    .map(([key, value]) => (typeof value === 'number' ? `${key}: ${value}` : `${key}: ${JSON.stringify(value)}`))
+    .join(', ');
+  return `style={{ ${body} }}`;
+}