ultra11y 2.30.0 → 2.31.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
       "name": "ultra11y",
       "source": "./",
       "description": "Automatic accessibility review of the code under change before every commit, push and pull request, plus full WCAG 2.2 AA / RGAA audits and conformance deliverables on demand.",
-      "version": "2.30.0",
+      "version": "2.31.0",
       "author": { "name": "maxgfr" },
       "homepage": "https://github.com/maxgfr/ultra11y",
       "repository": "https://github.com/maxgfr/ultra11y",

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ultra11y",
   "description": "Accessibility for WCAG 2.2 AA and country standards (RGAA…): an automatic review of the code under change before every commit, push and pull request, plus full audits and conformance deliverables on demand.",
-  "version": "2.30.0",
+  "version": "2.31.0",
   "author": { "name": "maxgfr" },
   "homepage": "https://github.com/maxgfr/ultra11y",
   "repository": "https://github.com/maxgfr/ultra11y",

package/.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ultra11y",
   "description": "Accessibility for WCAG 2.2 AA and country standards (RGAA…): an automatic review of the code under change before every commit, push and pull request, plus full audits and conformance deliverables on demand.",
-  "version": "2.30.0",
+  "version": "2.31.0",
   "author": { "name": "maxgfr", "url": "https://github.com/maxgfr" },
   "homepage": "https://github.com/maxgfr/ultra11y",
   "repository": "https://github.com/maxgfr/ultra11y",

package/.opencode/plugins/ultra11y.js

@@ -27,7 +27,7 @@ import { fileURLToPath } from "node:url";
 // Ownership marker: `ultra11y install --opencode` refuses to overwrite a plugin file that
 // does not carry it, so a user's own ultra11y.js is never clobbered.
 const ULTRA11Y_OPENCODE_PLUGIN = "ULTRA11Y_OPENCODE_PLUGIN";
-const ULTRA11Y_PLUGIN_VERSION = "2.30.0";
+const ULTRA11Y_PLUGIN_VERSION = "2.31.0";
 
 const here = dirname(fileURLToPath(import.meta.url));
 

package/README.md

@@ -32,7 +32,7 @@ ultra11y is built around an honest **division of labour**. Automated tools only
 - **Needs rendering (scan tier):** computed contrast, visible focus, zoom/reflow, content on hover — decided by `scan` (axe-core in a real browser); until then they stay **residual risks**, never silently "conforming".
 - **Advisory vs non-conformity:** a good practice with no failing normative test (an `advisory` pack rule, a best-practice-only axe violation, an agent recommendation) renders as « Recommandation (non normative) » — it never flips a criterion to `NC` nor enters the conformance rate. An NC always cites a `normativeRef`.
 - **Stateful scan probes:** the local runtime drives the page with bounded, non-navigating interactions (fill inputs then re-measure overflow; a live-region probe for status messages 4.1.3) — `--no-interact` opts out; `--interact-clicks` re-enables button clicks on authenticated scans (destructive-named buttons are never clicked).
