@surea11y/core 1.4.1 → 1.6.0

package/docs/I18N.md

@@ -4,14 +4,18 @@ Every rule's title/description, and every occurrence's summary/hint, is localize
 
 ## Current locale coverage
 
-| Locale | File | Keys | Coverage vs. English |
+| Locale | File | Keys | Values still in English |
 |---|---|---|---|
-| `en` (English) | `src/i18n/en.js` | 614 | 100% (the canonical/fallback set) |
-| `fr` (French) | `src/i18n/fr.js` | 614 | 100% |
-| `de` (German) | `src/i18n/de.js` | 614 | 100% |
-| `es` (Spanish) | `src/i18n/es.js` | 614 | 100% |
+| `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 |
 
-All four locales are fully translated as of this writing. That won't stay automatically true — every time a new rule (or a new i18n key) is added to `en.js`, every other locale needs the same key added, or it silently falls back to English for that string (see the fallback behavior below). `tests/i18n/i18n-locale-completeness.test.js` catches this: it fails the build if a locale listed in `FULLY_TRANSLATED_LOCALES` (currently `fr`, `de`, `es`) is missing any key present in `en.js`, and fails for *any* locale that has an orphaned key not in `en.js` (a sign of a typo or a stale key left behind after a rule was removed). Run `npm run i18n:report` any time to see per-locale coverage.
+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.
+
+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.
 
 ## Selecting a locale
 
@@ -19,17 +23,87 @@ All four locales are fully translated as of this writing. That won't stay automa
 runDomRulesInPage(url, null, { locale: 'fr' }, null);
 ```
 
-Default is `'en'` if omitted. Any string is accepted — an unrecognized locale (e.g. `'ja'`, not yet built) behaves exactly like a locale that's 0% translated: every string falls through to English (see below), not an error.
+Default is `'en'` if omitted. Any string is accepted; an unrecognized locale is never an error.
+
+## How a locale is chosen
+
+Two things happen, in this order. Getting them mixed up is the usual source of confusion, so they are described separately.
+
+### Step 1 — pick a dictionary (once per scan)
+
+1. Use the dictionary matching your code. `de` finds `de.json`. Case doesn't matter — `pt-br`, `pt-BR` and `PT-BR` all find `pt-BR.json`.
+2. Otherwise, drop everything after the first `-` and try that. `de-DE` finds `de.json`; so does `de-AT`.
+3. Otherwise, use English.
+
+So you only need a `de-DE.json` if German in Austria and Germany should actually read differently. Ship `de.json` and every German variant is covered.
+
+### Step 2 — resolve each string (per string)
+
+Within the chosen dictionary, every string is looked up on its own:
+
+1. Take the key's value from the chosen dictionary.
+2. If that key is missing, take the English one.
+3. If English is missing it too — which shouldn't happen for a built-in key, but can for a hand-rolled one — use the literal text the rule itself carries.
+
+The result is never a blank, an `undefined`, or a thrown error. A half-finished translation renders in your language where it exists and in English everywhere else. See `t()` in `scripts/build-core.js` for the exact implementation.
+
+## Knowing which locale you actually got
+
+Graceful fallback has one drawback: ask for a language the build doesn't carry and you get fluent English back, with nothing in the strings to say so. Every result therefore reports the resolution once, at the top:
+
+```json
+"engine": {
+  "tag": "a11ycore",
+  "schemaVersion": "1.0.0",
+  "locale": { "requested": "ja", "resolved": "en", "reason": "unknown-locale" }
+}
+```
+
+`requested` is what you asked for (after trimming; `en` if you passed nothing or a non-string), `resolved` is the dictionary that was used, and `reason` is one of:
+
+| `reason` | Meaning |
+|---|---|
+| `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. |
 
-## Fallback behavior (per-string, not per-locale)
+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.
 
-Resolution happens independently for *every individual string*, not once for the whole scan:
+If you need a particular language, `requested !== resolved` is the condition to check in CI. Note it is also true for the harmless `primary-subtag` case, so gate on `reason === 'unknown-locale' || reason === 'dictionary-not-loaded'` if a base-language match is good enough for you. See [`OUTPUT_SCHEMA.md`](./OUTPUT_SCHEMA.md#top-level-result) for the field's place in the result and [`API_STABILITY.md`](./API_STABILITY.md) for what is guaranteed about it.
 
-1. Look up the key in the requested locale's dictionary.
-2. If missing, fall back to the English (`en`) dictionary.
-3. If still missing (shouldn't happen for a built-in key, but true for anything hand-rolled), fall back to the literal string the rule itself provided as a default.
+## Where the dictionaries live
 
-This means requesting `locale: 'fr'` today gives you a real mix — translated strings where `fr.js` has the key, English strings where it doesn't — never a blank, `undefined`, or thrown error. See `t()` in `scripts/build-core.js` if you need the exact implementation.
+Which languages are available depends on how you load the engine.
+
+| How you load it | What you get |
+|---|---|
+| `require('@surea11y/core')` | Every locale, built in. Nothing to configure. |
+| 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.
+
+```html
+<script src="surea11y.browser.js"></script>
+<script src="surea11y.i18n.de.js"></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.
+
+### Supplying a dictionary yourself
+
+`engineOptions.messages` accepts `{ [locale]: { key: value } }` and takes precedence over anything built in or loaded from a side file. Useful for overriding a handful of strings, or for a language you maintain privately:
+
+```js
+runDomRulesInPage(url, null, {
+  locale: 'de',
+  messages: { de: { img_altPresent_title: 'Eigener Text' } }
+}, null);
+```
+
+Keys you don't supply fall back normally, so a partial override is fine.
 
 ## Where keys are used
 
