# 自架視覺回歸測試（VRT）工具包

這是一套自己寫的視覺回歸測試，用來取代 Chromatic / Percy 這類 SaaS。Playwright 截圖，pixelmatch 逐像素比對，報告是一份離線的 HTML，全部在本機或內網跑，截圖不會離開機器。

- 這份說明：`/notes/vrt/README.md`
- 全部程式碼合成一個檔（給 AI 讀這個就夠）：`/notes/vrt/kit.md`
- 個別原始檔：`/notes/vrt/kit/` 底下，路徑和專案裡要放的位置一樣（`gitlab-ci.yml` 放進專案時要改名成 `.gitlab-ci.yml`）

---

## 給 AI 的指示（請先讀這段）

1. 程式碼是完整、已驗證可以跑的版本。請原封不動複製到專案，不要重寫、不要「簡化」、不要換成別的套件。
2. 你要做的事是「接到專案的頁面和 component 上」，照「需要依專案修改的地方」那一節一步一步做，只改那裡列出的位置，其他邏輯保持原樣。
3. 依賴只有 `@playwright/test`、`pixelmatch`、`pngjs`，不要額外引入 reg-cli、jest-image-snapshot、looks-same 之類的套件。
4. 比對報告頁已經做好了，就是 `scripts/vrt/report.html`，不要自己另外做比對頁面，也不需要讀懂或修改它。它是模板，裡面的 `__VRT_DATA__` 會被 `compare.mjs` 替換成資料，不要刪掉這個字串。
5. 如果 CI 不是 GitLab，請照「CI 的約定」一節改寫 CI 設定和 `ci-comment.mjs`，其他檔案不用動。

---

## 核心想法

視覺測試失敗的原因幾乎都是「截圖本身不穩定」，不是比對演算法不夠聰明，所以這套的力氣都花在讓截圖可重現：

1. 基準(baseline)不存檔、不手動維護。每次都用 `git worktree` 把「目前分支從 main 分出來的那個 commit」(merge-base) 取出來，現場 build、現場拍。所以差異永遠等於「這個分支改了什麼」，別人後來合進 main 的東西不會混進來，也沒有「接受 baseline」這個動作，差異符合預期就直接核准 MR。
2. 兩邊在同一個環境拍。Mac 和 Linux 的字型渲染不同，CI 一律用 Playwright 官方 Docker image，基準和目前版本都在同一個容器裡拍。
3. 固定所有會變的東西：`page.clock` 固定時間、`page.route` mock 前端 API、擋掉 GA 等第三方、等字型與圖片載完、關掉動畫和游標，真的無法固定的區塊用 mask 蓋掉。
4. 連拍到兩張完全相同才存檔。兩張不一樣時會重新等一輪網路與圖片再拍，連拍 5 次都不一樣就讓測試失敗，並把最後兩張存到 `.vrt/unstable/`，看圖就知道是哪一塊在動，而不是存下一張會造成假差異的圖。
5. 一律用 production build 截圖(`next build && next start`)，dev mode 有 overlay，行為也不同。
6. 分岔點的截圖會快取在 `.vrt/expected`，key 是「commit + Playwright 版本 + 平台 + playwright.config.ts 與 tests/ 的 hash」，四個都一樣才沿用，否則重拍。

## 流程

```
scripts/vrt.sh test
  ├─ 算出分岔點 commit（VRT_BASE_SHA，或 git merge-base HEAD main）
  ├─ key 相同 → 沿用 .vrt/expected
  │  key 不同 → git worktree 取出分岔點 → npm ci（lockfile 沒變就沿用）→ playwright 拍到 .vrt/expected
  ├─ playwright 拍目前程式碼 → .vrt/actual
  └─ node scripts/vrt/compare.mjs
       ├─ pixelmatch 逐張比對（尺寸不同時補透明邊再比）
       ├─ 差異像素以 8px 格子分群成「變更區域」，重疊的框合併
       └─ 輸出 .vrt/report/{index.html, results.json, junit.xml, images/}
```

exit code：`0` 沒差異、`1` 有差異、`3` 截圖失敗（失敗時不會覆蓋上次的結果）。

## 安裝

```bash
npm i -D @playwright/test pixelmatch pngjs
npx playwright install chromium
chmod +x scripts/vrt.sh
```

`package.json` 加：

```json
"scripts": {
  "vrt": "scripts/vrt.sh test",
  "vrt:review": "scripts/vrt.sh review"
}
```

`.gitignore` 加：

```
/.vrt/
/test-results/
/playwright-report/
```

日常使用：

```bash
npm run vrt          # 拍分岔點與目前程式碼並比對
npm run vrt:review   # 開報告
VRT_BASE_REF=develop npm run vrt   # target 分支不是 main 時
```

`.vrt/report/` 是自給自足的靜態報告(HTML + 圖片)，可以整個資料夾當成 CI artifact 保存。報告有四種模式：並排(同步捲動)、差異、滑桿、疊圖。快捷鍵：`J`/`K` 切換快照，`N`/`P` 跳到下一處 / 上一處變更，按住 `Space` 暫時看基準圖，`O` 總覽，`H` 開關差異標示，`F` 切換符合寬度 / 100%。

## 檔案

| 檔案 | 用途 | 要不要改 |
|---|---|---|
| `playwright.config.ts` | 視窗尺寸(目前只拍 desktop 1440×900)、locale、時區、啟動 production build | 改 build / start 指令 |
| `tests/visual.spec.ts` | 要截圖的頁面與互動狀態清單 | 一定要改，列出你的路由 |
| `tests/vrt.ts` | 固定時間、mock API、擋第三方、等載入、連拍穩定檢查 | 改 mock 的 API |
| `scripts/vrt.sh` | 拍分岔點與目前版本、快取、比對、開報告 | 不用改 |
| `scripts/vrt/compare.mjs` | 像素比對、變更區域分群、產生報告與 JUnit | 不用改 |
| `scripts/vrt/report.html` | 報告模板，單一檔案、無外部依賴 | 不用改 |
| `scripts/vrt/ci-comment.mjs` | 在 GitLab MR 留下（或更新）結果留言 | 非 GitLab 要改 |
| `scripts/vrt/render-cards.mjs` | 把每個差異渲染成卡片圖，貼進 MR 留言 | 不用改 |
| `gitlab-ci.yml` | GitLab CI job（放進專案時改名 `.gitlab-ci.yml`） | 非 GitLab 要改 |

## 需要依專案修改的地方

照順序做，每一步都有要改的檔案和範例。

### 1. 列出要截圖的頁面：`tests/visual.spec.ts`

先找出專案有哪些頁面(App Router 用 `find app -name page.tsx`，Pages Router 看 `pages/`)，把主要頁面放進 `routes`。動態路由(`[slug]`、`[id]`)要填實際存在的網址，挑一兩個有代表性、資料不太會變的。

```ts
const routes = [
  { name: "home", path: "/" },
  { name: "product-list", path: "/products" },
  { name: "product-detail", path: "/products/12345" }, // 動態路由填實際的 id
];
```

`name` 只能用英數、底線、連字號，不能重複。

### 2. 找出瀏覽器端會打的 API，mock 掉：`tests/vrt.ts` 的 `stabilize()`

搜尋 `"use client"` 的檔案裡的 `fetch(`、`axios`、`useSWR`、`useQuery`，把每個 API 用 `page.route` 回傳固定資料，範例裡的 `**/api/stats` 換掉。

- 會寫入資料的(POST、PUT，例如瀏覽數、點擊追蹤、按讚)一定要 mock，不然每次測試都在寫正式資料。
- 會讀資料而且每次結果不同的(線上人數、推薦、隨機排序)也要 mock。
- 第三方網域的正規表達式補上公司用的追蹤、客服 widget、廣告。

```ts
await page.route("**/api/track", (route) => route.fulfill({ json: { ok: true } }));
await page.route("**/api/recommendations", (route) =>
  route.fulfill({ json: { items: [{ id: 1, name: "固定商品" }] } }),
);
```

固定時間 `2026-01-01T10:00:00+08:00` 可以留著。

### 3. 找出 build 時需要的環境變數

先只給 `NEXT_PUBLIC_*` 跑一次 `npm run build`，失敗的地方就是 build 時在 server 端讀資料的頁面。需要密鑰的(例如資料庫的 service key)，CI 給一個假值就好，前提是程式讀取失敗時有安全的預設值；沒有預設值會讓 build 直接失敗的，先在程式裡補上。不要把真的密鑰放進 CI。

### 4. 遮掉無法 mock 的 component

時鐘、倒數計時、輪播、廣告、影片這類一直在動的 component，在它最外層加 `data-testid`，再傳給 `snap()` 的 `mask`，截圖時會蓋成灰色。

```tsx
// component 裡
<div data-testid="countdown">...</div>
```

```ts
// tests/visual.spec.ts
await snap(page, name, testInfo.project.name, {
  mask: [page.getByTestId("countdown"), page.getByTestId("banner-carousel")],
});
```

### 5. 重要 component 的互動狀態(選用)

下拉選單、彈窗、表單錯誤、hover 這類只有操作後才看得到的樣子，各寫一個 test，操作完再截圖：

```ts
test("header: user menu open", async ({ page }, testInfo) => {
  await page.goto("/");
  await page.getByRole("button", { name: "會員" }).click();
  await snap(page, "header--menu-open", testInfo.project.name);
});

test("login: validation error", async ({ page }, testInfo) => {
  await page.goto("/login");
  await page.getByRole("button", { name: "登入" }).click();
  await snap(page, "login--error", testInfo.project.name);
});
```

### 6. 需要登入的頁面

在 `beforeEach` 裡登入，或用 Playwright 的 `storageState` 存一份登入狀態，測試帳號請用專門的帳號，不要用個人帳號。

### 7. 啟動指令與預設分支

- `playwright.config.ts` 的 `webServer.command` 換成專案的 build + start 指令，port 用 `VRT_PORT`（預設 4173）。不是 Next.js 的話，例如 Vite，就改成 `npm run build && npx vite preview --port ${port}`。`cwd: appDir` 一定要保留，基準版本靠它在 worktree 裡啟動。
- 預設分支不是 `main`：用 `VRT_BASE_REF` 指定，或改 `scripts/vrt.sh` 裡的預設值。

### 8. 驗收

1. 什麼都不改，跑 `npm run vrt`，結果必須是全部「無變化」。有差異或「連拍不一致」，回到第 2、4 步把動態的東西 mock 或遮掉。
2. 故意改一個 component 的樣式(例如按鈕顏色)，不用 commit，再跑一次，應該只有用到那個 component 的頁面出現差異，報告上的綠框框在那個 component 上。
3. 兩項都對了再接 CI。

## CI 的約定

CI 只需要做這幾件事，換成 GitHub Actions、Jenkins 都一樣：

1. 用 `mcr.microsoft.com/playwright:v<與 @playwright/test 完全相同的版本>-noble` 當執行環境。
2. checkout 要拿完整歷史(GitLab `GIT_DEPTH: 0`、GitHub `fetch-depth: 0`)，不然算不出 merge-base。
3. 執行 `VRT_BASE_SHA=<MR 的 diff base sha> VRT_BASE_NAME=<target 分支名> scripts/vrt.sh test`。
4. exit code `1` = 有視覺差異，標成警告、等人審閱，不擋合併；其他非 0 = 真的壞掉，讓 job 失敗。
5. 不管成功失敗都上傳 `.vrt/report/` 與 `.vrt/unstable/` 當 artifact，`junit.xml` 給 CI 的測試報告區塊。
6. （選用）`node scripts/vrt/ci-comment.mjs` 在 MR 留言。它需要 `VRT_GITLAB_TOKEN`(api scope)，沒設定就只印 log、不會讓 job 失敗。

