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

package/fesm2022/{ng-forge-dynamic-forms-ng-forge-dynamic-forms-o3rJX4vG.mjs → ng-forge-dynamic-forms-ng-forge-dynamic-forms-BbgkzKuI.mjs}

@@ -1,13 +1,14 @@
 import * as i0 from '@angular/core';
-import { InjectionToken, reflectComponentType, Injector, inject, EnvironmentInjector, DestroyRef, computed, input, ViewContainerRef, signal, Directive, Injectable, isSignal, untracked, linkedSignal, ChangeDetectionStrategy, Component, resourceFromSnapshots, runInInjectionContext, afterNextRender, isWritableSignal, model, makeEnvironmentProviders, Pipe } from '@angular/core';
+import { InjectionToken, inject, reflectComponentType, Injector, EnvironmentInjector, DestroyRef, computed, signal, input, ViewContainerRef, Directive, Injectable, isSignal, untracked, linkedSignal, ChangeDetectionStrategy, Component, resourceFromSnapshots, runInInjectionContext, afterNextRender, isWritableSignal, TemplateRef, model, contentChildren, makeEnvironmentProviders, Pipe } from '@angular/core';
 import { explicitEffect } from 'ngxtension/explicit-effect';
-import { of, forkJoin, from, catchError, map, switchMap, isObservable, firstValueFrom, exhaustMap, EMPTY, Subject, filter, TimeoutError, throwError, defer, combineLatest, pipe, debounceTime, distinctUntilChanged, tap, startWith, scan as scan$1, Observable, concatMap, take as take$1, pairwise, takeUntil, combineLatestWith, auditTime, scheduled, queueScheduler, merge, timer } from 'rxjs';
 import { takeUntilDestroyed, toObservable, toSignal, rxResource, outputFromObservable } from '@angular/core/rxjs-interop';
+import { of, forkJoin, from, catchError, map, switchMap, isObservable, firstValueFrom, exhaustMap, EMPTY, Subject, filter, TimeoutError, throwError, defer, combineLatest, pipe, debounceTime, distinctUntilChanged, tap, startWith, scan as scan$1, Observable, concatMap, take as take$1, pairwise, takeUntil, combineLatestWith, auditTime, scheduled, queueScheduler, merge, timer } from 'rxjs';
 import { submit, email, min, max, minLength, maxLength, pattern, required, validate, validateAsync, validateHttp, disabled, readonly, hidden, applyEach, applyWhenValue, applyWhen, apply, schema, validateStandardSchema, validateTree, form, provideSignalFormsConfig } from '@angular/forms/signals';
 import { scan, map as map$1, filter as filter$1, take, switchMap as switchMap$1, timeout, catchError as catchError$1, shareReplay } from 'rxjs/operators';
 import { HttpClient } from '@angular/common/http';
 import { isStandardSchemaMarker } from '@ng-forge/dynamic-forms/schema';
 import { NG_STATUS_CLASSES } from '@angular/forms/signals/compat';
+import { NgComponentOutlet, AsyncPipe, NgTemplateOutlet } from '@angular/common';
 
 /**
  * Type guard for WrapperTypeDefinition.
@@ -97,28 +98,39 @@ const DEFAULT_WRAPPERS = new InjectionToken('DEFAULT_WRAPPERS');
  *
  * @example
  * ```typescript
- * // In a mapper function
+ * // In a mapper function — prefer the helper for required access (descriptive error).
  * export function mapValueField(fieldDef: BaseValueField<any, any>): Binding[] {
- *   const context = inject(FIELD_SIGNAL_CONTEXT);
+ *   const context = injectFieldSignalContext();
  *   const form = context.form();
  *   // ... use context
  * }
  *
- * // In a component
- * export class MyFieldComponent {
- *   private context = inject(FIELD_SIGNAL_CONTEXT);
+ * // Optional access — token directly, returns null if not provided.
+ * const ctx = inject(FIELD_SIGNAL_CONTEXT, { optional: true });
+ * if (ctx) {
+ *   // ...
  * }
  * ```
  */
-const FIELD_SIGNAL_CONTEXT = new InjectionToken('FIELD_SIGNAL_CONTEXT', {
-    providedIn: null, // Not provided at root - must be provided by DynamicForm
-    factory: () => {
-        throw new DynamicFormError('FIELD_SIGNAL_CONTEXT was not provided. ' +
-            'This token must be provided by DynamicFormComponent or a container field component. ' +
-            'If you are calling a mapper function directly, ensure it runs within runInInjectionContext() ' +
-            'with an injector that provides FIELD_SIGNAL_CONTEXT.');
-    },
-});
+const FIELD_SIGNAL_CONTEXT = new InjectionToken('FIELD_SIGNAL_CONTEXT');
+/**
+ * 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 })`.
+ */
+function injectFieldSignalContext() {
+    const ctx = inject(FIELD_SIGNAL_CONTEXT, { optional: true });
+    if (!ctx) {
+        throw new DynamicFormError('FIELD_SIGNAL_CONTEXT is not provided. This consumer must run inside a <df-dynamic-form> component tree.');
+    }
+    return ctx;
+}
 /**
  * Injection token for providing array context metadata to mappers and components.
  *
@@ -252,65 +264,57 @@ const FORM_OPTIONS = new InjectionToken('FORM_OPTIONS');
  * and inherited by all children via Angular's hierarchical injector.
  */
 const EXTERNAL_DATA = new InjectionToken('EXTERNAL_DATA');
+
 /**
- * Injection token for array-level template registry.
- *
- * This registry tracks which template was used to create each array item,
- * keyed by the item's unique ID. This is essential for "recreate" operations
- * (e.g., after removing items from the middle) where we need to re-resolve
- * items using their original templates, not a fallback.
- *
- * The token is provided by ArrayFieldComponent at its level and shared
- * across all items in that array. Each nested array gets its own registry.
- *
- * @example
- * ```typescript
- * // In ArrayFieldComponent
- * providers: [
- *   { provide: ARRAY_TEMPLATE_REGISTRY, useValue: new Map() }
- * ]
- *
- * // When adding items
- * const registry = inject(ARRAY_TEMPLATE_REGISTRY);
- * registry.set(itemId, templates);
+ * Injection token for the dynamic forms logger.
  *
- * // During recreate, look up original template
- * const originalTemplate = registry.get(existingItemId);
- * ```
+ * Provided by provideDynamicForm() with ConsoleLogger as default.
+ * Override with withLoggerConfig(false) to disable logging.
  */
-const ARRAY_TEMPLATE_REGISTRY = new InjectionToken('ARRAY_TEMPLATE_REGISTRY');
+const DynamicFormLogger = new InjectionToken('DynamicFormLogger');
+
 /**
- * Injection token for array-level item ID generator.
- *
- * Provides a function that generates unique IDs for array items. Each array
- * component instance gets its own generator (via useFactory), ensuring:
- * - SSR hydration compatibility (server and client generate same IDs for same array)
- * - No global state pollution between form instances
- * - Deterministic IDs within each array's lifecycle
- *
- * The token is provided by ArrayFieldComponent at its level with a factory
- * that creates a fresh counter for each array instance.
- *
- * @example
- * ```typescript
- * // In ArrayFieldComponent
- * providers: [
- *   { provide: ARRAY_ITEM_ID_GENERATOR, useFactory: createArrayItemIdGenerator }
- * ]
- *
- * // Usage
- * const generateId = inject(ARRAY_ITEM_ID_GENERATOR);
- * const itemId = generateId(); // 'item-0', 'item-1', etc.
- * ```
+ * Shared empty chain — returned when no wrappers apply so callers get a
+ * stable reference. Freezing makes accidental mutation observable.
  */
-const ARRAY_ITEM_ID_GENERATOR = new InjectionToken('ARRAY_ITEM_ID_GENERATOR');
+const EMPTY_WRAPPERS = Object.freeze([]);
 /**
- * Factory function that creates a new array item ID generator.
- * Each invocation creates an independent counter starting at 0.
+ * Element-wise identity (`===`) comparator for wrapper chains. Used as the
+ * `equal` option on signal memoisation so reconciled `FieldDef`s with the
+ * same chain don't churn downstream — relies on `WrapperConfig` objects
+ * being stable across ticks, which holds for configs declared in
+ * `FormConfig` / `createWrappers(...)`.
  */
-function createArrayItemIdGenerator() {
-    let counter = 0;
-    return () => `item-${counter++}`;
+function isSameWrapperChain(a, b) {
+    if (a === b)
+        return true;
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++) {
+        if (a[i] !== b[i])
+            return false;
+    }
+    return true;
+}
+/**
+ * Resolves the wrapper chain for a field.
+ *
+ * Merge order (outermost → innermost): auto-associations, form defaults,
+ * field-level wrappers. `wrappers: null` skips all three; `skipAutoWrappers` /
+ * `skipDefaultWrappers` on the field opt out of individual layers. Fresh
+ * array per call — downstream memoisation is on the consuming computed.
+ */
+function resolveWrappers(field, defaultWrappers, autoAssociations) {
+    if (field.wrappers === null) {
+        return EMPTY_WRAPPERS;
+    }
+    const autoWrappers = field.skipAutoWrappers ? EMPTY_WRAPPERS : (autoAssociations.get(field.type) ?? EMPTY_WRAPPERS);
+    const defaults = field.skipDefaultWrappers ? EMPTY_WRAPPERS : (defaultWrappers ?? EMPTY_WRAPPERS);
+    const fieldLevel = field.wrappers ?? EMPTY_WRAPPERS;
+    if (autoWrappers.length === 0 && defaults.length === 0 && fieldLevel.length === 0) {
+        return EMPTY_WRAPPERS;
+    }
+    return [...autoWrappers, ...defaults, ...fieldLevel];
 }
 
 /**
@@ -507,58 +511,6 @@ class WrapperAwareInjector extends Injector {
     }
 }
 
-/**
- * Injection token for the dynamic forms logger.
- *
- * Provided by provideDynamicForm() with ConsoleLogger as default.
- * Override with withLoggerConfig(false) to disable logging.
- */
-const DynamicFormLogger = new InjectionToken('DynamicFormLogger');
-
-/**
- * Shared empty chain — returned when no wrappers apply so callers get a
- * stable reference. Freezing makes accidental mutation observable.
- */
-const EMPTY_WRAPPERS = Object.freeze([]);
-/**
- * Element-wise identity (`===`) comparator for wrapper chains. Used as the
- * `equal` option on signal memoisation so reconciled `FieldDef`s with the
- * same chain don't churn downstream — relies on `WrapperConfig` objects
- * being stable across ticks, which holds for configs declared in
- * `FormConfig` / `createWrappers(...)`.
- */
-function isSameWrapperChain(a, b) {
-    if (a === b)
-        return true;
-    if (a.length !== b.length)
-        return false;
-    for (let i = 0; i < a.length; i++) {
-        if (a[i] !== b[i])
-            return false;
-    }
-    return true;
-}
-/**
- * Resolves the wrapper chain for a field.
- *
- * Merge order (outermost → innermost): auto-associations, form defaults,
- * field-level wrappers. `wrappers: null` skips all three; `skipAutoWrappers` /
- * `skipDefaultWrappers` on the field opt out of individual layers. Fresh
- * array per call — downstream memoisation is on the consuming computed.
- */
-function resolveWrappers(field, defaultWrappers, autoAssociations) {
-    if (field.wrappers === null) {
-        return EMPTY_WRAPPERS;
-    }
-    const autoWrappers = field.skipAutoWrappers ? EMPTY_WRAPPERS : (autoAssociations.get(field.type) ?? EMPTY_WRAPPERS);
-    const defaults = field.skipDefaultWrappers ? EMPTY_WRAPPERS : (defaultWrappers ?? EMPTY_WRAPPERS);
-    const fieldLevel = field.wrappers ?? EMPTY_WRAPPERS;
-    if (autoWrappers.length === 0 && defaults.length === 0 && fieldLevel.length === 0) {
-        return EMPTY_WRAPPERS;
-    }
-    return [...autoWrappers, ...defaults, ...fieldLevel];
-}
-
 /**
  * Owns the wrapper-chain lifecycle for a field or container: async component
  * loading, switchMap-based cancellation of stale loads, flicker-tolerant
@@ -719,6 +671,20 @@ function toReadonlyFieldTree(field) {
         errors: state.errors,
     };
 }
+/**
+ * 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).
+ */
+function writeToFieldValue(value, next, logger) {
+    const candidate = value;
+    if (typeof candidate.set !== 'function') {
+        logger?.warn('writeToFieldValue: FieldState.value is not a WritableSignal — Signal Forms contract changed.');
+        return false;
+    }
+    candidate.set(next);
+    return true;
+}
 /**
  * DI-scoped cache for `ReadonlyFieldTree` views, keyed on the source FieldTree
  * identity. A fresh WeakMap per root injector keeps renders isolated under SSR —
@@ -749,6 +715,209 @@ function toReadonlyFieldTreeCached(cache, field) {
     return view;
 }
 
+/**
+ * Convert a field's raw mapper outputs into the {@link WrapperFieldInputs}
+ * bag consumed by wrappers and addons.
+ *
+ * The transformation hides write access on the underlying `FieldTree` —
+ * the bag's `field` slot is a {@link ReadonlyFieldTree} view. The raw
+ * `FieldTree` is still pushed to the innermost field component (which
+ * legitimately needs to write); intermediaries (wrappers, addons) are
+ * read-only by contract.
+ *
+ * Pure, dependency-injection-free — caller supplies the cache so the same
+ * `ReadonlyFieldTree` view is returned for the same source `FieldTree`
+ * across renders. Each `<df-dynamic-form>` instance scopes its own cache
+ * (SSR-safe).
+ *
+ * @param rawInputs Mapper outputs (`{ key, label, props, field?: FieldTree, ... }`).
+ * @param cache     `WeakMap<FieldTree, ReadonlyFieldTree>` provided via
+ *                  {@link READONLY_FIELD_TREE_CACHE}.
+ * @param fieldType Optional field-type discriminant. Injected here (rather
+ *                  than via the field mapper) because `type` is the
+ *                  registry key, not a component input — but addons and
+ *                  wrappers legitimately need it.
+ */
+function buildFieldInputs(rawInputs, cache, fieldType) {
+    const fieldTreeCandidate = rawInputs['field'];
+    // FieldTree is callable: `(): FieldState`. Anything else (undefined,
+    // primitive) means the field is rendered before the form is bound.
+    const hasFieldTree = fieldTreeCandidate !== undefined && typeof fieldTreeCandidate === 'function';
+    const readonlyField = hasFieldTree ? toReadonlyFieldTreeCached(cache, fieldTreeCandidate) : undefined;
+    // Lazy writer keyed on the raw FieldTree. Addons (e.g., `prime-button`
+    // presets) call this to mutate the host field. `writeToFieldValue`
+    // centralises the `Signal → WritableSignal` cast and warns at runtime
+    // if Signal Forms ever changes the contract.
+    const setValue = hasFieldTree
+        ? (next) => writeToFieldValue(fieldTreeCandidate().value, next)
+        : undefined;
+    // Shallow spread — relies on the mapper contract (see WrapperFieldInputs)
+    // that rawInputs are emitted as fresh snapshots, not mutated in place.
+    return {
+        ...rawInputs,
+        type: fieldType,
+        field: readonlyField,
+        setValue,
+    };
+}
+
+const EMPTY_STATE = Object.freeze({ phase: 'empty' });
+/**
+ * Encapsulates the imperative `ViewContainerRef` / `ComponentRef` lifecycle
+ * for the innermost field component. Pulled out of `DfFieldOutlet` so the
+ * directive itself stays declarative — signals + constructor wiring — while
+ * the unavoidable mutable bookkeeping (Angular's view container API is
+ * imperative) lives in one place behind a small, focused surface.
+ *
+ * State is held in a single `signal<FieldSlotState>` discriminated union;
+ * every mutation is an explicit `state.set(...)` transition. No nullable
+ * instance fields, no `undefined`-initialized refs — each phase carries
+ * exactly the data it owns.
+ *
+ * Responsibilities:
+ * - Create the component (or reuse the same-class instance across a rebuild,
+ *   preserving its DOM state, focus, and caret).
+ * - Push mapper inputs via `setInput`, dedup'd per-key so dev-mode NG0303
+ *   warnings for undeclared mapper keys don't replay on every emission.
+ * - Detach cleanly before the outer VCR clears, so same-class reuse can
+ *   re-insert the preserved `hostView`.
+ * - Destroy on directive teardown when the host view is still detached.
+ */
+class FieldComponentSlot {
+    state = signal(EMPTY_STATE, ...(ngDevMode ? [{ debugName: "state" }] : /* istanbul ignore next */ []));
+    /**
+     * Per-key cache for `pushInputs`. Lives outside the lifecycle state machine on
+     * purpose — it's a `setInput`-call optimization that changes on every keystroke,
+     * not a phase transition. Keeping it here means the `state` signal only emits
+     * on real `empty ⇄ mounted ⇄ detached` transitions (≈ once per
+     * mount/destroy cycle), not once per input emission.
+     */
+    lastInputs = null;
+    /** Read-only view of the lifecycle phase. Useful for tests and assertions. */
+    phase = () => this.state().phase;
+    /** Read-only view of the full state. Exposed so tests can assert ref stability. */
+    snapshot = () => this.state();
+    /**
+     * Mount the field component into `slot`. Reuses the existing `ComponentRef`
+     * when its component type matches (preserving DOM/focus/caret across a
+     * wrapper-chain rebuild); otherwise discards the old ref and creates a fresh
+     * one.
+     */
+    mountOrReuse(slot, component, fieldInjector, environmentInjector, rawInputs, fieldInputs) {
+        const current = this.state();
+        if (current.phase !== 'empty' && current.ref.componentType === component) {
+            slot.insert(current.ref.hostView);
+            this.lastInputs = null;
+            this.state.set(Object.freeze({ phase: 'mounted', ref: current.ref, slot }));
+            this.pushInputs(rawInputs, fieldInputs);
+            if (current.phase === 'detached')
+                this.replayFocus(current.focusSnapshot);
+            return;
+        }
+        // Different component class — destroy the prior ref (if any) and create
+        // a fresh one. The `empty` transition before `createComponent` ensures a
+        // throw inside the factory doesn't leave a dangling ref the next mount
+        // would try to re-insert.
+        if (current.phase !== 'empty')
+            current.ref.destroy();
+        this.lastInputs = null;
+        this.state.set(EMPTY_STATE);
+        const ref = slot.createComponent(component, {
+            environmentInjector,
+            injector: createWrapperAwareInjector(fieldInjector, slot.injector),
+        });
+        this.state.set(Object.freeze({ phase: 'mounted', ref, slot }));
+        this.pushInputs(rawInputs, fieldInputs);
+    }
+    /**
+     * Push mapper inputs onto the mounted component. Per-key reference compare
+     * skips `setInput` for unchanged values — necessary in dev mode where
+     * `setInput` on unknown keys logs NG0303 per call (Angular 21 is lenient
+     * at runtime but warns); without the cache, every emission would re-warn
+     * for every undeclared mapper key.
+     *
+     * Updates the `lastInputs` cache (a plain field, not part of `state`) so the
+     * `state` signal doesn't churn its reference on every keystroke.
+     *
+     * `reflectComponentType` does NOT include hostDirective-forwarded inputs
+     * (angular/angular#49734), so a declared-input filter here would skip every
+     * value flowing through `NgForgeFieldShell` / `NgForgeField` /
+     * `NgForgeAction`. Mapper-as-contract is enforced by the `*_INPUTS`
+     * lockstep type assertions, not at runtime here.
+     */
+    pushInputs(rawInputs, fieldInputs) {
+        const current = this.state();
+        if (current.phase !== 'mounted')
+            return;
+        const prev = this.lastInputs;
+        if (prev === rawInputs)
+            return;
+        for (const [key, value] of Object.entries(rawInputs)) {
+            if (prev && prev[key] === value)
+                continue;
+            current.ref.setInput(key, value);
+        }
+        // Side-channel forwarding for the `fieldInputs` bag — gated on
+        // `setInputIfDeclared` so leaf fields that don't declare it (most
+        // non-addon-aware components) skip silently rather than triggering
+        // NG0303 in dev. Pushed unconditionally on every emission since the bag
+        // changes identity when `rawInputs` does.
+        if (fieldInputs !== undefined) {
+            setInputIfDeclared(current.ref, 'fieldInputs', fieldInputs);
+        }
+        this.lastInputs = rawInputs;
+    }
+    /**
+     * Detach the host view from its current slot, capturing focus + caret so the
+     * next `mountOrReuse()` can replay them after re-inserting into the new
+     * slot. A stranded `mounted` state with a bad slot index (re-entrancy during
+     * a partial rebuild) is treated like `empty` to avoid leaks.
+     */
+    detach() {
+        const current = this.state();
+        if (current.phase !== 'mounted')
+            return;
+        const focusSnapshot = this.captureFocus(current.ref);
+        const idx = current.slot.indexOf(current.ref.hostView);
+        if (idx >= 0)
+            current.slot.detach(idx);
+        this.lastInputs = null;
+        this.state.set(Object.freeze({ phase: 'detached', ref: current.ref, focusSnapshot }));
+    }
+    /**
+     * Called on directive teardown. Only destroys when the host view is still
+     * detached — otherwise the outer `vcr.clear()` cascade has already destroyed
+     * it (calling `.destroy()` again would throw).
+     */
+    destroyOnTeardown() {
+        const current = this.state();
+        if (current.phase === 'detached')
+            current.ref.destroy();
+        this.lastInputs = null;
+        this.state.set(EMPTY_STATE);
+    }
+    captureFocus(ref) {
+        const hostEl = ref.location.nativeElement;
+        const active = document.activeElement;
+        if (!(active instanceof HTMLElement) || !hostEl.contains(active))
+            return null;
+        const sel = active;
+        return {
+            element: active,
+            selectionStart: typeof sel.selectionStart === 'number' ? sel.selectionStart : null,
+            selectionEnd: typeof sel.selectionEnd === 'number' ? sel.selectionEnd : null,
+        };
+    }
+    replayFocus(snap) {
+        if (!snap || !snap.element.isConnected)
+            return;
+        snap.element.focus();
+        if (snap.selectionStart !== null && snap.selectionEnd !== null && 'setSelectionRange' in snap.element) {
+            snap.element.setSelectionRange(snap.selectionStart, snap.selectionEnd);
+        }
+    }
+}
+
 /**
  * Structural directive that renders a `ResolvedField` with its effective
  * wrapper chain.
@@ -769,12 +938,16 @@ function toReadonlyFieldTreeCached(cache, field) {
  * includes the field's mapper outputs and a `ReadonlyFieldTree` view of its
  * form state.
  *
- * Rendering is gated by `field.renderReady()` — the directive waits until
- * the mapper produces the required inputs before instantiating the component.
- * Once rendered, a transient `renderReady → false` does *not* tear the chain
- * down; the controller keeps the mounted components alive and ignores the
- * flicker. Only a structural change (wrappers or component class) triggers
- * a rebuild.
+ * Rendering is gated by `field.renderReady() && !field.hidden()` — the
+ * directive waits until the mapper produces the required inputs AND the
+ * field isn't hidden before instantiating the component. Once rendered, a
+ * transient `renderReady → false` does *not* tear the chain down; the
+ * controller keeps the mounted components alive and ignores the flicker.
+ * Only a structural change (wrappers or component class) triggers a rebuild.
+ *
+ * Imperative `ComponentRef` / `ViewContainerRef` lifecycle is encapsulated
+ * in `FieldComponentSlot` — the directive itself is signal definitions
+ * plus three method calls (`mountOrReuse`, `detach`, `destroyOnTeardown`).
  *
  * @example
  * ```html
@@ -794,25 +967,16 @@ class DfFieldOutlet {
     wrapperAutoAssociations = inject(WRAPPER_AUTO_ASSOCIATIONS);
     defaultWrappersSignal = inject(DEFAULT_WRAPPERS, { optional: true });
     readonlyFieldCache = inject(READONLY_FIELD_TREE_CACHE);
-    fieldRef;
-    /**
-     * VCR the `fieldRef`'s host view is currently inserted into (either the outer
-     * VCR when there are no wrappers, or the innermost wrapper's `#fieldComponent`
-     * slot). Tracked so `beforeRebuild` can detach the view before the outer VCR
-     * cascade-destroys it.
-     */
-    fieldSlot;
-    /** Focus + caret captured during detach, replayed after re-insert. */
-    focusSnapshot;
+    /** Encapsulates Angular's imperative ComponentRef / ViewContainerRef lifecycle. */
+    fieldComponent = new FieldComponentSlot();
+    componentIdentity = computed(() => this.dfFieldOutlet().component, ...(ngDevMode ? [{ debugName: "componentIdentity" }] : /* istanbul ignore next */ []));
     /**
-     * Last rawInputs reference pushed to the innermost field. Used to dedupe the
-     * rawInputs effect when the same snapshot was already applied as part of the
-     * initial render — keeps per-keystroke input updates O(changed-keys) instead
-     * of re-walking the whole input bag.
+     * Gate for the wrapper chain controller: true only when required inputs are populated AND the
+     * field isn't hidden. Combining the two prevents an initial-mount race where the chain mounts
+     * during the brief window between `renderReady` flipping true and `hidden()` settling — that
+     * window is exactly where Angular Signal Forms' `[formField]` directive emits NG01916.
      */
