Render states and regression

async layoutlens.capture_state(source, *, viewport='desktop', timeout=30000, wait_for_selector=None, revision=None, browser='chromium', color_scheme='light', reduced_motion='reduce', locale='en-US', timezone_id='UTC', device_scale_factor=None)

Capture a URL or HTML source as a portable render state.

Parameters:

• source (str | Path) – URL or local HTML file; screenshot-only inputs are unsupported.

• viewport (ViewportType | tuple[int, int]) – Named browser viewport or (width, height) in CSS pixels.

• timeout (int) – Navigation and readiness timeout in milliseconds.

• wait_for_selector (str | None) – Optional application readiness selector.

• revision (str | None) – Optional source revision recorded for later attribution.

• browser (str) – Local Playwright engine: chromium, firefox, or webkit.

• color_scheme (str) – Emulated light, dark, or no-preference color scheme.

• reduced_motion (str) – Emulated reduce or no-preference motion preference.

• locale (str) – Browser locale.

• timezone_id (str) – Browser timezone.

• device_scale_factor (float | None) – Optional DPR override for the viewport.

Returns:

A versioned render state; use its save method to establish a baseline.

Return type:

RenderState

async layoutlens.capture_page(page, *, source=None, timeout=30000, revision=None, config=None)

Capture an already prepared page without changing its interaction state.

Parameters:

• page (Page) – Playwright page, including any caller-established interaction state.

• source (str | None) – Source label recorded in the artifact.

• timeout (int) – Maximum wait for fonts and images, in milliseconds.

• revision (str | None) – Optional verified source revision label for attribution.

• config (BrowserConfig | None) – Requested emulation settings recorded alongside measured conditions.

Returns:

Browser measurements and screenshot with explicit completeness status.

Return type:

RenderState

layoutlens.diff(before, after, *, tolerance_px=1, policy='qualified', qualifications=None, verifications=None, repository=None)

Compare persisted measurements without a browser or model call.

Parameters:

• before (RenderState) – Baseline render state.

• after (RenderState) – Candidate render state.

• tolerance_px (float) – Significance tolerance for geometric movement in CSS pixels.

• policy (GatePolicy) – Qualified gates by default, explicit findings, or report-only nothing.

• qualifications (list[Qualification] | None) – Independent rule qualification records; none ship by default.

• verifications (list[Verification] | None) – Recorded review or independent evidence for individual findings.

• repository (str | Path | None) – Optional local repository for revision-verified git attribution.

Returns:

Structured observations, candidate regressions, and completeness status.

Return type:

DiffReport

class layoutlens.RenderState(*, schema_version=2, source, environment, graph, capabilities=<factory>, geometry=<factory>, loading=<factory>, accessibility=<factory>, dom='', detector_evidence=<factory>, detector_config=<factory>, rule_version='1', coverage_gaps=<factory>, stable=True, revision=None, screenshot=b'')

A replayable capture with screenshot bytes kept outside its manifest.

Parameters:

• schema_version (Literal[2])

• source (str)

• environment (CaptureEnvironment)

• graph (LayoutGraph)

• capabilities (dict[str, bool])

• geometry (dict[str, float])

• loading (dict[str, Any])

• accessibility (list[dict[str, Any]])

• dom (str)

• detector_evidence (dict[str, Any])

• detector_config (dict[str, Any])

• rule_version (Literal['1'])

• coverage_gaps (list[str])

• stable (bool)

• revision (str | None)

• screenshot (bytes)

property fingerprint: str

Bind review evidence to the exact captured facts and screenshot.

save(directory)

Save a new artifact directory; refuse to overwrite a baseline.

Parameters:

directory (str | Path)

Return type:

Path

classmethod load(path)

Load a versioned artifact and verify every referenced asset.

Parameters:

path (str | Path)

Return type:

RenderState

diff(after, **options)

Compare this baseline with a candidate without opening a browser.

Parameters:

• after (RenderState)

• options (Any)

Return type:

DiffReport

class layoutlens.DiffReport(*, schema_version=1, before, after, matches=<factory>, deltas=<factory>, incomplete_reasons=<factory>, policy='qualified', tolerance_px=1, explanation=None)

Structured comparison whose gate status never depends on prose.

Parameters:

• schema_version (Literal[1])

• before (str)

• after (str)

• matches (list[Correspondence])

• deltas (list[VisualDelta])

• incomplete_reasons (list[str])

• policy (Literal['qualified', 'findings', 'nothing'])

• tolerance_px (float)

• explanation (str | None)

property gate_status: Literal['pass', 'fail', 'incomplete']

Distinguish missing evidence from a successful comparison.

to_json()

Serialize evidence and the derived gate status.

Return type:

str

summary()

Describe the result without interpreting observations as defects.

Return type:

str

class layoutlens.VisualDelta(*, element, before_element=None, after_element=None, before_bbox=None, after_bbox=None, changed_properties=<factory>, pixel_region=<factory>, measured_delta=<factory>, defect_class=None, evidence=<factory>, severity='note', level='observation', status='changed', likely_source=<factory>, gateability=<factory>)

Measured change, diagnosis, and independently evaluated gate decision.

Parameters:

• element (str)

• before_element (str | None)

• after_element (str | None)

• before_bbox (tuple[float, float, float, float] | None)

• after_bbox (tuple[float, float, float, float] | None)

• changed_properties (dict[str, Any])

• pixel_region (dict[str, Any])

• measured_delta (dict[str, Any])

• defect_class (str | None)

• evidence (dict[str, Any])

• severity (Literal['note', 'warning', 'error'])

• level (Literal['observation', 'candidate', 'verified', 'gateable'])

• status (Literal['changed', 'introduced', 'worsened', 'unchanged', 'resolved', 'unresolved'])

• likely_source (list[dict[str, Any]])

• gateability (dict[str, Any])

class layoutlens.Qualification(*, rule, rule_version, configuration, conditions, dataset_sha256, independent, sealed, true_positives, false_positives, provenance)

Independent, sealed precision evidence for one versioned rule.

Parameters:

• rule (str)

• rule_version (str)

• configuration (dict[str, Any])

• conditions (dict[str, Any])

• dataset_sha256 (str)

• independent (bool)

• sealed (bool)

• true_positives (int)

• false_positives (int)

• provenance (str)

property precision_interval: tuple[float, float]

Return the two-sided 95% Wilson interval, including empty samples.

qualifies(rule, version, configuration, conditions)

Require exact rule/configuration and applicable capture conditions.

Parameters:

• rule (str)

• version (str)

• configuration (dict)

• conditions (dict)

Return type:

bool

class layoutlens.Verification(*, state_sha256, rule, selector, evidence, reviewer, resolved_exceptions=<factory>, independent_support=False)

Auditable exception resolution or independent support for one finding.

Parameters:

• state_sha256 (str)

• rule (str)

• selector (str)

• evidence (str)

• reviewer (str)

• resolved_exceptions (list[str])

• independent_support (bool)

supports(finding, state_sha256)

Require complete exception resolution and recorded supporting evidence.

Parameters:

• finding (dict)

• state_sha256 (str)

Return type:

bool