@surea11y/core 1.7.0 → 1.8.1

package/docs/I18N.md

@@ -4,16 +4,23 @@ Every rule's title/description, and every occurrence's summary/hint, is localize
 
 ## Current locale coverage
 
-| Locale | File | Keys | Values still in English |
+| Locale | Files | Keys | Values identical to English |
 |---|---|---|---|
-| `en` (English) | `src/i18n/en.json` | 666 | — (the canonical/fallback set) |
-| `fr` (French) | `src/i18n/fr.json` | 666 | 1 |
-| `de` (German) | `src/i18n/de.json` | 666 | 0 |
-| `es` (Spanish) | `src/i18n/es.json` | 666 | 0 |
+| `en` (English) | `src/i18n/en.json` | 841 | — (the canonical/fallback set) |
+| `fr` (French) | `src/i18n/fr.json` | 841 | 3 — *Orientation*, *Interruptions*, *Occurrences*, which are the same words in French |
+| `de` (German) | `src/i18n/de.json` | 841 | 0 |
+| `es` (Spanish) | `src/i18n/es.json` | 841 | 2 — *Selector*, the same word in Spanish |
+| `ja` (Japanese) | `src/i18n/ja.json` | 841 | 0 |
+
+The last column is what `npm run i18n:report` measures: values that match the English text character for character. That catches a key nobody has translated yet, but it also counts a word that is simply the same in both languages, and it cannot see an English word left inside an otherwise translated sentence. Those are found by reading the text; none remain in the locales above.
 
 Locale files are plain JSON: a flat map of key to translated string, in the same key order as `en.json`. Nothing else lives in them, so contributing a language means editing text and never touching code.
 
-Every locale carries every key `en.json` has. Keeping it that way is the job of `npm run i18n:sync`: run it after any change to `en.json` and it rewrites every non-English locale file to match — adding keys that are new, dropping keys `en.json` no longer has, and leaving existing translations alone. A key it adds is seeded with the English text, which counts as untranslated until someone replaces it.
+A locale's text may be split between several files. `src/i18n/<locale>.json` holds the engine's own messages; a profile's `profiles/<key>/i18n/<locale>.json` holds those of its rules (see [`profiles/README.md`](../profiles/README.md)). Each file is synced against the `en.json` next to it, and the build merges them into one dictionary per locale. A key lives in exactly one of them: the build fails if two files define it.
+
+A profile chooses its languages: the locale files in its `i18n/` folder are the list. It always has `en.json`; a locale core has and the profile does not shows that profile's messages in English, as the engine does for any key a locale lacks. Because the profile chose it, `engine.locale.reason` stays `ok`: the build records the keys each locale leaves out that way, and only a key missing otherwise makes it `partial-dictionary`. Core's own messages are never left out by choice, so a locale only a profile has is reported as `partial-dictionary`.
+
+Every locale file carries every key the `en.json` next to it has. Keeping it that way is the job of `npm run i18n:sync`: run it after any change to `en.json` and it rewrites every non-English locale file to match — adding keys that are new, dropping keys `en.json` no longer has, and leaving existing translations alone. A key it adds is seeded with the English text, which counts as untranslated until someone replaces it.
 
 Forget to run it and the build fails: `tests/i18n-sync.test.js` and `tests/i18n/i18n-locale-completeness.test.js` reject a missing key, an orphaned key, or any file that `i18n:sync` would rewrite. `npm run i18n:check` reports the same thing without touching the files, and `npm run i18n:report` prints per-locale coverage.
 
@@ -55,7 +62,7 @@ Graceful fallback has one drawback: ask for a language the build doesn't carry a
 "engine": {
   "tag": "a11ycore",
   "schemaVersion": "1.0.0",
-  "locale": { "requested": "ja", "resolved": "en", "reason": "unknown-locale" }
+  "locale": { "requested": "ko", "resolved": "en", "reason": "unknown-locale" }
 }
 ```
 
@@ -66,8 +73,8 @@ Graceful fallback has one drawback: ask for a language the build doesn't carry a
 | `ok` | You got exactly what you asked for, and that dictionary carries every key. |
 | `primary-subtag` | Your code carried a subtag with no dictionary of its own, so its base language was used — you asked for `de-DE` and got `de`. Normal and expected; nothing to fix. A difference in case alone is not this: `DE` reports `ok`. |
 | `dictionary-not-loaded` | The project ships that language, but this copy of the engine doesn't carry it and none was supplied. In practice: the standalone browser bundle without its locale side file. |
-| `unknown-locale` | The project has no such translation at all, so English was used. `ja` and `pt-BR` both land here today. |
-| `partial-dictionary` | The dictionary was used but is missing some keys, so those individual strings fell back to English. |
+| `unknown-locale` | The project has no such translation at all, so English was used. `ko` and `pt-BR` both land here today. |
+| `partial-dictionary` | The dictionary was used but is missing some keys, so those individual strings fell back to English. A profile's messages in a language the profile does not offer also show in English, but do not count here. |
 
 Treat the list as open — a later release can add a value, so match on the ones you care about and let the rest fall through a default.
 
@@ -83,11 +90,14 @@ Which languages are available depends on how you load the engine.
 | A binding (Playwright, Cypress, …) | Every locale, built in. Nothing to configure. |
 | `surea11y.browser.js` in a `<script>` tag | English. Load `surea11y.i18n.<locale>.js` after it for anything else. |
 
-The bundle is split because it travels over the network to every page that uses it, and no page needs all four languages. Keeping English inline and the rest optional took about 280 KB off the download and stops it growing as languages are added. Nothing else changes: the Node package and the bindings are unaffected.
+The bundle is split because it travels over the network to every page that uses it, and no page needs every language. Keeping English inline and the rest optional took about 280 KB off the download and stops it growing as languages are added. Nothing else changes: the Node package and the bindings are unaffected.
 
 ```html
 <script src="surea11y.browser.js"></script>
