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

Attach your existing runtime to a bounded store, then call mountOverlay in the browser. The overlay starts collapsed and provides search, filters, causal evidence, capture controls, and explicit trace copy.

import { createStore } from "@generative-a11y/devtools";
import { mountOverlay } from "@generative-a11y/devtools/overlay";

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

// Call when removing the workbench. The runtime is borrowed.
export function disposeDevtools() {
  overlay.dispose();
  detach();
  store.dispose();
}

maxEntries caps retained records; the store reports dropped older records. The "support" runtime ID connects decisions and delivery results. The runtime is borrowed, so its owner disposes it after devtools detaches.

Workflow records expose content-free run and step identity, parent relationships, attempts, active or terminal state, and associated entity IDs when the adapter supplies them. The inspector does not infer missing hierarchy. Retry records connect the replaced and replacement attempt IDs, so causal chains remain separate across retries and concurrent siblings.

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

import { createRuntime } from "@generative-a11y/core";
import { bindRuntime } from "@generative-a11y/dom";
import { createStore } from "@generative-a11y/devtools";

export const runtime = createRuntime();
export const store = createStore();
const detach = store.attachRuntime({ id: "support", runtime });
const delivery = bindRuntime(runtime, {
  onDelivery(result) {
    store.recordDelivery({ runtimeId: "support", result });
  },
});

// Dispatch your host events through runtime. Keep this binding for the session.
export function disposeChat() {
  delivery.dispose();
  detach();
  store.dispose();
  runtime.dispose();
}

Send DeliveryResult values from the active binding's onDelivery callback 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.