feat!: sharp for PNG codec, Batch Review Mode by default

[FRSgit]

Summary

Two breaking changes for v5: image comparison no longer goes through pngjs, and Batch Review Mode becomes the default.

sharp replaces pngjs

• compareImagesTask decodes, pads and encodes with sharp (already a runtime dependency). pngjs's default write tried all five PNG filters per scanline in JS and accounted for most of the comparison time; sharp's native path is many times faster and unaffected by V8 coverage instrumentation.
• Same-size images are passed through as the bytes already in memory, so only the diff image is encoded on the success path. The task return contract is unchanged.
• Pixel data and diff results are identical to 4.x (verified by decoding both fixtures with pngjs and sharp and running both pad+pixelmatch pipelines: same RGBA bytes, same diff pixel count).
• pngjs, @types/pngjs, and the deprecated stubs @types/sharp and @types/pixelmatch are removed.

Batch Review Mode on by default

• pluginVisualRegressionBatchReviewMode and pluginVisualRegressionBatchReviewModeShowPassingImages are now read by shared getters in config.utils.ts. Previously support.ts (FAB, carousel, hooks) and commands.ts (matchImage, inlined) each read the flag on their own.
• The mode is on unless the option is explicitly false (or the string "false" from the CLI).
• examples/next configs drop the now-redundant opt-in; README's "How to enable" becomes "How to disable"; MIGRATION.md gets a new entry.

Breaking changes

• Batch Review Mode is the default. matchImage() no longer throws on the first mismatch. Failing snapshots are collected and a single error with the failure count is thrown once the spec finishes; in headed mode they can be reviewed and approved in bulk from the plugin's floating button. To keep the 4.x behaviour, set pluginVisualRegressionBatchReviewMode: false via expose (Cypress >= 15.10) or env (older Cypress). Projects that already set it to true can drop the option.

• Node.js >= 20.9.0. sharp 0.35 already required it; the engines field was stale.

• PNG bytes change. Files written by the plugin are now encoded by libvips. Existing baselines keep working and are only rewritten when updated. DIFF_IMAGES_VERSION stays 1 because the comparison algorithm is unchanged.

• Uniform padding. When compared images differ in size, the added area is now fully filled with rgba(0, 0, 0, 64); 4.x left the first padded row/column transparent due to an off-by-one. Diff results are unaffected.

Migration notes: packages/cypress-plugin-visual-regression-diff/MIGRATION.md, section 4.x -> 5.x.

Tests

• New config.utils.test.ts covers the expose/env fallback, the batch-mode default, and disabling via false / "false" on both Cypress APIs. support.test.ts keeps only the localStorage precedence tests.

• Base64 PNG snapshots (72 KB, coupled to encoder output) replaced by structural assertions: decode with sharp, check dimensions, check that same-size images are passed through untouched.

• New image.utils.test.ts covers decode (RGB → RGBA), encode round trip, padding pixels, and scaleImageAndWrite (previously untested).

• Integration suite with coverage: test body time 818 ms → 146 ms.

• Cypress examples/next and examples/webpack: component and e2e suites pass with Batch Review Mode on by default (no explicit option in either config); a plain comparison run against committed baselines passes; a forced size mismatch fails correctly and writes a stamped .diff.png at the padded size.

Other changes

• Cypress devDependency bumped to 16.1.0 in the plugin package and both examples (peer range >=13 unchanged). Example scripts use --expose, the Next.js example mounts from cypress/react, and the legacy Cypress.env() fallback goes through a local type since Cypress 16 typings dropped it.
• scripts/cypress.demo.config.ts (used only by the demo GIF recorder) moved out of examples/next.

🤖 Generated with Claude Code