feat(sim-builder): фаза 2 — физический интегратор (SimPhysics: гравитация/пружины/столкновения, drag тел)

plans/sim-builder/phase-2-physics.md

@@ -1,6 +1,6 @@
 # Phase 2: Физический интегратор
 
-**Status:** ⬜ Not Started
+**Status:** ✅ Implemented (не закоммичено — коммит за оркестратором)
 **Parent plan:** [PLAN.md](./PLAN.md)
 **Domain:** frontend
 
@@ -10,13 +10,13 @@
 После фазы маятник/столкновения/брошенное тело идут динамически из спеки.
 
 ## Tasks
-- [ ] Блок `physics` в спеке: `{ enabled, gravity:{x,y}, friction, walls:[...], restitution }`.
-- [ ] Тело-объект: `body:{ mass, vx, vy, fixed }` — интегрируется (опора на `_fx_motion.js`, посмотреть API; не дублировать интегратор).
-- [ ] Пружины: `springs:[{ a, b, k, length }]` (между телами или телом и точкой-якорем).
-- [ ] Столкновения: упругие шары/стены (restitution), базовый бродфейз достаточно (N небольшое).
-- [ ] Drag тела: перетаскивание задаёт позицию/скорость (отпустил — летит). Кинематические (формульные) объекты Ф0 сосуществуют с физическими.
-- [ ] Траектория: накопление следа центра тела (toggle в спеке).
-- [ ] Демо-спеки: «маятник» (груз+нить как пружина/констрейнт), «упругие шары».
+- [x] Блок `physics` в спеке: `{ enabled, gravity:{x,y}, friction, walls:[...], restitution, dt?, springs? }`. gravity/friction/restitution — числа ИЛИ выражения от params (вычисляются на reset).
+- [x] Тело-объект: `body:{ mass, vx, vy, fixed }` на point/circle — интегрируется фикс-шагом (накопитель dt). Нач. позиция/vx/vy/масса — числа или выражения от params (вычисляются при reset/init, далее интегрируются). Опора на математику `_fx_motion` (полу-неявный Эйлер); см. ниже.
+- [x] Пружины: `springs:[{ a, b, k, length, damping? }]` — концы: id тела ИЛИ якорь-точка `[x,y]`. Сила Гука + демпфирование вдоль оси. Рисуются зигзагом.
+- [x] Столкновения: упругие круг-круг (по нормали, импульс + позиционная коррекция по обратным массам) и круг-стена (restitution). Broadphase O(n^2) (N мало).
+- [x] Drag тела: тащишь — задаёт позицию (тело «приколото», не интегрируется); отпустил — сообщает скорость (бросок, кламп 40 м/с). Формульные объекты Ф0/Ф1 сосуществуют (drag-ручки и физ-тела в одной сцене).
+- [x] Траектория: тело с `trail:true` пишет след центра (переиспользован существующий механизм trail; позиция берётся из env-полей тела).
+- [x] Демо-спеки за флагом: «пружинный маятник» (`customphys`: тело+пружина+гравитация+drag) и «упругие шары» (`customballs`: 3 тела + 4 стены, g/упругость от слайдеров).
 
 ## Files to Modify/Create
 - `frontend/js/labs/_sim_engine.js` — физический режим, интеграция с _fx_motion (modify)
@@ -33,10 +33,72 @@
 - Не переусложнять коллизии — школьный уровень (круги/стены).
 
 ## Review Checklist
-- [ ] Все задачи выполнены
-- [ ] Использует _fx_motion, без своего дубля интегратора без причины
-- [ ] Стабильность (нет взрыва энергии на разумных параметрах)
-- [ ] Нет регрессий Ф0/Ф1
+- [x] Все задачи выполнены
+- [x] Опирается на математику `_fx_motion.spring` (полу-неявный/симплектический Эйлер `v+=a·dt; x+=v·dt`) — обобщена на связанные тела в `SimPhysics`; API tween/spring-фабрики `_fx_motion` (rAF-замыкания на одно значение) не подходит для N связанных тел, поэтому тонкий модуль поверх той же математики, без дубля иного интегратора.
+- [x] Стабильность (нет взрыва энергии): фикс-шаг dt (кламп 1/2000..1/30), накопитель + кап подшагов (8), кламп скорости (1e4), вязкое трение через `exp(-friction·dt)`. Headless-прогон: падение/маятник/шары — конечные, без NaN/∞.
+- [x] Нет регрессий Ф0/Ф1: формульные point/segment/circle/rect/polyline/path/vector/label/plot/readout/drag работают; тела и формульные объекты в одной сцене (тест mixed).
 
 ## Handoff to Next Phase
