# Документация Snow Manager

## Обзор

Класс `SnowManager` предоставляет обертку вокруг библиотеки `magic-snowflakes` с дополнительными функциями, такими как автоматическая пауза/возобновление, интеграция с темами и простая настройка.

## Быстрый старт

```html
<!-- Базовое подключение -->
<script src="node_modules/hrenpack-theme-style/dist/snow.js"></script>

<!-- С настройками через data-атрибуты -->
<script
        src="node_modules/hrenpack-theme-style/dist/snow.js"
        data-count="100"
        data-color="#ffffff"
        data-min-size="5"
        data-max-size="15"
        data-speed="2"
        data-rotation
        data-z-index="9999"
        data-no-optimize>
</script>
```
> ⚠️ **Важно:** Скрипт должен загружаться синхронно (без `async`/`defer`).

### Варианты инициализации

**Автоматическая (по умолчанию):**
```html
<script src="snow.js" data-count="100"></script>
```

**Ручная (с data-no-init):**
```html
<script src="snow.js" data-no-init></script>
<script>
// Инициализируем когда нужно
window.snowManager = new SnowManager({
    count: 100,
    color: '#ffffff'
});
</script>
```

## Справочник API
### Класс SnowManager
#### Конструктор
```typescript
new SnowManager(options?: SnowOptions)
```

#### Статические методы
- `fromScriptDataset()` - Создает экземпляр из data-атрибутов элемента script

#### Методы экземпляра

- `pause()` - Приостанавливает анимацию снегопада
- `play()` - Возобновляет анимацию снегопада
- `toggle()` - Переключает состояние (вкл/выкл)
- `destroy()` - Полностью удаляет снегопад и освобождает ресурсы

> **🔄 Пересоздание:** Изменение любого параметра через сеттер приводит к полному пересозданию экземпляра Snowflakes.

#### Свойства
Все свойства являются геттерами/сеттерами, синхронизированными с базовым экземпляром **snowflake**:
- `count` - Количество снежинок
- `color` - Цвет снежинок
- `minOpacity`, `maxOpacity` - Диапазон прозрачности
- `minSize`, `maxSize` - Диапазон размеров
- `speed` - Множитель скорости падения
- `rotation` - Включить вращение
- `wind` - Включить эффект ветра
- `zIndex` - CSS z-index
- `optimize` - Включит/выключить оптимизацию (отключение анимации, если вкладка неактивна)

## События
Снегопад автоматически реагирует на:
- Изменения видимости страницы (visibilitychange)
- События фокуса/размытия окна
- Изменения системной темы (через CSS-переменные)

## Архитектура

### Управление параметрами
При изменении любого свойства происходит следующее:

1. Получение текущих параметров из `snow.params`
2. Создание нового конфига с обновленным значением
3. Уничтожение старого экземпляра `snow.destroy()`
4. Создание нового экземпляра `new Snowflakes(newConfig)`

### Цикл жизни экземпляра
Инициализация → Выполнение → Приостановка/Возобновление → Уничтожение

### Data-атрибуты vs программное управление
| Способ          | Параметры                                            | Время применения       |
|-----------------|------------------------------------------------------|------------------------|
| Data-атрибуты   | count, color, size, opacity, speed, rotation, zIndex | При загрузке страницы  |
| Программное API | Все параметры, включая wind, autoResize, container   | В любой момент времени |


## Безопасность и производительность

#### Защита от XSS
При использовании data-атрибутов все значения проходят валидацию:
- Числовые параметры проверяются на корректность
- Строковые значения (color) санитизируются
- Булевые параметры обрабатываются безопасно

#### Оптимальные настройки для разных устройств:
| Устройство | count | maxSize | speed | optimize |
|------------|-------|---------|-------|----------|
| Десктоп (мощный) | 150 | 25 | 2 | true |
| Десктоп (обычный) | 80 | 20 | 1 | true |
| Планшет | 60 | 15 | 1 | true |
| Мобильный | 40 | 12 | 1 | true |
| Старые устройства | 20 | 10 | 0.5 | true |

#### Мониторинг производительности:
```javascript
// Проверка FPS снегопада
let frameCount = 0;
let lastTime = performance.now();

function monitorPerformance() {
    frameCount++;
    const currentTime = performance.now();
    if (currentTime - lastTime >= 1000) {
        const fps = Math.round((frameCount * 1000) / (currentTime - lastTime));
        console.log(`Snow FPS: ${fps}`);
        if (fps < 30) {
            console.warn('Низкий FPS. Рекомендуется уменьшить количество снежинок.');
        }
        frameCount = 0;
        lastTime = currentTime;
    }
    requestAnimationFrame(monitorPerformance);
}
monitorPerformance();
```

### Рекомендации по настройке
| Параметр     | Рекомендуемое значение               | Влияние на производительность          |
|--------------|--------------------------------------|----------------------------------------|
| `count`      | ≤ 150 на десктопе, ≤ 80 на мобильных | Прямо пропорционально нагрузке         |
| `types`      | 3-6                                  | Увеличивает потребление памяти         |
| `speed`      | 1-3                                  | Влияет на частоту перерисовки          |
| `autoResize` | `true`                               | Автоматическая оптимизация при ресайзе |

### Оптимизации
- **Автоматическая пауза:** При скрытии вкладки или потере фокуса
- **Smart rendering:** Использует аппаратное ускорение, когда доступно
- **Ресайз:** При `autoResize=true` автоматически адаптируется к размеру контейнера

### Ограничения
- **Пересоздание экземпляра:** Изменение параметров вызывает полную реинициализацию
- **Мобильные устройства:** Рекомендуется уменьшать `count` и `maxSize`
- **Старые браузеры:** Нет поддержки в Internet Explorer и Legacy Edge

## Примеры использования
### Программное управление
```javascript
// Получение текущих параметров
console.log(snowManager.count); // 50
console.log(snowManager.color); // "#5ecdef"

// Изменение параметров
snowManager.count = 100;
snowManager.speed = 2;
snowManager.color = "#ff0000";

// Управление состоянием
snowManager.pause();
setTimeout(() => snowManager.play(), 5000);
```

### Интеграция с интерфейсом
```html
<div class="snow-controls">
    <button onclick="snowManager.toggle()">Вкл/Выкл</button>
    <input type="range" min="1" max="200" 
           oninput="snowManager.count = this.value">
    <input type="color" 
           onchange="snowManager.color = this.value">
</div>
```

## Отладка и устранение неполадок
### Частые ошибки
1. **`document.currentScript is null`**
    - **Причина:** Скрипт загружается асинхронно
    - **Решение:** Уберите атрибуты `async`/`defer`
2. **Высокая загрузка ЦП**
    - **Решение:** Уменьшите `count` и/или `speed`

## Консольная отладка
```javascript
// Проверка состояния
console.log(snowManager.isActive); // true/false
console.log(snowManager.snow?.params); // Текущие параметры

// Принудительное обновление
snowManager.destroy();
snowManager = new SnowManager({ count: 50, color: '#fff' });
```