@a11y-oracle/focus-analyzer 1.0.0

package/README.md

@@ -0,0 +1,204 @@
+# @a11y-oracle/focus-analyzer
+
+Focus state analysis for accessibility testing. Provides visual focus indicator inspection, WCAG contrast ratio calculation, DOM tab order extraction, and keyboard trap detection.
+
+This is a low-level building block used internally by `@a11y-oracle/core-engine`. Most users should use the Playwright or Cypress plugin instead.
+
+## Installation
+
+```bash
+npm install @a11y-oracle/focus-analyzer
+```
+
+## Usage
+
+```typescript
+import { FocusAnalyzer } from '@a11y-oracle/focus-analyzer';
+
+const analyzer = new FocusAnalyzer(cdpSession);
+
+// Analyze the focus indicator on the currently focused element
+const indicator = await analyzer.getFocusIndicator();
+console.log(indicator.isVisible);     // true
+console.log(indicator.contrastRatio); // 12.63
+console.log(indicator.meetsWCAG_AA);  // true (visible + contrast >= 3.0)
+console.log(indicator.outlineColor);  // "rgb(0, 95, 204)"
+console.log(indicator.outlineWidth);  // "3px"
+
+// Extract all tabbable elements in DOM tab order
+const entries = await analyzer.getTabOrder();
+entries.forEach(e => {
+  console.log(`${e.index}: ${e.tag}#${e.id} (tabIndex=${e.tabIndex})`);
+});
+
+// Detect keyboard traps (WCAG 2.1.2)
+const result = await analyzer.detectKeyboardTrap('#modal-container', 20);
+if (result.isTrapped) {
+  console.log('Focus is trapped!');
+} else {
+  console.log(`Focus escaped to: ${result.escapeElement?.tag}`);
+}
+```
+
+## API Reference
+
+### `FocusAnalyzer`
+
+#### `constructor(cdp: CDPSessionLike)`
+
+Create a new focus analyzer. Internally creates a `KeyboardEngine` for trap detection.
+
+- `cdp` — Any CDP-compatible session (uses the `CDPSessionLike` interface from `@a11y-oracle/cdp-types`).
+
+#### `getFocusIndicator(): Promise<FocusIndicator>`
+
+Analyze the visual focus indicator of the currently focused element.
+
+Extracts computed CSS properties (`outline`, `box-shadow`, `border-color`, `background-color`) via `Runtime.evaluate`, then calculates the contrast ratio of the focus indicator against the background.
+
+Returns a default "not visible" indicator if no element has focus.
+
+**Visibility detection:**
+- An element has a visible **outline** if `outline-width` is not `0px` and `outline-color` is not `transparent`
+- An element has a visible **box-shadow** if `box-shadow` is not `none`
+
+**Contrast calculation:**
+- For outlines: contrast ratio between `outline-color` and `background-color`
+- For box-shadows: extracts the first color from the `box-shadow` value and computes contrast against `background-color`
+- Returns `contrastRatio: null` if colors cannot be reliably parsed (e.g., gradients, complex color functions)
+
+**WCAG 2.4.12 AA compliance:** `meetsWCAG_AA` is `true` when the indicator is visible AND the contrast ratio >= 3.0.
+
+#### `getTabOrder(): Promise<TabOrderEntry[]>`
+
+Extract all tabbable elements from the DOM in tab order.
+
+Queries for focusable elements (`a[href]`, `button:not([disabled])`, `input:not([disabled])`, `select:not([disabled])`, `textarea:not([disabled])`, `[tabindex]`), then filters out:
+- Elements with `tabIndex < 0`
+- Hidden elements (`display: none`, `visibility: hidden`)
+- Elements with no layout (`offsetParent === null`)
+- Elements inside `[inert]` containers
+
+Results are sorted by `tabIndex` value: positive `tabIndex` values first (ascending), then `tabIndex=0` elements in DOM order.
+
+#### `detectKeyboardTrap(selector: string, maxTabs?: number): Promise<TraversalResult>`
+
+Detect whether focus is trapped inside a container (WCAG 2.1.2).
+
+1. Focuses the first tabbable element inside the container matching `selector`
+2. Presses Tab repeatedly (up to `maxTabs`, default 50)
+3. After each Tab, checks whether focus has left the container
+4. Returns immediately if focus escapes, or declares a trap if `maxTabs` is exhausted
+
+Returns `{ isTrapped: false, tabCount: 0 }` if the container doesn't exist or has no focusable elements.
+
+### Pure Utility Functions
+
+The package also exports pure functions for color parsing and WCAG contrast calculation:
+
+#### `parseColor(css: string): RGBColor | null`
+
+Parse a CSS color string to an `RGBColor` object. Supports:
+- `rgb(r, g, b)` and `rgba(r, g, b, a)`
+- Hex colors: `#RGB`, `#RRGGBB`, `#RRGGBBAA`
+- `transparent` (returns `{ r: 0, g: 0, b: 0, a: 0 }`)
+
+Returns `null` for unsupported formats (named colors, `hsl()`, `color()`, etc.).
+
+#### `srgbToLinear(channel: number): number`
+
+Convert an sRGB channel value (0-255) to linear light.
+
+#### `relativeLuminance(color: RGBColor): number`
+
+Calculate WCAG relative luminance: `L = 0.2126*R + 0.7152*G + 0.0722*B`
+
+#### `contrastRatio(color1: RGBColor, color2: RGBColor): number`
+
+Calculate the WCAG contrast ratio between two colors. Returns a value between 1 (identical) and 21 (black on white).
+
+#### `meetsAA(ratio: number): boolean`
+
+Check if a contrast ratio meets WCAG AA for focus indicators (>= 3.0).
+
+### Types
+
+#### `RGBColor`
+
+```typescript
+interface RGBColor {
+  r: number; // 0-255
+  g: number; // 0-255
+  b: number; // 0-255
+  a: number; // 0-1
+}
+```
+
+#### `FocusIndicator`
+
+Full focus indicator analysis:
+
+```typescript
+interface FocusIndicator {
+  isVisible: boolean;
+  outline: string;          // Raw outline shorthand
+  outlineColor: string;     // e.g. "rgb(0, 95, 204)"
+  outlineWidth: string;     // e.g. "3px"
+  outlineOffset: string;    // e.g. "0px"
+  boxShadow: string;        // e.g. "0px 0px 0px 3px rgb(52, 152, 219)"
+  borderColor: string;
+  backgroundColor: string;
+  contrastRatio: number | null;
+  meetsWCAG_AA: boolean;
+}
+```
+
+#### `TabOrderEntry`
+
+```typescript
+interface TabOrderEntry {
+  index: number;     // Position in tab order (0-based)
+  tag: string;       // "BUTTON"
+  id: string;
+  textContent: string;
+  tabIndex: number;
+  role: string;
+  rect: { x: number; y: number; width: number; height: number };
+}
+```
+
+#### `TabOrderReport`
+
+```typescript
+interface TabOrderReport {
+  entries: TabOrderEntry[];
+  totalCount: number;
+}
+```
+
+#### `TraversalResult`
+
+```typescript
+interface TraversalResult {
+  isTrapped: boolean;                  // true if focus never escaped
+  tabCount: number;                    // Total Tab presses attempted
+  visitedElements: TabOrderEntry[];    // Elements that received focus
+  escapeElement: TabOrderEntry | null; // First element outside container
+}
+```
+
+## Exports
+
+```typescript
+export { FocusAnalyzer } from '@a11y-oracle/focus-analyzer';
+export { parseColor } from '@a11y-oracle/focus-analyzer';
+export { srgbToLinear, relativeLuminance, contrastRatio, meetsAA } from '@a11y-oracle/focus-analyzer';
+export type { RGBColor, FocusIndicator, TabOrderEntry, TraversalResult, TabOrderReport } from '@a11y-oracle/focus-analyzer';
+```
+
+## Limitations
+
+- **Complex focus indicators** — Gradients, CSS `color-mix()`, and other advanced color functions return `contrastRatio: null` because they cannot be reliably parsed into a single color value.
+- **Box-shadow parsing** — Only the first color found in a `box-shadow` value is used for contrast calculation. Multi-layer box-shadows may not be fully analyzed.
+- **Keyboard trap detection** — Tests with Tab key only. Intentional focus traps (e.g., modal dialogs) should be tested separately with Escape key navigation.
+- **`tabIndex` ordering** — The tab order extraction follows the standard algorithm (positive `tabIndex` first, then `tabIndex=0` in DOM order), but doesn't account for Shadow DOM boundaries.

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @module @a11y-oracle/focus-analyzer
+ *
+ * Focus state analysis for accessibility testing. Provides visual
+ * focus indicator inspection, WCAG contrast ratio calculation,
+ * DOM tab order extraction, and keyboard trap detection.
+ *
+ * @packageDocumentation
+ */
+export { FocusAnalyzer } from './lib/focus-analyzer.js';
+export { parseColor } from './lib/color-parser.js';
+export { srgbToLinear, relativeLuminance, contrastRatio, meetsAA } from './lib/contrast.js';
+export type { RGBColor, FocusIndicator, TabOrderEntry, TraversalResult, TabOrderReport, } from './lib/types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAC5F,YAAY,EACV,QAAQ,EACR,cAAc,EACd,aAAa,EACb,eAAe,EACf,cAAc,GACf,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,12 @@
+/**
+ * @module @a11y-oracle/focus-analyzer
+ *
+ * Focus state analysis for accessibility testing. Provides visual
+ * focus indicator inspection, WCAG contrast ratio calculation,
+ * DOM tab order extraction, and keyboard trap detection.
+ *
+ * @packageDocumentation
+ */
+export { FocusAnalyzer } from './lib/focus-analyzer.js';
+export { parseColor } from './lib/color-parser.js';
+export { srgbToLinear, relativeLuminance, contrastRatio, meetsAA } from './lib/contrast.js';