-<!-- Заполняет реализатор -->
+
+### Что реализовано (Phase 2) — только `_sim_engine.js` + `_sim_demo.js`
+Файл `_sim_physics.js` НЕ создавался: его нельзя подключить без правки `frontend/lab.html`
+(зона параллельной сессии). Интегратор живёт внутри `_sim_engine.js` и экспортируется
+как `window.SimPhysics` (переиспользуемо headless/билдером/доской). Если Ф4+ захочет
+вынести в отдельный файл — добавить `<script>` в lab.html и `module.exports`-ветку.
+
+- **`window.SimPhysics`** — `{ step(state, dtFrame), integrate(...), resolveCollisions(...) }`.
+  Полу-неявный Эйлер (математика `_fx_motion.spring`), фикс-шаг, пружины (Гук+демпф),
+  упругие столкновения круг-круг и круг-стена. Без DOM/eval — чистая функция над state.
+- **Engine**: `_preparePhysics()` (сборка тел/пружин/стен из спеки на reset),
+  `_stepPhysics(dt)` (вызывается в rAF до `_renderFrame`; удерживаемое тело временно
+  fixed), drag тел (`_dragBody`), `_drawSprings()`, рендер point/circle-тел из состояния
+  интегратора, body-поля в `_buildEnv`.
+
+### Формат (точные поля)
+```jsonc
+// глобальный блок физики
+physics: {
+  enabled: true,                 // false/отсутствие -> чистая кинематика (Ф0/Ф1)
+  gravity: { x:0, y:-9.8 },       // число ИЛИ выражение от params (вычисляется на reset)
+  friction?: 0,                   // вязкое затухание (1/с), exp(-friction·dt); число/выражение
+  restitution?: 1,                // упругость 0..1 (кламп); число/выражение
+  dt?: 1/240,                     // фикс-шаг (кламп 1/2000..1/30)
+  walls?: [
+    { side:'bottom'|'top'|'left'|'right' },  // из границ viewport
+    { x1,y1, x2,y2 }                          // произвольный отрезок (нормаль к центру)
+  ],
+  springs?: [
+    { a:'bodyId'|[x,y], b:'bodyId'|[x,y],     // конец: id тела ИЛИ якорь-точка
+      k:40, length:5, damping?:0.4 }          // k/length/damping — число/выражение
+  ]
+}
+// тело на point/circle (интегрируется, НЕ формула)
+{ id:'bob', type:'circle', r:0.6, x:'3', y:'-4',   // нач. позиция — число/выражение
+  trail?:true, trailColor?:'#...',                  // след тела (механизм Ф0)
+  body:{ mass?:1, vx?:0, vy?:0, fixed?:false } }    // масса/vx/vy — число/выражение
+```
+
+### env-поля тел (доступны readout/plot/label/привязкам)
+Для каждого тела в env кладутся `<id>.x`, `<id>.y`, `<id>.vx`, `<id>.vy` ИЗ СОСТОЯНИЯ
+ИНТЕГРАТОРА (не из выражения). Кладутся ПЕРВЫМИ в `_buildEnv` — снимает forward-ref
+проблему однопроходного env: формульные объекты, ссылающиеся на тело, видят его
+актуальную позицию/скорость в этом же кадре.
+
+### Гочи / решения / риски
+- **Имя param `e` зарезервировано** (число Эйлера в SimExpr). Не использовать `e` как
+  имя параметра в выражениях физики — взять `el`/`elast` и т.п. (демо «шары» учтено).
+- **Радиус тела для коллизий**: circle — мировой `r`; point — экранные px → переводятся
+  в мир через текущий масштаб (фолбэк 0.3) при `_preparePhysics`. Зависит от `_scale`,
+  поэтому физика собирается ПОСЛЕ `_fit()` (в reset, который зовётся после первого fit).
+- **Изменение params на лету**: gravity/k/length/restitution/масса/нач.условия пересчит. на
+  **reset** (и на паузе в `t==0` — для предпросмотра старта). Во время проигрывания слайдеры
+  меняют только сами params в env (для readout/формул), но не телепортируют тела/не меняют силы
+  до следующего reset. Это намеренно (стабильность). Если Ф4 захочет live-силы — пересобирать
+  `opts`/springs каждый кадр (тела не трогать).
+- **Drag во время play**: удерживаемое тело временно `fixed`; на отпускании — скорость из
+  сглаженной оценки движения курсора (кламп 40 м/с).
+- **Сериализация для Ф3 (БД/API)**: в спеке надо хранить/валидировать блок `physics`
+  (gravity x/y, friction, restitution, dt, walls[], springs[]) и `body{}` на объектах
+  (mass, vx, vy, fixed — числа или строки-выражения). Глубину/число springs/walls и
+  диапазоны (k, mass>0, restitution 0..1, dt) — проверять на сервере как и остальные
+  выражения. Строки-выражения санитизировать так же, как x/y/expr Ф0/Ф1.