Skip to content

The design language that makes your AI harness better at design.

JavaScript

Say which screenshot-contrast verdict the Rust engine uses

Paul Bakausd38ca3fa681c
diff --git a/docs/CLI-CONTRACT.md b/docs/CLI-CONTRACT.md
index 5afb6fe18..df4cdb39a 100644
--- a/docs/CLI-CONTRACT.md
+++ b/docs/CLI-CONTRACT.md
@@ -326,7 +326,7 @@ Optional keys added later by engines (appended after the above): `ignoreValue` (
- Launch: `launchArgs = process.env.CI ? ['--no-sandbox','--disable-setuid-sandbox'] : []`. On `win32` first `puppeteer.launch({channel:'chrome', headless, args})`, on failure fall back to bundled `puppeteer.launch({headless, args})` with `err.cause = channelError`. Non-Windows: bundled only.
- Flow: `newPage` → attach `pageerror` listener (message first line, trimmed, sliced to 160 chars, deduped) → `setViewport(viewport)` → `page.goto(url, {waitUntil, timeout: 30000})` → optional settle → `page.evaluate` sets `window.__IMPECCABLE_CONFIG__ = {...existing, autoScan:false, ...(designSystem ? {designSystem} : {})}` where designSystem serialized as `{present:true, hasFonts, allowedFonts:[...], hasColors, allowedColors:[{r,g,b}], hasRadii, allowedRadii:[px], hasPillRadius}` → `page.evaluate(browserScript)` (injects the bundle; defines `window.impeccableDetect/impeccableDetectAsync/impeccableScan/impeccableScanAsync/impeccableMeasureHiddenText/impeccableCollectVisualContrastCandidates/impeccableAnalyzeVisualContrast/impeccableGetLastVisualContrastAnalyses`) → `window.impeccableDetect({decorate:false, serialize:true})` returns groups `[{selector, tagName, rect, isPageLevel, isHidden, findings:[{type, category, severity, advisory, detail, ignoreValue, name, description}]}]`; flattened to `{id:type, snippet:detail, ignoreValue, severity}` → content-hidden sweep (`measureContentHiddenAfterReveal`: scroll in steps `max(200, floor(innerHeight*0.7))` with `behavior:'instant'`, 40ms rAF pauses, back to top, wait 700ms, then `impeccableMeasureHiddenText()`; `checkContentHiddenAtRest` fires when `totalChars>=200 && hiddenChars>=150 && share>0.3`, snippet `${pct}% of page text (${hidden} of ${total} chars) stays at opacity 0 / visibility hidden after reveal handlers ran (e.g. "sample")`) → up to 3 `script-error` findings `{id:'script-error', snippet:message}` → visual contrast fallback → `finally` close page (and browser if owned).
- Visual contrast fallback (`runVisualContrastFallback`): browser-side `impeccableAnalyzeVisualContrast({maxCandidates, scrollOffscreen})` findings not already low-contrast on that selector; then candidates (from analyses or `impeccableCollectVisualContrastCandidates`) not resolved pass/fail → per candidate `captureVisualContrastCandidate(page, candidate, viewport)`.
-- **Screenshot flow** (`screenshot-contrast.mjs`): clip sanitized (`x,y` floored ≥0; `width` ≤ viewport width (default 1600), `height` ≤ 320, both ≥1); `page.screenshot({encoding:'base64', clip, captureBeyondViewport:true})` before; inject `<style id="impeccable-visual-contrast-hide-style">[data-impeccable-visual-contrast-target]{color:transparent!important;-webkit-text-fill-color:transparent!important;text-shadow:none!important}[data-impeccable-visual-contrast-target][data-impeccable-bgclip-text="true"]{background-image:none!important}` and set attribute `data-impeccable-visual-contrast-target=impeccable-contrast-${Date.now()}-${rand}` (+ `data-impeccable-bgclip-text="true"` if `candidate.backgroundClipText`); screenshot after; remove attributes; in-page canvas diff: pixels with channel delta sum ≥10 are glyph pixels; ratio uses WCAG luminance of CSS text color (unless `preferRenderedForeground`) vs after-pixel; needs ≥8 ratios; p10 = `ratios[floor(0.10*n)]`; finding when `p10 < candidate.threshold`: `{id:'low-contrast', snippet:`pixel contrast ${p10.toFixed(1)}:1 median ${median.toFixed(1)}:1 (need ${threshold}:1) on ${reasons.slice(0,3).join(', ') || 'visual background'} "${text}"`}`. No screenshot files are written.
+- **Screenshot flow** (`screenshot-contrast.mjs`, as the JS ran it; the Rust engine's verdict and refusals replace the p10 rule below, see **What the visual pass refuses to read** under the Rust engine additions): clip sanitized (`x,y` floored ≥0; `width` ≤ viewport width (default 1600), `height` ≤ 320, both ≥1); `page.screenshot({encoding:'base64', clip, captureBeyondViewport:true})` before; inject `<style id="impeccable-visual-contrast-hide-style">[data-impeccable-visual-contrast-target]{color:transparent!important;-webkit-text-fill-color:transparent!important;text-shadow:none!important}[data-impeccable-visual-contrast-target][data-impeccable-bgclip-text="true"]{background-image:none!important}` and set attribute `data-impeccable-visual-contrast-target=impeccable-contrast-${Date.now()}-${rand}` (+ `data-impeccable-bgclip-text="true"` if `candidate.backgroundClipText`); screenshot after; remove attributes; in-page canvas diff: pixels with channel delta sum ≥10 are glyph pixels; ratio uses WCAG luminance of CSS text color (unless `preferRenderedForeground`) vs after-pixel; needs ≥8 ratios; p10 = `ratios[floor(0.10*n)]`; finding when `p10 < candidate.threshold`: `{id:'low-contrast', snippet:`pixel contrast ${p10.toFixed(1)}:1 median ${median.toFixed(1)}:1 (need ${threshold}:1) on ${reasons.slice(0,3).join(', ') || 'visual background'} "${text}"`}`. No screenshot files are written.
- Results mapped via `finding(id, url, snippet)` (file = the URL, line 0); `ignoreValue` set if present; `severity` overridden if the browser supplied one.
- **Rust engine additions (not in the JS):**
- **Scan order.** The reveal sweep runs *before* anything is measured, and one post-reveal capture serves every pass: the rule pass, `content-hidden-at-rest`, and the visual-contrast pass all read that capture, so a hit test any of them answers is answered for all three. The JS ran the rule pass over a capture taken right after load, when a scroll-reveal section is still at opacity 0 and the element checks skip it; the rules now measure the page as a visitor who scrolls it sees it, which reports the faults inside revealed sections and no longer reports a fade-in as `buried-raster`. `content-hidden-at-rest` still measures what stays hidden after the reveal handlers ran. Phase names, profile events, and the order findings are emitted in are unchanged.