Introducing a new way to review your PRs.

Read the announcement

pbakaus / impeccable

The design vocabulary for your coding agent. Steer with polish and bolder, review with critique and audit, catch AI slop before it ships.

View on GitHub

32 documents · Updated Nov 20, 2026

docs / browser-analysis-runtime

Browser analysis runtime

The browser analysis runtime measures a page in the state a user can see and sends those facts to the shared detector core. It supports direct in-page scans and snapshot-based scans, so the same browser rules can run even when page security policy blocks WebAssembly.

Runtime model

Analysis paths

The runtime has two paths that share one rule model. The in-page path measures the live DOM and calls the WebAssembly core in the page. The snapshot path measures the page first, then runs the same core over serialized facts in a native process or an extension offscreen document.

The following diagram shows how both paths turn page state into findings:

flowchart LR
    A[Rendered page] --> B{Runtime path}
    B -->|In-page| C[DOM probe]
    B -->|Snapshot| D[Page snapshot]
    C --> E[DOM abstraction]
    D --> F[Snapshot abstraction]
    E --> G[WebAssembly rule core]
    F --> G
    G --> H[Element and page findings]
    H --> I[Overlay, extension, CLI, or JSON]

The snapshot path keeps page measurement separate from rule decisions. This makes the runtime safe for strict-CSP pages and keeps the browser page passive during URL scans.

References: browser-bundle/README.md• L3-23 crates/…/snapshot_engine.rs• L1-25 crates/…/dom_source.rs• L1-6

Browser session

The browser session is the page boundary for URL and attached-page scans. It can start an isolated headless Chrome or connect to an existing DevTools browser, then expose navigation, frame state, page evaluation, screenshots, and page errors to the analysis flow. An attached page stays under its owner's control, while scan evaluation uses a document-bound isolated world that ends when the document changes.

This boundary lets the runtime inspect a real rendered page without giving the scan control of an existing application window. It also keeps navigation and frame changes visible to the capture process, so findings are tied to the document that was actually measured.

References: crates/…/cdp.rs• L124-126 crates/…/cdp.rs• L292-365 crates/…/cdp.rs• L744-768 crates/…/cdp.rs• L1434-1464

Bundled runtime

The browser bundle is the page-side runtime. Its probe measures the page, its snapshot producer creates a reusable capture, its visual adapter reads pixels, and its scan API joins those measurements with findings. The bundle does not define design rules; it delegates those decisions to the shared core.

The bundle serves several consumers:

  • the in-page detector, which runs the core beside the page;
  • the URL engine, which injects the snapshot producer and runs the core outside the page; and
  • the extension, which captures in a content script and runs the core in an offscreen document.

The bundle builder fixes the file order and embeds the matching WebAssembly glue and module. A change to a page-side file therefore changes all consumers that receive that generated artifact.

References: browser-bundle/README.md• L1-35 crates/…/lib.rs• L1-10 crates/…/lib.rs• L39-61 crates/…/lib.rs• L77-103

Page measurement

DOM abstraction

The DOM abstraction gives the rule core a small, stable view of a browser page. It exposes document structure, selectors, attributes, text, computed styles, geometry, visibility, media state, animation state, and hit-test results without placing rule logic in JavaScript.

In the live path, elements travel across the boundary as handles. The probe maps each handle to a real element and caches repeated reads during one core call. The core sees the same Dom contract whether the source is a live page or a snapshot.

References: browser-bundle/10-probe.js• L1-43 browser-bundle/10-probe.js• L104-187 crates/…/js_dom.rs• L1-12 crates/…/js_dom.rs• L111-138

CSS abstraction

The CSS abstraction represents the styles that affect rendered behavior rather than only the styles written in source. It reads computed properties for each element, pseudo-element styles when they paint content, active state pseudo-classes, keyframes, linked stylesheet rules, and font use.

This view lets the detector reason about the final cascade and about CSS that is active on the page. Linked rules enter the browser pattern view only when they resolve to live elements, while conditional rules and animation data preserve the page state seen at capture.

References: browser-bundle/15-snapshot.js• L19-71 browser-bundle/15-snapshot.js• L483-570 browser-bundle/15-snapshot.js• L656-681 crates/…/snapshot.rs• L11-24

Snapshot abstraction

The snapshot abstraction is a bounded, JSON form of the measured page. It stores the element tree, text, attributes, selected computed styles, pseudo-elements, geometry, visibility, media facts, viewport state, fonts, animations, linked CSS, and open shadow trees.

The capture has limits for element count and byte size. It also records which facts are not available from a static capture. Hit tests are requested by the core and answered from the live page before the scan continues, so the snapshot remains a stable view while runtime-only questions still use the real page.