-<script src="surea11y.i18n.de.js"></script>
+<script src="surea11y.i18n.ja.js"></script>
+<script>
+  const result = a11ycore.runa11yCoreInPage(location.href, null, { locale: 'ja' }, null);
+</script>
 ```
 
 Ask for a language whose file you didn't load and you get English, with `engine.locale.reason` set to `dictionary-not-loaded` — different from `unknown-locale`, which means the project has no such translation at all.
@@ -105,11 +115,35 @@ runDomRulesInPage(url, null, {
 
 Keys you don't supply fall back normally, so a partial override is fine.
 
+## Notes on individual locales
+
+**Japanese (`ja`).** Terms that WCAG 2.2 defines follow the Japanese translation published by WAIC (Web Accessibility Infrastructure Committee): 達成基準 for success criterion, アクセシブルな名前 for accessible name, テキストによる代替 for text alternative, 支援技術 for assistive technology, and the WAIC names for the criteria themselves, such as ラベルを含む名前 (name), コントラスト (最低限) and ターゲットのサイズ (最低限). Messages use the です/ます style, and hints ask for a fix with 〜してください. A few conventions worth keeping when you edit it:
+
+- Where an English title says *should*, the Japanese one ends in 〜が望ましい (or says 推奨), and *(manual review)* becomes (手動確認). A title that says *must* is phrased as a requirement. Keep that split: it is how a reader tells advisory findings from confirmed failures.
+- A `cantTell` summary says what a person has to decide, usually ending in 人による確認が必要です or in a sentence stating what could not be determined. It never reads as a failure.
+- A `pass` message describes the check that ran (計算できたすべてのテキストが…基準値を満たしています), not the page. Nothing in the dictionary claims conformance.
+- Quoted page content uses 「…」, so `{{name}}` becomes 「{{name}}」. Code keeps its ASCII quotes: `alt=""`, `role="img"`.
+- Rule descriptions quote the phrases a rule matches in both languages (「こちら」、"click here"), since the rules recognize both.
+
+Some parameter values are CSS or attribute vocabulary and are interpolated as-is in every locale: `{{fontWeightLabel}}` (`bold`, `700`), `{{labelSource}}` and `{{nameMechanism}}` (`aria-label`, `title`).
+
+## Language-specific matching
+
+Five rules judge text by known phrases, so they carry word lists as well as messages: `link-name-quality` ("click here", 「こちら」), `heading-quality` ("Untitled", 「見出し」), `form-control-label-quality` ("Label", 「入力欄」), `page-title-patterns` ("Home", 「トップページ」) and `media-alternative-transcript-evidence` ("transcript", 「文字起こし」). Each list covers `en`, `de`, `es`, `fr` and `ja`.
+
+English is always checked. The list for the element's own language, taken from the nearest `lang` attribute (the `<html>` element's for a page title), is added on top. Checking every list everywhere would flag words that are generic in one language and a real name in another, such as "Suite" or "Plus" on an English page. Transcript words are the exception: they are distinctive in every language and a page can link a transcript in another language, so all of them are always checked. Text is NFKC-normalized first, so full-width forms such as 「見出し２」 match.
+
+`page-title-patterns` also counts each Chinese, Japanese or Korean character as two when deciding whether a title is too short, since 「お問い合わせ」 is a complete title in six characters.
+
+Adding a language means adding its words to these lists as well as translating its dictionary.
+
 ## Where keys are used
 
 Two independent key namespaces, both resolved the same way:
 
 - **Rule-level**: `meta.i18n.titleKey` / `meta.i18n.descriptionKey` — resolve a rule's `title`/`description` on every `checksResults[]` entry.
+- **HTML report**: the `report_*` keys label the page `@surea11y/core/report` renders — headings, table columns, outcome and severity names, the headline, the pager. The report reads them in the locale the scan resolved to, so translating a dictionary translates the report too.
+- **Composite-level**: `meta.titleKey` / `meta.descriptionKey` in `src/catalogs/composites.wcag.js` — resolve each `rulesResults[]` rollup's `title`/`description`. The catalog's own `title`/`description` must match the English value, which `tests/i18n/i18n-composite-titles.test.js` checks. Titles use each language's published name for the success criterion.
 - **Occurrence-level**: `i18n.summaryKey` / `i18n.hintKey`, with `i18n.params` for `{{placeholder}}` interpolation — resolve an occurrence's `summary`/`hint`. See [`OUTPUT_SCHEMA.md`](./OUTPUT_SCHEMA.md#an-occurrence-occurrencesi).
 
 Both are included in the result alongside the already-resolved text, so you can re-render in a different locale from a saved result without re-scanning — see the `i18n` field's presence in `OUTPUT_SCHEMA.md`.
@@ -132,10 +166,18 @@ npm install
 npm run i18n:new pt-BR
 ```
 
-That writes `src/i18n/pt-BR.json` containing every key `en.json` has, in the same order, each seeded with the English text as a placeholder. **Use the shortest code that identifies the language** — `pt`, `nl`, `pl`. A file named `pt.json` serves everyone who asks for `pt`, `pt-BR` or `pt-PT`, because a code with a subtag falls back to its base language. Name it `pt-BR.json` and only people who ask for exactly that get it; `pt` speakers elsewhere fall through to English.
+That writes `src/i18n/pt-BR.json`, containing every key `en.json` has, in the same order, seeded with the English text as a placeholder. **Use the shortest code that identifies the language** — `pt`, `nl`, `pl`. A file named `pt.json` serves everyone who asks for `pt`, `pt-BR` or `pt-PT`, because a code with a subtag falls back to its base language. Name it `pt-BR.json` and only people who ask for exactly that get it; `pt` speakers elsewhere fall through to English.
 
 Add a regional file only when the wording genuinely has to differ, and add it alongside the base language rather than instead of it.
 
+A profile's messages are a file of their own, added with `--profile`:
+
+```sh
+npm run i18n:new -- pt-BR --profile <key>
+```
+
+writes `profiles/<key>/i18n/pt-BR.json` the same way. Without it, that profile's rules show in English in that locale.
+
 The command refuses to overwrite a file that already exists. To pick up work on an existing locale, edit it directly.
 
 ### 3. Translate the values
@@ -161,7 +203,7 @@ Four things to leave alone:
 
 Write for someone fixing the page, not for a specialist: say what is wrong and what to do about it. Where your language has established accessibility vocabulary (a national WCAG translation, a government standard), follow it rather than inventing terms.
 
-If a string is genuinely identical in your language, leave it. It is counted as untranslated but behaves correctly.
+If a string is genuinely identical in your language, leave it. The report counts it as identical to English, which is correct and needs no action.
 
 ### 4. Check your progress
 
