@surea11y/core 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+All notable changes to this project are documented here, in [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format.
+
+## [Unreleased]
+
+### Changed
+- Trimmed the published npm package: rule-authoring scaffolding (`docs/RULE_TEMPLATE.*`, `docs/RULE_TEST_TEMPLATE.md`, `docs/RULE_TEST_AUTHORING.md`, `docs/TEST_OUTCOME_STABILITY.md`) and the not-yet-documented `src/explain` module no longer ship in the tarball — both stay in the git repo for contributors.
+- README rewritten for clarity: corrected the install command and `require()` examples to the actual package name (`@surea11y/core`), and updated the rule count to 125.
+
+## [1.1.1] - 2026-07-24
+
+### Added
+- 125 rules (77 automatic/`fail`-capable, 48 manual/advisory) — see `docs/RULE_CATALOG.md` for the full list.
+- Full i18n support (English complete, French partial — see `docs/I18N.md`).
+- A generated public rule catalog (`docs/RULE_CATALOG.md`, via `npm run docs:rule-catalog`) and WCAG facet-coverage report (`coverage/coverage-report.md`, via `npm run coverage`).
+- This documentation set: `README.md`, `docs/OUTPUT_SCHEMA.md`, `docs/ENGINE_OPTIONS.md`, `docs/WCAG_CONFORMANCE.md`, `docs/POLICY.md`, `docs/I18N.md`, `docs/INTEGRATION.md`, `docs/LIMITATIONS.md`, `docs/TROUBLESHOOTING.md`, `LICENSE`.
+- Multi-region `contextSelector` support: pass an array of selectors (or one comma-separated selector string) to scan multiple, possibly disjoint regions in a single run — equivalent to the multi-region include capability found in other engines. Overlapping/nested regions are deduped automatically. See `docs/ENGINE_OPTIONS.md`.
+- `includeShadowDom` now defaults to `true` (opt out with `includeShadowDom: false`).
+- `structuralPath` on every `fail`/`cantTell` occurrence: a sibling-index path from `documentElement` down to the flagged element, a more robust element-identity mechanism than `selector` alone (survives some DOM changes a selector wouldn't) — equivalent to the ancestry/xpath-addressing feature found in other engines. See `docs/OUTPUT_SCHEMA.md`.
+- `engineOptions.customRules`: register additional rules at runtime, scan-scoped (not added to the static catalog), matching the shape of an internal rule module (`{ id, meta, runInPage, applicability?, data? }`) — equivalent to the rule/check registration pattern used by other engines. `runInPage`/`applicability` accept a real function or a function-source string, the latter needed for cross-realm callers (e.g. Playwright) whose `engineOptions` argument can't carry a live function across a serialization boundary. See `docs/ENGINE_OPTIONS.md`.
+- `runa11yCoreAcrossFrames` / `a11yCoreEnableFrameResponder`: cross-frame (including genuinely cross-origin) scanning for the "plain script injection" consumption mode (no automation driver) — a cooperative `postMessage` protocol similar in spirit to the cross-frame messaging mechanisms used by other engines, including the same real limitation (a non-cooperating child frame is unreachable). Bundler-free, like `runa11yCoreInPage`. See `docs/INTEGRATION.md`'s "Cross-frame scanning" section and `docs/OUTPUT_SCHEMA.md`'s "Cross-frame result" section.
+- `runOnly.tags` filtering by WCAG version: every rule/composite now carries the version-correct `wcag2*`/`wcag21*`/`wcag22*` level tag for its Success Criterion (matching the tagging convention used by other engines — a 2.1/2.2-introduced SC is tagged only with its true origin version, never also the pre-existing baseline tag), so a caller can select a WCAG 2.0/2.1/2.2 conformance target by combining tag sets. See `docs/ENGINE_OPTIONS.md`'s "Filtering by WCAG version" section and `src/coverage/wcag-version-map.js` for the canonical per-version SC list.
+- `docs/BINDING_AUTHORS_GUIDE.md`: a reference for building a *new* framework binding (Puppeteer, Cypress, ...) on top of this engine — what's already engine-level vs. what every binding has to build itself, checked against what the `surea11y-playwright` sibling project actually needed.
+
+### Fixed (selected)
+- A shared `buildSelector` helper bug where an ancestor element that was the *last* of several same-tag siblings got no `:nth-of-type()` disambiguation, producing selectors that matched multiple elements instead of the one they were built for.
+- Several `ALLOWED_ROLES_BY_ELEMENT` entries (`<label>`, `<table>`/`<td>`/`<th>`/`<tr>`, `input[type=checkbox][role=button]`) that were missing or too restrictive, found via real-world-page testing and verified against the W3C ARIA-in-HTML spec.
+- `aria-hidden-focus` false-flagging the common `tabindex="-1"`-behind-`aria-hidden` pattern (checked raw focusability instead of tabbability).
+- A label-naming bug (`hasLabelAssociation` ignoring a `<label>`'s own `aria-label`), duplicated across 7 rule files, all fixed identically.
+- A systemic "name from content" false-positive affecting 19 rule files (an `<img alt>` or `aria-label`-named descendant inside a link/button wasn't recognized as providing the accessible name).
+- `contextSelector` resolving via `document.querySelector` (first match only) instead of `querySelectorAll` — a selector matching several elements silently scanned only the first, dropping the rest with no indication.
+- Three rules (`form-control-programmatic-label-present`, `target-size-minimum`, `label-in-name`) that queried `ctx.root` directly instead of through the shared `queryAllSmart`/`queryAll` helpers, found while implementing multi-region `contextSelector` support — silently broke (found nothing) the moment `ctx.root` became an array.
+- `aria-required-parent`/`aria-required-children`'s ancestor/descendant searches and `getContentNameInfo`'s "name from content" walk not following shadow-DOM `<slot>` assignment; a duplicated `resolveAriaLabelledbyText` pattern across 16 rules and `getLabelText` across 7 not checking an `aria-labelledby`/`<label>` target's `title` attribute as a final accname fallback (e.g. an `<iframe title="...">` target, whose content is always empty).
+- `landmark-one-main` incorrectly also flagged "more than one main landmark" — out of its real scope (the equivalent check in other engines is presence-only; duplicates are `landmark-no-duplicate-main`'s job, already implemented correctly) and missing the accessibility-tree visibility filter its sibling rule already has.
+- `aria-required-children`, `aria-prohibited-children`, `aria-required-parent`, and `aria-required-attr` flagged containers/elements that were not currently exposed to the accessibility tree at all (`hidden`, a closed `<dialog>`, etc.) — e.g. a closed flyout `role="menu"` populated on open, or a custom `role="checkbox"` whose `aria-checked` is set on hydration. All four now skip elements that fail `isAccTreeEligible`; `aria-required-children`/`aria-required-attr` also honor `aria-busy="true"` as an explicit author signal of transient incompleteness (WAI-ARIA's own escape hatch for required owned elements, extended by analogy to required attributes).
+- `getAccessibleLandmarkName`, duplicated across 7 landmark rule files, never checked an element's `title` attribute as a naming source (only `aria-label`/`aria-labelledby`) — confirmed against another engine's real scan that `title` is a valid landmark-naming fallback. Replaced all 7 copies with one shared helper, `helpers.getLandmarkNameInfo`.
+
+### Known limitations
+See `docs/LIMITATIONS.md` — structural (keyboard-trap detection, reflow-at-zoom), environment-dependent (jsdom vs. real-browser geometry), and deliberately-not-automated (text-quality judgment calls) limitations, stated explicitly rather than left to be discovered.
+
+---
+
+## How to add an entry
+
+When you ship a change worth calling out to consumers (not every commit):
+1. Add a bullet under `[Unreleased]`, in the right subsection (`Added`, `Changed`, `Fixed`, `Deprecated`, `Removed`, `Security`) — create the subsection if it doesn't exist yet for this cycle.
+2. Write it from the consumer's perspective ("what changed for someone using this package"), not the implementation's.
+3. When you tag a release, rename `[Unreleased]` to `## [x.y.z] - YYYY-MM-DD` and start a fresh empty `[Unreleased]` above it.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jorge Rumoroso
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,145 @@
+# surea11y
+
+**surea11y runs automated accessibility tests against a real DOM** — 125 rules, standards-traceable, safe by default. Point it at a static HTML file or a URL, or run it inside a real rendered page — via Puppeteer, Playwright, Selenium, Cypress, or any other browser-automation driver — and it tells you exactly what fails a WCAG Success Criterion, where, and why — no browser extension, no dashboard sign-up, just a function call or a CLI command.
+
+What makes it trustworthy enough to gate a build on:
+
+- **No false alarms by design.** `fail` is reserved for deterministic, high-confidence, normative violations — never a heuristic guess. Where certainty isn't possible, the result says so (`cantTell`) instead of forcing a guess into a `pass`/`fail`.
+- **Deterministic, every time.** Same input, same result — no built-in clock, no randomness, nothing that can make a CI run flaky.
+- **Every rule is atomic and traceable.** One normative decision per rule, mapped to a WCAG Success Criterion where one applies, with a machine-readable rule ID and a human-readable hint for fixing it.
+- **Zero runtime dependencies in the library itself** (see [`SECURITY.md`](./SECURITY.md)) — the CLI is the only part that pulls in `jsdom`, and only if you use it.
+- **Runs anywhere your DOM does — jsdom or a real browser, each with real tradeoffs.** See "Static HTML vs. a live browser" below before picking one.
+- **Fully localized output** (English, French, more on the way) without sacrificing stable, locale-independent rule IDs and machine-readable keys.
+- **Extensible.** Register custom rules at scan time, filter by rule ID/tag/WCAG version, or scan several regions of a page in a single pass.
+
+## Static HTML vs. a live browser
+
+This is the decision that determines what content the engine can actually see — pick wrong and you'll get clean results on a page that isn't really accessible.
+
+- **CLI (`scan ./file.html` / `scan <url>`) and jsdom (`runDomRulesInPage`) — no JavaScript execution, no real CSS layout engine.** These parse markup as text/fetch it as-is; a URL scan sees exactly what the server sent, not what the page looks like after client JS runs. Fine for static or server-rendered HTML. Blind to anything a client-side framework adds after load — SPA content, hydration-driven attribute changes, modals/dropdowns that only exist post-interaction. Layout-dependent rules (`target-size-minimum`, most notably) report `notApplicable` rather than guess, since jsdom has no real `getBoundingClientRect()`.
+- **A real browser (`runa11yCoreInPage`, run inside a live page — Puppeteer/Playwright's `page.evaluate`, Selenium's `execute_script`, Cypress's in-browser test code, a browser extension, or any other driver that can run code in the page) — sees the fully rendered, post-JS, post-hydration DOM and real computed layout.** Required for client-rendered apps, and for accurate results on layout-dependent rules.
+
+Full detail on both: [`docs/LIMITATIONS.md`](./docs/LIMITATIONS.md) (everything each mode structurally can't see) and [`docs/INTEGRATION.md`](./docs/INTEGRATION.md) (the two patterns, in depth, with working code).
+
+## Install
+
+```sh
+npm install @surea11y/core
+```
+
+## Quickstart
+
+### CLI — fastest way to just try it
+
+```sh
+npx @surea11y/core scan ./index.html
+npx @surea11y/core scan https://example.com/
+```
+
+Static HTML only (no page JavaScript execution) — see [`docs/CLI.md`](./docs/CLI.md) for every flag, exit codes, and when you need the library instead (client-rendered content, real-browser geometry).
+
+### Library — for your own scripts, test suites, or browser-automation code
+
+Two runner functions, depending on where you run it (see [`docs/INTEGRATION.md`](./docs/INTEGRATION.md) for the full explanation of the difference and more patterns):
+
+```js
+// Node + jsdom (no real browser needed)
+const { JSDOM } = require('jsdom');
+const { runDomRulesInPage } = require('@surea11y/core');
+
+const dom = new JSDOM('<img src="logo.png">', { url: 'https://example.com/', pretendToBeVisual: true });
+global.window = dom.window;
+global.document = dom.window.document;
+
+const result = runDomRulesInPage('https://example.com/', null, {}, null);
+console.log(result.checksResults.filter((r) => r.outcome === 'fail'));
+// -> [{ ruleId: 'img-alt-present', outcome: 'fail', occurrences: [...] }]
+```
+
+```js
+// Puppeteer / Playwright, against a real rendered page
+const { runa11yCoreInPage } = require('@surea11y/core');
+
+const result = await page.evaluate(runa11yCoreInPage, 'https://example.com/', null, {}, null);
+```
+
+`runa11yCoreInPage` is fully self-contained (see [`docs/INTEGRATION.md`](./docs/INTEGRATION.md)), so it isn't Puppeteer/Playwright-specific — the same function works with Selenium's `execute_script`, runs natively in Cypress's in-browser test code, or in a browser extension content script. Puppeteer/Playwright are just the two shown here.
+
+## What you get back
+
+```json
+{
+  "engine": { "tag": "a11ycore", "schemaVersion": "1.0.0" },
+  "url": "https://example.com/",
+  "checksResults": [
+    {
+      "ruleId": "img-alt-present",
+      "outcome": "fail",
+      "severity": "serious",
+      "confidence": "high",
+      "occurrences": [
+        { "selector": "html > body > img", "html": "<img src=\"logo.png\">", "summary": "Missing alt attribute on <img>.", "hint": "Add an alt attribute (use alt=\"\" only for decorative images)." }
+      ]
+    }
+  ],
+  "rulesResults": []
+}
+```
+
+Full field-by-field reference (what every field means, what `cantTell` vs `notApplicable` means, how composite WCAG-SC rollups work): [`docs/OUTPUT_SCHEMA.md`](./docs/OUTPUT_SCHEMA.md).
+
+## Documentation
+
+| Doc | What's in it |
+|---|---|
+| [`docs/OUTPUT_SCHEMA.md`](./docs/OUTPUT_SCHEMA.md) | The full result shape — every field, every outcome value, worked examples. Start here. |
+| [`docs/CLI.md`](./docs/CLI.md) | The `surea11y scan` command — flags, exit codes, what it can and can't scan. |
+| [`docs/ENGINE_OPTIONS.md`](./docs/ENGINE_OPTIONS.md) | Every `engineOptions`/`runOnly` field: selecting rules, locale, shadow DOM, contrast mode, policy, and the common `runOnly` gotcha. |
+| [`docs/INTEGRATION.md`](./docs/INTEGRATION.md) | Node/jsdom vs. real-browser (Puppeteer, Playwright, Selenium, Cypress, or any driver) usage, CI gating, browser-extension context. |
+| [`docs/BINDING_AUTHORS_GUIDE.md`](./docs/BINDING_AUTHORS_GUIDE.md) | Building a *new* framework binding (Puppeteer, Cypress, ...)? What the engine gives you for free vs. what every binding has to build itself, checked against what `surea11y-playwright` actually needed. |
+| [`docs/RULE_CATALOG.md`](./docs/RULE_CATALOG.md) | All 125 rules — id, WCAG SC, level, confidence, severity. Generated; run `npm run docs:rule-catalog` to refresh. |
+| [`docs/WCAG_CONFORMANCE.md`](./docs/WCAG_CONFORMANCE.md) | How rule outcomes roll up to an SC-level / A-AA-AAA conformance picture, and what that picture does and doesn't claim. |
+| [`docs/POLICY.md`](./docs/POLICY.md) | The `a11y`/`generic` policy contracts — what they control and how to customize. |
+| [`docs/I18N.md`](./docs/I18N.md) | Current locale coverage and how to contribute a translation. |
+| [`docs/LIMITATIONS.md`](./docs/LIMITATIONS.md) | What this engine cannot do, and why — stated upfront. |
+| [`docs/TROUBLESHOOTING.md`](./docs/TROUBLESHOOTING.md) | Common gotchas, FAQ. |
+| [`docs/RULE_AUTHORING.md`](./docs/RULE_AUTHORING.md) | How to write a new rule — the exact module contract, a critical footgun to avoid, fixture requirements. |
+| [`docs/RULE_TAXONOMY.md`](./docs/RULE_TAXONOMY.md) | How rules are categorized. |
+| [`CONTRIBUTING.md`](./CONTRIBUTING.md) | How to add/change a rule, commit conventions, required checks before a PR. |
+| [`SECURITY.md`](./SECURITY.md) | Scope, threat model, how to report a vulnerability. |
+| [`CHANGELOG.md`](./CHANGELOG.md) | What changed, release to release. |
+
+## Folder layout
+
+```
+bin/
+  core.js       # CLI entry point (`npx @surea11y/core scan ...`) — see docs/CLI.md
+src/
+  index.js          # public entry point (re-exports src/core.js)
+  core.js            # GENERATED — do not edit directly, see "Build" below
+  checks/
+    automatic/        # type: 'automatic' rules — can return `fail`
+    manual/            # type: 'manual' rules — advisory, capped at `cantTell`
+  core/               # shared runtime: dom-runner, dom-helpers, aria-helpers, contrast-helpers
+  policy/             # policy contracts (a11y / generic)
+  i18n/               # locale dictionaries (en.js, fr.js)
+  coverage/           # WCAG facet definitions
+  catalogs/           # composite (WCAG-SC rollup) rule definitions
+scripts/
+  build-core.js       # bundles src/checks/**, src/core/**, src/i18n/** into src/core.js
+docs/                 # everything in the table above
+tests/
+  fixtures/            # one *-all-scenarios.html scenario page per rule
+  engine-checks/        # per-rule unit + fixture-coverage tests
+```
+
+## Build & test
+
+```sh
+npm run build   # regenerate src/core.js from source
+npm test        # build + run the full test suite
+```
+
+## License
+
+[MIT](./LICENSE)

package/bin/core.js

@@ -0,0 +1,244 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * surea11y CLI — a thin wrapper around the library for ad hoc/CI use.
+ *
+ * This is the one part of the package that depends on jsdom (see
+ * package.json's "dependencies" vs the library itself, which has none --
+ * `require('surea11y')` never loads jsdom; only running this CLI does).
+ * Static-HTML only: it does not execute page JavaScript, so client-rendered
+ * content won't be scanned. For that, use a real browser via Puppeteer/
+ * Playwright — see docs/INTEGRATION.md Pattern 2.
+ *
+ * Usage:
+ *   surea11y scan <file-or-url> [options]
+ *
+ * See docs/CLI.md for the full option reference.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const pkg = require('../package.json');
+
+// Piping output to `head`/`less`/etc. closes stdout early — without this,
+// the next write throws an unhandled EPIPE and crashes with a raw stack
+// trace instead of just stopping quietly, like well-behaved CLI tools do.
+process.stdout.on('error', (err) => {
+  if (err && err.code === 'EPIPE') process.exit(0);
+  throw err;
+});
+
+function printHelp() {
+  process.stdout.write(`surea11y v${pkg.version}
+
+Usage:
+  surea11y scan <file-or-url> [options]
+
+Options:
+  --json                  Print the raw result object as JSON instead of a summary
+  --locale <locale>       Locale for output text (default: en)
+  --rules <ids>           Comma-separated rule IDs to run (only these)
+  --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
+  -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
+  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
+`);
+}
+
+function parseArgs(argv) {
+  const out = { _: [], json: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    switch (a) {
+      case '--json':
+        out.json = true;
+        break;
+      case '--locale':
+        out.locale = argv[++i];
+        break;
+      case '--rules':
+        out.rules = argv[++i];
+        break;
+      case '--exclude-rules':
+        out.excludeRules = argv[++i];
+        break;
+      case '--tags':
+        out.tags = argv[++i];
+        break;
+      case '--context':
+        out.context = argv[++i];
+        break;
+      case '-h':
+      case '--help':
+        out.help = true;
+        break;
+      case '-v':
+      case '--version':
+        out.version = true;
+        break;
+      default:
+        out._.push(a);
+    }
+  }
+  return out;
+}
+
+function isUrl(s) {
+  return /^https?:\/\//i.test(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) : '');
+  return cause ? `${base}: ${cause}` : base;
+}
+
+async function loadHtml(target) {
+  if (isUrl(target)) {
+    const res = await fetch(target);
+    if (!res.ok) {
+      throw new Error(`Fetching ${target} failed: HTTP ${res.status} ${res.statusText}`);
+    }
+    return { html: await res.text(), url: target };
+  }
+
+  const resolved = path.resolve(process.cwd(), target);
+  if (!fs.existsSync(resolved)) {
+    throw new Error(`No such file: ${resolved}`);
+  }
+  return { html: fs.readFileSync(resolved, 'utf8'), url: `file://${resolved}` };
+}
+
+function buildEngineOptions(args) {
+  const engineOptions = {};
+  if (args.locale) engineOptions.locale = args.locale;
+  if (args.rules || args.excludeRules) {
+    engineOptions.rules = {};
+    if (args.rules) engineOptions.rules.include = args.rules;
+    if (args.excludeRules) engineOptions.rules.exclude = args.excludeRules;
+  }
+  if (args.tags) engineOptions.tags = { include: args.tags };
+  return engineOptions;
+}
+
+function printSummary(result) {
+  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`);
+
+  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`);
+      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`);
+      }
+      if (r.occurrences.length > 5) {
+        process.stdout.write(`    ... and ${r.occurrences.length - 5} more\n`);
+      }
+    }
+    process.stdout.write('\n');
+  }
+
+  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`);
+  }
+}
+
+async function runScan(args) {
+  const target = args._[0];
+  if (!target) {
+    process.stderr.write('Error: scan requires a file path or URL. See --help.\n');
+    process.exitCode = 2;
+    return;
+  }
+
+  let html, url;
+  try {
+    ({ html, url } = await loadHtml(target));
+  } catch (err) {
+    process.stderr.write(`Error: ${formatError(err)}\n`);
+    process.exitCode = 2;
+    return;
+  }
+
+  let JSDOM;
+  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.exitCode = 2;
+    return;
+  }
+
+  const { runDomRulesInPage } = require('../src/index.js');
+
+  const dom = new JSDOM(html, { url, pretendToBeVisual: true });
+  global.window = dom.window;
+  global.document = dom.window.document;
+
+  let result;
+  try {
+    result = runDomRulesInPage(url, args.context || null, buildEngineOptions(args), null);
+  } finally {
+    dom.window.close();
+  }
+
+  if (args.json) {
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+  } else {
+    printSummary(result);
+  }
+
+  const hasFail = result.checksResults.some((r) => r.outcome === 'fail');
+  process.exitCode = hasFail ? 1 : 0;
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (args.version) {
+    process.stdout.write(`${pkg.version}\n`);
+    return;
+  }
+  if (args.help || args._.length === 0) {
+    printHelp();
+    process.exitCode = args._.length === 0 && !args.help ? 2 : 0;
+    return;
+  }
+
+  const [command, ...rest] = args._;
+  if (command !== 'scan') {
+    process.stderr.write(`Error: unknown command "${command}". Only "scan" is supported. See --help.\n`);
+    process.exitCode = 2;
+    return;
+  }
+
+  args._ = rest;
+  await runScan(args);
+}
+
+main().catch((err) => {
+  process.stderr.write(`Error: ${formatError(err)}\n`);
+  process.exitCode = 2;
+});

package/docs/BINDING_AUTHORS_GUIDE.md

@@ -0,0 +1,41 @@
+# 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.
+
+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
+
+Some engine-parity features (relative to other established engines) are **engine-level** — call the engine, get the behavior, no binding code required. Others are **binding-layer** — the engine deliberately doesn't own them, because they only make sense once you have a real automation driver (a `Page`/`Browser`/`ElementHandle`-shaped object) in front of you. Building a new binding without knowing which is which leads to either reimplementing something the engine already does, or missing something because "surely the engine handles that."
+
+**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.
+- `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.
+
+**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).
+- **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:
+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).
+
+If your binding runs in the *same* realm as the page (a browser extension content script, or Cypress-style in-browser test code), this whole section doesn't apply to you — pass live functions freely.
+
+## 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:
+- [ ] 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.
+- [ ] TypeScript types (if you ship any) stay in sync with actual engine output — `structuralPath: number[] | null` and any new fields ([`OUTPUT_SCHEMA.md`](./OUTPUT_SCHEMA.md) is the source of truth) are easy to leave stale after an engine update.
+
+## 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.

package/docs/CLI.md

@@ -0,0 +1,49 @@
+# CLI
+
+`surea11y` ships a small CLI (`bin/core.js`) for ad hoc scans and CI, on top of the library API described in [`INTEGRATION.md`](./INTEGRATION.md).
+
+```sh
+npx @surea11y/core scan ./index.html
+npx @surea11y/core scan https://example.com/
+```
+
+## What it can and can't scan
+
+The CLI reads **static HTML only** — a local file, or the raw response of an HTTP(S) GET request — and never executes page JavaScript. That means client-rendered content (anything your framework injects after page load) won't be captured, and geometry-dependent rules like `target-size-minimum` will report `notApplicable` (no real CSS layout — see [`LIMITATIONS.md`](./LIMITATIONS.md)). If you need either of those, drive a real browser yourself and use `runa11yCoreInPage` directly — see [`INTEGRATION.md`](./INTEGRATION.md) Pattern 2. The CLI is the fast path for static/server-rendered pages and CI; the library is what you reach for beyond that.
+
+## Options
+
+| Flag | Meaning |
+|---|---|
+| `--json` | Print the raw result object (see [`OUTPUT_SCHEMA.md`](./OUTPUT_SCHEMA.md)) instead of a human-readable summary. |
+| `--locale <locale>` | Output text locale (default `en`) — see [`I18N.md`](./I18N.md). |
+| `--rules <ids>` | Comma-separated rule IDs — only run these. |
+| `--exclude-rules <ids>` | Comma-separated rule IDs — never run these. |
+| `--tags <tags>` | Comma-separated tags — e.g. `--tags wcag2a,wcag2aa` to target a conformance level (see [`WCAG_CONFORMANCE.md`](./WCAG_CONFORMANCE.md)). |
+| `--context <selector>` | Scope the scan to one CSS-selected subtree. |
+| `-h`, `--help` | Show usage. |
+| `-v`, `--version` | Show the installed version. |
+
+These map directly onto `engineOptions`/`runOnly` (see [`ENGINE_OPTIONS.md`](./ENGINE_OPTIONS.md)) — `--rules`/`--exclude-rules` become `engineOptions.rules.include`/`.exclude`, `--tags` becomes `engineOptions.tags.include`.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| `0` | Scan completed, no `fail` outcomes. |
+| `1` | Scan completed, at least one `fail` outcome — the CI-gating case. |
+| `2` | Usage error, or the scan itself couldn't run (bad path/URL, network failure, missing `jsdom`). |
+
+`cantTell` outcomes never affect the exit code — they're printed as a "needs human review" summary, consistent with the manual/`cantTell` mental model in [`TROUBLESHOOTING.md`](./TROUBLESHOOTING.md#should-i-treat-canttell-as-a-failure). If you need `cantTell`-aware gating, use `--json` and inspect `checksResults` yourself, or call the library directly (see [`INTEGRATION.md`](./INTEGRATION.md#ci-gating-a-build-on-the-result)).
+
+## In CI
+
+```sh
+npx @surea11y/core scan ./dist/index.html || exit 1
+```
+
+Or, since the exit code already reflects pass/fail, just let the command's own exit code propagate — most CI systems fail the step automatically on a non-zero exit.
+
+## A note on dependencies
+
+The CLI is the one part of this package that depends on `jsdom` — `require('@surea11y/core')` as a library never loads it (see [`SECURITY.md`](../SECURITY.md)). If you only ever use the library API directly against your own DOM (jsdom, a real browser, whatever you already have), you're not paying for `jsdom` a second time.