@reformer/core 11.0.0-beta.7 → 11.0.0-beta.9

package/docs/llms/03-api-signatures.md

@@ -7,181 +7,363 @@
 createModel<T extends object>(initial: T): FormModel<T>
 // model.get() / model.set(full) / model.patch(partial) / model.isDirty()
 // model.reset() / model.captureInitial() / model.signalAt(path)
-// model.$.field            → PathAwareSignal<FieldType>  (escape-hatch к сигналу)
-// model.arrayField         → ModelArray<Item>            (push/removeAt/insertAt/move/swap/clear/at/map/length)
-
-// Форма (ноды поверх сигналов модели)
-createForm<T>({ model, schema, behavior? }): FormProxy<T>
-// form.<field>             → FieldNode / GroupNode / FormArrayProxy
-// form.<field>.setValue(v) / .value.value / .errors.value / .disabled.value
-// form.<field>.enable() / .disable() / .reset() / .markAsTouched() / .setErrors([...])
-// form.<field>.updateComponentProps({ ... })
-
-// Валидация данных — ОТДЕЛЬНЫЙ контракт `@reformer/core/validation` (НЕ дерево createForm: то несёт
-// только layout, без validators). Схема — функция над моделью; внешний раннер разносит ошибки по нодам
-// формы (setErrors), warning не блокирует submit, устаревший прогон отменяется.
-validateModel<T>(model: FormModel<T>, schema: ValidationSchema<T>): Promise<boolean>   // из @reformer/core/validation
-// schema = defineValidationSchema<T>(({ model }) => { validate(...); ... })
-// ⚠️ form.submit() / form.validate() БОЛЬШЕ НЕ прогоняют schema-валидацию — гоняйте validateModel(model, schema) снаружи.
+// model.$.field            → PathAwareSignal<FieldType>  (ручка: привязка в схеме, правиле, операторе)
+// model.$.group.value      → снимок группы/массива; в dev заморожен — правка на месте бросает
+// model.arrayField         → ModelArray<Item>            (push/insertAt/removeAt/move/swap/clear/at/map/length)
+//   итерируем (for…of, spread); Object.keys — индексы; insertAt/move за концом — RangeError
+
+// Сборка одним вызовом: модель, форма, уровень формы и дерево для рендера
+createForm<T extends object>({
+  initial | model,
+  schema?: (model) => tree,          // билдер; JSON — документ + registry
+  behavior?,                         // defineFormBehavior(...)
+  validation?,                       // ValidationDefinition<T> | { rules?, extras?, strategy?, debounce? }
+  flow?,                             // { steps: [{ id, rules? }] } — id = selector узла шага
+  seed?, setup?,
+}): FormBundle<T>
+// bundle = { model, form, render, flow, validating, submission, validate, validateStep, dispose }
+//   (+ служебное validation: { rules, controller } | undefined — его армирует useFormBundle)
+// await bundle.validate()           → ValidationResult (вся форма; замечания показываются)
+// await bundle.validateStep('loan') → ValidationResult (правила шага; неизвестный шаг — исключение)
+// await bundle.submission.submit(handler) → SubmitResult<R> (один прогон; обработчик — только при valid)
+// bundle.submission.submitting      → ReadonlySignal<boolean> (работает обработчик)
+// bundle.flow?.next() / previous() / goTo(id) → FlowTransition
+// bundle.render.tree                → CompiledSchema (см. 37-compiled-schema.md)
+// bundle.dispose()                  → снять сборку: поведение, подписки нод, живую проверку;
+//                                     идущие проверки — cancelled; модель остаётся; идемпотентно
+// useFormBundle(() => createForm(…)) снимает сборку сам — при размонтировании компонента
+
+// Отправка — отдельный объект сборки (`bundle.submission`)
+interface FormSubmission<T> {
+  readonly submitting: ReadonlySignal<boolean>; // работает обработчик; пока идёт проверка — false
+  submit<R>(handler: (values: T) => R | Promise<R>): Promise<SubmitResult<R>>;
+}
+// Без сборки (визард в разметке без createForm): check: undefined — отправка без проверки
+createSubmission<T>(dependencies: {
+  check: (() => Promise<ActionCheck<T>>) | undefined; // ActionCheck = { result, values, stale }
+  values: () => T;
+}): FormSubmission<T>
+
+// Низкоуровневая фабрика: форма из готовых модели и дерева, без уровня формы
+createFormFromModel<T>({ model, schema?, behavior? }): FormGroup<T>
+disposeForm<T>(form: FormGroup<T>): void // снять такую форму: поведение и подписки нод; модель остаётся
 ```
 
+### Form nodes
+
+Ноды строит сборка; прикладной код работает с ними через интерфейсы. Классов нод в публичном
+API нет — вид ноды узнают гардами `isFormControl` / `isFormGroup` / `isFormArray`.
+
+```typescript
+interface FormNode<T> {
+  readonly value: ReadonlySignal<T>;
+  readonly valid: ReadonlySignal<boolean>;   // нет блокирующих замечаний, не disabled, не pending (у поля, группы и массива одинаково)
+  readonly invalid: ReadonlySignal<boolean>;
+  readonly pending: ReadonlySignal<boolean>; // идёт async-правило
+  readonly disabled: ReadonlySignal<boolean>;
+  readonly touched: ReadonlySignal<boolean>;
+  readonly dirty: ReadonlySignal<boolean>;
+  readonly issues: ReadonlySignal<readonly ValidationIssue[]>; // у группы и массива — свои и детей
+  readonly ownIssues: ReadonlySignal<readonly ValidationIssue[]>; // только свои: правила на ручке группы/массива
+  getValue(): T;
+  setValue(value: T): void;                 // пишет в модель
+  reset(value?: T): void;                   // значение и состояние — к начальным
+  markAsTouched(): void;                    // у группы — каскадно
+  markAsUntouched(): void;
+  enable(): void;
+  disable(): void;
+  setIssues(issues: readonly ValidationIssue[]): void; // ответ сервера, своя проверка
+  clearIssues(): void;
+}
+
+interface FormControl<T> extends FormNode<T> {
+  readonly component: ComponentRef | undefined;
+  readonly componentProps: ReadonlySignal<Readonly<Record<string, unknown>>>;
+  // invalid && (touched || dirty) — состояние ошибки: aria-invalid, рамка
+  readonly shouldShowError: ReadonlySignal<boolean>;
+  // есть замечания (ошибки ИЛИ предупреждения) && (touched || dirty) — показ текстов замечаний
+  readonly shouldShowIssues: ReadonlySignal<boolean>;
+  updateComponentProps(patch: Record<string, unknown>): void;
+}
+
+interface FormArray<T extends object> extends FormNode<T[]> {
+  readonly length: number;                  // число; чтение в эффекте/computed подписывает
+  at(index: number): FormGroup<T> | undefined;
+  map<R>(fn: (row: FormGroup<T>, index: number) => R): R[];
+  forEach(fn: (row: FormGroup<T>, index: number) => void): void;
+  keyAt(index: number): string;             // стабильный ключ строки — React `key`
+  push(item?: T): void;                     // без значения — по шаблону arrayOf(blank)
+  insert(index: number, item?: T): void;
+  removeAt(index: number): void;
+  move(from: number, to: number): void;
+  swap(first: number, second: number): void;
+  clear(): void;
+}
+
+// Группа: члены FormNode + ноды полей по именам + пространство `$` со всеми полями
+type FormGroup<T> = FormNode<T> & /* поля по именам */ & { readonly $: FormFields<T> };
+// form.email                — FormControl<string>
+// form.address.city         — FormControl<string> (вложенная группа — FormGroup)
+// form.items                — FormArray<Item> (массив объектов); form.tags — FormControl<string[]>
+// form.$.value              — поле, затенённое членом FormNode (value, issues, reset, …)
+```
+
+Поле затеняют только члены `FormNode`: поле данных `value` берётся через `form.$.value`. Имена
+`id`, `status`, `fields`, `submit` — обычные поля (`form.status`).
+
 ### Validators
 
 Валидаторы — **чистые фабрики** из `@reformer/core/validators`: возвращают правило `Rule<T>` =
-`(value) => ValidationError | null` (принимают nullable value). Передаются оператору
-`validate(sig, [required(), min(50000)])` внутри схемы валидации, а **не** в layout-дерево `createForm`.
+`(value: T) => ValidationIssue | null`. Передаются оператору `validate(sig, [required(), min(50000)])`
+внутри схемы валидации, а **не** в схему формы.
 
 ```typescript
