@reformer/renderer-json 8.0.0 → 9.0.0-beta.1

package/llms.txt

@@ -0,0 +1,1929 @@
+# ReFormer Renderer Json - LLM Integration Guide
+# AUTO-GENERATED. Edit docs/llms/*.md or JSDoc in src/ and run npm run generate:llms.
+
+> JSON-based form renderer for @reformer ecosystem
+> Package: @reformer/renderer-json  •  Version: 6.0.0
+
+## Table of Contents
+- 01-overview.md — Overview
+- 02-json-schema.md — JSON Schema
+- 03-registry.md — Component Registry
+- 04-troubleshooting.md — Troubleshooting / FAQ
+- 05-cookbook.md — Cookbook
+- 06-validation.md — Validation
+- 07-form-wizard.md — FormWizard
+- API Reference (auto-generated from JSDoc)
+
+## 1. Installation
+
+```bash
+npm install @reformer/renderer-json @reformer/renderer-react @reformer/core
+```
+
+Опционально для готовых UI-компонентов:
+
+```bash
+npm install @reformer/ui-kit
+```
+
+## 2. Import Patterns
+
+```typescript
+// recommended
+import {
+  JsonFormRenderer,
+  JsonRendererProvider,
+  defineRegistry,
+  FIELD_WRAPPER,
+  convertJsonToM1Tree,
+  type JsonFormSchema,
+} from '@reformer/renderer-json';
+```
+
+## 3. Quick Start
+
+Ключевая идея M1: **модель (`FormModel`) — источник данных, JSON-схема — layout**. Форма строится из той же JSON-схемы через `convertJsonToM1Tree`, а `JsonFormRenderer` получает модель через `JsonRendererProvider` settings (`model`). `JsonFormRenderer` НЕ имеет `form`-пропа — это by-design: JSON статичен, модель runtime.
+
+Минимальный рабочий монтаж:
+
+```tsx
+import { useMemo } from 'react';
+import { createForm, createModel } from '@reformer/core';
+import { Input, Box, FormField } from '@reformer/ui-kit';
+import {
+  JsonFormRenderer,
+  JsonRendererProvider,
+  defineRegistry,
+  FIELD_WRAPPER,
+  convertJsonToM1Tree,
+  type JsonFormSchema,
+} from '@reformer/renderer-json';
+
+type MyForm = { email: string };
+
+// 1. JSON-схема — чистые данные, операторы-строки, никаких React-импортов.
+const jsonSchema: JsonFormSchema = {
+  version: '1.0',
+  root: {
+    component: '$component(Box)',
+    children: [
+      { selector: 'email', value: '$model(email)', component: '$component(Input)',
+        componentProps: { label: 'Email' } },
+    ],
+  },
+};
+
+// 2. Реестр: имена из JSON → React-компоненты.
+const registry = defineRegistry((reg) => {
+  reg.component('Input', Input);
+  reg.component('Box', Box);
+  reg.component(FIELD_WRAPPER, FormField);
+});
+
+function MyFormPage() {
+  // 3. Модель + форма строятся ИЗ JSON-схемы (единая схема, без отдельной схемы формы).
+  const { model } = useMemo(() => {
+    const model = createModel<MyForm>({ email: '' });
+    createForm<MyForm>({ model, schema: convertJsonToM1Tree(jsonSchema, registry, model) });
+    return { model };
+  }, []);
+
+  // 4. Модель прокидывается через провайдер; JsonFormRenderer биндит листья к её сигналам.
+  return (
+    <JsonRendererProvider settings={{ registry, model }}>
+      <JsonFormRenderer<MyForm> schema={jsonSchema} />
+    </JsonRendererProvider>
+  );
+}
+```
+
+**Почему `model` через провайдер, а не `<JsonFormRenderer form={...}/>`?** Под M1 листья схемы (`value: '$model(path)'`) биндятся к сигналам модели (`model.signalAt(path)`) конвертером. Модель обязательна и передаётся через `JsonRendererProvider` settings — `JsonFormRenderer` без неё бросит `settings.model is required (M1)`. Сам рендерер принимает только `{ schema, renderBehavior?, onSchemaReady?, validate? }`.
+
+## 4. Key Concepts
+
+- **JSON-схема** — дерево `JsonNode` (см. [02-json-schema.md](02-json-schema.md)). Узлы: **field** (`value: '$model(...)'`), **array** (`array` + `item.$template`), **container** (`component` + `children`).
+- **Операторы** — строки `$model(path)` / `$component(Name)` / `$dataSource(NAME)`. Только они резолвятся; голые строки идут как есть.
+- **Модель (`model`)** — `FormModel`, источник данных. Передаётся в `JsonRendererProvider` settings; листья биндятся к её сигналам.
+- **Реестр** — карта имени из `$component(...)`/`$dataSource(...)` на React-компонент или source-значение. Без регистрации схема не сконвертируется (ошибка `Component "X" not found in registry`).
+- **`FIELD_WRAPPER`** — зарезервированный ключ реестра (`'$fieldWrapper'`) для компонента-обёртки полей (label, error, hint). Обычно `FormField` из `@reformer/ui-kit`.
+- **`convertJsonToM1Tree`** — конвертер JSON → RenderNode-дерево для `createForm({ model, schema })`.
+- **`renderBehavior`** — TS-функция `RenderBehaviorFn<T>` (hideWhen/patchProps/onInit), применяется поверх готовой схемы; в JSON поведение не выражается.
+
+## 5. Components and exports
+
+| Export                                          | Purpose                                                                    |
+| ----------------------------------------------- | -------------------------------------------------------------------------- |
+| `JsonFormRenderer`                              | Главный компонент-рендерер. Пропы: `{ schema, renderBehavior?, onSchemaReady?, validate? }`. |
+| `JsonRendererProvider`                          | Контекст-провайдер: реестр (`registry`), модель (`model`), настройки.       |
+| `useJsonRendererSettings`                       | Хук для чтения текущих настроек контекста.                                  |
+| `defineRegistry`                                | Builder реестра компонентов и dataSource-значений.                         |
+| `FIELD_WRAPPER`                                 | Ключ реестра (`'$fieldWrapper'`) для компонента-обёртки полей.              |
+| `JsonFormSchema`, `JsonNode`                    | Типы JSON-схемы (`JsonFieldNode`/`JsonArrayNode`/`JsonContainerNode`).      |
+| `isFieldNode`, `isArrayNode`, `isContainerNode` | Type guards для узлов.                                                      |
+| `parseOperator`, `isModelOp`, `isComponentOp`, `isDataSourceOp` | Разбор и type-guards строк-операторов.                      |
+| `ModelOp`, `ComponentOp`, `DataSourceOp`        | Template-literal типы операторов.                                          |
+| `convertJsonToM1Tree`                           | JSON → сырое RenderNode-дерево (для `createForm({ model, schema })`).       |
+| `createRenderSchemaFromJsonM1`                  | JSON → `RenderSchemaFn` (низкоуровневый, для `FormRenderer`/`JsonFormRenderer`). |
+| `SchemaErrorPanel`                              | Панель ошибок валидации схемы (рисуется при `validate` + невалидной схеме). |
+| `formSchemaMetaSchema`, `buildFormSchemaMetaSchema`, `getComponentNames`, `getDataSourceNames` | Мета-схема form-DSL + утилиты (ajv-free). |
+
+> `validateFormSchema` живёт в отдельной точке входа `@reformer/renderer-json/validate` (тянет ajv, не попадает в render-бандл). `JsonFormRenderer` грузит её динамически при `validate={true}`.
+
+## 6. See also
+
+- [02-json-schema.md](02-json-schema.md) — формат `JsonFormSchema`/`JsonNode` и синтаксис операторов.
+- [03-registry.md](03-registry.md) — как наполнять реестр.
+- [04-troubleshooting.md](04-troubleshooting.md) — частые ошибки.
+- [05-cookbook.md](05-cookbook.md) — массивы, dataSource-функции, миграция из TS RenderSchema.
+
+## 7. Key Concepts
+
+- **`JsonFormSchema`** — корневой документ: `version` (для миграций), опциональный `$schema` (путь к мета-схеме для IDE), единственный корневой узел `root`.
+- **`JsonNode`** — узел дерева. Дискриминированный union по строке-оператору, которую он несёт:
+  - **field-node** (`JsonFieldNode`) — лист: `value: '$model(path)'` + опциональный `component: '$component(Name)'` (дефолт — Input). Не имеет `children`. Несёт **только layout** — валидаторов в JSON нет, оператора `$validator(...)` не существует. Валидация значений — отдельная TS-схема над моделью, см. [06-validation.md](06-validation.md).
+  - **array-node** (`JsonArrayNode`) — массив: `array: '$model(path)'` + `item: { $template: <JsonNode> }` + опциональный `initialValue` (литерал нового элемента для кнопки «Добавить»).
+  - **container-node** (`JsonContainerNode`) — контейнер (Box/Section/Wizard/Step): `component: '$component(Name)'` + опциональные `children`.
+- **Операторы** — единственный способ привязки (см. [`operators.ts`](../../src/operators.ts)):
+  - `'$model(path)'` — путь к полю/массиву модели (лист → `model.signalAt(path)`, массив → value-прокси массива).
+  - `'$component(Name)'` — имя компонента в реестре (`reg.component`).
+  - `'$dataSource(NAME)'` — имя registry-source (`reg.dataSource`): options, itemLabel, константы, loading-компоненты.
+- **`selector`** — plain-строка, id узла для render-behavior (`schema.node('…')`, `hideWhen`, `patchProps`). **Не** путь модели.
+- **`componentProps`** — что прокидывается в React-компонент. Значения могут содержать строки-операторы (`'$dataSource(NAME)'`, `'$model(...)'`, `'$component(...)'`) или вложенные `JsonNode` — конвертер резолвит их рекурсивно. Обычные значения (числа, инлайн-массивы options, `label`) идут как есть.
+
+## 8. Type Guards
+
+Порядок важен: `isArrayNode` проверяй **первым** (array-node тоже несёт `$model`, но в поле `array`).
+
+```typescript
+import { isArrayNode, isFieldNode, isContainerNode, type JsonNode } from '@reformer/renderer-json';
+
+function inspect(node: JsonNode) {
+  if (isArrayNode(node)) {
+    // node.array: '$model(...)', node.item.$template: JsonNode
+  } else if (isFieldNode(node)) {
+    // node.value: '$model(...)', node.component?: '$component(...)'
+  } else if (isContainerNode(node)) {
+    // node.component: '$component(...)', node.children?: JsonNode[]
+  }
+}
+```
+
+## 9. Examples
+
+Минимальная схема с одним полем (лист `value` + контейнер `Box`):
+
+```typescript
+import type { JsonFormSchema } from '@reformer/renderer-json';
+
+const schema: JsonFormSchema = {
+  version: '1.0',
+  root: {
+    component: '$component(Box)',
+    children: [
+      {
+        selector: 'email',
+        value: '$model(email)',
+        component: '$component(Input)',
+        componentProps: { label: 'Email' },
+      },
+    ],
+  },
+};
+```
+
+Вложенный путь к полю и ссылка на dataSource-константу в `componentProps`:
+
+```typescript
+{
+  value: '$model(personalData.firstName)',
+  component: '$component(Input)',
+}
+
+{
+  value: '$model(loanType)',
+  component: '$component(Select)',
+  componentProps: { label: 'Тип кредита', options: '$dataSource(LOAN_TYPES)' },
+}
+```
+
+Массив с шаблоном элемента (`array` + `item.$template` + `initialValue`). Внутри `$template` пути `$model(...)` резолвятся **относительно элемента** массива:
+
+```typescript
+{
+  selector: 'properties-array',
+  array: '$model(properties)',
+  initialValue: { type: 'apartment', description: '', estimatedValue: 0, hasEncumbrance: false },
+  componentProps: {
+    title: 'Имущество',
+    addButtonLabel: '+ Добавить имущество',
+    itemLabel: '$dataSource(PROPERTY_ITEM_LABEL_SOURCE_FN)',
+  },
+  item: {
+    $template: {
+      component: '$component(Box)',
+      componentProps: { className: 'space-y-3' },
+      children: [
+        { value: '$model(type)', component: '$component(Select)',
+          componentProps: { label: 'Тип', options: '$dataSource(PROPERTY_TYPES)' } },
+        { value: '$model(estimatedValue)', component: '$component(Input)',
+          componentProps: { label: 'Стоимость', type: 'number' } },
+      ],
+    },
+  },
+}
+```
+
+## 10. Anti-patterns
+
+- **Голые строки вместо операторов** — `component: 'Input'` или `value: 'email'` не резолвятся. Нужны операторы: `component: '$component(Input)'`, `value: '$model(email)'`. Template-literal типы (`ModelOp`/`ComponentOp`) отловят это на этапе компиляции.
+- **Использовать `selector` как путь к полю** — `selector` это id для behavior; путь задаётся только через `value`/`array` оператором `$model(...)`.
+- **Забыть `item.$template` у массива** — array-node требует `array` **и** `item: { $template }`. Без `$template` `isArrayNode` вернёт false и узел не отрендерится как массив.
+- **`initialValue` как FieldConfig** — это plain-литерал по форме элемента (`{ field: value }`), а не `{ value, component }`. Клонируется через `JSON.parse(JSON.stringify(...))`, поэтому только сериализуемые значения.
+- **Ссылаться на `$dataSource(NAME)` без регистрации** — при `validate` неизвестное имя даст ошибку; без валидации строка просто прокинется как есть (молчаливый баг).
+- **Класть `validators` в field-node** — `JsonFieldNode` несёт только layout, поля `validators` в нём нет и оператора `$validator(...)` не существует. Валидация значений живёт в отдельной TS-схеме над моделью (`validateFormModel`), а не в JSON — см. [06-validation.md](06-validation.md).
+
+## 11. See also
+
+- [01-overview.md](01-overview.md) — как схема монтируется через `model` + `JsonRendererProvider`.
+- [03-registry.md](03-registry.md) — какие компоненты и source можно зарегистрировать.
+- [05-cookbook.md](05-cookbook.md) — `$template`, dataSource-функции, миграция из TS RenderSchema.
+- [06-validation.md](06-validation.md) — валидация значений (TS-схема над моделью + инъекция в wizard).
+- [Типы JsonFormSchema/JsonNode](../../src/types/json-schema.ts) и [операторы](../../src/operators.ts).
+
+## 12. Key Concepts
+
+- **component** — любой React-компонент, зарегистрированный под именем и доступный в схеме как `component: '$component(name)'`. Один метод `reg.component(name, Component)` регистрирует и компоненты-листья (Input/Select — узел несёт `value: '$model(path)'`), и контейнеры-обёртки (Box/Section/FormField — узел несёт `children`). Роль узла (лист vs контейнер) определяется **структурой узла в схеме** (`value` vs `children`), а не тем, как компонент зарегистрирован.
+- **dataSource value** — именованная константа, функция или React-компонент, на которые ссылаются строкой `'$dataSource(NAME)'` из `componentProps`. Регистрируется через `reg.dataSource(name, value)`.
+- **`FIELD_WRAPPER`** — зарезервированное имя (`'$fieldWrapper'`) для контейнера-обёртки полей (label, error, hint). Обычно регистрируется как `FormField` из `@reformer/ui-kit`.
+
+## 13. Builder API
+
+| Method                           | Purpose                                               |
+| -------------------------------- | ----------------------------------------------------- |
+| `reg.component(name, Component)` | Регистрирует компонент (лист или контейнер — роль решает структура узла). |
+| `reg.dataSource(name, value)`    | Регистрирует dataSource-значение (константу или функцию). |
+
+## 14. Examples
+
+Минимальный реестр:
+
+```typescript
+import { defineRegistry, FIELD_WRAPPER } from '@reformer/renderer-json';
+import { Input, Select, Box, FormField } from '@reformer/ui-kit';
+
+const registry = defineRegistry((reg) => {
+  reg.component('Input', Input);
+  reg.component('Select', Select);
+  reg.component('Box', Box);
+  reg.component(FIELD_WRAPPER, FormField);
+});
+```
+
+dataSource values для `componentProps` (в схеме — ссылка `'$dataSource(NAME)'`):
+
+```typescript
+const registry = defineRegistry((reg) => {
+  reg.component('Select', Select);
+  reg.dataSource('LOAN_TYPES', [
+    { value: 'consumer', label: 'Потребительский' },
+    { value: 'mortgage', label: 'Ипотека' },
+  ]);
+});
+
+// В JSON-схеме (лист + операторы):
+{
+  value: '$model(loanType)',
+  component: '$component(Select)',
+  componentProps: { options: '$dataSource(LOAN_TYPES)' },
+}
+```
+
+## 15. Anti-patterns
+
+- **Забыть зарегистрировать `FIELD_WRAPPER`** — поля будут рендериться без обёртки (нет label/error). В большинстве случаев это ошибка.
+- **Регистрировать React-element вместо компонента** — `reg.component('Input', <Input />)` не сработает, нужно передавать сам тип компонента: `reg.component('Input', Input)`.
+- **Ожидать наследования между вложенными `JsonRendererProvider`** — реестр сливается через `withParent`, дубли решаются по приоритету (внешний > внутренний).
+- **Использовать `$dataSource(NAME)` без регистрации** — без `validate` строка просто прокинется в проп как есть (молчаливый баг); с `validate` даст ошибку `unknown dataSource "NAME"`.
+- **Ссылаться на dataSource как на компонент** — `component: '$component(LoadingState)'`, где `LoadingState` зарегистрирован через `reg.dataSource`, бросит `Entry "..." is a 'dataSource' and cannot be used as $component(...)`. dataSource — только для значений в `componentProps`.
+
+## 16. See also
+
+- [01-overview.md](01-overview.md) — как реестр прокидывается через `JsonRendererProvider`.
+- [02-json-schema.md](02-json-schema.md) — где имена компонентов появляются в схеме (операторы `$component`/`$dataSource`).
+
+## 17. Component "X" not found in registry
+
+Имя из оператора `$component(X)` (или `$dataSource(X)`) не зарегистрировано в реестре. Проверь:
+
+- `defineRegistry` действительно содержит `reg.component('X', ...)` или `reg.dataSource('X', ...)`.
+- В схеме используется оператор, а не голая строка: `component: '$component(X)'`, а не `component: 'X'`.
+- `JsonFormRenderer` обёрнут в `JsonRendererProvider` с этим реестром.
+- Если используются вложенные провайдеры — реестр внутреннего провайдера наследуется через `withParent`, но дубли разрешаются в пользу внешнего.
+
+## 18. Field renders without label/error
+
+Не зарегистрирован контейнер с ключом `FIELD_WRAPPER`. Добавь:
+
+```typescript
+import { FIELD_WRAPPER } from '@reformer/renderer-json';
+import { FormField } from '@reformer/ui-kit';
+
+reg.component(FIELD_WRAPPER, FormField);
+```
+
+## 19. No model signal for "..." / settings.model is required
+
+Два разных симптома одной причины — модель.
+
+- `JsonFormRenderer: settings.model is required (M1)` — не передана модель. Под M1 листья схемы биндятся к сигналам `FormModel`; передай её в `JsonRendererProvider settings={{ registry, model }}`.
+- `[JsonRenderer/M1] No model signal for "path"` (warn) — путь в `$model(path)` не соответствует структуре модели. Проверь: `value: '$model(personalData.firstName)'` — поле `firstName` реально существует внутри `personalData` в `createModel(...)` initial-значениях.
+
+## 20. componentProps string passes through as plain string
+
+Строка `'$dataSource(NAME)'` в `componentProps` ссылается на source, который не зарегистрирован — конвертер оставляет её как есть. Используй `reg.dataSource('NAME', value)` либо передавай значение литералом напрямую. Голые строки (без `$dataSource(...)`) намеренно не резолвятся — это обычные значения пропа (`label`, `placeholder`).
+
+## 21. useJsonRendererSettings throws outside provider
+
+`useJsonRendererSettings` в dev-режиме бросает, если вызван вне `JsonRendererProvider` **или** если в провайдере не передан `registry`. Оберни вызывающий компонент в провайдер с реестром.
+
+## 22. "version" missing / invalid schema (при validate)
+
+`validate={true}` прогоняет схему через мета-схему (ajv) + обход имён операторов. Типичные ошибки: узел не подходит ни под field/array/container (нет ни `value`, ни `array`+`item`, ни `component`), голая строка вместо оператора, неизвестное `$component(...)`/`$dataSource(...)` имя. Ошибки рисуются в `SchemaErrorPanel` вместо формы. `$model(...)`-пути мета-схема не проверяет (только синтаксис) — они динамичны.
+
+## 23. Behavior selector matches nothing
+
+`hideWhen`/`patchProps` ищут узел по `selector`. Убедись, что у узла он явно задан (`selector: 'mortgage-section'`), и что значение совпадает с тем, на которое смотрит behavior. `selector` — plain-строка, НЕ оператор.
+
+## 24. $template inside array doesn't render rows
+
+Массив — это array-node, а не container с `itemComponent`. Проверь:
+
+- Узел использует `array: '$model(path)'` **и** `item: { $template: <JsonNode> }` (оба обязательны — иначе `isArrayNode` вернёт false).
+- Внутри `$template` пути `$model(...)` заданы **относительно элемента** (`value: '$model(type)'`, а не `'$model(properties[0].type)'`).
+- Есть `initialValue` (plain-литерал по форме элемента) — иначе кнопка «Добавить» создаст пустой элемент без сигналов для полей шаблона.
+
+## 25. Массив рендерится без строк / пустой при добавлении
+
+`initialValue` должен быть **полным** plain-объектом по форме элемента (все поля, что есть в `$template`). Если передать частичный объект (`{ type: 'apartment' }` без `estimatedValue`/`description`), под-модель нового элемента не получит сигналов для недостающих полей и они не отрендерятся. `initialValue` клонируется через `JSON.parse(JSON.stringify(...))` — только сериализуемые значения, никакого FieldConfig.
+
+## 26. Toggle-видимость секции массива
+
+Условный показ секции (напр. массив `properties` виден только когда `hasProperty === true`) делается **не** кастомным блоком, а через `renderBehavior`:
+
+```typescript
+import { hideWhen } from '@reformer/renderer-react';
+
+const renderBehavior: RenderBehaviorFn<MyForm> = (schema) => {
+  hideWhen(schema.node('properties-array'), () => model.signalAt('hasProperty').value !== true);
+};
+```
+
+`renderBehavior` передаётся пропом в `JsonFormRenderer`; узел адресуется по своему `selector`.
+
+## 27. See also
+
+- [01-overview.md](01-overview.md)
+- [02-json-schema.md](02-json-schema.md)
+- [03-registry.md](03-registry.md)
+- [05-cookbook.md](05-cookbook.md)
+
+## 28. Монтаж формы из JSON (M1) { #mounting }
+
+**Problem.** JSON-схема статична, а данные и форма — runtime. Нужно связать их без React-glue на каждой странице.
+
+**Solution.** Модель (`FormModel`) — источник данных, форма строится из **той же** JSON-схемы через `convertJsonToM1Tree`, а `JsonFormRenderer` получает модель через `JsonRendererProvider` settings. `JsonFormRenderer` не имеет `form`-пропа (by-design).
+
+```tsx
+import { useMemo } from 'react';
+import { createForm, createModel } from '@reformer/core';
+import {
+  JsonFormRenderer,
+  JsonRendererProvider,
+  convertJsonToM1Tree,
+  type JsonFormSchema,
+} from '@reformer/renderer-json';
+import rawJsonSchema from './json-schema.json';
+import { createRegistry } from './registry';
+
+const jsonSchema = rawJsonSchema as unknown as JsonFormSchema; // «схема пришла строкой»
+
+export function MyFormPage() {
+  const registry = useMemo(() => createRegistry(), []);
+  const { model } = useMemo(() => {
+    const model = createModel<MyForm>(initialValues);
+    // Форма строится из JSON: конвертер биндит листья к сигналам модели.
+    createForm<MyForm>({ model, schema: convertJsonToM1Tree(jsonSchema, registry, model) });
+    return { model };
+  }, [registry]);
+
+  return (
+    <JsonRendererProvider settings={{ registry, model }}>
+      <JsonFormRenderer<MyForm> schema={jsonSchema} validate={import.meta.env.DEV} />
+    </JsonRendererProvider>
+  );
+}
+```
+
+**Notes.**
+
+- `convertJsonToM1Tree` бросает при битой схеме (неизвестный `$component`) **до** рендера. Оберни в try/catch, если хочешь показать `SchemaErrorPanel` вместо краша (см. `buildModelAndForm` в эталоне).
+- `validate={import.meta.env.DEV}` — детекцию dev нельзя «запечь» в пакет; приложение передаёт значение из своего окружения.
+- Поведение (compute/enableWhen/navigation) идёт в `createForm({ behavior })`; render-behavior (hideWhen/patchProps/onInit) — отдельным пропом `renderBehavior`.
+
+## 29. $template для массивов { #template-arrays }
+
+**Problem.** В JSON нельзя выразить функцию `(itemPath) => RenderNode` для item-шаблона. Массив должен остаться декларативным.
+
+**Solution.** Array-node несёт `array: '$model(path)'` + `item: { $template: <JsonNode> }` + `initialValue`. Внутри `$template` пути `$model(...)` резолвятся **относительно элемента** массива. Массивы под M1 рендерятся native-веткой конвертера (`{ array, item }`) — отдельный контейнер-компонент не нужен.
+
+```typescript
+{
+  selector: 'properties-array',
+  array: '$model(properties)',
+  initialValue: { type: 'apartment', description: '', estimatedValue: 0, hasEncumbrance: false },
+  componentProps: {
+    title: 'Имущество',
+    addButtonLabel: '+ Добавить имущество',
+    itemLabel: '$dataSource(PROPERTY_ITEM_LABEL_SOURCE_FN)',
+    emptyMessage: 'Нажмите "Добавить имущество"',
+  },
+  item: {
+    $template: {
+      component: '$component(Box)',
+      componentProps: { className: 'space-y-3' },
+      children: [
+        { value: '$model(type)', component: '$component(Select)',
+          componentProps: { label: 'Тип', options: '$dataSource(PROPERTY_TYPES)' } },
+        { value: '$model(estimatedValue)', component: '$component(Input)',
+          componentProps: { label: 'Стоимость', type: 'number' } },
+        { value: '$model(description)', component: '$component(Textarea)',
+          componentProps: { label: 'Описание', rows: 2 } },
+      ],
+    },
+  },
+}
+```
+
+**Notes.**
+
+- `array` **и** `item.$template` обязательны оба — иначе узел не считается array-node (`isArrayNode`).
+- `initialValue` — полный plain-объект по форме элемента (все поля из `$template`). Клонируется через `JSON.parse(JSON.stringify(...))`; не FieldConfig. Частичный `initialValue` → у нового элемента нет сигналов для недостающих полей.
+- Внутри `$template` пути относительны элементу (`'$model(type)'`, а не `'$model(properties[0].type)'`).
+- Вложенный массив в массиве — новый array-node внутри `$template` со своим `array`/`item`.
+
+## 30. dataSource-значения и функции { #datasource }
+
+**Problem.** Нужно передать в проп массив options, функцию (`itemLabel: (form, index) => string`) или React-компонент (`LoadingComponent`) — а JSON хранит только примитивы и объекты.
+
+**Solution.** Регистрируешь значение через `reg.dataSource('NAME', value)`, в JSON-схеме ссылаешься оператором `'$dataSource(NAME)'`. Конвертер при обходе `componentProps` подставит зарегистрированное значение.
+
+```typescript
+import { createElement } from 'react';
+import { defineRegistry } from '@reformer/renderer-json';
+import { LoadingState, ErrorState } from '@reformer/ui-kit';
+
+const registry = defineRegistry((reg) => {
+  // 1. Константа: массив options.
+  reg.dataSource('LOAN_TYPES', [
+    { value: 'consumer', label: 'Потребительский' },
+    { value: 'mortgage', label: 'Ипотека' },
+  ]);
+
+  // 2. React-компонент как dataSource (для AsyncBoundary.LoadingComponent).
+  reg.dataSource('LoadingState', LoadingState);
+  reg.dataSource('ErrorStateDefault', () => createElement(ErrorState, { error: 'Ошибка' }));
+
+  // 3. Функция: itemLabel для array-секции.
+  reg.dataSource('PROPERTY_ITEM_LABEL_SOURCE_FN', (_form, index: number) => `Имущество #${index + 1}`);
+
+  // 4. Computed-константа.
+  reg.dataSource('CURRENT_YEAR_PLUS_ONE', new Date().getFullYear() + 1);
+});
+```
+
+```typescript
+// В JSON-схеме — ссылки операторами:
+{
+  selector: 'data-boundary',
+  component: '$component(AsyncBoundary)',
+  componentProps: {
+    status: 'loading',
+    LoadingComponent: '$dataSource(LoadingState)',       // → React-компонент
+    ErrorComponent: '$dataSource(ErrorStateDefault)',
+  },
+  children: [
+    { value: '$model(loanType)', component: '$component(Select)',
+      componentProps: { options: '$dataSource(LOAN_TYPES)' } },   // → массив
+    { value: '$model(carYear)', component: '$component(Input)',
+      componentProps: { type: 'number', max: '$dataSource(CURRENT_YEAR_PLUS_ONE)' } }, // → число
+  ],
+}
+```
+
+**Notes.**
+
+- Резолв происходит только для строк `'$dataSource(NAME)'`. Голые строки (`label`, `placeholder`) и инлайн-массивы options идут как есть.
+- Если имя не зарегистрировано: без `validate` строка `'$dataSource(NAME)'` останется строкой (молчаливый баг); с `validate` — ошибка `unknown dataSource "NAME"`.
+- dataSource нельзя использовать как имя `component` (`component: '$component(LoadingState)'`, где `LoadingState` — dataSource, бросит `Entry "..." is a 'dataSource' and cannot be used as $component(...)`). dataSource — только для значений в `componentProps`.
+
+## 31. Инъекция runtime-сущностей в компонент (form, validation) { #inject-runtime }
+
+**Problem.** Компоненту (напр. wizard) нужен `FormProxy` или validation-конфиг — рантайм-сущности, которые нельзя выразить в статичном JSON.
+
+**Solution.** Инжектируй их через `renderBehavior` + `onInit`/`patchProps` до первого рендера. Узел адресуется по `selector`.
+
+```typescript
+import { onInit, type RenderBehaviorFn } from '@reformer/renderer-react';
+
+function createMyRenderBehavior(
+  form: FormProxy<MyForm>,
+  model: FormModel<MyForm>
+): RenderBehaviorFn<MyForm> {
+  return (schema) => {
+    // JSON-схема не знает про FormProxy/валидацию — инъектим их в wizard до первого рендера.
+    onInit(schema.node('wizard'), () => {
+      schema.node('wizard').patchProps({ form, ...makeValidationConfig(model) });
+    });
+    // Остальное поведение (visibility/navigation) — из shared render-behavior.
+    createSharedRenderBehavior(form)(schema);
+  };
+}
+
+// <JsonFormRenderer schema={jsonSchema} renderBehavior={createMyRenderBehavior(form, model)} />
+```
+
+**Notes.**
+
+- `onInit(node, fn)` — build-time hook, вызывается один раз до первого рендера ноды.
+- `patchProps` мержит переданные пропы в `componentProps` ноды.
+
+## 32. Вся форма read-only / view-mode { #readonly }
+
+**Problem.** Нужно показать заполненную форму «только для просмотра» — все поля недоступны для ввода. Тянет искать флаг `settings.readonly` / `settings.mode`.
+
+**Solution.** Такого флага **нет**. Настройки рендерера (`JsonRendererSettings`) — это `registry` + `model` поверх `RendererSettings`, а `RendererSettings` несёт только `fieldWrapper` (см. [json-renderer-context.tsx](../../src/context/json-renderer-context.tsx), renderer-react `RendererSettings`). Read-only задаётся **на уровне модели**: `form.disable()` каскадит `disabled` по всему поддереву — `GroupNode.onDisable()` рекурсивно зовёт `field.disable()` на всех детях, а рендерер пробрасывает per-field `disabled: state.disabled` в компонент. Один вызов на корне → вся форма read-only.
+
+```typescript
+// Вариант A — сразу после сборки формы (самый прямой):
+const model = createModel<MyForm>(initialValues);
+const form = createForm<MyForm>({ model, schema: convertJsonToM1Tree(jsonSchema, registry, model) });
+form.disable(); // каскад disabled по всему дереву → вся форма read-only
+```
+
+```typescript
+// Вариант B — из render-behavior (например, включить view-mode по условию/после загрузки данных):
+import { onInit, type RenderBehaviorFn } from '@reformer/renderer-react';
+
+function createReadonlyBehavior(form: FormProxy<MyForm>): RenderBehaviorFn<MyForm> {
+  return (schema) => {
+    onInit(schema.node('wizard'), () => {
+      form.disable(); // корневой FormProxy отдаёт disable() (делегирует в GroupNode)
+    });
+  };
+}
+```
+
+**Notes.**
+
+- `form.disable()` — публичный метод узла (`FormNode.disable()`): ставит статус `disabled` и вызывает hook `onDisable`, который у группы каскадит на всех детей рекурсивно. Обратно — `form.enable()`.
+- **Caveat:** поле с явным `componentProps.disabled` **перебивает** каскад. Рендерер собирает пропы как `{ value, disabled: state.disabled, ...componentProps }` — спред `componentProps` идёт ПОСЛЕ `disabled`, поэтому `componentProps.disabled: false` вернёт полю доступность даже при `form.disable()`. Не задавай `disabled` в JSON, если хочешь глобальный каскад.
+- Отключённые узлы не валидируются и не попадают в `getValue()` — для чистого view-mode это обычно желаемо; если нужен submit disabled-значений, снимай `disable()` перед сбором.
+- `settings.readonly` / `settings.mode` не существует — model-level каскад (`form.disable()`) это канонический механизм view-mode.
+
+## 33. Migration from TS RenderSchema { #migration }
+
+**Problem.** Есть готовая `RenderSchemaFn<T>` (TS-вариант с `path.email`, React-компонентами по ссылке) — нужно перенести её в JSON-схему.
+
+**Solution.** Покомпонентная карта замен. Ключевое: TS-ссылки (`path.email`, `Box`, `LOAN_TYPES`) → строки-операторы.
+
+| TS RenderSchema (`@reformer/renderer-react`)                                             | JSON-схема (`@reformer/renderer-json`, M1)                                                                 |
+| ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `{ value: path.email, component: Input }`                                                | `{ value: '$model(email)', component: '$component(Input)' }`                                               |
+| `{ value: path.personalData.firstName, component: Input }`                               | `{ value: '$model(personalData.firstName)', component: '$component(Input)' }`                              |
+| `{ component: Box, componentProps: { className: 'grid' }, children: [...] }`             | `{ component: '$component(Box)', componentProps: { className: 'grid' }, children: [...] }`                 |
+| `{ component: Section, componentProps: { title: 'X' }, children: [...] }`                | `{ component: '$component(Section)', componentProps: { title: 'X' }, children: [...] }`                    |
+| `{ selector: 'mortgage-section', component: Section, ... }`                              | то же — `selector` сохраняется (plain-строка)                                                             |
+| `componentProps: { options: LOAN_TYPES }` (импорт константы)                            | `componentProps: { options: '$dataSource(LOAN_TYPES)' }` + `reg.dataSource('LOAN_TYPES', LOAN_TYPES)`      |
+| `componentProps: { LoadingComponent: LoadingState }`                                     | `componentProps: { LoadingComponent: '$dataSource(LoadingState)' }` + `reg.dataSource('LoadingState', ...)` |
+| `{ array: path.properties, item: (ip) => ({...}), initialValue: () => ({...}) }`         | `{ array: '$model(properties)', item: { $template: {...} }, initialValue: {...} }`                          |
+
+```typescript
+// После: JSON
+const schema: JsonFormSchema = {
+  version: '1.0',
+  root: {
+    component: '$component(Box)',
+    componentProps: { className: 'space-y-4' },
+    children: [
+      { value: '$model(email)', component: '$component(Input)', componentProps: { label: 'Email' } },
+      {
+        component: '$component(Section)',
+        componentProps: { title: 'Адрес' },
+        children: [{ value: '$model(address.city)', component: '$component(Input)' }],
+      },
+    ],
+  },
+};
+
+const registry = defineRegistry((reg) => {
+  reg.component('Input', Input);
+  reg.component('Box', Box);
+  reg.component('Section', Section);
+  reg.component(FIELD_WRAPPER, FormField);
+});
+```
+
+**Notes.**
+
+- В JSON `children` всегда отдельное поле узла (не `componentProps.children`).
+- field/array/container взаимоисключающи: `value` → лист, `array`+`item` → массив, `component`+`children` → контейнер. Дискриминация в конвертере: array → field → container.
+- Поведение (`hideWhen`, `onInit`, lifecycle) **не** переезжает в JSON — остаётся TS-функцией `RenderBehaviorFn<T>` и передаётся пропом `renderBehavior`. В эталоне TS- и JSON-варианты переиспользуют один shared behavior.
+
+## 34. See also
+
+- [01-overview.md](01-overview.md) — монтаж через `model` + `JsonRendererProvider`.
+- [02-json-schema.md](02-json-schema.md) — справочник по узлам `JsonNode` и операторам.
+- [03-registry.md](03-registry.md) — все методы `defineRegistry`.
+- [04-troubleshooting.md](04-troubleshooting.md) — типичные ошибки.
+
+## 35. Mental model — почему валидаторов нет в JSON { #mental-model }
+
+Одна ключевая мысль: **JSON-DSL несёт только layout, а не правила валидации.**
+
+- `JsonFieldNode` — это `{ selector?, value, component?, componentProps?, wrapper? }` и **ничего больше**. Поля `validators` в нём нет (см. [json-schema.ts](../../src/types/json-schema.ts) — интерфейс `JsonFieldNode`).
+- Операторы DSL — только `$model(...)`, `$component(...)`, `$dataSource(...)` (см. [operators.ts](../../src/operators.ts)). Оператора `$validator(...)` **не существует**.
+- `JsonFormRenderer` с пропом `validate` (и функция `validateFormSchema`) проверяют **структуру** схемы через ajv: корректность узлов + синтаксис операторов + известность имён `$component`/`$dataSource`. Это НЕ валидация введённых пользователем значений (см. [validate.ts](../../src/validate.ts)).
+- Значит, валидацию значений выражают **отдельной TS-схемой над МОДЕЛЬЮ** (`FormModel`), а не в JSON. Схема исполняется `validateFormModel(model, schema)` — тем же движком, что и в TS-варианте формы. Одна валидация на все варианты рендера.
+
+Дальше — три шага: (1) построить схему над моделью, (2) обернуть её в `{ validateStep, validateAll }`, (3) инъектировать в wizard через render-behavior.
+
+## 36. Шаг 1 — построить схему валидации над моделью { #build-schema }
+
+Схема валидации — дерево узлов движка M1: лист `{ value: signal, validators: [...] }`, контейнер `{ children: [...] }`. `value` — сигнал модели (`model.$.path`), НЕ строка-оператор `$model(...)` (операторы — только для layout-JSON; схема валидации это обычный TS-код). Фабрики правил импортируются из `@reformer/core/validators`.
+
+```typescript
+import { type FormModel } from '@reformer/core';
+import { required, min, max, minLength, email } from '@reformer/core/validators';
+
+type M = FormModel<CreditForm>;
+
+// Под-схема одного шага: дерево field-узлов { value, validators }.
+const step1 = (model: M) => ({
+  children: [
+    { value: model.$.loanType, validators: [required({ message: 'Выберите тип кредита' })] },
+    {
+      value: model.$.loanAmount,
+      validators: [required(), min(50000, { message: 'Минимум 50 000 ₽' }), max(10000000)],
+    },
+  ],
+});
+
+const step2 = (model: M) => ({
+  children: [
+    { value: model.$.personalData.firstName, validators: [required(), minLength(2)] },
+    { value: model.$.email, validators: [required(), email()] },
+  ],
+});
+
+// Карта шагов + полная схема (объединение для submit).
+const STEP_BUILDERS = [step1, step2];
+```
+
+Условные группы (`{ when, children }`), cross-field правила, секции массивов — тот же движок, что в TS-форме. Полное описание узлов схемы и `validateFormModel` — в `@reformer/core` [13-multi-step.md](../../../reformer/docs/llms/13-multi-step.md) (не дублируем здесь).
+
+## 37. Шаг 2 — исполнить: `{ validateStep, validateAll }` { #execute }
+
+`validateFormModel(model, schema)` прогоняет схему по текущим значениям модели и **сам роутит ошибки в ноды формы** (UI подсветит проблемные поля). Возвращает `{ valid, errors }`. Оборачиваем в две функции — контракт `FormWizardConfig` из `@reformer/cdk` (см. [form-wizard/types.ts](../../../reformer-cdk/src/components/form-wizard/types.ts): `validateStep?(step): boolean | Promise<boolean>`, `validateAll?(): boolean | Promise<boolean>`).
+
+```typescript
+import { validateFormModel } from '@reformer/core';
+
+export function makeValidationConfig(model: M) {
+  // Схема зависит только от ФОРМЫ модели, не от значений — строим дерево один раз.
+  const stepSchemas = STEP_BUILDERS.map((build) => build(model));
+  const fullSchema = { children: stepSchemas };
+
+  return {
+    validateStep: async (step: number): Promise<boolean> => {
+      const res = await validateFormModel(model, stepSchemas[step - 1] ?? { children: [] });
+      return res.valid; // ошибки уже проставлены в ноды текущего шага
+    },
+    validateAll: async (): Promise<boolean> => {
+      const res = await validateFormModel(model, fullSchema);
+      return res.valid;
+    },
+  };
+}
+```
+
+## 38. Шаг 3 — инъекция в wizard через render-behavior { #inject }
+
+JSON-схема статична и не знает про `FormProxy`/validation-конфиг — это рантайм-сущности. Инжектируем их в wizard-ноду через `renderBehavior` + `onInit` + `patchProps` до первого рендера (общий приём — см. [05-cookbook.md#inject-runtime](05-cookbook.md#inject-runtime)). Wizard-узел JSON-схемы должен нести `selector: 'wizard'`, чтобы адресоваться через `schema.node('wizard')`.
+
+```typescript
+import { onInit, type RenderBehaviorFn } from '@reformer/renderer-react';
+import type { FormProxy, FormModel } from '@reformer/core';
+
+export function createJsonRenderBehavior(
+  form: FormProxy<CreditForm>,
+  model: FormModel<CreditForm>
+): RenderBehaviorFn<CreditForm> {
+  return (schema) => {
+    // JSON не выражает FormProxy/валидацию — инъектим их в wizard до первого рендера.
+    onInit(schema.node('wizard'), () => {
+      schema.node('wizard').patchProps({ form, ...makeValidationConfig(model) });
+    });
+    // Остальное поведение (visibility/navigation) — из shared render-behavior.
+    createSharedRenderBehavior(form)(schema);
+  };
+}
+
+// <JsonFormRenderer schema={jsonSchema} renderBehavior={createJsonRenderBehavior(form, model)} />
+```
+
+`patchProps({ form, validateStep, validateAll })` кладёт `form` + оба колбэка в `componentProps` wizard-ноды. Wizard-компонент читает их как `FormWizardConfig` и запускает `validateStep` на «Далее», `validateAll` на submit.
+
+## 39. Полный рабочий пример { #full-example }
+
+Зеркалит golden-эталон (`complex-multy-step-form-renderer-json`): валидация — TS-схема над моделью, переиспользуемая всеми вариантами рендера, инъектируется в JSON-wizard. Submit и навигация между шагами приходят **не** отсюда, а из shared render-behavior — JSON-вариант лишь до-инъектит `form`/валидацию и делегирует остальное (см. [07-form-wizard.md](07-form-wizard.md)).
+
+```typescript
+// validation.ts — TS-схема над МОДЕЛЬЮ (не JSON)
+import { validateFormModel, type FormModel } from '@reformer/core';
+import { required, min, minLength, email } from '@reformer/core/validators';
+import type { CreditForm } from './types';
+
+type M = FormModel<CreditForm>;
+
+const step1 = (model: M) => ({
+  children: [
+    { value: model.$.loanType, validators: [required({ message: 'Выберите тип кредита' })] },
+    { value: model.$.loanAmount, validators: [required(), min(50000, { message: 'Минимум 50 000 ₽' })] },
+  ],
+});
+const step2 = (model: M) => ({
+  children: [
+    { value: model.$.personalData.firstName, validators: [required(), minLength(2)] },
+    { value: model.$.email, validators: [required(), email()] },
+  ],
+});
+const STEP_BUILDERS = [step1, step2];
+
+/** Контракт FormWizardConfig: per-step + полная валидация через validateFormModel. */
+export function makeValidationConfig(model: M) {
+  const stepSchemas = STEP_BUILDERS.map((build) => build(model));
+  const fullSchema = { children: stepSchemas };
+  return {
+    validateStep: async (step: number) =>
+      (await validateFormModel(model, stepSchemas[step - 1] ?? { children: [] })).valid,
+    validateAll: async () => (await validateFormModel(model, fullSchema)).valid,
+  };
+}
+```
+
+```typescript
+// render-behavior.ts — инъекция form + валидации в JSON-wizard
+import { onInit, type RenderBehaviorFn } from '@reformer/renderer-react';
+import type { FormProxy, FormModel } from '@reformer/core';
+import type { CreditForm } from './types';
+import { makeValidationConfig } from './validation';
+// Единый behavior (submit/навигация/visibility) — общий для TS- и JSON-варианта. См. 07-form-wizard.md.
+import { createSharedRenderBehavior } from './render-behavior.shared';
+
+export function createJsonRenderBehavior(
+  form: FormProxy<CreditForm>,
+  model: FormModel<CreditForm>
+): RenderBehaviorFn<CreditForm> {
+  return (schema) => {
+    // (1) Инъекция рантайм-сущностей: form + validation-конфиг в wizard-ноду.
+    onInit(schema.node('wizard'), () => {
+      schema.node('wizard').patchProps({ form, ...makeValidationConfig(model) });
+    });
+    // (2) Submit + навигация между шагами + visibility — из shared render-behavior.
+    //     БЕЗ этого вызова форма валидирует, но НЕ сабмитит и не навигирует (golden
+    //     `complex-multy-step-form-renderer-json/render-behavior.ts` делегирует так же).
+    createSharedRenderBehavior(form)(schema);
+  };
+}
+```
+
+## 40. Anti-patterns
+
+- **Ждать, что `validate={true}` (или `validateFormSchema`) валидирует значения** — этот проп проверяет только СТРУКТУРУ схемы через ajv (узлы + синтаксис операторов + имена компонентов). Введённые пользователем значения он не трогает. Валидацию значений исполняет `validateFormModel` над моделью.
+- **Пытаться добавить `validators` в JSON field-node** — `JsonFieldNode` несёт только layout (`value`/`component`/`componentProps`/`wrapper`). Поля `validators` в нём нет, оператора `$validator(...)` не существует. TypeScript отклонит лишнее поле; даже если протащить через `as`, конвертер его проигнорирует.
+- **Строить схему валидации по значениям, а не по shape модели** — узел это `{ value: model.$.path, validators }`, где `value` — сигнал (стабильная ссылка на форму модели), а не текущее значение поля. Схему собирают один раз на `model`; значения читаются движком в момент прогона `validateFormModel`.
+- **Забыть `selector: 'wizard'` у wizard-ноды** — без `selector` узел не адресуется через `schema.node('wizard')`, `onInit`/`patchProps` не найдут его и валидация не инъектируется (submit пройдёт без блокировки).
+
+## 41. See also
+
+- [07-form-wizard.md](07-form-wizard.md) — end-to-end wizard в JSON: submit (`onComponentEvent`), навигация (`renderEffect`) и инъекция этой валидации в одном месте.
+- [02-json-schema.md](02-json-schema.md) — справочник по узлам `JsonNode` (field-node несёт только layout).
+- [05-cookbook.md#inject-runtime](05-cookbook.md#inject-runtime) — общий приём инъекции runtime-сущностей через `onInit`/`patchProps`.
+- `@reformer/core` [13-multi-step.md](../../../reformer/docs/llms/13-multi-step.md) — узлы схемы валидации, `validateFormModel`, STEP_SCHEMAS.
+- [Типы JsonFormSchema/JsonNode](../../src/types/json-schema.ts) и [validate.ts](../../src/validate.ts) — структурная валидация схемы.
+
+## 42. Половина 1 — layout шагов в JSON { #json-shape }
+
+Wizard — обычная container-нода со `selector: 'wizard'` (чтобы адресоваться через `schema.node('wizard')`). Шаги лежат в **`componentProps.steps`** — массив container-нод, а **не** в top-level `children`. Каждый шаг — нода `$component(Step)` с `componentProps: { title, icon }` и собственным `children` (поддерево layout шага).
+
+```json
+{
+  "selector": "wizard",
+  "component": "$component(Wizard)",
+  "componentProps": {
+    "className": "bg-white p-8 rounded-lg shadow-md",
+    "steps": [
+      {
+        "component": "$component(Step)",
+        "componentProps": { "title": "Кредит", "icon": "💰" },
+        "children": [
+          {
+            "selector": "mortgage-section",
+            "component": "$component(Section)",
+            "componentProps": { "title": "Ипотека" },
+            "children": [
+              { "value": "$model(loanAmount)", "component": "$component(Input)",
+                "componentProps": { "label": "Сумма кредита (₽)", "type": "number" } }
+            ]
+          }
+        ]
+      },
+      {
+        "component": "$component(Step)",
+        "componentProps": { "title": "Заявитель", "icon": "🧑" },
+        "children": [
+          { "value": "$model(personalData.firstName)", "component": "$component(Input)",
+            "componentProps": { "label": "Имя" } }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Ground truth: golden `complex-multy-step-form-renderer-json/json-schema.json` (wizard-нода — `selector: 'wizard'`, `steps` внутри `componentProps`, каждый шаг — `$component(Step)` + `componentProps.title/icon` + `children`).
+
+> Отличие от `@reformer/renderer-react`: там шаг — объект `{ number, title, icon, body }`, где `body` — самостоятельный `RenderNode` (см. renderer-react [01-overview.md](../../../reformer-renderer-react/docs/llms/01-overview.md#multi-step-forms)). В JSON-DSL нельзя вписать `RenderNode` как значение пропа, поэтому шаг выражается **container-нодой** `Step` + `children`, а wizard-компонент адаптирует эту форму под `step.body`.
+
+## 43. Регистрируй свой wizard-компонент в реестре { #register }
+
+`$component(Wizard)` — это **запись в реестре**, а не библиотечный экспорт: имя резолвится через registry (`reg.component('Wizard', <твой компонент>)`). Имя произвольное — важно лишь совпадение строки в JSON и ключа в реестре.
+
+Канонический shipped-компонент — `FormWizard` из `@reformer/ui-kit/form-wizard` (см. renderer-react [01-overview.md](../../../reformer-renderer-react/docs/llms/01-overview.md#multi-step-forms)). Он принимает `componentProps.form`, `componentProps.steps` и `FormWizardConfig` (`validateStep`/`validateAll`), а `step.body` полиморфен (`FC | ReactNode | RenderNode<T>`). Твой зарегистрированный компонент должен быть совместим с этим контрактом.
+
+```typescript
+import { defineRegistry } from '@reformer/renderer-json';
+import { Step } from '@reformer/cdk/form-wizard';
+import { MyWizard } from './MyWizard'; // тонкая обёртка над ui-kit FormWizard
+
+const registry = defineRegistry((reg) => {
+  reg.component('Wizard', MyWizard); // ← имя из JSON `$component(Wizard)`
+  reg.component('Step', Step);       // container-нода шага
+  // ...остальные компоненты (Input, Select, Section, ...)
+});
+```
+
+> В golden-эталоне под `$component(Wizard)` зарегистрирован app-shim `RendererFormWizard`: он снимает `title`/`icon` c `componentProps` Step-ноды, а сам Step-узел кладёт в `step.body` ui-kit `FormWizard`. Shim — деталь приложения, **не** канон библиотеки; регистрируй под этим именем любой совместимый с `FormWizard` компонент.
+
+## 44. Половина 2 — поведение в одном render-behavior { #render-behavior }
+
+Один `RenderBehaviorFn<T>` навешивает всё рантайм-поведение на wizard-ноду. Порядок: (a) инъекция `form` + валидации через `onInit`; (b) submit через `onComponentEvent`; (c) навигация через `renderEffect` + `wizardRef`; (d) условные секции через `hideWhen`. Семантику хелперов см. renderer-react [03-render-behavior.md](../../../reformer-renderer-react/docs/llms/03-render-behavior.md).
+
+```typescript
+import {
+  onInit,
+  onComponentEvent,
+  renderEffect,
+  hideWhen,
+  type RenderBehaviorFn,
+} from '@reformer/renderer-react';
+import type { FormProxy, FormModel } from '@reformer/core';
+import type { FormWizardHandle } from '@reformer/cdk/form-wizard';
+import type { CreditForm } from './types';
+import { makeValidationConfig } from './validation'; // см. 06-validation.md
+import { submitCreditApplication } from './api';
+
+export function createWizardRenderBehavior(
+  form: FormProxy<CreditForm>,
+  model: FormModel<CreditForm>
+): RenderBehaviorFn<CreditForm> {
+  return (schema) => {
+    const wizard = schema.node('wizard');
+    const wizardRef = wizard.getRef<FormWizardHandle<CreditForm>>();
+
+    // (a) Инъекция рантайма: form + validateStep/validateAll в wizard-ноду до первого рендера.
+    //     Валидация — TS-схема над МОДЕЛЬЮ (не JSON). Детали — 06-validation.md.
+    onInit(wizard, () => {
+      wizard.patchProps({ form, ...makeValidationConfig(model) });
+    });
+
+    // (b) Submit: onComponentEvent получает те же аргументы, что и оригинальный проп onSubmit.
+    onComponentEvent(wizard, 'onSubmit', async (values: CreditForm) => {
+      await submitCreditApplication(values);
+    });
+
+    // (c) Навигация: реактивный эффект принимает СХЕМУ (не ноду); wizardRef доступен после mount.
+    renderEffect(schema, () => {
+      if (form.loanType.value.value === 'mortgage') {
+        wizardRef.current?.goToStep(1);
+      }
+    });
+
+    // (d) Условные секции: реактивно по сигналам формы (читай сигнал целиком: `.value.value`).
+    hideWhen(schema.node('mortgage-section'), () => form.loanType.value.value !== 'mortgage');
+  };
+}
+
+// <JsonFormRenderer schema={jsonSchema} renderBehavior={createWizardRenderBehavior(form, model)} />
+```
+
+Ground truth: golden `complex-multy-step-form-renderer/render-behavior.ts` — `onComponentEvent(schema.node('wizard'), 'onSubmit', ...)`, `renderEffect(schema, () => wizardRef.current?.goToStep(1))`, `hideWhen(...)`; инъекция `form`+валидации — `complex-multy-step-form-renderer-json/render-behavior.ts`.
+
+## 45. Anti-patterns
+
+- **Класть шаги в top-level `children` wizard-ноды** — шаги живут в `componentProps.steps`. Top-level `children` wizard-компонент не читает как шаги.
+- **Ждать шаг как `{ number, title, icon, body }` в JSON** — это форма renderer-react. В JSON шаг — container-нода `$component(Step)` + `componentProps.title/icon` + `children`.
+- **Считать `RendererFormWizard` библиотечным экспортом** — это app-shim эталона. Wizard-компонент подключается через реестр под любым именем; канон — ui-kit `FormWizard`.
+- **Забыть `createWizardRenderBehavior` (только `onInit` с валидацией)** — форма будет валидировать, но `onSubmit`/навигация не подключатся: submit-less форма. Submit и навигация приходят из этого же behavior.
+- **`renderEffect(node, ...)` вместо `renderEffect(schema, ...)`** — первый аргумент `renderEffect` это схема, а не узел (в отличие от `hideWhen`/`onComponentEvent`).
+- **Забыть `selector: 'wizard'`** — без селектора `schema.node('wizard')` не адресует узел, инъекция/submit/навигация не навесятся.
+
+## 46. See also
+
+- [06-validation.md](06-validation.md) — `makeValidationConfig` (TS-схема над моделью), инъекция `validateStep`/`validateAll` в wizard.
+- [05-cookbook.md#inject-runtime](05-cookbook.md#inject-runtime) — общий приём инъекции runtime-сущностей (`form`) через `onInit`/`patchProps`.
+- renderer-react [03-render-behavior.md](../../../reformer-renderer-react/docs/llms/03-render-behavior.md) — семантика `hideWhen`/`renderEffect`/`onComponentEvent`/`onInit`.
+- renderer-react [01-overview.md](../../../reformer-renderer-react/docs/llms/01-overview.md#multi-step-forms) — канонический `FormWizard`, форма шага `{ number, title, icon, body }`.
+
+## 47. API Reference
+
+_Auto-generated from JSDoc on public exports._
+
+### buildFormSchemaMetaSchema
+
+**Kind:** `function`
+
+Конкретная мета-схема: базовая + (если заданы `componentNames`) сужение `$component(...)` до
+enum допустимых значений (`["$component(Input)", "$component(Select)", …]`). `$dataSource`-имена
+JSON Schema'й не покрыть (вложены в произвольный componentProps) — их проверяет рекурсивный обход
+в `validateFormSchema`.
+
+enum, а не regex-`pattern`: ajv перечисляет допустимые имена в тексте ошибки, IDE даёт
+автодополнение по значениям, а имена не нужно экранировать под regex (напр. `$fieldWrapper`).
+
+**Signature:**
+```typescript
+export function buildFormSchemaMetaSchema(opts?: {
+  componentNames?: string[];
+}): Record<string, unknown>
+```
+
+**Examples:**
+
+```ts
+const schema = buildFormSchemaMetaSchema({ componentNames: getComponentNames(registry) });
+```
+
+_Source: src/schema/index.ts_
+
+### ComponentMetadata
+
+**Kind:** `interface`
+
+Запись реестра. Хранит сам компонент (или dataSource-значение) и его роль.
+
+**Signature:**
+```typescript
+export interface ComponentMetadata<P = any> {
+  component: ComponentType<P> | unknown;
+  type: 'component' | 'dataSource';
+  description?: string;
+}
+```
+
+**Examples:**
+
+```typescript
+const meta: ComponentMetadata = registry.get('Input')!;
+meta.type; // 'component'
+```
+
+_Source: src/registry/types.ts_
+
+### ComponentOp
+
+**Kind:** `type`
+
+Строка-оператор ссылки на компонент реестра: `` `$component(${name})` ``.
+
+**Signature:**
+```typescript
+export type ComponentOp = `$component(${string})`;
+```
+
+_Source: src/operators.ts_
+
+### ComponentRegistry
+
+**Kind:** `interface`
+
+Read-only API реестра, доступное в рантайме.
+
+Создаётся через {@link defineRegistry}. Передаётся в `JsonRendererProvider`
+через `settings.registry`.
+
+**Signature:**
+```typescript
+export interface ComponentRegistry {
+  get(name: string): ComponentMetadata | undefined;
+  getDataSource<T = unknown>(name: string): T | undefined;
+  has(name: string): boolean;
+  names(): string[];
+}
+```
+
+**Examples:**
+
+```typescript
+if (registry.has('Input')) {
+  registry.get('Input'); // ComponentMetadata
+}
+registry.names(); // ['Input', 'Box', 'LOAN_TYPES', ...]
+```
+
+_Source: src/registry/types.ts_
+
+### convertJsonToM1Tree
+
+**Kind:** `function`
+
+Сырое дерево RenderNode из JSON (M1) — для `createForm({ model, schema })`. Листья привязываются
+к сигналам модели (`'$model(path)'` → `model.signalAt`), компоненты/источники — из реестра.
+
+**Signature:**
+```typescript
+export function convertJsonToM1Tree<T>(
+  schema: JsonFormSchema,
+  registry: ComponentRegistry,
+  model: FormModel<T>
+): RenderNode<T>
+```
+
+**Parameters:**
+- `schema` — - JSON-схема формы ({@link JsonFormSchema}).
+- `registry` — - Реестр компонентов/источников (см. {@link defineRegistry}).
+- `model` — - Модель данных — источник значений (`FormModel`).
+
+**Returns:** Корневой {@link RenderNode} — кладётся в `createForm({ schema })`.
+
+**Examples:**
+
+Собрать форму из JSON-схемы (M1)
+```ts
+import { createForm } from '@reformer/core';
+
+const form = createForm<MyForm>({
+model,
+schema: convertJsonToM1Tree(jsonSchema, registry, model),
+behavior,
+});
+```
+
+_Source: src/converter/json-to-render-schema.ts_
+
+### createRenderSchemaFromJsonM1
+
+**Kind:** `function`
+
+`RenderSchemaFn` из JSON (M1) — для `FormRenderer`/`JsonFormRenderer`. Листья привязываются к
+сигналам модели (`'$model(path)'` → `model.signalAt`), компоненты/источники — из реестра.
+
+В отличие от {@link convertJsonToM1Tree} (который возвращает готовое дерево), здесь результат —
+ленивая функция-фабрика дерева, как её ждёт `createRenderSchema`. Обычно вызывается внутри
+{@link JsonFormRenderer}; напрямую нужен для интеграции с `FormRenderer` без JSON-обёртки.
+
+**Signature:**
+```typescript
+export function createRenderSchemaFromJsonM1<T>(
+  schema: JsonFormSchema,
+  registry: ComponentRegistry,
+  model: FormModel<T>
+): RenderSchemaFn<T>
+```
+
+**Parameters:**
+- `schema` — - JSON-схема формы ({@link JsonFormSchema}).
+- `registry` — - Реестр компонентов/источников (см. {@link defineRegistry}).
+- `model` — - Модель данных — источник значений (`FormModel`).
+
+**Returns:** `RenderSchemaFn<T>` — фабрика {@link RenderNode}-дерева для `createRenderSchema`.
+
+**Examples:**
+
+```ts
+import { createRenderSchema, FormRenderer } from '@reformer/renderer-react';
+
+const fn = createRenderSchemaFromJsonM1<MyForm>(jsonSchema, registry, model);
+const proxy = createRenderSchema<MyForm>(fn);
+<FormRenderer render={proxy} />;
+```
+
+_Source: src/converter/json-to-render-schema.ts_
+
+### DataSourceOp
+
+**Kind:** `type`
+
+Строка-оператор ссылки на registry-source: `` `$dataSource(${name})` ``.
+
+**Signature:**
+```typescript
+export type DataSourceOp = `$dataSource(${string})`;
+```
+
+_Source: src/operators.ts_
+
+### defineRegistry
+
+**Kind:** `function`
+
+Создаёт реестр компонентов через builder-callback.
+
+Реестр обязателен для работы {@link JsonFormRenderer} — иначе компоненты,
+упомянутые в JSON-схеме, не отрезолвятся.
+
+**Signature:**
+```typescript
+export function defineRegistry(fn: (reg: RegistryBuilder) => void): ComponentRegistry
+```
+
+**Parameters:**
+- `fn` — - Builder-callback. Получает {@link RegistryBuilder} с методами `component`, `dataSource`.
+
+**Returns:** Готовый {@link ComponentRegistry}, который кладётся в `JsonRendererProvider`.
+
+**Examples:**
+
+```typescript
+import { defineRegistry, FIELD_WRAPPER } from '@reformer/renderer-json';
+import { Input, Select, FormField } from '@reformer/ui-kit';
+
+const registry = defineRegistry((reg) => {
+  reg.component('Input', Input);
+  reg.component('Select', Select);
+  reg.component(FIELD_WRAPPER, FormField);
+  reg.dataSource('LOAN_TYPES', [
+    { value: 'consumer', label: 'Потребительский' },
+    { value: 'mortgage', label: 'Ипотека' },
+  ]);
+});
+```
+
+**See also:**
+- [docs/llms/03-registry.md](../../docs/llms/03-registry.md)
+
+_Source: src/registry/component-registry.ts_
+
+### FIELD_WRAPPER
+
+**Kind:** `const`
+
+Зарезервированный ключ реестра для контейнера-обёртки полей.
+
+Зарегистрируй компонент под этим именем (обычно `FormField` из `@reformer/ui-kit`),
+чтобы каждое поле получало label, error и hint автоматически.
+
+**Signature:**
+```typescript
+export const FIELD_WRAPPER
+```
+
+**Examples:**
+
+```typescript
+import { defineRegistry, FIELD_WRAPPER } from '@reformer/renderer-json';
+import { FormField } from '@reformer/ui-kit';
+
+const registry = defineRegistry((reg) => {
+  reg.component(FIELD_WRAPPER, FormField);
+});
+```
+
+_Source: src/registry/constants.ts_
+
+### formSchemaMetaSchema
+
+**Kind:** `const`
+
+Базовая мета-схема form-DSL (draft-07): структура узлов + синтаксис операторов, имена компонентов
+НЕ ограничены (паттерн `$component(...)` открыт). Для сужения до конкретного реестра —
+{@link buildFormSchemaMetaSchema}. Используется как `$schema` в IDE и как база валидатора.
+
+**Signature:**
+```typescript
+export const formSchemaMetaSchema
+```
+
+**Examples:**
+
+Подключить как `$schema` в JSON-файле схемы
+```ts
+// record можно записать в файл и сослаться на него из "$schema" JSON-схемы.
+formSchemaMetaSchema.$schema; // 'http://json-schema.org/draft-07/schema#'
+```
+
+_Source: src/schema/index.ts_
+
+### getComponentNames
+
+**Kind:** `function`
+
+Имена компонентов реестра (тип `component`) — то, что валидно в `$component(...)`.
+
+**Signature:**
+```typescript
+export function getComponentNames(registry: ComponentRegistry): string[]
+```
+
+**Parameters:**
+- `registry` — - Реестр (см. {@link defineRegistry}).
+
+**Returns:** Массив имён компонентов.
+
+**Examples:**
+
+Сузить мета-схему до компонентов реестра
+```ts
+const names = getComponentNames(registry); // ['Input', 'Select', 'Box', ...]
+const schema = buildFormSchemaMetaSchema({ componentNames: names });
+```
+
+_Source: src/schema/index.ts_
+
+### getDataSourceNames
+
+**Kind:** `function`
+
+Имена registry-dataSource (`reg.dataSource`) — то, что валидно в `$dataSource(...)`:
+options/itemLabel/константы/loading-компоненты.
+
+**Signature:**
+```typescript
+export function getDataSourceNames(registry: ComponentRegistry): string[]
+```
+
+**Parameters:**
+- `registry` — - Реестр (см. {@link defineRegistry}).
+
+**Returns:** Массив имён источников.
+
+**Examples:**
+
+```ts
+getDataSourceNames(registry); // ['LOAN_TYPES', 'GENDERS', 'LoadingState', ...]
+```
+
+_Source: src/schema/index.ts_
+
+### isArrayNode
+
+**Kind:** `function`
+
+Type-guard: узел — массив (`array: '$model(...)'` + `item.$template`). Проверять ПЕРВЫМ
+(лист/контейнер отсеиваются после, т.к. массив тоже несёт `$model`).
+
+**Signature:**
+```typescript
+export function isArrayNode(node: JsonNode): node is JsonArrayNode
+```
+
+**Parameters:**
+- `node` — - Узел JSON-схемы.
+
+**Returns:** `true`, если узел — {@link JsonArrayNode}.
+
+**Examples:**
+
+Сузить тип узла перед доступом к `item.$template`
+```ts
+if (isArrayNode(node)) {
+node.array;            // ModelOp
+node.item.$template;   // JsonNode
+}
+```
+
+_Source: src/types/json-schema.ts_
+
+### isComponentOp
+
+**Kind:** `const`
+
+Type-guard: строка — оператор `"$component(...)"` (ссылка на компонент реестра).
+
+**Signature:**
+```typescript
+export const isComponentOp
+```
+
+**Parameters:**
+- `v` — - Проверяемое значение.
+
+**Returns:** `true`, если `v` — {@link ComponentOp}.
+
+**Examples:**
+
+```ts
+if (isComponentOp(node.component)) {
+  const name = parseOperator(node.component)!.arg; // 'Select'
+}
+```
+
+_Source: src/operators.ts_
+
+### isContainerNode
+
+**Kind:** `function`
+
+Type-guard: узел — контейнер (`component: '$component(...)'`, без `value`/`array`).
+
+**Signature:**
+```typescript
+export function isContainerNode(node: JsonNode): node is JsonContainerNode
+```
+
+**Parameters:**
+- `node` — - Узел JSON-схемы.
+
+**Returns:** `true`, если узел — {@link JsonContainerNode}.
+
+**Examples:**
+
+Сузить тип узла перед обходом `children`
+```ts
+if (isContainerNode(node)) {
+node.component;   // ComponentOp
+node.children?.forEach(walk);
+}
+```
+
+_Source: src/types/json-schema.ts_
+
+### isDataSourceOp
+
+**Kind:** `const`
+
+Type-guard: строка — оператор `"$dataSource(...)"` (ссылка на registry-source).
+
+**Signature:**
+```typescript
+export const isDataSourceOp
+```
+
+**Parameters:**
+- `v` — - Проверяемое значение.
+
+**Returns:** `true`, если `v` — {@link DataSourceOp}.
+
+**Examples:**
+
+```ts
+if (isDataSourceOp(props.options)) {
+  const name = parseOperator(props.options)!.arg; // 'LOAN_TYPES'
+}
+```
+
+_Source: src/operators.ts_
+
+### isFieldNode
+
+**Kind:** `function`
+
+Type-guard: узел — лист (`value: '$model(...)'`).
+
+**Signature:**
+```typescript
+export function isFieldNode(node: JsonNode): node is JsonFieldNode
+```
+
+**Parameters:**
+- `node` — - Узел JSON-схемы.
+
+**Returns:** `true`, если узел — {@link JsonFieldNode}.
+
+**Examples:**
+
+Сузить тип узла перед доступом к `value`/`component`
+```ts
+if (isFieldNode(node)) {
+node.value;      // ModelOp
+node.component;  // ComponentOp | undefined
+}
+```
+
+_Source: src/types/json-schema.ts_
+
+### isModelOp
+
+**Kind:** `const`
+
+Type-guard: строка — оператор `"$model(...)"` (привязка к полю/массиву модели).
+
+**Signature:**
+```typescript
+export const isModelOp
+```
+
+**Parameters:**
+- `v` — - Проверяемое значение.
+
+**Returns:** `true`, если `v` — {@link ModelOp}.
+
+**Examples:**
+
+Сузить тип значения prop до ModelOp
+```ts
+if (isModelOp(value)) {
+const path = parseOperator(value)!.arg; // 'loanType'
+}
+```
+
+_Source: src/operators.ts_
+
+### JsonArrayNode
+
+**Kind:** `interface`
+
+Массив форм: данные из модели (`$model`) + шаблон элемента (`$template`).
+
+**Signature:**
+```typescript
+export interface JsonArrayNode {
+  /** Id для render-behavior. */
+  selector?: string;
+  /** Привязка к массиву модели: `'$model(coBorrowers)'`. */
+  array: ModelOp;
+  /** Шаблон под-схемы элемента. */
+  item: { $template: JsonNode };
+  /**
+   * «Пустой» элемент для кнопки «Добавить» (литерал-объект по форме элемента).
+   * Нужен, т.к. листья шаблона несут `value: '$model(...)'`, а не литерал-дефолт.
+   */
+  initialValue?: Record<string, unknown>;
+  /** Оформление секции массива (title/addButtonLabel/itemLabel/emptyMessage/…). */
+  componentProps?: Record<string, unknown>;
+}
+```
+
+_Source: src/types/json-schema.ts_
+
+### JsonContainerNode
+
+**Kind:** `interface`
+
+Контейнер (Box/Section/Wizard/Step/…) с дочерними узлами.
+
+**Signature:**
+```typescript
+export interface JsonContainerNode {
+  /** Id для render-behavior. */
+  selector?: string;
+  /** Компонент-контейнер из реестра: `'$component(Section)'`. */
+  component: ComponentOp;
+  /** Props компонента; значения могут содержать строки-операторы или вложенные узлы. */
+  componentProps?: Record<string, unknown>;
+  /** Дочерние узлы. */
+  children?: JsonNode[];
+}
+```
+
+_Source: src/types/json-schema.ts_
+
+### JsonFieldNode
+
+**Kind:** `interface`
+
+Лист формы: значение из модели (`$model`) + опциональный компонент (`$component`, дефолт — Input).
+
+**Signature:**
+```typescript
+export interface JsonFieldNode {
+  /** Id для render-behavior (hideWhen/patchProps). Опционален. */
+  selector?: string;
+  /** Привязка к сигналу модели: `'$model(personalData.lastName)'`. */
+  value: ModelOp;
+  /** Компонент поля из реестра: `'$component(Select)'`. Опционален. */
+  component?: ComponentOp;
+  /** Props компонента; значения могут содержать строки-операторы (`'$dataSource(NAME)'`) или вложенные узлы. */
+  componentProps?: Record<string, unknown>;
+  /** Обёртка поля (например, FormField). */
+  wrapper?: JsonNode;
+}
+```
+
+_Source: src/types/json-schema.ts_
+
+### JsonFormRenderer
+
+**Kind:** `function`
+
+Главный компонент пакета. Рендерит форму, описанную JSON-схемой.
+
+Должен использоваться внутри {@link JsonRendererProvider}, который снабжает рендерер
+реестром компонентов. Без реестра компонент бросит исключение при попытке резолва.
+
+**Signature:**
+```typescript
+export function JsonFormRenderer<T>({
+  schema,
+  renderBehavior,
+  onSchemaReady,
+  validate = false,
+}: JsonFormRendererProps<T>): ReactNode
+```
+
+**Examples:**
+
+Форма из JSON-схемы (M1)
+```tsx
+import { useMemo } from 'react';
+import { createModel } from '@reformer/core';
+import { Input, Box, FormField } from '@reformer/ui-kit';
+import {
+JsonFormRenderer,
+JsonRendererProvider,
+defineRegistry,
+FIELD_WRAPPER,
+type JsonFormSchema,
+} from '@reformer/renderer-json';
+
+// Привязки — строки-операторы: '$model(...)', '$component(...)', '$dataSource(...)'.
+const schema: JsonFormSchema = {
+version: '1.0',
+root: {
+component: '$component(Box)',
+children: [
+{
+value: '$model(email)',
+component: '$component(Input)',
+componentProps: { label: 'Email' },
+},
+],
+},
+};
+
+type MyForm = { email: string };
+
+function MyFormPage() {
+// M1: модель — источник истины значений; листья схемы биндятся к её сигналам.
+const model = useMemo(() => createModel<MyForm>({ email: '' }), []);
+const registry = useMemo(() => defineRegistry((reg) => {
+reg.component('Input', Input);
+reg.component('Box', Box);
+reg.component(FIELD_WRAPPER, FormField); // системная обёртка полей
+}), []);
+
+// Модель передаётся через провайдер (settings.model), НЕ пропом рендерера.
+return (
+<JsonRendererProvider settings={{ registry, model }}>
+<JsonFormRenderer<MyForm> schema={schema} validate={import.meta.env.DEV} />
+</JsonRendererProvider>
+);
+}
+```
+
+**Note**: `JsonFormRenderer` принимает ТОЛЬКО `{ schema, renderBehavior?, onSchemaReady?, validate? }`.
+Под M1 модель (`FormModel`) передаётся через {@link JsonRendererProvider} settings (`model`);
+листья JSON-схемы биндятся к её сигналам конвертером {@link createRenderSchemaFromJsonM1}.
+
+**See also:**
+- [docs/llms/01-overview.md](../../docs/llms/01-overview.md)
+
+_Source: src/components/json-form-renderer.tsx_
+
+### JsonFormRendererProps
+
+**Kind:** `interface`
+
+Props of {@link JsonFormRenderer}.
+
+**Signature:**
+```typescript
+export interface JsonFormRendererProps<T> {
+  /** JSON-схема формы. См. {@link JsonFormSchema}. */
+  schema: JsonFormSchema;
+  /** Опциональный behavior: hideWhen/patchProps/onComponentEvent поверх готовой схемы. */
+  renderBehavior?: RenderBehaviorFn<T>;
+  /** Колбэк, получающий построенный `RenderSchemaProxy` для внешних манипуляций. */
+  onSchemaReady?: (schema: RenderSchemaProxy<T>) => void;
+  /**
+   * Валидировать JSON-схему против мета-схемы перед рендером. При ошибках рисует
+   * {@link SchemaErrorPanel} вместо формы. ajv грузится **динамически** (`import('../validate')`) —
+   * в prod-бандл не попадает, пока `validate` не включён.
+   *
+   * По умолчанию `false`. Чтобы валидировать только в dev, приложение передаёт значение из
+   * СВОЕГО окружения: `validate={import.meta.env.DEV}` — детекцию dev нельзя «запечь» в пакет,
+   * т.к. `import.meta.env.DEV` инлайнится в `false` при production-сборке самого пакета.
+   */
+  validate?: boolean;
+}
+```
+
+_Source: src/components/json-form-renderer.tsx_
+
+### JsonFormSchema
+
+**Kind:** `interface`
+
+Корневая JSON-схема формы.
+
+**Signature:**
+```typescript
+export interface JsonFormSchema {
+  /**
+   * Путь к мета-схеме для IDE (VSCode подсветит структуру/синтаксис/имена `$component`).
+   * Игнорируется конвертером. Сгенерировать конкретную мета-схему: `gen-form-json-schema.ts`.
+   */
+  $schema?: string;
+  /** Версия схемы (для миграций). */
+  version?: string;
+  /** Корневой узел. */
+  root: JsonNode;
+}
+```
+
+**Examples:**
+
+```ts
+const schema: JsonFormSchema = {
+  version: '1.0',
+  root: {
+    component: '$component(Box)',
+    children: [{ value: '$model(email)', component: '$component(Input)' }],
+  },
+};
+```
+
+_Source: src/types/json-schema.ts_
+
+### JsonNode
+
+**Kind:** `type`
+
+Узел JSON-схемы (M1).
+
+**Signature:**
+```typescript
+export type JsonNode = JsonFieldNode | JsonArrayNode | JsonContainerNode;
+```
+
+_Source: src/types/json-schema.ts_
+
+### JsonOperator
+
+**Kind:** `type`
+
+Любой строковый оператор JSON-схемы.
+
+**Signature:**
+```typescript
+export type JsonOperator = ModelOp | ComponentOp | DataSourceOp;
+```
+
+_Source: src/operators.ts_
+
+### JsonRendererProvider
+
+**Kind:** `function`
+
+Провайдер настроек для {@link JsonFormRenderer}. Прокидывает реестр и
+fieldWrapper во вложенные компоненты через React Context.
+
+Поддерживает вложенность: внутренний провайдер сливается с внешним
+(внешний имеет приоритет в случае дублей имён в реестре).
+
+**Signature:**
+```typescript
+export function JsonRendererProvider({ settings, children }: JsonRendererProviderProps): ReactNode
+```
+
+**Examples:**
+
+M1: реестр + модель через settings
+```tsx
+// Модель — источник истины (M1); листья схемы биндятся к её сигналам.
+const model = useMemo(() => createModel<MyForm>({ email: '' }), []);
+const registry = useMemo(() => defineRegistry((reg) => {
+reg.component('Input', Input);
+reg.component(FIELD_WRAPPER, FormField);
+}), []);
+
+<JsonRendererProvider settings={{ registry, model }}>
+<JsonFormRenderer<MyForm> schema={schema} />
+</JsonRendererProvider>
+```
+
+_Source: src/context/json-renderer-context.tsx_
+
+### JsonRendererProviderProps
+
+**Kind:** `interface`
+
+Props {@link JsonRendererProvider}.
+
+**Signature:**
+```typescript
+export interface JsonRendererProviderProps {
+  /** Настройки рендерера, как минимум содержащие `registry`. */
+  settings: JsonRendererSettings;
+  /** Дочернее поддерево, в котором доступен `JsonFormRenderer` и `useJsonRendererSettings`. */
+  children: ReactNode;
+}
+```
+
+_Source: src/context/json-renderer-context.tsx_
+
+### JsonRendererSettings
+
+**Kind:** `interface`
+
+Расширенные настройки рендерера: всё из `RendererSettings` плюс реестр.
+
+**Signature:**
+```typescript
+export interface JsonRendererSettings extends RendererSettings {
+  /** Реестр компонентов и source-значений. См. {@link defineRegistry}. */
+  registry?: ComponentRegistry;
+  /**
+   * Модель данных (M1, единая схема). Если задана — JSON-листья биндятся к сигналам модели
+   * (`model.signalAt(selector)`), а форма строится из той же JSON-схемы (без отдельной схемы формы).
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  model?: FormModel<any>;
+}
+```
+
+_Source: src/context/json-renderer-context.tsx_
+
+### ModelOp
+
+**Kind:** `type`
+
+Строка-оператор привязки к полю/массиву модели: `` `$model(${path})` ``.
+
+**Signature:**
+```typescript
+export type ModelOp = `$model(${string})`;
+```
+
+_Source: src/operators.ts_
+
+### ParsedOperator
+
+**Kind:** `interface`
+
+Разобранный оператор: тип + аргумент (путь/имя).
+
+**Signature:**
+```typescript
+export interface ParsedOperator {
+  op: 'model' | 'component' | 'dataSource';
+  arg: string;
+}
+```
+
+_Source: src/operators.ts_
+
+### parseOperator
+
+**Kind:** `function`
+
+Разбор строки-оператора `"$op(arg)"`. Возвращает `null` для не-операторов (обычных строк),
+чтобы вызывающий оставил значение как есть.
+
+**Signature:**
+```typescript
+export function parseOperator(value: unknown): ParsedOperator | null
+```
+
+**Parameters:**
+- `value` — - Проверяемое значение (не-строки сразу дают `null`).
+
+**Returns:** 
+
+**Examples:**
+
+```ts
+parseOperator('$model(loanType)');   // { op: 'model', arg: 'loanType' }
+parseOperator('$dataSource(LOAN_TYPES)'); // { op: 'dataSource', arg: 'LOAN_TYPES' }
+parseOperator('Введите сумму');       // null  (обычная строка)
+```
+
+_Source: src/operators.ts_
+
+### RegistryBuilder
+
+**Kind:** `interface`
+
+Builder, который попадает в callback {@link defineRegistry}.
+
+**Signature:**
+```typescript
+export interface RegistryBuilder {
+  /**
+   * Зарегистрировать React-компонент под именем — доступен в схеме как
+   * `$component(name)`. Одним методом регистрируются и компоненты-листья
+   * (Input/Select), и контейнеры (Box/Section/FormField): роль узла (лист vs
+   * контейнер) определяется структурой узла схемы (`value` vs `children`),
+   * а не регистрацией.
+   */
+  component<P>(name: string, component: ComponentType<P>, description?: string): void;
+  dataSource<T>(name: string, value: T, description?: string): void;
+}
+```
+
+**Examples:**
+
+```typescript
+defineRegistry((reg: RegistryBuilder) => {
+  reg.component('Input', Input);
+  reg.component('Box', Box);
+  reg.dataSource('LOAN_TYPES', LOAN_TYPES);
+});
+```
+
+_Source: src/registry/types.ts_
+
+### SchemaErrorPanel
+
+**Kind:** `function`
+
+Список ошибок схемы (path + message), с пометкой источника. Без внешних UI-зависимостей
+(инлайн-стили), помечен `role="alert"` и `data-testid="schema-error-panel"`.
+
+Обычно рендерится автоматически внутри {@link JsonFormRenderer} (при `validate` и невалидной
+схеме). Можно использовать напрямую для показа результата `validateFormSchema().errors`.
+
+**Signature:**
+```typescript
+export function SchemaErrorPanel({ errors }: SchemaErrorPanelProps): ReactNode
+```
+
+**Parameters:**
+- `props` — - {@link SchemaErrorPanelProps} (массив `errors`).
+
+**Returns:** Панель со списком ошибок.
+
+**Examples:**
+
+Показать ошибки валидации схемы вручную
+```tsx
+import { validateFormSchema } from '@reformer/renderer-json/validate';
+
+const { valid, errors } = validateFormSchema(schema, { registry });
+if (!valid) return <SchemaErrorPanel errors={errors} />;
+```
+
+_Source: src/components/schema-error-panel.tsx_
+
+### SchemaErrorPanelProps
+
+**Kind:** `interface`
+
+Props of {@link SchemaErrorPanel}.
+
+**Signature:**
+```typescript
+export interface SchemaErrorPanelProps {
+  /** Человекочитаемые ошибки (`validateFormSchema().errors`). */
+  errors: string[];
+}
+```
+
+_Source: src/components/schema-error-panel.tsx_
+
+### useJsonRendererSettings
+
+**Kind:** `function`
+
+Хук для чтения текущих настроек {@link JsonRendererProvider}.
+
+В режиме разработки бросает исключение, если вызван вне провайдера или
+если в провайдере не передан `registry`.
+
+**Signature:**
+```typescript
+export function useJsonRendererSettings(): JsonRendererSettings
+```
+
+**Returns:** Текущие {@link JsonRendererSettings}.
+
+**Examples:**
+
+```tsx
+function MyControl() {
+  const { registry } = useJsonRendererSettings();
+  return <span>{registry?.has('Input') ? 'ready' : 'not registered'}</span>;
+}
+```
+
+_Source: src/context/json-renderer-context.tsx_