@surea11y/core 1.7.0 → 1.8.0

package/docs/RULE_HELPERS.md

@@ -40,6 +40,33 @@ open shadow roots are in scope and let this helper honor the caller's choice.
 const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('img') : helpers.queryAll('img');
 ```
 
+### `queryAllSource(selector)` → `Element[]`
+The same query as `queryAllSmart` (shadow roots per `includeShadowDom`, context scope,
+`excludeSelectors`) with no hidden-content filter: elements inside `hidden`,
+`display:none`, closed `<details>` and the like are returned whatever
+`includeHiddenElements` says. Only for rules that judge the markup itself rather than
+what is rendered, such as a standard's tests on the generated source.
+`<template>` content is not in the DOM tree and stays out. A WCAG rule should not use
+it: hidden content is not presented to users.
+
+### `getDoctypeInfo()` → `{ kind, name, publicId, systemId }`
+The document's doctype, classified by HTML version. `kind` is one of:
+
+| `kind` | Doctype |
+|---|---|
+| `'html5'` | name `html`, no public id, and no system id or `about:legacy-compat` |
+| `'xhtml10'` | a public id of XHTML 1.0 (strict, transitional or frameset) |
+| `'xhtml11'` | any other W3C XHTML public id: XHTML 1.1, XHTML Basic, XHTML 1.1 plus MathML (and SVG), XHTML+RDFa |
+| `'html4'` | a W3C or IETF HTML public id: HTML 2.0, 3.2, 4.0, 4.01, HTML 4.01+RDFa |
+| `'other'` | any other doctype, including one whose name is not `html` |
+| `'none'` | no doctype |
+
+Public ids are compared without regard to case, as the HTML parser does. `name`,
+`publicId` and `systemId` are the doctype's own values (empty strings when there is
+none). For rules whose verdict depends on the HTML version: a requirement that
+applies to HTML5 only, or `lang` read as `lang` or `xml:lang` by version. Whether a
+doctype is valid at all is not this helper's question.
+
 ### `composedParent(node)` → `Node | null`
 One step up the *flat tree*: `assignedSlot` first (a slotted node's rendered parent is
 its slot, not its light-DOM `parentNode`), then `parentNode`, then `.host` once you're
@@ -176,7 +203,9 @@ a name exists.
 Recursive "name from content" (accname step 2F): walks children using each child's
 *own* accessible name (not just literal text), so `<a href="…"><img alt="Company
 Name"></a>` and `<button><span aria-label="Close"></span></button>` both name correctly.
-A plain `TreeWalker(SHOW_TEXT)` walk misses both.
+A plain `TreeWalker(SHOW_TEXT)` walk misses both. An SVG element with a `<title>` child
+speaks for itself through that title (SVG-AAM), after its own `aria-labelledby` and
+`aria-label`, so `<button><svg><title>Search</title></svg></button>` is named "Search".
 
 ### `getAssociatedLabelElements(el)` → `Element[]`
 Real `<label>` element(s) associated with `el` — a `<label for="id">` pointing at it,
@@ -186,6 +215,15 @@ native `.labels`/`.control` API** — in this project's supported jsdom runtime,
 another one), which used to dominate whole-engine runtime on form-heavy pages. Use this
 whenever a rule needs the actual label element(s), not just a yes/no.
 