@@ -169,7 +211,7 @@ If a string is genuinely identical in your language, leave it. It is counted as
 npm run i18n:report
 ```
 
-Prints, per locale, how many values differ from English, plus any missing or orphaned keys. Anything still matching the English text is reported as untranslated — that is a progress signal, not an error.
+Prints, per locale, how many values differ from English, plus any missing or orphaned keys. A value that still matches the English text is counted as not yet translated. While you work, that is your progress signal; once you are done, whatever it still counts should be words your language shares with English.
 
 You do not need every string on day one. Per-string fallback means an unfinished locale renders in your language where you have translated it and in English everywhere else, which is exactly how `fr`, `de` and `es` started. Ship what you have.
 
@@ -182,25 +224,25 @@ npm test
 
 `npm run build` also emits `surea11y.i18n.<locale>.js` for the standalone browser bundle — generated, so there is nothing for you to write.
 
-Then open a pull request touching `src/i18n/<locale>.json`, plus one row in the coverage table at the top of this file. Tell us which language and, if you use one, which national terminology standard you followed — that helps whoever reviews it later.
+Then open a pull request touching `src/i18n/<locale>.json` (and a profile's `profiles/<key>/i18n/<locale>.json` if you translated its messages too), plus one row in the coverage table at the top of this file. Tell us which language and, if you use one, which national terminology standard you followed — that helps whoever reviews it later.
 
 Once a locale is in the repository it is maintained with the rest of the engine: when a new rule adds strings, `npm run i18n:sync` seeds them in your file in English and `npm run i18n:report` shows them as outstanding.
 
 ## Maintaining the locales
 
-When you add, rename or remove a key in `src/i18n/en.json`:
+When you add, rename or remove a key in `src/i18n/en.json` or a profile's `i18n/en.json`:
 
 ```sh
 npm run i18n:sync
 ```
 
-Every other locale is rewritten to match — new keys seeded in English, removed keys dropped, existing translations untouched. The command is idempotent and prints what it changed per locale.
+Every other locale file in the same folder is rewritten to match its `en.json` — new keys seeded in English, removed keys dropped, existing translations untouched. A locale a profile has no file for is left out: it never creates one. The command is idempotent and prints what it changed per file.
 
 | Command | Does |
 |---|---|
-| `npm run i18n:new <locale>` | Create a new locale file from `en.json`. Refuses to overwrite. |
-| `npm run i18n:sync` | Bring every locale file back in line with `en.json`. Add `-- <locale>` to restrict it to one. |
+| `npm run i18n:new <locale>` | Create core's file for the locale from `src/i18n/en.json`; with `-- <locale> --profile <key>`, a profile's from its own. Refuses to overwrite. |
+| `npm run i18n:sync` | Bring every locale file back in line with its `en.json`. Add `-- <locale>` to restrict it to one. |
 | `npm run i18n:check` | Same comparison, writes nothing, exits non-zero on drift. |
-| `npm run i18n:report` | Per-locale translation coverage. |
+| `npm run i18n:report` | Translation coverage per folder and locale: core's, then each profile's for the locales it has. |
 
 `npm test` fails if a locale file has drifted, so an added key cannot reach `main` without every locale carrying it.

package/docs/JUNIT.md

@@ -0,0 +1,73 @@
+# JUnit report
+
+`@surea11y/core/junit` renders a scan result as JUnit XML, the test report format CI dashboards read natively: GitLab's merge request test widget, Azure DevOps' Tests tab, Jenkins and CircleCI.
+
+```js
+const { renderJunitReport } = require('@surea11y/core/junit');
+const { runDomRulesInPage } = require('@surea11y/core');
+
+const result = runDomRulesInPage(url, null, { profile: 'wcag22-aa' }, null);
+require('fs').writeFileSync('surea11y.junit.xml', renderJunitReport(result));
+```
+
+`renderJunitReport(result, options)` is a pure function: it returns the XML as a string and never touches the filesystem. It works just as well on a result saved as JSON earlier, such as the output of `surea11y scan <target> --json` from [`@surea11y/cli`](https://github.com/SureA11y/cli#readme) — see [`CI_INTEGRATIONS.md`](./CI_INTEGRATIONS.md#junit-test-reports).
+
+## Shape
+
+One `<testsuite>` per WCAG Success Criterion, one `<testcase>` per rule mapped to it:
+
+```xml
+<testsuites name="surea11y" tests="14" failures="2" errors="0" skipped="4" time="0">
+  <testsuite name="WCAG 1.1.1 Non-text content: text alternatives" tests="1" failures="1" errors="0" skipped="0" time="0">
+    <properties>
+      <property name="wcagCriterion" value="1.1.1"/>
+      <property name="wcagLevel" value="A"/>
+      <property name="en301549" value="9.1.1.1"/>
+      <property name="criterionOutcome" value="fail"/>
+      <property name="engine" value="a11ycore"/>
+      <property name="schemaVersion" value="1.0.0"/>
+      <property name="wcagVersion" value="2.2"/>
+      <property name="profile" value="wcag22-aa"/>
+      <property name="locale" value="en"/>
+      <property name="url" value="https://example.test/"/>
+    </properties>
+    <testcase classname="wcag-1.1.1" name="img-alt-present" time="0">
+      <failure type="fail" message="1 failing occurrence: Missing alt attribute on &lt;img&gt;.">- Missing alt attribute on &lt;img&gt;. Add an alt attribute (use alt=&quot;&quot; only for decorative images).
+  selector: html &gt; body &gt; main &gt; img
+  html: &lt;img src=&quot;a.png&quot;&gt;</failure>
+    </testcase>
+  </testsuite>
+</testsuites>
+```
+
+- **Suites follow the criterion**, because that is what people track, and **testcases follow the rule** rather than the occurrence, so a defect repeated forty times on a page is one failing test whose body lists all forty, and test counts stay stable between runs.
+- Suites come from each rule's own WCAG mappings, not from the composites, so every rule that ran is reported even when composites were excluded. The composite, when it ran, supplies the suite's title and the `criterionOutcome` property. A rule mapped to two criteria appears in both suites. A rule mapped to no criterion goes into a final `Other checks` suite with `classname="other"`.
+- The run's `engine`, `schemaVersion`, `wcagVersion`, `profile`, `optInRules` (comma-separated tags, when `engineOptions.optInRules` added rules), `locale` and `url` are repeated as properties on every suite, each only when the result has it.
+- Suites are ordered by criterion, numerically (1.4.3 before 1.4.10), and testcases by rule id.
+- `en301549` properties name the EN 301 549 clause that restates the criterion, where there is one and the scan asked for EN 301 549 clauses (see [`WCAG_CONFORMANCE.md`](./WCAG_CONFORMANCE.md#en-301-549)).
+
+## Outcomes
+
+| Rule outcome | JUnit | Why |
+|---|---|---|
+| `fail` | `<failure type="fail">`, one line per failing occurrence (message, hint, selector, markup) | The deterministic, gating case. |
+| `cantTell` | `<skipped>` saying how many occurrences need manual review | JUnit has no "could not tell". Skipped surfaces it without turning a build red, the same line SARIF draws with `warning`. |
+| `pass` | a bare `<testcase>` | |
+| `notApplicable` | left out | A page has hundreds; none says anything. `includeNotApplicable: true` adds them as `<skipped message="Not applicable">`. |
+
+A `fail` rule that also has `cantTell` occurrences reports the failures in `<failure>` and the undecided ones in `<system-out>`, where dashboards show test output. A skipped `cantTell` rule does the same.
+
+## Options
+
+| Option | Default | Effect |
+|---|---|---|
+| `cantTellAs` | `'skipped'` | `'failure'` reports `cantTell` rules as `<failure type="cantTell">`, for a pipeline that must not pass while anything is undecided. |
+| `includeNotApplicable` | `false` | Include `notApplicable` rules as skipped tests. |
+| `baselineEntries` | none | Entries from [`BASELINE.md`](./BASELINE.md)'s `buildBaselineEntries()`. Fail occurrences recorded there are dropped, exactly as in SARIF. A rule whose every failure is already known is `<skipped message="N known failures recorded in the baseline">`, not passing: it did not pass. |
+| `name` | `'surea11y'` | The `name` of the root `<testsuites>`, for telling several pages' reports apart in one dashboard. |
+
+## Determinism
+
+The engine has no clock, and this report does not invent one: every `time` is `"0"`, and a `timestamp` attribute appears on each suite only when the result carries one (`engineOptions.timestamp`). The same scan always renders byte-identical XML, so a report can be committed or diffed.
+
+Text is escaped for XML, and characters XML 1.0 forbids even when escaped (most control characters, lone surrogates) are dropped, since markup captured from a page can contain them.

package/docs/LIMITATIONS.md

@@ -17,6 +17,7 @@ surea11y is a **static DOM scan**: it reads the DOM tree and computed styles at
 - **`<dialog>` and other elements hidden by the default UA stylesheet** (no `open` attribute, `display: none` by spec), along with any other subtree hidden via `display:none`, `visibility:hidden`, `[hidden]`, or closed `<details>`, are **excluded from rule evaluation by default** — matching the visibility-aware behavior of other established engines. This is a deliberate default (`engineOptions.includeHiddenElements: false`), not an oversight: hidden content isn't reachable by assistive technology or keyboard until it's shown, so flagging a markup defect inside it by default would often be noise. Set `engineOptions.includeHiddenElements: true` to evaluate hidden/collapsed subtrees anyway — e.g. to catch a markup defect (like a broken ARIA ID reference) before a dialog ever opens. See [`ENGINE_OPTIONS.md`](./ENGINE_OPTIONS.md#engineoptions--the-rest) for the option and exactly which hiding mechanisms it covers.
 - **jsdom's computed `text-shadow` is unreliable on a second read of the same element.** Confirmed in jsdom 29.1.1: reading a computed `text-shadow` value a second time on the same element — through any accessor, from any freshly-requested `CSSStyleDeclaration` for that element, regardless of caching — silently returns a different, wrong "no shadow" value instead of the real declared one. The first read is always correct. This engine works around it internally by reading each element's `text-shadow` exactly once per run and caching the result (see `__textShadowInfoEl` in `src/core/contrast-helpers.js`), so a single scan is unaffected. It only surfaces if you read `getComputedStyle(el).textShadow` yourself, more than once, against the same jsdom-parsed element — a real browser has no such bug.
 - **Under jsdom, scan time grows with the square of DOM depth, not with element count.** jsdom resolves inherited CSS by walking an element's ancestor chain on every `getComputedStyle` call, so one call per element costs O(elements x depth). Measured on jsdom 29.1.1 with no engine code involved: 4000 elements in one chain take 8.3s of `getComputedStyle` alone, against 0.25s for the same 4000 as siblings. The engine's own ancestor walks are capped and stay linear, so this is jsdom's cost rather than the rules'. It affects `runDomRulesInPage` and anything built on it, including `@surea11y/test-matchers`; a real browser computes inherited style natively and does not have this shape. Component frameworks routinely nest 100-300 deep, which is comfortably fast — it becomes noticeable past roughly 1000.
+- **In a real browser, some rules change the page for the time of their check, and the page's own scripts can react.** To measure what the browser draws, `css-hidden-focus` focuses elements as the keyboard would, and switches transitions off on the element it measures; `text-spacing-content-loss` adds a style sheet with the WCAG 1.4.12 spacing. All of this is put back before the rule returns: focus, scroll position, style attributes and the added style sheet. What cannot be put back is what the page's scripts do in response, since focusing an element fires its `focus` handlers: a carousel may move to the focused slide or enable a button. The findings are not affected, but if you scan a page you go on using, reload it afterwards.
 - **Static markup vs. live/post-hydration DOM state.** The rule logic itself is DOM-source-agnostic — it evaluates whatever DOM it's handed, whether that's jsdom-parsed static HTML (Pattern 1) or an already-loaded, already-hydrated real browser tab (Pattern 2, see [`INTEGRATION.md`](./INTEGRATION.md)). But the CLI (`npx @surea11y/cli scan <url>`) specifically fetches static HTML only, with no JS execution — see [the CLI docs](https://github.com/SureA11y/cli/blob/main/docs/CLI.md). For a JS-framework-hydrated widget whose server-rendered markup intentionally ships one state before client JS syncs it (e.g. `<input type="checkbox" aria-checked="true">` shipped before client JS sets the native `checked` property to match on hydration — an extremely common, entirely legitimate pattern), a CLI scan only sees the pre-hydration markup. A scan running inside an actual loaded browser tab sees the post-hydration state instead, so the two can disagree on exactly this class of element for reasons that have nothing to do with rule correctness. That's why `aria-checked-state-mismatch` is capped at `manual`/`cantTell` rather than a hard `fail`. If you need live-DOM accuracy for hydration-sensitive checks, run the library directly against an already-loaded page via Pattern 2, not the static-fetch CLI.
 
 ## Not attempted: judgment calls that aren't automatable safely

package/docs/OUTPUT_SCHEMA.md

@@ -19,7 +19,9 @@ This is the exact shape of the object returned by `runDomRulesInPage(...)` / `ru
     tag: string,
     schemaVersion: string,
     locale: { requested: string, resolved: string, reason: string },
