# План: составные типы параметров и полная типизация pipeline

> **СТАТУС: ЗАКРЫТ (2026-09-07).** Типизация pipeline, составные типы
> (dimension/color-pair/offset/position9/font-style/plate/gradient),
> `schema.layout`, изоляция веток и вся миграция инструментов (121/125,
> остальные 4 — отложены решениями) выполнены. Ключевые архитектурные решения
> (параллельная сборка, правило копий, изоляция old↔preview) закреплены в
> `AGENTS.md`. **Незакрытое из этого плана:** шаг 37 — физический переезд старых
> файлов в папки `old/` (перенесён в `backlog.md`), и удаление старого кода — по
> `plan-redesign.md` (C17–C21). Отложенные инструменты — `watermark-image-png`
> (overlay), `png-info`, `reduce-to-size` — в `backlog.md`. Ниже — полное
> состояние на момент закрытия.

> Статус: **в реализации.** Фаза 0 (фундамент) ✔, Фаза 1 (рабочий инструмент в
> preview) ✔, Фаза 2 (простые инструменты без составных типов) — переведены все
> одиночные инструменты (18 шт). Фаза 3 — **составной тип `dimension` полностью
> переведён** (12 инструментов: create-empty, single-color, random-noise,
> linear-gradient, color-spectrum, random-colors, draw-grid, placeholder,
> fit-on-background, change-canvas-size, resize, crop); **составной тип
> `color-pair` полностью переведён** (4 инструмента: blend-two, step-colors,
> linear-gradient, two-colors); **составной тип `offset` полностью переведён**
> (4 инструмента: circle-mask, square-mask, star-mask, wavy-mask); **составной
> тип `position9` — переведены add-text-png и date-stamp-png** (водяной
> знак-картинка — отдельный шаг: требует overlay-механику в новом превью);
> **составной тип `font-style` полностью переведён** (text-to-png, add-text,
> date-stamp); **составной тип `plate` полностью переведён** (add-text,
> date-stamp); **составной тип `gradient` полностью переведён**
> (linear-gradient): вместо горизонтального/ вертикального select — **угол
> 0..360°** (новый виджет `AngleControl`: slider + кнопки-пресеты
> 0°/90°/180°/270°, переиспользуемый компонент); preview научен применять
> **генераторы** (`executeGenerate`, кнопка Generate) и рендерить все kinds
> схемы (slider/number/color/select/checkbox/dimension/
> color-pair/offset/position9/font-style/plate/gradient). **Пер-инструмент
> раскладка `schema.layout` реализована** (шаг 32): тип `ToolSchemaLayout`
> {groups: [{title?, cols?, fields}]}, рендер групп в `SchemaFields.svelte`
> (заголовок группы + сетка колонок, неупомянутые поля — в общей группе), пилот
> — `add-text` (группы Text/Placement/Plate). **UI-макеты расставлены по
> переведённым инструментам** (шаг 33): geometry (fit-on-background,
> change-canvas-size, resize, crop), маски alpha (Shape/Position), generate
> (create-empty, linear-gradient, color-spectrum, random-colors, draw-grid,
> step-colors, placeholder, text-to-png), text (add-text, date-stamp), filters
> (randomize-pixels, add-noise) — везде, где канвас отделён от параметров
> эффекта либо фигура от позиции. Следующее закрыто в
> `archive/plan-migrate-remaining.md` (2026-09-07): перевод оставшихся
> инструментов выполнен (всего 121/125 в preview; 4 хвоста —
> `watermark-image-png`, `png-info`, `reduce-to-size-png`, `compress-png` —
> отложены решениями в `backlog.md`). Незакрытые продолжения: переезд старых
> компонентов в папки `old/` (шаг 37 ниже), закрытие долгов и сбор фидбека — см.
> также `plan-design-fix.md`.
>
> Ключевые файлы нового registry: `web/src/lib/registry-new/{types,index,*}.ts`
> (по файлу на категорию: geometry/alpha/convert/analyze/filters/color/generate)
>
> - `web/src/lib/preview/categories.ts`, `web/src/lib/registry-schema.ts` (kind
>   `dimension`), `kit/fields/DimensionField.svelte`,
>   `preview/executor/index.ts` (`executeGenerate`), `SchemaFields.svelte`
>   (полный рендер kinds). Старый `web/src/lib/registry.ts` разбит по категориям
>   в `web/src/lib/registry/` (см. `registry.ts` — тонкий баррель).

## Ключевая стратегия: параллельная сборка, старый UI не трогаем

