> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bedolagam.ru/llms.txt
> Use this file to discover all available pages before exploring further.

# Анимированные фоны

> Настройка анимированных фонов Cabinet на базе Aceternity UI

## Обзор

Cabinet включает библиотеку из **15 анимированных фонов**, работающих как полноэкранные визуальные эффекты за контентом. Фоны построены на основе компонентов [Aceternity UI](https://ui.aceternity.com/), оптимизированных для производительности в браузере и Telegram MiniApp.

<CardGroup cols={3}>
  <Card title="15 эффектов" icon="palette">
    CSS, Canvas и SVG-анимации на выбор
  </Card>

  <Card title="Live-превью" icon="eye">
    Предпросмотр прямо в админке при настройке
  </Card>

  <Card title="Мобильная оптимизация" icon="mobile">
    Автоматическое снижение нагрузки на мобильных устройствах
  </Card>
</CardGroup>

## Доступные фоны

### CSS-анимации

| Тип                    | Описание                                   | Настройки                                         |
| ---------------------- | ------------------------------------------ | ------------------------------------------------- |
| **Aurora**             | Градиентное свечение с плавными переливами | 3 цвета, скорость (медленно / нормально / быстро) |
| **Gradient Animation** | Анимированный многоцветный градиент        | 5 цветов, интерактивность мышью, размер           |
| **Grid**               | Сетка с анимацией                          | Размер ячейки, цвет                               |
| **Dots**               | Точечный паттерн                           | Размер ячейки, размер точки                       |
| **Spotlight**          | Двигающийся луч света                      | Цвет, размер                                      |

### Canvas-анимации

| Тип                  | Описание                   | Настройки                                      |
| -------------------- | -------------------------- | ---------------------------------------------- |
| **Sparkles**         | Мерцающие частицы          | Плотность, размер, скорость                    |
| **Vortex**           | Спиральный вихрь частиц    | Количество, радиус, оттенок, скорость          |
| **Shooting Stars**   | Падающие звёзды            | Цвет звёзд и хвоста, плотность, скорость       |
| **Wavy**             | Волновое искажение         | Скорость, ширина волны, размытие, прозрачность |
| **Background Lines** | Плавные линии              | Количество, цвет, скорость, толщина            |
| **Ripple**           | Расходящиеся круги         | Цвет, количество, скорость                     |
| **Boxes**            | Вращающиеся кубики в сетке | Строки, столбцы, цвет                          |
| **Meteors**          | Падающие метеоры           | Количество, цвет                               |

### SVG-анимации

| Тип                  | Описание                                  | Настройки                   |
| -------------------- | ----------------------------------------- | --------------------------- |
| **Background Beams** | 50 лучей с градиентом cyan→purple→magenta | Только глобальные настройки |
| **Beams Collision**  | Лучи со столкновениями                    | Только глобальные настройки |

## Настройка через админку

Управление фонами доступно в **Настройки → Фоны** в админ-панели Cabinet.

<Steps>
  <Step title="Включите анимацию">
    Переключатель «Анимация включена» активирует фон для всех пользователей.
  </Step>

  <Step title="Выберите тип">
    Кнопки сгруппированы по категориям (CSS / Canvas / SVG). При выборе тип сразу применяется в превью.
  </Step>

  <Step title="Настройте параметры">
    Каждый тип имеет свои настройки: цвета, скорость, плотность частиц и другие. Изменения видны в live-превью.
  </Step>

  <Step title="Глобальные настройки">
    Для любого типа доступны общие параметры.
  </Step>
</Steps>

### Глобальные параметры

| Параметр              | Диапазон   | По умолчанию | Описание                                                           |
| --------------------- | ---------- | ------------ | ------------------------------------------------------------------ |
| Прозрачность          | 0.1 – 1.0  | 1.0          | Общая прозрачность фона                                            |
| Размытие              | 0 – 20 px  | 0            | Гауссово размытие поверх анимации                                  |
| Снижение на мобильных | Вкл / Выкл | Вкл          | Урезает количество частиц и отключает интерактивность на мобильных |

## Производительность

Все фоны оптимизированы для работы без просадок:

* **Portal-рендеринг** — фон рендерится через `createPortal` на `document.body` с `z-index: -1`, полностью исключая implicit compositing между фоном и UI-элементами
* **GPU-ускорение** — CSS-анимации используют `transform` и `will-change` для композиторного слоя
* **CSS containment** — `contain: strict` изолирует перерисовки фона от остального UI
* **Lazy-загрузка** — JS-чанк фона загружается отложенно через `React.lazy`
* **Предзагрузка** — при повторных визитах чанк подгружается из localStorage-кэша ещё до рендера React
* **FPS-троттлинг** — `useAnimationLoop` хук: 30 FPS на мобильных / 60 FPS на десктопе, автопауза при сворачивании вкладки (Page Visibility API) и деактивации Telegram MiniApp
* **Мобильный режим** — количество частиц уменьшается, DPR ограничивается до 1.5, интерактивные эффекты отключаются, blur ограничен 4px
* **`prefers-reduced-motion`** — анимация полностью отключается при системной настройке «Уменьшить движение»
* **Валидация конфигурации** — проверка типа анимации по allowlist, числовые ограничения, лимит размера JSON-конфигурации

### SVG Beams

Компонент Background Beams использует чистые CSS-анимации `stroke-dashoffset` без изменения `opacity` — это предотвращает перерисовку (repaint) всей страницы. Из 50 лучей одновременно анимируются только 17, остальные отображаются статически с минимальной прозрачностью.

### Canvas Boxes

Компонент Boxes переписан с 225 отдельных DOM-элементов на единый `<canvas>`. Это исключает проблему re-compositing'а, когда hover-эффекты на контенте вызывали перерисовку всех 225 регионов. Canvas-содержимое пиксельное и не подвержено влиянию DOM-событий.

## API

| Метод | Путь                                 | Описание                              |
| ----- | ------------------------------------ | ------------------------------------- |
| GET   | `/cabinet/branding/animation-config` | Получить текущую конфигурацию         |
| PATCH | `/cabinet/branding/animation-config` | Обновить конфигурацию (админ)         |
| GET   | `/cabinet/branding/animation`        | Проверить, включена ли анимация       |
| PATCH | `/cabinet/branding/animation`        | Включить / выключить анимацию (админ) |

### Формат конфигурации

```json theme={null}
{
  "enabled": true,
  "type": "aurora",
  "settings": {
    "color1": "#00d2ff",
    "color2": "#7a2aff",
    "color3": "#ff0080",
    "speed": "normal"
  },
  "opacity": 1.0,
  "blur": 0,
  "reducedOnMobile": true
}
```

## Кэширование

Конфигурация фона кэшируется в `localStorage` (`cabinet_animation_config`). При загрузке страницы Cabinet сначала использует кэш для мгновенного отображения, затем в фоне запрашивает актуальную конфигурацию с сервера. Это обеспечивает отображение фона без задержки даже при медленном соединении.

## Отключение

Для полного отключения анимированных фонов:

1. **Через админку** — выключите переключатель «Анимация включена» в разделе настроек
2. **Через API** — `PATCH /cabinet/branding/animation` с `{"enabled": false}`
3. **Тип «none»** — выберите тип «Без анимации» для явного отключения