-    wcagVersion: "2.0" | "2.1" | "2.2"
+    wcagVersion: "2.0" | "2.1" | "2.2",
+    profile?: string,      // "wcag22-aa", "en301549-v4.1.1", "en301549-v3.2.1", "section508", or a registered standard's own
+    mappings?: string[]    // e.g. ["en301549"] or ["en301549:V3.2.1"]
   },
   url: string | null,
   title: string | null,
@@ -37,15 +39,19 @@ This is the exact shape of the object returned by `runDomRulesInPage(...)` / `ru
 | `engine.tag` | The engine's own identity tag, currently `"a11ycore"`. Every rule (built-in or custom) carries it in `meta.tags` — rule `ruleId`s themselves are bare (no prefix). |
 | `engine.schemaVersion` | The result-schema version (`"1.0.0"`). Bump-worthy if this document's shape ever changes incompatibly — pin to it if you're parsing output programmatically. See [`API_STABILITY.md`](./API_STABILITY.md) for the full stable/unstable field list and version-bump policy. |
 | `engine.locale` | Which dictionary the run actually used. `requested` is your `engineOptions.locale` after trimming (`"en"` if you passed nothing or a non-string); `resolved` is the locale whose dictionary was used; `reason` explains the pairing. Because locale fallback is graceful and per-string, asking for a language the build does not carry produces English text rather than an error — this field is how you find that out without reading the strings. Reported once per result: a run uses one dictionary throughout. |
-| `engine.locale.reason` | `"ok"` — you got the dictionary you asked for, and it carries every key. `"primary-subtag"` — your code had a subtag with no dictionary of its own, so its base language was used: `"de-DE"` resolves to `"de"`. `"dictionary-not-loaded"` — the project ships that language, but this build does not carry it and none was supplied (the standalone browser bundle, without its locale side file). `"unknown-locale"` — the project has no such translation at all. `"partial-dictionary"` — the dictionary was used but is missing keys English has, so those strings fell back to English. Treat the set as open; later releases can add to it. |
+| `engine.locale.reason` | `"ok"` — you got the dictionary you asked for, and it carries every key (a profile's messages in a language that profile does not offer show in English, by its choice, and do not count; see [`I18N.md`](./I18N.md)). `"primary-subtag"` — your code had a subtag with no dictionary of its own, so its base language was used: `"de-DE"` resolves to `"de"`. `"dictionary-not-loaded"` — the project ships that language, but this build does not carry it and none was supplied (the standalone browser bundle, without its locale side file). `"unknown-locale"` — the project has no such translation at all. `"partial-dictionary"` — the dictionary was used but is missing keys English has, so those strings fell back to English. Treat the set as open; later releases can add to it. |
 | `engine.wcagVersion` | Which version of WCAG this run was conformance-tested against: your `engineOptions.wcagVersion`, or what your version-origin tags implied, or the default `"2.2"`. It affects one thing today — a rule mapped only to SC 4.1.1 Parsing cannot `fail` under a 2.2 target (see `checksResults[i].wcagVersionScope` below). Reported once per result: a run has one target throughout. |
+| `engine.profile` | Present only when an `engineOptions.profile` selected this run's rules, and names the profile, lowercased. Absent when none was asked for, and also when one was asked for but did not apply (unknown name, or an include in `runOnly` or `engineOptions` chose the rules instead), so its presence is how you confirm a run really targeted that profile. See [`ENGINE_OPTIONS.md`](./ENGINE_OPTIONS.md#conformance-profiles). |
+| `engine.profileExcludes` | Present only when the applied profile leaves rules out (`exclude` in its standard's registry entry): `{ rules, criteria }`, the rules it names and the WCAG criteria it waives. Their rules and WCAG rollups did not run. See [`ENGINE_OPTIONS.md`](./ENGINE_OPTIONS.md#conformance-profiles). |
+| `engine.optInRules` | Present only when `engineOptions.optInRules` ran at least one opt-in rule that the rest of the selection would not have run. Lists their tags. Its presence means the result includes rules for requirements beyond the targeted standard, such as a national standard's, so a failure may not be a WCAG failure. Absent under a WCAG profile, where unlocking selects nothing, and when a standard's own profile ran its rules. See [`ENGINE_OPTIONS.md`](./ENGINE_OPTIONS.md#running-every-rule-optinrules). |
+| `engine.mappings` | Present only when the run names a standard besides WCAG in `meta.normativeMappings`, through `engineOptions.mappings` or a standard's profile. Lists them canonically, in table order: `"en301549"` for every version, `"en301549:V3.2.1"` for one. Absent means every result names WCAG only. See [`ENGINE_OPTIONS.md`](./ENGINE_OPTIONS.md#other-standards-mappings). |
 | `url` | The `pageUrl` argument you passed in, or `document.location.href` if you passed `null`/omitted it, or `null` if neither is available. |
 | `title` | `document.title` at scan time, or `null`. |
 | `timestamp` | **Not auto-generated.** Only set if you pass `engineOptions.timestamp` as a non-empty string — the engine has no built-in clock (deterministic-by-design). If you want a scan timestamp in the result, supply it yourself. |
 | `perfStats` | `null` unless `engineOptions.perfStats: true`. Internal timing/counters — shape not covered by this document, treat as debug-only. |
 | `contextSelector` | The (trimmed) `contextSelector` argument you passed — a string, an array of strings (multi-region scanning, see [`ENGINE_OPTIONS.md`](./ENGINE_OPTIONS.md)), or `null` if none/empty. |
 | `checksResults` | One entry per **atomic rule** that ran (every rule not filtered out by `runOnly` — see [`ENGINE_OPTIONS.md`](./ENGINE_OPTIONS.md)). **Every loaded rule produces an entry, even ones that outcome `notApplicable`** — this is not a "violations only" list. |
-| `rulesResults` | One entry per **composite (WCAG-SC rollup) rule** that ran — see [Composite result](#a-composite-result-rulesresultsi) and [`WCAG_CONFORMANCE.md`](./WCAG_CONFORMANCE.md). Empty array if no composite matched the current `runOnly`/tag filter. |
+| `rulesResults` | One entry per **composite (rollup) rule** that ran — see [Composite result](#a-composite-result-rulesresultsi) and [`WCAG_CONFORMANCE.md`](./WCAG_CONFORMANCE.md). Normally one per WCAG Success Criterion; a run under the profile of a standard with rollups of its own also gets those (`meta.standard` set). Empty array if no composite matched the current `runOnly`/tag filter. |
 | `overriddenBuiltinIds` | Rule ids where an `engineOptions.customRules` entry shared its `id` with a built-in rule, so the custom implementation replaced the built-in one for this scan (see [`ENGINE_OPTIONS.md`](./ENGINE_OPTIONS.md)). Always an array; empty when no collision occurred. Also logged via `console.warn` at scan time, since a same-named custom rule is as likely to be an accidental collision as a deliberate override. |
 
 ## Cross-frame result (`runa11yCoreAcrossFrames`)
@@ -87,7 +93,7 @@ This is the exact shape of the object returned by `runDomRulesInPage(...)` / `ru
     normative: boolean,
     atomic: boolean,
     category: "perceivable" | "operable" | "understandable" | "robust" | null,
