@setsquare/review-sdk 0.0.1 → 0.1.1

package/dist/settle.js

@@ -26,9 +26,44 @@
  *
  * Every scan carries its settle diagnostics, so a suspicious result is
  * identifiable in the evidence rather than silently trusted.
+ *
+ * **WHAT HAPPENS TO A PAGE THAT SETTLES LATE**, recorded here because #137 asked
+ * whether it is scanned or dropped and observed that it was currently neither —
+ * an accident of where the ceiling happened to fall. It is not an accident, and
+ * the behaviour is worth stating rather than changing:
+ *
+ *   - Still on screen when the test ends → **scanned, twice if needed.** The
+ *     ceiling fires and scans the skeleton, then the teardown sweep re-scans
+ *     because the mutation counter shows the page changed since. Dedupe keeps the
+ *     better one. Proved rather than asserted: `fixtures/.../public.spec.ts`
+ *     drives `/slow?delay=7000`, two seconds past the ceiling, and the surviving
+ *     evidence carries both of that route's late violations.
+ *   - Navigated away from mid-render → **cannot be scanned by anything.** It is
+ *     gone before teardown arrives. Recorded in the unscannable ledger rather
+ *     than dropped silently, and raising `settleTimeoutMs` does not help, because
+ *     the limit there is the test's pace and not our window.
+ *
+ * So the ceiling costs no evidence on its own. What costs evidence is a test
+ * moving on, and that is the customer's to change or accept.
  */
 /** Name of the page-side callback the SDK exposes. Namespaced; documented pollution. */
 export const MUTATION_TOTAL = '__setsquareMutationTotal';
