frontend-go-live-check 1.2.0 → 1.4.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 1.4.0
+
+- New layout checks on every page at every screen size, each with Actual and Expected pictures where possible:
+  - text that spills out of its box (for example a button with a fixed size that is too small for its label);
+  - text drawn on top of other text;
+  - content cut off at the edge of the screen where the user cannot scroll to it.
+- New content checks:
+  - buttons and links covered by another element;
+  - unfinished text: `undefined`, `NaN`, `null`, `[object Object]`, `Invalid Date`, `{{ }}`, translation keys, lorem ipsum, TODO;
+  - stretched or squashed images;
+  - loading indicators still showing after the page finished loading.
+- Evidence outlines now include text that runs outside its element.
+
+## 1.3.0
+
+- Every problem is shown as **Actual** next to **Expected**: a close-up of the problem outlined in red, and the same spot corrected (focus ring, contrast, text that fits, page that fits the screen, right-to-left…) outlined in green. Problems without a picture get one Expected sentence.
+- Plain-language explanations for every problem: what is wrong, who it affects, where (element name and CSS selector), how to see it yourself, and the standard behind it (WCAG, OWASP, OAuth).
+- The same layout in the HTML report, the PDF and the Word file.
+
 ## 1.1.0
 
 - **Sign-in with Google, Microsoft, Apple, UAE PASS and any OpenID Connect server.**

package/README.md

