@setsquare/review-sdk 0.0.1

package/dist/html-report.js

@@ -0,0 +1,649 @@
+import { BRAND_CSS, MASTHEAD_CSS, masthead } from './brand.js';
+import { esc } from './escape.js';
+import { humanInstant, shortCommit } from './human.js';
+import { insightBlocks } from './insights.js';
+import { renderScreensSection, SCREENS_CSS } from './screens.js';
+import { conformanceGrid, conformanceSummary, ruleSurfaceShare, stateCoverage, } from '@setsquare/schema/conformance';
+import { evidenceQuality, groupFindings, perfRows, surfaceRows, testOutcomes, totals, } from './summary.js';
+const STATE_WORD = {
+    failed: 'FAIL',
+    cantTell: 'CHECK',
+    rulesPassed: 'OK',
+    inapplicable: 'N/A',
+    untested: '—',
+};
+const STATE_LABEL = {
+    failed: 'failed',
+    cantTell: 'needs a person',
+    rulesPassed: 'every automated rule passed',
+    inapplicable: 'checks ran; nothing to check on this surface',
+    untested: 'untested',
+};
+function n(value) {
+    return value.toLocaleString('en-GB');
+}
+function percent(affected, total) {
+    if (total === 0 || affected === 0)
+        return '0%';
+    const rounded = Math.round((affected / total) * 100);
+    return rounded === 0 ? '<1%' : `${rounded}%`;
+}
+/** Why a merged group is partial, in one plain sentence. */
+function partialReason(group) {
+    if (group.missing.length > 0) {
+        return `${group.missing.length} invocation${group.missing.length === 1 ? '' : 's'} of run group “${group.id}” began but ${group.missing.length === 1 ? 'was' : 'were'} never merged.`;
+    }
+    if (group.stale.length > 0) {
+        return `${group.stale.length} invocation${group.stale.length === 1 ? '' : 's'} of run group “${group.id}” ${group.stale.length === 1 ? 'was' : 'were'} excluded as stale.`;
+    }
+    if (group.expectedParts !== null && group.completed !== group.expectedParts) {
+        return `${group.completed} of ${group.expectedParts} declared invocations of run group “${group.id}” have merged.`;
+    }
+    return `An invocation of run group “${group.id}” was cut short before it finished.`;
+}
+/** `href` is allowed only for URLs that came out of the envelope itself. */
+function helpLink(url) {
+    if (!url || !url.startsWith('https://'))
+        return '';
+    return ` <a href="${esc(url)}" rel="noopener">rule guidance</a>`;
+}
+export function renderHtmlReport(input) {
+    /*
+     * The P1b blocks, from the same wording functions the terminal uses.
+     *
+     * A definition list rather than a table: these are figure/label pairs with
+     * prose attached, not tabular data, and a table would promise columns that do
+     * not line up across blocks. Each block's notes carry the caveats that stop a
+     * reader drawing the wrong conclusion — "counts are per engine", "time spent
+     * not time added" — so they are rendered, never dropped as decoration.
+     */
+    const insightSections = insightBlocks(input.envelope, {
+        ...(input.declaredAxes ? { declaredAxes: input.declaredAxes } : {}),
+        ...(input.unmeasuredAxes ? { unmeasuredAxes: input.unmeasuredAxes } : {}),
+        ...(input.suite ? { suite: input.suite } : {}),
+        ...(input.overhead ? { overhead: input.overhead } : {}),
+    })
+        .map((block, index) => {
+        const id = `h-insight-${index}`;
+        const rows = block.figures
+            .map((figure) => `      <div><dt>${esc(String(figure.value))}</dt>` +
+            `<dd>${esc(figure.label)}` +
+            (figure.notes && figure.notes.length > 0
+                ? `<p class="muted">${figure.notes.map((note) => esc(note)).join('<br />')}</p>`
+                : '') +
+            `</dd></div>`)
+            .join('\n');
+        const notes = block.notes.map((note) => `    <p class="muted">${esc(note)}</p>`).join('\n');
+        return `
+  <section aria-labelledby="${id}">
+    <h2 id="${id}">${esc(block.heading)}</h2>
+    <dl class="insight">
+${rows}
+    </dl>
+${notes}
+  </section>`;
+    })
+        .join('\n');
+    const { envelope } = input;
+    const summary = conformanceSummary(envelope, {
+        ...(input.criterionRules ? { criterionRules: input.criterionRules } : {}),
+    });
+    const grid = conformanceGrid(envelope);
+    const count = totals(envelope);
+    const tests = testOutcomes(envelope);
+    const quality = evidenceQuality(envelope);
+    const groups = groupFindings(envelope);
+    const rows = surfaceRows(envelope);
+    const perf = perfRows(envelope);
+    const failingRules = new Set(envelope.scans.flatMap((scan) => scan.findings.filter((f) => f.status === 'violation').map((f) => f.ruleId))).size;
+    const verdictLine = () => {
+        if (count.scans === 0) {
+            return 'Nothing was scanned. This is not a clean result — it means nothing was looked at.';
+        }
+        const { verdict } = summary;
+        if (verdict.failuresDetectedAt) {
+            const fixes = verdict.nextFixes.map((r) => `${r.criterion} ${r.name}`).join(', ');
+            return (`Failures detected at Level ${verdict.failuresDetectedAt}. ` +
+                `To clear them, fix: ${esc(fixes)}. Automated checks cover only part of WCAG.`);
+        }
+        if (verdict.noFailuresDetectedAt) {
+            return (`No Level ${verdict.noFailuresDetectedAt} violations detected across ` +
+                `${n(summary.surfacesScanned)} surface${summary.surfacesScanned === 1 ? '' : 's'} (automated checks only).`);
+        }
+        return 'No conformance evidence in this run.';
+    };
+    const ladder = summary.levels
+        .map((level) => {
+        let state;
+        let cls;
+        if (!level.assessed) {
+            state = 'not assessed';
+            cls = 'muted';
+        }
+        else if (level.failing.length > 0) {
+            state = `failures detected — ${level.failing.length === 1 ? 'one criterion' : `${level.failing.length} criteria`}`;
+            cls = 'bad';
+        }
+        else {
+            state = 'no failures detected in what was scanned';
+            cls = 'good';
+        }
+        const scans = level.assessedScans
+            ? ` <span class="muted">(assessed on ${level.assessedScans.aaa} of ${level.assessedScans.total} scans)</span>`
+            : '';
+        return `<li><span class="level">${level.level}</span> <span class="${cls}">${state}</span>${scans}</li>`;
+    })
+        .join('\n      ');
+    /*
+     * The WCAG-EM-shaped scope statement: what was scanned, in which states, when,
+     * by what. The first page of any audit, and what lets a person staple this
+     * behind a manual sample instead of arguing with it.
+     */
+    const coverageRows = stateCoverage(envelope);
+    const scopeRows = coverageRows
+        .map((row) => `<tr><th scope="row">${esc(row.surface)}</th><td>${row.states.map(esc).join(', ')}${row.defaultOnly ? ' <span class="muted">(default state only)</span>' : ''}</td></tr>`)
+        .join('\n        ');
+    const defaultOnly = coverageRows.filter((row) => row.defaultOnly).length;
+    const stateNote = defaultOnly > 0 && coverageRows.length > 0
+        ? `<p class="muted">${defaultOnly} of ${coverageRows.length} surfaces have evidence in their default
+    state only. Error, loading and empty states are where regressions hide —
+    <code>setsquare.scan(page, surface, { state })</code> captures them.</p>`
+        : '';
+    const targets = [...new Set(envelope.scans.map((scan) => scan.wcagTarget))].sort().join(', ') || 'AA';
+    /* The grid: criteria × surfaces, real table, state words in every cell. */
+    const gridHead = grid.surfaces
+        .map((surface, i) => `<th scope="col"><span class="idx">${i + 1}</span> ${esc(surface)}</th>`)
+        .join('');
+    const gridBody = grid.rows
+        .map((row) => {
+        const cells = row.cells
+            .map((cell) => `<td class="s-${cell.state}">${STATE_WORD[cell.state]}</td>`)
+            .join('');
+        const removed = row.removedIn22
+            ? ' <span class="muted">(removed in WCAG 2.2 — counts toward no level)</span>'
+            : '';
+        return `<tr><th scope="row">${row.criterion} ${esc(row.name)} <span class="level">${row.removedIn22 ? '—' : row.level}</span>${removed}</th>${cells}</tr>`;
+    })
+        .join('\n        ');
+    const rollupDetail = (rollup) => {
+        const parts = [];
+        if (rollup.failedSurfaces.length > 0) {
+            parts.push(`<p><strong>Failed</strong> on ${rollup.failedSurfaces.length} of ${rollup.totalSurfaces} surfaces ` +
+                `(${percent(rollup.failedSurfaces.length, rollup.totalSurfaces)}): ${rollup.failedSurfaces.map(esc).join(', ')}</p>`);
+        }
+        if (rollup.cantTellSurfaces.length > 0) {
+            parts.push(`<p><strong>Needs a person</strong> on: ${rollup.cantTellSurfaces.map(esc).join(', ')}</p>`);
+        }
+        if (rollup.rulesPassedSurfaces.length > 0) {
+            parts.push(`<p><strong>Every automated rule passed</strong> on: ${rollup.rulesPassedSurfaces.map(esc).join(', ')}</p>`);
+        }
+        if (rollup.inapplicableSurfaces.length > 0) {
+            parts.push(`<p><strong>Nothing to check</strong> (checks ran, no such content) on: ${rollup.inapplicableSurfaces.map(esc).join(', ')}</p>`);
+        }
+        if (rollup.failingRules.length > 0) {
+            parts.push(`<p>Failing rules: <code>${rollup.failingRules.map(esc).join('</code>, <code>')}</code></p>`);
+        }
+        const passing = rollup.rules.filter((rule) => !rollup.failingRules.includes(rule));
+        if (passing.length > 0) {
+            parts.push(`<p class="muted">Other rules with evidence here: <code>${passing.map(esc).join('</code>, <code>')}</code></p>`);
+        }
+        return parts.join('\n          ');
+    };
+    /*
+     * Grouped by outcome, not by criterion number.
+     *
+     * Numeric order put a failure at 1.4.3 twenty rows below a pass at 1.1.1, so
+     * reading the failures meant reading everything. Nobody does that. The order
+     * below is the order people actually care in — what is broken, what needs a
+     * human, what held, what did not apply — with numeric order kept INSIDE each
+     * group so a known criterion is still findable.
+     *
+     * Criteria removed in 2.2 come last: they count toward no level, so they are
+     * the least actionable thing on the page.
+     */
+    const byNumber = (a, b) => a.criterion.localeCompare(b.criterion, 'en', { numeric: true });
+    const outcomeGroups = [
+        {
+            heading: 'Failures',
+            note: 'An automated check failed on at least one surface.',
+            rollups: summary.levels.flatMap((level) => level.failing).sort(byNumber),
+        },
+        {
+            heading: 'Needs a person',
+            note: 'A check ran and could not decide. These are not passes.',
+            rollups: summary.levels.flatMap((level) => level.cantTell).sort(byNumber),
+        },
+        {
+            heading: 'Every automated rule passed',
+            note: 'Evidence that the automated rules held here — not criterion conformance.',
+            rollups: summary.levels.flatMap((level) => level.rulesPassed).sort(byNumber),
+        },
+        {
+            heading: 'Nothing to check',
+            note: 'The checks ran and these pages contain nothing the criterion regulates.',
+            rollups: summary.levels.flatMap((level) => level.inapplicable).sort(byNumber),
+        },
+        {
+            heading: 'Removed in WCAG 2.2',
+            note: 'Kept for the record. These count toward no level.',
+            rollups: [...summary.removed].sort(byNumber),
+        },
+    ];
+    const criterionDetail = (rollup) => `
+      <details${rollup.state === 'failed' ? ' open' : ''}>
+        <summary><span class="s-${rollup.state} pill">${STATE_WORD[rollup.state]}</span> ${rollup.criterion} ${esc(rollup.name)} <span class="level">${rollup.removedIn22 ? 'removed in 2.2' : `Level ${rollup.level}`}</span></summary>
+        <div>
+          ${rollupDetail(rollup)}
+        </div>
+      </details>`;
+    const criteriaDetails = outcomeGroups
+        .filter((group) => group.rollups.length > 0)
+        .map((group) => `
+    <h3 class="outcome">${group.heading} <span class="count">${n(group.rollups.length)}</span></h3>
+    <p class="muted outcome-note">${group.note}</p>
+    ${group.rollups.map(criterionDetail).join('\n')}`)
+        .join('\n');
+    /* Coverage ledger, with the notRun/notAutomatable split when the map is present. */
+    const countedLevels = summary.levels.filter((level) => level.level !== 'AAA' || level.assessed);
+    const rulesPassedCount = countedLevels.reduce((sum, level) => sum + level.rulesPassed.length, 0);
+    const cantTellCount = countedLevels.reduce((sum, level) => sum + level.cantTell.length, 0);
+    const inapplicableRollups = countedLevels.flatMap((level) => level.inapplicable);
+    const untested = countedLevels.flatMap((level) => level.untested);
+    const coverage = [];
+    if (rulesPassedCount > 0) {
+        coverage.push(`<li><strong>${rulesPassedCount}</strong> criteria: every automated rule passed — evidence, not criterion conformance</li>`);
+    }
+    if (cantTellCount > 0)
+        coverage.push(`<li><strong>${cantTellCount}</strong> criteria need a person</li>`);
+    if (inapplicableRollups.length > 0) {
+        coverage.push(`<li><strong>${inapplicableRollups.length}</strong> criteria: checks ran, nothing to check on these pages — ` +
+            `${inapplicableRollups.map((r) => r.criterion).join(', ')}</li>`);
+    }
+    if (untested.length > 0) {
+        if (input.criterionRules) {
+            const noCheck = untested.filter((r) => r.untestedReason === 'notAutomatable');
+            const notRun = untested.filter((r) => r.untestedReason === 'notRun');
+            if (noCheck.length > 0) {
+                coverage.push(`<li><strong>${noCheck.length}</strong> criteria have no automated check in this engine: ` +
+                    `${noCheck.map((r) => r.criterion).join(', ')}</li>`);
+            }
+            if (notRun.length > 0) {
+                coverage.push(`<li><strong>${notRun.length}</strong> criteria have checks that did not run here: ` +
+                    `${notRun.map((r) => r.criterion).join(', ')}</li>`);
+            }
+        }
+        else {
+            coverage.push(`<li><strong>${untested.length}</strong> criteria not automatically checked in this run</li>`);
+        }
+    }
+    const surfacesBody = rows
+        .map((row) => {
+        const state = row.violations > 0 ? 'failed' : row.incomplete > 0 ? 'cantTell' : 'rulesPassed';
+        const word = row.violations > 0 ? 'FAIL' : row.incomplete > 0 ? 'CHECK' : 'pass';
+        return (`<tr><th scope="row">${esc(row.label)}</th>` +
+            `<td class="s-${state}">${word}</td>` +
+            `<td class="num">${n(row.violations)}</td>` +
+            `<td class="num">${n(row.incomplete)}</td>` +
+            `<td>${row.rules.map((rule) => `<code>${esc(rule)}</code>`).join(', ')}</td></tr>`);
+    })
+        .join('\n        ');
+    const ruleSections = (status) => groups
+        .filter((group) => group.status === status)
+        .map((group) => {
+        const share = ruleSurfaceShare(envelope, group.ruleId);
+        const spread = status === 'violation'
+            ? `on ${share.affected} of ${share.total} surfaces (${percent(share.affected, share.total)})`
+            : `on ${group.contexts.length} surface${group.contexts.length === 1 ? '' : 's'}`;
+        return `
+      <details>
+        <summary><code>${esc(group.ruleId)}</code> — ${esc(group.impact)}, ${n(group.nodes)} element${group.nodes === 1 ? '' : 's'} ${spread}${group.criteria.length > 0 ? ` — WCAG ${group.criteria.map(esc).join(', ')}` : ''}</summary>
+        <div>
+          ${group.failureSummary ? `<p>${esc(group.failureSummary)}</p>` : ''}
+          ${group.selectors.length > 0 ? `<p>Where: <code>${group.selectors.map(esc).join('</code>, <code>')}</code>${group.selectorsTruncated ? ' <span class="muted">(sample — every selector is in the embedded run data)</span>' : ''}</p>` : ''}
+          <p>${esc(group.contexts.join(', '))}${helpLink(group.helpUrl)}</p>
+        </div>
+      </details>`;
+    })
+        .join('\n');
+    const perfBody = perf
+        .map((row) => `<tr><th scope="row">${esc(row.label)}</th>` +
+        `<td class="num">${row.lcpMs !== undefined ? `${n(Math.round(row.lcpMs))}ms` : '—'}</td>` +
+        `<td class="num">${row.cls !== undefined ? row.cls.toFixed(2) : '—'}</td>` +
+        `<td class="num">${row.loadMs !== undefined ? `${n(Math.round(row.loadMs))}ms` : '—'}</td>` +
+        `<td class="num">${row.ttfbMs !== undefined ? `${n(Math.round(row.ttfbMs))}ms` : '—'}</td></tr>`)
+        .join('\n        ');
+    const testsLine = envelope.results.length > 0
+        ? `Playwright: ${tests.passed} passed` +
+            (tests.failed > 0 ? `, ${tests.failed} failed` : '') +
+            (tests.flaky > 0 ? `, ${tests.flaky} flaky` : '') +
+            (tests.skipped > 0 ? `, ${tests.skipped} skipped` : '') +
+            '.'
+        : '';
+    /*
+     * The group banner comes before every number in the document: a report over
+     * a half-merged group that leads with its conformance verdict is a report
+     * that will be quoted without the half that changes what it means.
+     */
+    const group = input.group;
+    const groupBanner = group
+        ? group.coverage === 'complete'
+            ? ''
+            : `
+  <p class="verdict ${group.coverage === 'partial' ? 'bad' : ''}">${group.coverage === 'partial'
+                ? `<strong>Partial run.</strong> ${esc(partialReason(group))} Evidence from what is missing is absent, not clean — do not treat this artifact as a baseline.`
+                : `<strong>Coverage unconfirmed.</strong> ${n(group.completed)} invocation${group.completed === 1 ? '' : 's'} of run group “${esc(group.id)}” merged; whether more were intended was not declared (set <code>SETSQUARE_RUN_PARTS</code>). Treat this artifact as current, not necessarily final.`}</p>`
+        : '';
+    const groupSection = group
+        ? `
+    <section aria-labelledby="h-group">
+      <h2 id="h-group">Run group</h2>
+      <p class="muted">This is the merged evidence of run group “${esc(group.id)}” — one logical run spanning
+      ${n(group.completed)} Playwright invocation${group.completed === 1 ? '' : 's'}${group.expectedParts !== null ? ` of ${n(group.expectedParts)} declared` : ''}. Test ids are prefixed with each invocation's label.</p>
+      <div class="tablewrap">
+        <table>
+          <thead><tr><th scope="col">Invocation</th><th scope="col">Lane</th><th scope="col">Started</th><th scope="col">Duration</th><th scope="col">Playwright</th><th scope="col">Tests</th><th scope="col">Scans</th></tr></thead>
+          <tbody>
+          ${group.parts
+            .map((part) => `<tr><th scope="row">${esc(part.label)}</th><td>${esc(part.lane ?? '—')}</td><td>${esc(part.startedAt)}</td><td class="num">${n(Math.round(part.durationMs / 1000))}s</td><td>${esc(part.playwrightStatus)}</td><td class="num">${n(part.tests)}</td><td class="num">${n(part.scans)}</td></tr>`)
+            .join('\n          ')}
+          </tbody>
+        </table>
+      </div>${group.missing.length > 0
+            ? `
+      <p class="bad">${n(group.missing.length)} invocation${group.missing.length === 1 ? '' : 's'} began but ${group.missing.length === 1 ? 'was' : 'were'} never merged: <code>${group.missing.map(esc).join('</code>, <code>')}</code>.</p>`
+            : ''}
+    </section>`
+        : '';
+    /*
+     * The screens block sits after the evidence and before the provenance: it is
+     * the part of this document a reviewer scans rather than reads, and putting it
+     * above the conformance verdict would let a page of pictures answer a question
+     * about WCAG that pictures cannot answer.
+     */
+    const screensSection = input.screens && input.screens.rows.length > 0
+        ? `\n${renderScreensSection(input.screens)}`
+        : '';
+    const warningsBlock = input.warnings.length > 0
+        ? `
+    <section aria-labelledby="h-warnings">
+      <h2 id="h-warnings">Worth knowing</h2>
+      <ul>
+        ${input.warnings.map((warning) => `<li>${esc(warning)}</li>`).join('\n        ')}
+      </ul>
+    </section>`
+        : '';
+    // `</script>`-proofing: `<` never appears raw inside the data block.
+    const embedded = JSON.stringify(envelope).replaceAll('<', '\\u003c');
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="color-scheme" content="light dark">
+<title>Setsquare — accessibility evidence, ${esc(humanInstant(envelope.generatedAt))}</title>
+<style>
+${BRAND_CSS}
+  /*
+   * The page's own names, mapped onto brand roles rather than renaming every
+   * rule below: one block to read, one place to change.
+   *
+   * The status roles lost their tinted BACKGROUNDS in the process, deliberately.
+   * tokens.css verifies each status colour as text on a surface and as a fill
+   * under its own ink pair; it has no tints, and inventing a pale red would mean
+   * shipping a contrast ratio nobody measured into an accessibility report. So a
+   * failing cell is bold danger-coloured TEXT, and the solid fill is kept for the
+   * pills, where role-under-its-own-ink is a measured pair.
+   *
+   * The faint --none-fg collapses into --ss-ink-muted: the palette has no second,
+   * fainter grey that clears 7:1, and the untested glyph is already distinct by
+   * content.
+   *
+   * (No backticks in this comment. It sits inside a template literal, so one
+   * would end the string and the parse error would surface pages away.)
+   */
+  :root {
+    --bg: var(--ss-surface); --fg: var(--ss-ink); --muted: var(--ss-ink-muted);
+    --line: var(--ss-border); --code-bg: var(--ss-surface-raised);
+    --bad-fg: var(--ss-danger); --warn-fg: var(--ss-warning); --good-fg: var(--ss-success);
+    --none-fg: var(--ss-ink-muted);
+  }
+${MASTHEAD_CSS}
+  * { box-sizing: border-box; }
+  body {
+    margin: 0 auto; padding: 2rem 1.5rem 4rem; max-width: 72rem;
+    background: var(--bg); color: var(--fg);
+    font: 16px/1.5 system-ui, -apple-system, "Segoe UI", sans-serif;
+  }
+  h1 { font-size: 1.6rem; margin: 0 0 .25rem; }
+  h2 { font-size: 1.2rem; margin: 2.5rem 0 .75rem; }
+  a { color: inherit; }
+  :focus-visible { outline: 3px solid var(--fg); outline-offset: 2px; }
+  code { background: var(--code-bg); padding: .1em .35em; border-radius: 4px; font-size: .875em; overflow-wrap: anywhere; }
+  .muted { color: var(--muted); }
+  .verdict { font-size: 1.1rem; margin: 1rem 0; padding: 1rem; border: 1px solid var(--line); border-radius: 8px; }
+  ul.ladder { list-style: none; padding: 0; margin: .5rem 0; }
+  ul.ladder li { padding: .2rem 0; }
+  .level { display: inline-block; min-width: 3ch; font-weight: 700; }
+  .good { color: var(--good-fg); }
+  .bad { color: var(--bad-fg); font-weight: 600; }
+  .figures { display: flex; flex-wrap: wrap; gap: 1.5rem; margin: 1.5rem 0; }
+  .figures div { border: 1px solid var(--line); border-radius: 8px; padding: .75rem 1rem; }
+  .figures strong { display: block; font-size: 1.4rem; }
+  /*
+   * The P1b insight blocks. A definition list, not the .figures stat strip:
+   * these rows carry prose under each figure, and a flex row of boxes would
+   * squeeze the caveats into columns nobody reads. The caveats are the point.
+   */
+  .insight { margin: 1rem 0; }
+  .insight > div { display: grid; grid-template-columns: 5rem 1fr; gap: .25rem 1rem; padding: .5rem 0; border-top: 1px solid var(--line); }
+  .insight > div:first-child { border-top: 0; }
+  .insight dt { font-weight: 600; text-align: right; font-variant-numeric: tabular-nums; }
+  .insight dd { margin: 0; }
+  .insight dd p { margin: .25rem 0 0; }
+  @media (max-width: 34rem) {
+    /* One column below the fold width: a 5rem gutter beside wrapping prose stops
+       being a gutter and starts being a squeeze. */
+    .insight > div { grid-template-columns: 1fr; }
+    .insight dt { text-align: left; }
+  }
+  .tablewrap { overflow-x: auto; }
+  table { border-collapse: collapse; width: 100%; margin: .75rem 0; }
+  th, td { border: 1px solid var(--line); padding: .4rem .6rem; text-align: left; vertical-align: top; }
+
+  /*
+   * Row banding, and the sticky criterion column.
+   *
+   * Neither is required by WCAG. Rows are already delineated by a 1px border in
+   * --ss-border, which tokens.css measures at 3.00:1 and is therefore at the
+   * 1.4.11 non-text-contrast threshold; and state is carried by the WORD in each
+   * cell, not by its colour, which is what 1.4.1 actually asks. Both of these are
+   * readability, and they are worth doing anyway.
+   *
+   * The bands are the two surfaces the palette already verifies, alternating —
+   * no new colour, so nothing new to measure. Light bands #ffffff against
+   * #f2f2f2, dark #0a0a0a against #1a1a1a, and tokens.css records each theme's
+   * ratios against its WORSE case, so the better surface cannot fail: ink is
+   * 18.76:1 / 17.40:1 and every status colour clears 7:1 on both.
+   *
+   * NB: no backticks anywhere in this style block — it is inside a template
+   * literal, so one ends the string and the parse error lands pages away.
+   *
+   * The band travels as a custom property rather than a background on the row,
+   * because the sticky cell has to paint the SAME band or it shows the wrong
+   * colour the moment it detaches.
+   */
+  tr { --row-bg: var(--ss-surface); }
+  tbody tr:nth-child(even) { --row-bg: var(--ss-surface-raised); }
+  th, td { background: var(--row-bg); }
+
+  /*
+   * The grid is sixteen surfaces wide inside a horizontal scroller, and what you
+   * lose scrolling right is not which row you are on — the borders handle that —
+   * it is WHICH CRITERION, because the row header has left the viewport. Pinning
+   * it is the difference between a readable table and a wall of FAIL.
+   *
+   * A box-shadow draws the right edge rather than border-right: under
+   * border-collapse: collapse the border belongs to the table, not the cell, so
+   * it does not travel with a sticky cell and the pinned column loses its edge.
+   */
+  .grid th[scope="row"], .grid thead th:first-child {
+    position: sticky; left: 0; z-index: 1;
+    box-shadow: 1px 0 0 var(--line);
+  }
+  /*
+   * The header cell sits above the body cells it shares a column with, so that
+   * when the table is ALSO scrolled down the two never fight over the corner.
+   * Pinning the row headers without pinning this one was the first version, and
+   * it looked broken in exactly the way you would expect: the surface headers
+   * slid underneath the criterion labels.
+   */
+  .grid thead th:first-child { z-index: 2; }
+  th[scope="col"] .idx { color: var(--muted); font-weight: 400; }
+  td.num { text-align: right; font-variant-numeric: tabular-nums; }
+  td.s-failed { color: var(--bad-fg); font-weight: 700; }
+  td.s-cantTell { color: var(--warn-fg); font-weight: 600; }
+  td.s-rulesPassed { color: var(--good-fg); }
+  td.s-inapplicable { color: var(--muted); }
+  /* Pills are the one solid fill: a role under its own -ink is a measured pair. */
+  .pill.s-failed { background: var(--ss-danger); color: var(--ss-danger-ink); font-weight: 700; }
+  .pill.s-cantTell { background: var(--ss-warning); color: var(--ss-warning-ink); font-weight: 600; }
+  .pill.s-rulesPassed { background: var(--ss-success); color: var(--ss-success-ink); }
+  .pill.s-inapplicable { background: var(--ss-surface-raised); color: var(--muted); border: 1px solid var(--line); }
+  td.s-untested { color: var(--none-fg); }
+  h3.outcome { font-size: 1rem; margin: 1.75rem 0 .1rem; display: flex; align-items: baseline; gap: .5rem; }
+  h3.outcome .count { font-weight: 400; color: var(--muted); font-size: .875rem; }
+  .outcome-note { margin: 0 0 .5rem; font-size: .875rem; }
+  .pill { display: inline-block; min-width: 4.5ch; text-align: center; padding: 0 .4em; border-radius: 4px; }
+  details { border: 1px solid var(--line); border-radius: 8px; padding: .5rem .75rem; margin: .5rem 0; }
+  details > div { margin-top: .5rem; }
+  summary { cursor: pointer; }
+  footer { margin-top: 3rem; padding-top: 1rem; border-top: 1px solid var(--line); color: var(--muted); font-size: .875rem; }
+  footer code { font-size: .8rem; }
+  .ok { color: var(--good-fg); }
+${SCREENS_CSS}
+</style>
+</head>
+<body>
+${masthead('Setsquare — accessibility evidence', 
+    /*
+     * The friendly instant is visible; the exact one stays in the `datetime`
+     * attribute, so a machine reading this page still gets milliseconds and a
+     * person reading it gets a date. The commit is shortened for display only —
+     * the full SHA is in run.json, which is what anything automated reads.
+     */
+    `<time datetime="${esc(envelope.generatedAt)}">${esc(humanInstant(envelope.generatedAt))}</time>` +
+        ` · ${esc(envelope.source.branch)} @ ${esc(shortCommit(envelope.source.commit))}` +
+        `${testsLine ? ` · ${esc(testsLine)}` : ''}`)}${groupBanner}
+<main>
+  <section aria-labelledby="h-verdict">
+    <h2 id="h-verdict">Conformance — WCAG 2.2 <span class="muted">(includes every 2.0 and 2.1 criterion)</span></h2>
+    <p class="verdict">${verdictLine()}</p>
+    <ul class="ladder">
+      ${ladder}
+    </ul>
+    <ul>
+      ${coverage.join('\n      ')}
+    </ul>
+  </section>
+
+  <section aria-labelledby="h-figures">
+    <h2 id="h-figures">This run</h2>
+    <div class="figures">
+      <div><strong>${n(count.surfaces)}</strong> surfaces scanned${count.themes > 0 ? ` in ${count.themes} theme${count.themes === 1 ? '' : 's'}` : ''}</div>
+      <div><strong>${n(failingRules)}</strong> rules failing, on ${n(count.violations)} elements</div>
+      <div><strong>${n(count.incomplete)}</strong> elements need a person</div>
+      <div><strong>${n(count.passes)}</strong> checks passed across ${n(quality.rulesAssessed)} rules</div>
+    </div>
+  </section>
+
+  <section aria-labelledby="h-grid">
+    <h2 id="h-grid">Conformance grid</h2>
+    <p class="muted">Criteria with evidence, per surface. A surface counts as failing if it fails in any scanned
+    state or theme. <strong>OK</strong> means every automated rule for the criterion passed there — evidence,
+    not criterion conformance; <strong>CHECK</strong> means automation could not decide; <strong>N/A</strong> means
+    the checks ran and the surface contains nothing the criterion regulates; <strong>—</strong> means
+    nothing looked.</p>
+    <div class="tablewrap">
+      <table class="grid">
+        <caption class="muted">WCAG success criteria × surfaces</caption>
+        <thead><tr><th scope="col">Criterion</th>${gridHead}</tr></thead>
+        <tbody>
+        ${gridBody}
+        </tbody>
+      </table>
+    </div>
+    ${criteriaDetails}
+  </section>
+
+  <section aria-labelledby="h-scope">
+    <h2 id="h-scope">Scope</h2>
+    <p>Assessed against WCAG 2.2 ${esc(targets)} with automated checks only, on the surfaces and states below.
+    Anything not listed was not looked at.</p>
+    <div class="tablewrap">
+      <table>
+        <thead><tr><th scope="col">Surface</th><th scope="col">States scanned</th></tr></thead>
+        <tbody>
+        ${scopeRows}
+        </tbody>
+      </table>
+    </div>
+    ${stateNote}
+  </section>
+
+  <section aria-labelledby="h-surfaces">
+    <h2 id="h-surfaces">Surfaces</h2>
+    <div class="tablewrap">
+      <table>
+        <thead><tr><th scope="col">Surface</th><th scope="col">State</th><th scope="col">Failing elements</th><th scope="col">Needs review</th><th scope="col">Rules failing</th></tr></thead>
+        <tbody>
+        ${surfacesBody}
+        </tbody>
+      </table>
+    </div>
+  </section>
+
+  <section aria-labelledby="h-rules">
+    <h2 id="h-rules">Rules failing</h2>
+    ${ruleSections('violation') || '<p class="muted">None.</p>'}
+  </section>
+
+  <section aria-labelledby="h-review">
+    <h2 id="h-review">Needs review</h2>
+    <p class="muted">Automation could not decide these — usually contrast over an image or a gradient.
+    Not passes and not failures; a person has to look.</p>
+    ${ruleSections('incomplete') || '<p class="muted">None.</p>'}
+  </section>
+${perf.length > 0
+        ? `
+  <section aria-labelledby="h-perf">
+    <h2 id="h-perf">Performance <span class="muted">(CI lab, not real users)</span></h2>
+    <div class="tablewrap">
+      <table>
+        <thead><tr><th scope="col">Page load</th><th scope="col">LCP</th><th scope="col">CLS</th><th scope="col">Load</th><th scope="col">TTFB</th></tr></thead>
+        <tbody>
+        ${perfBody}
+        </tbody>
+      </table>
+    </div>
+    <p class="muted">— means the engine did not report it: Firefox and WebKit implement neither LCP nor CLS.
+    Absent is not zero.</p>
+  </section>`
+        : ''}
+${insightSections}
+${screensSection}
+${groupSection}
+${warningsBlock}
+</main>
+<footer>
+  <p>Generated by Setsquare SDK ${esc(envelope.source.sdkVersion)} · axe-core ${esc(envelope.source.axeVersion)} ·
+  ruleset <code>${esc(envelope.source.rulesetDigest)}</code> · ${esc(envelope.source.runSource)} run.</p>
+  <p>This report summarises automated rule results per scanned surface. It is not a WCAG conformance claim:
+  WCAG conformance is defined per full page and complete process and includes requirements (non-interference,
+  accessibility support, conforming alternate versions) that automated scanning cannot evaluate.</p>
+</footer>
+<script type="application/json" id="setsquare-run">${embedded}</script>
+</body>
+</html>
+`;
+}
+//# sourceMappingURL=html-report.js.map