@a11y-oracle/core-engine 1.0.0

package/dist/lib/a11y-orchestrator.js

@@ -0,0 +1,170 @@
+/**
+ * @module a11y-orchestrator
+ *
+ * Coordinates the three sub-engines (Speech, Keyboard, Focus) into a
+ * single `pressKey()` → unified-state workflow.
+ *
+ * @example
+ * ```typescript
+ * import { A11yOrchestrator } from '@a11y-oracle/core-engine';
+ *
+ * const oracle = new A11yOrchestrator(cdpSession);
+ * await oracle.enable();
+ *
+ * const state = await oracle.pressKey('Tab');
+ * console.log(state.speech);                       // "Products, button, collapsed"
+ * console.log(state.focusedElement?.tag);           // "BUTTON"
+ * console.log(state.focusIndicator.meetsWCAG_AA);  // true
+ * ```
+ */
+import { SpeechEngine } from './speech-engine.js';
+import { KeyboardEngine } from '@a11y-oracle/keyboard-engine';
+import { FocusAnalyzer } from '@a11y-oracle/focus-analyzer';
+/**
+ * Orchestrates speech, keyboard dispatch, and focus analysis into a
+ * unified accessibility testing API.
+ *
+ * A single `pressKey()` call dispatches a keystroke, waits for focus
+ * to settle, then collects speech output, focused element info, and
+ * focus indicator analysis in parallel.
+ *
+ * ## Sub-engines
+ *
+ * | Engine | Responsibility |
+ * |--------|---------------|
+ * | {@link SpeechEngine} | AXTree → speech string |
+ * | {@link KeyboardEngine} | CDP key dispatch + `document.activeElement` |
+ * | {@link FocusAnalyzer} | CSS focus indicator + tab order + trap detection |
+ */
+export class A11yOrchestrator {
+    speech;
+    keyboard;
+    focusAnalyzer;
+    options;
+    /**
+     * @param cdp - CDP session for sending protocol commands.
+     * @param options - Optional configuration for speech output and focus settling.
+     */
+    constructor(cdp, options = {}) {
+        this.speech = new SpeechEngine(cdp, options);
+        this.keyboard = new KeyboardEngine(cdp);
+        this.focusAnalyzer = new FocusAnalyzer(cdp);
+        this.options = {
+            includeLandmarks: options.includeLandmarks ?? true,
+            includeDescription: options.includeDescription ?? false,
+            focusSettleMs: options.focusSettleMs ?? 50,
+        };
+    }
+    /**
+     * Enable the CDP Accessibility domain.
+     *
+     * Must be called before any other method.
+     */
+    async enable() {
+        await this.speech.enable();
+    }
+    /**
+     * Disable the CDP Accessibility domain.
+     *
+     * Call this when done to free browser resources.
+     */
+    async disable() {
+        await this.speech.disable();
+    }
+    /**
+     * Dispatch a key press and return the unified accessibility state.
+     *
+     * 1. Dispatches `keyDown` + `keyUp` via CDP `Input.dispatchKeyEvent`.
+     * 2. Waits {@link A11yOrchestratorOptions.focusSettleMs} for transitions.
+     * 3. Collects speech, focused element, and focus indicator **in parallel**.
+     *
+     * @param key - Key name (e.g. `'Tab'`, `'Enter'`, `'ArrowDown'`).
+     * @param modifiers - Optional modifier keys.
+     * @returns Unified accessibility state snapshot.
+     *
+     * @example
+     * ```typescript
+     * const state = await orchestrator.pressKey('Tab');
+     * expect(state.speech).toBe('Products, button, collapsed');
+     * expect(state.focusIndicator.meetsWCAG_AA).toBe(true);
+     * ```
+     */
+    async pressKey(key, modifiers) {
+        await this.keyboard.press(key, modifiers);
+        // Wait for focus transitions and CSS animations to settle
+        if (this.options.focusSettleMs > 0) {
+            await new Promise((resolve) => setTimeout(resolve, this.options.focusSettleMs));
+        }
+        return this.getState();
+    }
+    /**
+     * Get the current unified accessibility state without pressing a key.
+     *
+     * Collects speech, focused element, and focus indicator in parallel.
+     *
+     * @returns Unified accessibility state snapshot.
+     */
+    async getState() {
+        const [speechResult, focusedElementInfo, focusIndicator] = await Promise.all([
+            this.speech.getSpeech(),
+            this.keyboard.getFocusedElement(),
+            this.focusAnalyzer.getFocusIndicator(),
+        ]);
+        const focusedElement = focusedElementInfo
+            ? this.mapFocusedElement(focusedElementInfo)
+            : null;
+        const a11yFocusIndicator = {
+            isVisible: focusIndicator.isVisible,
+            contrastRatio: focusIndicator.contrastRatio,
+            meetsWCAG_AA: focusIndicator.meetsWCAG_AA,
+        };
+        return {
+            speech: speechResult?.speech ?? '',
+            speechResult,
+            focusedElement,
+            focusIndicator: a11yFocusIndicator,
+        };
+    }
+    /**
+     * Extract all tabbable elements in DOM tab order.
+     *
+     * @returns Report with sorted tab order entries and total count.
+     */
+    async traverseTabOrder() {
+        const entries = await this.focusAnalyzer.getTabOrder();
+        return {
+            entries,
+            totalCount: entries.length,
+        };
+    }
+    /**
+     * Detect whether a container traps keyboard focus.
+     *
+     * Focuses the first tabbable element in the container, then
+     * presses Tab repeatedly. If focus never escapes after `maxTabs`
+     * presses, the container is a keyboard trap (WCAG 2.1.2 failure).
+     *
+     * @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) {
+        return this.focusAnalyzer.detectKeyboardTrap(selector, maxTabs);
+    }
+    /**
+     * Map a raw `FocusedElementInfo` from keyboard-engine to the
+     * orchestrator's `A11yFocusedElement` shape.
+     */
+    mapFocusedElement(info) {
+        return {
+            tag: info.tag,
+            id: info.id,
+            className: info.className,
+            textContent: info.textContent,
+            role: info.role,
+            ariaLabel: info.ariaLabel,
+            tabIndex: info.tabIndex,
+            rect: info.rect,
+        };
+    }
+}

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

