@

feat(quantik-game): фаза 0 — слой целей в движке (goal/HUD/result)

Декларативный блок goal в спеке SimForge (булево SimExpr-условие победы),
вычисляемый каждый кадр: фиксация результата (победа/время/попытки/звёзды),
callback onGoal, HUD-оверлей (цель/звёзды/подсказка/баннер, inline SVG).
API инстанса: onGoal/getResult/resetResult. Серверный validateSpec
пропускает goal/game (длина выражений + escape текста, без исполнения).
Аддитивно: спека без goal ведёт себя как раньше. Смоук 40/40; npm test
238 pass/8 baseline; lint:routes 0. План фичи (7 фаз) + CONTEXT.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@

plans/quantik-game/CONTEXT.md

@@ -0,0 +1,61 @@
+# Feature Context: Квантик — Законы Мира
+
+## Current State
+- Ветка `feature/quantik-game` ответвлена от `feature/sim-builder` (движок P1–P3 там, не в master).
+- При ответвлении унаследован **чужой uncommitted WIP** sim-builder: `frontend/js/sim-builder.js`,
+  `frontend/sim-builder.html`, `.claude/settings.json` + множество untracked `tmp_*`/мусорных файлов.
+  ⛔ НЕ трогать и НЕ коммитить этот WIP — стейджить только свои файлы поимённо.
+- **Phase 0 реализован** (pending review): слой целей в движке `_sim_engine.js` (блок `goal`,
+  компиляция when/fail/stars через SimExpr, состояние результата, HUD-оверлей, API
+  `onGoal/getResult/resetResult`) + серверный гейт `validateSpec` пропускает `goal`/`game`.
+  Изменены: `frontend/js/labs/_sim_engine.js`, `backend/src/controllers/customSimController.js`.
+  Аддитивно: спека без `goal` ведёт себя ровно как раньше (HUD не создаётся, побед не считается).
+  Смоук 40/40; `npm test` 238 pass / 8 baseline fail; lint:routes 0.
+
+## Key Architecture Decisions
+- **«Атом» = блок `goal` в спеке** (булево SimExpr). Любой уровень = спека SimForge + `goal`.
+  Движок вычисляет `goal.when` каждый кадр; победа → result + callback. Нет `goal` → no-op.
+- **Уровни хранятся в `custom_sims`** (cat='game'), а не в новой таблице. Реюз авторинга/шаринга/embed.
+  Новые таблицы — только под ПРОГРЕСС игрока и лидерборд (мигр.).
+- **Герой Квантик**: в уровне = engine point с `body` + glow + trail (визуал P2). На карте/в
+  диалогах = `PetSprite.render(level, mood, accessories, colorKey, streak, pattern)` (DOM SVG).
+- **Управление = чинить закон**, а не WASD: игрок крутит `params`-слайдеры движка (угол/скорость/
+  гравитация) или собирает `f(x)`; затем «Запуск» — симуляция проигрывается к цели.
+- **Безопасность**: цвета — только в canvas-стоки; текст спеки — escape (`& < >`); выражения —
+  только длина на сервере, исполняет безопасный SimExpr на клиенте.
+
+## Engine touch-points (Phase 0)
+- Спека v1 формат — в шапке `_sim_engine.js`. Добавить `goal`/`game` СЮДА (документировать).
+- rAF-цикл `_renderFrame` (вычисляет env). Добавить `_evalGoal()` после построения env.
+- `mount()` возвращает инстанс — добавить `onGoal`, `getResult`, `resetResult`.
+- HUD — DOM-оверлей `_labelLayer`/новый слой (как readout-бейджи). Без эмодзи, inline SVG.
+- Серверный гейт `customSimController.validateSpec` (:93) — разрешить `goal`/`stars`/`hint`/`game`.
+
+## Cross-Phase Dependencies
+- Phase 1+ зависят от `goal`/`getResult`/`onGoal` из Phase 0.
+- Phase 2 (XP/скины) зависит от прогресса Phase 1.
+- Phase 4 (туннелирование) зависит от флешкарт-SR API.
+- Phase 5 (авторинг) трогает sim-builder — к этому моменту чужой P4-WIP должен быть смержен в
+  sim-builder; свериться перед стартом фазы (возможен мерж base-ветки).
+- Phase 6 (живая гонка) зависит от моста `sim_state` (Ф7 sim-builder) — он на base-ветке.
+
+## Temporary Workarounds
+(пока нет)
+
+## Phase 0 — API/гочи (для следующих фаз)
+- Движковое API цели: `inst.onGoal(cb)` (1 раз при победе, cb получает `getResult()`),
+  `inst.getResult()` → `{won,failed,timeMs,attempts,stars:{got,total}}` (без goal → `null`),
+  `inst.resetResult()` (сброс результата, НЕ считается попыткой). `inst.reset()` = полный
+  перезапуск уровня + `attempts++` (пользовательская попытка; первый авто-reset при mount НЕ считается).
+- HUD появляется **автоматически** при наличии `goal` в спеке (отдельного флага «game mode» нет).
+- `timeMs` = **мировое время** `t` от старта (`max(1, round(t*1000))`), детерминизм; не wallclock.
+- Env цели = весь env кадра + единственный доп.идентификатор **`tries`** (= attempts). Других не вводить.
+- Серверный `validateSpec` принимает `goal{when,title,hint,hold,fail,stars≤3}` и `game{...}` (резерв Ф1/5);
+  выражения не исполняются (только длина ≤500), текст escape+обрезка.
+- Победа делает `pause()` в кадре; следующий queued-rAF выходит рано → `onGoal` не задвоится.
+
+## Open Questions / Notes
+- Категория `cat='game'` — проверить список `CATS` в customSimController.js, расширить при необходимости.
+- Ассеты: разрешены CC0/открытые из интернета (выбор пользователя) — фиксировать источник+лицензию
+  в коммите/доке; визуальная база остаётся in-house (PetSprite/canvas/FLUX).
+- Маршрут страницы игры: clean URL `/quantik` (паттерн `/sim-builder`, `/lab`).

