docs(chemistry7): план визуального и интерактивного апгрейда (анимации)
~15 флагманских анимированных интерактивов поверх готового учебника: общий движок chem7_anim.js (частицы, пузырьки, пламя, морфинг цвета, RAF-реестр с паузой вне экрана), апгрейд виджетов по главам (разделение смесей, 3D-молекулы, горение, ряд активности с пузырьками, электролиз 2:1, титрование). Фазы V0-V5, правила (reduced-motion, тёмная тема, перф, достоверная химия). Монтаж в существующие контейнеры. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Maxim Dolgolyov
@@ -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 титрование).
|
||||||
Reference in New Issue
Block a user