textmachine/frontend/docs/FRONTEND_SESSION_PROMPT.md

> ⚠ **ЭТО НЕ ЗАДАНИЕ, а носитель норм зоны** — референсы с измеренными значениями, продуктовый
> сценарий экранов, жёсткие ограничения владельца и порядок работы. На него так ссылается
> `frontend/README.md`. **Статус этапов и что уже построено — ТОЛЬКО `frontend-PROGRESS.md`**,
> здесь этого нет намеренно (копия отставала); очередь этапов S2–S7 — `BACKLOG.md` Ф-1.
> Поставлено оркестратором №15 08.08 по слепому онбординг-замеру: холодная сессия открывала файл
> первым по указателям и читала запрет «дальше не идти», адресованный давно отработавшей сессии.

# Промт: сессия ФРОНТ TextMachine — MVP веб-интерфейса

## Обязательное чтение перед работой

1. `frontend/docs/STACK_DECISIONS.md` — **пины версий и ловушки**. Все версии сверены 02.08.2026
   многоагентным исследованием с адверсариальной проверкой. Не выбирай библиотеки сам,
   не «обновляй» пины по памяти: твои знания об экосистеме устарели, а вся документация
   в сети описывает ПРОШЛЫЕ версии этих инструментов.
2. `docs/product-requirements.md` — реестр продуктовых требований владельца.
3. `docs/glossary.md` — расшифровка проектных сокращений.
4. `frontend/references/*.png` — три скриншота, **открой и посмотри** (ты умеешь читать изображения).

## Кто ты и твоя зона

Ты фронтенд-сессия. **Зона записи — только `frontend/`.** `backend/`, `platform/`, `docs/`, `eval/` — read-only; расхождения и вопросы — пингом владельцу, не правкой чужой зоны.

### ⚠ Зона и git (читать ДО первой строки кода)

**Ты не коммитишь — лендит оркестратор.** Твоё дело: довести дерево до зелёного `npm run check`,
описать сделанное в `frontend/docs/frontend-PROGRESS.md` и передать.

1. **Писать только внутрь `frontend/`.** Ничего за её пределами — ни `docs/`, ни `backend/`, ни `platform/`, ни корневых файлов, ни `.gitignore`. Нужна правка вне зоны — пинг владельцу, её сделает оркестратор.
2. **Чужие незакоммиченные файлы в дереве не трогать.** Параллельные сессии — норма: то, что лежит рядом изменённым, принадлежит не тебе.
3. **НИКАКИХ** `git add -A`, `git add .`, `reset --hard`, `amend`/`rebase`, `checkout` поверх грязного дерева и любой перезаписи истории.
4. Никогда не готовить к лендингу: `START_PROMT.MD` (файл владельца), `.claude/settings.local.json`.

Общие правила проекта — в `CLAUDE.md` в корне (там же эта норма в каноническом виде).

## Что за продукт

Веб-сервис перевода книг (веб-новеллы, ранобэ) с одного языка на другой через ИИ. Пользователь загружает книгу, запускает перевод, подписывает словарь терминов, читает результат, выгружает готовое.

⚠ **API у ПЛАТФОРМЫ, а не у движка; движок фронту не виден вообще** (D39.85, `research/23`).
Ошибка дорогая: моки, снятые не с того уровня контракта, разойдутся с API. Прежде чем писать слой
данных, прочитай `FRONTEND_PLAN.md` §0.1–0.2 (карта канона и два провода) и первоисточник
`docs/research/23-engine-platform-seam.md`.

Контракт API v0 РАТИФИЦИРОВАН (D39.99/100/101; канон `docs/architecture/14-api-contract/` —
OpenAPI 3.1, типы генерятся из спеки), и слой данных строится ПО КОНТРАКТУ, а не по гипотезам.
Что у платформы уже живо и чего ещё нет — `platform/BACKLOG.md` и её зонный журнал.

---

## 1. Референсы — копировать, а не вдохновляться

В `frontend/references/` лежат скриншоты-референсы (кладёт владелец, в git они не едут). **Открой их своим инструментом чтения файлов — ты умеешь смотреть изображения.** Это обязательный первый шаг, до единой строки кода.

- `fleet.png` — **главная основа макета**. Копируем оболочку целиком: как устроены панели, отступы, скругления, плотность, палитра.
- `antigravity_main.png` — пустое состояние (ничего не выбрано).
- `antigravity_chat.png` — рабочее состояние с тремя колонками и правой панелью-документом.