-required(options?: { message?: string })
-min(value: number, options?: { message?: string })
-max(value: number, options?: { message?: string })
-minLength(length: number, options?: { message?: string })
-maxLength(length: number, options?: { message?: string })
-email(options?: { message?: string })
-pattern(regex: RegExp, options?: { message?: string })
-url(options?: { message?: string; requireProtocol?: boolean })
-phone(options?: { message?: string; format?: PhoneFormat })
-// Number validator factories
-isNumber(options?: { message?: string })
-integer(options?: { message?: string })
-multipleOf(divisor: number, options?: { message?: string })
-nonNegative(options?: { message?: string })       // value >= 0
-nonZero(options?: { message?: string })            // value !== 0
-// Date validator factories
-isDate(options?: { message?: string })
-minDate(date: Date | string, options?: { message?: string })
-maxDate(date: Date | string, options?: { message?: string })
-pastDate(options?: { message?: string })
-futureDate(options?: { message?: string })
-minAge(years: number, options?: { message?: string })
-maxAge(years: number, options?: { message?: string })
+required(options?: RuleOptions)                       // Rule<unknown>; пусто: null, undefined, '', [], NaN, false
+min(value: number, options?: RuleOptions)             // Rule<number | null | undefined>
+max(value: number, options?: RuleOptions)
+minLength(length: number, options?: RuleOptions)      // Rule<unknown>: строка либо массив
+maxLength(length: number, options?: RuleOptions)
+email(options?: RuleOptions)                          // Rule<string | null | undefined>
+pattern(regex: RegExp, options?: RuleOptions)
+url(options?: RuleOptions & { requireProtocol?: boolean; allowedProtocols?: string[] })
+// url: разбор new URL; localhost, IP, порт, кириллический домен — да; пробелы и userinfo — нет;
+// протоколы по умолчанию http/https (без учёта регистра), чужой — код url_protocol
+phone(options?: RuleOptions & { format?: PhoneFormat })
+// Number validator factories — Rule<number | null | undefined>
+isNumber(options?: RuleOptions)
+integer(options?: RuleOptions)
+multipleOf(divisor: number, options?: RuleOptions)  // делитель 0 / не конечный — RangeError при создании
+nonNegative(options?: RuleOptions)       // value >= 0
+nonZero(options?: RuleOptions)            // value !== 0
+// Date validator factories — Rule<string | Date | null | undefined>
+// строгий формат: Date либо строка YYYY-MM-DD; другие строки (дата-время, ДД.ММ.ГГГГ) — не даты:
+// isDate даёт date_invalid, остальные правила их пропускают. Рождённый 29 февраля в невисокосный
+// год взрослеет 28 февраля (ГК РФ, ст. 192); дата рождения в будущем — minAge даёт date_future
+isDate(options?: RuleOptions)
+minDate(date: Date, options?: RuleOptions)
+maxDate(date: Date, options?: RuleOptions)
+pastDate(options?: RuleOptions)
+futureDate(options?: RuleOptions)
+minAge(years: number, options?: RuleOptions)
+maxAge(years: number, options?: RuleOptions)
+// File validator factories — Rule<unknown>: файл либо массив файлов
+fileType(accept: string, options?: RuleOptions)       // синтаксис accept; «звезда/звезда» — любой файл
+maxFileSize(bytes: number, options?: RuleOptions)
+minFileSize(bytes: number, options?: RuleOptions)
+maxFiles(count: number, options?: RuleOptions)
+minFiles(count: number, options?: RuleOptions)        // [] при count > 0 — замечание, как у minLength
+maxTotalFileSize(bytes: number, options?: RuleOptions)
 ```
 
-Кроме `message`, каждое правило принимает `messageKey` (ключ словаря приложения) и `params`.
-Без `message` правило кладёт в ошибку пустую строку, а текст при отображении берётся из словаря
-локали по коду (`validation.<code>`): «Обязательное поле» под русской локалью, английская фраза без
-провайдера. Явное `message` важнее словаря, но языком не переключается; для локализуемого текста —
-`messageKey`. Подробно — [34-i18n.md](./34-i18n.md).
+Тип значения правила сверяется с типом поля: `validate(model.$.age, [email()])` для числового поля
+не компилируется. Набор правил для поля объявляют типом поля — `Rule<LoanType>[]`,
+`Rule<number | null>[]`: фабрики с более широким типом значения в него присваиваются.
+
+`RuleOptions` — `{ code?: string; params?: Record<string, unknown> }`. Текста у правила нет:
+замечание несёт только код и параметры (`ValidationIssue = { code, params?, severity? }`), а строку
+по коду при отображении даёт словарь — словарь формы (`defineIssueMessages`), затем словарь локали
+(`validation.<code>`): «Обязательное поле» под русской локалью, английская фраза без провайдера.
+Текст конкретного поля — свой код (`required({ code: 'phone.required' })`) и запись в словаре
+формы. Подробно — [36-issue-messages.md](./36-issue-messages.md).
 
-Использование: layout-дерево `createForm` привязывает поля к сигналам, правила живут отдельной
-`ValidationSchema` и гоняются раннером `validateModel` по требованию.
+Использование: схема формы привязывает поля к ручкам модели, правила живут отдельной
+`ValidationDefinition` и уходят в сборку полем `validation`.
 
 ```typescript
