@ng-forge/dynamic-forms 1.2.0-next.1 → 1.2.0-next.10

package/types/ng-forge-dynamic-forms-internal.d.ts

@@ -1,8 +1,8 @@
 import * as _ng_forge_dynamic_forms_internal from '@ng-forge/dynamic-forms/internal';
 import * as i0 from '@angular/core';
-import { Signal, Type, ResourceRef, ViewContainerRef, InjectionToken, WritableSignal, Injector, TemplateRef, PipeTransform, Resource } from '@angular/core';
+import { Signal, Type, ResourceRef, ViewContainerRef, InjectionToken, WritableSignal, Injector, TemplateRef, PipeTransform, Resource, Provider } from '@angular/core';
 import { Observable, OperatorFunction } from 'rxjs';
-import { FieldContext, TreeValidationResult, ValidationError as ValidationError$1, FieldTree, ReadonlyFieldState, LogicFn, SchemaPath, SchemaPathTree } from '@angular/forms/signals';
+import { FieldContext, ValidationError as ValidationError$1, TreeValidationResult, FieldTree, ReadonlyFieldState, LogicFn, SchemaPath, SchemaPathTree } from '@angular/forms/signals';
 import { FormSchema } from '@ng-forge/dynamic-forms/schema';
 
 type DynamicText = string | Observable<string> | Signal<string>;
@@ -83,6 +83,45 @@ interface FieldMeta {
     [key: string]: string | number | boolean | undefined;
 }
 
+/**
+ * Per-field WebMCP exposure policy.
+ *
+ * WebMCP tools are callable by any agent that reaches the page, so what a field
+ * lets an agent read and write is a security decision, not a formatting one.
+ * Sensible defaults are derived from the field itself (see below); this
+ * overrides them where the author knows better.
+ *
+ * Defaults, applied when a key is left unset:
+ *
+ * | Field | `readable` | `writable` |
+ * | --- | --- | --- |
+ * | `type: 'hidden'` | `false` | `false` |
+ * | `props.type === 'password'` | `false` | `true` |
+ * | `readonly: true`, or a `derivation` | `true` | `false` |
+ * | anything else | `true` | `true` |
+ *
+ * @experimental
+ */
+interface FieldWebMcpOptions {
+    /**
+     * Whether an agent may read this field's value back in a tool response.
+     *
+     * A field that is not readable is still reported by name, so the agent knows
+     * it exists and whether it currently holds a value — only the value itself is
+     * withheld.
+     */
+    readable?: boolean;
+    /** Whether an agent may write this field. A write to a non-writable field is rejected. */
+    writable?: boolean;
+}
+/**
+ * A field's WebMCP exposure policy. `false` is shorthand for hiding the field
+ * from agents entirely (`{ readable: false, writable: false }`).
+ *
+ * @experimental
+ */
+type FieldWebMcpConfig = FieldWebMcpOptions | false;
+
 /**
  * Base interface for all dynamic form field definitions.
  *
@@ -168,6 +207,17 @@ interface FieldDef<TProps, TMeta extends FieldMeta = FieldMeta> {
     skipDefaultWrappers?: boolean;
     /** Addons rendered inside this field's slots (typically `prefix` / `suffix`). */
     addons?: ReadonlyArray<AnyAddon>;
+    /**
+     * What a browser AI agent may read and write on this field, when the form
+     * opts in through `options.webMcp`. Ignored otherwise.
+     *
+     * Defaults are derived from the field (a password input is not readable, a
+     * `readonly` or derived field is not writable, a `hidden` field type is
+     * neither); `false` hides the field from agents entirely.
+     *
+     * @experimental
+     */
+    webMcp?: FieldWebMcpConfig;
 }
 type IncludedKeys = 'label' | 'className' | 'hidden' | 'tabIndex';
 /**
@@ -480,12 +530,242 @@ interface RowField<TFields extends readonly RowAllowedChildren[] = readonly RowA
 declare function isRowField(field: FieldDef<any>): field is RowField;
 type RowComponent = FieldComponent<RowField<RowAllowedChildren[]>>;
 
+/**
+ * Custom validator function signature using Angular's public FieldContext API
+ *
+ * @template TValue The type of value stored in the field being validated
+ */
+type CustomValidator<TValue = unknown> = (ctx: FieldContext<TValue>, params?: Record<string, unknown>) => ValidationError$1 | ValidationError$1[] | null;
+/**
+ * Async custom validator configuration using Angular's resource-based API
+ *
+ * @template TValue The type of value stored in the field being validated
+ * @template TParams The type of params passed to the resource
+ * @template TResult The type of result returned by the resource
+ */
+interface AsyncCustomValidator<TValue = unknown, TParams = unknown, TResult = unknown> {
+    /**
+     * Function that receives field context and returns resource params.
+     * Params will be tracked as a signal and trigger resource reload when changed.
+     */
+    readonly params: (ctx: FieldContext<TValue>, config?: Record<string, unknown>) => TParams;
+    /**
+     * Function that creates a ResourceRef from the params signal.
+     * The resource will be automatically managed by Angular's lifecycle.
+     */
+    readonly factory: (params: Signal<TParams | undefined>) => ResourceRef<TResult | undefined>;
+    /**
+     * Optional function to map successful resource result to validation errors.
+     * Return null if validation passes, or ValidationError/ValidationError[] if validation fails.
+     */
+    readonly onSuccess?: (result: TResult, ctx: FieldContext<TValue>) => TreeValidationResult;
+    /**
+     * Optional error handler for resource errors (network failures, etc.).
+     * Return null to ignore the error, or ValidationError to display it to the user.
+     */
+    readonly onError?: (error: unknown, ctx: FieldContext<TValue>) => ValidationError$1 | ValidationError$1[] | null;
+}
+/** HTTP request configuration for validateHttp API */
+interface HttpResourceRequest {
+    url: string;
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    body?: unknown;
+    headers?: Record<string, string | string[]>;
+}
+/**
+ * HTTP-based validator configuration for Angular's validateHttp API
+ *
+ * @template TValue The type of value stored in the field being validated
+ * @template TResult The type of HTTP response
+ */
+interface HttpCustomValidator<TValue = unknown, TResult = unknown> {
+    /**
+     * Function that returns the HTTP request configuration.
+     * Can return:
+     * - `undefined` to skip validation (e.g., if field is empty)
+     * - `string` for simple GET requests (just the URL)
+     * - `HttpResourceRequest` for full control (method, body, headers)
+     */
+    readonly request: (ctx: FieldContext<TValue>, config?: Record<string, unknown>) => string | HttpResourceRequest | undefined;
+    /** REQUIRED function to map successful HTTP response to validation errors. */
+    readonly onSuccess: (result: TResult, ctx: FieldContext<TValue>) => TreeValidationResult;
+    /**
+     * Optional error handler for HTTP errors (network failures, 4xx/5xx status codes).
+     * Return null to ignore the error, or ValidationError to display it to the user.
+     */
+    readonly onError?: (error: unknown, ctx: FieldContext<TValue>) => ValidationError$1 | ValidationError$1[] | null;
+}
+
+/** Mapping configuration for interpreting HTTP responses as validation results. */
+interface HttpValidationResponseMapping {
+    /** Expression evaluated with scope `{ response }`. Must evaluate to `true` (strict boolean) to be valid. */
+    validWhen: string;
+    /** Error kind returned when validation fails — maps to field-level `validationMessages` */
+    errorKind: string;
+    /**
+     * Parameters to include in the validation error for message interpolation.
+     * Map of parameter names to expressions evaluated against `{ response }`.
+     */
+    errorParams?: Record<string, string>;
+}
+
+/** Base configuration shared by all validators */
+interface BaseValidatorConfig {
+    /** Conditional logic for when validator applies */
+    when?: ConditionalExpression;
+}
+/** Built-in validator configuration (required, email, min, max, etc.) */
+interface BuiltInValidatorConfig extends BaseValidatorConfig {
+    /** Validator type identifier */
+    type: 'required' | 'email' | 'min' | 'max' | 'minLength' | 'maxLength' | 'pattern';
+    /** Static value for the validator (e.g., min value, pattern) */
+    value?: number | string | RegExp;
+    /** Dynamic value expression that evaluates to validator parameter */
+    expression?: string;
+}
+/**
+ * Custom validator configuration using Angular's public FieldContext API.
+ * Returns ValidationError | ValidationError[] | null synchronously.
+ */
+interface CustomValidatorConfig extends BaseValidatorConfig {
+    /** Validator type identifier */
+    type: 'custom';
+    /** Name of registered validator function (function-based pattern) */
+    functionName?: string;
+    /**
+     * Inline custom validator (code-only authoring).
+     * Mutually exclusive with `functionName`. NOT JSON-serializable.
+     */
+    fn?: CustomValidator;
+    /** Optional parameters to pass to validator function */
+    params?: Record<string, unknown>;
+    /** JavaScript expression to evaluate (expression-based pattern) */
+    expression?: string;
+    /** Error kind for expression-based validators - links to validationMessages */
+    kind?: string;
+    /**
+     * Parameters to include in error object for message interpolation (expression-based pattern)
+     * Map of parameter names to expressions that will be evaluated in the same context as the validation expression
+     */
+    errorParams?: Record<string, string>;
+}
+/**
+ * Shared fields for both branches of {@link AsyncValidatorConfig}.
+ *
+ * @internal
+ */
+interface AsyncValidatorConfigShared extends BaseValidatorConfig {
+    /** Validator type identifier. */
+    type: 'async';
+    /** Optional parameters to pass to validator function */
+    params?: Record<string, unknown>;
+}
+/**
+ * Async custom validator configuration using Angular's `validateAsync` API.
+ * Returns Observable<ValidationError | ValidationError[] | null>.
+ */
+type AsyncValidatorConfig = (AsyncValidatorConfigShared & {
+    /** Name of registered async validator function */
+    functionName: string;
+    /** Inline form is forbidden when `functionName` is set */
+    fn?: never;
+}) | (AsyncValidatorConfigShared & {
+    /** Inline async validator. Mutually exclusive with `functionName`. */
+    fn: AsyncCustomValidator;
+    /** Registered form is forbidden when `fn` is set */
+    functionName?: never;
+});
+/**
+ * Shared fields for both branches of {@link FunctionHttpValidatorConfig}.
+ *
+ * @internal
+ */
+interface FunctionHttpValidatorConfigShared extends BaseValidatorConfig {
+    /** Validator type identifier. */
+    type: 'http';
+    /** Optional parameters to pass to HTTP validator */
+    params?: Record<string, unknown>;
+}
+/** Function-based HTTP validator configuration. Uses Angular's `validateHttp` API. */
+type FunctionHttpValidatorConfig = (FunctionHttpValidatorConfigShared & {
+    /** Name of registered HTTP validator configuration */
+    functionName: string;
+    /** Inline form is forbidden when `functionName` is set */
+    fn?: never;
+}) | (FunctionHttpValidatorConfigShared & {
+    /** Inline HTTP validator. Mutually exclusive with `functionName`. */
+    fn: HttpCustomValidator;
+    /** Registered form is forbidden when `fn` is set */
+    functionName?: never;
+});
+/** Declarative HTTP validator configuration — fully JSON-serializable, no function registration required. */
+interface DeclarativeHttpValidatorConfig extends BaseValidatorConfig {
+    /** Validator type identifier */
+    type: 'http';
+    /** HTTP request configuration with expression-based query params and body */
+    http: HttpRequestConfig;
+    /** Mapping that interprets the HTTP response as a validation result */
+    responseMapping: HttpValidationResponseMapping;
+}
+/**
+ * Configuration for signal forms validator functions that can be serialized from API.
+ * Discriminated union type for type-safe validator configuration.
+ */
+type ValidatorConfig = BuiltInValidatorConfig | CustomValidatorConfig | AsyncValidatorConfig | FunctionHttpValidatorConfig | DeclarativeHttpValidatorConfig;
+/** Type guard to distinguish function-based HTTP validators from declarative ones. */
+declare function isFunctionHttpValidator(config: FunctionHttpValidatorConfig | DeclarativeHttpValidatorConfig): config is FunctionHttpValidatorConfig;
+
+/**
+ * Re-export Angular's ValidationError for consistency
+ * This replaces our custom ValidationError interface
+ */
+type ValidationError = ValidationError$1;
+/**
+ * Resolves a validation message from the validation error, so error params
+ * (e.g. maxLength, min) can be passed to an i18n layer natively.
+ */
+type ValidationMessageResolver = (error: ValidationError) => DynamicText;
+/** A validation message: static or reactive text, or a function of the validation error. */
+type ValidationMessage = DynamicText | ValidationMessageResolver;
+interface ValidationMessages {
+    required?: ValidationMessage;
+    email?: ValidationMessage;
+    min?: ValidationMessage;
+    max?: ValidationMessage;
+    minLength?: ValidationMessage;
+    maxLength?: ValidationMessage;
+    pattern?: ValidationMessage;
+    [key: string]: ValidationMessage | undefined;
+}
+
+/**
+ * Tree-level validation for container fields (`group` / `array`).
+ *
+ * A validator here runs against the container's own subtree: `ctx.value()` is the group's
+ * object or the array's item list. Layout containers (`page`, `row`, `container`) flatten
+ * into their parent and have no schema path, so they are excluded.
+ */
+interface ContainerValidation {
+    /**
+     * Marks every descendant required. An inherited default, not a rule on the container —
+     * a descendant's own `required` wins, including `false`. Use `minLength` for array size.
+     */
+    readonly required?: boolean;
+    /** Validators applied to the container's own schema path. Gated by `validateWhenHidden`. */
+    readonly validators?: ValidatorConfig[];
+    /**
+     * Messages keyed by error `kind`. Rendered by the `field-errors` wrapper, attached
+     * automatically when the container declares `validators`.
+     */
+    readonly validationMessages?: ValidationMessages;
+}
+
 /**
  * Group field interface for creating logical field groupings that map to object values
  * Groups create nested form structures where child field values are collected into an object
  * This is a programmatic grouping only - users cannot customize this field type
  */
