view-contracts 0.1.0 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "view-contracts",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Contract-first UI design toolchain — restricted TSX to View IR to platform renderers",
   "type": "module",
   "workspaces": [
@@ -12,7 +12,7 @@
   "files": [
     "dist/view-contracts.bundle.mjs",
     "dist/view-contracts.bundle.mjs.map",
-    "src/renderer/react/runtime",
+    "renderers/react/runtime",
     "src/generated/schema",
     "spec",
     "renderers",
@@ -43,7 +43,10 @@
     "contracts:check": "tsx src/cli.ts contracts check -c examples/admin-dashboard/view-contracts.config.yaml",
     "schema:generate": "tsx scripts/schema-generate.ts",
     "cli-contracts:validate": "cli-contracts validate",
-    "test:ci": "node dist/view-contracts.bundle.mjs --version && node dist/view-contracts.bundle.mjs --help",
+    "test": "vitest run",
+    "test:unit": "vitest run",
+    "test:smoke": "node dist/view-contracts.bundle.mjs --version && node dist/view-contracts.bundle.mjs --help",
+    "test:ci": "npm run test:unit && npm run build:publish && npm run test:smoke",
     "version": "node -e \"const fs=require('fs');const f='cli-contract.yaml';fs.writeFileSync(f,fs.readFileSync(f,'utf8').replace(/^  version: .*/m,'  version: '+process.env.npm_package_version))\" && git add cli-contract.yaml",
     "prepublishOnly": "npm run build:publish && npm run test:ci"
   },
@@ -73,6 +76,7 @@
   },
   "dependencies": {
     "commander": "^14.0.3",
+    "handlebars": "^4.7.9",
     "js-yaml": "^4.1.1",
     "micro-contracts": "^0.17.10",
     "react": "^19.2.0",
@@ -80,6 +84,7 @@
     "typescript": "^5.9.3"
   },
   "devDependencies": {
+    "@types/handlebars": "^4.1.0",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.19.21",
     "@types/react": "^19.2.17",
@@ -89,6 +94,7 @@
     "cli-contracts": "^0.33.13",
     "esbuild": "^0.28.0",
     "tsx": "^4.21.0",
-    "vite": "^6.4.1"
+    "vite": "^6.4.1",
+    "vitest": "^4.1.9"
   }
 }

package/renderers/react/README.md

@@ -3,8 +3,24 @@
 Per-target mapping for view-contracts UI DSL → React.
 
 - `routes.yaml` — generated output file routing
-- `elements.yaml` — element → React component (hand-maintained)
-- `properties.yaml` — property → style/attr (hand-maintained)
+- `elements.yaml` — vocabulary element → HTML tag (SSoT for compile-time lowering)
+- `element-config.meta.json` — shape of `elements.yaml` entries (drives schema codegen)
+- `templates/*.hbs` — Handlebars templates for generated runtime files (dispatch, types, theme, etc.)
+- `renderComponents.ts` / `renderRuntime.ts` — compile-time codegen (IR → JSX, runtime bundle)
+- `lowering/lowerToJsx.ts` — element-map-driven JSX emission
+- `runtime/` — preview/toolchain primitives (style, dispatch) — **not** copied to `generated/`
 
 Vocabulary (elements/properties) is defined in `spec/ui-dsl.schema.json` (from `ui-dsl-*.csv`).
-Sample-only preview helpers (Sidebar, Card, etc.) are **not** part of the vocabulary.
+Preview vocabulary stubs are generated to `src/generated/preview/vocabulary.tsx`.
+Sample-only preview helpers (Sidebar, Card, etc.) are **not** part of the vocabulary — they live in project `src/components/extensions.tsx`.
+
+Generic renderer utilities (template engine, YAML element-map validation) live under `src/renderer/`.
+
+## Compile-time lowering
+
+`renderComponents.ts` reads `elements.yaml` and emits native HTML/JSX into `generated/react/*.generated.tsx`.
+`renderers/react/runtime/` is **not** copied to `generated/`.
+
+## Template customization
+
+Set `rendererTemplatesDir` in `view-contracts.config.yaml` to override default templates.

package/renderers/react/element-config.meta.json

