@a11y-oracle/axe-bridge 1.0.0

package/README.md

@@ -0,0 +1,254 @@
+# @a11y-oracle/axe-bridge
+
+Axe-core result post-processor that resolves "incomplete" (Needs Review) findings using visual analysis, keyboard interaction, and CDP inspection. Drop-in middleware between axe-core's `analyze()` and your assertion layer.
+
+## The Problem
+
+axe-core marks rules as "incomplete" when they require state changes, interaction, or spatial awareness that static DOM analysis cannot reliably perform. This creates noise in CI dashboards and requires manual review for rules like color contrast, focus indicators, target sizes, and more.
+
+## The Solution
+
+`resolveAllIncomplete()` takes axe-core results and a live CDP session, then pipes them through 10 specialized resolvers that promote findings from `incomplete` to `passes` or `violations`:
+
+| # | Rule ID | WCAG SC | Technique |
+|---|---------|---------|-----------|
+| 1 | `color-contrast` | 1.4.3 | CSS halo heuristic + pixel-level screenshot analysis |
+| 2 | `identical-links-same-purpose` | 2.4.4 | URL normalization and comparison |
+| 3 | `link-in-text-block` | 1.4.1 | Default-state computed style checks |
+| 4 | `target-size` | 2.5.8 | Bounding box measurements + spacing |
+| 5 | `scrollable-region-focusable` | 2.1.1 | Scroll height + focusable child traversal |
+| 6 | `skip-link` | 2.4.1 | Tab-focus visibility verification |
+| 7 | `aria-hidden-focus` | 4.1.2 | Full keyboard Tab traversal |
+| 8 | `focus-indicator` | 2.4.7 | Before/after screenshot pixel diff |
+| 9 | `content-on-hover` | 1.4.13 | Hover + dismiss interaction tests |
+| 10 | `frame-tested` | N/A | Cross-origin iframe axe-core injection |
+
+## Installation
+
+```bash
+npm install @a11y-oracle/axe-bridge
+```
+
+## Usage
+
+### Resolve All Incompletes (Recommended)
+
+```typescript
+import { resolveAllIncomplete } from '@a11y-oracle/axe-bridge';
+
+// After running axe-core while the page is still live:
+const axeResults = await axe.run(document);
+const resolved = await resolveAllIncomplete(cdpSession, axeResults);
+
+// resolved.incomplete will have fewer (or zero) entries
+// resolved.violations and resolved.passes will have the promoted entries
+```
+
+### With Options
+
+```typescript
+const resolved = await resolveAllIncomplete(cdpSession, axeResults, {
+  wcagLevel: 'wcag22aa',
+  contrast: { threshold: 4.5, largeTextThreshold: 3.0 },
+  focusIndicator: { focusSettleDelay: 150, diffThreshold: 0.2 },
+  skipRules: ['frame-tested'], // skip specific resolvers
+});
+```
+
+### Individual Resolvers
+
+Each resolver can be used standalone:
+
+```typescript
+import { resolveIncompleteContrast } from '@a11y-oracle/axe-bridge';
+
+const resolved = await resolveIncompleteContrast(cdpSession, axeResults, {
+  wcagLevel: 'wcag22aa',
+});
+```
+
+### With Playwright
+
+```typescript
+import { test, expect } from '@playwright/test';
+import { resolveAllIncomplete } from '@a11y-oracle/axe-bridge';
+
+test('no unresolved accessibility issues', async ({ page }) => {
+  await page.goto('/my-page.html');
+  const cdp = await page.context().newCDPSession(page);
+
+  const axeResults = await axe.run(document);
+  const resolved = await resolveAllIncomplete(cdp, axeResults);
+
+  expect(resolved.violations).toHaveLength(0);
+  expect(resolved.incomplete).toHaveLength(0);
+
+  await cdp.detach();
+});
+```
+
+### With Cypress
+
+```typescript
+// Using Cypress.automation for CDP access:
+cy.window().then(async (win) => {
+  const axeResults = await axeCore.run(win.document);
+
+  // cdpSession obtained via Cypress.automation('remote:debugger:protocol', ...)
+  const resolved = await resolveAllIncomplete(cdpSession, axeResults);
+
+  expect(resolved.violations).to.have.length(0);
+});
+```
+
+## API Reference
+
+### `resolveAllIncomplete(cdp, axeResults, options?)`
+
+Orchestrator that pipes results through all 10 resolvers in sequence. Each resolver receives the output of the previous one.
+
+- **Parameters:**
+  - `cdp: CDPSessionLike` — CDP session connected to the page
+  - `axeResults: AxeResults` — Raw results from axe-core's `analyze()`
+  - `options?: IncompleteResolutionOptions` — Per-resolver options and `skipRules` filter
+- **Returns:** `Promise<AxeResults>` — Modified copy with resolved findings
+- **Pipeline order:** color-contrast → identical-links-same-purpose → link-in-text-block → target-size → scrollable-region-focusable → skip-link → aria-hidden-focus → focus-indicator → content-on-hover → frame-tested
+
+### Individual Resolvers
+
+#### `resolveIncompleteContrast(cdp, axeResults, options?)`
+
+Resolves `color-contrast` incomplete entries using CSS halo heuristics and pixel-level screenshot analysis.
+
+- **Options:** `ContrastResolutionOptions` — `wcagLevel`, `threshold`, `largeTextThreshold`
+- Automatically detects large text from axe-core's check data (>= 24px or bold >= 18.66px)
+
+#### `resolveIdenticalLinksSamePurpose(cdp, axeResults)`
+
+Resolves `identical-links-same-purpose` by normalizing URLs (stripping query params, hashes, resolving relative paths) and comparing destinations.
+
+- Same destination → **Pass**, different → **Violation**
+
+#### `resolveLinkInTextBlock(cdp, axeResults, options?)`
+
+Resolves `link-in-text-block` by checking the **default/resting state** for non-color visual indicators.
+
+- **Options:** `LinkInTextBlockOptions` — `linkTextContrastThreshold` (default: 3.0)
+- Checks: `text-decoration: underline`, `border-bottom > 0`, `font-weight` difference from parent
+- If no non-color indicator: compares link vs surrounding text color contrast
+
+#### `resolveTargetSize(cdp, axeResults, options?)`
+
+Resolves `target-size` by measuring bounding boxes and center-to-center spacing.
+
+- **Options:** `TargetSizeOptions` — `minSize` (default: 24)
+- Width/height >= 24px → **Pass**; undersized with 24px+ spacing → **Pass**; otherwise → **Violation**
+
+#### `resolveScrollableRegionFocusable(cdp, axeResults, options?)`
+
+Resolves `scrollable-region-focusable` by checking scroll height, tabindex, and focusable children.
+
+- **Options:** `ScrollableRegionOptions` — `maxChildren` (default: 50)
+- Not actually scrollable → **Pass**; has `tabindex >= 0` → **Pass**; focusable children scroll to content → **Pass**
+
+#### `resolveSkipLink(cdp, axeResults, options?)`
+
+Resolves `skip-link` by focusing the skip link and verifying it becomes visible.
+
+- **Options:** `SkipLinkOptions` — `focusSettleDelay` (default: 100)
+- Checks bounding box, viewport containment, opacity, clip, position
+
+#### `resolveAriaHiddenFocus(cdp, axeResults, options?)`
+
+Resolves `aria-hidden-focus` via a single keyboard Tab traversal across all flagged nodes.
+
+- **Options:** `AriaHiddenFocusOptions` — `maxTabs` (default: 100)
+- Tab lands on flagged element → **Violation**; traversal completes without landing → **Pass**
+
+#### `resolveFocusIndicator(cdp, axeResults, options?)`
+
+Resolves `focus-indicator` by pixel-diffing before/after focus screenshots.
+
+- **Options:** `FocusIndicatorOptions` — `focusSettleDelay` (default: 100), `diffThreshold` (default: 0.1%)
+- Screenshots are identical → **Violation**; pixels changed → **Pass**
+
+#### `resolveContentOnHover(cdp, axeResults, options?)`
+
+Resolves `content-on-hover` with hover and dismiss interaction tests.
+
+- **Options:** `ContentOnHoverOptions` — `hoverDelay` (default: 300), `dismissDelay` (default: 200)
+- Tests: content appears on hover, remains when mouse moves to content (hoverable), disappears on Escape (dismissible)
+
+#### `resolveFrameTested(cdp, axeResults, options?)`
+
+Resolves `frame-tested` by injecting axe-core into cross-origin iframes via CDP.
+
+- **Options:** `FrameTestedOptions` — `axeSource` (complete axe-core script), `iframeTimeout` (default: 30000)
+- Uses `Page.createIsolatedWorld` to bypass same-origin restrictions
+
+### Pipeline Utilities
+
+Shared helpers used by all resolvers:
+
+```typescript
+import {
+  getSelector,        // Extract innermost CSS selector from axe node target
+  cloneResults,       // Deep-clone AxeResults without mutation
+  ruleShell,          // Create a rule shell (metadata only, no nodes)
+  findIncompleteRule,  // Find a rule by ID in the incomplete array
+  applyPromotions,    // Move nodes between incomplete/passes/violations
+} from '@a11y-oracle/axe-bridge';
+```
+
+### Types
+
+```typescript
+import type {
+  // Axe-core compatible types
+  AxeResults,
+  AxeRule,
+  AxeNode,
+  AxeCheck,
+
+  // WCAG level
+  WcagLevel,
+  ContrastThresholds,
+
+  // Per-resolver options
+  ContrastResolutionOptions,
+  LinkInTextBlockOptions,
+  TargetSizeOptions,
+  ScrollableRegionOptions,
+  SkipLinkOptions,
+  AriaHiddenFocusOptions,
+  FocusIndicatorOptions,
+  ContentOnHoverOptions,
+  FrameTestedOptions,
+
+  // Orchestrator options
+  IncompleteResolutionOptions,
+
+  // Pipeline utility types
+  PromotionResult,
+} from '@a11y-oracle/axe-bridge';
+```
+
+> **Note:** Axe-core types are locally defined for structural compatibility without requiring axe-core as a runtime dependency.
+
+## How It Works
+
+Each resolver follows a common pipeline pattern:
+
+1. **Clone** — Deep-clone the input results (original is never mutated)
+2. **Find** — Locate the target rule in the `incomplete` array
+3. **Analyze** — For each flagged node, run the resolver's specific technique (CDP queries, screenshots, keyboard traversal, etc.)
+4. **Promote** — Move resolved nodes to `passes` or `violations`; unresolved nodes stay in `incomplete`
+
+The `resolveAllIncomplete` orchestrator chains all resolvers in sequence, so findings accumulate through the pipeline.
+
+## Dependencies
+
+- **`@a11y-oracle/visual-engine`** — Visual analysis engine (halo detection, pixel analysis, PNG decoding, CDP capture)
+- **`@a11y-oracle/focus-analyzer`** — Color parsing and contrast ratio computation
+- **`@a11y-oracle/keyboard-engine`** — Native CDP keyboard dispatch for skip-link, aria-hidden-focus, and content-on-hover
+- **`@a11y-oracle/cdp-types`** — `CDPSessionLike` interface for framework-agnostic CDP access

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @module @a11y-oracle/axe-bridge
+ *
+ * Axe-core result post-processor that resolves "incomplete" rule
+ * findings using visual analysis, keyboard interaction, and CDP
+ * inspection. Drop-in middleware between axe-core's `analyze()`
+ * and your assertion layer.
+ *
+ * @packageDocumentation
+ */
+export { resolveAllIncomplete } from './lib/resolve-all.js';
+export { resolveIncompleteContrast } from './lib/axe-bridge.js';
+export { resolveIdenticalLinksSamePurpose, normalizeUrl } from './lib/resolvers/identical-links-same-purpose.js';
+export { resolveLinkInTextBlock } from './lib/resolvers/link-in-text-block.js';
+export { resolveTargetSize } from './lib/resolvers/target-size.js';
+export { resolveScrollableRegionFocusable } from './lib/resolvers/scrollable-region-focusable.js';
+export { resolveSkipLink } from './lib/resolvers/skip-link.js';
+export { resolveAriaHiddenFocus } from './lib/resolvers/aria-hidden-focus.js';
+export { resolveFocusIndicator } from './lib/resolvers/focus-indicator.js';
+export { resolveContentOnHover } from './lib/resolvers/content-on-hover.js';
+export { resolveFrameTested } from './lib/resolvers/frame-tested.js';
+export { getContrastThresholds } from './lib/wcag-thresholds.js';
+export { getSelector, cloneResults, ruleShell, findIncompleteRule, applyPromotions, } from './lib/resolver-pipeline.js';
+export type { PromotionResult } from './lib/resolver-pipeline.js';
+export type { ContrastResolutionOptions, ContrastThresholds, WcagLevel, AxeResults, AxeRule, AxeNode, AxeCheck, LinkInTextBlockOptions, TargetSizeOptions, ScrollableRegionOptions, SkipLinkOptions, AriaHiddenFocusOptions, FocusIndicatorOptions, ContentOnHoverOptions, FrameTestedOptions, IncompleteResolutionOptions, } from './lib/types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAG5D,OAAO,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AAChE,OAAO,EAAE,gCAAgC,EAAE,YAAY,EAAE,MAAM,iDAAiD,CAAC;AACjH,OAAO,EAAE,sBAAsB,EAAE,MAAM,uCAAuC,CAAC;AAC/E,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AACnE,OAAO,EAAE,gCAAgC,EAAE,MAAM,gDAAgD,CAAC;AAClG,OAAO,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAC/D,OAAO,EAAE,sBAAsB,EAAE,MAAM,sCAAsC,CAAC;AAC9E,OAAO,EAAE,qBAAqB,EAAE,MAAM,oCAAoC,CAAC;AAC3E,OAAO,EAAE,qBAAqB,EAAE,MAAM,qCAAqC,CAAC;AAC5E,OAAO,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AAGrE,OAAO,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAGjE,OAAO,EACL,WAAW,EACX,YAAY,EACZ,SAAS,EACT,kBAAkB,EAClB,eAAe,GAChB,MAAM,4BAA4B,CAAC;AACpC,YAAY,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAGlE,YAAY,EACV,yBAAyB,EACzB,kBAAkB,EAClB,SAAS,EACT,UAAU,EACV,OAAO,EACP,OAAO,EACP,QAAQ,EACR,sBAAsB,EACtB,iBAAiB,EACjB,uBAAuB,EACvB,eAAe,EACf,sBAAsB,EACtB,qBAAqB,EACrB,qBAAqB,EACrB,kBAAkB,EAClB,2BAA2B,GAC5B,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,27 @@
+/**
+ * @module @a11y-oracle/axe-bridge
+ *
+ * Axe-core result post-processor that resolves "incomplete" rule
+ * findings using visual analysis, keyboard interaction, and CDP
+ * inspection. Drop-in middleware between axe-core's `analyze()`
+ * and your assertion layer.
+ *
+ * @packageDocumentation
+ */
+// ─── Orchestrator ───────────────────────────────────────────────
+export { resolveAllIncomplete } from './lib/resolve-all.js';
+// ─── Individual resolvers ───────────────────────────────────────
+export { resolveIncompleteContrast } from './lib/axe-bridge.js';
+export { resolveIdenticalLinksSamePurpose, normalizeUrl } from './lib/resolvers/identical-links-same-purpose.js';
+export { resolveLinkInTextBlock } from './lib/resolvers/link-in-text-block.js';
+export { resolveTargetSize } from './lib/resolvers/target-size.js';
+export { resolveScrollableRegionFocusable } from './lib/resolvers/scrollable-region-focusable.js';
+export { resolveSkipLink } from './lib/resolvers/skip-link.js';
+export { resolveAriaHiddenFocus } from './lib/resolvers/aria-hidden-focus.js';
+export { resolveFocusIndicator } from './lib/resolvers/focus-indicator.js';
+export { resolveContentOnHover } from './lib/resolvers/content-on-hover.js';
+export { resolveFrameTested } from './lib/resolvers/frame-tested.js';
+// ─── Threshold helpers ──────────────────────────────────────────
+export { getContrastThresholds } from './lib/wcag-thresholds.js';
+// ─── Pipeline utilities ─────────────────────────────────────────
+export { getSelector, cloneResults, ruleShell, findIncompleteRule, applyPromotions, } from './lib/resolver-pipeline.js';

