@reticular/speakable 1.2.0 → 1.4.0

package/dist/index.d.ts

@@ -345,4 +345,1061 @@ declare function formatDiffForCI(diff: SemanticDiff): string;
  */
 declare function hasAccessibilityRegression(diff: SemanticDiff): boolean;
 
-export { type AccessibleNode, type AccessibleRole, type AccessibleState, type AccessibleValue, type AnnouncementModel, CURRENT_MODEL_VERSION, type ChangeType, type DeserializationOptions, type FocusInfo, type ModelVersion, type NodeChange, type NodePath, type PropertyChange, SUPPORTED_ROLES, type SemanticDiff, type SerializationOptions, ValidationError, cloneModel, createModel, describeChange, deserializeModel, diffAccessibilityTrees, formatDiffAsJSON, formatDiffAsText, formatDiffForCI, hasAccessibilityRegression, modelsEqual, serializeModel, validateModel, validateRole, validateState, validateTreeStructure };
+/**
+ * NVDA screen reader announcement renderer.
+ *
+ * Generates heuristic announcement text approximating NVDA output.
+ * This is NOT a perfect emulation - real NVDA behavior varies by version,
+ * settings, and context. Use for development guidance only.
+ */
+
+/**
+ * Renders an announcement model as NVDA-style announcement text.
+ *
+ * @param model - Announcement model to render
+ * @param colorize - Whether to apply ANSI color codes to the output
+ * @returns NVDA-style announcement text
+ */
+declare function renderNVDA(model: AnnouncementModel, colorize?: boolean): string;
+
+/**
+ * JAWS screen reader announcement renderer.
+ *
+ * Generates heuristic announcement text approximating JAWS output.
+ * This is NOT a perfect emulation - real JAWS behavior varies by version,
+ * settings, verbosity level, and context. Use for development guidance only.
+ */
+
+/**
+ * Renders an announcement model as JAWS-style announcement text.
+ *
+ * @param model - Announcement model to render
+ * @param colorize - Whether to apply ANSI color codes to the output
+ * @returns JAWS-style announcement text
+ */
+declare function renderJAWS(model: AnnouncementModel, colorize?: boolean): string;
+
+/**
+ * VoiceOver screen reader announcement renderer.
+ *
+ * Generates heuristic announcement text approximating VoiceOver output.
+ * This is NOT a perfect emulation - real VoiceOver behavior varies by version,
+ * settings, and context. Use for development guidance only.
+ */
+
+/**
+ * Renders an announcement model as VoiceOver-style announcement text.
+ *
+ * @param model - Announcement model to render
+ * @param colorize - Whether to apply ANSI color codes to the output
+ * @returns VoiceOver-style announcement text
+ */
+declare function renderVoiceOver(model: AnnouncementModel, colorize?: boolean): string;
+
+/**
+ * Windows Narrator screen reader announcement renderer.
+ *
+ * Generates heuristic announcement text approximating Windows Narrator output.
+ * This is NOT a perfect emulation - real Narrator behavior varies by version,
+ * settings, and context. Use for development guidance only.
+ */
+
+/**
+ * Renders an announcement model as Narrator-style announcement text.
+ *
+ * @param model - Announcement model to render
+ * @param colorize - Whether to apply ANSI color codes to the output
+ * @returns Narrator-style announcement text
+ */
+declare function renderNarrator(model: AnnouncementModel, colorize?: boolean): string;
+
+/**
+ * Developer-friendly audit report renderer.
+ *
+ * Generates human-readable accessibility audit reports with:
+ * - Landmark structure analysis
+ * - Heading hierarchy validation
+ * - Interactive element inventory
+ * - Common accessibility issue detection
+ * - Summary statistics
+ */
+
+/**
+ * Severity level for accessibility issues.
+ */
+type IssueSeverity = 'error' | 'warning' | 'info';
+/**
+ * Accessibility issue detected during audit.
+ */
+interface AccessibilityIssue {
+    severity: IssueSeverity;
+    message: string;
+    suggestion?: string;
+    element?: {
+        role: AccessibleRole;
+        name: string;
+    };
+}
+/**
+ * Audit report statistics.
+ */
+interface AuditStatistics {
+    totalElements: number;
+    roleDistribution: Record<string, number>;
+    landmarkCount: number;
+    headingCount: number;
+    interactiveCount: number;
+    focusableCount: number;
+    statesUsed: Set<string>;
+}
+/**
+ * Complete audit report.
+ */
+interface AuditReport {
+    statistics: AuditStatistics;
+    landmarks: AccessibleNode[];
+    headings: AccessibleNode[];
+    interactiveElements: AccessibleNode[];
+    issues: AccessibilityIssue[];
+}
+/**
+ * Renders an announcement model as a developer-friendly audit report.
+ *
+ * @param model - Announcement model to audit
+ * @returns Formatted audit report text
+ */
+declare function renderAuditReport(model: AnnouncementModel, colorize?: boolean): string;
+/**
+ * Generates audit report data from an announcement model.
+ *
+ * @param model - Announcement model to analyze
+ * @returns Audit report data
+ */
+declare function generateAuditReport(model: AnnouncementModel): AuditReport;
+
+/**
+ * HTML parsing using jsdom.
+ *
+ * Provides lenient parsing with error recovery for malformed HTML.
+ */
+/**
+ * Parsing error class.
+ */
+declare class ParsingError extends Error {
+    readonly cause?: Error | undefined;
+    constructor(message: string, cause?: Error | undefined);
+}
+/**
+ * Parsing warning.
+ */
+interface ParsingWarning {
+    message: string;
+    line?: number;
+    column?: number;
+}
+/**
+ * Result of HTML parsing.
+ */
+interface ParseResult {
+    /** Parsed DOM document */
+    document: Document;
+    /** Warnings encountered during parsing */
+    warnings: ParsingWarning[];
+}
+/**
+ * Parses HTML string into a DOM document.
+ *
+ * Uses jsdom with lenient parsing mode to handle malformed HTML.
+ * Emits warnings for issues but continues processing.
+ *
+ * @param html - HTML string to parse
+ * @returns Parse result with document and warnings
+ * @throws ParsingError if parsing fails completely or input exceeds size limit
+ */
+declare function parseHTML(html: string): ParseResult;
+/**
+ * Parses HTML and returns just the document (throws on warnings).
+ *
+ * Convenience function for cases where warnings should be treated as errors.
+ *
+ * @param html - HTML string to parse
+ * @returns Parsed DOM document
+ * @throws ParsingError if parsing fails or warnings are present
+ */
+declare function parseHTMLStrict(html: string): Document;
+/**
+ * Validates that HTML string is not empty.
+ *
+ * @param html - HTML string to validate
+ * @throws ParsingError if HTML is empty or whitespace-only
+ */
+declare function validateHTMLNotEmpty(html: string): void;
+
+/**
+ * ARIA accessible name computation.
+ *
+ * Implements the ARIA name computation algorithm following the W3C specification.
+ * https://www.w3.org/TR/accname-1.2/
+ */
+/**
+ * Warning emitted during name computation.
+ */
+interface NameComputationWarning {
+    message: string;
+    element: Element;
+}
+/**
+ * Result of name computation.
+ */
+interface NameComputationResult {
+    name: string;
+    warnings: NameComputationWarning[];
+}
+/**
+ * Result of description computation.
+ */
+interface DescriptionComputationResult {
+    description: string;
+    warnings: NameComputationWarning[];
+}
+/**
+ * Computes the accessible name for an element following ARIA specification.
+ *
+ * Priority order:
+ * 1. aria-labelledby (references to other elements)
+ * 2. aria-label
+ * 3. Native label (for form controls)
+ * 4. alt attribute (for images)
+ * 5. Text content (for elements that support it)
+ * 6. title attribute (fallback)
+ *
+ * @param element - Element to compute name for
+ * @param visited - Set of visited elements (for cycle detection)
+ * @returns Computed accessible name and warnings
+ */
+declare function computeAccessibleName(element: Element, visited?: Set<Element>): NameComputationResult;
+/**
+ * Computes the accessible description for an element.
+ *
+ * Priority order:
+ * 1. aria-describedby (references to other elements)
+ * 2. title attribute (fallback)
+ *
+ * @param element - Element to compute description for
+ * @returns Computed accessible description and warnings
+ */
+declare function computeAccessibleDescription(element: Element): DescriptionComputationResult;
+
+/**
+ * Role computation and mapping.
+ *
+ * Maps HTML elements to their implicit ARIA roles and validates explicit roles.
+ */
+
+/**
+ * Warning emitted during role computation.
+ */
+interface RoleComputationWarning {
+    message: string;
+    element: Element;
+}
+/**
+ * Result of role computation.
+ */
+interface RoleComputationResult {
+    role: AccessibleRole | null;
+    warnings: RoleComputationWarning[];
+}
+/**
+ * Computes the accessible role for an element.
+ *
+ * Priority:
+ * 1. Explicit role attribute (if valid)
+ * 2. Implicit role based on element type
+ * 3. null if no role
+ *
+ * @param element - Element to compute role for
+ * @returns Computed role and warnings
+ */
+declare function computeRole(element: Element): RoleComputationResult;
+/**
+ * Checks if an element should be included in the accessibility tree.
+ *
+ * Elements are excluded if:
+ * - They have role="presentation" or role="none"
+ * - They have aria-hidden="true"
+ * - They have no accessible role
+ *
+ * @param element - Element to check
+ * @returns true if element should be included
+ */
+declare function isAccessible(element: Element): boolean;
+
+/**
+ * State and property extraction from ARIA attributes.
+ *
+ * Extracts accessibility states and properties from elements.
+ */
+
+/**
+ * Warning emitted during state extraction.
+ */
+interface StateExtractionWarning {
+    message: string;
+    element: Element;
+}
+/**
+ * Result of state extraction.
+ */
+interface StateExtractionResult {
+    state: AccessibleState;
+    warnings: StateExtractionWarning[];
+}
+/**
+ * Result of value extraction.
+ */
+interface ValueExtractionResult {
+    value: AccessibleValue | undefined;
+    warnings: StateExtractionWarning[];
+}
+/**
+ * Extracts accessibility state from an element.
+ *
+ * Extracts ARIA state attributes and native element states.
+ *
+ * @param element - Element to extract state from
+ * @returns Extracted state and warnings
+ */
+declare function extractState(element: Element): StateExtractionResult;
+/**
+ * Extracts value information from form controls.
+ *
+ * @param element - Element to extract value from
+ * @returns Extracted value and warnings
+ */
+declare function extractValue(element: Element): ValueExtractionResult;
+
+/**
+ * Focus information extraction.
+ *
+ * Determines focusability and tabindex for elements.
+ */
+
+/**
+ * Extracts focus information from an element.
+ *
+ * Determines if an element is focusable and extracts explicit tabindex.
+ *
+ * @param element - Element to extract focus info from
+ * @returns Focus information
+ */
+declare function extractFocusInfo(element: Element): FocusInfo;
+
+/**
+ * Accessibility tree builder.
+ *
+ * Builds the complete accessibility tree from a DOM tree by integrating
+ * all extraction components (role, name, description, state, value, focus).
+ *
+ * Supports transparent traversal through role-less elements, text node
+ * capture as staticText nodes, shadow DOM traversal, and CSS hidden state.
+ */
+
+/**
+ * Warning emitted during tree building.
+ */
+interface TreeBuildWarning {
+    message: string;
+    element: Element;
+}
+/**
+ * Result of tree building.
+ */
+interface TreeBuildResult {
+    model: AnnouncementModel;
+    warnings: TreeBuildWarning[];
+}
+/**
+ * Error thrown when selector filtering fails.
+ */
+declare class SelectorError extends Error {
+    constructor(message: string);
+}
+/**
+ * Builds an accessibility tree from a DOM element.
+ *
+ * Traverses the DOM tree depth-first, applies all extractors,
+ * filters inaccessible elements, and builds the hierarchical tree.
+ *
+ * @param rootElement - Root DOM element to build tree from
+ * @param sourceHash - Optional hash of source HTML for change detection
+ * @returns Announcement model and warnings
+ */
+declare function buildAccessibilityTree(rootElement: Element, sourceHash?: string): TreeBuildResult;
+/**
+ * Builds accessibility trees for elements matching a CSS selector.
+ *
+ * Uses querySelector/querySelectorAll to find matching elements,
+ * then builds an accessibility tree for each match.
+ *
+ * @param rootElement - Root DOM element to search within
+ * @param selector - CSS selector to match elements
+ * @param sourceHash - Optional hash of source HTML for change detection
+ * @returns Array of announcement models and warnings
+ * @throws SelectorError if no elements match the selector
+ */
+declare function buildAccessibilityTreeWithSelector(rootElement: Element, selector: string, sourceHash?: string): TreeBuildResult[];
+
+/**
+ * Runtime Accessibility Timeline - Type System
+ *
+ * Normalized event structures for representing accessibility-relevant
+ * changes during component interaction. All events use a discriminated
+ * union via the `kind` field on payloads and the `type` field on actions.
+ */
+/**
+ * Classification of accessibility-relevant events observed during runtime.
+ */
+type EventType = 'FOCUS_CHANGED' | 'ANNOUNCEMENT' | 'DOM_MUTATION' | 'ROLE_CHANGED' | 'ACCESSIBLE_NAME_CHANGED' | 'STATE_CHANGED' | 'KEYBOARD_ACTION' | 'DIALOG_OPENED' | 'DIALOG_CLOSED' | 'WARNING' | 'REGRESSION';
+/**
+ * Identifies the DOM element targeted by an accessibility event.
+ */
+interface EventTarget {
+    /** ARIA role of the target element */
+    role: string;
+    /** Computed accessible name */
+    accessibleName: string;
+    /** Stable CSS selector path for element identification */
+    selector: string;
+}
+interface FocusChangedPayload {
+    kind: 'focus_changed';
+    previousTarget: EventTarget | null;
+}
+interface AnnouncementPayload {
+    kind: 'announcement';
+    politeness: 'polite' | 'assertive';
+    text: string;
+}
+interface RoleChangedPayload {
+    kind: 'role_changed';
+    previousRole: string;
+    newRole: string;
+}
+interface AccessibleNameChangedPayload {
+    kind: 'accessible_name_changed';
+    previousName: string;
+    newName: string;
+}
+interface StateChangedPayload {
+    kind: 'state_changed';
+    attribute: string;
+    previousValue: string | boolean | null;
+    newValue: string | boolean | null;
+}
+interface DialogOpenedPayload {
+    kind: 'dialog_opened';
+    dialogName: string;
+    isModal: boolean;
+}
+interface DialogClosedPayload {
+    kind: 'dialog_closed';
+    dialogName: string;
+}
+interface KeyboardActionPayload {
+    kind: 'keyboard_action';
+    key: string;
+    modifiers: string[];
+}
+interface WarningPayload {
+    kind: 'warning';
+    message: string;
+    relatedEvent?: AccessibilityEvent;
+}
+/**
+ * Discriminated union of all event payload types.
+ * Use the `kind` field to narrow the type.
+ */
+type EventPayload = FocusChangedPayload | AnnouncementPayload | RoleChangedPayload | AccessibleNameChangedPayload | StateChangedPayload | DialogOpenedPayload | DialogClosedPayload | KeyboardActionPayload | WarningPayload;
+/**
+ * A normalized event representing a single accessibility-relevant change.
+ * Contains common fields for classification, timing, targeting, and
+ * type-specific payload data.
+ */
+interface AccessibilityEvent {
+    /** Event classification */
+    type: EventType;
+    /** Milliseconds elapsed since session start */
+    timestamp: number;
+    /** Target element information */
+    target: EventTarget;
+    /** Type-specific payload data */
+    payload: EventPayload;
+}
+/**
+ * Discriminated union of interaction actions.
+ * Use the `type` field to narrow the action kind.
+ */
+type InteractionAction = {
+    type: 'click';
+    selector: string;
+} | {
+    type: 'tab';
+} | {
+    type: 'shiftTab';
+} | {
+    type: 'escape';
+} | {
+    type: 'enter';
+} | {
+    type: 'space';
+} | {
+    type: 'arrowUp';
+} | {
+    type: 'arrowDown';
+} | {
+    type: 'arrowLeft';
+} | {
+    type: 'arrowRight';
+} | {
+    type: 'key';
+    combo: string;
+} | {
+    type: 'wait';
+    ms: number;
+};
+/**
+ * An ordered sequence of user actions to perform during timeline capture.
+ */
+interface InteractionSequence {
+    /** Human-readable description of the interaction */
+    description: string;
+    /** Ordered list of actions to perform */
+    actions: InteractionAction[];
+}
+/**
+ * Metadata captured alongside an accessibility timeline session.
+ */
+interface TimelineMetadata {
+    /** ISO timestamp of when the timeline was captured */
+    capturedAt: string;
+    /** Speakable package version used for capture */
+    speakableVersion: string;
+    /** The URL that was analyzed */
+    sourceUrl: string;
+    /** Browser context identifier (e.g., "jsdom/23.0.0") */
+    userAgent: string;
+}
+/**
+ * A complete accessibility timeline captured during an interaction session.
+ * Contains the ordered event sequence, session metadata, and extracted warnings.
+ */
+interface AccessibilityTimeline {
+    /** Timeline format version string (e.g., "1.0") */
+    version: string;
+    /** Component name */
+    component: string;
+    /** Story or variant name */
+    story: string | null;
+    /** Human-readable description of the interaction sequence performed */
+    interactionSequence: string;
+    /** Total session duration in milliseconds */
+    duration: number;
+    /** All accessibility events in chronological order */
+    events: AccessibilityEvent[];
+    /** WARNING-type events extracted for quick reference */
+    warnings: AccessibilityEvent[];
+    /** Session capture metadata */
+    metadata: TimelineMetadata;
+}
+
+/**
+ * Runtime Accessibility Engine
+ *
+ * Coordinates all accessibility observers (focus, mutation, live region, dialog)
+ * into a single engine that collects normalized AccessibilityEvents during
+ * component interaction. Events are timestamped relative to session start
+ * and stored in chronological order.
+ *
+ * @module runtime/engine
+ */
+
+interface EngineOptions {
+    /** Document to observe */
+    document: Document;
+    /** Whether to enable heuristic warnings (default: true) */
+    heuristics?: boolean;
+    /** Custom settle time in ms (default: 100) */
+    settleTime?: number;
+}
+interface RuntimeAccessibilityEngine {
+    /** Attach observers to the document and begin event collection */
+    attach(): void;
+    /** Detach all observers and stop collection */
+    detach(): void;
+    /** Get all collected events since attach (chronological order) */
+    getEvents(): AccessibilityEvent[];
+    /** Clear collected events without detaching */
+    reset(): void;
+    /** Whether the engine is currently attached */
+    readonly isAttached: boolean;
+    /** Expose dialog observer for heuristics module */
+    readonly dialogObserver: {
+        getOpenDialogs(): string[];
+    };
+}
+/**
+ * Creates a RuntimeAccessibilityEngine that coordinates all observers
+ * and collects accessibility events with monotonically increasing timestamps.
+ */
+declare function createEngine(options: EngineOptions): RuntimeAccessibilityEngine;
+
+/**
+ * Timeline Generator
+ *
+ * Orchestrates interaction sessions by coordinating the RuntimeAccessibilityEngine
+ * with interaction execution and heuristic analysis. Produces complete
+ * AccessibilityTimeline objects containing ordered events, warnings, and
+ * session metadata.
+ *
+ * @module runtime/timeline-generator
+ */
+
+/**
+ * Configuration options for creating a TimelineGenerator.
+ */
+interface TimelineGeneratorOptions {
+    /** Document or iframe to attach to */
+    document: Document;
+    /** Component name for metadata */
+    componentName: string;
+    /** Story or variant name for metadata */
+    storyName?: string;
+    /** Settle period after last action (default: 500ms) */
+    settlePeriod?: number;
+    /** Maximum wait for document load (default: 10000ms) */
+    loadTimeout?: number;
+    /** Enable heuristic warnings (default: true) */
+    heuristics?: boolean;
+}
+/**
+ * Orchestrates an interaction session and produces an AccessibilityTimeline.
+ */
+interface TimelineGenerator {
+    /** Execute an interaction sequence and produce a timeline */
+    capture(sequence: InteractionSequence): Promise<AccessibilityTimeline>;
+    /** Abort an in-progress capture */
+    abort(): void;
+}
+/**
+ * Creates a TimelineGenerator that coordinates the engine, interaction
+ * execution, and heuristic analysis to produce accessibility timelines.
+ *
+ * Usage:
+ * ```ts
+ * const generator = createTimelineGenerator({
+ *   document: myDocument,
+ *   componentName: 'LoginForm',
+ *   storyName: 'Default',
+ * });
+ *
+ * const timeline = await generator.capture({
+ *   description: 'Tab through form fields',
+ *   actions: [{ type: 'tab' }, { type: 'tab' }, { type: 'enter' }],
+ * });
+ * ```
+ */
+declare function createTimelineGenerator(options: TimelineGeneratorOptions): TimelineGenerator;
+
+/**
+ * Interaction Execution
+ *
+ * Executes interaction sequences against a document, dispatching proper
+ * DOM events (keyboard, mouse, focus) and emitting KEYBOARD_ACTION
+ * accessibility events for each action.
+ *
+ * @module runtime/interactions
+ */
+
+/**
+ * Execute a single interaction action against the document.
+ *
+ * For keyboard actions, dispatches proper KeyboardEvent sequences (keydown, keypress, keyup).
+ * For tab/shiftTab, computes next/previous focusable element and moves focus.
+ * Emits KEYBOARD_ACTION events for each keyboard action.
+ * Handles missing elements by emitting WARNING events and continuing.
+ *
+ * Click and wait actions do not emit KEYBOARD_ACTION events.
+ */
+declare function executeAction(action: InteractionAction, document: Document, onEvent: (event: AccessibilityEvent) => void, getTimestamp: () => number): Promise<void>;
+/**
+ * Execute an interaction sequence in order, with DOM stability waits between actions.
+ *
+ * Runs each action sequentially, waiting for `settleTime` milliseconds between actions
+ * to allow the DOM to stabilize. This ensures observers can capture resulting changes
+ * before the next action fires.
+ *
+ * @param sequence - The interaction sequence to execute
+ * @param document - The target document
+ * @param onEvent - Callback to emit accessibility events
+ * @param getTimestamp - Function returning current timestamp in ms since session start
+ * @param settleTime - Milliseconds to wait between actions for DOM stability (default: 100)
+ */
+declare function executeSequence(sequence: InteractionSequence, document: Document, onEvent: (event: AccessibilityEvent) => void, getTimestamp: () => number, settleTime?: number): Promise<void>;
+
+/**
+ * Built-in Interaction Patterns
+ *
+ * Provides pre-defined interaction sequences for common ARIA widget patterns.
+ * Each pattern exercises standard keyboard interaction behavior as defined by
+ * the WAI-ARIA Authoring Practices. Patterns use configurable selectors that
+ * can be overridden to match component-specific markup.
+ *
+ * @module runtime/patterns
+ */
+
+/**
+ * Optional map of CSS selectors to override defaults for built-in patterns.
+ *
+ * - `trigger` — element that opens/activates the widget
+ * - `container` — wrapper/container element for the widget
+ * - `content` — the content region within the widget
+ * - `items` — individual items within the widget (options, tabs, etc.)
+ * - `input` — text input element within the widget
+ */
+interface PatternSelectorMap {
+    trigger?: string;
+    container?: string;
+    content?: string;
+    items?: string;
+    input?: string;
+}
+/**
+ * Names of built-in interaction patterns.
+ */
+type BuiltinPatternName = 'modal-dialog' | 'combobox' | 'tabs' | 'accordion';
+/**
+ * Get a built-in interaction pattern by name.
+ *
+ * Each pattern returns an InteractionSequence with a descriptive name and the
+ * appropriate actions for testing common ARIA widget patterns. Optional selectors
+ * can override the defaults used to locate trigger, container, and content elements.
+ *
+ * Default selectors:
+ * - modal-dialog: trigger = 'button', container = '[role="dialog"], dialog'
+ * - combobox: input = '[role="combobox"], input[type="text"]', items = '[role="option"]'
+ * - tabs: container = '[role="tablist"]', items = '[role="tab"]'
+ * - accordion: trigger = 'button[aria-expanded]'
+ *
+ * @param name - The built-in pattern name
+ * @param selectors - Optional CSS selectors to override defaults
+ * @returns An InteractionSequence representing the pattern
+ */
+declare function getBuiltinPattern(name: BuiltinPatternName, selectors?: PatternSelectorMap): InteractionSequence;
+
+/**
+ * Heuristic Warning Analyzer
+ *
+ * Processes accessibility events one at a time and emits WARNING events
+ * when common runtime accessibility anti-patterns are detected. Operates
+ * independently of baselines, providing value from the first run.
+ *
+ * Detected patterns:
+ * - Focus not moved into modal dialog within configured timeout (default: 100ms)
+ * - Focus escaped modal dialog (focus moved to element outside open dialog)
+ * - Rapid announcements (too many in a short window)
+ * - Keyboard action with no accessibility response within timeout
+ * - Focused element removed from DOM without explicit focus management
+ *
+ * Uses event timestamps (not real-time timers) for timeout detection,
+ * enabling deterministic testing with jsdom.
+ *
+ * @module runtime/heuristics
+ */
+
+/**
+ * Configuration for heuristic warning thresholds.
+ */
+interface HeuristicConfig {
+    /** Time window to detect focus moving into dialog (default: 100ms) */
+    dialogFocusTimeout: number;
+    /** Time window to detect rapid announcements (default: 500ms) */
+    rapidAnnouncementWindow: number;
+    /** Threshold for rapid announcement count (default: 3) */
+    rapidAnnouncementThreshold: number;
+    /** Time window to detect keyboard action response (default: 200ms) */
+    keyboardResponseTimeout: number;
+}
+/**
+ * Processes accessibility events and detects runtime anti-patterns.
+ */
+interface HeuristicAnalyzer {
+    /** Process an event and return any warnings it triggers */
+    process(event: AccessibilityEvent): AccessibilityEvent[];
+    /** Get current open dialog selectors (for focus escape detection) */
+    readonly openDialogs: string[];
+}
+/**
+ * Creates a heuristic analyzer that processes accessibility events and
+ * emits warnings when common anti-patterns are detected.
+ *
+ * The analyzer uses event timestamps for timeout detection rather than
+ * real-time timers, making it deterministic and testable with jsdom.
+ */
+declare function createHeuristicAnalyzer(config?: Partial<HeuristicConfig>): HeuristicAnalyzer;
+
+/**
+ * Deterministic serialization and deserialization for Runtime Accessibility
+ * Timeline types.
+ *
+ * All serializers produce JSON with recursively sorted keys and 2-space
+ * indentation, guaranteeing:
+ *  - Byte-identical output for equivalent inputs (determinism)
+ *  - Round-trip integrity (serialize → deserialize → serialize = identical)
+ *  - Stable version-control diffs
+ */
+
+/**
+ * Serializes an AccessibilityEvent to deterministic JSON with sorted keys
+ * and 2-space indentation.
+ *
+ * @param event - The accessibility event to serialize
+ * @returns Deterministic JSON string
+ */
+declare function serializeEvent(event: AccessibilityEvent): string;
+/**
+ * Deserializes a JSON string into a validated AccessibilityEvent.
+ *
+ * @param json - JSON string to parse
+ * @returns Validated AccessibilityEvent
+ * @throws Error if the JSON is invalid or does not conform to the event schema
+ */
+declare function deserializeEvent(json: string): AccessibilityEvent;
+/**
+ * Serializes an AccessibilityTimeline to deterministic JSON with sorted keys
+ * and 2-space indentation.
+ *
+ * @param timeline - The accessibility timeline to serialize
+ * @returns Deterministic JSON string
+ */
+declare function serializeTimeline(timeline: AccessibilityTimeline): string;
+/**
+ * Deserializes a JSON string into a validated AccessibilityTimeline.
+ *
+ * @param json - JSON string to parse
+ * @returns Validated AccessibilityTimeline
+ * @throws Error if the JSON is invalid or does not conform to the timeline schema
+ */
+declare function deserializeTimeline(json: string): AccessibilityTimeline;
+/**
+ * Serializes an InteractionSequence to deterministic JSON with sorted keys
+ * and 2-space indentation.
+ *
+ * @param seq - The interaction sequence to serialize
+ * @returns Deterministic JSON string
+ */
+declare function serializeInteractionSequence(seq: InteractionSequence): string;
+/**
+ * Deserializes a JSON string into a validated InteractionSequence.
+ *
+ * @param json - JSON string to parse
+ * @returns Validated InteractionSequence
+ * @throws Error if the JSON is invalid or does not conform to the interaction schema
+ */
+declare function deserializeInteractionSequence(json: string): InteractionSequence;
+/**
+ * Checks whether two AccessibilityTimelines are deeply equal by comparing
+ * their deterministic serializations. Because serialization sorts keys
+ * recursively, structurally equivalent timelines produce identical strings.
+ *
+ * @param a - First timeline
+ * @param b - Second timeline
+ * @returns true if timelines are equivalent
+ */
+declare function timelinesEqual(a: AccessibilityTimeline, b: AccessibilityTimeline): boolean;
+
+/**
+ * Stable CSS Selector Generation
+ *
+ * Generates unique, deterministic CSS selectors for DOM elements.
+ * The selector strategy prioritizes stability and readability:
+ *
+ * 1. If the element has an ID, return `#id`
+ * 2. Walk up from the element to the document root, building a path
+ * 3. At each level, try tag name alone, then tag+classes, then tag:nth-child(n)
+ * 4. Stop building the path when the partial selector already uniquely identifies the element
+ */
+/**
+ * Generate a stable CSS selector that uniquely identifies the given element
+ * within its document.
+ *
+ * The selector is deterministic: given the same DOM structure, the same element
+ * will always produce the same selector string.
+ */
+declare function generateSelector(element: Element): string;
+
+/**
+ * Behavior Diff Engine
+ *
+ * Compares two Accessibility Timelines and produces a BehaviorDiffReport
+ * describing added, removed, and modified events. Events are matched by
+ * type + target selector. Timestamp differences alone do not count as
+ * modifications.
+ */
+
+/**
+ * A single entry in the diff report representing one difference between
+ * baseline and current timelines.
+ */
+interface DiffEntry {
+    /** The event from the current timeline (for added/modified) or baseline (for removed) */
+    event: AccessibilityEvent;
+    /** The corresponding event from the other timeline (for modified entries) */
+    previousEvent?: AccessibilityEvent;
+    /** Human-readable description of the difference */
+    message: string;
+}
+/**
+ * Structured summary of differences between two Accessibility Timelines.
+ */
+interface BehaviorDiffReport {
+    baseline: {
+        totalEvents: number;
+    };
+    current: {
+        totalEvents: number;
+    };
+    /** Events present in current but not in baseline */
+    added: DiffEntry[];
+    /** Events present in baseline but not in current */
+    removed: DiffEntry[];
+    /** Events present in both but with different payloads */
+    modified: DiffEntry[];
+    /** Aggregate counts (must equal array lengths exactly) */
+    summary: {
+        totalBaseline: number;
+        totalCurrent: number;
+        added: number;
+        removed: number;
+        modified: number;
+    };
+}
+/**
+ * Compare two Accessibility Timelines and produce a structured diff report.
+ *
+ * Algorithm:
+ * 1. Create matching keys for events: type + target selector
+ * 2. Walk baseline events and find matching current events
+ * 3. If matched: compare payloads (ignoring timestamp). Different = modified.
+ * 4. If no match in current: classify as removed
+ * 5. Unmatched current events: classify as added
+ * 6. Timestamp-only differences do NOT count as modifications
+ */
+declare function diffTimelines(baseline: AccessibilityTimeline, current: AccessibilityTimeline): BehaviorDiffReport;
+
+type SeverityLevel = 'critical' | 'high' | 'medium' | 'low';
+interface ClassifiedDiffEntry {
+    event: AccessibilityEvent;
+    previousEvent?: AccessibilityEvent;
+    message: string;
+    severity: SeverityLevel;
+}
+interface ClassifiedDiffReport {
+    entries: ClassifiedDiffEntry[];
+    highestSeverity: SeverityLevel | null;
+    criticalCount: number;
+    highCount: number;
+    mediumCount: number;
+    lowCount: number;
+}
+declare function classifyDiff(report: BehaviorDiffReport): ClassifiedDiffReport;
+
+interface BaselineFile {
+    baseline: {
+        createdAt: string;
+        speakableVersion: string;
+        storybookUrl?: string;
+        interactionSequence: string;
+    };
+    timeline: AccessibilityTimeline;
+}
+interface BaselineStorage {
+    save(componentName: string, storyName: string, timeline: AccessibilityTimeline, meta?: {
+        storybookUrl?: string;
+    }): Promise<void>;
+    load(componentName: string, storyName: string): Promise<BaselineFile | null>;
+    exists(componentName: string, storyName: string): Promise<boolean>;
+    getBaselinePath(componentName: string, storyName: string): string;
+}
+declare function createBaselineStorage(baseDir: string): BaselineStorage;
+
+/**
+ * Runtime Accessibility Timeline - Public API
+ *
+ * Exports all public types, interfaces, and factory functions for the
+ * Runtime Accessibility Engine. This module provides:
+ *
+ * - Event type system (EventType, AccessibilityEvent, payloads)
+ * - Runtime engine (createEngine)
+ * - Timeline generation (createTimelineGenerator)
+ * - Interaction execution (executeAction, executeSequence)
+ * - Built-in patterns (getBuiltinPattern)
+ * - Heuristic analysis (createHeuristicAnalyzer)
+ * - Serialization (serializeTimeline, deserializeTimeline, etc.)
+ * - Stable CSS selector generation (generateSelector)
+ */
+
+type index_AccessibilityEvent = AccessibilityEvent;
+type index_AccessibilityTimeline = AccessibilityTimeline;
+type index_AccessibleNameChangedPayload = AccessibleNameChangedPayload;
+type index_AnnouncementPayload = AnnouncementPayload;
+type index_BaselineFile = BaselineFile;
+type index_BaselineStorage = BaselineStorage;
+type index_BehaviorDiffReport = BehaviorDiffReport;
+type index_BuiltinPatternName = BuiltinPatternName;
+type index_ClassifiedDiffEntry = ClassifiedDiffEntry;
+type index_ClassifiedDiffReport = ClassifiedDiffReport;
+type index_DialogClosedPayload = DialogClosedPayload;
+type index_DialogOpenedPayload = DialogOpenedPayload;
+type index_DiffEntry = DiffEntry;
+type index_EngineOptions = EngineOptions;
+type index_EventPayload = EventPayload;
+type index_EventTarget = EventTarget;
+type index_EventType = EventType;
+type index_FocusChangedPayload = FocusChangedPayload;
+type index_HeuristicAnalyzer = HeuristicAnalyzer;
+type index_HeuristicConfig = HeuristicConfig;
+type index_InteractionAction = InteractionAction;
+type index_InteractionSequence = InteractionSequence;
+type index_KeyboardActionPayload = KeyboardActionPayload;
+type index_PatternSelectorMap = PatternSelectorMap;
+type index_RoleChangedPayload = RoleChangedPayload;
+type index_RuntimeAccessibilityEngine = RuntimeAccessibilityEngine;
+type index_SeverityLevel = SeverityLevel;
+type index_StateChangedPayload = StateChangedPayload;
+type index_TimelineGenerator = TimelineGenerator;
+type index_TimelineGeneratorOptions = TimelineGeneratorOptions;
+type index_TimelineMetadata = TimelineMetadata;
+type index_WarningPayload = WarningPayload;
+declare const index_classifyDiff: typeof classifyDiff;
+declare const index_createBaselineStorage: typeof createBaselineStorage;
+declare const index_createEngine: typeof createEngine;
+declare const index_createHeuristicAnalyzer: typeof createHeuristicAnalyzer;
+declare const index_createTimelineGenerator: typeof createTimelineGenerator;
+declare const index_deserializeEvent: typeof deserializeEvent;
+declare const index_deserializeInteractionSequence: typeof deserializeInteractionSequence;
+declare const index_deserializeTimeline: typeof deserializeTimeline;
+declare const index_diffTimelines: typeof diffTimelines;
+declare const index_executeAction: typeof executeAction;
+declare const index_executeSequence: typeof executeSequence;
+declare const index_generateSelector: typeof generateSelector;
+declare const index_getBuiltinPattern: typeof getBuiltinPattern;
+declare const index_serializeEvent: typeof serializeEvent;
+declare const index_serializeInteractionSequence: typeof serializeInteractionSequence;
+declare const index_serializeTimeline: typeof serializeTimeline;
+declare const index_timelinesEqual: typeof timelinesEqual;
+declare namespace index {
+  export { type index_AccessibilityEvent as AccessibilityEvent, type index_AccessibilityTimeline as AccessibilityTimeline, type index_AccessibleNameChangedPayload as AccessibleNameChangedPayload, type index_AnnouncementPayload as AnnouncementPayload, type index_BaselineFile as BaselineFile, type index_BaselineStorage as BaselineStorage, type index_BehaviorDiffReport as BehaviorDiffReport, type index_BuiltinPatternName as BuiltinPatternName, type index_ClassifiedDiffEntry as ClassifiedDiffEntry, type index_ClassifiedDiffReport as ClassifiedDiffReport, type index_DialogClosedPayload as DialogClosedPayload, type index_DialogOpenedPayload as DialogOpenedPayload, type index_DiffEntry as DiffEntry, type index_EngineOptions as EngineOptions, type index_EventPayload as EventPayload, type index_EventTarget as EventTarget, type index_EventType as EventType, type index_FocusChangedPayload as FocusChangedPayload, type index_HeuristicAnalyzer as HeuristicAnalyzer, type index_HeuristicConfig as HeuristicConfig, type index_InteractionAction as InteractionAction, type index_InteractionSequence as InteractionSequence, type index_KeyboardActionPayload as KeyboardActionPayload, type index_PatternSelectorMap as PatternSelectorMap, type index_RoleChangedPayload as RoleChangedPayload, type index_RuntimeAccessibilityEngine as RuntimeAccessibilityEngine, type index_SeverityLevel as SeverityLevel, type index_StateChangedPayload as StateChangedPayload, type index_TimelineGenerator as TimelineGenerator, type index_TimelineGeneratorOptions as TimelineGeneratorOptions, type index_TimelineMetadata as TimelineMetadata, type index_WarningPayload as WarningPayload, index_classifyDiff as classifyDiff, index_createBaselineStorage as createBaselineStorage, index_createEngine as createEngine, index_createHeuristicAnalyzer as createHeuristicAnalyzer, index_createTimelineGenerator as createTimelineGenerator, index_deserializeEvent as deserializeEvent, index_deserializeInteractionSequence as deserializeInteractionSequence, index_deserializeTimeline as deserializeTimeline, index_diffTimelines as diffTimelines, index_executeAction as executeAction, index_executeSequence as executeSequence, index_generateSelector as generateSelector, index_getBuiltinPattern as getBuiltinPattern, index_serializeEvent as serializeEvent, index_serializeInteractionSequence as serializeInteractionSequence, index_serializeTimeline as serializeTimeline, index_timelinesEqual as timelinesEqual };
+}
+
+export { type AccessibilityIssue, type AccessibleNode, type AccessibleRole, type AccessibleState, type AccessibleValue, type AnnouncementModel, type AuditReport, type AuditStatistics, CURRENT_MODEL_VERSION, type ChangeType, type DescriptionComputationResult, type DeserializationOptions, type FocusInfo, type IssueSeverity, type ModelVersion, type NameComputationResult, type NameComputationWarning, type NodeChange, type NodePath, type ParseResult, ParsingError, type ParsingWarning, type PropertyChange, type RoleComputationResult, type RoleComputationWarning, SUPPORTED_ROLES, SelectorError, type SemanticDiff, type SerializationOptions, type StateExtractionResult, type StateExtractionWarning, type TreeBuildResult, type TreeBuildWarning, ValidationError, type ValueExtractionResult, buildAccessibilityTree, buildAccessibilityTreeWithSelector, cloneModel, computeAccessibleDescription, computeAccessibleName, computeRole, createModel, describeChange, deserializeModel, diffAccessibilityTrees, extractFocusInfo, extractState, extractValue, formatDiffAsJSON, formatDiffAsText, formatDiffForCI, generateAuditReport, hasAccessibilityRegression, isAccessible, modelsEqual, parseHTML, parseHTMLStrict, renderAuditReport, renderJAWS, renderNVDA, renderNarrator, renderVoiceOver, index as runtime, serializeModel, validateHTMLNotEmpty, validateModel, validateRole, validateState, validateTreeStructure };