-- **Normative page sample (échantillon):** a country-standard audit runs over a declared `sample.pages` set — `sample check` lints its coverage against the standard's required page kinds, `scan --sample` scans it, and an un-scanned `--standard rgaa` report is flagged **partial**.
+- **Normative page sample (échantillon):** a country-standard audit runs over a declared `sample.pages` set — **`pages discover --crawl|--sitemap --write` builds it for you** (names read from each page's `<title>`, existing entries never overwritten), `sample check` lints its coverage against the standard's required page kinds, `scan --sample` scans it, and an un-scanned `--standard rgaa` report is flagged **partial**.
 - **Pack-only detection (declarative):** a standards pack can ship its own `rules` (a bounded, ReDoS-guarded matcher DSL — no code) and normativity/severity `overrides`, projecting onto its criteria without forking the engine.
 
 ## Measured against a corpus it did not write
@@ -58,6 +58,14 @@ npx ultra11y --help          # no install
 npm i -D ultra11y            # or as a dev dependency
 ```
 
+**As a test-runner plugin** — audit a page inside your own E2E run, in the state your test
+built it:
+
+```js
+import { checkA11y } from "ultra11y/playwright";   // or "ultra11y/cypress" (+ "/plugin")
+await checkA11y(page, { as: "accueil" });
+```
+
 **As an agent skill** — the repository ships **two** (pick at the prompt, or pass the name):
 `ultra11y` for full audits, compliance reports, PRD backlogs and standards packs, and
 `review-a11y` for the fast loop that audits **exactly the code under change** (staged files,
@@ -140,8 +148,11 @@ ultra11y render   [<dir>] [--scaffold | --setup | --e2e | --coverage | --storybo
 ultra11y snapshot write [--root <dir>] [--fail-on blocking|major|minor] [--json]   # payload on stdin → .ultra11y/pages/<id>/ + audit
 ultra11y snapshot list  [--root <dir>] [--json]
 ultra11y pages    --in <audit.json> [--standard <pack>] [--json] [--lang auto|en|fr]   # the per-page criterion grid
+ultra11y pages    --in <audit.json> --format report [--split page] [--out <dir>]        # the per-page report, with screenshots
+ultra11y pages    discover --sitemap <url> | --crawl <url> [--depth <n>] [--max <n>] [--write]   # build the page sample
 ultra11y dev      [--port <n>] [--standard <pack>]   |   dev --next                        # live overlay while you build + dashboard
 ultra11y criteria [<sc>] [--list] [--standard <pack> [--theme <N>]] [--generate] [--json] [--lang auto|en|fr]
+ultra11y judge    --in <audit.json> [--standard <pack>] [--max <n>] [--model <id>] [--apply]   # adjudicate with a model (ANTHROPIC_API_KEY)
 ultra11y check    --report <md> [--standard <pack>] [--quiet] [--json]
 ultra11y verify   --report <md> [--standard <pack>] [--semantic] [--apply <verdicts.json>] [--max-verify <n>] [--json]
 ultra11y fix      <globs… | ->  [--write] [--iterate] [--changed | --since <ref> | --staged] [--safe] [--only <ids>] [--jsx] [--json]
@@ -260,8 +271,13 @@ a test). See [`CONTRIBUTING.md`](CONTRIBUTING.md) and `skills/ultra11y/reference
   auto-codemods, fill-in `TODO` placeholders for the agent to complete, and judgment-only
   proposals. `--dry-run` is the default; `--write` applies but only after a re-audit proves
   no new non-conformity, and never on lossy JSX/TSX. See `references/fix.md`.
-- **During your E2E run** — `render --e2e` writes Playwright/Cypress fixtures that audit a
-  targeted page **inside the test run you already have**, so the page is checked in the state
+- **During your E2E run** — `import { checkA11y } from "ultra11y/playwright"` (or
+  `ultra11y/cypress` + `ultra11y/cypress/plugin`) audits a targeted page **inside the test run
+  you already have**; `render --e2e` still writes install-free fixtures for a repo that does
+  not depend on ultra11y, and the two cannot drift (the fixtures interpolate the published
+  module's tables, and a test gates both over the same findings). Cypress now feeds the pixel
+  tier too, via `after:screenshot`. `checkA11y(page, { report: true })` emits the per-page
+  report straight out of the run. The audit runs, so the page is checked in the state
   your test built (logged in, form filled, modal open) — state a separate `scan` run does not
   have. Each checked page is persisted as a **snapshot** (`.ultra11y/pages/<id>/`: the whole
   rendered document + computed styles + boxes), which is the durable half: the same page
@@ -269,6 +285,11 @@ a test). See [`CONTRIBUTING.md`](CONTRIBUTING.md) and `skills/ultra11y/reference
   a snapshot is a full document, the page-scoped rules finally run — RGAA **8.3** (`lang`),
   **8.5/8.6** (`title`) — and every finding carries both its page and the source file that
   rendered it. See `references/e2e.md` and `references/pages.md`.
+- **In your browser** — a Chrome extension (`extension/`) audits the page you are *looking at*:
+  a staging build, a page behind a login you walked through by hand. It is a client of the
+  side-car, not a second engine — it fetches the engine's own collector rather than copying it,
+  its manifest can reach **loopback and nothing else**, and the popup decides nothing the engine
+  did not. See `references/extension.md`.
 - **While you build** — `dev --next` writes a one-line Next overlay component and `dev` starts
   a loopback side-car: a floating panel lists the current page's non-conformities as you
   browse, each linking to its `file:line` in your editor, and `http://127.0.0.1:4111` shows
@@ -298,6 +319,15 @@ a test). See [`CONTRIBUTING.md`](CONTRIBUTING.md) and `skills/ultra11y/reference
   rather than guessed, and without signals the rules do not fire, so no pre-existing verdict
   changes. `tests/rgaa-coverage.test.ts` ratchets the result: **48 of 106** RGAA criteria now
   map onto an engine rule, up from 43, and the number can only go up.
+- **Every scanned page is a snapshot** — `scan` no longer keeps only findings: each page it
+  visits is persisted to `.ultra11y/pages/<id>/` (`--no-snapshot` opts out). That is what turns
+  a URL into a real per-page verdict — a page known only by its URL can never be conforming by
+  silence, so a sitemap-driven audit used to produce an almost empty grid. With a snapshot the
+  page-scoped rules run (**RGAA 8.3 / 8.5 / 8.6**), the DOM **JavaScript built at runtime** is
+  audited like any other markup, and the page re-audits **offline, with no browser**. The
+  collection happens on the *pristine* page — before axe injects its source and before any probe
+  fills an input or resizes the viewport — otherwise the snapshot would record our own
+  instrumentation instead of the site.
 - **Page by page** — RGAA is a per-page norm; the engine's verdict is scope-wide. `pages`
   bridges the two: one row per criterion, one column per page, embedded in `report` and
   rebuilt from a committed `audit.json` alone. The per-page status is not recomputed — a
@@ -305,7 +335,12 @@ a test). See [`CONTRIBUTING.md`](CONTRIBUTING.md) and `skills/ultra11y/reference
   and report agree by construction. Two rules hold the line: a finding is attributed to a page
   only when something **says** so (else it is counted as unattributed, never spread across
   pages), and a criterion is conforming *by silence* only on a page whose real rendered DOM
