view-contracts 0.3.5 → 0.4.1

package/docs/cli-reference.md

@@ -13,6 +13,7 @@ Contract-first UI design toolchain. Compiles restricted view-contract TSX to lan
   - [build](#view-contracts-build)
   - [contracts.generate](#view-contracts-contracts-generate)
   - [contracts.check](#view-contracts-contracts-check)
+  - [preview](#view-contracts-preview)
 
 ---
 
@@ -200,3 +201,38 @@ view-contracts contracts check -c view-contracts.config.yaml
 **Exit 1:** Lint failed.
 
 ---
+
+### preview
+
+Start DSL preview HTTP server.
+
+Compiles views/*.view.tsx on demand and serves a React preview over HTTP. No Vite setup required in the consumer project.
+
+**Usage:**
+
+```
+view-contracts preview
+```
+```
+view-contracts preview -c view-contracts.config.yaml
+```
+```
+view-contracts preview --port 3000 --screen AdminDashboard
+```
+
+#### Options
+
+| Option | Aliases | Required | Default | Description |
+|---|---|---|---|---|
+| `--config` | -c | No |  | Path to view-contracts.config.yaml (discovered upward from cwd when omitted). |
+| `--port` | -p | No |  | HTTP listen port. |
+| `--host` |  | No |  | HTTP listen host. |
+| `--screen` |  | No |  | Screen name from view-bindings.yaml (default first react target). |
+
+#### Exit Codes
+
+**Exit 0:** Server stopped normally.
+
+**Exit 1:** Startup or compile failed.
+
+---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "view-contracts",
-  "version": "0.3.5",
+  "version": "0.4.1",
   "description": "Contract-first UI design toolchain — restricted TSX to View IR to platform renderers",
   "type": "module",
   "workspaces": [
@@ -9,9 +9,18 @@
   "bin": {
     "view-contracts": "dist/view-contracts.bundle.mjs"
   },
+  "exports": {
+    ".": "./dist/view-contracts.bundle.mjs",
+    "./preview": "./dist/preview.mjs",
+    "./package.json": "./package.json"
+  },
   "files": [
     "dist/view-contracts.bundle.mjs",
     "dist/view-contracts.bundle.mjs.map",
+    "dist/preview.mjs",
+    "dist/preview.mjs.map",
+    "dist/preview-style-helpers.js",
+    "dist/preview-style-helpers.js.map",
     "renderers/react/runtime",
     "renderers/react/defaults",
     "src/generated/schema",
@@ -36,6 +45,7 @@
     "bundle": "node esbuild.bundle.mjs",
     "bundle:min": "node esbuild.bundle.mjs --minify",
     "build:views": "tsx src/cli.ts build -c examples/admin-dashboard/view-contracts.config.yaml",
+    "render:swiftui-prototype": "tsx scripts/render-swiftui-prototype.ts",
     "build:example": "vite build --config examples/admin-dashboard/.vite/vite.config.ts",
     "compile": "tsx src/cli.ts compile -c examples/admin-dashboard/view-contracts.config.yaml",
     "render:react": "tsx src/cli.ts render react -c examples/admin-dashboard/view-contracts.config.yaml",
@@ -74,8 +84,25 @@
   "engines": {
     "node": ">=20.0.0"
   },
+  "peerDependencies": {
+    "vite": "^5.0.0 || ^6.0.0",
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
   "dependencies": {
     "commander": "^14.0.3",
+    "esbuild": "^0.28.0",
     "handlebars": "^4.7.9",
     "js-yaml": "^4.1.1",
     "micro-contracts": "^0.17.10",

package/renderers/compose/renderRuntime.ts

@@ -0,0 +1,40 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import type { ViewBindingsFile, ViewContractsConfig } from '../../src/config.js';
+import { packageRoot } from '../../src/lib/packageRoot.js';
+import { renderTemplate } from '../../src/renderer/template.js';
+
+function composeTemplatesDir(): string {
+  return resolve(packageRoot(), 'renderers/compose/templates');
+}
+
+export async function renderComposeRuntime(
+  config: ViewContractsConfig,
+  bindings: ViewBindingsFile,
+): Promise<void> {
+  const composeDir = resolve(config.generated.reactDir, '../compose');
+  await mkdir(composeDir, { recursive: true });
+
+  await writeFile(
+    resolve(composeDir, 'VcTheme.kt'),
+    await renderTemplate(composeTemplatesDir(), 'VcTheme.kt.hbs', {
+      packageName: 'generated.compose',
+    }),
+    'utf-8',
+  );
+
+  for (const view of bindings.views) {
+    if (view.targets.includes('compose')) {
+      const out = resolve(composeDir, `${view.screenName}Screen.kt`);
+      await writeFile(
+        out,
+        await renderTemplate(composeTemplatesDir(), 'Screen.kt.hbs', {
+          screenName: view.screenName,
+          packageName: 'generated.compose',
+        }),
+        'utf-8',
+      );
+      console.log(`  compose → ${out}`);
+    }
+  }
+}

package/renderers/react/defaults/theme.yaml

@@ -6,6 +6,44 @@ defaults:
     radius: "{ui.space.radius-md}"
     padding: "{ui.space.button-padding}"
     fontWeight: "{ui.layout.font-bold}"
+  TextInput:
+    background: "{ui.surface}"
+    foreground: "{ui.text}"
+    radius: "{ui.space.radius-md}"
+    padding: "{ui.space.input-padding}"
+    border: "{ui.layout.border-1}"
+    borderColor: "{ui.border}"
+    minHeight: "{ui.space.input-min-height}"
+  TextArea:
+    background: "{ui.surface}"
+    foreground: "{ui.text}"
+    radius: "{ui.space.radius-md}"
+    padding: "{ui.space.textarea-padding}"
+    border: "{ui.layout.border-1}"
+    borderColor: "{ui.border}"
+  Select:
+    background: "{ui.surface}"
+    foreground: "{ui.text}"
+    radius: "{ui.space.radius-md}"
+    padding: "{ui.space.select-padding}"
+    border: "{ui.layout.border-1}"
+    borderColor: "{ui.border}"
+    minHeight: "{ui.space.input-min-height}"
+  TableHeader:
+    background: "{ui.surface-muted}"
+    alignItems: "{ui.layout.align-center}"
+  TableColumn:
+    padding: "{ui.space.table-column-padding}"
+    fontSize: "{ui.space.table-column-font-size}"
+    fontWeight: "{ui.layout.font-semibold}"
+    foreground: "{ui.text-muted}"
+  TableCell:
+    padding: "{ui.space.table-cell-padding}"
+    fontSize: "{ui.space.table-cell-font-size}"
+  TableRow:
+    alignItems: "{ui.layout.align-center}"
+  Box:
+    width: "{ui.layout.width-full}"
 variants:
   Button:
     primary:
@@ -23,6 +61,16 @@ variants:
   Text:
     muted:
       foreground: "{ui.text-muted}"
+    field-label:
+      fontSize: "{ui.space.font-field-label}"
+      fontWeight: "{ui.layout.font-bold}"
+      foreground: "{ui.text}"
+    field-help:
+      fontSize: "{ui.space.font-field-help}"
+      foreground: "{ui.text-muted}"
+    field-error:
+      fontSize: "{ui.space.font-field-help}"
+      foreground: "{ui.danger}"
     primary:
       foreground: "{ui.primary}"
     success:
@@ -31,3 +79,7 @@ variants:
       foreground: "{ui.warning}"
     danger:
       foreground: "{ui.danger}"
+  Box:
+    card:
+      background: "{ui.surface}"
+      width: "{ui.layout.width-full}"

package/renderers/react/defaults/tokens.yaml

@@ -1,4 +1,4 @@
-# Default design tokens — mirrors renderers/react/runtime/theme.css :root variables.
+# Default design tokens — merged into generated/react/theme.css via emitTokenCss().
 ui:
   bg:
     $type: color
@@ -61,6 +61,18 @@ ui:
     font-bold:
       $type: layout
       $value: "700"
+    font-semibold:
+      $type: layout
+      $value: "600"
+    border-1:
+      $type: layout
+      $value: "1px solid"
+    align-center:
+      $type: layout
+      $value: "center"
+    width-full:
+      $type: layout
+      $value: "100%"
   space:
     radius-md:
       $type: dimension
@@ -68,3 +80,66 @@ ui:
     button-padding:
       $type: dimension
       $value: "10px 14px"
+    input-padding:
+      $type: dimension
+      $value: "9px 12px"
+    input-min-height:
+      $type: dimension
+      $value: "42px"
+    select-padding:
+      $type: dimension
+      $value: "9px 36px 9px 12px"
+    textarea-padding:
+      $type: dimension
+      $value: "10px 12px"
+    field-gap:
+      $type: dimension
+      $value: "6px"
+    field-inner-gap:
+      $type: dimension
+      $value: "4px"
+    checkbox-gap:
+      $type: dimension
+      $value: "8px"
+    list-indent:
+      $type: dimension
+      $value: "20px"
+    list-item-padding:
+      $type: dimension
+      $value: "2px 0"
+    line-height-body:
+      $type: dimension
+      $value: "1.6"
+    line-height-heading:
+      $type: dimension
+      $value: "1.2"
+    font-field-label:
+      $type: dimension
+      $value: "13px"
+    font-field-help:
+      $type: dimension
+      $value: "12px"
+    table-column-padding:
+      $type: dimension
+      $value: "12px 14px"
+    table-column-font-size:
+      $type: dimension
+      $value: "12px"
+    table-cell-padding:
+      $type: dimension
+      $value: "14px"
+    table-cell-font-size:
+      $type: dimension
+      $value: "14px"
+    input-min-height-sm:
+      $type: dimension
+      $value: "34px"
+    input-min-height-lg:
+      $type: dimension
+      $value: "50px"
+    input-padding-sm:
+      $type: dimension
+      $value: "6px 10px"
+    input-padding-lg:
+      $type: dimension
+      $value: "12px 14px"

package/renderers/react/elementMap.ts

@@ -1,15 +1,39 @@
 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 { ALLOWED_COMPONENTS } from '../../src/schema/dsl-catalog.js';
+import { ELEMENT_CATALOG } from '../../src/schema/dsl-catalog.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 };
+/** Shape of entries in renderers/react/elements.yaml (renderer-owned SSoT). */
+export interface ReactRendererElementConfig {
+  tag: string;
+  className?: string;
+  ariaLabel?: boolean;
+  ariaHidden?: boolean;
+  flex?: 'row' | 'column';
+  wrapProp?: string;
+  flexGrowProp?: string;
+  void?: boolean;
+  actionEvent?: 'onClick' | 'onSubmit';
+  fieldWrap?: boolean;
+  inputType?: string;
+  sizeClass?: string;
+  optionsProp?: string;
+  checkbox?: boolean;
+  fieldContainer?: boolean;
+  scrollContainer?: boolean;
+  defaultRole?: string;
+  tableCell?: boolean;
+}
+
+export interface ReactElementMapFile {
+  elements: Record<string, ReactRendererElementConfig>;
+}
+
 export type ReactElementMap = ReactElementMapFile;
 export type ElementMapEntry = ReactRendererElementConfig;
 
@@ -41,8 +65,8 @@ export function isLowerableVocabularyElement(
 }
 
 export async function validateElementMapCoversVocabulary(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));
+  const map = await loadReactElementMap(customPath);
+  const missing = Object.keys(ELEMENT_CATALOG).filter((name) => !(name in map.elements));
   if (missing.length > 0) {
     throw new Error(
       `${SOURCE_LABEL}: ${missing.length} DSL element(s) have no React HTML map yet: ${missing.join(', ')}`,

package/renderers/react/elements.yaml

@@ -45,11 +45,6 @@ elements:
     tag: hr
     className: vc-divider
     void: true
-  Heading:
-    tag: dynamic-heading
-    className: vc-heading
-    levelProp: level
-    defaultLevel: 2
   Text:
     tag: p
     className: vc-text
@@ -140,3 +135,20 @@ elements:
     tag: li
     className: vc-list-item
     defaultRole: listitem
+  Table:
+    tag: table
+    className: vc-table
+  TableHeader:
+    tag: thead
+    className: vc-table-header
+  TableColumn:
+    tag: th
+    className: vc-table-column
+    tableCell: true
+  TableRow:
+    tag: tr
+    className: vc-table-row
+  TableCell:
+    tag: td
+    className: vc-table-cell
+    tableCell: true

package/renderers/react/lowering/foldStyle.ts

@@ -2,7 +2,7 @@
  * Compile-time style folding for React lowering.
  * Production generated JSX must not call runtime style helpers.
  */
-import { LOWERING_STYLE_PROPERTIES } from '../../../src/generated/schema/lowering-style-properties.js';
+import { LOWERING_STYLE_PROPERTIES } from '../../../src/schema/dsl-catalog.js';
 import type { IrLiteral, IrValue } from '../../../src/ir/types.js';
 import type { ElementMapEntry } from '../elementMap.js';
 import { foldLiteralsToCss, foldedStyleToJsx, type FoldedCss } from '../style/foldLiterals.js';
@@ -57,6 +57,18 @@ export function styleAttrForElement(entry: ElementMapEntry, props: Record<string
   let folded = foldLiteralsToCss(literals);
   folded = { ...folded, ...foldFlexContainer(entry) };
 
+  if (entry.tableCell) {
+    if ('alignItems' in folded) {
+      const ai = String(folded.alignItems);
+      folded.textAlign = ai === 'flex-end' ? 'right' : ai === 'center' ? 'center' : 'left';
+      delete folded.alignItems;
+    }
+    if ('width' in folded && !('flex' in folded)) {
+      folded.flexShrink = 0;
+      folded.flexGrow = 0;
+    }
+  }
+
   if (entry.scrollContainer) {
     const scrollLit = propLiteral(props, 'scroll');
     const axisLit = propLiteral(props, 'axis');

package/renderers/react/lowering/lowerToJsx.ts

@@ -4,6 +4,7 @@ import type {
   IrAction,
   IrBinding,
   IrComponentNode,
+  IrConcat,
   IrFragmentNode,
   IrLiteral,
   IrMapNode,
@@ -22,6 +23,14 @@ function bindingExpr(binding: IrBinding, vmRef = 'vm'): string {
   return binding.path ? `${root}.${binding.path}` : root;
 }
 
+function concatSegments(concat: IrConcat): string {
+  return concat.parts.map(p => typeof p === 'string' ? p : `\${${bindingExpr(p)}}`).join('');
+}
+
+function renderConcat(concat: IrConcat): string {
+  return `\`${concatSegments(concat)}\``;
+}
+
 function renderAction(action: IrAction, cast = false): string {
   const suffix = cast ? ' as ActionDescriptor' : '';
   if (!action.params || Object.keys(action.params).length === 0) {
@@ -62,6 +71,7 @@ export function renderValue(value: IrValue, level: number, castActions = false):
     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);
+    if (value.kind === 'concat') return renderConcat(value as IrConcat);
   }
   return 'undefined';
 }
@@ -108,6 +118,10 @@ function variantClassSuffix(elementName: string, props: Record<string, IrValue>)
   if (typeof variantLit === 'string') {
     return ` vc-${componentToKebab(elementName)}--${variantLit}`;
   }
+  const variantVal = props.variant;
+  if (variantVal && typeof variantVal === 'object' && 'kind' in variantVal && variantVal.kind === 'concat') {
+    return ` vc-${componentToKebab(elementName)}--${concatSegments(variantVal as IrConcat)}`;
+  }
   const variant = propExpr(props, 'variant');
   if (variant) return ` vc-${componentToKebab(elementName)}--\${${variant}}`;
   return undefined;
@@ -117,19 +131,8 @@ function classNameAttr(
   elementName: string,
   entry: ElementMapEntry,
   props: Record<string, IrValue>,
-  headingLevel?: number,
 ): string {
   const base = entry.className ?? '';
-  if (entry.tag === 'dynamic-heading' && headingLevel !== undefined) {
-    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}\`}`;
-  }
   const variantSuffix = variantClassSuffix(elementName, props);
   if (variantSuffix) {
     const variantLit = propLiteral(props, 'variant');
@@ -157,20 +160,20 @@ function emitFieldWrap(inner: string, props: Record<string, IrValue>, level: num
   const error = propExpr(props, 'error');
   const lines = [`${indent(level)}<label className="vc-field">`];
   if (typeof labelLit === 'string') {
-    lines.push(`${indent(level + 1)}<span className="vc-field-label">{${JSON.stringify(labelLit)}}</span>`);
+    lines.push(`${indent(level + 1)}<span className="vc-text vc-text--field-label">{${JSON.stringify(labelLit)}}</span>`);
   } else if (label) {
-    lines.push(`${indent(level + 1)}{${label} ? <span className="vc-field-label">{${label}}</span> : null}`);
+    lines.push(`${indent(level + 1)}{${label} ? <span className="vc-text vc-text--field-label">{${label}}</span> : null}`);
   }
   lines.push(`${indent(level + 1)}${inner}`);
   if (typeof helpLit === 'string') {
-    lines.push(`${indent(level + 1)}<span className="vc-field-help">{${JSON.stringify(helpLit)}}</span>`);
+    lines.push(`${indent(level + 1)}<span className="vc-text vc-text--field-help">{${JSON.stringify(helpLit)}}</span>`);
   } else if (help) {
-    lines.push(`${indent(level + 1)}{${help} ? <span className="vc-field-help">{${help}}</span> : null}`);
+    lines.push(`${indent(level + 1)}{${help} ? <span className="vc-text vc-text--field-help">{${help}}</span> : null}`);
   }
   if (typeof errorLit === 'string') {
-    lines.push(`${indent(level + 1)}<span className="vc-field-error">{${JSON.stringify(errorLit)}}</span>`);
+    lines.push(`${indent(level + 1)}<span className="vc-text vc-text--field-error">{${JSON.stringify(errorLit)}}</span>`);
   } else if (error) {
-    lines.push(`${indent(level + 1)}{${error} ? <span className="vc-field-error">{${error}}</span> : null}`);
+    lines.push(`${indent(level + 1)}{${error} ? <span className="vc-text vc-text--field-error">{${error}}</span> : null}`);
   }
   lines.push(`${indent(level)}</label>`);
   return lines.join('\n');
@@ -280,7 +283,6 @@ function emitOpenTag(
   entry: ElementMapEntry,
   props: Record<string, IrValue>,
   tag: string,
-  headingLevel?: number,
 ): string {
   const attrs: string[] = [];
   if (entry.ariaHidden) attrs.push('aria-hidden');
@@ -299,7 +301,7 @@ function emitOpenTag(
   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(elementName, entry, props, headingLevel));
+  attrs.push(classNameAttr(elementName, entry, props));
   pushStyleAttr(attrs, entry, props);
   return `<${tag} ${attrs.join(' ')}`;
 }
@@ -402,27 +404,6 @@ function lowerVocabularyElement(
     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(node.name, 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 foldedStyle = foldedStyleToJsx(foldLiteralsToCss(collectLiteralStyleProps(props)));
-    const styleFragment = foldedStyle ? ` ${foldedStyle}` : '';
-    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={\`vc-heading vc-heading-\${__level}\`}${styleFragment}>{/* children below */}</Tag>; })()}`
-      : '';
-    const fallbackStyle = styleAttrForElement(entry, props);
-    return visibilityGuard(inner || `${indent(level)}<h2 ${classNameAttr(node.name, entry, props, 2)}${fallbackStyle ? ` ${fallbackStyle}` : ''} />`, props, level);
-  }
-
   const tag = entry.tag;
   if (entry.void) {
     return visibilityGuard(emitVoidInput(node.name, entry, props, level), props, level);

package/renderers/react/paths.ts

@@ -1,10 +1,5 @@
-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');
-}
+export {
+  reactTemplatesDir,
+  reactRuntimeDir,
+  reactStructuralCssPath,
+} from '../../src/lib/rendererPaths.js';

package/renderers/react/preview/components.ts

@@ -0,0 +1,23 @@
+/**
+ * React preview composition root.
+ * Wires vocabulary stubs + renderer runtime + project extensions.
+ * This file belongs to the React renderer, NOT to core src/.
+ */
+import { vocabularyStubs } from './vocabulary.js';
+
+export const {
+  App, Box, Button, Checkbox, Column, Divider, Drawer,
+  Field, Form, Heading, Icon, IconButton, Image, Link,
+  List, ListItem, Modal, Page, Popover, Progress, Radio,
+  Row, SafeArea, ScrollArea, Select, Spacer, Spinner,
+  Stack, Switch, Table, TableCell, TableColumn, TableHeader,
+  TableRow, Text, TextArea, TextInput, Tooltip,
+} = vocabularyStubs;
+
+export {
+  isHidden,
+  toneClass,
+  registerPreviewActions,
+  clearPreviewActions,
+  dispatchPreviewAction,
+} from '../runtime/index.js';

package/renderers/react/preview/index.ts

@@ -0,0 +1,3 @@
+export { startPreview, PreviewApp } from './start.js';
+export type { PreviewOptions } from './start.js';
+export { PreviewShell } from '../../../src/preview/shell.js';

package/renderers/react/preview/start.tsx

@@ -0,0 +1,42 @@
+import type { ComponentType, ReactElement } from 'react';
+import type { ActionHandlers } from '@view-contracts/core';
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import '@view-contracts/theme';
+import { registerPreviewActions } from '../runtime/actionRuntime.js';
+import { PreviewShell } from '../../../src/preview/shell.js';
+
+export interface PreviewOptions<TVm> {
+  View: ComponentType<{ vm: TVm; actions?: ActionHandlers }>;
+  vm: TVm;
+  actions?: ActionHandlers;
+  onAction?: ActionHandlers;
+}
+
+/** Mount a view-contract screen for design preview (views/ + view-contracts packages only). */
+export function startPreview<TVm>(options: PreviewOptions<TVm>): void {
+  const actions = options.actions ?? {};
+  if (options.onAction) {
+    registerPreviewActions({ ...actions, ...options.onAction });
+  } else {
+    registerPreviewActions(actions);
+  }
+
+  const View = options.View;
+  ReactDOM.createRoot(document.getElementById('root') as HTMLElement).render(
+    <React.StrictMode>
+      <PreviewShell>
+        <View vm={options.vm} actions={actions} />
+      </PreviewShell>
+    </React.StrictMode>,
+  );
+}
+
+export function PreviewApp<TVm>(props: PreviewOptions<TVm>): ReactElement {
+  const View = props.View;
+  return (
+    <PreviewShell>
+      <View vm={props.vm} actions={props.actions} />
+    </PreviewShell>
+  );
+}

package/renderers/react/preview/style-helpers.ts

@@ -0,0 +1,5 @@
+/** Preview style helpers — re-export from renderer runtime. */
+export {
+  extensionClassName,
+  resolveExtensionVariant,
+} from '../runtime/style.js';