GitLab 對應的變數：`CI_MERGE_REQUEST_DIFF_BASE_SHA`、`CI_MERGE_REQUEST_TARGET_BRANCH_NAME`。GitHub Actions 對應的是 `github.event.pull_request.base.sha` 與 `github.base_ref`，並且要把 `ci-comment.mjs` 改成呼叫 GitHub 的 issue comment API。

## 常見坑

- `page.route()` 只攔得到瀏覽器發出的請求。Server Component 或 SSR 在伺服器端 fetch 的資料攔不到，要用環境變數讓伺服器改打 mock server，或在測試環境改接 fixture。
- `next/font/google` 在 build 時需要外網，內網 CI 要改用 `next/font/local`。
- Playwright 版本一升級，抗鋸齒可能有細微變化，所以版本也是快取 key 的一部分，升級後第一次會自動重拍基準。
- 截圖一直報「連拍 5 次都不一致」，代表頁面上還有東西在動，通常是輪播、skeleton、相對時間("3 分鐘前")，請 mock 或 mask 掉，不要調高次數。先打開 `.vrt/unstable/` 裡的兩張圖對照，CI 上在 job 的 artifacts 裡。
- build 時在 server 端讀資料、需要密鑰的頁面(例如用 service role 讀資料庫)：CI 不要給真的密鑰，給一個假值，前提是程式讀取失敗時有安全的預設值(例如當成 0 筆)。基準和目前版本兩邊會一樣，比對是穩定的。沒有預設值會直接讓 build 失敗的，就要先在程式裡補上。
- 會寫入資料的前端 API(來訪人數、點擊追蹤、按讚)一定要用 `page.route` mock 掉，不然每次 CI 都在灌正式資料。
- 兩邊都對同一個正式資料庫讀資料是可以的：基準和目前版本在同一個 job 裡前後幾分鐘拍完，資料一樣，不用另外準備測試資料。
- 長頁面的 lazy 圖片、載入失敗後才換上的 fallback 圖片，`tests/vrt.ts` 都已經處理，不要拿掉 `img.loading = "eager"` 和連拍迴圈裡的 `waitForStable`。
- 快照名稱只能用英數、底線、連字號，重複的名稱會直接報錯，避免兩個測試互相覆蓋。
- 本機在 Mac 拍的結果不要拿去跟 CI 比，兩邊一定要在同一個環境拍，這套的做法本來就是每次兩邊一起重拍。

---

# 完整原始碼

以下每個檔案都是完整內容，照標題的路徑存檔即可。`gitlab-ci.yml` 存成 `.gitlab-ci.yml`，`scripts/vrt.sh` 記得 `chmod +x`。

## `playwright.config.ts`

```ts
import { defineConfig, devices } from "@playwright/test";

// VRT_APP_DIR：要啟動哪一份程式碼（預設當前目錄；比對 main 時指向 git worktree）
// VRT_OUT：截圖輸出目錄（.vrt/expected 或 .vrt/actual）
const appDir = process.env.VRT_APP_DIR ?? ".";
const port = Number(process.env.VRT_PORT ?? 4173);

export default defineConfig({
  testDir: "./tests",
  fullyParallel: true,
  workers: process.env.CI ? 2 : undefined,
  reporter: [["list"]],
  use: {
    baseURL: `http://localhost:${port}`,
    locale: "zh-TW",
    timezoneId: "Asia/Taipei",
    colorScheme: "light",
  },
  projects: [
    { name: "desktop", use: { ...devices["Desktop Chrome"], viewport: { width: 1440, height: 900 } } },
  ],
  webServer: {
    // 一律用 production build 截圖，dev mode 有 overlay 且行為不同
    command: `npm run build && npx next start -p ${port}`,
    cwd: appDir,
    port,
    reuseExistingServer: false,
    timeout: 180_000,
  },
});
```

## `tests/vrt.ts`

```ts
import fs from "node:fs";
import path from "node:path";
import type { Locator, Page } from "@playwright/test";

const OUT_DIR = process.env.VRT_OUT ?? ".vrt/actual";
const MAX_SHOTS = 5; // 最多拍幾次來等畫面穩定

// 固定所有「每次都不一樣」的東西，讓截圖可重現
export async function stabilize(page: Page) {
  // 固定時間：所有 Date.now() / new Date() 都回傳這個時間點
  await page.clock.setFixedTime(new Date("2026-01-01T10:00:00+08:00"));

  // Mock 前端 API：回傳固定 fixture
  await page.route("**/api/stats", (route) =>
    route.fulfill({ json: { online: 128, orders: 42 } }),
  );

  // 擋掉第三方腳本（GA、客服 widget、廣告⋯）
  await page.route(/googletagmanager|google-analytics|hotjar|intercom/, (route) => route.abort());
}

export async function waitForStable(page: Page) {
  await page.waitForLoadState("networkidle");
  await page.evaluate(() => document.fonts.ready);
  // 等所有圖片（含 next/image lazy load）載入
  await page.evaluate(async () => {
    // lazy 圖片要捲到附近才會載入，長頁面中段的圖光是捲到底再捲回來不會觸發，會一直等不到
    for (const img of Array.from(document.images)) img.loading = "eager";
    window.scrollTo(0, document.body.scrollHeight);
    await Promise.all(
      Array.from(document.images)
        .filter((img) => !img.complete)
        .map((img) => new Promise((r) => { img.onload = img.onerror = r; })),
    );
    window.scrollTo(0, 0);
  });
}

export async function snap(
  page: Page,
  name: string,
  projectName: string,
  opts: { mask?: Locator[] } = {},
) {
  if (!/^[\w-]+$/.test(name)) throw new Error(`快照名稱只能用英數、底線、連字號：${name}`);
  await waitForStable(page);

  // 連續兩次截圖完全相同才算穩定；一直不穩定就讓測試失敗，不要存下會造成假差異的圖
  let prev: Buffer | null = null;
  let shot: Buffer | null = null;
  for (let n = 0; n < MAX_SHOTS; n++) {
    shot = await page.screenshot({
      fullPage: true,
      animations: "disabled",
      caret: "hide",
      mask: opts.mask,
      maskColor: "#a1a1aa",
    });
    if (prev?.equals(shot)) {
      const file = path.join(OUT_DIR, projectName, `${name}.png`);
      fs.mkdirSync(path.dirname(file), { recursive: true });
      try {
        // wx：檔案已存在就報錯，避免兩個測試用了同一個名稱而互相覆蓋
        fs.writeFileSync(file, shot, { flag: "wx" });
      } catch (e) {
        if ((e as NodeJS.ErrnoException).code === "EEXIST") throw new Error(`快照名稱重複：${projectName}/${name}`);
        throw e;
      }
      return;
    }
    prev = shot;
    // 不一樣時重新等一輪網路與圖片：載入失敗後才換上的圖片（例如 next/image 的 fallback）是新的 <img>，要重新等
    await page.waitForTimeout(200);
    await waitForStable(page);
  }

  // 把最後兩張不一樣的截圖留在 .vrt/unstable/，CI 會一起上傳，直接比對就知道是哪一塊在動
  const side = path.basename(OUT_DIR).replace(/\.tmp$/, "");
  const dir = path.join(path.dirname(OUT_DIR), "unstable", side, projectName);
  fs.mkdirSync(dir, { recursive: true });
  fs.writeFileSync(path.join(dir, `${name}-1.png`), prev!);
  fs.writeFileSync(path.join(dir, `${name}-2.png`), shot!);
  throw new Error(
    `${projectName}/${name}：連拍 ${MAX_SHOTS} 次畫面都不一致，請把動態區塊 mock 掉或加進 mask（最後兩張在 .vrt/unstable/${side}/${projectName}/）`,
  );
}
```

## `tests/visual.spec.ts`

```ts
import { test } from "@playwright/test";
import { snap, stabilize } from "./vrt";

// 要保護的頁面清單：接手專案時先把主要路由都列進來
const routes = [
  { name: "home", path: "/" },
  { name: "pricing", path: "/pricing" },
];

test.beforeEach(async ({ page }) => {
  await stabilize(page);
});

for (const { name, path } of routes) {
  test(`page ${name}`, async ({ page }, testInfo) => {
    await page.goto(path);
    await snap(page, name, testInfo.project.name, {
      // 無法 mock 的動態區塊直接遮罩
      mask: [page.getByTestId("clock")],
    });
  });
}

// 互動狀態也可以截：hover、展開選單、表單錯誤⋯
test("home: button hover", async ({ page }, testInfo) => {
  await page.goto("/");
  await page.getByRole("button", { name: "加入購物車" }).first().hover();
  await snap(page, "home--hover", testInfo.project.name, {
    mask: [page.getByTestId("clock")],
  });
});
```

## `scripts/vrt.sh`

```bash
#!/usr/bin/env bash
# 自架版視覺回歸測試（Chromatic 替代方案）
# 和 MR 一樣的比法：拍「target 分岔點」與「目前程式碼」，兩邊比對，一看就知道這個分支改了什麼。
#
#   scripts/vrt.sh test     拍分岔點（git worktree）與目前程式碼，比對並產生報告；有差異時 exit 1
#   scripts/vrt.sh review   開啟報告
#
#   VRT_BASE_REF   target 分支（預設 main）；分岔點 = git merge-base HEAD $VRT_BASE_REF
#   VRT_BASE_SHA   直接指定分岔點 commit（CI 用 $CI_MERGE_REQUEST_DIFF_BASE_SHA）
set -euo pipefail

ROOT="$(cd "$(dirname "$0")/.." && pwd)"
VRT="$ROOT/.vrt"
cd "$ROOT"

capture() { # $1=輸出目錄 $2=程式碼目錄；先拍到暫存目錄，成功才取代，失敗回傳 3（與「有差異」的 1 區分）
  rm -rf "$1.tmp"
  VRT_OUT="$1.tmp" VRT_APP_DIR="$2" npx playwright test || { rm -rf "$1.tmp"; echo "截圖失敗" >&2; exit 3; }
  rm -rf "$1"
  mv "$1.tmp" "$1"
}

prepare_worktree() { # $1=commit，印出 worktree 路徑
  local wt="${TMPDIR:-/tmp}/vrt-base/$(basename "$ROOT")"
  if [ -d "$wt" ] && git -C "$wt" rev-parse >/dev/null 2>&1; then
    # --force + clean：確保 worktree 與該 commit 完全一致（保留 node_modules 等 ignored 檔案）
    git -C "$wt" checkout --quiet --force --detach "$1" >&2
    git -C "$wt" clean -fdq -e .vrt-lock-hash >&2
  else
    rm -rf "$wt"
    git worktree prune
    git worktree add --detach "$wt" "$1" >&2
  fi

  # lockfile 沒變就沿用上次安裝的 node_modules
  local hash; hash="$(shasum "$wt/package-lock.json" | cut -d' ' -f1)"
  if [ ! -d "$wt/node_modules" ] || [ "$(cat "$wt/.vrt-lock-hash" 2>/dev/null)" != "$hash" ]; then
    echo "▸ 在 worktree 安裝依賴⋯" >&2
    (cd "$wt" && npm ci --no-audit --no-fund >&2)
    echo "$hash" > "$wt/.vrt-lock-hash"
  fi
  echo "$wt"
}

base_commit() {
  if [ -n "${VRT_BASE_SHA:-}" ]; then git rev-parse --verify "$VRT_BASE_SHA^{commit}"; return; fi
  local ref="${VRT_BASE_REF:-main}"
  git rev-parse --verify --quiet "$ref^{commit}" >/dev/null || ref="origin/$ref"
  git merge-base HEAD "$ref" || { echo "找不到與 ${VRT_BASE_REF:-main} 的分岔點" >&2; exit 3; }
}

