@elizaos/plugin-form 2.0.0-alpha.9 → 2.0.0-beta.1

package/auto-enable.ts

@@ -0,0 +1,24 @@
+// Auto-enable check for @elizaos/plugin-form.
+//
+// Plugin manifest entry-point — referenced by package.json's
+// `elizaos.plugin.autoEnableModule`. Keep this module light: env reads only,
+// no service init, no transitive imports of the full plugin runtime. The
+// auto-enable engine loads dozens of these per boot.
+import type { PluginAutoEnableContext } from "@elizaos/core";
+
+function isFeatureEnabled(
+  config: PluginAutoEnableContext["config"],
+  key: string,
+): boolean {
+  const f = (config?.features as Record<string, unknown> | undefined)?.[key];
+  if (f === true) return true;
+  if (f && typeof f === "object" && f !== null) {
+    return (f as Record<string, unknown>).enabled !== false;
+  }
+  return false;
+}
+
+/** Enable when `config.features.form` is truthy / not explicitly disabled. */
+export function shouldEnable(ctx: PluginAutoEnableContext): boolean {
+  return isFeatureEnabled(ctx.config, "form");
+}

package/dist/actions/restore.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @module actions/restore
+ * @description Planner action for restoring stashed form sessions.
+ *
+ * Restore is a planner-driven Action (not part of the post-message form
+ * evaluator) because the restored form context must reach the provider
+ * BEFORE the agent generates its response. If the user has an active form
+ * in the current room, the action asks them to continue or stash the
+ * current one. Multiple stashed forms restore the most recent.
+ */
+import { type Action } from "@elizaos/core";
+/**
+ * Form Restore Action
+ *
+ * Fast-path action for restoring stashed forms.
+ * Preempts REPLY to provide immediate restoration with summary.
+ *
+ * WHY action:
+ * - Needs to run BEFORE provider
+ * - Must generate immediate response
+ * - Context needed for next message
+ */
+export declare const formRestoreAction: Action;
+export default formRestoreAction;
+//# sourceMappingURL=restore.d.ts.map

package/dist/actions/restore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"restore.d.ts","sourceRoot":"","sources":["../../src/actions/restore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EACL,KAAK,MAAM,EASZ,MAAM,eAAe,CAAC;AAYvB;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,EAAE,MA4L/B,CAAC;AAEF,eAAe,iBAAiB,CAAC"}

package/dist/actions/restore.js

