frontend-go-live-check 1.3.0 → 1.4.1

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 1.4.1
+
+- Problems are grouped **by type** (Functionality, Design, Accessibility, Performance, Sign-in, APIs, Security, SEO, Code) in the HTML report, the PDF and the Word file, most serious first in each group.
+- Every problem has **Steps to reproduce** and **Test again**: the shortest command that checks only that problem after the fix.
+- README: new *How it works* and *Built with* sections.
+
+## 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.

package/README.md

@@ -20,9 +20,11 @@
   <a href="#quick-start">Quick start</a> ·
   <a href="#sign-in-email-google-microsoft-uae-pass">Sign-in</a> ·
   <a href="#what-it-checks">What it checks</a> ·
+  <a href="#how-it-works">How it works</a> ·
   <a href="#the-report">The report</a> ·
   <a href="#pipelines-approve-or-reject-the-merge">Pipelines</a> ·
   <a href="#settings">Settings</a> ·
+  <a href="#built-with">Built with</a> ·
   <a href="#faq">FAQ</a>
 </p>
 
@@ -142,9 +144,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 |
@@ -160,6 +162,24 @@ The report's **What was checked** table says exactly what ran on your project, a
 
 ---
 
+## How it works
+
+```text
+ ① Detect  ──▶  ② Build & start  ──▶  ③ Sign in  ──▶  ④ Find pages  ──▶  ⑤ Test  ──▶  ⑥ Report  ──▶  ⑦ Verdict
+```
+
+| Step | What happens |
+| :-: | --- |
+| **1. Detect** | Reads `package.json`: the framework, the package manager, the sign-in libraries, and your API file in `api/` |
+| **2. Build & start** | Builds the app and starts it **the way it runs in production**, plus any services you listed (a backend or a mock API) |
+| **3. Sign in** | With the test account, the saved session (`login`) or a test token, so the signed-in pages are tested too |
+| **4. Find pages** | Follows every link, reads your routes in the source code and your `sitemap.xml` |
+| **5. Test** | Opens every page at every screen size in a real browser and runs every check in [What it checks](#what-it-checks); then calls every API endpoint from your Postman or OpenAPI file |
+| **6. Report** | Writes the HTML report with Actual and Expected pictures, plus the PDF, the Word file and the zip |
+| **7. Verdict** | **READY**, **NEEDS ATTENTION** or **NOT READY**; in a pipeline, the run fails on blockers and the merge is rejected |
+
+---
+
 ## Works with
 
 **Next.js** · **React** (Vite, Create React App) · **Vue** · **Nuxt** · **Angular** · **Svelte / SvelteKit** · **Astro** · **Remix / React Router** · **Gatsby** · **Solid** · **Preact** · **Qwik** · **plain HTML**. Anything else, in any language, works with a start command or `--url`.
@@ -195,9 +215,9 @@ The framework and the package manager (npm, pnpm, yarn, bun) are detected. The a
 The report has:
 
 - the **verdict** and a **score per area** (click an area to filter);
-- every problem, with where it is and at which screen sizes;
+- **problems by type**: Functionality, Design, Accessibility, Performance, Sign-in, APIs, Security, SEO, Code, each with its score, worst problems first;
 - the API results, the speed of every page, and the load test;
-- screenshots of every page at every size.
+- screenshots of every page at every size, for the design review.
 
 ### Every problem: Actual next to Expected
 
@@ -206,7 +226,9 @@ Each problem is shown so a developer understands it at a glance, without knowing
 - **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**.
+- **where** (page, screen size, the element by name and CSS selector) and **who it affects**;
+- **steps to reproduce** it yourself;
+- **test again**: the shortest command that checks only this problem after the fix (copy button included), for example `npx frontend-go-live-check --only pages --pages /login --max-pages 1`.
 
 <p align="center">
   <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">
@@ -325,7 +347,7 @@ Everything is optional. `init` writes `go-live-check.config.json`, and your edit
 }
 ```
 
-API tests need no settings when your files are in `api/` ([see API tests](#settings)). Passwords are written as `"$NAME"`. Put their values in `go-live-check.env` (Git ignores it) or in your pipeline's secrets. They are replaced with `‹secret›` in every report.
+API tests need no settings when your files are in `api/` (see *API tests from Postman or OpenAPI* below). Passwords are written as `"$NAME"`. Put their values in `go-live-check.env` (Git ignores it) or in your pipeline's secrets. They are replaced with `‹secret›` in every report.
 
 <details>
 <summary><b>🔐 Sign-in forms that need help</b></summary>
@@ -451,6 +473,28 @@ console.log(summary.verdict); // READY · NEEDS ATTENTION · NOT READY
 
 ---
 
+## Built with
+
+Trusted open-source tools, used by thousands of teams, do the heavy lifting. The checks, the sign-in handling, the layout and content checks and the reports are this package's own code on top of them.
+
+| Job | Tool | What it does here |
+| --- | --- | --- |
+| 🌐 **Real browser** | [Playwright](https://playwright.dev) | Opens every page in Chromium (Firefox and WebKit with `--all-browsers`) at every screen size; clicks, types, uses the keyboard, signs in, takes the screenshots and prints the PDF |
+| ♿ **Accessibility** | [axe-core](https://github.com/dequelabs/axe-core) (`@axe-core/playwright`) | The accessibility rules (WCAG 2.0 / 2.1 / 2.2, A and AA) used by most accessibility tools |
+| ⚡ **Speed and quality** | [Lighthouse](https://developer.chrome.com/docs/lighthouse) | Google's performance, best-practice and SEO scores, as a phone and as a desktop |
+| | [chrome-launcher](https://github.com/GoogleChrome/chrome-launcher) · [puppeteer-core](https://pptr.dev) | Start and control Chrome for Lighthouse, including signed-in pages |
+| 🖼️ **Visual changes** | [pixelmatch](https://github.com/mapbox/pixelmatch) · [pngjs](https://github.com/pngjs/pngjs) | Compare every screenshot with the saved baseline, pixel by pixel, and mark the changes in red |
+| 🧪 **API tests** | [Ajv](https://ajv.js.org) · [ajv-formats](https://github.com/ajv-validator/ajv-formats) | Check every API answer against your OpenAPI or Postman schema, including formats (email, date, URL, ID) |
+| | [Faker](https://fakerjs.dev) | Realistic test data (names, emails, numbers) for the requests that create records |
+| | [yaml](https://eemeli.org/yaml) | Reads OpenAPI files written in YAML |
+| 📄 **Documents** | [docx](https://docx.js.org) | Writes the Word report |
+| | [JSZip](https://stuk.github.io/jszip) | Packs the full report, screenshots, PDF and Word file into one zip |
+| 🛡️ **Dependencies** | `npm audit` (comes with npm) | Known security problems in your project's libraries |
+
+No other services: nothing is uploaded, and no account is needed.
+
+---
+
 ## FAQ
 
 <details>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "frontend-go-live-check",
-  "version": "1.3.0",
+  "version": "1.4.1",
   "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

@@ -301,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

@@ -23,8 +23,21 @@ function drawOutlines([selectors, label, screenEdge, colour = '#e01e1e']) {
     }
     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 ${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');
@@ -51,7 +64,7 @@ function drawOutlines([selectors, label, screenEdge, colour = '#e01e1e']) {
   // Show the first problem element in the middle of the screen.
   if (found[0] && !screenEdge) found[0].scrollIntoView({ block: 'center', inline: 'nearest' });
   // Where the outlined elements are on screen now (for the close-up picture).
-  const rects = found.map((el) => el.getBoundingClientRect());
+  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;
@@ -106,7 +119,7 @@ export async function captureEvidence(page, reportDir, { selectors = [], label =
  * 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', 'small-text', 'focus-not-visible', 'mouse-only-control', 'rtl-missing', 'color-contrast', 'target-size']);
+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]) {
@@ -155,6 +168,17 @@ function applyExpected([kind, selectors]) {
       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') {

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

@@ -40,6 +40,13 @@ export const EXPLAIN = {
   '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">' },
@@ -108,6 +115,7 @@ export const EXPLAIN = {
   '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-login-failed': { what: 'The API tests could not sign in with a test user, so the tests that need a signed-in user did not run.', who: 'Every user of the app if the sign-in API itself is broken; otherwise check the test user settings.' },
   '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.' },
@@ -170,6 +178,13 @@ export const EXPECTED = {
   '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.',
@@ -224,6 +239,7 @@ export const EXPECTED = {
   '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-login-failed': 'The test user signs in to the API and gets a token, so every signed-in API test can run.',
   '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.',

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

@@ -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, mono: k === 'Elements' || k === 'Details', fill: undefined })] })),
+    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' || k === 'Evidence' || k === 'Test again after the fix', fill: undefined })] })),
   });
 }
 

package/src/export/model.mjs

@@ -36,6 +36,10 @@ 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 (/^api-/.test(f.ruleId ?? '') || /^\/api\b/.test(page)) {
+    if (f.ruleId === 'api-login-failed') return ['Send the sign-in request of the API (for example POST /api/login) with the test user named above and its password from go-live-check.env.', 'Look at the answer: it should be 200 with a token.'];
+    return ['Send the request in the curl command shown above, with a token of the test user named there.', 'Compare the status and the answer with what is Expected.'];
+  }
   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.');
@@ -47,12 +51,40 @@ export function stepsFor(f, pages) {
     if (f.selectors?.length) steps.push('Find the outlined element(s) with the selectors under "Elements" (DevTools > Elements > Ctrl/Cmd+F).');
     return steps;
   }
-  if (/^(GET|POST|PUT|PATCH|DELETE) /.test(page)) return ['Send the request shown under Evidence (curl), with a token of the test user named there.'];
-  return ['See the list under Evidence.'];
+  if (/^(GET|POST|PUT|PATCH|DELETE) /.test(page)) return ['Send the request in the curl command shown above, with a token of the test user named there.'];
+  return ['See the list shown above.'];
+}
+
+/**
+ * The shortest run that checks this one problem again after the fix (only its kind of check,
+ * only its page where possible).
+ */
+export function retestFor(f) {
+  const cmd = 'npx frontend-go-live-check';
+  const page = String(f.page ?? '');
+  const onPage = page.startsWith('/') && !/^\/api\b/.test(page) ? ` --pages ${page} --max-pages 1` : '';
+  const id = f.ruleId ?? '';
+  if (f.area === 'api' || /^api-/.test(id)) return `${cmd} --api-only`;
+  if (f.area === 'code') return `${cmd} --only code`;
+  if (f.area === 'security') return `${cmd} --only pages,security${onPage}`;
+  if (/when-api-fails$/.test(id)) return `${cmd} --only pages,resilience${onPage}`;
+  if (f.area === 'auth') return `${cmd} --only pages,auth`;
+  if (/^(perf-score|slow-lcp|layout-shift|blocking-time|large-javascript)/.test(id)) return `${cmd} --only pages,lighthouse${onPage}`;
+  if (/under-load$/.test(id)) return `${cmd} --only pages,load`;
+  if (id === 'visual-change') return `${cmd} --only pages${onPage}   (if the change is intended: ${cmd} --update-baseline)`;
+  return `${cmd} --only pages${onPage}`;
+}
+
+/** Findings grouped by type of problem (design, accessibility, APIs, security…), worst first in each. */
+export function byArea(findings) {
+  const order = Object.keys(AREAS);
+  const rank = (f) => SEVERITY_ORDER.indexOf(f.severity);
+  return [...findings].sort((a, b) => order.indexOf(a.area) - order.indexOf(b.area) || rank(a) - rank(b));
 }
 
 export function buildDocument(report, { version = '', settings = {} } = {}) {
-  const { meta, summary, findings = [], pages = [], lighthouse = { results: [] }, api, coverage = [], visual, requests, load } = report;
+  const { meta, summary, pages = [], lighthouse = { results: [] }, api, coverage = [], visual, requests, load } = report;
+  const findings = byArea(report.findings ?? []);
   const id = (i) => `GLC-${String(i + 1).padStart(3, '0')}`;
   const counts = summary.counts;
   const actionable = findings.filter((f) => f.severity !== 'info');
@@ -99,7 +131,7 @@ export function buildDocument(report, { version = '', settings = {} } = {}) {
     text: `${meta.project} (${meta.framework}) was tested on ${date(meta.finishedAt)}${meta.apiOnly ? '' : `: ${plural(pages.length, 'page')} at ${meta.viewports.length} screen sizes (${meta.viewports.join(', ')})`}${api ? `${meta.apiOnly ? ':' : ', and'} ${plural(api.endpoints.length, 'API endpoint')} with ${api.cases} test cases` : ''}. The test found ${plural(counts.blocker, 'blocking problem')}, ${plural(counts.major, 'major problem')} and ${plural(counts.minor, 'minor problem')}${counts.info ? `, plus ${counts.info} item${counts.info === 1 ? '' : 's'} for information` : ''}.`,
   });
   b.push({ t: 'table', head: ['Blocker', 'Major', 'Minor', 'Info'], widths: [25, 25, 25, 25], rows: [[counts.blocker, counts.major, counts.minor, counts.info].map(String)], tone: 'counts' });
-  const top = findings.filter((f) => f.severity === 'blocker' || f.severity === 'major').slice(0, 10);
+  const top = findings.filter((f) => f.severity === 'blocker' || f.severity === 'major').sort((a, c) => SEVERITY_ORDER.indexOf(a.severity) - SEVERITY_ORDER.indexOf(c.severity)).slice(0, 10);
   if (top.length) {
     b.push({ t: 'h3', text: 'Most important problems' });
     b.push({ t: 'bullets', items: top.map((f) => `${id(findings.indexOf(f))} · ${f.severity.toUpperCase()} · ${f.title} (${f.page})`) });
@@ -159,7 +191,7 @@ export function buildDocument(report, { version = '', settings = {} } = {}) {
   b.push({ t: 'h1', text: 'Findings' });
   if (!findings.length) b.push({ t: 'p', text: 'No problems were found.' });
   else {
-    b.push({ t: 'p', text: `${plural(findings.length, 'finding')}, most serious first. The same problem seen at several screen sizes is listed once.` });
+    b.push({ t: 'p', text: `${plural(findings.length, 'finding')}, grouped by type of problem (design, accessibility, APIs, security…), most serious first in each group. The same problem seen at several screen sizes is listed once.` });
     b.push({ t: 'table', head: ['ID', 'Severity', 'Problem', 'Where'], widths: [12, 13, 47, 28], rows: findings.map((f, i) => [id(i), cap(f.severity), f.title, String(f.page)]), tone: 'severity' });
     const byPage = new Map();
     actionable.forEach((f) => {
@@ -174,11 +206,12 @@ export function buildDocument(report, { version = '', settings = {} } = {}) {
       b.push({ t: 'p', text: 'Use this to share the work: each row lists the findings to fix in one place.', muted: true });
       b.push({ t: 'table', head: ['Page or endpoint', 'Blocker', 'Major', 'Minor', 'Findings'], widths: [34, 11, 11, 11, 33], rows: [...byPage].sort((a, b) => b[1].blocker - a[1].blocker || b[1].major - a[1].major).map(([k, r]) => [k, String(r.blocker), String(r.major), String(r.minor), r.ids.join(', ')]) });
     }
-    for (const severity of SEVERITY_ORDER) {
-      const group = findings.filter((f) => f.severity === severity);
+    for (const [areaId, areaName] of Object.entries(AREAS)) {
+      const group = findings.filter((f) => f.area === areaId);
       if (!group.length) continue;
-      b.push({ t: 'h2', text: `${severity[0].toUpperCase()}${severity.slice(1)} (${group.length})` });
-      b.push({ t: 'p', text: SEVERITY_TEXT[severity], muted: true });
+      const parts = SEVERITY_ORDER.map((sev) => [sev, group.filter((f) => f.severity === sev).length]).filter(([, n]) => n).map(([sev, n]) => `${n} ${sev}`);
+      b.push({ t: 'h2', text: `${areaName} (${group.length})` });
+      b.push({ t: 'p', text: parts.join(' · '), muted: true });
       for (const f of group) {
         const x = explain(f);
         const elements = elementsOf(f);
@@ -190,14 +223,15 @@ export function buildDocument(report, { version = '', settings = {} } = {}) {
           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 },
+          actual: { src: actualSrc ?? (f.ruleId === 'visual-change' && f.link ? f.link : ''), png: !actualSrc && f.ruleId === 'visual-change', text: (!/^a11y-/.test(f.ruleId) && (f.detail || ((f.items ?? []).length === 1 ? f.items[0] : ''))) || x.what },
           expected: { src: expectedSrc ?? '', text: x.expected || 'This problem no longer appears when the check runs again.' },
           rows: [
             ['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')],
+            ...(!(elements.length && (f.items ?? []).length <= elements.length && !/^a11y-/.test(f.ruleId)) && (f.items ?? []).length ? [['Evidence', f.items.slice(0, 8).join('\n')]] : []),
+            ['Steps to reproduce', stepsFor(f, pages).map((step, i) => `${i + 1}. ${step}`).join('\n')],
+            ['Test again after the fix', retestFor(f)],
             ...(x.ref ? [['Reference', x.ref]] : []),
           ],
           link: /^https?:/.test(f.link ?? '') ? f.link : '',

package/src/export/pdf.mjs

@@ -63,7 +63,7 @@ export function documentHtml(doc, reportDir) {
       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));
+      const fmt = (k, v) => (k === 'See it' || k === 'Steps to reproduce' ? `<ol>${v.split('\n').map((x) => `<li>${esc(x.replace(/^\d+\.\s*/, ''))}</li>`).join('')}</ol>` : k === 'Elements' || k === 'Details' || k === 'Evidence' ? v.split('\n').map((x) => `<code>${esc(x)}</code>`).join('<br>') : k === 'Test again after the fix' ? `<code class="cmd">${esc(v)}</code>` : 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>
         <p class="what">${esc(block.what)}</p>

package/src/report/report.mjs

@@ -8,7 +8,7 @@ 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';
+import { byArea, retestFor, stepsFor } from '../export/model.mjs';
 
 const WEIGHT = { blocker: 40, major: 15, minor: 5, info: 0 };
 
@@ -69,7 +69,7 @@ function findingHtml(f, pages = []) {
   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="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((!/^a11y-/.test(f.ruleId) && (f.detail || ((f.items ?? []).length === 1 ? f.items[0] : ''))) || 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">
@@ -82,10 +82,11 @@ function findingHtml(f, pages = []) {
     <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>
+      <dt>Where</dt><dd><strong>${pages.some((p) => p.key === f.page) ? `<a href="#page-${esc(String(f.page).replace(/[^\w-]/g, '_'))}" onclick="document.getElementById(this.hash.slice(1)).open=true">${esc(f.page)}</a>` : 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>
+      ${details.length && (actualSrc || visualChange) ? `<dt>Evidence</dt><dd><ul class="items">${details.map((i) => `<li><code>${esc(i)}</code></li>`).join('')}</ul></dd>` : ''}
+      <dt>Steps to reproduce</dt><dd><ol class="steps">${steps.map((step) => `<li>${esc(step)}</li>`).join('')}</ol></dd>
+      <dt>Test again</dt><dd><div class="retest"><code>${esc(retestFor(f))}</code><button type="button" class="copy" onclick="navigator.clipboard?.writeText(this.previousElementSibling.textContent.split('   (')[0]);this.textContent='Copied'">Copy</button></div><small class="muted">After the fix, run this: the problem must be gone.</small></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>
@@ -123,13 +124,30 @@ export function writeReports({ reportDir, meta, findings, summary, pages, lighth
     )
     .join('');
 
+  // Problems grouped by type (design, accessibility, APIs, security…), worst first in each.
+  const ICONS = { functionality: '🧭', responsive: '📱', accessibility: '♿', performance: '⚡', auth: '🔐', api: '🧪', security: '🛡️', seo: '🔎', code: '🧹' };
+  const scoreOf = new Map(summary.areas.map((a) => [a.id, a.score]));
+  const ordered = byArea(findings);
+  const groups = Object.entries(AREAS)
+    .map(([areaId, name]) => [areaId, name, ordered.filter((f) => f.area === areaId)])
+    .filter(([, , list]) => list.length)
+    .map(([areaId, name, list]) => {
+      const score = scoreOf.get(areaId) ?? 100;
+      const band = score >= 90 ? 'good' : score >= 60 ? 'warn' : 'bad';
+      return `<section class="agroup" data-group id="area-${areaId}">
+  <header class="ahead"><span class="aicon" aria-hidden="true">${ICONS[areaId] ?? '•'}</span><h3>${esc(name)}</h3><span class="ascore ${band}">${score}</span><span class="pchips">${SEVERITY_ORDER.map((sev) => {
+        const n = list.filter((f) => f.severity === sev).length;
+        return n ? `<span class="chip ${sev}">${n} ${sev}</span>` : '';
+      }).join('')}</span></header>
+  <div class="plist">${list.map((f) => findingHtml(f, pages)).join('')}</div>
+</section>`;
+    })
+    .join('');
   const gallery = pages
     .map((p) => {
-      const shots = Object.entries(p.shots)
-        .map(([size, src]) => `<figure><a href="${esc(src)}" target="_blank"><img loading="lazy" src="${esc(src)}" alt="${esc(`${p.key} at ${size}`)}"></a><figcaption>${esc(size)}</figcaption></figure>`)
-        .join('');
+      const shots = Object.entries(p.shots ?? {}).map(([size, src]) => `<figure><a href="${esc(src)}" target="_blank"><img loading="lazy" src="${esc(src)}" alt="${esc(`${p.key} at ${size}`)}"></a><figcaption>${esc(size)}</figcaption></figure>`).join('');
       const problems = findings.filter((f) => f.page === p.key && f.severity !== 'info').length;
-      return `<section class="page"><h3>${esc(p.title || p.key)} <code>${esc(p.key)}</code>${problems ? `<span class="pcount">${problems} problem${problems === 1 ? '' : 's'}</span>` : '<span class="pok">no problems</span>'}</h3><div class="shots">${shots}</div></section>`;
+      return `<details class="page" id="page-${esc(p.key.replace(/[^\w-]/g, '_'))}"><summary><strong>${esc(p.title || p.key)}</strong> <code>${esc(p.key)}</code> ${problems ? `<span class="pcount">${problems} problem${problems === 1 ? '' : 's'}</span>` : '<span class="pok">no problems</span>'}</summary><div class="shots">${shots}</div></details>`;
     })
     .join('');
 
@@ -162,7 +180,7 @@ export function writeReports({ reportDir, meta, findings, summary, pages, lighth
   if (visual) {
     const changed = visual.results.filter((r) => r.status === 'changed');
     const fresh = visual.results.filter((r) => r.status === 'new' || r.status === 'updated');
-    visualHtml = `<h2>Visual changes</h2>
+    visualHtml = `<h2 id="visual">Visual changes</h2>
 <p class="meta">${visual.updated ? `The baseline was updated with ${fresh.length} picture(s).` : fresh.length === visual.results.length ? `First run: ${fresh.length} picture(s) saved as the baseline in <code>${esc(visual.baselineDir)}</code>. Commit that folder; the next runs show what changed.` : `${visual.results.length - changed.length - fresh.length} picture(s) look the same as the baseline, ${changed.length} changed${fresh.length ? `, ${fresh.length} new` : ''}.`}</p>
 ${changed.length ? `<div class="shots">${changed.map((r) => `<figure><a href="visual/diff/${esc(r.name)}" target="_blank"><img loading="lazy" src="visual/diff/${esc(r.name)}" alt="${esc(`Changes on ${r.page}`)}"></a><figcaption>${esc(r.page)} · ${esc(r.view)} · ${(r.ratio * 100).toFixed(1)}% · <a href="visual/now/${esc(r.name)}" target="_blank">now</a></figcaption></figure>`).join('')}</div>` : ''}`;
   }
