@vnejs/docs 0.2.10 → 0.2.12

package/package.json

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

package/plugins/controls/controls.md

@@ -2,7 +2,7 @@
 
 Пакет: `@vnejs/plugins.controls.controls` · namespace: `CONTROLS`
 
-Стек обработчиков абстрактных control-кнопок (push/pop/emit).
+Стек обработчиков абстрактных control-кнопок (push/pop/emit) и текущий тип устройства ввода (keyboard / xbox / playstation).
 
 ## События
 
@@ -11,10 +11,17 @@
 | `EMIT` | `vne:controls:emit` | Инициировать действие или цикл. |
 | `PUSH` | `vne:controls:push` | Добавить элемент в очередь или стек. |
 | `POP` | `vne:controls:pop` | Извлечь элемент из очереди или стека. |
+| `DEVICE_SET` | `vne:controls:device_set` | Запросить смену типа устройства (`{ device }`). |
+| `DEVICE_CHANGED` | `vne:controls:device_changed` | Тип устройства реально сменился (`{ device, prevDevice }`). |
 
 ## Константы
 
-Нет.
+| Ключ | Смысл |
+|------|--------|
+| `BUTTONS` | Абстрактные control-кнопки (`ACCEPT`, `BACK`, …). |
+| `DEVICES.KEYBOARD` | `"keyboard"` |
+| `DEVICES.XBOX` | `"xbox"` |
+| `DEVICES.PLAYSTATION` | `"playstation"` |
 
 ## Параметры
 
@@ -29,6 +36,9 @@
 | Модуль | Зона ответственности |
 |--------|----------------------|
 | `controls` | Обрабатывает EMIT, PUSH, POP. |
+| `controls.device` | Хранит `currentDevice`; на `DEVICE_SET` эмитит `DEVICE_CHANGED` только при реальной смене. |
+
+Источники `DEVICE_SET`: keyboard (keydown) → keyboard; `controls.gamepad.device` (button_press / axis_move) → xbox|playstation по `gamepad.id`; cursor (`mousemove`) → keyboard.
 
 ## Близкие плагины
 
@@ -38,4 +48,6 @@
 
 ### Остальные
 
-— нет
+- [keyboard.md](./keyboard.md) — `KEYBOARD`
+- [gamepad.md](./gamepad.md) — `GAMEPAD`
+- [cursor.md](./cursor.md) — `CURSOR`

package/plugins/controls/cursor.md

@@ -2,7 +2,7 @@
 
 Пакет: `@vnejs/plugins.controls.cursor` · namespace: `CURSOR`
 
-Кастомный курсор: позиция, сдвиг, view и программный клик.
+Кастомный курсор: позиция, сдвиг, скролл под курсором, view и программный клик.
 
 ## События
 
@@ -15,7 +15,9 @@
 | `VIEW_SET` | `vne:cursor:view_set` | Записать или обновить значение. |
 | `MOVE` | `vne:cursor:move` | Событие `MOVE` namespace плагина. |
 | `MOVED` | `vne:cursor:moved` | Событие `MOVED` namespace плагина. |
-| `SHIFT` | `vne:cursor:shift` | Событие `SHIFT` namespace плагина. |
+| `SET_X_Y` | `vne:cursor:set_x_y` | Установить позицию курсора (`{ x?, y? }`) с clamp и `MOVED`. |
+| `SHIFT` | `vne:cursor:shift` | Сдвиг позиции курсора (`{ x?, y? }`). |
+| `SCROLL` | `vne:cursor:scroll` | Скролл ближайшего scrollable под курсором (`{ x?, y? }`). |
 
 ## Константы
 
@@ -30,20 +32,28 @@
 | `DEFAULT_SHIFT_REVERSE_X` | `boolean` | Значение по умолчанию: false. |
 | `DEFAULT_SHIFT_REVERSE_Y` | `boolean` | Значение по умолчанию: false. |
 | `BASE_SHIFT_SPEED` | `number` | Значение по умолчанию: 16. |
