# Put both versions on one image

People claim two versions of a page look the same without ever seeing them next to each other. Then a
vague reassurance ships something broken. This pass ends that. The page being matched on the left, the
page being built on the right, on a single image. **That combined image is what gets reviewed.**

Finding the differences is not this pass. This pass builds the thing the differences are found in.

Commands assume a folder named `beargrassai` on the machine running them.

---

## The two words

**REFERENCE** — the version the page must match. Usually the live site, but not always: sometimes a
static export of an old shop, sometimes a client's existing site on another platform, sometimes a dated
copy published to a separate address for review. Whatever the work names, that is the reference.

**CANDIDATE** — the version being built. It is not accepted until someone has compared it and said so.

---

## What you are doing here

Building the board somebody else will read. You are not the reviewer yet.

Done means: every page in scope has a combined image, there is a gallery to scroll, and there is a list
saying how many pairs were made and how many pictures failed to find a partner.

---

## The rule this pass exists to enforce

**Before anyone claims two versions match, a combined image must exist for every page in scope.**

Folders of single-side pictures are not the review surface. Counting elements in the markup is not a
substitute. Building the image is not itself the verdict — someone still has to read it.

---

## What this produces

1. Two sets of pictures, one per side, same pages, same screen size. Start with desktop.
2. **A gallery** — `sidebyside-gallery.html`, for a person to scroll, reference on the left.
3. **The combined images** — `pair-shots/sidebyside__<page>.png`. One file per page, both sides in it.
   These are what get reviewed.
4. **A list** — `sidebyside-manifest.json`: which pages paired, which did not, which folders went in.

The single-side files stay where they are as inputs. **They are not the deliverable.**

---

## Do it

Two page-sets. **Identical addresses, and identical names for the screen sizes.** The tool pairs pictures
by filename and the filename starts with the screen-size name, so one set saying `laptop-1280` and the
other saying `desktop` produces zero pairs while every command still looks like it worked.

The candidate must be a **pinned** version — a local server running one specific build, or a fixed
address for one specific deployment. Record which build you used. What is refused is a moving address
that may have changed under you between the two captures.

A reference built as folders carries a trailing slash — `/about/`. A candidate may serve `/about`. The
tool normalises both to the same key, so they still pair.

```
node agent-tools/picviewer/capture.mjs --project <name>-reference --only desktop
node agent-tools/picviewer/capture.mjs --project <name>-candidate --only desktop
```

Use the sign-in-wall wrapper for either side that needs it. Picture count must equal page count on both
sides. Write down both output folders.

Then combine:

```
node agent-tools/picviewer/sidebyside.mjs \
  --live  agent-tools/picviewer/out/<timestamp>/<reference-project> \
  --clone agent-tools/picviewer/out/<timestamp>/<candidate-project> \
  --out   Clients/<folder>/<date>/sidebyside-<label> \
  --viewport desktop \
  --strict \
  --expect-pairs <number of pages>
```

**`--live` and `--clone` are the tool's own flag names and do not mean what they say here.** Pass the
reference to `--live` and the candidate to `--clone`. Do not go hunting for a live address because a flag
is called `--live`. They are left as they are because renaming a flag would break every command written
down elsewhere.

Exit codes: `0` fine · `1` bad usage or a crash · `2` nothing paired · `3` unpaired pictures under
`--strict` · `4` fewer combined images than pairs · `5` fewer pairs than you said to expect.

`--html-only` makes the gallery without the combined images. That is an emergency escape for a person in
a hurry. It does not satisfy this pass.

The gallery's own header must stay in the normal flow of the page. Pinned to the top, it paints across
the middle of a tall combined image and ruins it.

---

## What good looks like

- One combined image per page, both sides visible, reference left
- A gallery that scrolls through all of them
- Zero unpaired pictures
- A list that says how many pairs, matching the number of pages you expected
- All of it in the client's dated folder, not buried in the tool's output tree

## Definition of done

1. Both sides captured, same pages, same screen-size names, counts matching.
2. `sidebyside-gallery.html` exists.
3. `pair-shots/sidebyside__*.png` exists for every paired page.
4. `sidebyside-manifest.json` exists and reports zero unpaired.
5. The tool exited 0, and the number of combined images equals the number of pairs.
6. The number of pairs equals the number of pages you set out to compare.
7. The build the candidate was served from is written down.

Then hand it to whoever is reading it. **Do not write a verdict from this file.**

## Refuse these

- Reviewing from single-side folders
- Treating page height as the finding
- Skipping the combined images
- Claiming two versions match because the images were built
- Pointing the candidate at a moving address instead of one pinned build
- Two page-sets whose screen-size names differ, which silently pairs nothing
- Pinning the gallery header to the top of the window