package/dist/lib/color-parser.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @module color-parser
+ *
+ * Parses CSS color values into normalized RGBA tuples.
+ * Handles `rgb()`, `rgba()`, `#hex` (3, 4, 6, 8 digit),
+ * and `transparent`.
+ */
+import type { RGBColor } from './types.js';
+/**
+ * Parse a CSS color string into an {@link RGBColor} tuple.
+ *
+ * Supports:
+ * - `rgb(r, g, b)` and `rgba(r, g, b, a)`
+ * - `#RGB`, `#RGBA`, `#RRGGBB`, `#RRGGBBAA`
+ * - `transparent` (returns black with alpha 0)
+ *
+ * @param css - A CSS color value string.
+ * @returns The parsed color, or `null` if parsing fails.
+ *
+ * @example
+ * ```typescript
+ * parseColor('rgb(255, 0, 0)');       // { r: 255, g: 0, b: 0, a: 1 }
+ * parseColor('#3498db');               // { r: 52, g: 152, b: 219, a: 1 }
+ * parseColor('rgba(0, 0, 0, 0.5)');   // { r: 0, g: 0, b: 0, a: 0.5 }
+ * parseColor('transparent');           // { r: 0, g: 0, b: 0, a: 0 }
+ * ```
+ */
+export declare function parseColor(css: string): RGBColor | null;
+//# sourceMappingURL=color-parser.d.ts.map

