What Is the Purpose of the visual-check Command in Archify?

The visual-check command in Archify is an automated browser-evidence tool that validates diagram layout containment across predefined viewports, captures light and dark theme screenshots, and generates machine-readable receipts and contact sheets for human review.

Archify is an open-source diagram delivery system that enforces strict quality gates before artifacts are marked as production-ready. The visual-check command serves as the automated perceptual validation layer, running a headless Chrome instance against delivered HTML files to provide reproducible evidence of rendering correctness while deliberately leaving final visual approval for human reviewers.

Core Functionality of the visual-check Command

The command performs four distinct operations to verify that diagram artifacts render correctly in real browser environments.

Layout Containment Validation

The tool verifies that rendered diagrams fit within a strict set of predefined desktop viewports. In archify/bin/visual-check.mjs (lines 12-17), the command tests against four resolution tiers:

• 1440 × 900 (smallest)
• 1600 × 1000
• 1920 × 1080
• 2048 × 1320 (largest)

Each viewport represents a common desktop resolution that the diagram must contain without overflow or broken layouts.

Screenshot Capture Across Viewports

After validating containment, the command captures visual evidence using headless Chrome. According to the implementation in archify/bin/visual-check.mjs (lines 19-23), it generates screenshots for the smallest and largest viewports in both light and dark themes:

• Light and dark variants at 1440 × 900
• Light and dark variants at 2048 × 1320

This four-shot capture strategy provides representative coverage of the visual spectrum without excessive storage overhead.

Machine-Readable Receipt Generation

The command creates a *.visual-check.json receipt file that records the complete audit trail. As implemented in archify/bin/visual-check.mjs (lines 59-75), the JSON structure includes:

• Containment status for each tested viewport
• Capture status indicating successful screenshot generation
• Diagnostics capturing any Chrome runtime errors or rendering anomalies

Crucially, the receipt marks the perceptual review status as "pending", emphasizing that visual-check provides evidence rather than approval.

Contact Sheet HTML Generation

For human review workflows, the command generates a *.visual-check.html contact sheet. The implementation (lines 573-580 in archify/bin/visual-check.mjs) arranges the four captured screenshots side-by-side, enabling quick visual comparison of theme variants and responsive behavior without requiring manual browser testing.

How visual-check Fits Into the Delivery Pipeline

The visual-check command operates after deterministic validation passes but before final visual sign-off. According to archify/references/delivery-contract.md (lines 13-22), this separation of concerns ensures that:

• Automated systems handle reproducible technical checks (containment, rendering, capture)
• Human reviewers perform subjective quality assessment (visual polish, aesthetic approval)

The command creates the necessary artifacts for the visual_review step but explicitly does not approve the diagram's visual quality itself.

Running the visual-check Command

Invoke the command through Archify’s CLI as registered in archify/bin/archify.mjs (lines 25-30):

archify visual-check <output.html> [--json]

Practical Example

# Run visual-check on a delivered artifact with JSON output

node archify/bin/archify.mjs visual-check dist/web-app.html --json

Generated Output Files

Executing the command creates the following artifacts relative to the input HTML:

• web-app.visual-check.json — Machine-readable receipt with containment status, capture status, and diagnostics
• web-app.visual-check.html — Contact sheet displaying the four captured screenshots for human inspection
• web-app.visual-check.1440x900.light.png — Light-theme screenshot at the smallest viewport
• web-app.visual-check.2048x1320.dark.png — Dark-theme screenshot at the largest viewport

Exit Codes and Status Handling

The command returns specific exit codes to support CI/CD pipeline integration:

• 0 — All viewports contained the layout and screenshots captured successfully
• 1 — Layout containment failed or screenshot capture failed (check receipt for diagnostics)
• 2 — Chrome unavailable (not installed or sandbox disabled); receipt marked as skipped

Source Code Architecture

Understanding the key files helps when extending or debugging the visual-check functionality:

• archify/bin/visual-check.mjs — Core implementation defining viewports, launching Chrome via Puppeteer, capturing screenshots, and writing receipt/contact sheet artifacts
• archify/bin/archify.mjs — CLI entry point that registers the visual-check sub-command and forwards arguments to the implementation module
• archify/references/delivery-contract.md — Documentation explaining how visual-check fits into the broader delivery contract and why human review remains mandatory
• archify/test/visual-check.test.mjs — Test suite validating containment logic, Chrome runtime handling, and receipt generation
• generated/maka-regenerated.workflow.visual-check.* — Example artifacts demonstrating the output format of JSON receipts, contact sheets, and PNG screenshots

Summary

• The visual-check command in Archify provides automated browser-based evidence that HTML diagram artifacts render correctly across four predefined desktop viewports.
• It captures light and dark theme screenshots at the smallest and largest viewports to verify visual consistency.
• The tool generates two key artifacts: a machine-readable JSON receipt (*.visual-check.json) and a human-review contact sheet (*.visual-check.html).
• Exit codes (0, 1, 2) enable CI/CD integration by distinguishing between success, rendering failures, and Chrome availability issues.
• The command deliberately marks visual review as "pending", maintaining the separation between automated evidence generation and human aesthetic approval.

Frequently Asked Questions

What viewports does the visual-check command test against?

The command validates layout containment against four predefined desktop resolutions: 1440 × 900, 1600 × 1000, 1920 × 1080, and 2048 × 1320. These viewports are hardcoded in archify/bin/visual-check.mjs to represent common desktop display sizes.

Does visual-check approve the visual quality of diagrams?

No. The visual-check command explicitly marks the perceptual review status as "pending" in the JSON receipt. Its purpose is to provide automated evidence that the artifact renders correctly in Chrome, while the final visual polish and aesthetic approval remain the responsibility of human reviewers performing the subsequent visual_review step.

What files does visual-check generate?

The command generates three types of artifacts: a *.visual-check.json receipt containing containment and capture status, a *.visual-check.html contact sheet for side-by-side screenshot comparison, and four PNG screenshots representing light and dark themes at the smallest (1440 × 900) and largest (2048 × 1320) viewports.

Why does visual-check exit with code 2?

Exit code 2 indicates that Chrome is unavailable—either not installed on the system or blocked by sandbox restrictions. When this occurs, the command creates a receipt marked as skipped rather than failed, allowing pipelines to distinguish between rendering defects and infrastructure issues.

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