@@ -40,11 +114,93 @@ Two independent key namespaces, both resolved the same way:
 
 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`.
 
-## Contributing a translation
+## Adding your language
+
+You do not need to know how the engine works, and you will not write any JavaScript beyond editing quoted strings. A translation is one data file.
+
+### 1. Get the repository running
+
+```sh
+git clone https://github.com/SureA11y/core.git
+cd core
+npm install
+```
+
+### 2. Create the file
+
+```sh
+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.
+
+Add a regional file only when the wording genuinely has to differ, and add it alongside the base language rather than instead of it.
+
+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
+
+Each entry is `"key": "text"`. Change only the text on the right:
+
+```json
+  "img_altPresent_title": "<img> must have an alt attribute",
+```
+
+becomes
+
+```json
+  "img_altPresent_title": "<img> precisa ter um atributo alt",
+```
+
+Four things to leave alone:
+
+- **The keys.** `img_altPresent_title` is an identifier the engine looks up. Renaming one breaks the lookup.
+- **`{{placeholder}}` tokens** — `{{ratio}}`, `{{element}}`, `{{role}}` and friends are substituted with real values at scan time. Keep them spelled exactly as in English. You may move them within the sentence if your grammar needs it.
+- **`{{#name}}…{{/name}}` and `{{^name}}…{{/name}}` blocks** — conditional sections, shown or hidden depending on the finding. Translate the text inside them; keep the markers.
+- **Code identifiers** — `<img>`, `aria-label`, `role="dialog"`, `alt=""`, CSS property names. These are things the reader will look for in their own source, so they stay in the original. A double quote inside a value has to stay escaped as `\"`, which is the one piece of JSON syntax you need.
+
+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.
+
+### 4. Check your progress
+
+```sh
+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.
+
+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.
+
+### 5. Before opening the pull request
+
+```sh
+npm run i18n:sync    # confirms your file matches en.json key-for-key
+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.
+
+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`:
+
+```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.
+
+| 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:check` | Same comparison, writes nothing, exits non-zero on drift. |
+| `npm run i18n:report` | Per-locale translation coverage. |
 
-1. Scaffold the file: `npm run i18n:new <locale>` (e.g. `npm run i18n:new de`) creates `src/i18n/<locale>.js` with all of `en.js`'s keys already present, each seeded with the English text as a placeholder. It refuses to overwrite an existing locale file unless you pass `--force`.
-2. Replace the placeholder values with real translations, key by key. Leave any you're unsure about as-is for now — a value identical to English is treated as untranslated, not broken (see the fallback behavior above).
-3. Check progress any time with `npm run i18n:report` — it prints, per locale, how many keys have been translated vs. still match the English placeholder, plus any missing or orphaned keys.
-4. You don't need every key on day one — the fallback behavior above means a partial translation degrades gracefully to English per-string, exactly like `fr`/`de`/`es` did during their own early stages. Ship what you have. A partial locale is valid and won't fail `i18n-locale-completeness.test.js` unless you also add it to `FULLY_TRANSLATED_LOCALES` in that file — only do that once `npm run i18n:report` shows 100% coverage.
-5. Keep `{{placeholder}}` tokens (and `{{#foo}}...{{/foo}}` conditional blocks) in translated strings exactly as they appear in the English source — they're substituted/evaluated verbatim regardless of locale (e.g. `{{element}}`, `{{role}}`). Never translate HTML tag/attribute names (`<img>`, `aria-label`, `role="dialog"`, etc.) — they're code identifiers, not prose.
-6. Run `npm run build && npm test` to confirm nothing broke, including locale-completeness.
+`npm test` fails if a locale file has drifted, so an added key cannot reach `main` without every locale carrying it.

package/docs/INTEGRATION.md

@@ -107,7 +107,29 @@ Good for: a manual check against a page open in a real browser, a bookmarklet, o
 
 `a11ycore.runa11yCoreInPage` is the exact same function described in Pattern 2 above — the bundle exists only to solve *loading* it without `require`/a module system, not to add a separate API surface. It carries the same self-containment property (own inlined rule catalog, no free variables), which is what makes a plain `<script>` tag sufficient.
 
-Deliberately excluded from this bundle: `runa11yCoreAcrossFrames`/`a11yCoreEnableFrameResponder`. Cross-frame scanning needs the embedded frame to load the engine and opt in too (see "Cross-frame scanning" below) — not a fit for a single dropped-in script tag. Use the npm package directly if you need it.
+### Scanning in a language other than English
+
+The bundle carries English only. Every other locale ships beside it as its own file — load one after the bundle and that language becomes available:
+
+```html
+<script src="node_modules/@surea11y/core/surea11y.browser.js"></script>
+<script src="node_modules/@surea11y/core/surea11y.i18n.de.js"></script>
+<script>
+  const result = a11ycore.runa11yCoreInPage(location.href, null, { locale: 'de' }, null);
+</script>
+```
+
+Load as many as you need; each adds one language and they don't interfere. Order matters only in that the bundle has to come first — a side file loaded on its own throws with a message saying so.
+
+Ask for a locale whose file you haven't loaded and you get English, not an error, with `result.engine.locale.reason` set to `dictionary-not-loaded` so it's visible rather than silent. See [`I18N.md`](./I18N.md).
+
+Why the split: the bundle is fetched over the network, and every language would otherwise be paid for by every page whether used or not. Keeping English inline and the rest optional took roughly 280 KB off the download and stops it growing as languages are added. The Node package is unaffected — `require('@surea11y/core')` still has every locale built in.
+
+If you'd rather supply a dictionary yourself, `engineOptions.messages` takes `{ [locale]: { key: value } }` directly and wins over a loaded side file.
+
+### What the bundle leaves out
+
+Deliberately excluded: `runa11yCoreAcrossFrames`/`a11yCoreEnableFrameResponder`. Cross-frame scanning needs the embedded frame to load the engine and opt in too (see "Cross-frame scanning" below) — not a fit for a single dropped-in script tag. Use the npm package directly if you need it.
 
 ## Scoping a scan to part of the page
 
@@ -139,11 +161,11 @@ Notes for CI specifically:
 
 ### Cross-frame scanning (including cross-origin)
 
-`runa11yCoreInPage` only ever scans the single document it runs in — it has no visibility into `<iframe>` content, same-origin or not. For most uses that's fine (rules apply to the current document; a consumer running once per frame, e.g. once per content-script injection into `all_frames: true`, already covers every frame independently). But sometimes you want ONE scan's result to include what's inside embedded frames too — payment widgets, cookie-consent dialogs, third-party embeds — the same real scenario other engines' own cross-frame messaging protocols exist for.
+`runa11yCoreInPage` only ever scans the single document it runs in — it has no visibility into `<iframe>` content, same-origin or not. For most uses that's fine (rules apply to the current document; a consumer running once per frame, e.g. once per content-script injection into `all_frames: true`, already covers every frame independently). But sometimes you want ONE scan's result to include what's inside embedded frames too — payment widgets, cookie-consent dialogs, third-party embeds — which is what the cross-frame functions below are for.
 
-`runa11yCoreAcrossFrames`/`a11yCoreEnableFrameResponder` are a separate, additive pair of functions for exactly this — not needed at all if you're driving the browser with Puppeteer/Playwright (see "Pattern 2" above): an automation driver already reaches every frame unconditionally via CDP, which is strictly *better* than what's described here. This exists specifically for when there's **no automation driver** — a plain script/bundled widget/browser extension running inside the page itself, fully subject to the same-origin policy, exactly like other engines' equivalent mechanisms are.
+`runa11yCoreAcrossFrames`/`a11yCoreEnableFrameResponder` are a separate, additive pair of functions for exactly this — not needed at all if you're driving the browser with Puppeteer/Playwright (see "Pattern 2" above): an automation driver already reaches every frame unconditionally via CDP, which is strictly *better* than what's described here. This exists specifically for when there's **no automation driver** — a plain script/bundled widget/browser extension running inside the page itself, fully subject to the same-origin policy.
 
-**How it works**: a parent frame's `runa11yCoreAcrossFrames()` call pings each direct child `<iframe>`/`<frame>` via `postMessage`; if — and only if — that child has *also* called `a11yCoreEnableFrameResponder()` (its own opt-in to being scannable from above), it runs its own scan and replies with the result, which the parent includes. **A non-cooperating frame (the common case for most third-party embeds you don't control) is simply unreachable** — this mirrors the same real limitation other engines have for non-cooperating frames; it is not a gap `surea11y` closes that they don't have either.
+**How it works**: a parent frame's `runa11yCoreAcrossFrames()` call pings each direct child `<iframe>`/`<frame>` via `postMessage`; if — and only if — that child has *also* called `a11yCoreEnableFrameResponder()` (its own opt-in to being scannable from above), it runs its own scan and replies with the result, which the parent includes. **A non-cooperating frame (the common case for most third-party embeds you don't control) is simply unreachable** — the same-origin policy allows no way around it from inside the page.
 
 ```js
 // Inside the embedded/child page (e.g. a widget's own bundle), once, at load:
@@ -167,8 +189,8 @@ for (const frame of result.frames) {
 
 A few things worth knowing:
 - **Async, unlike the other two runners** — `postMessage` round-trips can't be synchronous, so this is a separate, Promise-returning pair rather than an `engineOptions` flag on `runa11yCoreInPage` (which stays synchronous, unchanged, for every existing caller).
-- **`engineOptions.pingWaitTime`** (default `500`ms) and **`engineOptions.frameWaitTime`** (default `60000`ms) control how long a child frame gets to answer a ping and a full run request respectively, matching the defaults other engines use for the equivalent options.
+- **`engineOptions.pingWaitTime`** (default `500`ms) and **`engineOptions.frameWaitTime`** (default `60000`ms) control how long a child frame gets to answer a ping and a full run request respectively.
 - **No jsdom/Node equivalent** — this is browser-only. jsdom's window/frame model doesn't meaningfully represent independent-realm cross-origin `postMessage`, and the feature has no purpose in Node anyway.
 - **Bundler-free, like `runa11yCoreInPage`** — both functions are fully self-contained (their own private copy of the rule catalog and every helper they need), so raw-source injection (a bookmarklet, a content script with no build step) works with zero bundler needed, exactly like `runa11yCoreInPage` already does. If you *do* use a normal bundler/`require`/`import`, that works too, unchanged.
-- **Cost of that self-containment**: `src/core.js` grew from ~1.86MB to ~3.1MB, since these two functions each needed their own complete private copy of the rule catalog and shared helpers rather than sharing the outer `RULE_IMPLS`. If this file's size ever becomes a real problem, the fix would be to drop the bundler-free requirement for just these two functions (accepting that cross-frame scanning in "plain script injection" mode needs a real bundler, unlike `runa11yCoreInPage` alone) rather than tripling the embedded catalog again for some future feature.
-- **No origin/identity check on the sender** beyond the message's own namespaced envelope — matching the same permissiveness other engines take here. Running a read-only scan and replying with DOM-derived results isn't a privileged operation; the content involved is no more sensitive than what's already rendered on the page.
+- **Cost of that self-containment**: `src/core.js` grew from ~1.86MB to ~3.1MB when these two functions landed, since each needed its own complete private copy of the rule catalog and shared helpers rather than sharing the outer `RULE_IMPLS`; it is ~4.3MB now, and grows with every rule added, three times over. If this file's size ever becomes a real problem, the fix would be to drop the bundler-free requirement for just these two functions (accepting that cross-frame scanning in "plain script injection" mode needs a real bundler, unlike `runa11yCoreInPage` alone) rather than tripling the embedded catalog again for some future feature.
+- **No origin/identity check on the sender** beyond the message's own namespaced envelope. Running a read-only scan and replying with DOM-derived results isn't a privileged operation; the content involved is no more sensitive than what's already rendered on the page.

package/docs/LIMITATIONS.md

@@ -6,7 +6,7 @@ Stated plainly and upfront, not left for you to discover. Every item here is a d
 
 surea11y is a **static DOM scan**: it reads the DOM tree and computed styles at one instant, with no ability to simulate user interaction, wait for async state changes, or measure real layout at arbitrary viewport sizes. These aren't missing rules — no rule implementation, however clever, can close them without a fundamentally different architecture (real browser automation driving actual keyboard/pointer events over time):
 
-- **Keyboard-trap detection** (WCAG 2.1.2) — requires simulating actual focus/keydown sequences and observing whether focus can escape. No static markup signal exists for this.
+- **Keyboard-trap detection** (WCAG 2.1.2) — requires driving focus around the page and watching where it lands, which no single read of the DOM can do. A technique that would work has been scoped out (see the keyboard-trap section of [`ACT_RULE_MAPPING.md`](./ACT_RULE_MAPPING.md#keyboard-trap-detection-scoping-notes)), but it would be this engine's first check to mutate the page it is inspecting, so it is not built and would not be part of a normal scan if it were. Nothing in static markup stands in for it in the meantime.
 - **Reflow / clipping at zoom** (WCAG 1.4.10) — requires real layout measurement (`clientWidth`/`scrollWidth`) at a simulated 320px-equivalent viewport. Unlike some CSS-declaration-based heuristics elsewhere in this engine, there is no static markup proxy for "does content get clipped at 400% zoom" at all.
 - **Dynamic/post-interaction state** — anything that only exists after a click, hover, or async data load (a modal's contents, a dropdown's options, form-validation error messages) is invisible to a scan of the page's *current* DOM. If your framework renders it eagerly (even off-screen/`hidden`), it's scannable; if it only exists after interaction, it isn't, unless you drive that interaction yourself before scanning (e.g. click the button, *then* scan).
 
@@ -14,17 +14,19 @@ surea11y is a **static DOM scan**: it reads the DOM tree and computed styles at
 
 - **jsdom (Node, no real browser) has no CSS layout engine.** Rules needing real geometry — most notably `target-size-minimum` (WCAG 2.5.8, needs real `getBoundingClientRect()`) — report `notApplicable` under plain jsdom rather than guess. Run under a real browser (Puppeteer/Playwright — see [`INTEGRATION.md`](./INTEGRATION.md) Pattern 2) to get real findings from these rules.
 - **`<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.
