# AGENTS.md — как использовать этот каталог (для ИИ-агентов)

Каталог анимаций для лендингов: 8 категорий, 111 карточек. Каждая карточка — самодостаточный сниппет + описание + источник + подсказка по применению. Всё проверено в реальном Chromium (рендер, console errors, видимость контента).

## Файлы

| Путь | Что внутри |
|---|---|
| `catalog.json` | **Главный машинночитаемый файл.** `{ count, categories, cards: [...] }` — все карточки со всеми полями |
| `cards/<id>.md` | Человекочитаемая карточка: превью, код, заметки |
| `snippets/<id>.html` | Готовый standalone-файл демо (открывается в браузере как есть) |
| `previews/<id>.mp4` | Анимированное превью (H.264, 480×320, 25 fps) — основной формат для галереи (постер — jpg 960×640) |
| `previews/<id>.webp` / `.jpg` | WebP-запас (для markdown/GitHub) и статичный постер |
| `previews/manifest.json` | Только id → путь/триггеры для записи превью (служебное) |
| `previews/qa_results.json` | Отчёт QA: ошибки рендера, невидимый контент (машинночитаемый) |
| `previews/report.json` | Отчёт захвата превью: статус по каждому id |
| `research/SCHEMA.md` | Контракт карточки (если добавляешь новые) |
| `research/agent-*.json` | Сырые результаты ресёрча (источник правды для merge) |
| `tools/` | Пайплайн: merge → QA → capture превью → сборка сайта |

## Поля карточки (catalog.json)

```jsonc
{
  "id": "entr-fade-in-up",          // уникальный, с префиксом категории
  "name": "Fade In Up",             // стандартный англ. термин
  "name_ru": "Появление снизу",
  "category": "entrance",           // см. категории ниже
  "tags": ["on-scroll","fade"],     // для фильтрации/поиска
  "summary": "...",                 // 1–2 предложения: что происходит
  "effect": "...",                  // механика и тайминги
  "when_to_use": "...",             // где уместно на лендинге
  "tech": ["css","vanilla-js"],     // технологии
  "dependencies": [],               // напр. ["gsap 3.13 + ScrollTrigger (CDN)"]
  "difficulty": "easy",             // easy | medium | hard
  "code": { "html": "...", "css": "...", "js": "..." },
  "source": { "name": "...", "url": "...", "domain": "..." },
  "performance": "...",             // влияние на рендеринг
  "a11y": "...",                    // как учтён prefers-reduced-motion
  "browser_support": "...",
  "ai_use": "One-line ENGLISH instruction for an AI agent building a landing.",
  "preview": { "scroll": false, "mouse": null, "wait_ms": 2500, "bg": "#0b0d12" }
}
```

Категории и префиксы id: `entrance` (появления), `scroll` (скролл-сценарии), `text` (типографика), `hover` (hover/курсор), `navigation` (навигация и UI), `background` (фоны), `physics3d` (физика/3D/морфинг), `technique` (библиотеки и инженерные техники).

## Рабочий процесс агента-верстальщика

1. Прочитай `catalog.json` (или отфильтруй заранее: `category`, `tags`, `difficulty: easy`).
2. Выбери 3–7 карточек под задачу: hero-появление, скролл-эффект, hover, фон. Не больше одной «тяжёлой» (WebGL/particles) на первый экран.
3. Возьми `code.html/css/js` как есть; для standalone-превью открой `snippets/<id>.html`.
4. Если заполнен `dependencies` — подключи библиотеку с CDN из поля (пин версии сохраняй).
5. Собери страницу. Убедись, что каждый `ai_use`/`when_to_use` соответствует месту (hero vs. секция vs. CTA).
6. **Обязательно** сохрани `prefers-reduced-motion`-ветку из карточки и не дублируй анимации конкурирующих элементов (два reveal на одном заголовке = визуальный шум).

## Правила качества (извлечены из ресёрча)

- Анимируй только `transform` и `opacity` (композитор), `filter/blur` — точечно.
- Длительности: вход 400–700ms, hover 120–250ms, циклы 4–12s. Easing: `cubic-bezier(.2,.7,.2,1)`, `ease-out`; bounce — осознанно.
- Одна смысловая анимация на блок; stagger 60–120ms между детьми.
- Scroll-эффекты не должны красть управление (никакого scroll-jacking без нужды).
- Каждая карточка уже содержит reduced-motion-фолбэк — не удаляй его.

## Поиск под задачу (примеры)

- «hero появляется при загрузке» → `category=entrance`, tags `on-load`
- «слики при скролле» → `category=scroll`, tags `parallax|sticky`
- «оживить цифры метрик» → `category=text`, id `text-count-up-odometer`
- «кнопка CTA поинтереснее» → `category=hover`
- «фон для hero» → `category=background` (сначала `bg-gradient-shift`, тяжёлое — потом)
- «переход между страницами» → `category=navigation`, tags `view-transitions`
- «стек под лендинг на GSAP» → `category=technique`

## Регенерация пайплайна

```sh
python3 tools/merge_catalog.py            # research/*.json -> catalog.json + snippets/
node tools/qa_cards.js                    # рендер-проверка, постеры, QA-отчёт
node tools/capture_previews.js            # анимированные webp-превью (нужен playwright-core)
python3 tools/build_site.py               # cards/*.md + index.html
```

Требуется: Chromium из `../landing-research/node_modules/playwright-core` (см. `tools/capture_previews.js`, переменная `CHROME_BIN`), `ffmpeg` с `libwebp`.

## Лицензии и этика

Код пересобран по документации и референсам (ссылки в каждой карточке). Перед продакшеном проверь лицензию библиотек (GSAP — GreenSock standard, Three.js — MIT, Lenis — MIT, Swiper — MIT и т.д.) и условия источников.