+| `DEFAULT_SCROLL_SPEED` | `number` | Значение по умолчанию: 1. |
+| `BASE_SCROLL_SPEED` | `number` | Значение по умолчанию: 16. |
 
 ## Настройки
 
 | Ключ | Тип | Смысл |
 |------|-----|-------|
-| `SHIFT_SPEED` (`vne:cursor:shift_speed`) | `number` | Скорость воспроизведения или анимации. |
-| `SHIFT_REVERSE_Y` (`vne:cursor:shift_reverse_y`) | `string` | Настройка `vne:cursor:shift_reverse_y` в `shared.settings`. |
-| `SHIFT_REVERSE_X` (`vne:cursor:shift_reverse_x`) | `string` | Настройка `vne:cursor:shift_reverse_x` в `shared.settings`. |
+| `SHIFT_SPEED` (`vne:cursor:shift_speed`) | `number` | Множитель скорости сдвига курсора. |
+| `SHIFT_REVERSE_Y` (`vne:cursor:shift_reverse_y`) | `boolean` | Инверсия оси Y при `SHIFT`. |
+| `SHIFT_REVERSE_X` (`vne:cursor:shift_reverse_x`) | `boolean` | Инверсия оси X при `SHIFT`. |
+| `SCROLL_SPEED` (`vne:cursor:scroll_speed`) | `number` | Множитель скорости скролла при `SCROLL`. |
 
 ## Модули
 
 | Модуль | Зона ответственности |
 |--------|----------------------|
-| `cursor` | Обрабатывает MOVE, CLICK, SHIFT, VIEW_SET, …. |
+| `cursor` (`Cursor`) | SET_X_Y, resize; владеет `globalState.cursor` (x/y). |
+| `cursor.view_set` (`CursorView`) | VIEW_SET + STATE/STARTED для проставления `view`. Имя `view_set`, чтобы не пересечься с `plugins/views/cursor` (`cursor.view`). |
+| `cursor.move` (`CursorMove`) | MOVE (мышь) → `CONTROLS.DEVICE_SET` (keyboard) + SHOW + SET_X_Y; скрывает системный курсор. |
+| `cursor.shift` (`CursorShift`) | SHIFT + INIT `SHIFT_SPEED` / `SHIFT_REVERSE_*`. |
+| `cursor.click` (`CursorClick`) | CLICK по координатам курсора. |
+| `cursor.scroll` (`CursorScroll`) | SCROLL + INIT `SCROLL_SPEED`. |
 
 ## Близкие плагины
 
@@ -56,4 +66,5 @@
 
 ### Остальные
 
-— нет
+- [controls.md](./controls.md) — `CONTROLS`: EVENTS.DEVICE_SET (mousemove → keyboard)
+- [gamepad.md](./gamepad.md) — стики через `compatibility.controls.gamepad-with-controls.cursor`: left → `SHIFT`, right → `SCROLL`; тип устройства (xbox|ps) — `controls.gamepad.device`

package/plugins/controls/gamepad.md

@@ -74,7 +74,8 @@ Electron при `STEAM_DECK=1` добавляет `?steamDeck=1`.
 
 | Модуль | Зона ответственности |
 |--------|----------------------|
-| `controls.gamepad` | Подмодуль `gamepad` плагина. |
+| `controls.gamepad` | Маппинг joypad-кнопок → `CONTROLS.EMIT`; профили и lock активного пада. |
+| `controls.gamepad.device` | `button_press` / `axis_move` → `CONTROLS.DEVICE_SET` (`DEVICES.XBOX` или `DEVICES.PLAYSTATION` по `gamepad.id`). |
 
 ## Близкие плагины
 
@@ -84,4 +85,5 @@ Electron при `STEAM_DECK=1` добавляет `?steamDeck=1`.
 
 ### Остальные
 
