@copilotkit/vue 2.0.0-rc.20 → 2.0.0-rc.21

package/src/v2/components/A2UIMessageRenderer.ts

@@ -1,20 +1,22 @@
-import { computed, defineComponent, h } from "vue";
-import type { PropType } from "vue";
-import * as z from "zod";
+import { defineComponent, h, onBeforeUnmount, shallowRef, watch } from "vue";
+import type { Component, PropType } from "vue";
+import {
+  ɵA2UIActivityController,
+  ɵA2UI_SURFACE_ACTIVITY_TYPE,
+  ɵA2UI_SURFACE_CONTENT_SCHEMA,
+} from "@copilotkit/core";
+import type {
+  ɵA2UIActionAgent,
+  ɵA2UIActionInterceptor,
+  ɵA2UISurfaceContent,
+} from "@copilotkit/core";
+import type { ActivityMessage } from "@ag-ui/core";
 import type { VueActivityMessageRenderer } from "../types";
 import type { A2UITheme } from "../types";
 import A2UISurfaceActivityRenderer from "./A2UISurfaceActivityRenderer.vue";
-import {
-  A2UIBuildingState,
-  A2UILifecycleFields,
-  A2UIRecoveryFailure,
-  A2UIRetryingState,
-  resolveDebugExposure,
-} from "./a2ui/A2UIRecoveryStates";
+import { renderA2UILifecycleState } from "./a2ui/A2UIRecoveryStates";
 import type { A2UIRecoveryRendererOptions } from "./a2ui/A2UIRecoveryStates";
 
