@copilotkit/react-core 1.56.0 → 1.56.2-canary.pin-to-send

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/components/ui/button.tsx

@@ -99,25 +99,26 @@ const buttonVariants = cva(
   },
 );
 
-function Button({
-  className,
-  variant,
-  size,
-  asChild = false,
-  ...props
-}: React.ComponentProps<"button"> &
-  VariantProps<typeof buttonVariants> & {
-    asChild?: boolean;
-  }) {
+const Button = React.forwardRef<
+  HTMLButtonElement,
+  React.ComponentProps<"button"> &
+    VariantProps<typeof buttonVariants> & {
+      asChild?: boolean;
+    }
+>(function Button(
+  { className, variant, size, asChild = false, ...props },
+  ref,
+) {
   const Comp = asChild ? Slot : "button";
 
   return (
     <Comp
+      ref={ref}
       data-slot="button"
       className={cn(buttonVariants({ variant, size, className }))}
       {...props}
     />
   );
-}
+});
 
 export { Button, buttonVariants };

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();
+    },
+  );
 });

package/src/v2/hooks/__tests__/use-pin-to-send.test.tsx

@@ -0,0 +1,219 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { render, act } from "@testing-library/react";
+import React, { useRef } from "react";
+import { usePinToSend } from "../use-pin-to-send";
+import { LastUserMessageContext } from "../../components/chat/last-user-message-context";
+
+// Small harness that wires the hook up against an in-memory DOM.
+// Height mocks are applied via Object.defineProperty because jsdom doesn't run layout.
+function setHeight(el: HTMLElement, height: number) {
+  Object.defineProperty(el, "clientHeight", {
+    configurable: true,
+    value: height,
+  });
+  Object.defineProperty(el, "offsetHeight", {
+    configurable: true,
+    value: height,
+  });
+  el.getBoundingClientRect = () =>
+    ({
+      top: 0,
+      left: 0,
+      right: 0,
+      bottom: height,
+      width: 100,
+      height,
+      x: 0,
+      y: 0,
+      toJSON: () => ({}),
+    }) as DOMRect;
+}
+
+// Inner component so the hook is mounted inside the Provider and can read context.
+function HarnessInner({ topOffset }: { topOffset: number }) {
+  const scrollRef = useRef<HTMLDivElement>(null);
+  const contentRef = useRef<HTMLDivElement>(null);
+  const spacerRef = useRef<HTMLDivElement>(null);
+
+  usePinToSend({ scrollRef, contentRef, spacerRef, topOffset });
+
+  return (
+    <div ref={scrollRef} data-testid="scroll">
+      <div ref={contentRef} data-testid="content">
+        <div data-message-id="m1" data-role="user">
+          user msg 1
+        </div>
+        <div data-message-id="m2" data-role="assistant">
+          asst msg 1
+        </div>
+        <div data-message-id="m3" data-role="user">
+          user msg 2
+        </div>
+      </div>
+      <div ref={spacerRef} data-testid="spacer" style={{ height: 0 }} />
+    </div>
+  );
+}
+
+function Harness({
+  lastUserMessage,
+  topOffset = 16,
+}: {
+  lastUserMessage: { id: string | null; sendNonce: number };
+  topOffset?: number;
+}) {
+  return (
+    <LastUserMessageContext.Provider value={lastUserMessage}>
+      <HarnessInner topOffset={topOffset} />
+    </LastUserMessageContext.Provider>
+  );
+}
+
+beforeEach(() => {
+  HTMLElement.prototype.scrollTo = vi.fn();
+  // jsdom does not run rAF callbacks — stub it to fire synchronously so scroll assertions work.
+  vi.stubGlobal("requestAnimationFrame", (cb: FrameRequestCallback) => {
+    cb(0);
+    return 0;
+  });
+  vi.stubGlobal("cancelAnimationFrame", vi.fn());
+});
+
+describe("usePinToSend", () => {
+  it("sets spacer height to viewportHeight - userMessageHeight - topOffset on new send", async () => {
+    const { rerender, getByTestId } = render(
+      <Harness lastUserMessage={{ id: null, sendNonce: 0 }} />,
+    );
+
+    const scroll = getByTestId("scroll");
+    const spacer = getByTestId("spacer");
+    setHeight(scroll, 800);
+
+    const userMsg = scroll.querySelector(
+      '[data-message-id="m3"]',
+    ) as HTMLElement;
+    setHeight(userMsg, 40);
+
+    act(() => {
+      rerender(<Harness lastUserMessage={{ id: "m3", sendNonce: 1 }} />);
+    });
+
+    // viewport=800, userMsg=40, topOffset=16
+    // spacer = max(0, 800 - 40 - 16) = 744
+    expect(spacer.style.height).toBe("744px");
+  });
+
+  it("calls scrollTo with targetEl.offsetTop - topOffset on new send", async () => {
+    const { rerender, getByTestId } = render(
+      <Harness lastUserMessage={{ id: null, sendNonce: 0 }} />,
+    );
+
+    const scroll = getByTestId("scroll");
+    setHeight(scroll, 800);
+    const scrollTo = scroll.scrollTo as unknown as ReturnType<typeof vi.fn>;
+
+    const userMsg = scroll.querySelector(
+      '[data-message-id="m3"]',
+    ) as HTMLElement;
+    setHeight(userMsg, 40);
+    // computeOffsetTop uses getBoundingClientRect; mock top=400 on userMsg and top=0 on scroll
+    // so that elRect.top - stopRect.top + scrollEl.scrollTop = 400 - 0 + 0 = 400.
+    userMsg.getBoundingClientRect = () =>
+      ({
+        top: 400,
+        left: 0,
+        right: 100,
+        bottom: 440,
+        width: 100,
+        height: 40,
+        x: 0,
+        y: 400,
+        toJSON: () => ({}),
+      }) as DOMRect;
+
+    act(() => {
+      rerender(<Harness lastUserMessage={{ id: "m3", sendNonce: 1 }} />);
+    });
+
+    // Allow rAF to fire
+    await act(async () => {
+      await new Promise((r) => setTimeout(r, 0));
+    });
+
+    expect(scrollTo).toHaveBeenCalledWith({
+      top: 400 - 16,
+      behavior: "smooth",
+    });
+  });
+
+  it("shrinks spacer as content height grows (does not grow it)", async () => {
+    let observed: (() => void) | null = null;
+    const ROStub = vi.fn().mockImplementation((cb: () => void) => {
+      observed = cb;
+      return { observe: vi.fn(), unobserve: vi.fn(), disconnect: vi.fn() };
+    });
+    const prevRO = global.ResizeObserver;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    global.ResizeObserver = ROStub as any;
+
+    try {
+      const { rerender, getByTestId } = render(
+        <Harness lastUserMessage={{ id: null, sendNonce: 0 }} />,
+      );
+      const scroll = getByTestId("scroll");
+      const content = getByTestId("content");
+      const spacer = getByTestId("spacer");
+      setHeight(scroll, 800);
+      const userMsg = scroll.querySelector(
+        '[data-message-id="m3"]',
+      ) as HTMLElement;
+      setHeight(userMsg, 40);
+      setHeight(content, 200);
+
+      act(() => {
+        rerender(<Harness lastUserMessage={{ id: "m3", sendNonce: 1 }} />);
+      });
+
+      // Initial: 800 - 40 - 16 = 744
+      expect(spacer.style.height).toBe("744px");
+
+      // Simulate content growing — spacer should shrink
+      setHeight(content, 600);
+      act(() => observed?.());
+      expect(parseInt(spacer.style.height, 10)).toBeLessThan(744);
+
+      // Simulate content shrinking — spacer should NOT grow back
+      setHeight(content, 100);
+      const shrunkHeight = spacer.style.height;
+      act(() => observed?.());
+      expect(spacer.style.height).toBe(shrunkHeight);
+    } finally {
+      global.ResizeObserver = prevRO;
+    }
+  });
+
+  it("cancels the scheduled rAF on unmount (cleanup)", async () => {
+    // Use a real rAF handle so we can assert the cancel was issued with it.
+    const cancelSpy = vi.spyOn(global, "cancelAnimationFrame");
+    try {
+      const { rerender, unmount, getByTestId } = render(
+        <Harness lastUserMessage={{ id: null, sendNonce: 0 }} />,
+      );
+      const scroll = getByTestId("scroll");
+      setHeight(scroll, 800);
+      const userMsg = scroll.querySelector(
+        '[data-message-id="m3"]',
+      ) as HTMLElement;
+      setHeight(userMsg, 40);
+
+      act(() => {
+        rerender(<Harness lastUserMessage={{ id: "m3", sendNonce: 1 }} />);
+      });
+
+      unmount();
+      expect(cancelSpy).toHaveBeenCalled();
+    } finally {
+      cancelSpy.mockRestore();
+    }
+  });
+});

