@reformer/core 10.2.0 → 11.0.0-beta.1

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

@@ -0,0 +1,273 @@
+## 2. API SIGNATURES
+
+### Model & Form
+
+```typescript
+// Модель данных (источник истины значений)
+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) снаружи.
+```
+
+### Validators
+
+Валидаторы — **чистые фабрики** из `@reformer/core/validators`: возвращают правило `Rule<T>` =
+`(value) => ValidationError | null` (принимают nullable value). Передаются оператору
+`validate(sig, [required(), min(50000)])` внутри схемы валидации, а **не** в layout-дерево `createForm`.
+
+```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 })
+```
+
+Использование: layout-дерево `createForm` привязывает поля к сигналам, правила живут отдельной
+`ValidationSchema` и гоняются раннером `validateModel` по требованию.
+
+```typescript
+import { createModel, createForm } from '@reformer/core';
+import { defineValidationSchema, validate, validateModel } from '@reformer/core/validation';
+import { required, min, max, email } from '@reformer/core/validators';
+
+type Loan = { email: string; age: number; amount: number };
+const model = createModel<Loan>({ email: '', age: 0, amount: 0 });
+
+// layout-схема createForm НЕ несёт validators — только привязка поля к сигналу + компонент
+const form = createForm({
+  model,
+  schema: {
+    email:  { value: model.$.email,  component: Input },
+    age:    { value: model.$.age,    component: Input },
+    amount: { value: model.$.amount, component: Input },
+  },
+});
+
+// правила — в ОТДЕЛЬНОЙ схеме валидации (не в layout)
+const loanValidation = defineValidationSchema<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
+```
+
+### Custom & cross-field validators
+
+Контракт валидации — `@reformer/core/validation`. Схема (`ValidationSchema<T>`) — обычная функция над
+(под)моделью; внутри вызываются свободные операторы, которые сами пишут ошибки в ноды текущего прогона
+(`getNodeForSignal(sig).setErrors(...)` — автор коллектора не видит).
+
+```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;
+```
+
+Операторы (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 не блокирует, устаревший прогон отменяется) |
+
+> `Rule<T>` намеренно несёт `scope: never, root: never` — так value-only фабрики (`required()` = `(value, model, root)`)
+> и inline `(value) => err` ОБА присваиваются в `Rule<T>[]`, сохраняя проверку типа поля
+> (`validate(model.$.age, [email()])` подсветится). Ментальная модель автора — `(value) => error`.
+
+Кастомные правила, cross-field и async — в схеме:
+
+```typescript
+import { type ValidationError } from '@reformer/core';
+import {
+  defineValidationSchema, validate, validateAsync, cross,
+  type Rule, type AsyncRule,
+} from '@reformer/core/validation';
+import { required } from '@reformer/core/validators';
+
+type Signup = { password: string; confirm: string; email: string };
+
+// Value-only правило (Rule<T>)
+const strongPassword: Rule<string> = (value) =>
+  !value || value.length < 8 ? { code: 'too-short', message: 'Минимум 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: 'Пароли не совпадают' }
+    : null;
+
+// Async (AsyncRule<T>): получает { signal }; сетевой сбой → null (submit не блокируется)
+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 signupValidation = defineValidationSchema<Signup>(({ model }) => {
+  validate(model.$.password, [required(), strongPassword]);
+  validate(model.$.confirm, [required()]);
+  cross(model.$.confirm, passwordsMatch);        // ошибка вешается на confirm
+  validateAsync(model.$.email, [emailUnique]);
+});
+```
+
+### 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).
+
+```typescript
+import {
+  defineValidationSchema, validate, validateWhen, cross, each, apply, validateModel,
+} from '@reformer/core/validation';
+import { required, min } from '@reformer/core/validators';
+
+// Условная валидация — ипотечная ветка активна только при loanType === 'mortgage'
+const step1 = defineValidationSchema<LoanForm>(({ model }) => {
+  validate(model.$.loanType, [required()]);
+  validateWhen(
+    () => model.loanType === 'mortgage',
+    () => {
+      validate(model.$.propertyValue, [required(), min(1_000_000)]);
+      validate(model.$.initialPayment, [required()]);
+    },
+  );
+});
+
+// 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);
+  });
+});
+
+// Полная схема формы = композиция шагов (apply над той же моделью)
+const formValidation = defineValidationSchema<LoanForm>(() => apply(step1, step5));
+```
+
+Wizard-конфиг (per-step + полная валидация) — поверх того же раннера `validateModel`:
+
+```typescript
+const STEP_SCHEMAS = [step1, /* step2, … */ step5] as const;
+
+function makeValidationConfig(model: FormModel<LoanForm>) {
+  return {
+    validateStep: (n: number) => validateModel(model, STEP_SCHEMAS[n - 1]),
+    validateAll: () => validateModel(model, formValidation),   // formValidation = apply(...STEP_SCHEMAS, extras)
+  };
+}
+```
+
+Операторы `validate`/`validateAsync`/`validateWhen`/`cross`/`each`/`apply` экспортируются напрямую из
+`@reformer/core/validation` — это публичный API, а не локальный сахар примера.
+
+### 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 })`):
+
+```typescript
+import { defineFormBehavior, compute, enableWhen, onChange } from '@reformer/core/behaviors';
+
+const behavior = defineFormBehavior<MyForm>(({ model, form }) => {
+  compute(model.$.total, () => model.price * model.quantity);
+  enableWhen(model.$.city, () => Boolean(model.country), { resetOnDisable: true });
+  onChange(model.$.country, async (country) => {
+    form.city.updateComponentProps({ options: await loadCities(country) });
+  });
+});
+
+const form = createForm({ model, schema, behavior });
+```
+
+DSL-операторы: `compute` (auto-tracking, без явного списка источников), `computeFrom`, `copyFrom`,
+`onChange` (реакция на изменение; `{ debounce, immediate }`, 2-й аргумент колбэка — `{ signal }` AbortSignal),
+`enableWhen`/`disableWhen`, `transformValue`, `resetWhen`, `syncFields`, `revalidateWhen`,
+`apply` (под-схема для группы), `applyEach` (per-item для массива), `exclusiveFlag`, `aggregateInto`.
+См. `20-compute-vs-watch.md`.
+
+Поведение **не владеет** валидацией — это отдельный слой. Мост «поведение инициирует валидацию» — через
+`revalidateWhen`, который просто вызывает внешний раннер валидации:
+
+```typescript
+revalidateWhen([model.$.dep], () => void validateModel(model, schema));
+```

