From c1ef1ecee9d5d83568f33b313824e66e0955d116 Mon Sep 17 00:00:00 2001
From: Maxim Dolgolyov <maxim.dolgolyov@gmail.com>
Date: Sat, 30 May 2026 19:25:06 +0300
Subject: [PATCH] =?UTF-8?q?docs(chemistry7):=20=D0=BF=D0=BB=D0=B0=D0=BD=20?=
 =?UTF-8?q?=D0=B2=D0=B8=D0=B7=D1=83=D0=B0=D0=BB=D1=8C=D0=BD=D0=BE=D0=B3?=
 =?UTF-8?q?=D0=BE=20=D0=B8=20=D0=B8=D0=BD=D1=82=D0=B5=D1=80=D0=B0=D0=BA?=
 =?UTF-8?q?=D1=82=D0=B8=D0=B2=D0=BD=D0=BE=D0=B3=D0=BE=20=D0=B0=D0=BF=D0=B3?=
 =?UTF-8?q?=D1=80=D0=B5=D0=B9=D0=B4=D0=B0=20(=D0=B0=D0=BD=D0=B8=D0=BC?=
 =?UTF-8?q?=D0=B0=D1=86=D0=B8=D0=B8)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

~15 флагманских анимированных интерактивов поверх готового учебника:
общий движок chem7_anim.js (частицы, пузырьки, пламя, морфинг цвета,
RAF-реестр с паузой вне экрана), апгрейд виджетов по главам
(разделение смесей, 3D-молекулы, горение, ряд активности с пузырьками,
электролиз 2:1, титрование). Фазы V0-V5, правила (reduced-motion,
тёмная тема, перф, достоверная химия). Монтаж в существующие контейнеры.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 plans/textbooks-7/PLAN_CHEMISTRY_7_VISUAL.md | 227 +++++++++++++++++++
 1 file changed, 227 insertions(+)
 create mode 100644 plans/textbooks-7/PLAN_CHEMISTRY_7_VISUAL.md

diff --git a/plans/textbooks-7/PLAN_CHEMISTRY_7_VISUAL.md b/plans/textbooks-7/PLAN_CHEMISTRY_7_VISUAL.md
new file mode 100644
index 0000000..dbca6ac
--- /dev/null
+++ b/plans/textbooks-7/PLAN_CHEMISTRY_7_VISUAL.md
@@ -0,0 +1,227 @@
+# План: визуальный и интерактивный апгрейд учебника «Химия 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 титрование).