@a11y-oracle/cypress-plugin 1.0.0

package/README.md

@@ -0,0 +1,529 @@
+# @a11y-oracle/cypress-plugin
+
+Cypress integration for A11y-Oracle. Provides custom commands that read the browser's Accessibility Tree via Chrome DevTools Protocol, dispatch native keyboard events, and analyze visual focus indicators.
+
+```typescript
+describe('Navigation', () => {
+  beforeEach(() => {
+    cy.visit('/dropdown-nav.html');
+    cy.initA11yOracle();
+  });
+
+  afterEach(() => {
+    cy.disposeA11yOracle();
+  });
+
+  it('Tab to button announces name and role', () => {
+    cy.a11yPress('Tab')
+      .should('contain', 'Home')
+      .and('contain', 'menu item');
+  });
+});
+```
+
+## Installation
+
+```bash
+npm install -D @a11y-oracle/cypress-plugin @a11y-oracle/core-engine cypress
+```
+
+> **Chrome/Chromium only.** The plugin uses CDP, which is only available in Chrome-family browsers.
+
+## Setup
+
+### 1. Import Commands
+
+Add the plugin to your Cypress support file:
+
+```typescript
+// cypress/support/e2e.ts (or cypress/support/e2e.js)
+import '@a11y-oracle/cypress-plugin';
+```
+
+That's it. Importing the package registers all custom commands automatically.
+
+### 2. Configure Browser
+
+Ensure your Cypress config runs tests in Chrome:
+
+```typescript
+// cypress.config.ts
+import { defineConfig } from 'cypress';
+
+export default defineConfig({
+  e2e: {
+    baseUrl: 'http://localhost:4200',
+    specPattern: 'cypress/e2e/**/*.cy.ts',
+    supportFile: 'cypress/support/e2e.ts',
+  },
+});
+```
+
+Run with Chrome:
+
+```bash
+npx cypress run --browser chrome
+```
+
+## Usage
+
+### Speech Assertions
+
+```typescript
+describe('My Form', () => {
+  beforeEach(() => {
+    cy.visit('/form.html');
+    cy.initA11yOracle();
+  });
+
+  afterEach(() => {
+    cy.disposeA11yOracle();
+  });
+
+  it('Tab navigates to submit button', () => {
+    cy.a11yPress('Tab');
+    cy.a11yPress('Tab');
+    cy.a11yPress('Tab')
+      .should('equal', 'Submit, button');
+  });
+
+  it('checkbox announces checked state', () => {
+    cy.a11yPress('Tab');
+    cy.a11yPress('Space')
+      .should('contain', 'checkbox')
+      .should('contain', 'checked');
+  });
+});
+```
+
+### Unified State (Speech + Focus + Indicator)
+
+```typescript
+it('Tab returns unified accessibility state', () => {
+  cy.a11yPressKey('Tab').then((state) => {
+    // Speech
+    expect(state.speech).to.contain('Submit');
+    expect(state.speechResult?.role).to.equal('button');
+
+    // Focused element
+    expect(state.focusedElement?.tag).to.equal('BUTTON');
+    expect(state.focusedElement?.id).to.equal('submit-btn');
+
+    // Focus indicator (WCAG 2.4.12 AA)
+    expect(state.focusIndicator.isVisible).to.be.true;
+    expect(state.focusIndicator.meetsWCAG_AA).to.be.true;
+  });
+});
+
+it('Shift+Tab navigates backward', () => {
+  cy.a11yPressKey('Tab');
+  cy.a11yPressKey('Tab');
+  cy.a11yPressKey('Tab', { shift: true }).then((state) => {
+    expect(state.focusedElement).to.not.be.null;
+  });
+});
+```
+
+### Tab Order and Keyboard Trap Detection
+
+```typescript
+it('page has correct tab order', () => {
+  cy.a11yTraverseTabOrder().then((report) => {
+    expect(report.totalCount).to.be.greaterThan(0);
+    expect(report.entries[0].tag).to.equal('A');
+  });
+});
+
+it('modal does not trap keyboard focus', () => {
+  cy.a11yTraverseSubTree('#modal-container', 20).then((result) => {
+    expect(result.isTrapped).to.be.false;
+    expect(result.escapeElement).to.not.be.null;
+  });
+});
+```
+
+### Issue Reporting
+
+Check focus indicators and keyboard traps with automatic issue reporting. Issues are accumulated via `cy.task('logOracleIssues')` and can be written to a JSON report at the end of the run.
+
+```typescript
+describe('Accessibility audit', () => {
+  beforeEach(() => {
+    cy.visit('/my-page.html');
+    cy.initA11yOracle();
+  });
+
+  afterEach(() => {
+    cy.disposeA11yOracle();
+  });
+
+  it('focus indicators pass oracle rules', () => {
+    cy.a11yPressKey('Tab');
+    cy.a11yCheckFocusAndReport();   // checks + reports issues
+
+    cy.a11yPressKey('Tab');
+    cy.a11yCheckFocusAndReport();   // check each focused element
+  });
+
+  it('modal is not a keyboard trap', () => {
+    cy.get('#open-modal').click();
+    cy.a11yCheckTrapAndReport('#modal-dialog', 10);
+  });
+});
+```
+
+#### WCAG Level and Rule Configuration
+
+Filter issues by WCAG conformance level or disable specific rules via Cypress env:
+
+```typescript
+// cypress.config.ts
+export default defineConfig({
+  e2e: {
+    env: {
+      wcagLevel: 'wcag21aa',                       // WCAG 2.1 Level AA (default: 'wcag22aa')
+      disabledRules: ['oracle/positive-tabindex'],  // Suppress specific rules
+    },
+  },
+});
+```
+
+Supported `wcagLevel` values (matching axe-core tag format):
+- `'wcag2a'` / `'wcag2aa'` — WCAG 2.0
+- `'wcag21a'` / `'wcag21aa'` — WCAG 2.1
+- `'wcag22a'` / `'wcag22aa'` — WCAG 2.2 (default)
+
+Or override per-command:
+
+```typescript
+cy.a11yCheckFocusAndReport({ wcagLevel: 'wcag22a' });
+cy.a11yCheckFocusAndReport({ disabledRules: ['oracle/focus-low-contrast'] });
+```
+
+Set `Cypress.env('failOnErrors')` to `true` to fail the test immediately when issues are found:
+
+```typescript
+// cypress.config.ts
+export default defineConfig({
+  e2e: {
+    env: { failOnErrors: true },
+  },
+});
+```
+
+For detailed remediation guidance on each rule, see the [Remediation Guide](../../docs/REMEDIATION.md).
+
+### Node-Side Reporting Setup
+
+To accumulate issues across all specs and write a JSON report file, call `setupOracleReporting()` in your Cypress config:
+
+```typescript
+// cypress.config.ts
+import { defineConfig } from 'cypress';
+import { setupOracleReporting } from '@a11y-oracle/cypress-plugin';
+
+export default defineConfig({
+  e2e: {
+    setupNodeEvents(on, config) {
+      setupOracleReporting(on, config);
+    },
+    env: { projectName: 'my-app' },
+  },
+});
+```
+
+This registers the `logOracleIssues` task and writes `oracle-results-{projectName}.json` after the run completes.
+
+**Combining with axe-core violations:** If you want oracle issues in the same array as your axe-core violations (for a single upload to Beacon), add the task handler manually:
+
+```typescript
+setupNodeEvents(on, config) {
+  const allViolations: any[] = [];
+
+  on('task', {
+    logAxeViolations(violations) { allViolations.push(...violations); return null; },
+    logOracleIssues(issues) { allViolations.push(...issues); return null; },
+  });
+
+  on('after:run', () => {
+    if (allViolations.length > 0) {
+      fs.writeFileSync('a11y-results.json', JSON.stringify(allViolations, null, 2));
+    }
+  });
+},
+```
+
+### Asserting on Landmarks and Structure
+
+Use `getA11yFullTreeSpeech()` to inspect elements that don't have focus:
+
+```typescript
+it('navigation landmark exists', () => {
+  cy.getA11yFullTreeSpeech().then((tree) => {
+    const nav = tree.find(r => r.speech.includes('navigation landmark'));
+    expect(nav).to.exist;
+    expect(nav.speech).to.contain('Main');
+  });
+});
+```
+
+### Structured Speech Results
+
+Use `getA11ySpeechResult()` to access individual parts of the speech output:
+
+```typescript
+it('returns structured data', () => {
+  cy.a11yPress('Tab');
+  cy.getA11ySpeechResult().then((result) => {
+    expect(result).to.not.be.null;
+    expect(result.name).to.equal('Home');
+    expect(result.role).to.contain('menu item');
+    expect(result.states).to.be.an('array');
+    expect(result.rawNode).to.exist;
+  });
+});
+```
+
+### Configuration Options
+
+Pass options to `initA11yOracle()` to customize behavior:
+
+```typescript
+// Include descriptions from aria-describedby
+cy.initA11yOracle({ includeDescription: true });
+
+// Disable "landmark" suffix on landmark roles
+cy.initA11yOracle({ includeLandmarks: false });
+
+// Adjust focus settle delay for slow CSS transitions
+cy.initA11yOracle({ focusSettleMs: 100 });
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `includeLandmarks` | `boolean` | `true` | Append "landmark" to landmark roles |
+| `includeDescription` | `boolean` | `false` | Include `aria-describedby` text in output |
+| `focusSettleMs` | `number` | `50` | Delay (ms) after key press for focus/CSS to settle |
+
+## API Reference
+
+### Speech Commands
+
+#### `cy.initA11yOracle(options?)`
+
+Initialize the plugin. Must be called after `cy.visit()` and before other A11y-Oracle commands. Typically called in `beforeEach()`.
+
+Enables CDP domains, discovers the AUT iframe, creates the speech engine and orchestrator.
+
+#### `cy.a11yPress(key)`
+
+Press a keyboard key via CDP and return the speech for the newly focused element. Yields a string.
+
+```typescript
+cy.a11yPress('Tab').should('contain', 'button');
+cy.a11yPress('Enter').should('contain', 'expanded');
+cy.a11yPress('Escape').should('contain', 'collapsed');
+```
+
+Supported keys: `Tab`, `Enter`, `Space`, `Escape`, `ArrowUp`, `ArrowDown`, `ArrowLeft`, `ArrowRight`, `Home`, `End`, `Backspace`, `Delete`.
+
+#### `cy.getA11ySpeech()`
+
+Get the speech string for the currently focused element without pressing a key. Yields a string.
+
+#### `cy.getA11ySpeechResult()`
+
+Get the full structured result for the focused element. Yields `SpeechResult | null`.
+
+#### `cy.getA11yFullTreeSpeech()`
+
+Get speech for all non-ignored nodes in the accessibility tree. Yields `SpeechResult[]`.
+
+### Unified State Commands
+
+#### `cy.a11yPressKey(key, modifiers?)`
+
+Press a key via native CDP dispatch and return the unified accessibility state. Yields `A11yState`.
+
+```typescript
+cy.a11yPressKey('Tab').then((state) => {
+  expect(state.speech).to.contain('button');
+  expect(state.focusIndicator.meetsWCAG_AA).to.be.true;
+});
+
+// With modifier keys
+cy.a11yPressKey('Tab', { shift: true }).then((state) => {
+  expect(state.focusedElement).to.not.be.null;
+});
+```
+
+#### `cy.a11yState()`
+
+Get the current unified accessibility state without pressing a key. Yields `A11yState`.
+
+```typescript
+cy.get('#my-button').focus();
+cy.a11yState().then((state) => {
+  expect(state.speech).to.contain('Submit');
+});
+```
+
+#### `cy.a11yTraverseTabOrder()`
+
+Extract all tabbable elements in DOM tab order. Yields `TabOrderReport`.
+
+```typescript
+cy.a11yTraverseTabOrder().then((report) => {
+  expect(report.totalCount).to.be.greaterThan(0);
+});
+```
+
+#### `cy.a11yTraverseSubTree(selector, maxTabs?)`
+
+Detect whether a container traps keyboard focus (WCAG 2.1.2). Yields `TraversalResult`.
+
+```typescript
+cy.a11yTraverseSubTree('#modal', 20).then((result) => {
+  expect(result.isTrapped).to.be.false;
+});
+```
+
+### Reporting Commands
+
+#### `cy.a11yCheckFocusAndReport(context?)`
+
+Check the current focused element and report any issues via `cy.task('logOracleIssues')`. Runs all state-based rules: `oracle/focus-not-visible`, `oracle/focus-low-contrast`, `oracle/focus-missing-name`, `oracle/focus-generic-role`, and `oracle/positive-tabindex`.
+
+- `context` — Optional `Partial<AuditContext>`. Defaults to `{ project: Cypress.env('projectName'), specName: Cypress.spec.name, wcagLevel: Cypress.env('wcagLevel'), disabledRules: Cypress.env('disabledRules') }`.
+
+#### `cy.a11yCheckTrapAndReport(selector, maxTabs?, context?)`
+
+Check a container for keyboard traps and report any issues via `cy.task('logOracleIssues')`.
+
+- `selector` — CSS selector for the container to test.
+- `maxTabs` — Maximum Tab presses before declaring a trap. Default `50`.
+- `context` — Optional `Partial<AuditContext>`.
+
+#### `setupOracleReporting(on, config)`
+
+Node-side function (not a Cypress command). Call inside `setupNodeEvents()` to register the `logOracleIssues` task and write a JSON report in `after:run`. See [Node-Side Reporting Setup](#node-side-reporting-setup).
+
+```typescript
+import { setupOracleReporting } from '@a11y-oracle/cypress-plugin';
+```
+
+### Lifecycle
+
+#### `cy.disposeA11yOracle()`
+
+Dispose the plugin and release CDP resources. Typically called in `afterEach()`.
+
+### Types
+
+Types are re-exported from `@a11y-oracle/core-engine` and `@a11y-oracle/audit-formatter`:
+
+```typescript
+import type {
+  // Core engine types
+  SpeechResult,
+  A11yState,
+  A11yFocusedElement,
+  A11yFocusIndicator,
+  A11yOrchestratorOptions,
+  ModifierKeys,
+  TabOrderReport,
+  TabOrderEntry,
+  TraversalResult,
+  FocusIndicator,
+  // Audit formatter types
+  OracleIssue,
+  OracleNode,
+  OracleCheck,
+  OracleImpact,
+  OracleResultType,
+  AuditContext,
+} from '@a11y-oracle/cypress-plugin';
+```
+
+## How It Works
+
+The Cypress plugin uses a browser-side CDP approach through `Cypress.automation('remote:debugger:protocol')` — the same pattern used by [cypress-real-events](https://github.com/dmtrKovalenko/cypress-real-events). No Node-side tasks or external libraries are required.
+
+### Cypress Iframe Architecture
+
+Cypress runs the app under test (AUT) inside an iframe within its runner page. This creates a challenge: CDP commands target the runner page by default, not the AUT. The plugin handles this transparently:
+
+1. **Frame discovery** — On `initA11yOracle()`, the plugin calls `Page.getFrameTree()` to enumerate all frames. It identifies the AUT frame by filtering out Cypress internal frames (`/__/`, `__cypress`, `about:blank`).
+
+2. **Frame-scoped accessibility queries** — A CDP adapter injects the AUT `frameId` into every `Accessibility.getFullAXTree()` call, ensuring the accessibility tree is scoped to the app, not the runner UI.
+
+3. **Isolated execution context** — For `Runtime.evaluate` calls (focus indicator analysis, tab order, trap detection), the plugin creates an isolated world in the AUT frame via `Page.createIsolatedWorld`. This isolated world shares the same DOM (including `document.activeElement`, computed styles, etc.) but has its own JavaScript scope, ensuring evaluations target the AUT content.
+
+4. **Focus management** — Before each keyboard event, the plugin uses `DOM.focus()` on the AUT iframe element so that `Input.dispatchKeyEvent` reaches the correct frame.
+
+### CDP Flow
+
+```
+cy.a11yPressKey('Tab')
+  │
+  ├─ DOM.focus() on AUT iframe
+  ├─ Input.dispatchKeyEvent (keyDown + keyUp)
+  ├─ 50ms delay for focus/ARIA state updates
+  ├─ Accessibility.getFullAXTree({ frameId: autFrameId })
+  ├─ Runtime.evaluate({ contextId: autContextId }) — focused element
+  ├─ Runtime.evaluate({ contextId: autContextId }) — focus indicator CSS
+  ├─ Find focused node in AXTree → speech string
+  └─ Assemble A11yState { speech, focusedElement, focusIndicator }
+```
+
+## TypeScript
+
+The plugin augments the `Cypress.Chainable` interface. TypeScript will pick up the command types automatically when you import the plugin in your support file.
+
+If you need types in your test files without importing the support file:
+
+```typescript
+/// <reference types="@a11y-oracle/cypress-plugin" />
+```
+
+## Troubleshooting
+
+### "Could not find the AUT iframe"
+
+This error means `initA11yOracle()` was called before `cy.visit()`. The AUT iframe doesn't exist until Cypress loads a page.
+
+```typescript
+// Wrong
+cy.initA11yOracle();
+cy.visit('/page.html');
+
+// Correct
+cy.visit('/page.html');
+cy.initA11yOracle();
+```
+
+### Speech output contains Cypress UI elements
+
+If assertions match Cypress runner elements (like "Stop, button" or "Options, button"), the frame-scoping may have failed. Ensure:
+
+- You're running in Chrome (`--browser chrome`)
+- `cy.visit()` completed before `cy.initA11yOracle()`
+- The AUT URL is not `about:blank`
+
+### Empty speech string
+
+`a11yPress()` returns an empty string when no element has focus after the key press. This can happen if:
+
+- The key press moved focus outside the page (e.g., Tab past the last element)
+- The focused element has `role="presentation"` or `role="none"`
+- The focused element is the `RootWebArea` (document body)
+
+### Focus indicator shows `contrastRatio: null`
+
+This happens when the focus indicator color cannot be reliably parsed. Common causes:
+
+- Complex CSS color functions (`color-mix()`, `hsl()`, named colors)
+- Multi-layer gradients as focus indicators
+- `currentColor` as outline color
+
+For the full list of role and state mappings, see the [@a11y-oracle/core-engine README](../core-engine/README.md).

package/dist/index.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @module @a11y-oracle/cypress-plugin
+ *
+ * Cypress plugin for A11y-Oracle accessibility speech testing.
+ *
+ * Import this module in your Cypress support file to register
+ * custom commands that read the browser's accessibility tree
+ * and produce standardized speech output.
+ *
+ * ## Setup
+ *
+ * ```typescript
+ * // cypress/support/e2e.ts
+ * import '@a11y-oracle/cypress-plugin';
+ * ```
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * describe('Navigation', () => {
+ *   beforeEach(() => {
+ *     cy.visit('/');
+ *     cy.initA11yOracle();
+ *   });
+ *
+ *   afterEach(() => {
+ *     cy.disposeA11yOracle();
+ *   });
+ *
+ *   it('Tab announces first menu item', () => {
+ *     cy.a11yPress('Tab').should('contain', 'Home');
+ *   });
+ * });
+ * ```
+ *
+ * ## Requirements
+ *
+ * - Chromium-based browser (Chrome, Edge, Electron)
+ * - Cypress >= 12.0.0
+ */
+import './lib/commands.js';
+export type { SpeechResult, SpeechEngineOptions, A11yState, A11yFocusedElement, A11yFocusIndicator, A11yOrchestratorOptions, ModifierKeys, TabOrderReport, TabOrderEntry, TraversalResult, FocusIndicator, } from '@a11y-oracle/core-engine';
+export type { OracleIssue, OracleNode, OracleCheck, OracleImpact, OracleResultType, AuditContext, } from '@a11y-oracle/audit-formatter';
+export { setupOracleReporting } from './lib/reporting.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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAGH,OAAO,mBAAmB,CAAC;AAG3B,YAAY,EACV,YAAY,EACZ,mBAAmB,EACnB,SAAS,EACT,kBAAkB,EAClB,kBAAkB,EAClB,uBAAuB,EACvB,YAAY,EACZ,cAAc,EACd,aAAa,EACb,eAAe,EACf,cAAc,GACf,MAAM,0BAA0B,CAAC;AAGlC,YAAY,EACV,WAAW,EACX,UAAU,EACV,WAAW,EACX,YAAY,EACZ,gBAAgB,EAChB,YAAY,GACb,MAAM,8BAA8B,CAAC;AAGtC,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -0,0 +1,44 @@
+/**
+ * @module @a11y-oracle/cypress-plugin
+ *
+ * Cypress plugin for A11y-Oracle accessibility speech testing.
+ *
+ * Import this module in your Cypress support file to register
+ * custom commands that read the browser's accessibility tree
+ * and produce standardized speech output.
+ *
+ * ## Setup
+ *
+ * ```typescript
+ * // cypress/support/e2e.ts
+ * import '@a11y-oracle/cypress-plugin';
+ * ```
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * describe('Navigation', () => {
+ *   beforeEach(() => {
+ *     cy.visit('/');
+ *     cy.initA11yOracle();
+ *   });
+ *
+ *   afterEach(() => {
+ *     cy.disposeA11yOracle();
+ *   });
+ *
+ *   it('Tab announces first menu item', () => {
+ *     cy.a11yPress('Tab').should('contain', 'Home');
+ *   });
+ * });
+ * ```
+ *
+ * ## Requirements
+ *
+ * - Chromium-based browser (Chrome, Edge, Electron)
+ * - Cypress >= 12.0.0
+ */
+// Side-effect import: registers all custom Cypress commands
+import './lib/commands.js';
+// Node-side reporting setup
+export { setupOracleReporting } from './lib/reporting.js';

