@surea11y/core 1.2.0 → 1.4.0

package/README.md

@@ -1,33 +1,57 @@
 # @surea11y/core
 
-> **Reliable accessibility testing for real web applications.**
+[![surea11y core](docs/assets/brand-tag-dark.svg#gh-dark-mode-only)](https://www.npmjs.com/package/@surea11y/core#gh-dark-mode-only)
+[![surea11y core](docs/assets/brand-tag-light.svg#gh-light-mode-only)](https://www.npmjs.com/package/@surea11y/core#gh-light-mode-only)
+[![npm](https://img.shields.io/npm/v/@surea11y/core?style=flat-square&label=npm&labelColor=101413&color=3A4441)](https://www.npmjs.com/package/@surea11y/core)
+[![node](https://img.shields.io/node/v/@surea11y/core?style=flat-square&label=node&labelColor=101413&color=3A4441)](package.json)
+[![license](https://img.shields.io/badge/license-MPL--2.0-3A4441?style=flat-square&labelColor=101413)](LICENSE)
 
-surea11y is an accessibility engine designed to help development teams
-identify objective accessibility issues early in the software lifecycle.
-It runs against either static HTML or fully rendered browser pages,
-producing deterministic, standards-traceable results that are suitable
-for local development, automated testing and CI/CD pipelines.
+> **Accessibility testing that tells you what it can't tell you.**
 
-Unlike browser extensions or cloud-based services, surea11y is a
-library-first project. You install it, run it where your code runs, and
-receive structured results that can be consumed by people, scripts or
-reporting tools.
+surea11y is an accessibility engine for teams that need to know what automated
+testing *can't* establish. It reports findings, non-findings, and — unusually —
+explicit uncertainty, so results are auditable rather than reassuring.
 
-## Why surea11y?
+*Sure* means certainty about what is known, and honesty about what isn't.
 
-Accessibility automation is only valuable if developers can trust its
-results.
+It runs against either static HTML or fully rendered browser pages, producing
+deterministic, standards-traceable results suitable for local development,
+automated testing and CI/CD pipelines.
 
-surea11y is built around a conservative philosophy: **never report
-certainty when certainty cannot be established objectively.**
+Unlike browser extensions or cloud-based services, surea11y is a library-first
+project. You install it, run it where your code runs, and receive structured
+results that can be consumed by people, scripts or reporting tools.
 
-Instead of relying on heuristics that may generate false positives, each
-rule makes a single deterministic decision. If a violation can be
-proven, the outcome is `fail`. If human judgement is required, the
-engine reports `cantTell` instead of guessing.
+## What automated testing can and cannot do
 
-This makes the engine predictable, reproducible and suitable for
-automated quality gates.
+Automated tools are commonly reckoned to catch somewhere around a third of WCAG
+issues. The remainder require human judgement. That ceiling is a property of
+static analysis itself, not a gap in any particular tool.
+
+surea11y's answer is to be explicit about which side of that line every result
+falls on. Each rule makes a single deterministic decision:
+
+- **`fail`** — a violation provable from the DOM. Reserved for objective,
+  normative cases.
+- **`pass`** — this rule's specific condition is met. Not a claim that the page
+  is accessible.
+- **`cantTell`** — a human has to decide this, and the result says what was
+  ambiguous.
+- **`notApplicable`** — the rule's precondition isn't present.
+
+`cantTell` is the point of the project. An engine that quietly discards what it
+cannot determine produces a shorter report and a false sense of coverage.
+
+## What this engine does not detect
+
+Keyboard traps, reflow and clipping at 400% zoom, anything that only exists
+after a click or an async load, and judgement calls such as whether a heading is
+meaningful — these lie outside what a static DOM scan can establish. Each is a
+reasoned decision rather than an oversight.
+
+[`docs/LIMITATIONS.md`](./docs/LIMITATIONS.md) lists them in full with the
+reasoning for each. A `pass` from this engine — or from any automated tool — is
+never a substitute for the manual review WCAG itself requires.
 
 ### Key principles
 
@@ -44,7 +68,9 @@ automated quality gates.
 - **Extensible.** Add custom rules, register policies and filter scans
   by rule IDs, tags or WCAG version.
 - **Localized reporting.** Human-readable messages can be translated
-  without affecting machine-readable data.
+  without affecting machine-readable data. Ships with `en`, `fr`, `de`,
+  and `es` today — see [`docs/I18N.md`](./docs/I18N.md) to use one or
+  contribute another.
 
 ---
 
@@ -92,6 +118,26 @@ For a detailed comparison of both execution models, see
 
 ---
 
+## Which package do I need?
+
+surea11y is a family of packages sharing one engine. Install the one that
+matches how you test — each pulls in `@surea11y/core` for you.
+
+| I want to… | Install |
+|---|---|
+| Add accessibility checks to **Playwright** tests | [`@surea11y/playwright`](https://github.com/SureA11y/playwright#readme) |
+| …**Puppeteer** | [`@surea11y/puppeteer`](https://github.com/SureA11y/puppeteer#readme) |
+| …**Selenium** | [`@surea11y/selenium`](https://github.com/SureA11y/selenium#readme) |
+| …**Cypress** | [`@surea11y/cypress`](https://github.com/SureA11y/cypress#readme) |
+| …**WebdriverIO** | [`@surea11y/webdriverio`](https://github.com/SureA11y/webdriverio#readme) |
+| Assert in **Jest or Vitest** component tests | [`@surea11y/test-matchers`](https://github.com/SureA11y/test-matchers#readme) |
+| Scan static HTML from a **terminal or CI pipeline** | [`@surea11y/cli`](https://github.com/SureA11y/cli#readme) |
+| Run the engine against **a DOM I already have** | `@surea11y/core` (this package) |
+
+The rest of this README covers `@surea11y/core` itself.
+
+---
+
 ## Installation
 
 Install the core package from npm:
@@ -100,10 +146,13 @@ Install the core package from npm:
 npm install @surea11y/core
 ```
 
-The core engine has no runtime dependencies — requiring the library
-itself never loads `jsdom`. Only the bundled CLI loads it, and only
-when you actually run a scan, keeping the library lightweight and
-suitable for embedding into your own tooling.
+The core engine has **zero runtime dependencies**. Installing it pulls
+nothing else into your tree, which keeps it lightweight and suitable for
+embedding into your own tooling.
+
+The engine needs a DOM to read, but it never creates one — you supply it,
+whether that's jsdom, a Playwright page, or the live document in a
+browser. That is why nothing is installed on your behalf.
 
 ---
 
@@ -111,18 +160,21 @@ suitable for embedding into your own tooling.
 
 ### CLI
 
-The CLI is the fastest way to analyse a page without writing any code.
+The CLI ships as a separate package, [`@surea11y/cli`](https://www.npmjs.com/package/@surea11y/cli),
+so that installing the engine never pulls a DOM implementation into
+projects that already have one:
 
 ```bash
-npx @surea11y/core scan ./index.html
-npx @surea11y/core scan https://example.com/
+npx @surea11y/cli scan ./index.html
+npx @surea11y/cli scan https://example.com/
 ```
 
 The CLI analyses static HTML. It does not execute client-side
 JavaScript, making it ideal for static sites and server-rendered
 applications.
 
-For available options, exit codes and advanced usage, see `docs/CLI.md`.
+For available options, exit codes and advanced usage, see the
+[CLI documentation](https://github.com/SureA11y/cli#readme).
 
 ---
 
@@ -133,7 +185,12 @@ surea11y exposes two entry points depending on where your code executes.
 #### Node.js + jsdom
 
 Use `runDomRulesInPage()` when your application already has a DOM
-available through jsdom.
+available through jsdom. jsdom is not a dependency of this package, so
+install it alongside if you don't already have it:
+
+```bash
+npm install jsdom
+```
 
 ```js
 const { JSDOM } = require("jsdom");
@@ -198,6 +255,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
@@ -271,9 +388,10 @@ and progressively explore more advanced features.
 |---|---|
 | `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. |
@@ -341,8 +459,7 @@ The repository is organised so that the accessibility engine, rule
 implementations and supporting infrastructure remain clearly separated.
 
 ```text
-bin/
-  core.js                  # CLI entry point
+surea11y.browser.js        # Generated standalone browser bundle
 
 src/
   index.js                 # Public API
@@ -421,12 +538,35 @@ supported versions and the preferred disclosure process.
 
 ---
 
+## Versioning & stability
+
+`@surea11y/core` follows [semantic versioning](https://semver.org/). The result
+shape is a written contract — see [`docs/API_STABILITY.md`](docs/API_STABILITY.md)
+for exactly which fields are covered by semver, what triggers a patch/minor/major
+bump, the release cadence, and the rule-ID deprecation policy.
+
+In short: patch and minor releases are always backward-compatible, so a consumer
+pinned to a `^1.y.0` range is never broken by an upgrade within the `1.x` line.
+Correctness fixes ship as patches when ready; feature work is batched into
+periodic minors; breaking changes are reserved for major versions and are rare by
+design.
+
+## Maintainer
+
+surea11y is built and maintained by [Jorge Rumoroso](https://github.com/rumoroso).
+
+Bug reports and rule proposals are welcome via
+[issues](https://github.com/SureA11y/core/issues). For security disclosures see
+[`SECURITY.md`](./SECURITY.md).
+
 ## 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/surea11y-core.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+/* SPDX-License-Identifier: MPL-2.0 */
+
+'use strict';
+
+// Redirects the pre-1.4.0 `npx @surea11y/core scan ...` that older docs still
+// show. Not named `surea11y`: that belongs to @surea11y/cli, and core is a
+// transitive dependency of every binding, so both would collide in one .bin.
+
+process.stderr.write(
+  `The surea11y CLI is no longer part of @surea11y/core (moved in 1.4.0).
+
+  npx @surea11y/cli scan <file-or-url>
+
+Install it with: npm install --save-dev @surea11y/cli
+Docs: https://github.com/SureA11y/cli
+`
+);
+
+process.exit(2);

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)
 
@@ -13,6 +13,22 @@ Removing, renaming, or changing the type/meaning of any of these is a **major**
 
 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.
 
+## Package entry points (covered by semver)
+
+Since 1.4.0 the package declares an explicit `exports` map. These are the only importable paths, and removing or repointing one is a **major** bump:
+
+| Specifier | Resolves to | Contents |
+|---|---|---|
+| `@surea11y/core` | `src/index.js` | the full engine surface (`runDomRulesInPage`, `runa11yCoreInPage`, catalog accessors, …) |
+| `@surea11y/core/baseline` | `src/baseline.js` | `buildBaselineEntries()`, `matchBaseline()` |
+| `@surea11y/core/report` | `src/report.js` | `renderHtmlReport()` |
+| `@surea11y/core/sarif` | `src/sarif.js` | `renderSarifReport()` |
+| `@surea11y/core/browser` | `surea11y.browser.js` | the standalone browser bundle, for bundlers that resolve it as a module |
+
+Anything **not** in that table — `src/core/*`, `src/checks/*`, `src/i18n/*`, `src/policy/*`, and the generated `src/core.js` itself — is internal. Before 1.4.0 there was no `exports` map, so those paths were technically reachable via deep `require()`; they were never documented as public and are no longer resolvable. The `<script src="node_modules/@surea11y/core/surea11y.browser.js">` form documented in the README is a filesystem path, not module resolution, and is unaffected.
+
+Declaring this map is what lets the engine's internal file layout change without a major bump. Note that `src/checks/*` is still *shipped* (the generated bundle `require()`s it at runtime) — shipped is not the same as public.
+
 ## 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.
@@ -27,6 +43,16 @@ This list is deliberately not a new, invented guarantee — it codifies what the
 
 `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.
 
+## Release cadence
+
+The version number is the contract — not a measure of how much has changed or how often. surea11y follows semver strictly, so what a bump *means* is fixed regardless of how frequently they happen:
+
+- **Patch (`x.y.Z`)** — rule-correctness fixes and documentation updates. Released promptly, as needed, rather than held back; always safe to adopt within a major line.
+- **Minor (`x.Y.0`)** — additive, backward-compatible work: new rules, new locales, new `engineOptions`, new output formats. Batched into periodic releases rather than shipped one change at a time.
+- **Major (`X.0.0`)** — a breaking change to a stable field (see above). Rare by design; the entire point of the stable-fields list is to keep these infrequent and well-signposted.
+
+Because every `1.x` release is backward-compatible, a consumer pinned to a `^1.y.0` range is never broken by an upgrade within the line — so a steady stream of patch/minor releases reflects active maintenance and prompt fixes, not instability. Frequency of releases is not a signal of churn; a change to a **major** version is.
+
 ## Rule-ID deprecation policy
 
 A rule can be marked deprecated in its own `meta`:

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](https://github.com/SureA11y/cli#readme) (`npx @surea11y/cli 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/cli 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/cli scan ./dist/index.html --write-baseline a11y-baseline.json
+git add a11y-baseline.json
+```
+
+```yaml
+      - run: npm ci && npm run build
+      - run: npx @surea11y/cli 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/cli 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/cli 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 [the CLI docs](https://github.com/SureA11y/cli/blob/main/docs/CLI.md#what-it-can-and-cant-scan) for what that trades away (no client-rendered content, no real CSS layout).

package/docs/ENGINE_OPTIONS.md

@@ -224,6 +224,8 @@ See the option-by-option table above for anything not shown here, and the `custo
 
 Every shipped rule is baked into `src/core.js` at build time. `engineOptions.customRules` is the runtime escape hatch: an array of rule descriptors registered for that one call only — nothing is added to the static catalog (`getRulesCatalog()`/`getChecksCatalog()`), and nothing persists between calls. This is deliberate, not a limitation to work around: surea11y already takes fresh `engineOptions` per call with no mutable global config (unlike some other engines, which need a `configure()`/`reset()` step against a shared runtime), and custom rules follow that same per-call model.
 
+Calling the library directly is one way in; the CLI also exposes this via `--custom-rules <path>` (a local file, loaded once per scan) — see [the CLI docs](https://github.com/SureA11y/cli/blob/main/docs/CLI.md#custom-rules).
+
 A descriptor has the *same shape as an internal rule module's own export* — if you already know how to write a rule file for this engine, you already know this API:
 
 ```js

package/docs/I18N.md

@@ -6,10 +6,12 @@ Every rule's title/description, and every occurrence's summary/hint, is localize
 
 | Locale | File | Keys | Coverage vs. English |
 |---|---|---|---|
-| `en` (English) | `src/i18n/en.js` | 600 | 100% (the canonical/fallback set) |
-| `fr` (French) | `src/i18n/fr.js` | 600 | 100% |
+| `en` (English) | `src/i18n/en.js` | 614 | 100% (the canonical/fallback set) |
+| `fr` (French) | `src/i18n/fr.js` | 614 | 100% |
+| `de` (German) | `src/i18n/de.js` | 614 | 100% |
+| `es` (Spanish) | `src/i18n/es.js` | 614 | 100% |
 
-Both locales are fully translated as of this writing. That won't stay automatically true — every time a new rule (or a new i18n key) is added to `en.js`, `fr.js` needs the same key added, or it silently falls back to English for that string (see the fallback behavior below). There's no automated check for this yet; diff `Object.keys(require('./src/i18n/en.js'))` against `fr.js` after adding a rule to catch drift before it ships.
+All four locales are fully translated as of this writing. That won't stay automatically true — every time a new rule (or a new i18n key) is added to `en.js`, every other locale needs the same key added, or it silently falls back to English for that string (see the fallback behavior below). `tests/i18n/i18n-locale-completeness.test.js` catches this: it fails the build if a locale listed in `FULLY_TRANSLATED_LOCALES` (currently `fr`, `de`, `es`) is missing any key present in `en.js`, and fails for *any* locale that has an orphaned key not in `en.js` (a sign of a typo or a stale key left behind after a rule was removed). Run `npm run i18n:report` any time to see per-locale coverage.
 
 ## Selecting a locale
 
@@ -17,7 +19,7 @@ Both locales are fully translated as of this writing. That won't stay automatica
 runDomRulesInPage(url, null, { locale: 'fr' }, null);
 ```
 
-Default is `'en'` if omitted. Any string is accepted — an unrecognized locale (e.g. `'de'`, not yet built) behaves exactly like a locale that's 0% translated: every string falls through to English (see below), not an error.
+Default is `'en'` if omitted. Any string is accepted — an unrecognized locale (e.g. `'ja'`, not yet built) behaves exactly like a locale that's 0% translated: every string falls through to English (see below), not an error.
 
 ## Fallback behavior (per-string, not per-locale)
 
@@ -40,8 +42,9 @@ Both are included in the result alongside the already-resolved text, so you can
 
 ## Contributing a translation
 
-1. Open `src/i18n/en.js` — it's the canonical key list (590 entries, one `module.exports` object of `key: string`).
-2. Add matching keys to `src/i18n/<locale>.js` (create the file if the locale doesn't exist yet — follow `fr.js`'s structure exactly: `'use strict'; module.exports = { ...keys };`).
-3. You don't need every key on day one — the fallback behavior above means a partial translation degrades gracefully to English per-string, exactly like `fr` does today. Ship what you have.
-4. Keep `{{placeholder}}` tokens in translated strings exactly as they appear in the English source — they're substituted verbatim regardless of locale (e.g. `{{element}}`, `{{role}}`).
-5. Run `npm run build && npm test` — there's no locale-completeness test today (a partial locale is valid, not a failure), but this confirms nothing else broke.
+1. Scaffold the file: `npm run i18n:new <locale>` (e.g. `npm run i18n:new de`) creates `src/i18n/<locale>.js` with all of `en.js`'s keys already present, each seeded with the English text as a placeholder. It refuses to overwrite an existing locale file unless you pass `--force`.
+2. Replace the placeholder values with real translations, key by key. Leave any you're unsure about as-is for now — a value identical to English is treated as untranslated, not broken (see the fallback behavior above).
+3. Check progress any time with `npm run i18n:report` — it prints, per locale, how many keys have been translated vs. still match the English placeholder, plus any missing or orphaned keys.
+4. You don't need every key on day one — the fallback behavior above means a partial translation degrades gracefully to English per-string, exactly like `fr`/`de`/`es` did during their own early stages. Ship what you have. A partial locale is valid and won't fail `i18n-locale-completeness.test.js` unless you also add it to `FULLY_TRANSLATED_LOCALES` in that file — only do that once `npm run i18n:report` shows 100% coverage.
+5. Keep `{{placeholder}}` tokens (and `{{#foo}}...{{/foo}}` conditional blocks) in translated strings exactly as they appear in the English source — they're substituted/evaluated verbatim regardless of locale (e.g. `{{element}}`, `{{role}}`). Never translate HTML tag/attribute names (`<img>`, `aria-label`, `role="dialog"`, etc.) — they're code identifiers, not prose.
+6. Run `npm run build && npm test` to confirm nothing broke, including locale-completeness.

package/docs/INTEGRATION.md

@@ -91,6 +91,24 @@ const result = await page.evaluate(wrapperFn, {
 
 This is the only pattern that gives every rule real computed layout, so it's the one to reach for if you need `target-size-minimum` or any other geometry-dependent check to actually run instead of reporting `notApplicable`.
 
+## Pattern 3 — a standalone `<script>` tag (no driver, no bundler)
+
+Good for: a manual check against a page open in a real browser, a bookmarklet, or any other context where there's no automation driver and no build step to reach for.
+
+`@surea11y/core` ships `surea11y.browser.js` at the package root, a bundle generated from the same rule sources as `src/core.js`. Loading it directly defines one global, `a11ycore`:
+
+```html
+<script src="node_modules/@surea11y/core/surea11y.browser.js"></script>
+<script>
+  const result = a11ycore.runa11yCoreInPage(location.href, null, {}, null);
+  console.log(result.checksResults.filter((r) => r.outcome === 'fail'));
+</script>
+```
+
+`a11ycore.runa11yCoreInPage` is the exact same function described in Pattern 2 above — the bundle exists only to solve *loading* it without `require`/a module system, not to add a separate API surface. It carries the same self-containment property (own inlined rule catalog, no free variables), which is what makes a plain `<script>` tag sufficient.
+
+Deliberately excluded from this bundle: `runa11yCoreAcrossFrames`/`a11yCoreEnableFrameResponder`. Cross-frame scanning needs the embedded frame to load the engine and opt in too (see "Cross-frame scanning" below) — not a fit for a single dropped-in script tag. Use the npm package directly if you need it.
+
 ## Scoping a scan to part of the page
 
 Pass a CSS selector as the 2nd argument (`contextSelector`) to scan one subtree instead of the whole document — e.g. `runDomRulesInPage(url, '#app', {}, null)` to skip a surrounding CMS chrome you don't control. Pass an array of selectors (or a single comma-separated selector string) to scan multiple, possibly disjoint regions in one run — e.g. `runDomRulesInPage(url, ['#header', '#main'], {}, null)`. See [`ENGINE_OPTIONS.md`](./ENGINE_OPTIONS.md) for the full `contextSelector` reference and for `excludeSelectors`, the complementary "skip specific elements anywhere" option.
@@ -112,7 +130,7 @@ if (failures.length > 0) {
 
 Notes for CI specifically:
 - `cantTell` outcomes are advisory by design (see [`OUTPUT_SCHEMA.md`](./OUTPUT_SCHEMA.md#outcome-values)) — most teams log them without failing the build, since they require human judgment the CI run can't make.
-- For "only fail on *new* violations," the CLI has a built-in baseline/allowlist mechanism (`--write-baseline`/`--baseline`, see [`BASELINE.md`](./BASELINE.md)). Calling the library directly, the same matching logic is available as `buildBaselineEntries(result)`/`matchBaseline(result, baselineEntries)` from `require('@surea11y/core/src/baseline')` — or diff `checksResults` against a saved prior run yourself if your pages don't fit that model (see `BASELINE.md`'s "known limitation").
+- For "only fail on *new* violations," the CLI has a built-in baseline/allowlist mechanism (`--write-baseline`/`--baseline`, see [`BASELINE.md`](./BASELINE.md)). Calling the library directly, the same matching logic is available as `buildBaselineEntries(result)`/`matchBaseline(result, baselineEntries)` from `require('@surea11y/core/baseline')` — or diff `checksResults` against a saved prior run yourself if your pages don't fit that model (see `BASELINE.md`'s "known limitation").
 - Prefer Pattern 1 (jsdom) in CI unless you specifically need real-browser layout — it avoids the extra weight of a Puppeteer/Playwright + browser-binary install in your pipeline.
 
 ## Browser extension context