What Is the Archify visual-check Command? Automated Browser Evidence Explained

The Archify visual-check command is the automated browser-evidence step of the delivery pipeline that inspects frozen HTML artifacts across multiple Chrome viewports to capture screenshots and generate machine-readable proof of renderability, exiting with status codes that indicate pass, fail, or skip conditions.

The visual-check command in the tt-a1i/archify repository serves as the quality assurance mechanism that verifies delivered HTML artifacts actually render in a real browser environment. Unlike manual perceptual review, this command provides deterministic, machine-captured evidence that a candidate artifact displays correctly within specific viewport constraints after the validation and delivery stages complete.

What Does the Archify visual-check Command Do?

According to the archify/references/delivery-contract.md specification, visual-check executes after a candidate has been validated and delivered—meaning the deterministic artifact is frozen and immutable. The command performs five critical functions:

1. Inspects the exact HTML artifact without re-rendering or altering the source file.
2. Runs Chrome/Chromium via the DevTools pipe to measure layout containment across four standardized desktop viewports.
3. Captures light- and dark-theme screenshots at specific endpoint dimensions.
4. Writes side-car evidence files including PNG screenshots, an HTML contact-sheet, and a JSON receipt.
5. Exits with deterministic status codes that downstream automation can interpret unambiguously.

This process ensures that what was delivered can actually be displayed in a real browser, providing concrete evidence rather than assumptions about renderability.

Viewport Testing and Screenshot Capture Strategy

The visual-check command validates layout fitness across a range of display geometries to ensure the artifact remains usable on different desktop configurations.

Desktop Viewport Measurements

As defined in archify/references/delivery-contract.md, the command measures whether the page’s first-screen layout fits within four specific desktop viewports:

• 1440 × 900 (standard laptop)
• 1600 × 1000 (extended desktop)
• 1920 × 1080 (Full HD)
• 2048 × 1320 (high-resolution display)

The system launches Chrome/Chromium programmatically and uses the DevTools protocol to set these viewport dimensions precisely, checking that the artifact’s layout engine does not produce overflow or containment defects at any of these resolutions.

Light and Dark Theme Verification

Beyond viewport sizing, the command captures light- and dark-theme screenshots at two endpoint sizes: 1440 × 900 and 2048 × 1320. This ensures that the artifact respects prefers-color-scheme media queries and renders correctly regardless of the user’s system theme preference.

Generated Evidence Files and JSON Receipt

The archify/bin/visual-check.mjs implementation generates a comprehensive evidence package stored alongside the original artifact. The side-car output includes:

• Four PNG screenshots representing the two endpoint viewports in both light and dark modes.
• An HTML contact-sheet (output.visual-check.html) that aggregates the visual evidence for human inspection.
• A JSON receipt that binds the artifact’s SHA-256 hash and byte count, creating cryptographic proof of which exact file was tested.

The JSON receipt structure follows this schema:

{
  "artifact_sha256": "<hash>",
  "evidenceKind": "automated-browser",
  "status": "pass",
  "visualReview": "pending",
  "capturedScreenshots": [
    "output.visual-check.1440x900.light.png",
    "output.visual-check.1440x900.dark.png",
    "output.visual-check.2048x1320.light.png",
    "output.visual-check.2048x1320.dark.png"
  ],
  "contactSheet": "output.visual-check.html"
}

Crucially, the receipt always sets visualReview: "pending" because visual-check does not perform perceptual visual review—it merely records that a real browser successfully rendered the artifact within the prescribed bounds. Human approval or automated image-reader review must be recorded separately to change this status.

Exit Codes and CLI Usage

The archify/bin/visual-check.mjs file defines three specific exit statuses that allow CI/CD pipelines to react appropriately to the command outcome:

• 0 — Pass: All measurements and captures succeeded without containment defects.
• 1 — Fail: A containment defect was detected or a runtime/capture error occurred.
• 2 — Skipped: Chrome/Chromium is unavailable on the execution environment.

Command-Line Interface

Invoke visual-check after a successful delivery to collect browser evidence:

# Collect automated browser evidence for a delivered artifact

node bin/archify.mjs visual-check path/to/output.html --json

The --json flag outputs the receipt object to stdout for pipeline integration.

Programmatic API with runVisualCheck

For custom automation, import the core logic directly from the implementation file:

import { runVisualCheck } from './archify/bin/visual-check.mjs';

// Execute visual-check and capture the JSON receipt
const result = await runVisualCheck('dist/my-diagram.html', { json: true });
console.log(result.receipt);

This approach allows Node.js applications to trigger browser validation programmatically and consume the evidence receipt for downstream processing.

Key Limitations and Design Philosophy

As documented in archify/references/delivery-contract.md, the visual-check command adheres to a strict separation of concerns: it collects machine-readable evidence only. The command never alters the artifact’s content, never applies perceptual diff algorithms, and never assigns final visual approval. The visualReview field remains "pending" specifically to indicate that a human or specialized image-analysis service must still review the captured screenshots before final acceptance.

This design ensures that visual-check remains fast, deterministic, and automatable while leaving subjective quality assessment to appropriate review stages in the delivery pipeline.

Summary

• The Archify visual-check command verifies that frozen HTML artifacts render correctly in Chrome/Chromium across four desktop viewports.
• It captures light and dark theme screenshots at 1440×900 and 2048×1320 resolutions, generating four PNG files, an HTML contact-sheet, and a JSON receipt.
• The JSON receipt includes the artifact’s SHA-256 hash, evidenceKind: "automated-browser", and always sets visualReview: "pending".
• Exit codes are deterministic: 0 for pass, 1 for failure/containment defects, and 2 when Chrome is unavailable.
• The command does not perform perceptual review—it strictly provides machine-captured evidence that a real browser successfully loaded the artifact.

Frequently Asked Questions

Does the visual-check command perform visual diff testing or perceptual review?

No. According to the delivery contract in archify/references/delivery-contract.md, visual-check only provides machine-readable evidence that a real browser can render the artifact within prescribed bounds. It explicitly does not perform perceptual visual review, which is why the JSON receipt always marks visualReview: "pending" pending human or automated image-reader approval.

What specific viewports does the visual-check command test?

The command tests four desktop viewports defined in archify/references/delivery-contract.md: 1440×900, 1600×1000, 1920×1080, and 2048×1320. It captures actual screenshots at the two endpoints (1440×900 and 2048×1320) in both light and dark themes, while measuring layout containment across all four dimensions.

Why does the JSON receipt always show visualReview: "pending"?

The visualReview: "pending" status indicates that while the automated browser evidence has been collected successfully, no perceptual review has occurred yet. This field remains pending because visual-check captures evidence only—it does not judge visual correctness. Human reviewers or specialized image-analysis tools must examine the generated PNG screenshots and update the status separately.

What happens if Chrome or Chromium is not installed when running visual-check?

If Chrome/Chromium is unavailable, the visual-check command exits with status code 2 (skipped), as defined in archify/bin/visual-check.mjs lines 24-26. This allows CI/CD pipelines to distinguish between a genuine rendering failure (exit code 1) and an environment configuration issue that prevents the command from executing.

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