@vnejs/docs 0.2.65 → 0.2.66

package/plugins/scales/health.md

@@ -1,37 +1,37 @@
 # plugins/scales/health/
 
-Пакет: `@vnejs/plugins.scales.health` · namespace: `SCALE_HEALTH`
+Package: `@vnejs/plugins.scales.health` · namespace: `SCALE_HEALTH`
 
-Обрабатывает переполнение и опустошение шкалы здоровья.
+Handles overflow and underflow of the health scale.
 
-## События
+## Events
 
-Нет.
+None.
 
-## Константы
+## Constants
 
-Нет.
+None.
 
-## Параметры
+## Parameters
 
-Нет.
+None.
 
-## Настройки
+## Settings
 
-Нет.
+None.
 
-## Модули
+## Modules
 
-| Модуль         | Зона ответственности        |
-| -------------- | --------------------------- |
-| `scale_health` | Подмодуль `health` плагина. |
+| Module         | Role                       |
+| -------------- | -------------------------- |
+| `scale_health` | Plugin `health` submodule. |
 
-## Близкие плагины
+## Related plugins
 
 ### plugins/core/
 
-— нет
+— None
 
-### Остальные
+### Other
 
 - [scales.md](./scales.md) — `SCALES`: PARAMS.TYPES

package/plugins/scales/mana.md

@@ -1,37 +1,37 @@
 # plugins/scales/mana/
 
-Пакет: `@vnejs/plugins.scales.mana` · namespace: `SCALE_MANA`
+Package: `@vnejs/plugins.scales.mana` · namespace: `SCALE_MANA`
 
-Обрабатывает переполнение и опустошение шкалы маны.
+Handles overflow and underflow of the mana scale.
 
-## События
+## Events
 
-Нет.
+None.
 
-## Константы
+## Constants
 
-Нет.
+None.
 
-## Параметры
+## Parameters
 
-Нет.
+None.
 
-## Настройки
+## Settings
 
-Нет.
+None.
 
-## Модули
+## Modules
 
-| Модуль       | Зона ответственности      |
-| ------------ | ------------------------- |
-| `scale_mana` | Подмодуль `mana` плагина. |
+| Module       | Role                     |
+| ------------ | ------------------------ |
+| `scale_mana` | Plugin `mana` submodule. |
 
-## Близкие плагины
+## Related plugins
 
 ### plugins/core/
 
-— нет
+— None
 
-### Остальные
+### Other
 
 - [scales.md](./scales.md) — `SCALES`: PARAMS.TYPES

package/plugins/scales/scales.md

@@ -1,56 +1,56 @@
 # plugins/scales/scales/
 
-Пакет: `@vnejs/plugins.scales.scales` · namespace: `SCALES`
+Package: `@vnejs/plugins.scales.scales` · namespace: `SCALES`
 
-Управляет числовыми шкалами: spawn, change, set, check и границы.
+Manages numeric scales: spawn, change, set, check, and bounds.
 
-## События
+## Events
 
-Payloads и результаты хендлеров типизированы через module augmentation контракта (`VneEventPayloadMap` / `VneEventResultMap`); типы — в `@vnejs/contracts.scales`.
+Handler payloads and results are typed through module augmentation of the contract (`VneEventPayloadMap` / `VneEventResultMap`). The types live in `@vnejs/contracts.scales`.
 
