@factorialco/f0-react 1.414.1 → 1.415.0

package/dist/f0.d.ts

@@ -140,6 +140,7 @@ import { WithDataTestIdReturnType as WithDataTestIdReturnType_7 } from './f0';
 import { z } from 'zod';
 import { ZodEffects } from 'zod';
 import { ZodRawShape } from 'zod';
+import { ZodType } from 'zod';
 import { ZodTypeAny } from 'zod';
 
 export declare function A({ children, ...props }: React.AnchorHTMLAttributes<HTMLAnchorElement>): JSX_2.Element;
@@ -694,6 +695,18 @@ blurArea?: "l" | "r" | "lr";
 
 declare type AsAllowedList = (typeof allTags)[number];
 
+/**
+ * Accepts either a synchronous value or an async function that resolves it.
+ * The async function receives an `AbortSignal` for cancellation support.
+ */
+export declare type AsyncOrSync<T> = T | ((signal: AbortSignal) => Promise<T>);
+
+/**
+ * Async function that receives typed params (from AI presentForm).
+ * Use this variant when `defaultValuesParamsSchema` is provided.
+ */
+declare type AsyncWithParams<T, TParams> = (params: TParams) => Promise<T>;
+
 declare const Avatar: React_2.ForwardRefExoticComponent<Omit<AvatarPrimitive.AvatarProps & React_2.RefAttributes<HTMLSpanElement>, "ref"> & {
     size?: (typeof internalAvatarSizes)[number];
     type?: (typeof internalAvatarTypes)[number];
@@ -2070,6 +2083,8 @@ export declare interface CustomFieldRenderProps<TValue = unknown, TConfig = unde
     required?: boolean;
     /** Custom configuration passed via fieldConfig */
     config: TConfig;
+    /** Name identifying this custom field type (used with renderCustomField) */
+    customFieldName?: string;
 }
 
 /**
@@ -2096,6 +2111,8 @@ declare interface CustomFieldRenderPropsBase {
     disabled?: boolean;
     /** Whether the field is required (derived from Zod schema) */
     required?: boolean;
+    /** Name identifying this custom field type (used with renderCustomField) */
+    customFieldName?: string;
 }
 
 export declare const Dashboard: WithDataTestIdReturnType_3<ComponentType<DashboardProps_2> & PageLayoutGroupComponent_2>;
@@ -3347,6 +3364,38 @@ export declare const defaultTranslations: {
     };
 };
 
+/**
+ * Helper to define an available form with proper params typing.
+ * TypeScript infers `TParams` from `defaultValuesParamsSchema`, so the
+ * `defaultValues` callback receives fully typed params.
+ *
+ * @example
+ * ```tsx
+ * const employeeForm = defineAvailableForm({
+ *   name: "edit-employee",
+ *   schema: employeeSchema,
+ *   defaultValuesParamsSchema: z.object({ employeeId: z.string() }),
+ *   defaultValues: (params) => ({
+ *     // params.employeeId is typed as string
+ *     name: `Employee ${params.employeeId}`,
+ *   }),
+ * })
+ * ```
+ */
+export declare function defineAvailableForm<TParams extends Record<string, unknown> = Record<string, unknown>>(definition: F0AiAvailableFormDefinition<TParams>): F0AiAvailableFormDefinition<TParams>;
+
+/**
+ * Introspect an F0Form schema and return a serializable array of field descriptions.
+ * Pure function — usable outside React components.
+ *
+ * @example
+ * ```ts
+ * const fields = describeFormSchema(mySchema)
+ * // [{ name: "email", type: "text", label: "Email", required: true, ... }, ...]
+ * ```
+ */
+export declare function describeFormSchema(schema: F0FormSchema): FormFieldDescription[];
+
 export declare type DialogPosition = (typeof dialogPositions)[number];
 
 declare const dialogPositions: readonly ["center", "left", "right", "fullscreen"];
@@ -3649,6 +3698,41 @@ export declare interface F0ActionItemProps {
     inGroup?: boolean;
 }
 
