browser-microscope

# Purpose Dissect a single frozen frame of a live web page to explain layout and interaction bugs that jsdom and screenshots cannot — a click that does not register, an element covered by an invisible overlay, wrong scroll/snap math, a token that resolves to the wrong value, or a defect that only appears at certain viewport widths. It drives the locally-installed Playwright package through one bundled script and returns JSON, so findings are exact numbers, not guesses. This is the introspection primitive; `browser` / `browser-qa` walk user journeys, this one inspects the DOM truth at a moment in time. ## Prerequisites - The `playwright` (or `playwright-core`) npm package must be resolvable from the target project — usually a devDep, so run commands from the project directory. Pass `--playwright <path>` to point elsewhere. The script exits with code 3 and a remediation hint if it cannot find it — it never hard-stops the way a global `playwright-cli` dependency would. ## Variables PROBE: ./scripts/probe.mjs # Bundled introspection engine (relative to skill root) VIEWPORT: 1200x900 # Default viewport WxH; cross a breakpoint by changing width WAIT_MS: 1000 # Settle delay after load before probing ## Workflow 1. **Run from the target project** - `cd` into the repo so the script resolves its `playwright` devDep, then call the bundled engine. Read `node <PROBE> --help` once if you need the full flag list. - IF: the page is behind staging basic-auth → add `--http-auth user:pass` (username may be blank: `--http-auth ":pass"`) and `--ignore-https-errors`. - Example: `cd ~/Documents/app && node <PROBE> eval --url https://stg.example.com --http-auth ":s3cret" --ignore-https-errors --js "document.title"` 2. **When a click does not register → `hit-test`** - The most common "button is broken" cause: another element covers it. `hit-test` does a real `elementFromPoint` at the element's center and reports whether the click lands on the target or what is on top. - IF: `lands: false` → the `covering` element (tag/class/outerHTML) is eating the click — inspect its `z-index`, `position`, or whether it is a stray overlay. - IF: `visible: false` (zero-size) → the control is `display:none` / collapsed, not covered — check container queries and parent layout instead. - Example: `node <PROBE> hit-test --url <url> --selector 'button[aria-label="Previous"]'` 3. **When geometry looks wrong → `box`** - Dumps `getBoundingClientRect` + `scrollLeft/scrollWidth/clientWidth/maxScrollLeft` + computed margins/padding/overflow/scroll-padding/transform for one element. - IF: `scroll.overflowsX` is true but `maxScrollLeft` is tiny → the rail barely overflows; index-based "next/prev" math can clamp short of a slide (a real class of carousel bug). - Example: `node <PROBE> box --url <url> --selector '#rail .viewport'` 4. **Find the REAL scroll container → `find-scroller`** - A `querySelector('[class*=viewport]')` can match a non-scrolling wrapper. `find-scroller` returns elements whose COMPUTED `overflowX` is `scroll`/`auto`, with their scroll metrics — use this to grab the actual scroller, then `box` it. - Example: `node <PROBE> find-scroller --url <url>` 5. **Read design tokens live → `tokens`** - Resolves CSS custom properties through `getComputedStyle`. Confirms a token (e.g. `--bleed-left`, `--theme-bg-default`) actually computes to what you expect. - IF: a specific token must be read → pass `--names '--a,--b'` (enumeration is best-effort; named reads are guaranteed). Default selector is `:root`. - Example: `node <PROBE> tokens --url <url> --selector '#card' --names '--bleed-left,--bleed-right'` 6. **When a bug only appears at some widths → `sweep`** - Loads at each `--widths` value and runs a per-width probe (`--selector` hit-test, or a custom `--js`), so you can see exactly what flips across a container-query / breakpoint threshold. - Example: `node <PROBE> sweep --url <url> --widths 600,768,1200 --js "(()=>{const vp=[...document.querySelectorAll('[class*=viewport]')].find(e=>getComputedStyle(e).overflowX==='scroll'); return vp?{max:vp.scrollWidth-vp.clientWidth}:'none';})()"` 7. **Run anything else → `eval`** - `--js '<expression>'` runs arbitrary JS in the page and returns its JSON result (multi-statement: wrap as an IIFE `"(()=>{...})()"`). This is the escape hatch for focus order, stacking context, computed values, ARIA state — anything. - Add `--console` to any command to capture page console errors alongside the result. - Example: `node <PROBE> eval --url <url> --js "getComputedStyle(document.activeElement).outlineWidth"` ## Gotchas - **Programmatic `.click()` lies.** `element.click()` and Playwright's `locator.click()` on a forced node bypass hit-testing, so a covered button can look like it "works" in script while a real user's pointer is blocked. Trust `hit-test` (`elementFromPoint`), not a synthetic click, to decide whether a click truly lands. - **The local Playwright package is CommonJS.** `import { chromium }` fails under ESM; the bundled script already handles this (default import then destructure) — keep that pattern if you hand-roll a one-off. - **Class-substring selectors are treacherous** with hashed CS-module names (`_viewport_ab12` vs `_viewportWrapper_cd34` both match `[class*=viewport]`, and `querySelector` returns the first in document order — often the wrong one). Prefer `find-scroller` to grab the element by COMPUTED `overflowX`. ## References ### Worked diagnoses and advanced recipes - IF: you want a full worked example (the Carousel "left button dead ≥692px" case), more `eval` snippets (focus order, stacking, container-query state), or screenshot capture for visual diffing - THEN: Read `./reference/recipes.md` - EXAMPLES: - "show me how this found the carousel bug" - "how do I check focus order / z-index stacking with this" - "capture a screenshot at a specific width" ## Works well with Optional collaborators — `browser-microscope` runs standalone and these degrade gracefully if absent. - **`browser`** — the journey-walking complement; use `browser` to navigate, `browser-microscope` to dissect why a click won't land or a layout breaks. - **`browser-review` / `browser-qa`** — reach for the microscope to diagnose the layout failures these surface. - **`ios-simulator-microscope`** — the real-device counterpart; escalate there when a bug only reproduces in real iOS Safari (toolbar collapse, dynamic-viewport units, touch dynamics) that desktop Playwright can't model.