package/dist/lib/axe-bridge.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @module axe-bridge
+ *
+ * Post-processor for axe-core results that resolves "incomplete"
+ * color-contrast warnings using visual pixel analysis and CSS
+ * halo heuristics.
+ */
+import type { CDPSessionLike } from '@a11y-oracle/cdp-types';
+import type { AxeResults, ContrastResolutionOptions } from './types.js';
+/**
+ * Resolve incomplete color-contrast warnings from axe-core results
+ * using visual pixel analysis and CSS halo heuristics.
+ *
+ * The function deep-clones the input results and returns a modified
+ * copy where:
+ * - Elements that pass worst-case contrast are promoted to `passes`
+ * - Elements that fail best-case contrast are promoted to `violations`
+ * - Ambiguous elements (split decision, dynamic content) remain in `incomplete`
+ *
+ * @param cdp - CDP session connected to the page being tested.
+ * @param axeResults - Raw results from axe-core's `analyze()`.
+ * @param options - Optional threshold overrides.
+ * @returns Modified axe results with resolved contrast findings.
+ *
+ * @example
+ * ```typescript
+ * const axeResults = await axe.run(document);
+ * const cleaned = await resolveIncompleteContrast(cdp, axeResults);
+ * expect(cleaned.violations).toHaveLength(0);
+ * ```
+ */
+export declare function resolveIncompleteContrast(cdp: CDPSessionLike, axeResults: AxeResults, options?: ContrastResolutionOptions): Promise<AxeResults>;
+//# sourceMappingURL=axe-bridge.d.ts.map

