The design language that makes your AI harness better at design.
JavaScript
URL scans refuse challenge and error pages and name the flagged element
Paul Bakaus5bb677b1e2dd
diff --git a/crates/browser/src/cdp.rs b/crates/browser/src/cdp.rsindex 377d1bd9e..31fe34fd7 100644--- a/crates/browser/src/cdp.rs+++ b/crates/browser/src/cdp.rs@@ -307,6 +307,7 @@ impl Browser {swapped: false,same_document_navigation: false,iframe_sessions: HashSet::new(),+ main_document_response: None,};page.initialize()?;Ok(page)@@ -579,6 +580,9 @@ pub struct Page<'a> {same_document_navigation: bool,/// Auto-attached OOPIF sessions whose Page events feed the frame map.iframe_sessions: HashSet<String>,+ /// The CDP `Network.Response` of the main frame's latest document load+ /// (the last one wins, so after redirects this is the final response).+ main_document_response: Option<Value>,}/// A raw `Runtime.evaluate` outcome.@@ -818,6 +822,15 @@ impl<'a> Page<'a> {self.swapped = true;}}+ "Network.responseReceived" => {+ if session == self.session_id+ && params.get("type").and_then(Value::as_str) == Some("Document")+ && params.get("frameId").and_then(Value::as_str)+ == Some(self.main_frame_id.as_str())+ {+ self.main_document_response = params.get("response").cloned();+ }+ }"Page.navigatedWithinDocument" => {if params.get("frameId").and_then(Value::as_str)== Some(self.main_frame_id.as_str())@@ -966,6 +979,7 @@ impl<'a> Page<'a> {.unwrap_or_default();self.swapped = false;self.same_document_navigation = false;+ self.main_document_response = None;let deadline = Instant::now() + timeout;let timeout_msg = format!("Navigation timeout of {} ms exceeded", timeout.as_millis());@@ -1128,6 +1142,40 @@ impl<'a> Page<'a> {.to_string())}+ /// The main document's latest CDP `Network.Response` since the last+ /// [`Page::goto`], or `None` when no document response was seen (a+ /// `file://` load can have none).+ pub fn main_document_response(&mut self) -> Option<Value> {+ self.pump_events();+ self.main_document_response.clone()+ }++ /// A JPEG of the given document region (`captureBeyondViewport`), base64.+ pub fn screenshot_jpeg(+ &mut self,+ x: f64,+ y: f64,+ width: f64,+ height: f64,+ quality: u32,+ ) -> CdpResult<String> {+ let res = self.send(+ "Page.captureScreenshot",+ json!({+ "format": "jpeg",+ "quality": quality.min(100),+ "fromSurface": true,+ "clip": { "x": x, "y": y, "width": width.round(), "height": height.round(), "scale": 1 },+ "captureBeyondViewport": true,+ }),+ )?;+ Ok(res+ .get("data")+ .and_then(Value::as_str)+ .unwrap_or("")+ .to_string())+ }+/// The deduped `pageerror` messages so far.pub fn page_errors(&mut self) -> Vec<String> {self.pump_events();diff --git a/crates/browser/src/lib.rs b/crates/browser/src/lib.rsindex 98d44b34b..ea3d8009a 100644--- a/crates/browser/src/lib.rs+++ b/crates/browser/src/lib.rs@@ -14,11 +14,23 @@//! a single URL uses `detect_url` (`waitUntil: 'networkidle0'`, `settleMs://! 0`); several URLs share one browser through [`SharedBrowser`]//! (`createBrowserDetector()`: `waitUntil: 'load'`, `settleMs: 100`).+//!+//! Before any rule runs, the loaded page is classified ([`validity`]): a bot+//! challenge or an HTTP error page is refused with an error instead of being+//! scanned and reported clean.+//!+//! Two entry points serve measurement work rather than the CLI.+//! [`detect_url_evidence`] runs the same scan and also returns what a+//! reviewer needs to check the findings (the captures and hit-test answers,+//! element rects, a screenshot). [`replay_url_scan`] re-runs the deterministic+//! passes over a recorded capture with no browser, so a rule change can be+//! measured against saved pages.pub mod cdp;pub mod discovery;pub mod screenshot_contrast;pub mod snapshot_engine;+pub mod validity;use std::cell::RefCell;use std::collections::HashMap;@@ -26,14 +38,16 @@ use std::time::{Duration, Instant};use impeccable_core::browser::driver::{collect_browser_findings, serialize_findings};use impeccable_core::browser::page_checks::measure_hidden_text_dom;+use impeccable_core::browser::snapshot::Facts;use impeccable_core::checks::measures::{check_content_hidden_at_rest, ContentHiddenInput};use impeccable_core::findings::{try_finding, Finding};use impeccable_detect::design_system::DesignSystem;use impeccable_detect::engines::{EngineError, ScanOptions, SharedBrowser, UrlEngine};use impeccable_detect::profiler::{DetectorProfile, ProfileMeta};-use serde_json::{json, Value};+use serde_json::{json, Map, Value};use cdp::{Browser, CdpError, Page, Viewport};+use validity::{DocumentResponse, PageProbe, PageValidity};/// puppeteer's default `page.goto` timeout the JS passes explicitly.const NAVIGATION_TIMEOUT: Duration = Duration::from_millis(30000);@@ -75,7 +89,7 @@ impl BrowserEngine {}/// `launchBrowser()`: discover, then launch headless.- fn launch(&self) -> Result<Browser, EngineError> {+ pub fn launch(&self) -> Result<Browser, EngineError> {let exe = discovery::find_browser(&self.env).map_err(EngineError::new)?;Browser::launch(&exe, &self.launch_args(), self.dangerous_no_sandbox()).map_err(|e| EngineError::new(e.message))@@ -227,12 +241,101 @@ pub fn serialize_design_system_for_browser(ds: Option<&DesignSystem>) -> Value {})}+/// The pass that produced a finding, as [`Evidence::origins`] names it.+pub mod origin {+ /// The deterministic rule pass over the first capture. Replayable.+ pub const SCAN: &str = "scan";+ /// `content-hidden-at-rest`, over the post-reveal capture. Replayable.+ pub const CONTENT_HIDDEN: &str = "content-hidden";+ /// Uncaught page errors. Recorded, not replayable.+ pub const SCRIPT_ERROR: &str = "script-error";+ /// The visual-contrast pass (image and pixel reads). Recorded, not+ /// replayable.+ pub const VISUAL_CONTRAST: &str = "visual-contrast";+}+/// A pre-registry finding as `detectUrl` accumulates them.struct RawResult {id: String,snippet: String,ignore_value: String,severity: String,+ /// The flagged element's selector, when the pass names an element.+ selector: Option<String>,+ origin: &'static str,+}++impl RawResult {+ fn new(origin: &'static str, id: String, snippet: String) -> RawResult {+ RawResult {+ id,+ snippet,+ ignore_value: String::new(),+ severity: String::new(),+ selector: None,+ origin,+ }+ }+}++/// What [`detect_url_evidence`] records next to the findings.+#[derive(Debug, Default)]+pub struct Evidence {+ /// The main document's final HTTP response, when one was seen.+ pub response: Option<DocumentResponse>,+ /// The in-page probe the validity gate ran.+ pub probe: Option<PageProbe>,+ /// The validity verdict. A blocked page has no captures and no findings.+ pub validity: Option<PageValidity>,+ /// The first capture's JSON, which the rule pass ran over.+ pub scan_snapshot: Option<String>,+ /// Every hit test answered for the first capture.+ pub scan_facts: Facts,+ /// The post-reveal capture's JSON (`content-hidden-at-rest`).+ pub reveal_snapshot: Option<String>,+ /// Every hit test answered for the post-reveal capture's hidden-text measure.+ pub reveal_facts: Facts,+ /// Parallel to the findings: which pass produced each (see [`origin`]).+ pub origins: Vec<&'static str>,+ /// Document-coordinate `[x, y, width, height]` of each flagged selector,+ /// measured after the scan, so they match [`Evidence::screenshot`].+ pub element_rects: Map<String, Value>,+ /// Per flagged selector, measured after the scan: `{ tag, text, html,+ /// styles }` (text and html truncated; a fixed set of computed styles).+ pub element_details: Map<String, Value>,+ pub screenshot: Option<Screenshot>,+ /// Why no screenshot was taken, when one was requested and failed.+ pub screenshot_error: Option<String>,+}++/// A full-page screenshot taken after the scan.+#[derive(Debug, Clone)]+pub struct Screenshot {+ pub jpeg_base64: String,+ /// CSS pixels (the scan uses a device scale factor of 1).+ pub width: f64,+ pub height: f64,+ /// The document's height; larger than `height` when the capture was cut.+ pub document_height: f64,+}++/// What [`detect_url_evidence`] should capture beyond the findings.+#[derive(Debug, Clone)]+pub struct EvidenceRequest {+ pub screenshot: bool,+ /// Cut the screenshot at this height (CSS pixels).+ pub max_screenshot_height: f64,+ pub jpeg_quality: u32,+}++impl Default for EvidenceRequest {+ fn default() -> Self {+ EvidenceRequest {+ screenshot: true,+ max_screenshot_height: 12000.0,+ jpeg_quality: 82,+ }+ }}fn cdp_err(e: CdpError) -> EngineError {@@ -315,6 +418,14 @@ fn js_str_or_empty(v: Option<&Value>) -> String {}}+/// A non-empty `selector` field.+fn selector_of(v: &Value) -> Option<String> {+ v.get("selector")+ .and_then(Value::as_str)+ .filter(|s| !s.is_empty())+ .map(String::from)+}+/// `detectUrl(url, options)` with the wait/settle defaults the caller picks/// and an optional shared browser (`options.browser`).fn detect_url_impl(@@ -332,11 +443,6 @@ fn detect_url_impl(let url = url.as_str();let credentials = credentials.as_ref();let profile = options.profile.as_deref();- let (vw, vh) = options.viewport.unwrap_or((1280, 800));- let viewport = Viewport {- width: vw,- height: vh,- };let owns_browser = external.is_none();let mut owned: Option<Browser> = None;let browser: &mut Browser = match external {@@ -357,22 +463,107 @@ fn detect_url_impl(}};- let page = step(profile, "load", "new-page", url, || browser.new_page()).map_err(cdp_err);- let scanned = match page {- Ok(page) => scan_page(- page, url, credentials, options, wait_until, settle_ms, viewport, profile,- ),- Err(e) => Err(e),- };+ let scanned = scan_on_browser(+ browser, url, credentials, options, wait_until, settle_ms, profile, None,+ );// finally: close page (inside scan_page) and the browser when owned.if owns_browser {if let Some(b) = owned.take() {step(profile, "load", "close-browser", url, || b.close());}}- let results = scanned?;+ let (findings, _) = results_to_findings(url, scanned?)?;+ Ok(findings)+}++/// Run the URL engine's scan on a browser the caller owns and also return+/// the [`Evidence`] a reviewer needs to check each finding. The findings are+/// the ones `impeccable detect --json <url>` prints for the same page and+/// wait strategy. A blocked page returns no findings and an `Ok` with+/// [`Evidence::validity`] set, instead of the CLI's error.+pub fn detect_url_evidence(+ browser: &mut Browser,+ url: &str,+ options: &ScanOptions,+ wait_until: &str,+ settle_ms: u64,+ request: &EvidenceRequest,+) -> Result<(Vec<Finding>, Evidence), EngineError> {+ let (url, credentials) = split_scan_url(url);+ let mut evidence = Evidence::default();+ let results = scan_on_browser(+ browser,+ &url,+ credentials.as_ref(),+ options,+ wait_until,+ settle_ms,+ options.profile.as_deref(),+ Some((&mut evidence, request)),+ )?;+ let (findings, origins) = results_to_findings(&url, results)?;+ evidence.origins = origins;+ Ok((findings, evidence))+}++/// The outcome of [`replay_url_scan`].+#[derive(Debug)]+pub struct ReplayOutcome {+ /// Findings from the replayable passes ([`origin::SCAN`],+ /// [`origin::CONTENT_HIDDEN`]), in the order a live scan emits them.+ pub findings: Vec<Finding>,+ /// Hit tests the rules asked for that the recording cannot answer. Zero+ /// for an unchanged engine; a rule change that probes new points reports+ /// them here, and its findings for those points are an undercount.+ pub unanswered_hit_tests: usize,+}++/// Re-run the deterministic passes over a recorded capture, with no browser.+/// `scan_snapshot` and `scan_facts` come from [`Evidence::scan_snapshot`] and+/// [`Evidence::scan_facts`]; the post-reveal pair is optional.+pub fn replay_url_scan(+ url: &str,+ scan_snapshot: &str,+ scan_facts: &Facts,+ reveal: Option<(&str, &Facts)>,+ options: &ScanOptions,+) -> Result<ReplayOutcome, EngineError> {+ let config = snapshot_engine::browser_config(+ serialize_design_system_for_browser(options.design_system.as_deref()),+ options.rule_pack,+ );+ let dom = snapshot_engine::parse_snapshot(scan_snapshot).map_err(cdp_err)?;+ dom.add_facts(scan_facts);+ let collected = collect_browser_findings(&dom, &config);+ let mut unanswered = dom.take_needs().hit_tests.len();+ let groups = serialize_findings(&dom, &collected.groups);+ let mut results = results_from_groups(groups.as_array().map(Vec::as_slice).unwrap_or(&[]));+ if let Some((json, facts)) = reveal {+ let base = snapshot_engine::parse_snapshot(json).map_err(cdp_err)?;+ base.add_facts(facts);+ let measured = measure_hidden_text_dom(&base);+ unanswered += base.take_needs().hit_tests.len();+ results.extend(content_hidden_results(+ measured.total_chars,+ measured.hidden_chars,+ measured.hidden_samples,+ ));+ }+ let (findings, _) = results_to_findings(url, results)?;+ Ok(ReplayOutcome {+ findings,+ unanswered_hit_tests: unanswered,+ })+}+/// Map raw results onto registry findings, returning each one's origin+/// alongside.+fn results_to_findings(+ url: &str,+ results: Vec<RawResult>,+) -> Result<(Vec<Finding>, Vec<&'static str>), EngineError> {let mut findings = Vec::with_capacity(results.len());+ let mut origins = Vec::with_capacity(results.len());for r in results {let Some(mut item) = try_finding(&r.id, url, &r.snippet, 0.0) else {// JS: `finding()` dereferences an unknown registry entry.@@ -384,13 +575,82 @@ fn detect_url_impl(item.extras.insert("ignoreValue".into(), Value::String(r.ignore_value));}+ if let Some(selector) = r.selector {+ item.extras.insert("selector".into(), Value::String(selector));+ }if !r.severity.is_empty() && r.severity != item.severity {item.severity = r.severity;}impeccable_core::findings::derive_advisory_flag(&mut item);findings.push(item);+ origins.push(r.origin);+ }+ Ok((findings, origins))+}++/// Flatten `serialize_findings` groups into raw results, each carrying its+/// group's selector.+fn results_from_groups(groups: &[Value]) -> Vec<RawResult> {+ let mut out = Vec::new();+ for group in groups {+ let Some(findings) = group.get("findings").and_then(Value::as_array) else {+ continue;+ };+ let selector = selector_of(group);+ for f in findings {+ out.push(RawResult {+ id: js_str(f.get("type")),+ snippet: js_str(f.get("detail")),+ ignore_value: js_str_or_empty(f.get("ignoreValue")),+ severity: js_str_or_empty(f.get("severity")),+ selector: selector.clone(),+ origin: origin::SCAN,+ });+ }+ }+ out+}++fn content_hidden_results(+ total_chars: f64,+ hidden_chars: f64,+ hidden_samples: Vec<String>,+) -> Vec<RawResult> {+ let input = ContentHiddenInput {+ total_chars,+ hidden_chars,+ hidden_samples,+ };+ check_content_hidden_at_rest(&input)+ .into_iter()+ .map(|f| RawResult::new(origin::CONTENT_HIDDEN, f.id, f.snippet))+ .collect()+}++/// A new page on `browser`, scanned, then closed.+#[allow(clippy::too_many_arguments)]+fn scan_on_browser(+ browser: &mut Browser,+ url: &str,+ credentials: Option<&ScanCredentials>,+ options: &ScanOptions,+ wait_until: &str,+ settle_ms: u64,+ profile: Option<&DetectorProfile>,+ evidence: Option<(&mut Evidence, &EvidenceRequest)>,+) -> Result<Vec<RawResult>, EngineError> {+ let (vw, vh) = options.viewport.unwrap_or((1280, 800));+ let viewport = Viewport {+ width: vw,+ height: vh,+ };+ let page = step(profile, "load", "new-page", url, || browser.new_page()).map_err(cdp_err);+ match page {+ Ok(page) => scan_page(+ page, url, credentials, options, wait_until, settle_ms, viewport, profile, evidence,+ ),+ Err(e) => Err(e),}- Ok(findings)}/// Everything between `newPage` and the `finally` that closes the page.@@ -404,6 +664,7 @@ fn scan_page(settle_ms: u64,viewport: Viewport,profile: Option<&DetectorProfile>,+ evidence: Option<(&mut Evidence, &EvidenceRequest)>,) -> Result<Vec<RawResult>, EngineError> {let outcome = scan_page_inner(&mut page,@@ -414,11 +675,32 @@ fn scan_page(settle_ms,viewport,profile,+ evidence,);step(profile, "load", "close-page", url, || page.close());outcome}+/// Probe the loaded page and classify it. A probe that fails because the page+/// navigated underneath it (a challenge redirecting on its own) is retried+/// once after a short wait.+fn check_validity(page: &mut Page<'_>) -> Result<(Option<DocumentResponse>, PageProbe, PageValidity), CdpError> {+ let js = validity::probe_js();+ let raw = match page.evaluate_value(&js) {+ Ok(v) => v,+ Err(_) => {+ std::thread::sleep(Duration::from_millis(1000));+ page.evaluate_value(&js)?+ }+ };+ let probe = PageProbe::from_value(&raw);+ let response = page+ .main_document_response()+ .and_then(|r| DocumentResponse::from_cdp(&r));+ let verdict = validity::classify(response.as_ref(), &probe);+ Ok((response, probe, verdict))+}+#[allow(clippy::too_many_arguments)]fn scan_page_inner(page: &mut Page<'_>,@@ -429,6 +711,7 @@ fn scan_page_inner(settle_ms: u64,viewport: Viewport,profile: Option<&DetectorProfile>,+ mut evidence: Option<(&mut Evidence, &EvidenceRequest)>,) -> Result<Vec<RawResult>, EngineError> {step(profile, "load", "set-viewport", url, || {page.set_viewport(viewport)@@ -450,6 +733,25 @@ fn scan_page_inner(});}+ // A challenge or error page is not the site: refuse to report on it.+ let (response, probe, verdict) =+ step(profile, "load", "validity", url, || check_validity(page)).map_err(cdp_err)?;+ let blocked = verdict.error_message();+ if let Some((ev, _)) = evidence.as_mut() {+ ev.response = response;+ ev.probe = Some(probe);+ ev.validity = Some(verdict);+ }+ if let Some(message) = blocked {+ return match evidence {+ None => Err(EngineError::new(message)),+ Some((ev, request)) => {+ capture_post_scan(page, ev, request, &[]);+ Ok(Vec::new())+ }+ };+ }+// Inject the plain-JS snapshot producer (no WebAssembly runs in the page).step(profile, "scan", "inject-snapshot-script", url, || {snapshot_engine::ensure_snapshot_js(page)@@ -468,29 +770,24 @@ fn scan_page_inner(// produced; the group selectors feed the visual pass below.let mut serialized_groups: Vec<Value> = Vec::new();let mut results = step_findings(profile, "scan", "browser-scan", url, || {- let dom = snapshot_engine::capture_snapshot(page).map_err(cdp_err)?;- let collected =- snapshot_engine::resolve_needs(&dom, page, |d| collect_browser_findings(d, &config))- .map_err(cdp_err)?;+ let json = snapshot_engine::capture_snapshot_json(page).map_err(cdp_err)?;+ let dom = snapshot_engine::parse_snapshot(&json).map_err(cdp_err)?;+ let facts = evidence.as_mut().map(|(ev, _)| {+ ev.scan_snapshot = Some(json);+ &mut ev.scan_facts+ });+ let collected = snapshot_engine::resolve_needs_recording(+ &dom,+ page,+ |d| collect_browser_findings(d, &config),+ facts,+ )+ .map_err(cdp_err)?;serialized_groups = serialize_findings(&dom, &collected.groups).as_array().cloned().unwrap_or_default();- let mut out = Vec::new();- for group in &serialized_groups {- let Some(findings) = group.get("findings").and_then(Value::as_array) else {- continue;- };- for f in findings {- out.push(RawResult {- id: js_str(f.get("type")),- snippet: js_str(f.get("detail")),- ignore_value: js_str_or_empty(f.get("ignoreValue")),- severity: js_str_or_empty(f.get("severity")),- });- }- }- Ok::<_, EngineError>(out)+ Ok::<_, EngineError>(results_from_groups(&serialized_groups))})?;// content-hidden-at-rest: reveal sweep, then one post-reveal capture the@@ -498,37 +795,35 @@ fn scan_page_inner(// page revealed and scrolled to the top — the scroll-0 snapshot the in-page// path measured and analyzed).step(profile, "scan", "reveal-sweep", url, || reveal_sweep(page)).map_err(cdp_err)?;- let base = snapshot_engine::capture_snapshot(page).map_err(cdp_err)?;+ let base_json = snapshot_engine::capture_snapshot_json(page).map_err(cdp_err)?;+ let base = snapshot_engine::parse_snapshot(&base_json).map_err(cdp_err)?;let hidden = step_findings(profile, "scan", "content-hidden-at-rest", url, || {- let measured =- snapshot_engine::resolve_needs(&base, page, |d| measure_hidden_text_dom(d)).map_err(cdp_err)?;- let input = ContentHiddenInput {- total_chars: measured.total_chars,- hidden_chars: measured.hidden_chars,- hidden_samples: measured.hidden_samples,- };- Ok::<_, EngineError>(- check_content_hidden_at_rest(&input)- .into_iter()- .map(|f| RawResult {- id: f.id,- snippet: f.snippet,- ignore_value: String::new(),- severity: String::new(),- })- .collect(),+ let facts = evidence.as_mut().map(|(ev, _)| {+ ev.reveal_snapshot = Some(base_json);+ &mut ev.reveal_facts+ });+ let measured = snapshot_engine::resolve_needs_recording(+ &base,+ page,+ |d| measure_hidden_text_dom(d),+ facts,)+ .map_err(cdp_err)?;+ Ok::<_, EngineError>(content_hidden_results(+ measured.total_chars,+ measured.hidden_chars,+ measured.hidden_samples,+ ))})?;results.extend(hidden);for message in page.page_errors().into_iter().take(3) {- results.push(RawResult {- id: "script-error".to_string(),- snippet: message,- ignore_value: String::new(),- severity: String::new(),- });+ results.push(RawResult::new(+ origin::SCRIPT_ERROR,+ "script-error".to_string(),+ message,+ ));}let analyses = step(profile, "visual-contrast", "browser-analyze", url, || {@@ -537,9 +832,95 @@ fn scan_page_inner(.map_err(cdp_err)?;let visual = run_visual_contrast_fallback(page, &analyses, &serialized_groups, viewport, profile, url)?;results.extend(visual);++ if let Some((ev, request)) = evidence {+ let mut selectors: Vec<String> = Vec::new();+ for r in &results {+ if let Some(s) = &r.selector {+ if !selectors.contains(s) {+ selectors.push(s.clone());+ }+ }+ }+ capture_post_scan(page, ev, request, &selectors);+ }Ok(results)}+/// Element rects and the screenshot, after every pass has run, so a live+/// scan and an evidence scan drive the page identically up to here. Failures+/// are recorded on the evidence, never raised: the findings stand without them.+fn capture_post_scan(+ page: &mut Page<'_>,+ ev: &mut Evidence,+ request: &EvidenceRequest,+ selectors: &[String],+) {+ if !selectors.is_empty() {+ let expr = format!(+ r#"(() => {{+ const props = ['display', 'position', 'font-family', 'font-size', 'font-weight', 'font-style', 'line-height', 'letter-spacing', 'text-transform', 'text-align', 'color', 'background-color', 'background-image', 'border', 'border-radius', 'box-shadow', 'padding', 'margin', 'width', 'height', 'max-width', 'opacity'];+ const rects = {{}};+ const details = {{}};+ for (const s of {sels}) {{+ try {{+ const el = document.querySelector(s);+ if (!el) continue;+ const r = el.getBoundingClientRect();+ rects[s] = [r.x + window.scrollX, r.y + window.scrollY, r.width, r.height];+ const cs = getComputedStyle(el);+ const styles = {{}};+ for (const p of props) styles[p] = cs.getPropertyValue(p);+ details[s] = {{+ tag: el.tagName.toLowerCase(),+ text: (el.innerText || el.textContent || '').replace(/\s+/g, ' ').trim().slice(0, 300),+ html: (el.outerHTML || '').slice(0, 1500),+ styles,+ }};+ }} catch (e) {{}}+ }}+ return {{ rects, details }};+}})()"#,+ sels = json!(selectors)+ );+ if let Ok(v) = page.evaluate_value(&expr) {+ if let Some(Value::Object(m)) = v.get("rects") {+ ev.element_rects = m.clone();+ }+ if let Some(Value::Object(m)) = v.get("details") {+ ev.element_details = m.clone();+ }+ }+ }+ if !request.screenshot {+ return;+ }+ let dims = page.evaluate_value(+ "(() => ({ w: window.innerWidth, h: Math.max(document.documentElement ? document.documentElement.scrollHeight : 0, document.body ? document.body.scrollHeight : 0, window.innerHeight) }))()",+ );+ let dims = match dims {+ Ok(d) => d,+ Err(e) => {+ ev.screenshot_error = Some(e.message);+ return;+ }+ };+ let width = dims.get("w").and_then(Value::as_f64).unwrap_or(1280.0).max(1.0);+ let document_height = dims.get("h").and_then(Value::as_f64).unwrap_or(800.0).max(1.0);+ let height = document_height.min(request.max_screenshot_height);+ match page.screenshot_jpeg(0.0, 0.0, width, height, request.jpeg_quality) {+ Ok(jpeg_base64) => {+ ev.screenshot = Some(Screenshot {+ jpeg_base64,+ width,+ height,+ document_height,+ })+ }+ Err(e) => ev.screenshot_error = Some(e.message),+ }+}+/// The `measureContentHiddenAfterReveal` reveal sweep: scroll the page top to/// bottom (revealing lazy / on-scroll content), then back to the top and/// settle. The hidden-text measure then runs natively over a fresh capture.@@ -598,12 +979,10 @@ fn run_visual_contrast_fallback(.iter().any(|s| Some(s.as_str()) == r.get("selector").and_then(Value::as_str))})- .filter_map(|r| r.get("finding"))- .map(|f| RawResult {- id: js_str(f.get("id")),- snippet: js_str(f.get("snippet")),- ignore_value: String::new(),- severity: String::new(),+ .filter_map(|r| r.get("finding").map(|f| (f, selector_of(r))))+ .map(|(f, selector)| RawResult {+ selector,+ ..RawResult::new(origin::VISUAL_CONTRAST, js_str(f.get("id")), js_str(f.get("snippet")))}).collect();@@ -645,10 +1024,8 @@ fn run_visual_contrast_fallback(Ok::<_, EngineError>(f.map(|f| {vec![RawResult {- id: f.id.to_string(),- snippet: f.snippet,- ignore_value: String::new(),- severity: String::new(),+ selector: selector_of(candidate),+ ..RawResult::new(origin::VISUAL_CONTRAST, f.id.to_string(), f.snippet)}]}).unwrap_or_default(),@@ -680,6 +1057,23 @@ mod tests {assert!(serialize_design_system_for_browser(Some(&ds)).is_null());}+ #[test]+ fn group_findings_carry_the_group_selector() {+ let groups = vec![json!({+ "selector": "main > h1",+ "findings": [+ { "type": "tight-leading", "detail": "line-height 1.15x (need >=1.3)", "ignoreValue": "", "severity": "warning" },+ ],+ })];+ let (findings, origins) =+ results_to_findings("https://example.com/", results_from_groups(&groups)).unwrap();+ assert_eq!(findings.len(), 1);+ assert_eq!(findings[0].extras.get("selector"), Some(&json!("main > h1")));+ assert_eq!(origins, vec![origin::SCAN]);+ let text = serde_json::to_string(&findings[0]).unwrap();+ assert!(text.ends_with(r#""line":0,"snippet":"line-height 1.15x (need >=1.3)","selector":"main > h1"}"#));+ }+// Expected values come from tests/detect-url-launch.test.mjs (issue #657).#[test]fn split_scan_url_matches_js() {diff --git a/crates/browser/src/snapshot_engine.rs b/crates/browser/src/snapshot_engine.rsindex cdd115d3e..c5d90261f 100644--- a/crates/browser/src/snapshot_engine.rs+++ b/crates/browser/src/snapshot_engine.rs@@ -55,15 +55,25 @@ pub fn ensure_snapshot_js(page: &mut Page<'_>) -> CdpResult<()> {/// stable across scrolls (the DOM is unchanged), which is why an earlier/// snapshot's ids keep matching the page's current `__impCap`.pub fn capture_snapshot(page: &mut Page<'_>) -> CdpResult<SnapshotDom> {+ parse_snapshot(&capture_snapshot_json(page)?)+}++/// [`capture_snapshot`] without the parse: the capture's JSON exactly as the+/// page produced it, which is what a replay loads.+pub fn capture_snapshot_json(page: &mut Page<'_>) -> CdpResult<String> {let expr = "(function(){ const s = window.__impeccableSnapshot; const c = s.capture(); if (c.error) return { error: c.error }; window.__impCap = c; window.__impIO = s.visualIO(c); return { json: c.json }; })()";let out = page.evaluate_value(expr)?;if let Some(err) = out.get("error").and_then(Value::as_str) {return Err(CdpError::new(format!("snapshot capture failed: {err}")));}- let json = out- .get("json")+ out.get("json").and_then(Value::as_str)- .ok_or_else(|| CdpError::new("snapshot capture returned no json"))?;+ .map(String::from)+ .ok_or_else(|| CdpError::new("snapshot capture returned no json"))+}++/// Parse a capture's JSON into a [`SnapshotDom`].+pub fn parse_snapshot(json: &str) -> CdpResult<SnapshotDom> {SnapshotDom::from_json(json).map_err(|e| CdpError::new(format!("snapshot parse: {e}")))}@@ -164,6 +174,17 @@ pub fn resolve_needs<T>(dom: &SnapshotDom,page: &mut Page<'_>,f: impl Fn(&SnapshotDom) -> T,+) -> CdpResult<T> {+ resolve_needs_recording(dom, page, f, None)+}++/// [`resolve_needs`], appending every answered hit test to `record` so the+/// run can be replayed over the same capture without the page.+pub fn resolve_needs_recording<T>(+ dom: &SnapshotDom,+ page: &mut Page<'_>,+ f: impl Fn(&SnapshotDom) -> T,+ mut record: Option<&mut Facts>,) -> CdpResult<T> {let mut out = f(dom);let mut rounds = 0;@@ -171,6 +192,9 @@ pub fn resolve_needs<T>(let needs = dom.take_needs();let facts = answer_needs(page, &needs.hit_tests)?;dom.add_facts(&facts);+ if let Some(record) = record.as_deref_mut() {+ record.hits.extend(facts.hits.iter().cloned());+ }out = f(dom);rounds += 1;}diff --git a/crates/browser/src/validity.rs b/crates/browser/src/validity.rsnew file mode 100644index 000000000..1e8d8a8e9--- /dev/null+++ b/crates/browser/src/validity.rs@@ -0,0 +1,424 @@+//! Whether a loaded page is the site, or something standing in front of it.+//!+//! A bot challenge, a WAF block page, or an HTTP error page is a real page the+//! rules can run over, and a challenge page is small enough to come back+//! clean. A scan of it reports on the wrong page and exits 0, which reads as+//! "this site is fine". The URL engine classifies the page right after+//! navigation and refuses to report on a blocked one, so a clean result+//! always describes the site that was asked about.+//!+//! The decision is pure ([`classify`]) over two inputs: the main document's+//! HTTP response as CDP saw it, and a small in-page probe ([`PROBE_JS`]).+//! Header and HTTP-status signals stand alone. Titles and DOM markers only+//! count on a small page, because a real page can carry a captcha widget on a+//! form or be titled "Access denied" in a CMS without being a block page.++use serde_json::{json, Value};++/// Challenge pages are short. A page with more visible text than this is+/// treated as content even when its title or a marker looks like a challenge.+pub const SMALL_PAGE_CHARS: u64 = 3000;++/// Titles challenge and block pages use, lowercased and trimmed. Matched by+/// prefix, so "Access Denied" also covers "Access Denied - Reference #18...".+const CHALLENGE_TITLE_PREFIXES: &[&str] = &[+ "just a moment",+ "attention required! | cloudflare",+ "checking your browser",+ "human verification",+ "access denied",+ "access to this page has been denied",+ "pardon our interruption",+ "are you a robot",+ "robot or human",+ "please verify you are a human",+ "verify you are human",+ "bot verification",+ "security check",+ "you have been blocked",+ "request rejected",+ "ddos-guard",+ "one more step",+ "403 forbidden",+ "radware bot manager",+ "captcha",+];++/// Hosts that only serve challenges. A page that ends up on one of them after+/// redirects is a challenge whatever its title says.+const CHALLENGE_HOSTS: &[&str] = &["perfdrive.com", "captcha-delivery.com"];++/// DOM markers of challenge widgets that fill a page (not inline form+/// captchas). Each entry is `(selector, label)`; the probe reports the labels+/// of the selectors that match.+pub const CHALLENGE_MARKERS: &[(&str, &str)] = &[+ ("#challenge-form, #challenge-running, #cf-challenge-running", "cloudflare-challenge"),+ ("#px-captcha", "perimeterx-captcha"),+ ("iframe[src*='captcha-delivery.com']", "datadome-captcha"),+ ("iframe[src*='_Incapsula_Resource']", "imperva-incapsula"),+ ("#sec-if-cpt-container, #sec-cpt-if", "akamai-challenge"),+ ("#captcha-container[class*='amzn'], awswaf-captcha", "aws-waf-captcha"),+ (".geetest_holder, #nc_1_wrapper, #aliyunCaptcha-sliding-wrapper", "slider-captcha"),+];++/// The in-page probe: title, visible text length, final URL, and which+/// challenge markers are present. Read-only; returns a plain object.+pub fn probe_js() -> String {+ let markers: Vec<Value> = CHALLENGE_MARKERS+ .iter()+ .map(|(selector, label)| json!([selector, label]))+ .collect();+ format!(+ r#"(() => {{+ const markers = {markers};+ const found = [];+ for (const [selector, label] of markers) {{+ try {{ if (document.querySelector(selector)) found.push(label); }} catch (e) {{}}+ }}+ const text = (document.body && document.body.innerText) || '';+ return {{+ title: String(document.title || ''),+ textChars: text.replace(/\s+/g, ' ').trim().length,+ href: String(location.href || ''),+ markers: found,+ }};+}})()"#,+ markers = Value::Array(markers)+ )+}++/// What the probe saw in the page.+#[derive(Debug, Clone, Default, PartialEq)]+pub struct PageProbe {+ pub title: String,+ pub text_chars: u64,+ pub href: String,+ pub markers: Vec<String>,+}++impl PageProbe {+ pub fn from_value(v: &Value) -> PageProbe {+ PageProbe {+ title: v.get("title").and_then(Value::as_str).unwrap_or("").to_string(),+ text_chars: v.get("textChars").and_then(Value::as_f64).unwrap_or(0.0).max(0.0) as u64,+ href: v.get("href").and_then(Value::as_str).unwrap_or("").to_string(),+ markers: v+ .get("markers")+ .and_then(Value::as_array)+ .map(|a| a.iter().filter_map(Value::as_str).map(String::from).collect())+ .unwrap_or_default(),+ }+ }++ pub fn to_value(&self) -> Value {+ json!({+ "title": self.title,+ "textChars": self.text_chars,+ "href": self.href,+ "markers": self.markers,+ })+ }+}++/// The main document's HTTP response (the last one for the main frame, so+/// after redirects). `headers` names are lowercased.+#[derive(Debug, Clone, Default, PartialEq)]+pub struct DocumentResponse {+ pub url: String,+ pub status: u16,+ pub headers: Vec<(String, String)>,+}++impl DocumentResponse {+ /// From a CDP `Network.Response` object.+ pub fn from_cdp(response: &Value) -> Option<DocumentResponse> {+ let status = response.get("status").and_then(Value::as_f64)?;+ let headers = response+ .get("headers")+ .and_then(Value::as_object)+ .map(|m| {+ m.iter()+ .map(|(k, v)| {+ (+ k.to_ascii_lowercase(),+ v.as_str().map(String::from).unwrap_or_else(|| v.to_string()),+ )+ })+ .collect()+ })+ .unwrap_or_default();+ Some(DocumentResponse {+ url: response.get("url").and_then(Value::as_str).unwrap_or("").to_string(),+ status: status.max(0.0) as u16,+ headers,+ })+ }++ pub fn header(&self, name: &str) -> Option<&str> {+ self.headers+ .iter()+ .find(|(k, _)| k == name)+ .map(|(_, v)| v.as_str())+ }++ pub fn to_value(&self) -> Value {+ let headers: serde_json::Map<String, Value> = self+ .headers+ .iter()+ .map(|(k, v)| (k.clone(), Value::String(v.clone())))+ .collect();+ json!({ "url": self.url, "status": self.status, "headers": headers })+ }+}++#[derive(Debug, Clone, Copy, PartialEq, Eq)]+pub enum BlockKind {+ /// A bot challenge, captcha, or WAF block page.+ Challenge,+ /// The server answered with a 4xx/5xx status.+ HttpError,+}++impl BlockKind {+ pub fn as_str(self) -> &'static str {+ match self {+ BlockKind::Challenge => "challenge",+ BlockKind::HttpError => "http-error",+ }+ }+}++#[derive(Debug, Clone, PartialEq)]+pub enum PageValidity {+ Ok,+ Blocked {+ kind: BlockKind,+ /// Human-readable signals, in the order they were checked.+ evidence: Vec<String>,+ },+}++impl PageValidity {+ pub fn is_blocked(&self) -> bool {+ matches!(self, PageValidity::Blocked { .. })+ }++ pub fn to_value(&self) -> Value {+ match self {+ PageValidity::Ok => json!({ "status": "ok" }),+ PageValidity::Blocked { kind, evidence } => {+ json!({ "status": kind.as_str(), "evidence": evidence })+ }+ }+ }++ /// The error the CLI prints for a blocked page, or `None` when it is fine.+ pub fn error_message(&self) -> Option<String> {+ let PageValidity::Blocked { kind, evidence } = self else {+ return None;+ };+ let signals = evidence.join(", ");+ Some(match kind {+ BlockKind::Challenge => format!(+ "the page is a bot challenge, not the site ({signals}). Findings would describe the challenge page, so none are reported."+ ),+ BlockKind::HttpError => format!(+ "the page returned an error ({signals}). Findings would describe the error page, so none are reported."+ ),+ })+ }+}++/// Classify a loaded page. `response` is `None` when no main-document+/// response was seen (a `file://` URL, or a same-document navigation).+pub fn classify(response: Option<&DocumentResponse>, probe: &PageProbe) -> PageValidity {+ let mut challenge: Vec<String> = Vec::new();+ if let Some(r) = response {+ if let Some(action) = r.header("x-amzn-waf-action") {+ challenge.push(format!("x-amzn-waf-action: {action}"));+ }+ if let Some(v) = r.header("cf-mitigated") {+ if v.eq_ignore_ascii_case("challenge") {+ challenge.push("cf-mitigated: challenge".to_string());+ }+ }+ }+ if let Ok(final_url) = url::Url::parse(&probe.href) {+ if let Some(host) = final_url.host_str() {+ let host = host.to_ascii_lowercase();+ if CHALLENGE_HOSTS+ .iter()+ .any(|h| host == *h || host.ends_with(&format!(".{h}")))+ {+ challenge.push(format!("challenge host {host}"));+ }+ }+ }+ let small = probe.text_chars <= SMALL_PAGE_CHARS;+ if small {+ let title = probe.title.trim().to_lowercase();+ if !title.is_empty() && CHALLENGE_TITLE_PREFIXES.iter().any(|p| title.starts_with(p)) {+ challenge.push(format!("title \"{}\"", probe.title.trim()));+ }+ for m in &probe.markers {+ challenge.push(format!("marker {m}"));+ }+ }+ let status = response.map(|r| r.status).unwrap_or(0);+ if !challenge.is_empty() {+ if status >= 400 {+ challenge.insert(0, format!("HTTP {status}"));+ }+ return PageValidity::Blocked {+ kind: BlockKind::Challenge,+ evidence: challenge,+ };+ }+ if status >= 400 {+ return PageValidity::Blocked {+ kind: BlockKind::HttpError,+ evidence: vec![format!("HTTP {status}")],+ };+ }+ PageValidity::Ok+}++#[cfg(test)]+mod tests {+ use super::*;++ fn resp(status: u16, headers: &[(&str, &str)]) -> DocumentResponse {+ DocumentResponse {+ url: "https://example.com/".into(),+ status,+ headers: headers.iter().map(|(k, v)| (k.to_string(), v.to_string())).collect(),+ }+ }++ fn probe(title: &str, text_chars: u64, markers: &[&str]) -> PageProbe {+ PageProbe {+ title: title.into(),+ text_chars,+ href: "https://example.com/".into(),+ markers: markers.iter().map(|m| m.to_string()).collect(),+ }+ }++ #[test]+ fn aws_waf_captcha_is_a_challenge() {+ // siemens.com, 2026-09-11: CloudFront answered 405 with a captcha page.+ let v = classify(+ Some(&resp(405, &[("x-amzn-waf-action", "captcha")])),+ &probe("Human Verification", 120, &[]),+ );+ assert_eq!(+ v,+ PageValidity::Blocked {+ kind: BlockKind::Challenge,+ evidence: vec![+ "HTTP 405".into(),+ "x-amzn-waf-action: captcha".into(),+ "title \"Human Verification\"".into(),+ ],+ }+ );+ assert!(v.error_message().unwrap().starts_with("the page is a bot challenge"));+ }++ #[test]+ fn cloudflare_interstitial_title_on_a_small_page() {+ let v = classify(Some(&resp(403, &[])), &probe("Just a moment...", 80, &[]));+ assert!(matches!(v, PageValidity::Blocked { kind: BlockKind::Challenge, .. }));+ }++ #[test]+ fn cf_mitigated_header_alone_is_enough() {+ let v = classify(+ Some(&resp(200, &[("cf-mitigated", "challenge")])),+ &probe("Example", 20000, &[]),+ );+ assert!(matches!(v, PageValidity::Blocked { kind: BlockKind::Challenge, .. }));+ }++ #[test]+ fn challenge_title_on_a_content_page_is_content() {+ let v = classify(Some(&resp(200, &[])), &probe("Access denied: a novel", 40000, &[]));+ assert_eq!(v, PageValidity::Ok);+ }++ #[test]+ fn captcha_marker_on_a_content_page_is_content() {+ let v = classify(Some(&resp(200, &[])), &probe("Sign up", 9000, &["slider-captcha"]));+ assert_eq!(v, PageValidity::Ok);+ }++ #[test]+ fn marker_on_a_small_page_is_a_challenge() {+ let v = classify(Some(&resp(200, &[])), &probe("", 40, &["datadome-captcha"]));+ assert_eq!(+ v,+ PageValidity::Blocked {+ kind: BlockKind::Challenge,+ evidence: vec!["marker datadome-captcha".into()],+ }+ );+ }++ #[test]+ fn radware_redirect_host_is_a_challenge() {+ // yad2.co.il, 2026-09-11: a 302 to validate.perfdrive.com, which answers 200.+ let mut p = probe("Radware Bot Manager Block", 300, &[]);+ p.href = "https://validate.perfdrive.com/ccb4768f/?ssa=1".into();+ let v = classify(Some(&resp(200, &[])), &p);+ assert_eq!(+ v,+ PageValidity::Blocked {+ kind: BlockKind::Challenge,+ evidence: vec![+ "challenge host validate.perfdrive.com".into(),+ "title \"Radware Bot Manager Block\"".into(),+ ],+ }+ );+ }++ #[test]+ fn http_error_without_challenge_signals() {+ let v = classify(Some(&resp(404, &[])), &probe("Page not found", 400, &[]));+ assert_eq!(+ v,+ PageValidity::Blocked {+ kind: BlockKind::HttpError,+ evidence: vec!["HTTP 404".into()],+ }+ );+ assert!(v.error_message().unwrap().contains("HTTP 404"));+ }++ #[test]+ fn ordinary_pages_and_file_urls_pass() {+ assert_eq!(classify(Some(&resp(200, &[])), &probe("Stripe", 12000, &[])), PageValidity::Ok);+ assert_eq!(classify(None, &probe("fixture", 10, &[])), PageValidity::Ok);+ }++ #[test]+ fn response_from_cdp_lowercases_headers() {+ let r = DocumentResponse::from_cdp(&json!({+ "url": "https://example.com/",+ "status": 405,+ "headers": { "X-Amzn-Waf-Action": "captcha", "Server": "CloudFront" },+ }))+ .unwrap();+ assert_eq!(r.status, 405);+ assert_eq!(r.header("x-amzn-waf-action"), Some("captcha"));+ }++ #[test]+ fn probe_js_embeds_every_marker() {+ let js = probe_js();+ for (selector, label) in CHALLENGE_MARKERS {+ assert!(js.contains(label));+ assert!(js.contains(&selector.replace('\'', "'")));+ }+ }+}diff --git a/crates/browser/tests/evidence.rs b/crates/browser/tests/evidence.rsnew file mode 100644index 000000000..08ba2d9cb--- /dev/null+++ b/crates/browser/tests/evidence.rs@@ -0,0 +1,204 @@+//! The validity gate, evidence scans, and replay, against an installed+//! browser. Skips cleanly when there is none.+//!+//! - A bot challenge or an HTTP error page is refused with an error by the+//! CLI path and recorded (no findings, a screenshot) by the evidence path.+//! - An evidence scan reports the same findings as the CLI path, each named+//! by its element.+//! - Replaying the recorded captures with no browser reproduces the+//! deterministic passes' findings exactly, with no unanswered hit tests.++use std::collections::HashMap;+use std::io::{Read, Write};+use std::net::{TcpListener, TcpStream};+use std::path::{Path, PathBuf};++use impeccable_browser::{+ detect_url_evidence, origin, replay_url_scan, BrowserEngine, EvidenceRequest,+};+use impeccable_detect::engines::{ScanOptions, UrlEngine};++const CHALLENGE: &str = "<!doctype html><html><head><title>Human Verification</title></head><body><div id=\"captcha-container\">Please verify you are human.</div></body></html>";+const NOT_FOUND: &str = "<!doctype html><html><head><title>Not found</title></head><body><h1>Nothing here</h1></body></html>";++/// Fixtures that exercise the scan pass, hit tests (text-occlusion), and the+/// post-reveal content-hidden measure.+const REPLAY_FIXTURES: &[&str] = &[+ "should-flag.html",+ "text-occlusion.html",+ "reveal-working.html",+ "typography-should-flag.html",+ "quality.html",+ "layout.html",+];++fn fixtures_dir() -> PathBuf {+ Path::new(env!("CARGO_MANIFEST_DIR")).join("../../tests/fixtures/antipatterns")+}++fn serve() -> u16 {+ let listener = TcpListener::bind("127.0.0.1:0").expect("bind");+ let port = listener.local_addr().unwrap().port();+ std::thread::spawn(move || {+ for stream in listener.incoming().flatten() {+ std::thread::spawn(move || handle(stream));+ }+ });+ port+}++fn respond(stream: &mut TcpStream, status: &str, extra_headers: &str, content_type: &str, body: &[u8]) {+ let head = format!(+ "HTTP/1.0 {status}\r\nContent-Type: {content_type}\r\nContent-Length: {}\r\n{extra_headers}Connection: close\r\n\r\n",+ body.len()+ );+ let _ = stream.write_all(head.as_bytes());+ let _ = stream.write_all(body);+ let _ = stream.flush();+}++fn handle(mut stream: TcpStream) {+ let mut buf = [0u8; 8192];+ let n = stream.read(&mut buf).unwrap_or(0);+ let request = String::from_utf8_lossy(&buf[..n]);+ let path = request+ .lines()+ .next()+ .and_then(|l| l.split_whitespace().nth(1))+ .unwrap_or("/")+ .split('?')+ .next()+ .unwrap_or("/")+ .to_string();+ match path.as_str() {+ "/blocked" => respond(+ &mut stream,+ "405 Method Not Allowed",+ "x-amzn-waf-action: captcha\r\n",+ "text/html; charset=utf-8",+ CHALLENGE.as_bytes(),+ ),+ "/missing" => respond(&mut stream, "404 Not Found", "", "text/html; charset=utf-8", NOT_FOUND.as_bytes()),+ _ => {+ let rel = path.trim_start_matches('/');+ let file = fixtures_dir().join(rel);+ match std::fs::read(&file) {+ Ok(body) => {+ let ct = if rel.ends_with(".css") { "text/css" } else { "text/html; charset=utf-8" };+ respond(&mut stream, "200 OK", "", ct, &body)+ }+ Err(_) => respond(&mut stream, "404 Not Found", "", "text/plain", b"missing"),+ }+ }+ }+}++fn engine() -> Option<BrowserEngine> {+ let env: HashMap<String, String> = std::env::vars().collect();+ if impeccable_browser::discovery::find_browser(&env).is_err() {+ eprintln!("skip: no installed browser found");+ return None;+ }+ Some(BrowserEngine::new(env))+}++#[test]+fn blocked_pages_are_refused_by_the_cli_path_and_recorded_by_evidence() {+ let Some(engine) = engine() else { return };+ let port = serve();+ let options = ScanOptions::default();++ let blocked = format!("http://127.0.0.1:{port}/blocked");+ let err = engine.detect_url(&blocked, &options).expect_err("challenge page must not scan");+ assert!(err.message.contains("bot challenge"), "{}", err.message);+ assert!(err.message.contains("HTTP 405"), "{}", err.message);+ assert!(err.message.contains("x-amzn-waf-action: captcha"), "{}", err.message);++ let missing = format!("http://127.0.0.1:{port}/missing");+ let err = engine.detect_url(&missing, &options).expect_err("error page must not scan");+ assert!(err.message.contains("HTTP 404"), "{}", err.message);++ let mut browser = engine.launch().expect("launch");+ let (findings, evidence) =+ detect_url_evidence(&mut browser, &blocked, &options, "load", 100, &EvidenceRequest::default())+ .expect("evidence scan of a blocked page is Ok");+ browser.close();+ assert!(findings.is_empty());+ assert!(evidence.validity.as_ref().unwrap().is_blocked());+ assert_eq!(evidence.response.as_ref().unwrap().status, 405);+ assert!(evidence.scan_snapshot.is_none());+ assert!(evidence.screenshot.is_some(), "{:?}", evidence.screenshot_error);+}++#[test]+fn evidence_matches_the_cli_path_and_replay_matches_live() {+ let Some(engine) = engine() else { return };+ let port = serve();+ let options = ScanOptions::default();+ let mut browser = engine.launch().expect("launch");++ for name in REPLAY_FIXTURES {+ if !fixtures_dir().join(name).exists() {+ eprintln!("skip fixture {name}: not present");+ continue;+ }+ let url = format!("http://127.0.0.1:{port}/{name}");+ let cli = engine.detect_url(&url, &options).expect("cli scan");+ let (live, evidence) =+ detect_url_evidence(&mut browser, &url, &options, "networkidle0", 0, &EvidenceRequest::default())+ .expect("evidence scan");++ let strip = |f: &impeccable_core::findings::Finding| {+ (f.antipattern.clone(), f.snippet.clone())+ };+ // The visual-contrast pass samples pixels, so compare the passes that+ // do not: everything but visual-contrast must match the CLI path.+ let non_visual = |fs: &[impeccable_core::findings::Finding], origins: Option<&[&str]>| -> Vec<(String, String)> {+ fs.iter()+ .enumerate()+ .filter(|(i, f)| match origins {+ Some(o) => o[*i] != origin::VISUAL_CONTRAST,+ None => f.antipattern != "low-contrast" || f.extras.get("selector").is_some(),+ })+ .map(|(_, f)| strip(f))+ .collect()+ };+ assert_eq!(evidence.origins.len(), live.len());+ let live_scan: Vec<(String, String)> = non_visual(&live, Some(&evidence.origins));+ let cli_all: Vec<(String, String)> = cli.iter().map(strip).collect();+ for item in &live_scan {+ assert!(cli_all.contains(item), "{name}: evidence finding {item:?} missing from the CLI path");+ }++ let scan_findings = live.iter().zip(&evidence.origins).filter(|(_, o)| **o == origin::SCAN);+ for (f, _) in scan_findings {+ assert!(f.extras.get("selector").is_some(), "{name}: {} has no selector", f.antipattern);+ }+ assert!(evidence.screenshot.is_some(), "{name}: {:?}", evidence.screenshot_error);+ if live.iter().any(|f| f.extras.get("selector").is_some()) {+ assert!(!evidence.element_rects.is_empty(), "{name}: no element rects");+ }++ let replay = replay_url_scan(+ &url,+ evidence.scan_snapshot.as_deref().expect("scan snapshot"),+ &evidence.scan_facts,+ evidence+ .reveal_snapshot+ .as_deref()+ .map(|s| (s, &evidence.reveal_facts)),+ &options,+ )+ .expect("replay");+ let replayable: Vec<&impeccable_core::findings::Finding> = live+ .iter()+ .zip(&evidence.origins)+ .filter(|(_, o)| **o == origin::SCAN || **o == origin::CONTENT_HIDDEN)+ .map(|(f, _)| f)+ .collect();+ let replayed: Vec<&impeccable_core::findings::Finding> = replay.findings.iter().collect();+ assert_eq!(replayed, replayable, "{name}: replay differs from the live scan");+ assert_eq!(replay.unanswered_hit_tests, 0, "{name}: unanswered hit tests");+ }+ browser.close();+}diff --git a/docs/CLI-CONTRACT.md b/docs/CLI-CONTRACT.mdindex 7d1f89d76..68bd4f25c 100644--- a/docs/CLI-CONTRACT.md+++ b/docs/CLI-CONTRACT.md@@ -193,7 +193,9 @@ whose browser setup or scan throws, a path `statSync` cannot reachin a dir walk, and a per-file scan that throws(`stderr> Error: cannot scan <target>: <message>`). A multi-URL scan whoseshared browser fails to launch prints its `Error:` once and skips every URL-target.+target. A URL whose loaded page is a bot challenge or an HTTP error page is+also a failure to scan (see **Page validity gate** under URL scans): it+reports no findings and prints `stderr> Error: the page is ...`.**Output and exit codes**:- `allFindings.length > 0`:@@ -326,6 +328,9 @@ Optional keys added later by engines (appended after the above): `ignoreValue` (- 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.- 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):**+ - **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.- `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`.