adaptform 2.1.0 → 2.2.0

package/CHANGELOG.md

@@ -2,11 +2,59 @@
 
 [English](CHANGELOG.md) · [Русский](CHANGELOG.ru.md)
 
-All notable changes to AdaptForm are documented here. The `2.1.0` section is prepared for release; it remains unreleased until the maintainer publishes it.
+All notable changes to AdaptForm are documented here. Version `2.1.0` was published to npm on 2026-10-14.
 
 **[Interactive demo](https://arhimen.github.io/AdaptForm/)** · [Demo source](https://github.com/ArhiMEN/AdaptForm/tree/master/demo) · [Documentation](https://github.com/ArhiMEN/AdaptForm/blob/master/README.md)
 
-## [2.1.0] - Unreleased
+## [2.2.0] - Unreleased (source prepared)
+
+### Added — headless form state foundation
+
+- **HF-005:** Specify the field/form lifecycle, cleaned baselines, touched-vs-dirty semantics, snapshots, synchronous batches and compatibility rules in English and Russian. ([state contract](docs/ai/HEADLESS_STATE_CONTRACT.md))
+- **HF-006:** Track cleaned initial values with `Field.isDirty` and `commitBaseline()`, including semantic comparisons of Dates, optional Luxon values, plugin-cleaned values and supported nested structures.
+- **HF-007:** Expose derived `isDirty` and baseline commits on `Form`, `ArrayField` and `ArrayFormField`, including collection membership, order and nested values.
+- **HF-008:** Add `subscribe(listener)`, idempotent unsubscribe, stable immutable `getSnapshot()` and publicly exported `SnapshotValue`, `NodeSnapshot`, `FieldSnapshot`, `FormSnapshot`, `ArrayFieldSnapshot`, `ArrayFormSnapshot` types; no required UI framework or runtime dependencies.
+- **HF-009:** Add synchronous nested `Form.batch(callback)` with coalesced notifications, deferred automatic validation using final parent context and deterministic exception finalization. Completed writes are **not rolled back**.
+- **HF-010:** Propagate changes from children, nested forms and collections to parents; reconcile subscriptions when nodes are removed or replaced and release ownership links when observers leave. ([PR #16](https://github.com/ArhiMEN/AdaptForm/pull/16))
+
+### Fixed
+
+- `ArrayField.remove()/clear()` and `ArrayFormField.remove()/clear()` now defer automatic validation inside `Form.batch()`, while retaining synchronous checks outside a batch and immediate explicit `checkValid()`. Added 34 specific regressions.
+- `Form.allErrors` copies child error arrays rather than mutating or freezing live arrays when global errors and immutable snapshots are combined.
+
+### Compatibility and constraints
+
+- Existing class-based APIs, synchronous validation outside batches, `isTouched`, `isValid`, `reset()` behavior (including existing collection membership), serialization and the optional `adaptform/luxon` entry point are preserved.
+- `commitBaseline()` changes the dirty-comparison reference, **not** the target of `reset()`; after committing a different baseline, reset can leave `isDirty=true`.
+- Snapshots are detached immutable data descriptions, not original mutable objects; custom instances may be opaque. Direct in-place changes to exposed legacy arrays/options and arbitrary Form-property replacement are not automatically observed.
+- No `reinitialize()`, HF-004 collection-reset redesign, HF-011+ dependency graph, async validation, submission lifecycle, UI adapter or performance benchmark is included.
+
+### Verification and release status
+
+- Accepted integration PR [#16](https://github.com/ArhiMEN/AdaptForm/pull/16) passed **563 tests in 27 files**, lint, source/demo type-checks, package/demo builds and dependency audit (0 known vulnerabilities). Independent review and [documentation sync PR #17](https://github.com/ArhiMEN/AdaptForm/pull/17) were merged. The 2.2.0 release candidate requires its **own** successful CI.
+- The separate `tsconfig.test.json` check still has **54 existing diagnostics** and is not reported as passing; an older mapped-type `TS2589` reproduces on 2.1.1 as well. No new diagnostics were established in HF-005–HF-010.
+- **Not published.** The source/manifest is being prepared as `2.2.0`; do not interpret this entry or a GitHub merge as npm publication, a tag or a GitHub Release. The last independently verified npm `latest` was `2.1.0`.
+
+## [2.1.1] - Unreleased (prepared)
+
+### Fixed
+
+- **HF-002:** Defer `ArrayField` collection validation during `Form.setFields(data, false)`; with enabled validation, check the final collection once after all form values are assigned, using the parent form as context. Avoid validation against a transient empty array, while preserving the public `itemsValue` setter and its immediate validation of the completed replacement. ([PR #10](https://github.com/ArhiMEN/AdaptForm/pull/10))
+- **HF-003:** Reject incomplete decimal strings such as `"123."`, `"0."` and `"-123."` on explicit validation, including with `gt`/`ge`/`lt`/`le` bounds. Preserve the editable input, comma normalization, existing format-error messages and complete-number precision checks. ([PR #12](https://github.com/ArhiMEN/AdaptForm/pull/12))
+
+### Tests and verification
+
+- Add the HF-001 lifecycle characterization baseline and update its expectations after the two targeted fixes. ([PR #8](https://github.com/ArhiMEN/AdaptForm/pull/8))
+- The accepted HF-003 branch passed **477 tests in 21 files**, lint, source type-check, package build, package-content verification and npm audit (0 reported vulnerabilities). The 2.1.1 release candidate must pass its own CI before publication.
+
+### Compatibility and release status
+
+- **Intentional behavior change:** trailing-decimal values may still be entered and serialized, but no longer pass `Field.checkAndSetValid()` or `Form.checkValid()`. Applications must validate before submitting; `toJSON()` itself does not validate.
+- Public types, `rawValue`/`valueClear` representations, serialization shapes and the optional Luxon entry point are unchanged. No new runtime dependencies.
+- The separate test type-check `tsconfig.test.json` has **54 existing diagnostics** unchanged by HF-002/HF-003; it is not part of required CI. These are tracked as technical debt, not represented as passing.
+- **Release not yet published.** Version `2.1.1` is being prepared; do not infer npm publication, a GitHub release or a tag from this entry.
+
+## [2.1.0] - 2026-10-14
 
 ### Added
 
@@ -57,9 +105,9 @@ All notable changes to AdaptForm are documented here. The `2.1.0` section is pre
 
 ### Compatibility notes
 
-- Built-in library validation messages and their language have not been changed in this release candidate. Localization and any structured error-code contract are deferred to a separate coordinated task.
+- Built-in library validation messages and their language have not been changed in this release. Localization and any structured error-code contract are deferred to a separate coordinated task.
 - PlayLease-specific integration work is explicitly out of scope for this branch.
-- This changelog describes the release candidate in branch `v2.1.0`; npm publication and the GitHub release are still maintainer actions.
+- Version `2.1.0` was published manually to npm. No GitHub release or release tag has been created.
 
 ## [2.0.5] - 2026-07-22
 

package/CHANGELOG.ru.md

@@ -2,11 +2,59 @@
 
 [English](CHANGELOG.md) · [Русский](CHANGELOG.ru.md)
 
-Здесь описаны все значимые изменения AdaptForm. Раздел `2.1.0` подготовлен к выпуску, но остаётся неопубликованным до публикации сопровождающим проекта.
+Здесь описаны все значимые изменения AdaptForm. Версия `2.1.0` опубликована в npm 2026-10-14.
 
 **[Интерактивное демо](https://arhimen.github.io/AdaptForm/?lang=ru)** · [Исходный код демо](https://github.com/ArhiMEN/AdaptForm/tree/master/demo) · [Документация](https://github.com/ArhiMEN/AdaptForm/blob/master/README.ru.md)
 
-## [2.1.0] — Не выпущено
+## [2.2.0] — Не опубликована (исходники подготовлены)
+
+### Добавлено — фундамент headless-состояний
+
+- **HF-005:** Спецификация жизненного цикла полей и форм, baseline очищенных значений, touched/dirty, snapshots, синхронных batch и совместимости на EN/RU. ([контракт](docs/ai/HEADLESS_STATE_CONTRACT.ru.md))
+- **HF-006:** `Field.isDirty` и `commitBaseline()` с семантическим сравнением Date, необязательного Luxon, данных после плагинов и поддерживаемых вложенных структур.
+- **HF-007:** Производное `isDirty` и фиксация baseline у `Form`, `ArrayField`, `ArrayFormField`: учитываются состав, порядок коллекций и вложенные значения.
+- **HF-008:** `subscribe(listener)`, идемпотентная отписка, стабильный неизменяемый `getSnapshot()` и публичные типы `SnapshotValue`, `NodeSnapshot`, `FieldSnapshot`, `FormSnapshot`, `ArrayFieldSnapshot`, `ArrayFormSnapshot`. Новых обязательных runtime/UI-зависимостей нет.
+- **HF-009:** Синхронный вложенный `Form.batch(callback)` с объединёнными уведомлениями, отложенной автоматической валидацией по итоговым данным и корректным завершением при исключении. Уже выполненные изменения **не откатываются**.
+- **HF-010:** Передача изменений от потомков и коллекций родителю, обновление связей при удалении/замене и очистка владения при отписке. ([PR #16](https://github.com/ArhiMEN/AdaptForm/pull/16))
+
+### Исправлено
+
+- `ArrayField.remove()/clear()` и `ArrayFormField.remove()/clear()` откладывают автоматическую проверку внутри `Form.batch()`, но проверяют синхронно вне batch; явные `checkValid()` остаются немедленными. Добавлено 34 целевых регрессии.
+- `Form.allErrors` копирует массивы ошибок потомков, исключая мутацию и заморозку живых массивов при совмещении глобальных ошибок и snapshots.
+
+### Совместимость и ограничения
+
+- Сохранены прежние class-based API, синхронные проверки вне batch, `isTouched`, `isValid`, поведение `reset()` (включая состав коллекций), сериализация и необязательный `adaptform/luxon`.
+- `commitBaseline()` меняет точку сравнения dirty, **не** цель `reset()`. После фиксации другого baseline сброс может оставить `isDirty=true`.
+- Snapshots — независимые неизменяемые представления, а не исходные изменяемые объекты; пользовательские экземпляры классов могут быть непрозрачными. Прямые мутации прежних массивов/options и произвольная замена свойств Form не перехватываются автоматически.
+- Нет `reinitialize()`, изменения reset коллекций (HF-004), графа зависимостей (HF-011+), асинхронных валидаторов, submit lifecycle, UI-адаптеров или бенчмарков.
+
+### Проверки и выпуск
+
+- Принятый [PR #16](https://github.com/ArhiMEN/AdaptForm/pull/16) прошёл **563 теста в 27 файлах**, lint, проверку типов исходников/демо, сборки библиотеки/демо и аудит (0 известных уязвимостей). Независимое ревью выполнено, [PR #17 с документацией](https://github.com/ArhiMEN/AdaptForm/pull/17) объединён. Для кандидата 2.2.0 требуется **собственный** успешный CI.
+- Отдельная проверка `tsconfig.test.json` сохраняет **54 прежние диагностики** и не объявляется пройденной; старый `TS2589` mapped type воспроизводится также на 2.1.1. Новых диагностик в HF-005–HF-010 не установлено.
+- **Не опубликована.** В исходниках готовится `2.2.0`, но запись changelog или merge в GitHub не равны публикации npm, тегу или GitHub Release. Последняя отдельно проверенная npm-версия `latest` — `2.1.0`.
+
+## [2.1.1] — Не опубликована (подготовка)
+
+### Исправлено
+
+- **HF-002:** Проверка коллекции `ArrayField` откладывается при `Form.setFields(data, false)`. При включённой валидации завершённая коллекция проверяется один раз после присваивания всех полей, с контекстом родительской формы. Промежуточный пустой массив больше не проверяется; публичный setter `itemsValue` сохранён и проверяет итоговую замену немедленно. ([PR #10](https://github.com/ArhiMEN/AdaptForm/pull/10))
+- **HF-003:** Незавершённые десятичные значения, например `"123."`, `"0."` и `"-123."`, отклоняются при явной проверке, в том числе при ограничениях `gt`/`ge`/`lt`/`le`. Ввод остаётся редактируемым; нормализация запятой, существующие сообщения об ошибках формата и точность завершённых чисел сохранены. ([PR #12](https://github.com/ArhiMEN/AdaptForm/pull/12))
+
+### Тесты и проверки
+
+- Добавлены characterization-тесты жизненного цикла HF-001 и обновлены их ожидания после двух исправлений. ([PR #8](https://github.com/ArhiMEN/AdaptForm/pull/8))
+- В принятой ветке HF-003 прошли **477 тестов в 21 файле**, lint, типы исходного кода, сборка, проверка пакета и npm audit (0 известных уязвимостей). Кандидат 2.1.1 должен пройти собственный CI до публикации.
+
+### Совместимость и статус
+
+- **Намеренное изменение поведения:** строки с завершающим десятичным разделителем можно редактировать и сериализовать, но они больше не проходят `Field.checkAndSetValid()` и `Form.checkValid()`. Перед отправкой приложение должно проверить форму; `toJSON()` не запускает проверку.
+- Публичные типы, представления `rawValue`/`valueClear`, формат сериализации и необязательная точка входа Luxon не изменены. Новых обязательных зависимостей нет.
+- Отдельная типизация тестов `tsconfig.test.json` сохраняет **54 ранее существовавшие диагностики** после HF-002/HF-003; она не является обязательным этапом CI и не объявляется успешной.
+- **Версия ещё не опубликована.** `2.1.1` только готовится: эта запись не означает публикацию в npm, создание GitHub Release или тега.
+
+## [2.1.0] — 2026-10-14
 
 ### Добавлено
 
@@ -57,9 +105,9 @@
 
 ### Совместимость
 
-- Встроенные сообщения валидации библиотеки и их язык в этом кандидате не изменены. Их локализация и контракт структурированных кодов ошибок отложены до отдельной согласованной задачи.
+- Встроенные сообщения валидации библиотеки и их язык в этом выпуске не изменены. Их локализация и контракт структурированных кодов ошибок отложены до отдельной согласованной задачи.
 - Интеграция с PlayLease явно исключена из области этой ветки.
-- Эта история описывает кандидата в ветке `v2.1.0`; публикация npm-пакета и выпуск на GitHub остаются действиями сопровождающего проекта.
+- Версия `2.1.0` опубликована в npm вручную. Релиз и тег GitHub не создавались.
 
 ## [2.0.5] — 2026-07-22
 

package/README.md

@@ -7,11 +7,11 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
 
-**[Open the interactive demo](https://arhimen.github.io/AdaptForm/)** · **[Read the 2.1.0 changelog](https://github.com/ArhiMEN/AdaptForm/blob/master/CHANGELOG.md)** · **[Browse the demo source](https://github.com/ArhiMEN/AdaptForm/tree/master/demo)**
+**[Open the interactive demo](https://arhimen.github.io/AdaptForm/)** · **[Read the changelog](https://github.com/ArhiMEN/AdaptForm/blob/master/CHANGELOG.md)** · **[Browse the demo source](https://github.com/ArhiMEN/AdaptForm/tree/master/demo)**
 
 Maintainers: [automatic npm publication setup](docs/NPM_PUBLISH.md).
 
-AdaptForm is a TypeScript-first form modeling library inspired by Django Forms and Pydantic. Define forms as classes with typed fields. Each field owns its value, casting, validation, transformation plugins, errors, and state.
+AdaptForm is a TypeScript-first, framework-independent, class-based headless form engine inspired by Django Forms and Pydantic. Forms and fields manage values, casting, validation, errors, baselines, subscriptions and observable state without requiring UI framework components.
 
 ## Features
 
@@ -25,6 +25,9 @@ AdaptForm is a TypeScript-first form modeling library inspired by Django Forms a
 - JSON and `FormData` serialization.
 - Optional Luxon integration through the `adaptform/luxon` entry point.
 - Framework-agnostic core with no required runtime dependencies.
+- Clean-value baselines with `isDirty` and `commitBaseline()` on fields, forms and collections.
+- Stable immutable `getSnapshot()` data, `subscribe()` and unsubscribe for reactive UIs.
+- Synchronous nested `Form.batch()` and propagation of nested form/collection updates.
 
 ## Installation
 
@@ -40,7 +43,7 @@ Luxon integration is optional:
 npm install luxon
 ```
 
-The [interactive demo](https://arhimen.github.io/AdaptForm/) runs from repository source, with automatic deployment from `v2.1.0` and `master`. Version `2.1.0` is prepared in the repository; npm continues to serve the last published version until the maintainer publishes the release.
+The [interactive demo](https://arhimen.github.io/AdaptForm/) runs from repository source, with automatic deployment from `v2.1.0` and `master`. **Headless APIs in the 2.2.0 source candidate are not yet published to npm.** Check the [npm package](https://www.npmjs.com/package/adaptform) for available published versions.
 
 The demo supports English and Russian with a persistent language selector: [English](https://arhimen.github.io/AdaptForm/?lang=en) · [Русский](https://arhimen.github.io/AdaptForm/?lang=ru). Switching languages preserves form data and validation state.
 
@@ -127,7 +130,7 @@ const price = new Field(DecimalType, null, {
 })
 ```
 
-Supports `gt`, `ge`, `lt`, `le`, `decimalPlaces`, and `maxDigits`. Numeric inputs with excess precision are rejected rather than silently rounded. String inputs may use a comma or a period as the decimal separator.
+Supports `gt`, `ge`, `lt`, `le`, `decimalPlaces`, and `maxDigits`. Numeric inputs with excess precision are rejected rather than silently rounded. String inputs may use a comma or a period as the decimal separator. Incomplete values such as `"123."` retain their editable text but fail explicit validation; call `Form.checkValid()` before submitting. `toJSON()` does not validate automatically.
 
 ### BooleanType
 
@@ -180,7 +183,7 @@ Validators are synchronous; returning a Promise is not supported. For asynchrono
 - If you change dependent fields one at a time, call `form.checkValid()` after the changes to recompute cross-field rules.
 - `field.setRawValue(value, false)` and `form.setFields(data, false)` allow advanced callers to defer validation. Call `checkValid()` before relying on the validity state.
 - `reset()` restores defaults, clears errors, and leaves validity unset until the next validation. Collection validity is false after reset until the collection is checked again.
-- Adding, removing, or clearing collection items refreshes collection validation. Invalid removal indices are ignored.
+- Adding, removing, or clearing collection items refreshes collection validation outside `Form.batch()`; inside a batch automatic validation is deferred. Invalid removal indices are ignored.
 
 ## Dynamic collections
 
@@ -346,10 +349,10 @@ const date = new Field(DateLuxonType, null, {
 
 | Class | Main API |
 | --- | --- |
-| `Form` | `fields`, `setFields()`, `fieldsValue`, `checkValid()`, `isValid`, `allErrors`, `globalErrors`, `errors`, `setGlobalError()`, `clearGlobalErrors()`, `reset()`, `toJSON()`, `toFormData()` |
-| `Field` | `rawValue`, `setRawValue()`, `valueClear`, `errors`, `error`, `isValid`, `isTouched`, `isEmpty`, `checkValid()`, `reset()` |
-| `ArrayField` | `items`, `itemsValue`, `add()`, `remove()`, `clear()`, `checkValid()`, `reset()` |
-| `ArrayFormField` | `forms`, `formsFieldsValue`, `add()`, `remove()`, `clear()`, `checkValid()`, `reset()` |
+| `Form` | `fields`, `setFields()`, `fieldsValue`, `checkValid()`, `isValid`, `isDirty`, `commitBaseline()`, `subscribe()`, `getSnapshot()`, `batch()`, `allErrors`, `globalErrors`, `errors`, `setGlobalError()`, `clearGlobalErrors()`, `reset()`, `toJSON()`, `toFormData()` |
+| `Field` | `rawValue`, `setRawValue()`, `valueClear`, `errors`, `error`, `isValid`, `isTouched`, `isDirty`, `commitBaseline()`, `subscribe()`, `getSnapshot()`, `isEmpty`, `checkValid()`, `reset()` |
+| `ArrayField` | `items`, `itemsValue`, `add()`, `remove()`, `clear()`, `isDirty`, `commitBaseline()`, `subscribe()`, `getSnapshot()`, `checkValid()`, `reset()` |
+| `ArrayFormField` | `forms`, `formsFieldsValue`, `add()`, `remove()`, `clear()`, `isDirty`, `commitBaseline()`, `subscribe()`, `getSnapshot()`, `checkValid()`, `reset()` |
 | `ErrorsSchema` | `staticKey()`, `dynamicKey()`, `fallback()`, `transformValue()`, `parseErrors()`, `parseErrorsDetailed()`, `nest()`, `clone()`, `merge()`, `forArray()`, `fromObject()` |
 
 ## Development
@@ -386,3 +389,34 @@ The demo is built by GitHub Actions from `v2.1.0` and `master`. GitHub Pages is
 ## License
 
 MIT © Stanislav Orlov
+
+## Headless form state (2.2.0 source candidate)
+
+HF-005–HF-010 were merged after independent review. The **source candidate is 2.2.0**, but npm publication is separate, so these APIs may not yet be available from `npm install adaptform`.
+
+```typescript
+import {Field, Form, NumberType, StringType} from 'adaptform'
+
+class SettingsForm extends Form {
+  displayName = new Field(StringType, 'Alex')
+  notifications = new Field(NumberType, 1)
+}
+
+const form = new SettingsForm()
+const unsubscribe = form.subscribe(() => {
+  const snapshot = form.getSnapshot()
+  console.log(snapshot.isDirty, snapshot.isValid, snapshot.fieldsValue)
+})
+
+form.batch(() => {
+  form.displayName.rawValue = 'Alexandra'
+  form.notifications.rawValue = 2
+}) // One coherent notification after final automatic validation
+
+form.commitBaseline() // Accept current cleaned values; isDirty becomes false
+unsubscribe()        // Release the listener
+```
+
+`isTouched` keeps its former semantics. `commitBaseline()` changes the dirty-comparison baseline, **not** the constructor defaults restored by `reset()`; a reset may leave `isDirty=true`. Snapshots are detached read-only descriptions, not mutable source objects; `toJSON()` still does not validate.
+
+Automatic validation inside `Form.batch()` is deferred, whereas explicit `checkValid()` is immediate. Batch callbacks must be synchronous and do not roll back changes on errors. Direct in-place changes to legacy public arrays or arbitrary form properties are not automatically observed. See [usage and limitations](docs/ai/HEADLESS_STATE_USAGE.md) and the [2.1.1 compatibility table](docs/ai/HEADLESS_STATE_CONTRACT.md#compatibility-with-211).

package/README.ru.md

@@ -7,11 +7,11 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
 
-**[Открыть интерактивное демо](https://arhimen.github.io/AdaptForm/?lang=ru)** · **[История изменений 2.1.0](https://github.com/ArhiMEN/AdaptForm/blob/master/CHANGELOG.ru.md)** · **[Исходный код демо](https://github.com/ArhiMEN/AdaptForm/tree/master/demo)**
+**[Открыть интерактивное демо](https://arhimen.github.io/AdaptForm/?lang=ru)** · **[История изменений](https://github.com/ArhiMEN/AdaptForm/blob/master/CHANGELOG.ru.md)** · **[Исходный код демо](https://github.com/ArhiMEN/AdaptForm/tree/master/demo)**
 
 Для сопровождающих: [настройка автоматической публикации в npm](docs/NPM_PUBLISH.ru.md).
 
-AdaptForm — библиотека моделирования форм с приоритетом TypeScript, вдохновлённая Django Forms и Pydantic. Формы описываются классами с типизированными полями. Каждое поле управляет своим значением, приведением типов, валидацией, плагинами преобразования, ошибками и состоянием.
+AdaptForm — независимый от UI-фреймворков headless-движок форм с class-based API и приоритетом TypeScript, вдохновлённый Django Forms и Pydantic. Формы и поля управляют значениями, приведением типов, валидацией, ошибками, baseline, подписками и наблюдаемым состоянием без зависимости от UI-компонентов.
 
 ## Возможности
 
@@ -25,6 +25,9 @@ AdaptForm — библиотека моделирования форм с при
 - Сериализация в JSON и `FormData`.
 - Необязательная интеграция с Luxon через точку входа `adaptform/luxon`.
 - Независимое от фреймворков ядро без обязательных зависимостей времени выполнения.
+- Исходные очищенные значения с `isDirty` и `commitBaseline()` у полей, форм и коллекций.
+- Стабильные неизменяемые снимки `getSnapshot()`, подписки и отписка через `subscribe()`.
+- Вложенный синхронный `Form.batch()` и распространение обновлений вложенных форм и коллекций.
 
 ## Установка
 
@@ -40,7 +43,7 @@ npm install adaptform
 npm install luxon
 ```
 
-[Интерактивное демо](https://arhimen.github.io/AdaptForm/?lang=ru) использует исходный код репозитория и автоматически публикуется из `v2.1.0` и `master`. В репозитории подготовлена версия `2.1.0`; npm продолжает предоставлять последнюю опубликованную версию до публикации нового выпуска сопровождающим проекта.
+[Интерактивное демо](https://arhimen.github.io/AdaptForm/?lang=ru) использует исходный код репозитория и автоматически публикуется из `v2.1.0` и `master`. **Новые headless API в кандидатных исходниках 2.2.0 ещё не опубликованы в npm.** Доступные для установки версии проверяйте на [npm](https://www.npmjs.com/package/adaptform).
 
 Демо поддерживает английский и русский языки с сохранением выбора: [English](https://arhimen.github.io/AdaptForm/?lang=en) · [Русский](https://arhimen.github.io/AdaptForm/?lang=ru). Переключение языка сохраняет данные формы и состояние валидации.
 
@@ -127,7 +130,7 @@ const price = new Field(DecimalType, null, {
 })
 ```
 
-Поддерживаются `gt`, `ge`, `lt`, `le`, `decimalPlaces` и `maxDigits`. Числовые значения с избыточной точностью отклоняются без скрытого округления. В строковых значениях десятичным разделителем может быть запятая или точка.
+Поддерживаются `gt`, `ge`, `lt`, `le`, `decimalPlaces` и `maxDigits`. Числовые значения с избыточной точностью отклоняются без скрытого округления. В строковых значениях десятичным разделителем может быть запятая или точка. Незавершённые значения вроде `"123."` сохраняются при редактировании, но не проходят явную проверку; перед отправкой вызывайте `Form.checkValid()`. Метод `toJSON()` не выполняет валидацию автоматически.
 
 ### BooleanType
 
@@ -180,7 +183,7 @@ class PasswordForm extends Form {
 - Если зависимые поля меняются по отдельности, после изменений вызовите `form.checkValid()` для пересчёта зависимых правил.
 - `field.setRawValue(value, false)` и `form.setFields(data, false)` позволяют отложить валидацию. Прежде чем полагаться на корректность формы, вызовите `checkValid()`.
 - `reset()` восстанавливает значения по умолчанию, очищает ошибки и оставляет корректность неопределённой до следующей проверки. Корректность коллекции после сброса равна false до её повторной проверки.
-- Добавление, удаление и очистка элементов обновляют валидацию коллекции. Некорректные индексы удаления игнорируются.
+- Добавление, удаление и очистка элементов проверяют коллекции вне `Form.batch()`; внутри batch автоматическая валидация откладывается. Некорректные индексы удаления игнорируются.
 
 ## Динамические коллекции
 
@@ -346,10 +349,10 @@ const date = new Field(DateLuxonType, null, {
 
 | Класс | Основной API |
 | --- | --- |
-| `Form` | `fields`, `setFields()`, `fieldsValue`, `checkValid()`, `isValid`, `allErrors`, `globalErrors`, `errors`, `setGlobalError()`, `clearGlobalErrors()`, `reset()`, `toJSON()`, `toFormData()` |
-| `Field` | `rawValue`, `setRawValue()`, `valueClear`, `errors`, `error`, `isValid`, `isTouched`, `isEmpty`, `checkValid()`, `reset()` |
-| `ArrayField` | `items`, `itemsValue`, `add()`, `remove()`, `clear()`, `checkValid()`, `reset()` |
-| `ArrayFormField` | `forms`, `formsFieldsValue`, `add()`, `remove()`, `clear()`, `checkValid()`, `reset()` |
+| `Form` | `fields`, `setFields()`, `fieldsValue`, `checkValid()`, `isValid`, `isDirty`, `commitBaseline()`, `subscribe()`, `getSnapshot()`, `batch()`, `allErrors`, `globalErrors`, `errors`, `setGlobalError()`, `clearGlobalErrors()`, `reset()`, `toJSON()`, `toFormData()` |
+| `Field` | `rawValue`, `setRawValue()`, `valueClear`, `errors`, `error`, `isValid`, `isTouched`, `isDirty`, `commitBaseline()`, `subscribe()`, `getSnapshot()`, `isEmpty`, `checkValid()`, `reset()` |
+| `ArrayField` | `items`, `itemsValue`, `add()`, `remove()`, `clear()`, `isDirty`, `commitBaseline()`, `subscribe()`, `getSnapshot()`, `checkValid()`, `reset()` |
+| `ArrayFormField` | `forms`, `formsFieldsValue`, `add()`, `remove()`, `clear()`, `isDirty`, `commitBaseline()`, `subscribe()`, `getSnapshot()`, `checkValid()`, `reset()` |
 | `ErrorsSchema` | `staticKey()`, `dynamicKey()`, `fallback()`, `transformValue()`, `parseErrors()`, `parseErrorsDetailed()`, `nest()`, `clone()`, `merge()`, `forArray()`, `fromObject()` |
 
 ## Разработка
@@ -386,3 +389,34 @@ npm run dev -- --config demo/vite.config.ts
 ## Лицензия
 
 MIT © Stanislav Orlov
+
+## Headless-состояния форм (кандидат исходников 2.2.0)
+
+HF-005–HF-010 прошли независимое ревью и объединены. **Кандидат исходников — 2.2.0**, а публикация в npm — отдельный этап, поэтому новые API могут отсутствовать в пакете, установленном через `npm install adaptform`.
+
+```typescript
+import {Field, Form, NumberType, StringType} from 'adaptform'
+
+class SettingsForm extends Form {
+  displayName = new Field(StringType, 'Alex')
+  notifications = new Field(NumberType, 1)
+}
+
+const form = new SettingsForm()
+const unsubscribe = form.subscribe(() => {
+  const snapshot = form.getSnapshot()
+  console.log(snapshot.isDirty, snapshot.isValid, snapshot.fieldsValue)
+})
+
+form.batch(() => {
+  form.displayName.rawValue = 'Alexandra'
+  form.notifications.rawValue = 2
+}) // One coherent notification after final automatic validation
+
+form.commitBaseline() // Accept current cleaned values; isDirty becomes false
+unsubscribe()        // Release the listener
+```
+
+`isTouched` сохраняет прежнюю семантику. `commitBaseline()` меняет точку сравнения dirty, **не** значения конструктора, возвращаемые `reset()`; после сброса `isDirty` иногда остаётся `true`. Snapshots — независимые неизменяемые представления, а не ссылки на изменяемые данные. `toJSON()` по-прежнему не выполняет валидацию.
+
+Автоматическая проверка внутри `Form.batch()` откладывается, явные `checkValid()` выполняются сразу. Batch только синхронный; при исключении выполненные изменения не откатываются. Прямые мутации старых публичных массивов и произвольная замена свойств формы не создают автоматических уведомлений. Подробности: [использование и ограничения](docs/ai/HEADLESS_STATE_USAGE.ru.md), [совместимость с 2.1.1](docs/ai/HEADLESS_STATE_CONTRACT.ru.md#совместимость-с-211).

package/dist/{Form-kPYL4f-n.d.cts → Form-uHUaTUZS.d.cts}

@@ -1,3 +1,47 @@
+/** Shared mutation boundary; subclasses only describe state and their mutations. */
+declare abstract class ObservableNode<TSnapshot> {
+    private readonly _stateStore;
+    protected abstract captureState(): TSnapshot;
+    protected stateChildren(): readonly ObservableNode<unknown>[];
+    private contains;
+    protected validateAfterMutation(callback: () => unknown): void;
+    protected batchUpdate<TResult>(callback: () => TResult, validate: () => unknown): TResult;
+    subscribe(listener: () => void): () => void;
+    getSnapshot(): TSnapshot;
+    protected update<TResult>(callback: () => TResult): TResult;
+}
+
+/** Snapshots contain data only: mutable built-ins and opaque instances are described. */
+type SnapshotValue = null | undefined | string | number | boolean | bigint | readonly SnapshotValue[] | {
+    readonly [key: string]: SnapshotValue;
+};
+interface NodeSnapshot {
+    readonly isValid: boolean | null;
+    readonly isTouched: boolean;
+    readonly isDirty: boolean;
+}
+interface FieldSnapshot extends NodeSnapshot {
+    readonly rawValue: SnapshotValue;
+    readonly valueClear: SnapshotValue;
+    readonly errors: readonly string[];
+}
+interface FormSnapshot extends NodeSnapshot {
+    readonly fieldsValue: Readonly<Record<string, SnapshotValue>>;
+    readonly allErrors: Readonly<Record<string, readonly string[]>>;
+    readonly globalErrors: Readonly<Record<string, string>>;
+    readonly fields: Readonly<Record<string, FieldSnapshot | ArrayFieldSnapshot | ArrayFormSnapshot>>;
+}
+interface ArrayFieldSnapshot extends NodeSnapshot {
+    readonly itemsValue: readonly SnapshotValue[];
+    readonly errors: readonly string[];
+    readonly items: readonly FieldSnapshot[];
+}
+interface ArrayFormSnapshot extends NodeSnapshot {
+    readonly formsFieldsValue: readonly Readonly<Record<string, SnapshotValue>>[];
+    readonly errors: readonly string[];
+    readonly forms: readonly FormSnapshot[];
+}
+
 interface FieldPlugin<T = any> {
     pluginOptions?: PluginOptions;
     init?(field: Field<T>): void;
@@ -9,15 +53,23 @@ declare abstract class BasePlugin<T = any> implements FieldPlugin<T> {
     constructor(pluginOptions?: PluginOptions);
 }
 
-declare class ArrayField<T = any> {
+declare class ArrayField<T = any> extends ObservableNode<ArrayFieldSnapshot> {
     protected factory: (value?: T) => Field<T>;
+    protected captureState(): ArrayFieldSnapshot;
     protected options: ArrayFieldOptions;
     protected _items: Field<T>[];
     protected _errors: string[];
+    protected stateChildren(): readonly ObservableNode<unknown>[];
+    private _baseline;
     private _hasValidationResult;
-    isTouched: boolean;
+    private _isTouched;
+    get isTouched(): boolean;
+    set isTouched(value: boolean);
     constructor(factory: (value?: T) => Field<T>, options?: ArrayFieldOptions, initial?: (T | null)[]);
+    get isDirty(): boolean;
+    commitBaseline(): void;
     set itemsValue(items: (T | null)[]);
+    setItemsValue(items: (T | null)[], validate?: boolean): void;
     get itemsValue(): (T | null)[];
     get items(): Field<T>[];
     add(value?: T, force_check?: boolean): Field<T>;
@@ -33,14 +85,21 @@ declare class ArrayField<T = any> {
     reset(): void;
 }
 
-declare class ArrayFormField<T extends Form = Form> {
+declare class ArrayFormField<T extends Form = Form> extends ObservableNode<ArrayFormSnapshot> {
     private FormConstructor;
     private options;
+    protected captureState(): ArrayFormSnapshot;
     private _forms;
     private _errors;
+    protected stateChildren(): readonly ObservableNode<unknown>[];
+    private _baseline;
     private _hasValidationResult;
-    isTouched: boolean;
+    private _isTouched;
+    get isTouched(): boolean;
+    set isTouched(value: boolean);
     constructor(FormConstructor: new () => T, options?: ArrayFormFieldOptions, initial?: unknown[]);
+    get isDirty(): boolean;
+    commitBaseline(): void;
     set forms(forms: unknown[]);
     setForms(forms: unknown[], validate?: boolean): void;
     get forms(): T[];
@@ -170,15 +229,21 @@ declare abstract class FieldType<T, O extends FieldOptions = FieldOptions> {
 }
 
 type FieldTypeConstructor<T, O extends FieldOptions = FieldOptions> = new (options: O) => FieldType<T, O>;
-declare class Field<T = any, O extends FieldOptions = FieldOptions> {
+declare class Field<T = any, O extends FieldOptions = FieldOptions> extends ObservableNode<FieldSnapshot> {
     protected _rawValue: any;
     protected _valueClear: T | null;
     protected fieldType: FieldType<T, O>;
     protected defaultValue: T | null;
+    private _baseline;
     protected _errors: string[];
-    isValid: boolean | null;
-    isTouched: boolean;
+    private _isValid;
+    get isValid(): boolean | null;
+    set isValid(value: boolean | null);
+    private _isTouched;
+    get isTouched(): boolean;
+    set isTouched(value: boolean);
     constructor(TypeConstructor: FieldTypeConstructor<T, O>, defaultValue?: T | null, options?: O | null);
+    protected captureState(): FieldSnapshot;
     protected get plugins(): FieldPlugin<any>[];
     get options(): O;
     set options(options: O);
@@ -190,6 +255,8 @@ declare class Field<T = any, O extends FieldOptions = FieldOptions> {
     get error(): string;
     set error(message: string | null);
     get valueClear(): T | null;
+    get isDirty(): boolean;
+    commitBaseline(): void;
     private isRequired;
     checkValid(form?: Form): boolean;
     checkAndSetValid(form?: Form): boolean;
@@ -280,7 +347,10 @@ type FormFieldValue<TField> = TField extends Field<infer TValue, infer _Options>
 type FormFieldsValue<TForm extends Form> = {
     [K in keyof TForm as TForm[K] extends Field<infer _Value, infer _Options> | ArrayField<infer _ArrayValue> | ArrayFormField<infer _NestedForm> ? K : never]: FormFieldValue<TForm[K]>;
 };
-declare abstract class Form {
+declare abstract class Form extends ObservableNode<FormSnapshot> {
+    protected captureState(): FormSnapshot;
+    protected stateChildren(): readonly ObservableNode<unknown>[];
+    batch<TResult>(callback: () => TResult & (TResult extends PromiseLike<unknown> ? never : unknown)): TResult;
     private _globalErrors;
     errorsShema: ErrorsSchema;
     protected get _fields(): Record<string, Field<any> | ArrayField<any> | ArrayFormField<any>>;
@@ -305,6 +375,8 @@ declare abstract class Form {
     setGlobalError(key: string, message: string): void;
     clearGlobalErrors(): void;
     reset(): void;
+    get isDirty(): boolean;
+    commitBaseline(): void;
     get isTouched(): boolean;
     get isValid(): boolean;
     toFormData(): FormData;
@@ -312,4 +384,4 @@ declare abstract class Form {
     private serializeJsonValue;
 }
 
-export { ArrayField as A, BasePlugin as B, type DecimalOptions as D, ErrorsSchema as E, Field as F, type MaskPluginOptions as M, type NumberOptions as N, type PluginOptions as P, type StringOptions as S, FieldType as a, type BooleanOptions as b, type DateOptions as c, type ArrayFieldOptions as d, ArrayFormField as e, type ArrayFormFieldOptions as f, DefaultErrorsSchema as g, type DynamicRule as h, type FieldOptions as i, type FieldPlugin as j, Form as k, type FormFieldValue as l, type FormFieldsValue as m, type ParsedError as n, type messagesArrayFieldOptions as o, type messagesArrayFormFieldOptions as p, type messagesBooleanOptions as q, type messagesDateOptions as r, type messagesDecimalOptions as s, type messagesNumberOptions as t, type messagesOptions as u, type messagesStringOptions as v };
+export { ArrayField as A, BasePlugin as B, type messagesOptions as C, type DecimalOptions as D, ErrorsSchema as E, Field as F, type messagesStringOptions as G, type MaskPluginOptions as M, type NumberOptions as N, type PluginOptions as P, type StringOptions as S, FieldType as a, type BooleanOptions as b, type DateOptions as c, type ArrayFieldOptions as d, type ArrayFieldSnapshot as e, ArrayFormField as f, type ArrayFormFieldOptions as g, type ArrayFormSnapshot as h, DefaultErrorsSchema as i, type DynamicRule as j, type FieldOptions as k, type FieldPlugin as l, type FieldSnapshot as m, Form as n, type FormFieldValue as o, type FormFieldsValue as p, type FormSnapshot as q, type NodeSnapshot as r, type ParsedError as s, type SnapshotValue as t, type messagesArrayFieldOptions as u, type messagesArrayFormFieldOptions as v, type messagesBooleanOptions as w, type messagesDateOptions as x, type messagesDecimalOptions as y, type messagesNumberOptions as z };