@capagents/forgeqe 0.0.0-stage → 1.0.1

package/src/quality/budgets.ts

@@ -0,0 +1,249 @@
+import { existsSync, readFileSync } from "node:fs"
+import path from "node:path"
+
+import { DEFAULT_VISUAL, visualConfig, visualLine, type VisualConfig, type VisualReport } from "./visual.ts"
+
+/**
+ * Accessibility (WCAG) and performance (Core Web Vitals) of the pages a run visited, judged against budgets. A run
+ * fails on quality only when a budget set in forgeqe.yaml is exceeded; without budgets both are reported, never
+ * failed. Accessibility comes from axe-core, run on each page with the rules of the chosen standard; timings come
+ * from the browser's own performance entries.
+ */
+
+export const STANDARDS: Record<string, { label: string; tags: string[] }> = {
+  wcag2a: { label: "WCAG 2.x A", tags: ["wcag2a"] },
+  wcag21aa: { label: "WCAG 2.1 AA", tags: ["wcag2a", "wcag2aa", "wcag21a", "wcag21aa"] },
+  wcag22aa: { label: "WCAG 2.2 AA", tags: ["wcag2a", "wcag2aa", "wcag21a", "wcag21aa", "wcag22aa"] },
+  wcag21aaa: { label: "WCAG 2.1 AAA", tags: ["wcag2a", "wcag2aa", "wcag2aaa", "wcag21a", "wcag21aa", "wcag21aaa"] },
+  section508: { label: "Section 508", tags: ["section508", "wcag2a", "wcag2aa"] },
+  en301549: { label: "EN 301 549", tags: ["EN-301-549", "wcag2a", "wcag2aa", "wcag21a", "wcag21aa"] },
+  "best-practice": { label: "Best practice", tags: ["best-practice"] },
+}
+
+export const DISCLAIMER = "Automated checks find a part of the WCAG problems (often 30–50%); they are a pre-check, not conformance. A manual review still matters."
+
+export type Impact = "critical" | "serious" | "moderate" | "minor"
+export const IMPACTS: Impact[] = ["critical", "serious", "moderate", "minor"]
+
+export type A11yBudget = Partial<Record<Impact, number>> & { /** Rules that must not fail at all. */ rules?: string[]; /** Rules left out of the budget. */ ignore?: string[] }
+
+export const METRICS = ["lcp_ms", "cls", "inp_ms", "fcp_ms", "ttfb_ms", "load_ms"] as const
+export type Metric = (typeof METRICS)[number]
+export type PerfLimits = Partial<Record<Metric, number>>
+export type PerfBudget = PerfLimits & { /** Limits for pages whose path starts with the key (/checkout). */ pages?: Record<string, PerfLimits> }
+
+/** Google's "good" thresholds: `performance: web-vitals` in forgeqe.yaml. */
+export const WEB_VITALS: PerfLimits = { lcp_ms: 2500, cls: 0.1, inp_ms: 200, fcp_ms: 1800, ttfb_ms: 800 }
+
+export type QualityConfig = {
+  /** Screenshots of each page compared with approved baselines (quality.visual). */
+  visual: VisualConfig
+  /** A key of STANDARDS (default wcag21aa). */
+  standard: string
+  /** Also run axe-core's best-practice rules (reported, counted in budgets like the others). */
+  bestPractice: boolean
+  /** axe (default) or basic: ForgeQE's own checks when axe-core cannot be used. */
+  engine: "axe" | "basic"
+  /** visual: the most a page may differ from its baseline, in percent of its pixels. */
+  budgets: { accessibility?: A11yBudget; performance?: PerfBudget; visual?: number }
+}
+
+export const DEFAULT_QUALITY: QualityConfig = { standard: "wcag21aa", bestPractice: false, engine: "axe", budgets: {}, visual: DEFAULT_VISUAL }
+
+export function axeTags(q: QualityConfig): string[] {
+  const tags = STANDARDS[q.standard]?.tags || STANDARDS.wcag21aa.tags
+  return q.bestPractice && !tags.includes("best-practice") ? [...tags, "best-practice"] : tags
+}
+
+const num = (v: unknown) => (v === undefined || v === null || v === "" || Number.isNaN(Number(v)) ? undefined : Number(v))
+
+function limits(raw: Record<string, unknown>): PerfLimits {
+  const out: PerfLimits = {}
+  for (const m of METRICS) {
+    const v = num(raw[m] ?? raw[m.replace(/_ms$/, "")])
+    if (v !== undefined) out[m] = v
+  }
+  return out
+}
+
+/** quality: in forgeqe.yaml. */
+export function qualityConfig(raw: unknown): QualityConfig {
+  const q = (raw && typeof raw === "object" ? raw : {}) as Record<string, any>
+  const a11y = (q.accessibility || {}) as Record<string, any>
+  const budgets = (q.budgets || {}) as Record<string, any>
+  const standard = String(a11y.standard || "wcag21aa").toLowerCase().replace(/[^a-z0-9-]/g, "")
+  if (!STANDARDS[standard]) throw new Error(`quality.accessibility.standard "${a11y.standard}" is not one of ${Object.keys(STANDARDS).join(", ")}.`)
+  const out: QualityConfig = { standard, bestPractice: a11y.best_practice === true, engine: a11y.engine === "basic" ? "basic" : "axe", budgets: {}, visual: visualConfig(q.visual) }
+  const vb = budgets.visual
+  const vlimit = vb === true ? 0.1 : num(vb && typeof vb === "object" ? vb.max_diff_percent : vb)
+  if (vlimit !== undefined) out.budgets.visual = vlimit
+  const ab = budgets.accessibility
+  if (ab && typeof ab === "object") {
+    const b: A11yBudget = {}
+    for (const i of IMPACTS) if (num(ab[i]) !== undefined) b[i] = num(ab[i])
+    if (Array.isArray(ab.rules)) b.rules = ab.rules.map(String)
+    if (Array.isArray(ab.ignore)) b.ignore = ab.ignore.map(String)
+    out.budgets.accessibility = b
+  } else if (ab === true) out.budgets.accessibility = { critical: 0, serious: 0 }
+  const pb = budgets.performance
+  if (pb === "web-vitals" || pb === true) out.budgets.performance = { ...WEB_VITALS }
+  else if (pb && typeof pb === "object") {
+    const base = pb.preset === "web-vitals" ? { ...WEB_VITALS } : {}
+    out.budgets.performance = { ...base, ...limits(pb), ...(pb.pages && typeof pb.pages === "object" ? { pages: Object.fromEntries(Object.entries(pb.pages as Record<string, Record<string, unknown>>).map(([k, v]) => [k, limits(v || {})])) } : {}) }
+  }
+  return out
+}
+
+// -- reading a run --------------------------------------------------------------------------------
+
+export type A11yIssue = { rule: string; wcag?: string; level?: string; impact: Impact; help: string; helpUrl?: string; count: number; examples?: { html?: string; target?: string; text?: string }[] }
+export type A11yPage = { url: string; title?: string; engine?: string; tags?: string[]; passed?: string[]; incomplete?: string[]; issues: A11yIssue[] }
+export type PerfPage = { url: string; lcp?: number | null; cls?: number | null; inp?: number | null; fcp?: number | null; ttfb?: number | null; dcl?: number | null; load?: number | null; requests?: number; kb?: number }
+
+const readJson = <T>(file: string): T | null => {
+  try {
+    return existsSync(file) ? (JSON.parse(readFileSync(file, "utf8")) as T) : null
+  } catch {
+    return null
+  }
+}
+
+export const readA11y = (runDir: string) => readJson<A11yPage[]>(path.join(runDir, "accessibility.json")) || []
+export const readPerf = (runDir: string) => readJson<PerfPage[]>(path.join(runDir, "performance.json")) || []
+
+const VALUE: Record<Metric, keyof PerfPage> = { lcp_ms: "lcp", cls: "cls", inp_ms: "inp", fcp_ms: "fcp", ttfb_ms: "ttfb", load_ms: "load" }
+export const METRIC_LABEL: Record<Metric, string> = { lcp_ms: "LCP", cls: "CLS", inp_ms: "INP", fcp_ms: "FCP", ttfb_ms: "TTFB", load_ms: "Load" }
+export const fmtMetric = (m: Metric, v: number) => (m === "cls" ? v.toFixed(3).replace(/0+$/, "").replace(/\.$/, "") : v >= 1000 ? `${(v / 1000).toFixed(1)}s` : `${Math.round(v)}ms`)
+
+export type Breach = { kind: "accessibility" | "performance" | "visual"; page: string; text: string }
+
+export type QualityReport = {
+  standard: string
+  engine: string
+  accessibility: {
+    pages: number
+    /** Each rule that failed somewhere: on how many pages, how many elements. */
+    failed: { rule: string; wcag?: string; level?: string; impact: Impact; help: string; helpUrl?: string; pages: number; count: number }[]
+    /** Rules that passed on every page they ran on. */
+    passed: string[]
+    byImpact: Record<Impact, number>
+  }
+  performance: { pages: (PerfPage & { over: string[] })[] }
+  /** Each page against its visual baseline. */
+  visual?: VisualReport
+  budgets: { accessibility: boolean; performance: boolean; visual?: boolean }
+  breaches: Breach[]
+}
+
+const pathOf = (url: string) => {
+  try {
+    return new URL(url).pathname
+  } catch {
+    return url
+  }
+}
+
+/** The limits for a page: the budget's, with the longest matching path prefix's on top. */
+export function limitsFor(b: PerfBudget, url: string): PerfLimits {
+  const p = pathOf(url)
+  const { pages, ...base } = b
+  const match = Object.keys(pages || {})
+    .filter((k) => p === k || p.startsWith(k.endsWith("/") ? k : `${k}/`) || (k !== "/" && p.startsWith(k)))
+    .sort((a, b) => b.length - a.length)[0]
+  return { ...base, ...(match ? pages![match] : {}) }
+}
+
+/** Judge a run's pages: WCAG rules passed and failed, Core Web Vitals, and every budget exceeded. */
+export function evaluateQuality(runDir: string, q: QualityConfig): QualityReport | null {
+  const a11y = readA11y(runDir)
+  const perf = readPerf(runDir)
+  if (!a11y.length && !perf.length) return null
+  const ignore = new Set(q.budgets.accessibility?.ignore || [])
+  const failed = new Map<string, QualityReport["accessibility"]["failed"][number]>()
+  const passedAnywhere = new Set<string>()
+  const byImpact: Record<Impact, number> = { critical: 0, serious: 0, moderate: 0, minor: 0 }
+  const breaches: Breach[] = []
+  for (const page of a11y) {
+    for (const r of page.passed || []) passedAnywhere.add(r)
+    const counted: Record<Impact, A11yIssue[]> = { critical: [], serious: [], moderate: [], minor: [] }
+    for (const i of page.issues) {
+      const impact = (IMPACTS.includes(i.impact) ? i.impact : "minor") as Impact
+      byImpact[impact] += i.count
+      const f = failed.get(i.rule) || { rule: i.rule, wcag: i.wcag, level: i.level, impact, help: i.help, helpUrl: i.helpUrl, pages: 0, count: 0 }
+      f.pages++
+      f.count += i.count
+      failed.set(i.rule, f)
+      if (!ignore.has(i.rule)) counted[impact].push(i)
+    }
+    const b = q.budgets.accessibility
+    if (b) {
+      for (const impact of IMPACTS) {
+        const limit = b[impact]
+        const n = counted[impact].reduce((a, i) => a + i.count, 0)
+        if (limit !== undefined && n > limit)
+          breaches.push({ kind: "accessibility", page: page.url, text: `${n} ${impact} accessibility violation${n === 1 ? "" : "s"} (budget ${limit}): ${counted[impact].map((i) => `${i.rule}${i.wcag ? ` (WCAG ${i.wcag})` : ""}`).join(", ")}` })
+      }
+      for (const rule of b.rules || []) {
+        const hit = page.issues.find((i) => i.rule === rule)
+        if (hit) breaches.push({ kind: "accessibility", page: page.url, text: `${rule} fails on ${hit.count} element${hit.count === 1 ? "" : "s"} (budget: must pass)` })
+      }
+    }
+  }
+  const perfPages = perf.map((p) => {
+    const over: string[] = []
+    if (q.budgets.performance) {
+      const lim = limitsFor(q.budgets.performance, p.url)
+      for (const m of METRICS) {
+        const v = p[VALUE[m]] as number | null | undefined
+        const limit = lim[m]
+        if (limit === undefined || v === null || v === undefined) continue
+        if (v > limit) over.push(`${METRIC_LABEL[m]} ${fmtMetric(m, v)} (budget ${fmtMetric(m, limit)})`)
+      }
+    }
+    if (over.length) breaches.push({ kind: "performance", page: p.url, text: over.join(", ") })
+    return { ...p, over }
+  })
+  const engine = a11y.find((p) => p.engine)?.engine || (a11y.length ? "forgeqe" : "")
+  return {
+    standard: STANDARDS[q.standard]?.label || q.standard,
+    engine,
+    accessibility: {
+      pages: a11y.length,
+      failed: [...failed.values()].sort((a, b) => IMPACTS.indexOf(a.impact) - IMPACTS.indexOf(b.impact) || b.count - a.count),
+      passed: [...passedAnywhere].filter((r) => !failed.has(r)).sort(),
+      byImpact,
+    },
+    performance: { pages: perfPages },
+    budgets: { accessibility: Boolean(q.budgets.accessibility), performance: Boolean(q.budgets.performance) },
+    breaches,
+  }
+}
+
+/** A report with no accessibility or timing data, for a run that only has visual captures. */
+export function emptyReport(q: QualityConfig): QualityReport {
+  return {
+    standard: STANDARDS[q.standard]?.label || q.standard,
+    engine: "",
+    accessibility: { pages: 0, failed: [], passed: [], byImpact: { critical: 0, serious: 0, moderate: 0, minor: 0 } },
+    performance: { pages: [] },
+    budgets: { accessibility: Boolean(q.budgets.accessibility), performance: Boolean(q.budgets.performance) },
+    breaches: [],
+  }
+}
+
+/** One line for summaries: WCAG rules, vitals, and budgets. */
+export function qualityLine(r: QualityReport): string {
+  const parts: string[] = []
+  if (r.accessibility.pages) {
+    const n = r.accessibility.failed.length
+    parts.push(`${r.standard}: ${r.accessibility.passed.length} rules passed, ${n} failed${n ? ` (${IMPACTS.filter((i) => r.accessibility.byImpact[i]).map((i) => `${r.accessibility.byImpact[i]} ${i}`).join(", ")})` : ""}`)
+  }
+  const timed = r.performance.pages.filter((p) => p.lcp != null || p.cls != null)
+  if (timed.length) {
+    const worst = (k: "lcp" | "cls" | "inp") => Math.max(...timed.map((p) => Number(p[k] ?? 0)))
+    parts.push(`worst LCP ${fmtMetric("lcp_ms", worst("lcp"))}, CLS ${fmtMetric("cls", worst("cls"))}${timed.some((p) => p.inp) ? `, INP ${fmtMetric("inp_ms", worst("inp"))}` : ""}`)
+  }
+  if (r.visual?.pages.length) parts.push(`visual: ${visualLine(r.visual)}`)
+  if (r.budgets.accessibility || r.budgets.performance || r.budgets.visual) parts.push(r.breaches.length ? `${r.breaches.length} budget${r.breaches.length === 1 ? "" : "s"} exceeded` : "within budgets")
+  return parts.join(" · ")
+}

