@vnejs/docs 0.2.64 → 0.2.66

package/README.md

@@ -1,51 +1,51 @@
-# Документация VNEJS
+# VNEJS docs
 
-Монорепозиторий движка визуальных новелл **VNEJS** — plugin-архитектура на TypeScript с событийной шиной и композицией через `bundles/`.
+The **VNEJS** monorepo is a TypeScript visual-novel engine. It uses plugins, an event bus, and composition through `bundles/`.
 
-Публикуемый пакет: **`@vnejs/docs`**. Установка у потребителя:
+Published package: **`@vnejs/docs`**. Install:
 
 ```bash
 npm i @vnejs/docs
 ```
 
-Машинное оглавление: [`manifest.json`](./manifest.json).
+Machine index: [`manifest.json`](./manifest.json).
 
-## Для агента / автора сценария
+## For an agent or a scenario author
 
-Пишете или правите `.vne` во внешней игре — **сначала** смотрите сценарные разделы, не архитектуру плагинов.
+When you write or edit `.vne` in an external game, open the scenario sections first. Do not start with plugin architecture.
 
-| Приоритет | Раздел                                     | Когда открывать                                                 |
-| --------- | ------------------------------------------ | --------------------------------------------------------------- |
-| 1         | [`scenario.guide/`](./scenario.guide/)     | Авторские гайды с примерами (вариант B)                         |
-| 1         | [`scenario.catalog/`](./scenario.catalog/) | Полный индекс команд из `SCENARIO_COMMANDS` + stubs (вариант C) |
-| 2         | [`plugins/`](./plugins/)                   | События, модули, internals плагина                              |
-| 3         | [`architecture.md`](./architecture.md)     | Модель монорепы — редко, не для написания реплик                |
+| Priority | Section                                    | When to open                                                        |
+| -------- | ------------------------------------------ | ------------------------------------------------------------------- |
+| 1        | [`scenario.guide/`](./scenario.guide/)     | Author guides with examples (variant B)                             |
+| 1        | [`scenario.catalog/`](./scenario.catalog/) | Full command index from `SCENARIO_COMMANDS`, plus stubs (variant C) |
+| 2        | [`plugins/`](./plugins/)                   | Events, modules, plugin internals                                   |
+| 3        | [`architecture/`](./architecture/)         | Monorepo model. Read every file in this folder, together            |
 
-Сейчас в пакете **два** параллельных входа для сценария — сравните и выберите удобный. Оба ссылаются на `plugins/` за деталями.
+The package has two scenario entries. Compare them and pick one. Both link to `plugins/` for detail.
 
-## Содержание
+## Contents
 
-- [Сценарий — guide](./scenario.guide/README.md) — синтаксис `.vne` и тематические гайды
-- [Сценарий — catalog](./scenario.catalog/README.md) — каталог `$` / `%` команд
-- [Архитектура](./architecture.md) — каталоги монорепы и их связи, mermaid-диаграммы
-- [Changelog](./CHANGELOG.md) — изменения движка и API по версиям `@vnejs/docs`
+- [Scenario guide](./scenario.guide/README.md) — `.vne` syntax and topic guides
+- [Scenario catalog](./scenario.catalog/README.md) — `$` / `%` commands
+- [Architecture](./architecture/) — monorepo model, one file per directory. Read every file in the folder, together
+- [Changelog](./changelog/README.md) — engine and API changes, one file per `@vnejs/docs` release
 
-## Быстрый ориентир по монорепе
+## Monorepo map
 