Старый UI (группа `(old)/`, `ParamForm.svelte` + старый pipeline) **продолжает
работать как сейчас, без рефакторинга**. Новый `ToolSchema<P>` строится рядом и
служит источником для **нового UI**. Инструменты переписываются под новый
registry по мере нужды — для нового UI.

Это та же логика, что в `plan-redesign.md` применена к дизайну: параллельная
сборка, изоляция от старого, затем новый становится основным и старый удаляется
вместе со старым дизайном.

**Правило копий (важно!):** если для нового UI/registry нужно внести изменения в
файл, который **прямо или косвенно** уже используется `(old)` веткой, — этот
файл **НЕ трогаем**. Вместо этого делаем **копию** в новом месте (например, в
`lib/preview/`) и правим копию. Это приводит к дублированию, но **гарантированно
не задевает старую ветку сайта**. Пример: категории — новый
`lib/preview/categories.ts` (object as const) копирует и заменяет собой
`../categories` для нового кода, старый `categories.ts` обслуживает `(old)` и
остаётся без изменений. После перехода (Фаза 5) копия становится основной, а
исходник продолжает обслуживать `(old)` UI (он не удаляется — см. шаг 35).

**Разделение схем: две независимые схемы.**

| Схема                 | Источник                                          | Использование                                                    |
| --------------------- | ------------------------------------------------- | ---------------------------------------------------------------- |
| Старый `ParamDef[]`   | В `ToolEntry.params` — **остаётся без изменений** | Старый UI, старый pipeline (`ParamForm.svelte`, executor, chain) |
| Новый `ToolSchema<P>` | Новое поле `ToolEntry.schema` — добавляется рядом | Новый UI (kit/`ParamControl`, новый pipeline)                    |

- Старая и новая схемы **не выводятся друг из друга** — это два независимых
  описания инструмента.
- Пока новый UI не готов — `schema` просто отсутствует у большинства
  инструментов, старый UI ничего не замечает.
- Удаление старого UI (после перехода) попутно удаляет и старый `ParamDef[]`

### Разделение registry по UI (новое решение, Фаза 2+)

Помимо двух схем, registry тоже разделён по UI (по факту миграции):

- **Старый registry** (`web/src/lib/registry.ts` + `registry/` +
  `registry-helpers.ts`) — работает на старом UI, использует `ParamDef[]`. **Не
  трогаем**; остаётся обслуживать `(old)/` маршруты (см. шаг 35).
- **Новый registry** (`web/src/lib/registry-new/`) — строится **с нуля «как
  надо»**: `ToolEntry<P>` с обязательным `schema`, типизированный `run`, **без**
  `ParamDef[]` и **без** связи со старым. Импортирует core-функции
  (`expandCanvas`, `strokeImage`, …) напрямую. Наполняется **по-инструментно**
  по мере миграции (не разовым переводом всех 130). Preview показывает только
  переведённые инструменты.

Preview (`catalog.ts`, маршруты `preview/**`, `SchemaToolView`, `SchemaFields`)
импортируют из `$lib/registry-new`. После удаления старого UI `registry-new/`
переименуется в `registry`.

**Executor/worker для нового UI (осознанное дублирование):** общий
`executor.worker.ts` резолвит инструменты по `id` в **старом** registry — для
новых инструментов их там нет. Поэтому `executor.ts` + `executor.worker.ts`
**скопированы** в `web/src/lib/preview/` и переписаны под `registry-new` +
`sanitizeSchemaParams`. Старый executor/worker под старый UI остаются
нетронутыми; `SchemaToolView` использует `$lib/preview/executor`. Это
дублирование необходимо до ухода старого UI (после — preview-executor заменяет
общий).

## Проблема (текущая)

- `ParamDef` — плоский union из 6 примитивов
  (`number | slider | select | checkbox | color | text`). Параметры инструмента
  — отдельные записи в плоском массиве.
- `run()`/`generate()` получают `Record<string, unknown>`; значения достаются
  через `num(p, "fromColor")` — runtime string lookup **без type safety**, легко
  напутать id.
- Поля инструмента **слабо связаны** (например «ширина» и «цвет» рамки — два
  независимых поля без общего контракта) → общий генерализованный рендер, нет
  возможности сделать идеальный пер-инструмент UI.
- Preview-система (`tool-views.ts`) **дублирует** registry (FieldDef vs
  ParamDef) — одни и те же инструменты описаны дважды.

## Решения (принятые в обсуждении)