-| Ключ        | Строка                 | Смысл                                    |
-| ----------- | ---------------------- | ---------------------------------------- |
-| `SPAWN`     | `vne:scales:spawn`     | Событие `SPAWN` namespace плагина.       |
-| `DESTROY`   | `vne:scales:destroy`   | Событие `DESTROY` namespace плагина.     |
-| `SET`       | `vne:scales:set`       | Записать или обновить значение.          |
-| `RESET`     | `vne:scales:reset`     | Событие `RESET` namespace плагина.       |
-| `CHANGE`    | `vne:scales:change`    | Событие `CHANGE` namespace плагина.      |
-| `CHANGED`   | `vne:scales:changed`   | Зафиксировать изменение состояния.       |
-| `CHECK`     | `vne:scales:check`     | Проверить состояние или наличие ресурса. |
-| `OVERFLOW`  | `vne:scales:overflow`  | Событие `OVERFLOW` namespace плагина.    |
-| `UNDERFLOW` | `vne:scales:underflow` | Событие `UNDERFLOW` namespace плагина.   |
+| Key         | String                 | Meaning                             |
+| ----------- | ---------------------- | ----------------------------------- |
+| `SPAWN`     | `vne:scales:spawn`     | Plugin namespace event `SPAWN`.     |
+| `DESTROY`   | `vne:scales:destroy`   | Plugin namespace event `DESTROY`.   |
+| `SET`       | `vne:scales:set`       | Write or update a value.            |
+| `RESET`     | `vne:scales:reset`     | Plugin namespace event `RESET`.     |
+| `CHANGE`    | `vne:scales:change`    | Plugin namespace event `CHANGE`.    |
+| `CHANGED`   | `vne:scales:changed`   | Record a state change.              |
+| `CHECK`     | `vne:scales:check`     | Check state or resource presence.   |
+| `OVERFLOW`  | `vne:scales:overflow`  | Plugin namespace event `OVERFLOW`.  |
+| `UNDERFLOW` | `vne:scales:underflow` | Plugin namespace event `UNDERFLOW`. |
 
-## Константы
+## Constants
 
-Нет.
+None.
 
-## Параметры
+## Parameters
 
-| Ключ    | Тип      | Смысл                                                               |
-| ------- | -------- | ------------------------------------------------------------------- |
-| `TYPES` | `string` | Виды шкал (`health`, `mana`, …), расширяются дочерними контрактами. |
+| Key     | Type     | Meaning                                                         |
+| ------- | -------- | --------------------------------------------------------------- |
+| `TYPES` | `string` | Scale kinds (`health`, `mana`, …), extended by child contracts. |
 
-## Ключи
+## Keys
 
-Контракт экспортирует `getScaleKey(entityId, scaleType)` → `` `${entityId}:${scaleType}` `` (например `hero:health`). События scales принимают `key` как opaque string.
+The contract exports `getScaleKey(entityId, scaleType)` → `` `${entityId}:${scaleType}` `` (for example `hero:health`). Scales events accept `key` as an opaque string.
 
-## Настройки
+## Settings
 
-Нет.
+None.
 
-## Модули
+## Modules
 
-| Модуль   | Зона ответственности                           |
-| -------- | ---------------------------------------------- |
-| `scales` | Обрабатывает SPAWN, DESTROY, RESET, CHANGE, …. |
+| Module   | Role                                      |
+| -------- | ----------------------------------------- |
+| `scales` | Handles SPAWN, DESTROY, RESET, CHANGE, …. |
 
-## Близкие плагины
+## Related plugins
 
 ### plugins/core/
 
 - [state.md](../core/state.md) — `STATE`: EVENTS.SET, EVENTS.CLEAR
 
-### Остальные
+### Other
 
 - [health.md](./health.md) — `SCALES.TYPES.HEALTH`
 - [mana.md](./mana.md) — `SCALES.TYPES.MANA`

package/plugins/scenario/autoread.md

@@ -1,52 +1,52 @@
 # plugins/scenario/autoread/
 
-Пакет: `@vnejs/plugins.scenario.autoread` · namespace: `AUTOREAD`
+Package: `@vnejs/plugins.scenario.autoread` · namespace: `AUTOREAD`
 
-Автоматически продвигает сценарий по таймеру с настраиваемой задержкой и временными блокировками.
+Automatically advance the scenario on a timer with configurable delay and temporary block sources.
 
-## События
+## Events
 
