Check layout relationships, not just pixel differences.
Bronto Layout is a framework-independent, local CLI and TypeScript library for responsive layout verification. Inspect a site without writing a test, then explicitly preserve the alignments, spacing and containment rules that matter to your design. Reports work in terminals, CI and coding-agent workflows.
Status: MIT-licensed, experimental v0.5.0-beta.2, on npm as @ponchia/layout under the beta dist-tag. Chrome/Chromium and Node.js 22+ are needed for browser checks. Auto-detection prefers installed stable Chrome on Linux; use --chrome PATH or CHROME_PATH to override. The CLI ships no browser or third-party runtime dependencies and needs no account or hosted service.
Install it into a project:
npm install --save-dev @ponchia/layout@beta
npx bronto-layout doctor --verify-launchCurrent beta qualification uses in-house checks, not outside developer recruitment. Later betas publish from the protected release workflow with npm provenance; 0.5.0-beta.2, the first registry version, was bootstrapped by the maintainer and has none.
The published npm beta includes both the approved layout contract and its
self-contained HTML fixtures. You can reproduce the example from the project
where you installed @ponchia/layout@beta without cloning this repository,
running a build or installing browser automation dependencies.
This example intentionally moves a portfolio image 18px below the first paragraph at desktop widths. Both pages can look healthy to a zero-contract audit; only an approved alignment contract identifies the regression.
# In the project where you ran npm install --save-dev @ponchia/layout@beta:
npx --no-install bronto-layout doctor --verify-launch
# Check the published contract itself, without launching a browser.
npx --no-install bronto-layout validate \
--spec node_modules/@ponchia/layout/examples/portfolio-alignment.json
# Healthy portfolio layout: exit 0.
npx --no-install bronto-layout check \
--spec node_modules/@ponchia/layout/examples/portfolio-alignment.json \
--url node_modules/@ponchia/layout/examples/portfolio-alignment-healthy.html
# Same contract, intentionally broken layout: expected exit 1.
npx --no-install bronto-layout check \
--spec node_modules/@ponchia/layout/examples/portfolio-alignment.json \
--url node_modules/@ponchia/layout/examples/portfolio-alignment-broken.htmlThe verified npm beta includes all three files. The contract checks 375, 768
and 1280 CSS-pixel viewports; mobile deliberately stacks its content.
doctor --verify-launch first checks whether installed Chrome/Chromium can
start with normal sandbox settings. If it fails, address the local browser
environment rather than bypassing sandboxing for arbitrary websites.
See the complete walkthrough
and contributor setup for source-built development.
Real CLI screenshot, cropped from the self-contained intentionally broken 768px fixture—not a production-site finding or an accuracy claim.
# No contract: measured overflow and visible broken images; other leads need review.
npx --no-install bronto-layout audit --url http://localhost:5173 \
--widths 320,375,768,1280 --json --compact
# Create a versioned contract skeleton, then edit selectors and rules.
npx --no-install bronto-layout init --url http://localhost:5173 \
--out bronto-layout.json
npx --no-install bronto-layout validate --spec bronto-layout.json
npx --no-install bronto-layout check --spec bronto-layout.json --json
# Optional: suggest relationships and approve only the ones you intend to keep.
npx --no-install bronto-layout suggest --url http://localhost:5173 \
--widths 375,768,1280 --out proposals.jsonExit codes: 0 = observed checks passed, 1 = measured violation/regression, 2 = invalid input, runtime failure or unverified evidence. A successful check does not prove the entire visual design is correct. A zero-contract audit cannot infer design intent.
The tool does not repair CSS automatically. The suggestion workflow produces reviewable drafts; it does not turn observed relationships into blocking assertions without your explicit approval.
The optional host geometry adapter evaluates explicit alignment, spacing, containment and size intent against a complete, typed world/screen/SVG rectangle snapshot supplied by the owning application. Measurements are associated with stable host identities and a source revision. Mixed coordinate spaces, incomplete inventories and browser-only rules fail closed. Unavailable measurements produce unverified results, not false passes. The library never moves nodes or inspects canvas paint.
The optional SVG geometry capture adapter turns stable renderer-owned SVG/foreignObject elements into one bounded user-coordinate snapshot, including explicit unavailable results. It measures geometric boxes and HTML border rectangles; it does not certify glyph ink or clipped paint.
The beta integration guide shows npm and checksum-verified GitHub-release installs, a source checkout, a reusable commit-pinned GitHub Action, a strict CI contract check, and a sample AGENTS.md instruction. No npm package, analytics service or hosted dashboard is required for the Action. The Action stores JSON locally and does not upload private evidence automatically. An external workflow must pin a reviewed commit SHA and bring its own running site.
Responsive checks can opt into --interior-probes 3 --refine to sample failures between passing endpoints; the report documents sampled and untested widths. This improves coverage without asserting correctness at widths that were never visited. A reusable batch manifest can also opt into interiorProbes, refine and failOnSkip per approved contract job.
A screenshot comparison can tell you that pixels changed; it cannot tell you whether a particular relationship must stay fixed. Bronto Layout supports 14 constraint kinds, including edge alignment, containment, centering, equal/uniform gaps, element counts, non-overlap, dimensions, image proportion, clipping and observed layout stability. Rules can be scoped to viewport ranges and explicit UI states.
You can:
- Run conservative zero-contract audits and review potential layout leads separately from confirmed measurements.
- Compare baseline and candidate revisions using stable contract rules, JSON/SARIF reports and optional visual evidence.
- Test multiple widths, breakpoints and routes, including RTL, open Shadow DOM and declared interactions.
- Use optional real browser pointer-click checks when a DOM event alone would falsely “open” an obscured or offscreen control; separate mouse hit testing from keyboard/touch usability.
- Inspect element geometry and matched CSS without fabricating a source-level root cause.
- Use the pure TypeScript evaluation engine with host-provided geometry, without Chromium or a framework dependency.
Limitations: Browser execution currently supports Chromium-family browsers only. Closed shadow roots, cross-origin frame interiors, canvas/WebGL paint and unobserved application states are not verified. CSS-visible canvases are reported as known uninspected paint surfaces rather than clean rendered content. Heuristic text clipping/overlap/spacing findings are review warnings rather than automatic proof of a design error. Please don't use a sandbox override to visit untrusted websites.
- Automated CI runs on Node 22/24 with Chromium, package-install smoke checks, a portable-core coverage threshold and maintained macOS hosted-runner checks.
- Controlled fixture benchmarks provide reproducible regression protection; they are not an estimate of real-world precision/recall.
- The original 30-state and expanded 42-state v0.2 cohort have been captured. The expanded smoke caught a genuine 320px BrontoUI overflow, later fixed and verified on the deployed site. Independent field-review labels and accuracy estimates remain pending.
- Betas are on npm as
@ponchia/layout@beta, and each GitHub prerelease attaches the same checksum-verified.tgz; no general-availability or real-world accuracy claim. See the release checklist and field benchmark protocol.
Use the documentation index for current guides and historical evidence.
| Start here | Details |
|---|---|
| 10-minute first-run guide | Audit, suggest, approve, state replay and batch |
| Beta integrations and agent recipe | Local/source installation, pinned GitHub Action, CI coverage and agent policies |
| Existing Playwright test adapter | Reuse Playwright Page state, capture DOM geometry, evaluate approved contracts without launching another browser |
| npm beta bootstrap and protected OIDC | Authenticated first release, then provenance-attested, manually approved GitHub tag publishing |
| First-party beta trial worksheet | Record controlled pilot evidence without publicly exposing user data |
| First-party beta pilot findings | Measured project integrations, controlled failures, security limits and remaining evidence gaps |
| Weekly owned-site layout pulse | Six fixed public routes, sandboxed Chromium, sampled-width and coverage summary without uploading browser evidence |
| Independent first-use trial | Short, privacy-conscious feedback exercise for new developers |
| Portfolio regression case study | A known, deliberately introduced defect with healthy/broken pages |
| Real downstream CI: BrontoUI | A pinned consumer workflow with passing contracts and a caught regression |
| CLI reference | Extended commands, scenarios, screenshots and examples |
| Architecture | Core, browser adapters, CDP process lifecycle, evidence and coverage |
| Contract discovery | Why suggestions require human approval |
| Benchmarks and field validation | Controlled fixtures versus independently labeled sites |
| External open-source website study | Separate OSS cohort, limitations and independent-review protocol |
| External mobile-navigation states | Fixed anonymous menu-opening experiments, post-click assertions and screenshots |
| External below-the-fold states | Fixed Vite/Docusaurus section targets, actual scroll offsets and bounded screenshot evidence |
| Pinned source-built Eleventy study | Independent project build, responsive contracts, controlled semantic fault |
| Historical Svelte flex regression | Source-inspired switch occlusion caught by existing vertical containment contracts |
| Contributing and security | Local tests, reporting issues and safety |
See CONTRIBUTING.md. Bug reports that include a minimal reproduction, CSS width and expected layout relationship are especially valuable. The repo is MIT-licensed; no telemetry, SaaS account or hosted dashboard is required.
If the tool saves you time, you can support its maintenance on Ko-fi. Donations are optional; no functionality, accounts or updates are gated by payment.