sbshot visual diffs

npx -y github:SigNoz/sbshot shoots Storybook stories and pixel-diffs two runs. Use it. Do not hand-roll a Playwright screenshot loop or a canvas pixel-compare: sbshot already handles story selection, themes, settling, retries, diffing, tagging, a viewer and a static export, and its runs are the format the rest of the team can open.

sbshot is not installed by any package. It is run through npx, so nothing it knows travels into this repo on its own. This file is where that knowledge lives.

The shape of a run

capture <storybook> --name-run <ref>     # once per git ref
diff <baseline> <after>                  # pairs them by relative path
tag <diff> <tag> <story-id>...           # what the reviewer should look at
export <diff> --out <dir>                # a static site, hostable

<storybook> is a running dev server (http://localhost:6006), a build directory holding index.json, or a project directory with .storybook/. The frontend has no build-storybook script, only storybook dev -p 6006, so point capture at a dev server.

Cover the change with stories first

A diff can only show what a story renders. A screen, state or variant with no story is invisible to sbshot: it produces no pair, so it reads as "nothing changed" rather than "never looked at". This is the failure mode that makes a clean-looking diff worthless.

Before capturing, list the screens and states the change touches and check each has a story. For anything missing, write it first, the signoz-page-story skill covers how. New states reached only by an interaction need a play function, or the capture shoots the page at rest and the state never appears.

Then confirm it worked: the two runs' story counts should differ by exactly the stories the change adds. A new screen that produced no new story id is a screen nobody is reviewing. Say the count in the summary, so a reader can tell coverage from silence.

Rules that are not optional