-    normativeMappings: Array<{ standard: string, version: string, requirement: string, title: string, conformanceLevel: string }>,
+    normativeMappings: Array<{ standard: string, version: string, requirement: string, title: string, conformanceLevel?: string, wcagSc?: string[] }>,
     standard: string | null,
     applicability: string,
     expectation: string,
@@ -97,6 +103,8 @@ This is the exact shape of the object returned by `runDomRulesInPage(...)` / `ru
   },
   engineOptions: object,   // the resolved engineOptions this rule actually ran under
   schemaVersion: string,
+  rollupIds: string[],     // the rulesResults entries that group this rule in this run; [] if none
+  data?: object,           // page-level data a rule reports whatever its outcome; see below
   wcagVersionScope?: {     // present only when the target WCAG version changed this outcome
     target: "2.0" | "2.1" | "2.2",
     removedSc: string[],
@@ -110,8 +118,10 @@ Notes:
 
 - **`outcome` vs `outcomeNormalized`**: identical except `notApplicable` becomes `"inapplicable"` in `outcomeNormalized`. Both are provided so you can match either your own vocabulary or the engine's internal one.
 - **`type: "manual"` rules can never report `outcome: "fail"`.** If a manual rule's own logic would have said `fail`, the engine coerces it to `cantTell` and appends an explanatory note to `error` — this is enforced centrally (`policy.coerceManualFailToCantTell`, on by default under the `a11y` policy contract; see [`POLICY.md`](./POLICY.md)), not something each rule has to remember. `fail` is reserved for deterministic, `type: "automatic"` findings only.
-- **`meta.normativeMappings`** is how a check result ties back to a WCAG Success Criterion — `[]` for rules with no formal WCAG mapping (this engine calls them advisory `type: "manual"` rules). See [`WCAG_CONFORMANCE.md`](./WCAG_CONFORMANCE.md) for how these roll up.
+- **`rollupIds`** lists the composites in `rulesResults` that group this rule in this run. An empty list means the rule's findings appear in no rollup, so a consumer that reads only `rulesResults` never sees them; `heading-order`, for instance, belongs to no WCAG rollup.
+- **`meta.normativeMappings`** is how a check result ties back to a WCAG Success Criterion — `[]` for rules with no formal WCAG mapping (this engine calls them advisory `type: "manual"` rules). See [`WCAG_CONFORMANCE.md`](./WCAG_CONFORMANCE.md) for how these roll up. The list is not WCAG-only. When the scan asks for another standard (`engineOptions.mappings`, or a standard's profile), each WCAG criterion is followed by that standard's corresponding requirement, such as the EN 301 549 clause that restates it (`{ standard: "EN 301 549", version: "V3.2.1" | "V4.1.1", requirement: "9.1.1.1", title, wcagSc: ["1.1.1"] }`, one entry per version that includes the criterion, `wcagSc` naming the criteria it corresponds to), or the requirements of a standard mapped rule by rule that the rule checks (same shape, `wcagSc` empty for a requirement WCAG does not make, and any fields of that standard's own); and a rule may also cite WCAG's Understanding documents (`type: "Understanding"`). Filter on `standard` (and on the absence of `type`) before reading `requirement` as a Success Criterion. A composite's WCAG entry is always first. See [`WCAG_CONFORMANCE.md`](./WCAG_CONFORMANCE.md#en-301-549).
 - **`wcagVersionScope`**: only present when the run's target WCAG version turned this rule's `fail` into a `cantTell` — today that means a rule mapped to SC 4.1.1 Parsing (`duplicate-id`) under the default 2.2 target, since 2.2 removed that criterion. `removedSc` lists the criteria that stopped existing, `target` is the version that removed them, and `coercedFrom` is the outcome the rule itself reported. The occurrences are the rule's own, unchanged — nothing was dropped, only the conformance verdict was. Absent on every other result, and **never** reported through `error`: nothing went wrong. See [`ENGINE_OPTIONS.md`](./ENGINE_OPTIONS.md#filtering-by-wcag-version-21-vs-22).
+- **`data`**: present only on a rule that reports something about the whole page, whatever its outcome. No core rule does today; a profile's rule may, such as one returning the page's own entry for a probe that compares pages (see `probes` in [`ENGINE_OPTIONS.md`](./ENGINE_OPTIONS.md)). Like `data.details` on an occurrence, it is not a stable contract.
 - **`error`**: only present if the rule implementation threw an uncaught exception, or if the manual-fail coercion above fired. A thrown rule always surfaces as `outcome: "cantTell"` with `occurrences: []` and `error` set to the exception message — the engine never lets one broken rule crash the whole scan.
 - **`engineOptions`** on each result is the *resolved* options object (after locale/contrast defaults were applied), not literally what you passed in — useful for confirming what a given rule actually saw, especially the resolved `locale` and `contrast.mode`/`contrast.rootCanvasFallback`.
 
@@ -175,7 +185,7 @@ Every automatic rule that can report `cantTell` carries this, and a test holds t
 
 ## A composite result (`rulesResults[i]`)
 
-Composites roll multiple atomic rules up to one WCAG Success Criterion (e.g. `wcag-1.1.1-non-text-content` rolls up 22 atomic rules). Shape is the same envelope as a check result, with composite-specific `data.details`:
+Composites roll multiple atomic rules up to one WCAG Success Criterion (e.g. `wcag-1.1.1-non-text-content` rolls up 22 atomic rules). Under the profile of a standard with rollups of its own, there are also those, with the standard's wording as `title` and its name as `meta.standard`; they may be the only rollup some of its findings have, such as `heading-order`'s. Shape is the same envelope as a check result, with composite-specific `data.details`:
 
 ```ts
 {
@@ -186,6 +196,9 @@ Composites roll multiple atomic rules up to one WCAG Success Criterion (e.g. `wc
   data: {
     details: {
       reasonCode: string,       // e.g. "composite.rollup.fail.anyFail"
+      standard?: string,        // a standard's own rollup only, with version and criterion
+      version?: string,
+      criterion?: string,
       checksIds: string[],      // every atomic ruleId this composite rolls up
       contributors: Array<{ testId: string, outcome: string, severity: string | null }>,
       metrics: { failCount, cantTellCount, notApplicableCount, passCount, missingCount }

package/docs/REPORT.md

@@ -12,10 +12,15 @@ Open `report.html` directly from disk. Works alongside any other output mode —
 
 - **Hero**: one plain-language headline ("N of M applicable checks passed") plus a stacked bar and legend (icon + label + count — status is never color-only) broken down by outcome (`fail`/`cantTell`/`pass`/`notApplicable`).
 - **Worth reviewing**: one card per rule with `fail`/`cantTell` occurrences (not one per occurrence — a rule with many identical occurrences is one thing worth attention, not many), each showing severity, WCAG SC chip(s), a representative occurrence, and the total occurrence count. Capped at the 24 highest-priority rules with an overflow note past that.
-- **WCAG rollup**: grouped by conformance level (A / AA / AAA), sourced directly from the engine's own `rulesResults[]` composite rollups (`docs/WCAG_CONFORMANCE.md`) — one row per Success Criterion, its outcome, a pass/fail/needs-review/n/a breakdown, and which atomic rules contributed. This is real engine data, not an invented grouping — the same rollup you'd get from the raw JSON's `rulesResults`.
+- **WCAG rollup**: grouped by conformance level (A / AA / AAA), sourced directly from the engine's own `rulesResults[]` composite rollups (`docs/WCAG_CONFORMANCE.md`) — one row per Success Criterion (with the EN 301 549 clause that restates it, where there is one and the scan asked for EN 301 549 clauses), its outcome, a pass/fail/needs-review/n/a breakdown, and which atomic rules contributed. This is real engine data, not an invented grouping — the same rollup you'd get from the raw JSON's `rulesResults`.
+- **A standard's own rollup**: only when the scan ran the rules of a standard that has rollups of its own (its profile, or `engineOptions.optInRules`), one row per rollup, with the standard's wording, the requirements of the rules that decided the outcome, the breakdown and the contributing rules.
 - **Full technical data** (collapsed by default): a scorecard (tiles per outcome) and a searchable, filterable (by outcome), paginated table of every individual occurrence across the whole scan.
 
-The meta bar under the header carries the rule count, occurrence count, engine tag, schema version, and the locale the scan resolved to. Locale fallback is per-string and invisible in the text itself, so a report requested in a language the engine does not carry reads as an ordinary English one — the chip names the requested locale alongside the resolved one when the two differ. See [`I18N.md`](./I18N.md).
+The meta bar under the header carries the rule count, occurrence count, engine tag, schema version, the WCAG version the scan targeted the `engineOptions.profile` it used (when there was one), the opt-in rule tags `engineOptions.optInRules` added (when it added any), and the locale the scan resolved to. Locale fallback is per-string and invisible in the text itself, so a report requested in a language the engine does not carry reads as an ordinary English one — the chip names the requested locale alongside the resolved one when the two differ. See [`I18N.md`](./I18N.md).
+
+The whole page is written in the locale the scan resolved to: headings, table columns, outcome and severity names, the headline, the pager, and the date format, all from the `report_*` keys in the same dictionaries as the findings. `<html lang>` names that locale. The outcome codes in the occurrence filters (`fail`, `cantTell`, …) stay as they are, because they are the values a reader searches for in the JSON result.
+
+One case keeps English labels: a scan in a language the engine does not ship, run with a caller-supplied `engineOptions.messages` dictionary. That dictionary is not part of the result, so the report cannot read labels from it; its findings are then marked with their own language (`lang="nl"`, for instance), so a screen reader still reads them with the right voice.
 
 ## Library usage
 

package/docs/RULE_AUTHORING.md

@@ -114,7 +114,7 @@ const meta = {
       title: 'Non-text Content',
       conformanceLevel: 'A'
     }
-  ],
+  ], // WCAG only: EN 301 549 clauses are derived at build time (WCAG_CONFORMANCE.md#en-301-549)
 
   defaultSeverity: 'minor' | 'moderate' | 'serious' | 'critical',
   category: 'perceivable' | 'operable' | 'understandable' | 'robust',
@@ -141,8 +141,9 @@ The build/runtime resolves i18n by:
 2) falling back to `en` if missing,
 3) falling back to the literal `title`/`description` strings if still missing.
 
-Add the key and its English text to `src/i18n/en.json`, then run
-`npm run i18n:sync` so every other locale picks it up. `npm test` fails if you
+Add the key and its English text to `src/i18n/en.json` (a profile's rule:
+`profiles/<name>/i18n/en.json`), then run `npm run i18n:sync` so every other
+locale picks it up. `npm test` fails if you
 forget. See [`I18N.md`](./I18N.md).
 
 #### `meta.tags`
@@ -150,6 +151,35 @@ Tags are used for grouping/filtering. Typical tag families in this ruleset inclu
 - WCAG tagging: `wcag2a`, `wcag111`
 - domain: `nontext`, `images`, plus element-specific tags
 - nature: `atomic`, plus `automatic` or `manual`
+- another standard's own requirement: that standard's rule tag (see below)
+
+#### Rules for another standard's own requirements
+A rule that checks something WCAG does not require, but another standard does (a doctype or presentational attributes, say), declares no WCAG mapping (`wcagSc: []`, `normativeMappings: []`) and carries that standard's rule tag. The tag makes it **opt-in**: it runs only under the standard's profile, a selection that includes the tag, or its own id, never in a default or WCAG run ([`ENGINE_OPTIONS.md`](./ENGINE_OPTIONS.md#opt-in-rules)). That is what lets it report `fail`: its failures are failures of that standard, and only a scan targeting it sees them. Its module goes in that standard's profile rather than in `src/checks/`: `profiles/<key>/rules/automatic/` or `profiles/<key>/rules/manual/`. The build compiles it into the engine like any other rule. Its test and scenario page go in the profile too, in `profiles/<key>/tests/rules/` and `profiles/<key>/tests/fixtures/`. Map it to the standard's requirements the usual way (a row in the profile's rule map). Rule tags come from each standard's `ruleTag` in the registry, `src/coverage/standards.js` (a profile's from its `index.js`). The sample profile core's tests run against, `tests/fixtures/profiles/sample/`, has two such rules.
+
+#### Rule variants
+When another standard's requirement is a core rule with different thresholds (contrast at 7:1, say, or bold text large from 18.5px rather than WCAG's 14pt), write it as a **variant**, not a copy. The core rule declares the thresholds it reads from `ctx.config` as `settings`, with WCAG's values as defaults:
+
+```js
+// src/checks/automatic/contrast-minimum.js
+const settings = { boldLargeMinPx: null, largeTextRatio: 3, normalTextRatio: 4.5 };
+module.exports = { id, meta, runInPage, settings };
+```
+
+The variant is data, in the standard's profile:
+
+```js
+// profiles/<key>/rules/automatic/sample-contrast-enhanced.js
+module.exports = {
+  id: 'sample-contrast-enhanced',
+  from: 'contrast-minimum',
+  config: { normalTextRatio: 7, largeTextRatio: 4.5 },
+  meta: { /* its own title, description, i18n, tags... as any rule's */ }
+};
+```
+
+The build runs the base rule's `runInPage` and `applicability` under the variant's id and meta, with its `config` in `ctx.config`. A rule's settings are never the caller's: the runner drops a caller's value for one (`engineOptions.rules[ruleId]`), so the base rule always runs at its defaults and the variant at its `config`, while the caller's other config, such as `excludeSelectors`, still applies. A message key of the base's that starts with the base's prefix (its `meta.i18n.titleKey` without `_title`, `contrastMinimum`) is read from the variant's prefix instead (`sampleContrastEnhanced`), so the variant's dictionary has the same keys under its own prefix; the rule validator checks they exist. A fix to the base reaches every variant. The build refuses a variant whose base does not exist, is itself a variant, or declares no `settings`, and a setting the base does not declare or of another type. A base rule that caches verdicts depending on its settings keys those caches by them, as `contrast-minimum` does.
+
+Add a setting to a core rule when a standard needs it, with a default that keeps the rule's behaviour; the settings a rule declares are for its variants, not for callers, and stay outside semver until a profile can live outside this repository (see [`API_STABILITY.md`](./API_STABILITY.md#explicitly-unstable-not-covered-by-semver)).
 
 #### `meta.coverage.facetsBySc`
 This is the repo’s explicit **coverage model** for an SC.
@@ -317,7 +347,23 @@ The rule must return:
 
 Examples:
 
-### 8.2 Outcome conventions used by these rules
+### 8.2 What `ctx` carries
+
+`runInPage(ctx)` and `applicability(ctx)` receive the same object, built-in and custom rules alike:
+
+| Field | What it is |
+|---|---|
+| `document`, `window` | The page being scanned. |
+| `root` | The roots the scan covers: the document, or what `contextSelector` resolved to. |
+| `contextSelector` | The selector that scoped the run, if any. |
+| `rule` | The rule's resolved definition: `ruleId`, `defaultSeverity`, `defaultConfidence`, `type`, `meta`... |
+| `config` | `engineOptions.rules[ruleId]`, this rule's settings, if the caller gave any (see [`ENGINE_OPTIONS.md`](./ENGINE_OPTIONS.md)). |
+| `standard` | The standard and version the run targets, `{ key, name, version }` (`{ key: 'en301549', name: 'EN 301 549', version: 'V4.1.1' }`), when a standard's profile selected the run; `null` otherwise (no profile, a WCAG profile, or rules chosen by tag or id). A rule whose behaviour differs between versions of its standard reads it here, and does what holds for every version when it is `null`. |
+| `helpers` | The helpers documented in [`RULE_HELPERS.md`](./RULE_HELPERS.md). |
+| `engineOptions` | The scan's options as resolved. |
+| `inputs.probes` | Evidence the host application supplied (`engineOptions.probes`). |
+
+### 8.3 Outcome conventions used by these rules
 
 Automatic:
 - `notApplicable` if no applicable targets
@@ -385,7 +431,8 @@ exercised as real pages), not just embedded as strings inside `.test.js` files.
 ### 11.1 The fixture file
 
 - Path: `tests/fixtures/<rule-slug>-all-scenarios.html`, where `<rule-slug>` is the rule
-  id itself (e.g. `tab-name-present` → `tab-name-present-all-scenarios.html`).
+  id itself (e.g. `tab-name-present` → `tab-name-present-all-scenarios.html`). A
+  profile's rule keeps it in the profile: `profiles/<name>/tests/fixtures/`.
 - Structure: a real HTML page (`<!doctype html>`, `<title>`, minimal inline `<style>`)
   containing numbered scenario blocks, each:
   ```html
@@ -405,6 +452,24 @@ exercised as real pages), not just embedded as strings inside `.test.js` files.
     (eligible, FAIL)", "C. Ineligible (excluded from accessibility tree, skipped)").
 - Cover every branch the rule's own logic distinguishes: pass, fail (each distinct
   `reasonCode`), notApplicable/skipped, and — for manual rules — cantTell.
