vlmkit

vrt

vlmkit は、Playwright と pixelmatch を基盤とする TypeScript 製のビジュアル回帰テスト用ツールキットです。単純なピクセル差分だけでなく、エージェントが扱いやすいシグナルも表示します。計算済みスタイルの差分を全画面共通とブレークポイントごとに分けて示すほか、コンポーネントのバウンディングボックスを基準にセクションごとの diffRatio を算出し、最も差分の大きいビューポートのスクリーンショットパスをその場で表示します。また、任意で VLM が出力する CHANGE リストを LLM による CSS 修正のステップに渡せます。

ソース：https://github.com/mizchi/vlmkit。CHANGELOG と旧 CLI から新 CLI への対応表：CHANGELOG.md。

このスキルを呼び出すタイミング

• エージェントが CSS／HTML／コンポーネントを編集し、「見た目に何が、どこで変わったか」を知りたい場合。
• リファクタリングの PR を監査し、意図しないレイアウトのずれがないか確認する場合。
• 2 つの URL（開発サーバーとプレビュー環境、またはベースラインとバリアントなど）を比較する場合。
• PR 全体にわたる回帰を検出する CI ゲートが必要な場合。
• フレームワークや CSS ライブラリを入れ替え、書き換え後も見た目が同等か確認する場合。

呼び出さない場合

• 純粋なデータ構造のスナップショットテスト（Jest のスナップショットを使用してください）。
• CLS／LCP／FCP 以外の Lighthouse／Web Vitals（Lighthouse を直接使用してください）。
• 差分コンポーネントを使わないブラウザードライバー専用のフロー（Playwright Test を使用してください）。
• AI が生成したスクリーンショットの内容が正しいか確認する場合（review-image のようなビジョン LLM ツールを使用してください）。

インストール

前提条件：Node 24 以降。 CLI とワークスペースの各パッケージは、いずれも Node の --experimental-strip-types（24 以降ではデフォルトで有効）に依存しています。 Node 22 では動作しません。インストール前に node --version で確認してください。アップグレードするには、nvm install 24 && nvm use 24（または fnm／volta／お好みのバージョン管理ツール）を使用してください。

事前チェック：scripts/doctor.sh を実行すると、Node のバージョン、Playwright Chromium、任意の API キー、インストール済みのサブスキルをまとめて確認できます。セットアップ段階に応じた 2 種類の実行方法があります。