@@ -54,7 +54,7 @@ Have an API? Save your Postman collection as **`api/postman_collection.json`** (
 | --- | --- |
 | "Looks fine on my screen" | Every page at phone, tablet and desktop size, in a real browser |
 | Accessibility, security and speed are checked by different people, if at all | One run, one report, one verdict: **READY**, **NEEDS ATTENTION** or **NOT READY** |
-| Bugs reported as "the page is broken" | A picture of the problem outlined in red, the CSS selector, steps to see it, and how to fix it |
+| Bugs reported as "the page is broken" | Actual and Expected pictures side by side, the element and its CSS selector, and steps to see it |
 | Writing and maintaining end-to-end tests for every page | Nothing to write: pages are found by following links, your routes and your sitemap |
 | Releases go out on hope | A pipeline step that **blocks the merge** when there are blocking problems |
 
@@ -142,9 +142,9 @@ The report lists every sign-in method found (*email and password · Google · UA
 
 | | Area | What is checked |
 | :-: | --- | --- |
-| 🧭 | **Functionality** | JavaScript errors, console errors, failed requests, broken links, images and anchors, blank pages, the production build, the "page not found" page |
+| 🧭 | **Functionality** | JavaScript errors, console errors, failed requests, broken links, images and anchors, blank pages, buttons covered by something else, unfinished text (`undefined`, `NaN`, `[object Object]`, translation keys, lorem ipsum, TODO), loading spinners that never stop, the production build, the "page not found" page |
 | 🛟 | **Resilience** | Each page opened again with its API calls failing: does it crash, go blank, or tell the user? |
-| 📱 | **Design and responsive layout** | Every page at every screen size: sideways scrolling, cut-off or overlapping text and buttons, tiny text on phones, right-to-left layout (Arabic, Hebrew…), fonts that fail to load, too many fonts and sizes |
+| 📱 | **Design and responsive layout** | Every page at every screen size: sideways scrolling, text that spills out of its box (a button too small for its label), text on top of other text, content cut off at the screen edge, text cut off inside its box, overlapping buttons, stretched or squashed images, tiny text on phones, right-to-left layout (Arabic, Hebrew…), fonts that fail to load, too many fonts and sizes |
 | 🖼️ | **Visual changes** | A pixel comparison of every page with the saved baseline, with the changed areas in red |
 | ♿ | **Accessibility** | axe-core against WCAG 2.0 / 2.1 / 2.2 A and AA; keyboard-only use: visible focus, no traps, nothing that only a mouse can click; form field types |
 | ⚡ | **Performance** | Size, JavaScript, requests, load time, LCP, layout shift and frozen-page time for every page, against budgets; Lighthouse as a phone and as a desktop |
@@ -199,12 +199,17 @@ The report has:
 - the API results, the speed of every page, and the load test;
 - screenshots of every page at every size.
 
-### Every problem comes with evidence
+### Every problem: Actual next to Expected
 
-The page is shown at the screen size where the problem happens, with the problem **outlined in red**. Each problem also lists the element's CSS selector, the steps to see it, and how to fix it.
+Each problem is shown so a developer understands it at a glance, without knowing the rule behind it:
+
+- **one sentence** on what is wrong, in plain words;
+- **Actual**: a close-up of the page as it is now, with the problem outlined in red, at the screen size where it happens;
+- **Expected**: the same spot as it should be, outlined in green. For visual problems the tool corrects the page in the browser for this one picture: a visible focus ring, readable contrast, text that fits, a page that fits the screen, right-to-left layout. Other problems (APIs, security, sign-in) get one sentence saying what is expected;
+- **where** (page, screen size, the element by name and CSS selector), **who it affects**, and **how to see it yourself**.
 
 <p align="center">
-  <img src="https://unpkg.com/frontend-go-live-check@1/docs/finding.png" alt="A finding with its evidence picture: the clickable box is outlined in red" width="820">
+  <img src="https://unpkg.com/frontend-go-live-check@1/docs/finding.png" alt="A problem card: Actual (focus not visible, outlined in red) next to Expected (a clear focus ring, outlined in green)" width="860">
 </p>
 
 ### Share it as PDF or Word
@@ -222,7 +227,7 @@ Both documents follow a standard test-report layout:
 - contents;
 - an executive summary;
 - results by area;
-- every finding with an ID, its evidence and how to fix it;
+- every finding with an ID, Actual and Expected pictures, where it is and how to see it;
 - problems per page;
 - a fix checklist;
 - appendices with screenshots.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "frontend-go-live-check",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "Is your frontend ready to go live? One command tests any web frontend (React, Next.js, Vue, Angular, Svelte, plain HTML…): pages, responsive design, accessibility, keyboard, performance and load, API calls, security, SEO, sign-in and APIs from Postman/OpenAPI. Report with evidence, PDF and Word, and a pipeline gate that approves or rejects the merge.",
   "homepage": "https://www.npmjs.com/package/frontend-go-live-check",
   "repository": {

package/src/checks/browser.mjs

@@ -11,7 +11,7 @@ import { normaliseLogin, signIn } from '../core/login.mjs';
 import { inPageAudit } from './in-page.mjs';
 import { keyboardAudit } from './keyboard.mjs';
 import { compareWithBaseline } from './visual.mjs';
-import { captureEvidence, capturePage } from './evidence.mjs';
+import { captureEvidence, captureExpected, capturePage } from './evidence.mjs';
 import { rule } from '../core/rules.mjs';
 
 export { signIn };
@@ -283,8 +283,17 @@ export async function runBrowserChecks({ base, config, reportDir, log, starts =
             const key = `${finding.ruleId}|${finding.page}|${finding.detail ?? ''}|${(finding.items ?? []).join('|')}`;
             if (config.evidence !== false && !evidenceTaken.has(key)) {
               evidenceTaken.add(key);
-              finding.evidence = selectors === 'page' ? await capturePage(page, reportDir) : await captureEvidence(page, reportDir, { selectors, label: `${rule(finding.ruleId).title} · ${tag}`, ...options });
+              const shot = selectors === 'page' ? await capturePage(page, reportDir) : await captureEvidence(page, reportDir, { selectors, label: `${rule(finding.ruleId).title} · ${tag}`, ...options });
+              finding.evidence = typeof shot === 'string' ? shot : shot?.file ?? '';
+              if (shot?.zoom) finding.evidenceZoom = shot.zoom;
               if (finding.evidence) finding.evidenceView = tag;
+              // The same spot as it should look (corrected for this one picture).
+              const kind = finding.ruleId.startsWith('a11y-') ? String(finding.detail ?? '').split(':')[0].trim() : finding.ruleId;
+              const expected = await captureExpected(page, reportDir, finding.evidence, { kind, selectors: Array.isArray(selectors) ? selectors : [], label: `Expected · ${tag}`, screenEdge: options.screenEdge ?? 0 }).catch(() => null);
+              if (expected?.file) {
+                finding.expected = expected.file;
+                if (expected.zoom) finding.expectedZoom = expected.zoom;
+              }
             }
             add(finding);
           };
@@ -292,6 +301,18 @@ export async function runBrowserChecks({ base, config, reportDir, log, starts =
           if (!audit.viewportMeta) add({ ruleId: 'missing-viewport-meta', page: landedKey, view: tag });
           if (audit.overflow.length) await withEvidence({ ruleId: 'horizontal-overflow', page: landedKey, view: tag, detail: `The page is ${audit.docWidth}px wide on a ${audit.width}px screen.`, items: audit.overflow, selectors: audit.targets.overflow }, audit.targets.overflow, { screenEdge: audit.width });
           if (audit.clipped.length) await withEvidence({ ruleId: 'clipped-text', page: landedKey, view: tag, items: audit.clipped, selectors: audit.targets.clipped }, audit.targets.clipped);
+          if (audit.outside.length) await withEvidence({ ruleId: 'text-outside-box', page: landedKey, view: tag, items: audit.outside, selectors: audit.targets.outside }, audit.targets.outside);
+          if (audit.textOverlaps.length) await withEvidence({ ruleId: 'text-overlap', page: landedKey, view: tag, items: audit.textOverlaps, selectors: audit.targets.textOverlaps }, audit.targets.textOverlaps);
+          if (audit.cutOff.length) await withEvidence({ ruleId: 'cut-off-at-edge', page: landedKey, view: tag, items: audit.cutOff, selectors: audit.targets.cutOff }, audit.targets.cutOff);
+          if (audit.covered.length) await withEvidence({ ruleId: 'control-covered', page: landedKey, view: tag, items: audit.covered, selectors: audit.targets.covered }, audit.targets.covered);
+          if (audit.placeholders.length) await withEvidence({ ruleId: 'placeholder-text', page: landedKey, view: tag, items: audit.placeholders, selectors: audit.targets.placeholders }, audit.targets.placeholders);
+          if (audit.distorted.length) await withEvidence({ ruleId: 'distorted-image', page: landedKey, view: tag, items: audit.distorted, selectors: audit.targets.distorted }, audit.targets.distorted);
+          if (audit.loading.length) {
+            // Give slow data a little more time before calling it stuck.
+            await page.waitForTimeout(4000);
+            const again = await page.evaluate(inPageAudit, [Boolean(vp.isMobile) && vp.viewport.width < 600, vp.viewport.width]).catch(() => null);
+            if (again?.loading.length) await withEvidence({ ruleId: 'stuck-loading', page: landedKey, view: tag, items: again.loading, selectors: again.targets.loading }, again.targets.loading);
+          }
           if (audit.overlaps.length) await withEvidence({ ruleId: 'overlapping-elements', page: landedKey, view: tag, items: audit.overlaps, selectors: audit.targets.overlaps }, audit.targets.overlaps);
           if (audit.small.length) await withEvidence({ ruleId: 'small-text', page: landedKey, view: tag, items: audit.small, selectors: audit.targets.small }, audit.targets.small);
           for (const [i, src] of audit.brokenImages.entries()) await withEvidence({ ruleId: 'broken-image', page: landedKey, view: tag, detail: src, selectors: [audit.targets.brokenImages[i]] }, [audit.targets.brokenImages[i]]);

package/src/checks/evidence.mjs

@@ -7,7 +7,7 @@ import { mkdirSync } from 'node:fs';
 import { join } from 'node:path';
 
 /** Runs in the page: draws the outlines. Returns how many elements were found. */
-function drawOutlines([selectors, label, screenEdge]) {
+function drawOutlines([selectors, label, screenEdge, colour = '#e01e1e']) {
   document.getElementById('__glc_evidence')?.remove();
   const layer = document.createElement('div');
   layer.id = '__glc_evidence';
@@ -23,34 +23,52 @@ function drawOutlines([selectors, label, screenEdge]) {
     }
     if (el && !found.includes(el)) found.push(el);
   }
+  // The element's box plus wherever its content is drawn (text can run outside the box).
+  const extent = (el) => {
+    const b = el.getBoundingClientRect();
+    const range = document.createRange();
+    range.selectNodeContents(el);
+    const c = range.getBoundingClientRect();
+    if (!c.width || !c.height) return b;
+    const left = Math.min(b.left, c.left);
+    const top = Math.min(b.top, c.top);
+    const right = Math.max(b.right, c.right);
+    const bottom = Math.max(b.bottom, c.bottom);
+    return { left, top, right, bottom, width: right - left, height: bottom - top };
+  };
   found.forEach((el, i) => {
-    const r = el.getBoundingClientRect();
+    const r = extent(el);
     const box = document.createElement('div');
-    box.style.cssText = `position:absolute;left:${r.left + scrollX - 3}px;top:${r.top + scrollY - 3}px;width:${Math.max(r.width, 4) + 6}px;height:${Math.max(r.height, 4) + 6}px;border:3px solid #e01e1e;border-radius:4px;box-shadow:0 0 0 2px rgba(255,255,255,.9),0 0 0 9999px rgba(0,0,0,.08);box-sizing:border-box`;
+    box.style.cssText = `position:absolute;left:${r.left + scrollX - 3}px;top:${r.top + scrollY - 3}px;width:${Math.max(r.width, 4) + 6}px;height:${Math.max(r.height, 4) + 6}px;border:3px solid ${colour};border-radius:4px;box-shadow:0 0 0 2px rgba(255,255,255,.9),0 0 0 9999px rgba(0,0,0,.08);box-sizing:border-box`;
     const tag = document.createElement('div');
-    tag.textContent = found.length > 1 ? String(i + 1) : '!';
-    tag.style.cssText = `position:absolute;left:-3px;top:${r.top + scrollY < 26 ? 'calc(100% + 2px)' : '-24px'};background:#e01e1e;color:#fff;font:700 13px/20px system-ui,sans-serif;padding:0 7px;border-radius:4px`;
+    tag.textContent = colour === '#e01e1e' ? (found.length > 1 ? String(i + 1) : '!') : '✓';
+    tag.style.cssText = `position:absolute;left:-3px;top:${r.top + scrollY < 26 ? 'calc(100% + 2px)' : '-24px'};background:${colour};color:#fff;font:700 13px/20px system-ui,sans-serif;padding:0 7px;border-radius:4px`;
     box.appendChild(tag);
     layer.appendChild(box);
   });
   if (screenEdge) {
     const edge = document.createElement('div');
-    edge.style.cssText = `position:absolute;left:${screenEdge}px;top:0;width:0;height:${document.documentElement.scrollHeight}px;border-left:3px dashed #e01e1e`;
+    edge.style.cssText = `position:absolute;left:${screenEdge}px;top:0;width:0;height:${document.documentElement.scrollHeight}px;border-left:3px dashed ${colour}`;
     const text = document.createElement('div');
     text.textContent = 'screen edge';
-    text.style.cssText = 'position:absolute;left:6px;top:8px;background:#e01e1e;color:#fff;font:700 12px/18px system-ui,sans-serif;padding:0 6px;border-radius:4px;white-space:nowrap';
+    text.style.cssText = `position:absolute;left:6px;top:8px;background:${colour};color:#fff;font:700 12px/18px system-ui,sans-serif;padding:0 6px;border-radius:4px;white-space:nowrap`;
     edge.appendChild(text);
     layer.appendChild(edge);
   }
   if (label) {
     const caption = document.createElement('div');
     caption.textContent = label;
-    caption.style.cssText = `position:fixed;left:8px;bottom:8px;max-width:calc(100% - 16px);background:#e01e1e;color:#fff;font:600 13px/1.35 system-ui,sans-serif;padding:6px 10px;border-radius:6px;box-shadow:0 2px 6px rgba(0,0,0,.3)`;
+    caption.style.cssText = `position:fixed;left:8px;bottom:8px;max-width:calc(100% - 16px);background:${colour};color:#fff;font:600 13px/1.35 system-ui,sans-serif;padding:6px 10px;border-radius:6px;box-shadow:0 2px 6px rgba(0,0,0,.3)`;
     layer.appendChild(caption);
   }
   // Show the first problem element in the middle of the screen.
   if (found[0] && !screenEdge) found[0].scrollIntoView({ block: 'center', inline: 'nearest' });
-  return found.length;
+  // Where the outlined elements are on screen now (for the close-up picture).
+  const rects = found.map(extent);
+  const box = rects.length
+    ? { left: Math.min(...rects.map((r) => r.left)), top: Math.min(...rects.map((r) => r.top)), right: Math.max(...rects.map((r) => r.right)), bottom: Math.max(...rects.map((r) => r.bottom)) }
+    : null;
+  return { count: found.length, box };
 }
 
 let counter = 0;
@@ -59,24 +77,144 @@ let counter = 0;
  * Takes the evidence picture for one finding. Returns the report-relative path, or '' when the
  * elements could not be found again.
  */
-export async function captureEvidence(page, reportDir, { selectors = [], label = '', screenEdge = 0, limit = 80 }) {
-  if (counter >= limit) return '';
+export async function captureEvidence(page, reportDir, { selectors = [], label = '', screenEdge = 0, limit = 80, colour = '#e01e1e', file: fixedFile = '' }) {
+  if (!fixedFile && counter >= limit) return '';
   const dir = join(reportDir, 'evidence');
   mkdirSync(dir, { recursive: true });
-  const found = await page.evaluate(drawOutlines, [selectors.slice(0, 6), label, screenEdge]).catch(() => 0);
+  const drawn = await page.evaluate(drawOutlines, [selectors.slice(0, 6), label, screenEdge, colour]).catch(() => ({ count: 0, box: null }));
+  const found = drawn.count;
   if (!found && !screenEdge && selectors.length) {
     await page.evaluate(() => document.getElementById('__glc_evidence')?.remove()).catch(() => {});
     return '';
   }
-  counter += 1;
-  const file = `evidence/${String(counter).padStart(3, '0')}.jpg`;
+  if (!fixedFile) counter += 1;
+  const file = fixedFile || `evidence/${String(counter).padStart(3, '0')}.jpg`;
   await page.waitForTimeout(80);
   const ok = await page.screenshot({ path: join(reportDir, file), type: 'jpeg', quality: 72, animations: 'disabled', fullPage: Boolean(screenEdge) }).then(() => true).catch(() => false);
+  // A close-up around the problem, so small elements (a menu link, an icon) can be seen clearly.
+  let zoom = '';
+  const vp = page.viewportSize();
+  if (ok && drawn.box && !screenEdge && vp) {
+    const b = drawn.box;
+    const width = Math.min(vp.width, Math.max(520, b.right - b.left + 160));
+    const height = Math.min(vp.height, Math.max(260, b.bottom - b.top + 120));
+    const x = Math.max(0, Math.min(vp.width - width, (b.left + b.right) / 2 - width / 2));
+    const y = Math.max(0, Math.min(vp.height - height, (b.top + b.bottom) / 2 - height / 2));
+    if (width < vp.width * 0.85 || height < vp.height * 0.85) {
+      zoom = file.replace(/\.jpg$/, '-zoom.jpg');
+      await page.screenshot({ path: join(reportDir, zoom), type: 'jpeg', quality: 80, clip: { x, y, width, height } }).catch(() => {
+        zoom = '';
+      });
+    }
+  }
   await page.evaluate(() => {
     document.getElementById('__glc_evidence')?.remove();
     scrollTo(0, 0);
   }).catch(() => {});
-  return ok ? file : '';
+  return ok ? { file, zoom } : '';
+}
+
+/**
+ * The "Expected" picture: the same spot with the problem corrected in the browser for this one
+ * picture (outlined in green), then the page is put back exactly as it was.
+ * Only for problems a picture can show; others get the Expected sentence only.
+ */
+export const EXPECTED_VISUAL = new Set(['horizontal-overflow', 'clipped-text', 'text-outside-box', 'cut-off-at-edge', 'small-text', 'focus-not-visible', 'mouse-only-control', 'rtl-missing', 'color-contrast', 'target-size']);
+
+/** Runs in the page: corrects the problem on these elements; remembers how to undo it. */
+function applyExpected([kind, selectors]) {
+  const undo = [];
+  const set = (el, prop, value) => {
+    undo.push([el, prop, el.style.getPropertyValue(prop), el.style.getPropertyPriority(prop)]);
+    el.style.setProperty(prop, value, 'important');
+  };
+  const els = selectors.map((sel) => {
+    try {
+      return document.querySelector(sel);
+    } catch {
+      return null;
+    }
+  }).filter(Boolean);
+  const luminance = (rgb) => {
+    const [r, g, b] = (rgb.match(/[\d.]+/g) ?? [255, 255, 255]).slice(0, 3).map(Number).map((v) => {
+      const c = v / 255;
+      return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+    });
+    return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+  };
+  const background = (el) => {
+    for (let n = el; n; n = n.parentElement) {
+      const bg = getComputedStyle(n).backgroundColor;
+      if (bg && !/rgba\(0, 0, 0, 0\)|transparent/.test(bg)) return bg;
+    }
+    return 'rgb(255, 255, 255)';
+  };
+  if (kind === 'rtl-missing') {
+    const html = document.documentElement;
+    const before = html.getAttribute('dir');
+    html.setAttribute('dir', 'rtl');
+    window.__glcUndo = () => (before === null ? html.removeAttribute('dir') : html.setAttribute('dir', before));
+    return true;
+  }
+  for (const el of els) {
+    if (kind === 'horizontal-overflow') {
+      set(el, 'max-width', '100%');
+      set(el, 'box-sizing', 'border-box');
+      set(el, 'overflow-x', 'auto');
+      if (el.tagName === 'TABLE' || el.tagName === 'PRE') set(el, 'display', 'block');
+      for (const img of el.querySelectorAll('img, video, iframe')) set(img, 'max-width', '100%');
+    } else if (kind === 'clipped-text') {
+      set(el, 'overflow', 'visible');
+      set(el, 'height', 'auto');
+      set(el, 'max-height', 'none');
+      set(el, 'white-space', 'normal');
+    } else if (kind === 'text-outside-box') {
+      for (const prop of ['width', 'height']) set(el, prop, 'auto');
+      set(el, 'max-width', '100%');
+      set(el, 'white-space', 'normal');
+      set(el, 'overflow-wrap', 'anywhere');
+      if (getComputedStyle(el).display === 'inline') set(el, 'display', 'inline-block');
+    } else if (kind === 'cut-off-at-edge') {
+      for (const prop of ['left', 'right', 'margin-left', 'margin-right', 'text-indent', 'transform']) if (getComputedStyle(el)[prop.replace(/-(.)/g, (_, c) => c.toUpperCase())] !== 'auto') set(el, prop, prop === 'transform' ? 'none' : prop === 'left' || prop === 'right' ? 'auto' : '0');
+      set(el, 'max-width', '100%');
+      set(el, 'overflow-wrap', 'anywhere');
+      set(el, 'white-space', 'normal');
+    } else if (kind === 'small-text') {
+      set(el, 'font-size', '14px');
+    } else if (kind === 'color-contrast') {
+      set(el, 'color', luminance(background(el)) > 0.4 ? '#1b1f24' : '#ffffff');
+    } else if (kind === 'target-size') {
+      set(el, 'min-width', '24px');
+      set(el, 'min-height', '24px');
+      set(el, 'display', 'inline-block');
+    } else if (kind === 'focus-not-visible' || kind === 'mouse-only-control') {
+      set(el, 'outline', '3px solid #1f4fbf');
+      set(el, 'outline-offset', '2px');
+    }
+  }
+  if ((kind === 'focus-not-visible' || kind === 'mouse-only-control') && els[0]) els[0].focus?.({ preventScroll: true });
+  window.__glcUndo = () => {
+    for (const [el, prop, value, priority] of undo.reverse()) {
+      if (value) el.style.setProperty(prop, value, priority);
+      else el.style.removeProperty(prop);
+    }
+  };
+  return els.length > 0;
+}
+
+export async function captureExpected(page, reportDir, actualFile, { kind, selectors = [], label = '', screenEdge = 0 }) {
+  if (!actualFile || !EXPECTED_VISUAL.has(kind)) return null;
+  const applied = await page.evaluate(applyExpected, [kind, selectors.slice(0, 6)]).catch(() => false);
+  if (!applied) return null;
+  await page.waitForTimeout(120);
+  const file = actualFile.replace(/\.jpg$/, '-expected.jpg');
+  const shot = await captureEvidence(page, reportDir, { selectors: kind === 'rtl-missing' ? [] : selectors, label, screenEdge: kind === 'horizontal-overflow' ? screenEdge : 0, colour: '#16a34a', file });
+  await page.evaluate(() => {
+    window.__glcUndo?.();
+    delete window.__glcUndo;
+    document.activeElement?.blur?.();
+  }).catch(() => {});
+  return shot || null;
 }
 
 /** A plain picture of the page as it is now (no outlines), e.g. a page that crashed. */

package/src/checks/in-page.mjs

@@ -73,6 +73,178 @@ export function inPageAudit([phone, screenWidth]) {
     if (el.scrollWidth > el.clientWidth + 2 || el.scrollHeight > el.clientHeight + 2) { clipped.push(describe(el)); targets.clipped.push(cssPath(el)); }
   }
 
+  // Where an element's own text is drawn (it can be outside the element's box).
+  const range = document.createRange();
+  const textRect = (el, lines = []) => {
+    let box = null;
+    for (const n of el.childNodes) {
+      if (n.nodeType !== 3 || !n.textContent.trim()) continue;
+      range.selectNodeContents(n);
+      for (const r of range.getClientRects()) {
+        if (r.width < 1 || r.height < 1) continue;
+        if (lines.length < 20) lines.push({ left: r.left, top: r.top, right: r.right, bottom: r.bottom });
+        box = box ? { left: Math.min(box.left, r.left), top: Math.min(box.top, r.top), right: Math.max(box.right, r.right), bottom: Math.max(box.bottom, r.bottom) } : { left: r.left, top: r.top, right: r.right, bottom: r.bottom };
+      }
+    }
+    return box;
+  };
+  const transparent = (c) => !c || c === 'transparent' || /rgba\([^)]*,\s*0\)$/.test(c);
+  const srOnly = (el, cs, r) => r.width <= 2 || r.height <= 2 || (cs.clip && cs.clip !== 'auto') || (cs.clipPath && cs.clipPath !== 'none');
+  const inDialog = (el) => Boolean(el.closest('dialog, [role=dialog], [role=alertdialog], [aria-modal=true], [aria-hidden=true]'));
+  const texts = [];
+  for (const el of all) {
+    if (texts.length >= 600) break;
+    if (!visible(el) || !el.childNodes.length || inDialog(el)) continue;
+    const cs = getComputedStyle(el);
+    const r = el.getBoundingClientRect();
+    if (srOnly(el, cs, r) || transparent(cs.color)) continue;
+    const lines = [];
+    const t = textRect(el, lines);
+    if (t) texts.push({ el, cs, r, t, lines });
+  }
+
+  // Text that spills out of a box with a visible shape (a button, a badge, a card): the box is
+  // too small for its text, and the text runs over whatever is next to it.
+  const outside = [];
+  targets.outside = [];
+  for (const { el, cs, r, t } of texts) {
+    if (outside.length >= 5) break;
+    if (el === document.body || el === document.documentElement) continue;
+    if (/(hidden|clip)/.test(`${cs.overflowX} ${cs.overflowY}`)) continue; // that is clipped-text
+    const shaped = !transparent(cs.backgroundColor) || parseFloat(cs.borderLeftWidth) + parseFloat(cs.borderRightWidth) + parseFloat(cs.borderTopWidth) + parseFloat(cs.borderBottomWidth) > 0 || el.matches('button, [role=button], input, select, textarea');
+    if (!shaped) continue;
+    const slackY = Math.max(4, parseFloat(cs.fontSize) * 0.3);
+    const past = { right: t.right - r.right, left: r.left - t.left, bottom: t.bottom - r.bottom - slackY, top: r.top - t.top - slackY };
+    const worst = Object.entries(past).sort((a, b) => b[1] - a[1])[0];
+    if (worst[1] > 3) {
+      outside.push(`${describe(el)}: the text goes ${Math.round(worst[1] + (worst[0] === 'top' || worst[0] === 'bottom' ? slackY : 0))}px past the ${worst[0]} edge of its ${Math.round(r.width)} × ${Math.round(r.height)}px box`);
+      targets.outside.push(cssPath(el));
+    }
+  }
+
+  // Text drawn on top of other text (absolute positioning, negative margins, text spilling out).
+  const textOverlaps = [];
+  targets.textOverlaps = [];
+  const hit = (p, q) => {
+    const w = Math.min(p.right, q.right) - Math.max(p.left, q.left);
+    const h = Math.min(p.bottom, q.bottom) - Math.max(p.top, q.top);
+    if (w < 4 || h < 4) return null;
+    const smaller = Math.min((p.right - p.left) * (p.bottom - p.top), (q.right - q.left) * (q.bottom - q.top));
+    if (w * h < 0.15 * smaller) return null;
+    return { x: (Math.max(p.left, q.left) + Math.min(p.right, q.right)) / 2, y: (Math.max(p.top, q.top) + Math.min(p.bottom, q.bottom)) / 2 };
+  };
+  const reported = new Set();
+  for (let i = 0; i < texts.length && textOverlaps.length < 5; i++) {
+    const a = texts[i];
+    for (let j = i + 1; j < texts.length; j++) {
+      const b = texts[j];
+      if (!hit(a.t, b.t) || reported.has(b.el)) continue;
+      let point = null;
+      for (const p of a.lines) {
+        for (const q of b.lines) if ((point = hit(p, q))) break;
+        if (point) break;
+      }
+      if (!point) continue;
+      // Only when both texts can really be seen there (not one hidden behind a solid layer).
+      const top = document.elementFromPoint(point.x, point.y);
+      if (top && !(a.el.contains(top) || b.el.contains(top) || top.contains(a.el) || top.contains(b.el))) continue;
+      reported.add(a.el);
+      reported.add(b.el);
+      textOverlaps.push(`${describe(a.el).replace(/ ".*/, '')} "${[...a.el.childNodes].filter((n) => n.nodeType === 3).map((n) => n.textContent).join(' ').replace(/\s+/g, ' ').trim().slice(0, 30)}" and ${describe(b.el)}`);
+      targets.textOverlaps.push(cssPath(a.el), cssPath(b.el));
+      break;
+    }
+  }
+
+  // Content cut off at the edge of the screen where the user cannot scroll to it (pushed off to
+  // the left, or past the right edge when the page hides sideways scrolling).
+  const cutOff = [];
+  targets.cutOff = [];
+  for (const { el, t } of texts) {
+    if (cutOff.length >= 5) break;
+    if (insideFixedOrScroller(el) || overflow.some((o) => o.el.contains(el))) continue;
+    const left = t.left < -2 && t.right > 0;
+    const right = t.right > width + 2 && t.left < width && docWidth <= width + 1;
+    if (!left && !right) continue;
+    if (cutOff.length && targets.cutOff.some((sel) => document.querySelector(sel)?.contains(el))) continue;
+    cutOff.push(`${describe(el)}: ${left ? `starts ${Math.round(-t.left)}px before the left edge` : `goes ${Math.round(t.right - width)}px past the right edge`} of the screen`);
+    targets.cutOff.push(cssPath(el));
+  }
+
+  // Buttons and links covered by something else, so a click lands on the wrong thing.
+  const covered = [];
+  targets.covered = [];
+  for (const el of document.querySelectorAll('a[href], button, input:not([type=hidden]), select, textarea, [role=button]')) {
+    if (covered.length >= 5) break;
+    if (!visible(el) || inDialog(el) || el.disabled) continue;
+    const r = el.getBoundingClientRect();
+    if (r.width < 8 || r.height < 8 || r.top < 0 || r.left < 0 || r.bottom > innerHeight || r.right > innerWidth) continue;
+    const top = document.elementFromPoint(r.left + r.width / 2, r.top + r.height / 2);
+    if (!top || el.contains(top) || top.contains(el)) continue;
+    const label = top.closest('label');
+    if (label && (label.control === el || label.contains(el))) continue;
+    if (top.closest('dialog, [role=dialog], [role=alertdialog], [aria-modal=true]') || /cookie|consent|gdpr/i.test(`${top.closest('[id],[class]')?.id ?? ''} ${top.closest('[class]')?.className ?? ''}`)) continue;
+    covered.push(`${describe(el)} is under ${describe(top)}`);
+    targets.covered.push(cssPath(el), cssPath(top));
+  }
+
+  // Text that was never filled in: undefined, NaN, [object Object], template braces, lorem ipsum,
+  // TODO, translation keys shown instead of the translation.
+  const placeholders = [];
+  targets.placeholders = [];
+  const leftover = [
+    [/\bundefined\b/, 'undefined'], [/\bNaN\b/, 'NaN'], [/\[object Object\]/, '[object Object]'], [/Invalid Date/, 'Invalid Date'],
+    [/(^null$|:\s*null\b)/, 'null'], [/\{\{[^}]*\}\}|\$\{[^}]*\}/, 'template braces'], [/lorem ipsum/i, 'lorem ipsum'], [/\b(TODO|FIXME|TBD)\b/, 'TODO'],
+  ];
+  const key = /^[a-z][a-zA-Z0-9]*(\.[a-z][a-zA-Z0-9_]*){2,}$|^[a-z][a-zA-Z0-9]*\.[a-z]+[A-Z][a-zA-Z0-9]*$|^[A-Z][A-Z0-9]*(_[A-Z0-9]+){2,}$/;
+  const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT);
+  for (let n = walker.nextNode(); n && placeholders.length < 5; n = walker.nextNode()) {
+    const text = n.textContent.replace(/\s+/g, ' ').trim();
+    const el = n.parentElement;
+    if (!text || !el || el.closest('script, style, noscript, template, code, pre, samp, kbd, textarea, [contenteditable]') || !visible(el)) continue;
+    const found = leftover.find(([re]) => re.test(text))?.[1] ?? (key.test(text) ? 'translation key' : '');
+    if (!found || targets.placeholders.includes(cssPath(el))) continue;
+    placeholders.push(`${describe(el)} shows "${text.slice(0, 60)}" (${found})`);
+    targets.placeholders.push(cssPath(el));
+  }
+  for (const input of document.querySelectorAll('input[placeholder], input[value]')) {
+    if (placeholders.length >= 5 || !visible(input)) continue;
+    const text = `${input.value} ${input.placeholder}`;
+    const found = leftover.slice(0, 6).find(([re]) => re.test(text))?.[1];
+    if (found) {
+      placeholders.push(`${describe(input)} shows "${text.trim().slice(0, 60)}" (${found})`);
+      targets.placeholders.push(cssPath(input));
+    }
+  }
+
+  // Images stretched or squashed (shown at a different shape than the picture).
+  const distorted = [];
+  targets.distorted = [];
+  for (const img of document.images) {
+    if (distorted.length >= 5 || !visible(img) || !img.naturalWidth || !img.naturalHeight || /\.svg(\?|#|$)/i.test(img.currentSrc || img.src)) continue;
+    const cs = getComputedStyle(img);
+    if (cs.objectFit !== 'fill') continue;
+    const r = img.getBoundingClientRect();
+    const box = { w: r.width - parseFloat(cs.paddingLeft) - parseFloat(cs.paddingRight), h: r.height - parseFloat(cs.paddingTop) - parseFloat(cs.paddingBottom) };
+    if (box.w < 16 || box.h < 16) continue;
+    const ratio = (box.w / box.h) / (img.naturalWidth / img.naturalHeight);
+    if (Math.abs(ratio - 1) > 0.1) {
+      distorted.push(`${(img.currentSrc || img.src).startsWith('data:') ? 'an embedded image' : (img.currentSrc || img.src).split('/').pop().slice(0, 50)} is ${img.naturalWidth} × ${img.naturalHeight} but shown at ${Math.round(box.w)} × ${Math.round(box.h)} (${ratio > 1 ? 'stretched wide' : 'squashed'})`);
+      targets.distorted.push(cssPath(img));
+    }
+  }
+
+  // A loading indicator still showing after the page finished loading.
+  const loading = [];
+  targets.loading = [];
+  for (const el of document.querySelectorAll('[aria-busy=true], [role=progressbar]:not([aria-valuenow]), [class*=spinner i], [class*=loader i], [class*=loading i], [class*=skeleton i]')) {
+    if (loading.length >= 3 || !visible(el) || inDialog(el) || targets.loading.some((sel) => document.querySelector(sel)?.contains(el))) continue;
+    const r = el.getBoundingClientRect();
+    if (r.width < 8 || r.height < 8) continue;
+    loading.push(describe(el));
+    targets.loading.push(cssPath(el));
+  }
+
   // Small text on phones.
   const small = [];
   if (phone) {
@@ -219,6 +391,13 @@ export function inPageAudit([phone, screenWidth]) {
     overflow: overflow.map((o) => `${describe(o.el)} reaches ${o.right}px`),
     targets: { ...targets, overflow: overflow.map((o) => cssPath(o.el)), brokenImages: [...document.images].filter((img) => img.complete && img.naturalWidth === 0 && (img.currentSrc || img.src)).slice(0, 10).map(cssPath) },
     clipped,
+    outside,
+    textOverlaps,
+    cutOff,
+    covered,
+    placeholders,
+    distorted,
+    loading,
     small,
     overlaps,
     brokenImages,

package/src/core/explain.mjs

@@ -0,0 +1,303 @@
+/**
+ * Plain-language explanations for every finding, written for the developer who has to fix it:
+ *   what   what is wrong, in one or two sentences anyone on the team understands
+ *   who    who is affected and how (why it matters)
+ *   expected  how it should be instead, in one sentence (shown next to the Expected picture)
+ *   ref    the standard or guideline behind the check
+ * Accessibility findings from axe-core are explained per axe rule (AXE below).
+ */
+
+const WHO = {
+  functionality: 'Every user of the page: something does not work as it should.',
+  responsive: 'Users on the screen sizes listed: the page looks broken or is hard to use.',
+  accessibility: 'People with disabilities (screen-reader, keyboard-only, low-vision users) and anyone in a hurry or on a small screen.',
+  performance: 'Every user, most of all on phones and slow connections: the page feels slow.',
+  auth: 'Everyone with an account: their data and access depend on it.',
+  api: 'Everyone using the app: the server lets wrong or unsafe requests through, or fails.',
+  security: 'Your users and your organisation: attackers can use this.',
+  seo: 'People finding or sharing the site: search results and shared links look wrong.',
+  code: 'The team: the code is harder to maintain or ships mistakes.',
+};
+
+export const EXPLAIN = {
+  // ---------- functionality ----------
+  'build-failed': { what: 'The production build stops with an error, so this version cannot be deployed.', who: 'Nobody can use this version.' },
+  'start-failed': { what: 'The app does not start after the build, so nothing could be checked.', who: 'Nobody can use this version.' },
+  'page-error': { what: 'A JavaScript error stopped part of the page from running. Parts of the page may be missing or buttons may do nothing.', who: 'Every user who opens this page.', code: '// Before\nconst email = profile.contact.email;\n// After: guard data that may be missing\nconst email = profile?.contact?.email ?? \'\';' },
+  'console-error': { what: 'The page writes an error in the browser console. Often a sign of a bug, a failed request or a framework warning.', who: 'Usually invisible to users, but it often hides a real problem.' },
+  'failed-request': { what: 'The page asked the server for something (data, a script, a style) and got an error or no answer.', who: 'Users of this page: data or styling may be missing.' },
+  'broken-image': { what: 'An image on the page does not load and shows as broken or empty.', who: 'Every user of this page.' },
+  'broken-link': { what: 'A link leads to a page that does not exist ("page not found").', who: 'Users who click the link.' },
+  'broken-anchor': { what: 'A link that should jump to a section of the page (#…) points to a section that does not exist.', who: 'Users who click it: nothing happens.' },
+  'blank-page': { what: 'The page shows nothing at all.', who: 'Every user who opens this page.' },
+  'crash-when-api-fails': { what: 'When the server has a short problem, this page throws an error instead of telling the user.', who: 'Users during any server hiccup: they see a broken page.', code: '// Before\napi(\'/me\').then(setMe);\n// After\napi(\'/me\').then(setMe).catch(() => setError(\'Your profile could not be loaded. Try again.\'));' },
+  'blank-when-api-fails': { what: 'When the server has a short problem, this page goes blank.', who: 'Users during any server hiccup.' },
+  'silent-when-api-fails': { what: 'When the server has a short problem, the page shows no message: users wait for data that never comes.', who: 'Users during any server hiccup.', code: '{error && <p role="alert">Your applications could not be loaded. Please try again.</p>}' },
+  'no-not-found-page': { what: 'An address that does not exist shows a blank or normal page instead of a clear "page not found" page.', who: 'Users with an old bookmark or a mistyped address.' },
+  'login-failed': { what: 'The tool could not sign in with the test account, so the signed-in pages were not checked.', who: 'This run: most of the app was not tested.' },
+
+  // ---------- design and layout ----------
+  'missing-viewport-meta': { what: 'The page does not tell phones how wide it is, so phones show it zoomed out and tiny.', who: 'Phone users.', code: '<meta name="viewport" content="width=device-width, initial-scale=1">', ref: 'WCAG 1.4.10 Reflow' },
+  'horizontal-overflow': { what: 'Something on the page is wider than the screen, so the whole page scrolls sideways (the dashed line in the picture is the edge of the screen).', who: 'Phone and tablet users: they have to scroll left and right to read the page.', code: '/* Wrap wide tables so only the table scrolls */\n.table-wrap { overflow-x: auto; }\n/* and let other content shrink */\nimg, video { max-width: 100%; }', ref: 'WCAG 1.4.10 Reflow' },
+  'clipped-text': { what: 'Text is cut off inside its box, so part of it cannot be read.', who: 'Users on the screen sizes listed.', code: '/* Let the box grow, or show an ellipsis on purpose */\n.label { overflow: visible; }\n/* or */ .label { text-overflow: ellipsis; white-space: nowrap; overflow: hidden; }' },
+  'text-outside-box': { what: 'The box (for example a button) is smaller than its text, so the text runs out of it and over the page around it. Text outside the box is often hard or impossible to read.', who: 'Every user on the screen sizes listed.' },
+  'text-overlap': { what: 'Two pieces of text are drawn on top of each other, so neither can be read properly.', who: 'Every user on the screen sizes listed.' },
+  'cut-off-at-edge': { what: 'Part of the content is outside the screen and the page does not let the user scroll to it, so it cannot be seen at all.', who: 'Users on the screen sizes listed.' },
+  'control-covered': { what: 'Something lies on top of a button or link, so clicking it hits the covering element instead and nothing (or the wrong thing) happens.', who: 'Every user on the screen sizes listed.' },
+  'placeholder-text': { what: 'The page shows text that was never filled in properly: a value the code did not have (undefined, NaN, null), a translation key instead of the words, template braces or sample text.', who: 'Every user of this page; it looks broken and unprofessional.' },
+  'distorted-image': { what: 'An image is shown at a different shape than the picture itself, so it looks stretched or squashed.', who: 'Every user on the screen sizes listed.' },
+  'stuck-loading': { what: 'A loading indicator (spinner, skeleton, busy state) is still showing after the page and all its requests finished, so the user waits for content that never comes.', who: 'Every user of this page.' },
+  'overlapping-elements': { what: 'Buttons or links lie on top of each other, so users may press the wrong one.', who: 'Users on the screen sizes listed, especially on touch screens.' },
+  'small-text': { what: 'Text is smaller than 12 px on a phone and is hard to read.', who: 'Phone users, especially older users.', code: 'body { font-size: 16px; } /* and use rem for smaller text, never below 0.75rem */' },
+  'rtl-missing': { what: 'The page is in a right-to-left language (Arabic…) but is laid out left to right.', who: 'Arabic readers: the text and layout run in the wrong direction.', code: '<html lang="ar" dir="rtl">' },
+  'font-failed': { what: 'A web font did not load, so the page falls back to another font and looks different from the design.', who: 'Every user of this page.' },
+  'inconsistent-typography': { what: 'The page uses many different fonts or text sizes, so it looks inconsistent.', who: 'Every user: the design looks less polished.' },
+  'visual-change': { what: 'The page looks different from the saved baseline picture (changed areas in red). If you did not mean to change it, it is a design regression.', who: 'Every user of this page.' },
+
+  // ---------- accessibility and keyboard ----------
+  'focus-not-visible': { what: 'When you press Tab, these items get the keyboard focus, but nothing on screen shows it. Keyboard users cannot see where they are on the page.', who: 'Keyboard-only and screen-reader users, and anyone using Tab to fill in forms.', code: '/* Before */\nnav a:focus { outline: none; }\n/* After */\nnav a:focus-visible { outline: 2px solid #1f4fbf; outline-offset: 2px; }', ref: 'WCAG 2.4.7 Focus Visible (AA)' },
+  'keyboard-trap': { what: 'Pressing Tab keeps the focus on the same element: keyboard users are stuck and cannot leave it.', who: 'Keyboard-only and screen-reader users: they cannot use the rest of the page.', ref: 'WCAG 2.1.2 No Keyboard Trap (A)' },
+  'mouse-only-control': { what: 'This element reacts to a mouse click but cannot be reached or used with the keyboard (it is a clickable <div> or <span>, not a button or link).', who: 'Keyboard-only and screen-reader users: they cannot open or use it.', code: '<!-- Before -->\n<div class="card" onClick={toggle}>Opening hours</div>\n<!-- After -->\n<button type="button" class="card" onClick={toggle} aria-expanded={open}>Opening hours</button>', ref: 'WCAG 2.1.1 Keyboard (A)' },
+  'form-field-type': { what: 'Form fields use a general text type where a specific one exists (email, phone), or a password field cannot be filled by password managers.', who: 'Phone users get the wrong keyboard; password-manager users must type passwords by hand.', code: '<input type="email" autocomplete="email">\n<input type="tel" autocomplete="tel">\n<input type="password" autocomplete="current-password">', ref: 'WCAG 1.3.5 Identify Input Purpose (AA)' },
+
+  // ---------- performance ----------
+  'heavy-page': { what: 'The page downloads more data than the budget, so it loads slowly on phones.', who: 'Phone users and anyone on a slow or paid connection.' },
+  'heavy-javascript': { what: 'The page downloads more JavaScript than the budget. The browser must download and run all of it before the page responds.', who: 'Phone users: the page loads and reacts slowly.', code: '// Load pages only when they are opened (React)\nconst Reports = lazy(() => import(\'./pages/Reports\'));' },
+  'too-many-requests': { what: 'The page makes more requests than the budget; each one adds waiting time.', who: 'Users on slow connections.' },
+  'slow-page': { what: 'The page took longer than the budget to load, even on this fast computer.', who: 'Every user; on phones it will be slower still.' },
+  'page-layout-shift': { what: 'Content jumps around while the page loads, so users may click the wrong thing.', who: 'Every user, most of all on phones.', code: '<img src="banner.jpg" width="1200" height="400" alt="…">', ref: 'Core Web Vitals: CLS' },
+  'main-thread-blocked': { what: 'Scripts keep the browser busy while the page loads, so clicks and typing lag.', who: 'Every user, most of all on mid-range phones.', ref: 'Core Web Vitals: INP' },
+  'oversized-images': { what: 'Images are downloaded much larger than they are shown, wasting data and time.', who: 'Phone users and slow connections.', code: '<img src="photo-800.webp" srcset="photo-400.webp 400w, photo-800.webp 800w" sizes="(max-width: 600px) 100vw, 800px" alt="…">' },
+  'images-without-size': { what: 'Images have no width and height, so the page jumps when they load.', who: 'Every user.', code: '<img src="logo.png" width="160" height="40" alt="Service Portal">' },
+  'slow-api-call': { what: 'An API call the page makes is slower than the budget, so users wait for the data.', who: 'Every user of the pages that make this call.' },
+  'large-api-response': { what: 'An API call returns a very large response, which is slow to download and process.', who: 'Phone users and slow connections.' },
+  'repeated-api-call': { what: 'The page sends the same request several times while it loads. The extra requests only add waiting time and server load.', who: 'Every user, and the server.', code: '// React: one request, shared by every component\nconst { data } = useQuery({ queryKey: [\'health\'], queryFn: getHealth });' },
+  'too-many-api-calls': { what: 'The page makes many API calls while it loads.', who: 'Users on slow connections, and the server.' },
+  'uncompressed-response': { what: 'Text files and responses are sent without compression, so they are several times larger than needed.', who: 'Every user.', code: '# Nginx\ngzip on;\ngzip_types text/css application/javascript application/json;' },
+  'assets-not-cached': { what: 'Built files are downloaded again on every visit instead of coming from the browser cache.', who: 'Returning users.', code: '# Nginx: files with a hash in the name never change\nlocation /assets/ { add_header Cache-Control "public, max-age=31536000, immutable"; }' },
+  'slow-under-load': { what: 'With several users at the same time, requests become slow.', who: 'Every user at busy times.' },
+  'errors-under-load': { what: 'With several users at the same time, some requests fail.', who: 'Every user at busy times.' },
+  'perf-score-low': { what: 'Lighthouse rates the page speed as poor.', who: 'Every user, most of all on phones.' },
+  'perf-score-medium': { what: 'Lighthouse rates the page speed as needing improvement.', who: 'Phone users.' },
+  'slow-lcp': { what: 'The main content of the page appears late (Largest Contentful Paint).', who: 'Every user, most of all on phones.', ref: 'Core Web Vitals: LCP' },
+  'layout-shift': { what: 'Content jumps around while the page loads (Cumulative Layout Shift).', who: 'Every user.', ref: 'Core Web Vitals: CLS' },
+  'blocking-time': { what: 'Scripts block the page so it cannot respond to clicks for a while (Total Blocking Time).', who: 'Every user, most of all on phones.' },
+  'large-javascript': { what: 'The page loads a lot of JavaScript.', who: 'Phone users.' },
+
+  // ---------- sign-in and access ----------
+  'wrong-password-accepted': { what: 'The sign-in let the test user in with a WRONG password (or an empty form).', who: 'Every account: anyone could sign in as anyone.', ref: 'OWASP ASVS V2 Authentication' },
+  'login-no-error-message': { what: 'After a wrong password, the sign-in page shows no message.', who: 'Users who mistype their password: they do not know what happened.' },
+  'empty-login-no-feedback': { what: 'Submitting the empty sign-in form shows nothing about what is missing.', who: 'Every user signing in.' },
+  'user-enumeration': { what: 'A wrong password and an unknown user get different messages, so anyone can find out which accounts exist.', who: 'Every account holder: attackers can build a list of valid accounts.', code: '// Same message for both cases\nreturn res.status(401).json({ message: \'The user name or password is not correct.\' });', ref: 'OWASP ASVS 2.2' },
+  'page-without-sign-in': { what: 'A page that is shown to signed-in users also opens without signing in.', who: 'Account holders: their information may be visible to anyone.' },
+  'api-without-sign-in': { what: 'An API the app uses returns data without signing in.', who: 'Account holders: their data is readable by anyone who knows the address.', ref: 'OWASP API Security Top 10: API2' },
+  'sensitive-field-in-api': { what: 'An API response contains a field such as a password hash, secret or ID number.', who: 'Account holders: anyone who can see the response sees their sensitive data.', ref: 'OWASP API Security Top 10: API3' },
+  'token-in-web-storage': { what: 'The sign-in token is kept in localStorage or sessionStorage, where any script on the page can read it.', who: 'Account holders: if any script is compromised, their session can be stolen.', ref: 'OWASP Session Management' },
+  'form-server-error': { what: 'Submitting a form made the server fail (error 500).', who: 'Users of this form.' },
+  'form-accepts-empty': { what: 'An empty form was sent to the server and accepted.', who: 'Users and data quality: empty records are created.' },
+  'form-no-feedback': { what: 'Submitting the form empty gives no message about what is missing.', who: 'Users of this form.', code: '<input id="email" required aria-describedby="email-error">\n<p id="email-error" role="alert">Enter your email.</p>' },
+  'sso-not-https': { what: 'A sign-in with Google, UAE PASS or another provider starts over an unencrypted connection.', who: 'Every user signing in this way.' },
+  'sso-no-state': { what: 'The sign-in with an outside provider sends no "state" value. Without it, an attacker can trick a user into signing in to the attacker\'s account (login CSRF).', who: 'Every user signing in this way.', code: '// Use a library that adds state and PKCE (Auth.js, MSAL, oidc-client-ts),\n// or add a random state, keep it in the session, and compare it on return.', ref: 'OAuth 2.0 Security Best Current Practice (RFC 9700)' },
+  'sso-implicit-flow': { what: 'The sign-in uses the old token flow, which puts tokens in the address bar.', who: 'Every user signing in this way.', ref: 'RFC 9700' },
+  'sso-no-pkce': { what: 'The sign-in uses the code flow without PKCE.', who: 'Every user signing in this way (only a risk for apps without a server-side secret).', ref: 'RFC 9700' },
+  'sso-insecure-redirect': { what: 'The provider sends users back to an unencrypted or incomplete address.', who: 'Every user signing in this way.' },
+  'sso-button-broken': { what: 'A sign-in button (Google, UAE PASS…) does nothing when clicked.', who: 'Everyone who signs in this way: they cannot sign in.' },
+  'sso-cancel-crash': { what: 'When a user cancels at Google or UAE PASS, the page they come back to fails.', who: 'Users who change their mind or close the provider page.' },
+  'sso-cancel-blank': { what: 'When a user cancels at Google or UAE PASS, the page they come back to is blank.', who: 'Users who change their mind or close the provider page.' },
+  'sso-cancel-silent': { what: 'When a user cancels at Google or UAE PASS, the page they come back to does not say what happened.', who: 'Users who change their mind: they are stuck on "Signing you in…".', code: 'const error = new URLSearchParams(location.search).get(\'error\');\nif (error) return <p role="alert">Sign-in was cancelled. <a href="/login">Try again</a></p>;' },
+  'session-expired': { what: 'The saved sign-in (session or token) no longer works, so the signed-in pages were not really tested.', who: 'This run.' },
+  'signed-in-not-tested': { what: 'The tool was not told how to sign in, so only the public pages were tested.', who: 'This run: the signed-in part of the app was not checked.' },
+
+  // ---------- API tests ----------
+  'api-other-users-data': { what: 'A signed-in user could open a record that belongs to ANOTHER user by changing the id in the address.', who: 'Every account holder: anyone signed in can read other people\'s data.', code: '// Before\nconst record = await db.find(id);\n// After\nconst record = await db.find(id);\nif (!record || record.ownerId !== user.id) return res.status(404).end();', ref: 'OWASP API Security Top 10: API1 (Broken Object Level Authorization)' },
+  'api-no-token-accepted': { what: 'An endpoint that needs sign-in answered without any sign-in.', who: 'Account holders: their data is open to anyone.', ref: 'OWASP API2' },
+  'api-bad-token-accepted': { what: 'An endpoint accepted a tampered sign-in token.', who: 'Every account: tokens are not really checked.', ref: 'OWASP API2' },
+  'api-wrong-role-allowed': { what: 'A user without the needed role (for example not an admin) could use an endpoint meant for that role.', who: 'Your organisation: normal users can do admin actions.', ref: 'OWASP API5 (Broken Function Level Authorization)' },
+  'api-accepts-invalid-input': { what: 'The server accepted data that breaks its own rules (wrong type, too long, missing field).', who: 'Data quality and security: bad data gets stored.', ref: 'OWASP API Security' },
+  'api-mass-assignment': { what: 'The server let the client set a field it should control itself (for example status, role or owner).', who: 'Your organisation: users can change things they must not.', ref: 'OWASP API3 (Broken Object Property Level Authorization)' },
+  'api-server-error': { what: 'A request made the server fail (error 500).', who: 'Users of this feature.' },
+  'api-error-leaks-details': { what: 'An error response shows internal details (stack traces, SQL, file paths).', who: 'Your organisation: attackers learn how the system is built.' },
+  'api-slow': { what: 'Some API endpoints answer slower than the budget.', who: 'Every user of those features.' },
+
+  // ---------- security ----------
+  'exposed-file': { what: 'A private file (for example .env or .git) can be downloaded from the site.', who: 'Your organisation: passwords and keys inside it are public.' },
+  'secret-in-bundle': { what: 'A secret (API key, password, private key) is inside the JavaScript sent to every browser.', who: 'Your organisation: anyone can read and use it.' },
+  'secret-in-source': { what: 'A secret is written in the source code.', who: 'Your organisation: everyone with the code (and Git history) has it.' },
+  'source-maps-public': { what: 'Source maps can be downloaded, so anyone can read your original source code.', who: 'Your organisation.' },
+  'missing-csp': { what: 'The site sends no Content-Security-Policy, which limits the damage of injected scripts.', who: 'Every user, if a script injection bug exists.', code: "Content-Security-Policy: default-src 'self'; frame-ancestors 'none'" },
+  'missing-frame-protection': { what: 'Another site can show this site inside a frame (clickjacking).', who: 'Every user.', code: "Content-Security-Policy: frame-ancestors 'none'" },
+  'insecure-cookie': { what: 'A cookie is missing protective flags (HttpOnly, Secure or SameSite).', who: 'Every signed-in user.', code: 'Set-Cookie: session=…; HttpOnly; Secure; SameSite=Lax; Path=/' },
+  'vulnerable-dependency': { what: 'A package the app ships has a known vulnerability.', who: 'Every user, depending on the vulnerability.' },
+  'vulnerable-dependency-critical': { what: 'A package the app ships has a known CRITICAL vulnerability.', who: 'Every user.' },
+  'sensitive-in-url': { what: 'A password, token or ID number is sent in an address, where it is kept in logs and browser history.', who: 'The users whose values these are.' },
+  'mixed-content': { what: 'An HTTPS page loads something over plain HTTP.', who: 'Every user: the browser may block it or show a warning.' },
+
+  // ---------- SEO ----------
+  'missing-title': { what: 'The page has no title (the text shown in browser tabs and search results).', who: 'Everyone with several tabs open, and search engines.' },
+  'duplicate-title': { what: 'Several pages have the same title, so browser tabs, history and search results cannot be told apart.', who: 'Every user with several tabs open, and search engines.', code: "document.title = 'My applications · Service Portal';" },
+  'missing-description': { what: 'The page has no description for search results and shared links.', who: 'People finding the site in search.' },
+  'missing-h1': { what: 'The page has no main heading (h1).', who: 'Screen-reader users and search engines.' },
+  'missing-lang': { what: 'The page does not say its language.', who: 'Screen-reader users (wrong pronunciation) and translation tools.', code: '<html lang="en">', ref: 'WCAG 3.1.1 (A)' },
+};
+
+/** axe-core rules: the id is the start of the finding's detail ("color-contrast: …"). */
+export const AXE = {
+  'color-contrast': { what: 'Text is too light against its background to be read easily.', who: 'Low-vision users, older users, and anyone reading in sunlight.', code: '/* Before */ .faint { color: #b9bec6; }\n/* After: at least 4.5:1 against the background */ .faint { color: #5d6672; }', ref: 'WCAG 1.4.3 Contrast (AA)' },
+  'image-alt': { what: 'An image has no text alternative (alt), so screen readers cannot say what it shows.', who: 'Blind and screen-reader users.', code: '<img src="hero.svg" alt="People applying for services online">\n<!-- decorative images: alt="" -->', ref: 'WCAG 1.1.1 (A)' },
+  label: { what: 'A form field has no label, so screen readers cannot say what to type.', who: 'Screen-reader users, and voice-control users.', code: '<label for="email">Email</label>\n<input id="email" type="email">', ref: 'WCAG 1.3.1, 4.1.2 (A)' },
+  'button-name': { what: 'A button has no name (for example an icon without text), so screen readers say only "button".', who: 'Screen-reader users.', code: '<button aria-label="Close"><svg …/></button>', ref: 'WCAG 4.1.2 (A)' },
+  'link-name': { what: 'A link has no name (for example an icon without text).', who: 'Screen-reader users.', code: '<a href="/profile" aria-label="My profile"><svg …/></a>', ref: 'WCAG 2.4.4, 4.1.2 (A)' },
+  'target-size': { what: 'A button or link is too small or too close to others to tap reliably.', who: 'Touch-screen users and people with limited hand control.', code: '.icon-button { min-width: 24px; min-height: 24px; }', ref: 'WCAG 2.5.8 Target Size (AA)' },
+  'html-has-lang': { what: 'The page does not say its language.', who: 'Screen-reader users.', code: '<html lang="en">', ref: 'WCAG 3.1.1 (A)' },
+  'document-title': { what: 'The page has no title.', who: 'Screen-reader users and everyone with several tabs.', ref: 'WCAG 2.4.2 (A)' },
+  'select-name': { what: 'A dropdown has no label.', who: 'Screen-reader users.', ref: 'WCAG 4.1.2 (A)' },
+  'aria-required-attr': { what: 'An element with an ARIA role is missing an attribute that role needs.', who: 'Screen-reader users.', ref: 'WCAG 4.1.2 (A)' },
+  'list': { what: 'A list is built incorrectly, so screen readers cannot announce it as a list.', who: 'Screen-reader users.', ref: 'WCAG 1.3.1 (A)' },
+  'listitem': { what: 'A list item is not inside a list.', who: 'Screen-reader users.', ref: 'WCAG 1.3.1 (A)' },
+  'meta-viewport': { what: 'The page stops users from zooming in.', who: 'Low-vision users.', code: '<meta name="viewport" content="width=device-width, initial-scale=1">', ref: 'WCAG 1.4.4 (AA)' },
+  'frame-title': { what: 'A frame has no title.', who: 'Screen-reader users.', ref: 'WCAG 4.1.2 (A)' },
+  'duplicate-id-aria': { what: 'Two elements share an id used by ARIA, so labels point to the wrong element.', who: 'Screen-reader users.', ref: 'WCAG 4.1.2 (A)' },
+  'nested-interactive': { what: 'A button or link is inside another button or link.', who: 'Keyboard and screen-reader users.', ref: 'WCAG 4.1.2 (A)' },
+};
+
+
+/** How it should be, in one sentence, for the "Expected" side of each finding. */
+export const EXPECTED = {
+  'page-error': 'The page runs without JavaScript errors, and every part of it shows.',
+  'console-error': 'The browser console shows no errors on this page.',
+  'failed-request': 'Every request the page makes succeeds.',
+  'broken-image': 'The image loads and shows.',
+  'broken-link': 'The link opens an existing page.',
+  'broken-anchor': 'The link jumps to the section it names.',
+  'blank-page': 'The page shows its content.',
+  'crash-when-api-fails': 'The page stays on screen and shows a message such as "Could not load your profile. Try again."',
+  'blank-when-api-fails': 'The page stays on screen and shows a message with a way to try again.',
+  'silent-when-api-fails': 'A clear message says the data could not be loaded, with a way to try again.',
+  'no-not-found-page': 'An unknown address shows a "Page not found" page with a link home.',
+  'missing-viewport-meta': 'Phones show the page at its normal size, not zoomed out.',
+  'horizontal-overflow': 'The page fits the screen: no sideways scrolling. Wide content (such as a table) scrolls inside its own box.',
+  'clipped-text': 'All the text is visible inside its box.',
+  'text-outside-box': 'The box grows to fit its text: all the text sits inside it and nothing runs over the page.',
+  'text-overlap': 'Each piece of text has its own space and can be read on its own.',
+  'cut-off-at-edge': 'All the content fits inside the screen.',
+  'control-covered': 'Nothing covers the button or link: a click on it works.',
+  'placeholder-text': 'Every value shows real text: a name, number, date or a clear "not available".',
+  'distorted-image': 'The image keeps its own shape: it fits or is cropped, never stretched.',
+  'stuck-loading': 'When loading ends the indicator goes away and the content (or an error message) is shown.',
+  'overlapping-elements': 'Buttons and links sit apart, each easy to press on its own.',
+  'small-text': 'Text on phones is at least 12 px (16 px for body text) and easy to read.',
+  'rtl-missing': 'The Arabic page reads right to left: text, menus and layout are mirrored.',
+  'font-failed': 'The page uses the font from the design.',
+  'inconsistent-typography': 'The page uses one or two fonts and a small set of text sizes.',
+  'visual-change': 'The page looks like the approved baseline picture.',
+  'focus-not-visible': 'When you press Tab, a clear ring shows which item has the focus.',
+  'keyboard-trap': 'Pressing Tab always moves on to the next item.',
+  'mouse-only-control': 'The item can be reached with Tab and opened with Enter or Space, like a real button.',
+  'form-field-type': 'Email and phone fields bring up the right keyboard, and password managers can fill the password.',
+  'heavy-page': 'The page downloads less than the budget.',
+  'heavy-javascript': 'The page loads only the JavaScript it needs.',
+  'too-many-requests': 'The page makes fewer requests than the budget.',
+  'slow-page': 'The page loads within the budget.',
+  'page-layout-shift': 'Content stays in place while the page loads.',
+  'main-thread-blocked': 'The page reacts to clicks and typing right away while it loads.',
+  'oversized-images': 'Images are downloaded at the size they are shown.',
+  'images-without-size': 'Images have a width and height, so nothing jumps when they load.',
+  'slow-api-call': 'The API call answers within the budget.',
+  'large-api-response': 'The API returns only the data the page shows.',
+  'repeated-api-call': 'Each request is sent once per page load.',
+  'too-many-api-calls': 'The page needs only a few API calls to load.',
+  'uncompressed-response': 'Text files and responses are sent compressed (gzip or brotli).',
+  'assets-not-cached': 'Built files come from the browser cache on later visits.',
+  'slow-under-load': 'Requests stay fast with several users at the same time.',
+  'errors-under-load': 'No requests fail with several users at the same time.',
+  'wrong-password-accepted': 'A wrong password or an empty form is refused.',
+  'login-no-error-message': 'A wrong password shows a clear message.',
+  'empty-login-no-feedback': 'An empty sign-in shows which fields are needed.',
+  'user-enumeration': 'A wrong password and an unknown user get the same message.',
+  'page-without-sign-in': 'Opening the page without signing in sends the user to the sign-in page.',
+  'api-without-sign-in': 'The API answers 401 without signing in.',
+  'sensitive-field-in-api': 'API responses never contain passwords, secrets or ID numbers.',
+  'token-in-web-storage': 'The sign-in token is kept in an HttpOnly cookie that scripts cannot read.',
+  'form-server-error': 'The server answers bad input with a clear 400 message, never a 500.',
+  'form-accepts-empty': 'The form is not sent until the required fields are filled in.',
+  'form-no-feedback': 'Each missing field shows a message next to it.',
+  'sso-no-state': 'Every sign-in request carries a random "state" value that is checked on return.',
+  'sso-not-https': 'The sign-in starts on an https:// address.',
+  'sso-implicit-flow': 'The sign-in uses response_type=code with PKCE.',
+  'sso-no-pkce': 'The sign-in sends a code_challenge (PKCE).',
+  'sso-insecure-redirect': 'The provider returns the user to an https:// address of your own.',
+  'sso-button-broken': 'Clicking the button opens the provider\'s sign-in.',
+  'sso-cancel-crash': 'After a cancelled sign-in, the page says "Sign-in was cancelled" with a way to try again.',
+  'sso-cancel-blank': 'After a cancelled sign-in, the page says "Sign-in was cancelled" with a way to try again.',
+  'sso-cancel-silent': 'After a cancelled sign-in, the page says "Sign-in was cancelled" with a way to try again.',
+  'session-expired': 'The saved sign-in works, so every signed-in page is tested.',
+  'signed-in-not-tested': 'The tool signs in, so every signed-in page is tested.',
+  'api-other-users-data': 'Asking for another user\'s record answers 404 (or 403); users only see their own records.',
+  'api-no-token-accepted': 'Without signing in, the endpoint answers 401.',
+  'api-bad-token-accepted': 'A tampered token is refused with 401.',
+  'api-wrong-role-allowed': 'Users without the role get 403.',
+  'api-accepts-invalid-input': 'Invalid data is refused with 400 and a clear message.',
+  'api-mass-assignment': 'Fields the server controls (status, role, owner) are ignored or refused.',
+  'api-server-error': 'The server never answers 500 to a request.',
+  'api-error-leaks-details': 'Error responses show a short message, no internal details.',
+  'api-slow': 'Every endpoint answers within the budget.',
+  'exposed-file': 'Private files answer 404.',
+  'secret-in-bundle': 'No secrets in the JavaScript sent to browsers.',
+  'secret-in-source': 'No secrets in the source code; they come from the server environment.',
+  'source-maps-public': 'Source maps are not served in production.',
+  'missing-csp': 'The page is sent with a Content-Security-Policy header.',
+  'missing-frame-protection': 'The page refuses to be shown inside other sites.',
+  'insecure-cookie': 'Session cookies have HttpOnly, Secure and SameSite.',
+  'vulnerable-dependency': 'No dependency with a known vulnerability ships to production.',
+  'vulnerable-dependency-critical': 'No dependency with a known vulnerability ships to production.',
+  'sensitive-in-url': 'Passwords, tokens and ID numbers travel in headers or the request body, never in the address.',
+  'missing-title': 'The page has a title that names it.',
+  'duplicate-title': 'Each page has its own title, for example "My applications · Service Portal".',
+  'missing-description': 'The page has a short description.',
+  'missing-h1': 'The page has one main heading (h1).',
+  'missing-lang': 'The page says its language, for example <html lang="en">.',
+};
+export const AXE_EXPECTED = {
+  'color-contrast': 'The text is dark enough to read easily against its background (contrast at least 4.5:1).',
+  'image-alt': 'The image has a text alternative (alt) that says what it shows, or alt="" if it is decoration.',
+  label: 'Every form field has a visible label that screen readers read out.',
+  'button-name': 'Every button has a name that screen readers read out.',
+  'link-name': 'Every link has a name that screen readers read out.',
+  'target-size': 'Buttons and links are at least 24 × 24 px with space around them.',
+  'html-has-lang': 'The page says its language.',
+  'meta-viewport': 'Users can zoom in.',
+};
+
+/** The explanation for a finding: rule- or axe-specific, with sensible fallbacks. */
+export function explain(finding) {
+  let entry = EXPLAIN[finding.ruleId];
+  if (/^a11y-/.test(finding.ruleId)) {
+    const axeId = String(finding.detail ?? '').split(':')[0].trim();
+    entry = AXE[axeId] ?? { what: String(finding.detail ?? '').split(':').slice(1).join(':').trim() || finding.title, who: WHO.accessibility, ref: 'WCAG 2.2 AA' };
+  }
+  const axeId = /^a11y-/.test(finding.ruleId) ? String(finding.detail ?? '').split(':')[0].trim() : '';
+  return {
+    what: entry?.what ?? finding.title,
+    who: entry?.who ?? WHO[finding.area] ?? '',
+    expected: (axeId ? AXE_EXPECTED[axeId] : EXPECTED[finding.ruleId]) ?? '',
+    ref: entry?.ref ?? '',
+  };
+}
+
+/** "a#nav.link \"About\"" → the link "About" (for people, next to the CSS selector). */
+export function humanElement(item) {
+  const match = String(item).match(/^([a-z0-9]+)[^\s"]*\s*(?:"([^"]*)")?/i);
+  if (!match) return String(item);
+  const names = { a: 'link', button: 'button', input: 'field', select: 'dropdown', textarea: 'text box', img: 'image', table: 'table', div: 'box', span: 'text', p: 'paragraph', h1: 'heading', h2: 'heading', h3: 'heading', label: 'label', nav: 'menu', li: 'list item', td: 'table cell', th: 'table heading', svg: 'icon', form: 'form', section: 'section', header: 'header', footer: 'footer' };
+  const kind = names[match[1].toLowerCase()] ?? match[1].toLowerCase();
+  return match[2] ? `the ${kind} "${match[2]}"` : `a ${kind}`;
+}
+
+/** The elements of a finding for people: the link "About" next to its CSS selector. */
+export function elementsOf(f) {
+  const selectors = f.selectors ?? [];
+  const items = f.items ?? [];
+  // Only short element descriptions ("a \"About\"") become names; longer items stay under Details.
+  const describes = (item) => /^[a-z][a-z0-9]*[#.\w-]*(\s+"[^"]*")?$/i.test(String(item).trim());
+  return selectors.slice(0, 6).map((selector, i) => ({ name: items[i] && describes(items[i]) ? humanElement(items[i]) : '', selector }));
+}

package/src/core/rules.mjs

@@ -69,6 +69,34 @@ export const RULES = {
     area: 'responsive', severity: 'minor', title: 'Text is cut off inside its box',
     fix: 'Let the box grow (remove fixed width/height), allow wrapping, or use text-overflow: ellipsis with a title so the full text can still be read.',
   },
+  'text-outside-box': {
+    area: 'responsive', severity: 'major', title: 'Text spills out of its box',
+    fix: 'Let the box fit its text: remove the fixed width/height (use min-width/min-height), allow wrapping, or shorten the text.',
+  },
+  'text-overlap': {
+    area: 'responsive', severity: 'major', title: 'Text lies on top of other text',
+    fix: 'Give each piece of text its own space at this screen size: remove the absolute position or negative margin, or let the container grow.',
+  },
+  'cut-off-at-edge': {
+    area: 'responsive', severity: 'major', title: 'Content is cut off at the edge of the screen',
+    fix: 'Keep the content inside the screen: max-width: 100%, no fixed widths or negative offsets; let long words wrap.',
+  },
+  'control-covered': {
+    area: 'functionality', severity: 'major', title: 'A button or link is covered by something else',
+    fix: 'Move the covering element away, or fix its position/z-index so the button or link can be clicked. Decorative layers should use pointer-events: none.',
+  },
+  'placeholder-text': {
+    area: 'functionality', severity: 'major', title: 'Unfinished text on the page (undefined, NaN, a translation key…)',
+    fix: 'Show real values: handle missing data (show a dash or a message), format dates and numbers, add the missing translations, and remove sample text.',
+  },
+  'distorted-image': {
+    area: 'responsive', severity: 'minor', title: 'An image is stretched or squashed',
+    fix: 'Keep the picture\'s shape: set only the width (height: auto), or use object-fit: cover / contain.',
+  },
+  'stuck-loading': {
+    area: 'functionality', severity: 'major', title: 'The page is still loading after everything has loaded',
+    fix: 'Hide the loading indicator when the data arrives and when a request fails; show the content or an error message.',
+  },
   'overlapping-elements': {
     area: 'responsive', severity: 'minor', title: 'Buttons or links overlap each other',
     fix: 'Give the items room at this screen size: wrap them, stack them, or reduce their size. Overlapping controls are hard to tap.',

package/src/export/docx.mjs

@@ -51,7 +51,7 @@ function imageSize(buffer, png) {
 const run = (text, options = {}) => new TextRun({ text: String(text ?? ''), font: FONT, ...options });
 const para = (text, options = {}, runOptions = {}) => new Paragraph({ spacing: { after: 120 }, ...options, children: [run(text, runOptions)] });
 
-function cell(text, width, { fill, bold, color, align, size = 19, keepNext = false } = {}) {
+function cell(text, width, { fill, bold, color, align, size = 19, keepNext = false, mono = false } = {}) {
   return new TableCell({
     width: { size: width, type: WidthType.DXA },
     borders,
@@ -60,7 +60,7 @@ function cell(text, width, { fill, bold, color, align, size = 19, keepNext = fal
     shading: fill ? { type: ShadingType.CLEAR, color: 'auto', fill } : undefined,
     children: String(text ?? '')
       .split('\n')
-      .map((line) => new Paragraph({ alignment: align, keepNext, children: [run(line, { bold, color, size })] })),
+      .map((line) => new Paragraph({ alignment: align, keepNext, children: [run(line, { bold, color, size: mono ? 17 : size, ...(mono ? { font: 'Consolas' } : {}) })] })),
   });
 }
 
@@ -99,7 +99,7 @@ function kv(rows, keepWithNext = false) {
   return new Table({
     width: { size: PAGE_WIDTH, type: WidthType.DXA },
     columnWidths: widths,
-    rows: rows.map(([k, v], i) => new TableRow({ cantSplit: true, children: [cell(k, widths[0], { fill: C.head, bold: true, keepNext: keepWithNext && i === rows.length - 1 }), cell(v, widths[1], { keepNext: keepWithNext && i === rows.length - 1 })] })),
+    rows: rows.map(([k, v], i) => new TableRow({ cantSplit: true, children: [cell(k, widths[0], { fill: C.head, bold: true, keepNext: keepWithNext && i === rows.length - 1 }), cell(v, widths[1], { keepNext: keepWithNext && i === rows.length - 1, mono: k === 'Elements' || k === 'Details', fill: undefined })] })),
   });
 }
 
@@ -158,23 +158,34 @@ export async function writeDocx(doc, reportDir, outFile) {
           children: [run(`${block.id}  `, { color: C.muted }), run(block.title), run(`  ${block.severity.toUpperCase()}`, { color: SEV[block.severity], size: 20 })],
         }),
       );
+      children.push(new Paragraph({ keepNext: true, spacing: { after: 120 }, children: [run(block.what, { size: 21 })] }));
+      // Actual (red) next to Expected (green): pictures where there are any, and one sentence each.
+      const half = Math.floor(PAGE_WIDTH / 2);
+      const side = (part, label, colour, png) => {
+        const parts = [new Paragraph({ spacing: { after: 80 }, children: [run(`${label}  `, { bold: true, color: colour, size: 18 }), run(label === 'ACTUAL' ? 'how it is now' : 'how it should be', { color: C.muted, size: 17 })] })];
+        if (part.src && existsSync(join(reportDir, part.src))) {
+          const data = readFileSync(join(reportDir, part.src));
+          const size = imageSize(data, png);
+          const scale = Math.min(205 / size.width, 200 / size.height);
+          parts.push(new Paragraph({ alignment: AlignmentType.CENTER, children: [new ImageRun({ type: png ? 'png' : 'jpg', data, transformation: { width: Math.round(size.width * scale * 1.333), height: Math.round(size.height * scale * 1.333) }, altText: { title: `${label}: ${block.title}`, description: part.text, name: `${block.id}-${label}` } })] }));
+        } else if (label === 'EXPECTED' && block.actual.src) {
+          parts.push(new Paragraph({ alignment: AlignmentType.CENTER, spacing: { before: 200, after: 200 }, children: [run('✓', { size: 56, color: C.good })] }));
+        }
+        parts.push(new Paragraph({ spacing: { before: 80 }, children: [run(part.text, { size: 18 })] }));
+        return new TableCell({
+          width: { size: half, type: WidthType.DXA },
+          margins: { top: 100, bottom: 100, left: 120, right: 120 },
+          shading: { type: ShadingType.CLEAR, color: 'auto', fill: 'F7F8FA' },
+          borders: { top: { style: BorderStyle.SINGLE, size: 24, color: colour }, bottom: border, left: border, right: border },
+          children: parts,
+        });
+      };
+      children.push(new Table({ width: { size: half * 2, type: WidthType.DXA }, columnWidths: [half, half], rows: [new TableRow({ cantSplit: true, children: [side(block.actual, 'ACTUAL', C.blocker, block.actual.png), side(block.expected, 'EXPECTED', C.good, false)] })] }));
+      children.push(new Paragraph({ spacing: { after: 80 }, children: [] }));
       const rows = [...block.rows];
-      if (block.selectors.length) rows.push(['Elements', block.selectors.join('\n')]);
-      rows.push(['Steps to see it', block.steps.map((step, i) => `${i + 1}. ${step}`).join('\n')]);
-      if (block.evidence.length) rows.push(['Evidence', block.evidence.join('\n')]);
-      rows.push(['How to fix', block.fix]);
-      rows.push(['Check the fix', block.verify]);
-      if (block.link) rows.push(['Reference', block.link]);
-      const pic0 = block.picture && existsSync(join(reportDir, block.picture.src));
-      children.push(kv(rows, pic0));
-      const pic = block.picture && existsSync(join(reportDir, block.picture.src)) ? block.picture : null;
-      if (pic) {
-        const data = readFileSync(join(reportDir, pic.src));
-        const size = imageSize(data, pic.png);
-        const scale = Math.min(450 / size.width, 300 / size.height);
-        children.push(new Paragraph({ alignment: AlignmentType.CENTER, spacing: { before: 120 }, keepNext: true, children: [new ImageRun({ type: pic.png ? 'png' : 'jpg', data, transformation: { width: Math.round(size.width * scale), height: Math.round(size.height * scale) }, altText: { title: pic.caption, description: pic.caption, name: block.id } })] }));
-        children.push(new Paragraph({ alignment: AlignmentType.CENTER, spacing: { after: 200 }, children: [run(`${block.id} · ${pic.caption}`, { size: 17, color: C.muted, italics: true })] }));
-      } else children.push(spacer());
+      if (block.link) rows.push(['Learn more', block.link]);
+      children.push(kv(rows));
+      children.push(spacer());
     } else if (block.t === 'images') {
       const items = block.items.filter((i) => existsSync(join(reportDir, i.src)));
       if (!items.length) continue;

package/src/export/model.mjs

@@ -12,6 +12,7 @@
  *         { t: 'table', head, rows, widths, tone? } · { t: 'kv', rows } · { t: 'finding', ... }
  *         { t: 'images', items: [{ src, caption, width, height }] } · { t: 'break' }
  */
+import { elementsOf, explain } from '../core/explain.mjs';
 import { AREAS, SEVERITY_ORDER } from '../core/rules.mjs';
 
 export const SEVERITY_TEXT = {
@@ -31,13 +32,15 @@ const plural = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`;
 const date = (ms) => new Date(ms).toLocaleDateString('en-GB', { day: 'numeric', month: 'long', year: 'numeric' });
 const time = (ms) => new Date(ms).toLocaleTimeString('en-GB', { hour: '2-digit', minute: '2-digit' });
 
-function stepsFor(f, pages) {
+export function stepsFor(f, pages) {
   const page = String(f.page);
   const signedIn = pages.find((p) => p.key === page)?.signedIn;
   const screen = [f.evidenceView, ...(f.views ?? [])].map((v) => String(v ?? '').match(/^([^(,·]+?)\s*\((\d+) px\)/)).find(Boolean);
   if (page.startsWith('/')) {
     const steps = [`${signedIn ? 'Sign in as the test user, then open' : 'Open'} ${page}${screen ? ` on a ${screen[1].trim().toLowerCase()} screen (${screen[2]} px wide)` : ''}.`];
     if (f.ruleId === 'focus-not-visible' || f.ruleId === 'keyboard-trap') steps.push('Press Tab to move through the page.');
+    if (/^sso-cancel/.test(f.ruleId)) steps.push('This is the page the provider returns to. Add ?error=access_denied to its address (what Google or UAE PASS send when the user presses Cancel) and open it.');
+    else if (/^sso-|^uaepass-/.test(f.ruleId)) steps.push('Click the sign-in button named under Actual, and look at the address it opens (the browser address bar, or DevTools > Network).');
     if (/when-api-fails/.test(f.ruleId)) steps.push('In the browser developer tools, block the API requests (Network > right-click > Block request URL), then reload.');
     if (f.ruleId === 'horizontal-overflow') steps.push('Scroll sideways: the page moves left and right.');
     if (/^a11y-/.test(f.ruleId)) steps.push('Run an accessibility checker on the page (axe DevTools or Lighthouse > Accessibility) to see the same result.');
@@ -177,23 +180,26 @@ export function buildDocument(report, { version = '', settings = {} } = {}) {
       b.push({ t: 'h2', text: `${severity[0].toUpperCase()}${severity.slice(1)} (${group.length})` });
       b.push({ t: 'p', text: SEVERITY_TEXT[severity], muted: true });
       for (const f of group) {
+        const x = explain(f);
+        const elements = elementsOf(f);
+        const actualSrc = f.evidenceZoom ?? f.evidence;
+        const expectedSrc = f.expectedZoom ?? f.expected;
         b.push({
           t: 'finding',
           id: id(findings.indexOf(f)),
           title: f.title,
           severity: f.severity,
+          what: x.what,
+          actual: { src: actualSrc ?? (f.ruleId === 'visual-change' && f.link ? f.link : ''), png: !actualSrc && f.ruleId === 'visual-change', text: f.detail && !/^a11y-/.test(f.ruleId) ? f.detail : x.what },
+          expected: { src: expectedSrc ?? '', text: x.expected || 'This problem no longer appears when the check runs again.' },
           rows: [
-            ['Area', AREAS[f.area] ?? f.area],
-            ['Where', String(f.page)],
-            ...(f.views?.length ? [['Seen on', f.views.join(', ')]] : []),
-            ...(f.detail ? [['What was found', f.detail]] : []),
+            ['Where', `${f.page}${f.views?.length ? ` · ${f.views.join(', ')}` : ''}`],
+            ...(elements.length ? [['Elements', elements.map((e) => `${e.name ? `${e.name} ` : ''}${e.selector}`).join('\n')]] : []),
+            ...(x.who ? [['Affects', x.who]] : []),
+            ...(!(elements.length && (f.items ?? []).length <= elements.length && !/^a11y-/.test(f.ruleId)) && (f.items ?? []).length ? [['Details', f.items.slice(0, 8).join('\n')]] : []),
+            ['See it', stepsFor(f, pages).map((step, i) => `${i + 1}. ${step}`).join('\n')],
+            ...(x.ref ? [['Reference', x.ref]] : []),
           ],
-          evidence: (f.items ?? []).slice(0, 8),
-          picture: f.evidence ? { src: f.evidence, caption: `Evidence${f.evidenceView ? ` · ${f.evidenceView}` : ''}${f.selectors?.length ? ': the problem is outlined in red' : ''}` } : f.ruleId === 'visual-change' && f.link ? { src: f.link, caption: 'Changed areas in red', png: true } : null,
-          selectors: (f.selectors ?? []).slice(0, 6),
-          steps: stepsFor(f, pages),
-          fix: f.fix,
-          verify: 'Run the check again (npm run go-live): this finding must be gone.',
           link: /^https?:/.test(f.link ?? '') ? f.link : '',
         });
       }

package/src/export/pdf.mjs

@@ -60,13 +60,16 @@ export function documentHtml(doc, reportDir) {
       );
     } else if (block.t === 'finding') {
       const row = (k, v) => `<tr><th>${esc(k)}</th><td>${v}</td></tr>`;
-      const pic = block.picture ? dataUri(reportDir, block.picture.src, block.picture.png) : '';
+      const pic = (part, png) => (part.src ? dataUri(reportDir, part.src, png) : '');
+      const actualPic = pic(block.actual, block.actual.png);
+      const expectedPic = pic(block.expected, false);
+      const fmt = (k, v) => (k === 'See it' ? `<ol>${v.split('\n').map((x) => `<li>${esc(x.replace(/^\d+\.\s*/, ''))}</li>`).join('')}</ol>` : k === 'Elements' || k === 'Details' ? v.split('\n').map((x) => `<code>${esc(x)}</code>`).join('<br>') : esc(v));
       body.push(
-        `<section class="finding" style="--c:${SEV[block.severity]}"><h3><span class="fid">${esc(block.id)}</span> ${esc(block.title)} <span class="chip">${esc(block.severity)}</span></h3><table class="kv">${block.rows.map(([k, v]) => row(k, esc(v))).join('')}${
-          block.selectors.length ? row('Elements', block.selectors.map((x) => `<code>${esc(x)}</code>`).join('<br>')) : ''
-        }${row('Steps to see it', `<ol>${block.steps.map((x) => `<li>${esc(x)}</li>`).join('')}</ol>`)}${block.evidence.length ? row('Evidence', `<ul>${block.evidence.map((e) => `<li><code>${esc(e)}</code></li>`).join('')}</ul>`) : ''}${row('How to fix', esc(block.fix))}${row('Check the fix', esc(block.verify))}${block.link ? row('Reference', esc(block.link)) : ''}</table>${
-          pic ? `<figure class="evidence"><img src="${pic}" alt="${esc(block.picture.caption)}"><figcaption>${esc(block.id)} · ${esc(block.picture.caption)}</figcaption></figure>` : ''
-        }</section>`,
+        `<section class="finding" style="--c:${SEV[block.severity]}"><h3><span class="fid">${esc(block.id)}</span> ${esc(block.title)} <span class="chip">${esc(block.severity)}</span></h3>
+        <p class="what">${esc(block.what)}</p>
+        <div class="compare"><div class="side actual"><div class="lab"><b>ACTUAL</b> how it is now</div>${actualPic ? `<img src="${actualPic}" alt="Actual">` : ''}<p>${esc(block.actual.text)}</p></div>
+        <div class="side expected"><div class="lab"><b>EXPECTED</b> how it should be</div>${expectedPic ? `<img src="${expectedPic}" alt="Expected">` : actualPic ? '<div class="tick">✓</div>' : ''}<p>${esc(block.expected.text)}</p></div></div>
+        <table class="kv">${block.rows.map(([k, v]) => row(k, fmt(k, v))).join('')}${block.link ? row('Learn more', esc(block.link)) : ''}</table></section>`,
       );
     } else if (block.t === 'images') {
       const figures = block.items
@@ -104,10 +107,13 @@ tr{break-inside:avoid}thead{display:table-header-group}
 .good{color:#1a7f45;font-weight:700}.warn{color:#a15c00;font-weight:700}.bad{color:#b3261e;font-weight:700}.sev{font-weight:700;text-transform:capitalize}
 .count{font-size:20pt;font-weight:700;text-align:center}
 .verdict{border-left:5pt solid var(--v);background:#f4f6f9;padding:8pt 10pt;margin:6pt 0 10pt}.verdict strong{color:var(--v);font-size:14pt;margin-right:6pt}
-.finding{margin-bottom:10pt}.finding table{break-inside:avoid}.finding ol{margin:0;padding-left:14pt}
+.finding{margin-bottom:12pt}.what{margin:2pt 0 6pt}
+.compare{display:flex;gap:8pt;margin-bottom:6pt;break-inside:avoid}.side{flex:1;border:0.6pt solid #d9dde3;border-radius:4pt;padding:5pt;background:#f7f8fa}.side.actual{border-top:3pt solid #b3261e}.side.expected{border-top:3pt solid #1a7f45}
+.side .lab{font-size:8pt;color:#5d6672;margin-bottom:4pt}.side.actual b{color:#b3261e}.side.expected b{color:#1a7f45}.side img{display:block;max-width:100%;max-height:190pt;margin:0 auto;border:0.6pt solid #d9dde3;background:#fff}.side p{margin:4pt 0 0;font-size:9pt}.tick{text-align:center;font-size:30pt;color:#1a7f45;padding:20pt 0}.finding table{break-inside:avoid}.finding ol{margin:0;padding-left:14pt}
 figure.evidence{margin:4pt 0 0;break-inside:avoid}figure.evidence img{max-width:100%;max-height:300pt;border:0.6pt solid #d9dde3}.finding h3{border-left:3pt solid var(--c);padding-left:6pt}.fid{color:#5d6672;font-weight:400}
 .chip{font-size:8pt;color:#fff;background:var(--c);padding:1pt 5pt;border-radius:8pt;text-transform:uppercase;vertical-align:middle}
 code{font:8.5pt/1.35 Consolas,"DejaVu Sans Mono",monospace;word-break:break-word}
+pre{margin:0;font:8pt/1.4 Consolas,"DejaVu Sans Mono",monospace;white-space:pre-wrap;background:#f4f6f9;padding:4pt 6pt;border-radius:3pt}
 .figs{display:flex;gap:10pt;align-items:flex-start;break-inside:avoid;margin-bottom:8pt}
 figure{margin:0;flex:1;text-align:center}figure img{max-width:100%;max-height:230pt;border:0.6pt solid #d9dde3}figcaption{font-size:8.5pt;color:#5d6672}
 .break{break-after:page}

package/src/report/report.mjs

@@ -6,7 +6,9 @@
  */
 import { writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { elementsOf, explain } from '../core/explain.mjs';
 import { AREAS, SEVERITY_ORDER, rule } from '../core/rules.mjs';
+import { stepsFor } from '../export/model.mjs';
 
 const WEIGHT = { blocker: 40, major: 15, minor: 5, info: 0 };
 
@@ -20,7 +22,7 @@ export function mergeFindings(raw) {
     const existing = merged.get(key);
     if (existing) {
       if (f.view && !existing.views.includes(f.view)) existing.views.push(f.view);
-      if (!existing.evidence && f.evidence) Object.assign(existing, { evidence: f.evidence, evidenceView: f.evidenceView, selectors: f.selectors ?? existing.selectors });
+      if (!existing.evidence && f.evidence) Object.assign(existing, { evidence: f.evidence, evidenceZoom: f.evidenceZoom, expected: f.expected, expectedZoom: f.expectedZoom, evidenceView: f.evidenceView, selectors: f.selectors ?? existing.selectors });
       if (SEVERITY_ORDER.indexOf(severity) < SEVERITY_ORDER.indexOf(existing.severity)) existing.severity = severity;
     } else {
       merged.set(key, { ...f, area: r.area, title: r.title, fix: r.fix, severity, views: f.view ? [f.view] : [] });
@@ -51,16 +53,41 @@ const VERDICT_TEXT = {
   'NOT READY': 'Not ready: fix the blocking problems below first.',
 };
 
-function findingHtml(f) {
+/**
+ * One finding, shown so a developer understands it at a glance: one sentence on what is wrong,
+ * the Actual picture (problem in red) next to the Expected picture (corrected, in green), where it
+ * is, who it affects, and how to see it yourself.
+ */
+function findingHtml(f, pages = []) {
+  const x = explain(f);
+  const elements = elementsOf(f);
+  const steps = stepsFor(f, pages);
+  const details = elements.length && (f.items ?? []).length <= elements.length && !/^a11y-/.test(f.ruleId) ? [] : f.items ?? [];
+  const actualSrc = f.evidenceZoom ?? f.evidence;
+  const expectedSrc = f.expectedZoom ?? f.expected;
+  const picture = (src, full, alt) => `<a href="${esc(full ?? src)}" target="_blank"><img loading="lazy" src="${esc(src)}" alt="${esc(alt)}"></a>`;
+  const visualChange = f.ruleId === 'visual-change' && f.link ? f.link : '';
+  const compare = actualSrc || visualChange
+    ? `<div class="compare">
+      <figure class="actual"><figcaption><span class="tag bad">Actual</span> how it is now</figcaption>${actualSrc ? picture(actualSrc, f.evidence, `Actual: ${f.title}`) : picture(visualChange, visualChange, 'Changed areas in red')}<p>${esc(f.detail && !/^a11y-/.test(f.ruleId) ? f.detail : x.what)}</p></figure>
+      <figure class="expected"><figcaption><span class="tag good">Expected</span> how it should be</figcaption>${expectedSrc ? picture(expectedSrc, f.expected, `Expected: ${f.title}`) : '<div class="nopic">✓</div>'}<p>${esc(x.expected || 'This problem no longer appears when the check runs again.')}</p></figure>
+    </div>`
+    : `<div class="compare text">
+      <div class="actual"><span class="tag bad">Actual</span><p>${esc(f.detail || x.what)}</p>${details.length ? `<ul class="items">${details.map((i) => `<li><code>${esc(i)}</code></li>`).join('')}</ul>` : ''}</div>
+      <div class="expected"><span class="tag good">Expected</span><p>${esc(x.expected || 'This problem no longer appears when the check runs again.')}</p></div>
+    </div>`;
   return `<details class="finding sev-${f.severity}" data-sev="${f.severity}" data-area="${f.area}" ${f.severity === 'blocker' ? 'open' : ''}>
   <summary><span class="chip ${f.severity}">${f.severity}</span><span class="ftitle">${esc(f.title)}</span><span class="where">${esc(f.page)}</span></summary>
   <div class="fbody">
-    ${f.detail ? `<p class="detail">${esc(f.detail)}</p>` : ''}
-    ${f.items?.length ? `<ul class="items">${f.items.map((i) => `<li><code>${esc(i)}</code></li>`).join('')}</ul>` : ''}
-    ${f.views.length ? `<p class="views">Seen on: ${f.views.map(esc).join(' · ')}</p>` : ''}
-    ${f.selectors?.length ? `<p class="views">Elements: ${f.selectors.slice(0, 6).map((x) => `<code>${esc(x)}</code>`).join(' · ')}</p>` : ''}
-    ${f.evidence ? `<a class="evidence" href="${esc(f.evidence)}" target="_blank"><img loading="lazy" src="${esc(f.evidence)}" alt="${esc(`Evidence: ${f.title}`)}"><span>Evidence${f.evidenceView ? ` · ${esc(f.evidenceView)}` : ''}: the problem is outlined in red. Click to enlarge.</span></a>` : ''}
-    <p class="fix"><strong>How to fix:</strong> ${esc(f.fix)}${f.link ? ` <a href="${esc(f.link)}" target="_blank" rel="noopener">Details</a>` : ''}</p>
+    <p class="what">${esc(x.what)}</p>
+    ${compare}
+    <dl class="facts">
+      <dt>Where</dt><dd><strong>${esc(f.page)}</strong>${f.views.length ? ` · ${f.views.map(esc).join(', ')}` : ''}${elements.length ? `<ul class="elements">${elements.map((e) => `<li>${e.name ? `${esc(e.name)} ` : ''}<code>${esc(e.selector)}</code></li>`).join('')}</ul>` : ''}</dd>
+      ${x.who ? `<dt>Affects</dt><dd>${esc(x.who)}</dd>` : ''}
+      ${details.length && (actualSrc || visualChange) ? `<dt>Details</dt><dd><ul class="items">${details.map((i) => `<li><code>${esc(i)}</code></li>`).join('')}</ul></dd>` : ''}
+      <dt>See it</dt><dd><ol class="steps">${steps.map((step) => `<li>${esc(step)}</li>`).join('')}</ol></dd>
+      ${x.ref || f.link ? `<dt>Reference</dt><dd>${x.ref ? esc(x.ref) : ''}${f.link && /^https?:/.test(f.link) ? `${x.ref ? ' · ' : ''}<a href="${esc(f.link)}" target="_blank" rel="noopener">Learn more</a>` : ''}</dd>` : ''}
+    </dl>
   </div>
 </details>`;
 }
@@ -210,7 +237,17 @@ h1{font-size:26px;margin:0 0 4px}h2{font-size:19px;margin:36px 0 12px}h3{font-si
 .finding{background:var(--card);border:1px solid var(--line);border-left:4px solid var(--c);border-radius:10px;margin:8px 0}
 .sev-blocker{--c:var(--blocker)}.sev-major{--c:var(--major)}.sev-minor{--c:var(--minor)}.sev-info{--c:var(--info)}
 .finding summary{cursor:pointer;padding:10px 14px;display:flex;gap:10px;align-items:center;flex-wrap:wrap}.ftitle{font-weight:600}.where{color:var(--muted);font-size:13px;margin-left:auto;word-break:break-all}
-.fbody{padding:0 14px 12px}.evidence{display:block;margin:10px 0;text-decoration:none;color:var(--muted);font-size:12px}.evidence img{display:block;max-width:100%;max-height:420px;border:1px solid var(--line);border-radius:8px;margin-bottom:4px}.detail{margin:4px 0}.items{margin:6px 0;padding-left:18px}.items code{font-size:12.5px;word-break:break-word}.views{color:var(--muted);font-size:13px;margin:6px 0}.fix{margin:8px 0 0}
+.fbody{padding:2px 16px 16px}
+.what{margin:2px 0 12px;font-size:15px}
+.compare{display:grid;grid-template-columns:1fr 1fr;gap:14px;margin-bottom:14px}@media(max-width:820px){.compare{grid-template-columns:1fr}}
+.compare figure,.compare>div{min-width:0;margin:0;border:1px solid var(--line);border-radius:10px;padding:10px;background:var(--bg)}
+.compare .actual{border-top:4px solid var(--bad)}.compare .expected{border-top:4px solid var(--good)}
+.compare figcaption{font-size:13px;color:var(--muted);margin-bottom:8px}.compare img{display:block;width:100%;max-height:420px;object-fit:contain;object-position:top center;border-radius:6px;background:#fff;border:1px solid var(--line)}
+.compare p{margin:8px 0 0;font-size:14px}.compare .nopic{display:grid;place-items:center;height:120px;font-size:42px;color:var(--good)}
+.tag{display:inline-block;font-size:11px;font-weight:700;letter-spacing:.05em;text-transform:uppercase;padding:2px 8px;border-radius:999px;color:#fff;margin-right:6px}.tag.bad{background:var(--bad)}.tag.good{background:var(--good)}
+.compare.text p{margin-top:6px}.compare code,.facts code{word-break:break-all;white-space:pre-wrap}
+.facts{display:grid;grid-template-columns:110px 1fr;gap:6px 14px;margin:0;font-size:14px}.facts dt{color:var(--muted);font-weight:600}.facts dd{margin:0}
+.elements,.steps{margin:4px 0 0;padding-left:20px}.elements code{font-size:12.5px;word-break:break-all}
 a{color:var(--accent)}
 table{width:100%;border-collapse:collapse;background:var(--card);border:1px solid var(--line);border-radius:10px;overflow:hidden;font-size:14px}th,td{padding:8px 10px;border-bottom:1px solid var(--line);text-align:left;vertical-align:top}th{font-size:12px;color:var(--muted);text-transform:uppercase}
 td.good{color:var(--good);font-weight:700}td.warn{color:var(--warn);font-weight:700}td.bad{color:var(--bad);font-weight:700}
@@ -244,7 +281,7 @@ ul.plain{padding-left:18px}.empty{color:var(--muted)}
 <div class="filters" role="group" aria-label="Filter by severity">
   <button data-filter-sev="all" class="active">All</button>${SEVERITY_ORDER.map((s) => `<button data-filter-sev="${s}">${s} (${summary.counts[s]})</button>`).join('')}
 </div>
-<div id="findings">${findings.length ? findings.map(findingHtml).join('') : '<p class="empty">No problems found.</p>'}</div>
+<div id="findings">${findings.length ? findings.map((f) => findingHtml(f, pages)).join('') : '<p class="empty">No problems found.</p>'}</div>
 
 ${apiHtml}