How the Visual QA Diff Phase Works in the AI Website Cloner Template

The visual QA diff phase captures screenshots of both the original target website and the cloned Next.js build, then performs a pixel-by-pixel comparison using a library like pixelmatch to verify visual fidelity before finalizing the clone.

The JCodesMore/ai-website-cloner-template automates website replication through a multi-stage pipeline. At step 5, the Assembly & QA stage, the system executes a rigorous visual verification process to ensure the generated Next.js application matches the original design pixel-for-pixel. This visual QA diff phase merges component worktrees, renders the final page, and compares it against reference screenshots captured during the initial reconnaissance phase.

The Assembly & QA Pipeline Architecture

Worktree Consolidation and Build Rendering

Before visual comparison begins, the system consolidates all parallel development efforts. Builder agents that created components in separate Git worktrees merge their output into a single codebase. The template then wires up the page and launches the assembled site locally, typically via npm run dev, to generate a renderable build for screenshot capture.

Reference Image Retrieval

During the initial Reconnaissance phase, the system stored a baseline screenshot of the original target page. According to the repository structure, this reference image resides in docs/design-references/, serving as the ground truth for all subsequent visual comparisons.

Automated Screenshot Capture

The visual QA diff phase utilizes automated browser automation to capture the rendered output. The implementation supports multiple headless browsers including Playwright and Chrome MCP. The automation loads the locally running clone—typically at http://localhost:3000—and captures a full-page screenshot to ensure the entire viewport is evaluated.

Pixel-Level Image Comparison

Once both images are available, the system executes a pixel-by-pixel comparison using a specialized diff library such as pixelmatch. This process generates a diff image highlighting discrepancies in color, layout, or missing elements between the original reference and the cloned build.

Configurable Thresholds and Failure Reporting

The QA logic applies a configurable tolerance threshold to determine pass or fail status. If the percentage of differing pixels exceeds the specified tolerance—commonly set to 0.5% or similar—the visual QA diff phase fails and reports the discrepancy. The system saves the diff image to a review directory, allowing developers to inspect specific visual mismatches.

Implementation Example

The actual implementation resides within the cloning agents' scripts under the scripts/ directory. The following TypeScript example illustrates the core pattern used to execute the visual verification:

import { chromium } from "playwright";
import pixelmatch from "pixelmatch";
import { PNG } from "pngjs";
import fs from "fs";

async function visualQaDiff() {
  // Launch the built site (assumes it runs on http://localhost:3000)
  const browser = await chromium.launch();
  const page = await browser.newPage();
  await page.goto("http://localhost:3000");

  // Capture screenshot of the cloned page
  const cloneImg = await page.screenshot({ fullPage: true });
  fs.writeFileSync("tmp/clone.png", cloneImg);

  // Load the reference screenshot from reconnaissance phase
  const referenceImg = fs.readFileSync("docs/design-references/original.png");

  // Parse PNG buffers
  const img1 = PNG.sync.read(cloneImg);
  const img2 = PNG.sync.read(referenceImg);
  const { width, height } = img1;
  const diff = new PNG({ width, height });

  // Compute pixel differences
  const mismatched = pixelmatch(
    img1.data,
    img2.data,
    diff.data,
    width,
    height,
    { threshold: 0.1 }
  );

  // Save diff visualization for debugging
  fs.writeFileSync("tmp/diff.png", PNG.sync.write(diff));

  await browser.close();

  // Evaluate against tolerance threshold (e.g., 0.5%)
  const totalPixels = width * height;
  const percentDiff = (mismatched / totalPixels) * 100;
  if (percentDiff > 0.5) {
    throw new Error(
      `Visual QA failed – ${percentDiff.toFixed(2)}% of pixels differ (see tmp/diff.png)`
    );
  }
}

visualQaDiff().catch(console.error);

Key Files and Configuration

Several files within the repository enable this verification workflow:

• README.md (lines 86-95): Documents the multi-phase pipeline and explicitly defines step 5 as "Assembly & QA — merges worktrees, wires up the page, runs visual diff against the original" according to the source at https://github.com/JCodesMore/ai-website-cloner-template/blob/master/README.md#L86-L95.
• AGENTS.md: Contains the central instruction set for all agents, embedding the visual QA requirements within the assembly phase description.
• docs/design-references/: Directory storing original screenshots captured during reconnaissance to serve as comparison baselines.
• src/lib/utils.ts: Provides the cn() utility function used across UI components, supporting the consistent styling necessary for visual matching.
• scripts/: Houses the automation scripts that orchestrate the build process, screenshot capture, and pixel-diff execution.

Summary

• The visual QA diff phase occurs at step 5 (Assembly & QA) of the cloning pipeline in JCodesMore/ai-website-cloner-template.
• The process merges Git worktrees, renders the Next.js build locally, and captures screenshots using Playwright or similar headless browsers.
• Pixel-level comparison uses pixelmatch against reference images stored in docs/design-references/.
• Configurable tolerance thresholds determine pass/fail status, with diff images saved for manual review when discrepancies exceed allowed limits.
• Implementation details are documented in README.md lines 86-95 and executed via scripts in the scripts/ directory.

Frequently Asked Questions

What triggers the visual QA diff phase in the pipeline?

The visual QA diff phase activates during the Assembly & QA stage (step 5) after all builder agents complete their component work and the system merges the separate Git worktrees into a unified codebase. This occurs immediately following the component generation and wiring phase.

Which tools does the template use for screenshot capture and comparison?

The template utilizes Playwright or Chrome MCP for automated browser control and screenshot generation. For image analysis, it employs pixelmatch to perform pixel-by-pixel comparisons between the original reference image and the cloned build output.

Where does the template store the reference screenshots for comparison?

Reference screenshots captured during the initial Reconnaissance phase are stored in the docs/design-references/ directory. These images serve as the baseline for visual comparison against the locally rendered clone.

How does the system determine if the visual QA diff passes or fails?

The system calculates the percentage of differing pixels between the two images and compares it against a configurable tolerance threshold—typically set to 0.5% or lower. If the mismatch percentage exceeds this threshold, the phase fails and reports the error, saving a diff visualization for developer review.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}