package/docs/llms/04-common-patterns.md

@@ -0,0 +1,202 @@
+## 3. COMMON PATTERNS
+
+Все паттерны — на архитектуре M1: значения в модели (`model.$.field`), поведение (`defineFormBehavior`)
+на живых сигналах, валидация — отдельной ambient-схемой (`defineValidationSchema`, прогон по требованию
+через `validateModel`). Слои раздельны: layout НЕ несёт validators.
+
+### Conditional Fields with Auto-Reset
+
+```typescript
+import { enableWhen } from '@reformer/core';
+
+// поле включается по условию; при выключении — сброс к initial
+enableWhen(model.$.propertyValue, () => model.loanType === 'mortgage', {
+  resetOnDisable: true,
+});
+```
+
+Или декларативно внутри `defineFormBehavior`:
+
+```typescript
+import { defineFormBehavior, enableWhen } from '@reformer/core/behaviors';
+
+const behavior = defineFormBehavior<MyForm>(({ model }) => {
+  enableWhen(
+    [model.$.propertyValue, model.$.initialPayment],
+    () => model.loanType === 'mortgage',
+    { resetOnDisable: true }
+  );
+});
+```
+
+### Computed Field (same or cross level)
+
+`compute`/`computeFrom` пишут в целевой сигнал при изменении источников. Цель не входит
+в источники → цикла нет. Кросс-уровневые вычисления работают так же — источники берутся
+по сигналам из любого места модели.
+
+```typescript
+import { defineFormBehavior, compute, computeFrom } from '@reformer/core/behaviors';
+
+const behavior = defineFormBehavior<MyForm>(({ model }) => {
+  // compute: auto-tracking — читаем что нужно прямо из value-модели
+  compute(model.$.total, () => (model.price ?? 0) * (model.quantity ?? 0));
+
+  // computeFrom: явный список источников
+  computeFrom([model.$.price, model.$.quantity], model.$.total, (price, qty) => price * qty);
+
+  // кросс-уровневое: fullName из вложенной группы
+  compute(model.$.fullName, () =>
+    [model.personalData.firstName, model.personalData.lastName].filter(Boolean).join(' ')
+  );
+});
+```
+
+### Async reaction / dynamic options — `onChange`
+
+Для async-реакции на изменение поля (загрузка справочников, зависимые селекты) используй
+`onChange` из DSL. Колбэк выполняется вне effect-контекста (можно писать сигналы/ноды), а
+2-й аргумент — `{ signal }` (AbortSignal) для отмены устаревших запросов.
+
+```typescript
+import { defineFormBehavior, onChange } from '@reformer/core/behaviors';
+
+const behavior = defineFormBehavior<MyForm>(({ model, form }) => {
+  onChange(
+    model.$.region,
+    async (region, { signal }) => {
+      if (!region) {
+        form.city.updateComponentProps({ options: [] });
+        return;
+      }
+      const cities = await fetchCities(region, { signal });
+      form.city.updateComponentProps({ options: cities });
+    },
+    { debounce: 300 }
+  );
+});
+```
+
+> Низкоуровневый аналог — примитив `watchField(model.$.region, cb)` из `@reformer/core` (без debounce/AbortSignal;
+> для сети предпочтителен `onChange`). См. `20-compute-vs-watch.md`, `32-async-options-loading.md`.
+
+### Reading values
+
+```typescript
+// В React-компоненте — хуки
+const { value, errors, disabled } = useFormControl(form.email);
+const loanType = useFormControlValue(form.loanType); // значение напрямую
+
+// Вне React — из модели
+model.email;             // value-доступ (реактивно внутри effect/computed)
+model.$.email.value;     // через сигнал
+model.$.email.peek();    // нереактивный снимок
+model.get();             // весь объект-снимок
+```
+
+### Submit + validation
+
+Валидация — отдельная `ValidationSchema<T>` (`defineValidationSchema`), а не часть layout. Раннер
+`validateModel(model, schema)` сам роутит ошибки в ноды формы и возвращает `Promise<boolean>`
+(`false` = есть блокирующая ошибка; `severity: 'warning'` не блокирует).
+
+```typescript
+import { validateModel } from '@reformer/core/validation';
+
+async function handleSubmit(e: React.FormEvent) {
+  e.preventDefault();
+  const ok = await validateModel(model, schema); // ошибки сами доезжают до нод формы (UI подсветит)
+  if (!ok) return;                               // false → есть блокирующая ошибка
+  await api.send(model.get());
+  model.reset(); // к initial-снимку
+}
+```
+
+Multi-step: держи отдельные под-схемы на шаг и вызывай `validateModel(model, stepSchema)`. Для wizard'а —
+`makeValidationConfig(model)` → `{ validateStep, validateAll }` (`validateAll` прогоняет полную
+`apply(...STEP_SCHEMAS, extras)`). См. `13-multi-step.md`, `28-submit-and-reset.md`.
+
+### Cross-field validation — через `cross`
+
+Cross-field правило — обычная функция над **снапшотом** модели (`fn` получает `model.get()`),
+навешивается оператором `cross(sig, fn)` на поле-носитель ошибки внутри схемы:
+
+```typescript
+import { defineValidationSchema, validate, cross } from '@reformer/core/validation';
+import { required, min } from '@reformer/core/validators';
+import type { ValidationError } from '@reformer/core';
+
+// снапшот формы читается напрямую — без каста, соседние поля доступны как поля объекта
+const initialPaymentVsProperty = (f: MyForm): ValidationError | null =>
+  f.initialPayment && f.propertyValue && f.initialPayment > f.propertyValue
+    ? { code: 'tooHigh', message: 'Взнос не может превышать стоимость' }
+    : null;
+
+const schema = defineValidationSchema<MyForm>(({ model }) => {
+  validate(model.$.initialPayment, [required(), min(0)]);
+  cross(model.$.initialPayment, initialPaymentVsProperty); // ошибка сядет на initialPayment
+});
+```
+
+> Для элемента массива / под-модели захвати нужный снапшот в замыкание (`const item = im.get();
+> cross(im.$.x, () => rule(item))`) — `fn` всегда получает модель ТЕКУЩЕГО scope, а не под-модель.
+
+### Conditional validation — `validateWhen`
+
+Условная валидация — `validateWhen(() => cond, () => { … })`: правила внутри активны, только пока
+условие истинно; при `false` ранее тронутые поля гасятся. Это не `enable` (то — поведение), а
+включение/выключение самих проверок:
+
+```typescript
+import { validateWhen, validate, cross } from '@reformer/core/validation';
+
+validateWhen(
+  () => model.loanType === 'mortgage',
+  () => {
+    validate(model.$.propertyValue, [required(), min(1000000)]);
+    cross(model.$.initialPayment, initialPaymentVsProperty);
+  }
+);
+```
+
+### Перезапуск прогона — `revalidateWhen` (мост поведение → валидация)
+
+Схема прогоняется по требованию (submit/шаг). Чтобы перезапустить её при изменении зависимости —
+`revalidateWhen` из **поведения** (единственный мост поведение → валидация):
+
+```typescript
+import { defineFormBehavior, revalidateWhen } from '@reformer/core/behaviors';
+import { validateModel } from '@reformer/core/validation';
+
+const behavior = defineFormBehavior<MyForm>(({ model }) => {
+  revalidateWhen([model.$.propertyValue], () => void validateModel(model, schema));
+});
+```
+
+### Extracting named rules
+
+Когда тело правила растёт — выноси в именованную функцию. Field-правило типизируй `Rule<T>`
+(`(value) => ValidationError | null`), cross-field — обычной `(f: Root) => ValidationError | null`.
+Схема остаётся плоской и читается как оглавление:
+
+```typescript
+import { defineValidationSchema, validate } from '@reformer/core/validation';
+import { required } from '@reformer/core/validators';
+import type { Rule } from '@reformer/core/validation';
+
+// field-правило: (value) => error
+const validateAdultAge: Rule<string> = (value) => {
+  if (!value) return null;
+  const age = new Date().getFullYear() - new Date(value).getFullYear();
+  return age < 18 ? { code: 'tooYoung', message: 'Минимум 18 лет' } : null;
+};
+
+const schema = defineValidationSchema<MyForm>(({ model }) => {
+  validate(model.$.birthDate, [required(), validateAdultAge]);
+});
+```
+
+**Naming convention** (camelCase, семантика, не эхо оператора):
+
+- Cross-field правило → инвариант: `initialPaymentVsPropertyValue`, `paymentToIncomeUnderHalf`.
+- Field-правило → проверка: `validateAdultAge`, `passwordsMatch`.

