[thymikee]

Summary

diff screenshot scales the current image proportionally to the baseline width, aligns top-left, and compares the full union height. A 1080×2340 capture against a 375×812 Figma reference becomes 375×813; unmatched rows count as differences even at threshold 1. Equal-size RGB behavior stays unchanged. Original files stay unchanged.

JSON replaces dimensionMismatch with normalization for different-size inputs, including original/scaled/comparison sizes and coordinate scales. Region/ref rectangles use comparison pixels. A changeset documents the migration.

agent-device diff screenshot --baseline figma.png current.png --out diff.png --json

18 files; gross lines: production 293, tests 390, docs/changeset 11 (578 additions / 116 deletions). Scope includes PNG/JPEG allocation preflight and comparison-canvas limits. No linked issue.

Validation

Head: d01cc1103f142a756865c802fbeee3e2eeda3f66.

pnpm check:affected --run --head d01cc1103f142a756865c802fbeee3e2eeda3f66: passed; receipt run-yxTKES, exactCommit=true, checkoutChanged=false; 10 checks passed, 7 skipped, 4,062 related tests passed.

Coverage's import-budget assertion reproduced at e857610218 (23 eager modules versus 14). Loading normalization dependencies on demand fixes it. The full import-budget suite plus screenshot-diff/image tests pass: 900 tests. Independent follow-up review approved.

Full coverage, integration and platform smoke remain CI obligations at this head; parked replay lanes were skipped. Live capture was not rerun because capture dispatch is unchanged. Optional worker offload and JPEG decode-error unification remain outside this fix.

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-10-21 13:10 UTC

[github-actions]

Size Report

Metric	Base	Current	Diff
Installed (including dependencies)	5.48 MB	5.49 MB	+2.7 kB
Package (unpacked)	5.48 MB	5.49 MB	+2.7 kB
Package (download)	1.66 MB	1.66 MB	+998 B

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	40.4 ms	39.2 ms	-1.2 ms
CLI --help	82.2 ms	80.6 ms	-1.6 ms

[thymikee]

The PR is ready from the code side at e857610. The screenshot-diff change reads correctly, and the new diff tests would fail on the old dimensionMismatch path. The Coverage job ended without an assertion, a failing test or a threshold message, and nothing names a screenshot-diff test. Its log stops during macOS-helper build lines, which looks like a runner cutoff. That job runs the changed capture-kit and capture tests, so I cannot clear it without a rerun. I did not measure resizePngBox cost, and I did not run the repeated-IHDR regression or any test against pre-fix code. Live capture was not rerun, and it is not needed because capture dispatch is unchanged. No conflicts are known.

Not blocking, and you can take or leave these: the PR removes the released dimensionMismatch field and changes the different-size result from match:false at 100% to a normalized percentage that can match, so a changeset naming the removed field, the new normalization object and the new default would match how the repo records behavior changes (see .changeset/host-entry.md). resizePngBox at https://github.com/callstack/agent-device/blob/e857610/packages/capture-kit/src/screenshot-diff.ts#L115 resamples on the daemon request thread while the pixel compare runs in the PNG worker, so CPU-bound pixel work could all go through png-worker-client. The over-budget JPEG case throws INVALID_ARGS from the header preflight but COMMAND_FAILED when jpeg-js recovery hits the resolution limit (https://github.com/callstack/agent-device/blob/e857610/packages/capture-kit/src/screenshot-image.ts#L457), so mapping both to one code, or documenting the split, would help callers.

Before merge, please rerun the Coverage job to green and add the changeset.

[thymikee]

Addressed the required follow-ups at d01cc11:

• Added .changeset/screenshot-diff-width-normalization.md documenting the default normalization, removal of dimensionMismatch, the normalization replacement, and consumer migration.
• Fixed the actual Coverage failure. The raw job log contains an eager-closure-budgets.test.ts assertion: screenshot-diff imported 23 modules versus 14 at the merge-base. gh run view --log omitted those lines; this was not a runner cutoff. Resize and pixel-limit dependencies now load inside the comparison path.
• Reproduced that assertion on e857610. After the fix, the full import-budget suite and screenshot-diff/image tests pass (900 tests). Exact-head affected validation passed: 10 runnable checks, 4,062 related tests, exactCommit=true, checkoutChanged=false (receipt run-yxTKES). Independent follow-up review approved.

The optional worker offload remains a separate performance change pending measurement. JPEG errors retain the existing distinction: a readable over-budget header is INVALID_ARGS; a malformed stream that reaches decoder recovery is COMMAND_FAILED. No compatibility/error-handling change was added.

Fresh CI is required at the pushed head; I am monitoring it before calling Coverage cleared.