@surea11y/core 1.0.0 → 1.0.1

package/CHANGELOG.md

@@ -4,9 +4,26 @@ All notable changes to this project are documented here, in [Keep a Changelog](h
 
 ## [Unreleased]
 
+### Added
+- Completed French (`fr`) localization: translated the 313 remaining `src/i18n/fr.js` keys, bringing French to full parity with English (600/600 keys, up from 287/600). Verified against a live scan (`locale: 'fr'`) and confirmed no key/placeholder mismatches against `src/i18n/en.js`. Landmark terminology uses "point de repère" per MDN's French ARIA documentation.
+
+### Fixed
+- `docs/RULE_TAXONOMY.md`: automatic rules' allowed outcomes was missing `cantTell` (4 rules use it as a defensive fallback); the "current intents"/"current families" lists were stale and read as exhaustive when the ruleset actually spans 54 suffixes/68 prefixes — reframed as illustrative with a pointer to the generated `RULE_CATALOG.md`; `data.visibilityFilter.targetSet` was missing the `'dom'` value (only `'acc'` was listed).
+- `docs/OUTPUT_SCHEMA.md`: the `visibilityFilter` type was missing its always-present `eligible` field; the worked example's `structuralPath` values for the button/img pair were swapped; removed a citation to a note in `RULE_AUTHORING.md` that doesn't exist there.
+- `docs/I18N.md`: stale key counts (`en` listed as 590, actual 600; `fr` coverage listed as ~49%, actual ~48% at the time) — now updated to reflect full parity.
+
+## [1.0.1] - 2026-07-28
+
 ### 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.
+- `docs/ENGINE_OPTIONS.md`: documented the previously-undocumented `visibilityMode` option (`'styleOnly'`/`'styleAndGeometry'`, scoped to the three contrast rules), and added a "Recipes" section with composed, runnable examples for common scenarios (CI gating, auditor-mode contrast passes, scoped re-scans, reproducible snapshots, custom rules).
+
+### Fixed
+- `aria-allowed-attr`'s `SUPPORTED_ATTRS_BY_ROLE` table reconciled against the published WAI-ARIA 1.2 Recommendation (via `aria-query`, not axe-core's table — axe-core's own source comments confirm many of its `aria-expanded` allowances are deliberate ARIA 1.1 legacy carryovers, not current-spec facts). Added `aria-expanded` to 10 roles (checkbox, columnheader, gridcell, listbox, menuitemcheckbox, menuitemradio, row, rowheader, switch, tab) and `aria-activedescendant` to 8 composite-widget roles (combobox, grid, listbox, radiogroup, row, spinbutton, tablist, treegrid), plus smaller posinset/setsize/readonly/required/level gaps; removed `tree`'s unverified `aria-readonly`. `listitem` was already correct and is unchanged.
+- README: a "Real browser execution" code sample passed four positional arguments to `page.evaluate()` and claimed it worked with "any" automation framework — Playwright's `page.evaluate()` only accepts one argument alongside the function and throws on this exact pattern. Now shown as Puppeteer-specific, with a pointer to `INTEGRATION.md`'s wrapper for Playwright.
+- README: the JSON output example referenced a nonexistent rule id (`link-name-quality`); corrected to the real id, `link-name-quality-manual`.
+- README: Quick Start code samples labeled the runner's four positional arguments as `url, ruleFilter, options, policy`; corrected to the actual names (`pageUrl, contextSelector, engineOptions, runOnly`) used consistently elsewhere in the docs.
 
 ## [1.1.1] - 2026-07-24
 

package/README.md

@@ -1,75 +1,216 @@
-# surea11y
+# @surea11y/core
 
-**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.
+> **Reliable accessibility testing for real web applications.**
 
-What makes it trustworthy enough to gate a build on:
+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.
 
-- **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.
+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.
 
-## Static HTML vs. a live browser
+## Why surea11y?
 
-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.
+Accessibility automation is only valuable if developers can trust its
+results.
 
-- **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.
+surea11y is built around a conservative philosophy: **never report
+certainty when certainty cannot be established objectively.**
 
-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).
+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.
 