-Payloads и результаты хендлеров типизированы через module augmentation контракта (`VneEventPayloadMap` / `VneEventResultMap`); типы — в `@vnejs/contracts.scenario.autoread`.
+Handler payloads and results are typed through module augmentation of the contract (`VneEventPayloadMap` / `VneEventResultMap`). The types live in `@vnejs/contracts.scenario.autoread`.
 
-| Ключ             | Строка                        | Смысл                                                                                                        |
-| ---------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------ |
-| `EMIT`           | `vne:autoread:emit`           | Если авточтение включено и нет блокировок — `INTERACT.EMIT` по `vne-autoread-allow`, иначе `TIMEOUT_CREATE`. |
-| `PUSH`           | `vne:autoread:push`           | Добавить источник блокировки и `TIMEOUT_CLEAR`. Payload: `{ source? }`.                                      |
-| `POP`            | `vne:autoread:pop`            | Снять источник блокировки; если очередь пуста — `TIMEOUT_CREATE`. Payload: `{ source? }`.                    |
-| `TIMEOUT_CREATE` | `vne:autoread:timeout_create` | Поставить таймер на `SETTINGS.AUTOREAD.DELAY`; по нему эмитит `EMIT`.                                        |
-| `TIMEOUT_CLEAR`  | `vne:autoread:timeout_clear`  | Снять поставленный таймер.                                                                                   |
+| Key              | String                        | Meaning                                                                                               |
+| ---------------- | ----------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `EMIT`           | `vne:autoread:emit`           | When autoread is on and not blocked — `INTERACT.EMIT` on `vne-autoread-allow`, else `TIMEOUT_CREATE`. |
+| `PUSH`           | `vne:autoread:push`           | Add a block source and `TIMEOUT_CLEAR`. Payload: `{ source? }`.                                       |
+| `POP`            | `vne:autoread:pop`            | Remove a block source; when the queue is empty — `TIMEOUT_CREATE`. Payload: `{ source? }`.            |
+| `TIMEOUT_CREATE` | `vne:autoread:timeout_create` | Start a timer for `SETTINGS.AUTOREAD.DELAY`; when it fires, emit `EMIT`.                              |
+| `TIMEOUT_CLEAR`  | `vne:autoread:timeout_clear`  | Clear the active timer.                                                                               |
 
-## Константы
+## Constants
 
-| Ключ           | Смысл                                                                                                                                     |
-| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
-| `LOGS_ACTIONS` | Метки для логов: `EMIT` (`emit`), `PUSH` (`push`), `POP` (`pop`), `TIMEOUT_CREATE` (`timeout_create`), `TIMEOUT_CLEAR` (`timeout_clear`). |
+| Key            | Meaning                                                                                                                              |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `LOGS_ACTIONS` | Log labels: `EMIT` (`emit`), `PUSH` (`push`), `POP` (`pop`), `TIMEOUT_CREATE` (`timeout_create`), `TIMEOUT_CLEAR` (`timeout_clear`). |
 
-## Параметры
+## Parameters
 
-| Ключ              | Тип       | Смысл                                        |
-| ----------------- | --------- | -------------------------------------------- |
-| `DEFAULT_DELAY`   | `number`  | Значение по умолчанию: 5000.                 |
-| `DEFAULT_ENABLED` | `boolean` | Значение по умолчанию для включения функции. |
+| Key               | Type      | Meaning                                |
+| ----------------- | --------- | -------------------------------------- |
+| `DEFAULT_DELAY`   | `number`  | Default: 5000.                         |
+| `DEFAULT_ENABLED` | `boolean` | Default for whether the feature is on. |
 
-## Настройки
+## Settings
 
-| Ключ                               | Тип       | Смысл                                               |
-| ---------------------------------- | --------- | --------------------------------------------------- |
-| `ENABLED` (`vne:autoread:enabled`) | `boolean` | Включить или выключить функцию.                     |
-| `DELAY` (`vne:autoread:delay`)     | `number`  | Настройка `vne:autoread:delay` в `shared.settings`. |
+| Key                                | Type      | Meaning                                            |
+| ---------------------------------- | --------- | -------------------------------------------------- |
+| `ENABLED` (`vne:autoread:enabled`) | `boolean` | Turn the feature on or off.                        |
+| `DELAY` (`vne:autoread:delay`)     | `number`  | Setting `vne:autoread:delay` in `shared.settings`. |
 
