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

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

@@ -1,32 +1,52 @@
 import * as rxjs from 'rxjs';
-import * as _angular_core from '@angular/core';
-import { Type, Injector, Signal, EnvironmentInjector, WritableSignal, Provider, EnvironmentProviders, TemplateRef } from '@angular/core';
-import * as _ng_forge_dynamic_forms_internal from '@ng-forge/dynamic-forms/internal';
-import { FieldDef, FormEvent, RegisteredFieldTypes, InferFormModel, FormConfig, FormOptions, EventBus, LazyComponentLoader, WrapperTypeDefinition, FieldTypeDefinition, InferFormValue as InferFormValue$1, DerivationLogLevel, Logger, ValueExclusionConfig, ValidationExecutionConfig, TextAddon, WrapperFieldInputs, TemplateAddon, ComponentAddon, BaseAddon, AddonTypeDefinition, AddonActionHandler, ArrayItemDefinition } from '@ng-forge/dynamic-forms/internal';
-export { AddonActionContext, AddonActionPreset, AddonSlot, AddonTypeDefinition, AnyAddon, ArrayAllowedChildren, ArrayButtonConfig, ArrayField, ArrayItemTemplate, AsyncCondition, AsyncConditionFunction, AsyncCustomValidator, AsyncDerivationFunction, AsyncValidatorConfig, AvailableFieldTypes, BaseAddon, BaseCheckedField, BaseValidatorConfig, BaseValueField, BuiltInValidatorConfig, CheckedFieldComponent, CommonAddonActionPreset, CommonAddonSlot, ComponentAddon, ConditionalExpression, ContainerAllowedChildren, ContainerField, ContainerFieldTypes, CssWrapper, CustomFnConfig, CustomFunction, CustomValidator, CustomValidatorConfig, DF_FIELD_TEMPLATES, DeclarativeHttpValidatorConfig, DynamicFormActionRegistry, DynamicFormAddonActionPresetRegistry, DynamicFormAddonRegistry, DynamicFormAddonSlotRegistry, DynamicFormError, DynamicFormFieldRegistry, DynamicFormLogger, DynamicText, DynamicValue, EvaluationContext, ExtractField, FieldBoundAddonActionContext, FieldComponent, FieldDef, FieldMeta, FieldOption, FieldPathAccess, FieldRegistryContainers, FieldRegistryLeaves, FieldRegistryWrappers, FieldWithValidation, FieldWrapper, FormConfig, FormEvent, FormEventConstructor, FormMode, FormModeDetectionResult, FormOptions, FormStateCondition, GroupAllowedChildren, GroupField, HiddenField, HiddenScalar, HiddenValue, HttpCondition, HttpCustomValidator, HttpRequestConfig, HttpValidationResponseMapping, InferFormValue, LeafFieldTypes, Logger, LogicConfig, NarrowField, NarrowFields, NextButtonOptions, NoopLogger, OrphanAddonActionContext, PageAllowedChildren, PageField, RegisteredActionRef, RegisteredFieldTypes, ResolvedValidationExecutionConfig, ResolvedValueExclusionConfig, RowAllowedChildren, RowField, SchemaApplicationConfig, SchemaDefinition, SimplifiedArrayField, StateLogicConfig, SubmissionActionResult, SubmissionConfig, SubmitButtonOptions, TemplateAddon, TextAddon, TextElementType, TextField, TextProps, TokenContext, ValidationError, ValidationExecutionConfig, ValidationMessage, ValidationMessageResolver, ValidationMessages, ValidatorConfig, ValueExclusionConfig, ValueFieldComponent, ValueType, WithInputSignals, WrapperConfig, WrapperTypeDefinition, hasFormValue, isArrayField, isContainerField, isDisplayOnlyField, isFieldBoundContext, isFormStateCondition, isGroupField, isHiddenField, isLeafField, isPageField, isRowField, isSimplifiedArrayField, isValueBearingField, isWrapperTypeDefinition, resolveDynamicValue } from '@ng-forge/dynamic-forms/internal';
 import * as _angular_forms_signals from '@angular/forms/signals';
 import { FieldTree } from '@angular/forms/signals';
