4.1 Stage 1: Deterministic DOM Geometry Gate

chinwag ui-gate --url http://localhost:8080 --surfaces 16

✅ Available Now (v0.1.0 · CHWG-PUB-105): Stage 1 (verify-ui-geometry.py · 176/176 deterministic 12-tuple DOM physics assertions across 8 viewports and 2 color themes in <900ms at 0 Credits) is shipped and verified in v0.1.0. See /api/reality-matrix and the Chinwag Public Roadmap.

AI coding agents write valid JSX, Vue, and CSS that compiles without warnings and passes unit tests · yet renders broken layouts in a real browser. Hero headings wrap to four lines at 1024px, navigation pills collide on 768px tablets, sticky topbars obscure anchor targets, and light-mode muted text drops below WCAG AA contrast.

chinwag ui-gate solves this with a three-stage visual verification pipeline (WP-12). Stage 1 runs locally inside headless Chromium in under 900ms at 0 Cr (free), evaluating 11 deterministic DOM physics invariants across 8 standard viewports and 2 color themes (Midnight + Daylight) = 176 / 176 cell assertions.

chinwag ui-gate --url http://localhost:3000 --matrix 8x2 --stage 1

The 12-Tuple DOM Element Descriptor

Before evaluating layout invariants, Stage 1 injects a zero-dependency measurement probe into the live Chromium layout tree (document.querySelectorAll('*')) and extracts a compact 12-tuple geometric descriptor for every visible interactive, typographic, and container node:

pub struct DomGeometryTupleV1 {
    pub selector_hash: u64,          // 1. Canonical CSS path hash (BLAKE3-64)
    pub role_class: ElementRoleV1,   // 2. Heading | Body | Interactive | Nav | Sticky | Card | Media
    pub x: f32,                      // 3. Sub-pixel clientRect.left
    pub y: f32,                      // 4. Sub-pixel clientRect.top
    pub width: f32,                  // 5. Sub-pixel clientRect.width
    pub height: f32,                 // 6. Sub-pixel clientRect.height
    pub scroll_width: f32,           // 7. scrollWidth (horizontal overflow detector)
    pub line_box_count: u16,         // 8. Exact rendered text line count via getClientRects()
    pub font_size_px: f32,           // 9. Computed font-size in CSS pixels
    pub contrast_apca_wcag: f32,     // 10. Effective foreground/background WCAG 2.2 contrast ratio
    pub z_stack_tier: i32,           // 11. Effective stacking context & z-index tier
    pub hit_target_min_px: f32,      // 12. Minimum interactive touch/click dimension (min(w, h))
}

The 8 × 2 Viewport & Theme Matrix (16 Render Surfaces)

Every run sweeps 8 canonical device viewports across both Midnight (dark) and Daylight (light) color schemes:

The 11 Deterministic Invariants (16 Surfaces × 11 Invariants = 176/176)

For each of the 16 viewport-theme surfaces, Stage 1 verifies all 11 mathematical invariants:

Stage 1 CLI Output Example

When a layout bug occurs on a single breakpoint, chinwag ui-gate pinpoints the exact selector, viewport, theme, and sub-pixel coordinates:

$ chinwag ui-gate --url http://localhost:3000/pricing --stage 1
[ui-gate] Sweeping 8 viewports × 2 themes (16 surfaces × 11 invariants = 176 checks)...
  ✗ FAIL [GEO-01-ZERO-HORIZ-BLEED] at V8_MOBILE_SE (375×812 · Daylight)
    Selector: section.pricing-matrix > table.credit-schedule
    Measured: document.scrollWidth = 442px > window.innerWidth = 375px (+67px overflow)
  ✗ FAIL [GEO-06-CONTRAST-FLOOR] at V2_DESKTOP (1440×900 · Daylight)
    Selector: .tier-card .muted-footnote
    Measured: contrast = 3.41:1 < 4.50:1 required (#7A8291 on #F4F2ED)
[ui-gate] Result: 174/176 PASSED (2 deterministic geometry failures in 640ms · 0 Cr)

Next Step: Multimodal Vision-3 Inspection & Auto-Patch

Once Stage 1 (176/176) passes, chinwag ui-gate advances to Stage 2 and Stage 3 (Chinwag Vision-3 visual geometry audit and CSS auto-patch synthesis).

• Next: Stage 2 & 3: Chinwag Vision-3 Visual Geometry & CSS Auto-Patch
• Ready to automate UI verification across your repo? Reserve Your Organization Credit Pack →