ultra11y 5.0.1 → 5.2.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": "5.0.1",
+      "version": "5.2.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": "5.0.1",
+  "version": "5.2.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": "5.0.1",
+  "version": "5.2.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 = "5.0.1";
+const ULTRA11Y_PLUGIN_VERSION = "5.2.0";
 
 const here = dirname(fileURLToPath(import.meta.url));
 

package/dist/cypress-plugin.d.ts

@@ -1,4 +1,4 @@
-import { S as SnapshotPayload, F as FindingLike } from './payload-D0VQYlGS.js';
+import { S as SnapshotPayload, F as FindingLike } from './payload-B6NDkLYJ.js';
 
 type On = (event: string, handler: any) => void;
 interface TaskPayload extends SnapshotPayload {

package/dist/cypress.d.ts

@@ -1,5 +1,5 @@
-import { C as CheckOptions } from './payload-D0VQYlGS.js';
-export { s as slugify } from './payload-D0VQYlGS.js';
+import { C as CheckOptions } from './payload-B6NDkLYJ.js';
+export { s as slugify } from './payload-B6NDkLYJ.js';
 
 interface CypressCheckOptions extends CheckOptions {
     /** Capture a viewport screenshot so the pixel tier can run. On by default — the plugin

package/dist/cypress.mjs

@@ -120,6 +120,20 @@ function slugify(url) {
   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 stayedOnPage(expected, actual) {
+  if (!expected || !actual) return true;
+  const path = (u) => {
+    try {
+      return new URL(u, "http://x.invalid").pathname.replace(/\/+$/, "");
+    } catch {
+      return void 0;
+    }
+  };
+  const a = path(expected);
+  const b = path(actual);
+  if (a === void 0 || b === void 0) return true;
+  return a === b;
+}
 function buildPayload(collected, url, runner, opts, screenshot) {
   const id = opts.as || slugify(url);
   return {
@@ -151,6 +165,11 @@ function registerUltra11yCommand() {
     return cy.window({ log: false }).then((win) => {
       const collected = win.eval(COLLECT_SNAPSHOT);
       const url = collected.url || win.location.href;
+      if (opts.expectPath && !stayedOnPage(opts.expectPath, url)) {
+        throw new Error(
+          `ultra11y: ${opts.expectPath} landed on ${url} \u2014 not recording it as "${opts.as ?? opts.name ?? "this page"}". The state that opens this route is not the one the test built; seed it first, or drop the page from the sample.`
+        );
+      }
       const payload = {
         ...buildPayload(collected, url, "cypress", opts),
         failOn: opts.failOn,

package/dist/payload-B6NDkLYJ.d.ts

@@ -0,0 +1,51 @@
+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;
+    /** The path you NAVIGATED to. Given it, the fixture refuses to record a page the browser
+     *  did not stay on — a guarded route that redirected, a session that expired — instead of
+     *  filing that other screen under this page's `as`/`name`. Nothing about such a snapshot
+     *  looks wrong, which is what makes it the worst thing an accessibility report can carry.
+     *  Compared by path (a query or fragment the app appends to its own route is the same
+     *  page); a full URL works too. `scan --sample` applies the same rule. */
+    expectPath?: string;
+}
+
+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

@@ -1,4 +1,4 @@
-import { C as CheckOptions, A as AuditLike } from './payload-D0VQYlGS.js';
+import { C as CheckOptions, A as AuditLike } from './payload-B6NDkLYJ.js';
 
 interface PlaywrightPage {
     evaluate(script: string): Promise<unknown>;
@@ -31,5 +31,57 @@ declare function checkA11y(page: PlaywrightPage, opts?: PlaywrightCheckOptions):
  *  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;
+/** Options for {@link sweepSample}. */
+interface SweepOptions {
+    /** Where `.ultra11yrc.json` lives. Defaults to the process cwd. */
+    cwd?: string;
+    /** Which declared pages this sweep owns. Return false for a page the repo snapshots itself
+     *  — a wizard step that needs application state seeded first, say. Skipped pages are simply
+     *  not declared here; they are still in the sample, so the report still expects them. */
+    only?: (page: SamplePageLike) => boolean;
+    /** Awaited after navigation, before collecting. This is where a framework's readiness goes:
+     *  a design system that boots asynchronously will otherwise be serialized half-mounted, and
+     *  the audit reports non-conformities about markup no user ever meets. */
+    settle?: (page: PlaywrightPage) => Promise<void>;
+    /** Passed to every `checkA11y`. `failOn: false` (the default here) records without
+     *  asserting: the durable output of a sweep is the snapshot, not a red test. */
+    check?: Omit<PlaywrightCheckOptions, "as" | "name" | "auth" | "notes" | "sources" | "expectPath">;
+}
+interface SamplePageLike {
+    id: string;
+    name: string;
+    url: string;
+    auth?: boolean;
+    notes?: string;
+    sources?: string[];
+}
+/** Declare one Playwright test per page of the `.ultra11yrc.json` sample.
+ *
+ *  The sample already says what every page is — id, name, URL, whether it sits behind a login,
+ *  the sources that render it. A repo that then hand-writes a route table to drive its sweep is
+ *  keeping a second copy of that, and the two drift: a page renamed in one place keeps its old
+ *  identity in the report, which is the failure this whole tier exists to prevent.
+ *
+ *  So the sample drives the sweep:
+ *
+ *  ```ts
+ *  import { test } from "@playwright/test";
+ *  import { sweepSample } from "ultra11y/playwright";
+ *
+ *  sweepSample({ settle: async (page) => { await page.waitForLoadState("networkidle"); } });
+ *  ```
+ *
+ *  Each page is navigated, checked against `expectPath` and its HTTP status, and recorded. A
+ *  page the browser did not stay on — or that answered an error at the requested address — is
+ *  `test.skip`ped with the reason, never filed under the requested name.
+ *
+ *  Pages your own specs drive (a funnel step that needs state seeded) are excluded with
+ *  `only`. */
+declare function samplePagesFor(opts?: Pick<SweepOptions, "cwd" | "only">): SamplePageLike[];
+/** The path a sample URL points at. The sample stores absolute URLs (it is also read by
+ *  `scan`, which needs a real address); a Playwright test wants the path, so its `baseURL`
+ *  applies. Anything unparseable is already a path. */
+declare function sweepTarget(url: string): string;
+declare function sweepSample(opts?: SweepOptions): void;
 
-export { AuditLike, CheckOptions, type PlaywrightCheckOptions, checkA11y, test };
+export { AuditLike, CheckOptions, type PlaywrightCheckOptions, type SamplePageLike, type SweepOptions, checkA11y, samplePagesFor, sweepSample, sweepTarget, test };

package/dist/playwright.mjs

@@ -1,5 +1,7 @@
 // src/integrations/playwright.ts
+import { readFileSync } from "fs";
 import { createRequire as createRequire2 } from "module";
+import { join } from "path";
 
 // src/collector.ts
 var COLLECTED_CSS = [
@@ -143,6 +145,20 @@ function slugify(url) {
   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 stayedOnPage(expected, actual) {
+  if (!expected || !actual) return true;
+  const path = (u) => {
+    try {
+      return new URL(u, "http://x.invalid").pathname.replace(/\/+$/, "");
+    } catch {
+      return void 0;
+    }
+  };
+  const a = path(expected);
+  const b = path(actual);
+  if (a === void 0 || b === void 0) return true;
+  return a === b;
+}
 function buildPayload(collected, url, runner, opts, screenshot) {
   const id = opts.as || slugify(url);
   return {
@@ -221,6 +237,11 @@ async function checkA11y(page, opts = {}) {
     }
   }
   const url = collected.url || page.url();
+  if (opts.expectPath && !stayedOnPage(opts.expectPath, url)) {
+    throw new Error(
+      `ultra11y: ${opts.expectPath} landed on ${url} \u2014 not recording it as "${opts.as ?? opts.name ?? "this page"}". The state that opens this route is not the one the test built; seed it first, or drop the page from the sample.`
+    );
+  }
   const payload = buildPayload(collected, url, "playwright", opts, shot);
   const result = auditSnapshot(payload);
   if (opts.report) writePagesReport(typeof opts.report === "object" ? opts.report : {});
@@ -244,7 +265,58 @@ var test = (() => {
   }
   return void 0;
 })();
+function samplePagesFor(opts = {}) {
+  const cwd = opts.cwd ?? process.cwd();
+  let declared;
+  try {
+    const raw = readFileSync(join(cwd, ".ultra11yrc.json"), "utf8");
+    declared = JSON.parse(raw).sample?.pages ?? [];
+  } catch {
+    throw new Error(`ultra11y: no readable .ultra11yrc.json in ${cwd} \u2014 sweepSample reads the page sample from it.`);
+  }
+  return declared.filter((p) => opts.only?.(p) ?? true);
+}
+function sweepTarget(url) {
+  try {
+    return new URL(url).pathname || url;
+  } catch {
+    return url;
+  }
+}
+function sweepSample(opts = {}) {
+  const pages = samplePagesFor(opts);
+  const t = test;
+  if (!t) throw new Error("ultra11y: @playwright/test could not be resolved \u2014 sweepSample needs it.");
+  if (!pages.length) return;
+  for (const p of pages) {
+    const target = sweepTarget(p.url);
+    t(`a11y \u2014 ${p.name}`, async ({ page }) => {
+      const response = await page.goto(target);
+      if (opts.settle) await opts.settle(page);
+      const landed = page.url();
+      t.skip(!stayedOnPage(target, landed), `${target} landed on ${landed} \u2014 the current state does not open this screen; nothing to record as "${p.name}"`);
+      const status = response?.status();
+      t.skip(
+        status !== void 0 && status >= 400,
+        `${target} answered HTTP ${status} \u2014 an error page at the requested address; nothing to record as "${p.name}"`
+      );
+      await checkA11y(page, {
+        failOn: false,
+        ...opts.check,
+        as: p.id,
+        name: p.name,
+        ...p.auth !== void 0 ? { auth: p.auth } : {},
+        ...p.notes ? { notes: p.notes } : {},
+        ...p.sources ? { sources: p.sources } : {},
+        expectPath: target
+      });
+    });
+  }
+}
 export {
   checkA11y,
+  samplePagesFor,
+  sweepSample,
+  sweepTarget,
   test
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ultra11y",
-  "version": "5.0.1",
+  "version": "5.2.0",
   "description": "Audit HTML/CSS/JSX against WCAG 2.2 AA and produce a dated compliance report, or author/review accessible markup (native-HTML-first). A skills.sh agent skill: an install-free static engine (bundled, no npm install) plus the agent's judgment, with check/verify gates against hallucinated non-conformities, and pluggable in-repo standards packs (RGAA France first; Section 508 & EN 301 549 next).",
   "type": "module",
   "packageManager": "pnpm@10.33.0",

package/scripts/ultra11y.mjs

@@ -6,7 +6,7 @@ import { join as join50, relative as relative5, resolve as resolve15, sep as sep
 import { fileURLToPath as fileURLToPath5, pathToFileURL as pathToFileURL3 } from "url";
 
 // src/types.ts
-var VERSION = "5.0.1";
+var VERSION = "5.2.0";
 var SCHEMA_VERSION = 2;
 
 // src/audit.ts
@@ -57306,7 +57306,7 @@ function validateSample(raw) {
   const ids = /* @__PURE__ */ new Set();
   pages?.forEach((pg, i2) => {
     if (typeof pg !== "object" || pg === null || Array.isArray(pg)) {
-      err2(`sample.pages[${i2}]`, "each page must be an object { id, name, url, auth?, storageState?, notes? }");
+      err2(`sample.pages[${i2}]`, "each page must be an object { id, name, url, auth?, storageState?, notes?, sources? }");
       return;
     }
     const p = pg;
@@ -57330,6 +57330,8 @@ function validateSample(raw) {
       );
     }
     if (p.notes !== void 0 && typeof p.notes !== "string") err2(`sample.pages[${i2}].notes`, "notes must be a string");
+    if (p.sources !== void 0 && (!Array.isArray(p.sources) || p.sources.some((s2) => typeof s2 !== "string")))
+      err2(`sample.pages[${i2}].sources`, "sources must be an array of file paths");
   });
   if (s.transverse !== void 0) {
     if (!Array.isArray(s.transverse)) {
@@ -57350,7 +57352,8 @@ function normalizeSample(s) {
     url: String(p.url),
     ...typeof p.auth === "boolean" ? { auth: p.auth } : {},
     ...typeof p.storageState === "string" ? { storageState: p.storageState } : {},
-    ...typeof p.notes === "string" ? { notes: p.notes } : {}
+    ...typeof p.notes === "string" ? { notes: p.notes } : {},
+    ...Array.isArray(p.sources) ? { sources: p.sources } : {}
   }));
   const transverse = Array.isArray(s.transverse) ? s.transverse.map(String) : void 0;
   return { pages, ...transverse?.length ? { transverse } : {} };

package/skills/review-a11y/SKILL.md

@@ -5,7 +5,7 @@ when_to_use: "Invoke WITHOUT being asked whenever changed front-end code should
 allowed-tools: Bash(node ${CLAUDE_SKILL_DIR}/scripts/ultra11y.mjs *), Read, Grep, Glob
 license: MIT
 metadata:
-  version: 5.0.1
+  version: 5.2.0
 ---
 
 # review-a11y — accessibility review of changed code

package/skills/review-a11y/scripts/ultra11y.mjs

@@ -6,7 +6,7 @@ import { join as join50, relative as relative5, resolve as resolve15, sep as sep
 import { fileURLToPath as fileURLToPath5, pathToFileURL as pathToFileURL3 } from "url";
 
 // src/types.ts
-var VERSION = "5.0.1";
+var VERSION = "5.2.0";
 var SCHEMA_VERSION = 2;
 
 // src/audit.ts
@@ -57306,7 +57306,7 @@ function validateSample(raw) {
   const ids = /* @__PURE__ */ new Set();
   pages?.forEach((pg, i2) => {
     if (typeof pg !== "object" || pg === null || Array.isArray(pg)) {
-      err2(`sample.pages[${i2}]`, "each page must be an object { id, name, url, auth?, storageState?, notes? }");
+      err2(`sample.pages[${i2}]`, "each page must be an object { id, name, url, auth?, storageState?, notes?, sources? }");
       return;
     }
     const p = pg;
@@ -57330,6 +57330,8 @@ function validateSample(raw) {
       );
     }
     if (p.notes !== void 0 && typeof p.notes !== "string") err2(`sample.pages[${i2}].notes`, "notes must be a string");
+    if (p.sources !== void 0 && (!Array.isArray(p.sources) || p.sources.some((s2) => typeof s2 !== "string")))
+      err2(`sample.pages[${i2}].sources`, "sources must be an array of file paths");
   });
   if (s.transverse !== void 0) {
     if (!Array.isArray(s.transverse)) {
@@ -57350,7 +57352,8 @@ function normalizeSample(s) {
     url: String(p.url),
     ...typeof p.auth === "boolean" ? { auth: p.auth } : {},
     ...typeof p.storageState === "string" ? { storageState: p.storageState } : {},
-    ...typeof p.notes === "string" ? { notes: p.notes } : {}
+    ...typeof p.notes === "string" ? { notes: p.notes } : {},
+    ...Array.isArray(p.sources) ? { sources: p.sources } : {}
   }));
   const transverse = Array.isArray(s.transverse) ? s.transverse.map(String) : void 0;
   return { pages, ...transverse?.length ? { transverse } : {} };

package/skills/ultra11y/SKILL.md

@@ -4,7 +4,7 @@ description: "Use to AUDIT existing HTML/CSS/JSX against WCAG 2.2 AA accessibili
 when_to_use: "Invoke when the user asks for an accessibility AUDIT or a formal deliverable: audit a repo, site or page against WCAG 2.2 AA or a country standard (RGAA, Section 508, EN 301 549); produce a dated conformance report, a criterion grid, a PRD backlog, or tickets (GitHub/GitLab/Jira); author accessible markup from scratch; wire the repo gate (init --hook/--ci) or a rendered-DOM capture pipeline. For a review of the code UNDER CHANGE (diff, branch, PR), use the `review-a11y` skill instead."
 license: MIT
 metadata:
-  version: 5.0.1
+  version: 5.2.0
 ---
 
 # ultra11y — audit WCAG 2.2 AA and write accessible markup

package/skills/ultra11y/references/e2e.md

@@ -33,6 +33,56 @@ than restating them, and a test evaluates the generated `failingFindings` alongs
 one over the same findings. A fixture that gated differently from the published plugin would
 fail two projects differently while claiming to be the same tool.
 
+
+
+## Sweeping the declared sample (`sweepSample`)
+
+The sample in `.ultra11yrc.json` already says what every page is — id, name, URL, whether it
+sits behind a login, the `sources` that render it. A repo that then hand-writes a route table
+to drive its sweep keeps a second copy of that, and the two drift: a page renamed in one place
+keeps its old identity in the report, which is the failure this tier exists to prevent.
+
+So let the sample drive it:
+
+```ts
+import { sweepSample } from "ultra11y/playwright";
+
+sweepSample({
+  // Your framework's readiness. Without it a design system that boots asynchronously is
+  // serialized half-mounted, and the audit reports markup no user ever meets.
+  settle: async (page) => { await page.waitForLoadState("networkidle").catch(() => {}); },
+  // Pages your own specs drive — a wizard step that needs state seeded first.
+  only: (p) => !p.id.startsWith("declaration-etape-"),
+});
+```
+
+One test per page, each navigated, checked against `expectPath` and its HTTP status, and
+recorded under its declared identity. A page the browser did not stay on is `test.skip`ped
+with the reason.
+
+`samplePagesFor()` and `sweepTarget()` are the same logic without the runner, for a repo that
+wants to declare its own tests.
+
+## A page the browser did not stay on (`expectPath`)
+
+`as`/`name` is the identity the report speaks, and the fixture applies it to whatever is on
+screen. So a route your test could not open — a guarded step, an expired session — gets filed
+under the requested page's name, and its sheet, screenshot and rate all describe another
+screen. Nothing about the document looks wrong.
+
+Pass the path you navigated to and the fixture refuses instead:
+
+```js
+await checkA11y(page, { as: "declaration-etape-4", expectPath: "/declaration/etape/4" });
+// throws: /declaration/etape/4 landed on /declaration/etape/1 — not recording it as
+// "declaration-etape-4". The state that opens this route is not the one the test built.
+```
+
+Opt-in, and path-only: a query or fragment the app appends to its own route is the same page.
+`scan --sample` applies the same rule without being asked, because there the URL *is* the
+instruction. A page reported missing is a bug in your seeding; a page reported under the wrong
+name is a false conformance claim.
+
 ## Playwright
 
 ```js

package/skills/ultra11y/scripts/ultra11y.mjs

@@ -6,7 +6,7 @@ import { join as join50, relative as relative5, resolve as resolve15, sep as sep
 import { fileURLToPath as fileURLToPath5, pathToFileURL as pathToFileURL3 } from "url";
 
 // src/types.ts
-var VERSION = "5.0.1";
+var VERSION = "5.2.0";
 var SCHEMA_VERSION = 2;
 
 // src/audit.ts
@@ -57306,7 +57306,7 @@ function validateSample(raw) {
   const ids = /* @__PURE__ */ new Set();
   pages?.forEach((pg, i2) => {
     if (typeof pg !== "object" || pg === null || Array.isArray(pg)) {
-      err2(`sample.pages[${i2}]`, "each page must be an object { id, name, url, auth?, storageState?, notes? }");
+      err2(`sample.pages[${i2}]`, "each page must be an object { id, name, url, auth?, storageState?, notes?, sources? }");
       return;
     }
     const p = pg;
@@ -57330,6 +57330,8 @@ function validateSample(raw) {
       );
     }
     if (p.notes !== void 0 && typeof p.notes !== "string") err2(`sample.pages[${i2}].notes`, "notes must be a string");
+    if (p.sources !== void 0 && (!Array.isArray(p.sources) || p.sources.some((s2) => typeof s2 !== "string")))
+      err2(`sample.pages[${i2}].sources`, "sources must be an array of file paths");
   });
   if (s.transverse !== void 0) {
     if (!Array.isArray(s.transverse)) {
@@ -57350,7 +57352,8 @@ function normalizeSample(s) {
     url: String(p.url),
     ...typeof p.auth === "boolean" ? { auth: p.auth } : {},
     ...typeof p.storageState === "string" ? { storageState: p.storageState } : {},
-    ...typeof p.notes === "string" ? { notes: p.notes } : {}
+    ...typeof p.notes === "string" ? { notes: p.notes } : {},
+    ...Array.isArray(p.sources) ? { sources: p.sources } : {}
   }));
   const transverse = Array.isArray(s.transverse) ? s.transverse.map(String) : void 0;
   return { pages, ...transverse?.length ? { transverse } : {} };

package/src/integrations/cypress.ts

@@ -10,7 +10,7 @@
 // must be wired in `cypress.config.js` too — Cypress test code cannot write to disk, so the
 // collected page round-trips through a task.
 import { COLLECT_SNAPSHOT } from "../collector.js";
-import { type CheckOptions, buildPayload, slugify } from "./payload.js";
+import { type CheckOptions, buildPayload, slugify, stayedOnPage } from "./payload.js";
 
 // Cypress's globals are not a dependency of this package; they exist at run time only.
 declare const Cypress: {
@@ -45,6 +45,14 @@ export function registerUltra11yCommand(): void {
     return cy.window({ log: false }).then((win: { eval(s: string): unknown; location: { href: string } }) => {
       const collected = win.eval(COLLECT_SNAPSHOT) as Parameters<typeof buildPayload>[0];
       const url = collected.url || win.location.href;
+      // Same refusal as the Playwright fixture: a page the browser did not stay on must not
+      // be filed under the requested page's identity. See CheckOptions.expectPath.
+      if (opts.expectPath && !stayedOnPage(opts.expectPath, url)) {
+        throw new Error(
+          `ultra11y: ${opts.expectPath} landed on ${url} — not recording it as "${opts.as ?? opts.name ?? "this page"}". ` +
+            `The state that opens this route is not the one the test built; seed it first, or drop the page from the sample.`,
+        );
+      }
       const payload = {
         ...buildPayload(collected, url, "cypress", opts),
         failOn: opts.failOn,

package/src/integrations/payload.ts

@@ -98,6 +98,30 @@ export interface CheckOptions {
   notes?: string;
   /** Capture a viewport screenshot for the pixel tier (Playwright: on by default). */
   screenshot?: boolean;
+  /** The path you NAVIGATED to. Given it, the fixture refuses to record a page the browser
+   *  did not stay on — a guarded route that redirected, a session that expired — instead of
+   *  filing that other screen under this page's `as`/`name`. Nothing about such a snapshot
+   *  looks wrong, which is what makes it the worst thing an accessibility report can carry.
+   *  Compared by path (a query or fragment the app appends to its own route is the same
+   *  page); a full URL works too. `scan --sample` applies the same rule. */
+  expectPath?: string;
+}
+
+/** Did the browser stay on the page the caller asked for? Path-only, trailing slash folded;
+ *  anything unparseable passes — this catches a redirect, it does not invent one. */
+export function stayedOnPage(expected: string, actual: string): boolean {
+  if (!expected || !actual) return true;
+  const path = (u: string): string | undefined => {
+    try {
+      return new URL(u, "http://x.invalid").pathname.replace(/\/+$/, "");
+    } catch {
+      return undefined;
+    }
+  };
+  const a = path(expected);
+  const b = path(actual);
+  if (a === undefined || b === undefined) return true;
+  return a === b;
 }
 
 /** Build the snapshot payload from a collected page. Shared so every runner stamps the

package/src/integrations/playwright.ts

@@ -16,9 +16,11 @@
 // to `.ultra11y/pages/<id>/` (DOM + computed styles + boxes + stylesheets + screenshot), so
 // the same page re-audits offline with no browser: that is how CI decides the rendering
 // criteria without booting the app, and how the report speaks page by page. Commit it.
+import { readFileSync } from "node:fs";
 import { createRequire } from "node:module";
+import { join } from "node:path";
 import { COLLECT_SNAPSHOT } from "../collector.js";
-import { type AuditLike, type CheckOptions, auditSnapshot, buildPayload, gate, writePagesReport } from "./core.js";
+import { type AuditLike, type CheckOptions, auditSnapshot, buildPayload, gate, stayedOnPage, writePagesReport } from "./core.js";
 
 // Playwright's own types are not a dependency of this package (it is a peer of YOUR repo),
 // so the page object is structurally typed to exactly what is used.
@@ -52,6 +54,16 @@ export async function checkA11y(page: PlaywrightPage, opts: PlaywrightCheckOptio
   }
 
   const url = collected.url || page.url();
+  // Refuse a page the browser did not stay on, when the caller said where it went. The
+  // snapshot's identity is `as`/`name`, applied to whatever is on screen — so a guarded route
+  // that redirected would be filed under the requested page's name, and the resulting sheet,
+  // screenshot and rate would all describe another screen. Skipping loudly beats that.
+  if (opts.expectPath && !stayedOnPage(opts.expectPath, url)) {
+    throw new Error(
+      `ultra11y: ${opts.expectPath} landed on ${url} — not recording it as "${opts.as ?? opts.name ?? "this page"}". ` +
+        `The state that opens this route is not the one the test built; seed it first, or drop the page from the sample.`,
+    );
+  }
   const payload = buildPayload(collected, url, "playwright", opts, shot);
   const result = auditSnapshot(payload);
   if (opts.report) writePagesReport(typeof opts.report === "object" ? opts.report : {});
@@ -92,4 +104,112 @@ export const test: any = (() => {
   return undefined;
 })();
 
+/** Options for {@link sweepSample}. */
+export interface SweepOptions {
+  /** Where `.ultra11yrc.json` lives. Defaults to the process cwd. */
+  cwd?: string;
+  /** Which declared pages this sweep owns. Return false for a page the repo snapshots itself
+   *  — a wizard step that needs application state seeded first, say. Skipped pages are simply
+   *  not declared here; they are still in the sample, so the report still expects them. */
+  only?: (page: SamplePageLike) => boolean;
+  /** Awaited after navigation, before collecting. This is where a framework's readiness goes:
+   *  a design system that boots asynchronously will otherwise be serialized half-mounted, and
+   *  the audit reports non-conformities about markup no user ever meets. */
+  settle?: (page: PlaywrightPage) => Promise<void>;
+  /** Passed to every `checkA11y`. `failOn: false` (the default here) records without
+   *  asserting: the durable output of a sweep is the snapshot, not a red test. */
+  check?: Omit<PlaywrightCheckOptions, "as" | "name" | "auth" | "notes" | "sources" | "expectPath">;
+}
+
+export interface SamplePageLike {
+  id: string;
+  name: string;
+  url: string;
+  auth?: boolean;
+  notes?: string;
+  sources?: string[];
+}
+
+/** Declare one Playwright test per page of the `.ultra11yrc.json` sample.
+ *
+ *  The sample already says what every page is — id, name, URL, whether it sits behind a login,
+ *  the sources that render it. A repo that then hand-writes a route table to drive its sweep is
+ *  keeping a second copy of that, and the two drift: a page renamed in one place keeps its old
+ *  identity in the report, which is the failure this whole tier exists to prevent.
+ *
+ *  So the sample drives the sweep:
+ *
+ *  ```ts
+ *  import { test } from "@playwright/test";
+ *  import { sweepSample } from "ultra11y/playwright";
+ *
+ *  sweepSample({ settle: async (page) => { await page.waitForLoadState("networkidle"); } });
+ *  ```
+ *
+ *  Each page is navigated, checked against `expectPath` and its HTTP status, and recorded. A
+ *  page the browser did not stay on — or that answered an error at the requested address — is
+ *  `test.skip`ped with the reason, never filed under the requested name.
+ *
+ *  Pages your own specs drive (a funnel step that needs state seeded) are excluded with
+ *  `only`. */
+export function samplePagesFor(opts: Pick<SweepOptions, "cwd" | "only"> = {}): SamplePageLike[] {
+  const cwd = opts.cwd ?? process.cwd();
+  let declared: SamplePageLike[];
+  try {
+    const raw = readFileSync(join(cwd, ".ultra11yrc.json"), "utf8");
+    declared = (JSON.parse(raw) as { sample?: { pages?: SamplePageLike[] } }).sample?.pages ?? [];
+  } catch {
+    // Not "declare zero tests and pass" — that is indistinguishable from a sweep that ran.
+    throw new Error(`ultra11y: no readable .ultra11yrc.json in ${cwd} — sweepSample reads the page sample from it.`);
+  }
+  return declared.filter((p) => opts.only?.(p) ?? true);
+}
+
+/** The path a sample URL points at. The sample stores absolute URLs (it is also read by
+ *  `scan`, which needs a real address); a Playwright test wants the path, so its `baseURL`
+ *  applies. Anything unparseable is already a path. */
+export function sweepTarget(url: string): string {
+  try {
+    return new URL(url).pathname || url;
+  } catch {
+    return url;
+  }
+}
+
+export function sweepSample(opts: SweepOptions = {}): void {
+  const pages = samplePagesFor(opts);
+  const t = test;
+  if (!t) throw new Error("ultra11y: @playwright/test could not be resolved — sweepSample needs it.");
+  if (!pages.length) return;
+
+  // Serial by default is NOT imposed here: pages are independent unless the repo's own state
+  // makes them otherwise, and that is the repo's call (`workers` in its config).
+  for (const p of pages) {
+    const target = sweepTarget(p.url);
+    t(`a11y — ${p.name}`, async ({ page }: { page: PlaywrightPage & { goto(u: string): Promise<{ status(): number } | null> } }) => {
+      const response = await page.goto(target);
+      if (opts.settle) await opts.settle(page);
+
+      const landed = page.url();
+      t.skip(!stayedOnPage(target, landed), `${target} landed on ${landed} — the current state does not open this screen; nothing to record as "${p.name}"`);
+      const status = response?.status();
+      t.skip(
+        status !== undefined && status >= 400,
+        `${target} answered HTTP ${status} — an error page at the requested address; nothing to record as "${p.name}"`,
+      );
+
+      await checkA11y(page, {
+        failOn: false,
+        ...opts.check,
+        as: p.id,
+        name: p.name,
+        ...(p.auth !== undefined ? { auth: p.auth } : {}),
+        ...(p.notes ? { notes: p.notes } : {}),
+        ...(p.sources ? { sources: p.sources } : {}),
+        expectPath: target,
+      });
+    });
+  }
+}
+
 export type { AuditLike, CheckOptions };

package/src/sample.ts

@@ -54,7 +54,7 @@ export function validateSample(raw: unknown): SampleValidation {
   const ids = new Set<string>();
   pages?.forEach((pg, i) => {
     if (typeof pg !== "object" || pg === null || Array.isArray(pg)) {
-      err(`sample.pages[${i}]`, "each page must be an object { id, name, url, auth?, storageState?, notes? }");
+      err(`sample.pages[${i}]`, "each page must be an object { id, name, url, auth?, storageState?, notes?, sources? }");
       return;
     }
     const p = pg as Record<string, unknown>;
@@ -79,6 +79,8 @@ export function validateSample(raw: unknown): SampleValidation {
       );
     }
     if (p.notes !== undefined && typeof p.notes !== "string") err(`sample.pages[${i}].notes`, "notes must be a string");
+    if (p.sources !== undefined && (!Array.isArray(p.sources) || p.sources.some((s: unknown) => typeof s !== "string")))
+      err(`sample.pages[${i}].sources`, "sources must be an array of file paths");
   });
 
   if (s.transverse !== undefined) {
@@ -103,6 +105,7 @@ function normalizeSample(s: Record<string, unknown>): SampleConfig {
     ...(typeof p.auth === "boolean" ? { auth: p.auth } : {}),
     ...(typeof p.storageState === "string" ? { storageState: p.storageState } : {}),
     ...(typeof p.notes === "string" ? { notes: p.notes } : {}),
+    ...(Array.isArray(p.sources) ? { sources: p.sources as string[] } : {}),
   }));
   const transverse = Array.isArray(s.transverse) ? (s.transverse as string[]).map(String) : undefined;
   return { pages, ...(transverse?.length ? { transverse } : {}) };

package/src/types.ts

@@ -1,6 +1,6 @@
 // Single source of truth for shared types + the embedded version. sync-version.mjs
 // rewrites VERSION at release time (kept in lockstep with package.json + SKILL.md).
-export const VERSION = "5.0.1";
+export const VERSION = "5.2.0";
 export const SCHEMA_VERSION = 2;
 
 // Lang = the UI FRAME's language — the `L` localization tables each module (report,
@@ -34,6 +34,12 @@ export interface SamplePage {
   auth?: boolean; // the page sits behind authentication (renders an auth badge)
   storageState?: string; // Playwright storageState FILE PATH (content never read) — per-page auth
   notes?: string; // reproduction steps / required state, surfaced in the ticket repro block
+  // Source files that RENDER this page. A finding raised on the page's DOM is then reported
+  // against your component instead of against `dom.html`, which is the difference between a
+  // report a developer can act on and one that points at a serialized blob. Declared here so
+  // the sample is the single place a page is described — a repo that drives its own sweep no
+  // longer needs a parallel route table to carry them.
+  sources?: string[];
 }
 export interface SampleConfig {
   pages: SamplePage[];