Automattic / Automattic/wp-codebox
Visual compare emits a Blocks Engine report schema
- Lingua principale
- TypeScript
- Stelle
- 16
- Fork
- 4
- Merge medio
- 59m
- PR unite (30g)
- 131
Descrizione
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.
Guida per i contributori
Nessuna guida per i contributori indicizzata per questo repository
Direzione di ricerca
Inizia da browser-visual-compare.js e ispeziona i quattro punti di chiamata dell’adapter e le scritture degli artefatti, poi esamina i due file di dichiarazione e i fixture di parità di blocks-engine php-transformer che consumano lo schema. Sposta lo schema e il mapping nel consumer proprietario, smetti di incorporare il suo report in visual-diff.json e verifica che l’artefatto generico conservi solo l’evidenza normalizzata descritta in #732.
Scritto dal modello di indicizzazione a partire dal testo della issue.
Valutazione
- Stack tecnologico
- javascript, typescript
- Ambito
- testing, tooling
- Tipo di issue
- Refactoring
- Difficoltà
- 3/5
- Tempo stimato
- 1-2 giorni
- Stato di attività
- Attiva
- Chiarezza
- Abbastanza chiara
- Idoneità per principianti
- 58/100