-    lastPushedInputs;
-    componentIdentity = computed(() => this.dfFieldOutlet().component, ...(ngDevMode ? [{ debugName: "componentIdentity" }] : /* istanbul ignore next */ []));
-    renderReady = computed(() => this.dfFieldOutlet().renderReady(), ...(ngDevMode ? [{ debugName: "renderReady" }] : /* istanbul ignore next */ []));
+    renderReady = computed(() => this.dfFieldOutlet().renderReady() && !this.dfFieldOutlet().hidden(), ...(ngDevMode ? [{ debugName: "renderReady" }] : /* istanbul ignore next */ []));
     rawInputs = computed(() => this.dfFieldOutlet().inputs(), ...(ngDevMode ? [{ debugName: "rawInputs" }] : /* istanbul ignore next */ []));
     /**
      * Effective wrapper chain. Element-wise identity comparison keeps the signal
@@ -821,11 +985,13 @@ class DfFieldOutlet {
      */
     wrappers = computed(() => resolveWrappers(this.dfFieldOutlet().fieldDef, this.defaultWrappersSignal?.(), this.wrapperAutoAssociations), { ...(ngDevMode ? { debugName: "wrappers" } : /* istanbul ignore next */ {}), equal: isSameWrapperChain });
     /**
-     * `fieldInputs` bag handed to every wrapper in the chain. Memoised on
-     * `rawInputs` identity so repeated emissions with the same underlying object
-     * return the same view and don't cascade OnPush re-evaluations.
+     * `fieldInputs` bag handed to every wrapper in the chain AND forwarded to
+     * the innermost field component (when it declares `fieldInputs` as an
+     * input). Memoised on `rawInputs` identity so repeated emissions with the
+     * same underlying object return the same view and don't cascade OnPush
+     * re-evaluations.
      */
-    fieldInputs = computed(() => this.buildFieldInputs(this.rawInputs()), ...(ngDevMode ? [{ debugName: "fieldInputs" }] : /* istanbul ignore next */ []));
+    fieldInputs = computed(() => buildFieldInputs(this.rawInputs(), this.readonlyFieldCache, this.dfFieldOutlet().fieldDef.type), ...(ngDevMode ? [{ debugName: "fieldInputs" }] : /* istanbul ignore next */ []));
     defaultEnvInjector = inject(EnvironmentInjector);
     /** Environment injector for the innermost field component — `[environmentInjector]` input takes precedence over the directive's own DI. */
     fieldEnvInjector = computed(() => this.dfFieldOutletEnvironmentInjector() ?? this.defaultEnvInjector, ...(ngDevMode ? [{ debugName: "fieldEnvInjector" }] : /* istanbul ignore next */ []));
@@ -839,128 +1005,23 @@ class DfFieldOutlet {
             rebuildKey: this.componentIdentity,
             fieldInputs: this.fieldInputs,
             fieldInjector: this.fieldInjector,
-            beforeRebuild: () => this.detachFieldRef(),
+            beforeRebuild: () => this.fieldComponent.detach(),
             renderInnermost: (slot) => {
                 const resolved = this.dfFieldOutlet();
-                if (this.fieldRef && this.fieldRef.componentType === resolved.component) {
-                    // Same component class — re-insert the preserved hostView. Browser
-                    // loses focus on detach, so we replay the snapshot captured in
-                    // detachFieldRef. Input value persists on the DOM node itself.
-                    slot.insert(this.fieldRef.hostView);
-                    this.fieldSlot = slot;
-                    this.pushRawInputs(this.fieldRef, this.rawInputs());
-                    this.restoreFocusSnapshot();
-                    return;
-                }
-                // Different component class — discard the old ref and create fresh.
-                // Merge field + element injectors so the field can inject ancestor
-                // wrappers AND form-context tokens (ARRAY_CONTEXT etc.).
-                // Clear state before createComponent — if it throws (bad provider,
-                // invalid class) we don't want to leak a reference to a destroyed ref
-                // that the same-component branch would later try to re-insert.
-                this.focusSnapshot = undefined;
-                this.lastPushedInputs = undefined;
-                const previousRef = this.fieldRef;
-                this.fieldRef = undefined;
-                this.fieldSlot = undefined;
-                previousRef?.destroy();
-                this.fieldRef = slot.createComponent(resolved.component, {
-                    environmentInjector: this.fieldEnvInjector(),
-                    injector: createWrapperAwareInjector(resolved.injector, slot.injector),
-                });
-                this.fieldSlot = slot;
-                // setInput dirties the signal synchronously; the next CD pass reads
-                // it. Safe outside CD — see wrapper-chain-controller scheduling.
-                this.pushRawInputs(this.fieldRef, this.rawInputs());
+                this.fieldComponent.mountOrReuse(slot, resolved.component, resolved.injector, this.fieldEnvInjector(), this.rawInputs(), this.fieldInputs());
             },
         });
-        // Push rawInputs to the innermost field. Safe mid-rebuild — renderInnermost
-        // re-reads rawInputs synchronously on mount, so skipping here loses nothing.
-        explicitEffect([this.rawInputs], ([rawInputs]) => {
-            if (!this.fieldRef)
-                return;
-            if (this.lastPushedInputs === rawInputs)
-                return;
-            this.pushRawInputs(this.fieldRef, rawInputs);
-        });
-        this.destroyRef.onDestroy(() => {
-            // Only destroy when detached — vcr.clear() cascades otherwise.
-            if (this.fieldRef && !this.fieldSlot)
-                this.fieldRef.destroy();
-            this.fieldRef = undefined;
-            this.fieldSlot = undefined;
-            this.lastPushedInputs = undefined;
-        });
-    }
-    detachFieldRef() {
-        if (!this.fieldRef)
-            return;
-        if (!this.fieldSlot) {
-            // Stranded fieldRef — destroy to prevent a leak.
-            this.fieldRef.destroy();
-            this.fieldRef = undefined;
-            return;
-        }
-        this.captureFocusSnapshot();
-        const idx = this.fieldSlot.indexOf(this.fieldRef.hostView);
-        if (idx >= 0)
-            this.fieldSlot.detach(idx);
-        this.fieldSlot = undefined;
-    }
-    /** Capture active element + selection before the hostView is detached from DOM. */
-    captureFocusSnapshot() {
-        if (!this.fieldRef)
-            return;
-        const hostEl = this.fieldRef.location.nativeElement;
-        const active = document.activeElement;
-        if (!(active instanceof HTMLElement) || !hostEl.contains(active))
-            return;
-        const sel = active;
-        this.focusSnapshot = {
-            element: active,
-            selectionStart: typeof sel.selectionStart === 'number' ? sel.selectionStart : null,
-            selectionEnd: typeof sel.selectionEnd === 'number' ? sel.selectionEnd : null,
-        };
-    }
-    /** Re-apply the pre-detach focus + caret after the hostView is back in the DOM. */
-    restoreFocusSnapshot() {
-        const snap = this.focusSnapshot;
-        this.focusSnapshot = undefined;
-        if (!snap || !snap.element.isConnected)
-            return;
-        snap.element.focus();
-        if (snap.selectionStart !== null && snap.selectionEnd !== null && 'setSelectionRange' in snap.element) {
-            snap.element.setSelectionRange(snap.selectionStart, snap.selectionEnd);
-        }
-    }
-    pushRawInputs(ref, rawInputs) {
-        // setInput is lenient in Angular 21 — unknown keys silently drop (not NG0303). reflectComponentType does NOT include hostDirective forwarded inputs (angular/angular#49734), so a declared-input filter here would skip every value flowing through NgForgeFieldShell / NgForgeField / NgForgeAction. Mapper-as-contract is enforced by the *_INPUTS lockstep type assertions, not at runtime here.
-        const last = this.lastPushedInputs;
-        for (const [key, value] of Object.entries(rawInputs)) {
-            if (last && last[key] === value)
-                continue;
-            ref.setInput(key, value);
-        }
-        this.lastPushedInputs = rawInputs;
-    }
-    buildFieldInputs(rawInputs) {
-        const fieldTreeCandidate = rawInputs['field'];
-        // A FieldTree is a callable (() => FieldState). We expose it to wrappers via a narrow
-        // read-only view; raw FieldTree is still pushed to the innermost component for writes.
-        const readonlyField = fieldTreeCandidate && typeof fieldTreeCandidate === 'function'
-            ? toReadonlyFieldTreeCached(this.readonlyFieldCache, fieldTreeCandidate)
-            : undefined;
-        // Shallow spread — relies on the mapper contract (see WrapperFieldInputs)
-        // that rawInputs are emitted as fresh snapshots, not mutated in place.
-        return {
-            ...rawInputs,
-            field: readonlyField,
-        };
+        // Push rawInputs (plus the wrapper-style fieldInputs bag) to the innermost
+        // field on every change. The slot dedupes per-key, so the initial render's
+        // synchronous push from `renderInnermost` and the effect's first fire
+        // converge cleanly with no double-pushing.
+        explicitEffect([this.rawInputs, this.fieldInputs], ([rawInputs, fieldInputs]) => this.fieldComponent.pushInputs(rawInputs, fieldInputs));
+        this.destroyRef.onDestroy(() => this.fieldComponent.destroyOnTeardown());
     }
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.8", ngImport: i0, type: DfFieldOutlet, deps: [], target: i0.ɵɵFactoryTarget.Directive });
-    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "21.2.8", type: DfFieldOutlet, isStandalone: true, selector: "[dfFieldOutlet]", inputs: { dfFieldOutlet: { classPropertyName: "dfFieldOutlet", publicName: "dfFieldOutlet", isSignal: true, isRequired: true, transformFunction: null }, dfFieldOutletEnvironmentInjector: { classPropertyName: "dfFieldOutletEnvironmentInjector", publicName: "dfFieldOutletEnvironmentInjector", isSignal: true, isRequired: false, transformFunction: null } }, ngImport: i0 });
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: DfFieldOutlet, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "21.2.14", type: DfFieldOutlet, isStandalone: true, selector: "[dfFieldOutlet]", inputs: { dfFieldOutlet: { classPropertyName: "dfFieldOutlet", publicName: "dfFieldOutlet", isSignal: true, isRequired: true, transformFunction: null }, dfFieldOutletEnvironmentInjector: { classPropertyName: "dfFieldOutletEnvironmentInjector", publicName: "dfFieldOutletEnvironmentInjector", isSignal: true, isRequired: false, transformFunction: null } }, ngImport: i0 });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.8", ngImport: i0, type: DfFieldOutlet, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: DfFieldOutlet, decorators: [{
             type: Directive,
             args: [{
                     selector: '[dfFieldOutlet]',
@@ -1260,10 +1321,10 @@ class EventBus {
         }
         return this.pipeline$.pipe(filter((event) => event.type === eventType));
     }
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.8", ngImport: i0, type: EventBus, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
-    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.8", ngImport: i0, type: EventBus });
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: EventBus, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: EventBus });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.8", ngImport: i0, type: EventBus, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: EventBus, decorators: [{
             type: Injectable
         }] });
 
@@ -3337,10 +3398,10 @@ class FunctionRegistryService {
         this.clearAsyncValidators();
         this.clearHttpValidators();
     }
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.8", ngImport: i0, type: FunctionRegistryService, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
-    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.8", ngImport: i0, type: FunctionRegistryService });
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: FunctionRegistryService, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: FunctionRegistryService });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.8", ngImport: i0, type: FunctionRegistryService, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: FunctionRegistryService, decorators: [{
             type: Injectable
         }] });
 
@@ -3791,10 +3852,10 @@ class FieldContextRegistryService {
             },
         };
     }
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.8", ngImport: i0, type: FieldContextRegistryService, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
-    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.8", ngImport: i0, type: FieldContextRegistryService });
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: FieldContextRegistryService, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: FieldContextRegistryService });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.8", ngImport: i0, type: FieldContextRegistryService, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: FieldContextRegistryService, decorators: [{
             type: Injectable
         }] });
 
@@ -4149,8 +4210,8 @@ class PageOrchestratorComponent {
         }
         return false;
     }
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.8", ngImport: i0, type: PageOrchestratorComponent, deps: [], target: i0.ɵɵFactoryTarget.Component });
-    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "21.2.8", type: PageOrchestratorComponent, isStandalone: true, selector: "div[page-orchestrator]", inputs: { pageFields: { classPropertyName: "pageFields", publicName: "pageFields", isSignal: true, isRequired: true, transformFunction: null }, form: { classPropertyName: "form", publicName: "form", isSignal: true, isRequired: true, transformFunction: null }, fieldSignalContext: { classPropertyName: "fieldSignalContext", publicName: "fieldSignalContext", isSignal: true, isRequired: true, transformFunction: null } }, host: { properties: { "attr.data-current-page": "state().currentPageIndex", "attr.data-total-pages": "state().totalPages" }, classAttribute: "df-page-orchestrator" }, providers: [
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: PageOrchestratorComponent, deps: [], target: i0.ɵɵFactoryTarget.Component });
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "21.2.14", type: PageOrchestratorComponent, isStandalone: true, selector: "div[page-orchestrator]", inputs: { pageFields: { classPropertyName: "pageFields", publicName: "pageFields", isSignal: true, isRequired: true, transformFunction: null }, form: { classPropertyName: "form", publicName: "form", isSignal: true, isRequired: true, transformFunction: null }, fieldSignalContext: { classPropertyName: "fieldSignalContext", publicName: "fieldSignalContext", isSignal: true, isRequired: true, transformFunction: null } }, host: { properties: { "attr.data-current-page": "state().currentPageIndex", "attr.data-total-pages": "state().totalPages" }, classAttribute: "df-page-orchestrator" }, providers: [
             {
                 provide: FIELD_SIGNAL_CONTEXT,
                 useFactory: (orchestrator) => orchestrator.extendedFieldSignalContext(),
@@ -4180,9 +4241,9 @@ class PageOrchestratorComponent {
         }
       }
     }
-  `, isInline: true, styles: [":host{display:block;position:relative;width:100%}\n"], changeDetection: i0.ChangeDetectionStrategy.OnPush, deferBlockDependencies: [() => [import('./ng-forge-dynamic-forms-page-field.component-BX4R9GGa.mjs').then(m => m.default)], () => [import('./ng-forge-dynamic-forms-page-field.component-BX4R9GGa.mjs').then(m => m.default)]] });
+  `, isInline: true, styles: [":host{display:block;position:relative;width:100%}\n"], changeDetection: i0.ChangeDetectionStrategy.OnPush, deferBlockDependencies: [() => [import('./ng-forge-dynamic-forms-page-field.component-BwNIx3R1.mjs').then(m => m.default)], () => [import('./ng-forge-dynamic-forms-page-field.component-BwNIx3R1.mjs').then(m => m.default)]] });
 }