package/docs/llms/05-common-mistakes.md

@@ -0,0 +1,167 @@
+## 4. COMMON MISTAKES
+
+### Imports rule (#1 cause of cascading errors — read first)
+
+- Модель/форма/хуки/типы (`FormModel`, `ValidationError`)/**примитивы behaviors** — из `@reformer/core`.
+- Схема валидации (`defineValidationSchema` + операторы `validate`/`validateAsync`/`validateWhen`/`cross`/`each`/`apply`) и раннер `validateModel` — из `@reformer/core/validation`.
+- Чистые фабрики валидаторов (`required`/`min`/`email`/…) — из `@reformer/core/validators`.
+- Декларативный DSL поведения (`defineFormBehavior` + операторы) — из `@reformer/core/behaviors`.
+
+```typescript
+// ✅ CORRECT
+import {
+  createModel,
+  createForm,
+  useFormControl,
+  useFormControlValue,
+  type FormProxy,
+  type FieldConfig,
+  type FormModel,
+  type ValidationError,
+} from '@reformer/core';
+// схема валидации + раннер — отдельный слой:
+import {
+  defineValidationSchema,
+  validate,
+  validateAsync,
+  validateWhen,
+  cross,
+  each,
+  apply,
+  validateModel,
+  type Rule,
+  type AsyncRule,
+  type ValidationSchema,
+} from '@reformer/core/validation';
+import { required, min, max, email } from '@reformer/core/validators';
+// либо примитивы behaviors из основного пакета:
+import { computeFrom, enableWhen, copyFrom } from '@reformer/core';
+// либо декларативный DSL поведения:
+import { defineFormBehavior, compute, onChange } from '@reformer/core/behaviors';
+```
+
+> **watchField живёт в `@reformer/core`** (низкоуровневый примитив), НЕ в `@reformer/core/behaviors`.
+> В DSL для реакции на изменения используется `onChange`.
+
+### Значения — в модели, не в форме
+
+Под M1 источник истины значений — модель. Форма (ноды) отражает их.
+
+```typescript
+// ✅ читаем/пишем значение
+model.email = 'a@b.c';       // value-доступ
+model.$.email.value;         // сигнал
+model.get();                 // весь снимок для submit
+
+// В компоненте — реактивно через хуки
+const email = useFormControlValue(form.email);
+```
+
+### useFormControlValue (CRITICAL)
+
+```typescript
+// WRONG - useFormControlValue returns T directly, NOT { value: T }
+const { value: loanType } = useFormControlValue(control.loanType);
+// Result: loanType is ALWAYS undefined!
+
+// CORRECT
+const loanType = useFormControlValue(control.loanType);
+
+// ALSO CORRECT - useFormControl returns object
+const { value, errors } = useFormControl(control.loanType);
+```
+
+### Behaviors принимают СИГНАЛЫ, а не пути/форму
+
+```typescript
+// ❌ WRONG - строковые пути и (form) => ... это старый API, удалён
+enableWhen(path.city, (form) => Boolean(form.country));
+computeFrom(['price', 'quantity'], 'total', (values) => values.price * values.quantity);
+
+// ✅ CORRECT - сигналы модели, условие читает model напрямую
+enableWhen(model.$.city, () => Boolean(model.country), { resetOnDisable: true });
+computeFrom([model.$.price, model.$.quantity], model.$.total, (price, qty) => price * qty);
+```
+
+### Валидаторы — оператор `validate`, а не layout-нода
+
+Валидация — **отдельный слой** (`@reformer/core/validation`), а не поле layout-ноды. Layout
+(схема `createForm` / JSON-DSL) больше **не несёт** `validators`: правила живут в `ValidationSchema`,
+а прогоняет их внешний раннер `validateModel`. ⚠️ `form.validate()`/`submit()` schema-валидацию
+**НЕ запускают** — прогон только через `validateModel(model, schema)`.
+
+```typescript
+// ❌ WRONG - дерево { value, validators } и позиционная строка удалены
+const schema = {
+  email: { value: model.$.email, component: Input, validators: [required(), email()] },
+};
+validate(path.email, required(), 'Email is required'); // старая сигнатура validate() — удалена
+
+// ✅ CORRECT - операторы validate/validateAsync внутри defineValidationSchema; фабрики с options
+const emailSchema = defineValidationSchema<MyForm>(({ model }) => {
+  validate(model.$.email, [required({ message: 'Email is required' }), email()]);
+  validateAsync(model.$.email, [
+    async (value, { signal }) => {
+      const res = await fetch(`/api/free?email=${value}`, { signal });
+      return (await res.json()).free ? null : { code: 'taken', message: 'Email занят' };
+    },
+  ]);
+});
+
+// прогон по требованию (submit/шаг): ошибки сами доезжают до нод формы, warnings не блокируют
+const ok = await validateModel(model, emailSchema);
+```
+
+### Cross-field — оператор `cross`, а не `ctx.form`
+
+```typescript
+// ❌ WRONG - ctx.form / ctx.setFieldValue / value.value — старый API; ModelValidator(value,scope,root) удалён
+watchField(path.amount, (amount, ctx) => {
+  const rate = ctx.form.rate.value.value;
+  ctx.setFieldValue('total', amount * rate);
+});
+
+// ✅ CORRECT - compute (поведение) на сигналах; cross-field (валидация) через оператор cross
+compute(model.$.total, () => (model.amount ?? 0) * (model.rate ?? 0));
+
+// cross-field правило — обычная функция над снапшотом Root (`model.get()`), навешивается через cross(sig, fn):
+const amountVsMax = (f: MyForm): ValidationError | null =>
+  f.amount != null && f.maxAmount != null && f.amount > f.maxAmount
+    ? { code: 'tooBig', message: 'Превышает лимит' }
+    : null;
+
+const amountSchema = defineValidationSchema<MyForm>(({ model }) => {
+  cross(model.$.amount, amountVsMax); // fn получает model.get(), вешает ошибку на model.$.amount
+});
+```
+
+### Form-shape types — `type` over `interface`
+
+```typescript
+// ❌ interface лишён неявной index signature; конструкции ArrayNode<T> его отвергают
+export interface PropertyItem {
+  type: PropertyType;
+  description: string;
+}
+
+// ✅ type alias структурно совместим с Record<string, FormValue>
+export type PropertyItem = {
+  type: PropertyType;
+  description: string;
+};
+```
+
+`number | null` — конвенциональный тип для очищенного поля; встроенные валидаторы
+(`min`, `max`, `minLength`, `maxLength`, `minDate`, `maxDate`, `minAge`, `maxAge`) пропускают
+пустые значения внутри.
+
+### Proxy не проходит instanceof
+
+```typescript
+// ❌ instanceof на Proxy не работает
+if (node instanceof FieldNode) { ... }
+
+// ✅ type guards
+import { isFieldNode, isGroupNode, isArrayNode } from '@reformer/core';
+if (isFieldNode(node)) { ... }
+```

package/docs/llms/06-troubleshooting.md

@@ -0,0 +1,11 @@
+## 5. TROUBLESHOOTING
+
+| Error                                                  | Cause                                                    | Solution                                          |
+| ------------------------------------------------------ | -------------------------------------------------------- | ------------------------------------------------- |
+| `'string' is not assignable to '{ message?: string }'` | Валидатору передали строку вместо options                | Используй `required({ message: 'text' })`         |
+| `Module has no exported member`                        | Неверный источник импорта                                | `watchField`/примитивы — из `@reformer/core`; DSL — из `@reformer/core/behaviors`; фабрики — из `@reformer/core/validators` |
+| `undefined` из `useFormControlValue`                   | Деструктурировали хук                                    | `const v = useFormControlValue(...)` — без деструктуризации |
+| `enableWhen`/`disableWhen` не срабатывает              | Поле не материализовано в форме (элемент массива)        | Убедись, что поле есть в схеме `createForm`; для per-item — `applyEach` |
+| `Cycle detected`                                       | Взаимные `compute`/`computeFrom` без стабилизации        | Разорви цикл через условие `when` или `peek`; см. 22-cycle-detection.md |
+| Значение поля не пишется                               | Пишем в форму вместо модели                              | Значения принадлежат модели: `model.field = ...` / `model.$.field.value = ...` |
+| Ошибки не появляются после submit                      | Не вызвали `validateModel` (`form.submit()` НЕ гоняет schema-валидацию) | `await validateModel(model, schema)` из `@reformer/core/validation` — он роутит ошибки в ноды |