IMPRINT
The picture of a change, pinned to the pull request.

Imprint lays out before-and-after screenshots of a UI change as one PNG, serves
it at a stable public URL, and gives you the markdown to paste into an issue or
pull request. When the change moves on, publish again with the same key. The
picture updates everywhere it was pasted; GitHub shows the new one within about
a minute.

The image URL is public: anyone who has it can see the picture. Do not publish
screenshots that show secrets or personal data.

WHEN TO USE IT
When a change alters how something looks or behaves on screen, and a reviewer
would otherwise have to run the app to see it. A single control in a single
state is fine as a plain screenshot. Imprint helps when several controls or
states need lining up, and when the picture has to follow later commits.


1. TAKE THE SCREENSHOTS

- Run the app at the base commit and at the head commit.
- For each control the change touches, capture the same control in the same
  state on both sides: idle, hover, focus, pressed, or a viewport size.
- Crop to the control with a little context around it, and use the same crop
  on both sides, so a change in size shows.
- Capture at device scale factor 2. If you used 1 or 3, set "pixel_ratio".
- PNG, JPEG, or WebP; up to 8 MB and 4000 px per side each;
  up to 24 files per request.


2. PUBLISH

Write the fields to a file, fields.json:

  {"title": "Buttons fold on hover",
   "base": {"sha": "b3fca10", "label": "main"},
   "head": {"sha": "04e3d89", "label": "feat/buttons"},
   "rows": [{"label": "Hero CTA: hover",
             "before": "hero-before.png", "after": "hero-after.png"}]}

Then send it with the screenshots:

curl -sS https://imprint.stacking.me/v1/imprints \
  -H "Authorization: Bearer $IMPRINT_KEY" \
  -F key='OWNER/REPO#123/buttons' \
  -F preset=before-after \
  -F fields=<fields.json \
  -F files=@hero-before.png \
  -F files=@hero-after.png \
  -F pinned_to=https://github.com/OWNER/REPO/pull/123

Send fields as a file (-F fields=<fields.json) or with --form-string. Written
inline after -F, curl cuts the value at the first ';'.

key        You choose it, up to 200 characters. The same key later updates the
           same picture. OWNER/REPO#NUMBER/topic works well.
preset     before-after
fields     JSON, described below. An image field names an uploaded file by its
           filename: the name after @, without the folder.
files      Repeat once per screenshot. Every file must be used by a field.
pinned_to  Optional and repeatable: the issue or pull request URLs where you
           paste the image. Imprint records them.


3. PASTE THE MARKDOWN

The response is JSON:

  {
    "id": "q7Xc2mR9vLwT4nKpZb8sYe",
    "key": "OWNER/REPO#123/buttons",
    "revision": 1,
    "unchanged": false,
    "image_url": "https://imprint.stacking.me/i/q7Xc2mR9vLwT4nKpZb8sYe.png",
    "variant_urls": {"light": "https://imprint.stacking.me/i/q7Xc2mR9vLwT4nKpZb8sYe.light.png",
                     "dark": "https://imprint.stacking.me/i/q7Xc2mR9vLwT4nKpZb8sYe.dark.png",
                     "narrow.light": "https://imprint.stacking.me/i/q7Xc2mR9vLwT4nKpZb8sYe.narrow.light.png",
                     "narrow.dark": "https://imprint.stacking.me/i/q7Xc2mR9vLwT4nKpZb8sYe.narrow.dark.png"},
    "revision_url": "https://imprint.stacking.me/i/q7Xc2mR9vLwT4nKpZb8sYe/1.png",
    "markdown": "<picture>...</picture>",
    "markdown_plain": "![Buttons fold on hover](https://imprint.stacking.me/i/q7Xc2mR9vLwT4nKpZb8sYe.png)"
  }

On GitHub, paste "markdown" into the pull request description, the issue, or a
comment, once. It is a <picture> element: GitHub shows a transparent card in
the reader's light or dark theme, and a single-column card on a phone. Where HTML is not allowed (Linear, Slack,
plain markdown), paste "markdown_plain": a card with its own dark background
that reads on any page. To check exactly what was rendered, fetch
"revision_url".


4. PUBLISH AGAIN WHEN THE CHANGE MOVES

After you push a commit that changes what the picture shows, take new
screenshots and publish again with the same key. Do not paste the markdown
again: the URL stays the same, and the page shows the new revision on its next
load, within about a minute. If nothing changed, the response says
"unchanged": true and no revision is added.


FIELDS FOR before-after

{
  "title": "...",            required, up to 120 characters
  "summary": "...",          optional, up to 280: what changed, in a sentence or two
  "base": {"sha": "...", "label": "..."},
                             the commit the before screenshots show: sha is 7 to 40
                             hex characters; label (a branch or tag) is optional
  "head": {"sha": "...", "label": "..."},
                             the commit the after screenshots show
  "rows": [                  1 to 12 rows, one per control and state
    {
      "label": "...",        required, up to 80: the control and its state,
                             such as "Hero CTA: hover"
      "before": "a.png",     the base screenshot; leave it out for a new control
      "after": "b.png",      the head screenshot; leave it out for a removed one
      "note": "..."          optional, up to 140
    }
  ],
  "pixel_ratio": 2           optional: 1, 2, or 3, the device scale of the screenshots
}

Both screenshots in a row are drawn at the same scale, so a control that grew
or shrank looks it. Screenshots are never enlarged; wide ones are shrunk to fit
and the row says by how much.

GitHub shows images up to about 5 MB. A card over that is drawn at half
resolution; if it is still too big, the publish is refused with a 422. Fewer
rows or tighter crops fix it.


ERRORS

401  missing, unknown, or revoked key
411  no Content-Length header
413  the request is over 40 MB
422  {"errors": [...]}: every problem, each naming the field it is about.
     Fix them all and send again.
429  more than 60 publishes in an hour with this key