slimabbadi/ui-diff

O que ui-diff faz?

Capture uma página antes de editá-la, capture novamente depois e leia o que mudou. A comparação é executada localmente: os pixels são alinhados como em um diff de texto, e cada região alterada é associada à alteração no DOM que a causou. O modelo só paga por uma imagem quando algo visível mudou. Mesmo assim, a imagem contém apenas os elementos alterados, recortados, dentro de um orçamento de tokens (400 por padrão; duas capturas de tela de página inteira normalmente custam 2.000–5.000).

scripts/ fica ao lado deste arquivo. Abaixo, $UI_DIFF representa node <diretório desta skill>/scripts/ui-diff.mjs.

Configuração (uma vez por máquina)

1. Coloque agent-browser no PATH (npm i -g agent-browser, depois agent-browser install para Chromium; no Linux agent-browser install --with-deps).
2. Instale a biblioteca de imagens: execute npm install dentro de <diretório desta skill>/scripts.
3. Prova opcional de que a máquina está pronta: node <diretório desta skill>/scripts/selftest/selftest.mjs. Ele sai com código 0 quando todos os cenários passam.

Passos

1. Base antes da primeira edição: $UI_DIFF baseline <url> --name <slug>. Use um slug por página ou estado, como home ou checkout-mobile. Uma base carrega a página duas vezes para aprender quais partes piscam por conta própria.
2. Faça a alteração.
3. Verifique: $UI_DIFF check <url> --name <slug>. Código de saída 0 significa nenhuma alteração visual, 1 significa que uma alteração foi encontrada e 2 significa um erro.
4. Leia o relatório textual primeiro, depois decida sobre a imagem:
   • Cada alteração de DOM listada é uma que você pretendia e o relatório mostra 0 inexplicados: o texto é a evidência, então deixe a imagem fechada.
   • O relatório lista regiões inexplicadas (U1....), ou você precisa julgar como algo se parece: abra o caminho da imagem de revisão que o relatório imprime. Abra-a uma vez, no final do trabalho, porque uma leitura de imagem no meio da tarefa é recobrada em cada turno posterior.
5. Itere executando novamente check contra a mesma base. Crie uma nova base somente quando você aceitar o estado atual como a nova referência.

O passo está concluído quando o relatório lista exatamente as alterações que você pretendia e cada região inexplicada é compreendida ou corrigida.

Lendo o relatório

• Alterações de DOM são as causas: rótulo do elemento, depois propriedade antes -> depois (cores em hex) ou texto "antigo" -> "novo". Alterações idênticas são agrupadas (x3). Alterações que não tocam em pixels alterados são apenas contadas.
• layout lista as consequências: elementos movidos por (dx,dy), elementos redimensionados e linhas de pixels que se deslocaram com conteúdo idêntico. Estes são efeitos esperados de uma alteração de tamanho ou espaçamento, então não recebem imagem.
• regiões de pixels coloca cada área alterada em uma das quatro classes:
  • por alterações de DOM e apenas por layout são explicadas.
  • volátil significa que a página também mudou ali entre duas capturas idênticas.
  • inexplicada significa que os pixels mudaram e nada no DOM explica, por exemplo canvas, imagens ou pseudo-elementos. Regiões inexplicadas estão sempre na imagem: são onde as regressões se escondem.
• SUBTLE marca uma alteração muito tênue para ser vista, como um ajuste de token de design. Confie nos valores hexadecimais no texto em vez da imagem.
• Alterações de espaçamento (margin, padding, gap) aparecem em um recorte apenas em relação aos vizinhos. O texto fornece os valores exatos.

Ruído e opções

• ⚠ página continuou mudando entre as capturas significa conteúdo ao vivo (animações, carrosséis, temporizadores). Esconda-o com --hide "<seletores css>", ou escopo da verificação com --selector <css> para o elemento que você alterou.
• Banners de consentimento e widgets de chat pertencem a --hide. Elementos ocultos são sempre listados no relatório.
• Padrões do projeto vão em .ui-diff.json no diretório de trabalho, por exemplo { "hide": "#cookie-banner", "width": 1440 }. Flags sobrescrevem.
• Elementos position:fixed são fixados onde estão na página, então permanecem na comparação.
• As capturas vão para .ui-diff/ no diretório de trabalho. Essa pasta se ignora no git.
• Execute $UI_DIFF sem argumentos para imprimir todas as flags.