Add v2 live editor plan

docs/plan-v2.md

@@ -0,0 +1,302 @@
+# Bevy Forge v2 — план live-редактора
+
+Статус: план на согласование. Работа начинается с M0, не с «полного редактора».
+Репозиторий: https://git.shanaty.ru/Emil_Shanaty/Bevy_Forge
+
+## 1. Цель
+
+Сделать **встроенный live-редактор сцен для Bevy 0.20**: реальный ECS, реальный рендер,
+иерархия, reflection-инспектор, selection/transform, gizmo, сохранение сцены и BSN-экспорт.
+
+Это не клон Unity и не полный IDE. Это сфокусированный редактор сцен/уровней, который
+работает внутри игры и переиспользует уже готовый core v1.
+
+## 2. Жёсткие решения
+
+- **Bevy 0.20**, Rust 2021.
+- **Никакого egui** и связанных крейтов: `egui`, `eframe`, `bevy_egui`, `egui_dock`,
+  `bevy-inspector-egui`, `bevy_editor_pls`, BIRP, `transform-gizmo`.
+- UI — **родной Bevy UI**:
+  - `bevy_ui`;
+  - официальный `bevy_ui_widgets` 0.20 (button, checkbox, text input, list, menu,
+    dialog, modal, popover, radio, scroll area, slider, tabs);
+  - `bevy_text`, `bevy_input_focus`.
+- Иерархия, инспектор, gizmo, docking/tree (позже) — **свой код**.
+- v1 (standalone) не ломать. Новый редактор — отдельный crate в том же workspace.
+- Внешние редакторские проекты не добавлять как зависимости. `bevy_ui_widgets` —
+  официальная часть Bevy, а не сторонний редактор.
+- v1 пока остаётся на egui как legacy. В v2 egui не должно быть даже транзитивно.
+
+## 3. Что уже есть
+
+- `crates/bevy_forge_core` — сцены `.forge.ron`, компоненты, валидация, codegen BSN/Rust,
+  project/config/history/assets.
+- `crates/bevy_forge_editor` — standalone v1 на eframe/egui.
+- `crates/bevy_forge_cli` — `forge` CLI, scaffold, validate/export.
+- `compat/bsn-smoke` — компиляция сгенерированного BSN против реального Bevy 0.20.
+- `examples/demo-project` — 2D/3D сцены и текстуры.
+- Тесты: `cargo test --workspace` — 346 passed, 1 ignored; baseline зелёный.
+- Документация: `README.md`, `docs/architecture.md`, `docs/format.md`, `docs/bsn-export.md`.
+
+Переиспользовать: core-модель, `.forge.ron`, валидацию, codegen, CLI, demo, лицензии.
+Не переписывать: формат сцены, сериализацию, BSN-кодогенерацию без отдельного контракта.
+
+## 4. Архитектура v2
+
+```
+Bevy Forge v2
+├── crates/bevy_forge_runtime      # новый live-плагин
+│   ├── src/lib.rs                 # EditorPlugin, EditorState
+│   ├── src/plugin.rs              # режимы, системы, регистрация
+│   ├── src/ui/                    # Bevy UI: панели, тема, виджеты
+│   ├── src/hierarchy.rs           # ListBox, Children/ChildOf, selection
+│   ├── src/inspector.rs           # reflection-инспектор, свои виджеты
+│   ├── src/gizmo.rs               # transform gizmo, picking
+│   ├── src/screenshot.rs          # deterministic screenshot mode
+│   └── examples/editor_spike.rs   # demo app
+├── crates/bevy_forge_core         # переиспользуется
+├── crates/bevy_forge_editor       # v1 legacy, не ломать
+└── crates/bevy_forge_cli          # переиспользуется
+```
+
+### EditorPlugin
+
+- `EditorState`: `Enabled/Disabled`, `Selection`, `Mode` (`Edit/Paused/Play` позже).
+- `EditorPlugin` добавляется в игру; в релизе выключается feature-флагом.
+- UI-панели — обычные Bevy UI ноды, фиксированная раскладка:
+  - слева hierarchy;
+  - справа inspector;
+  - снизу/сверху toolbar и status;
+  - центр — viewport (игра).
+- Docking не делать в M0. Позже — свои tabs/split panes.
+- Инспектор читает `Reflect`/`TypeRegistry`; компоненты без `Reflect` показываются
+  read-only/`Debug`.
+- Gizmo — свой, на Bevy Gizmos + picking; не тащить `transform-gizmo`.
+- Screenshot — встроенный deterministic mode: размер окна, ожидание кадров, PNG, exit.
+- Scene save/load — через существующий core; BSN export — существующий codegen.
+- Code editor (Helix/Vim) — **не в M0**. Сначала внешний запуск, встроенный PTY-терминал
+  отдельным milestone.
+
+### Контракты M0
+
+Зафиксировать до кода:
+
+```rust
+pub struct EditorPlugin;
+pub struct EditorState { /* enabled, selection, ... */ }
+pub struct Selection(pub Option<Entity>);
+
+pub trait InspectorSource {
+    fn reflect_component(&self, entity: Entity) -> Option<&dyn Reflect>;
+}
+```
+
+Плагины модулей регистрируются в `lib.rs` заранее:
+
+```rust
+.add_plugins((HierarchyPlugin, InspectorPlugin, GizmoPlugin, ScreenshotPlugin))
+```
+
+T01 создаёт заглушки `HierarchyPlugin`/`InspectorPlugin`/`GizmoPlugin`, чтобы T02–T04
+не редактировали один `lib.rs`.
+
+## 5. Scope и non-goals
+
+### Входит в v2 core
+
+- live иерархия и selection;
+- reflection-инспектор для Transform/Name/Visibility и примитивных полей;
+- translate gizmo (позже rotate/scale);
+- editor camera;
+- save/load сцены `.forge.ron`;
+- BSN export;
+- undo/redo;
+- play/pause;
+- asset browser (базовый);
+- deterministic screenshots;
+- документация и тесты.
+
+### Не входит
+
+- modeling/скульптинг (это Blender);
+- полноценный code IDE внутри UI;
+- multi-world/полный Unity play mode;
+- сетевой collaborative editing;
+- поддержка всех кастомных компонентов без `Reflect`;
+- встроенный терминальный редактор в M0–M3;
+- миграция v1 на Bevy UI в этом плане (v1 остаётся legacy).
+
+## 6. Milestones и бюджет
+
+Бюджет — **верхняя оценка**, а не обещание. Считать по фактическим токенам и запросам.
+Ориентир: прямой `deepseek-flash`, off-peak, без Polza.
+
+| Milestone | Результат | Запросы | Output | Ожидаемо | Hard cap |
+|---|---|---:|---:|---:|---:|
+| **M0 Spike** | plugin + UI shell + hierarchy + inspector + один gizmo + screenshot | 200–300 | 0.3–0.5M | **$1.5–2.5** | **$2.5** |
+| **M1 Core** | selection, transform, undo/redo, save/load, editor camera | 400–700 | 0.8–1.5M | **$2.5–5** | **$5** |
+| **M2 Live** | play/pause, assets, real render, BSN export, file watch | 500–900 | 1.0–2.0M | **$2.5–5** | **$5** |
+| **M3 Hardening** | tests, UX, sizes, docs, performance | 300–600 | 0.6–1.2M | **$1–3** | **$3** |
+| **Итого core** | | **1 400–2 500** | **2.7–5.2M** | **$7.5–14** | **$15.5** |
+
+Отдельно, только после core:
+
+| Опция | Оценка |
+|---|---:|
+| Внешний запуск Helix/Vim + file watch | **$0.5–1** |
+| Встроенный PTY-терминал (Helix/Vim) | **$4–8**, 600–1000 запросов |
+| Neovim RPC backend | **$3–6** |
+
+Правило: milestone не начинается, пока предыдущий не принят verifier'ом и не записан
+фактический расход.
+
+## 7. M0 — детальный план
+
+### Состав
+
+- Lead: workspace, manifest, docs, integration, final gate.
+- Implementer A: T01 runtime shell + T02 hierarchy.
+- Implementer B: T03 inspector + T04 gizmo/screenshot (после T01 contract).
+- Verifier V01: независимая проверка, без участия в коде.
+- Максимум 2 implementer'а + 1 verifier. **Не swarm.**
+
+### Задачи
+
+| ID | Задача | Write scope | Зависит |
+|---|---|---|---|
+| LEAD | workspace manifest, пример, docs M0, интеграция | `Cargo.toml`, `docs/m0-spike.md`, `crates/bevy_forge_runtime/examples/**` | — |
+| T01 | runtime crate, `EditorPlugin`, UI shell, тема, заглушки плагинов | `crates/bevy_forge_runtime/Cargo.toml`, `src/lib.rs`, `src/plugin.rs`, `src/ui/**` | — |
+| T02 | hierarchy ListBox, Children/ChildOf, selection, scroll | `src/hierarchy.rs` | T01 |
+| T03 | reflection-инспектор: Name, Transform, Visibility, primitives | `src/inspector.rs` | T01 |
+| T04 | editor camera, translate gizmo, deterministic screenshot | `src/gizmo.rs`, `src/screenshot.rs` | T01 |
+| V01 | независимая проверка M0 | `.swarm/reviews/**` (вне продукта) | T01–T04 |
+
+T01 сначала коммитит каркас, контракты и заглушки плагинов; только после этого B начинает
+T03/T04. Каждый implementer добавляет focused-тесты для своего модуля; LEAD запускает
+общий gate. Не делить один `lib.rs` между T02–T04.
+
+### M0 acceptance
+
+- [ ] `cargo check -p bevy_forge_runtime` — без ошибок.
+- [ ] `cargo test -p bevy_forge_runtime` — тесты зелёные.
+- [ ] `cargo tree -p bevy_forge_runtime -i egui` — пусто/ошибка «package not found».
+- [ ] `cargo tree -p bevy_forge_runtime -i bevy_egui` — пусто.
+- [ ] `cargo run -p bevy_forge_runtime --example editor_spike` — открывается,
+      editor toggle работает.
+- [ ] Hierarchy показывает сущности сцены; клик меняет selection.
+- [ ] Inspector показывает Name/Transform/Visibility; изменение `Translation.x`
+      применяется к ECS и видно в gizmo.
+- [ ] Gizmo отображается и двигает выбранную сущность (хотя бы translate).
+- [ ] Screenshot mode сохраняет PNG в 1440×900 и 1000×640.
+- [ ] Нет изменений в core/v1, кроме необходимых shared manifest (LEAD).
+- [ ] README/`docs/m0-spike.md` описывают запуск и ограничения.
+
+### M0 verification
+
+V01 получает diff, acceptance-команды и скриншоты. Не читает отчёт Implementer'а как истину.
+Проверяет:
+
+- отсутствие egui в дереве runtime-крейта;
+- реальный запуск и два скриншота;
+- selection → inspector → ECS;
+- gizmo;
+- отсутствие out-of-scope правок;
+- читаемость кода и отсутствие «заглушек вместо функционала».
+
+### M0 stop-rules
+
+Остановиться и вернуться к плану, если:
+
+- 70% cap израсходовано, а acceptance не собран;
+- output >0.5M или запросов >300;
+- средний input >80k на запрос;
+- egui всё же попал в dependency tree;
+- hierarchy/inspector требуют переписывать core;
+- verifier нашёл критический дефект архитектуры, а не отдельный баг.
+
+## 8. M1–M3 — кратко
+
+### M1 Core
+- selection API и multi-select (если дёшево);
+- Transform editing с undo/redo (command stack);
+- save/load `.forge.ron` через core;
+- editor camera: pan/zoom/orbit;
+- горячие клавиши: delete, duplicate, focus, save;
+- unit-тесты на selection/undo/save;
+- без docking и без терминала.
+
+### M2 Live
+- play/pause без потери сцены (snapshot/restore);
+- asset browser: список файлов, превью, drag в сцену;
+- реальный рендер сцены, не wireframe;
+- BSN export из UI;
+- file watcher и hot reload;
+- базовая валидация сцены.
+
+### M3 Hardening
+- размеры 1440×900, 1280×720, 1000×640;
+- keyboard/focus/IME;
+- пустые/ошибочные состояния;
+- производительность hierarchy/inspector;
+- README, `docs/editor.md`, лицензии;
+- финальный независимый review.
+
+## 9. Токен-бюджет и процесс
+
+- Новый чат на каждый milestone. Не тащить историю v1.
+- 2 implementer'а + 1 verifier на M0/M1; 3+1 на M2; без 30 агентов.
+- Файлы до ~800 строк; если больше — split до dispatch.
+- Targeted tests; полный `cargo test --workspace` — только lead на финале.
+- Freeze перед verify; после фиксов — delta-review, не полный re-review.
+- Кэш: стабильный префикс system/tools/skills; не менять без причины.
+- Off-peak: после 13:00 МСК, до 04:00, выходные.
+- `max_tokens` и `reasoning_effort: low` для механических задач.
+- Прямой API, `deepseek-flash`; не Polza.
+- Бюджет записывать в `state.json`/`budget.md`: requests, input hit/miss, output, USD.
+
+### Stop-rules (общие)
+
+- 70% cap без принятого milestone → стоп.
+- output >2k/запрос или input >80k/запрос → пересобрать контекст.
+- verifier rejection >30% → проблема в брифах/контрактах.
+- Появился egui/сторонний редактор в runtime-крейте → стоп и убрать.
+
+## 10. Открытые вопросы
+
+1. `bevy_ui_widgets` — официальная часть Bevy 0.20, не сторонний редактор. Оставляем?
+   Если нет — делаем кнопки/поля/списки полностью вручную; это дороже.
+2. v1 оставляем legacy на egui или потом отдельно мигрируем/удаляем?
+   В v2 egui не используется в любом случае.
+3. Linux-first? Скриншоты/запуск сначала на Linux, потом macOS/Windows.
+4. Ветка `v2-live-editor`; main не ломаем.
+5. Нужен ли full docking в v2.0 или фиксированные панели достаточно?
+   По плану — фиксированные панели; docking позже.
+
+## 11. Промпт для нового чата
+
+```text
+Прочитай docs/plan-v2.md в репозитории Bevy_Forge и начни с M0 Spike.
+
+Repo: https://git.shanaty.ru/Emil_Shanaty/Bevy_Forge
+Ветка: v2-live-editor. v1 не ломать, core/codegen/CLI переиспользовать.
+
+Сначала:
+1. Prerequisite gate: rust/cargo, Bevy 0.20, display/screenshot; ничего не устанавливать
+   без разрешения; если чего-то нет — спросить.
+2. Прочитать README, docs/architecture.md, docs/plan-v2.md, Cargo.toml.
+3. Показать 5–6 задач M0 с write scope, acceptance и оценкой запросов.
+4. Дождаться подтверждения, затем делать.
+
+Ограничения:
+- никакого egui/eframe/bevy_egui/egui_dock/bevy-inspector-egui/bevy_editor_pls/BIRP;
+- UI только Bevy UI + официальный bevy_ui_widgets 0.20;
+- hierarchy/inspector/gizmo — свой код;
+- M0: plugin + UI shell + hierarchy + Name/Transform/Visibility inspector +
+  один translate gizmo + screenshot 1440×900 и 1000×640;
+- cap $2.5, 200–300 запросов, ≤0.5M output; direct deepseek-flash, off-peak;
+- 2 implementer'а + 1 verifier, без swarm;
+- остановиться на 70% cap или при появлении egui в дереве.
+
+После M0: отчёт с фактическими requests/input/output/USD, скриншотами и вердиктом
+verifier'а. Не начинать M1 без принятого M0.
+```