@@ -0,0 +1,176 @@
+import {
+  logger
+} from "@elizaos/core";
+const RESTORE_FIELD_LIMIT = 12;
+const RESTORE_RESPONSE_MAX_CHARS = 4e3;
+function truncateRestoreResponse(text) {
+  return text.length <= RESTORE_RESPONSE_MAX_CHARS ? text : `${text.slice(0, RESTORE_RESPONSE_MAX_CHARS)}
+
+[truncated restored form summary]`;
+}
+const formRestoreAction = {
+  name: "FORM_RESTORE",
+  contexts: ["tasks", "automation", "memory"],
+  contextGate: { anyOf: ["tasks", "automation", "memory"] },
+  roleGate: { minRole: "USER" },
+  similes: ["RESUME_FORM", "CONTINUE_FORM"],
+  description: "Restore a previously stashed form session",
+  descriptionCompressed: "Restore stashed form session.",
+  parameters: [
+    {
+      name: "sessionId",
+      description: "Optional stashed form session id to restore.",
+      required: false,
+      schema: { type: "string" }
+    }
+  ],
+  /**
+   * Validate: action is selectable whenever the user has stashed sessions
+   * and no active form in the current room. The planner picks it via the
+   * action description/similes when the user actually wants to resume.
+   */
+  validate: async (runtime, message, _state) => {
+    const formService = runtime.getService("FORM");
+    if (!formService) return false;
+    const entityId = message.entityId;
+    const roomId = message.roomId;
+    if (!entityId || !roomId) return false;
+    const stashed = await formService.getStashedSessions(entityId);
+    if (stashed.length === 0) return false;
+    const active = await formService.getActiveSession(entityId, roomId);
+    return active === null;
+  },
+  /**
+   * Handler: Restore the most recent stashed session.
+   *
+   * 1. Check for conflicts (active session in room)
+   * 2. Restore the session
+   * 3. Generate summary response
+   *
+   * @returns ActionResult with success status and session data
+   */
+  handler: async (runtime, message, _state, _options, callback) => {
+    try {
+      const formService = runtime.getService("FORM");
+      if (!formService) {
+        await callback?.({
+          text: "Sorry, I couldn't find the form service."
+        });
+        return { success: false };
+      }
+      const entityId = message.entityId;
+      const roomId = message.roomId;
+      if (!entityId || !roomId) {
+        await callback?.({
+          text: "Sorry, I couldn't identify you."
+        });
+        return { success: false };
+      }
+      const existing = await formService.getActiveSession(entityId, roomId);
+      if (existing) {
+        const form2 = formService.getForm(existing.formId);
+        await callback?.({
+          text: `You already have an active form: "${form2?.name || existing.formId}". Would you like to continue with that one, or should I save it and restore your other form?`
+        });
+        return { success: false };
+      }
+      const stashed = await formService.getStashedSessions(entityId);
+      if (stashed.length === 0) {
+        await callback?.({
+          text: "You don't have any saved forms to resume."
+        });
+        return { success: false };
+      }
+      const sessionToRestore = stashed.sort(
+        (a, b) => b.updatedAt - a.updatedAt
+      )[0];
+      const session = await formService.restore(sessionToRestore.id, entityId);
+      const form = formService.getForm(session.formId);
+      const context = formService.getSessionContext(session);
+      let responseText = `I've restored your "${form?.name || session.formId}" form. `;
+      responseText += `You're ${context.progress}% complete. `;
+      if (context.filledFields.length > 0) {
+        responseText += `
+
+Here's what I have so far:
+`;
+        for (const field of context.filledFields.slice(0, RESTORE_FIELD_LIMIT)) {
+          responseText += `\u2022 ${field.label}: ${field.displayValue}
+`;
+        }
+      }
+      if (context.nextField) {
+        responseText += `
+Let's continue with ${context.nextField.label}.`;
+        if (context.nextField.askPrompt) {
+          responseText += ` ${context.nextField.askPrompt}`;
+        }
+      } else if (context.status === "ready") {
+        responseText += `
+Everything looks complete! Ready to submit?`;
+      }
+      await callback?.({
+        text: truncateRestoreResponse(responseText)
+      });
+      return {
+        success: true,
+        data: {
+          sessionId: session.id,
+          formId: session.formId,
+          progress: context.progress
+        }
+      };
+    } catch (error) {
+      logger.error("[FormRestoreAction] Handler error:", String(error));
+      await callback?.({
+        text: "Sorry, I couldn't restore your form. Please try again."
+      });
+      return { success: false };
+    }
+  },
+  // Example conversations for training/documentation
+  examples: [
+    [
+      {
+        name: "{{user1}}",
+        content: { text: "Resume my form" }
+      },
+      {
+        name: "{{agentName}}",
+        content: {
+          text: "I've restored your form. Let's continue where you left off."
+        }
+      }
+    ],
+    [
+      {
+        name: "{{user1}}",
+        content: { text: "Continue with my registration" }
+      },
+      {
+        name: "{{agentName}}",
+        content: {
+          text: "I've restored your Registration form. You're 60% complete."
+        }
+      }
+    ],
+    [
+      {
+        name: "{{user1}}",
+        content: { text: "Pick up where I left off" }
+      },
+      {
+        name: "{{agentName}}",
+        content: {
+          text: "I've restored your form. Here's what you have so far..."
+        }
+      }
+    ]
+  ]
+};
+var restore_default = formRestoreAction;
+export {
+  restore_default as default,
+  formRestoreAction
+};
+//# sourceMappingURL=restore.js.map

