@json-render/core 0.4.3 → 0.5.0

package/dist/index.d.mts

@@ -1,7 +1,225 @@
 import { z } from 'zod';
 
 /**
- * Dynamic value - can be a literal or a path reference to data model
+ * Confirmation dialog configuration
+ */
+interface ActionConfirm {
+    title: string;
+    message: string;
+    confirmLabel?: string;
+    cancelLabel?: string;
+    variant?: "default" | "danger";
+}
+/**
+ * Action success handler
+ */
+type ActionOnSuccess = {
+    navigate: string;
+} | {
+    set: Record<string, unknown>;
+} | {
+    action: string;
+};
+/**
+ * Action error handler
+ */
+type ActionOnError = {
+    set: Record<string, unknown>;
+} | {
+    action: string;
+};
+/**
+ * Action binding — maps an event to an action invocation.
+ *
+ * Used inside the `on` field of a UIElement:
+ * ```json
+ * { "on": { "press": { "action": "setState", "params": { "path": "/x", "value": 1 } } } }
+ * ```
+ */
+interface ActionBinding {
+    /** Action name (must be in catalog) */
+    action: string;
+    /** Parameters to pass to the action handler */
+    params?: Record<string, DynamicValue>;
+    /** Confirmation dialog before execution */
+    confirm?: ActionConfirm;
+    /** Handler after successful execution */
+    onSuccess?: ActionOnSuccess;
+    /** Handler after failed execution */
+    onError?: ActionOnError;
+}
+/**
+ * @deprecated Use ActionBinding instead
+ */
+type Action = ActionBinding;
+/**
+ * Schema for action confirmation
+ */
+declare const ActionConfirmSchema: z.ZodObject<{
+    title: z.ZodString;
+    message: z.ZodString;
+    confirmLabel: z.ZodOptional<z.ZodString>;
+    cancelLabel: z.ZodOptional<z.ZodString>;
+    variant: z.ZodOptional<z.ZodEnum<{
+        default: "default";
+        danger: "danger";
+    }>>;
+}, z.core.$strip>;
+/**
+ * Schema for success handlers
+ */
+declare const ActionOnSuccessSchema: z.ZodUnion<readonly [z.ZodObject<{
+    navigate: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    set: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>, z.ZodObject<{
+    action: z.ZodString;
+}, z.core.$strip>]>;
+/**
+ * Schema for error handlers
+ */
+declare const ActionOnErrorSchema: z.ZodUnion<readonly [z.ZodObject<{
+    set: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>, z.ZodObject<{
+    action: z.ZodString;
+}, z.core.$strip>]>;
+/**
+ * Full action binding schema
+ */
+declare const ActionBindingSchema: z.ZodObject<{
+    action: z.ZodString;
+    params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull, z.ZodObject<{
+        path: z.ZodString;
+    }, z.core.$strip>]>>>;
+    confirm: z.ZodOptional<z.ZodObject<{
+        title: z.ZodString;
+        message: z.ZodString;
+        confirmLabel: z.ZodOptional<z.ZodString>;
+        cancelLabel: z.ZodOptional<z.ZodString>;
+        variant: z.ZodOptional<z.ZodEnum<{
+            default: "default";
+            danger: "danger";
+        }>>;
+    }, z.core.$strip>>;
+    onSuccess: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+        navigate: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        set: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$strip>, z.ZodObject<{
+        action: z.ZodString;
+    }, z.core.$strip>]>>;
+    onError: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+        set: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$strip>, z.ZodObject<{
+        action: z.ZodString;
+    }, z.core.$strip>]>>;
+}, z.core.$strip>;
+/**
+ * @deprecated Use ActionBindingSchema instead
+ */
+declare const ActionSchema: z.ZodObject<{
+    action: z.ZodString;
+    params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull, z.ZodObject<{
+        path: z.ZodString;
+    }, z.core.$strip>]>>>;
+    confirm: z.ZodOptional<z.ZodObject<{
+        title: z.ZodString;
+        message: z.ZodString;
+        confirmLabel: z.ZodOptional<z.ZodString>;
+        cancelLabel: z.ZodOptional<z.ZodString>;
+        variant: z.ZodOptional<z.ZodEnum<{
+            default: "default";
+            danger: "danger";
+        }>>;
+    }, z.core.$strip>>;
+    onSuccess: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+        navigate: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        set: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$strip>, z.ZodObject<{
+        action: z.ZodString;
+    }, z.core.$strip>]>>;
+    onError: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+        set: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$strip>, z.ZodObject<{
+        action: z.ZodString;
+    }, z.core.$strip>]>>;
+}, z.core.$strip>;
+/**
+ * Action handler function signature
+ */
+type ActionHandler<TParams = Record<string, unknown>, TResult = unknown> = (params: TParams) => Promise<TResult> | TResult;
+/**
+ * Action definition in catalog
+ */
+interface ActionDefinition<TParams = Record<string, unknown>> {
+    /** Zod schema for params validation */
+    params?: z.ZodType<TParams>;
+    /** Description for AI */
+    description?: string;
+}
+/**
+ * Resolved action with all dynamic values resolved
+ */
+interface ResolvedAction {
+    action: string;
+    params: Record<string, unknown>;
+    confirm?: ActionConfirm;
+    onSuccess?: ActionOnSuccess;
+    onError?: ActionOnError;
+}
+/**
+ * Resolve all dynamic values in an action binding
+ */
+declare function resolveAction(binding: ActionBinding, stateModel: StateModel): ResolvedAction;
+/**
+ * Interpolate ${path} expressions in a string
+ */
+declare function interpolateString(template: string, stateModel: StateModel): string;
+/**
+ * Context for action execution
+ */
+interface ActionExecutionContext {
+    /** The resolved action */
+    action: ResolvedAction;
+    /** The action handler from the host */
+    handler: ActionHandler;
+    /** Function to update state model */
+    setState: (path: string, value: unknown) => void;
+    /** Function to navigate */
+    navigate?: (path: string) => void;
+    /** Function to execute another action */
+    executeAction?: (name: string) => Promise<void>;
+}
+/**
+ * Execute an action with all callbacks
+ */
+declare function executeAction(ctx: ActionExecutionContext): Promise<void>;
+/**
+ * Helper to create action bindings
+ */
+declare const actionBinding: {
+    /** Create a simple action binding */
+    simple: (actionName: string, params?: Record<string, DynamicValue>) => ActionBinding;
+    /** Create an action binding with confirmation */
+    withConfirm: (actionName: string, confirm: ActionConfirm, params?: Record<string, DynamicValue>) => ActionBinding;
+    /** Create an action binding with success handler */
+    withSuccess: (actionName: string, onSuccess: ActionOnSuccess, params?: Record<string, DynamicValue>) => ActionBinding;
+};
+/**
+ * @deprecated Use actionBinding instead
+ */
+declare const action: {
+    /** Create a simple action binding */
+    simple: (actionName: string, params?: Record<string, DynamicValue>) => ActionBinding;
+    /** Create an action binding with confirmation */
+    withConfirm: (actionName: string, confirm: ActionConfirm, params?: Record<string, DynamicValue>) => ActionBinding;
+    /** Create an action binding with success handler */
+    withSuccess: (actionName: string, onSuccess: ActionOnSuccess, params?: Record<string, DynamicValue>) => ActionBinding;
+};
+
+/**
+ * Dynamic value - can be a literal or a path reference to state model
  */
 type DynamicValue<T = unknown> = T | {
     path: string;
@@ -37,18 +255,32 @@ declare const DynamicBooleanSchema: z.ZodUnion<readonly [z.ZodBoolean, z.ZodObje
  * Base UI element structure for v2
  */
 interface UIElement<T extends string = string, P = Record<string, unknown>> {
-    /** Unique key for reconciliation */
-    key: string;
     /** Component type from the catalog */
     type: T;
     /** Component props */
     props: P;
     /** Child element keys (flat structure) */
     children?: string[];
-    /** Parent element key (null for root) */
-    parentKey?: string | null;
     /** Visibility condition */
     visible?: VisibilityCondition;
+    /** Event bindings — maps event names to action bindings */
+    on?: Record<string, ActionBinding | ActionBinding[]>;
+    /** Repeat children once per item in a state array */
+    repeat?: {
+        path: string;
+        key?: string;
+    };
+}
+/**
+ * Element with key and parentKey for use with flatToTree.
+ * When elements are in an array (not a keyed map), key and parentKey
+ * are needed to establish identity and parent-child relationships.
+ */
+interface FlatElement<T extends string = string, P = Record<string, unknown>> extends UIElement<T, P> {
+    /** Unique key identifying this element */
+    key: string;
+    /** Parent element key (null for root) */
+    parentKey?: string | null;
 }
 /**
  * Visibility condition types
@@ -90,6 +322,9 @@ interface Spec {
     root: string;
     /** Flat map of elements by key */
     elements: Record<string, UIElement>;
+    /** Optional initial state to seed the state model.
+     *  Components using statePath will read from / write to this state. */
+    state?: Record<string, unknown>;
 }
 /**
  * Auth state for visibility evaluation
@@ -99,9 +334,9 @@ interface AuthState {
     user?: Record<string, unknown>;
 }
 /**
- * Data model type
+ * State model type
  */
-type DataModel = Record<string, unknown>;
+type StateModel = Record<string, unknown>;
 /**
  * Component schema definition using Zod
  */
@@ -111,30 +346,45 @@ type ComponentSchema = z.ZodType<Record<string, unknown>>;
  */
 type ValidationMode = "strict" | "warn" | "ignore";
 /**
- * JSON patch operation types
+ * JSON patch operation types (RFC 6902)
  */
-type PatchOp = "add" | "remove" | "replace" | "set";
+type PatchOp = "add" | "remove" | "replace" | "move" | "copy" | "test";
 /**
- * JSON patch operation
+ * JSON patch operation (RFC 6902)
  */
 interface JsonPatch {
     op: PatchOp;
     path: string;
+    /** Required for add, replace, test */
     value?: unknown;
+    /** Required for move, copy (source location) */
+    from?: string;
 }
 /**
- * Resolve a dynamic value against a data model
+ * Resolve a dynamic value against a state model
  */
-declare function resolveDynamicValue<T>(value: DynamicValue<T>, dataModel: DataModel): T | undefined;
+declare function resolveDynamicValue<T>(value: DynamicValue<T>, stateModel: StateModel): T | undefined;
 /**
- * Get a value from an object by JSON Pointer path
+ * Get a value from an object by JSON Pointer path (RFC 6901)
  */
 declare function getByPath(obj: unknown, path: string): unknown;
 /**
- * Set a value in an object by JSON Pointer path.
+ * Set a value in an object by JSON Pointer path (RFC 6901).
  * Automatically creates arrays when the path segment is a numeric index.
  */
 declare function setByPath(obj: Record<string, unknown>, path: string, value: unknown): void;
+/**
+ * Add a value per RFC 6902 "add" semantics.
+ * For objects: create-or-replace the member.
+ * For arrays: insert before the given index, or append if "-".
+ */
+declare function addByPath(obj: Record<string, unknown>, path: string, value: unknown): void;
+/**
+ * Remove a value per RFC 6902 "remove" semantics.
+ * For objects: delete the property.
+ * For arrays: splice out the element at the given index.
+ */
+declare function removeByPath(obj: Record<string, unknown>, path: string): void;
 /**
  * Find a form value from params and/or data.
  * Useful in action handlers to locate form input values regardless of path format.
@@ -165,8 +415,12 @@ type SpecStreamLine = JsonPatch;
  */
 declare function parseSpecStreamLine(line: string): SpecStreamLine | null;
 /**
- * Apply a single SpecStream patch to an object.
+ * Apply a single RFC 6902 JSON Patch operation to an object.
  * Mutates the object in place.
+ *
+ * Supports all six RFC 6902 operations: add, remove, replace, move, copy, test.
+ *
+ * @throws {Error} If a "test" operation fails (value mismatch).
  */
 declare function applySpecStreamPatch<T extends Record<string, unknown>>(obj: T, patch: SpecStreamLine): T;
 /**
@@ -174,8 +428,8 @@ declare function applySpecStreamPatch<T extends Record<string, unknown>>(obj: T,
  * Each line should be a patch operation.
  *
  * @example
- * const stream = `{"op":"set","path":"/name","value":"Alice"}
- * {"op":"set","path":"/age","value":30}`;
+ * const stream = `{"op":"add","path":"/name","value":"Alice"}
+ * {"op":"add","path":"/age","value":30}`;
  * const result = compileSpecStream(stream);
  * // { name: "Alice", age: 30 }
  */
@@ -245,7 +499,7 @@ declare const VisibilityConditionSchema: z.ZodType<VisibilityCondition>;
  * Context for evaluating visibility
  */
 interface VisibilityContext {
-    dataModel: DataModel;
+    stateModel: StateModel;
     authState?: AuthState;
 }
 /**
@@ -295,171 +549,29 @@ declare const visibility: {
 };
 
 /**
- * Confirmation dialog configuration
- */
-interface ActionConfirm {
-    title: string;
-    message: string;
-    confirmLabel?: string;
-    cancelLabel?: string;
-    variant?: "default" | "danger";
-}
-/**
- * Action success handler
- */
-type ActionOnSuccess = {
-    navigate: string;
-} | {
-    set: Record<string, unknown>;
-} | {
-    action: string;
-};
-/**
- * Action error handler
+ * A prop expression that resolves to a value based on state.
+ *
+ * - `{ $path: string }` reads a value from the state model
+ * - `{ $cond, $then, $else }` conditionally picks a value
+ * - Any other value is a literal (passthrough)
  */
-type ActionOnError = {
-    set: Record<string, unknown>;
+type PropExpression<T = unknown> = T | {
+    $path: string;
 } | {
-    action: string;
+    $cond: VisibilityCondition;
+    $then: PropExpression<T>;
+    $else: PropExpression<T>;
 };
 /**
- * Rich action definition
- */
-interface Action {
-    /** Action name (must be in catalog) */
-    name: string;
-    /** Parameters to pass to the action handler */
-    params?: Record<string, DynamicValue>;
-    /** Confirmation dialog before execution */
-    confirm?: ActionConfirm;
-    /** Handler after successful execution */
-    onSuccess?: ActionOnSuccess;
-    /** Handler after failed execution */
-    onError?: ActionOnError;
-}
-/**
- * Schema for action confirmation
- */
-declare const ActionConfirmSchema: z.ZodObject<{
-    title: z.ZodString;
-    message: z.ZodString;
-    confirmLabel: z.ZodOptional<z.ZodString>;
-    cancelLabel: z.ZodOptional<z.ZodString>;
-    variant: z.ZodOptional<z.ZodEnum<{
-        default: "default";
-        danger: "danger";
-    }>>;
-}, z.core.$strip>;
-/**
- * Schema for success handlers
- */
-declare const ActionOnSuccessSchema: z.ZodUnion<readonly [z.ZodObject<{
-    navigate: z.ZodString;
-}, z.core.$strip>, z.ZodObject<{
-    set: z.ZodRecord<z.ZodString, z.ZodUnknown>;
-}, z.core.$strip>, z.ZodObject<{
-    action: z.ZodString;
-}, z.core.$strip>]>;
-/**
- * Schema for error handlers
- */
-declare const ActionOnErrorSchema: z.ZodUnion<readonly [z.ZodObject<{
-    set: z.ZodRecord<z.ZodString, z.ZodUnknown>;
-}, z.core.$strip>, z.ZodObject<{
-    action: z.ZodString;
-}, z.core.$strip>]>;
-/**
- * Full action schema
- */
-declare const ActionSchema: z.ZodObject<{
-    name: z.ZodString;
-    params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull, z.ZodObject<{
-        path: z.ZodString;
-    }, z.core.$strip>]>>>;
-    confirm: z.ZodOptional<z.ZodObject<{
-        title: z.ZodString;
-        message: z.ZodString;
-        confirmLabel: z.ZodOptional<z.ZodString>;
-        cancelLabel: z.ZodOptional<z.ZodString>;
-        variant: z.ZodOptional<z.ZodEnum<{
-            default: "default";
-            danger: "danger";
-        }>>;
-    }, z.core.$strip>>;
-    onSuccess: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
-        navigate: z.ZodString;
-    }, z.core.$strip>, z.ZodObject<{
-        set: z.ZodRecord<z.ZodString, z.ZodUnknown>;
-    }, z.core.$strip>, z.ZodObject<{
-        action: z.ZodString;
-    }, z.core.$strip>]>>;
-    onError: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
-        set: z.ZodRecord<z.ZodString, z.ZodUnknown>;
-    }, z.core.$strip>, z.ZodObject<{
-        action: z.ZodString;
-    }, z.core.$strip>]>>;
-}, z.core.$strip>;
-/**
- * Action handler function signature
- */
-type ActionHandler<TParams = Record<string, unknown>, TResult = unknown> = (params: TParams) => Promise<TResult> | TResult;
-/**
- * Action definition in catalog
- */
-interface ActionDefinition<TParams = Record<string, unknown>> {
-    /** Zod schema for params validation */
-    params?: z.ZodType<TParams>;
-    /** Description for AI */
-    description?: string;
-}
-/**
- * Resolved action with all dynamic values resolved
- */
-interface ResolvedAction {
-    name: string;
-    params: Record<string, unknown>;
-    confirm?: ActionConfirm;
-    onSuccess?: ActionOnSuccess;
-    onError?: ActionOnError;
-}
-/**
- * Resolve all dynamic values in an action
+ * Resolve a single prop value that may contain expressions.
+ * Recursively resolves $path and $cond/$then/$else expressions.
  */