-## Модули
+## Modules
 
-| Модуль             | Зона ответственности                                                                                                                                                             |
-| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `autoread`         | `SETTINGS.INIT` в `setup`. `SETTINGS.CHANGED` для `ENABLED` эмитит `PUSH` / `POP`.                                                                                               |
-| `autoread.logs`    | Логи всех событий `AUTOREAD` через `EVENTS.LOGS.EMIT`. `PUSH` / `POP` пишут `source`.                                                                                                     |
-| `autoread.sources` | В `postinject` — `shared.autoreadDisableSources`. `PUSH` / `POP`. На `STATE.SET` очищает набор.                                                                                  |
-| `autoread.emit`    | `EMIT`: если включено и нет блокировок — `INTERACT.EMIT` по `vne-autoread-allow`, иначе `TIMEOUT_CREATE`.                                                                        |
-| `autoread.timeout` | `TIMEOUT_CREATE` / `TIMEOUT_CLEAR`. Таймер на `SETTINGS.AUTOREAD.DELAY`, по нему `EMIT`. `STATE.CLEAR` → `TIMEOUT_CLEAR`. `STATE.SET` → `TIMEOUT_CLEAR`, затем `TIMEOUT_CREATE`. |
+| Module             | Role                                                                                                                                                                        |
+| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `autoread`         | `SETTINGS.INIT` in `setup`. `SETTINGS.CHANGED` for `ENABLED` emits `PUSH` / `POP`.                                                                                          |
+| `autoread.logs`    | Log all `AUTOREAD` events via `EVENTS.LOGS.EMIT`. `PUSH` / `POP` log `source`.                                                                                              |
+| `autoread.sources` | In `postinject` — `shared.autoreadDisableSources`. `PUSH` / `POP`. On `STATE.SET` clears the set.                                                                           |
+| `autoread.emit`    | `EMIT`: when on and not blocked — `INTERACT.EMIT` on `vne-autoread-allow`, else `TIMEOUT_CREATE`.                                                                           |
+| `autoread.timeout` | `TIMEOUT_CREATE` / `TIMEOUT_CLEAR`. Timer on `SETTINGS.AUTOREAD.DELAY`, then `EMIT`. `STATE.CLEAR` → `TIMEOUT_CLEAR`. `STATE.SET` → `TIMEOUT_CLEAR`, then `TIMEOUT_CREATE`. |
 
-## Близкие плагины
+## Related plugins
 
 ### plugins/core/
 
@@ -55,6 +55,6 @@ Payloads и результаты хендлеров типизированы ч
 - [settings.md](../core/settings.md) — `SETTINGS`: EVENTS.CHANGED, EVENTS.INIT
 - [state.md](../core/state.md) — `STATE`: EVENTS.CLEAR, EVENTS.SET
 
-### Остальные
+### Other
 
-— нет
+— None

package/plugins/scenario/choose.md

@@ -1,106 +1,115 @@
 # plugins/scenario/choose/
 
-Пакет: `@vnejs/plugins.scenario.choose` · namespace: `CHOOSE`
+Package: `@vnejs/plugins.scenario.choose` · namespace: `CHOOSE`
 
-Обрабатывает сценарные команды `% choose` / `$ choose`, собирает опции, хранит состояние выбора в `globalState.choose` и переводит сценарий к выбранной ветке. UI не рендерит — за отображение отвечает [views.scenario/choose.md](../views.scenario/choose.md).
+Handles scenario commands `% choose` / `$ choose`, collects options, stores choice state in `globalState.choose`, and moves the scenario to the picked branch. Does not render UI — see [views.scenario/choose.md](../views.scenario/choose.md).
 
-## Сценарные команды
+## Scenario commands
 