package/dist/lib/color-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"color-parser.d.ts","sourceRoot":"","sources":["../../src/lib/color-parser.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CA0FvD"}

package/dist/lib/color-parser.js

@@ -0,0 +1,110 @@
+/**
+ * @module color-parser
+ *
+ * Parses CSS color values into normalized RGBA tuples.
+ * Handles `rgb()`, `rgba()`, `#hex` (3, 4, 6, 8 digit),
+ * and `transparent`.
+ */
+/**
+ * Parse a CSS color string into an {@link RGBColor} tuple.
+ *
+ * Supports:
+ * - `rgb(r, g, b)` and `rgba(r, g, b, a)`
+ * - `#RGB`, `#RGBA`, `#RRGGBB`, `#RRGGBBAA`
+ * - `transparent` (returns black with alpha 0)
+ *
+ * @param css - A CSS color value string.
+ * @returns The parsed color, or `null` if parsing fails.
+ *
+ * @example
+ * ```typescript
+ * parseColor('rgb(255, 0, 0)');       // { r: 255, g: 0, b: 0, a: 1 }
+ * parseColor('#3498db');               // { r: 52, g: 152, b: 219, a: 1 }
+ * parseColor('rgba(0, 0, 0, 0.5)');   // { r: 0, g: 0, b: 0, a: 0.5 }
+ * parseColor('transparent');           // { r: 0, g: 0, b: 0, a: 0 }
+ * ```
+ */
+export function parseColor(css) {
+    if (!css || typeof css !== 'string')
+        return null;
+    const trimmed = css.trim().toLowerCase();
+    // transparent
+    if (trimmed === 'transparent') {
+        return { r: 0, g: 0, b: 0, a: 0 };
+    }
+    // rgb() and rgba()
+    const rgbMatch = trimmed.match(/^rgba?\(\s*(\d{1,3})\s*,\s*(\d{1,3})\s*,\s*(\d{1,3})\s*(?:,\s*([\d.]+)\s*)?\)$/);
+    if (rgbMatch) {
+        return {
+            r: clamp(parseInt(rgbMatch[1], 10), 0, 255),
+            g: clamp(parseInt(rgbMatch[2], 10), 0, 255),
+            b: clamp(parseInt(rgbMatch[3], 10), 0, 255),
+            a: rgbMatch[4] !== undefined ? clamp(parseFloat(rgbMatch[4]), 0, 1) : 1,
+        };
+    }
+    // Modern space-separated rgb() / rgba() syntax: rgb(255 0 0 / 0.5)
+    const rgbSpaceMatch = trimmed.match(/^rgba?\(\s*(\d{1,3})\s+(\d{1,3})\s+(\d{1,3})\s*(?:\/\s*([\d.]+%?)\s*)?\)$/);
+    if (rgbSpaceMatch) {
+        let alpha = 1;
+        if (rgbSpaceMatch[4] !== undefined) {
+            const alphaStr = rgbSpaceMatch[4];
+            alpha = alphaStr.endsWith('%')
+                ? clamp(parseFloat(alphaStr) / 100, 0, 1)
+                : clamp(parseFloat(alphaStr), 0, 1);
+        }
+        return {
+            r: clamp(parseInt(rgbSpaceMatch[1], 10), 0, 255),
+            g: clamp(parseInt(rgbSpaceMatch[2], 10), 0, 255),
+            b: clamp(parseInt(rgbSpaceMatch[3], 10), 0, 255),
+            a: alpha,
+        };
+    }
+    // Hex colors
+    const hexMatch = trimmed.match(/^#([0-9a-f]+)$/);
+    if (hexMatch) {
+        const hex = hexMatch[1];
+        if (hex.length === 3) {
+            // #RGB → #RRGGBB
+            return {
+                r: parseInt(hex[0] + hex[0], 16),
+                g: parseInt(hex[1] + hex[1], 16),
+                b: parseInt(hex[2] + hex[2], 16),
+                a: 1,
+            };
+        }
+        if (hex.length === 4) {
+            // #RGBA → #RRGGBBAA
+            return {
+                r: parseInt(hex[0] + hex[0], 16),
+                g: parseInt(hex[1] + hex[1], 16),
+                b: parseInt(hex[2] + hex[2], 16),
+                a: parseInt(hex[3] + hex[3], 16) / 255,
+            };
+        }
+        if (hex.length === 6) {
+            // #RRGGBB
+            return {
+                r: parseInt(hex.substring(0, 2), 16),
+                g: parseInt(hex.substring(2, 4), 16),
+                b: parseInt(hex.substring(4, 6), 16),
+                a: 1,
+            };
+        }
+        if (hex.length === 8) {
+            // #RRGGBBAA
+            return {
+                r: parseInt(hex.substring(0, 2), 16),
+                g: parseInt(hex.substring(2, 4), 16),
+                b: parseInt(hex.substring(4, 6), 16),
+                a: parseInt(hex.substring(6, 8), 16) / 255,
+            };
+        }
+    }
+    return null;
+}
+/**
+ * Clamp a value between min and max.
+ */
+function clamp(value, min, max) {
+    return Math.min(Math.max(value, min), max);
+}

package/dist/lib/contrast.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @module contrast
+ *
+ * WCAG 2.x relative luminance and contrast ratio calculations.
+ *
+ * Implements the formulas from:
+ * - {@link https://www.w3.org/TR/WCAG21/#dfn-relative-luminance | WCAG 2.1 Relative Luminance}
+ * - {@link https://www.w3.org/TR/WCAG21/#dfn-contrast-ratio | WCAG 2.1 Contrast Ratio}
+ */
+import type { RGBColor } from './types.js';
+/**
+ * Convert an sRGB channel value (0–255) to linear RGB.
+ *
+ * Applies the sRGB inverse companding function:
+ * - If sRGB <= 0.04045: linear = sRGB / 12.92
+ * - Otherwise: linear = ((sRGB + 0.055) / 1.055) ^ 2.4
+ *
+ * @param channel - sRGB channel value in range [0, 255].
+ * @returns Linear RGB value in range [0, 1].
+ */
+export declare function srgbToLinear(channel: number): number;
+/**
+ * Calculate the WCAG relative luminance of a color.
+ *
+ * Formula: L = 0.2126 * R + 0.7152 * G + 0.0722 * B
+ * where R, G, B are linearized sRGB channel values.
+ *
+ * @param color - The RGB color.
+ * @returns Relative luminance in range [0, 1].
+ *          0 = darkest black, 1 = lightest white.
+ */
+export declare function relativeLuminance(color: RGBColor): number;
+/**
+ * Calculate the WCAG contrast ratio between two colors.
+ *
+ * Formula: (L1 + 0.05) / (L2 + 0.05)
+ * where L1 is the lighter luminance and L2 is the darker.
+ *
+ * @param foreground - The foreground (indicator) color.
+ * @param background - The background color.
+ * @returns Contrast ratio in range [1, 21].
+ *          1:1 = no contrast, 21:1 = maximum contrast.
+ */
+export declare function contrastRatio(foreground: RGBColor, background: RGBColor): number;
+/**
+ * Check if a contrast ratio meets WCAG 2.4.12 AA for focus indicators.
+ *
+ * WCAG 2.4.12 requires a minimum 3:1 contrast ratio for focus indicators.
+ *
+ * @param ratio - The contrast ratio.
+ * @returns `true` if the ratio meets or exceeds 3.0.
+ */
+export declare function meetsAA(ratio: number): boolean;
+//# sourceMappingURL=contrast.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"contrast.d.ts","sourceRoot":"","sources":["../../src/lib/contrast.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAGpD;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,CAKzD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ,GAAG,MAAM,CAMhF;AAED;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE9C"}

package/dist/lib/contrast.js

@@ -0,0 +1,68 @@
+/**
+ * @module contrast
+ *
+ * WCAG 2.x relative luminance and contrast ratio calculations.
+ *
+ * Implements the formulas from:
+ * - {@link https://www.w3.org/TR/WCAG21/#dfn-relative-luminance | WCAG 2.1 Relative Luminance}
+ * - {@link https://www.w3.org/TR/WCAG21/#dfn-contrast-ratio | WCAG 2.1 Contrast Ratio}
+ */
+/**
+ * Convert an sRGB channel value (0–255) to linear RGB.
+ *
+ * Applies the sRGB inverse companding function:
+ * - If sRGB <= 0.04045: linear = sRGB / 12.92
+ * - Otherwise: linear = ((sRGB + 0.055) / 1.055) ^ 2.4
+ *
+ * @param channel - sRGB channel value in range [0, 255].
+ * @returns Linear RGB value in range [0, 1].
+ */
+export function srgbToLinear(channel) {
+    const s = channel / 255;
+    return s <= 0.04045 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4);
+}
+/**
+ * Calculate the WCAG relative luminance of a color.
+ *
+ * Formula: L = 0.2126 * R + 0.7152 * G + 0.0722 * B
+ * where R, G, B are linearized sRGB channel values.
+ *
+ * @param color - The RGB color.
+ * @returns Relative luminance in range [0, 1].
+ *          0 = darkest black, 1 = lightest white.
+ */
+export function relativeLuminance(color) {
+    const r = srgbToLinear(color.r);
+    const g = srgbToLinear(color.g);
+    const b = srgbToLinear(color.b);
+    return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+/**
+ * Calculate the WCAG contrast ratio between two colors.
+ *
+ * Formula: (L1 + 0.05) / (L2 + 0.05)
+ * where L1 is the lighter luminance and L2 is the darker.
+ *
+ * @param foreground - The foreground (indicator) color.
+ * @param background - The background color.
+ * @returns Contrast ratio in range [1, 21].
+ *          1:1 = no contrast, 21:1 = maximum contrast.
+ */
+export function contrastRatio(foreground, background) {
+    const l1 = relativeLuminance(foreground);
+    const l2 = relativeLuminance(background);
+    const lighter = Math.max(l1, l2);
+    const darker = Math.min(l1, l2);
+    return (lighter + 0.05) / (darker + 0.05);
+}
+/**
+ * Check if a contrast ratio meets WCAG 2.4.12 AA for focus indicators.
+ *
+ * WCAG 2.4.12 requires a minimum 3:1 contrast ratio for focus indicators.
+ *
+ * @param ratio - The contrast ratio.
+ * @returns `true` if the ratio meets or exceeds 3.0.
+ */
+export function meetsAA(ratio) {
+    return ratio >= 3.0;
+}

package/dist/lib/focus-analyzer.d.ts

@@ -0,0 +1,77 @@
+/**
+ * @module focus-analyzer
+ *
+ * Analyzes visual focus indicators, extracts DOM tab order, and
+ * detects keyboard traps via CDP `Runtime.evaluate`.
+ *
+ * @example
+ * ```typescript
+ * import { FocusAnalyzer } from '@a11y-oracle/focus-analyzer';
+ *
+ * const analyzer = new FocusAnalyzer(cdpSession);
+ * const indicator = await analyzer.getFocusIndicator();
+ * console.log(indicator.isVisible, indicator.contrastRatio);
+ * ```
+ */
+import type { CDPSessionLike } from '@a11y-oracle/cdp-types';
+import type { FocusIndicator, TabOrderEntry, TraversalResult } from './types.js';
+/**
+ * Analyzes focus indicators, tab order, and keyboard traps.
+ *
+ * Uses CDP `Runtime.evaluate` to inspect DOM state and
+ * {@link KeyboardEngine} for dispatching Tab keys during
+ * trap detection.
+ */
+export declare class FocusAnalyzer {
+    private cdp;
+    private keyboard;
+    /**
+     * @param cdp - CDP session for sending protocol commands.
+     */
+    constructor(cdp: CDPSessionLike);
+    /**
+     * Analyze the visual focus indicator of the currently focused element.
+     *
+     * Extracts computed CSS properties (`outline`, `box-shadow`, `border`,
+     * `background-color`) and calculates the contrast ratio of the focus
+     * indicator against the background.
+     *
+     * @returns Focus indicator analysis, or a default "not visible"
+     *          indicator if no element has focus.
+     */
+    getFocusIndicator(): Promise<FocusIndicator>;
+    /**
+     * Extract all tabbable elements from the DOM in tab order.
+     *
+     * Queries for focusable elements (`a[href]`, `button`, `input`,
+     * `select`, `textarea`, `[tabindex]`), filters out hidden and
+     * disabled elements, and sorts by `tabIndex` value.
+     *
+     * @returns Tab order entries sorted by actual tab key order.
+     */
+    getTabOrder(): Promise<TabOrderEntry[]>;
+    /**
+     * Detect whether focus is trapped inside a container.
+     *
+     * Focuses the first tabbable element inside the container, then
+     * presses Tab repeatedly. If focus never leaves the container
+     * after `maxTabs` presses, the container is a keyboard trap.
+     *
+     * @param selector - CSS selector for the container to test.
+     * @param maxTabs - Maximum Tab presses before declaring a trap. Default 50.
+     * @returns Traversal result indicating trap status.
+     */
+    detectKeyboardTrap(selector: string, maxTabs?: number): Promise<TraversalResult>;
+    /**
+     * Extract the dominant color from a CSS box-shadow value.
+     *
+     * Takes the first color found in a `box-shadow` string.
+     * Example: `"0px 0px 0px 3px rgb(52, 152, 219)"` → rgb(52, 152, 219)
+     */
+    private extractBoxShadowColor;
+    /**
+     * Create a default "not visible" focus indicator.
+     */
+    private createEmptyIndicator;
+}
+//# sourceMappingURL=focus-analyzer.d.ts.map

package/dist/lib/focus-analyzer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"focus-analyzer.d.ts","sourceRoot":"","sources":["../../src/lib/focus-analyzer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAE7D,OAAO,KAAK,EACV,cAAc,EACd,aAAa,EACb,eAAe,EAChB,MAAM,YAAY,CAAC;AA4EpB;;;;;;GAMG;AACH,qBAAa,aAAa;IAMZ,OAAO,CAAC,GAAG;IALvB,OAAO,CAAC,QAAQ,CAAiB;IAEjC;;OAEG;gBACiB,GAAG,EAAE,cAAc;IAIvC;;;;;;;;;OASG;IACG,iBAAiB,IAAI,OAAO,CAAC,cAAc,CAAC;IAiDlD;;;;;;;;OAQG;IACG,WAAW,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC;IAS7C;;;;;;;;;;OAUG;IACG,kBAAkB,CACtB,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,MAAW,GACnB,OAAO,CAAC,eAAe,CAAC;IAgG3B;;;;;OAKG;IACH,OAAO,CAAC,qBAAqB;IAgB7B;;OAEG;IACH,OAAO,CAAC,oBAAoB;CAc7B"}

package/dist/lib/focus-analyzer.js

@@ -0,0 +1,299 @@
+/**
+ * @module focus-analyzer
+ *
+ * Analyzes visual focus indicators, extracts DOM tab order, and
+ * detects keyboard traps via CDP `Runtime.evaluate`.
+ *
+ * @example
+ * ```typescript
+ * import { FocusAnalyzer } from '@a11y-oracle/focus-analyzer';
+ *
+ * const analyzer = new FocusAnalyzer(cdpSession);
+ * const indicator = await analyzer.getFocusIndicator();
+ * console.log(indicator.isVisible, indicator.contrastRatio);
+ * ```
+ */
+import { KeyboardEngine } from '@a11y-oracle/keyboard-engine';
+import { parseColor } from './color-parser.js';
+import { contrastRatio, meetsAA } from './contrast.js';
+/**
+ * JavaScript expression to extract computed focus styles from
+ * `document.activeElement`.
+ */
+const GET_FOCUS_STYLES_JS = `
+(() => {
+  const el = document.activeElement;
+  if (!el || el === document.body || el === document.documentElement) {
+    return null;
+  }
+  const cs = window.getComputedStyle(el);
+  return {
+    outline: cs.outline || '',
+    outlineColor: cs.outlineColor || '',
+    outlineWidth: cs.outlineWidth || '',
+    outlineOffset: cs.outlineOffset || '',
+    boxShadow: cs.boxShadow || '',
+    borderColor: cs.borderColor || '',
+    backgroundColor: cs.backgroundColor || '',
+  };
+})()
+`;
+/**
+ * JavaScript expression to extract all tabbable elements in DOM order.
+ */
+const GET_TAB_ORDER_JS = `
+(() => {
+  const selector = [
+    'a[href]',
+    'button:not([disabled])',
+    'input:not([disabled]):not([type="hidden"])',
+    'select:not([disabled])',
+    'textarea:not([disabled])',
+    '[tabindex]',
+  ].join(', ');
+  const elements = Array.from(document.querySelectorAll(selector));
+  return elements
+    .filter(el => {
+      if (el.tabIndex < 0) return false;
+      if (el.offsetParent === null && el.tagName !== 'BODY') return false;
+      const cs = window.getComputedStyle(el);
+      if (cs.visibility === 'hidden' || cs.display === 'none') return false;
+      if (el.closest('[inert]')) return false;
+      return true;
+    })
+    .sort((a, b) => {
+      if (a.tabIndex === 0 && b.tabIndex === 0) return 0;
+      if (a.tabIndex === 0) return 1;
+      if (b.tabIndex === 0) return -1;
+      return a.tabIndex - b.tabIndex;
+    })
+    .map((el, i) => {
+      const rect = el.getBoundingClientRect();
+      return {
+        index: i,
+        tag: el.tagName,
+        id: el.id || '',
+        textContent: (el.textContent || '').trim().substring(0, 200),
+        tabIndex: el.tabIndex,
+        role: el.getAttribute('role') || '',
+        rect: {
+          x: Math.round(rect.x),
+          y: Math.round(rect.y),
+          width: Math.round(rect.width),
+          height: Math.round(rect.height),
+        },
+      };
+    });
+})()
+`;
+/**
+ * Analyzes focus indicators, tab order, and keyboard traps.
+ *
+ * Uses CDP `Runtime.evaluate` to inspect DOM state and
+ * {@link KeyboardEngine} for dispatching Tab keys during
+ * trap detection.
+ */
+export class FocusAnalyzer {
+    cdp;
+    keyboard;
+    /**
+     * @param cdp - CDP session for sending protocol commands.
+     */
+    constructor(cdp) {
+        this.cdp = cdp;
+        this.keyboard = new KeyboardEngine(cdp);
+    }
+    /**
+     * Analyze the visual focus indicator of the currently focused element.
+     *
+     * Extracts computed CSS properties (`outline`, `box-shadow`, `border`,
+     * `background-color`) and calculates the contrast ratio of the focus
+     * indicator against the background.
+     *
+     * @returns Focus indicator analysis, or a default "not visible"
+     *          indicator if no element has focus.
+     */
+    async getFocusIndicator() {
+        const result = (await this.cdp.send('Runtime.evaluate', {
+            expression: GET_FOCUS_STYLES_JS,
+            returnByValue: true,
+        }));
+        const styles = result.result.value;
+        if (!styles) {
+            return this.createEmptyIndicator();
+        }
+        const outlineWidth = styles.outlineWidth || '0px';
+        const hasOutline = outlineWidth !== '0px' &&
+            outlineWidth !== '0' &&
+            styles.outlineColor !== 'transparent';
+        const hasBoxShadow = styles.boxShadow !== 'none' && styles.boxShadow !== '';
+        const isVisible = hasOutline || hasBoxShadow;
+        // Calculate contrast ratio between focus indicator and background
+        let ratio = null;
+        if (isVisible) {
+            const indicatorColor = hasOutline
+                ? parseColor(styles.outlineColor)
+                : this.extractBoxShadowColor(styles.boxShadow);
+            const bgColor = parseColor(styles.backgroundColor);
+            if (indicatorColor && bgColor) {
+                ratio = contrastRatio(indicatorColor, bgColor);
+            }
+        }
+        return {
+            isVisible,
+            outline: styles.outline || '',
+            outlineColor: styles.outlineColor || '',
+            outlineWidth: styles.outlineWidth || '',
+            outlineOffset: styles.outlineOffset || '',
+            boxShadow: styles.boxShadow || '',
+            borderColor: styles.borderColor || '',
+            backgroundColor: styles.backgroundColor || '',
+            contrastRatio: ratio,
+            meetsWCAG_AA: isVisible && ratio !== null && meetsAA(ratio),
+        };
+    }
+    /**
+     * Extract all tabbable elements from the DOM in tab order.
+     *
+     * Queries for focusable elements (`a[href]`, `button`, `input`,
+     * `select`, `textarea`, `[tabindex]`), filters out hidden and
+     * disabled elements, and sorts by `tabIndex` value.
+     *
+     * @returns Tab order entries sorted by actual tab key order.
+     */
+    async getTabOrder() {
+        const result = (await this.cdp.send('Runtime.evaluate', {
+            expression: GET_TAB_ORDER_JS,
+            returnByValue: true,
+        }));
+        return result.result.value ?? [];
+    }
+    /**
+     * Detect whether focus is trapped inside a container.
+     *
+     * Focuses the first tabbable element inside the container, then
+     * presses Tab repeatedly. If focus never leaves the container
+     * after `maxTabs` presses, the container is a keyboard trap.
+     *
+     * @param selector - CSS selector for the container to test.
+     * @param maxTabs - Maximum Tab presses before declaring a trap. Default 50.
+     * @returns Traversal result indicating trap status.
+     */
+    async detectKeyboardTrap(selector, maxTabs = 50) {
+        // Focus the first tabbable element in the container
+        const focusResult = (await this.cdp.send('Runtime.evaluate', {
+            expression: `
+        (() => {
+          const container = document.querySelector(${JSON.stringify(selector)});
+          if (!container) return { error: 'Container not found' };
+          const focusable = container.querySelector(
+            'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])'
+          );
+          if (!focusable) return { error: 'No focusable elements in container' };
+          focusable.focus();
+          return { success: true };
+        })()
+      `,
+            returnByValue: true,
+        }));
+        if (focusResult.result.value?.error) {
+            return {
+                isTrapped: false,
+                tabCount: 0,
+                visitedElements: [],
+                escapeElement: null,
+            };
+        }
+        const visitedElements = [];
+        let escapeElement = null;
+        for (let i = 0; i < maxTabs; i++) {
+            await this.keyboard.press('Tab');
+            // Short delay for focus to settle
+            await new Promise((resolve) => setTimeout(resolve, 20));
+            // Check where focus is now
+            const checkResult = (await this.cdp.send('Runtime.evaluate', {
+                expression: `
+          (() => {
+            const container = document.querySelector(${JSON.stringify(selector)});
+            const el = document.activeElement;
+            if (!el || el === document.body) return { outside: true, element: null };
+            const rect = el.getBoundingClientRect();
+            const entry = {
+              index: ${i},
+              tag: el.tagName,
+              id: el.id || '',
+              textContent: (el.textContent || '').trim().substring(0, 200),
+              tabIndex: el.tabIndex,
+              role: el.getAttribute('role') || '',
+              rect: {
+                x: Math.round(rect.x),
+                y: Math.round(rect.y),
+                width: Math.round(rect.width),
+                height: Math.round(rect.height),
+              },
+            };
+            const isInside = container && container.contains(el);
+            return { outside: !isInside, element: entry };
+          })()
+        `,
+                returnByValue: true,
+            }));
+            const check = checkResult.result.value;
+            if (check.element) {
+                if (check.outside) {
+                    escapeElement = check.element;
+                    return {
+                        isTrapped: false,
+                        tabCount: i + 1,
+                        visitedElements,
+                        escapeElement,
+                    };
+                }
+                visitedElements.push(check.element);
+            }
+        }
+        // If we exhausted all tabs and focus never left, it's a trap
+        return {
+            isTrapped: true,
+            tabCount: maxTabs,
+            visitedElements,
+            escapeElement: null,
+        };
+    }
+    /**
+     * Extract the dominant color from a CSS box-shadow value.
+     *
+     * Takes the first color found in a `box-shadow` string.
+     * Example: `"0px 0px 0px 3px rgb(52, 152, 219)"` → rgb(52, 152, 219)
+     */
+    extractBoxShadowColor(boxShadow) {
+        // Try to find an rgb/rgba color in the box-shadow
+        const rgbMatch = boxShadow.match(/rgba?\([^)]+\)/);
+        if (rgbMatch) {
+            return parseColor(rgbMatch[0]);
+        }
+        // Try to find a hex color
+        const hexMatch = boxShadow.match(/#[0-9a-fA-F]{3,8}/);
+        if (hexMatch) {
+            return parseColor(hexMatch[0]);
+        }
+        return null;
+    }
+    /**
+     * Create a default "not visible" focus indicator.
+     */
+    createEmptyIndicator() {
+        return {
+            isVisible: false,
+            outline: '',
+            outlineColor: '',
+            outlineWidth: '',
+            outlineOffset: '',
+            boxShadow: '',
+            borderColor: '',
+            backgroundColor: '',
+            contrastRatio: null,
+            meetsWCAG_AA: false,
+        };
+    }
+}

package/dist/lib/types.d.ts

@@ -0,0 +1,97 @@
+/**
+ * @module types
+ *
+ * Type definitions for focus analysis, tab order traversal,
+ * and keyboard trap detection.
+ */
+/**
+ * An RGBA color tuple with channels in the range [0, 255]
+ * and alpha in the range [0, 1].
+ */
+export interface RGBColor {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}
+/**
+ * Analysis of the visual focus indicator on the currently focused element.
+ *
+ * Includes raw CSS values, parsed contrast ratio, and WCAG 2.4.12 AA pass/fail.
+ */
+export interface FocusIndicator {
+    /** Whether any visual focus indicator is detected. */
+    isVisible: boolean;
+    /** Raw `outline` shorthand value. */
+    outline: string;
+    /** Computed `outline-color`. */
+    outlineColor: string;
+    /** Computed `outline-width`. */
+    outlineWidth: string;
+    /** Computed `outline-offset`. */
+    outlineOffset: string;
+    /** Computed `box-shadow`. */
+    boxShadow: string;
+    /** Computed `border-color`. */
+    borderColor: string;
+    /** Computed `background-color`. */
+    backgroundColor: string;
+    /**
+     * Contrast ratio of the focus indicator against the background.
+     * `null` if the colors could not be reliably parsed.
+     */
+    contrastRatio: number | null;
+    /**
+     * Whether the focus indicator meets WCAG 2.4.12 AA
+     * (contrast ratio >= 3.0 and indicator is visible).
+     */
+    meetsWCAG_AA: boolean;
+}
+/**
+ * A single entry in the tab order — an element that can receive
+ * focus via the Tab key.
+ */
+export interface TabOrderEntry {
+    /** Position in the actual tab order (0-based). */
+    index: number;
+    /** Tag name (e.g. `'BUTTON'`). */
+    tag: string;
+    /** Element `id` attribute, or empty string. */
+    id: string;
+    /** Trimmed text content of the element. */
+    textContent: string;
+    /** The element's `tabIndex` property. */
+    tabIndex: number;
+    /** The element's `role` attribute, or empty string. */
+    role: string;
+    /** Bounding rectangle. */
+    rect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+/**
+ * Result of a keyboard trap detection traversal.
+ */
+export interface TraversalResult {
+    /** Whether focus was trapped (could not escape the container). */
+    isTrapped: boolean;
+    /** Total number of Tab presses attempted. */
+    tabCount: number;
+    /** Elements that received focus during the traversal. */
+    visitedElements: TabOrderEntry[];
+    /** The first element outside the container that received focus, or `null` if trapped. */
+    escapeElement: TabOrderEntry | null;
+}
+/**
+ * Full report of a tab order traversal across the page.
+ */
+export interface TabOrderReport {
+    /** Tabbable elements in actual tab-key order. */
+    entries: TabOrderEntry[];
+    /** Total number of tabbable elements found. */
+    totalCount: number;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/lib/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;GAGG;AACH,MAAM,WAAW,QAAQ;IACvB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,sDAAsD;IACtD,SAAS,EAAE,OAAO,CAAC;IACnB,qCAAqC;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,gCAAgC;IAChC,YAAY,EAAE,MAAM,CAAC;IACrB,gCAAgC;IAChC,YAAY,EAAE,MAAM,CAAC;IACrB,iCAAiC;IACjC,aAAa,EAAE,MAAM,CAAC;IACtB,6BAA6B;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,+BAA+B;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,mCAAmC;IACnC,eAAe,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B;;;OAGG;IACH,YAAY,EAAE,OAAO,CAAC;CACvB;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,kDAAkD;IAClD,KAAK,EAAE,MAAM,CAAC;IACd,kCAAkC;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,+CAA+C;IAC/C,EAAE,EAAE,MAAM,CAAC;IACX,2CAA2C;IAC3C,WAAW,EAAE,MAAM,CAAC;IACpB,yCAAyC;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,uDAAuD;IACvD,IAAI,EAAE,MAAM,CAAC;IACb,0BAA0B;IAC1B,IAAI,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CAC/D;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,kEAAkE;IAClE,SAAS,EAAE,OAAO,CAAC;IACnB,6CAA6C;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,eAAe,EAAE,aAAa,EAAE,CAAC;IACjC,yFAAyF;IACzF,aAAa,EAAE,aAAa,GAAG,IAAI,CAAC;CACrC;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,iDAAiD;IACjD,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,+CAA+C;IAC/C,UAAU,EAAE,MAAM,CAAC;CACpB"}

package/dist/lib/types.js

@@ -0,0 +1,7 @@
+/**
+ * @module types
+ *
+ * Type definitions for focus analysis, tab order traversal,
+ * and keyboard trap detection.
+ */
+export {};

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@a11y-oracle/focus-analyzer",
+  "version": "1.0.0",
+  "description": "Focus indicator CSS analysis (WCAG 2.4.12), tab order extraction, and keyboard trap detection",
+  "license": "MIT",
+  "author": "a11y-oracle",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/a11y-oracle/a11y-oracle.git",
+    "directory": "libs/focus-analyzer"
+  },
+  "bugs": {
+    "url": "https://github.com/a11y-oracle/a11y-oracle/issues"
+  },
+  "homepage": "https://github.com/a11y-oracle/a11y-oracle/tree/main/libs/focus-analyzer",
+  "keywords": [
+    "accessibility",
+    "a11y",
+    "focus",
+    "wcag",
+    "keyboard-trap",
+    "contrast",
+    "testing"
+  ],
+  "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"
+  ],
+  "dependencies": {
+    "@a11y-oracle/cdp-types": "1.0.0",
+    "@a11y-oracle/keyboard-engine": "1.0.0",
+    "tslib": "^2.3.0"
+  }
+}