Feat/readme screenshot

[nva138]

Closes #83.

Screenshot is now a file in the repo, npm run screenshots:update regenerates it and npm run screenshots:check compares. The check is a step in the existing Playwright workflow, and the diff image lands in test-results/, which already gets uploaded.

I went with plain scripts instead of a spec, because a test writing into the repo felt wrong: every local test:e2e would quietly rewrite the committed image. Put them in scripts/ next to the other two. Viewport and locale come from devices['Desktop Chrome'] so nothing is copy-pasted out of the Playwright config.

Tolerance is 0.1%. Two runs here give a byte-identical file, and shifting the signature by 20px gives 0.24%, so that felt like a reasonable spot. My reference image is from macOS though and CI regenerates on Linux, so the first run might say otherwise.

One thing: the empty white box above the signature is the invisible icon from #107. If that goes in first I'll regenerate.

[vitormattos]

The current CI is showing 1.9069% difference because the committed screenshot was generated on macOS and the CI generates it on Linux.

Could we make screenshots:update and screenshots:check generate the image in the same reproducible environment? For example, both could use the same Linux/Playwright environment.

I don't think increasing the tolerance is enough here, because the PR description says that moving the signature by 20px gives only 0.24%. A tolerance high enough to accept the macOS/Linux difference could also hide real visual changes.

[vitormattos]

Could we use a smaller viewport here, closer to the screenshot that we have in the README today?

With 1280x900 there is a lot of empty space on the sides and at the bottom. A smaller viewport would keep the screenshot more focused on the PDF and the elements.

[vitormattos]

Could you regenerate this screenshot after #107 is merged?

The current image still has the invisible action icon above the signature. Since this image will be shown in the README, I think we should avoid committing that visual issue in the final screenshot.

[nva138]

Thanks, makes sense.

2, 3 and 4: agreed. 4 is in the latest commit, the generated image now goes to test-results/ next to the diff. Viewport and regeneration I'd do together once #107 is in, both need a fresh image anyway.

For 1, you're right that a bigger tolerance is the wrong fix. Idea: generate inside mcr.microsoft.com/playwright:v1.63.0-noble (matches our @playwright/test) and run the CI check in the same image, then tolerance can go to zero. Downside is the container needs its own npm ci, rollup ships platform specific binaries so a macOS node_modules won't work in there. Slow, but it's a rare command.

Is that roughly what you meant or were you after something lighter?

Also merged current main into the branch. The PDF.js CSP changes did not move the screenshot, still zero pixels difference locally.

[vitormattos]

I think your container idea can work, but before deciding I would prefer to measure the cost.

Since this check will run on pull requests, could you test both approaches in CI?

• reuse the current Playwright job and run the screenshot check there;
• run the screenshot generation/check inside the Playwright container as you suggested.

Then we can compare the workflow time and see if the extra container setup and npm ci have a relevant cost here.

Without measuring it in this repository, I think we would just be guessing which approach is better.

[vitormattos]

Could we also save the generated screenshot when the image dimensions are different?

Right now this throws before demo-screenshot-current.png is written to test-results/. A viewport change can cause exactly this case, so the generated image would not be available in the CI artifacts when we need to inspect it.

[vitormattos]

I also noticed that you updated the branch by merging upstream/main into it.

For this kind of update, I suggest using rebase instead of merge. It keeps the PR history linear and avoids an extra merge commit that is only there to bring the branch up to date with main.

A common flow would be:

git fetch upstream
git rebase upstream/main
git push --force-with-lease

If there are conflicts, resolve them during the rebase, run git add for the resolved files, then continue with:

git rebase --continue

Using --force-with-lease is important here because the rebase rewrites the branch history, while still protecting against overwriting remote changes you do not have locally.