# План: визуальный и интерактивный апгрейд учебника «Химия 7»

**Дата:** 2026-05-30
**Контекст:** дополнение к [PLAN_CHEMISTRY_7.md](PLAN_CHEMISTRY_7.md). Базовый учебник реализован
полностью (все 26 §, 4 главы, виджеты в `chem7_ch1..4_widgets.js`), но интерактивы сейчас
в основном **статичные**: SVG-картинки, клик-раскрытие, `<select>`, цветные полоски.
**Цель этого плана** — превратить ключевые виджеты во **флагманы**: красивые, анимированные,
«живые» интерактивы с частицами, плавными переходами и геймификацией, которые запоминаются
семикласснику. Аналог [PLAN_PHYSICS_9_ADVANCED_INTERACTIVES.md](../textbooks-9/PLAN_PHYSICS_9_ADVANCED_INTERACTIVES.md).

---

## Принцип «флагмана» (красиво + анимированно)

Не очередной `select`+текст, а:
- **анимация в реальном времени** (`requestAnimationFrame`): частицы, пузырьки, пламя, капли;
- **прямое управление** мышью/тапом (drag, клик, ползунок), отклик сразу;
- **плавные переходы** (easing, морфинг цвета, появление/исчезновение);
- **достоверная химия в движении** (пузырьки H₂, рост кристаллов, цвет осадка, объёмы 2:1);
- **микро-геймификация**: подсветка успеха, конфетти на боссах, мини-цель в каждом флагмане;
- **бережно к производительности и доступности** (пауза вне экрана, `prefers-reduced-motion`).

Принцип внедрения — **без переписывания**: флагманы монтируются в **уже существующие
контейнеры** виджетов (`#p15-burn`, `#p23-water`, `#p9-bld`, …). Старый статичный код заменяется
анимированным внутри тех же `mount_*`. Тесты (`chemistry7-page.test.js`) и движок не трогаем.

---

## A. Общий движок `frontend/js/chem7_anim.js` (фундамент)

Один неймспейс `window.Chem7Anim` со всем, что нужно флагманам, чтобы не дублировать код:

```js
// RAF-реестр с авто-очисткой при уходе с § (goTo) и паузой вне вьюпорта
Chem7Anim.loop(canvasOrSvg, stepFn) -> handle{stop()}     // RAF + IntersectionObserver пауза
Chem7Anim.particles(host, opts)                            // система частиц (пузырьки, пар, искры, дым)
Chem7Anim.bubbles(host, {rate, color, riseSpeed})          // поток пузырьков газа (H₂, O₂, CO₂)
Chem7Anim.flame(host, {color, intensity, sparks})          // анимированное пламя (огонь/искры/дым)
Chem7Anim.colorMorph(el, fromColor, toColor, ms)           // плавная смена цвета (осадок, индикатор)
Chem7Anim.dropletInto(host, {color, onLand})               // падающая капля + расплыв цвета
Chem7Anim.grow(el, ms) / fadeSwap(el, htmlA, htmlB, ms)    // появление/морфинг содержимого
Chem7Anim.ease(t)                                          // easeInOutCubic и пресеты
Chem7Anim.confettiSmall(host)                              // лёгкое празднование (без CDN)
Chem7Anim.reduced()                                        // true при prefers-reduced-motion → упрощить
```

- Один RAF-цикл на флагман; `handle.stop()` вызывается из cleanup при `goTo` (хук добавить в
  движок или дергать через `IntersectionObserver`, чтобы анимация на закрытой секции не жгла CPU).
- Частицы — на `<canvas>` (производительно) либо SVG (≤30 элементов, легко стилизуется тёмной темой).
- 3D-молекулы — **через `biochem-core.js`** (там уже есть шаростержневые 3D-модели), не дублировать.

---

## B. Визуальный стандарт «красиво»

1. **Палитра главы** уже задана (emerald/cyan/violet/blue) — анимации берут акцент главы
   (`var(--pri)`, `var(--pri-d)`, `var(--pri-soft)`), а не хардкод.
2. **Достоверные цвета веществ**: пламя серы синее, магния — ослепительно-белое, искры железа —
   оранжевые; осадок Cu(OH)₂ голубой, медь красная, малахит зелёный→CuO чёрный; индикаторы
   (лакмус, метилоранж, фенолфталеин) — реальные оттенки.
3. **Плавность**: все переходы 200–500 мс с easing; никаких резких скачков; hover-микроотклик
   (лёгкий подъём/тень) на кликабельных элементах.
