iPad Screen Check: automated layout QA for touch web apps

---
name: screen-check
description: Build and run an automated screen check for touch web apps (iPad sizes, WebKit engine). Use before calling any UI change done, instead of eyeballing screenshots.
---

# Screen check: "a system, not more tokens"

An owner found a cut-off "Keep playing" button after an agent had already looked at screenshots. Their instruction: "I don't think the solution is always going to be throwing more tokens at it... build a better system so we can visualize the basics: the baseline." This skill is that system.

## What it is
One Node script (`scripts/screens.mjs`) plus one registry file per area (`scripts/screens/<area>.mjs`). The script opens every registered screen in **WebKit** (the iPad's engine) at real iPad viewports, screenshots it, runs layout checks **inside the page**, diffs against a saved baseline and writes one `report.html` (problems outlined in red, changed screens first) and a `report.json`. Most problems arrive as text, so screenshots only need a look when the report flags something.

## Registry format
```js
// scripts/screens/dig.mjs
export default [
  { name: "dig-menu", path: "/play/dig" },
  { name: "dig-leave", path: "/play/dig", steps: async (s) => { await s.tap("Dig Site"); await s.wait(2500); await s.back(); } },
  { name: "dig-rank-3", path: "/play/dig?rank=3", storage: { "dig.v2": "{...}" }, settle: 1500 },
];
```
Step helpers: `tap(label | {css} | {x,y} as 0-1 of the screen)`, `drag(from, to)`, `wait(ms)`, `waitFor(css)`, `back()`, `eval(fn, arg)`, `page` (raw Playwright page). `storage` is written to localStorage before load so deep states (rank 3, unlocked items) are one line, not a click path.

## Devices
```js
const DEVICES = {
  ipad11: { width: 1180, height: 820 },
  ipad13: { width: 1366, height: 1024 },
  mini:   { width: 1133, height: 744 },
  portrait: { width: 820, height: 1180 },
};
```
Use the `iPad Pro 11` user agent from Playwright's `devices`.

## Checks run in the page (page.evaluate over every button/label/img)
| code | meaning | severity |
|---|---|---|
| cut | element partly hidden by an ancestor with overflow hidden (compare getBoundingClientRect against each clipping ancestor) | fail |
| edge | element hangs off the viewport | fail |
| text | label's scrollWidth/scrollHeight exceeds its box | fail |
| image | `img.complete && naturalWidth === 0`, or background-image that failed | fail |
| console | page errors, console.error, 404 responses | fail |
| spill | a button's child sticks out of the button over a neighbour | warn |
| small | interactive element under 48 px (Apple minimum 44; toddlers need more) | warn |

Exit code 1 when any fail-level problem exists, so it can gate a CI job or an agent's "done".

## CLI
```
node scripts/screens.mjs                   # every area, iPad 11" landscape
node scripts/screens.mjs dig hatch         # only these registries
node scripts/screens.mjs --devices all     # ipad11, ipad13, mini, portrait
node scripts/screens.mjs --only leave      # screens whose name contains "leave"
node scripts/screens.mjs --baseline        # save this run as the baseline
node scripts/screens.mjs --engine chromium # Chromium instead of WebKit
```
Base URL from `PLAY_BASE` (default a local dev server). Output in `.qa/screens/<run>/`; baseline in `.qa/screens/baseline/<device>/<screen>.png`. Diff with `sharp` (pixel difference ratio; flag changes above ~0.5%).

## Rules for agents
1. Any UI change: run the check for the touched area with `--devices all` before reporting done. Paste the problem lines, not screenshots.
2. Add a registry entry for every new screen, dialog and state you build. A screen that isn't registered doesn't exist to QA.
3. Save a baseline only after a human looked at the report. Never `--baseline` to make red go away.
4. Subagents doing UI work get the same instructions and must add their screens.
5. Mute the browser (`--mute-audio` on Chromium; WebKit has no flag, so stub AudioContext or prefer Chromium for sound-heavy screens). Headless browsers play audio through the owner's speakers.
6. Keep QA output on a disk with room; screenshot runs across 4 devices fill small internal drives fast.

## Why WebKit
Safari/WKWebView differs from Chromium in flex gaps, `100dvh`, safe-area insets and audio autoplay. Checking in Chromium only hid real iPad bugs.