@positronic/core 0.0.52 → 0.0.53

package/dist/types/index.d.ts

@@ -1,11 +1,13 @@
-export { Brain, brain, DEFAULT_ENV } from './dsl/brain.js';
+export { Brain, brain } from './dsl/brain.js';
 export { BrainRunner } from './dsl/brain-runner.js';
+export { createBrain } from './dsl/create-brain.js';
+export type { CreateBrainConfig } from './dsl/create-brain.js';
 export { STATUS, BRAIN_EVENTS } from './dsl/constants.js';
 export type { Adapter } from './adapters/types.js';
-export type { BrainEvent, SerializedStep, InitialRunParams, RerunParams, BrainStartEvent, BrainCompleteEvent, BrainErrorEvent, StepStatusEvent, StepStartedEvent, StepCompletedEvent, StepRetryEvent, BrainStructure, BrainFactory, } from './dsl/brain.js';
+export type { BrainEvent, SerializedStep, InitialRunParams, RerunParams, BrainStartEvent, BrainCompleteEvent, BrainErrorEvent, StepStatusEvent, StepStartedEvent, StepCompletedEvent, StepRetryEvent, BrainStructure, BrainConfig, GeneratedPage, } from './dsl/brain.js';
 export type { ObjectGenerator, Message, ToolMessage } from './clients/types.js';
-export type { State, RuntimeEnv, Secrets, LoopTool, LoopConfig, LoopMessage, LoopToolWaitFor, ExtractTerminalInput, } from './dsl/types.js';
-export { createPatch, applyPatches } from './dsl/json-patch.js';
+export type { State, RuntimeEnv, Secrets, AgentTool, AgentConfig, AgentMessage, AgentToolWaitFor, ExtractTerminalInput, RetryConfig, } from './dsl/types.js';
+export { applyPatches } from './dsl/json-patch.js';
 export { z } from 'zod';
 export type { ResourceLoader } from './resources/resource-loader.js';
 export { createResources, type Resources } from './resources/resources.js';
@@ -14,9 +16,9 @@ export type { WebhookFunction, WebhookRegistration } from './dsl/webhook.js';
 export type { PagesService, Page, PageCreateOptions } from './dsl/pages.js';
 export type { Manifest as ResourceManifest, Entry as ResourceEntry, ResourceType, } from './resources/resources.js';
 export { RESOURCE_TYPES } from './resources/resources.js';
