pour-engine 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David Yarham
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,99 @@
+# pour engine
+
+The accessibility audit engine behind [pour.dev](https://pour.dev) — a
+clean-room WCAG engine written from the W3C specifications. Zero
+dependencies, runs entirely in the browser, returns structured per-rule
+results with the exact failing elements and the evidence for each verdict.
+
+## Rules & coverage
+
+**WCAG only, by design.** The engine tracks the WCAG spec exclusively — no
+Section 508, EN 301 549, or other standards. The full WCAG 2.2 catalog (all
+86 success criteria) lives in `engine/wcag22.js`, and
+[`engine/COVERAGE.md`](engine/COVERAGE.md) shows exactly which criteria are
+automated, partially automated, or need human review. Rules pierce open
+shadow DOM, callers can cover same-origin frames by running the engine per
+document, and every result carries its WCAG criterion, severity, a CSS path
+to the element, and an HTML snippet.
+
+Automation has limits, and the engine is honest about them: criteria no tool
+can verify are returned as a `manualReview` checklist instead of being
+silently skipped, and findings the engine can't judge conclusively land in
+`incomplete` rather than being guessed at.
+
+An experimental WCAG 3.0 draft mode (`engine/wcag30-draft.js`) reframes
+results against the draft's guidelines — clearly stamped as a draft, because
+no tool can honestly claim conformance to an unfinished standard.
+
+## Getting started
+
+```sh
+npm install pour-engine
+```
+
+> Not yet published to npm — `package.json` is marked `"private": true` while
+> this repository stays private. Remove that flag when open-sourcing.
+
+```js
+import { run, name, version } from 'pour-engine';
+
+// Audit the current document (browser, extension content script, bookmarklet…)
+const results = await run(document, {
+  // optional: filter rules by tag. Tags are cumulative — WCAG 2.2 AA means
+  // every A/AA rule from 2.0 through 2.2. Omit to run everything.
+  tags: ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'wcag22a', 'wcag22aa'],
+  // standard: 'wcag30-draft', // optional: experimental WCAG 3.0 draft mode
+});
+
+console.log(results.violations, results.passes, results.incomplete);
+```
+
+`run(context, options, onProgress)` accepts any Document (the top document
+or an iframe's), an options object, and an optional progress callback
+invoked before and after each rule — useful for live progress UI. Results
+include `violations`, `passes`, `incomplete`, `inapplicable`,
+`manualReview`, and per-rule timings.
+
+## Philosophy
+
+- **Spec-first.** Every rule and helper was written from the W3C
+  specifications (WCAG, ARIA, accname), not from other tools' behavior.
+  When a rule tightens, it tightens toward the spec.
+- **Zero dependencies.** The engine ships nothing but its own code, so it
+  can run anywhere a DOM exists — content scripts, bookmarklets, test
+  harnesses — without bundling baggage or supply-chain surface.
+- **No false authority.** A result is a violation only when the spec says
+  so. Everything uncertain is `incomplete` or `manualReview`, never a guess
+  dressed up as a finding.
+
+## Supported environments
+
+Any evergreen browser (the pour extension ships to Chromium; the bookmarklet
+runs wherever it's dropped). The engine needs a live DOM — it does not parse
+static HTML strings. For Node-based testing, drive it through a real browser
+(Puppeteer/Playwright).
+
+## Package contents
+
+- `engine/index.js` — the runner: rule selection, scoping, timings, results.
+- `engine/rules/` — one file per rule, named by criterion
+  (`1.1.1-image-alt.js`), plus the catalog index.
+- `engine/lib/` — shared helpers: DOM traversal, accessible-name
+  computation, contrast math, role model.
+- `engine/wcag22.js`, `engine/wcag30-draft.js` — the WCAG catalogs.
+- `config/project.config.js` — package-local stand-in for the pour
+  monorepo's project config (engine name + version only).
+
+The `engine/` directory is a byte-identical copy of `src/engine/` in the
+pour monorepo, which is the current source of truth — make changes there and
+sync them here. The test suite (annotated testbed pages and the verification
+runner) also lives in the monorepo and is not part of this package yet.
+
+## License
+
+Every rule and helper was written from the W3C specifications (WCAG 2.2,
+WAI-ARIA, accname). Rule ids and tag names follow the vocabulary the
+accessibility-tooling ecosystem already shares, so reports interoperate
+with existing pipelines.
+
+MIT — see [LICENSE](LICENSE).

package/config/project.config.js

@@ -0,0 +1,11 @@
+// Package-local stand-in for the pour monorepo's project config. The engine
+// source under engine/ is a byte-identical copy of the monorepo's src/engine/
+// — it imports '../config/project.config.js', and this file satisfies that
+// import so the copy needs no edits. Keep engine.version in step with
+// package.json's version.
+export default {
+  engine: {
+    name: 'pour engine',
+    version: '1.1.0',
+  },
+};

package/engine/COVERAGE.md

@@ -0,0 +1,115 @@
+# WCAG 2.2 coverage
+
+Generated by `node scripts/wcag-coverage.js` — do not edit by hand.
+
+All 86 success criteria of WCAG 2.2, and how the native engine covers them.
+"Partially automated" means our rules catch common failures but cannot prove conformance;
+"Manual review" criteria need a human (most of the spec — true for every automated tool).
+
+## Perceivable
+
+| SC | Name | Level | Coverage | Rules |
+|---|---|---|---|---|
+| 1.1.1 | [Non-text Content](https://www.w3.org/WAI/WCAG22/Understanding/non-text-content.html) | A | Partially automated | area-alt, image-alt, input-image-alt, object-alt, svg-img-alt |
+| 1.2.1 | [Audio-only and Video-only (Prerecorded)](https://www.w3.org/WAI/WCAG22/Understanding/audio-only-and-video-only-prerecorded.html) | A | Manual review | — |
+| 1.2.2 | [Captions (Prerecorded)](https://www.w3.org/WAI/WCAG22/Understanding/captions-prerecorded.html) | A | Partially automated | media-captions |
+| 1.2.3 | [Audio Description or Media Alternative (Prerecorded)](https://www.w3.org/WAI/WCAG22/Understanding/audio-description-or-media-alternative-prerecorded.html) | A | Manual review | — |
+| 1.2.4 | [Captions (Live)](https://www.w3.org/WAI/WCAG22/Understanding/captions-live.html) | AA | Manual review | — |
+| 1.2.5 | [Audio Description (Prerecorded)](https://www.w3.org/WAI/WCAG22/Understanding/audio-description-prerecorded.html) | AA | Manual review | — |
+| 1.2.6 | [Sign Language (Prerecorded)](https://www.w3.org/WAI/WCAG22/Understanding/sign-language-prerecorded.html) | AAA | Manual review | — |
+| 1.2.7 | [Extended Audio Description (Prerecorded)](https://www.w3.org/WAI/WCAG22/Understanding/extended-audio-description-prerecorded.html) | AAA | Manual review | — |
+| 1.2.8 | [Media Alternative (Prerecorded)](https://www.w3.org/WAI/WCAG22/Understanding/media-alternative-prerecorded.html) | AAA | Manual review | — |
+| 1.2.9 | [Audio-only (Live)](https://www.w3.org/WAI/WCAG22/Understanding/audio-only-live.html) | AAA | Manual review | — |
+| 1.3.1 | [Info and Relationships](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html) | A | Partially automated | aria-required-children, aria-required-parent, definition-list, dlitem-parent, form-label, list-structure, listitem-parent, p-as-heading, table-headers |
+| 1.3.2 | [Meaningful Sequence](https://www.w3.org/WAI/WCAG22/Understanding/meaningful-sequence.html) | A | Manual review | — |
+| 1.3.3 | [Sensory Characteristics](https://www.w3.org/WAI/WCAG22/Understanding/sensory-characteristics.html) | A | Manual review | — |
+| 1.3.4 | [Orientation](https://www.w3.org/WAI/WCAG22/Understanding/orientation.html) | AA | Manual review | — |
+| 1.3.5 | [Identify Input Purpose](https://www.w3.org/WAI/WCAG22/Understanding/identify-input-purpose.html) | AA | Partially automated | autocomplete-valid |
+| 1.3.6 | [Identify Purpose](https://www.w3.org/WAI/WCAG22/Understanding/identify-purpose.html) | AAA | Manual review | — |
+| 1.4.1 | [Use of Color](https://www.w3.org/WAI/WCAG22/Understanding/use-of-color.html) | A | Partially automated | link-in-text-block |
+| 1.4.2 | [Audio Control](https://www.w3.org/WAI/WCAG22/Understanding/audio-control.html) | A | Partially automated | audio-control |
+| 1.4.3 | [Contrast (Minimum)](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html) | AA | Partially automated | color-contrast, control-contrast |
+| 1.4.4 | [Resize Text](https://www.w3.org/WAI/WCAG22/Understanding/resize-text.html) | AA | Partially automated | meta-viewport |
+| 1.4.5 | [Images of Text](https://www.w3.org/WAI/WCAG22/Understanding/images-of-text.html) | AA | Manual review | — |
+| 1.4.6 | [Contrast (Enhanced)](https://www.w3.org/WAI/WCAG22/Understanding/contrast-enhanced.html) | AAA | Partially automated | color-contrast-enhanced |
+| 1.4.7 | [Low or No Background Audio](https://www.w3.org/WAI/WCAG22/Understanding/low-or-no-background-audio.html) | AAA | Manual review | — |
+| 1.4.8 | [Visual Presentation](https://www.w3.org/WAI/WCAG22/Understanding/visual-presentation.html) | AAA | Manual review | — |
+| 1.4.9 | [Images of Text (No Exception)](https://www.w3.org/WAI/WCAG22/Understanding/images-of-text-no-exception.html) | AAA | Manual review | — |
+| 1.4.10 | [Reflow](https://www.w3.org/WAI/WCAG22/Understanding/reflow.html) | AA | Partially automated | reflow |
+| 1.4.11 | [Non-text Contrast](https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast.html) | AA | Partially automated | non-text-contrast |
+| 1.4.12 | [Text Spacing](https://www.w3.org/WAI/WCAG22/Understanding/text-spacing.html) | AA | Partially automated | text-spacing |
+| 1.4.13 | [Content on Hover or Focus](https://www.w3.org/WAI/WCAG22/Understanding/content-on-hover-or-focus.html) | AA | Manual review | — |
+
+## Operable
+
+| SC | Name | Level | Coverage | Rules |
+|---|---|---|---|---|
+| 2.1.1 | [Keyboard](https://www.w3.org/WAI/WCAG22/Understanding/keyboard.html) | A | Partially automated | scrollable-region-focusable |
+| 2.1.2 | [No Keyboard Trap](https://www.w3.org/WAI/WCAG22/Understanding/no-keyboard-trap.html) | A | Manual review | — |
+| 2.1.3 | [Keyboard (No Exception)](https://www.w3.org/WAI/WCAG22/Understanding/keyboard-no-exception.html) | AAA | Partially automated | scrollable-region-focusable |
+| 2.1.4 | [Character Key Shortcuts](https://www.w3.org/WAI/WCAG22/Understanding/character-key-shortcuts.html) | A | Manual review | — |
+| 2.2.1 | [Timing Adjustable](https://www.w3.org/WAI/WCAG22/Understanding/timing-adjustable.html) | A | Partially automated | meta-refresh |
+| 2.2.2 | [Pause, Stop, Hide](https://www.w3.org/WAI/WCAG22/Understanding/pause-stop-hide.html) | A | Partially automated | pause-stop-hide |
+| 2.2.3 | [No Timing](https://www.w3.org/WAI/WCAG22/Understanding/no-timing.html) | AAA | Manual review | — |
+| 2.2.4 | [Interruptions](https://www.w3.org/WAI/WCAG22/Understanding/interruptions.html) | AAA | Manual review | — |
+| 2.2.5 | [Re-authenticating](https://www.w3.org/WAI/WCAG22/Understanding/re-authenticating.html) | AAA | Manual review | — |
+| 2.2.6 | [Timeouts](https://www.w3.org/WAI/WCAG22/Understanding/timeouts.html) | AAA | Manual review | — |
+| 2.3.1 | [Three Flashes or Below Threshold](https://www.w3.org/WAI/WCAG22/Understanding/three-flashes-or-below-threshold.html) | A | Manual review | — |
+| 2.3.2 | [Three Flashes](https://www.w3.org/WAI/WCAG22/Understanding/three-flashes.html) | AAA | Manual review | — |
+| 2.3.3 | [Animation from Interactions](https://www.w3.org/WAI/WCAG22/Understanding/animation-from-interactions.html) | AAA | Manual review | — |
+| 2.4.1 | [Bypass Blocks](https://www.w3.org/WAI/WCAG22/Understanding/bypass-blocks.html) | A | Partially automated | bypass-blocks |
+| 2.4.2 | [Page Titled](https://www.w3.org/WAI/WCAG22/Understanding/page-titled.html) | A | Automated | document-title |
+| 2.4.3 | [Focus Order](https://www.w3.org/WAI/WCAG22/Understanding/focus-order.html) | A | Manual review | — |
+| 2.4.4 | [Link Purpose (In Context)](https://www.w3.org/WAI/WCAG22/Understanding/link-purpose-in-context.html) | A | Partially automated | area-alt, link-name |
+| 2.4.5 | [Multiple Ways](https://www.w3.org/WAI/WCAG22/Understanding/multiple-ways.html) | AA | Manual review | — |
+| 2.4.6 | [Headings and Labels](https://www.w3.org/WAI/WCAG22/Understanding/headings-and-labels.html) | AA | Manual review | — |
+| 2.4.7 | [Focus Visible](https://www.w3.org/WAI/WCAG22/Understanding/focus-visible.html) | AA | Partially automated | focus-visible |
+| 2.4.8 | [Location](https://www.w3.org/WAI/WCAG22/Understanding/location.html) | AAA | Manual review | — |
+| 2.4.9 | [Link Purpose (Link Only)](https://www.w3.org/WAI/WCAG22/Understanding/link-purpose-link-only.html) | AAA | Manual review | — |
+| 2.4.10 | [Section Headings](https://www.w3.org/WAI/WCAG22/Understanding/section-headings.html) | AAA | Manual review | — |
+| 2.4.11 | [Focus Not Obscured (Minimum)](https://www.w3.org/WAI/WCAG22/Understanding/focus-not-obscured-minimum.html) | AA | Partially automated | focus-not-obscured |
+| 2.4.12 | [Focus Not Obscured (Enhanced)](https://www.w3.org/WAI/WCAG22/Understanding/focus-not-obscured-enhanced.html) | AAA | Manual review | — |
+| 2.4.13 | [Focus Appearance](https://www.w3.org/WAI/WCAG22/Understanding/focus-appearance.html) | AAA | Manual review | — |
+| 2.5.1 | [Pointer Gestures](https://www.w3.org/WAI/WCAG22/Understanding/pointer-gestures.html) | A | Manual review | — |
+| 2.5.2 | [Pointer Cancellation](https://www.w3.org/WAI/WCAG22/Understanding/pointer-cancellation.html) | A | Manual review | — |
+| 2.5.3 | [Label in Name](https://www.w3.org/WAI/WCAG22/Understanding/label-in-name.html) | A | Manual review | — |
+| 2.5.4 | [Motion Actuation](https://www.w3.org/WAI/WCAG22/Understanding/motion-actuation.html) | A | Manual review | — |
+| 2.5.5 | [Target Size (Enhanced)](https://www.w3.org/WAI/WCAG22/Understanding/target-size-enhanced.html) | AAA | Partially automated | target-size-enhanced |
+| 2.5.6 | [Concurrent Input Mechanisms](https://www.w3.org/WAI/WCAG22/Understanding/concurrent-input-mechanisms.html) | AAA | Manual review | — |
+| 2.5.7 | [Dragging Movements](https://www.w3.org/WAI/WCAG22/Understanding/dragging-movements.html) | AA | Manual review | — |
+| 2.5.8 | [Target Size (Minimum)](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html) | AA | Partially automated | target-size |
+
+## Understandable
+
+| SC | Name | Level | Coverage | Rules |
+|---|---|---|---|---|
+| 3.1.1 | [Language of Page](https://www.w3.org/WAI/WCAG22/Understanding/language-of-page.html) | A | Automated | html-lang |
+| 3.1.2 | [Language of Parts](https://www.w3.org/WAI/WCAG22/Understanding/language-of-parts.html) | AA | Partially automated | valid-lang-parts |
+| 3.1.3 | [Unusual Words](https://www.w3.org/WAI/WCAG22/Understanding/unusual-words.html) | AAA | Manual review | — |
+| 3.1.4 | [Abbreviations](https://www.w3.org/WAI/WCAG22/Understanding/abbreviations.html) | AAA | Manual review | — |
+| 3.1.5 | [Reading Level](https://www.w3.org/WAI/WCAG22/Understanding/reading-level.html) | AAA | Manual review | — |
+| 3.1.6 | [Pronunciation](https://www.w3.org/WAI/WCAG22/Understanding/pronunciation.html) | AAA | Manual review | — |
+| 3.2.1 | [On Focus](https://www.w3.org/WAI/WCAG22/Understanding/on-focus.html) | A | Manual review | — |
+| 3.2.2 | [On Input](https://www.w3.org/WAI/WCAG22/Understanding/on-input.html) | A | Manual review | — |
+| 3.2.3 | [Consistent Navigation](https://www.w3.org/WAI/WCAG22/Understanding/consistent-navigation.html) | AA | Manual review | — |
+| 3.2.4 | [Consistent Identification](https://www.w3.org/WAI/WCAG22/Understanding/consistent-identification.html) | AA | Manual review | — |
+| 3.2.5 | [Change on Request](https://www.w3.org/WAI/WCAG22/Understanding/change-on-request.html) | AAA | Manual review | — |
+| 3.2.6 | [Consistent Help](https://www.w3.org/WAI/WCAG22/Understanding/consistent-help.html) | A | Manual review | — |
+| 3.3.1 | [Error Identification](https://www.w3.org/WAI/WCAG22/Understanding/error-identification.html) | A | Manual review | — |
+| 3.3.2 | [Labels or Instructions](https://www.w3.org/WAI/WCAG22/Understanding/labels-or-instructions.html) | A | Partially automated | form-label |
+| 3.3.3 | [Error Suggestion](https://www.w3.org/WAI/WCAG22/Understanding/error-suggestion.html) | AA | Manual review | — |
+| 3.3.4 | [Error Prevention (Legal, Financial, Data)](https://www.w3.org/WAI/WCAG22/Understanding/error-prevention-legal-financial-data.html) | AA | Manual review | — |
+| 3.3.5 | [Help](https://www.w3.org/WAI/WCAG22/Understanding/help.html) | AAA | Manual review | — |
+| 3.3.6 | [Error Prevention (All)](https://www.w3.org/WAI/WCAG22/Understanding/error-prevention-all.html) | AAA | Manual review | — |
+| 3.3.7 | [Redundant Entry](https://www.w3.org/WAI/WCAG22/Understanding/redundant-entry.html) | A | Manual review | — |
+| 3.3.8 | [Accessible Authentication (Minimum)](https://www.w3.org/WAI/WCAG22/Understanding/accessible-authentication-minimum.html) | AA | Partially automated | auth-field-obstruction |
+| 3.3.9 | [Accessible Authentication (Enhanced)](https://www.w3.org/WAI/WCAG22/Understanding/accessible-authentication-enhanced.html) | AAA | Manual review | — |
+
+## Robust
+
+| SC | Name | Level | Coverage | Rules |
+|---|---|---|---|---|
+| 4.1.2 | [Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) | A | Partially automated | input-image-alt, form-label, link-name, aria-allowed-attr, aria-attr-valid, aria-field-name, aria-hidden-focus, aria-valid-refs, button-name, dialog-name, frame-title, label-for-valid, nested-interactive, role-required-aria, valid-role |
+| 4.1.3 | [Status Messages](https://www.w3.org/WAI/WCAG22/Understanding/status-messages.html) | AA | Manual review | — |
+
+**Totals:** 2 automated · 26 partially automated · 58 manual — with 71 rules.

package/engine/README.md

@@ -0,0 +1,115 @@
+# pour engine
+
+Our own accessibility engine (name/version defined in
+`src/config/project.config.js`) — written from the W3C specifications, and
+the product's only engine.
+
+**WCAG only, by design.** pour engine tracks the WCAG spec exclusively — no
+Section 508, EN 301 549, or other standards. The full WCAG 2.2 catalog (all
+86 success criteria) lives in `wcag22.js`, and `COVERAGE.md` (generated by
+`node scripts/wcag-coverage.js`) shows exactly which criteria are automated,
+partially automated, or need human review.
+
+## Provenance
+
+Every rule and helper is written from the W3C specifications — WCAG 2.2,
+WAI-ARIA, and the accessible-name computation spec. Where a threshold
+appears in the code (4.5:1, 24px, 72000 s), it comes from the spec text
+itself.
+
+The result vocabulary follows the conventions the accessibility-tooling
+ecosystem already speaks, so reports interoperate with existing pipelines:
+rule ids like `image-alt`, the `wcag2a`/`wcag111` tag scheme, the
+`critical/serious/moderate/minor` impact scale, and the result schema
+(`violations/passes/incomplete/inapplicable`, `helpUrl`, `failureSummary`).
+All user-facing prose (`help`, `message`, `fix`) is original.
+
+## What it aims to do well
+
+1. **Actionable messages.** Every finding says *how to fix it*, with
+   concrete suggested code for the specific element (see any rule's
+   `fix()`), not just what failed in spec language.
+2. **Readable source.** Each rule is one small file a contributor can read
+   in a minute — no rule → checks → metadata indirection.
+3. **Resolved verdicts over "incomplete" noise.** The engine works to
+   resolve backgrounds, backdrops, and paint order before giving up — and
+   when it genuinely can't judge, it says so plainly instead of guessing.
+4. **Size.** The engine is a few KB, so the extension and bookmarklet stay
+   light.
+5. **Filters integration.** Vision/sensory filters and the engine share
+   colour math and DOM helpers.
+6. **"Overdoing it" rules.** Best-practice rules that flag *redundant*
+   accessibility — role="list" on a `<ul>`, aria-required duplicating
+   required, aria-label repeating visible text, alt text starting with
+   "image of", tabindex="0" on a `<button>`. Leaner markup is better
+   markup. (Enable "Best practices" in settings to see them.)
+
+## Architecture
+
+```
+src/engine/
+  index.js               run(context, {tags}, onProgress) → results
+  wcag22.js              the full WCAG 2.2 success-criteria catalog
+  lib/
+    dom.js               visibility, CSS-path selectors, html snippets
+    accessible-name.js   accessible-name computation
+    contrast.js          colour parsing, luminance, contrast + pixel sampling
+    roles.js             ARIA role model (implicit roles, allowed attributes)
+  rules/
+    index.js             rule registry
+    wcag/<rule>.js       spec-required rules (tagged with wcag* criteria)
+    best-practice/<rule>.js  opt-in extras (tagged 'best-practice')
+```
+
+A rule is a small object:
+
+```js
+export default {
+  id: 'image-alt',
+  impact: 'critical',            // critical | serious | moderate | minor
+  tags: ['wcag2a', 'wcag111'],   // version/level tags + criterion tags
+  help: 'Every <img> needs a text alternative',
+  helpUrl: 'https://…',
+  selector: 'img',               // which elements the rule applies to
+  visibleOnly: true,             // skip hidden elements (default true)
+  evaluate(element, helpers) {
+    // → { status: 'pass' } or { status: 'fail'|'incomplete', message, fix }
+  },
+};
+```
+
+`run(context, { tags })` selects rules by tag, evaluates each matching
+element, and buckets results into `violations / passes / incomplete /
+inapplicable`, each node carrying its target selector, html snippet, and a
+plain-language failure summary with a concrete fix.
+
+Rules that need to see the whole page at once (e.g. heading order) implement
+`evaluateAll(elements, helpers)` instead of `evaluate`.
+
+## The spec is the authority
+
+Every rule is adjudicated against the WCAG, accname, and ARIA specs — those
+documents decide what is a violation. The engine is also validated
+continuously against pixel-measured ground truth on real sites (see the
+repository's engine lab) so its verdicts answer to rendered reality, not
+just to static analysis.
+
+## Full-spec coverage model
+
+Rules alone can never "cover WCAG" — most criteria need human judgment.
+pour engine therefore reports on **every** in-scope criterion, one of two ways:
+
+1. **Automated/partial** — the rules in `rules/`.
+2. **Manual review** — every audit's results include `manualReview`: the
+   in-scope criteria (filtered by the requested WCAG version and level)
+   that automation can't judge, rendered as a checklist in the extension.
+
+Nothing in the spec is silently skipped — that claim is the product.
+
+## Honest current state
+
+61 rules, hardened on real sites and the `testbeds/` pages. Known gaps:
+shadow DOM and iframe traversal, the full accname spec (ours is a close
+approximation), and the language subtag registry (BCP 47 shape check only).
+Grow it rule by rule; the test beds' `expect:` annotations are the
+regression suite.

package/engine/index.js

@@ -0,0 +1,258 @@
+// DY Engine runner: evaluates every applicable rule against the page and
+// returns structured results (violations / passes / incomplete /
+// inapplicable, plus the manual-review criteria and per-rule timings).
+import config from '../config/project.config.js';
+import rules from './rules/index.js';
+import wcagCatalog from './wcag22.js';
+import wcag30Draft from './wcag30-draft.js';
+import { isVisible, isRendered, cssPath, htmlSnippet, ownText, collectRoots } from './lib/dom.js';
+import { accessibleName } from './lib/accessible-name.js';
+import { resetAuditCaches } from './lib/contrast.js';
+
+export const name = config.engine.name;
+export const version = config.engine.version;
+
+const ruleHelpers = { isVisible, isRendered, cssPath, htmlSnippet, ownText, accessibleName };
+
+/** Does this rule match the requested tag selection? Empty/absent = all rules. */
+function ruleMatchesTags(rule, tags) {
+  if (!tags?.length) return true;
+  return rule.tags.some((tag) => tags.includes(tag));
+}
+
+/** Which WCAG version/level was requested, judged from the selected tags. */
+function scopeFromTags(tags) {
+  if (!tags?.length) return { version: '2.2', level: 'AAA' }; // no filter → everything
+  const version = tags.some((t) => t.startsWith('wcag22')) ? '2.2'
+    : tags.some((t) => t.startsWith('wcag21')) ? '2.1' : '2.0';
+  const level = tags.some((t) => /aaa$/.test(t)) ? 'AAA'
+    : tags.some((t) => /aa$/.test(t)) ? 'AA' : 'A';
+  return { version, level };
+}
+
+const VERSION_ORDER = { '2.0': 0, '2.1': 1, '2.2': 2 };
+const LEVEL_ORDER = { A: 0, AA: 1, AAA: 2 };
+
+/**
+ * The WCAG criteria in scope that automation cannot fully judge — reported
+ * with every audit so that "full spec coverage" is real: rules handle what
+ * they can, and the rest is an explicit human checklist, never silence.
+ */
+function manualReviewCriteria(tags) {
+  const scope = scopeFromTags(tags);
+  return wcagCatalog
+    .filter((criterion) => criterion.automation !== 'auto')
+    .filter((criterion) => VERSION_ORDER[criterion.since] <= VERSION_ORDER[scope.version])
+    .filter((criterion) => LEVEL_ORDER[criterion.level] <= LEVEL_ORDER[scope.level])
+    .map(({ num, name: criterionName, level, principle, url, automation }) =>
+      ({ num, name: criterionName, level, principle, url, automation }));
+}
+
+/**
+ * True when the element, or any flat-tree ancestor (crossing shadow
+ * boundaries host-ward), matches the exclude selector. Lets a testing tool
+ * keep its own injected UI out of the audit — a panel drawn over the page
+ * must never appear in the page's results.
+ */
+function isExcluded(element, selector) {
+  let node = element;
+  while (node) {
+    if (node.closest?.(selector)) return true;
+    node = node.getRootNode()?.host ?? null;
+  }
+  return false;
+}
+
+/** Serialize one evaluated element into a result node. */
+function toResultNode(element, outcome) {
+  const node = {
+    target: [cssPath(element)],
+    html: htmlSnippet(element),
+    failureSummary: [outcome.message, outcome.fix && `Fix: ${outcome.fix}`].filter(Boolean).join('\n'),
+  };
+  // Structured extras from the rule (e.g. the exact colour pair behind a
+  // contrast failure) ride along for UIs that can use them.
+  if (outcome.data) node.data = outcome.data;
+  return node;
+}
+
+/**
+ * Run the audit.
+ * @param {Document|Element} context - what to scan
+ * @param {{ tags?: string[], exclude?: string, standard?: string, signal?: AbortSignal }} options -
+ *   rule selection by tag (wcag2a…wcag22aa, best-practice), empty selects
+ *   every rule; exclude is a CSS selector — elements matching it, or inside
+ *   a match (including across shadow boundaries), are left out of every
+ *   rule; standard 'wcag30-draft' reframes the report against the WCAG 3.0
+ *   Working Draft (results.standard is stamped draft, the manual checklist
+ *   becomes the draft guidelines, and each rule result carries the draft
+ *   guideline it maps to) — the rules themselves stay WCAG 2.x, which is
+ *   the only honest claim a tool can make about a draft;
+ *   signal aborts the run between rules (throws AbortError)
+ * @param {(progress: object) => void} [onProgress] - called before each rule
+ *   starts ({rule, running}), during a rule at each renderer yield with a
+ *   fractional done (completed rules + this rule's evaluated-element share,
+ *   so a bar fills smoothly through big element sets), and after it
+ *   finishes ({rule, ms, counts})
+ */
+export async function run(context = document, options = {}, onProgress) {
+  const auditStarted = performance.now();
+  const draft30 = options.standard === 'wcag30-draft';
+  const results = {
+    testEngine: { name, version },
+    timestamp: new Date().toISOString(),
+    url: context.location?.href ?? context.ownerDocument?.location?.href ?? '',
+    standard: draft30 ? wcag30Draft.draftInfo : null,
+    violations: [],
+    passes: [],
+    incomplete: [],
+    inapplicable: [],
+    manualReview: draft30 ? wcag30Draft.manualReviewChecklist() : manualReviewCriteria(options.tags),
+    ruleTimings: [],
+  };
+
+  // `disabled: true` keeps a rule in the codebase (and coverage docs) but
+  // out of every run — for rules parked pending quality review.
+  const activeRules = rules.filter((rule) => !rule.disabled && ruleMatchesTags(rule, options.tags));
+  // Per-audit caches (resolved backgrounds, opacities) must start fresh —
+  // the page may have changed since the last run.
+  resetAuditCaches();
+  // Every queryable root — the page plus all open shadow trees — collected
+  // once so rules see web-component content without re-walking per rule.
+  const roots = collectRoots(context.querySelectorAll ? context : document);
+  // Universal-selector rules (aria attribute checks) share one full scan
+  // instead of each re-enumerating every element on the page.
+  let universalScan = null;
+  const elementsFor = (selector) => {
+    if (selector === '*') {
+      universalScan ??= roots.flatMap((root) => [...root.querySelectorAll('*')]);
+      return universalScan;
+    }
+    return roots.flatMap((root) => [...root.querySelectorAll(selector)]);
+  };
+  let completed = 0;
+  // Running totals so the UI can count issues up live as rules finish —
+  // both affected elements and distinct rules ("types") per severity.
+  const liveCounts = { critical: 0, serious: 0, moderate: 0, minor: 0, review: 0 };
+  const liveTypeCounts = { critical: 0, serious: 0, moderate: 0, minor: 0, review: 0 };
+
+  // The audit shares the page's main thread. Rules only await microtasks,
+  // so without a real yield the whole run is one long task and the browser
+  // never paints — in-page progress UI (the bookmarklet panel) would appear
+  // only when everything is done, and the audited page itself freezes.
+  // Yield about once a frame; between rules is the granularity we have.
+  let lastYield = performance.now();
+  // Yield via MessageChannel: a normal macrotask like setTimeout(0) — fair
+  // FIFO with the audited page's own tasks (deliberately NOT
+  // scheduler.yield(), whose continuations outprioritize and starve them) —
+  // but WITHOUT the ~4ms nested-timer clamp, which added phantom wall time
+  // across the hundreds of yields of a large audit.
+  const yieldChannel = typeof MessageChannel === 'function' ? new MessageChannel() : null;
+  const nextTask = () => new Promise((resolve) => {
+    if (!yieldChannel) { setTimeout(resolve, 0); return; }
+    yieldChannel.port1.onmessage = resolve; // one yield in flight at a time
+    yieldChannel.port2.postMessage(0);
+  });
+  const yieldToRenderer = async (beforeYield) => {
+    if (performance.now() - lastYield < 16) return;
+    // Runs only when a real yield (and so a paint) follows — the natural
+    // throttle for mid-rule progress reports.
+    beforeYield?.();
+    await nextTask();
+    lastYield = performance.now();
+  };
+
+  for (const rule of activeRules) {
+    // Between rules is the abort granularity we have — the same boundary
+    // the renderer yield uses.
+    if (options.signal?.aborted) throw new DOMException('Audit stopped', 'AbortError');
+    await yieldToRenderer();
+    // Announce BEFORE running: the UI label must show the rule currently
+    // under test, not the one that just finished (a slow rule would
+    // otherwise sit blamed on its predecessor's name).
+    onProgress?.({ done: completed, total: activeRules.length, rule: rule.id, running: true });
+    const ruleStarted = performance.now();
+
+    let elements = elementsFor(rule.selector);
+    if (options.exclude) {
+      elements = elements.filter((element) => !isExcluded(element, options.exclude));
+    }
+    if (rule.visibleOnly !== false) {
+      // visibility: 'visual' → rendered on screen counts even inside
+      // aria-hidden (visual rules); default → must be exposed to AT too.
+      elements = elements.filter(rule.visibility === 'visual' ? isRendered : isVisible);
+    }
+
+    let outcomes;
+    if (rule.evaluateAll) {
+      outcomes = rule.evaluateAll(elements, ruleHelpers);
+    } else {
+      // Evaluate sequentially with periodic yields so ONE heavy rule on a
+      // huge element set can't freeze the page for its whole duration —
+      // and so a Stop lands mid-rule, not only between rules.
+      outcomes = new Array(elements.length);
+      for (let i = 0; i < elements.length; i++) {
+        if ((i & 31) === 0 && i > 0) {
+          if (options.signal?.aborted) throw new DOMException('Audit stopped', 'AbortError');
+          // Fractional done: this rule's slice of the bar fills as its
+          // elements are evaluated instead of jumping on completion.
+          await yieldToRenderer(() => onProgress?.({
+            done: completed + i / elements.length,
+            total: activeRules.length,
+            rule: rule.id,
+            running: true,
+          }));
+        }
+        outcomes[i] = await rule.evaluate(elements[i], ruleHelpers);
+      }
+    }
+
+    // Only failures and review findings serialize element details — pass
+    // nodes are counted, not rendered: nothing consumes them, and building
+    // cssPath/snippets for every passing element dominated audit time on
+    // large pages.
+    const buckets = { fail: [], incomplete: [] };
+    let passCount = 0;
+    elements.forEach((element, i) => {
+      const status = outcomes[i].status;
+      if (status === 'pass') passCount += 1;
+      else buckets[status]?.push(toResultNode(element, outcomes[i]));
+    });
+
+    const ruleResult = {
+      id: rule.id,
+      impact: rule.impact,
+      tags: rule.tags,
+      help: rule.help,
+      description: rule.help,
+      helpUrl: rule.helpUrl,
+    };
+    if (draft30) {
+      // Which draft guideline this 2.x rule speaks to (null for rules with
+      // no draft counterpart, e.g. best-practice extras).
+      ruleResult.wcag30 = wcag30Draft.guidelineForTags(rule.tags);
+    }
+    if (!elements.length) results.inapplicable.push({ ...ruleResult, nodes: [] });
+    if (buckets.fail.length) results.violations.push({ ...ruleResult, nodes: buckets.fail });
+    if (buckets.incomplete.length) results.incomplete.push({ ...ruleResult, nodes: buckets.incomplete });
+    if (passCount) results.passes.push({ ...ruleResult, nodes: [], nodeCount: passCount });
+
+    liveCounts[rule.impact] = (liveCounts[rule.impact] ?? 0) + buckets.fail.length;
+    liveCounts.review += buckets.incomplete.length;
+    if (buckets.fail.length) liveTypeCounts[rule.impact] = (liveTypeCounts[rule.impact] ?? 0) + 1;
+    if (buckets.incomplete.length) liveTypeCounts.review += 1;
+    const ms = Math.round((performance.now() - ruleStarted) * 10) / 10;
+    results.ruleTimings.push({ rule: rule.id, ms, elements: elements.length });
+    onProgress?.({
+      done: ++completed,
+      total: activeRules.length,
+      rule: rule.id,
+      ms,
+      counts: { ...liveCounts },
+      typeCounts: { ...liveTypeCounts },
+    });
+  }
+
+  results.durationMs = Math.round(performance.now() - auditStarted);
+  return results;
+}