Berth Visual Diff

Visual before/after

After a UI change, look before you say done. One command shoots your worktree's pages and the same pages of a base, at several widths, and says what moved:

berthd shots compare                                  # pages and sizes from .berth/config.json
berthd shots compare --pages / /search /login --sizes 375 768 1280
berthd shots compare --base turn-start                # against the start of your turn
berthd shots compare --color-scheme both              # light and dark

It prints a few lines (about 450 tokens for 6 pages × 3 sizes) and keeps the screenshots, the heatmap and the regions as a visual diff the user sees in their Berth app, beside your chat. You need a dev server running in your worktree ($BERTH_PORT, see berth-preview). The default base is the main checkout's dev server; when it isn't running, the compare uses your turn-start baseline instead and says so on a note: line, or, with no baseline either, tells you what to do.

The loop

1. Before you change anything, if main's dev server may not be running: berthd shots baseline (saves your pages as turn-start, ~5 s).
2. Make the change, start or keep your dev server.
3. Compare: berthd shots compare. About 5-7 s for 6 pages × 3 sizes.
4. Read the summary (below). For every changed page, ask: did I mean this?
5. Look where it matters. Each changed shot prints look: <name>.png, a before|after crop of its biggest region (the folder is on the look: line at the end), at most 800 px wide (about 500 tokens to read). Read one only when the numbers and the element name don't tell you enough.
6. Fix what you didn't mean, and compare again. Re-running updates the same visual diff as a new version; the user sees it change live. Don't start a new one (--new) unless the base changed.
7. Say what changed in your reply, in words: what you meant, what you fixed, what is left. The visual diff is the proof, not the report.

Never say a UI change is done while the summary shows an ERROR, a page that now scrolls sideways, or a changed page you can't explain.

Reading the summary

visual diff vd-8f4c600c v1: search-perf vs main, 6 pages × 3 sizes in 5.3s
2 of 6 pages changed · most: /search at 768 (48%) · 1 layout warning · 3 new shots · 3 errors
  /account       375,768,1280  ERROR: after: HTTP 500
  /deals         375,768,1280  NEW: 404 before
  /search          375  changed    30%  5 regions, largest 359x712 at 16,704 (section.wrap in main)
                      ⚠ now scrolls sideways: 125px wider than the screen
                      look: 86882c2594cf18d7.png
  /                375  changed   1.7%  1 region, largest 344x64 at 16,296 (form.hero-search in section.wrap.hero); height 1811 → 1823; 450px from y=1277 only moved +12px
  /login                unchanged at every size
look: before|after crops of each shot's largest change, in /…/diffs/vd-8f4c600c/img/

• ERROR: the page failed on your side (or the base's): fix it first. The page's own JavaScript error follows.
• NEW / GONE: a 404 on one side. Expected for a page you added or removed; a surprise otherwise. NEW: not in the baseline means the baseline didn't shoot that page or size.
• changed N%: the share of the page's pixels that changed. Small and in one region is usually a targeted change; large and in many regions at one size only is usually a layout break at that size.
• (form.hero-search in section.wrap.hero): the element the largest region is in (its tag, id or classes, a button's text), and the named element around it. around … means the region spans several elements.
• only moved +12px: content below a taller element moved down. That is not counted as change, but check why it got taller.
• ⚠ now scrolls sideways: the page is wider than the screen at that size and wasn't before: a row that doesn't wrap, a fixed width, a long word. Almost never intended.
• unchanged: identical pixel for pixel (masked areas aside).

Choosing pages and sizes

• Pages: the ones your change can reach, plus one you think it can't (a canary). A shared component or CSS: the main pages that use it. Keep it under ~10; every page × size costs about 0.7 s of shooting.
• Sizes: 375 768 1280 (phone, tablet, laptop) covers most breakpoints. Add the project's own breakpoints (read its CSS or Tailwind config) when a change is near one.
• --color-scheme both shoots every page in light and dark (twice the shots); dark only dark. Use it when you touch colours or theme tokens.
• Pages that need a login: the compare runs its own browser, without the agent browser's cookies, so give it public pages (or a dev-only page that renders the component), and tell the user which pages you couldn't compare.
• Put the defaults in .berth/config.json so every compare is the same:

{
  "shots": {
    "pages": ["/", "/search", "/login", "/account"],
    "sizes": [375, 768, 1280],
    "mask": ["time", "[data-testid=avatar]", ".relative-date"]
  }
}