plans/quantik-game/PLAN.md

@@ -0,0 +1,91 @@
+# Feature: Квантик — Законы Мира (образовательная 2D-игра)
+
+**Branch:** `feature/quantik-game`
+**Base branch:** `feature/sim-builder` (движок P1–P3 и фазы sim-builder ещё не в master)
+**Created:** 2026-06-13
+**Status:** 🟡 In Progress
+**Strategy:** Incremental
+**Mode:** Automated
+**Execution:** Orchestrator
+
+## Summary
+2D физика-головоломка-платформер поверх движка **SimForge** (`_sim_engine.js`). Герой —
+**Квантик** (существующий питомец `PetSprite`): в уровне он светящаяся точка с glow и
+кометной трассой (P2), на карте/в диалогах — SVG-блоб `PetSprite.render`. Игрок не рулит
+героем напрямую, а **чинит «закон мира»**: задаёт скорость/угол/гравитацию (физ-уровни на
+`SimPhysics`), собирает `f(x)` для движения по кривой (граф-уровни на `plot`/`SimExpr`),
+открывает «ворота» уравниванием реакций/дробей. **Условие победы — булев блок `goal`
+(SimExpr) в спеке** — это «атом», переиспользуемый всеми типами уровней.
+
+Уровень = спека SimForge + блок `game/goal` → авторится в sim-builder, хранится в
+`custom_sims`, открывается тем же конвейером, что и обычные симуляции. Всё новое —
+**аддитивно и безопасно** (без `eval`/`Function`; нет блока `goal` → движок ведёт себя
+как раньше).
+
+Мета-слой: карта-созвездие, XP/скины Квантика, разблокировка по звёздам, класс-лидерборд
+через classroom SSE. Квантовые способности: суперпозиция, коллапс/пауза, туннелирование
+(энергия из быстрого SR-повторения флешкарт).
+
+**MVP играбелен после Фазы 2.**
+
+## Build & Test Commands
+- **Build:** нет (vanilla JS, без бандлера; статика через Express)
+- **Test:** `npm test` в `backend/` (`node --test tests/*.test.js`)
+- **Lint:** `npm run lint:routes` в `backend/`
+- ⚠️ После роутов/миграций: `npm run migrate` (живая БД `backend/data/learnspace.db`) + рестарт сервера.
+- ⚠️ baseline: 3 pre-existing fail (`auth.test.js` — bcrypt/JWT в тест-окружении) + 5 page-тестов (`jsdom` не установлен). Хук толерантен.
+
+## Project Constraints (соблюдают ВСЕ агенты)
+- ⛔ Никаких эмодзи в коде — только inline SVG `.ic`.
+- ⛔ Никакого `eval`/`new Function`. Выражения — ТОЛЬКО через `SimExpr` (безопасный парсер).
+- Поиск по коду: `ast-index` (символы/usages/callers) + `vex` (semantic). НЕ Grep tool.
+- БД — встроенный `node:sqlite` (`DatabaseSync`), НЕ better-sqlite3.
+- Frontend — vanilla JS, `window.LS.*` (js/api.js), без бандлера.
+- Стейджить файлы **поимённо** (НЕ `git add -A` — в репо много мусорных untracked + чужой WIP sim-builder).
+- Аддитивность: новые блоки/типы в спеке не ломают существующие симуляции и каталог.
+- Ассеты: база — in-house (PetSprite + canvas/SVG + встроенный FLUX `/api/imggen`).
+  Разрешены внешние **CC0/открытые** ассеты (звук/арт) с указанием источника/лицензии.
+
+## Reuse Map (что переиспользуем)
+- `frontend/js/labs/_sim_engine.js` — рантайм (SimPhysics, plot, glow/trails, zoom/pan, drag).
+- `frontend/js/labs/_sim_expr.js` — `SimExpr.compile/evalSafe` для `goal`/`stars`.
+- `frontend/js/pet-sprite.js` — `PetSprite.render(...)` Квантик + палитры → скины/нарратор.
+- `custom_sims` + `customSimController.validateSpec` — хранение уровней + серверный гейт.
+- `sim-builder.html`/`sim-builder.js` — авторинг уровней (Фаза 5).
+- Флешкарты Tier-1 SR (мигр.074) — энергия туннелирования (Фаза 4).
+- classroom SSE + мост `sim_state`/`apply_sim_state` (Ф7 sim-builder) — живая гонка (Фаза 6).
+- Паттерн раздачи классу + `pushNotif` + `lab_sim_links` (Ф6 sim-builder).
+
+## Phases
+
+- [x] Phase 0: Слой целей в движке (goal/HUD/result) [domain: frontend] → [subplan](./phase-0-objective-layer.md)
+- [ ] Phase 1: Оболочка игры + 1 физ-уровень + прогресс [domain: fullstack] → [subplan](./phase-1-shell-first-level.md)
+- [ ] Phase 2: Карта-созвездие + мир физ-уровней + XP/скины [domain: fullstack] → [subplan](./phase-2-map-world-xp.md)
+- [ ] Phase 3: Граф-уровни (движение по f(x)) + зоны-препятствия [domain: fullstack] → [subplan](./phase-3-graph-levels.md)
+- [ ] Phase 4: Квантовые способности + SR-комнаты [domain: fullstack] → [subplan](./phase-4-quantum-abilities-sr.md)
+- [ ] Phase 5: Авторинг уровней в sim-builder + раздача классу [domain: fullstack] → [subplan](./phase-5-authoring-sharing.md)
+- [ ] Phase 6: Класс-лидерборд / живая гонка (classroom SSE) [domain: fullstack] → [subplan](./phase-6-leaderboard-live.md)
+
+## Phase Progress Log
+
+| Phase | Domain | Status | Review | Build | Committed |
+|-------|--------|--------|--------|-------|-----------|
+| Phase 0: Слой целей в движке | frontend | ✅ Done | ✅ | ✅ | ✅ |
+| Phase 1: Оболочка + 1 уровень + прогресс | fullstack | ⬜ Not Started | ⬜ | ⬜ | ⬜ |
+| Phase 2: Карта + мир + XP/скины | fullstack | ⬜ Not Started | ⬜ | ⬜ | ⬜ |
+| Phase 3: Граф-уровни + зоны | fullstack | ⬜ Not Started | ⬜ | ⬜ | ⬜ |
+| Phase 4: Квантовые способности + SR | fullstack | ⬜ Not Started | ⬜ | ⬜ | ⬜ |
+| Phase 5: Авторинг + раздача | fullstack | ⬜ Not Started | ⬜ | ⬜ | ⬜ |
+| Phase 6: Лидерборд / живая гонка | fullstack | ⬜ Not Started | ⬜ | ⬜ | ⬜ |
+
+## MVP boundary
+После **Phase 2** игра играбельна и отгружаема: один полный мир физ-уровней с картой,
+прогрессом, XP и скинами. Фазы 3–6 — расширение (новые типы уровней, способности,
+авторинг, мультиплеер).
+
+## Final Review
+- [ ] Comprehensive code review (final-reviewer)
+- [ ] Security review (новые API: прогресс/лидерборд, user-input)
+- [ ] `npm test` без новых регрессий (поверх baseline)
+- [ ] `npm run lint:routes` baseline 0
+- [ ] Merged to `feature/sim-builder`

