@surea11y/core 1.0.0

package/docs/RULE_CATALOG.md

@@ -0,0 +1,180 @@
+# Rule catalog
+
+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.**
+
+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`
+
+| Rule ID | Title | WCAG SC | Level | Confidence | Default severity |
+|---|---|---|---|---|---|
+| `area-alt-present` | <area> must have an alt attribute | 1.1.1 | A | high | serious |
+| `aria-allowed-attr` | aria-* attributes must be permitted for the element’s role | 4.1.2 | A | medium | moderate |
+| `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-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 |
+| `aria-prohibited-children` | Container roles must not own a child with a disallowed role | 4.1.2 | A | medium | moderate |
+| `aria-required-attr` | Roles with a required ARIA state/property must carry it | 4.1.2 | A | high | serious |
+| `aria-required-children` | Container roles must own at least one required child role | 4.1.2 | A | medium | moderate |
+| `aria-required-parent` | Roles requiring a specific context role must be in that context | 4.1.2 | A | medium | moderate |
+| `aria-role-name-present` | ARIA widget/container roles have an accessible name | 4.1.2 | A | high | serious |
+| `aria-roles-valid` | role attribute must be a valid, non-abstract ARIA role | 4.1.2 | A | high | serious |
+| `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 |
+| `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 |
+| `contrast-enhanced` | Text meets enhanced color contrast (AAA) | 1.4.6 | AAA | high | serious |
+| `contrast-minimum` | Text meets minimum color contrast (AA) | 1.4.3 | AA | high | serious |
+| `css-orientation-lock` | CSS must not lock the page to a single orientation | 1.3.4 | AA | high | serious |
+| `definition-list-children-valid` | Description lists must be structured correctly | 1.3.1 | A | high | serious |
+| `deprecated-elements-not-used` | Obsolete non-stoppable elements (<blink>, <marquee>) must not be used | 2.2.2 | A | high | serious |
+| `dialog-name-present` | Dialogs have an accessible name | 4.1.2 | A | high | serious |
+| `dlitem-parent-valid` | Description-list items must be inside a description list | 1.3.1 | A | high | serious |
+| `duplicate-id-aria` | IDs referenced by ARIA must be unique | 4.1.2 | A | high | serious |
+| `embed-text-alternative-present` | <embed> must provide a text alternative | 1.1.1 | A | high | serious |
+| `form-control-programmatic-label-present` | Form controls must have a programmatic label | 1.3.1, 3.3.2, 4.1.2 | A | medium | serious |
+| `form-control-single-label` | Form controls must not have multiple labels | 3.3.2 | A | high | moderate |
+| `html-lang-attr-present` | Page language is declared | 3.1.1 | A | high | serious |
+| `html-xml-lang-mismatch` | lang and xml:lang must not disagree | 3.1.1 | A | high | serious |
+| `iframe-focusable-content` | Frames with tabindex="-1" must not contain focusable content | 2.1.1 | A | high | moderate |
+| `iframe-name-present` | Frames have an accessible name | 4.1.2 | A | high | serious |
+| `iframe-title-unique` | Frame titles must be unique | 4.1.2 | A | high | moderate |
+| `img-alt-present` | <img> must have an alt attribute | 1.1.1 | A | high | serious |
+| `input-image-alt-present` | <input type="image"> must have an alt attribute | 1.1.1 | A | high | serious |
+| `label-in-name` | Label in Name: accessible name contains visible text | 2.5.3 | A | high | serious |
+| `link-in-text-block` | Links in text blocks must be distinguishable from surrounding text without relying on color alone | 1.4.1 | A | high | serious |
+| `link-name-present` | Links have an accessible name | 4.1.2 | A | high | serious |
+| `list-children-valid` | Lists must only directly contain list items | 1.3.1 | A | high | serious |
+| `listbox-name-present` | Listboxes have an accessible name | 4.1.2 | A | high | serious |
+| `listitem-parent-valid` | List items must be inside a list container | 1.3.1 | A | high | serious |
+| `menuitem-name-present` | Menu items have an accessible name | 4.1.2 | A | high | serious |
+| `meta-refresh-no-exceptions` | Page must not use a meta refresh at all (AAA) | 2.2.4, 3.2.5 | AAA | high | moderate |
+| `meta-refresh-timing-absent` | Page must not use a timed meta refresh | 2.2.1 | A | high | serious |
+| `meta-viewport-zoom-enabled` | Viewport meta tag must not disable zoom | 1.4.4 | AA | high | serious |
+| `meter-name-present` | Meters have an accessible name | 1.1.1 | A | high | serious |
+| `nested-interactive-controls-absent` | Interactive controls must not be nested | 4.1.2 | A | high | serious |
+| `object-text-alternative-present` | <object> must provide a text alternative | 1.1.1 | A | high | serious |
+| `option-name-present` | Options have an accessible name | 4.1.2 | A | high | serious |
+| `page-title-present` | Page has a non-empty title | 2.4.2 | A | high | serious |
+| `progressbar-name-present` | Progress bars have an accessible name | 1.1.1 | A | high | serious |
+| `role-img-text-alternative-present` | [role="img"] must have an accessible text alternative | 1.1.1 | A | high | serious |
+| `searchbox-name-present` | Searchboxes have an accessible name | 4.1.2 | A | high | serious |
+| `server-side-image-map-absent` | Images must not use a server-side image map | 2.1.1 | A | high | serious |
+| `slider-name-present` | Sliders have an accessible name | 4.1.2 | A | high | serious |
+| `spinbutton-name-present` | Spinbuttons have an accessible name | 4.1.2 | A | high | serious |
+| `summary-name-present` | Summary elements have an accessible name | 4.1.2 | A | high | serious |
+| `svg-image-text-alternative-present` | SVG <image> must have a text alternative | 1.1.1 | A | medium | serious |
+| `svg-text-alternative-present` | <svg> must provide a text alternative | 1.1.1 | A | high | serious |
+| `tab-name-present` | Tabs have an accessible name | 4.1.2 | A | high | serious |
+| `table-headers-attr-valid` | Table cell "headers" attribute must reference valid header cells | 1.3.1 | A | high | serious |
+| `table-th-has-data-cells` | <th> elements must describe at least one data cell | 1.3.1 | A | high | moderate |
+| `target-size-minimum` | Pointer targets must be at least 24x24px large, or leave sufficient distance to other targets | 2.5.8 | AA | medium | serious |
+| `td-has-header` | Data cells in large tables must have an associated header | 1.3.1 | A | high | serious |
+| `textbox-name-present` | Textboxes have an accessible name | 4.1.2 | A | high | serious |
+| `tooltip-name-present` | Tooltips have an accessible name | 4.1.2 | A | high | serious |
+| `treeitem-name-present` | Tree items have an accessible name | 4.1.2 | A | high | serious |
+| `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`
+
+| Rule ID | Title | WCAG SC | Level | Confidence | Default severity |
+|---|---|---|---|---|---|
+| `accesskeys` | accesskey values must be unique | — | — | medium | minor |
+| `area-alt-decorative` | <area> with alt="" must be decorative (manual review) | 1.1.1 | A | medium | minor |
+| `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 |
+| `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 |
+| `empty-heading` | Headings must not be empty | — | — | medium | minor |
+| `empty-table-header` | Table header cells must not be empty | — | — | medium | minor |
+| `focus-order-semantics` | Elements added to the tab order should have interactive semantics | — | — | medium | minor |
+| `form-control-programmatic-label-quality` | Form controls should not rely on placeholder or title as the primary label | 4.1.2 | A | medium | moderate |
+| `heading-order` | Heading levels must not skip a level | — | — | medium | minor |
+| `identical-links-same-purpose` | Links with the same accessible name should lead to the same destination | 2.4.9 | AAA | low | minor |
+| `image-redundant-alt` | Image alt text must not duplicate adjacent visible text | — | — | medium | minor |
+| `img-alt-decorative` | <img> with alt="" must be decorative (manual review) | 1.1.1 | A | medium | minor |
+| `img-alt-quality` | <img> alt text must be appropriate (manual review) | 1.1.1 | A | medium | minor |
+| `input-image-alt-decorative` | <input type="image"> with alt="" must be appropriate (manual review) | 1.1.1 | A | medium | minor |
+| `input-image-alt-quality` | <input type="image"> alt text must be appropriate (manual review) | 1.1.1 | A | medium | minor |
+| `label-title-only` | Form controls should not use title as their only label | — | — | medium | minor |
+| `landmark-banner-is-top-level` | Banner landmark must be top-level | — | — | medium | minor |
+| `landmark-contentinfo-is-top-level` | Contentinfo landmark must be top-level | — | — | medium | minor |
+| `landmark-main-is-top-level` | Main landmark must be top-level | — | — | medium | minor |
+| `landmark-no-duplicate-banner` | Page must not have more than one banner landmark | — | — | medium | minor |
+| `landmark-no-duplicate-contentinfo` | Page must not have more than one contentinfo landmark | — | — | medium | minor |
+| `landmark-no-duplicate-main` | Page must not have more than one main landmark | — | — | medium | minor |
+| `landmark-one-main` | Page should have a main landmark | — | — | medium | minor |
+| `landmark-unique` | Landmarks with the same role must have unique names | — | — | medium | minor |
+| `link-name-quality` | Link text should be descriptive, not generic | 2.4.4 | A | medium | minor |
+| `manual-review` | Manual review: keyboard navigation and focus order | 2.1.1, 2.4.3, 2.4.7 | AA | medium | moderate |
+| `media-alternative-transcript-evidence` | Time-based media: transcript or text alternative evidence | 1.2.1 | A | low | moderate |
+| `meta-viewport-large` | Viewport meta tag should allow zooming up to 500% | — | — | medium | minor |
+| `mouse-only-event-handlers` | Pointer-only inline event handlers should have a keyboard-reachable equivalent | 2.1.1 | A | low | moderate |
+| `no-autoplay-audio` | Autoplaying audio should provide a pause/stop or volume-control mechanism | 1.4.2 | A | low | moderate |
+| `object-text-alternative-quality` | <object> text alternative must be appropriate (manual review) | 1.1.1 | A | medium | minor |
+| `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 should have a level-one heading | — | — | medium | minor |
+| `page-title-patterns` | Page title patterns that may be insufficiently descriptive | 2.4.2 | A | medium | minor |
+| `presentation-role-conflict` | Presentational role must not conflict with a global ARIA attribute or focusability | — | — | medium | minor |
+| `region` | Page content should be inside a landmark region | — | — | medium | minor |
+| `scope-attr-valid` | scope attribute must have a valid value | — | — | medium | minor |
+| `scrollable-region-focusable` | Scrollable regions with no focusable content should be keyboard-focusable | 2.1.1, 2.1.3 | AAA | low | moderate |
+| `skip-link` | Skip link must have a resolvable target | — | — | medium | minor |
+| `svg-text-alternative-quality` | <svg> text alternative must be appropriate (manual review) | 1.1.1 | A | medium | minor |
+| `tabindex` | tabindex should not be greater than 0 | — | — | medium | minor |
+| `table-duplicate-name` | Table caption must not duplicate its summary attribute | — | — | medium | minor |
+| `table-fake-caption` | A table's first row should not stand in for a real <caption> | 1.3.1 | A | low | minor |
+| `video-caption` | Prerecorded video should provide a captions track | 1.2.2 | A | low | moderate |
+
+## Composite (WCAG-SC rollup) rules (31)
+
+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.
+
+| Composite ID | Title | WCAG SC | Level | # atomic rules rolled up |
+|---|---|---|---|---|
+| `wcag-1.1.1-non-text-content` | Non-text content: text alternatives | 1.1.1 | A | 22 |
+| `wcag-1.2.1-audio-only-video-only-prerecorded` | Audio-only and video-only (prerecorded): transcript | 1.2.1 | A | 1 |
+| `wcag-1.2.2-captions-prerecorded` | Captions (Prerecorded) | 1.2.2 | A | 1 |
+| `wcag-1.3.1-info-and-relationships` | Info and Relationships | 1.3.1 | A | 11 |
+| `wcag-1.3.4-orientation` | Orientation | 1.3.4 | AA | 1 |
+| `wcag-1.3.5-identify-input-purpose` | Identify Input Purpose | 1.3.5 | AA | 1 |
+| `wcag-1.4.1-use-of-color` | Use of Color | 1.4.1 | A | 1 |
+| `wcag-1.4.12-text-spacing` | Text Spacing | 1.4.12 | AA | 1 |
+| `wcag-1.4.2-audio-control` | Audio Control | 1.4.2 | A | 1 |
+| `wcag-1.4.3-contrast-minimum` | Contrast: minimum | 1.4.3 | AA | 2 |
+| `wcag-1.4.4-resize-text` | Resize Text | 1.4.4 | AA | 1 |
+| `wcag-1.4.6-contrast-enhanced` | Contrast: enhanced | 1.4.6 | AAA | 2 |
+| `wcag-2.1.1-keyboard` | Keyboard | 2.1.1 | A | 5 |
+| `wcag-2.1.3-keyboard-no-exception` | Keyboard (No Exception) | 2.1.3 | AAA | 1 |
+| `wcag-2.2.1-timing-adjustable` | Timing Adjustable | 2.2.1 | A | 1 |
+| `wcag-2.2.2-pause-stop-hide` | Pause, Stop, Hide | 2.2.2 | A | 1 |
+| `wcag-2.2.4-interruptions` | Interruptions | 2.2.4 | AAA | 1 |
+| `wcag-2.4.1-bypass-blocks` | Bypass Blocks | 2.4.1 | A | 1 |
+| `wcag-2.4.2-page-titled` | Page titled | 2.4.2 | A | 2 |
+| `wcag-2.4.3-focus-order` | Focus order | 2.4.3 | A | 1 |
+| `wcag-2.4.4-link-purpose-in-context` | Link Purpose (In Context) | 2.4.4 | A | 1 |
+| `wcag-2.4.7-focus-visible` | Focus visible | 2.4.7 | AA | 3 |
+| `wcag-2.4.9-link-purpose-link-only` | Link Purpose (Link Only) | 2.4.9 | AAA | 1 |
+| `wcag-2.5.3-label-in-name` | Label in name | 2.5.3 | A | 1 |
+| `wcag-2.5.8-target-size-minimum` | Target size: minimum | 2.5.8 | AA | 1 |
+| `wcag-3.1.1-language-of-page` | Language of page | 3.1.1 | A | 2 |
+| `wcag-3.1.2-language-of-parts` | Language of Parts | 3.1.2 | AA | 1 |
+| `wcag-3.2.5-change-on-request` | Change on Request | 3.2.5 | AAA | 1 |
+| `wcag-3.3.2-labels-or-instructions` | Labels or Instructions | 3.3.2 | A | 2 |
+| `wcag-4.1.2-aria-validity` | Name, role, value: ARIA validity | 4.1.2 | A | 16 |
+| `wcag-4.1.2-name` | Name, role, value: accessible name | 4.1.2 | A | 23 |

package/docs/RULE_TAXONOMY.md

@@ -0,0 +1,145 @@
+# RULE_TAXONOMY.md — Canonical Rule Taxonomy (repo-derived)
+
+This document describes how rules in this repository are classified.
+It reflects **what already exists in the rules and tests**, not theory.
+
+---
+
+## 1. Primary taxonomy axes
+
+### 1.1 Automation / Decision Kind
+Encoded by: `meta.type`
+
+- `automatic`
+    - Rule makes a **normative decision**
+    - Allowed outcomes: `pass`, `fail`, `notApplicable`
+- `manual`
+    - Rule signals **human review required**
+    - Allowed outcomes: `cantTell`, `notApplicable`
+
+Manual rules MUST NOT make normative failure decisions.
+
+---
+
+### 1.2 Intent
+Encoded by: **rule id suffix**
+
+Current intents:
+
+- `present`
+    - Verifies that a required **mechanism exists**
+    - Typically automatic
+- `quality`
+    - Verifies appropriateness, correctness, or meaningfulness
+    - Always manual
+- `decorative`
+    - Verifies correct treatment of purely decorative content
+    - Always manual
+
+Intent determines whether a rule can be automatic.
+
+---
+
+### 1.3 Target Family
+Encoded by: **rule id prefix**
+
+Current families include:
+
+- `img`
+- `area`
+- `input-image`
+- `canvas`
+- `embed`
+- `object`
+- `svg`
+- `svg-image`
+- `video-poster`
+
+Each family defines:
+- which elements are queried
+- which helpers are applicable
+- which mechanisms are valid
+
+Rules MUST NOT mix families.
+
+---
+
+### 1.4 Target Set (Tree Scope)
+Encoded by: `data.visibilityFilter.targetSet`
+
+Current value used by this ruleset:
+- `acc` (accessibility tree)
+
+Rules explicitly log eligibility against the accessibility tree using:
+- `helpers.isAccTreeEligible`
+- `helpers.getEligibilityInfo(..., { targetSet: "acc" })`
+
+This is a semantic constraint, not logging noise.
+
+---
+
+### 1.5 Mechanism Type
+Implicitly encoded via helper usage and coverage facets.
+
+Examples:
+- attribute-based (`alt`, `poster`)
+- IDREF-based (`aria-labelledby`, `aria-describedby`)
+- fallback content (`<object>` contents)
+- computed accessible name / description
+- element-specific mechanisms (e.g. `<canvas>` alternatives)
+
+Different mechanisms require separate rules or facets.
+
+---
+
+### 1.6 WCAG Mapping
+Encoded by:
+- `meta.wcagSc`
+- `meta.normativeMappings`
+- optional `meta.informativeReferences`
+
+Multiple rules may map to the same SC.
+This is required for atomicity.
+
+---
+
+### 1.7 Coverage Facets
+Encoded by: `meta.coverage.facetsBySc`
+
+A **facet** represents one atomic coverage slice of a Success Criterion.
+
+Rules MUST:
+- declare at least one facet per SC
+- not share facets with rules that make a different decision
+- keep facet naming consistent within a family
+
+Facets are used for coverage accounting, not reporting.
+
+---
+
+## 2. Canonical rule family grid (example)
+
+For image alternatives (WCAG 1.1.1):
+
+| Rule ID | Family | Intent | Type |
+|------|-------|-------|------|
+| img-alt-present | img | present | automatic |
+| img-alt-quality | img | quality | manual |
+| img-alt-decorative | img | decorative | manual |
+
+Other families follow the same grid where applicable.
+
+---
+
+## 3. Atomicity rule (hard constraint)
+
+If two checks differ by **any** of the following, they MUST be separate rules:
+
+- normative vs review decision
+- intent (present / quality / decorative)
+- target family
+- mechanism type
+- outcome domain
+- coverage facet
+
+This constraint is already enforced by the existing ruleset.

package/docs/TROUBLESHOOTING.md

@@ -0,0 +1,48 @@
+# Troubleshooting / FAQ
+
+## "I passed `runOnly: ['some-rule-id']` but every rule still ran"
+
+`runOnly` must be an object, not a bare array — `runOnly: ['img-alt-present']` is silently ignored (the engine falls through to "run everything"), because that shape has none of the fields the engine actually checks (`includeRuleIds`, `tags`, etc.). This is easy to get wrong if you're coming from another engine that does accept a bare array.
+
+Fix:
+
+```js
+runOnly: { includeRuleIds: ['img-alt-present'] }
+```
+
+See [`ENGINE_OPTIONS.md`](./ENGINE_OPTIONS.md#via-runonly-4th-argument) for the full shape.
+
+## "My custom rule always returns `cantTell` with no clear reason"
+
+Check the result's `error` field first — if it says `"<something> is not defined"`, your `runInPage` references a variable from outside the function body (a module-scope `const`, an imported helper, anything not reached through `ctx.*`). This is a real, common footgun: `runInPage` is serialized to source text and re-evaluated later in the page context, so **the build never catches this — only running the rule does**, and the failure looks like a normal (if uninformative) result, not a crash. See [`RULE_AUTHORING.md`](./RULE_AUTHORING.md) §1.1 for the full explanation and the fix (move the value inside `runInPage`, or route it through `ctx.rule`/`ctx.helpers`).
+
+## "A geometry-dependent rule (e.g. `target-size-minimum`) always says `notApplicable`"
+
+Plain jsdom (no real browser) doesn't implement CSS layout — `getBoundingClientRect()` always returns zero geometry. Rules that need real layout deliberately report `notApplicable` under jsdom rather than guess. Run through a real browser instead (Puppeteer/Playwright — see [`INTEGRATION.md`](./INTEGRATION.md) Pattern 2) to get real findings from these rules. See [`LIMITATIONS.md`](./LIMITATIONS.md).
+
+## "I only see `fail`/`cantTell` occurrences — where's the list of elements that passed?"
+
+By design, this engine never enumerates the elements a rule *passed* — only the ones it flagged. A rule's overall `outcome: 'pass'` means "applicable target(s) existed and none were flagged," but `occurrences` is `[]` either way. If you need to know which specific elements were checked and considered fine, that's not currently exposed — see [`OUTPUT_SCHEMA.md`](./OUTPUT_SCHEMA.md#an-occurrence-occurrencesi).
+
+## "A rule I expected to fire returned `notApplicable` / found nothing on a page I know has the issue"
+
+Two common causes, in order of likelihood:
+
+1. **The element is excluded from the accessibility tree** — `aria-hidden="true"`, `display: none`, `visibility: hidden`, `hidden`, or an `inert` ancestor. Most rules deliberately skip content that's already invisible to assistive technology (checking a hidden element would be meaningless, and could produce a misleading `fail` on content no user encounters). Some rules explicitly opt out of this gating when it wouldn't make sense to (e.g. `no-autoplay-audio` — hidden audio still plays sound) — check the specific rule's file header comment (`@applicability`) in `src/checks/`.
+2. **`excludeSelectors`** — if you've configured this (directly or inherited from a shared config), confirm the element in question isn't matched by it.
+
+## "Does a clean scan (`pass` everywhere) mean the page is WCAG conformant?"
+
+No — see [`WCAG_CONFORMANCE.md`](./WCAG_CONFORMANCE.md). A `pass` means every *automatable* check came back clean. A meaningful fraction of WCAG requires human judgment (accurate alt text, understandable error messages) or dynamic testing this engine's architecture can't do at all (keyboard traps, reflow at zoom) — see [`LIMITATIONS.md`](./LIMITATIONS.md) for the explicit, non-exhaustive-on-purpose list.
+
+## "Should I treat `cantTell` as a failure?"
+
+Treat it as "needs a human to look" — it's neither pass nor fail by design. Most teams log `cantTell` findings without failing CI on them, since failing a build on something the engine explicitly couldn't determine tends to train people to ignore the gate. See [`POLICY.md`](./POLICY.md) if you want to reshape this behavior (e.g. via a custom policy contract), and [`INTEGRATION.md`](./INTEGRATION.md#ci-gating-a-build-on-the-result) for a concrete CI-gating example.
+
+## "Why is French only partially translated?"
+
+It genuinely is — see [`I18N.md`](./I18N.md) for the exact current coverage. Missing keys fall back to English per-string (never a blank or broken result), so a partial locale degrades gracefully rather than failing outright.
+
+## "`runDomRulesInPage` vs `runa11yCoreInPage` — which one do I want?"
+
+`runDomRulesInPage` if you're calling it directly in the same Node process (jsdom, browser-extension content script). `runa11yCoreInPage` if you're handing the *function itself* to a different JS realm — almost always `page.evaluate` in Puppeteer/Playwright, which serializes the function to source text and re-runs it inside the browser tab (which has no access to your Node module scope). See [`INTEGRATION.md`](./INTEGRATION.md) for both patterns worked out in full.

package/docs/WCAG_CONFORMANCE.md

@@ -0,0 +1,49 @@
+# WCAG conformance mapping guide
+
+How individual rule results relate to a WCAG Success Criterion (SC), and what surea11y can and cannot tell you about overall conformance.
+
+## The three layers
+
+1. **Atomic rules** (`checksResults[]`) — one normative decision each, e.g. "does this `<img>` have an `alt` attribute." See [`RULE_CATALOG.md`](./RULE_CATALOG.md) for all 123.
+2. **Facets** — a WCAG SC is usually bigger than any one rule can decide deterministically. Internally, each SC is broken into named "facets" (e.g. 1.1.1 Non-text Content has facets like `img-alt-attr-present`, `text-alternative-quality`, `decorative-null`) tracked in `src/coverage/wcag-facets.js`, each marked `full` (a rule decides it with high confidence), `partial` (a rule decides *part* of it — see each rule's own scope notes), or `manual` (no safe automated heuristic exists at all). Run `npm run coverage` to regenerate `coverage/coverage-report.md`, the per-SC facet breakdown.
+3. **Composite (WCAG-SC rollup) rules** (`rulesResults[]`) — a generated aggregate of every atomic rule mapped to one SC, giving you one pass/fail/cantTell/notApplicable verdict per SC instead of having to roll up dozens of atomic results yourself. See [`RULE_CATALOG.md`](./RULE_CATALOG.md#composite-wcag-sc-rollup-rules-31) for the full list (e.g. `wcag-1.1.1-non-text-content` rolls up 22 atomic rules).
+
+## How a composite's outcome is computed
+
+Deterministic precedence, evaluated over that composite's atomic contributors:
+
+| Condition | Composite outcome |
+|---|---|
+| Any contributor `fail` | `fail` |
+| No `fail`, but any contributor `cantTell` **or** a listed contributor didn't run at all | `cantTell` |
+| Every contributor `notApplicable` | `notApplicable` |
+| Otherwise (all ran, none failed/cantTell, not all N/A) | `pass` |
+
+This means: **a composite `pass` is a real, deterministic "every applicable automated check for this SC came back clean" — but it is not a WCAG conformance claim on its own.** If any facet of that SC has no automated coverage at all (see `coverage-report.md`), a composite `pass` is silent about that facet, not asserting it's fine. Cross-check the facet table before treating a composite `pass` as "SC fully verified."
+
+A composite's `data.details.contributors` array (see [`OUTPUT_SCHEMA.md`](./OUTPUT_SCHEMA.md#a-composite-result-rulesresultsi)) lists every atomic rule and its individual outcome — use this to see exactly which facet(s) drove a `fail`/`cantTell`, rather than treating the composite as a black box.
+
+## Targeting a conformance level (A / AA / AAA)
+
+Pass `runOnly.tags` (or `engineOptions.tags.include`) with one of `wcag2a`, `wcag2aa`, `wcag2aaa`:
+
+```js
+runDomRulesInPage(url, null, {}, { tags: ['wcag2aa'] });
+```
+
+This does two things at once:
+- **Filters atomic rules** to ones tagged at or under that level (a `wcag2aa`-tagged rule also carries `wcag2a`, since AA is cumulative on top of A — WCAG conformance is always defined this way).
+- **Suppresses composites above the target level** — e.g. requesting `wcag2aa` will not return a `rulesResults` entry for an AAA-only SC's composite, even if some AAA-level atomic rules happen to be tagged loosely. This is `inferTargetLevelFromRunOnly`/`isAllowedByTargetLevel` in the runner — see `src/core/dom-runner.js` if you need the exact precedence logic.
+
+Omit `tags` entirely (the default) and every rule at every level runs, with no composite suppression.
+
+## What this engine cannot tell you
+
+No automated tool — this one included — can certify full WCAG conformance. That's not a limitation specific to surea11y; it's inherent to WCAG itself; a meaningful fraction of Success Criteria require human judgment (is this alt text *accurate*, not just *present*; is this error message *understandable*) or dynamic testing this engine's static-DOM-scan architecture cannot do at all (keyboard-trap detection, real layout/reflow at zoom). See [`LIMITATIONS.md`](./LIMITATIONS.md) for the full, explicit list of what's out of scope and why.
+
+What surea11y *can* give you, honestly:
+- Every `fail` is a real, deterministic, normative violation — never a guess.
+- Every `cantTell` is an explicit flag for human review, not a swallowed uncertainty.
+- The facet coverage table tells you exactly which parts of which SCs have zero automated coverage, so you know where a `pass` is silent rather than exhaustive.
+
+A composite `pass` across every SC at your target level means: *every automatable check for that level came back clean.* It is the automatable subset of conformance, stated precisely — not a substitute for the manual review WCAG itself requires.

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@surea11y/core",
+  "version": "1.0.0",
+  "description": "Lightweight DOM rules accessibility core with modular rules.",
+  "main": "src/index.js",
+  "bin": {
+    "surea11y": "./bin/core.js"
+  },
+  "author": "Jorge Rumoroso",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rumoroso/surea11y-core.git"
+  },
+  "homepage": "https://github.com/rumoroso/surea11y-core#readme",
+  "bugs": {
+    "url": "https://github.com/rumoroso/surea11y-core/issues"
+  },
+  "engines": {
+    "node": "^20.19.0 || ^22.13.0 || >=24.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "bin",
+    "docs/**/*.md",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "!docs/RULE_TEMPLATE.md",
+    "!docs/RULE_TEST_TEMPLATE.md",
+    "!docs/RULE_TEST_AUTHORING.md",
+    "!docs/TEST_OUTCOME_STABILITY.md",
+    "!src/explain"
+  ],
+  "scripts": {
+    "build": "node scripts/build-core.js",
+    "test": "npm run build && node scripts/run-tests.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",
+    "engine-perf-bench-transparent": "node --expose-gc scripts/engine-perf-bench.js --profileRules=true --top=15 --iters=25 --generated=contrastTransparent",
+    "engine-perf-bench-opaque": "node --expose-gc scripts/engine-perf-bench.js --profileRules=true --top=15 --iters=25 --generated=contrastOpaque",
+    "test:typography-helpers": "node tests/contrast-typography.test.js",
+    "coverage": "node scripts/generate-wcag-coverage.js --rulesDir src/checks",
+    "coverage:strict": "node scripts/generate-wcag-coverage.js --rulesDir src/checks --strictFacets",
+    "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"
+  },
+  "devDependencies": {
+    "playwright": "^1.61.1"
+  }
+}