npm - @generative-a11y/devtools - Versions diffs - 0.1.0 → 0.2.0 - Mend

@generative-a11y/devtools 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (10) hide show

package/README.md CHANGED Viewed

@@ -11,17 +11,17 @@ npm install --save-dev @generative-a11y/devtools
 ```
 ```ts
-import { createDevtoolsStore } from "@generative-a11y/devtools";
-import { THREAD_ADAPTER_METADATA } from "@generative-a11y/assistant-ui";
+import { createStore } from "@generative-a11y/devtools";
+import { adapterInfo } from "@generative-a11y/assistant-ui";
-const store = createDevtoolsStore({ maxEntries: 250 });
+const store = createStore({ 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,
+    adapter: adapterInfo.name,
+    fidelity: adapterInfo.fidelity,
+    evidence: adapterInfo.observedRuntimeMethods,
   },
 });
 const unsubscribe = store.subscribe(renderDiagnostics);
@@ -39,9 +39,9 @@ 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()`.
+- `createStore({ 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
@@ -75,15 +75,20 @@ 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.
+Workflow fidelity distinguishes runs, steps, hierarchy, tools, interactions,
+replay, reconnection, and unsupported custom events as exact, partial, or
+unavailable where applicable. The inspector also shows content-free run and step
+parentage, attempt boundaries, active or terminal state, and associated entity
+IDs from the core diagnostic snapshot. `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
@@ -95,15 +100,30 @@ 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
+active binding's `onDelivery` callback yourself to capture a content-free
 delivery record alongside runtime decisions:
 ```ts
-const announcer = createDOMAnnouncer({
-  onDiagnostic(result) {
+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();
+}
 ```
 This exposes the browser-level method and status (`aria-notify`, fallback live
@@ -128,12 +148,28 @@ 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";
+import { mountOverlay } from "@generative-a11y/devtools/overlay";
-const overlay = mountDevtoolsOverlay({ store });
-overlay.dispose();
+const overlay = mountOverlay({ store });
+// Call overlay.dispose() when removing the workbench.
 ```
+## Attention decisions
+When core attention control is enabled, runtime snapshots include the observed
+mode, explicit user override, and effective normal/quiet state. The inspector
+shows these values under policy and scheduling. `attention-updated` explains
+control transitions; `attention-quiet` explains discarded routine output without
+an announcement backlog.
+`DevtoolsRecord.attentionMode` and `attentionOverride` preserve only recognized
+enum values from control events. Invalid mode payloads are omitted. Exports
+contain no DOM targets or reading history; the observation named
+`reading-history` means only the latest registered response is outside the
+intersection while the document is visible and focused. It does not track a
+screen-reader virtual cursor or prove what someone read. Existing trace schema 1
+consumers can ignore the optional fields.
 ## Documentation
 - [Devtools guide](https://generativea11y.com/docs/devtools)
@@ -149,3 +185,17 @@ overlay.dispose();
 - [`@generative-a11y/core/testing`](https://generativea11y.com/api/core/testing)
   provides deterministic replay and semantic test assertions without another
   package installation.
+## Localized announcements
+Runtime snapshots include optional `messages: { catalogId, locale }`. The
+inspector exposes only these fields and `catalog-format-error`; catalog
+messages, formatter arguments/functions and error text are not retained. Use a
+non-sensitive catalog ID.
+See the
+[localization guide](https://generativea11y.com/docs/localized-announcements).
+For React, pass the same callback through
+`<A11yProvider delivery={{ onDelivery }}>`. Do not create another announcer
+beside the provider; its existing delivery path supplies the reports.

package/dist/index.cjs CHANGED Viewed

@@ -20,7 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  createDevtoolsStore: () => createDevtoolsStore
+  createStore: () => createStore
 });
 module.exports = __toCommonJS(index_exports);
 function asRecord(runtimeId, event, captureSequence, runtimeSourceId) {
@@ -33,7 +33,27 @@ function asRecord(runtimeId, event, captureSequence, runtimeSourceId) {
       at: event.at,
       kind: event.kind,
       sourceType: event.event.type,
+      ...event.event.type === "attention.changed" && [
+        "foreground",
+        "background",
+        "reading-history",
+        "away",
+        "unknown"
+      ].includes(event.event.mode) ? { attentionMode: event.event.mode } : {},
+      ...event.event.type === "attention.override" && ["auto", "normal", "quiet"].includes(event.event.mode) ? { attentionOverride: event.event.mode } : {},
       ...event.event.eventId ? { sourceEventId: event.event.eventId } : {},
+      ..."runId" in event.event && event.event.runId ? { runId: event.event.runId } : {},
+      ..."runInstanceId" in event.event && event.event.runInstanceId ? { runInstanceId: event.event.runInstanceId } : {},
+      ..."nextRunInstanceId" in event.event && event.event.nextRunInstanceId ? { nextRunInstanceId: event.event.nextRunInstanceId } : {},
+      ..."parentRunId" in event.event && event.event.parentRunId ? { parentRunId: event.event.parentRunId } : {},
+      ..."parentRunInstanceId" in event.event && event.event.parentRunInstanceId ? { parentRunInstanceId: event.event.parentRunInstanceId } : {},
+      ..."stepId" in event.event && event.event.stepId ? { stepId: event.event.stepId } : {},
+      ..."stepInstanceId" in event.event && event.event.stepInstanceId ? { stepInstanceId: event.event.stepInstanceId } : {},
+      ..."nextStepInstanceId" in event.event && event.event.nextStepInstanceId ? { nextStepInstanceId: event.event.nextStepInstanceId } : {},
+      ..."parentStepId" in event.event && event.event.parentStepId ? { parentStepId: event.event.parentStepId } : {},
+      ..."parentStepInstanceId" in event.event && event.event.parentStepInstanceId ? { parentStepInstanceId: event.event.parentStepInstanceId } : {},
+      ..."parentToolId" in event.event && event.event.parentToolId ? { parentToolId: event.event.parentToolId } : {},
+      ..."parentResponseId" in event.event && event.event.parentResponseId ? { parentResponseId: event.event.parentResponseId } : {},
       ..."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 } : {},
@@ -63,6 +83,10 @@ function asRecord(runtimeId, event, captureSequence, runtimeSourceId) {
     ...event.decision.responseId ? { responseId: event.decision.responseId } : {},
     ...event.decision.toolId ? { toolId: event.decision.toolId } : {},
     ...event.decision.interactionId ? { interactionId: event.decision.interactionId } : {},
+    ...event.decision.runId ? { runId: event.decision.runId } : {},
+    ...event.decision.runInstanceId ? { runInstanceId: event.decision.runInstanceId } : {},
+    ...event.decision.stepId ? { stepId: event.decision.stepId } : {},
+    ...event.decision.stepInstanceId ? { stepInstanceId: event.decision.stepInstanceId } : {},
     ...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 } : {},
@@ -86,6 +110,25 @@ function copyRuntimeSource(source) {
     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"]);
+  const workflowFidelity = /* @__PURE__ */ new Set(["exact", "partial", "unavailable"]);
+  for (const field of [
+    "runs",
+    "steps",
+    "hierarchy",
+    "tools",
+    "interactions",
+    "replay",
+    "reconnection"
+  ]) {
+    if (fidelity[field] !== void 0 && !workflowFidelity.has(fidelity[field]))
+      throw new TypeError(
+        `source ${field} fidelity contains an unsupported value`
+      );
+  }
+  if (fidelity.customEvents !== void 0 && fidelity.customEvents !== "explicit-mapping" && fidelity.customEvents !== "unsupported")
+    throw new TypeError(
+      "source custom event fidelity contains an unsupported value"
+    );
   if (!lifecycleFidelity.has(fidelity.interruption))
     throw new TypeError(
       "source interruption fidelity contains an unsupported value"
@@ -109,6 +152,14 @@ function copyRuntimeSource(source) {
     adapter: source.adapter.trim(),
     evidence: Object.freeze(source.evidence.map((item) => item.trim())),
     fidelity: Object.freeze({
+      ...fidelity.runs ? { runs: fidelity.runs } : {},
+      ...fidelity.steps ? { steps: fidelity.steps } : {},
+      ...fidelity.hierarchy ? { hierarchy: fidelity.hierarchy } : {},
+      ...fidelity.tools ? { tools: fidelity.tools } : {},
+      ...fidelity.interactions ? { interactions: fidelity.interactions } : {},
+      ...fidelity.replay ? { replay: fidelity.replay } : {},
+      ...fidelity.reconnection ? { reconnection: fidelity.reconnection } : {},
+      ...fidelity.customEvents ? { customEvents: fidelity.customEvents } : {},
       interruption: fidelity.interruption,
       retries: fidelity.retries,
       connection: fidelity.connection,
@@ -133,6 +184,10 @@ function asDeliveryRecord(input, captureSequence, runtimeSourceId) {
     ...result.responseId ? { responseId: result.responseId } : {},
     ...result.toolId ? { toolId: result.toolId } : {},
     ...result.interactionId ? { interactionId: result.interactionId } : {},
+    ...result.runId ? { runId: result.runId } : {},
+    ...result.runInstanceId ? { runInstanceId: result.runInstanceId } : {},
+    ...result.stepId ? { stepId: result.stepId } : {},
+    ...result.stepInstanceId ? { stepInstanceId: result.stepInstanceId } : {},
     ...result.error?.name ? { errorName: result.error.name } : {}
   });
 }
@@ -143,8 +198,28 @@ function copyRuntimeSnapshot(source) {
     policy: Object.freeze({
       ...source.policy,
       text: Object.freeze({ ...source.policy.text }),
-      tools: Object.freeze({ ...source.policy.tools })
+      tools: Object.freeze({ ...source.policy.tools }),
+      workflows: Object.freeze({ ...source.policy.workflows }),
+      ...source.policy.attention ? {
+        attention: Object.freeze({
+          ...source.policy.attention,
+          quietWhen: Object.freeze([...source.policy.attention.quietWhen])
+        })
+      } : {}
     }),
+    ...source.messages ? {
+      messages: Object.freeze({
+        catalogId: source.messages.catalogId,
+        locale: source.messages.locale
+      })
+    } : {},
+    ...source.attention ? {
+      attention: Object.freeze({
+        observed: source.attention.observed,
+        override: source.attention.override,
+        effective: source.attention.effective
+      })
+    } : {},
     pending: Object.freeze({
       announcements: Object.freeze(
         source.pending.announcements.map((item) => Object.freeze({ ...item }))
@@ -159,10 +234,20 @@ function copyRuntimeSnapshot(source) {
     tools: Object.freeze(
       source.tools.map((item) => Object.freeze({ ...item }))
     ),
+    ...source.runs ? {
+      runs: Object.freeze(
+        source.runs.map((item) => Object.freeze({ ...item }))
+      )
+    } : {},
+    ...source.steps ? {
+      steps: Object.freeze(
+        source.steps.map((item) => Object.freeze({ ...item }))
+      )
+    } : {},
     pendingCount: source.pendingCount
   });
 }
-function createDevtoolsStore(options = {}) {
+function createStore(options = {}) {
   const maxEntries = options.maxEntries ?? 250;
   if (!Number.isSafeInteger(maxEntries) || maxEntries <= 0)
     throw new RangeError("maxEntries must be a positive safe integer");
@@ -369,5 +454,5 @@ function createDevtoolsStore(options = {}) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  createDevtoolsStore
+  createStore
 });

package/dist/index.d.cts CHANGED Viewed

@@ -1,7 +1,9 @@
-import { GenerativeA11yRuntime, AdapterFidelity, RuntimeDiagnosticEventV1, RuntimeDiagnosticSnapshotV1 } from '@generative-a11y/core';
+import { Runtime, AdapterFidelity, AttentionMode, AttentionOverride, RuntimeDiagnosticEventV1, RuntimeDiagnosticSnapshotV1 } from '@generative-a11y/core';
 type DevtoolsRecordKind = RuntimeDiagnosticEventV1["kind"] | "dom-delivery";
 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;
@@ -22,6 +24,30 @@ interface DevtoolsRecord {
     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;
@@ -41,7 +67,7 @@ interface DevtoolsRecord {
 interface DevtoolsRuntimeSource {
     readonly adapter: string;
     readonly evidence: readonly string[];
-    readonly fidelity: Readonly<Omit<AdapterFidelity, "optionalEvents"> & {
+    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][];
     }>;
 }
@@ -58,6 +84,14 @@ interface DeliveryRecordInput {
         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;
@@ -81,15 +115,15 @@ interface DevtoolsTraceExportV1 {
     readonly runtimeSnapshots: Readonly<Record<string, RuntimeDiagnosticSnapshotV1>>;
     readonly runtimeSources: Readonly<Record<string, DevtoolsRuntimeSource>>;
 }
-interface DevtoolsStoreOptions {
+interface StoreOptions {
     readonly maxEntries?: number;
 }
 interface AttachRuntimeOptions {
     readonly id: string;
-    readonly runtime: Pick<GenerativeA11yRuntime, "subscribeDiagnosticEvents" | "getDiagnosticSnapshot">;
+    readonly runtime: Pick<Runtime, "subscribeDiagnosticEvents" | "getDiagnosticSnapshot">;
     readonly source?: DevtoolsRuntimeSource;
 }
-interface DevtoolsStore {
+interface Store {
     attachRuntime(options: AttachRuntimeOptions): () => void;
     getSnapshot(): DevtoolsSnapshot;
     subscribe(listener: () => void): () => void;
@@ -101,6 +135,6 @@ interface DevtoolsStore {
     exportTrace(): DevtoolsTraceExportV1;
     dispose(): void;
 }
-declare function createDevtoolsStore(options?: DevtoolsStoreOptions): DevtoolsStore;
+declare function createStore(options?: StoreOptions): Store;
-export { type AttachRuntimeOptions, type DeliveryRecordInput, type DevtoolsRecord, type DevtoolsRecordKind, type DevtoolsRuntimeSource, type DevtoolsSnapshot, type DevtoolsStore, type DevtoolsStoreOptions, type DevtoolsTraceExportV1, createDevtoolsStore };
+export { type AttachRuntimeOptions, type DeliveryRecordInput, type DevtoolsRecord, type DevtoolsRecordKind, type DevtoolsRuntimeSource, type DevtoolsSnapshot, type DevtoolsTraceExportV1, type Store, type StoreOptions, createStore };

package/dist/index.d.ts CHANGED Viewed

@@ -1,7 +1,9 @@
-import { GenerativeA11yRuntime, AdapterFidelity, RuntimeDiagnosticEventV1, RuntimeDiagnosticSnapshotV1 } from '@generative-a11y/core';
+import { Runtime, AdapterFidelity, AttentionMode, AttentionOverride, RuntimeDiagnosticEventV1, RuntimeDiagnosticSnapshotV1 } from '@generative-a11y/core';
 type DevtoolsRecordKind = RuntimeDiagnosticEventV1["kind"] | "dom-delivery";
 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;
@@ -22,6 +24,30 @@ interface DevtoolsRecord {
     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;
@@ -41,7 +67,7 @@ interface DevtoolsRecord {
 interface DevtoolsRuntimeSource {
     readonly adapter: string;
     readonly evidence: readonly string[];
-    readonly fidelity: Readonly<Omit<AdapterFidelity, "optionalEvents"> & {
+    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][];
     }>;
 }
@@ -58,6 +84,14 @@ interface DeliveryRecordInput {
         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;
@@ -81,15 +115,15 @@ interface DevtoolsTraceExportV1 {
     readonly runtimeSnapshots: Readonly<Record<string, RuntimeDiagnosticSnapshotV1>>;
     readonly runtimeSources: Readonly<Record<string, DevtoolsRuntimeSource>>;
 }
-interface DevtoolsStoreOptions {
+interface StoreOptions {
     readonly maxEntries?: number;
 }
 interface AttachRuntimeOptions {
     readonly id: string;
-    readonly runtime: Pick<GenerativeA11yRuntime, "subscribeDiagnosticEvents" | "getDiagnosticSnapshot">;
+    readonly runtime: Pick<Runtime, "subscribeDiagnosticEvents" | "getDiagnosticSnapshot">;
     readonly source?: DevtoolsRuntimeSource;
 }
-interface DevtoolsStore {
+interface Store {
     attachRuntime(options: AttachRuntimeOptions): () => void;
     getSnapshot(): DevtoolsSnapshot;
     subscribe(listener: () => void): () => void;
@@ -101,6 +135,6 @@ interface DevtoolsStore {
     exportTrace(): DevtoolsTraceExportV1;
     dispose(): void;
 }
-declare function createDevtoolsStore(options?: DevtoolsStoreOptions): DevtoolsStore;
+declare function createStore(options?: StoreOptions): Store;
-export { type AttachRuntimeOptions, type DeliveryRecordInput, type DevtoolsRecord, type DevtoolsRecordKind, type DevtoolsRuntimeSource, type DevtoolsSnapshot, type DevtoolsStore, type DevtoolsStoreOptions, type DevtoolsTraceExportV1, createDevtoolsStore };
+export { type AttachRuntimeOptions, type DeliveryRecordInput, type DevtoolsRecord, type DevtoolsRecordKind, type DevtoolsRuntimeSource, type DevtoolsSnapshot, type DevtoolsTraceExportV1, type Store, type StoreOptions, createStore };

package/dist/index.js CHANGED Viewed

@@ -9,7 +9,27 @@ function asRecord(runtimeId, event, captureSequence, runtimeSourceId) {
       at: event.at,
       kind: event.kind,
       sourceType: event.event.type,
+      ...event.event.type === "attention.changed" && [
+        "foreground",
+        "background",
+        "reading-history",
+        "away",
+        "unknown"
+      ].includes(event.event.mode) ? { attentionMode: event.event.mode } : {},
+      ...event.event.type === "attention.override" && ["auto", "normal", "quiet"].includes(event.event.mode) ? { attentionOverride: event.event.mode } : {},
       ...event.event.eventId ? { sourceEventId: event.event.eventId } : {},
+      ..."runId" in event.event && event.event.runId ? { runId: event.event.runId } : {},
+      ..."runInstanceId" in event.event && event.event.runInstanceId ? { runInstanceId: event.event.runInstanceId } : {},
+      ..."nextRunInstanceId" in event.event && event.event.nextRunInstanceId ? { nextRunInstanceId: event.event.nextRunInstanceId } : {},
+      ..."parentRunId" in event.event && event.event.parentRunId ? { parentRunId: event.event.parentRunId } : {},
+      ..."parentRunInstanceId" in event.event && event.event.parentRunInstanceId ? { parentRunInstanceId: event.event.parentRunInstanceId } : {},
+      ..."stepId" in event.event && event.event.stepId ? { stepId: event.event.stepId } : {},
+      ..."stepInstanceId" in event.event && event.event.stepInstanceId ? { stepInstanceId: event.event.stepInstanceId } : {},
+      ..."nextStepInstanceId" in event.event && event.event.nextStepInstanceId ? { nextStepInstanceId: event.event.nextStepInstanceId } : {},
+      ..."parentStepId" in event.event && event.event.parentStepId ? { parentStepId: event.event.parentStepId } : {},
+      ..."parentStepInstanceId" in event.event && event.event.parentStepInstanceId ? { parentStepInstanceId: event.event.parentStepInstanceId } : {},
+      ..."parentToolId" in event.event && event.event.parentToolId ? { parentToolId: event.event.parentToolId } : {},
+      ..."parentResponseId" in event.event && event.event.parentResponseId ? { parentResponseId: event.event.parentResponseId } : {},
       ..."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 } : {},
@@ -39,6 +59,10 @@ function asRecord(runtimeId, event, captureSequence, runtimeSourceId) {
     ...event.decision.responseId ? { responseId: event.decision.responseId } : {},
     ...event.decision.toolId ? { toolId: event.decision.toolId } : {},
     ...event.decision.interactionId ? { interactionId: event.decision.interactionId } : {},
+    ...event.decision.runId ? { runId: event.decision.runId } : {},
+    ...event.decision.runInstanceId ? { runInstanceId: event.decision.runInstanceId } : {},
+    ...event.decision.stepId ? { stepId: event.decision.stepId } : {},
+    ...event.decision.stepInstanceId ? { stepInstanceId: event.decision.stepInstanceId } : {},
     ...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 } : {},
@@ -62,6 +86,25 @@ function copyRuntimeSource(source) {
     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"]);
+  const workflowFidelity = /* @__PURE__ */ new Set(["exact", "partial", "unavailable"]);
+  for (const field of [
+    "runs",
+    "steps",
+    "hierarchy",
+    "tools",
+    "interactions",
+    "replay",
+    "reconnection"
+  ]) {
+    if (fidelity[field] !== void 0 && !workflowFidelity.has(fidelity[field]))
+      throw new TypeError(
+        `source ${field} fidelity contains an unsupported value`
+      );
+  }
+  if (fidelity.customEvents !== void 0 && fidelity.customEvents !== "explicit-mapping" && fidelity.customEvents !== "unsupported")
+    throw new TypeError(
+      "source custom event fidelity contains an unsupported value"
+    );
   if (!lifecycleFidelity.has(fidelity.interruption))
     throw new TypeError(
       "source interruption fidelity contains an unsupported value"
@@ -85,6 +128,14 @@ function copyRuntimeSource(source) {
     adapter: source.adapter.trim(),
     evidence: Object.freeze(source.evidence.map((item) => item.trim())),
     fidelity: Object.freeze({
+      ...fidelity.runs ? { runs: fidelity.runs } : {},
+      ...fidelity.steps ? { steps: fidelity.steps } : {},
+      ...fidelity.hierarchy ? { hierarchy: fidelity.hierarchy } : {},
+      ...fidelity.tools ? { tools: fidelity.tools } : {},
+      ...fidelity.interactions ? { interactions: fidelity.interactions } : {},
+      ...fidelity.replay ? { replay: fidelity.replay } : {},
+      ...fidelity.reconnection ? { reconnection: fidelity.reconnection } : {},
+      ...fidelity.customEvents ? { customEvents: fidelity.customEvents } : {},
       interruption: fidelity.interruption,
       retries: fidelity.retries,
       connection: fidelity.connection,
@@ -109,6 +160,10 @@ function asDeliveryRecord(input, captureSequence, runtimeSourceId) {
     ...result.responseId ? { responseId: result.responseId } : {},
     ...result.toolId ? { toolId: result.toolId } : {},
     ...result.interactionId ? { interactionId: result.interactionId } : {},
+    ...result.runId ? { runId: result.runId } : {},
+    ...result.runInstanceId ? { runInstanceId: result.runInstanceId } : {},
+    ...result.stepId ? { stepId: result.stepId } : {},
+    ...result.stepInstanceId ? { stepInstanceId: result.stepInstanceId } : {},
     ...result.error?.name ? { errorName: result.error.name } : {}
   });
 }
@@ -119,8 +174,28 @@ function copyRuntimeSnapshot(source) {
     policy: Object.freeze({
       ...source.policy,
       text: Object.freeze({ ...source.policy.text }),
-      tools: Object.freeze({ ...source.policy.tools })
+      tools: Object.freeze({ ...source.policy.tools }),
+      workflows: Object.freeze({ ...source.policy.workflows }),
+      ...source.policy.attention ? {
+        attention: Object.freeze({
+          ...source.policy.attention,
+          quietWhen: Object.freeze([...source.policy.attention.quietWhen])
+        })
+      } : {}
     }),
+    ...source.messages ? {
+      messages: Object.freeze({
+        catalogId: source.messages.catalogId,
+        locale: source.messages.locale
+      })
+    } : {},
+    ...source.attention ? {
+      attention: Object.freeze({
+        observed: source.attention.observed,
+        override: source.attention.override,
+        effective: source.attention.effective
+      })
+    } : {},
     pending: Object.freeze({
       announcements: Object.freeze(
         source.pending.announcements.map((item) => Object.freeze({ ...item }))
@@ -135,10 +210,20 @@ function copyRuntimeSnapshot(source) {
     tools: Object.freeze(
       source.tools.map((item) => Object.freeze({ ...item }))
     ),
+    ...source.runs ? {
+      runs: Object.freeze(
+        source.runs.map((item) => Object.freeze({ ...item }))
+      )
+    } : {},
+    ...source.steps ? {
+      steps: Object.freeze(
+        source.steps.map((item) => Object.freeze({ ...item }))
+      )
+    } : {},
     pendingCount: source.pendingCount
   });
 }
-function createDevtoolsStore(options = {}) {
+function createStore(options = {}) {
   const maxEntries = options.maxEntries ?? 250;
   if (!Number.isSafeInteger(maxEntries) || maxEntries <= 0)
     throw new RangeError("maxEntries must be a positive safe integer");
@@ -344,5 +429,5 @@ function createDevtoolsStore(options = {}) {
   };
 }
 export {
-  createDevtoolsStore
+  createStore
 };

package/dist/overlay.cjs CHANGED Viewed

@@ -30,7 +30,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/overlay.ts
 var overlay_exports = {};
 __export(overlay_exports, {
-  mountDevtoolsOverlay: () => mountDevtoolsOverlay
+  mountOverlay: () => mountOverlay
 });
 module.exports = __toCommonJS(overlay_exports);
 var import_react2 = require("react");
@@ -226,23 +226,65 @@ var key = (record) => String(record.captureSequence);
 var time = (value) => value >= 1e10 ? new Date(value).toISOString().slice(11, 23) : `+${(value / 1e3).toFixed(2)}s`;
 var stage = (record) => record.kind === "event-observed" ? "Source evidence" : record.kind === "decision" ? "Runtime decision" : "DOM delivery";
 var title = (record) => record.kind === "event-observed" ? record.sourceType ?? "Observed event" : record.kind === "dom-delivery" ? `${record.deliveryStatus ?? "Delivery"} via ${record.deliveryMethod ?? "browser"}` : record.reason ?? record.disposition ?? "Runtime decision";
-function correlation(record) {
+function correlationKeys(record) {
   const prefix = `${record.runtimeId}:`;
-  if (record.sourceEventId) return `${prefix}event:${record.sourceEventId}`;
-  if (record.responseId)
-    return `${prefix}response:${record.responseId}:${record.sourceType ?? "unknown"}`;
-  if (record.toolId)
-    return `${prefix}tool:${record.toolId}:${record.sourceType ?? "unknown"}`;
+  const keys = /* @__PURE__ */ new Set();
+  if (record.sourceEventId) keys.add(`${prefix}event:${record.sourceEventId}`);
+  if (record.responseId) keys.add(`${prefix}response:${record.responseId}`);
+  if (record.toolId) keys.add(`${prefix}tool:${record.toolId}`);
   if (record.interactionId)
-    return `${prefix}interaction:${record.interactionId}`;
-  if (record.approvalId) return `${prefix}approval:${record.approvalId}`;
+    keys.add(`${prefix}interaction:${record.interactionId}`);
+  if (record.approvalId) keys.add(`${prefix}approval:${record.approvalId}`);
   if (record.announcementId)
-    return `${prefix}announcement:${record.announcementId}`;
-  return `${prefix}record:${record.captureSequence}`;
+    keys.add(`${prefix}announcement:${record.announcementId}`);
+  if (record.runId)
+    keys.add(
+      `${prefix}run:${record.runId}:${record.runInstanceId ?? "unidentified"}`
+    );
+  if (record.runId && record.nextRunInstanceId)
+    keys.add(`${prefix}run:${record.runId}:${record.nextRunInstanceId}`);
+  if (record.parentRunId)
+    keys.add(
+      `${prefix}run:${record.parentRunId}:${record.parentRunInstanceId ?? "unidentified"}`
+    );
+  if (record.stepId)
+    keys.add(
+      `${prefix}step:${record.runId ?? "unknown"}:${record.runInstanceId ?? "unidentified"}:${record.stepId}:${record.stepInstanceId ?? "unidentified"}`
+    );
+  if (record.stepId && record.nextStepInstanceId)
+    keys.add(
+      `${prefix}step:${record.runId ?? "unknown"}:${record.runInstanceId ?? "unidentified"}:${record.stepId}:${record.nextStepInstanceId}`
+    );
+  if (record.parentStepId)
+    keys.add(
+      `${prefix}step:${record.runId ?? "unknown"}:${record.runInstanceId ?? "unidentified"}:${record.parentStepId}:${record.parentStepInstanceId ?? "unidentified"}`
+    );
+  if (record.parentToolId) keys.add(`${prefix}tool:${record.parentToolId}`);
+  if (record.parentResponseId)
+    keys.add(`${prefix}response:${record.parentResponseId}`);
+  if (keys.size === 0) keys.add(`${prefix}record:${record.captureSequence}`);
+  return [...keys];
+}
+function relatedRecords(records, selected) {
+  const related = /* @__PURE__ */ new Set();
+  const keys = new Set(correlationKeys(selected));
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const record of records) {
+      if (related.has(record)) continue;
+      const recordKeys = correlationKeys(record);
+      if (!recordKeys.some((value) => keys.has(value))) continue;
+      related.add(record);
+      for (const value of recordKeys) keys.add(value);
+      changed = true;
+    }
+  }
+  return [...related];
 }
 function explain(record) {
   if (record.kind === "event-observed")
-    return "The adapter supplied this normalized public lifecycle signal.";
+    return record.sourceType?.startsWith("attention.") ? "The host supplied an attention observation or explicit user override. Browser evidence does not establish what someone is reading." : "The adapter supplied this normalized public lifecycle signal.";
   if (record.kind === "dom-delivery")
     return record.deliveryStatus === "unavailable" ? "The DOM driver was unavailable, so no browser delivery action was observed." : "The DOM driver reported this delivery action.";
   return {
@@ -250,6 +292,9 @@ function explain(record) {
     coalesced: "The runtime merged this work with an existing queued announcement.",
     duplicate: "The runtime suppressed a recently delivered duplicate.",
     "policy-silent": "The active policy intentionally made this event silent.",
+    "catalog-format-error": "The host message formatter failed; the runtime used a generic English notice without retaining the error or parameters.",
+    "attention-quiet": "Quiet mode discarded routine output without retaining an announcement backlog.",
+    "attention-updated": "The runtime updated its attention observation or user override without announcing the control event.",
     "queue-capacity": "The bounded queue rejected or displaced this work.",
     "scope-cancelled": "The lifecycle scope ended before this queued work delivered.",
     "runtime-disposed": "The runtime was disposed and cancelled remaining queued work.",
@@ -302,6 +347,12 @@ function Detail({
     ] }) });
   const source = snapshot.runtimeSources[record.runtimeSourceId ?? record.runtimeId];
   const runtime = snapshot.runtimeSnapshots[record.runtimeId];
+  const run = record.runInstanceId ? runtime?.runs?.find(
+    (item) => item.runId === record.runId && item.instanceId === record.runInstanceId
+  ) : void 0;
+  const step = record.runInstanceId && record.stepInstanceId ? runtime?.steps?.find(
+    (item) => item.runId === record.runId && item.stepId === record.stepId && item.runInstanceId === record.runInstanceId && item.instanceId === record.stepInstanceId
+  ) : void 0;
   const deliveries = related.filter((item) => item.kind === "dom-delivery");
   return /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)("aside", { className: "ga-trace-detail", "data-testid": "trace-detail", children: [
     /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)("div", { className: "ga-detail-intro", children: [
@@ -314,6 +365,43 @@ function Detail({
       /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("p", { children: record.reason?.startsWith("stale") ? "Compare the instance with the current runtime snapshot." : "Inspect related evidence and queue context if this was unexpected." })
     ] }),
     /* @__PURE__ */ (0, import_jsx_runtime5.jsx)(CausalChain, { records: related }),
+    record.runId ? /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)("section", { className: "ga-detail-section", children: [
+      /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("h4", { children: "Workflow hierarchy" }),
+      /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)("dl", { className: "ga-key-values", children: [
+        /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)("div", { children: [
+          /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("dt", { children: "Run" }),
+          /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("dd", { children: record.runId })
+        ] }),
+        /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)("div", { children: [
+          /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("dt", { children: "Run attempt" }),
+          /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("dd", { children: record.runInstanceId ?? run?.instanceId ?? "Not supplied" })
+        ] }),
+        /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)("div", { children: [
+          /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("dt", { children: "Parent run" }),
+          /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("dd", { children: record.parentRunId ?? run?.parentRunId ?? "None" })
+        ] }),
+        /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)("div", { children: [
+          /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("dt", { children: "Run state" }),
+          /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("dd", { children: run?.status ?? "Not retained" })
+        ] }),
+        /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)("div", { children: [
+          /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("dt", { children: "Step" }),
+          /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("dd", { children: record.stepId ?? "Partial identity" })
+        ] }),
+        /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)("div", { children: [
+          /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("dt", { children: "Step attempt" }),
+          /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("dd", { children: record.stepInstanceId ?? step?.instanceId ?? "Not supplied" })
+        ] }),
+        /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)("div", { children: [
+          /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("dt", { children: "Parent step" }),
+          /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("dd", { children: record.parentStepId ?? step?.parentStepId ?? "None" })
+        ] }),
+        /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)("div", { children: [
+          /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("dt", { children: "Step state" }),
+          /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("dd", { children: step?.status ?? "Not retained" })
+        ] })
+      ] })
+    ] }) : null,
     /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)("section", { className: "ga-detail-section", children: [
       /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("h4", { children: "Source evidence" }),
       source ? /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)("dl", { className: "ga-key-values", children: [
@@ -321,6 +409,22 @@ function Detail({
           /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("dt", { children: "Adapter" }),
           /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("dd", { children: source.adapter })
         ] }),
+        /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)("div", { children: [
+          /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("dt", { children: "Runs" }),
+          /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("dd", { children: source.fidelity.runs ?? "Not declared" })
+        ] }),
+        /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)("div", { children: [
+          /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("dt", { children: "Steps" }),
+          /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("dd", { children: source.fidelity.steps ?? "Not declared" })
+        ] }),
+        /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)("div", { children: [
+          /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("dt", { children: "Hierarchy" }),
+          /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("dd", { children: source.fidelity.hierarchy ?? "Not declared" })
+        ] }),
+        /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)("div", { children: [
+          /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("dt", { children: "Replay" }),
+          /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("dd", { children: source.fidelity.replay ?? "Not declared" })
+        ] }),
         /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)("div", { children: [
           /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("dt", { children: "Interruption" }),
           /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("dd", { children: source.fidelity.interruption })
@@ -342,6 +446,30 @@ function Detail({
     /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)("section", { className: "ga-detail-section", children: [
       /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("h4", { children: "Policy and scheduling" }),
       runtime ? /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)("dl", { className: "ga-key-values", children: [
+        runtime.messages && /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)(import_jsx_runtime5.Fragment, { children: [
+          /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)("div", { children: [
+            /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("dt", { children: "Announcement catalog" }),
+            /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("dd", { children: runtime.messages.catalogId })
+          ] }),
+          /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)("div", { children: [
+            /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("dt", { children: "Notice language" }),
+            /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("dd", { children: runtime.messages.locale })
+          ] })
+        ] }),
+        runtime.attention && /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)(import_jsx_runtime5.Fragment, { children: [
+          /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)("div", { children: [
+            /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("dt", { children: "Effective announcements" }),
+            /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("dd", { children: runtime.attention.effective })
+          ] }),
+          /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)("div", { children: [
+            /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("dt", { children: "Observed attention" }),
+            /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("dd", { children: runtime.attention.observed })
+          ] }),
+          /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)("div", { children: [
+            /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("dt", { children: "User override" }),
+            /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("dd", { children: runtime.attention.override })
+          ] })
+        ] }),
         /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)("div", { children: [
           /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("dt", { children: "Queue" }),
           /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)("dd", { children: [
@@ -431,11 +559,7 @@ function List({
     }
   );
 }
-function DevtoolsInspector({
-  store,
-  onClose,
-  onCopy
-}) {
+function Inspector({ store, onClose, onCopy }) {
   const snapshot = useSnapshot(store);
   const reduceMotion = (0, import_react.useReducedMotion)();
   const [query, setQuery] = React4.useState("");
@@ -453,13 +577,15 @@ function DevtoolsInspector({
       record.responseId,
       record.toolId,
       record.interactionId,
-      record.approvalId
+      record.approvalId,
+      record.runId,
+      record.runInstanceId,
+      record.stepId,
+      record.stepInstanceId
     ].filter(Boolean).join(" ").toLowerCase().includes(query.trim().toLowerCase())
   ).slice().reverse();
   const selected = visible.find((record) => key(record) === selectedKey) ?? visible[0];
-  const related = selected ? snapshot.records.filter(
-    (record) => correlation(record) === correlation(selected)
-  ) : [];
+  const related = selected ? relatedRecords(snapshot.records, selected) : [];
   React4.useEffect(
     () => () => {
       if (feedbackTimer.current !== void 0)
@@ -739,7 +865,7 @@ button:focus-visible, input:focus-visible, [role="listbox"]:focus-visible, [role
 .ga-workspace-feedback { top: 68px; color: #f7f7f7; background: #111; border-color: #111; border-radius: 3px; box-shadow: none; }
 @media (max-width: 760px) { .ga-bottom-dock { height: min(720px, 80vh); } .ga-inspector-header, .ga-session-toolbar { padding-right: 12px; padding-left: 12px; } .ga-session-toolbar { flex-wrap: wrap; } .ga-inspector-search { width: 100%; } .ga-session-count { margin-left: 0; } .ga-explorer-layout { flex-direction: column; } [data-slot="resizable-handle"] { width: 100%; height: 1px; } .ga-trace-row { grid-template-columns: 70px 1fr; padding: 8px 12px; } .ga-trace-row span, .ga-trace-row code { grid-column: 2; } .ga-trace-detail { padding: 18px 12px; } .ga-key-values { grid-template-columns: 1fr; } .ga-key-values-wide { grid-column: auto; } }
 `;
-function mountDevtoolsOverlay(options) {
+function mountOverlay(options) {
   const selectedDocument = options.document ?? (typeof document === "undefined" ? void 0 : document);
   if (!selectedDocument?.body)
     throw new Error("A mountable document is required");
@@ -794,7 +920,7 @@ function mountDevtoolsOverlay(options) {
       return clipboard.writeText(value);
     });
     root.render(
-      (0, import_react2.createElement)(DevtoolsInspector, {
+      (0, import_react2.createElement)(Inspector, {
         onClose: close,
         onCopy: copyText,
         store: options.store
@@ -833,5 +959,5 @@ function mountDevtoolsOverlay(options) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  mountDevtoolsOverlay
+  mountOverlay
 });

package/dist/overlay.d.cts CHANGED Viewed

@@ -1,15 +1,15 @@
-import { DevtoolsStore } from './index.cjs';
+import { Store } from './index.cjs';
 import '@generative-a11y/core';
-interface MountDevtoolsOverlayOptions {
-    readonly store: DevtoolsStore;
+interface OverlayOptions {
+    readonly store: Store;
     readonly document?: Document;
     readonly copyText?: (value: string) => void | Promise<void>;
 }
-interface MountedDevtoolsOverlay {
+interface Overlay {
     readonly host: HTMLElement;
     dispose(): void;
 }
-declare function mountDevtoolsOverlay(options: MountDevtoolsOverlayOptions): MountedDevtoolsOverlay;
+declare function mountOverlay(options: OverlayOptions): Overlay;
-export { type MountDevtoolsOverlayOptions, type MountedDevtoolsOverlay, mountDevtoolsOverlay };
+export { type Overlay, type OverlayOptions, mountOverlay };

package/dist/overlay.d.ts CHANGED Viewed

@@ -1,15 +1,15 @@
-import { DevtoolsStore } from './index.js';
+import { Store } from './index.js';
 import '@generative-a11y/core';
-interface MountDevtoolsOverlayOptions {
-    readonly store: DevtoolsStore;
+interface OverlayOptions {
+    readonly store: Store;
     readonly document?: Document;
     readonly copyText?: (value: string) => void | Promise<void>;
 }
-interface MountedDevtoolsOverlay {
+interface Overlay {
     readonly host: HTMLElement;
     dispose(): void;
 }
-declare function mountDevtoolsOverlay(options: MountDevtoolsOverlayOptions): MountedDevtoolsOverlay;
+declare function mountOverlay(options: OverlayOptions): Overlay;
-export { type MountDevtoolsOverlayOptions, type MountedDevtoolsOverlay, mountDevtoolsOverlay };
+export { type Overlay, type OverlayOptions, mountOverlay };

package/dist/overlay.js CHANGED Viewed

@@ -187,28 +187,70 @@ function ScrollBar({
 }
 // src/inspector.tsx
-import { jsx as jsx5, jsxs as jsxs2 } from "react/jsx-runtime";
+import { Fragment, jsx as jsx5, jsxs as jsxs2 } from "react/jsx-runtime";
 var key = (record) => String(record.captureSequence);
 var time = (value) => value >= 1e10 ? new Date(value).toISOString().slice(11, 23) : `+${(value / 1e3).toFixed(2)}s`;
 var stage = (record) => record.kind === "event-observed" ? "Source evidence" : record.kind === "decision" ? "Runtime decision" : "DOM delivery";
 var title = (record) => record.kind === "event-observed" ? record.sourceType ?? "Observed event" : record.kind === "dom-delivery" ? `${record.deliveryStatus ?? "Delivery"} via ${record.deliveryMethod ?? "browser"}` : record.reason ?? record.disposition ?? "Runtime decision";
-function correlation(record) {
+function correlationKeys(record) {
   const prefix = `${record.runtimeId}:`;
-  if (record.sourceEventId) return `${prefix}event:${record.sourceEventId}`;
-  if (record.responseId)
-    return `${prefix}response:${record.responseId}:${record.sourceType ?? "unknown"}`;
-  if (record.toolId)
-    return `${prefix}tool:${record.toolId}:${record.sourceType ?? "unknown"}`;
+  const keys = /* @__PURE__ */ new Set();
+  if (record.sourceEventId) keys.add(`${prefix}event:${record.sourceEventId}`);
+  if (record.responseId) keys.add(`${prefix}response:${record.responseId}`);
+  if (record.toolId) keys.add(`${prefix}tool:${record.toolId}`);
   if (record.interactionId)
-    return `${prefix}interaction:${record.interactionId}`;
-  if (record.approvalId) return `${prefix}approval:${record.approvalId}`;
+    keys.add(`${prefix}interaction:${record.interactionId}`);
+  if (record.approvalId) keys.add(`${prefix}approval:${record.approvalId}`);
   if (record.announcementId)
-    return `${prefix}announcement:${record.announcementId}`;
-  return `${prefix}record:${record.captureSequence}`;
+    keys.add(`${prefix}announcement:${record.announcementId}`);
+  if (record.runId)
+    keys.add(
+      `${prefix}run:${record.runId}:${record.runInstanceId ?? "unidentified"}`
+    );
+  if (record.runId && record.nextRunInstanceId)
+    keys.add(`${prefix}run:${record.runId}:${record.nextRunInstanceId}`);
+  if (record.parentRunId)
+    keys.add(
+      `${prefix}run:${record.parentRunId}:${record.parentRunInstanceId ?? "unidentified"}`
+    );
+  if (record.stepId)
+    keys.add(
+      `${prefix}step:${record.runId ?? "unknown"}:${record.runInstanceId ?? "unidentified"}:${record.stepId}:${record.stepInstanceId ?? "unidentified"}`
+    );
+  if (record.stepId && record.nextStepInstanceId)
+    keys.add(
+      `${prefix}step:${record.runId ?? "unknown"}:${record.runInstanceId ?? "unidentified"}:${record.stepId}:${record.nextStepInstanceId}`
+    );
+  if (record.parentStepId)
+    keys.add(
+      `${prefix}step:${record.runId ?? "unknown"}:${record.runInstanceId ?? "unidentified"}:${record.parentStepId}:${record.parentStepInstanceId ?? "unidentified"}`
+    );
+  if (record.parentToolId) keys.add(`${prefix}tool:${record.parentToolId}`);
+  if (record.parentResponseId)
+    keys.add(`${prefix}response:${record.parentResponseId}`);
+  if (keys.size === 0) keys.add(`${prefix}record:${record.captureSequence}`);
+  return [...keys];
+}
+function relatedRecords(records, selected) {
+  const related = /* @__PURE__ */ new Set();
+  const keys = new Set(correlationKeys(selected));
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const record of records) {
+      if (related.has(record)) continue;
+      const recordKeys = correlationKeys(record);
+      if (!recordKeys.some((value) => keys.has(value))) continue;
+      related.add(record);
+      for (const value of recordKeys) keys.add(value);
+      changed = true;
+    }
+  }
+  return [...related];
 }
 function explain(record) {
   if (record.kind === "event-observed")
-    return "The adapter supplied this normalized public lifecycle signal.";
+    return record.sourceType?.startsWith("attention.") ? "The host supplied an attention observation or explicit user override. Browser evidence does not establish what someone is reading." : "The adapter supplied this normalized public lifecycle signal.";
   if (record.kind === "dom-delivery")
     return record.deliveryStatus === "unavailable" ? "The DOM driver was unavailable, so no browser delivery action was observed." : "The DOM driver reported this delivery action.";
   return {
@@ -216,6 +258,9 @@ function explain(record) {
     coalesced: "The runtime merged this work with an existing queued announcement.",
     duplicate: "The runtime suppressed a recently delivered duplicate.",
     "policy-silent": "The active policy intentionally made this event silent.",
+    "catalog-format-error": "The host message formatter failed; the runtime used a generic English notice without retaining the error or parameters.",
+    "attention-quiet": "Quiet mode discarded routine output without retaining an announcement backlog.",
+    "attention-updated": "The runtime updated its attention observation or user override without announcing the control event.",
     "queue-capacity": "The bounded queue rejected or displaced this work.",
     "scope-cancelled": "The lifecycle scope ended before this queued work delivered.",
     "runtime-disposed": "The runtime was disposed and cancelled remaining queued work.",
@@ -268,6 +313,12 @@ function Detail({
     ] }) });
   const source = snapshot.runtimeSources[record.runtimeSourceId ?? record.runtimeId];
   const runtime = snapshot.runtimeSnapshots[record.runtimeId];
+  const run = record.runInstanceId ? runtime?.runs?.find(
+    (item) => item.runId === record.runId && item.instanceId === record.runInstanceId
+  ) : void 0;
+  const step = record.runInstanceId && record.stepInstanceId ? runtime?.steps?.find(
+    (item) => item.runId === record.runId && item.stepId === record.stepId && item.runInstanceId === record.runInstanceId && item.instanceId === record.stepInstanceId
+  ) : void 0;
   const deliveries = related.filter((item) => item.kind === "dom-delivery");
   return /* @__PURE__ */ jsxs2("aside", { className: "ga-trace-detail", "data-testid": "trace-detail", children: [
     /* @__PURE__ */ jsxs2("div", { className: "ga-detail-intro", children: [
@@ -280,6 +331,43 @@ function Detail({
       /* @__PURE__ */ jsx5("p", { children: record.reason?.startsWith("stale") ? "Compare the instance with the current runtime snapshot." : "Inspect related evidence and queue context if this was unexpected." })
     ] }),
     /* @__PURE__ */ jsx5(CausalChain, { records: related }),
+    record.runId ? /* @__PURE__ */ jsxs2("section", { className: "ga-detail-section", children: [
+      /* @__PURE__ */ jsx5("h4", { children: "Workflow hierarchy" }),
+      /* @__PURE__ */ jsxs2("dl", { className: "ga-key-values", children: [
+        /* @__PURE__ */ jsxs2("div", { children: [
+          /* @__PURE__ */ jsx5("dt", { children: "Run" }),
+          /* @__PURE__ */ jsx5("dd", { children: record.runId })
+        ] }),
+        /* @__PURE__ */ jsxs2("div", { children: [
+          /* @__PURE__ */ jsx5("dt", { children: "Run attempt" }),
+          /* @__PURE__ */ jsx5("dd", { children: record.runInstanceId ?? run?.instanceId ?? "Not supplied" })
+        ] }),
+        /* @__PURE__ */ jsxs2("div", { children: [
+          /* @__PURE__ */ jsx5("dt", { children: "Parent run" }),
+          /* @__PURE__ */ jsx5("dd", { children: record.parentRunId ?? run?.parentRunId ?? "None" })
+        ] }),
+        /* @__PURE__ */ jsxs2("div", { children: [
+          /* @__PURE__ */ jsx5("dt", { children: "Run state" }),
+          /* @__PURE__ */ jsx5("dd", { children: run?.status ?? "Not retained" })
+        ] }),
+        /* @__PURE__ */ jsxs2("div", { children: [
+          /* @__PURE__ */ jsx5("dt", { children: "Step" }),
+          /* @__PURE__ */ jsx5("dd", { children: record.stepId ?? "Partial identity" })
+        ] }),
+        /* @__PURE__ */ jsxs2("div", { children: [
+          /* @__PURE__ */ jsx5("dt", { children: "Step attempt" }),
+          /* @__PURE__ */ jsx5("dd", { children: record.stepInstanceId ?? step?.instanceId ?? "Not supplied" })
+        ] }),
+        /* @__PURE__ */ jsxs2("div", { children: [
+          /* @__PURE__ */ jsx5("dt", { children: "Parent step" }),
+          /* @__PURE__ */ jsx5("dd", { children: record.parentStepId ?? step?.parentStepId ?? "None" })
+        ] }),
+        /* @__PURE__ */ jsxs2("div", { children: [
+          /* @__PURE__ */ jsx5("dt", { children: "Step state" }),
+          /* @__PURE__ */ jsx5("dd", { children: step?.status ?? "Not retained" })
+        ] })
+      ] })
+    ] }) : null,
     /* @__PURE__ */ jsxs2("section", { className: "ga-detail-section", children: [
       /* @__PURE__ */ jsx5("h4", { children: "Source evidence" }),
       source ? /* @__PURE__ */ jsxs2("dl", { className: "ga-key-values", children: [
@@ -287,6 +375,22 @@ function Detail({
           /* @__PURE__ */ jsx5("dt", { children: "Adapter" }),
           /* @__PURE__ */ jsx5("dd", { children: source.adapter })
         ] }),
+        /* @__PURE__ */ jsxs2("div", { children: [
+          /* @__PURE__ */ jsx5("dt", { children: "Runs" }),
+          /* @__PURE__ */ jsx5("dd", { children: source.fidelity.runs ?? "Not declared" })
+        ] }),
+        /* @__PURE__ */ jsxs2("div", { children: [
+          /* @__PURE__ */ jsx5("dt", { children: "Steps" }),
+          /* @__PURE__ */ jsx5("dd", { children: source.fidelity.steps ?? "Not declared" })
+        ] }),
+        /* @__PURE__ */ jsxs2("div", { children: [
+          /* @__PURE__ */ jsx5("dt", { children: "Hierarchy" }),
+          /* @__PURE__ */ jsx5("dd", { children: source.fidelity.hierarchy ?? "Not declared" })
+        ] }),
+        /* @__PURE__ */ jsxs2("div", { children: [
+          /* @__PURE__ */ jsx5("dt", { children: "Replay" }),
+          /* @__PURE__ */ jsx5("dd", { children: source.fidelity.replay ?? "Not declared" })
+        ] }),
         /* @__PURE__ */ jsxs2("div", { children: [
           /* @__PURE__ */ jsx5("dt", { children: "Interruption" }),
           /* @__PURE__ */ jsx5("dd", { children: source.fidelity.interruption })
@@ -308,6 +412,30 @@ function Detail({
     /* @__PURE__ */ jsxs2("section", { className: "ga-detail-section", children: [
       /* @__PURE__ */ jsx5("h4", { children: "Policy and scheduling" }),
       runtime ? /* @__PURE__ */ jsxs2("dl", { className: "ga-key-values", children: [
+        runtime.messages && /* @__PURE__ */ jsxs2(Fragment, { children: [
+          /* @__PURE__ */ jsxs2("div", { children: [
+            /* @__PURE__ */ jsx5("dt", { children: "Announcement catalog" }),
+            /* @__PURE__ */ jsx5("dd", { children: runtime.messages.catalogId })
+          ] }),
+          /* @__PURE__ */ jsxs2("div", { children: [
+            /* @__PURE__ */ jsx5("dt", { children: "Notice language" }),
+            /* @__PURE__ */ jsx5("dd", { children: runtime.messages.locale })
+          ] })
+        ] }),
+        runtime.attention && /* @__PURE__ */ jsxs2(Fragment, { children: [
+          /* @__PURE__ */ jsxs2("div", { children: [
+            /* @__PURE__ */ jsx5("dt", { children: "Effective announcements" }),
+            /* @__PURE__ */ jsx5("dd", { children: runtime.attention.effective })
+          ] }),
+          /* @__PURE__ */ jsxs2("div", { children: [
+            /* @__PURE__ */ jsx5("dt", { children: "Observed attention" }),
+            /* @__PURE__ */ jsx5("dd", { children: runtime.attention.observed })
+          ] }),
+          /* @__PURE__ */ jsxs2("div", { children: [
+            /* @__PURE__ */ jsx5("dt", { children: "User override" }),
+            /* @__PURE__ */ jsx5("dd", { children: runtime.attention.override })
+          ] })
+        ] }),
         /* @__PURE__ */ jsxs2("div", { children: [
           /* @__PURE__ */ jsx5("dt", { children: "Queue" }),
           /* @__PURE__ */ jsxs2("dd", { children: [
@@ -397,11 +525,7 @@ function List({
     }
   );
 }
-function DevtoolsInspector({
-  store,
-  onClose,
-  onCopy
-}) {
+function Inspector({ store, onClose, onCopy }) {
   const snapshot = useSnapshot(store);
   const reduceMotion = useReducedMotion();
   const [query, setQuery] = React4.useState("");
@@ -419,13 +543,15 @@ function DevtoolsInspector({
       record.responseId,
       record.toolId,
       record.interactionId,
-      record.approvalId
+      record.approvalId,
+      record.runId,
+      record.runInstanceId,
+      record.stepId,
+      record.stepInstanceId
     ].filter(Boolean).join(" ").toLowerCase().includes(query.trim().toLowerCase())
   ).slice().reverse();
   const selected = visible.find((record) => key(record) === selectedKey) ?? visible[0];
-  const related = selected ? snapshot.records.filter(
-    (record) => correlation(record) === correlation(selected)
-  ) : [];
+  const related = selected ? relatedRecords(snapshot.records, selected) : [];
   React4.useEffect(
     () => () => {
       if (feedbackTimer.current !== void 0)
@@ -705,7 +831,7 @@ button:focus-visible, input:focus-visible, [role="listbox"]:focus-visible, [role
 .ga-workspace-feedback { top: 68px; color: #f7f7f7; background: #111; border-color: #111; border-radius: 3px; box-shadow: none; }
 @media (max-width: 760px) { .ga-bottom-dock { height: min(720px, 80vh); } .ga-inspector-header, .ga-session-toolbar { padding-right: 12px; padding-left: 12px; } .ga-session-toolbar { flex-wrap: wrap; } .ga-inspector-search { width: 100%; } .ga-session-count { margin-left: 0; } .ga-explorer-layout { flex-direction: column; } [data-slot="resizable-handle"] { width: 100%; height: 1px; } .ga-trace-row { grid-template-columns: 70px 1fr; padding: 8px 12px; } .ga-trace-row span, .ga-trace-row code { grid-column: 2; } .ga-trace-detail { padding: 18px 12px; } .ga-key-values { grid-template-columns: 1fr; } .ga-key-values-wide { grid-column: auto; } }
 `;
-function mountDevtoolsOverlay(options) {
+function mountOverlay(options) {
   const selectedDocument = options.document ?? (typeof document === "undefined" ? void 0 : document);
   if (!selectedDocument?.body)
     throw new Error("A mountable document is required");
@@ -760,7 +886,7 @@ function mountDevtoolsOverlay(options) {
       return clipboard.writeText(value);
     });
     root.render(
-      createElement(DevtoolsInspector, {
+      createElement(Inspector, {
         onClose: close,
         onCopy: copyText,
         store: options.store
@@ -798,5 +924,5 @@ function mountDevtoolsOverlay(options) {
   };
 }
 export {
-  mountDevtoolsOverlay
+  mountOverlay
 };

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@generative-a11y/devtools",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Development-only accessibility diagnostics and a redacted trace explorer for screen-reader announcements in AI runtimes.",
   "keywords": [
     "accessibility",
@@ -56,11 +56,11 @@
     "class-variance-authority": "0.7.1",
     "clsx": "2.1.1",
     "lucide-react": "1.31.0",
-    "motion": "^12.23.12",
+    "motion": "^13.1.1",
     "radix-ui": "1.6.7",
     "react-resizable-panels": "^4.12.3",
     "tailwind-merge": "3.6.0",
-    "@generative-a11y/core": "0.2.0"
+    "@generative-a11y/core": "0.4.0"
   },
   "peerDependencies": {
     "react": "^19.0.0",