package/dist/lib/axe-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"axe-bridge.d.ts","sourceRoot":"","sources":["../../src/lib/axe-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAE7D,OAAO,KAAK,EACV,UAAU,EAEV,yBAAyB,EAC1B,MAAM,YAAY,CAAC;AA2CpB;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,yBAAyB,CAC7C,GAAG,EAAE,cAAc,EACnB,UAAU,EAAE,UAAU,EACtB,OAAO,CAAC,EAAE,yBAAyB,GAClC,OAAO,CAAC,UAAU,CAAC,CA8DrB"}

package/dist/lib/axe-bridge.js

@@ -0,0 +1,106 @@
+/**
+ * @module axe-bridge
+ *
+ * Post-processor for axe-core results that resolves "incomplete"
+ * color-contrast warnings using visual pixel analysis and CSS
+ * halo heuristics.
+ */
+import { VisualContrastAnalyzer } from '@a11y-oracle/visual-engine';
+import { getContrastThresholds } from './wcag-thresholds.js';
+import { getSelector, cloneResults, findIncompleteRule, applyPromotions, } from './resolver-pipeline.js';
+/**
+ * Determine the effective contrast threshold for an axe node.
+ *
+ * axe-core stores font metadata in `node.any[0].data` for the
+ * color-contrast check. Large text (>= 18pt, or >= 14pt bold)
+ * uses the lower 3.0 threshold.
+ */
+function getEffectiveThreshold(node, threshold, largeTextThreshold) {
+    try {
+        const checkData = node.any?.[0]?.data;
+        if (!checkData)
+            return threshold;
+        const fontSize = parseFloat(String(checkData['fontSize'] ?? '0'));
+        const fontWeight = String(checkData['fontWeight'] ?? 'normal');
+        const isBold = fontWeight === 'bold' ||
+            fontWeight === 'bolder' ||
+            parseInt(fontWeight, 10) >= 700;
+        // WCAG large text: >= 18pt (24px) or >= 14pt (18.66px) if bold
+        if (fontSize >= 24 || (fontSize >= 18.66 && isBold)) {
+            return largeTextThreshold;
+        }
+    }
+    catch {
+        // If data parsing fails, use the stricter threshold
+    }
+    return threshold;
+}
+/**
+ * Resolve incomplete color-contrast warnings from axe-core results
+ * using visual pixel analysis and CSS halo heuristics.
+ *
+ * The function deep-clones the input results and returns a modified
+ * copy where:
+ * - Elements that pass worst-case contrast are promoted to `passes`
+ * - Elements that fail best-case contrast are promoted to `violations`
+ * - Ambiguous elements (split decision, dynamic content) remain in `incomplete`
+ *
+ * @param cdp - CDP session connected to the page being tested.
+ * @param axeResults - Raw results from axe-core's `analyze()`.
+ * @param options - Optional threshold overrides.
+ * @returns Modified axe results with resolved contrast findings.
+ *
+ * @example
+ * ```typescript
+ * const axeResults = await axe.run(document);
+ * const cleaned = await resolveIncompleteContrast(cdp, axeResults);
+ * expect(cleaned.violations).toHaveLength(0);
+ * ```
+ */
+export async function resolveIncompleteContrast(cdp, axeResults, options) {
+    const clone = cloneResults(axeResults);
+    // Derive thresholds: explicit values > wcagLevel > default (wcag22aa)
+    const levelThresholds = getContrastThresholds(options?.wcagLevel);
+    // Level A has no contrast requirement — skip resolution entirely
+    if (!levelThresholds && !options?.threshold && !options?.largeTextThreshold) {
+        return clone;
+    }
+    const threshold = options?.threshold ?? levelThresholds?.normalText ?? 4.5;
+    const largeTextThreshold = options?.largeTextThreshold ?? levelThresholds?.largeText ?? 3.0;
+    // Find the color-contrast rule in incomplete results
+    const found = findIncompleteRule(clone, 'color-contrast');
+    if (!found)
+        return clone;
+    const { index: ccIndex, rule: ccRule } = found;
+    const analyzer = new VisualContrastAnalyzer(cdp);
+    const passNodes = [];
+    const violationNodes = [];
+    const incompleteNodes = [];
+    // Analyze each incomplete node
+    for (const node of ccRule.nodes) {
+        const selector = getSelector(node);
+        if (!selector) {
+            incompleteNodes.push(node);
+            continue;
+        }
+        const effectiveThreshold = getEffectiveThreshold(node, threshold, largeTextThreshold);
+        const result = await analyzer.analyzeElement(selector, effectiveThreshold);
+        switch (result.category) {
+            case 'pass':
+                passNodes.push(node);
+                break;
+            case 'violation':
+                violationNodes.push(node);
+                break;
+            case 'incomplete':
+                incompleteNodes.push(node);
+                break;
+        }
+    }
+    applyPromotions(clone, ccIndex, ccRule, {
+        passNodes,
+        violationNodes,
+        incompleteNodes,
+    });
+    return clone;
+}