• インストール前（apm がまだない場合）：curl で一度だけ実行 — bash <(curl -sSL https://raw.githubusercontent.com/mizchi/skills/main/vlmkit/scripts/doctor.sh)
• インストール後（apm install -g mizchi/skills/vlmkit/vlmkit の実行後）：ローカルのコピーを実行 — bash ~/.claude/skills/vlmkit/scripts/doctor.sh

重大度のルール：FAIL 扱いとなるのは Node 24 以降とPlaywright Chromiumだけです（終了コード 0 を阻止します）。vrt CLI がまだ PATH にない場合を含め、それ以外はすべて設計上 WARN です。このスクリプトはインストール途中でも実行できることを想定しているためです（初回実行時に vlmkit CLI が WARN となるのは想定どおりです。まずすべての FAIL を解消してから vrt をインストールし、再実行すると WARN が解消されます）。

# CLI (global)
pnpm add -g @mizchi/vrt
# or per-project
pnpm add -D @mizchi/vrt
npx playwright install chromium

# Library packages (deep imports via .ts source)
pnpm add @mizchi/vlmkit-core @mizchi/vlmkit-capture @mizchi/vlmkit-markup @mizchi/vlmkit-ai

CLI チートシート（0.5.0 の動詞グループ）

以下で使用する I/O の規則：--output <dir> には常にディレクトリパスを指定します（エンジンはその中に diff-report.json とビューポートごとの PNG を書き込みます）。vlmkit diff agent はデフォルトで Markdown を標準出力に書き込みます。ファイルに書き込むには --out <path> を指定してください。 位置引数を 2 つ取るコマンド（例：vlmkit diff html <baseline> <variant>）には、ローカルファイルパス 2 つ、または URL 2 つを指定できます。明示的に指定する場合は --url／--current-url を使用してください。

# Diff
vlmkit diff html <baseline> <variant> --output reports/        # → reports/diff-report.json + PNGs (dir output)
vlmkit diff agent reports/diff-report.json [--out diff.md]     # → stdout (default) or --out path
vlmkit diff png  base.png current.png                          # Direct PNG diff (positional files)
vlmkit diff elements --selector .card …                        # Element-level shift isolation
vlmkit diff browsers <url>                                     # Chromium / Firefox / WebKit parity
vlmkit diff runs <dirs...>                                     # Aggregate N VRT runs

# Snapshot (baseline + diff lifecycle)
vlmkit snapshot <url1> [url2]... --output snapshots/
vlmkit snapshot approve                                        # Promote current → baseline
vlmkit snapshot stability <url...> --iterations 5              # FP-rate measurement
vlmkit snapshot flipbook --output snapshots/                   # Embed PNGs in a self-contained HTML

# Check (CI gates)
vlmkit check a11y contrast|touch|focus <html>                  # WCAG scans
vlmkit check tokens <html>                                     # Design-token scale conformance
vlmkit check theme  <html>                                     # prefers-color-scheme parity
vlmkit check perf   <html>                                     # CLS / LCP / FCP

# Inspect / Stress / Scan / Build
vlmkit inspect interact|explore|smoke <html|url>
vlmkit stress  i18n|media  <html>
vlmkit scan    component|breakpoints  <…>
vlmkit build   component <target.png> <current.html>           # Markup-from-screenshot loop

# Migration (framework / CSS-library swap audit). Three modes:
#   compare  — deterministic side-by-side audit; the default. Start here.
#   blind    — variant agent never sees baseline pixels (forces convergence from spec text alone).
#   subagent — dispatched subagent runs `compare` + writes a verdict.
# `--mask` and `--output` work identically across all three modes.
vlmkit migration compare|blind|subagent <baseline> <variant> --output reports/

# Long-running / stateful
vlmkit watch       <baseline> <variant>                        # File-watcher inner loop
vlmkit manifest    add|list|rm|check                           # Approval rules
vlmkit diff-pr     pin|verify|post                             # PR CI gate
vlmkit baseline    pin|verify|post|list|rm                     # Canonical alias of diff-pr

0.4.x の単一トークン形式のコマンド（vrt compare、vrt png-diff、vrt theme-parity など）は、引き続き非推奨の互換コマンドとして利用できます。これらのコマンドは 1 行のヒントを表示して、後続の処理を転送します。

サブスキルの振り分け

設計上、リポジトリは2つあります：このオリエンテーションスキルは mizchi/skills（汎用 スキル）にあり、vrt 固有の5つのサブスキルは .claude/skills/ 配下の mizchi/vlmkit/vlmkit にあります。以下の2つの apm install パスが異なっているのは、 対象のリポジトリが異なるためです。これは意図的なもので、誤記ではありません。

サブスキルをインストールしなくても、CLI は完全に動作します — サブスキルは、特定のタスクの形に合わせた振り分けを詳しくする、エージェント向けの参考資料です。エージェントに追加のコンテキストが必要な場合にのみインストールしてください。コマンドラインから vrt を実行するエンドユーザーには必要ありません。

対象範囲の境界：このオリエンテーションスキルが扱うのは 振り分け までです。読み込むサブスキルがわかったら、詳細な運用情報 — すべてのフラグ一覧、永続化パス（例：回帰監視の .vrt/last-diff-for-agent.json）、モードごとの動作、出力スキーマ — は対応するサブスキルに記載されています。エージェントにその詳細が必要な場合は、上記の apm コマンドでインストールしてください。

apm install mizchi/vlmkit/.claude/skills/<skill-name>

タスクの形に合わせて選びます：

サブスキル	使用する場面	エントリーワークフロー
vrt-visual-diff	単発で「この CSS の編集でピクセルに変化があったか、どこにあったか」を確認する	vlmkit diff html → vlmkit diff agent
vrt-regression-watch	実行をまたいだドリフト検出の CI ゲート／スケジュール実行	vlmkit diff agent --previous --fail-on-regression
vrt-migration-eval	フレームワーク／CSS ライブラリ／ビルドシステムの切り替え監査（意図的に大きな差分を生成）	vlmkit migration compare|blind|subagent
vrt-markup-synth	スクリーンショットからの HTML/CSS 生成、トークン／テーマ／i18n／a11y の監査	vlmkit build|scan|check|stress
vrt-css-fix-loop	VLM + LLM による CSS 自動修正ループ	fix-loop.ts (VRT_VLM_MODEL=…)

振り分けのヒューリスティック（ユーザーがタスクを伝えたら、自分に問いかけます）：

Is the markup deliberately different (rewrite / framework swap)?
├─ yes → vrt-migration-eval
└─ no
   ├─ Need to detect change between runs over time? → vrt-regression-watch
   ├─ Want a CSS-fix loop (auto-repair)?          → vrt-css-fix-loop
   ├─ Building from a screenshot / token audit?   → vrt-markup-synth
   └─ One-shot "what changed"                     → vrt-visual-diff

出力の構成

vlmkit diff html は次を書き込みます：

<output>/
├── diff-report.json            # canonical machine input for diff agent
├── migration-report.json       # legacy alias, byte-identical (will be removed)
├── diff-mobile.png             # per-viewport pixel diff
├── diff-desktop.png
└── diff-wide.png

続いて vlmkit diff agent <report.json> は、次の構成の Markdown を出力します：

# VRT diff (for agent)

### Diff by viewport (worst first)
| Viewport | Diff | Dominant category | Categories | Shift bands |
| ...

### Verified deltas (computed-style) × viewport     ← HOISTED to #2
#### Universal pairs         ← fix the base rule
#### Breakpoint-gated pairs  ← fix or add @media rule

### Per-section diffRatio
### Heuristic fix candidates

先頭にまとめられた 検証済みの差分 が重要なシグナルです — まず Universal ペアを読み、次に Breakpoint で制御された項目を読み、その後 Per-section を詳しく確認します。

よくある注意点

• マスキングは重要です。 実行のたびに変動する要素には、--mask ".marquee,.timestamp, [data-testid='live-counter']" を指定してください。 予期しないベースラインノイズの差分は、実際の回帰ではなく、マスクの指定漏れが原因であることがほとんどです。
• 出力先はファイルではなくディレクトリです。 --output reports/ を指定すると、 reports/diff-report.json と PNG が生成されます。vlmkit diff agent にはディレクトリではなく、JSON のパスを渡してください。
• Playwright のインストールが必要です。 初回実行時に "browser not found" とエラーが出た場合は、npx playwright install chromium を実行してください。
• マスクなしで同じ URL 同士を比較すると、誤検知のベースラインになります。 差分%のしきい値を信頼する前に、--mask が変動する要素をすべて検出できることを確認するために使ってください。
• dist バイナリはバンドルされています。 dist/vlmkit.mjs には、分割されたすべてのリーフコードが含まれています。インストール時にソースへの依存関係はありません。

環境変数

変数	用途	デフォルト
VRT_LLM_PROVIDER	fix-loop 用の LLM プロバイダー（gemini / openrouter / anthropic）	gemini
VRT_LLM_MODEL	LLM モデルの上書き	プロバイダーのデフォルト
VRT_VLM_MODEL	VLM モデル（OpenRouter の ID、または gemini:/claude: プレフィックス）	bytedance/ui-tars-1.5-7b
OPENROUTER_API_KEY / GEMINI_API_KEY / ANTHROPIC_API_KEY	プロバイダーごとの認証情報	—
VRT_CAPTURE_BACKEND	local（デフォルトの Playwright）または cloudflare（Browser Run）	local
DEBUG_VRT	詳細なログ出力	未設定

ライブラリの使用（vrt-core / vrt-capture / vrt-markup / vrt-ai）

CLI の機能では足りない場合は、該当するパッケージをディープインポートします：

import { compareScreenshots } from "@mizchi/vlmkit-core/heatmap.ts";
import { discoverViewports }  from "@mizchi/vlmkit-capture/viewport-discovery.ts";
import { extractComponents }  from "@mizchi/vlmkit-markup/component/component-extract.ts";
import { askVlm }             from "@mizchi/vlmkit-ai";

@mizchi/vlmkit-core の軽量な機能（画像／DOM／a11y のプリミティブ）には、Playwright への依存関係がありません。その他の3つのパッケージは、推移的に Playwright を取り込みます。

問題の報告／コントリビューション

• 問題／機能リクエスト：https://github.com/mizchi/vlmkit/issues
• ソース：https://github.com/mizchi/vlmkit
• PR を作成する前のスモークゲート：bash scripts/smoke-dist.sh（厳格。バンドルされた dist/vlmkit.mjs に対して 11 個のプローブを実行します）。