-| Синтаксис             | Смысл                                                                                                                       |
-| --------------------- | --------------------------------------------------------------------------------------------------------------------------- |
-| `% choose`            | Открыть выбор: собрать `% choose.option`, emit `EMIT`. Если все опции `hided` (или список пуст) — `SKIP` и переход за блок. |
-| `% choose.option "…"` | Ветка опции; при проходе мимо невыбранной — skip тела по indent.                                                            |
-| `$ choose repeat`     | Вернуться к ближайшему `% choose` **выше** текущей строки в том же label и `emit SCENARIO.NEXT`.                            |
+| Syntax                | Meaning                                                                                                                        |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `% choose`            | Open choice: collect `% choose.option`, emit `EMIT`. When all options are `hided` (or list empty) — `SKIP` and exit the block. |
+| `% choose.option "…"` | Option branch; when passing a non-chosen option — skip body by indent.                                                         |
+| `$ choose repeat`     | Return to the nearest `% choose` **above** the current line in the same label and `emit SCENARIO.NEXT`.                        |
 
-Пример цикла «осмотреть → вернуться в меню»:
+Example “look around → back to menu” loop:
 
 ```vne
 % choose
-  % choose.option "Осмотреть"
+  % choose.option "Look around"
     hided: $ flag seen
     $ flag seen
     "…"
     $ choose repeat
-# дальше — когда при повторном входе все option скрыты
+# later — when on re-entry all options are hidden
 ```
 
-## События
+## Events
 
-Payloads и результаты хендлеров типизированы через module augmentation контракта (`VneEventPayloadMap` / `VneEventResultMap`); типы — в `@vnejs/contracts.scenario.choose`.
+Handler payloads and results are typed through module augmentation of the contract (`VneEventPayloadMap` / `VneEventResultMap`). The types live in `@vnejs/contracts.scenario.choose`.
 
-| Ключ                 | Строка                          | Смысл                                                                                                                                           |
-| -------------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| `EMIT`               | `vne:choose:emit`               | Принять опции и args; если есть видимые — `STATE_UPDATE` и `SHOW`; иначе `SKIP`.                                                                |
-| `OPTION`             | `vne:choose:option`             | Принять выбор по UI-индексу: прогнать `OPTION_BEFORE`, затем `HIDE`, `OPTION_REPLACE`, установить `curLine`, сброс state, `emit SCENARIO.NEXT`. |
-| `OPTION_BEFORE`      | `vne:choose:option_before`      | Side effects до применения выбора (подписки с `priority` на Observer).                                                                          |
-| `OPTION_REPLACE`     | `vne:choose:option_replace`     | Подменить UI-индекс принятой опции (цепочка handlers перед переходом по ветке).                                                                 |
-| `OPTION_REPLACE_REG` | `vne:choose:option_replace_reg` | Зарегистрировать обработчик `OPTION_REPLACE`.                                                                                                   |
-| `SKIP`               | `vne:choose:skip`               | Пропустить блок: `curLine` на первую строку после indent-дерева `% choose`, `emit SCENARIO.NEXT`.                                               |
-| `SHOW`               | `vne:choose:show`               | Выбор активен (state готов). Слушает view-плагин.                                                                                               |
-| `HIDE`               | `vne:choose:hide`               | Выбор закрыт. Слушает view-плагин.                                                                                                              |
-| `EXEC_REG`           | `vne:choose:exec_reg`           | Зарегистрировать exec-обработчик для подстановки в опции.                                                                                       |
-| `EXEC_GET`           | `vne:choose:exec_get`           | Получить значение через зарегистрированный exec-обработчик.                                                                                     |
-| `STATE_UPDATE`       | `vne:choose:state_update`       | Обновить накопленное состояние модуля `choose`.                                                                                                 |
+| Key                  | String                          | Meaning                                                                                                                |
+| -------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `EMIT`               | `vne:choose:emit`               | Accept options and args; when any are visible — `STATE_UPDATE` and `SHOW`; else `SKIP`.                                |
+| `OPTION`             | `vne:choose:option`             | Accept UI index: run `OPTION_BEFORE`, then `HIDE`, `OPTION_REPLACE`, set `curLine`, reset state, `emit SCENARIO.NEXT`. |
+| `OPTION_BEFORE`      | `vne:choose:option_before`      | Side effects before applying choice (Observer subscriptions with `priority`).                                          |
+| `OPTION_REPLACE`     | `vne:choose:option_replace`     | Replace the accepted option UI index (handler chain before branch jump).                                               |
+| `OPTION_REPLACE_REG` | `vne:choose:option_replace_reg` | Register an `OPTION_REPLACE` handler.                                                                                  |
+| `OPTION_TEXT`        | `vne:choose:option_text`        | Replace option `text` before it is stored. No handlers — the scenario literal stays.                                   |
+| `OPTION_TEXT_REG`    | `vne:choose:option_text_reg`    | Register an `OPTION_TEXT` handler.                                                                                     |
+| `SKIP`               | `vne:choose:skip`               | Skip block: `curLine` to first line after `% choose` indent tree, `emit SCENARIO.NEXT`.                                |
+| `SHOW`               | `vne:choose:show`               | Choice active (state ready). View plugin listens.                                                                      |
+| `HIDE`               | `vne:choose:hide`               | Choice closed. View plugin listens.                                                                                    |
+| `EXEC_REG`           | `vne:choose:exec_reg`           | Register exec handler for substitution in options.                                                                     |
+| `EXEC_GET`           | `vne:choose:exec_get`           | Get a value via a registered exec handler.                                                                             |
+| `STATE_UPDATE`       | `vne:choose:state_update`       | Update accumulated `choose` module state.                                                                              |
 