package/dist/actions/restore.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/actions/restore.ts"],"sourcesContent":["/**\n * @module actions/restore\n * @description Planner action for restoring stashed form sessions.\n *\n * Restore is a planner-driven Action (not part of the post-message form\n * evaluator) because the restored form context must reach the provider\n * BEFORE the agent generates its response. If the user has an active form\n * in the current room, the action asks them to continue or stash the\n * current one. Multiple stashed forms restore the most recent.\n */\n\nimport {\n  type Action,\n  type ActionResult,\n  type HandlerCallback,\n  type HandlerOptions,\n  type IAgentRuntime,\n  logger,\n  type Memory,\n  type State,\n  type UUID,\n} from \"@elizaos/core\";\nimport type { FormService } from \"../service\";\n\nconst RESTORE_FIELD_LIMIT = 12;\nconst RESTORE_RESPONSE_MAX_CHARS = 4_000;\n\nfunction truncateRestoreResponse(text: string): string {\n  return text.length <= RESTORE_RESPONSE_MAX_CHARS\n    ? text\n    : `${text.slice(0, RESTORE_RESPONSE_MAX_CHARS)}\\n\\n[truncated restored form summary]`;\n}\n\n/**\n * Form Restore Action\n *\n * Fast-path action for restoring stashed forms.\n * Preempts REPLY to provide immediate restoration with summary.\n *\n * WHY action:\n * - Needs to run BEFORE provider\n * - Must generate immediate response\n * - Context needed for next message\n */\nexport const formRestoreAction: Action = {\n  name: \"FORM_RESTORE\",\n  contexts: [\"tasks\", \"automation\", \"memory\"],\n  contextGate: { anyOf: [\"tasks\", \"automation\", \"memory\"] },\n  roleGate: { minRole: \"USER\" },\n  similes: [\"RESUME_FORM\", \"CONTINUE_FORM\"],\n  description: \"Restore a previously stashed form session\",\n  descriptionCompressed: \"Restore stashed form session.\",\n  parameters: [\n    {\n      name: \"sessionId\",\n      description: \"Optional stashed form session id to restore.\",\n      required: false,\n      schema: { type: \"string\" },\n    },\n  ],\n\n  /**\n   * Validate: action is selectable whenever the user has stashed sessions\n   * and no active form in the current room. The planner picks it via the\n   * action description/similes when the user actually wants to resume.\n   */\n  validate: async (\n    runtime: IAgentRuntime,\n    message: Memory,\n    _state?: State,\n  ): Promise<boolean> => {\n    const formService = runtime.getService(\"FORM\") as FormService;\n    if (!formService) return false;\n\n    const entityId = message.entityId as UUID;\n    const roomId = message.roomId as UUID;\n    if (!entityId || !roomId) return false;\n\n    const stashed = await formService.getStashedSessions(entityId);\n    if (stashed.length === 0) return false;\n\n    const active = await formService.getActiveSession(entityId, roomId);\n    return active === null;\n  },\n\n  /**\n   * Handler: Restore the most recent stashed session.\n   *\n   * 1. Check for conflicts (active session in room)\n   * 2. Restore the session\n   * 3. Generate summary response\n   *\n   * @returns ActionResult with success status and session data\n   */\n  handler: async (\n    runtime: IAgentRuntime,\n    message: Memory,\n    _state?: State,\n    _options?: HandlerOptions,\n    callback?: HandlerCallback,\n  ): Promise<ActionResult> => {\n    try {\n      const formService = runtime.getService(\"FORM\") as FormService;\n      if (!formService) {\n        await callback?.({\n          text: \"Sorry, I couldn't find the form service.\",\n        });\n        return { success: false };\n      }\n\n      const entityId = message.entityId as UUID;\n      const roomId = message.roomId as UUID;\n\n      if (!entityId || !roomId) {\n        await callback?.({\n          text: \"Sorry, I couldn't identify you.\",\n        });\n        return { success: false };\n      }\n\n      // Check for existing active session in this room\n      // WHY check: Can't have two active sessions in same room\n      const existing = await formService.getActiveSession(entityId, roomId);\n      if (existing) {\n        const form = formService.getForm(existing.formId);\n        await callback?.({\n          text: `You already have an active form: \"${form?.name || existing.formId}\". Would you like to continue with that one, or should I save it and restore your other form?`,\n        });\n        return { success: false };\n      }\n\n      // Get stashed sessions\n      const stashed = await formService.getStashedSessions(entityId);\n\n      if (stashed.length === 0) {\n        await callback?.({\n          text: \"You don't have any saved forms to resume.\",\n        });\n        return { success: false };\n      }\n\n      // Restore the most recent stashed session — the user likely wants what\n      // they just stashed.\n      const sessionToRestore = stashed.sort(\n        (a, b) => b.updatedAt - a.updatedAt,\n      )[0];\n      const session = await formService.restore(sessionToRestore.id, entityId);\n\n      const form = formService.getForm(session.formId);\n      const context = formService.getSessionContext(session);\n\n      // Generate response with restored context\n      // WHY immediate response: User knows what happened\n      let responseText = `I've restored your \"${form?.name || session.formId}\" form. `;\n      responseText += `You're ${context.progress}% complete. `;\n\n      if (context.filledFields.length > 0) {\n        responseText += `\\n\\nHere's what I have so far:\\n`;\n        for (const field of context.filledFields.slice(0, RESTORE_FIELD_LIMIT)) {\n          responseText += `• ${field.label}: ${field.displayValue}\\n`;\n        }\n      }\n\n      if (context.nextField) {\n        responseText += `\\nLet's continue with ${context.nextField.label}.`;\n        if (context.nextField.askPrompt) {\n          responseText += ` ${context.nextField.askPrompt}`;\n        }\n      } else if (context.status === \"ready\") {\n        responseText += `\\nEverything looks complete! Ready to submit?`;\n      }\n\n      await callback?.({\n        text: truncateRestoreResponse(responseText),\n      });\n\n      return {\n        success: true,\n        data: {\n          sessionId: session.id,\n          formId: session.formId,\n          progress: context.progress,\n        },\n      };\n    } catch (error) {\n      logger.error(\"[FormRestoreAction] Handler error:\", String(error));\n      await callback?.({\n        text: \"Sorry, I couldn't restore your form. Please try again.\",\n      });\n      return { success: false };\n    }\n  },\n\n  // Example conversations for training/documentation\n  examples: [\n    [\n      {\n        name: \"{{user1}}\",\n        content: { text: \"Resume my form\" },\n      },\n      {\n        name: \"{{agentName}}\",\n        content: {\n          text: \"I've restored your form. Let's continue where you left off.\",\n        },\n      },\n    ],\n    [\n      {\n        name: \"{{user1}}\",\n        content: { text: \"Continue with my registration\" },\n      },\n      {\n        name: \"{{agentName}}\",\n        content: {\n          text: \"I've restored your Registration form. You're 60% complete.\",\n        },\n      },\n    ],\n    [\n      {\n        name: \"{{user1}}\",\n        content: { text: \"Pick up where I left off\" },\n      },\n      {\n        name: \"{{agentName}}\",\n        content: {\n          text: \"I've restored your form. Here's what you have so far...\",\n        },\n      },\n    ],\n  ],\n};\n\nexport default formRestoreAction;\n"],"mappings":"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","names":["form"]}

