@surea11y/core 1.2.0 → 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
@@ -274,6 +334,8 @@ and progressively explore more advanced features.
 | `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. |
@@ -341,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
 
@@ -423,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

@@ -23,6 +23,7 @@ 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
@@ -45,9 +46,11 @@ 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
 
@@ -63,8 +66,11 @@ Examples:
   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.
+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.
 `);
 }
 
@@ -91,6 +97,9 @@ 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;
@@ -100,6 +109,9 @@ function parseArgs(argv) {
       case '--html':
         out.html = argv[++i];
         break;
+      case '--sarif':
+        out.sarif = argv[++i];
+        break;
       case '-h':
       case '--help':
         out.help = true;
@@ -121,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;
 }
 
@@ -141,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) {
@@ -150,9 +167,48 @@ 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;
 }
 
+// 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) {
@@ -160,13 +216,17 @@ function printSummary(result, baselineMatch) {
   }
 
   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`);
@@ -180,15 +240,21 @@ function printSummary(result, baselineMatch) {
 
   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`);
+    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`);
+        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`);
@@ -203,18 +269,25 @@ function loadBaselineFile(baselinePath) {
   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.`);
+    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)}`);
+    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.`);
+    throw new Error(
+      `Baseline file "${baselinePath}" is not a supported baseline (expected { version: 1, entries: [...] }). Regenerate it with --write-baseline.`
+    );
   }
 
   return parsed;
@@ -229,7 +302,9 @@ async function runScan(args) {
   }
 
   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.stderr.write(
+      'Error: --baseline and --write-baseline cannot be used together in the same run. See --help.\n'
+    );
     process.exitCode = 2;
     return;
   }
@@ -245,6 +320,19 @@ async function runScan(args) {
     }
   }
 
+  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));
@@ -258,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;
   }
@@ -271,27 +361,58 @@ 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}` }));
+    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');
+      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.stderr.write(
+      `Wrote ${entries.length} occurrence(s) to baseline: ${args.writeBaseline}\n`
+    );
     process.exitCode = 0;
     return;
   }
@@ -300,7 +421,9 @@ async function runScan(args) {
     const match = matchBaseline(result, baselineFile.entries);
 
     if (args.json) {
-      process.stdout.write(JSON.stringify({ ...result, baseline: { mode: 'check', ...match } }, null, 2) + '\n');
+      process.stdout.write(
+        JSON.stringify({ ...result, baseline: { mode: 'check', ...match } }, null, 2) + '\n'
+      );
     } else {
       printSummary(result, match);
     }
@@ -333,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

@@ -1,6 +1,6 @@
 # API stability & versioning
 
-`@surea11y/core` has real downstream consumers today (5 framework bindings — Playwright, Puppeteer, Selenium, WebdriverIO, Cypress — plus a Jest/Vitest matcher package), 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.
+`@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)
 

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.

package/docs/CI_INTEGRATIONS.md

@@ -0,0 +1,103 @@
+# CI/CD pipeline integrations
+
+Ready-to-paste templates wrapping the [CLI](./CLI.md) (`npx @surea11y/core scan ...`) in GitHub Actions and Bitbucket Pipelines. If you're calling the library directly from your own Node script instead of the CLI, see [`INTEGRATION.md`](./INTEGRATION.md#ci-gating-a-build-on-the-result) instead — this page is specifically about the CLI as a pipeline step.
+
+All of these rely on the CLI's own exit codes (`0` clean, `1` at least one — or one *new*, with `--baseline` — `fail` outcome, `2` a usage/scan error) to gate the pipeline; no extra scripting is required for basic pass/fail gating.
+
+## GitHub Actions
+
+### Basic: gate on exit code
+
+```yaml
+name: Accessibility scan
+on: [pull_request]
+
+jobs:
+  a11y-scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm ci && npm run build   # produce whatever static HTML you're scanning
+      - run: npx @surea11y/core scan ./dist/index.html
+```
+
+This fails the job the moment any `fail` outcome is found. For an existing site with pre-existing violations, see the baseline variant below instead of disabling the step.
+
+### With a baseline (existing site, gate only on new violations)
+
+```sh
+# Once, locally: record every current fail occurrence, commit the file.
+npx @surea11y/core scan ./dist/index.html --write-baseline a11y-baseline.json
+git add a11y-baseline.json
+```
+
+```yaml
+      - run: npm ci && npm run build
+      - run: npx @surea11y/core scan ./dist/index.html --baseline a11y-baseline.json
+```
+
+See [`BASELINE.md`](./BASELINE.md) for what counts as "known" vs. "new", and how to regenerate the file as violations get fixed.
+
+### Uploading SARIF to GitHub Code Scanning
+
+`upload-sarif` needs `security-events: write` permission and does not fail the job itself — pair it with a separate gating step (or `continue-on-error` + your own check) if you also want the build to fail on new violations.
+
+```yaml
+name: Accessibility scan
+on: [pull_request]
+
+permissions:
+  contents: read
+  security-events: write
+
+jobs:
+  a11y-scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm ci && npm run build
+      - name: Scan (report, don't fail the job here)
+        run: npx @surea11y/core scan ./dist/index.html --baseline a11y-baseline.json --sarif results.sarif
+        continue-on-error: true
+        id: scan
+      - name: Upload SARIF to Code Scanning
+        uses: github/codeql-action/upload-sarif@v3
+        with:
+          sarif_file: results.sarif
+      - name: Fail the job on new violations
+        if: steps.scan.outcome == 'failure'
+        run: exit 1
+```
+
+See [`SARIF.md`](./SARIF.md) for the output format and a known limitation: a scan of a **local file** in your checkout gets inline annotations in the Code Scanning UI; a scan of a **live URL** doesn't (SARIF/Code Scanning can only associate a finding with a real file in the repository).
+
+## Bitbucket Pipelines
+
+Bitbucket Pipelines has no built-in SARIF-consuming dashboard equivalent to GitHub Code Scanning, so the CLI's exit code (plus, optionally, `--html` as a downloadable pipeline artifact) is the practical integration point rather than `--sarif`.
+
+```yaml
+pipelines:
+  pull-requests:
+    '**':
+      - step:
+          name: Accessibility scan
+          image: node:20
+          script:
+            - npm ci
+            - npm run build
+            - npx @surea11y/core scan ./dist/index.html --baseline a11y-baseline.json --html a11y-report.html
+          artifacts:
+            - a11y-report.html
+```
+
+The step fails the pipeline on the CLI's exit code exactly like any other `script` entry; `a11y-report.html` (see [`REPORT.md`](./REPORT.md)) is attached as a downloadable build artifact so a reviewer can open it without re-running the scan locally.
+
+## Free-tier/private-repo minute limits
+
+If your pipeline provider's free tier is minute-limited (Bitbucket Pipelines' free tier is 50 build-minutes/month on private workspaces, for example), a `jsdom`-based scan of static/server-rendered HTML (what the CLI does) is far cheaper than driving a real browser — see [`CLI.md`](./CLI.md#what-it-can-and-cant-scan) for what that trades away (no client-rendered content, no real CSS layout).