slimabbadi/ui-diff

ui-diff은(는) 무엇을 하나요?

페이지를 편집 전에 캡처하고, 편집 후에 다시 캡처하여 변경된 내용을 읽어보세요. 비교는 로컬에서 실행됩니다. 픽셀을 텍스트 diff처럼 정렬하고, 각 변경된 영역을 해당 DOM 변경과 매칭합니다. 모델은 시각적으로 변경된 것이 있을 때만 이미지 비용을 지불합니다. 그때도 이미지는 토큰 예산(기본 400, 전체 페이지 스크린샷 두 장은 일반적으로 2,000–5,000) 내에서 변경된 요소만 크롭하여 보여줍니다.

scripts/ 디렉토리는 이 파일 옆에 있습니다. 아래에서 $UI_DIFF는 node <이 스킬 디렉토리>/scripts/ui-diff.mjs를 의미합니다.

설정 (머신당 한 번)

1. agent-browser를 PATH에 추가하세요 (npm i -g agent-browser, 이어서 agent-browser install로 Chromium 설치; Linux에서는 agent-browser install --with-deps).
2. 이미지 라이브러리 설치: <이 스킬 디렉토리>/scripts 안에서 npm install을 실행하세요.
3. 머신이 준비되었는지 확인하려면 (선택 사항): node <이 스킬 디렉토리>/scripts/selftest/selftest.mjs를 실행하세요. 모든 시나리오가 통과하면 종료 코드 0을 반환합니다.

단계

1. 첫 편집 전 베이스라인: $UI_DIFF baseline <url> --name <slug>. 페이지나 상태별로 하나의 슬러그를 사용하세요(예: home 또는 checkout-mobile). 베이스라인은 페이지를 두 번 로드하여 스스로 깜박이는 부분을 학습합니다.
2. 변경을 수행하세요.
3. 확인: $UI_DIFF check <url> --name <slug>. 종료 코드 0은 시각적 변경 없음, 1은 변경 발견, 2는 오류를 의미합니다.
4. 먼저 텍스트 보고서를 읽은 후 이미지를 결정하세요:
   • 나열된 모든 DOM 변경이 의도한 것이고 보고서에 0 unexplained가 표시되면: 텍스트가 증거이므로 이미지는 열지 마세요.
   • 보고서에 설명되지 않은 영역(U1.…)이 나열되거나, 특정 부분이 어떻게 보이는지 판단해야 할 경우: 보고서가 출력하는 검토 이미지 경로를 여세요. 작업이 끝날 때 한 번만 열어야 합니다. 중간에 이미지를 읽으면 이후 턴마다 다시 청구되기 때문입니다.
5. 반복 같은 베이스라인에 대해 check를 다시 실행하세요. 현재 상태를 새로운 참조로 받아들일 때만 새 베이슬라인을 생성하세요.

보고서에 의도한 변경 사항만 정확히 나열되고, 모든 설명되지 않은 영역이 이해되거나 수정되었을 때 단계가 완료됩니다.

보고서 읽기

• DOM 변경은 원인입니다: 요소 레이블, 그 다음 속성 before -> after (색상은 16진수) 또는 텍스트 "old" -> "new". 동일한 변경은 그룹화됩니다 (x3). 변경된 픽셀과 관련 없는 변경은 개수만 세어집니다.
• layout은 결과를 나열합니다: (dx,dy)만큼 이동한 요소, 크기가 조정된 요소, 동일한 내용으로 이동한 픽셀 행. 이는 크기나 간격 변경의 예상 효과이므로 이미지가 제공되지 않습니다.
• pixel regions은 변경된 모든 영역을 네 가지 클래스 중 하나로 분류합니다:
  • by DOM changes 및 by layout only는 설명됨.
  • volatile은 페이지가 동일한 캡처 두 번 사이에서 그 부분도 변경되었음을 의미.
  • unexplained은 픽셀이 변경되었지만 DOM에서 이를 설명하는 것이 없음을 의미(예: canvas, 이미지, 의사 요소). 설명되지 않은 영역은 항상 이미지에 포함됩니다: 회귀가 숨는 곳입니다.
• SUBTLE은 너무 희미해서 보기 어려운 변경을 표시합니다(예: 디자인 토큰 조정). 텍스트의 16진수 값을 이미지보다 신뢰하세요.
• Spacing changes (margin, padding, gap)는 이웃과의 관계 속에서만 크롭에 나타납니다. 텍스트가 정확한 값을 제공합니다.

노이즈와 옵션

• ⚠ page kept changing between shots는 라이브 콘텐츠(애니메이션, 캐러셀, 타이머)를 의미합니다. --hide "<css selectors>"로 숨기거나, --selector <css>로 변경한 요소로 확인 범위를 좁히세요.
• 동의 배너와 채팅 위젯은 --hide에 포함하세요. 숨겨진 요소는 항상 보고서에 나열됩니다.
• 프로젝트 기본값은 작업 디렉토리의 .ui-diff.json에 설정합니다(예: { "hide": "#cookie-banner", "width": 1440 }). 플래그가 이를 재정의합니다.
• position:fixed 요소는 페이지에서 고정된 위치에 유지되므로 비교에 포함됩니다.
• 캡처는 작업 디렉토리의 .ui-diff/에 저장됩니다. 이 폴더는 git에서 무시됩니다.
• $UI_DIFF를 인수 없이 실행하면 모든 플래그가 출력됩니다.