Владелец сформулировал прямо: **«взять макет Fleet как он есть по блокам и стилю и полностью скопировать, переделав под наши нужды»**. Это не тот случай, где нужна своя эстетика. Нужна чужая, воспроизведённая точно.

### 1.1. Замеры референса: геометрия и шесть поверхностей Antigravity ниже — живые (носитель `FRONTEND_PLAN.md` §5.1); три поверхности Fleet отвергнуты

Ниже — не оценка на глаз, а **замер пикселей** `fleet.png` (Python/PIL: гистограмма поверхностей, поиск насыщенных пикселей, срез по горизонтали, детект края скругления). Скриншот снят при масштабе **2x** — установлено по кнопкам окна macOS: шаг 40 физических пикселей против штатных 20 CSS. Все размеры ниже уже переведены в CSS-пиксели.

⚠ **Таблицы поверхностей здесь БОЛЬШЕ НЕТ, и брать тон отсюда нельзя.** Она давала `#17191a`
полотном, `#27292b` приподнятой поверхностью и `#353739` выбранной строкой — все три отменены
пере-замером палитры по слову владельца и в токенах не стоят (`FRONTEND_PLAN.md` §5.1, блок
«что отвергнуто»). Действующие числа — только `src/tokens/tokens.css` и §5.1 плана.
Акцент и красный индикатора здесь тоже больше не описываются тоном и насыщенностью: и то и другое
выводится из hex, а hex живёт токеном — `frontend/src/tokens/tokens.css` греп `--color-accent`
(`#746deb`) и греп `--color-danger` (`#bd2f47`, ПОДНЯТ против замера `#b82e45` ради контраста,
`FRONTEND_PLAN.md` §5.1). Второго носителя у этих чисел быть не должно.

**Геометрия Fleet:**

- **Промежуток между панелями — ровно 8px**, одинаковый везде: слева, между всеми панелями, справа (замер среза: четыре промежутка по 16 физических пикселей, без единого исключения).
- **Радиус скругления панели — 6px** (край выходит на прямую за ~11 физических пикселей).
- Панели не имеют ни рамок, ни теней: отделение только промежутком и разницей заливки оболочки и полотна (`--color-shell` → `--color-panel`).

**Antigravity — для пустого состояния и настроек** (чистый нейтральный серый, без холодного оттенка, в отличие от Fleet):

| Роль | Значение |
|---|---|
| Фон | `#101010` |
| Боковая панель | `#161616` |
| Приподнятая карточка (поле ввода) | `#1c1c1c` |
| Заливка кнопки основного действия | `#252525` |
| Разделитель / граница | `#323232` |
| Текст | `#cecece` |

**Что НЕ замерено и требует проверки скриншот-циклом:** размеры шрифтов, высота строк, внутренние отступы панелей. Их снимай сам сравнением своей витрины с `fleet.png`.

### Что именно снято с `fleet.png` (следуй этому буквально)

**Оболочка.** Очень тёмный, почти чёрный фон окна. Панели лежат на нём **отдельными скруглёнными «карточками»** (радиус ~8–10px) с чуть более светлой заливкой, разделённые узкими промежутками фона ~6–8px. Теней нет вообще — разделение только промежутком и разницей заливки. Это главная визуальная подпись Fleet, и владельцу нравится именно она.

**Верхняя полоса.** Слева кнопки сворачивания панелей (левая / нижняя / правая), по центру — название текущего контекста, справа — ряд иконок-действий. Тонкие линейные монохромные иконки.

**Левая панель.** Сверху **ряд вкладок внутри самой панели** (`Files · Search · Git · History · +`) — не отдельный сайдбар с иконками, а вкладки в шапке панели. Ниже дерево: корень, узлы с шевронами, иконки типов, у выбранной строки — светлая скруглённая подложка (~6px), а не рамка.

**Центр.** Полоса вкладок: иконка + имя + крестик; активная вкладка светлее и скруглена. Ниже содержимое с колонкой номеров строк приглушённого цвета, у текущей строки — едва заметная подсветка всей полосы. Мелкие подписи-подсказки над блоками очень тусклым серым. В правом верхнем углу — компактный индикатор проблем.

**Правая панель.** Вкладка с заголовком и `+`. В пустом состоянии — центрированный блок: иконка, заголовок, описание, ряды «клавиша + подпись». Внизу поле ввода с **акцентной рамкой** — единственное цветное пятно в панели.

**Нижняя статус-полоса** лежит на фоне оболочки, вне карточек: слева хлебные крошки, справа компактные метаданные состояния.

**Цвет.** Практически монохром: серый текст на тёмном. Цвет встречается редко и всегда что-то означает. Акцент — один, холодный.

**Типографика.** Компактный чистый гротеск ~13px в интерфейсе, моноширинный в содержимом. Плотные строки.

### Что снято с `antigravity_main.png` — пустое состояние

Главная область почти пустая, и по её **центру стоит один составной блок** — скруглённая карточка ввода с подсказкой внутри и рядом мелких управляющих элементов по нижнему краю. Никаких иллюстраций, никаких «начните работу» с картинками. Просто действие по центру пустоты.

В левой панели: **выделенная кнопка основного действия во всю ширину сверху**, ниже пункты навигации с иконками, ниже секция-заголовок мелким приглушённым шрифтом с иконками действий справа, ниже дерево. **`Настройки` прибиты к самому низу панели.**

### Что снято с `antigravity_chat.png` — рабочее состояние

Три колонки. В правой панели — **ряд вкладок сверху** (несколько именованных разделов) и содержимое как форматированный документ: заголовки, абзацы, **блоки-выноски с цветной левой границей** (синяя — заметка, зелёная — подсказка) и мелкие «чипы» с моноширинным текстом внутри абзацев.

**Эти выноски — наша модель для подсветки неточностей перевода** (см. §4, пункт про ненавязчивость). Цветная полоска слева и тусклая подпись — вместо заливки текста.

---

## 2. Раскладка нашего приложения

Оболочка Fleet, наполнение наше: три сворачиваемые панели, вкладки в шапке каждой, верхняя полоса
и статус-полоса.

⚠ **Схемы раскладки здесь больше нет: оболочка ПОСТРОЕНА, и её описывал устаревающий рисунок.**
Действующая раскладка — код `src/shell/` (`Shell.tsx`, `Panel.tsx`, `layout.ts`) плюс наполнение
панелей; продуктовые решения по составу вкладок и панелей перевешивают из «Решений владельца
по продукту» в `frontend-PROGRESS.md`.

⚠ Метки глав — из ДАННЫХ книги; зашитого «Глава N» не существует (D39.100 К-3).

---

## 3. Сценарий и экраны

### 3.1. Пусто — ни одной книги

Центр пустой, по центру — блок добавления книги в духе `antigravity_main.png`: скруглённая карточка, зона переноса файла с подсказкой, под ней компактный ряд полей (язык оригинала, язык перевода, жанр) и кнопка. Без иллюстраций.

### 3.2. Загрузка книги

После выбора файла: **видимое подтверждение, что файл загружен целиком и успешно** — размер, объём, определённый язык. Не молчаливый переход.

### 3.3. Разбор на главы

Дальше книга разбирается на главы. Показать прогресс разбора; по завершении главы появляются деревом в левой панели. Это отдельный видимый шаг, а не часть перевода.

### 3.4. Перевод — первый проход

Кнопка запуска перевода. Пока идёт:

- **у каждой главы в дереве — свой индикатор выполнения** (крутящийся/прогресс), главы обрабатываются не по порядку и это нормально;
- общий прогресс по книге в статус-полосе (+ ETA — решение владельца, D39.100 К-5; поле в спеке есть);
- ⚠ **не рассказывать, что происходит внутри.** Никаких «сейчас работает редактор», «идёт добыча глоссария», никаких названий моделей. Пользователь видит «идёт перевод» и прогресс. Всё.

### 3.5. Банк памяти — подпись

По завершении первого прохода становится доступен **банк памяти**: таблица терминов книги (имена персонажей, места, термины) с предложенным переводом. Пользователь правит и подписывает.

Таблица должна быть быстрой в работе: терминов бывают сотни, идут подряд, **клавиатура важнее мыши** (перемещение по строкам, утверждение, правка без мыши). Массовые действия. Отдельная кнопка завершения подписи.

### 3.6. Перевод — финальный проход

После подписи — кнопка запуска финального перевода. Те же индикаторы, что и в 3.4.

### 3.7. Чтение и сравнение

Открытая глава в центре: **две колонки — оригинал и перевод**, пролистываются вместе. Абзацы слева и справа по количеству часто НЕ совпадают — это нормально для художественного перевода, выравнивание идёт по крупным блокам, не построчно. Возможность листать главы вперёд-назад.

### 3.8. Замечания

Места, где перевод может быть неточен, помечаются **ненавязчиво**: тонкая цветная полоска у левого края блока и тусклая подпись — по образцу выносок из `antigravity_chat.png`. Никакой заливки текста, никаких ярких маркеров, никаких иконок-восклицаний. Список всех замечаний главы — в правой панели, вкладка `Замечания`.

Правило: **если экран выглядит тревожным — он неправильный.** Замечание — это приглашение посмотреть, а не сигнал аварии.

### 3.9. Метаданные книги

Правая панель, вкладка `О книге`: название, языки, жанр, число глав, объём, даты, состояние перевода. Спокойный список пар «поле — значение», не карточки со статистикой.

⚠ Денежных полей здесь нет — см. §4.8.

### 3.10. Добавление главы

В дереве, под главами книги — действие добавления новой главы. Загруженная глава встаёт в дерево и может быть переведена отдельно.

### 3.11. Экспорт

Кнопка выгрузки текущей книги. Выбор формата, подтверждение готовности.

### 3.12. Настройки

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

⚠ Подписки, тарифов, остатка и счетов в MVP НЕТ — см. §4.8.

---

## 4. Жёсткие ограничения

1. **Не раскрывать устройство бэкенда.** Ни названий моделей, ни стадий конвейера, ни внутренней терминологии в рабочих экранах. Пользователю видны: загрузка, разбор, перевод, банк, готово. Всё техническое — в настройках.
2. **Цвет означает состояние и больше ничего.** Интерфейс монохромный. Цветными бывают: полоска замечания, индикатор состояния главы, акцент фокуса. Никаких зелёных кнопок «сохранить» и красных «удалить».
3. **Ненавязчивость замечаний** — §3.8. Это отдельное требование владельца, не деталь.
4. **Плотность.** Работают подолгу; лучше видеть много, чем красиво и мало. Компактные строки, небольшие отступы, маленькие скругления — как во Fleet.
5. **Только десктоп**, тёмная тема, базовая ширина 1440, работать должно и на 1920. Мобильной версии нет.
6. **Русский интерфейс**, кириллица в реальных пропорциях.
7. **Никаких готовых UI-китов** (MUI, Ant, Chakra) — они не дадут воспроизвести Fleet. Только собственные компоненты на токенах; для поведения выпадающих меню, диалогов и подсказок — headless-примитивы без своих стилей.

### Решения владельца от 02.08 — приняты, не переоткрывать

8. **Денег в интерфейсе MVP нет вообще** (⚠ поправка 04.08, D39.100/ПТ-35: запрет СУММ в силе, но добавлены статус `paused`, оповещение «лимиты исчерпаны» и страница СТАТУСА использования в настройках — без долларов). Ни сумм, ни потолков, ни оценки стоимости до запуска, ни
   счётчика во время прогона, ни подписки, ни остатка. Оплаты в MVP не будет, показывать нечего.
   Учёт расхода остаётся внутри движка как телеметрия владельца. Если видишь денежное поле в
   каком-либо разделе этого промта — это остаток прошлой редакции, его быть не должно.
9. **Подсветка сомнительных мест — только на уровне блока и главы.** Подчёркивания внутри текста
   не делаем: у проверок движка нет байтовых смещений, только счётчики. Вопрос закрыт, к нему не
   возвращаться.
10. **Выравнивание колонок — грубое, по единицам экспорта**, ориентир «глава целиком». Механизм в
    движке уже есть (`tmctl export --pairs`), достраивать ничего не надо. Читалка обязана нормально
    выглядеть и когда вся глава оказалась одним блоком.
11. **Остановка на подписи банка — параметр запуска**, задаётся галочкой в форме перед каждым
    прогоном, а не глобальной настройкой.

---

## 5. Технический стек

**Стек зафиксирован в `frontend/docs/STACK_DECISIONS.md` — бери пины оттуда, не выбирай сам.**
Перечня пинов здесь нет намеренно: третий экземпляр списка версий отставал бы первым.

Три вещи, которые чаще всего делают неправильно, — прочитай про них в STACK_DECISIONS:
раздел про гейт «одно место для цвета», раздел про читалку без синхронизации прокруток,
и §7 «Ловушки». Карта `src/` с назначением каждой папки и правилом зависимостей —
`FRONTEND_PLAN.md` §2.

**Никакого редактора текста** в этом MVP: тексты только читают и сравнивают.

---

## 5.1. Поддерживаемость — требование владельца, не пожелание

Владелец сформулировал прямо: **«главное, чтоб это было очень легко поддерживаемо»**. Этот код будут править другие сессии, не ты.

**Сами правила — в `FRONTEND_PLAN.md` §3, и там у каждого стоит его проверка** (машинный гейт либо ревью-вопрос с однозначным ответом). Здесь их перечня нет намеренно: правило без проверки — лозунг, а два экземпляра списка расходятся.

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

## 6. Данные: моков придерживаться, API не выдумывать

**Весь доступ к данным — через `src/api/`, внутри которого пока моки.** Компоненты не знают, что данные поддельные; когда появится сервер, меняется один модуль. Мир фикстур на маршрут — карта в `FRONTEND_PLAN.md` §2 и шапка `src/mock/worlds.ts`.

**Материал для фикстур бери реальный** — китайский текст с русским переводом, имена и термины. Выдуманный «Lorem ipsum» даст неверную плотность: кириллица длиннее латиницы, иероглифы короче всего, и колонки поедут. Пример реального фрагмента лежит в `backend/example/chapter1-zh.txt` (читать можно, править нельзя).

Состояния фикстур — по словарю КОНТРАКТА, а не по списку в прозе: перечень значений живёт в канонической спеке `docs/architecture/14-api-contract/openapi.yaml` и приезжает в код генерацией. Прозаический список снят намеренно — он отставал от спеки на редакции.

---

## 7. Как работать — это важнее, чем что писать

### 7.1. Смотри на то, что построил

**Заведи цикл со скриншотами первым делом, до экранов.** Скрипт `npm run shot` поднимает приложение, снимает PNG в `frontend/.shots/`, ты **открываешь этот PNG и смотришь на него** (ты умеешь читать изображения), сравниваешь с `references/fleet.png`, правишь.

Без этого цикла ты пишешь вслепую: код валиден, вид случаен. Это единственный способ выполнить требование «скопировать Fleet».

**Стенд ставится без sudo** (WSL2/Ubuntu, пароль root недоступен): Chromium Playwright плюс четыре системные библиотеки локально в `.tooling/`. Процедура — `FRONTEND_PLAN.md` §4, второго её экземпляра здесь нет намеренно: команды уже разошлись бы (там же CJK-шрифт стенда, без которого весь китайский в кадре — квадраты).

Проверка, что цикл живой, если ставишь его заново: отрисуй страницу с полотном панели на фоне оболочки, радиус 6, отступ 8 — сними, открой, убедись, что видишь именно это. Браузер headless, окна нет, графический сервер не нужен.

### 7.2. Ревью исполнением — обязательно

Проектная норма: любая сессия, пишущая код, обязана **проверять себя исполнением**, а не заявлением. Для тебя это значит:

- приложение реально запускается, экран реально открывается — проверено запуском, не предположением;
- скриншот снят и просмотрен, а не «должно выглядеть так»;
- расхождения с референсом названы вслух, даже если исправить не успел;
- если чего-то не сделал — сказано прямо, без «в основном готово».

Отчёт в конце: что построено, что видно на скриншотах, где отошёл от референса и почему, что осталось.

### 7.3. Чего не делать

- Не изобретать API и не ходить в `backend/` за данными — только моки.
- Не тащить UI-киты и не «улучшать» референс своим вкусом.
- Не рисовать мобильную версию, светлую тему, иллюстрации пустых состояний.
- Не раскрывать конвейер (§4.1) — это самое лёгкое требование забыть.
- Не хардкодить цвета и размеры мимо `tokens.css`.

---

## 8. Критерий сравнения с референсом

⚠ **Не растровое совпадение**, и почему — `STACK_DECISIONS.md` §7 п.5. Сходиться обязаны:
**замеренные цвета, промежутки 8px, радиусы 6px, плотность строк и общее впечатление**.
Кегли и интерлиньяж — подбором на глаз до похожести, померить их больше негде.

Гейт против хардкода цвета и размера обязан быть **проверен живым нарушением** (вставить `#fff`
в компонент, убедиться, что проверка падает, убрать) — а не объявлен зелёным. Что именно уже
проверено этим способом и чего гейты НЕ видят — `FRONTEND_PLAN.md` §5.4.

## 9. Форма данных — из контракта

⚠ **Пересказ того, что движок отдаёт фронту, снят: он отставал от канона.** Форму задаёт
ратифицированный контракт `docs/architecture/14-api-contract/` (спека + спутник с провенансом
и К-вопросами), а что достраивается в движке — `STACK_DECISIONS.md` §8. Цена расхождения
замерена на этой же зоне: редакция 0.3.0 сняла с провода пофазный прогресс, который здесь ещё
предписывалось строить (К-10, вердикт «НЕ строить», D39.138).

Что остаётся правилом ФРОНТА, а не контракта, — `FRONTEND_PLAN.md` §6.