-## Install
+This makes the engine predictable, reproducible and suitable for
+automated quality gates.
 
-```sh
+### Key principles
+
+- **Deterministic execution.** The same input always produces the same
+  output.
+- **Conservative by design.** `fail` is reserved for objective,
+  normative violations, minimizing false alarms.
+- **Standards traceability.** Rules map to the applicable WCAG Success
+  Criterion whenever appropriate.
+- **Stable machine-readable output.** Rule identifiers remain stable
+  regardless of language.
+- **Framework independent.** Run inside jsdom or any browser
+  automation framework.
+- **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.
+
+---
+
+## Choosing the right execution model
+
+surea11y supports two complementary execution models. Choosing the
+correct one is essential because it determines which parts of the page
+the engine can inspect.
+
+### Static HTML
+
+The CLI (`scan file.html` or `scan https://example.com`) and
+`runDomRulesInPage()` analyse HTML without executing page JavaScript.
+
+This approach is ideal for:
+
+- static websites;
+- server-side rendered applications;
+- generated documentation;
+- pre-rendered HTML.
+
+Because JavaScript is never executed, the engine cannot inspect content
+added after page load. Likewise, rules requiring real layout information
+cannot be evaluated and will report `notApplicable` instead of making
+assumptions.
+
+### Fully rendered browser
+
+`runa11yCoreInPage()` executes directly inside a live browser page.
+
+This allows the engine to inspect:
+
+- client-rendered applications;
+- hydrated pages;
+- computed styles;
+- runtime DOM changes;
+- layout-dependent rules.
+
+The function is browser-agnostic and can be executed through Puppeteer,
+Playwright, Selenium, Cypress or any environment capable of evaluating
+JavaScript inside the page.
+
+For a detailed comparison of both execution models, see
+`docs/LIMITATIONS.md` and `docs/INTEGRATION.md`.
+
+---
+
+## Installation
+
+Install the core package from npm:
+
+```bash
 npm install @surea11y/core
 ```
 
-## Quickstart
+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.
+
+---
 
-### CLI — fastest way to just try it
+## Quick Start
 
-```sh
+### CLI
+
+The CLI is the fastest way to analyse a page without writing any code.
+
+```bash
 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).
+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`.
+
+---
+
+### Library
 
-### Library — for your own scripts, test suites, or browser-automation code
+surea11y exposes two entry points depending on where your code executes.
 
-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):
+#### Node.js + jsdom
+
+Use `runDomRulesInPage()` when your application already has a DOM
+available through jsdom.
 
 ```js
-// Node + jsdom (no real browser needed)
-const { JSDOM } = require('jsdom');
-const { runDomRulesInPage } = require('@surea11y/core');
+const { JSDOM } = require("jsdom");
+const { runDomRulesInPage } = require("@surea11y/core");
+
+const dom = new JSDOM('<img src="logo.png">', {
+  url: "https://example.com/",
+  pretendToBeVisual: true
+});
 
-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: [...] }]
+const result = runDomRulesInPage(
+  "https://example.com/", // pageUrl
+  null,                   // contextSelector
+  {},                     // engineOptions
+  null                    // runOnly
+);
+
+console.log(
+  result.checksResults.filter(r => r.outcome === "fail")
+);
 ```
 
-```js
-// Puppeteer / Playwright, against a real rendered page
-const { runa11yCoreInPage } = require('@surea11y/core');
+This approach is fast, simple and requires no browser installation. It
+is best suited for static HTML and server-rendered pages.
+
+---
 
-const result = await page.evaluate(runa11yCoreInPage, 'https://example.com/', null, {}, null);
+#### Real browser execution
+
+For client-rendered applications, execute the engine inside the page
+itself.
+
+```js
+// Puppeteer
+const { runa11yCoreInPage } = require("@surea11y/core");
+
+const result = await page.evaluate(
+  runa11yCoreInPage,
+  "https://example.com/", // pageUrl
+  null,                   // contextSelector
+  {},                     // engineOptions
+  null                    // runOnly
+);
 ```
 