-- **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. Other engines running inside an actual loaded browser tab see the post-hydration state instead, so the two can disagree on exactly this class of element for reasons that have nothing to do with either engine's rule correctness. `aria-checked-state-mismatch` is deliberately `manual`/`cantTell`-capped for this exact reason 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.
+- **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.
+- **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.
 
-## Deliberately not attempted — judgment calls, not automatable safely
+## Not attempted: judgment calls that aren't automatable safely
 
 These have no comparably safe heuristic at this engine's confidence bar (`fail` must stay reserved for deterministic, high-confidence violations, full stop). Building them anyway would either catch almost nothing (too narrow to be useful) or risk real false positives (too broad to trust):
 
-- **"Is this heading/label text meaningful?"** — real headings and labels are enormously varied and legitimately short ("FAQ," "Name," "Overview" are all fine). Unlike link text (where a small, well-established "always bad" phrase list exists — see `link-name-quality`), there's no equivalent safe list here.
+- **"Is this heading/label text meaningful?"** — real headings and labels are enormously varied and legitimately short ("FAQ," "Name," "Overview" are all fine), so nothing decides from markup whether a heading describes the section under it or a label describes the field beside it. What *is* decidable is that some strings cannot describe anything: `heading-quality` and `form-control-label-quality` flag leftover placeholders, numbered template slots, filenames and URLs against curated exact-match lists, the same precision-over-recall trade-off `link-name-quality` makes. Both are `manual` rules capped at `cantTell` — they raise a candidate for review, they never assert the text is wrong.
 - **"Does this error message describe the problem?"** — what triggers a validation error and its content are almost always JS/validation-library-driven, invisible to a static scan in the first place; not just a heuristic-design problem.
 - **Fine-grained time-based-media sub-checks** (WCAG 1.2.x has ~8 distinct ACT-rule-level cases beyond what's built) — audio/video content itself is fundamentally unverifiable from static markup; the two broadest, safest cases are covered (`media-alternative-transcript-evidence`, `video-caption`), the narrower ones are not, by design.
 - **Images-of-text content analysis** (WCAG 1.4.5/1.4.9) — would need OCR-equivalent image understanding; out of scope for a static-markup engine.
 - **Motion-actuation controls** (WCAG 2.5.4) — niche, low real-world incidence; not prioritized, not structurally impossible.
+- **`img-alt-decorative`'s two ACT e88epe edge cases** — an `<img>` whose current network request state isn't "completely available" (still loading, or broken), and a `<canvas>` that is fully transparent (nothing actually drawn on it), are both exempt from ACT's own applicability. Neither is decidable from a static DOM scan (no image decoding, no canvas pixel readback), so both are left in scope rather than exempted — a rare false positive a human reviewer dismisses at a glance, safer than silently under-reporting a real excluded/undecorative element.
 
 ## What this means in practice
 

package/docs/OUTPUT_SCHEMA.md

@@ -15,7 +15,11 @@ This is the exact shape of the object returned by `runDomRulesInPage(...)` / `ru
 
 ```ts
 {
-  engine: { tag: string, schemaVersion: string },
+  engine: {
+    tag: string,
+    schemaVersion: string,
+    locale: { requested: string, resolved: string, reason: string }
+  },
   url: string | null,
   title: string | null,
   timestamp: string | null,
@@ -31,6 +35,8 @@ 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. |
 | `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. |
@@ -97,7 +103,7 @@ 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, high-confidence, `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 (other engines call these "Best Practices"; this engine calls them advisory `type: "manual"` rules). See [`WCAG_CONFORMANCE.md`](./WCAG_CONFORMANCE.md) for how these roll up.
+- **`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.
 - **`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`.
 
@@ -185,7 +191,11 @@ const result = runDomRulesInPage(
 
 ```json
 {
-  "engine": { "tag": "a11ycore", "schemaVersion": "1.0.0" },
+  "engine": {
+    "tag": "a11ycore",
+    "schemaVersion": "1.0.0",
+    "locale": { "requested": "en", "resolved": "en", "reason": "ok" }
+  },
   "url": "https://example.test/",
   "title": "Example",
   "timestamp": null,

package/docs/REPORT.md

@@ -15,6 +15,8 @@ Open `report.html` directly from disk. Works alongside any other output mode —
 - **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`.
 - **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).
+
 ## Library usage
 
 ```js
@@ -30,4 +32,4 @@ require('fs').writeFileSync('report.html', html);
 
 ## Scope
 
-This is a single-scan report — one point-in-time snapshot, not a dashboard tracking results across many scans over time. Multi-run history/trend tracking is a separate, larger concern (see the project roadmap's "Enterprise/compliance features" — historical trend tracking across scans) and isn't part of this tool.
+This is a single-scan report — one point-in-time snapshot, not a dashboard tracking results across many scans over time. Tracking results across many runs is a separate, larger concern and isn't part of this tool: keep the JSON from each scan and diff it yourself, or feed SARIF to a dashboard that already does history ([`SARIF.md`](./SARIF.md)).

package/docs/RULE_AUTHORING.md

@@ -52,7 +52,16 @@ function runInPage(ctx) { /* see Runtime Contract */ }
 module.exports = { id, meta, runInPage };
 ```
 
-No other exports.
+One optional fourth export: `applicability(ctx)`, a predicate the engine calls before
+`runInPage` to decide whether the rule is in scope for this run at all. Fourteen rules
+use it today (see §11.2). Export it alongside the other three when you need it:
+
+```js
+module.exports = { id, meta, runInPage, applicability };
+```
+
+Nothing else. `npm run validate:rules` enforces exactly this set, and rejects a fifth
+export.
 
 ---
 
@@ -78,7 +87,7 @@ Examples observed:
 
 ## 4) Meta Contract (all keys used by current rules)
 
-Every rule defines a `meta` object. In the rule set you uploaded, the union of meta keys is:
+Every rule defines a `meta` object. Across the shipped ruleset, the union of meta keys is:
 
 ### 4.1 Required top-level keys
 
@@ -132,6 +141,10 @@ 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
+forget. See [`I18N.md`](./I18N.md).
+
 #### `meta.tags`
 Tags are used for grouping/filtering. Typical tag families in this ruleset include:
 - WCAG tagging: `wcag2a`, `wcag111`
@@ -163,6 +176,31 @@ const meta = {
 
 ---
 
+## 4.3 Reporting an occurrence
+
+Build occurrences with `helpers.reportOccurrence(element, { summary, hint, i18n, data })`
+rather than assembling the object by hand:
+
+```js
+occurrences.push(helpers.reportOccurrence(el, { summary: '…', hint: '…' }));
+```
+
+It attaches the element for the engine to finalize, which is how `selector`,
+`html` and `structuralPath` get filled in centrally instead of in each rule.
+
+**This is a performance contract, not just a convenience.** Every occurrence
+gets a `structuralPath`. Given the element, the engine computes it directly.
+Given only a hand-built occurrence, it re-finds the element with
+`document.querySelector(selector)` — one DOM query per occurrence. That is
+fine for a rule reporting a single document-level finding, and quadratic for
+one reporting many: `region` hand-built its occurrences and took four minutes
+on a thousand-element page, against under a second afterwards.
+
+`perfStats.counters['structuralPath.selectorFallback']` counts how often the
+engine had to re-find an element, so a slow rule can be spotted without
+guessing. `tests/structural-path-fallback.test.js` fails if that count starts
+growing with page size.
+
 ## 5) i18n in occurrences (repo reality)
 
 Occurrences also support i18n via keys + params.
@@ -189,6 +227,29 @@ At normalization time, the engine:
 Translation strings use `{{paramName}}` placeholders.
 `params` is shallow-copied and passed into interpolation.
 
+**A param carries a value, never prose.** Element names, roles, attribute names,
+selectors, ids, counts and ratios are values: they read the same in every
+language, because the author will search their own source for them. An English
+word or sentence is not, and passing one means it stays English in every locale
+— with nothing to reveal it, since the key is present everywhere and coverage
+reports look complete.
+
+When a message varies by case, give each case its own key rather than
+interpolating the differing text:
+
+```js
+// wrong: the sentence lives in the rule, so no locale can reach it
+i18n: { hintKey: 'myRule_hint_fail', params: { advice: 'Replace it with role="list".' } }
+
+// right: one key per case, each translatable on its own
+i18n: { hintKey: 'myRule_hint_fail_directory', params: { role } }
+```
+
+`tests/i18n/i18n-translatable-strings.test.js` fails any dictionary value with
+no translatable text of its own, which catches the `"{{advice}}"` shape above.
+It cannot catch a param carrying prose into an otherwise-normal sentence, so
+that one is on you.
+
 ---
 
 ## 6) Helpers contract used by rules (ctx.helpers)
@@ -215,15 +276,19 @@ const nodes = helpers.queryAllSmart
   : helpers.queryAll('img');
 ```
 
-Shadow traversal is opt-in via engine option:
+Shadow traversal is on by default. It is the caller who opts out:
 ```js
-engineOptions: { includeShadowDom: true }
+engineOptions: { includeShadowDom: false }   // light DOM only
 ```
+So write the rule assuming open shadow roots are in scope; `queryAllSmart` honours the
+caller's choice for you. Closed roots are unreachable either way.
 
 ### 6.2 Reporting note for Shadow DOM
 
-Selectors do not pierce shadow boundaries, so a `selector` may not uniquely locate nodes in Shadow DOM.
-Therefore: **always include `html` in occurrences**.
+Selectors do not pierce shadow boundaries, so a `selector` may not uniquely locate a node
+inside a shadow root — which is why `html` matters as the "which element" signal there.
+You get both for free by reporting the element through `helpers.reportOccurrence` (§4.3);
+there is nothing extra to do for shadow DOM specifically.
 
 ---
 
@@ -237,7 +302,8 @@ data: {
 }
 ```
 
-This is consistent across your uploaded rule family.
+Pass the `eligInfo` you already computed for the element; the fallback object above is
+for the case where a rule has none to give.
 
 ---
 
@@ -266,34 +332,48 @@ Manual:
 
 ---
 
-## 9) Occurrence object shape (repo reality)
+## 9) Occurrence object shape
 
-Typical pattern:
+Report the element and let the engine finish the object (§4.3):
 
 ```js
-occurrences.push({
-  selector,
-  html,
-  summary: '…',
-  hint: '…',
-  i18n: { summaryKey: '…', hintKey: '…', params: { element: 'img' } },
-  data: { visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] } }
-});
+occurrences.push(
+  helpers.reportOccurrence(el, {
+    summary: '…',
+    hint: '…',
+    i18n: { summaryKey: '…', hintKey: '…', params: { element: 'img' } },
+    data: { visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] } }
+  })
+);
 ```
 
-Observed properties:
-- `selector` (or sometimes `selectorStr`)
-- `html`
+What a rule supplies:
 - `summary`
 - `hint`
 - `i18n` (`summaryKey`, `hintKey`, `params`)
 - `data` (includes `visibilityFilter`)
 
+What the engine fills in from the reported element:
+- `selector`
+- `html`
+- `structuralPath`
+
+Setting `selector`/`html` yourself still works and still wins — a handful of rules whose
+finding is not a single element (the contrast rules report text runs) do exactly that. It
+is the exception, not the pattern to copy.
+
 ---
 
 ## 10) Structured doc comment block
 
-Keep the structured header comment (`@rule`, `@atomic`, `@summary`, `@standard`, `@sc`, `@applicability`, `@expectation`).
+Keep the structured header comment (`@check`, `@atomic`, `@summary`, `@standard`, `@sc`,
+`@applicability`, `@expectation`). The id goes on `@check` — `@rule` is not a tag this
+repo uses. `docs/RULE_TEMPLATE.js` has the full block to copy.
+
+`@applicability` and `@expectation` are consumer-facing: `scripts/generate-rule-catalog.js`
+reads them straight from the source and publishes them per rule in
+[`RULE_CATALOG.md`](./RULE_CATALOG.md#rule-reference). Write them for someone deciding
+whether a result applies to their page, and rerun `npm run docs:rule-catalog` after editing them.
 
 ---
 
@@ -399,8 +479,9 @@ After adding or changing any fixture, regenerate the index:
 npm run fixtures:index
 ```
 
-This writes `tests/fixtures/INDEX.md` (human-readable) and `tests/fixtures/index.json`
+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). Commit both
+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
 alongside the fixture and test changes. A rule shipped without its fixture is treated
 the same as a rule shipped without tests — not done.