@vnejs/docs 0.2.37 → 0.2.39

package/CHANGELOG.md

@@ -2,6 +2,43 @@
 
 Краткая история изменений движка (плагины, helpers, packages, CLI и прочий runtime) и внешнего API. Версии — релизы пакета `@vnejs/docs`.
 
+## 0.2.39
+
+- `game/checkers` — пресеты `FLIPPED` (белые сверху / чёрные снизу, все дамки) и `RANDOM` (12+12 на случайных тёмных клетках; на каждый `SHOW` новый расклад). API: `PARAMS.CHECKERS.PRESETS.FLIPPED` / `RANDOM`, `createFlippedPreset`, `createRandomPreset`.
+- `games/checkers` — `% choose` «Партия»: 6 вариантов (COMMON / FLIPPED / RANDOM × первые ходят белые / чёрные) → `$ checkers show` с args.
+- `game/checkers` — `$ checkers show` берёт `initialOwner` / `initialPreset` из indent-args (`initialOwner: black`, `initialPreset: COMMON`), не из позиционных токенов.
+- `game/checkers` — `PARAMS.CHECKERS.PRESETS` (`COMMON` = стандартный старт); `SHOW.initialPreset` → cells из пресета (нет / неизвестный → `COMMON`). API: `PARAMS.CHECKERS.PRESETS`, `CheckersShowPayload.initialPreset`, `createCommonPreset`.
+- `game/checkers` — `EVENTS.CHECKERS.SHOW` payload `CheckersShowPayload` `{ initialOwner?, initialPreset? }`; без / невалидный `initialOwner` → белые. API: `CheckersShowPayload`.
+- `game/checkers` — `EVENTS.CHECKERS.SET` / `UNSET` (`vne:checkers:set` / `unset`): `{ cells, owner }` → `GRID.SET` + `TURNS.SET` (id / rows / columns из `GRID_ID` / `TURN_ID` / `PARAMS`); `UNSET` → `GRID.UNSET` + `TURNS.UNSET`. Модуль `checkers.set`. Call-sites: `SHOW` / `MOVE_PLAY` → `SET`, `HIDE` → `UNSET`.
+- `common/grid` — плагин квадратной сетки `@vnejs/plugins.common.grid` (`PLUGIN_NAME` `GRID`). API: `EVENTS.GRID.SET` / `GET` / `UNSET` / `CHANGED` / `PUT` / `MOVE` / `REMOVE` (`vne:grid:*`); элемент — объект с `id`; state — map `id → { rows, columns, cells }` (плотная `(item \| null)[][]`). `STATE.SET` / `CLEAR` диффят через `SET` / `UNSET`.
+- `game/checkers` — доска через `GRID.*` вместо `BOARD_CHANGE` / `BOARD_CHANGED` / `BOARD_GET`; модуль `checkers.board` удалён. API: `CONST.CHECKERS.GRID_ID` (`"checkers"`); `SHOW` → `GRID.SET` + `TURNS.SET`; `HIDE` → `GRID.UNSET` + `TURNS.UNSET`; `MOVE_PLAY` читает `GRID.GET`, пишет `GRID.SET`.
+- `views.screens/checkers` / `ai/checkers` — `board` с `GRID.CHANGED` / `UNSET` (`cells`, фильтр `GRID_ID`).
+- `bundles/checkers` — импорт `@vnejs/plugins.common.grid`.
+- `common/turn` — плагин хода `@vnejs/plugins.common.turn` (`PLUGIN_NAME` `TURNS`). API: `EVENTS.TURNS.SET` / `GET` / `UNSET` / `CHANGED` (`vne:turns:*`); payload `{ id, owner }` (`UNSET` — `{ id }`); state — map `id → owner` (параллельные партии). `STATE.SET` / `CLEAR` диффят map через `SET` / `UNSET`.
+- `game/checkers` — `turn` / `winner` убраны из state и `BOARD_CHANGE` / `BOARD_CHANGED` / `BOARD_GET`; ход через `TURNS.*`; победа через `FINISH` `{ winner }` (`CheckersFinishPayload`). API: `CONST.CHECKERS.TURN_ID` (`"checkers"`); `CONST.CHECKERS.COLORS` / `COLOR_VALUES` (бывшие `AI_COLORS` / `AI_COLOR_VALUES`); тип `CheckersColor` (бывший `CheckersAiColor`).
+- `views.screens/checkers` / `ai/checkers` — `turn` с `TURNS.CHANGED` / `UNSET`; `winner` с `CHECKERS.FINISH` / сброс на `SHOW`; `BOARD_CHANGED` / `STATE_UPDATE` только `board`. View: `checkers_view.status` (status text).
+- `bundles/checkers` — импорт `@vnejs/plugins.common.turn`.
+
+## 0.2.38
+
+- `ai/checkers` — ключи алгоритмов с префиксом домена: `CONST.CHECKERS_AI.AI_TYPES` → `checkers:sacrifice` / `checkers:random` / `checkers:strong` (вместо `sacrifice` / `random` / `strong`). `$ checkers.ai set <color> checkers:strong`.
+- `ai/checkers` — дефолтные алгоритмы `checkers:sacrifice` / `checkers:random` / `checkers:strong` регистрируются в `PARAMS.AI.ALGORITHMS` при загрузке контракта (side-effect, как `SCALE_MANA` → `PARAMS.SCALES.TYPES`). Больше не задаются в `games/checkers` scripts. API: экспорт `CheckersAiArgs`, `sacrifice` / `random` / `strong`.
+- `ai/checkers` — AI-оркестрация шашек вынесена из `game/checkers` в `@vnejs/plugins.ai.checkers` (`PLUGIN_NAME` `CHECKERS_AI`). API: `EVENTS.CHECKERS_AI.INTERACT` / `SET` / `UNSET` (`vne:checkers_ai:*`); `CONST.CHECKERS_AI.SOURCE` (`"checkers.ai.interact"`); `CONST.CHECKERS_AI.EXEC_ACTIONS` / `AI_TYPES`; `PARAMS.CHECKERS_AI.AI_DELAY`; `shared.checkersAi`; модули `checkers.ai` / `checkers.ai.start` / `checkers.ai.interact` / `checkers.ai.move.played`. Вместо `EVENTS.CHECKERS.AI_INTERACT` / `AI_SET` / `AI_UNSET`, `PARAMS.CHECKERS.AI_DELAY`, `CONST.CHECKERS.AI_EXEC_ACTIONS` / `AI_TYPES`, модулей `checkers.ai.show` / `checkers.move.played`. `$ checkers.ai` без изменения синтаксиса. Бандл: `@vnejs/plugins.ai.checkers`.
+- `game/checkers` — только правила / доска / ходы / `$ checkers`; цвета `AI_COLORS` / `AI_COLOR_VALUES` и `shared.checkersInteractDisableSources` остаются здесь.
+- `game/checkers` — `BOARD_CHANGE` / `BOARD_CHANGED` / `BOARD_GET` без `ai`; конфиг сторон только в `shared.checkersAi` (`AI_SET` / `AI_UNSET`).
+- `views.screens/checkers` — ACCEPT больше не эмитит `CHECKERS.FINISH` (только выбор клетки).
+- `game/checkers` — `PARAMS.CHECKERS.FINISH_DELAY` вместо `TRANSITION` для паузы на `FINISH`.
+- `views.screens/checkers` — `EVENTS.CHECKERS_VIEW.PLAYER_SELECT` / `CheckersPlayerSelectPayload`; модуль `checkers_view.player.select` (бывший `patchSelection`).
+- `game/checkers` — `MOVE_PLAY` сам эмитит `MOVE_PLAYED` `{ move, … }` или при победе `FINISH`; call-sites больше не шлют `MOVE_PLAYED` вручную. API: `CheckersMovePlayPayload` = `CheckersMovePlayedPayload` + `move`.
+- `views.screens/checkers` — `statusText` только во view (из `turn`/`winner` на `BOARD_CHANGED`); game модель без `statusText`.
+- `game/checkers` / `views.screens/checkers` — `selected` / `legalMoves` только во view (`CHECKERS_VIEW.STATE_UPDATE`); `BOARD_CHANGE` / `BOARD_CHANGED` без них.
+- `game/checkers` — правила / AI / `$ checkers` выделены из `views.screens/checkers` в `@vnejs/plugins.game.checkers` (`PLUGIN_NAME` `CHECKERS`). API: `EVENTS.CHECKERS.BOARD_CHANGED` / `BOARD_GET`; `PARAMS.CHECKERS.TRANSITION` (settle на `FINISH`); init доски на `SHOW` (`checkers.show`) → `START`. `PLAYER_INTERACT` убран из game.
+- `views.screens/checkers` — только UI: `PLUGIN_NAME` `CHECKERS_VIEW`; события `vne:checkers_view:*`; `EVENTS.CHECKERS_VIEW.PLAYER_INTERACT` / `CLICK` / grid; bridge SHOW/HIDE; зеркало `BOARD_CHANGED` → grid. `player.interact` ходит в game через `MOVES_GET` / `MOVE_PLAY` / `BOARD_CHANGE`.
+- `bundles/checkers` — импорт `@vnejs/plugins.game.checkers` + `@vnejs/plugins.views.screens.checkers`.
+- `ai/ai` — диспетчер: `emitOne(EVENTS.AI.EMIT, { type, args })` → `PARAMS.AI.ALGORITHMS[type](args, module)`. Дефолт `PARAMS.AI.ALGORITHMS` — `{}`. API: `EVENTS.AI.EMIT`, `PARAMS.AI.ALGORITHMS`, `CONST.AI.PLAYER_TYPE` (`"player"`), типы `AiAlgorithm` / `AiAlgorithmContext` / `AiEmitPayload` (`type` вместо `id`).
+- `views.screens/checkers` — (до сплита) `EVENTS.CHECKERS.MOVES_GET` / `MOVE_PLAY` / `MOVE_PLAYED` / `BOARD_CHANGE` / `PLAYER_INTERACT` / `AI_SET` / `AI_UNSET` / `AI_INTERACT` / `START`; `CONST.CHECKERS.AI_COLOR_VALUES` / `AI_EXEC_ACTIONS` / `EXEC_ACTIONS` (`show` / `hide`); модули `checkers.board`, `checkers.moves`, `checkers.move.play`, `checkers.move.played`, `checkers.player.interact`, `checkers.ai`, `checkers.ai.interact`, `checkers.ai.show`, `checkers.click`, `checkers.finish`, `checkers.controller.accept`. Алгоритмы в `games/checkers`. `$ checkers.ai set|unset` вместо `$ checkers ai`; `$ checkers show` без `emitNext` (сценарий ждёт `FINISH`); `$ checkers hide` → `HIDE` + `emitNext`. `FINISH` без `HIDE`. Удалён локальный `utils/ai` / `pickMove`. API: `EVENTS.CHECKERS.PLAYER_INTERACT`, `CheckersPlayerInteractPayload`; `EVENTS.CHECKERS.CLICK` вместо `CELL_CLICK` (`vne:checkers:click`) → `GRID_CLEAR` + `PLAYER_INTERACT`; `EVENTS.CHECKERS.AI_SET` / `CheckersAiSetPayload`; `EVENTS.CHECKERS.AI_UNSET` / `CheckersAiUnsetPayload` (`color`); `$ checkers.ai unset <color>` → сторона в `CONST.AI.PLAYER_TYPE`; `CONST.CHECKERS.AI_EXEC_ACTIONS` (`set` / `unset`); `CONST.AI.PLAYER_TYPE` вместо `CONST.CHECKERS.AI_TYPES.PLAYER`; `EVENTS.CHECKERS.START` (`afterShow`) → `AI_INTERACT` (`checkers.ai.show`); `EVENTS.CHECKERS.AI_INTERACT` вместо `AI_TURN`; `EVENTS.CHECKERS.MOVE_PLAYED` / `CheckersMovePlayedPayload` (`controllerType`); после хода `MOVE_PLAY` / `AI.EMIT` → `MOVE_PLAYED` → `AI_INTERACT` (`checkers.move.played`); `shared.checkersInteractDisableSources` (`SourcesSet`) вместо `checkersAiBusy` (source = `this.name` у `checkers.ai.interact`); вызов `AI.EMIT` с `{ type, args }`.
+- `bundles/checkers` — подключает `@vnejs/plugins.ai`.
+
 ## 0.2.36
 
 - `views.screens/checkers` — экран русских шашек: `$ checkers show`, сетка на `@vnejs/module.controller.arrows.grid`. API: `EVENTS.CHECKERS.*` (`SHOW` / `HIDE` / `ACCEPT` / `CELL_CLICK` / `FINISH` / `AI_TURN` / grid), `PARAMS.CHECKERS.ROWS` / `COLUMNS`, `CONST.CHECKERS.EXEC_ACTIONS`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vnejs/docs",
