compare-screenshots

Files (36)

• SKILL.md
• reference-landmarks.md · references/
• subagent-visual-review.md · references/
• visual-parity-diff.eval.mjs · scripts/
• visual-parity-diff.mjs · scripts/
• README.md · test/fixtures/target-without-helper-packages/
• fixture.png · test/fixtures/target-without-helper-packages/candidate/
• fixture.png · test/fixtures/target-without-helper-packages/reference/
• visual-parity-diff.test.mjs · test/
• LICENSE · vendor/pixelmatch/
• index.js · vendor/pixelmatch/
• package.json · vendor/pixelmatch/
• LICENSE · vendor/pngjs/
• bitmapper.js · vendor/pngjs/lib/
• bitpacker.js · vendor/pngjs/lib/
• chunkstream.js · vendor/pngjs/lib/
• constants.js · vendor/pngjs/lib/
• crc.js · vendor/pngjs/lib/
• filter-pack.js · vendor/pngjs/lib/
• filter-parse-async.js · vendor/pngjs/lib/
• filter-parse-sync.js · vendor/pngjs/lib/
• filter-parse.js · vendor/pngjs/lib/
• format-normaliser.js · vendor/pngjs/lib/
• interlace.js · vendor/pngjs/lib/
• packer-async.js · vendor/pngjs/lib/
• packer-sync.js · vendor/pngjs/lib/
• packer.js · vendor/pngjs/lib/
• paeth-predictor.js · vendor/pngjs/lib/
• parser-async.js · vendor/pngjs/lib/
• parser-sync.js · vendor/pngjs/lib/
• parser.js · vendor/pngjs/lib/
• png-sync.js · vendor/pngjs/lib/
• png.js · vendor/pngjs/lib/
• sync-inflate.js · vendor/pngjs/lib/
• sync-reader.js · vendor/pngjs/lib/
• package.json · vendor/pngjs/

SKILL.md (first lines)

# Compare Screenshots

Judge images against the intended result. A user-approved design is the target;
a historical baseline is only an earlier attempt and may be wrong. Metrics locate
differences, never decide correctness. Use
[design-with-images](../design-with-images/SKILL.md) for the full exploration-to-implementation loop.

## Workflow