-import * as _angular_forms from '@angular/forms';
+import * as _ng_forge_dynamic_forms_internal from '@ng-forge/dynamic-forms/internal';
+import { FormEvent, FieldDef, RegisteredFieldTypes, InferFormModel, FormConfig, FormOptions, EventBus, LazyComponentLoader, WrapperTypeDefinition, FieldTypeDefinition, InferFormValue as InferFormValue$1, DerivationLogLevel, Logger, ValueExclusionConfig, ValidationExecutionConfig, TextAddon, WrapperFieldInputs, TemplateAddon, ComponentAddon, BaseAddon, AddonTypeDefinition, AddonActionHandler, ArrayItemDefinition } from '@ng-forge/dynamic-forms/internal';
+export { AddonActionContext, AddonActionPreset, AddonSlot, AddonTypeDefinition, AnyAddon, ArrayAllowedChildren, ArrayButtonConfig, ArrayField, ArrayItemTemplate, AsyncCondition, AsyncConditionFunction, AsyncCustomValidator, AsyncDerivationFunction, AsyncValidatorConfig, AvailableFieldTypes, BaseAddon, BaseCheckedField, BaseValidatorConfig, BaseValueField, BuiltInValidatorConfig, CheckedFieldComponent, CommonAddonActionPreset, CommonAddonSlot, ComponentAddon, ConditionalExpression, ContainerAllowedChildren, ContainerField, ContainerFieldTypes, CssWrapper, CustomFnConfig, CustomFunction, CustomValidator, CustomValidatorConfig, DF_FIELD_TEMPLATES, DeclarativeHttpValidatorConfig, DynamicFormActionRegistry, DynamicFormAddonActionPresetRegistry, DynamicFormAddonRegistry, DynamicFormAddonSlotRegistry, DynamicFormError, DynamicFormFieldRegistry, DynamicFormLogger, DynamicText, DynamicValue, EvaluationContext, ExtractField, FieldBoundAddonActionContext, FieldComponent, FieldDef, FieldMeta, FieldOption, FieldPathAccess, FieldRegistryContainers, FieldRegistryLeaves, FieldRegistryWrappers, FieldWithValidation, FieldWrapper, FormConfig, FormEvent, FormEventConstructor, FormMode, FormModeDetectionResult, FormOptions, FormStateCondition, GroupAllowedChildren, GroupField, HiddenField, HiddenScalar, HiddenValue, HttpCondition, HttpCustomValidator, HttpRequestConfig, HttpValidationResponseMapping, InferFormValue, InitialPageConfig, LeafFieldTypes, Logger, LogicConfig, NarrowField, NarrowFields, NextButtonOptions, NoopLogger, OrphanAddonActionContext, PageAllowedChildren, PageField, RegisteredActionRef, RegisteredFieldTypes, ResolvedValidationExecutionConfig, ResolvedValueExclusionConfig, RowAllowedChildren, RowErrorSpec, RowField, SchemaApplicationConfig, SchemaDefinition, SimplifiedArrayField, StateLogicConfig, SubmissionActionResult, SubmissionConfig, SubmitButtonOptions, TemplateAddon, TextAddon, TextElementType, TextField, TextProps, TokenContext, ValidationError, ValidationExecutionConfig, ValidationMessage, ValidationMessageResolver, ValidationMessages, ValidatorConfig, ValueExclusionConfig, ValueFieldComponent, ValueType, WebMcpToolOptions, WithInputSignals, WrapperConfig, WrapperTypeDefinition, hasFormValue, isArrayField, isContainerField, isDisplayOnlyField, isFieldBoundContext, isFormStateCondition, isGroupField, isHiddenField, isLeafField, isPageField, isRowField, isSimplifiedArrayField, isValueBearingField, isWrapperTypeDefinition, resolveDynamicValue, rowError } from '@ng-forge/dynamic-forms/internal';
+import * as _angular_core from '@angular/core';
+import { Type, Injector, Signal, EnvironmentInjector, WritableSignal, Provider, EnvironmentProviders, TemplateRef } from '@angular/core';
 import * as _ng_forge_dynamic_forms from '@ng-forge/dynamic-forms';
 