plans/quantik-game/phase-0-objective-layer.md

@@ -0,0 +1,135 @@
+# Phase 0: Слой целей в движке (goal / HUD / result)
+
+**Status:** ✅ Done (reviewed — PASS, committed)
+**Parent plan:** [PLAN.md](./PLAN.md)
+**Domain:** frontend
+
+## Objective
+Ввести в `_sim_engine.js` **«атом» игры** — декларативный блок `goal` (условие победы как
+булево SimExpr-выражение), вычисляемый каждый кадр, с фиксацией результата (победа/время/
+попытки/звёзды), callback'ом и HUD-оверлеем. Расширить серверный гейт `validateSpec`, чтобы
+блок проходил валидацию. Всё аддитивно: спека без `goal` ведёт себя как раньше.
+
+## Спека (контракт, документировать в шапке `_sim_engine.js`)
+```
+goal: {
+  when:  '<bool expr>',          // SimExpr: победа, когда станет истинным (≠0)
+  hint?: 'текст подсказки',      // показывается в HUD (escape на сервере)
+  title?: 'Цель уровня',         // краткая формулировка цели для HUD
+  hold?: 0.0,                    // сек, сколько условие должно держаться (деф. 0 = мгновенно)
+  stars?: [                      // 0..3 доп.условий-«звёзд» (бонусы)
+    { when:'<bool expr>', label?:'...' }
+  ],
+  fail?: '<bool expr>'           // опц.: мгновенный проигрыш (вышел за поле/задел шип)
+}
+```
+- `when`/`stars[].when`/`fail` — компилируются ОДИН раз при mount (как все выражения), env тот же.
+- Доп. env-поля для целей: `t` (время), `tries` (число reset с начала), плюс всё что уже в env
+  (`<obj>.x/.y/.vx/.vy`, params, w/h, xmin..ymax). НЕ вводить новых небезопасных идентификаторов.
+- Звезда «залипает»: однажды истинное условие звезды остаётся засчитанным до reset (накопитель).
+
+## Tasks
+- [x] Task 1: В шапке `_sim_engine.js` задокументировать блок `goal` (формат v1, как сделано для physics/plot).
+- [x] Task 2: В `prepare`/mount компилировать `goal.when`, `goal.fail`, каждое `stars[].when`
+      через `SimExpr.compile` (хранить fn + error; кривое выражение → никогда не бросает).
+- [x] Task 3: Добавить состояние результата на инстанс: `_goalState = { won, failed, timeMs,
+      attempts, starsGot:[], firstWinT }`. Сбрасывать в `reset()` (attempts++ на reset, кроме первого).
+- [x] Task 4: В rAF-цикле (`_renderFrame`/`_stepPhysics`-соседство) после построения env и шага:
+      вычислить звёзды (накопить), `fail` (→ мягкий проигрыш-оверлей, не победа), `when`
+      (учесть `hold` — таймер удержания) → при победе зафиксировать `timeMs` (мировое t или
+      wallclock от старта play), выставить `won=true`, остановить (`pause`) и вызвать `onGoal` callback.
+- [x] Task 5: HUD-оверлей (DOM, поверх canvas, как слой readout): строка цели (`title`),
+      индикатор звёзд (inline SVG звезда — заполненная/контур), подсказка (`hint`),
+      баннер «Победа»/«Ещё раз» с кнопкой Reset. Стиль — тёмная плашка как у readout; без эмодзи.
+      HUD появляется ТОЛЬКО при наличии `goal` в спеке.
+- [x] Task 6: Публичное API инстанса: `onGoal(cb)` (cb получает `getResult()`), `getResult()`
+      → `{ won, failed, timeMs, attempts, stars:{got,total} }`, `resetResult()`.
+- [x] Task 7: `destroy()` снимает HUD-узлы/слушатели кнопок (нет утечек).
+- [x] Task 8: Сервер `backend/src/controllers/customSimController.js` `validateSpec`:
+      разрешить ключ `goal` (объект) и `game` (объект, см. Phase 1/5) на верхнем уровне спеки;
+      проверять `when`/`fail`/`stars[].when` через `checkExpr` (длина ≤ MAX_EXPR_LEN);
+      `hint`/`title`/`stars[].label` — `sanitizeText` (escape + обрезка); `stars` ≤ 3; `hold` число.
+      НЕ исполнять выражения. Обновить whitelist при необходимости.
+- [x] Task 9: Headless-смоук (vm + ручной DOM/canvas-стаб + РЕАЛЬНЫЕ `_sim_expr.js`+`_sim_engine.js`,
+      как в P1–P3): (а) спека с `goal.when` достигает победы → `getResult().won`, `timeMs>0`;
+      (б) звёзды накапливаются и не сбрасываются до reset; (в) `fail` ставит failed без won;
+      (г) `hold` требует удержания; (д) спека БЕЗ goal — поведение без изменений, HUD не создан;
+      (е) `onGoal` зовётся один раз; (ж) destroy снимает HUD-слушатели (баланс add/remove).
+      Удалить temp-смоук после прогона. → 40/40 PASS, удалён.
+
+## Files to Modify/Create
+- `frontend/js/labs/_sim_engine.js` — блок goal: документация, компиляция, eval в цикле, HUD, API.
+- `backend/src/controllers/customSimController.js` — `validateSpec`: разрешить `goal`/`game`.
+- (temp) headless-смоук — создать, прогнать, удалить.
+
+## Acceptance Criteria
+- Спека с `goal` показывает цель/звёзды/победу; `getResult()` корректен; `onGoal` срабатывает.
+- Спека без `goal` рендерится и ведёт себя ровно как раньше (нет HUD, нет накладных вычислений побед).
+- `validateSpec` пропускает корректный `goal`, режет переразмер/длинные выражения, экранирует текст.
+- `node --check` обоих файлов OK; headless-смоук зелёный; эмодзи нет; `eval`/`new Function` нет.
+- `cd backend && npm test` — без новых регрессий; `npm run lint:routes` — без новых ошибок.
+
+## Notes
+- Время победы: предпочесть **мировое `t`** (детерминизм, headless-тест), плюс можно хранить wallclock.
+- `attempts` = число `reset()` (первый mount/авто-reset не считать попыткой; считать пользовательские).
+- HUD не должен перехватывать pan/drag сцены вне своих интерактивных элементов (pointer-events: none
+  на контейнере, auto — на кнопках), как сделано с overlay-панелью в P1.
+- Не вводить новые env-идентификаторы помимо `t`/`tries` — безопасность контракта выражений.
+
+## Review Checklist
+- [x] Все задачи выполнены
+- [x] Код следует конвенциям движка (хелперы модульного уровня `_truthy`, инстанс-методы, без рисования по canvas — HUD это DOM-оверлей как readout)
+- [x] Аддитивность: существующие симуляции/каталог не затронуты (нет goal → `_goal=null`, HUD не создаётся, в rAF ветка `if (self._goal)` пропускается)
+- [x] Без эмодзи; без eval/Function (звёзды/иконки — inline SVG; выражения только через `SimExpr.compile`)
+- [x] Build (node --check) и тесты проходят (смоук 40/40; `npm test` 238 pass / 8 baseline fail; lint:routes 0)
+
+## Handoff to Next Phase
+
+### Движковое API цели (для Phase 1)
+Всё в `frontend/js/labs/_sim_engine.js`. `var inst = SimEngine.mount(host, spec)`:
+
+- **`inst.onGoal(cb)`** — подписка. `cb` получает `getResult()` и вызывается РОВНО ОДИН РАЗ при
+  первой победе (после `pause()`). Возвращает `inst` (chainable). Можно подписать несколько cb.
+- **`inst.getResult()`** → `{ won:bool, failed:bool, timeMs:number, attempts:number, stars:{got:number, total:number} }`.
+  Для спеки БЕЗ `goal` возвращает **`null`** — проверяйте на null перед использованием.
+- **`inst.resetResult()`** — сбросить результат как новый уровень (won/failed/звёзды/таймер обнуляются),
+  но **НЕ считается попыткой** (attempts сохраняется). Для перезапуска уровня используйте `inst.reset()`
+  (это И сбрасывает физику/время И инкрементит attempts как пользовательскую попытку).
+
+### Как включить «игровой режим» / HUD
+HUD появляется **автоматически**, как только в спеке есть верхнеуровневый блок `goal`. Отдельного
+флага «game mode» в движке НЕТ. Никакого вызова не нужно — `mount()` сам создаёт HUD при наличии `goal`.
+HUD = DOM-оверлей внутри `inst.el` (контейнер `pointer-events:none`, кнопка «Ещё раз» — `pointer-events:auto`,
+дёргает `inst.reset()`). Спрятать HUD = убрать `goal` из спеки.
+
+### Как измеряется timeMs
+**Мировое время** `t` от старта уровня (детерминизм для headless/реплеев): при победе
+`timeMs = max(1, round(t*1000))`. Это НЕ wallclock — паузы/тротлинг rAF не влияют. `firstWinT`
+(сырое мировое `t` победы) хранится внутри в `_goalState`, наружу отдаётся только `timeMs`.
+
+### Форма блока goal/game (что сервер теперь принимает)
+`validateSpec` (`backend/src/controllers/customSimController.js`) пропускает на верхнем уровне:
+```
+goal: {
+  when:  '<bool SimExpr>',        // ≤500 симв., НЕ исполняется на сервере
+  title?: '...', hint?: '...',    // sanitizeText: escape & < > + обрезка (title≤120, hint≤300)
+  hold?:  0,                      // число (сек удержания when); не-число → 400
+  fail?:  '<bool SimExpr>',       // ≤500 симв.
+  stars?: [ { when:'<bool SimExpr>', label?:'...' } ]   // ≤3 (иначе 400); label sanitizeText ≤120
+}
+game?: { ... }                    // зарезервирован под мета-слой Ф1/5; проходит как есть
+                                  // (под общими лимитами размер/глубина), НЕ исполняется
+```
+Категория `cat='game'` уже в `CATS` (math/phys/chem/bio/game) — расширять не нужно.
+
+### Env-контракт цели (безопасность)
+Выражения `goal.when`/`fail`/`stars[].when` видят ВЕСЬ env кадра (params, `t`, `w/h`, `xmin..ymax`,
+`<obj>.x/.y/.vx/.vy`) ПЛЮС единственный доп.идентификатор **`tries`** (= `attempts`). НЕ вводить
+новых идентификаторов в env цели — это контракт безопасности шаренных выражений.
+
+### Гочи для Phase 1
+- Победа ставит `pause()` внутри rAF-кадра; следующий queued-кадр выходит по `if (!self._running) return`
+  → `onGoal` не задвоится. НЕ вызывайте `play()` в `onGoal`-колбэке без `resetResult()`/`reset()`.
+- `goal.when` без `hold` срабатывает на ПЕРВОМ же кадре, где условие истинно (мгновенно).
+- Звёзды «залипают»: засчитываются и во время play (rAF), и на паузе/предпросмотре (`_renderFrame`).
+- Истинность булева = `_truthy`: конечное ненулевое число (SimExpr возвращает 0 при NaN/∞/ошибке).

