@reformer/core 8.0.0 → 9.0.0-beta.2

package/dist/core/nodes/group-node.d.ts

@@ -1,4 +1,4 @@
-import { ReadonlySignal } from '@preact/signals-core';
+import { Signal, ReadonlySignal } from '@preact/signals-core';
 import { FormNode, SetValueOptions } from './form-node';
 import { ValidationError, FieldStatus, FormSchema, GroupNodeConfig, FormValue } from '../types';
 import { FormProxy } from '../types/form-proxy';
@@ -54,6 +54,18 @@ export declare class GroupNode<T> extends FormNode<T> {
     private readonly _disabled;
     /** Form-level validation errors */
     private readonly _formErrors;
+    /**
+     * M1: валидация уровня модели/схемы (`validateFormModel(model, schema)`). Привязывается
+     * `createForm({ model, schema })`, т.к. под M1 валидаторы срезаны с FieldNode и живут на слое
+     * модели. Без неё `validate()`/`submit()` пропускали бы все schema-валидаторы. @internal
+     */
+    private _modelValidate?;
+    /**
+     * M1: связь листовой ноды-ребёнка → её сигнал модели (тот, что помечает `markDerived`).
+     * Нужна bulk-сеттерам (`setValue`/`patchValue`), чтобы корректно определять derived-поля:
+     * `field.value` — computed-обёртка, отличная от записываемого сигнала модели. @internal
+     */
+    private readonly _fieldSignals;
     readonly value: ReadonlySignal<T>;
     readonly valid: ReadonlySignal<boolean>;
     readonly invalid: ReadonlySignal<boolean>;
@@ -156,7 +168,12 @@ export declare class GroupNode<T> extends FormNode<T> {
      *
      * @param onSubmit - Callback для отправки данных
      * @param options - Опции submit (skipValidation, skipTouch)
-     * @returns Результат от onSubmit или null если валидация не пройдена
+     * @returns Результат от onSubmit или `null` если валидация не пройдена
+     *
+     * @remarks
+     * `null` перегружен: он означает и «валидация не пройдена», и легитимный `null`-результат
+     * `onSubmit` (или void-обработчик). Если вызывающей стороне нужно различать эти случаи —
+     * используйте {@link submitWithResult}, который возвращает явный флаг `success`.
      */
     submit<R>(onSubmit: (values: T) => Promise<R> | R, options?: SubmitOptions): Promise<R | null>;
     /**
@@ -244,7 +261,13 @@ export declare class GroupNode<T> extends FormNode<T> {
      * useEffect(() => dispose, []);
      * ```
      */
-    watchField<K extends keyof T>(fieldPath: K extends string ? K : string, callback: (value: T[K]) => void | Promise<void>): () => void;
+    /** Подписка на top-level поле — value типизирован как `T[K]`. */
+    watchField<K extends keyof T & string>(fieldPath: K, callback: (value: T[K]) => void | Promise<void>): () => void;
+    /**
+     * Подписка на вложенное поле по строковому пути ("address.city").
+     * Путь нельзя выразить в типах узла → value честно `unknown`, потребитель сужает.
+     */
+    watchFieldByPath(path: string, callback: (value: unknown) => void | Promise<void>): () => void;
     /**
      * Hook: вызывается после disable()
      */
@@ -258,6 +281,19 @@ export declare class GroupNode<T> extends FormNode<T> {
      * @internal
      */
     attachBehaviorCleanup(cleanup: () => void): void;
+    /**
+     * Прикрепить валидацию уровня модели/схемы (M1). Вызывается `createForm({ model, schema })`,
+     * чтобы `validate()`/`submit()` прогоняли schema-валидаторы (`validateFormModel`), а не только
+     * пустые FieldNode. Возвращаемый флаг — валидна ли модель по схеме.
+     * @internal
+     */
+    attachModelValidator(validate: () => Promise<boolean>): void;
+    /**
+     * Связать листовую ноду-ребёнка с её сигналом модели (M1). Вызывается `createForm` для каждого
+     * листового поля на его владеющей группе — используется bulk-сеттерами для derived-guard (F9).
+     * @internal
+     */
+    registerFieldSignal(node: FormNode<any>, signal: Signal<unknown>): void;
     /**
      * Очистить все ресурсы узла
      */

package/dist/core/nodes/model-array-node.d.ts

@@ -58,6 +58,7 @@ export declare class ModelArrayNode<T extends object> extends FormNode<T[]> {
     private readonly buildItem;
     private readonly itemNodes;
     private readonly cache;
+    private mountedModels;
     private readonly initial;
     private readonly _arrayErrors;
     private readonly disposeSync;
@@ -104,6 +105,17 @@ export declare class ModelArrayNode<T extends object> extends FormNode<T[]> {
     setErrors(errors: ValidationError[]): void;
     clearErrors(): void;
     protected onMarkAsTouched(): void;
-    /** Очистка подписки синхронизации. */
+    protected onMarkAsUntouched(): void;
+    protected onMarkAsDirty(): void;
+    protected onMarkAsPristine(): void;
+    protected onDisable(): void;
+    protected onEnable(): void;
+    /** Диспозит форму элемента (эффекты/поведения/вложенные подписки); терпима к не-GroupNode. */
+    private disposeItemNode;
+    /**
+     * Очистка подписки синхронизации И детерминированный teardown всех форм элементов.
+     * Без пробрасывания dispose в itemNodes эффекты/поведения каждой формы элемента (в т.ч. disposeSync
+     * вложенных ModelArrayNode) остались бы жить после teardown формы — утечка подписок.
+     */
     dispose(): void;
 }

package/dist/core/types/deep-schema.d.ts

@@ -1,10 +1,17 @@
 import { ComponentType } from 'react';
 import { Signal } from '@preact/signals-core';
-import { ValidatorFn, AsyncValidatorFn, FormFields, AnyFunction } from './index';
+import { ValidatorFn, AsyncValidatorFn, AnyFunction } from './index';
 /**
  * Конфигурация поля
  * @group Types
  * @category Configuration Types
+ * @remarks
+ * В схеме `createForm({ model, schema })` лист связывают через **`value: model.$.field`**: harvest
+ * ловит узел по идентичности `Signal` (`node.value instanceof Signal` — см. `create-form.ts`) и
+ * нормализует его в `valueSignal`. Писать `valueSignal:` **в самой схеме `createForm` нельзя** —
+ * harvest его не подхватит (проверка идёт по `node.value`), и `component`/`componentProps` этого
+ * узла молча отбросятся. `value`/`valueSignal` на прямом FieldNode-конфиге — это
+ * post-normalization / legacy-слой, а не форма записи в схеме `createForm`.
  */
 export interface FieldConfig<T> {
     /**
@@ -30,22 +37,48 @@ export interface FieldConfig<T> {
     /** Задержка (в мс) перед запуском асинхронной валидации */
     debounce?: number;
 }
+/**
+ * «Хотя бы одно поле обязано присутствовать»: превращает объект со всеми опциональными
+ * свойствами в объединение вариантов, где ровно один ключ обязателен, а остальные опциональны.
+ * Пустой объект `{}` не assignable ни к одному варианту и потому отклоняется.
+ *
+ * @internal
+ */
+type RequireAtLeastOne<T> = {
+    [K in keyof T]-?: Required<Pick<T, K>> & Partial<Omit<T, K>>;
+}[keyof T];
+/**
+ * {@link FieldConfig}, из которого нельзя сделать пустой `{}`.
+ *
+ * Все свойства {@link FieldConfig} опциональны, поэтому в {@link FormSchema} опечатка вида
+ * `{ email: {} }` молча проходит проверку типов и в рантайме становится пустой подгруппой
+ * вместо поля. `NonEmptyFieldConfig` требует наличия хотя бы одного свойства (value/valueSignal/
+ * component/validators/…), оставляя каждое из них опциональным по отдельности.
+ *
+ * @internal
+ */
+type NonEmptyFieldConfig<T> = RequireAtLeastOne<FieldConfig<T>>;
 /**
  * Конфигурация массива
  * @group Types
  * @category Configuration Types
  */
-export interface ArrayConfig<T extends FormFields> {
+export interface ArrayConfig<T extends object> {
     itemSchema: FormSchema<T>;
     initial?: Partial<T>[];
 }
 /**
- * Автоматически определяет тип схемы на основе TypeScript типа:
+ * **Data-shaped** конфиг формы: ключи повторяют структуру данных `T`, значения — {@link FieldConfig}
+ * (или вложенный `FormSchema`). Форма конфига, из которой строится {@link GroupNode}.
  * - `T[] -> [FormSchema<T>]` (массив с одним элементом)
  * - `object -> FormSchema<T>` (группа)
  * - `primitive -> FieldConfig<T>` (поле)
  *
- * Использует NonNullable для корректной обработки опциональных полей
+ * Использует NonNullable для корректной обработки опциональных полей.
+ *
+ * ⚠️ Не путать с {@link FormSchemaNode} — тот описывает **узел дерева** M1-схемы (лист/массив/
+ * контейнер), передаваемой в `createForm({ model, schema })`. `FormSchema` — это data-shaped конфиг
+ * (ключи = поля данных), а не узел дерева.
  *
  * @group Types
  * @category Configuration Types
@@ -78,5 +111,6 @@ export interface ArrayConfig<T extends FormFields> {
  * ```
  */
 export type FormSchema<T> = {
-    [K in keyof T]: NonNullable<T[K]> extends string | number | boolean ? FieldConfig<T[K]> : NonNullable<T[K]> extends Array<infer U> ? U extends string | number | boolean ? FieldConfig<T[K]> : U extends Date | File | Blob | AnyFunction ? FieldConfig<T[K]> : [FormSchema<U>] : NonNullable<T[K]> extends Date | File | Blob | AnyFunction ? FieldConfig<T[K]> : FormSchema<NonNullable<T[K]>>;
+    [K in keyof T]: NonNullable<T[K]> extends string | number | boolean ? NonEmptyFieldConfig<T[K]> : NonNullable<T[K]> extends Array<infer U> ? U extends string | number | boolean ? NonEmptyFieldConfig<T[K]> : U extends Date | File | Blob | AnyFunction ? NonEmptyFieldConfig<T[K]> : [FormSchema<U>] : NonNullable<T[K]> extends Date | File | Blob | AnyFunction ? NonEmptyFieldConfig<T[K]> : FormSchema<NonNullable<T[K]>>;
 };
+export {};

package/dist/core/types/form-proxy.d.ts

@@ -12,7 +12,7 @@ import { ArrayNode } from '../nodes/array-node';
  *
  * @internal
  */
-type IsGroupObject<V> = V extends ReadonlyArray<unknown> ? false : V extends Date | File | Blob ? false : V extends object ? true : false;
+type IsGroupObject<V> = V extends ReadonlyArray<unknown> ? false : V extends Date | File | Blob ? false : V extends (...args: never[]) => unknown ? false : V extends object ? true : false;
 /**
  * Мапит тип модели данных T на правильные типы узлов формы
  *
@@ -64,8 +64,33 @@ export type FormControlsProxy<T> = {
  * form.email.setValue('test@mail.com');
  * form.profile.name.setValue('John');
  * ```
+ *
+ * @remarks
+ * **Зарезервированные имена.** Прямой доступ `form.<name>` отдаёт приоритет собственным
+ * членам {@link GroupNode} (`value`, `status`, `id`, `errors`, `disabled`, `reset`, `submit`, …).
+ * Поэтому поле модели, названное любым из этих имён, недостижимо как `form.<name>` — там будет
+ * агрегированный сигнал/метод узла, а не {@link FieldNode}. Такие имена исключены из полевого
+ * пространства имён на уровне типов (через `Omit<…, keyof GroupNode>`), чтобы затенение не
+ * компилировалось молча. Для доступа к любому полю по имени — включая затенённые — используйте
+ * escape-hatch пространство {@link FormProxy.$}: `form.$.status`, `form.$.id`, `form.$.value`.
  */
-export type FormProxy<T> = GroupNode<T> & FormControlsProxy<T>;
+export type FormProxy<T> = GroupNode<T> & Omit<FormControlsProxy<T>, keyof GroupNode<T>> & {
+    /**
+     * Escape-hatch пространство имён «controls»: типобезопасный доступ ко ВСЕМ полям формы
+     * по имени, включая поля, чьи имена совпадают с членами {@link GroupNode}
+     * (`value`/`status`/`id`/`errors`/…), недостижимые через `form.<name>`.
+     *
+     * @example
+     * ```typescript
+     * // модель: { status: string; email: string }
+     * form.status;      // ReadonlySignal<FieldStatus> — агрегат GroupNode (не поле!)
+     * form.$.status;    // FieldNode<string> — поле пользователя
+     * form.$.status.setValue('active');
+     * form.$.email;     // FieldNode<string> — так же доступны и незатенённые поля
+     * ```
+     */
+    readonly $: FormControlsProxy<T>;
+};
 /**
  * Комбинированный тип для ArrayNode с Proxy доступом к элементам
  *

package/dist/core/types/index.d.ts

@@ -70,7 +70,7 @@ export type AsyncValidatorFn<T = FormValue> = (value: T, options?: AsyncValidato
 export interface ValidationError {
     code: string;
     message: string;
-    params?: FormFields;
+    params?: Record<string, FormValue>;
     /** Severity level: 'error' (default) blocks submission, 'warning' shows message but allows submission */
     severity?: 'error' | 'warning';
 }
@@ -85,7 +85,7 @@ export interface ErrorFilterOptions {
     /** Фильтр по сообщению (поддерживает частичное совпадение) */
     message?: string;
     /** Фильтр по параметрам ошибки */
-    params?: FormFields;
+    params?: Record<string, FormValue>;
     /** Кастомный предикат для фильтрации */
     predicate?: (error: ValidationError) => boolean;
 }
@@ -98,6 +98,7 @@ export type FieldStatus = 'valid' | 'invalid' | 'pending' | 'disabled';
 export type { FieldConfig } from './deep-schema';
 export type { Validator, AsyncValidator, ConditionFn, ValidateOptions, ValidateAsyncOptions, } from './validation-schema';
 export type { FormSchema, ArrayConfig } from './deep-schema';
+export type { FormSchemaNode, SchemaArrayControl, SchemaValidator } from './schema-node';
 export type { FormControlsProxy, FormProxy, FormArrayProxy } from './form-proxy';
 /**
  * Конфигурация GroupNode.
@@ -117,7 +118,7 @@ export interface GroupNodeConfig<T> {
  * Используется вместо инлайнового `Record<string, unknown>`
  * @internal
  */
-export type UnknownRecord = Record<string, any>;
+export type UnknownRecord = Record<string, unknown>;
 /**
  * Интерфейс для узлов с методом applyValidationSchema
  * @internal
@@ -156,13 +157,6 @@ export interface ConfigWithSchema {
 export interface ConfigWithValue {
     value: unknown;
 }
-/**
- * Тип для конфига с полями (FormSchema generic constraint)
- * Используется вместо `Record<string, any>` для схем форм
- * @deprecated
- * @internal
- */
-export type FormFields = Record<string, FormValue>;
 /**
  * Тип для путей к полям (field paths)
  * Используется в навигации по полям вместо any

package/dist/core/types/schema-node.d.ts

@@ -0,0 +1,79 @@
+import { ComponentType } from 'react';
+import { ValidationError } from './index';
+/**
+ * Валидатор поля схемы. Узел хранит validators гетерогенно: движок `validate*` вызывает их как
+ * `(value, scope, root)`, но сюда кладут любой контракт — `ValidatorFn` (value),
+ * `Validator` (value, control, root) или `ModelValidator` (value, model, root). Поэтому тип
+ * намеренно широкий по параметрам.
+ *
+ * @group Types
+ */
+export type SchemaValidator = (value: any, ...rest: any[]) => ValidationError | null | Promise<ValidationError | null>;
+/**
+ * Минимальный контракт реактивного массива модели ({@link FormSchemaNode.array}).
+ * Совпадает по форме с рантайм-фасадом `model.<array>` (см. `ModelArray`); рендерерский
+ * `RenderModelArrayControl` — его расширение (добавляет `move`).
+ *
+ * @group Types
+ */
+export interface SchemaArrayControl {
+    /** Путь массива в модели (dot-нотация) — нужен для резолва узла массива. */
+    readonly __path: string;
+    /** Реактивная длина. */
+    readonly length: number;
+    at(index: number): unknown;
+    push(item: unknown): void;
+    removeAt(index: number): void;
+}
+/**
+ * Узел единой схемы M1 — дерево, обходимое `createForm({ model, schema })`,
+ * `validateModel`/`validateFormModel` и рендерерами.
+ *
+ * Узел совмещает несколько ролей (различаются рантаймом по форме):
+ *  - **поле** — несёт `value: Signal` (сигнал модели `model.$.x`) + `component`/`validators`;
+ *  - **массив** — `{ array: model.<path>, item(itemModel) }`;
+ *  - **контейнер/ветка** — вложенные узлы (`children`), опц. условие `when`;
+ *  - **record-of-fields** — под-узлы под произвольными именованными ключами (индексная сигнатура).
+ *
+ * Индексная сигнатура (`[key: string]: unknown`) отражает свободный рекурсивный обход: под-узлы
+ * допустимы под любым ключом. Известные поля типизированы (даёт автокомплит и проверку их типов).
+ *
+ * @group Types
+ */
+export interface FormSchemaNode {
+    /**
+     * «Ручка» значения поля — маркер узла-поля. Обычно сигнал модели (`model.$.<path>`), но форма
+     * зависит от таргета (для массива `model.$.x` — дерево сигналов; в renderer-типах сужается до
+     * `Signal`). Движок разбирает узел как поле рантаймом по `value instanceof Signal`.
+     */
+    value?: unknown;
+    /** UI-компонент. Опционален: core-часть работает без UI (значение/валидация). */
+    component?: ComponentType<any>;
+    /** Props компонента. Также «клапан» для вложенности под-узлов (напр. steps визарда). */
+    componentProps?: Record<string, unknown>;
+    validators?: SchemaValidator[];
+    asyncValidators?: SchemaValidator[];
+    updateOn?: 'change' | 'blur' | 'submit';
+    disabled?: boolean;
+    /** Задержка (мс) перед запуском асинхронной валидации. */
+    debounce?: number;
+    /** Идентификатор узла (для wizard/tabs/renderBehavior). */
+    selector?: string;
+    testId?: string;
+    /** Дочерние узлы (даёт контекстную типизацию вложенным литералам — value/validators/when). */
+    children?: readonly FormSchemaNode[];
+    /** Условие включения поддерева (branch-узел `{ when, children }`). */
+    when?: (scope: any, root: any) => boolean;
+    /** Реактивный массив модели (`model.<path>`) — маркер узла-массива (вместе с `item`). */
+    array?: SchemaArrayControl;
+    /** Схема элемента массива: под-модель элемента → узел поддерева. */
+    item?: (itemModel: any) => FormSchemaNode;
+    /**
+     * Значение нового элемента массива для кнопки «Добавить»: либо готовое значение,
+     * либо фабрика `() => value`. Тип не различает варианты (union `unknown | (() => unknown)`
+     * схлопывается в `unknown`) — рантайм различает по `typeof initialValue === 'function'`.
+     */
+    initialValue?: unknown;
+    /** Свободная вложенность: record-of-fields и произвольные под-узлы. */
+    [key: string]: unknown;
+}

package/dist/core/types/validation-schema.d.ts

@@ -1,15 +1,26 @@
-import { FormFields, ValidationError } from './index';
-import { FormProxy } from './form-proxy';
+import { FormValue, ValidationError } from './index';
+import { FormModel } from '../model/types';
 /**
  * Чистый синхронный валидатор поля.
  *
- * Принимает значение поля, прокси текущего поля (control) и прокси корня формы (root).
- * Возвращает ValidationError либо null. Не знает про реестр валидации.
+ * Сигнатура зеркалит то, что реально вызывает движок M1
+ * (`validateModel`/`validateFormModel`/`validateModelSync`): `validator(value, scope, root)`.
+ * - `value` — значение поля (`TField`);
+ * - `scope` — ближайшая scope-**модель** (под-модель элемента массива или корень). Из `TForm`/`TField`
+ *   её тип не выводится, поэтому `unknown` — потребитель сужает сам (для типизированного scope
+ *   используйте {@link ModelValidator}`<TField, TScope, TForm>`);
+ * - `root` — корневая модель формы `FormModel<TForm>` (реактивный value-proxy: `root.field` читает
+ *   значение). Возвращает `ValidationError` либо `null`. Не знает про реестр валидации.
+ *
+ * Совместим с полем `validators` узла схемы (см. `SchemaValidator`) — там же лежат `ModelValidator`
+ * и `ValidatorFn`. Встроенные фабрики (`required()`/`email()`/…) возвращают `(value) => …` и
+ * дополнительные аргументы игнорируют.
  *
  * @example Кастомный валидатор в массиве `validators` поля схемы
  * ```typescript
- * const isAdult: Validator<MyForm, number> = (value, control, root) => {
+ * const isAdult: Validator<MyForm, number> = (value, _scope, root) => {
  *   if (value < 18) return { code: 'tooYoung', message: '18+' };
+ *   // root — FormModel<MyForm>: root.someOtherField читается как значение
  *   return null;
  * };
  *
@@ -21,30 +32,40 @@ import { FormProxy } from './form-proxy';
  * };
  * ```
  */
-export type Validator<TForm, TField> = (value: TField, control: FormProxy<TField>, root: FormProxy<TForm>) => ValidationError | null;
+export type Validator<TForm, TField> = (value: TField, scope: unknown, root: FormModel<TForm>) => ValidationError | null;
 /**
- * Чистый асинхронный валидатор поля.
+ * Чистый асинхронный валидатор поля. Та же тройка аргументов `(value, scope, root)`, что у
+ * {@link Validator}, но возвращает `Promise`.
  *
- * Регистрируется через `validateAsync(path, validator, { debounce })`.
+ * @deprecated Осиротевший остаток удалённого оператора `validateAsync` (Ф7). Рантаймом не
+ * потребляется — живой async-путь узла поля использует `AsyncValidatorFn` `(value, { signal })`.
+ * Экспортируется только ради обратной совместимости.
  */
-export type AsyncValidator<TForm, TField> = (value: TField, control: FormProxy<TField>, root: FormProxy<TForm>) => Promise<ValidationError | null>;
+export type AsyncValidator<TForm, TField> = (value: TField, scope: unknown, root: FormModel<TForm>) => Promise<ValidationError | null>;
 /**
- * Функция условия для applyWhen.
+ * Функция-предикат `(value) => boolean`.
+ *
+ * @deprecated Осиротевший остаток удалённого оператора `applyWhen` (Ф7). Рантаймом не
+ * потребляется; экспортируется только ради обратной совместимости.
  */
 export type ConditionFn<T> = (value: T) => boolean;
 /**
- * Опции для функции validate.
+ * Опции валидатора-фабрики (`required()`/`pattern()`/…). Передаются вторым (или последним)
+ * аргументом в фабрику и попадают в возвращаемую {@link ValidationError}.
  */
 export interface ValidateOptions {
-    /** Сообщение об ошибке */
+    /** Готовое сообщение об ошибке. Если не задано, валидаторы кладут `''`, и отображаемый текст
+     * резолвится из `code` (см. резолвер сообщений в `@reformer/cdk`). */
     message?: string;
-    /** Параметры ошибки */
-    params?: FormFields;
+    /** Параметры ошибки (подстановка в шаблон сообщения / i18n). */
+    params?: Record<string, FormValue>;
 }
 /**
- * Опции для функции validateAsync.
+ * @deprecated Осиротевший остаток удалённого оператора `validateAsync` (Ф7): опция `debounce`
+ * подключалась тем оператором, которого больше нет. Рантаймом не потребляется; экспортируется
+ * только ради обратной совместимости.
  */
 export interface ValidateAsyncOptions extends ValidateOptions {
-    /** Задержка перед выполнением валидации (в мс) */
+    /** Задержка перед выполнением валидации (в мс). */
     debounce?: number;
 }

package/dist/core/utils/create-form.d.ts

@@ -1,4 +1,5 @@
 import { FormProxy, GroupNodeConfig, FormSchema } from '../types';
+import { FormSchemaNode } from '../types/schema-node';
 import { FormModel } from '../model/types';
 import { FormBehavior } from '../../behaviors';
 /**
@@ -11,10 +12,10 @@ export interface CreateFormFromModelArgs<T> {
     /** Реактивная модель данных (источник истины значений). */
     model: FormModel<T>;
     /**
-     * Единая Schema (дерево узлов). createForm обходит её и привязывает конфиг поля к ноде
-     * по идентичности сигнала (`node.value === model.$.path`). Опциональна.
+     * Единая Schema (дерево узлов {@link FormSchemaNode}). createForm обходит её и привязывает конфиг
+     * поля к ноде по идентичности сигнала (`node.value === model.$.path`). Опциональна.
      */
-    schema?: unknown;
+    schema?: FormSchemaNode;
     /**
      * Декларативная схема поведения ({@link defineFormBehavior}). Запускается ПОСЛЕ построения нод и
      * заполнения реестра сигнал→нода; cleanup живёт на форме и вызывается в `form.dispose()`.

package/dist/core/utils/derived-registry.d.ts

@@ -6,6 +6,9 @@ import { Signal } from '@preact/signals-core';
  * bulk-сеттеры (`model.set`/`model.patch`, `patchValue`/`setValue`) пропускают это поле, чтобы
  * значение из payload не затирало вычисляемое. Прикладной код напрямую обычно не вызывает.
  *
+ * Идемпотентна на уровне флага: повторные вызовы наращивают счётчик ссылок, чтобы каждый оператор,
+ * пишущий в этот сигнал, был сбалансирован своим {@link unmarkDerived} при dispose.
+ *
  * @param signal - Сигнал значения из {@link FormModel}, которым владеет compute
  *
  * @example
@@ -17,9 +20,35 @@ import { Signal } from '@preact/signals-core';
  * ```
  *
  * @see {@link isDerived} - проверка пометки
+ * @see {@link unmarkDerived} - снять пометку при dispose оператора
  * @group Utilities
  */
 export declare function markDerived(signal: Signal<any>): void;
+/**
+ * Снять пометку производного сигнала (обратная операция к {@link markDerived}).
+ *
+ * Вызывается из очистки (`onDispose`) оператора `compute`/`computeFrom`, когда поведение снимается,
+ * но модель/сигнал продолжают жить (динамическая перекоммутация: удалить под-схему → сохранить модель
+ * → bulk-set). Без этого сигнал остаётся помеченным навсегда, и bulk-сеттеры навсегда пропускают
+ * поле, которое больше ничем не вычисляется.
+ *
+ * Учитывает счётчик ссылок: пометка снимается только когда снят последний владелец. Вызов на
+ * непомеченном сигнале — безопасный no-op.
+ *
+ * @param signal - Сигнал значения из {@link FormModel}, ранее помеченный {@link markDerived}
+ *
+ * @example
+ * ```typescript
+ * import { markDerived, unmarkDerived } from '@reformer/core';
+ *
+ * markDerived(model.$.total);
+ * onDispose(() => unmarkDerived(model.$.total)); // при снятии compute снова разрешаем bulk-set
+ * ```
+ *
+ * @see {@link markDerived} - пометить сигнал производным
+ * @group Utilities
+ */
+export declare function unmarkDerived(signal: Signal<any>): void;
 /**
  * Производный ли сигнал (помечен через {@link markDerived}).
  *

package/dist/core/utils/error-handler.d.ts

@@ -93,7 +93,10 @@ export declare class FormErrorHandler {
      * }
      * ```
      */
-    static handle(error: unknown, context: string, strategy?: ErrorStrategy): ValidationError | never | void;
+    static handle(error: unknown, context: string, strategy: ErrorStrategy.CONVERT): ValidationError;
+    static handle(error: unknown, context: string, strategy: ErrorStrategy.THROW): never;
+    static handle(error: unknown, context: string, strategy: ErrorStrategy.LOG): void;
+    static handle(error: unknown, context: string): never;
     /**
      * Извлечь сообщение из ошибки
      *

package/dist/core/utils/form-submitter.d.ts

@@ -1,10 +1,9 @@
 import { ReadonlySignal } from '@preact/signals-core';
-import { FormFields } from '../types';
 /**
  * Интерфейс формы для FormSubmitter
  * Минимальный контракт для работы с любой формой
  */
-export interface SubmittableForm<T extends FormFields> {
+export interface SubmittableForm<T extends object> {
     /** Пометить все поля как touched */
     markAsTouched(): void;
     /** Валидировать форму */
@@ -50,7 +49,7 @@ export interface SubmitResult<R> {
  * }
  * ```
  */
-export declare class FormSubmitter<T extends FormFields> {
+export declare class FormSubmitter<T extends object> {
     private readonly form;
     /** Внутренний сигнал состояния отправки */
     private readonly _submitting;
@@ -71,7 +70,12 @@ export declare class FormSubmitter<T extends FormFields> {
      *
      * @param onSubmit - Callback для отправки данных
      * @param options - Опции submit
-     * @returns Результат от onSubmit или null если валидация не пройдена
+     * @returns Результат от onSubmit или `null` если валидация не пройдена
+     *
+     * @remarks
+     * Возвращаемый `null` неоднозначен: он сигналит и провал валидации, и легитимный `null`,
+     * который вернул `onSubmit` (или void-обработчик). Чтобы различать эти случаи, используйте
+     * {@link submitWithResult} — он отдаёт явный флаг `success`.
      *
      * @example
      * ```typescript

package/dist/core/utils/index.d.ts

@@ -9,7 +9,7 @@ export { FormErrorHandler, ErrorStrategy } from './error-handler';
 export { createForm, createFormFromModel } from './create-form';
 export type { CreateFormFromModelArgs } from './create-form';
 export { registerSignalNode, getNodeForSignal } from './signal-node-registry';
-export { markDerived, isDerived } from './derived-registry';
+export { markDerived, isDerived, unmarkDerived } from './derived-registry';
 export { uniqueId } from './unique-id';
 export { safeCallback, runOutsideEffect, safeDebouncedCallback } from './safe-effect';
 export { FormSubmitter } from './form-submitter';

package/dist/core/utils/safe-effect.d.ts

@@ -4,14 +4,28 @@
  * Эти утилиты решают проблему "Cycle detected" в @preact/signals-core,
  * которая возникает при модификации сигналов внутри effect.
  *
+ * Отложенная запись ({@link runOutsideEffect}) откладывается на микротаск и при этом:
+ * - маршрутизирует синхронные throws и async-rejection через {@link FormErrorHandler} вместо того,
+ *   чтобы они всплывали неперехваченными в точке микротаска / тонули как unhandledRejection;
+ * - возвращает отменитель (canceller) для liveness — вызывающий может отменить ещё не выполненную
+ *   запись при dispose, чтобы она не сработала против снесённого узла/формы.
+ *
+ * NB: намеренно НЕ оборачиваем записи в `batch()`. Реципрокные guard'ы слоя данных (например
+ * `syncFields` в {@link module:core/model/behaviors}) держат флаг «идёт синхронизация» и сбрасывают его
+ * в `finally` ПОСЛЕ записи, полагаясь на то, что встречный эффект флашится СИНХРОННО во время записи
+ * (вне batch). `batch()` отложил бы встречный флаш за пределы сброса флага и сломал бы эту защиту
+ * (сходимость осталась бы за peek-guard'ом, но появились бы лишние круги). Коалесинг записей в один
+ * batch — законная оптимизация, но она требует, чтобы эти guard'ы стали batch-aware, поэтому делается
+ * не здесь. См. также `aggregateInto`, где коалесинг реализован на уровне самого оператора.
+ *
  * @group Utils
  * @module utils/safe-effect
  */
 /**
  * Создает callback, который выполняется вне контекста effect
  *
- * Использует queueMicrotask для отложенного выполнения,
- * что позволяет модифицировать сигналы без вызова "Cycle detected"
+ * Откладывает вызов через {@link runOutsideEffect} — то есть получает маршрутизацию ошибок и
+ * обработку async-rejection «бесплатно».
  *
  * @param callback - Функция для выполнения
  * @returns Обёрнутая функция, безопасная для вызова внутри effect
@@ -33,27 +47,33 @@
  */
 export declare function safeCallback<TArgs extends unknown[]>(callback: (...args: TArgs) => void | Promise<void>): (...args: TArgs) => void;
 /**
- * Выполняет функцию вне контекста effect
+ * Выполняет функцию вне контекста effect (отложенная запись на микротаск).
  *
- * Более простой вариант для одиночного вызова
+ * Сбои fn (синхронный throw и async-rejection) маршрутизируются через {@link FormErrorHandler}, а не
+ * всплывают неперехваченными. Возвращает отменитель: вызов до срабатывания микротаска отменяет запись
+ * (liveness-охрана — не писать против снесённого узла при dispose в том же тике).
  *
  * @param fn - Функция для выполнения
+ * @returns Отменитель ещё не выполненной записи (no-op, если запись уже выполнена)
  *
  * @example
  * ```typescript
  * effect(() => {
  *   const value = signal.value;
- *   runOutsideEffect(() => {
+ *   const cancel = runOutsideEffect(() => {
  *     otherSignal.value = transform(value);
  *   });
+ *   onDispose(cancel); // отменить ожидающую запись, если узел снесут в этом же тике
  * });
  * ```
  */
-export declare function runOutsideEffect(fn: () => void | Promise<void>): void;
+export declare function runOutsideEffect(fn: () => void | Promise<void>): () => void;
 /**
  * Создает версию callback с поддержкой debounce, безопасную для effect
  *
- * Комбинирует debounce логику с выходом из effect контекста
+ * `withDebounce` уже откладывает вызов (таймер) — этого достаточно для выхода из effect-контекста,
+ * поэтому дополнительного `queueMicrotask` нет (устранён двойной defer). Сбои callback (в т.ч.
+ * async-rejection) маршрутизируются через {@link FormErrorHandler}.
  *
  * @param callback - Функция для выполнения
  * @param withDebounce - Функция debounce обёртки из BehaviorRegistry