-| Каталог                                                       | Роль                                     |
-| ------------------------------------------------------------- | ---------------------------------------- |
-| [`packages/`](./architecture.md#packages)                     | Runtime: `shared`, `observer`, `core`, … |
-| [`modules_extensions/`](./architecture.md#modules_extensions) | Базовые классы модулей                   |
-| [`configs/`](./architecture.md#configs)                       | Общие TypeScript-конфиги                 |
-| [`contracts/`](./architecture.md#contracts)                   | Публичный API плагина                    |
-| [`plugins/`](./architecture.md#plugins)                       | Реализация поведения                     |
-| [`compatibility/`](./architecture.md#compatibility)           | Связка между плагинами                   |
-| [`bundles/`](./architecture.md#bundles)                       | Сборка набора плагинов для игры          |
-| [`helpers/`](./architecture.md#helpers)                       | Утилиты без привязки к движку            |
-| [`uis/`](./architecture.md#uis)                               | React-компоненты для view-плагинов       |
-| [`cli/`](./architecture.md#cli)                               | Сборка монорепы и игр                    |
-| [`games/`](./architecture.md#games)                           | Проекты игр: сценарий, entry, dist       |
-| [`backends/`](./architecture.md#backends)                     | Workers: токен Steam и JSON меток        |
-| [`vs_code_extensions/`](./architecture.md#vs_code_extensions) | Подсветка `.vne` в редакторе             |
+| Directory                                           | Role                                     |
+| --------------------------------------------------- | ---------------------------------------- |
+| [`packages/`](./architecture/packages.md)           | Runtime: `shared`, `observer`, `core`, … |
+| [`modules_extensions/`](./architecture/modules.md)  | Module base classes                      |
+| [`configs/`](./architecture/configs.md)             | Shared TypeScript configs                |
+| [`contracts/`](./architecture/contracts.md)         | Public plugin API                        |
+| [`plugins/`](./architecture/plugins.md)             | Behavior on the bus                      |
+| [`compatibility/`](./architecture/compatibility.md) | Link between plugins                     |
+| [`bundles/`](./architecture/bundles.md)             | Plugin set for a game                    |
+| [`helpers/`](./architecture/helpers.md)             | Utils with no engine tie                 |
+| [`uis/`](./architecture/uis.md)                     | React components for view plugins        |
+| [`cli/`](./architecture/cli.md)                     | Build the monorepo and the games         |
+| [`games/`](./architecture/games.md)                 | Game projects: scenario, entry, dist     |
+| [`backends/`](./architecture/backends.md)           | Workers: Steam token and label JSON      |
+| [`vs_code_extensions/`](./architecture/editor.md)   | `.vne` highlighting in the editor        |
 
-`games/` подключает один `bundles/` и получает `VneCore` — точку входа в движок.
+A game imports one `bundles/` package and gets `VneCore`, the engine entry.

package/architecture/backends.md

@@ -0,0 +1,18 @@
+# backends/
+
+**Отдельные Cloudflare Workers** — не плагины и не часть `VneCore`. Игра ходит к ним по HTTP. Пакеты в `plugins/` их не импортируют.
+
+| Пакет                  | Назначение                                                                                                                     |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| **`backends/auth`**    | Steam OpenID и проверка покупки своего AppID. Отдаёт подписанный JWT (`steamId`, `ownsApp`, `exp`).                            |
+| **`backends/content`** | `GET /label/*` — JSON меток из `dist/label`. Пускает только запрос с тем же JWT и `ownsApp`. Картинки и `mods.json` не отдаёт. |
+
+Оба воркера знают один `AUTH_SECRET`. Контент-воркер Steam не вызывает. Каталог ассетов при деплое указывает на `dist` игры, сами JSON в репозиторий воркера не копируются. Закрытый деплой не кладёт то же дерево `label/` рядом со статикой игры.
+
+```mermaid
+flowchart LR
+  Game[games/] -->|popup OpenID| Auth[backends/auth]
+  Auth --> Steam[steamcommunity.com]
+  Game -->|GET /label Bearer| Content[backends/content]
+  Auth -.->|общий AUTH_SECRET| Content
+```

package/architecture/build.md

@@ -0,0 +1,37 @@
+# Сборка end-to-end
+
+```mermaid
+flowchart TD
+  subgraph repo ["Монорепозиторий"]
+    CFG[configs/]
+    PKG[packages/]
+    ME[modules_extensions/]
+    CT[contracts/]
+    PL[plugins/]
+    CP[compatibility/]
+    BD[bundles/]
+    CL[cli/]
+  end
+
+  subgraph game_proj ["games/my-game/"]
+    SC[scenario .vne]
+    EN[entry/]
+  end
+
+  CFG --> PL
+  PKG --> ME --> PL
+  CT --> PL
+  CT --> CP
+  PL --> BD
+  CP --> BD
+  BD --> EN
+  SC --> CL
+  CL -->|"data + client"| ART[dist/]
+  EN --> ART
+  ART --> PLAY[Browser / Electron]
+```
+
+1. `bundles/` регистрирует `plugins/` и `compatibility/` в `VNE`.
+2. `cli/` собирает сценарий в JSON и клиент в `dist/`.
+3. `new VneCore().init()` — модули, media, lifecycle до `start`.
+4. Игра живёт на событиях шины; cross-plugin связи — через `compatibility/` из `bundles/`.

package/architecture/bundles.md

@@ -0,0 +1,20 @@
+# bundles/
+
+**Композиция** без бизнес-логики — цепочка side-effect импортов из `plugins/` и `compatibility/`.
+
+- Определяет **набор возможностей** для `games/`.
+- Экспортирует **`VneCore`**.
+- Дочерний пакет в `bundles/` импортирует родительский и **добавляет** плагины.
+
+```mermaid
+flowchart BT
+  CORE["bundles/core/"]
+  CANVAS["bundles/canvas.react/"]
+  SKEL["bundles/vn.skeleton/"]
+  BASE["bundles/vn.base/"]
+  GAME["bundles/coraline/"]
+
+  CORE --> CANVAS --> SKEL --> BASE --> GAME
+```
+
+Entry point: re-export `VneCore` → импорт `plugins/` → импорт `compatibility/`.

package/architecture/cli.md

@@ -0,0 +1,25 @@
+# cli/
+
+**CLI** для монорепы и сборки `games/` (`npx @vnejs/*`).
+
+```mermaid
+flowchart LR
+  MR["@vnejs/monorepo"]
+  BD["@vnejs/build"]
+  DS["@vnejs/desktop"]
+  TL["@vnejs/tools"]
+
+  MR --> WS[workspace-пакеты]
+  BD --> G[games/]
+  DS --> G
+  TL --> G
+```
+
+| CLI                   | Роль                                                                                |
+| --------------------- | ----------------------------------------------------------------------------------- |
+| **`@vnejs/monorepo`** | `build`, `package`, `publish`, `bump`, `sync-deps`, `graph`, `run-changed`, `clear` |
+| **`@vnejs/build`**    | **`data`** — `game/` → JSON в `dist/`; **`client`** — Vite entry → `dist/`          |
+| **`@vnejs/desktop`**  | **`web`** — static-сервер для `dist/`                                               |
+| **`@vnejs/tools`**    | Resize image/video/audio, контент-пайплайн                                          |
+
+Корень: `npm run build` → monorepo build; **Turbo** кэширует `build` с `dependsOn: ["^build"]`.

package/architecture/compatibility.md

@@ -0,0 +1,22 @@
+# compatibility/
+
+**Опциональная интеграция** между независимыми плагинами — включается в `bundles/`, не зашивается внутрь `plugins/`.
+
+- Один модуль, наследник `ModuleCore`.
+- В **`subscribe`** слушает A, эмитит B.
+- **`regModule`** без `regPlugin` — нет своего namespace в `VNE`.
+- Зависит только от **контрактов** из `contracts/`, не от реализаций в `plugins/`.
+
+Именование: `@vnejs/compatibility.{источник}-with-{цель}` → путь `compatibility/{источник}/{цель}/`.
+
+```mermaid
+flowchart LR
+  PA[plugins/ A] -->|"emit EVENT_A"| OBS[Observer]
+  OBS --> CM[compatibility/]
+  CM -->|"emit EVENT_B"| OBS
+  OBS --> PB[plugins/ B]
+
+  PA -.->|"не импортирует"| PB
+  CM --> CTA[contracts/ A]
+  CM --> CTB[contracts/ B]
+```

package/architecture/configs.md

@@ -0,0 +1,19 @@
+# configs/
+
+**Общие конфигурации сборки** — переиспользуемые TypeScript-настройки, не runtime.
+
+| Пакет                          | Назначение                                                                            |
+| ------------------------------ | ------------------------------------------------------------------------------------- |
+| **`@vnejs/configs.ts-common`** | tsconfig для `plugins/`, `contracts/`, `packages/`, `modules_extensions/`, `helpers/` |
+| **`@vnejs/configs.ts-uis`**    | tsconfig для `uis/react/` и view-кода `games/` (JSX, React-типы)                      |
+| **`@vnejs/configs.vitest`**    | Общий Vitest-конфиг (`create-config.js`, `setup.js`) для пакетов с тестами            |
+
+```mermaid
+flowchart LR
+  TC[configs.ts-common] --> PL[plugins/ / contracts/ / packages/]
+  TU[configs.ts-uis] --> UI[uis/react/]
+  TU --> GM[games/]
+  TV[configs.vitest] --> TEST[пакеты с vitest]
+```
+
+Пакеты `ts-*` экспортируют json; локальный `tsconfig.json` пакета **extends** общий и задаёт `rootDir` / `outDir`. Vitest-конфиг — JS-хелперы, не tsconfig.

package/architecture/contracts.md

@@ -0,0 +1,30 @@
+# contracts/
+
+**Контракт** — публичный API одного плагина: **спецификация**, не поведение.
+
+### Что входит в контракт
+
+- **`PLUGIN_NAME`** — namespace в реестре `VNE`.
+- **`CONSTANTS`**, **`SUBSCRIBE_EVENTS`**, **`PARAMS`**, **`SETTINGS_KEYS`**.
+- **Типы** — payload событий, shape глобального state, shared-поля.
+
+### TypeScript augmentation
+
+Контракт расширяет типы через `declare module`:
+
+- `@vnejs/shared` — `VnePluginEventsMap`, `VnePluginConstantsMap`, …
+- `@vnejs/module` — `ModuleGlobalState`, `ModuleShared`
+- другие контракты — при cross-cutting типах
+
+### Принципы
+
+- Один контракт обычно соответствует **одному плагину** в `plugins/` (1:1).
+- Контракт **не импортирует** реализацию из `plugins/`.
+- Доменная структура `contracts/` зеркалит таксономию `plugins/`.
+
+```mermaid
+flowchart LR
+  CT[contracts/] -->|"declare module"| TS[Типы VNE / Module]
+  CT -->|"CONSTANTS, EVENTS, PARAMS"| REG[regPlugin при загрузке plugins/]
+  PL[plugins/] -->|"import"| CT
+```

package/architecture/dependencies.md

@@ -0,0 +1,55 @@
+# Граф зависимостей между каталогами
+
+```mermaid
+flowchart TD
+  G[games/] --> B[bundles/]
+  G --> CLI[cli/]
+  G -.->|HTTP| BE[backends/]
+  B --> P[plugins/]
+  B --> C[compatibility/]
+  P --> CT[contracts/]
+  C --> CT
+  P --> H[helpers/]
+  P --> U[uis/]
+  P --> ME[modules_extensions/]
+  ME --> PKG[packages/]
+  CT --> PKG
+  CFG[configs/] --> P
+  CFG --> PKG
+  CFG --> U
+  VSC[vs_code_extensions/] -.->|"подсветка .vne"| G
+```
+
+**Направление зависимостей:**
+
+| От               | К                                   | Смысл                                                    |
+| ---------------- | ----------------------------------- | -------------------------------------------------------- |
+| `games/`         | `bundles/`, `cli/`                  | Игра не знает про отдельные плагины; сборка через `cli/` |
+| `games/`         | `backends/`                         | HTTP к воркерам токена и меток, без импорта пакетов      |
+| `bundles/`       | `plugins/`, `compatibility/`        | Только импорт нужного набора                             |
+| `plugins/`       | `contracts/`                        | Реализация следует объявленному API                      |
+| `plugins/`       | `modules_extensions/` → `packages/` | Модули наследуют базы, базы опираются на shared/observer |
+| `compatibility/` | `contracts/` (2+)                   | Связка по событиям, без импорта реализаций               |
+| `plugins/`       | `helpers/`, `uis/`                  | Горизонтальные утилиты и UI                              |
+| `plugins/`       | — другой `plugins/`                 | **Напрямую не зависит**                                  |
+| `configs/`       | пакеты workspace                    | Общие tsconfig, не runtime                               |
+
+## Резюме
+
+| Каталог                   | Одной фразой                      |
+| ------------------------- | --------------------------------- |
+| **`packages/`**           | Реестр, шина, VneCore             |
+| **`modules_extensions/`** | Базовые классы модулей            |
+| **`configs/`**            | Общие tsconfig                    |
+| **`contracts/`**          | API плагина: события, типы        |
+| **`plugins/`**            | Реализация на шине                |
+| **`compatibility/`**      | Opt-in связка двух плагинов       |
+| **`bundles/`**            | Набор способностей для игры       |
+| **`helpers/`**            | Утилиты без движка                |
+| **`uis/`**                | React/UI для view                 |
+| **`cli/`**                | Сборка монорепы и игр             |
+| **`games/`**              | Сценарий + entry + dist           |
+| **`backends/`**           | Workers: токен Steam и JSON меток |
+| **`vs_code_extensions/`** | Подсветка `.vne`                  |
+
+**Главное правило:** `plugins/` не знают друг о друге; интеграция — через события по `contracts/` и явный `compatibility/` в `bundles/`.

package/architecture/editor.md

@@ -0,0 +1,7 @@
+# vs_code_extensions/
+
+**Расширения редактора** для формата сценария — не runtime.
+
+| Расширение            | Назначение                                         |
+| --------------------- | -------------------------------------------------- |
+| **`@vnejs/language`** | Подсветка **`.vne`** в `games/*/game/**/scenario/` |

package/architecture/games.md

@@ -0,0 +1,38 @@
+# games/
+
+**Проекты игр** — потребители `bundles/` + `cli/`.
+
+```
+games/<name>/
+├── entry/           # index.ts, index.html → импорт bundles/, new VneCore()
+├── game/<mod>/      # scenario (.vne), scripts, media, public
+├── desktop/         # Electron dev/prod
+├── dist/            # JSON + JS после сборки
+│   ├── mods.json
+│   ├── label/       # label/<path>.json (например label/prologue/1.json)
+│   └── media_info/  # media_info/<mod>.json (не путать с /media/ ассетов)
+└── package.json
+```
+
+```mermaid
+flowchart LR
+  SC["game/**/*.vne"]
+  DATA["build data"]
+  JSON["dist mods.json label/ media_info/"]
+  ENTRY["entry/index.ts"]
+  CLIENT["build client"]
+  DIST["dist/"]
+  SRV["desktop web"]
+
+  SC --> DATA --> JSON
+  ENTRY --> CLIENT --> DIST
+  JSON --> RUN[Browser / Electron]
+  DIST --> RUN
+  SRV --> RUN
+```
+
+1. **`build:data`** — JSON для **`VneCore.init()`**: `mods.json`, `label/<path>.json`, `media_info/<mod>.json`.
+2. **`build:client`** — Vite + `bundles/`.
+3. **`entry/`** — `new VneCore()`, `await init()`.
+
+`games/` **не собирает** `plugins/` — выбирает `bundles/` и добавляет контент.

package/architecture/helpers.md

@@ -0,0 +1,14 @@
+# helpers/
+
+**Чистые утилиты** вне event-архитектуры.
+
+- **`helpers/primitives/`** — атомарные функции (`tokenize-*`, `get-id`, `to-json`, …).
+- **`helpers/composites/`** — составные утилиты поверх primitives (например `call-all-promises`).
+- **`helpers/base/`** — barrel **`@vnejs/helpers`** (реэкспорт primitives и composites).
+
+```mermaid
+flowchart LR
+  H[helpers/] --> P[plugins/]
+  H --> CORE[VneCore]
+  H -.->|"не связан"| VNE[(VNE / Observer)]
+```

package/architecture/model.md

@@ -0,0 +1,43 @@
+# Архитектура монорепозитория VNEJS
+
+Документ описывает **общую модель** монорепозитория: каталоги движка, направление зависимостей и сборку игры. Конкретные пакеты не перечисляются — только принципы и связи.
+
+## Суть модели
+
+Движок построен на **событийной шине** и **глобальном реестре**:
+
+- **`Observer`** — шина событий; модули подписываются (`on`) и публикуют (`emit`) по строковым ключам.
+- **`VNE`** — реестр, заполняемый при загрузке: `CONST`, `EVENTS`, `SETTINGS`, `PARAMS` — по namespace каждого плагина.
+- **`VneCore`** — runtime: собирает зарегистрированные модули, инжектит зависимости и запускает lifecycle (`inject → subscribe → setup → init → start`).
+
+Регистрация происходит **side-effect импортами** — при импорте пакета код сразу вызывает `regPlugin` или `regModule`, не дожидаясь явного вызова API.
+
+```mermaid
+flowchart LR
+  subgraph load ["Загрузка bundles/"]
+    I[side-effect import]
+    RP[regPlugin / regModule]
+    VNE[(VNE + VNE_MODULES)]
+    I --> RP --> VNE
+  end
+
+  subgraph runtime ["Runtime"]
+    VC[VneCore]
+    OBS[Observer]
+    VC -->|"создаёт модули из VNE_MODULES"| MOD[Модули]
+    MOD -->|"on / emit"| OBS
+    MOD -->|"читает"| VNE
+  end
+
+  VNE --> VC
+```
+
+## Именование npm-пакетов
+
+```
+plugins/core/system/   →  @vnejs/plugins.core.system
+contracts/text/text/   →  @vnejs/contracts.text
+compatibility/text/scenario.autoread/  →  @vnejs/compatibility.text-with-scenario.autoread
+```
+
+Слеш в пути → точка в имени; `compatibility/` — суффикс **`-with-`**.

package/architecture/modules.md

@@ -0,0 +1,87 @@
+# modules_extensions/
+
+**Иерархия базовых классов** для модулей внутри `plugins/`.
+
+### Иерархия классов
+
+```mermaid
+flowchart TD
+  M["@vnejs/module<br/>Module"]
+  MC["@vnejs/module.core<br/>ModuleCore"]
+  MR["@vnejs/module.replace<br/>ModuleReplace"]
+  MRE["@vnejs/module.replace.exec<br/>ModuleReplaceExec"]
+  MCO["@vnejs/module.components<br/>ModuleController, ModuleView"]
+  ML["@vnejs/module.layer<br/>canvas-слои"]
+  MA["@vnejs/module.audio"]
+  MCA["@vnejs/module.controller.audio"]
+  MCT["@vnejs/module.controller.tabs"]
+  MCP["@vnejs/module.controller.preload"]
+  MCB["@vnejs/module.controller.backgrounds"]
+  MCBG["@vnejs/module.controller.bg"]
+  MCAC["@vnejs/module.controller.accept"]
+  MCIN["@vnejs/module.controller.interact"]
+  MCAV["@vnejs/module.controller.arrows.vertical"]
+  MCAH["@vnejs/module.controller.arrows.horizontal"]
+  MCAG["@vnejs/module.controller.arrows.grid"]
+  MCPG["@vnejs/module.controller.pages"]
+  MCHS["@vnejs/module.controller.hide.on.state"]
+  MCHC["@vnejs/module.controller.hide.on.controls"]
+  MSC["@vnejs/module.scales.common"]
+
+  M --> MC
+  MC --> MR
+  MC --> MRE
+  MC --> MCO
+  MC --> MA
+  MC --> MCA
+  MC --> MCT
+  MC --> MCP
+  MC --> MCB
+  MC --> MCBG
+  MC --> MCAC
+  MC --> MCIN
+  MC --> MCAV
+  MC --> MCAH
+  MC --> MCAG
+  MC --> MCPG
+  MC --> MCHS
+  MC --> MCHC
+  MC --> MSC
+  MCO --> ML
+```
+
+| Пакет                                            | Назначение                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **`@vnejs/module`**                              | **`Module`**: `VNE`, `on`/`emit`, `inject`, state, shared, media, lifecycle                                                                                                                                                                                                                                                                                                                                                                    |
+| **`@vnejs/module.core`**                         | **`ModuleCore`** — типизированный доступ к **core-контрактам**                                                                                                                                                                                                                                                                                                                                                                                 |
+| **`@vnejs/module.replace`**                      | **`ModuleReplace`** — последовательная подмена значения поля payload через `REPLACE_KEY` и цепочку handlers                                                                                                                                                                                                                                                                                                                                    |
+| **`@vnejs/module.replace.exec`**                 | **`ModuleReplaceExec`** — реестр exec-handlers по имени модуля (`EXEC_REG` / `EXEC_GET`)                                                                                                                                                                                                                                                                                                                                                       |
+| **`@vnejs/module.components`**                   | **`ModuleView`**, **`ModuleController`** — React-view, zustand, media, controls. `SHOW`: `GATE` `-200`, `BEFORE` `-100`, `MAIN` `0`, `CONTROLS` `100`, `AFTER` `200`, `CLEANUP` `300`. `HIDE`: `GATE` `-300`, `CONTROLS` `-200`, `BEFORE` `-100`, `MAIN` `0`, `AFTER` `100`, `CLEANUP` `200`. `setShow` эмитит `UPDATE_STATE` `{ isShow }`, затем `updateView(isForce, false)`. `UPDATE_FAST`, `EXTERNAL_UPDATE` (`isShow` → `updateViewFast`) |
+| **`@vnejs/module.layer`**                        | Canvas layers: controller, image, sprite, text, video, props, view                                                                                                                                                                                                                                                                                                                                                                             |
+| **`@vnejs/module.audio`**                        | База для audio-плагинов scenario-слоёв (`music` / `sound` / …)                                                                                                                                                                                                                                                                                                                                                                                 |
+| **`@vnejs/module.controller.audio`**             | Overlay-BGM для view-экранов: pause global / play `view` / resume на `SHOW.AFTER` / `HIDE.AFTER` / PRELOAD                                                                                                                                                                                                                                                                                                                                     |
+| **`@vnejs/module.controller.tabs`**              | Навигация по вкладкам: TAB_PREV/TAB_NEXT → `TAB_SET`; guard + `applyTab` (`UPDATE_STATE` `{ tab }`) + abstract `onTabSet`; вкладка на `SHOW.BEFORE`, PUSH/POP на `CONTROLS`                                                                                                                                                                                                                                                                    |
+| **`@vnejs/module.controller.preload`**           | Предзагрузка меток и событий на `SHOW.BEFORE` (эмитит PRELOAD) и по PRELOAD. `isShow` из `UPDATE_STATE`; `MEMORY.CLEARED` — только при `isShow`. События задаёт плагин (`EVENT_SHOW` / `EVENT_HIDE` / `EVENT_PRELOAD` / `EVENT_UPDATE_STATE`)                                                                                                                                                                                                  |
+| **`@vnejs/module.controller.backgrounds`**       | Ротация списка фонов на `SHOW.AFTER` / таймеру / `MEMORY.CLEARED` при `isShow` из `UPDATE_STATE`. Таймер на `HIDE.AFTER` снимается всегда. События и список задаёт плагин                                                                                                                                                                                                                                                                      |
+| **`@vnejs/module.controller.bg`**                | Статичный фон экрана: `SHOW.BEFORE` пишет `bgSrc` через `UPDATE_STATE`; `isShow` приходит из `UPDATE_STATE`. Опционально PRELOAD / start / STATE.CLEAR; `MEMORY.CLEARED` — preload и/или refresh при `isShow`                                                                                                                                                                                                                                  |
+| **`@vnejs/module.controller.accept`**            | ACCEPT / INTERACT → событие ACCEPT плагина; PUSH/POP controls на `SHOW.CONTROLS` / `HIDE.CONTROLS`                                                                                                                                                                                                                                                                                                                                             |
+| **`@vnejs/module.controller.interact`**          | `BUTTONS.ANY` → `INTERACT.EMIT`; после показа `INTERACT.PUSH` (`onInteract`), перед скрытием `INTERACT.POP`; PUSH/POP controls на `SHOW.CONTROLS` / `HIDE.CONTROLS`                                                                                                                                                                                                                                                                            |
+| **`@vnejs/module.controller.arrows.vertical`**   | ARROW_UP / ARROW_BOTTOM по видимым пунктам; PUSH/POP controls на `SHOW.CONTROLS` / `HIDE.CONTROLS`; индекс через `UPDATE_STATE`; на `HIDE.CLEANUP` `currentArrowVerticalItem` становится `undefined` через `UPDATE_STATE`, затем `UPDATE_FAST`                                                                                                                                                                                                 |
+| **`@vnejs/module.controller.arrows.horizontal`** | ARROW_LEFT / ARROW_RIGHT по пунктам; PUSH/POP controls на `SHOW.CONTROLS` / `HIDE.CONTROLS`; индекс через `UPDATE_STATE`; на `HIDE.CLEANUP` `currentArrowHorizontalItem` становится `undefined` через `UPDATE_STATE`, затем `UPDATE_FAST`                                                                                                                                                                                                      |
+| **`@vnejs/module.controller.arrows.grid`**       | Четыре стрелки по сетке; `GRID_NEXT` / `GRID_PREV` на краю; PUSH/POP на `SHOW.CONTROLS` / `HIDE.CONTROLS`; `GRID_UPDATE_ITEMS` без payload, meta через `UPDATE_STATE`; на `HIDE.CLEANUP` `gridRow` / `gridColumn` становятся `undefined` через `UPDATE_STATE`, затем `UPDATE_FAST`                                                                                                                                                             |
+| **`@vnejs/module.controller.pages`**             | Пагинация: `PAGE_SET` / `PAGE_NEXT` / `PAGE_PREV` → `setPage` → `UPDATE_STATE` (`pageIndex`) + abstract `applyPage` + `UPDATE_FAST`                                                                                                                                                                                                                                                                                                            |
+| **`@vnejs/module.controller.hide.on.state`**     | STATE.SET / STATE.CLEAR → emit HIDE плагина (`isForce` задаёт наследник)                                                                                                                                                                                                                                                                                                                                                                       |
+| **`@vnejs/module.controller.hide.on.controls`**  | BACK / MENU / GAMEMENU → emit HIDE плагина; PUSH/POP controls на `SHOW.CONTROLS` / `HIDE.CONTROLS`                                                                                                                                                                                                                                                                                                                                             |
+| **`@vnejs/module.scales.common`**                | База для scales / RPG-модулей                                                                                                                                                                                                                                                                                                                                                                                                                  |
+
+### Принципы
+
+- Плагин берёт нужную базу (`ModuleCore`, `ModuleView`, `ModuleLayerController`, …), а не `Module` напрямую.
+- Базы тянут **контракты** из `contracts/` — отсюда типизация `EVENTS` / `CONST`.
+- **`ModuleCore`** — `plugins/core/` и `compatibility/`; **`ModuleView` / `ModuleLayer*`** — view/canvas + **`@vnejs/uis.react`**.
+
+|                   | `packages/`              | `modules_extensions/`        |
+| ----------------- | ------------------------ | ---------------------------- |
+| Роль              | Runtime и инфраструктура | Шаблоны для модулей плагинов |
+| Регистрация в VNE | да (`shared`, `core`)    | нет                          |
+| Наследование      | —                        | `plugins/` наследуют базы    |

package/architecture/packages.md

@@ -0,0 +1,43 @@
+# packages/
+
+**Runtime-основа движка** — публикуемые npm-пакеты `@vnejs/*`, на которых держатся `plugins/`, `bundles/` и `VneCore`.
+
+### Состав и зависимости
+
+```mermaid
+flowchart BT
+  CONST["constants"]
+  OBS["observer"]
+  SH["shared"]
+  SS["sources-set"]
+  SEM["semaphore"]
+  HELP["helpers/"]
+  CR["core — VneCore"]
+
+  CONST --> CR
+  OBS --> CR
+  SH --> CR
+  HELP --> CR
+  SS --> CT[contracts/ / plugins/]
+  SEM --> PL[plugins/]
+  SH --> PL
+  OBS --> ME[modules_extensions/]
+  SH --> ME
+```
+
+| Пакет                    | Назначение                                                                                                              |
+| ------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
+| **`@vnejs/shared`**      | Реестр **`VNE`**, массив **`VNE_MODULES`**, **`regPlugin`** / **`regModule`**, типы для module augmentation             |
+| **`@vnejs/observer`**    | **`Observer`** — pub/sub: `subscribe` / `emit` с `priority` (группы по возрастанию), `emitOne`, `emitReal`, `emitReals` |
+| **`@vnejs/core`**        | **`VneCore`**: модули из `VNE_MODULES`, lifecycle, загрузка `mods.json` / `media_info/`, `reset`                        |
+| **`@vnejs/constants`**   | Общие константы-заглушки (`EMPTY_OBJECT`, `EMPTY_ARRAY`)                                                                |
+| **`@vnejs/sources-set`** | **`SourcesSet`** — управление множеством «источников» (text и связанная логика)                                         |
+| **`@vnejs/semaphore`**   | **`Semaphore`** — очередь задач с весами и ограничением параллелизма                                                    |
+| **`@vnejs/test-utils`**  | Harness для тестов модулей: observer stubs, `createTestModule`, spies, DOM mocks                                        |
+
+### Принципы
+
+- **`shared` + `observer`** — фундамент; почти все плагины и модули зависят от них.
+- **`core`** — точка сборки runtime; `games/` создают `new VneCore()` после импорта `bundles/`.
+- **`test-utils`** — только для тестов workspace-пакетов; не часть игрового runtime.
+- Пакеты **не содержат** игровой логики и **не привязаны** к конкретному `bundles/`.

package/architecture/plugins.md

@@ -0,0 +1,36 @@
+# plugins/
+
+**Плагин** — реализация поведения, описанного в `contracts/`.
+
+### Регистрация
+
+1. Импорт контракта из `contracts/`.
+2. `regPlugin(PLUGIN_NAME, { constants, events, params, settings }, [ModuleClasses])`.
+3. Классы попадают в `VNE_MODULES` через `regModule`.
+
+### Модули и lifecycle
+
+Плагин — **набор модулей** с уникальным `name`. После `new VneCore()`:
+
+1. **`inject`** — observer, global state, shared, media. В конце, если метод есть, вызывается `postinject`.
+2. **`subscribe`** — подписки на события.
+3. **`setup`** — подготовка до `init` (все `setup` завершаются раньше любого `init`).
+4. **`init`** — асинхронная инициализация.
+5. **`start`** — после всех `init` (все `init` завершаются раньше любого `start`).
+
+```mermaid
+sequenceDiagram
+  participant A as Модуль plugins/ A
+  participant OBS as Observer
+  participant B as Модуль plugins/ B
+
+  A->>OBS: emit(EVENT_A.DONE, payload)
+  OBS->>B: handler
+  B->>OBS: emit(EVENT_B.START)
+```
+
+Пакеты из `plugins/` **не импортируют** код соседних плагинов — только контракт и `VNE`.
+
+### Зависимости
+
+- `contracts/`, **`@vnejs/module.*`**, **`@vnejs/helpers`**, **`@vnejs/uis.*`** (view).