@vnejs/docs 0.2.35 → 0.2.37

package/CHANGELOG.md

@@ -2,8 +2,24 @@
 
 Краткая история изменений движка (плагины, helpers, packages, CLI и прочий runtime) и внешнего API. Версии — релизы пакета `@vnejs/docs`.
 
+## 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`.
+- `views.screens/checkers` — AI сторон: `$ checkers ai <white|black> <player|sacrifice|random|strong>`; конфиг в `shared.checkersAi` (дефолт оба `player`), на SHOW копируется в state `ai`; AI vs AI стартует после готовности доски. `playMove` всегда ищет ход через `getAllMoves` (пустой `legalMoves: []` больше не блокирует AI). Пауза перед ходом AI: `PARAMS.CHECKERS.AI_DELAY` (1000мс). API: `CONST.CHECKERS.AI_COLORS`, `CONST.CHECKERS.AI_TYPES`, `EVENTS.CHECKERS.AI_TURN`, `PARAMS.CHECKERS.AI_DELAY`, `shared.checkersAi`, `shared.checkersAiBusy`.
+- `views.screens/checkers` — клетки доски: `vne-cursor-type="pointer"` вместо CSS `cursor`.
+- `views.screens/checkers` — доска CSS grid 8×8; размер клеток через `getVneLength(PARAMS.CHECKERS.CELL_SIZE)`, без flex-wrap (раньше клетки были в px и ряд ломался на ~6).
+- `views.screens/checkers` — анимации `PARAMS.CHECKERS.TRANSITION` (300мс): ход фигуры (`transform`), выбор (opacity 70%), взятие — уезд на кладбище (белые слева, чёрные справа; `PARAMS.CHECKERS.GRAVEYARD_GAP`), смена цвета клетки. Позиции — `calc(n * cellLen)`, overlay вне grid-children.
+- `bundles/checkers` — бандл: core + `canvas.layer` + controls/keyboard/gamepad/cursor + `text` + choose + `views.cursor` + gamepad↔cursor + `views.screens/checkers`.
+- `games/checkers` — тестовая игра: два `% choose` с `title` (белые/чёрные) и опциями «Игрок» / «… ИИ» → `$ checkers show`; курсор из Coraline (`icons/original-4k/cursor/default`); скрипты `resize:*` / `build:media:cp` / vercel-target как у Coraline.
+- `views.scenario/choose` — опциональный заголовок из `args.title` (`title: "…"` у `% choose`); API: `PARAMS.CHOOSE_VIEW.VIEW_PROPS.title` / `wrap`.
+
 ## 0.2.35
 
+- `scenario/qte` — обработка `RESULT` в модуле `qte.result` (`CLOSED` + `applyResult` / `emitNext`); `qte` только `EMIT` → `OPENED` и `shared.qteScenarioSkip`.
+- `scenario/qte` — флаг embedded-режима: `shared.qteScenarioSkip` вместо поля модуля; в `postinject` — `false`. `qte.logs` читает тот же shared. API: `shared.qteScenarioSkip`.
+- `scenario/qte` — логи в модуле `qte.logs`, не `emitLog` из `qte`. `EMIT` / `RESULT` пишут `skipScenario` (для `RESULT` — с `shared.qteScenarioSkip`). `MISSING` — из `qte.scenario` через `CONST.QTE.LOGS_ACTIONS.MISSING`. API: `CONST.QTE.LOGS_ACTIONS` (`EMIT` / `emit`, `RESULT` / `result`, `MISSING` / `missing`).
+- `helpers/get-block-skip-shift` — `getBlockSkipShift(lines, curLine)` сдвигает курсор за indent-поддерево (`indent > parent`). Call-sites: `scenario/choose` / `point_and_click` (`*.skip`), `scenario/qte` (fail), `vars` (не заходить внутрь). Не путать с `getOptionExecShift` (`>=`, пропуск одной option-ветки).
+- `helpers/get-block-options` — `getBlockOptions(lines, curLine, optionPrefix)` собирает `% ….option` на `parentIndent + 2` внутри блока → `{ index, optionLine }[]`. Call-sites: `scenario/choose` / `point_and_click` / `random` (scenario).
 - `module.controller.arrows.grid` — `cachedItemsCount` не считает слоты с `isStub`; после `GRID_UPDATE_ITEMS` невалидные `gridRow` / `gridColumn` (в т.ч. stub после смены `gridIndex`) сдвигаются на ближайшую валидную ячейку. API: `getGridItemsCount`, `snapSelectionToGrid`, `findNearestValidCell`.
 - `views/settings` — константа ключа вкладки дефолтных настроек. API: `CONST.SETTINGS_VIEW.DEFAULT_TAB` (`"DEFAULT"`).
 - `views.screens/settings` — показ полей на `SHOW_BEFORE` в `settings.screen.controller.fields` (`STATE_UPDATE` tabs/tab → `SETTINGS_VIEW.SHOW`); main только эмитит `SHOW_BEFORE` и `HIDE` → `SETTINGS_VIEW.HIDE`.

