I built WIDTHSCAN to find the exact viewport widths where websites break

PowerBuilderr — Wed, 12 Aug 2026 09:21:16 +0000

Responsive bugs do not always appear at standard device presets.

A page may look correct at 375px and 768px while breaking somewhere between them. Finding that exact transition manually can mean resizing DevTools one pixel at a time, inspecting the document width, and trying to identify which element escaped the viewport.

I built WIDTHSCAN to automate that investigation.

Have a public frontend project? Leave its URL in the comments. I’ll personally scan the first five sites and send each owner the result — no installation required. If the report is useful, I’ll then ask you to run WIDTHSCAN once yourself and tell me how the experience went.

What WIDTHSCAN does

WIDTHSCAN is an open-source, local-first responsive QA CLI.

It scans a local or deployed website across a configurable viewport-width range, observes responsive failures, and narrows the detected transitions to exact inclusive ranges.

The initial v0.1.0 release focuses on two detector types:

HORIZONTAL_OVERFLOW — reachable document-level horizontal overflow;
CLIPPED_TEXT — visible, meaningful text clipped by its own container.

Each scan creates:

a standalone HTML report;
machine-readable JSON results;
annotated screenshots;
likely offending elements;
a copyable fix prompt for a developer or coding agent.

The report works directly from the local filesystem. WIDTHSCAN does not require an account, cloud service, telemetry, or an external API.

Why exact ranges matter

A report such as 412–427px means the failure was observed at every refined width from 412px through 427px.

That is more actionable than saying that a page “has a mobile issue.” It provides concrete boundaries to reproduce before a fix and verify afterward.

WIDTHSCAN also distinguishes scan-bounded ranges. For example, ≤320–338px means that the issue was already present at the configured minimum of 320px, so the true lower boundary remains unknown.

Initial field testing

I tested WIDTHSCAN on five small public portfolio sites and manually reviewed the findings in Chromium.

The results included:

three confirmed horizontal-overflow defects;
one clean scan;
one intentionally moving element that could be excluded with --ignore.

Intentional overflow is important. Marquees, decorative animation fields, and reveal effects may deliberately place content outside a component.

WIDTHSCAN therefore supports repeatable CSS-selector exclusions:

npx widthscan https://example.com --ignore ".logo-marquee__track"

An element should only be ignored after manually confirming that its behavior is intentional and is not causing a real page-level failure.

I also scanned Arizo Studio with permission from its owner. WIDTHSCAN checked 101 viewport widths from 320px through 1920px, and neither detector produced a finding.

A clean scan is evidence that the available detectors did not find a failure. It is not proof that the website is completely responsive, accessible, or standards-compliant.

Try it on your project

Requirements:

Node.js 20 or newer;
npm;
Playwright Chromium.

Install the browser dependency:

npx playwright install chromium

Run WIDTHSCAN without a global installation:

npx widthscan@0.1.0 "https://example.com" --min 320 --max 1920 --height 900 --out widthscan-report

On Windows PowerShell, open the report with:

Start-Process .\widthscan-report\index.html

On macOS:

open ./widthscan-report/index.html

On Linux:

xdg-open ./widthscan-report/index.html

The same command can scan a local development server:

npx widthscan@0.1.0 "http://localhost:5173"

I’m looking for five early testers

I would like five frontend developers to run WIDTHSCAN on one real project.

The test should take approximately 5–10 minutes. I am especially interested in these questions:

Did installation work on the first attempt?
Was the detected behavior a real defect, intentional behavior, or a false positive?
Was the HTML report understandable?
What was the most confusing or inconvenient part?
Would you use WIDTHSCAN again before releasing a frontend project?

Short answers are welcome.

Repository:

https://github.com/PowerBuilderr/WIDTHSCAN

Feedback Issue:

https://github.com/PowerBuilderr/WIDTHSCAN/issues/1