-## Константы
+## Constants
 
-| Ключ                  | Смысл                                                                |
-| --------------------- | -------------------------------------------------------------------- |
-| `EXEC_ACTIONS.REPEAT` | Литерал `repeat` для `$ choose repeat`.                              |
-| `LOGS_ACTIONS`        | Метки для логов: `EMIT`, `OPTION`, `SKIP`, `SHOW`, `HIDE`, `REPEAT`. |
+| Key                   | Meaning                                                         |
+| --------------------- | --------------------------------------------------------------- |
+| `EXEC_ACTIONS.REPEAT` | Literal `repeat` for `$ choose repeat`.                         |
+| `LOGS_ACTIONS`        | Log labels: `EMIT`, `OPTION`, `SKIP`, `SHOW`, `HIDE`, `REPEAT`. |
 
-## Параметры
+## Parameters
 
-Нет.
+None.
 
-## Настройки
+## Settings
 
-Нет.
+None.
 
-## Стейт
+## State
 
 `globalState.choose`: `options`, `args`, `isShow`, `id`.
 
-`id` — экземпляр открытия. `crypto.randomUUID()` на `EMIT` (в том числе `$ choose repeat`), `""` после закрытия. В сейв и снапшот истории попадает вместе со стейтом. В сценарий не выводится.
+`id` — open instance id. `crypto.randomUUID()` on `EMIT` (including `$ choose repeat`), `""` after close. Saved in saves and history snapshots with state. Not exposed to scenario.
 
-`STATE.SET` не меняет стейт, если совпали `isShow` и `id`. Другой открытый выбор (`isShow: true`, другой `id`): запись среза, затем `HIDE` и `SHOW` с `{ isForce: true }`, чтобы view заново прочитал опции. Смена видимости — один `SHOW` или `HIDE` с `{ isForce: true }`. Пока выбор скрыт, другой срез только записывается в стейт.
+`STATE.SET` does not change state when `isShow` and `id` match. Another open choice (`isShow: true`, different `id`): write slice, then `HIDE` and `SHOW` with `{ isForce: true }` so the view re-reads options. Visibility change — one `SHOW` or `HIDE` with `{ isForce: true }`. While hidden, another slice only updates state.
 