@@ -0,0 +1,23 @@
+{
+  "description": "Per-element fields allowed in renderers/react/elements.yaml (React HTML lowering config — not UI DSL vocabulary).",
+  "fields": {
+    "tag": { "type": "string", "required": true },
+    "className": { "type": "string" },
+    "ariaLabel": { "type": "boolean" },
+    "ariaHidden": { "type": "boolean" },
+    "flex": { "type": "enum", "values": ["row", "column"] },
+    "wrapProp": { "type": "string" },
+    "flexGrowProp": { "type": "string" },
+    "void": { "type": "boolean" },
+    "levelProp": { "type": "string" },
+    "defaultLevel": { "type": "number" },
+    "actionEvent": { "type": "enum", "values": ["onClick", "onSubmit"] },
+    "variantClass": { "type": "boolean" },
+    "fieldWrap": { "type": "boolean" },
+    "inputType": { "type": "string" },
+    "sizeClass": { "type": "string" },
+    "optionsProp": { "type": "string" },
+    "checkbox": { "type": "boolean" },
+    "defaultRole": { "type": "string" }
+  }
+}

package/renderers/react/elementMap.ts

@@ -0,0 +1,55 @@
+import { resolve } from 'node:path';
+import { ALLOWED_COMPONENTS } from '../../src/generated/schema/allowed-components.js';
+import type { ReactElementMapFile, ReactRendererElementConfig } from '../../src/generated/schema/react-renderer-element-config.js';
+import { packageRoot } from '../../src/lib/packageRoot.js';
+import {
+  loadYamlFile,
+  validateMapEntryFields,
+  validateVocabularyElementNames,
+} from '../../src/renderer/elementMapValidation.js';
+import { loadUiDslSchema } from '../../src/schema/loadSchema.js';
+
+export type { ReactElementMapFile, ReactRendererElementConfig };
+export type ReactElementMap = ReactElementMapFile;
+export type ElementMapEntry = ReactRendererElementConfig;
+
+const SOURCE_LABEL = 'renderers/react/elements.yaml';
+
+let cachedMap: ReactElementMapFile | null = null;
+
+function validateElementMap(map: ReactElementMapFile): void {
+  validateVocabularyElementNames(Object.keys(map.elements), ALLOWED_COMPONENTS, SOURCE_LABEL);
+  validateMapEntryFields(map.elements, ['tag'], SOURCE_LABEL);
+}
+
+export async function loadReactElementMap(customPath?: string): Promise<ReactElementMapFile> {
+  if (!customPath && cachedMap) return cachedMap;
+  const mapPath = customPath ?? resolve(packageRoot(), 'renderers/react/elements.yaml');
+  const raw = await loadYamlFile<ReactElementMapFile>(mapPath);
+  validateElementMap(raw);
+  if (!customPath) cachedMap = raw;
+  return raw;
+}
+
+/** DSL vocabulary element with a React HTML lowering entry (excludes project extensions). */
+export function isLowerableVocabularyElement(
+  name: string,
+  map: ReactElementMapFile,
+  allowlistExtra: string[] = [],
+): boolean {
+  return ALLOWED_COMPONENTS.has(name) && !allowlistExtra.includes(name) && name in map.elements;
+}
+
+export async function assertElementMapCoversImplementedVocabulary(customPath?: string): Promise<void> {
+  const [schema, map] = await Promise.all([loadUiDslSchema(), loadReactElementMap(customPath)]);
+  const missing = Object.keys(schema.elements).filter((name) => !(name in map.elements));
+  if (missing.length > 0) {
+    console.warn(
+      `${SOURCE_LABEL}: ${missing.length} DSL element(s) have no React HTML map yet: ${missing.join(', ')}`,
+    );
+  }
+}
+
+export function isVocabularyElement(name: string, map: ReactElementMapFile, allowlistExtra: string[] = []): boolean {
+  return name in map.elements && !allowlistExtra.includes(name);
+}

package/renderers/react/elements.yaml

