# Vatse Motion: instruções para agentes (Codex, Claude e outros)

Você está num projeto que usa (ou é) o Vatse Motion. Siga estas regras ao criar ou editar animações.

## Como animar
1. **Prefira presets declarativos.** `<el data-vm="<preset>" data-vm-<param>="valor">`. Lista: `npx vatse-motion list`. Detalhes de um: `npx vatse-motion info <preset>`. Catálogo completo e tipado: `dist/manifest.json` (ou `llms.txt`).
2. **Use a API JS só quando o preset não existir**: `animate`, `from`, `fromTo`, `set`, `timeline`, `scene` (rolagem), `split` (texto), `smoothScroll`. Tipos: `dist/vatse-motion.d.ts`.
3. **Valide antes de concluir:** `npx vatse-motion check <pasta-ou-arquivos>`. Corrija todo ERRO; avisos indicam parâmetro com nome errado.

## Pacotes e templates
- Núcleo `vatse-motion.min.js`; presets das categorias `component` e `background` exigem `vatse-motion.components.min.js` / `vatse-motion.backgrounds.min.js` depois do núcleo (ou `vatse-motion.full.min.js`). O manifest diz o `bundle` de cada preset e o `check` acusa o script faltando.
- Para uma página nova, comece de um template em `templates/` (Estúdio, Produto, Portfólio, Restaurante, Clínica, Academia, SaaS, Evento, Imobiliária, Ônix) e troque textos, fotos e as variáveis de cor.

## Regras de qualidade
- Movimento contido e profissional: deslocamento 24-40 px, zoom 0,94-1,06, giro até 4°, desfoque até 8 px, 0,8-1,2 s com expo.out. Nada de efeito exagerado.
- Um efeito por bloco. Cenas fixas (`pin-scene`, `horizontal`, `sequence`) com moderação: no máximo 2 ou 3 por página.
- Não esconda conteúdo com CSS próprio para "esperar a animação": o Vatse Motion já cuida disso (`class="vm-cloak"` no `<html>` é opcional e tem limite de 2,5 s).
- Movimento reduzido (`prefers-reduced-motion`) e falha de JS já são tratados: o conteúdo aparece no estado final.
- Textos animados por `split`/`text-reveal` continuam acessíveis (aria-label automático); não duplique o texto.
- Tempos em segundos (`0.6`) ou ms (`600ms`); medidas em px por padrão (`40`) ou com unidade (`20%`, `50vh`).

## Para quem mantém a biblioteca
- Fonte única de verdade dos presets: `src/declarative/registry.js`. Um preset novo precisa de `name`, `aliases`, `category`, `description`, `params` (com `type`, `default`, `description`, e `values` quando `enum`), `example` e `run(el, params)` que devolve a função que desfaz.
- `npm run build` gera `dist/` (JS, CSS, manifest.json, .d.ts), `llms.txt` e `docs/presets.md`. Nunca edite esses arquivos à mão.
- `npm test` (vitest/jsdom). Teste no navegador com `demo/index.html`.