@copilotkit/react-core 1.55.0-next.9 → 1.55.1-next.0

package/src/v2/__tests__/utils/test-helpers.tsx

@@ -164,6 +164,7 @@ export function renderWithCopilotKit({
   humanInTheLoop,
   agentId,
   threadId,
+  defaultThrottleMs,
   children,
 }: {
   agent?: AbstractAgent;
@@ -175,6 +176,7 @@ export function renderWithCopilotKit({
   humanInTheLoop?: any[];
   agentId?: string;
   threadId?: string;
+  defaultThrottleMs?: number;
   children?: React.ReactNode;
 }): ReturnType<typeof render> {
   const resolvedAgents = agents || (agent ? { default: agent } : undefined);
@@ -189,6 +191,7 @@ export function renderWithCopilotKit({
       renderActivityMessages={renderActivityMessages}
       frontendTools={frontendTools}
       humanInTheLoop={humanInTheLoop}
+      defaultThrottleMs={defaultThrottleMs}
     >
       <CopilotChatConfigurationProvider
         agentId={resolvedAgentId}
@@ -417,6 +420,70 @@ export function testId(prefix: string): string {
   return `${prefix}_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
 }
 
+// Varied content lengths for realistic message sizes in perf tests.
+const SAMPLE_ASSISTANT_TEXTS = [
+  "Sure! I'd be happy to help you with that.",
+  "The weather in San Francisco today is 65°F with partly cloudy skies.",
+  "Here are the main points from the meeting: 1) Roadmap review, 2) Bug triage, 3) Release planning.",
+  "To configure a custom agent, extend AbstractAgent and implement the run() method. Register it with CopilotKitProvider via the agents__unsafe_dev_only prop.",
+  "Here is a React component that fetches data from an API endpoint using useEffect and useState.",
+];
+
+/**
+ * Generate a realistic sequence of BaseEvents for N assistant messages.
+ * Uses TEXT_MESSAGE_CHUNK (the only event type proven to create rendered messages
+ * in jsdom tests). Every 5th message includes a tool call.
+ *
+ * Wrap in RUN_STARTED / RUN_FINISHED yourself if you need a full run sequence:
+ * @example
+ * agent.emit(runStartedEvent());
+ * for (const event of generateMessages(100)) agent.emit(event);
+ * agent.emit(runFinishedEvent());
+ */
+export function generateMessages(n: number): BaseEvent[] {
+  const events: BaseEvent[] = [];
+
+  for (let i = 0; i < n; i++) {
+    const msgId = `gen-msg-${i}`;
+    const text = SAMPLE_ASSISTANT_TEXTS[i % SAMPLE_ASSISTANT_TEXTS.length];
+
+    // Stream content in ~20-char chunks to simulate real streaming
+    for (let offset = 0; offset < text.length; offset += 20) {
+      events.push(textChunkEvent(msgId, text.slice(offset, offset + 20)));
+    }
+
+    // Every 5th message has a tool call for realistic variety
+    if (i % 5 === 4) {
+      const tcId = `gen-tc-${i}`;
+      const tcResult = `{"result":"tool output for message ${i}"}`;
+      events.push(
+        toolCallChunkEvent({
+          toolCallId: tcId,
+          toolCallName: "exampleTool",
+          parentMessageId: msgId,
+          delta: "",
+        }),
+      );
+      events.push(
+        toolCallChunkEvent({
+          toolCallId: tcId,
+          parentMessageId: msgId,
+          delta: tcResult,
+        }),
+      );
+      events.push(
+        toolCallResultEvent({
+          toolCallId: tcId,
+          messageId: `${msgId}-result`,
+          content: tcResult,
+        }),
+      );
+    }
+  }
+
+  return events;
+}
+
 /**
  * Helper to emit a complete suggestion tool call with streaming chunks
  */

package/src/v2/a2ui/A2UICatalogContext.tsx

@@ -0,0 +1,79 @@
+"use client";
+
+import {
+  buildCatalogContextValue,
+  A2UI_SCHEMA_CONTEXT_DESCRIPTION,
+  extractCatalogComponentSchemas,
+} from "@copilotkit/a2ui-renderer";
+import {
+  A2UI_DEFAULT_GENERATION_GUIDELINES,
+  A2UI_DEFAULT_DESIGN_GUIDELINES,
+} from "@copilotkit/shared";
+import { useAgentContext } from "../hooks/use-agent-context";
+import { useCopilotKit } from "../providers/CopilotKitProvider";
+import { useLayoutEffect, useMemo } from "react";
+
+/**
+ * Renders agent context describing the available A2UI catalog and custom components.
+ * Only mount this component when A2UI is enabled.
+ *
+ * When `includeSchema` is true, the full component schemas (JSON Schema) are also
+ * sent as context using the same description key as the A2UI middleware, so the
+ * middleware can optionally overwrite it with a server-side schema.
+ */
+export function A2UICatalogContext({
+  catalog,
+  includeSchema,
+}: {
+  catalog?: any;
+  includeSchema?: boolean;
+}) {
+  const contextValue = buildCatalogContextValue(catalog);
+
+  useAgentContext({
+    description:
+      "A2UI catalog capabilities: available catalog IDs and custom component definitions the client can render.",
+    value: contextValue,
+  });
+
+  // When includeSchema is true, send full component schemas in the same format
+  // as the A2UI middleware so it can overwrite with a server-side schema if needed.
+  const { copilotkit } = useCopilotKit();
+  const schemaValue = useMemo(
+    () =>
+      includeSchema !== false
+        ? JSON.stringify(extractCatalogComponentSchemas(catalog))
+        : null,
+    [catalog, includeSchema],
+  );
+
+  useLayoutEffect(() => {
+    if (!copilotkit || !schemaValue) return;
+    const ids: string[] = [];
+    ids.push(
+      copilotkit.addContext({
+        description: A2UI_SCHEMA_CONTEXT_DESCRIPTION,
+        value: schemaValue,
+      }),
+    );
+    ids.push(
+      copilotkit.addContext({
+        description:
+          "A2UI generation guidelines — protocol rules, tool arguments, path rules, data model format, and form/two-way-binding instructions.",
+        value: A2UI_DEFAULT_GENERATION_GUIDELINES,
+      }),
+    );
+    ids.push(
+      copilotkit.addContext({
+        description:
+          "A2UI design guidelines — visual design rules, component hierarchy tips, and action handler patterns.",
+        value: A2UI_DEFAULT_DESIGN_GUIDELINES,
+      }),
+    );
+    return () => {
+      for (const id of ids) copilotkit.removeContext(id);
+    };
+  }, [copilotkit, schemaValue]);
+
+  return null;
+}

package/src/v2/a2ui/A2UIMessageRenderer.tsx

@@ -5,6 +5,7 @@ import { z } from "zod";
 import {
   A2UIProvider,
   useA2UIActions,
+  useA2UIError,
   A2UIRenderer,
   initializeDefaultCatalog,
   injectStyles,
@@ -12,6 +13,12 @@ import {
 } from "@copilotkit/a2ui-renderer";
 import type { Theme, A2UIClientEventMessage } from "@copilotkit/a2ui-renderer";
 
+/**
+ * The container key used to wrap A2UI operations for explicit detection.
+ * Must match A2UI_OPERATIONS_KEY in @ag-ui/a2ui-middleware and copilotkit.a2ui (Python).
+ */
+const A2UI_OPERATIONS_KEY = "a2ui_operations";
+
 // Initialize the React renderer's component catalog and styles once
 let initialized = false;
 function ensureInitialized() {
@@ -22,14 +29,30 @@ function ensureInitialized() {
   }
 }
 
+/**
+ * User action with dataContextPath, as dispatched by A2UI components.
+ */
+export type A2UIUserAction = {
+  name: string;
+  sourceComponentId: string;
+  surfaceId: string;
+  timestamp: string;
+  context?: Record<string, unknown>;
+  dataContextPath?: string;
+};
+
 export type A2UIMessageRendererOptions = {
   theme: Theme;
+  /** Optional component catalog to pass to A2UIProvider */
+  catalog?: any;
+  /** Optional custom loading component shown while A2UI surface is generating. */
+  loadingComponent?: React.ComponentType;
 };
 
 export function createA2UIMessageRenderer(
   options: A2UIMessageRendererOptions,
 ): ReactActivityMessageRenderer<any> {
-  const { theme } = options;
+  const { theme, catalog, loadingComponent } = options;
 
   return {
     activityType: "a2ui-surface",
@@ -38,24 +61,20 @@ export function createA2UIMessageRenderer(
       ensureInitialized();
 
       const [operations, setOperations] = useState<any[]>([]);
-      const lastSignatureRef = useRef<string | null>(null);
       const { copilotkit } = useCopilotKit();
 
+      const lastContentRef = useRef<unknown>(null);
       useEffect(() => {
-        if (!content || !Array.isArray(content.operations)) {
-          lastSignatureRef.current = null;
-          setOperations([]);
-          return;
-        }
-
-        const incoming = content.operations as any[];
-        const signature = stringifyOperations(incoming);
+        // Skip if same content reference
+        if (content === lastContentRef.current) return;
+        lastContentRef.current = content;
 
-        if (signature && signature === lastSignatureRef.current) {
+        const incoming = content?.[A2UI_OPERATIONS_KEY];
+        if (!content || !Array.isArray(incoming)) {
+          setOperations([]);
           return;
         }
 
-        lastSignatureRef.current = signature;
         setOperations(incoming);
       }, [content]);
 
@@ -77,7 +96,9 @@ export function createA2UIMessageRenderer(
       }, [operations]);
 
       if (!groupedOperations.size) {
-        return null;
+        // Show loading state while A2UI surface is being generated
+        const LoadingComponent = loadingComponent ?? DefaultA2UILoading;
+        return <LoadingComponent />;
       }
 
       return (
@@ -90,6 +111,7 @@ export function createA2UIMessageRenderer(
               theme={theme}
               agent={agent}
               copilotkit={copilotkit}
+              catalog={catalog}
             />
           ))}
         </div>
@@ -104,6 +126,8 @@ type ReactSurfaceHostProps = {
   theme: Theme;
   agent: any;
   copilotkit: any;
+  /** Optional component catalog to pass to A2UIProvider */
+  catalog?: any;
 };
 
 /**
@@ -116,15 +140,16 @@ function ReactSurfaceHost({
   theme,
   agent,
   copilotkit,
+  catalog,
 }: ReactSurfaceHostProps) {
-  // Bridge: when the React renderer dispatches an action, send it to CopilotKit
+  // Bridge: when the React renderer dispatches an action, forward to CopilotKit
   const handleAction = useCallback(
     async (message: A2UIClientEventMessage) => {
       if (!agent) return;
 
-      try {
-        console.info("[A2UI] Action dispatched", message.userAction);
+      const action = message.userAction as A2UIUserAction | undefined;
 
+      try {
         copilotkit.setProperties({
           ...(copilotkit.properties ?? {}),
           a2uiAction: message,
@@ -143,17 +168,33 @@ function ReactSurfaceHost({
 
   return (
     <div className="cpk:flex cpk:w-full cpk:flex-none cpk:flex-col cpk:gap-4">
-      <A2UIProvider onAction={handleAction} theme={theme}>
+      <A2UIProvider onAction={handleAction} theme={theme} catalog={catalog}>
         <SurfaceMessageProcessor
           surfaceId={surfaceId}
           operations={operations}
         />
-        <A2UIRenderer surfaceId={surfaceId} className="cpk:flex cpk:flex-1" />
+        <A2UISurfaceOrError surfaceId={surfaceId} />
       </A2UIProvider>
     </div>
   );
 }
 
+/**
+ * Renders the A2UI surface, or an error message if processing failed.
+ * Must be a child of A2UIProvider to access the error state.
+ */
+function A2UISurfaceOrError({ surfaceId }: { surfaceId: string }) {
+  const error = useA2UIError();
+  if (error) {
+    return (
+      <div className="cpk:rounded-lg cpk:border cpk:border-red-200 cpk:bg-red-50 cpk:p-3 cpk:text-sm cpk:text-red-700">
+        A2UI render error: {error}
+      </div>
+    );
+  }
+  return <A2UIRenderer surfaceId={surfaceId} className="cpk:flex cpk:flex-1" />;
+}
+
 /**
  * Processes A2UI operations into the provider's message processor.
  * Must be a child of A2UIProvider to access the actions context.
@@ -165,20 +206,74 @@ function SurfaceMessageProcessor({
   surfaceId: string;
   operations: any[];
 }) {
-  const { processMessages } = useA2UIActions();
-  const lastProcessedRef = useRef<string>("");
-
+  const { processMessages, getSurface } = useA2UIActions();
+  const lastHashRef = useRef<string>("");
   useEffect(() => {
-    const key = `${surfaceId}-${JSON.stringify(operations)}`;
-    if (key === lastProcessedRef.current) return;
-    lastProcessedRef.current = key;
+    // Skip if operations haven't actually changed (deep compare via hash).
+    // ACTIVITY_DELTA + ACTIVITY_SNAPSHOT can trigger multiple renders with
+    // the same logical content but different object references.
+    const hash = JSON.stringify(operations);
+    if (hash === lastHashRef.current) return;
+    lastHashRef.current = hash;
 
-    processMessages(operations);
-  }, [processMessages, surfaceId, operations]);
+    // Filter out createSurface if the surface already exists — the
+    // MessageProcessor throws on duplicate createSurface, but content
+    // snapshots always include the full operation list.
+    const existing = getSurface(surfaceId);
+    const ops = existing
+      ? operations.filter((op) => !op?.createSurface)
+      : operations;
+
+    // Error handling is done inside A2UIProvider.processMessages
+    processMessages(ops);
+  }, [processMessages, getSurface, surfaceId, operations]);
 
   return null;
 }
 
+/**
+ * Default loading component shown while an A2UI surface is generating.
+ * Displays an animated shimmer skeleton.
+ */
+function DefaultA2UILoading() {
+  return (
+    <div
+      className="cpk:flex cpk:flex-col cpk:gap-3 cpk:rounded-xl cpk:border cpk:border-gray-100 cpk:bg-gray-50/50 cpk:p-5"
+      style={{ minHeight: 120 }}
+    >
+      <div className="cpk:flex cpk:items-center cpk:gap-2">
+        <div
+          className="cpk:h-3 cpk:w-3 cpk:rounded-full cpk:bg-gray-200"
+          style={{
+            animation: "cpk-a2ui-pulse 1.5s ease-in-out infinite",
+          }}
+        />
+        <span className="cpk:text-xs cpk:font-medium cpk:text-gray-400">
+          Generating UI...
+        </span>
+      </div>
+      <div className="cpk:flex cpk:flex-col cpk:gap-2">
+        {[0.8, 0.6, 0.4].map((width, i) => (
+          <div
+            key={i}
+            className="cpk:h-3 cpk:rounded cpk:bg-gray-200/70"
+            style={{
+              width: `${width * 100}%`,
+              animation: `cpk-a2ui-pulse 1.5s ease-in-out ${i * 0.15}s infinite`,
+            }}
+          />
+        ))}
+      </div>
+      <style>{`
+        @keyframes cpk-a2ui-pulse {
+          0%, 100% { opacity: 0.4; }
+          50% { opacity: 1; }
+        }
+      `}</style>
+    </div>
+  );
+}
+
 function getOperationSurfaceId(operation: any): string | null {
   if (!operation || typeof operation !== "object") {
     return null;
@@ -188,19 +283,12 @@ function getOperationSurfaceId(operation: any): string | null {
     return operation.surfaceId;
   }
 
+  // v0.9 message keys
   return (
-    operation?.beginRendering?.surfaceId ??
-    operation?.surfaceUpdate?.surfaceId ??
-    operation?.dataModelUpdate?.surfaceId ??
+    operation?.createSurface?.surfaceId ??
+    operation?.updateComponents?.surfaceId ??
+    operation?.updateDataModel?.surfaceId ??
     operation?.deleteSurface?.surfaceId ??
     null
   );
 }
-
-function stringifyOperations(ops: any[]): string | null {
-  try {
-    return JSON.stringify(ops);
-  } catch (error) {
-    return null;
-  }
-}