docs: update a lot of plans, readmes, descriptions

2026-11-13 17:08:20 +00:00 · 2026-09-27 09:10:26 +05:00
parent 9c6f223b13
commit 82207c82f2
47 changed files with 1029 additions and 4615 deletions
@@ -1,58 +1,53 @@
-# План разработки: easy-png-tools
+# План развития: easy-png-tools

-> **Статус:** Фаза 1 (полноценный TS-сайт) в основном выполнена — сайт живёт,
-> каталог переведён в типизированный `registry` (122 текущих инструмента), новый
-> дизайн стал единственным production UI на корневых маршрутах; UI-v1 удалён в
-> Q3. Tech debt не закрыт полностью; текущий baseline и состав quality-проверок
-> — в `docs/README.md` и `docs/quality-gates.md`. Следующий этап: SEO S1-free
-> (`plan-seo.md`) + баги и продуктовые задачи из `docs/backlog.md`. Домен нужен
-> для SEO (`plan-seo.md`, S1-domain). Фазы 2–8 — будущие. Фазы 9–10 спланированы
-> в `docs/plan-platform.md`.
+> **Статус (2026-09):** Фаза 1 (полноценный TS-сайт) в основном выполнена — сайт
+> живёт, каталог переведён в типизированный `registry`, новый дизайн стал
+> единственным production UI на корневых маршрутах, UI-v1 удалён. Tech debt не
+> закрыт полностью; состав quality-проверок — `docs/quality-gates.md`,
+> архитектура кода — `docs/architecture.md`, список инструментов —
+> `docs/tools-map.md`. Текущий фокус: SEO S1-free (`docs/plan-seo.md`) +
+> продуктовые задачи из `docs/backlog.md`. Домен нужен для SEO (`plan-seo.md`,
+> S1-domain). Фазы 2–8 — будущие; фазы 9–10 спланированы в
+> `docs/plan-platform.md`.
+>
+> **Нумерация фаз этого документа не совпадает с волнами разработки** (`Q*`/`C*`
+> в других документах) и не используется как идентификатор задач: ссылаться на
+> фазу, а не на номер волны.

 ## 0. Решения

- **Набор PNG-утилит, всё в браузере** (SvelteKit + `adapter-static`), данные не
-  покидают машину.
- **Первый и главный приоритет — полностью рабочий TS-сайт**: максимум простых
-  инструментов уровня EASY, UX/UI, пайплайны (несколько инструментов подряд),
-  описания инструментов. Сайтом можно пользоваться уже после этой фазы.
+- **Набор утилит для изображений, всё в браузере** (SvelteKit +
+  `adapter-static`), данные не покидают машину.
+- **Первый и главный приоритет — полностью рабочий сайт**: максимум простых
+  инструментов, UX/UI, пайплайны (несколько инструментов подряд), описания
+  инструментов.
 - **Никакого wasm/Rust на этом этапе.** TS-реализация на canvas + `ImageData` —
  эталон алгоритмов, из которого позже генерируются эталонные файлы для проверки
  Rust-порта. Rust-ядро, WASM и CLI — отдельные фазы позже, когда сайт живёт.
 - **Пайплайн = JSON-список шагов** `{tool, params}`. Формат закладывается сейчас
  и потом станет общим для браузера, wasm и CLI.
- **Реестр инструментов** (id, title, description, схема параметров, `run`) —
-  источник истины: из него генерируются страницы, формы, пайплайны. Позже —
-  общий формат для Rust-парсера.
+- **Реестр инструментов** (`web/src/lib/registry/`: id, title, description,
+  category, schema, `run`) — источник истины: из него генерируются страницы,
+  формы, пайплайны. Позже — общий формат для Rust-парсера.
 - Валидация будущего Rust-порта — эталонные файлы, сгенерированные из
  TS-реализации. Сравнение: **бит-в-бит** для чистых пиксельных операций,
  **perceptual diff** для canvas-зависимых.
 - **Единая точка исполнения инструментов.** Страницы вызывают операции только
-  через `web/src/lib/tools/executor.ts::executeStep` — нигде напрямую
-  `tool.run`. Контракт уже асинхронный (`Promise<PixelImage>`), поэтому:
+  через `web/src/lib/executor/` — нигде напрямую `tool.run`. Контракт уже
+  асинхронный, поэтому:
  - когда появятся тяжёлые MEDIUM-операции (свёртки, квантование), внутренности
-    `executeStep` переезжают в Web Worker — воркер импортирует тот же чистый
-    core как TS-фолбэк, алгоритмы не дублируются, вызывающий код не меняется;
+    исполнителя переезжают в Web Worker — воркер импортирует тот же чистый core
+    как TS-фолбэк, алгоритмы не дублируются, вызывающий код не меняется;
  - в WASM-фазе тот же воркер принимает wasm-модуль и диспетчеризует по `toolId`
    — свитч A/B из фазы 5 сводится к замене реализации внутри исполнителя;
  - до появления MEDIUM-операций воркер не вводится: EASY-операции быстры и не
    блокируют UI.

-## 1. Структура репозитория (этап TS)
+## 1. Где что лежит

