generative-a11y
GitHubnpm
Devtools

@generative-a11y/devtools

Create a bounded redacted diagnostic store and an explicit browser Accessibility Trace Explorer for development.

createDevtoolsStore

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.

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

const store = createDevtoolsStore({ maxEntries: 250 });
const detach = store.attachRuntime({ id: "support", runtime });
const snapshot = store.getSnapshot();
const trace = store.exportTrace();

detach();
store.dispose();

How this code works

  1. 01
    Bound retained records

    maxEntries defaults to 250 and must be a positive safe integer.

  2. 02
    Attach public diagnostics

    attachRuntime borrows subscribeDiagnosticEvents and getDiagnosticSnapshot from core.

  3. 03
    Read or export

    Snapshots and V1 trace exports are immutable and content-free.

  4. 04
    Release capture

    Detach the borrowed runtime before disposing the store.

Options and return values

createDevtoolsStore(options)DevtoolsStoreFunction

Creates an isolated store with bounded records and no attached runtimes.

Default
maxEntries: 250
attachRuntime({ id, runtime, source? })() => voidMethod

Attaches public core diagnostics under a stable ID and returns idempotent detach.

Default
n/a
sourceDevtoolsRuntimeSourceOptional attach option

Records the adapter name, documented public evidence, and declared fidelity supplied by the integration.

Default
undefined
recordDelivery(input)voidMethod

Adds validated content-free DOM delivery evidence correlated by safe IDs.

Default
n/a
exportTrace()DevtoolsTraceExportV1Method

Refreshes runtime snapshots and exports the schema-versioned redacted trace.

Default
n/a

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.

Options and return values

getSnapshot()DevtoolsSnapshotMethod

Returns a cached immutable view until captured state changes.

Default
n/a
subscribe(listener)() => voidMethod

Observes store changes with an idempotent unsubscribe function.

Default
n/a
pauseCapture() / resumeCapture()voidMethod

Controls diagnostic retention without changing the observed runtimes.

Default
n/a
refreshSnapshots()voidMethod

Requests fresh content-free snapshots from attached runtimes without changing their state.

Default
n/a
clear() / dispose()voidMethod

Clears captured state or releases all store-owned resources.

Default
n/a

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.

Options and return values

droppedCountnumberSnapshot and export

Counts records removed from the ring buffer since the last clear.

Default
0
runtimeSourceIdstringOptional record field

Connects a record to an immutable adapter evidence revision without copying that metadata into each record.

Default
undefined
recordsreadonly DevtoolsRecord[]Snapshot and export

Contains redacted events, decisions, and optional DOM delivery results in capture order.

Default
[]
runtimeSnapshotsReadonly<Record<string, RuntimeDiagnosticSnapshotV1>>Snapshot and export

Stores the latest content-free core snapshot for each attached runtime.

Default
{}
runtimeSourcesReadonly<Record<string, DevtoolsRuntimeSource>>Snapshot and export

Stores immutable adapter evidence revisions still referenced by retained records.

Default
{}

mountDevtoolsOverlay

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.

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

const overlay = mountDevtoolsOverlay({ store });
overlay.dispose();

How this code works

  1. 01
    Pass the store

    The overlay reads the store you created and does not attach a runtime itself.

  2. 02
    Mount explicitly

    Importing the package does not create browser UI or global shortcuts.

  3. 03
    Dispose the host

    dispose unmounts the workbench and removes the custom element.

Options and return values

storeDevtoolsStoreRequired

Supplies the captured records and control methods displayed by the overlay.

Default
n/a
documentDocumentOptional

Selects the document that receives the Shadow DOM host.

Default
global document
copyText(value) => void | Promise<void>Optional

Overrides trace copying for hosts that provide their own clipboard bridge.

Default
Clipboard API
hostHTMLElementReturn field

Exposes the mounted custom element for inspection or host-controlled placement.

Default
n/a
dispose()voidReturn method

Unmounts the workbench and removes its host. Repeated calls are safe.

Default
n/a