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

package/dist/model/model-nodes.d.ts

@@ -1,8 +1,70 @@
 import { Signal } from '@preact/signals-core';
 import { PathAwareSignal } from './types';
 export declare const isIndexKey: (key: string) => boolean;
-export type ModelNode = LeafNode | GroupNode | ArrayNode;
-declare class LeafNode {
+/**
+ * Глубокое сравнение значений модели: объекты и массивы — по содержимому, даты — по времени,
+ * `NaN` равен себе, остальное (включая файлы) — по ссылке.
+ *
+ * То же сравнение стоит за `isDirty` модели и за сверкой «модель изменилась, пока шла проверка»
+ * при отправке и переходе шага: значение, изменённое и возвращённое, изменением не считается.
+ *
+ * @example
+ * ```typescript
+ * deepEqual({ date: new Date(0), tags: ['a'] }, { date: new Date(0), tags: ['a'] }); // true
+ * ```
+ */
+export declare const deepEqual: (a: unknown, b: unknown) => boolean;
+/** Фабрика нового элемента массива. */
+type Blank = () => unknown;
+/**
+ * Образец того же места модели внутри шаблона родительского массива. Ленивый: шаблон родителя
+ * ради него вызывается, только когда образец действительно понадобился.
+ */
+type Shape = () => unknown;
+/**
+ * Массив модели с шаблоном нового элемента.
+ *
+ * Шаблон — фабрика значения, которое получает `push()` / `insertAt(i)` без аргумента: кнопка
+ * «Добавить» секции массива, `model.items.push()` в поведении. Частичное значение
+ * (`push({ type: 'house' })`) дополняется из шаблона. Объявляется там же, где остальные
+ * начальные значения, — в модели; схеме и JSX знать его не нужно.
+ *
+ * Возвращает обычный массив: тип поля остаётся `U[]`. Шаблон переживает `set` / `patch` / `reset`
+ * модели. Вложенные массивы объявляются внутри шаблона элемента — тогда и элементы, пришедшие
+ * обычными данными (загрузка с сервера), получают их шаблоны.
+ *
+ * Шаблон привязан к самому массиву, поэтому до `createModel` его нельзя копировать:
+ * `structuredClone`, `JSON.parse(JSON.stringify(…))` и `[...array]` отдают массив без шаблона, и
+ * `push()` без значения бросит ошибку. Начальные значения с `arrayOf` держат в фабрике
+ * (`const initial = () => ({ items: arrayOf(blank) })`), а не в константе, которую клонируют.
+ *
+ * @typeParam U - Тип элемента массива.
+ * @param blank - Фабрика нового элемента. Вызывается на каждое добавление — значение не делится
+ *   между элементами.
+ * @param items - Начальные элементы. По умолчанию массив пуст.
+ * @returns Массив начальных значений с шаблоном.
+ *
+ * @example
+ * ```typescript
+ * const blankPhone = () => ({ number: '' });
+ * const blankCoBorrower = () => ({ name: '', phones: arrayOf(blankPhone) });
+ *
+ * const model = createModel({ coBorrowers: arrayOf(blankCoBorrower) });
+ *
+ * model.coBorrowers.push(); // { name: '', phones: [] }
+ * model.coBorrowers.at(0).phones.push(); // { number: '' }
+ * model.coBorrowers.push({ name: 'Анна' }); // { name: 'Анна', phones: [] } — остальное из шаблона
+ * ```
+ *
+ * @group Model
+ */
+export declare function arrayOf<U>(blank: () => U, items?: readonly U[]): U[];
+export type ModelNode = ModelLeafNode | ModelGroupNode | ModelArrayNode;
+/** Лист модели, чей это сигнал; `undefined` — сигнал не из модели. @internal */
+export declare function leafOfSignal(handle: object): {
+    reference(): unknown;
+} | undefined;
+declare class ModelLeafNode {
     path: string;
     readonly kind: "leaf";
     readonly signal: PathAwareSignal<unknown>;
@@ -14,34 +76,93 @@ declare class LeafNode {
     /** Нереактивный снимок. */
     peek(): unknown;
     set(value: unknown): void;
+    /**
+     * Вернуть значение к снимку. Производное поле (цель `compute`, поле сервера с `markDerived`)
+     * сброс не пишет — как `set` и `patch`: значением владеет поведение, а снимок такого поля снят
+     * до первого расчёта, и `compute` пересчитал бы его только при смене источников.
+     */
     resetToInitial(): void;
     captureInitial(): void;
+    /** Значение точки отсчёта — копия: правка полученного снимок не трогает. */
+    reference(): unknown;
     dirty(): boolean;
+    /**
+     * Отличается ли значение от снимка. Производное поле отличием не считается: его пишет поведение,
+     * а не пользователь — иначе форма без единой правки была бы «изменённой».
+     */
+    differsFrom(snapshot: unknown): boolean;
 }
-export declare class GroupNode {
+export declare class ModelGroupNode {
     path: string;
     readonly kind: "group";
     readonly children: Map<string, ModelNode>;
-    constructor(initial: Record<string, unknown>, path: string);
+    /**
+     * @param shape Образец той же группы из шаблона родительского массива: из него вложенные
+     *   массивы берут шаблоны, если значение пришло обычными данными (см. {@link ModelArrayNode}).
+     */
+    constructor(initial: Record<string, unknown>, path: string, shape?: Shape);
     rebase(path: string): void;
     /** Реактивное чтение поддерева (внутри effect/computed подписывает на все листья группы). */
     read(): Record<string, unknown>;
     peek(): Record<string, unknown>;
+    /**
+     * Полная установка: значение ожидается целиком. Ключи, которых в нём нет, остаются прежними —
+     * как у {@link patch}, — но в dev о них сообщает предупреждение: неполный объект в `set` — почти
+     * всегда ошибка вызывающего кода, а не намерение.
+     */
     set(value: unknown): void;
+    /**
+     * Частичное обновление: записываются только переданные ключи. Вложенная группа сливается так
+     * же, массив заменяется целиком.
+     */
+    patch(value: unknown): void;
+    /**
+     * Запись значения по ключам группы. Лишние ключи значения игнорируются, производные поля не
+     * затираются.
+     *
+     * @param missing - Куда складывать пути ключей, для которых значение не пришло. Передаётся при
+     *   полной установке ({@link set}); при частичной ({@link patch}) — `undefined`.
+     * @param partial - Частичное обновление: ключ со значением `undefined` — «не трогать», как в
+     *   частичном значении элемента массива (`DeepPartial` допускает `{ ключ: undefined }`).
+     */
+    private write;
     resetToInitial(): void;
     captureInitial(): void;
     dirty(): boolean;
+    /** Отличается ли группа от снимка её значения (строка массива сверяется со снимком массива). */
+    differsFrom(snapshot: unknown): boolean;
 }
-export declare class ArrayNode {
+export declare class ModelArrayNode {
     path: string;
+    private readonly shape?;
     readonly kind: "array";
     readonly items: Signal<ModelNode[]>;
     private initial;
-    constructor(initial: unknown[], path: string);
+    private blank;
+    private fallback;
+    private sample;
+    /** @param shape Образец того же массива из шаблона родителя (см. {@link ModelGroupNode}). */
+    constructor(initial: unknown[], path: string, shape?: Shape | undefined);
+    /** Шаблон по старшинству: свой (`arrayOf`) → из шаблона родителя → запасной извне. */
+    private template;
+    private readonly itemShape;
+    private build;
+    /**
+     * Значение нового элемента: из шаблона; переданный объект накладывается поверх шаблона —
+     * недостающие ключи берутся из шаблона, поэтому `push({ type: 'house' })` даёт полный элемент.
+     */
+    private fresh;
+    /** Запасной шаблон извне (сборка формы передаёт `initialValue`): шаблон модели главнее. */
+    provideBlank(blank: Blank): void;
     rebase(path: string): void;
     private reindex;
-    push(value: unknown): void;
-    insertAt(index: number, value: unknown): void;
+    /**
+     * Индекс за концом массива — ошибка, а не «в конец»: `splice` молча сдвигал бы элемент на
+     * другой индекс, и вызывающий код получал бы путь, которого не просил.
+     */
+    private beyondEnd;
+    push(value?: unknown): void;
+    insertAt(index: number, value?: unknown): void;
     removeAt(index: number): void;
     move(from: number, to: number): void;
     swap(a: number, b: number): void;
@@ -55,6 +176,15 @@ export declare class ArrayNode {
     set(value: unknown): void;
     resetToInitial(): void;
     captureInitial(): void;
+    /** Элементы точки отсчёта — копия: правка полученного снимок не трогает. */
+    reference(): unknown[];
     dirty(): boolean;
+    /**
+     * Отличается ли массив от снимка: другая длина либо отличается элемент. Сверка идёт по узлам, а
+     * не по значению целиком — производные поля строк (цели `compute` поведения строки) не в счёт.
+     */
+    differsFrom(snapshot: unknown): boolean;
 }
+/** Начальное значение элемента как шаблон: фабрика — как есть, значение — копией. */
+export declare const blankFrom: (initialValue: unknown) => Blank;
 export {};

package/dist/model/model-signals-proxy.d.ts

@@ -1,6 +1,6 @@
 import { Signal } from '@preact/signals-core';
 import { PathAwareSignal } from './types';
-import { ModelNode, GroupNode } from './model-nodes';
+import { ModelNode, ModelGroupNode, ModelArrayNode } from './model-nodes';
 /**
  * Узел дерева `$`: лист → сам {@link PathAwareSignal}, группа/массив → контейнерный узел —
  * {@link ReadonlySignal} агрегированного значения ПЛЮС доступ к детям по имени/индексу.
@@ -20,6 +20,13 @@ import { ModelNode, GroupNode } from './model-nodes';
  * полей, а потребители, перечисляющие модель, не видят служебных ключей.
  */
 export declare function signalsProxy(node: ModelNode): any;
+/**
+ * Узел модели за контейнерной ручкой дерева `$` (группа или массив). Для листа и для всего, что
+ * ручкой не является, — `undefined`.
+ *
+ * @internal
+ */
+export declare function containerNodeOf(handle: unknown): ModelGroupNode | ModelArrayNode | undefined;
 /**
  * Узел дерева `model.$` — контейнер (группа/массив), а не лист?
  *
@@ -37,12 +44,11 @@ export declare function isModelContainerSignal(value: unknown): boolean;
 /** Узел-массив дерева `model.$` — ручка значения массива целиком. */
 export declare function isModelArraySignal(value: unknown): boolean;
 /**
- * «Ручка значения», к которой можно привязать поле: лист (`instanceof Signal`) либо узел-массив
+ * «Ручка значения», к которой можно привязать поле: лист (сигнал, не контейнер) либо узел-массив
  * дерева `model.$` (значение — массив целиком, `.value` читается и пишется).
  *
  * Группа сюда не входит: она читается целиком, но не пишется и полем не бывает. Этой проверкой
- * `createForm` и рендереры отличают узел-поле схемы (`{ value, component }`) от контейнера —
- * вместо голого `value instanceof Signal`, который узел-массив не проходит.
+ * `createForm` и рендереры отличают узел-поле схемы (`{ model, component }`) от контейнера.
  *
  * @group Model
  * @example
@@ -54,4 +60,4 @@ export declare function isModelArraySignal(value: unknown): boolean;
  * ```
  */
 export declare function isValueSignal(value: unknown): value is Signal<unknown>;
-export declare function resolveSignalAt(root: GroupNode, path: string): PathAwareSignal<unknown> | undefined;
+export declare function resolveSignalAt(root: ModelGroupNode, path: string): PathAwareSignal<unknown> | undefined;

package/dist/model/model-value-proxy.d.ts

@@ -1,3 +1,84 @@
-import { GroupNode } from './model-nodes';
-export declare const rootByFacade: WeakMap<object, GroupNode>;
-export declare function makeFormModel(group: GroupNode): any;
+import { ModelGroupNode } from './model-nodes';
+import { FormModel, ModelArray } from './types';
+export declare const rootByFacade: WeakMap<object, ModelGroupNode>;
+export declare function makeFormModel(group: ModelGroupNode): any;
+/**
+ * Value-фасад для ручки {@link modelOf}: массив → {@link ModelArray}, объект → под-модель
+ * {@link FormModel}.
+ *
+ * @group Model
+ */
+export type ModelOf<V> = NonNullable<V> extends ReadonlyArray<infer U> ? ModelArray<U> : FormModel<NonNullable<V>>;
+/**
+ * Value-фасад по ручке дерева `model.$`: группа → под-модель {@link FormModel}, массив →
+ * {@link ModelArray}. Обратная операция к `model.$`: `modelOf(model.$.address) === model.address`.
+ *
+ * Ручка находит фасад по ИДЕНТИЧНОСТИ, а не по пути. Путь для этого не годится: он абсолютный
+ * (`items.0.phones`) и меняется при перестановке строк, а области поведения и формы строк
+ * вложенные — поиск по пути от под-модели строки ничего не находит.
+ *
+ * Лист ручкой контейнера не является — функция бросает. В частности, группа или массив,
+ * созданные из начального `null`, в модели — лист: вид узла фиксируется при создании.
+ *
+ * @typeParam V - Значение, которое хранит ручка (выводится из `peek()`).
+ * @param handle - Узел-группа или узел-массив дерева `model.$`.
+ * @returns Под-модель группы либо фасад массива.
+ * @throws TypeError если `handle` — лист или не ручка модели.
+ *
+ * @example
+ * ```typescript
+ * const model = createModel({ address: { city: '' }, phones: [{ number: '' }] });
+ *
+ * modelOf(model.$.address).city = 'Казань'; // под-модель: чтение, запись, get/set/patch
+ * modelOf(model.$.phones).push({ number: '+7' }); // фасад массива: мутации и обход
+ * modelOf(model.$.phones[0]).number; // строка массива — тоже группа
+ * ```
+ *
+ * @group Model
+ */
+export declare function modelOf<V extends object | null | undefined>(handle: {
+    peek(): V;
+}): ModelOf<V>;
+/**
+ * Ручка массива по привязке: сама ручка `model.$.<массив>` либо value-фасад `model.<массив>`.
+ * Для всего остального — `undefined`.
+ *
+ * @internal
+ */
+export declare function arrayHandleOf(binding: unknown): object | undefined;
+/**
+ * Ручка группы по привязке: `model.$.<группа>` либо под-модель `model.<группа>`. Для всего
+ * остального — `undefined`.
+ *
+ * @internal
+ */
+export declare function groupHandleOf(binding: unknown): object | undefined;
+/**
+ * Запасной шаблон нового элемента массива — от того, кто строит модель извне: сборка формы
+ * передаёт сюда `initialValue` узла-массива. Действует, только если модель своего шаблона не
+ * объявила (`arrayOf`): так живут формы, чья модель строится из данных без кода. Что это узел
+ * схемы, модель не знает.
+ *
+ * @internal
+ */
+export declare function provideArrayBlank(handle: unknown, initialValue: unknown): void;
+/**
+ * Value-фасад модели (под-модель или фасад массива), а не обычный объект?
+ *
+ * Обходчикам чужих деревьев, в которых могут лежать фасады модели, в фасад спускаться нельзя:
+ * чтение его ключей — это реактивное чтение значений модели.
+ *
+ * @internal
+ */
+/**
+ * Точка отсчёта модели по ручке, к которой привязана нода формы: сигналу листа или фасаду
+ * массива. К ней сброс формы (`form.reset()`) возвращает ноду — к тому же, к чему `model.reset()`
+ * возвращает модель: последний `captureInitial` либо значение создания модели.
+ *
+ * `undefined` — ручка не из модели (нода над собственным сигналом): сбрасывать её не к чему,
+ * кроме значения, с которым она создана. @internal
+ */
+export declare function referenceOf(handle: unknown): {
+    readonly value: unknown;
+} | undefined;
+export declare function isModelFacade(value: unknown): boolean;

package/dist/model/safe-effect.d.ts

@@ -68,6 +68,38 @@ export declare function safeCallback<TArgs extends unknown[]>(callback: (...args
  * ```
  */
 export declare function runOutsideEffect(fn: () => void | Promise<void>): () => void;
+/**
+ * Дождаться, пока отработают отложенные записи текущего тика — вместе с теми, что они породили
+ * (цепочка расчётов: каждая запись будит следующий расчёт, а тот снова пишет отложенно).
+ *
+ * Ждёт только микротаски: запись после таймера (debounce) или после `await` в async-callback сюда не
+ * входит — это уже не «тот же тик».
+ *
+ * Счётчик общий для рантайма, а не для одной модели: отложенные записи ставит {@link runOutsideEffect},
+ * а он моделей не различает. Нужен проверкам «по действию» — отправке и переходу шага: правила должны
+ * увидеть модель после записей поведения того же тика (колбэк `onChange`, сброс `resetOnDisable`).
+ *
+ * @returns Промис ожидания; `undefined` — отложенных записей сейчас нет, ждать нечего.
+ *
+ * @example
+ * ```typescript
+ * model.loanType = 'mortgage'; // поведение допишет зависимые поля на микротаске
+ * await deferredWritesSettled();
+ * const values = model.get(); // уже с записями поведения
+ * ```
+ */
+export declare function deferredWritesSettled(): Promise<void> | undefined;
+/**
+ * Отложенные записи одной операции: задание выполняется на микротаске ({@link runOutsideEffect}),
+ * а `cancelAll` отменяет все ещё не выполненные — при снятии операции (запись после cleanup не
+ * случится) или когда новое задание делает ожидающие устаревшими (побеждает последнее).
+ *
+ * @internal
+ */
+export declare function deferredWrites(): {
+    schedule(job: () => void): void;
+    cancelAll(): void;
+};
 /**
  * Создает версию callback с поддержкой debounce, безопасную для effect
  *
@@ -76,7 +108,7 @@ export declare function runOutsideEffect(fn: () => void | Promise<void>): () =>
  * async-rejection) маршрутизируются dev-логгером (logDeferError).
  *
  * @param callback - Функция для выполнения
- * @param withDebounce - Функция debounce обёртки из BehaviorRegistry
+ * @param withDebounce - Обёртка, откладывающая вызов (debounce)
  * @returns Обёрнутая функция
  *
  * @example

package/dist/model/types.d.ts

@@ -14,6 +14,33 @@ export type PathAwareSignal<T> = Signal<T> & {
  * @internal
  */
 type Opaque = Date | File | Blob;
+/**
+ * Значение одного ключа в {@link DeepPartial}: вложенная группа — частично, массив и спец-объект
+ * (Date/File/Blob) — целиком.
+ * @internal
+ */
+type DeepPartialValue<V> = NonNullable<V> extends ReadonlyArray<unknown> | Opaque ? V : NonNullable<V> extends object ? DeepPartial<NonNullable<V>> | Extract<V, null | undefined> : V;
+/**
+ * Частичное значение модели для {@link ModelApi.patch}: любой ключ можно опустить на любой
+ * глубине вложенных групп. Массив передаётся целиком — он заменяется, а не сливается.
+ *
+ * @example
+ * ```typescript
+ * type Profile = { name: string; address: { city: string; street: string }; tags: string[] };
+ * const update: DeepPartial<Profile> = { address: { city: 'Казань' } };
+ * ```
+ *
+ * @group Model
+ */
+export type DeepPartial<T> = {
+    [K in keyof T]?: DeepPartialValue<T[K]>;
+};
+/**
+ * `null` входит в тип `V`. Без `strictNullChecks` у потребителя `null` подходит любому типу —
+ * тогда признак ложен, и тип контейнера остаётся фасадом, как без `null`.
+ * @internal
+ */
+type IncludesNull<V> = null extends string ? false : null extends V ? true : false;
 /**
  * Фасад элемента массива при обходе (`at`/`map`/`forEach`): массив → {@link ModelArray},
  * Opaque (Date/File/Blob) и примитив → значение, объект → под-модель {@link FormModel}.
@@ -21,7 +48,7 @@ type Opaque = Date | File | Blob;
  * чтобы `files: File[]`/`dates: Date[]`/вложенные массивы не мис-типизировались как `FormModel`.
  * @internal
  */
-type ModelArrayItem<U> = NonNullable<U> extends ReadonlyArray<infer E> ? ModelArray<E> : NonNullable<U> extends Opaque ? U : NonNullable<U> extends object ? FormModel<NonNullable<U>> : U;
+type ModelArrayItem<U> = IncludesNull<U> extends true ? U : NonNullable<U> extends ReadonlyArray<infer E> ? ModelArray<E> : NonNullable<U> extends Opaque ? U : NonNullable<U> extends object ? FormModel<NonNullable<U>> : U;
 /**
  * Значение поля в value-доступе модели:
  * - массив → {@link ModelArray}
@@ -29,10 +56,13 @@ type ModelArrayItem<U> = NonNullable<U> extends ReadonlyArray<infer E> ? ModelAr
  * - объект → под-модель {@link FormModel} (value-доступ + `.$`-сигналы + API get/set/patch/…);
  *   промоутится рантаймом (`makeFormModel`); сигналы идентичны `model.$.<path>`
  * - примитив → значение
+ * - тип с `null` (`File[] | null`, `Address | null`) → значение как есть, без фасада: поле,
+ *   которое бывает `null`, начинают с `null`, а такое поле в рантайме — лист (значение целиком).
+ *   Контейнер, созданный из `[]` или `{}`, стал бы фасадом — nullable-контейнер начинают с `null`.
  *
  * @group Model
  */
-export type ModelValue<V> = NonNullable<V> extends ReadonlyArray<infer U> ? ModelArray<U> : NonNullable<V> extends Opaque ? V : NonNullable<V> extends object ? FormModel<NonNullable<V>> : V;
+export type ModelValue<V> = IncludesNull<V> extends true ? V : NonNullable<V> extends ReadonlyArray<infer U> ? ModelArray<U> : NonNullable<V> extends Opaque ? V : NonNullable<V> extends object ? FormModel<NonNullable<V>> : V;
 /**
  * Карта value-полей объекта (value-половина {@link FormModel}): поля доступны как обычные свойства
  * (чтение реактивно внутри `effect`/`computed`, запись — присваиванием). Вложенные объекты-поля
@@ -57,10 +87,13 @@ export interface ModelArray<U> {
     readonly __path: string;
     /** Реактивная длина. */
     readonly length: number;
-    /** Добавить элемент в конец (значение элемента целиком). */
-    push(item: U): void;
-    /** Вставить элемент по индексу. */
-    insertAt(index: number, item: U): void;
+    /**
+     * Добавить элемент в конец (значение элемента целиком). Без значения — элемент по шаблону
+     * массива (`arrayOf(blank)` в модели); шаблона нет — ошибка.
+     */
+    push(item?: U): void;
+    /** Вставить элемент по индексу. Без значения — элемент по шаблону, как у {@link push}. */
+    insertAt(index: number, item?: U): void;
     /** Удалить элемент по индексу. */
     removeAt(index: number): void;
     /** Переместить элемент. */
@@ -77,6 +110,8 @@ export interface ModelArray<U> {
     forEach(fn: (item: ModelArrayItem<U>, index: number) => void): void;
     /** Снимок массива значений (без подписки). */
     toArray(): U[];
+    /** Обход `for…of` / spread — те же элементы, что у {@link forEach}. */
+    [Symbol.iterator](): IterableIterator<ModelArrayItem<U>>;
     /** Индексный value-доступ. */
     [index: number]: ModelValue<U>;
 }
@@ -112,13 +147,13 @@ export type ModelGroupSignals<T> = ModelSignals<T> & ContainerSignal<T, keyof T>
  * push/removeAt/move).
  *
  * В отличие от группы, узел ЗАПИСЫВАЕМ: `model.$.tags.value = ['a']` заменяет массив целиком. Это
- * делает его {@link PathAwareSignal} — к нему привязывают поле (`{ value: model.$.tags, component }`),
+ * делает его {@link PathAwareSignal} — к нему привязывают поле (`{ model: model.$.tags, component }`),
  * правило (`validate(model.$.tags, …)`) и поведение, как к листу. Так массив служит ОДНИМ значением
  * поля: мультивыбор, теги, список файлов.
  *
- * `V` — объявленный тип поля, включая `null`/`undefined`: поле `string[] | null` с начальным `null`
- * в рантайме — лист с тем же `.value`/`peek`/`subscribe`, поэтому общая часть честна для обоих
- * случаев. `length` и индексы есть только у настоящего узла-массива (начальное значение — массив).
+ * `V` — объявленный тип поля, включая `undefined`. Поле с `null` в типе (`string[] | null`) — не
+ * узел-массив, а лист {@link PathAwareSignal}: его начинают с `null`, и `length` с индексами у него
+ * в рантайме нет (см. {@link ModelValue}).
  *
  * @group Model
  */
@@ -132,10 +167,11 @@ export type ModelArraySignals<U, V> = Signal<V> & {
  * Узел дерева сигналов `model.$`: массив → {@link ModelArraySignals}, Opaque (Date/File/Blob)
  * и примитив → {@link PathAwareSignal}, объект → {@link ModelGroupSignals}. Для примитивных
  * и Opaque массивов элемент — сам сигнал листа (а не под-дерево), поэтому `model.$.tags[0]` — это
- * `PathAwareSignal<string>`, а не `ModelGroupSignals<never>`.
+ * `PathAwareSignal<string>`, а не `ModelGroupSignals<never>`. Тип с `null` — лист
+ * {@link PathAwareSignal}: такое поле начинают с `null`, и под-сигналов у него нет.
  * @internal
  */
-type ModelSignalNode<V> = NonNullable<V> extends ReadonlyArray<infer U> ? ModelArraySignals<U, V> : NonNullable<V> extends Opaque ? PathAwareSignal<V> : NonNullable<V> extends object ? ModelGroupSignals<NonNullable<V>> : PathAwareSignal<V>;
+type ModelSignalNode<V> = IncludesNull<V> extends true ? PathAwareSignal<V> : NonNullable<V> extends ReadonlyArray<infer U> ? ModelArraySignals<U, V> : NonNullable<V> extends Opaque ? PathAwareSignal<V> : NonNullable<V> extends object ? ModelGroupSignals<NonNullable<V>> : PathAwareSignal<V>;
 /**
  * API уровня модели (доступно на корне, под-моделях вложенных объектов-групп и элементов массива).
  *
@@ -156,18 +192,35 @@ export interface ModelApi<T> {
      * Полная установка значений: принимает объект целиком (все ключи `T`) и записывает их в модель.
      * Производными полями (цели `compute`) владеет compute — их значения из payload игнорируются.
      * Не меняет initial-снимок. Для частичного обновления (только переданные ключи) — {@link ModelApi.patch}.
+     *
+     * Если в объекте не хватает ключей (значение пришло без типа — например, с сервера), эти поля
+     * остаются прежними, а в dev выводится предупреждение со списком.
      */
     set(value: T): void;
     /**
      * Частичное слияние значений (load/patch с сервера): обновляет только переданные ключи,
-     * отсутствующие ключи НЕ трогаются. Не меняет initial-снимок.
+     * отсутствующие ключи НЕ трогаются. Вложенные группы сливаются так же, массив заменяется
+     * целиком. Не меняет initial-снимок.
+     */
+    patch(value: DeepPartial<T>): void;
+    /**
+     * Отличаются ли текущие значения от initial-снимка (value-diff). Производные поля — цели
+     * `compute` / `computeFrom` и поля с `markDerived` — не в счёт: их пишет поведение, а не
+     * пользователь, и форма без единой правки изменённой не считается.
      */
-    patch(value: Partial<T>): void;
-    /** Отличаются ли текущие значения от initial-снимка (value-diff). */
     isDirty(): boolean;
-    /** Сбросить значения к initial-снимку. */
+    /**
+     * Сбросить значения к initial-снимку. Производные поля сброс не пишет, как `set` и `patch`:
+     * цель `compute` пересчитает поведение, когда вернутся её источники.
+     *
+     * Ноды формы не трогает: замечания погаснут при следующей проверке. Сброс для пользователя —
+     * `form.reset()`: та же точка отсчёта и чистые ноды.
+     */
     reset(): void;
-    /** Зафиксировать текущие значения как новый initial-снимок («точка отсчёта»). */
+    /**
+     * Зафиксировать текущие значения как новый initial-снимок («точка отсчёта»). К нему возвращают
+     * и `model.reset()`, и `form.reset()`.
+     */
     captureInitial(): void;
     /**
      * Резолв строкового пути в сигнал (для error-routing/мостов): лист либо массив целиком

package/dist/model.js

@@ -1,23 +1,27 @@
-import { c as s, e as r, a as i } from "./create-model-B8U-COv-.js";
-import { b as o, i as c, a as n, m as t, u as d } from "./model-signals-proxy-2vqS243J.js";
-import { c as m, a as u, r as b, b as h, d as p, e as g, f as k, s as v, t as D, w as F } from "./behaviors-value-C7dSEhCc.js";
+import { c as s, e as r, a as l } from "./create-model-BvcbNPgL.js";
+import { a as d, g as o, f as t, d as c, i as f, b as n, c as m, m as u, r as p, s as b, e as g, u as h } from "./safe-effect-BbtX3KuN.js";
+import { c as k, a as v, r as D, b as F, s as x, t as y, w as C } from "./behaviors-value-HA_Q03hc.js";
 export {
-  m as computeFrom,
-  u as copyFrom,
+  d as arrayOf,
+  k as computeFrom,
+  v as copyFrom,
   s as createModel,
+  o as deepEqual,
+  t as deferredWritesSettled,
   r as eachLeafSignal,
-  i as eachValueSignal,
-  o as isDerived,
-  c as isModelContainerSignal,
+  l as eachValueSignal,
+  c as isDerived,
+  f as isModelContainerSignal,
   n as isValueSignal,
-  t as markDerived,
-  b as resetWhen,
-  h as revalidateWhen,
+  m as markDerived,
+  u as modelOf,
+  D as resetWhen,
+  F as revalidateWhen,
   p as runOutsideEffect,
-  g as safeCallback,
-  k as safeDebouncedCallback,
-  v as syncFields,
-  D as transformValue,
-  d as unmarkDerived,
-  F as watchField
+  b as safeCallback,
+  g as safeDebouncedCallback,
+  x as syncFields,
+  y as transformValue,
+  h as unmarkDerived,
+  C as watchField
 };

package/dist/node-kind-C-r6ZMdo.js

@@ -0,0 +1,15 @@
+const n = Symbol.for("@reformer/core/form-node-kind"), e = Symbol.for("@reformer/core/form-node-raw");
+function t(r) {
+  if (typeof r != "object" || r === null) return;
+  const o = r[n];
+  return o === "control" || o === "group" || o === "array" ? o : void 0;
+}
+function f(r) {
+  return r[e] ?? r;
+}
+export {
+  n as N,
+  e as R,
+  t as k,
+  f as r
+};

package/dist/platforms/react/field-binding/field-adapter.d.ts

@@ -41,7 +41,7 @@ export interface FieldAdapter {
     strip?: string[];
     /**
      * Передавать ли контролу ноду формы пропом `control` (только рендерер). По умолчанию `false`:
-     * errors/touched обслуживает обёртка поля. Ставь `true`, если контрол сам вызывает
+     * issues/touched обслуживает обёртка поля. Ставь `true`, если контрол сам вызывает
      * `useFormControl(control)`.
      */
     passControl?: boolean;

package/dist/platforms/react/field-binding/field-handle.d.ts

@@ -43,8 +43,11 @@ export declare function makeElementFieldHandle(el: RefObject<HTMLElement | null>
 export declare function useFieldHandleRef<H = FieldHandle>(outerRef: Ref<H> | undefined): RefObject<unknown>;
 /**
  * Что публиковать потребителю по ref контрола: handle композита как есть, иначе (DOM-узел или
- * ещё пусто) — базовый {@link FieldHandle}, читающий узел лениво из `inner`.
+ * ещё пусто) — базовый {@link FieldHandle}, читающий узел лениво из `inner`. С `cache` базовый
+ * handle создаётся один раз и дальше переиспользуется.
  *
  * @internal Экспортируется для юнит-тестов.
  */
-export declare function resolveFieldHandle(inner: RefObject<unknown>): unknown;
+export declare function resolveFieldHandle(inner: RefObject<unknown>, cache?: {
+    current: FieldHandle | null;
+}): unknown;

package/dist/platforms/react/form-bundle-context.d.ts

@@ -0,0 +1,27 @@
+import { FormBundle } from '../../form/form-bundle';
+/**
+ * Контекст сборки. Значение — бандл `createForm`; вне рендерера — `null`.
+ *
+ * @example
+ * ```tsx
+ * <FormBundleContext.Provider value={bundle}>
+ *   <MyWizard />
+ * </FormBundleContext.Provider>
+ * ```
+ */
+export declare const FormBundleContext: import('react').Context<FormBundle<any> | null>;
+/**
+ * Бандл сборки, внутри которой отрисован компонент; `null` — компонент стоит вне рендерера
+ * (например, визард в разметке React-руками получает форму и поток шагов пропсами).
+ *
+ * @typeParam T - Форма данных модели.
+ *
+ * @example
+ * ```tsx
+ * function StepFooter() {
+ *   const bundle = useFormBundleContext<CreditForm>();
+ *   return <button onClick={() => void bundle?.validate()}>Проверить</button>;
+ * }
+ * ```
+ */
+export declare function useFormBundleContext<T = unknown>(): FormBundle<T> | null;