1. **Полная типизация.** `interface Params` (runtime-тип) объявляется явно в
   каждом инструменте. `run`/`generate` типизируются прямо на него, а не на
   `Record<string, unknown>`.
2. **Отдельная типизированная схема для UI/дефолтов/валидации.** Два понятия на
   инструмент: runtime-тип + схема. Схема проверяется компилятором на
   соответствие `Params` (чтобы не рассинхронизировались).
3. **Общий рендер,** но с пер-инструмент layout: общие компоненты рисуют поля по
   схеме; схема инструмента задаёт layout и группировку. Без отдельного
   Svelte-компонента на каждый инструмент.
4. **Составные типы** (`gradient`, `color-pair`, `dimension`, `offset`,
   `position9`, `font-style`, `plate`) остаются в плане — это способ выразить в
   схеме связанную группу полей и переиспользовать её на нескольких инструментах
   и в UI.
5. Рано или поздно `tool-views.ts` поглощается registry (preview/lede/layout
   переезжают в meta инструмента) — но это отдельный шаг, см. ниже.
6. **Старый UI не рефакторим.** Две независимые схемы: старый `ParamDef[]`
   остаётся источником для старого UI без изменений; новый `ToolSchema<P>`
   строится рядом для нового UI (см. «Ключевая стратегия» выше).

## Целевая архитектура (на примере «добавить рамку»)

Цель: «добавить рамку: ширина и цвет» — **один интерфейс**, а не два слабо
связанных поля.

```ts
// 1. Runtime-тип — что получает run/generate
interface AddBorderParams {
  thickness: number;  // рамка: ширина
  color: string;      // рамка: цвет
}

// 2. Типизированная UI-схема, проверяемая компилятором против Params
//    Ключи схемы обязаны совпадать с полями Params; default совместим с типом.
const addBorderSchema = toolSchema<AddBorderParams>({
  thickness: field.slider({ min: 1, max: 500, default: 5 }),
  color:     field.color({ default: "#000000" }),
  layout: { group: "border", cols: 2 },   // пер-инструмент раскладка
});

// 3. Инструмент в registry
const addBorder: ToolEntry<AddBorderParams> = {
  id: "add-border-png",
  title: "Add border to PNG",
  category: "geometry",
  schema: addBorderSchema,
  run: (img, p) => expandCanvas(img, 4x..., p.color),  // p.thickness — type safe
};
```

### Что даёт

- `p.thickness`, `p.color` — IDE autocomplete + compile-time ошибка при ошибке.
- `run()` нельзя передать лишний/чужой ключ.
- Схема — единый источник для дефолтов, валидации и рендера.
- Схема одного инструмента может задавать layout, которого нет в общем рендере.

## Типовая система (набросок)

```ts
// ─── Поле схемы ───
interface NumberField { kind: "number"; default: number; min?: number; max?: number; step?: number }
interface SliderField { kind: "slider"; default: number; min: number; max: number; step?: number }
interface ColorField  { kind: "color";  default: string }
interface SelectField { kind: "select"; default: string; options: { value: string; label: string }[] }
interface TextField   { kind: "text";   default: string; placeholder?: string }
interface CheckboxField { kind: "checkbox"; default: boolean }

type FieldDef =
  | NumberField | SliderField | ColorField | SelectField | TextField | CheckboxField;

// ─── «поле» описывает тип значения + схему вместе, чтобы не рассинхронизировать ───
interface Field<T> {
  schema: FieldDef;
  // T — ожидаемый runtime-тип этого поля (number|string|boolean)
}

// ─── Builder: field.slider({...}) возвращает Field<number> с типизированной схемой ───
const field = {
  slider: (s: SliderField): Field<number> => ({ schema: s }),
  number: (s: NumberField): Field<number> => ({ schema: s }),
  color:  (s: ColorField):  Field<string> => ({ schema: s }),
  select: <V extends string>(s: SelectField & { options: {value: V}[] }): Field<V> => ({ schema: s }),
  text:   (s: TextField):   Field<string> => ({ schema: s }),
  checkbox: (s: CheckboxField): Field<boolean> => ({ schema: s }),
};

// ─── toolSchema<P>: проверяет, что ключи схемы === полям P и типы сходятся ───
type FieldsOf<T> = { [K in keyof T]: Field<T[K]> } & {
  layout?: { group?: string; cols?: number };
};
function toolSchema<P>(fields: FieldsOf<P>): ToolSchema<P> { ... }
// TS выдаст ошибку, если schema содержит ключ, отсутствующий в Params, или
// если type поля не совпадает с типом Params[K].
```

