@surea11y/core 1.6.0 → 1.7.0

package/docs/RULE_CATALOG.md

@@ -2,29 +2,29 @@
 
 Generated from the compiled engine's own catalog (`getChecksCatalog()`/`getRulesCatalog()`) and each rule's source header. Run `node scripts/generate-rule-catalog.js` after `npm run build` to regenerate this file whenever rules change. Do not hand-edit.
 
-**130 rules total: 78 automatic (WCAG-normative, can return `fail`), 52 manual (advisory/judgment-required, capped at `cantTell`). 106 carry at least one formal WCAG Success Criterion mapping.**
+**133 rules total: 79 automatic (WCAG-normative, can return `fail`), 54 manual (advisory/judgment-required, capped at `cantTell`). 107 carry at least one formal WCAG Success Criterion mapping.**
 
 The tables below are an index; [rule reference](#rule-reference) carries each rule's description, what it applies to and what it expects.
 
 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 (78), can return `fail`
+## Automatic rules (79), can return `fail`
 
 | Rule ID | Title | WCAG SC | Level | Confidence | Default severity |
 |---|---|---|---|---|---|
 | [`area-alt-present`](#area-alt-present) | <area> must have an alt attribute | 1.1.1 | A | high | serious |
 | [`aria-allowed-attr`](#aria-allowed-attr) | aria-* attributes must be permitted for the element’s role | 4.1.2 | A | medium | moderate |
-| [`aria-allowed-role`](#aria-allowed-role) | Explicit role must be permitted for its host element | 4.1.2 | A | high | moderate |
-| [`aria-braille-equivalent`](#aria-braille-equivalent) | aria-braillelabel/aria-brailleroledescription must have a non-braille equivalent | 4.1.2 | A | high | serious |
-| [`aria-conditional-attr`](#aria-conditional-attr) | aria-errormessage requires aria-invalid to be set to a non-false value | 4.1.2 | A | high | serious |
+| [`aria-allowed-role`](#aria-allowed-role) | Explicit role must be permitted for its host element | — | — | high | moderate |
+| [`aria-braille-equivalent`](#aria-braille-equivalent) | aria-braillelabel/aria-brailleroledescription must have a non-braille equivalent | 4.1.2 | A | high | moderate |
+| [`aria-conditional-attr`](#aria-conditional-attr) | aria-errormessage requires aria-invalid to be set to a non-false value | 4.1.2 | A | high | moderate |
 | [`aria-deprecated-role`](#aria-deprecated-role) | role attribute should not use a deprecated or author-discouraged ARIA role | 4.1.2 | A | high | moderate |
 | [`aria-hidden-body`](#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-focus) | ARIA hidden elements must not be focusable | 2.4.7, 4.1.2 | AA | high | serious |
 | [`aria-prohibited-attr`](#aria-prohibited-attr) | ARIA naming attributes must not be used on roles that prohibit them | 4.1.2 | A | high | moderate |
-| [`aria-prohibited-children`](#aria-prohibited-children) | Container roles must not own a child with a disallowed role | 4.1.2 | A | medium | moderate |
+| [`aria-prohibited-children`](#aria-prohibited-children) | Container roles must not own a child with a disallowed role | 1.3.1 | A | medium | moderate |
 | [`aria-required-attr`](#aria-required-attr) | Roles with a required ARIA state/property must carry it | 4.1.2 | A | high | serious |
-| [`aria-required-children`](#aria-required-children) | Container roles must own at least one required child role | 4.1.2 | A | medium | moderate |
-| [`aria-required-parent`](#aria-required-parent) | Roles requiring a specific context role must be in that context | 4.1.2 | A | medium | moderate |
+| [`aria-required-children`](#aria-required-children) | Container roles must own at least one required child role | 1.3.1 | A | medium | moderate |
+| [`aria-required-parent`](#aria-required-parent) | Roles requiring a specific context role must be in that context | 1.3.1 | A | medium | moderate |
 | [`aria-role-name-present`](#aria-role-name-present) | ARIA roles that require an accessible name have one | 4.1.2 | A | high | serious |
 | [`aria-roles-valid`](#aria-roles-valid) | role attribute must be a valid, non-abstract ARIA role | 4.1.2 | A | high | serious |
 | [`aria-valid-attr`](#aria-valid-attr) | aria-* attributes must be real, defined ARIA attributes | 4.1.2 | A | high | serious |
@@ -50,6 +50,7 @@ See [`OUTPUT_SCHEMA.md`](./OUTPUT_SCHEMA.md) for what `type`/`confidence`/`sever
 | [`form-control-single-label`](#form-control-single-label) | Form controls must not have multiple labels | 3.3.2 | A | high | moderate |
 | [`html-lang-attr-present`](#html-lang-attr-present) | Page language is declared | 3.1.1 | A | high | serious |
 | [`html-xml-lang-mismatch`](#html-xml-lang-mismatch) | lang and xml:lang must not disagree | 3.1.1 | A | high | serious |
+| [`identical-iframes-same-purpose`](#identical-iframes-same-purpose) | Frames with the same name embed the same resource | 4.1.2 | A | medium | moderate |
 | [`iframe-focusable-content`](#iframe-focusable-content) | Frames with tabindex="-1" must not contain focusable content | 2.1.1 | A | high | moderate |
 | [`iframe-name-present`](#iframe-name-present) | Frames have an accessible name | 4.1.2 | A | high | serious |
 | [`iframe-title-unique`](#iframe-title-unique) | Frame titles must be unique | 4.1.2 | A | high | moderate |
@@ -91,7 +92,7 @@ See [`OUTPUT_SCHEMA.md`](./OUTPUT_SCHEMA.md) for what `type`/`confidence`/`sever
 | [`valid-lang`](#valid-lang) | Element lang attribute must be syntactically valid | 3.1.2 | AA | high | moderate |
 | [`video-poster-text-alternative-present`](#video-poster-text-alternative-present) | <video> poster must have a text alternative | 1.1.1 | A | medium | serious |
 
-## Manual rules (52), advisory, capped at `cantTell`
+## Manual rules (54), advisory, capped at `cantTell`
 
 | Rule ID | Title | WCAG SC | Level | Confidence | Default severity |
 |---|---|---|---|---|---|
@@ -120,6 +121,7 @@ See [`OUTPUT_SCHEMA.md`](./OUTPUT_SCHEMA.md) for what `type`/`confidence`/`sever
 | [`input-image-alt-quality`](#input-image-alt-quality) | <input type="image"> alt text must be appropriate (manual review) | 1.1.1 | A | medium | minor |
 | [`label-title-only`](#label-title-only) | Form controls should not use title as their only label | — | — | medium | minor |
 | [`landmark-banner-is-top-level`](#landmark-banner-is-top-level) | Banner landmark must be top-level | — | — | medium | minor |
+| [`landmark-complementary-is-top-level`](#landmark-complementary-is-top-level) | Complementary landmark must be top-level | — | — | medium | minor |
 | [`landmark-contentinfo-is-top-level`](#landmark-contentinfo-is-top-level) | Contentinfo landmark must be top-level | — | — | medium | minor |
 | [`landmark-main-is-top-level`](#landmark-main-is-top-level) | Main landmark must be top-level | — | — | medium | minor |
 | [`landmark-no-duplicate-banner`](#landmark-no-duplicate-banner) | Page must not have more than one banner landmark | — | — | medium | minor |
@@ -137,6 +139,7 @@ See [`OUTPUT_SCHEMA.md`](./OUTPUT_SCHEMA.md) for what `type`/`confidence`/`sever
 | [`p-as-heading`](#p-as-heading) | A <p> styled to look like a heading should probably be a real heading | 1.3.1 | A | low | minor |
 | [`page-has-heading-one`](#page-has-heading-one) | Page should have a level-one heading | — | — | medium | minor |
 | [`page-title-patterns`](#page-title-patterns) | Page title patterns that may be insufficiently descriptive | 2.4.2 | A | medium | minor |
+| [`password-paste-enabled`](#password-paste-enabled) | Authentication fields must not block pasting | 3.3.8 | AA | medium | serious |
 | [`presentation-role-conflict`](#presentation-role-conflict) | Presentational role must not conflict with a global ARIA attribute or focusability | — | — | medium | minor |
 | [`region`](#region) | Page content should be inside a landmark region | — | — | medium | minor |
 | [`scope-attr-valid`](#scope-attr-valid) | scope attribute must have a valid value | — | — | medium | minor |
@@ -148,7 +151,7 @@ See [`OUTPUT_SCHEMA.md`](./OUTPUT_SCHEMA.md) for what `type`/`confidence`/`sever
 | [`table-fake-caption`](#table-fake-caption) | A table's first row should not stand in for a real <caption> | 1.3.1 | A | low | minor |
 | [`video-caption`](#video-caption) | Prerecorded video should provide a captions track | 1.2.2 | A | low | moderate |
 
-## Composite (WCAG-SC rollup) rules (33)
+## Composite (WCAG-SC rollup) rules (34)
 
 Composite rules aren't individually authored. They're generated rollups over the atomic rules above, one per WCAG Success Criterion with automatable coverage. See [`WCAG_CONFORMANCE.md`](./WCAG_CONFORMANCE.md) for rollup semantics.
 
@@ -157,7 +160,7 @@ Composite rules aren't individually authored. They're generated rollups over the
 | `wcag-1.1.1-non-text-content` | Non-text content: text alternatives | Rollup of checks ensuring non-text content has an appropriate text alternative. | 1.1.1 | A | 22 |
 | `wcag-1.2.1-audio-only-video-only-prerecorded` | Audio-only and video-only (prerecorded): transcript | Rollup of checks for transcript availability for prerecorded audio-only/video-only media. | 1.2.1 | A | 1 |
 | `wcag-1.2.2-captions-prerecorded` | Captions (Prerecorded) | Rollup of checks for captions-track evidence on prerecorded video. | 1.2.2 | A | 1 |
-| `wcag-1.3.1-info-and-relationships` | Info and Relationships | Rollup of checks ensuring information, structure, and relationships conveyed through presentation are programmatically determinable. | 1.3.1 | A | 11 |
+| `wcag-1.3.1-info-and-relationships` | Info and Relationships | Rollup of checks ensuring information, structure, and relationships conveyed through presentation are programmatically determinable. | 1.3.1 | A | 14 |
 | `wcag-1.3.4-orientation` | Orientation | Rollup of checks ensuring content does not restrict its view to a single display orientation. | 1.3.4 | AA | 1 |
 | `wcag-1.3.5-identify-input-purpose` | Identify Input Purpose | Rollup of checks ensuring the autocomplete attribute correctly identifies input purpose. | 1.3.5 | AA | 1 |
 | `wcag-1.4.1-use-of-color` | Use of Color | Rollup of checks ensuring color is not used as the only visual means of conveying information. | 1.4.1 | A | 1 |
@@ -184,9 +187,10 @@ Composite rules aren't individually authored. They're generated rollups over the
 | `wcag-3.1.2-language-of-parts` | Language of Parts | Rollup of checks ensuring elements whose language differs from the page default declare it correctly. | 3.1.2 | AA | 1 |
 | `wcag-3.2.5-change-on-request` | Change on Request | Rollup of checks ensuring context changes only happen at the user's request (AAA). | 3.2.5 | AAA | 1 |
 | `wcag-3.3.2-labels-or-instructions` | Labels or Instructions | Rollup of checks ensuring form controls have unambiguous labeling. | 3.3.2 | A | 2 |
+| `wcag-3.3.8-accessible-authentication-minimum` | Accessible Authentication (Minimum) | Rollup of checks ensuring an authentication step leaves the mechanisms that help a user through it in place. | 3.3.8 | AA | 1 |
 | `wcag-4.1.1-parsing` | Parsing | Rollup of checks ensuring id values are unique. WCAG 2.0/2.1 only: SC 4.1.1 was removed in WCAG 2.2, so this composite carries the wcag22-removed tag. | 4.1.1 | A | 1 |
-| `wcag-4.1.2-aria-validity` | Name, role, value: ARIA validity | Rollup of checks that ARIA role and attribute usage conforms to the WAI-ARIA specification (valid roles, valid attributes, valid values, required attributes/relationships, unique ARIA-referenced ids). | 4.1.2 | A | 17 |
-| `wcag-4.1.2-name` | Name, role, value: accessible name | Rollup of checks that common interactive elements expose a non-empty accessible name. | 4.1.2 | A | 23 |
+| `wcag-4.1.2-aria-validity` | Name, role, value: ARIA validity | Rollup of checks that ARIA role and attribute usage conforms to the WAI-ARIA specification (valid roles, valid attributes, valid values, required attributes, unique ARIA-referenced ids). | 4.1.2 | A | 13 |
+| `wcag-4.1.2-name` | Name, role, value: accessible name | Rollup of checks that common interactive elements expose a non-empty accessible name. | 4.1.2 | A | 24 |
 
 ## Rule reference
 
@@ -256,19 +260,19 @@ Checks that every recognized aria-* attribute present on an element with an expl
 
 **Explicit role must be permitted for its host element**
 
-automatic · WCAG 4.1.2 (A) · confidence high · default severity moderate
+automatic · no formal WCAG SC mapping · confidence high · default severity moderate
 
 Checks that an explicit role="" attribute is one of the roles the ARIA-in-HTML specification permits for the host element (e.g. role="tab" is not permitted on <nav>).
 
 **Applies to.** Applies to elements with an explicit, valid, non-abstract role, where the host element/attribute combination has an asserted permitted-roles constraint in the ARIA-in-HTML table (src/core/aria-helpers.js ALLOWED_ROLES_BY_ELEMENT).
 
-**Expectation.** The explicit role is one of the roles the ARIA-in-HTML specification permits for that host element.
+**Expectation.** The explicit role is one of the roles the ARIA-in-HTML specification permits for that host element. Reported at CANTTELL rather than FAIL: ARIA-in-HTML's permitted-roles table is an author conformance requirement with no ACT rule and no WCAG mapping in any source. The role the author asked for is still the role assistive technology exposes, so whether the combination harms anyone depends on the widget, not on the table.
 
 ### `aria-braille-equivalent`
 
 **aria-braillelabel/aria-brailleroledescription must have a non-braille equivalent**
 
-automatic · WCAG 4.1.2 (A) · confidence high · default severity serious
+automatic · WCAG 4.1.2 (A) · confidence high · default severity moderate
 
 Checks that elements using aria-braillelabel also have a regular accessible name, and elements using aria-brailleroledescription also have aria-roledescription.
 
@@ -281,7 +285,7 @@ Per the ARIA specification, `aria-braillelabel` is a Braille-specific SUPPLEMENT
 - a non-empty accessible name from a non-braille mechanism, if it declares `aria-braillelabel`;
 - a non-empty `aria-roledescription`, if it declares `aria-brailleroledescription`.
 
-Using either braille-specific attribute as the ONLY naming mechanism leaves non-braille assistive technology (most screen readers, voice control, etc.) with no accessible name/role description at all.
+Using either braille-specific attribute as the ONLY naming mechanism leaves non-braille assistive technology (most screen readers, voice control, etc.) with no accessible name/role description at all. Reported at CANTTELL rather than FAIL: aria-brailleroledescription without aria-roledescription reaches no user at all, and a missing accessible name is the naming rules' decision for the roles that require one. The braille attribute being unpaired is worth surfacing, but it is not itself a criterion failing.
 
 ### `aria-checked-state-mismatch`
 
@@ -299,13 +303,13 @@ Flags a native <input type="checkbox">/<input type="radio"> whose ex
 
 **aria-errormessage requires aria-invalid to be set to a non-false value**
 
-automatic · WCAG 4.1.2 (A) · confidence high · default severity serious
+automatic · WCAG 4.1.2 (A) · confidence high · default severity moderate
 
 Checks that elements with aria-errormessage also have aria-invalid set to "true", "grammar", or "spelling"; otherwise the error message is dropped from the accessibility tree.
 
 **Applies to.** Elements with a non-empty `aria-errormessage` attribute.
 
-**Expectation.** Per the ARIA specification, `aria-errormessage` is only exposed to assistive technology when `aria-invalid` is present with a value other than `"false"` (i.e. `"true"`, `"grammar"`, or `"spelling"`). An element with `aria-errormessage` but `aria-invalid` absent or `"false"` silently drops the error message from the accessibility tree, authors almost always intend it to be exposed.
+**Expectation.** Per the ARIA specification, `aria-errormessage` is only exposed to assistive technology when `aria-invalid` is present with a value other than `"false"` (i.e. `"true"`, `"grammar"`, or `"spelling"`). An element with `aria-errormessage` but `aria-invalid` absent or `"false"` silently drops the error message from the accessibility tree, authors almost always intend it to be exposed. Reported at CANTTELL rather than FAIL: aria-errormessage is only exposed once aria-invalid is set, so the reference is currently inert. Whether that costs the user anything depends on whether the message is conveyed some other way (visible text next to the field, aria-describedby), which static markup does not settle.
 
 ### `aria-deprecated-role`
 
@@ -372,7 +376,7 @@ Checks that aria-label/aria-labelledby are not present on WAI-ARIA roles whose s
 
 **Container roles must not own a child with a disallowed role**
 
-automatic · WCAG 4.1.2 (A) · confidence medium · default severity moderate
+automatic · WCAG 1.3.1 (A) · confidence medium · default severity moderate
 
 Checks that every accessible-tree-owned child of a container role (list, listbox, menu, menubar, radiogroup, rowgroup, table, grid, treegrid, tablist, tree, row) has one of that role's allowed owned roles.
 
@@ -390,25 +394,30 @@ Checks that elements with an explicit role carry every unambiguous, context-inde
 
 **Applies to.** Applies to elements with an explicit, valid, non-abstract role that is also one of the small set of roles with a documented, context- independent required state/property (checkbox, combobox, heading, menuitemcheckbox, menuitemradio, meter, radio, scrollbar, separator, slider, switch) -- except when that explicit role is identical to the element's own native/implicit role (ACT 4e8ab6: e.g. <input type="checkbox" role="checkbox">, which is exempt because the native control's own state exposure already covers it; no aria-checked is required. helpers.aria.getNativeRoleForElement resolves this).
 
-**Expectation.** Every required aria-* attribute for that role is present (and non-empty).
+**Expectation.**
+
+Every required state/property for that role is present and non-empty. Graded by whether ARIA supplies a stand-in for the missing attribute:
+
+- FAIL where it does not, so the state is simply not exposed (aria-checked on checkbox/radio/switch/menuitemcheckbox/menuitemradio, aria-valuenow on slider/scrollbar/meter and on a focusable separator).
+- CANTTELL where ARIA defines an implicit value the role falls back to (aria-expanded on combobox, aria-level on heading), so the role still exposes a value and only the author knows whether it is the right one.
 
 ### `aria-required-children`
 
 **Container roles must own at least one required child role**
 
-automatic · WCAG 4.1.2 (A) · confidence medium · default severity moderate
+automatic · WCAG 1.3.1 (A) · confidence medium · default severity moderate
 
 Checks that container roles with a documented "required owned elements" entry (list, listbox, menu, radiogroup, table, grid, tablist, tree, row, ...) contain at least one descendant or aria-owns-referenced element with an acceptable owned role.
 
 **Applies to.** Applies to elements with an explicit, valid, non-abstract role that is also one of the container roles with a documented "required owned elements" entry (list, listbox, menu, menubar, radiogroup, rowgroup, table, grid, treegrid, tablist, tree, row).
 
-**Expectation.** At least one descendant, or one aria-owns-referenced element, has one of the acceptable owned roles for that container role.
+**Expectation.** At least one descendant, or one aria-owns-referenced element, has one of the acceptable owned roles for that container role. Reported at CANTTELL, never FAIL: this rule asks only whether the required content is PRESENT, and a container that owns nothing conveys nothing false -- an empty role="list" is announced as a list with no items, which is what it is. Whether the content a container does own is VALID is aria-prohibited-children's decision, and that rule still fails, so a genuinely misdescribed structure (a role="button" among list items, a tablist of plain buttons) is caught with the same strength as before. The native-HTML equivalents already work this way: nothing in this ruleset fails an empty <ul>, and list-children-valid judges only the children that exist.
 
 ### `aria-required-parent`
 
 **Roles requiring a specific context role must be in that context**
 
-automatic · WCAG 4.1.2 (A) · confidence medium · default severity moderate
+automatic · WCAG 1.3.1 (A) · confidence medium · default severity moderate
 
 Checks that roles with a documented "required context role" entry (listitem, option, tab, treeitem, row, cell, ...) have an ancestor or aria-owns owner with an acceptable context role.
 
@@ -438,7 +447,12 @@ Checks that an explicit role="" attribute resolves to a real, non-abstract WAI-A
 
 **Applies to.** Applies to any element with a non-empty role="" attribute in the composed DOM.
 
-**Expectation.** The role attribute's first token (the role actually used by assistive technology; later space-separated tokens are author-supplied fallbacks and are not evaluated here) must be a real WAI-ARIA role name, and must not be an abstract role (abstract roles exist only for the specification's own role taxonomy and must never be used directly in markup).
+**Expectation.**
+
+At least one role token names a concrete, non-abstract ARIA role. Graded by what the element falls back to when none does:
+
+- FAIL on a roleless host (div, span, custom element), which is left exposed as generic, so the role the author meant reaches no one.
+- CANTTELL where the element has a native role (a <button>, <nav>, <a href>), which the accessibility tree keeps using. ACT 674b10 lists 4.1.2 as a secondary requirement only, "satisfied through the implicit role," so the bad token is worth reporting but is not itself the criterion failing.
 
 ### `aria-text`
 
@@ -462,7 +476,7 @@ Checks that every aria-* attribute name present in the DOM is a real attribute d
 
 **Applies to.** Applies to any element in the composed DOM that carries at least one attribute whose name starts with "aria-".
 
-**Expectation.** Each aria-* attribute name is a real attribute defined by the WAI-ARIA specification (catches typos / made-up attribute names, which are silently ignored by assistive technology and therefore a real, deterministic defect).
+**Expectation.** Each aria-* attribute name is a real attribute defined by the WAI-ARIA specification (catches typos / made-up attribute names, which are silently ignored by assistive technology and therefore a real, deterministic defect). Reported at CANTTELL rather than FAIL: an aria-* attribute the spec does not define is inert, so nothing about the element's exposed name, role or value changes because it is there. Where the author meant a real attribute and the element ends up without a name, that absence is the naming rules' decision, not this one's. ACT 5f99a7 maps 1.3.1/4.1.2 as secondary requirements, "less strict" than the rule itself.
 
 ### `aria-valid-attr-value`
 
@@ -908,6 +922,18 @@ Checks that the <html> element's lang and xml:lang attributes declare the
 
 **Expectation.** The primary language subtag (the part before the first "-") of lang and xml:lang match, case-insensitively. When both attributes are present but declare different languages, assistive technology and user agents may resolve the page's language inconsistently.
 
+### `identical-iframes-same-purpose`
+
+**Frames with the same name embed the same resource**
+
+automatic · WCAG 4.1.2 (A) · confidence medium · default severity moderate
+
+Checks that <iframe>/<frame> elements sharing an accessible name embed the same resource, since one name can only describe one resource.
+
+**Applies to.** Applies to each set of two or more <iframe>/<frame> elements that are included in the accessibility tree and share the same non-empty accessible name, compared with whitespace collapsed. A frame named only by a mechanism that names nothing, or hidden from the accessibility tree, is not part of a set; a set needs two surviving members to exist at all.
+
+**Expectation.** Every frame in a set resolves to the same resource. A shared name describes one resource, so two frames answering to it must embed the same one.
+
 ### `identical-links-same-purpose`
 
 **Links with the same accessible name should lead to the same destination**
@@ -1076,6 +1102,18 @@ Checks that the banner landmark (role="banner" or a non-nested <header>) i
 
 **Expectation.** No banner candidate has an ancestor that is itself any landmark region. A banner nested inside another landmark is not a top-level, whole-page banner and confuses landmark-based navigation for assistive technology users.
 
+### `landmark-complementary-is-top-level`
+
+**Complementary landmark must be top-level**
+
+manual · no formal WCAG SC mapping · confidence medium · default severity minor
+
+Checks that the complementary landmark (role="complementary" or an <aside> that keeps its implicit role) is not nested inside another landmark region.
+
+**Applies to.** Applies whenever the page contains at least one element carrying the complementary role: explicit role="complementary", or an <aside> that keeps its implicit role (see implementation notes on when it does not).
+
+**Expectation.** No complementary candidate has an ancestor that is itself a landmark region. Complementary content supports the main content of the page and sits beside it; nested inside another landmark it is a section of that landmark instead, which is not what landmark navigation announces.
+
 ### `landmark-contentinfo-is-top-level`
 
 **Contentinfo landmark must be top-level**
@@ -1463,6 +1501,18 @@ Checks that the page includes a non-empty <title> element.
 
 **Expectation.** The document has a <title> element, and document.title with whitespace collapsed is non-empty. The element is looked for anywhere in the document, not only inside <head>: a <title> the parser leaves outside <head> is still the document title in every browser. Whether that title describes the page is page-title-patterns' question.
 
+### `password-paste-enabled`
+
+**Authentication fields must not block pasting**
+
+manual · WCAG 3.3.8 (AA) · confidence medium · default severity serious
+
+Checks that a password or one-time-code field carries no inline paste handler that cancels the paste, which would remove the password manager or clipboard that WCAG 3.3.8 relies on as the assisting mechanism.
+
+**Applies to.** Applies to any control whose autocomplete token is current-password, new-password or one-time-code, and to <input type="password"> unless its autocomplete names another purpose. A disabled or readonly field takes no input to block, and one outside the accessibility tree is not being asked for, so neither is in scope.
+
+**Expectation.** A reviewer confirms the field can still be pasted into. Remembering a password is a cognitive function test, and 3.3.8 asks for a mechanism that helps the user through one; a password manager, or the clipboard for a one-time code, is that mechanism.
+
 ### `presentation-role-conflict`
 
 **Presentational role must not conflict with a global ARIA attribute or focusability**

package/docs/RULE_HELPERS.md

@@ -0,0 +1,333 @@
+# RULE_HELPERS.md — `ctx.helpers` Reference (Canonical, repo-derived)
+
+This is the full reference for `ctx.helpers`, the object every rule's `runInPage(ctx)`
+receives (`const { helpers } = ctx`, per [`RULE_AUTHORING.md`](./RULE_AUTHORING.md) §6).
+It exists because that doc's own helpers section only calls out the dozen or so most
+common ones — the underlying object (`createDomHelpers()` in `src/core/dom-helpers.js`)
+exports around 35, and several of them replace logic a new rule would otherwise
+duplicate (often incorrectly — see the naming helpers below).
+
+Read [`RULE_AUTHORING.md`](./RULE_AUTHORING.md) first for the rule contract itself
+(module shape, `runInPage` constraints, occurrence reporting). This doc only covers
+what each helper does and when to reach for it.
+
+All helpers below are called as `helpers.<name>(...)` from inside `runInPage`. None of
+them may be assigned to a module-scope variable and closed over — same
+serialization constraint as everything else in `runInPage` (§1 of `RULE_AUTHORING.md`).
+
+---
+
+## 1) Query & traversal
+
+### `queryAll(selector)` → `Element[]`
+Plain `querySelectorAll(selector)` across the resolved context root(s), deduped, with
+self-match included (a root element matching `selector` itself is returned, which
+`querySelectorAll` alone never does). Light DOM only.
+
+### `queryAllDeep(selector)` → `Element[]`
+Same as `queryAll`, but also descends into open shadow roots (BFS over discovered
+`shadowRoot`s). Ignores `includeShadowDom`/hidden-content policy — it's the raw
+traversal `queryAllSmart` builds on.
+
+### `queryAllSmart(selector)` → `Element[]`
+**The one almost every rule should use.** Honors `engineOptions.includeShadowDom`
+(shadow-aware by default), applies the default hidden-content policy (filters out
+`display:none`/`hidden`/etc. unless `includeHiddenElements:true`), and applies any
+rule-scoped `excludeSelectors`. See `RULE_AUTHORING.md` §6.1 — write rules assuming
+open shadow roots are in scope and let this helper honor the caller's choice.
+
+```js
+const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('img') : helpers.queryAll('img');
+```
+
+### `composedParent(node)` → `Node | null`
+One step up the *flat tree*: `assignedSlot` first (a slotted node's rendered parent is
+its slot, not its light-DOM `parentNode`), then `parentNode`, then `.host` once you're
+at a `ShadowRoot`. Use this instead of `parentNode`/`closest` for any ancestor walk that
+must work correctly across shadow boundaries and slots.
+
+### `buildSimpleSelector(el, fallbackTag)` → `string`
+A short, non-unique selector for an element: `#id`, else a `data-testid`/`data-test`/
+`data-cy`/`data-qa` attribute selector, else `tag[name="..."]`, else just the tag name.
+Cheap; not guaranteed unique. Prefer `reportOccurrence` (§6 below) over building
+selectors by hand — see the perf note there.
+
+### `buildSelector(el)` → `string`
+The engine's real, best-effort-unique CSS selector builder (cached per element per
+run). Used internally by `reportOccurrence`'s finalization; rules generally don't need
+to call this directly.
+
+### `getOuterHtmlSnippet(el)` → `string`
+`el.outerHTML`, truncated to 2000 characters (with a trailing `…`) and cached per
+element per run. `reportOccurrence` (§6 below) already fills in an occurrence's `html`
+from the reported element, so most rules never call this directly — it's for the rare
+case where a rule needs the HTML snippet itself, not just an occurrence carrying it.
+
+### `isExcluded(el)` → `boolean`
+Whether `el` matches the currently effective `excludeSelectors` (global config ∪ the
+active rule's own `engineOptions.rules[ruleId].excludeSelectors`), via `closest()`.
+`queryAllSmart` already applies this filtering for you; reach for `isExcluded` directly
+only if a rule walks the DOM some other way (e.g. following `composedParent`) and still
+needs to respect exclusions on nodes found off that path.
+
+### `buildStructuralPath(node, selector)` → `number[] | null`
+Sibling-index path from the document root to `node` (or, given only a `selector`,
+re-resolves the element first — the same fallback `reportOccurrence` triggers, and the
+same one `perfStats.counters['structuralPath.selectorFallback']` counts, per
+`RULE_AUTHORING.md` §4.3). Rules don't normally call this either — it's what backs
+`selector`/`structuralPath` finalization for reported occurrences.
+
+---
+
+## 2) Eligibility & visibility
+
+These answer "is this node in scope" from different angles. They are easy to reach for
+the wrong one, so the distinctions matter:
+
+### `isAccTreeEligible(node)` → `{ eligible, reasons[] }`
+Whether a node is eligible for the accessibility tree, per an ordered set of checks
+(display/visibility, `hidden`, `inert`, closed `<details>`, template content, etc.).
+Deliberately keeps a focusable-but-`aria-hidden` element *eligible* — see the header
+comment on `isIncludedInAccessibilityTree` below for why.
+
+### `isIncludedInAccessibilityTree(el)` → `boolean`
+The narrower question most accessible-name rules actually want: `isAccTreeEligible`,
+minus anything eligible only because of an `ariaHiddenOverridden*` reason. ACT scopes
+name-computation rules (button-name, link-name, etc.) to elements genuinely included in
+the accessibility tree; a focusable element hidden by `aria-hidden` is a real
+issue, but it's `aria-hidden-focus`'s issue (WCAG 4.1.2), not a naming rule's — so
+naming rules should check this, not `isAccTreeEligible`, to avoid double-flagging the
+same element under the wrong rule.
+
+### `isDomVisibleEligible(node, ctx, opts)` → `{ eligible, reasons[], metrics }`
+Style/geometry-only visibility (not accessibility-tree membership): `display`,
+`visibility`, size/position, opacity, etc. `opts.visibilityMode` (`'styleOnly'` |
+`'styleAndGeometry'`), `opts.disableGeometry`, `opts.ignoreOpacity` tune what's checked.
+Use when a rule cares about visual rendering specifically, not AT exposure.
+
+### `getEligibilityInfo(node, ctx, opts)` → `{ eligible, reasons[], targetSet, accEligible }`
+A single wrapper choosing between the two above via `opts.targetSet` (`'acc'` |
+`'dom'`, default `'dom'`). **This is also the shape `RULE_AUTHORING.md` §7 requires every
+occurrence to carry** as `data.visibilityFilter` — call this once per element and pass
+its result straight through.
+
+### `getVisibilityHintsInfo(el, ctx, opts)` → `{ hints[], metrics, flags[] }`
+Style-only visibility *hints* for triage/diagnostics (`opacityZero`, `clipped`, etc.) —
+explicitly does **not** decide eligibility; a rule's own logic still owns the outcome.
+
+### `isWholeDocumentScope()` → `boolean`
+`true` unless `engineOptions.fragment: true` was set, or `contextSelector` scoped the
+run narrower than the whole document. Required for any rule checking a page-wide,
+one-per-document property (`<title>`, `<html lang>`, landmark structure) — gate it with
+an `applicability(ctx)` export using this, per `RULE_AUTHORING.md` §4.2/§11.2, or the
+rule will wrongly fault a scoped subtree for lacking something it was never meant to
+have.
+
+### `hasTruncatedAncestorWalk` (internal)
+Backs confidence scoring during result normalization when a 200-step ancestor walk
+didn't reach the root. Not something a rule calls directly.
+
+---
+
+## 3) Accessible naming & labeling
+
+Naming is layered — each function below builds on the ones above it — and several exist
+specifically to replace a naive reimplementation that gets an edge case wrong. Reach for
+the highest-level one that answers your actual question before dropping to a primitive.
+
+### `getAriaLabelInfo(el)` → `{ present, value, mechanism, flags[] }`
+Just `aria-label`, trimmed, presence-checked.
+
+### `getAriaLabelledByInfo(el, ctx, opts)` → `{ present, value, mechanism, refsCount, missing[], flags[] }`
+Resolves `aria-labelledby` through `getTextFromIdRefs` (recursive, accname-aligned — see
+§4 below), not raw `textContent`.
+
+### `getAriaNameInfo(el, ctx, opts)` → `{ present, value, mechanism, flags[] }`
+ARIA-only name with correct precedence: `aria-labelledby` (if it resolves non-empty)
+wins over `aria-label`. Use this rather than checking the two attributes yourself when
+you specifically want "does ARIA name this," excluding native `<label>`/content/title.
+
+### `getLandmarkNameInfo(el, ctx)` → `{ present, value, mechanism, flags[] }`
+Landmark-role naming (`nav`/`main`/`region`/`banner`/`contentinfo`, etc.): ARIA name,
+then `title` — landmark roles don't get a name from content, and `title` must be
+included or two landmarks distinguished only by `title` both read as unnamed and get
+flagged as duplicates. Shared by all 7 landmark rule files; use this rather than
+reimplementing landmark naming in a new landmark rule.
+
+### `getAccessibleNameInfo(el, ctx, opts)` → `{ present, value, mechanism, flags[] }`
+The general-purpose accessible name: ARIA name → native `<label>` association → `alt`
+(image-like elements) → `title` (flagged `title-used` — see the policy note in the
+source; `title` is accepted per spec but is a weak mechanism in practice). This is what
+almost every naming rule should call.
+
+### `getAccessibleDescriptionInfo(el, ctx, opts)` → `{ present, value, mechanism, flags[] }`
+`aria-describedby` (via `getTextFromIdRefs`), then optionally `title` if
+`opts.allowTitle === true`.
+
+### `getTextAlternativeInfo(el, ctx, opts)` → `{ present, value, mechanism, requiredMechanism, flags[] }`
+Mechanism-aware text alternative for elements with a *specific required* mechanism:
+`alt` for `img`/`area`/`input[type=image]` (missing `alt` is flagged even when an
+accessible name exists elsewhere — that's still a real alt-text violation), fallback
+content or ARIA/`title` for `<canvas>`. Use this for alt-text-shaped rules, not
+`getAccessibleNameInfo`, when the rule cares which mechanism was used, not just whether
+a name exists.
+
+### `getContentNameInfo(el, ctx, opts)` → `{ present, value, mechanism, flags[] }`
+Recursive "name from content" (accname step 2F): walks children using each child's
+*own* accessible name (not just literal text), so `<a href="…"><img alt="Company
+Name"></a>` and `<button><span aria-label="Close"></span></button>` both name correctly.
+A plain `TreeWalker(SHOW_TEXT)` walk misses both.
+
+### `getAssociatedLabelElements(el)` → `Element[]`
+Real `<label>` element(s) associated with `el` — a `<label for="id">` pointing at it,
+plus a wrapping `<label>` whose first labelable descendant it is. **Does not call the
+native `.labels`/`.control` API** — in this project's supported jsdom runtime,
+`.labels` is an expensive whole-document walk per element (`.control` resolution is
+another one), which used to dominate whole-engine runtime on form-heavy pages. Use this
+whenever a rule needs the actual label element(s), not just a yes/no.
+
+### `labelContributesAccessibleName(labelEl)` → `boolean`
+Whether a `<label>` element itself carries text that would name its control: own
+ARIA name, else rendered content (`getContentNameInfo`, so `aria-hidden`/`display:none`
+descendants are correctly excluded), else its own `title`. Shared by
+`form-control-single-label` and `form-control-programmatic-label-present` so they agree
+on what "a label with content" means.
+
+### `getLabelMethod(el, ctx, opts)` → `{ method, value }`
+Which mechanism actually labels `el` — `'label'` | `'aria-labelledby'` |
+`'aria-label'` | `'title'` | `'placeholder'` | `'none'` — checked in that precedence
+order.
+
+### `getLabelStrength(method)` → `'strong' | 'medium' | 'weak' | 'none'`
+Policy classification of a `getLabelMethod` result (`label`/`aria-labelledby` →
+strong, `aria-label` → medium, `title`/`placeholder` → weak). Deterministic and
+intentionally tweakable in one place rather than per rule.
+
+### `hasAccessibleName(el)` → `boolean`
+Back-compat convenience: `!!getAccessibleNameInfo(el).value`.
+
+---
+
+## 4) IDREF resolution
+
+Backs `aria-labelledby`/`aria-describedby` and any other space-separated ID-reference
+attribute.
+
+### `resolveIdRefs(idrefString, ctx, opts)` → `{ refs: Element[], missing: string[], flags[] }`
+Splits and resolves a space-separated ID list to elements (deduped, cached per scope).
+`opts.maxRefs` truncates deterministically (adds `'truncated'` to `flags`).
+
+### `getTextFromIdRefs(idrefString, ctx, opts)` → `{ text, refsCount, missing[], flags[] }`
+Resolves refs, then computes **each target's own text alternative** recursively
+(accname-aligned — a referenced element's name is recomputed, not read as raw
+`textContent`), joins with spaces. This is what `getAriaLabelledByInfo`/
+`getAccessibleDescriptionInfo` call internally.
+
+### `getTextFromIdRefsIdrefEligible(idrefString, ctx, opts)` → `{ text, refsCount, missing[], excluded[], flags[] }`
+Same, but under IDREF eligibility rules specifically: hidden/`aria-hidden`/collapsed
+targets are still included (IDREF targets aren't scoped by visibility the way rendered
+content is — see the `root` note in the source), only `inert` targets are excluded.
+`excluded` lists `{ id, reasons }` for anything dropped.
+
+---
+
+## 5) Role & focusability
+
+### `getRoleInfo(el, ctx, opts)` → `{ role, source, flags[] }`
+Explicit `role` attribute if present (flags `'presentation'` for
+`presentation`/`none`, `'multiple-roles'` if it contains whitespace), else a small,
+deliberately minimal implicit-role mapping (`a[href]`→`link`, `button`→`button`,
+`input[type=checkbox]`→`checkbox`, etc.) unless `opts.disallowImplicit`.
+
+### `getFocusableInfo(el, ctx, opts)` → `{ focusable, tabbable, mechanism, flags[] }`
+Platform focusability: whether `el` can receive focus at all, and whether it's in the
+default tab order.
+
+### `hasLandmarkScopingAncestor(el, ctx)` → `boolean`
+Whether `el` sits inside a landmark-scoping ancestor — the role-aware
+sectioning-content/`<main>` check backing `<header>`/`<footer>`/`<aside>`'s conditional
+implicit roles (their implicit landmark role only applies when *not* nested inside
+certain ancestors). Available both as `helpers.hasLandmarkScopingAncestor` and
+`helpers.aria.hasLandmarkScopingAncestor` — same function, re-exported at the top level
+so landmark-check files don't need to reach into `aria.*` for it.
+
+---
+
+## 6) Attributes, language, reporting, outcomes
+
+### `getAttributeInfo(el, attrName)` → `{ present, value, mechanism, flags[] }`
+Generic trimmed-attribute presence/value check. Use for any plain attribute a rule
+inspects directly (not one of the naming/ARIA attributes above, which have their own
+dedicated helpers).
+
+### `isValidLanguageTag(value)` / `isRegisteredLanguageSubtag(subtag)` → `boolean`
+BCP 47 well-formedness **plus** a real IANA subtag-registry check — shape alone accepts
+`"eng"` or `"em-US"`, which look like language tags but use an unregistered primary
+subtag (the registry only lists a three-letter subtag when no two-letter one exists,
+so `"en"` is registered and `"eng"` is not). Use `isValidLanguageTag` for any
+`lang`/`xml:lang`-checking rule instead of a regex-only check.
+
+### `reportOccurrence(node, partial)` → occurrence object
+**Use this to build every occurrence.** Attaches the element so the engine fills in
+`selector`, `html`, and `structuralPath` centrally — see `RULE_AUTHORING.md` §4.3/§9 for
+the full contract and why hand-building these fields yourself is a real (measured:
+4 min → <1 s) performance regression on any rule reporting many occurrences.
+
+```js
+occurrences.push(helpers.reportOccurrence(el, {
+  summary: '…',
+  hint: '…',
+  i18n: { summaryKey: '…', hintKey: '…', params: { element: 'img' } },
+  data: { visibilityFilter: eligInfo }
+}));
+```
+
+### `resolveTieredOutcome(failOccurrences, cantTellOccurrences, severity)` → `{ outcome, severity, occurrences }`
+For a rule that collects two confidence tiers in one run — some findings confident
+enough for `fail`, others only `cantTell` ("needs human review"). Returns `fail` (with
+**both** tiers' occurrences, tagged via `occurrenceOutcome`) whenever any fail-tier
+finding exists, `cantTell` when only cantTell-tier findings exist, `pass` otherwise.
+Reach for this instead of the naive `if (fails.length) return fail(fails); else if
+(cantTells.length) return cantTell(cantTells);`, which silently drops every cantTell
+finding whenever at least one fail finding also exists on the page.
+
+### `getPerfStats()` / `resetPerfStats()`
+Only populated when the engine is run with `perfStats: true`. Not for rule logic —
+useful when profiling a new rule's hot paths during development.
+
+---
+
+## 7) Namespaced helper groups
+
+Two larger helper sets are exposed as namespaces rather than flattened, since their
+member counts and internal cohesion (contrast math, ARIA validity data) don't fit the
+flat `helpers.*` list above:
+
+### `helpers.contrast.*`
+Color/contrast math and text-run analysis: `parseCssColorToRgba`, `compositeRgba`,
+`relativeLuminance`, `contrastRatio`, `requiredRatio`, `isLargeText`,
+`computeEffectiveForeground`/`computeEffectiveBackground`, `getComputabilityBlocker`,
+`getTextScan`, `isInactiveUiComponent`, plus small numeric/formatting utilities
+(`clamp01`, `round2`, `toHex2`, `pxToPt`, `fontWeightLabel`, …). Backs the
+`contrast-*` rule family (`contrast-minimum`, `contrast-enhanced`,
+`contrast-computable`) — see `src/core/contrast-helpers.js` if you're extending that
+family specifically.
+
+### `helpers.aria.*`
+ARIA validity/taxonomy data and checks: `isValidAriaAttrName`, `getAttrValueType`,
+`validateAttrValue`, `getExplicitRole`, `getAllRoleTokens`, `isAbstractRole`,
+`isDeprecatedRole`, `isAuthorDiscouragedRole`, `isAuthorProhibitedRole`,
+`isDeprecatedAttr`, `getDeprecatedRoleGuidance`, `isKnownRole`, `isValidConcreteRole`,
+`getRequiredAttrsForRole`, `getRequiredOwnedRoles`, `getRequiredContextRoles`,
+`isRoleAllowedOnElement`, `getContainmentRole`, `getNativeRoleForElement`,
+`hasLandmarkScopingAncestor` (also re-exported flat, see §5). Backs the whole
+`aria-*` rule family — check here before hand-rolling role/attribute validity logic in
+a new ARIA rule.
+
+---
+
+## 8) Not for rule use
+
+`helpers.__setActiveRuleExcludeSelectors` exists on the object but is engine-internal —
+`dom-runner.js` calls it before invoking each rule to scope that rule's
+`engineOptions.rules[ruleId].excludeSelectors`. A rule itself never calls it.