-export type { LoopStartEvent, LoopIterationEvent, LoopToolCallEvent, LoopToolResultEvent, LoopAssistantMessageEvent, LoopCompleteEvent, LoopTokenLimitEvent, LoopWebhookEvent, WebhookResponseEvent, HeartbeatEvent, } from './dsl/brain.js';
-export type { LoopResumeContext } from './dsl/loop-messages.js';
-export { reconstructLoopContext } from './dsl/loop-messages.js';
+export type { AgentStartEvent, AgentIterationEvent, AgentToolCallEvent, AgentToolResultEvent, AgentAssistantMessageEvent, AgentCompleteEvent, AgentTokenLimitEvent, AgentWebhookEvent, WebhookResponseEvent, } from './dsl/definitions/events.js';
+export { defaultTools, generateUI } from './tools/index.js';
+export type { UIComponent } from './ui/types.js';
 export { createBrainExecutionMachine, createBrainMachine, sendEvent, getDepth, isTopLevel, getCurrentStep, getBrainStack, getBrainRunId, getExecutionState, getPendingWebhooks, getError, getCompletedSteps, } from './dsl/brain-state-machine.js';
 export type { BrainStateMachine, BrainExecutionContext, BrainStackEntry, RunningBrain, StepInfo, ExecutionState, CreateMachineOptions, } from './dsl/brain-state-machine.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC3D,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAC1D,YAAY,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AACnD,YAAY,EACV,UAAU,EACV,cAAc,EACd,gBAAgB,EAChB,WAAW,EACX,eAAe,EACf,kBAAkB,EAClB,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,kBAAkB,EAClB,cAAc,EACd,cAAc,EACd,YAAY,GACb,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,eAAe,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAChF,YAAY,EACV,KAAK,EACL,UAAU,EACV,OAAO,EACP,QAAQ,EACR,UAAU,EACV,WAAW,EACX,eAAe,EACf,oBAAoB,GACrB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAMhE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,YAAY,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AACrE,OAAO,EAAE,eAAe,EAAE,KAAK,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAC3E,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,YAAY,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAC7E,YAAY,EAAE,YAAY,EAAE,IAAI,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAC5E,YAAY,EACV,QAAQ,IAAI,gBAAgB,EAC5B,KAAK,IAAI,aAAa,EACtB,YAAY,GACb,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAG1D,YAAY,EACV,cAAc,EACd,kBAAkB,EAClB,iBAAiB,EACjB,mBAAmB,EACnB,yBAAyB,EACzB,iBAAiB,EACjB,mBAAmB,EACnB,gBAAgB,EAChB,oBAAoB,EACpB,cAAc,GACf,MAAM,gBAAgB,CAAC;AAGxB,YAAY,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAGhE,OAAO,EACL,2BAA2B,EAC3B,kBAAkB,EAClB,SAAS,EACT,QAAQ,EACR,UAAU,EACV,cAAc,EACd,aAAa,EACb,aAAa,EACb,iBAAiB,EACjB,kBAAkB,EAClB,QAAQ,EACR,iBAAiB,GAClB,MAAM,8BAA8B,CAAC;AACtC,YAAY,EACV,iBAAiB,EACjB,qBAAqB,EACrB,eAAe,EACf,YAAY,EACZ,QAAQ,EACR,cAAc,EACd,oBAAoB,GACrB,MAAM,8BAA8B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACpD,YAAY,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAC1D,YAAY,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AACnD,YAAY,EACV,UAAU,EACV,cAAc,EACd,gBAAgB,EAChB,WAAW,EACX,eAAe,EACf,kBAAkB,EAClB,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,kBAAkB,EAClB,cAAc,EACd,cAAc,EACd,WAAW,EACX,aAAa,GACd,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,eAAe,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAChF,YAAY,EACV,KAAK,EACL,UAAU,EACV,OAAO,EACP,SAAS,EACT,WAAW,EACX,YAAY,EACZ,gBAAgB,EAChB,oBAAoB,EACpB,WAAW,GACZ,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAMnD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,YAAY,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AACrE,OAAO,EAAE,eAAe,EAAE,KAAK,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAC3E,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,YAAY,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAC7E,YAAY,EAAE,YAAY,EAAE,IAAI,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAC5E,YAAY,EACV,QAAQ,IAAI,gBAAgB,EAC5B,KAAK,IAAI,aAAa,EACtB,YAAY,GACb,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAG1D,YAAY,EACV,eAAe,EACf,mBAAmB,EACnB,kBAAkB,EAClB,oBAAoB,EACpB,0BAA0B,EAC1B,kBAAkB,EAClB,oBAAoB,EACpB,iBAAiB,EACjB,oBAAoB,GACrB,MAAM,6BAA6B,CAAC;AAGrC,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAG5D,YAAY,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAGjD,OAAO,EACL,2BAA2B,EAC3B,kBAAkB,EAClB,SAAS,EACT,QAAQ,EACR,UAAU,EACV,cAAc,EACd,aAAa,EACb,aAAa,EACb,iBAAiB,EACjB,kBAAkB,EAClB,QAAQ,EACR,iBAAiB,GAClB,MAAM,8BAA8B,CAAC;AACtC,YAAY,EACV,iBAAiB,EACjB,qBAAqB,EACrB,eAAe,EACf,YAAY,EACZ,QAAQ,EACR,cAAc,EACd,oBAAoB,GACrB,MAAM,8BAA8B,CAAC"}