package/dist/lib/resolve-all.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @module resolve-all
+ *
+ * Orchestrator that pipes axe-core results through all available
+ * incomplete rule resolvers in sequence.
+ *
+ * Each resolver receives the output of the previous one, so resolved
+ * findings accumulate through the pipeline.
+ */
+import type { CDPSessionLike } from '@a11y-oracle/cdp-types';
+import type { AxeResults, IncompleteResolutionOptions } from './types.js';
+/**
+ * Resolve all incomplete axe-core results by running each resolver
+ * in sequence.
+ *
+ * The pipeline processes rules in order:
+ * 1. `color-contrast` — visual pixel analysis
+ * 2. `identical-links-same-purpose` — URL normalization
+ * 3. `link-in-text-block` — default-state style checks
+ * 4. `target-size` — bounding box measurements
+ * 5. `scrollable-region-focusable` — scroll + focus tests
+ * 6. `skip-link` — focus visibility check
+ * 7. `aria-hidden-focus` — Tab traversal
+ * 8. `focus-indicator` — screenshot diff
+ * 9. `content-on-hover` — hover + dismiss tests
+ * 10. `frame-tested` — cross-origin iframe injection
+ *
+ * @param cdp - CDP session connected to the page being tested.
+ * @param axeResults - Raw results from axe-core's `analyze()`.
+ * @param options - Per-resolver options and `skipRules` filter.
+ * @returns Modified axe results with all resolvable findings classified.
+ *
+ * @example
+ * ```typescript
+ * import { resolveAllIncomplete } from '@a11y-oracle/axe-bridge';
+ *
+ * const raw = await axe.run(document);
+ * const resolved = await resolveAllIncomplete(cdp, raw, {
+ *   wcagLevel: 'wcag22aa',
+ *   skipRules: ['frame-tested'], // skip iframe injection
+ * });
+ * ```
+ */
+export declare function resolveAllIncomplete(cdp: CDPSessionLike, axeResults: AxeResults, options?: IncompleteResolutionOptions): Promise<AxeResults>;
+//# sourceMappingURL=resolve-all.d.ts.map

