Rendered Layout Checking for Diagram Design Compliance: Inside lint-render.py

The scripts/lint-render.py script performs rendered layout checking for Diagram Design compliance by launching a headless Chromium instance via Playwright to detect clipping, overflow, and layout defects invisible to static analysis.

The cathrynlavery/diagram-design repository enforces strict visual standards through both static and dynamic verification. While static analysis validates syntax and geometry, rendered layout checking for Diagram Design compliance requires actually painting the diagram in a browser to catch hidden overflow and clipping errors. The lint-render.py script serves as the authoritative tool for this task, orchestrating a complete browser environment to verify every pixel renders correctly.

The Rendered Layout Checking Pipeline for Diagram Design Compliance

As implemented in lines 1-5 of scripts/lint-render.py, the tool executes a five-stage verification pipeline that transforms static HTML files into visual compliance reports. The script uses Playwright to control a headless browser and injects specialized JavaScript routines to manipulate SVG constraints and measure paint output.

Browser Orchestration with launch()

The process begins with the launch() function (lines 14-20), which starts a bundled Chromium instance with network-resolution rules to isolate the rendering environment. This ensures consistent, reproducible rendering regardless of the host machine's network configuration or installed browsers.

Asset Surveying via SURVEY_JS

Once the page loads, the script injects SURVEY_JS (lines 16-26) to collect every <svg> element in the document. This survey records each SVG's dimensions and traces its chain of clipping ancestors, building a complete map of potential overflow containers that might hide diagram content.

Staged Overflow Release

To expose hidden content, the script executes RELEASE_JS (lines 84-100), progressively releasing overflow constraints. It starts with the SVG itself, then continues up to four nearest clipping ancestors, temporarily expanding each container to reveal any clipped paint that normal viewing would hide.

Pixel-Level Diff with DIFF_JS

After each overflow release, the script captures screenshots and compares them using DIFF_JS (lines 119-140). This custom diff routine counts new ink pixels appearing outside the released box. If new pixels appear, the script reports clipped content, measuring exactly how many pixels are cut off at various zoom levels.

Findings Aggregation

Finally, the script aggregates results (lines 442-454) into categories like "clipped" or "page-overflow", printing a summary indicating how many files were rendered and how many compliance violations were detected.

Running the Rendered Layout Linter

The script supports multiple execution modes for different development workflows. To check all shipped assets in the repository:

python3 scripts/lint-render.py --all

To verify a single diagram file during iterative development:

python3 scripts/lint-render.py skills/diagram-design/assets/example-venn.html

To run the script's internal self-test suite and verify the checker itself:

python3 scripts/lint-render.py --self-test

Typical output identifies specific clipping issues with pixel precision:

example-polar.html: clipped: example-polar.html paints outside its box: left by 3px (12 px of ink cut off at 1x)
example-waterfall.html: page-overflow: page scrolls 5px horizontally at 1600px wide
Summary: 12 file(s) rendered, 3 finding(s), 0 note(s) (not checked, not failed).

Complementary Tools for Diagram Design Compliance

While lint-render.py handles dynamic rendered layout checking, the repository maintains specialized tools for different aspects of compliance verification:

• scripts/verify-geometry.py – Performs static geometry checks such as label-mask clipping without rendering the page. This catches markup-level issues deterministically and runs faster than full browser verification.

• scripts/render-canonical-screenshots.py – Generates reference screenshots used by other verification scripts. It shares the same Playwright setup as the linter but produces baseline images rather than performing comparisons.

• docs/adr/0005-label-geometry-is-verified.md – Documents the architectural decision to maintain both static geometry verification and rendered layout checking, explaining why each approach is necessary for complete Diagram Design compliance.

Summary

• The scripts/lint-render.py file is the authoritative script for rendered layout checking in the Diagram Design repository.
• It launches a headless Chromium instance via Playwright to render diagrams exactly as users see them in production.
• The SURVEY_JS, RELEASE_JS, and DIFF_JS stages progressively expose and measure clipped content with pixel-level accuracy.
• The tool categorizes findings as "clipped" or "page-overflow" and provides precise measurements of how many pixels are cut off.
• It complements static tools like verify-geometry.py to provide complete visual compliance coverage that neither approach could achieve alone.

Frequently Asked Questions

What makes rendered layout checking different from static analysis?

Static analysis examines HTML and SVG markup to detect structural issues, but it cannot determine if content is actually clipped or overflowing when painted. Rendered layout checking launches a real browser, captures screenshots, and compares pixel output to detect visual defects that only appear during actual rendering, such as elements hidden by overflow: hidden containers.

How does lint-render.py detect clipped content in SVG elements?

The script uses a staged approach: first surveying all SVG elements and their clipping ancestors with SURVEY_JS, then progressively releasing overflow constraints on each SVG and up to four parent containers via RELEASE_JS. It captures screenshots before and after each release, using the custom DIFF_JS routine to count new ink pixels. Any new pixels appearing outside the original bounds indicate clipped content.

Can I run the layout checker on a single diagram file instead of the entire repository?

Yes. Instead of using the --all flag, pass the specific HTML file path directly to the command. For example: python3 scripts/lint-render.py skills/diagram-design/assets/example-venn.html. This is useful for rapid iteration when modifying a specific diagram without waiting for the full suite to complete.

What is the relationship between lint-render.py and verify-geometry.py?

verify-geometry.py performs static geometry checks without browser rendering, making it faster for detecting markup-level issues like incorrect label masks. lint-render.py performs the complementary rendered layout checking that requires actual browser painting to catch overflow and clipping. Together, they provide comprehensive compliance verification for Diagram Design standards.

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