@setsquare/review-sdk 0.0.1

package/dist/summary.js

@@ -0,0 +1,1308 @@
+import { conformanceGrid, conformanceSummary, ruleSurfaceShare, stateCoverage, } from '@setsquare/schema/conformance';
+import { PLATFORM_URL, ruleHelpUrl } from './links.js';
+import { continuationLines, createStyle, figureBlock, figureLine, heading, } from './style.js';
+import { flakeNotes, insightBlocks } from './insights.js';
+/**
+ * One wording for every renderer, because the three formats must never say
+ * different things about the same coverage.
+ */
+export function groupLines(group) {
+    const lines = [];
+    lines.push(`This invocation${group.lane ? ` (lane "${group.lane}")` : ''} is part of run group ` +
+        `"${group.id}". The summary above covers this invocation only; the evidence files ` +
+        `hold the whole group.`);
+    lines.push(`${group.mergedParts} invocation${group.mergedParts === 1 ? '' : 's'} merged so far` +
+        (group.labels.length > 0 ? ` (${group.labels.join(', ')})` : '') +
+        '.');
+    if (group.missing > 0) {
+        lines.push(`${group.missing} invocation${group.missing === 1 ? '' : 's'} began but ` +
+            `${group.missing === 1 ? 'was' : 'were'} never merged — that evidence is absent, ` +
+            'not clean. The merged run is partial.');
+    }
+    switch (group.coverage) {
+        case 'complete':
+            lines.push(`All ${group.expectedParts} declared invocation${group.expectedParts === 1 ? '' : 's'} ` +
+                'merged. The merged artifacts are final for this group.');
+            break;
+        case 'partial':
+            if (group.expectedParts !== null && group.missing === 0) {
+                lines.push(`${group.mergedParts} of ${group.expectedParts} declared invocations merged. ` +
+                    'The merged artifacts are partial until the rest arrive.');
+            }
+            break;
+        case 'unknown':
+            lines.push('Whether more invocations are coming is not declared — set SETSQUARE_RUN_PARTS to say ' +
+                'how many to expect. Until then, treat the merged artifacts as current, not final.');
+            break;
+    }
+    return lines;
+}
+const IMPACT_ORDER = ['critical', 'serious', 'moderate', 'minor'];
+/** Selectors shown per rule entry in the terminal; the full set is in report.html. */
+const MAX_ENTRY_SELECTORS = 5;
+/** `job-editor · dark` — the coordinates a person can act on. */
+function contextLabel(context) {
+    return [context.surface, context.theme, context.persona, context.state]
+        .filter(Boolean)
+        .join(' · ');
+}
+/**
+ * Collapse findings to one row per (rule, status).
+ *
+ * Deliberately not per rule alone: a rule that fails on one surface and is
+ * *unresolvable* on another is telling you two different things, and merging them
+ * would report "we could not check this" as "this is broken".
+ */
+export function groupFindings(envelope) {
+    const groups = new Map();
+    for (const scan of envelope.scans) {
+        for (const finding of scan.findings) {
+            const key = `${finding.ruleId}\u0000${finding.status}`;
+            const existing = groups.get(key);
+            const label = contextLabel(scan.context);
+            if (existing) {
+                existing.nodes += finding.targets.nodeCount;
+                if (!existing.contexts.includes(label))
+                    existing.contexts.push(label);
+                const slot = existing.contextNodes.find((c) => c.label === label);
+                if (slot)
+                    slot.nodes += finding.targets.nodeCount;
+                else
+                    existing.contextNodes.push({ label, nodes: finding.targets.nodeCount });
+                for (const selector of finding.targets.selectors) {
+                    if (existing.selectors.length >= MAX_ENTRY_SELECTORS) {
+                        existing.selectorsTruncated = true;
+                        break;
+                    }
+                    if (!existing.selectors.includes(selector))
+                        existing.selectors.push(selector);
+                }
+                if (finding.targets.selectorsTruncated)
+                    existing.selectorsTruncated = true;
+                if (!existing.failureSummary && finding.evidence?.failureSummary) {
+                    existing.failureSummary = finding.evidence.failureSummary;
+                }
+                continue;
+            }
+            groups.set(key, {
+                ruleId: finding.ruleId,
+                impact: finding.impact ?? 'unknown',
+                status: finding.status,
+                nodes: finding.targets.nodeCount,
+                contexts: [label],
+                contextNodes: [{ label, nodes: finding.targets.nodeCount }],
+                selectors: finding.targets.selectors.slice(0, MAX_ENTRY_SELECTORS),
+                selectorsTruncated: finding.targets.selectorsTruncated ||
+                    finding.targets.selectors.length > MAX_ENTRY_SELECTORS,
+                ...(finding.evidence?.failureSummary
+                    ? { failureSummary: finding.evidence.failureSummary }
+                    : {}),
+                ...(ruleHelpUrl(finding) ? { helpUrl: ruleHelpUrl(finding) } : {}),
+                criteria: finding.wcag?.criteria ?? [],
+            });
+        }
+    }
+    /*
+     * Violations before incompletes, then by impact, then by size, then by rule id.
+     *
+     * Fully determined at every level so two runs of the same suite produce
+     * byte-identical output — a summary you can diff is worth more than one sorted
+     * by whichever rule axe happened to mention first.
+     */
+    return [...groups.values()].sort((a, b) => {
+        if (a.status !== b.status)
+            return a.status === 'violation' ? -1 : 1;
+        const impactDelta = impactRank(a.impact) - impactRank(b.impact);
+        if (impactDelta !== 0)
+            return impactDelta;
+        if (a.nodes !== b.nodes)
+            return b.nodes - a.nodes;
+        return a.ruleId.localeCompare(b.ruleId);
+    });
+}
+function impactRank(impact) {
+    const index = IMPACT_ORDER.indexOf(impact);
+    // An unknown impact sorts last rather than first: axe leaves it off some
+    // incompletes, and "we do not know how bad this is" should not lead the report.
+    return index === -1 ? IMPACT_ORDER.length : index;
+}
+/**
+ * One row per scanned context, worst first.
+ *
+ * The summary used to report only totals and rules, which answered "what is
+ * broken" without answering "where". Both matter, and the second is the one a
+ * person acts on: they open a surface, not a rule.
+ */
+export function surfaceRows(envelope) {
+    /*
+     * Merged by LABEL, not by scan.
+     *
+     * Dedupe keys on the route pattern, so two genuinely different routes a
+     * customer has deliberately named the same surface both survive it — correctly,
+     * since they are different pages. But they must not appear as two identical
+     * rows here, because a reader has no way to tell them apart and will read it as
+     * the tool repeating itself.
+     */
+    const merged = new Map();
+    for (const scan of envelope.scans) {
+        const label = contextLabel(scan.context);
+        const failing = scan.findings.filter((finding) => finding.status === 'violation');
+        const unresolved = scan.findings.filter((finding) => finding.status === 'incomplete');
+        const row = merged.get(label) ?? { label, violations: 0, incomplete: 0, rules: [] };
+        row.violations += failing.reduce((sum, finding) => sum + finding.targets.nodeCount, 0);
+        row.incomplete += unresolved.reduce((sum, finding) => sum + finding.targets.nodeCount, 0);
+        row.rules = [...new Set([...row.rules, ...failing.map((finding) => finding.ruleId)])].sort();
+        merged.set(label, row);
+    }
+    const rows = [...merged.values()];
+    // Failing surfaces first and by severity of volume, then clean ones
+    // alphabetically. Determinate at every level so two runs stay diffable.
+    return rows.sort((a, b) => {
+        if (a.violations > 0 !== b.violations > 0)
+            return a.violations > 0 ? -1 : 1;
+        if (a.violations !== b.violations)
+            return b.violations - a.violations;
+        return a.label.localeCompare(b.label);
+    });
+}
+/**
+ * How much the findings are worth, as distinct from what they say.
+ *
+ * The worst failure available to an accessibility scanner is not a crash but a
+ * CONFIDENT FALSE PASS — audit a page before its content arrives, find nothing,
+ * report conformance nobody verified. That failure is invisible in the findings
+ * themselves, which is why the schema carries the conditions each scan fired
+ * under. Until now nothing read them back: every scan in a run looked equally
+ * trustworthy in the summary, including the ones we already knew were not.
+ *
+ * `rulesAssessed` is the other half of the same idea. "2,518 checks passed" is an
+ * impressive number with no denominator — 2,518 out of what? Naming how many
+ * distinct rules ran turns it into a statement someone could audit.
+ */
+export function evidenceQuality(envelope) {
+    const rules = new Set();
+    let quiet = 0;
+    let teardown = 0;
+    let ceiling = 0;
+    for (const scan of envelope.scans) {
+        for (const pass of scan.passes ?? [])
+            rules.add(pass.ruleId);
+        for (const finding of scan.findings)
+            rules.add(finding.ruleId);
+        // Absent on explicit scans, where the customer chose the moment and no
+        // heuristic was involved — so there is nothing to be suspicious of.
+        switch (scan.settle?.reason) {
+            case 'quiet':
+                quiet += 1;
+                break;
+            case 'teardown':
+                teardown += 1;
+                break;
+            case 'ceiling':
+                ceiling += 1;
+                break;
+            default:
+                break;
+        }
+    }
+    return { rulesAssessed: rules.size, quiet, teardown, ceiling };
+}
+/*
+ * Google's "good" thresholds for the two Core Web Vitals we can measure in a lab.
+ *
+ * Named constants with their source, because a bare 2500 in a comparison is a
+ * number nobody can check. These are the field thresholds, and applying them to
+ * CI-lab timings overstates how good the numbers are rather than how bad — a
+ * localhost page load on an idle runner beats a real phone on a real network
+ * every time. That direction matters: a threshold that flatters is safe to show
+ * as long as the report says what it is measuring, which is why the heading does.
+ */
+const GOOD_LCP_MS = 2500;
+const GOOD_CLS = 0.1;
+/**
+ * One row per page LOAD, not per scan.
+ *
+ * `setsquare.scan()` can run several times against one navigation — modal closed, then
+ * modal open — and every one of those scans carries the same `perf` numbers,
+ * because there was only ever one load. Averaging or ranking without collapsing
+ * them would weight a surface by how many states it happens to have, which is a
+ * property of how somebody wrote their test rather than of the page. `visitRef`
+ * exists in the schema precisely to make this collapse possible.
+ */
+export function perfRows(envelope) {
+    const byVisit = new Map();
+    for (const scan of envelope.scans) {
+        if (!scan.perf)
+            continue;
+        const key = scan.visitRef ?? `${scan.testId}:${contextLabel(scan.context)}`;
+        if (byVisit.has(key))
+            continue;
+        byVisit.set(key, {
+            label: contextLabel(scan.context),
+            ...(scan.perf.lcpMs !== undefined ? { lcpMs: scan.perf.lcpMs } : {}),
+            ...(scan.perf.cls !== undefined ? { cls: scan.perf.cls } : {}),
+            ...(scan.perf.loadMs !== undefined ? { loadMs: scan.perf.loadMs } : {}),
+            ...(scan.perf.ttfbMs !== undefined ? { ttfbMs: scan.perf.ttfbMs } : {}),
+        });
+    }
+    return [...byVisit.values()].sort((a, b) => (b.lcpMs ?? -1) - (a.lcpMs ?? -1) || a.label.localeCompare(b.label));
+}
+/**
+ * What Playwright itself reported — counted the way Playwright counts it.
+ *
+ * The first version of this disagreed with the run it was printed underneath. On
+ * Eos, Playwright said *26 passed, 2 failed, 2 flaky, 82 did not run* and we said
+ * *28 passed, 6 failed*. Both of our numbers were defensible and both were wrong
+ * to print: the 6 counted every failed ATTEMPT including retries, and the 28
+ * quietly folded the two flaky tests in with the healthy ones.
+ *
+ * A tool that runs inside somebody's suite and then contradicts that suite's own
+ * summary, on the same screen, a few lines further down, has undermined itself
+ * before it says anything about accessibility. So: one row per TEST, the last
+ * attempt decides, and a test that needed a retry is named as flaky rather than
+ * absorbed.
+ *
+ * `notRun` is the one that changes what the rest of the report means. Eos's run
+ * scanned 10 surfaces — which reads as coverage of the application until you know
+ * that 82 of its 112 tests never executed, because a failing setup project took
+ * their dependents down with it. Evidence from a quarter of a suite must not look
+ * like evidence from a suite.
+ */
+export function testOutcomes(envelope, plannedTests) {
+    const attempts = new Map();
+    for (const result of envelope.results) {
+        const rows = attempts.get(result.testId) ?? [];
+        rows.push({ retry: result.retry ?? 0, status: result.status });
+        attempts.set(result.testId, rows);
+    }
+    let passed = 0;
+    let failed = 0;
+    let flaky = 0;
+    let skipped = 0;
+    for (const rows of attempts.values()) {
+        // Highest retry number is the final attempt. Sorting rather than trusting
+        // arrival order: workers report concurrently and nothing guarantees a retry
+        // lands after the attempt it followed.
+        const final = [...rows].sort((a, b) => a.retry - b.retry).at(-1);
+        const everFailed = rows.some((row) => row.status !== 'passed' && row.status !== 'skipped');
+        if (final?.status === 'skipped')
+            skipped += 1;
+        else if (final?.status === 'passed') {
+            if (everFailed)
+                flaky += 1;
+            else
+                passed += 1;
+        }
+        else
+            failed += 1;
+    }
+    const reported = attempts.size;
+    return {
+        passed,
+        failed,
+        flaky,
+        skipped,
+        /*
+         * Only when we were told the size of the suite, and never negative. A
+         * reporter can be handed a filtered run (`--grep`, `--last-failed`, a single
+         * spec path), in which case the planned total IS the filtered total and this
+         * is correctly zero — the number describes what this run intended to do, not
+         * what the repository contains.
+         */
+        ...(plannedTests !== undefined ? { notRun: Math.max(0, plannedTests - reported) } : {}),
+    };
+}
+export function totals(envelope) {
+    const surfaces = new Set();
+    const themes = new Set();
+    let violations = 0;
+    let incomplete = 0;
+    let passes = 0;
+    let clean = 0;
+    for (const scan of envelope.scans) {
+        surfaces.add(scan.context.surface);
+        if (scan.context.theme)
+            themes.add(scan.context.theme);
+        const scanViolations = scan.findings.filter((f) => f.status === 'violation');
+        violations += scanViolations.reduce((sum, f) => sum + f.targets.nodeCount, 0);
+        incomplete += scan.findings
+            .filter((f) => f.status === 'incomplete')
+            .reduce((sum, f) => sum + f.targets.nodeCount, 0);
+        passes += scan.passes.reduce((sum, p) => sum + p.nodeCount, 0);
+        if (scanViolations.length === 0)
+            clean += 1;
+    }
+    return {
+        surfaces: surfaces.size,
+        themes: themes.size,
+        scans: envelope.scans.length,
+        violations,
+        incomplete,
+        passes,
+        clean,
+    };
+}
+/** Never wider than the terminal, never narrower than legible. */
+export function terminalWidth(columns) {
+    return Math.max(80, Math.min(columns ?? 80, 120));
+}
+/** 1259 -> 1,259. A four-digit count read as a price is a count read wrong. */
+function n(value) {
+    return value.toLocaleString('en-GB');
+}
+/**
+ * Wrap on word boundaries, continuation lines indented.
+ *
+ * Truncation was the first attempt and it cut the useful half off: a note saying
+ * WHICH surfaces went unscanned became "…the test moved on …", which is the part
+ * nobody needed. If a line is worth printing it is worth finishing.
+ */
+function wrap(value, width, indent) {
+    const words = value.split(/\s+/);
+    const lines = [];
+    let current = '';
+    for (const word of words) {
+        if (current.length > 0 && (current + ' ' + word).length > width) {
+            lines.push(current);
+            current = word;
+        }
+        else {
+            current = current.length > 0 ? current + ' ' + word : word;
+        }
+    }
+    if (current.length > 0)
+        lines.push(current);
+    return lines.map((line, index) => (index === 0 ? line : indent + line));
+}
+/**
+ * The plain-text summary.
+ *
+ * Two spaces of indent throughout rather than aligned columns: alignment breaks
+ * the moment a surface name is long, and a broken column looks like a bug in the
+ * tool rather than a long name.
+ */
+export function renderText(input, columns) {
+    const { envelope } = input;
+    const width = terminalWidth(columns);
+    const style = createStyle();
+    const lines = [];
+    const count = totals(envelope);
+    const tests = testOutcomes(envelope, input.plannedTests);
+    /*
+     * Every figure in one right-aligned gutter, matching the coverage audit.
+     *
+     * The two commands are one product and had two voices — the audit scannable,
+     * this a wall of even-weight prose with the numbers buried mid-sentence. A
+     * reader arriving here has just watched their suite run and wants three facts
+     * before they decide whether to care: did the tests pass, how much is broken,
+     * and where. Those are the three figures, and they now land in the left-hand
+     * strip before a word is read.
+     */
+    /**
+     * Where the run's own artefacts are, and — usually — the closing block.
+     *
+     * `promo` is a parameter because of one case: a run that scanned nothing must
+     * not be followed by a pitch. The numbers it would quote are all zero, so it
+     * would read as an advert bolted onto a failure, and the closing block's whole
+     * licence to exist is that it is derived from the run's own figures.
+     */
+    const trailer = (promo = true) => [
+        ...(input.warnings.length > 0 ? [''] : []),
+        ...warningLines(input.warnings, width, evidenceQuality(envelope), envelope),
+        '',
+        heading(style, 'Evidence'),
+        figureLine(style, '', input.envelopePath),
+        ...(input.htmlReportPath
+            ? [figureLine(style, '', `${input.htmlReportPath}  ${style.dim('(open in a browser)')}`)]
+            : []),
+        ...(input.screensPath
+            ? [figureLine(style, '', `${input.screensPath}  ${style.dim('(screenshots, one page)')}`)]
+            : []),
+        ...(input.reportPath
+            ? [figureLine(style, '', `${input.reportPath}  ${style.dim('(Playwright report)')}`)]
+            : []),
+        ...(input.group
+            ? [
+                '',
+                heading(style, 'Run group'),
+                ...groupLines(input.group).flatMap((line) => wrap(line, Math.max(40, width - 8), '').map((wrapped) => figureLine(style, '', wrapped))),
+            ]
+            : []),
+        ...(promo ? promoLines(input, count, width) : ['']),
+    ];
+    lines.push('');
+    lines.push(`  ${style.accent('Setsquare')} — accessibility evidence`);
+    lines.push('');
+    /*
+     * Playwright's own verdict, first and always.
+     *
+     * This runs inside somebody's test suite and the suite's result is the thing
+     * they came for. Leading with our findings — or omitting theirs — would be a
+     * tool behaving as though it were the point of the run rather than a passenger
+     * on it. It also makes the independence obvious: their tests pass or fail on
+     * their own terms, and nothing here changes that.
+     */
+    if (envelope.results.length > 0) {
+        lines.push(heading(style, 'Playwright'));
+        lines.push(figureLine(style, tests.passed, 'passed'));
+        if (tests.failed > 0)
+            lines.push(figureLine(style, tests.failed, 'failed'));
+        // Named, never folded into `passed`. A test that only goes green on a second
+        // attempt is not a passing test, and it is the category teams learn to ignore
+        // precisely because nothing puts a number on it.
+        if (tests.flaky > 0) {
+            lines.push(figureLine(style, tests.flaky, 'flaky — passed on retry'));
+            // WHICH tests, on which attempt, and where they first broke. The count alone
+            // is the number teams learn to ignore, precisely because it names nothing.
+            for (const note of flakeNotes(input.suite)) {
+                lines.push(...continuationLines(style, note, width));
+            }
+        }
+        if (tests.skipped > 0)
+            lines.push(figureLine(style, tests.skipped, 'skipped'));
+        if (tests.notRun) {
+            /*
+             * The line that changes what everything below it means.
+             *
+             * A run that scanned 10 surfaces reads as coverage of the application until
+             * you know that 82 of its 112 tests never executed. Evidence from a quarter
+             * of a suite must not look like evidence from a suite, so this is stated
+             * here rather than left for someone to work out from Playwright's output
+             * further up the screen.
+             */
+            lines.push(figureLine(style, tests.notRun, 'never ran'));
+            lines.push(...continuationLines(style, 'Findings below cover only what did run.'));
+        }
+        lines.push('');
+    }
+    if (count.scans === 0) {
+        /*
+         * Nothing scanned is a real outcome, and "0 violations" here would be the
+         * single most dangerous sentence this tool could print: it reads as "no
+         * problems" when it means "nobody looked". So the figure is deliberately the
+         * count of surfaces LOOKED AT, which is zero, and never a count of findings.
+         */
+        lines.push(heading(style, 'Accessibility'));
+        lines.push(figureLine(style, 0, 'surfaces scanned'));
+        lines.push(...continuationLines(style, 'This is not a clean result — it means nothing was looked at. Usually the ' +
+            'suite never opened a page, or every test finished before its page settled.', width));
+        lines.push(...trailer(false));
+        return join(lines);
+    }
+    const target = envelope.scans[0]?.wcagTarget ?? 'AA';
+    const quality = evidenceQuality(envelope);
+    lines.push(heading(style, `Accessibility — WCAG 2.2 ${target}`));
+    /*
+     * Rules first, elements second, and that ordering is the difference between a
+     * summary a person can act on and one that panics them.
+     *
+     * The fixture suite reports 626 failing elements, almost all of them one
+     * contrast rule on one deliberately absurd page. Leading with the element count
+     * reads as a fortnight of work; leading with the rule count reads as an
+     * afternoon, and is the truer description, because a person fixes a rule and its
+     * cause rather than an element.
+     */
+    const failingRules = new Set(envelope.scans.flatMap((scan) => scan.findings.filter((f) => f.status === 'violation').map((f) => f.ruleId))).size;
+    lines.push(figureLine(style, count.surfaces, `surface${count.surfaces === 1 ? '' : 's'} scanned` +
+        (count.themes > 0 ? ` in ${count.themes} theme${count.themes === 1 ? '' : 's'}` : '')));
+    /*
+     * Changed-only mode, stated where nobody can miss it.
+     *
+     * A filtered run's conformance figures describe a SLICE, and the figures
+     * themselves look identical to a full run's. The unscannable block below counts
+     * the skips, but a reader who quotes "surfaces scanned" from the top of this
+     * output would be quoting a slice as the application. So the mode is named
+     * immediately under the figure it qualifies, not in a footnote.
+     */
+    const changedOnly = (envelope.unscanned ?? []).filter((row) => row.reason === 'not-in-changed-set');
+    if (changedOnly.length > 0) {
+        const occurrences = changedOnly.reduce((total, row) => total + row.count, 0);
+        lines.push(...continuationLines(style, `Changed-only mode: ${changedOnly.length} ${changedOnly.length === 1 ? 'surface was' : 'surfaces were'} skipped (${occurrences} ${occurrences === 1 ? 'time' : 'times'}) because the change ` +
+            'does not reach them. Every figure below describes that slice, not the application.', width));
+    }
+    if (count.violations === 0 && count.incomplete === 0) {
+        lines.push(figureLine(style, 0, 'rules failing'));
+        lines.push(figureLine(style, count.passes, style.dim(`checks passed, across ${quality.rulesAssessed} distinct rules`)));
+        lines.push(...conformanceLines(input, style, width));
+        lines.push(...gridLines(input, style, width));
+        lines.push(...perfLines(envelope, style, width));
+        lines.push(...trailer());
+        return join(lines);
+    }
+    lines.push(figureLine(style, failingRules, `rule${failingRules === 1 ? '' : 's'} failing, on ${n(count.violations)} ` +
+        `element${count.violations === 1 ? '' : 's'}`));
+    if (count.incomplete > 0) {
+        lines.push(figureLine(style, count.incomplete, 'needing review — axe could not decide'));
+    }
+    lines.push(figureLine(style, count.passes, style.dim(`checks passed, across ${quality.rulesAssessed} distinct rules`)));
+    lines.push(...conformanceLines(input, style, width));
+    lines.push(...gridLines(input, style, width));
+    lines.push('');
+    /*
+     * Surfaces before rules.
+     *
+     * "Which pages are failing" is the question people actually arrive with, and it
+     * was answerable only by reading the rule entries and reassembling the list in
+     * your head. Failing surfaces are never truncated — a summary that hides a
+     * failure to stay tidy has chosen the wrong thing to optimise.
+     */
+    const rows = surfaceRows(envelope);
+    const failing = rows.filter((row) => row.violations > 0);
+    /*
+     * Three states, not two.
+     *
+     * A surface with no violations but unresolved checks has NOT been verified, and
+     * labelling it `pass` beside a genuinely clean one is the confident false pass
+     * this product exists to avoid — quieter than a crash and far more damaging,
+     * because somebody signs a conformance statement on the strength of it.
+     */
+    const needsReview = rows.filter((row) => row.violations === 0 && row.incomplete > 0);
+    const clean = rows.filter((row) => row.violations === 0 && row.incomplete === 0);
+    lines.push(heading(style, 'Surfaces'));
+    /*
+     * The violation count goes in the gutter and the verdict goes in the words.
+     *
+     * FAIL and pass are spelled out rather than shown by colour or by the number
+     * alone: a row has to state its own verdict when the escapes are stripped, and
+     * "0" is not a verdict — a surface with no violations might equally never have
+     * been looked at.
+     */
+    const labelWidth = Math.min(Math.max(...rows.map((row) => row.label.length)), Math.max(20, width - 40));
+    for (const row of failing) {
+        const rules = row.rules.join(', ');
+        const room = width - labelWidth - 20;
+        /*
+         * The rule names wrap to their own line rather than being cut with an
+         * ellipsis, for the same reason the audit's route list is never capped: the
+         * rule id is the actionable half of the row. "color-contrast, target-…" tells
+         * a reader there is a second problem and refuses to say which, which is worse
+         * than either naming it or staying silent.
+         */
+        if (rules.length <= room) {
+            lines.push(figureLine(style, row.violations, `FAIL  ${row.label.padEnd(labelWidth)}  ${style.dim(rules)}`));
+        }
+        else {
+            lines.push(figureLine(style, row.violations, `FAIL  ${row.label}`));
+            lines.push(...continuationLines(style, rules, width));
+        }
+    }
+    /*
+     * Clean surfaces are listed too, and in full.
+     *
+     * They are the evidence half of "accessibility evidence": a surface looked at
+     * and found clean is a fact worth having, and it is the only thing separating a
+     * passing surface from one nothing ever visited. Trimming the list to keep the
+     * output short would delete exactly that distinction.
+     */
+    for (const row of needsReview) {
+        lines.push(figureLine(style, row.incomplete, `CHECK ${row.label.padEnd(labelWidth)}  ${style.dim('unresolved')}`));
+    }
+    for (const row of clean) {
+        lines.push(figureLine(style, '', `pass  ${row.label}`));
+    }
+    lines.push(...perfLines(envelope, style, width));
+    const groups = groupFindings(envelope);
+    /*
+     * A rule entry reads like an instruction, not an inventory (reworked on
+     * feedback from the first real Eos run, 2026-08-19): what is wrong, what to
+     * change, where — then how widespread. The first cut led with an exhaustive
+     * surface list, which told a reader how big the problem was while refusing
+     * to say what to do about it, and duplicated SURFACES above line for line.
+     */
+    const ruleEntry = (group) => {
+        const criteria = group.criteria.length > 0 ? ` — WCAG ${group.criteria.join(', ')}` : '';
+        const entry = [
+            figureLine(style, group.nodes, `${style.bold(group.ruleId)}  ${style.dim(`${group.impact}${criteria}`)}`),
+        ];
+        // What to change: axe's own fix text (or the setsquare check's), from a
+        // representative node — the ratios and names are that node's, the shape of
+        // the fix is every node's.
+        if (group.failureSummary) {
+            entry.push(...continuationLines(style, group.failureSummary, width));
+        }
+        // Where: a bounded sample of failing selectors. The full set survives in
+        // report.html and run.json; a terminal entry needs enough to open devtools.
+        if (group.selectors.length > 0) {
+            entry.push(...continuationLines(style, `where: ${group.selectors.join('  ')}` +
+                (group.selectorsTruncated ? '  … every selector is in report.html' : ''), width));
+        }
+        /*
+         * How widespread. "13 of 100 surfaces (13%)" is what keeps four thousand
+         * findings readable — and past a handful of surfaces the list is capped to
+         * the worst three by element count, because every failing surface is
+         * ALREADY listed under SURFACES with this rule against it. Repeating all
+         * sixteen here was information nobody could act on twice. Incomplete
+         * groups get no share: the share counts detected failures, and an
+         * unresolved check is not one.
+         */
+        const share = group.status === 'violation' ? ruleSurfaceShare(envelope, group.ruleId) : undefined;
+        const lead = share
+            ? `on ${surfaceShare(share.affected, share.total)}`
+            : `on ${group.contexts.length} surface${group.contexts.length === 1 ? '' : 's'}`;
+        const ranked = [...group.contextNodes].sort((a, b) => b.nodes - a.nodes || a.label.localeCompare(b.label));
+        const spread = ranked.length <= 6
+            ? `${lead}: ${ranked.map((c) => c.label).join(', ')}`
+            : `${lead}, worst: ` +
+                ranked
+                    .slice(0, 3)
+                    .map((c) => `${c.label} (${n(c.nodes)})`)
+                    .join(', ') +
+                ` — all ${ranked.length} rows are marked under SURFACES above`;
+        entry.push(...continuationLines(style, spread, width));
+        if (group.helpUrl)
+            entry.push(...continuationLines(style, group.helpUrl, width));
+        entry.push('');
+        return entry;
+    };
+    const failingRuleGroups = groups.filter((group) => group.status === 'violation');
+    const review = groups.filter((group) => group.status === 'incomplete');
+    if (failingRuleGroups.length > 0) {
+        lines.push('');
+        lines.push(heading(style, 'Rules failing'));
+        for (const group of failingRuleGroups)
+            lines.push(...ruleEntry(group));
+    }
+    if (review.length > 0) {
+        /*
+         * A section of its own, not a parenthesis on the failure list.
+         *
+         * `incomplete` is axe saying "I could not decide" — most often contrast over
+         * a background image or a gradient, where the ratio is genuinely
+         * uncomputable from the DOM. These are neither passes nor failures, and
+         * listing them beside violations invites both of the available mistakes:
+         * treating them as broken and panicking, or treating them as fine and
+         * shipping. They are the one category that REQUIRES a person, which is worth
+         * saying plainly given we sell evidence.
+         */
+        lines.push('');
+        lines.push(heading(style, 'Needs review'));
+        lines.push(...continuationLines(style, 'axe could not decide these by itself — usually contrast over an image or a ' +
+            'gradient. Not passes and not failures; a person has to look.', width));
+        lines.push('');
+        for (const group of review)
+            lines.push(...ruleEntry(group));
+    }
+    /*
+     * The P1b blocks, after the accessibility findings and before the trailer.
+     *
+     * Ordered by how surprising they are rather than by how new: page runtime first,
+     * because "a 500 happened and no test noticed" is the thing a reader most needs
+     * to not miss; then what could not be checked, which qualifies everything above
+     * it; then the cross-surface findings, coverage, and last the run's own
+     * mechanics.
+     *
+     * Every block is `undefined` when it has nothing to say, so a run without the
+     * sidecar — or an envelope written before the capability — renders exactly as it
+     * did before rather than growing empty headings.
+     */
+    for (const block of insightBlocks(envelope, {
+        ...(input.declaredAxes ? { declaredAxes: input.declaredAxes } : {}),
+        ...(input.unmeasuredAxes ? { unmeasuredAxes: input.unmeasuredAxes } : {}),
+        ...(input.suite ? { suite: input.suite } : {}),
+        ...(input.overhead ? { overhead: input.overhead } : {}),
+    })) {
+        lines.push(...figureBlock(style, block.heading, block.figures, block.notes, width));
+    }
+    lines.push(...trailer());
+    return join(lines);
+}
+/**
+ * Join the assembled lines, collapsing any run of blank lines to one.
+ *
+ * Sections are built independently and several of them end with a blank line, so
+ * the seams accumulate — three blank lines appeared between the last rule and the
+ * warnings. Fixing it at each seam means every future section has to remember the
+ * convention; fixing it here means none of them do, and the sections stay
+ * composable.
+ */
+function join(lines) {
+    const out = [];
+    for (const line of lines) {
+        if (line === '' && out[out.length - 1] === '')
+            continue;
+        out.push(line);
+    }
+    return out.join('\n');
+}
+/**
+ * Pillar 3, finally visible.
+ *
+ * The SDK has captured navigation timing, LCP and CLS on every scan since P1-4.4
+ * and the summary never mentioned it. A run of Eos's legal lane held timings for
+ * six page loads and said nothing — a whole pillar of the product, measured and
+ * discarded at the last step.
+ *
+ * Three rules, each an honesty constraint rather than a layout one:
+ *
+ *   1. **Say what these numbers are.** They are CI-lab timings from an idle
+ *      runner, usually against localhost. They are not what a user on a phone
+ *      experiences, and a report that let someone believe otherwise would be
+ *      worse than one that stayed silent.
+ *   2. **Absent is not zero.** LCP and CLS reach a `PerformanceObserver` in
+ *      Chromium and simply do not exist in Firefox or WebKit, so a run across
+ *      three engines has loads with no vitals at all. Reporting those as 0ms
+ *      would invent the best possible score out of missing data.
+ *   3. **The threshold is named, not implied.** "Slowest LCP 348ms" means nothing
+ *      to a reader who does not carry 2,500ms in their head.
+ */
+function perfLines(envelope, style, width) {
+    const rows = perfRows(envelope);
+    if (rows.length === 0)
+        return [];
+    const lines = ['', heading(style, 'Performance')];
+    lines.push(figureLine(style, rows.length, `page load${rows.length === 1 ? '' : 's'} measured  ${style.dim('(CI lab, not real users)')}`));
+    const withLcp = rows.filter((row) => row.lcpMs !== undefined);
+    const withCls = rows.filter((row) => row.cls !== undefined);
+    const slowLcp = withLcp.filter((row) => (row.lcpMs ?? 0) > GOOD_LCP_MS);
+    const highCls = withCls.filter((row) => (row.cls ?? 0) > GOOD_CLS);
+    const worstLcp = withLcp[0];
+    if (worstLcp?.lcpMs !== undefined) {
+        lines.push(figureLine(style, `${n(Math.round(worstLcp.lcpMs))}ms`, `slowest LCP — ${worstLcp.label}`));
+    }
+    const worstCls = [...withCls].sort((a, b) => (b.cls ?? 0) - (a.cls ?? 0))[0];
+    if (worstCls?.cls !== undefined) {
+        lines.push(figureLine(style, worstCls.cls.toFixed(2), `worst CLS — ${worstCls.label}`));
+    }
+    if (slowLcp.length > 0) {
+        lines.push('');
+        lines.push(figureLine(style, slowLcp.length, `over the ${n(GOOD_LCP_MS)}ms LCP threshold`));
+        for (const row of slowLcp) {
+            lines.push(figureLine(style, `${n(Math.round(row.lcpMs ?? 0))}ms`, style.dim(row.label)));
+        }
+    }
+    if (highCls.length > 0) {
+        lines.push('');
+        lines.push(figureLine(style, highCls.length, `over the ${GOOD_CLS.toFixed(2)} CLS threshold`));
+        for (const row of highCls) {
+            lines.push(figureLine(style, (row.cls ?? 0).toFixed(2), style.dim(row.label)));
+        }
+    }
+    if (slowLcp.length === 0 && highCls.length === 0 && withLcp.length > 0) {
+        lines.push(...continuationLines(style, `All within the ${n(GOOD_LCP_MS)}ms LCP and ${GOOD_CLS.toFixed(2)} CLS thresholds ` +
+            'that Google treats as good — measured in a lab, so treat them as a floor.', width));
+    }
+    const missing = rows.length - withLcp.length;
+    if (missing > 0) {
+        /*
+         * Named rather than left as a gap in the arithmetic. LCP and CLS reach a
+         * PerformanceObserver in Chromium and do not exist at all in Firefox or
+         * WebKit, so a three-engine run legitimately has loads with no vitals — and a
+         * reader who notices the numbers not adding up deserves the reason.
+         */
+        lines.push(...continuationLines(style, `${missing} load${missing === 1 ? '' : 's'} reported no LCP: Firefox and WebKit do not ` +
+            'implement it, so it is absent rather than zero.', width));
+    }
+    return lines;
+}
+/** The `<1%` rule, matching `ruleSurfaceShare`: a real problem never rounds to nothing. */
+function sharePercent(affected, total) {
+    if (total === 0 || affected === 0)
+        return '0%';
+    const rounded = Math.round((affected / total) * 100);
+    return rounded === 0 ? '<1%' : `${rounded}%`;
+}
+/** `13 of 100 surfaces (13%)` — count first, scale second, neither replacing the other. */
+function surfaceShare(affected, total) {
+    return `${n(affected)} of ${n(total)} surface${total === 1 ? '' : 's'} (${sharePercent(affected, total)})`;
+}
+/**
+ * The conformance verdict, and the vocabulary discipline that governs it.
+ *
+ * Nothing here may say anyone "is" or "can claim" a level. WCAG conformance is
+ * defined per full page and complete process, includes requirements no scanner
+ * evaluates, and most criteria have failure modes no automated rule covers. So
+ * every sentence is about DETECTION: failures detected, no failures detected in
+ * what was scanned, checks that were not run. The moment this section says
+ * "conformant", somebody signs a statement on the strength of it — and the test
+ * suite greps for exactly that word to keep it out.
+ */
+function conformanceLines(input, style, width) {
+    const summary = conformanceSummary(input.envelope, {
+        ...(input.criterionRules ? { criterionRules: input.criterionRules } : {}),
+    });
+    if (summary.surfacesScanned === 0)
+        return [];
+    const lines = ['', heading(style, 'Conformance — WCAG 2.2')];
+    lines.push(...continuationLines(style, 'Includes every 2.0 and 2.1 criterion. Automated checks cover only part of WCAG, ' +
+        'so this is evidence about what was scanned, never a conformance claim.', width));
+    lines.push('');
+    const criterionRow = (rollup) => [
+        figureLine(style, rollup.failedSurfaces.length, `${style.bold(`${rollup.criterion} ${rollup.name}`)}  ${style.dim(`FAIL on ${surfaceShare(rollup.failedSurfaces.length, rollup.totalSurfaces)}`)}`),
+        ...continuationLines(style, rollup.failingRules.join(', '), width),
+    ];
+    for (const level of summary.levels) {
+        if (level.level === 'AAA' && !level.assessed) {
+            lines.push(...continuationLines(style, "Level AAA not assessed — AAA is opt-in; run with wcag: 'AAA' to include it.", width));
+            if (level.failing.length > 0) {
+                // Observed in passing on an AA-target run. Still evidence — hiding an
+                // observed failure would be the dishonest direction — but the verdict
+                // above never speaks to an unassessed level.
+                lines.push(...continuationLines(style, `${level.failing.length === 1 ? 'One AAA criterion' : `${level.failing.length} AAA criteria`} failed in passing:`, width));
+                for (const rollup of level.failing)
+                    lines.push(...criterionRow(rollup));
+            }
+            continue;
+        }
+        if (level.failing.length > 0) {
+            lines.push(figureLine(style, level.failing.length, `Level ${level.level.padEnd(3)}  failures detected — ` +
+                `${level.failing.length === 1 ? 'one criterion' : `${level.failing.length} criteria`} failing`));
+            for (const rollup of level.failing)
+                lines.push(...criterionRow(rollup));
+        }
+        else {
+            lines.push(figureLine(style, '', `Level ${level.level.padEnd(3)}  no failures detected in what was scanned`));
+        }
+        if (level.assessedScans) {
+            lines.push(...continuationLines(style, `AAA was assessed on ${level.assessedScans.aaa} of ${level.assessedScans.total} scans — ` +
+                'the rest looked with AA rules only.', width));
+        }
+    }
+    if (summary.removed.length > 0) {
+        for (const rollup of summary.removed) {
+            lines.push(...continuationLines(style, `${rollup.criterion} ${rollup.name} failed on ${surfaceShare(rollup.failedSurfaces.length, rollup.totalSurfaces)} — ` +
+                'removed in WCAG 2.2, so it counts toward no level here.', width));
+        }
+    }
+    lines.push('');
+    /*
+     * The fix breakdown, fact-shaped. "To clear detected Level A failures" and
+     * never "to reach Level A": fixing what automation found removes what
+     * automation found, and nothing more.
+     */
+    const { verdict } = summary;
+    if (verdict.failuresDetectedAt) {
+        const at = verdict.failuresDetectedAt;
+        const ids = (level) => summary.levels
+            .find((l) => l.level === level)
+            .failing.map((r) => r.criterion)
+            .join(', ');
+        let sentence = `To clear the detected Level ${at} failures, fix: ${verdict.nextFixes
+            .map((r) => r.criterion)
+            .join(', ')}.`;
+        const aa = summary.levels.find((l) => l.level === 'AA');
+        const aaa = summary.levels.find((l) => l.level === 'AAA');
+        if (at === 'A' && aa.failing.length > 0)
+            sentence += ` Then for AA: ${ids('AA')}.`;
+        if (at !== 'AAA' && aaa.assessed && aaa.failing.length > 0)
+            sentence += ` Then for AAA: ${ids('AAA')}.`;
+        lines.push(...continuationLines(style, sentence, width));
+    }
+    else if (verdict.noFailuresDetectedAt) {
+        lines.push(...continuationLines(style, `No Level ${verdict.noFailuresDetectedAt} violations detected across ` +
+            `${n(summary.surfacesScanned)} surface${summary.surfacesScanned === 1 ? '' : 's'} ` +
+            '(automated checks only).', width));
+    }
+    /*
+     * The coverage ledger. An auditor's first question about an untested
+     * criterion is "did you not check it, or can it not be checked?" — with the
+     * engine's rule map the two are split; without it the wording is combined,
+     * never wrong.
+     */
+    const counted = summary.levels.filter((level) => level.level !== 'AAA' || level.assessed);
+    const rulesPassed = counted.reduce((sum, level) => sum + level.rulesPassed.length, 0);
+    const cantTell = counted.reduce((sum, level) => sum + level.cantTell.length, 0);
+    const inapplicable = counted.reduce((sum, level) => sum + level.inapplicable.length, 0);
+    const untested = counted.flatMap((level) => level.untested);
+    if (rulesPassed > 0) {
+        lines.push(figureLine(style, rulesPassed, 'criteria: every automated rule passed — evidence, not conformance'));
+    }
+    if (cantTell > 0) {
+        lines.push(figureLine(style, cantTell, 'criteria need a person — automation could not decide'));
+    }
+    if (inapplicable > 0) {
+        // EARL's inapplicable, spelled out: the checks RAN and the pages contain
+        // nothing these criteria regulate — coverage, not a gap.
+        lines.push(figureLine(style, inapplicable, 'criteria: checks ran, nothing to check on these pages (no such content)'));
+    }
+    if (untested.length > 0) {
+        if (input.criterionRules) {
+            const noCheck = untested.filter((r) => r.untestedReason === 'notAutomatable').length;
+            const notRun = untested.filter((r) => r.untestedReason === 'notRun').length;
+            if (noCheck > 0)
+                lines.push(figureLine(style, noCheck, 'criteria have no automated check in this engine'));
+            if (notRun > 0)
+                lines.push(figureLine(style, notRun, 'criteria have checks that did not run here'));
+        }
+        else {
+            lines.push(figureLine(style, untested.length, 'criteria not automatically checked in this run'));
+        }
+    }
+    const anyFailure = summary.levels.some((level) => level.failing.length > 0);
+    if (anyFailure) {
+        lines.push(...continuationLines(style, 'A surface counts as failing if it fails in any scanned state or theme.', width));
+    }
+    /*
+     * Envelopes written before pass rows carried WCAG identity cannot credit any
+     * criterion as passed, however clean the run was. Said out loud, because the
+     * alternative reading — "nothing passed" — is wrong in the damaging
+     * direction.
+     */
+    const passRows = input.envelope.scans.flatMap((scan) => scan.passes);
+    if (passRows.length > 0 && passRows.every((pass) => !pass.wcag)) {
+        lines.push(...continuationLines(style, 'Rule passes in this run carry no WCAG mapping — it predates the mapping, so no ' +
+            'criterion can show its rules as passed. Re-run the suite to get full credit.', width));
+    }
+    return lines;
+}
+/**
+ * The criteria × surfaces matrix, drawn without box-drawing.
+ *
+ * Aligned single-glyph columns and a numbered legend instead of borders: it
+ * reads as a grid on screen and degrades to aligned text everywhere else. The
+ * glyph alone carries the meaning — colour never does — and the legend spells
+ * every glyph out in words, because ✓ at criterion level means "every
+ * automated rule passed", which is not the same claim as "passed".
+ *
+ * Steps aside by itself when the run has more surfaces than the width budget
+ * fits (the budget is the [80,120] clamp, not the raw terminal), and entirely
+ * when the customer chose `grid: 'rows'`.
+ */
+function gridLines(input, style, width) {
+    if ((input.grid ?? 'matrix') === 'rows')
+        return [];
+    const grid = conformanceGrid(input.envelope);
+    if (grid.rows.length === 0 || grid.surfaces.length === 0)
+        return [];
+    // ASCII glyphs whenever styling is off: the same environments that lose
+    // colour (CI, pipes, NO_COLOR) are the ones where glyph rendering is least
+    // trustworthy, and the fallback must be decided by something a test can set.
+    const glyph = style.on
+        ? { failed: '✗', cantTell: '?', rulesPassed: '✓', inapplicable: '–', untested: '·' }
+        : { failed: 'F', cantTell: '?', rulesPassed: 'P', inapplicable: '-', untested: '.' };
+    const indent = '  ';
+    const idWidth = Math.max(...grid.rows.map((row) => row.criterion.length));
+    const nameWidth = Math.min(Math.max(...grid.rows.map((row) => row.name.length)), 28);
+    const colWidth = Math.max(2, String(grid.surfaces.length).length + 1);
+    const labelWidth = idWidth + 2 + nameWidth + 2 + 4;
+    const needed = indent.length + labelWidth + grid.surfaces.length * colWidth;
+    if (needed > width) {
+        return [
+            '',
+            ...continuationLines(style, `The full criteria × surfaces grid needs more room than this summary has ` +
+                `(${grid.surfaces.length} surfaces) — see the HTML report for the matrix.`, width),
+        ];
+    }
+    const lines = ['', heading(style, 'Conformance grid')];
+    // Column header: surface indices, resolved by the legend below the matrix.
+    const header = indent +
+        ' '.repeat(labelWidth) +
+        grid.surfaces.map((_, i) => String(i + 1).padEnd(colWidth)).join('');
+    lines.push(style.dim(header.trimEnd()));
+    for (const row of grid.rows) {
+        const name = row.name.length > nameWidth ? `${row.name.slice(0, nameWidth - 1)}…` : row.name;
+        const marker = row.removedIn22 ? '—' : row.level;
+        const label = row.criterion.padEnd(idWidth) + '  ' + name.padEnd(nameWidth) + '  ' + marker.padEnd(4);
+        const cells = row.cells.map((cell) => glyph[cell.state].padEnd(colWidth)).join('');
+        lines.push((indent + label + cells).trimEnd());
+    }
+    lines.push('');
+    lines.push(...continuationLines(style, `${glyph.failed} failed   ${glyph.cantTell} needs a person   ` +
+        `${glyph.rulesPassed} every automated rule passed   ` +
+        `${glyph.inapplicable} nothing to check here   ${glyph.untested} untested`, width));
+    lines.push(...continuationLines(style, grid.surfaces.map((surface, i) => `${i + 1} ${surface}`).join('   '), width));
+    return lines;
+}
+function warningLines(warnings, width, quality, envelope) {
+    const style = createStyle();
+    const notes = [];
+    /*
+     * Coverage inequality, disclosed. A surface scanned in five states and one
+     * scanned once look identical in every count above, and error/loading/empty
+     * states are exactly where regressions hide — a form is usually fine until
+     * it is showing validation errors. One line, only when it applies.
+     */
+    if (envelope && envelope.scans.length > 0) {
+        const coverage = stateCoverage(envelope);
+        const defaultOnly = coverage.filter((row) => row.defaultOnly).length;
+        if (defaultOnly > 0) {
+            notes.push(`${defaultOnly} of ${coverage.length} surface${coverage.length === 1 ? ' has' : 's have'} evidence in ` +
+                'their default state only — error, loading and empty states are where regressions hide. ' +
+                'setsquare.scan(page, surface, { state }) captures them.');
+        }
+    }
+    /*
+     * A scan the ceiling cut short is weaker evidence, and it must say so.
+     *
+     * The settle heuristic waits for a page to go quiet and gives up after five
+     * seconds. Giving up is the right behaviour — scanning something is better than
+     * scanning nothing, and skipping silently would be worse than either — but the
+     * result is a scan of a page that was still moving. A clean result from one of
+     * those is a result to be suspicious of, and the whole reason the schema carries
+     * settle diagnostics is so that suspicion survives to the reader instead of
+     * dying in the envelope.
+     */
+    if (quality && quality.ceiling > 0) {
+        notes.push(`${quality.ceiling} scan${quality.ceiling === 1 ? ' was' : 's were'} cut short after ` +
+            'waiting 5s for the page to settle, so they describe a page that was still ' +
+            'changing. Treat a clean result from those as weaker evidence.');
+    }
+    if (warnings.length === 0 && notes.length === 0)
+        return [];
+    const lines = ['', heading(style, 'Worth knowing')];
+    for (const note of notes)
+        lines.push(...continuationLines(style, note, width));
+    /*
+     * A section of its own rather than a footnote.
+     *
+     * These are the things the run could NOT tell you — surfaces visited but never
+     * scanned, records that could not be read back. Missing evidence must never be
+     * quieter than present evidence, because a reader who skims past it concludes
+     * the run covered more than it did.
+     */
+    for (const warning of warnings) {
+        lines.push(...continuationLines(style, warning, width));
+    }
+    return lines;
+}
+/**
+ * The closing block (decision 12, 2026-08-18).
+ *
+ * Replaces the single quiet info line the plan originally specified. Every
+ * constraint that made that right survives — once per run, at the very end, never
+ * per-surface, never interrupting findings, suppressible — and only the length
+ * relaxes, because one line cannot carry *why* and a bare URL reads as an advert.
+ *
+ * Built from THIS run's numbers so it explains rather than sells, and it names
+ * only things the free layer structurally cannot do. Nothing is removed from the
+ * local tool to create the paid one, and this block must never imply otherwise.
+ */
+function promoLines(input, count, width) {
+    if (!input.promo)
+        return [];
+    const failingRules = new Set(input.envelope.scans.flatMap((scan) => scan.findings.filter((f) => f.status === 'violation').map((f) => f.ruleId))).size;
+    const subject = failingRules > 0
+        ? `${failingRules} rule${failingRules === 1 ? '' : 's'} failing across ${count.surfaces} surface${count.surfaces === 1 ? '' : 's'}`
+        : `${count.surfaces} clean surface${count.surfaces === 1 ? '' : 's'}`;
+    return [
+        '',
+        // Wrapped like everything else: a block that overflows the terminal is a
+        // block that looks broken, and this one is read on every single run.
+        ...wrap(`${subject}, this run only. Setsquare Cloud adds what a local tool cannot:`, width - 4, '').map((line) => `  ${line}`),
+        '    · is this better or worse than last week?  (local runs keep no history)',
+        '    · which change introduced each one, on the PR that did it',
+        '    · the root cause behind repeats, grouped instead of repeated',
+        `    ${PLATFORM_URL}`,
+        '',
+    ];
+}
+/** The conformance block in markdown — same facts as the terminal, same vocabulary rules. */
+function markdownConformance(input) {
+    const summary = conformanceSummary(input.envelope, {
+        ...(input.criterionRules ? { criterionRules: input.criterionRules } : {}),
+    });
+    if (summary.surfacesScanned === 0)
+        return [];
+    const lines = ['### Conformance — WCAG 2.2', ''];
+    const { verdict } = summary;
+    if (verdict.failuresDetectedAt) {
+        lines.push(`**Failures detected at Level ${verdict.failuresDetectedAt}.** To clear them, fix: ` +
+            `${verdict.nextFixes.map((r) => `${r.criterion} ${r.name}`).join(', ')}. ` +
+            'Automated checks cover only part of WCAG.');
+    }
+    else if (verdict.noFailuresDetectedAt) {
+        lines.push(`**No Level ${verdict.noFailuresDetectedAt} violations detected** across ` +
+            `${summary.surfacesScanned} surfaces (automated checks only).`);
+    }
+    lines.push('');
+    const withEvidence = summary.levels.flatMap((level) => level.level === 'AAA' && !level.assessed
+        ? level.failing
+        : [...level.failing, ...level.cantTell, ...level.rulesPassed, ...level.inapplicable]);
+    if (withEvidence.length > 0) {
+        lines.push('| Criterion | Level | State | Surfaces |');
+        lines.push('|---|---|---|---|');
+        const stateWords = {
+            failed: 'FAIL',
+            cantTell: 'needs a person',
+            rulesPassed: 'rules passed',
+            inapplicable: 'nothing to check',
+            untested: 'untested',
+        };
+        for (const rollup of [...withEvidence].sort((a, b) => a.criterion.localeCompare(b.criterion, 'en', { numeric: true }))) {
+            const surfaces = rollup.state === 'failed'
+                ? `${rollup.failedSurfaces.length} of ${rollup.totalSurfaces} (${sharePercent(rollup.failedSurfaces.length, rollup.totalSurfaces)})`
+                : `${rollup.totalSurfaces}`;
+            lines.push(`| ${rollup.criterion} ${rollup.name} | ${rollup.level} | ${stateWords[rollup.state]} | ${surfaces} |`);
+        }
+        lines.push('');
+    }
+    const aaa = summary.levels.find((level) => level.level === 'AAA');
+    if (aaa && !aaa.assessed) {
+        lines.push("Level AAA not assessed — AAA is opt-in; run with `wcag: 'AAA'` to include it.");
+        lines.push('');
+    }
+    return lines;
+}
+/** Markdown, for pasting into Slack, an issue, or an LLM prompt. */
+export function renderMarkdown(input) {
+    const { envelope } = input;
+    const count = totals(envelope);
+    const lines = [];
+    const tests = testOutcomes(envelope, input.plannedTests);
+    lines.push('## Accessibility evidence');
+    lines.push('');
+    if (envelope.results.length > 0) {
+        const parts = [`**${tests.passed}** passed`];
+        if (tests.failed > 0)
+            parts.push(`**${tests.failed}** failed`);
+        if (tests.flaky > 0)
+            parts.push(`**${tests.flaky}** flaky`);
+        if (tests.skipped > 0)
+            parts.push(`**${tests.skipped}** skipped`);
+        if (tests.notRun)
+            parts.push(`**${tests.notRun}** never ran`);
+        lines.push(`Playwright: ${parts.join(', ')}.`);
+        lines.push('');
+    }
+    if (count.scans === 0) {
+        lines.push('**No surfaces were scanned.** This is not a clean result — nothing was looked at.');
+        return lines.join('\n');
+    }
+    lines.push(`Scanned **${count.surfaces}** surfaces in **${count.themes}** themes against ` +
+        `WCAG 2.2 ${envelope.scans[0]?.wcagTarget ?? 'AA'} — ` +
+        `**${count.violations}** violations, **${count.incomplete}** needing review, ` +
+        `**${count.passes}** passing checks.`);
+    lines.push('');
+    /*
+     * The same conformance facts as the terminal, in markdown syntax. Always
+     * criterion rows, never the matrix — a glyph grid pastes as soup.
+     */
+    lines.push(...markdownConformance(input));
+    const groups = groupFindings(envelope);
+    if (groups.length > 0) {
+        lines.push('| Impact | Rule | Elements | Surfaces | WCAG |');
+        lines.push('|---|---|---|---|---|');
+        for (const group of groups) {
+            const rule = group.helpUrl ? `[${group.ruleId}](${group.helpUrl})` : group.ruleId;
+            const status = group.status === 'incomplete' ? ' *(needs review)*' : '';
+            lines.push(`| ${group.impact} | ${rule}${status} | ${group.nodes} | ` +
+                `${group.contexts.length} | ${group.criteria.join(', ') || '—'} |`);
+        }
+        lines.push('');
+        /*
+         * Surfaces listed under the table rather than inside it. A context list can be
+         * long, and a markdown table cell that wraps is a markdown table nobody can
+         * read — including in the PR comments this format is rehearsing for.
+         */
+        for (const group of groups) {
+            lines.push(`- **${group.ruleId}**: ${group.contexts.join(', ')}`);
+            if (group.failureSummary)
+                lines.push(`  - ${group.failureSummary}`);
+            if (group.selectors.length > 0) {
+                lines.push(`  - where: ${group.selectors.map((sel) => `\`${sel}\``).join(', ')}` +
+                    (group.selectorsTruncated ? ' …' : ''));
+            }
+        }
+        lines.push('');
+    }
+    // Surfaces, in the same order and with the same completeness as the terminal
+    // form. The two renderers differ in syntax and in nothing else — a pasted
+    // summary that says less than the one on screen is a summary people stop
+    // trusting.
+    lines.push('### Surfaces');
+    lines.push('');
+    for (const row of surfaceRows(envelope)) {
+        lines.push(row.violations > 0
+            ? `- **FAIL** ${row.label} — ${row.violations} elements: ${row.rules.join(', ')}`
+            : `- pass ${row.label}`);
+    }
+    const perf = perfRows(envelope);
+    if (perf.length > 0) {
+        const withLcp = perf.filter((row) => row.lcpMs !== undefined);
+        const slow = withLcp.filter((row) => (row.lcpMs ?? 0) > GOOD_LCP_MS);
+        lines.push('');
+        lines.push('### Performance');
+        lines.push('');
+        lines.push(`**${perf.length}** page loads measured in CI (lab timings, not real users). ` +
+            (withLcp.length === 0
+                ? 'No LCP reported — Firefox and WebKit do not implement it.'
+                : slow.length === 0
+                    ? `All within the ${GOOD_LCP_MS}ms LCP threshold.`
+                    : `**${slow.length}** over the ${GOOD_LCP_MS}ms LCP threshold: ` +
+                        slow.map((row) => `${row.label} (${Math.round(row.lcpMs ?? 0)}ms)`).join(', ')));
+    }
+    /*
+     * The same blocks as the terminal, in markdown. Same wording function, so the
+     * two formats cannot come to say different things about the same run — which is
+     * the rule `groupLines` established and this batch had to honour five more times.
+     */
+    for (const block of insightBlocks(envelope, {
+        ...(input.declaredAxes ? { declaredAxes: input.declaredAxes } : {}),
+        ...(input.unmeasuredAxes ? { unmeasuredAxes: input.unmeasuredAxes } : {}),
+        ...(input.suite ? { suite: input.suite } : {}),
+        ...(input.overhead ? { overhead: input.overhead } : {}),
+    })) {
+        lines.push('');
+        lines.push(`### ${block.heading}`);
+        lines.push('');
+        for (const figure of block.figures) {
+            lines.push(`- **${figure.value}** ${figure.label}`);
+            for (const note of figure.notes ?? [])
+                lines.push(`  - ${note}`);
+        }
+        for (const note of block.notes) {
+            lines.push('');
+            lines.push(note);
+        }
+    }
+    if (tests.flaky > 0) {
+        const flaky = flakeNotes(input.suite);
+        if (flaky.length > 0) {
+            lines.push('');
+            lines.push('### Flaky');
+            lines.push('');
+            for (const note of flaky)
+                lines.push(`- ${note}`);
+        }
+    }
+    lines.push('');
+    lines.push(`Evidence: \`${input.envelopePath}\``);
+    if (input.htmlReportPath)
+        lines.push(`Report: \`${input.htmlReportPath}\``);
+    if (input.screensPath)
+        lines.push(`Screens: \`${input.screensPath}\``);
+    if (input.reportPath)
+        lines.push(`Playwright report: \`${input.reportPath}\``);
+    if (input.group) {
+        lines.push('');
+        lines.push('### Run group');
+        lines.push('');
+        for (const line of groupLines(input.group))
+            lines.push(`- ${line}`);
+    }
+    return lines.join('\n');
+}
+export function render(input, format, columns) {
+    if (format === 'markdown')
+        return renderMarkdown(input);
+    if (format === 'json') {
+        // Machine output stays machine output: no closing block, no notes, nothing a
+        // parser has to skip.
+        return JSON.stringify({
+            totals: totals(input.envelope),
+            findings: groupFindings(input.envelope),
+            conformance: conformanceSummary(input.envelope, {
+                ...(input.criterionRules ? { criterionRules: input.criterionRules } : {}),
+            }),
+            // Machine consumers need the coverage verdict most of all: a parser
+            // that cannot see "partial" will treat a half-merged group as a run.
+            ...(input.group ? { group: input.group } : {}),
+            /*
+             * The insight blocks as DATA, not as rendered lines.
+             *
+             * A machine consumer wants the figures, and the notes carry the caveats
+             * that stop it drawing the wrong conclusion from them — particularly
+             * "these counts are per engine and deliberately not totalled" and "this
+             * is time spent, not time added". Dropping the notes here would leave a
+             * parser holding numbers with none of the constraints attached.
+             */
+            insights: insightBlocks(input.envelope, {
+                ...(input.declaredAxes ? { declaredAxes: input.declaredAxes } : {}),
+                ...(input.unmeasuredAxes ? { unmeasuredAxes: input.unmeasuredAxes } : {}),
+                ...(input.suite ? { suite: input.suite } : {}),
+                ...(input.overhead ? { overhead: input.overhead } : {}),
+            }),
+        }, null, 2);
+    }
+    return renderText(input, columns);
+}
+//# sourceMappingURL=summary.js.map