package/dist/types/tools/index.d.ts

@@ -0,0 +1,33 @@
+import { z } from 'zod';
+import type { AgentTool } from '../dsl/types.js';
+/**
+ * Default generateUI tool - gets enriched with component metadata at runtime.
+ *
+ * This tool allows the LLM to generate a UI and wait for user response.
+ * The actual component list and descriptions are injected at runtime
+ * based on the components registered with .withComponents().
+ */
+export declare const generateUI: AgentTool;
+/**
+ * Default tools bundle.
+ *
+ * Use with .withTools(defaultTools) to include standard tools in your brain.
+ * Tools can be extended or overridden in individual agent steps.
+ *
+ * @example
+ * ```typescript
+ * import { brain, defaultTools } from '@positronic/core';
+ *
+ * const myBrain = brain('my-brain')
+ *   .withTools(defaultTools)
+ *   .brain('agent', ({ tools }) => ({
+ *     system: 'You are helpful',
+ *     prompt: 'Help the user',
+ *     tools  // uses defaultTools
+ *   }));
+ * ```
+ */
+export declare const defaultTools: {
+    generateUI: AgentTool<z.ZodType<any, z.ZodTypeDef, any>>;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/types/tools/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/tools/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,SAAS,EAAoB,MAAM,iBAAiB,CAAC;AAGnE;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,EAAE,SAwBxB,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,YAAY;;CAExB,CAAC"}

package/dist/types/ui/component-utils.d.ts

@@ -0,0 +1,19 @@
+import type { UIComponent } from './types.js';
+/**
+ * Merge multiple component objects into one.
+ * Later objects override earlier ones for component definitions.
+ *
+ * @param componentSets - Component objects to merge
+ * @returns A merged component object
+ *
+ * @example
+ * ```typescript
+ * import { components } from '@positronic/gen-ui-components';
+ * import { myComponents } from './my-components';
+ *
+ * const merged = mergeComponents(components, myComponents);
+ * brain.withComponents(merged);
+ * ```
+ */
+export declare function mergeComponents(...componentSets: Record<string, UIComponent<any>>[]): Record<string, UIComponent<any>>;
+//# sourceMappingURL=component-utils.d.ts.map

package/dist/types/ui/component-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"component-utils.d.ts","sourceRoot":"","sources":["../../../src/ui/component-utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAC7B,GAAG,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,GAAG,CAAC,CAAC,EAAE,GACnD,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,GAAG,CAAC,CAAC,CAQlC"}

package/dist/types/ui/generate-page-html.d.ts

@@ -0,0 +1,39 @@
+import type { Placement } from './types.js';
+/**
+ * Options for generating the page HTML.
+ */
+export interface GeneratePageHtmlOptions {
+    /** The placements array representing the component tree */
+    placements: Placement[];
+    /** The ID of the root placement */
+    rootId: string;
+    /** Data to be passed to components for data binding resolution */
+    data: Record<string, unknown>;
+    /** Page title */
+    title?: string;
+    /** Form action URL for form submission */
+    formAction?: string;
+}
+/**
+ * Generate a complete HTML page from placements.
+ *
+ * The generated page includes:
+ * - React and ReactDOM from CDN
+ * - Tailwind CSS from CDN
+ * - Reference to component bundle at /bundle/components.js
+ * - Data and placements embedded as JSON
+ * - Bootstrap runtime that builds and renders the React tree
+ *
+ * @example
+ * ```typescript
+ * const html = generatePageHtml({
+ *   placements: result.placements,
+ *   rootId: result.rootId,
+ *   data: brainState,
+ *   title: 'My Generated Page',
+ *   formAction: '/api/submit',
+ * });
+ * ```
+ */
+export declare function generatePageHtml(options: GeneratePageHtmlOptions): string;
+//# sourceMappingURL=generate-page-html.d.ts.map

package/dist/types/ui/generate-page-html.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate-page-html.d.ts","sourceRoot":"","sources":["../../../src/ui/generate-page-html.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,2DAA2D;IAC3D,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,mCAAmC;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,iBAAiB;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0CAA0C;IAC1C,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AA8HD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,MAAM,CAsDzE"}

package/dist/types/ui/generate-ui.d.ts

@@ -0,0 +1,47 @@
+import type { ObjectGenerator } from '../clients/types.js';
+import type { UIComponent, Placement, FormSchema } from './types.js';
+/**
+ * Result of generateUI - contains all component placements from the agent loop.
+ */
+export interface GenerateUIResult {
+    placements: Placement[];
+    rootId: string | undefined;
+    yaml?: string;
+    text?: string;
+    usage: {
+        totalTokens: number;
+    };
+}
+/**
+ * Generate a UI page using an LLM agent loop with YAML templates.
+ *
+ * The agent receives the user's prompt and generates a YAML template describing
+ * the component tree. The template is validated and converted to placements.
+ *
+ * @example
+ * ```typescript
+ * import { components } from '@positronic/gen-ui-components';
+ *
+ * const result = await generateUI({
+ *   client,
+ *   prompt: 'Create a form to collect user name and email',
+ *   components,
+ *   schema: z.object({ name: z.string(), email: z.string() }),
+ *   data: { user: { name: 'John' } },
+ * });
+ *
+ * // result.placements contains the component tree as a flat array
+ * // result.rootId is the ID of the root component
+ * // result.yaml is the generated YAML template
+ * ```
+ */
+export declare function generateUI(params: {
+    client: ObjectGenerator;
+    prompt: string;
+    components: Record<string, UIComponent<any>>;
+    schema?: FormSchema;
+    data?: Record<string, unknown>;
+    system?: string;
+    maxSteps?: number;
+}): Promise<GenerateUIResult>;
+//# sourceMappingURL=generate-ui.d.ts.map

package/dist/types/ui/generate-ui.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate-ui.d.ts","sourceRoot":"","sources":["../../../src/ui/generate-ui.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AA0DrE;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,EAAE;QAAE,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;CAChC;AAgUD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,UAAU,CAAC,MAAM,EAAE;IACvC,MAAM,EAAE,eAAe,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC;IAC7C,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAqD5B"}

package/dist/types/ui/types.d.ts

@@ -0,0 +1,138 @@
+import type { ComponentType } from 'react';
+import { z } from 'zod';
+/**
+ * A placed component in the UI tree.
+ * Components are stored in a flat array with parentId references to form a tree.
+ */
+export interface Placement {
+    /** Unique identifier for this placement */
+    id: string;
+    /** Component name, e.g., "Form", "Input", "Checkbox" */
+    component: string;
+    /** Props for the component, may contain binding expressions like "{{path}}" */
+    props: Record<string, unknown>;
+    /** Parent placement ID, null for root components */
+    parentId: string | null;
+}
+/**
+ * Represents the inferred type of a data value.
+ * Used for validating data bindings against the provided data.
+ */
+export type DataType = {
+    kind: 'primitive';
+    type: 'string' | 'number' | 'boolean' | 'null';
+} | {
+    kind: 'array';
+    elementType: DataType;
+} | {
+    kind: 'object';
+    properties: Record<string, DataType>;
+} | {
+    kind: 'unknown';
+};
+/**
+ * Infer the DataType from a sample value.
+ */
+export declare function inferDataType(value: unknown): DataType;
+/**
+ * A validation error from ValidateForm.
+ */
+export interface ValidationError {
+    type: 'form-schema-mismatch' | 'invalid-binding' | 'unknown-component' | 'missing-prop';
+    message: string;
+    path?: string;
+}
+/**
+ * Result of validation.
+ */
+export interface ValidationResult {
+    valid: boolean;
+    errors: ValidationError[];
+}
+/**
+ * Extracted form field info.
+ */
+export interface ExtractedFormField {
+    name: string;
+    type: 'string' | 'number' | 'boolean' | 'string[]' | 'number[]';
+    insideLoop: boolean;
+}
+/**
+ * The extracted form schema from placements.
+ */
+export interface ExtractedFormSchema {
+    fields: ExtractedFormField[];
+}
+/**
+ * A UI component that can be used by the LLM to build pages.
+ * Combines a React component with metadata for the LLM.
+ *
+ * Use the schema-first approach: define props as a Zod schema,
+ * then derive the TypeScript type with `z.infer<typeof schema>`.
+ *
+ * @example
+ * ```typescript
+ * const InputPropsSchema = z.object({
+ *   name: z.string().describe('Form field name'),
+ *   label: z.string().describe('Label displayed above input'),
+ *   required: z.boolean().optional().describe('Whether field is required'),
+ * });
+ *
+ * type InputProps = z.infer<typeof InputPropsSchema>;
+ *
+ * export const Input: UIComponent<InputProps> = {
+ *   component: InputComponent,
+ *   description: 'A single-line text input field.',
+ *   propsSchema: InputPropsSchema,
+ * };
+ * ```
+ */
+export interface UIComponent<TProps = unknown> {
+    /**
+     * React component for rendering this UI element.
+     */
+    component: ComponentType<TProps>;
+    /**
+     * Description of what this component does and when to use it.
+     * This is shown to the LLM to help it choose appropriate components.
+     */
+    description: string;
+    /**
+     * Zod schema defining the props for this component.
+     * Used to generate documentation for the LLM about available props.
+     * Use `.describe()` on each field to provide helpful descriptions.
+     */
+    propsSchema?: z.ZodObject<z.ZodRawShape>;
+}
+/**
+ * Form-compatible primitive types that can be collected via HTML forms.
+ * These types map directly to form inputs without LLM coercion.
+ */
+export type FormPrimitive = z.ZodString | z.ZodNumber | z.ZodBoolean | z.ZodEnum<[string, ...string[]]>;
+/**
+ * A form field is either a primitive or an optional/array wrapper around a primitive.
+ */
+export type FormField = FormPrimitive | z.ZodOptional<FormPrimitive> | z.ZodArray<FormPrimitive>;
+/**
+ * A form schema is a Zod object where all fields are form-compatible.
+ * This constraint ensures forms can be mechanically converted to JSON
+ * without requiring LLM interpretation of the submitted data.
+ *
+ * Supported field types:
+ * - z.string() → Input / TextArea
+ * - z.number() → Input (type="number")
+ * - z.boolean() → Checkbox
+ * - z.enum([...]) → Select / radio buttons
+ * - z.array(z.string()) → MultiTextInput
+ * - z.array(z.enum([...])) → Multi-select / checkbox group
+ * - z.optional(...) → Optional version of any above
+ */
+export type FormSchema = z.ZodObject<{
+    [key: string]: FormField;
+}>;
+/**
+ * Type guard to check if a schema is form-compatible at runtime.
+ * Used as a backup validation when TypeScript inference isn't sufficient.
+ */
+export declare function isFormSchema(schema: z.ZodSchema): schema is FormSchema;
+//# sourceMappingURL=types.d.ts.map

package/dist/types/ui/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/ui/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAC3C,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,2CAA2C;IAC3C,EAAE,EAAE,MAAM,CAAC;IACX,wDAAwD;IACxD,SAAS,EAAE,MAAM,CAAC;IAClB,+EAA+E;IAC/E,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,oDAAoD;IACpD,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAMD;;;GAGG;AACH,MAAM,MAAM,QAAQ,GAChB;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,CAAA;CAAE,GACrE;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,WAAW,EAAE,QAAQ,CAAA;CAAE,GACxC;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAA;CAAE,GACxD;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC;AAExB;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ,CAkCtD;AAMD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,sBAAsB,GAAG,iBAAiB,GAAG,mBAAmB,GAAG,cAAc,CAAC;IACxF,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,eAAe,EAAE,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,UAAU,GAAG,UAAU,CAAC;IAChE,UAAU,EAAE,OAAO,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,kBAAkB,EAAE,CAAC;CAC9B;AAMD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,WAAW,CAAC,MAAM,GAAG,OAAO;IAC3C;;OAEG;IACH,SAAS,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAEjC;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;;;OAIG;IACH,WAAW,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;CAC1C;AAED;;;GAGG;AACH,MAAM,MAAM,aAAa,GACrB,CAAC,CAAC,SAAS,GACX,CAAC,CAAC,SAAS,GACX,CAAC,CAAC,UAAU,GACZ,CAAC,CAAC,OAAO,CAAC,CAAC,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC,CAAC,CAAC;AAErC;;GAEG;AACH,MAAM,MAAM,SAAS,GACjB,aAAa,GACb,CAAC,CAAC,WAAW,CAAC,aAAa,CAAC,GAC5B,CAAC,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC;AAE9B;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,SAAS,CAAC;IACnC,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;CAC1B,CAAC,CAAC;AAEH;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,CAAC,CAAC,SAAS,GAAG,MAAM,IAAI,UAAU,CAatE"}

package/dist/types/ui/validate-form.d.ts

@@ -0,0 +1,45 @@
+import { z } from 'zod';
+import type { Placement, ValidationResult, ExtractedFormSchema } from './types.js';
+import type { FormSchema } from './types.js';
+/**
+ * Check if a value is a binding expression like "{{path}}".
+ */
+export declare function isBinding(value: unknown): value is string;
+/**
+ * Extract the path from a binding expression.
+ * "{{email.subject}}" -> "email.subject"
+ */
+export declare function extractBindingPath(binding: string): string;
+/**
+ * Validate all data bindings in placements against the provided data type.
+ */
+export declare function validateDataBindings(placements: Placement[], data: Record<string, unknown>): ValidationResult;
+/**
+ * Extract form schema from placements.
+ * Finds all form input components and extracts their field info.
+ */
+export declare function extractFormSchema(placements: Placement[]): ExtractedFormSchema;
+/**
+ * Validate extracted form schema against a Zod schema.
+ */
+export declare function validateAgainstZod(extracted: ExtractedFormSchema, zodSchema: FormSchema): ValidationResult;
+/**
+ * Create the ValidateForm tool for the UI generation agent.
+ * Validates both form schema and data bindings.
+ */
+export declare function createValidateFormTool(placements: Placement[], schema: FormSchema | undefined, data: Record<string, unknown>): {
+    description: string;
+    inputSchema: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
+    execute: () => {
+        valid: boolean;
+        errors: Array<{
+            type: string;
+            message: string;
+        }>;
+        extractedFields: Array<{
+            name: string;
+            type: string;
+        }>;
+    };
+};
+//# sourceMappingURL=validate-form.d.ts.map

package/dist/types/ui/validate-form.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-form.d.ts","sourceRoot":"","sources":["../../../src/ui/validate-form.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EACV,SAAS,EAGT,gBAAgB,EAEhB,mBAAmB,EACpB,MAAM,YAAY,CAAC;AAEpB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAM7C;;GAEG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAEzD;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE1D;AAwHD;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,SAAS,EAAE,EACvB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,gBAAgB,CA2BlB;AAmBD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,SAAS,EAAE,GAAG,mBAAmB,CA2C9E;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,mBAAmB,EAC9B,SAAS,EAAE,UAAU,GACpB,gBAAgB,CAwBlB;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,SAAS,EAAE,EACvB,MAAM,EAAE,UAAU,GAAG,SAAS,EAC9B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;;mBAQd;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QAAC,eAAe,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;KAAE;EAuB5I"}

package/dist/types/yaml/data-validator.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Data validator for YAML templates.
+ *
+ * Validates that template bindings (like {{email.subject}}) reference
+ * valid paths in the provided data structure.
+ */
+import type { ComponentNode, DataType, ValidationResult } from './types.js';
+/**
+ * Loop context tracks variables introduced by List/Each components.
+ * Maps variable name to the element type of the array being iterated.
+ */
+type LoopContext = Map<string, DataType>;
+/**
+ * Infer a DataType from a sample JavaScript value.
+ */
+export declare function inferDataType(value: unknown): DataType;
+/**
+ * Resolve a binding path against a data type, considering loop context.
+ *
+ * @param path - The binding path like "email.subject" or "emails"
+ * @param rootType - The root data type
+ * @param loopContext - Map of loop variable names to their types
+ * @returns The resolved DataType or null if path is invalid
+ */
+export declare function resolvePathType(path: string, rootType: DataType, loopContext: LoopContext): DataType | null;
+/**
+ * Validate all data bindings in a component tree.
+ *
+ * @param root - The root ComponentNode
+ * @param dataType - The inferred type of the available data
+ * @returns ValidationResult with any errors found
+ */
+export declare function validateDataBindings(root: ComponentNode, dataType: DataType): ValidationResult;
+export {};
+//# sourceMappingURL=data-validator.d.ts.map

package/dist/types/yaml/data-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-validator.d.ts","sourceRoot":"","sources":["../../../src/yaml/data-validator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,aAAa,EACb,QAAQ,EAER,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAEpB;;;GAGG;AACH,KAAK,WAAW,GAAG,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;AAEzC;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ,CAkCtD;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,QAAQ,EAClB,WAAW,EAAE,WAAW,GACvB,QAAQ,GAAG,IAAI,CA+BjB;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,aAAa,EACnB,QAAQ,EAAE,QAAQ,GACjB,gBAAgB,CAyDlB"}

package/dist/types/yaml/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * YAML-based UI generation module.
+ *
+ * Provides parsing, validation, and type inference for YAML UI templates.
+ */
+export * from './types.js';
+export { parseTemplate, stringifyTemplate } from './parser.js';
+export { inferDataType, resolvePathType, validateDataBindings, } from './data-validator.js';
+export { extractFormSchema, fieldsToShape, validateAgainstZod, } from './schema-extractor.js';
+export { describeDataShape, inferTypeWithExamples } from './type-inference.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/yaml/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/yaml/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,EACL,aAAa,EACb,eAAe,EACf,oBAAoB,GACrB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,iBAAiB,EACjB,aAAa,EACb,kBAAkB,GACnB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/types/yaml/parser.d.ts

@@ -0,0 +1,20 @@
+/**
+ * YAML parser for UI templates.
+ *
+ * Parses YAML strings into a ComponentNode AST. Uses the {{path}} syntax
+ * to detect binding expressions that will be resolved at render time.
+ */
+import type { Template } from './types.js';
+/**
+ * Parse a YAML template string into a Template AST.
+ *
+ * @param yamlString - The YAML template to parse
+ * @returns The parsed Template with root ComponentNode
+ * @throws Error if YAML is invalid or doesn't match expected structure
+ */
+export declare function parseTemplate(yamlString: string): Template;
+/**
+ * Convert a Template back to YAML string (for debugging).
+ */
+export declare function stringifyTemplate(template: Template): string;
+//# sourceMappingURL=parser.d.ts.map

package/dist/types/yaml/parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../../src/yaml/parser.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAA4B,QAAQ,EAAE,MAAM,YAAY,CAAC;AA6FrE;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,QAAQ,CAS1D;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAoB5D"}

package/dist/types/yaml/schema-extractor.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Schema extractor for YAML templates.
+ *
+ * Extracts the form schema that will be produced by the template's form fields.
+ * Also validates extracted schema against expected Zod schemas.
+ */
+import { type ZodType, type ZodTypeDef } from 'zod';
+import type { ComponentNode, ExtractedFormSchema, FormField, FormFieldType, ValidationError } from './types.js';
+/**
+ * Extract form fields from a component tree.
+ *
+ * @param root - The root ComponentNode
+ * @returns ExtractedFormSchema with all form fields found
+ */
+export declare function extractFormSchema(root: ComponentNode): ExtractedFormSchema;
+/**
+ * Convert extracted fields to a nested object shape.
+ * Handles dot notation like "user.email" -> { user: { email: ... } }
+ */
+export declare function fieldsToShape(fields: FormField[]): Record<string, FormFieldType | Record<string, unknown>>;
+/**
+ * Validate an extracted schema against an expected Zod schema.
+ *
+ * @param extracted - The ExtractedFormSchema from the template
+ * @param zodSchema - The expected Zod schema (must be ZodObject)
+ * @returns Array of validation errors
+ */
+export declare function validateAgainstZod(extracted: ExtractedFormSchema, zodSchema: ZodType<unknown, ZodTypeDef, unknown>): ValidationError[];
+//# sourceMappingURL=schema-extractor.d.ts.map

package/dist/types/yaml/schema-extractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-extractor.d.ts","sourceRoot":"","sources":["../../../src/yaml/schema-extractor.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAK,KAAK,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,KAAK,CAAC;AACvD,OAAO,KAAK,EACV,aAAa,EACb,mBAAmB,EACnB,SAAS,EACT,aAAa,EACb,eAAe,EAChB,MAAM,YAAY,CAAC;AAiBpB;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,aAAa,GAAG,mBAAmB,CA4C1E;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,SAAS,EAAE,GAClB,MAAM,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAoBzD;AAmGD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,mBAAmB,EAC9B,SAAS,EAAE,OAAO,CAAC,OAAO,EAAE,UAAU,EAAE,OAAO,CAAC,GAC/C,eAAe,EAAE,CAoDnB"}

package/dist/types/yaml/type-inference.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Type inference for generating readable data shape descriptions.
+ *
+ * Used to describe available data to the LLM in a TypeScript-like format
+ * with inline examples for better template generation.
+ */
+/**
+ * Infer a type description for a value.
+ * Returns a simple type string like "string", "number", etc.
+ */
+export declare function inferTypeDescription(value: unknown): string;
+/**
+ * Infer a type description with inline examples.
+ * Makes it easier for the LLM to understand the data shape.
+ *
+ * @param value - The sample value to describe
+ * @param indent - Current indentation level
+ * @returns Multi-line string describing the type with examples
+ */
+export declare function inferTypeWithExamples(value: unknown, indent?: number): string;
+/**
+ * Describe the shape of data in a readable TypeScript-like format.
+ * This is the main entry point for generating data descriptions for the LLM.
+ *
+ * @param data - The data object to describe
+ * @returns A multi-line string describing the data shape with examples
+ *
+ * @example
+ * ```typescript
+ * const data = {
+ *   emails: [
+ *     { id: "1", subject: "Hello", from: "alice@example.com" }
+ *   ],
+ *   sessionId: "abc123"
+ * };
+ *
+ * console.log(describeDataShape(data));
+ * // Output:
+ * // {
+ * //   emails: Array<{
+ * //     id: string // e.g., "1"
+ * //     subject: string // e.g., "Hello"
+ * //     from: string // e.g., "alice@example.com"
+ * //   }> // 1 items
+ * //   sessionId: string // e.g., "abc123"
+ * // }
+ * ```
+ */
+export declare function describeDataShape(data: Record<string, unknown>): string;
+//# sourceMappingURL=type-inference.d.ts.map

package/dist/types/yaml/type-inference.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"type-inference.d.ts","sourceRoot":"","sources":["../../../src/yaml/type-inference.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAkC3D;AA+BD;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,SAAI,GAAG,MAAM,CA4DxE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAEvE"}