This is a submission for the Hacktoberfest Open-Source AI Challenge Week 3: Slow and Steady

What I Built

PixelBreak is a pre-commit hook + CLI tool that automatically catches responsive layout failures and visual regressions before they land in your repo — without any manual steps, subscriptions, or cloud services.

Every time you git commit, PixelBreak:

1. Scans your running app at every configured viewport width (375px → 1920px) using a real Chromium browser
2. Detects horizontal overflow and element clipping with deterministic pixel measurements
3. Compares screenshots against the previous committed version automatically — no manual baseline setup
4. Blocks the commit if anything breaks and opens a localhost dashboard showing exactly what changed

Who gets to be lazier: frontend developers who used to manually resize their browser at 5+ widths after every CSS change, or pay for Percy/Chromatic subscriptions. With PixelBreak, you just commit. The tool does the rest.

Demo

PixelBreak Dashboard — 6 findings blocked across 375px, 768px, 1024px, 1280px, 1440px, 1920px

Visual regression finding — Baseline (before), Current (after your change), Diff (changed pixels highlighted)

Since PixelBreak is a local-first tool, here's what a real terminal run looks like:

# Developer changes a CSS variable and tries to commit
git commit -m "style: update primary color"

# PixelBreak fires automatically
🔍 [PixelBreak] Running pre-commit checks...
🚀 Starting scan for project 'my-app'...
   Base URL: http://localhost:4173
   Profile:  responsive
   Widths:   [375, 768, 1024, 1280, 1440, 1920]px
   Git baseline: 1 staged file(s) detected — comparing against HEAD automatically.

📊 Scan Complete: 6 viewports, 8 findings

  🚨 BLOCKED [HIGH] horizontal-overflow @ 375px
     Element: #metrics-card overflows viewport by 857px

  🚨 BLOCKED [HIGH] horizontal-overflow @ 768px
     Element: #metrics-card overflows viewport by 464px

  🚨 BLOCKED [MODERATE] visual-regression @ 1024px
     0.09% pixel diff — 787 pixels changed

❌ Commit Gate: BLOCKED
   Dashboard: http://localhost:3847

Clone and try it yourself:

git clone https://github.com/praveen-pravi6B/pixelbreak
cd pixelbreak && pnpm install && pnpm build
pnpm demo
node apps/runner/dist/cli.js init
node apps/runner/dist/cli.js baseline update
# Change fixtures/broken-demo/src/style.css and commit

Code

How I Built It

Open-source AI: llama.cpp running Qwen2.5-Coder-Instruct (GGUF, Q4_K_M quantization) locally on port 8080. No API key, no cloud, no bundled weights.

The AI is the explanation layer — not the detection layer. Detection is fully deterministic:

Detection (no AI involved):

• @pixelbreak/layout-analyzer — injects JavaScript into Playwright pages to measure scrollWidth > clientWidth and element clipping geometry
• @pixelbreak/visual-diff — uses pixelmatch to compare screenshots pixel-by-pixel and generate diff PNGs

AI layer (llama.cpp + Qwen2.5-Coder):

• After deterministic detection blocks a commit, the AI receives: finding summary, measured pixel geometry, relevant computed CSS
• Returns structured JSON: summary, likely cause, supporting evidence, and a CSS patch proposal
• All responses are validated with a Zod schema — malformed output is rejected, never silently accepted
• The model cannot change severity, waive findings, or apply patches. severity: finding.severity is copied from the finding object, never from the AI response.

Git-aware automatic baselines:

The most important UX decision: instead of requiring pixelbreak baseline update before every scan, PixelBreak uses git show HEAD:<file> to automatically get the previous version of staged files as the baseline. You just commit — no manual setup.

Stack:

• pnpm workspaces monorepo (TypeScript, ESM throughout)
• Playwright for Chromium automation
• pixelmatch for pixel comparison
• Zod for all schema validation
• Commander.js for CLI
• React + Vite for the localhost dashboard
• Node.js built-in http for the dashboard server (no Express)

Why Does Open Innovation Matter?

I could have built this on Percy, Chromatic, or the Applitools API. But every hosted visual regression tool:

• Sends your screenshots to their servers — a non-starter for internal dashboards, confidential UIs, or enterprise apps
• Requires a subscription — free tiers run out, pricing changes, vendor disappears
• Locks you into their severity rules — you file a ticket if you disagree
• Breaks when you're offline or behind a corporate firewall

Open innovation made this possible in four concrete ways:

1. The AI runs on your hardware. Qwen2.5-Coder-Instruct via llama.cpp — download once, run forever, cost $0. No API key. No data leaving your machine. A team building a hospital admin panel can use PixelBreak without worrying about screenshots of patient data touching a third-party server.

2. You own the severity rules. The policy engine is a configurable YAML file. If your team disagrees with how a 0.08% pixel diff is classified, you change .pixelbreak.yml. No support ticket.

3. You can audit everything. When a security review found 9 vulnerabilities in my own code (command injection, path traversal, prototype pollution via YAML), I could read the exact lines, understand the attack vectors, fix them, and write tests that prove they're fixed. That's not possible with a black-box SaaS.