Ключевая идея связки: **builder `field.x<T>()` связывает runtime-тип поля с его
схемой на этапе компиляции**, а `toolSchema<P>` заставляет ключи схемы совпадать
с ключами `P`. Это и есть защита от рассинхрона.

## Составные типы (для переиспользования и группировки)

| Тип          | Под-поля                   | Инструментов |
| ------------ | -------------------------- | ------------ |
| `dimension`  | width + height             | 12           |
| `color-pair` | from + to                  | 4            |
| `offset`     | x + y                      | 4            |
| `gradient`   | from + to + dir (+ type?)  | 1            |
| `position9`  | position (3×3 grid)        | 3            |
| `font-style` | font + size + bold + color | 3-4          |
| `plate`      | enabled + color + opacity  | 2-3          |

Составной тип = группы полей, которые в интерфейсе `Params` могут
разворачиваться во вложенный объект или плоские ключи — решается на этапе
реализации. Пример для `gradient`:

```ts
interface GradientParams {
  from: string;
  to: string;
  dir: string;
}
// схема: field.color(from), field.color(to), field.select(dir)
// плюс annotation в схеме: { group: "gradient" } → UI рисует как цветовой переход
```

## Инвентарь: какие инструменты мигрировать

### dimension (12)

resize-png*, crop-png*, fit-on-background-png, create-empty-png,
single-color-png, random-noise-png, linear-gradient-png, color-spectrum-png,
random-colors-png, draw-grid-png, placeholder-png, change-canvas-size-png

(\* у resize/crop — не просто dimension, есть специфика: keepAspect, x/y и т.д.)

### color-pair (4)

blend-two-png, step-colors-png, linear-gradient-png, two-colors-png

### offset (4)

circle-mask-png, square-mask-png, star-mask-png, wavy-mask-png

### position9 (3)

add-text-png, date-stamp-png, watermark-image-png

### font-style (3-4)

text-to-png, add-text-png, date-stamp-png

### plate (2-3)

add-text-png, date-stamp-png

## Пошаговый план перевода инструментов

> Каждый шаг — **атомарное, маленькое изменение** (в идеале 1 инструмент = 1
> diff, укладывается в правило «коммиты < ~500 строк»). После каждого шага —
> ревью; параллельно можно делать UI нового инструмента.
>
> **Принцип малых шагов:** перевод инструмента не меняет поведение старой схемы
> (`params` остаётся), не ломает старый UI. Инструмент получает ДОПОЛНИТЕЛЬНО
> новое поле `schema` + `interface Params`, старое `run`/`params` не трогаем.
> Это гарантирует, что старый UI продолжает работать без регресса.
>
> **Новый подход (решение пользователя):** сначала делаем **один полноценный
> рабочий инструмент в preview** — не эталон «на бумаге», а реально юзабельный,
> чтобы руками оценить, насколько это рабочее решение и какие возникнут
> сложности. Оцениваем, при необходимости правим инфраструктуру, и только потом
> переводим остальные инструменты тем же проверенным паттерном.

### Фаза 0 — фундамент ✔ (сделано)

Typed field builders + `Field<T>` + `toolSchema<P>()` + `ToolSchema<P>` — в
`web/src/lib/registry-schema.ts`. `ToolEntry<P>` generic + опциональное поле
`schema`. Новые `defaultSchemaParams`/`sanitizeSchemaParams`. Старый
`ParamDef[]`/pipeline не тронуты. Проверено: compile-time-защита
(лишний/неверный/отсутствующий ключ ловит TS), тесты, svelte-check без новых
ошибок.

### Фаза 1 — ОДИН полноценный рабочий инструмент в preview (срез) ✔ (сделано)

Инструмент переехал в `registry-new` и рендерится через `SchemaToolView`
(`SchemaFields`/`SchemaPreview`); применение реально работает end-to-end до
картинки. Паттерн подтверждён. `find-contour-png` — следующий в этой фазе-2.

5. **Инструмент «добавить рамку» (`add-border-png`)** — сделать полностью
   рабочим в preview:
   - `interface AddBorderParams { thickness: number; color: string }`
   - `addBorderSchema = toolSchema<AddBorderParams>(...)` + `schema: ...` в
     entry (старый `params`/`run` остаются — старый UI не регрессит).
   - **Новый рендер в preview** (`kit/ToolView` → `ParamControl` или новый
     компонент схемы): читает `ToolSchema<P>`, рисует поля рамки, применение
     реально работает (end-to-end до картинки).
   - Дефолты/валидация/значения — из схемы (`defaultSchemaParams`,
     `sanitizeSchemaParams`).
   - **Ревью-оценка:** удобно ли это, что сломалось/усложнилось, что поправить в
     инфраструктуре до масштабирования. Принимается макет/решение.

