frontend-go-live-check 1.4.0 → 1.4.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # 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:

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>
 
@@ -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.4.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/core/explain.mjs

@@ -115,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.' },
@@ -238,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/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>`;