package/dist/lib/commands.d.ts

@@ -0,0 +1,101 @@
+/**
+ * @module commands
+ *
+ * Custom Cypress commands for accessibility speech testing and
+ * keyboard/focus analysis.
+ *
+ * Uses `Cypress.automation('remote:debugger:protocol')` to communicate
+ * with Chrome DevTools Protocol directly through Cypress's own CDP
+ * connection — no external libraries or Node-side tasks required.
+ *
+ * This is the same proven pattern used by cypress-real-events.
+ *
+ * ## Cypress iframe architecture
+ *
+ * Cypress runs the AUT (app under test) inside an iframe within
+ * its runner page. This module handles:
+ * - Scoping accessibility tree queries to the AUT frame via `frameId`
+ * - Executing `Runtime.evaluate` in the AUT frame via `contextId`
+ * - Focusing the AUT iframe before dispatching keyboard events
+ *
+ * @example
+ * ```typescript
+ * // In your test:
+ * cy.initA11yOracle();
+ * cy.a11yPress('Tab').should('contain', 'Home');
+ * cy.a11yPressKey('Tab').then(state => {
+ *   expect(state.focusIndicator.meetsWCAG_AA).to.be.true;
+ * });
+ * cy.disposeA11yOracle();
+ * ```
+ */
+import type { SpeechResult, A11yState, A11yOrchestratorOptions, TabOrderReport, TraversalResult, ModifierKeys } from '@a11y-oracle/core-engine';
+import type { AuditContext } from '@a11y-oracle/audit-formatter';
+declare global {
+    namespace Cypress {
+        interface Chainable {
+            /**
+             * Initialize A11y-Oracle. Must be called before other a11y commands.
+             * Typically called in `beforeEach()`.
+             */
+            initA11yOracle(options?: A11yOrchestratorOptions): Chainable<null>;
+            /**
+             * Press a keyboard key via CDP and return the speech for the
+             * newly focused element.
+             *
+             * @param key - Key name (e.g. `'Tab'`, `'Enter'`, `'ArrowDown'`).
+             */
+            a11yPress(key: string): Chainable<string>;
+            /** Get the speech string for the currently focused element. */
+            getA11ySpeech(): Chainable<string>;
+            /** Get the full {@link SpeechResult} for the currently focused element. */
+            getA11ySpeechResult(): Chainable<SpeechResult | null>;
+            /** Get speech output for every visible node in the accessibility tree. */
+            getA11yFullTreeSpeech(): Chainable<SpeechResult[]>;
+            /**
+             * Press a key via CDP and return the unified accessibility state.
+             *
+             * @param key - Key name (e.g. `'Tab'`, `'Enter'`, `'ArrowDown'`).
+             * @param modifiers - Optional modifier keys.
+             */
+            a11yPressKey(key: string, modifiers?: ModifierKeys): Chainable<A11yState>;
+            /** Get the current unified accessibility state without pressing a key. */
+            a11yState(): Chainable<A11yState>;
+            /** Extract all tabbable elements in DOM tab order. */
+            a11yTraverseTabOrder(): Chainable<TabOrderReport>;
+            /**
+             * Detect whether a container traps keyboard focus (WCAG 2.1.2).
+             *
+             * @param selector - CSS selector for the container to test.
+             * @param maxTabs - Maximum Tab presses before declaring a trap. Default 50.
+             */
+            a11yTraverseSubTree(selector: string, maxTabs?: number): Chainable<TraversalResult>;
+            /**
+             * Check the current focused element's focus indicator and report
+             * any issues via `cy.task('logOracleIssues')`.
+             *
+             * Mirrors the pattern of `checkAccessibilityAndReport` for axe-core.
+             * Issues are emitted as `OracleIssue[]` and can be accumulated in
+             * `setupNodeEvents` for end-of-run reporting.
+             *
+             * @param context - Optional audit context. Defaults to current spec name and project from env.
+             */
+            a11yCheckFocusAndReport(context?: Partial<AuditContext>): Chainable<void>;
+            /**
+             * Check a container for keyboard traps and report any issues via
+             * `cy.task('logOracleIssues')`.
+             *
+             * @param selector - CSS selector for the container to test.
+             * @param maxTabs - Maximum Tab presses before declaring a trap. Default 50.
+             * @param context - Optional audit context.
+             */
+            a11yCheckTrapAndReport(selector: string, maxTabs?: number, context?: Partial<AuditContext>): Chainable<void>;
+            /**
+             * Dispose A11y-Oracle and release resources.
+             * Typically called in `afterEach()`.
+             */
+            disposeA11yOracle(): Chainable<null>;
+        }
+    }
+}
+//# sourceMappingURL=commands.d.ts.map

