@surea11y/core 1.3.0 → 1.4.1

package/docs/CI_INTEGRATIONS.md

@@ -1,6 +1,6 @@
 # CI/CD pipeline integrations
 
-Ready-to-paste templates wrapping the [CLI](./CLI.md) (`npx @surea11y/core scan ...`) in GitHub Actions and Bitbucket Pipelines. If you're calling the library directly from your own Node script instead of the CLI, see [`INTEGRATION.md`](./INTEGRATION.md#ci-gating-a-build-on-the-result) instead — this page is specifically about the CLI as a pipeline step.
+Ready-to-paste templates wrapping the [CLI](https://github.com/SureA11y/cli#readme) (`npx @surea11y/cli scan ...`) in GitHub Actions and Bitbucket Pipelines. If you're calling the library directly from your own Node script instead of the CLI, see [`INTEGRATION.md`](./INTEGRATION.md#ci-gating-a-build-on-the-result) instead — this page is specifically about the CLI as a pipeline step.
 
 All of these rely on the CLI's own exit codes (`0` clean, `1` at least one — or one *new*, with `--baseline` — `fail` outcome, `2` a usage/scan error) to gate the pipeline; no extra scripting is required for basic pass/fail gating.
 
@@ -21,7 +21,7 @@ jobs:
         with:
           node-version: 20
       - run: npm ci && npm run build   # produce whatever static HTML you're scanning
-      - run: npx @surea11y/core scan ./dist/index.html
+      - run: npx @surea11y/cli scan ./dist/index.html
 ```
 
 This fails the job the moment any `fail` outcome is found. For an existing site with pre-existing violations, see the baseline variant below instead of disabling the step.
@@ -30,13 +30,13 @@ This fails the job the moment any `fail` outcome is found. For an existing site
 
 ```sh
 # Once, locally: record every current fail occurrence, commit the file.
-npx @surea11y/core scan ./dist/index.html --write-baseline a11y-baseline.json
+npx @surea11y/cli scan ./dist/index.html --write-baseline a11y-baseline.json
 git add a11y-baseline.json
 ```
 
 ```yaml
       - run: npm ci && npm run build
-      - run: npx @surea11y/core scan ./dist/index.html --baseline a11y-baseline.json
+      - run: npx @surea11y/cli scan ./dist/index.html --baseline a11y-baseline.json
 ```
 
 See [`BASELINE.md`](./BASELINE.md) for what counts as "known" vs. "new", and how to regenerate the file as violations get fixed.
@@ -63,7 +63,7 @@ jobs:
           node-version: 20
       - run: npm ci && npm run build
       - name: Scan (report, don't fail the job here)
-        run: npx @surea11y/core scan ./dist/index.html --baseline a11y-baseline.json --sarif results.sarif
+        run: npx @surea11y/cli scan ./dist/index.html --baseline a11y-baseline.json --sarif results.sarif
         continue-on-error: true
         id: scan
       - name: Upload SARIF to Code Scanning
@@ -91,7 +91,7 @@ pipelines:
           script:
             - npm ci
             - npm run build
-            - npx @surea11y/core scan ./dist/index.html --baseline a11y-baseline.json --html a11y-report.html
+            - npx @surea11y/cli scan ./dist/index.html --baseline a11y-baseline.json --html a11y-report.html
           artifacts:
             - a11y-report.html
 ```
@@ -100,4 +100,4 @@ The step fails the pipeline on the CLI's exit code exactly like any other `scrip
 
 ## Free-tier/private-repo minute limits
 
-If your pipeline provider's free tier is minute-limited (Bitbucket Pipelines' free tier is 50 build-minutes/month on private workspaces, for example), a `jsdom`-based scan of static/server-rendered HTML (what the CLI does) is far cheaper than driving a real browser — see [`CLI.md`](./CLI.md#what-it-can-and-cant-scan) for what that trades away (no client-rendered content, no real CSS layout).
+If your pipeline provider's free tier is minute-limited (Bitbucket Pipelines' free tier is 50 build-minutes/month on private workspaces, for example), a `jsdom`-based scan of static/server-rendered HTML (what the CLI does) is far cheaper than driving a real browser — see [the CLI docs](https://github.com/SureA11y/cli/blob/main/docs/CLI.md#what-it-can-and-cant-scan) for what that trades away (no client-rendered content, no real CSS layout).

package/docs/ENGINE_OPTIONS.md

@@ -224,7 +224,7 @@ See the option-by-option table above for anything not shown here, and the `custo
 
 Every shipped rule is baked into `src/core.js` at build time. `engineOptions.customRules` is the runtime escape hatch: an array of rule descriptors registered for that one call only — nothing is added to the static catalog (`getRulesCatalog()`/`getChecksCatalog()`), and nothing persists between calls. This is deliberate, not a limitation to work around: surea11y already takes fresh `engineOptions` per call with no mutable global config (unlike some other engines, which need a `configure()`/`reset()` step against a shared runtime), and custom rules follow that same per-call model.
 
-Calling the library directly is one way in; the CLI also exposes this via `--custom-rules <path>` (a local file, loaded once per scan) — see [`CLI.md`](./CLI.md#custom-rules).
+Calling the library directly is one way in; the CLI also exposes this via `--custom-rules <path>` (a local file, loaded once per scan) — see [the CLI docs](https://github.com/SureA11y/cli/blob/main/docs/CLI.md#custom-rules).
 
 A descriptor has the *same shape as an internal rule module's own export* — if you already know how to write a rule file for this engine, you already know this API:
 

package/docs/I18N.md

@@ -6,10 +6,12 @@ Every rule's title/description, and every occurrence's summary/hint, is localize
 
 | Locale | File | Keys | Coverage vs. English |
 |---|---|---|---|
-| `en` (English) | `src/i18n/en.js` | 600 | 100% (the canonical/fallback set) |
-| `fr` (French) | `src/i18n/fr.js` | 600 | 100% |
+| `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% |
 
-Both 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`, `fr.js` needs the same key added, or it silently falls back to English for that string (see the fallback behavior below). There's no automated check for this yet; diff `Object.keys(require('./src/i18n/en.js'))` against `fr.js` after adding a rule to catch drift before it ships.
+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.
 
 ## Selecting a locale
 
@@ -17,7 +19,7 @@ Both locales are fully translated as of this writing. That won't stay automatica
 runDomRulesInPage(url, null, { locale: 'fr' }, null);
 ```
 
-Default is `'en'` if omitted. Any string is accepted — an unrecognized locale (e.g. `'de'`, 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 (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.
 
 ## Fallback behavior (per-string, not per-locale)
 
@@ -40,8 +42,9 @@ Both are included in the result alongside the already-resolved text, so you can
 
 ## Contributing a translation
 
-1. Open `src/i18n/en.js` — it's the canonical key list (590 entries, one `module.exports` object of `key: string`).
-2. Add matching keys to `src/i18n/<locale>.js` (create the file if the locale doesn't exist yet — follow `fr.js`'s structure exactly: `'use strict'; module.exports = { ...keys };`).
-3. 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` does today. Ship what you have.
-4. Keep `{{placeholder}}` tokens in translated strings exactly as they appear in the English source — they're substituted verbatim regardless of locale (e.g. `{{element}}`, `{{role}}`).
-5. Run `npm run build && npm test` — there's no locale-completeness test today (a partial locale is valid, not a failure), but this confirms nothing else broke.
+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.

package/docs/INTEGRATION.md

@@ -130,7 +130,7 @@ if (failures.length > 0) {
 
 Notes for CI specifically:
 - `cantTell` outcomes are advisory by design (see [`OUTPUT_SCHEMA.md`](./OUTPUT_SCHEMA.md#outcome-values)) — most teams log them without failing the build, since they require human judgment the CI run can't make.
-- For "only fail on *new* violations," the CLI has a built-in baseline/allowlist mechanism (`--write-baseline`/`--baseline`, see [`BASELINE.md`](./BASELINE.md)). Calling the library directly, the same matching logic is available as `buildBaselineEntries(result)`/`matchBaseline(result, baselineEntries)` from `require('@surea11y/core/src/baseline')` — or diff `checksResults` against a saved prior run yourself if your pages don't fit that model (see `BASELINE.md`'s "known limitation").
+- For "only fail on *new* violations," the CLI has a built-in baseline/allowlist mechanism (`--write-baseline`/`--baseline`, see [`BASELINE.md`](./BASELINE.md)). Calling the library directly, the same matching logic is available as `buildBaselineEntries(result)`/`matchBaseline(result, baselineEntries)` from `require('@surea11y/core/baseline')` — or diff `checksResults` against a saved prior run yourself if your pages don't fit that model (see `BASELINE.md`'s "known limitation").
 - Prefer Pattern 1 (jsdom) in CI unless you specifically need real-browser layout — it avoids the extra weight of a Puppeteer/Playwright + browser-binary install in your pipeline.
 
 ## Browser extension context

package/docs/LIMITATIONS.md

@@ -14,7 +14,7 @@ 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/core scan <url>`) specifically fetches static HTML only, with no JS execution — see [`CLI.md`](./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.
+- **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.
 
 ## Deliberately not attempted — judgment calls, not automatable safely
 

package/docs/REPORT.md

@@ -18,7 +18,7 @@ Open `report.html` directly from disk. Works alongside any other output mode —
 ## Library usage
 
 ```js
-const { renderHtmlReport } = require('@surea11y/core/src/report');
+const { renderHtmlReport } = require('@surea11y/core/report');
 const { runDomRulesInPage } = require('@surea11y/core');
 
 const result = runDomRulesInPage(url, null, {}, null);

package/docs/RULE_CATALOG.md

@@ -2,11 +2,11 @@
 
 Generated from the compiled engine's own catalog (`getChecksCatalog()`/`getRulesCatalog()`) — run `node scripts/generate-rule-catalog.js` after `npm run build` to regenerate this file whenever rules change. Do not hand-edit.
 
-**125 rules total: 77 automatic (WCAG-normative, can return `fail`), 48 manual (advisory/judgment-required, capped at `cantTell`). 101 carry at least one formal WCAG Success Criterion mapping.**
+**125 rules total: 76 automatic (WCAG-normative, can return `fail`), 49 manual (advisory/judgment-required, capped at `cantTell`). 101 carry at least one formal WCAG Success Criterion mapping.**
 
 See [`OUTPUT_SCHEMA.md`](./OUTPUT_SCHEMA.md) for what `type`/`confidence`/`severity` mean on a scan result, and [`WCAG_CONFORMANCE.md`](./WCAG_CONFORMANCE.md) for how these roll up to an SC-level conformance claim. For WCAG-facet-level coverage-gap tracking (which parts of an SC are and aren't automatable yet), see `coverage/coverage-report.md` instead — that one is organized by facet, this one by rule.
 
-## Automatic rules (77) — can return `fail`
+## Automatic rules (76) — can return `fail`
 
 | Rule ID | Title | WCAG SC | Level | Confidence | Default severity |
 |---|---|---|---|---|---|
@@ -15,7 +15,7 @@ See [`OUTPUT_SCHEMA.md`](./OUTPUT_SCHEMA.md) for what `type`/`confidence`/`sever
 | `aria-allowed-role` | Explicit role must be permitted for its host element | 4.1.2 | A | high | moderate |
 | `aria-braille-equivalent` | aria-braillelabel/aria-brailleroledescription must have a non-braille equivalent | 4.1.2 | A | high | serious |
 | `aria-conditional-attr` | aria-errormessage requires aria-invalid to be set to a non-false value | 4.1.2 | A | high | serious |
-| `aria-deprecated-role` | role attribute must not use a deprecated or author-prohibited ARIA role | 4.1.2 | A | high | moderate |
+| `aria-deprecated-role` | role attribute should not use a deprecated or author-discouraged ARIA role | 4.1.2 | A | high | moderate |
 | `aria-hidden-body` | The document <body> must not be aria-hidden | 1.3.1, 4.1.2 | A | high | critical |
 | `aria-hidden-focus` | ARIA hidden elements must not be focusable | 2.4.7, 4.1.2 | AA | high | serious |
 | `aria-prohibited-attr` | ARIA naming attributes must not be used on roles that prohibit them | 4.1.2 | A | high | moderate |
@@ -28,10 +28,9 @@ See [`OUTPUT_SCHEMA.md`](./OUTPUT_SCHEMA.md) for what `type`/`confidence`/`sever
 | `aria-valid-attr` | aria-* attributes must be real, defined ARIA attributes | 4.1.2 | A | high | serious |
 | `aria-valid-attr-value` | aria-* attribute values must match their declared type | 4.1.2 | A | high | serious |
 | `autocomplete-valid` | autocomplete attribute must be a valid autofill value | 1.3.5 | AA | high | moderate |
-| `avoid-inline-spacing` | Inline style must not force text spacing with !important | 1.4.12 | AA | high | moderate |
+| `avoid-inline-spacing` | Inline style must not force text spacing below the WCAG metric | 1.4.12 | AA | high | moderate |
 | `binary-control-name-present` | Binary controls have an accessible name | 4.1.2 | A | high | serious |
 | `button-name-present` | Buttons have an accessible name | 4.1.2 | A | high | serious |
-| `bypass-blocks-present` | Page must provide a way to bypass repeated blocks | 2.4.1 | A | medium | serious |
 | `canvas-text-alternative-present` | <canvas> must provide a text alternative | 1.1.1 | A | high | serious |
 | `combobox-name-present` | Comboboxes have an accessible name | 4.1.2 | A | high | serious |
 | `contrast-computable` | Color contrast is computable for rendered text | 1.4.3, 1.4.6 | AAA | high | serious |
@@ -88,7 +87,7 @@ See [`OUTPUT_SCHEMA.md`](./OUTPUT_SCHEMA.md) for what `type`/`confidence`/`sever
 | `valid-lang` | Element lang attribute must be syntactically valid | 3.1.2 | AA | high | moderate |
 | `video-poster-text-alternative-present` | <video> poster must have a text alternative | 1.1.1 | A | medium | serious |
 
-## Manual rules (48) — advisory, capped at `cantTell`
+## Manual rules (49) — advisory, capped at `cantTell`
 
 | Rule ID | Title | WCAG SC | Level | Confidence | Default severity |
 |---|---|---|---|---|---|
@@ -97,6 +96,7 @@ See [`OUTPUT_SCHEMA.md`](./OUTPUT_SCHEMA.md) for what `type`/`confidence`/`sever
 | `area-alt-quality` | <area> alt text must be appropriate (manual review) | 1.1.1 | A | medium | minor |
 | `aria-checked-state-mismatch` | Native checkbox/radio aria-checked should match its actual state | 4.1.2 | A | medium | moderate |
 | `aria-text` | role="text" elements should have no focusable descendants | — | — | medium | minor |
+| `bypass-blocks-present` | Page must provide a way to bypass repeated blocks | 2.4.1 | A | medium | moderate |
 | `canvas-text-alternative-quality` | <canvas> text alternative must be appropriate (manual review) | 1.1.1 | A | medium | minor |
 | `css-hidden-focus` | Focusable elements must not be visually hidden | 2.4.7 | AA | low | serious |
 | `embed-text-alternative-quality` | <embed> text alternative must be appropriate (manual review) | 1.1.1 | A | medium | minor |

package/package.json

@@ -1,20 +1,50 @@
 {
   "name": "@surea11y/core",
-  "version": "1.3.0",
-  "description": "Lightweight DOM rules accessibility core with modular rules.",
+  "version": "1.4.1",
+  "description": "Deterministic WCAG 2.2 accessibility engine that tells you what it can't tell you. Zero dependencies.",
+  "keywords": [
+    "accessibility",
+    "a11y",
+    "wcag",
+    "wcag21",
+    "wcag22",
+    "accessibility-testing",
+    "a11y-testing",
+    "audit",
+    "aria",
+    "contrast",
+    "sarif",
+    "zero-dependencies",
+    "jsdom",
+    "playwright",
+    "puppeteer",
+    "selenium",
+    "cypress",
+    "webdriverio",
+    "jest",
+    "vitest"
+  ],
   "main": "src/index.js",
   "bin": {
-    "surea11y": "bin/core.js"
+    "surea11y-core": "bin/surea11y-core.js"
+  },
+  "exports": {
+    ".": "./src/index.js",
+    "./baseline": "./src/baseline.js",
+    "./report": "./src/report.js",
+    "./sarif": "./src/sarif.js",
+    "./browser": "./surea11y.browser.js",
+    "./package.json": "./package.json"
   },
   "author": "Jorge Rumoroso",
   "license": "MPL-2.0",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/rumoroso/surea11y-core.git"
+    "url": "git+https://github.com/SureA11y/core.git"
   },
-  "homepage": "https://github.com/rumoroso/surea11y-core#readme",
+  "homepage": "https://github.com/SureA11y/core#readme",
   "bugs": {
-    "url": "https://github.com/rumoroso/surea11y-core/issues"
+    "url": "https://github.com/SureA11y/core/issues"
   },
   "engines": {
     "node": "^20.19.0 || ^22.13.0 || >=24.0.0"
@@ -23,8 +53,13 @@
     "access": "public"
   },
   "files": [
-    "src",
-    "bin",
+    "src/index.js",
+    "src/core.js",
+    "src/baseline.js",
+    "src/report.js",
+    "src/sarif.js",
+    "src/checks/**/*.js",
+    "bin/surea11y-core.js",
     "surea11y.browser.js",
     "docs/**/*.md",
     "README.md",
@@ -33,8 +68,7 @@
     "!docs/RULE_TEMPLATE.md",
     "!docs/RULE_TEST_TEMPLATE.md",
     "!docs/RULE_TEST_AUTHORING.md",
-    "!docs/TEST_OUTCOME_STABILITY.md",
-    "!src/explain"
+    "!docs/TEST_OUTCOME_STABILITY.md"
   ],
   "scripts": {
     "lint": "eslint .",
@@ -43,8 +77,8 @@
     "format:check": "prettier --check \"src/**/*.js\" \"bin/**/*.js\" \"scripts/**/*.js\" \"tests/**/*.js\" \"eslint.config.js\"",
     "build": "node scripts/build-core.js && node scripts/build-browser.js",
     "pretest": "playwright install chromium",
-    "test": "npm run build && node scripts/run-tests.js",
-    "test:coverage": "npm run build && node scripts/run-tests.js --experimental-test-coverage --test-coverage-include=src/**/*.js --test-coverage-include=bin/**/*.js",
+    "test": "npm run format:check && npm run build && node scripts/run-tests.js",
+    "test:coverage": "npm run build && node scripts/run-tests.js --experimental-test-coverage --test-coverage-include=src/**/*.js",
     "test:contrast-helpers": "node tests/contrast-helpers.test.js",
     "helpers-perf-bench": "node --expose-gc scripts/dom-helpers-perf-bench.js",
     "engine-perf-bench": "node --expose-gc scripts/engine-perf-bench.js  --profileRules=true --iters=25 --top=15",
@@ -56,16 +90,18 @@
     "fixtures:index": "node scripts/generate-fixture-index.js",
     "docs:rule-catalog": "npm run build && node scripts/generate-rule-catalog.js",
     "validate:automatic-rules": "npm run build && node scripts/validate-all-rules.js src/checks/automatic",
-    "validate:manual-rules": "npm run build && node scripts/validate-all-rules.js src/checks/manual"
-  },
-  "dependencies": {
-    "jsdom": "^29.1.1"
+    "validate:manual-rules": "npm run build && node scripts/validate-all-rules.js src/checks/manual",
+    "i18n:new": "node scripts/i18n-scaffold.js",
+    "i18n:report": "node scripts/i18n-report.js"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
+    "aria-query": "^5.3.2",
     "eslint": "^10.8.0",
     "eslint-config-prettier": "^10.1.8",
     "globals": "^17.8.0",
+    "jsdom": "^29.1.1",
+    "language-subtag-registry": "^0.4.2",
     "playwright": "^1.62.1",
     "prettier": "^3.9.6"
   }

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

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
@@ -199,12 +201,8 @@ function runInPage(ctx) {
     }
 
     // A non-empty title attribute is HTML-AAM's own next fallback naming
-    // source once alt is entirely absent -- also accepted by a widely-used
-    // reference engine's equivalent area-alt rule (non-empty-title, same "any" list as
-    // non-empty-alt/aria-label/aria-labelledby). See img-alt-present's
-    // sibling fix (2026-07-23, AliExpress's title-only logo <img>) for
-    // the real page this was found via -- same gap, same fix, different
-    // element.
+    // source once alt is entirely absent. Same gap img-alt-present handles
+    // for <img title="..."> with no alt.
     const titleRaw = (() => {
       try {
         return el.getAttribute('title');