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

package/src/v2/components/__tests__/A2UIMessageRenderer.test.ts

@@ -1,17 +1,25 @@
-import { describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
 import { defineComponent, h, ref } from "vue";
-import { render, waitFor } from "@testing-library/vue";
+import { fireEvent, render, waitFor } from "@testing-library/vue";
+import type { ɵA2UIActionInterceptor } from "@copilotkit/core";
 import { createA2UIMessageRenderer } from "../A2UIMessageRenderer";
 import { CopilotKitKey } from "../../providers/keys";
 
-function copilotKitProvide() {
+function copilotKitProvide(
+  onRunAgent: (properties: Record<string, unknown>) => void = () => undefined,
+) {
+  const copilotkit = {
+    properties: {} as Record<string, unknown>,
+    setProperties(properties: Record<string, unknown>) {
+      copilotkit.properties = properties;
+    },
+    runAgent: async () => {
+      onRunAgent(copilotkit.properties);
+    },
+  };
   return {
     [CopilotKitKey as symbol]: {
-      copilotkit: ref({
-        properties: {},
-        setProperties: () => undefined,
-        runAgent: async () => undefined,
-      }),
+      copilotkit: ref(copilotkit),
       executingToolCallIds: ref(new Set()),
       a2uiTheme: ref({}),
       a2uiCatalog: ref(undefined),
@@ -22,6 +30,10 @@ function copilotKitProvide() {
 }
 
 describe("createA2UIMessageRenderer", () => {
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
   const renderLifecycle = (
     content: Record<string, unknown>,
     options: Partial<Parameters<typeof createA2UIMessageRenderer>[0]> = {},
@@ -46,6 +58,43 @@ describe("createA2UIMessageRenderer", () => {
     expect(container.textContent).toContain("~97 tokens");
   });
 
+  it("keeps an early retry looking like building until showAfterMs passes", async () => {
+    vi.useFakeTimers();
+    const { container } = renderLifecycle(
+      { status: "retrying", attempt: 1, maxAttempts: 3 },
+      { recovery: { showAfterMs: 2000 } },
+    );
+    expect(container.textContent).toContain("Building interface");
+    await vi.advanceTimersByTimeAsync(2000);
+    expect(container.textContent).toContain(
+      "Retrying generation… (1/3 attempts)",
+    );
+  });
+
+  it("shows retry validation issues unless debugExposure is hidden", () => {
+    const retry = {
+      status: "retrying",
+      attempt: 2,
+      errors: [{ code: "missing_required_prop" }],
+    };
+    const shown = renderLifecycle(retry);
+    expect(shown.container.querySelector("details summary")?.textContent).toBe(
+      "validation issues",
+    );
+    expect(shown.container.textContent).toContain("missing_required_prop");
+    const hidden = renderLifecycle(retry, {
+      recovery: { debugExposure: "hidden" },
+    });
+    expect(hidden.container.querySelector("details")).toBeNull();
+  });
+
+  it("shows collapsed developer details on failure by default", () => {
+    const { container } = renderLifecycle({ status: "failed", error: "boom" });
+    const details = container.querySelector("details");
+    expect(details?.hasAttribute("open")).toBe(false);
+    expect(details?.textContent).toContain("boom");
+  });
+
   it("shows the retry state for status 'retrying'", () => {
     const { container } = renderLifecycle({
       status: "retrying",
@@ -295,4 +344,118 @@ describe("createA2UIMessageRenderer", () => {
       expect(container.querySelector("[data-surface-id='s2']")).not.toBeNull();
     });
   });
+
+  const buttonContent = {
+    a2ui_operations: [
+      {
+        version: "v0.9",
+        createSurface: {
+          surfaceId: "form",
+          catalogId: "https://a2ui.org/specification/v0_9/basic_catalog.json",
+        },
+      },
+      {
+        version: "v0.9",
+        updateComponents: {
+          surfaceId: "form",
+          components: [
+            {
+              id: "root",
+              component: "Button",
+              child: "label",
+              action: { event: { name: "confirm", context: { n: 1 } } },
+            },
+            { id: "label", component: "Text", text: "Confirm" },
+          ],
+        },
+      },
+    ],
+  };
+
+  /** Renders the button surface, clicks it, and returns what reached the agent. */
+  async function clickButton(onAction?: ɵA2UIActionInterceptor) {
+    const forwarded: Record<string, unknown>[] = [];
+    const renderer = createA2UIMessageRenderer({ theme: {}, onAction });
+    const { findByRole } = render(renderer.render, {
+      props: {
+        activityType: "a2ui-surface",
+        content: buttonContent,
+        message: {},
+        agent: { agentId: "a" },
+      },
+      global: {
+        provide: copilotKitProvide((properties) =>
+          forwarded.push({ ...properties }),
+        ),
+      },
+    });
+    await fireEvent.click(await findByRole("button", { hidden: true }));
+    return forwarded;
+  }
+
+  it("forwards a button click to the agent wrapped as an A2UI userAction envelope", async () => {
+    const forwarded = await clickButton();
+    await waitFor(() => expect(forwarded).toHaveLength(1));
+    expect(forwarded[0]).toEqual({
+      a2uiAction: {
+        userAction: {
+          name: "confirm",
+          surfaceId: "form",
+          sourceComponentId: "root",
+          context: { n: 1 },
+          timestamp: expect.any(String),
+        },
+      },
+    });
+  });
+
+  it("does not run the agent when onAction handles the action", async () => {
+    const onAction = vi.fn<ɵA2UIActionInterceptor>(() => null);
+    const forwarded = await clickButton(onAction);
+    await waitFor(() => expect(onAction).toHaveBeenCalledOnce());
+    expect(forwarded).toEqual([]);
+  });
+
+  it("keeps the loader over the hidden surface until the surface can paint", async () => {
+    const renderer = createA2UIMessageRenderer({ theme: {} });
+    const createOnly = {
+      a2ui_operations: [buttonContent.a2ui_operations[0]],
+    };
+    const mounted = render(renderer.render, {
+      props: {
+        activityType: "a2ui-surface",
+        content: { status: "building", progressTokens: 120 },
+        message: {},
+        agent: {},
+      },
+      global: { provide: copilotKitProvide() },
+    });
+
+    await mounted.rerender({
+      activityType: "a2ui-surface",
+      content: createOnly,
+      message: {},
+      agent: {},
+    });
+    // A surface without components cannot paint: the loader stays on top.
+    expect(mounted.container.textContent).toContain("~120 tokens");
+    expect(
+      mounted.container.querySelector(
+        "[aria-hidden='true'] [data-testid='a2ui-activity-renderer']",
+      ),
+    ).not.toBeNull();
+
+    await mounted.rerender({
+      activityType: "a2ui-surface",
+      content: buttonContent,
+      message: {},
+      agent: {},
+    });
+    await waitFor(() => {
+      expect(mounted.container.textContent).not.toContain("Building interface");
+      expect(
+        mounted.container.querySelector("[aria-hidden='true']"),
+      ).toBeNull();
+    });
+  });
 });

package/src/v2/components/__tests__/CopilotKitInspector.test.ts

@@ -62,6 +62,48 @@ describe("CopilotKitInspector", () => {
     );
   });
 
+  it("forwards event listeners to the web inspector element", async () => {
+    const onVisibility = vi.fn();
+    const wrapper = mount(CopilotKitInspector, {
+      attrs: { onCpkInspectorVisibilityChange: onVisibility },
+    });
+    await settleInspectorLoad();
+
+    const event = new CustomEvent("cpk-inspector-visibility-change", {
+      detail: { visible: false },
+    });
+    wrapper.get("cpk-web-inspector").element.dispatchEvent(event);
+
+    expect(onVisibility).toHaveBeenCalledWith(event);
+  });
+
+  it("opens a request made before the web inspector module resolves", async () => {
+    const wrapper = mount(CopilotKitInspector);
+    const openRequest = { messageId: "message-early" };
+    await wrapper.setProps({ openRequest });
+
+    await settleInspectorLoad();
+
+    const inspector = wrapper.get("cpk-web-inspector")
+      .element as HTMLElement & {
+      openInspector: ReturnType<typeof vi.fn>;
+    };
+    expect(inspector.openInspector).toHaveBeenCalledExactlyOnceWith(
+      "message_toolbar",
+      openRequest,
+    );
+  });
+
+  it("emits Inspector visibility and removes the element on unmount", async () => {
+    const wrapper = mount(CopilotKitInspector, { attachTo: document.body });
+    await settleInspectorLoad();
+    expect(wrapper.emitted("visibility-change")).toEqual([[true]]);
+
+    wrapper.unmount();
+
+    expect(document.querySelector("cpk-web-inspector")).toBeNull();
+  });
+
   it("forwards Inspector open requests to the mounted element", async () => {
     const openRequest = { messageId: "message-1" };
     const wrapper = mount(CopilotKitInspector, {

package/src/v2/components/__tests__/OpenGenerativeUIRenderer.test.ts

@@ -100,16 +100,23 @@ describe("OpenGenerativeUIRenderer", () => {
     vi.restoreAllMocks();
   });
 
-  it("renders placeholder when no html", async () => {
+  it("shows the progress overlay with a spinner while generating", async () => {
     const { getByTestId, queryByTestId } = renderRenderer({
       initialHeight: 300,
     });
     await flushImport();
-    expect(getByTestId("open-generative-ui-placeholder")).not.toBeNull();
+    expect(getByTestId("open-generative-ui-spinner")).not.toBeNull();
     expect(queryByTestId("open-generative-ui-final-sandbox")).toBeNull();
     expect(mockCreate).not.toHaveBeenCalled();
   });
 
+  it("shows no spinner or overlay once generation is done", async () => {
+    const { queryByTestId } = renderRenderer({ generating: false });
+    await flushImport();
+    expect(queryByTestId("open-generative-ui-progress-overlay")).toBeNull();
+    expect(queryByTestId("open-generative-ui-spinner")).toBeNull();
+  });
+
   it("creates final sandbox when html is complete", async () => {
     renderRenderer({
       html: ["<head></head><body><p>Hello</p></body>"],

package/src/v2/components/__tests__/OpenGenerativeUIToolRenderer.test.ts

@@ -0,0 +1,38 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { render } from "@testing-library/vue";
+import { ToolCallStatus } from "@copilotkit/core";
+import { OpenGenerativeUIToolRenderer } from "../OpenGenerativeUIRenderer";
+
+function toolProps(messages: string[], status = ToolCallStatus.InProgress) {
+  return {
+    name: "generateSandboxedUi",
+    args: { placeholderMessages: [...messages] },
+    status,
+  };
+}
+
+describe("OpenGenerativeUIToolRenderer", () => {
+  beforeEach(() => vi.useFakeTimers());
+  afterEach(() => vi.useRealTimers());
+
+  it("keeps rotating while streamed snapshots repeat the same messages", async () => {
+    const view = render(OpenGenerativeUIToolRenderer, {
+      props: toolProps(["Sketching", "Styling"]),
+    });
+    expect(view.container.textContent).toBe("Styling");
+
+    await vi.advanceTimersByTimeAsync(4000);
+    await view.rerender(toolProps(["Sketching", "Styling"]));
+    await vi.advanceTimersByTimeAsync(1000);
+
+    expect(view.container.textContent).toBe("Sketching");
+  });
+
+  it("renders nothing once the tool call is complete", async () => {
+    const view = render(OpenGenerativeUIToolRenderer, {
+      props: toolProps(["Sketching"]),
+    });
+    await view.rerender(toolProps(["Sketching"], ToolCallStatus.Complete));
+    expect(view.container.textContent).toBe("");
+  });
+});

package/src/v2/components/a2ui/A2UIBuiltInToolCallRenderer.ts

@@ -1,15 +1,10 @@
 import { watch } from "vue";
 import type { ShallowRef } from "vue";
 import * as z from "zod";
+import { ɵRENDER_A2UI_TOOL_NAME as RENDER_A2UI_TOOL_NAME } from "@copilotkit/core";
 import type { CopilotKitCoreVue } from "../../lib/vue-core";
 import { defineToolCallRenderer } from "../../types/defineToolCallRenderer";
 
-/**
- * Tool name used by the dynamic A2UI generation secondary LLM.
- * This renderer is auto-registered when A2UI is enabled.
- */
-export const RENDER_A2UI_TOOL_NAME = "render_a2ui";
-
 /**
  * Registers a no-op renderer for the `render_a2ui` tool call so its raw
  * streamed args are never surfaced in the transcript, as React does.

package/src/v2/components/a2ui/A2UICatalogContext.ts

@@ -1,116 +1,50 @@
-import { computed, watch } from "vue";
+import { watch } from "vue";
 import type { ShallowRef } from "vue";
 import type { Catalog, ComponentApi } from "@a2ui/web_core/v0_9";
-import {
-  A2UI_SCHEMA_CONTEXT_DESCRIPTION,
-  buildCatalogContextValue as buildContextValue,
-  extractCatalogComponentSchemas,
-} from "@copilotkit/a2ui-renderer/catalog-schema";
-import {
-  A2UI_DEFAULT_GENERATION_GUIDELINES,
-  A2UI_DEFAULT_DESIGN_GUIDELINES,
-} from "@copilotkit/shared";
+import { A2UICatalogController } from "@copilotkit/a2ui-renderer/catalog-schema";
 import type { CopilotKitCoreVue } from "../../lib/vue-core";
 import { vueBasicCatalog } from "./catalog";
 
 /**
- * Build a context string describing the available A2UI catalog.
- * Defaults to the Vue basic catalog.
+ * Keeps the provider's A2UI catalog in sync with core through the shared
+ * `A2UICatalogController`: registers its components (so the Inspector can
+ * toggle them), reports the catalog with disabled components removed, and
+ * registers the agent context entries scoped to `core.a2uiAgents` while A2UI
+ * is on. Call from the provider's setup function.
  *
- * When `options.includeSchema` is `false`, custom components are listed by name
- * only and their JSON schemas are omitted.
+ * @param copilotkit - The provider's core.
+ * @param options.onFilteredCatalog - Receives the filtered catalog each time
+ *   it changes; the provider renders surfaces with it.
  */
-export function buildCatalogContextValue(
-  catalog?: Catalog<ComponentApi>,
-  options?: { includeSchema?: boolean },
-): string {
-  return buildContextValue(catalog ?? vueBasicCatalog, options);
-}
-
-/**
- * Registers agent context describing the available A2UI catalog, component
- * schemas, and generation/design guidelines.
- *
- * Vue-native equivalent of React's `<A2UICatalogContext>` component.
- * Call from the provider's setup function.
- */
-export function registerA2UICatalogContext(
+export function registerA2UICatalog(
   copilotkit: ShallowRef<CopilotKitCoreVue>,
   options: {
     enabled: () => boolean;
     catalog: () => Catalog<ComponentApi> | undefined;
     includeSchema: () => boolean;
+    onFilteredCatalog: (catalog: Catalog<ComponentApi> | undefined) => void;
   },
 ): void {
-  const contextValue = computed(() =>
-    buildCatalogContextValue(options.catalog(), {
-      includeSchema: options.includeSchema(),
-    }),
-  );
-
-  // Register catalog capabilities context
-  watch(
-    [() => copilotkit.value, options.enabled, contextValue],
-    ([core, isEnabled, value], _prev, onCleanup) => {
-      if (!isEnabled) return;
-      // Scope to the agents the runtime applies A2UI to (#5369), so other
-      // agents on the endpoint don't receive the catalog payload.
-      const agentIds = core.a2uiAgents;
-      const id = core.addContext({
-        description:
-          "A2UI catalog capabilities: available catalog IDs and " +
-          "custom component definitions the client can render.",
-        value,
-        ...(agentIds ? { agentIds } : {}),
-      });
-      onCleanup(() => core.removeContext(id));
-    },
-    { immediate: true },
-  );
-
-  // Register schema + generation/design guidelines
-  const schemaValue = computed(() => {
-    if (!options.includeSchema()) return null;
-    return JSON.stringify(
-      extractCatalogComponentSchemas(options.catalog() ?? vueBasicCatalog),
-    );
-  });
-
   watch(
-    [() => copilotkit.value, options.enabled, schemaValue],
-    ([core, isEnabled, schema], _prev, onCleanup) => {
-      if (!isEnabled || !schema) return;
-      const agentIds = core.a2uiAgents;
-      const scope = agentIds ? { agentIds } : {};
-      const ids: string[] = [];
-      ids.push(
-        core.addContext({
-          description: A2UI_SCHEMA_CONTEXT_DESCRIPTION,
-          value: schema,
-          ...scope,
-        }),
+    () => copilotkit.value,
+    (core, _previous, onCleanup) => {
+      const controller = new A2UICatalogController<Catalog<ComponentApi>>(
+        core,
+        vueBasicCatalog,
       );
-      ids.push(
-        core.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,
-          ...scope,
-        }),
+      const unsubscribe = controller.subscribe(() =>
+        options.onFilteredCatalog(controller.getSnapshot()),
       );
-      ids.push(
-        core.addContext({
-          description:
-            "A2UI design guidelines — visual design rules, component " +
-            "hierarchy tips, and action handler patterns.",
-          value: A2UI_DEFAULT_DESIGN_GUIDELINES,
-          ...scope,
-        }),
+      const stop = watch(
+        [options.enabled, options.catalog, options.includeSchema],
+        ([enabled, catalog, includeSchema]) =>
+          controller.update({ enabled, catalog, includeSchema }),
+        { immediate: true },
       );
       onCleanup(() => {
-        for (const id of ids) core.removeContext(id);
+        stop();
+        unsubscribe();
+        controller.dispose();
       });
     },
     { immediate: true },