-  "version": "0.2.37",
+  "version": "0.2.39",
   "description": "VNEJS documentation for engine consumers and coding agents",
   "files": [
     "*.md",

package/plugins/ai/ai.md

@@ -0,0 +1,75 @@
+# plugins/ai/ai/
+
+Пакет: `@vnejs/plugins.ai` · namespace: `AI`
+
+Универсальный диспетчер AI-алгоритмов: `emitOne(EVENTS.AI.EMIT, { type, args })` вызывает `PARAMS.AI.ALGORITHMS[type](args, module)`. Доменные стратегии подключают свои контракты (side-effect на `PARAMS.AI.ALGORITHMS`), как [`ai/checkers`](./checkers.md).
+
+## События
+
+| Ключ   | Строка        | Смысл                                                   |
+| ------ | ------------- | ------------------------------------------------------- |
+| `EMIT` | `vne:ai:emit` | Request/response (`emitOne`): payload `{ type, args }`. |
+
+```ts
+emitOne(EVENTS.AI.EMIT, { type, args });
+// → PARAMS.AI.ALGORITHMS[type](args, module) ?? null
+```
+
+| Поле   | Тип       | Смысл                                          |
+| ------ | --------- | ---------------------------------------------- |
+| `type` | `string`  | Ключ в `PARAMS.AI.ALGORITHMS`.                 |
+| `args` | `unknown` | Произвольный payload для выбранного алгоритма. |
+
+Второй аргумент алгоритма — модуль AI (`emit` / `emitOne` / `emitReal`), как у settings ACTIONS.
+
+Результат: значение из алгоритма или `null` (нет `type` / нет функции / алгоритм вернул `null`). Поддерживается `async`.
+
+## Константы
+
+| Ключ          | Тип / значение | Смысл                                                              |
+| ------------- | -------------- | ------------------------------------------------------------------ |
+| `PLAYER_TYPE` | `"player"`     | Тип контроллера «человек» (не алгоритм из `PARAMS.AI.ALGORITHMS`). |
+
+## Параметры
+
+| Ключ         | Тип / дефолт                         | Смысл                                                                |
+| ------------ | ------------------------------------ | -------------------------------------------------------------------- |
+| `ALGORITHMS` | `Record<string, AiAlgorithm>` → `{}` | Карта type → `(args, module) => result \| null`. Пусто по умолчанию. |
+
+```ts
+type AiAlgorithmContext = Pick<Module, "emit" | "emitOne" | "emitReal">;
+type AiAlgorithm<TArgs = unknown, TResult = unknown> = (args: TArgs, module: AiAlgorithmContext) => TResult | null | Promise<TResult | null>;
+type AiEmitPayload<TArgs = unknown> = { type?: string; args?: TArgs };
+```
+
+## Модули
+
+| Модуль    | Зона ответственности                                               |
+| --------- | ------------------------------------------------------------------ |
+| `ai.emit` | `on(EVENTS.AI.EMIT)` → `PARAMS.AI.ALGORITHMS[type]?.(args, this)`. |
+
+## Регистрация алгоритмов
+
+Доменный контракт мутирует `PARAMS.AI.ALGORITHMS` при загрузке (как `SCALE_MANA` → `PARAMS.SCALES.TYPES`):
+
+```ts
+import { PARAMS as AI_PARAMS } from "@vnejs/contracts.ai";
+
+AI_PARAMS.ALGORITHMS["checkers:sacrifice"] = sacrifice;
+AI_PARAMS.ALGORITHMS["checkers:random"] = random;
+AI_PARAMS.ALGORITHMS["checkers:strong"] = strong;
+```
+
+Шашечные `checkers:sacrifice` / `checkers:random` / `checkers:strong` — в [`ai/checkers`](./checkers.md). Игра может добавить свои ключи тем же способом или в скриптах.
+
+Вызывающая сторона (например `ai/checkers`):
+
+```ts
+await this.emitOne(this.EVENTS.AI.EMIT, { type, args: { board, turn, controllerType: type } });
+```
+
+## Близкие плагины
+
+- [ai/checkers.md](./checkers.md) — оркестрация шашек: `CHECKERS_AI.INTERACT` → `AI.EMIT`.
+- [game/checkers.md](../game/checkers.md) — правила: `MOVES_GET` / `MOVE_PLAY`.
+- [views.screens/checkers.md](../views.screens/checkers.md) — экран `CHECKERS_VIEW`.

package/plugins/ai/checkers.md

@@ -0,0 +1,58 @@
+# plugins/ai/checkers/
+
+Пакет: `@vnejs/plugins.ai.checkers` · namespace: `CHECKERS_AI`
+
+AI-оркестрация русских шашек: конфиг сторон, цикл хода через `AI.EMIT`, `$ checkers.ai`, дефолтные алгоритмы `checkers:sacrifice` / `checkers:random` / `checkers:strong`. Правила доски — в [`game/checkers`](../game/checkers.md); UI — в [`views.screens/checkers`](../views.screens/checkers.md); диспетчер — в [`ai/ai`](./ai.md).
+
+## События
+
+| Ключ       | Строка                     | Смысл                                   |
+| ---------- | -------------------------- | --------------------------------------- |
+| `INTERACT` | `vne:checkers_ai:interact` | Ход AI (если сторона не `player`).      |
+| `SET`      | `vne:checkers_ai:set`      | `$ checkers.ai set`: `{ color, type }`. |
+| `UNSET`    | `vne:checkers_ai:unset`    | `$ checkers.ai unset <color>`.          |
+
+Слушает `CHECKERS.START` → `INTERACT`; `CHECKERS.MOVE_PLAYED` → unlock + `INTERACT`. Сторона хода — с `TURNS.CHANGED` / `TURNS.UNSET`; победитель — с `CHECKERS.FINISH` / сброс на `SHOW`; `board` — с `GRID.CHANGED` / `GRID.UNSET` (`cells`, фильтр `CONST.CHECKERS.GRID_ID`).
+
+## Константы / Shared / Params
+
+| Ключ                                          | Смысл                                                                   |
+| --------------------------------------------- | ----------------------------------------------------------------------- |
+| `CONST.CHECKERS_AI.SOURCE`                    | `"checkers.ai.interact"` — ключ в `SourcesSet`                          |
+| `CONST.CHECKERS_AI.EXEC_ACTIONS` / `AI_TYPES` | set/unset; `checkers:sacrifice` / `checkers:random` / `checkers:strong` |
+| `shared.checkersAi`                           | `{ white, black }` → оба `player` по умолчанию                          |
+| `PARAMS.CHECKERS_AI.AI_DELAY`                 | пауза перед ходом AI (мс, `1000`)                                       |
+
+Busy-флаг пишется в `shared.checkersInteractDisableSources` (владелец — `CHECKERS`).
+
+Цвета сторон (`CONST.CHECKERS.COLORS`) — в контракте game.
+
+При загрузке контракта в `PARAMS.AI.ALGORITHMS` регистрируются `checkers:sacrifice` / `checkers:random` / `checkers:strong` (мутация как у `SCALE_MANA` → `PARAMS.SCALES.TYPES`).
+
+## Модули
+
+| Модуль                    | Зона                                               |
+| ------------------------- | -------------------------------------------------- |
+| `checkers.ai`             | `$ checkers.ai set/unset` → `SET` / `UNSET`        |
+| `checkers.ai.start`       | `CHECKERS.START` → `INTERACT`                      |
+| `checkers.ai.interact`    | `INTERACT` → delay → `AI.EMIT` (source = `SOURCE`) |
+| `checkers.ai.move.played` | `CHECKERS.MOVE_PLAYED` → `rm(SOURCE)` → `INTERACT` |
+
+## Сценарий
+
+```vne
+$ checkers.ai set white checkers:strong
+$ checkers.ai set black player
+```
+
+## Бандл
+
+`@vnejs/bundles.checkers` — `plugins.common.grid` + `plugins.common.turn` + `plugins.ai` + `plugins.ai.checkers` + `plugins.game.checkers` + `plugins.views.screens.checkers`.
+
+## Близкие плагины
+
+- [common/grid.md](../common/grid.md) — `GRID` (доска)
+- [common/turn.md](../common/turn.md) — `TURNS` (`id` / `owner`)
+- [ai/ai.md](./ai.md) — `EVENTS.AI.EMIT` / `PARAMS.AI.ALGORITHMS`
+- [game/checkers.md](../game/checkers.md) — правила, `START` / `MOVE_PLAYED`
+- [views.screens/checkers.md](../views.screens/checkers.md) — UI, gate по `SourcesSet`

package/plugins/common/grid.md

@@ -0,0 +1,39 @@
+# plugins/common/grid/
+
+Пакет: `@vnejs/plugins.common.grid` · namespace: `GRID`
+
+Хранит квадратные сетки по строковому `id` (несколько параллельных досок). Элемент клетки — любой объект с обязательным `id: string`; в одной сетке `id` уникален. Пустая клетка — `null`. Матрица — плотная `(item | null)[][]`.
+
+Не путать с UI-навигацией `*.GRID_*` из `@vnejs/module.controller.arrows.grid` (фокус стрелками на экране).
+
+## События
+
+| Ключ      | Строка             | Смысл                                                                                             |
+| --------- | ------------------ | ------------------------------------------------------------------------------------------------- |
+| `SET`     | `vne:grid:set`     | Создать/заменить `{ id, rows, columns, cells? }`. Без `cells` — пустая матрица. Затем `CHANGED`.  |
+| `GET`     | `vne:grid:get`     | `emitOne({ id })` → `{ id, rows, columns, cells } \| undefined`.                                  |
+| `UNSET`   | `vne:grid:unset`   | Удалить по `{ id }`. Без `CHANGED`.                                                               |
+| `CHANGED` | `vne:grid:changed` | Полный снимок после `SET` / `PUT` / `MOVE` / `REMOVE`.                                            |
+| `PUT`     | `vne:grid:put`     | `{ id, row, column, item }` — положить item; тот же `item.id` сначала снимается со старой клетки. |
+| `MOVE`    | `vne:grid:move`    | `{ id, from, to }` — перенос; занятый `to` — замена.                                              |
+| `REMOVE`  | `vne:grid:remove`  | `{ id, row?, column?, itemId? }` — очистить по позиции или по `itemId`.                           |
+
+State: map `id → { rows, columns, cells }`.
+
+`STATE.SET` / `STATE.CLEAR` не пишут map напрямую: отсутствующие id — `UNSET`, присутствующие — `SET`.
+
+## Константы / Params / Settings
+
+Нет.
+
+## Модули
+
+| Модуль | Зона ответственности                                             |
+| ------ | ---------------------------------------------------------------- |
+| `grid` | `SET` / `GET` / `UNSET` / `CHANGED` / `PUT` / `MOVE` / `REMOVE`. |
+
+## Близкие плагины
+
+- [game/checkers.md](../game/checkers.md) — пишет `GRID.SET` с `CONST.CHECKERS.GRID_ID`, читает через `GET`
+- [views.screens/checkers.md](../views.screens/checkers.md) / [ai/checkers.md](../ai/checkers.md) — зеркало через `CHANGED` / `UNSET`
+- [common/turn.md](./turn.md) — ход стороны (отдельный map)

package/plugins/common/turn.md

@@ -0,0 +1,33 @@
+# plugins/common/turn/
+
+Пакет: `@vnejs/plugins.common.turn` · namespace: `TURNS`
+
+Хранит текущий ход по строковому `id` (несколько параллельных партий) и `owner` (кто ходит — произвольная строка).
+
+## События
+
+| Ключ      | Строка              | Смысл                                                       |
+| --------- | ------------------- | ----------------------------------------------------------- |
+| `SET`     | `vne:turns:set`     | Записать `{ id, owner }`. Без `id` или без `owner` — no-op. |
+| `GET`     | `vne:turns:get`     | `emitOne({ id })` → `owner` (`string \| undefined`).        |
+| `UNSET`   | `vne:turns:unset`   | Удалить запись по `{ id }`.                                 |
+| `CHANGED` | `vne:turns:changed` | После успешного `SET`: `{ id, owner }`.                     |
+
+State: map `id → owner`.
+
+`STATE.SET` / `STATE.CLEAR` не пишут map напрямую: для новых и изменённых id — `TURNS.SET`, для удалённых — `TURNS.UNSET`.
+
+## Константы / Params / Settings
+
+Нет.
+
+## Модули
+
+| Модуль  | Зона ответственности                 |
+| ------- | ------------------------------------ |
+| `turns` | `SET` / `GET` / `UNSET` / `CHANGED`. |
+
+## Близкие плагины
+
+- [game/checkers.md](../game/checkers.md) — пишет `TURNS.SET` с `CONST.CHECKERS.TURN_ID`, читает через `GET`; доска — через [`common/grid`](./grid.md)
+- [views.screens/checkers.md](../views.screens/checkers.md) / [ai/checkers.md](../ai/checkers.md) — зеркало через `CHANGED` / `UNSET`

package/plugins/game/checkers.md

@@ -0,0 +1,70 @@
+# plugins/game/checkers/
+
+Пакет: `@vnejs/plugins.game.checkers` · namespace: `CHECKERS`
+
+Правила русских шашек и сценарные команды `$ checkers`. AI-оркестрация — в [`ai/checkers`](../ai/checkers.md) (`CHECKERS_AI`). UI — в [`views.screens/checkers`](../views.screens/checkers.md) (`CHECKERS_VIEW`). Доска — в [`common/grid`](../common/grid.md) (`GRID`). Ход стороны — в [`common/turn`](../common/turn.md) (`TURNS`).
+
+## События
+
+| Ключ           | Строка                      | Смысл                                                                                              |
+| -------------- | --------------------------- | -------------------------------------------------------------------------------------------------- |
+| `SHOW`         | `vne:checkers:show`         | Старт: `SET` (`cells` + `owner`) → `START`. Payload: `{ initialOwner?, initialPreset? }`.          |
+| `HIDE`         | `vne:checkers:hide`         | `UNSET` + сброс busy sources.                                                                      |
+| `START`        | `vne:checkers:start`        | Партия готова (слушает `CHECKERS_AI` → `INTERACT`).                                                |
+| `SET`          | `vne:checkers:set`          | `{ cells, owner }` → `GRID.SET` + `TURNS.SET` (id / rows / columns из констант).                   |
+| `UNSET`        | `vne:checkers:unset`        | `GRID.UNSET` + `TURNS.UNSET` по `GRID_ID` / `TURN_ID`.                                             |
+| `STATE_UPDATE` | `vne:checkers:state_update` | Патч game-стейта (без board).                                                                      |
+| `FINISH`       | `vne:checkers:finish`       | Конец партии: `{ winner }` → delay → `sources.clear()` + `emitNext`.                               |
+| `MOVES_GET`    | `vne:checkers:moves_get`    | `emitOne`: `{ board, turn }` → `{ moves, hanging, safe }`.                                         |
+| `MOVE_PLAY`    | `vne:checkers:move_play`    | `emitOne`: `{ move, controllerType? }` → `boolean`; успех → `MOVE_PLAYED` или при победе `FINISH`. |
+| `MOVE_PLAYED`  | `vne:checkers:move_played`  | После хода (из `MOVE_PLAY`); цикл AI — в `CHECKERS_AI`.                                            |
+
+`MOVE_PLAY` читает доску через `GRID.GET` и сторону через `TURNS.GET`; после хода пишет `CHECKERS.SET`. Победа — только через `FINISH` (`CheckersFinishPayload`).
+
+## Константы / Shared / Params
+
+| Ключ                                       | Смысл                                                                      |
+| ------------------------------------------ | -------------------------------------------------------------------------- |
+| `EXEC_ACTIONS` / `COLORS` / `COLOR_VALUES` | show/hide; white/black                                                     |
+| `CONST.CHECKERS.TURN_ID`                   | `"checkers"` — id в `TURNS`                                                |
+| `CONST.CHECKERS.GRID_ID`                   | `"checkers"` — id в `GRID`                                                 |
+| `shared.checkersInteractDisableSources`    | `SourcesSet` — блок интерактива на ход AI                                  |
+| `PARAMS.CHECKERS.FINISH_DELAY`             | пауза перед `emitNext` на `FINISH` (мс, `300`)                             |
+| `PARAMS.CHECKERS.ROWS` / `COLUMNS`         | `8` — размер для `GRID.SET` (внутри `SET`)                                 |
+| `PARAMS.CHECKERS.PRESETS`                  | пресеты доски: `COMMON`, `FLIPPED`, `RANDOM` (RANDOM каждый `SHOW` заново) |
+
+## Модули
+
+| Модуль                                  | Зона                                                   |
+| --------------------------------------- | ------------------------------------------------------ |
+| `checkers`                              | `$ checkers show/hide`                                 |
+| `checkers.show`                         | SHOW → `SET` + START; HIDE → `UNSET`                   |
+| `checkers.set`                          | `SET` → `GRID`/`TURNS`; `UNSET` → `GRID`/`TURNS` UNSET |
+| `checkers.moves` / `checkers.move.play` | ходы; `move.play` → `SET` / `FINISH`                   |
+| `checkers.finish`                       | FINISH → delay + `emitNext`                            |
+
+## Сценарий
+
+```vne
+$ checkers show
+$ checkers show
+  initialOwner: black
+  initialPreset: COMMON
+$ checkers hide
+```
+
+Args под `show`: `initialOwner` (`white` / `black`, иначе белые); `initialPreset` (ключ из `PARAMS.CHECKERS.PRESETS`, дефолт `COMMON`).
+
+`$ checkers.ai` — см. [`ai/checkers`](../ai/checkers.md).
+
+## Бандл
+
+`@vnejs/bundles.checkers` — `plugins.common.grid` + `plugins.common.turn` + `plugins.game.checkers` + `plugins.ai.checkers` + `plugins.views.screens.checkers` + `plugins.ai`.
+
+## Близкие плагины
+
+- [common/grid.md](../common/grid.md) — `GRID` (доска)
+- [common/turn.md](../common/turn.md) — `TURNS` (`id` / `owner`)
+- [ai/checkers.md](../ai/checkers.md) — `CHECKERS_AI`
+- [views.screens/checkers.md](../views.screens/checkers.md) — `CHECKERS_VIEW`
+- [ai/ai.md](../ai/ai.md) — диспетчер `AI.EMIT`

package/plugins/views.screens/checkers.md

@@ -1,102 +1,53 @@
 # plugins/views.screens/checkers/
 
-Пакет: `@vnejs/plugins.views.screens.checkers` · namespace: `CHECKERS`
+Пакет: `@vnejs/plugins.views.screens.checkers` · namespace: `CHECKERS_VIEW`
 
-Экран русских шашек: доска 8×8, навигация стрелками через `@vnejs/module.controller.arrows.grid`, ход через ACCEPT / клик. Стороны — игрок или AI (`player` / `sacrifice` / `random` / `strong`) через `$ checkers ai`.
+Экран русских шашек: доска 8×8, сетка, клик / ACCEPT. Правила — в [`game/checkers`](../game/checkers.md) (`CHECKERS`); AI — в [`ai/checkers`](../ai/checkers.md) (`CHECKERS_AI`).
 
-## События
-
-| Ключ                | Строка                           | Смысл                                       |
-| ------------------- | -------------------------------- | ------------------------------------------- |
-| `SHOW`              | `vne:checkers:show`              | Показать экран и начать партию.             |
-| `HIDE`              | `vne:checkers:hide`              | Скрыть экран.                               |
-| `UPDATE`            | `vne:checkers:update`            | Обновить React-view.                        |
-| `UPDATE_FAST`       | `vne:checkers:update_fast`       | Быстрый апдейт view (фокус сетки).          |
-| `ACCEPT`            | `vne:checkers:accept`            | Выбор фигуры / клетки / закрытие после win. |
-| `STATE_UPDATE`      | `vne:checkers:state_update`      | Патч стейта (доска, ход, сетка).            |
-| `GRID_NEXT`         | `vne:checkers:grid_next`         | Край сетки (отключён флагами).              |
-| `GRID_PREV`         | `vne:checkers:grid_prev`         | Край сетки (отключён флагами).              |
-| `GRID_CLEAR`        | `vne:checkers:grid_clear`        | Сброс `gridRow` / `gridColumn`.             |
-| `GRID_UPDATE_ITEMS` | `vne:checkers:grid_update_items` | Пересобрать `gridItems` (64 клетки).        |
-| `CELL_CLICK`        | `vne:checkers:cell_click`        | Клик по клетке → фокус + ACCEPT.            |
-| `FINISH`            | `vne:checkers:finish`            | Конец партии → HIDE + `emitNext`.           |
-| `AI_TURN`           | `vne:checkers:ai_turn`           | Ход AI (после SHOW / хода человека).        |
-
-## Константы
-
-| Ключ           | Смысл                                         |
-| -------------- | --------------------------------------------- |
-| `EXEC_ACTIONS` | `SHOW` → `"show"`, `AI` → `"ai"`.             |
-| `AI_COLORS`    | `WHITE` / `BLACK` → `"white"` / `"black"`.    |
-| `AI_TYPES`     | `PLAYER` / `SACRIFICE` / `RANDOM` / `STRONG`. |
+Bridge: `CHECKERS.SHOW/HIDE` → `CHECKERS_VIEW.SHOW/HIDE`. Модель доски зеркалится с `GRID.CHANGED` / `GRID.UNSET` (`cells` → `board`, фильтр `CONST.CHECKERS.GRID_ID`); сторона хода — с `TURNS.CHANGED` / `TURNS.UNSET`; победитель — с `CHECKERS.FINISH` `{ winner }` (сброс на `SHOW`).
 
-## Shared
+## События
 
-| Ключ             | Тип / дефолт                      | Смысл                                 |
-| ---------------- | --------------------------------- | ------------------------------------- |
-| `checkersAi`     | `{ white, black }` → оба `player` | Тип управления стороной.              |
-| `checkersAiBusy` | `boolean` → `false`               | Пока AI ходит — игнор ACCEPT / клика. |
+| Ключ                     | Строка                               | Смысл                                                                    |
+| ------------------------ | ------------------------------------ | ------------------------------------------------------------------------ |
+| `SHOW` / `HIDE`          | `vne:checkers_view:show` / `…:hide`  | Показ / скрытие экрана.                                                  |
+| `UPDATE` / `UPDATE_FAST` | `vne:checkers_view:update` / `_fast` | React-view.                                                              |
+| `ACCEPT`                 | `vne:checkers_view:accept`           | Выбор клетки → `GRID_CLEAR` + `PLAYER_INTERACT`.                         |
+| `STATE_UPDATE`           | `vne:checkers_view:state_update`     | Патч view-стейта (grid + зеркало доски).                                 |
+| `GRID_*`                 | `vne:checkers_view:grid_*`           | Навигация сетки.                                                         |
+| `CLICK`                  | `vne:checkers_view:click`            | Клик → `GRID_CLEAR` + `PLAYER_INTERACT`.                                 |
+| `PLAYER_INTERACT`        | `vne:checkers_view:player_interact`  | UX выбора фигуры / клетки → `MOVES_GET` / `MOVE_PLAY` / `PLAYER_SELECT`. |
+| `PLAYER_SELECT`          | `vne:checkers_view:player_select`    | Патч `selected` / `legalMoves` → `gridItems` + `UPDATE_FAST`.            |
 
 ## Параметры
 
-| Ключ            | Тип      | Смысл                                                                   |
-| --------------- | -------- | ----------------------------------------------------------------------- |
-| `TRANSITION`    | `number` | Длительность анимаций экрана / клеток / фигур (мс), по умолчанию `300`. |
-| `AI_DELAY`      | `number` | Пауза перед ходом AI (мс), по умолчанию `1000`.                         |
-| `ZINDEX`        | `number` | z-index экрана.                                                         |
-| `ROWS`          | `number` | `8`.                                                                    |
-| `COLUMNS`       | `number` | `8`.                                                                    |
-| `CELL_SIZE`     | `number` | Размер клетки в design-единицах (`getVneLength`).                       |
-| `CELL_GAP`      | `number` | Зазор между клетками.                                                   |
-| `GRAVEYARD_GAP` | `number` | Отступ между доской и «кладбищем» взятых фигур.                         |
-| `VIEW_PROPS`    | `object` | Layout screen / status / flex. Доска — CSS grid 8×8 в view.             |
+| Ключ                                       | Смысл                                |
+| ------------------------------------------ | ------------------------------------ |
+| `TRANSITION`                               | анимации экрана / клеток (мс, `300`) |
+| `ZINDEX`                                   | z-index экрана                       |
+| `ROWS` / `COLUMNS`                         | `8`                                  |
+| `CELL_SIZE` / `CELL_GAP` / `GRAVEYARD_GAP` | layout доски                         |
+| `VIEW_PROPS`                               | layout screen / status / flex        |
 
 ## Модули
 
-| Модуль                       | Зона ответственности                                                                                            |
-| ---------------------------- | --------------------------------------------------------------------------------------------------------------- |
-| `checkers.controller`        | SHOW/HIDE; `beforeShow` — стартовая доска + снимок `shared.checkersAi` в state; `FINISH` → HIDE + next.         |
-| `checkers.controller.grid`   | `@vnejs/module.controller.arrows.grid`, 8×8, оба `isDisableGridChange* = true`.                                 |
-| `checkers.controller.accept` | Выбор фигуры / ход / клик; после SHOW ждёт доску и эмитит `AI_TURN`; AI-цикл; победа → `FINISH`.                |
-| `checkers`                   | `$ checkers show` → SHOW; `$ checkers ai <color> <type>` → `shared.checkersAi`.                                 |
-| `checkers.view`              | React: доска (`vne-cursor-type` на клетках), фокус, подсветка; анимации; кладбище (белые слева, чёрные справа). |
-
-## AI-типы
-
-| Ключ        | Поведение                                                                  |
-| ----------- | -------------------------------------------------------------------------- |
-| `player`    | ход человеком                                                              |
-| `sacrifice` | среди ходов, после которых у противника есть взятие; иначе любой легальный |
-| `random`    | любой легальный ход                                                        |
-| `strong`    | среди ходов без ответа-взятия; если таких нет — среди «подставляющих»      |
+| Модуль                                           | Зона                                                   |
+| ------------------------------------------------ | ------------------------------------------------------ |
+| `checkers_view.bridge`                           | SHOW/HIDE bridge                                       |
+| `checkers_view.controller` / `.grid` / `.accept` | экран, сетка, ACCEPT                                   |
+| `checkers_view.click` / `.player.interact`       | клик и выбор (game: `MOVES_GET` / `MOVE_PLAY`)         |
+| `checkers_view.player.select`                    | `PLAYER_SELECT` → selection + grid                     |
+| `checkers_view.board`                            | `GRID.CHANGED` / `UNSET` → `gridItems` + `UPDATE_FAST` |
+| `checkers_view.status`                           | `TURNS` / `FINISH` / `SHOW` → status text              |
+| `checkers_view.view`                             | React                                                  |
 
 ## Сценарий
 
-```vne
-% choose
-  title: "Кто управляет белыми?"
-  % choose.option "Игрок"
-    $ checkers ai white player
-  % choose.option "Слабый ИИ"
-    $ checkers ai white sacrifice
-  % choose.option "Средний ИИ"
-    $ checkers ai white random
-  % choose.option "Сильный ИИ"
-    $ checkers ai white strong
-% choose
-  title: "Кто управляет чёрными?"
-  % choose.option "Игрок"
-    $ checkers ai black player
-  % choose.option "Слабый ИИ"
-    $ checkers ai black sacrifice
-  % choose.option "Средний ИИ"
-    $ checkers ai black random
-  % choose.option "Сильный ИИ"
-    $ checkers ai black strong
-$ checkers show
-```
+`$ checkers` — [`game/checkers`](../game/checkers.md); `$ checkers.ai` — [`ai/checkers`](../ai/checkers.md).
 
-## Бандл и игра
+## Близкие плагины
 
-- Бандл: `@vnejs/bundles.checkers` (`bundles/checkers`) — core + `canvas.layer` + controls/keyboard/gamepad/cursor + `text` + choose + `views.cursor` + этот плагин.
-- Тестовая игра: `games/checkers` — `npm run start` / `npm run dev`; иконки курсора — `media/icons/original-4k/cursor/default` (как у Coraline).
+- [common/grid.md](../common/grid.md) — `GRID` (доска)
+- [common/turn.md](../common/turn.md) — `TURNS` (`id` / `owner`)
+- [game/checkers.md](../game/checkers.md) — правила
+- [ai/checkers.md](../ai/checkers.md) — AI