Learn_System/plans/sim-builder/CONTEXT.md

Feature Context: Конструктор симуляций (SimForge)

Current State

• Фаза 0 РЕАЛИЗОВАНА (в рабочем дереве, не закоммичено — коммит за оркестратором). Ветка feature/sim-builder от master.
  • frontend/js/labs/_sim_expr.js → window.SimExpr (безопасный движок выражений, без eval/Function; compile/evaluate/evalSafe/compileValue/parse/tokenize, whitelist + сравнения/логика/тернарник/multi-var env).
  • frontend/js/labs/_sim_engine.js → window.SimEngine.mount(host, spec) -> { play, pause, reset, setParam, getParam, isRunning, destroy, el }. Canvas (мир→экран, Y вверх) + KaTeX-оверлей подписей + слайдеры/play/pause/reset. Формат спеки v1 задокументирован в шапке файла.
  • frontend/js/labs/_sim_adapter.js → window.registerSpecSim(spec) / window.SimAdapter — строит манифест LabRegistry (ленивый хост #sim-spec-host-<id> в #lab-sim).
  • frontend/js/labs/_sim_demo.js — демо customdemo (бросок тела) за флагом ?simdemo=1 / ?sim=customdemo / LAB_SHOW_SPEC_DEMO / localStorage lab-spec-demo=1. Ученикам не светится.
  • Подключение в frontend/lab.html: 3 каркасных модуля eager после _graph_panel.js, демо после _register-all.js. _sim_deps.js НЕ тронут.
  • Верификация: node --check все 4 файла OK; eval/Function отсутствуют (только в комментариях); эмодзи нет; SimExpr self-test 29/30 (единственный «FAIL» -2^2=4 — это парити с graph.js).
• Лаборатория уже декларативна на уровне регистрации: frontend/js/labs/_registry.js (LabRegistry.register/get/all/setActive/stop/destroy/resolvePreview), манифест с open(ctx)/mount(host)/stop/destroy. ~40 симуляций — рукописные JS-модули в frontend/js/labs/.
• Каталог в БД: миграция 042_lab_sims.sql (lab_sims), роуты backend/src/routes/lab.js (GET /api/lab/sims, PATCH/:id, POST /reorder, links). Привязка к программе: 043_lab_sim_links.sql.

Архитектурные решения (зафиксированы при планировании)

• Спека = JSON-данные. Версия specVersion. Корень: { specVersion, meta, viewport, params[], objects[], physics?, plots[], controls }.
• Движок выражений безопасный — собственный парсер (расширение y=f(x) из graph.js): токенайзер → AST → eval по окружению { params, t, объекты, whitelisted Math fns }. ⛔ Без eval/Function. Whitelist: + - * / ^ %, sin cos tan asin acos atan sqrt abs exp ln log min max floor ceil round sign pi e, сравнения, ?:.
• Рантайм window.SimEngine.mount(host, spec) -> instance{ play, pause, reset, setParam, destroy }. Рендер: canvas для геометрии/трасс + SVG/absolute-div оверлей для подписей (KaTeX). Регистрируется в LabRegistry адаптером (одна функция строит манифест из спеки).
• Объект: { id, type, ...props-with-bindings }. type ∈ point|segment|vector|circle|rect|polyline|path|label|image. Любое числовое свойство может быть числом ИЛИ строкой-выражением.
• Физический режим (Фаза 2): объект с body:{ mass, vx, vy, fixed } интегрируется _fx_motion; силы physics:{ gravity, springs[], collisions, friction, walls }. Формульный и физический режимы сосуществуют (формульные объекты — кинематические).
• Безопасность шаринга: published-спека валидируется на сервере (размер, схема, глубина AST, число объектов/параметров); подписи-строки санитизируются как svg/текст.

Temporary Workarounds

• (нет)

Cross-Phase Dependencies

• Ф1 (графики/drag) зависит от рантайма Ф0.
• Ф2 (физика) зависит от Ф0 (модель объектов/цикл).
• Ф4 (билдер) зависит от Ф0–Ф2 (что строить) + Ф3 (куда сохранять).
• Ф5 (каталог) зависит от Ф3 (БД) + Ф0 (адаптер LabRegistry).
• Ф6 (раздача) зависит от Ф3+Ф5.
• Ф7 (доска) зависит от Ф0 (рантайм) + Ф5 (источник sim) + существующего simOpen/simState.

Implementation Notes

• Каждая фаза должна оставлять /lab рабочим (Incremental).
• Тестировать рантайм Ф0–Ф2 рукописными спеками-фикстурами (без билдера).
• Reuse > переписывание: сначала смотреть _fx_motion, _graph_panel, graph.js.

RESUME STATE

• Последний коммит фичи: — (Ф0 реализована, но ещё не закоммичена — ждёт оркестратора)
• Текущая фаза: Phase 0 — Runtime core (✅ Implemented, pending commit) → дальше Phase 1 — Plots & interactions
• Режим: Automated / Orchestrator / Incremental
• Новые публичные API для следующих фаз: window.SimExpr, window.SimEngine.mount, window.registerSpecSim / window.SimAdapter. Формат спеки v1 — в шапке _sim_engine.js и в handoff phase-0.