¿Qué hace reanimate?
Reconstruye lo que el usuario señale para que se mueva como se mueve la referencia, pruébalo con una comparación cuadro por cuadro y continúa hasta que la comparación sea exitosa. El resultado es código en el proyecto del usuario más evidencia (números y hojas lado a lado), nunca "se ve más o menos bien".
Qué significa "terminado"
Elige el nivel de fidelidad de las palabras del usuario y establécelo en el primer mensaje; esto decide qué verificas.
| Nivel | Cuándo | Debe coincidir | Puede diferir |
|---|---|---|---|
| fiel al movimiento (por defecto) | "clonar esta animación", "hacer que la nuestra se sienta como la de ellos", "mismo héroe que X pero nuestra copia" | activación, secuencia y orden, escalonamiento, sincronización de cada paso (±80 ms), familia de easing, dirección y distancia del movimiento relativo al tamaño del elemento, proporciones del diseño | copia, colores, fuentes, imágenes, detalles de marca |
| fiel al píxel | "que coincida exactamente", "píxel perfecto", "los detalles deben coincidir", "1:1" | todo lo anterior más fuentes, tamaños, colores, espaciado, radios, sombras, activos; error medio del cuadro ≤ 2 % | nada que el usuario no haya pedido cambiar |
| mixto | "clonar X y agregar Y", "como la de ellos pero con nuestros niveles de precios" | las partes clonadas en uno de los niveles anteriores | las adiciones, que describes y muestras pero verificas solo que no rompan el movimiento clonado |
El usuario puede acotar el objetivo a una sección, un widget, una página o un rango de tiempo de un video ("los primeros 3 segundos", "0:12 a 0:15"). Clona exactamente eso; no incluyas el resto de la página.
Flujo de trabajo
Todo lo siguiente vive en .reanimate/<nombre>/ dentro del proyecto del usuario (agrégalo a .gitignore a menos que quieran que la evidencia se confirme en el repositorio). Conserva los artefactos de cada ronda; son la prueba.
0. Alcance
Escribe tres líneas al inicio de .reanimate/<nombre>/spec.md antes de cualquier captura:
- Objetivo: qué clonar, tan precisamente como lo dijo el usuario (URL + selector / rango de tiempo / "el interruptor en el gif").
- Destino: dónde va el código y en qué stack (lee
package.json, componentes existentes y la librería de animación ya en uso; adáptate a ella en lugar de introducir una nueva). - Fidelidad: fiel al movimiento, fiel al píxel o mixto, más la lista de adiciones para mixto.
Deduce lo que puedas de la solicitud y del repositorio. Pregunta solo cuando dos interpretaciones lleven a trabajos diferentes (por ejemplo, "el héroe" en una página con dos secciones candidatas). Cuando una referencia sea una página con inicio de sesión o un enlace de YouTube/Loom que no puedas descargar aquí, pídele al usuario una grabación de pantalla y continúa con todo lo demás mientras tanto.
1. Configuración
<skill> a continuación es el directorio donde vive este SKILL.md. Los scripts necesitan Bun; la primera ejecución descarga Chromium de Playwright y un ffmpeg estático (aproximadamente 250 MB).
bash <skill>/scripts/setup.sh # instala playwright, ffmpeg, pixelmatch una vez; imprime "ready"
Todos los scripts se ejecutan con bun <skill>/scripts/<nombre>.ts --help. Son deterministas y comparten una regla: captura la referencia y el clon con el mismo viewport, recorte de selector, activación, duración y fps, de lo contrario la comparación mide tu configuración en lugar de tu trabajo.
2. Capturar la referencia
Lee references/capture.md para la receta según tu tipo de fuente. En resumen:
- Sitio web:
capture.ts --url ... --out ref --selector <sección> --trigger load|scroll|hover|click|none --duration ... --track "<elementos en movimiento>". Obtienesvideo.webm,frames/,inspect.json(animaciones declaradas, keyframes, estilos calculados, fuentes, librerías detectadas) ytrack.json(por cuadro de animación: posición, tamaño, opacidad, transform de cada elemento rastreado). Para movimiento CSS/WAAPI,inspect.jsona menudo contiene las duraciones, retardos y easings exactos: úsalos, es mejor que estimar. - Video o gif:
frames.ts --in archivo --out ref/frames --fps 10..30 --start ... --end ... --crop .... Primero prueba con--probe, luego revisa algunos cuadros para encontrar el recorte del widget que estás clonando. - Canvas, WebGL, WebGPU, 3D (
inspect.json › canvasesmuestra uno, o la página usa three.js, Pixi, Babylon, Spline...): agrega--clock virtual --gl --assetsa la captura y leegl/summary.md(gl.ts summary <out>). Obtienes los códigos fuente de los shaders, cada uniforme constante, el grafo de escena, los pases de renderizado, las texturas y modelos, y cada propiedad animada de uniforme u objeto como un canal engl-track.json. El reloj virtual hace que cada cuadro sea exacto y cada captura idéntica, partículas aleatorias incluidas. Leereferences/webgl.md. - Lottie / Rive / exportación de prototipo: el archivo es la especificación; léelo, no lo derives de píxeles.
Luego construye hojas etiquetadas y míralas: sheet.ts filmstrip --frames ref/frames --out ref/sheets. Lee cada hoja con el visor de imágenes. Esta es la inspección cuadro por cuadro que el usuario solicitó; no la omitas ni muestrees solo la primera hoja.
3. Escribir la especificación de movimiento
Completa spec.md usando la plantilla en references/analysis.md. Una fila por elemento por propiedad: activación, tiempo de inicio, duración, retardo o escalonamiento, desde → hasta, easing, notas. Obtén los números de, en orden de preferencia: animaciones y keyframes de inspect.json → easing.ts en track.json, o en gl-track.json --channel para canvas → leyendo cuadros (primer cuadro donde cambia, último cuadro donde cambia, sobreimpulso o no). También anota los hechos estáticos de los que depende el movimiento: tamaños y posiciones de elementos, orden z, recorte por desbordamiento, orígenes de transformación, y para trabajo fiel al píxel, fuentes, colores, espaciado y activos.
La especificación es el contrato entre la referencia y el clon. Cada fila se convierte en una verificación en el paso 5. Si una fila tiene un "?" no has terminado de leer los cuadros.
4. Construir
Implementa en el stack del usuario siguiendo references/implementation.md (tablas de easing, matemáticas de escalonamiento, activadores de scroll y hover, movimiento reducido). Mantén la estructura del DOM cercana a la estructura de roles de la referencia para que los selectores rastreados tengan equivalentes. Para trabajo mixto, coloca las adiciones en componentes o bloques claramente separados y menciónalos en spec.md bajo "Adiciones".
Proporciona al clon una forma de ser capturado de la misma manera que la referencia: una ruta o una página estática que renderice el componente en el viewport de la referencia con el mismo activador. Un servidor de desarrollo está bien (capture.ts --url http://localhost:5173/...); un archivo HTML independiente también funciona.
5. Verificar, corregir, repetir
Captura el clon con el mismo comando exacto usado para la referencia, cambiando solo --url y --out clone-N, luego:
bun <skill>/scripts/compare.ts --ref ref/frames --clone clone-N/frames --out compare-N
bun <skill>/scripts/sheet.ts compare --ref ref/frames --clone clone-N/frames --diff compare-N/diff --out compare-N/sheets --every 2
bun <skill>/scripts/easing.ts --track clone-N/track.json --selector "<el>" --prop <translateY|opacity|...> --compare-track ref/track.json
Para trabajo con canvas, ejecuta también gl.ts compare --ref ref --clone clone-N, que verifica la configuración del canvas, la estructura de dibujo y cada canal animado.
Lee references/verify.md para saber cómo leer el informe, los criterios de aprobación para cada nivel de fidelidad y las correcciones que cada tipo de fallo suele necesitar. Mira tú mismo las hojas de comparación en cada ronda; los números te dicen que algo está mal, las hojas te dicen qué.
Repite hasta que cada fila de la especificación pase. Cada ronda: cambia la cosa más pequeña que la evidencia señale, vuelve a capturar, vuelve a comparar. Espera de 2 a 5 rondas. Si después de 5 rondas una fila aún falla, detente e infórmalo con sus números y la razón (fuente faltante, un shader o modelo que el usuario quizás no pueda copiar, un resorte físico que aproximaste), no bajes el umbral en silencio ni elimines la fila.
6. Informe
El mensaje final debe ser autosuficiente:
- Nivel de fidelidad y qué se clonó, qué se agregó.
- Dónde está el código (archivos) y cómo activar el movimiento.
- Una tabla breve de la última ronda de comparación: error de sincronización, error medio, coincidencia de easing por elemento clave, pasa/falla.
- Rutas a las hojas de comparación finales, incrustadas como imágenes cuando el entorno las muestre.
- Desviaciones residuales, cada una con un número y una razón.
Errores que desperdician rondas
- Diferente viewport o recorte entre referencia y clon: corrige la captura antes de tocar el código.
- Juzgar solo por el primer y el último cuadro: el easing vive en los cuadros intermedios; lee las hojas.
- Fuentes: una fuente de respaldo diferente cambia los píxeles de cada cuadro. Para trabajo fiel al píxel, carga la misma fuente (de
inspect.jsonfonts) antes de juzgar el error; para trabajo fiel al movimiento, ignora los píxeles de texto y lee las columnas de sincronización. - Referencia grabada en una página cargada vs clon capturado en frío: usa
--wait-before, o--trigger nonecon un--pre-jsque reinicie la animación, para que ambos comiencen desde reposo. - Movimiento impulsado por scroll: es una función de la posición de scroll, no del tiempo. Captura ambos con los mismos
--scroll-stepsy--scroll-ms, y compara por posición de scroll (elscrollYdel track), no por segundo. - Librerías JS (GSAP, resortes de Framer Motion):
--playback-rateno los ralentiza. Usatrack.jsonyeasing.ts(que reporta sobreimpulso y "tipo resorte") y ajusta los parámetros del resorte por el sobreimpulso y el tiempo de asentamiento. - Los videos de la pantalla de otra persona tienen un cursor, un marco de navegador y ruido de compresión: recórtalos y eleva un poco
--pixel-threshold(0.15) en lugar de perseguir el ruido. - Canvas y WebGL capturados en el reloj real: los cuadros se caen en GL de software y el contenido aleatorio difiere en cada carga, por lo que la comparación mide la máquina. Captura ambos lados con
--clock virtualy el mismo--seed. - Reconstruir un shader a partir de capturas de pantalla: el trazado ya tiene su fuente y cada constante. Lee
gl/shaders/y los uniformes fijos antes de escribir GLSL.