-declare function resolveAction(action: Action, dataModel: DataModel): ResolvedAction;
+declare function resolvePropValue(value: unknown, ctx: VisibilityContext): unknown;
 /**
- * Interpolate ${path} expressions in a string
- */
-declare function interpolateString(template: string, dataModel: DataModel): string;
-/**
- * Context for action execution
+ * Resolve all prop values in an element's props object.
+ * Returns a new props object with all expressions resolved.
  */
-interface ActionExecutionContext {
-    /** The resolved action */
-    action: ResolvedAction;
-    /** The action handler from the host */
-    handler: ActionHandler;
-    /** Function to update data model */
-    setData: (path: string, value: unknown) => void;
-    /** Function to navigate */
-    navigate?: (path: string) => void;
-    /** Function to execute another action */
-    executeAction?: (name: string) => Promise<void>;
-}
-/**
- * Execute an action with all callbacks
- */
-declare function executeAction(ctx: ActionExecutionContext): Promise<void>;
-/**
- * Helper to create actions
- */
-declare const action: {
-    /** Create a simple action */
-    simple: (name: string, params?: Record<string, DynamicValue>) => Action;
-    /** Create an action with confirmation */
-    withConfirm: (name: string, confirm: ActionConfirm, params?: Record<string, DynamicValue>) => Action;
-    /** Create an action with success handler */
-    withSuccess: (name: string, onSuccess: ActionOnSuccess, params?: Record<string, DynamicValue>) => Action;
-};
+declare function resolveElementProps(props: Record<string, unknown>, ctx: VisibilityContext): Record<string, unknown>;
 
 /**
  * Validation check definition
@@ -551,7 +663,7 @@ interface ValidationContext {
     /** Current value to validate */
     value: unknown;
     /** Full data model for resolving paths */
