@surea11y/core 1.6.0 → 1.8.0

package/README.md

@@ -6,30 +6,79 @@
 [![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)
 
+[Website](https://surea11y.dev/) · [Documentation](https://surea11y.dev/getting-started/) · [Rules](https://surea11y.dev/rules/)
+
 > **Accessibility testing that tells you what it can't tell you.**
 
-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.
+`@surea11y/core` is the WCAG accessibility testing engine behind the surea11y
+family of packages. It runs in Node.js against a DOM you supply (such as
+jsdom) or inside a real browser page, and returns deterministic,
+standards-traceable results. The integrations for Playwright, Cypress,
+Puppeteer, Selenium, WebdriverIO, Jest/Vitest and the command line are
+separate packages built on this engine: see
+[Which package do I need?](#which-package-do-i-need).
+
+What sets it apart is what it does with the cases automated testing can't
+settle. It implements the W3C's open [Accessibility Conformance Testing (ACT)
+Rules Format](https://www.w3.org/TR/act-rules-format/), verified against
+ACT's own published test corpus rather than judged only against itself, and
+it reports findings, non-findings, and (unusually) explicit uncertainty, so
+results are auditable rather than reassuring.
 
 *Sure* means certainty about what is known, and honesty about what isn't.
 
-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.
-
-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.
+132 accessibility rules · 58 validated against the ACT corpus (798 reference
+cases) · zero runtime dependencies
+
+Unlike browser extensions or cloud-based services, the engine is a library.
+You install it, run it where your code runs, and receive structured results
+that can be consumed by people, scripts or reporting tools.
+
+## Contents
+
+- [Goals](#goals)
+- [What automated testing can and cannot do](#what-automated-testing-can-and-cannot-do)
+- [What this engine does not detect](#what-this-engine-does-not-detect)
+- [Key principles](#key-principles)
+- [Choosing the right execution model](#choosing-the-right-execution-model)
+- [Which package do I need?](#which-package-do-i-need)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Understanding the Results](#understanding-the-results)
+- [Documentation](#documentation)
+- [Philosophy](#philosophy)
+- [Project Structure](#project-structure)
+- [Building the Project](#building-the-project)
+- [Contributing](#contributing)
+- [Security](#security)
+- [Versioning & stability](#versioning--stability)
+- [Maintainer](#maintainer)
+- [License](#license)
+
+## Goals
+
+1. **Say only what can be established, and say it plainly when it can't.**
+   `fail` is reserved for objective, normative violations; `cantTell` exists
+   so an ambiguous case is reported as ambiguous rather than silently
+   dropped or guessed at. A shorter report is not a goal in itself.
+
+2. **Verify against an open standard, not just internal tests.** Every rule
+   with a W3C ACT Rules counterpart runs against ACT's own published test
+   corpus — 798 examples across 58 rules — and the results are public. See
+   [Checked against the ACT corpus](#checked-against-the-act-corpus) below.
+
+3. **Make the engine and its rules approachable to build on.** Custom rules,
+   policies, and framework bindings are first-class extension points, and
+   every rule ships with its WCAG mapping, applicability, and expectation
+   documented. Worked examples are available in
+   [`docs/RULE_EXAMPLES.md`](./docs/RULE_EXAMPLES.md), and the complete rule
+   catalog can be browsed at [surea11y.dev/rules](https://surea11y.dev/rules/).
 
 ## What automated testing can and cannot do
 
-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:
+Many WCAG requirements cannot be determined through automated testing alone and
+require human judgement. surea11y's answer is to make that boundary explicit.
+Each rule makes a single deterministic decision:
 
 - **`fail`** — a violation provable from the DOM. Reserved for objective,
   normative cases.
@@ -42,18 +91,52 @@ falls on. Each rule makes a single deterministic decision:
 `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.
 
+### Checked against the ACT corpus
+
+Every rule with a [W3C ACT Rules](https://act-rules.github.io/) counterpart runs
+against ACT's own published test cases: 798 examples across 58 rules. The engine
+fails none of the examples ACT marks `passed` or `inapplicable`, so it reports no
+false positives against that corpus. Where it cannot decide a case it returns
+`cantTell`, which ACT permits for an automated implementation.
+
+Thirty-one examples ACT marks `failed` go unflagged. Most are judgement calls,
+such as whether a heading describes the content under it.
+[`docs/ACT_RULE_MAPPING.md`](./docs/ACT_RULE_MAPPING.md) lists every one with the
+reasoning, and `node scripts/act-testcase-check.js` reproduces the figures. They
+cover the rules that have an ACT counterpart.
+
+The [EARL implementation report](https://surea11y.github.io/act-report/act-report.jsonld)
+records the outcome for every one of those cases, passes and inapplicable
+results included, so a rule that stayed silent because nothing applied is
+distinguishable from one that is not implemented. `node scripts/act-report.js`
+regenerates it against the corpus as it stands rather than a snapshot, and a
+scheduled job republishes it weekly and on release.
+
 ## 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.
+Some things lie outside what a scan of the DOM can establish. For example,
+the engine will not:
 
-[`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.
+- 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 trap, or reflow and clipping at 400% zoom, since both
+  require simulating real user interaction over time;
+- see anything that only exists after a click or an async load.
+
+Where a case comes down to judgement, such as whether a heading is
+meaningful, the engine reports `cantTell` rather than guessing. Each of these
+boundaries is a reasoned decision rather than an oversight:
+[Known limitations](https://surea11y.dev/help/known-limitations/) lists them
+in full with the reasoning for each (also in
+[`docs/LIMITATIONS.md`](./docs/LIMITATIONS.md)). A `pass` from this engine, or
+from any automated tool, is never a substitute for the manual review WCAG
+itself requires.
 
-### Key principles
+## Key principles
 
 - **Deterministic execution.** The same input always produces the same
   output.
@@ -69,21 +152,22 @@ never a substitute for the manual review WCAG itself requires.
   by rule IDs, tags or WCAG version.
 - **Localized reporting.** Human-readable messages can be translated
   without affecting machine-readable data. Ships with `en`, `fr`, `de`,
-  and `es` today — see [`docs/I18N.md`](./docs/I18N.md) to use one or
+  `es` and `ja` today. See [`docs/I18N.md`](./docs/I18N.md) to use one or
   contribute another.
 
 ---
 
 ## Choosing the right execution model
 
-surea11y supports two complementary execution models. Choosing the
+The engine 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.
+`runDomRulesInPage()` analyses HTML without executing page JavaScript,
+and so does the separate [`@surea11y/cli`](#cli) package, which wraps it
+for the terminal.
 
 This approach is ideal for:
 
@@ -134,7 +218,9 @@ matches how you test — each pulls in `@surea11y/core` for you.
 | 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.
+[Getting Started](https://surea11y.dev/getting-started/) on surea11y.dev
+covers installation and usage for each of these. The rest of this README
+covers `@surea11y/core` itself.
 
 ---
 
@@ -329,6 +415,33 @@ 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.
 
+### Conformance targets and EN 301 549
+
+To test against a named target instead of a hand-picked tag list, pass a
+profile:
+
+```js
+runDomRulesInPage(url, null, { profile: 'en301549-v3.2.1' }, null);
+```
+
+`wcag22-aa`, `en301549-v4.1.1`, `en301549-v3.2.1` and `section508` each run
+the WCAG Level A and AA rules of the version they build on; the result records
+the one used in `engine.profile`. A profile only chooses which rules
+run; it does not certify conformance. A standard with verdicts of its own
+comes as a profile under [`profiles/`](./profiles/README.md), with its own
+rules, which run only when a scan targets it; to run every rule instead, pass
+`optInRules: 'all'` with no profile; the result records it in
+`engine.optInRules`.
+
+An EN 301 549 profile also maps every WCAG criterion in the result to the
+clause of that version that restates it (1.4.3 to 9.1.4.3, for example), and
+the SARIF, JUnit and HTML reports carry those clauses. To get the clauses
+without the profile, or for both versions, pass
+`mappings: ['en301549']` (or `'en301549:V3.2.1'`); by default a result names
+WCAG only. See
+[`docs/ENGINE_OPTIONS.md`](./docs/ENGINE_OPTIONS.md#conformance-profiles) and
+[`docs/WCAG_CONFORMANCE.md`](./docs/WCAG_CONFORMANCE.md#en-301-549).
+
 ---
 
 ## Understanding the Results
@@ -392,14 +505,25 @@ 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`.
+For a complete field-by-field reference, see
+[Output schema](https://surea11y.dev/results-reports/output-schema/)
+(`docs/OUTPUT_SCHEMA.md` in the repository).
 
 ---
 
 ## Documentation
 
-The project documentation is organized by topic so you can start quickly
-and progressively explore more advanced features.
+Full documentation is available at **[surea11y.dev](https://surea11y.dev/)**:
+[getting started](https://surea11y.dev/getting-started/) for each integration,
+the [rule catalog](https://surea11y.dev/rules/),
+[configuration](https://surea11y.dev/configuration/),
+[results and reports](https://surea11y.dev/results-reports/),
+[WCAG conformance](https://surea11y.dev/conformance/), and
+[help](https://surea11y.dev/help/).
+
+The repository also contains the following technical and contributor
+documentation, useful as direct references when building on the engine or
+contributing to it:
 
 | Document | Description |
 |---|---|
@@ -408,17 +532,20 @@ and progressively explore more advanced features.
 | `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/JUNIT.md` | JUnit XML report for the test dashboards of GitLab, Azure DevOps, Jenkins and CircleCI. |
+| `docs/EARL.md` | EARL 1.0 report in JSON-LD: the W3C interchange format, and the ACT implementation-report format. |
 | `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. |
-| `docs/RULE_CATALOG.md` | Reference of every built-in accessibility rule. |
+| `docs/RULE_CATALOG.md` | Reference of every built-in accessibility rule; a profile's own rules are in its catalog, in `profiles/<key>/docs/RULE_CATALOG.md`. |
 | `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_HELPERS.md` | Reference for every `ctx.helpers` function available to a rule. |
 | `docs/RULE_TAXONOMY.md` | Rule categorization model. |
 | `docs/ACT_RULE_MAPPING.md` | Which ACT rules this engine implements, which it doesn't, and where the two differ by design. |
 | `docs/DESIGN_CHALLENGES.md` | Open and settled design questions, each with the reasoning behind the call. |
@@ -438,40 +565,16 @@ 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.
+Some WCAG requirements can be checked with complete confidence. Others
+need human judgement, knowledge of context, or usability evaluation. A
+single score or a pass/fail verdict flattens that difference; surea11y
+reports it.
 
-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.
+This is why `cantTell` and `notApplicable` exist as outcomes (see
+[What automated testing can and cannot do](#what-automated-testing-can-and-cannot-do)),
+and why the engine is explicit about
+[what it does not detect](#what-this-engine-does-not-detect). It shapes
+every rule in the engine.
 
 ---
 
@@ -490,6 +593,11 @@ src/
   baseline.js              # Baseline entry point (@surea11y/core/baseline)
   report.js                # HTML report entry point (@surea11y/core/report)
   sarif.js                 # SARIF entry point (@surea11y/core/sarif)
+  junit.js                 # JUnit XML entry point (@surea11y/core/junit)
+  earl.js                  # EARL entry point (@surea11y/core/earl)
+  en301549.js              # EN 301 549 clause table (@surea11y/core/en301549)
+  wcag.js                  # WCAG criteria per version (@surea11y/core/wcag)
+  profile-kit.js           # Mapping for a profile made with profile:new (internal, not exported)
 
   checks/
     automatic/             # Deterministic automated rules
@@ -502,6 +610,10 @@ src/
   catalogs/                # Composite rule catalogs
   explain/                 # Occurrence grouping, internal
 
+profiles/
+  index.js                 # The profiles built into the engine (none yet)
+  README.md                # What a profile holds and how to add one
+
 scripts/
   build-core.js            # Generates src/core.js
   build-browser.js         # Generates the browser bundle and its locale side files
@@ -550,9 +662,7 @@ engine consistency to ensure deterministic results across releases.
 
 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:
+Bug fix, documentation, or a new rule — the same principles apply:
 
 - deterministic behaviour;
 - objective rule evaluation;
@@ -603,24 +713,3 @@ 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
-
-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/ACT_RULE_MAPPING.md

@@ -7,7 +7,7 @@ Cross-reference between the [W3C ACT Rules](https://act-rules.github.io/rules/)
 - **~2** are covered structurally by our composite/rollup layer, not a named rule
 - **~46 are gaps**, no corresponding rule in this repo, listed in [Gaps](#gaps-no-corresponding-rule) below
 
-**Every matched rule has now been run through ACT's own official test-case corpus** (`scripts/act-testcase-check.js`, 713 test cases across the 51-rule matched set of the time). Started at 86 mismatches; real bugs were fixed, mapping errors corrected, and every remaining mismatch triaged into a scope difference, a jsdom/environment limit, or a genuine open design question (tracked in [`docs/DESIGN_CHALLENGES.md`](./DESIGN_CHALLENGES.md)). A second pass then re-ran the whole corpus from a local checkout (see "Second pass" below) and repeated the exercise on what it turned up. Current state: **798 examples across the 58-rule matched set, 32 mismatches, all explained** below or in that file; see "Progress" further down for the full per-rule breakdown. (The exact example count drifts slightly over time as ACT's own published corpus gains or loses cases; re-run `scripts/act-testcase-check.js` for the live figure rather than trusting this number indefinitely.)
+**Every matched rule has now been run through ACT's own official test-case corpus** (`scripts/act-testcase-check.js`, 713 test cases across the 51-rule matched set of the time). Started at 86 mismatches; real bugs were fixed, mapping errors corrected, and every remaining mismatch triaged into a scope difference, a jsdom/environment limit, or a genuine open design question (tracked in [`docs/DESIGN_CHALLENGES.md`](./DESIGN_CHALLENGES.md)). A second pass then re-ran the whole corpus from a local checkout (see "Second pass" below) and repeated the exercise on what it turned up. Current state: **798 examples across the 58-rule matched set, 31 mismatches, all explained** below or in that file, and — the figure that matters for an implementation report — **zero false positives**: no example ACT declares `passed` or `inapplicable` is failed by this engine, so every remaining mismatch is a case it does not catch rather than one it gets wrong; see "Progress" further down for the full per-rule breakdown. (The exact example count drifts slightly over time as ACT's own published corpus gains or loses cases; re-run `scripts/act-testcase-check.js` for the live figure rather than trusting this number indefinitely.)
 
 Real rule bugs found and fixed this way, in rough chronological order:
 - `button-name-present` wasn't crediting the UA-default label on `input[type=submit]`/`input[type=reset]` with no `value`, and wasn't honoring `role="none"`/`role="presentation"` conflict-resolution.
@@ -31,6 +31,7 @@ Real rule bugs found and fixed this way, in rough chronological order:
 - `getContainmentRole` handed several native tags an implicit role in every context, where HTML-AAM makes them conditional: `<li>` is a `listitem` only inside `<ul>`/`<ol>`/`<menu>`, `<option>` only inside `select`/`datalist`/`optgroup`, the table family only inside a real table. ACT `bc4a75` fails `<div role="list"><li>Item</li>…</div>` for exactly that reason and the engine passed it. The three rules built on that helper (`aria-required-children`, `aria-prohibited-children`, `aria-required-parent`) all inherit the fix.
 - `identical-links-same-purpose`'s `a[href]`-only selector missed `role="link"` elements entirely; ACT `fd3a94`/`b20e66`'s own failed examples are `<span role="link" tabindex="0" onclick="location='...'">`. Widened to `a[href], [role="link"]`, with a regex fallback that reads a `location`/`location.href`/`location.assign(...)`/`location.replace(...)` destination straight out of the `onclick` attribute value, a literal string already present in markup, no script execution needed. This rule is `cantTell`-capped, so an unrecognized `onclick` shape just costs recall, not a false fail.
 - `iframe-name-present`'s focusability exemption only applied inside the `role="none"`/`"presentation"` branch; a plain `<iframe tabindex="-1">` with no role at all (ACT cae760's own passed example) still demanded a name. Per cae760's own Applicability text, an iframe is only in scope when it is BOTH accessibility-tree-eligible AND reachable by sequential focus navigation, unconditionally, not only as a role="none" carve-out. The focusability check now gates applicability directly, regardless of role.
+- `avoid-inline-spacing` failed text that can never take a soft wrap break, which ACT 78fd32/24afc2/9e45ec exclude from applicability altogether. This was the engine's last false positive on the corpus, and the rule's own header had already predicted it: layout settles whether text wraps and a static scan cannot. Two shapes do establish that no wrap is possible without layout — text not allowed to wrap, and a fixed-width element inside a horizontally scrolling ancestor — and those now report `cantTell` instead of `fail`. Everything else is still treated as wrapping, so an ordinary forced value below the metric fails as before.
 
 Mapping-table corrections found this way (data-only, no rule-code change):
 - `bc4a75` was mapped to `aria-required-children` alone, but this repo splits ACT's single question into two atomic decisions: "does a required child exist" and "is every owned child allowed," the second being `aria-prohibited-children`. Measuring one rule against a two-part expectation reported the missing half as an engine gap; it was a mapping gap. Now a family match.
@@ -47,7 +48,7 @@ Gaps closed since:
 - `oj04fd` "Element in sequential focus order has visible focus" is now partly covered by the new `css-focus-indicator-suppressed` rule: it reads the page's own stylesheets for a `:focus`/`:focus-visible` rule that removes the outline, and reports the tab stops it matches unless some other focus rule draws a replacement for them. ACT's expectation is a pixel comparison between the focused and unfocused states, which no static check performs, and its passed examples paint their indicator from an `onfocus` handler onto a sibling, so the rule is `cantTell`-capped and the mapping is `partial`.
 - `cc0f0a` "Form field label is descriptive" is now partly covered by the new `form-control-label-quality` rule. Three shapes of a bad label are decidable from markup: a placeholder string, a label repeated on several fields with no *visible* heading, legend or row text telling them apart, and a label split between visible and hidden parts. The second and third are what ACT's own failed examples 4 and 5 test, and the rule catches both; the remaining three failures turn on the meaning of an ordinary word, so the mapping is `partial` and the rule is `cantTell`-capped.
 - `5effbb` "Link in context is descriptive" is now partly covered by `link-name-quality`, which already flagged a curated list of generic phrases ("click here", "read more", ...) with no regard for context. It gained a second curated list, bare file-format names ("HTML", "PDF", "EPUB", ...), and both lists now check for adjacent context (an `aria-describedby` target, the enclosing list item/table cell/paragraph's own text, or, for the format-name list only, a table's first-row header) before flagging, so a phrase that context already resolves is left alone. Clean on 17 of ACT's 18 examples; the remaining one needs to judge whether an ordinary word ("Workshop") actually relates to a nearby paragraph, a step beyond a phrase list.
-- `3ea0c8` "Id attribute value is unique" is closed by the new `duplicate-id` rule, clean against all 10 of ACT's examples, including the per-tree scoping that keeps the same id inside two different shadow roots from counting as a duplicate. It is the first rule in the catalog whose Success Criterion no longer exists in the current WCAG version, so it carries `wcag22-removed` alongside its `wcag2a` origin tag; see `docs/ENGINE_OPTIONS.md` for how a 2.2 conformance run excludes it.
+- `3ea0c8` "Id attribute value is unique" is closed by the new `duplicate-id` rule, clean against all 10 of ACT's examples, including the per-tree scoping that keeps the same id inside two different shadow roots from counting as a duplicate. It is the first rule in the catalog whose Success Criterion no longer exists in the current WCAG version, so it carries `wcag22-removed` alongside its `wcag2a` origin tag; under the default 2.2 target the engine reports its findings as `cantTell` rather than `fail`. See `docs/ENGINE_OPTIONS.md` for that and for excluding the rule outright.
 
 ### Second pass: the corpus read from a local checkout
 
@@ -73,9 +74,11 @@ We also have automatic rules with **no ACT counterpart at all** (see [Extra cove
 
 ### Progress: full validation results, by ACT rule
 
-**Clean (0 mismatches):** `5f99a7`, `80f0bf`, `4c31df`, `73f2c2`, `97a4e1`, `cf77f2`, `b40fd1`, `46ca7f`, `6cfa84`, `307n5z`, `4e8ab6`, `a25f45`, `ffd0e9`, `b5c3f8`, `2779a5`, `5b7ae0`, `bf051a`, `qt1vmo`, `59796f`, `23a2a8`, `24afc2`, `9e45ec`, `c487ae`, `m6b1q3`, `bc659a`, `bisz58`, `b4f0c3`, `674b10`, `0ssw9k`, `3ea0c8`, `5c01ea`, `bc4a75`, `2ee8b8`, `e88epe`, `7d6734`, `de46e4`, `6a7281`, `8fc3b6`, `akn7bn`, `fd3a94`, `b20e66`, `cae760` (42 of 57 matched rules).
+**Clean (0 mismatches):** `5f99a7`, `80f0bf`, `4c31df`, `73f2c2`, `97a4e1`, `cf77f2`, `b40fd1`, `46ca7f`, `6cfa84`, `307n5z`, `4e8ab6`, `a25f45`, `ffd0e9`, `b5c3f8`, `2779a5`, `5b7ae0`, `bf051a`, `qt1vmo`, `59796f`, `23a2a8`, `24afc2`, `9e45ec`, `c487ae`, `m6b1q3`, `bc659a`, `bisz58`, `b4f0c3`, `674b10`, `0ssw9k`, `3ea0c8`, `5c01ea`, `bc4a75`, `2ee8b8`, `e88epe`, `7d6734`, `de46e4`, `6a7281`, `8fc3b6`, `akn7bn`, `fd3a94`, `b20e66`, `cae760`, `78fd32` (43 of 58 matched rules).
 
-**Remaining mismatches (32 total), all triaged:**
+Two rules changed what they report after this table was last regenerated, both from `fail` to `cantTell`: `3ea0c8`/`duplicate-id` under the default WCAG 2.2 target, and `6a7281`/`aria-valid-attr-value` for an unresolved `aria-controls` target (see `docs/DESIGN_CHALLENGES.md`). The verdicts above should still hold, since `evaluate()` in `scripts/act-testcase-check.js` counts a `cantTell` carrying occurrences as satisfying an ACT "failed" expectation and a `cantTell` never breaks a "passed" one, but neither was re-run against the live corpus at the time (the site was unreachable from that environment). Re-run both when convenient.
+
+**Remaining mismatches (31 total), all triaged.** Every one is an ACT `failed` example this engine does not flag — a coverage gap, which a partially consistent implementation is allowed — not an example it fails wrongly:
 
 | ACT ID | Mismatches | Category |
 |---|---|---|
@@ -87,7 +90,6 @@ We also have automatic rules with **no ACT counterpart at all** (see [Extra cove
 | `oj04fd` | 1 | env/harness limit: ACT's one failed example keeps its `outline: none` in a linked stylesheet, which the example runner does not fetch, so no focus rule is visible to parse at all. Inlining that same CSS reports the element (`tests/engine-checks/manual/css-focus-indicator-suppressed.test.js` pins it); a real page hands the engine its stylesheets through the CSSOM |
 | `cc0f0a` | 3 | inherent limitation: `form-control-label-quality` catches the three deterministic shapes (a placeholder label, a label repeated with no visible heading/legend/row telling the fields apart, a label split between visible and hidden parts, which covers ACT's failed examples 4 and 5). The remaining three fail on the meaning of a well-formed word, `<label>Menu</label>` over a first-name field, which no markup-level check reaches |
 | `b49b2e` | 5 | inherent limitation: `heading-quality` catches placeholder heading text (a generic word, a numbered template slot, a filename, a URL), which is the deterministic half of this rule; whether a well-formed heading actually describes the content after it is a reading-comprehension judgment, and all 5 of ACT's failed examples are exactly that shape ("Weather" over opening hours, across five different heading-naming mechanisms) |
-| `78fd32` | 1 | documented limitation: `avoid-inline-spacing`'s own header comment already states it can't detect "text that never soft-wraps" without real layout |
 | `aizyf1` | 2 | inherent tension with `5effbb`'s own examples, not a bug: both remaining cases (`<a>this product</a>` after "See the description of", and a format-name list under an "Ulysses" heading) are ACT's own *passed* examples for `5effbb` (context-aware) but *failed* examples for `aizyf1` (context-blind: the accessible name alone, ignoring what makes it clear, must already be descriptive). One shared rule can credit context or not, not both on the same markup; `link-name-quality` sides with `5effbb`'s reading, which is what its context-detection is for |
 | `5effbb` | 1 | genuine judgment gap: the one remaining case (`<a>Workshop</a>` after an unrelated paragraph) needs to judge whether an ordinary word actually relates to nearby prose, not a phrase-list or context-structure question `link-name-quality` can answer |
 | `d0f69e` | 3 | documented false-negative policy: `table-th-has-data-cells`'s own header comment explains it only catches the unambiguous "zero data cells anywhere" case, not real positional header-association (the new ARIA-grid coverage added during this pass is real but doesn't happen to close these 3 specific positional-mismatch cases) |
@@ -185,7 +187,7 @@ Grouped by theme, with WCAG SC where ACT declares one:
 - `3e12e1` Block of repeated content is collapsible
 
 **Judgment-call gaps found during test-case validation:**
-- `4b1c6c` "Iframes with identical accessible names have equivalent purpose" was originally mapped to `iframe-title-unique`, but running ACT's own test cases against it exposed that they test different things: ACT's rule accepts a duplicate name when the two iframes point to equivalent content (same resource, mirrors, equivalent ads/sections) and only fails when duplicate-named iframes point to genuinely different content, a content-equivalence judgment call, the same class of check as our existing manual `identical-links-same-purpose`. `iframe-title-unique` instead flags *any* duplicate `title` attribute outright, by design (see its own header comment), a stricter, different, independently-valid check with no ACT counterpart of its own. Moved to "Extra coverage" below; `4b1c6c` itself stays a gap, closing it for real would mean a new manual `identical-iframes-same-purpose`-style rule, not a fix to `iframe-title-unique`.
+- `4b1c6c` "Iframes with identical accessible names have equivalent purpose" was originally mapped to `iframe-title-unique`, but ACT's own test cases showed they test different things: ACT's rule accepts a duplicate name when the frames embed equivalent content (same resource, mirrors, equivalent ads or sections) and fails only when they embed different content, a content-equivalence judgment of the same kind as our manual `identical-links-same-purpose`. `iframe-title-unique` failed any duplicate `title` attribute, which this note first filed as a deliberate, stricter check with no ACT counterpart. `4b1c6c` was then closed by `identical-iframes-same-purpose`. On a second look (#16), the stricter check had no normative basis: WCAG 4.1.2 asks that a frame's name be exposed, not unique, and seven of 4b1c6c's ten passed examples failed under it. A frame's `title` is also its accessible name unless `aria-label` or `aria-labelledby` overrides it, so the two rules asked the same question of the same elements. `iframe-title-unique` is deprecated since 1.8.0 and reports `notApplicable`; `identical-iframes-same-purpose` alone covers `4b1c6c`. See `DESIGN_CHALLENGES.md`.
 - `5effbb` "Link in context is descriptive" was originally mapped to `link-in-text-block` on a name-similarity guess ("link" + "context/text"); its real applicability/expectation (fetched directly from act-rules.github.io) is "the accessible name together with its programmatically determined link context describes the purpose of the link," WCAG 2.4.4, the *context-aware* sibling of `aizyf1`/`link-name-quality`, unrelated to `link-in-text-block`'s WCAG 1.4.1 color-distinguishability check (which is itself correctly scoped to `a[href]` only, per its own header comment, not a bug). This was later closed by teaching `link-name-quality` to weigh adjacent context; see "Gaps closed since" below.
 - `oj04fd` "Element in sequential focus order has visible focus" was originally mapped to `css-hidden-focus` on a surface keyword match ("focus," "visible"); its real applicability/expectation is about whether a browser draws *any* visible focus indicator for a normally-visible, normally-positioned element (i.e. `:focus`/`:focus-visible` CSS suppressing the outline with no replacement), a completely different concern from `css-hidden-focus`'s actual check (a keyboard-focusable element that is itself visually hidden by CSS, e.g. `opacity:0`/clip/off-screen). Removed from the matched table and moved to Gaps; a plausible new-rule candidate, not a fix to `css-hidden-focus`, and built as one since, `css-focus-indicator-suppressed`, which is what `oj04fd` maps to now.
 - `cc0f0a` "Form field label is descriptive" and `c4a8a4` "HTML page title is descriptive" were both mapped to rules that only catch a narrower, adjacent concern: `form-control-programmatic-label-quality` flags a *weak primary labeling mechanism* (title/placeholder used instead of a real label), never whether a properly-associated label's own text is relevant to the field; `page-title-patterns` flags generic/templated title *patterns* (e.g. "Home", "Untitled"), never whether a specific, plausible-looking title actually matches the page's content (ACT's own failed example: `<title>Apple harvesting season</title>` on a page about clementines, a real title/content mismatch neither pattern-list nor mechanism-check was ever designed to catch). Both ACT ids moved to Gaps; both of our rules moved to [Extra coverage](#extra-coverage-beyond-act) as valid, independent, narrower checks with no ACT counterpart of their own. `cc0f0a` has since been picked up by a new rule of its own, `form-control-label-quality`; `c4a8a4` remains a gap.
@@ -207,7 +209,7 @@ The goal is maximum automation, not just parity with ACT's own scope; several ga
 - `c4a8a4` HTML page title is descriptive (title-vs-content relevance): harder to heuristic than the others in this tier (needs some notion of "does this title's vocabulary overlap with the page's own content," not just a pattern/word list), so lower confidence within this tier.
 
 **Design decision needed before building (not purely a confidence question):**
-- ~~`3ea0c8` Page-wide unique `id`~~: built as `duplicate-id`, tagged `wcag2a` plus the new `wcag22-removed`, which a 2.2 conformance run excludes and a 2.0/2.1 run keeps. The decision that unblocked it, and the reasoning, are in `docs/DESIGN_CHALLENGES.md`'s "Decided" section; the tag is documented in `docs/ENGINE_OPTIONS.md`.
+- ~~`3ea0c8` Page-wide unique `id`~~: built as `duplicate-id`, tagged `wcag2a` plus the new `wcag22-removed`, which a 2.2 conformance run reports as `cantTell` (or excludes outright) and a 2.0/2.1 run keeps as a real failure. The decision that unblocked it, and the reasoning, are in `docs/DESIGN_CHALLENGES.md`'s "Decided" section; the tag is documented in `docs/ENGINE_OPTIONS.md`.
 
 **Lower confidence, needs a different technique than the rest of the engine:**
 - `e6952f` Attribute is not duplicated: only detectable from the raw HTML *text* (the DOM has already collapsed duplicate attributes by the time any DOM-based rule runs), a different input than every other rule in this engine uses. Feasible only where raw source is available (not guaranteed in every integration).
@@ -233,7 +235,7 @@ The goal is maximum automation, not just parity with ACT's own scope; several ga
 
 Rules in this repo with no ACT counterpart, mostly finer decomposition of ACT's single `e086e5` "form field has accessible name" rule into one rule per ARIA widget type, plus some ARIA-validity and structural rules ACT doesn't break out separately:
 
-`aria-hidden-body`, `aria-braille-equivalent`, `aria-conditional-attr`, `aria-deprecated-role`, `aria-prohibited-attr`, `aria-prohibited-children`, `aria-role-name-present`, `binary-control-name-present`, `canvas-text-alternative-present`, `combobox-name-present`, `contrast-computable`, `definition-list-children-valid`, `deprecated-elements-not-used`, `dialog-name-present`, `dlitem-parent-valid`, `duplicate-id-aria`, `embed-text-alternative-present`, `form-control-programmatic-label-quality`, `form-control-single-label`, `iframe-title-unique`, `list-children-valid`, `listbox-name-present`, `listitem-parent-valid`, `meter-name-present`, `nested-interactive-controls-absent`, `option-name-present`, `page-title-patterns`, `progressbar-name-present`, `searchbox-name-present`, `server-side-image-map-absent`, `slider-name-present`, `spinbutton-name-present`, `summary-name-present`, `svg-image-text-alternative-present`, `tab-name-present`, `target-size-minimum`, `td-has-header`, `textbox-name-present`, `tooltip-name-present`, `treeitem-name-present`, `video-poster-text-alternative-present`, `area-alt-present`.
+`aria-hidden-body`, `aria-braille-equivalent`, `aria-conditional-attr`, `aria-deprecated-role`, `aria-prohibited-attr`, `aria-prohibited-children`, `aria-role-name-present`, `binary-control-name-present`, `canvas-text-alternative-present`, `combobox-name-present`, `contrast-computable`, `definition-list-children-valid`, `deprecated-elements-not-used`, `dialog-name-present`, `dlitem-parent-valid`, `duplicate-id-aria`, `embed-text-alternative-present`, `form-control-programmatic-label-quality`, `form-control-single-label`, `list-children-valid`, `listbox-name-present`, `listitem-parent-valid`, `meter-name-present`, `nested-interactive-controls-absent`, `option-name-present`, `page-title-patterns`, `progressbar-name-present`, `searchbox-name-present`, `server-side-image-map-absent`, `slider-name-present`, `spinbutton-name-present`, `summary-name-present`, `svg-image-text-alternative-present`, `tab-name-present`, `target-size-minimum`, `td-has-header`, `textbox-name-present`, `tooltip-name-present`, `treeitem-name-present`, `video-poster-text-alternative-present`, `area-alt-present`.
 
 ## Next steps