# План развития: easy-image-tools

> **Статус: active.** Фаза 1 выполнена — сайт живёт на типизированном реестре,
> production UI — корневые маршруты. Текущий фокус: SEO S1-free
> (`docs/plan-seo.md`) + открытые задачи (`docs/backlog.md`). Домен
> `easy-image-tools.com` зарегистрирован; остался cutover для индексации
> (S1-domain). Фазы 2–8 — будущие; 9–10 спланированы в `docs/plan-platform.md`;
> 11 — пайплайн.
>
> **Идентификаторы.** Ссылаться на фазу этого документа. Пространства
> идентификаторов задач: `FA-*` — правки полей и раскладки
> (`docs/plan-fields-audit-fixes.md`); `S*` — SEO/GEO (`docs/plan-seo.md`); `A*`
> — API, `P*` — PWA, `F*` — шрифты (`docs/plan-platform.md`); `R*` — бренд и
> домен (`docs/plan-seo.md`, §6). Буквы `Q*`/`C*` в архивных документах
> относятся к волнам редизайна и как идентификаторы задач не используются.

## 0. Решения

Продуктовые и стратегические — здесь; устройство кода (реестр, исполнитель,
слои) — `docs/architecture.md`, разделы 2–3.

- **Набор утилит для изображений, всё в браузере** (SvelteKit +
  `adapter-static`): файл картинки не покидает машину. Счётчик посещений GA4
  этому не противоречит — границы `docs/plan-seo.md`, §0.
- **Первый и главный приоритет — полностью рабочий сайт**: максимум простых
  инструментов, UX/UI, пайплайны (несколько инструментов подряд), описания
  инструментов.
- **Никакого wasm/Rust на этом этапе.** TS-реализация на canvas + `ImageData` —
  эталон алгоритмов, из которого позже генерируются эталонные файлы для проверки
  Rust-порта. Rust-ядро, WASM и CLI — отдельные фазы позже, когда сайт живёт.
- **Пайплайн = JSON-список шагов** `{id, params}` — формат шага совпадает с
  полем `Page.steps`. Формат зафиксирован этим решением и станет общим для
  браузера, wasm и CLI; реализуется в фазе 11, не в фазе 1.
- Валидация будущего Rust-порта — эталонные файлы, сгенерированные из
  TS-реализации. Сравнение: **бит-в-бит** для чистых пиксельных операций,
  **perceptual diff** для canvas-зависимых (правила сравнения — раздел 3).

## 1. Где что лежит

Актуальная карта модулей, поток данных и рецепт добавления инструмента —
`docs/architecture.md`. Список реализованных инструментов — `docs/tools-map.md`,
открытые продуктовые задачи — `docs/backlog.md`.

## 2. Фазы

### Фаза 1 — Полноценный TS-сайт (выполнена)

Поставлено: каркас SvelteKit + static, дизайн-система и общий лейаут; ядро над
`ImageData` (загрузка/декодирование, кодирование, операции по категориям) без
DOM-зависимостей; типизированный реестр с универсальным рендерером страницы и
формы; массовая реализация EASY-инструментов; i18n, темы, состояния
загрузки/ошибок. Checkpoint достигнут: загрузил PNG → применил инструмент →
скачал результат, без wasm.

**В фазе 1 пайплайна нет.** Workspace цепочек с сохранением в localStorage и
экспортом в JSON — фаза 11, не поставленная часть фазы 1. Страница инструмента
работает ровно с одной записью реестра; что именно зарезервировано под пайплайн
(компонент `StepCard`, ключи `chain.*`), перечислено в `docs/architecture.md`,
раздел 1 «Чего в коде нет».

Незакрытый долг по фазе — в `docs/backlog.md`; он не входит в фазы 2–8 и 11.

### Фаза 2 — Тестовые PNG и генератор эталонов

- Фикстурные входы: градиенты/паттерны/шум + пара «настоящих» PNG.
- Правило: сравниваем **распакованные пиксели**, не байты файла.
- **Checkpoint:** в `tests/reference/<op>/` лежат `input-*.png` +
  `expected-*.png`.

### Фаза 3 — Эталонные файлы и UI-регресс

> UI-регресс на Playwright уже существует и закрывает фазу 3 частично
> (`web/e2e/`, browser matrix). Недостающая часть фазы — именно эталоны.

- Скрипт генерации эталонов: грузит страницу, гоняет TS-реализацию, сохраняет
  `expected-*.png`.
- **Checkpoint:** регресс-тесты падают при изменении выхода эталона.

### Фаза 4 — Rust-ядро

- Порт 1:1 чистых операций (первым делом те, что покрыты эталонными файлами) с
  `PixelImage` ↔ TS `ImageData`.
- `clamp_to_u8` с семантикой `ToUint8Clamp` (round-half-to-even, ≥255 → 255) +
  юнит-тесты на краях.
- `cargo test` читает эталонные файлы напрямую, **без браузера**.
- **Checkpoint:** `cargo test` зелёный на всех эталонных файлах.

### Фаза 5 — WASM на сайте

- Спайк WASM + Vite (проверить интеграцию) → wasm-bindgen-биндинги.
- Свитч A/B: TS-реализация заменяется на wasm-вызов.
- Playwright-проверка: wasm-результат == эталон.
- **Checkpoint:** сайт работает через WASM; A/B TS vs WASM идентично.

### Фаза 6 — Rust-CLI