plans/quantik-game/phase-1-shell-first-level.md

@@ -0,0 +1,63 @@
+# Phase 1: Оболочка игры + 1 физ-уровень + прогресс (MVP)
+
+**Status:** ⬜ Not Started
+**Parent plan:** [PLAN.md](./PLAN.md)
+**Domain:** fullstack
+
+## Objective
+Сквозной играбельный срез: страница `/quantik` грузит уровень-спеку, монтирует движок в
+«игровом режиме» (управление = слайдеры закона + кнопка «Запуск»), на победу шлёт результат
+на сервер, показывает экран успеха со звёздами/временем. Прогресс сохраняется в БД.
+Первый уровень — «Артиллерия Квантика»: угол+скорость, попасть в портал, собрать звезду.
+
+## Tasks
+- [ ] Task 1: Миграция (следующий свободный номер) `game_progress`: `id, user_id, level_id TEXT,
+      best_time_ms INTEGER, best_stars INTEGER, attempts INTEGER, completed_at`. Индекс по (user_id, level_id) UNIQUE.
+- [ ] Task 2: Контроллер `gameController.js` + роутер `game.js`, смонтировать в `server.js`
+      (после `/api/custom-sims`). Эндпоинты: `GET /api/game/progress` (свой прогресс по всем
+      уровням), `POST /api/game/progress` `{level_id, time_ms, stars}` (upsert: пишем лучший
+      результат — min time / max stars; attempts++). auth-only; валидация входа.
+- [ ] Task 3: Клиент `LS.gameProgressList()` / `LS.gameProgressSubmit(levelId, {time_ms, stars})` в js/api.js.
+- [ ] Task 4: Уровень как ДАННЫЕ: модуль `frontend/js/game/levels.js` (или сид в `custom_sims`).
+      Для MVP — встроенная спека уровня `phys-artillery-1` (physics + goal + 1 star + portal/star объекты).
+      Решение источника уровней зафиксировать в CONTEXT.md (встроенные данные сейчас; custom_sims в Ф5).
+- [ ] Task 5: Страница `frontend/quantik.html` + `frontend/js/game/quantik-game.js`:
+      доступ всем авторизованным (LS.initPage()); подключает `_sim_expr.js`+`_sim_engine.js`
+      тем же путём, что lab.html/sim-builder.html. Монтирует уровень, ставит `onGoal` → submit + экран успеха.
+- [ ] Task 6: «Игровой режим» движка/обёртки: цель видна (HUD из Ф0), управление = существующие
+      слайдеры params; кнопки «Запуск»(play)/«Сброс»(reset). Без редакторских панелей.
+- [ ] Task 7: Экран успеха (DOM-оверлей страницы): звёзды, время, попытки, кнопки «Ещё раз»/«Дальше»
+      (для MVP «Дальше» неактивна/возврат). Inline SVG, без эмодзи.
+- [ ] Task 8: Пункт в сайдбаре `js/sidebar.js` — `/quantik` в группе practice (по примеру `/sim-builder`),
+      видимость по роли (доступно ученикам — это игра). `isActive('/quantik')` подсветка.
+- [ ] Task 9: Тест бэкенда `backend/tests/game.test.js` (паттерн lab-links.test.js: свой app.use
+      нового роутера, getToken/inject): submit пишет лучший результат, не ухудшает, attempts++,
+      требует auth, валидирует вход. Headless-смоук страницы по возможности (vm + стаб), иначе ручная проверка логики.
+
+## Files to Modify/Create
+- `backend/src/db/migrations/0NN_game_progress.sql` — таблица прогресса.
+- `backend/src/controllers/gameController.js`, `backend/src/routes/game.js` — API.
+- `backend/src/server.js` — монтаж роутера.
+- `frontend/quantik.html`, `frontend/js/game/quantik-game.js`, `frontend/js/game/levels.js` — клиент+уровень.
+- `frontend/js/api.js` — `LS.gameProgress*`.
+- `frontend/js/sidebar.js` — пункт меню.
+- `backend/tests/game.test.js` — тест.
+
+## Acceptance Criteria
+- `/quantik` грузится, монтирует уровень, цель видна; «Запуск» проигрывает физику.
+- Попадание в портал (+звезда) → экран успеха с временем/звёздами; результат записан в `game_progress`.
+- Повторный худший результат не перезаписывает лучший; attempts растёт.
+- `npm run migrate` применяет миграцию; `npm test` зелёный (+ новый тест); `lint:routes` baseline 0.
+
+## Notes
+- Маршрутизация `/js/game/*`: помнить гочу sim-builder — `/js` мапится на корневой `js/`, а файлы
+  лежат во `frontend/js/game/` → отдаются через `express.static(frontendDir)`. Не трогать server.js static.
+- Роуты `:id` прикрыть `authMiddleware` на уровне роутера (lint:routes baseline 0).
+- Время — из `getResult().timeMs` (Ф0).
+
+## Review Checklist
+- [ ] Все задачи; конвенции (ownership/auth как studentMaterials/customSim); без эмодзи/eval
+- [ ] Миграция применяется; API безопасен; тест зелёный; lint baseline 0; existing тесты не сломаны
+
+## Handoff to Next Phase
+<!-- Заполняет агент-имплементер. -->

