Render Linting Script Checks in Diagram-Design: 8 Automated Validations Explained

The scripts/lint-render.py script performs eight distinct automated checks—including runtime error detection, SVG geometry validation, clipping (spill) detection, and network isolation enforcement—to validate diagram rendering in a headless Chromium environment.

The cathrynlavery/diagram-design repository relies on a comprehensive render linting pipeline to ensure diagrams display correctly across devices. Unlike static analysis tools, this Python script launches a bundled Chromium instance to detect visual regressions and runtime failures that only appear during actual rendering.

The Eight Core Render Linting Script Checks

The validation logic in scripts/lint-render.py executes a battery of tests against each diagram example. These checks target specific failure modes ranging from JavaScript runtime errors to visual overflow artifacts.

1. Runtime Failure Detection

The script attaches Playwright event listeners via the watch() function to intercept three critical error types before any visual validation begins. It monitors pageerror for uncaught exceptions, console for error-level messages, and requestfailed for missing local assets. According to the source code at lines 44–55, any missing-asset event triggers a "missing-asset" finding, while console and page errors are captured to diagnose JavaScript failures during diagram initialization.

2. SVG Geometry Validation

In clipping_findings() (lines 18–22), the script validates that each SVG possesses measurable dimensions. It examines the width and height properties of every SVG entry collected by the survey; if either value is falsy or zero, the script records an "svg-collapsed" finding. This prevents false positives in subsequent spill-detection logic and ensures the viewport is renderable.

3. Unmeasurable Ancestor Detection

Diagrams contained within scrolling ancestors cannot reliably undergo spill detection because the overflow behavior interferes with coordinate measurements. The script detects this condition in lines 31–34 by checking for a blockedBy property in the survey JavaScript output. When a scrolling ancestor blocks measurement, the lint reports "unmeasurable" as a note—categorized separately from failures so it does not trigger a non-zero exit status.

4. Clipping and Spill Detection

The most complex validation occurs in lines 84–100, where the script detects ink spill—pixels that paint outside the intended SVG boundaries or clipping boxes. The compare_release() function orchestrates a staged release of overflow properties:

• It iterates through stages starting with the SVG alone (stage 0) and ascending through each clipping ancestor up to MAX_ANCESTOR_STAGES.
• For each stage, it executes SET_SCALE_JS to normalize dimensions, then runs RELEASE_JS to temporarily remove overflow constraints.
• The shoot() function captures screenshots before and after release, feeding them into DIFF_JS for pixel-level comparison.

The diff logic applies thresholds including CHANNEL_THRESHOLD, MIN_DIFF_PIXELS, and EDGE_GUARD to distinguish legitimate anti-aliasing from actual spills. If the pixel count exceeds MIN_DIFF_PIXELS, the script records a "clipped" finding with side-wise spill distances.

5. Page Overflow Detection

After individual SVG validation, the script checks for horizontal overflow of the entire viewport. The PAGE_OVERFLOW_JS snippet measures the amount of content extending beyond the visible area; if this exceeds the defined TOLERANCE, a "page-overflow" finding is appended to the results (lines 82–88).

6. Network Isolation Enforcement

To ensure CI pipeline security and reproducibility, block_network() (lines 22–31) enforces strict network isolation by aborting any request that is not a local file:// URL, data: URI, or blob:. The optional --fonts flag permits connections to Google Fonts hosts, but all other external traffic—including WebSockets, fetch requests, Server-Sent Events, and images—is blocked. The network_isolation_failures() self-test verifies this enforcement by attempting connections to a local listener and confirming they fail.

7. Gallery Mobile UI Sanity Check

The gallery_mobile_failures() function (lines 70–78) validates mobile rendering specifically for the gallery interface. It verifies three conditions on a 390×844 viewport: the correct example routes properly, the preview iframe maintains adequate height, and no horizontal scroll occurs. This ensures responsive designs behave correctly on mobile devices.

8. Self-Test Verification

The self_test() routine (lines 99–135) runs synthetic fixtures to verify the linting logic itself. It constructs miniature HTML pages simulating specific failure modes—stroke spill, marker spill, filter bleed, clipping wrappers, and scrolling ancestors—then asserts that the script correctly identifies each scenario. This prevents regression in the linting rules and validates that thresholds like MIN_DIFF_PIXELS remain properly calibrated.

How the Render Linting Pipeline Executes

Understanding the execution flow clarifies how these eight checks interact during validation.

Preparation and Isolation