Результат: один реально рабочий инструмент на новой системе = доказываем
паттерн, прежде чем переводить остальных.

### Фаза 2 — простые инструменты без составных типов (1 инструмент = 1 шаг)

Одиночные/небольшие инструменты, где `interface Params` + `schema` не требуют
составных типов. Каждый — отдельный маленький diff (~15-30 строк), тем самым
проверенным в Фазе 1 паттерном. **Переезжают в `registry-new`.**

Переведено: `add-border-png` (Фаза 1), `add-stroke-png`, `find-contour-png`,
плюс весь блок простых инструментов ниже (пункты 8-22). Следующее — Фаза 3.

6. ~~add-stroke-png (color + slider)~~ → переведён в `registry-new` ✔
7. ~~find-contour-png (color + slider)~~ → переведён в `registry-new` ✔
8. ~~convert-png-to-jpg (color + slider)~~ → переведён в `registry-new` ✔
9. ~~convert-png-to-webp (slider)~~ → переведён в `registry-new` ✔
10. ~~remove-color-from-png (color + slider)~~ → переведён в `registry-new` ✔
11. ~~extract-color-from-png (color + slider)~~ → переведён в `registry-new` ✔
12. ~~add-noise-png (slider + select + number)~~ → переведён в `registry-new` ✔
13. ~~randomize-pixels-png (slider + number)~~ → переведён в `registry-new` ✔
14. ~~pixelate-png (slider)~~ → переведён в `registry-new` ✔
15. ~~vignette-png (slider)~~ → переведён в `registry-new` ✔
16. ~~gamma-png (slider)~~ → переведён в `registry-new` ✔
17. ~~temperature-png (slider)~~ → переведён в `registry-new` ✔
18. ~~tint-png (color + slider)~~ → переведён в `registry-new` ✔
19. ~~quantize-png (slider)~~ → переведён в `registry-new` ✔
20. ~~custom-palette-png (text)~~ → переведён в `registry-new` ✔
21. ~~dithering-png (slider + select)~~ → переведён в `registry-new` ✔
22. ~~jpeg-artifacts-png (slider)~~ → переведён в `registry-new` ✔

> **Замечание (конвертеры):** старые `convert-png-to-jpg`/`convert-png-to-webp`
> несли `output`-метаданные (`mime`/`ext`/`qualityParamId`) для выбора формата
> вывода. В новом `ToolEntry<P>` поля `output` пока нет, поэтому при переводе
> эти метаданные не перенесены — preview пока отдаёт результат как PNG. Механика
> выбора формата/качества в новом UI — отдельный шаг (не блокирует Фазу 2).

### Фаза 3 — инструменты с составными типами (по типу, затем по инструментам)

24. `dimension` — **переведены все 12 инструментов** ✔ (`create-empty-png`,
    `single-color-png`, `random-noise-png`, `linear-gradient-png`,
    `color-spectrum-png`, `random-colors-png`, `draw-grid-png`,
    `placeholder-png` — генераторы в `registry-new/generate.ts`;
    `fit-on-background-png`, `change-canvas-size-png`, `resize-png`, `crop-png`
    — в `registry-new/geometry.ts`). Составной тип во всех видах: вложенный
    объект `size: { width, height }` в Params + `field.dimension`, виджет
    `kit/fields/DimensionField.svelte`. Preview: генераторы применяются через
    `executeGenerate` (кнопка Generate), `SchemaFields` рендерит все kinds схемы
    (slider/number/color/select/ checkbox/dimension). Тесты: 592 passed.
25. `color-pair` — **все 4 инструмента переведены** ✔ (`blend-two-png`,
    `step-colors-png`, `linear-gradient-png` — генераторы в
    `registry-new/generate.ts`, `two-colors-png` — run в
    `registry-new/color.ts`). Составной тип во всех видах: вложенный объект
    `pair: { from, to }` + `field.colorPair`, виджет
    `kit/fields/schema/ColorPairControl.svelte`, kind `color-pair` в схеме
    (default/sanitize). Тесты: +4 (596 passed).