References: browser-bundle/15-snapshot.js• L73-74 browser-bundle/15-snapshot.js• L754-979 crates/…/snapshot.rs• L26-41 crates/…/dom_source.rs• L66-123

Inspector capture

Inspector capture supplements the page-side view with browser layout data that page selectors cannot always expose. It can count native nodes across closed shadow roots and find the layout boxes of generated pseudo-elements, while a capture stylesheet provides a controlled place for temporary inspection styles.

This second view helps the runtime measure what the browser lays out without treating hidden trees as absent. It is used for targeted rendered evidence rather than as a replacement for the shared DOM abstraction.

References: crates/…/cdp.rs• L1467-1499 crates/…/cdp.rs• L1501-1516 crates/…/cdp.rs• L1519-1583

WebAssembly integration

Shared rule core

The WebAssembly module is the decision layer for browser analysis. It receives the DOM abstraction, applies browser checks, groups findings by element or page, and serializes the shared finding shape for each consumer.

The JavaScript runtime supplies measurement and transport. The WebAssembly exports supply finding collection, serialization, hidden-text measurement, and visual-contrast decisions. This split keeps thresholds and rule meaning aligned across the page, extension, and URL paths.

References: crates/…/lib.rs• L1-18 crates/…/lib.rs• L41-75 crates/…/exports_driver.rs• L9-40 crates/…/exports_visual.rs• L31-43

CSP-safe execution

The extension avoids running WebAssembly in the page. Its content script captures the page and answers live hit-test and image-pixel questions. An offscreen document hosts the core and continues the scan through a request-and-answer session.

The URL engine uses the same idea without loading the detector module next to the page. It injects only the plain snapshot producer, then runs the core over SnapshotDom in the native browser engine. This preserves the page's own content-security policy and avoids changing the page to make analysis possible.

References: extension/…/content-script.js• L1-17 browser-bundle/60-offscreen.js• L1-30 browser-bundle/60-offscreen.js• L64-105 crates/…/snapshot_engine.rs• L1-25 crates/…/cdp.rs• L875-903

Rendered-page evidence

Runtime state evidence

Rendered-page detection combines structure with the state that controls what a visitor sees. The core can use visibility, effective opacity, clipping, document bounds, text rectangles, scroll metrics, animation state, media readiness, and shadow-tree links to separate active content from authored but unpainted content.

The browser pass also uses page relationships. It can inspect headings, text flow, nested surfaces, viewport overflow, occlusion, and other page-level facts that are not reliable from isolated source text.

References: crates/…/mod.rs• L43-76 crates/…/driver.rs• L41-64 crates/…/painted.rs• L2378-2420 crates/…/page_checks.rs• L203-315

Hit-test evidence

Hit tests show which elements are at points on the rendered surface. The runtime uses them for text coverage, occlusion, and visual background work. A live page answers these points with elementFromPoint and elementsFromPoint; a snapshot records the questions and pauses until the page supplies the answers.

This evidence is deliberately separate from the snapshot's tree and styles. A node can exist in the DOM and have a valid computed style while another painted layer covers it.

References: browser-bundle/10-probe.js• L119-128 browser-bundle/15-snapshot.js• L986-999 browser-bundle/60-offscreen.js• L73-105 crates/…/snapshot.rs• L26-36

Pixel evidence

Pixel evidence resolves surfaces that CSS values cannot describe well. The visual pass can load images, draw them to a canvas, read sample points, and combine translucent layers. The core decides which text is a candidate, where to sample, how to combine samples, and whether the result is a finding.

If an image is unavailable, cross-origin data cannot be read, or a canvas cannot provide pixels, the runtime reports an unresolved result instead of treating the surface as safe. Content outside the viewport can be retried when it enters view.

References: browser-bundle/35-visual.js• L1-35 browser-bundle/35-visual.js• L57-156 browser-bundle/15-snapshot.js• L684-747 browser-bundle/30-scan-common.js• L9-26

Detection evidence

The rendered scan returns findings grouped by their element plus page-level findings. The browser-facing runtime can serialize these results for JSON or an extension panel, while the overlay uses the same groups to mark the page.

URL analysis can retain a scan snapshot and the facts used to answer it. Its evidence record can also include element rectangles, element details, transient or moved targets, page anchors, and an optional screenshot. These records help a reviewer compare a finding with the rendered state that produced it.

The browser session also retains a bounded set of distinct uncaught page errors with a source location when the browser provides one. These diagnostics show when page code affected the capture without allowing an error flood to stop the analysis.

References: browser-bundle/50-scan.js• L60-95 browser-bundle/50-scan.js• L119-137 crates/…/lib.rs• L340-413 crates/…/lib.rs• L655-698 crates/…/cdp.rs• L1084-1109 crates/…/cdp.rs• L1836-1840 crates/…/cdp.rs• L1889-2164