# 分岔點的截圖只在「commit、Playwright 版本、平台、截圖設定」都相同時才沿用
capture_key() { # $1=commit
  local pw; pw="$(node -p 'require("@playwright/test/package.json").version')"
  local spec; spec="$(cat playwright.config.ts $(find tests -type f | sort) | shasum | cut -d' ' -f1)"
  echo "$1 playwright@$pw $(uname -sm | tr ' ' -) spec@${spec:0:12}"
}

case "${1:-}" in
  test)
    rm -rf "$VRT/unstable"
    commit="$(base_commit)"
    sha="${commit:0:7}"
    # 報告上顯示的名稱：直接指定 commit 時就顯示那個 ref，不冒用分支名
    if [ -n "${VRT_BASE_SHA:-}" ]; then ref="${VRT_BASE_NAME:-$VRT_BASE_SHA}"; else ref="${VRT_BASE_NAME:-${VRT_BASE_REF:-main}}"; fi
    key="$(capture_key "$commit")"

    if [ "$(cat "$VRT/expected/.key" 2>/dev/null)" = "$key" ]; then
      echo "▸ 分岔點 $ref $sha 已拍過，沿用"
    else
      echo "▸ 拍攝分岔點 $ref $sha"
      wt="$(prepare_worktree "$commit")"
      capture "$VRT/expected" "$wt"
      echo "$key" > "$VRT/expected/.key"
    fi
    printf '{"ref":"%s","sha":"%s"}\n' "$ref" "$sha" > "$VRT/expected/.meta.json"

    echo "▸ 拍攝目前程式碼"
    capture "$VRT/actual" "$ROOT"
    echo "▸ 比對中"
    set +e
    node "$ROOT/scripts/vrt/compare.mjs"
    status=$?
    set -e
    echo
    echo "  報告：npm run vrt:review"
    exit $status
    ;;

  review)
    report="$VRT/report/index.html"
    [ -f "$report" ] || { echo "還沒有報告，先跑：npm run vrt" >&2; exit 1; }
    case "$(uname)" in
      Darwin) open "$report" ;;
      Linux) xdg-open "$report" >/dev/null 2>&1 || echo "$report" ;;
      *) echo "$report" ;;
    esac
    ;;

  *)
    sed -n '2,10p' "$0"
    exit 1
    ;;
esac
```

## `scripts/vrt/compare.mjs`

```js
// 比對 .vrt/expected 與 .vrt/actual，輸出 .vrt/report（results + 圖片 + index.html）
// 有任何差異（變更、新增、刪除）時 exit 1
import { execSync } from "node:child_process";
import fs from "node:fs";
import path from "node:path";
import { fileURLToPath } from "node:url";
import pixelmatch from "pixelmatch";
import { PNG } from "pngjs";

const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
const VRT = path.join(ROOT, ".vrt");
const EXPECTED = path.join(VRT, "expected");
const ACTUAL = path.join(VRT, "actual");
const REPORT = path.join(VRT, "report");

const THRESHOLD = 0.1; // 單一像素的 YIQ 色差容忍度
const DIFF_COLOR = [0, 240, 180];
const CELL = 8; // 變更區域分群的格子大小（px）
const GAP = 3; // 相距幾格內的變更視為同一區域

function listPngs(dir) {
  if (!fs.existsSync(dir)) return [];
  return fs
    .readdirSync(dir, { recursive: true })
    .filter((f) => f.endsWith(".png"))
    .map((f) => f.split(path.sep).join("/").replace(/\.png$/, ""));
}

const readPng = (file) => PNG.sync.read(fs.readFileSync(file));

// 把圖貼到 W×H 的透明畫布左上角，讓不同尺寸的截圖可以逐像素比對
function pad(png, W, H) {
  if (png.width === W && png.height === H) return png.data;
  const out = Buffer.alloc(W * H * 4);
  for (let y = 0; y < png.height; y++) {
    png.data.copy(out, y * W * 4, y * png.width * 4, (y + 1) * png.width * 4);
  }
  return out;
}

// 把差異像素分群成矩形區域，讓報告可以逐一跳轉
function findRegions(mask, W, H) {
  const cols = Math.ceil(W / CELL);
  const rows = Math.ceil(H / CELL);
  const hot = new Uint8Array(cols * rows);
  for (let y = 0; y < H; y++) {
    for (let x = 0; x < W; x++) {
      if (mask[(y * W + x) * 4 + 3]) hot[Math.floor(y / CELL) * cols + Math.floor(x / CELL)] = 1;
    }
  }
  const seen = new Uint8Array(cols * rows);
  const regions = [];
  for (let i = 0; i < hot.length; i++) {
    if (!hot[i] || seen[i]) continue;
    let [x0, y0, x1, y1] = [Infinity, Infinity, -1, -1];
    const stack = [i];
    seen[i] = 1;
    while (stack.length) {
      const c = stack.pop();
      const cx = c % cols;
      const cy = (c - cx) / cols;
      x0 = Math.min(x0, cx); y0 = Math.min(y0, cy);
      x1 = Math.max(x1, cx); y1 = Math.max(y1, cy);
      for (let dy = -GAP; dy <= GAP; dy++) {
        for (let dx = -GAP; dx <= GAP; dx++) {
          const nx = cx + dx;
          const ny = cy + dy;
          if (nx < 0 || ny < 0 || nx >= cols || ny >= rows) continue;
          const n = ny * cols + nx;
          if (hot[n] && !seen[n]) { seen[n] = 1; stack.push(n); }
        }
      }
    }
    const p = 6;
    const x = Math.max(0, x0 * CELL - p);
    const y = Math.max(0, y0 * CELL - p);
    regions.push({
      x, y,
      w: Math.min(W, (x1 + 1) * CELL + p) - x,
      h: Math.min(H, (y1 + 1) * CELL + p) - y,
    });
  }
  return mergeOverlapping(regions).sort((a, b) => a.y - b.y || a.x - b.x);
}

// 外接矩形可能互相重疊（甚至整個包住另一個），合併後才不會出現重複的編號框
function mergeOverlapping(regions) {
  const rs = regions.map((r) => ({ ...r }));
  for (let merged = true; merged; ) {
    merged = false;
    for (let i = 0; i < rs.length && !merged; i++) {
      for (let j = i + 1; j < rs.length; j++) {
        const a = rs[i], b = rs[j];
        if (a.x < b.x + b.w && b.x < a.x + a.w && a.y < b.y + b.h && b.y < a.y + a.h) {
          const x = Math.min(a.x, b.x), y = Math.min(a.y, b.y);
          rs[i] = { x, y, w: Math.max(a.x + a.w, b.x + b.w) - x, h: Math.max(a.y + a.h, b.y + b.h) - y };
          rs.splice(j, 1);
          merged = true;
          break;
        }
      }
    }
  }
  return rs;
}

function copy(src, rel) {
  const dest = path.join(REPORT, rel);
  fs.mkdirSync(path.dirname(dest), { recursive: true });
  fs.copyFileSync(src, dest);
  return rel;
}

function git(cmd) {
  try { return execSync(`git ${cmd}`, { cwd: ROOT, stdio: ["ignore", "pipe", "ignore"] }).toString().trim(); }
  catch { return null; }
}

function compareOne(id) {
  const [viewport, ...rest] = id.split("/");
  const name = rest.join("/");
  const exp = path.join(EXPECTED, `${id}.png`);
  const act = path.join(ACTUAL, `${id}.png`);
  const item = { id, name, viewport, files: {} };

  if (!fs.existsSync(exp)) {
    const png = readPng(act);
    return { ...item, status: "added", after: { w: png.width, h: png.height },
      files: { after: copy(act, `images/actual/${id}.png`) } };
  }
  if (!fs.existsSync(act)) {
    const png = readPng(exp);
    return { ...item, status: "removed", before: { w: png.width, h: png.height },
      files: { before: copy(exp, `images/expected/${id}.png`) } };
  }

  const a = readPng(exp);
  const b = readPng(act);
  const W = Math.max(a.width, b.width);
  const H = Math.max(a.height, b.height);
  const mask = new PNG({ width: W, height: H });
  const diffPixels = pixelmatch(pad(a, W, H), pad(b, W, H), mask.data, W, H, {
    threshold: THRESHOLD, diffMask: true, diffColor: DIFF_COLOR,
  });

  item.before = { w: a.width, h: a.height };
  item.after = { w: b.width, h: b.height };
  item.files.before = copy(exp, `images/expected/${id}.png`);
  item.files.after = copy(act, `images/actual/${id}.png`);

  if (diffPixels === 0) return { ...item, status: "unchanged", diffPixels: 0, diffRatio: 0, regions: [] };

  const diffRel = `images/diff/${id}.png`;
  fs.mkdirSync(path.dirname(path.join(REPORT, diffRel)), { recursive: true });
  fs.writeFileSync(path.join(REPORT, diffRel), PNG.sync.write(mask));
  item.files.diff = diffRel;
  const regions = findRegions(mask.data, W, H);
  return { ...item, status: "changed", diffPixels, diffRatio: diffPixels / (W * H), regions };
}

const ids = [...new Set([...listPngs(EXPECTED), ...listPngs(ACTUAL)])].sort();
fs.rmSync(REPORT, { recursive: true, force: true });
fs.mkdirSync(REPORT, { recursive: true });

const ORDER = { changed: 0, added: 1, removed: 2, unchanged: 3 };
const items = ids.map(compareOne).sort((a, b) => ORDER[a.status] - ORDER[b.status] || a.id.localeCompare(b.id));

let baseline = null;
try { baseline = JSON.parse(fs.readFileSync(path.join(EXPECTED, ".meta.json"), "utf8")); } catch {}

const results = {
  generatedAt: new Date().toISOString(),
  baseline,
  head: {
    // CI 是 detached HEAD，改用 GitLab 提供的分支名稱
    ref: process.env.CI_MERGE_REQUEST_SOURCE_BRANCH_NAME ?? process.env.CI_COMMIT_REF_NAME ?? git("rev-parse --abbrev-ref HEAD"),
    sha: git("rev-parse --short HEAD"),
    dirty: Boolean(git("status --porcelain")),
  },
  items,
};

fs.writeFileSync(path.join(REPORT, "results.json"), JSON.stringify(results, null, 2));
const template = fs.readFileSync(path.join(path.dirname(fileURLToPath(import.meta.url)), "report.html"), "utf8");
fs.writeFileSync(
  path.join(REPORT, "index.html"),
  template.replace("__VRT_DATA__", () => JSON.stringify(results).replace(/</g, "\\u003c")),
);

