ghost-qa 1.3.1 → 2.0.0

package/README.md

@@ -1,9 +1,10 @@
 # 👻 ghost-qa
 
-**Autonomous headless browser QA & self-healing verification loop for coding agents.**
+**Autonomous headless browser QA & self-healing verification loop for coding agents.** `v2.0.0` — the 8-Trap Deep Browser Inspection Engine: 3 viewports × light/dark, QA Health Score (A+…F), interactive HTML dashboard, and regression diffing.
 
 [![CI](https://github.com/avivgerz-hue/ghost-qa/actions/workflows/ci.yml/badge.svg)](https://github.com/avivgerz-hue/ghost-qa/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/ghost-qa.svg)](https://www.npmjs.com/package/ghost-qa)
+[![npm downloads](https://img.shields.io/npm/dm/ghost-qa.svg)](https://www.npmjs.com/package/ghost-qa)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
 [![Node >= 20](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](https://nodejs.org)
 [![Powered by Playwright](https://img.shields.io/badge/powered%20by-Playwright-45ba4b.svg)](https://playwright.dev)
@@ -15,11 +16,13 @@ Coding agents (Claude Code, Codex, Cursor, Windsurf) write code **blind** — th
 `ghost-qa` fixes that. One command launches a headless browser against your running app, crawls the live DOM, safely pokes every button, traps runtime/network/layout failures, and hands the agent a structured **Self-Healing Bug Report** so it fixes its own bugs *before* telling you it's done.
 
 ```bash
-npx github:avivgerz-hue/ghost-qa test http://localhost:3000
+npx -y ghost-qa test http://localhost:3000
 ```
 
 No test scripts. No config. No mercy for "it works on my machine".
 
+> Prefer running straight from GitHub instead of npm? `npx -y github:avivgerz-hue/ghost-qa test http://localhost:3000` works identically — every command in this README accepts either package source (`ghost-qa mcp`, `ghost-qa init`, …).
+
 ---
 
 ## ⚡ Quickstart
@@ -30,10 +33,10 @@ npm run dev            # → http://localhost:3000
 
 # 2. Verify it in a real browser (one-time: downloads Chromium)
 npx playwright install chromium
-npx github:avivgerz-hue/ghost-qa test http://localhost:3000
+npx -y ghost-qa test http://localhost:3000
 
 # 3. Teach your coding agent to do this automatically, forever
-npx github:avivgerz-hue/ghost-qa init
+npx -y ghost-qa init
 ```
 
 `ghost-qa init` installs `.claude/skills/ghost-qa/SKILL.md` and appends the strict **"Verify in Browser Before Done"** protocol to `CLAUDE.md`, `AGENTS.md`, and `.cursorrules`. From then on, your agent runs ghost-qa itself, fixes what it finds, and only reports completion on a PASS.
@@ -63,76 +66,124 @@ npx github:avivgerz-hue/ghost-qa init
                     │        ▼                    ▼                      │
                     │   ┌─────────┐  ┌──────────┐  ┌─────────┐          │
                     │   │ CONSOLE │  │ NETWORK  │  │ LAYOUT  │          │
-                    │   │  A11Y   │  │  PERF    │  │ 5 TRAPS │          │
+                    │   │  A11Y   │  │  PERF    │  │ 8 TRAPS │          │
                     │   │  TRAP   │  │  TRAP    │  │  TRAP   │          │
                     │   └─────────┘  └──────────┘  └─────────┘          │
-                    │   Desktop 1440×900  +  Mobile 390×844 (iPhone)     │
+                    │   Desktop 1440×900 · Tablet 768×1024 · Mobile 375×812 │
                     └────────────────────────────────────────────────────┘
                                           │
                           fix bugs ───────┘  re-run until ✔ PASS
 ```
 
 1. The agent writes code and starts the dev server.
-2. `ghost-qa test` crawls every internal route on **desktop + mobile**, exercising interactive controls.
-3. Five traps capture everything the browser actually experienced.
-4. Failures return as a token-efficient diagnostic; the agent fixes the root causes and re-runs.
-5. The loop ends only at **PASS** — that's when the agent may tell you it's done.
+2. `ghost-qa test` crawls every internal route on **Desktop 1440×900, Tablet 768×1024 and Mobile 375×812**, in **light + dark** colour schemes, exercising interactive controls.
+3. Eight traps capture everything the browser actually experienced, scored into a deterministic **QA Health Score (0–100, Grade A+…F)**.
+4. Failures return as a token-efficient diagnostic (`GHOST-QA-REPORT.md` + `PATCH-PROMPT.md` with exact selectors); the agent fixes root causes and re-runs.
+5. `ghost-qa compare before.json after.json` proves the fix: the loop ends only at **score 95–100 (A+)**, zero critical/major remaining, and **zero new regressions**.
 
 ---
 
-## 🪤 The 5-Trap Engine
+## 🪤 The 8-Trap Deep Browser Inspection Engine *(v2.0.0)*
 
-### 1. Console Trap — `src/traps/console-trap.ts`
+### 1. Console & Framework Runtime Trap — `src/traps/console-trap.ts`
 - Uncaught `pageerror` exceptions with stack traces
 - Unhandled promise rejections
 - **React hydration mismatches** ("Text content did not match", "A tree hydrated but…")
+- **Duplicate-key warnings** and **Content-Security-Policy violations** *(new in v2)*
 - `console.error` (major) and `console.warning` (minor) — with dev-server noise (`[vite]`, HMR, React DevTools banners) filtered out
 
-### 2. Network Trap — `src/traps/network-trap.ts`
+### 2. Network & Asset Integrity Trap — `src/traps/network-trap.ts`
 - HTTP `5xx` API crashes (critical) and `4xx` responses (major)
-- Failed `fetch`/`XHR` requests and connection failures
-- **CORS-blocked requests** with remediation guidance
-- Broken static assets (JS/CSS/images/fonts) and missing favicons (minor)
+- Failed `fetch`/`XHR` requests, **timed-out requests**, and connection failures
+- **CORS-blocked requests and failed CORS preflights** with remediation guidance
+- Broken static assets, broken images (`naturalWidth === 0`), **broken inline SVGs (0×0)**, **>500KB unoptimized payloads**, and missing favicons (minor)
 
-### 3. Layout Trap — `src/traps/layout-trap.ts`
+### 3. Layout, Responsive Geometry & Collision Trap — `src/traps/layout-trap.ts`
 - **Horizontal overflow**: `scrollWidth > innerWidth`, with the offending elements named (critical on mobile)
+- **Overlapping interactive elements** via bounding-box collision math, with exact selectors + boxes *(new in v2)*
+- **Touch targets < 44×44px** on touch viewports (WCAG 2.5.5 / Apple HIG), **clipped text**, and **off-screen interactives** *(new in v2)*
 - Zero-dimension interactive elements — buttons rendered at 0×0 that no human could tap
-- Broken images (`naturalWidth === 0`)
 - Missing `<meta name="viewport">` on mobile
 
-### 4. Accessibility Trap — `src/traps/a11y-trap.ts` *(new in v1.1.0)*
+### 4. Accessibility (WCAG 2.1 AA) & Keyboard Focus Trap — `src/traps/a11y-trap.ts`
 - Buttons and links with **no accessible name** (icon-only controls screen readers can't identify)
 - Images **missing `alt`** attributes (descriptive alt, or `alt=""` for decorative)
 - Form inputs with **no associated label** — a placeholder is not a label
+- **Real computed contrast ratios** (`getComputedStyle` foreground vs effective background, WCAG formula) *(new in v2)*
+- **Heading hierarchy** (missing `<h1>`, h1→h3 skips) and **automated Tab-order verification** — simulated Tab presses catch invisible or dead focus states *(new in v2)*
 - Missing document `<title>` and missing `<html lang>`
 
-### 5. Performance & Asset Trap — `src/traps/perf-trap.ts` *(new in v1.1.0)*
+### 5. Performance & Core Web Vitals Trap — `src/traps/perf-trap.ts`
+- **Core Web Vitals**: TTFB, FCP, LCP estimation, and CLS (Cumulative Layout Shift) *(new in v2)*
 - Slow page loads via Navigation Timing (DOMContentLoaded / load budgets, 2× = critical)
-- **Oversized resources** (> 1MB single asset) and excessive total payload (> 3MB)
+- **Oversized resources** (> 1MB single asset), **unoptimized >500KB images/scripts**, and excessive total payload (> 3MB)
 - Main-thread jank / layout-thrashing indicators from the Long Tasks API
-- Render-blocking `<head>` resources and excessive DOM size
+- Render-blocking `<head>` resources, excessive DOM size (>1500 nodes) and **DOM depth > 32**
+
+### 6. Safe Interactive & Link Integrity Trap — `src/traps/links-trap.ts` *(new in v2)*
+- Placeholder links (`href=""`, `href="#"`, `javascript:void(0)`) and **dead anchors/routes** found during crawling
+- Buttons inside `<form>` with **no `type`** (they silently become submit buttons)
+- Disabled/stuck interactive controls — all observational, this trap never clicks anything
+
+### 7. SEO, Metadata & Social Graph Trap — `src/traps/seo-trap.ts` *(new in v2)*
+- `<title>` (missing, <10 or >60 chars), meta description, `<html lang>`, viewport meta, canonical tag
+- OpenGraph set (`og:title`, `og:description`, `og:image`) for link unfurls
+- **Duplicate `id` attributes** in the live, post-hydration DOM
+
+### 8. Dark / Light Theme Emulation Trap — `src/traps/theme-trap.ts` *(new in v2)*
+- Every page also renders under `colorScheme: 'dark'` and `'light'` emulation
+- Computed contrast is re-evaluated per scheme — invisible dark-mode text (dark-on-dark) is caught automatically and tagged with the failing scheme
 
 Plus a **safety-first Interaction Runner**: it fills forms with inert data (`ghost-qa@example.com`), opens tabs/modals/menus, and clicks ordinary buttons — but *never* destructive ones (`delete`, `checkout`, `pay`, `logout`, `publish`… are blocked by a tested safety gate).
 
 ---
 
-## 🔌 Native MCP Server *(new in v1.1.0)*
+## 📊 QA Health Score, Artifacts & Interactive Dashboard *(new in v2)*
+
+Every run computes a deterministic **QA Health Score (0–100)** and **Letter Grade (A+ … F)**: each trap starts at 100 and loses 25 per critical, 10 per major, 3 per minor finding; the overall score is the mean of the eight trap sub-scores (Console, Network, Layout, A11y, Performance, Links/UX, SEO/DOM, Theme Parity).
+
+```bash
+npx -y ghost-qa test http://localhost:3000 --out-dir ghost-qa-out --screenshots
+```
+
+| Artifact | Contents |
+| --- | --- |
+| `report.json` | Complete machine-readable telemetry: per-trap scores, viewport matrices, exact DOM selectors (`#id`, `data-testid`, CSS path) and bounding boxes |
+| `GHOST-QA-REPORT.md` | Human + agent Self-Healing Bug Report with root-cause analysis and the fix playbook |
+| `PATCH-PROMPT.md` | Copy-paste remediation prompt: every finding with selector, bounding box, parent-component hints and the compare loop |
+| `report.html` | Self-contained, zero-dependency, dark-mode **interactive QA Dashboard**: Grade hero (A+…F), 8-Trap Scorecard, Route & Viewport Matrix, filterable findings (severity/trap/viewport), embedded screenshots when captured |
+
+## 🔀 Regression Diffing — `ghost-qa compare` / `ghost_qa_compare` *(new in v2)*
+
+```bash
+npx -y ghost-qa test http://localhost:3000 --json > before.json   # baseline
+# …agent fixes the bugs…
+npx -y ghost-qa test http://localhost:3000 --json > after.json    # re-audit
+npx -y ghost-qa compare before.json after.json                    # Regression & Verification Delta Report
+```
+
+The delta matches findings by stable fingerprint id and reports **`scoreDelta`, `fixedFindings`, `newRegressions`, `remainingFindings`** — so a coding agent can *prove* its fix resolved the bug without introducing regressions. `verified` requires score ≥ 95, zero regressions and no blocking findings left. Also available as the `ghost_qa_compare` MCP tool.
+
+---
+
+## 🔌 Native MCP Server
 
 ghost-qa ships a zero-dependency **Model Context Protocol** server (JSON-RPC 2.0 over stdio), so MCP hosts can invoke browser verification as a native tool instead of shelling out:
 
 ```bash
-npx github:avivgerz-hue/ghost-qa mcp
+npx -y ghost-qa mcp
 ```
 
 | MCP tool | What it does |
 | --- | --- |
-| `ghost_qa_audit_url` | Runs the full crawl + 5-trap suite against a running URL and returns the Self-Healing Bug Report (text + structured content) |
+| `ghost_qa_audit_url` | Runs the full 8-trap deep inspection (3 viewports × light/dark) and returns the Self-Healing Bug Report + QA Health Score (structured content includes the full report for baselining) |
+| `ghost_qa_compare` | *(new in v2)* Diffs two report JSONs into the Regression & Verification Delta Report (`scoreDelta`, `fixedFindings`, `newRegressions`, `remainingFindings`) |
 | `ghost_qa_doctor` | Verifies Node, Chromium availability, and runs a live browser smoke test |
 
-`npx github:avivgerz-hue/ghost-qa init` writes the ready-to-use `.mcp.json` entry for you (merging with any servers you already have):
+`npx -y ghost-qa init` writes the ready-to-use `.mcp.json` entry for you (merging with any servers you already have):
 
 ```json
-{ "mcpServers": { "ghost-qa": { "command": "npx", "args": ["-y", "github:avivgerz-hue/ghost-qa", "mcp"] } } }
+{ "mcpServers": { "ghost-qa": { "command": "npx", "args": ["-y", "ghost-qa", "mcp"] } } }
 ```
 
 Works with Claude Code, Claude Desktop, Cursor, Codex — any MCP host.
@@ -151,7 +202,7 @@ docker run -i ghost-qa   # MCP JSON-RPC over stdin/stdout
 Don't even start the dev server yourself — ghost-qa will spawn it, wait for the URL to respond, audit, and terminate the whole process tree afterward:
 
 ```bash
-npx github:avivgerz-hue/ghost-qa test http://localhost:3000 --server-cmd "npm run dev"
+npx -y ghost-qa test http://localhost:3000 --server-cmd "npm run dev"
 ```
 
 Pair it with `--html ghost-qa-report.html` for a self-contained, dark-mode **visual evidence dashboard** (routes, interactions, every trap finding per viewport) you can attach to CI artifacts or PRs.
@@ -163,7 +214,7 @@ Pair it with `--html ghost-qa-report.html` for a self-contained, dark-mode **vis
 ```
 👻 ghost-qa — autonomous browser verification
 Target: http://localhost:3000/
-Duration: 8.4s · Viewports: desktop + mobile · Depth: 2
+Duration: 14.2s · Viewports: desktop + tablet + mobile · Schemes: light + dark · Depth: 2
 
 Routes crawled
   /                            Home                 [200] 3 issues
@@ -174,6 +225,7 @@ Coverage
   Routes visited:       3
   Interactions tested:  21 passed · 1 failed · 4 skipped (safety)
   Issues:               5 total — 2 critical, 3 major, 0 minor
+  QA Health Score:      62/100 — Grade D (8 traps · per-trap: console 65 · network 75 · layout 90 · a11y 100 · perf 100 · links 100 · seo 100 · theme 65)
 
 Failures caught
   ✖ CRITICAL [console] React hydration mismatch: Text content did not match…
@@ -196,7 +248,8 @@ The agent-facing report (`--report ghost-qa-report.md`) groups the same bugs by
 | --- | --- |
 | `ghost-qa test <url>` | Crawl a running app and trap browser failures. Exit `0` = PASS, `1` = blocking issues, `2` = runner error |
 | `ghost-qa init [--force]` | Install `.claude/skills/ghost-qa/SKILL.md`, verification protocol (`CLAUDE.md`, `AGENTS.md`, `.cursorrules`) + MCP config (`.mcp.json`) — all idempotent |
-| `ghost-qa mcp` | Run the native MCP server (JSON-RPC 2.0 over stdio) exposing `ghost_qa_audit_url` and `ghost_qa_doctor` |
+| `ghost-qa compare <before.json> <after.json>` | Regression & Verification Delta Report between two report JSONs. Exit `1` if new regressions appeared |
+| `ghost-qa mcp` | Run the native MCP server (JSON-RPC 2.0 over stdio) exposing `ghost_qa_audit_url`, `ghost_qa_compare` and `ghost_qa_doctor` |
 | `ghost-qa doctor` | Diagnose Node ≥ 20, Playwright and Chromium setup, with a live browser smoke test |
 | `ghost-qa --version` / `--help` | Version / usage |
 
@@ -207,7 +260,10 @@ The agent-facing report (`--report ghost-qa-report.md`) groups the same bugs by
 | `--max-depth <n>` | `2` | Link-following depth from the start URL |
 | `--max-routes <n>` | `25` | Maximum routes to visit |
 | `--timeout <ms>` | `15000` | Per-navigation timeout |
-| `--viewport <name>` | `both` | `both` \| `desktop` \| `mobile` |
+| `--viewport <name>` | `all` | `all` \| `both` (desktop+mobile) \| `desktop` \| `tablet` \| `mobile` |
+| `--color-scheme <name>` | `both` | `both` \| `light` \| `dark` — colour schemes emulated per viewport |
+| `--screenshots` | off | Capture a screenshot per route/viewport for the HTML dashboard |
+| `--out-dir <dir>` | — | Write `report.json` + `GHOST-QA-REPORT.md` + `PATCH-PROMPT.md` + `report.html` into this directory |
 | `--no-interactions` | off | Load pages only; don't click or fill anything |
 | `--headed` | off | Show the browser window (debugging) |
 | `--fail-on <severity>` | `major` | Exit 1 on `critical` \| `major` \| `minor` issues |
@@ -224,7 +280,7 @@ Works with any stack that serves HTML on localhost — Next.js, Vite, Remix, Ast
 
 ## 🤖 The Agent Skill
 
-`SKILL.md` (repo root) is the master skill. `npx github:avivgerz-hue/ghost-qa init` installs it for:
+`SKILL.md` (repo root) is the master skill. `npx -y ghost-qa init` installs it for:
 
 - **Claude Code** → `.claude/skills/ghost-qa/SKILL.md` + protocol in `CLAUDE.md`
 - **Codex / generic agents** → protocol in `AGENTS.md`

package/SKILL.md

@@ -1,18 +1,16 @@
 ---
 name: ghost-qa
-description: Verify frontend work in a real headless browser before reporting a task complete. Use after building or changing any UI, route, form, API integration, or client-side logic — crawls the running app on desktop and mobile, runs a 5-trap engine (console/hydration, network, layout, accessibility, performance), exercises interactive controls, and returns a self-healing bug report to fix from. Also usable via the ghost_qa_audit_url MCP tool.
+description: Verify frontend work in a real headless browser before reporting a task complete. The autonomous Staff QA Engineer protocol — doctor readiness, multi-viewport 8-Trap baseline audit (Desktop/Tablet/Mobile, light + dark), DOM-to-source root-cause mapping, surgical remediation, and closed-loop delta verification with ghost_qa_compare until QA Health Score is 95–100 (Grade A+). Use after building or changing any UI, route, form, API integration, or client-side logic.
 license: MIT
 ---
 
-# 👻 ghost-qa — Verify in Browser Before Done
+# 👻 ghost-qa — Autonomous Staff QA Engineer Protocol
 
-Coding agents write code blind. Code that type-checks can still ship with React hydration mismatches, uncaught exceptions, 500ing APIs, dead buttons, icon-only controls no screen reader can name, and mobile layouts that scroll sideways. **The browser is the source of truth — never your mental model of the DOM.**
+Coding agents write code blind. Code that type-checks can still ship with React hydration mismatches, uncaught exceptions, 500ing APIs, dead links, invisible dark-mode text, 30px tap targets, and mobile layouts that scroll sideways. **The browser is the source of truth — never your mental model of the DOM.**
 
-## The Rule
+> **The Rule:** Before reporting ANY task that touches frontend code as complete, you MUST execute all five phases below, in order, and finish with a verified delta: QA Health Score 95–100 (Grade A+ band), zero critical/major findings, zero new regressions.
 
-> Before reporting ANY task that touches frontend code as complete, you MUST run the app in a real browser with ghost-qa, fix everything blocking it catches, and re-run until it passes.
-
-Unit tests, type-checking, linting and code review do **not** satisfy this rule. They cannot see hydration, layout, network or accessibility failures.
+Unit tests, type-checking, linting and code review do **not** satisfy this rule. They cannot see hydration, layout, network, contrast or focus failures.
 
 ## When to use this skill
 
@@ -20,86 +18,91 @@ Unit tests, type-checking, linting and code review do **not** satisfy this rule.
 - ✅ You fixed a bug that manifested in the browser
 - ✅ You are about to tell the user a UI task is "done"
 
-**Not a substitute for:** your unit/E2E test suites, a full WCAG accessibility audit (ghost-qa's a11y trap covers common machine-checkable failures, not full WCAG conformance), load testing, or manual exploratory QA.
+**Not a substitute for:** your unit/E2E suites, a full manual WCAG audit (the a11y trap covers machine-checkable WCAG 2.1 AA failures), load testing, or exploratory QA.
 
-## Choose your path
+## The 8-Trap Deep Browser Inspection Engine
 
-| Situation | Command |
-| --- | --- |
-| Dev server already running | `npx github:avivgerz-hue/ghost-qa test <url>` |
-| Server not running (most common) | `npx github:avivgerz-hue/ghost-qa test <url> --server-cmd "npm run dev"` — ghost-qa spawns it, waits for it, audits, and kills the process tree afterward |
-| Your host exposes MCP tools | Call **`ghost_qa_audit_url`** with the URL (call `ghost_qa_doctor` first if it errors) — identical engine, identical report |
-| Mobile-only bug hunt | add `--viewport mobile` |
-| Large app | add `--max-depth 3 --max-routes 50` |
-| Evidence for a PR/CI | add `--report ghost-qa-report.md --html ghost-qa-report.html` |
-
-Common local URLs: Next.js / CRA `http://localhost:3000`, Vite `http://localhost:5173`, Astro `http://localhost:4321`, Angular `http://localhost:4200`. If unsure, check the dev server output or `package.json` scripts — never guess silently; state the URL you verified in your completion message.
-
-## The Self-Healing Loop
-
-1. **Run the audit** (path table above). The 5-Trap Engine checks, on Desktop 1440×900 *and* Mobile 390×844:
-   - **Console** — uncaught errors, unhandled promise rejections, React hydration mismatches, `console.error`
-   - **Network** — HTTP 4xx/5xx, failed fetch/XHR, CORS failures, broken assets
-   - **Layout** — horizontal overflow, zero-size interactive elements, broken images, missing viewport meta
-   - **Accessibility** — buttons/links with no accessible name, images missing `alt`, inputs with no label, missing `<title>` / `<html lang>`
-   - **Performance** — slow loads, oversized assets/payloads, main-thread long-task jank, render-blocking resources, excessive DOM
-2. **Read the Self-Healing Bug Report.** Every issue has a stable `#id`, a severity (`critical` / `major` / `minor`), the route, and the viewport. Fix **critical and major** issues. Note minors; fix them when cheap.
-3. **Fix root causes in source** (fix guidance below). Reference issues by `#id` in your own narration so the user can follow along.
-4. **Re-run the identical command.** A fix that breaks a different route or viewport only shows up on re-run.
-5. **Repeat until `GHOST-QA PASS`.** If you have looped 5 times on the same `#id`, stop and report to the user what is stuck and why — do not silently give up or declare success.
-6. **Only then** report completion, using the completion template below.
-
-## Fix guidance per trap
-
-| Trap | Typical root causes | Fix like this |
+Every audit crawls each route on **Desktop 1440×900, Tablet 768×1024 and Mobile 375×812**, under **light + dark** colour schemes:
+
+| # | Trap | What it catches |
 | --- | --- | --- |
-| Hydration mismatch | `Date.now()`/`Math.random()`/`window` during render, server/client branching, invalid HTML nesting (`<p>` in `<p>`, `<div>` in `<p>`) | Make server and client render identical markup; move time/random/client-only values into `useEffect` + state; fix the nesting |
-| Uncaught page error | undefined data, missing null checks on async data, bad imports | Reproduce via the stack trace in the report; guard the actual data path |
-| Console error | failed state updates, rejected promises, React warnings treated seriously by the app | Trace the first error, not the cascade after it |
-| HTTP 5xx | API route crash, bad env var, DB down | Read the server logs for that endpoint; the browser found it, the fix is server-side |
-| HTTP 404 / broken asset | wrong path, case-sensitivity, asset not emitted by the build | Compare the URL in the report with the actual build output / public dir |
-| CORS failure | API missing `Access-Control-Allow-Origin` for the page origin | Fix the API's CORS config (or the dev proxy), not the fetch call |
-| Horizontal overflow | `100vw` + scrollbar, fixed-width children, flex/grid children without `min-width: 0` | Constrain widths (`max-width: 100%`, `min-width: 0`, `overflow-wrap`); the report names the offending elements |
-| Zero-size interactive | collapsed CSS, `display: contents` misuse, content that never rendered | Restore a real, tappable size (≥ 24px, ideally ≥ 40px on mobile) |
-| No accessible name | icon-only `<button>`/`<a>` | Add visible text or `aria-label` describing the action/destination |
-| Missing `alt` | forgotten attribute | Descriptive alt; `alt=""` only if purely decorative |
-| Input without label | placeholder used as label | Real `<label for>`, wrapping `<label>`, or `aria-label` |
-| Slow load / oversized asset | unoptimized images, giant bundles, blocking scripts | Compress/lazy-load, `defer`/`async`, code-split; check the named resource first |
-| Long-task jank | heavy sync JS, layout reads in loops after writes | Break up work, memoize, batch DOM reads before writes |
-
-## Anti-cheating rules (this is the point of the skill)
-
-- ❌ Never silence the checker: no deleting the failing UI, no blanket `try/catch`, no `suppressHydrationWarning`, no removing the code path "so the error goes away"
-- ❌ Never use `--no-interactions` or narrow `--viewport`/`--max-depth` to hide failures (legitimate only when a page has side-effectful controls, and you must say so)
-- ❌ Never edit ghost-qa's report, thresholds, or your project's ghost-qa invocation to manufacture a PASS
-- ✅ If a finding is a genuine false positive, say so explicitly in your completion message with the `#id` and why — a human can overrule the tool; you may not quietly ignore it
-
-## Safety guarantees you can rely on
-
-ghost-qa never clicks destructive controls (delete, checkout, pay, logout, publish, sign-in…), never submits real orders/payments, fills forms only with inert data (`ghost-qa@example.com`, `ghost-qa test`), stays on same-origin links, and is designed for localhost/dev servers. **Do not point it at production systems you do not own or have permission to test.** Pages behind authentication will typically redirect to a login page — ghost-qa will audit what an anonymous visitor sees; say so if that's what happened.
+| 1 | Console & Framework Runtime | `pageerror`, `console.error`, unhandled rejections, React/Next.js hydration mismatches, duplicate-key warnings, CSP violations |
+| 2 | Network & Asset Integrity | 4xx/5xx, timed-out/aborted requests, failed CORS preflights, broken images (`naturalWidth === 0`), broken inline SVGs (0×0), >500KB unoptimized payloads |
+| 3 | Layout, Responsive Geometry & Collision | Horizontal overflow, overlapping interactive elements (bounding-box collision math), <44×44px touch targets, clipped text, off-screen interactives |
+| 4 | Accessibility (WCAG 2.1 AA) & Keyboard Focus | Missing accessible names/labels/alt, heading hierarchy breaks, real computed contrast ratios, automated Tab-order verification (invisible/dead focus) |
+| 5 | Performance & Core Web Vitals | TTFB, FCP, LCP, CLS, DOM bloat (>1500 nodes), DOM depth (>32), render-blocking scripts, long tasks |
+| 6 | Safe Interactive & Link Integrity | Placeholder hrefs (`""`, `#`, `javascript:void(0)`), dead anchors/routes, in-form buttons without `type`, stuck disabled controls |
+| 7 | SEO, Metadata & Social Graph | Title length, meta description, `<html lang>`, viewport meta, canonical, OpenGraph set, duplicate `id`s |
+| 8 | Dark / Light Theme Emulation | Contrast/visibility recomputed under `colorScheme: light` and `dark` — catches invisible dark-mode text |
 
-## Troubleshooting
+Scoring is deterministic: each trap starts at 100, −25 per critical, −10 per major, −3 per minor. The **QA Health Score** is the mean of the 8 trap scores, graded **A+ (97+) … F (<60)**.
 
-| Symptom | Do this |
-| --- | --- |
-| "could not launch Chromium" | `npx playwright install chromium` (one-time), then `npx github:avivgerz-hue/ghost-qa doctor` |
-| `navigation-failed` on every route | Server isn't on that URL/port — start it, or re-run with `--server-cmd "npm run dev"` |
-| Everything 404s | Wrong port or base path — confirm the URL in a browser/`curl` yourself first |
-| Audit seems to test a login page | The app requires auth for those routes; report that limitation instead of claiming full verification |
-| Perf findings vary between runs | Machine load affects timings; re-run once before treating a borderline perf major as real |
-| MCP tool unavailable | Fall back to the CLI — the audit engine and report are identical |
+---
+
+## Phase 1 — Environment & Server Readiness (`ghost_qa_doctor`)
+
+1. Call the **`ghost_qa_doctor`** MCP tool, or run `npx -y ghost-qa doctor`.
+2. It must report **READY**: Node ≥ 20, Chromium installed, live browser smoke test passing.
+3. If Chromium is missing: `npx playwright install chromium` (one-time), then re-run doctor. **Never skip to Phase 2 on a red doctor** — a failed launch is not a passing audit.
+4. Start the app (`npm run dev`) or plan to use `--server-cmd "npm run dev"` / let the audit spawn it.
+
+## Phase 2 — Multi-Viewport 8-Trap Baseline Audit (`ghost_qa_audit_url`)
+
+Run the baseline BEFORE changing code (or before your fix, when debugging):
+
+- MCP: call **`ghost_qa_audit_url`** with the app URL. Save the full returned report JSON as **`before.json`**.
+- CLI equivalent: `npx -y ghost-qa test <local-url> --out-dir ghost-qa-out` → writes `report.json` (copy to `before.json`), `GHOST-QA-REPORT.md`, `PATCH-PROMPT.md`, and the interactive `report.html` dashboard. Add `--screenshots` for embedded route screenshots; `--server-cmd "npm run dev"` if the server isn't running.
+
+Record the baseline: **QA Health Score, grade, per-trap scores, and every finding's `#id`.** Common local URLs: Next.js/CRA `http://localhost:3000`, Vite `http://localhost:5173`, Astro `http://localhost:4321`, Angular `http://localhost:4200`. Never guess silently — state the URL you verified.
 
-## Completion template
+## Phase 3 — DOM-to-Source Root-Cause Mapping
 
-When the final run passes, report completion like this:
+For every critical/major finding, trace it back to the exact source component before editing:
 
-> ✅ Done. Verified in a real browser with ghost-qa: `npx github:avivgerz-hue/ghost-qa test <url>` → **GHOST-QA PASS**
-> Routes crawled: N · Interactions tested: N · Issues fixed this session: (list `#id`s, or "none found")
-> Stack: desktop 1440×900 + mobile 390×844, 5 traps (console, network, layout, accessibility, performance)
+- **Exact selectors:** findings carry `#id`, `[data-testid=…]`, or a CSS path, plus the live **bounding box**. Search the codebase for that id/testid/class or the element's visible text to find the React/Next.js/Vue/Svelte component that renders it.
+- **Collisions/overflow:** the two colliding selectors + boxes tell you which siblings overlap — inspect their flex/grid/absolute layout in that component, on the failing viewport.
+- **Console stacks:** follow the first app-owned stack frames to the throwing component/effect. Hydration mismatches mean server and client rendered different markup (Date/random/`window` at render, invalid nesting like `<p>` in `<p>`).
+- **Dark-mode contrast:** a `theme-contrast` finding names the scheme that fails — find the hard-coded colour in that component and replace it with the theme token.
+- **Network:** map the failing URL to its route handler/client fetch; 5xx is server code, CORS preflight is API config.
 
-## Completion checklist
+Write the mapping down (finding `#id` → file → root cause) before Phase 4. If you cannot map a finding, say so — do not guess-fix.
+
+## Phase 4 — Surgical Code Remediation
+
+Fix root causes, one finding at a time, in severity order (critical → major → minor):
+
+- **Hydration:** identical server/client markup; defer client-only values to effects; fix invalid HTML nesting. Never `suppressHydrationWarning` to silence it.
+- **Responsive geometry:** `min-width: 0` on flex/grid children, `max-width: 100%`, no `100vw` + scrollbar overflow, reserve image space with width/height or `aspect-ratio` (also fixes CLS).
+- **Tap targets:** every touch target ≥ 44×44px (padding or min-height/min-width).
+- **ARIA/labels:** visible text or `aria-label` on icon controls, `<label for>` (or wrapping label) per input, `alt` on images (`alt=""` only if decorative), one `<h1>`, no heading level skips, visible `:focus-visible` rings — never `outline: none` without a replacement.
+- **Dark-mode tokens:** CSS variables / `dark:` variants driven by `prefers-color-scheme` or the app theme — never hard-coded hex that only works in one scheme.
+- **Links/forms:** real hrefs or `<button type="button">`; dead anchors get real targets; in-form buttons get explicit `type`.
+- **Performance:** defer/async non-critical scripts, compress/resize/lazy-load >500KB assets, code-split, break up long tasks.
+
+**Anti-cheating rules (absolute):** never delete failing UI, never loosen the checker, never hide elements from the traps, never stub network responses. Fixing the checker instead of the bug is a failed task.
+
+## Phase 5 — Closed-Loop Delta Verification (`ghost_qa_compare`)
+
+1. Re-run the identical audit (same URL/viewports) → save as **`after.json`**.
+2. Compare: MCP **`ghost_qa_compare`** with `{ before, after }`, or `npx -y ghost-qa compare before.json after.json`.
+3. Read the **Regression & Verification Delta Report**: `scoreDelta`, `fixedFindings`, `newRegressions`, `remainingFindings`.
+4. **Done only when ALL hold:** QA Health Score **95–100 (Grade A+ band)** · zero critical/major remaining · **zero new regressions** (`verified: true`). Otherwise loop back to Phase 3 with the delta as your new worklist.
+5. If the same `#id` survives 5 loops, stop and report honestly what you tried — never declare success on a red delta.
+
+## Completion report (required format)
+
+> ✅ Done. Verified in a real browser with ghost-qa: `ghost_qa_audit_url` on `<url>`
+> Stack: Desktop 1440×900 + Tablet 768×1024 + Mobile 375×812, light + dark, 8 traps
+> QA Health Score: `<before>` → `<after>` (Grade `<grade>`) · Delta: `<n>` fixed, 0 new regressions
+> Routes crawled: `<n>` · Interactions tested: `<n>` · Artifacts: `report.json`, `GHOST-QA-REPORT.md`, `PATCH-PROMPT.md`, `report.html`
+
+## Troubleshooting
+
+| Symptom | Fix |
+| --- | --- |
+| "could not launch Chromium" | `npx playwright install chromium` (one-time), then `npx -y ghost-qa doctor` |
+| Navigation failures on every route | The dev server isn't running (or wrong port) — start it, or use `--server-cmd "npm run dev"` |
+| Score stuck below 95 | Work the delta's remaining findings by severity; re-check Phase 3 mapping before editing |
+| A trap flags a healthy page | File an issue with `report.json` attached — false positives are the most valuable bug reports |
 
-- [ ] Final code state audited (not an earlier draft of the change)
-- [ ] All critical/major issues fixed at the root cause, or explicitly reported as false positives with reasoning
-- [ ] Final run prints `GHOST-QA PASS`
-- [ ] Completion message uses the template above and names the URL verified
+> All commands use the published npm package (`npx -y ghost-qa …`). If npm is unavailable, `npx -y github:avivgerz-hue/ghost-qa …` runs the identical CLI straight from GitHub.

package/dist/bin/ghost-qa.d.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { type GhostQAOptions } from '../src/types.js';
-export declare const VERSION = "1.3.0";
-export declare const AGENT_PROTOCOL = "<!-- ghost-qa:start -->\n## \uD83D\uDC7B ghost-qa \u2014 Browser Verification Protocol (MANDATORY)\n\nBefore reporting any task that touches frontend code as complete, you MUST verify it in a real browser:\n\n1. Ensure the app is running locally (e.g. `npm run dev`).\n2. Run: `npx github:avivgerz-hue/ghost-qa test <local-url>` (e.g. `npx github:avivgerz-hue/ghost-qa test http://localhost:3000`) \u2014 or call the `ghost_qa_audit_url` MCP tool if your host exposes it. Add `--server-cmd \"npm run dev\"` to let ghost-qa manage the dev server itself.\n3. If ghost-qa reports ANY critical or major issue (hydration errors, console errors, 4xx/5xx responses, mobile overflow, accessibility or performance failures, broken interactions), fix the root cause in source and re-run.\n4. Repeat until ghost-qa prints **PASS**. Only then may you tell the user the task is done.\n\nNever declare a UI task finished based only on code review, type-checking, or unit tests. The browser is the source of truth.\n<!-- ghost-qa:end -->";
+export declare const VERSION: string;
+export declare const AGENT_PROTOCOL = "<!-- ghost-qa:start -->\n## \uD83D\uDC7B ghost-qa \u2014 Browser Verification Protocol (MANDATORY)\n\nBefore reporting any task that touches frontend code as complete, you MUST verify it in a real browser \u2014 the closed-loop Self-Healing Browser Verification Protocol:\n\n1. **Readiness:** run `ghost-qa doctor` (or the `ghost_qa_doctor` MCP tool). Do not proceed on red.\n2. **Baseline audit:** ensure the app runs locally, then `npx -y ghost-qa test <local-url> --out-dir ghost-qa-out` (add `--server-cmd \"npm run dev\"` to let ghost-qa manage the server) \u2014 or call `ghost_qa_audit_url`. This runs the 8-Trap Engine on Desktop 1440\u00D7900, Tablet 768\u00D71024 and Mobile 375\u00D7812, light + dark. Save the baseline as `before.json` (it is `ghost-qa-out/report.json`).\n3. **Root-cause mapping:** for every critical/major finding, map the exact DOM selector, bounding box, stack trace or dark-mode contrast failure back to the component file that renders it.\n4. **Surgical remediation:** fix root causes in source (hydration, overflow, tap targets, ARIA/labels, dark-mode tokens\u2026). Never silence the checker or delete failing UI.\n5. **Delta verification:** re-run the audit to `after.json`, then `npx -y ghost-qa compare before.json after.json` (or `ghost_qa_compare`). Repeat until QA Health Score is **95\u2013100 (A+)**, zero critical/major remain, and the delta shows **zero new regressions**. Only then report done, citing score, routes, viewports and the delta.\n\nNever declare a UI task finished based only on code review, type-checking, or unit tests. The browser is the source of truth.\n<!-- ghost-qa:end -->";
 export interface ParsedTestArgs {
     target: string;
     options: GhostQAOptions;
@@ -9,10 +9,18 @@ export interface ParsedTestArgs {
     quiet: boolean;
     reportFile?: string;
     htmlFile?: string;
+    outDir?: string;
     serverCmd?: string;
     serverTimeoutMs: number;
 }
 export declare function parseTestArgs(args: string[]): ParsedTestArgs;
+export interface ParsedCompareArgs {
+    beforeFile: string;
+    afterFile: string;
+    json: boolean;
+    outFile?: string;
+}
+export declare function parseCompareArgs(args: string[]): ParsedCompareArgs;
 export declare function installSkill(targetDir: string, force?: boolean): Promise<Array<{
     file: string;
     action: string;
@@ -20,7 +28,7 @@ export declare function installSkill(targetDir: string, force?: boolean): Promis
 /**
  * Writes (or merges into) `.mcp.json`, preserving any MCP servers the
  * project already configured. The ghost-qa entry is always refreshed so
- * hosts invoke the published CLI: `npx -y github:avivgerz-hue/ghost-qa mcp`.
+ * hosts invoke the published CLI: `npx -y ghost-qa mcp`.
  */
 export declare function installMcpConfig(mcpJsonPath: string, force?: boolean): Promise<string>;
 export declare function main(argv?: string[]): Promise<number>;

package/dist/bin/ghost-qa.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ghost-qa.d.ts","sourceRoot":"","sources":["../../bin/ghost-qa.ts"],"names":[],"mappings":";AAWA,OAAO,EAAmB,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEvE,eAAO,MAAM,OAAO,UAAmB,CAAC;AAKxC,eAAO,MAAM,cAAc,mgCAWX,CAAC;AAyEjB,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,cAAc,CAAC;IACxB,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,cAAc,CA+E5D;AAyDD,wBAAsB,YAAY,CAChC,SAAS,EAAE,MAAM,EACjB,KAAK,UAAQ,GACZ,OAAO,CAAC,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,CAqBlD;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,WAAW,EAAE,MAAM,EACnB,KAAK,UAAQ,GACZ,OAAO,CAAC,MAAM,CAAC,CAuBjB;AAuCD,wBAAsB,IAAI,CAAC,IAAI,WAAwB,GAAG,OAAO,CAAC,MAAM,CAAC,CAoDxE;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,SAAS,GAAE,MAAwB,GAClC,OAAO,CAOT"}
+{"version":3,"file":"ghost-qa.d.ts","sourceRoot":"","sources":["../../bin/ghost-qa.ts"],"names":[],"mappings":";AAYA,OAAO,EAAmB,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEvE,eAAO,MAAM,OAAO,QAAmB,CAAC;AAKxC,eAAO,MAAM,cAAc,8mDAYX,CAAC;AAoFjB,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,cAAc,CAAC;IACxB,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,cAAc,CAgG5D;AAED,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,iBAAiB,CAiBlE;AAiFD,wBAAsB,YAAY,CAChC,SAAS,EAAE,MAAM,EACjB,KAAK,UAAQ,GACZ,OAAO,CAAC,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,CAqBlD;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,WAAW,EAAE,MAAM,EACnB,KAAK,UAAQ,GACZ,OAAO,CAAC,MAAM,CAAC,CAuBjB;AAuCD,wBAAsB,IAAI,CAAC,IAAI,WAAwB,GAAG,OAAO,CAAC,MAAM,CAAC,CAiExE;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,SAAS,GAAE,MAAwB,GAClC,OAAO,CAOT"}