package/package.json

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

package/plugins/scenario/choose.md

@@ -63,12 +63,12 @@
 | `choose`                 | State: `STATE_UPDATE`, синхронизация с `STATE.SET` / `STATE.CLEAR` (→ `SHOW` / `HIDE`). |
 | `choose.emit`            | Обрабатывает `EMIT` (→ `STATE_UPDATE` + `SHOW` или `SKIP`).                             |
 | `choose.option`          | Обрабатывает `OPTION`.                                                                  |
-| `choose.skip`            | Обрабатывает `SKIP`.                                                                    |
+| `choose.skip`            | Обрабатывает `SKIP` через `getBlockSkipShift`.                                          |
 | `choose.logs`            | Логирование `EMIT` / `OPTION` / `SKIP` / `SHOW` / `HIDE`.                               |
 | `choose.option.before`   | Реестр обработчиков `OPTION_BEFORE_REG`; наследник `@vnejs/module.handlers`.            |
 | `choose.replace`         | Реестр обработчиков `OPTION_REPLACE_REG`; наследник `@vnejs/module.replace`.            |
 | `choose.exec`            | Реестр обработчиков EXEC_REG / EXEC_GET.                                                |
-| `choose.scenario`        | Регистрация `% choose`: сбор option-строк, emit `EMIT`.                                 |
+| `choose.scenario`        | Регистрация `% choose`: сбор option-строк через `getBlockOptions`, emit `EMIT`.         |
 | `choose.scenario.option` | Регистрация `% choose.option`: skip невыбранных веток.                                  |
 | `choose.scenario.module` | Регистрация `$ choose`: action `repeat`.                                                |
 

package/plugins/scenario/point_and_click.md

@@ -54,17 +54,17 @@
 
 ## Модули
 
-| Модуль                            | Зона ответственности                                                                    |
-| --------------------------------- | --------------------------------------------------------------------------------------- |
-| `point_and_click`                 | State: `STATE_UPDATE`, синхронизация с `STATE.SET` / `STATE.CLEAR` (→ `SHOW` / `HIDE`). |
-| `point_and_click.emit`            | Обрабатывает `EMIT` (→ `STATE_UPDATE` + `SHOW` или `SKIP`).                             |
-| `point_and_click.option`          | Обрабатывает `OPTION`.                                                                  |
-| `point_and_click.skip`            | Обрабатывает `SKIP`.                                                                    |
-| `point_and_click.logs`            | Логирование `EMIT` / `OPTION` / `SKIP` / `SHOW` / `HIDE`.                               |
-| `point_and_click.exec`            | Реестр обработчиков EXEC_REG / EXEC_GET.                                                |
-| `point_and_click.scenario`        | Регистрация `% point-and-click`: сбор option-строк, emit `EMIT`.                        |
-| `point_and_click.scenario.option` | Регистрация `% point-and-click.option`: skip невыбранных веток.                         |
-| `point_and_click.scenario.module` | Регистрация `$ point-and-click`: action `repeat`.                                       |
+| Модуль                            | Зона ответственности                                                                     |
+| --------------------------------- | ---------------------------------------------------------------------------------------- |
+| `point_and_click`                 | State: `STATE_UPDATE`, синхронизация с `STATE.SET` / `STATE.CLEAR` (→ `SHOW` / `HIDE`).  |
+| `point_and_click.emit`            | Обрабатывает `EMIT` (→ `STATE_UPDATE` + `SHOW` или `SKIP`).                              |
+| `point_and_click.option`          | Обрабатывает `OPTION`.                                                                   |
+| `point_and_click.skip`            | Обрабатывает `SKIP` через `getBlockSkipShift`.                                           |
+| `point_and_click.logs`            | Логирование `EMIT` / `OPTION` / `SKIP` / `SHOW` / `HIDE`.                                |
+| `point_and_click.exec`            | Реестр обработчиков EXEC_REG / EXEC_GET.                                                 |
+| `point_and_click.scenario`        | Регистрация `% point-and-click`: сбор option-строк через `getBlockOptions`, emit `EMIT`. |
+| `point_and_click.scenario.option` | Регистрация `% point-and-click.option`: skip невыбранных веток.                          |
+| `point_and_click.scenario.module` | Регистрация `$ point-and-click`: action `repeat`.                                        |
 
 ## Compatibility
 

