Archify Visual Check Command: Options, Containment, Capture, and Contact Sheet Explained

Use archify visual-check <output.html> to validate layout containment across four desktop viewports, generate light/dark theme screenshots, and produce a JSON receipt plus contact-sheet HTML for human review without modifying the original artifact.

The visual-check command in the tt-a1i/archify repository is a post-delivery quality gate designed for deterministic visual validation. As implemented in archify/bin/visual-check.mjs, it renders an HTML artifact at multiple resolutions, checks for overflow, captures themed screenshots, and generates side-car files that preserve the original artifact's immutability.

---

Command Options and Basic Usage

The visual-check command accepts a single positional argument and two optional flags.

# Standard usage with JSON receipt output

archify visual-check dist/my-diagram.html --json

# Human-readable console output (no --json flag)

archify visual-check dist/my-diagram.html

# Disable Chrome sandbox when running as root

export ARCHIFY_CHROME_NO_SANDBOX=1
archify visual-check dist/my-diagram.html --json

In archify/bin/archify.mjs, the CLI entry point validates that exactly one .html file is provided and aborts with a clear error if the file is missing or has an incorrect extension.

---

Layout Containment Validation Across Four Viewports

The visual-check command defines four desktop readability viewports in visual-check.mjs:

Viewport	Dimensions	Purpose
Small desktop	1440×900	Baseline laptop screens
Medium desktop	1600×1000	Extended workspace
Standard HD	1920×1080	Full HD displays
Large desktop	2048×1320	High-resolution monitors

For each viewport, the renderer measures the diagram's bounding box. If any dimension overflows the viewport boundary, the containment check fails. The implementation in visual-check.mjs lines 609-656 emits diagnostics and sets receipt.captures.status to "fail", resulting in exit code 1.

---

Theme Capture System: Light and Dark Screenshots

The visual-check command captures eight PNG screenshots total — four viewports × two themes. As defined in visual-check.mjs:

• Light theme renders at 1440×900 and 2048×1320
• Dark theme renders at the same two extreme viewports

Screenshots are written atomically beside the artifact. The naming convention follows:

<artifact-base>.visual-check.<width>x<height>.<theme>.png

Chrome discovery follows a priority order defined in visual-check.mjs:

1. ARCHIFY_CHROME environment variable
2. OS-specific defaults (Chrome, Chromium, Google Chrome)
3. PATH search

If no Chrome executable is found, the command returns exit code 2 with a skipped receipt.

---

Contact Sheet and Side-Car File Generation

The sidecarPaths() function in visual-check.mjs lines 55-74 creates three output types with the base name <artifact>.visual-check:

Side-car Type	File Extension	Purpose
JSON receipt	.visual-check.json	Machine-parseable validation results
Contact sheet	.visual-check.html	Human review interface with all screenshots
Screenshots	.visual-check.*.png	Eight PNG captures for visual audit

The contact-sheet HTML displays all screenshots side-by-side as implemented in visual-check.mjs. This compact layout enables reviewers to quickly assess layout consistency and theme rendering without opening individual files.

---

JSON Receipt Structure and Exit Codes

According to [SKILL.md](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md#L103-L108), the JSON receipt contains:

{
  "schemaVersion": 1,
  "ok": true,
  "command": "visual-check",
  "status": "pass",
  "visualReview": "pending",
  "artifact": { "path": "/abs/path/to/file.html" },
  "containment": { "status": "pass" },
  "captures": { "status": "pass" },
  "sidecars": {
    "receipt": "file.visual-check.json",
    "contactSheet": "file.visual-check.html",
    "screenshots": ["..."]
  }
}

Critical field: visualReview is always "pending" — no automatic approval occurs. Human reviewers must manually inspect the contact sheet and sign off.

Exit Code	Meaning	Trigger
0	Success	All viewports contained, captures succeeded
1	Failure	Overflow detected or capture failure
2	Skipped	Chrome unavailable

---

Integration with Delivery Workflow

Per the [delivery-contract.md](https://github.com/tt-a1i/archify/blob/main/archify/references/delivery-contract.md#L13-L15) specification, visual-check is designed to run after a successful deliver run. Running it on a failed delivery would incorrectly inspect the previous last-good artifact rather than the broken candidate.

---

Summary

• archify visual-check validates layout containment without modifying artifacts
• Four viewports (1440×900 to 2048×1320) ensure desktop readability coverage
• Eight PNG captures (light/dark at extreme resolutions) provide visual evidence
• Three side-car files — JSON receipt, HTML contact sheet, and screenshots — support automated and manual review workflows
• Three exit codes (0, 1, 2) distinguish pass, fail, and skipped states
• Immutability guarantee: the original HTML is never altered; all evidence lives in side-cars

---

Frequently Asked Questions

How does Archify visual check determine if a layout is contained?

The visual-check command measures the diagram's bounding box at each of four defined viewports in visual-check.mjs. If width or height exceeds the viewport dimensions, containment fails and diagnostics are emitted.

What files does visual-check generate?

The command produces a JSON receipt, an HTML contact sheet, and eight PNG screenshots — all using the naming pattern <artifact>.visual-check.* as defined in the sidecarPaths() function at visual-check.mjs lines 55-74.

Why does visual-check always mark visualReview as pending?

As documented in [SKILL.md](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md#L103-L108), Archify does not make automatic "polish" claims. The "pending" status ensures human reviewers must manually inspect the contact-sheet HTML and screenshots before approving the artifact.

How do I run visual-check without Chrome sandbox?

Set the environment variable ARCHIFY_CHROME_NO_SANDBOX=1 before executing the command. This is required when running as root inside containerized environments.

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