// JUnit 報告：GitLab MR 頁面的測試結果區塊會直接顯示
const xml = (v) => String(v).replace(/[<>&"]/g, (c) => ({ "<": "&lt;", ">": "&gt;", "&": "&amp;", '"': "&quot;" })[c]);
const failMsg = {
  changed: (i) => `${(i.diffRatio * 100).toFixed(2)}% 像素不同，${i.regions.length} 處變更`,
  added: () => "新增的快照，沒有基準",
  removed: () => "快照已被移除",
};
const failures = items.filter((i) => i.status !== "unchanged");
fs.writeFileSync(path.join(REPORT, "junit.xml"), `<?xml version="1.0" encoding="UTF-8"?>
<testsuites><testsuite name="視覺測試" tests="${items.length}" failures="${failures.length}">
${items.map((i) => `  <testcase classname="vrt.${xml(i.viewport)}" name="${xml(i.name)}">${i.status === "unchanged" ? "" : `<failure message="${xml(failMsg[i.status](i))}"/>`}</testcase>`).join("\n")}
</testsuite></testsuites>
`);

const count = (s) => items.filter((i) => i.status === s).length;
const icon = { changed: "●", added: "+", removed: "−", unchanged: "✓" };
for (const i of items) {
  const extra = i.status === "changed" ? `  ${(i.diffRatio * 100).toFixed(2)}%  ${i.regions.length} 處` : "";
  console.log(`  ${icon[i.status]} ${i.status.padEnd(9)} ${i.id}${extra}`);
}
console.log(`\n  變更 ${count("changed")} · 新增 ${count("added")} · 刪除 ${count("removed")} · 無變化 ${count("unchanged")}`);
process.exit(items.some((i) => i.status !== "unchanged") ? 1 : 0);
```

## `scripts/vrt/ci-comment.mjs`

```js
// 在 GitLab MR 留下（或更新）視覺測試結果留言
// 需要 CI/CD 變數 VRT_GITLAB_TOKEN（api scope）；沒有設定時只在 log 印出摘要
import fs from "node:fs";
import path from "node:path";
import { fileURLToPath } from "node:url";
import { renderCards } from "./render-cards.mjs";

const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
const REPORT = path.join(ROOT, ".vrt/report");
const MARKER = "<!-- vrt-report -->";
const MAX_CARDS = 8; // 最多附幾張卡片圖
const OPEN_CARDS = 3; // 前幾張直接展開，其餘收合

const {
  VRT_GITLAB_TOKEN: TOKEN,
  CI_API_V4_URL: API,
  CI_PROJECT_ID: PROJECT,
  CI_PROJECT_URL,
  CI_MERGE_REQUEST_IID: MR,
  CI_JOB_ID,
  CI_JOB_URL,
} = process.env;

const resultsFile = path.join(REPORT, "results.json");
const results = fs.existsSync(resultsFile) ? JSON.parse(fs.readFileSync(resultsFile, "utf8")) : null;

async function gitlab(method, url, body) {
  const res = await fetch(`${API}/projects/${PROJECT}${url}`, {
    method,
    headers: { "PRIVATE-TOKEN": TOKEN, ...(body && !(body instanceof FormData) ? { "content-type": "application/json" } : {}) },
    body: body instanceof FormData ? body : body && JSON.stringify(body),
  });
  if (!res.ok) throw new Error(`${method} ${url} → ${res.status} ${await res.text()}`);
  return res.json();
}

async function upload(rel) {
  const form = new FormData();
  form.append("file", new Blob([fs.readFileSync(path.join(REPORT, rel))], { type: "image/png" }), path.basename(rel));
  const { url } = await gitlab("POST", "/uploads", form);
  return url;
}

function buildBody(previews) {
  const reportUrl = `${CI_PROJECT_URL}/-/jobs/${CI_JOB_ID}/artifacts/file/.vrt/report/index.html`;
  if (!results) {
    return `${MARKER}\n### 視覺測試：執行失敗\n\n截圖或比對過程出錯，請看 [job log](${CI_JOB_URL})。如果是「連拍畫面都不一致」，最後兩張截圖在 [artifacts 的 .vrt/unstable/](${CI_JOB_URL}/artifacts/browse/.vrt/unstable/)。`;
  }
  const { items, baseline, head } = results;
  const count = (s) => items.filter((i) => i.status === s).length;
  const changed = items.filter((i) => i.status !== "unchanged");
  const base = `\`${baseline?.ref ?? "baseline"}\` ${baseline?.sha ?? ""}`.trim();
  const cur = `\`${head.ref}\` ${head.sha}`;

  if (!changed.length) {
    return `${MARKER}\n### ✅ 視覺測試：沒有差異\n\n${items.length} 個快照與基準一致。${base} → ${cur}`;
  }

  const label = { changed: "🟠 變更", added: "🔵 新增", removed: "🔴 刪除" };
  const rows = changed.map((i) => {
    const detail = i.status === "changed"
      ? `${(i.diffRatio * 100).toFixed(2)}% · ${i.regions.length} 處${i.before.h !== i.after.h ? ` · 高度 ${i.before.h}→${i.after.h}` : ""}`
      : "";
    return `| ${label[i.status]} | \`${i.name}\` | ${i.viewport} | ${detail} |`;
  });

  // 卡片圖本身已含名稱、視窗、差異比例，前幾張直接展開，其餘收合
  const withCard = changed.filter((i) => previews[i.id]);
  const shown = withCard.slice(0, OPEN_CARDS).map((i) => `![${i.id}](${previews[i.id]})`);
  const rest = withCard.slice(OPEN_CARDS);
  const folded = rest.length
    ? [`<details><summary>其他 ${rest.length} 個快照</summary>\n`, ...rest.map((i) => `![${i.id}](${previews[i.id]})\n`), "</details>"]
    : [];

  return [
    MARKER,
    `### 👀 視覺測試：${changed.length} 個快照需要審閱`,
    "",
    `${base} → ${cur} · 變更 ${count("changed")} · 新增 ${count("added")} · 刪除 ${count("removed")} · 無變化 ${count("unchanged")}`,
    "",
    `**[開啟審閱報告 →](${reportUrl})**`,
    "",
    "| 狀態 | 快照 | 視窗 | 差異 |",
    "|---|---|---|---|",
    ...rows,
    "",
    ...shown.flatMap((md) => [md, ""]),
    ...folded,
    "",
    "<sub>差異符合預期就直接核准 MR；不符合預期請修正後再推。</sub>",
  ].join("\n");
}

async function main() {
  if (!MR) return console.log("不是 MR pipeline，略過留言");
  if (!TOKEN) {
    console.log("未設定 VRT_GITLAB_TOKEN，略過 MR 留言（結果仍會顯示在 MR 的測試報告區塊）");
    return;
  }

  const previews = {};
  const ids = (results?.items ?? []).filter((i) => i.status !== "unchanged").slice(0, MAX_CARDS).map((i) => i.id);
  if (ids.length) {
    try {
      const cards = await renderCards(results, REPORT, ids);
      for (const [id, rel] of Object.entries(cards)) previews[id] = await upload(rel);
    } catch (e) {
      // 圖片失敗時仍然發文字留言
      console.error("卡片圖產生或上傳失敗，改發純文字留言：", e.message);
    }
  }
  const body = buildBody(previews);

  // 同一個 MR 只保留一則結果留言，每次推送就更新它
  const notes = await gitlab("GET", `/merge_requests/${MR}/notes?per_page=100&sort=desc`);
  const existing = notes.find((n) => n.body?.includes(MARKER));
  if (existing) await gitlab("PUT", `/merge_requests/${MR}/notes/${existing.id}`, { body });
  else await gitlab("POST", `/merge_requests/${MR}/notes`, { body });
  console.log(existing ? "已更新 MR 留言" : "已新增 MR 留言");
}

main().catch((e) => {
  // 留言失敗不應該讓整個 job 失敗
  console.error("MR 留言失敗：", e.message);
});
```

## `scripts/vrt/render-cards.mjs`

```js
// 把每個有差異的快照渲染成「卡片」圖片（給 MR 留言用），樣式與審閱報告一致
// 做法：在報告目錄寫一個 card.html，用 Playwright 逐張開啟並截圖
import fs from "node:fs";
import path from "node:path";
import { chromium } from "@playwright/test";

const CARD_HTML = String.raw`<!doctype html>
<html lang="zh-TW"><head><meta charset="utf-8">
<style>
:root {
  --panel: #ffffff; --panel-2: #f7f8fa; --border: #e4e7eb; --text: #16191d; --muted: #69717d; --faint: #9aa1ab;
  --changed: #d97706; --changed-soft: #fff5e3; --added: #2563eb; --added-soft: #e9f0ff;
  --removed: #dc2626; --removed-soft: #fdeded; --diff: rgb(0, 240, 180);
  --checker-a: #eceef1; --checker-b: #f6f7f9; --stage: #eef0f3;
}
* { box-sizing: border-box; margin: 0; padding: 0; }
body { display: inline-block; background: transparent; padding: 12px; font: 13px/1.45 -apple-system, "Segoe UI", "PingFang TC", "Noto Sans CJK TC", "Noto Sans TC", "WenQuanYi Zen Hei", sans-serif; color: var(--text); -webkit-font-smoothing: antialiased; }
.card { width: max-content; background: var(--panel); border: 1px solid var(--border); border-radius: 14px; overflow: hidden;
  box-shadow: 0 1px 2px rgba(16,24,40,.06), 0 8px 24px rgba(16,24,40,.08); }
.head { display: flex; align-items: center; gap: 10px; padding: 14px 18px; border-bottom: 1px solid var(--border); }
.head h1 { font-size: 16px; font-weight: 700; }
.chip { padding: 2px 8px; border-radius: 6px; font-size: 12px; font-weight: 600; background: var(--panel-2); color: var(--muted); border: 1px solid var(--border); }
.chip.changed { background: var(--changed-soft); color: var(--changed); border-color: transparent; }
.chip.added { background: var(--added-soft); color: var(--added); border-color: transparent; }
.chip.removed { background: var(--removed-soft); color: var(--removed); border-color: transparent; }
.stat { margin-left: auto; text-align: right; }
.stat b { font-size: 15px; font-variant-numeric: tabular-nums; }
.stat span { display: block; color: var(--muted); font-size: 12px; }
.body { display: flex; gap: 16px; padding: 16px 18px; background: var(--stage); }
.col { display: grid; gap: 8px; }
.label { display: flex; align-items: center; gap: 6px; font-size: 12px; font-weight: 700; color: var(--muted); }
.label i { width: 8px; height: 8px; border-radius: 50%; }
.frame { position: relative; overflow: hidden; border-radius: 8px; box-shadow: 0 0 0 1px rgba(0,0,0,.06), 0 4px 12px rgba(16,24,40,.08);
  background: repeating-conic-gradient(var(--checker-a) 0 25%, var(--checker-b) 0 50%) 0 0 / 14px 14px; }
.canvas { position: absolute; left: 0; top: 0; }
.canvas img { position: absolute; left: 0; top: 0; display: block; }
.region { position: absolute; border: 2px solid var(--diff); border-radius: 4px; box-shadow: 0 0 0 1px rgba(0,0,0,.2), 0 0 0 6px rgba(0,240,180,.18); }
.region .tag { position: absolute; left: -2px; top: -2px; transform: translateY(-100%); padding: 0 6px; border-radius: 4px 4px 0 0;
  font: 700 11px/16px ui-monospace, Menlo, monospace; background: var(--diff); color: #003b2c; }
.mini { display: grid; gap: 8px; align-content: start; }
.mini .map { position: relative; border-radius: 4px; overflow: hidden; box-shadow: 0 0 0 1px rgba(0,0,0,.08); background: #fff; }
.mini .map img { position: absolute; left: 0; top: 0; width: 100%; opacity: .55; }
.mini .view { position: absolute; border: 2px solid var(--text); border-radius: 2px; background: rgba(22,25,29,.06); }
.mini .dot { position: absolute; background: var(--diff); border-radius: 2px; box-shadow: 0 0 0 1px rgba(0,0,0,.25); }
.foot { display: flex; gap: 16px; padding: 10px 18px; border-top: 1px solid var(--border); color: var(--faint); font-size: 12px; }
.foot b { color: var(--muted); font-weight: 600; }
.foot .r { margin-left: auto; }
</style></head>
<body><div class="card" id="card"></div>
<script>
(async () => {
  const { item: it, base, head } = JSON.parse(decodeURIComponent(location.hash.slice(1)));
  const COL_W = 520, COL_H = 380, MINI_W = 64;
  const esc = (s) => String(s ?? "").replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" })[c]);
  const a = it.before ?? it.after, b = it.after ?? it.before;
  const W = Math.max(a.w, b.w), H = Math.max(a.h, b.h);
  const regions = it.regions ?? [];

  // 選出要放大的視窗：盡量把所有變更框進來，放不下就只框第一處
  const aspect = COL_H / COL_W, pad = Math.round(W * 0.04), minW = Math.min(W, Math.max(W * 0.45, 800)); // 下限避免手機高解析截圖放太大
  const union = (rs) => rs.reduce((u, r) => ({ x0: Math.min(u.x0, r.x), y0: Math.min(u.y0, r.y), x1: Math.max(u.x1, r.x + r.w), y1: Math.max(u.y1, r.y + r.h) }),
    { x0: Infinity, y0: Infinity, x1: -Infinity, y1: -Infinity });
  function windowFor(u) {
    const w = Math.min(W, Math.max(minW, u.x1 - u.x0 + pad * 2, (u.y1 - u.y0 + pad * 2) / aspect));
    const h = w * aspect;
    const cx = (u.x0 + u.x1) / 2, cy = (u.y0 + u.y1) / 2;
    return { x: Math.max(0, Math.min(W - w, cx - w / 2)), y: Math.max(0, Math.min(Math.max(0, H - h), cy - h / 2)), w, h,
      fits: u.y1 - u.y0 + pad * 2 <= h };
  }
  let win = { x: 0, y: 0, w: W, h: W * aspect, fits: true };
  let shown = regions.length;
  if (regions.length) {
    win = windowFor(union(regions));
    if (!win.fits) { win = windowFor(union([regions[0]])); shown = 1; }
  }
  const s = COL_W / win.w;
  const pct = (v, t) => (v / t) * 100 + "%";

  const img = (src, d, cls = "") => '<img class="' + cls + '" src="' + esc(src) + '" style="width:' + pct(d.w, W) + ';height:' + pct(d.h, H) + '">';
  const canvas = (inner) => '<div class="canvas" style="width:' + W * s + 'px;height:' + H * s + 'px;transform:translate(' + (-win.x * s) + 'px,' + (-win.y * s) + 'px)">' + inner + "</div>";
  const boxes = regions.map((r, n) => '<div class="region" style="left:' + pct(r.x, W) + ";top:" + pct(r.y, H) + ";width:" + pct(r.w, W) + ";height:" + pct(r.h, H) + '"><span class="tag">' + (n + 1) + "</span></div>").join("");
  const frame = (inner) => '<div class="frame" style="width:' + COL_W + "px;height:" + COL_H + 'px">' + canvas(inner) + "</div>";

  const STATUS = { changed: "變更", added: "新增", removed: "刪除" };
  const COLOR = { changed: "var(--changed)", added: "var(--added)", removed: "var(--removed)" };
  let cols = "";
  if (it.files.before) cols += '<div class="col"><div class="label"><i style="background:var(--faint)"></i>基準 · ' + esc(base) + "</div>" + frame(img(it.files.before, it.before)) + "</div>";
  if (it.files.after) {
    // 卡片只畫框、不疊綠色遮罩：遮罩會改變顏色（例如紅字被混成黑色），讓人誤判
    const overlay = boxes;
    cols += '<div class="col"><div class="label"><i style="background:' + COLOR[it.status] + '"></i>目前 · ' + esc(head) + "</div>" + frame(img(it.files.after, it.after) + overlay) + "</div>";
  }

  // 全頁縮圖：標出放大視窗與每一處變更的位置
  const ms = Math.min(MINI_W / W, (COL_H) / H);
  const mini = '<div class="mini"><div class="label">全頁</div><div class="map" style="width:' + W * ms + "px;height:" + H * ms + 'px">' +
    '<img src="' + esc(it.files.after ?? it.files.before) + '" style="width:' + pct((it.after ?? it.before).w, W) + '">' +
    regions.map((r) => '<div class="dot" style="left:' + pct(r.x, W) + ";top:" + pct(r.y, H) + ";width:max(3px," + pct(r.w, W) + ");height:max(3px," + pct(r.h, H) + ')"></div>').join("") +
    '<div class="view" style="left:' + pct(win.x, W) + ";top:" + pct(win.y, H) + ";width:" + pct(win.w, W) + ";height:" + pct(Math.min(win.h, H - win.y), H) + '"></div>' +
    "</div></div>";

  const sizeChanged = it.before && it.after && (it.before.w !== it.after.w || it.before.h !== it.after.h);
  const stat = it.status === "changed"
    ? "<b>" + (it.diffRatio * 100).toFixed(2) + "%</b><span>" + regions.length + " 處變更</span>"
    : "<b>" + STATUS[it.status] + "</b><span>" + (it.status === "added" ? "沒有基準可比對" : "目前版本已移除") + "</span>";

  document.getElementById("card").innerHTML =
    '<div class="head"><h1>' + esc(it.name.replace(/--/g, " › ")) + '</h1><span class="chip">' + esc(it.viewport) + '</span><span class="chip ' + it.status + '">' + STATUS[it.status] + '</span><div class="stat">' + stat + "</div></div>" +
    '<div class="body">' + cols + mini + "</div>" +
    '<div class="foot">' + (sizeChanged ? "<span>尺寸 <b>" + it.before.w + "×" + it.before.h + "</b> → <b>" + it.after.w + "×" + it.after.h + "</b></span>" : "") +
    (regions.length > shown ? "<span>放大顯示第 1 處，其餘 " + (regions.length - shown) + " 處請開審閱報告</span>" : "") +
    '<span class="r">綠框＝變更區域</span></div>';

  await Promise.all([...document.images].map((i) => i.complete ? null : new Promise((r) => { i.onload = i.onerror = r; })));
  document.body.dataset.ready = "1";
})();
</script></body></html>`;

/**
 * @param {object} results  compare.mjs 產生的 results.json
 * @param {string} reportDir .vrt/report
 * @param {string[]} ids    要渲染的快照
 * @returns {Promise<Record<string, string>>} id → 卡片圖片相對路徑
 */
export async function renderCards(results, reportDir, ids) {
  reportDir = path.resolve(reportDir);
  const htmlPath = path.join(reportDir, "card.html");
  fs.writeFileSync(htmlPath, CARD_HTML);
  const browser = await chromium.launch();
  const page = await browser.newPage({ viewport: { width: 1400, height: 900 }, deviceScaleFactor: 2 });
  const base = [results.baseline?.ref, results.baseline?.sha].filter(Boolean).join(" ") || "baseline";
  const head = [results.head.ref, results.head.sha].filter(Boolean).join(" ");
  const out = {};
  try {
    for (const [n, id] of ids.entries()) {
      const item = results.items.find((i) => i.id === id);
      const hash = encodeURIComponent(JSON.stringify({ item, base, head }));
      await page.goto(`file://${htmlPath}?n=${n}#${hash}`); // 加 query 強制重新載入
      await page.waitForSelector("body[data-ready]");
      const rel = `images/card/${id}.png`;
      fs.mkdirSync(path.dirname(path.join(reportDir, rel)), { recursive: true });
      await page.locator("body").screenshot({ path: path.join(reportDir, rel), omitBackground: true });
      out[id] = rel;
    }
  } finally {
    await browser.close();
  }
  return out;
}
```

## `.gitlab-ci.yml`

```yaml
# 視覺回歸測試：每個 MR 自動執行
# 以 MR 分岔點（diff base）為基準重新截圖，與 MR 最新版本比對；
# 兩邊都在同一個容器裡截圖，所以不會有 Mac / Linux 字型渲染差異。

workflow:
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

visual-tests:
  stage: test
  # 版本必須與 package.json 的 @playwright/test 一致
  image: mcr.microsoft.com/playwright:v1.63.0-noble
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  variables:
    GIT_DEPTH: 0
    CI: "true"
    npm_config_cache: $CI_PROJECT_DIR/.npm
  cache:
    key:
      files: [package-lock.json]
    paths: [.npm/]
  before_script:
    - command -v git >/dev/null || (apt-get update -qq && apt-get install -y -qq git >/dev/null)
    - git config --global --add safe.directory '*'
    - npm ci --no-audit --no-fund
  script:
    - status=0; VRT_BASE_SHA="$CI_MERGE_REQUEST_DIFF_BASE_SHA" VRT_BASE_NAME="$CI_MERGE_REQUEST_TARGET_BRANCH_NAME" scripts/vrt.sh test || status=$?
    - node scripts/vrt/ci-comment.mjs
    # 1 = 有視覺差異：標成警告（橘色）等人審閱，不擋合併；其他非 0 = 真的壞掉
    - if [ "$status" = 1 ]; then exit 42; fi
    - exit $status
  allow_failure:
    exit_codes: [42]
  artifacts:
    when: always
    expire_in: 30 days
    expose_as: "Visual test report"
    paths:
      - .vrt/report/
      - .vrt/unstable/
    reports:
      junit: .vrt/report/junit.xml
```

## `scripts/vrt/report.html`

```html
<!doctype html>
<html lang="zh-TW">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>視覺測試報告</title>
<style>
:root {
  --bg: #f4f5f7;
  --panel: #ffffff;
  --panel-2: #f7f8fa;
  --hover: #f0f2f5;
  --border: #e4e7eb;
  --border-strong: #d5d9df;
  --text: #16191d;
  --muted: #69717d;
  --faint: #9aa1ab;
  --accent: #2563eb;
  --accent-soft: #e9f0ff;
  --changed: #d97706;
  --changed-soft: #fff5e3;
  --added: #2563eb;
  --added-soft: #e9f0ff;
  --removed: #dc2626;
  --removed-soft: #fdeded;
  --ok: #15803d;
  --ok-soft: #e6f6ea;
  --diff: rgb(0, 240, 180);
  --checker-a: #eceef1;
  --checker-b: #f6f7f9;
  --stage: #e9ebee;
  --shadow: 0 1px 2px rgba(16, 24, 40, .06), 0 6px 16px rgba(16, 24, 40, .08);
  --radius: 10px;
  color-scheme: light;
}
@media (prefers-color-scheme: dark) {
  :root {
    --bg: #0f1114;
    --panel: #171a1f;
    --panel-2: #1c2026;
    --hover: #22272e;
    --border: #2a2f37;
    --border-strong: #363c46;
    --text: #e8eaed;
    --muted: #9aa2ad;
    --faint: #6b7380;
    --accent: #5b8cff;
    --accent-soft: #1b2640;
    --changed: #f5a524;
    --changed-soft: #33260f;
    --added: #5b8cff;
    --added-soft: #1b2640;
    --removed: #f26464;
    --removed-soft: #3a1717;
    --ok: #3fbf6a;
    --ok-soft: #132c1c;
    --checker-a: #1a1d22;
    --checker-b: #202329;
    --stage: #0b0d10;
    --shadow: 0 1px 2px rgba(0, 0, 0, .4), 0 8px 24px rgba(0, 0, 0, .35);
    color-scheme: dark;
  }
}

* { box-sizing: border-box; margin: 0; padding: 0; }
html, body { height: 100%; }
body {
  font: 13px/1.45 -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang TC", "Noto Sans TC", sans-serif;
  background: var(--bg);
  color: var(--text);
  overflow: hidden;
  -webkit-font-smoothing: antialiased;
}
button { font: inherit; color: inherit; background: none; border: 0; cursor: pointer; }
button:disabled { cursor: not-allowed; opacity: .45; }
kbd {
  font: 11px/1 ui-monospace, SFMono-Regular, Menlo, monospace;
  padding: 2px 5px; border-radius: 4px;
  border: 1px solid var(--border-strong); border-bottom-width: 2px;
  background: var(--panel); color: var(--muted);
}
.mono { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 12px; }

.app { display: grid; grid-template-rows: 56px 1fr; height: 100vh; }

/* ── Topbar ─────────────────────────────────────── */
.topbar {
  display: flex; align-items: center; gap: 20px;
  padding: 0 16px 0 20px;
  background: var(--panel); border-bottom: 1px solid var(--border);
}
.brand { display: flex; align-items: center; gap: 10px; font-weight: 700; font-size: 14px; white-space: nowrap; }
.brand svg { flex: none; }
.compare {
  display: flex; align-items: center; gap: 8px; min-width: 0;
  padding: 5px 10px; border-radius: 8px; background: var(--panel-2); border: 1px solid var(--border);
}
.ref { display: flex; align-items: center; gap: 6px; white-space: nowrap; }
.ref b { font-weight: 600; }
.ref .sha { color: var(--muted); }
.ref .dirty { color: var(--changed); font-size: 11px; }
.compare .arrow { color: var(--faint); }
.pills { display: flex; gap: 6px; }
.pill {
  display: inline-flex; align-items: center; gap: 6px;
  padding: 3px 9px; border-radius: 999px; font-weight: 600; font-size: 12px; white-space: nowrap;
}
.pill i { width: 7px; height: 7px; border-radius: 50%; background: currentColor; }
.pill.changed { color: var(--changed); background: var(--changed-soft); }
.pill.added { color: var(--added); background: var(--added-soft); }
.pill.removed { color: var(--removed); background: var(--removed-soft); }
.pill.unchanged { color: var(--ok); background: var(--ok-soft); }
.spacer { flex: 1; }
.btn {
  display: inline-flex; align-items: center; gap: 8px;
  height: 32px; padding: 0 12px; border-radius: 8px;
  border: 1px solid var(--border-strong); background: var(--panel); font-weight: 600;
  transition: background .15s, border-color .15s;
}
.btn:hover:not(:disabled) { background: var(--hover); }
.btn.ghost { border-color: transparent; }
.btn.active { background: var(--accent-soft); border-color: var(--accent); color: var(--accent); }

/* ── Layout ─────────────────────────────────────── */
.body { display: grid; grid-template-columns: 300px 1fr; min-height: 0; }

/* ── Sidebar ────────────────────────────────────── */
.sidebar {
  display: flex; flex-direction: column; min-height: 0;
  background: var(--panel); border-right: 1px solid var(--border);
}
.side-head { padding: 12px; display: grid; gap: 10px; border-bottom: 1px solid var(--border); }
.search {
  width: 100%; height: 32px; padding: 0 10px 0 32px; border-radius: 8px;
  border: 1px solid var(--border); background: var(--panel-2) no-repeat 10px center; color: var(--text); font: inherit;
  background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='14' height='14' fill='none' stroke='%239aa1ab' stroke-width='2'%3E%3Ccircle cx='6' cy='6' r='4.5'/%3E%3Cpath d='m9.5 9.5 3 3'/%3E%3C/svg%3E");
}
.search:focus { outline: 2px solid var(--accent-soft); border-color: var(--accent); }
.tabs { display: grid; grid-template-columns: 1fr 1fr; padding: 3px; border-radius: 8px; background: var(--hover); }
.tabs button { height: 26px; border-radius: 6px; font-weight: 600; color: var(--muted); }
.tabs button.on { background: var(--panel); color: var(--text); box-shadow: 0 1px 2px rgba(0,0,0,.08); }
.tabs .n { margin-left: 4px; font-weight: 500; color: var(--faint); }
.list { overflow: auto; padding: 6px 0 12px; flex: 1; }
.group-title {
  display: flex; align-items: center; gap: 8px;
  padding: 12px 16px 4px; font-weight: 600; color: var(--text);
}
.group-title svg { color: var(--faint); }
.row {
  display: grid; grid-template-columns: 18px 1fr auto; align-items: center; gap: 8px;
  width: 100%; padding: 7px 14px 7px 26px; text-align: left; position: relative;
}
.row:hover { background: var(--hover); }
.row.sel { background: var(--accent-soft); }
.row.sel::before { content: ""; position: absolute; left: 0; top: 4px; bottom: 4px; width: 3px; border-radius: 0 3px 3px 0; background: var(--accent); }
.row .vp { color: var(--muted); }
.row.sel .vp { color: var(--text); font-weight: 600; }
.row .pct { color: var(--faint); font-size: 12px; font-variant-numeric: tabular-nums; }
.status-icon { width: 16px; height: 16px; border-radius: 50%; display: grid; place-items: center; }
.status-icon.changed { background: var(--changed-soft); color: var(--changed); }
.status-icon.added { background: var(--added-soft); color: var(--added); }
.status-icon.removed { background: var(--removed-soft); color: var(--removed); }
.status-icon.unchanged { color: var(--ok); }
.side-foot { padding: 10px 14px; border-top: 1px solid var(--border); color: var(--faint); font-size: 12px; display: flex; flex-wrap: wrap; gap: 6px 12px; }

/* ── Main ───────────────────────────────────────── */
.main { display: grid; grid-template-rows: auto 1fr auto; min-width: 0; min-height: 0; }
.toolbar {
  display: flex; align-items: center; gap: 14px; flex-wrap: wrap;
  padding: 10px 16px; background: var(--panel); border-bottom: 1px solid var(--border);
}
.title { display: flex; align-items: center; gap: 10px; min-width: 0; }
.title h2 { font-size: 15px; font-weight: 700; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
.chip {
  display: inline-flex; align-items: center; gap: 5px;
  padding: 2px 8px; border-radius: 6px; font-size: 12px; font-weight: 600;
  background: var(--hover); color: var(--muted); white-space: nowrap;
}
.chip.changed { background: var(--changed-soft); color: var(--changed); }
.chip.added { background: var(--added-soft); color: var(--added); }
.chip.removed { background: var(--removed-soft); color: var(--removed); }
.chip.unchanged { background: var(--ok-soft); color: var(--ok); }
.meta { color: var(--muted); font-size: 12px; white-space: nowrap; font-variant-numeric: tabular-nums; }
.seg { display: inline-flex; padding: 3px; border-radius: 8px; background: var(--hover); }
.seg button { height: 26px; padding: 0 10px; border-radius: 6px; font-weight: 600; color: var(--muted); display: inline-flex; align-items: center; gap: 6px; }
.seg button.on { background: var(--panel); color: var(--text); box-shadow: 0 1px 2px rgba(0,0,0,.08); }
.toggle { display: inline-flex; align-items: center; gap: 8px; color: var(--muted); font-weight: 600; cursor: pointer; user-select: none; }
.toggle .sw { width: 30px; height: 18px; border-radius: 9px; background: var(--border-strong); position: relative; transition: background .2s; }
.toggle .sw::after { content: ""; position: absolute; top: 2px; left: 2px; width: 14px; height: 14px; border-radius: 50%; background: #fff; transition: transform .2s; box-shadow: 0 1px 2px rgba(0,0,0,.2); }
.toggle.on .sw { background: var(--diff); }
.toggle.on .sw::after { transform: translateX(12px); }
.range { display: inline-flex; align-items: center; gap: 8px; color: var(--muted); font-weight: 600; }
.range input { width: 110px; accent-color: var(--accent); }

/* ── Stage ──────────────────────────────────────── */
.stage { position: relative; min-height: 0; background: var(--stage); display: flex; }
.panes { display: grid; flex: 1; min-width: 0; gap: 1px; background: var(--border); }
.panes.two { grid-template-columns: 1fr 1fr; }
.pane { display: grid; grid-template-rows: auto 1fr; min-width: 0; min-height: 0; background: var(--stage); }
.pane-label {
  display: flex; align-items: center; gap: 8px; padding: 8px 14px;
  font-size: 12px; font-weight: 600; color: var(--muted); background: var(--panel-2); border-bottom: 1px solid var(--border);
}
.pane-label .dot { width: 8px; height: 8px; border-radius: 50%; }
.pane-label .dims { margin-left: auto; font-weight: 500; color: var(--faint); }
.scroller { overflow: auto; padding: 24px; min-height: 0; }
.frame {
  position: relative; margin: 0 auto; border-radius: 4px; box-shadow: var(--shadow); overflow: hidden;
  background: repeating-conic-gradient(var(--checker-a) 0 25%, var(--checker-b) 0 50%) 0 0 / 16px 16px;
}
.frame img { position: absolute; left: 0; top: 0; display: block; user-select: none; -webkit-user-drag: none; }
.frame .mask { width: 100%; height: 100%; pointer-events: none; mix-blend-mode: multiply; opacity: .8; }
.frame .alt { visibility: hidden; }
.stage.peek .frame .alt { visibility: visible; }
.stage.peek .frame .cur, .stage.peek .frame .mask, .stage.peek .frame .region { visibility: hidden; }
.mode-diff .cur { filter: grayscale(1); opacity: .28; }
.mode-diff .mask { mix-blend-mode: normal; opacity: 1; }

.region {
  position: absolute; border: 2px solid var(--diff); border-radius: 4px; pointer-events: none;
  box-shadow: 0 0 0 1px rgba(0,0,0,.25), inset 0 0 0 1px rgba(0,0,0,.15);
  opacity: .9;
}
.region.active { animation: pulse 1.4s ease-out infinite; border-width: 3px; opacity: 1; }
.region .tag {
  position: absolute; top: -1px; left: -1px; transform: translateY(-100%);
  padding: 1px 6px; border-radius: 4px 4px 0 0; font: 700 11px/16px ui-monospace, Menlo, monospace;
  background: var(--diff); color: #003b2c;
}
@keyframes pulse {
  0% { box-shadow: 0 0 0 0 rgba(0, 240, 180, .55); }
  100% { box-shadow: 0 0 0 14px rgba(0, 240, 180, 0); }
}

.slider-frame { cursor: ew-resize; }
.slider-frame .cur { clip-path: inset(0 0 0 var(--pos)); }
.slider-frame .before, .onion-frame .before { visibility: visible; }
.handle { position: absolute; top: 0; bottom: 0; left: var(--pos); width: 2px; margin-left: -1px; background: #fff; box-shadow: 0 0 0 1px rgba(0,0,0,.25); pointer-events: none; }
.handle::after {
  content: "‹ ›"; position: absolute; top: 50%; left: 50%; transform: translate(-50%, -50%);
  width: 34px; height: 34px; border-radius: 50%; background: #fff; color: #333; font-weight: 700;
  display: grid; place-items: center; box-shadow: var(--shadow); letter-spacing: 2px;
}
.side-tag {
  position: absolute; top: 10px; padding: 3px 8px; border-radius: 6px;
  background: rgba(15,17,20,.72); color: #fff; font-size: 11px; font-weight: 700; pointer-events: none;
}
.onion-frame .cur { opacity: var(--op); }

.placeholder {
  margin: 48px auto; max-width: 320px; text-align: center; color: var(--muted);
  display: grid; gap: 10px; justify-items: center;
}
.placeholder .big { width: 48px; height: 48px; border-radius: 50%; display: grid; place-items: center; background: var(--panel); box-shadow: var(--shadow); }

.peek-badge {
  position: absolute; top: 14px; left: 50%; transform: translateX(-50%);
  padding: 6px 12px; border-radius: 999px; background: var(--text); color: var(--bg);
  font-weight: 700; font-size: 12px; box-shadow: var(--shadow); display: none; z-index: 5;
}
.stage.peek .peek-badge { display: block; }

/* ── Footer ─────────────────────────────────────── */
.footer {
  display: flex; align-items: center; gap: 12px; padding: 10px 16px;
  background: var(--panel); border-top: 1px solid var(--border);
}
.nav { display: inline-flex; align-items: center; gap: 4px; color: var(--muted); font-variant-numeric: tabular-nums; }
.nav .btn { width: 32px; padding: 0; justify-content: center; }
.nav .label { min-width: 88px; text-align: center; font-weight: 600; }
.regions-nav { display: inline-flex; align-items: center; gap: 6px; padding-left: 12px; border-left: 1px solid var(--border); color: var(--muted); }

/* ── Overview ───────────────────────────────────── */
.overview { overflow: auto; padding: 24px; }
.overview h3 { font-size: 13px; color: var(--muted); font-weight: 700; margin: 8px 4px 12px; text-transform: uppercase; letter-spacing: .04em; }
.cards { display: grid; grid-template-columns: repeat(auto-fill, minmax(240px, 1fr)); gap: 16px; margin-bottom: 28px; }
.card {
  background: var(--panel); border-radius: var(--radius); overflow: hidden; text-align: left;
  border: 1px solid var(--border); box-shadow: 0 1px 2px rgba(0,0,0,.04);
  transition: transform .15s, box-shadow .15s, border-color .15s;
}
.card:hover { transform: translateY(-2px); box-shadow: var(--shadow); border-color: var(--border-strong); }
.thumb { position: relative; height: 170px; overflow: hidden; background: var(--panel-2); border-bottom: 1px solid var(--border); }
.thumb .shot { position: absolute; left: 0; right: 0; top: 0; margin: 0 auto; box-shadow: 0 0 0 1px var(--border); }
.thumb img { position: absolute; left: 0; top: 0; }
.thumb .mask { width: 100%; height: 100%; mix-blend-mode: multiply; opacity: .8; }
.card-body { padding: 10px 12px; display: flex; align-items: center; gap: 8px; }
.card-body .name { font-weight: 600; flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }

.empty-all { margin: 80px auto; text-align: center; display: grid; gap: 12px; justify-items: center; color: var(--muted); }
.empty-all .big { width: 64px; height: 64px; border-radius: 50%; display: grid; place-items: center; background: var(--ok-soft); color: var(--ok); }
.empty-all h2 { color: var(--text); font-size: 18px; }


@media (max-width: 900px) {
  .body { grid-template-columns: 1fr; }
  .sidebar { display: none; }
  .compare { display: none; }
}
</style>
</head>
<body>
<div class="app">
  <header class="topbar" id="topbar"></header>
  <div class="body">
    <aside class="sidebar" id="sidebar"></aside>
    <section class="main" id="main"></section>
  </div>
</div>
<script id="vrt-data" type="application/json">__VRT_DATA__</script>
<script>
(() => {
  const DATA = JSON.parse(document.getElementById("vrt-data").textContent);
  const ITEMS = DATA.items;
  const STATUS = {
    changed: { label: "變更", icon: '<svg width="8" height="8"><circle cx="4" cy="4" r="4" fill="currentColor"/></svg>' },
    added: { label: "新增", icon: '<svg width="10" height="10" stroke="currentColor" stroke-width="2"><path d="M5 1v8M1 5h8"/></svg>' },
    removed: { label: "刪除", icon: '<svg width="10" height="10" stroke="currentColor" stroke-width="2"><path d="M1 5h8"/></svg>' },
    unchanged: { label: "無變化", icon: '<svg width="12" height="12" fill="none" stroke="currentColor" stroke-width="2"><path d="m2 6.5 2.5 2.5L10 3.5"/></svg>' },
  };
  const ICON = {
    check: '<svg width="12" height="12" fill="none" stroke="currentColor" stroke-width="2.4"><path d="m2 6.5 2.5 2.5L10 3.5"/></svg>',
    left: '<svg width="14" height="14" fill="none" stroke="currentColor" stroke-width="2"><path d="m9 3-4 4 4 4"/></svg>',
    right: '<svg width="14" height="14" fill="none" stroke="currentColor" stroke-width="2"><path d="m5 3 4 4-4 4"/></svg>',
    page: '<svg width="14" height="14" fill="none" stroke="currentColor" stroke-width="1.6"><rect x="2.5" y="1.5" width="9" height="11" rx="1.5"/><path d="M5 5h4M5 7.5h4"/></svg>',
    grid: '<svg width="14" height="14" fill="none" stroke="currentColor" stroke-width="1.6"><rect x="1.5" y="1.5" width="4.5" height="4.5" rx="1"/><rect x="8" y="1.5" width="4.5" height="4.5" rx="1"/><rect x="1.5" y="8" width="4.5" height="4.5" rx="1"/><rect x="8" y="8" width="4.5" height="4.5" rx="1"/></svg>',
  };
  const MODES = [
    { id: "sbs", label: "並排", key: "1" },
    { id: "diff", label: "差異", key: "2" },
    { id: "slider", label: "滑桿", key: "3" },
    { id: "onion", label: "疊圖", key: "4" },
  ];

  const state = {
    view: "item",
    filter: ITEMS.some((i) => i.status !== "unchanged") ? "review" : "all",
    query: "",
    selected: null,
    mode: "sbs",
    overlay: true,
    fit: true,
    region: -1,
    pos: 50,
    op: 50,
  };

  const $ = (s, el = document) => el.querySelector(s);
  const esc = (s) => String(s ?? "").replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
  const pct = (r) => (r < 0.0001 ? "<0.01%" : (r * 100).toFixed(2) + "%");
  const prettyName = (n) => n.replace(/--/g, " › ");
  const needsReview = (i) => i.status !== "unchanged";
  const byId = (id) => ITEMS.find((i) => i.id === id);

  function visibleItems() {
    const q = state.query.trim().toLowerCase();
    return ITEMS.filter((i) => (state.filter === "all" || needsReview(i)) && (!q || i.id.toLowerCase().includes(q)));
  }

  // ── Topbar ──────────────────────────────────────
  function renderTopbar() {
    const count = (s) => ITEMS.filter((i) => i.status === s).length;
    const b = DATA.baseline, h = DATA.head;
    const pills = ["changed", "added", "removed", "unchanged"]
      .filter((s) => count(s) || s === "unchanged")
      .map((s) => `<span class="pill ${s}"><i></i>${count(s)} ${STATUS[s].label}</span>`).join("");
    $("#topbar").innerHTML = `
      <div class="brand">
        <svg width="22" height="22" viewBox="0 0 22 22"><rect width="22" height="22" rx="6" fill="var(--accent)"/><rect x="5" y="6" width="7" height="10" rx="1.5" fill="#fff" opacity=".55"/><rect x="10" y="6" width="7" height="10" rx="1.5" fill="#fff"/></svg>
        視覺測試
      </div>
      <div class="compare mono">
        <span class="ref"><b>${esc(b?.ref ?? "baseline")}</b>${b?.sha ? `<span class="sha">${esc(b.sha)}</span>` : ""}</span>
        <span class="arrow">→</span>
        <span class="ref"><b>${esc(h.ref ?? "current")}</b><span class="sha">${esc(h.sha ?? "")}</span>${h.dirty ? '<span class="dirty">● 未提交</span>' : ""}</span>
      </div>
      <div class="pills">${pills}</div>
      <div class="spacer"></div>
      <button class="btn ${state.view === "overview" ? "active" : ""}" data-act="overview">${ICON.grid}總覽</button>
    `;
  }

  // ── Sidebar ─────────────────────────────────────
  function renderSidebar() {
    const nReview = ITEMS.filter(needsReview).length;
    const groups = new Map();
    for (const i of visibleItems()) {
      if (!groups.has(i.name)) groups.set(i.name, []);
      groups.get(i.name).push(i);
    }
    const rows = [...groups].map(([name, items]) => `
      <div class="group-title">${ICON.page}${esc(prettyName(name))}</div>
      ${items.map((i) => {
        return `<button class="row ${state.selected === i.id && state.view === "item" ? "sel" : ""}" data-id="${esc(i.id)}">
          <span class="status-icon ${i.status}" title="${STATUS[i.status].label}">${STATUS[i.status].icon}</span>
          <span class="vp">${esc(i.viewport)}</span>
          <span class="pct">${i.status === "changed" ? pct(i.diffRatio) : ""}</span>
        </button>`;
      }).join("")}
    `).join("");
    const sidebar = $("#sidebar");
    const scroll = $(".list", sidebar)?.scrollTop ?? 0;
    sidebar.innerHTML = `
      <div class="side-head">
        <input class="search" placeholder="搜尋快照" value="${esc(state.query)}" id="search">
        <div class="tabs">
          <button class="${state.filter === "review" ? "on" : ""}" data-filter="review">待審閱<span class="n">${nReview}</span></button>
          <button class="${state.filter === "all" ? "on" : ""}" data-filter="all">全部<span class="n">${ITEMS.length}</span></button>
        </div>
      </div>
      <div class="list">${rows || '<div class="placeholder">沒有符合的快照</div>'}</div>
      <div class="side-foot"><span><kbd>J</kbd> <kbd>K</kbd> 切換</span><span><kbd>N</kbd> <kbd>P</kbd> 變更區域</span><span><kbd>Space</kbd> 按住看基準</span></div>
    `;
    $(".list", sidebar).scrollTop = scroll;
  }

  // ── Main ────────────────────────────────────────
  function frameDims(item) {
    const a = item.before ?? item.after, b = item.after ?? item.before;
    return { W: Math.max(a.w, b.w), H: Math.max(a.h, b.h) };
  }

  function img(cls, src, dims, W, H) {
    return `<img class="${cls}" src="${esc(src)}" style="width:${(dims.w / W) * 100}%;height:${(dims.h / H) * 100}%" alt="">`;
  }

  function overlays(item, W, H) {
    if (item.status !== "changed" || !state.overlay || state.mode === "slider" || state.mode === "onion") return "";
    const regions = item.regions.map((r, n) => `
      <div class="region ${n === state.region ? "active" : ""}" style="left:${(r.x / W) * 100}%;top:${(r.y / H) * 100}%;width:${(r.w / W) * 100}%;height:${(r.h / H) * 100}%">
        ${n === state.region ? `<span class="tag">${n + 1}</span>` : ""}
      </div>`).join("");
    return `<img class="mask" src="${esc(item.files.diff)}" alt="">${regions}`;
  }

  // 一個 frame = 以兩張圖的最大尺寸為畫布，讓左右兩邊座標一致、捲動可同步
  function frame(item, side, scale, extraClass = "", extra = "") {
    const { W, H } = frameDims(item);
    const style = `width:${Math.round(W * scale)}px;height:${Math.round(H * scale)}px;--pos:${state.pos}%;--op:${state.op / 100}`;
    if (side === "before") {
      return `<div class="frame ${extraClass}" style="${style}">${img("", item.files.before, item.before, W, H)}</div>`;
    }
    const alt = item.files.before ? img("alt before", item.files.before, item.before, W, H) : "";
    return `<div class="frame ${extraClass}" style="${style}">${alt}${img("cur", item.files.after, item.after, W, H)}${overlays(item, W, H)}${extra}</div>`;
  }

  function placeholder(text) {
    return `<div class="placeholder"><div class="big">${ICON.page}</div>${esc(text)}</div>`;
  }

  function paneLabel(color, text, dims) {
    return `<div class="pane-label"><span class="dot" style="background:${color}"></span>${text}${dims ? `<span class="dims mono">${dims.w} × ${dims.h}</span>` : ""}</div>`;
  }

  function computeScale(item, columns) {
    if (!state.fit) return 1;
    const stage = $(".stage");
    const width = (stage?.clientWidth ?? window.innerWidth - 300) / columns - 48 - (columns - 1);
    return Math.min(1, width / frameDims(item).W);
  }

  function renderStage(item) {
    const stage = $(".stage");
    const b = DATA.baseline?.ref ?? "基準", h = DATA.head.ref ?? "目前";
    const useTwo = state.mode === "sbs";
    const scale = computeScale(item, useTwo ? 2 : 1);
    stage.className = `stage mode-${state.mode}`;

    if (useTwo) {
      stage.innerHTML = `<div class="peek-badge">顯示基準中</div><div class="panes two">
        <div class="pane">${paneLabel("var(--faint)", `基準 · ${esc(b)}`, item.before)}
          <div class="scroller" data-sync>${item.files.before ? frame(item, "before", scale) : placeholder("新增的快照，沒有基準可比對")}</div></div>
        <div class="pane">${paneLabel(`var(--${item.status === "unchanged" ? "ok" : item.status})`, `目前 · ${esc(h)}`, item.after)}
          <div class="scroller" data-sync>${item.files.after ? frame(item, "after", scale) : placeholder("這個快照在目前版本已被移除")}</div></div>
      </div>`;
      syncScroll(stage);
      return;
    }

    let body;
    if (!item.files.after || !item.files.before) {
      body = item.files.after ? frame(item, "after", scale) : frame(item, "before", scale);
    } else if (state.mode === "slider") {
      body = frame(item, "after", scale, "slider-frame",
        `<div class="handle"></div><span class="side-tag" style="left:10px">基準</span><span class="side-tag" style="right:10px">目前</span>`);
    } else if (state.mode === "onion") {
      body = frame(item, "after", scale, "onion-frame");
    } else {
      body = frame(item, "after", scale);
    }
    stage.innerHTML = `<div class="peek-badge">顯示基準中</div><div class="panes"><div class="pane">
      ${paneLabel(`var(--${item.status === "unchanged" ? "ok" : item.status})`, MODES.find((m) => m.id === state.mode).label + " · " + esc(b) + " → " + esc(h), item.after ?? item.before)}
      <div class="scroller">${body}</div></div></div>`;
    if (state.mode === "slider") bindSlider(stage);
  }

  function syncScroll(stage) {
    const scrollers = [...stage.querySelectorAll("[data-sync]")];
    let lock = false;
    for (const s of scrollers) {
      s.addEventListener("scroll", () => {
        if (lock) return;
        lock = true;
        for (const o of scrollers) if (o !== s) { o.scrollTop = s.scrollTop; o.scrollLeft = s.scrollLeft; }
        requestAnimationFrame(() => (lock = false));
      });
    }
  }

  function bindSlider(stage) {
    const f = $(".slider-frame", stage);
    if (!f) return;
    const move = (e) => {
      const r = f.getBoundingClientRect();
      state.pos = Math.max(0, Math.min(100, ((e.clientX - r.left) / r.width) * 100));
      f.style.setProperty("--pos", state.pos + "%");
    };
    f.addEventListener("pointerdown", (e) => { f.setPointerCapture(e.pointerId); move(e); f.onpointermove = move; });
    f.addEventListener("pointerup", () => (f.onpointermove = null));
  }

  function renderItem() {
    const item = byId(state.selected);
    const list = visibleItems();
    const idx = list.findIndex((i) => i.id === item.id);
    const regions = item.regions?.length ?? 0;
    const dimsChanged = item.before && item.after && (item.before.w !== item.after.w || item.before.h !== item.after.h);

    $("#main").innerHTML = `
      <div class="toolbar">
        <div class="title"><h2>${esc(prettyName(item.name))}</h2><span class="chip">${esc(item.viewport)}</span>
          <span class="chip ${item.status}">${STATUS[item.status].label}</span></div>
        ${item.status === "changed" ? `<span class="meta">${pct(item.diffRatio)} 像素不同 · ${regions} 處變更${dimsChanged ? ` · 尺寸 ${item.before.w}×${item.before.h} → ${item.after.w}×${item.after.h}` : ""}</span>` : ""}
        <div class="spacer"></div>
        ${state.mode === "onion" ? `<label class="range">基準<input type="range" min="0" max="100" value="${state.op}" id="op">目前</label>` : ""}
        ${item.status === "changed" && state.mode === "sbs" ? `<span class="toggle ${state.overlay ? "on" : ""}" data-act="overlay"><span class="sw"></span>標示差異 <kbd>H</kbd></span>` : ""}
        <div class="seg">${MODES.map((m) => `<button class="${state.mode === m.id ? "on" : ""}" data-mode="${m.id}">${m.label}</button>`).join("")}</div>
        <div class="seg"><button class="${state.fit ? "on" : ""}" data-act="fit">符合寬度</button><button class="${state.fit ? "" : "on"}" data-act="actual">100%</button></div>
      </div>
      <div class="stage"></div>
      <div class="footer">
        <div class="nav">
          <button class="btn" data-act="prev" ${idx <= 0 ? "disabled" : ""} title="上一個 (K)">${ICON.left}</button>
          <span class="label">${idx + 1} / ${list.length}</span>
          <button class="btn" data-act="next" ${idx >= list.length - 1 ? "disabled" : ""} title="下一個 (J)">${ICON.right}</button>
        </div>
        ${regions ? `<div class="regions-nav">變更區域
          <button class="btn ghost" data-act="rprev" title="上一處 (P)">${ICON.left}</button>
          <span class="mono">${state.region >= 0 ? state.region + 1 : "–"} / ${regions}</span>
          <button class="btn ghost" data-act="rnext" title="下一處 (N)">${ICON.right}</button></div>` : ""}
      </div>`;
    renderStage(item);
  }

  function renderOverview() {
    const sections = ["changed", "added", "removed", "unchanged"].map((s) => {
      const items = ITEMS.filter((i) => i.status === s);
      if (!items.length) return "";
      return `<h3>${STATUS[s].label} · ${items.length}</h3><div class="cards">${items.map((i) => {
        const src = i.files.after ?? i.files.before;
        const { W, H } = frameDims(i);
        const dims = i.after ?? i.before;
        // 縮圖對準第一個變更區域；手機截圖不放大
        const r = i.regions?.[0];
        const focus = r ? (r.y + r.h / 2) / H : 0;
        const shot = `width:${W < 1280 ? "55%" : "100%"};aspect-ratio:${W}/${H};transform:translateY(min(0px, calc(85px - ${(focus * 100).toFixed(2)}%)))`;
        return `<button class="card" data-id="${esc(i.id)}">
          <div class="thumb"><div class="shot" style="${shot}"><img src="${esc(src)}" style="width:${(dims.w / W) * 100}%;height:${(dims.h / H) * 100}%" loading="lazy" alt="">
            ${i.files.diff ? `<img class="mask" src="${esc(i.files.diff)}" loading="lazy" alt="">` : ""}</div></div>
          <div class="card-body"><span class="status-icon ${i.status}">${STATUS[i.status].icon}</span>
            <span class="name">${esc(prettyName(i.name))}</span><span class="chip">${esc(i.viewport)}</span>
            ${i.status === "changed" ? `<span class="meta">${pct(i.diffRatio)}</span>` : ""}</div>
        </button>`;
      }).join("")}</div>`;
    }).join("");

    const clean = !ITEMS.some(needsReview);
    $("#main").innerHTML = `<div class="overview" style="grid-row: 1 / -1">
      ${clean ? `<div class="empty-all"><div class="big">${ICON.check.replace(/12/g, "28")}</div><h2>沒有視覺差異</h2><p>${ITEMS.length} 個快照都與基準一致。</p></div>` : ""}
      ${sections}</div>`;
  }

  function render() {
    renderTopbar();
    renderSidebar();
    if (state.view === "overview" || !state.selected) renderOverview();
    else renderItem();
  }

  // ── Actions ─────────────────────────────────────
  function select(id) {
    state.selected = id;
    state.view = "item";
    state.region = -1;
    render();
  }

  function step(delta) {
    const list = visibleItems();
    const idx = list.findIndex((i) => i.id === state.selected);
    const next = list[idx + delta];
    if (next) select(next.id);
  }

  function gotoRegion(delta) {
    const item = byId(state.selected);
    const n = item?.regions?.length;
    if (!n) return;
    state.region = (state.region + delta + n) % n;
    state.overlay = true;
    renderItem();
    const r = item.regions[state.region];
    const { W } = frameDims(item);
    const scrollers = [...document.querySelectorAll(".stage .scroller")];
    const target = scrollers[scrollers.length - 1];
    const frameEl = $(".frame", target);
    if (!frameEl) return;
    const scale = frameEl.clientWidth / W;
    target.scrollTo({
      top: Math.max(0, (r.y + r.h / 2) * scale - target.clientHeight / 2 + 24),
      left: Math.max(0, (r.x + r.w / 2) * scale - target.clientWidth / 2 + 24),
      behavior: "smooth",
    });
  }

  function act(name) {
    switch (name) {
      case "overview": state.view = state.view === "overview" ? "item" : "overview"; if (!state.selected) state.view = "overview"; render(); break;
      case "prev": step(-1); break;
      case "next": step(1); break;
      case "rprev": gotoRegion(-1); break;
      case "rnext": gotoRegion(1); break;
      case "overlay": state.overlay = !state.overlay; renderItem(); break;
      case "fit": state.fit = true; renderItem(); break;
      case "actual": state.fit = false; renderItem(); break;
    }
  }

  document.addEventListener("click", (e) => {
    const t = e.target.closest("[data-act],[data-id],[data-mode],[data-filter]");
    if (!t) return;
    if (t.dataset.act) act(t.dataset.act);
    else if (t.dataset.id) select(t.dataset.id);
    else if (t.dataset.mode) { state.mode = t.dataset.mode; renderItem(); }
    else if (t.dataset.filter) { state.filter = t.dataset.filter; renderSidebar(); }
  });

  document.addEventListener("input", (e) => {
    if (e.target.id === "search") {
      state.query = e.target.value;
      const caret = e.target.selectionStart;
      renderSidebar();
      const s = $("#search"); s.focus(); s.setSelectionRange(caret, caret);
    }
    if (e.target.id === "op") {
      state.op = +e.target.value;
      $(".onion-frame")?.style.setProperty("--op", state.op / 100);
    }
  });

  document.addEventListener("keydown", (e) => {
    if (e.target.tagName === "INPUT" || e.metaKey || e.ctrlKey || e.altKey) return;
    const k = e.key.toLowerCase();
    if (k === " ") { e.preventDefault(); $(".stage")?.classList.add("peek"); return; }
    const mode = MODES.find((m) => m.key === k);
    if (mode && state.view === "item" && state.selected) { state.mode = mode.id; renderItem(); return; }
    const map = { j: "next", arrowdown: "next", k: "prev", arrowup: "prev", n: "rnext", p: "rprev", h: "overlay", o: "overview" };
    if (map[k]) { e.preventDefault(); act(map[k]); }
    if (k === "f") act(state.fit ? "actual" : "fit");
  });
  document.addEventListener("keyup", (e) => { if (e.key === " ") $(".stage")?.classList.remove("peek"); });

  let resizeTimer;
  window.addEventListener("resize", () => {
    clearTimeout(resizeTimer);
    resizeTimer = setTimeout(() => { if (state.view === "item" && state.selected) renderStage(byId(state.selected)); }, 120);
  });

  // ── Boot ────────────────────────────────────────
  const first = ITEMS.find(needsReview) ?? null;
  state.selected = first?.id ?? null;
  if (!first) state.view = "overview";
  render();
})();
</script>
</body>
</html>
```