-i0.ɵɵngDeclareClassMetadataAsync({ minVersion: "18.0.0", version: "21.2.8", ngImport: i0, type: PageOrchestratorComponent, resolveDeferredDeps: () => [import('./ng-forge-dynamic-forms-page-field.component-BX4R9GGa.mjs').then(m => m.default)], resolveMetadata: PageFieldComponent => ({ decorators: [{
+i0.ɵɵngDeclareClassMetadataAsync({ minVersion: "18.0.0", version: "21.2.14", ngImport: i0, type: PageOrchestratorComponent, resolveDeferredDeps: () => [import('./ng-forge-dynamic-forms-page-field.component-BwNIx3R1.mjs').then(m => m.default)], resolveMetadata: PageFieldComponent => ({ decorators: [{
                 type: Component,
                 args: [{ selector: 'div[page-orchestrator]', imports: [PageFieldComponent], template: `
     @for (pageField of pageFields(); track pageField.key; let i = $index) {
@@ -4614,6 +4675,85 @@ function isValidNonPagedForm(fields) {
     return result.mode === 'non-paged' && result.isValid;
 }
 
+function createSlot() {
+    let counter = 0;
+    const templates = new Map();
+    const itemOrder = [];
+    const primitiveFieldKey = signal(undefined, ...(ngDevMode ? [{ debugName: "primitiveFieldKey" }] : /* istanbul ignore next */ []));
+    return {
+        templates,
+        itemOrder,
+        primitiveFieldKey,
+        nextId: () => `item-${counter++}`,
+        setTemplate(itemId, t) {
+            templates.set(itemId, t);
+        },
+        getTemplate(itemId) {
+            return templates.get(itemId);
+        },
+        hasTemplate(itemId) {
+            return templates.has(itemId);
+        },
+        setIdAt(index, itemId) {
+            itemOrder[index] = itemId;
+        },
+        removeAt(index) {
+            const [removed] = itemOrder.splice(index, 1);
+            if (removed !== undefined)
+                templates.delete(removed);
+        },
+        moveItem(fromIndex, toIndex) {
+            const [id] = itemOrder.splice(fromIndex, 1);
+            if (id !== undefined)
+                itemOrder.splice(toIndex, 0, id);
+        },
+        truncate(length) {
+            const removed = itemOrder.splice(length);
+            for (const id of removed)
+                templates.delete(id);
+        },
+        clear() {
+            templates.clear();
+            itemOrder.length = 0;
+            counter = 0;
+            primitiveFieldKey.set(undefined);
+        },
+    };
+}
+/**
+ * Form-scoped registry of per-array durable state. One slot per array path
+ * (e.g. 'members', 'team.members', 'orders.lineItems'). Survives
+ * `ArrayFieldComponent` lifecycle, dies with the `DynamicForm`. Cleared on
+ * schema swap by the `formSetup` effect in `FormStateManager`.
+ *
+ * `ArrayFieldComponent` injects this service and obtains its slot via
+ * `slotFor(arrayPath)` on mount. Replaces the prior per-component
+ * `ARRAY_TEMPLATE_REGISTRY` + `ARRAY_ITEM_ID_GENERATOR` providers.
+ */
+class ArrayItemRegistryService {
+    slots = new Map();
+    /** Get-or-create a slot for the array at the given path. */
+    slotFor(arrayPath) {
+        let slot = this.slots.get(arrayPath);
+        if (!slot) {
+            slot = createSlot();
+            this.slots.set(arrayPath, slot);
+        }
+        return slot;
+    }
+    /** Drop all slots — called from the `formSetup` effect on schema change. */
+    clearAll() {
+        for (const slot of this.slots.values())
+            slot.clear();
+        this.slots.clear();
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: ArrayItemRegistryService, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: ArrayItemRegistryService });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: ArrayItemRegistryService, decorators: [{
+            type: Injectable
+        }] });
+
 class SchemaRegistryService {
     registeredSchemas = new Map();
     /**
@@ -4649,10 +4789,10 @@ class SchemaRegistryService {
         }
         return schema;
     }
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.8", ngImport: i0, type: SchemaRegistryService, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
-    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.8", ngImport: i0, type: SchemaRegistryService });
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: SchemaRegistryService, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: SchemaRegistryService });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.8", ngImport: i0, type: SchemaRegistryService, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: SchemaRegistryService, decorators: [{
             type: Injectable
         }] });
 
@@ -4860,8 +5000,6 @@ class HttpConditionFunctionCacheService {
  * );
  * // user.value() keeps the old user data during loading transitions
  * ```
- *
- * @experimental Uses Angular's experimental resource composition APIs.
  */
 function withPreviousValue(input) {
     const derived = linkedSignal({ ...(ngDevMode ? { debugName: "derived" } : /* istanbul ignore next */ {}), source: input.snapshot,
@@ -8324,9 +8462,13 @@ function buildClassName(fieldDef) {
  * @returns Record of input names to values
  */
 function buildBaseInputs(fieldDef, defaultProps) {
-    const { key, label, className, tabIndex, props, meta } = fieldDef;
+    const { key, label, className, tabIndex, props, meta, addons } = fieldDef;
     const inputs = {};
-    // Always include key - required by components for accessibility and identification
+    // Always include key — required by components for accessibility and identification.
+    // `type` is intentionally NOT propagated to the field component (it's the
+    // registry discriminant, not a component input); wrappers and addons read it
+    // from `WrapperFieldInputs.type` which is injected at the buildFieldInputs()
+    // boundary by `DfFieldOutlet`.
     inputs['key'] = key;
     if (label !== undefined) {
         inputs['label'] = label;
@@ -8356,6 +8498,13 @@ function buildBaseInputs(fieldDef, defaultProps) {
     if (meta !== undefined) {
         inputs['meta'] = meta;
     }
+    // Forward addons. Field components that don't declare an `addons` input
+    // signal (Tier 3 — toggle, checkbox, radio, slider) ignore this key via
+    // Angular's `setInput` no-op-on-unknown behaviour, so it's safe to forward
+    // unconditionally.
+    if (addons !== undefined) {
+        inputs['addons'] = addons;
+    }
     return inputs;
 }
 /**
@@ -8795,18 +8944,52 @@ function createRenderReadySignal(inputs, definition) {
     });
 }
 /**
- * Resolves a single field definition to a ResolvedField using RxJS.
- * Loads the component asynchronously and maps inputs in the injection context.
+ * Reads the current hidden state from mapper inputs. Uniform across all field
+ * types — value-bearing leaves source from the `FieldTree`'s `state.hidden()`
+ * (where Angular Signal Forms cascades `hidden(path, …)`), and non-field outputs
+ * (button/text/containers) source from the mapper's explicit `inputs.hidden`.
  *
- * For componentless fields (e.g., hidden fields), returns undefined since
- * there's nothing to render. These fields still contribute to form values
- * through the form schema.
+ * The `@if (!field.hidden())` gate at every `*dfFieldOutlet` consumption site uses
+ * this signal, removing hidden fields from the DOM. That's required to silence
+ * Angular's `NG01916: Field 'X' is hidden but is being rendered` warning — and
+ * is the prescribed pattern from the
+ * [`hidden` API docs](https://angular.dev/api/forms/signals/hidden).
  *
- * @param fieldDef - The field definition to resolve
- * @param context - The context containing dependencies for resolution
- * @returns Observable that emits ResolvedField or undefined (for componentless fields or on error)
+ * Container internal state (e.g. an `ArrayFieldComponent`'s items + dynamic
+ * templates + id counter) survives this destroy/recreate via the form-scoped
+ * `ArrayItemRegistryService` keyed by array path.
  */
-function resolveField(fieldDef, context) {
+function createHiddenSignal(inputs) {
+    return computed(() => {
+        const currentInputs = inputs();
+        const fieldCandidate = currentInputs['field'];
+        // Value-bearing leaves expose `field` as a callable `FieldTree` whose invocation returns a
+        // `FieldState` with a `hidden` accessor. `isSignal()` doesn't recognise the Proxy-wrapped
+        // FieldTree (no SIGNAL symbol), so we duck-type the shape and call `state.hidden()` directly.
+        if (typeof fieldCandidate === 'function') {
+            const state = fieldCandidate();
+            if (state && typeof state.hidden === 'function') {
+                return state.hidden() === true;
+            }
+        }
+        // Non-value fields (button, text, containers) carry an explicit `hidden` input set by
+        // `applyHiddenLogic` based on the mapper-side evaluation.
+        return currentInputs['hidden'] === true;
+    });
+}
+/**
+ * Resolves a single field definition to a ResolvedField using RxJS.
+ * Loads the component asynchronously and maps inputs in the injection context.
+ *
+ * For componentless fields (e.g., hidden fields), returns undefined since
+ * there's nothing to render. These fields still contribute to form values
+ * through the form schema.
+ *
+ * @param fieldDef - The field definition to resolve
+ * @param context - The context containing dependencies for resolution
+ * @returns Observable that emits ResolvedField or undefined (for componentless fields or on error)
+ */
+function resolveField(fieldDef, context) {
     return from(context.loadTypeComponent(fieldDef.type)).pipe(map((component) => {
         // Check if component is destroyed before proceeding
         if (context.destroyRef.destroyed) {
@@ -8830,6 +9013,7 @@ function resolveField(fieldDef, context) {
             injector: context.injector,
             inputs,
             renderReady: createRenderReadySignal(inputs, definition),
+            hidden: createHiddenSignal(inputs),
         };
     }), catchError((error) => {
         // Only call onError if component is not destroyed to avoid accessing cleaned-up state
@@ -8866,6 +9050,7 @@ function resolveFieldSync(fieldDef, context) {
         injector: context.injector,
         inputs,
         renderReady: createRenderReadySignal(inputs, definition),
+        hidden: createHiddenSignal(inputs),
     };
 }
 /**
@@ -8892,13 +9077,14 @@ function reconcileFields(prev, curr) {
             }
             // Same component instance + injector, but the field definition changed.
             // Preserve component identity (so ngComponentOutlet keeps the same instance)
-            // while swapping in the freshly-mapped inputs/renderReady signals so prop
-            // updates (e.g. select options) reach the component.
+            // while swapping in the freshly-mapped inputs/renderReady/hidden signals
+            // so prop updates (e.g. select options) reach the component.
             return {
                 ...existing,
                 fieldDef: field.fieldDef,
                 inputs: field.inputs,
                 renderReady: field.renderReady,
+                hidden: field.hidden,
             };
         }
         // New field, type changed, or context changed (new injector) - use new field
@@ -9390,6 +9576,272 @@ function validateFormConfig(fields, registry, logger) {
     }
 }
 
+/**
+ * Walk a field's addons; return the survivors plus a list of warnings for
+ * anything dropped.
+ *
+ * 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.
+ */
+function validateFieldAddons(field, fieldRegistry, kindRegistry, source) {
+    const warnings = [];
+    const incoming = field.addons;
+    if (!incoming?.length) {
+        return { addons: [], warnings };
+    }
+    const fieldType = field.type;
+    const fieldDef = fieldRegistry.get(fieldType);
+    if (!fieldDef) {
+        warnings.push({ type: 'unknown-field-type', fieldKey: field.key, fieldType });
+        return { addons: [], warnings };
+    }
+    const addonSupport = fieldDef.addons;
+    if (!addonSupport) {
+        warnings.push({ type: 'field-type-no-addon-support', fieldKey: field.key, fieldType });
+        return { addons: [], warnings };
+    }
+    const allowedSlots = addonSupport.slots;
+    const allowedKinds = addonSupport.allowedKinds;
+    const registeredKinds = Array.from(kindRegistry.keys());
+    const survivors = [];
+    for (const addon of incoming) {
+        // Slot allowed?
+        if (!allowedSlots.includes(addon.slot)) {
+            warnings.push({
+                type: 'unknown-slot',
+                fieldKey: field.key,
+                fieldType,
+                slot: String(addon.slot),
+                allowedSlots,
+            });
+            continue;
+        }
+        // Kind registered? `AnyAddon.kind` is already a string-literal union via
+        // DynamicFormAddonRegistry; no need to cast.
+        const kindDef = kindRegistry.get(addon.kind);
+        if (!kindDef) {
+            warnings.push({
+                type: 'unknown-kind',
+                fieldKey: field.key,
+                kind: addon.kind,
+                registeredKinds,
+            });
+            continue;
+        }
+        // Kind whitelisted (if `allowedKinds` was set)?
+        if (allowedKinds && !allowedKinds.includes(kindDef.kind)) {
+            warnings.push({
+                type: 'kind-not-allowed',
+                fieldKey: field.key,
+                fieldType,
+                kind: kindDef.kind,
+                allowedKinds,
+            });
+            continue;
+        }
+        // Code-only kind dropped from JSON-source configs. A kind opts out of
+        // JSON-safety via `AddonKindDefinition.jsonSafe: false` (defaults to true).
+        if (source === 'json' && kindDef.jsonSafe === false) {
+            warnings.push({
+                type: 'code-only-kind-in-json',
+                fieldKey: field.key,
+                kind: kindDef.kind,
+            });
+            continue;
+        }
+        // Multi-set XOR + JSON-source function stripping. Both runs operate on
+        // a working copy via `ensureCopy()` so the original config isn't
+        // mutated — the survivor pushed at the bottom is either the original
+        // addon (no strips) or the sanitized copy.
+        let sanitized = addon;
+        let stripped = false;
+        const ensureCopy = () => {
+            if (!stripped)
+                sanitized = { ...sanitized };
+            stripped = true;
+        };
+        // Snapshot which click variants the original config declared BEFORE
+        // any stripping. Computing variants AFTER function-strip would
+        // underreport the multi-variant warning (`action` would silently
+        // vanish from the reported list).
+        const declaredVariants = ['preset', 'actionRef', 'action'].filter((k) => sanitized[k] !== undefined);
+        // JSON-source function strip — inline `action`/`hidden`/`disabled`/
+        // `loading` functions can't round-trip through serialization, so they
+        // get dropped here with a warning. Inline-source configs keep them.
+        if (source === 'json') {
+            const dropReactiveFn = (key) => {
+                if (typeof sanitized[key] === 'function') {
+                    ensureCopy();
+                    delete sanitized[key];
+                    warnings.push({
+                        type: 'code-only-action-in-json',
+                        fieldKey: field.key,
+                        reason: `function '${key}' on kind '${kindDef.kind}' (use a signal/observable in code, or omit in JSON)`,
+                    });
+                }
+            };
+            if (typeof sanitized.action === 'function') {
+                ensureCopy();
+                delete sanitized.action;
+                warnings.push({
+                    type: 'code-only-action-in-json',
+                    fieldKey: field.key,
+                    reason: `inline 'action' function on kind '${kindDef.kind}'`,
+                });
+            }
+            dropReactiveFn('hidden');
+            dropReactiveFn('disabled');
+            dropReactiveFn('loading');
+        }
+        // Multi-set XOR — applies to BOTH inline and JSON sources. TypeScript
+        // discriminated unions already reject multi-set at compile time, but
+        // configs that bypass type-checking (loose `any`, runtime composition,
+        // JSON parsing) still need defence-in-depth. Keep the first variant,
+        // strip the rest; mirrors the runtime precedence
+        // (preset > actionRef > action) so the chosen handler matches what
+        // the dispatcher would have picked.
+        if (declaredVariants.length > 1) {
+            ensureCopy();
+            for (const k of declaredVariants.slice(1))
+                delete sanitized[k];
+            warnings.push({
+                type: 'code-only-action-in-json',
+                fieldKey: field.key,
+                reason: `multiple click variants on kind '${kindDef.kind}' (${declaredVariants.join(', ')}); kept '${declaredVariants[0]}'`,
+            });
+        }
+        if (stripped) {
+            survivors.push(sanitized);
+            continue;
+        }
+        // Per-kind shape validator (throws on violation).
+        if (kindDef.validate) {
+            try {
+                kindDef.validate(addon, field.key);
+            }
+            catch (error) {
+                warnings.push({
+                    type: 'shape-violation',
+                    fieldKey: field.key,
+                    kind: kindDef.kind,
+                    reason: error instanceof Error ? error.message : String(error),
+                });
+                continue;
+            }
+        }
+        survivors.push(addon);
+    }
+    return { addons: survivors, warnings };
+}
+/**
+ * Recursively walk a field tree, validating each field's addons. Returns a
+ * sanitized copy of the input field array plus accumulated warnings.
+ */
+function walkAndValidateAddons(fields, fieldRegistry, kindRegistry, source) {
+    const allWarnings = [];
+    const sanitized = fields.map((field) => {
+        let next = field;
+        if (field.addons?.length) {
+            const { addons, warnings } = validateFieldAddons(field, fieldRegistry, kindRegistry, source);
+            allWarnings.push(...warnings);
+            next = { ...next, addons };
+        }
+        // Recurse into containers — every container field type carries its
+        // children on a `fields` array.
+        const children = next.fields;
+        if (Array.isArray(children)) {
+            const { fields: visited, warnings } = walkAndValidateAddons(children, fieldRegistry, kindRegistry, source);
+            allWarnings.push(...warnings);
+            next = { ...next, fields: visited };
+        }
+        return next;
+    });
+    return { fields: sanitized, warnings: allWarnings };
+}
+
+/**
+ * Stable structural fingerprint for an `AddonWarning`, used by the
+ * FormStateManager dedup cache. Includes every distinguishing field
+ * (`type`, `fieldKey`, `kind`/`slot`/`reason` as relevant) so warnings
+ * for different fields or different kinds never collapse to one log
+ * line — independent of the human-readable format which may change.
+ */
+function addonWarningKey(w) {
+    switch (w.type) {
+        case 'unknown-field-type':
+            return `${w.type}|${w.fieldKey}|${w.fieldType}`;
+        case 'field-type-no-addon-support':
+            return `${w.type}|${w.fieldKey}|${w.fieldType}`;
+        case 'unknown-slot':
+            return `${w.type}|${w.fieldKey}|${w.fieldType}|${w.slot}`;
+        case 'unknown-kind':
+            return `${w.type}|${w.fieldKey}|${w.kind}`;
+        case 'kind-not-allowed':
+            return `${w.type}|${w.fieldKey}|${w.fieldType}|${w.kind}`;
+        case 'shape-violation':
+            return `${w.type}|${w.fieldKey}|${w.kind}|${w.reason}`;
+        case 'code-only-kind-in-json':
+            return `${w.type}|${w.fieldKey}|${w.kind}`;
+        case 'code-only-action-in-json':
+            return `${w.type}|${w.fieldKey}|${w.reason}`;
+    }
+}
+/**
+ * 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.
+ */
+function formatAddonWarning(w) {
+    switch (w.type) {
+        case 'unknown-field-type':
+            return `Field '${w.fieldKey}': unknown field type '${w.fieldType}'. Addons dropped.`;
+        case 'field-type-no-addon-support':
+            return (`Field '${w.fieldKey}' (type: '${w.fieldType}'): this field type does not declare addon support. Addons dropped. ` +
+                `If this is incorrect, add 'addons: { slots: [...] }' to the field type registration.`);
+        case 'unknown-slot':
+            return (`Field '${w.fieldKey}' (type: '${w.fieldType}'): slot '${w.slot}' is not supported. ` +
+                `Allowed: ${w.allowedSlots.join(', ')}. Addon dropped.`);
+        case 'unknown-kind':
+            return (`Field '${w.fieldKey}': addon kind '${w.kind}' is not registered. ` +
+                `Did you forget withCustomAddon({ kind: '${w.kind}', ... })? ` +
+                `Currently registered: ${w.registeredKinds.join(', ') || '(none)'}. Addon dropped.`);
+        case 'kind-not-allowed':
+            return (`Field '${w.fieldKey}' (type: '${w.fieldType}'): addon kind '${w.kind}' is not in the allowed list. ` +
+                `Allowed: ${w.allowedKinds.join(', ')}. Addon dropped.`);
+        case 'shape-violation':
+            return `Field '${w.fieldKey}': addon kind '${w.kind}' shape invalid: ${w.reason}. Addon dropped.`;
+        case 'code-only-kind-in-json':
+            return `Field '${w.fieldKey}': addon kind '${w.kind}' is code-only and cannot be used with JSON-derived configs. Addon dropped.`;
+        case 'code-only-action-in-json':
+            return `Field '${w.fieldKey}': ${w.reason}. Use 'preset' or 'actionRef' instead. Addon dropped.`;
+    }
+}
+
+/**
+ * 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.
+ */
+const ADDON_KIND_REGISTRY = new InjectionToken('ADDON_KIND_REGISTRY', {
+    providedIn: 'root',
+    factory: () => new Map(),
+});
+
 /**
  * Injection token for global value exclusion defaults.
  *
@@ -10083,6 +10535,12 @@ class FormStateManager {
     eventBus = inject(EventBus);
     functionRegistry = inject(FunctionRegistryService);
     schemaRegistry = inject(SchemaRegistryService);
+    // Optional so unit-test setups that drive FormStateManager directly without provideDynamicFormDI()
+    // (e.g. mocked RootFormRegistryService specs) don't have to manually wire the registry. Real
+    // DynamicForm usage always provides it via coreProviders; if you hit the dev warning below in
+    // your own setup, you're using DynamicForm without provideDynamicFormDI() — fix the providers
+    // chain rather than ignoring it.
+    arrayItemRegistry = inject(ArrayItemRegistryService, { optional: true });
     /** Host component dependencies (config, formOptions, value). */
     deps = (() => {
         const raw = inject(FORM_STATE_DEPS);
@@ -10091,12 +10549,28 @@ class FormStateManager {
                 'Ensure DynamicForm assigns its input signals to FORM_STATE_DEPS.');
         }
         // Safe cast: DynamicForm populates FormStateDeps with its concrete signals.
+        // `source` is optional — `DynamicForm` always populates it, but other
+        // callers of `FormStateManager` (e.g., specs) may omit it.
         return raw;
     })();
     /** Global value exclusion defaults. */
     valueExclusionDefaults = inject(VALUE_EXCLUSION_DEFAULTS);
     /** Field registry for loading components. */
     fieldRegistry = injectFieldRegistry();
+    /** Addon-kind registry — feeds the addon validator at config-setup time. */
+    addonKindRegistry = inject(ADDON_KIND_REGISTRY);
+    /**
+     * Fingerprints of addon warnings emitted by the last config setup.
+     * Used to skip re-logging warnings that already fired for the previous
+     * config — avoids spam when the form swaps config repeatedly but the
+     * addon issues haven't changed.
+     *
+     * Scoping: per-FormStateManager (i.e., per `<df-dynamic-form>` component
+     * instance). Replaced wholesale on every config setup — bounded by the
+     * current config's warning count, never grows unbounded across swaps.
+     * A warning that disappears and later returns re-logs as expected.
+     */
+    lastAddonWarningKeys = new Set();
     // ─────────────────────────────────────────────────────────────────────────────
     // State Machine
     // ─────────────────────────────────────────────────────────────────────────────
@@ -10709,12 +11183,24 @@ class FormStateManager {
             }
         });
         // Schema change resets the saved store + transition tracker so values from a stale schema
-        // can't leak into the new one.
+        // can't leak into the new one. Also drops every per-array slot in the registry so a fresh
+        // schema starts with an empty template/itemOrder/id-counter state.
+        let warnedAboutMissingArrayRegistry = false;
         explicitEffect([this.formSetup], () => {
             this.prevFieldStateSnapshot.set({});
             if (Object.keys(this.excludedValueStore()).length > 0) {
                 this.excludedValueStore.set({});
             }
+            if (this.arrayItemRegistry) {
+                this.arrayItemRegistry.clearAll();
+            }
+            else if (DEV_MODE && !warnedAboutMissingArrayRegistry) {
+                warnedAboutMissingArrayRegistry = true;
+                this.logger.warn('ArrayItemRegistryService was not provided to FormStateManager. ' +
+                    'Array fields will lose dynamically-added item templates across hide/show cycles. ' +
+                    'This usually means DynamicForm was bootstrapped without provideDynamicFormDI() — ' +
+                    'check your providers chain.');
+            }
         });
         // Outward sync uses boundFormValue (honors only explicit excludeValueIf* opt-ins) so
         // global defaults that target submission output don't reshape the host's bound model.
@@ -10772,11 +11258,35 @@ class FormStateManager {
     }
     createFormSetupFromConfig(fields, mode, registry) {
         const normalizedFields = normalizeSimplifiedArrays(fields);
-        // Validate after normalization so simplified array templates are already expanded
-        // into full ArrayField.fields and are reachable during traversal.
+        // Two validation passes run after normalization so simplified array templates
+        // are already expanded into full ArrayField.fields and reachable during traversal:
+        // 1. Structural — duplicate keys, unknown field types, invalid regex patterns.
+        // 2. Addon pass below — strips invalid/unsupported addons with lenient warnings.
         validateFormConfig(normalizedFields, registry, this.logger);
-        const flattenedFields = this.fieldProcessors.memoizedFlattenFields(normalizedFields, registry);
-        const flattenedFieldsForRendering = this.fieldProcessors.memoizedFlattenFieldsForRendering(normalizedFields, registry);
+        // Addon pass — strip invalid / unsupported addon entries and log a warning
+        // for each one dropped. Lenient by design: the form keeps rendering even
+        // when a JSON-source config ships an addon the FE doesn't understand.
+        //
+        // Warnings are deduped across consecutive config setups: a warning that
+        // already fired for the previous config is skipped, so swapping config
+        // back and forth doesn't spam the console.
+        const source = this.deps.source?.() ?? 'inline';
+        const { fields: sanitizedFields, warnings: addonWarnings } = walkAndValidateAddons(normalizedFields, registry, this.addonKindRegistry, source);
+        const nextKeys = new Set();
+        for (const w of addonWarnings) {
+            // Dedup uses a structural fingerprint so different fields with the
+            // same warning category never collide; the rendered message is what
+            // we log.
+            const key = addonWarningKey(w);
+            nextKeys.add(key);
+            if (!this.lastAddonWarningKeys.has(key)) {
+                this.logger.warn(formatAddonWarning(w));
+            }
+        }
+        this.lastAddonWarningKeys = nextKeys;
+        const validatedFields = sanitizedFields;
+        const flattenedFields = this.fieldProcessors.memoizedFlattenFields(validatedFields, registry);
+        const flattenedFieldsForRendering = this.fieldProcessors.memoizedFlattenFieldsForRendering(validatedFields, registry);
         const fieldsById = this.fieldProcessors.memoizedKeyBy(flattenedFields);
         const defaultValues = this.fieldProcessors.memoizedDefaultValues(fieldsById, registry);
         const fieldsToRender = mode === 'paged' ? [] : flattenedFieldsForRendering;
@@ -10804,10 +11314,10 @@ class FormStateManager {
     ngOnDestroy() {
         this.machine.dispatch({ type: Action.Destroy });
     }
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.8", ngImport: i0, type: FormStateManager, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
-    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.8", ngImport: i0, type: FormStateManager });
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: FormStateManager, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: FormStateManager });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.8", ngImport: i0, type: FormStateManager, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: FormStateManager, decorators: [{
             type: Injectable
         }], ctorParameters: () => [] });
 
@@ -13891,7 +14401,11 @@ function isDynamicFormFeature(value) {
         Array.isArray(value.ɵproviders));
 }
 /**
- * Helper to create a feature with proper typing
+ * Helper to create a feature with proper typing.
+ *
+ * `kind` is the discriminant compared by string equality at the
+ * provider-resolution site (and in feature-specific type guards). Each
+ * feature module owns its own kind literal — no central registry.
  */
 function createFeature(kind, providers) {
     return {
@@ -14429,6 +14943,30 @@ function warnAboutWildcardDependencies(logger, entries, fieldCount) {
     }
 }
 
+/**
+ * Multi-provider token populated by `provideAddonActions({...})` calls.
+ * `ADDON_ACTION_REGISTRY` aggregates these into a single name → handler map.
+ *
+ * @internal
+ */
+const ADDON_ACTION_HANDLERS = new InjectionToken('ADDON_ACTION_HANDLERS');
+/**
+ * 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`.
+ */
+const ADDON_ACTION_REGISTRY = new InjectionToken('ADDON_ACTION_REGISTRY');
+function createAddonActionRegistry() {
+    const sources = inject(ADDON_ACTION_HANDLERS, { optional: true }) ?? [];
+    const map = new Map();
+    for (const handlers of sources) {
+        for (const [name, fn] of Object.entries(handlers)) {
+            map.set(name, fn);
+        }
+    }
+    return map;
+}
+
 /**
  * Always-on providers for any DynamicForm: state machine, registries, signal-context tokens.
  * Pure form bootstrap — no derivation, HTTP, or async machinery.
@@ -14443,7 +14981,7 @@ function coreProviders() {
         FunctionRegistryService,
         {
             provide: FORM_STATE_DEPS,
-            useFactory: () => ({ config: null, formOptions: null, value: null }),
+            useFactory: () => ({ config: null, formOptions: null, value: null, source: null }),
         },
         FormStateManager,
         {
@@ -14452,6 +14990,7 @@ function coreProviders() {
             deps: [FormStateManager],
         },
         FieldContextRegistryService,
+        ArrayItemRegistryService,
         {
             provide: DEFAULT_PROPS,
             useFactory: (stateManager) => computed(() => stateManager.activeConfig()?.defaultProps),
@@ -14478,6 +15017,11 @@ function coreProviders() {
             deps: [FormStateManager],
         },
         { provide: DEPRECATION_WARNING_TRACKER, useFactory: createWarningTracker },
+        // ADDON_ACTION_REGISTRY must live at form scope (not root) because the
+        // multi-provider source `ADDON_ACTION_HANDLERS` is contributed by
+        // `provideAddonActions(...)` features passed to `provideDynamicForm(...)`
+        // — those entries are only visible inside the form's own injector tree.
+        { provide: ADDON_ACTION_REGISTRY, useFactory: createAddonActionRegistry },
     ];
 }
 /**
@@ -14669,13 +15213,90 @@ class EventDispatcher {
     disconnect() {
         this.bus = undefined;
     }
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.8", ngImport: i0, type: EventDispatcher, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
-    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.8", ngImport: i0, type: EventDispatcher });
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: EventDispatcher, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: EventDispatcher });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: EventDispatcher, decorators: [{
+            type: Injectable
+        }] });
+
+/**
+ * Marks an `<ng-template>` projected into `<df-dynamic-form>` content as
+ * available to template addons by name.
+ *
+ * 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.
+ *
+ * @example
+ * ```html
+ * <df-dynamic-form [config]="config">
+ *   <ng-template dfTemplate="searchIcon" let-field>
+ *     <my-icon [field]="field" />
+ *   </ng-template>
+ * </df-dynamic-form>
+ * ```
+ *
+ * In the field config:
+ * ```ts
+ * { slot: 'prefix', kind: 'template', templateKey: 'searchIcon' }
+ * ```
+ */
+class DfTemplate {
+    /** Name this template registers under — referenced from `TemplateAddon.templateKey`. */
+    dfTemplate = input.required(...(ngDevMode ? [{ debugName: "dfTemplate" }] : /* istanbul ignore next */ []));
+    /** The wrapped template, captured for registration and `NgTemplateOutlet` rendering. */
+    templateRef = inject(TemplateRef);
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: DfTemplate, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "21.2.14", type: DfTemplate, isStandalone: true, selector: "ng-template[dfTemplate]", inputs: { dfTemplate: { classPropertyName: "dfTemplate", publicName: "dfTemplate", isSignal: true, isRequired: true, transformFunction: null } }, exportAs: ["dfTemplate"], ngImport: i0 });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.8", ngImport: i0, type: EventDispatcher, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: DfTemplate, decorators: [{
+            type: Directive,
+            args: [{
+                    selector: 'ng-template[dfTemplate]',
+                    exportAs: 'dfTemplate',
+                }]
+        }], propDecorators: { dfTemplate: [{ type: i0.Input, args: [{ isSignal: true, alias: "dfTemplate", required: true }] }] } });
+/**
+ * Holder service published at the `<df-dynamic-form>` component scope.
+ * `DynamicForm` collects projected `<ng-template dfTemplate="...">` via
+ * `contentChildren(DfTemplate)` and pushes the resulting map through
+ * `DfFieldTemplateRegistry.set(...)`. The {@link DF_FIELD_TEMPLATES}
+ * injection token is provided as a factory that returns this service's
+ * `map` signal, so template-addon components can resolve `templateKey`
+ * without coupling to the host form's generic class.
+ */
+class DfFieldTemplateRegistry {
+    _map = signal(new Map(), ...(ngDevMode ? [{ debugName: "_map" }] : /* istanbul ignore next */ []));
+    /** Reactive view consumed by the `template` addon kind via DI. */
+    map = this._map.asReadonly();
+    /** Replace the registry contents — called from `DynamicForm` when projected templates change. */
+    set(value) {
+        this._map.set(value);
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: DfFieldTemplateRegistry, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: DfFieldTemplateRegistry });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: DfFieldTemplateRegistry, decorators: [{
             type: Injectable
         }] });
 
+/**
+ * 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.
+ */
+const DF_FIELD_TEMPLATES = new InjectionToken('DF_FIELD_TEMPLATES');
+
 /**
  * Dynamic form component — renders a form based on configuration.
  * Delegates state management to `FormStateManager`.
@@ -14695,6 +15316,13 @@ class DynamicForm {
     formOptions = input(undefined, ...(ngDevMode ? [{ debugName: "formOptions" }] : /* istanbul ignore next */ []));
     /** Form values for two-way data binding. */
     value = model(undefined, ...(ngDevMode ? [{ debugName: "value" }] : /* istanbul ignore next */ []));
+    /**
+     * 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 = input('inline', ...(ngDevMode ? [{ debugName: "source" }] : /* istanbul ignore next */ []));
     // ─────────────────────────────────────────────────────────────────────────────
     // Dependencies
     // ─────────────────────────────────────────────────────────────────────────────
@@ -14704,6 +15332,12 @@ class DynamicForm {
     eventBus = inject(EventBus);
     logger = inject(DynamicFormLogger);
     dispatcher = inject(EventDispatcher, { optional: true });
+    templateRegistry = inject(DfFieldTemplateRegistry);
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Projected templates — collected for the `template` addon kind via DI.
+    // ─────────────────────────────────────────────────────────────────────────────
+    /** All `<ng-template dfTemplate="...">` instances projected into this form. */
+    _projectedTemplates = contentChildren(DfTemplate, ...(ngDevMode ? [{ debugName: "_projectedTemplates" }] : /* istanbul ignore next */ []));
     /** State manager that owns all form state. Initialized via connectDeps() to guarantee
      * FORM_STATE_DEPS is populated before FormStateManager is injected. */
     stateManager = this.connectDeps();
@@ -14856,6 +15490,15 @@ class DynamicForm {
                 }, { injector: this.injector });
             }
         });
+        // Mirror projected `<ng-template dfTemplate="...">` into the template
+        // registry so `template` addons can resolve `templateKey` via DI.
+        explicitEffect([this._projectedTemplates], ([templates]) => {
+            const map = new Map();
+            for (const t of templates) {
+                map.set(t.dfTemplate(), t.templateRef);
+            }
+            this.templateRegistry.set(map);
+        });
     }
     /**
      * Populates FORM_STATE_DEPS with this component's input signals, then injects
@@ -14868,6 +15511,7 @@ class DynamicForm {
         deps.config = this.config;
         deps.formOptions = this.formOptions;
         deps.value = this.value;
+        deps.source = this.source;
         return inject((FormStateManager));
     }
     setupEventHandlers() {
@@ -14883,8 +15527,12 @@ class DynamicForm {
             error: (err) => this.logger.error('Submission handler error', err),
         });
     }
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.8", ngImport: i0, type: DynamicForm, deps: [], target: i0.ɵɵFactoryTarget.Component });
-    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "21.2.8", type: DynamicForm, isStandalone: true, selector: "form[dynamic-form]", inputs: { config: { classPropertyName: "config", publicName: "dynamic-form", isSignal: true, isRequired: true, transformFunction: null }, formOptions: { classPropertyName: "formOptions", publicName: "formOptions", isSignal: true, isRequired: false, transformFunction: null }, value: { classPropertyName: "value", publicName: "value", isSignal: true, isRequired: false, transformFunction: null } }, outputs: { value: "valueChange", validityChange: "validityChange", dirtyChange: "dirtyChange", submitted: "submitted", reset: "reset", cleared: "cleared", events: "events", initialized: "initialized", onPageChange: "onPageChange", onPageNavigationStateChange: "onPageNavigationStateChange" }, host: { attributes: { "novalidate": "" }, listeners: { "submit": "onNativeSubmit($event)" }, properties: { "class.disabled": "disabled()", "class.df-form-paged": "formModeDetection().mode === \"paged\"", "class.df-form-non-paged": "formModeDetection().mode === \"non-paged\"", "attr.data-form-mode": "formModeDetection().mode" }, classAttribute: "df-dynamic-form df-form" }, providers: [provideDynamicFormDI()], ngImport: i0, template: `
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: DynamicForm, deps: [], target: i0.ɵɵFactoryTarget.Component });
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "21.2.14", type: DynamicForm, isStandalone: true, selector: "form[dynamic-form]", inputs: { config: { classPropertyName: "config", publicName: "dynamic-form", isSignal: true, isRequired: true, transformFunction: null }, formOptions: { classPropertyName: "formOptions", publicName: "formOptions", isSignal: true, isRequired: false, transformFunction: null }, value: { classPropertyName: "value", publicName: "value", isSignal: true, isRequired: false, transformFunction: null }, source: { classPropertyName: "source", publicName: "source", isSignal: true, isRequired: false, transformFunction: null } }, outputs: { value: "valueChange", validityChange: "validityChange", dirtyChange: "dirtyChange", submitted: "submitted", reset: "reset", cleared: "cleared", events: "events", initialized: "initialized", onPageChange: "onPageChange", onPageNavigationStateChange: "onPageNavigationStateChange" }, host: { attributes: { "novalidate": "" }, listeners: { "submit": "onNativeSubmit($event)" }, properties: { "class.disabled": "disabled()", "class.df-form-paged": "formModeDetection().mode === \"paged\"", "class.df-form-non-paged": "formModeDetection().mode === \"non-paged\"", "attr.data-form-mode": "formModeDetection().mode" }, classAttribute: "df-dynamic-form df-form" }, providers: [
+            provideDynamicFormDI(),
+            DfFieldTemplateRegistry,
+            { provide: DF_FIELD_TEMPLATES, useFactory: () => inject(DfFieldTemplateRegistry).map },
+        ], queries: [{ propertyName: "_projectedTemplates", predicate: DfTemplate, isSignal: true }], ngImport: i0, template: `
     @if (shouldRender()) {
       @switch (formModeDetection().mode) {
         @case ('paged') {
@@ -14892,7 +15540,13 @@ class DynamicForm {
         }
         @case ('non-paged') {
           @for (field of resolvedFields(); track field.key) {
-            <ng-container *dfFieldOutlet="field; environmentInjector: environmentInjector" />
+            <!-- @if + DfFieldOutlet's own renderReady-&-!hidden gate together silence NG01916:
+                 the template @if removes the host from the DOM (Angular's prescribed pattern), and
+                 the directive's gate stops a same-CD-pass mount before [formField] can warn.
+                 Don't dedupe one without the other — see DfFieldOutlet.renderReady. -->
+            @if (!field.hidden()) {
+              <ng-container *dfFieldOutlet="field; environmentInjector: environmentInjector" />
+            }
           }
         }
         @default {
@@ -14900,9 +15554,9 @@ class DynamicForm {
         }
       }
     }
-  `, isInline: true, styles: [":host,.df-form{--df-grid-columns: 12;--df-grid-gap: .5rem;--df-grid-row-gap: .5rem;--df-breakpoint-sm: 576px;--df-breakpoint-md: 768px;--df-breakpoint-lg: 992px;--df-breakpoint-xl: 1200px;--df-grid-gap-sm: .5rem;--df-grid-gap-md: .5rem;--df-grid-gap-lg: .5rem;--df-grid-gap-xl: .5rem;--df-grid-row-gap-sm: .5rem;--df-grid-row-gap-md: .5rem;--df-grid-row-gap-lg: .5rem;--df-grid-row-gap-xl: .5rem;--df-array-item-gap: var(--df-grid-row-gap);--df-group-gap: var(--df-grid-gap);--df-group-padding: var(--df-grid-gap)}.df-form{display:grid;grid-template-columns:1fr;gap:var(--df-grid-row-gap);width:100%}.df-form>*{grid-column:1/-1}.df-row{display:grid;grid-template-columns:repeat(var(--df-grid-columns, 12),1fr);gap:var(--df-grid-gap);align-items:start;width:100%}.df-row>*:not([class*=df-col-]){grid-column:1/-1}.df-col-1{grid-column:span 1}.df-col-2{grid-column:span 2}.df-col-3{grid-column:span 3}.df-col-4{grid-column:span 4}.df-col-5{grid-column:span 5}.df-col-6{grid-column:span 6}.df-col-7{grid-column:span 7}.df-col-8{grid-column:span 8}.df-col-9{grid-column:span 9}.df-col-10{grid-column:span 10}.df-col-11{grid-column:span 11}.df-col-12{grid-column:span 12}.df-col-auto{grid-column:span auto;width:auto}.df-col-full{grid-column:1/-1}.df-col-start-1{grid-column-start:1}.df-col-start-2{grid-column-start:2}.df-col-start-3{grid-column-start:3}.df-col-start-4{grid-column-start:4}.df-col-start-5{grid-column-start:5}.df-col-start-6{grid-column-start:6}.df-col-start-7{grid-column-start:7}.df-col-start-8{grid-column-start:8}.df-col-start-9{grid-column-start:9}.df-col-start-10{grid-column-start:10}.df-col-start-11{grid-column-start:11}.df-col-start-12{grid-column-start:12}.df-col-end-1{grid-column-end:1}.df-col-end-2{grid-column-end:2}.df-col-end-3{grid-column-end:3}.df-col-end-4{grid-column-end:4}.df-col-end-5{grid-column-end:5}.df-col-end-6{grid-column-end:6}.df-col-end-7{grid-column-end:7}.df-col-end-8{grid-column-end:8}.df-col-end-9{grid-column-end:9}.df-col-end-10{grid-column-end:10}.df-col-end-11{grid-column-end:11}.df-col-end-12{grid-column-end:12}.df-col-end-13{grid-column-end:13}@media(max-width:576px){.df-form{--df-grid-gap: var(--df-grid-gap-sm);--df-grid-row-gap: var(--df-grid-row-gap-sm)}.df-row{grid-template-columns:1fr}.df-row>*{grid-column:1/-1!important}.df-row.df-row-mobile-keep-cols{grid-template-columns:repeat(var(--df-grid-columns),1fr)}.df-row.df-row-mobile-keep-cols>*{grid-column:revert!important}}@media(min-width:577px)and (max-width:768px){.df-form{--df-grid-gap: var(--df-grid-gap-md);--df-grid-row-gap: var(--df-grid-row-gap-md)}.df-row{--df-grid-columns: 6}.df-col-sm-1{grid-column:span 1}.df-col-sm-2{grid-column:span 2}.df-col-sm-3{grid-column:span 3}.df-col-sm-4{grid-column:span 4}.df-col-sm-5{grid-column:span 5}.df-col-sm-6{grid-column:span 6}.df-col-sm-full{grid-column:1/-1}}@media(min-width:769px)and (max-width:992px){.df-form{--df-grid-gap: var(--df-grid-gap-lg);--df-grid-row-gap: var(--df-grid-row-gap-lg)}.df-col-md-1{grid-column:span 1}.df-col-md-2{grid-column:span 2}.df-col-md-3{grid-column:span 3}.df-col-md-4{grid-column:span 4}.df-col-md-5{grid-column:span 5}.df-col-md-6{grid-column:span 6}.df-col-md-7{grid-column:span 7}.df-col-md-8{grid-column:span 8}.df-col-md-9{grid-column:span 9}.df-col-md-10{grid-column:span 10}.df-col-md-11{grid-column:span 11}.df-col-md-12{grid-column:span 12}.df-col-md-full{grid-column:1/-1}}@media(min-width:993px){.df-form{--df-grid-gap: var(--df-grid-gap-xl);--df-grid-row-gap: var(--df-grid-row-gap-xl)}.df-col-lg-1{grid-column:span 1}.df-col-lg-2{grid-column:span 2}.df-col-lg-3{grid-column:span 3}.df-col-lg-4{grid-column:span 4}.df-col-lg-5{grid-column:span 5}.df-col-lg-6{grid-column:span 6}.df-col-lg-7{grid-column:span 7}.df-col-lg-8{grid-column:span 8}.df-col-lg-9{grid-column:span 9}.df-col-lg-10{grid-column:span 10}.df-col-lg-11{grid-column:span 11}.df-col-lg-12{grid-column:span 12}.df-col-lg-full{grid-column:1/-1}}.df-gap-none{--df-grid-gap: 0}.df-gap-xs{--df-grid-gap: .25rem}.df-gap-sm{--df-grid-gap: .5rem}.df-gap-md{--df-grid-gap: 1rem}.df-gap-lg{--df-grid-gap: 1.5rem}.df-gap-xl{--df-grid-gap: 2rem}.df-row-gap-none{--df-grid-row-gap: 0}.df-row-gap-xs{--df-grid-row-gap: .25rem}.df-row-gap-sm{--df-grid-row-gap: .5rem}.df-row-gap-md{--df-grid-row-gap: 1rem}.df-row-gap-lg{--df-grid-row-gap: 1.5rem}.df-row-gap-xl{--df-grid-row-gap: 2rem}.df-field{display:block;width:100%;min-width:0;overflow:hidden;margin:0}.df-group,.df-page{display:block;width:100%}.df-form.disabled,.df-row.disabled,.df-field.disabled{opacity:.6;pointer-events:none}.df-sr-only{position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border:0}.df-sr-only-focusable:focus,.df-sr-only-focusable:active{position:static;width:auto;height:auto;padding:inherit;margin:inherit;overflow:visible;clip:auto;white-space:normal}.df-live-region{position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border:0}.df-form :focus-visible{outline:2px solid var(--df-focus-color, #005fcc);outline-offset:2px}.df-group:focus-within{outline:1px dashed var(--df-focus-color, #005fcc);outline-offset:4px}:host{display:grid;grid-template-columns:1fr;gap:var(--df-grid-row-gap);width:100%}:host>*{grid-column:1/-1}:host.df-form-spacing-custom{--df-grid-row-gap: var(--form-custom-spacing, 1.5rem)}:host.df-form-gap-none{--df-grid-row-gap: 0}:host.df-form-gap-xs{--df-grid-row-gap: .25rem}:host.df-form-gap-sm{--df-grid-row-gap: .5rem}:host.df-form-gap-md{--df-grid-row-gap: 1rem}:host.df-form-gap-lg{--df-grid-row-gap: 1.5rem}:host.df-form-gap-xl{--df-grid-row-gap: 2rem}:host.df-form-paged{--df-grid-row-gap: 0}\n"], dependencies: [{ kind: "directive", type: DfFieldOutlet, selector: "[dfFieldOutlet]", inputs: ["dfFieldOutlet", "dfFieldOutletEnvironmentInjector"] }, { kind: "component", type: PageOrchestratorComponent, selector: "div[page-orchestrator]", inputs: ["pageFields", "form", "fieldSignalContext"] }], changeDetection: i0.ChangeDetectionStrategy.OnPush });
+  `, isInline: true, styles: [".df-form{display:grid;grid-template-columns:1fr;gap:var(--df-grid-row-gap, .5rem);width:100%}.df-form>*{grid-column:1/-1}.df-row{display:grid;grid-template-columns:repeat(var(--df-grid-columns, 12),1fr);gap:var(--df-grid-gap, .5rem);align-items:start;width:100%}.df-row>*:not([class*=df-col-]){grid-column:1/-1}.df-col-1{grid-column:span 1}.df-col-2{grid-column:span 2}.df-col-3{grid-column:span 3}.df-col-4{grid-column:span 4}.df-col-5{grid-column:span 5}.df-col-6{grid-column:span 6}.df-col-7{grid-column:span 7}.df-col-8{grid-column:span 8}.df-col-9{grid-column:span 9}.df-col-10{grid-column:span 10}.df-col-11{grid-column:span 11}.df-col-12{grid-column:span 12}.df-col-auto{grid-column:span auto;width:auto}.df-col-full{grid-column:1/-1}.df-col-start-1{grid-column-start:1}.df-col-start-2{grid-column-start:2}.df-col-start-3{grid-column-start:3}.df-col-start-4{grid-column-start:4}.df-col-start-5{grid-column-start:5}.df-col-start-6{grid-column-start:6}.df-col-start-7{grid-column-start:7}.df-col-start-8{grid-column-start:8}.df-col-start-9{grid-column-start:9}.df-col-start-10{grid-column-start:10}.df-col-start-11{grid-column-start:11}.df-col-start-12{grid-column-start:12}.df-col-end-1{grid-column-end:1}.df-col-end-2{grid-column-end:2}.df-col-end-3{grid-column-end:3}.df-col-end-4{grid-column-end:4}.df-col-end-5{grid-column-end:5}.df-col-end-6{grid-column-end:6}.df-col-end-7{grid-column-end:7}.df-col-end-8{grid-column-end:8}.df-col-end-9{grid-column-end:9}.df-col-end-10{grid-column-end:10}.df-col-end-11{grid-column-end:11}.df-col-end-12{grid-column-end:12}.df-col-end-13{grid-column-end:13}@media(max-width:576px){.df-form{--df-grid-gap: var(--df-grid-gap-sm, .5rem);--df-grid-row-gap: var(--df-grid-row-gap-sm, .5rem)}.df-row{grid-template-columns:1fr}.df-row>*{grid-column:1/-1!important}.df-row.df-row-mobile-keep-cols{grid-template-columns:repeat(var(--df-grid-columns, 12),1fr)}.df-row.df-row-mobile-keep-cols>*{grid-column:revert!important}}@media(min-width:577px)and (max-width:768px){.df-form{--df-grid-gap: var(--df-grid-gap-md, .5rem);--df-grid-row-gap: var(--df-grid-row-gap-md, .5rem)}.df-row{--df-grid-columns: 6}.df-col-sm-1{grid-column:span 1}.df-col-sm-2{grid-column:span 2}.df-col-sm-3{grid-column:span 3}.df-col-sm-4{grid-column:span 4}.df-col-sm-5{grid-column:span 5}.df-col-sm-6{grid-column:span 6}.df-col-sm-full{grid-column:1/-1}}@media(min-width:769px)and (max-width:992px){.df-form{--df-grid-gap: var(--df-grid-gap-lg, .5rem);--df-grid-row-gap: var(--df-grid-row-gap-lg, .5rem)}.df-col-md-1{grid-column:span 1}.df-col-md-2{grid-column:span 2}.df-col-md-3{grid-column:span 3}.df-col-md-4{grid-column:span 4}.df-col-md-5{grid-column:span 5}.df-col-md-6{grid-column:span 6}.df-col-md-7{grid-column:span 7}.df-col-md-8{grid-column:span 8}.df-col-md-9{grid-column:span 9}.df-col-md-10{grid-column:span 10}.df-col-md-11{grid-column:span 11}.df-col-md-12{grid-column:span 12}.df-col-md-full{grid-column:1/-1}}@media(min-width:993px){.df-form{--df-grid-gap: var(--df-grid-gap-xl, .5rem);--df-grid-row-gap: var(--df-grid-row-gap-xl, .5rem)}.df-col-lg-1{grid-column:span 1}.df-col-lg-2{grid-column:span 2}.df-col-lg-3{grid-column:span 3}.df-col-lg-4{grid-column:span 4}.df-col-lg-5{grid-column:span 5}.df-col-lg-6{grid-column:span 6}.df-col-lg-7{grid-column:span 7}.df-col-lg-8{grid-column:span 8}.df-col-lg-9{grid-column:span 9}.df-col-lg-10{grid-column:span 10}.df-col-lg-11{grid-column:span 11}.df-col-lg-12{grid-column:span 12}.df-col-lg-full{grid-column:1/-1}}.df-gap-none{--df-grid-gap: 0}.df-gap-xs{--df-grid-gap: .25rem}.df-gap-sm{--df-grid-gap: .5rem}.df-gap-md{--df-grid-gap: 1rem}.df-gap-lg{--df-grid-gap: 1.5rem}.df-gap-xl{--df-grid-gap: 2rem}.df-row-gap-none{--df-grid-row-gap: 0}.df-row-gap-xs{--df-grid-row-gap: .25rem}.df-row-gap-sm{--df-grid-row-gap: .5rem}.df-row-gap-md{--df-grid-row-gap: 1rem}.df-row-gap-lg{--df-grid-row-gap: 1.5rem}.df-row-gap-xl{--df-grid-row-gap: 2rem}.df-field{display:block;width:100%;min-width:0;overflow:hidden;margin:0}.df-group,.df-page{display:block;width:100%}.df-form.disabled,.df-row.disabled,.df-field.disabled{opacity:.6;pointer-events:none}.df-sr-only{position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border:0}.df-sr-only-focusable:focus,.df-sr-only-focusable:active{position:static;width:auto;height:auto;padding:inherit;margin:inherit;overflow:visible;clip:auto;white-space:normal}.df-live-region{position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border:0}.df-form :focus-visible{outline:2px solid var(--df-focus-color, #005fcc);outline-offset:2px}.df-group:focus-within{outline:1px dashed var(--df-focus-color, #005fcc);outline-offset:4px}:host{display:grid;grid-template-columns:1fr;gap:var(--df-grid-row-gap, .5rem);width:100%}:host>*{grid-column:1/-1}:host.df-form-spacing-custom{--df-grid-row-gap: var(--df-form-custom-spacing, 1.5rem)}:host.df-form-gap-none{--df-grid-row-gap: 0}:host.df-form-gap-xs{--df-grid-row-gap: .25rem}:host.df-form-gap-sm{--df-grid-row-gap: .5rem}:host.df-form-gap-md{--df-grid-row-gap: 1rem}:host.df-form-gap-lg{--df-grid-row-gap: 1.5rem}:host.df-form-gap-xl{--df-grid-row-gap: 2rem}:host.df-form-paged{gap:0}\n"], dependencies: [{ kind: "directive", type: DfFieldOutlet, selector: "[dfFieldOutlet]", inputs: ["dfFieldOutlet", "dfFieldOutletEnvironmentInjector"] }, { kind: "component", type: PageOrchestratorComponent, selector: "div[page-orchestrator]", inputs: ["pageFields", "form", "fieldSignalContext"] }], changeDetection: i0.ChangeDetectionStrategy.OnPush });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.8", ngImport: i0, type: DynamicForm, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: DynamicForm, decorators: [{
             type: Component,
             args: [{ selector: 'form[dynamic-form]', imports: [DfFieldOutlet, PageOrchestratorComponent], template: `
     @if (shouldRender()) {
@@ -14912,7 +15566,13 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.8", ngImpor
         }
         @case ('non-paged') {
           @for (field of resolvedFields(); track field.key) {
-            <ng-container *dfFieldOutlet="field; environmentInjector: environmentInjector" />
+            <!-- @if + DfFieldOutlet's own renderReady-&-!hidden gate together silence NG01916:
+                 the template @if removes the host from the DOM (Angular's prescribed pattern), and
+                 the directive's gate stops a same-CD-pass mount before [formField] can warn.
+                 Don't dedupe one without the other — see DfFieldOutlet.renderReady. -->
+            @if (!field.hidden()) {
+              <ng-container *dfFieldOutlet="field; environmentInjector: environmentInjector" />
+            }
           }
         }
         @default {
@@ -14920,7 +15580,11 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.8", ngImpor
         }
       }
     }
-  `, providers: [provideDynamicFormDI()], host: {
+  `, providers: [
+                        provideDynamicFormDI(),
+                        DfFieldTemplateRegistry,
+                        { provide: DF_FIELD_TEMPLATES, useFactory: () => inject(DfFieldTemplateRegistry).map },
+                    ], host: {
                         class: 'df-dynamic-form df-form',
                         novalidate: '', // Disable browser validation - Angular Signal Forms handles validation
                         '[class.disabled]': 'disabled()',
@@ -14928,8 +15592,8 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.8", ngImpor
                         '[class.df-form-non-paged]': 'formModeDetection().mode === "non-paged"',
                         '[attr.data-form-mode]': 'formModeDetection().mode',
                         '(submit)': 'onNativeSubmit($event)',
-                    }, changeDetection: ChangeDetectionStrategy.OnPush, styles: [":host,.df-form{--df-grid-columns: 12;--df-grid-gap: .5rem;--df-grid-row-gap: .5rem;--df-breakpoint-sm: 576px;--df-breakpoint-md: 768px;--df-breakpoint-lg: 992px;--df-breakpoint-xl: 1200px;--df-grid-gap-sm: .5rem;--df-grid-gap-md: .5rem;--df-grid-gap-lg: .5rem;--df-grid-gap-xl: .5rem;--df-grid-row-gap-sm: .5rem;--df-grid-row-gap-md: .5rem;--df-grid-row-gap-lg: .5rem;--df-grid-row-gap-xl: .5rem;--df-array-item-gap: var(--df-grid-row-gap);--df-group-gap: var(--df-grid-gap);--df-group-padding: var(--df-grid-gap)}.df-form{display:grid;grid-template-columns:1fr;gap:var(--df-grid-row-gap);width:100%}.df-form>*{grid-column:1/-1}.df-row{display:grid;grid-template-columns:repeat(var(--df-grid-columns, 12),1fr);gap:var(--df-grid-gap);align-items:start;width:100%}.df-row>*:not([class*=df-col-]){grid-column:1/-1}.df-col-1{grid-column:span 1}.df-col-2{grid-column:span 2}.df-col-3{grid-column:span 3}.df-col-4{grid-column:span 4}.df-col-5{grid-column:span 5}.df-col-6{grid-column:span 6}.df-col-7{grid-column:span 7}.df-col-8{grid-column:span 8}.df-col-9{grid-column:span 9}.df-col-10{grid-column:span 10}.df-col-11{grid-column:span 11}.df-col-12{grid-column:span 12}.df-col-auto{grid-column:span auto;width:auto}.df-col-full{grid-column:1/-1}.df-col-start-1{grid-column-start:1}.df-col-start-2{grid-column-start:2}.df-col-start-3{grid-column-start:3}.df-col-start-4{grid-column-start:4}.df-col-start-5{grid-column-start:5}.df-col-start-6{grid-column-start:6}.df-col-start-7{grid-column-start:7}.df-col-start-8{grid-column-start:8}.df-col-start-9{grid-column-start:9}.df-col-start-10{grid-column-start:10}.df-col-start-11{grid-column-start:11}.df-col-start-12{grid-column-start:12}.df-col-end-1{grid-column-end:1}.df-col-end-2{grid-column-end:2}.df-col-end-3{grid-column-end:3}.df-col-end-4{grid-column-end:4}.df-col-end-5{grid-column-end:5}.df-col-end-6{grid-column-end:6}.df-col-end-7{grid-column-end:7}.df-col-end-8{grid-column-end:8}.df-col-end-9{grid-column-end:9}.df-col-end-10{grid-column-end:10}.df-col-end-11{grid-column-end:11}.df-col-end-12{grid-column-end:12}.df-col-end-13{grid-column-end:13}@media(max-width:576px){.df-form{--df-grid-gap: var(--df-grid-gap-sm);--df-grid-row-gap: var(--df-grid-row-gap-sm)}.df-row{grid-template-columns:1fr}.df-row>*{grid-column:1/-1!important}.df-row.df-row-mobile-keep-cols{grid-template-columns:repeat(var(--df-grid-columns),1fr)}.df-row.df-row-mobile-keep-cols>*{grid-column:revert!important}}@media(min-width:577px)and (max-width:768px){.df-form{--df-grid-gap: var(--df-grid-gap-md);--df-grid-row-gap: var(--df-grid-row-gap-md)}.df-row{--df-grid-columns: 6}.df-col-sm-1{grid-column:span 1}.df-col-sm-2{grid-column:span 2}.df-col-sm-3{grid-column:span 3}.df-col-sm-4{grid-column:span 4}.df-col-sm-5{grid-column:span 5}.df-col-sm-6{grid-column:span 6}.df-col-sm-full{grid-column:1/-1}}@media(min-width:769px)and (max-width:992px){.df-form{--df-grid-gap: var(--df-grid-gap-lg);--df-grid-row-gap: var(--df-grid-row-gap-lg)}.df-col-md-1{grid-column:span 1}.df-col-md-2{grid-column:span 2}.df-col-md-3{grid-column:span 3}.df-col-md-4{grid-column:span 4}.df-col-md-5{grid-column:span 5}.df-col-md-6{grid-column:span 6}.df-col-md-7{grid-column:span 7}.df-col-md-8{grid-column:span 8}.df-col-md-9{grid-column:span 9}.df-col-md-10{grid-column:span 10}.df-col-md-11{grid-column:span 11}.df-col-md-12{grid-column:span 12}.df-col-md-full{grid-column:1/-1}}@media(min-width:993px){.df-form{--df-grid-gap: var(--df-grid-gap-xl);--df-grid-row-gap: var(--df-grid-row-gap-xl)}.df-col-lg-1{grid-column:span 1}.df-col-lg-2{grid-column:span 2}.df-col-lg-3{grid-column:span 3}.df-col-lg-4{grid-column:span 4}.df-col-lg-5{grid-column:span 5}.df-col-lg-6{grid-column:span 6}.df-col-lg-7{grid-column:span 7}.df-col-lg-8{grid-column:span 8}.df-col-lg-9{grid-column:span 9}.df-col-lg-10{grid-column:span 10}.df-col-lg-11{grid-column:span 11}.df-col-lg-12{grid-column:span 12}.df-col-lg-full{grid-column:1/-1}}.df-gap-none{--df-grid-gap: 0}.df-gap-xs{--df-grid-gap: .25rem}.df-gap-sm{--df-grid-gap: .5rem}.df-gap-md{--df-grid-gap: 1rem}.df-gap-lg{--df-grid-gap: 1.5rem}.df-gap-xl{--df-grid-gap: 2rem}.df-row-gap-none{--df-grid-row-gap: 0}.df-row-gap-xs{--df-grid-row-gap: .25rem}.df-row-gap-sm{--df-grid-row-gap: .5rem}.df-row-gap-md{--df-grid-row-gap: 1rem}.df-row-gap-lg{--df-grid-row-gap: 1.5rem}.df-row-gap-xl{--df-grid-row-gap: 2rem}.df-field{display:block;width:100%;min-width:0;overflow:hidden;margin:0}.df-group,.df-page{display:block;width:100%}.df-form.disabled,.df-row.disabled,.df-field.disabled{opacity:.6;pointer-events:none}.df-sr-only{position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border:0}.df-sr-only-focusable:focus,.df-sr-only-focusable:active{position:static;width:auto;height:auto;padding:inherit;margin:inherit;overflow:visible;clip:auto;white-space:normal}.df-live-region{position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border:0}.df-form :focus-visible{outline:2px solid var(--df-focus-color, #005fcc);outline-offset:2px}.df-group:focus-within{outline:1px dashed var(--df-focus-color, #005fcc);outline-offset:4px}:host{display:grid;grid-template-columns:1fr;gap:var(--df-grid-row-gap);width:100%}:host>*{grid-column:1/-1}:host.df-form-spacing-custom{--df-grid-row-gap: var(--form-custom-spacing, 1.5rem)}:host.df-form-gap-none{--df-grid-row-gap: 0}:host.df-form-gap-xs{--df-grid-row-gap: .25rem}:host.df-form-gap-sm{--df-grid-row-gap: .5rem}:host.df-form-gap-md{--df-grid-row-gap: 1rem}:host.df-form-gap-lg{--df-grid-row-gap: 1.5rem}:host.df-form-gap-xl{--df-grid-row-gap: 2rem}:host.df-form-paged{--df-grid-row-gap: 0}\n"] }]
-        }], ctorParameters: () => [], propDecorators: { config: [{ type: i0.Input, args: [{ isSignal: true, alias: "dynamic-form", required: true }] }], formOptions: [{ type: i0.Input, args: [{ isSignal: true, alias: "formOptions", required: false }] }], value: [{ type: i0.Input, args: [{ isSignal: true, alias: "value", required: false }] }, { type: i0.Output, args: ["valueChange"] }], validityChange: [{ type: i0.Output, args: ["validityChange"] }], dirtyChange: [{ type: i0.Output, args: ["dirtyChange"] }], submitted: [{ type: i0.Output, args: ["submitted"] }], reset: [{ type: i0.Output, args: ["reset"] }], cleared: [{ type: i0.Output, args: ["cleared"] }], events: [{ type: i0.Output, args: ["events"] }], initialized: [{ type: i0.Output, args: ["initialized"] }], onPageChange: [{ type: i0.Output, args: ["onPageChange"] }], onPageNavigationStateChange: [{ type: i0.Output, args: ["onPageNavigationStateChange"] }] } });
+                    }, changeDetection: ChangeDetectionStrategy.OnPush, styles: [".df-form{display:grid;grid-template-columns:1fr;gap:var(--df-grid-row-gap, .5rem);width:100%}.df-form>*{grid-column:1/-1}.df-row{display:grid;grid-template-columns:repeat(var(--df-grid-columns, 12),1fr);gap:var(--df-grid-gap, .5rem);align-items:start;width:100%}.df-row>*:not([class*=df-col-]){grid-column:1/-1}.df-col-1{grid-column:span 1}.df-col-2{grid-column:span 2}.df-col-3{grid-column:span 3}.df-col-4{grid-column:span 4}.df-col-5{grid-column:span 5}.df-col-6{grid-column:span 6}.df-col-7{grid-column:span 7}.df-col-8{grid-column:span 8}.df-col-9{grid-column:span 9}.df-col-10{grid-column:span 10}.df-col-11{grid-column:span 11}.df-col-12{grid-column:span 12}.df-col-auto{grid-column:span auto;width:auto}.df-col-full{grid-column:1/-1}.df-col-start-1{grid-column-start:1}.df-col-start-2{grid-column-start:2}.df-col-start-3{grid-column-start:3}.df-col-start-4{grid-column-start:4}.df-col-start-5{grid-column-start:5}.df-col-start-6{grid-column-start:6}.df-col-start-7{grid-column-start:7}.df-col-start-8{grid-column-start:8}.df-col-start-9{grid-column-start:9}.df-col-start-10{grid-column-start:10}.df-col-start-11{grid-column-start:11}.df-col-start-12{grid-column-start:12}.df-col-end-1{grid-column-end:1}.df-col-end-2{grid-column-end:2}.df-col-end-3{grid-column-end:3}.df-col-end-4{grid-column-end:4}.df-col-end-5{grid-column-end:5}.df-col-end-6{grid-column-end:6}.df-col-end-7{grid-column-end:7}.df-col-end-8{grid-column-end:8}.df-col-end-9{grid-column-end:9}.df-col-end-10{grid-column-end:10}.df-col-end-11{grid-column-end:11}.df-col-end-12{grid-column-end:12}.df-col-end-13{grid-column-end:13}@media(max-width:576px){.df-form{--df-grid-gap: var(--df-grid-gap-sm, .5rem);--df-grid-row-gap: var(--df-grid-row-gap-sm, .5rem)}.df-row{grid-template-columns:1fr}.df-row>*{grid-column:1/-1!important}.df-row.df-row-mobile-keep-cols{grid-template-columns:repeat(var(--df-grid-columns, 12),1fr)}.df-row.df-row-mobile-keep-cols>*{grid-column:revert!important}}@media(min-width:577px)and (max-width:768px){.df-form{--df-grid-gap: var(--df-grid-gap-md, .5rem);--df-grid-row-gap: var(--df-grid-row-gap-md, .5rem)}.df-row{--df-grid-columns: 6}.df-col-sm-1{grid-column:span 1}.df-col-sm-2{grid-column:span 2}.df-col-sm-3{grid-column:span 3}.df-col-sm-4{grid-column:span 4}.df-col-sm-5{grid-column:span 5}.df-col-sm-6{grid-column:span 6}.df-col-sm-full{grid-column:1/-1}}@media(min-width:769px)and (max-width:992px){.df-form{--df-grid-gap: var(--df-grid-gap-lg, .5rem);--df-grid-row-gap: var(--df-grid-row-gap-lg, .5rem)}.df-col-md-1{grid-column:span 1}.df-col-md-2{grid-column:span 2}.df-col-md-3{grid-column:span 3}.df-col-md-4{grid-column:span 4}.df-col-md-5{grid-column:span 5}.df-col-md-6{grid-column:span 6}.df-col-md-7{grid-column:span 7}.df-col-md-8{grid-column:span 8}.df-col-md-9{grid-column:span 9}.df-col-md-10{grid-column:span 10}.df-col-md-11{grid-column:span 11}.df-col-md-12{grid-column:span 12}.df-col-md-full{grid-column:1/-1}}@media(min-width:993px){.df-form{--df-grid-gap: var(--df-grid-gap-xl, .5rem);--df-grid-row-gap: var(--df-grid-row-gap-xl, .5rem)}.df-col-lg-1{grid-column:span 1}.df-col-lg-2{grid-column:span 2}.df-col-lg-3{grid-column:span 3}.df-col-lg-4{grid-column:span 4}.df-col-lg-5{grid-column:span 5}.df-col-lg-6{grid-column:span 6}.df-col-lg-7{grid-column:span 7}.df-col-lg-8{grid-column:span 8}.df-col-lg-9{grid-column:span 9}.df-col-lg-10{grid-column:span 10}.df-col-lg-11{grid-column:span 11}.df-col-lg-12{grid-column:span 12}.df-col-lg-full{grid-column:1/-1}}.df-gap-none{--df-grid-gap: 0}.df-gap-xs{--df-grid-gap: .25rem}.df-gap-sm{--df-grid-gap: .5rem}.df-gap-md{--df-grid-gap: 1rem}.df-gap-lg{--df-grid-gap: 1.5rem}.df-gap-xl{--df-grid-gap: 2rem}.df-row-gap-none{--df-grid-row-gap: 0}.df-row-gap-xs{--df-grid-row-gap: .25rem}.df-row-gap-sm{--df-grid-row-gap: .5rem}.df-row-gap-md{--df-grid-row-gap: 1rem}.df-row-gap-lg{--df-grid-row-gap: 1.5rem}.df-row-gap-xl{--df-grid-row-gap: 2rem}.df-field{display:block;width:100%;min-width:0;overflow:hidden;margin:0}.df-group,.df-page{display:block;width:100%}.df-form.disabled,.df-row.disabled,.df-field.disabled{opacity:.6;pointer-events:none}.df-sr-only{position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border:0}.df-sr-only-focusable:focus,.df-sr-only-focusable:active{position:static;width:auto;height:auto;padding:inherit;margin:inherit;overflow:visible;clip:auto;white-space:normal}.df-live-region{position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border:0}.df-form :focus-visible{outline:2px solid var(--df-focus-color, #005fcc);outline-offset:2px}.df-group:focus-within{outline:1px dashed var(--df-focus-color, #005fcc);outline-offset:4px}:host{display:grid;grid-template-columns:1fr;gap:var(--df-grid-row-gap, .5rem);width:100%}:host>*{grid-column:1/-1}:host.df-form-spacing-custom{--df-grid-row-gap: var(--df-form-custom-spacing, 1.5rem)}:host.df-form-gap-none{--df-grid-row-gap: 0}:host.df-form-gap-xs{--df-grid-row-gap: .25rem}:host.df-form-gap-sm{--df-grid-row-gap: .5rem}:host.df-form-gap-md{--df-grid-row-gap: 1rem}:host.df-form-gap-lg{--df-grid-row-gap: 1.5rem}:host.df-form-gap-xl{--df-grid-row-gap: 2rem}:host.df-form-paged{gap:0}\n"] }]
+        }], ctorParameters: () => [], propDecorators: { config: [{ type: i0.Input, args: [{ isSignal: true, alias: "dynamic-form", required: true }] }], formOptions: [{ type: i0.Input, args: [{ isSignal: true, alias: "formOptions", required: false }] }], value: [{ type: i0.Input, args: [{ isSignal: true, alias: "value", required: false }] }, { type: i0.Output, args: ["valueChange"] }], source: [{ type: i0.Input, args: [{ isSignal: true, alias: "source", required: false }] }], _projectedTemplates: [{ type: i0.ContentChildren, args: [i0.forwardRef(() => DfTemplate), { isSignal: true }] }], validityChange: [{ type: i0.Output, args: ["validityChange"] }], dirtyChange: [{ type: i0.Output, args: ["dirtyChange"] }], submitted: [{ type: i0.Output, args: ["submitted"] }], reset: [{ type: i0.Output, args: ["reset"] }], cleared: [{ type: i0.Output, args: ["cleared"] }], events: [{ type: i0.Output, args: ["events"] }], initialized: [{ type: i0.Output, args: ["initialized"] }], onPageChange: [{ type: i0.Output, args: ["onPageChange"] }], onPageNavigationStateChange: [{ type: i0.Output, args: ["onPageNavigationStateChange"] }] } });
 /**
  * Recursively counts container fields (page, row, group, array, wrapper) in a field tree.
  * Descends into container children including array item templates to ensure
@@ -14959,6 +15623,147 @@ function countContainersRecursive(fields) {
     return count;
 }
 
+/**
+ * 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
+ */
+const ADDON_KIND_COMPONENT_CACHE = new InjectionToken('ADDON_KIND_COMPONENT_CACHE');
+/**
+ * Injection function for accessing the addon kind registry.
+ *
+ * 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');
+ * ```
+ */
+function injectAddonKindRegistry() {
+    const registry = inject(ADDON_KIND_REGISTRY);
+    const componentCache = inject(ADDON_KIND_COMPONENT_CACHE);
+    return {
+        /** Look up a kind definition by its discriminant. */
+        getKind(kind) {
+            return registry.get(kind);
+        },
+        /** Whether a kind is currently registered. */
+        hasKind(kind) {
+            return registry.has(kind);
+        },
+        /** All registered kind names — useful for actionable validator warnings. */
+        getKindNames() {
+            return Array.from(registry.keys());
+        },
+        /**
+         * Resolve a kind to its renderer component. Caches on first resolution.
+         *
+         * @throws DynamicFormError when the kind is not registered.
+         */
+        async loadKindComponent(kind) {
+            const definition = registry.get(kind);
+            if (!definition) {
+                const known = Array.from(registry.keys()).join(', ') || '(none)';
+                throw new DynamicFormError(`Addon kind '${kind}' is not registered. Currently registered kinds: ${known}.`);
+            }
+            const cached = componentCache.get(kind);
+            if (cached) {
+                return cached;
+            }
+            try {
+                const component = resolveDefaultExport(await definition.loadComponent());
+                if (component) {
+                    componentCache.set(kind, component);
+                    return component;
+                }
+                throw new DynamicFormError(`Addon kind '${kind}' loadComponent resolved to null.`);
+            }
+            catch (error) {
+                if (error instanceof DynamicFormError)
+                    throw error;
+                throw new DynamicFormError(`Failed to load component for addon kind '${kind}': ${error instanceof Error ? error.message : String(error)}`);
+            }
+        },
+        /**
+         * Synchronous lookup of an already-loaded kind component, or undefined.
+         * Returns `undefined` when the kind isn't registered in this scope even
+         * if a prior scope cached a component under the same name — prevents
+         * cross-form cache hits when registrations diverge.
+         */
+        getLoadedKindComponent(kind) {
+            if (!registry.has(kind))
+                return undefined;
+            return componentCache.get(kind);
+        },
+        /** Direct read-only access to the registry map. */
+        get raw() {
+            return registry;
+        },
+    };
+}
+
+/**
+ * Built-in addon kinds shipped by core.
+ *
+ * Universally adapter-independent: `text`, `template`, `component`. Adapters
+ * register their own kinds (e.g., `prime-icon`, `prime-button`) via
+ * `withCustomAddon(...)` features.
+ */
+const BUILT_IN_ADDON_KINDS = [
+    {
+        kind: 'text',
+        loadComponent: () => Promise.resolve().then(function () { return textAddon_component; }).then((m) => m.TextAddonComponent),
+        validate: (addon, fieldKey) => {
+            const text = addon.text;
+            // Validates structural presence: rejects missing / null / non-string-non-callable,
+            // and rejects literal empty strings. DynamicText values that resolve to empty
+            // at runtime (signal/observable yielding '') are NOT caught here — they're
+            // legal as far as the config is concerned, just render an empty span.
+            if (text === undefined || text === null) {
+                throw new DynamicFormError(`Addon kind 'text' requires a 'text' field (field: '${fieldKey}').`);
+            }
+            if (typeof text === 'string' && text.length === 0) {
+                throw new DynamicFormError(`Addon kind 'text' requires a non-empty 'text' string (field: '${fieldKey}').`);
+            }
+        },
+    },
+    {
+        kind: 'template',
+        loadComponent: () => Promise.resolve().then(function () { return templateAddon_component; }).then((m) => m.TemplateAddonComponent),
+        validate: (addon, fieldKey) => {
+            const key = addon.templateKey;
+            if (typeof key !== 'string' || key.length === 0) {
+                throw new DynamicFormError(`Addon kind 'template' requires a non-empty 'templateKey' string (field: '${fieldKey}').`);
+            }
+        },
+    },
+    {
+        kind: 'component',
+        // The shape carries a function loader — not serialisable; dropped by the
+        // validator when the form config originated from JSON.
+        jsonSafe: false,
+        loadComponent: () => Promise.resolve().then(function () { return componentAddon_component; }).then((m) => m.ComponentAddonComponent),
+        validate: (addon, fieldKey) => {
+            const loader = addon.component;
+            if (typeof loader !== 'function') {
+                throw new DynamicFormError(`Addon kind 'component' requires a 'component' loader function (field: '${fieldKey}').`);
+            }
+        },
+    },
+];
+
 /**
  * No-op logger for when no logger is provided.
  * Used as fallback in button logic evaluation to avoid breaking downstream packages.
@@ -15495,8 +16300,14 @@ function containerFieldMapper(fieldDef) {
  * ```
  */
 /**
- * Base field type definitions for fields that don't use the `field` input.
- * Used by display-only fields like `text` that render immediately without
+ * Base for container field types that consume the mapper-emitted `field` input
+ * (row, group, array, page, container).
+ */
+const CONTAINER_FIELD_TYPES_BASE = {
+    renderReadyWhen: ['field'],
+};
+/**
+ * Base for display-only fields (`text`) that render immediately without
  * waiting for form value integration.
  */
 const DISPLAY_FIELD_TYPES_BASE = {
@@ -15515,31 +16326,35 @@ const BUILT_IN_FIELDS = [
         // `row` is a virtual field type: it maps to ContainerFieldComponent, and
         // the rowFieldMapper injects a `{ type: 'row' }` wrapper so the container
         // renders the flex/grid layout via RowWrapperComponent.
-        loadComponent: () => import('./ng-forge-dynamic-forms-container-field.component-Pcxg5PQu.mjs'),
+        loadComponent: () => import('./ng-forge-dynamic-forms-container-field.component-BD7Lpcts.mjs'),
         mapper: rowFieldMapper,
         valueHandling: 'flatten',
+        ...CONTAINER_FIELD_TYPES_BASE,
     },
     {
         name: 'group',
-        loadComponent: () => import('./ng-forge-dynamic-forms-group-field.component-fzKwPrQr.mjs'),
+        loadComponent: () => import('./ng-forge-dynamic-forms-group-field.component-C9xUHrXp.mjs'),
         mapper: groupFieldMapper,
         valueHandling: 'include',
+        ...CONTAINER_FIELD_TYPES_BASE,
     },
     {
         name: 'array',
-        loadComponent: () => import('./ng-forge-dynamic-forms-array-field.component-DJ-LiLm_.mjs'),
+        loadComponent: () => import('./ng-forge-dynamic-forms-array-field.component-Ckpe0rW7.mjs'),
         mapper: arrayFieldMapper,
         valueHandling: 'include',
+        ...CONTAINER_FIELD_TYPES_BASE,
     },
     {
         name: 'page',
-        loadComponent: () => import('./ng-forge-dynamic-forms-page-field.component-BX4R9GGa.mjs'),
+        loadComponent: () => import('./ng-forge-dynamic-forms-page-field.component-BwNIx3R1.mjs'),
         mapper: pageFieldMapper,
         valueHandling: 'flatten',
+        ...CONTAINER_FIELD_TYPES_BASE,
     },
     {
         name: 'text',
-        loadComponent: () => import('./ng-forge-dynamic-forms-text-field.component-B9SK8Vun.mjs'),
+        loadComponent: () => import('./ng-forge-dynamic-forms-text-field.component-CpgtswdO.mjs'),
         mapper: textFieldMapper,
         valueHandling: 'exclude',
         ...DISPLAY_FIELD_TYPES_BASE,
@@ -15551,22 +16366,32 @@ const BUILT_IN_FIELDS = [
     },
     {
         name: 'container',
-        loadComponent: () => import('./ng-forge-dynamic-forms-container-field.component-Pcxg5PQu.mjs'),
+        loadComponent: () => import('./ng-forge-dynamic-forms-container-field.component-BD7Lpcts.mjs'),
         mapper: containerFieldMapper,
         valueHandling: 'flatten',
+        ...CONTAINER_FIELD_TYPES_BASE,
     },
 ];
 const BUILT_IN_WRAPPERS = [
     {
         wrapperName: 'css',
-        loadComponent: () => import('./ng-forge-dynamic-forms-css-wrapper.component-CJACCIEK.mjs'),
+        loadComponent: () => import('./ng-forge-dynamic-forms-css-wrapper.component-DkyuJH6T.mjs'),
     },
     {
         wrapperName: 'row',
-        loadComponent: () => import('./ng-forge-dynamic-forms-row-wrapper.component-BIvEUoia.mjs'),
+        loadComponent: () => import('./ng-forge-dynamic-forms-row-wrapper.component-CFtnatYj.mjs'),
     },
 ];
 
+/**
+ * Multi-provider token used by `withCustomAddon(...)` features to contribute
+ * addon kind definitions. `provideDynamicForm` aggregates all values into
+ * the form-scoped `ADDON_KIND_REGISTRY` map.
+ *
+ * @internal
+ */
+const ADDON_KIND_DEFINITIONS = new InjectionToken('ADDON_KIND_DEFINITIONS');
+
 /**
  * Bundle wrapper registrations into a single object that can be passed to
  * `provideDynamicForm(...)`.
@@ -15683,8 +16508,6 @@ function provideDynamicForm(...items) {
     const defaultLoggerProvider = hasLoggerFeature ? [] : [{ provide: DynamicFormLogger, useValue: new ConsoleLogger() }];
     return makeEnvironmentProviders([
         ...defaultLoggerProvider,
-        // Always provide default Signal Forms classes (ng-touched, ng-invalid, etc.)
-        provideSignalFormsConfig({ classes: NG_STATUS_CLASSES }),
         {
             provide: FIELD_REGISTRY,
             useFactory: () => {
@@ -15735,6 +16558,31 @@ function provideDynamicForm(...items) {
                 return autoMap;
             },
         },
+        // Form-scoped addon kind registry. Built from BUILT_IN_ADDON_KINDS plus
+        // every kind contributed by `withCustomAddon(...)` features (via the
+        // ADDON_KIND_DEFINITIONS multi-provider). Overrides the empty
+        // `providedIn: 'root'` default so contributions from form-scoped
+        // providers are visible.
+        {
+            provide: ADDON_KIND_REGISTRY,
+            useFactory: () => {
+                const logger = inject(DynamicFormLogger);
+                const contributed = inject(ADDON_KIND_DEFINITIONS, { optional: true }) ?? [];
+                const registry = new Map();
+                for (const def of BUILT_IN_ADDON_KINDS) {
+                    registry.set(def.kind, def);
+                }
+                for (const def of contributed) {
+                    if (registry.has(def.kind)) {
+                        logger.warn(`Addon kind "${def.kind}" is already registered. Overwriting.`);
+                    }
+                    registry.set(def.kind, def);
+                }
+                return registry;
+            },
+        },
+        // Per-form addon-component cache (no root fallback — isolated by form scope).
+        { provide: ADDON_KIND_COMPONENT_CACHE, useFactory: () => new Map() },
         ...featureProviders,
     ]);
 }
@@ -15911,6 +16759,35 @@ function withValidationExecutionDefaults(config) {
     return createFeature('validation-execution', [{ provide: VALIDATION_EXECUTION_DEFAULTS, useValue: resolved }]);
 }
 
+/**
+ * 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 Opt in once at the application root
+ * ```typescript
+ * bootstrapApplication(AppComponent, {
+ *   providers: [
+ *     provideDynamicForm(
+ *       ...withMaterialFields(),
+ *       withLegacyStatusClasses()
+ *     )
+ *   ]
+ * });
+ * ```
+ *
+ * @returns A DynamicFormFeature that enables the legacy `ng-*` class strategy
+ *
+ * @public
+ */
+function withLegacyStatusClasses() {
+    return createFeature('legacy-status-classes', [...provideSignalFormsConfig({ classes: NG_STATUS_CLASSES })]);
+}
+
 /**
  * Zero-cost type carrier used in wrapper registrations.
  *
@@ -15938,45 +16815,752 @@ function wrapperProps() {
     return undefined;
 }
 
-function isValueField(field) {
-    // `nullable: true` without an explicit `value` is still a value-bearing declaration:
-    // the field resolves to `null` at runtime. Treating it as a value field keeps
-    // downstream narrowing consistent with getFieldDefaultValue's behavior.
-    return 'value' in field || 'nullable' in field;
-}
-
-function isCheckedField(field) {
-    return field.type === 'checkbox';
+/** Type guard narrowing {@link AddonActionContext} to its field-bound variant. */
+function isFieldBoundContext(ctx) {
+    return ctx.form !== null;
 }
 
 /**
- * Builder for array manipulation events.
+ * Normalises a {@link DynamicValue} into a `Signal<T>`.
  *
- * Provides a fluent, discoverable API for array operations.
- * Type `arrayEvent('key').` in your IDE to see all available operations.
+ * 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.
  *
- * **BREAKING CHANGE**: Template is now required for add operations.
+ * Static values yield a `computed` that always returns the same constant —
+ * preferable to wrapping in `signal()` because the computed never causes
+ * change-detection invalidation.
  *
- * Supports both primitive and object array items:
- * - Primitive: Pass a single field definition → extracts field value directly
- * - Object: Pass an array of field definitions → merges fields into object
+ * 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
- * import { arrayEvent } from '@ng-forge/dynamic-forms';
+ * const isHidden = resolveDynamicValue(addon().hidden, false);
+ * // template: \@if (isHidden()) { ... }
+ * ```
+ */
+function resolveDynamicValue(value, fallback, injector) {
+    if (value === undefined) {
+        return computed(() => fallback);
+    }
+    if (isSignal(value)) {
+        return value;
+    }
+    if (isObservable(value)) {
+        return toSignal(value, { initialValue: fallback, injector });
+    }
+    // Static value
+    return computed(() => value);
+}
+
+/**
+ * Dispatcher component that renders an addon by looking up its `kind` in
+ * `ADDON_KIND_REGISTRY` and instantiating the registered component.
  *
- * // Object item: append { name, email } object
- * eventBus.dispatch(arrayEvent('contacts').append([
- *   { key: 'name', type: 'input', label: 'Name' },
- *   { key: 'email', type: 'input', label: 'Email' }
- * ]));
+ * Used by every adapter's field component to render slot content:
  *
- * // Primitive item: append single value
- * eventBus.dispatch(arrayEvent('tags').append(
- *   { key: 'tag', type: 'input', label: 'Tag' }
- * ));
+ * ```html
+ * \@for (a of addonsAt('prefix'); track $index) {
+ *   <df-addon-slot [addon]="a" />
+ * }
+ * ```
  *
- * // Removing items (no template needed)
+ * 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.
+ */
+class DfAddonSlot {
+    registry = injectAddonKindRegistry();
+    logger = inject(DynamicFormLogger);
+    hostInjector = inject(Injector);
+    addon = input.required(...(ngDevMode ? [{ debugName: "addon" }] : /* istanbul ignore next */ []));
+    /**
+     * 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).
+     */
+    fieldInputs = input(...(ngDevMode ? [undefined, { debugName: "fieldInputs" }] : /* istanbul ignore next */ []));
+    /**
+     * 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.
+     */
+    hidden = input(undefined, ...(ngDevMode ? [{ debugName: "hidden" }] : /* istanbul ignore next */ []));
+    /** `slot` HTML attribute forwarded to host — needed for Ionic shadow projection. */
+    slotAttr = computed(() => this.addon().slot, ...(ngDevMode ? [{ debugName: "slotAttr" }] : /* istanbul ignore next */ []));
+    className = computed(() => this.addon().className ?? null, ...(ngDevMode ? [{ debugName: "className" }] : /* istanbul ignore next */ []));
+    /**
+     * 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.
+     */
+    _hiddenByValue = new WeakMap();
+    _resolvedHidden = signal(undefined, ...(ngDevMode ? [{ debugName: "_resolvedHidden" }] : /* istanbul ignore next */ []));
+    /**
+     * `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.
+     */
+    isHidden = computed(() => {
+        const pre = this.hidden();
+        if (pre)
+            return pre();
+        const local = this._resolvedHidden();
+        return local ? local() : false;
+    }, ...(ngDevMode ? [{ debugName: "isHidden" }] : /* istanbul ignore next */ []));
+    /**
+     * 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.
+     */
+    asyncLoaded = signal(undefined, ...(ngDevMode ? [{ debugName: "asyncLoaded" }] : /* istanbul ignore next */ []));
+    /**
+     * 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.
+     */
+    resolvedComponent = computed(() => {
+        const kind = this.addon().kind;
+        const cached = this.registry.getLoadedKindComponent(kind);
+        if (cached)
+            return cached;
+        const loaded = this.asyncLoaded();
+        return loaded?.kind === kind ? loaded.component : undefined;
+    }, ...(ngDevMode ? [{ debugName: "resolvedComponent" }] : /* istanbul ignore next */ []));
+    /** Inputs passed to the kind component — addon plus the wrapper-style host bag. */
+    kindInputs = computed(() => ({
+        addon: this.addon(),
+        fieldInputs: this.fieldInputs(),
+    }), ...(ngDevMode ? [{ debugName: "kindInputs" }] : /* istanbul ignore next */ []));
+    constructor() {
+        // Resolve `addon.hidden` outside any reactive context AND unconditionally —
+        // the host-supplied signal is a perf hint, not a precondition. Keeping
+        // `_resolvedHidden` always-fresh closes a race where `isHidden` could
+        // return `false` between a host-`hidden` clear and the effect re-running.
+        explicitEffect([this.addon], ([addon]) => {
+            const h = addon.hidden;
+            const valueKey = typeof h === 'object' && h !== null ? h : null;
+            let resolved = valueKey ? this._hiddenByValue.get(valueKey) : undefined;
+            if (!resolved) {
+                resolved = resolveDynamicValue(addon.hidden, false, this.hostInjector);
+                if (valueKey)
+                    this._hiddenByValue.set(valueKey, resolved);
+            }
+            this._resolvedHidden.set(resolved);
+        });
+        // Kick off async loads on cache miss. `resolvedComponent` filters stale
+        // results by kind identity, so this effect is a pure side-effect dispatcher.
+        explicitEffect([this.addon], ([addon]) => {
+            const kind = addon.kind;
+            if (this.registry.getLoadedKindComponent(kind))
+                return; // sync path; computed picks it up
+            this.registry
+                .loadKindComponent(kind)
+                .then((component) => this.asyncLoaded.set({ kind, component }))
+                .catch((error) => {
+                this.logger.warn(`Failed to load addon kind '${kind}': ${error instanceof Error ? error.message : String(error)}. ` +
+                    `Registered kinds: ${this.registry.getKindNames().join(', ') || '(none)'}.`);
+            });
+        });
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: DfAddonSlot, deps: [], target: i0.ɵɵFactoryTarget.Component });
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "21.2.14", type: DfAddonSlot, isStandalone: true, selector: "df-addon-slot", inputs: { addon: { classPropertyName: "addon", publicName: "addon", isSignal: true, isRequired: true, transformFunction: null }, fieldInputs: { classPropertyName: "fieldInputs", publicName: "fieldInputs", isSignal: true, isRequired: false, transformFunction: null }, hidden: { classPropertyName: "hidden", publicName: "hidden", isSignal: true, isRequired: false, transformFunction: null } }, host: { properties: { "attr.slot": "slotAttr()", "class": "className()", "style.display": "isHidden() ? \"none\" : null" } }, ngImport: i0, template: `
+    @if (resolvedComponent(); as cmp) {
+      <ng-container *ngComponentOutlet="cmp; inputs: kindInputs()" />
+    }
+  `, isInline: true, dependencies: [{ kind: "directive", type: NgComponentOutlet, selector: "[ngComponentOutlet]", inputs: ["ngComponentOutlet", "ngComponentOutletInputs", "ngComponentOutletInjector", "ngComponentOutletEnvironmentInjector", "ngComponentOutletContent", "ngComponentOutletNgModule"], exportAs: ["ngComponentOutlet"] }], changeDetection: i0.ChangeDetectionStrategy.OnPush });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: DfAddonSlot, decorators: [{
+            type: Component,
+            args: [{
+                    selector: 'df-addon-slot',
+                    imports: [NgComponentOutlet],
+                    template: `
+    @if (resolvedComponent(); as cmp) {
+      <ng-container *ngComponentOutlet="cmp; inputs: kindInputs()" />
+    }
+  `,
+                    host: {
+                        '[attr.slot]': 'slotAttr()',
+                        '[class]': 'className()',
+                        '[style.display]': 'isHidden() ? "none" : null',
+                    },
+                    changeDetection: ChangeDetectionStrategy.OnPush,
+                }]
+        }], ctorParameters: () => [], propDecorators: { addon: [{ type: i0.Input, args: [{ isSignal: true, alias: "addon", required: true }] }], fieldInputs: [{ type: i0.Input, args: [{ isSignal: true, alias: "fieldInputs", required: false }] }], hidden: [{ type: i0.Input, args: [{ isSignal: true, alias: "hidden", required: false }] }] } });
+
+/**
+ * Pipe that handles dynamic text resolution with support for static strings,
+ * Observables, and Signals.
+ *
+ * Supports:
+ * - Static strings (pass-through)
+ * - Observables (subscribed internally)
+ * - Signals (converted to Observable using toObservable for reactivity)
+ *
+ * @example
+ * ```html
+ * <!-- Static string -->
+ * {{ 'Hello World' | dynamicText | async }}
+ *
+ * <!-- Observable -->
+ * {{ transloco.selectTranslate('key') | dynamicText | async }}
+ *
+ * <!-- Signal -->
+ * {{ myTextSignal | dynamicText | async }}
+ * ```
+ *
+ * @public
+ */
+class DynamicTextPipe {
+    injector = inject(Injector);
+    /**
+     * Transforms dynamic text input into a resolved string value
+     *
+     * @param value - The dynamic text value to resolve
+     * @returns The resolved string value as an Observable
+     */
+    transform(value) {
+        if (isObservable(value)) {
+            return value;
+        }
+        if (isSignal(value)) {
+            return toObservable(value, { injector: this.injector });
+        }
+        return of(value || '');
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: DynamicTextPipe, deps: [], target: i0.ɵɵFactoryTarget.Pipe });
+    static ɵpipe = i0.ɵɵngDeclarePipe({ minVersion: "14.0.0", version: "21.2.14", ngImport: i0, type: DynamicTextPipe, isStandalone: true, name: "dynamicText" });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: DynamicTextPipe, decorators: [{
+            type: Pipe,
+            args: [{
+                    name: 'dynamicText',
+                }]
+        }] });
+
+/**
+ * Renderer for the universal `text` addon kind.
+ *
+ * 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.
+ */
+class TextAddonComponent {
+    addon = input.required(...(ngDevMode ? [{ debugName: "addon" }] : /* istanbul ignore next */ []));
+    /** Accepted for contract uniformity — `NgComponentOutlet` setInput is strict; every kind must declare it. */
+    fieldInputs = input(...(ngDevMode ? [undefined, { debugName: "fieldInputs" }] : /* istanbul ignore next */ []));
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: TextAddonComponent, deps: [], target: i0.ɵɵFactoryTarget.Component });
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.1.0", version: "21.2.14", type: TextAddonComponent, isStandalone: true, selector: "df-text-addon", inputs: { addon: { classPropertyName: "addon", publicName: "addon", isSignal: true, isRequired: true, transformFunction: null }, fieldInputs: { classPropertyName: "fieldInputs", publicName: "fieldInputs", isSignal: true, isRequired: false, transformFunction: null } }, host: { properties: { "attr.aria-hidden": "\"true\"" } }, ngImport: i0, template: `<span>{{ addon().text | dynamicText | async }}</span>`, isInline: true, dependencies: [{ kind: "pipe", type: AsyncPipe, name: "async" }, { kind: "pipe", type: DynamicTextPipe, name: "dynamicText" }], changeDetection: i0.ChangeDetectionStrategy.OnPush });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: TextAddonComponent, decorators: [{
+            type: Component,
+            args: [{
+                    selector: 'df-text-addon',
+                    imports: [AsyncPipe, DynamicTextPipe],
+                    template: `<span>{{ addon().text | dynamicText | async }}</span>`,
+                    host: {
+                        '[attr.aria-hidden]': '"true"',
+                    },
+                    changeDetection: ChangeDetectionStrategy.OnPush,
+                }]
+        }], propDecorators: { addon: [{ type: i0.Input, args: [{ isSignal: true, alias: "addon", required: true }] }], fieldInputs: [{ type: i0.Input, args: [{ isSignal: true, alias: "fieldInputs", required: false }] }] } });
+
+var textAddon_component = /*#__PURE__*/Object.freeze({
+    __proto__: null,
+    TextAddonComponent: TextAddonComponent
+});
+
+/**
+ * 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.
+ */
+class TemplateAddonComponent {
+    templates = inject(DF_FIELD_TEMPLATES, { optional: true });
+    logger = inject(DynamicFormLogger);
+    addon = input.required(...(ngDevMode ? [{ debugName: "addon" }] : /* istanbul ignore next */ []));
+    /** Forwarded by `df-addon-slot`; surfaced to the template as its implicit `$implicit` context. */
+    fieldInputs = input(...(ngDevMode ? [undefined, { debugName: "fieldInputs" }] : /* istanbul ignore next */ []));
+    // Pure computed: pure lookup, no side effects. Unresolved → null; the
+    // `@if` in the template skips the outlet and renders nothing.
+    template = computed(() => {
+        const map = this.templates?.();
+        const key = this.addon().templateKey;
+        return map?.get(key) ?? null;
+    }, ...(ngDevMode ? [{ debugName: "template" }] : /* istanbul ignore next */ []));
+    /** Implicit context payload — template authors bind via `let-fi`. */
+    outletContext = computed(() => ({ $implicit: this.fieldInputs() }), ...(ngDevMode ? [{ debugName: "outletContext" }] : /* istanbul ignore next */ []));
+    constructor() {
+        // Logging side effect lives in an effect, not the computed — keeps
+        // the computed pure so signal-graph evaluations don't duplicate warnings.
+        explicitEffect([this.template, this.addon], ([tpl, addon]) => {
+            if (!tpl) {
+                this.logger.warn(`Template addon: no <ng-template dfTemplate="${addon.templateKey}"> found. Did you project it as a child of <df-dynamic-form>?`);
+            }
+        });
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: TemplateAddonComponent, deps: [], target: i0.ɵɵFactoryTarget.Component });
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "21.2.14", type: TemplateAddonComponent, isStandalone: true, selector: "df-template-addon", inputs: { addon: { classPropertyName: "addon", publicName: "addon", isSignal: true, isRequired: true, transformFunction: null }, fieldInputs: { classPropertyName: "fieldInputs", publicName: "fieldInputs", isSignal: true, isRequired: false, transformFunction: null } }, ngImport: i0, template: `
+    @if (template(); as tpl) {
+      <ng-container *ngTemplateOutlet="tpl; context: outletContext()" />
+    }
+  `, isInline: true, dependencies: [{ kind: "directive", type: NgTemplateOutlet, selector: "[ngTemplateOutlet]", inputs: ["ngTemplateOutletContext", "ngTemplateOutlet", "ngTemplateOutletInjector"] }], changeDetection: i0.ChangeDetectionStrategy.OnPush });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: TemplateAddonComponent, decorators: [{
+            type: Component,
+            args: [{
+                    selector: 'df-template-addon',
+                    imports: [NgTemplateOutlet],
+                    template: `
+    @if (template(); as tpl) {
+      <ng-container *ngTemplateOutlet="tpl; context: outletContext()" />
+    }
+  `,
+                    changeDetection: ChangeDetectionStrategy.OnPush,
+                }]
+        }], ctorParameters: () => [], propDecorators: { addon: [{ type: i0.Input, args: [{ isSignal: true, alias: "addon", required: true }] }], fieldInputs: [{ type: i0.Input, args: [{ isSignal: true, alias: "fieldInputs", required: false }] }] } });
+
+var templateAddon_component = /*#__PURE__*/Object.freeze({
+    __proto__: null,
+    TemplateAddonComponent: TemplateAddonComponent
+});
+
+/**
+ * Renderer for the universal `component` addon kind.
+ *
+ * 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.
+ *
+ * @codeOnly The `component` loader is a function; this kind is dropped in
+ * lenient validation when the config originated from JSON.
+ */
+class ComponentAddonComponent {
+    logger = inject(DynamicFormLogger);
+    addon = input.required(...(ngDevMode ? [{ debugName: "addon" }] : /* istanbul ignore next */ []));
+    /** Accepted for contract uniformity — `NgComponentOutlet` setInput is strict; every kind must declare it. */
+    fieldInputs = input(...(ngDevMode ? [undefined, { debugName: "fieldInputs" }] : /* istanbul ignore next */ []));
+    inputs = computed(() => (this.addon().inputs ?? {}), ...(ngDevMode ? [{ debugName: "inputs" }] : /* istanbul ignore next */ []));
+    /**
+     * 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.
+     */
+    asyncLoaded = signal(undefined, ...(ngDevMode ? [{ debugName: "asyncLoaded" }] : /* istanbul ignore next */ []));
+    resolvedComponent = computed(() => {
+        const current = this.addon();
+        const loaded = this.asyncLoaded();
+        return loaded?.addon === current ? loaded.component : undefined;
+    }, ...(ngDevMode ? [{ debugName: "resolvedComponent" }] : /* istanbul ignore next */ []));
+    constructor() {
+        explicitEffect([this.addon], ([addon]) => {
+            Promise.resolve(addon.component())
+                .then((mod) => {
+                const component = resolveDefaultExport(mod);
+                if (component)
+                    this.asyncLoaded.set({ addon, component });
+            })
+                .catch((error) => {
+                this.logger.warn(`Failed to load component addon (slot: '${addon.slot}'): ${error instanceof Error ? error.message : String(error)}`);
+            });
+        });
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: ComponentAddonComponent, deps: [], target: i0.ɵɵFactoryTarget.Component });
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "21.2.14", type: ComponentAddonComponent, isStandalone: true, selector: "df-component-addon", inputs: { addon: { classPropertyName: "addon", publicName: "addon", isSignal: true, isRequired: true, transformFunction: null }, fieldInputs: { classPropertyName: "fieldInputs", publicName: "fieldInputs", isSignal: true, isRequired: false, transformFunction: null } }, ngImport: i0, template: `
+    @if (resolvedComponent(); as cmp) {
+      <ng-container *ngComponentOutlet="cmp; inputs: inputs()" />
+    }
+  `, isInline: true, dependencies: [{ kind: "directive", type: NgComponentOutlet, selector: "[ngComponentOutlet]", inputs: ["ngComponentOutlet", "ngComponentOutletInputs", "ngComponentOutletInjector", "ngComponentOutletEnvironmentInjector", "ngComponentOutletContent", "ngComponentOutletNgModule"], exportAs: ["ngComponentOutlet"] }], changeDetection: i0.ChangeDetectionStrategy.OnPush });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: ComponentAddonComponent, decorators: [{
+            type: Component,
+            args: [{
+                    selector: 'df-component-addon',
+                    imports: [NgComponentOutlet],
+                    template: `
+    @if (resolvedComponent(); as cmp) {
+      <ng-container *ngComponentOutlet="cmp; inputs: inputs()" />
+    }
+  `,
+                    changeDetection: ChangeDetectionStrategy.OnPush,
+                }]
+        }], ctorParameters: () => [], propDecorators: { addon: [{ type: i0.Input, args: [{ isSignal: true, alias: "addon", required: true }] }], fieldInputs: [{ type: i0.Input, args: [{ isSignal: true, alias: "fieldInputs", required: false }] }] } });
+
+var componentAddon_component = /*#__PURE__*/Object.freeze({
+    __proto__: null,
+    ComponentAddonComponent: ComponentAddonComponent
+});
+
+/**
+ * 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.
+ */
+async function runPresetAction(preset, ctx, collaborators, adapterLabel, fieldLabel) {
+    // Guard against orphan dispatches — none of the built-in presets do
+    // anything useful without a host field, except `copy` and `paste` which
+    // only need the clipboard API. The canonical discriminant per the
+    // `AddonActionContext` discriminated union is `ctx.form` — non-null on
+    // the field-bound variant, null on the orphan variant. `field.key` was
+    // unreliable for nested-array scenarios where keys can legitimately be
+    // empty strings.
+    if (ctx.form === null && preset !== 'copy' && preset !== 'paste') {
+        collaborators.logger.warn(`preset '${String(preset)}' fired without a host field context — ignoring.`);
+        return;
+    }
+    switch (preset) {
+        case 'clear': {
+            // Preserve type semantics: strings clear to `''` (browser-friendly for
+            // input.value), everything else clears to `undefined` (numeric / object
+            // / date fields would otherwise become a string and break their type).
+            const next = typeof ctx.value === 'string' ? '' : undefined;
+            collaborators.fieldValueSetter?.(next);
+            return;
+        }
+        case 'reset': {
+            const defaultValue = collaborators.fieldDefaultValueGetter?.();
+            collaborators.fieldValueSetter?.(defaultValue !== undefined ? defaultValue : typeof ctx.value === 'string' ? '' : undefined);
+            return;
+        }
+        case 'paste': {
+            if (typeof navigator === 'undefined' || !navigator.clipboard) {
+                collaborators.logger.warn(`preset 'paste' requires a browser clipboard API (not available in this environment).`);
+                return;
+            }
+            try {
+                const text = await navigator.clipboard.readText();
+                collaborators.fieldValueSetter?.(text);
+            }
+            catch (error) {
+                collaborators.logger.warn(`preset 'paste' clipboard read failed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            return;
+        }
+        case 'copy': {
+            if (typeof navigator === 'undefined' || !navigator.clipboard) {
+                collaborators.logger.warn(`preset 'copy' requires a browser clipboard API (not available in this environment).`);
+                return;
+            }
+            try {
+                // Explicit null check — `String(null) === 'null'` would write the
+                // literal string "null" to the clipboard.
+                const v = ctx.value;
+                await navigator.clipboard.writeText(v == null ? '' : String(v));
+            }
+            catch (error) {
+                collaborators.logger.warn(`preset 'copy' clipboard write failed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            return;
+        }
+        case 'toggle-password-visibility': {
+            const override = collaborators.typeOverride;
+            if (!override) {
+                collaborators.logger.warn(`preset 'toggle-password-visibility' has no effect outside a '${fieldLabel}' field.`);
+                return;
+            }
+            // Refuse to flip non-password inputs. Re-check on EVERY dispatch (not
+            // just when override is undefined) because `props().type` can change
+            // reactively after the first toggle — e.g., 'password' → 'email'. Once
+            // the override is touched, only the override is canonical for the
+            // current visible/hidden state; the baseline still gates whether
+            // toggling makes semantic sense for this field.
+            const baseline = collaborators.baselineType?.();
+            if (baseline !== undefined && baseline !== 'password') {
+                collaborators.logger.warn(`preset 'toggle-password-visibility' refused: host '${fieldLabel}' has type '${baseline}', not 'password'.`);
+                return;
+            }
+            const current = override();
+            override.set(current === 'text' ? 'password' : 'text');
+            return;
+        }
+        default:
+            collaborators.logger.warn(`preset '${String(preset)}' is not implemented in the ${adapterLabel} adapter.`);
+    }
+}
+
+/**
+ * Walk `FIELD_REGISTRY` and return every field type that opted into addons
+ * (i.e., declared `addons` on its `FieldTypeDefinition`).
+ *
+ * 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
+ * @Component({ ... })
+ * class FormBuilder {
+ *   protected readonly addonable = injectFieldsSupportingAddons();
+ *
+ *   constructor() {
+ *     // -> [{ name: 'prime-input', slots: ['prefix', 'suffix'], allowedKinds: [...] }, ...]
+ *   }
+ * }
+ * ```
+ */
+function injectFieldsSupportingAddons() {
+    const registry = inject(FIELD_REGISTRY);
+    const entries = [];
+    for (const [name, def] of registry.entries()) {
+        if (def.addons === undefined)
+            continue;
+        entries.push({ name, slots: def.addons.slots, allowedKinds: def.addons.allowedKinds });
+    }
+    return entries;
+}
+
+/**
+ * Register a custom addon kind with the form.
+ *
+ * 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(),
+ *   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');
+ *       }
+ *     },
+ *   }),
+ * );
+ * ```
+ *
+ * Multiple `withCustomAddon(...)` calls are supported; later registrations
+ * for the same kind override earlier ones (with a warning logged).
+ */
+function withCustomAddon(definition) {
+    return createFeature('addons', [
+        {
+            provide: ADDON_KIND_DEFINITIONS,
+            useValue: definition,
+            multi: true,
+        },
+    ]);
+}
+
+/**
+ * Register named action handlers reachable via JSON-driven addon configs.
+ *
+ * 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:
+ *
+ * ```typescript
+ * 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);
+ * ```
+ *
+ * Multiple `provideAddonActions(...)` calls are merged; later names override
+ * earlier ones for the same key.
+ */
+function provideAddonActions(handlers) {
+    return createFeature('addon-actions', [
+        {
+            provide: ADDON_ACTION_HANDLERS,
+            useValue: handlers,
+            multi: true,
+        },
+    ]);
+}
+
+/**
+ * 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
+ * @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;
+ *   };
+ * }
+ * ```
+ */
+function sanitizeFormConfig(config, options = {}) {
+    const fieldRegistry = inject(FIELD_REGISTRY);
+    const kindRegistry = inject(ADDON_KIND_REGISTRY);
+    const source = options.source ?? 'inline';
+    const { fields, warnings } = walkAndValidateAddons((config.fields ?? []), fieldRegistry, kindRegistry, source);
+    return {
+        sanitized: { ...config, fields: fields },
+        warnings,
+    };
+}
+/**
+ * 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.
+ */
+function logAddonWarnings(warnings, logger) {
+    for (const w of warnings) {
+        if (logger) {
+            logger.warn(formatAddonWarning(w));
+        }
+        else {
+            console.warn('[Dynamic Forms]', formatAddonWarning(w));
+        }
+    }
+}
+/**
+ * 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.
+ */
+function sanitizeFormConfigPure(config, fieldRegistry, kindRegistry, options = {}) {
+    const source = options.source ?? 'inline';
+    const { fields, warnings } = walkAndValidateAddons((config.fields ?? []), fieldRegistry, kindRegistry, source);
+    return { sanitized: { ...config, fields: fields }, warnings };
+}
+
+function isValueField(field) {
+    // `nullable: true` without an explicit `value` is still a value-bearing declaration:
+    // the field resolves to `null` at runtime. Treating it as a value field keeps
+    // downstream narrowing consistent with getFieldDefaultValue's behavior.
+    return 'value' in field || 'nullable' in field;
+}
+
+function isCheckedField(field) {
+    return field.type === 'checkbox';
+}
+
+/**
+ * Builder for array manipulation events.
+ *
+ * Provides a fluent, discoverable API for array operations.
+ * Type `arrayEvent('key').` in your IDE to see all available operations.
+ *
+ * **BREAKING CHANGE**: Template is now required for add operations.
+ *
+ * Supports both primitive and object array items:
+ * - Primitive: Pass a single field definition → extracts field value directly
+ * - Object: Pass an array of field definitions → merges fields into object
+ *
+ * @example
+ * ```typescript
+ * import { arrayEvent } from '@ng-forge/dynamic-forms';
+ *
+ * // Object item: append { name, email } object
+ * eventBus.dispatch(arrayEvent('contacts').append([
+ *   { key: 'name', type: 'input', label: 'Name' },
+ *   { key: 'email', type: 'input', label: 'Email' }
+ * ]));
+ *
+ * // Primitive item: append single value
+ * eventBus.dispatch(arrayEvent('tags').append(
+ *   { key: 'tag', type: 'input', label: 'Tag' }
+ * ));
+ *
+ * // Removing items (no template needed)
  * eventBus.dispatch(arrayEvent('contacts').pop());      // Remove last
  * eventBus.dispatch(arrayEvent('contacts').shift());    // Remove first
  * eventBus.dispatch(arrayEvent('contacts').removeAt(2)); // Remove at index
@@ -16452,56 +18036,6 @@ function applyMetaToElement(element, meta, previouslyApplied) {
     return newApplied;
 }
 
-/**
- * Pipe that handles dynamic text resolution with support for static strings,
- * Observables, and Signals.
- *
- * Supports:
- * - Static strings (pass-through)
- * - Observables (subscribed internally)
- * - Signals (converted to Observable using toObservable for reactivity)
- *
- * @example
- * ```html
- * <!-- Static string -->
- * {{ 'Hello World' | dynamicText | async }}
- *
- * <!-- Observable -->
- * {{ transloco.selectTranslate('key') | dynamicText | async }}
- *
- * <!-- Signal -->
- * {{ myTextSignal | dynamicText | async }}
- * ```
- *
- * @public
- */
-class DynamicTextPipe {
-    injector = inject(Injector);
-    /**
-     * Transforms dynamic text input into a resolved string value
-     *
-     * @param value - The dynamic text value to resolve
-     * @returns The resolved string value as an Observable
-     */
-    transform(value) {
-        if (isObservable(value)) {
-            return value;
-        }
-        if (isSignal(value)) {
-            return toObservable(value, { injector: this.injector });
-        }
-        return of(value || '');
-    }
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.8", ngImport: i0, type: DynamicTextPipe, deps: [], target: i0.ɵɵFactoryTarget.Pipe });
-    static ɵpipe = i0.ɵɵngDeclarePipe({ minVersion: "14.0.0", version: "21.2.8", ngImport: i0, type: DynamicTextPipe, isStandalone: true, name: "dynamicText" });
-}
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.8", ngImport: i0, type: DynamicTextPipe, decorators: [{
-            type: Pipe,
-            args: [{
-                    name: 'dynamicText',
-                }]
-        }] });
-
 /**
  * Interpolates {{param}} placeholders in message with error values
  *
@@ -16633,5 +18167,5 @@ function extractErrorParams(error) {
  * Generated bundle index. Do not edit.
  */
 