-## Модули
+## Modules
 
-| Модуль                   | Зона ответственности                                                                                                                                       |
-| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `choose`                 | State (`id`, `options`, `args`, `isShow`): `STATE_UPDATE`, `STATE.SET` / `STATE.CLEAR` (→ `SHOW` / `HIDE`; смена открытого выбора — `HIDE`, затем `SHOW`). |
-| `choose.emit`            | Обрабатывает `EMIT` (→ `STATE_UPDATE` + `SHOW` или `SKIP`).                                                                                                |
-| `choose.option`          | Обрабатывает `OPTION`.                                                                                                                                     |
-| `choose.skip`            | Обрабатывает `SKIP` через `getBlockSkipShift`.                                                                                                             |
-| `choose.logs`            | Логирование `EMIT` / `OPTION` / `SKIP` / `SHOW` / `HIDE`.                                                                                                  |
-| `choose.replace`         | Реестр обработчиков `OPTION_REPLACE_REG`; наследник `@vnejs/module.replace`.                                                                               |
-| `choose.exec`            | Реестр обработчиков EXEC_REG / EXEC_GET.                                                                                                                   |
-| `choose.scenario`        | Регистрация `% choose`: сбор option-строк через `getBlockOptions`, emit `EMIT`.                                                                            |
-| `choose.scenario.option` | Регистрация `% choose.option`: skip невыбранных веток.                                                                                                     |
-| `choose.scenario.module` | Регистрация `$ choose`: action `repeat`.                                                                                                                   |
+| Module                   | Role                                                                                                                                                     |
+| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `choose`                 | State (`id`, `options`, `args`, `isShow`): `STATE_UPDATE`, `STATE.SET` / `STATE.CLEAR` (→ `SHOW` / `HIDE`; different open choice — `HIDE`, then `SHOW`). |
+| `choose.emit`            | Handles `EMIT` (→ `STATE_UPDATE` + `SHOW` or `SKIP`).                                                                                                    |
+| `choose.option`          | Handles `OPTION`.                                                                                                                                        |
+| `choose.skip`            | Handles `SKIP` via `getBlockSkipShift`.                                                                                                                  |
+| `choose.logs`            | Log `EMIT` / `OPTION` / `SKIP` / `SHOW` / `HIDE`.                                                                                                        |
+| `choose.replace`         | Registry for `OPTION_REPLACE_REG` handlers; extends `@vnejs/module.replace`.                                                                             |
+| `choose.option.text`     | Registry for `OPTION_TEXT_REG` handlers; extends `@vnejs/module.replace`. `EMIT` resolves each option through `OPTION_TEXT`.                              |
+| `choose.exec`            | Registry for EXEC_REG / EXEC_GET handlers.                                                                                                               |
+| `choose.scenario`        | Register `% choose`: collect option lines via `getBlockOptions`, emit `EMIT`.                                                                            |
+| `choose.scenario.option` | Register `% choose.option`: skip unchosen branches.                                                                                                      |
+| `choose.scenario.module` | Register `$ choose`: action `repeat`.                                                                                                                    |
 
 ## Compatibility
 
 ### `compatibility/scenario.choose/scenario.fastforward/`
 
-Пакет: `@vnejs/compatibility.scenario.choose-with-scenario.fastforward`
+Package: `@vnejs/compatibility.scenario.choose-with-scenario.fastforward`
 
-В `subscribe` слушает `OPTION_BEFORE`: при выборе опции эмитит `FASTFORWARD.CHECK` (до `HIDE` / `OPTION_REPLACE`).
+In `subscribe` listens to `OPTION_BEFORE`: on option pick emits `FASTFORWARD.CHECK` (before `HIDE` / `OPTION_REPLACE`).
 
 ### `compatibility/scenario.choose/scenario.history/`
 
-Пакет: `@vnejs/compatibility.scenario.choose-with-scenario.history`
+Package: `@vnejs/compatibility.scenario.choose-with-scenario.history`
 