-    dataModel: DataModel;
+    stateModel: StateModel;
     /** Custom validation functions from catalog */
     customFunctions?: Record<string, ValidationFunction>;
 }
@@ -582,6 +694,81 @@ declare const check: {
     matches: (otherPath: string, message?: string) => ValidationCheck;
 };
 
+/**
+ * Severity level for validation issues.
+ */
+type SpecIssueSeverity = "error" | "warning";
+/**
+ * A single validation issue found in a spec.
+ */
+interface SpecIssue {
+    /** Severity: errors should be fixed, warnings are informational */
+    severity: SpecIssueSeverity;
+    /** Human-readable description of the issue */
+    message: string;
+    /** The element key where the issue was found (if applicable) */
+    elementKey?: string;
+    /** Machine-readable issue code for programmatic handling */
+    code: "missing_root" | "root_not_found" | "missing_child" | "visible_in_props" | "orphaned_element" | "empty_spec" | "on_in_props" | "repeat_in_props";
+}
+/**
+ * Result of spec structural validation.
+ */
+interface SpecValidationIssues {
+    /** Whether the spec passed validation (no errors; warnings are OK) */
+    valid: boolean;
+    /** List of issues found */
+    issues: SpecIssue[];
+}
+/**
+ * Options for validateSpec.
+ */
+interface ValidateSpecOptions {
+    /**
+     * Whether to check for orphaned elements (elements not reachable from root).
+     * Defaults to false since orphans are harmless (just unused).
+     */
+    checkOrphans?: boolean;
+}
+/**
+ * Validate a spec for structural integrity.
+ *
+ * Checks for common AI-generation errors:
+ * - Missing or empty root
+ * - Root element not found in elements map
+ * - Children referencing non-existent elements
+ * - `visible` placed inside `props` instead of on the element
+ * - Orphaned elements (optional)
+ *
+ * @example
+ * ```ts
+ * const result = validateSpec(spec);
+ * if (!result.valid) {
+ *   console.log("Spec errors:", result.issues);
+ * }
+ * ```
+ */
+declare function validateSpec(spec: Spec, options?: ValidateSpecOptions): SpecValidationIssues;
+/**
+ * Auto-fix common spec issues in-place and return a corrected copy.
+ *
+ * Currently fixes:
+ * - `visible` inside `props` → moved to element level
+ * - `on` inside `props` → moved to element level
+ * - `repeat` inside `props` → moved to element level
+ *
+ * Returns the fixed spec and a list of fixes applied.
+ */
+declare function autoFixSpec(spec: Spec): {
+    spec: Spec;
+    fixes: string[];
+};
+/**
+ * Format validation issues into a human-readable string suitable for
+ * inclusion in a repair prompt sent back to the AI.
+ */
+declare function formatSpecIssues(issues: SpecIssue[]): string;
+
 /**
  * Schema builder primitives
  */