+- A whole-document rule (`page-title-present`, `meta-refresh-timing-absent`, `region`)
+  can only demonstrate one outcome per page. Its fixture declares a single bare
+  `.case-title` with no `.case` wrapper, and the page itself is the case; the marker is
+  compared against the rule-level outcome, so `PASS` and `NEUTRAL` are distinguished
+  there. Cover the remaining branches with inline tests rather than near-identical
+  fixture files.
+- One fixture shared by several rules that expect different things of the same case
+  (`tests/fixtures/contrast-all-scenarios.html` serves `contrast-minimum`,
+  `contrast-enhanced` and `contrast-computable`) carries a per-rule marker as a
+  `data-outcome-<rule-id>` attribute on the `.case`, which overrides the shared
+  `.case-title` for that rule. Use an attribute rather than more text when the rules
+  under test evaluate text: a `.case-title` added to a contrast case is one more text
+  node to check. A marker word the parser does not recognise (`MIXED`, `UNSTATED`)
+  asserts nothing, for a case whose outcome the fixture does not state.
+- `npm run fixtures:markers:check` replays every fixture and fails when a marker no
+  longer matches what the rule reports; `scripts/data/fixture-markers.json` records the
+  cases that already disagree, so that set can only shrink. A profile's rules have
+  their record in the profile's own `scripts/data/fixture-markers.json`.
 
 ### 11.2 Known, acceptable exceptions to "one fixture, many cases"
 
@@ -480,7 +545,9 @@ npm run fixtures:index
 This writes `tests/fixtures/INDEX.md` (human-readable), `tests/fixtures/index.json`
 (machine-readable — every rule, its fixture path, and parsed pass/fail/cantTell case
 counts, for external tooling to enumerate and load fixtures directly) and
-`tests/fixtures/index.html` (the same listing as a browsable page). Commit all three
+`tests/fixtures/index.html` (the same listing as a browsable page). A profile's rules
+get the same three files in the profile's `tests/fixtures/`, with paths relative to the
+profile's folder. Commit all three
 alongside the fixture and test changes. A rule shipped without its fixture is treated
 the same as a rule shipped without tests — not done. `npm run fixtures:check` reports
 a stale index without rewriting it, and CI fails on one.