plans/quantik-game/phase-2-map-world-xp.md

@@ -0,0 +1,56 @@
+# Phase 2: Карта-созвездие + мир физ-уровней + XP/скины (MVP-мир)
+
+**Status:** ⬜ Not Started
+**Parent plan:** [PLAN.md](./PLAN.md)
+**Domain:** fullstack
+
+## Objective
+Превратить одиночный уровень в **играбельный мир**: карта-созвездие из ~5–6 физ-уровней,
+разблокировка по звёздам, XP, выбор скина Квантика, нарратор-Квантик (`PetSprite`) на интро/
+победе. После этой фазы игра полноценно отгружаема.
+
+## Tasks
+- [ ] Task 1: Контент — ~5–6 физ-уровней-спек (данные в `levels.js`), нарастающая сложность:
+      артиллерия → перелёт через стену → отскок (restitution) → пружина/маятник → орбита/гравитация.
+      Каждый: `goal` + 1–3 звезды + норматив времени (`par_ms`) для 3-й звезды.
+- [ ] Task 2: Структура «мир/глава»: метаданные уровня (id, title, chapter, order, par_ms, hint).
+      Карта группирует по главам (созвездиям).
+- [ ] Task 3: Карта-созвездие `frontend/js/game/map.js` (+ разметка в quantik.html): узлы-уровни
+      на SVG/canvas-фоне, линии-связи, статус (заблокирован/доступен/пройден + число звёзд).
+      Разблокировка: уровень открыт, если набрано ≥ threshold звёзд в предыдущих (правило в данных).
+- [ ] Task 4: XP/уровень игрока: XP = сумма звёзд × коэффициент (+ бонус за par). Хранить в
+      прогрессе (расширить `game_progress` агрегацией на клиенте ИЛИ доб. поле/таблицу `game_player`).
+      Полоса XP + «уровень Квантика» в шапке карты.
+- [ ] Task 5: Скины Квантика: выбор `colorKey` из палитр `PetSprite` (+ позже паттерны). Скин
+      влияет на цвет glow-точки героя в уровне (param/проп движка) и на `PetSprite` на карте.
+      Хранить выбор (localStorage сейчас; серверно — опц.). Разблокировка скинов по XP/звёздам.
+- [ ] Task 6: Нарратор: `PetSprite.render(...)` в интро уровня (краткая формулировка «почини закон…»)
+      и на экране победы (реакция по числу звёзд: happy/ecstatic). Реюз mood из pet-sprite.js.
+- [ ] Task 7: Навигация: карта → уровень → результат → возврат на карту с обновлённым статусом/XP.
+- [ ] Task 8: Тесты: разблокировка (логика чистой функцией — юнит-тест), агрегация XP; смоук карты.
+
+## Files to Modify/Create
+- `frontend/js/game/levels.js` — контент мира (расширить).
+- `frontend/js/game/map.js` — карта-созвездие.
+- `frontend/js/game/quantik-game.js` — навигация карта↔уровень, XP/скин в шапке.
+- `frontend/quantik.html` — разметка карты/шапки.
+- (опц.) `backend` — поле/агрегация игрока, если решим серверно; иначе клиентская агрегация прогресса.
+- тест(ы) разблокировки/XP.
+
+## Acceptance Criteria
+- Карта показывает мир, статусы и звёзды; пройденные уровни открывают следующие.
+- XP/уровень Квантика растут; смена скина видна и на карте, и в уровне.
+- Нарратор-Квантик появляется на интро/победе с корректным настроением.
+- Тесты разблокировки/XP зелёные; lint baseline 0; existing тесты не сломаны.
+
+## Notes
+- Без эмодзи — звёзды/иконки только inline SVG (`.ic`).
+- Разблокировку держать **данными/чистой функцией** (легко тестировать и переносить на сервер).
+- Не плодить серверные таблицы без нужды: прогресс уже в `game_progress` (Ф1); XP можно агрегировать.
+
+## Review Checklist
+- [ ] Все задачи; чистая функция разблокировки покрыта тестом; без эмодзи/eval
+- [ ] Карта/навигация работают; existing тесты целы; lint baseline 0
+
+## Handoff to Next Phase
+<!-- Заполняет агент-имплементер. -->