@@ -638,6 +825,8 @@ interface Schema<TDef extends SchemaDefinition = SchemaDefinition> {
     readonly definition: TDef;
     /** Custom prompt template for this schema */
     readonly promptTemplate?: PromptTemplate;
+    /** Default rules baked into the schema (injected before customRules) */
+    readonly defaultRules?: string[];
     /** Create a catalog from this schema */
     createCatalog<TCatalog extends InferCatalogInput<TDef["catalog"]>>(catalog: TCatalog): Catalog$1<TDef, TCatalog>;
 }
@@ -698,6 +887,8 @@ type PromptTemplate<TCatalog = unknown> = (context: PromptContext<TCatalog>) =>
 interface SchemaOptions<TCatalog = unknown> {
     /** Custom prompt template for this schema */
     promptTemplate?: PromptTemplate<TCatalog>;
+    /** Default rules baked into the schema (injected before customRules in prompts) */
+    defaultRules?: string[];
 }
 /**
  * Spec validation result
@@ -776,6 +967,41 @@ declare function defineSchema<TDef extends SchemaDefinition>(builder: (s: Schema
  */
 declare function defineCatalog<TDef extends SchemaDefinition, TCatalog extends InferCatalogInput<TDef["catalog"]>>(schema: Schema<TDef>, catalog: TCatalog): Catalog$1<TDef, TCatalog>;
 