Page validity evidence

The URL runtime checks whether the loaded page represents the site before it reports design findings. A bot challenge, block page, HTTP error page, or blocking overlay can make the rendered state unrelated to the target site, so the runtime records the validity result and can return no findings for that page.

This gate prevents downstream systems from treating challenge-page styles or error-page layout as evidence about the product under review.

References: crates/…/validity.rs• L1-18 crates/…/validity.rs• L306-359 crates/…/lib.rs• L655-659

Capture state

Capture state controls whether two observations describe the same rendered conditions. The browser can pin the page clock, set the viewport and reduced-motion preference, wait for the requested document lifecycle across child frames, and capture either the current viewport or a document region without changing an attached page's window.

These controls make screenshots and layout facts comparable across scans. They also limit the risk that navigation, responsive layout, or animation changes the page between measurement steps.

References: crates/…/cdp.rs• L1242-1429 crates/…/cdp.rs• L1261-1299 crates/…/cdp.rs• L1692-1834

The runtime is one evidence surface in the wider detector. UI quality detection system explains how browser results fit with source and static HTML analysis. Detector analysis pipeline explains target routing and result processing. Detection engines and antipattern rules explains the rule and evidence boundary. Design system profiling explains how project context changes rendered-value checks.

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep the live DOM probe and snapshot fields aligned with the shared Dom contract.
  • Keep the computed-style property lists aligned between the page snapshot and the Rust snapshot reader.
  • When a rule reads a new browser fact, add its live and snapshot behavior together and check the unknown-fact path.
  • Keep in-page and offscreen visual I/O aligned for image loads, canvas reads, hit tests, and unresolved results.
  • When bundle files change, preserve the embedded file list and concatenation order for all generated consumers.
  • When snapshot limits or element links change, check shadow-tree, slot, text-rect, and media handling in both capture paths.
  • When validity or evidence fields change, keep blocked-page behavior distinct from ordinary scan findings.
  • When browser session modes change, preserve ownership rules for launched and attached pages and invalidate capture contexts after navigation.
  • When frame lifecycle or page-error handling changes, keep child-frame progress visible and diagnostics bounded during long scans.

Important failure modes

TriggerConsequenceGuard
The snapshot style list and the core style contract driftSnapshot scans answer some CSS reads as empty and can under-report findingsKeep the two property lists checked together and inspect unknown-style diagnostics
A page exceeds the snapshot element or byte limitThe scan stops before the core receives a complete page viewIncrease the route's capture budget or use a smaller target; do not treat capture failure as a clean scan
The page CSP blocks the in-page WebAssembly coreIn-page detector calls fail before findings are collectedUse the snapshot path with the content script and offscreen or native core
A hit test or pixel read cannot be answeredOcclusion or visual contrast stays unresolvedPreserve the unresolved result and avoid converting missing evidence into a pass
A stale scan session answers a newer scanFindings or overlays can describe an older DOM stateSupersede the old session and keep scan generations separate
The loaded page is a challenge or error pageFindings describe the block or error surface instead of the target siteApply the page-validity gate before reporting rendered findings
The document navigates or its frame is replaced during isolated captureThe capture context no longer describes the page being measuredReject the old context and start a new capture for the current document
A page emits uncaught errors without endDiagnostic storage can grow or protocol work can starve the scanDeduplicate errors, cap retained diagnostics, and handle events while commands are in flight

Key files

FileWhy to read it
browser-bundle/README.mdGives the bundle boundary, consumers, build relationship, and probe rules.
browser-bundle/10-probe.jsShows the live DOM measurement contract used by the core.
browser-bundle/15-snapshot.jsShows the page capture and the live I/O needed by snapshot scans.
browser-bundle/35-visual.jsShows how browser I/O supports visual contrast without owning rule decisions.
browser-bundle/50-scan.jsShows the in-page scan API and the bridge from core results to page consumers.
browser-bundle/60-offscreen.jsShows the CSP-safe extension session and snapshot-based core execution.
crates/…/js_dom.rsDefines the live-page adapter for the shared DOM contract.
crates/…/dom_source.rsShows how the same exports switch between live and snapshot probes.
crates/…/snapshot.rsDefines the serialized page view and its missing-fact model.
crates/…/mod.rsMaps the browser rule modules and the shared evidence responsibilities.
crates/…/cdp.rsDefines the browser session boundary, lifecycle tracking, native capture, screenshots, and page diagnostics.
crates/…/snapshot_engine.rsShows the URL engine's passive snapshot capture and runtime fact collection.
crates/…/lib.rsDefines the evidence returned with rendered-page findings.
extension/…/content-script.jsShows how the extension captures, answers runtime questions, and presents results.