# План фазы 5: этап 5 — игровой интерфейс (apps/web, Astro)

Обновлено: 2026-08-05 | Статус: завершён (гейты зелёные, astro build собирает dist)

## Итоговые пометки (факт против плана)

- Astro запинен **5.18.2**, а не 7.1.6: astro 6/7 жёстко требуют Node
  > =22.12.0 (bin/astro.mjs, проверено по tarball), в окружении Node 20.
  > 5.18.2 — последняя линия с engines `^20.3.0`. Конфиг и объём — по плану
  > (output: 'static', без интеграций).
- Зона расширена на 3 корневых конфига игноров: eslint.config.js,
  .prettierignore, .gitignore — по одной записи `**/.astro/` (генерируемый
  astro каталог ломал lint/format).
- AiClient дополнен `readonly fallback` (предусмотрено текстом контракта);
  loadSettings/saveSettings — необязательным параметром StorageLike.
- Воркер собран Vite (chunk ai-worker-*.js в dist). Смоук dist в браузере:
  доска рендерится, ход игрока + ответ бота работают.

## Критические долги (реестр — в начале, III.5)

- Нет.

## Ключевые решения (не пере-решать)

- Astro 7.1.6 (версия сверена npm view 2026-08-05), output: 'static', без
  UI-фреймворков — vanilla TS + DOM (спека: «без тяжёлых UI-фреймворков»).
- Строки UI — один ресурсный файл src/ui/strings.ts с первого дня (спека).
- Отмена хода бота — terminate + пересоздание воркера (решение по известной
  проблеме cancel в реальном Worker, отчёт сессии 4).
- Режим подсказки: topMoves последнего MCTS-ответа как разметка + оценка;
  дельта = изменение winRate лучшего хода между запросами (упрощение —
  оценка с точки зрения стороны, чей ход анализировался; зафиксировано).
- Схема localStorage и AiClient — контракты в docs/INTERFACES.md
  (зафиксированы 2026-08-05 до кода).
- Страницы: / — заглушка-визитка со ссылкой на партию; /play — игра.
  Курс — этап 6, полировка (a11y, .htaccess) — этап 7.

## Объём этапа 5

1. apps/web (Astro): package.json @go-learn/web 0.1.0, astro.config.mjs
   (static), tsconfig (extends базового, lib DOM), workspaces += "apps/*".
2. Страница /play: доска (packages/board render + reduceInput + setupCanvas +
   attachPointerInput), панель: выбор доски 9/13/19, уровня 1–6, цвета
   (чёрные/белые/случайно), коми (auto/число), кнопки «Пас», «Сдаться»,
   «Отменить ход», «Новая партия»; счётчики пленников; статус-строка
   (чей ход, причина отказа из MoveError, итог партии).
3. Подсчёт по окончании (два паса): scorePosition + отметка мёртвых
   (suggestDeadGroups + ручной toggle по клику) → итог.
4. SGF: «Скачать SGF» (serializeSgf, blob-скачивание), «Загрузка SGF» —
   режим просмотра (parseSgf, навигация назад/вперёд без игры).
5. Подсказки ур. 4+ (переключатель, hintsEnabled): топ-3 хода маркерами с
   оценкой; дельта winRate.
6. 19×19 при ур. 4–6 — честное предупреждение (спека этапа 4).
7. Тёмная минималистичная тема (согласована с палитрой packages/board),
   адаптивность desktop+мобильные.
8. lib/storage.ts (по контракту), lib/ai-client.ts (по контракту),
   lib/game-store.ts (чистый, без DOM: GameTree + действия), ui/strings.ts.
9. Воркер: entry ai-worker.ts (строка подключения — комментарий в
   packages/ai/src/worker.ts), сборка воркера средствами Astro/Vite.

## Тесты (гейт приёмки этапа)

- storage: roundtrip save→load; битый JSON/checksum/неизвестная version →
  дефолты + recovered; миграция-путь задокументирован.
- game-store (чистый): новая партия, ход игрока через pending→confirm,
  отказ с reason при нелегальном, пас×2 → фаза подсчёта, toggle мёртвой
  группы, итог, resign → result, отмена хода, viewer: загрузка SGF,
  навигация prev/next.
- ai-client: фейк-worker (инжекция) — маршрутизация ур. 1–3 в синхронный
  движок, ур. 4–6 в воркер; cancel → AiCancelledError; фолбэк при отказе
  воркера.
- Матрица «чего НЕ покрывает ни один тест»: реальный кадр канвы в браузере,
  pointer на тачах, реальный Worker, astro build — смоук этапа 7 +
  ручная проверка владельцем.
- vitest.config: include += apps/*/src.

## Критерий выхода

Все тесты зелёные + `npm run gates` зелёный + `astro build` собирает dist.
Критерий v1 №4 («чистый клон собирается») проверяется сборкой в этой фазе;
№2 (партия против ур.5) и №5 (мобильный Safari) — ручная приёмка владельцем
после фазы 5–7.