-const A2UI_OPERATIONS_KEY = "a2ui_operations";
-
 export type A2UIMessageRendererOptions = {
   theme: A2UITheme;
   catalog?: any;
@@ -25,88 +27,116 @@ export type A2UIMessageRendererOptions = {
    * sub-label appears, and how much retry/debug detail to surface.
    */
   recovery?: A2UIRecoveryRendererOptions;
+  /**
+   * Intercept actions before they reach the agent: return `null` to handle an
+   * action client-side, return an action to forward that one instead, or
+   * return nothing to forward it unchanged.
+   */
+  onAction?: ɵA2UIActionInterceptor;
 };
 
+function isComponent(value: unknown): value is Component {
+  return (
+    typeof value === "function" || (typeof value === "object" && value !== null)
+  );
+}
+
 /**
  * The `a2ui-surface` activity carries the WHOLE generative-UI lifecycle on one
  * stable messageId: pre-paint `status` ("building" | "retrying" | "failed")
- * with recovery detail, then `a2ui_operations` on paint. The states swap in
- * place, so the painted surface replaces the skeleton. `.loose()` keeps
- * the operations and any future fields.
+ * with recovery detail, then `a2ui_operations` on paint. Core's
+ * `ɵA2UIActivityController` decides what shows; this renderer draws it and
+ * keeps the surface mounted, hidden under the loader, until it has painted.
  */
-const A2UISurfaceContentSchema = z
-  .object({
-    a2ui_operations: z.array(z.any()).optional(),
-    ...A2UILifecycleFields,
-  })
-  .loose();
-
 export function createA2UIMessageRenderer(
   options: A2UIMessageRendererOptions,
 ): VueActivityMessageRenderer<any> {
-  const showAfterMs = options.recovery?.showAfterMs ?? 2000;
-  const showAfterAttempts = options.recovery?.showAfterAttempts ?? 2;
-  const optionDebugExposure = options.recovery?.debugExposure ?? "collapsed";
-
-  // Renders the pre-paint lifecycle state for a content snapshot.
-  const renderLifecycle = (content: any) => {
-    const debugExposure = resolveDebugExposure(content, optionDebugExposure);
-    if (content?.status === "failed") {
-      return h(A2UIRecoveryFailure, { content, debugExposure });
-    }
-    if (content?.status === "retrying") {
-      return h(A2UIRetryingState, {
-        content,
-        showAfterMs,
-        showAfterAttempts,
-        debugExposure,
-      });
-    }
-    // "building" / default: a host-supplied loader wins; else the skeleton.
-    if (options.loadingComponent) {
-      return h(options.loadingComponent as any);
-    }
-    return h(A2UIBuildingState, { content });
-  };
+  const loadingComponent = isComponent(options.loadingComponent)
+    ? options.loadingComponent
+    : undefined;
 
   return {
-    activityType: "a2ui-surface",
-    content: A2UISurfaceContentSchema,
+    activityType: ɵA2UI_SURFACE_ACTIVITY_TYPE,
+    content: ɵA2UI_SURFACE_CONTENT_SCHEMA,
     render: defineComponent({
       name: "A2UIMessageRendererHost",
       props: {
         activityType: { type: String, required: true },
-        content: { type: Object as PropType<any>, required: true },
-        message: { type: Object as PropType<any>, required: true },
+        content: {
+          type: Object as PropType<ɵA2UISurfaceContent>,
+          required: true,
+        },
+        message: { type: Object as PropType<ActivityMessage>, required: true },
         agent: {
-          type: Object as PropType<any>,
+          type: Object as PropType<ɵA2UIActionAgent>,
           required: false,
           default: undefined,
         },
       },
       setup(props) {
-        const operations = computed(() =>
-          Array.isArray(props.content?.[A2UI_OPERATIONS_KEY])
-            ? props.content[A2UI_OPERATIONS_KEY]
-            : [],
+        const controller = new ɵA2UIActivityController({
+          recovery: options.recovery,
+          warn:
+            process.env.NODE_ENV !== "production"
+              ? (message) => console.warn(message)
+              : undefined,
+        });
+        const snapshot = shallowRef(controller.getSnapshot());
+        const unsubscribe = controller.subscribe(() => {
+          snapshot.value = controller.getSnapshot();
+        });
+        watch(
+          () => props.content,
+          (content) => controller.setContent(content),
+          { immediate: true },
         );
+        onBeforeUnmount(() => {
+          unsubscribe();
+          controller.dispose();
+        });
+        const markRendered = () => controller.markRendered();
 
         return () => {
-          // No painted surface yet → the pre-paint lifecycle state. It shares
-          // this activity's messageId, so the painted surface below replaces
-          // it in place once operations arrive.
-          if (operations.value.length === 0) {
-            return renderLifecycle(props.content);
+          const current = snapshot.value;
+          if (current.view === "lifecycle") {
+            return renderA2UILifecycleState(current, loadingComponent);
           }
 
-          return h(A2UISurfaceActivityRenderer, {
-            activityType: "a2ui-surface",
-            content: { operations: operations.value },
-            message: props.message,
-            agent: props.agent,
-            theme: options.theme,
-            catalog: options.catalog,
-          });
+          const handingOff = current.view === "handoff";
+          return h("div", { style: { position: "relative" } }, [
+            // The surface stays mounted in the same place across the
+            // hand-off; only its wrapper styling changes, so what painted
+            // while hidden is kept.
+            h(
+              "div",
+              {
+                "aria-hidden": handingOff ? "true" : undefined,
+                style: handingOff
+                  ? {
+                      position: "absolute",
+                      inset: "0",
+                      opacity: 0,
+                      pointerEvents: "none",
+                    }
+                  : undefined,
+              },
+              [
+                h(A2UISurfaceActivityRenderer, {
+                  activityType: ɵA2UI_SURFACE_ACTIVITY_TYPE,
+                  content: { operations: current.operations },
+                  message: props.message,
+                  agent: props.agent,
+                  theme: options.theme,
+                  catalog: options.catalog,
+                  onAction: options.onAction,
+                  onRendered: markRendered,
+                }),
+              ],
+            ),
+            handingOff
+              ? renderA2UILifecycleState(current, loadingComponent)
+              : null,
+          ]);
         };
       },
     }),

package/src/v2/components/A2UISurfaceActivityRenderer.vue

@@ -1,147 +1,112 @@
 <script setup lang="ts">
-import { computed, h, onBeforeUnmount, shallowRef, ref, watch } from "vue";
-import type { VNode } from "vue";
+import { computed, onBeforeUnmount, shallowRef, watch } from "vue";
 import type { ActivityMessage } from "@ag-ui/core";
 import type { A2UITheme } from "../types";
 import type { A2UIOperation } from "./a2ui";
-import { getOperationSurfaceId } from "./a2ui";
 import { useCopilotKit } from "../providers";
 import { MessageProcessor } from "@a2ui/web_core/v0_9";
 import type { SurfaceModel } from "@a2ui/web_core/v0_9";
+import { A2UIOperationApplier } from "@copilotkit/a2ui-renderer/engine";
+import { A2UISurfaceDiagnostics } from "@copilotkit/a2ui-renderer/engine-core";
+import { ɵrunA2UIAction, ɵtoA2UIClientEvent } from "@copilotkit/core";
+import type {
+  ɵA2UIActionAgent,
+  ɵA2UIActionInterceptor,
+} from "@copilotkit/core";
 import { vueBasicCatalog, A2uiSurface } from "./a2ui/index";
 import type { VueComponentImplementation } from "./a2ui/index";
 
-const DEFAULT_SURFACE_ID = "default";
-
 const props = defineProps<{
   activityType: string;
-  content: { operations: A2UIOperation[] };
+  content: { operations: readonly A2UIOperation[] };
   message: ActivityMessage;
-  agent?: object;
+  agent?: ɵA2UIActionAgent;
   theme?: A2UITheme;
   catalog?: any;
+  /** Intercepts a user action before it reaches the agent. */
+  onAction?: ɵA2UIActionInterceptor;
 }>();
 
-const { copilotkit } = useCopilotKit();
+const emit = defineEmits<{
+  /** After each batch of operations was applied. */
+  rendered: [];
+}>();
 
-// MessageProcessor from @a2ui/web_core — framework-agnostic
-// Use shallowRef to avoid Vue's deep UnwrapRef which strips private class members
-const processorRef =
-  shallowRef<MessageProcessor<VueComponentImplementation> | null>(null);
-// Version counter to trigger Vue reactivity on processor state changes
-const version = ref(0);
-// Error state
-const error = ref<string | null>(null);
-// Track last processed operations hash to avoid re-processing
-let lastOpsHash = "";
+const { copilotkit } = useCopilotKit();
 
-function getOrCreateProcessor(): MessageProcessor<VueComponentImplementation> {
-  if (!processorRef.value) {
+type Surface = SurfaceModel<VueComponentImplementation>;
+
+// One processor for all surfaces of the activity; the core-shared applier
+// validates the operations and applies only what is new in each snapshot.
+// shallowRef avoids Vue's deep UnwrapRef, which strips private class members.
+let processor: MessageProcessor<VueComponentImplementation> | null = null;
+let applier: A2UIOperationApplier<VueComponentImplementation> | null = null;
+const surfaces = shallowRef<readonly Surface[]>([]);
+const error = shallowRef<string | null>(null);
+const diagnostics =
+  process.env.NODE_ENV !== "production"
+    ? new A2UISurfaceDiagnostics({ warn: (message) => console.warn(message) })
+    : null;
+
+function getApplier() {
+  if (!processor || !applier) {
     const catalog = props.catalog ?? vueBasicCatalog;
-    processorRef.value = new MessageProcessor<VueComponentImplementation>(
+    const created = new MessageProcessor<VueComponentImplementation>(
       [catalog],
-      (action: unknown) => {
-        handleAction(action);
-      },
+      (action) =>
+        ɵrunA2UIAction({
+          message: ɵtoA2UIClientEvent(action),
+          agent: props.agent,
+          core: copilotkit.value,
+          onAction: props.onAction,
+        }),
     );
+    processor = created;
+    applier = new A2UIOperationApplier(created, catalog.id);
   }
-  return processorRef.value;
-}
-
-async function handleAction(message: unknown) {
-  if (!props.agent) return;
-  try {
-    copilotkit.value.setProperties({
-      ...copilotkit.value.properties,
-      a2uiAction: message,
-    });
-    await copilotkit.value.runAgent({ agent: props.agent as any });
-  } finally {
-    const { a2uiAction, ...rest } = copilotkit.value.properties ?? {};
-    copilotkit.value.setProperties(rest);
-  }
+  return applier;
 }
 
-function processOperations(operations: A2UIOperation[]) {
-  if (!operations?.length) return;
-
-  const hash = JSON.stringify(operations);
-  if (hash === lastOpsHash) return;
-  lastOpsHash = hash;
-
-  const processor = getOrCreateProcessor();
+function processOperations(operations: readonly A2UIOperation[]) {
+  const current = getApplier();
   try {
-    // Group operations by surface ID
-    const grouped = new Map<string, A2UIOperation[]>();
-    for (const op of operations) {
-      const surfaceId = getOperationSurfaceId(op) ?? DEFAULT_SURFACE_ID;
-      if (!grouped.has(surfaceId)) grouped.set(surfaceId, []);
-      grouped.get(surfaceId)!.push(op);
-    }
-
-    // For each surface, skip createSurface if the surface already exists
-    for (const [surfaceId, ops] of grouped) {
-      const existing = processor.model.getSurface(surfaceId);
-      const filtered = existing
-        ? ops.filter((op) => !(op as any)?.createSurface)
-        : ops;
-      processor.processMessages(filtered as any);
-    }
+    surfaces.value = current.apply(operations);
     error.value = null;
   } catch (err) {
     console.warn("[A2UI Vue] processMessages error:", err);
     error.value = err instanceof Error ? err.message : String(err);
+    surfaces.value = [];
+    return;
   }
-  version.value++;
+  if (processor) diagnostics?.check(operations, processor.model);
+  emit("rendered");
 }
 
-// Process operations on mount and when they change
+// A new catalog needs a new processor, rebuilt from the current operations.
 watch(
-  () => [props.content.operations, props.theme, props.catalog, props.agent],
+  () => props.catalog,
   () => {
-    processOperations(props.content.operations);
+    processor = null;
+    applier = null;
+    processOperations(props.content.operations ?? []);
   },
+);
+
+watch(
+  () => props.content.operations,
+  (operations) => processOperations(operations ?? []),
   { deep: true, immediate: true },
 );
 
 onBeforeUnmount(() => {
-  processorRef.value = null;
-  lastOpsHash = "";
+  diagnostics?.dispose();
+  processor = null;
+  applier = null;
 });
 
 const hasOperations = computed(
   () => (props.content.operations ?? []).length > 0,
 );
-
-// Compute the list of surfaces to render
-const surfaceEntries = computed(() => {
-  // Touch version to ensure reactivity
-  void version.value;
-
-  if (!processorRef.value) return [];
-
-  const entries: Array<{
-    surfaceId: string;
-    surface: SurfaceModel<VueComponentImplementation>;
-  }> = [];
-
-  // Group operations by surface to know which surfaces we expect
-  const grouped = new Map<string, A2UIOperation[]>();
-  for (const op of props.content.operations ?? []) {
-    const surfaceId = getOperationSurfaceId(op) ?? DEFAULT_SURFACE_ID;
-    if (!grouped.has(surfaceId)) grouped.set(surfaceId, []);
-    grouped.get(surfaceId)!.push(op);
-  }
-
-  for (const [surfaceId] of grouped) {
-    const surface = processorRef.value.model.getSurface(surfaceId);
-    if (surface) {
-      entries.push({ surfaceId, surface });
-    }
-  }
-
-  return entries;
-});
 </script>
 
 <template>
@@ -160,13 +125,13 @@ const surfaceEntries = computed(() => {
       data-testid="a2ui-activity-renderer"
     >
       <div
-        v-for="entry in surfaceEntries"
-        :key="entry.surfaceId"
+        v-for="surface in surfaces"
+        :key="surface.id"
         class="cpk-a2ui-message-surface-host"
-        :data-surface-id="entry.surfaceId"
+        :data-surface-id="surface.id"
       >
         <div class="a2ui-surface cpk-a2ui-message-surface">
-          <A2uiSurface :surface="entry.surface" />
+          <A2uiSurface :surface="surface" />
         </div>
       </div>
     </div>

package/src/v2/components/CopilotKitInspector.vue

@@ -4,9 +4,9 @@ defineOptions({
   inheritAttrs: false,
 });
 
-import { onMounted, onUnmounted, shallowRef, useAttrs, watch } from "vue";
-import type { ObjectDirective } from "vue";
-import type { WebInspectorElement } from "@copilotkit/web-inspector";
+import { onBeforeUnmount, onMounted, ref, useAttrs, watch } from "vue";
+import { ɵmountInspector } from "@copilotkit/web-inspector/mount";
+import type { ɵInspectorMount } from "@copilotkit/web-inspector/mount";
 import type { CopilotKitCoreVue } from "../lib/vue-core";
 import type { VueInspectorOpenRequest } from "../providers/keys";
 
@@ -15,72 +15,125 @@ const props = defineProps<{
   openRequest?: VueInspectorOpenRequest | null;
 }>();
 
+const emit = defineEmits<{
+  "visibility-change": [visible: boolean];
+}>();
+
 const attrs = useAttrs();
-const inspectorTag = shallowRef<string | null>(null);
-const inspector = shallowRef<WebInspectorElement | null>(null);
-
-let isMounted = true;
-let configureInspector:
-  | ((
-      element: WebInspectorElement,
-      core: CopilotKitCoreVue | null,
-    ) => WebInspectorElement)
-  | null = null;
-
-const vConfigureInspector: ObjectDirective<WebInspectorElement, undefined> = {
-  created(element) {
-    configureInspector?.(element, props.core ?? null);
-    inspector.value = element;
-    if (props.openRequest) {
-      element.openInspector?.("message_toolbar", props.openRequest);
+const host = ref<HTMLSpanElement | null>(null);
+let mount: ɵInspectorMount | null = null;
+let appliedAttributes: Record<string, string> = {};
+const boundListeners = new Map<
+  string,
+  { eventName: string; listener: (event: Event) => void }
+>();
+
+function isListener(name: string, value: unknown) {
+  const isHandler = typeof value === "function" || Array.isArray(value);
+  return /^on[A-Z]/.test(name) && isHandler;
+}
+
+/** `onCpkInspectorVisibilityChange` listens to `cpk-inspector-visibility-change`, as in Vue. */
+function toEventName(name: string) {
+  return name
+    .slice(2)
+    .replace(/\B([A-Z])/g, "-$1")
+    .toLowerCase();
+}
+
+// Text attributes and listeners go to the Inspector element (the host is only
+// a mount point), so `data-testid` or `@cpk-inspector-visibility-change`
+// land where callers expect them.
+function toAttributes(source: Record<string, unknown>) {
+  const attributes: Record<string, string> = {};
+  for (const [name, value] of Object.entries(source)) {
+    if (typeof value === "string" || typeof value === "number") {
+      attributes[name] = String(value);
+    } else if (value === true) {
+      attributes[name] = "";
     }
-  },
-};
+  }
+  return attributes;
+}
+
+function callListener(name: string, event: Event) {
+  const handler = attrs[name];
+  const handlers = Array.isArray(handler) ? handler : [handler];
+  for (const candidate of handlers) {
+    if (typeof candidate === "function") candidate(event);
+  }
+}
+
+function syncListeners(element: Element) {
+  const names = Object.keys(attrs).filter((name) =>
+    isListener(name, attrs[name]),
+  );
+  for (const [name, bound] of boundListeners) {
+    if (names.includes(name)) continue;
+    element.removeEventListener(bound.eventName, bound.listener);
+    boundListeners.delete(name);
+  }
+  for (const name of names) {
+    if (boundListeners.has(name)) continue;
+    const bound = {
+      eventName: toEventName(name),
+      listener: (event: Event) => callListener(name, event),
+    };
+    element.addEventListener(bound.eventName, bound.listener);
+    boundListeners.set(name, bound);
+  }
+}
+
+function syncAttributes() {
+  const element = mount?.element;
+  if (!element) return;
+  const next = toAttributes(attrs);
+  for (const name of Object.keys(appliedAttributes)) {
+    if (!(name in next)) element.removeAttribute(name);
+  }
+  for (const [name, value] of Object.entries(next)) {
+    element.setAttribute(name, value);
+  }
+  appliedAttributes = next;
+  syncListeners(element);
+}
 
 onMounted(() => {
-  void import("@copilotkit/web-inspector")
-    .then((mod) => {
-      if (!isMounted) return;
-
-      mod.defineWebInspector?.();
-      configureInspector = (element, core) =>
-        mod.configureWebInspectorElement(element, core, {
-          development: process.env.NODE_ENV === "development",
-          framework: "vue",
-          sdkVersion,
-        });
-      inspectorTag.value = mod.WEB_INSPECTOR_TAG;
-    })
-    .catch((error: unknown) => {
-      console.error("Failed to load CopilotKit inspector:", error);
-    });
+  if (!host.value) return;
+  mount = ɵmountInspector(host.value, props.core ?? null, {
+    load: () => import("@copilotkit/web-inspector"),
+    notificationContext: {
+      development: process.env.NODE_ENV === "development",
+      framework: "vue",
+      sdkVersion,
+    },
+  });
+  mount.onVisibility((visible) => emit("visibility-change", visible));
+  mount.onElement(syncAttributes);
+  if (props.openRequest) mount.open(props.openRequest);
 });
 
-onUnmounted(() => {
-  isMounted = false;
-  inspector.value = null;
+onBeforeUnmount(() => {
+  boundListeners.clear();
+  mount?.dispose();
+  mount = null;
 });
 
 watch(
   () => props.core,
-  (core) => {
-    if (inspector.value) inspector.value.core = core ?? null;
-  },
+  (core) => mount?.setCore(core ?? null),
 );
 
 watch(
   () => props.openRequest,
   (request) => {
-    if (request) inspector.value?.openInspector?.("message_toolbar", request);
+    if (request) mount?.open(request);
   },
 );
+
+watch(() => ({ ...attrs }), syncAttributes);
 </script>
 
 <template>
-  <component
-    :is="inspectorTag"
-    v-if="inspectorTag"
-    v-bind="attrs"
-    v-configure-inspector
-  />
+  <span ref="host" style="display: contents" />
 </template>