## Architecture

Two cooperating helpers share one threshold, one viewport, and one font/animation discipline so the e2e and Storybook baselines stay comparable.

### Adapter choice

- **e2e path:** Playwright's built-in `expect(page).toHaveScreenshot()` — already in the dependency closure, supports per-OS baselines natively, threshold semantics (`maxDiffPixelRatio`, `maxDiffPixels`) are well documented. No `pixelmatch` direct dep needed.
- **Storybook path:** `@storybook/test-runner` is the canonical Storybook→Playwright bridge. It exposes `preVisit` / `postVisit` hooks where we capture screenshots using the same Playwright `Page` instance, so the comparator and threshold match the e2e path bit-for-bit.

A pure-Node `pixelmatch` helper was rejected: it would fork the comparator, drift in floating-point handling between OSes, and double the surface to maintain.

### Default thresholds

- `maxDiffPixelRatio: 0.005` (0.5%). Tighter ratios (e.g. 0.001) produce noise from sub-pixel font rendering on different GPU drivers.
- `animations: 'disabled'`, `caret: 'hide'`, `scale: 'css'`.
- Viewport: 1280×720 default. Stories pin to the same default unless the story sets an explicit `parameters.viewport`.
- `prefers-reduced-motion: reduce` forced via `page.emulateMedia`.

### OS matrix

Baselines are stored per platform: `__snapshots__/<linux|darwin|win32>/...`. CI MUST run at least the platforms it intends to gate on. A platform with no baseline directory MUST skip the comparison (no implicit pass) and emit a warning.

### Baseline-update workflow

1. Developer runs `bunx turbo test --filter=<pkg> -- --update-snapshots` locally.
2. Diff is committed in a **separate, review-tagged commit** prefixed `chore(visual): refresh baselines — <reason>`. Squashing into feature commits is forbidden.
3. PR reviewer compares before/after PNGs in the diff view; CI re-runs the comparator on the new baselines to catch accidental cross-platform drift.

### Determinism levers

- Fonts: `await document.fonts.ready` after `networkidle`. Web fonts that load lazily are the #1 source of flake.
- Color scheme: stories with `parameters.colorScheme === 'dark'` toggle via `page.emulateMedia({ colorScheme: 'dark' })` before capture.
- Time: any time-display surfaces under test must already accept an injected `Clock` per `openspec/project.md`; visual specs SHALL pass a `FakeClock` set to a fixed instant.

### Error model

`VisualRegressionError extends TestingE2eError` for the e2e path, `StorybookVisualError extends TestingDomError` for the Storybook path. Each carries `{ code, cause?, context: { baselinePath, actualPath, diffPath, pixelRatio } }`.

### Cross-links

- Release-readiness gate: `../enterprise-testbed-verification/proposal.md`.
- Audit driver: `/mnt/s/web/genesis/docs/superpowers/specs/2026-04-25-test-suite-audit.md` §2 row 2.
- Project rules: `/mnt/s/web/genesis/CLAUDE.md` "Web App & Page Verification".