4. **Карточка-рамка** флагмана единая: заголовок, подсказка-цель, область анимации, контролы.
5. **Тёмная тема**: все цвета через CSS-переменные/`html.dark`-ветки; canvas перечитывает фон.
6. **Доступность**: при `prefers-reduced-motion` — статичный финальный кадр вместо цикла;
   `aria-label` на canvas; управление и с клавиатуры.
7. **Без эмодзи** — только inline SVG `.ic` (правило проекта [[feedback_no_emoji]]).
8. **Производительность**: пауза анимации, когда виджет не на экране (`IntersectionObserver`);
   `cancelAnimationFrame` при уходе с §; ≤1 RAF-цикл на видимый флагман.

---

## C. Флагманы по главам (текущий виджет → анимированный апгрейд)

### Глава 1 — Первоначальные понятия (emerald)
| § | Контейнер | Сейчас | Флагман (анимация) |
|---|---|---|---|
| §2 / ПР1 | `#p2-sep` / `#pr1-sep` | выбор метода (текст) | **Симулятор разделения смесей**: частицы песка оседают на фильтре, вода капает; при выпаривании — пар уходит частицами, растут кристаллы соли; магнит притягивает железные опилки (полёт частиц). RAF + `particles` |
| §5 / §6 | `#p5-gal` / `#p6-gal` | статичные шарики | **3D-модели молекул** (biochem-core): O₂/O₃/H₂/N₂/H₂O/CO₂/CH₄/NH₃ — вращение мышью, лёгкое «дыхание» атомов |
| §9 | `#p9-bld` | селекты → формула | **Конструктор со «связями-крючками»**: у атомов выезжают чёрточки валентности; верное число — атомы с щелчком соединяются (snap + подсветка), неверное — отталкиваются (shake) |
| §10 / ЛО1 | `#p10-signs` / `#lo1-signs` | список признаков | **Анимированные опыты-демо**: малахит зеленеет→чернеет (colorMorph) + пузырьки газа; CuSO₄+NaOH — падает синий осадок (частицы оседают); горение серы — синее пламя + «запах» (волны) |
| §11 | `#p11-bal` | статичные весы (toggle) | **Живые весы массы**: коромысло качается и встаёт ровно; молекулы перелетают слева направо и перестраиваются в продукты; стрелка не сдвигается — «масса сохранилась» |
| §12 | `#p12-mount` | балансировщик (Chem8) | **Живой балансировщик**: атомы-шарики каждого элемента слева/справа; при дисбалансе сторона «перевешивает» и мигает; ползунок коэффициента анимирует число молекул до баланса |

### Глава 2 — Кислород (cyan)
| § | Контейнер | Сейчас | Флагман |
|---|---|---|---|
| §13 | `#p13-air` | статичная полоса | **Живая диаграмма воздуха**: донат «прорисовывается», внутри летают молекулы газов в пропорции 78/21/1; hover — сектор подсвечивается и всплывает |
| §15 | `#p15-burn` | статичное пламя + ур-е | **Симулятор горения**: реальное пламя частицами (`flame`), цвет по веществу (S — синее, Mg — белое, Fe — оранжевые искры), дым; вещество «убывает», оксид оседает; уравнение проявляется |
| §17 / ПР2 | `#p17-prod` / `#pr2-test` | схема (текст) | **Прибор получения O₂**: нагрев колбы (свечение), пузырьки поднимаются по трубке, газ вытесняет воду в сосуде; тлеющая лучинка **вспыхивает** (вспышка пламени) |

### Глава 3 — Водород (violet)
| § | Контейнер | Сейчас | Флагман |
|---|---|---|---|
| §19 | `#p19-rx` | текст + свотч | **Восстановление CuO**: пробирка нагревается, поток H₂; чёрный CuO **плавно краснеет** до меди (colorMorph), на стенках конденсируются капли воды |
| §20 / ЛО3 | `#p20-ind` / `#lo3-ind` | цветная полоска | **Капля индикатора**: капля падает в раствор и **цвет расплывается** радиально (лакмус→красный, метилоранж→розовый) |
| §21 | `#p21-act` | кликабельный ряд | **Интерактивный ряд активности**: drag металла в стакан с кислотой → если левее H₂, идут **пузырьки H₂** (bubbles) и металл «тает»; правее — тишина; шкала «активности» подсвечивается градиентом |
| ЛО4 | `#lo4-rx` | текст-результат | **Пробирка металл+кислота**: выбор металла/кислоты → анимация пузырьков (Zn/Fe/Mg) или их отсутствие (Cu); уравнение всплывает |
| §22 | `#p22-salt` | селекты → формула | **Сборка соли**: атом металла «выталкивает» водород из кислоты (H₂ улетает пузырьком), кислотный остаток соединяется с металлом → формула соли собирается с анимацией |
| ПР3 | `#pr3-test` | 2 кнопки | **Проверка чистоты H₂**: «хлопок» (вспышка + волна) для смеси с воздухом vs спокойное пламя для чистого |