package/src/quality/history.ts

@@ -0,0 +1,149 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs"
+import path from "node:path"
+
+import type { Card } from "../card.ts"
+import { fmtMetric, IMPACTS, type Impact, type Metric, type QualityReport } from "./budgets.ts"
+
+/**
+ * Each page's accessibility and timings over time, so a run shows what got better or worse: in
+ * quality-history.json in the reports folder (keep it between CI runs as a cache to track a pipeline's trend).
+ */
+
+export const HISTORY_NAME = "quality-history.json"
+const KEEP = 50
+const WINDOW = 10
+
+type Entry = { at: string; run: string; a11y?: Record<Impact, number> & { rules: string[] }; perf?: Partial<Record<"lcp" | "cls" | "inp" | "fcp" | "ttfb" | "load", number>> }
+type HistoryFile = { version: 1; pages: Record<string, Entry[]> }
+
+export const historyFile = (outDir: string) => path.join(outDir, HISTORY_NAME)
+
+/** A page's key: its origin and path, without query or hash. */
+export function pageKey(url: string): string {
+  try {
+    const u = new URL(url)
+    return `${u.origin}${u.pathname.replace(/\/+$/, "") || "/"}`
+  } catch {
+    return url
+  }
+}
+
+export function readQualityHistory(file: string): HistoryFile {
+  try {
+    const d = JSON.parse(readFileSync(file, "utf8")) as HistoryFile
+    return { version: 1, pages: d?.pages && typeof d.pages === "object" ? d.pages : {} }
+  } catch {
+    return { version: 1, pages: {} }
+  }
+}
+
+/** Add one run's pages. */
+export function recordQuality(file: string, report: QualityReport, a11yPages: { url: string; issues: { rule: string; impact: string; count: number }[] }[], run: string, at = new Date().toISOString()): void {
+  const h = readQualityHistory(file)
+  const entries = new Map<string, Entry>()
+  const entry = (url: string) => {
+    const k = pageKey(url)
+    const e = entries.get(k) || { at, run }
+    entries.set(k, e)
+    return e
+  }
+  for (const p of a11yPages) {
+    const counts: Record<Impact, number> = { critical: 0, serious: 0, moderate: 0, minor: 0 }
+    for (const i of p.issues) counts[(IMPACTS.includes(i.impact as Impact) ? i.impact : "minor") as Impact] += i.count
+    entry(p.url).a11y = { ...counts, rules: [...new Set(p.issues.map((i) => i.rule))].sort() }
+  }
+  for (const p of report.performance.pages) {
+    const perf: Entry["perf"] = {}
+    for (const k of ["lcp", "cls", "inp", "fcp", "ttfb", "load"] as const) if (typeof p[k] === "number") perf[k] = p[k] as number
+    if (Object.keys(perf).length) entry(p.url).perf = perf
+  }
+  for (const [k, e] of entries) h.pages[k] = [...(h.pages[k] || []), e].slice(-KEEP)
+  mkdirSync(path.dirname(file), { recursive: true })
+  writeFileSync(file, `${JSON.stringify(h, null, 1)}\n`)
+}
+
+const median = (xs: number[]) => {
+  const s = [...xs].sort((a, b) => a - b)
+  return s.length ? (s.length % 2 ? s[(s.length - 1) / 2] : (s[s.length / 2 - 1] + s[s.length / 2]) / 2) : NaN
+}
+
+/** How much worse than the usual value counts as a regression: a share, and an absolute amount so noise on fast pages does not count. */
+const WORSE: Record<"lcp" | "cls" | "inp" | "fcp" | "ttfb" | "load", { share: number; min: number; metric: Metric }> = {
+  lcp: { share: 0.2, min: 300, metric: "lcp_ms" },
+  cls: { share: 0.25, min: 0.05, metric: "cls" },
+  inp: { share: 0.25, min: 50, metric: "inp_ms" },
+  fcp: { share: 0.2, min: 300, metric: "fcp_ms" },
+  ttfb: { share: 0.3, min: 200, metric: "ttfb_ms" },
+  load: { share: 0.25, min: 500, metric: "load_ms" },
+}
+
+export type PageTrend = {
+  page: string
+  runs: number
+  /** Accessibility violations by impact, oldest first, last WINDOW runs. */
+  a11y: { latest?: Record<Impact, number>; trail: number[]; newRules: string[]; fixedRules: string[] }
+  perf: { latest: Entry["perf"]; usual: Entry["perf"]; worse: string[]; better: string[] }
+}
+
+/** Each page's trend: the latest run against the one before (rules) and against the usual values of the last runs (timings). */
+export function qualityTrends(file: string, filter?: string): PageTrend[] {
+  const h = readQualityHistory(file)
+  const f = (filter || "").toLowerCase()
+  return Object.entries(h.pages)
+    .filter(([k]) => !f || k.toLowerCase().includes(f))
+    .map(([page, entries]) => {
+      const withA11y = entries.filter((e) => e.a11y)
+      const last = withA11y.at(-1)?.a11y
+      const prev = withA11y.at(-2)?.a11y
+      const withPerf = entries.filter((e) => e.perf)
+      const latest = withPerf.at(-1)?.perf || {}
+      const before = withPerf.slice(-WINDOW - 1, -1)
+      const usual: Entry["perf"] = {}
+      const worse: string[] = []
+      const better: string[] = []
+      for (const k of Object.keys(WORSE) as (keyof typeof WORSE)[]) {
+        const xs = before.map((e) => e.perf?.[k]).filter((v): v is number => typeof v === "number")
+        const now = latest[k]
+        if (!xs.length || typeof now !== "number") continue
+        const m = median(xs)
+        usual[k] = m
+        const { share, min, metric } = WORSE[k]
+        if (now - m > Math.max(min, m * share)) worse.push(`${k.toUpperCase()} ${fmtMetric(metric, now)} (usually ${fmtMetric(metric, m)})`)
+        else if (m - now > Math.max(min, m * share)) better.push(`${k.toUpperCase()} ${fmtMetric(metric, now)} (usually ${fmtMetric(metric, m)})`)
+      }
+      return {
+        page,
+        runs: entries.length,
+        a11y: {
+          ...(last ? { latest: { critical: last.critical, serious: last.serious, moderate: last.moderate, minor: last.minor } } : {}),
+          trail: withA11y.slice(-WINDOW).map((e) => IMPACTS.reduce((a, i) => a + (e.a11y![i] || 0), 0)),
+          newRules: last && prev ? last.rules.filter((r) => !prev.rules.includes(r)) : [],
+          fixedRules: last && prev ? prev.rules.filter((r) => !last.rules.includes(r)) : [],
+        },
+        perf: { latest, usual, worse, better },
+      }
+    })
+    .sort((a, b) => b.perf.worse.length + b.a11y.newRules.length - (a.perf.worse.length + a.a11y.newRules.length) || b.runs - a.runs)
+}
+
+export function trendsCard(trends: PageTrend[], file: string, cwd: string): Card {
+  const body: string[] = []
+  for (const t of trends.slice(0, 20)) {
+    const a = t.a11y.latest
+    const total = a ? IMPACTS.reduce((s, i) => s + a[i], 0) : undefined
+    body.push(`▸ ${t.page}  · ${t.runs} run${t.runs === 1 ? "" : "s"}`)
+    if (a) body.push(`    accessibility: ${total} violation${total === 1 ? "" : "s"}${total ? ` (${IMPACTS.filter((i) => a[i]).map((i) => `${a[i]} ${i}`).join(", ")})` : ""}  trend ${t.a11y.trail.join(" → ")}`)
+    if (t.a11y.newRules.length) body.push(`    ✗ new: ${t.a11y.newRules.join(", ")}`)
+    if (t.a11y.fixedRules.length) body.push(`    ✓ fixed: ${t.a11y.fixedRules.join(", ")}`)
+    const l = t.perf.latest || {}
+    const shown = (["lcp", "cls", "inp", "fcp", "ttfb"] as const).filter((k) => typeof l[k] === "number").map((k) => `${k.toUpperCase()} ${fmtMetric(WORSE[k].metric, l[k]!)}`)
+    if (shown.length) body.push(`    timings: ${shown.join(", ")}`)
+    for (const w of t.perf.worse) body.push(`    ✗ slower: ${w}`)
+    for (const b of t.perf.better) body.push(`    ✓ faster: ${b}`)
+  }
+  if (trends.length > 20) body.push(`and ${trends.length - 20} more pages`)
+  const rel = path.relative(cwd, file)
+  body.push("", `History   ${rel && !rel.startsWith("..") ? rel : file}`)
+  const regress = trends.filter((t) => t.perf.worse.length || t.a11y.newRules.length).length
+  return { status: regress ? "fail" : trends.length ? "ok" : "stopped", title: trends.length ? `Accessibility and performance over time: ${regress ? `${regress} page${regress === 1 ? "" : "s"} got worse` : "nothing got worse"}` : "No accessibility or performance history yet", stats: `${trends.length} page${trends.length === 1 ? "" : "s"}`, body }
+}

