@setsquare/review-sdk 0.0.1 → 0.1.0

package/dist/checks/shortcuts.js

@@ -0,0 +1,196 @@
+import { CHARACTER_KEY_SHORTCUTS_HELP_URL } from '../links.js';
+import { sanitiseLabel } from '../sanitise.js';
+/**
+ * WCAG 2.1.4 Character Key Shortcuts (A): a single-character shortcut with no
+ * way to turn it off or remap it makes a page unusable for anyone using speech
+ * input, because every dictated word is a volley of shortcuts.
+ *
+ * A small rule and a real failure — and the only one in this package that
+ * needs to run BEFORE the customer's own code. There is no way to enumerate a
+ * page's event listeners after the fact: `getEventListeners` is a DevTools
+ * API and does not exist in page script. So the only route is to wrap
+ * `addEventListener` at init time and watch what gets registered.
+ *
+ * ---------------------------------------------------------------------------
+ * **Opt-in, and off by default, because of the footprint.**
+ *
+ * Everything else this SDK does happens after a page has loaded and can be
+ * undone. This patches a DOM method before any of the customer's scripts run,
+ * for the whole life of the page. Even proven inert, that is a larger presence
+ * in someone's application than a scanner has any business having by default —
+ * and "it is only a pass-through" is exactly the reasoning that precedes a
+ * subtle break in someone else's product.
+ *
+ * So it is a choice, `keyShortcuts: true`, and while it is off the criterion
+ * reports as a check that exists and did not run here, which is what it is.
+ *
+ * **Inertness, concretely.** The wrapper records `(type, target)` and the key
+ * literals it can read out of the handler's own source, then delegates with
+ * the ORIGINAL arguments — never a wrapped listener. That last part is what
+ * keeps `removeEventListener` working: a wrapped listener is a different
+ * function object and would never match, so a page that adds and removes a
+ * handler would silently keep it forever. The fixture asserts exactly that.
+ * ---------------------------------------------------------------------------
+ */
+export const SETSQUARE_SHORTCUTS_CHECK_VERSION = 'setsquare-shortcuts@1';
+export const KEY_SHORTCUTS_RULE_ID = 'setsquare-key-shortcuts';
+/** Handlers to look at. Beyond this a page is instrumenting, not shortcutting. */
+const MAX_HANDLERS = 40;
+/**
+ * Installed before any page script. See the class comment for why this is
+ * opt-in; see `fixture.ts` for where it is installed.
+ *
+ * A source string rather than a function, because `addInitScript` serialises
+ * it and a closure over anything in this module would not survive.
+ */
+export const KEY_LISTENER_SCRIPT = `
+(() => {
+  const found = [];
+  Object.defineProperty(window, '__setsquareKeyListeners', {
+    value: found,
+    // Non-enumerable so it does not appear in a customer's own iteration over
+    // window, and non-writable so page code cannot clobber it by accident.
+    enumerable: false,
+    writable: false,
+    configurable: true,
+  });
+
+  const KEY_EVENTS = new Set(['keydown', 'keypress', 'keyup']);
+  const MODIFIER = /\\b(ctrlKey|metaKey|altKey|shiftKey|getModifierState)\\b/;
+
+  /*
+   * Which keys a handler reacts to, read out of its own source.
+   *
+   * The instrumentation can see THAT a key listener exists and never which key
+   * it cares about — so without this the finding would be "this page has a
+   * keydown handler", which is true of most of the web and useful to nobody.
+   * Reading the source is a heuristic and is treated as one: everything this
+   * rule reports is needs-review.
+   *
+   * A handler that consults a modifier is not what 2.1.4 is about, so it is
+   * left alone. That is most of the false positives.
+   */
+  const keysIn = (source) => {
+    if (typeof source !== 'string' || source.length === 0) return [];
+    if (source.indexOf('[native code]') !== -1) return [];
+    if (MODIFIER.test(source)) return [];
+
+    const keys = new Set();
+    const literal = /(?:\\.key\\s*={2,3}\\s*|case\\s+)['"]([^'"\\\\]{1})['"]/g;
+    let match;
+    while ((match = literal.exec(source)) !== null) {
+      const key = match[1];
+      // Printable, single character, not whitespace. Enter, Escape and Tab are
+      // multi-character names and fall out here, which is right: 2.1.4 is
+      // about character keys.
+      if (key.trim().length === 1) keys.add(key);
+    }
+
+    const code = /(?:keyCode|which)\\s*={2,3}\\s*(\\d{2,3})/g;
+    while ((match = code.exec(source)) !== null) {
+      const value = Number(match[1]);
+      // Letters and digits only. The named keys have codes too, and reporting
+      // Escape as a character shortcut would be wrong.
+      if (value >= 48 && value <= 57) keys.add(String(value - 48));
+      else if (value >= 65 && value <= 90) keys.add(String.fromCharCode(value).toLowerCase());
+    }
+
+    return [...keys];
+  };
+
+  const original = EventTarget.prototype.addEventListener;
+  EventTarget.prototype.addEventListener = function (type, listener, options) {
+    try {
+      if (KEY_EVENTS.has(type) && (this === document || this === window) && found.length < 40) {
+        let source = '';
+        try {
+          source = typeof listener === 'function' ? Function.prototype.toString.call(listener) : '';
+        } catch {}
+        const keys = keysIn(source);
+        if (keys.length > 0) {
+          found.push({ type, target: this === window ? 'window' : 'document', keys });
+        }
+      }
+    } catch {}
+
+    /*
+     * The original arguments, never a wrapper. A wrapped listener is a
+     * different function object, so removeEventListener would never match it
+     * and a page that adds and removes a handler would silently keep it for
+     * ever. That is the failure this line exists to prevent.
+     */
+    return original.call(this, type, listener, options);
+  };
+})();
+`;
+/**
+ * Read what the instrumentation saw. Returns nothing when it was never
+ * installed, which is the honest answer for an opt-in check that is off.
+ */
+export async function runKeyShortcuts(page) {
+    try {
+        const rows = await page.evaluate(() => {
+            const found = window['__setsquareKeyListeners'];
+            return Array.isArray(found) ? found.slice(0, 40) : undefined;
+        });
+        if (rows === undefined)
+            return {};
+        return keyShortcutEvidence(rows);
+    }
+    catch {
+        return {};
+    }
+}
+const SHORTCUTS_WCAG = { criteria: ['2.1.4'], level: 'A', versionTags: [] };
+/**
+ * The verdict, and it is always needs-review or inapplicable — never a
+ * violation, and the reason is worth stating rather than assuming.
+ *
+ * 2.1.4 is satisfied if the shortcut can be turned off, remapped, or is only
+ * active when a specific component has focus. All three are page-level
+ * affordances: the first two live in a settings screen we are not looking at,
+ * and the third is a property of the handler's own logic. We can see that a
+ * handler compares against `j`; we cannot see whether the user was ever
+ * offered a way to stop it. Reporting a violation from what we CAN see would
+ * be asserting the part we cannot.
+ */
+export function keyShortcutEvidence(rows) {
+    const usable = rows.filter((row) => row.keys.length > 0).slice(0, MAX_HANDLERS);
+    if (usable.length === 0) {
+        // The instrumentation ran and found no unmodified character handler. That
+        // is a real observation about the page, not an absence of one.
+        return { inapplicable: { ruleId: KEY_SHORTCUTS_RULE_ID, wcag: SHORTCUTS_WCAG } };
+    }
+    const keys = [...new Set(usable.flatMap((row) => row.keys))].sort();
+    const first = usable[0];
+    return {
+        finding: {
+            ruleId: KEY_SHORTCUTS_RULE_ID,
+            status: 'incomplete',
+            impact: 'moderate',
+            wcag: SHORTCUTS_WCAG,
+            helpUrl: CHARACTER_KEY_SHORTCUTS_HELP_URL,
+            evidence: {
+                failureSummary: `A ${first.type} handler on ${first.target} reacts to the character key(s) ` +
+                    `${keys.map((key) => `"${key}"`).join(', ')} without consulting a modifier. ` +
+                    `${usable.length} handler(s) found. WCAG 2.1.4 is satisfied if the shortcut can be ` +
+                    `turned off, remapped, or is only active when a specific component has focus — all ` +
+                    `three are affordances this check cannot see, so it is not reported as a failure. ` +
+                    `A person confirms one of them exists. This matters most for speech input, where ` +
+                    `every dictated word is a volley of these.`,
+            },
+            // Selectors are the wrong shape for a document-level handler, so the
+            // targets are the handlers themselves, named by what they listen to.
+            targets: {
+                nodeCount: usable.length,
+                selectors: usable
+                    .slice(0, 10)
+                    .map((handler) => `${handler.target} ${handler.type} [${handler.keys.join(' ')}]`)
+                    .map((label) => sanitiseLabel(label))
+                    .filter((label) => label !== undefined),
+                selectorsTruncated: usable.length > 10,
+            },
+        },
+    };
+}
+//# sourceMappingURL=shortcuts.js.map