-```txt
-easy-png-tools/
-  web/                        # SvelteKit (adapter-static)
-    src/lib/core/             # TS-ядро: Image (ImageData) + операции (без DOM)
-      color.ts  alpha.ts  geometry.ts  format.ts  text.ts  analyze.ts
-    src/lib/registry.ts       # реестр инструментов: id, title, description, params, run
-    src/lib/pipeline.ts       # пайплайн: шаги, применение, localStorage, экспорт/импорт JSON
-    src/lib/components/       # DropZone, Preview, ParamForm (из схемы), Download, PipelineSteps
-    src/routes/               # маршруты-утилиты (генерируются из реестра) + /workspace
-  docs/
-  core/                       # (позже) Rust-крейт
-  tests/                      # (позже) эталонные файлы и harness
-```
+Актуальная карта модулей, поток данных и рецепт добавления инструмента —
+`docs/architecture.md`. Список реализованных инструментов — `docs/tools-map.md`,
+открытые продуктовые задачи — `docs/backlog.md`.

 ## 2. Фазы

@@ -64,22 +59,21 @@ clamp-семантики (в TS это делает `Uint8ClampedArray` сам).
 1.1 **Каркас и UX/UI.** SvelteKit + static adapter, дизайн-система (цвета,
 типографика, компоненты), общий лейаут, шапка с навигацией по категориям.

-1.2 **Ядро.** Тип `Image` (обёртка над `ImageData`), загрузка/декодирование
-файла, кодирование и скачивание, библиотека операций
-(color/alpha/geometry/format/text/analyze). Всё без DOM-зависимостей внутри
+1.2 **Ядро.** Операции над `ImageData` (загрузка/декодирование файла,
+кодирование и скачивание, библиотека операций
+color/alpha/geometry/format/text/analyze). Всё без DOM-зависимостей внутри
 `core`.

 1.3 **Реестр инструментов.** Одна запись =
-`{ id, title, description, category, params: ParamDef[], run }`. Универсальный
-рендерер: страница инструмента и форма параметров строятся из записи реестра
+`{ id, title, description, category, schema, run }`. Универсальный рендерер:
+страница инструмента и форма параметров строятся из записи реестра
 автоматически; маршруты-утилиты генерируются из реестра на билде. Новый
-инструмент = новая запись + функция `run`.
+инструмент = новая запись + функция `run` (рецепт — `docs/architecture.md` §8).

-1.4 **Пайплайн-workspace** (`/workspace`): загрузил изображение → список шагов
-(инструмент + его параметры) → последовательное применение с превью каждого шага
-→ скачивание финального результата. Добавление/удаление/перестановка шагов.
-Сохранение пайплайнов в localStorage, экспорт/импорт JSON. Общие компоненты:
-DropZone, Preview, ParamForm, Download, PipelineSteps.
+1.4 **Пайплайн-workspace**: загрузил изображение → список шагов (инструмент +
+его параметры) → последовательное применение с превью каждого шага → скачивание
+финального результата. Добавление/удаление шагов. Сохранение пайплайнов в
+localStorage, экспорт/импорт JSON.

 1.5 **Массовая реализация EASY-инструментов** по категориям:

@@ -105,17 +99,19 @@ wasm.
 - **Checkpoint:** в `tests/reference/<op>/` лежат `input-*.png` +
  `expected-*.png`.

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

- `tools/gen-references.ts`: грузит страницу, гоняет TS-эталон, сохраняет
+> UI-регресс на Playwright уже существует и закрывает фазу 3 частично
+> (`web/e2e/`, browser matrix). Недостающая часть фазы — именно эталоны.
+
+- Скрипт генерации эталонов: грузит страницу, гоняет TS-реализацию, сохраняет
  `expected-*.png`.
- Регресс: изменение TS-ядра ловится тестами.
 - **Checkpoint:** регресс-тесты падают при изменении выхода эталона.

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

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

 - **Реестр разрастается, страницы дублируются** — один универсальный рендерер
  страниц/форм из записей реестра; инструмент = данные + `run`.
- **Семантика пайплайна** — зафиксировать: каждый шаг применяется к результату
-  предыдущего; единый тип `Image` на всём пути; схема параметров на шаге.
+- **Семантика пайплайна** — зафиксирована: каждый шаг применяется к результату
+  предыдущего; единый тип `PixelImage` на всём пути; схема параметров на шаге.
 - **Canvas-операции не бит-в-бит** — класс perceptual закладывается на Фазе 2–3,
  а не в конце.
 - **WASM + Vite** — спайк на Фазе 5 до массовой интеграции (риск отложен
@@ -192,10 +188,7 @@ Manifest + service worker, оффлайн-режим («работает без

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

-```bash
-pnpm dev                    # разработка (Фаза 1+, обёртка `pnpm --dir web dev`)
-pnpm build                  # статический экспорт (обёртка `pnpm --dir web build`)
-pnpm --dir web exec playwright test # эталоны + UI-регресс (Фаза 3+)
-cargo test                  # Rust-ядро против эталонных файлов (Фаза 4+)
-harness compare tests/reference # сквозная сверка native + wasm (Фаза 7)
-```
+Текущие команды и матрица «изменение → проверки» — `docs/quality-gates.md`
+(`pnpm verify` — быстрый gate текущего этапа). Для будущих фаз добавляются
+`cargo test` (Rust-ядро против эталонных файлов, фаза 4+) и
+`harness compare tests/reference` (сквозная сверка native + wasm, фаза 7).