The pipeline begins with launch(), which starts a headless Chromium instance configured with resolver_rule() to block external DNS resolution. Immediately after launch, block_network() installs request interception handlers to enforce the network isolation policy before any navigation occurs.

Survey Phase

Once the page loads, the script injects SURVEY_JS to collect metadata about every <svg> element. This JavaScript gathers bounding boxes, computed overflow settings, and the complete ancestor chain up to the document root, storing them for the clipping analysis phase.

Staged Paint Comparisons

For each identified SVG, the script enters a comparison loop:

1. Scaling: Optionally applies SET_SCALE_JS to normalize the SVG dimensions for consistent pixel comparison.
2. Release: Executes RELEASE_JS to remove overflow restrictions on the target element and its ancestors.
3. Capture: Calls shoot() to capture screenshots before and after the overflow release.
4. Diff Analysis: Runs DIFF_JS to compare images, ignoring the interior of the released bounding box to focus only on external spillage.

Findings Aggregation

After completing staged comparisons for all SVGs, the script aggregates findings. Categories listed in NOTE_CATEGORIES (such as "unmeasurable") are treated as informational notes, while all other findings—including "clipped", "page-overflow", and "missing-asset"—cause the script to exit with a non-zero status, signaling CI failure.

Running the Render Lint Script

The lint-render.py script supports several execution modes for different validation scenarios.

Validate a Single Example

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

This command renders the specified HTML file, prints any findings to stdout, and exits with status 0 if no failures are detected, or 1 if issues are found.

Batch Process All Shipped Assets

python3 scripts/lint-render.py --all

The --all flag expands to every example-*.html and template*.html file returned by shipped_assets(), validating the entire example library in a single invocation.

Execute the Self-Test Suite

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

This mode runs self_test() against synthetic fixtures, outputting a summary such as "self-test OK: 38 cases, no false flags." A successful self-test exits with 0, confirming the linting logic behaves as expected.

Enable Google Fonts for Accurate Text Metrics

python3 scripts/lint-render.py --fonts example-polar.html

The --fonts flag modifies the resolver rules to allow connections to Google Fonts hosts, enabling accurate text measurement while maintaining isolation from all other external resources.

Summary

• The scripts/lint-render.py script performs eight automated checks covering runtime errors, SVG geometry, ancestor scroll blocking, visual spill detection, page overflow, network isolation, mobile UI sanity, and self-test validation.
• Clipping detection uses staged screenshot comparisons with DIFF_JS to identify ink spill outside SVG boundaries, applying thresholds like MIN_DIFF_PIXELS to reduce false positives.
• Network isolation is enforced by block_network() to ensure reproducible, secure CI environments, with optional exceptions only for Google Fonts when using --fonts.
• Findings categorized as notes (e.g., "unmeasurable") do not fail the build, while "clipped", "page-overflow", "missing-asset", and runtime errors trigger non-zero exit codes.
• The script validates both individual files and entire asset libraries, including a comprehensive self-test suite to prevent regression in linting logic.

Frequently Asked Questions

What distinguishes a "clipped" finding from an "unmeasurable" finding?

A "clipped" finding indicates detected ink spill outside the SVG bounds, identified through pixel differencing in compare_release(). An "unmeasurable" finding occurs when a scrolling ancestor blocks measurement, making spill detection impossible. While clipped findings cause lint failures, unmeasurable findings are treated as notes in NOTE_CATEGORIES and do not trigger non-zero exit status.

How does the script prevent external network requests during testing?

The block_network() function intercepts all outbound requests via Playwright's request interception API, aborting any URL that is not file://, data:, blob:, or an allowed Google Fonts host. The network_isolation_failures() self-test verifies this by attempting WebSocket, fetch, and image requests to local listeners and confirming they are blocked.

What triggers a render linting script check to fail the CI pipeline?

Any finding outside the NOTE_CATEGORIES list causes a non-zero exit status. This includes "clipped" (visual spill), "page-overflow" (horizontal scroll), "svg-collapsed" (zero-size viewport), "missing-asset" (failed resource loading), and runtime JavaScript errors captured by the watch() listeners.

How does the spill detection algorithm handle anti-aliasing artifacts?

The DIFF_JS logic applies multiple thresholds to distinguish spill from rendering artifacts: CHANNEL_THRESHOLD filters minor color variations, EDGE_GUARD provides a safety margin around the clipping box, and MIN_DIFF_PIXELS requires a minimum count of differing pixels before reporting a "clipped" finding.

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