-В `subscribe` слушает `OPTION_BEFORE`: при выборе опции эмитит `HISTORY.ADD` с `{ locKey: "choice" }` (без speaker/text). Текст строки берётся из локализации экрана history (`history.json`). Подключается в `bundles/vn.skeleton`.
+In `subscribe` listens to `OPTION_BEFORE`: on option pick emits `HISTORY.ADD` with `{ locKey: "choice" }` (no speaker/text). Line text comes from history screen localization (`history.json`). Wired in `bundles/vn.skeleton`.
 
 ### `compatibility/scenario.choose/scenario.qte/`
 
-Пакет: `@vnejs/compatibility.scenario.choose-with-scenario.qte`
+Package: `@vnejs/compatibility.scenario.choose-with-scenario.qte`
 
-На `OPTION_REPLACE` запускает QTE, если у опции есть `qte: <id>` (см. [qte.md](./qte.md#compatibility)). Поле `qte` добавляется в тип `ChooseOption` через module augmentation этого пакета; `qte-fallback` — keyword на строке опции (`% choose.option "…" | qte-fallback`), попадает в `ChooseOption.keywords`.
+On `OPTION_REPLACE` runs QTE when the option has `qte: <id>` (see [qte.md](./qte.md#compatibility)). Field `qte` is added to `ChooseOption` via this package’s module augmentation; `qte-fallback` — keyword on the option line (`% choose.option "…" | qte-fallback`), lands in `ChooseOption.keywords`.
 
-## Близкие плагины
+### `compatibility/scenario.choose/text/`
+
+Package: `@vnejs/compatibility.scenario.choose-with-text`
+
+In `init` registers an `OPTION_TEXT` handler that returns `TEXT.REPLACE`. `text.locs` and `text.inject` stay on that chain. Without this package the option keeps the literal from the scenario line. Wired in `bundles/vn.skeleton`.
+
+## Related plugins
 
 ### plugins/core/
 
@@ -108,11 +117,11 @@ Payloads и результаты хендлеров типизированы ч
 - [scenario.md](../core/scenario.md) — `SCENARIO`: EVENTS.NEXT, EVENTS.LINE_EXEC_REG, EVENTS.LINES_GET
 - [state.md](../core/state.md) — `STATE`: EVENTS.SET, EVENTS.CLEAR
 
-### Остальные
+### Other
 
-- [text.md](../text/text.md) — `TEXT`: EVENTS.REPLACE (текст опций)
-- [qte.md](./qte.md) — `QTE`: связка через `OPTION_REPLACE` (compatibility выше)
-- [fastforward.md](./fastforward.md) — `FASTFORWARD`: связка через `OPTION_BEFORE` (compatibility выше)
-- [history.md](./history.md) — `HISTORY`: связка через `OPTION_BEFORE` → `ADD` с `locKey` (compatibility выше)
-- [views.scenario/choose.md](../views.scenario/choose.md) — `CHOOSE_VIEW`: UI выбора (слушает SHOW / HIDE)
-- [scenario/point_and_click.md](./point_and_click.md) — тот же паттерн `repeat` / `SKIP` / `SHOW` / `HIDE` / `STATE_UPDATE`
+- [text.md](../text/text.md) — `TEXT`: `OPTION_TEXT` → `REPLACE` (compatibility above)
+- [qte.md](./qte.md) — `QTE`: link via `OPTION_REPLACE` (compatibility above)
+- [fastforward.md](./fastforward.md) — `FASTFORWARD`: link via `OPTION_BEFORE` (compatibility above)
+- [history.md](./history.md) — `HISTORY`: link via `OPTION_BEFORE` → `ADD` with `locKey` (compatibility above)
+- [views.scenario/choose.md](../views.scenario/choose.md) — `CHOOSE_VIEW`: choice UI (listens SHOW / HIDE)
+- [scenario/point_and_click.md](./point_and_click.md) — same `repeat` / `SKIP` / `SHOW` / `HIDE` / `STATE_UPDATE` pattern