-  was audited. See `references/pages.md`.
+  was audited. And `pages --format report [--split page]` turns that into the **deliverable an
+  auditor hands over**: one dossier per page — identity, **screenshot**, rate, *every* criterion
+  of the standard with its status on that page, then each non-conformity as the ordinary auditor
+  block. It re-decides nothing and invents no format, so a page sheet and the compliance report
+  cannot disagree; `check` gates it against invented criteria like any other report.
+  See `references/pages.md`.
 - **A shipped GitHub Action** — `uses: maxgfr/ultra11y@main` audits the **code** (PR diff) and,
   optionally, the **pages** (it can start your app, wait for it, then scan real URLs or your
   declared sample). The engine ships inside the action, so there is nothing to install and no
@@ -325,6 +360,18 @@ a test). See [`CONTRIBUTING.md`](CONTRIBUTING.md) and `skills/ultra11y/reference
   regression variant (hook + committed baseline / GitHub Actions job) that fails only on **new**
   non-conformities, not the existing backlog. See `references/automation.md`.
 
+### Optional model tier (`judge`) — for the runs with no agent in the loop
+
+Inside a coding agent the judgment criteria are the agent's to rule on. Outside one — CI, a
+browser extension, an E2E run — nobody does, so they stay « à évaluer ». `judge` adjudicates
+them with a model, and is a **caller, not a second judge**: the worklist, the evidence and the
+prompt are `verify --manual`'s own, and the verdicts pass through the **same fail-closed gate**
+an agent's do. An unjustified `C`, an `NC` citing a line that does not resolve, a verdict for a
+criterion nobody asked about, or an incomplete run are all refused — and a rejected
+adjudication leaves the audit untouched. All-`manual` with reasons is accepted, because that is
+a correct answer. It is the **only** part of the tool that takes an API key; without one the
+command explains itself and exits, and nothing else changes.
+
 ### Optional dynamic tier (axe-core)
 
 `scan` runs **axe-core in a headless browser** to decide the *needs-rendering* criteria the static engine leaves as residual risks — chiefly **computed colour contrast (1.4.3)** plus a 320px **reflow** check (1.4.10) and a render cross-check of the structural rules. Two runtimes (default `--runtime auto`): **`--runtime local`** uses a Playwright that resolves from your project (`--cwd`) — **no Docker** — and additionally probes focus visibility (2.4.7), 200% zoom (1.4.4), text spacing (1.4.12) and content-on-hover (1.4.13), plus **stateful** probes (fill inputs then re-measure overflow, and a live-region probe for status messages 4.1.3 — opt out with `--no-interact`, `--interact-clicks` for authed-scan button clicks), and takes `--storage-state` for authenticated pages; **`--runtime docker`** falls back to a self-contained image built on first use. `--merge` folds the findings into a static `AuditResult`, upgrading `manual` criteria to `C`/`NC`. A country-standard audit scans its declared page sample with `scan --sample` (lint it first with `sample check`):
@@ -353,14 +400,19 @@ The skill (`skills/ultra11y/SKILL.md` + `references/`) teaches the agent when an
 pnpm install
 pnpm test               # vitest
 pnpm run typecheck
-pnpm run build          # tsup → scripts/ultra11y.mjs, mirrored into skills/ultra11y/scripts/
-pnpm run check:build    # asserts the committed bundle is reproducible
+pnpm run build          # tsup → scripts/ultra11y.mjs (engine) + dist/ (the e2e plugins)
+pnpm run check:build    # asserts every committed artefact is reproducible from its source
 pnpm run build:wcag     # re-derive src/data/wcag.json from the vendored W3C source
 pnpm run build:pack:rgaa # re-build the RGAA pack from the vendored DINUM source
 pnpm run build:criteria  # regenerate skills/ultra11y/references/criteria.md
+pnpm run build:icons     # re-generate the browser extension's icons from their source
 ```
 
