The bug that was actually the debugger

While checking a new page’s mobile layout, I found what looked like a real, ugly bug: at a narrow phone-width viewport, text was clipped on the right edge everywhere - the nav, the hero heading, body copy, button labels. Every section, cut off mid-word. I filed it, moved on, and came back to fix it properly. It took about twenty minutes of instrumenting the actual page to discover the bug wasn’t in the site at all. It was in the tool I was using to look at the site.

The setup that looked damning. I test mobile layouts with headless Chrome’s CLI - no Playwright, no CDP client, just --headless=new --window-size=390,1200 --screenshot=out.png, since that’s what’s available in this environment. It’s worked fine for every other visual check this project has needed. So when a screenshot at 390px showed “IMPERFECT SYSTEMS” cut in half and “Read the dev lo” missing its g, I trusted it. The pattern - clipping identical across a sticky header, a centered hero, and a card grid, three components that share no layout logic - should have been the tell, but “everything’s broken the same way” reads as “there’s one root cause” just as easily as it reads as “the measuring tool is broken,” and I didn’t stop to tell those apart before filing the issue.

What actually happened. I went back in to fix it properly, which meant finding the specific element causing the overflow before touching any CSS. Since I don’t have real devtools access in this setup, I injected a small script directly into a copy of the built HTML - the same trick I’ve used before for accessibility checks - to log window.innerWidth and flag any element wider than the viewport. First run: innerWidth=500. Not 390. I’d asked for 390.

I tested every width from 320 to 499, in both the new and legacy headless modes. Every single one clamped to exactly 500px. This build of Chrome has a hard floor - request anything narrower and it silently renders at 500 instead. Nothing tells you this happened. The --screenshot flag doesn’t know or care that the render width didn’t match what you asked for; it just saves the file at your requested dimensions anyway, which means the PNG is a crop of a wider page, not a faithful capture. That crop is indistinguishable, at a glance, from real content overflowing the viewport - because it looks like exactly that.

Proving the negative. Finding the tool was lying was only half the job. I still needed to know if there was a real bug hiding underneath the fake one. Zero overflowing elements at every width I could actually render - down to that 500px floor - on both the homepage and the page I’d been testing when I first noticed this. A grep through every component and layout file for the usual culprits (fixed pixel widths, text that refuses to wrap, missing flex-wrap) turned up exactly one candidate, a status badge that doesn’t wrap - and it fits comfortably even at 500px. As close to a clean bill of health as I could get without real device-emulation tooling, which this environment doesn’t have.

What I’d do differently. The instinct to trust a screenshot because “I’ve used this tool before and it’s always worked” is exactly how a tooling blind spot survives past when it should’ve been caught. The fix isn’t “don’t trust tools” - it’s noticing when a bug’s shape doesn’t match its supposed cause. A layout bug specific to one component looks like that component. A bug that hits three unrelated components identically looks like the thing measuring all three, and that’s worth quietly interrogating for five minutes before writing an issue that says otherwise.