# Archify Validator: Preventing Arrows Crossing the Legend

> Learn how the Archify validator prevents arrows crossing the legend in rendered diagrams. It stops renders with collisions, ensuring visual clarity.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: internals
- Published: 2026-07-12

---

**The Archify validator rejects any rendered diagram where arrows intersect the legend area, ensuring visual clarity by aborting the render with a non-zero exit code when collisions are detected.**

The **Archify validator** is a post-render artifact checker in the `tt-a1i/archify` repository that enforces diagram quality standards. One of its critical safeguards, the **`legend_clearance`** check, specifically prevents arrows from obscuring legend text or symbols in the final SVG output. This validation step runs automatically after rendering to guarantee that workflow, architecture, sequence, and other diagram types remain readable and professionally formatted.

## How the Legend Clearance Validator Works

The validation logic in `scripts/check-render-output.mjs` implements a geometric collision detection system that compares arrow segments against legend bounding boxes.

### Extracting and Parsing the SVG

The validator first locates the single `<svg>` element within the generated HTML file using the `single_svg` check. It then scans for all arrow elements—specifically `<path>` or `<line>` elements carrying Archify arrow classes (`a-default`, `a-emphasis`, `a-security`, `a-dashed`) that include a `marker-end` attribute. The `collectArrows` function decomposes each arrow into discrete line segments for intersection testing.

### Building Bounding Boxes for Collision Detection

The script identifies the legend region by searching for the HTML comment `<!-- Legend -->`. From that anchor point, it gathers all `<rect>` and `<text>` elements belonging to the legend via the `collectLegendBoxes` function, converting each into bounding box coordinates. Simultaneously, the renderer files like `renderers/workflow/render-workflow.mjs` calculate the legend’s vertical position using the `legendY()` function, ensuring the legend sits below the last lane to establish a predictable rectangular region.

### The Collision Detection Algorithm

Each arrow segment is tested against every legend bounding box using the `segmentIntersectsBox` utility. If `collectLegendCollisions` detects any intersection, the validator records a `legend_clearance` failure listing the specific path and the coordinates of the violated legend element. The check produces a JSON report where `"ok": false` for the `legend_clearance` entry triggers a non-zero exit code, halting the pipeline.

```json
{
  "ok": false,
  "file": "output.html",
  "checks": [
    { "name": "single_svg", "ok": true, "details": [] },
    { "name": "finite_svg", "ok": true, "details": [] },
    { "name": "orthogonal_arrows", "ok": true, "details": [] },
    {
      "name": "legend_clearance",
      "ok": false,
      "details": [
        "path 1 crosses legend rect@40,132"
      ]
    }
  ]
}

```

## Running the Validator Manually

You can execute the post-render checker independently from the command line to verify existing HTML files.

```bash
node scripts/check-render-output.mjs workflow.html

```

Successful validation returns a JSON object with all checks marked `true`:

```json
{
  "ok": true,
  "file": "/tmp/workflow.html",
  "checks": [
    {"name":"single_svg","ok":true,"details":[]},
    {"name":"finite_svg","ok":true,"details":[]},
    {"name":"orthogonal_arrows","ok":true,"details":[]},
    {"name":"legend_clearance","ok":true,"details":[]}
  ]
}

```

When `legend_clearance` fails, the output includes specific collision details such as `"path 1 crosses legend rect@40,132"`, allowing you to pinpoint exactly which arrow violates the legend boundary.

## Fixing Legend Crossing Issues

When the validator rejects a diagram due to arrow-legend collisions, you must adjust the layout to reroute the offending arrow.

### Increasing Lane Gaps

In `renderers/workflow/render-workflow.mjs`, modify the `layout.laneGap` property to increase vertical spacing between lanes, providing room for horizontal arrows to traverse without intersecting the legend positioned below:

```javascript
const layout = {
  laneX: 40,
  laneY: 52,
  laneW: 640,
  laneH: 104,
  laneGap: 30,   // Increase from 20 to 30
  // ...
};

```

After adjusting the layout and re-rendering, rerun `node scripts/check-render-output.mjs` to confirm the `legend_clearance` check passes.

## Summary

- The **`legend_clearance`** check in `scripts/check-render-output.mjs` detects arrows that intersect legend bounding boxes and aborts the render with a non-zero exit code.
- The validator identifies arrows by their CSS classes (`a-default`, `a-emphasis`, `a-security`, `a-dashed`) and marker attributes, then tests line segments against legend `<rect>` and `<text>` elements.
- Renderer files like `renderers/workflow/render-workflow.mjs` position the legend below the diagram using `legendY()`, establishing a known rectangular safe zone.
- You can manually trigger validation via the CLI, and failures report specific coordinates like `"path 1 crosses legend rect@40,132"`.
- Increasing `layout.laneGap` in the renderer configuration is the primary method to resolve collisions and achieve clean diagram output.

## Frequently Asked Questions

### What triggers the legend_clearance check in Archify?

The `legend_clearance` check triggers whenever any arrow segment—defined as a `<path>` or `<line>` with Archify arrow classes and a `marker-end` attribute—intersects a bounding box constructed from legend `<rect>` or `<text>` elements. The check runs automatically as part of the post-render validation pipeline in `scripts/check-render-output.mjs`.

### How does the Archify validator detect arrows crossing the legend?

The validator uses the `collectArrows` function to extract line segments from arrow elements and `collectLegendBoxes` to build bounding boxes from elements following the `<!-- Legend -->` comment. It then applies the `segmentIntersectsBox` algorithm to test for geometric collisions, recording failures via `collectLegendCollisions`.

### Can I disable the legend clearance check in Archify?

No, the `legend_clearance` check is a mandatory quality gate in the Archify validation pipeline. If the check fails, the validator returns a non-zero exit code and aborts the process, forcing you to fix the diagram layout rather than bypass the validation.

### Which renderers in Archify support legend clearance validation?

All Archify renderers support legend clearance validation because they share the same post-render validation pipeline. The `renderers/workflow/render-workflow.mjs`, `renderers/architecture/render-architecture.mjs`, and `renderers/sequence/render-sequence.mjs` files each implement legend positioning logic (via functions like `legendY()`) that works in conjunction with the validator in `scripts/check-render-output.mjs`.