Automate README screenshot generation and visual validation

[vitormattos]

The README currently shows a screenshot of the pdf-elements demo using a GitHub attachment.

As the library evolves, this screenshot can become outdated without being noticed. We should keep the screenshot in the repository, generate it automatically from the demo, and validate it in CI.

This issue depends on #82, which adds the Playwright infrastructure used to run browser-based tests.

What should be done

Store the screenshot in the repository

Move the README screenshot to a versioned file in the repository, for example:

img/screenshot/demo.png

Update the README to use this file instead of the current GitHub attachment.

Generate the screenshot automatically

Add an npm script that uses Playwright to generate the README screenshot from the standalone pdf-elements demo.

For example:

"screenshots:update": "node playwright/generate-screenshots.mjs"

The exact file structure can follow the Playwright setup introduced by #82.

The generated screenshot should be deterministic:

• use a fixed viewport;
• use a fixed locale;
• load a stable PDF fixture and element state;
• wait until the PDF and elements are fully rendered;
• avoid timestamps, random values and animations that can create unnecessary differences;
• write directly to the screenshot file used by the README.

Running the command repeatedly with the same source code should produce equivalent output.

Validate the screenshot

Add a second command, for example:

"screenshots:check": "node playwright/check-screenshots.mjs"

It should generate the current screenshot and compare it with the committed version.

Use pixelmatch or an equivalent small image-comparison library.

The comparison should:

• report the number and percentage of different pixels;
• use a documented tolerance for insignificant rendering differences;
• fail when the difference is above the accepted tolerance;
• create a visual diff when validation fails.

Do not require an exact zero-pixel match if small browser-rendering differences make that unreliable.

Run the validation in CI

Run the screenshot check in GitHub Actions after the Playwright environment is available.

When the screenshot is outdated, CI should:

• fail the check;
• clearly report the detected difference;
• upload the generated screenshot and visual diff as artifacts;
• tell the contributor to run npm run screenshots:update and commit the result when the visual change is expected.

The workflow must not update or commit the screenshot automatically.

Reuse the Playwright CI infrastructure from #82 instead of setting up a second unrelated browser environment.

References

The following implementations can be used as references:

• LibreSign issue #8090 — automate screenshot generation
• LibreSign issue #8091 — validate screenshots in pull requests
• profile_fields screenshot generator
• LSTelegramNotify screenshot comparison
• LSTelegramNotify screenshot validation workflow

These implementations are references only. Keep the solution appropriate for a standalone Vue library and avoid adding application-specific setup.

Acceptance criteria

• The README screenshot is stored as a versioned file in this repository.
• The README references the versioned screenshot instead of a GitHub attachment.
• An npm command regenerates the screenshot without manual browser interaction.
• Screenshot generation uses deterministic viewport, locale and demo data.
• An npm command compares the generated screenshot with the committed screenshot.
• The comparison reports the number and percentage of different pixels.
• A documented tolerance prevents insignificant rendering differences from failing CI.
• A relevant visual difference fails the CI check.
• A visual diff and generated screenshot are available as workflow artifacts on failure.
• CI explains how to regenerate the screenshot when the change is expected.
• The workflow never commits screenshot changes automatically.
• The implementation reuses the Playwright infrastructure from Add browser interaction and accessibility tests with Playwright #82.
• No Nextcloud or LibreSign runtime is required.

Good first issue

This is a good first issue for contributors interested in Playwright, documentation automation and visual regression testing.

The Playwright foundation is handled by #82, so this task can stay focused on one README screenshot and its validation.

Additional context

• If you have questions, feel free to ask in this issue.
• Give a ⭐️ to pdf-elements if you find the package useful.
• You can also support the project by giving a ⭐️ to LibreSign.