@vnejs/docs 0.2.1

package/README.md

@@ -0,0 +1,49 @@
+# Документация VNEJS
+
+Монорепозиторий движка визуальных новелл **VNEJS** — plugin-архитектура на TypeScript с событийной шиной и композицией через `bundles/`.
+
+Публикуемый пакет: **`@vnejs/docs`**. Установка у потребителя:
+
+```bash
+npm i @vnejs/docs
+```
+
+Машинное оглавление: [`manifest.json`](./manifest.json).
+
+## Для агента / автора сценария
+
+Пишете или правите `.vne` во внешней игре — **сначала** смотрите сценарные разделы, не архитектуру плагинов.
+
+| Приоритет | Раздел | Когда открывать |
+|-----------|--------|-----------------|
+| 1 | [`scenario.guide/`](./scenario.guide/) | Авторские гайды с примерами (вариант B) |
+| 1 | [`scenario.catalog/`](./scenario.catalog/) | Полный индекс команд из `SCENARIO_COMMANDS` + stubs (вариант C) |
+| 2 | [`plugins/`](./plugins/) | События, модули, internals плагина |
+| 3 | [`architecture.md`](./architecture.md) | Модель монорепы — редко, не для написания реплик |
+
+Сейчас в пакете **два** параллельных входа для сценария — сравните и выберите удобный. Оба ссылаются на `plugins/` за деталями.
+
+## Содержание
+
+- [Сценарий — guide](./scenario.guide/README.md) — синтаксис `.vne` и тематические гайды
+- [Сценарий — catalog](./scenario.catalog/README.md) — каталог `$` / `%` команд
+- [Архитектура](./architecture.md) — каталоги монорепы и их связи, mermaid-диаграммы
+
+## Быстрый ориентир по монорепе
+
+| Каталог                                                       | Роль                                     |
+| ------------------------------------------------------------- | ---------------------------------------- |
+| [`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       |
+| [`vs_code_extensions/`](./architecture.md#vs_code_extensions) | Подсветка `.vne` в редакторе             |
+
+`games/` подключает один `bundles/` и получает `VneCore` — точку входа в движок.

package/architecture.md

@@ -0,0 +1,507 @@
+# Архитектура монорепозитория VNEJS
+
+Документ описывает **общую модель** монорепозитория: каталоги движка, направление зависимостей и сборку игры. Конкретные пакеты не перечисляются — только принципы и связи.
+
+## Суть модели
+
+Движок построен на **событийной шине** и **глобальном реестре**:
+
+- **`Observer`** — шина событий; модули подписываются (`on`) и публикуют (`emit`) по строковым ключам.
+- **`VNE`** — реестр, заполняемый при загрузке: `CONST`, `EVENTS`, `SETTINGS`, `PARAMS` — по namespace каждого плагина.
+- **`VneCore`** — runtime: собирает зарегистрированные модули, инжектит зависимости и запускает lifecycle (`inject → subscribe → init`).
+
+Регистрация происходит **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/]
+  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/` |
+| `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`, `emitOne`, `emitReal`, `emitReals` |
+| **`@vnejs/core`** | **`VneCore`**: модули из `VNE_MODULES`, lifecycle, загрузка `mods.json` / media, `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"]
+  MH["@vnejs/module.handlers<br/>ModuleHandlers"]
+  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"]
+  MSC["@vnejs/module.scales.common"]
+
+  M --> MC
+  MC --> MH
+  MC --> MR
+  MC --> MRE
+  MC --> MCO
+  MC --> MA
+  MC --> MCA
+  MC --> MCT
+  MC --> MSC
+  MCO --> ML
+```
+
+| Пакет | Назначение |
+|-------|------------|
+| **`@vnejs/module`** | **`Module`**: `VNE`, `on`/`emit`, `inject`, state, shared, media, lifecycle |
+| **`@vnejs/module.core`** | **`ModuleCore`** — типизированный доступ к **core-контрактам**; `emitLog`, `emitNext`, … |
+| **`@vnejs/module.handlers`** | **`ModuleHandlers`** — параллельные обработчики emit-событий с приоритетами (side effects) |
+| **`@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 |
+| **`@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/HIDE/PRELOAD |
+| **`@vnejs/module.controller.tabs`** | Навигация по вкладкам view-экранов: TAB_PREV/TAB_NEXT → `TAB_SET`, PUSH/POP controls на SHOW/HIDE |
+| **`@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.
+2. **`subscribe`** — подписки на события.
+3. **`init`** — асинхронная инициализация.
+
+```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 после сборки
+└── package.json
+```
+
+```mermaid
+flowchart LR
+  SC["game/**/*.vne"]
+  DATA["build data"]
+  JSON["dist/*.json"]
+  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`, labels, media).
+2. **`build:client`** — Vite + `bundles/`.
+3. **`entry/`** — `new VneCore()`, `await init()`.
+
+`games/` **не собирает** `plugins/` — выбирает `bundles/` и добавляет контент.
+
+---
+
+## 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, `SYSTEM.STARTED`.
+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 |
+| **`vs_code_extensions/`** | Подсветка `.vne` |
+
+**Главное правило:** `plugins/` не знают друг о друге; интеграция — через события по `contracts/` и явный `compatibility/` в `bundles/`.

package/manifest.json

@@ -0,0 +1,44 @@
+{
+  "name": "@vnejs/docs",
+  "readOrder": [
+    "scenario.guide/README.md",
+    "scenario.catalog/README.md",
+    "scenario.catalog/index.md",
+    "plugins/",
+    "architecture.md"
+  ],
+  "sections": {
+    "scenario.guide": {
+      "path": "scenario.guide/",
+      "role": "Author-facing .vne guides (variant B)",
+      "entry": "scenario.guide/README.md",
+      "pages": [
+        "scenario.guide/README.md",
+        "scenario.guide/dialogue.md",
+        "scenario.guide/flow.md",
+        "scenario.guide/vars.md",
+        "scenario.guide/choose.md",
+        "scenario.guide/point-and-click.md",
+        "scenario.guide/qte-random.md",
+        "scenario.guide/audio.md",
+        "scenario.guide/canvas.md",
+        "scenario.guide/views.md"
+      ]
+    },
+    "scenario.catalog": {
+      "path": "scenario.catalog/",
+      "role": "Command catalog from SCENARIO_COMMANDS (variant C)",
+      "entry": "scenario.catalog/README.md",
+      "index": "scenario.catalog/index.md",
+      "stubs": "scenario.catalog/stubs/"
+    },
+    "plugins": {
+      "path": "plugins/",
+      "role": "Plugin internals: events, modules, contracts"
+    },
+    "architecture": {
+      "path": "architecture.md",
+      "role": "Monorepo architecture (read rarely for scenario authoring)"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@vnejs/docs",
+  "version": "0.2.1",
+  "description": "VNEJS documentation for engine consumers and coding agents",
+  "files": [
+    "*.md",
+    "*.json",
+    "plugins/**/*.md",
+    "scenario.guide/**/*.md",
+    "scenario.catalog/**/*.md"
+  ],
+  "exports": {
+    "./package.json": "./package.json",
+    "./manifest.json": "./manifest.json",
+    "./README.md": "./README.md",
+    "./architecture.md": "./architecture.md",
+    "./plugins/*": "./plugins/*",
+    "./scenario.guide/*": "./scenario.guide/*",
+    "./scenario.catalog/*": "./scenario.catalog/*"
+  },
+  "scripts": {
+    "publish:major": "npx @vnejs/monorepo publish major --access public",
+    "publish:minor": "npx @vnejs/monorepo publish minor --access public",
+    "publish:patch": "npx @vnejs/monorepo publish patch --access public"
+  },
+  "license": "ISC"
+}

package/plugins/audio/ambient.md

@@ -0,0 +1,39 @@
+# plugins/audio/ambient/
+
+Пакет: `@vnejs/plugins.audio.ambient` · namespace: `AMBIENT`
+
+Воспроизведение зацикленного ambient-аудио из сценария с отдельной громкостью.
+
+## События
+
+Нет.
+
+## Константы
+
+Нет.
+
+## Параметры
+
+Нет.
+
+## Настройки
+
+| Ключ | Тип | Смысл |
+|------|-----|-------|
+| `VOLUME` (`vne:ambient:volume`) | `number` | Уровень громкости. |
+
+## Модули
+
+| Модуль | Зона ответственности |
+|--------|----------------------|
+| `ambient` | Модуль `ambient`. |
+
+## Близкие плагины
+
+### plugins/core/
+
+— нет
+
+### Остальные
+
+— нет