@surea11y/core 1.1.2 → 1.3.0

package/README.md

@@ -198,6 +198,66 @@ For complete integration examples, see `docs/INTEGRATION.md`.
 
 ---
 
+#### Standalone browser bundle
+
+For a page that isn't driven by an automation framework at all — a manual
+QA pass, a bookmarklet, a browser extension — the package also ships a
+self-contained bundle that needs no `require`, no bundler, and no build
+step:
+
+```html
+<script src="node_modules/@surea11y/core/surea11y.browser.js"></script>
+<script>
+  const result = a11ycore.runa11yCoreInPage(
+    location.href, // pageUrl
+    null,           // contextSelector
+    {},             // engineOptions
+    null            // runOnly
+  );
+
+  console.log(result.checksResults.filter(r => r.outcome === "fail"));
+</script>
+```
+
+Loading `surea11y.browser.js` defines a single global, `a11ycore`, exposing
+the same `runa11yCoreInPage` function described above — calling it runs a
+real scan against the page it's loaded into and returns the same result
+shape documented in [Understanding the Results](#understanding-the-results).
+
+`contextSelector`, `engineOptions`, and `runOnly` are the same three
+arguments described throughout this README and `docs/ENGINE_OPTIONS.md` —
+nothing about calling the engine changes just because it's loaded this
+way. A scan scoped to one region, filtered to a specific WCAG level, with
+a couple of known-noisy selectors excluded, looks like this:
+
+```html
+<script src="node_modules/@surea11y/core/surea11y.browser.js"></script>
+<script>
+  const result = a11ycore.runa11yCoreInPage(
+    location.href,
+    "#main",                                     // contextSelector: scan only this region
+    {
+      excludeSelectors: ["#cookie-banner", ".intercom-launcher"],
+      contrast: { mode: "auditorAssist" }         // trade some false-positive protection for more findings
+    },
+    { tags: ["wcag2a", "wcag2aa"] }               // runOnly: WCAG 2.0 A/AA rules only
+  );
+
+  console.log(result.checksResults.filter(r => r.outcome === "fail"));
+</script>
+```
+
+This bundle is generated from the same rule sources as the rest of the
+engine (`npm run build` regenerates it alongside `src/core.js`), so its
+behavior never drifts from the library's. It intentionally exposes only
+`runa11yCoreInPage` — cross-frame scanning
+(`runa11yCoreAcrossFrames`/`a11yCoreEnableFrameResponder`) requires the
+embedded frame to also load the engine and opt in, which doesn't fit a
+single dropped-in `<script>` tag; reach for the npm package directly if
+you need that.
+
+---
+
 ## Understanding the Results
 
 Every scan returns a structured JSON document designed for both
@@ -270,7 +330,12 @@ and progressively explore more advanced features.
 | Document | Description |
 |---|---|
 | `docs/OUTPUT_SCHEMA.md` | Complete description of every field returned by the engine. |
+| `docs/API_STABILITY.md` | Semver guarantees on the result shape, and the rule-ID deprecation policy. |
 | `docs/CLI.md` | CLI commands, options, exit codes and examples. |
+| `docs/BASELINE.md` | CI baseline/allowlist: gate builds only on new violations. |
+| `docs/REPORT.md` | Self-contained HTML report: browsable summary, WCAG rollup, filterable occurrence table. |
+| `docs/SARIF.md` | SARIF 2.1.0 report for GitHub Code Scanning and other SARIF dashboards. |
+| `docs/CI_INTEGRATIONS.md` | GitHub Actions and Bitbucket Pipelines templates wrapping the CLI. |
 | `docs/ENGINE_OPTIONS.md` | Configuration, filtering, policies and localization. |
 | `docs/INTEGRATION.md` | Using surea11y with jsdom, Playwright, Puppeteer, Selenium, Cypress and other drivers. |
 | `docs/BINDING_AUTHORS_GUIDE.md` | Building new framework integrations on top of the engine. |
@@ -338,6 +403,8 @@ The repository is organised so that the accessibility engine, rule
 implementations and supporting infrastructure remain clearly separated.
 
 ```text
+surea11y.browser.js        # Generated standalone browser bundle
+
 bin/
   core.js                  # CLI entry point
 
@@ -420,10 +487,12 @@ supported versions and the preferred disclosure process.
 
 ## License
 
-This project is released under the MIT License.
+This project is released under the Mozilla Public License 2.0 (MPL-2.0).
 
 See the accompanying `LICENSE` file for the complete license text.
 
+MPL-2.0 is file-level copyleft: it applies to `@surea11y/core`'s own source files, not to code that merely depends on it. A project that installs `@surea11y/core` as a normal package dependency and imports its public API — without copying or modifying this repository's source files — is unaffected by MPL-2.0 and may keep its own license (including a permissive one like MIT).
+
 ---
 
 ## Final Notes

package/bin/core.js

@@ -21,6 +21,9 @@ const fs = require('fs');
 const path = require('path');
 
 const pkg = require('../package.json');
+const { buildBaselineEntries, matchBaseline } = require('../src/baseline.js');
+const { renderHtmlReport } = require('../src/report.js');
+const { renderSarifReport } = require('../src/sarif.js');
 
 // Piping output to `head`/`less`/etc. closes stdout early — without this,
 // the next write throws an unhandled EPIPE and crashes with a raw stack
@@ -43,18 +46,31 @@ Options:
   --exclude-rules <ids>   Comma-separated rule IDs to exclude
   --tags <tags>           Comma-separated tags to run (e.g. wcag2a,wcag2aa)
   --context <selector>    CSS selector to scope the scan to a subtree
+  --custom-rules <path>   Load runtime custom rules from a JS file (repeatable)
+  --write-baseline <path> Write every current "fail" occurrence to <path>; never fails the build
+  --baseline <path>       Gate only on occurrences not already recorded in <path>
+  --html <path>           Write a self-contained, browsable HTML report to <path>
+  --sarif <path>          Write a SARIF 2.1.0 report to <path> (for GitHub Code Scanning etc.)
   -h, --help              Show this help
   -v, --version           Show the installed version
 
 Exit codes:
-  0  scan completed, no "fail" outcomes
-  1  scan completed, at least one "fail" outcome
+  0  scan completed, no "fail" outcomes (or no *new* ones, with --baseline)
+  1  scan completed, at least one "fail" outcome (or *new* one, with --baseline)
   2  usage error or the scan itself could not run (bad path/URL, network failure, etc.)
 
 Examples:
   surea11y scan ./index.html
   surea11y scan https://example.com/ --tags wcag2a,wcag2aa
   surea11y scan ./index.html --json > result.json
+  surea11y scan ./index.html --write-baseline baseline.json
+  surea11y scan ./index.html --baseline baseline.json
+  surea11y scan ./index.html --html report.html
+  surea11y scan ./index.html --baseline baseline.json --sarif results.sarif
+  surea11y scan ./index.html --custom-rules ./a11y-rules.js
+
+See docs/BASELINE.md for the baseline/allowlist mechanism, docs/REPORT.md for the HTML report,
+docs/SARIF.md for the SARIF report, docs/CLI.md#custom-rules for custom rules.
 `);
 }
 