@@ -0,0 +1,87 @@
+# React renderer element → HTML lowering map (SSoT).
+# Vocabulary from spec/ui-dsl.schema.json. Extension components are project-specific
+# (allowlistExtra) and stay as React component imports — not listed here.
+
+elements:
+  Page:
+    tag: main
+    className: ui-page
+    ariaLabel: true
+  Box:
+    tag: div
+    className: ui-box
+    ariaLabel: true
+  Column:
+    tag: div
+    className: ui-column
+    flex: column
+    ariaLabel: true
+  Row:
+    tag: div
+    className: ui-row
+    flex: row
+    wrapProp: wrap
+    ariaLabel: true
+  Stack:
+    tag: div
+    className: ui-stack
+    ariaLabel: true
+  Spacer:
+    tag: div
+    className: ui-spacer
+    ariaHidden: true
+    flexGrowProp: weight
+  Divider:
+    tag: hr
+    className: ui-divider
+    void: true
+  Heading:
+    tag: dynamic-heading
+    className: ui-heading
+    levelProp: level
+    defaultLevel: 2
+  Text:
+    tag: p
+    className: ui-text
+  Link:
+    tag: a
+    className: ui-link
+    actionEvent: onClick
+  Button:
+    tag: button
+    className: ui-button
+    variantClass: true
+    actionEvent: onClick
+  Form:
+    tag: form
+    className: ui-form
+    actionEvent: onSubmit
+    ariaLabel: true
+  TextInput:
+    tag: input
+    className: ui-input
+    fieldWrap: true
+    inputType: text
+    sizeClass: ui-field
+  TextArea:
+    tag: textarea
+    className: ui-textarea
+    fieldWrap: true
+  Select:
+    tag: select
+    className: ui-select
+    fieldWrap: true
+    sizeClass: ui-field
+    optionsProp: options
+  Checkbox:
+    tag: label
+    className: ui-check
+    checkbox: true
+  List:
+    tag: ul
+    className: ui-list
+    defaultRole: list
+  ListItem:
+    tag: li
+    className: ui-list-item
+    defaultRole: listitem

package/renderers/react/index.ts

@@ -0,0 +1,2 @@
+export { renderReactFromIr, renderReactComponent } from './renderComponents.js';
+export { renderReactRuntime } from './renderRuntime.js';

package/renderers/react/lowering/lowerToJsx.ts

