docs(hyperframes): lecciones medidas contra un corpus de referencias, y cuatro herramientas de verificación

[occazzio]

Qué es

Usé el kit para producir ocho piezas, midiendo cada una contra un corpus de 22 referencias reales de motion graphics. El proceso dejó un conjunto de hallazgos que contradicen o completan lo que el skill de hyperframes ya decía, más cuatro herramientas que sostienen esas afirmaciones.

Todo lo que se afirma en el documento está medido, no estimado.

Qué cambia

Nuevo · references/lecciones-medidas.md

Enlazado como primera referencia del SKILL.md, con la nota de que donde contradiga al resto del skill gana, porque está medido.

• Trampas del motor de captura por seek. immediateRender muerde en las dos direcciones: con el default el elemento se congela en su estado inicial desde el cuadro 0, y con false muestra su estado final desde el cuadro 0. Este último apareció tres veces en piezas distintas. También: los fundidos que terminan en un límite de clip necesitan un tl.set duro, no hay obturador —todo el motion blur es autoreado—, y dos tweens sobre la misma propiedad se pisan en silencio.
• La escala real de un travelling. Medido cuadro a cuadro sobre una referencia: el objeto pasa del 13 % al 88 % del ancho del cuadro en 3.8 s. Un empuje de 1.0 a 1.15 no es una cámara. Y el error de fondo suele ser anterior: construir el objeto a escala web, con lo cual por más que se empuje nunca llena el cuadro.
• Por qué una cámara necesita textura para verse. Un degradado radial desplazado se ve idéntico a sí mismo. Incluye el umbral de percepción (1 px de desplazamiento aparente por cuadro) y una trampa cara: mix-blend-mode: overlay sobre negro devuelve negro, así que el grano queda puesto y es invisible.
• Cómo se ilumina un objeto en la oscuridad: lo define su borde, no su relleno.
• Medición de texto. Ninguna es válida antes de document.fonts.ready: offsetWidth devuelve el ancho de la tipografía de respaldo, medido 23 % menor, y una caja calculada con ese número recorta la frase para siempre. Incluye las alternativas por porcentaje y transformada que no dependen de ninguna métrica.
• Siete layouts de composición leídos de las referencias, con el único caso en que corresponde centrar.
• Ritmo (variación máx÷mediana ≈ 3×), tiempo de lectura (17 caracteres por segundo contados después de que el texto está completo), y las equivalencias de curva entre la literatura y GSAP: cubic out es power2.out, no power3 — la numeración de GSAP induce a este error.
• Audio: el sonido va en el pico de la animación y no en el corte; loudnorm controla el pico de muestra mientras el encoder AAC reconstruye picos entre muestras (~1.6 dB).
• Método: medir la fluidez en vez de opinarla, mirar a resolución completa y no en miniaturas, y el A/B pareado por timestamp contra la referencia.

Nuevo · scripts/lab/

fluidez.sh	mide cuántos cuadros no cambian respecto del anterior y dibuja el perfil
sfx.sh	sintetiza aire/click/sub/cama/riser con el pico en una posición conocida
master.sh	deja el audio en −16 LUFS verificando el pico real y corrigiéndose solo
getfont.mjs	baja cualquier Google Font en woff2 y arma el @font-face

Las cuatro usan sólo ffmpeg y Node, que el kit ya requiere.

Correcciones a contenido existente

• references/typography.md prohibía tipografías sin advertir que el motor sólo embebe 18 familias. Siguiendo la lista tal como estaba se podía elegir una que no está embebida y el render caía a la de respaldo en silencio. Ahora dice cuáles sobreviven a ambos filtros y cómo traer las demás.
• references/motion-principles.md proponía animar letterSpacing como variación de entrada, y el propio lint del motor lo rechaza: reflowea el texto y se clava a píxeles enteros, así que tiembla bajo la captura por seek. Corregido con la alternativa (partir en spans y animar la x de cada glifo).

Para el revisor

• El documento está en español. Si preferís que el kit mantenga todo en inglés, lo traduzco sin problema — decímelo y lo hago en este mismo PR.
• .claude/ y .agents/ están sincronizados con npm run sync:skills, como pide el CLAUDE.md del repo.
• Verificado: npm run check da 695 archivos y 0 errores; npm run sync:skills no reporta discrepancias.
• Las herramientas van en scripts/lab/ y no en video-projects/, que está en .gitignore — las referencias del documento apuntan ahí.
• El corpus de 22 referencias de motion graphics no se incluye: es material de terceros. El documento lo describe sin depender de esos archivos.

🤖 Generated with Claude Code