PixelBreak: Local-First Pre-Commit Tool That Blocks Bad Commits Before They Break Your Frontend

Description and use

PixelBreak blocks bad commits before they land in the repo by detecting responsive layout failures (horizontal overflow, element clipping) and visual regressions (pixel diffs) across 6 configured viewport widths, comparing against git HEAD baselines automatically, and opening a localhost dashboard with diff screenshots, AI root-cause explanation, and CSS patch suggestions — all local-first with zero cloud calls, zero telemetry, and zero API key required.

Problem

Frontend developers manually resize their browser at 5+ viewport widths after every CSS change to catch responsive layout failures and visual regressions, or pay for cloud-based visual regression subscriptions (Percy, Chromatic) that send screenshots to third-party servers, require accounts, lock into vendor severity rules, and break offline or behind corporate firewalls.

Outcome

PixelBreak blocks bad commits before they land in the repo by detecting responsive layout failures (horizontal overflow, element clipping) and visual regressions (pixel diffs) across 6 configured viewport widths, comparing against git HEAD baselines automatically, and opening a localhost dashboard with diff screenshots, AI root-cause explanation, and CSS patch suggestions — all local-first with zero cloud calls, zero telemetry, and zero API key required.

Workflow

• Developer changes a CSS variable and runs git commit -m "style: update primary color"
• PixelBreak fires automatically as a pre-commit hook
• PixelBreak scans the running app at configured viewport widths (375, 768, 1024, 1280, 1440, 1920 px) using Playwright + Chromium
• Layout analyzer injects JavaScript to measure scrollWidth > clientWidth and element clipping geometry
• Visual diff module compares screenshots pixel-by-pixel using pixelmatch and generates diff PNGs
• Git-aware automatic baselines use git show HEAD:<file> to get the previous version of staged files as baseline — no manual setup
• Policy engine evaluates findings; severity is copied from the finding object (severity: finding.severity), never from the AI response
• If high/critical regressions are found, the commit is BLOCKED
• AI layer receives finding summary, measured pixel geometry, and relevant computed CSS; returns structured JSON (summary, likely cause, supporting evidence, CSS patch proposal)
• All AI responses are validated with Zod schema; malformed output is rejected
• Dashboard at http://localhost:3847 shows Baseline / Current / Diff screenshots side by side, AI explanation, and copyable CSS patch

Evidence

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.

Source

Every time you git commit, PixelBreak: Scans your running app at every configured viewport width (375px → 1920px) using a real Chromium browser; Detects horizontal overflow and element clipping with deterministic pixel measurements; Compares screenshots against the previous committed version automatically — no manual baseline