motion-analytics

Analítica de movimiento

La calidad del movimiento se puede medir. "Se siente suave" y "se parece a la referencia" son afirmaciones; esta habilidad las convierte en números que puedes repetir la próxima semana.

Dos tareas:

1. Rendimiento: cuánto tiempo toma cada fotograma, qué tan pesada es la página y cómo se adapta cuando el dispositivo es lento. Guía: references/performance.md. Herramienta: scripts/frame-meter.js.
2. Calificación de referencia: qué tan cerca está una página de una referencia o de su propio objetivo de diseño, evaluado de manera justa. Guía: references/reference-grading.md. Herramienta: scripts/compare-sheet.mjs.

Inicio rápido

Medir tiempo de fotograma en cualquier página

Agrega el medidor y abre la página con ?meter:

<script src="frame-meter.js" defer></script>

Aparece un pequeño indicador que muestra p50, p95 y un nivel de calidad sugerido, y la consola registra un resumen cada cinco segundos. Desde la consola también puedes ejecutar:

frameMeter.start();          // iniciar una medición limpia
// ...desplázate por la página, usa la interacción principal...
frameMeter.report();         // { frames, p50, p95, p99, max, fps, longFrames, jank, suggest }

Mide en el dispositivo más lento que te importe, no en tu estación de trabajo. Desplázate por toda la página y usa la interacción principal durante la medición, porque los fotogramas inactivos ocultan los momentos costosos.

Generar una tabla comparativa lado a lado

node scripts/compare-sheet.mjs ./shots/nuestros ./shots/referencia ./comparar --labels "Nuestro,Referencia"

Empareja imágenes con el mismo nombre de archivo, genera compare.html (siempre) y compare.png (cuando sharp está instalado). Entrega la tabla a los evaluadores como se describe en la guía de calificación.

Los números que importan

Medida	Objetivo	Por qué
Tiempo de fotograma p95	16.7 ms o menos en el dispositivo objetivo (60 Hz)	p95 es lo que la gente siente; la mediana oculta los tirones
Tiempo de fotograma p50	Muy por debajo de p95	Una gran brecha indica picos: subidas, GC, compilación de shaders
Fotogramas largos (más de 50 ms)	0 mientras se desplaza	Cada uno es un salto visible
Peso de página en primera pantalla	Menos de 3 MB	Primera impresión en datos móviles
Página completa	Menos de 10 MB	Tiempo de carga, costo de datos, batería
Largest Contentful Paint	Menos de 2.5 s	Mostrar una imagen compuesta antes de que lleguen los recursos pesados
Cumulative Layout Shift	Menos de 0.1	Los recuadros de canvas y vídeo deben reservar su espacio
Interaction to Next Paint	Menos de 200 ms	Los bucles de renderizado pesados no deben bloquear la entrada

Detalles, presupuestos por tipo de recurso y una escalera de calidad funcional en references/performance.md.

Flujo de trabajo

1. Línea base. Carga la página con ?meter, desplázate de arriba a abajo dos veces, usa la interacción principal y luego lee frameMeter.report(). Anota el dispositivo, navegador, ventana gráfica y los números.
2. Encuentra la sección costosa. Repite por sección con frameMeter.start() al inicio de la sección y report() después. El peor p95 es donde trabajar.
3. Corrige la causa. Generalmente una de: relación de píxeles del dispositivo demasiado alta, un pase posterior a resolución completa, demasiadas llamadas de dibujo, una textura subida a mitad del desplazamiento, un shader compilado en la primera vista o renderizado mientras está oculto. Consulta la tabla de correcciones en la guía de rendimiento.
4. Agrega la escalera. Incluso una página rápida necesita una forma de adaptarse en un teléfono débil. Usa el fragmento de escalera dinámica: baja un escalón por encima de 22 ms p95, sube un escalón por debajo de 12 ms.
5. Vuelve a medir de la misma manera. Mismo dispositivo, misma ruta, misma duración. Informa antes y después.
6. Califica contra el objetivo. Cuando la página recrea un diseño o un aspecto de referencia, genera tablas de cuatro momentos y aplica el método de tres evaluadores descrito en references/reference-grading.md.

Formato del informe

Página: <nombre>   Dispositivo: <modelo, navegador>   Ventana: <ancho x alto, DPR>
Ruta: desplazamiento completo x2 + interacción principal, 60 s
Antes: p50 9.8 ms, p95 31.2 ms, fotogramas largos 6, peso 14.1 MB
Después:  p50 7.1 ms, p95 15.9 ms, fotogramas largos 0, peso 8.7 MB
Cambios: límite de DPR 1.5 en teléfonos, bloom a media res, texturas hero a WebP 2048, shaders precompilados en el cargador
Escalera: niveles 0 a 3, se estabiliza en nivel 3 en escritorio, nivel 2 en el teléfono de prueba

Reglas

• Informa p95, no el FPS promedio. Un promedio de 58 fps puede ocultar un tirón cada segundo.
• Una clase de dispositivo por número. Nunca mezcles una medición de portátil con una de teléfono en una misma afirmación.
• Misma ruta cada vez. Las mediciones solo son comparables cuando la ruta de desplazamiento, la interacción y la duración coinciden.
• Mide también la carga en frío. La primera vista compila shaders y sube texturas. Ahí es donde viven los fotogramas largos.
• Califica con evidencia. Un veredicto "cercano" necesita tablas en momentos igualados y evaluadores que no hayan construido la página.

Relacionado

• Rúbrica de revisión y comprobaciones de bloqueo de QA: ../motion-review/SKILL.md.
• Flujo de trabajo artesanal y biblioteca de técnicas: ../motioncraft-builder/SKILL.md.