Otimizar Animações Web
Regra Principal
Meça a página real antes de editar. O objetivo não é remover o movimento; é fazer com que o trabalho fora da tela pare, o movimento visível seja retomado corretamente e a limpeza de rota/desmontagem libere recursos de longa duração.
Use o Codex Browser quando disponível, especialmente para páginas localhost. Não use o Chrome a menos que o usuário peça explicitamente.
Fluxo de Trabalho
-
Inspecione o contexto do repositório.
- Leia
AGENTS.mdou instruções locais. - Execute
git status --shortno início. - Encontre componentes de página, hooks de animação, keyframes CSS,
requestAnimationFrame,setInterval,setTimeout, componentes de canvas/WebGL/física, elementos de mídia, timelines/tweens GSAP e utilitários de visibilidade existentes. - Pesquise a limpeza de efeitos para listeners de eventos, observadores, loops RAF, intervalos, timers, scripts externos, streams de mídia, texturas/materiais/geometrias/renderizadores WebGL e trabalhos assíncronos que podem ser concluídos após a desmontagem.
- Se a árvore de trabalho estiver suja, planeje um staging restrito desde o início.
- Leia
-
Capture uma linha de base no navegador.
- Abra a rota exata que o usuário nomeou.
- Faça perfil no topo, meio da página, rodapé/conteúdo inferior e em uma viewport móvel quando o layout puder ser diferente.
- Conte animações CSS pelo
animationName,animationPlayStatee visibilidade. Inclua::beforee::after. - Inspecione elementos canvas/WebGL separadamente; o perfil CSS não prova que os loops RAF pararam.
- Registre quais nomes de animação estão sendo executados fora da tela e os proprietários DOM responsáveis.
- Para perguntas sobre memória/vazamento, registre também contagens de elementos/canvas/imagens/iframes, métricas de heap JS expostas quando disponíveis, uma amostra ociosa após 10-30 segundos e uma amostra curta de ciclo de rota. Se as APIs de heap retornarem
nullou o sandbox do navegador bloquear monkey-patching, informe isso e confie em contagens observáveis estáveis mais auditoria de código. - Mantenha os testes de estresse limitados. Uma falha de aba do navegador durante o perfil é evidência de sobrecarga, mas não atribua demais a causa a menos que seja reproduzida por um teste mínimo.
- Veja
references/browser-profiling.mdpara um avaliador reutilizável do Codex Browser.
-
Aplique o patch no menor proprietário que controla o movimento.
- Prefira um hook de revelação/visibilidade de página existente se o aplicativo tiver um.
- Caso contrário, adicione um
IntersectionObserverque alterna uma classe estável comois-offscreenem seções e elementos filhos animados. - Pause animações CSS com regras direcionadas:
main > section.is-offscreen .expensive-animation,
.expensive-animation.is-offscreen {
animation-play-state: paused !important;
}
- Para cartões repetidos ou placeholders, observe o invólucro do cartão e os descendentes animados, não o documento inteiro.
- Para faixas de marquee/ticker, pause a faixa quando sua seção estiver fora da tela.
- Para skeletons e brilhos de pseudo-elementos, inclua seletores de pausa
::beforee::afteronde necessário. - Para loops de canvas/WebGL/física, controle o loop RAF diretamente:
- Inicie quando o canvas/contêiner intersectar.
- Cancele
requestAnimationFramequando estiver fora da tela. - Retome na reentrada.
- Desconecte observadores e cancele quadros na limpeza.
- Adicione um marcador de depuração não visual como
data-animation-activequando ajudar na verificação no navegador.
- Respeite
prefers-reduced-motionse o componente já fizer isso, e evite introduzir loops de renderização React para estado de rolagem/animação. - Para endurecimento de vazamentos:
- Limpe cada timeout/intervalo criado pelo efeito.
- Cancele RAF antes da desmontagem e antes de reiniciar um loop.
- Desconecte
IntersectionObserver,ResizeObserver,MutationObservere assinaturas personalizadas. - Remova listeners globais/window/document com a mesma referência de manipulador.
- Descarte texturas, materiais, geometrias, renderizadores Three/WebGL e remova nós DOM do renderizador.
- Mate tweens/timelines GSAP para nós DOM e objetos mutáveis como uniforms de shader.
- Pare streams de mídia e pause fontes de áudio/vídeo destacadas.
- Proteja carregadores assíncronos com uma flag
isDisposede descarte recursos carregados se eles resolverem após a desmontagem. - Na limpeza do React, capture valores de
ref.currentdentro do efeito antes de retornar a limpeza se o lint avisar que a ref pode mudar. - Limite deltas de quadros de física ou simulação após pausas de visibilidade para que quadros atrasados não executem atualizações superdimensionadas.
-
Verifique o comportamento, não apenas as builds.
- Recarregue a rota e execute novamente os mesmos perfis de topo/meio/rodapé/mobile.
- Resultado alvo:
offscreenRunningCount: 0para as seções de página sob teste. - Confirme que as animações visíveis ainda são executadas ou retomadas quando roladas para a viewport.
- Confirme que loops RAF/canvas relatam inativo fora da tela e ativo na viewport, ou prove de outra forma o cancelamento a partir do estado de código/tempo de execução.
- Para auditorias de vazamento, compare ciclos de rota e amostras ociosas antes/depois. As contagens de DOM/canvas/imagens devem retornar à mesma linha de base após navegação repetida, permitindo pequenas alterações esperadas de conteúdo assíncrono.
- Exercite uma interação normal de página, como pesquisa/filtro/navegação, para que o observador não quebre o conteúdo dinâmico.
- Verifique avisos/erros no console de uma nova aba.
-
Execute verificações locais.
- Use os gates normais do repositório. Para aplicativos React/Vite, isso é frequentemente:
git diff --check
npm run lint
npm run build
- Mencione avisos não fatais conhecidos separadamente das falhas.
- Faça commit de forma restrita quando solicitado pelas instruções do repositório/usuário.
- Se houver alterações sujas não relacionadas, use um índice isolado:
rm -f /tmp/<tarefa>-index
GIT_INDEX_FILE=/tmp/<tarefa>-index git read-tree HEAD
# Aplique apenas os trechos pretendidos ao índice temporário.
GIT_INDEX_FILE=/tmp/<tarefa>-index git diff --cached --check
GIT_INDEX_FILE=/tmp/<tarefa>-index git commit -m "Pausar animações fora da tela da página <page>"
git restore --staged <files> 2>/dev/null || true
- Nunca coloque em stage arquivos amplos de uma árvore de trabalho suja a menos que cada trecho pertença à tarefa.
- Relate com evidências.
- Comece com os achados: o que ainda estava em execução, o que parecia propenso a vazamentos e o que não pôde ser medido.
- Separe os riscos da auditoria de código das medições ao vivo do navegador.
- Inclua as rotas exatas amostradas, contagens de animação fora da tela, estabilidade das contagens de DOM/canvas, resultado do ciclo de rota e verificações locais.
- Declare as limitações claramente, especialmente contadores de heap indisponíveis ou instrumentação de navegador bloqueada.
Padrões de Correção Recomendados
is-offscreenem nível de seção maisis-offscreenem nível de elemento para seções longas onde animações filhas abaixo da dobra ainda podem ser executadas.- Constantes de seletor de visibilidade compartilhadas por rota, como
COURSES_PAGE_ANIMATION_VISIBILITY_SELECTOR. - Limiares de
IntersectionObserverem torno de0.01para controle de animação. - Controle direto do loop RAF para efeitos WebGL/canvas;
animation-play-statenão pode pausar loops de renderização JavaScript. - Limites de delta de quadro para loops de física que retomam após um quadro pausado ou atrasado.
- Nós de limpeza capturados para refs React usados por efeitos GSAP/WebGL.
- Guards
isDisposedpara carregadores de imagem/vídeo/textura/dados que podem resolver após a desmontagem. - Sondagens curtas ociosas e de ciclo de rota para capturar nós DOM, canvases, iframes ou mídias não liberadas acumuladas.
Evite
- Remover todas as animações para fazer o perfil passar.
- Pausar o movimento herói visível porque um seletor ancestral é muito amplo.
- Assumir que
animation-play-statecobre pseudo-elementos ou loops RAF JavaScript. - Confiar em uma única medição no topo da página em páginas longas.
- Tratar contadores de heap indisponíveis como prova de que não há vazamento de memória.
- Executar loops de estresse ilimitados no navegador; use ciclos limitados e registre falhas sem exagerar a causalidade.
- Usar capturas de tela sozinhas como prova de desempenho.
- Deixar trechos locais não relacionados acompanharem no commit.