-/** Resolved field ready for rendering with ngComponentOutlet / DfFieldOutlet. */
-interface ResolvedField {
-    key: string;
-    /** The original field definition (used by DfFieldOutlet to resolve wrappers). */
-    fieldDef: FieldDef<unknown>;
-    component: Type<unknown>;
-    injector: Injector;
-    inputs: Signal<Record<string, unknown>>;
-    renderReady: Signal<boolean>;
-    /**
-     * Whether the field is currently hidden. Sourced from the FieldTree's
-     * `state.hidden()` for value-bearing fields (set by Angular Signal Forms in
-     * response to `hidden(path, …)` calls), or from the mapper's explicit
-     * `hidden` input for non-value fields (button, text, container, …). Consumers
-     * must `@if (!field.hidden())` around `*dfFieldOutlet` so hidden fields are
-     * removed from the DOM — Angular Signal Forms warns (NG01916) otherwise.
-     */
-    hidden: Signal<boolean>;
+/**
+ * Global default configuration for progressive field mounting ("field
+ * windowing"): fields beyond `eager` render as `@defer (on viewport)`
+ * placeholders instead of mounting immediately, and mount only once scrolled
+ * near/into view.
+ *
+ * @internal
+ */
+interface FieldWindowingConfig {
+    /** Whether field windowing is active. */
+    readonly enabled: boolean;
+    /** Number of leading fields mounted eagerly (not windowed). */
+    readonly eager: number;
+    /** CSS `min-height` reserved for each unmounted field's placeholder. */
+    readonly placeholderHeight: string;
+    /** Parking: hold scrolled-away fields out of change detection, DOM intact. */
+    readonly park: FieldParkingConfig;
+}
+/**
+ * Parking config. `@defer (on viewport)` only ever mounts — it never unmounts —
+ * so without parking a form that has been scrolled through ends up with every
+ * field live again, and the windowing win is handed back for the rest of the
+ * session. Parking closes that: a field that scrolls away leaves change
+ * detection but keeps its DOM, so it stays findable, autofillable and
+ * reachable by assistive tech.
+ *
+ * Off in this default, on whenever `withFieldWindowing()` is used. Parking
+ * suspends model → DOM updates for a scrolled-away field until it returns, so
+ * it is a rendering behaviour change and is not something a form should get
+ * without asking. It exists to bound what windowing leaves mounted, which is
+ * why enabling windowing enables it too.
+ *
+ * @internal
+ */
+interface FieldParkingConfig {
+    /** Whether scrolled-away fields are held out of change detection. */
+    readonly enabled: boolean;
+    /** `IntersectionObserver` rootMargin — how far outside the viewport stays live. */
+    readonly margin: string;
 }
 
 /** Error from async field component loading. */
@@ -64,24 +84,58 @@ declare class PageChangeEvent implements FormEvent {
     previousPageIndex?: number | undefined);
 }
 
