@ukiahinsure/a2ui-react-adapter 0.1.0

package/dist/providerValidation.js

@@ -0,0 +1,249 @@
+import {
+  A2UI_CAPABILITIES_TOPIC,
+  A2UI_CLIENT_TOPIC,
+  A2UI_SERVER_TOPIC
+} from "./chunk-AOBRTDAU.js";
+
+// src/providerValidation.ts
+var MAX_EVIDENCE_EVENTS = 128;
+function createA2UIProviderValidationProbe(sourceRoom) {
+  const evidence = [];
+  const listeners = /* @__PURE__ */ new Set();
+  const scenarioByRequest = /* @__PURE__ */ new Map();
+  let lastActionText;
+  let lastCapability;
+  let disposed = false;
+  const record = (event) => {
+    if (disposed) {
+      return;
+    }
+    evidence.push(event);
+    if (evidence.length > MAX_EVIDENCE_EVENTS) {
+      evidence.splice(0, evidence.length - MAX_EVIDENCE_EVENTS);
+    }
+    for (const listener of listeners) {
+      listener();
+    }
+  };
+  const inspectOutgoing = (text, topic) => {
+    const envelope = decodeObject(text);
+    if (envelope === null) {
+      return;
+    }
+    const requestId = safeString(envelope.requestId);
+    if (topic === A2UI_CAPABILITIES_TOPIC && envelope.kind === "capabilities") {
+      const capability = envelope;
+      lastCapability = capability;
+      if (requestId !== void 0) {
+        scenarioByRequest.set(requestId, "capability");
+      }
+      record({
+        name: "capability_sent",
+        exactEnvelopeVersion: envelope.envelopeVersion === "v1",
+        exactA2uiVersion: Array.isArray(envelope.supportedA2uiVersions) && envelope.supportedA2uiVersions.length === 1 && envelope.supportedA2uiVersions[0] === "0.9.1",
+        exactCatalog: Array.isArray(envelope.supportedCatalogIds) && envelope.supportedCatalogIds.length === 1 && envelope.supportedCatalogIds[0] === "https://a2ui.org/specification/v0_9/basic_catalog.json",
+        exactRenderer: typeof envelope.renderer === "object" && envelope.renderer !== null && "name" in envelope.renderer && "version" in envelope.renderer && envelope.renderer.name === "a2ui_react_adapter" && envelope.renderer.version === "0.1.0",
+        requestsSnapshot: envelope.requestSnapshot === true
+      });
+      return;
+    }
+    if (topic === A2UI_CLIENT_TOPIC && envelope.kind === "action") {
+      const action = safeAction(envelope.action);
+      const revision = safeInteger(envelope.revision);
+      if (requestId === void 0 || action === void 0 || revision === null) {
+        return;
+      }
+      lastActionText = text;
+      scenarioByRequest.set(requestId, "action");
+      record({ name: "action_sent", action, revision });
+    }
+  };
+  const inspectIncoming = (text) => {
+    const envelope = decodeObject(text);
+    if (envelope === null) {
+      return;
+    }
+    const seq = safeInteger(envelope.seq);
+    if (seq === null) {
+      return;
+    }
+    if (envelope.kind === "snapshot" || envelope.kind === "surfaceUpdate") {
+      const revision = safeInteger(envelope.revision);
+      if (revision === null) {
+        return;
+      }
+      const inResponseTo2 = safeString(envelope.inResponseTo);
+      record({
+        name: "server_surface",
+        kind: envelope.kind,
+        seq,
+        revision,
+        correlated: inResponseTo2 !== void 0 && scenarioByRequest.has(inResponseTo2)
+      });
+      return;
+    }
+    if (envelope.kind !== "ack") {
+      return;
+    }
+    const inResponseTo = safeString(envelope.inResponseTo);
+    const status = envelope.status;
+    if (inResponseTo === void 0 || status !== "accepted" && status !== "rejected") {
+      return;
+    }
+    const scenario = scenarioByRequest.get(inResponseTo);
+    if (scenario === void 0) {
+      return;
+    }
+    const reasonCode = safeReason(envelope.reasonCode);
+    record({
+      name: "server_ack",
+      scenario,
+      seq,
+      status,
+      ...reasonCode === void 0 ? {} : { reasonCode },
+      correlated: true
+    });
+  };
+  const room = {
+    localParticipant: {
+      async sendText(text, options) {
+        inspectOutgoing(text, options.topic);
+        return sourceRoom.localParticipant.sendText(text, options);
+      }
+    },
+    registerTextStreamHandler(topic, handler) {
+      if (topic !== A2UI_SERVER_TOPIC) {
+        sourceRoom.registerTextStreamHandler(topic, handler);
+        return;
+      }
+      sourceRoom.registerTextStreamHandler(topic, (reader, participant) => {
+        let readPromise;
+        const inspectedReader = {
+          ...reader.info === void 0 ? {} : { info: reader.info },
+          readAll(options) {
+            readPromise ??= reader.readAll(options).then((text) => {
+              inspectIncoming(text);
+              return text;
+            });
+            return readPromise;
+          }
+        };
+        handler(inspectedReader, participant);
+      });
+    },
+    unregisterTextStreamHandler(topic) {
+      sourceRoom.unregisterTextStreamHandler(topic);
+    },
+    on(event, listener) {
+      return sourceRoom.on(event, listener);
+    },
+    off(event, listener) {
+      return sourceRoom.off(event, listener);
+    }
+  };
+  const sendProbe = async (scenario, envelope) => {
+    if (disposed) {
+      return false;
+    }
+    const requestId = safeString(envelope.requestId);
+    if (requestId === void 0) {
+      return false;
+    }
+    scenarioByRequest.set(requestId, scenario);
+    record({ name: "probe_sent", scenario });
+    try {
+      await sourceRoom.localParticipant.sendText(JSON.stringify(envelope), {
+        topic: scenario === "unsupported" ? A2UI_CAPABILITIES_TOPIC : A2UI_CLIENT_TOPIC
+      });
+      return true;
+    } catch {
+      scenarioByRequest.delete(requestId);
+      return false;
+    }
+  };
+  return {
+    room,
+    getSnapshot() {
+      return {
+        events: evidence.map((event) => ({ ...event })),
+        hasCapability: evidence.some(
+          (event) => event.name === "capability_sent"
+        ),
+        hasSurface: evidence.some((event) => event.name === "server_surface"),
+        hasAction: evidence.some((event) => event.name === "action_sent")
+      };
+    },
+    subscribe(listener) {
+      if (disposed) {
+        return () => void 0;
+      }
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    async replayLastAction() {
+      const envelope = decodeObject(lastActionText);
+      return envelope === null ? false : sendProbe("duplicate", envelope);
+    },
+    async sendStaleLastAction() {
+      const previous = decodeObject(lastActionText);
+      if (previous === null || previous.kind !== "action") {
+        return false;
+      }
+      const envelope = {
+        ...previous,
+        requestId: createRequestId("req")
+      };
+      return sendProbe("stale", envelope);
+    },
+    async sendUnsupportedCapability() {
+      if (lastCapability === void 0) {
+        return false;
+      }
+      const envelope = {
+        ...lastCapability,
+        requestId: createRequestId("cap"),
+        supportedA2uiVersions: ["1.0.0"],
+        requestSnapshot: false
+      };
+      return sendProbe("unsupported", envelope);
+    },
+    dispose() {
+      disposed = true;
+      lastActionText = void 0;
+      lastCapability = void 0;
+      scenarioByRequest.clear();
+      evidence.splice(0);
+      listeners.clear();
+    }
+  };
+}
+function decodeObject(text) {
+  if (typeof text !== "string") {
+    return null;
+  }
+  try {
+    const value = JSON.parse(text);
+    return typeof value === "object" && value !== null && !Array.isArray(value) ? value : null;
+  } catch {
+    return null;
+  }
+}
+function safeString(value) {
+  return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+function safeInteger(value) {
+  return typeof value === "number" && Number.isSafeInteger(value) ? value : null;
+}
+function safeReason(value) {
+  return typeof value === "string" && /^[a-z0-9_]{1,64}$/.test(value) ? value : void 0;
+}
+function safeAction(value) {
+  return value === "flow.submit" || value === "flow.skip" || value === "flow.revise" || value === "flow.list.add" || value === "flow.list.update" || value === "flow.list.delete" ? value : void 0;
+}
+function createRequestId(prefix) {
+  return `${prefix}-${globalThis.crypto.randomUUID()}`;
+}
+export {
+  createA2UIProviderValidationProbe
+};
+//# sourceMappingURL=providerValidation.js.map

package/dist/providerValidation.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/providerValidation.ts"],"sourcesContent":["/**\n * Provider-acceptance probe for a real A2UI room.\n *\n * This opt-in entry point keeps protocol-aware fault injection in the adapter\n * package. It never records action payloads, message bodies, participant\n * identities, tokens, URLs, or request identifiers in its public evidence.\n */\n\nimport {\n  A2UI_CAPABILITIES_TOPIC,\n  A2UI_CLIENT_TOPIC,\n  A2UI_SERVER_TOPIC,\n} from \"./envelope.js\";\nimport type { A2UICapabilityEnvelope } from \"./envelope.js\";\nimport type { A2UIRoomLike, A2UIStreamParticipant } from \"./session.js\";\n\nconst MAX_EVIDENCE_EVENTS = 128;\n\nexport type A2UIProviderValidationScenario =\n  | \"capability\"\n  | \"action\"\n  | \"duplicate\"\n  | \"stale\"\n  | \"unsupported\";\n\nexport type A2UIProviderValidationEvent =\n  | {\n      readonly name: \"capability_sent\";\n      readonly exactEnvelopeVersion: boolean;\n      readonly exactA2uiVersion: boolean;\n      readonly exactCatalog: boolean;\n      readonly exactRenderer: boolean;\n      readonly requestsSnapshot: boolean;\n    }\n  | {\n      readonly name: \"action_sent\";\n      readonly action: string;\n      readonly revision: number;\n    }\n  | {\n      readonly name: \"server_surface\";\n      readonly kind: \"snapshot\" | \"surfaceUpdate\";\n      readonly seq: number;\n      readonly revision: number;\n      readonly correlated: boolean;\n    }\n  | {\n      readonly name: \"server_ack\";\n      readonly scenario: A2UIProviderValidationScenario;\n      readonly seq: number;\n      readonly status: \"accepted\" | \"rejected\";\n      readonly reasonCode?: string;\n      readonly correlated: boolean;\n    }\n  | {\n      readonly name: \"probe_sent\";\n      readonly scenario: \"duplicate\" | \"stale\" | \"unsupported\";\n    };\n\nexport interface A2UIProviderValidationSnapshot {\n  readonly events: readonly A2UIProviderValidationEvent[];\n  readonly hasCapability: boolean;\n  readonly hasSurface: boolean;\n  readonly hasAction: boolean;\n}\n\nexport interface A2UIProviderValidationProbe {\n  /** Structural room wrapper passed to A2UISessionController. */\n  readonly room: A2UIRoomLike;\n  getSnapshot(): A2UIProviderValidationSnapshot;\n  subscribe(listener: () => void): () => void;\n  replayLastAction(): Promise<boolean>;\n  sendStaleLastAction(): Promise<boolean>;\n  sendUnsupportedCapability(): Promise<boolean>;\n  dispose(): void;\n}\n\ninterface ReaderLike {\n  readonly info?: { readonly size?: number };\n  readAll(options?: { signal?: AbortSignal }): Promise<string>;\n}\n\ntype StreamHandler = (\n  reader: ReaderLike,\n  participant: A2UIStreamParticipant,\n) => void;\n\ntype SafeEnvelope = Record<string, unknown>;\n\n/** Wrap one caller-owned room with transient, body-free provider evidence. */\nexport function createA2UIProviderValidationProbe(\n  sourceRoom: A2UIRoomLike,\n): A2UIProviderValidationProbe {\n  const evidence: A2UIProviderValidationEvent[] = [];\n  const listeners = new Set<() => void>();\n  const scenarioByRequest = new Map<\n    string,\n    A2UIProviderValidationScenario\n  >();\n  let lastActionText: string | undefined;\n  let lastCapability: A2UICapabilityEnvelope | undefined;\n  let disposed = false;\n\n  const record = (event: A2UIProviderValidationEvent): void => {\n    if (disposed) {\n      return;\n    }\n    evidence.push(event);\n    if (evidence.length > MAX_EVIDENCE_EVENTS) {\n      evidence.splice(0, evidence.length - MAX_EVIDENCE_EVENTS);\n    }\n    for (const listener of listeners) {\n      listener();\n    }\n  };\n\n  const inspectOutgoing = (text: string, topic: string): void => {\n    const envelope = decodeObject(text);\n    if (envelope === null) {\n      return;\n    }\n    const requestId = safeString(envelope.requestId);\n    if (\n      topic === A2UI_CAPABILITIES_TOPIC &&\n      envelope.kind === \"capabilities\"\n    ) {\n      const capability = envelope as unknown as A2UICapabilityEnvelope;\n      lastCapability = capability;\n      if (requestId !== undefined) {\n        scenarioByRequest.set(requestId, \"capability\");\n      }\n      record({\n        name: \"capability_sent\",\n        exactEnvelopeVersion: envelope.envelopeVersion === \"v1\",\n        exactA2uiVersion:\n          Array.isArray(envelope.supportedA2uiVersions) &&\n          envelope.supportedA2uiVersions.length === 1 &&\n          envelope.supportedA2uiVersions[0] === \"0.9.1\",\n        exactCatalog:\n          Array.isArray(envelope.supportedCatalogIds) &&\n          envelope.supportedCatalogIds.length === 1 &&\n          envelope.supportedCatalogIds[0] ===\n            \"https://a2ui.org/specification/v0_9/basic_catalog.json\",\n        exactRenderer:\n          typeof envelope.renderer === \"object\" &&\n          envelope.renderer !== null &&\n          \"name\" in envelope.renderer &&\n          \"version\" in envelope.renderer &&\n          envelope.renderer.name === \"a2ui_react_adapter\" &&\n          envelope.renderer.version === \"0.1.0\",\n        requestsSnapshot: envelope.requestSnapshot === true,\n      });\n      return;\n    }\n    if (topic === A2UI_CLIENT_TOPIC && envelope.kind === \"action\") {\n      const action = safeAction(envelope.action);\n      const revision = safeInteger(envelope.revision);\n      if (requestId === undefined || action === undefined || revision === null) {\n        return;\n      }\n      lastActionText = text;\n      scenarioByRequest.set(requestId, \"action\");\n      record({ name: \"action_sent\", action, revision });\n    }\n  };\n\n  const inspectIncoming = (text: string): void => {\n    const envelope = decodeObject(text);\n    if (envelope === null) {\n      return;\n    }\n    const seq = safeInteger(envelope.seq);\n    if (seq === null) {\n      return;\n    }\n    if (envelope.kind === \"snapshot\" || envelope.kind === \"surfaceUpdate\") {\n      const revision = safeInteger(envelope.revision);\n      if (revision === null) {\n        return;\n      }\n      const inResponseTo = safeString(envelope.inResponseTo);\n      record({\n        name: \"server_surface\",\n        kind: envelope.kind,\n        seq,\n        revision,\n        correlated:\n          inResponseTo !== undefined && scenarioByRequest.has(inResponseTo),\n      });\n      return;\n    }\n    if (envelope.kind !== \"ack\") {\n      return;\n    }\n    const inResponseTo = safeString(envelope.inResponseTo);\n    const status = envelope.status;\n    if (\n      inResponseTo === undefined ||\n      (status !== \"accepted\" && status !== \"rejected\")\n    ) {\n      return;\n    }\n    const scenario = scenarioByRequest.get(inResponseTo);\n    if (scenario === undefined) {\n      return;\n    }\n    const reasonCode = safeReason(envelope.reasonCode);\n    record({\n      name: \"server_ack\",\n      scenario,\n      seq,\n      status,\n      ...(reasonCode === undefined ? {} : { reasonCode }),\n      correlated: true,\n    });\n  };\n\n  const room: A2UIRoomLike = {\n    localParticipant: {\n      async sendText(text, options) {\n        inspectOutgoing(text, options.topic);\n        return sourceRoom.localParticipant.sendText(text, options);\n      },\n    },\n    registerTextStreamHandler(topic, handler: StreamHandler) {\n      if (topic !== A2UI_SERVER_TOPIC) {\n        sourceRoom.registerTextStreamHandler(topic, handler);\n        return;\n      }\n      sourceRoom.registerTextStreamHandler(topic, (reader, participant) => {\n        let readPromise: Promise<string> | undefined;\n        const inspectedReader: ReaderLike = {\n          ...(reader.info === undefined ? {} : { info: reader.info }),\n          readAll(options) {\n            readPromise ??= reader.readAll(options).then((text) => {\n              inspectIncoming(text);\n              return text;\n            });\n            return readPromise;\n          },\n        };\n        handler(inspectedReader, participant);\n      });\n    },\n    unregisterTextStreamHandler(topic) {\n      sourceRoom.unregisterTextStreamHandler(topic);\n    },\n    on(event, listener) {\n      return sourceRoom.on(event, listener);\n    },\n    off(event, listener) {\n      return sourceRoom.off(event, listener);\n    },\n  };\n\n  const sendProbe = async (\n    scenario: \"duplicate\" | \"stale\" | \"unsupported\",\n    envelope: SafeEnvelope,\n  ): Promise<boolean> => {\n    if (disposed) {\n      return false;\n    }\n    const requestId = safeString(envelope.requestId);\n    if (requestId === undefined) {\n      return false;\n    }\n    scenarioByRequest.set(requestId, scenario);\n    record({ name: \"probe_sent\", scenario });\n    try {\n      await sourceRoom.localParticipant.sendText(JSON.stringify(envelope), {\n        topic:\n          scenario === \"unsupported\"\n            ? A2UI_CAPABILITIES_TOPIC\n            : A2UI_CLIENT_TOPIC,\n      });\n      return true;\n    } catch {\n      scenarioByRequest.delete(requestId);\n      return false;\n    }\n  };\n\n  return {\n    room,\n    getSnapshot() {\n      return {\n        events: evidence.map((event) => ({ ...event })),\n        hasCapability: evidence.some(\n          (event) => event.name === \"capability_sent\",\n        ),\n        hasSurface: evidence.some((event) => event.name === \"server_surface\"),\n        hasAction: evidence.some((event) => event.name === \"action_sent\"),\n      };\n    },\n    subscribe(listener) {\n      if (disposed) {\n        return () => undefined;\n      }\n      listeners.add(listener);\n      return () => listeners.delete(listener);\n    },\n    async replayLastAction() {\n      const envelope = decodeObject(lastActionText);\n      return envelope === null\n        ? false\n        : sendProbe(\"duplicate\", envelope);\n    },\n    async sendStaleLastAction() {\n      const previous = decodeObject(lastActionText);\n      if (previous === null || previous.kind !== \"action\") {\n        return false;\n      }\n      const envelope: SafeEnvelope = {\n        ...previous,\n        requestId: createRequestId(\"req\"),\n      };\n      return sendProbe(\"stale\", envelope);\n    },\n    async sendUnsupportedCapability() {\n      if (lastCapability === undefined) {\n        return false;\n      }\n      const envelope: SafeEnvelope = {\n        ...lastCapability,\n        requestId: createRequestId(\"cap\"),\n        supportedA2uiVersions: [\"1.0.0\"],\n        requestSnapshot: false,\n      };\n      return sendProbe(\"unsupported\", envelope);\n    },\n    dispose() {\n      disposed = true;\n      lastActionText = undefined;\n      lastCapability = undefined;\n      scenarioByRequest.clear();\n      evidence.splice(0);\n      listeners.clear();\n    },\n  };\n}\n\nfunction decodeObject(text: string | undefined): SafeEnvelope | null {\n  if (typeof text !== \"string\") {\n    return null;\n  }\n  try {\n    const value: unknown = JSON.parse(text);\n    return typeof value === \"object\" && value !== null && !Array.isArray(value)\n      ? (value as SafeEnvelope)\n      : null;\n  } catch {\n    return null;\n  }\n}\n\nfunction safeString(value: unknown): string | undefined {\n  return typeof value === \"string\" && value.length > 0 ? value : undefined;\n}\n\nfunction safeInteger(value: unknown): number | null {\n  return typeof value === \"number\" && Number.isSafeInteger(value)\n    ? value\n    : null;\n}\n\nfunction safeReason(value: unknown): string | undefined {\n  return typeof value === \"string\" && /^[a-z0-9_]{1,64}$/.test(value)\n    ? value\n    : undefined;\n}\n\nfunction safeAction(value: unknown): string | undefined {\n  return value === \"flow.submit\" ||\n    value === \"flow.skip\" ||\n    value === \"flow.revise\" ||\n    value === \"flow.list.add\" ||\n    value === \"flow.list.update\" ||\n    value === \"flow.list.delete\"\n    ? value\n    : undefined;\n}\n\nfunction createRequestId(prefix: \"cap\" | \"req\"): string {\n  return `${prefix}-${globalThis.crypto.randomUUID()}`;\n}\n"],"mappings":"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","names":["inResponseTo"]}

