ultra11y 5.1.0 → 5.2.1

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.1.0",
+      "version": "5.2.1",
       "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.1.0",
+  "version": "5.2.1",
   "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.1.0",
+  "version": "5.2.1",
   "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.1.0";
+const ULTRA11Y_PLUGIN_VERSION = "5.2.1";
 
 const here = dirname(fileURLToPath(import.meta.url));
 

package/dist/playwright.d.ts

@@ -31,5 +31,62 @@ 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.
+     *
+     *  Typed loosely on purpose. The caller writes this against Playwright's real `Page` — with
+     *  `waitForLoadState`, `waitForFunction`, locators — and Playwright is not a dependency of
+     *  this package, so the narrow structural shape the collector needs would reject the very
+     *  function this option exists to take. Same reasoning as `test` below. */
+    settle?: (page: any) => Promise<void> | 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 = [
@@ -263,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.1.0",
+  "version": "5.2.1",
   "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.1.0";
+var VERSION = "5.2.1";
 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.1.0
+  version: 5.2.1
 ---
 
 # 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.1.0";
+var VERSION = "5.2.1";
 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.1.0
+  version: 5.2.1
 ---
 
 # ultra11y — audit WCAG 2.2 AA and write accessible markup

package/skills/ultra11y/references/e2e.md

@@ -34,6 +34,35 @@ one over the same findings. A fixture that gated differently from the published
 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

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.1.0";
+var VERSION = "5.2.1";
 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/playwright.ts

@@ -16,7 +16,9 @@
 // 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, stayedOnPage, writePagesReport } from "./core.js";
 
@@ -102,4 +104,118 @@ 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.
+   *
+   *  Typed loosely on purpose. The caller writes this against Playwright's real `Page` — with
+   *  `waitForLoadState`, `waitForFunction`, locators — and Playwright is not a dependency of
+   *  this package, so the narrow structural shape the collector needs would reject the very
+   *  function this option exists to take. Same reasoning as `test` below. */
+  // biome-ignore lint/suspicious/noExplicitAny: the shape is Playwright's, which is not a dependency here
+  settle?: (page: any) => Promise<void> | 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.1.0";
+export const VERSION = "5.2.1";
 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[];