package/plugins/scenario/qte.md

@@ -17,7 +17,10 @@
 
 ## Константы
 
-- **`LINE_KEYWORDS.QTE_FALLBACK`** — `"qte-fallback"`: keyword на `% choose.option` для ветки fail QTE (через compatibility choose↔qte).
+| Ключ                         | Смысл                                                                                               |
+| ---------------------------- | --------------------------------------------------------------------------------------------------- |
+| `LINE_KEYWORDS.QTE_FALLBACK` | `"qte-fallback"`: keyword на `% choose.option` для ветки fail QTE (через compatibility choose↔qte). |
+| `LOGS_ACTIONS`               | Метки для логов: `EMIT` (`emit`), `RESULT` (`result`), `MISSING` (`missing`).                       |
 
 ## Параметры
 
@@ -41,10 +44,12 @@ View сам переводит проценты в геометрию (град
 
 ## Модули
 
-| Модуль         | Зона ответственности                                                                                                          |
-| -------------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| `qte`          | EMIT / RESULT / OPENED / CLOSED; `applyResult` (success → `curLine + 1`, fail → пропуск indented-блока); флаг `skipScenario`. |
-| `qte.scenario` | Регистрация `% qte` в SCENARIO; lookup `ITEMS`; при отсутствии id/item — `RESULT { success: false }`.                         |
+| Модуль         | Зона ответственности                                                                                                  |
+| -------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `qte`          | EMIT → `OPENED`; в `postinject` и на `EMIT` пишет `shared.qteScenarioSkip`.                                           |
+| `qte.result`   | RESULT → `CLOSED`; без skip — `applyResult` (success → `curLine + 1`, fail → `getBlockSkipShift`) и `emitNext`.       |
+| `qte.logs`     | Логи `EMIT` / `RESULT` через `emitLog`; `skipScenario` из `shared.qteScenarioSkip`.                                   |
+| `qte.scenario` | Регистрация `% qte` в SCENARIO; lookup `ITEMS`; при отсутствии id/item — log `MISSING` и `RESULT { success: false }`. |
 
 ## Сценарий
 
@@ -61,7 +66,7 @@ View сам переводит проценты в геометрию (град
 
 ## Embedded (`skipScenario`)
 
-При `EMIT` с `skipScenario: true` модуль `qte` на `RESULT` **не** меняет `curLine` и **не** вызывает `emitNext` — только `CLOSED`. Используется compatibility choose↔qte, чтобы ветвление осталось у choose.
+При `EMIT` с `skipScenario: true` ставится `shared.qteScenarioSkip`; на `RESULT` модуль `qte.result` **не** меняет `curLine` и **не** вызывает `emitNext` — только `CLOSED`. Используется compatibility choose↔qte, чтобы ветвление осталось у choose. В `postinject` модуля `qte` флаг — `false`.
 
 ## Compatibility
 

package/plugins/scenario/random.md

@@ -22,9 +22,9 @@
 
 ## Модули
 
-| Модуль   | Зона ответственности |
-| -------- | -------------------- |
-| `random` | Модуль `random`.     |
+| Модуль   | Зона ответственности                                                                                                |
+| -------- | ------------------------------------------------------------------------------------------------------------------- |
+| `random` | Сбор `% random.option` через `getBlockOptions`, случайный выбор ветки; skip невыбранных через `getOptionExecShift`. |
 
 ## Близкие плагины
 

package/plugins/vars/vars.md

@@ -31,12 +31,12 @@
 
 ## Модули
 
-| Модуль          | Зона ответственности                               |
-| --------------- | -------------------------------------------------- |
-| `vars.global`   | Обрабатывает GLOBAL_GET, GLOBAL_SET, GLOBAL_CLEAR. |
-| `vars.inject`   | Подмодуль `inject` плагина.                        |
-| `vars`          | Реестр обработчиков DEFAULT_REG.                   |
-| `vars.scenario` | Подмодуль `scenario` плагина.                      |
+| Модуль          | Зона ответственности                                                  |
+| --------------- | --------------------------------------------------------------------- |
+| `vars.global`   | Обрабатывает GLOBAL_GET, GLOBAL_SET, GLOBAL_CLEAR.                    |
+| `vars.inject`   | Подмодуль `inject` плагина.                                           |
+| `vars`          | Реестр обработчиков DEFAULT_REG.                                      |
+| `vars.scenario` | На `SCENARIO`: вход внутрь или `getBlockSkipShift` мимо indent-блока. |
 
 ## Близкие плагины
 

package/plugins/views.scenario/choose.md

@@ -24,12 +24,12 @@ React-UI выбора из текстовых опций. Зависит от sc
 
 ## Параметры
 
-| Ключ                  | Тип      | Смысл                                           |
-| --------------------- | -------- | ----------------------------------------------- |
-| `TRANSITION`          | `number` | Длительность анимации показа/скрытия (мс).      |
-| `ZINDEX`              | `number` | Z-index слоя и индекс блока controls.           |
-| `VIEW_PROPS`          | `object` | Пропсы Screen, PositionBox, TextControls, Text. |
-| `CONTROLS_EXTENSIONS` | `object` | Дополнительные обработчики controls.            |
+| Ключ                  | Тип      | Смысл                                                                  |
+| --------------------- | -------- | ---------------------------------------------------------------------- |
+| `TRANSITION`          | `number` | Длительность анимации показа/скрытия (мс).                             |
+| `ZINDEX`              | `number` | Z-index слоя и индекс блока controls.                                  |
+| `VIEW_PROPS`          | `object` | Пропсы Screen, PositionBox, Flex-wrap, title Text, TextControls, Text. |
+| `CONTROLS_EXTENSIONS` | `object` | Дополнительные обработчики controls.                                   |
 
 ## Настройки
 
@@ -43,7 +43,7 @@ React-UI выбора из текстовых опций. Зависит от sc
 | `choose_view.controller`        | `CONTROLS_EXTENSIONS`, `beforeShow` / `afterHide`, зеркало `STATE_UPDATE` / `UPDATE_FAST`.                                                                                                                                                                               |
 | `choose_view.controller.accept` | Наследует `@vnejs/module.controller.accept`: `ACCEPT` / `INTERACT` → `ACCEPT` → `CHOOSE.OPTION` по `currentArrowVerticalItem`; зеркалит `STATE_UPDATE`; PUSH/POP на SHOW/HIDE.                                                                                           |
 | `choose_view.controller.arrows` | Наследует `@vnejs/module.controller.arrows.vertical`: `ARROW_UP` / `ARROW_BOTTOM` по полному `options[]`; скипает `hided` через `isArrowItemAvailable` (индекс исходный); PUSH/POP на SHOW/HIDE; эмитит `STATE_UPDATE` с `{ currentArrowVerticalItem }` и `UPDATE_FAST`. |
-| `choose_view.view`              | React-render опций.                                                                                                                                                                                                                                                      |
+| `choose_view.view`              | React-render опций; опциональный заголовок из `args.title`.                                                                                                                                                                                                              |
 
 ## Связь с CHOOSE
 

package/plugins/views.screens/checkers.md

@@ -0,0 +1,102 @@
+# plugins/views.screens/checkers/
+
+Пакет: `@vnejs/plugins.views.screens.checkers` · namespace: `CHECKERS`
+
+Экран русских шашек: доска 8×8, навигация стрелками через `@vnejs/module.controller.arrows.grid`, ход через ACCEPT / клик. Стороны — игрок или AI (`player` / `sacrifice` / `random` / `strong`) через `$ 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`. |
+
+## Shared
+
+| Ключ             | Тип / дефолт                      | Смысл                                 |
+| ---------------- | --------------------------------- | ------------------------------------- |
+| `checkersAi`     | `{ white, black }` → оба `player` | Тип управления стороной.              |
+| `checkersAiBusy` | `boolean` → `false`               | Пока AI ходит — игнор ACCEPT / клика. |
+
+## Параметры
+
+| Ключ            | Тип      | Смысл                                                                   |
+| --------------- | -------- | ----------------------------------------------------------------------- |
+| `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.             |
+
+## Модули
+
+| Модуль                       | Зона ответственности                                                                                            |
+| ---------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `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`    | среди ходов без ответа-взятия; если таких нет — среди «подставляющих»      |
+
+## Сценарий
+
+```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
+```
+
+## Бандл и игра
+
+- Бандл: `@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).

package/scenario.guide/choose.md

@@ -4,6 +4,7 @@
 
 ```vne
 % choose
+  title: "Меню"
   % choose.option "Осмотреть"
     hided: $ flag seen
     $ flag seen
@@ -24,6 +25,8 @@
 
 Если все опции `hided` (или список пуст) — блок пропускается.
 
+Опционально у блока: `title: "…"` — заголовок над опциями (рисует `views.scenario.choose`).
+
 ## Props и keywords опции
 
 ```vne