package/src/v2/hooks/__tests__/use-render-custom-messages.test.tsx

@@ -0,0 +1,55 @@
+import React from "react";
+import { describe, it, expect, vi } from "vitest";
+import { renderHook } from "@testing-library/react";
+import { useRenderCustomMessages } from "../use-render-custom-messages";
+import { CopilotKitProvider } from "../../providers/CopilotKitProvider";
+import { CopilotChatConfigurationProvider } from "../../providers/CopilotChatConfigurationProvider";
+
+/**
+ * Regression test for #3497: useRenderCustomMessages throws "Agent not found"
+ * when the agent is undefined during the connecting state.
+ *
+ * During initial connection, the agent may not yet be registered in the
+ * CopilotKit registry. The hook should return null gracefully instead of
+ * throwing an error.
+ */
+describe("useRenderCustomMessages (#3497)", () => {
+  it("returns null instead of throwing when agent is not found", () => {
+    // Render the hook inside a CopilotKitProvider with an agentId that
+    // does NOT exist in the registry (simulating connecting state).
+    // The hook should not throw.
+    const wrapper = ({ children }: { children: React.ReactNode }) => (
+      <CopilotKitProvider
+        renderCustomMessages={[
+          {
+            agentId: "nonexistent-agent",
+            render: () => <div>Custom</div>,
+          },
+        ]}
+      >
+        <CopilotChatConfigurationProvider
+          agentId="nonexistent-agent"
+          threadId="test-thread"
+        >
+          {children}
+        </CopilotChatConfigurationProvider>
+      </CopilotKitProvider>
+    );
+
+    const { result } = renderHook(() => useRenderCustomMessages(), { wrapper });
+
+    // The hook should return a function (the render function), not throw
+    // When called, it should handle missing agent gracefully
+    if (typeof result.current === "function") {
+      const output = result.current({
+        message: { id: "msg-1", role: "assistant", content: "test" },
+        position: "after",
+      });
+      // Should return null since agent isn't found
+      expect(output).toBeNull();
+    } else {
+      // If result.current is null, that's also acceptable
+      expect(result.current).toBeNull();
+    }
+  });
+});