@copilotkit/react-core 1.56.1 → 1.56.2-canary.test-welcome-screen

package/src/v2/components/chat/__tests__/CopilotChatActivityRendering.e2e.test.tsx

@@ -1,7 +1,8 @@
 import React from "react";
-import { fireEvent, screen, waitFor } from "@testing-library/react";
+import { fireEvent, render, screen, waitFor } from "@testing-library/react";
 import { z } from "zod";
 import {
+  MockReconnectableAgent,
   MockStepwiseAgent,
   activitySnapshotEvent,
   renderWithCopilotKit,
@@ -10,9 +11,48 @@ import {
   testId,
 } from "../../../__tests__/utils/test-helpers";
 import { ReactActivityMessageRenderer } from "../../../types";
-import { useCopilotKit } from "../../../providers";
+import {
+  CopilotChatConfigurationProvider,
+  CopilotKitProvider,
+  useCopilotKit,
+} from "../../../providers";
 import { AbstractAgent } from "@ag-ui/client";
+import { IntelligenceAgent } from "@copilotkit/core";
 import { getThreadClone } from "../../../hooks/use-agent";
+import { createA2UIMessageRenderer } from "../../../a2ui/A2UIMessageRenderer";
+import type { Theme } from "@copilotkit/a2ui-renderer";
+import { CopilotChat } from "..";
+
+const { mockWebsandboxCreate, mockWebsandboxDestroy } = vi.hoisted(() => {
+  const mockDestroy = vi.fn();
+  const mockCreate = vi.fn(() => ({
+    iframe: document.createElement("iframe"),
+    promise: Promise.resolve(),
+    run: vi.fn().mockResolvedValue(undefined),
+    destroy: mockDestroy,
+  }));
+
+  return {
+    mockWebsandboxCreate: mockCreate,
+    mockWebsandboxDestroy: mockDestroy,
+  };
+});
+
+vi.mock("@jetbrains/websandbox", () => ({
+  default: {
+    create: (...args: unknown[]) => mockWebsandboxCreate(...args),
+  },
+}));
+
+function jsonResponse(body: unknown, status = 200): Response {
+  return {
+    ok: status >= 200 && status < 300,
+    status,
+    statusText: status === 200 ? "OK" : "Error",
+    json: async () => body,
+    text: async () => JSON.stringify(body),
+  } as Response;
+}
 
 describe("CopilotChat activity message rendering", () => {
   it("renders custom components for activity snapshots", async () => {
@@ -208,4 +248,262 @@ describe("CopilotChat activity message rendering", () => {
     expect(capturedAgent).toBe(clone);
     expect(capturedAgent).not.toBe(agent); // must NOT be the registry agent
   });
+
+  it("restores a completed A2UI surface after reconnect from an event-native baseline", async () => {
+    const agent = new MockReconnectableAgent();
+    const threadId = testId("a2ui-thread");
+    const surfaceId = testId("surface");
+    const a2uiRenderer = createA2UIMessageRenderer({
+      theme: {} as Theme,
+    });
+
+    const { unmount } = renderWithCopilotKit({
+      agent,
+      threadId,
+      renderActivityMessages: [a2uiRenderer],
+    });
+
+    const input = await screen.findByRole("textbox");
+    fireEvent.change(input, { target: { value: "Show me the restored UI" } });
+    fireEvent.keyDown(input, { key: "Enter", code: "Enter" });
+
+    await waitFor(() => {
+      expect(screen.getByText("Show me the restored UI")).toBeDefined();
+    });
+
+    agent.emit(runStartedEvent());
+    agent.emit(
+      activitySnapshotEvent({
+        messageId: testId("a2ui-activity"),
+        activityType: "a2ui-surface",
+        content: {
+          a2ui_operations: [
+            {
+              version: "v0.9",
+              createSurface: {
+                surfaceId,
+                catalogId:
+                  "https://a2ui.org/specification/v0_9/basic_catalog.json",
+              },
+            },
+            {
+              version: "v0.9",
+              updateComponents: {
+                surfaceId,
+                components: [
+                  {
+                    id: "root",
+                    component: "Text",
+                    text: "Restored dashboard",
+                    variant: "body",
+                  },
+                ],
+              },
+            },
+          ],
+        },
+      }),
+    );
+    agent.emit(runFinishedEvent());
+    agent.complete();
+
+    await waitFor(() => {
+      expect(
+        document.querySelector(`[data-surface-id='${surfaceId}']`),
+      ).not.toBeNull();
+    });
+
+    unmount();
+    agent.reset();
+
+    renderWithCopilotKit({
+      agent,
+      threadId,
+      renderActivityMessages: [a2uiRenderer],
+    });
+
+    await waitFor(() => {
+      expect(
+        document.querySelector(`[data-surface-id='${surfaceId}']`),
+      ).not.toBeNull();
+    });
+  });
+
+  it("restores a completed A2UI surface from an IntelligenceAgent /connect bootstrap plan", async () => {
+    const threadId = testId("intelligence-connect-thread");
+    const surfaceId = testId("intelligence-connect-surface");
+    const fetchMock = vi.fn().mockResolvedValueOnce(
+      jsonResponse({
+        mode: "bootstrap",
+        latestEventId: "event-3",
+        events: [
+          {
+            type: "RUN_STARTED",
+            threadId,
+            run_id: "backend-run-1",
+            input: {
+              messages: [
+                {
+                  id: testId("connect-user-message"),
+                  role: "user",
+                  content: "show me the restored ui",
+                },
+              ],
+            },
+          },
+          {
+            type: "ACTIVITY_SNAPSHOT",
+            messageId: testId("connect-a2ui-activity"),
+            activityType: "a2ui-surface",
+            content: {
+              a2ui_operations: [
+                {
+                  version: "v0.9",
+                  createSurface: {
+                    surfaceId,
+                    catalogId:
+                      "https://a2ui.org/specification/v0_9/basic_catalog.json",
+                  },
+                },
+                {
+                  version: "v0.9",
+                  updateComponents: {
+                    surfaceId,
+                    components: [
+                      {
+                        id: "root",
+                        component: "Text",
+                        text: "Restored dashboard",
+                        variant: "body",
+                      },
+                    ],
+                  },
+                },
+              ],
+            },
+          },
+          {
+            type: "RUN_FINISHED",
+          },
+        ],
+      }),
+    );
+    vi.stubGlobal("fetch", fetchMock);
+
+    const agent = new IntelligenceAgent({
+      url: "ws://localhost:4000/client",
+      runtimeUrl: "http://localhost:4000",
+      agentId: "my-agent",
+    });
+    const a2uiRenderer = createA2UIMessageRenderer({
+      theme: {} as Theme,
+    });
+
+    try {
+      renderWithCopilotKit({
+        agent,
+        threadId,
+        renderActivityMessages: [a2uiRenderer],
+      });
+
+      await waitFor(() => {
+        expect(fetchMock).toHaveBeenCalledTimes(1);
+      });
+      await waitFor(() => {
+        expect(screen.getByText("show me the restored ui")).toBeDefined();
+      });
+      await waitFor(() => {
+        expect(
+          document.querySelector(`[data-surface-id='${surfaceId}']`),
+        ).not.toBeNull();
+      });
+
+      const [url, options] = fetchMock.mock.calls[0] as [string, RequestInit];
+      expect(url).toContain("/agent/my-agent/connect");
+      expect(options.method).toBe("POST");
+
+      const requestBody = JSON.parse(String(options.body)) as {
+        threadId: string;
+        lastSeenEventId: string | null;
+        messages: unknown[];
+      };
+      expect(requestBody.threadId).toBe(threadId);
+      expect(requestBody.lastSeenEventId).toBeNull();
+      expect(requestBody.messages).toEqual([]);
+    } finally {
+      vi.unstubAllGlobals();
+    }
+  });
+
+  it("restores a completed Open Generative UI activity after reconnect from an event-native baseline", async () => {
+    mockWebsandboxCreate.mockClear();
+    mockWebsandboxDestroy.mockClear();
+
+    const agent = new MockReconnectableAgent();
+    const threadId = testId("open-generative-ui-thread");
+    const restoredHtml =
+      "<head></head><body><div>Restored open generative UI</div></body>";
+
+    const renderOpenGenerativeUIChat = () =>
+      render(
+        <CopilotKitProvider
+          agents__unsafe_dev_only={{ default: agent }}
+          openGenerativeUI={{}}
+        >
+          <CopilotChatConfigurationProvider threadId={threadId}>
+            <div style={{ height: 400 }}>
+              <CopilotChat welcomeScreen={false} />
+            </div>
+          </CopilotChatConfigurationProvider>
+        </CopilotKitProvider>,
+      );
+
+    const { unmount } = renderOpenGenerativeUIChat();
+
+    const input = await screen.findByRole("textbox");
+    fireEvent.change(input, { target: { value: "Show me the restored app" } });
+    fireEvent.keyDown(input, { key: "Enter", code: "Enter" });
+
+    await waitFor(() => {
+      expect(screen.getByText("Show me the restored app")).toBeDefined();
+    });
+
+    agent.emit(runStartedEvent());
+    agent.emit(
+      activitySnapshotEvent({
+        messageId: testId("open-generative-ui-activity"),
+        activityType: "open-generative-ui",
+        content: {
+          initialHeight: 180,
+          generating: false,
+          html: [restoredHtml],
+          htmlComplete: true,
+        },
+      }),
+    );
+    agent.emit(runFinishedEvent());
+    agent.complete();
+
+    await waitFor(() => {
+      expect(mockWebsandboxCreate).toHaveBeenCalledTimes(1);
+    });
+    expect(mockWebsandboxCreate.mock.calls[0]?.[1]).toMatchObject({
+      frameContent: restoredHtml,
+    });
+
+    unmount();
+
+    agent.reset();
+
+    renderOpenGenerativeUIChat();
+
+    await waitFor(() => {
+      expect(mockWebsandboxCreate).toHaveBeenCalledTimes(2);
+    });
+    expect(mockWebsandboxCreate.mock.calls[1]?.[1]).toMatchObject({
+      frameContent: restoredHtml,
+    });
+
+    expect(mockWebsandboxDestroy).toHaveBeenCalledTimes(1);
+  });
 });

package/src/v2/components/chat/__tests__/CopilotChatView.connectingGate.test.tsx

@@ -0,0 +1,56 @@
+import React from "react";
+import { render, screen } from "@testing-library/react";
+import { describe, it, expect } from "vitest";
+import { CopilotChatView } from "../CopilotChatView";
+import { CopilotKitProvider } from "../../../providers/CopilotKitProvider";
+import { CopilotChatConfigurationProvider } from "../../../providers/CopilotChatConfigurationProvider";
+
+// Minimal provider wrapper. No agent registry is required because these tests
+// only exercise local render decisions (welcome-screen suppression) that
+// don't touch the agent runtime.
+const TestWrapper: React.FC<{ children: React.ReactNode }> = ({ children }) => (
+  <CopilotKitProvider>
+    <CopilotChatConfigurationProvider threadId="test-thread">
+      <div style={{ height: 400 }}>{children}</div>
+    </CopilotChatConfigurationProvider>
+  </CopilotKitProvider>
+);
+
+describe("CopilotChatView connect-gating", () => {
+  it("suppresses the welcome screen while isConnecting=true", () => {
+    render(
+      <TestWrapper>
+        <CopilotChatView messages={[]} isConnecting />
+      </TestWrapper>,
+    );
+
+    // Switching threads would otherwise flash the welcome greeting before
+    // bootstrap messages arrive.
+    expect(screen.queryByTestId("copilot-welcome-screen")).toBeNull();
+  });
+
+  it("suppresses the welcome screen when hasExplicitThreadId=true", () => {
+    render(
+      <TestWrapper>
+        <CopilotChatView messages={[]} hasExplicitThreadId />
+      </TestWrapper>,
+    );
+
+    // A caller-managed thread (threadId prop / config provider) should never
+    // display the generic "start a new chat" welcome — even when the thread
+    // has no messages yet.
+    expect(screen.queryByTestId("copilot-welcome-screen")).toBeNull();
+  });
+
+  it("shows the welcome screen by default for a fresh empty chat", () => {
+    render(
+      <TestWrapper>
+        <CopilotChatView messages={[]} />
+      </TestWrapper>,
+    );
+
+    // Positive control: with no threadId supplied and no connect in flight,
+    // an empty chat should still render the welcome screen.
+    expect(screen.getByTestId("copilot-welcome-screen")).toBeDefined();
+  });
+});

package/src/v2/components/chat/__tests__/CopilotChatView.pinToSend.test.tsx

@@ -0,0 +1,94 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { render } from "@testing-library/react";
+import React from "react";
+import { CopilotKitProvider } from "../../../providers/CopilotKitProvider";
+import { CopilotChatConfigurationProvider } from "../../../providers/CopilotChatConfigurationProvider";
+import { CopilotChatView } from "../CopilotChatView";
+import { LastUserMessageContext } from "../last-user-message-context";
+
+beforeEach(() => {
+  HTMLElement.prototype.scrollTo = vi.fn();
+});
+
+// Wrapper to provide required context (same pattern as CopilotChatView.slots.e2e.test.tsx)
+const TestWrapper: React.FC<{ children: React.ReactNode }> = ({ children }) => (
+  <CopilotKitProvider>
+    <CopilotChatConfigurationProvider threadId="test-thread">
+      <div style={{ height: 400 }}>{children}</div>
+    </CopilotChatConfigurationProvider>
+  </CopilotKitProvider>
+);
+
+const sampleMessages = [
+  { id: "1", role: "user" as const, content: "Hello" },
+  { id: "2", role: "assistant" as const, content: "Hi there!" },
+];
+
+// Wait for the ScrollView's `hasMounted` useEffect to flip — the pre-mount
+// fallback render does not include the message list, so a findBy on the
+// message list is a reliable "mount is done" signal. Without this gate,
+// absence assertions pass vacuously against the pre-mount render.
+async function waitForMount(screen: {
+  findByTestId: (id: string) => Promise<HTMLElement>;
+}) {
+  await screen.findByTestId("copilot-message-list");
+}
+
+describe("CopilotChatView pin-to-send mode", () => {
+  it("renders the pin-to-send spacer element when autoScroll='pin-to-send'", async () => {
+    const screen = render(
+      <TestWrapper>
+        <LastUserMessageContext.Provider value={{ id: null, sendNonce: 0 }}>
+          <CopilotChatView autoScroll="pin-to-send" messages={sampleMessages} />
+        </LastUserMessageContext.Provider>
+      </TestWrapper>,
+    );
+    await waitForMount(screen);
+    const spacer = screen.container.querySelector("[data-pin-to-send-spacer]");
+    expect(spacer).not.toBeNull();
+  });
+
+  it("does not render the spacer when autoScroll='pin-to-bottom'", async () => {
+    const screen = render(
+      <TestWrapper>
+        <CopilotChatView autoScroll="pin-to-bottom" messages={sampleMessages} />
+      </TestWrapper>,
+    );
+    await waitForMount(screen);
+    const spacer = screen.container.querySelector("[data-pin-to-send-spacer]");
+    expect(spacer).toBeNull();
+  });
+
+  it("does not render the spacer when autoScroll='none'", async () => {
+    const screen = render(
+      <TestWrapper>
+        <CopilotChatView autoScroll="none" messages={sampleMessages} />
+      </TestWrapper>,
+    );
+    await waitForMount(screen);
+    const spacer = screen.container.querySelector("[data-pin-to-send-spacer]");
+    expect(spacer).toBeNull();
+  });
+
+  it("boolean true still maps to pin-to-bottom (back-compat)", async () => {
+    const screen = render(
+      <TestWrapper>
+        <CopilotChatView autoScroll={true} messages={sampleMessages} />
+      </TestWrapper>,
+    );
+    await waitForMount(screen);
+    const spacer = screen.container.querySelector("[data-pin-to-send-spacer]");
+    expect(spacer).toBeNull();
+  });
+
+  it("boolean false still maps to none (back-compat)", async () => {
+    const screen = render(
+      <TestWrapper>
+        <CopilotChatView autoScroll={false} messages={sampleMessages} />
+      </TestWrapper>,
+    );
+    await waitForMount(screen);
+    const spacer = screen.container.querySelector("[data-pin-to-send-spacer]");
+    expect(spacer).toBeNull();
+  });
+});

package/src/v2/components/chat/__tests__/copilot-chat-throttle.test.tsx

@@ -4,7 +4,6 @@ import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
 import { CopilotChat } from "../CopilotChat";
 import { useAgent } from "../../../hooks/use-agent";
 import { useCopilotKit } from "../../../providers/CopilotKitProvider";
-import { useCopilotChatConfiguration } from "../../../providers/CopilotChatConfigurationProvider";
 import { MockStepwiseAgent } from "../../../__tests__/utils/test-helpers";
 import { CopilotKitCoreRuntimeConnectionStatus } from "@copilotkit/core";
 

package/src/v2/components/chat/__tests__/normalize-auto-scroll.test.ts

@@ -0,0 +1,37 @@
+import { describe, it, expect } from "vitest";
+import {
+  normalizeAutoScroll,
+  type AutoScrollMode,
+} from "../normalize-auto-scroll";
+
+describe("normalizeAutoScroll", () => {
+  it("returns 'pin-to-bottom' for undefined (default)", () => {
+    expect(normalizeAutoScroll(undefined)).toBe("pin-to-bottom");
+  });
+
+  it("maps true -> 'pin-to-bottom'", () => {
+    expect(normalizeAutoScroll(true)).toBe("pin-to-bottom");
+  });
+
+  it("maps false -> 'none'", () => {
+    expect(normalizeAutoScroll(false)).toBe("none");
+  });
+
+  it("passes 'pin-to-bottom' through", () => {
+    expect(normalizeAutoScroll("pin-to-bottom")).toBe("pin-to-bottom");
+  });
+
+  it("passes 'pin-to-send' through", () => {
+    expect(normalizeAutoScroll("pin-to-send")).toBe("pin-to-send");
+  });
+
+  it("passes 'none' through", () => {
+    expect(normalizeAutoScroll("none")).toBe("none");
+  });
+
+  it("falls back to 'pin-to-bottom' for unknown strings", () => {
+    expect(normalizeAutoScroll("bogus" as AutoScrollMode)).toBe(
+      "pin-to-bottom",
+    );
+  });
+});

package/src/v2/components/chat/index.ts

@@ -86,3 +86,5 @@ export type {
   AttachmentsConfig,
   AttachmentModality,
 } from "@copilotkit/shared";
+
+export type { AutoScrollMode } from "./normalize-auto-scroll";

package/src/v2/components/chat/last-user-message-context.ts

@@ -0,0 +1,21 @@
+import React from "react";
+
+/**
+ * Context used by `CopilotChatView` to announce the latest user message
+ * to descendants (notably `usePinToSend`), so scroll logic can anchor
+ * the viewport to the most recent user turn in "pin-to-send" mode.
+ *
+ * `sendNonce` increments on each new send so repeated IDs (e.g., message
+ * edits that preserve the ID) still trigger dependent effects.
+ */
+export type LastUserMessageState = {
+  id: string | null;
+  sendNonce: number;
+};
+
+export const LastUserMessageContext = React.createContext<LastUserMessageState>(
+  {
+    id: null,
+    sendNonce: 0,
+  },
+);

package/src/v2/components/chat/normalize-auto-scroll.ts

@@ -0,0 +1,17 @@
+export type AutoScrollMode = "pin-to-bottom" | "pin-to-send" | "none";
+
+const VALID: readonly AutoScrollMode[] = [
+  "pin-to-bottom",
+  "pin-to-send",
+  "none",
+];
+
+export function normalizeAutoScroll(
+  value: AutoScrollMode | boolean | undefined,
+): AutoScrollMode {
+  if (value === undefined) return "pin-to-bottom";
+  if (value === true) return "pin-to-bottom";
+  if (value === false) return "none";
+  if ((VALID as readonly string[]).includes(value)) return value;
+  return "pin-to-bottom";
+}

package/src/v2/components/license-warning-banner.tsx

@@ -1,4 +1,9 @@
-import React from "react";
+import React, { useEffect } from "react";
+
+// Total reserved vertical space for the fixed license banner: banner height
+// (~36px) + bottom offset (8px) + visual gap above the chat input (~8px).
+const LICENSE_BANNER_OFFSET_PX = 52;
+const LICENSE_BANNER_OFFSET_VAR = "--copilotkit-license-banner-offset";
 
 interface LicenseWarningBannerProps {
   type:
@@ -72,6 +77,20 @@ function BannerShell({
   actionUrl: string;
   onDismiss?: () => void;
 }) {
+  // Publish the banner's reserved bottom offset so the chat input can lift
+  // itself above it via padding-bottom: var(--copilotkit-license-banner-offset).
+  useEffect(() => {
+    if (typeof document === "undefined") return;
+    const root = document.documentElement;
+    root.style.setProperty(
+      LICENSE_BANNER_OFFSET_VAR,
+      `${LICENSE_BANNER_OFFSET_PX}px`,
+    );
+    return () => {
+      root.style.removeProperty(LICENSE_BANNER_OFFSET_VAR);
+    };
+  }, []);
+
   return (
     <div style={{ ...BANNER_STYLES.base, ...getSeverityStyle(severity) }}>
       <span>{message}</span>

package/src/v2/hooks/__tests__/use-agent-stability.test.tsx

@@ -29,6 +29,10 @@ describe("useAgent stability during runtime connection", () => {
     runtimeTransport: string;
     headers: Record<string, string>;
     agents: Record<string, AbstractAgent>;
+    subscribeToAgentWithOptions: (
+      agent: AbstractAgent,
+      subscriber: any,
+    ) => { unsubscribe: () => void };
   };
 
   beforeEach(() => {
@@ -40,6 +44,8 @@ describe("useAgent stability during runtime connection", () => {
       runtimeTransport: "rest",
       headers: {},
       agents: {},
+      subscribeToAgentWithOptions: (agent, subscriber) =>
+        agent.subscribe(subscriber),
     };
 
     mockUseCopilotKit.mockReturnValue({

package/src/v2/hooks/__tests__/use-agent-thread-isolation.test.tsx

@@ -47,6 +47,10 @@ describe("useAgent thread isolation", () => {
     runtimeTransport: string;
     headers: Record<string, string>;
     agents: Record<string, AbstractAgent>;
+    subscribeToAgentWithOptions: (
+      agent: AbstractAgent,
+      subscriber: any,
+    ) => { unsubscribe: () => void };
   };
 
   let registeredAgent: CloneableAgent;
@@ -64,6 +68,8 @@ describe("useAgent thread isolation", () => {
       runtimeTransport: "rest",
       headers: {},
       agents: { "my-agent": registeredAgent },
+      subscribeToAgentWithOptions: (agent, subscriber) =>
+        agent.subscribe(subscriber),
     };
 
     mockUseCopilotKit.mockReturnValue({