26. `offset` — **все 4 инструмента переведены** ✔ (`circle-mask-png`,
    `square-mask-png`, `star-mask-png`, `wavy-mask-png` — run в
    `registry-new/alpha.ts`). Составной тип во всех видах: вложенный объект
    `offset: { x, y }` + `field.offset`, виджет
    `kit/fields/schema/OffsetControl.svelte`, kind `offset` в схеме
    (default/sanitize). Тесты: +4 (600 passed).
27. `position9` — **переведены `add-text-png` и `date-stamp-png`** ✔ (run в
    `registry-new/text.ts`, оба `domOnly`). Составной тип во всех видах:
    значение — строка `Position9`, kind `position9` в схеме (default/sanitize по
    `POSITION9_VALUES`), виджет 3×3 `kit/fields/schema/PositionControl.svelte`.
    В `ToolEntry` добавлен флаг `domOnly` (превью-executor держит такие
    инструменты вне worker). `watermark-image-png` — отдельный под-шаг: ему
    нужен overlay-source (`getOverlay`/store), которого в новом превью пока нет.
    Тесты: +2 (602 passed). `font-style` и `plate` на этих инструментах сводятся
    в шаги 28-29.
28. `font-style` — **все 3 инструмента переведены** ✔ (`text-to-png` — генератор
    в `registry-new/generate.ts` (domOnly), `add-text-png`/ `date-stamp-png` —
    рефакторинг в `registry-new/text.ts`). Составной тип во всех видах:
    вложенный объект `style: { font, size, bold, color }` + `field.fontStyle`,
    виджет `kit/fields/schema/FontStyleControl.svelte`, kind `font-style` в
    схеме (default/sanitize, clamp размера к min/max). Тесты: +1 (603 passed).
29. `plate` — **все 2 инструмента переведены** ✔ (`add-text-png`,
    `date-stamp-png` — рефакторинг в `registry-new/text.ts`). Составной тип во
    всех видах: вложенный объект `plate: { enabled, color, opacity }` +
    `field.plate`, виджет `kit/fields/schema/PlateControl.svelte` (чекбокс +
    цвет + слайдер непрозрачности, деактивируется при выключенной плашке), kind
    `plate` в схеме (default/sanitize, clamp opacity к 0..100). Покрытие тестов
    расширено (дефолты/sanitize plate в существующих тестах).
30. `gradient` — **переведён** ✔ (linear-gradient-png). Направление градиента —
    не горизонталь/вертикаль, а **произвольный угол**: новый переиспользуемый
    виджет `kit/fields/schema/AngleControl.svelte` (слайдер 0..360° + кнопки
    стандартных углов 0°/90°/180°/270° с активным состоянием). Составной тип
    `gradient: { from, to, angle }` во всех видах (`field.gradient`, kind
    `gradient` в схеме — default/sanitize, clamp угла к 0..360, валидация
    цветов; виджет `kit/fields/schema/GradientControl.svelte` — пара цветов +
    AngleControl). Рендер по углу — локальный `angleGradient` в
    `registry-new/generate.ts` (core-`gradientImage` не трогали: он умеет только
    horizontal/vertical и используется старым UI). Семантика: 0° слева направо,
    90° сверху вниз, рост угла по часовой (ось Y вниз); нормализация по полному
    диапазону проекции на ось (180°/270° разворачивают градиент). Тесты:
    дефолты, направление по углу (0°/90°/180°), sanitize/кламп.

### Фаза 4 — масштаб UI на остальные инструменты

31. По мере перевода инструментов в Фазе 2-3 — рендер схемы (из Фазы 1)
    покрывает их автоматически; составные виджеты (dimension, color-pair,
    offset, position9, font-style, plate, gradient) — по одному, каждый с ревью.
32. Пер-инструмент layout (`schema.layout`) — **реализован** ✔.
    `ToolSchemaLayout.groups: { title?, cols?, fields[] }` в registry-schema;
    `SchemaFields.svelte` рендерит группы (подпись + сетка `1..n` колонок,
    неупомянутые поля — в общей группе в конце, без заголовка). Пилот —
    `add-text-png` (Text: text+style; Placement: position+margin; Plate). Тесты:
    schema-layout в registry-schema.test.ts; полные запуски чисты.
