feat: taste onboarding for new listeners (M6)

- GET /onboarding offers the library's top artists (with album covers)
  and genres and says whether to show it (not done and < 10 plays);
  PUT /me/onboarding stores the choice or a skip (migration 00009).
- The recommender seeds the taste from it while the user has fewer than
  30 scored tracks: chosen artists' tracks +1, chosen genres +0.5.
- Web: onboarding replaces the wave on the home page until done or
  skipped; artist grid with covers, genre chips, at least 3 artists.
- e2e journey and the recommender DB test cover it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

apps/web/src/pages/HomePage.tsx

@@ -1,5 +1,5 @@
 import { unwrap } from '@pipu/core';
-import { useQuery } from '@tanstack/react-query';
+import { useQuery, useQueryClient } from '@tanstack/react-query';
 import { useState } from 'react';
 import { useTranslation } from 'react-i18next';
 
@@ -24,6 +24,7 @@ import {
 import { cx, FormError, Icon } from '../shared/ui/ui';
 import { WaveButton } from '../widgets/wave/WaveButton';
 import s from './home.module.css';
+import { Onboarding } from './Onboarding';
 
 /** Иконки Material Symbols по именам из /wave/options. */
 const ICONS: Record<string, string> = {
@@ -44,8 +45,28 @@ const WAVE_COLORS: [string, string, string] = ['#2F80FF', '#7C5CFF', '#35D3FF'];
 
 type Tr = (key: string) => string;
 
-/** Главная (раскладка Center): кнопка «Моя волна» и под ней выбор занятия и настроения. */
+/** Главная: для нового пользователя без истории — сначала онбординг вкуса, затем волна. */
 export function HomePage() {
+  const session = useSession();
+  const queryClient = useQueryClient();
+  const onboarding = useQuery({
+    queryKey: ['onboarding'],
+    queryFn: async () => unwrap(await session.client.GET('/api/v1/onboarding')),
+    staleTime: Infinity,
+  });
+  if (onboarding.data?.required) {
+    return (
+      <Onboarding
+        options={onboarding.data}
+        onDone={() => queryClient.setQueryData(['onboarding'], { ...onboarding.data, required: false })}
+      />
+    );
+  }
+  return <WaveHome />;
+}
+
+/** Главная (раскладка Center): кнопка «Моя волна» и под ней выбор занятия и настроения. */
+function WaveHome() {
   const { t } = useTranslation();
   const tr = t as unknown as Tr;
   const session = useSession();

apps/web/src/pages/Onboarding.tsx

@@ -0,0 +1,113 @@
+import type { components } from '@pipu/api-client';
+import { unwrap } from '@pipu/core';
+import { useMutation } from '@tanstack/react-query';
+import { useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { useSession } from '../app/session';
+import { Cover } from '../entities/catalog';
+import { useErrorText } from '../shared/lib/errors';
+import { checkIcon } from '../shared/ui/icons';
+import { Button, cx, FormError, Icon } from '../shared/ui/ui';
+import s from './onboarding.module.css';
+
+type Options = components['schemas']['Onboarding'];
+
+/** Минимум исполнителей, чтобы волне было от чего оттолкнуться. */
+const MIN_ARTISTS = 3;
+
+/**
+ * Онбординг вкуса (docs/recommendations.md#7): исполнители и жанры библиотеки — начальный вкус «Моей волны»,
+ * пока своей истории почти нет. Пропуск тоже запоминается: второй раз не спросим.
+ */
+export function Onboarding({ options, onDone }: { options: Options; onDone: () => void }) {
+  const { t } = useTranslation();
+  const session = useSession();
+  const errorText = useErrorText();
+  const [artists, setArtists] = useState<Set<string>>(new Set());
+  const [genres, setGenres] = useState<Set<string>>(new Set());
+  const save = useMutation({
+    mutationFn: async (skip: boolean) =>
+      unwrap(
+        await session.client.PUT('/api/v1/me/onboarding', {
+          body: skip ? { artist_ids: [], genres: [] } : { artist_ids: [...artists], genres: [...genres] },
+        }),
+      ),
+    onSuccess: onDone,
+  });
+  // Функциональное обновление: быстрые нажатия подряд не теряют выбор.
+  const toggle = (update: (fn: (prev: Set<string>) => Set<string>) => void, key: string) =>
+    update((prev) => {
+      const next = new Set(prev);
+      if (next.has(key)) next.delete(key);
+      else next.add(key);
+      return next;
+    });
+  const enough = artists.size >= MIN_ARTISTS || (artists.size > 0 && genres.size > 0);
+
+  return (
+    <div className={s.page}>
+      <header className={s.head}>
+        <h1>{t('onboarding.title')}</h1>
+        <p>{t('onboarding.subtitle')}</p>
+      </header>
+
+      <section aria-label={t('onboarding.artists')}>
+        <h2 className={s.label}>{t('onboarding.artists')}</h2>
+        <div className={s.artists}>
+          {options.artists.map((a) => {
+            const on = artists.has(a.id);
+            return (
+              <button
+                key={a.id}
+                type="button"
+                className={cx(s.artist, on && s.on)}
+                aria-pressed={on}
+                onClick={() => toggle(setArtists, a.id)}
+              >
+                <span className={s.avatar}>
+                  <Cover album={{ id: a.id, cover_url: a.cover_url, cover_colors: a.cover_colors }} size={96} round />
+                  {on && (
+                    <span className={s.check}>
+                      <Icon src={checkIcon} size={22} />
+                    </span>
+                  )}
+                </span>
+                <span className={s.name}>{a.name}</span>
+              </button>
+            );
+          })}
+        </div>
+      </section>
+
+      {options.genres.length > 0 && (
+        <section aria-label={t('onboarding.genres')}>
+          <h2 className={s.label}>{t('onboarding.genres')}</h2>
+          <div className={s.genres}>
+            {options.genres.map((g) => (
+              <button
+                key={g.name}
+                type="button"
+                className={s.genre}
+                aria-pressed={genres.has(g.name)}
+                onClick={() => toggle(setGenres, g.name)}
+              >
+                {g.name}
+              </button>
+            ))}
+          </div>
+        </section>
+      )}
+
+      <FormError>{save.error ? errorText(save.error) : null}</FormError>
+      <div className={s.actions}>
+        <Button variant="ghost" busy={save.isPending && save.variables} onClick={() => save.mutate(true)}>
+          {t('onboarding.skip')}
+        </Button>
+        <Button variant="primary" busy={save.isPending && !save.variables} disabled={!enough} onClick={() => save.mutate(false)}>
+          {enough ? t('onboarding.done') : t('onboarding.pick_more', { count: MIN_ARTISTS - artists.size })}
+        </Button>
+      </div>
+    </div>
+  );
+}

apps/web/src/pages/onboarding.module.css

@@ -0,0 +1,124 @@
+.page {
+  display: flex;
+  flex-direction: column;
+  gap: 28px;
+  max-width: 1100px;
+  margin: 0 auto;
+  animation: pipuIn 0.2s ease-out;
+}
+
+.head h1 {
+  margin: 0 0 8px;
+  font-family: var(--font-display);
+  font-size: 32px;
+  font-weight: 600;
+  letter-spacing: -0.02em;
+}
+
+.head p {
+  margin: 0;
+  color: var(--text2);
+}
+
+.label {
+  margin: 0 0 14px;
+  font-size: 13px;
+  font-weight: 700;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  color: var(--text3);
+}
+
+.artists {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(120px, 1fr));
+  gap: 18px 12px;
+}
+
+.artist {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 10px;
+  padding: 10px 6px;
+  border-radius: var(--radius-lg);
+  text-align: center;
+}
+
+.artist:hover {
+  background: var(--hover);
+}
+
+.avatar {
+  position: relative;
+  border-radius: 50%;
+  transition:
+    box-shadow 0.15s,
+    transform 0.15s;
+}
+
+.on .avatar {
+  box-shadow:
+    0 0 0 3px var(--bg),
+    0 0 0 5px var(--accent);
+  transform: scale(0.96);
+}
+
+.check {
+  position: absolute;
+  right: -2px;
+  bottom: -2px;
+  display: grid;
+  place-items: center;
+  width: 32px;
+  height: 32px;
+  border-radius: 50%;
+  background: var(--accent);
+  color: #fff;
+  box-shadow: var(--glow);
+}
+
+.name {
+  font-size: 14px;
+  font-weight: 600;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  max-width: 100%;
+}
+
+.genres {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
+}
+
+.genre {
+  height: 38px;
+  padding: 0 16px;
+  border-radius: var(--radius-pill);
+  border: 1px solid var(--line);
+  background: var(--surface2);
+  font-weight: 600;
+  font-size: 14px;
+}
+
+.genre[aria-pressed='true'] {
+  background: var(--accent);
+  border-color: var(--accent);
+  color: #fff;
+  box-shadow: var(--glow);
+}
+
+.actions {
+  position: sticky;
+  bottom: 16px;
+  display: flex;
+  justify-content: flex-end;
+  gap: 10px;
+  padding: 12px;
+  border-radius: var(--radius-lg);
+  border: 1px solid var(--line2);
+  background: var(--glass);
+  backdrop-filter: blur(28px) saturate(1.3);
+}