Optimizar Animaciones Web
Regla Principal
Mide la página real antes de editar. El objetivo no es eliminar el movimiento; es hacer que el trabajo fuera de pantalla se detenga, el movimiento visible se reanude correctamente y la limpieza de rutas/desmontaje libere recursos de larga duración.
Usa Codex Browser cuando esté disponible, especialmente para páginas en localhost. No uses Chrome a menos que el usuario lo solicite explícitamente.
Flujo de Trabajo
-
Inspecciona el contexto del repositorio.
- Lee
AGENTS.mdo las instrucciones locales. - Ejecuta
git status --shortal inicio. - Encuentra componentes de página, hooks de animación, keyframes CSS,
requestAnimationFrame,setInterval,setTimeout, componentes de canvas/WebGL/física, elementos multimedia, líneas de tiempo/tweens de GSAP y utilidades de visibilidad existentes. - Busca en la limpieza de efectos los listeners de eventos, observadores, bucles RAF, intervalos, temporizadores, scripts externos, flujos multimedia, texturas/materiales/geometrías/renderizadores WebGL y trabajo asíncrono que pueda completarse después del desmontaje.
- Si el árbol de trabajo está sucio, planifica un staging estrecho desde el principio.
- Lee
-
Captura una línea base en el navegador.
- Abre la ruta exacta que el usuario mencionó.
- Perfila arriba, en la mitad, en el pie/pie de página inferior y en una ventana móvil cuando el diseño pueda diferir.
- Cuenta las animaciones CSS mediante
animationName,animationPlayStatey visibilidad. Incluye::beforey::after. - Inspecciona los elementos canvas/WebGL por separado; el perfilado CSS no prueba que los bucles RAF se hayan detenido.
- Registra qué nombres de animación están ejecutándose fuera de pantalla y los propietarios DOM responsables.
- Para solicitudes de memoria/fugas, también registra los recuentos de elementos/canvas/imágenes/iframes, las métricas de heap JS expuestas cuando estén disponibles, una muestra inactiva después de 10-30 segundos y una muestra corta de ciclo de ruta. Si las APIs de heap devuelven
nullo el sandbox del navegador bloquea el monkey-patching, dilo y confía en los recuentos observables estables más la auditoría del código fuente. - Mantén las pruebas de estrés acotadas. Un fallo de pestaña del navegador durante el perfilado es evidencia de sobrecarga, pero no atribuyas la causa en exceso a menos que se reproduzca con una prueba mínima.
- Consulta
references/browser-profiling.mdpara un evaluador reutilizable de Codex Browser.
-
Parchea al propietario más pequeño que controla el movimiento.
- Prefiere un hook de revelación/visibilidad de página existente si la aplicación tiene uno.
- De lo contrario, agrega un
IntersectionObserverque alterne una clase estable comois-offscreenen las secciones y elementos hijos animados. - Pausa las animaciones CSS con reglas específicas:
main > section.is-offscreen .expensive-animation,
.expensive-animation.is-offscreen {
animation-play-state: paused !important;
}
- Para tarjetas repetidas o placeholders, observa el contenedor de la tarjeta y los descendientes animados, no todo el documento.
- Para pistas de marquesina/ticker, pausa la pista cuando su sección esté fuera de pantalla.
- Para cargadores de esqueleto y destellos de pseudo-elementos, incluye selectores de pausa
::beforey::afterdonde sea necesario. - Para bucles de canvas/WebGL/física, controla el bucle RAF directamente:
- Inicia cuando el canvas/contenedor intersecte.
- Cancela
requestAnimationFramecuando esté fuera de pantalla. - Reanuda al volver a entrar.
- Desconecta los observadores y cancela los marcos al limpiar.
- Agrega un marcador de depuración no visual como
data-animation-activecuando ayude a la verificación en el navegador.
- Respeta
prefers-reduced-motionsi el componente ya lo hace y evita introducir bucles de renderizado de React para el estado de desplazamiento/animación. - Para el endurecimiento de fugas:
- Limpia cada timeout/interval creado por el efecto.
- Cancela RAF antes del desmontaje y antes de reiniciar un bucle.
- Desconecta
IntersectionObserver,ResizeObserver,MutationObservery suscripciones personalizadas. - Elimina los listeners globales/window/document con la misma referencia de manejador.
- Desecha texturas, materiales, geometrías, renderizadores Three/WebGL y elimina los nodos DOM del renderizador.
- Mata los tweens/líneas de tiempo de GSAP para nodos DOM y objetos mutables como uniformes de shaders.
- Detén los flujos multimedia y pausa las fuentes de video/audio desvinculadas.
- Protege los cargadores asíncronos con un flag
isDisposedy desecha los recursos cargados si se resuelven después del desmontaje. - En la limpieza de React, captura los valores de
ref.currentdentro del efecto antes de devolver la limpieza si el linter advierte que la ref puede cambiar. - Limita los deltas de cuadros de física o simulación después de pausas de visibilidad para que los cuadros retrasados no ejecuten actualizaciones sobredimensionadas.
-
Verifica el comportamiento, no solo las compilaciones.
- Recarga la ruta y vuelve a ejecutar los mismos perfiles de arriba/medio/pie/página móvil.
- Resultado objetivo:
offscreenRunningCount: 0para las secciones de página bajo prueba. - Confirma que las animaciones visibles aún se ejecuten o se reanuden al desplazarse a la vista.
- Confirma que los bucles RAF/canvas informen inactivos fuera de pantalla y activos en la vista, o de lo contrario prueba la cancelación desde el estado de origen/tiempo de ejecución.
- Para auditorías de fugas, compara los ciclos de ruta antes/después y las muestras inactivas. Los recuentos de DOM/canvas/imágenes deben volver a la misma línea base después de la navegación repetida, permitiendo pequeños cambios esperados de contenido asíncrono.
- Realiza una interacción normal de página, como búsqueda/filtro/navegación, para que el observador no rompa el contenido dinámico.
- Verifica las advertencias/errores de la consola en una pestaña nueva.
-
Ejecuta comprobaciones locales.
- Usa las puertas de control normales del repositorio. Para aplicaciones React/Vite, esto suele ser:
git diff --check
npm run lint
npm run build
- Menciona las advertencias no fatales conocidas por separado de los fallos.
- Confirma de forma estrecha cuando lo soliciten las instrucciones del repositorio/usuario.
- Si existen cambios sucios no relacionados, usa un índice aislado:
rm -f /tmp/<task>-index
GIT_INDEX_FILE=/tmp/<task>-index git read-tree HEAD
# Aplica solo los fragmentos previstos al índice temporal.
GIT_INDEX_FILE=/tmp/<task>-index git diff --cached --check
GIT_INDEX_FILE=/tmp/<task>-index git commit -m "Pausar animaciones de <página> fuera de pantalla"
git restore --staged <archivos> 2>/dev/null || true
- Nunca hagas stage de archivos amplios de un árbol de trabajo sucio a menos que cada fragmento pertenezca a la tarea.
- Informa con evidencia.
- Comienza con los hallazgos: qué seguía ejecutándose, qué parecía propenso a fugas y qué no se pudo medir.
- Separa los riesgos de auditoría del código fuente de las mediciones en vivo del navegador.
- Incluye las rutas exactas muestreadas, los recuentos de animaciones fuera de pantalla, la estabilidad de los recuentos de DOM/canvas, el resultado del ciclo de ruta y las comprobaciones locales.
- Indica las limitaciones claramente, especialmente los contadores de heap no disponibles o la instrumentación del navegador bloqueada.
Patrones de Corrección Buenos
is-offscreena nivel de sección másis-offscreena nivel de elemento para secciones largas donde las animaciones de hijos debajo del pliegue aún pueden ejecutarse.- Constantes de selector de visibilidad compartidas por ruta, como
COURSES_PAGE_ANIMATION_VISIBILITY_SELECTOR. - Umbrales de
IntersectionObserveralrededor de0.01para la compuerta de animación. - Control directo del bucle RAF para efectos WebGL/canvas;
animation-play-statede CSS no puede pausar los bucles de renderizado de JavaScript. - Límites de delta de cuadros para bucles de física que se reanudan después de un cuadro pausado o retrasado.
- Nodos de limpieza capturados para refs de React utilizados por efectos GSAP/WebGL.
- Protectores
isDisposedpara cargadores de imágenes/video/textura/datos que pueden resolverse después del desmontaje. - Sondas cortas de inactividad y ciclo de ruta para detectar acumulación de nodos DOM, canvas, iframes o medios no liberados.
Evitar
- Eliminar todas las animaciones para que el perfil pase.
- Pausar el movimiento heroico visible porque un selector ancestro es demasiado amplio.
- Asumir que
animation-play-statecubre pseudo-elementos o bucles RAF de JavaScript. - Confiar en una sola medición en la parte superior de la página en páginas largas.
- Tratar los contadores de heap no disponibles como prueba de que no hay fuga de memoria.
- Ejecutar bucles de estrés ilimitados en el navegador; usa ciclos acotados y registra fallos sin exagerar la causalidad.
- Usar capturas de pantalla como única prueba de rendimiento.
- Permitir que fragmentos locales no relacionados viajen en el commit.