Kino•shka

Каталог фильмов — SPA с лентой на главной, поиском, фильтрами, страницами фильмов (обзор, каст, медиа), списком избранного (хранится в localStorage браузера, без синхронизации между устройствами), разделом «Popular this week» (/popular) с позициями фильмов в рейтинге и их изменением, и разделом «Recommended for you» (/recommendations) — рекомендации, вычисленные чистым правилом поверх избранного (топ-3 жанра + средний рейтинг избранного), и профилем (/profile) — локальное имя (хранится в localStorage, без бэкенда), быстрые ссылки на избранное/популярное/рекомендации и выбор темы Light/Dark/System, а также страницей персоны (/person/:id) — фото, дата рождения/возраст, профессии, фильмография со ссылками на карточки фильмов и факты, доступной по клику на актёра/члена съёмочной группы со страницы фильма.

Стек

• React 19 + TypeScript 7 + Vite 8
• React Router 7 — клиентская маршрутизация
• React Compiler — автоматическая мемоизация (babel-plugin-react-compiler); ручные useMemo / useCallback / memo не нужны
• Vitest + Testing Library + MSW — юнит и интеграционные тесты, мокирование API-запросов
• Playwright + axe-core — E2E-тесты в реальном браузере против production preview-сборки (vite preview) и реального API, с a11y-проверкой (AxeBuilder) в каждом сценарии; отдельный mobile-viewport project (devices['iPhone 13']) на /, /search, /movie/:id
• Zod — валидация данных (localStorage, API-границы)
• oxlint — Rust-линтер (TS/React/jsx-a11y правила)
• husky + lint-staged + commitlint — pre-commit линтинг и conventional commits (pnpm commit)
• Sentry (@sentry/react + @sentry/vite-plugin) — error tracking и Performance-трейсинг (tracesSampleRate=0.2, параметризованные роуты типа /movie/:id группируются в один transaction через reactRouterBrowserTracingIntegration/wrapCreateBrowserRouter) в prod-сборке, аплоад source maps на этапе билда; alert/dashboard-провижининг as code (make sentry-telemetry) поверх sentry CLI
• Plausible — privacy-friendly event tracking (page view, search submitted, filter changed, favorite added) в prod-сборке; Core Web Vitals (LCP/INP/CLS) теперь собираются через Sentry Performance (см. выше), а не через отдельный web-vitals-пайплайн

Команды

make dev              # dev-сервер с HMR
make build            # проверка типов (tsc -b) + production-сборка
make lint             # oxlint по всем TS/TSX-файлам
make preview          # раздача production-сборки локально
make test             # запустить тесты один раз
make test-watch       # тесты в watch-режиме
make coverage         # отчёт покрытия
make e2e              # E2E-тесты (Playwright) против production preview-сборки
make e2e-install      # установить браузеры Playwright (chromium + webkit)
make lighthouse       # Lighthouse CI dev-smoke локально (не авторитетный источник порогов, см. AGENTS.md)
make generate-api     # регенерировать API-клиент из OpenAPI-спецификации
make check            # format-check + lint + build (полная проверка)
make hooks            # установить git-хуки husky
make audit            # pnpm audit (prod-зависимости, high severity)
make analyze          # визуализация состава бандла (dist/stats.html)
make size             # бюджеты размера бандла (size-limit)
make knip             # детектор неиспользуемого кода/зависимостей
make sentry-telemetry # провижининг Sentry alert/dashboard as code (см. sentry-telemetry.config.ts)
make clean            # удалить dist и node_modules

Архитектура

Проект следует Feature-Sliced Design:

src/
├── app/        # провайдеры, роутер, глобальные стили
├── pages/      # компоненты уровня роута
├── widgets/    # крупные переиспользуемые секции UI (header, mobile-chrome, movie-rail, search-sidebar)
├── features/   # интерактивные фичи (catalog-filter, favorites, watched, watchlist, theme, recommendations, profile)
├── entities/   # бизнес-объекты (movie, person — типы, данные, UI)
└── shared/     # утилиты и примитивы (lib/, ui/)

Направление импортов: pages → widgets → features → entities → shared. Импорты вверх по слоям запрещены.

Адаптивность

Mobile-first: у каждой страницы/виджета один компонент и один CSS-модуль — мобильная раскладка безусловная (базовая), десктопные переопределения идут в блоках @media (min-width: 720px) поверх неё. Пары *Desktop/*Mobile не используются. Breakpoint: 720px (MOBILE_BREAKPOINT, src/shared/lib/viewport/useViewport.ts).

Хук useViewport остался, но его вызовы намеренно сужены до двух точечных JS-развилок — случаев, когда разница не CSS-вариант оформления, а выбор, какой компонент монтировать (и его сайд-эффекты):

• src/app/layouts/AppLayout.tsx — выбирает Header (@widgets/header) или MobileHeader+BottomNav (@widgets/mobile-chrome).
• src/pages/search/ui/Search/Search.tsx — выбирает SearchSidebar (@widgets/search-sidebar) или мобильный filter-bar + BottomSheet.

Остальные бывшие useViewport()-развилки (старые *Page.tsx, стрелки скролла в MovieRail и т.п.) свелись к чистому CSS.

Структура компонентов

Каждый компонент живёт в собственной директории с CSS-модулем:

ComponentName/
├── index.tsx
└── ComponentName.module.css

Каждый слайс widgets/ и features/ предоставляет публичный API через index.ts в корне слайса. Всегда импортируй через него, не через внутренние пути:

import { Header } from '@widgets/header' // ✓
import { Header } from '@widgets/header/ui/Header' // ✗

Соглашения

• Типы: использовать type, не interface
• TypeScript: включены noUnusedLocals, noUnusedParameters, erasableSyntaxOnly — enum и namespace запрещены
• Стили: CSS Modules (ComponentName.module.css), hover-состояния через :hover, не через useState
• Иконки: SVG-спрайт public/icons.svg; ссылка через <use href="/icons.svg#<id>" />
• Шрифты: Instrument Serif, Instrument Sans, JetBrains Mono (Google Fonts, загружаются в index.html) — новые шрифты не добавлять

Sentry MCP

В корне репозитория закоммичен .mcp.json с project-scoped Sentry MCP-сервером (https://mcp.sentry.dev/mcp). После клонирования репозитория Claude Code предложит авторизовать этот MCP-сервер через OAuth — подтвердите авторизацию, чтобы получить доступ к Sentry-инструментам (issues, alerts, dashboards) прямо из сессии. Опционально можно локально (не в коммите) сузить url до https://mcp.sentry.dev/mcp/mycomp-ey/kinoshka, ограничив MCP-сервер конкретными org/project.