1. **Establish the target.** Use the user-approved reference and stated design
   requirements when available; do not replace them with your own taste. Otherwise
   derive the target from the visual requirement, what the thing depicts in reality
   and the domain skill that owns the look. Write it down in one or two
   concrete sentences ("low sun should cast long shadows east; trees fill the
   canopy; labels stay legible at this zoom").
   - If the right answer isn't clear — competing valid readings, a taste or
     product-intent call, a tradeoff only the owner can settle — **stop and ask
     the user** what the correct answer should be. Show them the comparison.
     Do not quietly default to the baseline to avoid asking; that bakes in
     whatever the baseline got wrong.
2. **Confirm comparability** so the differences you see are real, not capture
   artifacts: same viewport, DPR, route/page, frozen time/tick, camera intent,
   UI state, data, fonts/assets where they matter. If not comparable, fix
   capture setup or compare only a crop/feature where the mismatch is harmless.
3. **Measure the approved design.** For reference matching, read and complete
   [Reference Landmarks](references/reference-landmarks.md) before changing code
   or accepting a candidate. Then generate artifacts sized to the question:
   side-by-side, key-feature crops/zooms, grayscale, absolute grayscale heatmap,
   pixelmatch diff, per-image Sobel/edge maps, edge-difference heatmap, JSON
   metrics.
4. **Inspect boundaries before judging the whole.** For every changed visual
   effect, inspect all sides at native scale and in matched detail crops. Include
   the effect's full fade and surrounding space; a crop ending at the component
   box hides spill. Compare top/right/bottom/left extents separately, anchored to
   visible text, rules or silhouettes rather than inferred CSS bounds. Check
   every foreground feature crossed by the effect (lines, icons, text, adjacent
   panels): brightness, color, sharpness and continuity must match the target.
   A readable line can still be incorrectly dimmed. Record each check as
   reference observation → candidate observation → pass/fix/uncertain, with its
   crop. Use the landmark table to resolve local distances and contrast;
   full-frame averages cannot settle a local defect.
5. **Judge each divergence against the target.** For every place the two images
   differ, name what is actually there in plain terms — missing content, wrong
   camera, bad hierarchy, weak contrast, wrong depth, text overlap, layout
   shift, clipped edge, unexpected blur, style mismatch — and decide which side
   is closer to correct. The answer can be the candidate, the baseline, both
   wrong, or a genuine toss-up.
6. **Get a neutral second opinion** for disputed or high-stakes calls: a fresh
   subagent given only the two images and neutral labels, per
   `references/subagent-visual-review.md`.
7. **Resolve mismatches to an approved target.** When implementing a selected
   design, record material differences in spacing, shape, softness, typography
   and hierarchy; revise, recapture and repeat until resolved or the user changes
   the target. Do not silently exempt a difference because the code is simpler.
8. **Conclude with one verdict:** candidate is less wrong (accept, and re-bless
   the baseline if one exists), baseline is less wrong (reject), both wrong
   (another pass needed — say what's still off), or unclear (ask the user).
   Accept only when every boundary/overlap check passes or has an explicit
   user-approved deviation; uncertainty requires closer evidence, not a pass.
   Overall resemblance or a positive second opinion cannot cancel a local defect.
   Never accept on a lower score alone or reject on a higher one. Never hide
   content, blur detail, crop away differences, or make the capture less
   truthful to move a number.

## Useful Metrics

Pick metrics that answer the question. For full visual comparisons, report:

- `mae`: mean absolute grayscale difference, 0..255, lower is closer.
- `rmse`: grayscale root mean square error, lower is closer.
- `diffRatio16`, `diffRatio32`, `diffRatio64`: fraction of pixels over each
  grayscale delta threshold.
- `pixelmatchRatio`: mismatch ratio from pixelmatch over grayscale images.
- `edgeEnergyCurrent` and `edgeEnergyCandidate`: average Sobel edge strength.
- `edgeEnergyRatio`: candidate/current. Far below 1 usually means missing
  geometry, props, labels, or terrain; far above 1 usually means noisy or
  incorrect detail.
- `edgeDiffRatio32`: fraction of pixels whose Sobel edge differs materially.
- `avgLuminanceCurrent`, `avgLuminanceCandidate`, `avgLuminanceDelta`: average
  brightness and delta. Use when a render is visibly too dark/light even if a
  broader distance score improves.
- Content proxies relevant to the scene: black/void ratio, terrain-like ratio,
  water-like ratio, team-color ratio, label/text mask ratio.

For UI/document/layout reviews, also use crop bounds, text/foreground mask
coverage, contrast checks, edge clipping, element positions, and before/after
dimensions when those beat global pixel distance.

## Single-Image Metrics

Every metric above measures one image against another, so none of them can
answer "is this capture worth anything" when there is nothing to compare it to
— and the pair score is symmetric, so an enormous distance never says *which*
side is the empty frame. A few absolute numbers do, computed on a coarse grid
from a single PNG:

- `colorEntropyBits` under ~3.0, or `dominantColorShare` over ~0.6: one colour
  owns the frame. A sparse scene, an unlit one, or a subject that never drew.
- `edgeDensity` under ~0.04: almost no form anywhere. Empty framing, a
  primitive-dominant scene, or the subject sitting outside the crop.
- `luminanceContrast` under ~60: fog, darkness, or haze compressing the whole
  frame into one band.
- `transparentShare` above 0 on a capture that should be opaque: the capture
  itself is wrong. A transparent pixel keeps whatever RGB it was left with, so
  an invisible frame can look rich until it is composited — the scene metrics
  composite before measuring, and name the invisible share rather than letting
  you infer it. The pair metrics above still read stored RGB, so this field is
  where transparency gets told either way.

These are thresholds for *suspicion*, not gates. A deliberately minimal design,
a night scene, an empty-state screen, and a whiteboard all trip them honestly.
Use them to decide where to look, then say what the frame is actually doing —
never adjust a capture to raise a number, which is the same failure as cropping
away a difference.

## Distance Score

When a single fixed-pair number is useful, this default works for structural
changes:

From transitive-bullshit/skills, MIT.

More from transitive-bullshit/skills