-/** State interface for the page orchestrator */
-interface PageOrchestratorState {
+/** Navigation state of a paged form, as emitted by `PagerStateEvent`. */
+interface PagerState {
     /** Current page index (0-based) */
     currentPageIndex: number;
     /** Total number of pages */
     totalPages: number;
-    /** Whether the current page is the first page */
+    /** Whether the current page is the first visible page */
     isFirstPage: boolean;
-    /** Whether the current page is the last page */
+    /** Whether the current page is the last visible page */
     isLastPage: boolean;
-    /** Whether navigation is currently disabled */
-    navigationDisabled: boolean;
 }
 
-declare class PageNavigationStateChangeEvent implements FormEvent {
-    state: PageOrchestratorState;
-    type: "page-navigation-state-change";
-    constructor(state: PageOrchestratorState);
+/**
+ * Event emitted whenever the pager state of a paged form changes.
+ *
+ * Unlike `PageChangeEvent`, which fires only when the active page changed, this
+ * fires on any change to the derived state — including when `isFirstPage` /
+ * `isLastPage` flip because a page's `hidden` logic toggled and the set of
+ * visible pages shifted, with the active page never moving.
+ */
+declare class PagerStateEvent implements FormEvent {
+    state: PagerState;
+    readonly type: "pager-state";
+    constructor(state: PagerState);
+}
+
+/** Emitted after the active page and all of its visible fields have rendered. */
+declare class ActivePageInitializedEvent implements FormEvent {
+    readonly pageIndex: number;
+    readonly pageKey: string;
+    readonly type: "active-page-initialized";
+    constructor(pageIndex: number, pageKey: string);
+}
+
+/** Resolved field ready for rendering with ngComponentOutlet / DfFieldOutlet. */
+interface ResolvedField {
+    key: string;
+    /** The original field definition (used by DfFieldOutlet to resolve wrappers). */
+    fieldDef: FieldDef<unknown>;
+    component: Type<unknown>;
+    injector: Injector;
+    inputs: Signal<Record<string, unknown>>;
+    renderReady: Signal<boolean>;
+    /**
+     * Whether the field is currently hidden. Sourced from the FieldTree's
+     * `state.hidden()` for value-bearing fields (set by Angular Signal Forms in
+     * response to `hidden(path, …)` calls), or from the mapper's explicit
+     * `hidden` input for non-value fields (button, text, container, …). Consumers
+     * must `@if (!field.hidden())` around `*dfFieldOutlet` so hidden fields are
+     * removed from the DOM — Angular Signal Forms warns (NG01916) otherwise.
+     */
+    hidden: Signal<boolean>;
 }
 
 /**
@@ -135,6 +189,7 @@ declare class DynamicForm<TFields extends RegisteredFieldTypes[] = RegisteredFie
     private logger;
     private dispatcher;
     private templateRegistry;
+    private globalFieldWindowing;
     /** All `<ng-template dfTemplate="...">` instances projected into this form. */
     private readonly _projectedTemplates;
     private readonly stateManager;
@@ -162,11 +217,21 @@ declare class DynamicForm<TFields extends RegisteredFieldTypes[] = RegisteredFie
         maxDerivationIterations?: number;
         submitButton?: _ng_forge_dynamic_forms.SubmitButtonOptions;
         nextButton?: _ng_forge_dynamic_forms.NextButtonOptions;
+        initialPage?: number | _ng_forge_dynamic_forms.InitialPageConfig;
+        pagePreloadWindow?: number;
+        fieldWindowing?: boolean | {
+            eager?: number;
+            placeholderHeight?: string;
+            park?: boolean | {
+                margin?: string;
+            };
+        };
         excludeValueIfHidden?: boolean;
         excludeValueIfDisabled?: boolean;
         excludeValueIfReadonly?: boolean;
         validateWhenHidden?: boolean;
         emitFormValueOnEvents?: boolean;
+        webMcp?: _ng_forge_dynamic_forms.WebMcpToolOptions;
     }>;
     /** Field signal context for injection into child components */
     fieldSignalContext: Signal<_ng_forge_dynamic_forms_internal.FieldSignalContext<TModel>>;
@@ -175,7 +240,7 @@ declare class DynamicForm<TFields extends RegisteredFieldTypes[] = RegisteredFie
     /** The Angular Signal Form instance */
     form: Signal<FieldTree<TModel, string | number, "writable">>;
     /** Current form values (reactive) */
-    formValue: Signal<TModel | (TModel extends infer T ? T extends TModel ? T extends _angular_forms.AbstractControl<unknown, infer TValue extends unknown, any> ? TValue : never : never : never)>;
+    formValue: Signal<TModel>;
     /** Whether the form is currently valid */
     valid: Signal<boolean>;
     /** Whether the form is currently invalid */
@@ -195,13 +260,33 @@ declare class DynamicForm<TFields extends RegisteredFieldTypes[] = RegisteredFie
     /** Whether to render the form template */
     private derivationReady;
     shouldRender: Signal<boolean>;
+    /**
+     * What the experimental WebMCP layer is doing for this form.
+     *
+     * Injecting it is also what instantiates the gate (component providers are
+     * lazy), which is what keeps the registrar lazily loaded. Intentionally absent
+     * from `shouldRender`: agent visibility must never gate render.
+     *
+     * `'disabled'` unless `withExperimentalWebMcp()` is provided; `'idle'` until a
+     * config declares `options.webMcp`; `'active'` once its tools are registered.
+     * `'failed'` and `'unsupported'` are the two ways registration does not
+     * happen, and are worth surfacing rather than guessing at.
+     *
+     * @experimental
+     */
+    readonly webMcpStatus: Signal<_ng_forge_dynamic_forms.WebMcpStatus>;
     /** Resolved fields ready for rendering */
     protected resolvedFields: Signal<ResolvedField[]>;
     /**
-     * Recursively counts container components that will emit ComponentInitializedEvent.
-     * Includes the dynamic-form component itself (+1).
+     * Effective field-windowing config for non-paged forms. Per-form
+     * `FormOptions.fieldWindowing` wins over the global `withFieldWindowing()`
+     * default; both fall back to disabled (fully eager).
      */
-    private totalComponentsCount;
+    protected readonly fieldWindowing: Signal<FieldWindowingConfig>;
+    private readonly initializedComponents;
+    private readonly initialPageReady;
+    private readonly initializationReady;
+    /** Replayable readiness so late subscribers cannot miss hot EventBus announcements. */
     initialized$: rxjs.Observable<boolean>;
     /** Emits when form validity changes. */
     validityChange: _angular_core.OutputRef<boolean>;
@@ -216,14 +301,23 @@ declare class DynamicForm<TFields extends RegisteredFieldTypes[] = RegisteredFie
     /** Emits all form events for custom event handling. */
     events: _angular_core.OutputRef<_ng_forge_dynamic_forms.FormEvent>;
     /**
-     * Emits when all form components are initialized and ready for interaction.
-     * Useful for E2E testing to ensure the form is fully rendered before interaction.
+     * Emits when a non-paged form is fully initialized, or when the initially active page of a
+     * paged form is ready for interaction. Virtualized inactive pages are not part of initial
+     * readiness because they intentionally remain unmounted.
      */
     initialized: _angular_core.OutputRef<boolean>;
+    /**
+     * EXPERIMENTAL. Added alongside page preloading; the emission contract may change.
+     *
+     * Emits after the currently visible page and all of its visible fields render. Announced
+     * once per visit to a page, and again when that page is returned to. Use this when work must
+     * run after every page transition; `initialized` emits only for the initial page.
+     */
+    activePageInitialized: _angular_core.OutputRef<ActivePageInitializedEvent>;
     /** Emits when the current page changes in paged forms. */
     onPageChange: _angular_core.OutputRef<PageChangeEvent>;
-    /** Emits when page navigation state changes (canGoNext, canGoPrevious, etc.). */
-    onPageNavigationStateChange: _angular_core.OutputRef<PageNavigationStateChangeEvent>;
+    /** Emits when pager state changes (currentPageIndex, totalPages, isFirstPage, isLastPage). */
+    onPageNavigationStateChange: _angular_core.OutputRef<PagerStateEvent>;
     constructor();
     /**
      * Handles native form submission triggered by:
@@ -234,6 +328,15 @@ declare class DynamicForm<TFields extends RegisteredFieldTypes[] = RegisteredFie
      * @param event - The native submit event from the form element
      */
     protected onNativeSubmit(event: Event): void;
+    /**
+     * Whether a field should be deferred by field windowing. Containers are never
+     * windowed: they emit `ComponentInitializedEvent`, which the form's init
+     * tracker counts, so deferring one would stall `initialized` until it scrolls
+     * into view. Leaf fields carry no such count, so they defer freely.
+     */
+    protected windowsField(field: ResolvedField, index: number): boolean;
+    /** Class string for a windowed field's placeholder — matches the real field's grid column. */
+    protected placeholderGridClass(field: ResolvedField): string;
     private setupEffects;
     /**
      * Populates FORM_STATE_DEPS with this component's input signals, then injects
@@ -244,7 +347,7 @@ declare class DynamicForm<TFields extends RegisteredFieldTypes[] = RegisteredFie
     private connectDeps;
     private setupEventHandlers;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<DynamicForm<any, any>, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<DynamicForm<any, any>, "form[dynamic-form]", never, { "config": { "alias": "dynamic-form"; "required": true; "isSignal": true; }; "formOptions": { "alias": "formOptions"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": false; "isSignal": true; }; "source": { "alias": "source"; "required": false; "isSignal": true; }; }, { "value": "valueChange"; "validityChange": "validityChange"; "dirtyChange": "dirtyChange"; "submitted": "submitted"; "reset": "reset"; "cleared": "cleared"; "events": "events"; "initialized": "initialized"; "onPageChange": "onPageChange"; "onPageNavigationStateChange": "onPageNavigationStateChange"; }, ["_projectedTemplates"], never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<DynamicForm<any, any>, "form[dynamic-form]", never, { "config": { "alias": "dynamic-form"; "required": true; "isSignal": true; }; "formOptions": { "alias": "formOptions"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": false; "isSignal": true; }; "source": { "alias": "source"; "required": false; "isSignal": true; }; }, { "value": "valueChange"; "validityChange": "validityChange"; "dirtyChange": "dirtyChange"; "submitted": "submitted"; "reset": "reset"; "cleared": "cleared"; "events": "events"; "initialized": "initialized"; "activePageInitialized": "activePageInitialized"; "onPageChange": "onPageChange"; "onPageNavigationStateChange": "onPageNavigationStateChange"; }, ["_projectedTemplates"], never, true, never>;
 }
 
 /**
@@ -450,6 +553,216 @@ declare function withEventFormValue(): DynamicFormFeature<'event-form-value'>;
  */
 declare function withValueExclusionDefaults(config?: Partial<ValueExclusionConfig>): DynamicFormFeature<'value-exclusion'>;
 
+/**
+ * Configures the global page preload window for paged forms — how many pages on
+ * each side of the current page are mounted during browser idle time.
+ *
+ * @remarks
+ * Paged forms only ever display one page at a time, so mounting every page (the
+ * fields, containers, and change-detection of pages the user may never reach)
+ * is wasted work: it inflates initial-render time and makes every keystroke pay
+ * change detection for off-screen pages. The preload window bounds how much is
+ * mounted around the current page. The active page always renders directly;
+ * eligible neighbours render on idle. Pages outside the window remain lightweight
+ * placeholders until navigation or a window change makes them eligible.
+ *
+ * **Precedence:**
+ * 1. Per-form `pagePreloadWindow` on `FormOptions` — wins for that form
+ * 2. Global `withPagePreload(n)` — baseline default for all forms
+ * 3. No feature — token default (`1`, i.e. current page ±1)
+ *
+ * @param window - Pages to preload on idle on each side of the current page. `0`
+ *   mounts only the current page; `1` (default) mounts ±1 for flicker-free sequential
+ *   navigation; higher values pre-warm more pages for jump navigation. Negative
+ *   values are clamped to `0`.
+ * @returns A DynamicFormFeature that configures the global preload window
+ *
+ * @example
+ * ```typescript
+ * provideDynamicForm(...withMaterialFields(), withPagePreload(2));
+ * ```
+ */
+declare function withPagePreload(window: number): DynamicFormFeature<'page-preload'>;
+
+/** Per-form override shape for parking. `false` opts out; an object tunes the margin. */
+type FieldParkingOption = boolean | {
+    /** IntersectionObserver root margin. Supports one to four `px` or `%` values. */
+    margin?: string;
+};
+
+/**
+ * Configures global progressive field mounting ("field windowing") for large
+ * flat (single-page) forms.
+ *
+ * @remarks
+ * A flat form mounts every field eagerly, so a large form pays the full
+ * initial-render cost up front and every keystroke walks all N live views —
+ * even for fields far off-screen. Field windowing bounds how much is mounted:
+ * the first `eager` fields render immediately, and the rest render as a
+ * lightweight placeholder that mounts the moment it scrolls near/into view.
+ * Validators, derivations, and values live at the Signal Forms schema level
+ * (not the DOM), so unmounted fields keep full form semantics.
+ *
+ * Mounting is one-way — `@defer (on viewport)` never unmounts — so on its own
+ * that bound is temporary: scroll a long form once and every field is live
+ * again for the rest of the session. **Parking** closes the gap and comes on
+ * with this feature (it is off when the feature is not used, since it changes
+ * rendering behaviour). A field scrolled outside `park.margin` leaves change detection but
+ * keeps its DOM, so it costs nothing per keystroke while staying findable by
+ * browser search, fillable by autofill, and reachable by assistive tech. Its
+ * own edits still reach the model: Angular binds `input` / `blur` with plain
+ * DOM listeners, which keep firing on a detached view.
+ *
+ * **Precedence:**
+ * 1. Per-form `fieldWindowing` on `FormOptions` — wins for that form
+ * 2. Global `withFieldWindowing(...)` — baseline default for all forms
+ * 3. No feature — token default (disabled, i.e. fully eager)
+ *
+ * @param config - `eager` (default `12`), `placeholderHeight` (default `'4rem'`)
+ *   and `park` (default on, margin `'100%'`) overrides. `eager` is clamped to a
+ *   non-negative integer.
+ * @returns A DynamicFormFeature that enables the global field windowing default
+ *
+ * @example
+ * ```typescript
+ * provideDynamicForm(...withMaterialFields(), withFieldWindowing({ eager: 20 }));
+ * ```
+ */
+declare function withFieldWindowing(config?: {
+    eager?: number;
+    placeholderHeight?: string;
+    park?: FieldParkingOption;
+}): DynamicFormFeature<'field-windowing'>;
+
+/**
+ * Enables WebMCP tool registration for forms that declare `options.webMcp`.
+ *
+ * @experimental
+ *
+ * @remarks
+ * WebMCP lets an AI agent running in the browser discover and drive a form
+ * through structured tools rather than by simulating clicks. Each opted-in form
+ * registers `fill_{name}`, which applies a partial patch of values to the form
+ * and reports back what it set, which fields apply, which are still empty, and
+ * any validation errors. Submission is a separate, per-form opt-in
+ * (`options.webMcp.allowSubmit`); without it the agent stages values and a human
+ * presses the button.
+ *
+ * The tool schema is generated from the form config, so agents see labels,
+ * option enums with their human titles, and static validator constraints rather
+ * than the bare types value-shape inference would produce. Agent arguments are
+ * validated in code before anything is written, and a call that does not parse
+ * is rejected whole rather than half-applied.
+ *
+ * Nothing is registered unless a form opts in, and the registrar module is
+ * dynamically imported, so a form without `options.webMcp` never loads it — the
+ * feature itself, the token and the form-scoped hook that decides are part of
+ * the main bundle. Registration is browser-only and no-ops where the page
+ * exposes no model context.
+ *
+ * Named `experimental` on purpose: WebMCP is a proposed standard, in an origin
+ * trial as of Chrome 149, and the browser surface underneath this may still
+ * change. Expect breaking changes outside a major version.
+ *
+ * @returns A DynamicFormFeature enabling WebMCP registration.
+ *
+ * @example
+ * ```typescript
+ * provideDynamicForm(...withMaterialFields(), withExperimentalWebMcp());
+ *
+ * const config = {
+ *   options: { webMcp: { name: 'signup', description: 'Sign a new user up.' } },
+ *   fields: [...],
+ * } as const satisfies FormConfig;
+ * ```
+ */
+declare function withExperimentalWebMcp(): DynamicFormFeature<'web-mcp'>;
+
+/**
+ * What the WebMCP layer is currently doing for this form. Reported by
+ * `DynamicForm.webMcpStatus()`; `'active'` is the only state in which an agent
+ * can see the form.
+ *
+ * @experimental
+ */
+type WebMcpStatus = 
+/** `withExperimentalWebMcp()` is not provided, or this is the server. */
+'disabled'
+/** Enabled, but the current config does not declare `options.webMcp`. */
+ | 'idle'
+/** Loading the registrar or awaiting `registerTool()`. */
+ | 'registering'
+/** Tools are registered against the browser's model context. */
+ | 'active'
+/** The browser exposes no model context, so there is nothing to register against. */
+ | 'unsupported'
+/** Registration was attempted and rejected. See the console for the reason. */
+ | 'failed';
+
+/**
+ * How a submission ended.
+ *
+ * Dispatching `FormSubmitEvent` is fire-and-forget: the submission pipeline
+ * drops a second submission through `exhaustMap`, skips submission entirely when
+ * the form is invalid or async validators are still pending, and swallows an
+ * asynchronous action failure to keep the stream alive. None of that is visible
+ * to the caller, which is fine for a button click — the user is watching the
+ * page — and wrong for anything that has to report back, an agent tool call
+ * above all.
+ *
+ * @experimental
+ */
+type SubmissionOutcome = {
+    readonly status: 'success';
+}
+/** No `submission.action` is configured; the `(submitted)` output received the value. */
+ | {
+    readonly status: 'dispatched';
+}
+/** The form was invalid, so nothing was submitted. */
+ | {
+    readonly status: 'validation-failed';
+}
+/** Async validators had not resolved, so submission was skipped. */
+ | {
+    readonly status: 'pending-validation';
+}
+/** The action ran and came back with server-side validation errors. */
+ | {
+    readonly status: 'server-errors';
+}
+/** The action threw or rejected. */
+ | {
+    readonly status: 'action-failed';
+    readonly error: unknown;
+}
+/** Another submission was already in flight and this one was dropped. */
+ | {
+    readonly status: 'busy';
+}
+/** The form went away before the submission settled. */
+ | {
+    readonly status: 'cancelled';
+};
+/**
+ * The reply channel a caller attaches to `FormSubmitEvent` when it needs to know
+ * what happened.
+ *
+ * `accept()` is called by the submission handler the moment it takes the event.
+ * Because the event bus dispatches synchronously, a caller that finds its reply
+ * un-accepted once `dispatch()` returns knows the pipeline dropped the
+ * submission rather than merely not having finished it yet — which is the only
+ * way to tell "busy" apart from "still running".
+ *
+ * @experimental
+ */
+interface SubmissionReply {
+    /** Marks the submission as taken by the pipeline. */
+    accept(): void;
+    /** Reports the final outcome. The first call wins; later calls are ignored. */
+    settle(outcome: SubmissionOutcome): void;
+}
+
 /**
  * Configures global validation execution defaults — when validators should run
  * relative to a field's reactive state.
@@ -635,9 +948,50 @@ interface SanitizedFormConfig {
  */
 declare function sanitizeFormConfig(config: FormConfig, options?: SanitizeFormConfigOptions): SanitizedFormConfig;
 
-/** Event dispatched to submit the form (the action behind a `submit` button). */
+/** Per-dispatch overrides for a page jump. */
+interface PageNavigationOptions {
+    /**
+     * Whether to apply the forward-jump validity gate.
+     *
+     * Set `false` to land on the target regardless of earlier pages, which is what
+     * restoring a saved session wants. Bounds and hidden-page checks still apply.
+     *
+     * @default true
+     */
+    validate?: boolean;
+}
+/**
+ * Event dispatched to move a paged form to a specific page.
+ *
+ * Backward jumps are unconditional. Forward jumps validate every visible page
+ * between the current one and the target (the target itself is not validated);
+ * if one is invalid, navigation stops on the first invalid page. Pass
+ * `{ validate: false }` to skip that gate and land on the target.
+ */
+declare class GoToPageEvent implements FormEvent {
+    /** The target page index (0-based) */
+    readonly pageIndex: number;
+    /** Per-dispatch overrides; omit for the default gated behavior. */
+    readonly options?: PageNavigationOptions | undefined;
+    readonly type: "go-to-page";
+    constructor(
+    /** The target page index (0-based) */
+    pageIndex: number, 
+    /** Per-dispatch overrides; omit for the default gated behavior. */
+    options?: PageNavigationOptions | undefined);
+}
+
+/**
+ * Event dispatched to submit the form (the action behind a `submit` button).
+ *
+ * A caller that needs to know how the submission ended passes a
+ * {@link SubmissionReply}; the submission handler reports back through it. A
+ * button click passes nothing and stays fire-and-forget, as before.
+ */
 declare class FormSubmitEvent implements FormEvent {
+    readonly reply?: SubmissionReply | undefined;
     readonly type: "submit";
+    constructor(reply?: SubmissionReply | undefined);
 }
 
 /** Event dispatched to advance a paged form to the next page. */
@@ -878,5 +1232,5 @@ interface ArrayItemContext {
     formValue?: unknown;
 }
 
-export { AppendArrayItemEvent, BUILT_IN_FIELDS, ComponentAddonComponent, ConsoleLogger, DfTemplate, DynamicForm, EventDispatcher, FormClearEvent, FormResetEvent, FormSubmitEvent, InsertArrayItemEvent, MoveArrayItemEvent, NextPageEvent, PageChangeEvent, PopArrayItemEvent, PrependArrayItemEvent, PreviousPageEvent, RemoveAtIndexEvent, ShiftArrayItemEvent, TemplateAddonComponent, TextAddonComponent, arrayEvent, createWrappers, isWrappersBundle, provideDynamicForm, sanitizeFormConfig, withAddonActions, withCustomAddon, withEventFormValue, withLegacyStatusClasses, withLoggerConfig, withValidationExecutionDefaults, withValueExclusionDefaults, wrapperProps };
-export type { AddonActionsFeature, AddonWarning, ArrayItemContext, ArrayItemDefinitionTemplate, ExtractFieldDefs, ExtractFormValue, InferWrapperRegistry, SanitizeFormConfigOptions, SanitizedFormConfig, WrapperRegistration, WrappersBundle };
+export { ActivePageInitializedEvent, AppendArrayItemEvent, BUILT_IN_FIELDS, ComponentAddonComponent, ConsoleLogger, DfTemplate, DynamicForm, EventDispatcher, FormClearEvent, FormResetEvent, FormSubmitEvent, GoToPageEvent, InsertArrayItemEvent, MoveArrayItemEvent, NextPageEvent, PageChangeEvent, PagerStateEvent, PopArrayItemEvent, PrependArrayItemEvent, PreviousPageEvent, RemoveAtIndexEvent, ShiftArrayItemEvent, TemplateAddonComponent, TextAddonComponent, arrayEvent, createWrappers, isWrappersBundle, provideDynamicForm, sanitizeFormConfig, withAddonActions, withCustomAddon, withEventFormValue, withExperimentalWebMcp, withFieldWindowing, withLegacyStatusClasses, withLoggerConfig, withPagePreload, withValidationExecutionDefaults, withValueExclusionDefaults, wrapperProps };
+export type { AddonActionsFeature, AddonWarning, ArrayItemContext, ArrayItemDefinitionTemplate, ExtractFieldDefs, ExtractFormValue, FieldParkingOption, InferWrapperRegistry, PageNavigationOptions, PagerState, SanitizeFormConfigOptions, SanitizedFormConfig, SubmissionOutcome, SubmissionReply, WebMcpStatus, WrapperRegistration, WrappersBundle };