Automattic / Automattic/wp-codebox

Make visual-compare diagnostics region-aware and semantic

Open
#1,884 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
16
Forks
4
Avg merge
59m
Merged PRs (30d)
131

Description

## Problem

`wordpress.visual-compare` captures the first 160 visible DOM elements, matches source and candidate by exact generated path, omits pseudo-elements, and ranks rectangle overlap rather than mismatched pixels. Gutenberg wrapper changes therefore turn corresponding elements into added/removed rows and late-page mismatch regions lose actionable element attribution.

Observed in Static Site Importer fixture `15-saas`: only 2 flow elements matched while 158 were reported added and 158 removed; both 160-element snapshots were truncated. The pixel diff clearly showed navigation, button, text, and pseudo-element paint drift that the explanation did not rank explicitly.

## Required outcome

- Match elements semantically when wrappers and `:nth-of-type()` paths differ, with deterministic confidence and ambiguity handling.
- Capture visible `::before` and `::after` paint/style evidence under their host element.
- Augment bounded snapshots with elements intersecting top mismatch regions, including late-page elements.
- Rank attributed elements by mismatched-pixel impact rather than rectangle overlap alone.
- Preserve explicit selector capture and bounded output with exact selection/truncation metadata.

## Acceptance

- Wrapper insertion does not collapse semantic matching.
- A pseudo-element paint mismatch is named in the explanation.
- An element after the initial document-order budget is captured when it intersects a top mismatch region.
- A large unchanged wrapper ranks below a smaller element covering actual mismatch pixels.
- Deterministic tests cover all behaviors.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start at the wordpress.visual-compare entry point and inspect its snapshot, matching, mismatch-region, and explanation logic, then review the existing tests. Define deterministic coverage for semantic wrapper matching, pseudo-elements, late-page region capture, pixel-impact ranking, and selector/truncation metadata. Done means all listed acceptance behaviors pass without losing bounded output.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
frontend, testing
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.