@a11y-oracle/playwright-plugin 1.0.0

package/README.md

@@ -0,0 +1,376 @@
+# @a11y-oracle/playwright-plugin
+
+Playwright integration for A11y-Oracle. Provides a test fixture and wrapper class that reads the browser's Accessibility Tree via Chrome DevTools Protocol, dispatches native keyboard events, and analyzes visual focus indicators.
+
+```typescript
+import { test, expect } from '@a11y-oracle/playwright-plugin';
+
+test('dropdown button announces correctly', async ({ page, a11y }) => {
+  await page.goto('/dropdown-nav.html');
+
+  const speech = await a11y.press('Tab');
+  expect(speech).toContain('Home');
+  expect(speech).toContain('menu item');
+});
+```
+
+## Installation
+
+```bash
+npm install -D @a11y-oracle/playwright-plugin @a11y-oracle/core-engine @playwright/test
+```
+
+> **Chromium only.** CDP sessions are not available for Firefox or WebKit in Playwright.
+
+## Usage
+
+### Test Fixture (Recommended)
+
+The plugin exports an extended `test` function that injects an `a11y` fixture. The CDP session is created before each test and cleaned up automatically after.
+
+```typescript
+import { test, expect } from '@a11y-oracle/playwright-plugin';
+
+test.describe('Navigation', () => {
+  test.beforeEach(async ({ page }) => {
+    await page.goto('/my-page.html');
+  });
+
+  test('Tab to button announces name and role', async ({ a11y }) => {
+    const speech = await a11y.press('Tab');
+    expect(speech).toBe('Submit, button');
+  });
+
+  test('checkbox announces checked state', async ({ a11y }) => {
+    await a11y.press('Tab');
+    await a11y.press('Tab');
+    const speech = await a11y.press('Space');
+    expect(speech).toContain('checkbox');
+    expect(speech).toContain('checked');
+  });
+
+  test('navigation landmark exists', async ({ a11y }) => {
+    const tree = await a11y.getFullTreeSpeech();
+    const nav = tree.find(r => r.speech.includes('navigation landmark'));
+    expect(nav).toBeDefined();
+  });
+});
+```
+
+### Unified State API
+
+The `pressKey()` method returns a complete `A11yState` snapshot combining speech output, focused element info, and focus indicator analysis:
+
+```typescript
+test('focus indicator meets WCAG 2.4.12 AA', async ({ page, a11y }) => {
+  await page.goto('/my-page.html');
+
+  const state = await a11y.pressKey('Tab');
+
+  // Speech
+  expect(state.speech).toContain('Submit');
+  expect(state.speechResult?.role).toBe('button');
+
+  // Focused element
+  expect(state.focusedElement?.tag).toBe('BUTTON');
+  expect(state.focusedElement?.id).toBe('submit-btn');
+  expect(state.focusedElement?.tabIndex).toBe(0);
+
+  // Focus indicator CSS analysis
+  expect(state.focusIndicator.isVisible).toBe(true);
+  expect(state.focusIndicator.contrastRatio).toBeGreaterThanOrEqual(3.0);
+  expect(state.focusIndicator.meetsWCAG_AA).toBe(true);
+});
+
+test('Shift+Tab navigates backward', async ({ page, a11y }) => {
+  await page.goto('/my-page.html');
+
+  await a11y.pressKey('Tab');
+  const state1 = await a11y.pressKey('Tab');
+  const state2 = await a11y.pressKey('Tab', { shift: true });
+
+  expect(state2.focusedElement?.id).toBe(state1.focusedElement?.id);
+});
+```
+
+### Tab Order and Keyboard Trap Detection
+
+```typescript
+test('page has correct tab order', async ({ page, a11y }) => {
+  await page.goto('/my-page.html');
+
+  const report = await a11y.traverseTabOrder();
+  expect(report.totalCount).toBeGreaterThan(0);
+  expect(report.entries[0].tag).toBe('A');
+});
+
+test('modal does not trap keyboard focus', async ({ page, a11y }) => {
+  await page.goto('/modal.html');
+
+  const result = await a11y.traverseSubTree('#modal-container', 20);
+  expect(result.isTrapped).toBe(false);
+  expect(result.escapeElement).not.toBeNull();
+});
+```
+
+### Audit and Issue Reporting
+
+Use `OracleAuditor` from `@a11y-oracle/audit-formatter` to automatically check WCAG rules on every interaction and accumulate any issues:
+
+```bash
+npm install -D @a11y-oracle/audit-formatter
+```
+
+```typescript
+import { test, expect } from '@a11y-oracle/playwright-plugin';
+import { OracleAuditor } from '@a11y-oracle/audit-formatter';
+
+test('all focus indicators pass oracle rules', async ({ page, a11y }) => {
+  await page.goto('/my-page.html');
+
+  const auditor = new OracleAuditor(a11y, {
+    project: 'my-app',
+    specName: 'navigation.spec.ts',
+  });
+
+  // Each pressKey() automatically checks all 5 state-based rules
+  await auditor.pressKey('Tab');
+  await auditor.pressKey('Tab');
+  await auditor.pressKey('Tab');
+
+  // checkTrap() automatically checks keyboard-trap
+  await auditor.checkTrap('#modal-container');
+
+  // Assert no issues found across all interactions
+  expect(auditor.getIssues()).toHaveLength(0);
+});
+```
+
+To write issues to a JSON report file at the end of the suite:
+
+```typescript
+import { test } from '@a11y-oracle/playwright-plugin';
+import { OracleAuditor, type OracleIssue } from '@a11y-oracle/audit-formatter';
+import * as fs from 'fs';
+
+const allIssues: OracleIssue[] = [];
+
+test('check page focus indicators', async ({ page, a11y }) => {
+  await page.goto('/my-page.html');
+  const auditor = new OracleAuditor(a11y, {
+    project: 'my-app',
+    specName: 'nav.spec.ts',
+  });
+
+  await auditor.pressKey('Tab');
+  await auditor.pressKey('Tab');
+  allIssues.push(...auditor.getIssues());
+});
+
+test.afterAll(() => {
+  if (allIssues.length > 0) {
+    fs.writeFileSync('oracle-results.json', JSON.stringify(allIssues, null, 2));
+  }
+});
+```
+
+For detailed remediation guidance on each rule, see the [Remediation Guide](../../docs/REMEDIATION.md).
+
+### Customizing Options
+
+Override speech engine options per test group using `test.use()`:
+
+```typescript
+test.describe('without landmark suffix', () => {
+  test.use({ a11yOptions: { includeLandmarks: false } });
+
+  test('nav role without landmark', async ({ page, a11y }) => {
+    await page.goto('/my-page.html');
+    const tree = await a11y.getFullTreeSpeech();
+    const nav = tree.find(r => r.role === 'navigation');
+    expect(nav?.speech).toBe('Main, navigation');
+  });
+});
+```
+
+Available options:
+
+| 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 |
+
+### Manual Usage
+
+If you need more control over the lifecycle (e.g., attaching to a specific page mid-test), use the `A11yOracle` class directly:
+
+```typescript
+import { A11yOracle } from '@a11y-oracle/playwright-plugin';
+import { test, expect } from '@playwright/test';
+
+test('manual setup', async ({ page }) => {
+  await page.goto('/my-page.html');
+
+  const a11y = new A11yOracle(page, { includeDescription: true });
+  await a11y.init();
+
+  const speech = await a11y.press('Tab');
+  expect(speech).toContain('button');
+
+  await a11y.dispose();
+});
+```
+
+## API Reference
+
+### `A11yOracle`
+
+Manages a CDP session and provides accessibility testing for the current page.
+
+#### `constructor(page: Page, options?: A11yOrchestratorOptions)`
+
+Create a new instance.
+
+- `page` — Playwright `Page` to attach to.
+- `options.includeLandmarks` — Append "landmark" to landmark roles. Default `true`.
+- `options.includeDescription` — Include description text. Default `false`.
+- `options.focusSettleMs` — Delay after key press for focus/CSS to settle. Default `50`.
+
+#### `init(): Promise<void>`
+
+Open a CDP session and enable the Accessibility domain. Must be called before any other method. The test fixture calls this automatically.
+
+#### Speech-Only API
+
+##### `press(key: string): Promise<string>`
+
+Press a keyboard key (via Playwright's `page.keyboard.press()`) and return the speech for the newly focused element. Returns an empty string if no element has focus.
+
+```typescript
+const speech = await a11y.press('Tab');
+// "Products, button, collapsed"
+```
+
+##### `getSpeech(): Promise<string>`
+
+Get the speech string for the currently focused element without pressing a key.
+
+##### `getSpeechResult(): Promise<SpeechResult | null>`
+
+Get the full structured result for the focused element.
+
+##### `getFullTreeSpeech(): Promise<SpeechResult[]>`
+
+Get speech for all non-ignored nodes in the accessibility tree.
+
+#### Unified State API
+
+##### `pressKey(key: string, modifiers?: ModifierKeys): Promise<A11yState>`
+
+Dispatch a key via native CDP `Input.dispatchKeyEvent` and return the unified accessibility state. Unlike `press()`, this uses hardware-level key dispatch and returns the full state.
+
+```typescript
+const state = await a11y.pressKey('Tab');
+// state.speech           → "Products, button, collapsed"
+// state.focusedElement   → { tag: 'BUTTON', id: '...', ... }
+// state.focusIndicator   → { isVisible: true, meetsWCAG_AA: true, ... }
+```
+
+##### `getA11yState(): Promise<A11yState>`
+
+Get the current unified state without pressing a key.
+
+```typescript
+await page.focus('#my-button');
+const state = await a11y.getA11yState();
+```
+
+##### `traverseTabOrder(): Promise<TabOrderReport>`
+
+Extract all tabbable elements in DOM tab order.
+
+##### `traverseSubTree(selector: string, maxTabs?: number): Promise<TraversalResult>`
+
+Detect whether a container traps keyboard focus (WCAG 2.1.2).
+
+#### Lifecycle
+
+##### `dispose(): Promise<void>`
+
+Detach the CDP session and free resources. The test fixture calls this automatically.
+
+### Test Fixture
+
+The `test` export extends Playwright's `test` with two fixtures:
+
+| Fixture | Type | Description |
+|---------|------|-------------|
+| `a11y` | `A11yOracle` | Initialized instance, auto-disposed after each test |
+| `a11yOptions` | `A11yOrchestratorOptions` | Override via `test.use()` |
+
+### Exports
+
+```typescript
+// Test fixture (recommended)
+export { test, expect } from '@a11y-oracle/playwright-plugin';
+
+// Manual usage
+export { A11yOracle } from '@a11y-oracle/playwright-plugin';
+
+// Fixture types
+export type { A11yOracleFixtures } from '@a11y-oracle/playwright-plugin';
+
+// Re-exported types from core-engine
+export type {
+  A11yState,
+  A11yFocusedElement,
+  A11yFocusIndicator,
+  A11yOrchestratorOptions,
+  SpeechResult,
+  SpeechEngineOptions,
+  ModifierKeys,
+  TabOrderReport,
+  TabOrderEntry,
+  TraversalResult,
+  FocusIndicator,
+} from '@a11y-oracle/playwright-plugin';
+```
+
+## Playwright Config
+
+The plugin requires Chromium. A typical `playwright.config.ts`:
+
+```typescript
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  use: {
+    baseURL: 'http://localhost:4200',
+  },
+  projects: [
+    {
+      name: 'chromium',
+      use: { browserName: 'chromium' },
+    },
+  ],
+  webServer: {
+    command: 'npm run serve',
+    url: 'http://localhost:4200',
+    reuseExistingServer: !process.env.CI,
+  },
+});
+```
+
+## How It Works
+
+1. The fixture opens a CDP session via `page.context().newCDPSession(page)`
+2. It creates both a `SpeechEngine` and an `A11yOrchestrator` on that session
+3. **`press(key)`** — Uses Playwright's keyboard API, waits 50ms, then reads the AXTree for speech
+4. **`pressKey(key)`** — Uses native CDP `Input.dispatchKeyEvent` for hardware-level dispatch, waits `focusSettleMs`, then collects speech + focused element + focus indicator in parallel
+5. Focus indicator analysis runs `Runtime.evaluate` to read computed CSS styles and calculate contrast ratios
+6. On dispose, the CDP session is detached
+
+The speech format follows: `[Computed Name], [Role], [State/Properties]`
+
+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,40 @@
+/**
+ * @module @a11y-oracle/playwright-plugin
+ *
+ * Playwright integration for A11y-Oracle. Provides a test fixture and
+ * wrapper class for asserting accessibility speech output in Playwright
+ * tests.
+ *
+ * ## Quick Start
+ *
+ * ```typescript
+ * import { test, expect } from '@a11y-oracle/playwright-plugin';
+ *
+ * test('button announces correctly', async ({ page, a11y }) => {
+ *   await page.goto('/my-page.html');
+ *   const speech = await a11y.press('Tab');
+ *   expect(speech).toBe('Submit, button');
+ * });
+ * ```
+ *
+ * ## Manual Usage
+ *
+ * ```typescript
+ * import { A11yOracle } from '@a11y-oracle/playwright-plugin';
+ * import { test, expect } from '@playwright/test';
+ *
+ * test('manual setup', async ({ page }) => {
+ *   const a11y = new A11yOracle(page);
+ *   await a11y.init();
+ *   // ... assertions ...
+ *   await a11y.dispose();
+ * });
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { A11yOracle } from './lib/a11y-oracle.js';
+export { test, expect } from './lib/fixture.js';
+export type { A11yOracleFixtures } from './lib/fixture.js';
+export type { A11yState, A11yFocusedElement, A11yFocusIndicator, A11yOrchestratorOptions, SpeechResult, SpeechEngineOptions, ModifierKeys, TabOrderReport, TabOrderEntry, TraversalResult, FocusIndicator, } from '@a11y-oracle/core-engine';
+//# 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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAChD,YAAY,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAG3D,YAAY,EACV,SAAS,EACT,kBAAkB,EAClB,kBAAkB,EAClB,uBAAuB,EACvB,YAAY,EACZ,mBAAmB,EACnB,YAAY,EACZ,cAAc,EACd,aAAa,EACb,eAAe,EACf,cAAc,GACf,MAAM,0BAA0B,CAAC"}

package/dist/index.js

@@ -0,0 +1,37 @@
+/**
+ * @module @a11y-oracle/playwright-plugin
+ *
+ * Playwright integration for A11y-Oracle. Provides a test fixture and
+ * wrapper class for asserting accessibility speech output in Playwright
+ * tests.
+ *
+ * ## Quick Start
+ *
+ * ```typescript
+ * import { test, expect } from '@a11y-oracle/playwright-plugin';
+ *
+ * test('button announces correctly', async ({ page, a11y }) => {
+ *   await page.goto('/my-page.html');
+ *   const speech = await a11y.press('Tab');
+ *   expect(speech).toBe('Submit, button');
+ * });
+ * ```
+ *
+ * ## Manual Usage
+ *
+ * ```typescript
+ * import { A11yOracle } from '@a11y-oracle/playwright-plugin';
+ * import { test, expect } from '@playwright/test';
+ *
+ * test('manual setup', async ({ page }) => {
+ *   const a11y = new A11yOracle(page);
+ *   await a11y.init();
+ *   // ... assertions ...
+ *   await a11y.dispose();
+ * });
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { A11yOracle } from './lib/a11y-oracle.js';
+export { test, expect } from './lib/fixture.js';

package/dist/lib/a11y-oracle.d.ts

@@ -0,0 +1,161 @@
+/**
+ * @module a11y-oracle
+ *
+ * Playwright wrapper around the core {@link SpeechEngine} and
+ * {@link A11yOrchestrator}. Manages the CDP session lifecycle and
+ * provides a clean API for accessibility speech and keyboard/focus
+ * assertions in Playwright tests.
+ *
+ * @example
+ * ```typescript
+ * import { A11yOracle } from '@a11y-oracle/playwright-plugin';
+ *
+ * const a11y = new A11yOracle(page);
+ * await a11y.init();
+ *
+ * // Speech-only API (backward compatible)
+ * const speech = await a11y.press('Tab');
+ * expect(speech).toBe('Products, button, collapsed');
+ *
+ * // Unified state API (new)
+ * const state = await a11y.pressKey('Tab');
+ * expect(state.speech).toContain('Products');
+ * expect(state.focusIndicator.meetsWCAG_AA).toBe(true);
+ *
+ * await a11y.dispose();
+ * ```
+ */
+import type { Page } from '@playwright/test';
+import type { SpeechResult, A11yState, A11yOrchestratorOptions, TabOrderReport, TraversalResult, ModifierKeys } from '@a11y-oracle/core-engine';
+/**
+ * Playwright wrapper that manages a CDP session and provides
+ * accessibility speech output and keyboard/focus analysis for the
+ * currently focused element.
+ *
+ * For most use cases, prefer the {@link test} fixture from the
+ * package root, which handles init/dispose automatically.
+ *
+ * ## CDP Requirement
+ *
+ * This class requires a Chromium-based browser. CDP sessions are
+ * not available for Firefox or WebKit in Playwright.
+ */
+export declare class A11yOracle {
+    private page;
+    private cdpSession;
+    private engine;
+    private orchestrator;
+    private options;
+    /**
+     * Create a new A11yOracle instance.
+     *
+     * @param page - The Playwright Page to attach to.
+     * @param options - Optional speech engine and orchestrator configuration.
+     */
+    constructor(page: Page, options?: A11yOrchestratorOptions);
+    /**
+     * Initialize the CDP session and enable the Accessibility domain.
+     *
+     * Must be called before any other method. The {@link test} fixture
+     * calls this automatically.
+     *
+     * @throws Error if the browser does not support CDP (e.g., Firefox).
+     */
+    init(): Promise<void>;
+    /**
+     * Press a keyboard key and return the speech for the newly focused element.
+     *
+     * Internally calls `page.keyboard.press(key)` followed by a short delay
+     * to allow the browser to update focus and ARIA states before reading
+     * the accessibility tree.
+     *
+     * @param key - The key to press (e.g., `'Tab'`, `'Enter'`, `'Escape'`).
+     *              Uses Playwright's key name format.
+     * @returns The speech string for the focused element after the key press,
+     *          or an empty string if no element has focus.
+     *
+     * @example
+     * ```typescript
+     * const speech = await a11y.press('Tab');
+     * expect(speech).toBe('Products, button, collapsed');
+     * ```
+     */
+    press(key: string): Promise<string>;
+    /**
+     * Get the speech string for the currently focused element.
+     *
+     * @returns The speech string (e.g., `"Products, button, collapsed"`),
+     *          or an empty string if no element has focus.
+     *
+     * @throws Error if {@link init} has not been called.
+     */
+    getSpeech(): Promise<string>;
+    /**
+     * Get the full {@link SpeechResult} for the currently focused element.
+     *
+     * @returns The full speech result, or `null` if no element has focus.
+     * @throws Error if {@link init} has not been called.
+     */
+    getSpeechResult(): Promise<SpeechResult | null>;
+    /**
+     * Get speech output for ALL non-ignored nodes in the accessibility tree.
+     *
+     * @returns Array of {@link SpeechResult} objects for every visible node.
+     * @throws Error if {@link init} has not been called.
+     */
+    getFullTreeSpeech(): Promise<SpeechResult[]>;
+    /**
+     * Dispatch a key via CDP and return the unified accessibility state.
+     *
+     * Unlike {@link press}, this uses native CDP key dispatch (not
+     * Playwright's keyboard API) and returns the full {@link A11yState}
+     * including speech, focused element info, and focus indicator analysis.
+     *
+     * @param key - Key name (e.g. `'Tab'`, `'Enter'`, `'ArrowDown'`).
+     * @param modifiers - Optional modifier keys (shift, ctrl, alt, meta).
+     * @returns Unified accessibility state snapshot.
+     *
+     * @example
+     * ```typescript
+     * const state = await a11y.pressKey('Tab');
+     * expect(state.speech).toContain('Products');
+     * expect(state.focusIndicator.meetsWCAG_AA).toBe(true);
+     * ```
+     */
+    pressKey(key: string, modifiers?: ModifierKeys): Promise<A11yState>;
+    /**
+     * Get the current unified accessibility state without pressing a key.
+     *
+     * @returns Unified accessibility state snapshot.
+     */
+    getA11yState(): Promise<A11yState>;
+    /**
+     * Alias for {@link getA11yState} that satisfies the
+     * {@link OrchestratorLike} interface from `@a11y-oracle/audit-formatter`.
+     *
+     * @returns Unified accessibility state snapshot.
+     */
+    getState(): Promise<A11yState>;
+    /**
+     * Extract all tabbable elements in DOM tab order.
+     *
+     * @returns Report with sorted tab order entries and total count.
+     */
+    traverseTabOrder(): Promise<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.
+     * @returns Traversal result indicating whether focus is trapped.
+     */
+    traverseSubTree(selector: string, maxTabs?: number): Promise<TraversalResult>;
+    /**
+     * Detach the CDP session and clean up resources.
+     *
+     * The {@link test} fixture calls this automatically after each test.
+     */
+    dispose(): Promise<void>;
+    private assertOrchestrator;
+}
+//# sourceMappingURL=a11y-oracle.d.ts.map

package/dist/lib/a11y-oracle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"a11y-oracle.d.ts","sourceRoot":"","sources":["../../src/lib/a11y-oracle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAc,MAAM,kBAAkB,CAAC;AAGzD,OAAO,KAAK,EACV,YAAY,EACZ,SAAS,EACT,uBAAuB,EACvB,cAAc,EACd,eAAe,EACf,YAAY,EACb,MAAM,0BAA0B,CAAC;AAElC;;;;;;;;;;;;GAYG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,IAAI,CAAO;IACnB,OAAO,CAAC,UAAU,CAA2B;IAC7C,OAAO,CAAC,MAAM,CAA6B;IAC3C,OAAO,CAAC,YAAY,CAAiC;IACrD,OAAO,CAAC,OAAO,CAA0B;IAEzC;;;;;OAKG;gBACS,IAAI,EAAE,IAAI,EAAE,OAAO,GAAE,uBAA4B;IAK7D;;;;;;;OAOG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAS3B;;;;;;;;;;;;;;;;;OAiBG;IACG,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAOzC;;;;;;;OAOG;IACG,SAAS,IAAI,OAAO,CAAC,MAAM,CAAC;IAKlC;;;;;OAKG;IACG,eAAe,IAAI,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IAOrD;;;;;OAKG;IACG,iBAAiB,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;IASlD;;;;;;;;;;;;;;;;;OAiBG;IACG,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,SAAS,CAAC;IAKzE;;;;OAIG;IACG,YAAY,IAAI,OAAO,CAAC,SAAS,CAAC;IAKxC;;;;;OAKG;IACG,QAAQ,IAAI,OAAO,CAAC,SAAS,CAAC;IAIpC;;;;OAIG;IACG,gBAAgB,IAAI,OAAO,CAAC,cAAc,CAAC;IAKjD;;;;;;OAMG;IACG,eAAe,CACnB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,eAAe,CAAC;IAO3B;;;;OAIG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAY9B,OAAO,CAAC,kBAAkB;CAK3B"}

package/dist/lib/a11y-oracle.js

@@ -0,0 +1,217 @@
+/**
+ * @module a11y-oracle
+ *
+ * Playwright wrapper around the core {@link SpeechEngine} and
+ * {@link A11yOrchestrator}. Manages the CDP session lifecycle and
+ * provides a clean API for accessibility speech and keyboard/focus
+ * assertions in Playwright tests.
+ *
+ * @example
+ * ```typescript
+ * import { A11yOracle } from '@a11y-oracle/playwright-plugin';
+ *
+ * const a11y = new A11yOracle(page);
+ * await a11y.init();
+ *
+ * // Speech-only API (backward compatible)
+ * const speech = await a11y.press('Tab');
+ * expect(speech).toBe('Products, button, collapsed');
+ *
+ * // Unified state API (new)
+ * const state = await a11y.pressKey('Tab');
+ * expect(state.speech).toContain('Products');
+ * expect(state.focusIndicator.meetsWCAG_AA).toBe(true);
+ *
+ * await a11y.dispose();
+ * ```
+ */
+import { SpeechEngine } from '@a11y-oracle/core-engine';
+import { A11yOrchestrator } from '@a11y-oracle/core-engine';
+/**
+ * Playwright wrapper that manages a CDP session and provides
+ * accessibility speech output and keyboard/focus analysis for the
+ * currently focused element.
+ *
+ * For most use cases, prefer the {@link test} fixture from the
+ * package root, which handles init/dispose automatically.
+ *
+ * ## CDP Requirement
+ *
+ * This class requires a Chromium-based browser. CDP sessions are
+ * not available for Firefox or WebKit in Playwright.
+ */
+export class A11yOracle {
+    page;
+    cdpSession = null;
+    engine = null;
+    orchestrator = null;
+    options;
+    /**
+     * Create a new A11yOracle instance.
+     *
+     * @param page - The Playwright Page to attach to.
+     * @param options - Optional speech engine and orchestrator configuration.
+     */
+    constructor(page, options = {}) {
+        this.page = page;
+        this.options = options;
+    }
+    /**
+     * Initialize the CDP session and enable the Accessibility domain.
+     *
+     * Must be called before any other method. The {@link test} fixture
+     * calls this automatically.
+     *
+     * @throws Error if the browser does not support CDP (e.g., Firefox).
+     */
+    async init() {
+        this.cdpSession = await this.page.context().newCDPSession(this.page);
+        this.engine = new SpeechEngine(this.cdpSession, this.options);
+        this.orchestrator = new A11yOrchestrator(this.cdpSession, this.options);
+        await this.orchestrator.enable();
+    }
+    // ── Speech-only API (backward compatible) ──────────────────────
+    /**
+     * Press a keyboard key and return the speech for the newly focused element.
+     *
+     * Internally calls `page.keyboard.press(key)` followed by a short delay
+     * to allow the browser to update focus and ARIA states before reading
+     * the accessibility tree.
+     *
+     * @param key - The key to press (e.g., `'Tab'`, `'Enter'`, `'Escape'`).
+     *              Uses Playwright's key name format.
+     * @returns The speech string for the focused element after the key press,
+     *          or an empty string if no element has focus.
+     *
+     * @example
+     * ```typescript
+     * const speech = await a11y.press('Tab');
+     * expect(speech).toBe('Products, button, collapsed');
+     * ```
+     */
+    async press(key) {
+        await this.page.keyboard.press(key);
+        // Allow browser to update focus and ARIA states
+        await this.page.waitForTimeout(50);
+        return this.getSpeech();
+    }
+    /**
+     * Get the speech string for the currently focused element.
+     *
+     * @returns The speech string (e.g., `"Products, button, collapsed"`),
+     *          or an empty string if no element has focus.
+     *
+     * @throws Error if {@link init} has not been called.
+     */
+    async getSpeech() {
+        const result = await this.getSpeechResult();
+        return result?.speech ?? '';
+    }
+    /**
+     * Get the full {@link SpeechResult} for the currently focused element.
+     *
+     * @returns The full speech result, or `null` if no element has focus.
+     * @throws Error if {@link init} has not been called.
+     */
+    async getSpeechResult() {
+        if (!this.engine) {
+            throw new Error('A11yOracle not initialized. Call init() first.');
+        }
+        return this.engine.getSpeech();
+    }
+    /**
+     * Get speech output for ALL non-ignored nodes in the accessibility tree.
+     *
+     * @returns Array of {@link SpeechResult} objects for every visible node.
+     * @throws Error if {@link init} has not been called.
+     */
+    async getFullTreeSpeech() {
+        if (!this.engine) {
+            throw new Error('A11yOracle not initialized. Call init() first.');
+        }
+        return this.engine.getFullTreeSpeech();
+    }
+    // ── Unified state API (new) ────────────────────────────────────
+    /**
+     * Dispatch a key via CDP and return the unified accessibility state.
+     *
+     * Unlike {@link press}, this uses native CDP key dispatch (not
+     * Playwright's keyboard API) and returns the full {@link A11yState}
+     * including speech, focused element info, and focus indicator analysis.
+     *
+     * @param key - Key name (e.g. `'Tab'`, `'Enter'`, `'ArrowDown'`).
+     * @param modifiers - Optional modifier keys (shift, ctrl, alt, meta).
+     * @returns Unified accessibility state snapshot.
+     *
+     * @example
+     * ```typescript
+     * const state = await a11y.pressKey('Tab');
+     * expect(state.speech).toContain('Products');
+     * expect(state.focusIndicator.meetsWCAG_AA).toBe(true);
+     * ```
+     */
+    async pressKey(key, modifiers) {
+        this.assertOrchestrator();
+        return this.orchestrator.pressKey(key, modifiers);
+    }
+    /**
+     * Get the current unified accessibility state without pressing a key.
+     *
+     * @returns Unified accessibility state snapshot.
+     */
+    async getA11yState() {
+        this.assertOrchestrator();
+        return this.orchestrator.getState();
+    }
+    /**
+     * Alias for {@link getA11yState} that satisfies the
+     * {@link OrchestratorLike} interface from `@a11y-oracle/audit-formatter`.
+     *
+     * @returns Unified accessibility state snapshot.
+     */
+    async getState() {
+        return this.getA11yState();
+    }
+    /**
+     * Extract all tabbable elements in DOM tab order.
+     *
+     * @returns Report with sorted tab order entries and total count.
+     */
+    async traverseTabOrder() {
+        this.assertOrchestrator();
+        return this.orchestrator.traverseTabOrder();
+    }
+    /**
+     * 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.
+     * @returns Traversal result indicating whether focus is trapped.
+     */
+    async traverseSubTree(selector, maxTabs) {
+        this.assertOrchestrator();
+        return this.orchestrator.traverseSubTree(selector, maxTabs);
+    }
+    // ── Lifecycle ──────────────────────────────────────────────────
+    /**
+     * Detach the CDP session and clean up resources.
+     *
+     * The {@link test} fixture calls this automatically after each test.
+     */
+    async dispose() {
+        if (this.orchestrator) {
+            await this.orchestrator.disable();
+            this.orchestrator = null;
+        }
+        if (this.cdpSession) {
+            await this.cdpSession.detach();
+            this.cdpSession = null;
+            this.engine = null;
+        }
+    }
+    assertOrchestrator() {
+        if (!this.orchestrator) {
+            throw new Error('A11yOracle not initialized. Call init() first.');
+        }
+    }
+}

package/dist/lib/fixture.d.ts

@@ -0,0 +1,68 @@
+/**
+ * @module fixture
+ *
+ * Playwright test fixture that provides an automatically managed
+ * {@link A11yOracle} instance as the `a11y` fixture parameter.
+ *
+ * @example
+ * ```typescript
+ * import { test, expect } from '@a11y-oracle/playwright-plugin';
+ *
+ * test('navigation announces correctly', async ({ page, a11y }) => {
+ *   await page.goto('/dropdown-nav.html');
+ *
+ *   const speech = await a11y.press('Tab');
+ *   expect(speech).toBe('Products, button, collapsed');
+ * });
+ * ```
+ */
+import { A11yOracle } from './a11y-oracle.js';
+import type { A11yOrchestratorOptions } from '@a11y-oracle/core-engine';
+/**
+ * Type definition for the A11y-Oracle Playwright fixtures.
+ *
+ * - `a11y`: An initialized {@link A11yOracle} instance, ready to use.
+ * - `a11yOptions`: Configuration options for the orchestrator (speech engine
+ *   and focus analysis). Override in `test.use()` to customize behavior.
+ */
+export type A11yOracleFixtures = {
+    /** An initialized A11yOracle instance for the current page. */
+    a11y: A11yOracle;
+    /** Orchestrator options. Override via `test.use({ a11yOptions: { ... } })`. */
+    a11yOptions: A11yOrchestratorOptions;
+};
+/**
+ * Extended Playwright test with the `a11y` fixture.
+ *
+ * The fixture automatically:
+ * 1. Creates a new {@link A11yOracle} instance for each test
+ * 2. Initializes the CDP session
+ * 3. Disposes the session after the test completes
+ *
+ * @example
+ * ```typescript
+ * import { test, expect } from '@a11y-oracle/playwright-plugin';
+ *
+ * test('button announces name and role', async ({ page, a11y }) => {
+ *   await page.goto('/my-page.html');
+ *   await a11y.press('Tab');
+ *   expect(await a11y.getSpeech()).toBe('Submit, button');
+ * });
+ *
+ * // Customize options for a test group:
+ * test.describe('without landmarks', () => {
+ *   test.use({ a11yOptions: { includeLandmarks: false } });
+ *
+ *   test('nav without landmark suffix', async ({ page, a11y }) => {
+ *     await page.goto('/my-page.html');
+ *     const all = await a11y.getFullTreeSpeech();
+ *     const nav = all.find(r => r.role === 'navigation');
+ *     expect(nav?.speech).toBe('Main, navigation');
+ *   });
+ * });
+ * ```
+ */
+export declare const test: import("@playwright/test").TestType<import("@playwright/test").PlaywrightTestArgs & import("@playwright/test").PlaywrightTestOptions & A11yOracleFixtures, import("@playwright/test").PlaywrightWorkerArgs & import("@playwright/test").PlaywrightWorkerOptions>;
+/** Re-export Playwright's expect for convenience. */
+export { expect } from '@playwright/test';
+//# sourceMappingURL=fixture.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fixture.d.ts","sourceRoot":"","sources":["../../src/lib/fixture.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AAExE;;;;;;GAMG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,+DAA+D;IAC/D,IAAI,EAAE,UAAU,CAAC;IACjB,+EAA+E;IAC/E,WAAW,EAAE,uBAAuB,CAAC;CACtC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,IAAI,kQAUf,CAAC;AAEH,qDAAqD;AACrD,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/lib/fixture.js

@@ -0,0 +1,63 @@
+/**
+ * @module fixture
+ *
+ * Playwright test fixture that provides an automatically managed
+ * {@link A11yOracle} instance as the `a11y` fixture parameter.
+ *
+ * @example
+ * ```typescript
+ * import { test, expect } from '@a11y-oracle/playwright-plugin';
+ *
+ * test('navigation announces correctly', async ({ page, a11y }) => {
+ *   await page.goto('/dropdown-nav.html');
+ *
+ *   const speech = await a11y.press('Tab');
+ *   expect(speech).toBe('Products, button, collapsed');
+ * });
+ * ```
+ */
+import { test as base } from '@playwright/test';
+import { A11yOracle } from './a11y-oracle.js';
+/**
+ * Extended Playwright test with the `a11y` fixture.
+ *
+ * The fixture automatically:
+ * 1. Creates a new {@link A11yOracle} instance for each test
+ * 2. Initializes the CDP session
+ * 3. Disposes the session after the test completes
+ *
+ * @example
+ * ```typescript
+ * import { test, expect } from '@a11y-oracle/playwright-plugin';
+ *
+ * test('button announces name and role', async ({ page, a11y }) => {
+ *   await page.goto('/my-page.html');
+ *   await a11y.press('Tab');
+ *   expect(await a11y.getSpeech()).toBe('Submit, button');
+ * });
+ *
+ * // Customize options for a test group:
+ * test.describe('without landmarks', () => {
+ *   test.use({ a11yOptions: { includeLandmarks: false } });
+ *
+ *   test('nav without landmark suffix', async ({ page, a11y }) => {
+ *     await page.goto('/my-page.html');
+ *     const all = await a11y.getFullTreeSpeech();
+ *     const nav = all.find(r => r.role === 'navigation');
+ *     expect(nav?.speech).toBe('Main, navigation');
+ *   });
+ * });
+ * ```
+ */
+export const test = base.extend({
+    // Default options (empty = use engine defaults)
+    a11yOptions: [{}, { option: true }],
+    a11y: async ({ page, a11yOptions }, use) => {
+        const a11y = new A11yOracle(page, a11yOptions);
+        await a11y.init();
+        await use(a11y);
+        await a11y.dispose();
+    },
+});
+/** Re-export Playwright's expect for convenience. */
+export { expect } from '@playwright/test';

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@a11y-oracle/playwright-plugin",
+  "version": "1.0.0",
+  "description": "Playwright test fixture for accessibility speech assertions, keyboard navigation, and focus indicator validation",
+  "license": "MIT",
+  "author": "a11y-oracle",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/a11y-oracle/a11y-oracle.git",
+    "directory": "libs/playwright-plugin"
+  },
+  "bugs": {
+    "url": "https://github.com/a11y-oracle/a11y-oracle/issues"
+  },
+  "homepage": "https://github.com/a11y-oracle/a11y-oracle/tree/main/libs/playwright-plugin",
+  "keywords": [
+    "accessibility",
+    "a11y",
+    "playwright",
+    "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": {
+    "@playwright/test": ">=1.40.0"
+  },
+  "dependencies": {
+    "@a11y-oracle/core-engine": "1.0.0",
+    "tslib": "^2.3.0"
+  }
+}