- CLI: обход папки, `--pipeline pipeline.json`, запись результатов.
- Воспроизведение эталонов из консоли.
- **Checkpoint:** CLI выдаёт те же пиксели, что сохранены в эталонных файлах.

### Фаза 7 — Сквозная проверка идентичности

- Матрица: **эталонные файлы (из TS) ↔ Rust-native ↔ Rust-wasm**, одна команда
  `harness compare`.
- **Checkpoint:** сходимость по всем покрытым операциям во всех трёх рантаймах.

### Фаза 8 — Масштабирование и продвинутое

- Порт оставшихся EASY → MEDIUM (свёртки, морфология, квантование; кодеки через
  крейт `image`).
- Canvas-зависимые операции (текст, градиенты, штампы, `ctx.filter`): остаются в
  TS с perceptual-классом либо реимплементация в Rust. Для текста выбран курс на
  реимплементацию в Rust (рендер без DOM + шрифты OFL с лицензионными
  паспортами) — `docs/plan-platform.md`, §4.
- batch-страница: дроп папки → wasm по всем файлам → zip. localStorage-пресеты
  (тот же JSON, что у CLI).
- HARD: compress/optimize через oxipng/zopfli (в Rust — нативно).

### Фаза 9 — API (монетизация) — см. `docs/plan-platform.md`

Серверная обёртка над тем же ядром (нативный Rust или wasm на edge — решает
спайк), ключи и free tier, платные лимиты, индексируемая документация `/api`.
Чек-лист и решения — `docs/plan-platform.md`, §1.

### Фаза 10 — PWA — см. `docs/plan-platform.md`

Manifest + service worker, оффлайн-режим («работает без сети — файлы не покидают
устройство»), установка как приложение. Wasm-фаз не требует, идёт после S1 из
`plan-seo.md`. Чек-лист — `docs/plan-platform.md`, §2.

### Фаза 11 — Пайплайн (цепочки шагов)

Продуктовая фича, **не зависит от wasm-фаз**: работает на существующем
исполнителе и реестре, поэтому может идти параллельно с SEO. Номер 11 выбран
чтобы не сдвигать уже используемые ссылки на фазы 2–10.

- **Формат шага** — `{id, params}`, список шагов применяется последовательно,
  результат предыдущего идёт в следующий. Формат зафиксирован в §0 как общий для
  браузера, wasm и CLI, поэтому версионируется с первого дня. Он уже совпадает с
  полем `Page.steps` (`{ id, params? }`), так что страница может быть готовой
  цепочкой без новой модели данных; исполняется пока первый шаг.
- **Первый шаг фазы:** модуль состояния цепочки + сохранение в localStorage +
  экспорт/импорт JSON (ошибки разбора уже описаны ключами
  `errors.badPipelineShape` / `errors.pipelineVersion` / `errors.noSteps`).
- **Затем:** редактирование шагов (drag-n-drop, удаление, добавление), переход
  «один инструмент → цепочка» без перезагрузки, сохранённые именованные цепочки,
  отображение маски результата.
- **Checkpoint:** собрал цепочку из N шагов → сохранил → вернулся позже → скачал
  результат последнего шага, всё в браузере.

Ограничения и открытые вопросы (1 → many не терминален, many → 1, частичные
ошибки, имена частей) — `docs/backlog.md`, раздел «Идеи». Пайплайн из архивного
UI-v1 удалён; что осталось в коде под эту фазу — `docs/architecture.md`,
раздел 1.

## 3. Правила сравнения (для фаз 4–7)

| Класс операции                                                                 | Критерий                                                                    |
| ------------------------------------------------------------------------------ | --------------------------------------------------------------------------- |
| Чистые пиксельные: цвет, альфа, порог, свёртки, морфология, квантование        | **бит-в-бит**                                                               |
| Canvas-растеризация: текст, градиенты, антиалиасинг, `drawImage`, `ctx.filter` | **perceptual diff** (допуск: % изменившихся пикселей / цветовое расстояние) |
| PNG-декод                                                                      | бит-в-бит (lossless)                                                        |
| JPEG-декод                                                                     | perceptual (разные декодеры дают лёгкий дрейф)                              |
| Кодирование                                                                    | сравниваем декодированные пиксели, не байты файла                           |
| compress/optimize                                                              | своя метрика: размер + визуальная дельта                                    |

## 4. Риски и контрмеры

- **Реестр разрастается, страницы дублируются** — один универсальный рендерер
  страниц/форм из записей реестра; инструмент = данные + `run`.
- **Семантика пайплайна** — зафиксирована: каждый шаг применяется к результату
  предыдущего; единый тип `PixelImage` на всём пути; схема параметров на шаге.
- **Canvas-операции не бит-в-бит** — класс perceptual закладывается на Фазе 2–3,
  а не в конце.
- **WASM + Vite** — спайк на Фазе 5 до массовой интеграции (риск отложен
  сознательно: сайт уже живёт на TS).
- **Расползание реестра при будущем Rust-порте** — схема параметров в JSON, её
  можно парсить и из Rust.
- **Разные декодеры PNG** — фикстурные PNG генерировать самим, чтобы не тащить
  чужие артефакты.

## 5. Команды верификации

Команды текущего этапа и матрица «изменение → проверки» —
`docs/quality-gates.md` (`pnpm verify` — быстрый gate). Команды фаз 2–8
(`cargo test`, `harness compare`) **в проекте не существуют** и появятся вместе
с соответствующими фазами: до этапа 2 проверять нечем, кроме `pnpm verify` и
e2e.