@@ -0,0 +1,41 @@
+/**
+ * @module role-map
+ *
+ * Maps Chrome DevTools Protocol AXTree role values to human-readable
+ * speech role strings.
+ *
+ * CDP already maps HTML elements to their implicit ARIA roles (e.g.,
+ * `<button>` → `"button"`, `<nav>` → `"navigation"`). This module
+ * translates those internal role names to the strings that appear in
+ * the final speech output.
+ *
+ * Unknown roles pass through as-is, ensuring forward compatibility
+ * with new ARIA roles.
+ */
+/**
+ * Maps CDP AXTree `role.value` strings to speech output role strings.
+ *
+ * Keys are the role values returned by `Accessibility.getFullAXTree()`.
+ * Values are the corresponding human-readable strings used in speech
+ * output.
+ *
+ * Roles that map to an empty string (`''`) are silent — they produce
+ * no role announcement in the speech output.
+ *
+ * @example
+ * ```typescript
+ * ROLE_TO_SPEECH['button']     // → 'button'
+ * ROLE_TO_SPEECH['navigation'] // → 'navigation'
+ * ROLE_TO_SPEECH['generic']    // → '' (silent)
+ * ```
+ */
+export declare const ROLE_TO_SPEECH: Record<string, string>;
+/**
+ * Set of roles classified as "landmark" roles.
+ *
+ * When a node has a landmark role, the word `"landmark"` is appended
+ * to its speech output. For example, a `<nav>` element produces
+ * `"Main, navigation landmark"` rather than just `"Main, navigation"`.
+ */
+export declare const LANDMARK_ROLES: Set<string>;
+//# sourceMappingURL=role-map.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"role-map.d.ts","sourceRoot":"","sources":["../../src/lib/role-map.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAkFjD,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,aASzB,CAAC"}

package/dist/lib/role-map.js