4. No lock-in by design. The AI adapter speaks the OpenAI-compatible /v1/chat/completions API. Swap llama.cpp for Ollama, LM Studio, or any future local inference server — zero code changes.

My Agent Session

Built with Claude Code across two sessions — foundation phases on a personal machine, AI engine + dashboard + security hardening in this session:

$ gh auth switch --user praveen-pravi6B

Switched active account to praveen-pravi6B

IMPLEMENTATION_STATUS.md

Phase A-D complete. Phase E (Local AI), F (Dashboard), G (Release Readiness) pending. 25 tests passing.

README.md — 11.5KB comprehensive guide

Created: product overview, CLI reference, severity policy, local AI setup, waiver system, privacy section

CONTRIBUTING.md, CONTRIBUTORS.md, THIRD_PARTY_NOTICES.md

All created with correct content

packages/ai-engine/src/types.ts

AiExplanation, PatchProposal, AiStatus types — isHypothesis always true

packages/ai-engine/src/prompts.ts

SYSTEM_PROMPT enforcing: cannot change severity, cannot waive, cannot auto-apply patches. buildExplanationPrompt() sends minimum evidence.

packages/ai-engine/src/validator.ts

Zod schema AiExplanationResponseSchema — rejects malformed JSON, missing fields, empty strings

packages/ai-engine/src/adapter.ts

LlamaCppAdapter: checkStatus() + explainFinding(). Uses execFileSync array args (no shell injection). AiUnavailableError and AiResponseError custom error types.

packages/ai-engine/test/ai-engine.test.ts

14 unit tests: valid response parsing, null patch, non-JSON rejection, schema validation, AiUnavailableError on ECONNREFUSED, severity immutability verified, empty choices array, HTTP 403/500

$ pnpm test

44/44 tests passing

apps/dashboard/src/components/ScanSummary.tsx

PASS/BLOCK banner, Blocked/Waived/Allowed counts, severity pips

apps/dashboard/src/components/FindingDetail.tsx

Baseline / Current / Diff screenshots side-by-side, evidence geometry, computed CSS

apps/dashboard/src/components/AiPanel.tsx

HYPOTHESIS NOT VERIFIED banner always shown. Summary, cause, evidence, limitations.

apps/dashboard/src/components/PatchReview.tsx

Diff syntax highlighting, copy-to-clipboard only — never writes to files

apps/dashboard/src/components/WaiverFlow.tsx

Generates .pixelbreak-waivers.yml YAML snippet — user copies manually, dashboard never writes files

$ pnpm build && pnpm test

All 10 packages built. 44/44 tests pass.

docs/local-model-setup.md

llama.cpp install, Qwen2.5-Coder GGUF download, server startup, hardware requirements, troubleshooting

docs/configuration.md

Full .pixelbreak.yml field reference

docs/severity-policy.md

Severity thresholds, commit gate logic, waiver rules, AI constraints table

docs/privacy.md

What stays local, what is never transmitted, local AI data flow

$ pnpm build && pnpm test

Test Files 10 passed. Tests 44 passed. Duration 20.96s

apps/runner/src/git-baseline.ts

CRITICAL: execSync string interpolation → execFileSync array args (command injection prevention). CRITICAL: per-file restoration guarantee in withHeadVersions. HIGH: skip symlinks + files >50MB.

apps/runner/src/dashboard-server.ts

CRITICAL: path traversal fix — resolve relative to outputDir not CWD. Reject symlinks in artifact serving.

apps/runner/src/cli.ts

HIGH: exec (shell) → execFile for openBrowser. Init command now auto-adds .pixelbreak/ to .gitignore.

packages/policy-engine/src/waivers.ts

HIGH: Zod .strict() schema rejects __proto__ and unknown keys (prototype pollution prevention)

packages/config/src/loader.ts

HIGH: --config path validated within project directory (path traversal prevention)

apps/runner/src/scanner.ts

HIGH: page.goto throws loudly on unreachable app. Empty widths guard. 5min timeout. Random scan ID suffix.

$ pnpm test

Test Files 14 passed. Tests 84 passed. 0 failed.

The Lazy Payoff

Before PixelBreak, a developer changing a CSS file would need to:

1. Open browser dev tools → resize to 375px → does it look right? (memory-based)
2. Resize to 768px → check again
3. Resize to 1024px → check again
4. Resize to 1280px, 1440px, 1920px → check, check, check
5. Compare visually against "what it looked like before" → impossible from memory

Time per CSS change: 5–10 minutes if done properly. Realistically: skipped 90% of the time.

With PixelBreak: 0 extra minutes. The commit either goes through or it doesn't.

During this week's build, PixelBreak caught:

• A min-width: 1200px on a flex container that caused 857px overflow at 375px — completely broken on mobile, would have shipped
• A color variable change creating 787 changed pixels at 1024px — would have passed code review unnoticed
• A table that overflowed at 375px when the metrics container was fixed — a bug introduced by fixing another bug, caught automatically

Community Wisdom: Visual regression testing for modern web apps by Rizwan Saleem — the hosted tool landscape that shaped the decision to go local-first.