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

> Discover the Archify visual-check command, automating browser evidence capture. Inspect HTML artifacts, generate screenshots, and get machine-readable proof of renderability.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: how-to-guide
- Published: 2026-09-08

---

**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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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:

```json
{
  "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:

```bash

# 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:

```javascript
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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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.