@@ -183,7 +201,7 @@ ${changed.length ? `<div class="shots">${changed.map((r) => `<figure><a href="vi
       return `<td>${rows.map((r) => `<span class="${r.ok ? 'pass' : 'fail'}" title="${esc(`${r.kind}: ${r.label}`)}">${r.status}${r.kind === 'other-user' ? '*' : ''} ${r.ok ? '✓' : '✗'}</span>`).join('<br>')}</td>`;
     };
     const notes = (key) => [...new Set(api.results.filter((r) => r.endpoint === key && r.ok === null).map((r) => r.note))].join('; ');
-    apiHtml = `<h2>API tests</h2>
+    apiHtml = `<h2 id="api">API tests</h2>
 <div class="apistats">
   <div><strong>${tested}/${api.endpoints.length}</strong><span>endpoints tested</span></div>
   <div><strong>${api.cases}</strong><span>cases</span></div>
@@ -246,12 +264,26 @@ h1{font-size:26px;margin:0 0 4px}h2{font-size:19px;margin:36px 0 12px}h3{font-si
 .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}
+.facts{display:grid;grid-template-columns:150px 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}
 .tablewrap{overflow-x:auto}
+.agroup{background:var(--card);border:1px solid var(--line);border-radius:14px;padding:14px 16px;margin:14px 0}
+.ahead{display:flex;gap:10px;align-items:center;flex-wrap:wrap}.ahead h3{margin:0;font-size:17px}.aicon{font-size:20px}
+.ascore{font-weight:700;font-size:14px;border-radius:8px;padding:1px 8px;border:1px solid currentColor}.ascore.good{color:var(--good)}.ascore.warn{color:var(--warn)}.ascore.bad{color:var(--bad)}
+.retest{display:flex;gap:8px;align-items:flex-start}.retest code{flex:1;background:var(--bg);border:1px solid var(--line);border-radius:6px;padding:6px 8px;font-size:12.5px}
+.copy{border:1px solid var(--line);background:var(--card);color:var(--ink);border-radius:6px;padding:5px 10px;cursor:pointer;font:inherit;font-size:12px}
+details.page summary{cursor:pointer;display:flex;gap:10px;align-items:center;flex-wrap:wrap}details.page .shots{margin-top:10px}
+.toc{display:flex;gap:6px 18px;flex-wrap:wrap;margin:14px 0 0;font-size:14px}.toc a{text-decoration:none;font-weight:600}
+.pgroup{background:var(--card);border:1px solid var(--line);border-radius:14px;padding:14px 16px;margin:14px 0}
+.phead{display:flex;gap:10px;align-items:center;flex-wrap:wrap}.phead h3{margin:0}.phead code{font-size:15px}
+.pkind{font-size:11px;font-weight:700;text-transform:uppercase;letter-spacing:.06em;color:var(--muted);border:1px solid var(--line);border-radius:6px;padding:1px 6px}
+.pchips{display:flex;gap:6px;flex-wrap:wrap;margin-left:auto}
+.pshots{margin:10px 0 4px}.pshots summary{cursor:pointer;font-size:13px;font-weight:600;color:var(--accent)}.pshots .shots{margin-top:8px}.pshots .shots img{max-height:220px;max-width:200px}
+.plist .finding{background:var(--bg)}.plist{margin-top:8px}
+.pgroup.clean summary{cursor:pointer;display:flex;gap:10px;align-items:center}.cleanpage{margin-top:14px}.cleanpage h3{font-size:14px}
 .page{background:var(--card);border:1px solid var(--line);border-radius:12px;padding:14px;margin:10px 0}.pcount{font-size:12px;color:var(--major);font-weight:600}.pok{font-size:12px;color:var(--good)}
 .shots{display:flex;gap:12px;overflow-x:auto;align-items:flex-start}.shots figure{margin:0;flex:0 0 auto}.shots img{display:block;max-height:340px;max-width:260px;border:1px solid var(--line);border-radius:6px;object-fit:cover;object-position:top}
 figcaption{font-size:12px;color:var(--muted);margin-top:4px}