@@ -0,0 +1,128 @@
+/**
+ * @module role-map
+ *
+ * Maps Chrome DevTools Protocol AXTree role values to human-readable
+ * speech role strings.
+ *
+ * CDP already maps HTML elements to their implicit ARIA roles (e.g.,
+ * `<button>` → `"button"`, `<nav>` → `"navigation"`). This module
+ * translates those internal role names to the strings that appear in
+ * the final speech output.
+ *
+ * Unknown roles pass through as-is, ensuring forward compatibility
+ * with new ARIA roles.
+ */
+/**
+ * Maps CDP AXTree `role.value` strings to speech output role strings.
+ *
+ * Keys are the role values returned by `Accessibility.getFullAXTree()`.
+ * Values are the corresponding human-readable strings used in speech
+ * output.
+ *
+ * Roles that map to an empty string (`''`) are silent — they produce
+ * no role announcement in the speech output.
+ *
+ * @example
+ * ```typescript
+ * ROLE_TO_SPEECH['button']     // → 'button'
+ * ROLE_TO_SPEECH['navigation'] // → 'navigation'
+ * ROLE_TO_SPEECH['generic']    // → '' (silent)
+ * ```
+ */
+export const ROLE_TO_SPEECH = {
+    // ─── Interactive widget roles ───
+    button: 'button',
+    link: 'link',
+    checkbox: 'checkbox',
+    radio: 'radio button',
+    textbox: 'edit text',
+    combobox: 'combo box',
+    slider: 'slider',
+    switch: 'switch',
+    tab: 'tab',
+    menuitem: 'menu item',
+    menuitemcheckbox: 'menu item checkbox',
+    menuitemradio: 'menu item radio',
+    option: 'option',
+    searchbox: 'search text',
+    spinbutton: 'spin button',
+    // ─── Landmark roles ───
+    navigation: 'navigation',
+    main: 'main',
+    banner: 'banner',
+    contentinfo: 'content info',
+    complementary: 'complementary',
+    search: 'search',
+    region: 'region',
+    form: 'form',
+    // ─── Document structure roles ───
+    heading: 'heading',
+    list: 'list',
+    listitem: 'list item',
+    img: 'image',
+    figure: 'figure',
+    table: 'table',
+    row: 'row',
+    cell: 'cell',
+    columnheader: 'column header',
+    rowheader: 'row header',
+    grid: 'grid',
+    gridcell: 'grid cell',
+    tree: 'tree',
+    treeitem: 'tree item',
+    tablist: 'tab list',
+    tabpanel: 'tab panel',
+    menu: 'menu',
+    menubar: 'menu bar',
+    toolbar: 'toolbar',
+    dialog: 'dialog',
+    alertdialog: 'alert dialog',
+    alert: 'alert',
+    status: 'status',
+    progressbar: 'progress bar',
+    separator: 'separator',
+    group: 'group',
+    article: 'article',
+    definition: 'definition',
+    term: 'term',
+    note: 'note',
+    log: 'log',
+    marquee: 'marquee',
+    timer: 'timer',
+    tooltip: 'tooltip',
+    feed: 'feed',
+    math: 'math',
+    directory: 'directory',
+    document: 'document',
+    application: 'application',
+    // ─── Silent roles (no spoken role) ───
+    generic: '',
+    none: '',
+    presentation: '',
+    StaticText: '',
+    InlineTextBox: '',
+    LineBreak: '',
+    RootWebArea: '',
+    WebArea: '',
+    paragraph: '',
+    DescriptionListDetail: '',
+    DescriptionListTerm: '',
+    DescriptionList: '',
+};
+/**
+ * Set of roles classified as "landmark" roles.
+ *
+ * When a node has a landmark role, the word `"landmark"` is appended
+ * to its speech output. For example, a `<nav>` element produces
+ * `"Main, navigation landmark"` rather than just `"Main, navigation"`.
+ */
+export const LANDMARK_ROLES = new Set([
+    'navigation',
+    'main',
+    'banner',
+    'contentinfo',
+    'complementary',
+    'search',
+    'region',
+    'form',
+]);

package/dist/lib/speech-engine.d.ts