-Releases are cut automatically by semantic-release on push to `main` (GitHub release + tarball, no npm publish).
+Releases are cut automatically by **semantic-release** on push to `main` (GitHub release +
+npm publish via OIDC trusted publishing, plus the moving `v2` major tag). The version bump is
+decided by **Conventional Commits**: a commit whose subject carries no `feat:`/`fix:` prefix
+is analysed as *no release*, so a change that must ship needs at least one conventional commit
+in the range — otherwise `@v2` and npm keep serving the previous version while `main` moves on.
 
 ## Data & licensing
 

package/dist/cypress-plugin.d.ts

@@ -0,0 +1,17 @@
+import { S as SnapshotPayload, F as FindingLike } from './payload-D0VQYlGS.js';
+
+type On = (event: string, handler: any) => void;
+interface TaskPayload extends SnapshotPayload {
+    failOn?: string | false;
+    /** The name `cy.screenshot()` was called with, when the browser half took one. */
+    screenshotName?: string;
+}
+interface TaskResult {
+    findings: FindingLike[];
+    failing: FindingLike[];
+    message: string;
+}
+/** Register the ultra11y task (and the screenshot capture) on Cypress's node events. */
+declare function register(on: On): void;
+
+export { type TaskPayload, type TaskResult, register as default };

package/dist/cypress-plugin.mjs