@@ -274,23 +306,26 @@ ul.plain{padding-left:18px}.empty{color:var(--muted)}
   <div class="counts">${SEVERITY_ORDER.map((s) => `<span class="chip ${s}">${summary.counts[s]} ${s}</span>`).join('')}</div>
 </div>
 
+<nav class="toc" aria-label="Contents"><a href="#problems">Problems by type</a>${pages.length ? '<a href="#pages">Screenshots</a>' : ''}${api ? '<a href="#api">API tests</a>' : ''}${meta.apiOnly ? '' : '<a href="#speed">Speed</a>'}${visual ? '<a href="#visual">Visual changes</a>' : ''}<a href="#checked">What was checked</a></nav>
+
 <h2>Areas</h2>
 <div class="areas">${areaCards}</div>
 
-<h2>Findings</h2>
+<h2 id="problems">Problems by type</h2>
+<p class="meta">Grouped by type of problem, most serious first in each group. Open a problem to see the <b>evidence</b> (Actual next to Expected), the <b>steps to reproduce</b> it, and the command to <b>test it again</b> after the fix.</p>
 <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((f) => findingHtml(f, pages)).join('') : '<p class="empty">No problems found.</p>'}</div>
+<div id="findings">${findings.length ? groups : '<p class="empty">No problems found.</p>'}</div>
 
 ${apiHtml}
 