plans/quantik-game/phase-3-graph-levels.md

@@ -0,0 +1,49 @@
+# Phase 3: Граф-уровни (движение по f(x)) + зоны-препятствия
+
+**Status:** ⬜ Not Started
+**Parent plan:** [PLAN.md](./PLAN.md)
+**Domain:** fullstack
+
+## Objective
+Новый тип уровня: Квантик движется по кривой `y=f(x)`, которую **собирает игрок** (настраивает
+параметры/выбирает выражение). Препятствия — «запретные зоны»; цель/звёзды/проигрыш — выражения.
+Реюз `plot` + `SimExpr`. Сид граф-главы.
+
+## Tasks
+- [ ] Task 1: «Бегунок по кривой»: герой-точка с `x` = функция t (напр. линейный проход xmin→xmax),
+      `y = f(x)` через ту же скомпилированную функцию, что у `plot`. Кривая рисуется (P3 plot),
+      герой едет по ней с glow/trail. Без физики (кинематический проход), либо мягкая физика — на выбор уровня.
+- [ ] Task 2: Тип объекта/поле «зона» (forbidden/target): прямоугольник/круг в мире + удобные
+      env-предикаты (или документированный паттерн: `fail:'inzone(...)'`). Реализовать helper-предикаты
+      БЕЗ расширения небезопасного синтаксиса — предпочесть готовить булевы поля зон в env
+      (напр. `zone1.hit`) на основе позиции героя, чтобы `goal`/`fail` ссылались на них.
+- [ ] Task 3: Цель = добраться до конца/в целевую зону, не задев запретные (`fail`). Звёзды: пройти
+      под нормативом, собрать бонус-точки (зоны-сборы).
+- [ ] Task 4: Управление: слайдеры коэффициентов `f(x)` (a·sin(b·x+c)+d и т.п.) ИЛИ выбор/набор
+      выражения с inline-проверкой `SimExpr.compile(...).error` (как в sim-builder). Безопасно.
+- [ ] Task 5: Контент: сид граф-главы (~4–5 уровней): синус под мостом, парабола над ямой,
+      кусочная подгонка, экспонента/логарифм — растущая сложность, привязка к темам алгебры.
+- [ ] Task 6: Интеграция в карту (Ф2): новая глава-созвездие; общий конвейер результата/XP.
+- [ ] Task 7: Тесты: проход по кривой достигает цели; задевание зоны → fail; смоук рендера кривой+героя.
+
+## Files to Modify/Create
+- `frontend/js/labs/_sim_engine.js` — поддержка «бегунка по кривой» (если не выразимо текущими полями)
+  и подготовка булевых полей зон в env. Аддитивно, документировать в шапке.
+- `frontend/js/game/levels.js` — граф-глава.
+- `frontend/js/game/quantik-game.js` / `map.js` — новая глава, управление коэффициентами.
+- тест(ы).
+
+## Acceptance Criteria
+- Квантик едет по собранной игроком кривой; правильная `f(x)` проводит между препятствиями к цели.
+- Задевание запретной зоны → проигрыш; норматив/сборы дают звёзды.
+- Кривая безопасна (SimExpr, без eval); existing симуляции/уровни не затронуты; тесты зелёные.
+
+## Notes
+- НЕ вводить произвольные функции-предикаты в синтаксис выражений (безопасность). Зоны → булевы env-поля.
+- Переиспользовать P3 plot (несколько кривых, заливка, маркеры) для визуала «земли»/препятствий.
+
+## Review Checklist
+- [ ] Все задачи; аддитивность движка; без эмодзи/eval; тесты зелёные; lint baseline 0
+
+## Handoff to Next Phase
+<!-- Заполняет агент-имплементер. -->

