@copilotkit/react-core 1.56.2 → 1.56.4

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({

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

@@ -4,7 +4,10 @@ import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
 import { useAgent, UseAgentUpdate } from "../use-agent";
 import { useCopilotKit } from "../../providers/CopilotKitProvider";
 import { MockStepwiseAgent } from "../../__tests__/utils/test-helpers";
-import { CopilotKitCoreRuntimeConnectionStatus } from "@copilotkit/core";
+import {
+  CopilotKitCore,
+  CopilotKitCoreRuntimeConnectionStatus,
+} from "@copilotkit/core";
 import type { Message } from "@ag-ui/core";
 import type { RunAgentInput } from "@ag-ui/client";
 
@@ -126,11 +129,19 @@ function createTestComponent(
   };
 }
 
-/** Factory for the mock return value of useCopilotKit */
+/** Factory for the mock return value of useCopilotKit.
+ *  Uses a real CopilotKitCore instance so subscribeToAgentWithOptions (with its throttle
+ *  logic) is exercised end-to-end rather than mocked. */
 function createMockContext(
   agent: MockStepwiseAgent,
   overrides: { defaultThrottleMs?: number } = {},
 ) {
+  const core = new CopilotKitCore({
+    runtimeUrl: "http://localhost:3000/api/copilot",
+  });
+  if (overrides.defaultThrottleMs !== undefined) {
+    core.setDefaultThrottleMs(overrides.defaultThrottleMs);
+  }
   return {
     copilotkit: {
       getAgent: () => agent,
@@ -139,7 +150,8 @@ function createMockContext(
       runtimeTransport: "rest",
       headers: {},
       agents: { [String(agent.agentId)]: agent },
-      defaultThrottleMs: overrides.defaultThrottleMs,
+      defaultThrottleMs: core.defaultThrottleMs,
+      subscribeToAgentWithOptions: core.subscribeToAgentWithOptions.bind(core),
     },
     executingToolCallIds: new Set(),
   };
@@ -313,7 +325,7 @@ describe("useAgent throttleMs", () => {
     expect(screen.getByTestId("count").textContent).toBe("3");
   });
 
-  it("with throttleMs, onStateChanged still fires immediately", async () => {
+  it("with throttleMs, onStateChanged is also throttled (shared window)", async () => {
     const TestComponent = createTestComponent({
       updates: [
         UseAgentUpdate.OnMessagesChanged,
@@ -324,19 +336,29 @@ describe("useAgent throttleMs", () => {
 
     render(<TestComponent />);
 
-    // Fire onMessagesChanged to start the throttle window
+    // Fire onMessagesChanged to start the throttle window (leading edge)
     act(() => {
       mockAgent.messages = [userMsg("1", "a")];
       notifyMessagesChanged(mockAgent);
     });
+    expect(screen.getByTestId("count").textContent).toBe("1");
 
-    // Fire onStateChanged 10ms later — fires via microtask batch (not synchronously)
-    await act(async () => {
+    // Fire onStateChanged 10ms later — should be deferred (within throttle window)
+    act(() => {
       vi.advanceTimersByTime(10);
       mockAgent.state = { count: 42 };
       notifyStateChanged(mockAgent);
     });
 
+    // State update is pending, not yet rendered
+    expect(screen.getByTestId("state").textContent).toBe("{}");
+
+    // Trailing edge fires after the window — await so microtask from
+    // batchedForceUpdate flushes and triggers the React re-render.
+    await act(async () => {
+      vi.advanceTimersByTime(100);
+    });
+
     expect(screen.getByTestId("state").textContent).toBe('{"count":42}');
   });
 
@@ -372,7 +394,7 @@ describe("useAgent throttleMs", () => {
     expect(renderCount.current).toBe(countBeforeUnmount);
   });
 
-  it("with throttleMs and updates excluding OnMessagesChanged, throttle is a no-op", async () => {
+  it("with throttleMs and only OnStateChanged subscribed, first state fires on leading edge", async () => {
     const TestComponent = createTestComponent({
       updates: [UseAgentUpdate.OnStateChanged],
       throttleMs: 100,
@@ -380,7 +402,8 @@ describe("useAgent throttleMs", () => {
 
     render(<TestComponent />);
 
-    // Only onStateChanged is subscribed — fires via microtask batch
+    // First onStateChanged fires immediately (leading edge) — await so
+    // microtask from batchedForceUpdate flushes.
     await act(async () => {
       mockAgent.state = { value: "test" };
       notifyStateChanged(mockAgent);
@@ -388,15 +411,13 @@ describe("useAgent throttleMs", () => {
 
     expect(screen.getByTestId("state").textContent).toBe('{"value":"test"}');
 
-    // No onMessagesChanged subscription should exist
+    // No onMessagesChanged subscription should exist — messages notification
+    // does nothing because the handler was never registered.
     act(() => {
       mockAgent.messages = [userMsg("1", "a")];
       notifyMessagesChanged(mockAgent);
     });
 
-    // onMessagesChanged was sent but no handler is subscribed, so no
-    // re-render is triggered. We verify by checking state still shows the
-    // last rendered value.
     expect(screen.getByTestId("state").textContent).toBe('{"value":"test"}');
   });
 
@@ -418,6 +439,7 @@ describe("useAgent throttleMs", () => {
         expect.stringContaining(
           "throttleMs must be a non-negative finite number",
         ),
+        expect.any(Error),
       );
 
       // Should behave as unthrottled — every notification fires immediately
@@ -864,23 +886,23 @@ describe("useAgent defaultThrottleMs from provider", () => {
   ])(
     "with invalid provider defaultThrottleMs ($label), falls back to unthrottled and warns",
     ({ value }) => {
+      const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+
       mockUseCopilotKit.mockReturnValue(
         createMockContext(mockAgent, { defaultThrottleMs: value }),
       );
 
-      const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
       const TestComponent = createTestComponent({ throttleMs: undefined });
 
       render(<TestComponent />);
 
-      expect(errorSpy).toHaveBeenCalledWith(
-        expect.stringContaining("provider-level defaultThrottleMs"),
-      );
+      // The core setter rejects invalid values and logs an error
       expect(errorSpy).toHaveBeenCalledWith(
         expect.stringContaining("must be a non-negative finite number"),
+        expect.any(Error),
       );
 
-      // Should behave as unthrottled
+      // Should behave as unthrottled (setter rejected the value)
       act(() => {
         mockAgent.messages = [userMsg("1", "a")];
         notifyMessagesChanged(mockAgent);
@@ -963,41 +985,45 @@ describe("useAgent defaultThrottleMs from provider", () => {
   });
 });
 
-describe("CopilotKitCore.setDefaultThrottleMs validation", () => {
+describe("CopilotKitCore.setDefaultThrottleMs", () => {
+  it("stores valid values", () => {
+    const core = new CopilotKitCore({});
+    core.setDefaultThrottleMs(100);
+    expect(core.defaultThrottleMs).toBe(100);
+  });
+
+  it("stores 0", () => {
+    const core = new CopilotKitCore({});
+    core.setDefaultThrottleMs(100);
+    core.setDefaultThrottleMs(0);
+    expect(core.defaultThrottleMs).toBe(0);
+  });
+
+  it("stores undefined", () => {
+    const core = new CopilotKitCore({});
+    core.setDefaultThrottleMs(100);
+    core.setDefaultThrottleMs(undefined);
+    expect(core.defaultThrottleMs).toBeUndefined();
+  });
+
   it.each([
     { label: "NaN", value: NaN },
     { label: "Infinity", value: Infinity },
     { label: "-1", value: -1 },
     { label: "-Infinity", value: -Infinity },
-  ])("rejects invalid value ($label) and stores undefined", ({ value }) => {
-    // Simulate the core setter behavior: invalid values are rejected
-    // and the stored value becomes undefined (no default configured).
-    // This is tested via the mock context to verify that the hook
-    // correctly handles a sanitized undefined from the core.
-    const mockAgent = new MockStepwiseAgent();
-    mockAgent.agentId = "test-agent";
-
-    // After the core setter rejects an invalid value, hooks see undefined
-    mockUseCopilotKit.mockReturnValue(
-      createMockContext(mockAgent, { defaultThrottleMs: undefined }),
-    );
-
-    vi.useFakeTimers();
-    const TestComponent = createTestComponent({ throttleMs: undefined });
-    render(<TestComponent />);
-
-    // Should behave as unthrottled (no provider default in effect)
-    act(() => {
-      mockAgent.messages = [userMsg("1", "a")];
-      notifyMessagesChanged(mockAgent);
-    });
-    expect(screen.getByTestId("count").textContent).toBe("1");
-
-    act(() => {
-      mockAgent.messages = [userMsg("1", "a"), assistantMsg("2", "b")];
-      notifyMessagesChanged(mockAgent);
-    });
-    expect(screen.getByTestId("count").textContent).toBe("2");
-    vi.useRealTimers();
-  });
+  ])(
+    "rejects invalid value ($label) and preserves previous value",
+    ({ value }) => {
+      const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+      const core = new CopilotKitCore({});
+      core.setDefaultThrottleMs(200);
+      core.setDefaultThrottleMs(value);
+      expect(core.defaultThrottleMs).toBe(200);
+      expect(errorSpy).toHaveBeenCalledWith(
+        expect.stringContaining("must be a non-negative finite number"),
+        expect.any(Error),
+      );
+      errorSpy.mockRestore();
+    },
+  );
 });