+/**
+ * A form definition that the AI can interact with even though the form is not rendered.
+ *
+ * Use the generic parameter to type the params accepted by a functional `defaultValues`.
+ * Prefer using {@link defineAvailableForm} for automatic inference from `defaultValuesParamsSchema`.
+ */
+export declare interface F0AiAvailableFormDefinition<TParams extends Record<string, unknown> = Record<string, unknown>> {
+    /** Unique name to identify the form */
+    name: string;
+    /** Zod schema that defines the form's fields and validation */
+    schema: F0FormSchema;
+    /**
+     * Default values for the form fields.
+     * Can be a static object or a function that receives params (supplied by the AI via presentForm)
+     * and returns the defaults.
+     */
+    defaultValues?: Record<string, unknown> | ((params: TParams) => Record<string, unknown>);
+    /**
+     * Zod schema that describes the params accepted by a functional `defaultValues`.
+     * When provided, the AI will see this schema and can supply params when calling presentForm.
+     * Params are validated against this schema before being passed to `defaultValues`.
+     */
+    defaultValuesParamsSchema?: ZodType<TParams>;
+    /** Section configs (title, description) keyed by section ID */
+    sections?: Record<string, F0SectionConfig>;
+    /** Optional submit handler. Called when AI triggers formSubmit on this form. */
+    onSubmit?: (values: Record<string, unknown>) => void | Promise<void>;
+    /** Title shown in the dialog header or wizard header */
+    title?: string;
+    /** Description shown under the title in dialog mode */
+    description?: string;
+    /** Wizard steps (required for wizard mode to work with multiple steps) */
+    steps?: F0WizardFormStep[];
+}
+
 /**
  * @experimental This is an experimental component use it at your own risk
  */
@@ -3737,6 +3821,88 @@ export declare interface F0AiCollapsibleMessageProps {
     children: ReactNode;
 }
 
+/**
+ * Entry in the AI form registry
+ */
+export declare interface F0AiFormEntry {
+    ref: React.MutableRefObject<F0FormRef | null>;
+    schema: F0FormSchema;
+    /** Whether this entry was registered from an availableFormDefinition (not a rendered form) */
+    virtual?: boolean;
+    /** Section configs (title, description) keyed by section ID */
+    sections?: Record<string, F0SectionConfig>;
+    /** Zod schema for params accepted by presentForm (virtual entries only) */
+    defaultValuesParamsSchema?: ZodType;
+    /** Raw defaultValues function that accepts params (from rendered forms with defaultValuesParamsSchema) */
+    defaultValuesFn?: (params: Record<string, unknown>) => Promise<Record<string, unknown>>;
+    /** Field names explicitly set via setValue/setValues on a virtual ref */
+    dirtyFields?: Set<string>;
+}
+
+/**
+ * Context value for the AI form registry
+ */
+declare interface F0AiFormRegistryContextValue {
+    register: (name: string, ref: React.MutableRefObject<F0FormRef | null>, schema: F0FormSchema, sections?: Record<string, F0SectionConfig>, defaultValuesParamsSchema?: ZodType, defaultValuesFn?: (params: Record<string, unknown>) => Promise<Record<string, unknown>>) => void;
+    unregister: (name: string) => void;
+    get: (name: string) => F0AiFormEntry | undefined;
+    getFormNames: () => string[];
+    /** Rebuild the form descriptions snapshot (call after mutating form state) */
+    rebuildDescriptions: () => void;
+    /** Structured descriptions of all active forms, updated on register/unregister */
+    formDescriptions: {
+        formName: string;
+        formSchema: Record<string, unknown>;
+        fieldDescriptions: Record<string, {
+            label: string;
+            section?: string;
+            placeholder?: string;
+            helpText?: string;
+            description?: string;
+        }>;
+        sectionDescriptions: Record<string, {
+            title: string;
+            description?: string;
+        }>;
+        formValues: Record<string, unknown>;
+        formErrors: Record<string, unknown>;
+        isDirty: boolean;
+        /** JSON Schema of defaultValuesParams accepted by presentForm (only for forms with defaultValuesParamsSchema) */
+        defaultValuesParamsSchema?: Record<string, unknown>;
+    }[];
+    /** Currently AI-presented form, or null */
+    presentedForm: F0AiPresentedForm | null;
+    /** Called by the AI tool to present a form */
+    presentForm: (formName: string, mode: "dialog" | "wizard", defaultValuesParams?: Record<string, unknown>) => {
+        success: boolean;
+        error?: string;
+    };
+    /** Called when the presented form is closed (submit/cancel) */
+    dismissForm: () => void;
+}
+
+/**
+ * Provider that maintains a registry of active F0Forms,
+ * enabling AI tools to look up forms by name.
+ *
+ * Place this inside both the CopilotKit provider and above the F0Form components.
+ *
+ * @example
+ * ```tsx
+ * <F0AiChatProvider>
+ *   <F0AiFormRegistryProvider>
+ *     <F0Form name="my-form" ... />
+ *     <F0AiChat />
+ *   </F0AiFormRegistryProvider>
+ * </F0AiChatProvider>
+ * ```
+ */
+export declare function F0AiFormRegistryProvider({ children, availableFormDefinitions, }: {
+    children: React.ReactNode;
+    /** Form definitions the AI can interact with even if the form is not rendered on the page */
+    availableFormDefinitions?: F0AiAvailableFormDefinition[];
+}): JSX_2.Element;
+
 /**
  * @experimental This is an experimental component use it at your own risk
  */
