# Frontend: LoVisual site (Подсистема 1) — Implementation Plan > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. **Goal:** The account hub for LoVisual players: sign up / log in, link the game (device code), manage avatar and linked devices, keep 4 cloud config slots with share codes, and browse/copy configs from the public showcase. Plus a landing page that explains all of that in one screen. **Architecture:** React 19 SPA (Vite 8), feature folders per `frontend/ARCHITECTURE.md`. Server state via TanStack Query; one fetch wrapper (`shared/api/client.ts`) owns the access token (memory only), silent refresh through the httpOnly `lv_refresh` cookie, and error normalization. Routing via React Router 8 data router. The browser only ever talks to `/api/*` (Vite dev proxy → gateway on :8080; same path behind nginx in prod). **Tech Stack (installed and verified 2026-09-24, commit "chore(frontend): add router, react-query, fonts and vitest"):** React 19.2, Vite 8.3, TypeScript 7.0, Tailwind CSS 4.3 (`@tailwindcss/vite`), react-router 8.4 (`createBrowserRouter`/`createMemoryRouter`/`RouterProvider`/`Link`/`NavLink`/`Outlet`/`Navigate`/`useNavigate`/`useParams`/`useSearchParams` all exported from `react-router`), @tanstack/react-query 5.103, Vitest 5 + jsdom 30 + Testing Library (React 16, user-event 14, jest-dom 7 via `@testing-library/jest-dom/vitest`), fonts `@fontsource/comfortaa`, `@fontsource-variable/inter`, `@fontsource/iosevka`. Bun is the package manager (`bun add`, `bun run test`, `bun run build`, `bun run lint`). ## Global Constraints - **Bilingual (ru default, en).** From Task 5A on, no user-facing string is hard-coded: every string goes through i18next (`useTranslation`), with Russian as the source dictionary and English kept key-for-key identical (enforced by types). Sentence case, active voice in both. Code identifiers/comments in English. - **The mod is free.** No pricing, subscriptions, keys or HWID anywhere on the site. «Скачать» is the primary action everywhere. - **Visually rich, not minimal** (owner's explicit requirement after reviewing the first landing): every public page has a real visual centerpiece that shows the product (live ClickGui/HUD replicas, particle/bloom effects matching the mod, procedural scenes), orchestrated motion via `motion` (respecting `prefers-reduced-motion`), and depth. Text-and-boxes pages are rejected. - ≤250 lines per file, ≤4 files per folder (subfolders don't count). Tests live in a `tests/` subfolder of the feature/shared folder they cover (colocating `X.test.tsx` next to `X.tsx` would halve every folder's capacity under the 4-file rule) — Task 2 updates `ARCHITECTURE.md` accordingly. - No `any`. DTOs typed from the backend contracts (`backend/PLAN.md`, `backend/gateway/PLAN.md` Tasks 3–6, `backend/configs-service/PLAN.md`). - No barrel `index.ts` files. No business logic in `pages/`. - Access token lives in memory only (never localStorage). The refresh token is never visible to JS. - Every task: `bun run test`, `bun run build` (includes `tsc -b`) and `bun run lint` pass before commit. - Commits: English, conventional, explicit paths (`git add frontend/...`), never anything under `mod/`. End with `Claude-Session: https://claude.ai/code/session_01F1M1Jic1wTSn4igUENynmZ`. - `erasableSyntaxOnly` is on: no TS parameter properties, no enums — use explicit fields and string-literal unions. --- ## Design **Subject:** LoVisual is a legit visuals mod for Minecraft (HUD, particles, themes). The site's audience is its players; its main job is managing cloud configs and linking the game, with the landing explaining those two ideas. **Palette** — lifted from the mod's own default ClickGui theme (`mod/.../theme/presets/ThemePresets1.java`: window `#12191B`, header `#142226`, accent `#5CC8E7`, muted `#C6D2CD`), so the site feels like the in-game UI rather than a generic dark template: | Token | Hex | Role | |---|---|---| | `abyss` | `#0D1416` | page background (teal-tinted, not neutral black) | | `slate` | `#142226` | panels, top bar (the mod's header colour) | | `shoal` | `#1F3238` | borders, inputs, raised controls | | `frost` | `#9FB3B0` | secondary text (≈8:1 on abyss) | | `snow` | `#EEF5F3` | primary text | | `ice` | `#5CC8E7` | the one accent: primary actions, focus, share codes | | `ember` | `#E8835A` | destructive actions and errors only | **Type (revised 2026-09-25 — Cyrillic-first, commit "Cyrillic-first fonts"):** Unbounded Variable (wide geometric display face with full Cyrillic; headings, big numbers, logo) — `font-display`; Onest Variable (designed for Cyrillic; all body/UI text) — `font-sans`; JetBrains Mono Variable (has Cyrillic, unlike Iosevka; share codes, commands, chat lines, device codes) — `font-code`. Scale (≈1.25): 14 / 16 / 20 / 25 / 31 / 39 px, hero clamp(2.5rem, 6vw, 5rem). Body line length ≤ 70ch. **Visual direction (revised 2026-09-25):** the site looks like the mod running. Signature pieces, all built in code (no stock images; no AI-image API keys are available): - **ClickGui replica** — an HTML/CSS reproduction of the in-game ClickGui window (category column Combat / Visuals / Player / Misc, module cards with toggles and setting sliders, the theme's gradients and accent bloom), themable at runtime from the mod's real presets, with subtle 3D tilt following the pointer. - **HUD replicas** — TargetHUD, Keybinds, Potions, Watermark, Armor widgets drawn like the mod's HUD, draggable with the pointer. - **Particle field** — a `` of soft glowing particles (the mod's AmbientParticles/bloom look) tinted by the active theme accent; pauses when off-screen or with reduced motion. - **Voxel scene** — a procedural blocky landscape/sky (canvas or CSS 3D) as the backdrop the HUD sits on, so no copyrighted screenshots are needed. Real in-game screenshots from the owner can replace it later. - Gradients are allowed where they reproduce the mod's own theme gradients; decorative gradient washes are still out. **Layout:** Left-aligned, max width 1120px, 24px gutters (16px on phones). Top bar: logo left, three nav links (Витрина, Мои конфиги, Привязать игру), account button right. Panels (slate fill, 1px shoal border, 10px radius — the ClickGui window shape) are used only for things that *are* panels in the game: config slots, showcase entries, forms. Everything else sits directly on the page. ``` ┌ LoVisual ─────── Витрина Мои конфиги Привязать игру ───── [Войти] ┐ │ │ │ Твои настройки LoVisual — │ │ на любом компьютере │ │ Четыре облачных слота, код для друзей и витрина готовых конфигов. │ │ [Создать аккаунт] Смотреть витрину │ │ │ │ ┌ chat ─────────────────────────────────────────┐ │ │ │ %config load 7KQ3M9XA▌ │ ← signature │ │ │ [LoVisual] Конфиг «pvp» загружен │ │ │ └───────────────────────────────────────────────┘ │ │ │ │ Четыре слота ┌slot1┐┌slot2┐ │ │ ... └─────┘└─────┘ (2×2) │ │ Привязка игры: 1 → 2 → 3 (real sequence, so numbered) │ └──────────────────────────────────────────────────────────────────────┘ ``` **Principles:** 1. Speak the game's language: codes and commands appear exactly as typed in-game, in Iosevka. 2. One signature moment: the hero's chat line types `%config load …` once on load, then the confirmation line appears. Nothing else animates on its own (`prefers-reduced-motion` → both lines shown immediately). 3. Panels only where the game has panels; no card grids as decoration. 4. Errors say what happened and what to do, never "Что-то пошло не так". *Review against generic defaults:* dark + single accent is on the list of AI defaults. It is kept deliberately because it is the product's real in-game palette; the teal-tinted base (not #111), the ClickGui panel shape, Comfortaa, and the chat-line hero are what make it specific. Rejected alternatives: a stat-number hero ("10 000 игроков") — no real numbers exist; an all-caps eyebrow over each section — the section headings carry that job. --- ## File Structure ``` frontend/ index.html # title, lang="ru", favicon src/ main.tsx App.tsx routes.tsx index.css test/ setup.ts render.tsx fetch.ts smoke.test.tsx shared/ types.ts # Me (used by auth + account) api/ client.ts errors.ts tests/client.test.ts ui/ Button.tsx TextField.tsx ShareCode.tsx Notice.tsx tests/ui.test.tsx layout/ AppShell.tsx TopBar.tsx tests/layout.test.tsx features/ auth/ api.ts session.tsx RequireAuth.tsx validation.ts forms/ LoginForm.tsx RegisterForm.tsx tests/ session.test.tsx forms.test.tsx landing/ CommandHero.tsx HowItWorks.tsx tests/landing.test.tsx device-link/ api.ts LinkDeviceForm.tsx tests/link.test.tsx account/ api.ts components/ ProfileCard.tsx AvatarUpload.tsx DeviceList.tsx tests/account.test.tsx configs/ api.ts types.ts components/ SlotGrid.tsx SlotPanel.tsx PublishForm.tsx tests/configs.test.tsx showcase/ api.ts types.ts components/ ListingList.tsx ListingItem.tsx ListingDetail.tsx CopyToSlot.tsx tests/showcase.test.tsx pages/ public/ HomePage.tsx LoginPage.tsx RegisterPage.tsx NotFoundPage.tsx app/ LinkPage.tsx AccountPage.tsx ConfigsPage.tsx showcase/ ShowcasePage.tsx ListingPage.tsx ``` --- ### Task 1: Tooling — DONE Installed router/query/fonts/test tooling, Vitest config in `vite.config.ts` (jsdom, `src/test/setup.ts`), dev proxy `/api` → `http://localhost:8080` with `cookiePathRewrite: { '/auth': '/api/auth' }` (the backend scopes `lv_refresh` to `Path=/auth`), scaffold demo removed, smoke test. Nothing to do. --- ### Task 2: Design tokens, fonts, shared UI kit **Files:** - Modify: `src/index.css`, `index.html`, `frontend/ARCHITECTURE.md` (tests in `tests/` subfolders) - Create: `src/shared/ui/{Button,TextField,ShareCode,Notice}.tsx`, `src/shared/ui/tests/ui.test.tsx` **Interfaces (produces):** - `Button` props: `ButtonHTMLAttributes & { variant?: 'primary' | 'quiet' | 'danger'; busy?: boolean }` — `busy` disables and sets `aria-busy`. - `TextField` props: `InputHTMLAttributes & { label: string; error?: string; hint?: string }` — label wired via `useId`, error via `aria-invalid` + `aria-describedby`. - `ShareCode` props: `{ code: string; label?: string }` — shows the code in Iosevka + a «Скопировать» button (clipboard, then «Скопировано» for 2s, announced via `aria-live="polite"`). - `Notice` props: `{ tone: 'info' | 'error'; children: ReactNode }` — `role="alert"` for error, `role="status"` for info. - [ ] **Step 1: Tokens and fonts — `src/index.css`** ```css @import "tailwindcss"; @import "@fontsource-variable/inter"; @import "@fontsource/comfortaa/400.css"; @import "@fontsource/comfortaa/700.css"; @import "@fontsource/iosevka/400.css"; @import "@fontsource/iosevka/700.css"; @theme { --color-abyss: #0d1416; --color-slate: #142226; --color-shoal: #1f3238; --color-frost: #9fb3b0; --color-snow: #eef5f3; --color-ice: #5cc8e7; --color-ember: #e8835a; --font-display: "Comfortaa", ui-rounded, system-ui, sans-serif; --font-sans: "Inter Variable", system-ui, sans-serif; --font-code: "Iosevka", ui-monospace, monospace; --text-hero: 3.8125rem; --text-hero--line-height: 1.05; --radius-panel: 10px; } @layer base { html { color-scheme: dark; } body { @apply bg-abyss text-snow font-sans antialiased; min-height: 100dvh; } h1, h2, h3 { @apply font-display font-bold; } :focus-visible { outline: 2px solid var(--color-ice); outline-offset: 2px; } } @media (prefers-reduced-motion: reduce) { *, *::before, *::after { animation-duration: 0.01ms !important; transition-duration: 0.01ms !important; } } ``` `index.html`: `lang="ru"`, `LoVisual — аккаунт и облачные конфиги`, ``, ``. - [ ] **Step 2: Failing tests — `src/shared/ui/tests/ui.test.tsx`** ```tsx import { render, screen } from '@testing-library/react' import userEvent from '@testing-library/user-event' import { expect, test, vi } from 'vitest' import { Button } from '../Button' import { TextField } from '../TextField' import { ShareCode } from '../ShareCode' import { Notice } from '../Notice' test('busy button is disabled and announces busy', () => { render() const b = screen.getByRole('button', { name: 'Сохранить' }) expect(b).toBeDisabled() expect(b).toHaveAttribute('aria-busy', 'true') }) test('text field links label and error', () => { render() const input = screen.getByLabelText('Почта') expect(input).toHaveAttribute('aria-invalid', 'true') expect(input).toHaveAccessibleDescription('Введи почту') }) test('share code copies to clipboard and confirms', async () => { const user = userEvent.setup() const writeText = vi.spyOn(navigator.clipboard, 'writeText').mockResolvedValue() render() expect(screen.getByText('7KQ3M9XA')).toBeInTheDocument() await user.click(screen.getByRole('button', { name: 'Скопировать' })) expect(writeText).toHaveBeenCalledWith('7KQ3M9XA') expect(await screen.findByText('Скопировано')).toBeInTheDocument() }) test('error notice is an alert', () => { render(Неверный код) expect(screen.getByRole('alert')).toHaveTextContent('Неверный код') }) ``` (`userEvent.setup()` installs a clipboard stub on `navigator.clipboard`, which is why `spyOn` works after it.) Run: `bun run test` → FAIL. - [ ] **Step 3: Implement the kit** `Button.tsx`: ```tsx import type { ButtonHTMLAttributes } from 'react' type Variant = 'primary' | 'quiet' | 'danger' const VARIANTS: Record = { primary: 'bg-ice text-abyss hover:bg-ice/90', quiet: 'bg-transparent text-snow border border-shoal hover:border-frost', danger: 'bg-transparent text-ember border border-ember/60 hover:border-ember', } export function Button({ variant = 'primary', busy = false, disabled, className = '', type = 'button', ...rest }: ButtonHTMLAttributes & { variant?: Variant; busy?: boolean }) { return ( {copied ? 'Скопировано' : ''} ) } ``` `Notice.tsx`: ```tsx import type { ReactNode } from 'react' export function Notice({ tone, children }: { tone: 'info' | 'error'; children: ReactNode }) { const styles = tone === 'error' ? 'border-ember/60 text-ember' : 'border-shoal text-frost' return (
{children}
) } ``` - [ ] **Step 4: ARCHITECTURE.md** Replace the "Тестирование" section's colocation rule with: tests live in a `tests/` subfolder inside the feature (or `shared/*`) folder they cover — still deleted together with the feature, but they don't eat into the 4-files-per-folder budget. Update the example tree accordingly. - [ ] **Step 5: test/build/lint pass; commit** ```bash git add frontend/src/index.css frontend/index.html frontend/ARCHITECTURE.md frontend/src/shared git commit -m "feat(frontend): design tokens from the mod theme, fonts and shared UI kit" ``` --- ### Task 3: API client + test helpers **Files:** - Create: `src/shared/api/client.ts`, `src/shared/api/errors.ts`, `src/shared/api/tests/client.test.ts`, `src/shared/types.ts`, `src/test/fetch.ts`, `src/test/render.tsx` **Interfaces (produces):** - `class ApiError extends Error { status: number; retryAfter: number | null }`. - `createApiClient(baseUrl?: string, fetchImpl?: typeof fetch): ApiClient`, `ApiClient = { request(path, options?: RequestOptions): Promise; refresh(): Promise; setAccessToken(t: string | null): void; hasAccessToken(): boolean }`, `RequestOptions = { method?: string; json?: unknown; body?: BodyInit; signal?: AbortSignal }`. Singleton `api = createApiClient()`. - Behaviour: JSON body → `content-type: application/json`; token → `authorization: Bearer`; `credentials: 'include'` always; on 401 for a non-`/auth/*` path → one shared (single-flight) `POST /auth/refresh`, then one retry; non-2xx → `ApiError` with the backend's `{error}` message and `Retry-After` seconds; 204/empty body → `undefined`. - `errors.ts`: `describeError(err: unknown, overrides?: Partial>): string` — Russian message per status (429 includes the wait: «Слишком много попыток. Подожди N с.»; network failure → «Нет связи с сервером. Проверь интернет и попробуй ещё раз.»; 5xx → «Сервер не ответил. Попробуй через минуту.»; 404 → «Не найдено.»; default 400 → «Проверь введённые данные.»). - `shared/types.ts`: `Me = { id: string; email: string; display_nick: string; role: 'user' | 'admin'; avatar_url: string | null; created_at: string }`. - `test/fetch.ts`: `mockFetch(routes: Record Response | Promise>)` — key `"METHOD /path"` (path without `/api`, query ignored); unknown routes → 404; returns the `vi.fn` for call assertions; installs via `vi.stubGlobal('fetch', …)`. `json(body, status = 200, headers?)` helper. - `test/render.tsx`: `renderApp(routes: RouteObject[], initialPath: string)` → wraps in a fresh `QueryClient` (`retry: false`) + `SessionProvider` (Task 4 — until then only QueryClient) + `createMemoryRouter`; returns Testing Library result + `router`. - [ ] **Step 1: Test helpers first** `src/test/fetch.ts`: ```ts import { vi } from 'vitest' type Handler = (init: RequestInit) => Response | Promise export function json(body: unknown, status = 200, headers: Record = {}): Response { return new Response(body === undefined ? null : JSON.stringify(body), { status, headers: { 'content-type': 'application/json', ...headers }, }) } export function mockFetch(routes: Record) { const fn = vi.fn(async (input: RequestInfo | URL, init: RequestInit = {}) => { const url = new URL(String(input), 'http://localhost') const key = `${(init.method ?? 'GET').toUpperCase()} ${url.pathname.replace(/^\/api/, '')}` const handler = routes[key] return handler ? handler(init) : json({ error: `no mock for ${key}` }, 404) }) vi.stubGlobal('fetch', fn) return fn } ``` Add `afterEach(() => vi.unstubAllGlobals())` to `src/test/setup.ts`. - [ ] **Step 2: Failing client tests — `src/shared/api/tests/client.test.ts`** ```ts import { expect, test } from 'vitest' import { ApiError, createApiClient } from '../client' import { json, mockFetch } from '../../../test/fetch' test('sends json with bearer token and cookies', async () => { const fetch = mockFetch({ 'PUT /configs/1': () => json({ ok: true }) }) const api = createApiClient() api.setAccessToken('tok') await api.request('/configs/1', { method: 'PUT', json: { a: 1 } }) const [, init] = fetch.mock.calls[0] const headers = new Headers(init?.headers) expect(headers.get('authorization')).toBe('Bearer tok') expect(headers.get('content-type')).toBe('application/json') expect(init?.credentials).toBe('include') expect(init?.body).toBe('{"a":1}') }) test('401 triggers one refresh and one retry', async () => { let calls = 0 const fetch = mockFetch({ 'GET /me': () => (++calls === 1 ? json({ error: 'unauthorized' }, 401) : json({ id: 'x' })), 'POST /auth/refresh': () => json({ access_token: 'new' }), }) const api = createApiClient() await expect(api.request('/me')).resolves.toEqual({ id: 'x' }) expect(fetch.mock.calls.filter(([u]) => String(u).endsWith('/auth/refresh'))).toHaveLength(1) expect(new Headers(fetch.mock.calls[2][1]?.headers).get('authorization')).toBe('Bearer new') }) test('concurrent 401s share a single refresh', async () => { let refreshes = 0 mockFetch({ 'GET /a': (init) => (new Headers(init.headers).get('authorization') ? json(1) : json({}, 401)), 'GET /b': (init) => (new Headers(init.headers).get('authorization') ? json(2) : json({}, 401)), 'POST /auth/refresh': () => { refreshes++; return json({ access_token: 't' }) }, }) const api = createApiClient() await Promise.all([api.request('/a'), api.request('/b')]) expect(refreshes).toBe(1) }) test('failed refresh surfaces the original 401 and clears the token', async () => { mockFetch({ 'GET /me': () => json({ error: 'unauthorized' }, 401), 'POST /auth/refresh': () => json({ error: 'unauthorized' }, 401), }) const api = createApiClient() api.setAccessToken('stale') await expect(api.request('/me')).rejects.toMatchObject({ status: 401 }) expect(api.hasAccessToken()).toBe(false) }) test('auth endpoints never trigger refresh', async () => { const fetch = mockFetch({ 'POST /auth/login': () => json({ error: 'unauthorized' }, 401) }) await expect(createApiClient().request('/auth/login', { method: 'POST', json: {} })).rejects.toBeInstanceOf(ApiError) expect(fetch).toHaveBeenCalledTimes(1) }) test('429 carries retry-after; 204 resolves undefined', async () => { mockFetch({ 'POST /auth/login': () => json({ error: 'too many requests' }, 429, { 'retry-after': '42' }), 'DELETE /device/links/1': () => new Response(null, { status: 204 }), }) const api = createApiClient() await expect(api.request('/auth/login', { method: 'POST' })).rejects.toMatchObject({ status: 429, retryAfter: 42 }) await expect(api.request('/device/links/1', { method: 'DELETE' })).resolves.toBeUndefined() }) ``` - [ ] **Step 3: Implement `client.ts`** ```ts export class ApiError extends Error { readonly status: number readonly retryAfter: number | null constructor(status: number, message: string, retryAfter: number | null = null) { super(message) this.name = 'ApiError' this.status = status this.retryAfter = retryAfter } } export type RequestOptions = { method?: string; json?: unknown; body?: BodyInit; signal?: AbortSignal } export type ApiClient = { request(path: string, options?: RequestOptions): Promise refresh(): Promise setAccessToken(token: string | null): void hasAccessToken(): boolean } async function toError(res: Response): Promise { let message = `HTTP ${res.status}` try { const body: unknown = await res.json() if (body && typeof body === 'object' && 'error' in body && typeof body.error === 'string') message = body.error } catch { // non-JSON error body: keep the status text } const retry = Number(res.headers.get('retry-after')) return new ApiError(res.status, message, Number.isFinite(retry) && retry > 0 ? retry : null) } export function createApiClient( baseUrl = '/api', // Resolved at call time so tests can stub the global fetch. fetchImpl: typeof fetch = (input, init) => fetch(input, init), ): ApiClient { let accessToken: string | null = null let refreshing: Promise | null = null async function refreshOnce(): Promise { try { const res = await fetchImpl(`${baseUrl}/auth/refresh`, { method: 'POST', credentials: 'include' }) if (!res.ok) { accessToken = null return false } const body = (await res.json()) as { access_token: string } accessToken = body.access_token return true } catch { return false } } function refresh(): Promise { refreshing ??= refreshOnce().finally(() => { refreshing = null }) return refreshing } function send(path: string, options: RequestOptions): Promise { const headers = new Headers() let body = options.body if (options.json !== undefined) { headers.set('content-type', 'application/json') body = JSON.stringify(options.json) } if (accessToken) headers.set('authorization', `Bearer ${accessToken}`) return fetchImpl(`${baseUrl}${path}`, { method: options.method ?? 'GET', headers, body, credentials: 'include', signal: options.signal, }) } async function request(path: string, options: RequestOptions = {}): Promise { let res = await send(path, options) if (res.status === 401 && !path.startsWith('/auth/') && (await refresh())) { res = await send(path, options) } if (!res.ok) throw await toError(res) const text = await res.text() return (text ? JSON.parse(text) : undefined) as T } return { request, refresh, setAccessToken: (token) => { accessToken = token }, hasAccessToken: () => accessToken !== null, } } export const api = createApiClient() ``` - [ ] **Step 4: `errors.ts`, `shared/types.ts`, `test/render.tsx`** ```ts // errors.ts import { ApiError } from './client' const BY_STATUS: Record = { 400: 'Проверь введённые данные.', 401: 'Нужно войти в аккаунт.', 403: 'Недостаточно прав.', 404: 'Не найдено.', 409: 'Уже существует.', } export function describeError(err: unknown, overrides: Partial> = {}): string { if (err instanceof ApiError) { if (err.status === 429) { return err.retryAfter ? `Слишком много попыток. Подожди ${err.retryAfter} с.` : 'Слишком много попыток. Подожди немного.' } if (err.status >= 500) return 'Сервер не ответил. Попробуй через минуту.' return overrides[err.status] ?? BY_STATUS[err.status] ?? 'Запрос не прошёл. Попробуй ещё раз.' } return 'Нет связи с сервером. Проверь интернет и попробуй ещё раз.' } ``` ```ts // shared/types.ts export type Me = { id: string email: string display_nick: string role: 'user' | 'admin' avatar_url: string | null created_at: string } ``` ```tsx // test/render.tsx import { QueryClient, QueryClientProvider } from '@tanstack/react-query' import { render } from '@testing-library/react' import { createMemoryRouter, RouterProvider, type RouteObject } from 'react-router' export function renderApp(routes: RouteObject[], initialPath = '/') { const client = new QueryClient({ defaultOptions: { queries: { retry: false }, mutations: { retry: false } } }) const router = createMemoryRouter(routes, { initialEntries: [initialPath] }) const result = render( , ) return { ...result, router, client } } ``` Add one test for `describeError` (429 with and without `retryAfter`, a `TypeError` → network message) to `client.test.ts`. - [ ] **Step 5: pass; commit** ```bash git add frontend/src/shared frontend/src/test git commit -m "feat(frontend): API client with silent refresh, error descriptions and test helpers" ``` --- ### Task 4: Session, login, register, route guard **Files:** - Create: `src/features/auth/{api.ts,session.tsx,RequireAuth.tsx,validation.ts}`, `src/features/auth/forms/{LoginForm,RegisterForm}.tsx`, `src/features/auth/tests/{session,forms}.test.tsx`, `src/pages/public/{LoginPage,RegisterPage}.tsx` - Modify: `src/test/render.tsx` (wrap in `SessionProvider`) **Interfaces:** - `auth/api.ts`: `login(email, password): Promise` (stores token via `api.setAccessToken`), `register(email, password, nick): Promise`, `logout(): Promise` (POST `/auth/logout`, clears token even if it fails), `fetchMe(): Promise`. - `auth/session.tsx`: `SessionProvider`, `useSession(): { status: 'loading' | 'anonymous' | 'authenticated'; me: Me | null; signIn(email, password): Promise; signUp(email, password, nick): Promise; signOut(): Promise }`. On mount: `api.refresh()`; if true → load `['me']`. `signIn` → login + refetch me. `signUp` → register then signIn. `signOut` → logout, `queryClient.clear()`. - `auth/validation.ts` (mirrors the backend so 400s are rare): `validateEmail`, `validatePassword` (8+ chars, ≤256 bytes via `new TextEncoder().encode(p).length`), `validateNick` (1..32 chars after trim) — each returns `string | undefined` (Russian message). - `RequireAuth`: loading → quiet placeholder `

Проверяем вход…

`; anonymous → ``; else ``. - Login form: fields «Почта», «Пароль»; submit «Войти»; 401 → «Неверная почта или пароль.»; success → navigate to `state.from ?? '/configs'`. Register form: «Почта», «Ник на сайте» (hint «Не обязательно совпадает с ником в Minecraft.»), «Пароль» (hint «Минимум 8 символов.»); submit «Создать аккаунт»; 409 → «Эта почта уже занята. Войди или используй другую.» - [ ] **Step 1: Failing tests** `tests/session.test.tsx`: ```tsx import { screen } from '@testing-library/react' import { expect, test } from 'vitest' import { RequireAuth } from '../RequireAuth' import { useSession } from '../session' import { renderApp } from '../../../test/render' import { json, mockFetch } from '../../../test/fetch' const me = { id: '1', email: 'a@b.c', display_nick: 'Rider', role: 'user', avatar_url: null, created_at: '2026-09-24T00:00:00Z' } function Whoami() { const { me } = useSession() return

Привет, {me?.display_nick}

} const routes = [ { path: '/login', element:

Страница входа

}, { element: , children: [{ path: '/configs', element: }] }, ] test('restores the session from the refresh cookie', async () => { mockFetch({ 'POST /auth/refresh': () => json({ access_token: 't' }), 'GET /me': () => json(me) }) renderApp(routes, '/configs') expect(await screen.findByText('Привет, Rider')).toBeInTheDocument() }) test('anonymous visitor is sent to login', async () => { mockFetch({ 'POST /auth/refresh': () => json({ error: 'unauthorized' }, 401) }) renderApp(routes, '/configs') expect(await screen.findByText('Страница входа')).toBeInTheDocument() }) ``` `tests/forms.test.tsx`: ```tsx import { screen } from '@testing-library/react' import userEvent from '@testing-library/user-event' import { expect, test } from 'vitest' import { LoginForm } from '../forms/LoginForm' import { RegisterForm } from '../forms/RegisterForm' import { renderApp } from '../../../test/render' import { json, mockFetch } from '../../../test/fetch' const me = { id: '1', email: 'a@b.c', display_nick: 'Rider', role: 'user', avatar_url: null, created_at: '2026-09-24T00:00:00Z' } const anon = { 'POST /auth/refresh': () => json({ error: 'unauthorized' }, 401) } test('wrong password shows a clear error', async () => { const user = userEvent.setup() mockFetch({ ...anon, 'POST /auth/login': () => json({ error: 'unauthorized' }, 401) }) renderApp([{ path: '/login', element: }], '/login') await user.type(await screen.findByLabelText('Почта'), 'a@b.c') await user.type(screen.getByLabelText('Пароль'), 'wrong-password') await user.click(screen.getByRole('button', { name: 'Войти' })) expect(await screen.findByRole('alert')).toHaveTextContent('Неверная почта или пароль.') }) test('successful login goes to configs', async () => { const user = userEvent.setup() mockFetch({ ...anon, 'POST /auth/login': () => json({ access_token: 't' }), 'GET /me': () => json(me) }) renderApp([{ path: '/login', element: }, { path: '/configs', element:

Мои конфиги

}], '/login') await user.type(await screen.findByLabelText('Почта'), 'a@b.c') await user.type(screen.getByLabelText('Пароль'), 'correct-horse') await user.click(screen.getByRole('button', { name: 'Войти' })) expect(await screen.findByText('Мои конфиги')).toBeInTheDocument() }) test('register validates before calling the server', async () => { const user = userEvent.setup() const fetch = mockFetch(anon) renderApp([{ path: '/register', element: }], '/register') await user.type(await screen.findByLabelText('Почта'), 'not-an-email') await user.type(screen.getByLabelText('Пароль'), 'short') await user.click(screen.getByRole('button', { name: 'Создать аккаунт' })) expect(screen.getByLabelText('Почта')).toHaveAttribute('aria-invalid', 'true') expect(screen.getByLabelText('Пароль')).toHaveAccessibleDescription('Минимум 8 символов.') expect(fetch.mock.calls.some(([u]) => String(u).includes('/auth/register'))).toBe(false) }) test('taken email explains what to do', async () => { const user = userEvent.setup() mockFetch({ ...anon, 'POST /auth/register': () => json({ error: 'email already registered' }, 409) }) renderApp([{ path: '/register', element: }], '/register') await user.type(await screen.findByLabelText('Почта'), 'a@b.c') await user.type(screen.getByLabelText('Ник на сайте'), 'Rider') await user.type(screen.getByLabelText('Пароль'), 'correct-horse') await user.click(screen.getByRole('button', { name: 'Создать аккаунт' })) expect(await screen.findByRole('alert')).toHaveTextContent('Эта почта уже занята') }) ``` - [ ] **Step 2: Implement `api.ts`, `validation.ts`** ```ts // api.ts import { api } from '../../shared/api/client' import type { Me } from '../../shared/types' export async function login(email: string, password: string): Promise { const res = await api.request<{ access_token: string }>('/auth/login', { method: 'POST', json: { email, password } }) api.setAccessToken(res.access_token) } export async function register(email: string, password: string, nick: string): Promise { await api.request('/auth/register', { method: 'POST', json: { email, password, nick } }) } export async function logout(): Promise { try { await api.request('/auth/logout', { method: 'POST' }) } finally { api.setAccessToken(null) } } export const fetchMe = () => api.request('/me') ``` ```ts // validation.ts export function validateEmail(email: string): string | undefined { const v = email.trim() if (!v) return 'Введи почту.' if (v.length > 254 || !/^[^@\s]+@[^@\s]+$/.test(v)) return 'Похоже, в почте опечатка.' } export function validatePassword(password: string): string | undefined { if ([...password].length < 8) return 'Минимум 8 символов.' if (new TextEncoder().encode(password).length > 256) return 'Слишком длинный пароль.' } export function validateNick(nick: string): string | undefined { const len = [...nick.trim()].length if (len === 0) return 'Придумай ник.' if (len > 32) return 'Не длиннее 32 символов.' } ``` - [ ] **Step 3: Implement `session.tsx`** ```tsx import { useQuery, useQueryClient } from '@tanstack/react-query' import { createContext, useCallback, useContext, useMemo, type ReactNode } from 'react' import { api } from '../../shared/api/client' import type { Me } from '../../shared/types' import { fetchMe, login, logout, register } from './api' type Session = { status: 'loading' | 'anonymous' | 'authenticated' me: Me | null signIn(email: string, password: string): Promise signUp(email: string, password: string, nick: string): Promise signOut(): Promise } const SessionContext = createContext(null) export function SessionProvider({ children }: { children: ReactNode }) { const client = useQueryClient() // Restores the session after a reload: the refresh cookie survives, the // in-memory access token does not. const restored = useQuery({ queryKey: ['session-restore'], queryFn: () => api.refresh(), staleTime: Infinity }) const meQuery = useQuery({ queryKey: ['me'], queryFn: fetchMe, enabled: restored.data === true }) const signIn = useCallback(async (email: string, password: string) => { await login(email, password) client.setQueryData(['session-restore'], true) await client.fetchQuery({ queryKey: ['me'], queryFn: fetchMe }) }, [client]) const signUp = useCallback(async (email: string, password: string, nick: string) => { await register(email, password, nick) await signIn(email, password) }, [signIn]) const signOut = useCallback(async () => { await logout() client.clear() client.setQueryData(['session-restore'], false) }, [client]) const value = useMemo(() => { const me = meQuery.data ?? null const status = restored.isPending || (restored.data && meQuery.isPending) ? 'loading' : me ? 'authenticated' : 'anonymous' return { status, me, signIn, signUp, signOut } }, [restored.isPending, restored.data, meQuery.isPending, meQuery.data, signIn, signUp, signOut]) return {children} } export function useSession(): Session { const session = useContext(SessionContext) if (!session) throw new Error('useSession outside SessionProvider') return session } ``` (React 19: a context object renders directly as a provider.) Update `test/render.tsx` to wrap `RouterProvider` in `` (inside `QueryClientProvider`). - [ ] **Step 4: `RequireAuth.tsx`, forms, pages** ```tsx // RequireAuth.tsx import { Navigate, Outlet, useLocation } from 'react-router' import { useSession } from './session' export function RequireAuth() { const { status } = useSession() const location = useLocation() if (status === 'loading') return

Проверяем вход…

if (status === 'anonymous') return return } ``` ```tsx // forms/LoginForm.tsx import { useState, type FormEvent } from 'react' import { Link, useLocation, useNavigate } from 'react-router' import { describeError } from '../../../shared/api/errors' import { Button } from '../../../shared/ui/Button' import { Notice } from '../../../shared/ui/Notice' import { TextField } from '../../../shared/ui/TextField' import { useSession } from '../session' export function LoginForm() { const { signIn } = useSession() const navigate = useNavigate() const from = (useLocation().state as { from?: string } | null)?.from ?? '/configs' const [email, setEmail] = useState('') const [password, setPassword] = useState('') const [error, setError] = useState() const [busy, setBusy] = useState(false) async function submit(e: FormEvent) { e.preventDefault() setBusy(true) setError(undefined) try { await signIn(email.trim(), password) navigate(from, { replace: true }) } catch (err) { setError(describeError(err, { 401: 'Неверная почта или пароль.' })) } finally { setBusy(false) } } return (
setEmail(e.target.value)} /> setPassword(e.target.value)} /> {error ? {error} : null}

Нет аккаунта? Создать

) } ``` `RegisterForm.tsx` follows the same shape: three fields, per-field `error` from `validation.ts` computed on submit (fields keep their `hint` otherwise), no request when any field is invalid, `describeError(err, { 409: 'Эта почта уже занята. Войди или используй другую.' })`, success → `navigate('/configs', { replace: true })`, footer «Уже есть аккаунт? Войти». Password field: `hint="Минимум 8 символов."`, and when its validation fails show the validation message as `error` (so the test's accessible description `Минимум 8 символов.` holds either way). Pages (thin): `LoginPage.tsx` ```tsx import { LoginForm } from '../../features/auth/forms/LoginForm' export default function LoginPage() { return (

Вход

) } ``` `RegisterPage.tsx` the same with «Новый аккаунт» and a one-line lead: «Аккаунт нужен для облачных конфигов и привязки игры. Пароль в мод вводить не придётся.» - [ ] **Step 5: pass; commit** ```bash git add frontend/src/features/auth frontend/src/pages frontend/src/test git commit -m "feat(frontend): session restore, login and registration with client-side validation" ``` --- ### Task 5: App shell, routes, landing page **Files:** - Create: `src/routes.tsx`, `src/shared/layout/{AppShell,TopBar}.tsx`, `src/shared/layout/tests/layout.test.tsx`, `src/features/landing/{CommandHero,HowItWorks}.tsx`, `src/features/landing/tests/landing.test.tsx`, `src/pages/public/{HomePage,NotFoundPage}.tsx` - Modify: `src/App.tsx`, `src/test/smoke.test.tsx` (delete — superseded by layout tests) **Interfaces:** - `routes: RouteObject[]` in `routes.tsx` — root `{ element: , children: [...] }`. Pages from Tasks 6–9 are added there by those tasks; lazy-load them with `lazy: () => import('./pages/app/ConfigsPage').then((m) => ({ Component: m.default }))`. - `App.tsx`: `QueryClientProvider` (singleton `QueryClient`, `staleTime: 30_000`) → `SessionProvider` → `RouterProvider router={createBrowserRouter(routes)}`. - `TopBar`: logo «LoVisual» (Comfortaa, links to `/`); `NavLink`s «Витрина» `/showcase`, «Мои конфиги» `/configs`, «Привязать игру» `/link` (active link: `text-snow`, inactive `text-frost`); right side: anonymous → «Войти» (quiet button-styled link to `/login`); authenticated → avatar (or first letter of nick in a shoal circle) + nick linking to `/account`. On < 640px nav collapses under a «Меню» disclosure button (`aria-expanded`). - `CommandHero`: headline «Твои настройки LoVisual — на любом компьютере», lead «Четыре облачных слота, код, которым делишься с друзьями, и витрина готовых конфигов.», CTAs «Создать аккаунт» (→ `/register`, primary; replaced by «Мои конфиги» → `/configs` when authenticated) and «Смотреть витрину» (quiet). Below: the chat bar (`bg-black/55`, Iosevka, like Minecraft's chat) that types `%config load 7KQ3M9XA` (60ms/char, once, via `setInterval` in an effect) then shows `[LoVisual] Конфиг «pvp» загружен` in ice. With `matchMedia('(prefers-reduced-motion: reduce)').matches` both lines render complete immediately. The whole bar has `aria-label="Пример: загрузка конфига по коду в чате игры"` and the animated text is `aria-hidden`, so screen readers get one stable sentence. - `HowItWorks`: section «Четыре слота в облаке» (2×2 grid of small slate panels: «pvp», «стрим», «ленивый», «пусто» in frost italics) with one sentence each side; section «Привязка игры» as an `
    ` of three steps: «В моде открой вкладку аккаунта — там появится код.» / «Введи код на странице «Привязать игру».» / «Готово: мод входит в аккаунт сам, пароль ему не нужен.»; closing line «Любой конфиг из витрины можно скопировать в свободный слот одной кнопкой.» with a link «Открыть витрину». - `NotFoundPage`: «Такой страницы нет» + link «На главную». - [ ] **Step 1: Failing tests** `layout.test.tsx`: ```tsx import { screen } from '@testing-library/react' import { expect, test } from 'vitest' import { routes } from '../../../routes' import { renderApp } from '../../../test/render' import { json, mockFetch } from '../../../test/fetch' test('anonymous visitor sees nav and a login link', async () => { mockFetch({ 'POST /auth/refresh': () => json({}, 401) }) renderApp(routes, '/') expect(await screen.findByRole('link', { name: 'Войти' })).toHaveAttribute('href', '/login') expect(screen.getByRole('link', { name: 'Витрина' })).toBeInTheDocument() expect(screen.getByRole('heading', { level: 1 })).toHaveTextContent('на любом компьютере') }) test('signed-in visitor sees their nick instead of login', async () => { mockFetch({ 'POST /auth/refresh': () => json({ access_token: 't' }), 'GET /me': () => json({ id: '1', email: 'a@b.c', display_nick: 'Rider', role: 'user', avatar_url: null, created_at: '' }), }) renderApp(routes, '/') expect(await screen.findByRole('link', { name: /Rider/ })).toHaveAttribute('href', '/account') expect(screen.queryByRole('link', { name: 'Войти' })).not.toBeInTheDocument() }) test('unknown path shows not found', async () => { mockFetch({ 'POST /auth/refresh': () => json({}, 401) }) renderApp(routes, '/definitely-not-here') expect(await screen.findByRole('heading', { name: 'Такой страницы нет' })).toBeInTheDocument() }) ``` `landing.test.tsx`: ```tsx import { render, screen } from '@testing-library/react' import { expect, test, vi } from 'vitest' import { CommandHero } from '../CommandHero' import { createMemoryRouter, RouterProvider } from 'react-router' import { QueryClient, QueryClientProvider } from '@tanstack/react-query' import { SessionProvider } from '../../auth/session' import { json, mockFetch } from '../../../test/fetch' test('reduced motion shows the full command at once', async () => { vi.stubGlobal('matchMedia', (q: string) => ({ matches: q.includes('reduce'), addEventListener() {}, removeEventListener() {} })) mockFetch({ 'POST /auth/refresh': () => json({}, 401) }) const router = createMemoryRouter([{ path: '/', element: }]) render( , ) expect(await screen.findByText('%config load 7KQ3M9XA')).toBeInTheDocument() expect(screen.getByText('[LoVisual] Конфиг «pvp» загружен')).toBeInTheDocument() expect(screen.getByLabelText('Пример: загрузка конфига по коду в чате игры')).toBeInTheDocument() }) ``` (jsdom has no `matchMedia`; `CommandHero` must guard `typeof window.matchMedia === 'function'` and treat "unknown" as reduced motion — safe default, also keeps other tests deterministic.) - [ ] **Step 2: Implement** `AppShell` (TopBar + `
    ` + ``), `TopBar`, `CommandHero`, `HowItWorks`, pages, `routes.tsx`, `App.tsx` per the interfaces above. `routes.tsx` for now: ```tsx import type { RouteObject } from 'react-router' import { RequireAuth } from './features/auth/RequireAuth' import { AppShell } from './shared/layout/AppShell' import HomePage from './pages/public/HomePage' import LoginPage from './pages/public/LoginPage' import RegisterPage from './pages/public/RegisterPage' import NotFoundPage from './pages/public/NotFoundPage' export const routes: RouteObject[] = [ { element: , children: [ { path: '/', element: }, { path: '/login', element: }, { path: '/register', element: }, { element: , children: [] }, // Tasks 6–8 add /link, /account, /configs { path: '*', element: }, ], }, ] ``` `shared/layout` importing from `features/auth/session` is the one allowed shared→feature edge (the shell needs the session); note it in `ARCHITECTURE.md`. The typing effect in `CommandHero`: ```tsx const COMMAND = '%config load 7KQ3M9XA' function prefersReducedMotion(): boolean { return typeof window.matchMedia !== 'function' || window.matchMedia('(prefers-reduced-motion: reduce)').matches } // inside the component const [typed, setTyped] = useState(() => (prefersReducedMotion() ? COMMAND.length : 0)) useEffect(() => { if (typed >= COMMAND.length) return const t = setInterval(() => setTyped((n) => Math.min(n + 1, COMMAND.length)), 60) return () => clearInterval(t) }, [typed >= COMMAND.length]) const done = typed >= COMMAND.length ``` Render `{COMMAND.slice(0, typed)}` + a blinking caret span (`animate-pulse`, hidden once `done`), and the confirmation line only when `done`. - [ ] **Step 3: pass; visual check** `bun run dev`, open `http://localhost:5173/` (no backend needed — refresh fails → anonymous). Check 1280px and 375px widths: no horizontal scroll, nav collapses, hero line wraps cleanly, focus ring visible when tabbing. Fix anything off before committing. - [ ] **Step 4: commit** ```bash git add frontend/src git commit -m "feat(frontend): app shell, routing and landing page with the chat-command hero" ``` --- ### Task 5A: i18n foundation (ru/en) and migrating existing strings **Why now:** every later task writes strings; converting after the fact doubles the work. **Files:** - Move: `src/App.tsx`, `src/routes.tsx` → `src/app/App.tsx`, `src/app/routes.tsx` (src/ top level becomes `main.tsx`, `index.css` + `app/`), update imports. - Create: `src/app/i18n.ts` (init), `src/app/i18next.d.ts` (typed keys), `src/shared/i18n/{common.ru.ts,common.en.ts,LanguageSwitch.tsx}`, `src/shared/i18n/tests/i18n.test.tsx` - Create per feature: `src/features//i18n/{ru.ts,en.ts}` for `auth` and `landing` now; later tasks add their own. - Modify: every component with hard-coded text (shared/ui ShareCode, shared/api/errors.ts, shared/layout, features/auth forms + validation, features/landing, pages/public/*), `src/test/setup.ts` (init i18n with `lng: 'ru'` synchronously), `index.html` (`lang` set at runtime). **Interfaces:** - One i18next namespace per feature (`common`, `auth`, `landing`, later `account`, `configs`, `showcase`, `download`, `themes`, `profile`, `link`). Russian dictionaries are `as const` objects; English ones are typed `satisfies Translation` where `type Translation = { [K in keyof T]: T[K] extends string ? string : Translation }` (exported from `shared/i18n/common.ru.ts`) — a missing or extra key in `en` is a compile error. - `app/i18n.ts`: `initI18n(lng?: 'ru' | 'en'): i18n` — `i18next.use(LanguageDetector).use(initReactI18next).init({ resources: { ru: {...namespaces}, en: {...} }, fallbackLng: 'ru', supportedLngs: ['ru','en'], ns: [...], defaultNS: 'common', interpolation: { escapeValue: false }, detection: { order: ['localStorage','navigator'], caches: ['localStorage'], lookupLocalStorage: 'lv_lang' } })`; on `languageChanged` set `document.documentElement.lang`. - `app/i18next.d.ts`: `declare module 'i18next' { interface CustomTypeOptions { defaultNS: 'common'; resources: { common: typeof commonRu; auth: typeof authRu; landing: typeof landingRu /* extended by later tasks */ } } }` so `t('auth:login.submit')` is type-checked. - `LanguageSwitch`: two-state toggle «RU / EN» in the TopBar (and footer), `aria-pressed` on the active one, calls `i18n.changeLanguage`. - `describeError(err, overrides)` takes the `t` function: `describeError(t, err, overrides)`; messages move to `common` namespace (`errors.rateLimited` with `{{seconds}}` interpolation, etc.). - Plurals via i18next plural keys (`_one/_few/_many` for ru, `_one/_other` for en). - [ ] **Step 1: Failing tests (`shared/i18n/tests/i18n.test.tsx`)** ```tsx import { render, screen } from '@testing-library/react' import userEvent from '@testing-library/user-event' import { I18nextProvider, useTranslation } from 'react-i18next' import { expect, test } from 'vitest' import { initI18n } from '../../../app/i18n' import { LanguageSwitch } from '../LanguageSwitch' function Probe() { const { t } = useTranslation('auth') return

    {t('login.submit')}

    } test('switching language re-renders strings and sets ', async () => { const user = userEvent.setup() const i18n = initI18n('ru') render() expect(screen.getByText('Войти')).toBeInTheDocument() await user.click(screen.getByRole('button', { name: 'EN' })) expect(screen.getByText('Log in')).toBeInTheDocument() expect(document.documentElement.lang).toBe('en') }) test('russian plurals', () => { const i18n = initI18n('ru') expect(i18n.t('common:time.days', { count: 1 })).toBe('1 день') expect(i18n.t('common:time.days', { count: 3 })).toBe('3 дня') expect(i18n.t('common:time.days', { count: 5 })).toBe('5 дней') }) ``` Existing tests keep asserting Russian text — they must still pass unchanged after the migration (that's the regression check). Add one English smoke test for the landing hero headline. - [ ] **Step 2: Implement; migrate every existing string; `grep -rnP '[А-Яа-яЁё]' src --include=*.tsx --include=*.ts | grep -v '/i18n/' | grep -v '/tests/'` must print nothing.** - [ ] **Step 3: test/build/lint; commit** — `feat(frontend): ru/en i18n with typed per-feature dictionaries and language switch` --- ### Task 5B: Landing v2 — the product on screen Replaces the Task 5 landing body (keep `CommandHero`'s chat line — it becomes one section). Everything is drawn in code. **Files:** new feature folders (each ≤4 files + subfolders): - `src/features/clickgui/` — `ClickGuiWindow.tsx` (window chrome + category column + module list), `ModuleCard.tsx` (toggle, expandable settings: slider/checkbox/color dot), `themeVars.ts` (`themeToCssVars(entry: ThemeEntry): CSSProperties` — maps the mod's 12 colors + 5 gradients to CSS custom properties `--gui-window-bg` …), `demo.ts` (scripted demo timeline); `tests/`. - `src/features/themes/` — `presets.generated.ts` (from the mod, see Task 5D Step 1 — generate it in THIS task, 5D reuses it), `types.ts` (`ThemeEntry`, `GradientSpec`, `argbToCss(hex: string): string` for `#AARRGGBB`), `useActiveTheme.ts` (context: active preset id, `setTheme`, persisted in `localStorage` key `lv_theme`); `tests/`. - `src/features/hud/` — `HudWidget.tsx` (draggable wrapper: pointer events, clamped to parent, keyboard-movable with arrow keys when focused), `widgets/{TargetHud,Keybinds,Potions,Watermark}.tsx`; `tests/`. - `src/features/landing/` — `CommandHero.tsx` (existing chat line, now a section), `HowItWorks.tsx` (existing, restyled), `sections/{Hero,ThemeStrip,HudPlayground,ModuleWall,ShowcaseTeaser,FaqDownload}.tsx`, `effects/{ParticleField.tsx,VoxelScene.tsx,useInView.ts}`; `tests/`. **Page composition (top to bottom):** 1. **Hero** — full-viewport. Backdrop: `VoxelScene` (procedural blocky hills + dusk sky, parallax on scroll) under `ParticleField` (canvas, ~120 soft particles, accent-tinted, `requestAnimationFrame`, paused via `IntersectionObserver` and when `prefers-reduced-motion`). Left: headline (Unbounded, clamp size) «Визуалы, которые видно» / en «Visuals you can see», lead «Бесплатный легит-мод для Minecraft 26.2: 52 визуальных модуля, облачные конфиги и темы, которые ты собираешь сам.», primary «Скачать бесплатно» (direct release link, Task 5C `DOWNLOAD_URL`) + secondary «Создать аккаунт». Right: `ClickGuiWindow` in 3D (`perspective` + `rotateX/Y` from pointer, max 8°, spring via `motion`), running `demo.ts`: a fake cursor moves, toggles «Trails», opens its settings, drags a slider, then switches theme; loop every ~12s; pauses on hover (user takes over — cards are clickable). 2. **ThemeStrip** — «Сотни оттенков. Твой — один.»: horizontal row of every preset from `presets.generated.ts` as swatch pills (window bg + accent + gradient); clicking one re-themes the hero ClickGui and the page accent live (CSS vars on `:root` via `useActiveTheme`) with a 400ms cross-fade; CTA «Собрать свою тему» → `/themes`. 3. **HudPlayground** — `VoxelScene` crop with 4 draggable HUD widgets; caption «Перетащи — так же, как в игре.»; «Сбросить» button restores positions. 4. **Cloud configs** — the existing `CommandHero` chat line + `HowItWorks` 2×2 slots, now animated in sequence when scrolled into view (`useInView`): `%config save 1` → slot fills with a pulse → code appears → second chat line `%config load 7KQ3M9XA` → «Конфиг загружен». 5. **ModuleWall** — «88 модулей. 52 — про красоту.»: dense wall of module names (from a list in `landing/i18n` — names stay as in-game, untranslated) in 4 category columns; hovering a visuals module shows a one-line description tooltip; the wall slowly auto-scrolls vertically in each column at different speeds (CSS `@keyframes` translateY on duplicated lists, `animation-play-state: paused` on hover and under reduced motion). 6. **ShowcaseTeaser** — top 3 popular configs from `GET /showcase?sort=popular` (TanStack Query); on error/empty shows 3 skeleton-styled example cards labelled «Пример» (never a broken section). 7. **FaqDownload** — FAQ accordion (`
    `; 5 questions: бесплатно ли, какие версии, нужен ли аккаунт, безопасно ли / легит, как перенести настройки) + final download band with version, Minecraft version and size (from Task 5C release data). 8. **Footer** — logo, nav, GitHub link, `LanguageSwitch`, «Не связано с Mojang или Microsoft.» **Interfaces:** - `themeToCssVars(entry)` output keys (used by ClickGui CSS): `--gui-window-bg, --gui-header, --gui-stroke, --gui-surface, --gui-surface-hover, --gui-card-on, --gui-card-off, --gui-text, --gui-text-muted, --gui-accent, --gui-accent-soft, --gui-stroke-soft`, plus `--gui-{window,header,surface,card,stroke}-gradient` as `linear-gradient(deg, start, end)` when enabled, else the flat color. - `demo.ts`: `type DemoStep = { at: number /*ms*/; action: 'move' | 'click' | 'drag' | 'theme'; target: string; value?: number | string }`, `DEMO: DemoStep[]`, `useDemo(steps, { paused }): { cursor: {x,y}, state }`. - `HudWidget` props: `{ id: string; initial: { x: number; y: number }; children: ReactNode; label: string }` — `aria-label={label}`, `tabIndex=0`, arrows move 8px. - [ ] **Step 1: Failing tests** — `themeToCssVars` maps a preset exactly (ARGB `#F012191B` → `rgba(18, 25, 27, 0.941)`); clicking a ThemeStrip swatch changes `--gui-accent` on the ClickGui root; `HudWidget` moves with ArrowRight by 8px and stays inside its parent bounds; `ParticleField` renders nothing animated (no rAF scheduled) under reduced motion (mock `matchMedia`); ModuleWall lists all four category headings; ShowcaseTeaser falls back to example cards on fetch error; hero download link points to the release URL. - [ ] **Step 2: Implement.** Performance budget: landing JS ≤ 220 kB gzip (check `bun run build` output), no layout shift from fonts (`font-display: swap` is the fontsource default; reserve hero height), 60fps particle field on a mid laptop (cap DPR at 2, ≤150 particles). - [ ] **Step 3: Visual check** with headless Firefox screenshots at 1440 and 375 (`firefox --headless --screenshot` — note it captures before long animations settle, so also verify the reduced-motion static state), both languages. Fix overflow, contrast, clipping. - [ ] **Step 4: commit** — `feat(frontend): landing v2 with live ClickGui, theme strip, HUD playground and module wall` --- ### Task 5C: Download (one click from GitHub Releases) + «Что нового» **Decisions:** the download button is a plain link to `https://github.com/${VITE_GITHUB_REPO}/releases/latest/download/lovisual.jar` — GitHub redirects straight to the file, so one click downloads the latest build with no intermediate page. This requires every release to carry an asset named exactly `lovisual.jar` (Step 1 adds the CI that guarantees it). `VITE_GITHUB_REPO=loki5512344/LoVisual-` in `frontend/.env` (and `.env.example`). The repo is private today — until it is public, the link 404s for visitors; the page shows the changelog fallback message then. **Files:** - Create: `.github/workflows/release.yml` (repo root) — on tag `v*`: JDK 25 (match `mod/build.gradle` toolchain), `./gradlew build` in `mod/`, copy the remapped jar to `lovisual.jar`, create the release with both `lovisual-.jar` and `lovisual.jar` via `softprops/action-gh-release@v2` (`generate_release_notes: true`). - Create: `src/features/download/{api.ts,DownloadButton.tsx,ReleaseNotes.tsx}`, `src/features/download/i18n/{ru,en}.ts`, `src/features/download/tests/download.test.tsx`, `src/pages/public/…` → pages/public is full (4 files) — create `src/pages/download/DownloadPage.tsx`. - Modify: `src/app/routes.tsx` (`/download`), TopBar (a «Скачать» primary button on the right, before login), Landing hero/FAQ band (use `DownloadButton`). - Add dependency: `react-markdown` (release notes are Markdown; react-markdown does not render raw HTML by default — keep it that way, no `rehype-raw`). **Interfaces:** - `api.ts`: `DOWNLOAD_URL: string`; `type Release = { tag_name: string; name: string; published_at: string; body: string; html_url: string; assets: { name: string; size: number; download_count: number }[] }`; `fetchReleases(): Promise` → `GET https://api.github.com/repos/${repo}/releases?per_page=10` (unauthenticated, 60 req/h/IP is plenty; TanStack Query `staleTime: 10 min`). - `DownloadButton` props: `{ size?: 'md' | 'lg' }` — `` styled as primary button, label «Скачать бесплатно», sub-label with latest version + size when releases loaded («v0.1.1 · 4,2 МБ»). - `ReleaseNotes`: list of releases (version, date via `Intl.DateTimeFormat(i18n.language)`, Markdown body, «Все релизы на GitHub» link). Error/empty → «Список изменений появится, когда выйдет первый публичный релиз.» - `DownloadPage` (`/download`): big button, requirements block (Minecraft 26.2, Fabric Loader 0.19.4+, Fabric API; optional Sodium/Iris — values in the download dictionary, sourced from `mod/gradle.properties`), 3-step install guide (real sequence: скачать → положить в `mods` → запустить с профилем Fabric), then `ReleaseNotes`. - [ ] **Step 1: CI workflow** (no test; validate with `actionlint` if available, otherwise careful review). Tagging/pushing is the owner's action — do not push tags. - [ ] **Step 2: Failing tests** — button href equals `https://github.com/loki5512344/LoVisual-/releases/latest/download/lovisual.jar` (with `vi.stubEnv('VITE_GITHUB_REPO', …)`); release notes render Markdown headings and do NOT render a raw `