@generative-a11y/devtools
Capture redacted runtime diagnostics and inspect them in a browser overlay.
createStore
The headless store is framework-neutral and has no browser side effects on import. It subscribes to public runtime diagnostics and owns only its bounded captured history.
import { createStore } from "@generative-a11y/devtools";
const store = createStore({ maxEntries: 250 });
const detach = store.attachRuntime({ id: "support", runtime });
const snapshot = store.getSnapshot();
const trace = store.exportTrace();
detach();
store.dispose();maxEntries defaults to 250 and must be a positive safe integer. The store
borrows public runtime diagnostics; disposing it detaches runtimes without
disposing them. Snapshots and trace exports are immutable and content-free.
Prop
Type
Capture controls and ownership
pauseCapture and resumeCapture affect devtools capture only. They do not pause runtime scheduling or browser delivery. clear removes records without detaching runtimes; dispose detaches runtimes and removes subscribers.
Prop
Type
Snapshot and trace contracts
Devtools snapshots and V1 exports contain redacted records, runtime snapshots, and declared adapter sources. The bounded record list reports how much older data it dropped.
Prop
Type
Workflow record correlation
Workflow records retain runId, runInstanceId, stepId, and
stepInstanceId. Parent fields preserve only hierarchy supplied by the source.
nextRunInstanceId and nextStepInstanceId connect a retry record to its
replacement attempt. The trace explorer uses these exact attempt keys so
concurrent or replaced attempts are not merged by label.
Prop
Type
Adapter fidelity
DevtoolsRuntimeSource stores an integration's declared evidence and fidelity.
Workflow fields cover runs, steps, hierarchy, tools, interactions, replay,
reconnection, retries, interruption, connection, and custom events. Devtools
does not inspect framework internals or fill in evidence the adapter lacks.
mountOverlay
Import the browser helper from @generative-a11y/devtools/overlay. It mounts one Shadow DOM host after an explicit call, starts collapsed, and restores prior focus when closed.
import { mountOverlay } from "@generative-a11y/devtools/overlay";
const overlay = mountOverlay({ store });
// Call overlay.dispose() when removing the workbench.The overlay reads your store without attaching runtimes itself. Importing the
module creates no browser UI or global shortcuts. dispose() removes the
workbench and its host.
Prop
Type
Evidence and testing note
Captured runtime and browser evidence does not prove that assistive technology spoke an announcement.
Localized announcements
See catalogs and adapter copy for the typed
messages and copy options, language ownership, validation, construction
lifetime, and replay requirements. Existing lifecycle evidence and timing remain
unchanged.
Public declarations: @generative-a11y/devtools
All exported values and types for this entry point. Import these names from @generative-a11y/devtools; the signatures below are reference material, not a replacement for the ownership and lifecycle guidance above.
AttachRuntimeOptions — type
interface AttachRuntimeOptions {
readonly id: string;
readonly runtime: Pick<Runtime, "subscribeDiagnosticEvents" | "getDiagnosticSnapshot">;
readonly source?: DevtoolsRuntimeSource;
}createStore — value
declare function createStore(options?: StoreOptions): Store;DeliveryRecordInput — type
interface DeliveryRecordInput {
readonly runtimeId: string;
readonly result: {
readonly status: "notified" | "mutated" | "unavailable" | "disposed";
readonly method: "aria-notify" | "live-region" | "none";
readonly channel: "polite" | "assertive";
readonly announcementId: string;
readonly sourceType: string;
readonly at: number;
readonly sourceEventId?: string;
readonly responseId?: string;
readonly toolId?: string;
readonly interactionId?: string;
/** Stable logical run identity copied from the delivered intent. */
readonly runId?: string;
/** Stable run attempt identity copied from the delivered intent. */
readonly runInstanceId?: string;
/** Stable logical step identity copied from the delivered intent. */
readonly stepId?: string;
/** Stable step attempt identity copied from the delivered intent. */
readonly stepInstanceId?: string;
readonly error?: {
readonly name: string;
readonly message?: string;
};
};
}DevtoolsRecord — type
interface DevtoolsRecord {
readonly attentionMode?: AttentionMode;
readonly attentionOverride?: AttentionOverride;
readonly runtimeId: string;
/** Opaque key for the immutable adapter evidence captured with this record. */
readonly runtimeSourceId?: string;
readonly sequence?: number;
readonly captureSequence: number;
readonly at: number;
readonly kind: DevtoolsRecordKind;
readonly sourceType?: string;
readonly sourceEventId?: string;
readonly disposition?: string;
readonly reason?: string;
readonly announcementId?: string;
readonly responseId?: string;
readonly responseInstanceId?: string;
readonly nextResponseInstanceId?: string;
readonly attempt?: number;
readonly toolId?: string;
readonly toolInstanceId?: string;
readonly interactionId?: string;
readonly approvalId?: string;
/** Stable logical run identity retained as content-free correlation data. */
readonly runId?: string;
/** Stable run attempt identity retained as correlation data. */
readonly runInstanceId?: string;
/** Replacement run attempt identity on retry evidence. */
readonly nextRunInstanceId?: string;
/** Explicit logical parent run identity. */
readonly parentRunId?: string;
/** Explicit parent run attempt identity. */
readonly parentRunInstanceId?: string;
/** Stable logical step identity retained as content-free correlation data. */
readonly stepId?: string;
/** Stable step attempt identity retained as correlation data. */
readonly stepInstanceId?: string;
/** Replacement step attempt identity on retry evidence. */
readonly nextStepInstanceId?: string;
/** Explicit logical parent step identity. */
readonly parentStepId?: string;
/** Explicit parent step attempt identity. */
readonly parentStepInstanceId?: string;
/** Explicit tool that delegated to a child run. */
readonly parentToolId?: string;
/** Explicit response that owns a child run. */
readonly parentResponseId?: string;
readonly progress?: number;
readonly outcome?: string;
readonly count?: number;
readonly scheduledAt?: number;
readonly dueAt?: number;
readonly delayMs?: number;
readonly queueSequence?: number;
readonly channel?: "polite" | "assertive";
readonly deliveryStatus?: "notified" | "mutated" | "unavailable" | "disposed";
readonly deliveryMethod?: "aria-notify" | "live-region" | "none";
readonly errorName?: string;
}DevtoolsRecordKind — type
type DevtoolsRecordKind = RuntimeDiagnosticEventV1["kind"] | "dom-delivery";DevtoolsRuntimeSource — type
/**
* Explicit, serializable evidence declared by an integration. Devtools never
* detects framework state or infers fidelity on its own.
*/
interface DevtoolsRuntimeSource {
readonly adapter: string;
readonly evidence: readonly string[];
readonly fidelity: Readonly<Pick<AdapterFidelity, "interruption" | "retries" | "connection"> & Partial<Pick<AdapterFidelity, "runs" | "steps" | "hierarchy" | "tools" | "interactions" | "replay" | "reconnection" | "customEvents">> & {
readonly optionalEvents?: readonly NonNullable<AdapterFidelity["optionalEvents"]>[number][];
}>;
}DevtoolsSnapshot — type
interface DevtoolsSnapshot {
readonly paused: boolean;
readonly droppedCount: number;
readonly records: readonly DevtoolsRecord[];
readonly runtimeIds: readonly string[];
readonly runtimeSnapshots: Readonly<Record<string, RuntimeDiagnosticSnapshotV1>>;
readonly runtimeSources: Readonly<Record<string, DevtoolsRuntimeSource>>;
}DevtoolsTraceExportV1 — type
interface DevtoolsTraceExportV1 {
readonly schemaVersion: 1;
readonly kind: "generative-a11y/devtools-trace";
readonly paused: boolean;
readonly droppedCount: number;
readonly records: readonly DevtoolsRecord[];
readonly runtimeSnapshots: Readonly<Record<string, RuntimeDiagnosticSnapshotV1>>;
readonly runtimeSources: Readonly<Record<string, DevtoolsRuntimeSource>>;
}Store — type
interface Store {
attachRuntime(options: AttachRuntimeOptions): () => void;
getSnapshot(): DevtoolsSnapshot;
subscribe(listener: () => void): () => void;
pauseCapture(): void;
resumeCapture(): void;
refreshSnapshots(): void;
recordDelivery(input: DeliveryRecordInput): void;
clear(): void;
exportTrace(): DevtoolsTraceExportV1;
dispose(): void;
}StoreOptions — type
interface StoreOptions {
readonly maxEntries?: number;
}Public declarations: @generative-a11y/devtools/overlay
All exported values and types for this entry point. Import these names from @generative-a11y/devtools/overlay; the signatures below are reference material, not a replacement for the ownership and lifecycle guidance above.
mountOverlay — value
declare function mountOverlay(options: OverlayOptions): Overlay;Overlay — type
interface Overlay {
readonly host: HTMLElement;
dispose(): void;
}OverlayOptions — type
interface OverlayOptions {
readonly store: Store;
readonly document?: Document;
readonly copyText?: (value: string) => void | Promise<void>;
}