slimabbadi/ui-diff

ui-diff は何をしますか？

ページを編集前にキャプチャし、編集後に再度キャプチャして、変更内容を読み取ります。比較はローカルで実行されます。ピクセルはテキストdiffのように整列され、各変更領域はそれを引き起こしたDOM変更にマッピングされます。モデルは、目に見える変更があった場合にのみ画像に対して課金されます。その場合でも、画像には変更された要素のみが切り抜かれて、トークン予算内（デフォルト400、2ページの全画面スクリーンショットで通常2,000～5,000トークン）で収まります。

scripts/はこのファイルと同じディレクトリにあります。以下では、$UI_DIFFはnode <このスキルのディレクトリ>/scripts/ui-diff.mjsを表します。

セットアップ（マシンごとに1回）

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>。ページまたは状態ごとに1つのスラグ（例：homeやcheckout-mobile）を使用します。ベースラインはページを2回読み込み、自然に変動する部分を学習します。
2. 変更を加えます。
3. 確認： $UI_DIFF check <url> --name <slug>。終了コード0は視覚的な変更がないこと、1は変更が見つかったこと、2はエラーを意味します。
4. 最初にテキストレポートを読み、その後画像を確認するか判断します。
   • リストされたDOM変更がすべて意図したもので、レポートに0 unexplainedと表示されている場合：テキストが証拠となるので、画像は開かないでください。
   • レポートに説明不能な領域（U1.…）がリストされているか、何かの見た目を判断する必要がある場合：レポートが表示するレビュー画像パスを開きます。作業の最後に1回だけ開いてください。タスクの途中で画像を読み込むと、後続のターンごとに再課金されるためです。
5. 繰り返すには、同じベースラインに対してcheckを再実行します。現在の状態を新しい基準として受け入れる場合にのみ、新しいベースラインを取得します。

レポートに意図した変更だけが正確にリストされ、すべての説明不能な領域が理解されるか修正されたとき、このステップは完了です。

レポートの読み方

• DOM変更は原因です：要素ラベル、次にプロパティ 変更前 -> 変更後（色は16進数）、またはテキスト "旧" -> "新"。同一の変更はグループ化されます（x3）。変更されたピクセルに影響を与えない変更はカウントのみされます。
• レイアウトは結果をリストします：(dx,dy)移動した要素、サイズ変更された要素、および同一コンテンツで移動したピクセル行。これらはサイズや間隔の変更による予想される影響であるため、画像は生成されません。
• ピクセル領域は、変更されたすべての領域を4つのクラスのいずれかに分類します。
  • DOM変更によるものとレイアウトのみによるものは説明済みです。
  • 揮発性は、2回の同一キャプチャ間でページがその領域でも変更されたことを意味します。
  • 説明不能は、ピクセルが変更されたが、DOMではそれを説明できないことを意味します（例：canvas、画像、疑似要素）。説明不能な領域は常に画像に含まれます。これらはリグレッションが隠れている場所です。
• SUBTLEは、デザイントークンの微調整など、見るには薄すぎる変更を示します。画像よりもテキストの16進数を信頼してください。
• 間隔の変更（margin、padding、gap）は、隣接要素との相対的な切り抜きでのみ表示されます。テキストには正確な値が示されます。

ノイズとオプション

• ⚠ ページがショット間で変動し続けましたは、ライブコンテンツ（アニメーション、カルーセル、タイマー）を意味します。--hide "<cssセレクター>"で非表示にするか、--selector <css>で変更した要素にチェックを範囲限定します。
• 同意バナーやチャットウィジェットは--hideに含めるべきです。非表示にした要素は常にレポートにリストされます。
• プロジェクトのデフォルトは、作業ディレクトリの.ui-diff.jsonに設定します。例：{ "hide": "#cookie-banner", "width": 1440 }。フラグがこれを上書きします。
• position:fixed要素はページ上の位置に固定されるため、比較に残ります。
• キャプチャは作業ディレクトリの.ui-diff/に保存されます。このフォルダはgitでは無視されます。
• $UI_DIFFを引数なしで実行すると、すべてのフラグが表示されます。