@@ -3771,6 +3937,20 @@ export declare class F0AiMask {
     private render;
 }
 
+/**
+ * Tracks an AI-presented form (opened via the presentForm tool)
+ */
+export declare interface F0AiPresentedForm {
+    /** Name of the form (matches an availableFormDefinition) */
+    name: string;
+    /** Render mode chosen by the LLM */
+    mode: "dialog" | "wizard";
+    /** Resolved definition from availableFormDefinitions */
+    definition: F0AiAvailableFormDefinition;
+    /** Snapshot of the virtual form's values at the time presentForm was called */
+    initialValues: Record<string, unknown>;
+}
+
 export declare const F0Alert: WithDataTestIdReturnType_3<({ title, description, action, link, icon, variant, }: F0AlertProps) => JSX_2.Element>;
 
 export declare interface F0AlertProps {
@@ -4110,6 +4290,12 @@ export declare interface F0BaseConfig {
      * renderIf: ({ values }) => values.status === 'active'
      */
     renderIf?: F0BaseFieldRenderIfProp;
+    /**
+     * Name identifying a reusable custom field type.
+     * When set, the form-level `renderCustomField` callback is invoked to provide
+     * field-specific configuration (e.g. data source, options) or a custom component.
+     */
+    customFieldName?: string;
 }
 
 /**
@@ -4145,6 +4331,11 @@ export declare interface F0BaseField {
      * @default false
      */
     resetOnDisable?: boolean;
+    /**
+     * Name identifying a reusable custom field type.
+     * Used with the form-level `renderCustomField` callback.
+     */
+    customFieldName?: string;
 }
 
 /**
@@ -4448,10 +4639,15 @@ export declare type F0CustomConfig<TValue = unknown, TConfig = undefined> = TCon
  *
  * @typeParam TValue - Type of the field value
  */
-declare interface F0CustomConfigBase<TValue = unknown> {
+declare type F0CustomConfigBase<TValue = unknown> = {
     /** Render function for the custom component */
     render: (props: CustomFieldRenderProps<TValue, undefined>) => ReactNode;
-}
+} | {
+    /** Name identifying this custom field type (resolved by renderCustomField on the form) */
+    customFieldName: string;
+    /** Optional render function (overridden by form-level renderCustomField when customFieldName is set) */
+    render?: (props: CustomFieldRenderProps<TValue, undefined>) => ReactNode;
+};
 
 /**
  * Custom config with fieldConfig (render receives typed config)
@@ -4459,12 +4655,19 @@ declare interface F0CustomConfigBase<TValue = unknown> {
  * @typeParam TValue - Type of the field value
  * @typeParam TConfig - Type of the fieldConfig object
  */
-declare interface F0CustomConfigWithFieldConfig<TValue = unknown, TConfig = unknown> {
+declare type F0CustomConfigWithFieldConfig<TValue = unknown, TConfig = unknown> = {
     /** Custom configuration to pass to the render function */
     fieldConfig: TConfig;
     /** Render function for the custom component */
     render: (props: CustomFieldRenderProps<TValue, TConfig>) => ReactNode;
-}
+} | {
+    /** Custom configuration to pass to the render function */
+    fieldConfig: TConfig;
+    /** Name identifying this custom field type (resolved by renderCustomField on the form) */
+    customFieldName: string;
+    /** Optional render function (overridden by form-level renderCustomField when customFieldName is set) */
+    render?: (props: CustomFieldRenderProps<TValue, TConfig>) => ReactNode;
+};
 
 /**
  * Custom field with all properties for rendering (runtime type)
@@ -4472,11 +4675,13 @@ declare interface F0CustomConfigWithFieldConfig<TValue = unknown, TConfig = unkn
 export declare type F0CustomField = F0BaseField & {
     type: "custom";
     /** Render function for the custom component */
