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

Phase 4: Квантовые способности + SR-комнаты

Status: ✅ Done (reviewed — PASS, committed) Parent plan: PLAN.md Domain: fullstack

Objective

Фирменные «квантовые» механики, дающие герою идентичность, плюс связка с флешкарт-SR: суперпозиция (раздвоение), коллапс/пауза (точный прицел), туннелирование (проход сквозь тонкую стену за «энергию», которую даёт быстрое SR-повторение).

Tasks

• Task 1: Суперпозиция: уровни L12/L13 с двумя телами ball+ball2, общий закон (theta,v) рулит обеими зеркально; goal.when ссылается на ball.* И ball2.* (победа — только обе). Реюз мульти-body физики. ball2 — полупрозрачный «фантом» (tintHeroSpec в quantik-game.js).
• Task 2: Коллапс/пауза-прицел: уровень L14 несёт пунктир-plot (id 'aim') с предсказанной параболой текущего закона; способность «Прицел» = пауза-тоггл (inst.pause/play) для прицела.
• Task 3: Туннелирование: барьер = forbidden-зона wall; fail:'wall.hit && tunnel<1'. Способность «Туннель» тратит TUNNEL_COST энергии → inst.setParam('tunnel',1) (стена проницаема). tunnel — НЕ слайдер (только способность); отсутствует в env → 0 → стена сплошная.
• Task 4: SR-комната: QuantikAbilities.openRestRoom — мини-сессия повторения в модалке (НЕ iframe). LS.fcListDecks → fcStudySession → fcReview; «Знаю/Легко» начисляют энергию. Пусто (нет колод/нет due) → дружелюбное окно + ссылка /flashcards.
• Task 5: Контент — глава quantum (5 уровней): L12/L13 суперпозиция, L14 прицел, L15/L16 туннель.
• Task 6: Тесты (headless vm + РЕАЛЬНЫЕ движки): суперпозиция (оба тела), энергия (grant/spend/ reward чистая логика), tunnel flips fail, per-level solvability sweep (5/5 выигрываемы, full-star достижим), регресс существующих 11 уровней без throw. 48/48; harness удалён.

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

Что добавлено (файлы)

• Новый frontend/js/game/quantik-abilities.js (window.QuantikEnergy + window.QuantikAbilities).
• frontend/js/game/levels.js — глава quantum (L12–L16) + CHAPTERS.quantum.
• frontend/js/game/quantik-game.js — tintHeroSpec тинтует ball2 (фантом); start() монтирует QuantikAbilities.mountBar (оборачивает inst.destroy для снятия панели); openRest() + сброс abilities.resetAbilities() на «Ещё раз».
• frontend/quantik.html — <script src="/js/game/quantik-abilities.js"> (после map.js, до game.js)
  • CSS .qa-* (панель/HUD/тост/SR-модалка/карточка/оценки).
• js/api.js — fcStudySession(deckId) (GET /flashcards/decks/:id/study) и fcReview(cardId, quality) (POST /flashcards/cards/:id/review body {quality}).
• ⛔ Движок _sim_engine.js НЕ тронут — туннель/прицел/суперпозиция выражены через безопасную модель спеки (зона+undefined-param / pause-toggle / два тела). Engine touch = 0.

Энергия (клиентский ресурс)

• localStorage ключ quantik-energy (целое 0..ENERGY_MAX=99). window.QuantikEnergy: getEnergy/setEnergy/grantEnergy/spendEnergy/canSpend/rewardForQuality/onEnergyChange. TUNNEL_COST=3, REWARD_GOOD=1 (q=4 «Знаю»), REWARD_EASY=2 (q=5 «Легко»).
• Туннель тратит энергию ОДИН раз за попытку (tunnelUsed); «Ещё раз»/новый mount сбрасывают tunnel→0 (стена снова сплошная).

Контракты для Phase 5 (авторинг)

• Способность «Туннель» активируется, если goal.fail/when/stars упоминают слово tunnel (QuantikAbilities.levelHasTunnel). Авторский UI должен уметь добавить forbidden-зону wall и fail:'wall.hit && tunnel<1'. tunnel — служебный param (не слайдер).
• Способность «Прицел» появляется, если на сцене есть plot с id:'aim' ИЛИ lineStyle:'dashed' (levelHasAim). Авторский UI может предложить «предсказанную траекторию» как пунктир-plot.
• Суперпозиция = чистый контент: второе тело id:'ball2' (point/circle с body), goal.when с обоими ball.*+ball2.*. tintHeroSpec уже тинтует ball/ball2; авторские id вне этих двух тинтоваться скином не будут (Phase 5 при желании расширит).
• Глава = метаданные: quantum появилась на карте без правок map.js (groupByChapter + Levels.chapter). Новая глава = новый chapter-ключ + CHAPTERS-запись (контракт Phase 2).

Solvability (проверено на реальном движке, harness удалён)

• L12 Раздвоение: 52 win-комбо (есть выигрышная v почти для любой θ), full-star напр. θ70/v10.
• L13 Две двери: full-star θ45/v11. L14 Прицел: full-star θ60/v12 (2/2 звезды).
• L15 барьер: с tunnel=1 — 4 win, full-star a0/b3.7; БЕЗ tunnel — 0 win (гейт работает).
• L16 капстоун: с tunnel=1 — full-star a-0.25/k7.2 (монета сдвинута на (5,6.9) r0.85 — была (5,6) r0.7, конфликтовала со 2-й звездой k≥6.8); БЕЗ tunnel — 0 win.