@@ -0,0 +1,82 @@
+// src/integrations/cypress-plugin.ts
+import { readFileSync } from "fs";
+
+// src/integrations/core.ts
+import { spawnSync } from "child_process";
+import { createRequire } from "module";
+
+// src/integrations/payload.ts
+var RANK = { bloquant: 0, majeur: 1, mineur: 2 };
+var THRESHOLD = { blocking: 0, bloquant: 0, major: 1, majeur: 1, minor: 2, mineur: 2 };
+function failingFindings(result, failOn) {
+  const max = THRESHOLD[failOn];
+  if (max === void 0) throw new Error(`ultra11y: failOn must be blocking|major|minor (got "${failOn}")`);
+  return (result.findings ?? []).filter((f) => !f.advisory && (RANK[f.severity] ?? 99) <= max);
+}
+function formatFailure(pageName, failing) {
+  const lines = [`ultra11y: ${failing.length} accessibility non-conformity(ies) on "${pageName}":`];
+  for (const f of failing.slice(0, 20)) {
+    lines.push(`  [${f.severity}] ${f.ruleId} (WCAG ${f.criteriaId}) \u2014 ${f.origin?.sourceFile ?? f.file} \u2014 ${f.message}`);
+  }
+  if (failing.length > 20) lines.push(`  \u2026 and ${failing.length - 20} more.`);
+  lines.push("Full detail: .ultra11y/pages/ \u2014 re-audit offline with `ultra11y audit`.");
+  return lines.join("\n");
+}
+
+// src/integrations/core.ts
+function enginePath() {
+  if (process.env.ULTRA11Y) return process.env.ULTRA11Y;
+  try {
+    return createRequire(import.meta.url).resolve("ultra11y/scripts/ultra11y.mjs");
+  } catch {
+    return new URL("../scripts/ultra11y.mjs", import.meta.url).pathname;
+  }
+}
+function auditSnapshot(payload, engine = enginePath()) {
+  const res = spawnSync(process.execPath, [engine, "snapshot", "write", "--json"], {
+    input: JSON.stringify(payload),
+    encoding: "utf8",
+    maxBuffer: 192 * 1024 * 1024
+  });
+  if (res.error) throw new Error(`ultra11y: could not run the engine at ${engine} \u2014 ${res.error.message}`);
+  if (!res.stdout) throw new Error(`ultra11y: the engine produced no output (exit ${res.status})
+${res.stderr || ""}`);
+  try {
+    return JSON.parse(res.stdout);
+  } catch {
+    throw new Error(`ultra11y: could not parse the engine output
+${res.stdout.slice(0, 500)}`);
+  }
+}
+
+// src/integrations/cypress-plugin.ts
+function register(on) {
+  const shots = /* @__PURE__ */ new Map();
+  on("after:screenshot", (details) => {
+    if (details?.name && details.path) shots.set(details.name, details.path);
+    return details;
+  });
+  on("task", {
+    ultra11ySnapshot(payload) {
+      const withShot = { ...payload };
+      const path = payload.screenshotName ? shots.get(payload.screenshotName) : void 0;
+      if (path) {
+        try {
+          withShot.screenshot = readFileSync(path).toString("base64");
+        } catch {
+        }
+      }
+      const result = auditSnapshot(withShot);
+      const failOn = payload.failOn === void 0 ? "blocking" : payload.failOn;
+      const failing = failOn === false ? [] : failingFindings(result, failOn);
+      return {
+        findings: result.findings ?? [],
+        failing,
+        message: failing.length ? formatFailure(String(payload.meta.name), failing) : ""
+      };
+    }
+  });
+}
+export {
+  register as default
+};

package/dist/cypress.d.ts

@@ -0,0 +1,11 @@
+import { C as CheckOptions } from './payload-D0VQYlGS.js';
+export { s as slugify } from './payload-D0VQYlGS.js';
+
+interface CypressCheckOptions extends CheckOptions {
+    /** Capture a viewport screenshot so the pixel tier can run. On by default — the plugin
+     *  reads it back through Cypress's `after:screenshot` event. */
+    screenshot?: boolean;
+}
+declare function registerUltra11yCommand(): void;
+
+export { type CypressCheckOptions, registerUltra11yCommand };

package/dist/cypress.mjs