-interface GroupField<TFields extends readonly GroupAllowedChildren[] = readonly GroupAllowedChildren[]> extends FieldDef<never> {
+interface GroupField<TFields extends readonly GroupAllowedChildren[] = readonly GroupAllowedChildren[]> extends FieldDef<never>, ContainerValidation {
     type: 'group';
     readonly fields: TFields;
     /** Groups do not have a label property - they are logical containers only * */
@@ -573,7 +853,7 @@ type ArrayItemTemplate = readonly ArrayAllowedChildren[];
  */
 type ArrayItemDefinition = ArrayAllowedChildren | ArrayItemTemplate;
 /** Array field interface for creating dynamic field collections that map to array values. */
-interface ArrayField<TFields extends readonly ArrayItemDefinition[] = readonly ArrayItemDefinition[]> extends FieldDef<never> {
+interface ArrayField<TFields extends readonly ArrayItemDefinition[] = readonly ArrayItemDefinition[]> extends FieldDef<never>, ContainerValidation {
     type: 'array';
     /**
      * Array of item definitions. Each element defines one array item:
@@ -619,7 +899,7 @@ interface ArrayButtonConfig {
     readonly props?: Record<string, unknown>;
 }
 /** Simplified array field interface for common use cases. */
-interface SimplifiedArrayField extends FieldDef<never> {
+interface SimplifiedArrayField extends FieldDef<never>, ContainerValidation {
     type: 'array';
     /**
      * Template defining the structure of a single array item.
@@ -795,282 +1075,97 @@ type InferSingleTemplateValueBase<T, D extends number> = T extends {
         type: 'number';
     };
 } ? number : T extends {
-    type: 'checkbox' | 'toggle';
-} ? boolean : T extends {
-    value: infer V;
-} ? [V] extends [null] ? string : Widen<V, Depth[D]> : string;
-type InferSingleTemplateValue<T, D extends number> = T extends {
-    nullable: true;
-} ? InferSingleTemplateValueBase<T, D> | null : InferSingleTemplateValueBase<T, D>;
-/**
- * Infers the value type for an array field.
- * Handles four cases:
- * 1. Simplified array with template + value → infer item type from value
- * 2. Simplified array with array template (no value) → infer object type from template fields
- * 3. Simplified array with single-field template (no value) → infer primitive type from template field
- * 4. Full-API array with fields → infer from children
- */
-type InferArrayValue<T, D extends number> = T extends {
-    template: unknown;
-    value: readonly (infer Item)[];
-} ? Widen<Item>[] : T extends {
-    template: infer TArr;
-} ? TArr extends readonly RegisteredFieldTypes[] ? InferFormValueWithDepth<[...TArr], Depth[D]>[] : InferSingleTemplateValue<TArr, D>[] : T extends {
-    fields: infer F;
-} ? InferContainerChildren<F, Depth[D], unknown>[] : unknown[];
-/**
- * Recurse into a container's child fields, but only when they form a fixed-length
- * tuple — i.e. a config authored with `as const`. A general `RegisteredFieldTypes[]`
- * array (notably the base default `InferFormValue<RegisteredFieldTypes[]>` over the
- * whole registry) bails to `TFallback`; recursing there would make the type explode
- * past TypeScript's union-complexity limit (TS2590) and break consumers of the
- * abstract `FormConfig`. `[...F]` re-mutabilises the readonly tuple for the inner
- * `InferFormValueWithDepth` constraint.
- */
-type InferContainerChildren<F, D extends number, TFallback> = F extends readonly RegisteredFieldTypes[] ? number extends F['length'] ? TFallback : InferFormValueWithDepth<[...F], D> : TFallback;
-/** Process a single field and determine its contribution to the form value type */
-type ProcessField<T, D extends number = 5> = [D] extends [never] ? Record<string, unknown> : T extends {
-    type: 'page' | 'row';
-    fields: infer F;
-} ? InferContainerChildren<F, Depth[D], never> : T extends {
-    type: 'group';
-    key: infer K;
-    fields: infer F;
-} ? K extends string ? {
-    [P in K]: InferContainerChildren<F, Depth[D], Record<string, unknown>>;
-} : never : T extends {
-    type: 'array';
-    key: infer K;
-} ? K extends string ? {
-    [P in K]: InferArrayValue<T, D>;
-} : never : T extends {
-    type: 'text';
-} ? never : T extends {
-    type: 'submit' | 'button' | 'next' | 'previous' | 'addArrayItem' | 'add-array-item' | 'prependArrayItem' | 'prepend-array-item' | 'insertArrayItem' | 'insert-array-item' | 'removeArrayItem' | 'remove-array-item' | 'popArrayItem' | 'pop-array-item' | 'shiftArrayItem' | 'shift-array-item';
-} ? never : T extends {
-    key: infer K;
-    value: infer V;
-} ? K extends string ? {
-    [P in K]: MaybeOptional<T, InferValueType<T, V>>;
-} : never : T extends {
-    key: infer K;
-} ? K extends string ? {
-    [P in K]: MaybeOptional<T, T extends {
-        nullable: true;
-    } ? string | null : string>;
-} : never : never;
-/** Internal helper with depth tracking */
-type InferFormValueWithDepth<T extends RegisteredFieldTypes[], D extends number = 5> = UnionToIntersection<ProcessField<T[number], D>>;
-/** Helper to extract fields from either fields array or FormConfig */
-type ExtractFields<T> = T extends {
-    fields: infer TFields;
-} ? TFields extends readonly RegisteredFieldTypes[] ? TFields : never : T extends readonly RegisteredFieldTypes[] ? T : never;
-/**
- * Infer form value type from fields array or FormConfig.
- * Recursively processes nested structures and merges the results.
- * Limited to 5 levels of nesting to prevent infinite type instantiation.
- */
-type InferFormValue<T> = ExtractFields<T> extends readonly RegisteredFieldTypes[] ? InferFormValueWithDepth<ExtractFields<T> extends RegisteredFieldTypes[] ? ExtractFields<T> : [...ExtractFields<T>], 5> : never;
-/**
- * Default `TModel` for `DynamicForm` / `FormStateManager` generics.
- *
- * Equals `InferFormValue<T>` for any concrete config (an object type). Falls back
- * to `Record<string, unknown>` only when inference yields a non-record — e.g. an
- * empty `fields` array, where `InferFormValue` is `unknown` — so the `TModel
- * extends Record<string, unknown>` bound always holds by construction.
- *
- * Crucially, unlike the older `InferFormValue<T> & Record<string, unknown>`
- * default, this does NOT graft an index signature onto the model. That matters at
- * the consumer call site: the index signature made `value['anyTypo']` resolve to
- * `unknown` instead of erroring, silently defeating the typo-safety the inference
- * is meant to provide.
- */
-type InferFormModel<T, M = InferFormValue<T>> = M extends Record<string, unknown> ? M : Record<string, unknown>;
-
-/**
- * Custom validator function signature using Angular's public FieldContext API
- *
- * @template TValue The type of value stored in the field being validated
- */
-type CustomValidator<TValue = unknown> = (ctx: FieldContext<TValue>, params?: Record<string, unknown>) => ValidationError$1 | ValidationError$1[] | null;
-/**
- * Async custom validator configuration using Angular's resource-based API
- *
- * @template TValue The type of value stored in the field being validated
- * @template TParams The type of params passed to the resource
- * @template TResult The type of result returned by the resource
- */
-interface AsyncCustomValidator<TValue = unknown, TParams = unknown, TResult = unknown> {
-    /**
-     * Function that receives field context and returns resource params.
-     * Params will be tracked as a signal and trigger resource reload when changed.
-     */
-    readonly params: (ctx: FieldContext<TValue>, config?: Record<string, unknown>) => TParams;
-    /**
-     * Function that creates a ResourceRef from the params signal.
-     * The resource will be automatically managed by Angular's lifecycle.
-     */
-    readonly factory: (params: Signal<TParams | undefined>) => ResourceRef<TResult | undefined>;
-    /**
-     * Optional function to map successful resource result to validation errors.
-     * Return null if validation passes, or ValidationError/ValidationError[] if validation fails.
-     */
-    readonly onSuccess?: (result: TResult, ctx: FieldContext<TValue>) => TreeValidationResult;
-    /**
-     * Optional error handler for resource errors (network failures, etc.).
-     * Return null to ignore the error, or ValidationError to display it to the user.
-     */
-    readonly onError?: (error: unknown, ctx: FieldContext<TValue>) => ValidationError$1 | ValidationError$1[] | null;
-}
-/** HTTP request configuration for validateHttp API */
-interface HttpResourceRequest {
-    url: string;
-    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
-    body?: unknown;
-    headers?: Record<string, string | string[]>;
-}
-/**
- * HTTP-based validator configuration for Angular's validateHttp API
- *
- * @template TValue The type of value stored in the field being validated
- * @template TResult The type of HTTP response
- */
-interface HttpCustomValidator<TValue = unknown, TResult = unknown> {
-    /**
-     * Function that returns the HTTP request configuration.
-     * Can return:
-     * - `undefined` to skip validation (e.g., if field is empty)
-     * - `string` for simple GET requests (just the URL)
-     * - `HttpResourceRequest` for full control (method, body, headers)
-     */
-    readonly request: (ctx: FieldContext<TValue>, config?: Record<string, unknown>) => string | HttpResourceRequest | undefined;
-    /** REQUIRED function to map successful HTTP response to validation errors. */
-    readonly onSuccess: (result: TResult, ctx: FieldContext<TValue>) => TreeValidationResult;
-    /**
-     * Optional error handler for HTTP errors (network failures, 4xx/5xx status codes).
-     * Return null to ignore the error, or ValidationError to display it to the user.
-     */
-    readonly onError?: (error: unknown, ctx: FieldContext<TValue>) => ValidationError$1 | ValidationError$1[] | null;
-}
-
-/** Mapping configuration for interpreting HTTP responses as validation results. */
-interface HttpValidationResponseMapping {
-    /** Expression evaluated with scope `{ response }`. Must evaluate to `true` (strict boolean) to be valid. */
-    validWhen: string;
-    /** Error kind returned when validation fails — maps to field-level `validationMessages` */
-    errorKind: string;
-    /**
-     * Parameters to include in the validation error for message interpolation.
-     * Map of parameter names to expressions evaluated against `{ response }`.
-     */
-    errorParams?: Record<string, string>;
-}
-
-/** Base configuration shared by all validators */
-interface BaseValidatorConfig {
-    /** Conditional logic for when validator applies */
-    when?: ConditionalExpression;
-}
-/** Built-in validator configuration (required, email, min, max, etc.) */
-interface BuiltInValidatorConfig extends BaseValidatorConfig {
-    /** Validator type identifier */
-    type: 'required' | 'email' | 'min' | 'max' | 'minLength' | 'maxLength' | 'pattern';
-    /** Static value for the validator (e.g., min value, pattern) */
-    value?: number | string | RegExp;
-    /** Dynamic value expression that evaluates to validator parameter */
-    expression?: string;
-}
-/**
- * Custom validator configuration using Angular's public FieldContext API.
- * Returns ValidationError | ValidationError[] | null synchronously.
- */
-interface CustomValidatorConfig extends BaseValidatorConfig {
-    /** Validator type identifier */
-    type: 'custom';
-    /** Name of registered validator function (function-based pattern) */
-    functionName?: string;
-    /**
-     * Inline custom validator (code-only authoring).
-     * Mutually exclusive with `functionName`. NOT JSON-serializable.
-     */
-    fn?: CustomValidator;
-    /** Optional parameters to pass to validator function */
-    params?: Record<string, unknown>;
-    /** JavaScript expression to evaluate (expression-based pattern) */
-    expression?: string;
-    /** Error kind for expression-based validators - links to validationMessages */
-    kind?: string;
-    /**
-     * Parameters to include in error object for message interpolation (expression-based pattern)
-     * Map of parameter names to expressions that will be evaluated in the same context as the validation expression
-     */
-    errorParams?: Record<string, string>;
-}
+    type: 'checkbox' | 'toggle';
+} ? boolean : T extends {
+    value: infer V;
+} ? [V] extends [null] ? string : Widen<V, Depth[D]> : string;
+type InferSingleTemplateValue<T, D extends number> = T extends {
+    nullable: true;
+} ? InferSingleTemplateValueBase<T, D> | null : InferSingleTemplateValueBase<T, D>;
 /**
- * Shared fields for both branches of {@link AsyncValidatorConfig}.
- *
- * @internal
+ * Infers the value type for an array field.
+ * Handles four cases:
+ * 1. Simplified array with template + value → infer item type from value
+ * 2. Simplified array with array template (no value) → infer object type from template fields
+ * 3. Simplified array with single-field template (no value) → infer primitive type from template field
+ * 4. Full-API array with fields → infer from children
  */
-interface AsyncValidatorConfigShared extends BaseValidatorConfig {
-    /** Validator type identifier. */
-    type: 'async';
-    /** Optional parameters to pass to validator function */
-    params?: Record<string, unknown>;
-}
+type InferArrayValue<T, D extends number> = T extends {
+    template: unknown;
+    value: readonly (infer Item)[];
+} ? Widen<Item>[] : T extends {
+    template: infer TArr;
+} ? TArr extends readonly RegisteredFieldTypes[] ? InferFormValueWithDepth<[...TArr], Depth[D]>[] : InferSingleTemplateValue<TArr, D>[] : T extends {
+    fields: infer F;
+} ? InferContainerChildren<F, Depth[D], unknown>[] : unknown[];
 /**
- * Async custom validator configuration using Angular's `validateAsync` API.
- * Returns Observable<ValidationError | ValidationError[] | null>.
+ * Recurse into a container's child fields, but only when they form a fixed-length
+ * tuple — i.e. a config authored with `as const`. A general `RegisteredFieldTypes[]`
+ * array (notably the base default `InferFormValue<RegisteredFieldTypes[]>` over the
+ * whole registry) bails to `TFallback`; recursing there would make the type explode
+ * past TypeScript's union-complexity limit (TS2590) and break consumers of the
+ * abstract `FormConfig`. `[...F]` re-mutabilises the readonly tuple for the inner
+ * `InferFormValueWithDepth` constraint.
  */
-type AsyncValidatorConfig = (AsyncValidatorConfigShared & {
-    /** Name of registered async validator function */
-    functionName: string;
-    /** Inline form is forbidden when `functionName` is set */
-    fn?: never;
-}) | (AsyncValidatorConfigShared & {
-    /** Inline async validator. Mutually exclusive with `functionName`. */
-    fn: AsyncCustomValidator;
-    /** Registered form is forbidden when `fn` is set */
-    functionName?: never;
-});
+type InferContainerChildren<F, D extends number, TFallback> = F extends readonly RegisteredFieldTypes[] ? number extends F['length'] ? TFallback : InferFormValueWithDepth<[...F], D> : TFallback;
+/** Process a single field and determine its contribution to the form value type */
+type ProcessField<T, D extends number = 5> = [D] extends [never] ? Record<string, unknown> : T extends {
+    type: 'page' | 'row';
+    fields: infer F;
+} ? InferContainerChildren<F, Depth[D], never> : T extends {
+    type: 'group';
+    key: infer K;
+    fields: infer F;
+} ? K extends string ? {
+    [P in K]: InferContainerChildren<F, Depth[D], Record<string, unknown>>;
+} : never : T extends {
+    type: 'array';
+    key: infer K;
+} ? K extends string ? {
+    [P in K]: InferArrayValue<T, D>;
+} : never : T extends {
+    type: 'text';
+} ? never : T extends {
+    type: 'submit' | 'button' | 'next' | 'previous' | 'addArrayItem' | 'add-array-item' | 'prependArrayItem' | 'prepend-array-item' | 'insertArrayItem' | 'insert-array-item' | 'removeArrayItem' | 'remove-array-item' | 'popArrayItem' | 'pop-array-item' | 'shiftArrayItem' | 'shift-array-item';
+} ? never : T extends {
+    key: infer K;
+    value: infer V;
+} ? K extends string ? {
+    [P in K]: MaybeOptional<T, InferValueType<T, V>>;
+} : never : T extends {
+    key: infer K;
+} ? K extends string ? {
+    [P in K]: MaybeOptional<T, T extends {
+        nullable: true;
+    } ? string | null : string>;
+} : never : never;
+/** Internal helper with depth tracking */
+type InferFormValueWithDepth<T extends RegisteredFieldTypes[], D extends number = 5> = UnionToIntersection<ProcessField<T[number], D>>;
+/** Helper to extract fields from either fields array or FormConfig */
+type ExtractFields<T> = T extends {
+    fields: infer TFields;
+} ? TFields extends readonly RegisteredFieldTypes[] ? TFields : never : T extends readonly RegisteredFieldTypes[] ? T : never;
 /**
- * Shared fields for both branches of {@link FunctionHttpValidatorConfig}.
- *
- * @internal
+ * Infer form value type from fields array or FormConfig.
+ * Recursively processes nested structures and merges the results.
+ * Limited to 5 levels of nesting to prevent infinite type instantiation.
  */
-interface FunctionHttpValidatorConfigShared extends BaseValidatorConfig {
-    /** Validator type identifier. */
-    type: 'http';
-    /** Optional parameters to pass to HTTP validator */
-    params?: Record<string, unknown>;
-}
-/** Function-based HTTP validator configuration. Uses Angular's `validateHttp` API. */
-type FunctionHttpValidatorConfig = (FunctionHttpValidatorConfigShared & {
-    /** Name of registered HTTP validator configuration */
-    functionName: string;
-    /** Inline form is forbidden when `functionName` is set */
-    fn?: never;
-}) | (FunctionHttpValidatorConfigShared & {
-    /** Inline HTTP validator. Mutually exclusive with `functionName`. */
-    fn: HttpCustomValidator;
-    /** Registered form is forbidden when `fn` is set */
-    functionName?: never;
-});
-/** Declarative HTTP validator configuration — fully JSON-serializable, no function registration required. */
-interface DeclarativeHttpValidatorConfig extends BaseValidatorConfig {
-    /** Validator type identifier */
-    type: 'http';
-    /** HTTP request configuration with expression-based query params and body */
-    http: HttpRequestConfig;
-    /** Mapping that interprets the HTTP response as a validation result */
-    responseMapping: HttpValidationResponseMapping;
-}
+type InferFormValue<T> = ExtractFields<T> extends readonly RegisteredFieldTypes[] ? InferFormValueWithDepth<ExtractFields<T> extends RegisteredFieldTypes[] ? ExtractFields<T> : [...ExtractFields<T>], 5> : never;
 /**
- * Configuration for signal forms validator functions that can be serialized from API.
- * Discriminated union type for type-safe validator configuration.
+ * Default `TModel` for `DynamicForm` / `FormStateManager` generics.
+ *
+ * Equals `InferFormValue<T>` for any concrete config (an object type). Falls back
+ * to `Record<string, unknown>` only when inference yields a non-record — e.g. an
+ * empty `fields` array, where `InferFormValue` is `unknown` — so the `TModel
+ * extends Record<string, unknown>` bound always holds by construction.
+ *
+ * Crucially, unlike the older `InferFormValue<T> & Record<string, unknown>`
+ * default, this does NOT graft an index signature onto the model. That matters at
+ * the consumer call site: the index signature made `value['anyTypo']` resolve to
+ * `unknown` instead of erroring, silently defeating the typo-safety the inference
+ * is meant to provide.
  */
-type ValidatorConfig = BuiltInValidatorConfig | CustomValidatorConfig | AsyncValidatorConfig | FunctionHttpValidatorConfig | DeclarativeHttpValidatorConfig;
-/** Type guard to distinguish function-based HTTP validators from declarative ones. */
-declare function isFunctionHttpValidator(config: FunctionHttpValidatorConfig | DeclarativeHttpValidatorConfig): config is FunctionHttpValidatorConfig;
+type InferFormModel<T, M = InferFormValue<T>> = M extends Record<string, unknown> ? M : Record<string, unknown>;
 
 /** Special form-state conditions for button disabled logic. */
 type FormStateCondition = 
@@ -1454,29 +1549,6 @@ interface SchemaDefinition {
     subSchemas?: SchemaApplicationConfig[];
 }
 
-/**
- * Re-export Angular's ValidationError for consistency
- * This replaces our custom ValidationError interface
- */
-type ValidationError = ValidationError$1;
-/**
- * Resolves a validation message from the validation error, so error params
- * (e.g. maxLength, min) can be passed to an i18n layer natively.
- */
-type ValidationMessageResolver = (error: ValidationError) => DynamicText;
-/** A validation message: static or reactive text, or a function of the validation error. */
-type ValidationMessage = DynamicText | ValidationMessageResolver;
-interface ValidationMessages {
-    required?: ValidationMessage;
-    email?: ValidationMessage;
-    min?: ValidationMessage;
-    max?: ValidationMessage;
-    minLength?: ValidationMessage;
-    maxLength?: ValidationMessage;
-    pattern?: ValidationMessage;
-    [key: string]: ValidationMessage | undefined;
-}
-
 /**
  * The result type for submission actions.
  * Can be either a Promise or an Observable.
@@ -1584,11 +1656,28 @@ interface FormOptions {
     /** Default disabled behavior for next page buttons. */
     nextButton?: NextButtonOptions;
     /**
-     * For paged forms: how many pages on each side of the current page are eagerly
-     * mounted (the "preload window"). Pages outside the window render a lightweight
-     * placeholder and mount when navigation brings them into range.
+     * For paged forms: which page to start on. Use for deep links and session restore.
+     *
+     * Applied by the orchestrator as it initializes, so it is race-free even when the
+     * config arrives asynchronously. Out-of-range indices clamp to the last page;
+     * negative or non-finite values fall back to `0`. A hidden target resolves to the
+     * nearest visible page.
+     *
+     * The shorthand `initialPage: 4` lands on the page unconditionally, which is what
+     * restore usually wants. Pass `{ index, validate: true }` to run the same validity
+     * gate a forward `GoToPageEvent` uses, which stops on the first invalid page.
+     *
+     * A gated landing resolves once at mount, so supply restored values with the config.
+     *
+     * @default undefined (starts on page 0)
+     */
+    initialPage?: number | InitialPageConfig;
+    /**
+     * For paged forms: how many pages on each side of the current page are mounted
+     * during idle time (the "preload window"). The active page renders directly;
+     * pages outside the window remain lightweight placeholders.
      *
-     * `0` mounts only the current page; `1` mounts ±1 for flicker-free sequential
+     * `0` mounts only the current page; `1` preloads ±1 on idle for flicker-free sequential
      * navigation; higher values pre-warm more pages for jump navigation at the cost
      * of more initial DOM + change detection.
      *
@@ -1604,7 +1693,16 @@ interface FormOptions {
      *
      * `true` enables windowing using the global `withFieldWindowing()` defaults;
      * `false` force-disables it even if the global feature is enabled; an object
-     * enables it with per-form `eager` / `placeholderHeight` overrides.
+     * enables it with per-form `eager` / `placeholderHeight` / `park` overrides.
+     *
+     * `park` holds scrolled-away fields out of change detection while leaving
+     * their DOM in place, so they stay findable, autofillable and reachable by
+     * assistive tech. It is off unless `withFieldWindowing()` is used, because it
+     * suspends model → DOM updates for a scrolled-away field until it returns.
+     * Set `park: true` to opt in without deferred mounting, `park: false` to opt
+     * out, or `park: { margin }` to change how far outside the viewport stays live.
+     * The margin follows `IntersectionObserver.rootMargin` and accepts one to four
+     * pixel or percentage values; unsupported units fall back to the inherited margin.
      *
      * Overrides the global `withFieldWindowing(...)` default for this form.
      *
@@ -1613,6 +1711,9 @@ interface FormOptions {
     fieldWindowing?: boolean | {
         eager?: number;
         placeholderHeight?: string;
+        park?: boolean | {
+            margin?: string;
+        };
     };
     /**
      * Whether to exclude values of hidden fields from submission output.
@@ -1644,6 +1745,67 @@ interface FormOptions {
      * @default undefined (uses global setting)
      */
     emitFormValueOnEvents?: boolean;
+    /**
+     * Exposes this form to browser AI agents as WebMCP tools.
+     *
+     * Requires the `withExperimentalWebMcp()` feature on `provideDynamicForm(...)`. Registers
+     * `fill_{name}`, which applies a partial patch of values and reports the
+     * form's state back. Submission stays off unless `allowSubmit` is set.
+     *
+     * Experimental: WebMCP is an emerging standard and Angular's underlying APIs
+     * are marked experimental, so this may change outside a major version.
+     *
+     * @example
+     * ```typescript
+     * options: { webMcp: { name: 'invoice', description: 'Create an invoice for a customer.' } }
+     * ```
+     *
+     * @default undefined (form is not exposed to agents)
+     */
+    webMcp?: WebMcpToolOptions;
+}
+/** Identifies a form's WebMCP tools to connected AI agents. */
+interface WebMcpToolOptions {
+    /**
+     * Base name for this form's tools, used as `fill_{name}` and (when submission
+     * is allowed) `submit_{name}`. Must be unique across every form on the page.
+     */
+    name: string;
+    /** What this form is for, and when an agent should reach for it. */
+    description: string;
+    /**
+     * Whether an agent may submit this form directly.
+     *
+     * Off by default. Every registered tool is callable by any agent that reaches
+     * the page, including one acting on injected instructions from elsewhere, so
+     * submission is treated as the consequential step and kept opt-in. With it
+     * off, an agent can still fill the form and a human presses the button.
+     *
+     * Leave it off for anything that spends money, sends a message, or cannot be
+     * undone.
+     *
+     * @default false
+     */
+    allowSubmit?: boolean;
+    /**
+     * How much of the form a tool response hands back to the agent.
+     *
+     * `'changed'` (the default) returns only the values the call itself set, plus
+     * which fields apply, which are still empty, and any validation errors. That
+     * is enough for an agent to orient itself and correct its own work without
+     * being handed every value the form already held — prefilled personal data,
+     * identifiers, anything a user typed before the agent arrived.
+     *
+     * `'all'` returns the whole model, minus fields whose `webMcp.readable` is
+     * off. Choose it deliberately: every registered tool is callable by any agent
+     * that reaches the page, and Chrome's guidance is that even a read-only tool
+     * can reveal user information.
+     *
+     * @see https://developer.chrome.com/docs/ai/webmcp/secure-tools
+     *
+     * @default 'changed'
+     */
+    readback?: 'changed' | 'all';
 }
 /** Options for controlling submit button disabled behavior. */
 interface SubmitButtonOptions {
@@ -1660,6 +1822,18 @@ interface SubmitButtonOptions {
      */
     disableWhileSubmitting?: boolean;
 }
+/** Which page a paged form starts on, for deep links and session restore. */
+interface InitialPageConfig {
+    /** Target page index (0-based). */
+    index: number;
+    /**
+     * Whether to apply the forward-jump validity gate, stopping on the first
+     * invalid page instead of landing on the target.
+     *
+     * @default false
+     */
+    validate?: boolean;
+}
 /** Options for controlling next page button disabled behavior. */
 interface NextButtonOptions {
     /**
@@ -1821,6 +1995,24 @@ interface RowWrapper {
     readonly type: 'row';
 }
 
+/**
+ * Renders the wrapped field's validation errors, for a leaf or a container.
+ *
+ * On a container it is the only thing that can render the message — a `group` / `array`
+ * has no adapter field component — so it is appended automatically when the container
+ * declares `validators`. On a leaf it is opt-in: adding it takes error rendering over
+ * from the field component, which suppresses its own via `FIELD_ERROR_DISPLAY`.
+ *
+ * To restyle it, register a `WrapperTypeDefinition` with the same
+ * `wrapperName: 'field-errors'` — the later registration wins, so an adapter or an app
+ * can swap in its own component without touching config.
+ */
+interface FieldErrorsWrapper {
+    readonly type: 'field-errors';
+    /** Messages keyed by error `kind`. Containers forward their own `validationMessages`. */
+    readonly validationMessages?: ValidationMessages;
+}
+
 /** Container fields registry - augment this interface to add custom container fields */
 interface FieldRegistryContainers {
     page: PageField;
@@ -1838,6 +2030,7 @@ interface FieldRegistryLeaves {
 interface FieldRegistryWrappers {
     css: CssWrapper;
     row: RowWrapper;
+    'field-errors': FieldErrorsWrapper;
 }
 /**
  * Global interface for dynamic form field definitions with categorization
@@ -1916,6 +2109,12 @@ interface WrapperTypeDefinition<T extends WrapperConfig = WrapperConfig> {
     loadComponent: LazyComponentLoader;
     /** Field types this wrapper should auto-apply to. */
     types?: readonly string[];
+    /**
+     * Declares that this wrapper renders the wrapped field's errors, so the default
+     * `field-errors` wrapper is not appended next to it. Needed here as well as via
+     * `provideFieldErrorDisplay`: the chain resolves before any component exists to ask.
+     */
+    rendersFieldErrors?: boolean;
 }
 /** Type guard for WrapperTypeDefinition. */
 declare function isWrapperTypeDefinition(value: unknown): value is WrapperTypeDefinition;
@@ -1941,9 +2140,11 @@ interface FieldWrapper {
     readonly fieldComponent: Signal<ViewContainerRef>;
 }
 /** Injection token for the wrapper type registry. */
-declare const WRAPPER_REGISTRY: InjectionToken<Map<string, WrapperTypeDefinition<_ng_forge_dynamic_forms_internal.RowWrapper | _ng_forge_dynamic_forms_internal.CssWrapper>>>;
+declare const WRAPPER_REGISTRY: InjectionToken<Map<string, WrapperTypeDefinition<_ng_forge_dynamic_forms_internal.RowWrapper | _ng_forge_dynamic_forms_internal.CssWrapper | _ng_forge_dynamic_forms_internal.FieldErrorsWrapper>>>;
 /** Component cache for loaded wrapper components. */
 declare const WRAPPER_COMPONENT_CACHE: InjectionToken<Map<string, Type<unknown>>>;
+/** Pending wrapper loads, shared by preloading and the normal render path. */
+declare const WRAPPER_COMPONENT_LOAD_CACHE: InjectionToken<Map<string, Promise<Type<unknown> | undefined>>>;
 /**
  * Pre-computed reverse index: `fieldType → WrapperConfig[]` for every
  * registered `WrapperTypeDefinition.types` entry. Built once in the
@@ -2919,8 +3120,122 @@ declare class RootFormRegistryService {
     constructor(formValue: Signal<Record<string, unknown>>, rootForm: Signal<FieldTree<Record<string, unknown>> | undefined>);
 }
 
-declare function applyValidator(config: ValidatorConfig, fieldPath: SchemaPath<any> | SchemaPathTree<any>): void;
-declare function applyValidators(configs: ValidatorConfig[], fieldPath: SchemaPath<any> | SchemaPathTree<any>): void;
+/** Resolved validation error with interpolated message */
+interface ResolvedError {
+    kind: string;
+    message: string;
+}
+/**
+ * Factory function that creates a signal of resolved validation errors
+ * Handles async resolution of DynamicText validation messages
+ *
+ * @param field - Signal containing the FieldTree, or `undefined` before it
+ *   exists (containers resolve their node lazily from the parent tree)
+ * @param validationMessages - Signal containing custom field-level validation messages
+ * @param defaultValidationMessages - Signal containing default validation messages (fallback)
+ * @param injector - Optional injector for DynamicText resolution
+ * @returns Signal<ResolvedError[]> - Reactively resolved error messages
+ */
+declare function createResolvedErrorsSignal<T>(field: Signal<FieldTree<T> | undefined>, validationMessages: Signal<ValidationMessages | undefined>, defaultValidationMessages?: Signal<ValidationMessages | undefined>, injector?: Injector): Signal<ResolvedError[]>;
+
+/** A wrapper's claim to render errors, scoped to the one field key it wraps. */
+interface FieldErrorDisplayClaim {
+    /** Key of the field whose errors this wrapper renders; `undefined` before inputs bind. */
+    readonly claimedKey: Signal<string | undefined>;
+}
+/**
+ * Marks that a wrapper is rendering a field's errors, so that field's component stops
+ * rendering its own and the message appears once.
+ *
+ * The claim carries a key because a wrapper's providers reach every descendant: a wrapper
+ * around an `array` would otherwise silence the errors of every input inside it. A field
+ * suppresses its own rendering only when the claimed key is its own.
+ *
+ * Not `multi` — element injectors shadow rather than merge, so a nested claim would hide
+ * the outer one regardless.
+ */
+declare const FIELD_ERROR_DISPLAY: InjectionToken<FieldErrorDisplayClaim>;
+/** The error surface a wrapper gets, mirroring what `NgForgeField` exposes to field components. */
+interface FieldErrors {
+    /** Every resolved error, regardless of whether it should be shown yet. */
+    readonly errors: Signal<ResolvedError[]>;
+    /** Whether errors are ready to show — invalid, touched, and non-empty. */
+    readonly showErrors: Signal<boolean>;
+    /** `errors()` gated by `showErrors()`. This is what a template should render. */
+    readonly errorsToDisplay: Signal<ResolvedError[]>;
+    /** `{key}-error`, for wiring `aria-describedby` on the wrapped control. */
+    readonly errorId: Signal<string>;
+}
+interface FieldErrorsOptions {
+    /** The wrapper's `fieldInputs` input. */
+    readonly fieldInputs: Signal<WrapperFieldInputs | undefined>;
+    /** Overrides the messages in `fieldInputs` — containers pass their own. */
+    readonly validationMessages?: Signal<ValidationMessages | undefined>;
+    /** Defaults to the current injection context. */
+    readonly injector?: Injector;
+}
+/**
+ * Resolves the wrapped field's errors for a wrapper component, for a leaf or a container.
+ *
+ * A wrapper cannot `inject(NgForgeField)` — the chain is built before the field component
+ * exists — so this reads the same information out of the `fieldInputs` bag it already has.
+ * A leaf carries its own `field`; a container has none, so its node is resolved by key
+ * against the parent tree in `FIELD_SIGNAL_CONTEXT`.
+ *
+ * Must be called in an injection context.
+ */
+declare function injectFieldErrors(options: FieldErrorsOptions): FieldErrors;
+
+/** The error to raise, minus the `fieldTree` that {@link rowError} fills in. */
+interface RowErrorSpec {
+    /** Error kind, matched against `validationMessages`. */
+    readonly kind: string;
+    /**
+     * Message shown for this error. A row-targeted error needs its own, because the
+     * container's `validationMessages` are keyed to the container, not to the child the
+     * error moves to.
+     */
+    readonly message?: string;
+    readonly [param: string]: unknown;
+}
+/**
+ * Targets a validation error at one field of one row, from a validator declared on the
+ * array (issue #568).
+ *
+ * A container validator sees the whole item list, which is what makes per-row rules
+ * expressible at all — but one message for the list cannot say which row is wrong.
+ * Returning the result of this helper puts the error on that row's own input, where the
+ * adapter renders it like any other field error.
+ *
+ * ```typescript
+ * const periodOrder: CustomValidator = (ctx) => {
+ *   const rows = (ctx.value() ?? []) as { from?: string; to?: string }[];
+ *   return rows.flatMap((row, i) =>
+ *     row.from && row.to && row.to < row.from
+ *       ? [rowError(ctx, i, 'to', { kind: 'periodOrder', message: 'The end must not be before the start.' })]
+ *       : [],
+ *   );
+ * };
+ * ```
+ *
+ * Returns the error untargeted when the row or field cannot be resolved, so it still
+ * surfaces on the container rather than vanishing.
+ */
+declare function rowError(ctx: FieldContext<unknown>, index: number, key: string, error: RowErrorSpec): ValidationError$1;
+
+/**
+ * Computed signal that determines if errors should be displayed.
+ * Based on field's invalid, touched, and error count.
+ *
+ * @param field - Signal containing the FieldTree, or `undefined` before it exists
+ * @returns Signal<boolean> - True if errors should be displayed
+ */
+declare function shouldShowErrors<T>(field: Signal<FieldTree<T> | undefined>): Signal<boolean>;
+
+/** `field` = `validate()`; `tree` = `validateTree()`, which re-homes errors carrying a `fieldTree`. */
+type ValidatorAttachment = 'field' | 'tree';
+declare function applyValidator(config: ValidatorConfig, fieldPath: SchemaPath<any> | SchemaPathTree<any>, attachment?: ValidatorAttachment): void;
+declare function applyValidators(configs: ValidatorConfig[], fieldPath: SchemaPath<any> | SchemaPathTree<any>, attachment?: ValidatorAttachment): void;
 
 /**
  * Create a dynamic value function from an expression string.
@@ -2969,7 +3284,7 @@ interface BaseCheckedField<TProps, TMeta extends FieldMeta = FieldMeta, TNullabl
     nullable?: TNullable;
 }
 declare function isCheckedField<TProps, TMeta extends FieldMeta = FieldMeta>(field: FieldDef<TProps, TMeta>): field is BaseCheckedField<TProps, TMeta, boolean>;
-type ExcludedKeys$1 = 'type' | 'conditionals' | 'value' | 'nullable' | 'disabled' | 'readonly' | 'hidden' | 'col' | keyof FieldWithValidation | 'excludeValueIfHidden' | 'excludeValueIfDisabled' | 'excludeValueIfReadonly' | 'validateWhenHidden' | 'wrappers' | 'skipAutoWrappers' | 'skipDefaultWrappers' | 'addons';
+type ExcludedKeys$1 = 'type' | 'conditionals' | 'value' | 'nullable' | 'disabled' | 'readonly' | 'hidden' | 'col' | keyof FieldWithValidation | 'excludeValueIfHidden' | 'excludeValueIfDisabled' | 'excludeValueIfReadonly' | 'validateWhenHidden' | 'wrappers' | 'skipAutoWrappers' | 'skipDefaultWrappers' | 'addons' | 'webMcp';
 type CheckedFieldComponent<T extends BaseCheckedField<Record<string, unknown> | unknown, FieldMeta, boolean>> = Prettify<WithInputSignals<Omit<T, ExcludedKeys$1>>>;
 
 /**
@@ -2993,7 +3308,7 @@ interface BaseValueField<TProps, TValue, TMeta extends FieldMeta = FieldMeta, TN
     nullable?: TNullable;
 }
 declare function isValueField<TProps, TMeta extends FieldMeta = FieldMeta>(field: FieldDef<TProps, TMeta>): field is BaseValueField<TProps, ValueType, TMeta, boolean>;
-type ExcludedKeys = 'type' | 'conditionals' | 'value' | 'valueType' | 'nullable' | 'disabled' | 'readonly' | 'hidden' | 'col' | 'minValue' | 'maxValue' | 'step' | 'required' | 'email' | 'min' | 'max' | 'minLength' | 'maxLength' | 'pattern' | 'validators' | 'logic' | 'derivation' | 'schemas' | 'excludeValueIfHidden' | 'excludeValueIfDisabled' | 'excludeValueIfReadonly' | 'validateWhenHidden' | 'wrappers' | 'skipAutoWrappers' | 'skipDefaultWrappers' | 'addons';
+type ExcludedKeys = 'type' | 'conditionals' | 'value' | 'valueType' | 'nullable' | 'disabled' | 'readonly' | 'hidden' | 'col' | 'minValue' | 'maxValue' | 'step' | 'required' | 'email' | 'min' | 'max' | 'minLength' | 'maxLength' | 'pattern' | 'validators' | 'logic' | 'derivation' | 'schemas' | 'excludeValueIfHidden' | 'excludeValueIfDisabled' | 'excludeValueIfReadonly' | 'validateWhenHidden' | 'wrappers' | 'skipAutoWrappers' | 'skipDefaultWrappers' | 'addons' | 'webMcp';
 type ValueFieldComponent<T extends BaseValueField<Record<string, unknown> | unknown, unknown, FieldMeta, boolean>> = Prettify<WithInputSignals<Omit<T, ExcludedKeys>>>;
 
 /** Base interface for all form events in the dynamic form system. */
@@ -3637,6 +3952,11 @@ declare function memoize<TFunc extends (...args: any[]) => any>(fn: TFunc, resol
  * @returns Fields as array
  */
 declare function normalizeFieldsArray<T>(fields: readonly T[] | Record<string, T>): T[];
+/**
+ * {@link getChangedKeys} restricted to `keys`. Callers that only care about a handful of
+ * paths avoid diffing an entire form value on every change.
+ */
+declare function getChangedKeysWithin(previous: Record<string, unknown> | null | undefined, current: Record<string, unknown> | null | undefined, keys: ReadonlySet<string>): Set<string>;
 /**
  * Gets the keys that differ between two objects.
  *
@@ -3656,5 +3976,46 @@ declare function assertNever(value: never): never;
  */
 declare function withPreviousValue<T>(input: Resource<T>): Resource<T>;
 
-export { ADDON_ACTION_HANDLERS, ADDON_ACTION_REGISTRY, ADDON_TYPE_COMPONENT_CACHE, ADDON_TYPE_DEFINITIONS, ADDON_TYPE_REGISTRY, ARRAY_CONTEXT, AsyncConditionFunctionCacheService, ComponentInitializedEvent, DEFAULT_PROPS, DEFAULT_VALIDATION_MESSAGES, DEFAULT_WRAPPERS, DEPRECATION_WARNING_TRACKER, DF_FIELD_TEMPLATES, DfAddonSlot, DynamicFormError, DynamicFormLogger, DynamicTextPipe, DynamicValueFunctionCacheService, EMIT_FORM_VALUE_ON_EVENTS, EXTERNAL_DATA, EventBus, ExpressionParser, ExpressionParserError, FIELD_REGISTRY, FIELD_SIGNAL_CONTEXT, FORM_ID_PREFIX, FORM_OPTIONS, FieldContextRegistryService, FunctionRegistryService, GROUP_CONTEXT, HTTP_CONDITION_CACHE, HttpConditionCache, HttpConditionFunctionCacheService, INITIALIZATION_TIMEOUT_MS, LogicFunctionCacheService, NoopLogger, READONLY_FIELD_TREE_CACHE, RootFormRegistryService, TokenType, WRAPPER_AUTO_ASSOCIATIONS, WRAPPER_COMPONENT_CACHE, WRAPPER_REGISTRY, applyMetaToElement, applyValidator, applyValidators, arrayFieldMapper, assertNever, baseFieldMapper, buildBaseInputs, buildClassName, compareValues, containerFieldMapper, createAddonActionRegistry, createDebouncedLogicFunction, createDefaultDerivationLogConfig, createDynamicValueFunction, createFieldValueProxy, createFormFieldStateMap, createFormStateLogicFunction, createInitializationTracker, createLogicFunction, createWarningTracker, deepMergeDefaults, derivedFromDeferred, detectFormMode, dynamicTextToObservable, evaluateCondition, evaluateNonFieldDisabled, evaluateNonFieldHidden, extractExpressionDependencies, extractStringDependencies, getArrayLength, getChangedKeys, getFieldValueHandling, getGridClassString, getNestedValue, groupFieldMapper, hasChildFields, hasCrossFieldWhenCondition, hasFormValue, hasNestedProperty, hasTargetProperty, injectAddonTypeRegistry, injectFieldSignalContext, injectFieldsSupportingAddons, injectNonFieldEvaluationContext, interpolateParams, isArrayField, isCheckedField, isContainerField, isCrossFieldBuiltInValidator, isCrossFieldExpression, isCrossFieldSchema, isCrossFieldStateLogic, isCrossFieldValidator, isDerivationLogicConfig, isDisplayOnlyField, isEqual, isFieldBoundContext, isFormStateCondition, isFunctionHttpValidator, isGenericContainerField, isGroupField, isHiddenField, isLeafField, isNonPagedForm, isPageField, isPagedForm, isResourceBasedValidator, isRowField, isSimplifiedArrayField, isStateLogicConfig, isValidNonPagedForm, isValidPagedForm, isValueBearingField, isValueField, isWrapperTypeDefinition, keyBy, mapValues, memoize, normalizeFieldsArray, omit, pageFieldMapper, readFieldStateInfo, resolveDynamicValue, resolveHttpRequest, resolveNextButtonDisabled, resolveNonFieldDisabled, resolveNonFieldHidden, resolveSubmitButtonDisabled, resolveTokens, rowFieldMapper, runPresetAction, setupInitializationTracking, shouldLog, textFieldMapper, toReadonlyFieldTree, toReadonlyFieldTreeCached, validatePageNesting, withPreviousValue, writeToFieldValue };
-export type { ASTNode, AddonActionContext, AddonActionHandler, AddonActionPreset, AddonShapeValidator, AddonSlot, AddonTypeDefinition, AddonTypeRegistryRef, AddonTypeSchema, AndCondition, AnyAddon, ArrayAllowedChildren, ArrayButtonConfig, ArrayComponent, ArrayContext, ArrayField, ArrayFieldTree, ArrayItemDefinition, ArrayItemTemplate, ArrayLiteralNode, ArrowFunctionNode, AsyncCondition, AsyncConditionFunction, AsyncCustomValidator, AsyncDerivationFunction, AsyncValidatorConfig, AvailableFieldTypes, BaseAddon, BaseCheckedField, BaseValidatorConfig, BaseValueField, BinaryOpNode, BuiltInValidatorConfig, ButtonLogicContext, CallExpressionNode, CheckedFieldComponent, CommonAddonActionPreset, CommonAddonSlot, ComparisonOperator, ComponentAddon, ComputedMemberAccessNode, ConditionalExpression, ConditionalNode, ContainerAllowedChildren, ContainerComponent, ContainerField, ContainerFieldTypes, ContainerLogicConfig, CrossFieldDetectionContext, CssWrapper, CustomCondition, CustomFnConfig, CustomFunction, CustomFunctionOptions, CustomFunctionScope, CustomValidator, CustomValidatorConfig, DeclarativeHttpValidatorConfig, DerivationLogConfig, DerivationLogLevel, DerivationLogicConfig, DerivedFromDeferredOptions, DynamicFormActionRegistry, DynamicFormAddonActionPresetRegistry, DynamicFormAddonRegistry, DynamicFormAddonSlotRegistry, DynamicFormFieldRegistry, DynamicText, DynamicValue, EvaluationContext, ExtractField, FieldAddonSupport, FieldAddonSupportEntry, FieldBoundAddonActionContext, FieldComponent, FieldDef, FieldMeta, FieldOption, FieldPathAccess, FieldRegistryContainers, FieldRegistryLeaves, FieldRegistryWrappers, FieldScope, FieldSignalContext, FieldStateContext, FieldStateInfo, FieldTreeRecord, FieldTypeDefinition, FieldValueCondition, FieldWithValidation, FieldWrapper, FormConfig, FormEvent, FormEventConstructor, FormFieldStateMap, FormMode, FormModeDetectionResult, FormOptions, FormStateCondition, FunctionHttpValidatorConfig, GroupAllowedChildren, GroupComponent, GroupContext, GroupField, HiddenField, HiddenScalar, HiddenValue, HttpCondition, HttpCustomValidator, HttpRequestConfig, HttpResourceRequest, HttpValidationResponseMapping, IdentifierNode, InferFormModel, InferFormValue, InitializationTrackingOptions, JavascriptCondition, LazyComponentLoader, LeafFieldTypes, LiteralNode, Logger, LogicConfig, LogicTrigger, MapperFn, MemberAccessNode, MemoizeOptions, NarrowField, NarrowFields, NextButtonOptions, NonFieldLogicConfig, NonFieldLogicContext, NonFieldLogicType, ObjectLiteralNode, OrCondition, OrphanAddonActionContext, PageAllowedChildren, PageField, PresetCollaborators, Prettify, ReadonlyFieldTree, RegisteredActionRef, RegisteredFieldTypes, RegisteredWrapperTypes, RenderReadyInput, ResolvedValidationExecutionConfig, ResolvedValueExclusionConfig, RowAllowedChildren, RowComponent, RowField, RowWrapper, SchemaApplicationConfig, SchemaDefinition, SimplifiedArrayField, StateLogicConfig, StateLogicType, SubmissionActionResult, SubmissionConfig, SubmitButtonOptions, TemplateAddon, TextAddon, TextElementType, TextField, TextProps, Token, TokenContext, UnaryOpNode, ValidationError, ValidationExecutionConfig, ValidationMessage, ValidationMessageResolver, ValidationMessages, ValidatorConfig, ValueExclusionConfig, ValueFieldComponent, ValueHandlingMode, ValueType, WarningTracker, WithInputSignals, WrapperAutoAssociations, WrapperConfig, WrapperFieldInputs, WrapperTypeDefinition };
+/**
+ * Plumbing shared by every `field-errors` wrapper: the slot, the inputs, the resolved
+ * error surface, and the key this wrapper claims. Subclasses supply only a template —
+ * which is the only thing that actually differs between the core default and each
+ * adapter's native markup.
+ *
+ * ```typescript
+ * @Component({
+ *   selector: 'df-mat-field-errors',
+ *   imports: [MatError],
+ *   template: `
+ *     <ng-container #fieldComponent></ng-container>
+ *     @if (ngf.errorsToDisplay()[0]; as error) {
+ *       <mat-error [id]="ngf.errorId()">{{ error.message }}</mat-error>
+ *     }
+ *   `,
+ *   providers: [provideFieldErrorDisplay(() => MatFieldErrorsWrapperComponent)],
+ * })
+ * export default class MatFieldErrorsWrapperComponent extends FieldErrorsWrapperBase {}
+ * ```
+ */
+declare abstract class FieldErrorsWrapperBase implements FieldWrapper, FieldErrorDisplayClaim {
+    readonly fieldComponent: i0.Signal<ViewContainerRef>;
+    /** Overrides the messages in `fieldInputs`. Containers forward their own. */
+    readonly validationMessages: i0.InputSignal<ValidationMessages | undefined>;
+    readonly fieldInputs: i0.InputSignal<WrapperFieldInputs | undefined>;
+    /** The field whose errors this wrapper renders — see `FieldErrorDisplayClaim`. */
+    readonly claimedKey: i0.Signal<string | undefined>;
+    /** Resolved error surface, mirroring what `injectNgForgeField()` gives a field component. */
+    protected readonly ngf: _ng_forge_dynamic_forms_internal.FieldErrors;
+    static ɵfac: i0.ɵɵFactoryDeclaration<FieldErrorsWrapperBase, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<FieldErrorsWrapperBase, never, never, { "validationMessages": { "alias": "validationMessages"; "required": false; "isSignal": true; }; "fieldInputs": { "alias": "fieldInputs"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+/**
+ * Declares that a wrapper renders the wrapped field's errors, so that field's component
+ * renders none of its own.
+ *
+ * Takes a thunk because the class is still being defined when the decorator evaluates.
+ */
+declare function provideFieldErrorDisplay(wrapper: () => Type<FieldErrorDisplayClaim>): Provider;
+
+export { ADDON_ACTION_HANDLERS, ADDON_ACTION_REGISTRY, ADDON_TYPE_COMPONENT_CACHE, ADDON_TYPE_DEFINITIONS, ADDON_TYPE_REGISTRY, ARRAY_CONTEXT, AsyncConditionFunctionCacheService, ComponentInitializedEvent, DEFAULT_PROPS, DEFAULT_VALIDATION_MESSAGES, DEFAULT_WRAPPERS, DEPRECATION_WARNING_TRACKER, DF_FIELD_TEMPLATES, DfAddonSlot, DynamicFormError, DynamicFormLogger, DynamicTextPipe, DynamicValueFunctionCacheService, EMIT_FORM_VALUE_ON_EVENTS, EXTERNAL_DATA, EventBus, ExpressionParser, ExpressionParserError, FIELD_ERROR_DISPLAY, FIELD_REGISTRY, FIELD_SIGNAL_CONTEXT, FORM_ID_PREFIX, FORM_OPTIONS, FieldContextRegistryService, FieldErrorsWrapperBase, FunctionRegistryService, GROUP_CONTEXT, HTTP_CONDITION_CACHE, HttpConditionCache, HttpConditionFunctionCacheService, INITIALIZATION_TIMEOUT_MS, LogicFunctionCacheService, NoopLogger, READONLY_FIELD_TREE_CACHE, RootFormRegistryService, TokenType, WRAPPER_AUTO_ASSOCIATIONS, WRAPPER_COMPONENT_CACHE, WRAPPER_COMPONENT_LOAD_CACHE, WRAPPER_REGISTRY, applyMetaToElement, applyValidator, applyValidators, arrayFieldMapper, assertNever, baseFieldMapper, buildBaseInputs, buildClassName, compareValues, containerFieldMapper, createAddonActionRegistry, createDebouncedLogicFunction, createDefaultDerivationLogConfig, createDynamicValueFunction, createFieldValueProxy, createFormFieldStateMap, createFormStateLogicFunction, createInitializationTracker, createLogicFunction, createResolvedErrorsSignal, createWarningTracker, deepMergeDefaults, derivedFromDeferred, detectFormMode, dynamicTextToObservable, evaluateCondition, evaluateNonFieldDisabled, evaluateNonFieldHidden, extractExpressionDependencies, extractStringDependencies, getArrayLength, getChangedKeys, getChangedKeysWithin, getFieldValueHandling, getGridClassString, getNestedValue, groupFieldMapper, hasChildFields, hasCrossFieldWhenCondition, hasFormValue, hasNestedProperty, hasTargetProperty, injectAddonTypeRegistry, injectFieldErrors, injectFieldSignalContext, injectFieldsSupportingAddons, injectNonFieldEvaluationContext, interpolateParams, isArrayField, isCheckedField, isContainerField, isCrossFieldBuiltInValidator, isCrossFieldExpression, isCrossFieldSchema, isCrossFieldStateLogic, isCrossFieldValidator, isDerivationLogicConfig, isDisplayOnlyField, isEqual, isFieldBoundContext, isFormStateCondition, isFunctionHttpValidator, isGenericContainerField, isGroupField, isHiddenField, isLeafField, isNonPagedForm, isPageField, isPagedForm, isResourceBasedValidator, isRowField, isSimplifiedArrayField, isStateLogicConfig, isValidNonPagedForm, isValidPagedForm, isValueBearingField, isValueField, isWrapperTypeDefinition, keyBy, mapValues, memoize, normalizeFieldsArray, omit, pageFieldMapper, provideFieldErrorDisplay, readFieldStateInfo, resolveDynamicValue, resolveHttpRequest, resolveNextButtonDisabled, resolveNonFieldDisabled, resolveNonFieldHidden, resolveSubmitButtonDisabled, resolveTokens, rowError, rowFieldMapper, runPresetAction, setupInitializationTracking, shouldLog, shouldShowErrors, textFieldMapper, toReadonlyFieldTree, toReadonlyFieldTreeCached, validatePageNesting, withPreviousValue, writeToFieldValue };
+export type { ASTNode, AddonActionContext, AddonActionHandler, AddonActionPreset, AddonShapeValidator, AddonSlot, AddonTypeDefinition, AddonTypeRegistryRef, AddonTypeSchema, AndCondition, AnyAddon, ArrayAllowedChildren, ArrayButtonConfig, ArrayComponent, ArrayContext, ArrayField, ArrayFieldTree, ArrayItemDefinition, ArrayItemTemplate, ArrayLiteralNode, ArrowFunctionNode, AsyncCondition, AsyncConditionFunction, AsyncCustomValidator, AsyncDerivationFunction, AsyncValidatorConfig, AvailableFieldTypes, BaseAddon, BaseCheckedField, BaseValidatorConfig, BaseValueField, BinaryOpNode, BuiltInValidatorConfig, ButtonLogicContext, CallExpressionNode, CheckedFieldComponent, CommonAddonActionPreset, CommonAddonSlot, ComparisonOperator, ComponentAddon, ComputedMemberAccessNode, ConditionalExpression, ConditionalNode, ContainerAllowedChildren, ContainerComponent, ContainerField, ContainerFieldTypes, ContainerLogicConfig, ContainerValidation, CrossFieldDetectionContext, CssWrapper, CustomCondition, CustomFnConfig, CustomFunction, CustomFunctionOptions, CustomFunctionScope, CustomValidator, CustomValidatorConfig, DeclarativeHttpValidatorConfig, DerivationLogConfig, DerivationLogLevel, DerivationLogicConfig, DerivedFromDeferredOptions, DynamicFormActionRegistry, DynamicFormAddonActionPresetRegistry, DynamicFormAddonRegistry, DynamicFormAddonSlotRegistry, DynamicFormFieldRegistry, DynamicText, DynamicValue, EvaluationContext, ExtractField, FieldAddonSupport, FieldAddonSupportEntry, FieldBoundAddonActionContext, FieldComponent, FieldDef, FieldErrorDisplayClaim, FieldErrors, FieldErrorsOptions, FieldErrorsWrapper, FieldMeta, FieldOption, FieldPathAccess, FieldRegistryContainers, FieldRegistryLeaves, FieldRegistryWrappers, FieldScope, FieldSignalContext, FieldStateContext, FieldStateInfo, FieldTreeRecord, FieldTypeDefinition, FieldValueCondition, FieldWebMcpConfig, FieldWebMcpOptions, FieldWithValidation, FieldWrapper, FormConfig, FormEvent, FormEventConstructor, FormFieldStateMap, FormMode, FormModeDetectionResult, FormOptions, FormStateCondition, FunctionHttpValidatorConfig, GroupAllowedChildren, GroupComponent, GroupContext, GroupField, HiddenField, HiddenScalar, HiddenValue, HttpCondition, HttpCustomValidator, HttpRequestConfig, HttpResourceRequest, HttpValidationResponseMapping, IdentifierNode, InferFormModel, InferFormValue, InitialPageConfig, InitializationTrackingOptions, JavascriptCondition, LazyComponentLoader, LeafFieldTypes, LiteralNode, Logger, LogicConfig, LogicTrigger, MapperFn, MemberAccessNode, MemoizeOptions, NarrowField, NarrowFields, NextButtonOptions, NonFieldLogicConfig, NonFieldLogicContext, NonFieldLogicType, ObjectLiteralNode, OrCondition, OrphanAddonActionContext, PageAllowedChildren, PageField, PresetCollaborators, Prettify, ReadonlyFieldTree, RegisteredActionRef, RegisteredFieldTypes, RegisteredWrapperTypes, RenderReadyInput, ResolvedError, ResolvedValidationExecutionConfig, ResolvedValueExclusionConfig, RowAllowedChildren, RowComponent, RowErrorSpec, RowField, RowWrapper, SchemaApplicationConfig, SchemaDefinition, SimplifiedArrayField, StateLogicConfig, StateLogicType, SubmissionActionResult, SubmissionConfig, SubmitButtonOptions, TemplateAddon, TextAddon, TextElementType, TextField, TextProps, Token, TokenContext, UnaryOpNode, ValidationError, ValidationExecutionConfig, ValidationMessage, ValidationMessageResolver, ValidationMessages, ValidatorAttachment, ValidatorConfig, ValueExclusionConfig, ValueFieldComponent, ValueHandlingMode, ValueType, WarningTracker, WebMcpToolOptions, WithInputSignals, WrapperAutoAssociations, WrapperConfig, WrapperFieldInputs, WrapperTypeDefinition };