@reformer/core 11.0.0-beta.1 → 11.0.0-beta.10

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

@@ -0,0 +1,190 @@
+import { Signal } from '@preact/signals-core';
+import { PathAwareSignal } from './types';
+export declare const isIndexKey: (key: string) => boolean;
+/**
+ * Глубокое сравнение значений модели: объекты и массивы — по содержимому, даты — по времени,
+ * `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>;
+    private initial;
+    constructor(initial: unknown, path: string);
+    rebase(path: string): void;
+    /** Реактивное чтение (внутри effect/computed создаёт зависимость). */
+    read(): unknown;
+    /** Нереактивный снимок. */
+    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 ModelGroupNode {
+    path: string;
+    readonly kind: "group";
+    readonly children: Map<string, ModelNode>;
+    /**
+     * @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 ModelArrayNode {
+    path: string;
+    private readonly shape?;
+    readonly kind: "array";
+    readonly items: Signal<ModelNode[]>;
+    private initial;
+    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;
+    /**
+     * Индекс за концом массива — ошибка, а не «в конец»: `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;
+    clear(): void;
+    /**
+     * Реактивное чтение массива. Читаем `items.value` (а не `.peek()`) — внутри effect/computed это
+     * подписка на СОСТАВ массива, поэтому push/removeAt/move ретригерят наравне с правкой элемента.
+     */
+    read(): unknown[];
+    peek(): unknown[];
+    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

@@ -0,0 +1,63 @@
+import { Signal } from '@preact/signals-core';
+import { PathAwareSignal } from './types';
+import { ModelNode, ModelGroupNode, ModelArrayNode } from './model-nodes';
+/**
+ * Узел дерева `$`: лист → сам {@link PathAwareSignal}, группа/массив → контейнерный узел —
+ * {@link ReadonlySignal} агрегированного значения ПЛЮС доступ к детям по имени/индексу.
+ *
+ * Узел массива вдобавок принимает запись `.value` — замену массива целиком (см. шапку модуля).
+ * Любая другая запись в контейнер — ошибка: свойство, молча осевшее на прокси, выглядело бы как
+ * удачная запись, а модель осталась бы прежней.
+ *
+ * Порядок разрешения ключа: служебные `__path`/`__kind` → ребёнок → свойство сигнала. Дети идут
+ * раньше свойств сигнала — тот же приоритет, что у {@link makeFormModel} (поле формы затеняет метод
+ * API). Поэтому имена `value`/`peek`/`subscribe`/`valueOf`/`toString`/`toJSON`/`brand` де-факто
+ * зарезервированы: одноимённое поле формы затенит свойство сигнала (`subscribe` при этом продолжает
+ * работать — он замкнут на агрегат, а не читает `.value` через прокси).
+ *
+ * `has`/`ownKeys` намеренно НЕ показывают свойства сигнала — ровно как `__path`, доступный через
+ * `get`, но невидимый для `in`/`Object.keys`. Так `Object.keys(model.$.<group>)` остаётся списком
+ * полей, а потребители, перечисляющие модель, не видят служебных ключей.
+ */
+export declare function signalsProxy(node: ModelNode): any;
+/**
+ * Узел модели за контейнерной ручкой дерева `$` (группа или массив). Для листа и для всего, что
+ * ручкой не является, — `undefined`.
+ *
+ * @internal
+ */
+export declare function containerNodeOf(handle: unknown): ModelGroupNode | ModelArrayNode | undefined;
+/**
+ * Узел дерева `model.$` — контейнер (группа/массив), а не лист?
+ *
+ * Контейнерный узел структурно совместим с `ReadonlySignal` (`peek`/`value`/`subscribe`), поэтому
+ * duck-typing «есть `peek` ⇒ это лист» на нём даёт ложное срабатывание. Этот guard — надёжный
+ * способ различить: обходчикам дерева нужно спускаться в контейнер, а не читать его целиком.
+ *
+ * @group Model
+ * @example
+ * ```typescript
+ * const isLeaf = (v: unknown) => isSignalLike(v) && !isModelContainerSignal(v);
+ * ```
+ */
+export declare function isModelContainerSignal(value: unknown): boolean;
+/** Узел-массив дерева `model.$` — ручка значения массива целиком. */
+export declare function isModelArraySignal(value: unknown): boolean;
+/**
+ * «Ручка значения», к которой можно привязать поле: лист (сигнал, не контейнер) либо узел-массив
+ * дерева `model.$` (значение — массив целиком, `.value` читается и пишется).
+ *
+ * Группа сюда не входит: она читается целиком, но не пишется и полем не бывает. Этой проверкой
+ * `createForm` и рендереры отличают узел-поле схемы (`{ model, component }`) от контейнера.
+ *
+ * @group Model
+ * @example
+ * ```typescript
+ * const model = createModel({ name: '', tags: [] as string[], address: { city: '' } });
+ * isValueSignal(model.$.name);    // true — лист
+ * isValueSignal(model.$.tags);    // true — массив как значение
+ * isValueSignal(model.$.address); // false — группа
+ * ```
+ */
+export declare function isValueSignal(value: unknown): value is Signal<unknown>;
+export declare function resolveSignalAt(root: ModelGroupNode, path: string): PathAwareSignal<unknown> | undefined;

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

@@ -0,0 +1,84 @@
+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/{state → model}/safe-effect.d.ts

@@ -19,7 +19,7 @@
  * не здесь. См. также `aggregateInto`, где коалесинг реализован на уровне самого оператора.
  *
  * @group Utils
- * @module utils/safe-effect
+ * @module model/safe-effect
  */
 /**
  * Создает callback, который выполняется вне контекста effect
@@ -68,6 +68,54 @@ export declare function safeCallback<TArgs extends unknown[]>(callback: (...args
  * ```
  */
 export declare function runOutsideEffect(fn: () => void | Promise<void>): () => void;
+/**
+ * Выполнить сборку так, чтобы записи, отложенные ею, выполнились до возврата, — вместе с теми, что
+ * они породили (копия `syncFields`, нормализация `transformValue`, сброс выключенного поля).
+ *
+ * Без этого первые записи поведения приходили бы на микротаске, уже после сборки, и точка отсчёта
+ * модели, снятая в конце сборки, их бы не видела: пара `syncFields` попала бы в неё рассогласованной,
+ * и `form.reset()` вернул бы её не к собранному состоянию, а к полусобранному.
+ *
+ * Записи выполняются вне `batch()` — как на микротаске: встречные эффекты флашатся синхронно (см.
+ * комментарий модуля). Вложенная сборка своих записей не выполняет — это сделает внешняя.
+ *
+ * @param build - Сборка: подключение поведения.
+ * @returns То, что вернула сборка.
+ * @internal
+ */
+export declare function runAssemblyWrites<R>(build: () => R): R;
+/**
+ * Дождаться, пока отработают отложенные записи текущего тика — вместе с теми, что они породили
+ * (цепочка расчётов: каждая запись будит следующий расчёт, а тот снова пишет отложенно).
+ *
+ * Ждёт только микротаски: запись после таймера (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 +124,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

@@ -0,0 +1,239 @@
+import { ReadonlySignal, Signal } from '@preact/signals-core';
+/**
+ * Сигнал, который знает свой путь в модели (`'personalData.lastName'`).
+ * Используется как «ручка поля»: и привязка value в схеме, и идентичность для testId/devtools.
+ *
+ * @group Model
+ */
+export type PathAwareSignal<T> = Signal<T> & {
+    /** Путь поля в модели (dot-нотация). На элементах массива включает индекс. */
+    readonly __path: string;
+};
+/**
+ * Спец-объекты, которые трактуются как листья (не разворачиваются в под-модель).
+ * @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}.
+ * Зеркалит листовой/объектный сплит {@link ModelValue} (но объект → под-модель с API),
+ * чтобы `files: File[]`/`dates: Date[]`/вложенные массивы не мис-типизировались как `FormModel`.
+ * @internal
+ */
+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}
+ * - спец-объект (Date/File/Blob) → как есть
+ * - объект → под-модель {@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> = 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`, запись — присваиванием). Вложенные объекты-поля
+ * резолвятся в под-модели {@link FormModel} (см. {@link ModelValue}), массивы — в {@link ModelArray}.
+ *
+ * @group Model
+ */
+export type ModelObject<T> = {
+    [K in keyof T]: ModelValue<T[K]>;
+};
+/**
+ * Реактивный массив модели. Мутации (`push`/`removeAt`/…) меняют длину реактивно;
+ * `map`/`forEach`/`at` отдают под-модель элемента ({@link FormModel}) для объектных элементов.
+ *
+ * @group Model
+ */
+export interface ModelArray<U> {
+    /**
+     * Путь массива в модели (dot-нотация). Предоставляется рантаймом (value-прокси) и требуется
+     * рендер-слою для резолва узла массива (напр. `ArrayRenderNode` в `@reformer/renderer-react`).
+     */
+    readonly __path: string;
+    /** Реактивная длина. */
+    readonly length: number;
+    /**
+     * Добавить элемент в конец (значение элемента целиком). Без значения — элемент по шаблону
+     * массива (`arrayOf(blank)` в модели); шаблона нет — ошибка.
+     */
+    push(item?: U): void;
+    /** Вставить элемент по индексу. Без значения — элемент по шаблону, как у {@link push}. */
+    insertAt(index: number, item?: U): void;
+    /** Удалить элемент по индексу. */
+    removeAt(index: number): void;
+    /** Переместить элемент. */
+    move(from: number, to: number): void;
+    /** Поменять местами два элемента. */
+    swap(a: number, b: number): void;
+    /** Очистить массив. */
+    clear(): void;
+    /** Элемент по индексу: объект → под-модель, массив → {@link ModelArray}, лист → значение. */
+    at(index: number): NonNullable<U> extends object ? ModelArrayItem<U> : ModelArrayItem<U> | undefined;
+    /** Map по элементам (объект → {@link FormModel}, Opaque/примитив → значение, массив → {@link ModelArray}). */
+    map<R>(fn: (item: ModelArrayItem<U>, index: number) => R): R[];
+    /** Итерация по элементам (см. {@link ModelArrayItem}). */
+    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>;
+}
+/**
+ * Карта под-сигналов объекта в дереве `model.$` (без свойств самого узла — их добавляет
+ * {@link ModelGroupSignals}).
+ *
+ * @group Model
+ */
+export type ModelSignals<T> = {
+    [K in keyof T]: ModelSignalNode<T[K]>;
+};
+/**
+ * Свойства контейнерного узла дерева `$`, «поверх» карты детей. Ключи детей вырезаются из
+ * {@link ReadonlySignal}: доступ к полю формы всегда выигрывает у одноимённого свойства сигнала
+ * (так же ведёт себя рантайм), поэтому `{ value: string }` не порождает конфликта типов.
+ * @internal
+ */
+type ContainerSignal<T, TKeys extends PropertyKey> = Omit<ReadonlySignal<T>, TKeys>;
+/**
+ * Узел-группа дерева `model.$`: доступ к под-сигналам полей ({@link ModelSignals}) И одновременно
+ * {@link ReadonlySignal} агрегированного значения группы — `.value`/`.peek()`/`.subscribe()`.
+ *
+ * ⚠️ Поле формы с именем `value`/`peek`/`subscribe`/`valueOf`/`toString`/`toJSON`/`brand` затеняет
+ * одноимённое свойство сигнала (редкий краевой случай); `subscribe` при этом продолжает работать.
+ *
+ * @group Model
+ */
+export type ModelGroupSignals<T> = ModelSignals<T> & ContainerSignal<T, keyof T>;
+/**
+ * Узел-массив дерева `model.$`: индексируемый доступ к под-сигналам элементов, реактивная `length`
+ * и сигнал значения массива целиком (реагирует и на правку элемента, и на изменение состава —
+ * push/removeAt/move).
+ *
+ * В отличие от группы, узел ЗАПИСЫВАЕМ: `model.$.tags.value = ['a']` заменяет массив целиком. Это
+ * делает его {@link PathAwareSignal} — к нему привязывают поле (`{ model: model.$.tags, component }`),
+ * правило (`validate(model.$.tags, …)`) и поведение, как к листу. Так массив служит ОДНИМ значением
+ * поля: мультивыбор, теги, список файлов.
+ *
+ * `V` — объявленный тип поля, включая `undefined`. Поле с `null` в типе (`string[] | null`) — не
+ * узел-массив, а лист {@link PathAwareSignal}: его начинают с `null`, и `length` с индексами у него
+ * в рантайме нет (см. {@link ModelValue}).
+ *
+ * @group Model
+ */
+export type ModelArraySignals<U, V> = Signal<V> & {
+    /** Путь массива в модели (dot-нотация). */
+    readonly __path: string;
+    readonly length: number;
+    readonly [index: number]: ModelSignalNode<U>;
+};
+/**
+ * Узел дерева сигналов `model.$`: массив → {@link ModelArraySignals}, Opaque (Date/File/Blob)
+ * и примитив → {@link PathAwareSignal}, объект → {@link ModelGroupSignals}. Для примитивных
+ * и Opaque массивов элемент — сам сигнал листа (а не под-дерево), поэтому `model.$.tags[0]` — это
+ * `PathAwareSignal<string>`, а не `ModelGroupSignals<never>`. Тип с `null` — лист
+ * {@link PathAwareSignal}: такое поле начинают с `null`, и под-сигналов у него нет.
+ * @internal
+ */
+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 уровня модели (доступно на корне, под-моделях вложенных объектов-групп и элементов массива).
+ *
+ * ⚠️ Имена методов (`$`/`get`/`set`/`patch`/`isDirty`/`reset`/`signalAt`/`captureInitial`)
+ * зарезервированы: одноимённое поле формы их затеняет (редкий краевой случай).
+ *
+ * @group Model
+ */
+export interface ModelApi<T> {
+    /**
+     * Escape-hatch к сигналам: `model.$.loanType` → `PathAwareSignal<LoanType>`.
+     * Сам узел — {@link ReadonlySignal} модели целиком: `model.$.subscribe(v => …)`.
+     */
+    readonly $: ModelGroupSignals<T>;
+    /** Снимок значений (без подписки) — для submit. */
+    get(): T;
+    /**
+     * Полная установка значений: принимает объект целиком (все ключи `T`) и записывает их в модель.
+     * Производными полями (цели `compute`) владеет compute — их значения из payload игнорируются.
+     * Не меняет initial-снимок. Для частичного обновления (только переданные ключи) — {@link ModelApi.patch}.
+     *
+     * Если в объекте не хватает ключей (значение пришло без типа — например, с сервера), эти поля
+     * остаются прежними, а в dev выводится предупреждение со списком.
+     */
+    set(value: T): void;
+    /**
+     * Частичное слияние значений (load/patch с сервера): обновляет только переданные ключи,
+     * отсутствующие ключи НЕ трогаются. Вложенные группы сливаются так же, массив заменяется
+     * целиком. Не меняет initial-снимок.
+     */
+    patch(value: DeepPartial<T>): void;
+    /**
+     * Отличаются ли текущие значения от initial-снимка (value-diff). Производные поля — цели
+     * `compute` / `computeFrom` и поля с `markDerived` — не в счёт: их пишет поведение, а не
+     * пользователь, и форма без единой правки изменённой не считается.
+     */
+    isDirty(): boolean;
+    /**
+     * Сбросить значения к initial-снимку. Производные поля сброс не пишет, как `set` и `patch`:
+     * цель `compute` пересчитает поведение, когда вернутся её источники.
+     *
+     * Ноды формы не трогает: замечания погаснут при следующей проверке. Сброс для пользователя —
+     * `form.reset()`: та же точка отсчёта и чистые ноды.
+     */
+    reset(): void;
+    /**
+     * Зафиксировать текущие значения как новый initial-снимок («точка отсчёта»). К нему возвращают
+     * и `model.reset()`, и `form.reset()`.
+     */
+    captureInitial(): void;
+    /**
+     * Резолв строкового пути в сигнал (для error-routing/мостов): лист либо массив целиком
+     * (ручка значения массива — см. {@link ModelArraySignals}). Для пути группы — `undefined`.
+     */
+    signalAt(path: string): PathAwareSignal<unknown> | undefined;
+}
+/**
+ * FormModel — под-модель объекта `T`: value-доступ ({@link ModelObject}) + `.$`-сигналы + {@link ModelApi}
+ * (get/set/patch/isDirty/reset/signalAt). Вложенные объекты-группы модели — тоже {@link FormModel}
+ * (доступны как `model.<group>`), поэтому `model.<group>.$.<field>` эквивалентно `model.$.<group>.<field>`.
+ *
+ * @group Model
+ */
+export type FormModel<T> = ModelObject<T> & ModelApi<T>;
+export {};