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

> Master Archify visual check options for containment, capture, and contact sheets. Validate layouts, generate screenshots, and review artifacts efficiently with this powerful command.

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

---

**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](https://github.com/tt-a1i/archify) repository is a post-delivery quality gate designed for deterministic visual validation. As implemented in [`archify/bin/visual-check.mjs`](https://github.com/tt-a1i/archify/blob/main/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.

```bash

# 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`](https://github.com/tt-a1i/archify/blob/main/archify/bin/archify.mjs#L56-L63), 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`](https://github.com/tt-a1i/archify/blob/main/archify/bin/visual-check.mjs#L12-L17):

| 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](https://github.com/tt-a1i/archify/blob/main/archify/bin/visual-check.mjs#L609-L656) 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`](https://github.com/tt-a1i/archify/blob/main/archify/bin/visual-check.mjs#L19-L23):

- **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`](https://github.com/tt-a1i/archify/blob/main/archify/bin/visual-check.mjs#L7-L38):

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](https://github.com/tt-a1i/archify/blob/main/archify/bin/visual-check.mjs#L55-L74) creates three output types with the base name `<artifact>.visual-check`:

| Side-car Type | File Extension | Purpose |
|---------------|---------------|---------|
| JSON receipt | [`.visual-check.json`](https://github.com/tt-a1i/archify/blob/main/.visual-check.json) | Machine-parseable validation results |
| Contact sheet | [`.visual-check.html`](https://github.com/tt-a1i/archify/blob/main/.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`](https://github.com/tt-a1i/archify/blob/main/archify/bin/visual-check.mjs#L567-L573). 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/SKILL.md)](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md#L103-L108), the JSON receipt contains:

```json
{
  "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/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`](https://github.com/tt-a1i/archify/blob/main/archify/bin/visual-check.mjs#L609-L656). 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](https://github.com/tt-a1i/archify/blob/main/archify/bin/visual-check.mjs#L55-L74).

### Why does visual-check always mark visualReview as pending?

As documented in [[`SKILL.md`](https://github.com/tt-a1i/archify/blob/main/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.