@ng-forge/dynamic-forms 0.9.0-next.11 → 0.9.0-next.13

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

@@ -1,13 +1,155 @@
 import * as rxjs from 'rxjs';
 import { Observable } from 'rxjs';
 import * as _angular_core from '@angular/core';
-import { Signal, ResourceRef, Type, ViewContainerRef, InjectionToken, Injector, WritableSignal, EnvironmentInjector, Provider, EnvironmentProviders, Resource, PipeTransform } from '@angular/core';
+import { Signal, Type, ResourceRef, ViewContainerRef, InjectionToken, Injector, WritableSignal, EnvironmentInjector, Provider, EnvironmentProviders, TemplateRef, Resource, PipeTransform } from '@angular/core';
 import * as _ng_forge_dynamic_forms from '@ng-forge/dynamic-forms';
 import * as _angular_forms_signals from '@angular/forms/signals';
 import { FieldContext, TreeValidationResult, ValidationError as ValidationError$1, FieldTree, SchemaPath, SchemaPathTree } from '@angular/forms/signals';
 import { FormSchema } from '@ng-forge/dynamic-forms/schema';
 import * as _angular_forms from '@angular/forms';
 
+type DynamicText = string | Observable<string> | Signal<string>;
+
+/**
+ * Generic reactive value — a static value, an Angular Signal, or an RxJS Observable.
+ *
+ * Generalises {@link DynamicText} for arbitrary value types. Used by
+ * cross-cutting properties that need to react to form state without forcing
+ * every consumer to deal with reactivity (e.g., `hidden` / `disabled` on
+ * addons).
+ *
+ * @example
+ * ```typescript
+ * const a: DynamicValue<boolean> = true;
+ * const b: DynamicValue<boolean> = signal(false);
+ * const c: DynamicValue<boolean> = isValid$;
+ * ```
+ */
+type DynamicValue<T> = T | Signal<T> | Observable<T>;
+
+/**
+ * Universal addon slot names supported by every adapter.
+ *
+ * Adapters render `prefix` to the leading edge of a field and `suffix` to
+ * the trailing edge (mirrored in RTL). Additional slots may be contributed
+ * via {@link DynamicFormAddonSlotRegistry} module augmentation.
+ */
+type CommonAddonSlot = 'prefix' | 'suffix';
+/**
+ * Module-augmentable registry of adapter-specific addon slot names.
+ *
+ * Adapters that expose slots beyond the universal `prefix` / `suffix` (e.g.,
+ * an "error overlay" slot specific to one design system) declare them here.
+ *
+ * @example
+ * ```typescript
+ * declare module '@ng-forge/dynamic-forms' {
+ *   interface DynamicFormAddonSlotRegistry {
+ *     'mat-error-overlay': true;
+ *   }
+ * }
+ * ```
+ */
+interface DynamicFormAddonSlotRegistry {
+}
+/**
+ * Union of every valid addon slot — universal slots plus any registered via
+ * {@link DynamicFormAddonSlotRegistry} module augmentation.
+ */
+type AddonSlot = CommonAddonSlot | keyof DynamicFormAddonSlotRegistry;
+
+/**
+ * Base shape every addon kind extends.
+ *
+ * Public contract:
+ * - `slot` chooses where the addon renders (prefix / suffix / adapter-specific).
+ * - `hidden` / `disabled` are reactive — re-evaluated when their underlying
+ *   signals or observables emit.
+ * - Multiple addons in the same slot render in array order, left-to-right
+ *   within the slot (LTR; mirrored in RTL).
+ *
+ * Note: `meta` is intentionally absent — adapters declare addon-specific
+ * fields via module augmentation rather than an untyped escape hatch.
+ */
+interface BaseAddon<TSlot extends AddonSlot = AddonSlot> {
+    /** Slot to render this addon in. */
+    readonly slot: TSlot;
+    /** CSS class applied to the addon host element. */
+    readonly className?: string;
+    /** Reactive visibility — when `true`, the addon is removed from layout. */
+    readonly hidden?: DynamicValue<boolean>;
+    /** Reactive disabled state — primarily relevant for interactive kinds. */
+    readonly disabled?: DynamicValue<boolean>;
+}
+/**
+ * Module-augmentable registry of addon kinds.
+ *
+ * Each key is the kind discriminant; each value is the addon's full shape
+ * (extending {@link BaseAddon}). Core ships `text`, `template`, and
+ * `component`; adapters add their own (e.g., `prime-icon`, `prime-button`).
+ *
+ * @example
+ * ```typescript
+ * declare module '@ng-forge/dynamic-forms' {
+ *   interface DynamicFormAddonRegistry {
+ *     'prime-icon': PrimeIconAddon;
+ *     'prime-button': PrimeButtonAddon;
+ *   }
+ * }
+ * ```
+ */
+interface DynamicFormAddonRegistry {
+    text: TextAddon;
+    template: TemplateAddon;
+    component: ComponentAddon;
+}
+/**
+ * Union of every registered addon shape.
+ */
+type AnyAddon = DynamicFormAddonRegistry[keyof DynamicFormAddonRegistry];
+/**
+ * Renders text content inline.
+ *
+ * `text` is `DynamicText`, supporting plain strings, observables, and
+ * signals — so values like `'$'`, `'.com'`, or interpolated counters
+ * (`'42/100'`) all work uniformly.
+ */
+interface TextAddon extends BaseAddon {
+    readonly kind: 'text';
+    readonly text: DynamicText;
+}
+/**
+ * Renders a named `<ng-template>` projected into the host `<df-dynamic-form>`.
+ *
+ * JSON-safe — backends ship the key, FE supplies the template definition.
+ * Use the `templateAddon(ref)` helper for rename-safe authoring in code.
+ */
+interface TemplateAddon extends BaseAddon {
+    readonly kind: 'template';
+    readonly templateKey: string;
+}
+/**
+ * Renders an arbitrary Angular component as the addon body.
+ *
+ * The loader returns either a component class directly or a module with a
+ * `default` export. For non-default exports, unwrap with `.then(m => m.X)`:
+ *
+ * ```ts
+ * { kind: 'component', component: () => import('./my').then(m => m.MyComponent) }
+ * ```
+ *
+ * @codeOnly The `component` loader is a function and cannot survive
+ * `JSON.stringify`/`parse`. The lenient validator drops this kind when the
+ * config originated from JSON (set via `sanitizeFormConfig({ source: 'json' })`).
+ */
+interface ComponentAddon extends BaseAddon {
+    readonly kind: 'component';
+    readonly component: () => Promise<Type<unknown> | {
+        default: Type<unknown>;
+    }>;
+    readonly inputs?: Record<string, unknown>;
+}
+
 type WithInputSignals<T> = {
     readonly [K in keyof T]-?: Signal<T[K]>;
 };
@@ -16,8 +158,6 @@ type Prettify<T> = {
     [K in keyof T]: T[K];
 } & {};
 
-type DynamicText = string | Observable<string> | Signal<string>;
-
 /**
  * Interface for dynamic forms logger implementations.
  * Allows custom logging integrations (Sentry, DataDog, etc.)
@@ -589,351 +729,116 @@ interface ContainerLogicConfig {
 }
 
 /**
- * An array item template is an array of allowed children that defines one OBJECT array item's fields.
- * Used for object arrays where each item is `{ key1: value1, key2: value2, ... }`.
+ * Row field interface for creating horizontal layouts.
+ * A row is a synthetic field type that resolves to a Container at runtime,
+ * with a synthesized `{ type: 'row' }` wrapper applied for layout. The row
+ * itself does not hold a value — its children flatten into the parent form.
+ *
+ * Note: Rows do not support `meta` since they have no native form element.
  */
-type ArrayItemTemplate = readonly ArrayAllowedChildren[];
+interface RowField<TFields extends readonly RowAllowedChildren[] = readonly RowAllowedChildren[]> extends FieldDef<never> {
+    type: 'row';
+    /** Child definitions to render within this row */
+    readonly fields: TFields;
+    /** Row fields do not have a label property **/
+    readonly label?: never;
+    /** Rows do not support meta - they have no native form element **/
+    readonly meta?: never;
+    /**
+     * Logic configurations for conditional row visibility.
+     * Only 'hidden' type logic is supported for rows.
+     */
+    readonly logic?: ContainerLogicConfig[];
+}
 /**
- * An array item definition can be either:
- * - A single field (ArrayAllowedChildren) for PRIMITIVE array items - extracts field value directly
- * - An array of fields (ArrayItemTemplate) for OBJECT array items - merges fields into object
- *
- * This allows support for:
- * - Primitive arrays: `['tag1', 'tag2']`
- * - Object arrays: `[{ name: 'Alice', email: '...' }]`
- * - Heterogeneous arrays: `[{ value: 'x' }, 'y']` (mixed primitives and objects)
+ * Type guard for RowField with proper type narrowing
  */
-type ArrayItemDefinition = ArrayAllowedChildren | ArrayItemTemplate;
+declare function isRowField(field: FieldDef<any>): field is RowField;
+
 /**
- * Array field interface for creating dynamic field collections that map to array values.
- *
- * Key concepts:
- * - The outer `fields` array defines INITIAL ITEMS (each element is one array item to render)
- * - Each element can be either:
- *   - A single FieldDef (primitive item) - the field's value is extracted directly
- *   - An array of FieldDefs (object item) - fields are merged into an object
- * - Items can have different field configurations (heterogeneous arrays supported)
- * - Empty `fields: []` means no initial items - user adds via buttons with explicit templates
- * - Initial values are declared via `value` property on each field definition
- *
- * @example
- * // Primitive array: ['angular', 'typescript']
- * {
- *   key: 'tags',
- *   type: 'array',
- *   fields: [
- *     { key: 'tag', type: 'input', value: 'angular' },      // Single field = primitive
- *     { key: 'tag', type: 'input', value: 'typescript' },
- *   ]
- * }
- *
- * @example
- * // Object array: [{ name: 'Alice', email: '...' }]
- * {
- *   key: 'contacts',
- *   type: 'array',
- *   fields: [
- *     [                                                      // Array = object
- *       { key: 'name', type: 'input', value: 'Alice' },
- *       { key: 'email', type: 'input', value: 'alice@example.com' }
- *     ],
- *   ]
- * }
- *
- * @example
- * // Heterogeneous array: [{ label: 'Structured' }, 'Simple']
- * {
- *   key: 'items',
- *   type: 'array',
- *   fields: [
- *     [{ key: 'label', type: 'input', value: 'Structured' }],  // Object item
- *     { key: 'value', type: 'input', value: 'Simple' },        // Primitive item
- *   ]
- * }
- *
- * @example
- * // Empty array (add items via buttons)
- * {
- *   key: 'tags',
- *   type: 'array',
- *   fields: []  // No initial items - user adds via button with template
- * }
+ * 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
  *
- * Nesting constraints: Arrays can contain rows, leaf fields, or groups (for object arrays),
- * but NOT pages or other arrays. Runtime validation enforces these rules.
+ * TypeScript cannot enforce field nesting rules due to circular dependency limitations.
+ * For documentation: Groups should contain rows and leaf fields, but NOT pages or other groups.
+ * Runtime validation enforces these rules.
  *
- * Note: Arrays are container fields and do not support `meta` since they have no native form element.
+ * Note: Groups are container fields and do not support `meta` since they have no native form element.
  */