plans/quantik-game/phase-4-quantum-abilities-sr.md

@@ -0,0 +1,48 @@
+# Phase 4: Квантовые способности + SR-комнаты
+
+**Status:** ⬜ Not Started
+**Parent plan:** [PLAN.md](./PLAN.md)
+**Domain:** fullstack
+
+## Objective
+Фирменные «квантовые» механики, дающие герою идентичность, плюс связка с флешкарт-SR:
+**суперпозиция** (раздвоение), **коллапс/пауза** (точный прицел), **туннелирование**
+(проход сквозь тонкую стену за «энергию», которую даёт быстрое SR-повторение).
+
+## Tasks
+- [ ] Task 1: Суперпозиция: уровень с двумя телами-копиями Квантика; общий «закон» (params) рулит
+      обеими; цель — обе достигают порталов/условий (`goal.when` ссылается на оба `<id>.x/.y`).
+      Реюз существующей мульти-body физики. Визуал — две glow-точки (полупрозрачные «фантомы»).
+- [ ] Task 2: Коллапс/пауза-прицел: на паузе показать предсказанную траекторию (`plot trace`/
+      пунктир) текущего закона до запуска — «прицеливание». Реюз предпросмотра старта (P1/P2).
+- [ ] Task 3: Туннелирование: «энергетический заряд» расходуется, чтобы пройти сквозь помеченную
+      `tunnelable:true` стену (стена временно проницаема). Энергия в HUD.
+- [ ] Task 4: SR-комната: перед/в уровне — мини-сессия повторения флешкарт (реюз Tier-1 SR API,
+      мигр.074). Правильные ответы дают «энергию туннелирования». Открыть существующий движок
+      повторения в модалке/панели игры; начислять заряды по результату.
+- [ ] Task 5: Контент: 2–3 уровня под каждую способность (обучающий + применение).
+- [ ] Task 6: Тесты: суперпозиция (оба тела в `goal`), расход/начисление энергии (чистая логика),
+      проницаемость стены при заряде; смоук.
+
+## Files to Modify/Create
+- `frontend/js/labs/_sim_engine.js` — поле `tunnelable` у стены + расход энергии (аддитивно, документировать).
+- `frontend/js/game/quantik-game.js` — способности, HUD энергии, SR-комната-модалка.
+- интеграция с флешкарт-SR (клиентский модуль повторения / `LS` API).
+- `frontend/js/game/levels.js` — уровни способностей.
+- тест(ы).
+
+## Acceptance Criteria
+- Суперпозиция: победа только когда обе копии выполнили условие.
+- Коллапс: на паузе виден предсказанный путь.
+- Туннелирование тратит энергию; SR-повторение её пополняет; стена проницаема только при заряде.
+- Без eval/эмодзи; existing симуляции/SR не сломаны; тесты зелёные; lint baseline 0.
+
+## Notes
+- Имя param `e` зарезервировано (число Эйлера в SimExpr) — для энергии брать `energy`/`charge`.
+- SR-движок повторения уже существует — переиспользовать, не дублировать расписание.
+
+## Review Checklist
+- [ ] Все задачи; аддитивность; без эмодзи/eval; тесты зелёные; lint baseline 0
+
+## Handoff to Next Phase
+<!-- Заполняет агент-имплементер. -->

plans/quantik-game/phase-5-authoring-sharing.md

