Debug AI accessibility with the trace explorer

Install development-only diagnostics

Install @generative-a11y/devtools in development environments. The package observes public core diagnostics and does not patch dispatch, change announcement policy, or depend on an AI framework.

npm install --save-dev @generative-a11y/devtools

Open the Accessibility Trace Explorer

The optional overlay mounts only when your code calls mountDevtoolsOverlay. It starts collapsed inside an open Shadow DOM and provides search, filters, causal evidence, capture controls, and explicit trace copy.

import { createDevtoolsStore } from "@generative-a11y/devtools";
import { mountDevtoolsOverlay } from "@generative-a11y/devtools/overlay";

const store = createDevtoolsStore({ maxEntries: 250 });
const detach = store.attachRuntime({ id: "support", runtime });
const overlay = mountDevtoolsOverlay({ store });

// Dispose in reverse ownership order.
overlay.dispose();
detach();
store.dispose();

Captured evidence and redaction

The store retains event categories, outcomes, timing, stable IDs, queue and entity snapshots, declared adapter evidence, and browser delivery metadata. It excludes assistant text, labels, errors, tool data, stacks, DOM content, deduplication keys, and timer handles.

Pass adapter metadata through source only when a documented integration can support it. Devtools does not detect a framework or invent events that the framework did not report.

Correlate runtime decisions with DOM delivery

Send DOMDeliveryResult values from createDOMAnnouncer onDiagnostic to store.recordDelivery. Safe announcement and entity IDs connect the browser action to the runtime decision that requested it.

Overlay keyboard and focus behavior

Opening the workspace moves focus into it. Escape or the close control collapses the workspace and restores the element focused before opening. Streaming records do not move focus, the overlay does not trap focus, and it creates no live region or global keyboard shortcut.