Archify Validator: Preventing Arrows Crossing the Legend

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.

{
  "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.

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

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

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

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.

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