package/dist/checks/shortcuts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shortcuts.js","sourceRoot":"","sources":["../../src/checks/shortcuts.ts"],"names":[],"mappings":"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"}

package/dist/checks/versions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"versions.d.ts","sourceRoot":"","sources":["../../src/checks/versions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAO9C;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,EAAE,CAKnE;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,wBAAwB,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAO1E,CAAC"}
+{"version":3,"file":"versions.d.ts","sourceRoot":"","sources":["../../src/checks/versions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAa9C;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,EAAE,CAanE;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,wBAAwB,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAyB1E,CAAC"}

package/dist/checks/versions.js

@@ -1,5 +1,11 @@
 import { readingLevelEnabled } from '../runtime.js';
 import { SETSQUARE_DYNAMIC_CHECKS_VERSION } from './dynamic.js';
+import { SETSQUARE_FOCUS_CHECKS_VERSION } from './focus.js';
+import { SETSQUARE_KEYBOARD_CHECKS_VERSION } from './keyboard.js';
+import { SETSQUARE_CONTEXT_CHECK_VERSION } from './context-change.js';
+import { SETSQUARE_REFLOW_CHECK_VERSION } from './reflow.js';
+import { SETSQUARE_HEURISTICS_VERSION } from './heuristics.js';
+import { SETSQUARE_SHORTCUTS_CHECK_VERSION } from './shortcuts.js';
 import { SETSQUARE_RULE_PACK_VERSION } from './rule-pack.js';
 import { READING_LEVEL_CHECK_VERSION } from '../reading-level.js';
 /**
@@ -15,7 +21,15 @@ import { READING_LEVEL_CHECK_VERSION } from '../reading-level.js';
  * teach people to ignore the warning that exists to catch real drift.
  */
 export function setsquareCheckVersions(policy) {
-    const versions = [SETSQUARE_DYNAMIC_CHECKS_VERSION];
+    const versions = [
+        SETSQUARE_DYNAMIC_CHECKS_VERSION,
+        SETSQUARE_FOCUS_CHECKS_VERSION,
+        SETSQUARE_KEYBOARD_CHECKS_VERSION,
+        SETSQUARE_REFLOW_CHECK_VERSION,
+        SETSQUARE_CONTEXT_CHECK_VERSION,
+        SETSQUARE_SHORTCUTS_CHECK_VERSION,
+        SETSQUARE_HEURISTICS_VERSION,
+    ];
     if (policy.target === 'AAA')
         versions.push(SETSQUARE_RULE_PACK_VERSION);
     if (readingLevelEnabled())
@@ -41,5 +55,23 @@ export const SETSQUARE_CHECK_CRITERIA = new Map([
     ['setsquare-target-size-aaa', ['2.5.5']],
     ['setsquare-visual-presentation', ['1.4.8']],
     ['setsquare-link-purpose', ['2.4.9']],
+    ['setsquare-focus-obscured', ['2.4.11']],
+    ['setsquare-focus-obscured-enhanced', ['2.4.12']],
+    ['setsquare-focus-visible', ['2.4.7']],
+    ['setsquare-focus-appearance', ['2.4.13']],
+    ['setsquare-keyboard-trap', ['2.1.2']],
+    ['setsquare-reflow', ['1.4.10']],
+    ['setsquare-on-focus', ['3.2.1']],
+    ['setsquare-on-input', ['3.2.2']],
+    ['setsquare-key-shortcuts', ['2.1.4']],
+    ['setsquare-meaningful-sequence', ['1.3.2']],
+    ['setsquare-sensory-characteristics', ['1.3.3']],
+    ['setsquare-headings-and-labels', ['2.4.6']],
+    ['setsquare-section-headings', ['2.4.10']],
+    ['setsquare-abbreviations', ['3.1.4']],
+    ['setsquare-location', ['2.4.8']],
+    ['setsquare-captions', ['1.2.1', '1.2.2', '1.2.3']],
+    ['setsquare-captions-aa', ['1.2.4', '1.2.5']],
+    ['setsquare-captions-aaa', ['1.2.6', '1.2.7', '1.2.8', '1.2.9']],
 ]);
 //# sourceMappingURL=versions.js.map

package/dist/checks/versions.js.map

@@ -1 +1 @@
-{"version":3,"file":"versions.js","sourceRoot":"","sources":["../../src/checks/versions.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,EAAE,gCAAgC,EAAE,MAAM,cAAc,CAAC;AAChE,OAAO,EAAE,2BAA2B,EAAE,MAAM,gBAAgB,CAAC;AAE7D,OAAO,EAAE,2BAA2B,EAAE,MAAM,qBAAqB,CAAC;AAElE;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,sBAAsB,CAAC,MAAkB;IACvD,MAAM,QAAQ,GAAG,CAAC,gCAAgC,CAAC,CAAC;IACpD,IAAI,MAAM,CAAC,MAAM,KAAK,KAAK;QAAE,QAAQ,CAAC,IAAI,CAAC,2BAA2B,CAAC,CAAC;IACxE,IAAI,mBAAmB,EAAE;QAAE,QAAQ,CAAC,IAAI,CAAC,2BAA2B,CAAC,CAAC;IACtE,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAA2C,IAAI,GAAG,CAAC;IACtF,CAAC,wBAAwB,EAAE,CAAC,QAAQ,CAAC,CAAC;IACtC,CAAC,2BAA2B,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IACjD,CAAC,yBAAyB,EAAE,CAAC,OAAO,CAAC,CAAC;IACtC,CAAC,2BAA2B,EAAE,CAAC,OAAO,CAAC,CAAC;IACxC,CAAC,+BAA+B,EAAE,CAAC,OAAO,CAAC,CAAC;IAC5C,CAAC,wBAAwB,EAAE,CAAC,OAAO,CAAC,CAAC;CACtC,CAAC,CAAC"}
+{"version":3,"file":"versions.js","sourceRoot":"","sources":["../../src/checks/versions.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,EAAE,gCAAgC,EAAE,MAAM,cAAc,CAAC;AAChE,OAAO,EAAE,8BAA8B,EAAE,MAAM,YAAY,CAAC;AAC5D,OAAO,EAAE,iCAAiC,EAAE,MAAM,eAAe,CAAC;AAClE,OAAO,EAAE,+BAA+B,EAAE,MAAM,qBAAqB,CAAC;AACtE,OAAO,EAAE,8BAA8B,EAAE,MAAM,aAAa,CAAC;AAC7D,OAAO,EAAE,4BAA4B,EAAE,MAAM,iBAAiB,CAAC;AAC/D,OAAO,EAAE,iCAAiC,EAAE,MAAM,gBAAgB,CAAC;AACnE,OAAO,EAAE,2BAA2B,EAAE,MAAM,gBAAgB,CAAC;AAE7D,OAAO,EAAE,2BAA2B,EAAE,MAAM,qBAAqB,CAAC;AAElE;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,sBAAsB,CAAC,MAAkB;IACvD,MAAM,QAAQ,GAAG;QACf,gCAAgC;QAChC,8BAA8B;QAC9B,iCAAiC;QACjC,8BAA8B;QAC9B,+BAA+B;QAC/B,iCAAiC;QACjC,4BAA4B;KAC7B,CAAC;IACF,IAAI,MAAM,CAAC,MAAM,KAAK,KAAK;QAAE,QAAQ,CAAC,IAAI,CAAC,2BAA2B,CAAC,CAAC;IACxE,IAAI,mBAAmB,EAAE;QAAE,QAAQ,CAAC,IAAI,CAAC,2BAA2B,CAAC,CAAC;IACtE,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAA2C,IAAI,GAAG,CAAC;IACtF,CAAC,wBAAwB,EAAE,CAAC,QAAQ,CAAC,CAAC;IACtC,CAAC,2BAA2B,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IACjD,CAAC,yBAAyB,EAAE,CAAC,OAAO,CAAC,CAAC;IACtC,CAAC,2BAA2B,EAAE,CAAC,OAAO,CAAC,CAAC;IACxC,CAAC,+BAA+B,EAAE,CAAC,OAAO,CAAC,CAAC;IAC5C,CAAC,wBAAwB,EAAE,CAAC,OAAO,CAAC,CAAC;IACrC,CAAC,0BAA0B,EAAE,CAAC,QAAQ,CAAC,CAAC;IACxC,CAAC,mCAAmC,EAAE,CAAC,QAAQ,CAAC,CAAC;IACjD,CAAC,yBAAyB,EAAE,CAAC,OAAO,CAAC,CAAC;IACtC,CAAC,4BAA4B,EAAE,CAAC,QAAQ,CAAC,CAAC;IAC1C,CAAC,yBAAyB,EAAE,CAAC,OAAO,CAAC,CAAC;IACtC,CAAC,kBAAkB,EAAE,CAAC,QAAQ,CAAC,CAAC;IAChC,CAAC,oBAAoB,EAAE,CAAC,OAAO,CAAC,CAAC;IACjC,CAAC,oBAAoB,EAAE,CAAC,OAAO,CAAC,CAAC;IACjC,CAAC,yBAAyB,EAAE,CAAC,OAAO,CAAC,CAAC;IACtC,CAAC,+BAA+B,EAAE,CAAC,OAAO,CAAC,CAAC;IAC5C,CAAC,mCAAmC,EAAE,CAAC,OAAO,CAAC,CAAC;IAChD,CAAC,+BAA+B,EAAE,CAAC,OAAO,CAAC,CAAC;IAC5C,CAAC,4BAA4B,EAAE,CAAC,QAAQ,CAAC,CAAC;IAC1C,CAAC,yBAAyB,EAAE,CAAC,OAAO,CAAC,CAAC;IACtC,CAAC,oBAAoB,EAAE,CAAC,OAAO,CAAC,CAAC;IACjC,CAAC,oBAAoB,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IACnD,CAAC,uBAAuB,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAC7C,CAAC,wBAAwB,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;CACjE,CAAC,CAAC"}

package/dist/contract.d.ts

@@ -165,6 +165,24 @@ export interface ScanResultRecord {
     };
     /** How the page was judged ready. Absent on explicit scans — no heuristic ran. */
     settle?: AxeScan['settle'];
+    /**
+     * This record carries ONLY Setsquare's driven checks — no axe run happened.
+     *
+     * Emitted at teardown for a page that was already scanned mid-test and has
+     * not changed since. That skip is right for axe (nothing to find twice) and
+     * wrong for the driven checks, which never run mid-test at all: focusing,
+     * pressing Tab and resizing are unsafe while a test is still asserting, so
+     * they only ever happen at teardown. Without this record a page that settled
+     * during its test got no focus, keyboard, reflow or context evidence — which
+     * was quietly true of text-spacing and status messages for months, and
+     * meant the criteria those checks exist for stayed at "no automated result"
+     * on exactly the fast, static pages most suites are made of.
+     *
+     * `toScans` MERGES these into the scan sharing their `visitRef` rather than
+     * emitting a second row: two rows for one context would collide in dedupe
+     * and one kind of evidence would silently win.
+     */
+    checksOnly?: true;
 }
 export type ScanRecord = ObservationRecord | ScanResultRecord;
 /**

package/dist/contract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"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"}

package/dist/covers.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Level 3: a test says which success criteria it covers.
+ *
+ * Auto-scan gets a grid from a suite nobody edited, and `setsquare.scan()`
+ * reaches the states auto-scan cannot. This reaches the CRITERIA neither can:
+ * the ones no automated engine evaluates at all.
+ *
+ * A suite that checks reflow at 320px, drives focus across a soft navigation
+ * or asserts that a focus ring is visible is already covering criteria axe
+ * has no rule for — and until this existed, the conformance report said "no
+ * automated result" for every one of them. Not because anyone decided that:
+ * a Playwright spec lands in the envelope as a pass/fail row with no
+ * criterion attached, so the projection could not see it. This is the join.
+ *
+ * ```ts
+ * test('no horizontal overflow at 320px', async ({ page }) => {
+ *   setsquare.covers('1.4.10');
+ *   await page.setViewportSize({ width: 320, height: 800 });
+ *   …
+ * });
+ * ```
+ *
+ * **What this is not.** We do not check that a test declaring `1.4.10` tests
+ * reflow, and we never will — there is no way to. So the report renders it as
+ * your assertion and not as our finding: its own cell state, worded "covered
+ * by your own test", never merged into the state that means every automated
+ * rule passed. The declaration is exactly as strong as the test behind it,
+ * and the report says whose claim it is.
+ */
+export declare function covers(...criteria: string[]): void;
+/**
+ * The annotation type the declaration travels under.
+ *
+ * Defined beside both the writer above and the reader below so the string
+ * cannot drift between them — the same reasoning that keeps the sanitisation
+ * limits in one file shared by the schema and the SDK.
+ */
+export declare const COVERS_ANNOTATION = "setsquare-covers";
+/**
+ * Read the declarations back off one attempt's annotations.
+ *
+ * Tolerates a missing `annotations` array rather than assuming it: the SDK's
+ * declared peer range reaches back to Playwright 1.45, and `TestResult.annotations`
+ * only arrived in 1.49. On an older runner the declarations are simply not
+ * there, which is the right degradation — the report loses a state it never had.
+ *
+ * Unknown ids are dropped here rather than thrown, because by this point the
+ * throw has already happened in the worker. Anything invalid reaching the
+ * reporter came from a hand-written annotation, and a reporter is the wrong
+ * place to fail a run that has finished.
+ */
+export declare function coversFromAnnotations(annotations: readonly {
+    type: string;
+    description?: string;
+}[] | undefined): string[];
+//# sourceMappingURL=covers.d.ts.map

package/dist/covers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"covers.d.ts","sourceRoot":"","sources":["../src/covers.ts"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,MAAM,CAAC,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,IAAI,CA4DlD;AAED;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,qBAAqB,CAAC;AAEpD;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,EAAE,GAAG,SAAS,GACzE,MAAM,EAAE,CAUV"}

package/dist/covers.js

@@ -0,0 +1,135 @@
+import { test } from '@playwright/test';
+import { MAX_CRITERIA_PER_TEST } from '@setsquare/schema/limits';
+import { WCAG22_CRITERION_IDS, wcagCriterion } from '@setsquare/schema/wcag22';
+import { WCAG22_SPEC_URL } from './links.js';
+import { isDisabled } from './options.js';
+/**
+ * Level 3: a test says which success criteria it covers.
+ *
+ * Auto-scan gets a grid from a suite nobody edited, and `setsquare.scan()`
+ * reaches the states auto-scan cannot. This reaches the CRITERIA neither can:
+ * the ones no automated engine evaluates at all.
+ *
+ * A suite that checks reflow at 320px, drives focus across a soft navigation
+ * or asserts that a focus ring is visible is already covering criteria axe
+ * has no rule for — and until this existed, the conformance report said "no
+ * automated result" for every one of them. Not because anyone decided that:
+ * a Playwright spec lands in the envelope as a pass/fail row with no
+ * criterion attached, so the projection could not see it. This is the join.
+ *
+ * ```ts
+ * test('no horizontal overflow at 320px', async ({ page }) => {
+ *   setsquare.covers('1.4.10');
+ *   await page.setViewportSize({ width: 320, height: 800 });
+ *   …
+ * });
+ * ```
+ *
+ * **What this is not.** We do not check that a test declaring `1.4.10` tests
+ * reflow, and we never will — there is no way to. So the report renders it as
+ * your assertion and not as our finding: its own cell state, worded "covered
+ * by your own test", never merged into the state that means every automated
+ * rule passed. The declaration is exactly as strong as the test behind it,
+ * and the report says whose claim it is.
+ */
+export function covers(...criteria) {
+    if (criteria.length === 0) {
+        throw new TypeError('setsquare.covers() needs at least one WCAG success criterion id.');
+    }
+    const seen = new Set();
+    for (const criterion of criteria) {
+        /*
+         * An unknown id throws, and that is the one place this SDK deliberately
+         * does throw into a customer's test.
+         *
+         * Everywhere else the discipline is absolute: a scan that fails warns and
+         * returns "not scanned", because our evidence-gathering has no standing to
+         * overturn the suite's own verdict. This is a different thing. A typo here
+         * is not our code failing on their page — it is a claim that cannot be
+         * satisfied, and the only alternative to throwing is dropping it silently,
+         * which leaves someone believing they have coverage they do not have. That
+         * is the failure mode this whole feature exists to close, so it cannot be
+         * the failure mode of the feature itself.
+         *
+         * It can never fire on a correct declaration, so it can never turn a build
+         * red for an accessibility reason. WCAG 2.2 is a frozen Recommendation;
+         * the valid set will not change under anyone.
+         */
+        const known = wcagCriterion(criterion);
+        if (!known || known.removedIn) {
+            throw new TypeError(`setsquare.covers("${criterion}") is not a WCAG 2.2 success criterion. ` +
+                `Ids look like "1.4.10" or "2.4.11"` +
+                (known?.removedIn
+                    ? `; ${criterion} was removed in WCAG ${known.removedIn}.`
+                    : `. See ${WCAG22_SPEC_URL}`));
+        }
+        seen.add(criterion);
+    }
+    if (seen.size > MAX_CRITERIA_PER_TEST) {
+        throw new TypeError(`setsquare.covers() accepts at most ${MAX_CRITERIA_PER_TEST} criteria per test; ` +
+            `this test declared ${seen.size}. A test asserting twenty of the eighty-six ` +
+            `is claiming more than one test can plausibly check.`);
+    }
+    // Off means off, here as everywhere: the switch exists so somebody can answer
+    // "is it you or is it me" in one command. Validation still runs, because a
+    // typo is a typo whether or not evidence is being gathered.
+    if (isDisabled())
+        return;
+    const info = test.info();
+    for (const criterion of seen) {
+        /*
+         * Carried on Playwright's own annotation channel rather than an attachment.
+         * Annotations are already on `TestResult` where the reporter reads outcomes,
+         * they survive into Playwright's own HTML report — so the declaration is
+         * visible even to someone not using Setsquare's — and they cost nothing.
+         */
+        info.annotations.push({ type: COVERS_ANNOTATION, description: criterion });
+    }
+}
+/**
+ * The annotation type the declaration travels under.
+ *
+ * Defined beside both the writer above and the reader below so the string
+ * cannot drift between them — the same reasoning that keeps the sanitisation
+ * limits in one file shared by the schema and the SDK.
+ */
+export const COVERS_ANNOTATION = 'setsquare-covers';
+/**
+ * Read the declarations back off one attempt's annotations.
+ *
+ * Tolerates a missing `annotations` array rather than assuming it: the SDK's
+ * declared peer range reaches back to Playwright 1.45, and `TestResult.annotations`
+ * only arrived in 1.49. On an older runner the declarations are simply not
+ * there, which is the right degradation — the report loses a state it never had.
+ *
+ * Unknown ids are dropped here rather than thrown, because by this point the
+ * throw has already happened in the worker. Anything invalid reaching the
+ * reporter came from a hand-written annotation, and a reporter is the wrong
+ * place to fail a run that has finished.
+ */
+export function coversFromAnnotations(annotations) {
+    if (!annotations)
+        return [];
+    const valid = new Set(WCAG22_CRITERION_IDS);
+    const found = new Set();
+    for (const annotation of annotations) {
+        if (annotation.type !== COVERS_ANNOTATION)
+            continue;
+        const id = annotation.description?.trim();
+        if (id && valid.has(id))
+            found.add(id);
+    }
+    return [...found].sort(compareCriteria).slice(0, MAX_CRITERIA_PER_TEST);
+}
+/** Dotted ids sort numerically: 1.4.10 after 1.4.9, not after 1.4.1. */
+function compareCriteria(a, b) {
+    const pa = a.split('.').map(Number);
+    const pb = b.split('.').map(Number);
+    for (let i = 0; i < Math.max(pa.length, pb.length); i += 1) {
+        const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+        if (d !== 0)
+            return d;
+    }
+    return 0;
+}
+//# sourceMappingURL=covers.js.map

package/dist/covers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"covers.js","sourceRoot":"","sources":["../src/covers.ts"],"names":[],"mappings":"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"}

package/dist/dedupe.d.ts

@@ -43,6 +43,29 @@ export interface DedupeInput {
  * `/items/:id/edit`), so it collapses exactly what should collapse. The surface
  * name then comes from whichever scan WINS, which is how an explicit label ends
  * up on the row instead of competing with an inferred one for a place in the list.
+ *
+ * ## The viewport joined the tuple on 2026-09-12, and it had to
+ *
+ * It was missing, and the consequence was not theoretical: adding a tablet and
+ * a mobile Playwright project to this repository's own marketing site produced
+ * three scans of every surface and this function collapsed them to one. Ties
+ * break LAST-wins, so the last project configured won every bucket and the
+ * entire grid became mobile evidence — with the desktop and tablet scans
+ * silently dropped and the report showing no sign that anything had been lost.
+ * A run that looked at three widths reported one, and the two it discarded were
+ * the two the reader would have assumed were there.
+ *
+ * The argument is the one already made above for the theme: collapsing two
+ * themes reports a themed surface as clean when only one of its themes was
+ * looked at, and a viewport is the same shape of claim. A rule only ever sees
+ * the viewport it ran in — a navigation that collapses into a menu below a
+ * breakpoint is a different DOM, not a narrower one — so a scan at 1280 has no
+ * opinion whatsoever about the same page at 390.
+ *
+ * A single-viewport run is unaffected: every scan carries the same value, so
+ * every key is unchanged. It costs the common case nothing and it is the
+ * difference between viewport evidence existing and viewport evidence being
+ * thrown away.
  */
 export declare function contextKey(scan: AxeScan): string;
 /**

package/dist/dedupe.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dedupe.d.ts","sourceRoot":"","sources":["../src/dedupe.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAEjD;;;;;;;;;;;;;GAaG;AAEH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,OAAO,CAAC;IACd,+CAA+C;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,gFAAgF;IAChF,cAAc,EAAE,OAAO,CAAC;IACxB,oEAAoE;IACpE,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAGhD;AA6BD;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG;IAAE,IAAI,EAAE,OAAO,EAAE,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAoBvF;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,EAAE,GACtE,GAAG,CAAC,MAAM,CAAC,CAQb"}
+{"version":3,"file":"dedupe.d.ts","sourceRoot":"","sources":["../src/dedupe.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAEjD;;;;;;;;;;;;;GAaG;AAEH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,OAAO,CAAC;IACd,+CAA+C;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,gFAAgF;IAChF,cAAc,EAAE,OAAO,CAAC;IACxB,oEAAoE;IACpE,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAShD;AA6BD;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG;IAAE,IAAI,EAAE,OAAO,EAAE,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CA0BvF;AA8DD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,EAAE,GACtE,GAAG,CAAC,MAAM,CAAC,CAQb"}