package/dist/builder.d.ts

@@ -0,0 +1,320 @@
+/**
+ * @module builder
+ * @description Fluent builder API for defining forms and controls
+ *
+ * ## Why a Builder API
+ *
+ * Form definitions can be verbose with many optional fields. The builder
+ * API provides:
+ *
+ * 1. **Type Safety**: Method chaining with TypeScript gives autocomplete
+ * 2. **Readability**: Intent is clear from method names
+ * 3. **Defaults**: Builder applies sensible defaults
+ * 4. **Validation**: Build-time checks for common mistakes
+ *
+ * ## Usage Examples
+ *
+ * ### Simple Form
+ *
+ * ```typescript
+ * const form = Form.create('contact')
+ *   .name('Contact Form')
+ *   .control(C.email('email').required())
+ *   .control(C.text('message').required())
+ *   .build();
+ * ```
+ *
+ * ### Complex Form
+ *
+ * ```typescript
+ * const registrationForm = Form.create('registration')
+ *   .name('User Registration')
+ *   .description('Create your account')
+ *   .control(
+ *     C.email('email')
+ *       .required()
+ *       .ask('What email should we use for your account?')
+ *       .example('user@example.com')
+ *   )
+ *   .control(
+ *     C.text('username')
+ *       .required()
+ *       .minLength(3)
+ *       .maxLength(20)
+ *       .pattern('^[a-z0-9_]+$')
+ *       .ask('Choose a username (letters, numbers, underscore)')
+ *   )
+ *   .control(
+ *     C.number('age')
+ *       .min(13)
+ *       .ask('How old are you?')
+ *   )
+ *   .onSubmit('handle_registration')
+ *   .ttl({ minDays: 7, maxDays: 30 })
+ *   .build();
+ * ```
+ *
+ * ### Custom Type
+ *
+ * ```typescript
+ * // Register custom type first
+ * FormService.registerType('solana_address', {
+ *   validate: (v) => ({
+ *     valid: /^[1-9A-HJ-NP-Za-km-z]{32,44}$/.test(String(v)),
+ *     error: 'Invalid Solana address'
+ *   }),
+ *   extractionPrompt: 'a Solana wallet address (Base58 encoded)'
+ * });
+ *
+ * // Use in form
+ * const form = Form.create('wallet')
+ *   .control(
+ *     C.field('walletAddress')
+ *       .type('solana_address')
+ *       .required()
+ *       .label('Wallet Address')
+ *       .ask('What is your Solana wallet address?')
+ *   )
+ *   .build();
+ * ```
+ *
+ * ## Shorthand Exports
+ *
+ * For convenience:
+ * - `Form` is an alias for `FormBuilder`
+ * - `C` is an alias for `ControlBuilder`
+ *
+ * This enables the concise syntax shown in examples.
+ */
+import type { JsonValue } from "@elizaos/core";
+import type { FormControl, FormControlDependency, FormControlOption, FormDefinition, FormDefinitionHooks } from "./types";
+/**
+ * Fluent builder for FormControl.
+ *
+ * Create controls with readable, chainable syntax:
+ *
+ * ```typescript
+ * ControlBuilder.email('email').required().ask('What is your email?')
+ * ```
+ *
+ * All methods return `this` for chaining except `build()` which returns
+ * the final FormControl.
+ */
+export declare class ControlBuilder {
+    /** Partial control being built */
+    private control;
+    /**
+     * Create a new ControlBuilder.
+     *
+     * @param key - The unique key for this control
+     */
+    constructor(key: string);
+    /** Create a generic field builder */
+    static field(key: string): ControlBuilder;
+    /** Create a text field */
+    static text(key: string): ControlBuilder;
+    /** Create an email field */
+    static email(key: string): ControlBuilder;
+    /** Create a number field */
+    static number(key: string): ControlBuilder;
+    /** Create a boolean (yes/no) field */
+    static boolean(key: string): ControlBuilder;
+    /** Create a select field with options */
+    static select(key: string, options: FormControlOption[]): ControlBuilder;
+    /** Create a date field */
+    static date(key: string): ControlBuilder;
+    /** Create a file upload field */
+    static file(key: string): ControlBuilder;
+    /** Set the field type */
+    type(type: string): this;
+    /** Mark field as required */
+    required(): this;
+    /** Mark field as optional (default) */
+    optional(): this;
+    /** Mark field as hidden (extract silently, never ask) */
+    hidden(): this;
+    /** Mark field as sensitive (don't echo value back) */
+    sensitive(): this;
+    /** Mark field as readonly (can't change after set) */
+    readonly(): this;
+    /** Mark field as accepting multiple values */
+    multiple(): this;
+    /** Set regex pattern for validation */
+    pattern(regex: string): this;
+    /** Set minimum value (for numbers) or minimum length (via minLength) */
+    min(n: number): this;
+    /** Set maximum value (for numbers) or maximum length (via maxLength) */
+    max(n: number): this;
+    /** Set minimum string length */
+    minLength(n: number): this;
+    /** Set maximum string length */
+    maxLength(n: number): this;
+    /** Set allowed values (enum) */
+    enum(values: string[]): this;
+    /** Set select options */
+    options(opts: FormControlOption[]): this;
+    /** Set human-readable label */
+    label(label: string): this;
+    /** Set custom prompt for asking this field */
+    ask(prompt: string): this;
+    /** Set description for LLM context */
+    description(desc: string): this;
+    /** Add extraction hints (keywords to look for) */
+    hint(...hints: string[]): this;
+    /** Set example value for "give me an example" */
+    example(value: string): this;
+    /** Set confidence threshold for auto-acceptance */
+    confirmThreshold(n: number): this;
+    /** Set accepted MIME types for file upload */
+    accept(mimeTypes: string[]): this;
+    /** Set maximum file size in bytes */
+    maxSize(bytes: number): this;
+    /** Set maximum number of files */
+    maxFiles(n: number): this;
+    /** Set roles that can see/fill this field */
+    roles(...roles: string[]): this;
+    /** Set default value */
+    default(value: JsonValue): this;
+    /** Set dependency on another field */
+    dependsOn(field: string, condition?: FormControlDependency["condition"], value?: JsonValue): this;
+    /** Set database column name (defaults to key) */
+    dbbind(columnName: string): this;
+    /** Set section name for grouping */
+    section(name: string): this;
+    /** Set display order within section */
+    order(n: number): this;
+    /** Set placeholder text */
+    placeholder(text: string): this;
+    /** Set help text */
+    helpText(text: string): this;
+    /** Set custom widget type */
+    widget(type: string): this;
+    /** Add localized text for a locale */
+    i18n(locale: string, translations: {
+        label?: string;
+        description?: string;
+        askPrompt?: string;
+        helpText?: string;
+    }): this;
+    /** Add custom metadata */
+    meta(key: string, value: JsonValue): this;
+    /**
+     * Build the final FormControl.
+     *
+     * Applies defaults and validates the control.
+     *
+     * @returns Complete FormControl object
+     */
+    build(): FormControl;
+}
+/**
+ * Fluent builder for FormDefinition.
+ *
+ * Create forms with readable, chainable syntax:
+ *
+ * ```typescript
+ * Form.create('contact')
+ *   .name('Contact Form')
+ *   .control(C.email('email').required())
+ *   .onSubmit('handle_contact')
+ *   .build();
+ * ```
+ */
+export declare class FormBuilder {
+    /** Partial form being built */
+    private form;
+    /**
+     * Create a new FormBuilder.
+     *
+     * @param id - Unique form identifier
+     */
+    constructor(id: string);
+    /** Create a new form builder */
+    static create(id: string): FormBuilder;
+    /** Set form name */
+    name(name: string): this;
+    /** Set form description */
+    description(desc: string): this;
+    /** Set form version */
+    version(v: number): this;
+    /**
+     * Add a control to the form.
+     *
+     * Accepts either a ControlBuilder (calls .build()) or a FormControl.
+     */
+    control(builder: ControlBuilder | FormControl): this;
+    /** Add multiple controls */
+    controls(...builders: (ControlBuilder | FormControl)[]): this;
+    /** Add required text fields */
+    required(...keys: string[]): this;
+    /** Add optional text fields */
+    optional(...keys: string[]): this;
+    /** Set roles that can start this form */
+    roles(...roles: string[]): this;
+    /** Allow multiple submissions per user */
+    allowMultiple(): this;
+    /** Disable undo functionality */
+    noUndo(): this;
+    /** Disable skip functionality */
+    noSkip(): this;
+    /** Disable autofill */
+    noAutofill(): this;
+    /** Set maximum undo steps */
+    maxUndoSteps(n: number): this;
+    /** Configure TTL (time-to-live) settings */
+    ttl(config: {
+        minDays?: number;
+        maxDays?: number;
+        effortMultiplier?: number;
+    }): this;
+    /** Disable nudge messages */
+    noNudge(): this;
+    /** Set inactivity hours before nudge */
+    nudgeAfter(hours: number): this;
+    /** Set custom nudge message */
+    nudgeMessage(message: string): this;
+    /** Set task worker to call on session start */
+    onStart(workerName: string): this;
+    /** Set task worker to call on field change */
+    onFieldChange(workerName: string): this;
+    /** Set task worker to call when form is ready to submit */
+    onReady(workerName: string): this;
+    /** Set task worker to call on submission */
+    onSubmit(workerName: string): this;
+    /** Set task worker to call on cancellation */
+    onCancel(workerName: string): this;
+    /** Set task worker to call on expiration */
+    onExpire(workerName: string): this;
+    /** Set multiple hooks at once */
+    hooks(hooks: FormDefinitionHooks): this;
+    /** Enable debug mode (logs extraction reasoning) */
+    debug(): this;
+    /** Add localized form text */
+    i18n(locale: string, translations: {
+        name?: string;
+        description?: string;
+    }): this;
+    /** Add custom metadata */
+    meta(key: string, value: JsonValue): this;
+    /**
+     * Build the final FormDefinition.
+     *
+     * Applies defaults and validates the form.
+     *
+     * @returns Complete FormDefinition object
+     */
+    build(): FormDefinition;
+}
+/**
+ * Shorthand for FormBuilder.create
+ *
+ * Usage: `Form.create('myForm')...`
+ */
+export declare const Form: typeof FormBuilder;
+/**
+ * Shorthand for ControlBuilder factories
+ *
+ * Usage: `C.email('email').required()`
+ */
+export declare const C: typeof ControlBuilder;
+//# sourceMappingURL=builder.d.ts.map

package/dist/builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../src/builder.ts"],"names":[],"mappings":"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"}