-`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.
+`runa11yCoreInPage` is self-contained (its whole rule catalog is
+inlined), so it works unmodified with any framework capable of
+evaluating a function inside the page — Puppeteer, Selenium, Cypress,
+browser extensions and custom drivers can all call it exactly as
+shown above. **Playwright is the one exception**: its `page.evaluate()`
+only accepts a single argument alongside the function, so
+`runa11yCoreInPage` needs a one-argument wrapper instead of four
+positional arguments — see `docs/INTEGRATION.md` for the exact pattern.
+
+This allows the engine to inspect the fully rendered DOM exactly as
+users experience it.
+
+For complete integration examples, see `docs/INTEGRATION.md`.
 
-## What you get back
+---
+
+## Understanding the Results
+
+Every scan returns a structured JSON document designed for both
+developers and automated tooling.
+
+A simplified example looks like this:
 
 ```json
 {
-  "engine": { "tag": "a11ycore", "schemaVersion": "1.0.0" },
+  "engine": {
+    "tag": "a11ycore",
+    "schemaVersion": "1.0.0"
+  },
   "url": "https://example.com/",
   "checksResults": [
     {
@@ -78,68 +219,228 @@ const result = await page.evaluate(runa11yCoreInPage, 'https://example.com/', nu
       "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)." }
+        {
+          "selector": "html > body > img",
+          "summary": "Missing alt attribute on <img>.",
+          "hint": "Add an alt attribute or use alt=\"\" for decorative images."
+        }
+      ]
+    },
+    {
+      "ruleId": "link-name-quality-manual",
+      "outcome": "cantTell",
+      "severity": "minor",
+      "confidence": "medium",
+      "occurrences": [
+        {
+          "selector": "html > body > a:nth-child(3)",
+          "summary": "Link text may not be descriptive enough out of context.",
+          "hint": "Confirm the link text clearly describes its destination or purpose."
+        }
       ]
     }
-  ],
-  "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).
+The second result illustrates the engine's conservative stance: it can
+confirm a link has text, but whether that text is genuinely descriptive
+requires human judgement, so it reports `cantTell` instead of guessing.
+
+Each finding contains enough information to answer four questions:
+
+- **What failed?** (`ruleId`)
+- **Why did it fail?** (`summary`)
+- **Where did it fail?** (`selector` and occurrences)
+- **How can it be fixed?** (`hint`)
+
+The complete schema also includes confidence, severity, WCAG
+traceability, composite rule results and other metadata intended for
+reporting and automation.
+
+For a complete field-by-field reference, see `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
+The project documentation is organized by topic so you can start quickly
+and progressively explore more advanced features.
 
-```
+| Document | Description |
+|---|---|
+| `docs/OUTPUT_SCHEMA.md` | Complete description of every field returned by the engine. |
+| `docs/CLI.md` | CLI commands, options, exit codes and examples. |
+| `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. |
+| `docs/RULE_CATALOG.md` | Reference of every built-in accessibility rule. |
+| `docs/WCAG_CONFORMANCE.md` | Understanding WCAG rollups and conformance reporting. |
+| `docs/POLICY.md` | Built-in policy contracts and customization. |
+| `docs/I18N.md` | Translation support and localization. |
+| `docs/LIMITATIONS.md` | Structural limitations of automated accessibility testing. |
+| `docs/TROUBLESHOOTING.md` | Frequently asked questions and common issues. |
+| `docs/RULE_AUTHORING.md` | Writing custom accessibility rules. |
+| `docs/RULE_TAXONOMY.md` | Rule categorization model. |
+| `CONTRIBUTING.md` | Contributing guidelines. |
+| `SECURITY.md` | Security policy and vulnerability reporting. |
+| `CHANGELOG.md` | Release history. |
+
+---
+
+## Philosophy
+
+surea11y is built on a simple principle:
+
+> Automate what can be determined objectively. Never pretend to automate
+> what cannot.
+
+Accessibility is not something that can be reduced to a single score or
+a binary pass/fail result. Some WCAG requirements can be evaluated with
+complete confidence, while others require human judgement, knowledge of
+context or usability evaluation.
+
+Rather than hiding that distinction, surea11y makes it explicit.
+
+That philosophy influences every rule in the engine and is the reason
+outcomes such as `cantTell` and `notApplicable` exist. They communicate
+uncertainty honestly instead of encouraging misleading conclusions.
+
+### What surea11y won't catch
+
+Being explicit about the boundaries of automation is part of the same
+philosophy. For example, surea11y will not:
+
+- confirm that alt text is *meaningful*, only that it is present
+  (an alt attribute of `"image123.png"` passes the objective check);
+- judge whether a color contrast choice is aesthetically appropriate,
+  only whether it meets the applicable contrast ratio;
+- determine whether an error message actually *explains* the problem,
+  since that depends on validation logic a static scan can't see;
+- detect a keyboard focus trap or content clipped at 400% zoom, since
+  both require simulating real user interaction over time, not just
+  reading the DOM at one instant.
+
+These are the cases where the engine reports `cantTell`, and where a
+human reviewer's judgement remains necessary. See
+`docs/LIMITATIONS.md` for the complete list of structural limitations.
+
+The objective of the project is not to replace accessibility experts. It
+is to remove repetitive verification work, provide reliable automated
+feedback to developers and help teams integrate accessibility into their
+normal development process.
+
+---
+
+## Project Structure
+
+The repository is organised so that the accessibility engine, rule
+implementations and supporting infrastructure remain clearly separated.
+
+```text
 bin/
