@vnejs/docs 0.2.65 → 0.2.67

package/architecture.md

@@ -1,566 +0,0 @@
-# Архитектура монорепозитория 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
-```
-
----
-
-## Граф зависимостей между каталогами
-
-```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/
-
-**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/`.
-
----
-
-## 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/` наследуют базы    |
-
----
-
-## 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.
-
----
-
-## 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
-```
-
----
-
-## 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).
-
----
-
-## 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]
-```
-
----
-
-## 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/`.
-
----
-
-## 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)]
-```
-
----
-
-## uis/
-
-**Презентационный слой** для view-плагинов — не плагин, не в `VNE`.
-
-| Часть                       | Назначение                    |
-| --------------------------- | ----------------------------- |
-| **`uis/utils/`**            | `cn`, `injectStyles`, `sel`   |
-| **`uis/react/primitives/`** | Атомы (button, text, icon, …) |
-| **`uis/react/composites/`** | Составные компоненты          |
-| **`uis/react/complex/`**    | Крупные UI-блоки              |
-| **`uis/react/hooks/`**      | React-хуки                    |
-| **`uis/react/base/`**       | Barrel **`@vnejs/uis.react`** |
-
-View-плагины в `plugins/`: **`ModuleView`** + render на компонентах из `uis/`.
-
-```mermaid
-flowchart TD
-  VP[plugins/ view / ModuleView]
-  VP --> UIR["@vnejs/uis.react"]
-  VP --> UU["@vnejs/uis.utils"]
-  VP --> OBS[Observer]
-  UIR -.->|"не использует"| VNE
-```
-
----
-
-## 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"]`.
-
----
-
-## 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/` и добавляет контент.
-
----
-
-## 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
-```
-
----
-
-## vs_code_extensions/
-
-**Расширения редактора** для формата сценария — не runtime.
-
-| Расширение            | Назначение                                         |
-| --------------------- | -------------------------------------------------- |
-| **`@vnejs/language`** | Подсветка **`.vne`** в `games/*/game/**/scenario/` |
-
----
-
-## Именование 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-`**.
-
----
-
-## Сборка 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/`.
-
----
-
-## Резюме
-
-| Каталог                   | Одной фразой                      |
-| ------------------------- | --------------------------------- |
-| **`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/`.