@@ -0,0 +1,170 @@
+// src/collector.ts
+var COLLECTED_CSS = [
+  "color",
+  "backgroundColor",
+  "backgroundImage",
+  "fontSize",
+  "fontWeight",
+  "fontStyle",
+  "textDecorationLine",
+  "textTransform",
+  "lineHeight",
+  "letterSpacing",
+  "wordSpacing",
+  "whiteSpace",
+  "display",
+  "visibility",
+  "opacity",
+  "position",
+  "overflowX",
+  "overflowY",
+  "outlineStyle",
+  "outlineWidth",
+  "outlineColor",
+  // All four borders + the box shadow: WCAG 1.4.11 asks whether a control's BOUNDARY is
+  // perceivable, and a boundary can be drawn by any side, by the fill, by an outline or by a
+  // shadow. Collecting only one side would manufacture non-conformities on the other three.
+  "borderTopStyle",
+  "borderRightStyle",
+  "borderBottomStyle",
+  "borderLeftStyle",
+  "borderTopWidth",
+  "borderRightWidth",
+  "borderBottomWidth",
+  "borderLeftWidth",
+  "borderTopColor",
+  "borderRightColor",
+  "borderBottomColor",
+  "borderLeftColor",
+  "boxShadow",
+  "cursor"
+];
+var COLLECT_MAX_ELEMENTS = 5e3;
+var COLLECT_SNAPSHOT = `(() => {
+  const PROPS = ${JSON.stringify(COLLECTED_CSS)};
+  const MAX = ${COLLECT_MAX_ELEMENTS};
+  const els = document.querySelectorAll('*');
+  const styles = [];
+  const boxes = [];
+  const n = Math.min(els.length, MAX);
+  for (let i = 0; i < n; i++) {
+    const el = els[i];
+    const tag = el.tagName.toLowerCase();
+    const cs = getComputedStyle(el);
+    const css = {};
+    for (const p of PROPS) {
+      const v = cs[p];
+      if (v !== undefined && v !== null && v !== '') css[p] = String(v);
+    }
+    styles.push({ i: i, tag: tag, css: css });
+    const r = el.getBoundingClientRect();
+    boxes.push({ i: i, tag: tag, x: Math.round(r.left), y: Math.round(r.top), w: Math.round(r.width), h: Math.round(r.height) });
+  }
+  // The page's own stylesheets. Some criteria are properties of the STYLESHEET rather than of
+  // any element's computed style \u2014 focus styling removed with no replacement (2.4.7), a media
+  // query that locks the orientation (1.3.4) \u2014 and this is the only place they exist.
+  // A cross-origin sheet throws on .cssRules: COUNT those instead of ignoring them, so a rule
+  // reading this digest can tell "nothing there" apart from "I could not look".
+  const cssRules = [];
+  let unreadable = 0;
+  const MAXR = 4000;
+  const camel = (p) => p.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+  const walk = (list, media) => {
+    for (const r of list) {
+      if (cssRules.length >= MAXR) return;
+      if (typeof r.selectorText === 'string' && r.style) {
+        const decls = {};
+        for (let i = 0; i < r.style.length; i++) {
+          const prop = r.style[i];
+          decls[camel(prop)] = r.style.getPropertyValue(prop);
+        }
+        cssRules.push(media ? { selector: r.selectorText, media: media, decls: decls } : { selector: r.selectorText, decls: decls });
+      } else if (r.cssRules) {
+        const cond = r.conditionText || (r.media && r.media.mediaText) || media;
+        walk(r.cssRules, cond);
+      }
+    }
+  };
+  for (const sheet of document.styleSheets) {
+    try {
+      walk(sheet.cssRules, undefined);
+    } catch (e) {
+      unreadable++;
+    }
+  }
+
+  const truncated = els.length > MAX;
+  return {
+    dom: document.documentElement.outerHTML,
+    css: { v: 1, rules: cssRules, unreadable: unreadable, truncated: cssRules.length >= MAXR },
+    title: document.title,
+    lang: document.documentElement.getAttribute('lang') || '',
+    url: location.href,
+    viewport: { width: window.innerWidth, height: window.innerHeight },
+    styles: { v: 1, entries: styles, truncated: truncated },
+    boxes: { v: 1, entries: boxes, truncated: truncated }
+  };
+})()`;
+
+// src/integrations/payload.ts
+function slugify(url) {
+  let path = url;
+  try {
+    path = new URL(url).pathname;
+    try {
+      path = decodeURIComponent(path);
+    } catch {
+    }
+  } catch {
+  }
+  const slug = path.normalize("NFD").replace(new RegExp("\\p{Diacritic}", "gu"), "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  return slug || (path === "/" || path === "" ? "accueil" : "page");
+}
+function buildPayload(collected, url, runner, opts, screenshot) {
+  const id = opts.as || slugify(url);
+  return {
+    meta: {
+      v: 1,
+      id,
+      name: opts.name || collected.title || id,
+      url,
+      runner,
+      viewport: collected.viewport,
+      capturedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      ...opts.auth !== void 0 ? { auth: opts.auth } : {},
+      ...opts.sources ? { sources: opts.sources } : {},
+      ...opts.notes ? { notes: opts.notes } : {}
+    },
+    dom: collected.dom,
+    styles: collected.styles,
+    boxes: collected.boxes,
+    css: collected.css,
+    ...screenshot ? { screenshot } : {}
+  };
+}
+
+// src/integrations/cypress.ts
+function registerUltra11yCommand() {
+  Cypress.Commands.add("ultra11y", (opts = {}) => {
+    const shotName = opts.screenshot === false ? void 0 : `ultra11y-${opts.as || "page"}-${Date.now()}`;
+    if (shotName) cy.screenshot(shotName, { capture: "viewport", log: false });
+    return cy.window({ log: false }).then((win) => {
+      const collected = win.eval(COLLECT_SNAPSHOT);
+      const url = collected.url || win.location.href;
+      const payload = {
+        ...buildPayload(collected, url, "cypress", opts),
+        failOn: opts.failOn,
+        ...shotName ? { screenshotName: shotName } : {}
+      };
+      return cy.task("ultra11ySnapshot", payload, { log: false }).then((res) => {
+        if (res?.failing?.length) throw new Error(res.message);
+        return res;
+      });
+    });
+  });
+}
+registerUltra11yCommand();
+export {
+  registerUltra11yCommand,
+  slugify
+};

package/dist/payload-D0VQYlGS.d.ts

@@ -0,0 +1,44 @@
+interface FindingLike {
+    ruleId: string;
+    criteriaId: string;
+    file: string;
+    line: number;
+    severity: string;
+    message: string;
+    advisory?: boolean;
+    origin?: {
+        sourceFile?: string;
+        sourceLine?: number;
+    };
+}
+interface AuditLike {
+    findings?: FindingLike[];
+}
+interface SnapshotPayload {
+    meta: Record<string, unknown>;
+    dom: string;
+    styles?: unknown;
+    boxes?: unknown;
+    css?: unknown;
+    screenshot?: string;
+}
+/** Same slug rule as the engine (src/snapshot.ts slugifyPageId): accent-folded URL path. */
+declare function slugify(url: string): string;
+interface CheckOptions {
+    /** The page id (directory name). Defaults to the slugified URL path. */
+    as?: string;
+    /** Human page name for the report. Defaults to the document title. */
+    name?: string;
+    /** Severity at which the check fails, or `false` to record without ever failing. */
+    failOn?: "blocking" | "major" | "minor" | false;
+    /** Mark the page as sitting behind authentication. */
+    auth?: boolean;
+    /** Source files that rendered it — findings are then reported against YOUR code. */
+    sources?: string[];
+    /** Reproduction notes carried into the auditor ticket. */
+    notes?: string;
+    /** Capture a viewport screenshot for the pixel tier (Playwright: on by default). */
+    screenshot?: boolean;
+}
+
+export { type AuditLike as A, type CheckOptions as C, type FindingLike as F, type SnapshotPayload as S, slugify as s };

package/dist/playwright.d.ts

@@ -0,0 +1,35 @@
+import { C as CheckOptions, A as AuditLike } from './payload-D0VQYlGS.js';
+
+interface PlaywrightPage {
+    evaluate(script: string): Promise<unknown>;
+    screenshot(opts: {
+        fullPage: boolean;
+    }): Promise<Buffer>;
+    url(): string;
+}
+interface PlaywrightCheckOptions extends CheckOptions {
+    /** Also write the per-page report once this page is recorded. Off by default: a report
+     *  per checked page would be wasteful in a suite; turn it on in a final test. */
+    report?: boolean | {
+        out?: string;
+        standard?: string;
+        lang?: string;
+    };
+}
+/** Collect the current page, persist it as a snapshot, audit it, and fail on the threshold. */
+declare function checkA11y(page: PlaywrightPage, opts?: PlaywrightCheckOptions): Promise<AuditLike>;
+/** Optional fixture form. Import `test` from here instead of `@playwright/test`.
+ *
+ *  Playwright belongs to YOUR project, not to this package, so it is resolved from the
+ *  PROJECT FIRST (cwd) and only then relative to this module — the same order
+ *  `scan --runtime local` uses (src/scan-local.ts resolveLocalDeps). Module-relative alone
+ *  works for an ordinary `node_modules/ultra11y` install, where Node walks up into the
+ *  project's own tree, but silently yields `undefined` whenever the package is linked,
+ *  pnpm-hoisted elsewhere, or in a monorepo — and a fixture that is `undefined` for
+ *  layout reasons is a confusing failure.
+ *
+ *  Resolution is lazy and guarded either way, so importing this in a Cypress-only repo
+ *  gives `undefined` rather than a crash. */
+declare const test: any;
+
+export { AuditLike, CheckOptions, type PlaywrightCheckOptions, checkA11y, test };