@@ -0,0 +1,49 @@
+# Phase 5: Авторинг уровней в sim-builder + раздача классу
+
+**Status:** ⬜ Not Started
+**Parent plan:** [PLAN.md](./PLAN.md)
+**Domain:** fullstack
+
+## Objective
+Дать учителю собирать **игровые уровни без кода** в существующем sim-builder: задать цель/звёзды/
+подсказку/главу/норматив, сохранить как `custom_sims` с `cat='game'`, опубликовать и раздать
+классу. Игра начинает грузить уровни из БД (а не только встроенные).
+
+⚠️ ПЕРЕД СТАРТОМ: свериться с base-веткой `feature/sim-builder` — чужой P4-WIP билдера должен
+быть смержен. При необходимости влить base в `feature/quantik-game` и разрешить конфликты.
+
+## Tasks
+- [ ] Task 1: Режим «Игровой уровень» в `sim-builder.js`/`.html`: панель цели (`goal.when`,
+      `title`, `hint`, `hold`, `fail`), список звёзд (add/del: `when`+`label`), глава/порядок/`par_ms`.
+      Inline-проверка выражений через `SimExpr.compile().error` (как остальные поля билдера).
+- [ ] Task 2: `buildSpec()` материализует блок `goal`/`game`; `loadFromSim()` раскладывает обратно
+      (round-trip), как сделано с plot-range в Ф4 билдера.
+- [ ] Task 3: Кнопка «Играть» в билдере — открыть текущую спеку в игровом режиме (тест уровня автором).
+- [ ] Task 4: Каталог уровней: игра грузит `custom_sims` c `cat='game'` (свои+published) — реюз
+      `LS.customSimsList`/`Get`. Категория `game` в списке `CATS` (customSimController) + фильтр.
+- [ ] Task 5: Раздача классу: реюз паттерна Ф6 sim-builder (авто-публикация + `pushNotif` ученикам,
+      ссылка `/quantik?level=custom:<id>`); привязка к программе через `lab_sim_links` (`sim_id='custom:<id>'`).
+- [ ] Task 6: Deep-link `/quantik?level=custom:<id>` (паттерн Ф5/Ф7 sim-builder, доступ own|published|admin).
+- [ ] Task 7: Тесты: round-trip goal в билдере (headless как Ф4 sim-builder); доступ к чужому
+      draft запрещён; published-уровень виден; раздача шлёт уведомление.
+
+## Files to Modify/Create
+- `frontend/sim-builder.html`, `frontend/js/sim-builder.js` — режим игрового уровня (аддитивно).
+- `backend/src/controllers/customSimController.js` — `CATS` += 'game'; (goal уже в validateSpec из Ф0).
+- `frontend/js/game/quantik-game.js` — загрузка уровней из custom_sims + deep-link.
+- тест(ы).
+
+## Acceptance Criteria
+- Учитель собирает уровень с целью/звёздами, тестирует «Играть», сохраняет/публикует.
+- Игра грузит уровни из БД; deep-link открывает конкретный уровень с проверкой доступа.
+- Раздача классу публикует + уведомляет; round-trip спеки без потерь; тесты зелёные; lint baseline 0.
+
+## Notes
+- Билдер — зона, где мог идти параллельный P4-WIP; правки строго аддитивны, свериться с base.
+- Санитизация goal-полей — уже на сервере (Ф0). Клиентская валидация зеркалит её (как в Ф4 билдера).
+
+## Review Checklist
+- [ ] Все задачи; аддитивность билдера; ownership/доступ корректны; без эмодзи/eval; тесты зелёные
+
+## Handoff to Next Phase
+<!-- Заполняет агент-имплементер. -->

plans/quantik-game/phase-6-leaderboard-live.md

@@ -0,0 +1,43 @@
+# Phase 6: Класс-лидерборд / живая гонка (classroom SSE)
+
+**Status:** ⬜ Not Started
+**Parent plan:** [PLAN.md](./PLAN.md)
+**Domain:** fullstack
+
+## Objective
+Соревновательный слой: лидерборды по уровню/классу и опциональная **живая гонка** в онлайн-уроке
+(реюз classroom SSE + моста `sim_state`/`apply_sim_state` из Ф7 sim-builder).
+
+## Tasks
+- [ ] Task 1: API лидерборда: `GET /api/game/leaderboard?level_id=...&scope=class|global` — топ по
+      времени/звёздам. Источник — `game_progress` (best per user). Доступ: класс — только своему классу.
+- [ ] Task 2: UI лидерборда: на экране уровня/победы и на карте — топ класса (имена/время/звёзды),
+      позиция игрока. Inline SVG-медали, без эмодзи.
+- [ ] Task 3: Живая гонка (опц.): учитель в classroom запускает уровень классу; ученики решают
+      одновременно; прогресс/финиши транслируются через существующий SSE-relay. Реюз iframe-конвейера
+      `/lab?embed=...` НЕ требуется — гонка может жить на `/quantik` с гоночной комнатой по classId.
+- [ ] Task 4: Сервер: relay результатов гонки (минимальный, поверх существующего SSE), без новых
+      тяжёлых таблиц — эфемерное состояние гонки в памяти/коротком хранилище.
+- [ ] Task 5: Тесты: лидерборд отдаёт корректный топ и режет чужой класс; submit обновляет позицию;
+      смоук UI.
+
+## Files to Modify/Create
+- `backend/src/controllers/gameController.js`, `routes/game.js` — leaderboard (+ гонка-relay).
+- `frontend/js/game/quantik-game.js` / `map.js` — UI лидерборда + гоночная комната.
+- (опц.) интеграция кнопки запуска гонки в classroom.html (аддитивно, как Ф7 sim-builder).
+- тест(ы).
+
+## Acceptance Criteria
+- Лидерборд по классу/глобально корректен и изолирован по классу; позиция игрока видна.
+- Живая гонка (если включена) синхронит финиши классу через SSE; закрытие чистое.
+- Без эмодзи/eval; existing функционал цел; тесты зелёные; lint baseline 0.
+
+## Notes
+- Реюз durable-уведомлений `pushNotif` для приглашения в гонку; эфемерный прогресс — через SSE.
+- classroom.html — большой; искать через vex по DOM-id, точечный Read (ast-index не индексит inline-script).
+
+## Review Checklist
+- [ ] Все задачи; изоляция по классу; аддитивность classroom; без эмодзи/eval; тесты зелёные
+
+## Handoff to Next Phase
+<!-- Финальная фаза — далее комплексное ревью и мерж в feature/sim-builder. -->