package/dist/lib/resolve-all.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-all.d.ts","sourceRoot":"","sources":["../../src/lib/resolve-all.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,KAAK,EAAE,UAAU,EAAE,2BAA2B,EAAE,MAAM,YAAY,CAAC;AAyF1E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAsB,oBAAoB,CACxC,GAAG,EAAE,cAAc,EACnB,UAAU,EAAE,UAAU,EACtB,OAAO,GAAE,2BAAgC,GACxC,OAAO,CAAC,UAAU,CAAC,CAiBrB"}

package/dist/lib/resolve-all.js

@@ -0,0 +1,117 @@
+/**
+ * @module resolve-all
+ *
+ * Orchestrator that pipes axe-core results through all available
+ * incomplete rule resolvers in sequence.
+ *
+ * Each resolver receives the output of the previous one, so resolved
+ * findings accumulate through the pipeline.
+ */
+import { resolveIncompleteContrast } from './axe-bridge.js';
+import { resolveIdenticalLinksSamePurpose } from './resolvers/identical-links-same-purpose.js';
+import { resolveLinkInTextBlock } from './resolvers/link-in-text-block.js';
+import { resolveTargetSize } from './resolvers/target-size.js';
+import { resolveScrollableRegionFocusable } from './resolvers/scrollable-region-focusable.js';
+import { resolveSkipLink } from './resolvers/skip-link.js';
+import { resolveAriaHiddenFocus } from './resolvers/aria-hidden-focus.js';
+import { resolveFocusIndicator } from './resolvers/focus-indicator.js';
+import { resolveContentOnHover } from './resolvers/content-on-hover.js';
+import { resolveFrameTested } from './resolvers/frame-tested.js';
+/**
+ * Ordered pipeline of resolvers. Each entry maps a rule ID to
+ * its resolver function. The order is chosen to run simpler
+ * resolvers first (pure DOM queries) and more complex ones
+ * (screenshots, keyboard traversal) later.
+ */
+const RESOLVER_PIPELINE = [
+    {
+        ruleId: 'color-contrast',
+        invoke: (cdp, results, opts) => resolveIncompleteContrast(cdp, results, {
+            wcagLevel: opts.wcagLevel,
+            ...opts.contrast,
+        }),
+    },
+    {
+        ruleId: 'identical-links-same-purpose',
+        invoke: (cdp, results) => resolveIdenticalLinksSamePurpose(cdp, results),
+    },
+    {
+        ruleId: 'link-in-text-block',
+        invoke: (cdp, results, opts) => resolveLinkInTextBlock(cdp, results, opts.linkInTextBlock),
+    },
+    {
+        ruleId: 'target-size',
+        invoke: (cdp, results, opts) => resolveTargetSize(cdp, results, opts.targetSize),
+    },
+    {
+        ruleId: 'scrollable-region-focusable',
+        invoke: (cdp, results, opts) => resolveScrollableRegionFocusable(cdp, results, opts.scrollableRegion),
+    },
+    {
+        ruleId: 'skip-link',
+        invoke: (cdp, results, opts) => resolveSkipLink(cdp, results, opts.skipLink),
+    },
+    {
+        ruleId: 'aria-hidden-focus',
+        invoke: (cdp, results, opts) => resolveAriaHiddenFocus(cdp, results, opts.ariaHiddenFocus),
+    },
+    {
+        ruleId: 'focus-indicator',
+        invoke: (cdp, results, opts) => resolveFocusIndicator(cdp, results, opts.focusIndicator),
+    },
+    {
+        ruleId: 'content-on-hover',
+        invoke: (cdp, results, opts) => resolveContentOnHover(cdp, results, opts.contentOnHover),
+    },
+    {
+        ruleId: 'frame-tested',
+        invoke: (cdp, results, opts) => resolveFrameTested(cdp, results, opts.frameTested),
+    },
+];
+/**
+ * Resolve all incomplete axe-core results by running each resolver
+ * in sequence.
+ *
+ * The pipeline processes rules in order:
+ * 1. `color-contrast` — visual pixel analysis
+ * 2. `identical-links-same-purpose` — URL normalization
+ * 3. `link-in-text-block` — default-state style checks
+ * 4. `target-size` — bounding box measurements
+ * 5. `scrollable-region-focusable` — scroll + focus tests
+ * 6. `skip-link` — focus visibility check
+ * 7. `aria-hidden-focus` — Tab traversal
+ * 8. `focus-indicator` — screenshot diff
+ * 9. `content-on-hover` — hover + dismiss tests
+ * 10. `frame-tested` — cross-origin iframe injection
+ *
+ * @param cdp - CDP session connected to the page being tested.
+ * @param axeResults - Raw results from axe-core's `analyze()`.
+ * @param options - Per-resolver options and `skipRules` filter.
+ * @returns Modified axe results with all resolvable findings classified.
+ *
+ * @example
+ * ```typescript
+ * import { resolveAllIncomplete } from '@a11y-oracle/axe-bridge';
+ *
+ * const raw = await axe.run(document);
+ * const resolved = await resolveAllIncomplete(cdp, raw, {
+ *   wcagLevel: 'wcag22aa',
+ *   skipRules: ['frame-tested'], // skip iframe injection
+ * });
+ * ```
+ */
+export async function resolveAllIncomplete(cdp, axeResults, options = {}) {
+    const skipSet = new Set(options.skipRules ?? []);
+    let current = axeResults;
+    for (const entry of RESOLVER_PIPELINE) {
+        // Skip if rule is in skipRules
+        if (skipSet.has(entry.ruleId))
+            continue;
+        // Skip if no incomplete entries exist for this rule
+        const hasRule = current.incomplete.some((r) => r.id === entry.ruleId);
+        if (!hasRule)
+            continue;
+        current = await entry.invoke(cdp, current, options);
+    }
+    return current;
+}

