@capagents/forgeqe 0.0.0-stage → 1.0.1

package/py/forgeqe_engine/diagnostics.py

@@ -0,0 +1,609 @@
+"""
+What went wrong in the browser during a run, for the report and for bugs: console errors, uncaught exceptions, failed
+and slow requests (Chrome's own log and resource timing), accessibility checks on each page (Chrome's accessibility
+tree, WCAG contrast), and where each action landed on the page the model saw.
+"""
+from __future__ import annotations
+
+import asyncio
+import base64
+import json
+import logging
+import re
+import time
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Set, Tuple
+from urllib.parse import urlsplit
+
+from .network import NetworkCapture, hook
+
+logger = logging.getLogger(__name__)
+
+SLOW_MS = 3000
+MAX_EVENTS = 500
+MAX_PAGES = 25
+MAX_EXAMPLES = 5
+CHECK_TIMEOUT = 10.0
+PROBLEMS_PER_STEP = 25
+
+INTERACTIVE_ROLES = {
+    "button": ("button-name", "4.1.2", "critical", "Buttons need a name a screen reader can announce"),
+    "link": ("link-name", "2.4.4", "serious", "Links need text that says where they go"),
+    "textbox": ("label", "1.3.1", "critical", "Form fields need a label"),
+    "searchbox": ("label", "1.3.1", "critical", "Form fields need a label"),
+    "combobox": ("label", "1.3.1", "critical", "Form fields need a label"),
+    "listbox": ("label", "1.3.1", "critical", "Form fields need a label"),
+    "spinbutton": ("label", "1.3.1", "critical", "Form fields need a label"),
+    "slider": ("label", "1.3.1", "critical", "Form fields need a label"),
+    "checkbox": ("label", "1.3.1", "critical", "Form fields need a label"),
+    "radio": ("label", "1.3.1", "critical", "Form fields need a label"),
+    "switch": ("label", "1.3.1", "critical", "Form fields need a label"),
+    "menuitem": ("button-name", "4.1.2", "serious", "Menu items need a name a screen reader can announce"),
+    "tab": ("button-name", "4.1.2", "serious", "Tabs need a name a screen reader can announce"),
+}
+IMAGE_ROLES = {"image", "img"}
+
+RESOURCES_JS = """(() => {
+  const o = performance.timeOrigin, out = [];
+  for (const e of [...performance.getEntriesByType('navigation'), ...performance.getEntriesByType('resource')]) {
+    const status = e.responseStatus || 0;
+    if (e.duration >= %d || status >= 400) out.push({url: e.name, type: e.initiatorType || e.entryType, ms: Math.round(e.duration), status, t: (o + e.startTime) / 1000});
+  }
+  return out;
+})()""" % SLOW_MS
+
+# WCAG 1.4.3 contrast on visible text, the page language (3.1.1) and zoom (1.4.4). Text over a background image or
+# gradient is skipped: its background colour is not known.
+PAGE_CHECKS_JS = r"""(() => {
+  const parse = (c) => { const m = c.match(/rgba?\(([^)]+)\)/); if (!m) return null; const p = m[1].split(/[ ,\/]+/).filter(Boolean).map(Number); return [p[0], p[1], p[2], p.length > 3 ? p[3] : 1]; };
+  const lum = ([r, g, b]) => { const f = (v) => { v /= 255; return v <= 0.03928 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4); }; return 0.2126 * f(r) + 0.7152 * f(g) + 0.0722 * f(b); };
+  const blend = (top, under) => { const a = top[3]; return [top[0] * a + under[0] * (1 - a), top[1] * a + under[1] * (1 - a), top[2] * a + under[2] * (1 - a), 1]; };
+  const background = (el) => {
+    const layers = [];
+    for (let n = el; n && n.nodeType === 1; n = n.parentElement) {
+      const s = getComputedStyle(n);
+      if (s.backgroundImage && s.backgroundImage !== 'none') return null;
+      const c = parse(s.backgroundColor);
+      if (c && c[3] > 0) { layers.push(c); if (c[3] >= 1) break; }
+    }
+    let bg = [255, 255, 255, 1];
+    for (let i = layers.length - 1; i >= 0; i--) bg = blend(layers[i], bg);
+    return bg;
+  };
+  const low = [];
+  let checked = 0;
+  const walker = document.createTreeWalker(document.body || document.documentElement, NodeFilter.SHOW_TEXT);
+  const seen = new Set();
+  while (walker.nextNode() && checked < 600) {
+    const t = walker.currentNode, el = t.parentElement;
+    if (!el || seen.has(el) || !t.textContent.trim()) continue;
+    seen.add(el);
+    const r = el.getBoundingClientRect();
+    if (r.width < 1 || r.height < 1) continue;
+    const s = getComputedStyle(el);
+    if (s.visibility === 'hidden' || s.display === 'none' || Number(s.opacity) === 0) continue;
+    checked++;
+    const bg = background(el), fg0 = parse(s.color);
+    if (!bg || !fg0) continue;
+    const fg = blend(fg0, bg);
+    const a = lum(fg), b = lum(bg);
+    const ratio = (Math.max(a, b) + 0.05) / (Math.min(a, b) + 0.05);
+    const size = parseFloat(s.fontSize), bold = Number(s.fontWeight) >= 700;
+    const need = size >= 24 || (bold && size >= 18.66) ? 3 : 4.5;
+    if (ratio < need) low.push({html: el.outerHTML.slice(0, 160), text: t.textContent.trim().slice(0, 80), ratio: Math.round(ratio * 100) / 100, need});
+  }
+  const vp = document.querySelector('meta[name="viewport"]');
+  const vpc = vp ? vp.getAttribute('content') || '' : '';
+  const maxScale = (vpc.match(/maximum-scale\s*=\s*([\d.]+)/) || [])[1];
+  return {lang: document.documentElement.getAttribute('lang') || '', contrast: low, checked,
+          noZoom: /user-scalable\s*=\s*(no|0)/i.test(vpc) || (maxScale !== undefined && Number(maxScale) < 2), viewport: vpc};
+})()"""
+
+
+# Core Web Vitals, observed from the start of each document (buffered entries cover a page that loaded before this ran).
+# INP is the slowest interaction seen, close to the real p98 for the few interactions a run makes.
+VITALS_INIT = r"""(() => {
+  if (window.__wpVitals) return;
+  const v = window.__wpVitals = {lcp: null, cls: 0, inp: null, fcp: null};
+  const watch = (type, cb, extra) => { try { new PerformanceObserver((l) => l.getEntries().forEach(cb)).observe({type, buffered: true, ...(extra || {})}); } catch (e) {} };
+  watch('largest-contentful-paint', (e) => { v.lcp = e.renderTime || e.loadTime || e.startTime; });
+  let session = 0, start = 0, last = 0;
+  watch('layout-shift', (e) => {
+    if (e.hadRecentInput) return;
+    if (e.startTime - last < 1000 && e.startTime - start < 5000) session += e.value; else { session = e.value; start = e.startTime; }
+    last = e.startTime; v.cls = Math.max(v.cls, session);
+  });
+  watch('paint', (e) => { if (e.name === 'first-contentful-paint') v.fcp = e.startTime; });
+  watch('event', (e) => { if (e.interactionId) v.inp = Math.max(v.inp || 0, e.duration); }, {durationThreshold: 16});
+  watch('first-input', (e) => { v.inp = Math.max(v.inp || 0, e.duration); });
+})()"""
+
+VITALS_READ = r"""(() => {
+  const v = window.__wpVitals;
+  const n = performance.getEntriesByType('navigation')[0] || {};
+  const r = performance.getEntriesByType('resource');
+  const fcp = (performance.getEntriesByName('first-contentful-paint')[0] || {}).startTime;
+  const ms = (x) => (typeof x === 'number' && x > 0 ? Math.round(x) : null);
+  return {url: location.href, observed: !!v, lcp: ms(v && v.lcp), cls: v ? Math.round(v.cls * 1000) / 1000 : null, inp: ms(v && v.inp),
+          fcp: ms((v && v.fcp) || fcp), ttfb: ms(n.responseStart), dcl: ms(n.domContentLoadedEventEnd), load: ms(n.loadEventEnd),
+          requests: r.length, kb: Math.round((r.reduce((a, x) => a + (x.transferSize || 0), 0) + (n.transferSize || 0)) / 1024)};
+})()"""
+
+# axe-core results, small: each violated rule with up to five elements, and the ids of the rules that passed.
+AXE_RUN = r"""axe.run(document, {runOnly: {type: 'tag', values: %s}, resultTypes: ['violations']}).then((r) => ({
+  version: r.testEngine && r.testEngine.version,
+  passed: r.passes.map((p) => p.id),
+  incomplete: r.incomplete.map((p) => p.id),
+  violations: r.violations.map((v) => ({id: v.id, impact: v.impact, help: v.help, helpUrl: v.helpUrl, tags: v.tags, count: v.nodes.length,
+    examples: v.nodes.slice(0, 5).map((n) => ({html: (n.html || '').slice(0, 160), target: (n.target || []).join(' '), text: (n.failureSummary || '').slice(0, 300)}))}))
+}))"""
+
+WCAG_SC = re.compile(r"^wcag(\d)(\d)(\d{1,2})$")
+WCAG_LEVEL = re.compile(r"^wcag2\d?(a{1,3})$")
+
+
+def wcag_of(tags: List[str]) -> Tuple[str, str]:
+    """The success criteria (1.4.3) and the level (A, AA, AAA) an axe rule's tags name."""
+    criteria = [".".join(m.groups()) for m in (WCAG_SC.match(t) for t in tags) if m]
+    levels = [m.group(1).upper() for m in (WCAG_LEVEL.match(t) for t in tags) if m]
+    return ", ".join(criteria), (min(levels, key=len) if levels else "")
+
+
+# Visual captures: animations, transitions and the text caret are frozen, and masked regions are hidden (their space
+# kept), so a page compares with its baseline on what changed, not on what moves.
+VISUAL_PREP = r"""((selectors) => {
+  const old = document.getElementById('__wp_visual'); if (old) old.remove();
+  const s = document.createElement('style'); s.id = '__wp_visual';
+  s.textContent = '*,*::before,*::after{animation-play-state:paused!important;animation-delay:-0.0001s!important;transition:none!important;caret-color:transparent!important;scroll-behavior:auto!important}'
+    + (selectors.length ? selectors.join(',') + '{visibility:hidden!important}' : '');
+  (document.head || document.documentElement).appendChild(s);
+  return true;
+})(%s)"""
+VISUAL_DONE = "(() => { const s = document.getElementById('__wp_visual'); if (s) s.remove(); })()"
+MAX_FULL_HEIGHT = 8000
+
+
+def masks_for(url: str, visual: Dict[str, Any]) -> List[str]:
+    """The selectors to mask on a page: the global ones, and those of every path prefix the page is under."""
+    path = urlsplit(url).path or "/"
+    out = [str(s) for s in (visual.get("mask") or [])]
+    for prefix, sels in (visual.get("pages") or {}).items():
+        if path == prefix or path.startswith(prefix.rstrip("/") + "/") or (prefix != "/" and path.startswith(prefix)):
+            out += [str(s) for s in (sels or [])]
+    return out
+
+
+def _page_key(url: str) -> str:
+    try:
+        u = urlsplit(url)
+    except ValueError:
+        return url
+    return f"{u.scheme}://{u.netloc}{u.path or '/'}"
+
+
+def _prop(node: Dict[str, Any], name: str) -> Any:
+    for p in node.get("properties") or []:
+        if p.get("name") == name:
+            return (p.get("value") or {}).get("value")
+    return None
+
+
+def _value(field: Any) -> str:
+    return str((field or {}).get("value") or "").strip() if isinstance(field, dict) else ""
+
+
+def box_for(browser_state: Any, index: Any) -> Optional[Dict[str, float]]:
+    """Where the element at a selector-map index sat in the viewport screenshot, as fractions of its width and height."""
+    try:
+        node = browser_state.dom_state.selector_map.get(int(index))
+        pos = getattr(node, "absolute_position", None)
+        info = getattr(browser_state, "page_info", None)
+        if pos is None or info is None or not info.viewport_width or not info.viewport_height:
+            return None
+        vw, vh = float(info.viewport_width), float(info.viewport_height)
+        x, y = (pos.x - info.scroll_x) / vw, (pos.y - info.scroll_y) / vh
+        w, h = pos.width / vw, pos.height / vh
+    except Exception:
+        return None
+    if w <= 0 or h <= 0 or x >= 1 or y >= 1 or x + w <= 0 or y + h <= 0:
+        return None
+    x0, y0 = max(0.0, x), max(0.0, y)
+    return {"x": round(x0, 4), "y": round(y0, 4), "w": round(min(1.0, x + w) - x0, 4), "h": round(min(1.0, y + h) - y0, 4)}
+
+
+class Diagnostics:
+    def __init__(self, *, accessibility: bool = True, network: bool = True, axe: Optional[Dict[str, Any]] = None, vitals: bool = True, visual: Optional[Dict[str, Any]] = None) -> None:
+        self.accessibility = accessibility
+        # axe-core: {"script": path to axe.min.js, "tags": ["wcag2a", "wcag2aa"]}; without it, the built-in checks.
+        self.axe_tags: List[str] = [str(t) for t in ((axe or {}).get("tags") or ["wcag2a", "wcag2aa"])]
+        self._axe_source: Optional[str] = None
+        if axe and axe.get("script"):
+            try:
+                self._axe_source = Path(str(axe["script"])).read_text(encoding="utf-8")
+            except OSError:
+                logger.warning("axe-core not found at %s: using the built-in accessibility checks", axe.get("script"))
+        self.vitals = vitals
+        self.perf: Dict[str, Dict[str, Any]] = {}
+        # {"mask": [selectors], "pages": {"/path": [selectors]}, "full_page": bool}; None: no visual captures.
+        self.visual: Optional[Dict[str, Any]] = visual
+        self.shots: Dict[str, Dict[str, Any]] = {}
+        self.timeout = CHECK_TIMEOUT * (3 if self._axe_source else 1)
+        self.network: Optional[NetworkCapture] = NetworkCapture() if network else None
+        self._net_handlers: Dict[str, Any] = {}
+        self.events: List[Dict[str, Any]] = []
+        self.pages: Dict[str, Dict[str, Any]] = {}
+        self._client: Any = None
+        self._sessions: Set[str] = set()
+        self._resources: Set[Tuple[str, int]] = set()
+        self._lock = asyncio.Lock()
+
+    # -- Chrome events ------------------------------------------------------------------------
+
+    def _add(self, event: Dict[str, Any]) -> None:
+        if len(self.events) >= MAX_EVENTS:
+            return
+        for e in self.events[-60:]:
+            if all(e.get(k) == event.get(k) for k in ("kind", "text", "url", "status")) and abs(e["t"] - event["t"]) < 30:
+                e["count"] = e.get("count", 1) + 1
+                return
+        self.events.append(event)
+
+    @staticmethod
+    def _when(ms: Any) -> float:
+        try:
+            v = float(ms)
+            return v / 1000 if v > 1e11 else v
+        except (TypeError, ValueError):
+            return time.time()
+
+    def _on_console(self, params: Any, session_id: Optional[str] = None) -> None:
+        try:
+            kind = str(params.get("type") or "")
+            if kind not in ("error", "assert", "warning"):
+                return
+            parts = []
+            for a in params.get("args") or []:
+                v = a.get("value")
+                parts.append(str(v) if v is not None else str(a.get("description") or a.get("unserializableValue") or a.get("type") or ""))
+            frames = ((params.get("stackTrace") or {}).get("callFrames") or [{}])
+            self._add({"t": self._when(params.get("timestamp")), "kind": "console", "level": "warning" if kind == "warning" else "error",
+                       "text": " ".join(parts).strip()[:500], "url": str(frames[0].get("url") or "")})
+        except Exception:
+            logger.debug("console event not read", exc_info=True)
+
+    def _on_exception(self, params: Any, session_id: Optional[str] = None) -> None:
+        try:
+            d = params.get("exceptionDetails") or {}
+            text = str((d.get("exception") or {}).get("description") or d.get("text") or "Uncaught exception")
+            self._add({"t": self._when(params.get("timestamp")), "kind": "exception", "level": "error",
+                       "text": text.strip()[:800], "url": str(d.get("url") or ""), **({"line": d["lineNumber"] + 1} if isinstance(d.get("lineNumber"), int) else {})})
+        except Exception:
+            logger.debug("exception event not read", exc_info=True)
+
+    def _on_log(self, params: Any, session_id: Optional[str] = None) -> None:
+        try:
+            e = params.get("entry") or {}
+            if e.get("level") != "error":
+                return
+            source = str(e.get("source") or "")
+            self._add({"t": self._when(e.get("timestamp")), "kind": "network" if source == "network" else "console", "level": "error",
+                       "text": str(e.get("text") or "").strip()[:500], "url": str(e.get("url") or ""), "source": source})
+        except Exception:
+            logger.debug("log entry not read", exc_info=True)
+
+    async def _session(self, browser: Any) -> Any:
+        client = getattr(browser, "cdp_client", None)
+        if client is None:
+            return None
+        if client is not self._client:
+            reg = client.register
+            reg.Runtime.consoleAPICalled(self._on_console)
+            reg.Runtime.exceptionThrown(self._on_exception)
+            reg.Log.entryAdded(self._on_log)
+            self._client = client
+            self._sessions.clear()
+            if self.network is not None:
+                net = self.network
+                self._net_handlers = {
+                    "Network.requestWillBeSent": net.on_request,
+                    "Network.responseReceived": net.on_response,
+                    "Network.loadingFinished": lambda p, s=None: net.on_finished(p, s, client),
+                    "Network.loadingFailed": net.on_failed,
+                }
+        # Hooked again on each call: a watchdog that registers later would otherwise replace these handlers.
+        for method, fn in self._net_handlers.items():
+            hook(client, method, fn)
+        session = await browser.get_or_create_cdp_session()
+        if session.session_id not in self._sessions:
+            self._sessions.add(session.session_id)
+            await session.cdp_client.send.Runtime.enable(session_id=session.session_id)
+            await session.cdp_client.send.Log.enable(session_id=session.session_id)
+            if self.network is not None:
+                await session.cdp_client.send.Network.enable(session_id=session.session_id)
+            if self.vitals:
+                try:
+                    await session.cdp_client.send.Page.addScriptToEvaluateOnNewDocument(params={"source": VITALS_INIT}, session_id=session.session_id)
+                except Exception:
+                    logger.debug("vitals script not added", exc_info=True)
+        return session
+
+    async def start(self, browser: Any) -> None:
+        """Listen from the first page on, so the calls the start page makes are recorded too."""
+        async with self._lock:
+            try:
+                await asyncio.wait_for(self._session(browser), timeout=CHECK_TIMEOUT)
+            except Exception:
+                logger.debug("diagnostics start failed", exc_info=True)
+
+    async def _eval(self, session: Any, expression: str) -> Any:
+        r = await session.cdp_client.send.Runtime.evaluate(
+            params={"expression": expression, "returnByValue": True}, session_id=session.session_id
+        )
+        return ((r or {}).get("result") or {}).get("value")
+
+    # -- per page -----------------------------------------------------------------------------
+
+    async def sample(self, browser: Any) -> None:
+        """Called after each step: pick up failed and slow requests, and check a page not seen before."""
+        async with self._lock:
+            try:
+                await asyncio.wait_for(self._sample(browser), timeout=self.timeout)
+            except Exception:
+                logger.debug("diagnostics sample failed", exc_info=True)
+
+    async def _sample(self, browser: Any) -> None:
+        session = await self._session(browser)
+        if session is None:
+            return
+        if self.network is not None:
+            await self.network.settle(2.0)
+        for r in await self._eval(session, RESOURCES_JS) or []:
+            key = (str(r.get("url")), int(float(r.get("t") or 0) * 1000))
+            if key in self._resources:
+                continue
+            self._resources.add(key)
+            url, status, t = str(r.get("url") or ""), int(r.get("status") or 0), float(r.get("t") or time.time())
+            if status >= 400:
+                logged = next((e for e in self.events if e["kind"] == "network" and e.get("url") == url and not e.get("status")), None)
+                if logged:
+                    logged["status"] = status
+                else:
+                    self._add({"t": t, "kind": "network", "level": "error", "text": f"HTTP {status}", "url": url, "status": status})
+            if int(r.get("ms") or 0) >= SLOW_MS:
+                self._add({"t": t, "kind": "slow", "level": "warning", "text": f"{r.get('type') or 'request'} took {int(r['ms']) / 1000:.1f}s",
+                           "url": url, "ms": int(r["ms"])})
+        if self.vitals:
+            await self._read_vitals(session)
+        if self.accessibility:
+            await self._check_page(browser, session)
+        if self.visual is not None:
+            await self._capture(session)
+
+    async def _capture(self, session: Any) -> None:
+        """The page as it is now, for comparison with its baseline. Each page keeps its last capture: the state the flow left it in."""
+        try:
+            url = str(await self._eval(session, "location.href") or "")
+        except Exception:
+            return
+        key = _page_key(url)
+        if not url.startswith("http") or (key not in self.shots and len(self.shots) >= MAX_PAGES):
+            return
+        send = session.cdp_client.send
+        try:
+            await self._eval(session, VISUAL_PREP % json.dumps(masks_for(url, self.visual or {})))
+            await asyncio.sleep(0.15)
+            params: Dict[str, Any] = {"format": "png", "fromSurface": True}
+            if (self.visual or {}).get("full_page"):
+                metrics = await send.Page.getLayoutMetrics(session_id=session.session_id)
+                size = (metrics or {}).get("cssContentSize") or (metrics or {}).get("contentSize") or {}
+                width, height = int(size.get("width") or 0), min(int(size.get("height") or 0), MAX_FULL_HEIGHT)
+                if width and height:
+                    params.update({"captureBeyondViewport": True, "clip": {"x": 0, "y": 0, "width": width, "height": height, "scale": 1}})
+            shot = await send.Page.captureScreenshot(params=params, session_id=session.session_id)
+            data = (shot or {}).get("data")
+            if data:
+                title = str(await self._eval(session, "document.title") or "")
+                self.shots[key] = {"url": url, "title": title, "png": base64.b64decode(data), "full_page": bool(params.get("clip"))}
+        except Exception:
+            logger.debug("visual capture failed", exc_info=True)
+        finally:
+            try:
+                await self._eval(session, VISUAL_DONE)
+            except Exception:
+                pass
+
+    def write_visual(self, out_dir: Path) -> Optional[str]:
+        """visual/<n>.png for each page, and visual.json listing them."""
+        if not self.shots:
+            return None
+        folder = out_dir / "visual"
+        folder.mkdir(parents=True, exist_ok=True)
+        index = []
+        for i, (key, s) in enumerate(self.shots.items(), 1):
+            name = f"{i:02d}-{re.sub(r'[^A-Za-z0-9]+', '-', urlsplit(key).path).strip('-')[:40] or 'home'}.png"
+            (folder / name).write_bytes(s["png"])
+            index.append({"page": key, "url": s["url"], "title": s["title"], "file": f"visual/{name}", "full_page": s["full_page"]})
+        file = out_dir / "visual.json"
+        file.write_text(json.dumps(index, indent=2), encoding="utf-8")
+        return str(file.resolve())
+
+    async def _read_vitals(self, session: Any) -> None:
+        """This page's timings so far: the worst across visits for shifts and interactions, the first load's for the rest."""
+        try:
+            v = await self._eval(session, VITALS_READ) or {}
+            if not v.get("observed"):
+                # A page that loaded before the script was added: observe now; buffered entries arrive by the next step.
+                await self._eval(session, VITALS_INIT)
+        except Exception:
+            logger.debug("vitals not read", exc_info=True)
+            return
+        url = str(v.get("url") or "")
+        if not url.startswith("http"):
+            return
+        key = _page_key(url)
+        if key not in self.perf and len(self.perf) >= MAX_PAGES:
+            return
+        p = self.perf.setdefault(key, {"url": url, "samples": 0})
+        p["samples"] += 1
+        for k in ("ttfb", "fcp", "dcl", "load"):
+            if p.get(k) is None and v.get(k) is not None:
+                p[k] = v[k]
+        if v.get("lcp") is not None:
+            p["lcp"] = max(p.get("lcp") or 0, v["lcp"])
+        for k in ("cls", "inp", "requests", "kb"):
+            if v.get(k) is not None:
+                p[k] = max(p.get(k) or 0, v[k])
+
+    async def _axe(self, session: Any) -> Optional[Dict[str, Any]]:
+        """axe-core's results for the page, or None when it could not run (the built-in checks run instead)."""
+        if not self._axe_source:
+            return None
+        try:
+            loaded = await self._eval(session, "typeof window.axe !== 'undefined'")
+            if not loaded:
+                await session.cdp_client.send.Runtime.evaluate(params={"expression": self._axe_source, "returnByValue": False}, session_id=session.session_id)
+            r = await session.cdp_client.send.Runtime.evaluate(
+                params={"expression": AXE_RUN % json.dumps(self.axe_tags), "returnByValue": True, "awaitPromise": True}, session_id=session.session_id
+            )
+            value = ((r or {}).get("result") or {}).get("value")
+            return value if isinstance(value, dict) and "violations" in value else None
+        except Exception:
+            logger.debug("axe-core did not run", exc_info=True)
+            return None
+
+    async def _check_page(self, browser: Any, session: Any) -> None:
+        try:
+            url = str(await browser.get_current_page_url() or "")
+        except Exception:
+            return
+        key = _page_key(url)
+        if not url.startswith("http") or key in self.pages or len(self.pages) >= MAX_PAGES:
+            return
+        send = session.cdp_client.send
+        order = {"critical": 0, "serious": 1, "moderate": 2, "minor": 3}
+        axe = await self._axe(session)
+        if axe is not None:
+            issues_list = []
+            for v in axe["violations"]:
+                criteria, level = wcag_of(list(v.get("tags") or []))
+                issues_list.append({"rule": v.get("id"), "wcag": criteria, "level": level, "impact": v.get("impact") or "minor", "help": v.get("help") or "",
+                                    "helpUrl": v.get("helpUrl") or "", "count": int(v.get("count") or 0), "examples": v.get("examples") or []})
+            title = ""
+            try:
+                title = str(await self._eval(session, "document.title") or "")
+            except Exception:
+                pass
+            self.pages[key] = {
+                "url": url,
+                "title": title,
+                "engine": f"axe-core {axe.get('version') or ''}".strip(),
+                "tags": self.axe_tags,
+                "passed": list(axe.get("passed") or []),
+                "incomplete": list(axe.get("incomplete") or []),
+                "issues": sorted(issues_list, key=lambda i: (order.get(i["impact"], 9), -i["count"])),
+            }
+            return
+        tree = await send.Accessibility.getFullAXTree(params={}, session_id=session.session_id)
+        nodes = [n for n in (tree or {}).get("nodes") or [] if not n.get("ignored")]
+        issues: Dict[str, Dict[str, Any]] = {}
+        title = ""
+
+        async def add(rule: str, wcag: str, impact: str, help_text: str, example: Dict[str, Any], backend: Optional[int] = None) -> None:
+            issue = issues.setdefault(rule, {"rule": rule, "wcag": wcag, "impact": impact, "help": help_text, "count": 0, "examples": []})
+            issue["count"] += 1
+            if len(issue["examples"]) >= MAX_EXAMPLES:
+                return
+            if backend and "html" not in example:
+                try:
+                    html = await send.DOM.getOuterHTML(params={"backendNodeId": backend}, session_id=session.session_id)
+                    example["html"] = str((html or {}).get("outerHTML") or "")[:160]
+                except Exception:
+                    pass
+            issue["examples"].append(example)
+
+        last_level = 0
+        for n in nodes:
+            role, name = _value(n.get("role")), _value(n.get("name"))
+            backend = n.get("backendDOMNodeId")
+            if role == "RootWebArea":
+                title = title or name
+                if not name:
+                    await add("document-title", "2.4.2", "serious", "Pages need a title", {"text": url})
+            elif role in INTERACTIVE_ROLES and not name:
+                rule, wcag, impact, help_text = INTERACTIVE_ROLES[role]
+                await add(rule, wcag, impact, help_text, {"role": role}, backend)
+            elif role in IMAGE_ROLES and not name:
+                await add("image-alt", "1.1.1", "critical", "Images need a text alternative (or alt=\"\" if decorative)", {"role": role}, backend)
+            elif role == "heading":
+                level = _prop(n, "level")
+                if isinstance(level, (int, float)):
+                    if last_level and level > last_level + 1:
+                        await add("heading-order", "1.3.1", "moderate", "Heading levels should go down one at a time",
+                                  {"text": f"h{last_level} then h{int(level)}: {name[:60]}"}, backend)
+                    last_level = int(level)
+
+        page = await self._eval(session, PAGE_CHECKS_JS) or {}
+        if not page.get("lang"):
+            await add("html-lang", "3.1.1", "serious", "The page needs a lang attribute on <html>", {"html": "<html>"})
+        for c in page.get("contrast") or []:
+            await add("color-contrast", "1.4.3", "serious", "Text needs enough contrast with its background",
+                      {"html": c.get("html"), "text": f"{c.get('text')} (contrast {c.get('ratio')}:1, needs {c.get('need')}:1)"})
+        if page.get("noZoom"):
+            await add("meta-viewport", "1.4.4", "critical", "Pages must let people zoom", {"html": f'<meta name="viewport" content="{page.get("viewport")}">'})
+
+        self.pages[key] = {
+            "url": url,
+            "title": title,
+            "engine": "forgeqe",
+            "checked": int(page.get("checked") or 0),
+            "issues": sorted(issues.values(), key=lambda i: (order.get(i["impact"], 9), -i["count"])),
+        }
+
+    # -- results ------------------------------------------------------------------------------
+
+    def summary(self) -> Dict[str, int]:
+        def total(kind: str, level: Optional[str] = None) -> int:
+            return sum(e.get("count", 1) for e in self.events if e["kind"] == kind and (level is None or e["level"] == level))
+
+        return {
+            "console_errors": total("console", "error") + total("exception"),
+            "console_warnings": total("console", "warning"),
+            "failed_requests": total("network"),
+            "slow_requests": total("slow"),
+            "pages_checked": len(self.pages),
+            "accessibility_issues": sum(i["count"] for p in self.pages.values() for i in p["issues"]),
+            **({"api_calls": len(self.network.calls)} if self.network is not None and self.network.calls else {}),
+            **({"pages_timed": len(self.perf)} if self.perf else {}),
+            **({"pages_captured": len(self.shots)} if self.shots else {}),
+        }
+
+    def write(self, out_dir: Path) -> Optional[str]:
+        if not self.pages:
+            return None
+        file = out_dir / "accessibility.json"
+        file.write_text(json.dumps(list(self.pages.values()), indent=2, ensure_ascii=False), encoding="utf-8")
+        return str(file.resolve())
+
+    def write_perf(self, out_dir: Path) -> Optional[str]:
+        if not self.perf:
+            return None
+        file = out_dir / "performance.json"
+        file.write_text(json.dumps(list(self.perf.values()), indent=2), encoding="utf-8")
+        return str(file.resolve())
+
+
+def assign_problems(entries: List[Dict[str, Any]], events: List[Dict[str, Any]]) -> None:
+    """Attach each browser problem to the timeline step it happened in (by the steps' start times)."""
+    if not entries or not events:
+        return
+    starts = [(e.get("t0"), e) for e in entries if isinstance(e.get("t0"), (int, float))]
+    for ev in sorted(events, key=lambda e: e["t"]):
+        owner = entries[0]
+        for t0, entry in starts:
+            if t0 <= ev["t"]:
+                owner = entry
+        bucket = owner.setdefault("problems", [])
+        if len(bucket) < PROBLEMS_PER_STEP:
+            bucket.append({k: v for k, v in ev.items() if k != "t"})
+        else:
+            owner["more_problems"] = owner.get("more_problems", 0) + ev.get("count", 1)