+/**
+ * Whether this page has EVER met the quiet definition since its last navigation.
+ *
+ * Read at teardown, where no settle signal exists to consult: the teardown sweep
+ * scans whatever is on screen, and until this flag there was no way to tell a
+ * page that had finished rendering from one caught mid-flight. Both produced a
+ * scan that looked identical, and the checks making whole-page ABSENCE claims —
+ * "nothing on this page says where you are" — were as confident on one as the
+ * other. Friction record run 4 watched 2.4.8 flip between two runs of unchanged
+ * code for exactly that reason.
+ *
+ * A flag rather than a measurement, because measuring at teardown means sampling
+ * mutations, waiting `quietMs`, and sampling again — half a second added to every
+ * page of every test, to learn something the detector already knew.
+ */
+export const WENT_QUIET = '__setsquareWentQuiet';
 export const SETTLE_BINDING = '__setsquareSettle';
 export const DEFAULT_SETTLE = {
     /*
@@ -83,6 +118,9 @@ export function settleScript(config) {
   // Monotonic across the document lifetime, NOT reset per navigation: the
   // teardown sweep uses it to decide whether a page changed after being scanned.
   window.__setsquareMutationTotal = 0;
+  // Reset on every navigation below: "this page went quiet" must never be
+  // inherited by the next URL, which is the one way this flag could lie.
+  window.${WENT_QUIET} = false;
   let via = 'load';
 
   const report = (reason) => {
@@ -114,8 +152,10 @@ export function settleScript(config) {
       // readyState is checked HERE rather than as a precondition, so a page that
       // goes quiet while still loading keeps waiting instead of being scanned
       // half-built.
-      if (document.readyState === 'complete') report('quiet');
-      else scheduleQuiet();
+      if (document.readyState === 'complete') {
+        window.${WENT_QUIET} = true;
+        report('quiet');
+      } else scheduleQuiet();
     }, QUIET);
   };
 
@@ -124,6 +164,7 @@ export function settleScript(config) {
     fired = false;
     navigatedAt = Date.now();
     mutations = 0;
+    window.${WENT_QUIET} = false;
     clearTimeout(ceilingTimer);
     ceilingTimer = setTimeout(() => report('ceiling'), CEILING);
     scheduleQuiet();

package/dist/settle.js.map

@@ -1 +1 @@
-{"version":3,"file":"settle.js","sourceRoot":"","sources":["../src/settle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,wFAAwF;AACxF,MAAM,CAAC,MAAM,cAAc,GAAG,0BAA0B,CAAC;AAEzD,MAAM,CAAC,MAAM,cAAc,GAAG,mBAAmB,CAAC;AAqBlD,MAAM,CAAC,MAAM,cAAc,GAAiB;IAC1C;;;;;;;OAOG;IACH,OAAO,EAAE,GAAG;IACZ;;;;;;;;OAQG;IACH,eAAe,EAAE,IAAI;CACtB,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,YAAY,CAAC,MAAoB;IAC/C,OAAO;;;;;;;kBAOS,MAAM,CAAC,OAAO;oBACZ,MAAM,CAAC,eAAe;;;;;;;;;;;;;;;;;;;;;;0BAsBhB,cAAc;iBACvB,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6D9B,CAAC;AACF,CAAC"}
+{"version":3,"file":"settle.js","sourceRoot":"","sources":["../src/settle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAEH,wFAAwF;AACxF,MAAM,CAAC,MAAM,cAAc,GAAG,0BAA0B,CAAC;AAEzD;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,sBAAsB,CAAC;AAEjD,MAAM,CAAC,MAAM,cAAc,GAAG,mBAAmB,CAAC;AAqBlD,MAAM,CAAC,MAAM,cAAc,GAAiB;IAC1C;;;;;;;OAOG;IACH,OAAO,EAAE,GAAG;IACZ;;;;;;;;OAQG;IACH,eAAe,EAAE,IAAI;CACtB,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,YAAY,CAAC,MAAoB;IAC/C,OAAO;;;;;;;kBAOS,MAAM,CAAC,OAAO;oBACZ,MAAM,CAAC,eAAe;;;;;;;;;;;;WAY/B,UAAU;;;;;;;;;;;;;0BAaK,cAAc;iBACvB,cAAc;;;;;;;;;;;;;;;;;;;iBAmBd,UAAU;;;;;;;;;;;aAWd,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkCtB,CAAC;AACF,CAAC"}

package/dist/summary.d.ts

@@ -157,6 +157,21 @@ export interface SurfaceRow {
      */
     incomplete: number;
     rules: string[];
+    /**
+     * The same coordinates WITHOUT the viewport.
+     *
+     * The HTML report groups these rows into a row group per band and prints the
+     * band's sizes on its heading, so repeating the size on all thirty-six rows
+     * underneath is noise the grouping was supposed to remove. It is only noise
+     * where the band holds ONE size, which the renderer knows and this does not —
+     * so both strings are carried and the renderer picks.
+     */
+    shortLabel: string;
+    /** The width this row was assessed at, when the run controlled one. */
+    viewport?: {
+        width: number;
+        height: number;
+    };
 }
 /**
  * One row per scanned context, worst first.
@@ -175,6 +190,19 @@ export interface EvidenceQuality {
     teardown: number;
     /** Scans the settle ceiling cut short. Weaker evidence, and named as such. */
     ceiling: number;
+    /**
+     * The longest a ceiling scan actually waited, and the most DOM mutations any
+     * of them counted.
+     *
+     * Both measured, neither configured. The note that reads these used to say
+     * "after waiting 5s", which is the DEFAULT — so a suite that raised
+     * `settleTimeoutMs` was told a number it had changed. And "a page that was
+     * still changing" without saying how much leaves the reader with one action
+     * ("raise the timeout") when there are two: a page 200 mutations from quiet
+     * will settle if given longer, and a page with a poller never will.
+     */
+    ceilingWaitedMs: number;
+    ceilingMutations: number;
 }
 /**
  * How much the findings are worth, as distinct from what they say.
@@ -193,6 +221,13 @@ export interface EvidenceQuality {
 export declare function evidenceQuality(envelope: RunIngestRequest): EvidenceQuality;
 export interface PerfRow {
     label: string;
+    /** The same coordinates without the viewport — see `SurfaceRow.shortLabel`. */
+    shortLabel: string;
+    /** The width this page load happened at, when the run controlled one. */
+    viewport?: {
+        width: number;
+        height: number;
+    };
     lcpMs?: number;
     cls?: number;
     loadMs?: number;

