@surea11y/core 1.3.0 → 1.4.0

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.0",
+  "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,16 @@
     "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",
     "eslint": "^10.8.0",
     "eslint-config-prettier": "^10.1.8",
     "globals": "^17.8.0",
+    "jsdom": "^29.1.1",
     "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');

package/src/checks/automatic/aria-allowed-attr.js

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
@@ -19,57 +21,19 @@
  *   set already covers implicit-role elements without asserting anything
  *   role-specific; scope kept deliberately narrow to avoid false positives
  *   on implicit-role ARIA-in-HTML edge cases not modeled here.
- * - SUPPORTED_ATTRS_BY_ROLE widened 2026-07-21 (7 new roles), cross-checked
- *   against a widely-used reference engine's own per-role `allowedAttrs`
- *   table AND verified each addition is an unambiguous, well-established ARIA
- *   fact rather than a blind import:
- *   - `searchbox`: identical to the already-covered `textbox` (ARIA
- *     explicitly defines searchbox as textbox's subclass, same supported
- *     set).
- *   - `meter`: valuenow/valuemax/valuemin/valuetext, matching the
- *     already-covered slider/progressbar/scrollbar/spinbutton pattern
- *     (valuenow is also separately *required* on meter — see
- *     `aria-required-attr`'s own 2026-07-21 widening — but the two tables
- *     aren't unioned automatically, so it needs listing in both places).
- *   - `columnheader`/`rowheader`: same table-role family already covered
- *     by `gridcell`/`row` — sort/col-row-index/span are standard WAI-ARIA
- *     grid-model properties.
- *   - `dialog`/`alertdialog`: `aria-modal` — the spec-defining property
- *     that distinguishes a modal from a non-modal dialog; unambiguous.
- *   - `listitem`: level/posinset/setsize — standard flat-representation-
- *     of-hierarchy properties, same family as the already-covered
- *     `treeitem`.
- *   - `menu`/`menubar`/`toolbar`: activedescendant/orientation — standard
- *     composite-widget properties, same family as the already-covered
- *     `tablist`.
- * - SUPPORTED_ATTRS_BY_ROLE full-reconciliation pass 2026-07-28: the
- *   2026-07-21 pass deliberately deferred ~61 roles where a widely-used
- *   reference engine allows `aria-expanded`, treating it as too thin/
- *   near-universal to import blindly. Checked against `aria-query`
- *   (tracks the published WAI-ARIA 1.2 Recommendation, 6 June 2023 — the
- *   latest actually-published version, as opposed to the in-progress 1.3
- *   Editor's Draft) instead of that reference engine directly, because its own
- *   source comments (`// Spec difference: Aria-expanded removed in 1.2`)
- *   show that most of its `aria-expanded` allowances are deliberate
- *   ARIA-1.1 legacy/AT-compat carryovers it keeps on purpose, not
- *   current-spec facts — importing them wholesale would have re-added
- *   exactly the kind of unverified allowance the 07-21 pass was avoiding.
- *   `aria-query`'s per-role tables (with superclass inheritance resolved,
- *   e.g. `aria-activedescendant` via the abstract `composite` role) gave a
- *   spec-grounded diff instead. Net changes from that diff:
- *   - `aria-expanded` added to: checkbox, columnheader, gridcell, listbox,
- *     menuitemcheckbox, menuitemradio, row, rowheader, switch, tab —
- *     confirmed present in current spec for these roles specifically
- *     (unlike e.g. `listitem`, `dialog`, `alertdialog`, `heading`, which
- *     the spec does NOT list it for — those stay excluded).
- *   - `aria-activedescendant` added to: combobox, grid, listbox,
- *     radiogroup, row, spinbutton, tablist, treegrid (inherited from the
- *     abstract `composite` role for any composite/managed-focus widget).
- *   - `aria-readonly`/`aria-required` added to: switch, menuitemcheckbox,
- *     menuitemradio. `aria-posinset`/`aria-setsize` added to: tab, radio,
- *     menuitemcheckbox, menuitemradio. `aria-level` added to: tablist.
- *   - `tree`'s `aria-readonly` removed: not in aria-query's resolved
- *     props for `tree` (was an unverified carryover, not spec-backed).
+ * - SUPPORTED_ATTRS_BY_ROLE holds unambiguous, well-established ARIA facts:
+ *   subclass relationships like `searchbox`==`textbox`; same-family widget
+ *   properties like `columnheader`/`rowheader` sort/col-row-index/span
+ *   matching `gridcell`/`row`; spec-defining properties like `dialog`/
+ *   `alertdialog` `aria-modal`. `aria-expanded` entries are checked against
+ *   `aria-query` (which tracks the published WAI-ARIA 1.2 Recommendation,
+ *   with superclass inheritance resolved, e.g. `aria-activedescendant` via
+ *   the abstract `composite` role) rather than imported wholesale, since
+ *   much of the wider ARIA-1.1 `aria-expanded` allowance list is legacy/
+ *   AT-compat carryover, not current-spec fact.
+ *   `meter`'s valuenow/valuemax/valuemin/valuetext is also separately
+ *   *required* (see `aria-required-attr`), but the two tables aren't
+ *   unioned automatically, so it's listed in both places.
  * - Not rule-gated on isAccTreeEligible: this remains a static-markup
  *   property, while engine-level hidden-subtree filtering still applies
  *   unless engineOptions.includeHiddenElements is true.

package/src/checks/automatic/aria-allowed-role.js

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**

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

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**

package/src/checks/automatic/aria-conditional-attr.js

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
@@ -16,13 +18,12 @@
  *   `"false"` silently drops the error message from the accessibility
  *   tree — authors almost always intend it to be exposed.
  * @implementation-notes
- * - This is deliberately narrow: a widely-used reference engine's own
- *   `aria-conditional-attr` rule covers a broader table of attribute/condition
- *   pairs. This rule implements only the one pairing (`aria-errormessage` /
- *   `aria-invalid`) that is unambiguous and explicitly stated in the
- *   ARIA spec, to keep `fail` high-confidence — matches this repo's
- *   established pattern (see `aria-required-attr`/`aria-prohibited-attr`
- *   for the same "narrower than that reference engine, but zero false positives"
+ * - This is deliberately narrow: the broader space is a table of many
+ *   attribute/condition pairs. This rule implements only the one pairing
+ *   (`aria-errormessage` / `aria-invalid`) that is unambiguous and
+ *   explicitly stated in the ARIA spec, to keep `fail` high-confidence —
+ *   matches this repo's established pattern (see `aria-required-attr`/
+ *   `aria-prohibited-attr` for the same "narrow but zero false positives"
  *   trade-off).
  * - Does not check whether the `aria-errormessage` ID reference itself
  *   resolves to an existing element — that is `aria-valid-attr-value`'s

package/src/checks/automatic/aria-deprecated-role.js

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
@@ -12,9 +14,8 @@
  *   declare — either because WAI-ARIA has deprecated it (e.g. "directory",
  *   superseded by role="list") or because it's reserved for user-agent-
  *   internal use only, not a spec deprecation but the same "valid token,
- *   prohibited for authors" shape (role="generic" — verified 2026-07-20
- *   against both the WAI-ARIA 1.2 spec text and MDN's explicit "It should
- *   not be used by web authors" guidance).
+ *   prohibited for authors" shape (role="generic" — per WAI-ARIA 1.2 and
+ *   MDN's "It should not be used by web authors" guidance).
  * @expectation
  *   The role in use is neither deprecated nor author-prohibited. This is a
  *   distinct, atomic decision from aria-roles-valid (existence/

package/src/checks/automatic/aria-hidden-body.js

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
@@ -14,10 +16,10 @@
  * @expectation
  *   <body> does not have aria-hidden="true". Hiding the document body
  *   removes the entire page's content and structure from the
- *   accessibility tree at once — a widely-used reference engine tags this under both 1.3.1
- *   (Info and Relationships: the page's structure becomes entirely
- *   non-determinable) and 4.1.2 (Name, Role, Value: nothing in the
- *   document exposes a role/name/value any longer).
+ *   accessibility tree at once — both 1.3.1 (Info and Relationships: the
+ *   page's structure becomes entirely non-determinable) and 4.1.2 (Name,
+ *   Role, Value: nothing in the document exposes a role/name/value any
+ *   longer) apply.
  */
 
 const id = 'aria-hidden-body';

package/src/checks/automatic/aria-hidden-focus.js

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
@@ -12,7 +14,7 @@
  *   No element with aria-hidden="true" may itself be focusable, and no focusable element
  *   may exist within an aria-hidden="true" subtree.
  *
- * Notes on parity with a widely-used reference engine's aria-hidden-focus check:
+ * Notes:
  * - Focusability is computed via ctx.helpers.getFocusableInfo (native + tabindex + contenteditable).
  * - Elements that are not rendered (e.g., display:none, visibility:hidden, [hidden]) are excluded.
  * - Elements hidden via CSS in ways that still allow keyboard focus (e.g., opacity:0, off-screen, clip)
@@ -485,14 +487,11 @@ function runInPage(ctx) {
     // An explicit negative tabindex removes the element from the keyboard
     // tab sequence entirely, regardless of tag — the standard, WAI-
     // recommended technique for safely hiding focusable content behind
-    // aria-hidden (verified against a widely-used reference engine's own aria-hidden-focus check,
-    // which requires tabbability — not raw focusability — via its
-    // `focusable-not-tabbable` sub-check; confirmed via a real page:
-    // Wikipedia's sticky header uses <button tabindex="-1">/<a tabindex="-1">
-    // inside aria-hidden divs, a correct pattern this rule was previously
-    // flagging as a false positive). Such an element is still
-    // programmatically focusable (script could call .focus()), but that's
-    // not what "no focusable content behind aria-hidden" cares about.
+    // aria-hidden (e.g. <button tabindex="-1"> / <a tabindex="-1"> inside
+    // an aria-hidden container). This cares about tabbability, not raw
+    // focusability. Such an element is still programmatically focusable
+    // (script could call .focus()), but that's not what "no focusable
+    // content behind aria-hidden" cares about.
     const explicitTabindex = trim(el.getAttribute('tabindex'));
     if (
       explicitTabindex !== '' &&
@@ -640,10 +639,9 @@ function runInPage(ctx) {
     // cheaper first cannot change which elements end up in the bucket —
     // it only skips the expensive check for the (typically vast) majority
     // of focusable candidates that were never inside an aria-hidden root
-    // in the first place. On a real page with a large focusable-candidate
-    // count and a complex stylesheet (Daily Mail: ~1400 links, ~3600 CSS
-    // rules), this cut this check's runtime from ~30s to well under 1s —
-    // a pure ordering change, not a behavior change.
+    // in the first place. On pages with many focusable candidates and a
+    // large stylesheet this is a big speedup, and a pure ordering change,
+    // not a behavior change.
     const rootEl = closestAriaHiddenTrue(el);
     if (!rootEl) continue;
 
@@ -777,6 +775,7 @@ function runInPage(ctx) {
       hint: downgradedToCantTell
         ? 'Verify this is an intentional focus sentinel/focus-trap handoff and that keyboard users never remain on hidden focus targets.'
         : 'Remove focusability from descendants or remove aria-hidden; ensure focus and accessibility trees stay aligned.',
+      occurrenceOutcome: downgradedToCantTell ? 'cantTell' : 'fail',
       i18n: {
         summaryKey: downgradedToCantTell
           ? 'ariaHidden_focus_summary_cantTell_redirect'