-  core.js       # CLI entry point (`npx @surea11y/core scan ...`) — see docs/CLI.md
+  core.js                  # CLI entry point
+
 src/
-  index.js          # public entry point (re-exports src/core.js)
-  core.js            # GENERATED — do not edit directly, see "Build" below
+  index.js                 # Public API
+  core.js                  # Generated runtime bundle
+
   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
+    automatic/             # Deterministic automated rules
+    manual/                # Advisory rules (maximum outcome: cantTell)
+
+  core/                    # Shared engine runtime
+  policy/                  # Policy implementations
+  i18n/                    # Localized messages
+  coverage/                # WCAG coverage definitions
+  catalogs/                # Composite rule catalogs
+
 scripts/
-  build-core.js       # bundles src/checks/**, src/core/**, src/i18n/** into src/core.js
-docs/                 # everything in the table above
+  build-core.js            # Generates the runtime bundle
+
+docs/                      # Project documentation
+
 tests/
-  fixtures/            # one *-all-scenarios.html scenario page per rule
-  engine-checks/        # per-rule unit + fixture-coverage tests
+  fixtures/                # Rule fixtures
+  engine-checks/           # Engine and rule tests
+```
+
+This separation allows the engine to evolve independently from framework
+integrations while keeping the rule authoring experience consistent.
+
+---
+
+## Building the Project
+
+After cloning the repository, regenerate the bundled runtime:
+
+```bash
+npm run build
 ```
 
-## Build & test
+To execute the complete test suite:
 
-```sh
-npm run build   # regenerate src/core.js from source
-npm test        # build + run the full test suite
+```bash
+npm test
 ```
 
+The test suite validates rule behaviour, fixture coverage and overall
+engine consistency to ensure deterministic results across releases.
+
+---
+
+## Contributing
+
+Contributions are welcome.
+
+Whether you are fixing a bug, improving documentation or implementing a
+new accessibility rule, please keep the project's core principles in
+mind:
+
+- deterministic behaviour;
+- objective rule evaluation;
+- conservative outcome reporting;
+- stable public APIs;
+- standards traceability;
+- comprehensive test coverage.
+
+Before opening a pull request, please review `CONTRIBUTING.md` for the
+complete development workflow and coding conventions.
+
+---
+
+## Security
+
+Security issues should be reported responsibly.
+
+Please refer to `SECURITY.md` for the project's security policy,
+supported versions and the preferred disclosure process.
+
+---
+
 ## License
 
