feat(frontend): epic E5 — viewer UI (TASK-41…48, TASK-58) #6

Merged

geekiot merged 14 commits from feat/ui-frontend-e5 into main

2026-08-09 20:15:54 +05:00

geekiot commented

2026-08-09 20:15:35 +05:00

Owner

What this PR contains

The complete viewer frontend (epic E5) plus a supporting api endpoint:

TASK-41 — NextJS scaffold (App Router, strict TS) and the cartoon hand-drawn design foundation: table, avatar, speech bubble, buttons; Russian-only UI without an i18n layer (NFR-050; stack fixed as D-109).
TASK-58 — GET /settings in the viewer api: exactly 5 viewer keys from SETTINGS_REGISTRY (D-110) so the frontend follows setting changes without a release.
TASK-42 — typed API client (openapi-typescript codegen from the approved contract) and the polling loop: monotonic seq cursor (D-16), adaptive interval 1000–10000 ms driven by render backlog time (D-26, D-103), stop on session_status (D-73).
TASK-43 — home page: top menu button leads to the live session (US-V-01), countdown to next_scheduled_at (US-V-02).
TASK-44 — session screen: ellipse table (6..13+ players), avatars assembled from the component triple (D-47, placeholders until OPEN-8), speech bubbles timed by the D-26 formula with the D-103 cap, elimination marks.
TASK-45 — renderers for all 31 event types (coverage verified against the TASK-32 fixture), reasoning hidden by default and expandable (D-38), game error list from level: "error" (D-101), night table styling.
TASK-46 — pause/resume without event loss, catch-up to last_seq, chat (US-V-04); sessions list with the "finished with error" badge; replay via the same render path (US-V-05, D-62).
TASK-47 — player list and profile: temperament with metrics, model, games/wins, per-team win split, public memory (D-52), history (D-66).
TASK-48 — stats overview: all 6 D-20 metrics with provider columns carrying colored team shares (US-V-07); test tab rendering /sessions/test through the same SessionView (US-V-08, D-75); D-74 finalized (field composition fixed, TODO removed).

Spec and contracts

New decisions: D-109 (frontend stack), D-110 (/settings); D-74 finalized. Spec changes land as separate docs(spec) commits ahead of code. OpenAPI contract updated (/settings, D-74 draft marks removed); the implementation matches the contracts with zero deviations.

Verification

frontend: 144 vitest tests (including a full replay of the real fixture — 249 events), npm run build ✓
backend: 455 passed, 1 skipped (temperament catalog content — TASK-53/E7)
treefmt / ruff / ty / nix flake check — all green

Open items

OPEN-8: avatar assets — approach approved (SVG 8/6/6), illustrator-agent prompt at docs/prompts/avatar-assets-agent.md; the frontend renders placeholders, swapping assets requires no code change.
Known game-core flake (test_two_runs_are_identical) — out of scope; issue draft handed to the owner.

## What this PR contains The complete viewer frontend (epic E5) plus a supporting api endpoint: - **TASK-41** — NextJS scaffold (App Router, strict TS) and the cartoon hand-drawn design foundation: table, avatar, speech bubble, buttons; Russian-only UI without an i18n layer (NFR-050; stack fixed as D-109). - **TASK-58** — `GET /settings` in the viewer api: exactly 5 viewer keys from SETTINGS_REGISTRY (D-110) so the frontend follows setting changes without a release. - **TASK-42** — typed API client (openapi-typescript codegen from the approved contract) and the polling loop: monotonic seq cursor (D-16), adaptive interval 1000–10000 ms driven by render backlog time (D-26, D-103), stop on `session_status` (D-73). - **TASK-43** — home page: top menu button leads to the live session (US-V-01), countdown to `next_scheduled_at` (US-V-02). - **TASK-44** — session screen: ellipse table (6..13+ players), avatars assembled from the component triple (D-47, placeholders until OPEN-8), speech bubbles timed by the D-26 formula with the D-103 cap, elimination marks. - **TASK-45** — renderers for all 31 event types (coverage verified against the TASK-32 fixture), reasoning hidden by default and expandable (D-38), game error list from `level: "error"` (D-101), night table styling. - **TASK-46** — pause/resume without event loss, catch-up to `last_seq`, chat (US-V-04); sessions list with the "finished with error" badge; replay via the same render path (US-V-05, D-62). - **TASK-47** — player list and profile: temperament with metrics, model, games/wins, per-team win split, public memory (D-52), history (D-66). - **TASK-48** — stats overview: all 6 D-20 metrics with provider columns carrying colored team shares (US-V-07); test tab rendering `/sessions/test` through the same SessionView (US-V-08, D-75); D-74 finalized (field composition fixed, TODO removed). ## Spec and contracts New decisions: D-109 (frontend stack), D-110 (`/settings`); D-74 finalized. Spec changes land as separate `docs(spec)` commits ahead of code. OpenAPI contract updated (`/settings`, D-74 draft marks removed); the implementation matches the contracts with zero deviations. ## Verification - frontend: 144 vitest tests (including a full replay of the real fixture — 249 events), `npm run build` ✓ - backend: 455 passed, 1 skipped (temperament catalog content — TASK-53/E7) - treefmt / ruff / ty / `nix flake check` — all green ## Open items - OPEN-8: avatar assets — approach approved (SVG 8/6/6), illustrator-agent prompt at `docs/prompts/avatar-assets-agent.md`; the frontend renders placeholders, swapping assets requires no code change. - Known game-core flake (`test_two_runs_are_identical`) — out of scope; issue draft handed to the owner.

geekiot added 14 commits

2026-08-09 20:15:35 +05:00

docs(spec): D-109 — frontend stack (NextJS App Router, CSS Modules, Vitest+RTL snapshots) 8c00fdbc48

feat(frontend): NextJS scaffold and cartoon design foundation (TASK-41, FR-040, NFR-050, D-21) 78fbace0c7

docs(spec): D-110 — viewer settings endpoint GET /settings (TASK-58 registered) 8f00e3900a

feat(api): viewer settings endpoint GET /settings (TASK-58, D-110, D-103) 27cfa86efd

feat(frontend): typed api client (OpenAPI codegen) and adaptive polling loop (TASK-42, D-16, D-26, D-73) 71754847b8

feat(frontend): home page with live-session button and countdown (TASK-43, FR-040, US-V-01, US-V-02) c023768358

docs(prompts): avatar assets agent prompt (CO-STAR); OPEN-8 approach fixed 4be6e658b9

feat(frontend): session screen — ellipse table, layered avatars, timed speech bubbles (TASK-44, FR-041, US-V-03, D-26, D-47) 48b4626b8e

feat(frontend): render all event types, expandable reasoning, game error list (TASK-45, D-38, D-101, FR-041) 2d107e550d

feat(frontend): playback controls, chat, sessions list with replay (TASK-46, FR-042, US-V-04, US-V-05, D-62) bd9327875d