kinqsradio/motion-match

Coincidencia de movimiento

Usa esto cuando el usuario señala algo que se mueve y quiere que lo nuestro se mueva igual, o quiere pruebas de que lo hace. El resultado es código más números y hojas de cálculo, nunca «se ve más o menos igual».

Los derechos van primero

Decide quién posee la referencia antes de capturar nada, y menciónalo en tu primer mensaje.

Referencia	Lo que puedes hacer
Trabajo propio, o uno que el usuario posea o tenga licencia	Cualquier fidelidad, incluido nivel de píxel
Sitio web o vídeo de otra persona	Medir solo tiempos, curvas de easing, orden y distancia, como especificación escrita, y construir con nuestro propio diseño

Para el trabajo de otros:

• Nunca copies su código, shaders, recursos, fuentes, marca, diseño o texto. Nunca recrees un producto real como si fuera nuestro.
• Una coincidencia exacta a nivel de píxel está descartada, sea cual sea la redacción de la solicitud. Ofrece en su lugar una coincidencia a nivel de movimiento y explica por qué: «Puedo igualar cómo se mueve con tu diseño. Copiar su apariencia tomaría su trabajo de diseño, así que no lo haré».
• Los muros de inicio de sesión, de pago, comprobaciones de bots y DRM permanecen cerrados. Respeta los términos del sitio y captura solo lo que un visitante normal ve. Cuando no se pueda acceder a una página, pide una grabación de pantalla. Nunca descargues el vídeo de otra persona.
• Las capturas sin procesar se quedan en una carpeta local ignorada. Nunca se confirman, publican ni usan en un entregable, y se eliminan cuando el usuario lo decida. Solo los números escritos continúan adelante. Informa al usuario de dónde están.

Si el usuario dice que posee una referencia y nada lo contradice, confía en su palabra y regístralo en la especificación. «Hazlo idéntico al sitio de esa empresa» no es una licencia. Usa --rights third-party siempre que la propiedad no esté clara.

Fidelidad

Indica el nivel en tu primer mensaje; determina lo que verificas.

Nivel	Debe coincidir	Puede diferir
Movimiento (por defecto)	Disparador, orden, escalonamiento, tiempos de cada paso dentro de 80 ms, easing, dirección y distancia	Código, colores, fuentes, imágenes, diseño, marca
Píxel, solo propio o con licencia	Todo lo anterior, más fuentes, tamaños, colores, espaciado y recursos; diferencia media como máximo 2%	Nada que el usuario no haya pedido cambiar
Mixto	La parte igualada, en uno de los niveles anteriores	Las adiciones, que no deben romper el movimiento igualado

Coincide solo con lo que el usuario nombró: una sección, un widget o un rango de tiempo.

Método

Trabaja en output/motion-match/<nombre>/, o en otra carpeta que Git ignore. Conserva cada ronda. Pasa --playwright y --chrome, o configura PLAYWRIGHT_CORE y CHROME_PATH. Se requiere Node 22, un controlador de navegador existente y un navegador existente; se necesita ffmpeg para vídeo. No se instala nada.

1. Alcance. Escribe el objetivo, el destino en el proyecto, los derechos y la fidelidad.

2. Captura la referencia con scripts/capture.mjs, o scripts/frames.mjs para un vídeo proporcionado. Dale los derechos que decidiste:

   node <skill>/scripts/capture.mjs --url <page> --out <dir>/ref --rights third-party \
     --selector .hero --track ".title, .cta" --duration 2000
   

3. Lee cada hoja de cálculo. Ejecuta scripts/sheet.mjs filmstrip, luego abre cada hoja. El easing está en los fotogramas intermedios.

4. Escribe la especificación. Ejecuta scripts/spec.mjs draft: una fila por elemento por propiedad. Un ? significa que no has terminado de leer los fotogramas, y la verificación se niega a ejecutarse hasta que cada uno sea reemplazado.

5. Construye en el stack del propio proyecto, con su propio diseño para una referencia de terceros.

6. Graba el nuestro de la misma forma. Reutiliza el comando de referencia, cambiando solo --url, --out y --rights. Configuraciones diferentes miden tu configuración, y compare.mjs las falla.

7. Compara. Ejecuta scripts/spec.mjs check, scripts/compare.mjs y scripts/sheet.mjs compare. Lee cada hoja.

8. Cambia la cosa más pequeña que señalen los números, una causa por ronda, luego vuelve al paso 6.

9. Detente después de 5 rondas si una fila sigue fallando, e infórmalo con sus números y el motivo. Mantén los umbrales donde están.

10. Informa para que el mensaje se sostenga por sí solo: los derechos y la fidelidad; qué se igualó y qué se añadió; los archivos y cómo activar el movimiento; una tabla de la última ronda; las rutas de las hojas de cálculo; cada residual con un número y un motivo; y dónde se encuentra cualquier captura sin procesar de terceros.

Fallo trabajado

La ronda 1 de tres tarjetas falla:

.card-1 opacity  inicio +300 ms  fin +300 ms  easing RMSE 0.0003  FALLO
.card-2 opacity  inicio +300 ms  fin +300 ms  easing RMSE 0.0055  FALLO
huecos           116.7 contra 116.7         pasa

Cada fila llega tarde en la misma cantidad, y la curva y los huecos son correctos, así que la única causa es el retardo base. Cambia ese número y vuelve a grabar. Alinear los fotogramas haría que esta fila pase y enviara una animación con 300 ms de retraso, por lo que compare.mjs rechaza --auto-align entre dos capturas.

Errores comunes

• Diferente viewport o recorte entre los dos lados: corrige la captura antes de tocar el código.
• Juzgar desde el primer y último fotograma: lee los intermedios.
• Fuentes: una fuente de respaldo cambia los píxeles de cada fotograma. A fidelidad de movimiento, lee las filas de tiempo e ignora los píxeles de texto.
• Página ya ocupada contra un inicio en frío: usa el mismo --wait-before en ambos lados.
• Movimiento impulsado por desplazamiento sigue la posición de desplazamiento, no el tiempo. Usa los mismos --scroll-steps y --scroll-ms, y compara por scrollY.
• Muelles: easing.mjs informa sobre el rebasamiento y la rigidez y amortiguación ajustadas. Ajusta por rebasamiento y tiempo de estabilización.
• Las grabaciones de pantalla llevan cursor, marco del navegador y ruido de compresión. Recórtalos y aumenta ligeramente --activity-threshold.
• Contenido de Canvas: usa el reloj virtual y el mismo --seed en ambos lados. El contenido aleatorio en el reloj real mide la máquina.
• Las animaciones CSS reportan linear en timing.easing. El easing real está en cada fotograma clave.

Límites

Usa orbyn-ui-design para decidir qué movimiento debería tener un producto, technical-illustration para grabaciones y product-illustration para interfaces falsas. Un vídeo sigue la regla de solo código: estudia una referencia para la técnica, y nunca copies sus fotogramas.

Leer cuando sea necesario

• Para recetas de captura, disparadores y archivos de salida, lee capture.
• Para el formato de especificación y cómo leer fotogramas, lee analysis.
• Para easing, muelles y patrones de construcción, lee implementation.
• Para criterios de éxito y qué significa cada fallo, lee verify.