-${meta.apiOnly ? '' : `<h2>Speed and quality (Lighthouse)</h2>
-${lighthouse.results.length ? `<div class="tablewrap"><table><thead><tr><th>Page</th><th>Device</th><th>Perf.</th><th>Access.</th><th>Best pract.</th><th>SEO</th><th>LCP</th><th>CLS</th><th>TBT</th><th>JS</th><th></th></tr></thead><tbody>${lhRows}</tbody></table></div><p class="meta">Phone = slow 4G and a mid-range phone CPU, as Lighthouse simulates it. Good: LCP under 2.5 s, CLS under 0.1, TBT under 200 ms.</p>` : '<p class="empty">Lighthouse did not run.</p>'}
+${meta.apiOnly || !pages.length ? '' : `<h2 id="pages">Screenshots of every page</h2>
+<p class="meta">Every page at every screen size, as the browser drew it: for the design review. Open a page to see its pictures; click a picture for full size.</p>
+${gallery}`}
 
-<h2>Pages and screenshots (design review)</h2>
-<p class="meta">Every page at every screen size, as the browser drew it. Look through them for anything that looks wrong; click a picture for full size.</p>
-${gallery || '<p class="empty">No pages were opened.</p>'}`}
+${meta.apiOnly ? '' : `<h2 id="speed">Speed and quality (Lighthouse)</h2>
+${lighthouse.results.length ? `<div class="tablewrap"><table><thead><tr><th>Page</th><th>Device</th><th>Perf.</th><th>Access.</th><th>Best pract.</th><th>SEO</th><th>LCP</th><th>CLS</th><th>TBT</th><th>JS</th><th></th></tr></thead><tbody>${lhRows}</tbody></table></div><p class="meta">Phone = slow 4G and a mid-range phone CPU, as Lighthouse simulates it. Good: LCP under 2.5 s, CLS under 0.1, TBT under 200 ms.</p>` : '<p class="empty">Lighthouse did not run.</p>'}`}
 
 ${requestsHtml}
 
