feat(visual-agent): visual diff + change quantification

[kiannidev]

Summary

• Adds compareRouteScreenshots and compareVisualCaptureSets in src/visual-agent/visual-diff.ts to compare before/after PNG captures per route using pixelmatch.
• Produces diff PNG bytes, changed-pixel percentages, and route status classification (changed, unchanged, new, removed).
• Applies anti-alias tolerance via pixelmatch threshold and suppresses sub-threshold noise with a configurable changed-pixel percent cutoff.
• Returns an overall summary with average changed-pixel percent across comparable routes.

Closes #582

Parent epic: #577

Test plan

• npm run typecheck
• Unit tests in test/unit/visual-diff.test.ts cover unchanged, changed, new/removed, noise suppression, dimension mismatch, and set summaries
• Full CI (npm run validate)

Made with Cursor

[ghost]

Note

Gittensory Gate skipped

PR closed before full evaluation. No late first comment was created.

Signal	Result	Evidence	Action
Gate result	⚠️ Skipped	#651 is no longer open.	No action.

---

💰 Earn for open-source contributions like this. Gittensor lets GitHub contributors earn for the work they already do — register to start earning →.

Checked by Gittensory, a quiet PR intelligence layer for OSS maintainers.

[superagent-security]

Superagent didn't find any vulnerabilities or security issues in this PR.

[ghost]

gittensory · advisory review

Reviewed 5 changed file(s) — two independent AI reviewers.

Changed files: package-lock.json, package.json, src/visual-agent/visual-diff.ts, test/unit/visual-diff.test.ts, test/unit/worker-entry-boundary.test.ts

Suggested action: ✅ Safe to merge — both reviewers found no blocking issues.

Reviewer A · gpt-oss-120b — recommends ✅ merge
This PR introduces a visual diff utility for comparing PNG screenshots, adds comprehensive unit tests, and enforces that the new Node‑only modules are not pulled into the Cloudflare Worker entry or MCP binary. The implementation is clean, type‑safe, and respects the project's public/private boundaries.

Suggestions

• Add a brief comment in the package.json scripts or README noting that pixelmatch/pngjs are Node‑only and must stay out of the worker bundle.
• Consider adding a lint rule or CI check to prevent accidental imports of visual-agent modules from non‑agent entry points.

Worth double-checking

• Future code changes might inadvertently import visual-agent utilities into the worker bundle; the existing test guards against this but a lint rule would provide earlier detection.
• The new dependencies increase bundle size for any agent that uses visual diff; ensure they remain optional and not included in production builds.

Reviewer B · nemotron-3-120b-a12b — recommends ✅ merge
The PR adds a visual diff utility for comparing route screenshots using pixelmatch and pngjs, with comprehensive unit tests and a boundary test to prevent accidental inclusion in Worker/MCP bundles. The code is well-structured, type-safe, and respects the project's public/private boundary by design.

Worth double-checking

• Ensure the visual-agent module is never imported in src/index.ts or MCP bin (covered by new boundary test).
• Verify that the added dependencies (pixelmatch, pngjs) are correctly listed as devDependencies in the MCP bundle if used there (though the boundary test should prevent this).

[kiannidev]

Hi, @JSONbored
I resolved conflicts.
Please review PR again

Thanks

[JSONbored]

PR #651 — feat(visual-agent): visual diff + change quantification
Author: kiannidev | CI: ✅ pass | Status: Concerns
ACTION: REQUEST CHANGES

Highlights:

• Internal tooling that produces visual-diff bytes — not a visible UI change, so the screenshot rule doesn't apply.
• Pure, deterministic, well-tested image comparison (unchanged/changed/new/removed, noise suppression, dimension mismatch, diff-image toggle).
• pixelmatch/pngjs are genuinely required by this feature (legitimate, scoped).

Change requests / reasons:

• merge conflicts
• Verify pixelmatch/pngjs (Node Buffer/zlib) are NOT imported into the Worker entry bundle — could break the deploy bundle. Confirm they're only on the agent path.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.68%. Comparing base (950c6e0) to head (365ee15).

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #651      +/-   ##
==========================================
+ Coverage   96.66%   96.68%   +0.01%     
==========================================
  Files          92       93       +1     
  Lines       13720    13769      +49     
  Branches     5001     5015      +14     
==========================================
+ Hits        13263    13312      +49     
  Misses         88       88              
  Partials      369      369              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[JSONbored]

PR #651 — feat(visual-agent): visual diff + change quantification
Verdict: MERGE
Resolves issue #582: FULLY
CI: All green (validate, test x2, lint, workers, mcp, ui, security, Superagent Security Scan = success, codecov). gittensory/Context neutral.

Highlights:

• Implements exactly what #582 asks: compareRouteScreenshots + compareVisualCaptureSets using pixelmatch/pngjs, producing diff PNG bytes, per-route changed-pixel %, and changed/unchanged/new/removed classification + overall average and summary.
• Anti-alias tolerance via pixelmatch threshold and sub-threshold noise suppression via configurable changeThresholdPercent; dimension mismatch handled as deterministic "changed" (no crash).
• Strong unit tests (all four classifications, noise suppression, custom threshold, includeDiffImage toggle, width/height-only mismatch, mixed/empty summaries).
• Good safety boundary: worker-entry-boundary.test.ts asserts the Node-only deps (pixelmatch/pngjs/visual-agent) never become reachable from the Worker entry or the published MCP bin.

Concerns / required changes:

• Minor: includes test-only additions for the pre-existing /v1/scoring/explain-breakdown route and gittensory_explain_score_breakdown — tangential extra coverage, no unrelated production code. Harmless, slightly off-scope.

Completeness vs issue: Routes with real changes get a diff image + change %, unchanged marked unchanged, new/removed classified — all acceptance criteria met and tested.

[JSONbored]

Adding gittensor:feature label as a one-time goodwill gesture - please do NOT complete issues assigned to other people unless explicitly asked to do so, or else you will not get any points in the future.