inspectra-engine 0.0.0-stage → 1.0.2

package/ui-check.js

@@ -0,0 +1,1493 @@
+import imageTools from "./scanner/legacy-image-tools.cjs";
+const { getPNG, getPixelmatch } = imageTools;
+import { chromium } from "playwright";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { OUTPUT_DIR, normalizeImageSize } from "./compare.js";
+import { fileURLToPath } from "node:url";
+
+const execFileAsync = promisify(execFile);
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export const VIEWPORTS = {
+  desktop1920: { name: "Desktop Full HD", width: 1920, height: 1080 },
+  desktop: { name: "Desktop", width: 1440, height: 900 },
+  laptop1366: { name: "Laptop", width: 1366, height: 768 },
+  tablet1024: { name: "Tablet Landscape", width: 1024, height: 768 },
+  tablet: { name: "Tablet", width: 768, height: 1024 },
+  mobile375: { name: "Mobile", width: 375, height: 667 },
+  mobile320: { name: "Mobile Small", width: 320, height: 568 },
+};
+
+const STYLE_PROPS = [
+  "fontFamily",
+  "fontSize",
+  "fontWeight",
+  "lineHeight",
+  "letterSpacing",
+  "wordSpacing",
+  "color",
+  "backgroundColor",
+  "borderRadius",
+  "borderTopWidth",
+  "paddingTop",
+  "paddingRight",
+  "paddingBottom",
+  "paddingLeft",
+];
+
+/**
+ * Runs inside the browser. Builds an inventory of UI components, finds layout problems and
+ * collects visible text. Never reports the *content* of dynamic copy/images, only structure.
+ */
+export function inspectPage({ props, ignore, snapshot = null }) {
+  const norm = (s) => String(s || "").toLowerCase().replace(/[^a-z0-9]+/g, " ").trim();
+  const skipTags = new Set(["SCRIPT", "STYLE", "NOSCRIPT", "TEMPLATE", "HEAD", "META", "LINK"]);
+
+  // Steppers / progress trackers have a different number of steps per flow, so they are never compared.
+  const AUTO_IGNORE =
+    "[class*=stepper i], [class*=step-i i], [class*=steps i], [class*=wizard i], [class*=progress i], [class*=breadcrumb i], [id*=stepper i], [role=progressbar], [aria-label*=stepper i], [aria-label*=progress i], [aria-label*=breadcrumb i]";
+  function isIgnored(el) {
+    try {
+      if (el.closest(AUTO_IGNORE)) return true;
+    } catch {
+      // ignore
+    }
+    if (!ignore) return false;
+    try {
+      return Boolean(el.closest(ignore));
+    } catch {
+      return false;
+    }
+  }
+  function clippedByAncestor(el) {
+    const r = el.getBoundingClientRect();
+    for (let p = el.parentElement; p && p !== document.body; p = p.parentElement) {
+      const cs = getComputedStyle(p);
+      const pr = p.getBoundingClientRect();
+      if (cs.display === "none" || cs.visibility === "hidden" || Number(cs.opacity) === 0) return true;
+      if (/hidden|clip|auto|scroll/.test(cs.overflowX) && (r.right <= pr.left || r.left >= pr.right)) return true;
+      if (/hidden|clip|auto|scroll/.test(cs.overflowY) && (r.bottom <= pr.top || r.top >= pr.bottom)) return true;
+    }
+    return false;
+  }
+  function containedHorizontally(el) {
+    const r = el.getBoundingClientRect();
+    for (let p = el.parentElement; p && p !== document.body; p = p.parentElement) {
+      const cs = getComputedStyle(p), pr = p.getBoundingClientRect();
+      if (/hidden|clip|auto|scroll/.test(cs.overflowX) && pr.left >= -2 && pr.right <= document.documentElement.clientWidth + 2 && (r.left < pr.left || r.right > pr.right)) return true;
+    }
+    return false;
+  }
+  function visible(el) {
+    const cs = getComputedStyle(el);
+    if (cs.display === "none" || cs.visibility === "hidden" || Number(cs.opacity) === 0) return false;
+    const r = el.getBoundingClientRect();
+    return r.width > 2 && r.height > 2 && !clippedByAncestor(el);
+  }
+  function label(el) {
+    let s = el.tagName.toLowerCase();
+    if (el.id) s += `#${el.id}`;
+    const cls = typeof el.className === "string" ? el.className.trim().split(/\s+/).filter(Boolean).slice(0, 2) : [];
+    if (cls.length) s += "." + cls.join(".");
+    return s;
+  }
+  function ownText(el) {
+    let t = "";
+    for (const c of el.childNodes) if (c.nodeType === 3) t += c.textContent;
+    return t.replace(/\s+/g, " ").trim();
+  }
+  function categoryKey(el, cs, repeated = null) {
+    const text = ownText(el);
+    if (!text || text.length > 80 || !/^inline/.test(cs.display) || el.closest("h1,h2,h3,h4,h5,h6") ||
+      el.matches("h1,h2,h3,h4,h5,h6,a[href],button,input,select,textarea,[role=button]") ||
+      ["transparent", "rgba(0, 0, 0, 0)"].includes(cs.backgroundColor)) return null;
+    if (repeated === null) {
+      repeated = false;
+      for (let group = el.parentElement; group && group !== document.body; group = group.parentElement) {
+        if (!/flex|grid/.test(getComputedStyle(group).display) && !group.matches("ul,ol,[role=list]")) continue;
+        const items = [...group.children].filter(visible);
+        const width = items[0]?.getBoundingClientRect().width;
+        if (items.length >= 2 && width && items.filter(item => Math.abs(item.getBoundingClientRect().width - width) < 3).length >= Math.max(2, items.length * 0.6)) {
+          repeated = true; break;
+        }
+      }
+    }
+    return repeated ? text.normalize("NFKC").toLowerCase().replace(/\s+/gu, " ").trim() : null;
+  }
+  function fullText(el) {
+    return (el.innerText || el.textContent || "").replace(/\s+/g, " ").trim();
+  }
+  function accName(el) {
+    return (
+      fullText(el) ||
+      el.getAttribute("aria-label") ||
+      el.getAttribute("title") ||
+      el.getAttribute("alt") ||
+      el.getAttribute("value") ||
+      ""
+    ).slice(0, 80);
+  }
+  // Box around the rendered glyphs only (a heading block is often much wider than its text).
+  // Built from the text runs, since a block child (<h2><p>…</p></h2>) would stretch a range over the whole row.
+  function rangeRect(node, exact = false, isVisible = null) {
+    const texts = [];
+    if (node.nodeType === 3) texts.push(node);
+    else for (let tw = document.createTreeWalker(node, NodeFilter.SHOW_TEXT), t = tw.nextNode(); t; t = tw.nextNode()) if (t.textContent.trim()) texts.push(t);
+    let l = Infinity, t = Infinity, r = -Infinity, b = -Infinity;
+    const range = document.createRange();
+    for (const tn of texts) {
+      if (isVisible && !isVisible(tn.parentElement)) continue;
+      range.selectNodeContents(tn);
+      for (const q of range.getClientRects()) {
+        if (!q.width || !q.height) continue;
+        l = Math.min(l, q.left); t = Math.min(t, q.top); r = Math.max(r, q.right); b = Math.max(b, q.bottom);
+      }
+    }
+    if (l === Infinity) return null;
+    const round = exact ? (v) => v : Math.round;
+    return { x: round(l + window.scrollX), y: round(t + window.scrollY), width: round(r - l), height: round(b - t) };
+  }
+  function rectOf(el, exact = false) {
+    const r = el.getBoundingClientRect();
+    const round = exact ? (v) => v : Math.round;
+    return {
+      x: round(r.left + window.scrollX),
+      y: round(r.top + window.scrollY),
+      width: round(r.width),
+      height: round(r.height),
+    };
+  }
+  // Full scene extraction is opt-in; legacy comparison heuristics remain below.
+  if (snapshot) {
+    const evidence = (method, kind = "computed") => ({ sourceType: "url", kind, method });
+    const known = (value, method) => ({ status: "known", value, provenance: evidence(method), confidence: { score: 1 } });
+    const unknown = (method) => ({ status: "unknown", provenance: evidence(method, "unknown"), confidence: { score: null } });
+    const length = (value, property) => /^-?(?:\d+\.?\d*|\.\d+)px$/.test(value)
+      ? known(Number.parseFloat(value), `getComputedStyle.${property}`)
+      : unknown(`Unresolved getComputedStyle.${property}: ${value}`);
+    const colors = new Map();
+    let colorContext;
+    function measuredColor(value) {
+      if (colors.has(value)) return colors.get(value);
+      const rgb = value.match(/^rgba?\(([^)]+)\)$/i), srgb = value.match(/^color\(srgb\s+([^)]+)\)$/i);
+      const parts = (rgb || srgb)?.[1].replace(/[,/]/g, " ").trim().split(/\s+/);
+      let result;
+      if (parts && [3, 4].includes(parts.length) && parts.every(p => /^[+-]?(?:\d+\.?\d*|\.\d+)(?:e[+-]?\d+)?%?$/i.test(p))) {
+        const channels = parts.slice(0, 3).map(p => Number.parseFloat(p) * (p.endsWith("%") ? 255 / 100 : srgb ? 255 : 1));
+        const alpha = parts.length === 4 ? Number.parseFloat(parts[3]) / (parts[3].endsWith("%") ? 100 : 1) : 1;
+        if (channels.every(n => Number.isFinite(n) && n >= 0 && n <= 255) && Number.isFinite(alpha) && alpha >= 0 && alpha <= 1) {
+          result = known({ r: channels[0], g: channels[1], b: channels[2], a: alpha }, "getComputedStyle.color; exact sRGB components");
+        }
+      }
+      if (!result && CSS.supports("color", value)) {
+        // Convert modern CSS spaces through the local browser renderer. This is
+        // one color normalization, never screenshot/pixel comparison.
+        colorContext ??= document.createElement("canvas").getContext("2d", { willReadFrequently: true });
+        if (colorContext) {
+          colorContext.clearRect(0, 0, 1, 1);
+          colorContext.fillStyle = value;
+          colorContext.fillRect(0, 0, 1, 1);
+          const [r, g, b, a] = colorContext.getImageData(0, 0, 1, 1).data;
+          result = known({ r, g, b, a: a / 255 }, "getComputedStyle.color; browser-rendered sRGB 8-bit normalization");
+        }
+      }
+      result ??= unknown(`Unresolved getComputedStyle.color: ${value}`);
+      colors.set(value, result);
+      return result;
+    }
+    const clean = (s) => String(s || "").replace(/\s+/g, " ").trim().slice(0, 2048);
+    function snapshotVisible(el) {
+      if (excluded.has(el.tagName) || ignore && el.closest(ignore)) return false;
+      const cs = getComputedStyle(el), r = el.getBoundingClientRect();
+      if (!r.width || !r.height || cs.visibility !== "visible" || clippedByAncestor(el)) return false;
+      for (let p = el; p; p = p.parentElement) {
+        const s = getComputedStyle(p);
+        if (s.display === "none" || Number(s.opacity) === 0 || s.contentVisibility === "hidden") return false;
+      }
+      return true;
+    }
+    function visibleText(el) {
+      const walker = document.createTreeWalker(el, NodeFilter.SHOW_TEXT), parts = [];
+      for (let tn = walker.nextNode(); tn; tn = walker.nextNode()) {
+        if (!tn.textContent.trim() || excluded.has(tn.parentElement.tagName)) continue;
+        if (ignore && tn.parentElement.closest(ignore)) continue;
+        if (snapshotVisible(tn.parentElement)) parts.push(tn.textContent);
+      }
+      return clean(parts.join(" "));
+    }
+    const nodes = [], relationships = [], details = {};
+    const ids = new Map(), siblingCounts = new Map(), labelRefs = new Map();
+    const roleOf = (el) => {
+      const explicit = el.getAttribute("role")?.trim().split(/\s+/)[0];
+      if (explicit && explicit.length <= 256) return explicit;
+      const tag = el.localName;
+      if (/^h[1-6]$/.test(tag)) return "heading";
+      if (tag === "a") return el.hasAttribute("href") ? "link" : "generic";
+      if (tag === "input") {
+        const type = el.type;
+        if (["button", "submit", "reset", "image"].includes(type)) return "button";
+        return ({ checkbox: "checkbox", radio: "radio", range: "slider", number: "spinbutton", search: "searchbox" })[type]
+          || (["text", "email", "tel", "url", "password"].includes(type) ? "textbox" : "generic");
+      }
+      if (tag === "select") return el.multiple || el.size > 1 ? "listbox" : "combobox";
+      if (tag === "section" || tag === "form") return el.hasAttribute("aria-label") || el.hasAttribute("aria-labelledby") || el.hasAttribute("title")
+        ? (tag === "section" ? "region" : "form") : "generic";
+      if ((tag === "header" || tag === "footer") && el.closest("article, aside, main, nav, section")) return "generic";
+      return ({ body: "document", main: "main", nav: "navigation", header: "banner", footer: "contentinfo",
+        section: "region", article: "article", aside: "complementary", p: "paragraph", button: "button",
+        form: "form", textarea: "textbox", img: "img", svg: "img", video: "video", audio: "audio",
+        ul: "list", ol: "list", li: "listitem", table: "table", tr: "row", th: "columnheader", td: "cell",
+        fieldset: "group", progress: "progressbar", meter: "meter", dialog: "dialog" })[tag] || "generic";
+    };
+    // Structural paths identify nodes within a capture without CSS class names or page mutation.
+    const pathOf = (el) => {
+      if (el === document.body) return "body";
+      const parts = [];
+      for (let p = el; p && p !== document.body; p = p.parentElement) {
+        parts.push(Array.prototype.indexOf.call(p.parentElement.children, p));
+      }
+      return `body/${parts.reverse().join("/")}`;
+    };
+    const excluded = new Set(["SCRIPT", "STYLE", "NOSCRIPT", "TEMPLATE", "HEAD", "META", "LINK"]);
+    const candidates = [document.body, ...document.body.querySelectorAll("*")];
+    for (const el of candidates) {
+      if (excluded.has(el.tagName) || el.closest("svg") && el.localName !== "svg") continue;
+      if (ignore && el.closest(ignore)) continue;
+      const cs = getComputedStyle(el);
+      // Keep offscreen document content, but exclude hidden and fully clipped boxes.
+      if (!snapshotVisible(el)) continue;
+      if (nodes.length >= snapshot.maxNodes) throw new Error(`UISnapshot node limit exceeded (${snapshot.maxNodes})`);
+      const id = `n${nodes.length}`, semanticRole = roleOf(el);
+      const category = semanticRole === "generic" ? categoryKey(el, cs) : null;
+      const role = category ? "category-badge" : semanticRole;
+      ids.set(el, id);
+      const typography = { fontFamily: cs.fontFamily.length <= 256 ? known(cs.fontFamily, "getComputedStyle.fontFamily") : unknown("fontFamily exceeds schema limit") };
+      for (const prop of ["fontSize", "lineHeight", "letterSpacing", "wordSpacing"]) typography[prop] = length(cs[prop], prop);
+      typography.fontWeight = /^\d+(\.\d+)?$/.test(cs.fontWeight)
+        ? known(Number(cs.fontWeight), "getComputedStyle.fontWeight") : unknown(`Unresolved fontWeight: ${cs.fontWeight}`);
+      typography.color = structuredClone(measuredColor(cs.color));
+      const layout = { display: known(cs.display, "getComputedStyle.display") };
+      for (const prop of ["paddingTop", "paddingRight", "paddingBottom", "paddingLeft", "marginTop", "marginRight", "marginBottom", "marginLeft", "rowGap", "columnGap"]) layout[prop] = length(cs[prop], prop);
+      const text = snapshot.includeText ? visibleText(el) : "";
+      const bounds = rectOf(el, true);
+      if (Object.values(bounds).some((v) => !Number.isFinite(v) || Math.abs(v) > 1e9) || Math.abs(bounds.x + bounds.width) > 1e9 || Math.abs(bounds.y + bounds.height) > 1e9) {
+        throw new Error("Rendered bounds exceed the Shivax coordinate range");
+      }
+      nodes.push({ id, role, ...(text ? { text } : {}), bounds: known(bounds, "getBoundingClientRect + window.scroll"), typography, layout });
+      let parent = el.parentElement;
+      while (parent && !ids.has(parent)) parent = parent.parentElement;
+      const parentId = ids.get(parent) || null;
+      if (parentId) relationships.push({ from: parentId, to: id, type: "parent-child", provenance: evidence("DOM nearest captured ancestor"), confidence: { score: 1 } });
+      const labelledBy = (el.getAttribute("aria-labelledby") || "").split(/\s+/).filter(Boolean);
+      labelRefs.set(id, labelledBy.map((key) => document.getElementById(key)));
+      const name = clean(labelledBy.map((key) => document.getElementById(key)?.textContent || "").join(" ")
+        || el.getAttribute("aria-label") || [...(el.labels || [])].map((l) => l.innerText).join(" ")
+        || el.getAttribute("alt") || el.getAttribute("title") || (role === "button" ? el.innerText || el.getAttribute("value") : ""));
+      const glyphBounds = snapshot.includeText ? rangeRect(el, true, snapshotVisible) : null;
+      details[id] = {
+        tag: el.localName, path: pathOf(el), parentId,
+        ...(snapshot.includeText && category ? { category: { status: "known", value: category,
+          provenance: evidence("Painted inline text inside a repeated content group; inferred category identity", "estimated"), confidence: { score: 0.8 } } } : {}),
+        siblingIndex: siblingCounts.get(parentId) || 0,
+        domSiblingIndex: el.parentElement ? Array.prototype.indexOf.call(el.parentElement.children, el) : 0,
+        ...(snapshot.includeText && name ? { accessibleName: { status: "known", value: name, provenance: evidence("DOM label attributes/text (partial accessible-name algorithm)", "estimated"), confidence: { score: 0.8 } } } : {}),
+        textBounds: glyphBounds ? known(glyphBounds, "Range.getClientRects union") : unknown("No visible text glyphs"),
+        flexGrid: Object.fromEntries(["flexDirection", "flexWrap", "flexGrow", "flexShrink", "flexBasis", "order", "justifyContent", "alignItems", "alignSelf", "alignContent", "gridTemplateColumns", "gridTemplateRows", "gridAutoFlow", "gridColumn", "gridRow"].map((p) => [p, known(cs[p], `getComputedStyle.${p}`)])),
+        scroll: known({ x: el.scrollLeft, y: el.scrollTop, width: el.scrollWidth, height: el.scrollHeight }, "DOM element scroll metrics"),
+        ...(el.localName === "img" ? { media: { kind: "image", loaded: el.complete && el.naturalWidth > 0, naturalWidth: el.naturalWidth, naturalHeight: el.naturalHeight } } : {}),
+        ...(["video", "audio", "svg", "canvas"].includes(el.localName) ? { media: { kind: el.localName } } : {}),
+      };
+      siblingCounts.set(parentId, (siblingCounts.get(parentId) || 0) + 1);
+    }
+    for (const [from, labels] of labelRefs) {
+      for (const to of new Set(labels.map((el) => ids.get(el)).filter((id) => id && id !== from))) {
+        relationships.push({ from, to, type: "labelled-by", provenance: evidence("DOM.aria-labelledby"), confidence: { score: 1 } });
+      }
+      if (relationships.length > 40000) throw new Error("UISnapshot relationship limit exceeded (40000)");
+    }
+    const previous = new Map();
+    for (const node of nodes) {
+      const d = details[node.id], prev = previous.get(d.parentId);
+      d.previousSiblingId = prev?.id || null;
+      d.nextSiblingId = null;
+      if (prev) {
+        details[prev.id].nextSiblingId = node.id;
+        const a = prev.bounds.value, b = node.bounds.value;
+        d.gapFromPrevious = known({ horizontal: b.x - a.x - a.width, vertical: b.y - a.y - a.height }, "Signed edge distances from getBoundingClientRect");
+      }
+      previous.set(d.parentId, node);
+    }
+    return {
+      snapshot: { version: 1, sourceType: "url", scope: snapshot.scope,
+        viewport: { width: innerWidth, height: innerHeight, devicePixelRatio },
+        coordinates: { unit: "css-px", unitsPerCssPixel: 1, origin: "document" }, nodes, relationships },
+      metadata: { nodes: details, scroll: { x: scrollX, y: scrollY, width: document.documentElement.scrollWidth, height: document.documentElement.scrollHeight },
+        assets: { fonts: document.fonts.status, failedFonts: [...document.fonts].filter((f) => f.status === "error").map((f) => f.family),
+          failedImages: [...document.images].filter((i) => !i.complete || i.currentSrc && i.naturalWidth === 0).length } },
+    };
+  }
+  // Browsers report colours in the format they were written in (oklch, lab, hex...). The same colour written two
+  // ways must compare equal, so every colour is converted to rgb()/rgba() by painting it on a 1px canvas.
+  const colorCtx = document.createElement("canvas").getContext("2d", { willReadFrequently: true });
+  const colorCache = new Map();
+  function toRgb(v) {
+    if (!v || /^rgba?\(/.test(v) || v === "none" || v === "transparent") return v;
+    if (colorCache.has(v)) return colorCache.get(v);
+    let out = v;
+    try {
+      colorCtx.clearRect(0, 0, 1, 1);
+      colorCtx.fillStyle = "#000";
+      colorCtx.fillStyle = v;
+      colorCtx.fillRect(0, 0, 1, 1);
+      const [r, g, b, a] = colorCtx.getImageData(0, 0, 1, 1).data;
+      out = a === 255 ? `rgb(${r}, ${g}, ${b})` : `rgba(${r}, ${g}, ${b}, ${Math.round((a / 255) * 100) / 100})`;
+    } catch {
+      // keep the original string
+    }
+    colorCache.set(v, out);
+    return out;
+  }
+  const COLOR_PROPS = new Set(["color", "backgroundColor", "iconColor", "iconFill", "borderTopColor"]);
+  function styleOf(el) {
+    const cs = getComputedStyle(el);
+    const o = {};
+    for (const p of props) {
+      let v = cs[p];
+      if (p === "fontFamily") v = v.split(",")[0].replace(/["']/g, "").trim();
+      if (COLOR_PROPS.has(p)) v = toRgb(v);
+      o[p] = v;
+    }
+    return o;
+  }
+
+  const all = [...document.body.querySelectorAll("*")].filter(
+    (el) => !skipTags.has(el.tagName) && !isIgnored(el) && visible(el)
+  );
+
+  // ---- Inventory ----
+  const count = (sel) => all.filter((el) => el.matches(sel)).length;
+  const counts = {
+    header: count("header, [role=banner]"),
+    nav: count("nav, [role=navigation]"),
+    main: count("main, [role=main]"),
+    footer: count("footer, [role=contentinfo]"),
+    aside: count("aside, [role=complementary]"),
+    sections: count("section, [role=region]"),
+    forms: count("form"),
+    inputs: count("input:not([type=hidden]), textarea, select"),
+    images: count("img, picture, [role=img]:not(svg)"),
+    icons: count("svg"),
+    lists: count("ul, ol"),
+    tables: count("table"),
+    videos: count("video, iframe"),
+  };
+
+  const buttonSel =
+    "button, [role=button], input[type=button], input[type=submit]";
+  const isButton = (el) => {
+    if (el.matches(buttonSel)) return true;
+    if (!el.matches("a[href]")) return false;
+    const cs = getComputedStyle(el);
+    const painted = !["transparent", "rgba(0, 0, 0, 0)"].includes(cs.backgroundColor) ||
+      (parseFloat(cs.borderTopWidth) > 0 && cs.borderTopStyle !== "none");
+    return painted && (parseFloat(cs.paddingLeft) > 0 || parseFloat(cs.paddingTop) > 0);
+  };
+  const buttons = all
+    .filter(isButton)
+    .map((el) => ({ label: accName(el), rect: rectOf(el), iconOnly: !fullText(el), el }));
+  const navLinks = all
+    .filter((el) => el.matches("nav a, [role=navigation] a, header a"))
+    .map((el) => ({ label: accName(el), rect: rectOf(el), el }));
+  const headings = all
+    .filter((el) => /^H[1-6]$/.test(el.tagName))
+    .map((el) => ({ level: Number(el.tagName[1]), label: fullText(el).slice(0, 80), rect: rectOf(el), el }));
+
+  counts.buttons = buttons.length;
+  counts.navLinks = navLinks.length;
+  counts.headings = headings.length;
+
+  // Page text (for the expected-checklist lookup)
+  const labelBag = new Set();
+  for (const el of all) {
+    if (el.matches("a, button, h1, h2, h3, h4, h5, h6, label, legend, summary, th, [role=button], [role=tab]")) {
+      labelBag.add(norm(fullText(el)));
+    }
+    const aria = el.getAttribute("aria-label");
+    if (aria) labelBag.add(norm(aria));
+    const alt = el.getAttribute("alt");
+    if (alt) labelBag.add(norm(alt));
+    const ph = el.getAttribute("placeholder");
+    if (ph) labelBag.add(norm(ph));
+  }
+  const bodyText = norm(document.body.innerText);
+
+  // ---- Styles of components, grouped by kind (text is dynamic, so it is never used to match them) ----
+  const styled = [];
+  for (const b of buttons) styled.push({ kind: "button", label: b.label, rect: b.rect, styles: styleOf(b.el) });
+  for (const h of headings) styled.push({ kind: `h${h.level}`, label: h.label, rect: h.rect, styles: styleOf(h.el) });
+  for (const n of navLinks) styled.push({ kind: "nav link", label: n.label, rect: n.rect, styles: styleOf(n.el) });
+
+  // ---- Page sections: the top-level blocks of the page (header, hero, services, footer...) ----
+  const isVis = (el) => visible(el) && !isIgnored(el) && !skipTags.has(el.tagName);
+  const kidsOf = (el) => [...el.children].filter(isVis);
+  const unwrap = (el) => {
+    let cur = el;
+    for (let i = 0; i < 6; i++) {
+      const ks = kidsOf(cur);
+      if (ks.length !== 1) break;
+      cur = ks[0];
+    }
+    return cur;
+  };
+  const blocks = [];
+  for (const k of kidsOf(unwrap(document.body))) {
+    if (k.matches("main, [role=main]")) blocks.push(...kidsOf(unwrap(k)));
+    else blocks.push(k);
+  }
+  // Layout containers inside a section (the section itself, rows, columns, cards) with their spacing,
+  // keyed by child-index path so the same container can be paired between reference and target.
+  const SPACE_PROPS = ["paddingTop", "paddingRight", "paddingBottom", "paddingLeft", "marginTop", "marginBottom", "rowGap", "columnGap"];
+  function spacingNodes(root) {
+    const out = [];
+    const walk = (el, path, depth, uniq, chain) => {
+      if (out.length >= 600) return;
+      if (depth > 0) {
+        // Visually hidden (sr-only) and hairline elements are not visible UI.
+        const br = el.getBoundingClientRect();
+        if (br.width <= 2 || br.height <= 2) return;
+      }
+      const cs = getComputedStyle(el);
+      const visibleKids = kidsOf(el);
+      // Media and empty image/decorative wrappers carry CMS content, not text UI.
+      if (depth > 0 && !fullText(el) && (el.matches("img, picture, svg, video") || el.querySelector("img, picture, svg, video") || cs.position === "absolute")) return;
+      // Collapse neutral wrappers so moving CSS onto an equivalent wrapper does not
+      // create a second visual component at the same rectangle.
+      const neutralWrapper = depth > 0 && visibleKids.length === 1 && !ownText(el) &&
+        !/^H[1-6]$/.test(el.tagName) &&
+        ["paddingTop", "paddingRight", "paddingBottom", "paddingLeft", "marginTop", "marginBottom"].every(p => parseFloat(cs[p]) === 0) &&
+        ["transparent", "rgba(0, 0, 0, 0)"].includes(cs.backgroundColor) && parseFloat(cs.borderTopWidth) === 0 &&
+        Math.abs(el.getBoundingClientRect().width - visibleKids[0].getBoundingClientRect().width) <= 2;
+      // How many items the parent and grandparent hold: a structural fingerprint used instead of text for pairing.
+      const shape = [el.parentElement, el.parentElement && el.parentElement.parentElement].map((p) => (p ? kidsOf(p).length : 0)).join(",");
+      let repeatCount = null, repeatItem = null;
+      for (let group = el.parentElement; group && root.contains(group); group = group.parentElement) {
+        const gs = getComputedStyle(group), items = kidsOf(group);
+        if ((!/flex|grid/.test(gs.display) && !group.matches("ul,ol,[role=list]")) || items.length < 2) continue;
+        const sample = items[0], sw = sample.getBoundingClientRect().width;
+        // Cards in a grid of 3+ may differ by an optional badge or price tag, so their child counts can vary slightly.
+        const sameShape = (k) => kidsOf(k).length === kidsOf(sample).length ||
+          (items.length >= 3 && k.tagName === sample.tagName && Math.abs(kidsOf(k).length - kidsOf(sample).length) <= 2);
+        if (sw && items.filter(k => Math.abs(k.getBoundingClientRect().width - sw) < 3 && sameShape(k)).length >= Math.max(2, items.length * 0.6)) {
+          repeatCount = items.length; repeatItem = items.find(item => item === el || item.contains(el)); break;
+        }
+      }
+      const interactive = el.matches("a[href], button, [role=button], input, select, textarea");
+      const list = el.closest("ul, ol");
+      const listSize = list ? kidsOf(list).length : null;
+      const nm = () => {
+        const t = ownText(el).slice(0, 28);
+        return el.tagName.toLowerCase() + (t ? ` “${t}”` : "");
+      };
+      const hasText = ownText(el).length > 0 || (/^H[1-6]$/.test(el.tagName) && fullText(el).length > 0);
+      const isBtn = isButton(el);
+      const visualBox =
+        (cs.backgroundColor !== "rgba(0, 0, 0, 0)" && cs.backgroundColor !== "transparent") ||
+        (parseFloat(cs.borderTopWidth) > 0 && cs.borderTopStyle !== "none");
+      const parentStyle = el.parentElement ? getComputedStyle(el.parentElement) : null;
+      // A plain block wrapper can constrain the content width without padding or flex/grid.
+      const blockContainer = !hasText && kidsOf(el).length > 0 && cs.display === "block";
+      const layoutBox = blockContainer || /flex|grid/.test(cs.display) || SPACE_PROPS.some((p) => /^[1-9]/.test(cs[p]) && p.startsWith("padding"));
+      const contentSized = /^inline/.test(cs.display) ||
+        (parentStyle && /flex/.test(parentStyle.display) && Number(cs.flexGrow) === 0 && cs.flexBasis === "auto");
+      if (/^(IMG|SVG|PICTURE|VIDEO)$/i.test(el.tagName)) {
+        // Photos, videos and image markup are dynamic content; only SVG icons are UI.
+        if (el.tagName.toLowerCase() !== "svg") return;
+        const r = el.getBoundingClientRect();
+        const styles = { iconWidth: `${Math.round(r.width)}px`, iconHeight: `${Math.round(r.height)}px` };
+        if (/^svg$/i.test(el.tagName)) {
+          styles.iconColor = toRgb(cs.color);
+          styles.iconFill = toRgb(cs.fill);
+        }
+        out.push({ path, label: label(el), name: nm(), shape, listSize, repeatCount, interactive, tagPath: chain, tag: el.tagName.toLowerCase(), rect: rectOf(el), styles, widthPct: null, kind: "media", uniq });
+        return;
+      }
+      if (!neutralWrapper && (depth === 0 || layoutBox || hasText || isBtn || visualBox || el.matches("input, textarea, select"))) {
+        const styles = {};
+        const accentRects = [];
+        let textRect = null;
+        for (const p of SPACE_PROPS) styles[p] = cs[p];
+        for (const p of ["marginTop", "marginBottom"]) {
+          if (el.computedStyleMap?.().get(p.replace(/[A-Z]/g, m => "-" + m.toLowerCase()))?.toString() === "auto") styles[p] = "auto";
+        }
+        const itemCount = visibleKids.length + (ownText(el) ? 1 : 0);
+        // Gaps only have an effect between rendered flex/grid items.
+        if (!/flex|grid/.test(cs.display) || itemCount < 2) {
+          styles.rowGap = "0px"; styles.columnGap = "0px";
+        } else if (/flex/.test(cs.display) && cs.flexWrap === "nowrap") {
+          styles[cs.flexDirection.startsWith("column") ? "columnGap" : "rowGap"] = "0px";
+        }
+        if (/^H[1-6]$/.test(el.tagName)) { styles.rowGap = "0px"; styles.columnGap = "0px"; }
+        if (hasText) {
+          // Padding/margins may move to a sole-child rich-text wrapper without
+          // changing the rendered component. Compare the combined inset.
+          for (let parent = el.parentElement; parent && parent !== root && kidsOf(parent).length === 1; parent = parent.parentElement) {
+            const ps = getComputedStyle(parent);
+            for (const p of ["paddingTop", "paddingRight", "paddingBottom", "paddingLeft", "marginTop", "marginBottom"]) {
+              if (styles[p] !== "auto") styles[p] = `${(parseFloat(styles[p]) || 0) + (parseFloat(ps[p]) || 0)}px`;
+            }
+          }
+          for (const p of ["fontFamily", "fontSize", "fontWeight", "lineHeight", "letterSpacing", "wordSpacing", "color"]) {
+            styles[p] = p === "fontFamily" ? cs[p].split(",")[0].replace(/["']/g, "").trim() : p === "color" ? toRgb(cs[p]) : cs[p];
+          }
+          if (/^H[1-6]$/.test(el.tagName)) {
+            // Headings are not walked into, so a highlighted word (<span style="color:pink">) is recorded here.
+            const accents = new Set();
+            const tw = document.createTreeWalker(el, NodeFilter.SHOW_TEXT);
+            for (let tn = tw.nextNode(); tn; tn = tw.nextNode()) {
+              if (!tn.textContent.trim() || !tn.parentElement) continue;
+              const c = toRgb(getComputedStyle(tn.parentElement).color);
+              if (c !== styles.color) { accents.add(c); const ar = rangeRect(tn); if (ar) accentRects.push(ar); }
+            }
+            styles.accentColor = accents.size ? [...accents].sort().join(" + ") : "none";
+          }
+          textRect = rangeRect(el);
+        }
+        if ((layoutBox && !hasText) || visualBox) {
+          styles.backgroundColor = toRgb(cs.backgroundColor);
+          styles.borderRadius = cs.borderRadius;
+        }
+        const sr = depth === 0 ? { width: document.documentElement.clientWidth } : root.getBoundingClientRect();
+        // Width as a share of the section, only for block-level layout containers (text boxes shrink to content).
+        const widthPct = layoutBox && !hasText && !contentSized && sr.width ? Math.round((el.getBoundingClientRect().width / sr.width) * 1000) / 10 : null;
+        const gapRects = { rowGap: [], columnGap: [] };
+        const renderedGaps = { rowGap: null, columnGap: null };
+        const distributedGap = /space-between|space-around|space-evenly/.test(cs.justifyContent);
+        const flow = visibleKids.filter(k => !["absolute", "fixed"].includes(getComputedStyle(k).position)).map(rectOf);
+        for (let i = 0; i < flow.length; i++) for (let j = i + 1; j < flow.length; j++) {
+          const a = flow[i], b = flow[j];
+          const iy = Math.min(a.y + a.height, b.y + b.height) - Math.max(a.y, b.y);
+          const ix = Math.min(a.x + a.width, b.x + b.width) - Math.max(a.x, b.x);
+          const dx = b.x - a.x - a.width, dy = b.y - a.y - a.height;
+          if (iy > 0 && dx >= 0) renderedGaps.columnGap = Math.min(renderedGaps.columnGap ?? Infinity, dx);
+          if (ix > 0 && dy >= 0) renderedGaps.rowGap = Math.min(renderedGaps.rowGap ?? Infinity, dy);
+          if (iy > 0 && dx > 0 && dx <= (parseFloat(cs.columnGap) || 0) + 2 && gapRects.columnGap.length < 3)
+            gapRects.columnGap.push({ x: a.x + a.width, y: Math.max(a.y, b.y), width: dx, height: iy });
+          if (ix > 0 && dy > 0 && dy <= (parseFloat(cs.rowGap) || 0) + 2 && gapRects.rowGap.length < 3)
+            gapRects.rowGap.push({ x: Math.max(a.x, b.x), y: a.y + a.height, width: ix, height: dy });
+        }
+        const category = categoryKey(el, cs, Boolean(repeatCount));
+        const recordHeading = category ? repeatItem?.querySelector("h1,h2,h3,h4,h5,h6") : null;
+        out.push({ path, label: label(el), name: nm(), textLen: (ownText(el) || fullText(el)).length,
+          categoryKey: category,
+          recordKey: recordHeading ? fullText(recordHeading).normalize("NFKC").toLowerCase().replace(/\s+/gu, " ").trim() : null,
+          shape, listSize, repeatCount, interactive, tagPath: chain, tag: el.tagName.toLowerCase(), rect: rectOf(el), textRect, accentRects, styles, widthPct, gapRects, renderedGaps, distributedGap, kind: isBtn ? "button" : el.matches("input, textarea, select") ? "input" : hasText ? "text" : "box", uniq, visualBox });
+      }
+      if (depth >= 12) return;
+      if (/^H[1-6]$/.test(el.tagName)) return;
+      const kids = kidsOf(el);
+      const seen = {};
+      kids.forEach((k) => (seen[k.tagName] = (seen[k.tagName] || 0) + 1));
+      kids.forEach((k, i) => walk(k, `${path}/${i}`, depth + 1, seen[k.tagName] === 1, `${chain}>${k.tagName.toLowerCase()}`));
+    };
+    walk(root, "", 0, true, root.tagName.toLowerCase());
+    return out;
+  }
+  const cnt = (el, sel) => [...el.querySelectorAll(sel)].filter(isVis).length;
+  const roleOf = (el) =>
+    el.matches("header, [role=banner]") ? "header"
+    : el.matches("footer, [role=contentinfo]") ? "footer"
+    : el.matches("nav, [role=navigation]") ? "nav"
+    : "block";
+  const sections = blocks
+    .filter((el) => {
+      const r = el.getBoundingClientRect();
+      return getComputedStyle(el).position !== "fixed" && r.height >= 40 && r.width >= document.documentElement.clientWidth * 0.4;
+    })
+    .slice(0, 40)
+    .map((el, index) => {
+      const h = el.querySelector("h1,h2,h3,h4,h5,h6");
+      const heading = h && isVis(h) ? fullText(h).slice(0, 80) : "";
+      return {
+        index,
+        role: roleOf(el),
+        label: label(el),
+        heading,
+        counts: {
+          buttons: [el, ...el.querySelectorAll("*")].filter((n) => isVis(n) && isButton(n)).length,
+          images: cnt(el, "img, picture, [role=img]:not(svg)"),
+          links: cnt(el, "a[href]"),
+          headings: cnt(el, "h1,h2,h3,h4,h5,h6"),
+          inputs: cnt(el, "input:not([type=hidden]), textarea, select"),
+        },
+        rect: rectOf(el),
+        spacing: spacingNodes(el),
+      };
+    });
+
+  // ---- Layout problems ----
+  const vw = document.documentElement.clientWidth;
+  const layout = [];
+  const sw = document.documentElement.scrollWidth;
+  if (sw > vw + 1) {
+    const culpritEls = all
+      .filter((el) => el.getBoundingClientRect().right > vw + 1 && getComputedStyle(el).position !== "fixed")
+      .slice(0, 5);
+    const culprits = culpritEls.map(label);
+    layout.push({
+      severity: "high",
+      type: "Horizontal overflow",
+      detail: `Page is ${sw}px wide in a ${vw}px viewport (horizontal scrollbar).`,
+      elements: culprits,
+      rects: culpritEls.map(rectOf),
+    });
+  }
+
+  for (const el of all) {
+    if (layout.length > 120) break;
+    const cs = getComputedStyle(el);
+    const hasText = ownText(el).length > 0;
+
+    if (hasText && (cs.overflowX === "hidden" || cs.overflowX === "clip") && cs.textOverflow !== "ellipsis") {
+      if (el.scrollWidth > el.clientWidth + 2) {
+        layout.push({
+          severity: "medium",
+          type: "Clipped text",
+          detail: `Text is cut off horizontally (${el.scrollWidth}px content in ${el.clientWidth}px box).`,
+          elements: [label(el)],
+          rects: [rectOf(el)],
+          text: ownText(el).slice(0, 60),
+        });
+      }
+    }
+    if (hasText && (cs.overflowY === "hidden" || cs.overflowY === "clip") && el.scrollHeight > el.clientHeight + 4 && cs.webkitLineClamp === "none") {
+      layout.push({
+        severity: "medium",
+        type: "Clipped text",
+        detail: `Text is cut off vertically (${el.scrollHeight}px content in ${el.clientHeight}px box).`,
+        elements: [label(el)],
+        rects: [rectOf(el)],
+        text: ownText(el).slice(0, 60),
+      });
+    }
+    if (el.tagName === "IMG" && el.complete && el.naturalWidth === 0 && el.currentSrc) {
+      layout.push({
+        severity: "medium",
+        type: "Broken image",
+        detail: "Image failed to load.",
+        elements: [label(el)],
+        rects: [rectOf(el)],
+      });
+    }
+    if (hasText && cs.position !== "fixed" && !containedHorizontally(el)) {
+      const r = el.getBoundingClientRect();
+      if (r.left < -2 || r.right > vw + 2) {
+        if (sw <= vw + 1 || r.right > vw + 2) {
+          layout.push({
+            severity: "medium",
+            type: "Outside viewport",
+            detail: `Text element extends beyond the ${vw}px viewport (left ${Math.round(r.left)}, right ${Math.round(r.right)}).`,
+            elements: [label(el)],
+            text: ownText(el).slice(0, 60),
+          });
+        }
+      }
+    }
+  }
+
+  // Overlapping text-bearing elements / buttons (not ancestors of each other)
+  const boxes = all
+    .filter((el) => ownText(el).length > 0 || el.matches(buttonSel))
+    .filter((el) => getComputedStyle(el).position !== "fixed")
+    .slice(0, 700)
+    .map((el) => ({ el, r: el.getBoundingClientRect() }));
+  let overlaps = 0;
+  for (let i = 0; i < boxes.length && overlaps < 25; i++) {
+    for (let j = i + 1; j < boxes.length && overlaps < 25; j++) {
+      const a = boxes[i];
+      const b = boxes[j];
+      if (a.el.contains(b.el) || b.el.contains(a.el)) continue;
+      const ix = Math.min(a.r.right, b.r.right) - Math.max(a.r.left, b.r.left);
+      const iy = Math.min(a.r.bottom, b.r.bottom) - Math.max(a.r.top, b.r.top);
+      if (ix <= 2 || iy <= 2) continue;
+      const smaller = Math.min(a.r.width * a.r.height, b.r.width * b.r.height);
+      if ((ix * iy) / smaller > 0.3) {
+        overlaps++;
+        layout.push({
+          severity: "medium",
+          type: "Overlapping elements",
+          detail: `${label(a.el)} overlaps ${label(b.el)} (${Math.round(ix)}×${Math.round(iy)}px).`,
+          elements: [label(a.el), label(b.el)],
+          rects: [rectOf(a.el), rectOf(b.el)],
+          text: `${ownText(a.el).slice(0, 30)} / ${ownText(b.el).slice(0, 30)}`,
+        });
+      }
+    }
+  }
+
+  // ---- Visible text for the spelling check (headings, buttons, labels, nav, copy) ----
+  const texts = [];
+  const seen = new Set();
+  for (const el of all) {
+    if (el.closest("svg, code, pre")) continue;
+    const t = ownText(el);
+    if (t.length < 2 || seen.has(t)) continue;
+    seen.add(t);
+    texts.push({ tag: el.tagName.toLowerCase(), text: t.slice(0, 3000), rect: rectOf(el) });
+    if (texts.length >= 2500) break;
+  }
+
+  return {
+    counts,
+    buttons: buttons.map(({ label, key, rect, iconOnly }) => ({ label, key, rect, iconOnly })),
+    navLinks: navLinks.map(({ label, key, rect }) => ({ label, key, rect })),
+    headings: headings.map(({ level, label, key, rect }) => ({ level, label, key, rect })),
+    styled,
+    sections,
+    labelBag: [...labelBag],
+    bodyText,
+    layout,
+    texts,
+  };
+}
+
+const RUNS_DIR = path.join(OUTPUT_DIR, "runs");
+const KEEP_RUNS = 20;
+
+// Each run writes its screenshots to its own folder so concurrent or later runs never overwrite them.
+function newRunDir() {
+  const id = `${new Date().toISOString().replace(/[-:.TZ]/g, "").slice(0, 14)}-${Math.random().toString(36).slice(2, 8)}`;
+  const dir = path.join(RUNS_DIR, id);
+  fs.mkdirSync(dir, { recursive: true });
+  try {
+    const old = fs.readdirSync(RUNS_DIR).sort().slice(0, -KEEP_RUNS);
+    for (const d of old) fs.rmSync(path.join(RUNS_DIR, d), { recursive: true, force: true });
+  } catch {
+    // cleanup is best effort
+  }
+  return { id, dir };
+}
+
+/**
+ * Brings a page to its fully loaded, final visual state before it is measured and captured:
+ * lazy images loaded, scroll-reveal content shown, fonts ready, animations finished.
+ */
+export async function settlePage(page, disableAnimations = true, readinessTimeout = 15000, revealFallback = true) {
+  if (disableAnimations) {
+    // Finish animations instantly instead of removing them: `animation: none` would put keyframe-revealed
+    // elements back to their hidden starting state.
+    await page.addStyleTag({
+      content:
+        "*,*::before,*::after{animation-duration:0s!important;animation-delay:0s!important;animation-iteration-count:1!important;transition-duration:0s!important;transition-delay:0s!important;scroll-behavior:auto!important}",
+    });
+  }
+  await page.evaluate(() => {
+    for (const img of document.querySelectorAll("img[loading=lazy]")) img.loading = "eager";
+  });
+  // Scroll down one screen at a time, slowly enough for IntersectionObserver-based lazy loading and
+  // reveal animations to fire. The page may grow while scrolling, so the height is re-read each step.
+  await page.evaluate(async () => {
+    const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+    const step = Math.max(300, Math.floor(window.innerHeight * 0.75));
+    for (let y = 0, i = 0; y < document.documentElement.scrollHeight && i < 200; y += step, i++) {
+      window.scrollTo(0, y);
+      await sleep(180);
+    }
+    window.scrollTo(0, document.documentElement.scrollHeight);
+    await sleep(400);
+    window.scrollTo(0, 0);
+  });
+  await page.waitForLoadState("networkidle", { timeout: 15000 }).catch(() => {});
+  // Wait for every image (including CSS-free <img> swapped in by lazy loaders) to finish loading.
+  await page
+    .evaluate(async () => {
+      const imgs = [...document.images].filter((i) => !i.complete || (i.currentSrc && i.naturalWidth === 0));
+      await Promise.race([
+        Promise.all(imgs.map((i) => (i.decode ? i.decode().catch(() => {}) : Promise.resolve()))),
+        new Promise((r) => setTimeout(r, 10000)),
+      ]);
+    })
+    .catch(() => {});
+  await page.waitForFunction(() => document.fonts.status === "loaded", null, { timeout: readinessTimeout });
+  // Reveal-on-scroll libraries (AOS, Framer Motion, WOW, GSAP...) leave content at opacity 0 when they
+  // did not fire. Force those elements to their final state; real hidden UI (menus, modals) uses
+  // display:none / visibility and is left alone.
+  if (revealFallback) await page.evaluate(() => {
+    const revealHint = /\b(aos|reveal|fade|animate|wow|motion|in-view|inview|scroll)/i;
+    for (const el of document.body.querySelectorAll("*")) {
+      const cs = getComputedStyle(el);
+      if (cs.display === "none" || Number(cs.opacity) > 0.01) continue;
+      const r = el.getBoundingClientRect();
+      if (r.width < 4 || r.height < 4) continue;
+      const inlineHidden = /opacity:\s*0(\.0+)?(;|$)/.test(el.getAttribute("style") || "");
+      const hinted = el.hasAttribute("data-aos") || revealHint.test(typeof el.className === "string" ? el.className : "");
+      if (!inlineHidden && !hinted) continue;
+      el.style.setProperty("opacity", "1", "important");
+      el.style.setProperty("transform", "none", "important");
+      if (cs.visibility === "hidden") el.style.setProperty("visibility", "visible", "important");
+    }
+  });
+  await page.waitForTimeout(300);
+}
+
+export async function createInspectionPage(browser, viewport, deviceScaleFactor = 1) {
+  const context = await browser.newContext({ viewport: { width: viewport.width, height: viewport.height }, deviceScaleFactor });
+  try { return await context.newPage(); }
+  catch (error) { await context.close(); throw error; }
+}
+
+export async function capturePageScreenshot(page, filePath) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  await page.screenshot({ path: filePath, fullPage: true });
+  return page.evaluate(() => ({ width: document.documentElement.scrollWidth, height: document.documentElement.scrollHeight }));
+}
+
+async function inspect(browser, url, viewport, ignore, shotName, disableAnimations = true, run = null) {
+  const page = await createInspectionPage(browser, viewport);
+  try {
+    await page.goto(url, { waitUntil: "networkidle", timeout: 60000 });
+    await settlePage(page, disableAnimations);
+    const data = await page.evaluate(inspectPage, { props: STYLE_PROPS, ignore });
+    if (shotName) {
+      try {
+        const dir = run ? run.dir : OUTPUT_DIR;
+        const size = await capturePageScreenshot(page, path.join(dir, shotName));
+        data.shot = { image: run ? `visual-reports/runs/${run.id}/${shotName}` : `visual-reports/${shotName}`, ...size };
+      } catch {
+        data.shot = null;
+      }
+    }
+    return data;
+  } finally {
+    await page.close();
+  }
+}
+
+const norm = (s) => String(s || "").toLowerCase().replace(/[^a-z0-9]+/g, " ").trim();
+
+function pxNum(v) {
+  const m = /^(-?[\d.]+)px$/.exec(v);
+  return m ? Number(m[1]) : null;
+}
+
+function rgbNum(v) {
+  const m = /^rgba?\(\s*([\d.]+),\s*([\d.]+),\s*([\d.]+)(?:,\s*([\d.]+))?\s*\)$/.exec(String(v || ""));
+  return m ? [+m[1], +m[2], +m[3], m[4] === undefined ? 1 : +m[4]] : null;
+}
+
+// Colours a few units apart (rounding between colour spaces, e.g. Tailwind v3 hex vs v4 oklch) look identical.
+const COLOR_TOL = 8;
+
+function sameStyle(a, b) {
+  if (a === b) return true;
+  const ca = rgbNum(a);
+  const cb = rgbNum(b);
+  if (ca && cb) return Math.max(...[0, 1, 2].map((i) => Math.abs(ca[i] - cb[i]))) <= COLOR_TOL && Math.abs(ca[3] - cb[3]) <= 0.05;
+  const x = pxNum(a);
+  const y = pxNum(b);
+  return x !== null && y !== null && Math.abs(x - y) <= 1;
+}
+
+// Raw tag and asset counts describe the implementation and dynamic data, not visual parity.
+// Compare matched visual sections and their UI components instead.
+export function checkCompleteness(ref, tgt) {
+  return dedupe(checkStructure(ref, tgt));
+}
+
+/**
+ * Compares page structure: top-level sections and the kinds of elements inside them.
+ * Anything present in the reference but absent from the target is reported as high severity.
+ */
+function checkStructure(ref, tgt) {
+  const findings = [];
+  const rs = ref.sections || [];
+  const ts = tgt.sections || [];
+  if (!rs.length || !ts.length) return findings;
+  const title = (sec) => sec.heading || `section ${sec.index + 1}`;
+
+  // Match sections in document order, never by how many CMS items they contain.
+  // With the same number of sections, changing cards, heading tags or button tags
+  // cannot make an existing section appear missing or moved.
+  const usedT = new Set();
+  const matchOf = new Map();
+  if (rs.length === ts.length) {
+    rs.forEach((_, i) => { matchOf.set(i, i); usedT.add(i); });
+  } else {
+    let next = 0;
+    rs.forEach((r, i) => {
+      const j = ts.findIndex((t, j) => j >= next && (t.role === r.role || t.role === "block" || r.role === "block"));
+      if (j >= 0) { matchOf.set(i, j); usedT.add(j); next = j + 1; }
+    });
+  }
+
+  const missing = rs.filter((_, i) => !matchOf.has(i));
+  if (missing.length) {
+    findings.push({
+      severity: "high",
+      type: `Sections missing in target (${missing.length})`,
+      detail: "These sections are in the reference but no section with the same structure was found at that position in the target.",
+      elements: missing.map(title),
+      refRects: missing.map((m) => m.rect),
+      tgtRects: rs.flatMap((m, i) => {
+        if (matchOf.has(i)) return [];
+        let prevJ = -1;
+        for (let k = i - 1; k >= 0; k--) if (matchOf.has(k)) { prevJ = matchOf.get(k); break; }
+        const at = prevJ >= 0 ? ts[prevJ].rect : null;
+        return [{ x: at ? at.x : 0, y: at ? at.y + at.height : 0, width: at ? at.width : m.rect.width, height: Math.min(m.rect.height, 120) }];
+      }),
+    });
+  }
+  const extra = ts.filter((_, j) => !usedT.has(j));
+  if (extra.length) {
+    findings.push({
+      severity: "medium",
+      type: `Extra sections in target (${extra.length})`,
+      detail: "These sections are in the target but not in the reference (page structure differs).",
+      elements: extra.map(title),
+      tgtRects: extra.map((e) => e.rect),
+    });
+  }
+
+  const pairs = [...matchOf.entries()].sort((a, b) => a[0] - b[0]);
+  findings.push(...checkSpacing(rs, ts, pairs));
+  findings.push(...checkMissingElements(rs, ts, pairs));
+
+  return findings;
+}
+
+/**
+ * Pairs visual components by kind and relative position. Tags, classes and wrapper depth
+ * are only weak tie breakers. Data-driven category badges additionally use their
+ * category label and, for duplicate labels, the owning repeated item's heading.
+ */
+function pairNodes(refNodes = [], tgtNodes = [], strict = false) {
+  const rRoot = refNodes.find(n => n.path === "");
+  const tRoot = tgtNodes.find(n => n.path === "");
+  const pairs = [], tgtOf = new Map(), usedR = new Set(), usedT = new Set();
+  const add = (r, t) => { pairs.push([r, t]); tgtOf.set(r, t); usedR.add(r); usedT.add(t); };
+  if (rRoot && tRoot) add(rRoot, tRoot);
+  // A category's color follows its data identity, not a CMS card's current slot.
+  // Resolve duplicate labels only when the owning article title disambiguates them.
+  for (const byRecord of [true, false]) {
+    const groups = nodes => {
+      const index = new Map();
+      for (const node of nodes) if (node.categoryKey && (!byRecord || node.recordKey)) {
+        const key = JSON.stringify([node.categoryKey, byRecord ? node.recordKey : null]);
+        const list = index.get(key) || []; list.push(node); index.set(key, list);
+      }
+      return index;
+    };
+    const refs = groups(refNodes), targets = groups(tgtNodes);
+    for (const [key, nodes] of refs) {
+      const other = targets.get(key);
+      if (nodes.length === 1 && other?.length === 1 && !usedR.has(nodes[0]) && !usedT.has(other[0])) add(nodes[0], other[0]);
+    }
+  }
+  const rel = (n, root) => ({
+    x: root?.rect.width ? (n.rect.x - root.rect.x) / root.rect.width : 0,
+    y: root?.rect.height ? (n.rect.y - root.rect.y) / root.rect.height : 0,
+    w: root?.rect.width ? n.rect.width / root.rect.width : 0,
+  });
+  const distance = (r, t) => [...new Set([...Object.keys(r.styles), ...Object.keys(t.styles)])].reduce((sum, p) => {
+    const a = r.styles[p], b = t.styles[p];
+    if (sameStyle(a, b) || (["rowGap", "columnGap", "letterSpacing", "wordSpacing"].includes(p) && [a, b].every(v => v === "normal" || v === "0px"))) return sum;
+    return sum + (a === undefined || b === undefined ? 0.1 : 1);
+  }, 0);
+  const inside = (n, root) => root.path === "" || n.path.startsWith(root.path + "/");
+  const paletteCache = new Map();
+  const palette = (node, nodes) => {
+    if (!paletteCache.has(node)) paletteCache.set(node, new Set(nodes.filter(n =>
+      ["text", "button"].includes(n.kind) && inside(n, node)).map(n =>
+      ["fontFamily", "fontSize", "fontWeight", "lineHeight", "color"].map(p => n.styles[p]).join("|"))));
+    return paletteCache.get(node);
+  };
+  // Establish visual containers first; text is then matched inside its corresponding
+  // container, so a heading cannot be paired with a card caption elsewhere.
+  for (const boxes of [true, false]) {
+    const candidates = [];
+    for (const r of refNodes) {
+      if (usedR.has(r) || (r.kind === "box") !== boxes) continue;
+      const host = boxes ? rRoot : [...tgtOf.keys()]
+        .filter(n => n.kind === "box" && inside(r, n))
+        .sort((a, b) => b.path.length - a.path.length)[0] || rRoot;
+      const targetHost = tgtOf.get(host) || tRoot;
+      const a = rel(r, host);
+      for (const t of tgtNodes) {
+        if (usedT.has(t) || (t.kind === "box") !== boxes) continue;
+        const textLike = n => ["text", "button"].includes(n.kind);
+        if (r.kind !== t.kind && !(textLike(r) && textLike(t))) continue;
+        if (!boxes && r.interactive !== undefined && t.interactive !== undefined && r.interactive !== t.interactive) continue;
+        if (!boxes && targetHost && !inside(t, targetHost)) continue;
+        const b = rel(t, targetHost);
+        let position = Math.abs(a.x - b.x) + 0.4 * Math.abs(a.y - b.y);
+        if (boxes) position += Math.abs(a.w - b.w);
+        if (position > 0.75) continue;
+        const styleDistance = distance(r, t);
+        // A large mismatch without a reliable counterpart is ambiguous content.
+        if (strict && styleDistance > 4 && r.path !== t.path) continue;
+        let paletteCost = 0;
+        if (boxes) {
+          const rp = palette(r, refNodes), tp = palette(t, tgtNodes);
+          // A decoration with no text (a badge dot, for example) cannot be a card.
+          if (Boolean(rp.size) !== Boolean(tp.size)) continue;
+          const union = new Set([...rp, ...tp]);
+          if (union.size) paletteCost = 0.4 * [...union].filter(v => !rp.has(v) || !tp.has(v)).length / union.size;
+        }
+        candidates.push({r, t, cost: position + 0.15 * styleDistance + paletteCost});
+      }
+    }
+    candidates.sort((a, b) => a.cost - b.cost);
+    for (const {r, t} of candidates) if (!usedR.has(r) && !usedT.has(t)) add(r, t);
+  }
+  return { pairs, tgtOf, unpaired: refNodes.filter(n => n.path !== "" && !usedR.has(n)) };
+}
+
+const SPACE_LABELS = {
+  paddingTop: "padding-top", paddingRight: "padding-right", paddingBottom: "padding-bottom", paddingLeft: "padding-left",
+  marginTop: "margin-top", marginBottom: "margin-bottom", rowGap: "row gap", columnGap: "column gap",
+};
+
+/**
+ * Compares spacing (section padding / margins, gaps between rows and columns, padding inside cards) of matched
+ * sections. Only the containers whose spacing differs are reported, so the highlight is small and exact.
+ * Content differences (more or fewer cards, longer text) never produce a finding here.
+ */
+function highlightRects(node, diffs) {
+  if (diffs.every(d => ["row gap", "column gap"].includes(d.prop))) {
+    const rects = diffs.flatMap(d => node.gapRects?.[d.prop === "row gap" ? "rowGap" : "columnGap"] || []);
+    if (rects.length) return rects;
+  }
+  if (diffs.every(d => d.prop === "container width")) {
+    const r = node.rect;
+    return [{ ...r, width: 3 }, { ...r, x: r.x + r.width - 3, width: 3 }];
+  }
+  return [node.rect];
+}
+
+const COLOUR_PROPS = new Set(["color", "accentColor", "backgroundColor", "iconColor", "iconFill"]);
+const COLOUR_LABELS = { color: "text colour", accentColor: "highlighted words colour", backgroundColor: "background colour", iconColor: "icon colour", iconFill: "icon fill" };
+
+// Text colour: box the glyphs. Highlighted words only: box those words. Background / icons: box the element.
+function colourRects(node, diffs) {
+  const props = new Set(diffs.map((d) => d.prop));
+  const text = node.textRect && node.textRect.width > 0 ? node.textRect : null;
+  if (props.has("accentColor") && !props.has("color") && node.accentRects?.length) {
+    return props.size === 1 ? node.accentRects : [node.rect];
+  }
+  if ([...props].every((p) => p === "color" || p === "accentColor") && text) return [text];
+  return [node.rect];
+}
+
+function checkSpacing(rs, ts, pairs) {
+  const findings = [];
+  const TOL = 2;
+  for (const [i, j] of pairs) {
+    const r = rs[i];
+    const t = ts[j];
+    for (const [rn, tn] of pairNodes(r.spacing, t.spacing, true).pairs) {
+      if (rn.kind === "media" || tn.kind === "media") continue;
+      const diffs = [];
+      for (const p of Object.keys(SPACE_LABELS)) {
+        const a = rn.styles[p];
+        const b = tn.styles[p];
+        if (a === b) continue;
+        if ((p === "rowGap" || p === "columnGap") && rn.renderedGaps && tn.renderedGaps) {
+          const x = rn.renderedGaps[p], y = tn.renderedGaps[p];
+          if (rn.distributedGap || tn.distributedGap || x === null || y === null || Math.abs(x - y) <= TOL) continue;
+        }
+        if ((p === "marginTop" || p === "marginBottom") && (a === "auto" || b === "auto")) continue;
+        const x = pxNum(a);
+        const y = pxNum(b);
+        if (x !== null && y !== null && Math.abs(x - y) <= TOL) continue;
+        // margin: auto resolves to a fractional, content-driven pixel value; not a design difference.
+        if ((p === "marginTop" || p === "marginBottom") && [pxNum(a), pxNum(b)].some((v) => v !== null && v >= 24 && Math.abs(v - Math.round(v)) > 0.2)) continue;
+        // "normal" gap vs 0px is not a visible difference
+        if ((a === "normal" && y === 0) || (b === "normal" && x === 0)) continue;
+        diffs.push({ prop: SPACE_LABELS[p], ref: a, act: b });
+      }
+      for (const p of ["fontFamily", "fontSize", "fontWeight", "lineHeight", "letterSpacing", "wordSpacing", "color", "backgroundColor", "borderRadius", "iconWidth", "iconHeight", "iconColor", "iconFill", "accentColor"]) {
+        if (COLOUR_PROPS.has(p) && (rn.categoryKey || tn.categoryKey) && rn.categoryKey !== tn.categoryKey) continue;
+        const a = rn.styles[p];
+        const b = tn.styles[p];
+        if (a === undefined || b === undefined || sameStyle(a, b)) continue;
+        if (p === "borderRadius" && Math.abs(pxNum(a) - pxNum(b)) <= 2) continue;
+        if (p === "accentColor") {
+          const ca = a === "none" ? [] : a.split(" + "), cb = b === "none" ? [] : b.split(" + ");
+          if (ca.length === cb.length && ca.every(x => cb.some(y => sameStyle(x, y)))) continue;
+        }
+        if ((p === "wordSpacing" || p === "letterSpacing") && (a === "normal" || a === "0px") && (b === "normal" || b === "0px")) continue;
+        if (p === "iconWidth" || p === "iconHeight") {
+          // Photos are dynamic content: only small icons (both sides <= 96px) are compared by size.
+          if (Math.max(pxNum(rn.styles.iconWidth), pxNum(rn.styles.iconHeight), pxNum(tn.styles.iconWidth), pxNum(tn.styles.iconHeight)) > 96) continue;
+          if (Math.abs(pxNum(a) - pxNum(b)) <= 3) continue;
+        }
+        diffs.push({ prop: p, ref: a, act: b });
+      }
+      if (rn.repeatCount === tn.repeatCount && rn.widthPct !== null && tn.widthPct !== null && Math.abs(rn.widthPct - tn.widthPct) > 3) {
+        diffs.push({ prop: "container width", ref: `${rn.widthPct}%`, act: `${tn.widthPct}%` });
+      }
+      if (!diffs.length) continue;
+      // Colour changes get their own finding, boxed tightly around the coloured text so they are easy to see.
+      const colourDiffs = diffs.filter((d) => COLOUR_PROPS.has(d.prop));
+      const otherDiffs = diffs.filter((d) => !COLOUR_PROPS.has(d.prop));
+      if (colourDiffs.length) {
+        findings.push({
+          locate: true,
+          severity: "medium",
+          type: `Colour mismatch in "${title0(r)}"`,
+          detail: `${rn.name}: ${colourDiffs.map((d) => `${COLOUR_LABELS[d.prop]} ${d.ref} vs ${d.act}`).join(", ")}.`,
+          diffs: colourDiffs,
+          nodeTag: rn.tag,
+          refRects: colourRects(rn, colourDiffs),
+          tgtRects: colourRects(tn, colourDiffs),
+        });
+      }
+      if (!otherDiffs.length) continue;
+      findings.push({
+        locate: true,
+        severity: "medium",
+        type: `UI style mismatch in "${title0(r)}"`,
+        detail: `${rn.name}: ${otherDiffs.map((d) => `${d.prop} ${d.ref} vs ${d.act}`).join(", ")}.`,
+        diffs: otherDiffs,
+        nodeTag: rn.tag,
+        refRects: highlightRects(rn, otherDiffs),
+        tgtRects: highlightRects(tn, otherDiffs),
+      });
+    }
+  }
+  // Vertical space between consecutive matched sections
+  const ordered = [...pairs].sort((a, b) => a[0] - b[0]);
+  for (let k = 1; k < ordered.length; k++) {
+    const [pi, pj] = ordered[k - 1];
+    const [ci, cj] = ordered[k];
+    if (ci !== pi + 1 || cj !== pj + 1) continue;
+    const refGap = rs[ci].rect.y - (rs[pi].rect.y + rs[pi].rect.height);
+    const tgtGap = ts[cj].rect.y - (ts[pj].rect.y + ts[pj].rect.height);
+    if (Math.abs(refGap - tgtGap) <= TOL * 2) continue;
+    const band = (a, b) => ({ x: a.x, y: a.y + a.height, width: a.width, height: Math.max(b.y - (a.y + a.height), 4) });
+    findings.push({
+      locate: true,
+      severity: "medium",
+      type: `Section spacing mismatch`,
+      detail: `Space between "${title0(rs[pi])}" and "${title0(rs[ci])}" is ${refGap}px in reference, ${tgtGap}px in target.`,
+      refRects: [band(rs[pi].rect, rs[ci].rect)],
+      tgtRects: [band(ts[pj].rect, ts[cj].rect)],
+    });
+  }
+  return findings;
+}
+const title0 = (sec) => sec.heading || `section ${sec.index + 1}`;
+
+/**
+ * The reference is the baseline. A button, form field, label/heading text or whole block that exists in a reference
+ * section but has no counterpart at the same place in the matching target section is reported as missing, and
+ * highlighted in the target where it should be. The same check run the other way reports text and buttons that only
+ * the target has (an added eyebrow label, for example). Items in repeated lists (cards...) and long copy are ignored
+ * because they are dynamic content.
+ */
+function checkMissingElements(rs, ts, pairs) {
+  const findings = [];
+  for (const [i, j] of pairs) {
+    findings.push(...unmatchedNodes(rs[i], ts[j], "missing"));
+    findings.push(...unmatchedNodes(ts[j], rs[i], "extra"));
+  }
+  return findings;
+}
+
+function unmatchedNodes(fromSec, toSec, mode) {
+  const findings = [];
+  const nodes = fromSec.spacing || [];
+  const { unpaired, tgtOf } = pairNodes(nodes, toSec.spacing);
+  const unpairedSet = new Set(unpaired);
+  const byPath = new Map(nodes.map((n) => [n.path, n]));
+  const below = (n) => nodes.filter((d) => d.path.startsWith(n.path + "/"));
+  const shortText = (n) => n.kind === "text" && !n.listSize && (/^h[1-6]$/.test(n.tag) || (n.textLen > 0 && n.textLen <= 40));
+  const reportable = (n) => {
+    if (n.path === "" || n.repeatCount) return false;
+    if (["button", "input"].includes(n.kind)) return n.uniq;
+    if (n.kind === "text") return shortText(n);
+    if (n.kind === "box") {
+      // A block is missing only when none of its text found a counterpart elsewhere (not merely re-wrapped).
+      const content = below(n).filter((d) => ["text", "button", "input"].includes(d.kind));
+      return content.length > 0 && content.every((d) => unpairedSet.has(d) && !d.repeatCount);
+    }
+    return false;
+  };
+  const reported = new Set();
+  for (const rn of unpaired) {
+    if (!reportable(rn)) continue;
+    // Report only the topmost missing item; its children are missing with it.
+    const parts = rn.path.split("/");
+    let ancestorReported = false;
+    let host = null;
+    for (let n = parts.length - 1; n >= 1; n--) {
+      const an = byPath.get(parts.slice(0, n).join("/"));
+      if (!an) continue;
+      if (reported.has(an)) { ancestorReported = true; break; }
+      if (tgtOf.has(an)) { host = tgtOf.get(an); break; }
+    }
+    if (ancestorReported) continue;
+    host = host || tgtOf.get(byPath.get(""));
+    if (!host) continue;
+    reported.add(rn);
+    const firstText = rn.kind === "box" ? below(rn).find((d) => d.name.includes("“")) : null;
+    const name = firstText ? `${rn.tag} with ${firstText.name}` : rn.name;
+    const noun = { button: "button", text: /^h[1-6]$/.test(rn.tag) ? "heading" : "text", box: "block", input: "form field" }[rn.kind];
+    const where = `"${title0(mode === "missing" ? fromSec : toSec)}"`;
+    if (mode === "extra") {
+      findings.push({
+        locate: true,
+        severity: "medium",
+        type: `Extra ${noun} in ${where}`,
+        detail: `${name} is in the target but not in the reference.`,
+        tgtRects: [rn.rect],
+      });
+      continue;
+    }
+    // Place the highlight right after the previous sibling when it exists in the target.
+    const idx = Number(parts[parts.length - 1]);
+    const prevRef = idx > 0 ? byPath.get([...parts.slice(0, -1), idx - 1].join("/")) : null;
+    const prev = prevRef ? tgtOf.get(prevRef) : null;
+    const rect = prev
+      ? { x: prev.rect.x, y: prev.rect.y + prev.rect.height, width: Math.max(prev.rect.width, rn.rect.width), height: Math.max(rn.rect.height, 8) }
+      : { x: host.rect.x, y: host.rect.y, width: Math.max(rn.rect.width, 8), height: Math.max(rn.rect.height, 8) };
+    findings.push({
+      locate: true,
+      severity: "high",
+      type: `Missing ${noun} in ${where}`,
+      detail: `${name} is in the reference but has no counterpart in the target. Highlighted where it should be.`,
+      refRects: [rn.rect],
+      tgtRects: [rect],
+    });
+  }
+  return findings;
+}
+
+function checkChecklist(tgt, checklist) {
+  const findings = [];
+  for (const raw of checklist) {
+    const item = norm(raw);
+    if (!item) continue;
+    const found = tgt.labelBag.some((l) => l && (l === item || l.includes(item))) || tgt.bodyText.includes(item);
+    if (!found) {
+      findings.push({
+        severity: "high",
+        type: "Expected item not found",
+        detail: `"${raw}" from your checklist was not found on the target page.`,
+      });
+    }
+  }
+  return findings;
+}
+
+/** Compare matched visual components; global tag frequencies vary with CMS content. */
+function checkStyling(ref, tgt) {
+  const typography = new Set(["fontFamily", "fontSize", "fontWeight", "lineHeight", "letterSpacing", "wordSpacing"]);
+  return checkCompleteness(ref, tgt)
+    .filter(f => f.diffs?.some(d => typography.has(d.prop)))
+    .map(f => ({ ...f, type: `Style mismatch: ${f.nodeTag || "component"}` }));
+}
+
+function dedupe(list) {
+  const seen = new Set();
+  return list.filter((f) => {
+    const k = `${f.type}|${f.detail}`;
+    if (seen.has(k)) return false;
+    seen.add(k);
+    return true;
+  });
+}
+
+/** Reuse the UI-check inventory and engines on an already-captured local page. */
+export async function inspectUICheckPage(page, ignoreSelectors = []) {
+  return page.evaluate(inspectPage, { props: STYLE_PROPS, ignore: ignoreSelectors.join(",") });
+}
+export function collectUICheck(ref, tgt, { checklist = [], styling = true } = {}) {
+  const completeness = [...(ref ? checkCompleteness(ref, tgt) : []), ...checkChecklist(tgt, checklist)];
+  const findings = ref && styling ? checkStyling(ref, tgt) : [];
+  const styleKeys = new Set(findings.map(f => JSON.stringify([f.refRects, f.tgtRects, f.diffs])));
+  return { completeness: completeness.filter(f => !styleKeys.has(JSON.stringify([f.refRects, f.tgtRects, f.diffs]))), layout: dedupe(tgt.layout), styling: findings };
+}
+
+/**
+ * Spell-checks the visible text with cspell (en + en-GB). Custom words are never flagged.
+ */
+export async function checkSpelling(texts, customWords = [], signal) {
+  signal?.throwIfAborted();
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "uicheck-"));
+  try {
+    const textFile = path.join(dir, "text.txt");
+    const cfgFile = path.join(dir, "cspell.json");
+    // Only spell-check Latin-script text; other scripts (Arabic, CJK, ...) would all be flagged.
+    const nonLatin = /(?!\p{Script=Latin})\p{L}/u;
+    texts = texts.filter((t) => !nonLatin.test(t.text));
+    fs.writeFileSync(textFile, texts.map((t) => t.text).join("\n"));
+    fs.writeFileSync(
+      cfgFile,
+      JSON.stringify({
+        language: "en,en-GB",
+        words: customWords,
+        // Domain names / paths such as pharmacyregulation.org are not prose.
+        ignoreRegExpList: ["/\\b[\\w-]+(\\.[\\w-]+)*\\.(org|com|net|uk|co|io|gov|nhs|info|app|dev)\\b[\\w./?=&%-]*/i"],
+      })
+    );
+    const bin = path.join(__dirname, "node_modules", ".bin", "cspell");
+    let stdout = "";
+    try {
+      ({ stdout } = await execFileAsync(bin, ["lint", "--no-progress", "--no-summary", "--show-suggestions", "-c", "cspell.json", "text.txt"], { cwd: dir, maxBuffer: 10 * 1024 * 1024, signal }));
+    } catch (e) {
+      // cspell exits with code 1 when it finds unknown words; that is a normal result.
+      if (e.code === 1 && typeof e.stdout === "string") stdout = e.stdout;
+      else throw e;
+    }
+    // Lines look like: text.txt:1:1 - Unknown word (Maleria) Suggestions: [Malaria, Materia, ...]
+    const found = new Map();
+    for (const line of stdout.split("\n")) {
+      const m = /Unknown word \((.+?)\)(?:\s+Suggestions: \[(.*)\])?/.exec(line);
+      if (!m || found.has(m[1])) continue;
+      const seen = new Set();
+      const suggestions = (m[2] || "")
+        .split(",")
+        .map((x) => x.trim().replace(/\*$/, ""))
+        .filter((x) => {
+          const k = x.toLowerCase();
+          if (!x || k === m[1].toLowerCase() || seen.has(k)) return false;
+          seen.add(k);
+          return true;
+        })
+        .slice(0, 4);
+      found.set(m[1], suggestions);
+    }
+    return [...found.entries()].map(([w, suggestions]) => {
+      const re = new RegExp(`\\b${w.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`, "i");
+      const hits = texts.filter((t) => re.test(t.text));
+      const hit = hits[0];
+      let context = "";
+      if (hit) {
+        // Show a window of text around the word instead of cutting the start of the string.
+        const at = hit.text.search(re);
+        const from = Math.max(0, at - 50);
+        context = (from > 0 ? "…" : "") + hit.text.slice(from, at + w.length + 50) + (at + w.length + 50 < hit.text.length ? "…" : "");
+      }
+      return {
+        word: w,
+        suggestions,
+        tag: hit?.tag || "",
+        context,
+        rects: hits.slice(0, 5).map((h) => h.rect).filter(Boolean),
+      };
+    });
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Optional "where to look" layer: a transparent PNG with only the differing pixels painted, to overlay on the
+ * target screenshot. Content differences show up too, so it never produces findings by itself.
+ */
+function pixelDiffLayer(run, key, refShot, tgtShot) {
+  if (!refShot || !tgtShot) return null;
+  try {
+    const read = (img) => getPNG().sync.read(fs.readFileSync(path.join(OUTPUT_DIR, "..", img)));
+    const a = read(refShot.image);
+    const b = read(tgtShot.image);
+    const width = Math.max(a.width, b.width);
+    const height = Math.max(a.height, b.height);
+    const diff = new (getPNG())({ width, height });
+    const changed = getPixelmatch()(normalizeImageSize(a, width, height).data, normalizeImageSize(b, width, height).data, diff.data, width, height, {
+      threshold: 0.1,
+      includeAA: false,
+      diffMask: true,
+      diffColor: [244, 63, 94],
+    });
+    const name = `pixeldiff-${key}.png`;
+    fs.writeFileSync(path.join(run.dir, name), getPNG().sync.write(diff));
+    return {
+      image: `visual-reports/runs/${run.id}/${name}`,
+      width,
+      height,
+      percent: Math.round((changed / (width * height)) * 10000) / 100,
+    };
+  } catch {
+    return null;
+  }
+}
+
+export async function runUiCheck({
+  referenceUrl = "",
+  targetUrl,
+  viewports = ["desktop"],
+  checklist = [],
+  customWords = [],
+  ignoreSelectors = [],
+  spelling = false,
+  styling = true,
+  pixelDiff = false,
+}) {
+  if (!targetUrl) throw new Error("Target URL is required");
+  if (!referenceUrl && !checklist.length) {
+    throw new Error("Provide a Reference URL, an expected-items checklist, or both");
+  }
+  const ignore = ignoreSelectors.join(",");
+  const browser = await chromium.launch({ headless: true });
+  const run = newRunDir();
+  try {
+    const results = [];
+    let spellTexts = null;
+    let spellViewport = "desktop";
+    for (const key of viewports) {
+      const vp = VIEWPORTS[key];
+      if (!vp) continue;
+      const tgt = await inspect(browser, targetUrl, vp, ignore, `target-${key}.png`, true, run);
+      const ref = referenceUrl ? await inspect(browser, referenceUrl, vp, ignore, `reference-${key}.png`, true, run) : null;
+      if (key === "desktop" || !spellTexts) {
+        spellTexts = tgt.texts;
+        spellViewport = key;
+      }
+
+      const checks = collectUICheck(ref, tgt, { checklist, styling });
+      results.push({
+        viewport: { key, ...vp },
+        counts: { reference: ref?.counts || null, target: tgt.counts },
+        reference: ref?.shot || null,
+        target: tgt.shot || null,
+        ...checks,
+        pixelDiff: pixelDiff ? pixelDiffLayer(run, key, ref?.shot, tgt.shot) : null,
+      });
+    }
+
+    const spell = spelling && spellTexts ? await checkSpelling(spellTexts, customWords) : [];
+
+    const all = [
+      ...results.flatMap((r) => [...r.completeness, ...r.layout, ...r.styling]),
+      ...spell.map(() => ({ severity: "medium" })),
+    ];
+    const summary = {
+      high: all.filter((f) => f.severity === "high").length,
+      medium: all.filter((f) => f.severity === "medium").length,
+      low: all.filter((f) => f.severity === "low").length,
+      info: all.filter((f) => f.severity === "info").length,
+      misspellings: spell.length,
+    };
+    return { runId: run.id, referenceUrl, targetUrl, summary, results, spelling: spell, spellingRan: Boolean(spelling), spellingViewport: spellViewport, timestamp: new Date().toISOString() };
+  } finally {
+    await browser.close();
+  }
+}
+
+/**
+ * Spell-checks the visible text of one URL (used by the DOM/CSS page).
+ */
+export async function spellCheckUrl({ url, viewport = VIEWPORTS.desktop, customWords = [], ignoreSelectors = [] }) {
+  const browser = await chromium.launch({ headless: true });
+  try {
+    const page = await inspect(browser, url, viewport, ignoreSelectors.join(","), null);
+    return await checkSpelling(page.texts, customWords);
+  } finally {
+    await browser.close();
+  }
+}