The design language that makes your AI harness better at design.
JavaScript
Merge corpus/fix-visual-contrast into corpus/integration
Paul Bakaus5c58898a1fb5
diff --cc docs/CLI-CONTRACT.mdindex bdb7e935a,12c4ef791..252d12ce8--- a/docs/CLI-CONTRACT.md+++ b/docs/CLI-CONTRACT.md@@@ -329,9 -329,9 +329,10 @@@ Optional keys added later by engines (a- **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.- 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.- **Element identity.** A finding from the rule pass or the visual-contrast pass carries `selector` (after `ignoreValue`): the flagged group's generated selector (`body` / `html` for page-level groups), or the visual-contrast candidate's selector. `content-hidden-at-rest` and `script-error` findings have none.- **Page validity gate.** After `goto` (and settle), before injecting anything, the engine classifies the page (`crates/browser/src/validity.rs`) from the main document's final CDP response and an in-page probe (title, visible text length, final URL, challenge-widget markers). Challenge: an `x-amzn-waf-action` header, `cf-mitigated: challenge`, a final URL on a challenge-only host (`perfdrive.com`, `captcha-delivery.com`), or, on a page with at most 3000 characters of visible text, a challenge title prefix ("Just a moment", "Attention Required! | Cloudflare", "Human Verification", "Access Denied", "Radware Bot Manager", "Captcha", ...) or a full-page widget marker (Cloudflare challenge form, PerimeterX, DataDome, Imperva, Akamai, AWS WAF, slider captchas). HTTP error: a final status >= 400 with no challenge signal. A blocked page throws `the page is a bot challenge, not the site (<signals>). Findings would describe the challenge page, so none are reported.` or `the page returned an error (HTTP <status>). Findings would describe the error page, so none are reported.`, which the CLI prints as `Error: ...` and counts as an operational failure (exit 1). A `file://` load has no response, so only the probe signals apply.+ - **What the visual pass refuses to read.** The JS reported whatever its sampling produced; the engine says nothing where the reading is not the text's own background. In the stack walk (`impeccable_core::browser::visual`): a translucent surface no longer restarts the walk at its own parent (which re-entered the stack above the node it came from and composited that surface over itself until its alpha read as opaque, and which skipped siblings painted between the surface and that parent) — the walk keeps descending the one `elementsFromPoint` stack, collecting translucent surfaces until an opaque one grounds them, then composites them back in order (topmost surface still names the method, `...+alpha`); a walk that reaches the end of the stack with nothing opaque is unresolved rather than reporting the last translucent color as a surface. A gradient answers analytically only when its stops agree: any stop below 0.95 alpha (a scrim, a glow, a `from-x/10` wash composites differently at every point of the box) or two opaque stops more than 2× apart in contrast make it `gradient stops disagree`, and an `svg` in the stack makes it `<tag> paint`; both end the walk (`stop`) rather than letting the nodes under them answer for the text, so the candidate falls to the screenshot pass. In the screenshot flow: a candidate whose reasons include `background-clip text`, `filter`, or `backdrop filter` is refused before the two screenshots are taken; the verdict is the median over the *fully painted* glyph pixels (channel delta ≥ 75% of the strongest delta in the box, ≥ 8 of them) rather than the tenth percentile over every changed pixel, which antialiased edges drive to 1:1; and the pass reports nothing when the diff is not a glyph over its background — more than 55% of the clip changed (the page repainted), more than a quarter of the changed pixels moved the opposite way from the rest (text mid-animation leaves its old position and its new one in the same diff), most fully painted pixels are not the color the text declares (`preferRenderedForeground` aside, where the painted value *is* the claim), the surface under the glyphs stands 2:1 or further from the surface beside them in the same box (the page paints its own text twice, so hiding one copy leaves the other where the glyphs were), or the median of every measured pixel is more than 3× the verdict (the sample is two populations, not one surface). The snippet shape is unchanged, so `median` in it stays the median over every glyph pixel and now reads at or below the verdict.- `createBrowserDetector(options)`: shared browser, defaults `waitUntil:'load'`, `settleMs:100`, `viewport 1280x800`; `close()` closes only an owned browser.- Tests: `tests/detect-url-launch.test.mjs`, `tests/detect-antipatterns-browser.test.mjs`.diff --cc tests/oracle/DELTAS.mdindex d10eabfe5,3d42386db..09854c4bc--- a/tests/oracle/DELTAS.md+++ b/tests/oracle/DELTAS.md@@@ -165,16 -165,18 +165,32 @@@ CLI 4.0.0 release; it is what the binar- `cli-version`.+## Recorded 2026-09-12: the URL scan reads the page after the reveal sweep++`crates/browser` now runs the reveal sweep before it captures the page, and+every deterministic pass reads that one post-reveal capture. The new fixture+`tests/fixtures/antipatterns/scroll-reveal.html` is what holds that order: its+left column carries faults a pre-reveal pass cannot see (a section at opacity 0+skips the element checks), its right column carries the fade-in a pre-reveal+pass reports as `buried-raster`. URL scans have no goldens, so the fixture is+pinned by `crates/browser/tests/evidence.rs`; the goldens below move only+because a file was added to the fixture directory the static engine walks.++- `detect-fixture-json-scroll-reveal-html`, `detect-fixture-text-scroll-reveal-html`: new cases. The static engine has no reveal to run, so it reports the fade-in from the stylesheet; that is its correct reading of the source and the fixture says so in a comment.+- `detect-dir-json-all-fixtures`, `detect-dir-text-all-fixtures`, `detect-dir-quiet-all-fixtures`, `detect-scope-type`, `detect-scope-both`, `detect-no-advisory-json`, `detect-no-advisory-text`: the four new findings are appended and the total moves from 419 to 423. No existing fixture's findings changed.+++ ## Recorded 2026-09-12: a fixture for the visual-contrast sampling decisions++ `tests/fixtures/antipatterns/visual-contrast-sampling.html` is new: the+ reduced false positives and protected true positives behind the visual pass's+ sampling fix (glass panel, filtered wrapper, transparent gradient stop, a+ ten-percent tint of the text's own color, vector avatar paint, gradient-clipped+ heading, faded accordion trigger, translucent pill on a pale photo). The static+ text scan reads the file like any other fixture; the only rule with an opinion+ about it is `gradient-text`, which fires twice on the one `background-clip:+ text` heading (the existing duplicate the CSS-text and element forms produce).+ The dir-wide goldens gain those two findings and their count moves 419 → 421.+ Nothing else in any golden changed: the fix is in the browser passes, which+ have no goldens (browser output depends on the machine).++ - `detect-dir-text-all-fixtures`, `detect-dir-json-all-fixtures`, `detect-dir-quiet-all-fixtures`, `detect-no-advisory-text`, `detect-no-advisory-json`, and the two new per-fixture cases `detect-fixture-text-visual-contrast-sampling-html` / `detect-fixture-json-visual-contrast-sampling-html`.