see-ui

name	see-ui
description	Look at any web UI you build or change — render it headless with `botference see` and read the screenshots — because layout and design failures produce NO errors or warnings. Use after every UI change, before declaring done, and whenever a human says something "looks wrong".

see-ui — look at the page before you say it's done

Layout and design failures are invisible to your normal loop: the DOM is valid, the CSS applied, the console silent — and the page is still broken to a human eye (a chart squashed into 5% of its width renders "successfully"). Code and logs cannot catch "technically correct but looks wrong". Pixels can, and you can read pixels.

The command

botference see <target> [label] [--viewport WxH]... [--basic-auth U:P] [--out DIR]

• <target>: a URL, a bare :port (localhost), or the NAME of a running botference service — its listening port is discovered from the live process, you never need to know it.
• Default viewports: 390x844 (phone — real mobile layout, since responsive CSS answers to viewport width) and 1440x900 (desktop).
• It prints wrote: <path>.png lines. Read those images. That is the entire point — do not run the command and skip looking.
• Output defaults to .botference/shots/ (gitignored by convention).

Protocol

1. After ANY change that affects rendered UI, screenshot both default viewports and look at them before reporting the change as done.
2. When a human reports something "looks wrong/bad/off", screenshot FIRST, at the viewport they used (phone screenshots → 390x844), and compare with what they see. Do not reason about CSS from source alone.
3. If the app has a login form, your screenshot will show only the gate. Fix that properly: let bare-localhost requests through unauthenticated (the review engine's rule — anyone on the loopback port already owns the machine). --basic-auth helps only for HTTP basic auth, not form gates.
4. Charts and figures: vision discovers a failure class once — then lock it out forever with a deterministic test on the generated SVG/scales, no browser needed. Assert data coverage (observed data spans ≥ ~half the x-range; projections must not compress history), containment (points inside the plot area, y-domain spans the data, no NaN coordinates), and legibility (labels don't collide, sane tick counts, markers above minimum visible size). Every visual chart fix ships with the invariant test that would have failed on the bad render.

Notes

• Engine: headless system Chrome — no Playwright, nothing to install. A --virtual-time-budget is applied so client-drawn charts finish rendering before the shot.
• Sandboxes are handled — run the command yourself. Your sandbox cannot launch Chrome (seatbelt kills it); botference see detects that and hands the job to the see-broker service automatically, printing the same wrote: paths. Do not retry Chrome by hand and do not ask a human for pixels. If it reports "no see-broker service is alive", relay exactly this to the machine owner: botference service start see-broker -- botference see --serve
• Emulation caveat: it is Chrome at phone size, not iOS Safari. If a bug reproduces on a real iPhone but not in your render, say so — that is the one case that justifies installing Playwright (for its WebKit engine), a decision for the human, not you.
• botference service list shows what is running if you are unsure of a service name.