-export { ShiftArrayItemEvent as $, ARRAY_CONTEXT as A, BUILT_IN_FIELDS as B, CONTAINER_FIELD_PROCESSORS as C, DynamicFormLogger as D, EventBus as E, FIELD_SIGNAL_CONTEXT as F, GROUP_CONTEXT as G, DEFAULT_VALIDATION_MESSAGES as H, DynamicForm as I, DynamicFormError as J, EventDispatcher as K, FIELD_REGISTRY as L, FORM_OPTIONS as M, FormClearEvent as N, FormResetEvent as O, INITIALIZATION_TIMEOUT_MS as P, InsertArrayItemEvent as Q, RootFormRegistryService as R, MoveArrayItemEvent as S, NextPageEvent as T, NoopLogger as U, PageChangeEvent as V, WRAPPER_AUTO_ASSOCIATIONS as W, PopArrayItemEvent as X, PrependArrayItemEvent as Y, PreviousPageEvent as Z, RemoveAtIndexEvent as _, DEFAULT_WRAPPERS as a, SubmitEvent as a0, WRAPPER_REGISTRY as a1, applyMetaToElement as a2, applyValidator as a3, applyValidators as a4, arrayEvent as a5, arrayFieldMapper as a6, baseFieldMapper as a7, buildBaseInputs as a8, containerFieldMapper as a9, provideDynamicForm as aA, resolveNextButtonDisabled as aB, resolveNonFieldDisabled as aC, resolveNonFieldHidden as aD, resolveSubmitButtonDisabled as aE, resolveTokens as aF, rowFieldMapper as aG, textFieldMapper as aH, toReadonlyFieldTree as aI, withEventFormValue as aJ, withLoggerConfig as aK, withPreviousValue as aL, withValidationExecutionDefaults as aM, withValueExclusionDefaults as aN, wrapperProps as aO, createField as aa, createWrappers as ab, evaluateNonFieldDisabled as ac, evaluateNonFieldHidden as ad, field as ae, formConfig as af, getArrayLength as ag, groupFieldMapper as ah, hasFormValue as ai, interpolateParams as aj, isArrayField as ak, isCheckedField as al, isContainerField as am, isContainerTypedField as an, isDisplayOnlyField as ao, isFormStateCondition as ap, isLeafField as aq, isPageField as ar, isRowField as as, isSimplifiedArrayField as at, isValueBearingField as au, isValueField as av, isWrapperTypeDefinition as aw, isWrappersBundle as ax, omit as ay, pageFieldMapper as az, isSameWrapperChain as b, createFieldResolutionPipe as c, derivedFromDeferred as d, createWrapperChainController as e, DfFieldOutlet as f, isEqual as g, createSchemaFromFields as h, injectFieldRegistry as i, createRenderReadySignal as j, ARRAY_TEMPLATE_REGISTRY as k, ARRAY_ITEM_ID_GENERATOR as l, mapFieldToInputs as m, getNormalizedArrayMetadata as n, getFieldValueHandling as o, getFieldDefaultValue as p, isGroupField as q, resolveWrappers as r, createArrayItemIdGenerator as s, ComponentInitializedEvent as t, DynamicTextPipe as u, validatePageNesting as v, dynamicTextToObservable as w, AppendArrayItemEvent as x, ConsoleLogger as y, DEFAULT_PROPS as z };
-//# sourceMappingURL=ng-forge-dynamic-forms-ng-forge-dynamic-forms-o3rJX4vG.mjs.map
+export { arrayFieldMapper as $, ADDON_ACTION_HANDLERS as A, BUILT_IN_FIELDS as B, CONTAINER_FIELD_PROCESSORS as C, DEFAULT_PROPS as D, EventBus as E, FIELD_REGISTRY as F, GROUP_CONTEXT as G, NoopLogger as H, INITIALIZATION_TIMEOUT_MS as I, PopArrayItemEvent as J, PrependArrayItemEvent as K, PreviousPageEvent as L, MoveArrayItemEvent as M, NextPageEvent as N, RootFormRegistryService as O, PageChangeEvent as P, SubmitEvent as Q, RemoveAtIndexEvent as R, ShiftArrayItemEvent as S, TemplateAddonComponent as T, TextAddonComponent as U, WRAPPER_REGISTRY as V, WRAPPER_AUTO_ASSOCIATIONS as W, applyMetaToElement as X, applyValidator as Y, applyValidators as Z, arrayEvent as _, ADDON_ACTION_REGISTRY as a, textFieldMapper as a$, baseFieldMapper as a0, buildBaseInputs as a1, containerFieldMapper as a2, createField as a3, createFieldResolutionPipe as a4, createHiddenSignal as a5, createRenderReadySignal as a6, createSchemaFromFields as a7, createWrapperChainController as a8, createWrappers as a9, isGroupField as aA, isLeafField as aB, isPageField as aC, isRowField as aD, isSameWrapperChain as aE, isSimplifiedArrayField as aF, isValueBearingField as aG, isValueField as aH, isWrapperTypeDefinition as aI, isWrappersBundle as aJ, logAddonWarnings as aK, mapFieldToInputs as aL, omit as aM, pageFieldMapper as aN, provideAddonActions as aO, provideDynamicForm as aP, resolveDynamicValue as aQ, resolveNextButtonDisabled as aR, resolveNonFieldDisabled as aS, resolveNonFieldHidden as aT, resolveSubmitButtonDisabled as aU, resolveTokens as aV, resolveWrappers as aW, rowFieldMapper as aX, runPresetAction as aY, sanitizeFormConfig as aZ, sanitizeFormConfigPure as a_, derivedFromDeferred as aa, dynamicTextToObservable as ab, evaluateNonFieldDisabled as ac, evaluateNonFieldHidden as ad, field as ae, formConfig as af, formatAddonWarning as ag, getArrayLength as ah, getFieldDefaultValue as ai, getFieldValueHandling as aj, getNormalizedArrayMetadata as ak, groupFieldMapper as al, hasFormValue as am, injectAddonKindRegistry as an, injectFieldRegistry as ao, injectFieldSignalContext as ap, injectFieldsSupportingAddons as aq, interpolateParams as ar, isArrayField as as, isCheckedField as at, isContainerField as au, isContainerTypedField as av, isDisplayOnlyField as aw, isEqual as ax, isFieldBoundContext as ay, isFormStateCondition as az, ADDON_KIND_COMPONENT_CACHE as b, toReadonlyFieldTree as b0, validateFieldAddons as b1, validatePageNesting as b2, walkAndValidateAddons as b3, withCustomAddon as b4, withEventFormValue as b5, withLegacyStatusClasses as b6, withLoggerConfig as b7, withPreviousValue as b8, withValidationExecutionDefaults as b9, withValueExclusionDefaults as ba, wrapperProps as bb, writeToFieldValue as bc, ADDON_KIND_DEFINITIONS as c, ADDON_KIND_REGISTRY as d, ARRAY_CONTEXT as e, AppendArrayItemEvent as f, ArrayItemRegistryService as g, ComponentAddonComponent as h, ComponentInitializedEvent as i, ConsoleLogger as j, DEFAULT_VALIDATION_MESSAGES as k, DEFAULT_WRAPPERS as l, DF_FIELD_TEMPLATES as m, DfAddonSlot as n, DfFieldOutlet as o, DfTemplate as p, DynamicForm as q, DynamicFormError as r, DynamicFormLogger as s, DynamicTextPipe as t, EventDispatcher as u, FIELD_SIGNAL_CONTEXT as v, FORM_OPTIONS as w, FormClearEvent as x, FormResetEvent as y, InsertArrayItemEvent as z };
+//# sourceMappingURL=ng-forge-dynamic-forms-ng-forge-dynamic-forms-BbgkzKuI.mjs.map