@@ -81,6 +97,21 @@ function parseArgs(argv) {
       case '--context':
         out.context = argv[++i];
         break;
+      case '--custom-rules':
+        (out.customRules = out.customRules || []).push(argv[++i]);
+        break;
+      case '--baseline':
+        out.baseline = argv[++i];
+        break;
+      case '--write-baseline':
+        out.writeBaseline = argv[++i];
+        break;
+      case '--html':
+        out.html = argv[++i];
+        break;
+      case '--sarif':
+        out.sarif = argv[++i];
+        break;
       case '-h':
       case '--help':
         out.help = true;
@@ -102,7 +133,12 @@ function isUrl(s) {
 
 function formatError(err) {
   const base = err && err.message ? err.message : String(err);
-  const cause = err && err.cause && err.cause.message ? err.cause.message : (err && err.cause ? String(err.cause) : '');
+  const cause =
+    err && err.cause && err.cause.message
+      ? err.cause.message
+      : err && err.cause
+        ? String(err.cause)
+        : '';
   return cause ? `${base}: ${cause}` : base;
 }
 
@@ -122,7 +158,7 @@ async function loadHtml(target) {
   return { html: fs.readFileSync(resolved, 'utf8'), url: `file://${resolved}` };
 }
 
-function buildEngineOptions(args) {
+function buildEngineOptions(args, customRules) {
   const engineOptions = {};
   if (args.locale) engineOptions.locale = args.locale;
   if (args.rules || args.excludeRules) {
@@ -131,23 +167,66 @@ function buildEngineOptions(args) {
     if (args.excludeRules) engineOptions.rules.exclude = args.excludeRules;
   }
   if (args.tags) engineOptions.tags = { include: args.tags };
+  if (customRules && customRules.length) engineOptions.customRules = customRules;
   return engineOptions;
 }
 
-function printSummary(result) {
+// Loads one --custom-rules file. The CLI runs custom rules in the same
+// process/JS realm as the scan itself (unlike a binding whose engineOptions
+// crosses page.evaluate()'s serialization boundary), so a descriptor's
+// runInPage/applicability may be a real function -- see the customRules
+// section of docs/ENGINE_OPTIONS.md for the full descriptor contract this
+// mirrors. Validated up front (not left to the engine's own silent-skip of
+// invalid entries) so a typo in a hand-authored file fails loudly as a usage
+// error instead of quietly producing a scan with one fewer rule than expected.
+function loadCustomRulesFile(customRulesPath) {
+  const resolved = path.resolve(process.cwd(), customRulesPath);
+
+  let loaded;
+  try {
+    loaded = require(resolved);
+  } catch (err) {
+    throw new Error(`Could not load custom rules file "${customRulesPath}": ${formatError(err)}`, {
+      cause: err
+    });
+  }
+
+  const descriptors = Array.isArray(loaded) ? loaded : [loaded];
+
+  for (const d of descriptors) {
+    const hasId = d && typeof d === 'object' && typeof d.id === 'string' && d.id.trim();
+    const hasRunInPage =
+      d &&
+      (typeof d.runInPage === 'function' ||
+        (typeof d.runInPage === 'string' && d.runInPage.trim()));
+    if (!hasId || !hasRunInPage) {
+      throw new Error(
+        `Custom rules file "${customRulesPath}" must export a rule descriptor ({ id, runInPage, ... }) or an array of them. See docs/CLI.md#custom-rules.`
+      );
+    }
+  }
+
+  return descriptors;
+}
+
+function printSummary(result, baselineMatch) {
   const byOutcome = { pass: 0, fail: 0, cantTell: 0, notApplicable: 0 };
   for (const r of result.checksResults) {
     if (Object.prototype.hasOwnProperty.call(byOutcome, r.outcome)) byOutcome[r.outcome] += 1;
   }
 
   process.stdout.write(`\nsurea11y scan: ${result.url || '(no url)'}\n`);
-  process.stdout.write(`  pass: ${byOutcome.pass}   fail: ${byOutcome.fail}   cantTell: ${byOutcome.cantTell}   notApplicable: ${byOutcome.notApplicable}\n\n`);
+  process.stdout.write(
+    `  pass: ${byOutcome.pass}   fail: ${byOutcome.fail}   cantTell: ${byOutcome.cantTell}   notApplicable: ${byOutcome.notApplicable}\n\n`
+  );
 
   const fails = result.checksResults.filter((r) => r.outcome === 'fail');
   if (fails.length) {
     process.stdout.write(`FAIL (${fails.length} rule(s)):\n`);
     for (const r of fails) {
-      process.stdout.write(`\n  ${r.ruleId}  (${r.severity}, ${r.occurrences.length} occurrence(s))\n`);
+      process.stdout.write(
+        `\n  ${r.ruleId}  (${r.severity}, ${r.occurrences.length} occurrence(s))\n`
+      );
       for (const occ of r.occurrences.slice(0, 5)) {
         process.stdout.write(`    - ${occ.selector || '(no selector)'}\n      ${occ.summary}\n`);
         if (occ.hint) process.stdout.write(`      hint: ${occ.hint}\n`);
@@ -161,8 +240,57 @@ function printSummary(result) {
 
   const cantTells = result.checksResults.filter((r) => r.outcome === 'cantTell');
   if (cantTells.length) {
-    process.stdout.write(`cantTell — needs human review (${cantTells.length} rule(s)): ${cantTells.map((r) => r.ruleId).join(', ')}\n\n`);
+    process.stdout.write(
+      `cantTell — needs human review (${cantTells.length} rule(s)): ${cantTells.map((r) => r.ruleId).join(', ')}\n\n`
+    );
+  }
+
+  if (baselineMatch) {
+    process.stdout.write(
+      `baseline: ${baselineMatch.knownCount} known, ${baselineMatch.newCount} new, ${baselineMatch.staleCount} stale (no longer detected)\n`
+    );
+    if (baselineMatch.newCount) {
+      process.stdout.write(`\nNEW (not in baseline, ${baselineMatch.newCount} occurrence(s)):\n`);
+      for (const occ of baselineMatch.newOccurrences.slice(0, 5)) {
+        process.stdout.write(
+          `  - ${occ.ruleId}: ${occ.selector || '(no selector)'}\n    ${occ.summary}\n`
+        );
+      }
+      if (baselineMatch.newOccurrences.length > 5) {
+        process.stdout.write(`  ... and ${baselineMatch.newOccurrences.length - 5} more\n`);
+      }
+    }
+    process.stdout.write('\n');
+  }
+}
+
+function loadBaselineFile(baselinePath) {
+  let raw;
+  try {
+    raw = fs.readFileSync(baselinePath, 'utf8');
+  } catch (err) {
+    throw new Error(
+      `Could not read baseline file "${baselinePath}": ${formatError(err)}. Run with --write-baseline ${baselinePath} first to create one.`,
+      { cause: err }
+    );
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`Baseline file "${baselinePath}" is not valid JSON: ${formatError(err)}`, {
+      cause: err
+    });
+  }
+
+  if (!parsed || parsed.version !== 1 || !Array.isArray(parsed.entries)) {
+    throw new Error(
+      `Baseline file "${baselinePath}" is not a supported baseline (expected { version: 1, entries: [...] }). Regenerate it with --write-baseline.`
+    );
   }
+
+  return parsed;
 }
 
 async function runScan(args) {
@@ -173,6 +301,38 @@ async function runScan(args) {
     return;
   }
 
+  if (args.baseline && args.writeBaseline) {
+    process.stderr.write(
+      'Error: --baseline and --write-baseline cannot be used together in the same run. See --help.\n'
+    );
+    process.exitCode = 2;
+    return;
+  }
+
+  let baselineFile = null;
+  if (args.baseline) {
+    try {
+      baselineFile = loadBaselineFile(args.baseline);
+    } catch (err) {
+      process.stderr.write(`Error: ${formatError(err)}\n`);
+      process.exitCode = 2;
+      return;
+    }
+  }
+
+  let customRules = [];
+  if (args.customRules && args.customRules.length) {
+    try {
+      for (const customRulesPath of args.customRules) {
+        customRules = customRules.concat(loadCustomRulesFile(customRulesPath));
+      }
+    } catch (err) {
+      process.stderr.write(`Error: ${formatError(err)}\n`);
+      process.exitCode = 2;
+      return;
+    }
+  }
+
   let html, url;
   try {
     ({ html, url } = await loadHtml(target));
@@ -186,7 +346,9 @@ async function runScan(args) {
   try {
     ({ JSDOM } = require('jsdom'));
   } catch {
-    process.stderr.write('Error: the surea11y CLI requires jsdom. Run `npm install jsdom` (it should already be a dependency of this package — this likely means a broken install).\n');
+    process.stderr.write(
+      'Error: the surea11y CLI requires jsdom. Run `npm install jsdom` (it should already be a dependency of this package — this likely means a broken install).\n'
+    );
     process.exitCode = 2;
     return;
   }
@@ -199,11 +361,76 @@ async function runScan(args) {
 
   let result;
   try {
-    result = runDomRulesInPage(url, args.context || null, buildEngineOptions(args), null);
+    result = runDomRulesInPage(
+      url,
+      args.context || null,
+      buildEngineOptions(args, customRules),
+      null
+    );
   } finally {
     dom.window.close();
   }
 
+  if (args.html) {
+    fs.writeFileSync(
+      args.html,
+      renderHtmlReport(result, { title: `surea11y scan report — ${target}` })
+    );
+    process.stderr.write(`Wrote HTML report to: ${args.html}\n`);
+  }
+
+  if (args.sarif) {
+    fs.writeFileSync(
+      args.sarif,
+      renderSarifReport(result, {
+        toolVersion: pkg.version,
+        informationUri: (pkg.homepage || '').replace(/#.*$/, ''),
+        baselineEntries: baselineFile ? baselineFile.entries : undefined
+      })
+    );
+    process.stderr.write(`Wrote SARIF report to: ${args.sarif}\n`);
+  }
+
+  if (args.writeBaseline) {
+    const entries = buildBaselineEntries(result);
+    const payload = { version: 1, generatedAt: new Date().toISOString(), entries };
+    fs.writeFileSync(args.writeBaseline, JSON.stringify(payload, null, 2) + '\n');
+
+    if (args.json) {
+      process.stdout.write(
+        JSON.stringify(
+          {
+            ...result,
+            baseline: { mode: 'write', path: args.writeBaseline, entries: entries.length }
+          },
+          null,
+          2
+        ) + '\n'
+      );
+    } else {
+      printSummary(result);
+    }
+    process.stderr.write(
+      `Wrote ${entries.length} occurrence(s) to baseline: ${args.writeBaseline}\n`
+    );
+    process.exitCode = 0;
+    return;
+  }
+
+  if (baselineFile) {
+    const match = matchBaseline(result, baselineFile.entries);
+
+    if (args.json) {
+      process.stdout.write(
+        JSON.stringify({ ...result, baseline: { mode: 'check', ...match } }, null, 2) + '\n'
+      );
+    } else {
+      printSummary(result, match);
+    }
+    process.exitCode = match.newCount > 0 ? 1 : 0;
+    return;
+  }
+
   if (args.json) {
     process.stdout.write(JSON.stringify(result, null, 2) + '\n');
   } else {
@@ -229,7 +456,9 @@ async function main() {
 
   const [command, ...rest] = args._;
   if (command !== 'scan') {
-    process.stderr.write(`Error: unknown command "${command}". Only "scan" is supported. See --help.\n`);
+    process.stderr.write(
+      `Error: unknown command "${command}". Only "scan" is supported. See --help.\n`
+    );
     process.exitCode = 2;
     return;
   }

package/docs/API_STABILITY.md

@@ -0,0 +1,61 @@
+# API stability & versioning
+
+`@surea11y/core` has real downstream consumers today: 5 first-party framework bindings (Playwright, Puppeteer, Selenium, WebdriverIO, Cypress) published to npm, plus a Jest/Vitest matcher (`@surea11y/test-matchers`, `toHaveNoA11yViolations()`) — all pinned to a `^1.1.0`-style semver range. Until now, "what counts as a breaking change" was implicit — discoverable only by reading source, not written down anywhere. This document makes that contract explicit.
+
+## Stable fields (covered by semver)
+
+Removing, renaming, or changing the type/meaning of any of these is a **major** version bump:
+
+- Top-level result: `engine.tag`, `engine.schemaVersion`, `url`, `checksResults` (an array), `rulesResults` (an array).
+- Each `checksResults[i]` / `rulesResults[i]` entry: `ruleId`, `outcome`, `outcomeNormalized`, `severity`, `confidence`, `type`, `title`, `description`, `meta` (including `meta.normativeMappings`, `meta.deprecated`/`.deprecation` — see below), `engineOptions`, `schemaVersion`.
+- Each occurrence (`occurrences[i]`): `selector`, `html`, `summary`, `hint`, `i18n`, `structuralPath`.
+- The rule **catalog** (`getChecksCatalog()`/`getRulesCatalog()`, a separate surface from a scan result — see `RULE_AUTHORING.md`): `ruleId`, `title`, `description`, `tags`, `wcagSc`, `normativeMappings`, `defaultSeverity`, `defaultConfidence`, `type`, `deprecated`/`.deprecation`. Note `tags` lives here, not on a per-scan `checksResults[i].meta` — the two surfaces intentionally carry different subsets of a rule's metadata.
+
+This list is deliberately not a new, invented guarantee — it codifies what the 6 real consumers above (and `docs/OUTPUT_SCHEMA.md`'s own worked examples) already depend on today, either directly or as documented shape.
+
+## Explicitly unstable (not covered by semver)
+
+- `perfStats` and `ruleTimings` — internal timing/debug counters, only present when `engineOptions.perfStats`/`.profileRules` is set. Shape not covered by this document.
+- `occurrences[i].data.details` — rule-specific, non-normative extra context. Shape varies per rule and may change in a patch release; treat as best-effort, not a stable contract (this was already noted in `docs/OUTPUT_SCHEMA.md` before this document existed).
+- `ruleInterfaceVersion` / `ruleVersion` on a rule's meta — currently unused scaffolding (every rule defaults to the same two static strings; nothing meaningfully sets or consumes them today). Not part of this contract until they're actually wired up to mean something.
+
+## What triggers which version bump
+
+- **Patch**: a correctness fix that changes *which* outcome a rule produces for the same input, without changing the shape or mechanism. Example: the fragment-scan applicability fix (`engineOptions.fragment`, see `ENGINE_OPTIONS.md`) changed several rules from incorrectly `fail`ing on a scoped subtree to correctly `notApplicable` — that's a patch, not a major bump, because no stable field's *shape* changed, only a bug got fixed. Don't over-index on "any output change = major" — bug fixes are expected to change output.
+- **Minor**: adding a new stable field, adding a new rule to the catalog, or marking an existing rule `deprecated` (see below).
+- **Major**: removing or renaming a stable field, changing a stable field's type or meaning, or removing a rule ID once its deprecation notice period has passed. Paired with an `engine.schemaVersion` bump specifically when the *shape* changes (as opposed to package-level major bumps for other reasons, e.g. dropping support for an old Node version).
+
+`engine.schemaVersion` has been `"1.0.0"` since the engine's first release and has never needed a bump — nothing has changed a stable field's shape yet. Adding the `deprecated`/`deprecation` meta fields described below is purely additive (new optional fields, ignored safely by anything not looking for them), so it does **not** warrant a schema bump either — this is the policy's first real application.
+
+## Rule-ID deprecation policy
+
+A rule can be marked deprecated in its own `meta`:
+
+```js
+const meta = {
+  // ...
+  deprecated: true,
+  deprecation: {
+    replacedBy: 'new-rule-id',   // or null if there's no direct replacement
+    reason: 'Why this rule is being retired.',
+    sinceVersion: '1.2.0'        // the package version this was first marked deprecated in
+  }
+};
+```
+
+`meta.deprecated: true` requires both `deprecation.reason` and `deprecation.sinceVersion` — `normalizeRuleMeta` (`src/core/rule-meta.js`) throws a clear build-time error otherwise, the same way it already validates `meta.i18n.titleKey`.
+
+**A deprecated rule keeps running and producing results completely normally** — `pass`/`fail`/`cantTell`/`notApplicable` exactly as before. Deprecation is a catalog-level signal (visible via `getChecksCatalog()`, and in `docs/RULE_CATALOG.md`) for integrators to plan a migration on their own schedule — deliberately **not** an automatic exclusion (there is no `engineOptions.excludeDeprecated` flag). Silently dropping a rule's results the moment it's deprecated would be exactly the kind of surprise this document exists to prevent.
+
+The process:
+1. Mark the rule `deprecated: true` with `deprecation.reason`/`.replacedBy`/`.sinceVersion` set. Document it under `CHANGELOG.md`'s `### Deprecated` section (a standard Keep-a-Changelog category that's been in this project's changelog template since the beginning but never actually used until now).
+2. Leave it running normally for at least one full minor version cycle after the deprecation, so integrators pinned to `^x.y.0` have a real chance to see it before it's gone.
+3. Remove the rule file entirely in a future **major** version, documented under `### Removed`.
+
+No rule has been deprecated yet as of this document's introduction — this is the mechanism, ready for the first real case.
+
+## See also
+
+- [`OUTPUT_SCHEMA.md`](./OUTPUT_SCHEMA.md) — the full result shape this document's stability rules apply to.
+- [`RULE_AUTHORING.md`](./RULE_AUTHORING.md) §4.1 — the full rule `meta` contract, including `deprecated`/`deprecation`.
+- [`ENGINE_OPTIONS.md`](./ENGINE_OPTIONS.md) — `engineOptions.fragment`, referenced above as a worked example of a patch-level behavior fix.

package/docs/BASELINE.md

@@ -0,0 +1,66 @@
+# Baseline / allowlist
+
+A strict CI gate ("fail the build on any `fail` outcome") is an adoption blocker for a team scanning an existing, imperfect site for the first time — they can't ship anything until every pre-existing violation is fixed. A baseline lets a team say "these N are already known — don't gate on them, but fail the moment a genuinely new one appears."
+
+```sh
+# Once: record every current fail occurrence, does not fail the build.
+surea11y scan ./dist/index.html --write-baseline baseline.json
+
+# Commit baseline.json to git.
+
+# From then on, in CI: only a NEW (not-yet-baselined) fail occurrence gates the build.
+surea11y scan ./dist/index.html --baseline baseline.json
+```
+
+The baseline file is meant to be committed to git, so accepting more accessibility debt becomes an explicit, reviewable decision — a new violation shows up as a new row in the file's diff in a PR, not a silent change in a count.
+
+## When this is useful
+
+- **Adopting scanning on an existing site.** The motivating case above: a first scan on a mature site can turn up hundreds of pre-existing violations. Baselining them once unblocks gating immediately instead of requiring "fix everything first."
+- **Incremental remediation with a visible burn-down.** Fix violations in batches, then periodically regenerate the baseline with `--write-baseline`. Each regeneration's git diff *shrinks* as entries disappear — the file itself becomes a progress tracker, and a PR that fixes a batch of issues shows exactly what got cleaned up.
+- **Third-party/vendor content you don't control.** A page embeds a widget (chat bubble, ad unit, payment iframe) with known, unfixable-by-you violations. Baselining just those specific occurrences is more precise than excluding the whole subtree via `excludeSelectors` (see [`ENGINE_OPTIONS.md`](./ENGINE_OPTIONS.md)) — new issues introduced anywhere else near it, including inside your own code, still gate normally.
+- **Regression safety net during a large refactor.** Mid-migration, some rules may legitimately fail temporarily in ways already tracked and being fixed across many PRs. Baselining the known-in-progress set still catches *unrelated* new regressions from other PRs during the same window, instead of turning the gate off entirely or blocking every PR on it.
+- **Staged rollout of a new or stricter rule.** Turning on a rule (or a whole WCAG level) the codebase isn't clean against yet: baseline the existing gaps, enable gating immediately, and prevent any *new* violations of that rule while the backlog is cleaned up separately — rather than waiting to enable the rule until the codebase is already compliant.
+
+## How matching works
+
+Nothing in an occurrence's shape is a perfect, page-position-independent identity (see [`OUTPUT_SCHEMA.md`](./OUTPUT_SCHEMA.md)): `selector` and `structuralPath` are both derived from the element's position in the DOM, so either can shift when *unrelated* markup changes elsewhere on the page, even though the flagged element itself never changed.
+
+Instead, a baseline entry's identity is:
+
+```
+ruleId + reasonCode + html
+```
+
+where `reasonCode` is the rule-specific code from `occurrence.data.details.reasonCode` (defaulting to `"DEFAULT"` when a rule doesn't set one), and `html` is the occurrence's outer-HTML snippet. This is content-based rather than position-based: it survives the flagged element moving around the page (a reorder, an unrelated sibling added/removed) as long as the flagged element's own markup doesn't change. `selector` is still recorded in the baseline file, but purely for human context when reading a diff — it is never used for matching.
+
+**Known limitation**: an element whose *own* markup includes dynamic content (a timestamp, a live counter, a randomly-generated id) will never match itself across two scans, since its `html` snippet differs every time. If your pages hit this case, the baseline mechanism won't help for those specific rules/elements — see "Alternative" below.
+
+Matching counts occurrences, not just presence: if a page has 3 elements that produce byte-identical `ruleId`+`reasonCode`+`html` (e.g. the same broken component repeated 3 times) and the baseline recorded only 1 of them, a fresh scan reports 1 known and 2 new — not all 3 as known.
+
+Baseline entries that don't match anything in a fresh scan are reported as **stale** (the violation was presumably fixed) — this is informational only and never gates the build; regenerate the baseline with `--write-baseline` periodically to clean these up.
+
+## File format
+
+```json
+{
+  "version": 1,
+  "generatedAt": "2026-07-30T12:00:00.000Z",
+  "entries": [
+    { "ruleId": "img-alt-present", "reasonCode": "DEFAULT", "selector": "html > body > img", "html": "<img src=\"logo.png\">" }
+  ]
+}
+```
+
+`--baseline <path>` rejects a file that isn't `{ version: 1, entries: [...] }` with a clear exit-2 error rather than guessing at an older/different format.
+
+## Combining with `--json`
+
+When `--baseline` or `--write-baseline` is used together with `--json`, the printed object gains a `baseline` key alongside the normal engine result (this is CLI-output-only — it is not part of the engine's own result contract described in `OUTPUT_SCHEMA.md`):
+
+- `--write-baseline`: `{ mode: "write", path, entries: <number written> }`
+- `--baseline`: `{ mode: "check", totalFail, knownCount, newCount, staleCount, newOccurrences: [...] }`
+
+## Alternative: diff two scans yourself
+
+If your pages don't fit this model (heavy dynamic content inside the flagged elements themselves), the always-available fallback is to diff two full `--json` outputs yourself — see [`INTEGRATION.md`](./INTEGRATION.md#ci-gating-a-build-on-the-result). That gives you full control over the identity/matching logic at the cost of writing it yourself.

package/docs/BINDING_AUTHORS_GUIDE.md

@@ -1,8 +1,8 @@
 # Binding authors' guide
 
-Written for whoever builds the *next* framework binding on top of `surea11y` (Puppeteer, Cypress, Selenium, WebdriverIO, whatever comes after) — not for someone consuming a binding, and not for someone calling the engine directly. If that's you, see [`INTEGRATION.md`](./INTEGRATION.md) instead.
+Written for whoever builds the *next* framework binding on top of `@surea11y/core` (Puppeteer, Cypress, Selenium, WebdriverIO, whatever comes after) — not for someone consuming a binding, and not for someone calling the engine directly. If that's you, see [`INTEGRATION.md`](./INTEGRATION.md) instead.
 
-The first real binding, `surea11y-playwright` (a sibling project, not part of this repo), has already worked through most of the design questions a new binding hits. This doc exists so the next one doesn't have to re-derive them — it's a checklist and a map of "what the engine already gives you for free" vs. "what every binding has to build itself," backed by what that binding actually did, not theory.
+The first real binding, `@surea11y/playwright` (a sibling project, not part of this repo), has already worked through most of the design questions a new binding hits. This doc exists so the next one doesn't have to re-derive them — it's a checklist and a map of "what the engine already gives you for free" vs. "what every binding has to build itself," backed by what that binding actually did, not theory.
 
 ## Core-engine vs. binding-layer: know which side you're on
 
@@ -10,19 +10,19 @@ Some engine-parity features (relative to other established engines) are **engine
 
 **Already engine-level, works the moment you call `runa11yCoreInPage`/`runDomRulesInPage` — no binding code needed:**
 - All rule execution, WCAG SC mapping, composite rollups.
-- `runOnly`/`engineOptions.rules`/`.tags`/`.tests` rule selection — including [WCAG-version filtering](./ENGINE_OPTIONS.md#filtering-by-wcag-version-21-vs-22) (`wcag21a`/`wcag22aa`-style tags): if your binding has any kind of `.withTags()`/`.options()` passthrough that forwards `runOnly`/`engineOptions` generically, WCAG-version filtering already works through it with zero extra code — just document the tag vocabulary for your users, the way `surea11y-playwright`'s README does.
+- `runOnly`/`engineOptions.rules`/`.tags`/`.tests` rule selection — including [WCAG-version filtering](./ENGINE_OPTIONS.md#filtering-by-wcag-version-21-vs-22) (`wcag21a`/`wcag22aa`-style tags): if your binding has any kind of `.withTags()`/`.options()` passthrough that forwards `runOnly`/`engineOptions` generically, WCAG-version filtering already works through it with zero extra code — just document the tag vocabulary for your users, the way `@surea11y/playwright`'s README does.
 - `structuralPath` on every `fail`/`cantTell` occurrence — if your binding passes occurrences through unreshaped (don't strip fields you don't recognize), this reaches your consumers automatically.
 - `engineOptions.customRules` — runtime rule registration. Works through a generic `engineOptions` passthrough too, **but** see the caveat below: if your binding crosses a serialization boundary (see next section), your consumers must pass `runInPage`/`applicability` as `fn.toString()` source, not a live function. Worth a dedicated `.withCustomRules([...])` convenience method for ergonomics, but not required for the feature to work.
-- Cross-frame scanning **if** your driver reaches every frame itself already (Puppeteer/Cypress/Selenium all can, via CDP or equivalent) — you don't need `runa11yCoreAcrossFrames`/`a11yCoreEnableFrameResponder` at all. Just call the engine once per frame your driver already gives you and merge the results yourself (see `surea11y-playwright`'s `.frames(true)`, which does exactly this — no engine change was needed for it). The `postMessage`-based cross-frame functions exist specifically for the *no-automation-driver* case (a plain injected script) and are the wrong tool for a driver-based binding.
+- Cross-frame scanning **if** your driver reaches every frame itself already (Puppeteer/Cypress/Selenium all can, via CDP or equivalent) — you don't need `runa11yCoreAcrossFrames`/`a11yCoreEnableFrameResponder` at all. Just call the engine once per frame your driver already gives you and merge the results yourself (see `@surea11y/playwright`'s `.frames(true)`, which does exactly this — no engine change was needed for it). The `postMessage`-based cross-frame functions exist specifically for the *no-automation-driver* case (a plain injected script) and are the wrong tool for a driver-based binding.
 
 **Binding-layer — your binding has to build these itself, the engine won't:**
-- **Element references.** The engine returns `selector`/`structuralPath` strings, never a live handle — it has no concept of your driver's element-reference type. Resolve `occurrences[i].selector` back to a real handle yourself (Playwright's approach: `page.evaluateHandle` instead of `page.evaluate`, then `elementHandle.$(selector)` per occurrence — see `.elementRef(true)` in `surea11y-playwright`).
-- **Result verbosity/reporter filtering.** The engine deliberately always returns every rule's outcome, including `pass`/`notApplicable` — "not a violations-only list" is a stated engine design choice (see [`OUTPUT_SCHEMA.md`](./OUTPUT_SCHEMA.md)), not an oversight to work around. If your consumers want a trimmed view for CI-scale output, that's a post-filter your binding adds (`surea11y-playwright`'s `.reportOnly(['fail','cantTell'])` is a simple array-filter over the full result — no engine change).
+- **Element references.** The engine returns `selector`/`structuralPath` strings, never a live handle — it has no concept of your driver's element-reference type. Resolve `occurrences[i].selector` back to a real handle yourself (Playwright's approach: `page.evaluateHandle` instead of `page.evaluate`, then `elementHandle.$(selector)` per occurrence — see `.elementRef(true)` in `@surea11y/playwright`).
+- **Result verbosity/reporter filtering.** The engine deliberately always returns every rule's outcome, including `pass`/`notApplicable` — "not a violations-only list" is a stated engine design choice (see [`OUTPUT_SCHEMA.md`](./OUTPUT_SCHEMA.md)), not an oversight to work around. If your consumers want a trimmed view for CI-scale output, that's a post-filter your binding adds (`@surea11y/playwright`'s `.reportOnly(['fail','cantTell'])` is a simple array-filter over the full result — no engine change).
 - **Formatted failure output for your framework's own assertion/reporting style** (e.g. Playwright/Jest-style multi-line failure messages). The engine's raw result is framework-agnostic on purpose; shaping it into "what shows up in a failed test's stack trace" is squarely binding territory.
 
 ## The serialization-boundary caveat
 
-If your binding drives a *separate JS realm* (a browser page/tab is a different realm than your Node test process — this is Playwright/Puppeteer/Selenium's situation, not Cypress's, since Cypress test code already runs in-browser), anything you hand to `page.evaluate()`-equivalent gets structurally cloned/JSON-serialized. **Live functions do not survive that boundary.** This bit `surea11y-playwright` in two places:
+If your binding drives a *separate JS realm* (a browser page/tab is a different realm than your Node test process — this is Playwright/Puppeteer/Selenium's situation, not Cypress's, since Cypress test code already runs in-browser), anything you hand to `page.evaluate()`-equivalent gets structurally cloned/JSON-serialized. **Live functions do not survive that boundary.** This bit `@surea11y/playwright` in two places:
 1. `runa11yCoreInPage` itself is designed around this — it's fully self-contained (`.toString()`-serializable, no closure over outer scope) specifically so it can be reconstructed from source inside the page realm.
 2. `engineOptions.customRules[].runInPage`/`.applicability` accept a function-source string for exactly this reason — a binding crossing this boundary must tell its consumers to pass `fn.toString()`, not `fn`. Document this prominently; it's an easy trap (a function looks like it should just work as an argument until it silently fails to serialize).
 
@@ -30,7 +30,7 @@ If your binding runs in the *same* realm as the page (a browser extension conten
 
 ## Things to check before shipping a new binding
 
-A short list, derived from what the audit pass on `surea11y-playwright` actually found missing on a first pass (per its own `ROADMAP.md`) — worth checking explicitly rather than assuming your binding's generic passthrough covers them:
+A short list, derived from what the audit pass on `@surea11y/playwright` actually found missing on a first pass (per its own `ROADMAP.md`) — worth checking explicitly rather than assuming your binding's generic passthrough covers them:
 - [ ] Combinations of your own filtering methods behave sanely together (e.g. include+exclude on the same ID, tag-include + tag-exclude on the same tag) — these interact through the engine's `includeMode`/exclude-always-wins semantics ([`ENGINE_OPTIONS.md`](./ENGINE_OPTIONS.md)), test them explicitly rather than assuming.
 - [ ] `structuralPath` and `customRules` still work correctly when combined with whatever binding-layer features you build (verbosity filtering, element refs, per-frame scanning) — a filter applied after the fact should never silently drop fields a consumer expects on a surviving occurrence.
 - [ ] If you support cross-frame scanning via your own driver, confirm each frame's result gets the same normalization (selector/structuralPath/severity) as a single-document scan — don't let a "per-frame" code path silently skip the shared result-shaping logic.
@@ -38,4 +38,4 @@ A short list, derived from what the audit pass on `surea11y-playwright` actually
 
 ## A known engine-side tradeoff worth knowing about
 
-`src/core.js` is not small (~3.1MB as of 2026-07-22) because the bundler-free, no-driver-context functions (`runa11yCoreInPage`, `runa11yCoreAcrossFrames`, `a11yCoreEnableFrameResponder`) each carry their own complete self-contained copy of the rule catalog. If your binding only ever uses `require('@surea11y/core')` in Node and injects `runa11yCoreInPage.toString()` into the page (the same pattern `surea11y-playwright` uses), your actual browser-injected payload is unaffected by this — only your Node-side `require()` footprint grows. Worth knowing if your binding's own package size matters to your consumers.
+`src/core.js` is not small (~3.1MB as of 2026-07-22) because the bundler-free, no-driver-context functions (`runa11yCoreInPage`, `runa11yCoreAcrossFrames`, `a11yCoreEnableFrameResponder`) each carry their own complete self-contained copy of the rule catalog. If your binding only ever uses `require('@surea11y/core')` in Node and injects `runa11yCoreInPage.toString()` into the page (the same pattern `@surea11y/playwright` uses), your actual browser-injected payload is unaffected by this — only your Node-side `require()` footprint grows. Worth knowing if your binding's own package size matters to your consumers.