package/dist/lib/commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../../src/lib/commands.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAGH,OAAO,KAAK,EAEV,YAAY,EACZ,SAAS,EACT,uBAAuB,EACvB,cAAc,EACd,eAAe,EACf,YAAY,EACb,MAAM,0BAA0B,CAAC;AAMlC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAIjE,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,OAAO,CAAC;QAChB,UAAU,SAAS;YACjB;;;eAGG;YACH,cAAc,CAAC,OAAO,CAAC,EAAE,uBAAuB,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;YAEnE;;;;;eAKG;YACH,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC;YAE1C,+DAA+D;YAC/D,aAAa,IAAI,SAAS,CAAC,MAAM,CAAC,CAAC;YAEnC,2EAA2E;YAC3E,mBAAmB,IAAI,SAAS,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;YAEtD,0EAA0E;YAC1E,qBAAqB,IAAI,SAAS,CAAC,YAAY,EAAE,CAAC,CAAC;YAEnD;;;;;eAKG;YACH,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC,SAAS,CAAC,CAAC;YAE1E,0EAA0E;YAC1E,SAAS,IAAI,SAAS,CAAC,SAAS,CAAC,CAAC;YAElC,sDAAsD;YACtD,oBAAoB,IAAI,SAAS,CAAC,cAAc,CAAC,CAAC;YAElD;;;;;eAKG;YACH,mBAAmB,CACjB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,GACf,SAAS,CAAC,eAAe,CAAC,CAAC;YAE9B;;;;;;;;;eASG;YACH,uBAAuB,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;YAE1E;;;;;;;eAOG;YACH,sBAAsB,CACpB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAC9B,SAAS,CAAC,IAAI,CAAC,CAAC;YAEnB;;;eAGG;YACH,iBAAiB,IAAI,SAAS,CAAC,IAAI,CAAC,CAAC;SACtC;KACF;CACF"}