package/dist/summary.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"summary.d.ts","sourceRoot":"","sources":["../src/summary.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"summary.d.ts","sourceRoot":"","sources":["../src/summary.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAoBtE,OAAO,EAA6B,KAAK,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7E,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE5D;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,+EAA+E;IAC/E,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,KAAK,EAAE,OAAO,CAAC;IACf;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,IAAI,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;IACzB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC;IACxD;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,YAAY,CAAC;CACtB;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,sEAAsE;IACtE,WAAW,EAAE,MAAM,CAAC;IACpB,yEAAyE;IACzE,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,2DAA2D;IAC3D,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,oDAAoD;IACpD,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,UAAU,GAAG,SAAS,GAAG,SAAS,CAAC;CAC9C;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,EAAE,CA+CxD;AAID,UAAU,SAAS;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,UAAU,CAAC,QAAQ,CAAC,CAAC;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,4EAA4E;IAC5E,YAAY,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACjD;;;;;OAKG;IACH,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,kBAAkB,EAAE,OAAO,CAAC;IAC5B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AA+CD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,gBAAgB,GAAG,SAAS,EAAE,CAkErE;AASD,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;;OAMG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB;;;;;;;;OAQG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB,uEAAuE;IACvE,QAAQ,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CAC9C;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,gBAAgB,GAAG,UAAU,EAAE,CA+CpE;AAED,MAAM,WAAW,eAAe;IAC9B,kEAAkE;IAClE,aAAa,EAAE,MAAM,CAAC;IACtB,sEAAsE;IACtE,KAAK,EAAE,MAAM,CAAC;IACd,sEAAsE;IACtE,QAAQ,EAAE,MAAM,CAAC;IACjB,8EAA8E;IAC9E,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;;;;;;OAUG;IACH,eAAe,EAAE,MAAM,CAAC;IACxB,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,gBAAgB,GAAG,eAAe,CAmC3E;AAED,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,+EAA+E;IAC/E,UAAU,EAAE,MAAM,CAAC;IACnB,yEAAyE;IACzE,QAAQ,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAeD;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,GAAG,OAAO,EAAE,CAwB9D;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,uEAAuE;IACvE,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,gBAAgB,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,YAAY,CA4C5F;AAED,wBAAgB,MAAM,CAAC,QAAQ,EAAE,gBAAgB,GAAG,SAAS,CA+B5D;AAED,kEAAkE;AAClE,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAEjE;AAgCD;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,YAAY,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CA2cxE;AAsyBD,oEAAoE;AACpE,wBAAgB,cAAc,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CA6J1D;AAED,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,UAAU,GAAG,MAAM,CAAC;AAEzD,wBAAgB,MAAM,CAAC,KAAK,EAAE,YAAY,EAAE,MAAM,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAsC3F"}

package/dist/summary.js

@@ -40,12 +40,43 @@ export function groupLines(group) {
 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]
+/**
+ * `job-editor · dark` — the coordinates a person can act on.
+ *
+ * The viewport joins them ONLY when the run holds more than one, and that
+ * condition is the whole design. Dedupe keys on the viewport unconditionally,
+ * because collapsing two widths into one row loses evidence; a label is read by
+ * a person, and `home · light · 1280×720` on every row of a suite that has one
+ * viewport is thirteen characters of noise repeated forty times. Where there
+ * genuinely are several, the label is the only thing telling two otherwise
+ * identical rows apart — and without it the surfaces table merges them by label
+ * and reports one surface's failures three times over.
+ */
+function contextLabel(context, withViewport = false) {
+    const viewport = withViewport && context.viewport
+        ? `${context.viewport.width}\u00d7${context.viewport.height}`
+        : undefined;
+    return [context.surface, context.theme, context.persona, context.state, viewport]
         .filter(Boolean)
         .join(' · ');
 }
+/**
+ * Whether this run looked at more than one viewport.
+ *
+ * Computed per envelope rather than carried on the scan, because it is a fact
+ * about the RUN: one scan cannot know whether it was the only width looked at.
+ */
+function hasSeveralViewports(envelope) {
+    const seen = new Set();
+    for (const scan of envelope.scans) {
+        const viewport = scan.context.viewport;
+        if (viewport)
+            seen.add(`${viewport.width}x${viewport.height}`);
+        if (seen.size > 1)
+            return true;
+    }
+    return false;
+}
 /**
  * Collapse findings to one row per (rule, status).
  *
@@ -55,11 +86,12 @@ function contextLabel(context) {
  */
 export function groupFindings(envelope) {
     const groups = new Map();
+    const withViewport = hasSeveralViewports(envelope);
     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);
+            const label = contextLabel(scan.context, withViewport);
             if (existing) {
                 existing.nodes += finding.targets.nodeCount;
                 if (!existing.contexts.includes(label))
@@ -144,11 +176,25 @@ export function surfaceRows(envelope) {
      * the tool repeating itself.
      */
     const merged = new Map();
+    const withViewport = hasSeveralViewports(envelope);
     for (const scan of envelope.scans) {
-        const label = contextLabel(scan.context);
+        const label = contextLabel(scan.context, withViewport);
         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: [] };
+        const row = merged.get(label) ?? {
+            label,
+            shortLabel: contextLabel(scan.context),
+            violations: 0,
+            incomplete: 0,
+            rules: [],
+            /*
+             * Carried as data as well as inside the label, because the report GROUPS
+             * on it. The label is for a person to read and a string cannot be grouped
+             * on without parsing it back, which is the kind of thing that works until
+             * a surface name contains a multiplication sign.
+             */
+            ...(scan.context.viewport ? { viewport: scan.context.viewport } : {}),
+        };
         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();
@@ -184,6 +230,8 @@ export function evidenceQuality(envelope) {
     let quiet = 0;
     let teardown = 0;
     let ceiling = 0;
+    let ceilingWaitedMs = 0;
+    let ceilingMutations = 0;
     for (const scan of envelope.scans) {
         for (const pass of scan.passes ?? [])
             rules.add(pass.ruleId);
@@ -200,12 +248,17 @@ export function evidenceQuality(envelope) {
                 break;
             case 'ceiling':
                 ceiling += 1;
+                // The worst case rather than an average: one page pinned at the ceiling
+                // is the thing worth knowing about, and a mean over a healthy run would
+                // hide it.
+                ceilingWaitedMs = Math.max(ceilingWaitedMs, scan.settle.sinceNavMs);
+                ceilingMutations = Math.max(ceilingMutations, scan.settle.mutations);
                 break;
             default:
                 break;
         }
     }
-    return { rulesAssessed: rules.size, quiet, teardown, ceiling };
+    return { rulesAssessed: rules.size, quiet, teardown, ceiling, ceilingWaitedMs, ceilingMutations };
 }
 /*
  * Google's "good" thresholds for the two Core Web Vitals we can measure in a lab.
@@ -231,14 +284,17 @@ const GOOD_CLS = 0.1;
  */
 export function perfRows(envelope) {
     const byVisit = new Map();
+    const withViewport = hasSeveralViewports(envelope);
     for (const scan of envelope.scans) {
         if (!scan.perf)
             continue;
-        const key = scan.visitRef ?? `${scan.testId}:${contextLabel(scan.context)}`;
+        const key = scan.visitRef ?? `${scan.testId}:${contextLabel(scan.context, withViewport)}`;
         if (byVisit.has(key))
             continue;
         byVisit.set(key, {
-            label: contextLabel(scan.context),
+            label: contextLabel(scan.context, withViewport),
+            shortLabel: contextLabel(scan.context),
+            ...(scan.context.viewport ? { viewport: scan.context.viewport } : {}),
             ...(scan.perf.lcpMs !== undefined ? { lcpMs: scan.perf.lcpMs } : {}),
             ...(scan.perf.cls !== undefined ? { cls: scan.perf.cls } : {}),
             ...(scan.perf.loadMs !== undefined ? { loadMs: scan.perf.loadMs } : {}),
@@ -484,8 +540,27 @@ export function renderText(input, columns) {
          */
         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));
+        /*
+         * Name the cause when the run knows it, and only then.
+         *
+         * "Usually the suite never opened a page, or every test finished before its
+         * page settled" is a guess offered in place of a fact the envelope is
+         * holding. On a lane run with `SETSQUARE_AUTOSCAN=0` both halves of that
+         * sentence are false and both describe a broken suite, which is how a
+         * perfectly healthy functional lane came to read as a failure.
+         *
+         * "This is not a clean result" stays either way. Nothing was looked at, and
+         * that is true whether or not the reason is reassuring.
+         */
+        const offRows = (envelope.unscanned ?? []).filter((row) => row.reason === 'autoscan-disabled');
+        const allOff = offRows.length > 0 && offRows.length === (envelope.unscanned ?? []).length;
+        lines.push(...continuationLines(style, allOff
+            ? 'This is not a clean result — it means nothing was looked at. Automatic ' +
+                'scanning was off for this run (SETSQUARE_AUTOSCAN=0), so the surfaces ' +
+                'below were visited and never scanned. That is the configuration working ' +
+                'as asked; it is not a fault in the suite.'
+            : '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);
     }
@@ -829,6 +904,17 @@ function conformanceLines(input, style, width) {
     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),
+        /*
+         * A cross-surface criterion has no failing RULE to name — the finding is
+         * the comparison itself — so the row would otherwise be a bare percentage.
+         * Both disagreeing surfaces are named, because "the navigation is
+         * inconsistent" without saying between which two pages sends the reader to
+         * look at everything.
+         */
+        ...(rollup.consistency?.disagreements ?? [])
+            .slice(0, 2)
+            .flatMap((row) => continuationLines(style, row.detail, width)),
+        ...(rollup.consistency?.note ? continuationLines(style, rollup.consistency.note, width) : []),
     ];
     for (const level of summary.levels) {
         if (level.level === 'AAA' && !level.assessed) {
@@ -849,9 +935,28 @@ function conformanceLines(input, style, width) {
             for (const rollup of level.failing)
                 lines.push(...criterionRow(rollup));
         }
+        else if (level.assertedFailing.length > 0) {
+            // Not "no failures detected": a level whose own declared test is red is
+            // neither clean nor failed, and saying "no failures detected" over the
+            // top of it would be the dishonest direction.
+            lines.push(figureLine(style, level.assertedFailing.length, `Level ${level.level.padEnd(3)}  no failures detected, but ` +
+                `${level.assertedFailing.length === 1 ? 'a criterion your suite covers' : `${level.assertedFailing.length} criteria your suite covers`} did not pass`));
+        }
         else {
             lines.push(figureLine(style, '', `Level ${level.level.padEnd(3)}  no failures detected in what was scanned`));
         }
+        /*
+         * Listed whether or not the level also has detected failures. These are
+         * the customer's own assertions, so the row says whose claim it is and
+         * names the test — the only useful next action is opening that file.
+         */
+        for (const rollup of level.assertedFailing) {
+            lines.push(...continuationLines(style, `${rollup.criterion} ${rollup.name} — your own test for it did not pass` +
+                (rollup.assertions && rollup.assertions.notUpheld.length > 0
+                    ? `: ${rollup.assertions.notUpheld.join(', ')}`
+                    : '') +
+                '. Setsquare did not detect this; your suite declared it.', width));
+        }
         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));
@@ -887,6 +992,15 @@ function conformanceLines(input, style, width) {
             sentence += ` Then for AAA: ${ids('AAA')}.`;
         lines.push(...continuationLines(style, sentence, width));
     }
+    else if (verdict.assertionsFailingAt) {
+        // The third outcome. Neither "we found failures" — we found none — nor
+        // "no failures detected", which would be publishing a clean line over the
+        // top of the suite's own red check.
+        lines.push(...continuationLines(style, `No Level ${verdict.assertionsFailingAt} violations detected, but ` +
+            `${verdict.failingAssertions.length === 1 ? 'a criterion your suite declares it covers' : `${verdict.failingAssertions.length} criteria your suite declares it covers`} ` +
+            `did not pass: ${verdict.failingAssertions.map((r) => r.criterion).join(', ')}. ` +
+            'That is your assertion, not our finding — but nothing here says the level is clean.', width));
+    }
     else if (verdict.noFailuresDetectedAt) {
         lines.push(...continuationLines(style, `No Level ${verdict.noFailuresDetectedAt} violations detected across ` +
             `${n(summary.surfacesScanned)} surface${summary.surfacesScanned === 1 ? '' : 's'} ` +
@@ -902,6 +1016,7 @@ function conformanceLines(input, style, width) {
     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 assertedBySuite = counted.flatMap((level) => level.assertedBySuite);
     const untested = counted.flatMap((level) => level.untested);
     if (rulesPassed > 0) {
         lines.push(figureLine(style, rulesPassed, 'criteria: every automated rule passed — evidence, not conformance'));
@@ -914,17 +1029,69 @@ function conformanceLines(input, style, width) {
         // 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 (assertedBySuite.length > 0) {
+        /*
+         * Deliberately worded as the customer's claim and placed AFTER the
+         * rule-based figures, because it is the weakest positive line on the
+         * summary. It is also the only line here whose strength we cannot assess:
+         * it is exactly as good as the tests behind it.
+         */
+        lines.push(figureLine(style, assertedBySuite.length, 'criteria covered by your own tests — your assertion, no rule ran'));
+    }
     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'));
+        const noRule = untested.filter((r) => r.untestedReason === 'noRuleCanDecide');
+        if (noRule.length > 0) {
+            /*
+             * The most useful line on this block, and the one the product's central
+             * claim rests on. "No automated rule can decide these, whatever anyone
+             * builds" is a concrete floor under "automated evidence is not
+             * conformance" — and a customer who sees it understands what they still
+             * owe an auditor, which is a better thing to have told them than a tick.
+             */
+            lines.push(figureLine(style, noRule.length, 'criteria no automated rule can decide — what you still owe an auditor'));
         }
-        else {
-            lines.push(figureLine(style, untested.length, 'criteria not automatically checked in this run'));
+        const compared = untested.filter((r) => r.untestedReason === 'singleSurface');
+        if (compared.length > 0) {
+            /*
+             * Its own line, and never folded into "no automated check". These
+             * criteria HAVE a check; fewer than two pages carried the thing it
+             * compares, so there was nothing to compare. Reporting them as
+             * uncheckable would be wrong in the direction that sells the product
+             * short — one more page with the evidence on it is all they need.
+             *
+             * THE WORDING USED TO SAY "this run had one surface", AND THAT WAS A
+             * CLAIM, not a description. It printed unchanged on an eighteen-surface
+             * run of this repository's own site, two lines under "18 surfaces
+             * scanned" — because the reason is fewer than two surfaces carrying the
+             * EVIDENCE, not fewer than two surfaces. 3.2.6 needs at least two pages
+             * that actually offer a help mechanism; a hundred pages without one
+             * still give it nothing to compare. The schema's own note on
+             * `singleSurface` had it right all along.
+             */
+            lines.push(figureLine(style, compared.length, 'criteria compare pages against each other — fewer than two pages carried the evidence'));
+        }
+        const skipped = untested.filter((r) => r.untestedReason === 'declarationSkipped').length;
+        if (skipped > 0) {
+            // Not folded into "no automated check": the criterion had a check, it
+            // was the suite's own, and it did not run. That is a suite problem, and
+            // reporting it as a tooling limitation would hide it.
+            lines.push(figureLine(style, skipped, 'criteria your suite covers were skipped and did not run'));
+        }
+        const rest = untested.filter((r) => r.untestedReason !== 'declarationSkipped' &&
+            r.untestedReason !== 'singleSurface' &&
+            r.untestedReason !== 'noRuleCanDecide');
+        if (rest.length > 0) {
+            if (input.criterionRules) {
+                const noCheck = rest.filter((r) => r.untestedReason === 'notAutomatable').length;
+                const notRun = rest.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, rest.length, 'criteria not automatically checked in this run'));
+            }
         }
     }
     const anyFailure = summary.levels.some((level) => level.failing.length > 0);
@@ -966,9 +1133,31 @@ function gridLines(input, style, width) {
     // 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.
+    //
+    // The two declared states get their own glyphs and never borrow ✓ or ✗.
+    // A cell that means "your test says so" must not look like a cell that
+    // means "a rule ran" — that flattening is the exact thing the state was
+    // added to prevent, and a shared glyph would reintroduce it in the one
+    // rendering most people actually read.
     const glyph = style.on
-        ? { failed: '✗', cantTell: '?', rulesPassed: '✓', inapplicable: '–', untested: '·' }
-        : { failed: 'F', cantTell: '?', rulesPassed: 'P', inapplicable: '-', untested: '.' };
+        ? {
+            failed: '✗',
+            assertedFailing: '⊗',
+            cantTell: '?',
+            rulesPassed: '✓',
+            inapplicable: '–',
+            assertedBySuite: '⊙',
+            untested: '·',
+        }
+        : {
+            failed: 'F',
+            assertedFailing: 'f',
+            cantTell: '?',
+            rulesPassed: 'P',
+            inapplicable: '-',
+            assertedBySuite: 'y',
+            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);
@@ -998,7 +1187,10 @@ function gridLines(input, style, width) {
     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));
+        `${glyph.inapplicable} nothing to check here   ` +
+        `${glyph.assertedBySuite} covered by your own test   ` +
+        `${glyph.assertedFailing} your own test for it did not pass   ` +
+        `${glyph.untested} untested`, width));
     lines.push(...continuationLines(style, grid.surfaces.map((surface, i) => `${i + 1} ${surface}`).join('   '), width));
     return lines;
 }
@@ -1032,9 +1224,28 @@ function warningLines(warnings, width, quality, envelope) {
      * 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.');
+        /*
+         * Say WHOSE window it was, and WHAT the page was doing in it.
+         *
+         * The old sentence said "after waiting 5s", which is the default — a suite
+         * that raised `settleTimeoutMs` was quoted a number it had changed. And it
+         * described "a page that was still changing" without the one figure that
+         * tells a reader which of the two available actions is theirs: a page a few
+         * mutations from quiet settles if given longer, and a page with a poller
+         * never will, and no timeout helps the second.
+         *
+         * Both numbers are measured off the scans themselves rather than read from
+         * configuration, which also means they stay true if the window is changed
+         * per project.
+         */
+        const waited = `${(quality.ceilingWaitedMs / 1000).toFixed(1)}s`;
+        notes.push(`${quality.ceiling} scan${quality.ceiling === 1 ? ' was' : 's were'} cut short by our ` +
+            `settle window — the longest waited ${waited} and the page was still changing, with ` +
+            `${quality.ceilingMutations.toLocaleString('en-GB')} DOM mutation` +
+            `${quality.ceilingMutations === 1 ? '' : 's'} counted since it loaded. Treat a clean ` +
+            'result from those as weaker evidence. If the page settles and simply needs longer, ' +
+            'raise `settleTimeoutMs`; if something polls or animates forever, no window will help ' +
+            'and the scan is of a moving page by nature.');
     }
     if (warnings.length === 0 && notes.length === 0)
         return [];
@@ -1105,16 +1316,25 @@ function markdownConformance(input) {
     }
     lines.push('');
     const withEvidence = summary.levels.flatMap((level) => level.level === 'AAA' && !level.assessed
-        ? level.failing
-        : [...level.failing, ...level.cantTell, ...level.rulesPassed, ...level.inapplicable]);
+        ? [...level.failing, ...level.assertedFailing]
+        : [
+            ...level.failing,
+            ...level.assertedFailing,
+            ...level.cantTell,
+            ...level.rulesPassed,
+            ...level.inapplicable,
+            ...level.assertedBySuite,
+        ]);
     if (withEvidence.length > 0) {
         lines.push('| Criterion | Level | State | Surfaces |');
         lines.push('|---|---|---|---|');
         const stateWords = {
             failed: 'FAIL',
+            assertedFailing: 'your test for it did not pass',
             cantTell: 'needs a person',
             rulesPassed: 'rules passed',
             inapplicable: 'nothing to check',
+            assertedBySuite: 'covered by your own test',
             untested: 'untested',
         };
         for (const rollup of [...withEvidence].sort((a, b) => a.criterion.localeCompare(b.criterion, 'en', { numeric: true }))) {