easy-png-tools2/docs/archive/plan-tool-workbench.md

План: декомпозиция страницы инструмента, реактивные параметры, предпросмотр маски

СТАТУС: ВЫПОЛНЕН 2026-08-23.

1. Зачем

• Страница инструмента (ToolPage.svelte) разрослась: состояние процесса, загрузка файлов, вставка из буфера и разметка трёх зон живут в одном файле.
• Назревают два требования к процессу: параметры применяются автоматически без кнопки; у части утилит на экране показывается одно — визуализация фильтра/маски, а скачивается (и в будущем передаётся следующему инструменту) другое — результат.

2. Контракт «результат и маска» в реестре

• run(img, params) — как сейчас: возвращает итоговое изображение. Его скачивают и будут передавать дальше по цепочке.
• Запись реестра получает опциональное поле preview?(img, params) — возвращает картинку для показа на экране (маску/фильтр).
• Если у записи есть preview, в карточке результата появляется переключатель «Показать маску». Включён — на превью маска, выключен (по умолчанию) — результат. Скачивание всегда отдаёт результат run, независимо от положения переключателя.
• Первая реализация — удаление цвета: в ядро добавляется чистая функция colorMask(img, hex, tolerance) — чёрно-белая маска, где удаляемые пиксели белые; с юнит-тестами; preview записи вызывает её.

3. Декомпозиция страницы

Новая папка components/tool/; карточки — чисто отображательные, состояние живёт только в оркестраторе:

• SourceCard.svelte — левая половина сцены: пусто → зона перетаскивания; загружено → превью исходника под оверлеем замены с кнопкой «Заменить изображение».
• ResultCard.svelte — правая половина: пустые состояния, превью результата или сводка, чип «Пересчёт…», кнопка скачивания, при наличии preview — переключатель маски.
• ParamsCard.svelte — форма параметров и подпись «Изменения применяются автоматически»; для инструментов без параметров не выводится.
• ToolPage.svelte остаётся оркестратором: состояние (исходник, результат, сводка, статус, ошибка, значения), декодирование файлов, вставка из буфера, сброс, токен запусков и эффект с задержкой. Ожидаемо худеет примерно вдвое.

Карточки переиспользуются будущим многошаговым режимом.

4. Реактивные параметры (в этом же проходе)

• Кнопки «Применить» больше нет ни у одного инструмента.
• Изменение параметра запускает вычисление через 300 мс после последнего изменения; каждое новое изменение перезапускает таймер.
• Токен запусков: если во время вычисления параметры поменялись, устаревший ответ отбрасывается.
• Загрузка и замена файла считают сразу и подавляют ровно один авто-запуск эффекта.
• Ошибка пересчёта — баннер сверху, прежний результат не сбрасывается.

5. Этапы и проверки

• A. Декомпозиция — перенос разметки в три карточки один к одному, поведение не меняется. Проверка: check/build, визуально идентично.
• B. Реактивность — токен, задержка, чип пересчёта, минус кнопка. Проверка: смоук §6 пп. 1–6.
• C. Маска — типы реестра, colorMask с тестами, переключатель в карточке результата, пример на удалении цвета. Проверка: тесты + смоук §6 пп. 7–9.
• D. Итог — полный прогон test/check/build.

6. Смоук-чеклист

1. Загрузка файла → результат появляется сразу.
2. Изменить параметр → около 0.3 с и результат обновился сам.
3. Быстро изменить яркость несколько раз → одна финальная версия, промежуточные не мелькают.
4. Во время пересчёта чип виден, предыдущий результат не исчезает.
5. Инструмент без параметров и информационная страница ведут себя как раньше.
6. Некорректные параметры (обрезка вне картинки) → баннер ошибки, прежний результат цел.
7. Переключатель «Показать маску» у удаления цвета: включён — белым по чёрному видно, что удалится; выключен — обычный полупрозрачный результат.
8. С включённой маской скачивание всё равно сохраняет прозрачный результат, а не маску.
9. Замена исходника возвращает переключатель маски в выключенное состояние.

7. Критерии готовности

• ToolPage содержит только оркестрацию состояния и эффектов; вся разметка панелей — в components/tool/*.
• Кнопки «Применить» нет ни на одной странице.
• Скачивание всегда соответствует run; экран может показывать preview.
• test/check/build зелёные, смоук §6 пройден.

8. Что сознательно не делаем

• Вынос вычислений в веб-воркер; настраиваемая задержка — фиксированные 300 мс.
• Редактор масок (кисть, слои, история) — только автогенерация из параметров инструмента.
• Передача результата между инструментами — придёт вместе с многошаговым режимом позже.