@reformer/core 10.2.0 → 11.0.0-beta.2

package/docs/llms/30-type-safety-recipes.md

@@ -0,0 +1,159 @@
+## 30. TYPE-SAFETY RECIPES
+
+Идиоматичные паттерны, которые держат сгенерированный код без `any` и `as`-кастов под M1.
+
+### Recipe 1 — Imports (root cause prevention)
+
+- Модель/форма/хуки/типы/**примитивы behaviors** — из `@reformer/core`.
+- Схема валидации (операторы + раннер `validateModel`) — из `@reformer/core/validation`.
+- Чистые фабрики валидаторов — из `@reformer/core/validators`.
+- Декларативный DSL (`defineFormBehavior` + операторы) — из `@reformer/core/behaviors`.
+
+```typescript
+import {
+  createModel,
+  createForm,
+  type FormModel,
+  type FormProxy,
+  type ModelSignals,
+} from '@reformer/core';
+import {
+  defineValidationSchema,
+  validate,
+  cross,
+  validateModel,
+  type Rule,
+} from '@reformer/core/validation';
+import { required, min, max, email } from '@reformer/core/validators';
+import { defineFormBehavior, compute, enableWhen, onChange } from '@reformer/core/behaviors';
+```
+
+> **watchField — из `@reformer/core`** (примитив), НЕ из `@reformer/core/behaviors` (там `onChange`).
+
+### Recipe 2 — Form-shape types as `type`, not `interface`
+
+`Record<string, FormValue>` требует index signature. У `interface` её нет неявно; у `type` —
+структурно. Объявляй через `type`-alias всё, что попадает в `FormProxy<T>`/`ArrayNode<T>`:
+корневую форму, вложенные группы, типы элементов массива.
+
+```typescript
+export type PropertyItem = {
+  type: 'apartment' | 'house' | 'car';
+  description: string;
+  estimatedValue: number;
+};
+
+export type CreditApplicationForm = {
+  loanAmount: number | null;
+  properties: PropertyItem[];
+  // ...
+};
+```
+
+### Recipe 3 — Схема привязана к сигналам модели
+
+`value` поля — это сигнал модели (`model.$.field`), а не литерал. Тип поля выводится из сигнала.
+Layout-схема БЕЗ валидаторов — правила живут в отдельной validation-схеме.
+
+```typescript
+const model = createModel<CreditApplicationForm>(initial);
+
+const schema = {
+  loanAmount: { value: model.$.loanAmount, component: Input },
+  // вложенная группа — builder, принимающий ModelSignals<Sub>
+  personalData: personalDataNodes(model.$.personalData),
+  // массив — { array, item }
+  properties: { array: model.properties, item: propertyItem },
+};
+
+// правила — отдельно; типы полей выводятся из сигналов
+const validation = defineValidationSchema<CreditApplicationForm>(({ model }) => {
+  validate(model.$.loanAmount, [required(), min(50000)]);
+});
+```
+
+### Recipe 4 — Cross-field валидаторы: `cross` над типизированным снапшотом
+
+Правило — обычная функция `(f: Root) => ValidationError | null` над снапшотом `model.get()`.
+Соседние поля читаются без `as`; ошибка вешается на поле-носитель `sig`:
+
+```typescript
+import type { ValidationError } from '@reformer/core';
+
+const initialPaymentVsProperty = (f: CreditApplicationForm): ValidationError | null =>
+  f.initialPayment && f.propertyValue && f.initialPayment > f.propertyValue
+    ? { code: 'tooHigh', message: 'Взнос не может превышать стоимость' }
+    : null;
+
+// внутри defineValidationSchema<CreditApplicationForm>(({ model }) => { ... }):
+cross(model.$.initialPayment, initialPaymentVsProperty);
+```
+
+### Recipe 5 — `compute` читает модель напрямую (без аннотаций)
+
+`compute(target, () => …)` читает value-модель (`model.field`) — типы полей выводятся из типа
+модели, `as`-касты не нужны:
+
+```typescript
+compute(model.$.monthlyPayment, () =>
+  annuityMonthly(model.loanAmount ?? 0, model.loanTerm ?? 0, model.interestRate ?? 0)
+);
+
+// nested reads — тоже напрямую
+compute(model.$.fullName, () =>
+  [model.personalData.firstName, model.personalData.lastName].filter(Boolean).join(' ')
+);
+```
+
+### Recipe 6 — `null` vs `undefined` для опциональных полей
+
+Оба работают. `null` — конвенция «пользователь очистил поле». Встроенные валидаторы
+(`min`, `max`, `minLength`, `maxLength`, `minDate`, `maxDate`, `minAge`, `maxAge`) пропускают
+пустые значения — guard `if (value != null)` не нужен.
+
+```typescript
+export type CreditForm = {
+  loanAmount: number | null;   // min(model.$.loanAmount, 50000) — ок
+  loanPurpose: string | null;  // minLength — ок
+  birthDate: string | null;    // minAge — ок
+};
+```
+
+### Recipe 7 — Нода поля для кастомных компонентов
+
+`useFormControl(control)` типизируется по `FieldNode<T>`. В props компонента используй `FieldNode<T>`:
+
+```typescript
+import type { FieldNode } from '@reformer/core';
+
+type MyFieldProps<T> = { control: FieldNode<T> };
+function MyField<T>({ control }: MyFieldProps<T>) {
+  const { value, errors, disabled } = useFormControl(control);
+  // ...
+}
+```
+
+### Recipe 8 — Вынос правил в именованные функции
+
+Field-правила — именованные `Rule<T>`, validation-схема остаётся плоской:
+
+```typescript
+import type { Rule } from '@reformer/core/validation';
+
+const validateAdultAge: Rule<string | null> = (value) => {
+  if (!value) return null;
+  const age = new Date().getFullYear() - new Date(value).getFullYear();
+  return age < 18 ? { code: 'tooYoung', message: 'Минимум 18 лет' } : null;
+};
+
+// внутри defineValidationSchema<MyForm>(({ model }) => { ... }):
+validate(model.$.birthDate, [validateAdultAge]);
+```
+
+### Anti-patterns to avoid
+
+- `import { computeFrom } from '@reformer/core/behaviors'` для примитива, вызываемого вне
+  `defineFormBehavior` → примитив живёт в `@reformer/core` (возвращает cleanup).
+- `interface MyForm { ... }` для form-shape → см. Recipe 2.
+- `as`-касты значений полей внутри `compute` → читай `model.field` напрямую (Recipe 5).
+- строковые пути / `(form) => ...` в behaviors → это удалённый API, используй сигналы (`model.$.x`).

package/docs/llms/31-async-validator-debounce.md

@@ -0,0 +1,135 @@
+## 31. ASYNC VALIDATOR
+
+Для проверок типа «уникальность email», «валидация ИНН через API», «проверка адреса» —
+async-правило это `AsyncRule<T>` = `(value, { signal }) => Promise<ValidationError | null>`.
+Оно регистрируется оператором `validateAsync(sig, [asyncRules])` внутри схемы валидации
+(`@reformer/core/validation`) и исполняется внешним раннером `validateModel` (async-правила
+прогоняются параллельно через `Promise.all`, раннер их дожидается).
+
+Слои разделены: layout (`createForm`-схема / JSON) НЕ несёт валидаторов — правила живут в
+отдельной функции-схеме `defineValidationSchema<T>(({ model }) => …)`.
+
+```ts
+import { createModel } from '@reformer/core';
+import {
+  validate,
+  validateAsync,
+  defineValidationSchema,
+  validateModel,
+  type AsyncRule,
+} from '@reformer/core/validation';
+import { required, email } from '@reformer/core/validators';
+
+// async-правило: (value, { signal }) => Promise<ValidationError | null>.
+// `signal` — AbortSignal устаревшего прогона: прокинь его в fetch, чтобы отменить in-flight.
+const checkEmailUnique: AsyncRule<string> = async (value, { signal }) => {
+  if (!value) return null; // пусто = валидно (sync `required` отдельно)
+  try {
+    const res = await fetch(`/api/check-email?email=${encodeURIComponent(value)}`, { signal });
+    const { available } = (await res.json()) as { available: boolean };
+    return available ? null : { code: 'email-taken', message: 'Email уже зарегистрирован' };
+  } catch {
+    return null; // сетевой сбой/отмена НЕ блокирует submit — возвращаем null, а не ошибку
+  }
+};
+
+const model = createModel<{ email: string }>({ email: '' });
+
+// Схема — обычная функция над моделью; sync и async — разными операторами на одном сигнале.
+const schema = defineValidationSchema<{ email: string }>(({ model }) => {
+  validate(model.$.email, [required(), email()]); // sync-фабрики
+  validateAsync(model.$.email, [checkEmailUnique]); // async-правило
+});
+
+// Прогон по требованию (submit / шаг):
+const ok = await validateModel(model, schema); // Promise<boolean>
+```
+
+### Как это исполняется
+
+1. `validateModel(model, schema)` открывает ambient-окно и **синхронно** прогоняет схему:
+   `validate`/`validateAsync`/`cross` регистрируют правила своих полей.
+2. Sync-правила выполняются сразу; async-правила из `validateAsync` собираются и после закрытия
+   ambient-окна дожидаются параллельно (`Promise.all`) с прокинутым `AbortSignal`.
+3. Ошибки роутятся в ноды формы (`getNodeForSignal(sig).setErrors(...)`), UI подсвечивает поле;
+   поля, ставшие валидными, гасятся (`setErrors([])`).
+4. Возвращает `Promise<boolean>` — `true`, если нет блокирующих ошибок (`severity:'warning'`
+   не блокирует). Устаревший (отменённый) прогон возвращает `false` — ему нельзя доверять для submit.
+
+Синхронного варианта у нового контракта нет: раннер один — `validateModel`, и он всегда `async`.
+
+### Sync и async — два оператора
+
+Разделение sync/async делается не полем схемы, а разными операторами на одном сигнале:
+`validate(sig, [syncRules])` и `validateAsync(sig, [asyncRules])`. Раннер прогоняет sync-правила
+инлайн, а async — дожидается. Держи async-правило дешёвым: ранний `if (!value) return null`
+пропускает сетевой вызов, пока `required()`/формат ещё не пройдены.
+
+```ts
+validate(model.$.inn, [required(), pattern(/^\d{12}$/)]); // формат — sync, мгновенно
+validateAsync(model.$.inn, [checkInnInRegistry]); // обращение к API — отдельным оператором
+```
+
+### UI integration
+
+`validateModel(...)` возвращает `Promise<boolean>` — индикатор проверки держи вокруг этого
+`await`. Раннер схемы **не** выставляет per-field `pending` на ноде (он роутит только ошибки через
+`setErrors`), поэтому спиннер async-валидации — это собственный флаг (обычно form-level, как
+`ui.pending` в submit-флоу, или локальный state компонента):
+
+```tsx
+const [checking, setChecking] = useState(false);
+
+const runValidation = async (): Promise<boolean> => {
+  setChecking(true);
+  try {
+    return await validateModel(model, schema);
+  } finally {
+    setChecking(false);
+  }
+};
+
+return checking ? <Spinner /> : errors.length ? <Error errors={errors} /> : null;
+```
+
+### Debounce и отмена
+
+- **Отмена устаревших — раннером, бесплатно.** Быстрый повторный `validateModel(model, schema)`
+  той же пары `(model, schema)` отменяет предыдущий in-flight прогон через `AbortController`;
+  его `AbortSignal` прокинут в `validateAsync`-правила, поэтому `fetch(url, { signal })` рвётся
+  сам. Ручной debounce для КОРРЕКТНОСТИ не нужен — держи схему стабильным `const`
+  (`defineValidationSchema`), иначе отмена не сматчит прогоны по идентичности.
+- Валидация запускается on-demand (submit / шаг / через `revalidateWhen`), а не на каждый
+  keystroke — отдельный `debounce` в правиле обычно не нужен.
+- Если нужно дебаунсить дорогой async-валидатор относительно частых изменений — триггерь прогон
+  из поведения через `onChange`, который даёт debounce из коробки:
+
+  ```ts
+  import { defineFormBehavior, onChange } from '@reformer/core/behaviors';
+  import { validateModel } from '@reformer/core/validation';
+
+  export const behavior = defineFormBehavior<{ username: string }>(({ model }) => {
+    onChange(model.$.username, () => void validateModel(model, schema), { debounce: 300 });
+  });
+  ```
+
+  Либо оборачивай в свой debounce колбэк `revalidateWhen([...], () => void validateModel(...))`.
+- **Async cross-field** — инлайн `validateAsync`-правило, замыкающее `model` и читающее снапшот
+  соседей `model.get()` до первого `await` (у `AsyncRule` нет `root`, только `value` + `signal`;
+  `cross(...)` — синхронный):
+
+  ```ts
+  validateAsync(model.$.email, [
+    async (email, { signal }) => {
+      const { username } = model.get(); // снапшот соседних полей до await
+      const res = await fetch(`/api/check?email=${email}&user=${username}`, { signal });
+      return (await res.json()).ok ? null : { code: 'conflict', message: 'Пара занята' };
+    },
+  ]);
+  ```
+
+### See also
+
+- [27-revalidate-when.md](27-revalidate-when.md) — перезапуск `validateModel` по триггерам
+- [29-async-preload.md](29-async-preload.md) — async preload данных при init формы
+- [32-async-options-loading.md](32-async-options-loading.md) — `onChange` с debounce + AbortSignal

package/docs/llms/32-async-options-loading.md

@@ -0,0 +1,108 @@
+## 32. ASYNC OPTIONS LOADING
+
+Для динамической подгрузки опций dropdown'а по значению другого поля (`region` → `city options`,
+`carBrand` → `carModel options`) — используй `onChange` из `@reformer/core/behaviors` +
+`form.field.updateComponentProps({ options })`. `onChange` даёт debounce и AbortSignal из коробки.
+
+```ts
+import { defineFormBehavior, onChange } from '@reformer/core/behaviors';
+
+type CityOption = { value: string; label: string };
+
+async function fetchCitiesByRegion(region: string, opts?: { signal?: AbortSignal }): Promise<CityOption[]> {
+  const res = await fetch(`/api/cities?region=${encodeURIComponent(region)}`, { signal: opts?.signal });
+  return res.json();
+}
+
+export const behavior = defineFormBehavior<MyForm>(({ model, form }) => {
+  onChange(
+    model.$.registrationAddress.region,
+    async (region, { signal }) => {
+      // сбросить зависимое поле при смене source
+      model.registrationAddress.city = '';
+
+      if (!region) {
+        form.registrationAddress.city.updateComponentProps({ options: [] });
+        return;
+      }
+
+      // (опционально) loading-состояние
+      form.registrationAddress.city.updateComponentProps({ loading: true, options: [] });
+
+      try {
+        const options = await fetchCitiesByRegion(region, { signal }); // отмена устаревших
+        form.registrationAddress.city.updateComponentProps({ loading: false, options });
+      } catch (e) {
+        if ((e as Error).name === 'AbortError') return; // устаревший запрос — молча выходим
+        form.registrationAddress.city.updateComponentProps({ loading: false, options: [] });
+      }
+    },
+    { debounce: 300 }
+  );
+});
+```
+
+### Lifecycle
+
+1. `onChange` подписан на изменения `model.$.region`.
+2. Debounce 300 мс (не fetch на каждое нажатие клавиши).
+3. Async `fetchCitiesByRegion(region, { signal })` — `signal` отменяет устаревший запрос при
+   следующей смене значения (защита от race).
+4. Результат — `updateComponentProps({ options })` на target-поле.
+5. UI (Select / Combobox) обновляется через сигнал `componentProps`.
+
+### Переиспользуемый оператор
+
+Как в монорепо — собираешь свой оператор поверх `onChange`:
+
+```ts
+import { onChange } from '@reformer/core/behaviors';
+import type { ReadonlySignal } from '@reformer/core/behaviors';
+
+function loadOptionsOn<TValue, TOption>(
+  source: ReadonlySignal<TValue>,
+  target: { updateComponentProps(p: Record<string, unknown>): void; reset?: () => void },
+  fetcher: (value: TValue, opts?: { signal?: AbortSignal }) => Promise<TOption[]>,
+  options: { debounce?: number; resetTarget?: boolean } = {}
+): void {
+  const { debounce = 300, resetTarget = false } = options;
+  onChange(
+    source,
+    async (value, { signal }) => {
+      if (resetTarget) target.reset?.();
+      if (!value) { target.updateComponentProps({ options: [] }); return; }
+      try {
+        const data = await fetcher(value, { signal });
+        target.updateComponentProps({ options: data });
+      } catch {
+        target.updateComponentProps({ options: [] });
+      }
+    },
+    { debounce }
+  );
+}
+
+// Usage:
+loadOptionsOn(model.$.carBrand, form.carModel, fetchCarModels, { resetTarget: true });
+```
+
+### Common patterns
+
+- **Debounce 300–500 мс** — баланс UX и rate-limit.
+- **Reset target value** — при смене source очисти зависимое поле (`model.city = ''`), чтобы не
+  остался устаревший выбор.
+- **Loading state** — `updateComponentProps({ loading: true })` пока идёт fetch (компонент должен поддержать).
+- **Cancellation** — `onChange` даёт `{ signal }` (AbortSignal); передавай его в `fetch` и
+  игнорируй `AbortError`.
+
+### Initial load (preload at form mount)
+
+Для загрузки опций при инициализации формы — external hook + `model.set` + `updateComponentProps`
+(см. [29-async-preload.md](29-async-preload.md)). `onChange` не срабатывает на init (по умолчанию
+`immediate: false`); для запуска сразу передай `{ immediate: true }`.
+
+### See also
+
+- [11-async-watchfield.md](11-async-watchfield.md) — общий паттерн `onChange`
+- [29-async-preload.md](29-async-preload.md) — preload данных при инициализации
+- [31-async-validator-debounce.md](31-async-validator-debounce.md) — async **валидация** (не options)

package/docs/llms/33-validation-strategy.md

@@ -0,0 +1,193 @@
+# useFormValidation — Единый выбор стратегии валидации
+
+## Purpose
+
+Одна декларативная точка выбора «когда прогонять схему валидации» вместо ручной разводки
+`markAsTouched` + `validateModel` + `revalidateWhen` + `useState(pending)`. Аддитивный слой над
+функциональной схемой (`@reformer/core/validation`): переиспользует `validateModel` как
+ЕДИНСТВЕННЫЙ движок (роутинг ошибок в ноды, отмена устаревших прогонов, дедуп по `(model, schema)`),
+второго движка не заводит. Node-level `updateOn` / `debounce` на самой ноде поля (legacy-триггеры)
+этот API НЕ трогает.
+
+Стратегия определяет только момент запуска и раскрытие ошибок — сами правила остаются в отдельной
+`defineValidationSchema<T>(({ model }) => …)`.
+
+## API
+
+Основной способ — React-хук `useFormValidation` из `@reformer/core` (рядом с `useFormControl`).
+Под ним — headless-фабрика `createFormValidation` из `@reformer/core/validation` (для SSR / тестов /
+не-React потребителей).
+
+```typescript
+// React (@reformer/core)
+function useFormValidation<T>(args: {
+  model: FormModel<T>;
+  schema: ValidationSchema<T>;         // СТАБИЛЬНАЯ ссылка (module-level const / useMemo)
+  strategy?: ValidationStrategyKind;   // default 'submit'
+  debounce?: number;                   // мс, для live-фаз (change / live-часть afterFirstSubmit)
+  liveAfterSubmit?: 'change' | 'blur'; // default 'change'
+}): { submit: () => Promise<boolean>; validate: () => Promise<boolean>; isValidating: boolean };
+
+// headless (@reformer/core/validation)
+type ValidationStrategyKind = 'submit' | 'blur' | 'change' | 'afterFirstSubmit';
+interface ValidationStrategyOptions {
+  strategy?: ValidationStrategyKind;
+  debounce?: number;
+  liveAfterSubmit?: 'change' | 'blur';
+}
+interface FormValidationController {
+  validate(): Promise<boolean>;        // полный прогон, touch:true (раскрыть ВСЕ ошибки); переводит afterFirstSubmit в live-фазу
+  start(): () => void;                 // армит реактивные подписки (ТОЛЬКО на клиенте) → dispose
+  dispose(): void;
+  readonly isValidating: boolean;
+  readonly validating: ReadonlySignal<boolean>;
+}
+function createFormValidation<T>(
+  model: FormModel<T>,
+  schema: ValidationSchema<T>,
+  options?: ValidationStrategyOptions,
+): FormValidationController;
+```
+
+- `useFormValidation` мемоизирует контроллер по `[model, schema, strategy, debounce, liveAfterSubmit]`,
+  армит стратегию в `useEffect` (SSR-safe), а `submit()` = `controller.validate()`.
+- `createFormValidation` ЧИСТА до `start()` (никаких подписок) → SSR-safe; `start()` возвращает
+  `dispose` и арминует триггеры только на клиенте.
+
+### Стратегии
+
+| strategy | когда прогон | touch | раскрытие ошибок |
+| --- | --- | --- | --- |
+| `submit` (default) | только `validate()` / `submit()` | `true` | всё на submit |
+| `blur` | смена `touched` поля (потеря фокуса) | `false` | только сблюренные (по `touched`) |
+| `change` | на каждый ввод (+ `debounce`) | `false` | только редактированные (по `dirty`) |
+| `afterFirstSubmit` | тихо до 1-го submit, затем live (`liveAfterSubmit: 'change'` \| `'blur'`, default `'change'`) | `true` один раз на 1-м submit, дальше `false` | тихо → раскрыть всё на submit → далее live |
+
+## Examples
+
+### Простая форма — afterFirstSubmit + debounce
+
+Тихо до первой отправки, `submit()` раскрывает все ошибки и переводит форму в живую фазу
+(дальше проверка на ввод с задержкой 400 мс). `submit()` сам метит `touched` — ручной
+`markAsTouched` не нужен.
+
+```tsx
+import { createModel, createForm, useFormValidation } from '@reformer/core';
+import { defineValidationSchema, validate } from '@reformer/core/validation';
+import { required, email, minLength } from '@reformer/core/validators';
+
+type RegistrationData = { username: string; email: string; password: string };
+
+// Схема — стабильный module-level const (иначе ломается дедуп раннера).
+const registrationValidation = defineValidationSchema<RegistrationData>(({ model }) => {
+  validate(model.$.username, [required(), minLength(3)]);
+  validate(model.$.email, [required(), email()]);
+  validate(model.$.password, [required(), minLength(8)]);
+});
+
+function RegistrationForm() {
+  const model = useMemo(() => createModel<RegistrationData>({ username: '', email: '', password: '' }), []);
+  const form = useMemo(() => createForm({ model }), [model]);
+
+  const { submit, isValidating } = useFormValidation({
+    model,
+    schema: registrationValidation,
+    strategy: 'afterFirstSubmit',
+    debounce: 400,
+  });
+
+  const onSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    if (await submit()) await api.save(model.get()); // true = нет блокирующих ошибок
+  };
+
+  return (
+    <form onSubmit={onSubmit}>
+      <FormField control={form.username} />
+      <FormField control={form.email} />
+      <FormField control={form.password} />
+      <button type="submit" disabled={isValidating}>Отправить</button>
+    </form>
+  );
+}
+```
+
+### Wizard — live-стратегия внутри активного шага
+
+`defineSteps(..., { strategy })` задаёт ЖИВУЮ стратегию ВНУТРИ шага; `useWizardStepValidation`
+арминует её под текущий шаг (`currentStep` из `FormWizardContext`) и снимает при смене шага / unmount.
+Per-step gate (`validateStep` на «Далее») и `validateAll` (submit) при этом НЕ меняются — стратегия
+добавляет живой слой ПОВЕРХ них. No-op, если `strategy` не задана / `'submit'` / у шага нет правил.
+
+```tsx
+import { defineSteps, useWizardStepValidation, FormWizard } from '@reformer/cdk/form-wizard';
+
+const config = defineSteps<'loan' | 'applicant' | 'confirm', CreditForm>(model, {
+  steps: { loan: loanStep, applicant: applicantStep, confirm: null }, // confirm — без правил, ЯВНО
+  extras: crossFieldRules,   // применяются только в validateAll (submit)
+  strategy: 'blur',          // живая валидация полей текущего шага при потере фокуса
+});
+
+function LoanStepBody() {
+  useWizardStepValidation(config); // армит 'blur' под активный шаг, снимает при переходе
+  return <>{/* поля шага */}</>;
+}
+
+<FormWizard form={form} config={config}>
+  <LoanStepBody />
+</FormWizard>;
+```
+
+### Headless / SSR / тесты — createFormValidation
+
+```typescript
+import { createFormValidation } from '@reformer/core/validation';
+
+const ctrl = createFormValidation(model, registrationValidation, {
+  strategy: 'afterFirstSubmit',
+  debounce: 300,
+});
+const dispose = ctrl.start();        // ТОЛЬКО на клиенте (в React — из useEffect)
+const ok = await ctrl.validate();    // submit → раскрыть все ошибки
+dispose();
+```
+
+## Anti-patterns
+
+```typescript
+// ❌ schema пересоздаётся каждый рендер → контроллер и дедуп раннера ломаются
+function MyForm() {
+  const schema = defineValidationSchema<Form>(({ model }) => { … }); // новая ссылка на каждый рендер
+  useFormValidation({ model, schema, strategy: 'change' });
+}
+
+// ✅ Стабильная ссылка: module-level const (или useMemo с пустыми deps)
+const formValidation = defineValidationSchema<Form>(({ model }) => { … });
+function MyForm() {
+  useFormValidation({ model, schema: formValidation, strategy: 'change' });
+}
+```
+
+```typescript
+// ❌ Node-level updateOn (Слой B) И активная schema-стратегия на ОДНОМ поле → оба пишут ошибки в ноду → мерцание
+// узел поля: { updateOn: 'blur', … } + useFormValidation({ strategy: 'blur', schema: включает это же поле })
+
+// ✅ Одно поле обслуживает ОДИН слой: либо node-level updateOn, либо schema-стратегия — не оба сразу
+```
+
+```typescript
+// ❌ start() на сервере — арминует реактивные подписки при SSR
+const ctrl = createFormValidation(model, schema, { strategy: 'change' });
+ctrl.start(); // на сервере подписок быть не должно
+
+// ✅ Фабрика чиста до start(); армить только на клиенте (useFormValidation делает это в useEffect)
+const ctrl = createFormValidation(model, schema, { strategy: 'change' });
+if (typeof window !== 'undefined') ctrl.start();
+```
+
+## See also
+
+- [28-submit-and-reset.md](./28-submit-and-reset.md) — submit-флоу и `validateModel` (движок под стратегией)
+- [27-revalidate-when.md](./27-revalidate-when.md) — ручные триггеры перевалидации (низкоуровневый примитив)
+- [31-async-validator-debounce.md](./31-async-validator-debounce.md) — async-правила и отмена устаревших прогонов
+- [13-multi-step.md](./13-multi-step.md) — per-step / полная валидация wizard (`validateStep` / `validateAll`)