LayoutLens: Measured UI Regressions

LayoutLens captures browser evidence, matches elements across versions, and reports measured layout changes with candidate DOM/CSS causes. Capture and diff run locally without an API key. Model explanation is optional.

import asyncio
from layoutlens import capture_state, diff


async def main():
    before = await capture_state("before.html")
    after = await capture_state("after.html")
    before.save("artifacts/baseline")
    after.save("artifacts/candidate")
    report = diff(before, after)
    print(report.to_json())


asyncio.run(main())

Create the two HTML files before running this example. Each save() writes a new artifact directory and refuses to overwrite an existing baseline.

A RenderState contains the screenshot, DOM structure, computed styles, geometry, accessibility roles/names, text rectangles, focus/interaction information, loading state, browser conditions, and replayable detector evidence. Its graph records containment, alignment, overlap, adjacency, proximity, and geometric reading order.

VisualDelta records before/after boxes, changed properties, numeric deltas, image regions, correspondence evidence, candidate defect class, source attribution, and gate policy. Saved artifacts can be compared offline.

Evidence level	Meaning
Observation	A measured browser fact or rendered change
Candidate	A measurement matches a defect predicate
Verified	Recorded exception resolution or independent evidence supports the finding
Gateable	An applicable independent precision evaluation qualifies the rule

Default CI blocking requires a sealed independent evaluation whose 95% Wilson precision interval has a lower bound of at least 99%. The evaluation must match the rule version, detector configuration, and capture conditions. Its record includes the dataset hash, provenance, and evaluation counts. No layout rules ship with qualifying evidence yet. Candidates remain warnings; policy="findings" explicitly opts into strict blocking. An incomplete comparison never reports a passing gate.

Axe accessibility rule outcomes remain separately identified. Standalone layout scans and optional hybrid model analysis also retain candidate findings without equating deterministic measurement with proven defects.

The bundled model benchmark recorded 60 correct answers out of 74 labeled queries (81.1%, gpt-4o-mini, 2026-07-21). That result measures single-page questions, not the accuracy of the regression engine. The benchmark section links the recorded results and scoring method.

Quick Start

Installation

Requires Python 3.12 or newer.

pip install layoutlens
playwright install chromium  # For screenshot capture

Capture and compare

layoutlens capture before.html --save artifacts/baseline
layoutlens capture after.html --save artifacts/candidate
layoutlens diff artifacts/baseline artifacts/candidate --output json

These commands use Chromium by default and need no model API key. Diff exits with 0 for a passing gate, 1 for a blocking finding, and 2 for incomplete evidence or an execution error. Candidates warn by default; add --fail-on findings to block introduced or worsened candidates without upgrading their evidence level.

Python capture and analysis methods are async. The opening example uses asyncio.run(...); the remaining Python examples assume an async function or a notebook that supports await.

Deterministic Accessibility Checks (axe-core) — No API Key Required

LayoutLens runs vendored axe-core 4.10.3 against a Playwright-rendered page. It reports outcomes from automated WCAG A/AA rules without an API key. A passing scan means those rules found no violations; it does not establish WCAG conformance.

CLI

# Deterministic axe-core scan only — no API key needed
layoutlens page.html --a11y axe

# Hybrid: axe-core + LLM vision, axe overrides the verdict on violations (needs an API key)
layoutlens https://example.com --a11y hybrid

# Legacy vision-only accessibility check (needs an API key)
layoutlens page.html --a11y llm

--a11y requires one of hybrid/axe/llm and is mutually exclusive with --query — accessibility mode always uses the built-in WCAG checks instead of a free-form question.

Python

from layoutlens import LayoutLens, AxeAuditor

# Raw axe-core report — no LayoutLens instance or API key needed at all
report = await AxeAuditor().audit("page.html")
print(report.summary())
print(report.ok)  # True if there are zero violations
print(report.violations)  # list[A11yFinding]: rule_id, impact, wcag_refs, nodes, ...

# Via the LayoutLens API, restricted to WCAG A/AA tags, still keyless
lens = LayoutLens()  # no API key required at construction
result = await lens.check_accessibility("page.html", mode="axe")
print(
    result.answer
)  # "Yes — axe-core found no WCAG A/AA violations" (or lists violated rules)

This is the beginning of the README. Read the rest at the original. Read the full README ↗