merge: feature/lab-content-engine → master

Контент-движок лаборатории (фазы 0-5): LabRegistry, data-driven регистрация,
вынос тел в labs-bodies.html, ленивая загрузка кода, БД-каталог lab_sims + API +
админка, курикулумные связи lab_sim_links + двусторонняя навигация.
Плюс накопленная работа параллельных сессий (chemistry-8, phys7, biochem, optics).

Разрешение конфликтов: frontend/lab.html — версия feature (контент-движок);
opticsbench.js / seed_biochem_challenges.js / BIOCHEM_UPGRADE.md /
biochem-pathways-plan.md — версия master (более свежая работа парал. сессий).

Тесты: 160, 157 pass, 3 fail (pre-existing baseline auth.test.js).

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

plans/lab-content-engine/CONTEXT.md

@@ -0,0 +1,116 @@
+# Feature Context: Контент-движок лаборатории
+
+## Current State
+- Лаборатория работает на захардкоженной регистрации (см. PLAN.md Summary).
+- Ветка `feature/lab-content-engine` создана от `master`.
+
+## Architecture map (как было ДО рефактора)
+- `frontend/lab.html` — sim-тела `<div id="sim-xxx">` (inline HTML, ~3000 строк) + 58 `<script>` тегов (4800-4861) + three.js.
+- `frontend/js/labs/lab-glue.js`:
+  - `_catFilter`, `_disabledSimIds`, `_simModuleDisabled` (вкл/выкл из админки)
+  - `filterSims()`, `renderSims()` (карточки каталога)
+  - preview-хелперы `_grid/_axes/_svg` + ~60 констант `P_*`
+  - массив `SIMS` (821-866), `window.SIMS`/`window.LAB_SIMS`
+- `frontend/js/labs/lab-init.js`:
+  - объявления переменных симуляций (gSim, pSim, …)
+  - `ALL_SIM_BODIES` / `ALL_CTRL_BARS` (33-48)
+  - `_pauseAllSims()` (54-91), `openSim(id)` if-цепочка (93-160), `closeSim()` (212-258)
+  - `_simShow()`, `_addTouchSupport()` (touch-bridge + ResizeObserver)
+  - объект `THEORY` + `loadTheory()` + `_theoryToggle()`
+  - функции `_openXxx()` (603-756) — единый шаблон: `_simShow('sim-xxx')` + ленивое `new XxxSim(...)` + показ `ctrl-xxx`
+- `frontend/js/admin/sections/sims.js` — админ-секция (пока только вкл/выкл, `_disabledSimIds`).
+
+## Загрузочный порядок (КРИТИЧНО)
+В lab.html: движки `_fx_*`, `_phys_visuals`, `_graph_panel`, `_chem_visuals` грузятся ПЕРЕД симуляциями.
+`lab-init.js` (4826) грузится ПЕРЕД `lab-glue.js` (4827). `renderSims()` вызывается в конце lab-glue.
+Некоторые sim-файлы (graph.js) грузятся РАНЬШЕ lab-glue.js → preview `P_*` ещё не определены на момент исполнения их тел.
+=> В манифестах `preview` поддерживает функцию (ленивое вычисление в renderSims), не только строку.
+
+## Контракт LabRegistry (Фаза 0)
+```
+LabRegistry.register(manifest)  // manifest.id уникален; повторная регистрация перезаписывает
+LabRegistry.get(id)             // по base-id (без ':arg')
+LabRegistry.has(id)
+LabRegistry.all()               // в порядке регистрации
+LabRegistry.setActive(sim) / stopActive() / destroyActive()  // менеджер жизненного цикла
+```
+manifest: `{ id, cat, title, desc, preview(string|fn), theory?, bodyId?, mount?(host), open(ctx), stop?(), destroy?(), subject?, grade?, topics? }`
+
+## Адаптер (Фаза 0): реестр в приоритете, иначе legacy
+- `renderSims()` — порядок берём из исходного `SIMS`; для id, который есть в реестре, используем манифест (resolve preview), иначе legacy-запись; в конце добавляем registry-only записи, которых нет в SIMS.
+- `openSim(id)` — `base = id.split(':')[0]`; если `LabRegistry.has(base)` → `stopActive()`; `get(base).open({arg})`; `setActive`; иначе старый if-путь.
+- `loadTheory(id)` — если `get(base).theory` есть → рендерим из него; иначе `THEORY[base]`.
+- `closeSim()`/`_pauseAllSims()` — дополнительно `LabRegistry.stopActive()` / `destroyActive()`.
+
+## RESUME STATE — Phase 4 done (2026-05-30, latest)
+- Ф4: каталог симуляций в БД. Миграция `042_lab_sims.sql` (таблица lab_sims, сид 40), `backend/src/routes/lab.js` (GET /api/lab/sims auth; PATCH /:id + POST /reorder admin), mount в server.js, 11 тестов, переписан admin/sections/sims.js (убран хардкод ADMIN_SIMS).
+- enabled зеркалится в legacy app_settings.sim_disabled_ids → lab.html без правок. preview-SVG остаются в коде.
+- Ревью PASS (без блокеров). route-auth lint чистый. Миграция применена к живой БД. Запушено, remote синхронен.
+- ВАЖНО: `npm test` = 3 PRE-EXISTING baseline-фейла (НЕ мои; документированы с lab-split). pre-commit хук: BASELINE_FAILS=3, блокирует только при >3. Мои 11 проходят, +0.
+- ⚠️ Параллельная сессия коммитит в ветку — был 2 behind, rebase прошёл чисто (без пересечений по файлам). Всегда fetch+rebase перед push.
+- НЕ ПРОВЕРЕНО В БРАУЗЕРЕ: админка «Симуляции» (грузит /api/lab/sims, тумблеры, звезда featured) + исчезновение выключенной симуляции на /lab.
+- ОСТАЛОСЬ: Фаза 5 (курикулум: lab_sim_links + кнопки «Открыть в лаборатории» в учебнике/теории + связанная теория/задачи на странице sim). subject/grade/featured/tags уже в схеме lab_sims.
+
+## RESUME STATE — Phase 3 done + FIXED (2026-05-30, ранее)
+- HEAD=9069d80 (Ф3 + критический фикс). ЗАПУШЕНО, remote синхронен (0 0).
+- ВАЖНЫЙ УРОК: коммит fc1139f был СЛОМАН — 2 edit'а (_register-all open-обёртка + lab-init Promise-обработка) не применились (упали по отступу old_string), а я запушил, не заметив. Ревью-агент поймал: lab.html убрал eager-скрипты, но open остался синхронным → ReferenceError на клике. Фикс в 9069d80. ПРАВИЛО: после каждого edit проверять `grep -c` маркера; не пушить пакет без поштучной верификации.
+- ТЕПЕРЬ КОРРЕКТНО: open → LabLoader.ensure(id).then(rawOpen); openSim обрабатывает Promise. E2E vm-harness (click→ensure→load→rawOpen, pendulum/stereo:cube/molphys/alias magnetic) ALL PASS.
+
+## RESUME STATE — Phase 3 done (исходный, до фикса)
+- HEAD=70762be (Ф3). Ленивая загрузка кода: старт /lab ~530KB вместо ~2.9MB+600KB three.js (~6×).
+- Новые файлы: `_loader.js`, `_sim_deps.js` (генерированный манифест). Правки: `_register-all.js`, `lab-init.js`, `lab.html` (eager сокращён до каркаса).
+- Манифест SIM_DEPS: каждый sim → {open, files[], three}. Инвариант (проверен): файл, определяющий open-функцию, ВСЕГДА в files[] (кроме graph — он eager). Self-heal = страховка.
+- ⚠️ PUSH: на момент завершения Ф3 окружение глючило (пустой вывод команд); локально 2 коммита ahead (Ф2-docs + Ф3), 0 behind. НУЖНО допушить: `git push origin feature/lab-content-engine` (мог не пройти из-за транзиентного auth — повторить).
+- ⚠️ НЕ ПРОВЕРЕНО В БРАУЗЕРЕ (см. чеклист в phase-3-lazy-load.md handoff).
+- ГЕНЕРАТОР МАНИФЕСТА был временным (%TEMP%, удалён). Логика: framework-set + статический анализ provides/refs (комментарии вырезаются) + транзитивное замыкание по ленивым файлам; 3D-set хардкод {crystal,orbitals,stereo,periodic}; EXTRA_DEPS={periodic:[_periodic_data.js]}. При Ф4/5 положить в tools/gen-sim-deps.js.
+- СЛЕДУЮЩЕЕ: Ф4 (БД lab_sims + API + админка, backend — не трогает lab.html) или Ф5 (курикулум).
+
+## RESUME STATE — Phase 2 done (2026-05-30, ранее)
+- Ф2: 40 тел симуляций (~4420 строк) вынесены из lab.html (4880→484 строк) в `frontend/labs-bodies.html`. На месте региона — `#sim-bodies-host` + инлайн-скрипт с СИНХРОННЫМ XHR (`open(...,false)`), который во время парсинга грузит partial и `insertAdjacentHTML('beforebegin')` вставляет тела ДО хоста, затем удаляет хост. Тела присутствуют до DOMContentLoaded → обработчики geometry.js:3207 и порядок init сохранены.
+- ctrl-бары (#ctrl-*) и #theory-panel ОСТАЛИСЬ в lab.html (они в topbar, не в регионе).
+- partial раздаётся существующим `express.static(frontendDir)` (server.js:475) — новый роут не нужен.
+- ГАРАНТИИ (механические, не браузерные): реконструкция before+region+after == оригинал ПОБАЙТОВО; id-мультимножество (newLab−host)+partial == оригинал; 40 sim-body div; node --check OK.
+- ⚠️ НЕ ПРОВЕРЕНО В БРАУЗЕРЕ. РИСКИ к проверке вручную: (1) sync-XHR может блокироваться при file:// — но тут Express, ок; (2) консольное предупреждение о deprecated sync XHR — безвредно; (3) CSP на инлайн-скрипт — на странице уже есть инлайн-скрипты, должно быть ок; (4) кэш partial (?v=1) — при правках бампать версию.
+- ПРОВЕРИТЬ: открыть /lab, дождаться каталога, открыть несколько симуляций (graph, pendulum, geometry — у неё DOMContentLoaded-кнопки, stereo:cube, opticsbench), убедиться что canvas рисуется и кнопки работают.
+- ОТКАТ: `git revert <commit Ф2>` или вернуть регион из labs-bodies.html обратно.
+- СЛЕДУЮЩЕЕ: Фаза 3 (ленивая загрузка кода) ИЛИ Фаза 4 (БД+админка, backend — без конфликтов с lab.html). Параллельная сессия всё ещё может править lab.html.
+
+## RESUME STATE — Phase 1 done (2026-05-30, later)
+- Коммиты: 36c091b → 0888a70 (фикс Ф0) → ebb2a9b (Ф1). HEAD=ebb2a9b, ЗАПУШЕНО, remote синхронен.
+- Ф1: централизованный `_register-all.js` (data-driven из SIMS+THEORY+OPEN map 40 шт), if-цепочка openSim удалена, _pilots.js удалён, LAB_SIM_ALIASES добавлены. Ревью PASS, vm-harness ALL PASS.
+- SIMS/THEORY/_pauseAllSims/closeSim/ALL_SIM_BODIES/ALL_CTRL_BARS НАМЕРЕННО оставлены (источники данных + lifecycle-дробовик) — паритет без браузера. Их удаление = Фаза 2 (с ленивым mount).
+- БЛОКЕР-РИСК: параллельная сессия (biochem/opticsbench) активно правит lab.html и откатывала мои include-правки. Перед Фазой 2 (вынос ~3000 строк из lab.html) — СОГЛАСОВАТЬ, иначе конфликты/потеря работы.
+- СЛЕДУЮЩЕЕ: пользователю желательно открыть /lab в браузере и кликнуть несколько симуляций (особенно с :arg — стерео-фигуры, оптика-режимы) перед Фазой 2.
+
+## RESUME STATE (2026-05-30, ранее)
+- Ветка `feature/lab-content-engine`. Коммиты: 36c091b (Фаза 0, была неполной) → 8f72d68 (фикс 3 блокеров, ЗАПУШЕН).
+- Первое ревью Фазы 0 = FAIL (3 блокера: _registry.js не подключён, пилоты не зарегистрированы, loadTheory не адаптирован). ВСЕ ТРИ ИСПРАВЛЕНЫ в 8f72d68:
+  - `_registry.js` подключён в lab.html:4799 (после three.js).
+  - `frontend/js/labs/_pilots.js` — регистрирует graph/quadratic/pendulum; подключён в lab.html:4863 (defer, последним).
+  - `loadTheory` (lab-glue.js:951) — реестр в приоритете.
+- СЛЕДУЮЩИЙ ШАГ: повторное независимое ревью Фазы 0 (агент). Если PASS → Фаза 1.
+- Фаза 1 решено вести ПО КАТЕГОРИЯМ с коммитами (math→phys→chem→bio→game), legacy удалять в конце.
+- НЕ ПРОВЕРЕНО в браузере (нет автоматизации). Паритет — статически + ревью.
+- ВАЖНО: _open* функции глобальны (graph.js:506, quadratic.js:454, pendulum.js:1749). P_* — top-level const в lab-glue.js (доступны cross-script). THEORY — const в lab-init.js. Манифест Фазы1 регистрировать в самом sim-файле, но следить за порядком (preview/theory как fn если файл грузится до lab-glue/lab-init).
+- УРОК: lab-glue.js/lab-init.js часто перенумеровываются линтером — перед Edit перечитывать. Делать правки ПО ОДНОЙ с проверкой (был сбой пакетного выполнения).
+
+## Temporary Workarounds
+- Пилоты (graph/quadratic/pendulum) оставлены в SIMS/THEORY для порядка карточек и единого источника теории; merge перекрывает по id. Удалить в Фазе 1.
+
+## Known follow-ups (из ревью Фазы 0)
+- При переключении на LEGACY-симуляцию `LabRegistry._active` не очищается → лишний destroyActive() на неактивной. Безвредно сейчас; очистить `_active` на legacy-open в Фазе 1.
+
+## Cross-Phase Dependencies
+- Фаза 1 опирается на ядро реестра из Фазы 0.
+- Фаза 3 (ленивая загрузка) опирается на манифесты с зависимостями движков (Фаза 1/2).
+- Фаза 4 (БД) мёржит код-манифесты Фазы 1 с оверрайдами.
+- Фаза 5 использует поля subject/grade/topics из манифестов.
+
+## Deep-links (сохранить!)
+`openSim('stereo:figure')`, `?stereofig=`, обратная совместимость `magnetic/coulomb→emfield`, `thinlens/mirrors/refraction→opticsbench`.
+
+## Проектные правила (НЕ нарушать)
+- Иконки: только inline SVG `.ic`, НЕ эмоджи.
+- Поиск по коду: ast-index, НЕ Grep tool.
+- БД: встроенный `node:sqlite` DatabaseSync, НЕ better-sqlite3.
+- Git: коммитить только изменённые файлы.

plans/lab-content-engine/PLAN.md

@@ -0,0 +1,53 @@
+# Feature: Контент-движок лаборатории (симуляции как данные)
+
+**Branch:** `feature/lab-content-engine`
+**Base branch:** `master`
+**Created:** 2026-05-30
+**Status:** ✅ Complete (все 6 фаз; backend полностью, фронт Ф5 — параллельная сессия; не мёржено в master)
+**Strategy:** Big Bang
+**Mode:** Automated
+**Execution:** Direct
+
+## Summary
+
+Превратить захардкоженную в 6 местах регистрацию ~49 симуляций лаборатории в единый
+декларативный манифест + реестр (`LabRegistry`). Каждая симуляция сама себя регистрирует
+объектом `{id, cat, title, desc, preview, theory, bodyId/mount, open, stop, destroy, subject, grade, topics}`.
+Ядро (renderSims/openSim/closeSim/loadTheory) работает с реестром, а не с массивами и
+if-цепочками. Далее — ленивая загрузка кода, БД-бэкенд с админкой и курикулумная привязка.
+
+## Build & Test Commands
+- **Build:** — (фронт без сборки, статика через Express)
+- **Test:** `cd backend && npm test` (актуально для Фаз 4-5; Фазы 0-3 — статическая проверка + ревью по диффу)
+- **Lint:** `cd backend && npm run lint:routes` (актуально для Фаз 4-5)
+
+## Phases
+
+- [x] Phase 0: Ядро реестра + адаптер + 3 пилота [domain: frontend] → [subplan](./phase-0-registry-core.md)
+- [x] Phase 1: Миграция всех симуляций на манифесты [domain: frontend] → [subplan](./phase-1-migrate-all.md)
+- [x] Phase 2: Тела симуляций вынесены в labs-bodies.html (sync-инъекция) [domain: frontend] → [subplan](./phase-2-lazy-mount.md)
+- [x] Phase 3: Ленивая загрузка кода симуляций [domain: frontend] → [subplan](./phase-3-lazy-load.md)
+- [x] Phase 4: Реестр в БД + API + админка [domain: fullstack] → [subplan](./phase-4-db-admin.md)
+- [x] Phase 5: Курикулумная привязка [domain: fullstack] → [subplan](./phase-5-curriculum.md)
+
+## Phase Progress Log
+
+| Phase | Domain | Status | Review | Build | Committed |
+|-------|--------|--------|--------|-------|-----------|
+| Phase 0: Ядро реестра | frontend | ✅ Done (fix 0888a70) | ✅ PASS (re-review) | ✅ n/a | ⚠️ local only (push auth fail) |
+| Phase 1: Миграция всех | frontend | ✅ Done (ebb2a9b) | ✅ PASS | ✅ n/a | ✅ pushed |
+| Phase 2: Вынос тел | frontend | ✅ Done | ✅ браузер-проверка пройдена | ✅ n/a | ✅ pushed |
+| Phase 3: Ленивая загрузка | frontend | ✅ Done (201e94e +fix) | ✅ E2E harness ALL PASS | ✅ n/a | ⚠️ нужна браузер-проверка |
+| Phase 4: БД + админка | fullstack | ✅ Done | ✅ PASS (review) | ✅ 11/11 +0 baseline | ✅ pushed |
+| Phase 5: Курикулум | fullstack | ⬜ Not Started | ⬜ | ⬜ | ⬜ |
+
+## Final Review
+- [x] Per-phase independent reviews (PASS)
+- [x] Backend tests pass (lab-sims 11/11, lab-links 18/18; +0 к baseline)
+- [x] route-auth lint: 0 роутов lab.js во флаге
+- [ ] Merged to `master` (НЕ выполнено — ветка общая, мёрж за пользователем)
+
+## Notes (Big Bang temporary breakage map)
+- Фаза 1 может временно ломать каталог/открытие симуляций пока миграция не завершена — устраняется внутри Фазы 1.
+- Фаза 2 временно меняет структуру lab.html (вынос тел) — устраняется внутри Фазы 2.
+- Полная работоспособность лаборатории гарантируется после ФИНАЛЬНОЙ фазы.

plans/lab-content-engine/phase-0-registry-core.md

@@ -0,0 +1,51 @@
+# Phase 0: Ядро реестра + адаптер + 3 пилота
+
+**Status:** ✅ Done
+**Parent plan:** [PLAN.md](./PLAN.md)
+**Domain:** frontend
+
+## Objective
+Создать `LabRegistry` (реестр + менеджер активной симуляции). Подключить адаптер: ядро
+лаборатории сначала смотрит в реестр, иначе — старый путь. Мигрировать 3 пилота
+(graph, quadratic, pendulum) и доказать паритет. Полностью обратимо.
+
+## Tasks
+- [ ] Создать `frontend/js/labs/_registry.js` — `window.LabRegistry` (register/get/has/all + setActive/stopActive/destroyActive). Без эмоджи.
+- [ ] Подключить `_registry.js` в lab.html ПЕРВЫМ среди labs-скриптов (до graph.js).
+- [ ] Адаптер `renderSims()` (lab-glue.js): порядок из SIMS, registry-override + resolve preview (string|fn), append registry-only.
+- [ ] Адаптер `openSim()` (lab-init.js): base-id, registry-first → stopActive/open/setActive; deep-link `:arg` сохранить.
+- [ ] Адаптер `loadTheory()` (lab-init.js): registry.theory в приоритете, иначе THEORY[base].
+- [ ] Адаптер `closeSim()`/`_pauseAllSims()`: добавить `LabRegistry.stopActive()`/`destroyActive()`.
+- [ ] Зарегистрировать 3 пилота в конце lab-init.js (после _openXxx): graph, quadratic, pendulum — с preview-fn, theory-объектом, open=_openXxx, stop/destroy.
+- [ ] Удалить graph/quadratic/pendulum из legacy `THEORY` и `SIMS` (проверка, что адаптер их подхватывает из реестра).
+
+## Files to Modify/Create
+- `frontend/js/labs/_registry.js` — новый: ядро реестра.
+- `frontend/lab.html` — добавить `<script src="/js/labs/_registry.js">` первым (в обоих местах, если дублируется список).
+- `frontend/js/labs/lab-glue.js` — renderSims адаптер; убрать 3 пилота из SIMS.
+- `frontend/js/labs/lab-init.js` — openSim/loadTheory/closeSim/_pauseAllSims адаптеры; регистрация 3 пилотов; убрать 3 пилота из THEORY.
+
+## Acceptance Criteria
+- Каталог отображает все симуляции в прежнем порядке; 3 пилота открываются и работают идентично.
+- Остальные 46 симуляций открываются по-старому (legacy путь не сломан).
+- Deep-links и обратная совместимость id работают.
+- Нет дублей карточек (пилот не показан дважды).
+- Нет эмоджи; иконки `.ic`.
+
+## Notes
+- Порядок загрузки: см. CONTEXT.md. preview как функция спасает от undefined P_*.
+- `_disabledSimIds` фильтрация должна продолжать работать для registry-записей.
+
+## Review Checklist
+- [ ] Адаптер не ломает legacy симуляции
+- [ ] Паритет 3 пилотов (open/stop/close/theory/preview)
+- [ ] Соблюдены конвенции проекта (no emoji, .ic)
+- [ ] Нет дублирования карточек
+
+## Handoff to Next Phase
+- Ядро `LabRegistry` готово (`frontend/js/labs/_registry.js`): register/get/has/all + setActive/stopActive/destroyActive + resolvePreview. Подключено первым.
+- Адаптер активен в renderSims (lab-glue.js) и openSim/loadTheory/_pauseAllSims/closeSim (lab-init.js): реестр в приоритете, иначе legacy.
+- Пилоты graph/quadratic/pendulum зарегистрированы в КОНЦЕ lab-init.js (после _openXxx). preview — ленивая функция (P_* из lab-glue, грузится позже). theory ссылается на объекты THEORY (единый источник).
+- Пилоты НЕ удалены из SIMS/THEORY (сохранены для порядка и единого источника); merge перекрывает их по id. В Фазе 1 удалить legacy полностью.
+- РЕВЬЮ-WARNING для Фазы 1: при переключении на LEGACY-симуляцию `_active` в реестре не очищается → следующий closeSim вызовет destroyActive() на уже неактивной. Для пилотов безвредно (idempotent stop). Очистить `_active` на legacy-open при миграции.
+- Паттерн манифеста для Фазы 1: `{id,cat,title,desc,preview(fn|str),theory,open,stop,destroy}`. Регистрировать в самом sim-файле; следить за порядком загрузки (preview как fn спасает).

plans/lab-content-engine/phase-1-migrate-all.md

@@ -0,0 +1,45 @@
+# Phase 1: Миграция всех симуляций на манифесты
+
+**Status:** ✅ Done (ebb2a9b, reviewed PASS, pushed)
+**Parent plan:** [PLAN.md](./PLAN.md)
+**Domain:** frontend
+
+## Objective
+Перевести все ~49 симуляций на сам/регистрацию через `LabRegistry`. Перенести данные
+(catalogue meta, preview, theory) и поведение (open/stop/destroy) в манифесты. Удалить
+legacy-структуры. Сохранить глобальные имена через shim.
+
+## Tasks
+- [ ] Для каждой симуляции зарегистрировать манифест (метаданные из SIMS, preview из P_*, theory из THEORY, open/stop/destroy из _openXxx + _pauseAllSims/closeSim веток).
+- [ ] Удалить массив `SIMS` (lab-glue.js) и объект `THEORY` (lab-init.js).
+- [ ] Удалить if-цепочку `openSim`, `_pauseAllSims`, switch в `closeSim`, `ALL_SIM_BODIES`/`ALL_CTRL_BARS`.
+- [ ] lab-init.js усохнуть до generic-логики (openSim/closeSim через реестр).
+- [ ] Shim глобальных имён (gSim, pSim, …) — их дёргают deep-link/поиск/инлайн-обработчики.
+- [ ] Сохранить обратную совместимость id (magnetic/coulomb→emfield, thinlens/mirrors/refraction→opticsbench, stereo:fig, hydrostatics:arg, molphys:arg, chemistry:arg, dynamics:arg, emfield:mode, opticsbench:mode).
+
+## Files to Modify/Create
+- Все `frontend/js/labs/*.js` симуляции — добавить `LabRegistry.register(...)`.
+- `frontend/js/labs/lab-glue.js`, `frontend/js/labs/lab-init.js` — удалить legacy.
+
+## Acceptance Criteria
+- Все симуляции открываются/работают как раньше (паритет).
+- Удалены все 6 точек дублирования из CONTEXT.md.
+- Deep-links и алиасы работают.
+
+## Notes
+- Мигрировать пачками (по категориям) с проверкой паритета после каждой пачки (Big Bang допускает временную поломку между пачками).
+- Превью с зависимостями (random в P_ELECTROLYSIS) перенести как есть.
+
+## Review Checklist
+- [ ] Ни одна симуляция не потеряна
+- [ ] Глобальные shim'ы на месте
+- [ ] Алиасы/deep-links работают
+- [ ] Legacy полностью удалён
+
+## Handoff to Next Phase
+- РЕАЛИЗАЦИЯ ОТЛИЧАЕТСЯ ОТ ИСХОДНОГО ПЛАНА (осознанно): вместо ручного переписывания манифестов в каждом sim-файле сделана централизованная data-driven регистрация в `frontend/js/labs/_register-all.js`. Манифесты строятся из существующих SIMS (метаданные+preview) + THEORY (теория) + карта OPEN (40 обёрток над глобальными _openXxx). Это структурно гарантирует паритет каталога и диспетчеризации.
+- УДАЛЕНО: if-цепочка openSim (~60 строк), _pilots.js. ДОБАВЛЕНО: LAB_SIM_ALIASES (magnetic/coulomb/thinlens/mirrors/refraction).
+- НЕ УДАЛЕНО (осознанно, для паритета без браузера): SIMS (lab-glue) и THEORY (lab-init) остаются ИСТОЧНИКАМИ данных; _pauseAllSims()/closeSim() «дробовик» и ALL_SIM_BODIES/ALL_CTRL_BARS остаются — управляют скрытием тел и остановкой. Поэтому stop/destroy в манифестах НЕ заданы.
+- ОСТАТОК ИЗ ПЛАНА (перенесено в Фазу 2+): полное удаление SIMS/THEORY/ALL_SIM_BODIES/ALL_CTRL_BARS и сворачивание lifecycle в манифесты (stop/destroy per-sim) — делать вместе с ленивым mount (Фаза 2), т.к. требует знания тел симуляций. Глобальные имена (gSim, pendSim…) НЕ трогались — shim не понадобился.
+- ВЕРИФИКАЦИЯ: исполняемый vm-harness (40 регистраций + dispatch + алиасы + :arg) ALL PASS; независимое ревью PASS (coverage 40/40, dispatch parity, node --check). В БРАУЗЕРЕ НЕ ПРОВЕРЕНО.
+- РИСК ДЛЯ ФАЗЫ 2: параллельная сессия активно правит lab.html (откатывала мои правки include дважды). Фаза 2 = вынос ~3000 строк ИЗ lab.html → высокий риск конфликтов. Координировать.

plans/lab-content-engine/phase-2-lazy-mount.md

@@ -0,0 +1,37 @@
+# Phase 2: Тела симуляций как шаблоны + ленивый mount
+
+**Status:** ✅ Done (3f99d1b) — браузер-проверка пройдена (пользователь подтвердил: симуляции работают)
+**Parent plan:** [PLAN.md](./PLAN.md)
+**Domain:** frontend
+
+## Objective
+Вынести inline-HTML тел симуляций (`<div id="sim-xxx">`, ~3000 строк) из lab.html в
+манифесты: `mount(host)` создаёт DOM лениво при первом открытии. lab.html худеет.
+
+## Tasks
+- [ ] Добавить в манифест поле `mount(host)` (или `bodyHtml`) — строит/возвращает тело симуляции.
+- [ ] Ядро: при первом open — если тело не смонтировано, вызвать mount() в контейнер `#lab-sim`.
+- [ ] Перенести разметку каждого `sim-xxx` тела + его `ctrl-xxx` бара из lab.html в соответствующий модуль.
+- [ ] Удалить вынесенные блоки из lab.html.
+- [ ] Сохранить id элементов (canvas ids, ctrl ids) — на них завязаны Sim-классы.
+
+## Files to Modify/Create
+- Все `frontend/js/labs/*.js` — добавить mount/bodyHtml.
+- `frontend/lab.html` — удалить inline тела.
+
+## Acceptance Criteria
+- Все симуляции монтируются и работают.
+- lab.html значительно меньше (~3000 строк вынесено).
+- Повторное открытие не дублирует DOM.
+
+## Notes
+- Theory-panel и общий sim-topbar остаются в lab.html.
+- KaTeX/lucide ре-инициализация после mount при необходимости.
+
+## Review Checklist
+- [ ] Нет дублей DOM при повторном open
+- [ ] id элементов сохранены
+- [ ] Все тела перенесены
+
+## Handoff to Next Phase
+<!-- заполнить после фазы -->

plans/lab-content-engine/phase-3-lazy-load.md

@@ -0,0 +1,46 @@
+# Phase 3: Ленивая загрузка кода симуляций
+
+**Status:** ✅ Done (70762be) — vm-harness + owner-in-files инвариант пройдены; нужна браузер-проверка
+**Parent plan:** [PLAN.md](./PLAN.md)
+**Domain:** frontend
+
+## Objective
+Грузить тяжёлый код симуляции и движков по клику, а не 58 скриптов + three.js сразу.
+Лёгкий манифест каталога загружается сразу.
+
+## Tasks
+- [ ] Вынести лёгкие метаданные каталога (id/cat/title/desc/preview) в отдельный `sims.manifest.js`, грузимый сразу.
+- [ ] Тяжёлый код симуляции (Sim-класс + open/mount) грузить динамически при openSim (инъекция script или import()).
+- [ ] Объявить зависимости движков в манифесте (`deps: ['_fx_core','_phys_visuals',...]`); загрузчик резолвит и грузит до кода симуляции, кешируя загруженное.
+- [ ] three.js грузить только для 3D-симуляций (stereo).
+- [ ] Лоадер с дедупликацией (один и тот же файл не грузится дважды).
+
+## Files to Modify/Create
+- `frontend/js/labs/_loader.js` — новый: динамический загрузчик + резолв зависимостей.
+- `frontend/js/labs/sims.manifest.js` — новый: лёгкий каталог.
+- `frontend/lab.html` — убрать массовые `<script>`, оставить ядро (api, registry, loader, manifest).
+
+## Acceptance Criteria
+- Первый рендер каталога без загрузки кода симуляций.
+- Открытие симуляции догружает её код+движки и работает.
+- three.js грузится только для 3D.
+- Заметное падение объёма стартовой загрузки lab.html.
+
+## Notes
+- Учесть defer-скрипты (solutions/organic/periodic/qualanalysis).
+- Кеш загруженных модулей в Map.
+
+## Review Checklist
+- [ ] Нет двойной загрузки
+- [ ] Зависимости движков соблюдены
+- [ ] Старт лаборатории легче
+
+## Handoff to Next Phase
+- РЕАЛИЗОВАНО: каркас (~530KB) грузится eager; код симуляций (~2.5MB) + three.js (~600KB) — лениво по клику. Старт /lab легче в ~6 раз.
+- Файлы: `_loader.js` (LabLoader.ensure + кеш + self-heal), `_sim_deps.js` (СГЕНЕРИРОВАННЫЙ манифест SIM_DEPS + LAB_LAZY_FILES), правки `_register-all.js` (open→ensure.then), `lab-init.js` (openSim обрабатывает Promise), `lab.html` (eager сокращён до 12 labs-скриптов + framework).
+- EAGER framework: _registry,_loader,_sim_deps,_fx_*,_graph_panel,_phys_visuals,_chem_visuals,_util,graph.js,lab-init,lab-glue,_register-all. graph.js eager (даёт GRID для 15 сим). _periodic_data — ЛЕНИВЫЙ (dep periodic).
+- three.js — лениво, только для crystal/orbitals/stereo/periodic (THREE_SIMS).
+- SELF-HEAL: если после загрузки манифестных файлов window[openName] не функция → грузятся ВСЕ ленивые файлы. Поэтому ошибка манифеста не ломает симуляцию (худший случай = поведение до Ф3).
+- РЕГЕНЕРАЦИЯ МАНИФЕСТА: скрипт-генератор был временным (в %TEMP%), НЕ в репо. При добавлении/переименовании симуляции: либо вручную дописать SIM_DEPS в _sim_deps.js, либо восстановить генератор (логика в CONTEXT). СТОИТ положить генератор в tools/ при Фазе 4/5.
+- БРАУЗЕР-ПРОВЕРКА (обязательна): открыть /lab → Network: на старте НЕ должно быть 45 sim-js и three.js; кликнуть pendulum (грузит pendulum.js), molphys (gas+states+brownian+diffusion), stereo (three.js+stereo.js), periodic (_periodic_data+periodic+three), chemistry (5 файлов), geometry, opticsbench; проверить deep-link stereo:cube, opticsbench:mirror, alias #magnetic.
+- РИСК для Ф4/5: lab.html сильно изменён; параллельные сессии правят его — fetch+проверка перед работой.

plans/lab-content-engine/phase-4-db-admin.md

@@ -0,0 +1,48 @@
+# Phase 4: Реестр в БД + API + админка
+
+**Status:** ✅ Done — review PASS, 11 тестов, миграция применена, запушено
+**Parent plan:** [PLAN.md](./PLAN.md)
+**Domain:** fullstack
+
+## Objective
+Хранить оверрайды каталога в БД, мёржить с код-манифестами, управлять каталогом из
+админки (вкл/выкл, порядок, теги, рекомендуемые).
+
+## Tasks
+- [ ] Миграция БД: таблица `lab_sims` (id PK, title, cat, subject, grade, desc, enabled, sort, topic_id, textbook_ref, flags JSON, updated_at). Через `node:sqlite` DatabaseSync.
+- [ ] Backend route `GET /api/lab/sims` — отдаёт мёрж: код-манифест (база) + БД-оверрайды.
+- [ ] Backend admin routes: upsert/enable/disable/reorder/tag (под RBAC admin).
+- [ ] Frontend: каталог берёт enabled/order/теги из `/api/lab/sims` (с фолбэком на код-манифест офлайн).
+- [ ] Расширить `frontend/js/admin/sections/sims.js`: список, вкл/выкл, drag-reorder, теги, «рекомендуемые».
+- [ ] Сохранить совместимость с `_disabledSimIds`.
+
+## Files to Modify/Create
+- `backend/src/db/migrations/0XX_lab_sims.sql` — новая миграция.
+- `backend/src/routes/lab.js` (или расширить существующий) — API.
+- `backend/src/server.js` — подключить роут (если новый файл).
+- `frontend/js/admin/sections/sims.js` — расширить админку.
+- `frontend/js/labs/_loader.js`/manifest — учитывать БД-данные.
+
+## Acceptance Criteria
+- `npm test` зелёный; `npm run lint:routes` без ошибок (auth на роутах).
+- Админ может вкл/выкл/переупорядочить/тегировать симуляцию, изменения видны в каталоге.
+- Офлайн/без БД — фолбэк на код-манифест.
+
+## Notes
+- RBAC: мутации только admin. Чтение каталога — для роли с доступом к лаборатории.
+- Не дублировать данные: код-манифест = источник базовых полей; БД = оверрайды/доп.
+
+## Review Checklist
+- [ ] Миграция идемпотентна
+- [ ] Роуты под auth (lint:routes)
+- [ ] Мёрж корректен, фолбэк работает
+- [ ] Тесты проходят
+
+## Handoff to Next Phase
+- РЕАЛИЗОВАНО: таблица `lab_sims` (миграция 042), `backend/src/routes/lab.js` (GET /api/lab/sims + PATCH /:id + POST /reorder), монтирование в server.js (require:58, mount:181), 11 тестов `lab-sims.test.js`, переписан `frontend/js/admin/sections/sims.js` (убран ADMIN_SIMS).
+- ИСТОЧНИК ИСТИНЫ каталога теперь БД (lab_sims). preview-SVG остаются в коде. Поля subject/grade/featured/tags ГОТОВЫ в схеме и API — Фаза 5 их наполнит (курикулум) и фронт /lab может начать их потреблять.
+- СОВМЕСТИМОСТЬ: enabled зеркалится в app_settings.sim_disabled_ids, поэтому lab.html (читает /api/settings/sims) скрывает выключенные без правок фронта. Каталог /lab пока НЕ читает /api/lab/sims (рендерится из кода-реестра+SIMS) — это опционально для Фазы 5: можно подтянуть порядок/featured/теги из БД.
+- ТЕСТЫ: `npm test` имеет 3 PRE-EXISTING baseline-фейла (документированы с lab-split, не связаны с этой работой). pre-commit хук толерантен (BASELINE_FAILS=3). Мои 11 тестов проходят, +0 к фейлам.
+- БРАУЗЕР-ПРОВЕРКА (желательно для Ф4): зайти в админку → раздел «Симуляции»: список грузится из API, тумблеры вкл/выкл и звёзда «рекомендуемая» работают; на /lab выключенная симуляция исчезает из каталога.
+- ⚠️ ПАРАЛЛЕЛЬНАЯ СЕССИЯ активно коммитит в эту ветку (chemistry-8 и др.) — fetch+rebase перед push (в этой фазе было 2 behind, rebase прошёл чисто, без пересечений по файлам).
+- Для Фазы 5: связи sim ↔ §учебника/тема/kmap можно класть в новую таблицу `lab_sim_links`; subject/grade уже есть в lab_sims для грубой привязки.

plans/lab-content-engine/phase-5-curriculum.md

@@ -0,0 +1,43 @@
+# Phase 5: Курикулумная привязка
+
+**Status:** ⬜ Not Started
+**Parent plan:** [PLAN.md](./PLAN.md)
+**Domain:** fullstack
+
+## Objective
+Связать симуляции с учебной программой: § учебника, узел knowledge-map, тема банка
+вопросов. Двусторонняя навигация.
+
+## Tasks
+- [ ] Схема связей: использовать поля манифеста (subject/grade/topics) + таблицу связей `lab_sim_links` (sim_id, kind[textbook|topic|kmap|question], ref_id).
+- [ ] API: `GET /api/lab/sims/:id/related` — связанные § / темы / задачи.
+- [ ] Frontend учебник/теория: кнопка «Открыть в лаборатории» в § (deep-link openSim).
+- [ ] Frontend knowledge-map: узел темы → ссылка на симуляцию.
+- [ ] Страница симуляции: блок «Связанная теория и задачи».
+- [ ] Админка: редактирование связей симуляции.
+
+## Files to Modify/Create
+- `backend/src/db/migrations/0XX_lab_sim_links.sql`
+- `backend/src/routes/lab.js` — related endpoint.
+- `frontend/textbooks.html` / theory / учебник-рендер — кнопки в §.
+- `frontend/knowledge-map.html` — ссылки с узлов.
+- `frontend/lab.html` — блок связей на странице sim.
+- `frontend/js/admin/sections/sims.js` — редактор связей.
+
+## Acceptance Criteria
+- Из § учебника можно открыть нужную симуляцию.
+- На странице симуляции видны связанные теория/задачи.
+- Узлы knowledge-map ведут на симуляции.
+- `npm test` зелёный, роуты под auth.
+
+## Notes
+- Привязки опциональны: отсутствие связей не ломает страницы.
+- Переиспользовать существующие topic_id банка вопросов и структуру учебников.
+
+## Review Checklist
+- [ ] Навигация в обе стороны работает
+- [ ] Пустые связи не ломают UI
+- [ ] Роуты под auth, тесты проходят
+
+## Handoff to Next Phase
+<!-- финальная фаза -->

plans/textbooks-8/PLAN_CHEMISTRY_8.md

@@ -0,0 +1,417 @@
+# План реализации: Химия 8 (Беларусь) — интерактивный наглядный учебник
+
+> Цель: создать **с нуля** интерактивный наглядный учебник по всей программе 8 класса
+> в **современной архитектуре hub + главы** (как Физика 7–11 / Алгебра / Геометрия —
+> НЕ как легаси-монолит `chemistry_9.html`), на уровне их качества, с поправкой на
+> содержание 8 класса: **количественные понятия (моль, M, Vm, расчёты по уравнениям),
+> классы неорганических соединений, периодический закон, строение атома, химическая
+> связь, ОВР, растворы.**
+>
+> **Архитектура (утверждена):** `chemistry_8_hub.html` (хаб-каталог глав) + **7 файлов глав**
+> (вводный раздел + 6 глав книги). В БД — родитель `chemistry-8` + 7 детей с `parent_slug`.
+> Каждая глава — самостоятельная страница со своими § (см. карту ниже), модульный
+> CSS/JS на предмет. Единый стандарт с планом Химии 9 ([[plans/textbooks-9/PLAN_CHEMISTRY_9.md]]).
+
+---
+
+## 🎯 Источник
+
+| Параметр | Значение |
+|----------|----------|
+| Книга | `himiya_8kl_shimanovich_rus_2018 (1).pdf` |
+| Авторы | Шиманович И. Е., Красицкий В. А., Сечко О. И., Хвалюк В. Н. |
+| Изд. | Минск, «Народная асвета», 2018, 243 с. (тираж 116 000) |
+| Структура | **Вводный раздел + 6 глав, 52 §, 4 лабораторных опыта, 4 практические работы** |
+| Справочные таблицы | ПСХЭ Менделеева, таблица растворимости, ряд активности металлов (форзацы) |
+
+PDF лежит в `G:\Dev\Тесты\Методички\тест_6 класс\Книги\`. Оглавление — стр. 238–239 PDF.
+
+> **Важные отличия от Химии 9:**
+> 1. Страниц химии-8 **ещё нет** — строим с нуля. Каркас берём у **современных hub-учебников**
+>    (`physics_9_hub.html` + `physics_9_chN.html`), а НЕ у легаси-монолита `chemistry_9.html`.
+> 2. Описательной химии металлов/неметаллов в 8 классе **нет** (это 9 класс) — акцент на
+>    количественные расчёты, классификацию веществ, строение атома и химическую связь, ОВР.
+>
+> **Соответствие «раздел книги → файл главы → slug»:**
+>
+> | Раздел книги | § | Файл | slug | Цвет |
+> |---|---|---|---|---|
+> | Вводный: Количественные понятия | 1–9 | `chemistry_8_intro.html` | `chemistry-8-intro` | amber |
+> | Гл.1 Классы неорг. соединений | 10–23 | `chemistry_8_ch1.html` | `chemistry-8-ch1` | teal |
+> | Гл.2 Периодический закон и ПСХЭ | 24–28 | `chemistry_8_ch2.html` | `chemistry-8-ch2` | indigo |
+> | Гл.3 Строение атома | 29–35 | `chemistry_8_ch3.html` | `chemistry-8-ch3` | blue |
+> | Гл.4 Химическая связь | 36–41 | `chemistry_8_ch4.html` | `chemistry-8-ch4` | green |
+> | Гл.5 ОВР | 42–45 | `chemistry_8_ch5.html` | `chemistry-8-ch5` | deep-orange |
+> | Гл.6 Растворы | 46–52 | `chemistry_8_ch6.html` | `chemistry-8-ch6` | cyan |
+>
+> Хаб: `chemistry_8_hub.html` / slug `chemistry-8` (родитель в каталоге).
+
+---
+
+## 📗 ПОЛНАЯ КАРТА СОДЕРЖАНИЯ (52 §)
+
+Колонка **«Интерактив»** — главный наглядный элемент сверх текста (минимум 1 «звёздный»
+виджет на §; полный набор — в стандарте ниже).
+
+### ВВОДНЫЙ РАЗДЕЛ. Повторение курса 7 класса. Количественные понятия в химии (§§1–9) — *amber*
+| § | Тема | Ключ | Интерактив (звёздный виджет) |
+|---|------|------|------------------------------|
+| §1 | Атомы. Химические элементы. Относительная атомная масса | $Z$, символ, $A_r$ | **miniPeriodic** + поиск $A_r$ по элементу; модель атома |
+| §2 | Молекулы. Простые/сложные вещества. Химические формулы. $M_r$ | формула, индексы, $M_r=\sum A_r$ | **Конструктор формул** + калькулятор $M_r$ (biochem-core) |
+| §3 | Химическое количество вещества | понятие «порция», $n$ | Визуализация «порции вещества» (частицы → моль) |
+| §4 | Моль — единица количества вещества. Постоянная Авогадро | $N=n\cdot N_A$, $N_A=6{,}02\cdot10^{23}$ | **Счётчик частиц** $N\leftrightarrow n$, масштаб $N_A$ |
+| §5 | Молярная масса. Молярный объём газов | $M$ (г/моль), $V_m=22{,}4$ л/моль (н.у.) | Калькулятор $M$ + газовая модель ($V_m$) |
+| §6 | Вычисление $n$ по $m$ и $m$ по $n$ | $n=\dfrac{m}{M}$ | **Треугольник $n$–$m$–$M$** (интерактивный калькулятор-тренажёр) |
+| §7 | Вычисление $n$ газа по $V$ и $V$ по $n$ | $n=\dfrac{V}{V_m}$ | Калькулятор $V=n\cdot V_m$ + связка $m$–$n$–$V$–$N$ |
+| §8 | Химические реакции | признаки, закон сохранения массы, балансировка | **Балансировщик уравнений** (анимация коэффициентов) + классификатор типов реакций |
+| §9 | Количественные расчёты по уравнениям реакций | стехиометрия, мольные отношения | **sim `stoichiometry`** + пошаговый решатель «дано → по уравнению» |
+
+**Практическая работа 1** (после §7): «Химическое количество вещества».
+
+### ГЛАВА 1. Важнейшие классы неорганических соединений (§§10–23) — *teal/cyan*
+| § | Тема | Ключ | Интерактив |
+|---|------|------|------------|
+| §10 | Оксиды. Состав и классификация | $Э_xO_y$; осн./кисл./амфот./несолеобр. | **Классификатор оксидов** (drag формулы → класс) + конструктор формул оксидов по валентности |
+| §11 | Химические свойства оксидов | осн.оксид+кислота/вода; кисл.оксид+щёлочь/вода | **Матрица реакций оксидов** (`chemEq`, признаки) |
+| §12 | Получение и применение оксидов | горение, разложение; применение | Схемы получения + инфографика применения |
+| §13 | Кислоты. Состав и классификация | $H_xAc$; бескисл./кислородсод., основность | **Классификатор кислот** + `indicatorScale` (лакмус/метилоранж) |
+| §14 | Химические свойства кислот | + Me (ряд активности), + осн.оксид, + основание, + соль | **Реакции кислот** (4 типа) + ряд активности + `indicatorScale` |
+| §15 | Получение и применение кислот | кисл.оксид+вода, соль+кислота | Схемы получения + инфографика |
+| §16 | Основания | $Me(OH)_n$; щёлочи/нерастворимые | Конструктор $Me(OH)_n$ + `indicatorScale` (фенолфталеин малиновый) |
+| §17 | Химические свойства оснований | нейтрализация, +кисл.оксид, +соль, разложение | **Реакция нейтрализации** (анимация) + `indicatorScale` |
+| §18 | Получение и применение оснований | Me+вода, щёлочь+соль | Схемы; **Лаб.1**: получение нерастворимого основания (`testTube` $Cu(OH)_2$↓ голубой) |
+| §19 | Соли. Состав и классификация | катион×анион; средние/кислые/основные | **Конструктор солей** (катион×анион) + `solubilityTable` |
+| §20 | Химические свойства солей | РИО (↓↑), соль+Me (ряд активности) | `solubilityTable` + предсказатель РИО; **Лаб.2**: соли+металлы |
+| §21 | Получение и применение солей | 8+ способов получения | **Матрица способов получения солей** |
+| §22 | Взаимосвязь между классами неорг. веществ | генетическая связь Me/неMe → оксид → гидроксид → соль | **Генетическая карта-граф** (интерактивные переходы) |
+| §23 | Решение расчётных задач по теме | расчёты по классам, по уравнениям | **sim `stoichiometry`** + тренажёр расчётов |
+
+**Лаб. опыт 1** (после §18): получение нерастворимого основания.
+**Практическая работа 2** (после §18): изучение реакции нейтрализации.
+**Лаб. опыт 2** (после §20): взаимодействие растворов солей с металлами.
+**Практическая работа 3** (после §22): решение экспериментальных задач.
+
+### ГЛАВА 2. Периодический закон и периодическая система (§§24–28) — *indigo/violet*
+| § | Тема | Ключ | Интерактив |
+|---|------|------|------------|
+| §24 | Систематизация химических элементов | ранние классификации, металлы/неметаллы | Сортировщик элементов (Me/неMe/амфот.) |
+| §25 | Понятие об амфотерности | $Zn(OH)_2, Al(OH)_3$ + кислота **и** + щёлочь | **Амфотерность** (`testTube`, обе реакции); **Лаб.3**: гидроксид цинка |
+| §26 | Естественные семейства элементов | щелочные, ЩЗМ, галогены, инертные | **miniPeriodic** — подсветка семейств, тренды свойств |
+| §27 | Периодический закон Д. И. Менделеева | формулировка, периодичность | **Демонстрация периодичности** (карточки-раскладка элементов) |
+| §28 | Периодическая система химических элементов | период/группа/подгруппа, структура | **Интерактивная ПСХЭ** (sim `periodic`) + разбор структуры |
+
+**Лаб. опыт 3** (после §25): получение гидроксида цинка и изучение амфотерных свойств.
+
+### ГЛАВА 3. Строение атома и периодичность свойств (§§29–35) — *blue*
+| § | Тема | Ключ | Интерактив |
+|---|------|------|------------|
+| §29 | Строение атома. Атомный номер | ядро ($p^+,n^0$) + $e^-$, $Z$ | **Модель атома** (sim `bohratom`) — сборка по $Z$ |
+| §30 | Массовое число атома. Нуклиды | $A=Z+N$, нуклид | Калькулятор $A=Z+N$ + конструктор нуклида |
+| §31 | Изотопы. Явление радиоактивности | одинаковый $Z$, разный $N$; распад | Изотопы-конструктор + sim `radioactive` + расчёт $A_r$ по изотопам |
+| §32 | Состояние электронов. Электронное облако. Орбиталь | $s,p,d$ орбитали, форма облака | **3D-облака орбиталей** (sim `orbitals`) |
+| §33 | Строение электронных оболочек атомов | уровни, $2n^2$, конфигурация | **Конструктор электронной конфигурации** (`orbitalDiagram`, заполнение) |
+| §34 | Периодичность изменения свойств атомов | радиус, ЭО, металличность по периоду/группе | **Графики трендов** (slider период/группа → свойство) |
+| §35 | Характеристика элемента по положению в ПС | алгоритм «паспорта» элемента | **Генератор «паспорта элемента»** (пошагово) |
+
+### ГЛАВА 4. Химическая связь (§§36–41) — *green*
+| § | Тема | Ключ | Интерактив |
+|---|------|------|------------|
+| §36 | Природа химической связи | октет, энергия связи, устойчивость | Анимация «почему атомы соединяются» |
+| §37 | Ковалентная связь | общие электронные пары, схемы Льюиса | **Конструктор e-пар** + структурные формулы (biochem-core) |
+| §38 | Неполярная и полярная ков. связь. ЭО | $\Delta$ЭО → полярность, диполь | **Slider ЭО → тип связи** + диполь; **Лаб.4**: модели молекул (biochem-core 3D) |
+| §39 | Ионная связь | передача $e^-$, ионная решётка | **Анимация $Na\to Cl$** + решётка $NaCl$ |
+| §40 | Металлическая связь. Межмолекулярное взаимодействие | «электронный газ», водородная связь | **Модель электронного газа** + водородная связь |
+| §41 | Кристаллическое состояние вещества | 4 типа решёток → свойства | **4 типа решёток** (3D) + связь «тип → свойства» |
+
+**Лаб. опыт 4** (после §38): составление моделей молекул.
+
+### ГЛАВА 5. Окислительно-восстановительные реакции (§§42–45) — *deep-orange*
+| § | Тема | Ключ | Интерактив |
+|---|------|------|------------|
+| §42 | Степень окисления | правила, расчёт по формуле | **Калькулятор степени окисления** (любая формула) |
+| §43 | Процессы окисления и восстановления | отдача/приём $e^-$, окислитель/восстановитель | Визуализация переноса $e^-$ |
+| §44 | Окислительно-восстановительные реакции | метод электронного баланса | **Балансировщик ОВР** (пошаговый e-баланс) |
+| §45 | ОВР вокруг нас | горение, коррозия, дыхание, батарейки | Инфографика-исследование ОВР в жизни |
+
+### ГЛАВА 6. Растворы (§§46–52) — *cyan*
+| § | Тема | Ключ | Интерактив |
+|---|------|------|------------|
+| §46 | Смеси веществ | однородные/неоднородные, разделение | Классификатор смесей + методы разделения |
+| §47 | Растворение веществ в воде | гидратация, тепловой эффект | **Анимация растворения** (`dissociationAnim`) |
+| §48 | Характеристики растворимости веществ | $s=f(t)$, насыщ./ненасыщ. | **График растворимости** + `solubilityTable` |
+| §49 | Качественные характеристики состава растворов | насыщ./ненасыщ./разб./конц. | Качественная шкала «крепости» раствора |
+| §50 | Количественные характеристики. Массовая доля | $w=\dfrac{m_{в-ва}}{m_{р-ра}}$ | **Калькулятор $w$** (sim `solutions`) |
+| §51 | Молярная концентрация растворённых веществ | $c=\dfrac{n}{V}$, разбавление, смешение | **Калькулятор $c$** + разбавление/смешение |
+| §52 | Вода и растворы в жизни и деятельности человека | значение, очистка, быт | Инфографика-исследование |
+
+**Практическая работа 4** (после §51): приготовление раствора с заданной $w$ и $c$.
+
+**Итого**: 52 §, вводный раздел + 6 глав, **4 лаб. опыта** (§18, §20, §25, §38), **4 практические работы** (§7, §18, §22, §51).
+
+---
+
+## ⚗️ ХИМИЧЕСКИЙ СТАНДАРТ КАЧЕСТВА
+
+### A. Движки и переиспользуемые активы (всё уже есть в проекте)
+
+| Что нужно | Берём из | Файл / id |
+|-----------|----------|-----------|
+| Парсинг формул, $M$/$M_r$, формула Хилла | biochem-core | `frontend/js/biochem-core.js` ✅ |
+| 2D/3D шаростержневые модели, VSEPR | biochem-core | `frontend/js/biochem-core.js` ✅ |
+| Интерактивная ПСХЭ | sim `periodic` | реестр `_register-all.js` ✅ |
+| Модель атома (Бор) | sim `bohratom` | реестр ✅ |
+| Орбитали | sim `orbitals` | реестр ✅ |
+| Радиоактивность/изотопы | sim `radioactive` | реестр ✅ |
+| Стехиометрия | sim `stoichiometry` | реестр ✅ |
+| Титрование (нейтрализация) | sim `titration` | реестр ✅ |
+| Качественный анализ | sim `qualanalysis` | реестр ✅ |
+| Растворы / массовая доля | sim `solutions` | реестр ✅ |
+| Песочница реакций | sim `chemsandbox` | реестр ✅ |
+
+Монтаж: контейнер `<div id="sim-<id>"></div>` + `openSim('<id>')` (или прямой mount
+через `window.LabRegistry`), как на остальных страницах.
+
+### B. Общий хелпер `/js/chem8_svg.js` (по образцу `geom7_svg.js`, `alg10_svg.js`)
+
+> **Рекомендация:** химические примитивы 8 и 9 классов сильно пересекаются. Реализовать
+> файл так, чтобы его можно было продвинуть в **общий `/js/chem_svg.js`** (план Химии 9
+> ссылается на `chem9_svg.js` — при совместной разработке свести в один shared-модуль и
+> переиспользовать оба). Молекулы — **только через `biochem-core.js`**, не дублировать.
+
+```js
+// 1. Рендер уравнения реакции: коэффициенты, состояния (↑↓), стрелки, условия над стрелкой
+const chemEq = (src, opts={}) => { /* токенизация формул, верхн./нижн. индексы, →/⇌/→[t°] */ };
+
+// 2. Ион с зарядом:  ionLabel('SO4', -2) → 'SO₄²⁻'
+const ionLabel = (formula, charge) => { /* нижние индексы + надстрочный заряд */ };
+
+// 3. Пробирка с осадком/газом/окраской (SVG-анимация)
+const testTube = ({fill, precipitate, gas, color, label}) => { /* svg */ };
+
+// 4. Треугольник n–m–M (звёздный виджет §6): кликаешь искомое → формула + калькулятор
+const moleTriangle = (mount, {solveFor}) => { /* n=m/M, m=n·M, M=m/n */ };
+
+// 5. Балансировщик уравнений (§8): подбор коэффициентов, проверка баланса атомов
+const equationBalancer = (mount, {skeleton}) => { /* матрица атомов, подсветка дисбаланса */ };
+
+// 6. Калькулятор степени окисления (§42): формула → с.о. каждого элемента (правила)
+const oxStateCalc = (mount, {formula}) => { /* разбор, правила H+1/O−2/Σ=0 */ };
+
+// 7. Балансировщик ОВР методом e-баланса (§44): полуреакции, НОК, коэффициенты
+const redoxBalancer = (mount, {skeleton}) => { /* окислитель/восстановитель, Δe⁻ */ };
+
+// 8. Орбитальная диаграмма (§33): orbitalDiagram('1s2 2s2 2p4') → клетки + ↑↓
+const orbitalDiagram = (config) => { /* svg клетки, принцип Хунда/Паули */ };
+
+// 9. Интерактивная таблица растворимости (§19,20,48): подсветка пары катион×анион (Р/Н/М/—)
+const solubilityTable = (mount, {highlight}) => { /* из форзаца книги */ };
+
+// 10. Интерактивный ряд активности металлов (§14,20): клик → предсказание реакции
+const activitySeries = (mount, opts) => { /* K Ca Na Mg Al Zn Fe ... Au + (H₂) */ };
+
+// 11. Мини-ПСХЭ с подсветкой (§1,26,34): элемент/группа/период/семейство
+const miniPeriodic = (mount, {highlight, onClick}) => { /* интерактивная сетка */ };
+
+// 12. Индикатор + шкала pH (§13,14,16,17): лакмус/фенолфталеин/метилоранж
+const indicatorScale = (mount, {ph, indicator}) => { /* цвет полоски */ };
+
+// 13. Анимация растворения/гидратации (§47): частицы воды окружают ионы/молекулы
+const dissociationAnim = (mount, {substance}) => { /* canvas/SVG-частицы */ };
+
+// 14. Классификатор-DnD (§10,13,16,19,46): drag формулы → класс/тип; проверка
+const classifier = (mount, {items, buckets}) => { /* оксиды/кислоты/основания/соли/смеси */ };
+
+// 15. Генетическая карта-граф (§22): Me/неMe → оксид → гидроксид → соль, клик-переходы
+const geneticMap = (mount, opts) => { /* SVG-граф классов + рендер реакции перехода */ };
+```
+
+### C. Правила рендера химии (обязательны с §1)
+
+1. **Формулы веществ** — нижние индексы для атомов ($H_2O$, $CaCO_3$), верхние для зарядов
+   ионов ($SO_4^{2-}$) и степеней окисления ($\overset{+2}{Ca}$); единый рендер через
+   `chemEq`/`ionLabel`, не «сырой» текст.
+2. **Уравнения реакций** — всегда сбалансированы; стрелки `=`/`→` (необратимая),
+   `⇌` (обратимая), `↑` (газ), `↓` (осадок), условия над стрелкой ($t$, кат., эл.ток).
+3. **Состояние/признак** — для качественных реакций показывать цвет осадка, пузырьки газа,
+   изменение окраски индикатора (через `testTube`/`indicatorScale`).
+4. **Количественные расчёты** — каждый расчётный § даёт калькулятор/тренажёр с пошаговым
+   решением (дано → формула → подстановка → ответ с единицами), не только готовый ответ.
+5. **Молекулярные модели** — структурная формула + 3D (biochem-core) для каждой изучаемой
+   молекулы (§37–38, §41); для типов решёток — 3D-ячейки.
+6. **Цвета — химически достоверные**: осадки ($Cu(OH)_2$ голубой, $Fe(OH)_3$ бурый,
+   $Zn(OH)_2$ белый); индикаторы (фенолфталеин в щёлочи малиновый, лакмус в кислоте красный,
+   метилоранж в кислоте розовый).
+7. **Безопасность** — где уместно (растворение кислот/щелочей, разбавление) — заметка-«скрепка».
+8. **KaTeX-эскейпы** — в JS-шаблонах двойной backslash (`\\to`, `\\downarrow`, `\\rightleftharpoons`).
+9. **Drag/слайдеры** — `window`-listeners + `{passive:false}` + state ВЫШЕ `redraw()`
+   (стандарт геометрии), `touch-action:none` на draggable SVG/canvas, **без `setPointerCapture`**.
+10. **Без эмоджи** — только inline SVG `.ic`/`.ico` (правило проекта [[feedback_no_emoji]]).
+
+### D. Типы интерактивов по темам 8 класса
+
+| Тип темы | Интерактив |
+|----------|------------|
+| Количество вещества (§3–7, 9) | `moleTriangle`, калькуляторы $M/V_m/N$, sim `stoichiometry` |
+| Химические реакции (§8) | `equationBalancer`, классификатор типов |
+| Классы соединений (§10–21) | `classifier`, матрицы реакций, `indicatorScale`, `solubilityTable`, `activitySeries` |
+| Генетическая связь (§22) | `geneticMap` |
+| Периодический закон / ПСХЭ (§24–28, 34) | `miniPeriodic`, sim `periodic`, графики трендов |
+| Строение атома (§29–33) | sim `bohratom`, sim `orbitals`, sim `radioactive`, `orbitalDiagram` |
+| Химическая связь (§36–41) | slider ЭО, biochem-core 3D, ионная/металлич. решётка, 4 типа кристаллов |
+| ОВР (§42–44) | `oxStateCalc`, `redoxBalancer`, визуализация переноса $e^-$ |
+| Растворы (§46–52) | `dissociationAnim`, график растворимости, sim `solutions`, калькулятор $c$ |
+| Качественные/амфотерность (§18,25) | `testTube` + уравнение + признак |
+
+---
+
+## 📦 СТРУКТУРА КАЖДОГО § (стандарт наполнения)
+
+**Теория (3–4 карточки):**
+- `theory` — основное определение/понятие + наглядная SVG/модель
+- `rule` — ключевая закономерность/формула (рамка)
+- `example` — разобранный пример (реакция/расчёт) с пошаговым рендером
+- (для прикладных §) `apply` — применение/значение (инфографика)
+
+**Интерактивы (4–6 на §):**
+1. **Звёздный виджет** темы (из карты содержания)
+2. **Конструктор/симулятор** (slider / drag / sim из реестра)
+3. **Калькулятор** ($M$, $n$, $w$, $c$, с.о., по уравнению) — где применимо
+4. **DnD-классификатор** (классы веществ, тип связи/реакции, тип решётки)
+5. **Тренажёр** — 5 задач с inline-наглядностью (формула/уравнение/модель в условии)
+6. **Босс §** — 4 интеграционные задачи (+5 XP каждая)
+
+**Дополнительно:** пополнение глоссария (термины §, `[[ссылки]]`), «Вопросы и задания»
+из учебника (адаптированные, с проверкой), проходящий jsdom-тест страницы.
+
+**Финал главы:** итоговая шпаргалка (mini-cards), карта связей (SVG-граф понятий),
+7 интегрированных боссов (+10 XP), achievement «Мастер главы N» (+50 XP, confetti),
+кнопка перехода к следующей главе.
+
+---
+
+## 🚀 ПОРЯДОК РЕАЛИЗАЦИИ (по фазам)
+
+### Phase 0 — Фундамент (hub + каркасы глав)
+- **`chemistry_8_hub.html`** — хаб-каталог 7 глав по образцу `physics_9_hub.html`: палитра
+  **amber**, водяной знак «ХИМИЯ», карточки глав с прогрессом (грузится из
+  `/api/textbooks/chemistry-8/children`), блок «Финал курса» (шпаргалка + боссы — наполняется в Phase 7),
+  achievement-strip «Химик 8 класса», тема (localStorage `chemistry8_theme`).
+- **7 файлов глав** `chemistry_8_intro.html` + `chemistry_8_ch1..ch6.html` — на Phase 0
+  валидные каркасы-заглушки (header с водяным знаком, hero, sidebar-оглавление §, контейнер
+  параграфов, XP/tracker-интеграция), наполнение § — в Phase 1–6.
+- **`/js/chem8_svg.js`** (хелперы B — заглушки → реализация по фазам).
+- Подключить `biochem-core.js` + нужные симуляторы на страницах глав.
+- **Миграция `041_chemistry8_hub.sql`** (следующий номер после `040_content_access.sql`):
+  **INSERT** родителя `chemistry-8` (`html_path='chemistry_8_hub.html'`, `para_count=52`,
+  `color='amber'`, `parent_slug=NULL`) + **7 детей** `chemistry-8-intro`/`-ch1..-ch6`
+  (`parent_slug='chemistry-8'`, свои `html_path`/`para_count`/`color`/`sort_order`) — по образцу
+  `038_physics_9_hub.sql`. Применить `npm run migrate`.
+- jsdom-тест-каркас: хаб строится, все 8 файлов парсятся, ссылки глав ведут на существующие slug.
+
+### Phase 1 — Вводный раздел «Количественные понятия» (§§1–9) + ПР1 — фундамент расчётов
+Базовые движки: калькулятор $M_r$ (biochem-core), `moleTriangle`, связка $m$–$n$–$V$–$N$,
+`equationBalancer`, sim `stoichiometry`. **Критично** — эти расчёты используются во всех главах.
+
+### Phase 2 — Глава 1 «Классы неорганических соединений» (§§10–23) + Лаб.1,2 + ПР2,3
+Самая объёмная. Закладываем `classifier`, `indicatorScale`, `solubilityTable`,
+`activitySeries`, матрицы реакций, `testTube` (первые качественные/нейтрализация),
+`geneticMap` (§22), sim `titration`.
+
+### Phase 3 — Глава 2 «Периодический закон и ПСХЭ» (§§24–28) + Лаб.3
+`miniPeriodic`, sim `periodic`, амфотерность ($Zn(OH)_2$ — обе реакции + `testTube`),
+демонстрация периодичности.
+
+### Phase 4 — Глава 3 «Строение атома» (§§29–35)
+sim `bohratom`, sim `orbitals`, sim `radioactive`, `orbitalDiagram`, графики периодических
+трендов, генератор «паспорта элемента».
+
+### Phase 5 — Глава 4 «Химическая связь» (§§36–41) + Лаб.4
+slider ЭО → тип связи, biochem-core 3D-модели, ионная/металлическая решётки,
+4 типа кристаллических решёток (3D) и связь «тип → свойства».
+
+### Phase 6 — Глава 5 «ОВР» (§§42–45) + Глава 6 «Растворы» (§§46–52) + ПР4
+`oxStateCalc`, `redoxBalancer`, визуализация переноса $e^-$; затем `dissociationAnim`,
+график растворимости, sim `solutions`, калькулятор $c$, ПР4.
+
+### Phase 7 — Финалы глав + общий финал учебника
+Шпаргалки и карты связей по каждой главе; интегрированные боссы + achievements;
+**большой финал**: генетическая карта классов + строение/связь, итоговый босс-квест,
+ачивка «Химик 8 класса»; глоссарий собран и связан `[[ссылками]]`.
+
+### Phase 8 — Качество и админка
+Полный прогон jsdom-тестов (каждый § — builder не stub); аудит баланса уравнений и
+KaTeX/`chemEq`-эскейпов; синхронизация с админкой (если новые sim в `lab.html` →
+обновить `ADMIN_SIMS` в `admin.html` — [[feedback_sims_admin_sync]]); проверка доступа
+по классам/ученикам ([[project_content_access]], `/api/access`).
+
+> Рекомендуемый темп: внутри фазы — по 2–3 § за «волну», каждая волна = commit +
+> проходящий jsdom-тест (правило CLAUDE.md: commit изменённых файлов + push).
+
+---
+
+## 🗄️ ИНТЕГРАЦИЯ С ПРОЕКТОМ
+
+| Точка | Действие |
+|-------|----------|
+| **БД каталог** | `chemistry-8` в `textbooks` **отсутствует** → миграция `041_chemistry8_hub.sql`: INSERT родитель + 7 детей (образец — `038_physics_9_hub.sql`). Каталог `/api/textbooks` показывает только `parent_slug IS NULL`; хаб тянет детей через `/api/textbooks/chemistry-8/children`. |
+| **Прогресс/XP** | Автоматически: `textbook-xp-widget.js` (+5 XP/§), `textbook-tracker.js`, `LS.xp`. Доп. XP за боссов — по образцу `phys7_ch1_widgets.js`. |
+| **Симуляторы** | Реестр `frontend/js/labs/_register-all.js`. Нужные химические sim уже зарегистрированы: `periodic`, `bohratom`, `orbitals`, `radioactive`, `stoichiometry`, `titration`, `qualanalysis`, `solutions`, `chemsandbox`. |
+| **Молекулы** | `biochem-core.js` (парсинг, $M$, 2D/3D, VSEPR). |
+| **Бэкенд** | Роуты готовы: `backend/src/routes/textbooks.js` (catalog/progress/bookmarks). Доступ: `backend/src/services/contentAccess.js`. |
+| **Глоссарий** | Виджет всплывающих определений на странице (общего нет — реализовать). |
+| **Тесты** | `cd backend && npm test` (jsdom). На каждый § — тест: страница строится, builder не stub, уравнения сбалансированы. |
+| **Админка** | Новые sim в `lab.html` → синхронно `ADMIN_SIMS` в `admin.html`. |
+
+---
+
+## ⚠️ КРИТИЧЕСКИЕ ПРАВИЛА
+
+### ❌ НЕ делать
+- «Сырые» формулы текстом — только `chemEq`/`ionLabel`/KaTeX.
+- Несбалансированные уравнения (аудит баланса перед commit).
+- Дублировать молекулярный движок — использовать `biochem-core.js`.
+- `setPointerCapture` (теряется после `innerHTML`-replace) → `window`-listeners + state-flag.
+- `\to`, `\downarrow`, `\rightleftharpoons` без удвоения backslash в JS-шаблонах.
+- Slider-диапазоны за пределы химически возможного (концентрации, температуры, $V_m$).
+- Эмоджи — запрещены; только inline SVG `.ic`.
+- **Grep tool — запрещён**; поиск только `ast-index` ([[reference_sqlite_node]] и правила проекта).
+
+### ✅ Обязательно
+- Каждый commit → jsdom-тест 100% pass.
+- Аудит баланса уравнений + KaTeX-эскейпов после каждой волны.
+- Расчётный § = калькулятор/тренажёр с **пошаговым** решением и единицами измерения.
+- Качественная реакция = уравнение (молек.+, где есть, ионное) **+ видимый признак**.
+- Цвета осадков/индикаторов — химически достоверные.
+- Все builder-функции в конце финальной волны главы — НЕ stub'ы.
+- Коммитить только изменённые файлы (не `git add -A`), сразу push.
+
+---
+
+## 📊 Оценка объёма
+
+| Раздел | § | Лаб/ПР | Ожидаемый LOC |
+|--------|---|--------|---------------|
+| Вводный (кол-во вещества) | 9 | ПР1 | ~7 000 (+`moleTriangle`, `equationBalancer`, `stoichiometry`) |
+| Гл.1 Классы соединений | 14 | Лаб1,2 + ПР2,3 | ~16 000 (+`classifier`, `solubilityTable`, `activitySeries`, `geneticMap`) |
+| Гл.2 ПЗ и ПСХЭ | 5 | Лаб3 | ~5 000 (+`miniPeriodic`, амфотерность) |
+| Гл.3 Строение атома | 7 | — | ~7 000 (+`orbitalDiagram`, sim bohratom/orbitals/radioactive) |
+| Гл.4 Химическая связь | 6 | Лаб4 | ~6 500 (+3D-модели, 4 решётки) |
+| Гл.5 ОВР | 4 | — | ~4 500 (+`oxStateCalc`, `redoxBalancer`) |
+| Гл.6 Растворы | 7 | ПР4 | ~7 000 (+`dissociationAnim`, sim solutions, калькулятор $c$) |
+| Финалы глав + общий | — | — | ~5 000 |
+| `/js/chem8_svg.js` хелперы | — | — | ~3 000 |
+| Хаб + 7 каркасов глав (Phase 0) | — | — | ~3 000 |
+| **Итого** | **52** | **4 лаб + 4 ПР** | **~64 000 LOC** |
+
+---
+
+## 🎬 Запуск
+
+**Phase 0**: `chemistry_8_hub.html` (по образцу `physics_9_hub.html`) + 7 каркасов глав
+(`chemistry_8_intro.html`, `chemistry_8_ch1..ch6.html`) + `/js/chem8_svg.js` (скелет) +
+подключение `biochem-core.js`/симуляторов + миграция `041_chemistry8_hub.sql` (родитель + 7 детей)
++ `npm run migrate` + jsdom-каркас.
+**Phase 1**: Вводный раздел (§§1–9) — закладываем движки расчётов (`moleTriangle`,
+`equationBalancer`, sim `stoichiometry`), от которых зависят все главы.
+
+Дальше — последовательно по главам (Phase 2 → 6), затем финалы (Phase 7) и качество (Phase 8).

plans/textbooks-8/PLAN_CHEMISTRY_8_UPGRADE.md

@@ -0,0 +1,102 @@
+# План апгрейда: Химия 8 — больше интерактива и наполнения
+
+> База готова: вводный раздел + 6 глав, все 52 §, движок `chem8_engine.js` + 12 виджетов,
+> 37 тестов. Этот план — **следующий уровень**: финал курса, глоссарий, новые движки-виджеты,
+> 3D-модели молекул, обогащение контента и финалов глав, синхронизация с админкой.
+
+Принципы (как в базовом плане): эталонная SPA-структура, без эмоджи (только inline SVG `.ic`),
+KaTeX-эскейпы, jsdom-проверка каждого нового виджета, поиск через `ast-index`, изоляция
+химии на ветке `feature/chemistry-8` (cherry-pick из рабочей ветки).
+
+---
+
+## U1 — Финал курса в хабе (Phase 7) ⭐ старт
+
+`chemistry_8_hub.html` сейчас содержит заглушку «Финал курса появится позже». Заменить на
+полноценный финал по образцу `physics_9_hub.html`:
+
+- **Шпаргалка курса** — 7 cheat-cards (вводный + 6 глав) с ключевыми формулами/реакциями.
+- **10 интегрированных боссов** — задачи, каждая связывает ≥2 раздела (например, «масса осадка
+  по уравнению РИО», «c раствора + расчёт по уравнению»). +15 XP за босса.
+- **Ачивка «Химик 8 класса»** — при всех 10 → +150 XP, confetti, CTA «К каталогу».
+- Прогресс-бар боссов, lazy-render при раскрытии аккордеона, localStorage
+  (`chemistry8_course_bosses`, `chemistry8_course_master`).
+- jsdom-тест: финал раскрывается, 10 боссов рендерятся, KaTeX, без ошибок.
+
+## U2 — Глоссарий (Phase 8a)
+
+Единый виджет всплывающих определений терминов на всех 8 страницах:
+
+- `chem8_glossary.js` — словарь ~120 терминов (оксид, кислота, основание, соль, моль, валентность,
+  степень окисления, электроотрицательность, изотоп, орбиталь, растворимость, концентрация …).
+- Авто-подсветка терминов в тексте `.card-body` (`<abbr class="gloss" data-term="…">`) +
+  popover с определением и `[[ссылками]]` на связанные термины.
+- Кнопка «Глоссарий» в header каждой главы → модальное окно со списком/поиском.
+- Тест: словарь парсится, термин даёт определение.
+
+## U3 — Новые движки-виджеты (chem8_svg.js)
+
+Заменить оставшиеся заглушки реальными реализациями + добавить новые:
+
+| Виджет | § | Что делает |
+|--------|---|------------|
+| `dissociationAnim` | §47, ТЭД | анимация распада соли/кислоты на ионы в воде (canvas/SVG-частицы) |
+| `geneticMap` | §22 | интерактивный граф классов (Me→оксид→основание→соль), клик по ребру → реакция |
+| `redoxBalancer` | §44 | общий балансировщик ОВР методом e-баланса (не преднабор) |
+| `reactionMatrix` | §11,14,17,20 | матрица «реагент × реагент» → продукт/нет реакции |
+| `phScale` | §13,16 | расширенная шкала pH с примерами бытовых веществ |
+| `ionConverter` | §9,РИО | молекулярное → полное ионное → сокращённое ионное уравнение |
+
+Каждый — с jsdom-смоук-тестом монтажа и расчёта.
+
+## U4 — 3D-модели молекул (biochem-core)
+
+Интегрировать `biochem-core.js` (window.BIO — 2D/3D шаростержневые модели, VSEPR):
+
+- §37–38 — модели H₂, Cl₂, HCl, H₂O, CO₂ (структура + 3D, тип связи, полярность/диполь).
+- §41 — 3D-ячейки 4 типов решёток.
+- Хелпер `chem8Mol(mount, formula)` — обёртка над BIO для монтажа модели по формуле.
+- Тест: модель строится, молярная масса совпадает с `Chem8.molarMass`.
+
+## U5 — Обогащение контента §
+
+По канве учебников Исаченковой (см. [[reference_textbook_sources]]):
+
+- **8–10 задач** на § (сейчас 3–5): добавить уровни сложности, задачи «для любознательных».
+- **life-grid** примеры из жизни в каждый § (где уместно).
+- **insight-box** «это интересно» / историческая справка.
+- **«Контрольные вопросы»** из учебника (адаптированные) — уже частично есть, расширить.
+- Разобранные **примеры с пошаговым решением** (`exa-step`) в расчётных §.
+
+## U6 — Финалы глав (интегрированные боссы)
+
+Сейчас финал главы = шпаргалка + POOLS-задачи. Усилить:
+
+- Каждый финал главы → **карта связей** (SVG-граф понятий главы).
+- **Achievement-strip** «Мастер главы N» (+50 XP, confetti) при полном прохождении.
+- Кнопка перехода к следующей главе.
+
+## U7 — Синхронизация с админкой и доступом (Phase 8b)
+
+- Проверить, что `chemistry-8` и 7 детей видны в админке (`/api/textbooks/admin/all`).
+- Если добавлялись sim в `lab.html` → обновить `ADMIN_SIMS` в `admin.html` ([[feedback_sims_admin_sync]]).
+- Доступ по классам/ученикам ([[project_content_access]], `/api/access`) — проверить выдачу.
+- Прогресс/XP агрегируется в хабе (`/api/textbooks/chemistry-8/children`) — проверить.
+
+## U8 — Качество
+
+- jsdom-смоук на каждый новый виджет (монтаж + расчёт).
+- Аудит баланса всех уравнений и KaTeX/`chemEq`-эскейпов.
+- Полный прогон `cd backend && npm test`.
+- Аудит доступности (контраст, фокус, клавиатура для боссов/тренажёров).
+
+---
+
+## Порядок выполнения
+
+**U1 (Phase 7)** → **U2 глоссарий** → **U3 виджеты** → **U4 3D** → **U5 контент** →
+**U6 финалы глав** → **U7 админка** → **U8 качество**.
+
+Темп: один U-блок = волна = commit + проходящие тесты + cherry-pick на `feature/chemistry-8`.
+
+**Старт: U1 — финал курса в хабе.**