@generative-a11y/devtools 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bhavesh Chowdhury
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,151 @@
+# `@generative-a11y/devtools`
+
+Opt-in, development-only diagnostics for generative-a11y runtimes. The default
+headless store is framework-neutral, side-effect-free on import, and retains a
+bounded redacted trace: it stores categories, timing, outcomes, stable runtime
+IDs, queue/entity snapshots, and browser delivery metadata. It never retains
+assistant text, labels, error messages, tool data, stacks, or DOM content.
+
+```sh
+npm install --save-dev @generative-a11y/devtools
+```
+
+```ts
+import { createDevtoolsStore } from "@generative-a11y/devtools";
+import { THREAD_ADAPTER_METADATA } from "@generative-a11y/assistant-ui";
+
+const store = createDevtoolsStore({ maxEntries: 250 });
+const detach = store.attachRuntime({
+  id: "support",
+  runtime,
+  source: {
+    adapter: THREAD_ADAPTER_METADATA.name,
+    fidelity: THREAD_ADAPTER_METADATA.fidelity,
+    evidence: THREAD_ADAPTER_METADATA.observedRuntimeMethods,
+  },
+});
+const unsubscribe = store.subscribe(renderDiagnostics);
+
+store.pauseCapture(); // Does not pause or alter the runtime.
+store.resumeCapture();
+store.refreshSnapshots();
+const trace = store.exportTrace(); // schema-versioned and redacted
+store.clear();
+
+unsubscribe();
+detach();
+store.dispose();
+```
+
+## Store API
+
+- `createDevtoolsStore({ maxEntries })` creates an isolated store. `maxEntries`
+  defaults to `250`, must be a positive safe integer, and bounds the retained
+  ring buffer. `droppedCount` reports records evicted since the last `clear()`.
+- `attachRuntime({ id, runtime })` validates a non-empty ID, subscribes only to
+  public diagnostics, captures an initial safe snapshot, and returns an
+  idempotent detach function. Attaching the same ID replaces its subscription
+  only after the replacement subscribes successfully.
+- `subscribe(listener)` observes store snapshot changes and returns an
+  idempotent unsubscribe function. Listener failures do not alter capture.
+- `getSnapshot()` returns a cached, immutable, content-free view until captured
+  state changes. `refreshSnapshots()` explicitly requests fresh runtime
+  snapshots without changing the observed runtimes.
+- `pauseCapture()` and `resumeCapture()` change devtools capture only. They do
+  not pause scheduling, delivery, or any host runtime behavior.
+- `recordDelivery(input)` adds validated, content-free DOM delivery evidence. It
+  records nothing while capture is paused or after disposal, but malformed IDs
+  and timestamps still throw so integration defects remain visible.
+- `exportTrace()` refreshes runtime snapshots and returns an immutable,
+  schema-versioned, redacted trace. `clear()` removes retained records and
+  resets `droppedCount` without detaching runtimes.
+- `dispose()` is idempotent. It detaches all runtimes, clears captured state,
+  publishes one final empty snapshot to current subscribers, and then removes
+  those subscribers. Later attachment or subscription attempts throw; other
+  control methods are no-ops.
+
+The store only subscribes through `subscribeDiagnosticEvents()` and does not
+monkey-patch dispatch, access browser globals, create UI, retain a core history,
+or alter accessibility policy. A captured DOM/API delivery remains evidence of
+an action, not proof that assistive technology spoke it.
+
+## Declared adapter evidence
+
+Pass `source` when attaching a runtime driven by an adapter. This is an
+explicit, serializable declaration from the integration, not framework detection
+by devtools. It lets an inspector show the adapter name, documented public
+evidence and declared fidelity without filling gaps in the lifecycle trace.
+`interruption` and `retries` accept `exact`, `action-wrapper`, or `unavailable`.
+`connection` accepts those values plus `inferred`, because some integrations can
+only derive connection state from another documented public signal. The store
+freezes a copy of this metadata and includes it in its redacted export. Each
+captured record references an opaque `runtimeSourceId`. Source revisions remain
+immutable and exportable for as long as a retained record references them, even
+after a runtime detaches or the same runtime ID is reattached with different
+metadata. Unreferenced revisions are removed with ring-buffer eviction so
+repeated attachment cannot create unbounded source history.
+
+Use an adapter package's exported metadata where it fits the integration. For
+custom adapters, provide only public signals that justify normalized events. Do
+not put user content, internal URLs, or private framework state in `evidence`.
+The store accepts at most 12 public evidence strings, each at most 120
+characters, and rejects unsupported fidelity or optional-event values before it
+subscribes to a runtime.
+
+## Browser delivery correlation
+
+The store intentionally does not import `@generative-a11y/dom`. Connect the
+announcer's public diagnostic callback yourself to capture a content-free
+delivery record alongside runtime decisions:
+
+```ts
+const announcer = createDOMAnnouncer({
+  onDiagnostic(result) {
+    store.recordDelivery({ runtimeId: "support", result });
+  },
+});
+```
+
+This exposes the browser-level method and status (`aria-notify`, fallback live
+region, unavailable, or disposed) and safe correlation IDs. It still cannot
+establish what a screen reader announced.
+
+## Explicit overlay
+
+`@generative-a11y/devtools/overlay` is an optional browser-only mounting helper.
+It creates one open Shadow DOM host only when called and starts collapsed. The
+mounted workbench is built from package-local shadcn/Radix components, with its
+styles contained inside that Shadow DOM. It provides one searchable, filterable
+Accessibility Trace Explorer with a keyboard-managed trace list, selected causal
+evidence, plain-language policy and delivery context, collapsed raw metadata,
+capture pause/resume/clear/refresh actions, and explicit trace copy. These
+actions affect only devtools capture, never runtime policy, queueing, focus, or
+host UI.
+
+Opening the overlay moves focus into the workbench; closing it restores the
+element focused before the launcher was activated. Streaming records never move
+focus. The overlay does not trap focus, create a live region, modify host
+layout, or install global shortcuts.
+
+```ts
+import { mountDevtoolsOverlay } from "@generative-a11y/devtools/overlay";
+
+const overlay = mountDevtoolsOverlay({ store });
+overlay.dispose();
+```
+
+## Documentation
+
+- [Devtools guide](https://generativea11y.com/docs/devtools)
+- [API reference](https://generativea11y.com/api/devtools)
+- [Repository](https://github.com/bhaveshchow20/generative-a11y)
+
+## Related packages
+
+- [`@generative-a11y/core`](https://www.npmjs.com/package/@generative-a11y/core)
+  exposes the versioned diagnostic stream and content-free snapshots.
+- [`@generative-a11y/dom`](https://www.npmjs.com/package/@generative-a11y/dom)
+  exposes browser delivery results for safe correlation.
+- [`@generative-a11y/core/testing`](https://generativea11y.com/api/core/testing)
+  provides deterministic replay and semantic test assertions without another
+  package installation.

package/dist/index.cjs

@@ -0,0 +1,373 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  createDevtoolsStore: () => createDevtoolsStore
+});
+module.exports = __toCommonJS(index_exports);
+function asRecord(runtimeId, event, captureSequence, runtimeSourceId) {
+  if (event.kind === "event-observed") {
+    return Object.freeze({
+      runtimeId,
+      ...runtimeSourceId ? { runtimeSourceId } : {},
+      sequence: event.sequence,
+      captureSequence,
+      at: event.at,
+      kind: event.kind,
+      sourceType: event.event.type,
+      ...event.event.eventId ? { sourceEventId: event.event.eventId } : {},
+      ..."responseId" in event.event ? { responseId: event.event.responseId } : {},
+      ..."responseInstanceId" in event.event && event.event.responseInstanceId ? { responseInstanceId: event.event.responseInstanceId } : {},
+      ..."nextResponseInstanceId" in event.event && event.event.nextResponseInstanceId ? { nextResponseInstanceId: event.event.nextResponseInstanceId } : {},
+      ..."attempt" in event.event && event.event.attempt !== void 0 ? { attempt: event.event.attempt } : {},
+      ..."toolId" in event.event ? { toolId: event.event.toolId } : {},
+      ..."toolInstanceId" in event.event && event.event.toolInstanceId ? { toolInstanceId: event.event.toolInstanceId } : {},
+      ..."interactionId" in event.event ? { interactionId: event.event.interactionId } : {},
+      ..."approvalId" in event.event ? { approvalId: event.event.approvalId } : {},
+      ..."progress" in event.event && event.event.progress !== void 0 ? { progress: event.event.progress } : {},
+      ..."outcome" in event.event ? { outcome: event.event.outcome } : {},
+      ..."count" in event.event ? { count: event.event.count } : {}
+    });
+  }
+  return Object.freeze({
+    runtimeId,
+    ...runtimeSourceId ? { runtimeSourceId } : {},
+    sequence: event.sequence,
+    captureSequence,
+    at: event.at,
+    kind: event.kind,
+    ...event.decision.sourceType ? { sourceType: event.decision.sourceType } : {},
+    ...event.decision.sourceEventId ? { sourceEventId: event.decision.sourceEventId } : {},
+    disposition: event.decision.disposition,
+    reason: event.decision.reason,
+    ...event.decision.announcement ? { announcementId: event.decision.announcement.id } : {},
+    ...event.decision.announcement ? { channel: event.decision.announcement.channel } : {},
+    ...event.decision.responseId ? { responseId: event.decision.responseId } : {},
+    ...event.decision.toolId ? { toolId: event.decision.toolId } : {},
+    ...event.decision.interactionId ? { interactionId: event.decision.interactionId } : {},
+    ...event.decision.scheduledAt !== void 0 ? { scheduledAt: event.decision.scheduledAt } : {},
+    ...event.decision.dueAt !== void 0 ? { dueAt: event.decision.dueAt } : {},
+    ...event.decision.delayMs !== void 0 ? { delayMs: event.decision.delayMs } : {},
+    ...event.decision.queueSequence !== void 0 ? { queueSequence: event.decision.queueSequence } : {}
+  });
+}
+function copyRuntimeSource(source) {
+  if (source === void 0) return void 0;
+  if (typeof source.adapter !== "string" || !source.adapter.trim() || source.adapter.length > 80)
+    throw new TypeError("source adapter must be a non-empty string");
+  if (!Array.isArray(source.evidence))
+    throw new TypeError("source evidence must be an array");
+  if (source.evidence.length > 12 || source.evidence.some(
+    (item) => typeof item !== "string" || !item.trim() || item.length > 120
+  ))
+    throw new TypeError(
+      "source evidence entries must be public strings up to 120 characters"
+    );
+  const { fidelity } = source;
+  if (typeof fidelity !== "object" || fidelity === null)
+    throw new TypeError("source fidelity must be an object");
+  const lifecycleFidelity = /* @__PURE__ */ new Set(["exact", "action-wrapper", "unavailable"]);
+  const connectionFidelity = /* @__PURE__ */ new Set([...lifecycleFidelity, "inferred"]);
+  if (!lifecycleFidelity.has(fidelity.interruption))
+    throw new TypeError(
+      "source interruption fidelity contains an unsupported value"
+    );
+  if (!lifecycleFidelity.has(fidelity.retries))
+    throw new TypeError("source retry fidelity contains an unsupported value");
+  if (!connectionFidelity.has(fidelity.connection))
+    throw new TypeError(
+      "source connection fidelity contains an unsupported value"
+    );
+  const optionalEvents = fidelity.optionalEvents;
+  const validOptionalEvents = /* @__PURE__ */ new Set([
+    "tool.progress",
+    "tool.failed",
+    "citation.available",
+    "interaction.requested"
+  ]);
+  if (optionalEvents !== void 0 && (!Array.isArray(optionalEvents) || optionalEvents.some((event) => !validOptionalEvents.has(event))))
+    throw new TypeError("source optional events contain an unsupported value");
+  return Object.freeze({
+    adapter: source.adapter.trim(),
+    evidence: Object.freeze(source.evidence.map((item) => item.trim())),
+    fidelity: Object.freeze({
+      interruption: fidelity.interruption,
+      retries: fidelity.retries,
+      connection: fidelity.connection,
+      ...optionalEvents ? { optionalEvents: Object.freeze([...optionalEvents]) } : {}
+    })
+  });
+}
+function asDeliveryRecord(input, captureSequence, runtimeSourceId) {
+  const { result } = input;
+  return Object.freeze({
+    runtimeId: input.runtimeId,
+    ...runtimeSourceId ? { runtimeSourceId } : {},
+    captureSequence,
+    at: result.at,
+    kind: "dom-delivery",
+    sourceType: result.sourceType,
+    announcementId: result.announcementId,
+    channel: result.channel,
+    deliveryStatus: result.status,
+    deliveryMethod: result.method,
+    ...result.sourceEventId ? { sourceEventId: result.sourceEventId } : {},
+    ...result.responseId ? { responseId: result.responseId } : {},
+    ...result.toolId ? { toolId: result.toolId } : {},
+    ...result.interactionId ? { interactionId: result.interactionId } : {},
+    ...result.error?.name ? { errorName: result.error.name } : {}
+  });
+}
+function copyRuntimeSnapshot(source) {
+  return Object.freeze({
+    schemaVersion: 1,
+    at: source.at,
+    policy: Object.freeze({
+      ...source.policy,
+      text: Object.freeze({ ...source.policy.text }),
+      tools: Object.freeze({ ...source.policy.tools })
+    }),
+    pending: Object.freeze({
+      announcements: Object.freeze(
+        source.pending.announcements.map((item) => Object.freeze({ ...item }))
+      ),
+      flushes: Object.freeze(
+        source.pending.flushes.map((item) => Object.freeze({ ...item }))
+      )
+    }),
+    responses: Object.freeze(
+      source.responses.map((item) => Object.freeze({ ...item }))
+    ),
+    tools: Object.freeze(
+      source.tools.map((item) => Object.freeze({ ...item }))
+    ),
+    pendingCount: source.pendingCount
+  });
+}
+function createDevtoolsStore(options = {}) {
+  const maxEntries = options.maxEntries ?? 250;
+  if (!Number.isSafeInteger(maxEntries) || maxEntries <= 0)
+    throw new RangeError("maxEntries must be a positive safe integer");
+  const records = [];
+  const runtimes = /* @__PURE__ */ new Map();
+  const runtimeSources = /* @__PURE__ */ new Map();
+  const sourceRevisions = /* @__PURE__ */ new Map();
+  const runtimeSnapshots = /* @__PURE__ */ new Map();
+  const listeners = /* @__PURE__ */ new Set();
+  let paused = false;
+  let droppedCount = 0;
+  let nextCaptureSequence = 0;
+  let disposed = false;
+  let cachedSnapshot;
+  const notify = () => {
+    cachedSnapshot = void 0;
+    for (const listener of [...listeners]) {
+      try {
+        listener();
+      } catch {
+      }
+    }
+  };
+  const snapshot = () => {
+    if (cachedSnapshot) return cachedSnapshot;
+    const snapshots = Object.freeze(
+      Object.fromEntries(
+        [...runtimeSnapshots.entries()].sort(([left], [right]) => left.localeCompare(right)).map(([id, value]) => [id, value])
+      )
+    );
+    const sources = Object.freeze(
+      Object.fromEntries(
+        [...runtimeSources.entries()].sort(([left], [right]) => left.localeCompare(right)).map(([id, source]) => [id, source])
+      )
+    );
+    cachedSnapshot = Object.freeze({
+      paused,
+      droppedCount,
+      records: Object.freeze([...records]),
+      runtimeIds: Object.freeze([...runtimes.keys()].sort()),
+      runtimeSnapshots: snapshots,
+      runtimeSources: sources
+    });
+    return cachedSnapshot;
+  };
+  const refreshRuntimeSnapshot = (runtimeId, runtime) => {
+    try {
+      runtimeSnapshots.set(
+        runtimeId,
+        copyRuntimeSnapshot(runtime.getDiagnosticSnapshot())
+      );
+    } catch {
+    }
+  };
+  const refreshAllSnapshots = () => {
+    for (const [runtimeId, attachment] of runtimes)
+      refreshRuntimeSnapshot(runtimeId, attachment.runtime);
+  };
+  const appendRecord = (record) => {
+    if (records.length === maxEntries) {
+      records.shift();
+      droppedCount += 1;
+    }
+    records.push(record);
+  };
+  const pruneRuntimeSources = () => {
+    const retained = new Set(
+      records.flatMap(
+        (record) => record.runtimeSourceId ? [record.runtimeSourceId] : []
+      )
+    );
+    for (const attachment of runtimes.values())
+      if (attachment.sourceId) retained.add(attachment.sourceId);
+    for (const sourceId of runtimeSources.keys())
+      if (!retained.has(sourceId)) runtimeSources.delete(sourceId);
+  };
+  const capture = (runtimeId, runtime, runtimeSourceId, event) => {
+    if (paused || disposed) return;
+    appendRecord(
+      asRecord(runtimeId, event, nextCaptureSequence++, runtimeSourceId)
+    );
+    pruneRuntimeSources();
+    refreshRuntimeSnapshot(runtimeId, runtime);
+    notify();
+  };
+  return {
+    attachRuntime({ id, runtime, source }) {
+      if (disposed)
+        throw new Error("Cannot attach to a disposed devtools store");
+      if (!id.trim()) throw new TypeError("runtime id must be non-empty");
+      const copiedSource = copyRuntimeSource(source);
+      let revision = (sourceRevisions.get(id) ?? 0) + 1;
+      let sourceId = copiedSource ? revision === 1 ? id : `${id}#${revision}` : void 0;
+      while (sourceId && runtimeSources.has(sourceId)) {
+        revision += 1;
+        sourceId = `${id}#${revision}`;
+      }
+      let active = false;
+      const unsubscribe = runtime.subscribeDiagnosticEvents((event) => {
+        if (active) capture(id, runtime, sourceId, event);
+      });
+      const previous = runtimes.get(id);
+      const attachment = {
+        runtime,
+        unsubscribe,
+        source: copiedSource,
+        sourceId
+      };
+      active = true;
+      previous?.unsubscribe();
+      runtimes.set(id, attachment);
+      if (copiedSource && sourceId) {
+        runtimeSources.set(sourceId, copiedSource);
+        sourceRevisions.set(id, revision);
+      }
+      refreshRuntimeSnapshot(id, runtime);
+      pruneRuntimeSources();
+      notify();
+      let attached = true;
+      return () => {
+        if (!attached) return;
+        attached = false;
+        unsubscribe();
+        if (runtimes.get(id) === attachment) {
+          runtimes.delete(id);
+          runtimeSnapshots.delete(id);
+        }
+        pruneRuntimeSources();
+        notify();
+      };
+    },
+    getSnapshot: snapshot,
+    subscribe(listener) {
+      if (disposed)
+        throw new Error("Cannot subscribe to a disposed devtools store");
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    pauseCapture() {
+      if (disposed || paused) return;
+      paused = true;
+      notify();
+    },
+    resumeCapture() {
+      if (disposed || !paused) return;
+      paused = false;
+      notify();
+    },
+    refreshSnapshots() {
+      if (disposed) return;
+      refreshAllSnapshots();
+      notify();
+    },
+    recordDelivery(input) {
+      if (!input.runtimeId.trim())
+        throw new TypeError("delivery runtimeId must be non-empty");
+      if (!Number.isFinite(input.result.at))
+        throw new TypeError("delivery at must be finite");
+      if (paused || disposed) return;
+      appendRecord(
+        asDeliveryRecord(
+          input,
+          nextCaptureSequence++,
+          runtimes.get(input.runtimeId)?.sourceId
+        )
+      );
+      pruneRuntimeSources();
+      notify();
+    },
+    clear() {
+      if (disposed) return;
+      records.length = 0;
+      droppedCount = 0;
+      pruneRuntimeSources();
+      notify();
+    },
+    exportTrace() {
+      refreshAllSnapshots();
+      notify();
+      const current = snapshot();
+      return Object.freeze({
+        schemaVersion: 1,
+        kind: "generative-a11y/devtools-trace",
+        paused: current.paused,
+        droppedCount: current.droppedCount,
+        records: current.records,
+        runtimeSnapshots: current.runtimeSnapshots,
+        runtimeSources: current.runtimeSources
+      });
+    },
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      for (const { unsubscribe } of runtimes.values()) unsubscribe();
+      runtimes.clear();
+      runtimeSnapshots.clear();
+      runtimeSources.clear();
+      sourceRevisions.clear();
+      records.length = 0;
+      notify();
+      listeners.clear();
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createDevtoolsStore
+});

package/dist/index.d.cts

@@ -0,0 +1,106 @@
+import { GenerativeA11yRuntime, AdapterFidelity, RuntimeDiagnosticEventV1, RuntimeDiagnosticSnapshotV1 } from '@generative-a11y/core';
+
+type DevtoolsRecordKind = RuntimeDiagnosticEventV1["kind"] | "dom-delivery";
+interface DevtoolsRecord {
+    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;
+    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;
+}
+/**
+ * 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<Omit<AdapterFidelity, "optionalEvents"> & {
+        readonly optionalEvents?: readonly NonNullable<AdapterFidelity["optionalEvents"]>[number][];
+    }>;
+}
+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;
+        readonly error?: {
+            readonly name: string;
+            readonly message?: string;
+        };
+    };
+}
+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>>;
+}
+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>>;
+}
+interface DevtoolsStoreOptions {
+    readonly maxEntries?: number;
+}
+interface AttachRuntimeOptions {
+    readonly id: string;
+    readonly runtime: Pick<GenerativeA11yRuntime, "subscribeDiagnosticEvents" | "getDiagnosticSnapshot">;
+    readonly source?: DevtoolsRuntimeSource;
+}
+interface DevtoolsStore {
+    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;
+}
+declare function createDevtoolsStore(options?: DevtoolsStoreOptions): DevtoolsStore;
+
+export { type AttachRuntimeOptions, type DeliveryRecordInput, type DevtoolsRecord, type DevtoolsRecordKind, type DevtoolsRuntimeSource, type DevtoolsSnapshot, type DevtoolsStore, type DevtoolsStoreOptions, type DevtoolsTraceExportV1, createDevtoolsStore };