-    render: (props: CustomFieldRenderPropsBase & {
+    render?: (props: CustomFieldRenderPropsBase & {
         config: unknown;
     }) => ReactNode;
     /** Custom configuration (if provided) */
     fieldConfig?: unknown;
+    /** Name identifying this custom field type (resolved by renderCustomField on the form) */
+    customFieldName?: string;
     /** Conditional rendering based on another field's value */
     renderIf?: CustomFieldRenderIf;
 };
@@ -5166,6 +5371,14 @@ export declare interface F0FormDefinitionPerSection<T extends F0PerSectionSchema
     onSubmit: (arg: F0WizardFormPerSectionSubmitArg<T>) => Promise<F0FormSubmitResult> | F0FormSubmitResult;
     submitConfig?: F0PerSectionSubmitConfig;
     errorTriggerMode?: F0FormErrorTriggerMode;
+    /** Whether async defaultValues are still being resolved */
+    isLoading?: boolean;
+    /** Zod schema describing params the AI can supply when calling presentForm */
+    defaultValuesParamsSchema?: ZodType;
+    /** Raw defaultValues function for AI registry use when params are involved */
+    defaultValuesFn?: (params: Record<string, unknown>) => Promise<{
+        [K in keyof T]?: Partial<z.infer<T[K]>>;
+    }>;
 }
 
 export declare interface F0FormDefinitionSingleSchema<TSchema extends F0FormSchema_2> {
@@ -5177,6 +5390,12 @@ export declare interface F0FormDefinitionSingleSchema<TSchema extends F0FormSche
     onSubmit: (arg: F0WizardFormSingleSubmitArg<TSchema>) => Promise<F0FormSubmitResult> | F0FormSubmitResult;
     submitConfig?: F0FormSubmitConfig;
     errorTriggerMode?: F0FormErrorTriggerMode;
+    /** Whether async defaultValues are still being resolved */
+    isLoading?: boolean;
+    /** Zod schema describing params the AI can supply when calling presentForm */
+    defaultValuesParamsSchema?: ZodType;
+    /** Raw defaultValues function for AI registry use when params are involved */
+    defaultValuesFn?: (params: Record<string, unknown>) => Promise<Partial<z.infer<TSchema>>>;
 }
 
 /**
@@ -5349,6 +5568,17 @@ export declare interface F0FormPropsWithPerSectionDefinition<T extends F0PerSect
     styling?: F0FormStylingConfig;
     formRef?: React.MutableRefObject<F0FormRef | null>;
     initialFiles?: InitialFile[];
+    /**
+     * Callback that renders custom fields identified by `customFieldName`.
+     * When a field has `customFieldName`, this function is called instead of the inline `render`.
+     */
+    renderCustomField?: RenderCustomFieldFunction;
+    /**
+     * Whether async defaultValues are still being resolved.
+     * When true, the form renders with loading indicators inside each field
+     * instead of replacing the entire form with skeleton placeholders.
+     */
+    isLoading?: boolean;
 }
 
 /**
@@ -5392,6 +5622,17 @@ export declare interface F0FormPropsWithPerSectionSchema<T extends F0PerSectionS
      * `defaultValues` against `InitialFile.value`.
      */
     initialFiles?: InitialFile[];
+    /**
+     * Callback that renders custom fields identified by `customFieldName`.
+     * When a field has `customFieldName`, this function is called instead of the inline `render`.
+     */
+    renderCustomField?: RenderCustomFieldFunction;
+    /**
+     * Whether async defaultValues are still being resolved.
+     * When true, the form renders with loading indicators inside each field
+     * instead of replacing the entire form with skeleton placeholders.
+     */
+    isLoading?: boolean;
 }
 
 /**
@@ -5436,6 +5677,27 @@ export declare interface F0FormPropsWithSingleSchema<TSchema extends F0FormSchem
      * `defaultValues` against `InitialFile.value`.
      */
     initialFiles?: InitialFile[];