@@ -0,0 +1,149 @@
+/**
+ * @module speech-engine
+ *
+ * The central class of A11y-Oracle. {@link SpeechEngine} connects to the
+ * browser's Accessibility Tree via the Chrome DevTools Protocol and generates
+ * standardized speech output following the format:
+ *
+ * ```
+ * [Computed Name], [Role], [State/Properties]
+ * ```
+ *
+ * Chrome's CDP already computes accessible names per the W3C AccName spec,
+ * so the engine's job is to:
+ * 1. Fetch the AXTree via `Accessibility.getFullAXTree()`
+ * 2. Find the currently focused node
+ * 3. Map the node's role and properties to human-readable strings
+ * 4. Assemble the final speech string
+ *
+ * @example
+ * ```typescript
+ * import { SpeechEngine } from '@a11y-oracle/core-engine';
+ *
+ * const engine = new SpeechEngine(cdpSession);
+ * await engine.enable();
+ *
+ * const result = await engine.getSpeech();
+ * console.log(result?.speech); // "Products, button, collapsed"
+ * ```
+ */
+import type { Protocol } from 'devtools-protocol';
+import type { CDPSessionLike, SpeechEngineOptions, SpeechResult } from './types.js';
+/**
+ * Generates standardized speech output from the browser's Accessibility Tree.
+ *
+ * The engine operates through a {@link CDPSessionLike} interface, making it
+ * framework-agnostic. It works with Playwright's CDP sessions, raw WebSocket
+ * connections, or any other CDP-compatible client.
+ *
+ * ## Speech Output Format
+ *
+ * Every element produces a string in this format:
+ * ```
+ * [Computed Name], [Role], [State/Properties]
+ * ```
+ *
+ * Parts are omitted if they are empty. For example:
+ * - `"Products, button, collapsed"` — name + role + state
+ * - `"Main, navigation landmark"` — name + role (landmark)
+ * - `"Home, link"` — name + role (no states)
+ *
+ * ## Landmark Roles
+ *
+ * Landmark roles (navigation, main, banner, etc.) automatically append
+ * the word "landmark" to their role string unless
+ * {@link SpeechEngineOptions.includeLandmarks} is set to `false`.
+ */
+export declare class SpeechEngine {
+    private cdp;
+    private options;
+    /**
+     * Create a new SpeechEngine instance.
+     *
+     * @param cdp - A CDP session-like object for sending protocol commands.
+     * @param options - Optional configuration for speech output behavior.
+     */
+    constructor(cdp: CDPSessionLike, options?: SpeechEngineOptions);
+    /**
+     * Enable the CDP Accessibility domain.
+     *
+     * Must be called before any other method. Enables the browser to
+     * start tracking and reporting accessibility tree data.
+     */
+    enable(): Promise<void>;
+    /**
+     * Disable the CDP Accessibility domain.
+     *
+     * Call this when you're done using the engine to free browser resources.
+     */
+    disable(): Promise<void>;
+    /**
+     * Get the speech output for the currently focused element.
+     *
+     * Fetches the full AXTree, locates the node with `focused: true`,
+     * and computes its speech string.
+     *
+     * @returns The {@link SpeechResult} for the focused element, or `null`
+     *          if no element has focus or the focused element is ignored.
+     *
+     * @example
+     * ```typescript
+     * // After pressing Tab to focus a button
+     * const result = await engine.getSpeech();
+     * console.log(result?.speech); // "Products, button, collapsed"
+     * console.log(result?.name);   // "Products"
+     * console.log(result?.role);   // "button"
+     * console.log(result?.states); // ["collapsed"]
+     * ```
+     */
+    getSpeech(): Promise<SpeechResult | null>;
+    /**
+     * Get speech output for ALL non-ignored, non-silent nodes in the tree.
+     *
+     * Useful for asserting on landmarks, headings, or other structural
+     * elements that may not have focus.
+     *
+     * @returns An array of {@link SpeechResult} objects for every visible
+     *          node that produces speech output.
+     *
+     * @example
+     * ```typescript
+     * const all = await engine.getFullTreeSpeech();
+     * const nav = all.find(r => r.speech === 'Main, navigation landmark');
+     * expect(nav).toBeDefined();
+     * ```
+     */
+    getFullTreeSpeech(): Promise<SpeechResult[]>;
+    /**
+     * Find the most specific focused node in the flat AXTree node list.
+     *
+     * CDP returns the AXTree as a flat array with the document node first
+     * and more specific nodes later. Multiple nodes can report `focused: true`
+     * (e.g., both the RootWebArea and the actual focused element). This method
+     * returns the **last** focused node, which is the most specific (deepest)
+     * element that actually has user focus.
+     *
+     * @param nodes - The flat array of AXNodes from `getFullAXTree()`.
+     * @returns The most specific focused node, or `null` if no node is focused.
+     */
+    findFocusedNode(nodes: Protocol.Accessibility.AXNode[]): Protocol.Accessibility.AXNode | null;
+    /**
+     * Compute the speech string for a single AXNode.
+     *
+     * Follows the output format: `[Computed Name], [Role], [State/Properties]`.
+     * Parts are omitted when empty. Ignored nodes and nodes with no
+     * meaningful content return `null`.
+     *
+     * @param node - A CDP AXNode from the accessibility tree.
+     * @returns A {@link SpeechResult} with the computed speech, or `null`
+     *          if the node should be silent (ignored, no role, no name).
+     *
+     * @example
+     * ```typescript
+     * const result = engine.computeSpeech(axNode);
+     * // { speech: "Products, button, collapsed", name: "Products", ... }
+     * ```
+     */
+    computeSpeech(node: Protocol.Accessibility.AXNode): SpeechResult | null;
+}
+//# sourceMappingURL=speech-engine.d.ts.map

package/dist/lib/speech-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"speech-engine.d.ts","sourceRoot":"","sources":["../../src/lib/speech-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,KAAK,EAAE,cAAc,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAKpF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,GAAG,CAAiB;IAC5B,OAAO,CAAC,OAAO,CAAgC;IAE/C;;;;;OAKG;gBACS,GAAG,EAAE,cAAc,EAAE,OAAO,GAAE,mBAAwB;IAQlE;;;;;OAKG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAI7B;;;;OAIG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAI9B;;;;;;;;;;;;;;;;;;OAkBG;IACG,SAAS,IAAI,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IAO/C;;;;;;;;;;;;;;;OAeG;IACG,iBAAiB,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;IAOlD;;;;;;;;;;;OAWG;IACH,eAAe,CACb,KAAK,EAAE,QAAQ,CAAC,aAAa,CAAC,MAAM,EAAE,GACrC,QAAQ,CAAC,aAAa,CAAC,MAAM,GAAG,IAAI;IAWvC;;;;;;;;;;;;;;;;OAgBG;IACH,aAAa,CAAC,IAAI,EAAE,QAAQ,CAAC,aAAa,CAAC,MAAM,GAAG,YAAY,GAAG,IAAI;CA6CxE"}