Use WP Codebox visual-compare evidence for replica verification

[chubes4]

Problem

Data Liberation Agent currently owns its own low-level visual comparison stack for origin vs replica verification:

• src/lib/screenshot/compare.ts joins origin/replica screenshot manifests by pathname, crops screenshots, runs pixelmatch, writes diff PNGs, and emits comparison.json.
• scripts/diff-pngs.ts duplicates a standalone PNG diff path.
• scripts/run-design-e2e.ts uses those primitives for the guided HTML-first parity gate.
• scripts/carry-replica-shots.ts captures replica screenshots into the same manifest shape for comparison.
• src/mcp-server/handlers/compare.ts exposes this through liberate_compare.

That logic is useful, but most of the screenshot diff/evidence layer is generic browser visual comparison rather than Data Liberation-specific migration policy.

Upstream tracker

WP Codebox issue: Automattic/wp-codebox#732

The proposed upstream primitive should provide generic visual-compare evidence: source/candidate screenshots, diff image, mismatch JSON, viewport/profile metadata, explicit failure statuses, and artifact-bundle integration.

Proposed DLA direction

Once the WP Codebox primitive exists, DLA should consume it for replica verification where practical while keeping DLA-specific semantics local.

DLA should keep owning:

• source-site discovery and screenshot capture strategy;
• authenticated/CDP capture behavior;
• platform-specific settling, overlay dismissal, lazy-load behavior, and extraction state;
• migration-specific thresholds and labels;
• guided notes/verdicts such as whether a replica is faithful enough to ship.

DLA can stop owning or reduce:

• generic PNG pair diffing;
• generic screenshot-set comparison JSON shape;
• duplicated standalone diff helpers;
• ad hoc artifact formatting that could instead reference Codebox visual-compare artifacts.

Boundary note

Static Site Importer has its own visual-fidelity comparison target metadata and should remain Codebox-agnostic. SSI should describe what to compare; Codebox can provide a generic harness for consumers that choose to run that comparison.

Acceptance criteria

• DLA can use WP Codebox visual-compare artifacts for origin vs replica evidence in at least one verification path.
• DLA preserves existing migration-specific scoring/rubric behavior.
• Existing liberate_compare behavior either remains compatible or is migrated with a clear artifact compatibility path.
• DLA does not make Static Site Importer aware of WP Codebox.
• Missing screenshots, dimension mismatches, and decode errors remain explicit in DLA-facing results.

cc @borkweb

[chubes4]

WP Codebox now has a merged generic wordpress.visual-compare runtime command: Automattic/wp-codebox#734

This came from looking at DLA's current screenshot comparison path and should give DLA a reusable artifact-backed primitive for source/candidate/diff evidence while DLA keeps owning migration-specific scoring, repair policy, and source/replica judgment.

Suggested adoption shape: use wordpress.visual-compare where a Codebox runtime is available, then map its visual-diff.json metrics and artifacts into DLA's existing comparison/reporting flow instead of duplicating the low-level PNG diff plumbing.