package/dist/session-B_2-bK2s.d.ts

@@ -0,0 +1,348 @@
+/**
+ * MedAid A2UI LiveKit envelope contract v1 — client-side constants and types.
+ *
+ * These declarations mirror the canonical machine-readable contract owned by
+ * `livekitFlowfactory/contracts/a2ui-livekit-*-envelope.v1.schema.json`
+ * (human-readable source: MediAid `docs/aide/contracts/a2ui-livekit-envelope-contract.md`).
+ * They are a declared copy: Stage 17 acceptance verifies drift against the
+ * canonical fixtures. The envelope contract version ("v1", the `.v1` topic
+ * suffix) is not the A2UI protocol version; `a2uiVersion` is negotiated
+ * separately.
+ */
+declare const ENVELOPE_VERSION: "v1";
+declare const A2UI_PROTOCOL_VERSION: "0.9.1";
+declare const A2UI_SERVER_TOPIC = "medaid.a2ui.server.v1";
+declare const A2UI_CLIENT_TOPIC = "medaid.a2ui.client.v1";
+declare const A2UI_CAPABILITIES_TOPIC = "medaid.a2ui.capabilities.v1";
+declare const MAX_ENVELOPE_BYTES = 262144;
+declare const CLIENT_ACTIONS: readonly ["flow.submit", "flow.skip", "flow.revise", "flow.list.add", "flow.list.update", "flow.list.delete"];
+type ClientAction = (typeof CLIENT_ACTIONS)[number];
+declare const CLIENT_ERROR_CODES: readonly ["render_failed", "catalog_unsupported", "message_malformed", "envelope_unsupported"];
+type ClientErrorCode = (typeof CLIENT_ERROR_CODES)[number];
+type ParticipantRole = "member" | "agent";
+interface SectionNavigation {
+    orderedSectionIds: string[];
+    activeSectionId: string | null;
+    completedSectionIds: string[];
+    futureSectionIds: string[];
+}
+interface A2UIFieldInteractionField {
+    field: string;
+    componentId: string;
+}
+interface A2UIFieldInteractionGroup {
+    groupId: string;
+    ownerStateId: string;
+    sectionId?: string;
+    mode: "current" | "revision";
+    fields: A2UIFieldInteractionField[];
+}
+interface ServerEnvelopeBase {
+    envelopeVersion: typeof ENVELOPE_VERSION;
+    a2uiVersion: string;
+    seq: number;
+}
+interface SurfaceUpdateEnvelope extends ServerEnvelopeBase {
+    kind: "surfaceUpdate";
+    surfaceId: string;
+    revision: number;
+    activeStateId?: string | null;
+    sectionNavigation?: SectionNavigation;
+    fieldInteractions?: A2UIFieldInteractionGroup[];
+    messages: unknown[];
+}
+interface SnapshotEnvelope extends ServerEnvelopeBase {
+    kind: "snapshot";
+    surfaceId: string;
+    revision: number;
+    activeStateId?: string | null;
+    sectionNavigation?: SectionNavigation;
+    fieldInteractions?: A2UIFieldInteractionGroup[];
+    inResponseTo?: string;
+    messages: unknown[];
+}
+interface AckFieldError {
+    field: string;
+    reasonCode: string;
+}
+interface AckEnvelope extends ServerEnvelopeBase {
+    kind: "ack";
+    inResponseTo: string;
+    status: "accepted" | "rejected";
+    reasonCode?: string;
+    fieldErrors?: AckFieldError[];
+    noSurface?: boolean;
+}
+type A2UIServerEnvelope = SurfaceUpdateEnvelope | SnapshotEnvelope | AckEnvelope;
+interface A2UIClientActionEnvelope {
+    envelopeVersion: typeof ENVELOPE_VERSION;
+    a2uiVersion: string;
+    kind: "action";
+    requestId: string;
+    role: ParticipantRole;
+    surfaceId: string;
+    stateId: string;
+    revision: number;
+    action: ClientAction;
+    payload?: {
+        fields?: Record<string, string | number | boolean | null>;
+        targetStateId?: string;
+        listPath?: string;
+        itemId?: string;
+    };
+}
+interface A2UIClientErrorEnvelope {
+    envelopeVersion: typeof ENVELOPE_VERSION;
+    a2uiVersion: string;
+    kind: "clientError";
+    requestId: string;
+    role: ParticipantRole;
+    errorCode: ClientErrorCode;
+    surfaceId?: string;
+    detail?: string;
+}
+interface A2UICapabilityEnvelope {
+    envelopeVersion: typeof ENVELOPE_VERSION;
+    kind: "capabilities";
+    requestId: string;
+    role: ParticipantRole;
+    supportedA2uiVersions: string[];
+    supportedCatalogIds: string[];
+    renderer: {
+        name: string;
+        version: string;
+    };
+    requestSnapshot?: boolean;
+}
+
+/**
+ * A2UIClientAdapter: the only place protocol messages are applied client-side.
+ *
+ * Wraps the official A2UI v0.9.1 message processor with the trusted Basic
+ * Catalog. Hosts never see protocol SDK types directly; they receive the
+ * adapter's surface handles and safe error events using the locked
+ * client-error codes. Unsupported catalogs or malformed messages produce an
+ * error callback and leave prior committed surfaces untouched — there is no
+ * partial render path and no dynamic catalog loading.
+ */
+
+/** Opaque renderer-owned handle. Hosts may identify it, but never inspect SDK state. */
+interface AdapterSurface {
+    readonly id: string;
+}
+interface A2UIClientErrorEvent {
+    errorCode: ClientErrorCode;
+    surfaceId?: string;
+    detail?: string;
+}
+/** Protocol-neutral action emitted by the trusted official renderer. */
+interface A2UIRendererActionEvent {
+    actionName: string;
+    surfaceId: string;
+    sourceComponentId: string;
+    context: Readonly<Record<string, unknown>>;
+}
+type A2UIFieldControl = "text" | "date" | "choice";
+type A2UIFieldValue = string | number | boolean | null;
+/** Safe structural metadata used only for labels, validation, and focus. */
+interface A2UIFieldDescriptor {
+    readonly componentId: string;
+    readonly field: string;
+    readonly label: string;
+    readonly control: A2UIFieldControl;
+    readonly required: boolean;
+}
+/** Safe authored tab title/child binding; section status remains envelope-owned. */
+interface A2UITabDescriptor {
+    readonly componentId: string;
+    readonly title: string;
+    readonly childId: string;
+}
+interface A2UISurfaceStructure {
+    readonly fields: readonly A2UIFieldDescriptor[];
+    readonly tabs: readonly A2UITabDescriptor[];
+}
+interface A2UIClientAdapterOptions {
+    /** Safe client-error events (locked codes); wired to LiveKit in later items. */
+    onClientError?: (event: A2UIClientErrorEvent) => void;
+    /** Trusted catalog actions normalized without exposing official A2UI types. */
+    onAction?: (action: A2UIRendererActionEvent) => void;
+    /** Application acknowledgements; consumed by Queue-Item 024-005. */
+    onAck?: (envelope: Extract<A2UIServerEnvelope, {
+        kind: "ack";
+    }>) => void;
+}
+declare class A2UIClientAdapter {
+    #private;
+    readonly rendererName = "a2ui_react_adapter";
+    readonly rendererVersion = "0.1.0";
+    constructor(options?: A2UIClientAdapterOptions);
+    /** Catalog ids this adapter will announce in capability envelopes. */
+    get supportedCatalogIds(): string[];
+    get lastSeq(): number;
+    /** The most recently created live surface, if any. */
+    get currentSurface(): AdapterSurface | undefined;
+    getSurface(id: string): AdapterSurface | undefined;
+    /** Immutable value-free structure for host accessibility augmentation. */
+    getSurfaceStructure(id: string): A2UISurfaceStructure;
+    /** Read a complete scalar field set without exposing the SDK data model. */
+    getFieldValues(surfaceId: string, fields: readonly string[]): Record<string, A2UIFieldValue> | null;
+    /** Restore a private draft after a trusted processor replacement. */
+    applyFieldValues(surfaceId: string, values: Readonly<Record<string, A2UIFieldValue>>): boolean;
+    /**
+     * Apply one validated server envelope. Returns false for duplicates and
+     * out-of-order deliveries (the per-session `seq` guard) and for envelopes
+     * that fail to apply; committed surfaces are never partially replaced.
+     */
+    applyServerEnvelope(envelope: A2UIServerEnvelope): boolean;
+    /**
+     * Reset the ordering guard; used when a reconnect snapshot restarts the
+     * server sequence (Queue-Item 024-004).
+     */
+    resetSequence(): void;
+    /** Clear every generated surface without disposing the reusable adapter. */
+    clearSurfaces(): void;
+    /** Emit one of the locked, body-free client error events. */
+    reportClientError(errorCode: ClientErrorCode, surfaceId?: string, detail?: string): void;
+    /** Report a rendering failure (used by the surface host error boundary). */
+    reportRenderFailure(surfaceId: string | undefined, detail: string): void;
+    subscribe: (listener: () => void) => (() => void);
+    subscribeActions: (listener: (event: A2UIRendererActionEvent) => void) => (() => void);
+    subscribeClientErrors: (listener: (event: A2UIClientErrorEvent) => void) => (() => void);
+    /** Monotonic change counter for `useSyncExternalStore`. */
+    getVersion: () => number;
+    dispose(): void;
+}
+
+/**
+ * MedAid v0.9.1 action/correlation bridge.
+ *
+ * The official renderer emits protocol actions; this bridge binds them to the
+ * authoritative session metadata and the MedAid v1 envelope. It deliberately
+ * separates LiveKit delivery from application acknowledgement so a successful
+ * `sendText` call can never be mistaken for a workflow transition.
+ */
+
+type A2UIActionDeliveryStatus = "publishing" | "awaiting_ack" | "retryable";
+interface A2UIPendingAction {
+    readonly requestId: string;
+    readonly action: ClientAction;
+    readonly surfaceId: string;
+    readonly stateId: string;
+    readonly revision: number;
+    readonly deliveryStatus: A2UIActionDeliveryStatus;
+    readonly attemptCount: number;
+    readonly groupId?: string;
+}
+interface A2UIActionResult {
+    readonly requestId: string;
+    readonly action: ClientAction;
+    readonly surfaceId: string;
+    readonly stateId: string;
+    readonly revision: number;
+    readonly status: "accepted" | "rejected";
+    readonly reasonCode?: string;
+    readonly fieldErrors: readonly AckFieldError[];
+    readonly groupId?: string;
+}
+interface A2UIActionState {
+    readonly pendingRequests: readonly A2UIPendingAction[];
+    readonly lastResult: A2UIActionResult | null;
+}
+
+/**
+ * Protocol-neutral A2UI session lifecycle over a structural LiveKit room.
+ *
+ * LiveKit SDK imports stay out of this module and its declarations. Hosts
+ * retain ownership of shared rooms and must explicitly identify which remote
+ * participant is trusted to publish Flow Factory server envelopes.
+ */
+
+interface A2UITextStreamReaderLike {
+    readonly info?: {
+        readonly size?: number;
+    };
+    readAll(options?: {
+        signal?: AbortSignal;
+    }): Promise<string>;
+}
+interface A2UIStreamParticipant {
+    readonly identity: string;
+}
+type A2UITextStreamHandler = (reader: A2UITextStreamReaderLike, participant: A2UIStreamParticipant) => void;
+type A2UIRoomEvent = "reconnected" | "disconnected";
+/** Minimal room contract used by the adapter; no LiveKit SDK type is exposed. */
+interface A2UIRoomLike {
+    readonly localParticipant: {
+        sendText(text: string, options: {
+            topic: string;
+        }): Promise<unknown>;
+    };
+    registerTextStreamHandler(topic: string, handler: A2UITextStreamHandler): void;
+    unregisterTextStreamHandler(topic: string): void;
+    on(event: A2UIRoomEvent, listener: () => void): unknown;
+    off(event: A2UIRoomEvent, listener: () => void): unknown;
+}
+type A2UITrustedServerParticipant = (participant: A2UIStreamParticipant) => boolean;
+type A2UISessionStatus = "idle" | "connecting" | "connected" | "unsupported" | "closed";
+interface A2UISurfaceMetadata {
+    readonly surfaceId: string;
+    readonly activeStateId: string | null;
+    readonly revision: number;
+    readonly sectionNavigation: SectionNavigation | null;
+    readonly fieldInteractions: readonly A2UIFieldInteractionGroup[];
+}
+/** Protocol-neutral local edit/navigation state exposed to host applications. */
+interface A2UIEditingSnapshot {
+    readonly authoritativeSectionId: string | null;
+    readonly viewedSectionId: string | null;
+    readonly dirtyGroupIds: readonly string[];
+    readonly pendingGroupIds: readonly string[];
+    readonly rejectedGroupIds: readonly string[];
+}
+interface A2UISessionSnapshot {
+    readonly status: A2UISessionStatus;
+    readonly restoring: boolean;
+    readonly surface: A2UISurfaceMetadata | null;
+    readonly actions: A2UIActionState;
+    readonly editing: A2UIEditingSnapshot;
+}
+interface A2UISessionControllerOptions {
+    room: A2UIRoomLike;
+    adapter: A2UIClientAdapter;
+    isTrustedServerParticipant: A2UITrustedServerParticipant;
+    participantRole?: ParticipantRole;
+    /** Time before a delivered action becomes explicitly retryable. */
+    actionAckTimeoutMs?: number;
+    /** Best-effort capability retry schedule for servers that attach after join. */
+    capabilityRetryScheduleMs?: readonly number[];
+}
+/** Attach one A2UI adapter to an existing, caller-owned room. */
+declare class A2UISessionController {
+    #private;
+    constructor(options: A2UISessionControllerOptions);
+    get status(): A2UISessionStatus;
+    get restoring(): boolean;
+    get surfaceMetadata(): A2UISurfaceMetadata | null;
+    get actionState(): A2UIActionState;
+    /** Retry one or every delivery-failed/timed-out request with its original id. */
+    retryPendingAction(requestId?: string): boolean;
+    /** Select the authoritative server-owned section without choosing workflow state. */
+    returnToCurrentSection(): boolean;
+    /** View one exact server-issued active/completed section locally. */
+    viewSection(sectionId: string): boolean;
+    /** Capture a renderer-owned group after a real user input/change event. */
+    captureFieldGroupDraft(groupId: string): boolean;
+    /** Commit one complete owning group against the latest surface revision. */
+    commitFieldGroup(groupId: string): boolean;
+    getSnapshot: () => A2UISessionSnapshot;
+    subscribe: (listener: () => void) => (() => void);
+    /** Register the server stream before announcing exact renderer capability. */
+    start(): Promise<void>;
+    /**
+     * Detach only A2UI handlers/listeners. The shared room remains caller-owned.
+     */
+    stop(): void;
+}
+
+export { A2UIClientAdapter as A, type A2UITrustedServerParticipant as B, A2UI_CAPABILITIES_TOPIC as C, A2UI_CLIENT_TOPIC as D, A2UI_PROTOCOL_VERSION as E, A2UI_SERVER_TOPIC as F, type AckEnvelope as G, type AckFieldError as H, type AdapterSurface as I, CLIENT_ACTIONS as J, CLIENT_ERROR_CODES as K, type ClientAction as L, type ClientErrorCode as M, ENVELOPE_VERSION as N, MAX_ENVELOPE_BYTES as O, type ParticipantRole as P, type SnapshotEnvelope as Q, type SurfaceUpdateEnvelope as R, type SectionNavigation as S, type A2UISurfaceMetadata as a, A2UISessionController as b, type A2UIRoomLike as c, type A2UIActionDeliveryStatus as d, type A2UIActionResult as e, type A2UIActionState as f, type A2UICapabilityEnvelope as g, type A2UIClientActionEnvelope as h, type A2UIClientAdapterOptions as i, type A2UIClientErrorEnvelope as j, type A2UIClientErrorEvent as k, type A2UIEditingSnapshot as l, type A2UIFieldControl as m, type A2UIFieldDescriptor as n, type A2UIFieldInteractionField as o, type A2UIFieldInteractionGroup as p, type A2UIFieldValue as q, type A2UIPendingAction as r, type A2UIRendererActionEvent as s, type A2UIServerEnvelope as t, type A2UISessionControllerOptions as u, type A2UISessionSnapshot as v, type A2UISessionStatus as w, type A2UIStreamParticipant as x, type A2UISurfaceStructure as y, type A2UITabDescriptor as z };