slimabbadi/ui-diff

¿Qué hace ui-diff?

Captura una página antes de editarla, captúrala de nuevo después y lee qué cambió. La comparación se ejecuta localmente: los píxeles se alinean como un diff de texto, y cada región modificada se empareja con el cambio DOM que la causó. El modelo solo paga por una imagen cuando algo visible cambió. Incluso entonces, la imagen contiene solo los elementos modificados, recortados, dentro de un presupuesto de tokens (400 por defecto; dos capturas de pantalla completas suelen costar entre 2000 y 5000).

scripts/ está junto a este archivo. A continuación, $UI_DIFF representa node <directorio_de_este_skill>/scripts/ui-diff.mjs.

Configuración (una vez por máquina)

1. Coloca agent-browser en el PATH (npm i -g agent-browser, luego agent-browser install para Chromium; en Linux agent-browser install --with-deps).
2. Instala la biblioteca de imágenes: ejecuta npm install dentro de <directorio_de_este_skill>/scripts.
3. Prueba opcional de que la máquina está lista: node <directorio_de_este_skill>/scripts/selftest/selftest.mjs. Sale con código 0 cuando todos los escenarios pasan.

Pasos

1. Línea base antes de la primera edición: $UI_DIFF baseline <url> --name <slug>. Usa un slug por página o estado, como home o checkout-mobile. Una línea base carga la página dos veces para aprender qué partes parpadean por sí solas.
2. Haz el cambio.
3. Verifica: $UI_DIFF check <url> --name <slug>. Salida 0 significa que no hay cambios visuales, 1 significa que se encontró un cambio, y 2 significa un error.
4. Lee primero el informe de texto, luego decide sobre la imagen:
   • Cada cambio DOM listado es uno que pretendías y el informe muestra 0 unexplained: el texto es la evidencia, así que deja la imagen sin abrir.
   • El informe lista regiones no explicadas (U1.…), o necesitas juzgar cómo se ve algo: abre la ruta de la imagen de revisión que imprime el informe. Ábrela una vez, al final del trabajo, porque una lectura de imagen a medio camino se recobra en cada turno posterior.
5. Itera volviendo a ejecutar check contra la misma línea base. Toma una nueva línea base solo cuando aceptes el estado actual como nueva referencia.

El paso está completo cuando el informe lista exactamente los cambios que pretendías, y cada región no explicada está entendida o corregida.

Leyendo el informe

• Cambios DOM son las causas: etiqueta del elemento, luego propiedad antes -> después (colores en hex) o texto "viejo" -> "nuevo". Los cambios idénticos se agrupan (x3). Los cambios que no tocan píxeles modificados solo se cuentan.
• layout lista las consecuencias: elementos movidos por (dx, dy), elementos redimensionados y filas de píxeles que se desplazaron con contenido idéntico. Estos son efectos esperados de un cambio de tamaño o espaciado, por lo que no reciben imagen.
• regiones de píxeles coloca cada área modificada en una de cuatro clases:
  • por cambios DOM y solo por layout están explicadas.
  • volátil significa que la página también cambió allí entre dos capturas idénticas.
  • no explicada significa que los píxeles cambiaron y nada en el DOM lo explica, por ejemplo canvas, imágenes o pseudo-elementos. Las regiones no explicadas siempre están en la imagen: son donde se esconden las regresiones.
• SUBTLE marca un cambio demasiado tenue para verlo, como un ajuste de token de diseño. Confía en los valores hex en el texto sobre la imagen.
• Cambios de espaciado (margin, padding, gap) aparecen en un recorte solo en relación con los vecinos. El texto da los valores exactos.

Ruido y opciones

• ⚠ page kept changing between shots significa contenido en vivo (animaciones, carruseles, temporizadores). Ocúltalo con --hide "<selectores css>", o limita la verificación con --selector <css> al elemento que cambiaste.
• Los banners de consentimiento y widgets de chat van en --hide. Los elementos ocultos siempre se listan en el informe.
• Los valores predeterminados del proyecto van en .ui-diff.json en el directorio de trabajo, por ejemplo { "hide": "#cookie-banner", "width": 1440 }. Las banderas lo anulan.
• Los elementos position:fixed se fijan donde están en la página, por lo que permanecen en la comparación.
• Las capturas van a .ui-diff/ en el directorio de trabajo. Esa carpeta se ignora a sí misma en git.
• Ejecuta $UI_DIFF sin argumentos para imprimir todas las banderas.