@generative-a11y/devtools 0.1.0

package/dist/index.d.ts

@@ -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 };

package/dist/index.js

@@ -0,0 +1,348 @@
+// src/index.ts
+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();
+    }
+  };
+}
+export {
+  createDevtoolsStore
+};