@kw-yeh/vibeflow 4.0.6 → 4.2.0

package/README.md

@@ -1,5 +1,9 @@
 # VibeFlow
 
+[![npm version](https://img.shields.io/npm/v/@kw-yeh/vibeflow.svg)](https://www.npmjs.com/package/@kw-yeh/vibeflow)
+[![npm downloads](https://img.shields.io/npm/dm/@kw-yeh/vibeflow.svg)](https://www.npmjs.com/package/@kw-yeh/vibeflow)
+[![node](https://img.shields.io/node/v/@kw-yeh/vibeflow.svg)](https://www.npmjs.com/package/@kw-yeh/vibeflow)
+
 **讓多個 coding agent 同時開工的本機看板。**
 
 每張卡片是一個任務。卡片一開始，VibeFlow 就幫它開一條獨立的 Git 分支與 worktree，在裡面啟動 Claude Code 或 Codex，並把即時終端機放在卡片旁邊。好幾張卡可以同時跑，彼此不會改到同一份檔案，你的專案資料夾本身也不會被切換分支。
@@ -22,6 +26,7 @@ vibeflow
 - **看得到 agent 做了什麼**：每張卡有 diff 檢視、artifacts，以及一份會保留下來的決策紀錄（agent 做了哪些決定、為什麼）。
 - **選你要的 agent**：Claude Code 或 Codex，每張卡可以各自指定 model、推理強度（effort）與 Auto Mode（是否免確認執行）。
 - **Web UI 與終端機 UI 共用同一個看板**：習慣瀏覽器用 Web UI，習慣終端機用 `vibeflow tui`。
+- **內建 skill，可自行調整**：每個人的 Library（設定 → Library）都附帶 `visual-parity`、`pr` 兩個 skill，兩個 agent 都會載入。可以直接編輯、停用或刪除，隨時能還原成 VibeFlow 出貨的版本；沒改過的會跟著 VibeFlow 升級更新。`visual-parity` 需要 Python 與 `pip install playwright && playwright install chromium`。
 - **也能用指令操作**：`vibeflow task create` 不開 UI 直接建卡；agent 自己也能在看板上建立後續的卡片。
 
 ---

package/dist/builtin-skills/pr/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: pr
+description: Create or update a GitHub draft pull request for the current branch with gh — conventional-commit title, What / Why / How body in English, written only from this branch's diff. Use when the user says "open a PR", "create PR", "建立 PR", "開 PR", or "/pr #123" to update an existing one.
+---
+
+# Pull request
+
+Talk to the user in their language. Write the PR title and body in English.
+
+## 1. Mode
+
+- Argument is a number or `#number` → **update** that PR (`gh pr edit`).
+- Anything else (an issue reference, or nothing) → **create** a new draft PR.
+
+## 2. Check the branch
+
+Run and read:
+
+```bash
+git branch --show-current
+git status --short
+gh repo view --json defaultBranchRef -q .defaultBranchRef.name
+```
+
+- On the default branch → stop and tell the user to create a feature branch first.
+- Uncommitted changes → tell the user and ask whether to commit them first; do not commit on your own.
+- Update mode: `gh pr view <n> --json headRefName,baseRefName` — if `headRefName` is not the current
+  branch, stop and tell the user; never rewrite another branch's PR with this diff.
+- Base: in update mode the PR's `baseRefName`; otherwise the default branch.
+- Push what the PR is about to describe:
+  - No upstream yet (`git rev-parse --abbrev-ref @{upstream}` fails) → `git push -u origin HEAD`.
+  - Upstream exists but lacks commits (`git rev-list --count @{upstream}..HEAD` is above 0) → `git push`.
+
+## 3. Read the change
+
+```bash
+git fetch origin <base>
+git log --oneline origin/<base>..HEAD
+git diff --stat origin/<base>...HEAD
+git diff origin/<base>...HEAD
+```
+
+Describe **only** this diff — nothing the base branch already had. If the diff is too large to read
+whole, use `--stat` to pick the files that matter and read those.
+
+## 4. Write it
+
+**Title:** conventional commit — `<type>(<scope>): <summary>`, under 72 characters.
+`type` is one of `feat`, `fix`, `refactor`, `perf`, `docs`, `test`, `build`, `ci`, `chore`.
+Add `scope` only when one area clearly owns the change.
+
+**Body:**
+
+```markdown
+## What
+<one or two sentences: what changes for a user or a caller>
+
+## Why
+<the problem or goal; link the issue if there is one>
+
+## How
+- <the key decisions, not a file-by-file list>
+
+## Testing
+- <what was run or checked, and the result>
+```
+
+Issue link: if the argument or the branch name carries an issue reference (`#123`, `ABC-123`),
+put it in **Why** (`Closes #123` for a GitHub issue in this repo).
+
+## 5. Create or update
+
+Write the body to a temp file, then:
+
+```bash
+gh pr create --draft --base <base> --title "<title>" --body-file <file>
+gh pr edit <n> --title "<title>" --body-file <file>
+```
+
+Report the PR URL and the title to the user.

package/dist/builtin-skills/visual-parity/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: visual-parity
+description: 比對兩個已渲染網頁的樣式落差（新舊版對照 / 改版驗收），跑互動 E2E 流程並蒐集 console 與 network 錯誤，以及在 375/768/1440 三種寬度檢查 RWD 與水平溢出。當使用者提到「新舊頁面長得不一樣」「跟測試環境比對」「像素比對」「樣式對不上」「visual diff」「RWD 檢查」「開 dev server 驗收」「E2E 驗收」時使用。比對與驗收的結果寫進檔案，只回傳壓縮過的落差表。
+---
+
+# Visual Parity
+
+一次跑完、產出完整落差清單。**禁止**「改一項 → 截圖 → 再改一項」的來回迴圈。
+
+## 為什麼存在
+
+改一項就截圖一次，會把每張截圖與每份 computed style 永久留在 context 裡。同一份工作在 600k context 下做，成本是 100k 時的六倍。本 skill 把比對結果寫進檔案，只回傳一張壓縮過的落差表。
+
+## 鐵則
+
+1. **不要 Read `scripts/parity.py`。** 它是黑箱，用 `--help` 就夠。下文的 `parity.py` 一律指本 SKILL.md 所在目錄下的 `scripts/parity.py`，用絕對路徑呼叫。
+2. **不要把報告全文讀進 context。** stdout 的摘要已含「最常出現的落差屬性」；需要細節時用 `grep` 撈特定屬性或 selector，不要 `Read` 整份。
+3. **不要逐項修。** 先看 stdout 的 top differing properties——落差通常是少數幾條系統性規則（一條 `margin-bottom`、一組 token）造成的，不是幾十個獨立問題。
+4. **改完重跑一次全量比對**，而不是只驗剛改的那一項。
+
+## 前置
+
+- `<skill-dir>` 是本 SKILL.md 所在的目錄；script 在 `<skill-dir>/scripts/parity.py`。
+- 下文指令寫 `python`；macOS / Linux 沒有 `python` 時改用 `python3`。
+- 需要 `pip install playwright && playwright install chromium`（macOS / Linux 用 `pip3` 或 `python3 -m pip`）；錄 `.mp4` 才需要 ffmpeg（選配）。
+- 受測頁面要先跑起來。server 已經在跑就直接呼叫 `parity.py`；自簽憑證已預設接受（`ignore_https_errors`）。
+- 頁面需要登入或一次性 token 時，`--ref` / `--local` 直接給帶 token 的完整 URL，或先用 `flow` 的步驟登入。
+  打到登入頁或拒絕頁時比對結果毫無意義——`matched` 異常地少就先檢查這個。
+- 新舊對照要同時起兩份 server（不同 port），各自當 `--ref` 與 `--local`。
+
+## diff — 新舊頁面樣式落差
+
+```bash
+python <skill-dir>/scripts/parity.py diff \
+  --ref   https://staging.example.com/faq/content?id=28473 \
+  --local https://localhost:3000/faq/content?id=28473 \
+  --out   parity-diff.md
+```
+
+元素配對：先套 `--map` 的手動對照，再以「標籤+文字」自動配對，最後以「純文字」補配（吸收 SPA→SSR 的標籤變化，例如 `<p>` 變 `<div>`）。
+
+stdout 會回報四個數字：
+
+- `matched` — 成功配對並比對的元素數
+- `diffs` — 屬性落差總數
+- `missing-locally` — 舊頁有、新頁完全沒有的內容（**抓漏掉的區塊用這個**）
+- `skipped-ambiguous` — 文字在頁面上重複、無法 1:1 配對，**未被比對**。數字大不代表有問題，但代表覆蓋率沒滿；關鍵區塊落在這裡就用 `--map` 補。
+
+其他參數：`--width` / `--widths`、`--wait-selector`（等內容渲染完）、`--extra-wait`（動畫或延遲載入）。
+Exit code 1 表示有落差，0 表示完全一致。
+
+### --map：手動指定對照
+
+DOM 結構差太多時（舊 iframe vs 新 SSR），用 JSON 補：
+
+```json
+{
+  "#faqAnswer": ".faq-body",
+  ".uform_search": "[data-testid=search-hero]",
+  "#footer .crumb": "nav[aria-label=breadcrumb]"
+}
+```
+
+左邊是 ref 的 selector、右邊是 local 的。支援尾綴比對，不必寫完整路徑。
+
+## responsive — 三種寬度 + 水平溢出
+
+```bash
+python <skill-dir>/scripts/parity.py responsive \
+  --ref <URL> --local <URL> --out parity-responsive.md
+```
+
+等同在 375 / 768 / 1440 各跑一次 diff，另外檢查 local 是否出現水平溢出（`scrollWidth > clientWidth`），這是 RWD 破版最常見的徵兆。
+
+## flow — 互動驗收 + console/network 錯誤
+
+用 JSON 描述步驟，不要每次現寫 Playwright：
+
+```json
+[
+  {"action": "goto", "url": "https://localhost:3000/products"},
+  {"action": "click", "selector": ".ba-free-download", "desc": "點 Free Download"},
+  {"action": "wait", "selector": "[role=dialog]"},
+  {"action": "expect_focused", "selector": "[role=dialog] input[type=email]", "desc": "focus 應落在 input 而非 close button"},
+  {"action": "fill", "selector": "input[type=email]", "value": "a@b.com"},
+  {"action": "click", "selector": "button[type=submit]"},
+  {"action": "expect_text", "selector": "[role=dialog]", "value": "Check your email"}
+]
+```
+
+```bash
+python <skill-dir>/scripts/parity.py flow --steps steps.json --out parity-flow.md
+```
+
+可用 action：`goto` `click` `fill` `press` `wait` `expect_text` `expect_visible` `expect_focused` `screenshot`。
+`wait` 吃 `selector`，或改吃 `{"action":"wait","ms":800}` 單純停一段時間——動畫沒有對應的 selector 可等時用這個。
+預設第一個失敗就停（`--keep-going` 可跑完全部）。console error/warning 與失敗的 request 一律蒐集，這類問題不會反映在樣式比對裡。
+`--headed` 可開有頭瀏覽器讓人工旁觀。
+
+### --video：錄整段互動
+
+截圖看不出 transition、loading、hover 這類會動的東西，用錄影：
+
+```bash
+python <skill-dir>/scripts/parity.py flow \
+  --steps steps.json --out parity-flow.md --video parity-flow.mp4
+```
+
+- 副檔名 `.mp4` 會在錄完後用 ffmpeg 轉成 H.264（QuickTime 直接開），中間的 webm 自動刪除。**ffmpeg 不存在時不會失敗**，保留 `.webm` 並在 stdout 提示。副檔名寫 `.webm` 則完全不轉檔。
+- `--video-size WxH`（預設 `1280x720`）同時決定錄影解析度與 viewport。
+- `--video-tail <秒>`（預設 `1`）最後一步跑完後繼續錄的時間，避免收尾的動畫被切掉。
+- 影格率是 Playwright screencast 的 **25fps**，判斷「動畫有沒有做對」夠用；要判斷「掉不掉幀」不夠，那種要用 macOS `screencapture -v` 錄 60fps。
+- 影片路徑會同時寫進報告開頭與 stdout。
+
+把 flow 的 JSON 存進專案（例如 `e2e/`），下次改版直接重跑，就是回歸測試。
+
+## 維護
+
+改過 `parity.py` 後跑 `python <skill-dir>/scripts/parity.py selftest`，會用內建 fixture 驗證配對與 diff 邏輯仍正確。

package/dist/builtin-skills/visual-parity/scripts/parity.py

@@ -0,0 +1,449 @@
+#!/usr/bin/env python3
+"""visual-parity: rendered-page comparison and E2E flow runner.
+
+Black-box script. Run with --help. Do not read this source into an agent
+context window; every mode writes its full result to a report file and prints
+only a compressed summary to stdout.
+"""
+import argparse
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+from collections import Counter, defaultdict
+
+try:
+    from playwright.sync_api import sync_playwright
+except ImportError:
+    sys.exit("playwright not installed. Run: pip install playwright && playwright install chromium")
+
+PROPS = [
+    "font-family", "font-size", "font-weight", "font-style", "line-height",
+    "letter-spacing", "text-align", "text-transform", "text-decoration-line",
+    "color", "background-color", "opacity", "visibility",
+    "margin-top", "margin-right", "margin-bottom", "margin-left",
+    "padding-top", "padding-right", "padding-bottom", "padding-left",
+    "border-top-width", "border-right-width", "border-bottom-width", "border-left-width",
+    "border-top-color", "border-radius",
+    "display", "flex-direction", "justify-content", "align-items", "gap",
+    "list-style-type", "white-space", "overflow-x", "box-shadow",
+]
+
+# Box dimensions are compared with a tolerance; exact equality is noise.
+BOX_TOLERANCE_PX = 2
+
+COLLECT_JS = """
+(props) => {
+  const SKIP = new Set(['SCRIPT','STYLE','META','LINK','HEAD','NOSCRIPT','TITLE','BR']);
+  const cssPath = (el) => {
+    const parts = [];
+    while (el && el.nodeType === 1 && parts.length < 8) {
+      if (el === document.body) { parts.unshift('body'); break; }
+      let p = el.tagName.toLowerCase();
+      if (el.id && /^[A-Za-z][\\w-]*$/.test(el.id)) { parts.unshift('#' + el.id); break; }
+      const par = el.parentElement;
+      if (par) {
+        const sibs = Array.from(par.children).filter(c => c.tagName === el.tagName);
+        if (sibs.length > 1) p += ':nth-of-type(' + (sibs.indexOf(el) + 1) + ')';
+      }
+      parts.unshift(p);
+      el = el.parentElement;
+    }
+    return parts.join(' > ');
+  };
+  const ownText = (el) => (el.children.length === 0
+    ? el.textContent
+    : Array.from(el.childNodes).filter(n => n.nodeType === 3).map(n => n.textContent).join(' '));
+
+  const out = [];
+  for (const el of document.querySelectorAll('*')) {
+    if (SKIP.has(el.tagName)) continue;
+    const r = el.getBoundingClientRect();
+    if (r.width === 0 && r.height === 0) continue;
+    const cs = getComputedStyle(el);
+    const styles = {};
+    for (const p of props) styles[p] = cs.getPropertyValue(p).trim();
+    out.push({
+      path: cssPath(el),
+      tag: el.tagName.toLowerCase(),
+      text: ownText(el).replace(/\\s+/g, ' ').trim().slice(0, 120),
+      w: Math.round(r.width), h: Math.round(r.height),
+      styles,
+    });
+    if (out.length >= 2500) break;
+  }
+  return {
+    elements: out,
+    docScrollWidth: document.documentElement.scrollWidth,
+    clientWidth: document.documentElement.clientWidth,
+  };
+}
+"""
+
+
+def norm(t):
+    return re.sub(r"\s+", " ", t or "").strip().lower()
+
+
+def collect(page, url, wait_selector, extra_wait):
+    page.goto(url, wait_until="domcontentloaded", timeout=60000)
+    try:
+        page.wait_for_load_state("networkidle", timeout=30000)
+    except Exception:
+        pass  # some pages poll forever; the DOM is usable regardless
+    if wait_selector:
+        page.wait_for_selector(wait_selector, timeout=30000)
+    if extra_wait:
+        page.wait_for_timeout(int(extra_wait * 1000))
+    return page.evaluate(COLLECT_JS, PROPS)
+
+
+def build_pairs(ref_els, loc_els, manual_map):
+    """Match ref elements to local elements. Returns (pairs, unmatched_ref)."""
+    pairs, used_loc = [], set()
+
+    ref_by_path = {e["path"]: e for e in ref_els}
+    loc_by_path = {e["path"]: e for e in loc_els}
+    for ref_sel, loc_sel in (manual_map or {}).items():
+        r = ref_by_path.get(ref_sel) or next((e for e in ref_els if e["path"].endswith(ref_sel)), None)
+        l = loc_by_path.get(loc_sel) or next((e for e in loc_els if e["path"].endswith(loc_sel)), None)
+        if r and l:
+            pairs.append((r, l, "manual"))
+            used_loc.add(l["path"])
+
+    def index(els, keyfn):
+        idx = defaultdict(list)
+        for e in els:
+            k = keyfn(e)
+            if k:
+                idx[k].append(e)
+        return {k: v[0] for k, v in idx.items() if len(v) == 1}
+
+    matched_ref = {id(r) for r, _, _ in pairs}
+    for keyfn, label in (
+        (lambda e: f"{e['tag']}|{norm(e['text'])}" if norm(e["text"]) else None, "tag+text"),
+        (lambda e: norm(e["text"]) if norm(e["text"]) else None, "text"),
+    ):
+        ridx, lidx = index(ref_els, keyfn), index(loc_els, keyfn)
+        for k, r in ridx.items():
+            if id(r) in matched_ref:
+                continue
+            l = lidx.get(k)
+            if l and l["path"] not in used_loc:
+                pairs.append((r, l, label))
+                matched_ref.add(id(r))
+                used_loc.add(l["path"])
+
+    # An unmatched ref element is only "missing" if its text appears nowhere
+    # locally. Text that exists but is ambiguous (repeated nav labels, table
+    # cells) simply cannot be paired 1:1 — reporting it as missing sends the
+    # reader chasing content that is actually on the page.
+    loc_texts = {norm(e["text"]) for e in loc_els if norm(e["text"])}
+    missing, ambiguous = [], []
+    for e in ref_els:
+        t = norm(e["text"])
+        if id(e) in matched_ref or not t:
+            continue
+        (missing if t not in loc_texts else ambiguous).append(e)
+    return pairs, missing, ambiguous
+
+
+def diff_pair(r, l):
+    out = []
+    for p in PROPS:
+        a, b = r["styles"].get(p, ""), l["styles"].get(p, "")
+        if a != b:
+            out.append((p, a, b))
+    for dim in ("w", "h"):
+        if abs(r[dim] - l[dim]) > BOX_TOLERANCE_PX:
+            out.append((f"box-{dim}", f"{r[dim]}px", f"{l[dim]}px"))
+    return out
+
+
+def run_diff(args):
+    manual_map = {}
+    if args.map:
+        manual_map = json.load(open(args.map, encoding="utf-8"))
+
+    widths = [int(w) for w in args.widths.split(",")] if args.widths else [args.width]
+    sections, stdout_rows = [], []
+    prop_counter = Counter()
+    total_pairs = total_diffs = 0
+    overflow_notes = []
+
+    with sync_playwright() as p:
+        browser = p.chromium.launch(headless=True)
+        ctx = browser.new_context(ignore_https_errors=True)
+        page = ctx.new_page()
+        for w in widths:
+            page.set_viewport_size({"width": w, "height": args.height})
+            ref = collect(page, args.ref, args.wait_selector, args.extra_wait)
+            loc = collect(page, args.local, args.wait_selector, args.extra_wait)
+
+            if loc["docScrollWidth"] > loc["clientWidth"] + 1:
+                overflow_notes.append(
+                    f"{w}px: local has horizontal overflow "
+                    f"(scrollWidth {loc['docScrollWidth']} > clientWidth {loc['clientWidth']})"
+                )
+
+            pairs, missing, ambiguous = build_pairs(ref["elements"], loc["elements"], manual_map)
+            total_pairs += len(pairs)
+
+            rows = []
+            for r, l, how in pairs:
+                for prop, a, b in diff_pair(r, l):
+                    rows.append((prop, r["path"], l["path"], a, b, r["text"][:40], how))
+                    prop_counter[prop] += 1
+            total_diffs += len(rows)
+
+            sec = [f"\n## viewport {w}px\n",
+                   f"matched {len(pairs)} elements, {len(rows)} property diffs, "
+                   f"{len(missing)} missing locally, "
+                   f"{len(ambiguous)} not compared (text present but ambiguous)\n"]
+            if rows:
+                sec.append("\n| property | ref value | local value | ref selector | text |")
+                sec.append("|---|---|---|---|---|")
+                for prop, rp, lp, a, b, txt, how in sorted(rows):
+                    sec.append(f"| {prop} | `{a}` | `{b}` | `{rp}` | {txt} |")
+            if missing:
+                sec.append("\n### present in ref, missing locally\n")
+                for e in missing[:60]:
+                    sec.append(f"- `{e['tag']}` {e['text'][:90]}")
+                if len(missing) > 60:
+                    sec.append(f"- ...and {len(missing) - 60} more")
+            if ambiguous:
+                sec.append(
+                    f"\n### not compared: {len(ambiguous)} elements whose text is repeated on the page\n"
+                    "Add entries to `--map` to compare these explicitly.\n")
+            sections.append("\n".join(sec))
+            stdout_rows.append((w, len(pairs), len(rows), len(missing), len(ambiguous)))
+
+        browser.close()
+
+    report = [f"# visual-parity diff\n", f"- ref:   {args.ref}", f"- local: {args.local}",
+              f"- widths: {widths}"]
+    if overflow_notes:
+        report.append("\n**layout warnings**")
+        report += [f"- {n}" for n in overflow_notes]
+    report += sections
+    with open(args.out, "w", encoding="utf-8") as f:
+        f.write("\n".join(report))
+
+    print(f"report: {args.out}")
+    for w, np_, nd, nm, na in stdout_rows:
+        print(f"  {w}px: {np_} matched, {nd} diffs, {nm} missing-locally, {na} skipped-ambiguous")
+    for n in overflow_notes:
+        print(f"  WARN {n}")
+    if prop_counter:
+        print("\ntop differing properties (fix these systemically, not element by element):")
+        for prop, c in prop_counter.most_common(15):
+            print(f"  {c:4d}  {prop}")
+    return 1 if total_diffs else 0
+
+
+def save_video(video, out_path):
+    """Persist a Playwright video; convert to MP4 when the caller asked for one.
+
+    Returns the path actually written, which falls back to the .webm original
+    if ffmpeg is missing or fails.
+    """
+    root, ext = os.path.splitext(out_path)
+    ext = ext.lower()
+    webm = out_path if ext == ".webm" else root + ".webm"
+    video.save_as(webm)
+    if ext != ".mp4":
+        return webm
+    ffmpeg = shutil.which("ffmpeg")
+    if not ffmpeg:
+        print(f"  ffmpeg not found - kept {webm} (install with: brew install ffmpeg)")
+        return webm
+    try:
+        subprocess.run(
+            [ffmpeg, "-y", "-loglevel", "error", "-i", webm,
+             "-vf", "scale=trunc(iw/2)*2:trunc(ih/2)*2",
+             "-c:v", "libx264", "-preset", "veryfast", "-crf", "23",
+             "-pix_fmt", "yuv420p", "-movflags", "+faststart", out_path],
+            check=True, capture_output=True)
+    except subprocess.CalledProcessError as e:
+        print(f"  ffmpeg failed - kept {webm}: {e.stderr.decode()[:200]}")
+        return webm
+    os.remove(webm)
+    return out_path
+
+
+def run_flow(args):
+    steps = json.load(open(args.steps, encoding="utf-8"))
+    console_errors, failed_requests, results = [], [], []
+
+    video_path, tmpdir = None, None
+
+    with sync_playwright() as p:
+        browser = p.chromium.launch(headless=args.headless)
+        ctx_opts = {"ignore_https_errors": True}
+        if args.video:
+            w, h = (int(v) for v in args.video_size.lower().split("x"))
+            tmpdir = tempfile.mkdtemp(prefix="parity-video-")
+            ctx_opts.update(record_video_dir=tmpdir,
+                            record_video_size={"width": w, "height": h},
+                            viewport={"width": w, "height": h})
+        ctx = browser.new_context(**ctx_opts)
+        page = ctx.new_page()
+        page.on("console", lambda m: console_errors.append(f"[{m.type}] {m.text}"[:300])
+                if m.type in ("error", "warning") else None)
+        page.on("requestfailed", lambda r: failed_requests.append(f"{r.method} {r.url} — {r.failure}"[:300]))
+
+        for i, step in enumerate(steps):
+            act = step.get("action")
+            desc = step.get("desc", f"{act} {step.get('selector') or step.get('url') or ''}")
+            try:
+                if act == "goto":
+                    page.goto(step["url"], wait_until="domcontentloaded", timeout=60000)
+                    try:
+                        page.wait_for_load_state("networkidle", timeout=20000)
+                    except Exception:
+                        pass
+                elif act == "click":
+                    page.click(step["selector"], timeout=15000)
+                elif act == "fill":
+                    page.fill(step["selector"], step["value"], timeout=15000)
+                elif act == "press":
+                    page.press(step["selector"], step["key"], timeout=15000)
+                elif act == "wait":
+                    if "ms" in step:
+                        page.wait_for_timeout(step["ms"])
+                    else:
+                        page.wait_for_selector(step["selector"], timeout=step.get("timeout", 15000))
+                elif act == "expect_text":
+                    got = page.inner_text(step["selector"], timeout=15000)
+                    assert step["value"] in got, f"expected {step['value']!r} in {got[:120]!r}"
+                elif act == "expect_visible":
+                    assert page.is_visible(step["selector"]), "not visible"
+                elif act == "expect_focused":
+                    got = page.evaluate(
+                        "s => document.activeElement === document.querySelector(s)", step["selector"])
+                    assert got, "element is not document.activeElement"
+                elif act == "screenshot":
+                    page.screenshot(path=step["path"], full_page=step.get("full_page", True))
+                else:
+                    raise ValueError(f"unknown action {act!r}")
+                results.append((i, desc, "PASS", ""))
+            except Exception as e:
+                results.append((i, desc, "FAIL", str(e)[:300]))
+                if not args.keep_going:
+                    break
+
+        if args.video and args.video_tail:
+            page.wait_for_timeout(int(args.video_tail * 1000))
+        video = page.video if args.video else None
+        ctx.close()  # the video file is only finalized on context close
+        if video:
+            video_path = save_video(video, args.video)
+        browser.close()
+        if tmpdir:
+            shutil.rmtree(tmpdir, ignore_errors=True)
+
+    lines = ["# visual-parity flow\n", f"steps file: {args.steps}\n"]
+    if video_path:
+        lines.append(f"video: {video_path}\n")
+    lines += ["| # | step | result | detail |", "|---|---|---|---|"]
+    lines += [f"| {i} | {d} | {r} | {m} |" for i, d, r, m in results]
+    if console_errors:
+        lines += ["\n## console errors/warnings\n"] + [f"- {e}" for e in dict.fromkeys(console_errors)]
+    if failed_requests:
+        lines += ["\n## failed requests\n"] + [f"- {e}" for e in dict.fromkeys(failed_requests)]
+    with open(args.out, "w", encoding="utf-8") as f:
+        f.write("\n".join(lines))
+
+    failed = [r for r in results if r[2] == "FAIL"]
+    print(f"report: {args.out}")
+    if video_path:
+        print(f"video: {video_path}")
+    print(f"  {len(results) - len(failed)}/{len(results)} steps passed")
+    for i, d, r, m in failed:
+        print(f"  FAIL step {i}: {d} — {m}")
+    if console_errors:
+        print(f"  {len(set(console_errors))} unique console errors/warnings")
+    if failed_requests:
+        print(f"  {len(set(failed_requests))} failed requests")
+    return 1 if failed else 0
+
+
+def selftest():
+    """Assert the matcher and differ actually catch a known difference."""
+    a = """<html><body><h1>Hello</h1><p class=x>Body copy</p>
+      <ul><li>Item one</li></ul><div>Only in ref 🎉</div></body></html>"""
+    b = """<html><body><h1 style="font-size:40px">Hello</h1>
+      <div class=y style="margin-bottom:0">Body copy</div>
+      <ul><li style="color:rgb(255,0,0)">Item one</li></ul></body></html>"""
+    d = tempfile.mkdtemp()
+    for name, html in (("a.html", a), ("b.html", b)):
+        open(os.path.join(d, name), "w", encoding="utf-8").write(html)
+    out = os.path.join(d, "r.md")
+    args = argparse.Namespace(
+        ref="file://" + os.path.join(d, "a.html"), local="file://" + os.path.join(d, "b.html"),
+        map=None, widths=None, width=1440, height=900, wait_selector=None, extra_wait=0, out=out)
+    run_diff(args)
+    body = open(out, encoding="utf-8").read()
+    assert "font-size" in body, "should detect the h1 font-size change"
+    assert "color" in body, "should detect the li color change"
+    assert "Only in ref" in body, "should report the ref-only element as missing locally"
+    assert "`div`" in body or "margin-bottom" in body, "should match p->div across tag change"
+    print("\nselftest OK")
+
+
+def main():
+    # Windows consoles default to a legacy codepage (e.g. cp950); page text
+    # echoed to stdout must not crash the run.
+    for stream in (sys.stdout, sys.stderr):
+        if hasattr(stream, "reconfigure"):
+            stream.reconfigure(errors="replace")
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    d = sub.add_parser("diff", help="compare computed styles of two rendered URLs")
+    d.add_argument("--ref", required=True, help="reference URL (old page / staging)")
+    d.add_argument("--local", required=True, help="URL under development")
+    d.add_argument("--map", help="JSON file: {\"<ref selector>\": \"<local selector>\"} manual overrides")
+    d.add_argument("--width", type=int, default=1440)
+    d.add_argument("--widths", help="comma list, e.g. 375,768,1440 (overrides --width)")
+    d.add_argument("--height", type=int, default=900)
+    d.add_argument("--wait-selector", help="wait for this selector before collecting")
+    d.add_argument("--extra-wait", type=float, default=0, help="extra seconds after networkidle")
+    d.add_argument("--out", default="parity-diff.md")
+
+    r = sub.add_parser("responsive", help="diff at 375/768/1440 plus horizontal-overflow check")
+    for a in ("--ref", "--local"):
+        r.add_argument(a, required=True)
+    r.add_argument("--map")
+    r.add_argument("--height", type=int, default=900)
+    r.add_argument("--wait-selector")
+    r.add_argument("--extra-wait", type=float, default=0)
+    r.add_argument("--out", default="parity-responsive.md")
+
+    f = sub.add_parser("flow", help="run an interaction flow, collect console + network errors")
+    f.add_argument("--steps", required=True, help="JSON array of step objects")
+    f.add_argument("--out", default="parity-flow.md")
+    f.add_argument("--headed", dest="headless", action="store_false", default=True)
+    f.add_argument("--keep-going", action="store_true", help="continue after a failing step")
+    f.add_argument("--video", help="record the run to this path; .mp4 converts via ffmpeg, .webm keeps the native output")
+    f.add_argument("--video-size", default="1280x720", help="WxH of both the recording and the viewport (default 1280x720)")
+    f.add_argument("--video-tail", type=float, default=1.0, help="seconds to keep recording after the last step so trailing animations finish (default 1)")
+
+    sub.add_parser("selftest", help="verify the matcher/differ still work")
+
+    args = ap.parse_args()
+    if args.cmd == "diff":
+        sys.exit(run_diff(args))
+    if args.cmd == "responsive":
+        args.widths, args.width = "375,768,1440", 1440
+        sys.exit(run_diff(args))
+    if args.cmd == "flow":
+        sys.exit(run_flow(args))
+    selftest()
+
+
+if __name__ == "__main__":
+    main()