-import { createModel, createForm } from '@reformer/core';
-import { defineValidationSchema, validate, validateModel } from '@reformer/core/validation';
+import { createForm, type FormModel, type FormSchemaNode } from '@reformer/core';
+import { defineValidation, validate } from '@reformer/core/validation';
 import { required, min, max, email } from '@reformer/core/validators';
 
-type Loan = { email: string; age: number | null; amount: number | null };
-const model = createModel<Loan>({ email: '', age: null, amount: null });
+interface Loan {
+  email: string;
+  age: number | null;
+  amount: number | null;
+}
 
-// layout-схема createForm НЕ несёт validators — только привязка поля к сигналу + компонент
-const form = createForm({
-  model,
-  schema: {
-    email:  { value: model.$.email,  component: Input },
-    age:    { value: model.$.age,    component: InputNumber },
-    amount: { value: model.$.amount, component: InputNumber },
-  },
+// схема формы правил не несёт — только привязка поля к ручке модели + компонент
+const loanSchema = (model: FormModel<Loan>): FormSchemaNode => ({
+  children: [
+    { model: model.$.email, component: Input },
+    { model: model.$.age, component: InputNumber },
+    { model: model.$.amount, component: InputNumber },
+  ],
 });
 
-// правила — в ОТДЕЛЬНОЙ схеме валидации (не в layout)
-const loanValidation = defineValidationSchema<Loan>(({ model }) => {
-  validate(model.$.email,  [required(), email()]);
-  validate(model.$.age,    [required(), min(18)]);
+// правила — в ОТДЕЛЬНОЙ схеме валидации
+const loanValidation = defineValidation<Loan>(({ model }) => {
+  validate(model.$.email, [required(), email()]);
+  validate(model.$.age, [required(), min(18)]);
   validate(model.$.amount, [min(0), max(1000)]);
 });
 
-const ok = await validateModel(model, loanValidation);   // Promise<boolean>; ошибки сами доедут до form.<field>.errors
+const loan = createForm<Loan>({
+  initial: { email: '', age: null, amount: null },
+  schema: loanSchema,
+  validation: loanValidation,
+});
+
+const result = await loan.validate(); // ValidationResult; замечания сами доедут до loan.form.<field>.issues
+if (result.status === 'valid') send(loan.model.get());
 ```
 
 ### Custom & cross-field validators
 
-Контракт валидации — `@reformer/core/validation`. Схема (`ValidationSchema<T>`) — обычная функция над
-(под)моделью; внутри вызываются свободные операторы, которые сами пишут ошибки в ноды текущего прогона
-(`getNodeForSignal(sig).setErrors(...)` — автор коллектора не видит).
+Контракт валидации — `@reformer/core/validation`. Схема (`ValidationDefinition<T>`) — обычная функция
+над (под)моделью; внутри вызываются операторы, которые сами пишут замечания в сток текущего прогона —
+автор коллектора не видит.
 
 ```typescript
-type Rule<T>      = (value: T, scope: never, root: never) => ValidationError | null;   // scope/root = never (см. ниже)
-type AsyncRule<T> = (value: T, ctx: { signal: AbortSignal }) => Promise<ValidationError | null>;
-type ValidationSchema<T> = (ctx: { model: FormModel<T> }) => void;
+type Rule<T>      = (value: T) => ValidationIssue | null;
+type AsyncRule<T> = (value: T, ctx: { signal: AbortSignal }) => Promise<ValidationIssue | null>;
+
+interface ValidationScope<T> {
+  readonly model: FormModel<T>;
+  // правило над несколькими полями: check получает снимок модели области
+  cross(handle: PathAwareSignal<unknown>, check: (snapshot: T) => ValidationIssue | null): void;
+}
+type ValidationDefinition<T> = (scope: ValidationScope<T>) => void;
 ```
 
-Операторы (ambient — валидны только внутри прогона `validateModel`):
+Операторы (валидны только внутри прогона схемы):
 
 | Оператор | Назначение |
 |---|---|
 | `validate(sig, rules: Rule<T>[])` | синхронные правила поля |
 | `validateAsync(sig, rules: AsyncRule<T>[])` | асинхронные правила (раннер дожидается, прокидывает `AbortSignal`) |
 | `validateWhen(cond: () => boolean, cb: () => void)` | условная ветка: правила внутри активны/гасятся по `cond` (не трогает enable — это поведение) |
-| `cross(sig, fn: (form) => err \| null)` | cross-field; `fn` получает снапшот модели текущего scope (`model.get()`) |
-| `each(arr, itemFn: (im: FormModel<U>) => void)` | per-item по элементам массива модели |
-| `apply(...schemas: ValidationSchema<T>[])` | композиция под-схем над той же моделью |
-| `defineValidationSchema<T>(fn): ValidationSchema<T>` | тонкая identity-обёртка (типизация/discoverability) |
-| `validateModel<T>(model, schema): Promise<boolean>` | внешний раннер (warning не блокирует, устаревший прогон отменяется) |
+| `cross(sig, check)` из аргумента схемы | правило над несколькими полями; `check` получает снимок модели области, тип снимка выведен |
+| `apply(model.$.group, schema)` | правила подформы: схема над типом группы подключается к ручке группы |
+| `applyEach(model.$.items, schema)` | правила строк массива: схема над типом строки |
+| `apply(...schemas: ValidationDefinition<T>[])` | композиция схем над той же моделью |
+| `defineValidation<T>(fn): ValidationDefinition<T>` | тонкая identity-обёртка (типизация/discoverability) |
+
+Прогон. В сборке — уровень формы (`bundle.validate()`, `bundle.validateStep(id)`,
+`bundle.submission.submit(handler)`, см. [38-form-flow.md](./38-form-flow.md)). Без сборки — раннер
+либо контроллер стратегии:
+
+| Функция                                         | Что делает                                                                                                                                 |
+| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `validateModel(model, schema, { touch }?)`      | сбор + разнос; `true` только при статусе `valid`                                                                                           |
+| `runValidation(model, schema)`                  | только сбор: `Promise<ValidationResult>`, ноды не трогает                                                                                  |
+| `applyValidationResult(result, { touch }?)`     | разнос собранного результата по нодам формы                                                                                                |
+| `createFormValidation(model, schema, options?)` | контроллер стратегии: `validate()`, `run(options?)`, `start()`, `dispose()` — см. [33-validation-strategy.md](./33-validation-strategy.md) |
+
+```typescript
+// Контроллер стратегии (@reformer/core/validation)
+controller.validate(): Promise<boolean>; // нейтральная проверка: проверенные поля touched, фаза не меняется
+controller.run(options?: FormValidationRunOptions): Promise<ValidationResult>;
+interface FormValidationRunOptions {
+  touch?: true | 'all'; // 'all' — при отказе (invalid, error) тронуть всю форму
+  submit?: boolean;     // попытка отправки: переводит afterFirstSubmit в живую фазу
+}
 
-> `Rule<T>` намеренно несёт `scope: never, root: never` — так value-only фабрики (`required()` = `(value, model, root)`)
-> и inline `(value) => err` ОБА присваиваются в `Rule<T>[]`, сохраняя проверку типа поля
-> (`validate(model.$.age, [email()])` подсветится). Ментальная модель автора — `(value) => error`.
+// Хук без сборки (@reformer/core/react)
+useFormValidation({ model, schema, strategy?, debounce?, liveAfterSubmit? }): {
+  submit: () => Promise<boolean>;   // попытка отправки: при отказе раскрыта вся форма
+  validate: () => Promise<boolean>; // проверка без отправки: фаза afterFirstSubmit не меняется
+  isValidating: boolean;
+}
+```
+
+```typescript
+type ValidationStatus = 'valid' | 'invalid' | 'cancelled' | 'error';
+
+interface ValidationResult {
+  readonly status: ValidationStatus;
+  /** Замечания по ручке поля `model.$.…`; путь — `handle.__path`. */
+  readonly issues: ReadonlyMap<PathAwareSignal<unknown>, readonly ValidationIssue[]>;
+  /** Правила, которые не вернули результат (сеть, исключение). */
+  readonly failures: readonly { handle: PathAwareSignal<unknown>; error: unknown }[];
+}
+```
+
+- `valid` — блокирующих замечаний нет (`severity: 'warning'` не блокирует);
+- `invalid` — есть блокирующие замечания;
+- `error` — async-правило не вернуло результат: сбой **блокирует**, на поле ставится замечание
+  `{ code: 'ruleFailed' }` («Не удалось проверить поле. Повторите попытку»), причина — в `failures`;
+- `cancelled` — прогон вытеснен более новым по той же паре (модель, схема); такой результат не
+  разносится.
+
+`validateModel` отвечает `false` на всё, кроме `valid`. Различить замечания, сбой и отмену —
+`bundle.validate()` сборки либо `runValidation`:
+
+```typescript
+const result = await bundle.validate();
+if (result.status === 'error') showToast('Не удалось проверить форму, повторите попытку');
+```
+
+Пока идут async-правила поля, его нода в состоянии `pending` (`form.email.pending.value`).
 
 Кастомные правила, cross-field и async — в схеме:
 
 ```typescript
-import { type ValidationError } from '@reformer/core';
+import { type ValidationIssue } from '@reformer/core';
 import {
-  defineValidationSchema, validate, validateAsync, cross,
+  defineValidation, validate, validateAsync,
   type Rule, type AsyncRule,
 } from '@reformer/core/validation';
 import { required } from '@reformer/core/validators';
 
-type Signup = { password: string; confirm: string; email: string };
+interface Signup {
+  password: string;
+  confirm: string;
+  email: string;
+}
 
-// Value-only правило (Rule<T>)
+// Правило значения (Rule<T>)
 const strongPassword: Rule<string> = (value) =>
-  !value || value.length < 8 ? { code: 'too-short', message: 'Минимум 8 символов' } : null;
+  value.length < 8 ? { code: 'password.weak', params: { minLength: 8 } } : null;
 
-// Cross-field: обычная функция над снапшотом модели (model.get()), вешается через cross(sig, fn)
-const passwordsMatch = (f: Signup): ValidationError | null =>
-  f.confirm && f.password && f.confirm !== f.password
-    ? { code: 'mismatch', message: 'Пароли не совпадают' }
+// Правило над несколькими полями: обычная функция над снимком модели
+const passwordsMatch = (signup: Signup): ValidationIssue | null =>
+  signup.confirm && signup.password && signup.confirm !== signup.password
+    ? { code: 'confirm.mismatch' }
     : null;
 
-// Async (AsyncRule<T>): получает { signal }; сетевой сбой → null (submit не блокируется)
+// Async (AsyncRule<T>): получает { signal }. Отклонённый промис — сбой правила: прогон получает
+// статус `error`, поле — замечание `ruleFailed`. Если сетевой сбой не должен блокировать отправку,
+// перехвати его в правиле и верни `null`.
 const emailUnique: AsyncRule<string> = async (value, { signal }) => {
   if (!value) return null;
-  try {
-    const res = await fetch(`/api/check-email?email=${encodeURIComponent(value)}`, { signal });
-    return (await res.json()).available ? null : { code: 'taken', message: 'Email уже зарегистрирован' };
-  } catch {
-    return null;
-  }
+  const response = await fetch(`/api/check-email?email=${encodeURIComponent(value)}`, { signal });
+  return (await response.json()).available
+    ? null
+    : { code: 'email.taken' };
 };
 
-const signupValidation = defineValidationSchema<Signup>(({ model }) => {
+const signupValidation = defineValidation<Signup>(({ model, cross }) => {
   validate(model.$.password, [required(), strongPassword]);
   validate(model.$.confirm, [required()]);
-  cross(model.$.confirm, passwordsMatch);        // ошибка вешается на confirm
+  cross(model.$.confirm, passwordsMatch); // замечание вешается на confirm
   validateAsync(model.$.email, [emailUnique]);
 });
+// Тексты кодов 'password.weak', 'confirm.mismatch', 'email.taken' — в словаре формы
+// (defineIssueMessages), см. 36-issue-messages.md
 ```
 
+> `cross` берётся только из аргумента схемы: из `@reformer/core/validation` он не импортируется.
+
 ### Conditional & array validation
 
-Условные ветки и массивы — операторы `validateWhen` / `each` / `apply` внутри схемы (не узлы дерева):
+Условные ветки, подформы и массивы — операторы внутри схемы (не узлы дерева):
 
 - **условная ветка** `validateWhen(() => cond, () => { validate(...) })` — правила внутри активны только
-  при истинном условии; при ложном ошибки полей ветки гасятся (`setErrors([])`). Enable/сброс поля — дело поведения;
-- **массив** `each(model.arr, (im) => { validate(im.$.field, [...]) })` — правила применяются к каждому
-  элементу; `im` — под-модель элемента. Для cross-field над элементом захватывайте снапшот в замыкание (`const item = im.get()`);
-- **композиция** `apply(...schemas)` — объединяет под-схемы над той же моделью (напр. полную схему из per-step).
+  при истинном условии; при ложном замечания полей ветки гасятся. Enable/сброс поля — дело поведения;
+- **подформа** `apply(model.$.group, groupRules)` — схема над типом группы; принимает и массив ручек;
+- **массив** `applyEach(model.$.items, rowRules)` — схема над типом строки применяется к каждой строке;
+- **композиция** `apply(...schemas)` — объединяет схемы над той же моделью.
+
+У схемы, подключённой через `apply(ручка, схема)` / `applyEach`, своя область: `model` — под-модель,
+`cross` получает её снимок.
 
 ```typescript
 import {
-  defineValidationSchema, validate, validateWhen, cross, each, apply, validateModel,
+  apply, applyEach, defineValidation, validate, validateWhen,
 } from '@reformer/core/validation';
 import { required, min } from '@reformer/core/validators';
 
 // Условная валидация — ипотечная ветка активна только при loanType === 'mortgage'
-const step1 = defineValidationSchema<LoanForm>(({ model }) => {
+const loanRules = defineValidation<LoanForm>(({ model }) => {
   validate(model.$.loanType, [required()]);
   validateWhen(
     () => model.loanType === 'mortgage',
@@ -192,64 +374,46 @@ const step1 = defineValidationSchema<LoanForm>(({ model }) => {
   );
 });
 
-// Per-item валидация элементов массива (each над ModelArray)
-const step5 = defineValidationSchema<LoanForm>(({ model }) => {
-  each(model.coBorrowers, (im) => {
-    const item = im.get();                          // снапшот элемента для cross
-    validate(im.$.income, [required(), min(10_000)]);
-    cross(im.$.income, () =>
-      item.income < item.loanShare ? { code: 'tooLow', message: 'Доход ниже доли' } : null);
-  });
+// Правила строки массива — отдельная схема над типом строки
+const coBorrowerRules = defineValidation<CoBorrower>(({ model, cross }) => {
+  validate(model.$.income, [required(), min(10_000)]);
+  cross(model.$.income, (coBorrower) =>
+    coBorrower.income < coBorrower.loanShare ? { code: 'income.tooLow' } : null);
 });
 
-// Полная схема формы = композиция шагов (apply над той же моделью)
-const formValidation = defineValidationSchema<LoanForm>(() => apply(step1, step5));
+const additionalRules = defineValidation<LoanForm>(({ model }) => {
+  applyEach(model.$.coBorrowers, coBorrowerRules);
+});
 ```
 
-Wizard-конфиг (per-step + полная валидация) — поверх того же раннера `validateModel`:
+Пошаговая и полная валидация — поток шагов сборки: `flow.steps[].id` — `selector` шага в схеме,
+`validation.extras` — правила вне шагов.
 
 ```typescript
-const STEP_SCHEMAS = [step1, /* step2, … */ step5] as const;
+const loan = createForm<LoanForm>({
+  initial,
+  schema: loanSchema,
+  validation: { extras: crossStepRules }, // правила всей формы — проверяются только целиком
+  flow: {
+    steps: [
+      { id: 'loan', rules: loanRules }, // id = selector узла шага
+      { id: 'additional', rules: additionalRules },
+    ],
+  },
+});
 
-function makeValidationConfig(model: FormModel<LoanForm>) {
-  return {
-    validateStep: (n: number) => validateModel(model, STEP_SCHEMAS[n - 1]),
-    validateAll: () => validateModel(model, formValidation),   // formValidation = apply(...STEP_SCHEMAS, extras)
-  };
-}
+await loan.validateStep('loan'); // правила одного шага → ValidationResult
+await loan.validate(); // все шаги + extras → ValidationResult
+await loan.flow?.next(); // проверить текущий шаг и перейти → FlowTransition
+loan.validating.value; // идёт ли проверка — полная либо шага
 ```
 
-Операторы `validate`/`validateAsync`/`validateWhen`/`cross`/`each`/`apply` экспортируются напрямую из
-`@reformer/core/validation` — это публичный API, а не локальный сахар примера.
+Подробно — [13-multi-step.md](./13-multi-step.md) и [38-form-flow.md](./38-form-flow.md).
 
 ### Behaviors
 
-Два способа. **Примитивы из `@reformer/core`** (принимают сигналы, возвращают cleanup):
-
-```typescript
-computeFrom(sources: ReadonlySignal[], target: Signal, fn: (...vals) => R, options?: { when?: (...vals) => boolean }): () => void
-copyFrom(source: ReadonlySignal, target: Signal, options?: { when?: () => boolean; transform?: (v) => v }): () => void
-watchField(source: ReadonlySignal, cb: (value) => void, options?: { immediate?: boolean }): () => void
-enableWhen(target: ReadonlySignal, condition: () => boolean, options?: { resetOnDisable?: boolean }): () => void
-disableWhen(target: ReadonlySignal, condition: () => boolean, options?: { resetOnDisable?: boolean }): () => void
-transformValue(target: Signal, transformer: (value) => value): () => void
-resetWhen(target: Signal, condition: () => boolean, options?: { resetValue?: T }): () => void
-syncFields(a: Signal, b: Signal, options?: { transform?: (v) => v }): () => void
-revalidateWhen(deps: ReadonlySignal[], revalidate: () => void): () => void
-```
-
-```typescript
-import { computeFrom, enableWhen, copyFrom } from '@reformer/core';
-
-const cleanups = [
-  computeFrom([model.$.price, model.$.quantity], model.$.total, (p, q) => p * q),
-  enableWhen(model.$.city, () => Boolean(model.country), { resetOnDisable: true }),
-  copyFrom(model.$.email, model.$.emailAdditional, { when: () => model.sameEmail === true }),
-];
-// при teardown: cleanups.forEach((c) => c());
-```
-
-**Декларативный DSL из `@reformer/core/behaviors`** (регистрирует cleanup сам, передаётся в `createForm({ behavior })`):
+**Поведение формы — декларативный DSL из `@reformer/core/behaviors`** (регистрирует cleanup сам,
+передаётся в `createForm({ behavior })`):
 
 ```typescript
 import { defineFormBehavior, compute, enableWhen, onChange } from '@reformer/core/behaviors';
@@ -262,15 +426,66 @@ const behavior = defineFormBehavior<MyForm>(({ model, form }) => {
   });
 });
 
-const form = createForm({ model, schema, behavior });
+const { form } = createForm<MyForm>({ initial, schema, behavior });
 ```
 
+Область поведения — `{ model, form, schema, flow }`: `schema` адресует узлы своей области
+(`schema.node(selector)`), `flow` — поток шагов сборки (без `flow` в конфиге — `undefined`).
+
 DSL-операторы: `compute` (auto-tracking, без явного списка источников), `computeFrom`, `copyFrom`,
 `onChange` (реакция на изменение; `{ debounce, immediate }`, 2-й аргумент колбэка — `{ signal }` AbortSignal),
 `enableWhen`/`disableWhen`, `transformValue`, `resetWhen`, `syncFields`, `revalidateWhen`,
-`apply` (под-схема для группы), `applyEach` (per-item для массива), `exclusiveFlag`, `aggregateInto`.
+`apply` (поведение подформы), `applyEach` (поведение строки массива), `exclusiveFlag`, `aggregateInto`;
+операторы узлов схемы — `hideWhen`, `onComponentEvent`, `onMount`, `onUnmount`, `onInit`, `renderEffect`.
 См. `20-compute-vs-watch.md`.
 
+- `copyFrom` групп разной формы — как `set` группы модели: поля цели, которых нет в значении
+  источника, остаются прежними; в dev — одно предупреждение на оператор. Значение цели целиком
+  собирает `transform`.
+- `exclusiveFlag`: выбор строки (флаг стал `true`) снимает флаг у остальных. Строка, пришедшая с
+  `true` (начальные данные, добавленная), прежний выбор не снимает — флаг сбрасывается у неё; из
+  нескольких пришедших сразу остаётся первая.
+- Ручка не того вида — в dev ошибка с путём: `applyEach` / `exclusiveFlag` / `aggregateInto` ждут
+  массив, `apply` — группу. `enableWhen` / `disableWhen` на поле без ноды формы ничего не делают;
+  в dev — предупреждение.
+
+**Примитивы над сигналами — `@reformer/core/model`** (принимают сигналы, возвращают cleanup; в корне
+`@reformer/core` их нет). Нужны вне формы — там, где нет области поведения:
+
+```typescript
+computeFrom(sources: ReadonlySignal[], target: Signal, fn: (...vals) => R, options?: { when?: (...vals) => boolean }): () => void
+copyFrom(source: ReadonlySignal, target: Signal, options?: { when?: () => boolean; transform?: (v) => v }): () => void
+watchField(source: ReadonlySignal, cb: (value) => void, options?: { immediate?: boolean }): () => void
+transformValue(target: Signal, transformer: (value) => value): () => void
+resetWhen(target: Signal, condition: () => boolean, options?: { resetValue?: T }): () => void // resetValue обязателен, если null не в типе поля
+syncFields(a: Signal, b: Signal, options?: { transform?: (v) => v }): () => void
+revalidateWhen(deps: ReadonlySignal[], revalidate: () => void): () => void
+```
+
+Утилиты значений там же, в `@reformer/core/model`:
+
+```typescript
+// сравнение значений модели: объекты и массивы — по содержимому, даты — по времени, NaN равен себе;
+// на нём стоят isDirty и сверка «модель изменилась, пока шла проверка» при отправке и переходе шага
+deepEqual(first: unknown, second: unknown): boolean
+// дождаться отложенных записей поведения текущего тика (onChange, resetOnDisable);
+// undefined — ждать нечего
+deferredWritesSettled(): Promise<void> | undefined
+```
+
+```typescript
+import { computeFrom, copyFrom } from '@reformer/core/model';
+
+const cleanups = [
+  computeFrom([model.$.price, model.$.quantity], model.$.total, (price, quantity) => price * quantity),
+  copyFrom(model.$.email, model.$.emailAdditional, { when: () => model.sameEmail === true }),
+];
+// при teardown: cleanups.forEach((cleanup) => cleanup());
+```
+
+`enableWhen` / `disableWhen` работают с состоянием ноды формы и существуют только как операторы
+поведения (`@reformer/core/behaviors`).
+
 Поведение **не владеет** валидацией — это отдельный слой. Мост «поведение инициирует валидацию» — через
 `revalidateWhen`, который просто вызывает внешний раннер валидации: