# frontend — веб-интерфейс

Зона записи сессий «Фронт». **Статус этапов, что построено и решения владельца по продукту —
`docs/frontend-PROGRESS.md`** (единственный носитель; здесь его копии намеренно нет, она отставала).
Что впереди — `docs/BACKLOG.md`, Ф-1.

## Как запустить

```bash
npm install
npm run dev          # http://localhost:5173/showcase
npm run check        # prettier → eslint → stylelint → contract → tsc → vitest
npm run check:full   # + сборка + скриншоты
npm run shot         # снимки в .shots/ — открыть и посмотреть глазами
npm run scenes       # сценарии интеракций: клик → кадр → проверка состояния
```

Маршрут выбирает мир фикстур, и снимаются все. Список маршрутов выводится из
`src/api/scenarios.ts` (`src/routes.tsx`), второй его экземпляр держит `scripts/shot.mjs`,
и расхождение двух списков падает тестом `src/routes.test.ts`. Прозаической копии списка здесь
нет намеренно: она отставала на этап, а два списка кода замкнуты друг на друга.

Два ключа снимка стоит знать: `--size 1280x764` даёт вьюпорт референса для прямого наложения,
`--dpr 1` снимает то, что видит владелец на своём мониторе (при дефолтных 2x полупиксель CSS
ложится в целый пиксель устройства, и мыло на штрихах иконок в кадр не попадает вовсе).
Замер кадра — `.tooling/py/bin/python scripts/measure.py references/fleet.png .shots/showcase.png`
(окружение запинено в `scripts/requirements.txt`, ставится одной строкой из его шапки).

Для скриншот-цикла нужен Chromium Playwright и локальные библиотеки в `.tooling/`
(ставятся без sudo, процедура — `docs/FRONTEND_PLAN.md` §4).

`npm install` заодно ставит pre-commit хук (`scripts/githooks/`): коммит с frontend-путями
не проходит без зелёного `npm run check`; смесь frontend/ с чужой зоной и файлы
«никогда не коммитить» блокируются для всех (D39.88). Обход — `git commit --no-verify`.

## Что здесь будет

Веб-приложение поверх `../platform/`. MVP — не IDE, а **дашборд + читалка**: библиотека книг,
наблюдение за прогоном, подпись банка памяти, сравнение оригинала с переводом, добавление главы.
Редактирование перевода прямо в интерфейсе — ПОЗЖЕ (тогда появится редактор текста; в MVP не нужен).

Десктоп — то же самое приложение в окне (Tauri), отдельной логики не имеет. В MVP не делается.

## Документы

- [`docs/FRONTEND_SESSION_PROMPT.md`](docs/FRONTEND_SESSION_PROMPT.md) — нормы зоны (не задание):
  референсы с измеренными значениями, продуктовый сценарий экранов, жёсткие ограничения
  владельца, порядок работы и критерий сравнения с референсом.
- [`docs/STACK_DECISIONS.md`](docs/STACK_DECISIONS.md) — пины версий, ловушки и список того,
  что достраивается в движке. Источник: многоагентное исследование 02.08.2026.
- [`docs/FRONTEND_PLAN.md`](docs/FRONTEND_PLAN.md) — как пишется фронт: сверенные пины, карта
  `src/`, слои каскада, правила поддерживаемости в проверяемой форме, протокол скриншот-цикла,
  перепроверенные замеры референса и границы гейтов.
- [`docs/frontend-PROGRESS.md`](docs/frontend-PROGRESS.md) — журнал зоны: текущее состояние,
  решения владельца по продукту, открытые вопросы, хроника сессий. Имя с префиксом `frontend-`
  намеренно: журнал оркестратора называется `docs/PROGRESS.md`, и одноимённые файлы путали
  ссылки. Прогресс фронта пишут сюда все, включая оркестратора (слово владельца 04.08).
- [`docs/BACKLOG.md`](docs/BACKLOG.md) — зонный бэклог фронта.
- [`docs/API_CONTRACT_INPUT.md`](docs/API_CONTRACT_INPUT.md) — ⚠ **исполнено, не поддерживается:**
  вход в контракт, написанный до него; остаётся аудиторским следом. Условия переноса в архив —
  в его собственном баннере.
- [`docs/api-contract/openapi.yaml`](docs/api-contract/openapi.yaml) — зонная копия контракта
  v0 (OpenAPI 3.1), из неё генерится `src/api/schema.ts` и её линтует spectral шагом
  `npm run check`. ⚠ **Не черновик и НЕ норматив:** контракт ратифицирован (D39.99), нормативен
  ТОЛЬКО канон `docs/architecture/14-api-contract/` (0.9.0), а копия стоит на 0.2.3 —
  байт-равенства сегодня НЕТ (D39.142 п.5). Синк `cmp` + перегенерация типов — первое касание
  зоны при разморозке; правит копию фронт-сессия, переносит в канон диффом оркестратор.
- [`docs/API_CONTRACT_DRAFT.md`](docs/API_CONTRACT_DRAFT.md) — ⚠ **исполнено:** зонный указатель
  на канон спутника `docs/architecture/14-api-contract/README.md`. Провенанс каждого решения,
  обоснования, зависимости и К-вопросы живут ТАМ; при расхождении по форме побеждает спека.
- `references/` — скриншоты-референсы (Fleet, Antigravity), в git не едут: кладёт владелец.

## Язык кода и язык интерфейса — разные вещи

Исходники зоны **английские**: комментарии, имена тестов, сообщения ошибок и логи скриптов.
Русский в `src/` живёт ровно в двух местах, и оба — данные: каталог сообщений
`src/i18n/ru.ts` (слова интерфейса, переводится файлом) и фикстуры `src/mock/` (проза книги,
которая стоит вместо настоящей). Держат это два гейта с РАЗНЫМИ правилами, и почему именно так — `docs/STACK_DECISIONS.md` §1.

## Источник внешнего вида — один

**Замеры референсов, зафиксированные в `tokens.css`.** Промежуточных дизайн-макетов нет:
инструменты проектирования макетов не используются (решение владельца 02.08). Палитра и геометрия
сняты замером, а не подобраны; действующие числа, способ их повторить и то, что отвергнуто, —
`docs/FRONTEND_PLAN.md` §5.1. Их берут как данность, а не выводят заново.