package/dist/lib/resolver-pipeline.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @module resolver-pipeline
+ *
+ * Shared utilities for axe-core incomplete rule resolvers.
+ * Provides the common clone → find-rule → analyze → promote → return
+ * pipeline that every resolver follows.
+ */
+import type { AxeResults, AxeRule, AxeNode } from './types.js';
+/**
+ * Extract the innermost CSS selector from an axe node's target.
+ *
+ * axe-core represents selectors as arrays where shadow DOM targets
+ * have multiple entries. We use the last (innermost) selector.
+ */
+export declare function getSelector(node: AxeNode): string;
+/**
+ * Deep-clone an AxeResults object to avoid mutating the original.
+ */
+export declare function cloneResults(results: AxeResults): AxeResults;
+/**
+ * Create a rule shell (all metadata, no nodes) from an existing rule.
+ */
+export declare function ruleShell(rule: AxeRule): AxeRule;
+/** Categorized node results from a resolver's analysis phase. */
+export interface PromotionResult {
+    passNodes: AxeNode[];
+    violationNodes: AxeNode[];
+    incompleteNodes: AxeNode[];
+}
+/**
+ * Apply node promotions to a cloned AxeResults object.
+ *
+ * Moves nodes from the incomplete rule entry into the passes and
+ * violations arrays, then updates or removes the incomplete entry.
+ *
+ * @param clone - The cloned AxeResults to mutate.
+ * @param ruleIndex - Index of the rule in `clone.incomplete`.
+ * @param rule - The incomplete rule being resolved.
+ * @param result - Categorized nodes from the resolver's analysis.
+ */
+export declare function applyPromotions(clone: AxeResults, ruleIndex: number, rule: AxeRule, result: PromotionResult): void;
+/**
+ * Find a rule by ID in the incomplete array.
+ *
+ * @returns The rule index and rule object, or null if not found.
+ */
+export declare function findIncompleteRule(clone: AxeResults, ruleId: string): {
+    index: number;
+    rule: AxeRule;
+} | null;
+//# sourceMappingURL=resolver-pipeline.d.ts.map