@@ -0,0 +1,397 @@
+import type { ElementMapEntry, ReactElementMap } from '../elementMap.js';
+import { LOWERING_STYLE_PROPERTIES } from '../../../src/generated/schema/lowering-style-properties.js';
+import type {
+  IrAction,
+  IrBinding,
+  IrComponentNode,
+  IrFragmentNode,
+  IrLiteral,
+  IrMapNode,
+  IrNode,
+  IrTextNode,
+  IrValue,
+} from '../../../src/ir/types.js';
+
+function indent(level: number): string {
+  return '  '.repeat(level);
+}
+
+function bindingExpr(binding: IrBinding, vmRef = 'vm'): string {
+  const root = binding.scope ?? vmRef;
+  return binding.path ? `${root}.${binding.path}` : root;
+}
+
+function renderAction(action: IrAction, cast = false): string {
+  const suffix = cast ? ' as ActionDescriptor' : '';
+  if (!action.params || Object.keys(action.params).length === 0) {
+    return `{ name: ${JSON.stringify(action.name)} }${suffix}`;
+  }
+  const params = Object.entries(action.params)
+    .map(([key, val]) => `${key}: ${renderValue(val, 0)}`)
+    .join(', ');
+  return `{ name: ${JSON.stringify(action.name)}, params: { ${params} } }${suffix}`;
+}
+
+function renderLiteralValue(value: unknown, level: number, castActions = false): string {
+  if (value === null) return 'null';
+  if (typeof value === 'string') return JSON.stringify(value);
+  if (typeof value === 'number' || typeof value === 'boolean') return String(value);
+  if (Array.isArray(value)) {
+    return `[\n${value.map((item) => `${indent(level + 1)}${renderLiteralValue(item, level + 1, castActions)}`).join(',\n')}\n${indent(level)}]`;
+  }
+  if (typeof value === 'object' && value !== null) {
+    const obj = value as Record<string, unknown>;
+    if ('kind' in obj && obj.kind === 'action') {
+      return renderAction(obj as unknown as IrAction, castActions);
+    }
+    const entries = Object.entries(obj).map(([key, val]) => `${key}: ${renderLiteralValue(val, level + 1, castActions)}`);
+    return `{\n${entries.map((entry) => `${indent(level + 1)}${entry}`).join(',\n')}\n${indent(level)}}`;
+  }
+  return 'undefined';
+}
+
+export function renderValue(value: IrValue, level: number, castActions = false): string {
+  if (value === null) return 'null';
+  if (typeof value === 'string') return JSON.stringify(value);
+  if (typeof value === 'number' || typeof value === 'boolean') return String(value);
+  if (Array.isArray(value)) {
+    return `[\n${value.map((item) => `${indent(level + 1)}${renderValue(item, level + 1, castActions)}`).join(',\n')}\n${indent(level)}]`;
+  }
+  if (typeof value === 'object' && value !== null && 'kind' in value) {
+    if (value.kind === 'binding') return bindingExpr(value as IrBinding);
+    if (value.kind === 'action') return renderAction(value as IrAction, castActions);
+    if (value.kind === 'literal') return renderLiteralValue((value as IrLiteral).value, level, castActions);
+  }
+  return 'undefined';
+}
+
+function propLiteral(props: Record<string, IrValue>, key: string): unknown | undefined {
+  const value = props[key];
+  if (value === null || value === undefined) return undefined;
+  if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') return value;
+  if (typeof value === 'object' && 'kind' in value && value.kind === 'literal') {
+    return (value as IrLiteral).value;
+  }
+  return undefined;
+}
+
+function propExpr(props: Record<string, IrValue>, key: string): string | undefined {
+  const value = props[key];
+  if (value === null || value === undefined) return undefined;
+  return renderValue(value, 0);
+}
+
+function collectStyleProps(props: Record<string, IrValue>): string {
+  const entries = Object.entries(props).filter(([key]) => LOWERING_STYLE_PROPERTIES.has(key));
+  if (entries.length === 0) return '{}';
+  const body = entries.map(([key, val]) => `${key}: ${renderValue(val, 0)}`).join(', ');
+  return `{ ${body} }`;
+}
+
+function extraFlexStyle(entry: ElementMapEntry, props: Record<string, IrValue>): string {
+  if (!entry.flex) return '';
+  const parts = [`display: 'flex'`, `flexDirection: '${entry.flex === 'column' ? 'column' : 'row'}'`];
+  if (props.align) parts.push(`alignItems: mapAlign(${propExpr(props, 'align')})`);
+  if (props.justify) parts.push(`justifyContent: mapJustify(${propExpr(props, 'justify')})`);
+  return `, ${parts.join(', ')}`;
+}
+
+function styleAttr(entry: ElementMapEntry, props: Record<string, IrValue>): string {
+  const base = collectStyleProps(props);
+  const flex = extraFlexStyle(entry, props);
+  if (entry.flexGrowProp && props[entry.flexGrowProp]) {
+    const grow = propExpr(props, entry.flexGrowProp);
+    return `style={{ ...commonStyle(${base})${flex}, flexGrow: ${grow} ?? 1 }}`;
+  }
+  if (flex) return `style={{ ...commonStyle(${base})${flex} }}`;
+  return `style={commonStyle(${base})}`;
+}
+
+function actionHandler(props: Record<string, IrValue>, event: 'onClick' | 'onSubmit'): string | undefined {
+  const action = props.action ?? props[event === 'onClick' ? 'onClick' : 'onSubmit'];
+  if (!action || typeof action !== 'object' || !('kind' in action) || action.kind !== 'action') {
+    return undefined;
+  }
+  const expr = renderAction(action as IrAction, true);
+  if (event === 'onSubmit') {
+    return `onSubmit={(e) => { e.preventDefault(); void dispatchAction(${expr}); }}`;
+  }
+  return `onClick={() => { void dispatchAction(${expr}); }}`;
+}
+
+function classNameAttr(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}"`;
+  }
+  if (entry.variantClass) {
+    const variantLit = propLiteral(props, 'variant');
+    if (typeof variantLit === 'string') {
+      return `className="${base} ui-button-${variantLit}"`;
+    }
+    const variant = propExpr(props, 'variant');
+    if (variant) return `className={\`${base} ui-button-\${${variant} ?? 'secondary'}\`}`;
+    return `className="${base} ui-button-secondary"`;
+  }
+  if (entry.wrapProp && propLiteral(props, entry.wrapProp) === true) {
+    return `className="${base} ui-wrap"`;
+  }
+  if (entry.sizeClass && props.size) {
+    const size = propExpr(props, 'size');
+    return `className={\`${entry.className} ${entry.sizeClass}-\${${size} ?? 'md'}\`}`;
+  }
+  return `className="${base}"`;
+}
+
+function emitFieldWrap(inner: string, props: Record<string, IrValue>, level: number): string {
+  const labelLit = propLiteral(props, 'label');
+  const helpLit = propLiteral(props, 'help');
+  const errorLit = propLiteral(props, 'error');
+  const label = propExpr(props, 'label');
+  const help = propExpr(props, 'help');
+  const error = propExpr(props, 'error');
+  const lines = [`${indent(level)}<label className="ui-field">`];
+  if (typeof labelLit === 'string') {
+    lines.push(`${indent(level + 1)}<span className="ui-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)}${inner}`);
+  if (typeof helpLit === 'string') {
+    lines.push(`${indent(level + 1)}<span className="ui-field-help">{${JSON.stringify(helpLit)}}</span>`);
+  } else if (help) {
+    lines.push(`${indent(level + 1)}{${help} ? <span className="ui-field-help">{${help}}</span> : null}`);
+  }
+  if (typeof errorLit === 'string') {
+    lines.push(`${indent(level + 1)}<span className="ui-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)}</label>`);
+  return lines.join('\n');
+}
+
+function emitCheckbox(props: Record<string, IrValue>, level: number): string {
+  const name = 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="ui-check">
+${indent(level + 1)}<input type="checkbox" name={${name}} ${checked} ${disabled} />
+${indent(level + 1)}<span>{${label}}</span>
+${indent(level)}</label>`;
+}
+
+function emitSelectOptions(props: Record<string, IrValue>, level: number): string {
+  const options = props.options;
+  if (!options || typeof options !== 'object' || !('kind' in options)) return '';
+  if (options.kind === 'literal' && Array.isArray((options as IrLiteral).value)) {
+    const items = (options as IrLiteral).value as Array<{ label: string; value: string }>;
+    return items.map((opt) => `${indent(level + 1)}<option key={${JSON.stringify(opt.value)}} value={${JSON.stringify(opt.value)}}>{${JSON.stringify(opt.label)}}</option>`).join('\n');
+  }
+  const expr = renderValue(options, 0);
+  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)];
+  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'}`);
+  return `${indent(level)}<${entry.tag} ${attrs.join(' ')} />`;
+}
+
+function emitOpenTag(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')}}`);
+  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 (entry.actionEvent) {
+    const handler = actionHandler(props, entry.actionEvent);
+    if (handler) attrs.push(handler);
+  }
+  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(styleAttr(entry, props));
+  return `<${tag} ${attrs.join(' ')}`;
+}
+
+function visibilityGuard(inner: string, props: Record<string, IrValue>, level: number): string {
+  if (props.visible === undefined) return inner;
+  const vis = propExpr(props, 'visible');
+  return `${indent(level)}{${vis} !== false ? (\n${inner}\n${indent(level)}) : null}`;
+}
+
+type NodeRenderer = (node: IrComponentNode, level: number, itemScope?: string) => string;
+
+function renderChildren(
+  children: IrNode[],
+  level: number,
+  renderNested: NodeRenderer,
+  itemScope?: string,
+): string {
+  if (children.length === 0) return '';
+  const vmRef = itemScope ?? 'vm';
+  const parts = children.map((child) => {
+    if (child.kind === 'text') {
+      const text = (child as IrTextNode).value;
+      return text ? `${indent(level)}{${JSON.stringify(text)}}` : '';
+    }
+    if (child.kind === 'binding') {
+      return `${indent(level)}{${bindingExpr(child, vmRef)}}`;
+    }
+    if (child.kind === 'map') return renderMap(child as IrMapNode, level, renderNested);
+    if (child.kind === 'fragment') {
+      return renderChildren(child.children, level, renderNested, itemScope);
+    }
+    if (child.kind === 'component') return renderNested(child, level, itemScope);
+    return '';
+  }).filter(Boolean);
+  return parts.join('\n');
+}
+
+function renderMap(node: IrMapNode, level: number, renderNested: NodeRenderer): string {
+  const item = node.item;
+  let body = renderNested(node.body as IrComponentNode, level + 1, item);
+  if (node.key) {
+    const keyAttr = ` key={${bindingExpr(node.key, item)}}`;
+    body = body.replace(/^( +)<(\w+)/, `$1<$2${keyAttr}`);
+  }
+  return `${indent(level)}{${bindingExpr(node.source)}.map((${item}) => (\n${body}\n${indent(level)}))}`;
+}
+
+function lowerVocabularyElement(
+  node: IrComponentNode,
+  entry: ElementMapEntry,
+  level: number,
+  itemScope: string | undefined,
+  renderNested: NodeRenderer,
+): string {
+  const props = node.props;
+  const childContent = renderChildren(node.children, level + 1, renderNested, itemScope);
+
+  if (entry.checkbox) {
+    return visibilityGuard(emitCheckbox(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);
+      inner = `${indent(level + 1)}${open}>\n${emitSelectOptions(props, level + 2)}\n${indent(level + 1)}</${tag}>`;
+    } else {
+      inner = emitVoidInput(entry, props, level + 1);
+    }
+    return visibilityGuard(emitFieldWrap(inner, props, level), props, level);
+  }
+
+  if (entry.tag === 'dynamic-heading') {
+    const levelLit = propLiteral(props, 'level');
+    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 body = childContent
+        ? `${indent(level)}${open}>\n${childContent}\n${indent(level)}</${tag}>`
+        : `${indent(level)}${open} />`;
+      return visibilityGuard(body, props, level);
+    }
+    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>; })()}`
+      : '';
+    return visibilityGuard(inner || `${indent(level)}<h2 ${classNameAttr(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);
+  }
+
+  const open = emitOpenTag(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}>`;
+  } else if (!childContent) {
+    body = `${indent(level)}${open} />`;
+  } else {
+    body = `${indent(level)}${open}>\n${childContent}\n${indent(level)}</${tag}>`;
+  }
+  return visibilityGuard(body, props, level);
+}
+
+function renderExtensionProps(props: Record<string, IrValue>, itemScope?: string): string {
+  const vmRef = itemScope ?? 'vm';
+  return Object.entries(props).map(([key, value]) => {
+    if (key === 'action' && typeof value === 'object' && value !== null && 'kind' in value && value.kind === 'action') {
+      return `${key}={${renderAction(value as IrAction, true)}}`;
+    }
+    if (typeof value === 'object' && value !== null && 'kind' in value && value.kind === 'binding') {
+      return `${key}={${bindingExpr(value as IrBinding, vmRef)}}`;
+    }
+    if (key === 'children') return '';
+    return `${key}={${renderValue(value, 0, key === 'columns')}}`;
+  }).join(' ');
+}
+
+function renderExtensionElement(
+  node: IrComponentNode,
+  level: number,
+  itemScope: string | undefined,
+  renderNested: NodeRenderer,
+): string {
+  const props = renderExtensionProps(node.props, itemScope);
+  const propStr = props ? ` ${props}` : '';
+  const childContent = renderChildren(node.children, level + 1, renderNested, itemScope);
+  if (!childContent) {
+    return `${indent(level)}<${node.name}${propStr} />`;
+  }
+  return `${indent(level)}<${node.name}${propStr}>\n${childContent}\n${indent(level)}</${node.name}>`;
+}
+
+function isVocabulary(name: string, map: ReactElementMap, allowlistExtra: string[]): boolean {
+  return name in map.elements && !allowlistExtra.includes(name);
+}
+
+export function collectExtensionComponents(
+  node: IrNode,
+  map: ReactElementMap,
+  allowlistExtra: string[],
+  names: Set<string>,
+): void {
+  if (node.kind === 'component') {
+    if (!isVocabulary(node.name, map, allowlistExtra)) names.add(node.name);
+    for (const child of node.children) collectExtensionComponents(child, map, allowlistExtra, names);
+    return;
+  }
+  if (node.kind === 'map') collectExtensionComponents(node.body, map, allowlistExtra, names);
+  if (node.kind === 'fragment') {
+    for (const child of node.children) collectExtensionComponents(child, map, allowlistExtra, names);
+  }
+}
+
+export function createNodeRenderer(
+  map: ReactElementMap,
+  allowlistExtra: string[],
+): NodeRenderer {
+  const renderNested: NodeRenderer = (node, level, itemScope) => {
+    if (isVocabulary(node.name, map, allowlistExtra)) {
+      return lowerVocabularyElement(node, map.elements[node.name]!, level, itemScope, renderNested);
+    }
+    return renderExtensionElement(node, level, itemScope, renderNested);
+  };
+  return renderNested;
+}

package/renderers/react/paths.ts

@@ -0,0 +1,10 @@
+import { resolve } from 'node:path';
+import { packageRoot } from '../../src/lib/packageRoot.js';
+
+export function reactTemplatesDir(customDir?: string): string {
+  return customDir ?? resolve(packageRoot(), 'renderers/react/templates');
+}
+
+export function reactRuntimeDir(): string {
+  return resolve(packageRoot(), 'renderers/react/runtime');
+}