+/**
+ * Options for building a user prompt.
+ */
+interface UserPromptOptions {
+    /** The user's text prompt */
+    prompt: string;
+    /** Existing spec to refine (triggers patch-only mode) */
+    currentSpec?: Spec | null;
+    /** Runtime state context to include */
+    state?: Record<string, unknown> | null;
+    /** Maximum length for the user's text prompt (applied before wrapping) */
+    maxPromptLength?: number;
+}
+/**
+ * Build a user prompt for AI generation.
+ *
+ * Handles common patterns that every consuming app needs:
+ * - Truncating the user's prompt to a max length
+ * - Including the current spec for refinement (patch-only mode)
+ * - Including runtime state context
+ *
+ * @example
+ * ```ts
+ * // Fresh generation
+ * buildUserPrompt({ prompt: "create a todo app" })
+ *
+ * // Refinement with existing spec
+ * buildUserPrompt({ prompt: "add a dark mode toggle", currentSpec: spec })
+ *
+ * // With state context
+ * buildUserPrompt({ prompt: "show my data", state: { todos: [] } })
+ * ```
+ */
+declare function buildUserPrompt(options: UserPromptOptions): string;
+
 /**
  * Component definition with visibility and validation support
  */
@@ -874,4 +1100,4 @@ interface SystemPromptOptions {
  */
 declare function generateSystemPrompt<TComponents extends Record<string, ComponentDefinition>, TActions extends Record<string, ActionDefinition>, TFunctions extends Record<string, ValidationFunction>>(catalog: Catalog<TComponents, TActions, TFunctions>, options?: SystemPromptOptions): string;
 
-export { type Action, type ActionConfirm, ActionConfirmSchema, type ActionDefinition, type ActionExecutionContext, type ActionHandler, type ActionOnError, ActionOnErrorSchema, type ActionOnSuccess, ActionOnSuccessSchema, ActionSchema, type AuthState, type Catalog$1 as Catalog, type CatalogConfig, type ComponentDefinition, type ComponentSchema, type DataModel, type DynamicBoolean, DynamicBooleanSchema, type DynamicNumber, DynamicNumberSchema, type DynamicString, DynamicStringSchema, type DynamicValue, DynamicValueSchema, type InferActionParams, type InferCatalogActions, type InferCatalogComponentProps, type InferCatalogComponents, type InferCatalogInput, type InferComponentProps, type InferSpec, type JsonPatch, type Catalog as LegacyCatalog, type LogicExpression, LogicExpressionSchema, type PatchOp, type PromptContext, type PromptOptions, type PromptTemplate, type ResolvedAction, type Schema, type SchemaBuilder, type SchemaDefinition, type SchemaOptions, type SchemaType, type Spec, type SpecStreamCompiler, type SpecStreamLine, type SpecValidationResult, type SystemPromptOptions, type UIElement, type ValidationCheck, type ValidationCheckResult, ValidationCheckSchema, type ValidationConfig, ValidationConfigSchema, type ValidationContext, type ValidationFunction, type ValidationFunctionDefinition, type ValidationMode, type ValidationResult, type VisibilityCondition, VisibilityConditionSchema, type VisibilityContext, action, applySpecStreamPatch, builtInValidationFunctions, check, compileSpecStream, createCatalog, createSpecStreamCompiler, defineCatalog, defineSchema, evaluateLogicExpression, evaluateVisibility, executeAction, findFormValue, generateCatalogPrompt, generateSystemPrompt, getByPath, interpolateString, parseSpecStreamLine, resolveAction, resolveDynamicValue, runValidation, runValidationCheck, setByPath, visibility };
+export { type Action, type ActionBinding, ActionBindingSchema, type ActionConfirm, ActionConfirmSchema, type ActionDefinition, type ActionExecutionContext, type ActionHandler, type ActionOnError, ActionOnErrorSchema, type ActionOnSuccess, ActionOnSuccessSchema, ActionSchema, type AuthState, type Catalog$1 as Catalog, type CatalogConfig, type ComponentDefinition, type ComponentSchema, type DynamicBoolean, DynamicBooleanSchema, type DynamicNumber, DynamicNumberSchema, type DynamicString, DynamicStringSchema, type DynamicValue, DynamicValueSchema, type FlatElement, type InferActionParams, type InferCatalogActions, type InferCatalogComponentProps, type InferCatalogComponents, type InferCatalogInput, type InferComponentProps, type InferSpec, type JsonPatch, type Catalog as LegacyCatalog, type LogicExpression, LogicExpressionSchema, type PatchOp, type PromptContext, type PromptOptions, type PromptTemplate, type PropExpression, type ResolvedAction, type Schema, type SchemaBuilder, type SchemaDefinition, type SchemaOptions, type SchemaType, type Spec, type SpecIssue, type SpecIssueSeverity, type SpecStreamCompiler, type SpecStreamLine, type SpecValidationIssues, type SpecValidationResult, type StateModel, type SystemPromptOptions, type UIElement, type UserPromptOptions, type ValidateSpecOptions, type ValidationCheck, type ValidationCheckResult, ValidationCheckSchema, type ValidationConfig, ValidationConfigSchema, type ValidationContext, type ValidationFunction, type ValidationFunctionDefinition, type ValidationMode, type ValidationResult, type VisibilityCondition, VisibilityConditionSchema, type VisibilityContext, action, actionBinding, addByPath, applySpecStreamPatch, autoFixSpec, buildUserPrompt, builtInValidationFunctions, check, compileSpecStream, createCatalog, createSpecStreamCompiler, defineCatalog, defineSchema, evaluateLogicExpression, evaluateVisibility, executeAction, findFormValue, formatSpecIssues, generateCatalogPrompt, generateSystemPrompt, getByPath, interpolateString, parseSpecStreamLine, removeByPath, resolveAction, resolveDynamicValue, resolveElementProps, resolvePropValue, runValidation, runValidationCheck, setByPath, validateSpec, visibility };