+### `getNativeHostNameInfo(el, ctx, opts)` → `{ present, value, mechanism }`
+The name an element gets from its HTML host markup rather than from ARIA: an associated
+`<label>` on a labelable element, the first child `<legend>` of a `<fieldset>`, the first
+child `<caption>` of a `<table>`, and, only with `opts.placeholder: true`, the
+`placeholder` of a text-like `<input>` or a `<textarea>` (HTML-AAM's last name source).
+`mechanism` is `'label'`, `'legend'`, `'caption'`, `'placeholder'` or `'none'`. For rules
+on name-from-author-only roles (`role="textbox"`, `"slider"`, `"radiogroup"`, …) whose
+ARIA check does not read host markup, although the browser still computes it.
+
 ### `labelContributesAccessibleName(labelEl)` → `boolean`
 Whether a `<label>` element itself carries text that would name its control: own
 ARIA name, else rendered content (`getContentNameInfo`, so `aria-hidden`/`display:none`
@@ -267,6 +305,13 @@ subtag (the registry only lists a three-letter subtag when no two-letter one exi
 so `"en"` is registered and `"eng"` is not). Use `isValidLanguageTag` for any
 `lang`/`xml:lang`-checking rule instead of a regex-only check.
 
+### `hasSkipLinkWording(text)` → `boolean`
+Whether a link's text reads as a skip link ("Skip to content", "Aller au contenu",
+"Zum Inhalt", "Saltar al contenido", "本文へ"...), in the languages the engine ships.
+One list for every rule that looks for a skip link, core's `skip-link` and any a
+profile brings, so they recognise the same links; add a phrasing here, not in a
+rule.
+
 ### `reportOccurrence(node, partial)` → occurrence object
 **Use this to build every occurrence.** Attaches the element so the engine fills in
 `selector`, `html`, and `structuralPath` centrally — see `RULE_AUTHORING.md` §4.3/§9 for
@@ -307,11 +352,23 @@ flat `helpers.*` list above:
 Color/contrast math and text-run analysis: `parseCssColorToRgba`, `compositeRgba`,
 `relativeLuminance`, `contrastRatio`, `requiredRatio`, `isLargeText`,
 `computeEffectiveForeground`/`computeEffectiveBackground`, `getComputabilityBlocker`,
+`hasBackgroundImageOrGradient`, `hasBlendMode`, `hasFilter`, `computeOpacityProduct`,
 `getTextScan`, `isInactiveUiComponent`, plus small numeric/formatting utilities
-(`clamp01`, `round2`, `toHex2`, `pxToPt`, `fontWeightLabel`, …). Backs the
-`contrast-*` rule family (`contrast-minimum`, `contrast-enhanced`,
-`contrast-computable`) — see `src/core/contrast-helpers.js` if you're extending that
-family specifically.
+(`clamp01`, `clamp255`, `round2`, `toHex2`, `rgbToHex`, `rgbaToString`, `parsePx`,
+`normalizeFontWeight`, `pxToPt`, `fontWeightLabel`). That is the whole namespace,
+apart from `sharedCache`: a plain object that lives for one scan and lets the contrast
+rules reuse per-element work. Treat it as an optimisation, never as data a rule
+depends on: a key may be absent, and a rule stores only under keys of its own unless
+it computes exactly what that key's other users compute (`contrast-minimum`,
+`contrast-enhanced` and `contrast-computable`, and `contrast-minimum`'s variants,
+share `__elBgCache`, `__elFgCache` and `__elBlockerCache`,
+WeakMaps of each element's effective background, foreground and computability blocker;
+a variant with other thresholds keeps its own font and analysis caches, keyed by them). Backs the
+`contrast-*` rule family (`contrast-minimum` and its variants, `contrast-enhanced`,
+`contrast-computable`) — see `src/core/contrast-helpers.js`
+if you're extending that family specifically. `isLargeText(fontSizePx, fontWeightNum,
+boldLargeMinPx)` takes an optional third argument, the size from which bold text is large:
+WCAG's 14pt when it is left out, 18.5 for a standard that puts it there.
 
 ### `helpers.aria.*`
 ARIA validity/taxonomy data and checks: `isValidAriaAttrName`, `getAttrValueType`,

package/docs/RULE_TAXONOMY.md

@@ -45,7 +45,7 @@ decidable from markup.
 ### 1.2 Intent
 Encoded by: **rule id suffix**
 
-Illustrative intents (from the image-alternatives family used as the running example in §2, not an exhaustive list — the ruleset's 130 rules use dozens of distinct suffixes; `docs/RULE_CATALOG.md` is the generated, always-current list):
+Illustrative intents (from the image-alternatives family used as the running example in §2, not an exhaustive list — the ruleset's rules use dozens of distinct suffixes; `docs/RULE_CATALOG.md` is the generated, always-current list):
 
 - `present`
     - Verifies that a required **mechanism exists**
@@ -64,7 +64,7 @@ Intent determines whether a rule can be automatic.
 ### 1.3 Target Family
 Encoded by: **rule id prefix**
 
-Illustrative families, from the image-alternatives cluster (WCAG 1.1.1) used as the running example in §2 — not an exhaustive list. The ruleset's 130 rules span dozens of families (`aria-*`, `contrast-*`, `dialog-*`, `iframe-*`, `label-*`, `link-*`, `list-*`, `landmark-*`, and more); see `docs/RULE_CATALOG.md` for the generated, always-current list:
+Illustrative families, from the image-alternatives cluster (WCAG 1.1.1) used as the running example in §2 — not an exhaustive list. The ruleset's rules span dozens of families (`aria-*`, `contrast-*`, `dialog-*`, `iframe-*`, `label-*`, `link-*`, `list-*`, `landmark-*`, and more); see `docs/RULE_CATALOG.md` for the generated, always-current list:
 
 - `img`
 - `area`

package/docs/SARIF.md

@@ -52,7 +52,8 @@ Every rule that ran (regardless of whether it produced a result) is listed once
 | `results[].locations[].logicalLocations[].fullyQualifiedName` | `occurrence.selector`, when present. |
 | `results[].partialFingerprints["surea11y/violation/v1"]` | The same `ruleId + reasonCode + html` identity key used by [`BASELINE.md`](./BASELINE.md) (`computeBaselineKey`) — a stable, content-based fingerprint rather than a position-based one. |
 | `results[].properties.severity` / `.confidence` | `checksResults[i].severity` / `.confidence` — informational, not part of SARIF's own schema. |
-| `tool.driver.rules[].properties.tags` | `accessibility`, `automatic`/`manual`, and a `wcag-<SC>` tag per `meta.normativeMappings[].requirement`. |
+| `tool.driver.rules[].properties.tags` | `accessibility`, `automatic`/`manual`, and a `wcag-<SC>` tag per WCAG Success Criterion in `meta.normativeMappings`. Understanding-document entries get no tag. Each EN 301 549 clause the result carries (only when the scan asked for them, see [`ENGINE_OPTIONS.md`](./ENGINE_OPTIONS.md#other-standards-mappings)) gets an `en301549-<clause>` tag, e.g. `en301549-9.1.1.1`: clause numbers are the same in every version that has them, so the tag carries no version. |
+| `runs[0].properties` | `wcagVersion`, `profile` and `optInRules` from the result's `engine`: the conformance target the run used, so a dashboard can tell a WCAG 2.1 run from a 2.2 one, and the opt-in rule tags it added beyond that target when it added any. Omitted for results from engines that predate those fields. |
 
 ## Locations
 

package/docs/WCAG_CONFORMANCE.md

@@ -4,9 +4,9 @@ How individual rule results relate to a WCAG Success Criterion (SC), and what su
 
 ## The three layers
 
-1. **Atomic rules** (`checksResults[]`) — one normative decision each, e.g. "does this `<img>` have an `alt` attribute." See [`RULE_CATALOG.md`](./RULE_CATALOG.md) for all 130.
+1. **Atomic rules** (`checksResults[]`) — one normative decision each, e.g. "does this `<img>` have an `alt` attribute." See [`RULE_CATALOG.md`](./RULE_CATALOG.md) for every one.
 2. **Facets** — a WCAG SC is usually bigger than any one rule can decide deterministically. Internally, each SC is broken into named "facets" (e.g. 1.1.1 Non-text Content has facets like `img-alt-attr-present`, `text-alternative-quality`, `decorative-null`) tracked in `src/coverage/wcag-facets.js`, each marked `full` (a rule decides it with high confidence), `partial` (a rule decides *part* of it — see each rule's own scope notes), or `manual` (no safe automated heuristic exists at all). Run `npm run coverage` to regenerate `coverage/coverage-report.md`, the per-SC facet breakdown.
-3. **Composite (WCAG-SC rollup) rules** (`rulesResults[]`) — a generated aggregate of every atomic rule mapped to one SC, giving you one pass/fail/cantTell/notApplicable verdict per SC instead of having to roll up dozens of atomic results yourself. See [`RULE_CATALOG.md`](./RULE_CATALOG.md#composite-wcag-sc-rollup-rules-33) for the full list (e.g. `wcag-1.1.1-non-text-content` rolls up 22 atomic rules).
+3. **Composite (WCAG-SC rollup) rules** (`rulesResults[]`) — a generated aggregate of every atomic rule mapped to one SC, giving you one pass/fail/cantTell/notApplicable verdict per SC instead of having to roll up dozens of atomic results yourself. See the composite section of [`RULE_CATALOG.md`](./RULE_CATALOG.md) for the full list (e.g. `wcag-1.1.1-non-text-content` rolls up 22 atomic rules).
 
 ## How a composite's outcome is computed
 
@@ -37,6 +37,8 @@ carries one level tag per Success Criterion it maps to, and nothing more: a rule
 mapped only to an AA criterion is tagged `wcag2aa` and *not* `wcag2a`. Asking for
 `{ tags: ['wcag2aa'] }` on its own therefore runs the 10 rules mapped to a 2.0 AA
 criterion, not the ~100 that make up an A + AA target. List every level you mean.
+`engineOptions.profile` (`wcag22-aa`, `en301549-v4.1.1`, `en301549-v3.2.1`, `section508`) does
+this for you; see [`ENGINE_OPTIONS.md`](./ENGINE_OPTIONS.md#conformance-profiles).
 
 The same applies across WCAG versions — a criterion introduced in 2.1 or 2.2 carries
 only its own origin tag — so a full conformance target is a union of tag sets. See
@@ -61,12 +63,63 @@ you need the exact precedence.
 Omit `tags` entirely (the default) and every rule at every level runs, with no composite
 suppression.
 
+## EN 301 549
+
+Chapter 9 of EN 301 549 restates the WCAG Level A and AA Success Criteria as clauses numbered `9.` plus the criterion's own number: WCAG 1.4.3 is clause 9.1.4.3. When a scan asks for them, every atomic and composite result carries, after its WCAG entries in `meta.normativeMappings`, the clause for each of its criteria, once per version of the standard that includes that criterion. A scan asks with `engineOptions.mappings: ['en301549']` (both versions) or `['en301549:V3.2.1']` (one), or by targeting an EN 301 549 profile, which adds the version it names; by default results name WCAG only (see [`ENGINE_OPTIONS.md`](./ENGINE_OPTIONS.md#other-standards-mappings)):
+
+| Version | Built on | Differs from the other in |
+|---|---|---|
+| V3.2.1 (2021-03) | WCAG 2.1 A and AA, 50 criteria | Includes 9.4.1.1 Parsing |
+| V4.1.1 (2026-09) | WCAG 2.2 A and AA, 55 criteria | Adds 2.4.11, 2.5.7, 2.5.8, 3.2.6, 3.3.7, 3.3.8; 9.4.1.1 is void |
+
+Each clause entry also names the criterion it restates, as `wcagSc: ["1.4.3"]`, so a view grouped by criterion (JUnit's suites, the HTML report's rollup) puts it under the right one even on a rule mapped to several.
+
+AAA criteria have no clause in either version. The table lives in `src/coverage/en301549-map.js`, taken from the ETSI text; rules never declare these entries themselves, the build derives them from each rule's WCAG mapping. A rule added through `engineOptions.customRules` keeps exactly the mappings it declares. The catalogs name the clauses under the same options: `getChecksCatalog({ mappings: ['en301549'] })` in each entry's `normativeMappings`, and composite entries returned by `getRulesCatalog({ mappings: ['en301549'] })` as `meta.standardMappings`, so the clauses a criterion maps to can be read without running a scan. Called with no options, they name WCAG only, as a result does.
+
+The table is public as `@surea11y/core/en301549`, for tools that need the reverse view, such as which criteria a version requires that a scan did not cover:
+
+```js
+const { EN301549_CLAUSES, en301549ClausesForSc } = require('@surea11y/core/en301549');
+
+Object.keys(EN301549_CLAUSES['V3.2.1']);  // the 50 WCAG 2.1 A and AA criteria V3.2.1 restates
+en301549ClausesForSc('2.5.8');            // [{ version: 'V4.1.1', clause: '9.2.5.8', title: 'Target size (minimum)' }]
+```
+
+This is a correspondence between two published documents, not a conformance claim: a clause on a result says which EN 301 549 requirement that WCAG criterion is, nothing more. Which version a given law requires is outside the engine.
+
+## Adding another standard
+
+EN 301 549 is an entry in a registry, `src/coverage/standards.js`. The build, the runner, the rule catalog and the reporters read it, so a new standard goes the same way. Where its entry lives depends on the standard:
+
+- A standard that restates WCAG one criterion at a time, as EN 301 549 does, only renumbers WCAG's verdicts. Its table goes in `src/coverage/<name>-map.js` and its entry in `NORMATIVE_STANDARDS`, next to EN 301 549's.
+- A standard with verdicts of its own is a **profile**: a folder under `profiles/` holding its entry, its tables, and the scripts and tests that go with them, listed in `profiles/index.js`. The registry appends each profile's entry after its own. `npm run profile:new -- <key>` creates one, working and empty, to fill in. See [`profiles/README.md`](../profiles/README.md) for the layout.
+
+Either way, the entry needs:
+
+1. A table taken from the published text, with a function that returns a rule's entries given the rule's id and WCAG criteria. Each entry is `{ standard, version, requirement, title, wcagSc }`, where `wcagSc` lists the WCAG criteria that requirement corresponds to. A standard that restates WCAG derives its entries from the criteria. One organised differently looks the rule up by id, in a table of the rules it maps.
+2. Its `key` (what `engineOptions.mappings` accepts, and the SARIF tag prefix and JUnit property name), its `standard` (the name its entries carry and the report shows), its `versions`, and that function as `mappingsFor`.
+
+The rest is optional, and the comment at the top of the registry describes each field:
+
+- `profiles`: named conformance targets. Each gives the WCAG tags it runs and the version it targets, and switches that version's mappings on. With `mappedRules: true` it also runs every rule the standard maps, which matters when the standard requires things WCAG leaves to best practice. With `exclude: { rules, criteria }` it leaves rules out: the rules it names, and the WCAG criteria a standard narrower than WCAG waives (their WCAG rollups, and every rule that checks nothing else). The build refuses an unknown rule or criterion, and a rule the profile both maps and excludes. A standard that replaces a WCAG check with a stricter one of its own excludes the WCAG rule and maps its own.
+- `ruleTag`: a tag for rules that check requirements only this standard makes. Another standard may not map them or derive variants from them; the build refuses it, so standards stay independent of each other, and a rule two of them need belongs in core. These rules are opt-in (see [`RULE_AUTHORING.md`](./RULE_AUTHORING.md)), so a WCAG scan never runs them. In a profile, they go in its `rules/` folder, which its `index.js` exports as `rulesDir`.
+- `ruleMapped: true`: the entries come from each rule rather than from its WCAG criterion, so a WCAG rollup names only the entries of the rules that decided its outcome. A standard mapped that way for some requirements and restating WCAG for others lists the prefixes of the restating ones in `restatedPrefixes` (`['A.']`): a rollup names those whatever decided it, as it names EN 301 549's.
+- `composites()`: rollups of the standard's own, such as one per requirement. They carry the rule tag, so only a run that asks for the standard produces them, and the HTML report shows them in a section of their own.
+- `report`: the dictionary key of the note above that section (`noteKey`), and the language of the rollup titles when it is not the scan's (`titleLang`).
+- `validate(rules)`: checks the standard's own tables against the rules that exist. The build fails on any problem it returns.
+
+A standard built on a WCAG version reads that version from `@surea11y/core/wcag` (`src/wcag.js`) rather than keeping its own copy: `wcagCriteria('2.1', { levels: ['A', 'AA'] })` lists the criteria in force in 2.1 with their 2.1 titles and levels (4.1.1 Parsing is Level A there, and gone in 2.2), `wcagCriterion(sc, version)` looks one up, and `wcagTags('2.1')` gives the rule tags a profile on 2.1 A and AA selects, as EN 301 549's profiles do. It is the one core module a profile's own tables may require (see [`profiles/README.md`](../profiles/README.md#what-a-profile-may-use)).
+
+`tests/coverage/standards.test.js` holds every registered standard to the contract. What stays per standard is its table, its tests, its rules, and a public export if tools need the reverse view, as `@surea11y/core/en301549` does.
+
+A standard is compiled into the engine. At run time, a custom rule (`engineOptions.customRules`) can name any standard in its own `normativeMappings`, and the result keeps those entries as written, but only registered standards get a profile, a `mappings` switch, opt-in rules, rollups, or a place in SARIF, JUnit and the HTML report.
+
 ## What this engine cannot tell you
 
 No automated tool — this one included — can certify full WCAG conformance. That's not a limitation specific to surea11y; it's inherent to WCAG itself; a meaningful fraction of Success Criteria require human judgment (is this alt text *accurate*, not just *present*; is this error message *understandable*) or dynamic testing this engine's static-DOM-scan architecture cannot do at all (keyboard-trap detection, real layout/reflow at zoom). See [`LIMITATIONS.md`](./LIMITATIONS.md) for the full, explicit list of what's out of scope and why.
 
 What surea11y *can* give you, honestly:
-- Every `fail` is a real, deterministic, normative violation under the version you targeted — never a guess.
+- Every `fail` is a real, deterministic, normative violation of the standard and version you targeted — never a guess. By default that standard is WCAG: a rule for a requirement only another standard makes (a rule for a national standard's own requirement, say) is opt-in and runs only when you target that standard ([`ENGINE_OPTIONS.md`](./ENGINE_OPTIONS.md#opt-in-rules)), so a WCAG scan never fails a page for something WCAG does not require. The one exception is a run that asks for every rule (`engineOptions.optInRules`): it targets no single standard, and says so in `engine.optInRules`.
 - Every `cantTell` is an explicit flag for human review, not a swallowed uncertainty.
 - The facet coverage table tells you exactly which parts of which SCs have zero automated coverage, so you know where a `pass` is silent rather than exhaustive.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@surea11y/core",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "Deterministic WCAG 2.2 accessibility engine that tells you what it can't tell you. Zero dependencies.",
   "keywords": [
     "accessibility",
@@ -14,6 +14,7 @@
     "aria",
     "contrast",
     "sarif",
+    "junit",
     "zero-dependencies",
     "jsdom",
     "playwright",
@@ -30,7 +31,10 @@
     "./baseline": "./src/baseline.js",
     "./report": "./src/report.js",
     "./sarif": "./src/sarif.js",
+    "./junit": "./src/junit.js",
     "./earl": "./src/earl.js",
+    "./en301549": "./src/en301549.js",
+    "./wcag": "./src/wcag.js",
     "./browser": "./surea11y.browser.js",
     "./i18n/*": "./surea11y.i18n.*.js",
     "./package.json": "./package.json"
@@ -41,7 +45,7 @@
     "type": "git",
     "url": "git+https://github.com/SureA11y/core.git"
   },
-  "homepage": "https://github.com/SureA11y/core#readme",
+  "homepage": "https://surea11y.dev/",
   "bugs": {
     "url": "https://github.com/SureA11y/core/issues"
   },
@@ -57,7 +61,18 @@
     "src/baseline.js",
     "src/report.js",
     "src/sarif.js",
+    "src/junit.js",
     "src/earl.js",
+    "src/en301549.js",
+    "src/coverage/en301549-map.js",
+    "src/coverage/standards.js",
+    "src/wcag.js",
+    "src/profile-kit.js",
+    "src/coverage/wcag-facets.js",
+    "src/coverage/wcag-version-map.js",
+    "profiles/index.js",
+    "profiles/*/*.js",
+    "profiles/*/rules/**/*.js",
     "src/checks/**/*.js",
     "surea11y.browser.js",
     "surea11y.i18n.*.js",
@@ -73,29 +88,37 @@
   "scripts": {
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
-    "format": "prettier --write \"src/**/*.js\" \"scripts/**/*.js\" \"tests/**/*.js\" \"eslint.config.js\"",
-    "format:check": "prettier --check \"src/**/*.js\" \"scripts/**/*.js\" \"tests/**/*.js\" \"eslint.config.js\"",
+    "format": "prettier --write \"src/**/*.js\" \"scripts/**/*.js\" \"tests/**/*.js\" \"profiles/**/*.js\" \"eslint.config.js\"",
+    "format:check": "prettier --check \"src/**/*.js\" \"scripts/**/*.js\" \"tests/**/*.js\" \"profiles/**/*.js\" \"eslint.config.js\"",
     "build": "node scripts/build-core.js && node scripts/build-browser.js",
     "pretest": "playwright install chromium",
     "test": "npm run lint && npm run format:check && npm run build && npm run validate:rules && node scripts/run-tests.js",
-    "test:coverage": "npm run build && node scripts/run-tests.js --experimental-test-coverage --test-coverage-include=src/**/*.js",
+    "test:coverage": "npm run build && node scripts/run-tests.js --experimental-test-coverage --test-coverage-include=src/**/*.js --test-coverage-include=profiles/**/*.js",
     "test:contrast-helpers": "node tests/contrast-helpers.test.js",
     "helpers-perf-bench": "node --expose-gc scripts/dom-helpers-perf-bench.js",
     "engine-perf-bench": "node --expose-gc scripts/engine-perf-bench.js  --profileRules=true --iters=25 --top=15",
     "engine-perf-bench-transparent": "node --expose-gc scripts/engine-perf-bench.js --profileRules=true --top=15 --iters=25 --generated=contrastTransparent",
     "engine-perf-bench-opaque": "node --expose-gc scripts/engine-perf-bench.js --profileRules=true --top=15 --iters=25 --generated=contrastOpaque",
     "test:typography-helpers": "node tests/contrast-typography.test.js",
-    "coverage": "node scripts/generate-wcag-coverage.js --rulesDir src/checks",
-    "coverage:strict": "node scripts/generate-wcag-coverage.js --rulesDir src/checks --strictFacets",
-    "coverage:check": "node scripts/generate-wcag-coverage.js --rulesDir src/checks --check",
+    "coverage": "node scripts/generate-wcag-coverage.js",
+    "coverage:strict": "node scripts/generate-wcag-coverage.js --strictFacets",
+    "coverage:check": "node scripts/generate-wcag-coverage.js --check",
     "finding-ids": "npm run build && node scripts/generate-finding-ids.js",
+    "finding-ids:release": "node scripts/freeze-finding-ids.js",
     "fixtures:index": "node scripts/generate-fixture-index.js",
     "fixtures:check": "node scripts/generate-fixture-index.js --check",
+    "fixtures:markers": "npm run build && node scripts/generate-fixture-markers.js",
+    "fixtures:markers:check": "npm run build && node scripts/generate-fixture-markers.js --check",
     "docs:rule-catalog": "npm run build && node scripts/generate-rule-catalog.js",
-    "validate:automatic-rules": "npm run build && node scripts/validate-all-rules.js src/checks/automatic",
-    "validate:manual-rules": "npm run build && node scripts/validate-all-rules.js src/checks/manual",
-    "validate:rules": "npm run build && node scripts/validate-all-rules.js src/checks/automatic src/checks/manual",
+    "docs:rule-catalog:check": "npm run build && node scripts/generate-rule-catalog.js --check",
+    "rule-examples:coverage": "npm run build && node scripts/generate-rule-examples-coverage.js",
+    "rule-examples:coverage:check": "npm run build && node scripts/generate-rule-examples-coverage.js --check",
+    "docs:rule-review": "npm run build && node scripts/generate-rule-review.js",
+    "validate:automatic-rules": "npm run build && node scripts/validate-all-rules.js src/checks/automatic profiles/*/rules/automatic",
+    "validate:manual-rules": "npm run build && node scripts/validate-all-rules.js src/checks/manual profiles/*/rules/manual",
+    "validate:rules": "npm run build && node scripts/validate-all-rules.js",
     "i18n:new": "node scripts/i18n-scaffold.js",
+    "profile:new": "node scripts/profile-new.js",
     "i18n:sync": "node scripts/i18n-sync.js",
     "i18n:check": "node scripts/i18n-sync.js --check",
     "i18n:report": "node scripts/i18n-report.js"

package/profiles/index.js

@@ -0,0 +1,14 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
+'use strict';
+
+/**
+ * The profiles built into the engine, in registry order. Each one is a
+ * standard whose verdicts are not WCAG's renumbered (see profiles/README.md),
+ * and exports `standard`, its registry entry, which src/coverage/standards.js
+ * appends after the standards core keeps for itself, `rulesDir`, the folder
+ * of its own rules, which the build compiles with core's, and `i18nDir`, the
+ * folder of its dictionaries, which the build adds to core's.
+ */
+
+module.exports = [];

package/src/checks/automatic/area-alt-present.js

@@ -11,19 +11,30 @@
  * @applicability
  *   Applies to <area> elements that:
  *   1) are in a <map> that is referenced by an <img usemap>, AND
- *   2) the referencing <img> is eligible in the accessibility tree (best-effort), AND
- *   3) the <area> itself is eligible in the accessibility tree (with engine exceptions).
+ *   2) carry a non-empty href (an <area> with no href is not a hyperlink
+ *      at all per the HTML spec, and has nothing for this rule to name), AND
+ *   3) the referencing <img> is actually rendered (hidden/display:none/
+ *      visibility exclude it; aria-hidden does not, since <area> is not a
+ *      DOM descendant of <img>), AND
+ *   4) the <area> itself is eligible in the accessibility tree. hidden,
+ *      display:none and inert on the <area> or its <map> do not exclude it:
+ *      neither element generates a box, so a real browser's image-map
+ *      hit-testing ignores all three there (verified against Chromium and
+ *      Firefox); only those mechanisms on a genuine ancestor of the whole
+ *      <img>+<map> pairing do.
  * @expectation
- *   Each applicable <area> element has an alt attribute.
- *   The alt attribute may be empty (alt="").
+ *   Each applicable <area> element has a non-empty accessible name, from alt,
+ *   aria-label/aria-labelledby, or title. An <area> in a used map is always
+ *   a link, so alt="" is not decorative here as it is on <img>: an empty alt
+ *   fails the same as a missing one unless another mechanism names it.
  */
 
 const id = 'area-alt-present';
 
 const meta = {
-  title: '<area> must have an alt attribute',
+  title: '<area> must have an accessible name',
   description:
-    'Checks that <area> elements provide an alt attribute to support a text alternative mechanism.',
+    'Checks that <area> elements have a non-empty accessible name via alt, aria-label/aria-labelledby, or title.',
   i18n: {
     titleKey: 'area_altPresent_title',
     descriptionKey: 'area_altPresent_description'
@@ -76,6 +87,11 @@ function runInPage(ctx) {
   const isAccTreeEligible =
     helpers && typeof helpers.isAccTreeEligible === 'function' ? helpers.isAccTreeEligible : null;
 
+  const isDomVisibleEligible =
+    helpers && typeof helpers.isDomVisibleEligible === 'function'
+      ? helpers.isDomVisibleEligible
+      : null;
+
   const getAriaNameInfo =
     helpers && typeof helpers.getAriaNameInfo === 'function' ? helpers.getAriaNameInfo : null;
 
@@ -156,17 +172,32 @@ function runInPage(ctx) {
     const img = getReferencingImgForArea(el);
     if (!img) continue;
 
-    // 1) The referencing <img> must itself be eligible in the acc tree.
-    // This is the "visibility of map/area doesn't matter; the image does" policy.
-    if (isAccTreeEligible) {
-      const imgElig = (() => {
+    // 0b) Without href an <area> is not a hyperlink at all per the HTML
+    // spec -- just a shape with no associated action -- so it has nothing
+    // for this rule to name.
+    const hrefRaw = el.getAttribute('href');
+    if (!hrefRaw || !hrefRaw.trim()) continue;
+
+    // 1) The referencing <img> must actually be rendered: a used map's
+    // hotspots depend on the img's box, not its accessibility-tree
+    // exposure. <area> is not a DOM descendant of <img> -- only linked by
+    // the usemap IDREF -- so aria-hidden on the img has nothing to
+    // propagate along (verified against Chromium and Firefox: the area
+    // stays reachable regardless). hidden/display:none/visibility on the
+    // img itself still excludes it, since that removes the box the
+    // hotspot geometry depends on.
+    if (isDomVisibleEligible) {
+      const imgVis = (() => {
         try {
-          return isAccTreeEligible(img, ctx);
+          return isDomVisibleEligible(img, ctx, {
+            visibilityMode: 'styleOnly',
+            disableGeometry: true
+          });
         } catch {
           return { eligible: true, reasons: [] };
         }
       })();
-      if (imgElig && imgElig.eligible === false) continue;
+      if (imgVis && imgVis.eligible === false) continue;
     }
 
     // 2) The <area> itself must be eligible (aria-hidden/inert exceptions handled by helper).
@@ -184,8 +215,18 @@ function runInPage(ctx) {
     // From here: applicable
     applicableCount += 1;
 
-    const hasAlt = el.getAttribute('alt') !== null;
-    if (hasAlt) continue;
+    let altRaw;
+    try {
+      altRaw = el.getAttribute('alt');
+    } catch {
+      altRaw = null;
+    }
+    const hasAltAttr = altRaw !== null;
+    const altGivesName = hasAltAttr && String(altRaw).trim() !== '';
+    if (altGivesName) continue;
+
+    // alt="" is not decorative on an <area>: a used map's area is always a
+    // link, so it needs a name from elsewhere or it fails.
 
     // aria-label / aria-labelledby is also a valid, standards-recognized
     // text-alternative mechanism for <area> (HTML-AAM accessible name
@@ -201,8 +242,8 @@ function runInPage(ctx) {
     }
 
     // A non-empty title attribute is HTML-AAM's own next fallback naming
-    // source once alt is entirely absent. Same gap img-alt-present handles
-    // for <img title="..."> with no alt.
+    // source once alt gives no name (missing or empty). Same gap
+    // img-alt-present handles for <img title="..."> with no alt.
     const titleRaw = (() => {
       try {
         return el.getAttribute('title');
@@ -214,21 +255,36 @@ function runInPage(ctx) {
 
     const eligInfo = getEligibilityInfo ? getEligibilityInfo(el, ctx, { targetSet: 'acc' }) : null;
 
-    const baseOccurrence = {
-      // Leave selector/html empty so the engine can fill them from __node.
-      selector: '',
-      html: '',
-      summary: 'Missing alt attribute on &lt;area&gt;.',
-      hint: 'Add an alt attribute (use alt="" only for decorative areas).',
-      i18n: {
-        summaryKey: 'area_altPresent_summary_fail',
-        hintKey: 'area_altPresent_hint_fail',
-        params: { element: 'area' }
-      },
-      data: {
-        visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] }
-      }
-    };
+    const baseOccurrence = hasAltAttr
+      ? {
+          // Leave selector/html empty so the engine can fill them from __node.
+          selector: '',
+          html: '',
+          summary: 'Empty alt attribute leaves &lt;area&gt; link with no accessible name.',
+          hint: 'Describe the link destination in alt, or add aria-label/aria-labelledby (an <area> cannot be decorative once its map is used).',
+          i18n: {
+            summaryKey: 'area_altPresent_summary_fail_empty',
+            hintKey: 'area_altPresent_hint_fail_empty',
+            params: { element: 'area' }
+          },
+          data: {
+            visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] }
+          }
+        }
+      : {
+          selector: '',
+          html: '',
+          summary: 'Missing alt attribute on &lt;area&gt;.',
+          hint: 'Add an alt attribute describing the link destination (an <area> cannot be decorative).',
+          i18n: {
+            summaryKey: 'area_altPresent_summary_fail',
+            hintKey: 'area_altPresent_hint_fail',
+            params: { element: 'area' }
+          },
+          data: {
+            visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] }
+          }
+        };
 
     if (helpers && typeof helpers.reportOccurrence === 'function') {
       occurrences.push(helpers.reportOccurrence(el, baseOccurrence));

package/src/checks/automatic/aria-braille-equivalent.js

@@ -113,13 +113,28 @@ function runInPage(ctx) {
         nameInfo && typeof nameInfo.value === 'string' ? nameInfo.value : ''
       );
       const name = programmaticName || getConservativeSubtreeText(el);
-      if (!name) missing.push({ attr: 'aria-braillelabel', requires: 'an accessible name' });
+      if (!name)
+        missing.push({
+          attr: 'aria-braillelabel',
+          requires: 'an accessible name',
+          messageKey: 'label',
+          summary:
+            'This element has aria-braillelabel but no accessible name, its non-braille equivalent.',
+          hint: 'aria-braillelabel is a Braille-specific supplement, not a replacement, so also give the element an accessible name (for example visible text, aria-label or aria-labelledby).'
+        });
     }
 
     if (brailleRoleDesc) {
       const roleDesc = trim(el.getAttribute('aria-roledescription'));
       if (!roleDesc)
-        missing.push({ attr: 'aria-brailleroledescription', requires: 'aria-roledescription' });
+        missing.push({
+          attr: 'aria-brailleroledescription',
+          requires: 'aria-roledescription',
+          messageKey: 'roleDescription',
+          summary:
+            'This element has aria-brailleroledescription but not aria-roledescription, its non-braille equivalent.',
+          hint: 'aria-brailleroledescription is a Braille-specific supplement, not a replacement, so also provide aria-roledescription.'
+        });
     }
 
     if (!missing.length) continue;
@@ -129,12 +144,15 @@ function runInPage(ctx) {
     for (const m of missing) {
       occurrences.push(
         helpers.reportOccurrence(el, {
-          summary: `This element has ${m.attr} but no ${m.requires}, its non-braille equivalent.`,
-          hint: `${m.attr} is a Braille-specific supplement, not a replacement, so also provide ${m.requires}.`,
+          // One message per missing equivalent rather than a shared template:
+          // `requires` is English prose for the label case, and interpolating
+          // it put English into every translated sentence.
+          summary: m.summary,
+          hint: m.hint,
           i18n: {
-            summaryKey: 'ariaBrailleEquivalent_summary_fail',
-            hintKey: 'ariaBrailleEquivalent_hint_fail',
-            params: { element: tag, attr: m.attr, requires: m.requires }
+            summaryKey: `ariaBrailleEquivalent_summary_fail_${m.messageKey}`,
+            hintKey: `ariaBrailleEquivalent_hint_fail_${m.messageKey}`,
+            params: { element: tag, attr: m.attr }
           },
           uncertainty: {
             code: 'spec-only',