### Глава 4 — Вода (blue)
| § | Контейнер | Сейчас | Флагман |
|---|---|---|---|
| §23 | `#p23-water` | статичные пробирки 2:1 | **Электролиз воды**: на электродах рождаются пузырьки, трубка с H₂ наполняется **вдвое быстрее**, чем с O₂; счётчик объёмов растёт 2:1 в реальном времени |
| §24 / ЛО5 | `#p24-ind` / `#lo5-ind` | цветная полоска | **Капля индикатора в щёлочи**: фенолфталеин расцветает **малиновым** (colorMorph), лакмус — синим |
| §25 / ПР4 | `#p25-neu` / `#pr4-neu` | стакан (toggle) | **Титрование-нейтрализация**: капли кислоты падают в малиновый раствор, цвет **постепенно бледнеет** до бесцветного по мере добавления; «перелил» — предупреждение; уравнение всплывает |
| §26 | `#p26-eco` | список-кнопки | **Круговорот и очистка воды**: анимированная инфографика — испарение→облака→дождь→река; на станции вода проходит фильтр и обеззараживание (поток капель по этапам) |

**Звёздные флагманы (вау-эффект):** §15 горение, §21 ряд активности с пузырьками, §23 электролиз
2:1, §25 титрование, §5/§6 3D-молекулы, §2 разделение смесей.

---

## D. Порядок реализации (по фазам)

### Phase V0 — Движок `chem7_anim.js` (фундамент)
- Создать `frontend/js/chem7_anim.js` (`window.Chem7Anim`): RAF-реестр + `IntersectionObserver`-пауза,
  система частиц на canvas, `bubbles`, `flame`, `colorMorph`, `dropletInto`, `confettiSmall`, `ease`, `reduced`.
- CSS-хелперы (микро-переходы, hover-подъём, рамка флагмана) — добавить в общий
  `chem7-anim.css` (подключить в 4 главах) **или** инлайн-`<style>` в главах (как тема).
- Подключить `chem7_anim.js` на 4 страницы глав (с `?v=YYYYMMDD` cache-busting).
- Хук очистки: в `goTo`/unmount останавливать активные циклы (через `IntersectionObserver` на хосте
  виджета — не требует правок движка).
- jsdom-тест: движок грузится, `loop/particles` создают canvas без ошибок, `stop()` чистит RAF.

### Phase V1 — Глава 1 (emerald): §2 смеси, §5/§6 3D-молекулы, §9 валентность, §10/§11/§12 реакции
Пилот: §15-стиль не тут, но §5/§6 (3D через biochem-core) и §2 (частицы) — лучшие первые «вау».

### Phase V2 — Глава 2 (cyan): §13 диаграмма, §15 горение (звёздный), §17/ПР2 прибор O₂
§15 — флагман главы; на нём отрабатываем `flame`/`particles`/«вспышку лучинки».

### Phase V3 — Глава 3 (violet): §19 восстановление, §20/ЛО3 индикаторы, §21 ряд активности (звёздный), ЛО4, §22 соли, ПР3
§21 с drag-and-bubbles — флагман; переиспользуем `bubbles`/`colorMorph` из V2.

### Phase V4 — Глава 4 (blue): §23 электролиз (звёздный), §24/ЛО5 индикаторы, §25/ПР4 титрование (звёздный), §26 круговорот
§23 (2:1) и §25 (титрование) — два флагмана; добиваем `dropletInto` и счётчики.

### Phase V5 — Полировка
- Аудит: каждый RAF имеет пауза/`stop`, пауза вне экрана, корректный cleanup при `goTo`.
- `prefers-reduced-motion`: статичный кадр; проверить тёмную тему на всех canvas.
- Производительность: профиль на слабом устройстве; ≤1 активный цикл на видимый флагман.
- Микро-геймификация: `confettiSmall` на победе боссов глав; подсветка успеха в флагманах.

> Темп: 2–3 флагмана за «волну», каждая = commit + проходящий тест (правило CLAUDE.md).
> После каждой волны — **проверка персиста правок** через `node`-маркеры (флака кириллического
> пути, см. [[project_chemistry7_textbook]] / [[feedback_verify_edits_applied]]) и push.

---

## E. Технологический стек

