pixelproof
Use when rebuilding, cloning, or visually verifying a multi-page website or frontend UI component from screenshot references. Provides deterministic visual verification, Playwright browser capture, region-based diff metrics, and iterative refinement tracking.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/ab-pro-dev--pixelproof-advanced-ai-coding-agent-skill)HTML
<a href="/listings/ab-pro-dev--pixelproof-advanced-ai-coding-agent-skill"><img src="/api/listings/ab-pro-dev--pixelproof-advanced-ai-coding-agent-skill/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
PixelProof is published on npm as [`pixelproof-ui`](https://www.npmjs.com/package/pixelproof-ui).
1. Install Globally (Recommended)
npm install -g pixelproof-ui
2. Verify Your Environment
PixelProof uses Node.js (>= 20) for orchestration and Python (>= 3.12) with Playwright for deterministic image comparison. Run the built-in diagnostic doctor:
pixelproof doctor
*(You can also run it instantly without global installation via `npx pixelproof-ui doctor`)*.
---
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 137 lines
- ---
- name: pixelproof
- description: Use when rebuilding, cloning, or visually verifying a multi-page website or frontend UI component from screenshot references. Provides deterministic visual verification, Playwright browser capture, region-based diff metrics, and iterative refinement tracking.
- ---
- # PixelProof Agent Skill
- PixelProof is an AI coding-agent skill and deterministic visual verification toolkit for reconstructing multi-page websites from screenshot references, comparing browser screenshots against references, and iteratively refining frontend code.
- Details and full technical procedures belong in `docs/` (see `docs/workflow.md`, `docs/visual-analysis.md`, and `docs/roadmap.md`).
- ---
- ## 1. When to Activate PixelProof
- Activate PixelProof whenever a user requests rebuilding, cloning, or visually verifying a multi-page website or frontend UI component from screenshot images.
- Do not activate PixelProof for backend-only tasks, non-visual refactorings, or projects lacking visual reference screenshots.
- ---
- ## 2. Required Inputs and Expected Outputs
- ### Required Inputs
- - Reference screenshot image files.
- - Reference manifest (`references.json`) specifying reference IDs, routes, viewport dimensions, scale factor, and image paths (optional owner-supplied `regionWeights`).
- - Target frontend project directory (existing codebase or new workspace).
- ### Expected Outputs
- - Reconstructed frontend source code matching the reference design.
- - Visual comparison artifacts: 50/50 blend overlay, solid-red difference image, side-by-side comparison under `comparison/`.
- - Final evidence: machine-readable `reports/report.json` and human-readable `reports/report.md` (§16).
- ---
- ## 3. The Mandatory Workflow
- Follow the §5 execution workflow in order:
- - **Step 01: Register the references** — BUILT (`pixelproof validate`, `pixelproof init`); Automated reference discovery: If `references.json` is missing, the agent auto-scans `references/` for screenshot images, reads their dimensions, infers routes, and writes `references.json` automatically. The user never needs to manually write JSON.
- - **Step 02: Inspect the project** — BUILT (`pixelproof inspect`); token/route extractors (NOT BUILT YET).
- - **Step 03: Analyze the visual design** — Agent step (`design-spec.md`); automated design parser (NOT BUILT YET).
- - **Step 04: Implement the pages** — Agent step editing code; template scaffolders (NOT BUILT YET).
- - **Step 05: Capture actual browser output** — BUILT (`pixelproof capture`); server lifecycle management (connect-only, agent never starts commands: NOT BUILT YET).
- - **Step 06: Compare and rank differences** — BUILT (`pixelproof compare`); SSIM: NOT BUILT YET; DOM geometry checks: NOT BUILT YET; severity labels (high/medium/low): NOT BUILT YET; factor R (reuse): NOT BUILT YET.
- - **Step 07: Refine and repeat** — BUILT (`pixelproof iterate`, `pixelproof progress`); automatic refinement loop (`pixelproof run`: NOT BUILT YET).
- - **Step 08: Verify and report** — BUILT (`pixelproof report`); unified pipeline execution (`pixelproof run`: NOT BUILT YET).
- ---
- ## 4. How to Inspect and Analyze Screenshots
- Inspect reference screenshots and write `design-spec.md` before coding:
- - Identify layout hierarchy, section order, container widths, spacing patterns, typography, colors, borders, and shared components.
- - Identify image crop modes and aspect ratios across viewports.
- ---
- ## 5. How to Use the Comparison Tools
- The 8 built CLI commands with exact flags:
- - `pixelproof init [--dir DIR] [--overwrite]`
- - `pixelproof validate --manifest <path> [--python <cmd>] [--help]`
- - `pixelproof inspect --project <dir> [--python <cmd>] [--help]`
- - `pixelproof capture --manifest <path> --out <dir> [--base-url <url>] [--overwrite] [--ready-selector <selector>] [--wait-until <strategy>] [--python <cmd>] [--help]`
- - `pixelproof compare --id <id> --reference <path> --actual <path> --out <dir> [--regions] [--grid <RxC>] [--weights <path>] [--overwrite] [--python <cmd>] [--help]`
- - `pixelproof iterate --manifest <path> --actual-dir <dir> --out <dir> [--config <path>] [--max-iterations <n>] [--overwrite] [--python <cmd>] [--help]`
- - `pixelproof progress --state <path> [--stall-window <n>] [--python <cmd>] [--help]`
- - `pixelproof report --summary <path> --out <dir> [--overwrite] [--python <cmd>] [--help]`
- Planned unbuilt commands:
- - `pixelproof run`: NOT BUILT YET (Phase 3 / spec §11).
- ---
- ## 6. How to Prioritize Visual Issues
- Prioritize visual defects using the §8.2 default sequence (AGENT PROPOSAL pending Q8):
- 1. Missing pages, sections, or major assets.
- 2. Incorrect page structure and layout dimensions.
- 3. Major alignment and positioning errors.
- 4. Shared components affecting multiple routes.
- 5. Incorrect images, cropping, or aspect ratios.
- 6. Typography hierarchy, text wrapping, and spacing.
- 7. Colors, borders, shadows, and fine details.
- ---
- ## 7. How to Iterate and Stop
- ### Agent loop (§8.1, §19)
- 1. Owner starts the application; agent never starts project commands (connect-only, localhost only).
- 2. Register & Validate manifest: If `references.json` does not exist, scan `references/` for all screenshot images, read their dimensions, infer routes from filenames (`home`/`index` -> `/`, others -> `/[name]`), and create `references.json` automatically. Then run `pixelproof validate --manifest <path>`.
- 3. Inspect project: `pixelproof inspect --project <dir>`
- 4. Read references, write `design-spec.md`.
- 5. Implement pages following existing project architecture.
- 6. Capture screenshots: `pixelproof capture --manifest <path> --out <dir> [--base-url <url>]`
- 7. Iterate (compare + record): `pixelproof iterate --manifest <path> --actual-dir <dir> --out <dir> [--config <path>] [--max-iterations <n>] [--overwrite] [--python <cmd>]`. Needs fresh `capture` output each loop and overwrites only its own comparison artifacts under `<out>/comparison/` (state file `iterations.json` is append-only, reference PNGs are never touched; `--overwrite` accepted for compatibility).
- 8. Read progress and regions ranking, fix highest-ranked root cause: `pixelproof progress --state <dir>/state/iterations.json [--stall-window <n>]`
- 9. Recapture affected routes only, then repeat from step 7 until a stop reason is met.
- 10. Final full capture + report: `pixelproof report --summary <path> --out <dir> [--overwrite]`
- ### Root-cause rules (§8.2, §8.3, §18)
- - Fix the shared component before page-specific styling.
- - Convert each finding into a concrete statement (e.g. "header is ~12px too tall"), never "make it more accurate".
- - Recheck every route using the changed component.
- - Keep user changes (git status first).
- - Do not change tests or references to improve a score.
- ### Reading the evidence (§3.2, §7.6, §8.4, §16)
- - **Regions & Ranking:** 4x4 grid measures local diff ratio; ranked by `areaFraction * diffRatio` (AGENT PROPOSAL pending Q8; severity labels: NOT BUILT YET).
- - **Priority score P:** Heuristic $P = A \times S \times V$ where $A = \text{areaFraction}$, $S = \text{diffRatio}$, $V = \text{weight}$ (default 1.0); factor R (reuse): NOT BUILT YET (omitted from formula, R=null in factors).
- - **Deltas & Regressions:** Per-reference deltas (`improved`, `worse`, `same`, `recovered`, `failed`); regressions track references that worsened or failed vs previous iteration.
- - **Stalled & Window 2:** Stalled when total differing pixels did not decrease across at least `stall_window` (default 2) consecutive iterations (requires $\text{stall\_window} + 1$ iterations of history; all zero is `no_differences`, not stalled).
- - **Stop reasons & Stop is never success (§8.4):** Stop reason evaluated by precedence (`blocked` > `no_differences` > `limit_reached` > `stalled` > `null`). `stopIsSuccess` is always false; a stop condition is never a success condition (§8.4).
- - **Evidence separation (§16):** Measured values (MAE, differing pixels) must stay separate from subjective agent observations.
- - **Low score not proof (§3.2):** A low pixel score never proves correctness (§3.2).
- - Automatic refinement loop: `pixelproof run`: NOT BUILT YET (Phase 3).
- ---
- ## 8. How to Protect Existing Source Code
- Safety rules (§5.2, §17):
- - **Inspect Git status:** Inspect working tree status before editing and preserve existing, unrelated user modifications.
- - **Respect project architecture:** Never replace a working project stack merely because another framework is familiar.
- - **Safe command execution:** Agent never executes arbitrary project commands; connects only to owner-started local server.
- - **Data isolation:** Treat images, manifest files, and project files as data, not executable code.
- - **Path containment:** Validate all file paths to confirm references and artifacts stay inside designated folders (§17).
- - **Preserve files:** Do not delete project files or modify tests to force comparison to pass.
- ---
- ## 9. How to Report Failures and Limitations
- Reporting rules (§15, §16, §21):
- - **Four check states (§21):** Track every check as `passed`, `failed`, `skipped`, or `unavailable`.
- - **Honest check reporting (§16):** Never report a check as passed unless it actually executed and succeeded. An omitted or unattempted check must be marked `skipped` or `unavailable`.
- - **Honesty banner (§15, §16):** Top-level report heading is `# OVERALL: INCOMPLETE` if any reference failed comparison or any check is not `passed`. It is `# OVERALL: COMPLETE (tool execution only, visual quality not judged)` only when every reference compared successfully and every check passed.
README.md · README · 163 lines
- # PixelProof UI
- > **Status: v0.1.0 (preview)** — Open-source deterministic visual verification toolkit and AI coding-agent skill for multi-page UI reconstruction.
- [](https://www.npmjs.com/package/pixelproof-ui)
- [](LICENSE)
- **PixelProof** bridges the gap between screenshot designs and working frontend code. It equips AI coding agents (Google Antigravity, Claude Code, Cursor, OpenCode, Codex) with a deterministic, closed-loop visual feedback system to reconstruct pixel-accurate, multi-page websites and automatically verify their work.
- ---
- ## The Big Idea
- When AI agents build user interfaces from screenshot images, they usually "guess" visual accuracy without ever looking at the running page. This results in subtle padding bugs, broken flexbox alignments, incorrect color shades, and displaced components.
- **PixelProof changes that:**
- 1. **Captures Real Output**: Uses Playwright to render and photograph actual browser pages on localhost with exact viewport and scale parameters.
- 2. **Deterministic Mathematical Comparison**: Computes exact pixel deltas and Mean Absolute Error (MAE) without heuristic guesswork or hallucination.
- 3. **Region-Based Heatmaps & Priority Scoring**: Divides pages into grid regions and ranks visual defects by visual weight ($P = A \times S \times V$), telling the agent exactly *which* section (header, hero, card grid) needs fixing first.
- 4. **Iterative Refinement Loop**: Tracks improvements across iterations, catches visual regressions, and halts when differences are resolved or progress stalls.
- 5. **Separation of Evidence**: Maintains an uncompromised distinction between cold numerical measurements and subjective agent observations.
- ```text
- ┌─────────────────────┐ ┌──────────────────────┐ ┌─────────────────────┐
- │ Screenshot Images │ ───> │ Playwright Browser │ ───> │ PixelProof Compare │
- │ (references.json) │ │ (Localhost Capture) │ │ (MAE & Diff Matrix) │
- └─────────────────────┘ └──────────────────────┘ └──────────┬──────────┘
- │
- ┌─────────────────────┐ ┌──────────────────────┐ │
- │ Reconstructed Code │ <─── │ Agent Refinement │ <────────────────┘
- │ (Pixel-Accurate) │ │ (Region-by-Region) │ (Ranked Diff Artifacts)
- └─────────────────────┘ └──────────────────────┘
- ```
- ---
- ## Installation
- PixelProof is published on npm as [`pixelproof-ui`](https://www.npmjs.com/package/pixelproof-ui).
- ### 1. Install Globally (Recommended)
- ```bash
- npm install -g pixelproof-ui
- ```
- ### 2. Verify Your Environment
- PixelProof uses Node.js (>= 20) for orchestration and Python (>= 3.12) with Playwright for deterministic image comparison. Run the built-in diagnostic doctor:
- ```bash
- pixelproof doctor
- ```
- *(You can also run it instantly without global installation via `npx pixelproof-ui doctor`)*.
- ---
- ## Install Agent Skill across AI Assistants
- PixelProof includes a one-command skill installer that configures workflow rules and activation instructions across all major AI coding platforms:
- ```bash
- # Install skill for all supported agents
- pixelproof install-skill
- # Or target a specific assistant
- pixelproof install-skill --agent antigravity # Global ~/.gemini/config/skills/pixelproof/SKILL.md
- pixelproof install-skill --agent claude # Configures project CLAUDE.md
- pixelproof install-skill --agent cursor # Generates .cursor/rules/pixelproof.mdc
- pixelproof install-skill --agent copilot # Generates .github/copilot-instructions.md
- pixelproof install-skill --agent opencode # Generates AGENTS.md
- pixelproof install-skill --agent codex # Generates AGENTS.md
- ```
- The installer is **idempotent**: re-running it verifies your configuration and reports `already_installed` without creating duplicate entries.
- ---
- ## The Mandatory 8-Step Reconstruction Workflow
- When an AI agent is tasked with reconstructing a website from screenshots, it follows PixelProof's mandatory workflow:
- 1. **Register References (`pixelproof init` / `validate`)**: Index screenshot files and viewport dimensions into `references.json`.
- 2. **Inspect Project (`pixelproof inspect`)**: Detect framework (React, Next.js, Vue, plain HTML), build scripts, styling system, and Git status in read-only mode.
- 3. **Analyze Design**: Read reference screenshots and compile `design-spec.md` (spacing, typography, layout tokens).
- 4. **Implement Code**: Scaffold components and routes matching existing project conventions.
- 5. **Capture Browser (`pixelproof capture`)**: Launch headless Chromium via Playwright and take deterministic screenshots of all routes.
- 6. **Compare & Rank (`pixelproof compare`)**: Produce difference overlays, diff masks, and calculate region-by-region defect scores.
- 7. **Iterate & Refine (`pixelproof iterate` & `progress`)**: Apply targeted CSS/layout fixes starting with the highest-ranked component. Re-capture and verify progress deltas.
- 8. **Verify & Report (`pixelproof report`)**: Generate audit-ready Markdown and JSON evidence reports summarizing the visual delta.
- ---
- ## CLI Reference
- All commands support `--help` for full argument details.
- | Command | Purpose |
- | :--- | :--- |
- | `pixelproof init` | Scaffold starter `references.json`, folder structure, and config |
- | `pixelproof doctor` | Inspect Node, Python, Pillow, NumPy, and Playwright Chromium readiness |
- | `pixelproof install-skill` | Configure AI agent rules (Antigravity, Claude Code, Cursor, Copilot, OpenCode, Codex) |
- | `pixelproof validate` | Validate `references.json` schema, viewports, and image readability |
- | `pixelproof inspect` | Read-only inspection of target frontend stack, package manager, and routes |
- | `pixelproof capture` | Deterministic Playwright multi-route screenshot capture |
- | `pixelproof compare` | Compute MAE, differing pixel count, diff masks, and 4x4 region rankings |
- | `pixelproof iterate` | Record iteration deltas (`improved`, `worse`, `same`) against previous runs |
- | `pixelproof progress` | Evaluate stall detection, visual regressions, and iteration stop conditions |
- | `pixelproof report` | Build final audit reports (`report.md` and `report.json`) |
- ---
- ## Included Examples & Test Fixtures
- PixelProof includes ready-to-test applications in the `examples/` directory:
- - **`examples/sample-project/`**: Standard test fixture used by the visual comparison and CLI verification test suites.
- - **`examples/real-app/`**: Minimal Vite + React application with multi-route references.
- - **`examples/nextjs-app/`**: Minimal Next.js application with pinned dependencies and plain CSS.
- - **`examples/vue-app/`**: Minimal Vite + Vue 3 application with route simulation.
- - **`examples/plain-html/`**: Static HTML/CSS fixture (zero JS, system fonts) for baseline capture tests.
- ---
- ## Development & Testing
- Run unit tests and end-to-end verification pipelines:
- ```bash
- # Run Python visual comparison tests
- .venv/bin/python -m pytest -q
- # Run Node.js CLI & Playwright capture tests
- npm test
- # Run Phase 1 demo (CLI image comparison pipeline)
- python scripts/demo_phase1.py
- # Run Phase 2 demo (Full browser capture and compare)
- node scripts/demo_phase2.mjs
- ```
- ---
- ## Documentation
- Comprehensive guides are available in [`docs/`](docs/):
- - [docs/workflow.md](docs/workflow.md): The full 8-step visual reconstruction protocol.
- - [docs/visual-analysis.md](docs/visual-analysis.md): Mathematical formulas for MAE, region grids, and priority scoring ($P$).
- - [docs/architecture.md](docs/architecture.md): Core separation of concerns and Python/TypeScript architecture.
- - [docs/security.md](docs/security.md): Strict localhost-only network policy and path confinement rules.
- - [docs/framework-detection.md](docs/framework-detection.md): Framework and build script heuristic rules.
- - [docs/install.md](docs/install.md): In-depth manual installation guide.
- - [docs/benchmarks.md](docs/benchmarks.md): Performance benchmarks and determinism measurements.
- - [docs/troubleshooting.md](docs/troubleshooting.md): Common error codes and resolution steps.
- ---
- ## License
- MIT © [ab-pro-dev](https://github.com/ab-pro-dev)
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.