+    /**
+     * Callback that renders custom fields identified by `customFieldName`.
+     * When a field has `customFieldName`, this function is called instead of the inline `render`.
+     */
+    renderCustomField?: RenderCustomFieldFunction;
+    /**
+     * Whether async defaultValues are still being resolved.
+     * When true, the form renders with loading indicators inside each field
+     * instead of replacing the entire form with skeleton placeholders.
+     */
+    isLoading?: boolean;
+    /**
+     * Zod schema describing params the AI can supply when calling presentForm.
+     * Passed through to the AI form registry.
+     */
+    defaultValuesParamsSchema?: ZodType;
+    /**
+     * Raw defaultValues function for the AI registry to call with params.
+     * Set automatically when using `useF0FormDefinition` with a functional `defaultValues`.
+     */
+    defaultValuesFn?: (params: Record<string, unknown>) => Promise<Record<string, unknown>>;
 }
 
 /**
@@ -5449,6 +5711,11 @@ export declare interface F0FormPropsWithSingleSchemaDefinition<TSchema extends F
     styling?: F0FormStylingConfig;
     formRef?: React.MutableRefObject<F0FormRef | null>;
     initialFiles?: InitialFile[];
+    /**
+     * Callback that renders custom fields identified by `customFieldName`.
+     * When a field has `customFieldName`, this function is called instead of the inline `render`.
+     */
+    renderCustomField?: RenderCustomFieldFunction;
 }
 
 /**
@@ -5473,6 +5740,27 @@ export declare interface F0FormRef {
      * Get the current form values (including unsaved changes)
      */
     getValues: () => Record<string, unknown>;
+    /**
+     * Set a single field value programmatically
+     */
+    setValue: (fieldName: string, value: unknown, options?: F0FormSetValueOptions) => void;
+    /**
+     * Set multiple field values at once
+     */
+    setValues: (values: Record<string, unknown>, options?: F0FormSetValueOptions) => void;
+    /**
+     * Manually trigger validation for a specific field or all fields
+     * @returns true if validation passes
+     */
+    trigger: (fieldName?: string) => Promise<boolean>;
+    /**
+     * Get current validation errors as a map of field name to error message
+     */
+    getErrors: () => Record<string, string>;
+    /**
+     * Get the list of field names in the form
+     */
+    getFieldNames: () => string[];
     /* Excluded from this release type: _setStateCallback */
 }
 
@@ -5483,6 +5771,14 @@ export declare type F0FormSchema<T extends ZodRawShape = ZodRawShape> = z.ZodObj
 
 declare type F0FormSchema_2<T extends ZodRawShape = ZodRawShape> = z.ZodObject<T> | ZodEffects<z.ZodObject<T>>;
 
+/**
+ * Options for setValue
+ */
+export declare interface F0FormSetValueOptions {
+    shouldValidate?: boolean;
+    shouldDirty?: boolean;
+}
+
 /**
  * Callback to update form state in the hook
  */