33. Для каждого переведённого инструмента — UI-макет **расставлен** ✔.
    Layout-группы заданы там, где группировка содержательна (канвас отдельно от
    параметров эффекта, фигура отдельно от позиции; составные виджеты — внутри
    групп целиком):
    - geometry: fit-on-background (Canvas/Background), change-canvas-size
      (Canvas/Anchor), resize (Canvas/Scaling), crop (Offset/Crop area);
    - alpha-маски: circle/square/star/wavy (Shape — с 2 колонками где плотно,
      Position — offset);
    - generate: create-empty (Canvas/Fill), linear-gradient (Canvas/Colors),
      color-spectrum (Canvas/Spectrum), random-colors (Canvas/Random), draw-grid
      (Canvas/Grid), step-colors (Colors/Output), placeholder
      (Canvas/Colors/Text), text-to-png (Text/Background/Padding);
    - text: add-text, date-stamp (Text/Placement/Plate);
    - filters: randomize-pixels (Blocks), add-noise (Noise/Seed). Инструменты с
      1–3 простыми полями остались без layout (одна общая группа).

### Фаза 5 — изоляция старого UI

34. Поглощение `tool-views.ts` (preview/lede/layout → meta инструмента) ✔.
    Отдельного `tool-views.ts` в репо нет: preview сразу строился на
    `registry-new`. Meta инструмента живёт в `ToolEntry` (`title`,
    `description`, `category`, `run`/`generate`), layout — в `schema.layout`
    (шаг 32), рендер — `SchemaToolView`/`SchemaFields`/`SchemaPreview`.
    Дублирующей системы нет.
35. Старый UI **не удаляется**, а выносится в `(old)/`-маршруты и остаётся там
    временно (посмотреть, как работает, сравнить с новым; старые тесты
    продолжают проходить):
    - маршруты `(old)/{+page,demo,list-tools,tools/[id]}` — старый дизайн, тянет
      `old.css` (не `design2.css`), старый header/footer;
    - старый `registry.ts`/`registry/` + `ParamDef[]` обслуживают только
      `(old)/`-инструменты — не удаляются, не рефакторятся;
    - удаление происходит позже, отдельным решением (когда новый UI покроет все
      инструменты и ревью завершено).
36. **Линтер-изоляция веток** (гарантия, что old и preview не смешиваются) ✔.
    Кастомный ESLint-плагин `web/eslint-plugins/isolation/no-mixed-imports`
    Резолвит каждый импорт (и `$lib/...`, и относительные `./`/`../`) до
    реального файла, классифицирует источник и цель по фактическому пути и
    ругается на old→new и new→old. Конфигурация (`old`/`new` glob-паттерны,
    `root`, `alias`) вынесена в настройки правила — единая точка правды:
    - старое: `routes/(old)/**`, `lib/registry.ts`, `lib/registry/**`,
      `lib/registry-helpers.ts`, `lib/categories.ts`, `lib/tools/**`,
      `lib/components/**` (кроме `kit/`);
    - новое: `routes/preview/**`, `lib/registry-new/**`, `lib/preview/**`,
      `lib/registry-schema.ts`, `lib/registry-schema.test.ts`,
      `lib/components/kit/**`;
    - общее (разрешено обоим): всё прочее — `core/`, `i18n/`, `theme`,
      `assets/`, корневой `lib` (`index.ts`, тесты). Достигнутая полная изоляция
      (одиночные пересечения устранены):
    - старые пилоты `registry/geometry.ts` (`add-border`) и `registry/alpha.ts`
      (`add-stroke`) получали `schema` из нового `registry-schema` — убрано; оба
      инструмента работают в старом UI через `params: ParamDef[]`, в preview —
      через свои schema-версии в `registry-new/`;
    - `registry.ts` больше не импортирует `ToolSchema` из `registry-schema`;
    - preview `list-tools` тянул `TOOL_ICONS` из старого `lib/tools/tool-icons`
      → создана копия `lib/preview/tool-icons.ts` (правило копий).
37. Перенос всех старых компонентов/библиотек в папки `old/` (**следующее**):
    переезд не трогает плагин — достаточно дописать один glob-паттерн в
    настройку правила (например `lib/old/**`, `lib/components/old/**`), а сама
    проверка работает по фактическим путям автоматически.

### Как ревьюить каждый шаг

- Diff **только один инструмент** (или фундамент без инструментов).
- Старый `params`/`run`/`defaultParams`/`sanitizeParams` — **не изменены**
  (кроме добаление `schema`, если это пилот).
- Старый UI и старые тесты продолжают работать — запустить `pnpm --dir web test`
  и `pnpm --dir web exec svelte-check`.
- Порядок полей в `interface Params` и в `schema` совпадает; дефолты в сeme
  равны старым `default` из `params`.
- Пилот из Фазы 1 проверяется **руками в preview**: применяется рамка,
  дефолты/валидация/смена значений работают end-to-end.

## Поток данных (runtime)

### Старый pipeline (не трогаем)

