view-contracts 0.5.8 → 0.5.9

package/README.md

@@ -335,7 +335,7 @@ npm install -D view-contracts
 npx view-contracts build -c view-contracts.config.yaml
 ```
 
-Releases are published to npm when a [GitHub Release](https://github.com/foo-log-inc/view-contracts/releases) is published (`v*` tag).
+**Merging to `main` publishes to npm.** `release.yml` runs on every push to `main`, creates the `v<version>` [GitHub Release](https://github.com/foo-log-inc/view-contracts/releases) when that tag does not exist yet, and `publish.yml` publishes on that Release. There is no manual step between merge and publish, so a merge that carries a version bump ships that version.
 
 ### Bumping the version
 

package/cli-contract.yaml

@@ -3,7 +3,7 @@ cli_contracts: 0.1.0
 
 info:
   title: view-contracts CLI
-  version: 0.5.8
+  version: 0.5.9
   description: >-
     Contract-first UI design toolchain. Compiles restricted view-contract TSX
     to language-neutral View IR and renders platform targets (React, SwiftUI, Compose).

package/dist/types/renderers/compose/elementMap.d.ts

@@ -0,0 +1,10 @@
+export interface ComposeElementConfig {
+    container?: 'group' | 'vstack' | 'hstack' | 'navstack' | 'scrollview' | 'field' | 'cellgroup' | 'tablestack';
+    leaf?: 'text' | 'button' | 'textfield' | 'texteditor' | 'picker' | 'spacer' | 'divider' | 'image' | 'progressview' | 'toggle';
+    spacingProp?: string;
+}
+export interface ComposeElementMap {
+    elements: Record<string, ComposeElementConfig>;
+}
+export declare function loadComposeElementMap(customPath?: string): Promise<ComposeElementMap>;
+export declare function isComposeVocabulary(name: string, map: ComposeElementMap, allowlistExtra?: string[]): boolean;

package/dist/types/renderers/compose/lowering/lowerToCompose.d.ts

@@ -0,0 +1,22 @@
+import type { ThemeIR, TokenIR } from '../../../src/design/types.js';
+import type { IrNode } from '../../../src/ir/types.js';
+import type { ComposeElementMap } from '../elementMap.js';
+export interface ComposeRenderContext {
+    map: ComposeElementMap;
+    theme: ThemeIR;
+    tokens: TokenIR;
+    allowlistExtra: string[];
+    propsRoot?: string;
+    /** How list `.map()` IR nodes should lower inside the current container. */
+    listScope?: 'none' | 'lazyColumn' | 'lazyGrid';
+    /** When true, Text leaves inherit table cell truncation behavior. */
+    cellTextBehavior?: boolean;
+    /** True when rendering inside a verticalScroll container. */
+    inVerticalScroll?: boolean;
+    /** True when rendering TableHeader column cells (compact vertical padding). */
+    inTableHeader?: boolean;
+}
+type NodeRenderer = (node: IrNode, level: number, itemScope?: string) => string;
+export declare function createComposeNodeRenderer(ctx: ComposeRenderContext): NodeRenderer;
+export declare function lowerIrToComposeBody(root: IrNode, ctx: ComposeRenderContext, level?: number): string;
+export {};

package/dist/types/renderers/compose/lowering/modifiers.d.ts

@@ -0,0 +1,36 @@
+import type { VisualPropSet } from '../../../src/renderer/style/mergeVisualProps.js';
+export declare function composeColorExpr(value: string): string | null;
+/** Map DSL justify enum to Compose Row horizontalArrangement (accepts schema + legacy aliases). */
+export declare function composeRowArrangement(justifyLit: unknown, spacing: string): string;
+export declare function composeContentAlignment(value: string): string;
+export interface VisualPropModifierOptions {
+    /** When true, text appearance props target the Text composable directly. */
+    isLeaf?: boolean;
+}
+/**
+ * Convert merged DSL visual props to Compose modifier / text-behavior tags.
+ *
+ * Order for Compose (outside-in, opposite of SwiftUI):
+ *   foreground/font → fillMax frame → shadow → background → clip → border → fixed sizes → padding → margin → opacity → text behavior
+ */
+export declare function visualPropSetToModifiers(merged: VisualPropSet, options?: VisualPropModifierOptions): string[];
+export declare function stripLayoutFrameModifiers(mods: string[]): string[];
+export declare function stripBackgroundModifiers(mods: string[]): string[];
+export declare function stripPaddingModifiers(mods: string[]): string[];
+export declare function stripClipModifiers(mods: string[]): string[];
+export declare function extractPaddingModifiers(mods: string[]): string[];
+export declare function extractClipRadiusDp(mods: string[]): number | null;
+/** Convert extracted `.padding(...)` modifiers to a Compose PaddingValues expression. */
+export declare function paddingModifiersToPaddingValues(mods: string[]): string | null;
+export declare function hasStyledContainerModifiers(mods: string[]): boolean;
+export declare function hasFillMaxHeight(modifiers: string[]): boolean;
+export declare function dedupeModifiers(mods: string[]): string[];
+export declare function applyModifiers(base: string, modifiers: string[]): string;
+export declare function extractTextStyleModifiers(modifiers: string[]): string[];
+export declare function extractTextMaxLines(modifiers: string[]): number | null;
+export declare function extractTextOverflow(modifiers: string[]): string | null;
+export declare function hasTextFillMaxWidth(modifiers: string[]): boolean;
+export declare function extractContentColor(modifiers: string[]): string | null;
+export declare function extractInheritedTextStyleParts(modifiers: string[]): string[];
+export declare function hasWrapContentCenter(modifiers: string[]): boolean;
+export declare function extractApplyVcStyleExpr(modifierExpr: string): string | null;

package/dist/types/renderers/compose/renderComponents.d.ts

@@ -0,0 +1,9 @@
+import type { ViewIrDocument } from '../../src/ir/types.js';
+import type { ThemeIR, TokenIR } from '../../src/design/types.js';
+export interface RenderComposeOptions {
+    theme: ThemeIR;
+    tokens: TokenIR;
+    allowlistExtra?: string[];
+    elementMapPath?: string;
+}
+export declare function renderComposeComponent(doc: ViewIrDocument, options: RenderComposeOptions): Promise<string>;

package/dist/types/renderers/compose/renderRuntime.d.ts

@@ -0,0 +1,10 @@
+import type { ViewBindingsFile, ViewContractsConfig } from '../../src/config.js';
+import type { ThemeIR, TokenIR } from '../../src/design/types.js';
+import type { ViewIrDocument } from '../../src/ir/types.js';
+export declare function renderComposeRuntime(configPath: string, config: ViewContractsConfig, bindings: ViewBindingsFile, design?: {
+    theme: ThemeIR;
+    tokens: TokenIR;
+}, compiledDocs?: {
+    screens: Map<string, ViewIrDocument>;
+    partials: ViewIrDocument[];
+}): Promise<void>;

package/dist/types/renderers/compose/renderTheme.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Generate VcTheme.kt with variant style dictionary for runtime lookup.
+ */
+import type { ThemeIR, TokenIR } from '../../src/design/types.js';
+export declare function renderComposeTheme(theme: ThemeIR, tokens: TokenIR): string;

package/dist/types/renderers/react/elementMap.d.ts

@@ -0,0 +1,32 @@
+/** 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;
+export declare function loadReactElementMap(customPath?: string): Promise<ReactElementMapFile>;
+/** DSL vocabulary element with a React HTML lowering entry (excludes project extensions). */
+export declare function isLowerableVocabularyElement(name: string, map: ReactElementMapFile, allowlistExtra?: string[]): boolean;
+export declare function validateElementMapCoversVocabulary(customPath?: string): Promise<void>;
+export declare const assertElementMapCoversImplementedVocabulary: typeof validateElementMapCoversVocabulary;
+export declare function isVocabularyElement(name: string, map: ReactElementMapFile, allowlistExtra?: string[]): boolean;

package/dist/types/renderers/react/lowering/foldStyle.d.ts

@@ -0,0 +1,7 @@
+import type { IrValue } from '../../../src/ir/types.js';
+import type { ElementMapEntry } from '../elementMap.js';
+import { type FoldedCss } from '../style/foldLiterals.js';
+export declare function collectLiteralStyleProps(props: Record<string, IrValue>): Record<string, unknown>;
+export declare function foldFlexContainer(entry: ElementMapEntry): FoldedCss;
+export declare function styleAttrForElement(entry: ElementMapEntry, props: Record<string, IrValue>): string;
+export { foldLiteralsToCss, foldedStyleToJsx } from '../style/foldLiterals.js';

package/dist/types/renderers/react/lowering/lowerToJsx.d.ts

@@ -0,0 +1,6 @@
+import type { ReactElementMap } from '../elementMap.js';
+import type { IrComponentNode, IrNode, IrValue } from '../../../src/ir/types.js';
+export declare function renderValue(value: IrValue, level: number, castActions?: boolean): string;
+export declare function collectViewRefComponents(node: IrNode, names: Set<string>): void;
+export declare function collectExtensionComponents(node: IrNode, map: ReactElementMap, allowlistExtra: string[], names: Set<string>): void;
+export declare function createNodeRenderer(map: ReactElementMap, allowlistExtra: string[]): (node: IrComponentNode, level: number, itemScope?: string) => string;

package/dist/types/renderers/react/paths.d.ts

@@ -0,0 +1 @@
+export { reactTemplatesDir, reactRuntimeDir, reactStructuralCssPath, } from '../../src/lib/rendererPaths.js';

package/dist/types/renderers/react/renderComponents.d.ts

@@ -0,0 +1,26 @@
+import type { ViewIrDocument } from '../../src/ir/types.js';
+export interface PreviewImportSpecifiers {
+    dispatch: string;
+    styleHelpers: string;
+    contracts: string;
+    extensions: string;
+}
+export interface RenderReactOptions {
+    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 declare function renderReactComponent(doc: ViewIrDocument, options: RenderReactOptions): Promise<string>;
+export declare function renderReactFromIr(doc: ViewIrDocument, outputPath: string, options: RenderReactOptions): Promise<void>;
+/** Render screen + partial modules for preview (single file, no cross-imports). */
+export declare function renderReactPreviewBundle(screen: ViewIrDocument, partials: ViewIrDocument[], options: RenderReactOptions): Promise<string>;
+export declare function partialReactOutputPath(reactDir: string, partial: ViewIrDocument): string;

package/dist/types/renderers/react/renderRuntime.d.ts

@@ -0,0 +1,3 @@
+import type { ViewContractsConfig } from '../../src/config.js';
+/** Emit standalone generated runtime (no preview vocabulary copy; no @view-contracts imports). */
+export declare function renderReactRuntime(configPath: string, config: ViewContractsConfig): Promise<void>;

package/dist/types/renderers/react/runtime/style.d.ts

@@ -0,0 +1,19 @@
+/** Map flex alignment shorthand to CSS align-items / align-self values. */
+export declare function mapAlign(value?: string): string | undefined;
+/** Map flex justification shorthand to CSS justify-content values. */
+export declare function mapJustify(value?: string): string | undefined;
+/** Preview vocabulary helper — production lowered JSX uses visibility guards instead. */
+export declare function isHidden(props: {
+    visible?: boolean;
+    hidden?: boolean;
+}): boolean;
+/** Sample/extension helper for preview tone class names. */
+export declare function toneClass(tone: string | undefined): string;
+/** Resolve theme variant name from variant or legacy tone prop. */
+export declare function resolveExtensionVariant(variant?: string, tone?: string): string;
+/** Build vc-* base + --variant modifier for themed extension components. */
+export declare function extensionClassName(component: string, options?: {
+    variant?: string;
+    tone?: string;
+    extra?: string | false;
+}): string;

package/dist/types/renderers/react/style/foldLiterals.d.ts

@@ -0,0 +1,3 @@
+export type FoldedCss = Record<string, string | number>;
+export declare function foldLiteralsToCss(literals: Record<string, unknown>): FoldedCss;
+export declare function foldedStyleToJsx(style: FoldedCss): string;

package/dist/types/renderers/react/syncGeneratedRuntime.d.ts

@@ -0,0 +1,7 @@
+import type { ViewContractsConfig } from '../../src/config.js';
+/** Remove legacy generated layout under generated/react/. */
+export declare function removeLegacyReactRuntimeLayout(reactDir: string): Promise<void>;
+/** Emit generated/react/runtime.ts — fixed system runtime only (dispatch + style helpers). */
+export declare function writeGeneratedRuntimeBundle(configPath: string, config: ViewContractsConfig, templatesDir?: string): Promise<{
+    runtimePath: string;
+}>;

package/dist/types/renderers/registry.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Unified renderer registry — sole entry point for core → renderer dispatch.
+ * Each export lazily loads its submodule so unused renderers are not pulled in.
+ */
+import type { ViewContractsConfig, ViewBindingsFile } from '../src/config.js';
+import type { ViewIrDocument } from '../src/ir/types.js';
+import type { ThemeIR, TokenIR } from '../src/design/types.js';
+export type { RenderReactOptions } from './react/renderComponents.js';
+export declare function renderReactFromIr(doc: ViewIrDocument, outputPath: string, options: import('./react/renderComponents.js').RenderReactOptions): Promise<void>;
+export declare function renderReactPreviewBundle(screen: ViewIrDocument, partials: ViewIrDocument[], options: import('./react/renderComponents.js').RenderReactOptions): Promise<string>;
+export declare function renderReactRuntime(configPath: string, config: ViewContractsConfig): Promise<void>;
+export declare function renderSwiftUIRuntime(configPath: string, config: ViewContractsConfig, bindings: ViewBindingsFile, design?: {
+    theme: ThemeIR;
+    tokens: TokenIR;
+}, compiledDocs?: {
+    screens: Map<string, ViewIrDocument>;
+    partials: ViewIrDocument[];
+}): Promise<void>;
+export declare function renderSwiftComponent(doc: ViewIrDocument, options: {
+    theme: ThemeIR;
+    tokens: TokenIR;
+    allowlistExtra?: string[];
+}): Promise<string>;
+export declare function renderComposeComponent(doc: ViewIrDocument, options: {
+    theme: ThemeIR;
+    tokens: TokenIR;
+    allowlistExtra?: string[];
+}): Promise<string>;
+export declare function renderComposeRuntime(configPath: string, config: ViewContractsConfig, bindings: ViewBindingsFile, design?: {
+    theme: ThemeIR;
+    tokens: TokenIR;
+}, compiledDocs?: {
+    screens: Map<string, ViewIrDocument>;
+    partials: ViewIrDocument[];
+}): Promise<void>;

package/dist/types/renderers/swiftui/elementMap.d.ts

@@ -0,0 +1,10 @@
+export interface SwiftUIElementConfig {
+    container?: 'group' | 'vstack' | 'hstack' | 'navstack' | 'scrollview' | 'field' | 'cellgroup' | 'tablestack';
+    leaf?: 'text' | 'button' | 'textfield' | 'texteditor' | 'picker' | 'spacer' | 'divider' | 'image' | 'progressview' | 'toggle';
+    spacingProp?: string;
+}
+export interface SwiftUIElementMap {
+    elements: Record<string, SwiftUIElementConfig>;
+}
+export declare function loadSwiftUIElementMap(customPath?: string): Promise<SwiftUIElementMap>;
+export declare function isSwiftUIVocabulary(name: string, map: SwiftUIElementMap, allowlistExtra?: string[]): boolean;

package/dist/types/renderers/swiftui/lowering/lowerToSwiftUI.d.ts

@@ -0,0 +1,15 @@
+import type { ThemeIR, TokenIR } from '../../../src/design/types.js';
+import type { IrNode } from '../../../src/ir/types.js';
+import type { SwiftUIElementMap } from '../elementMap.js';
+export interface SwiftUIRenderContext {
+    map: SwiftUIElementMap;
+    theme: ThemeIR;
+    tokens: TokenIR;
+    allowlistExtra: string[];
+    /** Root prop name for partial scope (e.g. "item" for KpiCard). */
+    propsRoot?: string;
+}
+type NodeRenderer = (node: IrNode, level: number, itemScope?: string) => string;
+export declare function createSwiftUINodeRenderer(ctx: SwiftUIRenderContext): NodeRenderer;
+export declare function lowerIrToSwiftBody(root: IrNode, ctx: SwiftUIRenderContext, level?: number): string;
+export {};

package/dist/types/renderers/swiftui/lowering/modifiers.d.ts

@@ -0,0 +1,16 @@
+import type { VisualPropSet } from '../../../src/renderer/style/mergeVisualProps.js';
+/**
+ * Convert merged DSL visual props to a single SwiftUI modifier chain.
+ *
+ * SwiftUI modifier order for fill elements:
+ *   foreground / font → padding → frame(fill) → background → clipShape → shadow → overlay → frame(fixed) → opacity
+ *
+ * For non-fill elements:
+ *   foreground / font → padding → background → clipShape → shadow → overlay → frame → opacity
+ *
+ * The key insight: .frame(maxWidth: .infinity) MUST come BEFORE .background()
+ * so the background fills the expanded area. Otherwise the background only
+ * covers the natural content width.
+ */
+export declare function visualPropSetToModifiers(merged: VisualPropSet): string[];
+export declare function applyModifiers(body: string, modifiers: string[], indent: number): string;

package/dist/types/renderers/swiftui/renderComponents.d.ts

@@ -0,0 +1,9 @@
+import type { ViewIrDocument } from '../../src/ir/types.js';
+import type { ThemeIR, TokenIR } from '../../src/design/types.js';
+export interface RenderSwiftOptions {
+    theme: ThemeIR;
+    tokens: TokenIR;
+    allowlistExtra?: string[];
+    elementMapPath?: string;
+}
+export declare function renderSwiftComponent(doc: ViewIrDocument, options: RenderSwiftOptions): Promise<string>;

package/dist/types/renderers/swiftui/renderRuntime.d.ts

@@ -0,0 +1,10 @@
+import type { ViewBindingsFile, ViewContractsConfig } from '../../src/config.js';
+import type { ThemeIR, TokenIR } from '../../src/design/types.js';
+import type { ViewIrDocument } from '../../src/ir/types.js';
+export declare function renderSwiftUIRuntime(configPath: string, config: ViewContractsConfig, bindings: ViewBindingsFile, design?: {
+    theme: ThemeIR;
+    tokens: TokenIR;
+}, compiledDocs?: {
+    screens: Map<string, ViewIrDocument>;
+    partials: ViewIrDocument[];
+}): Promise<void>;

package/dist/types/renderers/swiftui/renderTheme.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Generate VcTheme.swift with variant style dictionary for runtime lookup.
+ * Enables dynamic variant resolution (IrConcat / IrBinding) in SwiftUI lowering.
+ */
+import type { ThemeIR, TokenIR } from '../../src/design/types.js';
+export declare function renderSwiftTheme(theme: ThemeIR, tokens: TokenIR): string;

package/dist/types/src/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/types/src/commands/index.d.ts

@@ -0,0 +1,2 @@
+import type { CommandHandlers } from '../generated/cli/program.js';
+export declare const handlers: CommandHandlers;

package/dist/types/src/compiler/compileView.d.ts

@@ -0,0 +1,27 @@
+import type { ViewIrDocument } from '../ir/types.js';
+import type { ExtensionRegistryDocument } from '../extensions/loadExtensions.js';
+export interface CompileViewInput {
+    sourcePath: string;
+    exportName?: string;
+    screenName: string;
+    targets?: string[];
+}
+export interface CompileOptions {
+    /** Project root (the view-contracts.config.yaml directory) that IR source paths are relative to. */
+    projectRoot: string;
+    allowlistExtra?: string[];
+    extensionRegistry?: ExtensionRegistryDocument;
+    targets?: string[];
+}
+export interface CompileViewResult {
+    screen: ViewIrDocument;
+    partials: ViewIrDocument[];
+}
+export declare function compileViewFile(options: CompileViewInput, compileOptions: CompileOptions): Promise<ViewIrDocument>;
+export declare function compileViewFileWithPartials(options: CompileViewInput, compileOptions: CompileOptions): Promise<CompileViewResult>;
+export declare function compileAllViews(views: CompileViewInput[], options: CompileOptions): Promise<ViewIrDocument[]>;
+export declare function compileAllViewsWithPartials(views: CompileViewInput[], options: CompileOptions): Promise<{
+    screens: ViewIrDocument[];
+    partials: ViewIrDocument[];
+}>;
+export declare function partialOutputName(doc: ViewIrDocument): string;

package/dist/types/src/compiler/jsxToIr.d.ts

@@ -0,0 +1,33 @@
+import type { IrBinding, IrNode } from '../ir/types.js';
+export interface CompileContext {
+    vmName: string;
+    scopes: string[];
+    propBindings: Record<string, IrBinding>;
+    errors: string[];
+    warnings: string[];
+    viewImports: Map<string, string>;
+    allowedComponents: Set<string>;
+    /** Source binding from an ancestor Table element, used by TableRow each="..." */
+    tableSource?: IrBinding;
+}
+export interface ParsedViewPartialResult {
+    exportName: string;
+    propsType?: string;
+    propNames: string[];
+    root: IrNode;
+    errors: string[];
+    warnings: string[];
+}
+export interface ParsedView {
+    viewModel: string;
+    exportName: string;
+    root: IrNode;
+    errors: string[];
+    warnings: string[];
+}
+export declare function compileViewSource(source: string, fileName: string, exportName: string, options?: {
+    allowlistExtra?: string[];
+}): ParsedView;
+export declare function compileViewPartialSource(source: string, fileName: string, exportName: string, options?: {
+    allowlistExtra?: string[];
+}): ParsedViewPartialResult;

package/dist/types/src/compiler/viewPartial.d.ts

@@ -0,0 +1,13 @@
+import ts from 'typescript';
+export interface ParsedViewPartial {
+    paramName: string;
+    jsxRoot: ts.JsxChild;
+    /** Destructured prop names from view callback (e.g. ["items"] from ({ items }) =>). */
+    propNames: string[];
+    /** Raw TypeScript type from view<T>() generic, if present. */
+    propsType?: string;
+}
+export declare function parseViewImports(sourceFile: ts.SourceFile, fileDir: string): Map<string, string>;
+export declare function findViewPartialInSource(sourceFile: ts.SourceFile, exportName: string): ParsedViewPartial | null;
+export declare function loadViewPartial(filePath: string, exportName: string): ParsedViewPartial | null;
+export declare function resolveViewModulePath(importPath: string, fileDir: string): string;

package/dist/types/src/config.d.ts

@@ -0,0 +1,77 @@
+export interface ViewBinding {
+    id: string;
+    screenConst: string;
+    screenId: string;
+    screenName: string;
+    route: string;
+    operationId: string;
+    viewModel: string;
+    source: string;
+    exportName: string;
+    targets: string[];
+}
+export interface ViewBindingsFile {
+    version: string;
+    openapi: string;
+    views: ViewBinding[];
+    clientActions?: Array<{
+        name: string;
+        description: string;
+    }>;
+}
+export interface DesignConfig {
+    /** DTCG tokens file (.yaml, .yml, or .json) relative to config file directory. */
+    tokens?: string;
+    /** Theme variants file (.yaml, .yml, or .json) relative to config file directory. */
+    theme?: string;
+    /** Optional project extensions CSS relative to config file directory. */
+    extensionsCss?: string;
+}
+export interface ViewContractsConfig {
+    version: string;
+    openapi: string;
+    bindings: string;
+    microContractsConfig: string;
+    generated: {
+        contractDir: string;
+        actions: string;
+        bridge: string;
+        reactDir: string;
+    };
+    viewsDir: string;
+    /** Generated React runtime bundle (e.g. generated/react/runtime.ts). */
+    runtimeModule?: string;
+    /** @deprecated Use runtimeModule */
+    componentsModule?: string;
+    /** Project React theme CSS path (e.g. generated/react/theme.css). */
+    themeModule?: string;
+    /** Design token / theme inputs (required for build). */
+    design?: DesignConfig;
+    /** Extra component names allowed at compile time (sample/project extensions). */
+    allowlistExtra?: string[];
+    /** Optional custom Handlebars templates directory (relative to project root). */
+    rendererTemplatesDir?: string;
+    /** Optional extension registry YAML (relative to project root). */
+    extensions?: string;
+    /** Preview-only options (not used by production builds). */
+    preview?: {
+        /** Directory of *.mock.yaml files relative to config (default: views/preview). */
+        mocksDir?: string;
+    };
+}
+export declare function discoverConfigPath(startDir?: string): Promise<string | null>;
+export declare function resolveConfigPath(config?: string): Promise<string>;
+export declare function loadConfig(configPath: string): Promise<ViewContractsConfig>;
+/** Resolve config paths relative to the config file directory (project root). */
+export declare function normalizeConfig(configPath: string, config: ViewContractsConfig): ViewContractsConfig;
+export declare function loadBindings(bindingsPath: string): Promise<ViewBindingsFile>;
+export declare function reactOutputPath(config: ViewContractsConfig, view: ViewBinding): string;
+export declare function projectRoot(configPath: string): string;
+export declare function themeCssPath(_configPath: string, config: ViewContractsConfig): string;
+export declare function requireDesignPaths(config: ViewContractsConfig): {
+    tokensPath: string;
+    themePath: string;
+};
+export declare function runtimeImportSpecifier(_configPath: string, _config: ViewContractsConfig, outputPath: string): string;
+/** @deprecated Use runtimeImportSpecifier */
+export declare function componentsImportSpecifier(configPath: string, config: ViewContractsConfig, outputPath: string): string;

package/dist/types/src/design/buildThemeCss.d.ts

@@ -0,0 +1,3 @@
+import type { ViewContractsConfig } from '../config.js';
+/** Merge project design inputs + package structural CSS into theme stylesheet content. */
+export declare function buildThemeCss(config: ViewContractsConfig, configPath: string): Promise<string>;

package/dist/types/src/design/cssEmitUtils.d.ts

@@ -0,0 +1,3 @@
+import type { TokenIR } from './types.js';
+export declare function componentToKebab(name: string): string;
+export declare function tokenCssVar(tokens: TokenIR, ref: string): string;

package/dist/types/src/design/cssPropertyMap.d.ts

@@ -0,0 +1,2 @@
+import type { VariantProperty } from './types.js';
+export declare const CSS_PROPERTY_BY_VARIANT_PROPERTY: Record<VariantProperty, string>;

package/dist/types/src/design/emitDefaultCss.d.ts

@@ -0,0 +1,2 @@
+import type { ThemeIR, TokenIR } from './types.js';
+export declare function emitDefaultCss(tokens: TokenIR, theme: ThemeIR): string;

package/dist/types/src/design/emitTokenCss.d.ts

@@ -0,0 +1,4 @@
+import type { TokenIR } from './types.js';
+export declare function emitTokenCss(ir: TokenIR): string;
+/** Structural CSS only — visual values live in tokens.yaml + theme.yaml (+ extensions.css). */
+export declare function extractStructuralThemeCss(css: string): string;

package/dist/types/src/design/emitVariantCss.d.ts

@@ -0,0 +1,2 @@
+import type { ThemeIR, TokenIR } from './types.js';
+export declare function emitVariantCss(tokens: TokenIR, theme: ThemeIR): string;

package/dist/types/src/design/index.d.ts

@@ -0,0 +1,19 @@
+export { emitTokenCss, extractStructuralThemeCss } from './emitTokenCss.js';
+export { emitDefaultCss } from './emitDefaultCss.js';
+export { emitVariantCss } from './emitVariantCss.js';
+export { loadDesignFile } from './load.js';
+export { parseTheme } from './parseTheme.js';
+export { parseTokens } from './parseTokens.js';
+export { validateDesign, validateTheme } from './validate.js';
+export { validateViewVariants } from './validateViewVariants.js';
+export { validateVcNamespaceCss, validateVcNamespaceSource } from './validateVcNamespace.js';
+export { validateProjectDesign } from './validateProjectDesign.js';
+export { buildThemeCss } from './buildThemeCss.js';
+export { DesignThemeError, DesignTokenError, DesignConstraintError, TOKEN_TYPES, VARIANT_PROPERTIES } from './types.js';
+export type { ThemeIR, TokenEntry, TokenIR, TokenType, VariantProperty, VariantPropertyRef, } from './types.js';
+export declare function loadAndParseTokens(filePath: string): Promise<import("./types.js").TokenIR>;
+export declare function loadAndParseTheme(filePath: string): Promise<import("./types.js").ThemeIR>;
+export declare function loadValidateDesign(tokensPath: string, themePath: string): Promise<{
+    tokenIR: import("./types.js").TokenIR;
+    themeIR: import("./types.js").ThemeIR;
+}>;

package/dist/types/src/design/load.d.ts

@@ -0,0 +1 @@
+export declare function loadDesignFile(filePath: string): Promise<unknown>;

package/dist/types/src/design/parseTheme.d.ts

@@ -0,0 +1,2 @@
+import { type ThemeIR } from './types.js';
+export declare function parseTheme(source: unknown): ThemeIR;

package/dist/types/src/design/parseTokens.d.ts

@@ -0,0 +1,2 @@
+import { type TokenIR } from './types.js';
+export declare function parseTokens(source: unknown): TokenIR;

package/dist/types/src/design/themeElementProperties.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Properties allowed in theme defaults/variants for a vocabulary element.
+ * Returns the intersection of the element's catalog properties and VARIANT_PROPERTIES.
+ */
+export declare function themePropertiesForElement(elementName: string): Set<string>;

package/dist/types/src/design/types.d.ts

@@ -0,0 +1,37 @@
+export declare const TOKEN_TYPES: readonly ["color", "dimension", "shadow", "typography", "layout"];
+export type TokenType = (typeof TOKEN_TYPES)[number];
+export interface TokenEntry {
+    /** Dot-separated path, e.g. `ui.primary` or `semantic.color.text`. */
+    path: string;
+    type: TokenType;
+    /** Resolved CSS-ready value. */
+    value: string;
+    cssVar: string;
+    /** Set when the token was defined via `{group.token}` reference. */
+    ref?: string;
+}
+export interface TokenIR {
+    entries: TokenEntry[];
+}
+export declare class DesignTokenError extends Error {
+    constructor(message: string);
+}
+export declare const VARIANT_PROPERTIES: readonly ["background", "foreground", "radius", "padding", "shadow", "typography", "display", "gridTemplateColumns", "minHeight", "maxWidth", "width", "height", "margin", "border", "borderColor", "flexDirection", "fontWeight", "fontSize", "alignItems", "justifyContent"];
+export type VariantProperty = (typeof VARIANT_PROPERTIES)[number];
+export declare const VARIANT_PROPERTY_ACCEPTS: Record<VariantProperty, readonly TokenType[]>;
+export interface VariantPropertyRef {
+    ref: string;
+    accepts: TokenType[];
+}
+export interface ThemeIR {
+    /** Element-level defaults applied when no variant is specified. */
+    defaults: Record<string, Record<string, VariantPropertyRef>>;
+    variants: Record<string, Record<string, Record<string, VariantPropertyRef>>>;
+}
+export declare class DesignThemeError extends Error {
+    constructor(message: string);
+}
+/** Project design violated a namespace constraint (e.g. hand-written .vc-* outside DSL output). */
+export declare class DesignConstraintError extends Error {
+    constructor(message: string);
+}