Automattic / Automattic/wp-codebox
Visual compare emits a Blocks Engine report schema
- Dominant language
- TypeScript
- Stars
- 16
- Forks
- 4
- Avg merge
- 59m
- Merged PRs (30d)
- 131
Description
Follow-up to #732.
## The boundary
#732 built the visual-compare primitive with an explicit split: WP Codebox owns the generic evidence substrate, downstream products own policy. Its acceptance criteria state:
> No downstream-specific thresholds, Static Site Importer semantics, Data Liberation semantics, or pass/fail policy are encoded in WP Codebox.
## What shipped
`browser-visual-compare` exports `blocksEngineVisualParityReportFromVisualCompare()`, returning a `BlocksEngineVisualParityReport` with `schema: "blocks-engine/php-transformer/visual-parity-report/v1"`.
That type carries verdicts, not evidence:
```ts
status: "pass" | "warning" | "fail" | "unknown";
severity: "none" | "info" | "warning" | "error" | "critical";
```
It is also not opt-in. The adapter is called in four places inside `browser-visual-compare.js`, and each writes two things:
```js
await artifactSession.writeJson("visualDiff", "visual-diff.json", summaryWithBlocksEngineVisualParity);
await artifactSession.writeJson("blocksEngineVisualParity", "blocks-engine-visual-parity-report.json", blocksEngineVisualParity);
```
So the downstream report is written as its own artifact **and embedded inside the generic one**. Every consumer of `visual-diff.json` receives a `blocksEngineVisualParity` field carrying another product's schema and its pass/fail verdict, whether or not it has anything to do with Blocks Engine.
## Why it matters beyond naming
The status mapping is policy. `identical → pass`, `different → fail`, `partial → warning` is one product's threshold decision, made inside the substrate that was specified not to make it.
It also sets a precedent. #732 names `wp-site-generator`, `data-liberation-agent`, and `static-site-importer` as consumers. If one gets a bespoke report shape in the shared artifact, the others have a reasonable claim to theirs, and the generic artifact becomes a union of downstream schemas.
## Where it should live
The schema is owned and consumed by `blocks-engine`'s php-transformer — its parity test fixtures are the readers. `static-site-importer` sees it only transitively through the vendored figma transformer. `data-liberation-agent` does not reference it at all.
So the mapping belongs next to the schema that defines it, in `blocks-engine`, consuming Codebox's generic `visual-diff.json`.
## Suggested shape
- Stop embedding `blocksEngineVisualParity` in `visual-diff.json`.
- Move `blocksEngineVisualParityReportFromVisualCompare` and `BlocksEngineVisualParityReport` to the consumer that owns the schema.
- Keep `visual-diff.json` as the normalized generic evidence #732 specified: mismatch ratio, diff pixels, dimensions, viewport/profile metadata, source/candidate metadata, pairing strategy, explicit missing-capture and decode failures.
The coupling is small — two declaration files, one schema string, one function and its interface — so this is a contained change rather than a redesign.
## AI assistance
Claude via OpenCode inspected the shipped `runtime-playground` visual-compare surface, traced the adapter's call sites and artifact writes, and identified the consuming repositories. Chris Huber directed and reviewed the finding.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start in browser-visual-compare.js and inspect the four adapter call sites and artifact writes, then review the two declaration files and the blocks-engine php-transformer parity fixtures that consume the schema. Move the schema and mapping to the owning consumer, stop embedding its report in visual-diff.json, and verify that the generic artifact retains only the normalized evidence described in #732.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript, typescript
- Domain
- testing, tooling
- Issue type
- Refactor
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 58/100