Improve auto-sync of documentation screenshots

[ianpaschal]

Summary by CodeRabbit

• New Features

  • Added intelligent screenshot comparison to sync only modified documentation images, reducing unnecessary updates.
  • Implemented automatic PNG image optimization during screenshot synchronization.

• Improvements

  • Enhanced screenshot quality with improved device scaling configuration.

• Chores

  • Updated build and testing configurations to support improved screenshot handling workflow.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
combat-command-app	Ready	Preview, Comment	Jun 12, 2026 8:34am

[coderabbitai]

Walkthrough

This PR refactors screenshot handling to reduce documentation churn by intelligently syncing only changed images. It moves screenshot output from docs-screenshots/ to test/output/screenshots/, updates Playwright with device scale factor 2 for better visual capture, and introduces a new sync-docs-screenshots.cjs script that compares PNGs using pixelmatch before copying. The CI workflow uploads from the new directory, the sync workflow installs comparison tools and runs the script to copy only modified screenshots into the static site, and linting is extended to cover the new .github scripts.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly reflects the main objective of the PR, which systematically improves the screenshot synchronization workflow through script additions, configuration updates, and artifact path changes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch ian/fix-screenshot-sync-assignee

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint install failed due to a network error.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.github/scripts/sync-docs-screenshots.cjs:
- Around line 4-6: The script destructures process.argv into sourceDir,
targetDir and toolsDir and directly requires modules via path.join; add
validation to ensure the expected positional args exist (check
process.argv.length or that sourceDir/targetDir/toolsDir are non-empty), verify
that sourceDir and targetDir paths exist and are directories (use
fs.existsSync/fs.statSync), and ensure toolsDir exists before requiring PNG and
pixelmatch (wrap the require(path.join(toolsDir, ...)) calls in a try/catch or
pre-check so you can log a clear usage message and exit with non-zero status
when arguments or paths are missing/invalid); reference the process.argv
destructuring and the require(path.join(toolsDir, 'node_modules', 'pngjs')) /
require(path.join(toolsDir, 'node_modules', 'pixelmatch')) locations when
applying these checks.
- Around line 20-32: Wrap the PNG parsing and comparison logic that uses
PNG.sync.read(sourcePath) and PNG.sync.read(targetPath) plus the pixelmatch()
call in a try-catch block so a corrupted/malformed PNG doesn't crash the whole
script; catch any error, log a clear diagnostic message that includes the file
name (file), sourcePath/targetPath and the error, then continue to the next file
(i.e. skip comparison for this pair) so the loop proceeds; ensure you still only
compute numDiffPixels and compare against maxDiffRatio inside the try so those
operations are protected.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 3f45fce0-e4f0-44f9-bb5a-4b5f06a19c60

📥 Commits

Reviewing files that changed from the base of the PR and between 978a2d8 and 6ae78f9.

📒 Files selected for processing (7)

• .github/scripts/sync-docs-screenshots.cjs
• .github/workflows/ci.yml
• .github/workflows/sync-docs-screenshots.yml
• .gitignore
• eslint.config.mjs
• playwright.config.ts
• test/helpers/screenshot.ts