-[MIT](./LICENSE)
+This project is released under the MIT License.
+
+See the accompanying `LICENSE` file for the complete license text.
+
+---
+
+## Final Notes
+
+surea11y was created with a simple goal: make accessibility testing
+trustworthy enough to become part of everyday software engineering.
+
+It does not attempt to replace manual accessibility reviews, usability
+testing or expert judgement. Instead, it focuses on providing reliable
+automated verification for the parts of accessibility that can be
+evaluated objectively.
+
+By combining deterministic rules, standards traceability, stable
+machine-readable output and honest reporting of uncertainty, surea11y
+enables teams to detect accessibility issues earlier, reduce regressions
+and build more accessible products with confidence.
+
+Accessibility is not a checkbox performed before release. It is an
+engineering practice that benefits from continuous feedback, and
+surea11y is designed to become one of those feedback loops.

package/docs/ENGINE_OPTIONS.md

@@ -82,6 +82,7 @@ const engineOptions = {
     mode: 'strictConformance',     // 'strictConformance' (default) | 'auditorAssist'
     rootCanvasFallback: '#ffffff'  // background assumed when the true root background isn't computable
   },
+  visibilityMode: 'styleOnly',     // 'styleOnly' (default) | 'styleAndGeometry' — see below; scoped to the contrast rules only
 
   policyContract: 'a11y',          // 'a11y' (default) | 'generic' | inline contract object — see POLICY.md
   policy: {                        // optional overrides on top of policyContract
@@ -116,13 +117,77 @@ const engineOptions = {
 | `timestamp` | Passed straight through to the result's top-level `timestamp` field; the engine does not generate one itself (deterministic-by-design). |
 | `contrast.mode` | `strictConformance` (default): contrast rules stay silent (`notApplicable`/skip) whenever the true rendered background isn't confidently computable, to protect against false `fail`s. `auditorAssist`: trades some of that safety margin for more findings, intended for a human auditor who will double-check flagged cases, not for unattended CI gating. |
 | `contrast.rootCanvasFallback` | The assumed page background color when it's not computable at all — only matters in `auditorAssist` mode. |
+| `visibilityMode` | Controls how strict the three contrast rules (`contrast-minimum`, `contrast-enhanced`, `contrast-computable`) are about deciding a text node is actually eligible to check. **Not read by any other rule.** `'styleOnly'` (default): eligibility is CSS-only — `display`, `visibility`, `opacity`, ancestor-hiding, etc. `'styleAndGeometry'`: adds real layout checks (`getClientRects()`/`getBoundingClientRect()`) on top of that — text with no client rects, or zero width/height, is excluded too. Reach for `'styleAndGeometry'` when running under a real browser/Playwright-Puppeteer (`runa11yCoreInPage`) and you want contrast findings to reflect actual rendered layout rather than just computed style; under plain jsdom (`runDomRulesInPage`) there's no real layout engine, so `'styleAndGeometry'` mostly just adds `getBoundingClientRect()` zero-size checks, not true clipping/overflow detection — see [`LIMITATIONS.md`](./LIMITATIONS.md). |
 | `policyContract` / `policy` | See [`POLICY.md`](./POLICY.md) — controls which outcomes/confidence values are allowed and whether manual rules' would-be `fail`s get coerced to `cantTell`. |
-| `output.includeSelector` / `.includeHtml` | Only affects the small number of rules (currently 4 of 123) that rely on the engine's automatic selector/HTML fill-in rather than building their own — most rules set `selector`/`html` themselves inside `runInPage` and are unaffected by this option. Not a reliable way to strip selectors/HTML from all output. |
+| `output.includeSelector` / `.includeHtml` | Only affects the small number of rules (currently 4 of 125) that rely on the engine's automatic selector/HTML fill-in rather than building their own — most rules set `selector`/`html` themselves inside `runInPage` and are unaffected by this option. Not a reliable way to strip selectors/HTML from all output. |
 | `rules[ruleId]` | Passed through to that rule as `ctx.config`. The plumbing exists end-to-end, but **no shipped rule currently reads `ctx.config`** — this is infrastructure for future per-rule configurability, not a lever that changes any of today's 123 rules' behavior. |
 | `probes` | An optional, JSON-safe evidence object your host application can supply (depth- and size-capped by the engine before rules see it, via `ctx.inputs.probes`) — for future rules that might accept externally-supplied signals (e.g. real layout measurements a static DOM scan can't compute itself). Not consumed by any current rule. |
 | `perfStats` / `profileRules` | Debug-only. `perfStats: true` returns internal counters on the result's `perfStats` field; `profileRules: true` additionally adds a per-rule timing breakdown. Shape is not part of the stable output contract — don't build on it. |
 | `pingWaitTime` / `frameWaitTime` | Only read by `runa11yCoreAcrossFrames` (see [`INTEGRATION.md`](./INTEGRATION.md#cross-frame-scanning-including-cross-origin)) — how long to wait for a child frame to answer a ping (default `500`ms) and a full run request (default `60000`ms) before treating it as unreachable. Ignored by `runDomRulesInPage`/`runa11yCoreInPage`. |
 
+## Recipes — composing options for real scenarios
+
+The reference above documents each option in isolation. These combine several at once, for scenarios you're likely to actually hit.
+
+**CI gate: WCAG 2.2 AA only, ignore a third-party widget you don't control**
+
+```js
+runDomRulesInPage(url, null, {
+  excludeSelectors: ['#cookie-banner', '.intercom-launcher'],
+  tags: { include: 'wcag2a,wcag2aa,wcag21a,wcag21aa,wcag22a,wcag22aa' }
+}, null);
+```
+
+**Human auditor doing a deep contrast pass in a real browser** — trade some false-positive protection for more findings, and check real layout (not just computed style) since a real page is being driven. Shown with Puppeteer's `page.evaluate` (accepts multiple args); if you're on Playwright, wrap the four positional args into a single object first — see [`INTEGRATION.md`](./INTEGRATION.md):
+
+```js
+const result = await page.evaluate(runa11yCoreInPage, url, null, {
+  contrast: { mode: 'auditorAssist' },
+  visibilityMode: 'styleAndGeometry'
+}, null);
+```
+
+**Scoped re-scan of one region after a UI change, skipping shadow DOM** — useful in a component-level test where you only care about the widget you just changed:
+
+```js
+runDomRulesInPage(url, '#checkout-form', {
+  includeShadowDom: false
+}, { includeRuleIds: ['form-control-programmatic-label-present', 'button-name-present'] });
+```
+
+**Reproducible output for snapshot testing** — pin a `timestamp` so two runs of the same HTML produce byte-identical JSON, and request the debug timing breakdown:
+
+```js
+runDomRulesInPage(url, null, {
+  timestamp: '2026-01-01T00:00:00Z',
+  perfStats: true,
+  profileRules: true
+}, null);
+```
+
+**A custom, org-specific rule alongside the built-ins**, only for this one call:
+
+```js
+runDomRulesInPage(url, null, {
+  customRules: [{
+    id: 'org-no-inline-onclick',
+    meta: { title: 'No inline onclick handlers', defaultSeverity: 'moderate' },
+    runInPage(ctx) {
+      const els = ctx.helpers.queryAll('[onclick]');
+      const occurrences = els.map((el) => ({
+        selector: ctx.helpers.buildSelector(el),
+        html: el.outerHTML,
+        summary: 'Inline onclick handler found.',
+        hint: 'Move event handling into an external script.'
+      }));
+      return { ruleId: ctx.rule.ruleId, outcome: occurrences.length ? 'fail' : 'pass', severity: 'moderate', occurrences };
+    }
+  }]
+}, null);
+```
+
+See the option-by-option table above for anything not shown here, and the `customRules` section immediately below for the full descriptor contract.
+
 ## `customRules` — runtime-registered rules (equivalent to the rule/check registration pattern used by other engines)
 
 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.