Ноты

Тренажёр для ребёнка: узнавать ноты на нотном стане в скрипичном и басовом ключе. Работает офлайн, ставится на главный экран как приложение.

Приложение показывает одну ноту и спрашивает, как она называется. Десять вопросов — занятие, за занятие дают звёзды, неузнанные ноты можно повторить отдельно.

Если нота не узнаётся, подсказка показывает ближайшую опорную ноту и предлагает посчитать от неё ступени — так ноты и учат помимо тренажёра. За три верных подряд загорается огонёк, за занятие без ошибок сыплется конфетти и играет фанфара.

Тема следует за системой: светлая днём, тёмная вечером. Сам нотный стан остаётся листом бумаги в любой — ноты ребёнок читает чёрными по белому.

Полное описание — docs/SPEC.md. Что и почему решали — docs/DECISIONS.md.

Состояние

Рабочее целиком: семь уровней от трёх нот до двух ключей вперемешку, занятие, подсказка по опорным нотам, итог со звёздами, работа над ошибками, звук нот, прогресс между запусками, офлайн.

Не сделано: узнавание на слух, длительности и ритм, знаки альтерации, несколько детей на одном устройстве.

Запуск

Приложение — набор статических файлов, сборка не нужна. Но модули ES и сервис-воркер не работают через file://, поэтому нужен любой локальный сервер:

powershell -ExecutionPolicy Bypass -File tools/serve.ps1

Затем открыть http://localhost:4180. Порт меняется ключом -Port. Node в проекте не используется, но если он установлен, подойдёт и npx serve ..

Проверки

Открыть /tests/index.html на том же локальном сервере. Проверки идут в браузере, без сборки и без установки чего-либо; зелёная полоса сверху и галочка в заголовке вкладки означают, что всё прошло.

Работают они на отдельном ключе хранения notes.test — звёзды ребёнка при запуске не трогаются. Сервис-воркер страница снимает сама, иначе она показывала бы не то, что лежит в репозитории, а то, что осталось в кэше у этого браузера. Снимает она только своё — воркер «Нот» и кэши notes-*: на Pages у того же адреса есть соседи, и их офлайн трогать нельзя.

На каждый push и pull request те же проверки прогоняет GitHub Actions: поднимает статический сервер, открывает эту же страницу настоящим браузером и читает итог. Отдельным шагом сверяется список офлайн-кэша с деревом проекта.

Разработка

index.html          разметка оболочки, без стилей и скриптов
css/style.css       все стили, цвета переменными в :root
sw.js               кэш и офлайн; при правке файлов поднимать APP_VERSION
manifest.json       описание PWA

js/main.js          точка входа
js/app.js           экраны и маршрутизация (#/занятие/октава)
js/version.js       версия приложения

js/core/notes.js    ноты, ключи, положение на стане, опоры, частоты
js/core/staff.js    рисование стана, ключей и ноты
js/core/levels.js   уровни и их наборы нот
js/core/drill.js    движок занятия: очередь, ответы, счёт
js/core/store.js    прогресс в localStorage
js/core/tone.js     звук нот через Web Audio
js/core/haptics.js  вибрация на ответ
js/core/actions.js  делегирование событий по data-action
js/core/ui.js       сборка разметки с экранированием

js/modules/home.js    выбор уровня
js/modules/drill.js   экран занятия
js/modules/result.js  итог занятия

docs/               описание проекта и журнал решений
tests/              проверки, запускаются в браузере
tools/serve.ps1     локальный сервер для разработки
tools/make-icons.ps1 генерация значков, включая maskable
tools/check-precache.ps1 сверка списка офлайн-кэша с деревом проекта
tools/ci-tests.mjs  запуск тех же проверок из CI настоящим браузером

Правила, которые важно не нарушить:

• музыкальная правда живёт в js/core/notes.js и нигде больше: ни один экран не считает положение ноты сам;
• любое значение, попадающее в разметку, проходит через ui.esc() или шаблон ui.html;
• обработчики вешаются через data-action, а не onclick;
• цвета берутся из CSS-переменных, а не задаются в JavaScript;
• при изменении состава файлов обновлять список в sw.js и поднимать APP_VERSION.

Публикация

GitHub Pages из ветки main. Файл .nojekyll обязателен — иначе Pages игнорирует каталоги, начинающиеся с подчёркивания. Все пути в проекте относительные, поэтому приложение работает и из подкаталога вида /Notes/.