@@ -5904,6 +6200,7 @@ declare type F0SelectBaseProps<T extends string, R = unknown> = {
  * Supports either:
  * - Static `options` array
  * - Dynamic `source` with `mapOptions` function
+ * - Runtime-provided via `customFieldName` (no options/source needed at definition time)
  *
  * @typeParam T - The value type (string or number)
  * @typeParam R - Record type from the data source
@@ -5911,7 +6208,7 @@ declare type F0SelectBaseProps<T extends string, R = unknown> = {
  * Note: `clearable` is derived from the Zod schema:
  * - `z.string().optional()` or `z.string().nullable()` → clearable
  */
-export declare type F0SelectConfig<T extends SelectValueType = string, R extends RecordType = RecordType> = F0SelectConfigWithOptions<T> | F0SelectConfigWithSource<T, R>;
+export declare type F0SelectConfig<T extends SelectValueType = string, R extends RecordType = RecordType> = F0SelectConfigWithOptions<T> | F0SelectConfigWithSource<T, R> | F0SelectConfigWithCustomFieldName;
 
 /**
  * Base config options shared by all select field variants
@@ -5925,6 +6222,18 @@ declare interface F0SelectConfigBase {
     searchBoxPlaceholder?: string;
 }
 
+/**
+ * Config for select fields whose options/source are provided at runtime
+ * via `customFieldName` and `renderCustomField`.
+ */
+declare interface F0SelectConfigWithCustomFieldName extends F0SelectConfigBase {
+    options?: never;
+    source?: never;
+    mapOptions?: never;
+    /** Required: identifies the custom field provider */
+    customFieldName: string;
+}
+
 /**
  * Config for select fields with static options
  * @typeParam T - The value type (string or number)
@@ -6335,6 +6644,11 @@ declare interface F0WizardFormBaseProps {
      * @default false
      */
     autoSkipCompletedSteps?: boolean;
+    /**
+     * Callback that renders custom fields identified by `customFieldName`.
+     * When a field has `customFieldName`, this function is called instead of the inline `render`.
+     */
+    renderCustomField?: RenderCustomFieldFunction;
 }
 
 export declare interface F0WizardFormPerSectionProps<T extends F0PerSectionSchema_2> extends F0WizardFormBaseProps {
@@ -6665,6 +6979,26 @@ export declare type FormatPreset = {
 
 /* Excluded from this release type: FormDefinitionItem */
 
+/**
+ * Serializable description of a single form field,
+ * intended for AI tools to understand form structure.
+ */
+export declare interface FormFieldDescription {
+    name: string;
+    type: F0FieldType;
+    label: string;
+    required: boolean;
+    placeholder?: string;
+    helpText?: string;
+    options?: {
+        label: string;
+        value: string | number;
+    }[];
+    optionsSource?: "dynamic";
+    section?: string;
+    customFieldName?: string;
+}
+
 /**
  * Standalone form field props — decoupled from react-hook-form.
  * This is the minimal contract that field renderers need to operate.
@@ -8609,6 +8943,59 @@ declare type RelaxedNumericWithFormatter = Omit<NumericWithFormatter, "numericVa
     numericValue: Numeric;
 };
 
+/**
+ * Callback provided to F0Form / F0WizardForm that renders custom fields
+ * identified by `customFieldName` instead of an inline `render` function.
+ *
+ * For `fieldType: "custom"` — return a ReactNode (component) as before.
+ * For `fieldType: "select"` — return either a ReactNode or a `RenderCustomFieldSelectConfig`
+ * with `{ _type: "select-config", source, mapOptions }` to configure the select dynamically.
+ */
+export declare type RenderCustomFieldFunction = (props: RenderCustomFieldProps) => RenderCustomFieldResult;
+
+/**
+ * Props passed to the form-level `renderCustomField` callback.
+ * Extends the base custom field render props with a required `customFieldName`.
+ */
+export declare interface RenderCustomFieldProps extends CustomFieldRenderPropsBase {
+    /** Name identifying this custom field type */
+    customFieldName: string;
+    /** Custom configuration (if provided via fieldConfig) */
+    config: unknown;
+    /** The field type this customFieldName is attached to (e.g. "select", "custom") */
+    fieldType: string;
+}
+
+/**
+ * Return type for the `renderCustomField` callback.
+ * Can return either:
+ * - A React node (rendered directly as a custom component)
+ * - A select config object (merged into the select field props)
+ */
+declare type RenderCustomFieldResult = React.ReactNode | RenderCustomFieldSelectConfig;
+
+/**
+ * Select field configuration that `renderCustomField` can return
+ * for select fields with `customFieldName` (e.g. reusable entity selectors).
+ *
+ * Mirrors the select field config shape — either static `options` or dynamic `source`+`mapOptions`.
+ */
+export declare interface RenderCustomFieldSelectConfig {
+    _type: "select-config";
+    /** Data source for fetching options dynamically */
+    source?: unknown;
+    /** Function to map data source items to select options */
+    mapOptions?: (item: never) => unknown;
+    /** Static options array */
+    options?: unknown[];
+    /** Whether multiple selection is allowed */
+    multiple?: boolean;
+    /** Whether to show the search box */
+    showSearchBox?: boolean;
+    /** Placeholder for the search box */
+    searchBoxPlaceholder?: string;
+}
+
 declare type RendererDefinition = ValueDisplayRendererDefinition;
 
 /**
@@ -9924,6 +10311,23 @@ export declare const useEmojiConfetti: () => {
     fireEmojiConfetti: (emoji: string, elementRef: RefObject<HTMLElement>) => void;
 };
 
+/**
+ * Hook that registers all AI form interaction tools and pushes
+ * form context to the co-agent shared state via `useCoAgent`.
+ *
+ * Must be called inside a component tree that has both:
+ * - A `F0AiFormRegistryProvider` ancestor (for form lookup)
+ * - A CopilotKit context (for tool registration + co-agent state)
+ * - An `AiChatStateProvider` ancestor (for the agent name)
+ */
+export declare const useF0AiFormActions: () => void;
+
+/**
+ * Hook to access the AI form registry.
+ * Returns null if not inside a F0AiFormRegistryProvider.
+ */
+export declare function useF0AiFormRegistry(): F0AiFormRegistryContextValue | null;
+
 export declare const useF0Dialog: () => F0DialogContextType;
 
 /**
@@ -9967,32 +10371,68 @@ export declare const useF0Dialog: () => F0DialogContextType;
  */
 export declare function useF0Form(): UseF0FormReturn;
 
-export declare function useF0FormDefinition<TSchema extends F0FormSchema_2>(input: UseF0FormDefinitionSingleSchemaInput<TSchema>): F0FormDefinitionSingleSchema<TSchema>;
+/** Single schema, no params */
+export declare function useF0FormDefinition<TSchema extends F0FormSchema_2>(input: UseF0FormDefinitionSingleSchemaInputWithoutParams<TSchema>): F0FormDefinitionSingleSchema<TSchema>;
 
-export declare function useF0FormDefinition<T extends F0PerSectionSchema_2>(input: UseF0FormDefinitionPerSectionInput<T>): F0FormDefinitionPerSection<T>;
+/** Single schema, with params */
+export declare function useF0FormDefinition<TSchema extends F0FormSchema_2, TParams extends Record<string, unknown>>(input: UseF0FormDefinitionSingleSchemaInputWithParams<TSchema, TParams>): F0FormDefinitionSingleSchema<TSchema>;
 
-declare interface UseF0FormDefinitionPerSectionInput<T extends F0PerSectionSchema_2> {
+/** Per-section, no params */
+export declare function useF0FormDefinition<T extends F0PerSectionSchema_2>(input: UseF0FormDefinitionPerSectionInputWithoutParams<T>): F0FormDefinitionPerSection<T>;
+
+/** Per-section, with params */
+export declare function useF0FormDefinition<T extends F0PerSectionSchema_2, TParams extends Record<string, unknown>>(input: UseF0FormDefinitionPerSectionInputWithParams<T, TParams>): F0FormDefinitionPerSection<T>;
+
+/** Base fields shared by all per-section input variants */
+declare interface UseF0FormDefinitionPerSectionInputBase<T extends F0PerSectionSchema_2> {
     name: string;
     schema: T;
     sections?: Record<string, F0PerSectionSectionConfig>;
-    defaultValues?: {
-        [K in keyof T]?: Partial<z.infer<T[K]>>;
-    };
     onSubmit: (arg: F0WizardFormPerSectionSubmitArg<T>) => Promise<F0FormSubmitResult> | F0FormSubmitResult;
     submitConfig?: F0PerSectionSubmitConfig;
     errorTriggerMode?: F0FormErrorTriggerMode;
 }
 
-declare interface UseF0FormDefinitionSingleSchemaInput<TSchema extends F0FormSchema_2> {
+/** Per-section input WITHOUT `defaultValuesParamsSchema` */
+declare interface UseF0FormDefinitionPerSectionInputWithoutParams<T extends F0PerSectionSchema_2> extends UseF0FormDefinitionPerSectionInputBase<T> {
+    defaultValues?: AsyncOrSync<{
+        [K in keyof T]?: Partial<z.infer<T[K]>>;
+    }>;
+    defaultValuesParamsSchema?: undefined;
+}
+
+/** Per-section input WITH `defaultValuesParamsSchema` */
+declare interface UseF0FormDefinitionPerSectionInputWithParams<T extends F0PerSectionSchema_2, TParams extends Record<string, unknown>> extends UseF0FormDefinitionPerSectionInputBase<T> {
+    defaultValues?: {
+        [K in keyof T]?: Partial<z.infer<T[K]>>;
+    } | AsyncWithParams<{
+        [K in keyof T]?: Partial<z.infer<T[K]>>;
+    }, TParams>;
+    defaultValuesParamsSchema: ZodType<TParams>;
+}
+
+/** Base fields shared by all single-schema input variants */
+declare interface UseF0FormDefinitionSingleSchemaInputBase<TSchema extends F0FormSchema_2> {
     name: string;
     schema: TSchema;
     sections?: Record<string, F0SectionConfig>;
-    defaultValues?: Partial<z.infer<TSchema>>;
     onSubmit: (arg: F0WizardFormSingleSubmitArg<TSchema>) => Promise<F0FormSubmitResult> | F0FormSubmitResult;
     submitConfig?: F0FormSubmitConfig;
     errorTriggerMode?: F0FormErrorTriggerMode;
 }
 
+/** Single-schema input WITHOUT `defaultValuesParamsSchema` → `defaultValues` is sync or `(signal) => Promise<T>` */
+declare interface UseF0FormDefinitionSingleSchemaInputWithoutParams<TSchema extends F0FormSchema_2> extends UseF0FormDefinitionSingleSchemaInputBase<TSchema> {
+    defaultValues?: AsyncOrSync<Partial<z.infer<TSchema>>>;
+    defaultValuesParamsSchema?: undefined;
+}
+
+/** Single-schema input WITH `defaultValuesParamsSchema` → `defaultValues` is sync or `(params) => Promise<T>` */
+declare interface UseF0FormDefinitionSingleSchemaInputWithParams<TSchema extends F0FormSchema_2, TParams extends Record<string, unknown>> extends UseF0FormDefinitionSingleSchemaInputBase<TSchema> {
+    defaultValues?: Partial<z.infer<TSchema>> | AsyncWithParams<Partial<z.infer<TSchema>>, TParams>;
+    defaultValuesParamsSchema: ZodType<TParams>;
+}
+
 /**
  * Return type for the useF0Form hook
  */
@@ -10019,6 +10459,27 @@ export declare interface UseF0FormReturn {
      * Get the current form values (including unsaved changes)
      */
     getValues: () => Record<string, unknown>;
+    /**
+     * Set a single field value programmatically
+     */
+    setValue: (fieldName: string, value: unknown, options?: F0FormSetValueOptions) => void;
+    /**
+     * Set multiple field values at once
+     */
+    setValues: (values: Record<string, unknown>, options?: F0FormSetValueOptions) => void;
+    /**
+     * Manually trigger validation for a specific field or all fields
+     * @returns true if validation passes
+     */
+    trigger: (fieldName?: string) => Promise<boolean>;
+    /**
+     * Get current validation errors as a map of field name to error message
+     */
+    getErrors: () => Record<string, string>;
+    /**
+     * Get the list of field names in the form
+     */
+    getFieldNames: () => string[];
     /**
      * Whether the form is currently submitting
      */
@@ -10045,6 +10506,24 @@ export declare interface UseF0FormReturn {
  */
 export declare type UseFileUpload = () => FileUploadHookReturn;
 
+/**
+ * AI tool that fills one or more fields in an active F0Form.
+ * After setting values, it triggers validation and returns any errors.
+ */
+export declare const useFormFillAction: () => void;
+
+/**
+ * AI tool that reads the current state of an active F0Form —
+ * current values, dirty status, and validation errors.
+ */
+export declare const useFormGetStateAction: () => void;
+
+/**
+ * AI tool that submits an active F0Form.
+ * Triggers validation first — only calls onSubmit if all fields pass.
+ */
+export declare const useFormSubmitAction: () => void;
+
 export declare const useGroups: <R extends RecordType>(groups: GroupRecord<R>[], defaultOpenGroups?: boolean | GroupRecord<R>["key"][]) => {
     openGroups: Record<string, boolean>;
     setGroupOpen: (key: string, open: boolean) => void;
@@ -10385,11 +10864,6 @@ declare module "gridstack" {
 }
 
 
-declare namespace Calendar {
-    var displayName: string;
-}
-
-
 declare module "@tiptap/core" {
     interface Commands<ReturnType> {
         aiBlock: {
@@ -10437,3 +10911,8 @@ declare module "@tiptap/core" {
         };
     }
 }
+
+
+declare namespace Calendar {
+    var displayName: string;
+}