-- [controls.md](./controls.md) — `CONTROLS`: EVENTS.EMIT, CONST.BUTTONS
+- [controls.md](./controls.md) — `CONTROLS`: EVENTS.EMIT, EVENTS.DEVICE_SET (через `controls.gamepad.device` → xbox|playstation), CONST.BUTTONS, CONST.DEVICES
+- [cursor.md](./cursor.md) — через `compatibility.controls.gamepad-with-controls.cursor`: left stick (оси 0–1) → `CURSOR.SHIFT`, right stick (оси 2–3) → `CURSOR.SCROLL`; RT → `CURSOR.CLICK`

package/plugins/controls/keyboard.md

@@ -34,4 +34,4 @@
 
 ### Остальные
 
-- [controls.md](./controls.md) — `CONTROLS`: EVENTS.EMIT, CONST.BUTTONS
+- [controls.md](./controls.md) — `CONTROLS`: EVENTS.EMIT, EVENTS.DEVICE_SET, CONST.BUTTONS, CONST.DEVICES

package/plugins/views/controls.hints.md

@@ -0,0 +1,56 @@
+# plugins/views/controls.hints/
+
+Пакет: `@vnejs/plugins.views.controls.hints` · namespace: `CONTROLS_HINTS`
+
+Оверлей подсказок кнопок (keyboard / xbox / playstation). Группы из `PARAMS.GROUPS` показываются и прячутся по событиям из конфига; иконки переключаются по `CONTROLS.DEVICE_CHANGED`.
+
+## События
+
+| Ключ | Строка | Смысл |
+|------|--------|-------|
+| `UPDATE` | `vne:controls_hints:update` | Обновить состояние или отображение. |
+
+## Константы
+
+Нет.
+
+## Параметры
+
+| Ключ | Тип | Смысл |
+|------|-----|-------|
+| `GROUPS` | `ControlsHintsGroup[]` | Группы подсказок (position, direction, show/hide events, controls). |
+| `LOC_LABEL` | `string` | Метка locs (`controlsHints`). |
+| `TRANSITION` | `number` | Длительность перехода View. |
+| `ZINDEX` | `number` | Fallback z-index группы, если не задан в `position.zIndex`. |
+| `VIEW_PROPS` | `object` | Стили `icon` / `text` / `controlFlex` / `groupFlex`. |
+
+Для экрана обычно задают `position.zIndex = PARAMS.<SCREEN>.ZINDEX + 100`, чтобы другие экраны могли перекрыть подсказки.
+
+Появление/скрытие группы анимируется через `View` с `transition={PARAMS.TRANSITION}` (по умолчанию `300` ms). Группа видима, если `isShow` и есть контролы для текущего device (с учётом `hideOnDevices`). При уходе в пустой список (например keyboard) предыдущие иконки держатся до конца transition, чтобы fade-out успел отрисоваться.
+
+Элемент `controls[]`: `{ locKey, keyboard: string[], xbox: string[], playstation: string[], hideOnDevices?: ControlsDevice[] }` — пути внутри `media/view/{quality}/` (ведущий `/` снимается). `hideOnDevices` — девайсы, на которых контрол не рендерится (`CONTROLS.DEVICES.*`).
+
+## Настройки
+
+Нет.
+
+## Модули
+
+| Модуль | Зона ответственности |
+|--------|----------------------|
+| `controls.hints.controller` | Preload иконок на `SYSTEM.STARTED` / `MEMORY.CLEARED`; show/hide групп; `DEVICE_CHANGED`; `COMPONENTS.EXTERNAL_UPDATE` → `updateViewFast`. |
+| `controls.hints.view` | Рендер нескольких `View` + `Flex` + `Icon` + `Text`. |
+
+## Близкие плагины
+
+### plugins/core/
+
+- [components.md](../core/components.md) — `COMPONENTS`: EXTERNAL_UPDATE
+- [media.md](../core/media.md) — `MEDIA`: LOAD
+- [memory.md](../core/memory.md) — `MEMORY`: CLEARED
+- [state.md](../core/state.md) — `STATE`: SET, CLEAR
+- [system.md](../core/system.md) — `SYSTEM`: STARTED
+
+### Остальные
+
+- [controls.md](../controls/controls.md) — `CONTROLS`: DEVICE_CHANGED, DEVICES