package/dist/lib/commands.js

@@ -0,0 +1,363 @@
+/**
+ * @module commands
+ *
+ * Custom Cypress commands for accessibility speech testing and
+ * keyboard/focus analysis.
+ *
+ * Uses `Cypress.automation('remote:debugger:protocol')` to communicate
+ * with Chrome DevTools Protocol directly through Cypress's own CDP
+ * connection — no external libraries or Node-side tasks required.
+ *
+ * This is the same proven pattern used by cypress-real-events.
+ *
+ * ## Cypress iframe architecture
+ *
+ * Cypress runs the AUT (app under test) inside an iframe within
+ * its runner page. This module handles:
+ * - Scoping accessibility tree queries to the AUT frame via `frameId`
+ * - Executing `Runtime.evaluate` in the AUT frame via `contextId`
+ * - Focusing the AUT iframe before dispatching keyboard events
+ *
+ * @example
+ * ```typescript
+ * // In your test:
+ * cy.initA11yOracle();
+ * cy.a11yPress('Tab').should('contain', 'Home');
+ * cy.a11yPressKey('Tab').then(state => {
+ *   expect(state.focusIndicator.meetsWCAG_AA).to.be.true;
+ * });
+ * cy.disposeA11yOracle();
+ * ```
+ */
+import { SpeechEngine, A11yOrchestrator } from '@a11y-oracle/core-engine';
+import { KEY_DEFINITIONS } from '@a11y-oracle/keyboard-engine';
+import { formatAllIssues, formatTrapIssue, } from '@a11y-oracle/audit-formatter';
+// ── Internals ──────────────────────────────────────────────────────
+let engine = null;
+let orchestrator = null;
+let autFrameId = null;
+let autContextId = null;
+/**
+ * Send a raw CDP command through Cypress's automation channel.
+ */
+function sendCDP(command, params = {}) {
+    return Cypress.automation('remote:debugger:protocol', {
+        command,
+        params,
+    });
+}
+/**
+ * Create a {@link CDPSessionLike} adapter that routes CDP calls through
+ * Cypress's built-in `remote:debugger:protocol` automation channel.
+ *
+ * Automatically injects:
+ * - The AUT iframe's `frameId` into `Accessibility.getFullAXTree` calls
+ * - The AUT iframe's `contextId` into `Runtime.evaluate` calls
+ *
+ * This ensures all queries target the AUT content, not the Cypress
+ * runner UI.
+ */
+function createFrameAwareCDPAdapter() {
+    return {
+        send: (method, params) => {
+            const p = { ...params };
+            // Scope AXTree to AUT frame
+            if (method === 'Accessibility.getFullAXTree' && autFrameId) {
+                p['frameId'] = autFrameId;
+            }
+            // Scope Runtime.evaluate to AUT frame's execution context
+            if (method === 'Runtime.evaluate' && autContextId !== null) {
+                p['contextId'] = autContextId;
+            }
+            return sendCDP(method, p);
+        },
+    };
+}
+/**
+ * Discover the AUT (app under test) iframe's frame ID
+ * from the Cypress runner page's frame tree.
+ *
+ * The AUT frame is identified by having a URL that doesn't
+ * contain `/__/` (runner), `__cypress` (spec iframe), or
+ * `about:blank` (snapshot frames).
+ */
+async function findAUTFrameId() {
+    const result = await sendCDP('Page.getFrameTree');
+    const childFrames = result.frameTree.childFrames || [];
+    for (const child of childFrames) {
+        const url = child.frame.url || '';
+        if (url &&
+            !url.includes('/__/') &&
+            !url.includes('__cypress') &&
+            url !== 'about:blank') {
+            return child.frame.id;
+        }
+    }
+    // Fallback: first child frame with a non-blank URL
+    for (const child of childFrames) {
+        if (child.frame.url && child.frame.url !== 'about:blank') {
+            return child.frame.id;
+        }
+    }
+    return null;
+}
+/**
+ * Discover the execution context ID for the AUT frame.
+ *
+ * Creates an isolated world in the AUT frame, which shares the
+ * same DOM (including `document.activeElement`, computed styles, etc.)
+ * but has its own JavaScript scope. This ensures `Runtime.evaluate`
+ * calls execute in the AUT, not the Cypress runner.
+ */
+async function findAUTContextId(frameId) {
+    try {
+        const result = await sendCDP('Page.createIsolatedWorld', {
+            frameId,
+            worldName: 'a11y-oracle',
+            grantUniversalAccess: true,
+        });
+        return result.executionContextId;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Focus the AUT iframe element so that CDP keyboard events
+ * reach the AUT's content instead of the Cypress runner UI.
+ */
+async function focusAUTFrame() {
+    try {
+        // Get the runner page's document
+        const doc = await sendCDP('DOM.getDocument', { depth: 0 });
+        if (!doc?.root?.nodeId)
+            return;
+        // Find all iframes and focus the AUT one
+        const iframes = await sendCDP('DOM.querySelectorAll', {
+            nodeId: doc.root.nodeId,
+            selector: 'iframe',
+        });
+        if (!iframes?.nodeIds)
+            return;
+        for (const nodeId of iframes.nodeIds) {
+            try {
+                const attrs = await sendCDP('DOM.getAttributes', { nodeId });
+                const attrList = attrs.attributes;
+                // Find the iframe whose src matches the AUT URL
+                const srcIndex = attrList.indexOf('src');
+                if (srcIndex >= 0) {
+                    const src = attrList[srcIndex + 1];
+                    if (src &&
+                        !src.includes('/__/') &&
+                        !src.includes('__cypress') &&
+                        src !== 'about:blank') {
+                        await sendCDP('DOM.focus', { nodeId });
+                        return;
+                    }
+                }
+                // Also check by name attribute (Cypress names AUT frames)
+                const nameIndex = attrList.indexOf('name');
+                if (nameIndex >= 0) {
+                    const name = attrList[nameIndex + 1];
+                    if (name && name.startsWith('Your project:')) {
+                        await sendCDP('DOM.focus', { nodeId });
+                        return;
+                    }
+                }
+            }
+            catch {
+                // Skip iframes we can't inspect
+            }
+        }
+    }
+    catch {
+        // DOM query failed — frame focus is best-effort
+    }
+}
+/**
+ * Dispatch a real keyboard event (keyDown + keyUp) via CDP.
+ */
+async function dispatchKey(key) {
+    const keyDef = KEY_DEFINITIONS[key];
+    if (!keyDef) {
+        const supported = Object.keys(KEY_DEFINITIONS).join(', ');
+        throw new Error(`Unknown key: "${key}". Supported keys: ${supported}`);
+    }
+    // Ensure the AUT iframe has focus before each key dispatch
+    await focusAUTFrame();
+    await sendCDP('Input.dispatchKeyEvent', {
+        type: 'keyDown',
+        key: keyDef.key,
+        code: keyDef.code,
+        windowsVirtualKeyCode: keyDef.keyCode,
+        nativeVirtualKeyCode: keyDef.keyCode,
+    });
+    await sendCDP('Input.dispatchKeyEvent', {
+        type: 'keyUp',
+        key: keyDef.key,
+        code: keyDef.code,
+        windowsVirtualKeyCode: keyDef.keyCode,
+        nativeVirtualKeyCode: keyDef.keyCode,
+    });
+}
+// ── Commands ───────────────────────────────────────────────────────
+Cypress.Commands.add('initA11yOracle', (options) => {
+    cy.wrap(null, { log: false }).then(async () => {
+        // Enable required CDP domains
+        await sendCDP('DOM.enable');
+        await sendCDP('Page.enable');
+        // Discover the AUT frame
+        autFrameId = await findAUTFrameId();
+        if (!autFrameId) {
+            throw new Error('A11y-Oracle: Could not find the AUT iframe. ' +
+                'Ensure cy.visit() was called before cy.initA11yOracle().');
+        }
+        // Get the AUT frame's execution context for Runtime.evaluate
+        autContextId = await findAUTContextId(autFrameId);
+        // Focus the AUT iframe so key events reach it
+        await focusAUTFrame();
+        // Create the CDP adapter that routes to the AUT frame
+        const adapter = createFrameAwareCDPAdapter();
+        // Create the speech engine scoped to the AUT frame
+        engine = new SpeechEngine(adapter, options);
+        await engine.enable();
+        // Create the orchestrator for unified state
+        orchestrator = new A11yOrchestrator(adapter, options);
+        await orchestrator.enable();
+        return null;
+    });
+});
+Cypress.Commands.add('a11yPress', (key) => {
+    cy.wrap(null, { log: false }).then(async () => {
+        if (!engine) {
+            throw new Error('A11y-Oracle not initialized. Call cy.initA11yOracle() first.');
+        }
+        await dispatchKey(key);
+        // Allow browser to update focus and ARIA states
+        await new Promise((resolve) => setTimeout(resolve, 50));
+        const result = await engine.getSpeech();
+        return result?.speech ?? '';
+    });
+});
+Cypress.Commands.add('getA11ySpeech', () => {
+    cy.wrap(null, { log: false }).then(async () => {
+        if (!engine) {
+            throw new Error('A11y-Oracle not initialized. Call cy.initA11yOracle() first.');
+        }
+        const result = await engine.getSpeech();
+        return result?.speech ?? '';
+    });
+});
+Cypress.Commands.add('getA11ySpeechResult', () => {
+    cy.wrap(null, { log: false }).then(async () => {
+        if (!engine) {
+            throw new Error('A11y-Oracle not initialized. Call cy.initA11yOracle() first.');
+        }
+        return (await engine.getSpeech()) ?? null;
+    });
+});
+Cypress.Commands.add('getA11yFullTreeSpeech', () => {
+    cy.wrap(null, { log: false }).then(async () => {
+        if (!engine) {
+            throw new Error('A11y-Oracle not initialized. Call cy.initA11yOracle() first.');
+        }
+        return engine.getFullTreeSpeech();
+    });
+});
+Cypress.Commands.add('a11yPressKey', (key, modifiers) => {
+    cy.wrap(null, { log: false }).then(async () => {
+        if (!orchestrator) {
+            throw new Error('A11y-Oracle not initialized. Call cy.initA11yOracle() first.');
+        }
+        // Ensure the AUT iframe has focus before key dispatch
+        await focusAUTFrame();
+        return orchestrator.pressKey(key, modifiers);
+    });
+});
+Cypress.Commands.add('a11yState', () => {
+    cy.wrap(null, { log: false }).then(async () => {
+        if (!orchestrator) {
+            throw new Error('A11y-Oracle not initialized. Call cy.initA11yOracle() first.');
+        }
+        return orchestrator.getState();
+    });
+});
+Cypress.Commands.add('a11yTraverseTabOrder', () => {
+    cy.wrap(null, { log: false }).then(async () => {
+        if (!orchestrator) {
+            throw new Error('A11y-Oracle not initialized. Call cy.initA11yOracle() first.');
+        }
+        return orchestrator.traverseTabOrder();
+    });
+});
+Cypress.Commands.add('a11yTraverseSubTree', (selector, maxTabs) => {
+    cy.wrap(null, { log: false }).then(async () => {
+        if (!orchestrator) {
+            throw new Error('A11y-Oracle not initialized. Call cy.initA11yOracle() first.');
+        }
+        return orchestrator.traverseSubTree(selector, maxTabs);
+    });
+});
+/**
+ * Build an AuditContext from optional overrides, falling back to
+ * Cypress.spec.name and Cypress.env('projectName').
+ */
+function resolveAuditContext(overrides) {
+    return {
+        project: overrides?.project ?? Cypress.env('projectName') ?? '',
+        specName: overrides?.specName ?? Cypress.spec.name,
+        wcagLevel: overrides?.wcagLevel ?? Cypress.env('wcagLevel') ?? undefined,
+        disabledRules: overrides?.disabledRules ?? Cypress.env('disabledRules') ?? undefined,
+    };
+}
+Cypress.Commands.add('a11yCheckFocusAndReport', (context) => {
+    cy.wrap(null, { log: false }).then(async () => {
+        if (!orchestrator) {
+            throw new Error('A11y-Oracle not initialized. Call cy.initA11yOracle() first.');
+        }
+        const ctx = resolveAuditContext(context);
+        const state = await orchestrator.getState();
+        const issues = formatAllIssues(state, ctx);
+        if (issues.length > 0) {
+            cy.task('log', `[A11y-Oracle] ${issues.length} focus issue(s) detected on ${ctx.specName}`);
+            cy.task('logOracleIssues', issues).then(() => {
+                if (Cypress.env('failOnErrors')) {
+                    throw new Error(`[A11y-Oracle] ${issues.length} focus indicator issue(s) detected: ${issues.map((issue) => issue.ruleId).join(', ')}`);
+                }
+            });
+        }
+    });
+});
+Cypress.Commands.add('a11yCheckTrapAndReport', (selector, maxTabs, context) => {
+    cy.wrap(null, { log: false }).then(async () => {
+        if (!orchestrator) {
+            throw new Error('A11y-Oracle not initialized. Call cy.initA11yOracle() first.');
+        }
+        const ctx = resolveAuditContext(context);
+        const result = await orchestrator.traverseSubTree(selector, maxTabs ?? 50);
+        const issues = formatTrapIssue(result, selector, ctx);
+        if (issues.length > 0) {
+            cy.task('log', `[A11y-Oracle] Keyboard trap detected in ${selector} on ${ctx.specName}`);
+            cy.task('logOracleIssues', issues).then(() => {
+                if (Cypress.env('failOnErrors')) {
+                    throw new Error(`[A11y-Oracle] Keyboard trap detected in ${selector}`);
+                }
+            });
+        }
+    });
+});
+Cypress.Commands.add('disposeA11yOracle', () => {
+    cy.wrap(null, { log: false }).then(async () => {
+        if (orchestrator) {
+            await orchestrator.disable();
+            orchestrator = null;
+        }
+        if (engine) {
+            // Engine was already disabled via orchestrator (same CDP session)
+            engine = null;
+        }
+        autFrameId = null;
+        autContextId = null;
+        return null;
+    });
+});

package/dist/lib/key-map.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @module key-map
+ *
+ * Maps human-readable key names to CDP `Input.dispatchKeyEvent` parameters.
+ * Used by the {@link commands} module to dispatch real keyboard events
+ * through the Chrome DevTools Protocol.
+ */
+export interface KeyDefinition {
+    /** The `key` property for CDP (e.g. `'Tab'`, `'Enter'`). */
+    key: string;
+    /** The `code` property for CDP (e.g. `'Tab'`, `'Enter'`). */
+    code: string;
+    /** The Windows virtual key code (e.g. `9` for Tab). */
+    keyCode: number;
+}
+/**
+ * Map of key names to their CDP Input.dispatchKeyEvent parameters.
+ *
+ * Supports all common navigation and interaction keys used in
+ * WCAG keyboard accessibility patterns.
+ */
+export declare const KEY_DEFINITIONS: Record<string, KeyDefinition>;
+//# sourceMappingURL=key-map.d.ts.map

package/dist/lib/key-map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"key-map.d.ts","sourceRoot":"","sources":["../../src/lib/key-map.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,aAAa;IAC5B,4DAA4D;IAC5D,GAAG,EAAE,MAAM,CAAC;IACZ,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb,uDAAuD;IACvD,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAczD,CAAC"}

package/dist/lib/key-map.js

@@ -0,0 +1,28 @@
+/**
+ * @module key-map
+ *
+ * Maps human-readable key names to CDP `Input.dispatchKeyEvent` parameters.
+ * Used by the {@link commands} module to dispatch real keyboard events
+ * through the Chrome DevTools Protocol.
+ */
+/**
+ * Map of key names to their CDP Input.dispatchKeyEvent parameters.
+ *
+ * Supports all common navigation and interaction keys used in
+ * WCAG keyboard accessibility patterns.
+ */
+export const KEY_DEFINITIONS = {
+    Tab: { key: 'Tab', code: 'Tab', keyCode: 9 },
+    Enter: { key: 'Enter', code: 'Enter', keyCode: 13 },
+    ' ': { key: ' ', code: 'Space', keyCode: 32 },
+    Space: { key: ' ', code: 'Space', keyCode: 32 },
+    Escape: { key: 'Escape', code: 'Escape', keyCode: 27 },
+    ArrowUp: { key: 'ArrowUp', code: 'ArrowUp', keyCode: 38 },
+    ArrowDown: { key: 'ArrowDown', code: 'ArrowDown', keyCode: 40 },
+    ArrowLeft: { key: 'ArrowLeft', code: 'ArrowLeft', keyCode: 37 },
+    ArrowRight: { key: 'ArrowRight', code: 'ArrowRight', keyCode: 39 },
+    Home: { key: 'Home', code: 'Home', keyCode: 36 },
+    End: { key: 'End', code: 'End', keyCode: 35 },
+    Backspace: { key: 'Backspace', code: 'Backspace', keyCode: 8 },
+    Delete: { key: 'Delete', code: 'Delete', keyCode: 46 },
+};

package/dist/lib/reporting.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @module reporting
+ *
+ * Node-side setup for Oracle issue reporting in Cypress.
+ *
+ * Call `setupOracleReporting()` inside `setupNodeEvents()` in your
+ * `cypress.config.ts` to register the `logOracleIssues` task and
+ * automatically write a JSON report file at the end of each run.
+ *
+ * @example
+ * ```typescript
+ * // cypress.config.ts
+ * import { setupOracleReporting } from '@a11y-oracle/cypress-plugin';
+ *
+ * export default defineConfig({
+ *   e2e: {
+ *     setupNodeEvents(on, config) {
+ *       setupOracleReporting(on, config);
+ *     },
+ *     env: { projectName: 'my-app' },
+ *   },
+ * });
+ * ```
+ *
+ * Or, to combine oracle issues with your existing axe-core violations
+ * array, just add the `logOracleIssues` task yourself:
+ *
+ * ```typescript
+ * on('task', {
+ *   logAxeViolations(violations) { allViolations.push(...violations); return null; },
+ *   logOracleIssues(issues) { allViolations.push(...issues); return null; },
+ * });
+ * ```
+ */
+/**
+ * Register Oracle reporting tasks and after:run hook.
+ *
+ * Registers:
+ * - `logOracleIssues` task — accumulates OracleIssue objects in memory
+ * - `after:run` hook — writes accumulated issues to
+ *   `oracle-results-${projectName}.json`
+ *
+ * @param on - Cypress `on` function from `setupNodeEvents`
+ * @param config - Cypress plugin config object
+ */
+export declare function setupOracleReporting(on: Cypress.PluginEvents, config: Cypress.PluginConfigOptions): void;
+//# sourceMappingURL=reporting.d.ts.map

package/dist/lib/reporting.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reporting.d.ts","sourceRoot":"","sources":["../../src/lib/reporting.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAKH;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,EAAE,EAAE,OAAO,CAAC,YAAY,EACxB,MAAM,EAAE,OAAO,CAAC,mBAAmB,GAClC,IAAI,CA4BN"}

package/dist/lib/reporting.js

@@ -0,0 +1,71 @@
+/**
+ * @module reporting
+ *
+ * Node-side setup for Oracle issue reporting in Cypress.
+ *
+ * Call `setupOracleReporting()` inside `setupNodeEvents()` in your
+ * `cypress.config.ts` to register the `logOracleIssues` task and
+ * automatically write a JSON report file at the end of each run.
+ *
+ * @example
+ * ```typescript
+ * // cypress.config.ts
+ * import { setupOracleReporting } from '@a11y-oracle/cypress-plugin';
+ *
+ * export default defineConfig({
+ *   e2e: {
+ *     setupNodeEvents(on, config) {
+ *       setupOracleReporting(on, config);
+ *     },
+ *     env: { projectName: 'my-app' },
+ *   },
+ * });
+ * ```
+ *
+ * Or, to combine oracle issues with your existing axe-core violations
+ * array, just add the `logOracleIssues` task yourself:
+ *
+ * ```typescript
+ * on('task', {
+ *   logAxeViolations(violations) { allViolations.push(...violations); return null; },
+ *   logOracleIssues(issues) { allViolations.push(...issues); return null; },
+ * });
+ * ```
+ */
+/// <reference types="node" />
+import * as fs from 'fs';
+/**
+ * Register Oracle reporting tasks and after:run hook.
+ *
+ * Registers:
+ * - `logOracleIssues` task — accumulates OracleIssue objects in memory
+ * - `after:run` hook — writes accumulated issues to
+ *   `oracle-results-${projectName}.json`
+ *
+ * @param on - Cypress `on` function from `setupNodeEvents`
+ * @param config - Cypress plugin config object
+ */
+export function setupOracleReporting(on, config) {
+    const allIssues = [];
+    const projectName = config.env?.['projectName'] ?? 'default-project';
+    on('task', {
+        logOracleIssues(issues) {
+            if (Array.isArray(issues)) {
+                const enriched = issues.map((v) => ({
+                    ...v,
+                    project: v.project || projectName,
+                }));
+                allIssues.push(...enriched);
+            }
+            return null;
+        },
+    });
+    on('after:run', () => {
+        if (allIssues.length > 0) {
+            const reportPath = `oracle-results-${projectName}.json`;
+            fs.writeFileSync(reportPath, JSON.stringify(allIssues, null, 2));
+            console.log(`\n[A11y-Oracle] Report saved to ${reportPath}`);
+            console.log(`[A11y-Oracle] Total issues found: ${allIssues.length}`);
+        }
+    });
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@a11y-oracle/cypress-plugin",
+  "version": "1.0.0",
+  "description": "Cypress custom commands for accessibility speech assertions with iframe-aware CDP routing",
+  "license": "MIT",
+  "author": "a11y-oracle",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/a11y-oracle/a11y-oracle.git",
+    "directory": "libs/cypress-plugin"
+  },
+  "bugs": {
+    "url": "https://github.com/a11y-oracle/a11y-oracle/issues"
+  },
+  "homepage": "https://github.com/a11y-oracle/a11y-oracle/tree/main/libs/cypress-plugin",
+  "keywords": [
+    "accessibility",
+    "a11y",
+    "cypress",
+    "screen-reader",
+    "wcag",
+    "testing",
+    "e2e"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!**/*.tsbuildinfo"
+  ],
+  "peerDependencies": {
+    "cypress": ">=12.0.0"
+  },
+  "dependencies": {
+    "@a11y-oracle/core-engine": "1.0.0",
+    "@a11y-oracle/keyboard-engine": "1.0.0",
+    "@a11y-oracle/audit-formatter": "1.0.0",
+    "tslib": "^2.3.0"
+  }
+}