@@ -302,15 +337,15 @@ ${perfRows ? `<h2>Every page: size and speed</h2>
 <div class="tablewrap"><table><thead><tr><th>Page</th><th>Downloaded</th><th>JavaScript</th><th>Images</th><th>Requests</th><th>Load</th><th>LCP</th><th>CLS</th></tr></thead><tbody>${perfRows}</tbody></table></div>
 <p class="meta">Measured in the test browser on this computer (no network slow-down); red = over the budget in the settings.</p>` : ''}
 
-<h2>What was checked</h2>
+<h2 id="checked">What was checked</h2>
 ${coverageHtml}
-<p class="meta">Not covered by an automatic check: ${meta.apiOnly ? '' : 'whether the design matches what was intended (use the screenshots above), '}business rules (what each ${meta.apiOnly ? 'endpoint' : 'page'} should do beyond its documented shape), load under many users, and an in-depth penetration test. ${esc(meta.steps.join(' · '))}</p>
+<p class="meta">Not covered by an automatic check: ${meta.apiOnly ? '' : 'whether the design matches what was intended (use the screenshots of each page), '}business rules (what each ${meta.apiOnly ? 'endpoint' : 'page'} should do beyond its documented shape), load under many users, and an in-depth penetration test. ${esc(meta.steps.join(' · '))}</p>
 </main>
 <script>
 const sevButtons=[...document.querySelectorAll('[data-filter-sev]')],areaButtons=[...document.querySelectorAll('[data-filter-area]')];let sev='all',area=null;