- **Canvas 2D** — частицы, пузырьки, пламя, дым (производительно, десятки-сотни частиц).
- **SVG + CSS-анимации/transition** — лёгкие переходы, морфинг цвета, появление (≤30 элементов).
- **biochem-core.js** — 3D-модели молекул (вращение) — НЕ дублировать.
- **`Chem8.chemEq`** — рендер уравнений (всплывающие формулы) — переиспользовать.
- **requestAnimationFrame** + RAF-реестр в `chem7_anim.js`; `IntersectionObserver` — пауза вне экрана.
- **Web Audio (опционально)** — лёгкий «хлопок» гремучего газа, «пшик» лучинки (с тумблером звука, по умолчанию выкл).
- **Без внешних CDN** для анимаций (свой `confettiSmall`); KaTeX/biochem-core уже подключены.

### Шаблон флагмана (внутри существующего `mount_*`)
```js
function mount_p15() {
  var host = $('p15-burn'); if (!host || host._built) return; host._built = 1;
  // ... контролы (select вещества + кнопка) ...
  var anim = null;
  function ignite(fuel){
    if (anim) anim.stop();
    anim = Chem7Anim.flame(host.querySelector('.stage'), { color: fuel.flame, sparks: fuel.el==='Fe' });
    // дым, убывание вещества, оседание оксида, всплытие уравнения...
  }
  // пауза вне экрана + stop при уходе:
  Chem7Anim.onHidden(host, function(){ if (anim) anim.stop(); });
}
```

---

## F. Критические правила

### ❌ НЕ делать
- Бесконечный RAF без паузы/`stop` (жжёт CPU/батарею) — всегда `IntersectionObserver`-пауза + cleanup.
- Хардкод цветов мимо палитры главы и тёмной темы.
- Анимации без `prefers-reduced-motion`-ветки.
- Дублировать 3D-движок молекул — только `biochem-core.js`.
- Эмодзи — только inline SVG `.ic`.
- Менять химию ради «красоты» (объёмы 2:1, достоверные цвета пламени/осадков/индикаторов).
- Ломать тесты `chemistry7-page.test.js` (флагманы монтируются в те же контейнеры; ассерты на наличие узлов оставить рабочими).

### ✅ Обязательно
- Один RAF-цикл на видимый флагман; `stop()` при уходе с § и пауза вне вьюпорта.
- Достоверные цвета и пропорции (пламя S синее / Mg белое / Fe искры; H₂:O₂=2:1; осадки/индикаторы).
- Тёмная тема и `prefers-reduced-motion` проверены на каждом флагмане.
- После волны: jsdom-тест зелёный + **проверка персиста** правок `node`-маркером + push.
- Cache-busting `?v=YYYYMMDD` на `chem7_anim.js` и обновлённых `chem7_chN_widgets.js`.

---

## G. Оценка объёма

| Блок | Что | LOC |
|------|-----|-----|
| V0 движок | `chem7_anim.js` (частицы, bubbles, flame, colorMorph, droplet, RAF-реестр, confetti) + CSS | ~1 200 |
| V1 Гл.1 | смеси, 3D-молекулы, валентность-крючки, реакции/весы/балансировщик | ~1 400 |
| V2 Гл.2 | диаграмма воздуха, горение (звёздный), прибор O₂ | ~1 100 |
| V3 Гл.3 | восстановление, индикаторы-капля, ряд активности (звёздный), соли, ПР3 | ~1 400 |
| V4 Гл.4 | электролиз 2:1 (звёздный), индикаторы, титрование (звёздный), круговорот | ~1 300 |
| V5 полировка | reduced-motion, тёмная тема, перф, конфетти, аудит | ~400 |
| **Итого** | **~15 флагманов + движок** | **~6 800 LOC** |

Прирост идёт **поверх** готового учебника: меняются тела `mount_*` (статика → анимация), добавляется
один общий движок. Базовая логика (POOLS, теория, прогресс, KaTeX) не трогается.

---

## H. Связанные документы
- [PLAN_CHEMISTRY_7.md](PLAN_CHEMISTRY_7.md) — базовый учебник (реализован).
- [PLAN_PHYSICS_9_ADVANCED_INTERACTIVES.md](../textbooks-9/PLAN_PHYSICS_9_ADVANCED_INTERACTIVES.md) — образец «флагманского» подхода (RAF, геймификация, ленивая загрузка).
- [[project_chemistry7_textbook]] — статус курса, контейнеры виджетов, флака кириллического пути.

---

## 🎬 Запуск
**Phase V0**: `chem7_anim.js` (движок частиц/RAF) + подключение на 4 страницы + jsdom-тест каркаса.
**Phase V1**: пилот на Главе 1 — §5/§6 3D-молекулы (biochem-core) и §2 разделение смесей (частицы):
самые быстрые «вау» с минимальным риском. Если заходит — катим V2→V4 по звёздным флагманам
(§15 горение, §21 ряд активности, §23 электролиз, §25 титрование).