-interface ArrayField<TFields extends readonly ArrayItemDefinition[] = readonly ArrayItemDefinition[]> extends FieldDef<never> {
-    type: 'array';
-    /**
-     * Array of item definitions. Each element defines one array item:
-     * - Single FieldDef = primitive item (field's value is extracted directly)
-     * - Array of FieldDefs = object item (fields are merged into an object)
-     * - Empty array `[]` = no initial items (add via buttons with explicit templates)
-     * - Items can have different configurations (heterogeneous arrays supported)
-     * - Initial values are set via `value` property on each field definition
-     */
+interface GroupField<TFields extends readonly GroupAllowedChildren[] = readonly GroupAllowedChildren[]> extends FieldDef<never> {
+    type: 'group';
     readonly fields: TFields;
-    /** Array fields do not have a label property **/
+    /** Groups do not have a label property - they are logical containers only **/
     readonly label?: never;
-    /** Arrays do not support meta - they have no native form element **/
+    /** Groups do not support meta - they have no native form element **/
     readonly meta?: never;
     /**
-     * Logic configurations for conditional array visibility.
-     * Only 'hidden' type logic is supported for arrays.
+     * Logic configurations for conditional group visibility.
+     * Only 'hidden' type logic is supported for groups.
      */
     readonly logic?: ContainerLogicConfig[];
+}
+/**
+ * Type guard for GroupField with proper type narrowing
+ */
+declare function isGroupField(field: FieldDef<any>): field is GroupField;
+
+/**
+ * Page field interface for creating top-level page layouts
+ * This is a special field type that contains other field definitions
+ * The page itself doesn't have a value - it's a layout container like row
+ * Pages can only be used at the top level and cannot be nested
+ * This is a programmatic field type only - users cannot customize this field type
+ *
+ * TypeScript cannot enforce field nesting rules due to circular dependency limitations.
+ * For documentation: Pages should contain rows, groups, and leaf fields, but NOT other pages.
+ * Runtime validation enforces these rules.
+ *
+ * Note: Pages are container fields and do not support `meta` since they have no native form element.
+ */
+interface PageField<TFields extends readonly PageAllowedChildren[] = PageAllowedChildren[]> extends FieldDef<never> {
+    type: 'page';
+    /** Child field definitions to render within this page */
+    readonly fields: TFields;
+    /** Page fields do not have a label property **/
+    readonly label?: never;
+    /** Pages do not support meta - they have no native form element **/
+    readonly meta?: never;
     /**
-     * Minimum number of items required in the array.
-     * Validation fails if the array has fewer items than this value.
-     */
-    readonly minLength?: number;
-    /**
-     * Maximum number of items allowed in the array.
-     * Validation fails if the array has more items than this value.
+     * Logic configurations for conditional page visibility.
+     * Only 'hidden' type logic is supported for pages.
+     *
+     * @example
+     * ```typescript
+     * {
+     *   key: 'businessPage',
+     *   type: 'page',
+     *   logic: [{
+     *     type: 'hidden',
+     *     condition: {
+     *       type: 'fieldValue',
+     *       fieldPath: 'accountType',
+     *       operator: 'notEquals',
+     *       value: 'business',
+     *     },
+     *   }],
+     *   fields: [...]
+     * }
+     * ```
      */
-    readonly maxLength?: number;
+    readonly logic?: ContainerLogicConfig[];
 }
 /**
- * Type guard for ArrayField with proper type narrowing.
- * Validates that the field is an array type with a fields property that is an array.
- * Fields can contain either single FieldDefs (primitive items) or arrays of FieldDefs (object items).
+ * Type guard for PageField with proper type narrowing
  */
-declare function isArrayField(field: FieldDef<any>): field is ArrayField;
+declare function isPageField(field: FieldDef<unknown>): field is PageField;
+
 /**
- * Configuration for auto-generated add/remove buttons in simplified array fields.
+ * Helper type to convert union to intersection.
+ * Uses `U extends U` to trigger distributive conditional type behavior.
  */
-interface ArrayButtonConfig {
-    /** Custom label for the button */
-    readonly label?: string;
-    /** Additional properties passed to the button component */
-    readonly props?: Record<string, unknown>;
-}
-/**
- * Simplified array field interface for common use cases.
- *
- * Instead of manually specifying each item in `fields`, provide a `template` that defines
- * the structure of a single item, and a `value` array with initial data.
- * The library auto-generates add/remove buttons.
- *
- * Discriminant: `template` presence → simplified API; `Array.isArray(template)` → object vs primitive.
- *
- * @example
- * // Primitive array: ['angular', 'typescript']
- * {
- *   key: 'tags',
- *   type: 'array',
- *   template: { key: 'value', type: 'input', label: 'Tag', required: true },
- *   value: ['angular', 'typescript']
- * }
- *
- * @example
- * // Object array: [{ name: 'Jane', phone: '555' }]
- * {
- *   key: 'contacts',
- *   type: 'array',
- *   template: [
- *     { key: 'name', type: 'input', label: 'Contact Name', required: true },
- *     { key: 'phone', type: 'input', label: 'Phone Number' },
- *   ],
- *   value: [{ name: 'Jane', phone: '555' }]
- * }
- *
- * @example
- * // Button customization / opt-out
- * {
- *   key: 'tags',
- *   type: 'array',
- *   template: { key: 'value', type: 'input', label: 'Tag' },
- *   addButton: { label: 'Add Tag', props: { color: 'primary' } },
- *   removeButton: false
- * }
- */
-interface SimplifiedArrayField extends FieldDef<never> {
-    type: 'array';
-    /**
-     * Template defining the structure of a single array item.
-     * - Single field (ArrayAllowedChildren) → primitive array (each item is a single value)
-     * - Array of fields (readonly ArrayAllowedChildren[]) → object array (each item is an object)
-     */
-    readonly template: ArrayAllowedChildren | readonly ArrayAllowedChildren[];
-    /** Initial values for the array. Each element creates one array item. */
-    readonly value?: readonly unknown[];
-    /**
-     * Configuration for the auto-generated "Add" button, or `false` to disable it.
-     * Defaults to a button with label "Add".
-     */
-    readonly addButton?: ArrayButtonConfig | false;
-    /**
-     * Configuration for the auto-generated "Remove" button on each item, or `false` to disable it.
-     * Defaults to a button with label "Remove".
-     */
-    readonly removeButton?: ArrayButtonConfig | false;
-    /** Simplified arrays do not support the label property */
-    readonly label?: never;
-    /** Simplified arrays do not support meta */
-    readonly meta?: never;
-    /**
-     * Logic configurations for conditional array visibility.
-     * Only 'hidden' type logic is supported for arrays.
-     */
-    readonly logic?: ContainerLogicConfig[];
-    /**
-     * Minimum number of items required in the array.
-     * Validation fails if the array has fewer items than this value.
-     */
-    readonly minLength?: number;
-    /**
-     * Maximum number of items allowed in the array.
-     * Validation fails if the array has more items than this value.
-     */
-    readonly maxLength?: number;
-    /** Mutually exclusive with `template` — use `fields` for the full API instead */
-    readonly fields?: never;
-}
-/**
- * Type guard for SimplifiedArrayField.
- * Checks for `type: 'array'` with a `template` property (discriminant from full ArrayField).
- */
-declare function isSimplifiedArrayField(field: FieldDef<any>): field is SimplifiedArrayField;
-
-/**
- * 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
- *
- * TypeScript cannot enforce field nesting rules due to circular dependency limitations.
- * For documentation: Groups should contain rows and leaf fields, but NOT pages or other groups.
- * Runtime validation enforces these rules.
- *
- * Note: Groups are container fields and do not support `meta` since they have no native form element.
- */
-interface GroupField<TFields extends readonly GroupAllowedChildren[] = readonly GroupAllowedChildren[]> extends FieldDef<never> {
-    type: 'group';
-    readonly fields: TFields;
-    /** Groups do not have a label property - they are logical containers only **/
-    readonly label?: never;
-    /** Groups do not support meta - they have no native form element **/
-    readonly meta?: never;
-    /**
-     * Logic configurations for conditional group visibility.
-     * Only 'hidden' type logic is supported for groups.
-     */
-    readonly logic?: ContainerLogicConfig[];
-}
-/**
- * Type guard for GroupField with proper type narrowing
- */
-declare function isGroupField(field: FieldDef<any>): field is GroupField;
-
-/**
- * Scalar types supported by hidden fields.
- * These are the primitive value types that can be stored.
- */
-type HiddenScalar = string | number | boolean;
-/**
- * All value types supported by hidden fields.
- * Supports both scalar values and arrays of scalars for storing
- * multiple IDs or similar data.
- */
-type HiddenValue = HiddenScalar | HiddenScalar[];
-/**
- * Hidden field definition for storing values without rendering UI.
- *
- * Hidden fields participate in the form schema and contribute to form values,
- * but do not render any visible component. They are useful for:
- * - Storing IDs when updating existing records
- * - Persisting metadata that shouldn't be user-editable
- * - Tracking computed values that need to be submitted
- *
- * Unlike the `hidden` property on other fields (which hides a rendered field),
- * this field type renders nothing at all - it's a componentless field.
- *
- * @example
- * ```typescript
- * // Store a record ID for updates
- * const idField: HiddenField<string> = {
- *   type: 'hidden',
- *   key: 'id',
- *   value: '550e8400-e29b-41d4-a716-446655440000',
- * };
- *
- * // Store multiple tag IDs
- * const tagIdsField: HiddenField<number[]> = {
- *   type: 'hidden',
- *   key: 'tagIds',
- *   value: [1, 2, 3],
- * };
- * ```
- *
- * @typeParam TValue - The type of value stored (must be HiddenValue compatible)
- */
-interface HiddenField<TValue extends HiddenValue = HiddenValue> extends FieldDef<never> {
-    /** Discriminant for hidden field type */
-    type: 'hidden';
-    /**
-     * The value to store in the form.
-     * This is required - a hidden field without a value serves no purpose.
-     */
-    value: TValue;
-}
-
-/**
- * Page field interface for creating top-level page layouts
- * This is a special field type that contains other field definitions
- * The page itself doesn't have a value - it's a layout container like row
- * Pages can only be used at the top level and cannot be nested
- * This is a programmatic field type only - users cannot customize this field type
- *
- * TypeScript cannot enforce field nesting rules due to circular dependency limitations.
- * For documentation: Pages should contain rows, groups, and leaf fields, but NOT other pages.
- * Runtime validation enforces these rules.
- *
- * Note: Pages are container fields and do not support `meta` since they have no native form element.
- */
-interface PageField<TFields extends readonly PageAllowedChildren[] = PageAllowedChildren[]> extends FieldDef<never> {
-    type: 'page';
-    /** Child field definitions to render within this page */
-    readonly fields: TFields;
-    /** Page fields do not have a label property **/
-    readonly label?: never;
-    /** Pages do not support meta - they have no native form element **/
-    readonly meta?: never;
-    /**
-     * Logic configurations for conditional page visibility.
-     * Only 'hidden' type logic is supported for pages.
-     *
-     * @example
-     * ```typescript
-     * {
-     *   key: 'businessPage',
-     *   type: 'page',
-     *   logic: [{
-     *     type: 'hidden',
-     *     condition: {
-     *       type: 'fieldValue',
-     *       fieldPath: 'accountType',
-     *       operator: 'notEquals',
-     *       value: 'business',
-     *     },
-     *   }],
-     *   fields: [...]
-     * }
-     * ```
-     */
-    readonly logic?: ContainerLogicConfig[];
-}
-/**
- * Type guard for PageField with proper type narrowing
- */
-declare function isPageField(field: FieldDef<unknown>): field is PageField;
-
-/**
- * Helper type to convert union to intersection.
- * Uses `U extends U` to trigger distributive conditional type behavior.
- */
-type UnionToIntersection<U> = (U extends U ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+type UnionToIntersection<U> = (U extends U ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
 /**
  * Depth counter for recursion limiting (prevents infinite type instantiation)
  */
@@ -2420,7 +2325,6 @@ type SubmissionActionResult = Promise<TreeValidationResult> | Observable<TreeVal
  * @typeParam TValue - The form value type
  *
  * @public
- * @experimental
  */
 interface SubmissionConfig<TValue = unknown> {
     /**
@@ -3434,18 +3338,70 @@ interface TextField extends FieldDef<TextProps> {
 }
 
 /**
- * Configuration for the built-in 'css' wrapper type.
+ * Scalar types supported by hidden fields.
+ * These are the primitive value types that can be stored.
+ */
+type HiddenScalar = string | number | boolean;
+/**
+ * All value types supported by hidden fields.
+ * Supports both scalar values and arrays of scalars for storing
+ * multiple IDs or similar data.
+ */
+type HiddenValue = HiddenScalar | HiddenScalar[];
+/**
+ * Hidden field definition for storing values without rendering UI.
  *
- * The CSS wrapper applies CSS classes around wrapped content via a DynamicText
- * input that resolves to space-separated class names.
+ * Hidden fields participate in the form schema and contribute to form values,
+ * but do not render any visible component. They are useful for:
+ * - Storing IDs when updating existing records
+ * - Persisting metadata that shouldn't be user-editable
+ * - Tracking computed values that need to be submitted
+ *
+ * Unlike the `hidden` property on other fields (which hides a rendered field),
+ * this field type renders nothing at all - it's a componentless field.
  *
  * @example
  * ```typescript
- * const wrapper: CssWrapper = {
- *   type: 'css',
- *   cssClasses: 'my-css-class another-class',
+ * // Store a record ID for updates
+ * const idField: HiddenField<string> = {
+ *   type: 'hidden',
+ *   key: 'id',
+ *   value: '550e8400-e29b-41d4-a716-446655440000',
  * };
- * ```
+ *
+ * // Store multiple tag IDs
+ * const tagIdsField: HiddenField<number[]> = {
+ *   type: 'hidden',
+ *   key: 'tagIds',
+ *   value: [1, 2, 3],
+ * };
+ * ```
+ *
+ * @typeParam TValue - The type of value stored (must be HiddenValue compatible)
+ */
+interface HiddenField<TValue extends HiddenValue = HiddenValue> extends FieldDef<never> {
+    /** Discriminant for hidden field type */
+    type: 'hidden';
+    /**
+     * The value to store in the form.
+     * This is required - a hidden field without a value serves no purpose.
+     */
+    value: TValue;
+}
+
+/**
+ * Configuration for the built-in 'css' wrapper type.
+ *
+ * The CSS wrapper applies CSS classes around wrapped content via a DynamicText
+ * input that resolves to space-separated class names.
+ *
+ * @example
+ * ```typescript
+ * const wrapper: CssWrapper = {
+ *   type: 'css',
+ *   cssClasses: 'my-css-class another-class',
+ * };
+ * ```
  */
 interface CssWrapper {
     readonly type: 'css';
@@ -3472,6 +3428,118 @@ interface RowWrapper {
     readonly type: 'row';
 }
 
+/**
+ * Resolves a wrapper type name to its registered config interface.
+ *
+ * When `TWrappers` is a specific registered key (e.g., `'css'`), resolves to
+ * the full config type from `FieldRegistryWrappers` (e.g., `CssWrapper`),
+ * providing type-safe access to wrapper-specific properties like `cssClasses`.
+ *
+ * When `TWrappers` is the full `RegisteredWrapperTypes` union, distributes
+ * to produce a discriminated union of all registered wrapper configs.
+ *
+ * @example
+ * ```typescript
+ * // Resolves to CssWrapper — cssClasses is typed
+ * type CssConfig = WrapperConfig<'css'>;
+ *
+ * // Union of all registered wrapper configs
+ * type AnyConfig = WrapperConfig;
+ * ```
+ */
+type WrapperConfig<TWrappers extends RegisteredWrapperTypes = RegisteredWrapperTypes> = TWrappers extends keyof FieldRegistryWrappers ? FieldRegistryWrappers[TWrappers] : {
+    readonly type: TWrappers;
+};
+/**
+ * Signature of a lazy component loader — either a direct component class or
+ * an ES module whose `default` export is the component. Shared by field and
+ * wrapper registrations so the `loadComponent: () => import('./x.component')`
+ * idiom types cleanly in both places.
+ */
+type LazyComponentLoader<T = unknown> = () => Promise<Type<T> | {
+    default: Type<T>;
+}>;
+/**
+ * Configuration interface for registering wrapper types.
+ *
+ * Defines how a wrapper component is loaded and identified. Wrapper components
+ * provide visual decoration around field content (sections, headers, styling)
+ * without affecting the form data structure.
+ *
+ * @example
+ * ```typescript
+ * const SectionWrapper: WrapperTypeDefinition = {
+ *   name: 'section',
+ *   loadComponent: () => import('./section-wrapper.component').then(m => m.SectionWrapperComponent),
+ * };
+ * ```
+ */
+interface WrapperTypeDefinition<T extends WrapperConfig = WrapperConfig> {
+    /** Unique identifier for the wrapper type (also serves as discriminant from FieldTypeDefinition) */
+    wrapperName: string;
+    /** Wrapper definition type marker (internal use) */
+    _wrapper?: T;
+    /**
+     * Function to load the wrapper component (supports lazy loading).
+     * Returns a Promise that resolves to the component class or module with default export.
+     */
+    loadComponent: LazyComponentLoader;
+    /**
+     * Field types this wrapper should auto-apply to.
+     *
+     * When a field's `type` matches any entry, the wrapper is injected into that
+     * field's effective wrapper chain at the lowest priority (can be overridden
+     * by `FormConfig.defaultWrappers` or the field-level `wrappers` array, and
+     * fully cleared with `wrappers: null`).
+     */
+    types?: readonly string[];
+}
+/**
+ * Type guard for WrapperTypeDefinition.
+ *
+ * Discriminates via `wrapperName` — field types use `name`, wrapper types use `wrapperName`.
+ */
+declare function isWrapperTypeDefinition(value: unknown): value is WrapperTypeDefinition;
+/**
+ * Contract that wrapper components must satisfy.
+ *
+ * Each wrapper exposes a `#fieldComponent` ViewContainerRef where the inner
+ * content (next wrapper, or the field) is rendered imperatively. Config
+ * properties (minus `type`) are set on the component via `setInput`; a
+ * wrapper opts into a key by declaring a matching `input()`, and unknown
+ * keys are silently dropped. Wrappers may additionally declare a
+ * `fieldInputs` input for the wrapped field's mapper outputs (see
+ * `WrapperFieldInputs` for when that's undefined).
+ *
+ * @example
+ * ```typescript
+ * @Component({
+ *   template: `
+ *     <dbx-section [header]="header() ?? ''">
+ *       <ng-container #fieldComponent></ng-container>
+ *     </dbx-section>
+ *   `,
+ * })
+ * export class SectionWrapperComponent implements FieldWrapper {
+ *   readonly fieldComponent = viewChild.required('fieldComponent', { read: ViewContainerRef });
+ *   readonly header = input<string>();
+ *   readonly fieldInputs = input<WrapperFieldInputs>();
+ * }
+ * ```
+ */
+interface FieldWrapper {
+    /** ViewContainerRef slot where inner content is rendered */
+    readonly fieldComponent: Signal<ViewContainerRef>;
+}
+/**
+ * Injection token for the wrapper type registry.
+ *
+ * Provides access to the map of registered wrapper types. The registry is
+ * populated via `provideDynamicForm()` and used by `ContainerFieldComponent` to
+ * resolve wrapper types to their component implementations.
+ */
+declare const WRAPPER_REGISTRY: InjectionToken<Map<string, WrapperTypeDefinition<RowWrapper | _ng_forge_dynamic_forms.CssWrapper>>>;
+
 /**
  * Container field interface for wrapping child fields with UI chrome.
  *
@@ -3554,326 +3622,397 @@ interface ContainerField<TFields extends readonly ContainerAllowedChildren[] = r
 declare function isContainerTypedField(field: FieldDef<any>): field is ContainerField;
 
 /**
- * Container fields registry - augment this interface to add custom container fields
+ * Type constraints for field nesting rules
+ * These ensure that container fields can only contain valid child field types
  *
- * @example
- * ```typescript
- * declare module '@ng-forge/dynamic-forms' {
- *   interface FieldRegistryContainers {
- *     'my-container': MyContainerFieldDef;
- *   }
- * }
- * ```
+ * Note: We explicitly list types instead of using Exclude to avoid circular dependencies
  */
-interface FieldRegistryContainers {
-    page: PageField;
-    row: RowField;
-    group: GroupField;
-    array: ArrayField | SimplifiedArrayField;
-    container: ContainerField;
-}
 /**
- * Leaf fields registry - augment this interface to add custom leaf fields
- *
- * @example
- * ```typescript
- * declare module '@ng-forge/dynamic-forms' {
- *   interface FieldRegistryLeaves {
- *     'my-input': MyInputFieldDef;
- *   }
- * }
- * ```
+ * Fields that are allowed as children of Page fields
+ * Pages can contain: rows, groups, arrays, and leaf fields (but NOT other pages)
  */
-interface FieldRegistryLeaves {
-    text: TextField;
-    hidden: HiddenField;
-}
+type PageAllowedChildren = LeafFieldTypes | RowField | GroupField | ArrayField | SimplifiedArrayField | ContainerField;
 /**
- * Wrapper type registry for module augmentation.
- *
- * Augment this interface to add type-safe wrapper type definitions.
- *
- * @example
- * ```typescript
- * declare module '@ng-forge/dynamic-forms' {
- *   interface FieldRegistryWrappers {
- *     'section': MySectionFieldDef
- *   }
- * }
- * ```
+ * Fields that are allowed as children of Group fields
+ * Groups can contain: rows and leaf fields (but NOT pages or other groups)
  */
-interface FieldRegistryWrappers {
-    css: CssWrapper;
-    row: RowWrapper;
-}
+type GroupAllowedChildren = LeafFieldTypes | RowField | ContainerField;
 /**
- * Global interface for dynamic form field definitions with categorization
- * This interface combines containers and leaves from their respective registries
- *
- * Container fields: Layout fields that contain other fields (page, row, group, array)
- * Leaf fields: Fields that can hold values or display content (input, text, etc.)
- *
- * To add custom fields, augment FieldRegistryContainers or FieldRegistryLeaves
+ * Fields that are allowed as children of Array fields
+ * Arrays can contain: rows, groups, and leaf fields (but NOT pages or other arrays)
+ * Groups are used for creating object arrays where each array item is an object
  */
-interface DynamicFormFieldRegistry {
-    /**
-     * Container fields that hold other fields (no value, have children)
-     */
-    containers: FieldRegistryContainers;
-    /**
-     * Leaf fields that have values or display content
-     */
-    leaves: FieldRegistryLeaves;
-    /**
-     * Field wrappers types
-     */
-    wrappers: FieldRegistryWrappers;
-}
+type ArrayAllowedChildren = LeafFieldTypes | RowField | GroupField | ContainerField;
 /**
- * Union type of all registered container field definitions
+ * Fields that are allowed as children of Container fields.
+ * Containers are pure layout primitives that flatten their children into the
+ * parent form, so most registered field types may appear inside — including
+ * hidden fields and other containers — but NOT pages.
  */
-type ContainerFieldTypes = DynamicFormFieldRegistry['containers'][keyof DynamicFormFieldRegistry['containers']];
+type ContainerAllowedChildren = LeafFieldTypes | RowField | GroupField | ArrayField | SimplifiedArrayField | ContainerField;
 /**
- * Union type of all registered leaf field definitions
+ * Row is a synthetic field type that resolves to a Container at runtime, so
+ * it accepts the same children as a Container.
  */
-type LeafFieldTypes = DynamicFormFieldRegistry['leaves'][keyof DynamicFormFieldRegistry['leaves']];
+type RowAllowedChildren = ContainerAllowedChildren;
+
 /**
- * Union type of all registered field definitions
+ * An array item template is an array of allowed children that defines one OBJECT array item's fields.
+ * Used for object arrays where each item is `{ key1: value1, key2: value2, ... }`.
  */
-type RegisteredFieldTypes = ContainerFieldTypes | LeafFieldTypes;
+type ArrayItemTemplate = readonly ArrayAllowedChildren[];
 /**
- * Extract field types that are available in the registry
+ * An array item definition can be either:
+ * - A single field (ArrayAllowedChildren) for PRIMITIVE array items - extracts field value directly
+ * - An array of fields (ArrayItemTemplate) for OBJECT array items - merges fields into object
+ *
+ * This allows support for:
+ * - Primitive arrays: `['tag1', 'tag2']`
+ * - Object arrays: `[{ name: 'Alice', email: '...' }]`
+ * - Heterogeneous arrays: `[{ value: 'x' }, 'y']` (mixed primitives and objects)
  */
-type AvailableFieldTypes = keyof DynamicFormFieldRegistry['containers'] | keyof DynamicFormFieldRegistry['leaves'];
+type ArrayItemDefinition = ArrayAllowedChildren | ArrayItemTemplate;
 /**
- * Extract wrapper types that are available in the registry
- */
-type RegisteredWrapperTypes = keyof DynamicFormFieldRegistry['wrappers'];
-/**
- * Combined registry mapping type names to field definitions.
- * This flattens containers and leaves into a single mapping.
- */
-type FieldTypeMap = DynamicFormFieldRegistry['containers'] & DynamicFormFieldRegistry['leaves'];
-/**
- * Extract a specific field type from RegisteredFieldTypes based on the `type` discriminant.
- * This enables proper type narrowing when defining fields.
+ * Array field interface for creating dynamic field collections that map to array values.
+ *
+ * Key concepts:
+ * - The outer `fields` array defines INITIAL ITEMS (each element is one array item to render)
+ * - Each element can be either:
+ *   - A single FieldDef (primitive item) - the field's value is extracted directly
+ *   - An array of FieldDefs (object item) - fields are merged into an object
+ * - Items can have different field configurations (heterogeneous arrays supported)
+ * - Empty `fields: []` means no initial items - user adds via buttons with explicit templates
+ * - Initial values are declared via `value` property on each field definition
  *
  * @example
- * ```typescript
- * // Extract a specific field type
- * type MyInputField = ExtractField<'input'>;
+ * // Primitive array: ['angular', 'typescript']
+ * {
+ *   key: 'tags',
+ *   type: 'array',
+ *   fields: [
+ *     { key: 'tag', type: 'input', value: 'angular' },      // Single field = primitive
+ *     { key: 'tag', type: 'input', value: 'typescript' },
+ *   ]
+ * }
  *
- * // Use in field definitions for proper props inference
- * const field: ExtractField<'input'> = {
- *   type: 'input',
- *   key: 'email',
- *   value: '',
- *   props: { type: 'email' } // Only input props allowed here
- * };
- * ```
- */
-type ExtractField<T extends AvailableFieldTypes> = T extends keyof FieldTypeMap ? FieldTypeMap[T] : never;
-/**
- * Narrow a field definition based on its `type` property.
- * Use this to get proper type inference when working with field unions.
+ * @example
+ * // Object array: [{ name: 'Alice', email: '...' }]
+ * {
+ *   key: 'contacts',
+ *   type: 'array',
+ *   fields: [
+ *     [                                                      // Array = object
+ *       { key: 'name', type: 'input', value: 'Alice' },
+ *       { key: 'email', type: 'input', value: 'alice@example.com' }
+ *     ],
+ *   ]
+ * }
  *
  * @example
- * ```typescript
- * function processField<T extends RegisteredFieldTypes>(field: T): NarrowField<T> {
- *   return field as NarrowField<T>;
+ * // Heterogeneous array: [{ label: 'Structured' }, 'Simple']
+ * {
+ *   key: 'items',
+ *   type: 'array',
+ *   fields: [
+ *     [{ key: 'label', type: 'input', value: 'Structured' }],  // Object item
+ *     { key: 'value', type: 'input', value: 'Simple' },        // Primitive item
+ *   ]
  * }
- * ```
- */
-type NarrowField<T> = T extends {
-    type: infer TType;
-} ? (TType extends AvailableFieldTypes ? ExtractField<TType> : T) : T;
-/**
- * Narrow each field in an array based on its `type` property.
- * Use with `satisfies` to get proper type inference for field arrays.
  *
  * @example
- * ```typescript
- * const fields = [
- *   { type: 'input', key: 'name', value: '', props: { type: 'text' } },
- *   { type: 'select', key: 'country', value: 'us', options: [...] },
- * ] as const satisfies NarrowFields;
- * ```
- */
-type NarrowFields = readonly NarrowField<RegisteredFieldTypes>[];
-
-/**
- * Type constraints for field nesting rules
- * These ensure that container fields can only contain valid child field types
+ * // Empty array (add items via buttons)
+ * {
+ *   key: 'tags',
+ *   type: 'array',
+ *   fields: []  // No initial items - user adds via button with template
+ * }
  *
- * Note: We explicitly list types instead of using Exclude to avoid circular dependencies
- */
-/**
- * Fields that are allowed as children of Page fields
- * Pages can contain: rows, groups, arrays, and leaf fields (but NOT other pages)
- */
-type PageAllowedChildren = LeafFieldTypes | RowField | GroupField | ArrayField | SimplifiedArrayField | ContainerField;
-/**
- * Fields that are allowed as children of Group fields
- * Groups can contain: rows and leaf fields (but NOT pages or other groups)
- */
-type GroupAllowedChildren = LeafFieldTypes | RowField | ContainerField;
-/**
- * Fields that are allowed as children of Array fields
- * Arrays can contain: rows, groups, and leaf fields (but NOT pages or other arrays)
- * Groups are used for creating object arrays where each array item is an object
- */
-type ArrayAllowedChildren = LeafFieldTypes | RowField | GroupField | ContainerField;
-/**
- * Fields that are allowed as children of Container fields.
- * Containers are pure layout primitives that flatten their children into the
- * parent form, so most registered field types may appear inside — including
- * hidden fields and other containers — but NOT pages.
- */
-type ContainerAllowedChildren = LeafFieldTypes | RowField | GroupField | ArrayField | SimplifiedArrayField | ContainerField;
-/**
- * Row is a synthetic field type that resolves to a Container at runtime, so
- * it accepts the same children as a Container.
- */
-type RowAllowedChildren = ContainerAllowedChildren;
-
-/**
- * Row field interface for creating horizontal layouts.
- * A row is a synthetic field type that resolves to a Container at runtime,
- * with a synthesized `{ type: 'row' }` wrapper applied for layout. The row
- * itself does not hold a value — its children flatten into the parent form.
+ * Nesting constraints: Arrays can contain rows, leaf fields, or groups (for object arrays),
+ * but NOT pages or other arrays. Runtime validation enforces these rules.
  *
- * Note: Rows do not support `meta` since they have no native form element.
+ * Note: Arrays are container fields and do not support `meta` since they have no native form element.
  */
-interface RowField<TFields extends readonly RowAllowedChildren[] = readonly RowAllowedChildren[]> extends FieldDef<never> {
-    type: 'row';
-    /** Child definitions to render within this row */
+interface ArrayField<TFields extends readonly ArrayItemDefinition[] = readonly ArrayItemDefinition[]> extends FieldDef<never> {
+    type: 'array';
+    /**
+     * Array of item definitions. Each element defines one array item:
+     * - Single FieldDef = primitive item (field's value is extracted directly)
+     * - Array of FieldDefs = object item (fields are merged into an object)
+     * - Empty array `[]` = no initial items (add via buttons with explicit templates)
+     * - Items can have different configurations (heterogeneous arrays supported)
+     * - Initial values are set via `value` property on each field definition
+     */
     readonly fields: TFields;
-    /** Row fields do not have a label property **/
+    /** Array fields do not have a label property **/
     readonly label?: never;
-    /** Rows do not support meta - they have no native form element **/
+    /** Arrays do not support meta - they have no native form element **/
     readonly meta?: never;
     /**
-     * Logic configurations for conditional row visibility.
-     * Only 'hidden' type logic is supported for rows.
+     * Logic configurations for conditional array visibility.
+     * Only 'hidden' type logic is supported for arrays.
      */
     readonly logic?: ContainerLogicConfig[];
+    /**
+     * Minimum number of items required in the array.
+     * Validation fails if the array has fewer items than this value.
+     */
+    readonly minLength?: number;
+    /**
+     * Maximum number of items allowed in the array.
+     * Validation fails if the array has more items than this value.
+     */
+    readonly maxLength?: number;
 }
 /**
- * Type guard for RowField with proper type narrowing
+ * Type guard for ArrayField with proper type narrowing.
+ * Validates that the field is an array type with a fields property that is an array.
+ * Fields can contain either single FieldDefs (primitive items) or arrays of FieldDefs (object items).
  */
-declare function isRowField(field: FieldDef<any>): field is RowField;
-
+declare function isArrayField(field: FieldDef<any>): field is ArrayField;
 /**
- * Resolves a wrapper type name to its registered config interface.
+ * Configuration for auto-generated add/remove buttons in simplified array fields.
+ */
+interface ArrayButtonConfig {
+    /** Custom label for the button */
+    readonly label?: string;
+    /** Additional properties passed to the button component */
+    readonly props?: Record<string, unknown>;
+}
+/**
+ * Simplified array field interface for common use cases.
  *
- * When `TWrappers` is a specific registered key (e.g., `'css'`), resolves to
- * the full config type from `FieldRegistryWrappers` (e.g., `CssWrapper`),
- * providing type-safe access to wrapper-specific properties like `cssClasses`.
+ * Instead of manually specifying each item in `fields`, provide a `template` that defines
+ * the structure of a single item, and a `value` array with initial data.
+ * The library auto-generates add/remove buttons.
  *
- * When `TWrappers` is the full `RegisteredWrapperTypes` union, distributes
- * to produce a discriminated union of all registered wrapper configs.
+ * Discriminant: `template` presence → simplified API; `Array.isArray(template)` → object vs primitive.
  *
  * @example
- * ```typescript
- * // Resolves to CssWrapper — cssClasses is typed
- * type CssConfig = WrapperConfig<'css'>;
- *
- * // Union of all registered wrapper configs
- * type AnyConfig = WrapperConfig;
- * ```
- */
-type WrapperConfig<TWrappers extends RegisteredWrapperTypes = RegisteredWrapperTypes> = TWrappers extends keyof FieldRegistryWrappers ? FieldRegistryWrappers[TWrappers] : {
-    readonly type: TWrappers;
-};
-/**
- * Signature of a lazy component loader — either a direct component class or
- * an ES module whose `default` export is the component. Shared by field and
- * wrapper registrations so the `loadComponent: () => import('./x.component')`
- * idiom types cleanly in both places.
- */
-type LazyComponentLoader<T = unknown> = () => Promise<Type<T> | {
-    default: Type<T>;
-}>;
-/**
- * Configuration interface for registering wrapper types.
+ * // Primitive array: ['angular', 'typescript']
+ * {
+ *   key: 'tags',
+ *   type: 'array',
+ *   template: { key: 'value', type: 'input', label: 'Tag', required: true },
+ *   value: ['angular', 'typescript']
+ * }
  *
- * Defines how a wrapper component is loaded and identified. Wrapper components
- * provide visual decoration around field content (sections, headers, styling)
- * without affecting the form data structure.
+ * @example
+ * // Object array: [{ name: 'Jane', phone: '555' }]
+ * {
+ *   key: 'contacts',
+ *   type: 'array',
+ *   template: [
+ *     { key: 'name', type: 'input', label: 'Contact Name', required: true },
+ *     { key: 'phone', type: 'input', label: 'Phone Number' },
+ *   ],
+ *   value: [{ name: 'Jane', phone: '555' }]
+ * }
  *
  * @example
- * ```typescript
- * const SectionWrapper: WrapperTypeDefinition = {
- *   name: 'section',
- *   loadComponent: () => import('./section-wrapper.component').then(m => m.SectionWrapperComponent),
- * };
- * ```
+ * // Button customization / opt-out
+ * {
+ *   key: 'tags',
+ *   type: 'array',
+ *   template: { key: 'value', type: 'input', label: 'Tag' },
+ *   addButton: { label: 'Add Tag', props: { color: 'primary' } },
+ *   removeButton: false
+ * }
  */
-interface WrapperTypeDefinition<T extends WrapperConfig = WrapperConfig> {
-    /** Unique identifier for the wrapper type (also serves as discriminant from FieldTypeDefinition) */
-    wrapperName: string;
-    /** Wrapper definition type marker (internal use) */
-    _wrapper?: T;
+interface SimplifiedArrayField extends FieldDef<never> {
+    type: 'array';
     /**
-     * Function to load the wrapper component (supports lazy loading).
-     * Returns a Promise that resolves to the component class or module with default export.
+     * Template defining the structure of a single array item.
+     * - Single field (ArrayAllowedChildren) → primitive array (each item is a single value)
+     * - Array of fields (readonly ArrayAllowedChildren[]) → object array (each item is an object)
      */
-    loadComponent: LazyComponentLoader;
+    readonly template: ArrayAllowedChildren | readonly ArrayAllowedChildren[];
+    /** Initial values for the array. Each element creates one array item. */
+    readonly value?: readonly unknown[];
     /**
-     * Field types this wrapper should auto-apply to.
-     *
-     * When a field's `type` matches any entry, the wrapper is injected into that
-     * field's effective wrapper chain at the lowest priority (can be overridden
-     * by `FormConfig.defaultWrappers` or the field-level `wrappers` array, and
-     * fully cleared with `wrappers: null`).
+     * Configuration for the auto-generated "Add" button, or `false` to disable it.
+     * Defaults to a button with label "Add".
      */
-    types?: readonly string[];
+    readonly addButton?: ArrayButtonConfig | false;
+    /**
+     * Configuration for the auto-generated "Remove" button on each item, or `false` to disable it.
+     * Defaults to a button with label "Remove".
+     */
+    readonly removeButton?: ArrayButtonConfig | false;
+    /** Simplified arrays do not support the label property */
+    readonly label?: never;
+    /** Simplified arrays do not support meta */
+    readonly meta?: never;
+    /**
+     * Logic configurations for conditional array visibility.
+     * Only 'hidden' type logic is supported for arrays.
+     */
+    readonly logic?: ContainerLogicConfig[];
+    /**
+     * Minimum number of items required in the array.
+     * Validation fails if the array has fewer items than this value.
+     */
+    readonly minLength?: number;
+    /**
+     * Maximum number of items allowed in the array.
+     * Validation fails if the array has more items than this value.
+     */
+    readonly maxLength?: number;
+    /** Mutually exclusive with `template` — use `fields` for the full API instead */
+    readonly fields?: never;
 }
 /**
- * Type guard for WrapperTypeDefinition.
+ * Type guard for SimplifiedArrayField.
+ * Checks for `type: 'array'` with a `template` property (discriminant from full ArrayField).
+ */
+declare function isSimplifiedArrayField(field: FieldDef<any>): field is SimplifiedArrayField;
+
+/**
+ * Container fields registry - augment this interface to add custom container fields
  *
- * Discriminates via `wrapperName` — field types use `name`, wrapper types use `wrapperName`.
+ * @example
+ * ```typescript
+ * declare module '@ng-forge/dynamic-forms' {
+ *   interface FieldRegistryContainers {
+ *     'my-container': MyContainerFieldDef;
+ *   }
+ * }
+ * ```
  */
-declare function isWrapperTypeDefinition(value: unknown): value is WrapperTypeDefinition;
+interface FieldRegistryContainers {
+    page: PageField;
+    row: RowField;
+    group: GroupField;
+    array: ArrayField | SimplifiedArrayField;
+    container: ContainerField;
+}
 /**
- * Contract that wrapper components must satisfy.
+ * Leaf fields registry - augment this interface to add custom leaf fields
  *
- * Each wrapper exposes a `#fieldComponent` ViewContainerRef where the inner
- * content (next wrapper, or the field) is rendered imperatively. Config
- * properties (minus `type`) are set on the component via `setInput`; a
- * wrapper opts into a key by declaring a matching `input()`, and unknown
- * keys are silently dropped. Wrappers may additionally declare a
- * `fieldInputs` input for the wrapped field's mapper outputs (see
- * `WrapperFieldInputs` for when that's undefined).
+ * @example
+ * ```typescript
+ * declare module '@ng-forge/dynamic-forms' {
+ *   interface FieldRegistryLeaves {
+ *     'my-input': MyInputFieldDef;
+ *   }
+ * }
+ * ```
+ */
+interface FieldRegistryLeaves {
+    text: TextField;
+    hidden: HiddenField;
+}
+/**
+ * Wrapper type registry for module augmentation.
+ *
+ * Augment this interface to add type-safe wrapper type definitions.
  *
  * @example
  * ```typescript
- * @Component({
- *   template: `
- *     <dbx-section [header]="header() ?? ''">
- *       <ng-container #fieldComponent></ng-container>
- *     </dbx-section>
- *   `,
- * })
- * export class SectionWrapperComponent implements FieldWrapper {
- *   readonly fieldComponent = viewChild.required('fieldComponent', { read: ViewContainerRef });
- *   readonly header = input<string>();
- *   readonly fieldInputs = input<WrapperFieldInputs>();
+ * declare module '@ng-forge/dynamic-forms' {
+ *   interface FieldRegistryWrappers {
+ *     'section': MySectionFieldDef
+ *   }
  * }
  * ```
  */
-interface FieldWrapper {
-    /** ViewContainerRef slot where inner content is rendered */
-    readonly fieldComponent: Signal<ViewContainerRef>;
+interface FieldRegistryWrappers {
+    css: CssWrapper;
+    row: RowWrapper;
 }
 /**
- * Injection token for the wrapper type registry.
+ * Global interface for dynamic form field definitions with categorization
+ * This interface combines containers and leaves from their respective registries
  *
- * Provides access to the map of registered wrapper types. The registry is
- * populated via `provideDynamicForm()` and used by `ContainerFieldComponent` to
- * resolve wrapper types to their component implementations.
+ * Container fields: Layout fields that contain other fields (page, row, group, array)
+ * Leaf fields: Fields that can hold values or display content (input, text, etc.)
+ *
+ * To add custom fields, augment FieldRegistryContainers or FieldRegistryLeaves
  */
-declare const WRAPPER_REGISTRY: InjectionToken<Map<string, WrapperTypeDefinition<RowWrapper | _ng_forge_dynamic_forms.CssWrapper>>>;
+interface DynamicFormFieldRegistry {
+    /**
+     * Container fields that hold other fields (no value, have children)
+     */
+    containers: FieldRegistryContainers;
+    /**
+     * Leaf fields that have values or display content
+     */
+    leaves: FieldRegistryLeaves;
+    /**
+     * Field wrappers types
+     */
+    wrappers: FieldRegistryWrappers;
+}
+/**
+ * Union type of all registered container field definitions
+ */
+type ContainerFieldTypes = DynamicFormFieldRegistry['containers'][keyof DynamicFormFieldRegistry['containers']];
+/**
+ * Union type of all registered leaf field definitions
+ */
+type LeafFieldTypes = DynamicFormFieldRegistry['leaves'][keyof DynamicFormFieldRegistry['leaves']];
+/**
+ * Union type of all registered field definitions
+ */
+type RegisteredFieldTypes = ContainerFieldTypes | LeafFieldTypes;
+/**
+ * Extract field types that are available in the registry
+ */
+type AvailableFieldTypes = keyof DynamicFormFieldRegistry['containers'] | keyof DynamicFormFieldRegistry['leaves'];
+/**
+ * Extract wrapper types that are available in the registry
+ */
+type RegisteredWrapperTypes = keyof DynamicFormFieldRegistry['wrappers'];
+/**
+ * Combined registry mapping type names to field definitions.
+ * This flattens containers and leaves into a single mapping.
+ */
+type FieldTypeMap = DynamicFormFieldRegistry['containers'] & DynamicFormFieldRegistry['leaves'];
+/**
+ * Extract a specific field type from RegisteredFieldTypes based on the `type` discriminant.
+ * This enables proper type narrowing when defining fields.
+ *
+ * @example
+ * ```typescript
+ * // Extract a specific field type
+ * type MyInputField = ExtractField<'input'>;
+ *
+ * // Use in field definitions for proper props inference
+ * const field: ExtractField<'input'> = {
+ *   type: 'input',
+ *   key: 'email',
+ *   value: '',
+ *   props: { type: 'email' } // Only input props allowed here
+ * };
+ * ```
+ */
+type ExtractField<T extends AvailableFieldTypes> = T extends keyof FieldTypeMap ? FieldTypeMap[T] : never;
+/**
+ * Narrow a field definition based on its `type` property.
+ * Use this to get proper type inference when working with field unions.
+ *
+ * @example
+ * ```typescript
+ * function processField<T extends RegisteredFieldTypes>(field: T): NarrowField<T> {
+ *   return field as NarrowField<T>;
+ * }
+ * ```
+ */
+type NarrowField<T> = T extends {
+    type: infer TType;
+} ? (TType extends AvailableFieldTypes ? ExtractField<TType> : T) : T;
+/**
+ * Narrow each field in an array based on its `type` property.
+ * Use with `satisfies` to get proper type inference for field arrays.
+ *
+ * @example
+ * ```typescript
+ * const fields = [
+ *   { type: 'input', key: 'name', value: '', props: { type: 'text' } },
+ *   { type: 'select', key: 'country', value: 'us', options: [...] },
+ * ] as const satisfies NarrowFields;
+ * ```
+ */
+type NarrowFields = readonly NarrowField<RegisteredFieldTypes>[];
 
 /**
  * Base interface for native HTML attributes that can be passed to form field elements.
@@ -3974,18 +4113,26 @@ interface FieldDef<TProps, TMeta extends FieldMeta = FieldMeta> {
     /**
      * Field type identifier for component selection.
      *
-     * Determines which component will be rendered for this field.
-     * Must match a registered field type name in the field registry.
+     * Determines which component will be rendered for this field. Names
+     * registered through module augmentation of `DynamicFormFieldRegistry`
+     * are surfaced as IDE autocomplete suggestions via `RegisteredFieldTypes`;
+     * the `(string & {})` branch keeps arbitrary custom identifiers accepted
+     * as an escape hatch for fields that haven't been augmented into the
+     * registry.
      *
      * @example
      * ```typescript
-     * type: 'input'     // Text input field
-     * type: 'select'    // Dropdown selection
-     * type: 'checkbox'  // Boolean checkbox
-     * type: 'group'     // Field group container
+     * type: 'input'     // Text input field (registered)
+     * type: 'select'    // Dropdown selection (registered)
+     * type: 'checkbox'  // Boolean checkbox  (registered)
+     * type: 'group'     // Field group container (registered)
+     * type: 'my-custom' // Unregistered — still accepted, no autocomplete
      * ```
+     *
+     * Wrapper types are intentionally excluded — wrappers are configured through
+     * `wrappers` / `withFormWrappers()` rather than via the field-type discriminant.
      */
-    type: string;
+    type: RegisteredFieldTypes['type'] | (string & {});
     /**
      * Human-readable field label displayed to users.
      *
@@ -4188,6 +4335,24 @@ interface FieldDef<TProps, TMeta extends FieldMeta = FieldMeta> {
      * and any field-level `wrappers`.
      */
     skipDefaultWrappers?: boolean;
+    /**
+     * Addons rendered inside this field's slots (typically `prefix` / `suffix`).
+     *
+     * Each addon declares its kind, slot, and kind-specific configuration.
+     * Whether a field type accepts addons — and which slots / kinds — is
+     * declared at registration via `FieldTypeDefinition.addons`. Field types
+     * without that registration ("Tier 3", e.g., toggle, radio) drop any
+     * `addons` value with a lenient warning at config init.
+     *
+     * @example
+     * ```typescript
+     * addons: [
+     *   { slot: 'prefix', kind: 'prime-icon', icon: 'search' },
+     *   { slot: 'suffix', kind: 'prime-button', preset: 'clear', ariaLabel: 'Clear' },
+     * ]
+     * ```
+     */
+    addons?: ReadonlyArray<AnyAddon>;
 }
 type IncludedKeys = 'label' | 'className' | 'hidden' | 'tabIndex';
 /**
@@ -4282,6 +4447,103 @@ interface GroupContext {
  */
 type MapperFn<T extends FieldDef<unknown>> = (input: T) => Signal<Record<string, unknown>>;
 
+/**
+ * Minimal JSON Schema fragment used by the MCP server to surface an addon
+ * kind's shape to AI form generators. Covers the common subset
+ * (`type`/`properties`/`required`/`enum`/etc.) without pulling in a full JSON
+ * Schema dependency. Extra keys are allowed via the `[key: string]` index so
+ * vendor-specific annotations (`x-foo`, `markdownDescription`) still typecheck.
+ *
+ * Tooling-only: the runtime addon validator does NOT consult `schema` — it
+ * relies on each kind's `validate?(addon, fieldKey)` callback for shape
+ * enforcement. `schema` exists exclusively so the MCP server (and any other
+ * AI-driven form authoring tool) can describe the kind to a model without
+ * hand-maintaining a parallel registry.
+ */
+interface AddonKindSchema {
+    readonly $ref?: string;
+    readonly $schema?: string;
+    readonly title?: string;
+    readonly description?: string;
+    readonly type?: 'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean' | 'null' | ReadonlyArray<'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean' | 'null'>;
+    readonly enum?: ReadonlyArray<unknown>;
+    readonly const?: unknown;
+    readonly properties?: Readonly<Record<string, AddonKindSchema>>;
+    readonly required?: ReadonlyArray<string>;
+    readonly additionalProperties?: boolean | AddonKindSchema;
+    readonly items?: AddonKindSchema | ReadonlyArray<AddonKindSchema>;
+    readonly oneOf?: ReadonlyArray<AddonKindSchema>;
+    readonly anyOf?: ReadonlyArray<AddonKindSchema>;
+    readonly allOf?: ReadonlyArray<AddonKindSchema>;
+    readonly not?: AddonKindSchema;
+    readonly default?: unknown;
+    readonly examples?: ReadonlyArray<unknown>;
+    readonly minimum?: number;
+    readonly maximum?: number;
+    readonly minLength?: number;
+    readonly maxLength?: number;
+    readonly pattern?: string;
+    readonly format?: string;
+    /** Vendor extensions and unrecognised keywords pass through untyped. */
+    readonly [key: string]: unknown;
+}
+/**
+ * Optional shape validator a kind ships to enforce its required fields at
+ * runtime. Throws are caught by the validator and converted into lenient
+ * warnings; the offending addon is dropped and the form keeps rendering.
+ */
+type AddonShapeValidator<T extends BaseAddon = BaseAddon> = (addon: T, fieldKey: string) => void;
+/**
+ * Per-kind registration metadata.
+ *
+ * Registered via `withCustomAddon(...)` features (or adapter feature
+ * helpers like `withPrimeNGAddons()`); resolved at render time by
+ * `<df-addon-slot>`.
+ */
+interface AddonKindDefinition<T extends BaseAddon = BaseAddon> {
+    /** Discriminant matching `addon.kind`. */
+    readonly kind: string;
+    /** Lazy loader for the kind's renderer component. */
+    readonly loadComponent: LazyComponentLoader;
+    /** Optional shape validator — throw `DynamicFormError` to drop the addon with a warning. */
+    readonly validate?: AddonShapeValidator<T>;
+    /** Optional JSON Schema fragment for MCP / pre-flight tooling. */
+    readonly schema?: AddonKindSchema;
+    /**
+     * Whether the kind survives `JSON.stringify` / `JSON.parse`. Kinds whose
+     * shape includes a function payload (e.g., the built-in `'component'`
+     * loader, inline `prime-button` `action` handlers) declare `jsonSafe: false`
+     * so the validator drops them when the config was loaded from a JSON
+     * source (`sanitizeFormConfig(config, { source: 'json' })`). Defaults to
+     * `true` — kinds are JSON-safe unless explicitly opted out.
+     */
+    readonly jsonSafe?: boolean;
+}
+/**
+ * Per-field-type addon-support metadata declared at field registration.
+ *
+ * Source of truth for the runtime validator: which slots are valid for a
+ * field type, which kinds are accepted (optional whitelist).
+ *
+ * Field types that do not declare `addons` on their `FieldTypeDefinition`
+ * are treated as Tier 3 — addons configured on such fields are dropped
+ * with a warning at config init.
+ */
+interface FieldAddonSupport {
+    /** Slots a field of this type accepts. */
+    readonly slots: readonly AddonSlot[];
+    /** Optional whitelist of allowed addon kinds. Omitted = any registered kind. */
+    readonly allowedKinds?: readonly string[];
+}
+/**
+ * Global registry of addon kinds.
+ *
+ * Populated by `withCustomAddon(...)` features and adapter feature helpers
+ * (e.g., `withPrimeNGAddons()`). Read by `<df-addon-slot>` to resolve a
+ * kind discriminant to its renderer component.
+ */
+declare const ADDON_KIND_REGISTRY: InjectionToken<Map<string, AddonKindDefinition<BaseAddon<AddonSlot>>>>;
+
 /**
  * Defines how a field type handles form values and data collection.
  *
@@ -4374,7 +4636,24 @@ interface FieldTypeDefinition<T extends FieldDef<any> = any> {
     /** Semantic scope for tooling to discover interchangeable field alternatives */
     scope?: FieldScope | FieldScope[];
     /** Mapped component inputs that must exist before the renderer instantiates the component */
-    renderReadyWhen?: RenderReadyInput[];
+    renderReadyWhen?: readonly RenderReadyInput[];
+    /**
+     * Declares which addon slots this field accepts and (optionally) the
+     * subset of kinds allowed.
+     *
+     * Source of truth for the runtime addon validator. Field types that
+     * omit this property are treated as Tier 3 — any `addons` configured
+     * on such a field are dropped with a warning at config init.
+     *
+     * @example
+     * ```typescript
+     * {
+     *   name: 'prime-input',
+     *   addons: { slots: ['prefix', 'suffix'] },
+     * }
+     * ```
+     */
+    addons?: FieldAddonSupport;
 }
 /**
  * Injection token for the global field type registry.
@@ -4403,6 +4682,15 @@ interface ResolvedField {
     injector: Injector;
     inputs: Signal<Record<string, unknown>>;
     renderReady: Signal<boolean>;
+    /**
+     * Whether the field is currently hidden. Sourced from the FieldTree's
+     * `state.hidden()` for value-bearing fields (set by Angular Signal Forms in
+     * response to `hidden(path, …)` calls), or from the mapper's explicit
+     * `hidden` input for non-value fields (button, text, container, …). Consumers
+     * must `@if (!field.hidden())` around `*dfFieldOutlet` so hidden fields are
+     * removed from the DOM — Angular Signal Forms warns (NG01916) otherwise.
+     */
+    hidden: Signal<boolean>;
 }
 
 /**
@@ -4610,12 +4898,22 @@ declare class DynamicForm<TFields extends RegisteredFieldTypes[] = RegisteredFie
     formOptions: _angular_core.InputSignal<FormOptions | undefined>;
     /** Form values for two-way data binding. */
     value: _angular_core.ModelSignal<Partial<TModel> | undefined>;
+    /**
+     * How lenient the addon validator is on `config.fields[...].addons`.
+     * `'inline'` (default) keeps everything; `'json'` drops code-only kinds
+     * with a warning. Read at form init and on every config swap — change
+     * `source` AND the config to force re-validation mid-flight.
+     */
+    source: _angular_core.InputSignal<"json" | "inline">;
     private destroyRef;
     private injector;
     protected environmentInjector: EnvironmentInjector;
     private eventBus;
     private logger;
     private dispatcher;
+    private templateRegistry;
+    /** All `<ng-template dfTemplate="...">` instances projected into this form. */
+    private readonly _projectedTemplates;
     /** State manager that owns all form state. Initialized via connectDeps() to guarantee
      * FORM_STATE_DEPS is populated before FormStateManager is injected. */
     private readonly stateManager;
@@ -4729,7 +5027,7 @@ declare class DynamicForm<TFields extends RegisteredFieldTypes[] = RegisteredFie
     private connectDeps;
     private setupEventHandlers;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<DynamicForm<any, any>, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<DynamicForm<any, any>, "form[dynamic-form]", never, { "config": { "alias": "dynamic-form"; "required": true; "isSignal": true; }; "formOptions": { "alias": "formOptions"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": false; "isSignal": true; }; }, { "value": "valueChange"; "validityChange": "validityChange"; "dirtyChange": "dirtyChange"; "submitted": "submitted"; "reset": "reset"; "cleared": "cleared"; "events": "events"; "initialized": "initialized"; "onPageChange": "onPageChange"; "onPageNavigationStateChange": "onPageNavigationStateChange"; }, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<DynamicForm<any, any>, "form[dynamic-form]", never, { "config": { "alias": "dynamic-form"; "required": true; "isSignal": true; }; "formOptions": { "alias": "formOptions"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": false; "isSignal": true; }; "source": { "alias": "source"; "required": false; "isSignal": true; }; }, { "value": "valueChange"; "validityChange": "validityChange"; "dirtyChange": "dirtyChange"; "submitted": "submitted"; "reset": "reset"; "cleared": "cleared"; "events": "events"; "initialized": "initialized"; "onPageChange": "onPageChange"; "onPageNavigationStateChange": "onPageNavigationStateChange"; }, ["_projectedTemplates"], never, true, never>;
 }
 
 declare class EventBus {
@@ -4904,214 +5202,6 @@ interface DynamicFormFeature<TKind extends string = string> {
     ɵproviders: Provider[];
 }
 
-interface FieldOption<T = unknown> {
-    label: DynamicText;
-    value: T;
-    disabled?: boolean;
-    [key: string]: unknown;
-}
-
-/**
- * Injection token for form-level default wrappers.
- *
- * Provides a Signal of the `defaultWrappers` array from FormConfig. Consumed by
- * `DfFieldOutlet` / `ContainerFieldComponent` to merge into each field's
- * effective wrapper chain (lowest priority after auto-associations, higher
- * than field-level `wrappers`).
- *
- * Provided once at the DynamicForm level and inherited via Angular's
- * hierarchical injector.
- */
-declare const DEFAULT_WRAPPERS: InjectionToken<Signal<readonly WrapperConfig[] | undefined>>;
-/**
- * Injection token for providing field signal context to mappers and components.
- *
- * The field signal context is the "nervous system" of the dynamic form library,
- * providing access to:
- * - The form instance and structure
- * - Current form values (as signals)
- * - Default values
- * - Validation messages
- * - The injector for creating components
- *
- * This token is provided by the DynamicForm component and can be scoped
- * for nested forms (Groups, Arrays) via child injectors.
- *
- * @example
- * ```typescript
- * // In a mapper function
- * export function mapValueField(fieldDef: BaseValueField<any, any>): Binding[] {
- *   const context = inject(FIELD_SIGNAL_CONTEXT);
- *   const form = context.form();
- *   // ... use context
- * }
- *
- * // In a component
- * export class MyFieldComponent {
- *   private context = inject(FIELD_SIGNAL_CONTEXT);
- * }
- * ```
- */
-declare const FIELD_SIGNAL_CONTEXT: InjectionToken<FieldSignalContext<Record<string, unknown>>>;
-/**
- * Injection token for providing array context metadata to mappers and components.
- *
- * This token is optionally provided by ArrayFieldComponent when creating injectors
- * for array items. It contains metadata about the array item's position and parent.
- *
- * Mappers can inject this token with {optional: true} to access array context:
- *
- * @example
- * ```typescript
- * // In a mapper function
- * export function buttonMapper(fieldDef: FieldDef<any>): Binding[] {
- *   const arrayContext = inject(ARRAY_CONTEXT, { optional: true });
- *   if (arrayContext) {
- *     // Use arrayContext.index, arrayContext.arrayKey, etc.
- *   }
- * }
- * ```
- */
-declare const ARRAY_CONTEXT: InjectionToken<ArrayContext>;
-/**
- * Injection token for providing group ancestry to mappers and components.
- *
- * Re-provided in two places:
- * 1. `GroupFieldComponent` provides a context whose `groupPath()` is the
- *    parent path extended by its own key (e.g. `'address'` or `'user.address'`).
- * 2. `createArrayItemInjector` provides a sentinel with an empty `groupPath`,
- *    resetting the chain at array boundaries — descendants of an array item
- *    that re-enter a group compose paths INSIDE the array item, matching the
- *    property-derivation collector's keying.
- *
- * `mapFieldToInputs` reads this to scope DOM IDs and override-store keys so
- * the same leaf key can appear in different groups without colliding (#401).
- *
- * Inject with `{ optional: true }` because top-level fields with no group
- * ancestor (and no enclosing array) won't have the token provided. The token
- * IS present for fields inside an array even when no inner group exists — the
- * array-boundary sentinel makes injection succeed with an empty `groupPath`.
- */
-declare const GROUP_CONTEXT: InjectionToken<GroupContext>;
-/**
- * Injection token for form-level default props.
- *
- * Default props are form-wide property defaults that are merged with field-level props.
- * Field props take precedence over default props.
- *
- * Unlike FIELD_SIGNAL_CONTEXT which is re-provided by container components (Group, Array),
- * DEFAULT_PROPS is provided ONCE at the DynamicForm level and inherited by all children
- * via Angular's hierarchical injector.
- *
- * The token provides a Signal to enable reactivity - when config changes, mappers
- * that read the signal inside their computed() will automatically update.
- *
- * @example
- * ```typescript
- * // In a mapper function
- * const defaultPropsSignal = inject(DEFAULT_PROPS);
- *
- * return computed(() => {
- *   const defaultProps = defaultPropsSignal?.();  // Read inside computed for reactivity
- *   const baseInputs = buildBaseInputs(fieldDef, defaultProps);
- *   // ...
- * });
- * ```
- */
-declare const DEFAULT_PROPS: InjectionToken<Signal<Record<string, unknown> | undefined>>;
-/**
- * Injection token for form-level default validation messages.
- *
- * Default validation messages act as fallbacks when fields have validation
- * errors but no field-level `validationMessages` defined.
- *
- * Like DEFAULT_PROPS, this token is provided ONCE at the DynamicForm level
- * and inherited by all children via Angular's hierarchical injector.
- *
- * The token provides a Signal to enable reactivity - when config changes, mappers
- * that read the signal inside their computed() will automatically update.
- *
- * @example
- * ```typescript
- * // In a mapper or component
- * const defaultMessagesSignal = inject(DEFAULT_VALIDATION_MESSAGES);
- *
- * return computed(() => {
- *   const defaultMessages = defaultMessagesSignal?.();  // Read inside computed for reactivity
- *   const message = defaultMessages?.required ?? 'Field is required';
- *   // ...
- * });
- * ```
- */
-declare const DEFAULT_VALIDATION_MESSAGES: InjectionToken<Signal<ValidationMessages | undefined>>;
-/**
- * Injection token for form-level options.
- *
- * Form options control form-wide behavior including button disabled states.
- * Used by button mappers to determine default disabled behavior.
- *
- * Like DEFAULT_PROPS, this token is provided ONCE at the DynamicForm level
- * and inherited by all children via Angular's hierarchical injector.
- *
- * The token provides a Signal to enable reactivity - when config changes, mappers
- * that read the signal inside their computed() will automatically update.
- *
- * @example
- * ```typescript
- * // In a button mapper
- * const formOptionsSignal = inject(FORM_OPTIONS);
- *
- * return computed(() => {
- *   const formOptions = formOptionsSignal?.();  // Read inside computed for reactivity
- *   const disableWhenInvalid = formOptions?.submitButton?.disableWhenInvalid ?? true;
- *   // ...
- * });
- * ```
- */
-declare const FORM_OPTIONS: InjectionToken<Signal<FormOptions | undefined>>;
-
-/**
- * Type guard to check if a field is a container field (page, row, group, or array)
- * Container fields have a 'fields' property and don't contribute values directly.
- * This overload works with RegisteredFieldTypes for full type narrowing.
- */
-declare function isContainerField(field: RegisteredFieldTypes): field is ContainerFieldTypes;
-/**
- * Type guard to check if a field is a container field (page, row, group, or array).
- * This overload works with any FieldDef for looser type checking.
- */
-declare function isContainerField(field: FieldDef<unknown>): boolean;
-/**
- * Type guard to check if a field is a leaf field (value or display field)
- * Leaf fields don't have children and either contribute values or display content
- */
-declare function isLeafField(field: RegisteredFieldTypes): field is LeafFieldTypes;
-/**
- * Type guard to check if a field has a value property (value-bearing field)
- * These fields contribute to the form value output
- * Note: Using `unknown` in the Extract condition to match any value type
- */
-declare function isValueBearingField(field: RegisteredFieldTypes): field is Extract<RegisteredFieldTypes, {
-    value: unknown;
-}>;
-/**
- * Type guard to check if a field is excluded from form values (display-only field)
- * Currently this includes text fields and any other fields without a value property
- */
-declare function isDisplayOnlyField(field: RegisteredFieldTypes): boolean;
-
-/**
- * Helper types for creating type-safe field configurations with proper nesting constraints
- */
-
-/**
- * Type helper for accessing nested field paths safely
- * This allows accessing child paths while maintaining some type safety
- */
-type FieldPathAccess<TValue> = {
-    [K in keyof TValue]: SchemaPath<TValue[K]> | SchemaPathTree<TValue[K]>;
-};
-
 /**
  * User-facing wrapper registration shape used with `createWrappers(...)`.
  *
@@ -5199,6 +5289,48 @@ type InferWrapperRegistry<T> = T extends WrappersBundle<infer R> ? {
     };
 } : never;
 
+/**
+ * Type guard to check if a field is a container field (page, row, group, or array)
+ * Container fields have a 'fields' property and don't contribute values directly.
+ * This overload works with RegisteredFieldTypes for full type narrowing.
+ */
+declare function isContainerField(field: RegisteredFieldTypes): field is ContainerFieldTypes;
+/**
+ * Type guard to check if a field is a container field (page, row, group, or array).
+ * This overload works with any FieldDef for looser type checking.
+ */
+declare function isContainerField(field: FieldDef<unknown>): boolean;
+/**
+ * Type guard to check if a field is a leaf field (value or display field)
+ * Leaf fields don't have children and either contribute values or display content
+ */
+declare function isLeafField(field: RegisteredFieldTypes): field is LeafFieldTypes;
+/**
+ * Type guard to check if a field has a value property (value-bearing field)
+ * These fields contribute to the form value output
+ * Note: Using `unknown` in the Extract condition to match any value type
+ */
+declare function isValueBearingField(field: RegisteredFieldTypes): field is Extract<RegisteredFieldTypes, {
+    value: unknown;
+}>;
+/**
+ * Type guard to check if a field is excluded from form values (display-only field)
+ * Currently this includes text fields and any other fields without a value property
+ */
+declare function isDisplayOnlyField(field: RegisteredFieldTypes): boolean;
+
+/**
+ * Helper types for creating type-safe field configurations with proper nesting constraints
+ */
+
+/**
+ * Type helper for accessing nested field paths safely
+ * This allows accessing child paths while maintaining some type safety
+ */
+type FieldPathAccess<TValue> = {
+    [K in keyof TValue]: SchemaPath<TValue[K]> | SchemaPathTree<TValue[K]>;
+};
+
 /**
  * Extract FieldDef type from FieldTypeDefinition
  */
@@ -5237,390 +5369,1479 @@ type ExtractFieldTypes<T extends FieldTypeOrFeature[]> = {
  * @param items - Field type definitions and/or features (like withLoggerConfig)
  * @returns Environment providers for dependency injection with type inference
  *
- * @example
- * ```typescript
- * // Application-level setup
- * bootstrapApplication(AppComponent, {
- *   providers: [
- *     provideDynamicForm(...withMaterialFields())
- *   ]
- * });
- * ```
+ * @example
+ * ```typescript
+ * // Application-level setup
+ * bootstrapApplication(AppComponent, {
+ *   providers: [
+ *     provideDynamicForm(...withMaterialFields())
+ *   ]
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Disable logging
+ * bootstrapApplication(AppComponent, {
+ *   providers: [
+ *     provideDynamicForm(
+ *       ...withMaterialFields(),
+ *       withLoggerConfig(false)
+ *     )
+ *   ]
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Custom field types with type inference
+ * import { CustomFieldType, AnotherFieldType } from './custom-fields';
+ *
+ * export const appConfig: ApplicationConfig = {
+ *   providers: [
+ *     provideDynamicForm(CustomFieldType, AnotherFieldType)
+ *   ]
+ * };
+ * ```
+ *
+ * @typeParam T - Array of field type definitions for type inference
+ *
+ * @public
+ */
+declare function provideDynamicForm<const T extends FieldTypeOrFeature[]>(...items: T): ProvideDynamicFormResult<ExtractFieldTypes<T> extends FieldTypeDefinition[] ? ExtractFieldTypes<T> : FieldTypeDefinition[]>;
+/**
+ * Extract FieldDef types from provider result
+ */
+type ExtractFieldDefs<T> = T extends {
+    __fieldDefs?: infer F;
+} ? F : never;
+/**
+ * Extract form value type from provider result
+ */
+type ExtractFormValue<T> = T extends {
+    __formValue?: infer V;
+} ? V : never;
+
+/**
+ * Type representing a FieldTree for an array.
+ * Extends FieldTree to add numeric indexing for accessing item FieldTrees.
+ */
+type ArrayFieldTree<T> = FieldTree<T[]> & {
+    readonly [index: number]: FieldTree<T> | undefined;
+};
+/**
+ * Get the length of an array FieldTree.
+ */
+declare function getArrayLength<T>(arrayFieldTree: ArrayFieldTree<T>): number;
+/**
+ * Read-only view of a single field's observable state.
+ *
+ * Whitelisted read signals copied from Angular Signal Forms' `FieldState` so wrappers
+ * can observe a field without being able to mutate it. New write-capable members
+ * added in future Angular versions are excluded by default (the `Pick` list stays
+ * the source of truth).
+ *
+ * `value` is narrowed from `WritableSignal<TValue>` to `Signal<TValue>` so consumers
+ * cannot write through it.
+ */
+interface ReadonlyFieldTree<TValue = unknown> {
+    readonly value: Signal<TValue>;
+    readonly valid: Signal<boolean>;
+    readonly invalid: Signal<boolean>;
+    readonly touched: Signal<boolean>;
+    readonly dirty: Signal<boolean>;
+    readonly required: Signal<boolean>;
+    readonly disabled: Signal<boolean>;
+    readonly hidden: Signal<boolean>;
+    readonly errors: Signal<readonly unknown[]>;
+}
+/**
+ * Build a `ReadonlyFieldTree` by extracting the whitelisted read signals from a
+ * Signal Forms `FieldTree`. Returns a fresh plain object — no casting, no proxying,
+ * so consumers only see the narrow surface and Angular's `WritableSignal` capability
+ * on `value` is hidden.
+ */
+declare function toReadonlyFieldTree<TValue>(field: FieldTree<TValue>): ReadonlyFieldTree<TValue>;
+/**
+ * Write a value into a FieldTree's underlying signal. Signal Forms stores
+ * `FieldState.value` as a `WritableSignal`; this helper centralises the cast
+ * and warns if that contract ever changes (vs a silent no-op).
+ */
+declare function writeToFieldValue<T>(value: Signal<T>, next: T, logger?: {
+    warn: (msg: string) => void;
+}): boolean;
+
+/**
+ * Fields every addon-action context carries, regardless of whether the
+ * addon is bound to a host field or rendered orphaned.
+ */
+interface AddonActionContextBase<TValue> {
+    /**
+     * Identity of the host field this addon is attached to. Empty strings
+     * indicate the addon is rendered outside an active field context (rare).
+     * Use {@link isFieldBoundContext} or the `form !== null` check to
+     * narrow before relying on field identity.
+     */
+    readonly field: {
+        readonly key: string;
+        readonly type: string;
+    };
+    /**
+     * Current value of the host field at the time the action fires.
+     * `undefined` when the host field has no value yet (initial render before
+     * defaultValue resolution) or when the addon is rendered outside a field.
+     */
+    readonly value: TValue | undefined;
+}
+/**
+ * Field-bound variant — the addon is attached to a real field and has a
+ * working value-writer. The common case for `pi-button` / `mat-button` /
+ * `bs-button` / `ion-button` inside an adapter input field.
+ *
+ * `setValue` is non-optional here; the optional chain (`ctx.setValue?.()`)
+ * is unnecessary noise once you've narrowed via {@link isFieldBoundContext}.
+ */
+interface FieldBoundAddonActionContext<TValue = unknown> extends AddonActionContextBase<TValue> {
+    /** Read-only view of the host field's tree — same view wrappers receive. */
+    readonly form: ReadonlyFieldTree<TValue>;
+    /** Push a new value into the host field. */
+    readonly setValue: (next: TValue) => void;
+}
+/**
+ * Orphan variant — the addon is rendered outside any field component (rare;
+ * happens when consumers compose `<df-addon-slot>` directly without a host
+ * field). No writer is reachable; reading `value` may also yield `undefined`.
+ */
+interface OrphanAddonActionContext<TValue = unknown> extends AddonActionContextBase<TValue> {
+    readonly form: null;
+    /** Always absent in the orphan variant — distinguishes the union members. */
+    readonly setValue?: undefined;
+}
+/**
+ * Context handed to inline addon actions and registered handler functions.
+ *
+ * Discriminated by `form`: field-bound contexts have a non-null `form` and a
+ * required `setValue`; orphan contexts have `form: null` and no `setValue`.
+ * Use {@link isFieldBoundContext} when the handler needs to write back.
+ *
+ * @example
+ * ```typescript
+ * provideAddonActions({
+ *   submit: (ctx) => {
+ *     if (!isFieldBoundContext(ctx)) return;
+ *     // ctx.setValue is now `(next: TValue) => void` — no optional chain.
+ *     myService.send(ctx.field.key, ctx.value, ctx.setValue);
+ *   },
+ * });
+ * ```
+ */
+type AddonActionContext<TValue = unknown> = FieldBoundAddonActionContext<TValue> | OrphanAddonActionContext<TValue>;
+/** Type guard narrowing {@link AddonActionContext} to its field-bound variant. */
+declare function isFieldBoundContext<TValue>(ctx: AddonActionContext<TValue>): ctx is FieldBoundAddonActionContext<TValue>;
+/**
+ * Built-in preset actions shared across adapters.
+ *
+ * Adapter kinds that accept a `preset` field render the corresponding
+ * behaviour:
+ *
+ * - `'clear'`: empties the field value.
+ * - `'reset'`: restores the field's configured default value (resolved
+ *   from the form's `defaultValues` map at click time); falls back to
+ *   empty when no default is reachable.
+ * - `'paste'`: reads from the system clipboard and writes the result.
+ * - `'copy'`: writes the field's current value to the system clipboard.
+ * - `'toggle-password-visibility'`: flips a host input's `type` between
+ *   `password` and `text` (requires the host field to provide a type
+ *   override token, e.g., `PRIME_INPUT_TYPE_OVERRIDE`).
+ *
+ * Form submission is intentionally NOT exposed as a button-addon preset —
+ * use the dedicated `'submit'` field type instead.
+ */
+type CommonAddonActionPreset = 'clear' | 'reset' | 'paste' | 'copy' | 'toggle-password-visibility';
+/**
+ * Module-augmentable registry of adapter-specific preset names.
+ *
+ * Adapters add their canonical actions (e.g., Material's
+ * `'mat-datepicker-open'`) without forking the `AddonActionPreset` union.
+ *
+ * @example
+ * ```typescript
+ * declare module '@ng-forge/dynamic-forms' {
+ *   interface DynamicFormAddonActionPresetRegistry {
+ *     'mat-datepicker-open': true;
+ *   }
+ * }
+ * ```
+ */
+interface DynamicFormAddonActionPresetRegistry {
+}
+/**
+ * Union of every preset name an addon may reference — universal presets
+ * plus any contributed via {@link DynamicFormAddonActionPresetRegistry}.
+ *
+ * The `(string & {})` escape hatch keeps autocomplete on the known +
+ * augmented presets while accepting arbitrary strings for one-off adapter
+ * presets that don't warrant a module-augmentation. The runtime preset
+ * runner already handles unknown names gracefully via its `default:` arm
+ * (logs a warning, no throw). Mirrors `FieldDef.type`'s
+ * `RegisteredFieldTypes['type'] | (string & {})` shape.
+ */
+type AddonActionPreset = CommonAddonActionPreset | keyof DynamicFormAddonActionPresetRegistry | (string & {});
+/**
+ * Module-augmentable registry of user-defined named action handlers.
+ *
+ * Users register handlers once at bootstrap with `provideAddonActions({...})`
+ * and reference them from JSON-driven configs via `actionRef: 'handlerName'`.
+ *
+ * @example
+ * ```typescript
+ * declare module '@ng-forge/dynamic-forms' {
+ *   interface DynamicFormActionRegistry {
+ *     openProfile: true;
+ *     runWorkflow: true;
+ *   }
+ * }
+ * ```
+ */
+interface DynamicFormActionRegistry {
+}
+/**
+ * Typed string handle to a registered action handler. The empty registry
+ * resolves to `never`; augmenting `DynamicFormActionRegistry` populates the
+ * union and unlocks autocomplete.
+ */
+type RegisteredActionRef = keyof DynamicFormActionRegistry;
+
+/**
+ * Map of named `TemplateRef`s collected by `<df-dynamic-form>` from
+ * `<ng-template dfTemplate="...">` children projected into its content.
+ * The directive selector is `dfTemplate` (see `DfTemplate`); the input
+ * value is the name addons reference via `templateKey`.
+ *
+ * The `template` addon kind looks up its `templateKey` in this map at
+ * render time. Exposed as a `Signal` so projections can be added or
+ * removed reactively (e.g., when the host conditionally projects).
+ *
+ * Provided at the form-component level (not root) so multiple
+ * `<df-dynamic-form>` instances on the same page have independent
+ * template scopes.
+ */
+declare const DF_FIELD_TEMPLATES: InjectionToken<Signal<ReadonlyMap<string, TemplateRef<unknown>>>>;
+
+interface FieldOption<T = unknown> {
+    label: DynamicText;
+    value: T;
+    disabled?: boolean;
+    [key: string]: unknown;
+}
+
+/**
+ * Injection token for form-level default wrappers.
+ *
+ * Provides a Signal of the `defaultWrappers` array from FormConfig. Consumed by
+ * `DfFieldOutlet` / `ContainerFieldComponent` to merge into each field's
+ * effective wrapper chain (lowest priority after auto-associations, higher
+ * than field-level `wrappers`).
+ *
+ * Provided once at the DynamicForm level and inherited via Angular's
+ * hierarchical injector.
+ */
+declare const DEFAULT_WRAPPERS: InjectionToken<Signal<readonly WrapperConfig[] | undefined>>;
+/**
+ * Injection token for providing field signal context to mappers and components.
+ *
+ * The field signal context is the "nervous system" of the dynamic form library,
+ * providing access to:
+ * - The form instance and structure
+ * - Current form values (as signals)
+ * - Default values
+ * - Validation messages
+ * - The injector for creating components
+ *
+ * This token is provided by the DynamicForm component and can be scoped
+ * for nested forms (Groups, Arrays) via child injectors.
+ *
+ * @example
+ * ```typescript
+ * // In a mapper function — prefer the helper for required access (descriptive error).
+ * export function mapValueField(fieldDef: BaseValueField<any, any>): Binding[] {
+ *   const context = injectFieldSignalContext();
+ *   const form = context.form();
+ *   // ... use context
+ * }
+ *
+ * // Optional access — token directly, returns null if not provided.
+ * const ctx = inject(FIELD_SIGNAL_CONTEXT, { optional: true });
+ * if (ctx) {
+ *   // ...
+ * }
+ * ```
+ */
+declare const FIELD_SIGNAL_CONTEXT: InjectionToken<FieldSignalContext<Record<string, unknown>>>;
+/**
+ * Throwing accessor for {@link FIELD_SIGNAL_CONTEXT}.
+ *
+ * Use when the consumer requires the context — group/array containers and
+ * mappers that depend on form structure. Throws a descriptive
+ * `DynamicFormError` instead of Angular's generic `NullInjectorError` when
+ * the token isn't provided.
+ *
+ * Consumers that may legitimately run outside a `DynamicForm` should keep
+ * using `inject(FIELD_SIGNAL_CONTEXT, { optional: true })`.
+ */
+declare function injectFieldSignalContext<TModel extends Record<string, unknown> = Record<string, unknown>>(): FieldSignalContext<TModel>;
+/**
+ * Injection token for providing array context metadata to mappers and components.
+ *
+ * This token is optionally provided by ArrayFieldComponent when creating injectors
+ * for array items. It contains metadata about the array item's position and parent.
+ *
+ * Mappers can inject this token with {optional: true} to access array context:
+ *
+ * @example
+ * ```typescript
+ * // In a mapper function
+ * export function buttonMapper(fieldDef: FieldDef<any>): Binding[] {
+ *   const arrayContext = inject(ARRAY_CONTEXT, { optional: true });
+ *   if (arrayContext) {
+ *     // Use arrayContext.index, arrayContext.arrayKey, etc.
+ *   }
+ * }
+ * ```
+ */
+declare const ARRAY_CONTEXT: InjectionToken<ArrayContext>;
+/**
+ * Injection token for providing group ancestry to mappers and components.
+ *
+ * Re-provided in two places:
+ * 1. `GroupFieldComponent` provides a context whose `groupPath()` is the
+ *    parent path extended by its own key (e.g. `'address'` or `'user.address'`).
+ * 2. `createArrayItemInjector` provides a sentinel with an empty `groupPath`,
+ *    resetting the chain at array boundaries — descendants of an array item
+ *    that re-enter a group compose paths INSIDE the array item, matching the
+ *    property-derivation collector's keying.
+ *
+ * `mapFieldToInputs` reads this to scope DOM IDs and override-store keys so
+ * the same leaf key can appear in different groups without colliding (#401).
+ *
+ * Inject with `{ optional: true }` because top-level fields with no group
+ * ancestor (and no enclosing array) won't have the token provided. The token
+ * IS present for fields inside an array even when no inner group exists — the
+ * array-boundary sentinel makes injection succeed with an empty `groupPath`.
+ */
+declare const GROUP_CONTEXT: InjectionToken<GroupContext>;
+/**
+ * Injection token for form-level default props.
+ *
+ * Default props are form-wide property defaults that are merged with field-level props.
+ * Field props take precedence over default props.
+ *
+ * Unlike FIELD_SIGNAL_CONTEXT which is re-provided by container components (Group, Array),
+ * DEFAULT_PROPS is provided ONCE at the DynamicForm level and inherited by all children
+ * via Angular's hierarchical injector.
+ *
+ * The token provides a Signal to enable reactivity - when config changes, mappers
+ * that read the signal inside their computed() will automatically update.
+ *
+ * @example
+ * ```typescript
+ * // In a mapper function
+ * const defaultPropsSignal = inject(DEFAULT_PROPS);
+ *
+ * return computed(() => {
+ *   const defaultProps = defaultPropsSignal?.();  // Read inside computed for reactivity
+ *   const baseInputs = buildBaseInputs(fieldDef, defaultProps);
+ *   // ...
+ * });
+ * ```
+ */
+declare const DEFAULT_PROPS: InjectionToken<Signal<Record<string, unknown> | undefined>>;
+/**
+ * Injection token for form-level default validation messages.
+ *
+ * Default validation messages act as fallbacks when fields have validation
+ * errors but no field-level `validationMessages` defined.
+ *
+ * Like DEFAULT_PROPS, this token is provided ONCE at the DynamicForm level
+ * and inherited by all children via Angular's hierarchical injector.
+ *
+ * The token provides a Signal to enable reactivity - when config changes, mappers
+ * that read the signal inside their computed() will automatically update.
+ *
+ * @example
+ * ```typescript
+ * // In a mapper or component
+ * const defaultMessagesSignal = inject(DEFAULT_VALIDATION_MESSAGES);
+ *
+ * return computed(() => {
+ *   const defaultMessages = defaultMessagesSignal?.();  // Read inside computed for reactivity
+ *   const message = defaultMessages?.required ?? 'Field is required';
+ *   // ...
+ * });
+ * ```
+ */
+declare const DEFAULT_VALIDATION_MESSAGES: InjectionToken<Signal<ValidationMessages | undefined>>;
+/**
+ * Injection token for form-level options.
+ *
+ * Form options control form-wide behavior including button disabled states.
+ * Used by button mappers to determine default disabled behavior.
+ *
+ * Like DEFAULT_PROPS, this token is provided ONCE at the DynamicForm level
+ * and inherited by all children via Angular's hierarchical injector.
+ *
+ * The token provides a Signal to enable reactivity - when config changes, mappers
+ * that read the signal inside their computed() will automatically update.
+ *
+ * @example
+ * ```typescript
+ * // In a button mapper
+ * const formOptionsSignal = inject(FORM_OPTIONS);
+ *
+ * return computed(() => {
+ *   const formOptions = formOptionsSignal?.();  // Read inside computed for reactivity
+ *   const disableWhenInvalid = formOptions?.submitButton?.disableWhenInvalid ?? true;
+ *   // ...
+ * });
+ * ```
+ */
+declare const FORM_OPTIONS: InjectionToken<Signal<FormOptions | undefined>>;
+
+/**
+ * Built-in field types provided by the dynamic form library.
+ *
+ * Each field type is validated at compile time using satisfies, ensuring
+ * type safety of the mapper function while allowing the array to be typed
+ * as FieldTypeDefinition[] for consumer flexibility.
+ */
+declare const BUILT_IN_FIELDS: FieldTypeDefinition[];
+
+/**
+ * Configuration options for the logger feature.
+ *
+ * @public
+ */
+interface LoggerConfigOptions {
+    /**
+     * Whether general logging is enabled.
+     *
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Derivation logging level.
+     *
+     * - `'none'`: No derivation debug logging (default)
+     * - `'summary'`: Log cycle completion with counts
+     * - `'verbose'`: Log individual derivation evaluations with details
+     *
+     * @default 'none'
+     */
+    derivations?: DerivationLogLevel;
+}
+/**
+ * Configure logging for dynamic forms.
+ *
+ * By default, general logging is enabled (ConsoleLogger) and derivation
+ * logging is disabled ('none'). Use this feature to enable derivation debugging.
+ *
+ * @example
+ * ```typescript
+ * // Disable all logging
+ * provideDynamicForm(
+ *   ...withMaterialFields(),
+ *   withLoggerConfig(false)
+ * )
+ *
+ * // Enable verbose derivation logging
+ * provideDynamicForm(
+ *   ...withMaterialFields(),
+ *   withLoggerConfig({ derivations: 'verbose' })
+ * )
+ *
+ * // Disable derivation logging but keep general logging
+ * provideDynamicForm(
+ *   ...withMaterialFields(),
+ *   withLoggerConfig({ derivations: 'none' })
+ * )
+ *
+ * // Conditional logging (e.g., only in dev mode)
+ * provideDynamicForm(
+ *   ...withMaterialFields(),
+ *   withLoggerConfig(() => isDevMode())
+ * )
+ * ```
+ *
+ * @param config - Boolean to enable/disable logging, a function returning boolean, or a config object
+ * @returns A DynamicFormFeature that configures logging
+ *
+ * @public
+ */
+declare function withLoggerConfig(config?: boolean | (() => boolean) | LoggerConfigOptions): DynamicFormFeature<'logger'>;
+
+/**
+ * Injection token for the dynamic forms logger.
+ *
+ * Provided by provideDynamicForm() with ConsoleLogger as default.
+ * Override with withLoggerConfig(false) to disable logging.
+ */
+declare const DynamicFormLogger: InjectionToken<Logger>;
+
+/**
+ * Console-based logger implementation.
+ */
+declare class ConsoleLogger implements Logger {
+    private readonly prefix;
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+}
+
+/**
+ * No-operation logger implementation.
+ * All methods are no-ops - used in production by default.
+ */
+declare class NoopLogger implements Logger {
+    debug(): void;
+    info(): void;
+    warn(): void;
+    error(): void;
+}
+
+/**
+ * Enables automatic form value attachment to all events dispatched through the EventBus.
+ *
+ * When this feature is enabled, events dispatched via `eventBus.dispatch()` will include
+ * the current form value in the `formValue` property. This is useful for event handlers
+ * that need access to the complete form state at the time of the event.
+ *
+ * @example Global opt-in
+ * ```typescript
+ * provideDynamicForm(
+ *   ...withMaterialFields(),
+ *   withEventFormValue()
+ * )
+ * ```
+ *
+ * @example Consumer usage
+ * ```typescript
+ * eventBus.on<SubmitEvent>('submit').subscribe(event => {
+ *   if (hasFormValue(event)) {
+ *     console.log('Form value:', event.formValue);
+ *   }
+ * });
+ * ```
+ *
+ * @example Per-form disable (when globally enabled)
+ * ```typescript
+ * const config: FormConfig = {
+ *   fields: [...],
+ *   options: { emitFormValueOnEvents: false }
+ * };
+ * ```
+ *
+ * @remarks
+ * **Precedence rules:**
+ * 1. Per-form `false` - Disables for this form, regardless of global setting
+ * 2. Per-form `true` - Enables for this form, regardless of global setting
+ * 3. Per-form `undefined` - Uses global setting
+ * 4. Global `withEventFormValue()` - Enables globally
+ * 5. No global feature - Disabled globally (default)
+ *
+ * @returns A DynamicFormFeature that enables form value attachment to events
+ *
+ * @public
+ */
+declare function withEventFormValue(): DynamicFormFeature<'event-form-value'>;
+
+/**
+ * Configuration for excluding field values from form submission output
+ * based on their reactive state (hidden, disabled, readonly).
+ *
+ * Supports a 3-tier configuration hierarchy: Field > Form > Global.
+ * The most specific level wins for each property.
+ *
+ * @public
+ */
+interface ValueExclusionConfig {
+    /**
+     * Whether to exclude the value of hidden fields from submission output.
+     *
+     * When `true`, fields whose `hidden()` state is `true` will have their
+     * values omitted from the submitted form value.
+     *
+     * @remarks
+     * This does NOT affect HiddenField (`type: 'hidden'`) — those fields
+     * store values without UI and their `hidden()` state is always `false`.
+     */
+    readonly excludeValueIfHidden?: boolean;
+    /**
+     * Whether to exclude the value of disabled fields from submission output.
+     *
+     * When `true`, fields whose `disabled()` state is `true` will have their
+     * values omitted from the submitted form value.
+     */
+    readonly excludeValueIfDisabled?: boolean;
+    /**
+     * Whether to exclude the value of readonly fields from submission output.
+     *
+     * When `true`, fields whose `readonly()` state is `true` will have their
+     * values omitted from the submitted form value.
+     */
+    readonly excludeValueIfReadonly?: boolean;
+}
+/**
+ * Fully resolved exclusion config with all properties required.
+ * Produced by the 3-tier resolution: `field ?? form ?? global`.
+ *
+ * @public
+ */
+type ResolvedValueExclusionConfig = Required<ValueExclusionConfig>;
+
+/**
+ * Configures global value exclusion defaults for form submission output.
+ *
+ * Value exclusion is **enabled by default** — field values are excluded from the
+ * `(submitted)` output based on their reactive state. Use this feature to
+ * override those defaults. This does NOT affect two-way binding (`value` model /
+ * `entity`) — fields retain their values internally.
+ *
+ * @example Default behavior (all exclusions enabled)
+ * ```typescript
+ * provideDynamicForm(
+ *   ...withMaterialFields(),
+ *   withValueExclusionDefaults()
+ * )
+ * ```
+ *
+ * @example Disable specific exclusions
+ * ```typescript
+ * provideDynamicForm(
+ *   ...withMaterialFields(),
+ *   withValueExclusionDefaults({ excludeValueIfReadonly: false })
+ * )
+ * ```
+ *
+ * @example Disable all exclusions (restore pre-v1 behavior)
+ * ```typescript
+ * provideDynamicForm(
+ *   ...withMaterialFields(),
+ *   withValueExclusionDefaults({
+ *     excludeValueIfHidden: false,
+ *     excludeValueIfDisabled: false,
+ *     excludeValueIfReadonly: false,
+ *   })
+ * )
+ * ```
+ *
+ * @remarks
+ * **Precedence rules:**
+ * 1. Per-field `excludeValueIf*` on `FieldDef` — wins for that field
+ * 2. Per-form `excludeValueIf*` on `FormOptions` — wins for all fields in that form
+ * 3. Global `withValueExclusionDefaults()` — baseline default
+ * 4. No global feature — uses token default (all enabled)
+ *
+ * @param config - Partial override of exclusion rules. Unspecified properties default to `true`.
+ * @returns A DynamicFormFeature that configures value exclusion defaults
+ *
+ * @public
+ */
+declare function withValueExclusionDefaults(config?: Partial<ValueExclusionConfig>): DynamicFormFeature<'value-exclusion'>;
+
+/**
+ * Configuration for when validation runs based on a field's reactive state.
+ *
+ * Currently controls whether hidden fields are validated. Resolved through a
+ * tree-aware hierarchy: per-field overrides inherit down to descendants, with
+ * per-form `FormOptions` and global `withValidationExecutionDefaults()` providing
+ * the root inherited value.
+ *
+ * @public
+ */
+interface ValidationExecutionConfig {
+    /**
+     * Whether validators run while a field is hidden (statically, via `hidden`
+     * logic, or because any ancestor is hidden).
+     *
+     * When `false`, all validators on a hidden field are skipped — the field is
+     * effectively inert until shown. State logic (hidden/disabled/readonly) and
+     * value derivations continue to apply.
+     */
+    readonly validateWhenHidden?: boolean;
+}
+/**
+ * Fully resolved validation execution config — every property defined.
+ *
+ * @public
+ */
+type ResolvedValidationExecutionConfig = Required<ValidationExecutionConfig>;
+
+/**
+ * Configures global validation execution defaults — when validators should run
+ * relative to a field's reactive state.
+ *
+ * By default, validators are **skipped** for hidden fields (`validateWhenHidden: false`),
+ * matching what most users expect: a hidden field is inert. Use this feature to
+ * restore the legacy behavior where hidden fields still validate.
+ *
+ * @example Default behavior — no feature needed
+ * ```typescript
+ * provideDynamicForm(...withMaterialFields())
+ * // hidden fields skip validation
+ * ```
+ *
+ * @example Restore legacy validation-on-hidden behavior
+ * ```typescript
+ * provideDynamicForm(
+ *   ...withMaterialFields(),
+ *   withValidationExecutionDefaults({ validateWhenHidden: true })
+ * )
+ * ```
+ *
+ * @remarks
+ * **Precedence rules:**
+ * 1. Per-field `FieldDef.validateWhenHidden` — wins for that field; inherits down to descendants
+ *    that don't override.
+ * 2. Per-form `FormOptions.validateWhenHidden` — root inherited value for the form.
+ * 3. Global `withValidationExecutionDefaults()` — fallback when no form/field setting.
+ * 4. No feature configured — uses token default (`validateWhenHidden: false`).
+ *
+ * @param config - Partial override. Unspecified properties keep their defaults.
+ * @returns A `DynamicFormFeature` that configures validation execution defaults.
+ *
+ * @public
+ */
+declare function withValidationExecutionDefaults(config?: Partial<ValidationExecutionConfig>): DynamicFormFeature<'validation-execution'>;
+
+/**
+ * Opt into Angular Signal Forms' legacy `.ng-touched` / `.ng-invalid` /
+ * `.ng-dirty` / `.ng-pristine` / `.ng-untouched` / `.ng-pending` /
+ * `.ng-valid` CSS classes on form-bound elements.
+ *
+ * Wires Angular's `@angular/forms/signals/compat` `NG_STATUS_CLASSES` strategy
+ * via `provideSignalFormsConfig`. Without this feature the modern Signal Forms
+ * class strategy is active, which omits the legacy `ng-*` classes.
  *
- * @example
+ * @example Opt in once at the application root
  * ```typescript
- * // Disable logging
  * bootstrapApplication(AppComponent, {
  *   providers: [
  *     provideDynamicForm(
  *       ...withMaterialFields(),
- *       withLoggerConfig(false)
+ *       withLegacyStatusClasses()
  *     )
  *   ]
  * });
  * ```
  *
- * @example
- * ```typescript
- * // Custom field types with type inference
- * import { CustomFieldType, AnotherFieldType } from './custom-fields';
- *
- * export const appConfig: ApplicationConfig = {
- *   providers: [
- *     provideDynamicForm(CustomFieldType, AnotherFieldType)
- *   ]
- * };
- * ```
- *
- * @typeParam T - Array of field type definitions for type inference
+ * @returns A DynamicFormFeature that enables the legacy `ng-*` class strategy
  *
  * @public
  */
-declare function provideDynamicForm<const T extends FieldTypeOrFeature[]>(...items: T): ProvideDynamicFormResult<ExtractFieldTypes<T> extends FieldTypeDefinition[] ? ExtractFieldTypes<T> : FieldTypeDefinition[]>;
-/**
- * Extract FieldDef types from provider result
- */
-type ExtractFieldDefs<T> = T extends {
-    __fieldDefs?: infer F;
-} ? F : never;
-/**
- * Extract form value type from provider result
- */
-type ExtractFormValue<T> = T extends {
-    __formValue?: infer V;
-} ? V : never;
+declare function withLegacyStatusClasses(): DynamicFormFeature<'legacy-status-classes'>;
 
 /**
- * Built-in field types provided by the dynamic form library.
+ * Zero-cost type carrier used in wrapper registrations.
  *
- * Each field type is validated at compile time using satisfies, ensuring
- * type safety of the mapper function while allowing the array to be typed
- * as FieldTypeDefinition[] for consumer flexibility.
+ * Returns `undefined` at runtime but is typed as `T`, so TypeScript can
+ * thread a wrapper's config type through `createWrappers(...)` into the
+ * `InferWrapperRegistry<typeof ...>` utility without requiring users to
+ * hand-write the augmentation shape.
+ *
+ * @example
+ * ```typescript
+ * const wrappers = createWrappers(
+ *   {
+ *     wrapperName: 'section',
+ *     loadComponent: () => import('./section-wrapper'),
+ *     props: wrapperProps<SectionWrapper>(),
+ *   },
+ * );
+ *
+ * declare module '@ng-forge/dynamic-forms' {
+ *   interface FieldRegistryWrappers extends InferWrapperRegistry<typeof wrappers> {}
+ * }
+ * ```
  */
-declare const BUILT_IN_FIELDS: FieldTypeDefinition[];
+declare function wrapperProps<T>(): T;
 
 /**
- * Configuration options for the logger feature.
+ * Input shape passed to a wrapper component via the `fieldInputs` input.
  *
- * @public
+ * Carries the wrapped field's mapper outputs plus an optional `field`
+ * read-only view. Wrappers reached through a container path (which has
+ * no FieldTree of its own) receive `fieldInputs === undefined`, so any
+ * wrapper that reads `fieldInputs.field` must guard for it.
+ *
+ * Mappers must emit new rawInputs objects per tick rather than mutating
+ * the previous one — this bag is a shallow spread, so mutations to shared
+ * nested values leak to downstream wrappers.
  */
-interface LoggerConfigOptions {
-    /**
-     * Whether general logging is enabled.
-     *
-     * @default true
-     */
-    enabled?: boolean;
+interface WrapperFieldInputs {
+    readonly key: string;
+    /** Field-type discriminant (mirrors `FieldDef.type`) — useful for kind-aware addons. */
+    readonly type?: string;
+    readonly label?: string;
+    readonly placeholder?: string;
+    readonly className?: string;
+    readonly props?: Record<string, unknown>;
+    readonly validationMessages?: Record<string, string>;
+    readonly defaultValidationMessages?: Record<string, string>;
+    readonly field?: ReadonlyFieldTree;
     /**
-     * Derivation logging level.
-     *
-     * - `'none'`: No derivation debug logging (default)
-     * - `'summary'`: Log cycle completion with counts
-     * - `'verbose'`: Log individual derivation evaluations with details
-     *
-     * @default 'none'
+     * Write a value into the wrapped field's tree. Provided by `buildFieldInputs`
+     * when a `FieldTree` is present. Addons (e.g., `prime-button` presets) use this
+     * to mutate the host field; wrappers should treat the field as read-only.
      */
-    derivations?: DerivationLogLevel;
+    readonly setValue?: (next: unknown) => void;
+    readonly [key: string]: unknown;
 }
+
 /**
- * Configure logging for dynamic forms.
+ * Dispatcher component that renders an addon by looking up its `kind` in
+ * `ADDON_KIND_REGISTRY` and instantiating the registered component.
  *
- * By default, general logging is enabled (ConsoleLogger) and derivation
- * logging is disabled ('none'). Use this feature to enable derivation debugging.
+ * Used by every adapter's field component to render slot content:
  *
- * @example
- * ```typescript
- * // Disable all logging
- * provideDynamicForm(
- *   ...withMaterialFields(),
- *   withLoggerConfig(false)
- * )
+ * ```html
+ * \@for (a of addonsAt('prefix'); track $index) {
+ *   <df-addon-slot [addon]="a" />
+ * }
+ * ```
  *
- * // Enable verbose derivation logging
- * provideDynamicForm(
- *   ...withMaterialFields(),
- *   withLoggerConfig({ derivations: 'verbose' })
- * )
+ * Behaviour:
+ * - Resolves and caches the kind's component asynchronously on first render.
+ * - Forwards the `slot` HTML attribute on the host so Ionic shadow-DOM
+ *   projection works (`<ion-input>` projects children with `slot="start"`
+ *   into its native start slot).
+ * - Honours the addon's reactive `hidden` flag — when `true`, the host is
+ *   `display: none` so it occupies no layout but stays in DOM (cheaper than
+ *   tearing down the component).
+ * - Forwards `className` to the host element.
+ * - ARIA semantics are owned by individual kind components — decorative
+ *   kinds (icons, text) set `aria-hidden="true"` on themselves; interactive
+ *   kinds (buttons) handle their own `aria-label`.
+ *
+ * If the kind cannot be resolved (registry miss, load failure), the
+ * dispatcher logs a warning and renders nothing — never throws. The
+ * runtime addon validator should have caught unknown kinds at config init,
+ * but this provides a defence-in-depth fallback for misconfigured registries.
+ */
+declare class DfAddonSlot {
+    private readonly registry;
+    private readonly logger;
+    private readonly hostInjector;
+    readonly addon: _angular_core.InputSignal<AnyAddon>;
+    /**
+     * Optional read-only view of the host field's mapped inputs — same shape
+     * wrappers receive (`field?: ReadonlyFieldTree`, `key`, `props`, etc.).
+     * Forwarded to kind components so they can read field state without
+     * re-injecting `FIELD_SIGNAL_CONTEXT` and rebuilding context themselves.
+     *
+     * `undefined` when the addon is rendered outside a field (rare).
+     */
+    readonly fieldInputs: _angular_core.InputSignal<WrapperFieldInputs | undefined>;
+    /**
+     * Pre-resolved `hidden` signal supplied by the host field. When provided,
+     * the dispatcher reads this instead of re-resolving `addon.hidden` —
+     * lets the host (e.g., `prime-input`) share a single subscription per
+     * Observable-typed `hidden` between its own visibility filter and the
+     * slot's `[style.display]` binding.
+     */
+    readonly hidden: _angular_core.InputSignal<Signal<boolean> | undefined>;
+    /** `slot` HTML attribute forwarded to host — needed for Ionic shadow projection. */
+    protected readonly slotAttr: Signal<_ng_forge_dynamic_forms.AddonSlot>;
+    protected readonly className: Signal<string | null>;
+    /**
+     * Locally-resolved `hidden` signal — always reflects `addon.hidden`
+     * regardless of whether the host supplied a pre-resolved signal.
+     * Populated via `explicitEffect` so `resolveDynamicValue` (which may call
+     * `toSignal` for Observable-typed values) does NOT run inside a reactive
+     * context (NG0602). The WeakMap caches per `hidden`-value identity, so
+     * swapping `addon` inputs that share the same Observable reuses the
+     * subscription instead of leaking a fresh one per swap.
+     *
+     * Resolved unconditionally (not gated on host `hidden()` presence) so a
+     * transition from `host hidden = Signal` → `undefined` doesn't expose a
+     * brief window where neither value is current — the upstream effect
+     * re-runs eventually, but the computed read can happen in between.
+     */
+    private readonly _hiddenByValue;
+    private readonly _resolvedHidden;
+    /**
+     * `hidden` resolved from `DynamicValue<boolean>` to a flat `Signal<boolean>`.
+     * Prefers the host-supplied signal when present (avoids duplicate `toSignal`
+     * subscriptions for Observable-typed `hidden`); falls back to the locally-
+     * resolved signal, which is always populated by the addon-tracking effect.
+     */
+    protected readonly isHidden: Signal<boolean>;
+    /**
+     * Latest async-loaded `{ kind, component }` pair. Tagging the result with
+     * its kind lets `resolvedComponent` filter stale loads structurally — no
+     * monotonic token needed. When `addon.kind` changes mid-load, the prior
+     * load still completes and writes here, but the computed ignores it
+     * because the recorded kind no longer matches the current one.
+     */
+    private readonly asyncLoaded;
+    /**
+     * Resolved kind component — composed declaratively from two sources of
+     * truth: the registry's synchronous cache (warm hits, e.g., a second
+     * `<df-addon-slot>` for an already-loaded kind) and the kind-tagged async
+     * loader result. Reading `addon().kind` first makes the computed react to
+     * addon swaps and naturally invalidate stale async-load results.
+     */
+    protected readonly resolvedComponent: Signal<Type<unknown> | undefined>;
+    /** Inputs passed to the kind component — addon plus the wrapper-style host bag. */
+    protected readonly kindInputs: Signal<{
+        addon: AnyAddon;
+        fieldInputs: WrapperFieldInputs | undefined;
+    }>;
+    constructor();
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<DfAddonSlot, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<DfAddonSlot, "df-addon-slot", never, { "addon": { "alias": "addon"; "required": true; "isSignal": true; }; "fieldInputs": { "alias": "fieldInputs"; "required": false; "isSignal": true; }; "hidden": { "alias": "hidden"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Marks an `<ng-template>` projected into `<df-dynamic-form>` content as
+ * available to template addons by name.
  *
- * // Disable derivation logging but keep general logging
- * provideDynamicForm(
- *   ...withMaterialFields(),
- *   withLoggerConfig({ derivations: 'none' })
- * )
+ * The host form collects all `DfTemplate` instances via `contentChildren`
+ * and exposes them through {@link DF_FIELD_TEMPLATES}, where the template
+ * addon kind looks them up by `templateKey` at render time.
  *
- * // Conditional logging (e.g., only in dev mode)
- * provideDynamicForm(
- *   ...withMaterialFields(),
- *   withLoggerConfig(() => isDevMode())
- * )
+ * @example
+ * ```html
+ * <df-dynamic-form [config]="config">
+ *   <ng-template dfTemplate="searchIcon" let-field>
+ *     <my-icon [field]="field" />
+ *   </ng-template>
+ * </df-dynamic-form>
  * ```
  *
- * @param config - Boolean to enable/disable logging, a function returning boolean, or a config object
- * @returns A DynamicFormFeature that configures logging
- *
- * @public
+ * In the field config:
+ * ```ts
+ * { slot: 'prefix', kind: 'template', templateKey: 'searchIcon' }
+ * ```
  */
-declare function withLoggerConfig(config?: boolean | (() => boolean) | LoggerConfigOptions): DynamicFormFeature<'logger'>;
+declare class DfTemplate {
+    /** Name this template registers under — referenced from `TemplateAddon.templateKey`. */
+    readonly dfTemplate: _angular_core.InputSignal<string>;
+    /** The wrapped template, captured for registration and `NgTemplateOutlet` rendering. */
+    readonly templateRef: TemplateRef<unknown>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<DfTemplate, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<DfTemplate, "ng-template[dfTemplate]", ["dfTemplate"], { "dfTemplate": { "alias": "dfTemplate"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+}
 
 /**
- * Injection token for the dynamic forms logger.
+ * Renderer for the universal `text` addon kind.
  *
- * Provided by provideDynamicForm() with ConsoleLogger as default.
- * Override with withLoggerConfig(false) to disable logging.
- */
-declare const DynamicFormLogger: InjectionToken<Logger>;
-
-/**
- * Console-based logger implementation.
+ * Renders the addon's `text` (a `DynamicText`) inside a span. Decorative —
+ * sets `aria-hidden="true"` on the host so screen readers skip it; users
+ * who need announcement should use a `*-button` kind with `ariaLabel` instead.
  */
-declare class ConsoleLogger implements Logger {
-    private readonly prefix;
-    debug(message: string, ...args: unknown[]): void;
-    info(message: string, ...args: unknown[]): void;
-    warn(message: string, ...args: unknown[]): void;
-    error(message: string, ...args: unknown[]): void;
+declare class TextAddonComponent {
+    readonly addon: _angular_core.InputSignal<TextAddon>;
+    /** Accepted for contract uniformity — `NgComponentOutlet` setInput is strict; every kind must declare it. */
+    readonly fieldInputs: _angular_core.InputSignal<WrapperFieldInputs | undefined>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<TextAddonComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<TextAddonComponent, "df-text-addon", never, { "addon": { "alias": "addon"; "required": true; "isSignal": true; }; "fieldInputs": { "alias": "fieldInputs"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
 /**
- * No-operation logger implementation.
- * All methods are no-ops - used in production by default.
+ * Renderer for the universal `template` addon kind.
+ *
+ * Resolves the addon's `templateKey` against {@link DF_FIELD_TEMPLATES}
+ * (populated by `<df-dynamic-form>` from `<ng-template dfTemplate="...">`
+ * children) and renders via `NgTemplateOutlet`. The wrapper-style host bag
+ * (`fieldInputs`) is forwarded as the template's implicit context — author
+ * the template as `<ng-template dfTemplate="..." let-fi>{{ fi.key }}</ng-template>`.
+ *
+ * If the key is unresolved, logs a warning and renders nothing — keeps the
+ * form alive when a backend references a template the FE has not registered.
  */
-declare class NoopLogger implements Logger {
-    debug(): void;
-    info(): void;
-    warn(): void;
-    error(): void;
+declare class TemplateAddonComponent {
+    private readonly templates;
+    private readonly logger;
+    readonly addon: _angular_core.InputSignal<TemplateAddon>;
+    /** Forwarded by `df-addon-slot`; surfaced to the template as its implicit `$implicit` context. */
+    readonly fieldInputs: _angular_core.InputSignal<WrapperFieldInputs | undefined>;
+    protected readonly template: _angular_core.Signal<_angular_core.TemplateRef<unknown> | null>;
+    /** Implicit context payload — template authors bind via `let-fi`. */
+    protected readonly outletContext: _angular_core.Signal<{
+        $implicit: WrapperFieldInputs | undefined;
+    }>;
+    constructor();
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<TemplateAddonComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<TemplateAddonComponent, "df-template-addon", never, { "addon": { "alias": "addon"; "required": true; "isSignal": true; }; "fieldInputs": { "alias": "fieldInputs"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
 /**
- * Enables automatic form value attachment to all events dispatched through the EventBus.
- *
- * When this feature is enabled, events dispatched via `eventBus.dispatch()` will include
- * the current form value in the `formValue` property. This is useful for event handlers
- * that need access to the complete form state at the time of the event.
- *
- * @example Global opt-in
- * ```typescript
- * provideDynamicForm(
- *   ...withMaterialFields(),
- *   withEventFormValue()
- * )
- * ```
- *
- * @example Consumer usage
- * ```typescript
- * eventBus.on<SubmitEvent>('submit').subscribe(event => {
- *   if (hasFormValue(event)) {
- *     console.log('Form value:', event.formValue);
- *   }
- * });
- * ```
- *
- * @example Per-form disable (when globally enabled)
- * ```typescript
- * const config: FormConfig = {
- *   fields: [...],
- *   options: { emitFormValueOnEvents: false }
- * };
- * ```
- *
- * @remarks
- * **Precedence rules:**
- * 1. Per-form `false` - Disables for this form, regardless of global setting
- * 2. Per-form `true` - Enables for this form, regardless of global setting
- * 3. Per-form `undefined` - Uses global setting
- * 4. Global `withEventFormValue()` - Enables globally
- * 5. No global feature - Disabled globally (default)
+ * Renderer for the universal `component` addon kind.
  *
- * @returns A DynamicFormFeature that enables form value attachment to events
+ * Loads the user-supplied component lazily (`addon.component()`) and renders
+ * it via `NgComponentOutlet` with `addon.inputs` forwarded as input bindings.
+ * The wrapper-style `fieldInputs` bag is not propagated — user components
+ * receive only what `addon.inputs` declares. Authors that need field state
+ * should switch to the `template` kind or build a wrapper.
  *
- * @public
+ * @codeOnly The `component` loader is a function; this kind is dropped in
+ * lenient validation when the config originated from JSON.
  */
-declare function withEventFormValue(): DynamicFormFeature<'event-form-value'>;
+declare class ComponentAddonComponent {
+    private readonly logger;
+    readonly addon: _angular_core.InputSignal<ComponentAddon>;
+    /** Accepted for contract uniformity — `NgComponentOutlet` setInput is strict; every kind must declare it. */
+    readonly fieldInputs: _angular_core.InputSignal<WrapperFieldInputs | undefined>;
+    protected readonly inputs: _angular_core.Signal<Record<string, unknown>>;
+    /**
+     * Latest async-loaded `{ addon, component }` pair. Tagging the result with
+     * its source addon lets `resolvedComponent` filter stale loads structurally
+     * — same kind-tagging pattern `DfAddonSlot` uses. When `addon` swaps
+     * mid-load, the prior loader still completes and writes here, but the
+     * computed ignores it because the recorded addon no longer matches the
+     * current one.
+     */
+    private readonly asyncLoaded;
+    protected readonly resolvedComponent: _angular_core.Signal<Type<unknown> | undefined>;
+    constructor();
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ComponentAddonComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<ComponentAddonComponent, "df-component-addon", never, { "addon": { "alias": "addon"; "required": true; "isSignal": true; }; "fieldInputs": { "alias": "fieldInputs"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
 
 /**
- * Configuration for excluding field values from form submission output
- * based on their reactive state (hidden, disabled, readonly).
+ * Optional collaborators a preset may need beyond the base context. Passed
+ * by the button kind component which has access to its own DI scope.
  *
- * Supports a 3-tier configuration hierarchy: Field > Form > Global.
- * The most specific level wins for each property.
- *
- * @public
+ * Adapter input components fill in the collaborators their preset semantics
+ * require:
+ * - `mat-input` / `bs-input` / `prime-input` / `ion-input` populate
+ *   `typeOverride` + `fieldValueSetter` + `fieldDefaultValueGetter` +
+ *   `baselineType` from their own DI scope.
+ * - Addons rendered outside any input field receive `{ logger }` only and
+ *   the input-specific presets warn-and-no-op.
  */
-interface ValueExclusionConfig {
+interface PresetCollaborators {
+    /** Per-field input-type override signal — populated only inside an input field. */
+    readonly typeOverride?: WritableSignal<string | undefined>;
+    /** Writer that pushes a value into the host field's tree. */
+    readonly fieldValueSetter?: (next: unknown) => void;
     /**
-     * Whether to exclude the value of hidden fields from submission output.
-     *
-     * When `true`, fields whose `hidden()` state is `true` will have their
-     * values omitted from the submitted form value.
-     *
-     * @remarks
-     * This does NOT affect HiddenField (`type: 'hidden'`) — those fields
-     * store values without UI and their `hidden()` state is always `false`.
+     * Read the host field's configured default value (from the form's
+     * `defaultValues` map keyed by `field.key`). Used by the `'reset'`
+     * preset; absent when the addon is rendered outside an active field
+     * context, in which case `'reset'` falls back to clearing.
      */
-    readonly excludeValueIfHidden?: boolean;
+    readonly fieldDefaultValueGetter?: () => unknown;
     /**
-     * Whether to exclude the value of disabled fields from submission output.
-     *
-     * When `true`, fields whose `disabled()` state is `true` will have their
-     * values omitted from the submitted form value.
+     * Baseline configured input type (from `props().type`), read at preset-run
+     * time. Used by `toggle-password-visibility` to refuse to corrupt
+     * `'email'`/`'number'`/etc. inputs into `'password'` when no override is
+     * yet set.
      */
-    readonly excludeValueIfDisabled?: boolean;
+    readonly baselineType?: () => string | undefined;
     /**
-     * Whether to exclude the value of readonly fields from submission output.
+     * Logger for warnings about presets that can't be fulfilled in this context.
      *
-     * When `true`, fields whose `readonly()` state is `true` will have their
-     * values omitted from the submitted form value.
+     * Passed via collaborators (rather than injected) because `runPresetAction`
+     * is a DI-free pure function shared across adapters — each adapter's
+     * `ADDON_PRESET_HANDLER` factory injects `DynamicFormLogger` itself and
+     * forwards it here. The `[Dynamic Forms]` prefix comes from
+     * `ConsoleLogger`'s implementation, so the final console line is identical
+     * to one logged directly via `inject(DynamicFormLogger)`.
      */
-    readonly excludeValueIfReadonly?: boolean;
+    readonly logger: Logger;
+}
+/**
+ * Apply a built-in preset action against the addon's host field. Shared
+ * across all adapters — each adapter's `ADDON_PRESET_HANDLER` provider
+ * delegates here.
+ *
+ * Presets that require adapter-specific UI mechanics (clipboard, type
+ * override) are best-effort — they no-op with a warning when the necessary
+ * collaborator isn't available (e.g., toggle-password-visibility outside an
+ * input field).
+ *
+ * @param adapterLabel Used in warnings — `'Material'` / `'Bootstrap'` / etc.
+ * @param fieldLabel   Used in warnings — `'mat-input'` / `'bs-input'` / etc.
+ */
+declare function runPresetAction(preset: AddonActionPreset, ctx: AddonActionContext, collaborators: PresetCollaborators, adapterLabel: string, fieldLabel: string): Promise<void>;
+
+/**
+ * Cache for resolved addon-kind components.
+ *
+ * Provided per-form by `provideDynamicFormDI()` so two `<df-dynamic-form>`
+ * instances with conflicting `loadComponent` factories for the same kind
+ * never share a stale entry. Has no `providedIn: 'root'` factory — the
+ * registry consumer is always inside a form scope, and a root fallback
+ * would only hide misconfiguration (an SSR cross-request hit if a future
+ * code path forgot to provide it locally).
+ *
+ * Mirrors `COMPONENT_CACHE` (field types) and `WRAPPER_COMPONENT_CACHE`
+ * (wrappers).
+ *
+ * @internal
+ */
+declare const ADDON_KIND_COMPONENT_CACHE: InjectionToken<Map<string, Type<unknown>>>;
+/**
+ * Public shape returned by {@link injectAddonKindRegistry}. Pinned explicitly
+ * so the API extractor doesn't churn between versions when the inner factory
+ * gets refactored.
+ */
+interface AddonKindRegistryRef {
+    getKind(kind: string): AddonKindDefinition | undefined;
+    hasKind(kind: string): boolean;
+    getKindNames(): string[];
+    loadKindComponent(kind: string): Promise<Type<unknown>>;
+    getLoadedKindComponent(kind: string): Type<unknown> | undefined;
+    readonly raw: ReadonlyMap<string, AddonKindDefinition>;
 }
 /**
- * Fully resolved exclusion config with all properties required.
- * Produced by the 3-tier resolution: `field ?? form ?? global`.
+ * Injection function for accessing the addon kind registry.
  *
- * @public
+ * Usage parallels {@link injectFieldRegistry}: lookup, lazy load, cache.
+ * Must be called within an injection context.
+ *
+ * @example
+ * ```typescript
+ * const addonKinds = injectAddonKindRegistry();
+ * const Component = await addonKinds.loadKindComponent('prime-icon');
+ * ```
  */
-type ResolvedValueExclusionConfig = Required<ValueExclusionConfig>;
+declare function injectAddonKindRegistry(): AddonKindRegistryRef;
 
 /**
- * Configures global value exclusion defaults for form submission output.
+ * One entry per field type that declares addon support.
  *
- * Value exclusion is **enabled by default** — field values are excluded from the
- * `(submitted)` output based on their reactive state. Use this feature to
- * override those defaults. This does NOT affect two-way binding (`value` model /
- * `entity`) — fields retain their values internally.
+ * `name` is the field-type discriminant; `slots` and `allowedKinds` mirror
+ * the `FieldTypeDefinition.addons` registration.
+ */
+interface FieldAddonSupportEntry {
+    readonly name: string;
+    readonly slots: FieldAddonSupport['slots'];
+    readonly allowedKinds: FieldAddonSupport['allowedKinds'];
+}
+/**
+ * Walk `FIELD_REGISTRY` and return every field type that opted into addons
+ * (i.e., declared `addons` on its `FieldTypeDefinition`).
  *
- * @example Default behavior (all exclusions enabled)
+ * Useful for tooling — admin UIs surfacing "which fields can carry addons?",
+ * docs generators, MCP server cross-checks. Field types without an `addons`
+ * registration ("Tier 3" — toggle, checkbox, radio, slider) are excluded.
+ *
+ * Must be called within an injection context.
+ *
+ * @example
  * ```typescript
- * provideDynamicForm(
- *   ...withMaterialFields(),
- *   withValueExclusionDefaults()
- * )
+ * @Component({ ... })
+ * class FormBuilder {
+ *   protected readonly addonable = injectFieldsSupportingAddons();
+ *
+ *   constructor() {
+ *     // -> [{ name: 'prime-input', slots: ['prefix', 'suffix'], allowedKinds: [...] }, ...]
+ *   }
+ * }
  * ```
+ */
+declare function injectFieldsSupportingAddons(): FieldAddonSupportEntry[];
+
+/**
+ * Normalises a {@link DynamicValue} into a `Signal<T>`.
  *
- * @example Disable specific exclusions
+ * Accepts a static value, a `Signal<T>`, or an `Observable<T>`. The result
+ * is a `Signal<T>` that reactively reflects the current value, suitable
+ * for direct use in Angular templates.
+ *
+ * Static values yield a `computed` that always returns the same constant —
+ * preferable to wrapping in `signal()` because the computed never causes
+ * change-detection invalidation.
+ *
+ * Pass an `injector` when calling outside an Angular injection context
+ * (e.g., from inside a `computed`). `toSignal` needs a `DestroyRef` to
+ * unsubscribe — without an injector it falls back to `inject(DestroyRef)`,
+ * which throws when called outside injection context.
+ *
+ * @example
  * ```typescript
- * provideDynamicForm(
- *   ...withMaterialFields(),
- *   withValueExclusionDefaults({ excludeValueIfReadonly: false })
- * )
+ * const isHidden = resolveDynamicValue(addon().hidden, false);
+ * // template: \@if (isHidden()) { ... }
  * ```
+ */
+declare function resolveDynamicValue<T>(value: DynamicValue<T> | undefined, fallback: T, injector?: Injector): Signal<T>;
+
+/**
+ * Register a custom addon kind with the form.
  *
- * @example Disable all exclusions (restore pre-v1 behavior)
+ * The provided definition is added to `ADDON_KIND_REGISTRY` at form
+ * initialisation, alongside the built-in `text` / `template` / `component`
+ * kinds and any kinds contributed by adapter feature helpers
+ * (`withPrimeNGAddons()` etc.).
+ *
+ * @example
  * ```typescript
  * provideDynamicForm(
  *   ...withMaterialFields(),
- *   withValueExclusionDefaults({
- *     excludeValueIfHidden: false,
- *     excludeValueIfDisabled: false,
- *     excludeValueIfReadonly: false,
- *   })
- * )
+ *   withCustomAddon({
+ *     kind: 'lucide-icon',
+ *     // Match how field types register: a default-exported component lets
+ *     // `loadComponent` return the import promise directly.
+ *     loadComponent: () => import('./lucide-icon-addon.component'),
+ *     validate: (addon) => {
+ *       if (typeof addon.icon !== 'string') {
+ *         throw new Error('lucide-icon: icon string is required');
+ *       }
+ *     },
+ *   }),
+ * );
  * ```
  *
- * @remarks
- * **Precedence rules:**
- * 1. Per-field `excludeValueIf*` on `FieldDef` — wins for that field
- * 2. Per-form `excludeValueIf*` on `FormOptions` — wins for all fields in that form
- * 3. Global `withValueExclusionDefaults()` — baseline default
- * 4. No global feature — uses token default (all enabled)
- *
- * @param config - Partial override of exclusion rules. Unspecified properties default to `true`.
- * @returns A DynamicFormFeature that configures value exclusion defaults
- *
- * @public
+ * Multiple `withCustomAddon(...)` calls are supported; later registrations
+ * for the same kind override earlier ones (with a warning logged).
  */
-declare function withValueExclusionDefaults(config?: Partial<ValueExclusionConfig>): DynamicFormFeature<'value-exclusion'>;
+declare function withCustomAddon<T extends BaseAddon>(definition: AddonKindDefinition<T>): DynamicFormFeature<'addons'>;
 
 /**
- * Configuration for when validation runs based on a field's reactive state.
- *
- * Currently controls whether hidden fields are validated. Resolved through a
- * tree-aware hierarchy: per-field overrides inherit down to descendants, with
- * per-form `FormOptions` and global `withValidationExecutionDefaults()` providing
- * the root inherited value.
+ * Handler signature for user-registered addon actions.
  *
- * @public
+ * Backends reference handlers by name via `actionRef: 'name'` on button-style
+ * addons; the dispatcher invokes the registered function with the addon's
+ * action context.
  */
-interface ValidationExecutionConfig {
-    /**
-     * Whether validators run while a field is hidden (statically, via `hidden`
-     * logic, or because any ancestor is hidden).
-     *
-     * When `false`, all validators on a hidden field are skipped — the field is
-     * effectively inert until shown. State logic (hidden/disabled/readonly) and
-     * value derivations continue to apply.
-     */
-    readonly validateWhenHidden?: boolean;
-}
+type AddonActionHandler<TValue = unknown> = (ctx: AddonActionContext<TValue>) => void;
 /**
- * Fully resolved validation execution config — every property defined.
+ * Multi-provider token populated by `provideAddonActions({...})` calls.
+ * `ADDON_ACTION_REGISTRY` aggregates these into a single name → handler map.
  *
- * @public
+ * @internal
  */
-type ResolvedValidationExecutionConfig = Required<ValidationExecutionConfig>;
+declare const ADDON_ACTION_HANDLERS: InjectionToken<readonly Record<string, AddonActionHandler<unknown>>[]>;
+/**
+ * Form-scoped name → handler map. Read by adapter button kinds at click
+ * time for `actionRef: 'name'` lookups. Provided at form scope (not root)
+ * because `ADDON_ACTION_HANDLERS` is form-scoped via `provideAddonActions`.
+ */
+declare const ADDON_ACTION_REGISTRY: InjectionToken<ReadonlyMap<string, AddonActionHandler<unknown>>>;
 
 /**
- * Configures global validation execution defaults — when validators should run
- * relative to a field's reactive state.
+ * Typed feature returned by {@link provideAddonActions}. Carries the
+ * registered handler keys as a phantom type so consumers can derive the
+ * `DynamicFormActionRegistry` augmentation in one line instead of hand-typing
+ * every key.
  *
- * By default, validators are **skipped** for hidden fields (`validateWhenHidden: false`),
- * matching what most users expect: a hidden field is inert. Use this feature to
- * restore the legacy behavior where hidden fields still validate.
+ * Phantom field is `__handlerKeys` (the leading underscores signal "internal,
+ * type-only — not for runtime access").
+ */
+type AddonActionsFeature<K extends string = string> = DynamicFormFeature<'addon-actions'> & {
+    /** @internal Phantom field carrying the registered keys; never read at runtime. */
+    readonly __handlerKeys?: K;
+};
+/**
+ * Register named action handlers reachable via JSON-driven addon configs.
  *
- * @example Default behavior — no feature needed
- * ```typescript
- * provideDynamicForm(...withMaterialFields())
- * // hidden fields skip validation
- * ```
+ * Once registered, a backend can ship
+ * `{ kind: 'prime-button', actionRef: 'openProfile' }` and the FE will invoke
+ * the corresponding handler at click time.
+ *
+ * Define handlers once and augment the registry from the same object:
  *
- * @example Restore legacy validation-on-hidden behavior
  * ```typescript
- * provideDynamicForm(
- *   ...withMaterialFields(),
- *   withValidationExecutionDefaults({ validateWhenHidden: true })
- * )
+ * export const appActions = provideAddonActions({
+ *   openProfile: (ctx) => modalService.open(ProfileModal, { data: ctx.value }),
+ *   runWorkflow: (ctx) => workflowService.run(ctx.field.key, ctx.value),
+ * });
+ *
+ * declare module '@ng-forge/dynamic-forms' {
+ *   // Pulls the keys straight off `appActions` — no manual list to keep in sync.
+ *   interface DynamicFormActionRegistry extends Record<NonNullable<typeof appActions['__handlerKeys']>, true> {}
+ * }
+ *
+ * // Then in your bootstrap:
+ * provideDynamicForm(...withPrimeNGFields(), appActions);
  * ```
  *
- * @remarks
- * **Precedence rules:**
- * 1. Per-field `FieldDef.validateWhenHidden` — wins for that field; inherits down to descendants
- *    that don't override.
- * 2. Per-form `FormOptions.validateWhenHidden` — root inherited value for the form.
- * 3. Global `withValidationExecutionDefaults()` — fallback when no form/field setting.
- * 4. No feature configured — uses token default (`validateWhenHidden: false`).
+ * Multiple `provideAddonActions(...)` calls are merged; later names override
+ * earlier ones for the same key.
+ */
+declare function provideAddonActions<const H extends Record<string, AddonActionHandler>>(handlers: H): AddonActionsFeature<keyof H & string>;
+
+/**
+ * Multi-provider token used by `withCustomAddon(...)` features to contribute
+ * addon kind definitions. `provideDynamicForm` aggregates all values into
+ * the form-scoped `ADDON_KIND_REGISTRY` map.
  *
- * @param config - Partial override. Unspecified properties keep their defaults.
- * @returns A `DynamicFormFeature` that configures validation execution defaults.
+ * @internal
+ */
+declare const ADDON_KIND_DEFINITIONS: InjectionToken<readonly AddonKindDefinition<_ng_forge_dynamic_forms.BaseAddon<_ng_forge_dynamic_forms.AddonSlot>>[]>;
+
+/**
+ * Reason an addon was dropped during validation.
  *
- * @public
+ * Each variant carries its own context fields so log messages can be both
+ * actionable (registered kinds enumerated, fix suggestion present) and
+ * machine-readable (admin UIs surfacing per-error guidance).
  */
-declare function withValidationExecutionDefaults(config?: Partial<ValidationExecutionConfig>): DynamicFormFeature<'validation-execution'>;
+type AddonWarning = {
+    type: 'unknown-field-type';
+    fieldKey: string;
+    fieldType: string;
+} | {
+    type: 'field-type-no-addon-support';
+    fieldKey: string;
+    fieldType: string;
+} | {
+    type: 'unknown-slot';
+    fieldKey: string;
+    fieldType: string;
+    slot: string;
+    allowedSlots: readonly string[];
+} | {
+    type: 'unknown-kind';
+    fieldKey: string;
+    kind: string;
+    registeredKinds: readonly string[];
+} | {
+    type: 'kind-not-allowed';
+    fieldKey: string;
+    fieldType: string;
+    kind: string;
+    allowedKinds: readonly string[];
+} | {
+    type: 'shape-violation';
+    fieldKey: string;
+    kind: string;
+    reason: string;
+} | {
+    type: 'code-only-kind-in-json';
+    fieldKey: string;
+    kind: string;
+} | {
+    type: 'code-only-action-in-json';
+    fieldKey: string;
+    reason: string;
+};
+/**
+ * Render an `AddonWarning` to a developer-friendly message.
+ *
+ * Returns the bare message — the `[Dynamic Forms]` prefix is added by the
+ * library's logger (`ConsoleLogger`) and by `DynamicFormError`. Pass the
+ * result of this function directly into `logger.warn(...)` to get the
+ * standard prefixed line; use `logAddonWarnings()` for direct
+ * `console.warn` output (which prefixes manually).
+ *
+ * Messages are designed to be actionable: they enumerate the relevant set
+ * (registered kinds, allowed slots) and suggest a likely fix.
+ */
+declare function formatAddonWarning(w: AddonWarning): string;
 
 /**
- * Zero-cost type carrier used in wrapper registrations.
+ * Walk a field's addons; return the survivors plus a list of warnings for
+ * anything dropped.
  *
- * Returns `undefined` at runtime but is typed as `T`, so TypeScript can
- * thread a wrapper's config type through `createWrappers(...)` into the
- * `InferWrapperRegistry<typeof ...>` utility without requiring users to
- * hand-write the augmentation shape.
+ * Pure: receives the registries as arguments (so the function is reusable
+ * outside Angular's DI — tests, server-side validation, etc.).
+ *
+ * @param field        The field to validate.
+ * @param fieldRegistry Snapshot of `FIELD_REGISTRY` map.
+ * @param kindRegistry  Snapshot of `ADDON_KIND_REGISTRY` map.
+ * @param source       Whether the config originated from JSON (lenient drop
+ *                      of code-only kinds) or inline TypeScript.
+ */
+declare function validateFieldAddons(field: FieldDef<unknown>, fieldRegistry: ReadonlyMap<string, FieldTypeDefinition>, kindRegistry: ReadonlyMap<string, AddonKindDefinition>, source: 'json' | 'inline'): {
+    addons: AnyAddon[];
+    warnings: AddonWarning[];
+};
+/**
+ * Recursively walk a field tree, validating each field's addons. Returns a
+ * sanitized copy of the input field array plus accumulated warnings.
+ */
+declare function walkAndValidateAddons(fields: readonly FieldDef<unknown>[], fieldRegistry: ReadonlyMap<string, FieldTypeDefinition>, kindRegistry: ReadonlyMap<string, AddonKindDefinition>, source: 'json' | 'inline'): {
+    fields: FieldDef<unknown>[];
+    warnings: AddonWarning[];
+};
+
+/**
+ * Options accepted by {@link sanitizeFormConfig}.
+ */
+interface SanitizeFormConfigOptions {
+    /**
+     * Whether the config originated from JSON (server-driven) or inline
+     * TypeScript code.
+     *
+     * - `'inline'` (default): keeps everything; assumes the config is
+     *   authored in code and code-only constructs (inline `action`
+     *   functions, `component` kind) are intentional. The default avoids
+     *   silently stripping inline behaviour during in-process authoring.
+     * - `'json'`: drops code-only addon kinds (`component`, inline
+     *   `action: function`) with a warning, since they cannot survive
+     *   serialization. Use this when sanitising configs received from a
+     *   backend / form-builder UI.
+     */
+    source?: 'json' | 'inline';
+}
+/**
+ * Result of a `sanitizeFormConfig` call.
+ */
+interface SanitizedFormConfig {
+    /** Sanitized config — invalid addons stripped from the field tree. */
+    sanitized: FormConfig;
+    /** Structured list of every addon that was dropped, and why. */
+    warnings: readonly AddonWarning[];
+}
+/**
+ * Walk a `FormConfig`, validate every field's addons against the active
+ * `FIELD_REGISTRY` and `ADDON_KIND_REGISTRY`, and return a sanitized copy
+ * plus a list of dropped-addon warnings.
+ *
+ * Distinct from the INTERNAL `validateFormConfig` in
+ * `utils/config-validation/config-validator.ts` (which throws on
+ * structural errors like duplicate keys / unknown field types). This
+ * helper is the PUBLIC, lenient addon-shape pass — renamed to
+ * `sanitizeFormConfig` to avoid the name collision.
+ *
+ * Lenient by design: invalid addons are dropped (with warnings) rather than
+ * thrown. The form keeps rendering even when the backend ships an addon the
+ * FE doesn't understand.
+ *
+ * `<df-dynamic-form>` already runs this internally at form init — calling
+ * the public helper AND passing the original config to the form will
+ * double-emit warnings. Use this entry point only when you need the
+ * sanitized config or warning list outside the form (e.g., admin-UI
+ * diagnostics, build-time lints).
+ *
+ * Must be called within an Angular injection context — typically inside
+ * an admin-UI component or a `runInInjectionContext()` block on the server.
  *
  * @example
  * ```typescript
- * const wrappers = createWrappers(
- *   {
- *     wrapperName: 'section',
- *     loadComponent: () => import('./section-wrapper'),
- *     props: wrapperProps<SectionWrapper>(),
- *   },
- * );
- *
- * declare module '@ng-forge/dynamic-forms' {
- *   interface FieldRegistryWrappers extends InferWrapperRegistry<typeof wrappers> {}
+ * @Component({ ... })
+ * class AdminFormBuilder {
+ *   private readonly check = (cfg: FormConfig) => {
+ *     const { sanitized, warnings } = sanitizeFormConfig(cfg, { source: 'json' });
+ *     if (warnings.length > 0) {
+ *       this.diagnostics.set(warnings);
+ *     }
+ *     return sanitized;
+ *   };
  * }
  * ```
  */
-declare function wrapperProps<T>(): T;
+declare function sanitizeFormConfig(config: FormConfig, options?: SanitizeFormConfigOptions): SanitizedFormConfig;
+/**
+ * Default warning sink. Pass a `DynamicFormLogger` to route through the
+ * form's configured logger (respects `NoopLogger` opt-out); omit it to
+ * fall back to `console.warn` for build-time / admin-UI use cases that
+ * run outside an Angular injection context.
+ */
+declare function logAddonWarnings(warnings: readonly AddonWarning[], logger?: Logger): void;
+/**
+ * DI-free variant of {@link sanitizeFormConfig} for tooling that lives
+ * outside Angular's injector — build-time linters, MCP-side checks, CLI
+ * scripts.
+ *
+ * Caller passes the registries explicitly; the result has the same shape
+ * as the DI-bound version.
+ */
+declare function sanitizeFormConfigPure(config: FormConfig, fieldRegistry: ReadonlyMap<string, FieldTypeDefinition>, kindRegistry: ReadonlyMap<string, AddonKindDefinition>, options?: SanitizeFormConfigOptions): SanitizedFormConfig;
 
 interface FieldWithValidation {
     readonly required?: boolean;
@@ -5706,7 +6927,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$1 = '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';
+type ExcludedKeys$1 = '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 ValueFieldComponent<T extends BaseValueField<Record<string, unknown> | unknown, unknown, FieldMeta, boolean>> = Prettify<WithInputSignals<Omit<T, ExcludedKeys$1>>>;
 
 interface BaseCheckedField<TProps, TMeta extends FieldMeta = FieldMeta> extends FieldDef<TProps, TMeta>, FieldWithValidation {
@@ -5719,7 +6940,7 @@ interface BaseCheckedField<TProps, TMeta extends FieldMeta = FieldMeta> extends
     required?: boolean;
 }
 declare function isCheckedField<TProps, TMeta extends FieldMeta = FieldMeta>(field: FieldDef<TProps, TMeta>): field is BaseCheckedField<TProps, TMeta>;
-type ExcludedKeys = 'type' | 'conditionals' | 'value' | 'disabled' | 'readonly' | 'hidden' | 'col' | keyof FieldWithValidation | 'excludeValueIfHidden' | 'excludeValueIfDisabled' | 'excludeValueIfReadonly' | 'validateWhenHidden' | 'wrappers' | 'skipAutoWrappers' | 'skipDefaultWrappers';
+type ExcludedKeys = 'type' | 'conditionals' | 'value' | 'disabled' | 'readonly' | 'hidden' | 'col' | keyof FieldWithValidation | 'excludeValueIfHidden' | 'excludeValueIfDisabled' | 'excludeValueIfReadonly' | 'validateWhenHidden' | 'wrappers' | 'skipAutoWrappers' | 'skipDefaultWrappers' | 'addons';
 type CheckedFieldComponent<T extends BaseCheckedField<Record<string, unknown> | unknown>> = Prettify<WithInputSignals<Omit<T, ExcludedKeys>>>;
 
 declare function applyValidator(config: ValidatorConfig, fieldPath: SchemaPath<any> | SchemaPathTree<any>): void;
@@ -6495,8 +7716,6 @@ declare function applyMetaToElement(element: Element, meta: FieldMeta | undefine
  * );
  * // user.value() keeps the old user data during loading transitions
  * ```
- *
- * @experimental Uses Angular's experimental resource composition APIs.
  */
 declare function withPreviousValue<T>(input: Resource<T>): Resource<T>;
 
@@ -6615,6 +7834,12 @@ interface ResolvedArrayItemField {
     inputs: Signal<Record<string, unknown>>;
     /** Whether required mapped inputs are available for safe component instantiation. */
     renderReady: Signal<boolean>;
+    /**
+     * Whether the array-item field is currently hidden — mirrors `ResolvedField.hidden`
+     * so the same `@if (!field.hidden())` template gate works for top-level and
+     * array-item fields.
+     */
+    hidden: Signal<boolean>;
 }
 /**
  * Resolved array item ready for declarative rendering with ngComponentOutlet.
@@ -6645,7 +7870,9 @@ declare class ArrayFieldComponent<TModel extends Record<string, unknown> = Recor
     protected readonly environmentInjector: EnvironmentInjector;
     private readonly eventBus;
     private readonly logger;
-    private readonly templateRegistry;
+    private readonly arrayItemRegistry;
+    private readonly slot;
+    /** Bound id-generator reference threaded to `resolveArrayItem` so callsites stay terse. */
     private readonly generateItemId;
     field: _angular_core.InputSignal<ArrayField<readonly ArrayItemDefinition[]>>;
     key: _angular_core.InputSignal<string>;
@@ -6710,9 +7937,7 @@ declare class ArrayFieldComponent<TModel extends Record<string, unknown> = Recor
     private readonly itemTemplates;
     private readonly arrayFieldTrees;
     private readonly resolvedItemsSignal;
-    private readonly updateVersion;
-    private readonly pendingInitializationCycle;
-    private readonly settledInitializationCycle;
+    private readonly fsm;
     /**
      * Map of item IDs to their current positions. O(1) lookup vs O(n) indexOf().
      * Used by child linkedSignals to reactively track their position in the array.
@@ -6832,71 +8057,6 @@ declare class ContainerFieldComponent {
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<ContainerFieldComponent, "div[container-field]", never, { "field": { "alias": "field"; "required": true; "isSignal": true; }; "key": { "alias": "key"; "required": true; "isSignal": true; }; "className": { "alias": "className"; "required": false; "isSignal": true; }; "hidden": { "alias": "hidden"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
-/**
- * Type representing a FieldTree for an array.
- * Extends FieldTree to add numeric indexing for accessing item FieldTrees.
- */
-type ArrayFieldTree<T> = FieldTree<T[]> & {
-    readonly [index: number]: FieldTree<T> | undefined;
-};
-/**
- * Get the length of an array FieldTree.
- */
-declare function getArrayLength<T>(arrayFieldTree: ArrayFieldTree<T>): number;
-/**
- * Read-only view of a single field's observable state.
- *
- * Whitelisted read signals copied from Angular Signal Forms' `FieldState` so wrappers
- * can observe a field without being able to mutate it. New write-capable members
- * added in future Angular versions are excluded by default (the `Pick` list stays
- * the source of truth).
- *
- * `value` is narrowed from `WritableSignal<TValue>` to `Signal<TValue>` so consumers
- * cannot write through it.
- */
-interface ReadonlyFieldTree<TValue = unknown> {
-    readonly value: Signal<TValue>;
-    readonly valid: Signal<boolean>;
-    readonly invalid: Signal<boolean>;
-    readonly touched: Signal<boolean>;
-    readonly dirty: Signal<boolean>;
-    readonly required: Signal<boolean>;
-    readonly disabled: Signal<boolean>;
-    readonly hidden: Signal<boolean>;
-    readonly errors: Signal<readonly unknown[]>;
-}
-/**
- * Build a `ReadonlyFieldTree` by extracting the whitelisted read signals from a
- * Signal Forms `FieldTree`. Returns a fresh plain object — no casting, no proxying,
- * so consumers only see the narrow surface and Angular's `WritableSignal` capability
- * on `value` is hidden.
- */
-declare function toReadonlyFieldTree<TValue>(field: FieldTree<TValue>): ReadonlyFieldTree<TValue>;
-
-/**
- * Input shape passed to a wrapper component via the `fieldInputs` input.
- *
- * Carries the wrapped field's mapper outputs plus an optional `field`
- * read-only view. Wrappers reached through a container path (which has
- * no FieldTree of its own) receive `fieldInputs === undefined`, so any
- * wrapper that reads `fieldInputs.field` must guard for it.
- *
- * Mappers must emit new rawInputs objects per tick rather than mutating
- * the previous one — this bag is a shallow spread, so mutations to shared
- * nested values leak to downstream wrappers.
- */
-interface WrapperFieldInputs {
-    readonly key: string;
-    readonly label?: string;
-    readonly placeholder?: string;
-    readonly className?: string;
-    readonly props?: Record<string, unknown>;
-    readonly validationMessages?: Record<string, string>;
-    readonly defaultValidationMessages?: Record<string, string>;
-    readonly field?: ReadonlyFieldTree;
-    readonly [key: string]: unknown;
-}
-
 /**
  * Native JavaScript utility functions to replace lodash-es
  * These are simple implementations for common object manipulation patterns
@@ -6975,5 +8135,5 @@ declare class RootFormRegistryService {
  */
 declare const INITIALIZATION_TIMEOUT_MS: InjectionToken<number>;
 
-export { ARRAY_CONTEXT, AppendArrayItemEvent, ArrayFieldComponent, BUILT_IN_FIELDS, ConsoleLogger, ContainerFieldComponent, DEFAULT_PROPS, DEFAULT_VALIDATION_MESSAGES, DEFAULT_WRAPPERS, DynamicForm, DynamicFormError, DynamicFormLogger, DynamicTextPipe, EventBus, EventDispatcher, FIELD_REGISTRY, FIELD_SIGNAL_CONTEXT, FORM_OPTIONS, FormClearEvent, FormResetEvent, GROUP_CONTEXT, GroupFieldComponent, INITIALIZATION_TIMEOUT_MS, InsertArrayItemEvent, MoveArrayItemEvent, NextPageEvent, NoopLogger, PageChangeEvent, PopArrayItemEvent, PrependArrayItemEvent, PreviousPageEvent, RemoveAtIndexEvent, RootFormRegistryService, ShiftArrayItemEvent, SubmitEvent, WRAPPER_REGISTRY, applyMetaToElement, applyValidator, applyValidators, arrayEvent, arrayFieldMapper, baseFieldMapper, buildBaseInputs, containerFieldMapper, createField, createWrappers, dynamicTextToObservable, evaluateNonFieldDisabled, evaluateNonFieldHidden, field, formConfig, getArrayLength, groupFieldMapper, hasFormValue, interpolateParams, isArrayField, isCheckedField, isContainerField, isContainerTypedField, isDisplayOnlyField, isEqual, isFormStateCondition, isGroupField, isLeafField, isPageField, isRowField, isSimplifiedArrayField, isValueBearingField, isValueField, isWrapperTypeDefinition, isWrappersBundle, omit, pageFieldMapper, provideDynamicForm, resolveNextButtonDisabled, resolveNonFieldDisabled, resolveNonFieldHidden, resolveSubmitButtonDisabled, resolveTokens, rowFieldMapper, textFieldMapper, toReadonlyFieldTree, withEventFormValue, withLoggerConfig, withPreviousValue, withValidationExecutionDefaults, withValueExclusionDefaults, wrapperProps };
-export type { ArrayAllowedChildren, ArrayButtonConfig, ArrayContext, ArrayField, ArrayFieldTree, ArrayItemContext, ArrayItemDefinitionTemplate, ArrayItemTemplate, AsyncCondition, AsyncConditionFunction, AsyncCustomValidator, AsyncDerivationFunction, AsyncValidatorConfig, AvailableFieldTypes, BaseCheckedField, BaseValidatorConfig, BaseValueField, BuiltInValidatorConfig, ButtonLogicContext, CheckedFieldComponent, ConditionalExpression, ContainerAllowedChildren, ContainerField, ContainerFieldTypes, CssWrapper, CustomFnConfig, CustomFunction, CustomValidator, CustomValidatorConfig, DeclarativeHttpValidatorConfig, DynamicFormFieldRegistry, DynamicText, EvaluationContext, ExtractField, ExtractFieldDefs, ExtractFormValue, FieldComponent, FieldDef, FieldMeta, FieldOption, FieldPathAccess, FieldRegistryContainers, FieldRegistryLeaves, FieldRegistryWrappers, FieldScope, FieldSignalContext, FieldStateContext, FieldStateInfo, FieldTypeDefinition, FieldWithValidation, FieldWrapper, FormConfig, FormEvent, FormEventConstructor, FormFieldStateMap, FormMode, FormModeDetectionResult, FormOptions, FormStateCondition, GroupAllowedChildren, GroupField, HttpCondition, HttpCustomValidator, HttpRequestConfig, HttpResourceRequest, HttpValidationResponseMapping, InferFormValue$1 as InferFormValue, InferWrapperRegistry, LeafFieldTypes, Logger, LogicConfig, MapperFn, NarrowField, NarrowFields, NextButtonOptions, NonFieldLogicConfig, NonFieldLogicContext, NonFieldLogicType, PageAllowedChildren, PageField, Prettify, ReadonlyFieldTree, RegisteredFieldTypes, ResolvedValidationExecutionConfig, ResolvedValueExclusionConfig, RowAllowedChildren, RowField, SchemaApplicationConfig, SchemaDefinition, SimplifiedArrayField, StateLogicConfig, SubmissionActionResult, SubmissionConfig, SubmitButtonOptions, TextElementType, TextField, TextProps, TokenContext, ValidationError, ValidationExecutionConfig, ValidationMessages, ValidatorConfig, ValueExclusionConfig, ValueFieldComponent, ValueHandlingMode, ValueType, WithInputSignals, WrapperConfig, WrapperFieldInputs, WrapperRegistration, WrapperTypeDefinition, WrappersBundle };
+export { ADDON_ACTION_HANDLERS, ADDON_ACTION_REGISTRY, ADDON_KIND_COMPONENT_CACHE, ADDON_KIND_DEFINITIONS, ADDON_KIND_REGISTRY, ARRAY_CONTEXT, AppendArrayItemEvent, ArrayFieldComponent, BUILT_IN_FIELDS, ComponentAddonComponent, ConsoleLogger, ContainerFieldComponent, DEFAULT_PROPS, DEFAULT_VALIDATION_MESSAGES, DEFAULT_WRAPPERS, DF_FIELD_TEMPLATES, DfAddonSlot, DfTemplate, DynamicForm, DynamicFormError, DynamicFormLogger, DynamicTextPipe, EventBus, EventDispatcher, FIELD_REGISTRY, FIELD_SIGNAL_CONTEXT, FORM_OPTIONS, FormClearEvent, FormResetEvent, GROUP_CONTEXT, GroupFieldComponent, INITIALIZATION_TIMEOUT_MS, InsertArrayItemEvent, MoveArrayItemEvent, NextPageEvent, NoopLogger, PageChangeEvent, PopArrayItemEvent, PrependArrayItemEvent, PreviousPageEvent, RemoveAtIndexEvent, RootFormRegistryService, ShiftArrayItemEvent, SubmitEvent, TemplateAddonComponent, TextAddonComponent, WRAPPER_REGISTRY, applyMetaToElement, applyValidator, applyValidators, arrayEvent, arrayFieldMapper, baseFieldMapper, buildBaseInputs, containerFieldMapper, createField, createWrappers, dynamicTextToObservable, evaluateNonFieldDisabled, evaluateNonFieldHidden, field, formConfig, formatAddonWarning, getArrayLength, groupFieldMapper, hasFormValue, injectAddonKindRegistry, injectFieldSignalContext, injectFieldsSupportingAddons, interpolateParams, isArrayField, isCheckedField, isContainerField, isContainerTypedField, isDisplayOnlyField, isEqual, isFieldBoundContext, isFormStateCondition, isGroupField, isLeafField, isPageField, isRowField, isSimplifiedArrayField, isValueBearingField, isValueField, isWrapperTypeDefinition, isWrappersBundle, logAddonWarnings, omit, pageFieldMapper, provideAddonActions, provideDynamicForm, resolveDynamicValue, resolveNextButtonDisabled, resolveNonFieldDisabled, resolveNonFieldHidden, resolveSubmitButtonDisabled, resolveTokens, rowFieldMapper, runPresetAction, sanitizeFormConfig, sanitizeFormConfigPure, textFieldMapper, toReadonlyFieldTree, validateFieldAddons, walkAndValidateAddons, withCustomAddon, withEventFormValue, withLegacyStatusClasses, withLoggerConfig, withPreviousValue, withValidationExecutionDefaults, withValueExclusionDefaults, wrapperProps, writeToFieldValue };
+export type { AddonActionContext, AddonActionHandler, AddonActionPreset, AddonActionsFeature, AddonKindDefinition, AddonKindSchema, AddonShapeValidator, AddonSlot, AddonWarning, AnyAddon, ArrayAllowedChildren, ArrayButtonConfig, ArrayContext, ArrayField, ArrayFieldTree, ArrayItemContext, ArrayItemDefinitionTemplate, ArrayItemTemplate, AsyncCondition, AsyncConditionFunction, AsyncCustomValidator, AsyncDerivationFunction, AsyncValidatorConfig, AvailableFieldTypes, BaseAddon, BaseCheckedField, BaseValidatorConfig, BaseValueField, BuiltInValidatorConfig, ButtonLogicContext, CheckedFieldComponent, CommonAddonActionPreset, CommonAddonSlot, ComponentAddon, ConditionalExpression, ContainerAllowedChildren, ContainerField, ContainerFieldTypes, CssWrapper, CustomFnConfig, CustomFunction, CustomValidator, CustomValidatorConfig, DeclarativeHttpValidatorConfig, DynamicFormActionRegistry, DynamicFormAddonActionPresetRegistry, DynamicFormAddonRegistry, DynamicFormAddonSlotRegistry, DynamicFormFieldRegistry, DynamicText, DynamicValue, EvaluationContext, ExtractField, ExtractFieldDefs, ExtractFormValue, FieldAddonSupport, FieldAddonSupportEntry, FieldBoundAddonActionContext, FieldComponent, FieldDef, FieldMeta, FieldOption, FieldPathAccess, FieldRegistryContainers, FieldRegistryLeaves, FieldRegistryWrappers, FieldScope, FieldSignalContext, FieldStateContext, FieldStateInfo, FieldTypeDefinition, FieldWithValidation, FieldWrapper, FormConfig, FormEvent, FormEventConstructor, FormFieldStateMap, FormMode, FormModeDetectionResult, FormOptions, FormStateCondition, GroupAllowedChildren, GroupField, HttpCondition, HttpCustomValidator, HttpRequestConfig, HttpResourceRequest, HttpValidationResponseMapping, InferFormValue$1 as InferFormValue, InferWrapperRegistry, LeafFieldTypes, Logger, LogicConfig, MapperFn, NarrowField, NarrowFields, NextButtonOptions, NonFieldLogicConfig, NonFieldLogicContext, NonFieldLogicType, OrphanAddonActionContext, PageAllowedChildren, PageField, PresetCollaborators, Prettify, ReadonlyFieldTree, RegisteredActionRef, RegisteredFieldTypes, ResolvedValidationExecutionConfig, ResolvedValueExclusionConfig, RowAllowedChildren, RowField, SanitizeFormConfigOptions, SanitizedFormConfig, SchemaApplicationConfig, SchemaDefinition, SimplifiedArrayField, StateLogicConfig, SubmissionActionResult, SubmissionConfig, SubmitButtonOptions, TemplateAddon, TextAddon, TextElementType, TextField, TextProps, TokenContext, ValidationError, ValidationExecutionConfig, ValidationMessages, ValidatorConfig, ValueExclusionConfig, ValueFieldComponent, ValueHandlingMode, ValueType, WithInputSignals, WrapperConfig, WrapperFieldInputs, WrapperRegistration, WrapperTypeDefinition, WrappersBundle };