package/src/quality/visual.ts

@@ -0,0 +1,201 @@
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
+import path from "node:path"
+
+import pixelmatch from "pixelmatch"
+import { PNG } from "pngjs"
+
+/**
+ * Visual comparison: each page a run visits is captured (animations frozen, masked regions hidden) and compared
+ * pixel by pixel with its approved baseline. A page with no baseline yet gets its first capture as the baseline. The
+ * changed share of pixels is reported for every page; a run fails on it only when quality.budgets.visual sets a
+ * limit. Baselines are per page, viewport size, and operating system (fonts render differently), in
+ * .forgeqe/visual-baselines/ next to forgeqe.yaml: commit them to share them, and approve a change on purpose.
+ */
+
+export type VisualConfig = {
+  enabled: boolean
+  /** Selectors hidden on every page before capture (dates, ads, carousels). */
+  mask: string[]
+  /** Per path prefix: more selectors to hide, and a page's own limit. */
+  pages: Record<string, { mask?: string[]; maxDiffPercent?: number }>
+  fullPage: boolean
+  /** How different two pixels' colours must be to count (0–1, pixelmatch's threshold). */
+  threshold: number
+  /** A page's first capture becomes its baseline. */
+  autoBaseline: boolean
+  baselineDir?: string
+}
+
+export const DEFAULT_VISUAL: VisualConfig = { enabled: true, mask: [], pages: {}, fullPage: false, threshold: 0.1, autoBaseline: true }
+
+export function visualConfig(raw: unknown): VisualConfig {
+  const v = (raw && typeof raw === "object" ? raw : raw === false ? { enabled: false } : {}) as Record<string, any>
+  const pages: VisualConfig["pages"] = {}
+  for (const [k, p] of Object.entries((v.pages || {}) as Record<string, any>)) {
+    pages[k] = { ...(Array.isArray(p?.mask) ? { mask: p.mask.map(String) } : {}), ...(Number.isFinite(Number(p?.max_diff_percent)) && p?.max_diff_percent !== undefined ? { maxDiffPercent: Number(p.max_diff_percent) } : {}) }
+  }
+  return {
+    enabled: v.enabled !== false,
+    mask: Array.isArray(v.mask) ? v.mask.map(String) : [],
+    pages,
+    fullPage: v.full_page === true,
+    threshold: Number(v.threshold) > 0 && Number(v.threshold) < 1 ? Number(v.threshold) : 0.1,
+    autoBaseline: v.auto_baseline !== false,
+    ...(v.baseline_dir ? { baselineDir: String(v.baseline_dir) } : {}),
+  }
+}
+
+/** What the engine needs: masks by path prefix, and whether to capture the full page. */
+export function engineVisual(v: VisualConfig): { mask: string[]; pages: Record<string, string[]>; full_page: boolean } | undefined {
+  if (!v.enabled) return undefined
+  return { mask: v.mask, pages: Object.fromEntries(Object.entries(v.pages).filter(([, p]) => p.mask?.length).map(([k, p]) => [k, p.mask!])), full_page: v.fullPage }
+}
+
+export type Capture = { page: string; url: string; title?: string; file: string; full_page?: boolean }
+export type VisualStatus = "same" | "changed" | "new" | "no_baseline"
+export type VisualPage = {
+  page: string
+  url: string
+  title?: string
+  status: VisualStatus
+  /** Share of pixels that differ, in percent (two decimals). */
+  diffPercent?: number
+  diffPixels?: number
+  /** The run's capture, the baseline it was compared with, and the diff image (changed pixels in red). */
+  current: string
+  baseline?: string
+  diff?: string
+  size?: string
+  /** The page's limit from the budget, when one is set. */
+  limit?: number
+  over?: boolean
+  /** The sizes differ: a taller or wider page (counted as changed pixels). */
+  resized?: string
+}
+export type VisualReport = { baselineDir: string; pages: VisualPage[] }
+
+export const readCaptures = (runDir: string): Capture[] => {
+  try {
+    const v = JSON.parse(readFileSync(path.join(runDir, "visual.json"), "utf8"))
+    return Array.isArray(v) ? v : []
+  } catch {
+    return []
+  }
+}
+
+/** A page's baseline file: host/path, the image size, and the operating system. */
+export function baselineName(page: string, png: { width: number; height: number }, fullPage?: boolean): string {
+  let host = "page"
+  let p = page
+  try {
+    const u = new URL(page)
+    host = u.host.replace(/[^A-Za-z0-9.-]+/g, "_")
+    p = u.pathname
+  } catch {}
+  const slug = p.replace(/[^A-Za-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 80) || "home"
+  return path.join(host, `${slug}-${fullPage ? `${png.width}w-full` : `${png.width}x${png.height}`}-${process.platform}.png`)
+}
+
+function limitFor(v: VisualConfig, budget: number | undefined, url: string): number | undefined {
+  let p = url
+  try {
+    p = new URL(url).pathname
+  } catch {}
+  const match = Object.keys(v.pages)
+    .filter((k) => v.pages[k].maxDiffPercent !== undefined && (p === k || p.startsWith(k.endsWith("/") ? k : `${k}/`) || (k !== "/" && p.startsWith(k))))
+    .sort((a, b) => b.length - a.length)[0]
+  return match ? v.pages[match].maxDiffPercent : budget
+}
+
+const read = (file: string) => PNG.sync.read(readFileSync(file))
+
+/** Two images on one canvas of the larger size: pixels only one of them has count as changed. */
+export function diffImages(a: PNG, b: PNG, threshold: number): { pixels: number; total: number; diff: PNG } {
+  const width = Math.max(a.width, b.width)
+  const height = Math.max(a.height, b.height)
+  const pad = (img: PNG) => {
+    if (img.width === width && img.height === height) return img.data
+    const out = new PNG({ width, height })
+    PNG.bitblt(img, out, 0, 0, img.width, img.height, 0, 0)
+    return out.data
+  }
+  const diff = new PNG({ width, height })
+  const pixels = pixelmatch(pad(a), pad(b), diff.data, width, height, { threshold })
+  return { pixels, total: width * height, diff }
+}
+
+/** Compare each page the run captured with its baseline, write the diff images, and make baselines for new pages. */
+export function compareVisual(runDir: string, v: VisualConfig, baselineDir: string, budget?: number): VisualReport | null {
+  const captures = readCaptures(runDir)
+  if (!captures.length) return null
+  const pages: VisualPage[] = []
+  for (const c of captures) {
+    const current = path.join(runDir, c.file)
+    if (!existsSync(current)) continue
+    const img = read(current)
+    const name = baselineName(c.page, img, c.full_page)
+    const baseline = path.join(baselineDir, name)
+    const limit = limitFor(v, budget, c.url)
+    const base: VisualPage = { page: c.page, url: c.url, ...(c.title ? { title: c.title } : {}), status: "new", current, size: `${img.width}×${img.height}`, ...(limit !== undefined ? { limit } : {}) }
+    if (!existsSync(baseline)) {
+      if (v.autoBaseline) {
+        mkdirSync(path.dirname(baseline), { recursive: true })
+        copyFileSync(current, baseline)
+        recordApproval(baselineDir, name, c, path.basename(runDir), "first capture")
+        pages.push({ ...base, status: "new", baseline })
+      } else pages.push({ ...base, status: "no_baseline" })
+      continue
+    }
+    const old = read(baseline)
+    const { pixels, total, diff } = diffImages(old, img, v.threshold)
+    const percent = Math.round((pixels / total) * 10000) / 100
+    const resized = old.width !== img.width || old.height !== img.height ? `${old.width}×${old.height} → ${img.width}×${img.height}` : undefined
+    let diffFile: string | undefined
+    if (pixels) {
+      diffFile = current.replace(/\.png$/, "-diff.png")
+      writeFileSync(diffFile, PNG.sync.write(diff))
+    }
+    pages.push({ ...base, status: pixels ? "changed" : "same", diffPercent: percent, diffPixels: pixels, baseline, ...(diffFile ? { diff: diffFile } : {}), ...(resized ? { resized } : {}), ...(limit !== undefined ? { over: percent > limit } : {}) })
+  }
+  const report = { baselineDir, pages }
+  writeFileSync(path.join(runDir, "visual-result.json"), `${JSON.stringify(report, null, 2)}\n`)
+  return report
+}
+
+type Approval = { file: string; page: string; run: string; at: string; why: string }
+
+function recordApproval(baselineDir: string, name: string, c: Pick<Capture, "page">, run: string, why: string): void {
+  const index = path.join(baselineDir, "baselines.json")
+  let data: Record<string, Approval> = {}
+  try {
+    data = JSON.parse(readFileSync(index, "utf8"))
+  } catch {}
+  data[name.split(path.sep).join("/")] = { file: name.split(path.sep).join("/"), page: c.page, run, at: new Date().toISOString(), why }
+  mkdirSync(baselineDir, { recursive: true })
+  writeFileSync(index, `${JSON.stringify(Object.fromEntries(Object.entries(data).sort(([a], [b]) => a.localeCompare(b))), null, 2)}\n`)
+}
+
+/** Make a run's captures the baselines: every page, or the pages whose URL contains one of `only`. */
+export function approveVisual(runDir: string, baselineDir: string, only: string[] = [], why = "approved"): { page: string; baseline: string }[] {
+  const out: { page: string; baseline: string }[] = []
+  const filter = only.map((o) => o.toLowerCase())
+  for (const c of readCaptures(runDir)) {
+    if (filter.length && !filter.some((f) => c.page.toLowerCase().includes(f) || c.url.toLowerCase().includes(f))) continue
+    const current = path.join(runDir, c.file)
+    if (!existsSync(current)) continue
+    const name = baselineName(c.page, read(current), c.full_page)
+    const target = path.join(baselineDir, name)
+    mkdirSync(path.dirname(target), { recursive: true })
+    copyFileSync(current, target)
+    recordApproval(baselineDir, name, c, path.basename(runDir), why)
+    out.push({ page: c.page, baseline: target })
+  }
+  return out
+}
+
+export function visualLine(r: VisualReport): string {
+  const n = (s: VisualStatus) => r.pages.filter((p) => p.status === s).length
+  const changed = r.pages.filter((p) => p.status === "changed")
+  const most = changed.sort((a, b) => (b.diffPercent || 0) - (a.diffPercent || 0))[0]
+  return [`${n("same")} same`, changed.length ? `${changed.length} changed${most ? ` (up to ${most.diffPercent}%)` : ""}` : "", n("new") ? `${n("new")} new baseline${n("new") === 1 ? "" : "s"}` : "", n("no_baseline") ? `${n("no_baseline")} without a baseline` : ""].filter(Boolean).join(", ")
+}