Всё как сейчас: старое `defaultParams`/`sanitizeParams`/executor/chain работают
на `ParamDef[]` и `Record<string, unknown>`. Никаких изменений.

### Новый pipeline (строим рядом)

- **Хранилище значений** — типизировано на схему; у нового UI значения полей
  собираются в `Params` по `ToolSchema<P>`.
- **defaultParams / sanitizeParams (новые)** — выводятся из `ToolSchema<P>`,
  дефолты лежат в схеме. Старые функции не трогаем, добавляем новые рядом.
- **Executor/worker (новые)** — получает `Record<string, unknown>`, собирает
  `Params` по схеме, вызывает `run`. Остаётся serializable.
- **Pipeline/chain (новый)** — шаги хранят значения, типизируются по схеме.

## Изменения в UI-компонентах

- **Старый UI** (`ParamForm.svelte`, группа `(old)/`) — **не трогаем.** Работает
  на `ParamDef[]` как раньше.
- **Новый UI** (kit/`SchemaToolView` + `SchemaFields` + `SchemaPreview`, читает
  `ToolSchema<P>`) — сейчас рендерит поля по схеме (number/slider/color).
- `tool-views.ts` отсутствует — preview/lede/layout уже живут в meta инструмента
  (`ToolEntry` + `schema.layout`), дублирования нет.

## Оценка трудозатрат

| Часть                                                 | Сложность                | Время                  |
| ----------------------------------------------------- | ------------------------ | ---------------------- |
| Typed field builders + toolSchema\<P\>                | Средняя                  | ~2ч                    |
| Новые defaultParams/sanitizeParams под схему          | Средняя                  | ~2-3ч                  |
| ToolEntry\<P\> generic + поле schema (рядом с params) | Низкая-Средняя           | ~1-2ч                  |
| Новый executor/worker/pipeline под схему              | Средняя                  | ~2-3ч                  |
| Миграция инструментов на interface Params + схемы     | Механическая, но крупная | ~8-12ч                 |
| Новый рендер (kit/ParamControl) + составные виджеты   | Средняя                  | ~4-5ч                  |
| Поглощение tool-views.ts                              | Средняя                  | ~1-2ч                  |
| Вынос старого UI в (old)/ + адаптация маршрутов       | Средняя-Низкая           | ~2-3ч                  |
| **Итого**                                             |                          | **~22-32ч** (поэтапно) |

> Оценка выросла по сравнению с ранней версией плана, потому что принят путь
> «явный interface Params + схема + общий рендер с пер-инструмент layout» — это
> полный рефакторинг pipeline, а не только добавление составных типов.
>
> Старый UI/`ParamDef[]`/старый pipeline в смету **не входят** — они не
> рефакторятся, а продолжают работать на `(old)/`-маршрутах до перехода (затем
> убираются отдельным решением — см. шаг 35).

## Порядок реализации (кратко)

Детальный пошаговый план с атомарными изменениями и порядком ревью — в разделе
«Пошаговый план перевода инструментов» выше. Здесь краткая сводка фаз:

1. **Фаза 0** — фундамент: builders + `toolSchema<P>` + `ToolEntry<P>.schema` +
   новые default/sanitize. Ни одного инструмента не изменено. ✔
2. **Фаза 1** — **один полноценный рабочий инструмент в preview** («добавить
   рамку»): schema + рендер + end-to-end применение. Ручная оценка
   работоспособности решения/сложностей.
3. **Фаза 2** — простые/одиночные инструменты (проверенный паттерн Фазы 1), 1
   инструмент = 1 диф.
4. **Фаза 3** — инструменты с составными типами (dimension → color-pair → offset
   → position9 → font-style → plate → gradient), пилот каждого типа отдельно.
5. **Фаза 4** — масштаб UI на остальные: составные виджеты, пер-инструмент
   layout (для каждого инструмента — UI-макет).
6. **Фаза 5** — изоляция: старый UI на `(old)/`-маршруты (не удаляется, остаётся
   для ревью); preview на `registry-new` полностью; линтер-изоляция веток
   (плагин `isolation`), затем перенос старых компонентов/библиотек в папки
   `old/`.

## Зависимости

- **UI сперва доделать** — текущая активная работа; типизация params ожидает
  готовности нового дизайна.
- Ветка redesign (`plan-redesign.md`) — параллельная, учесть при миграции
  kit/`ParamControl.svelte` и `overlay-store`.
- Старый pipeline остаётся рабочим и шippable на всём протяжении перехода
  (аналогично стратегии `plan-redesign.md`).