-function apply(){document.querySelectorAll('.finding').forEach(f=>{f.hidden=!((sev==='all'||f.dataset.sev===sev)&&(!area||f.dataset.area===area))});sevButtons.forEach(b=>b.classList.toggle('active',b.dataset.filterSev===sev));areaButtons.forEach(b=>b.classList.toggle('active',b.dataset.filterArea===area))}
+function apply(){document.querySelectorAll('.finding').forEach(f=>{f.hidden=!((sev==='all'||f.dataset.sev===sev)&&(!area||f.dataset.area===area))});document.querySelectorAll('[data-group]').forEach(g=>{g.hidden=![...g.querySelectorAll('.finding')].some(f=>!f.hidden)});sevButtons.forEach(b=>b.classList.toggle('active',b.dataset.filterSev===sev));areaButtons.forEach(b=>b.classList.toggle('active',b.dataset.filterArea===area))}
 sevButtons.forEach(b=>b.addEventListener('click',()=>{sev=b.dataset.filterSev;apply()}));
-areaButtons.forEach(b=>b.addEventListener('click',()=>{area=area===b.dataset.filterArea?null:b.dataset.filterArea;apply();document.getElementById('findings').scrollIntoView({behavior:'smooth'})}));
+areaButtons.forEach(b=>b.addEventListener('click',()=>{area=area===b.dataset.filterArea?null:b.dataset.filterArea;apply();(document.getElementById('area-'+b.dataset.filterArea)||document.getElementById('findings')).scrollIntoView({behavior:'smooth'})}));
 </script>
 </body>
 </html>`;