@surea11y/core 1.0.0

package/docs/OUTPUT_SCHEMA.md

@@ -0,0 +1,237 @@
+# Output schema reference
+
+This is the exact shape of the object returned by `runDomRulesInPage(...)` / `runa11yCoreInPage(...)` (see [`INTEGRATION.md`](./INTEGRATION.md) for which one to call). Every example on this page is real output from the current engine (`schemaVersion: "1.0.0"`), not hand-written. `runa11yCoreAcrossFrames` returns a different, recursive shape wrapping this one — see [Cross-frame result](#cross-frame-result-runa11ycoreacrossframes) below.
+
+- [Top-level result](#top-level-result)
+- [Cross-frame result (`runa11yCoreAcrossFrames`)](#cross-frame-result-runa11ycoreacrossframes)
+- [A check result (`checksResults[i]`)](#a-check-result-checksresultsi)
+- [An occurrence (`occurrences[i]`)](#an-occurrence-occurrencesi)
+- [A composite result (`rulesResults[i]`)](#a-composite-result-rulesresultsi)
+- [Outcome values](#outcome-values)
+- [Severity and confidence values](#severity-and-confidence-values)
+- [Worked example](#worked-example)
+
+## Top-level result
+
+```ts
+{
+  engine: { tag: string, schemaVersion: string },
+  url: string | null,
+  title: string | null,
+  timestamp: string | null,
+  perfStats: object | null,
+  contextSelector: string | string[] | null,
+  checksResults: CheckResult[],
+  rulesResults: CompositeResult[],
+  overriddenBuiltinIds: string[]
+}
+```
+
+| Field | Meaning |
+|---|---|
+| `engine.tag` | The engine's own identity tag, currently `"a11ycore"`. Every rule (built-in or custom) carries it in `meta.tags` — rule `ruleId`s themselves are bare (no prefix). |
+| `engine.schemaVersion` | The result-schema version (`"1.0.0"`). Bump-worthy if this document's shape ever changes incompatibly — pin to it if you're parsing output programmatically. |
+| `url` | The `pageUrl` argument you passed in, or `document.location.href` if you passed `null`/omitted it, or `null` if neither is available. |
+| `title` | `document.title` at scan time, or `null`. |
+| `timestamp` | **Not auto-generated.** Only set if you pass `engineOptions.timestamp` as a non-empty string — the engine has no built-in clock (deterministic-by-design). If you want a scan timestamp in the result, supply it yourself. |
+| `perfStats` | `null` unless `engineOptions.perfStats: true`. Internal timing/counters — shape not covered by this document, treat as debug-only. |
+| `contextSelector` | The (trimmed) `contextSelector` argument you passed — a string, an array of strings (multi-region scanning, see [`ENGINE_OPTIONS.md`](./ENGINE_OPTIONS.md)), or `null` if none/empty. |
+| `checksResults` | One entry per **atomic rule** that ran (every rule not filtered out by `runOnly` — see [`ENGINE_OPTIONS.md`](./ENGINE_OPTIONS.md)). **Every loaded rule produces an entry, even ones that outcome `notApplicable`** — this is not a "violations only" list. |
+| `rulesResults` | One entry per **composite (WCAG-SC rollup) rule** that ran — see [Composite result](#a-composite-result-rulesresultsi) and [`WCAG_CONFORMANCE.md`](./WCAG_CONFORMANCE.md). Empty array if no composite matched the current `runOnly`/tag filter. |
+| `overriddenBuiltinIds` | Rule ids where an `engineOptions.customRules` entry shared its `id` with a built-in rule, so the custom implementation replaced the built-in one for this scan (see [`ENGINE_OPTIONS.md`](./ENGINE_OPTIONS.md)). Always an array; empty when no collision occurred. Also logged via `console.warn` at scan time, since a same-named custom rule is as likely to be an accidental collision as a deliberate override. |
+
+## Cross-frame result (`runa11yCoreAcrossFrames`)
+
+`runa11yCoreAcrossFrames` (see [`INTEGRATION.md`](./INTEGRATION.md#cross-frame-scanning-including-cross-origin)) returns a different, recursive shape instead of a plain top-level result:
+
+```ts
+{
+  topFrame: <the normal top-level result shape above>,
+  frames: Array<
+    | { url: string | null, topFrame: <top-level result>, frames: [...same shape, recursively] }
+    | { url: string | null, error: string }
+  >
+}
+```
+
+- `topFrame` is exactly the [top-level result](#top-level-result) shape, for the frame the function was called in.
+- `frames` has one entry per direct child `<iframe>`/`<frame>` in the scanned scope. A reachable child (one that called `a11yCoreEnableFrameResponder()`) contributes its own complete `{ url, topFrame, frames }` — including *its own* nested `frames`, recursively, since a further-nested grandchild is only reachable through its immediate parent. An unreachable child (the common case for most third-party embeds — no cooperating responder, or it timed out) contributes `{ url, error }` instead, and does not abort the rest of the scan.
+- This is a **tree, not a flat list** — a deliberate difference from the `surea11y-playwright` binding's `.frames(true)`, which *can* flatten because Playwright's `page.frames()` already gives every frame regardless of nesting depth; a `postMessage` relay has no such global view, so nesting is expressed structurally instead.
+
+## A check result (`checksResults[i]`)
+
+```ts
+{
+  ruleId: string,
+  outcome: "pass" | "fail" | "cantTell" | "notApplicable",
+  outcomeNormalized: "pass" | "fail" | "cantTell" | "inapplicable",
+  severity: "minor" | "moderate" | "serious" | "critical",
+  confidence: "high" | "medium" | "low",
+  type: "automatic" | "manual",
+  occurrences: Occurrence[],
+  title: string,
+  description: string,
+  i18n: { titleKey: string, descriptionKey: string } | null,
+  meta: {
+    ruleId: string,
+    ruleInterfaceVersion: string,
+    ruleVersion: string,
+    normative: boolean,
+    atomic: boolean,
+    category: "perceivable" | "operable" | "understandable" | "robust" | null,
+    normativeMappings: Array<{ standard: string, version: string, requirement: string, title: string, conformanceLevel: string }>,
+    standard: string | null,
+    applicability: string,
+    expectation: string,
+    references: string[],
+    requirements: object | null,
+    mappings: object | null
+  },
+  engineOptions: object,   // the resolved engineOptions this rule actually ran under
+  schemaVersion: string,
+  error?: string           // present only if the rule threw — see below
+}
+```
+
+Notes:
+
+- **`outcome` vs `outcomeNormalized`**: identical except `notApplicable` becomes `"inapplicable"` in `outcomeNormalized`. Both are provided so you can match either your own vocabulary or the engine's internal one.
+- **`type: "manual"` rules can never report `outcome: "fail"`.** If a manual rule's own logic would have said `fail`, the engine coerces it to `cantTell` and appends an explanatory note to `error` — this is enforced centrally (`policy.coerceManualFailToCantTell`, on by default under the `a11y` policy contract; see [`POLICY.md`](./POLICY.md)), not something each rule has to remember. `fail` is reserved for deterministic, high-confidence, `type: "automatic"` findings only.
+- **`meta.normativeMappings`** is how a check result ties back to a WCAG Success Criterion — `[]` for rules with no formal WCAG mapping (other engines call these "Best Practices"; this engine calls them advisory `type: "manual"` rules). See [`WCAG_CONFORMANCE.md`](./WCAG_CONFORMANCE.md) for how these roll up.
+- **`error`**: only present if the rule implementation threw an uncaught exception, or if the manual-fail coercion above fired. A thrown rule always surfaces as `outcome: "cantTell"` with `occurrences: []` and `error` set to the exception message — the engine never lets one broken rule crash the whole scan.
+- **`engineOptions`** on each result is the *resolved* options object (after locale/contrast defaults were applied), not literally what you passed in — useful for confirming what a given rule actually saw, especially the resolved `locale` and `contrast.mode`/`contrast.rootCanvasFallback`.
+
+## An occurrence (`occurrences[i]`)
+
+Only present when `outcome` is `fail` or `cantTell` (a `pass`/`notApplicable` result has `occurrences: []` — this engine does not enumerate the elements it passed, only the ones it flagged; see the note in `docs/RULE_AUTHORING.md` on why "silence" from a `pass` rule is not the same as an enumerated list of passing elements).
+
+```ts
+{
+  selector: string,
+  html: string,
+  structuralPath: number[] | null,
+  summary: string,
+  hint: string,
+  i18n: { summaryKey: string, hintKey: string, params: object } | null,
+  data: {
+    visibilityFilter?: { targetSet: string, accEligible: boolean | null, reasons: string[] },
+    details?: object   // rule-specific, non-normative — see below
+  }
+}
+```
+
+| Field | Meaning |
+|---|---|
+| `selector` | A best-effort CSS selector built to resolve back to the flagged element (see `helpers.buildSelector` in `RULE_AUTHORING.md`). Not guaranteed unique in adversarial DOM shapes, but the engine actively verifies it resolves to the reported element before using it. |
+| `html` | An outer-HTML snippet of the flagged element — use this as your primary "which element" signal when `includeShadowDom: true` (selectors don't pierce shadow boundaries). |
+| `structuralPath` | The flagged element's sibling-index path from `documentElement` down to it (e.g. `[1, 0, 2]`) — `[]` if the element *is* `documentElement`, `null` if it couldn't be determined. A more robust element-identity mechanism than `selector` alone: it survives DOM changes a selector string wouldn't (an id/class rename, for instance), at the cost of not being usable as an actual CSS selector. Computed from the element reference when the rule kept one, otherwise by re-resolving `selector` against the document (same caveat as `selector` itself: a non-unique selector could resolve to a different element than intended). |
+| `summary` | Human-readable, already localized ("This button has no accessible name."). |
+| `hint` | Human-readable remediation guidance, already localized. |
+| `i18n` | The raw translation keys behind `summary`/`hint`, if you want to re-render them in a different locale yourself without re-running the scan. `null` if the occurrence didn't use key-based i18n. |
+| `data.visibilityFilter` | Present on most occurrences: why the engine considered this element eligible for accessibility-tree evaluation (or not). `reasons` is a list of machine-readable exclusion codes when `accEligible: false`. |
+| `data.details` | Rule-specific structured data (e.g. `reasonCode`, computed metrics, resolved references) — **non-normative**: useful for building richer UI or debugging, but never changes what `outcome`/`severity` mean. Shape varies per rule; treat as best-effort extra context, not a stable contract. |
+
+## A composite result (`rulesResults[i]`)
+
+Composites roll multiple atomic rules up to one WCAG Success Criterion (e.g. `wcag-1.1.1-non-text-content` rolls up 22 atomic rules). Shape is the same envelope as a check result, with composite-specific `data.details`:
+
+```ts
+{
+  ruleId: string,              // e.g. "wcag-1.1.1-non-text-content"
+  outcome: "pass" | "fail" | "cantTell" | "notApplicable",
+  severity, confidence, type, title, description, meta, engineOptions, schemaVersion,  // same as a check result
+  occurrences: [],              // always empty — composites are rollups, not element-level findings
+  data: {
+    details: {
+      reasonCode: string,       // e.g. "composite.rollup.fail.anyFail"
+      checksIds: string[],      // every atomic ruleId this composite rolls up
+      contributors: Array<{ testId: string, outcome: string, severity: string | null }>,
+      metrics: { failCount, cantTellCount, notApplicableCount, passCount, missingCount }
+    }
+  }
+}
+```
+
+Rollup precedence (deterministic, in this order): **any contributor `fail` → composite `fail`**; else **any `cantTell` (or a contributor rule that didn't run at all, `missingCount > 0`) → composite `cantTell`**; else **all contributors `notApplicable` → composite `notApplicable`**; else **`pass`**. See [`WCAG_CONFORMANCE.md`](./WCAG_CONFORMANCE.md) for what this means for an overall conformance claim.
+
+## Outcome values
+
+| Outcome | Meaning | Can appear on `type: "manual"`? |
+|---|---|---|
+| `fail` | Deterministic, high-confidence, normative violation — no heuristics, no guessing. | No (coerced to `cantTell`) |
+| `pass` | The rule's applicable target(s) exist and none were flagged. | Yes |
+| `cantTell` | Requires human judgment — either genuinely ambiguous, or a `manual` rule's advisory finding. | Yes |
+| `notApplicable` | The rule found no elements it applies to on this page/scope. | Yes |
+
+`fail` is intentionally the narrowest, highest-bar outcome in this engine: reserved for deterministic, normative violations; chasing rule coverage must never dilute this.
+
+## Severity and confidence values
+
+- `severity`: `minor` < `moderate` < `serious` < `critical` — the rule author's assessment of user impact, independent of `confidence`.
+- `confidence`: `low` < `medium` < `high` — how certain the engine is that a `fail`/`cantTell` verdict is correct. Both are informational metadata for prioritization; neither changes `outcome`'s meaning.
+
+## Worked example
+
+Scanning `<img src="logo.png">` (no `alt`) and `<button></button>` (no accessible name), scoped to just those two rules via `runOnly: { includeRuleIds: [...] }` (see [`ENGINE_OPTIONS.md`](./ENGINE_OPTIONS.md) — this is **not** a bare array):
+
+```js
+const result = runDomRulesInPage(
+  'https://example.test/',
+  null,
+  {},
+  { includeRuleIds: ['img-alt-present', 'button-name-present'] }
+);
+```
+
+```json
+{
+  "engine": { "tag": "a11ycore", "schemaVersion": "1.0.0" },
+  "url": "https://example.test/",
+  "title": "Example",
+  "timestamp": null,
+  "perfStats": null,
+  "contextSelector": null,
+  "checksResults": [
+    {
+      "ruleId": "button-name-present",
+      "outcome": "fail",
+      "severity": "serious",
+      "confidence": "high",
+      "type": "automatic",
+      "occurrences": [
+        {
+          "selector": "html > body > button",
+          "html": "<button></button>",
+          "structuralPath": [1, 0],
+          "summary": "This button has no accessible name.",
+          "hint": "Provide visible button text or a programmatic accessible-name mechanism (for example aria-label) so assistive technologies can identify the button.",
+          "data": {
+            "visibilityFilter": { "eligible": true, "reasons": [], "targetSet": "acc", "accEligible": true },
+            "details": { "reasonCode": "name_missing" }
+          }
+        }
+      ]
+    },
+    {
+      "ruleId": "img-alt-present",
+      "outcome": "fail",
+      "severity": "serious",
+      "confidence": "high",
+      "type": "automatic",
+      "occurrences": [
+        {
+          "selector": "html > body > img",
+          "html": "<img src=\"logo.png\">",
+          "structuralPath": [1, 1],
+          "summary": "Missing alt attribute on <img>.",
+          "hint": "Add an alt attribute (use alt=\"\" only for decorative images)."
+        }
+      ]
+    }
+  ],
+  "rulesResults": [],
+  "overriddenBuiltinIds": []
+}
+```
+
+(Trimmed for readability — the real result also includes `title`/`description`/`i18n`/`meta`/`engineOptions`/`schemaVersion` on every entry, per the full shape above. `rulesResults` is empty here because `runOnly.includeRuleIds` scoped the scan to two atomic rules and no composite's own ID was included.)

package/docs/POLICY.md

@@ -0,0 +1,71 @@
+# Policy & contracts guide
+
+A policy controls two things, independent of any individual rule's logic: **which outcome/confidence values are allowed to reach the result at all**, and **whether a `manual` rule's would-be `fail` gets coerced to `cantTell`**. It never changes what a rule decides — only how that decision is allowed to be represented.
+
+## The two built-in contracts
+
+```js
+{
+  a11y: {
+    id: 'a11y',
+    allowedOutcomes: ['fail', 'pass', 'cantTell', 'notApplicable'],
+    allowedConfidence: ['high', 'medium', 'low'],
+    coerceManualFailToCantTell: true   // ← the only difference
+  },
+  generic: {
+    id: 'generic',
+    allowedOutcomes: ['fail', 'pass', 'cantTell', 'notApplicable'],
+    allowedConfidence: ['high', 'medium', 'low'],
+    coerceManualFailToCantTell: false
+  }
+}
+```
+
+(Source of truth: `src/policy/contracts.js`.)
+
+- **`a11y`** (the default): enforces the engine's core non-negotiable — a `type: 'manual'` rule (advisory/judgment-required, see [`RULE_CATALOG.md`](./RULE_CATALOG.md)) can never produce a `fail`. If a manual rule's own logic decides `fail`, the policy coerces it to `cantTell` and appends a note to the result's `error` field. Use this contract for anything where a `fail` result carries weight — CI gating, compliance reporting, anywhere someone might treat `fail` as "definitely broken."
+- **`generic`**: identical outcome/confidence vocabulary, but does **not** coerce manual `fail`s. Only meaningful if you've deliberately reconfigured a manual rule to be more assertive than its default and want that respected — not a general-purpose "looser" mode.
+
+## Selecting a contract
+
+```js
+runDomRulesInPage(url, null, { policyContract: 'a11y' }, null);   // default if omitted
+runDomRulesInPage(url, null, { policyContract: 'generic' }, null);
+```
+
+Or supply an inline contract object instead of a name:
+
+```js
+runDomRulesInPage(url, null, {
+  policyContract: {
+    id: 'my-custom-policy',
+    allowedOutcomes: ['fail', 'pass', 'cantTell', 'notApplicable'],
+    allowedConfidence: ['high', 'medium'],   // drop 'low' — anything low-confidence becomes cantTell
+    coerceManualFailToCantTell: true
+  }
+}, null);
+```
+
+Any field you omit from an inline contract object falls back to the `a11y` contract's value for that field — you're overriding, not replacing wholesale.
+
+## Fine-grained overrides
+
+`engineOptions.policy` overrides individual fields on top of whichever contract you selected, without defining a whole new contract:
+
+```js
+runDomRulesInPage(url, null, {
+  policyContract: 'a11y',
+  policy: { coerceManualFailToCantTell: false }   // keep everything else about 'a11y', just flip this one flag
+}, null);
+```
+
+## What happens when a value isn't allowed
+
+- **`outcome` not in `allowedOutcomes`**: silently coerced to `cantTell`. (In practice this only matters for custom contracts that narrow the outcome list — the two built-in contracts allow all four values.)
+- **`confidence` not in `allowedConfidence`**: silently replaced with the rule's own `defaultConfidence`.
+
+Neither of these ever throws — policy resolution is designed to always produce a valid result, per the engine's "safe-by-default" principle.
+
+## Why this exists as a separate layer
+
+Keeping outcome-integrity rules (like "manual rules can't fail") in a policy layer — rather than hard-coded into every rule, or worse, left to each rule author's discretion — means the guarantee holds even if a rule's own logic has a bug, and means different consumers can have different appetites for risk (a CI gate vs. an internal audit dashboard) without forking the rule set itself. This protects the engine's core guarantee: `fail` must always mean "deterministic, high-confidence, normative violation," full stop.

package/docs/RULE_AUTHORING.md

@@ -0,0 +1,375 @@
+# RULE_AUTHORING.md — a11yCore DOM Rule Authoring (Canonical, repo-derived)
+
+This guide is derived from the **actual rule modules, helpers, build pipeline, and tests** in this codebase.
+Follow it literally when adding or modifying rules.
+
+> Key principle: **Atomic + deterministic + standards-traceable**.
+> One rule = one normative decision.
+
+---
+
+## 1) Where rules run (critical mental model)
+
+Rules are bundled into the generated core and executed inside the **page/DOM context**.
+
+- `runInPage(ctx)` is **serialized** and evaluated later from its source text.
+- Therefore it must be **self-contained** (no outer-scope references).
+
+### 1.1 Forbidden inside `runInPage`
+❌ Don’t reference anything defined outside the function body, including:
+- `id`
+- `meta`
+- imported modules
+- closure variables
+
+This is a known, **recurring** footgun (“meta is not defined” incident).
+
+⚠️ **Why this is dangerous, not just annoying: the build does NOT fail.** `runInPage` is serialized via `fn.toString()` and re-evaluated as source text later, in the page context — `build-core.js` never parses that source for free variables, and `npm run build`/`npm test`'s own tests only verify serialization round-trips correctly, not that every identifier resolves. The break only surfaces when the rule actually *runs*: the reference throws a `ReferenceError` inside `runInPage`, the runner's own `try/catch` (`src/core/dom-runner.js`) catches it silently, and the rule's result becomes `{ outcome: 'cantTell', occurrences: [], error: '<name> is not defined' }` — a normal-looking result, not a crash. A rule broken this way can sit unnoticed indefinitely unless something specifically asserts its `outcome`/`error`, which is why every rule's fixture-coverage test (§11) matters: it's often the *only* thing that would catch this.
+
+**If you add a module-scope `const`/helper function to a rule file, move it inside `runInPage` itself** (or route the value through `ctx.rule`/`ctx.helpers` if it must be engine-provided) — do not leave it at module scope and reference it from inside `runInPage`, even though nothing will complain until you actually run the rule and check its `error` field.
+
+✅ Use `ctx.rule.*` instead:
+- `ctx.rule.ruleId`
+- `ctx.rule.defaultSeverity`
+- `ctx.rule.defaultConfidence`
+- `ctx.rule.type`
+
+---
+
+## 2) Rule module contract (exact)
+
+Each rule file is a CommonJS module exporting exactly:
+
+```js
+'use strict';
+
+const id = 'some-rule-id';
+
+const meta = { /* see Meta Contract */ };
+
+function runInPage(ctx) { /* see Runtime Contract */ }
+
+module.exports = { id, meta, runInPage };
+```
+
+No other exports.
+
+---
+
+## 3) Rule ID conventions (repo reality)
+
+IDs are kebab-case, bare (no engine prefix).
+
+Common pattern used in this ruleset:
+```
+<target>-<topic>-<intent>
+```
+
+Examples observed:
+- `img-alt-present`
+- `img-alt-quality`
+- `img-alt-decorative`
+- `canvas-text-alternative-present`
+- `video-poster-text-alternative-present`
+
+**Manual vs automatic is NOT encoded in the id** in this repo; it is encoded by `meta.type`.
+
+---
+
+## 4) Meta Contract (all keys used by current rules)
+
+Every rule defines a `meta` object. In the rule set you uploaded, the union of meta keys is:
+
+### 4.1 Required top-level keys
+
+```js
+const meta = {
+  title: '…',
+  description: '…',
+
+  i18n: {
+    titleKey: '…',
+    descriptionKey: '…'
+  },
+
+  helpUrl: null, // or URL string
+
+  tags: [ '…' ],
+  wcagSc: [ '1.1.1' ],
+
+  normativeMappings: [
+    {
+      standard: 'WCAG',
+      version: '2.2',
+      requirement: '1.1.1',
+      title: 'Non-text Content',
+      conformanceLevel: 'A'
+    }
+  ],
+
+  defaultSeverity: 'minor' | 'moderate' | 'serious' | 'critical',
+  category: 'perceivable' | 'operable' | 'understandable' | 'robust',
+  type: 'automatic' | 'manual',
+  defaultConfidence: 'high' | 'medium' | 'low',
+
+  coverage: {
+    facetsBySc: {
+      '1.1.1': ['facet-a', 'facet-b']
+    }
+  }
+};
+```
+
+### 4.2 Notes on specific meta keys
+
+#### `meta.i18n`
+This repo uses **key-based i18n**:
+- `titleKey`, `descriptionKey` are dictionary keys.
+- `title` and `description` remain as **English fallbacks**.
+
+The build/runtime resolves i18n by:
+1) looking up the requested locale dictionary,
+2) falling back to `en` if missing,
+3) falling back to the literal `title`/`description` strings if still missing.
+
+#### `meta.tags`
+Tags are used for grouping/filtering. Typical tag families in this ruleset include:
+- WCAG tagging: `wcag2a`, `wcag111`
+- domain: `nontext`, `images`, plus element-specific tags
+- nature: `atomic`, plus `automatic` or `manual`
+
+#### `meta.coverage.facetsBySc`
+This is the repo’s explicit **coverage model** for an SC.
+Each atomic rule declares which “facet(s)” of an SC it covers.
+
+Keep facet naming consistent across a family.
+
+---
+
+## 5) i18n in occurrences (repo reality)
+
+Occurrences also support i18n via keys + params.
+
+### 5.1 Occurrence i18n shape
+
+Every occurrence may include:
+
+```js
+i18n: {
+  summaryKey: '…',
+  hintKey: '…',
+  params: { /* string substitutions */ }
+}
+```
+
+At normalization time, the engine:
+- ensures `summary`, `hint`, and `html` are strings,
+- ensures `i18n` is either a normalized object or `null`,
+- resolves `summary` and `hint` using i18n keys (with locale → `en` fallback → literal fallback).
+
+### 5.2 Param interpolation
+
+Translation strings use `{{paramName}}` placeholders.
+`params` is shallow-copied and passed into interpolation.
+
+---
+
+## 6) Helpers contract used by rules (ctx.helpers)
+
+Rules use helpers returned by `createDomHelpers()`.
+
+Helpers observed in this repo include:
+- `queryAll`, `queryAllDeep`, `queryAllSmart`
+- `getOuterHtmlSnippet`
+- `buildSimpleSelector`, `buildSelector`
+- `isAccTreeEligible`, `getEligibilityInfo`
+- `resolveIdRefs`, `getTextFromIdRefs`
+- `getAccessibleNameInfo`, `getAccessibleDescriptionInfo`
+- `getTextAlternativeInfo`
+- `getRoleInfo`, `getFocusableInfo`
+
+### 6.1 Shadow DOM scanning
+
+Rules that need to work with open Shadow DOM should prefer:
+
+```js
+const nodes = helpers.queryAllSmart
+  ? helpers.queryAllSmart('img')
+  : helpers.queryAll('img');
+```
+
+Shadow traversal is opt-in via engine option:
+```js
+engineOptions: { includeShadowDom: true }
+```
+
+### 6.2 Reporting note for Shadow DOM
+
+Selectors do not pierce shadow boundaries, so a `selector` may not uniquely locate nodes in Shadow DOM.
+Therefore: **always include `html` in occurrences**.
+
+---
+
+## 7) Eligibility logging (required in this ruleset)
+
+This repo requires rules to attach an eligibility/visibility trace in each occurrence:
+
+```js
+data: {
+  visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] }
+}
+```
+
+This is consistent across your uploaded rule family.
+
+---
+
+## 8) `runInPage(ctx)` runtime contract (repo reality)
+
+### 8.1 Expected return shape
+
+The rule must return:
+- `ruleId` (must be `rule.ruleId`)
+- `outcome`: `"pass" | "fail" | "cantTell" | "notApplicable"`
+- `severity`: string
+- `occurrences`: array
+
+Examples:
+
+### 8.2 Outcome conventions used by these rules
+
+Automatic:
+- `notApplicable` if no applicable targets
+- `pass` if applicable targets exist and no occurrences
+- `fail` if occurrences exist
+
+Manual:
+- `notApplicable` if no applicable targets
+- `cantTell` if at least one target requires review
+
+---
+
+## 9) Occurrence object shape (repo reality)
+
+Typical pattern:
+
+```js
+occurrences.push({
+  selector,
+  html,
+  summary: '…',
+  hint: '…',
+  i18n: { summaryKey: '…', hintKey: '…', params: { element: 'img' } },
+  data: { visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] } }
+});
+```
+
+Observed properties:
+- `selector` (or sometimes `selectorStr`)
+- `html`
+- `summary`
+- `hint`
+- `i18n` (`summaryKey`, `hintKey`, `params`)
+- `data` (includes `visibilityFilter`)
+
+---
+
+## 10) Structured doc comment block
+
+Keep the structured header comment (`@rule`, `@atomic`, `@summary`, `@standard`, `@sc`, `@applicability`, `@expectation`).
+
+---
+
+## 11) Scenario fixture + fixture-coverage test (required for every rule)
+
+Every rule — automatic or manual, no exceptions — needs a standalone, loadable HTML
+scenario page in addition to its inline unit tests. This is not optional polish: the
+project's test fixtures are meant to be usable directly by external tooling (loaded and
+exercised as real pages), not just embedded as strings inside `.test.js` files.
+
+### 11.1 The fixture file
+
+- Path: `tests/fixtures/<rule-slug>-all-scenarios.html`, where `<rule-slug>` is the rule
+  id itself (e.g. `tab-name-present` → `tab-name-present-all-scenarios.html`).
+- Structure: a real HTML page (`<!doctype html>`, `<title>`, minimal inline `<style>`)
+  containing numbered scenario blocks, each:
+  ```html
+  <div class="case" id="case_NN">
+    <div class="case-title">NN — PASS: role=tab, visible text content</div>
+    <div role="tab" tabindex="0" id="<slug>_case_NN">Apple</div>
+  </div>
+  ```
+  - The `.case-title` text MUST start with `NN — MARKER:` where `MARKER` is one of
+    `PASS`, `FAIL`, `CANTTELL`, or `NEUTRAL`/`INELIGIBLE` (the fixture-index generator,
+    §11.3, parses this to count scenarios per outcome — see
+    `scripts/generate-fixture-index.js`'s `parseFixtureCases`).
+  - The actual test target gets its own stable id of the form `<slug>_case_NN` (short,
+    memorable abbreviation of the rule name — see existing fixtures for precedent, e.g.
+    `tab_case_01`, `binctl_case_01`).
+  - Group related cases under `<h2>` sections (e.g. "A. Named (eligible)", "B. Unnamed
+    (eligible, FAIL)", "C. Ineligible (excluded from accessibility tree, skipped)").
+- Cover every branch the rule's own logic distinguishes: pass, fail (each distinct
+  `reasonCode`), notApplicable/skipped, and — for manual rules — cantTell.
+
+### 11.2 Known, acceptable exceptions to "one fixture, many cases"
+
+A few rule shapes genuinely cannot express every branch as a single static page. When
+you hit one of these, still create the fixture (covering whatever branches ARE
+expressible statically) and add an explicit `<p class="note">` in the fixture, plus a
+comment in the `.test.js` fixture-coverage test, stating which branch is NOT covered and
+why:
+
+- **Whole-document checks** (e.g. `aria-hidden-body`, `page-title-present`,
+  `meta-viewport-zoom-enabled`, `bypass-blocks-present`): the property being checked
+  exists once per page (one `<body>`, one `<title>`, one viewport meta), so only one
+  outcome is demonstrable per fixture file. Pick the most illustrative FAIL case; note
+  that PASS/other branches are covered by the rule's inline unit tests instead of
+  minting near-duplicate fixture files.
+- **Runtime-mutation-only branches** (e.g. `iframe-focusable-content`'s FAIL branch,
+  which requires mutating `iframe.contentDocument` after parse — jsdom does not
+  populate `srcdoc` synchronously): cover every branch that IS expressible statically;
+  leave the rest to the existing programmatic test.
+- **Rules with no branching logic at all** (e.g. `manual-review`, which always returns
+  `cantTell` regardless of page content): a single trivial case is fine, purely for
+  index completeness — say so in the fixture's note.
+
+Do not force a false "PASS" demonstration or fabricate a scenario that doesn't actually
+exercise the code path it claims to.
+
+### 11.3 The fixture-coverage test
+
+Add one test to the rule's existing `tests/engine-checks/**/<rule>.test.js` (do not
+create a separate file):
+
+```js
+const fs = require('node:fs');
+const path = require('node:path');
+
+test(`${RULE_ID}: fixture coverage (tests/fixtures/<rule-slug>-all-scenarios.html)`, () => {
+  const fixturePath = path.join(__dirname, '../..', 'fixtures', '<rule-slug>-all-scenarios.html');
+  const fixtureHtml = fs.readFileSync(fixturePath, 'utf8');
+  const result = runa11yCoreOnHtml(fixtureHtml, { runOnly: [RULE_ID] });
+
+  const rule = assertRule(result, RULE_ID, 'fail', { minOccurrences: N, maxOccurrences: N });
+  // assert the exact expected-fail ids (and, if useful, expected-no-occurrence ids)
+});
+```
+
+The file MUST declare `const RULE_ID = '...'` near the top (the fixture-index
+generator discovers a rule's test file and fixture by scanning for that constant —
+tests using only inline string literals won't be picked up; see
+`tests/engine-checks/manual-review.test.js` for the fix applied when this was missed).
+
+### 11.4 Keeping the index current
+
+After adding or changing any fixture, regenerate the index:
+
+```
+npm run fixtures:index
+```
+
+This writes `tests/fixtures/INDEX.md` (human-readable) and `tests/fixtures/index.json`
+(machine-readable — every rule, its fixture path, and parsed pass/fail/cantTell case
+counts, for external tooling to enumerate and load fixtures directly). Commit both
+alongside the fixture and test changes. A rule shipped without its fixture is treated
+the same as a rule shipped without tests — not done.