@copilotkit/react-core 1.57.1 → 1.57.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@copilotkit/react-core",
-  "version": "1.57.1",
+  "version": "1.57.3",
   "private": false,
   "keywords": [
     "ai",
@@ -81,11 +81,11 @@
     "untruncate-json": "^0.0.1",
     "use-stick-to-bottom": "^1.1.1",
     "zod-to-json-schema": "^3.24.5",
-    "@copilotkit/a2ui-renderer": "1.57.1",
-    "@copilotkit/core": "1.57.1",
-    "@copilotkit/web-inspector": "1.57.1",
-    "@copilotkit/runtime-client-gql": "1.57.1",
-    "@copilotkit/shared": "1.57.1"
+    "@copilotkit/a2ui-renderer": "1.57.3",
+    "@copilotkit/core": "1.57.3",
+    "@copilotkit/runtime-client-gql": "1.57.3",
+    "@copilotkit/shared": "1.57.3",
+    "@copilotkit/web-inspector": "1.57.3"
   },
   "devDependencies": {
     "@tailwindcss/cli": "^4.1.11",

package/src/v2/components/chat/CopilotSidebar.tsx

@@ -14,6 +14,7 @@ export type CopilotSidebarProps = Omit<CopilotChatProps, "chatView"> & {
   toggleButton?: CopilotSidebarViewProps["toggleButton"];
   defaultOpen?: boolean;
   width?: number | string;
+  position?: CopilotSidebarViewProps["position"];
 };
 
 export function CopilotSidebar({
@@ -21,6 +22,7 @@ export function CopilotSidebar({
   toggleButton,
   defaultOpen,
   width,
+  position,
   ...chatProps
 }: CopilotSidebarProps) {
   const { checkFeature } = useLicenseContext();
@@ -41,6 +43,7 @@ export function CopilotSidebar({
         toggleButton: viewToggleButton,
         width: viewWidth,
         defaultOpen: viewDefaultOpen,
+        position: viewPosition,
         ...restProps
       } = viewProps as CopilotSidebarViewProps;
 
@@ -51,12 +54,13 @@ export function CopilotSidebar({
           toggleButton={toggleButton ?? viewToggleButton}
           width={width ?? viewWidth}
           defaultOpen={defaultOpen ?? viewDefaultOpen}
+          position={position ?? viewPosition}
         />
       );
     };
 
     return Object.assign(Component, CopilotChatView);
-  }, [header, toggleButton, width, defaultOpen]);
+  }, [header, toggleButton, width, defaultOpen, position]);
 
   return (
     <>

package/src/v2/components/chat/CopilotSidebarView.tsx

@@ -21,6 +21,7 @@ export type CopilotSidebarViewProps = CopilotChatViewProps & {
   toggleButton?: SlotValue<typeof CopilotChatToggleButton>;
   width?: number | string;
   defaultOpen?: boolean;
+  position?: "left" | "right";
 };
 
 export function CopilotSidebarView({
@@ -28,6 +29,7 @@ export function CopilotSidebarView({
   toggleButton,
   width,
   defaultOpen = true,
+  position = "right",
   ...props
 }: CopilotSidebarViewProps) {
   return (
@@ -36,6 +38,7 @@ export function CopilotSidebarView({
         header={header}
         toggleButton={toggleButton}
         width={width}
+        position={position}
         {...props}
       />
     </CopilotChatConfigurationProvider>
@@ -46,6 +49,7 @@ function CopilotSidebarViewInternal({
   header,
   toggleButton,
   width,
+  position = "right",
   ...props
 }: Omit<CopilotSidebarViewProps, "defaultOpen">) {
   const configuration = useCopilotChatConfiguration();
@@ -118,29 +122,34 @@ function CopilotSidebarViewInternal({
       return;
     if (!window.matchMedia("(min-width: 768px)").matches) return;
 
+    const marginStyleProp =
+      position === "left" ? "marginInlineStart" : "marginInlineEnd";
+    const transitionCssProp =
+      position === "left" ? "margin-inline-start" : "margin-inline-end";
+
     if (isSidebarOpen) {
       if (hasMounted.current) {
-        document.body.style.transition = `margin-inline-end ${SIDEBAR_TRANSITION_MS}ms ease`;
+        document.body.style.transition = `${transitionCssProp} ${SIDEBAR_TRANSITION_MS}ms ease`;
       }
-      document.body.style.marginInlineEnd = widthToMargin(sidebarWidth);
+      document.body.style[marginStyleProp] = widthToMargin(sidebarWidth);
     } else if (hasMounted.current) {
-      document.body.style.transition = `margin-inline-end ${SIDEBAR_TRANSITION_MS}ms ease`;
-      document.body.style.marginInlineEnd = "";
+      document.body.style.transition = `${transitionCssProp} ${SIDEBAR_TRANSITION_MS}ms ease`;
+      document.body.style[marginStyleProp] = "";
     }
 
     hasMounted.current = true;
 
     return () => {
-      document.body.style.marginInlineEnd = "";
+      document.body.style[marginStyleProp] = "";
       document.body.style.transition = "";
     };
-  }, [isSidebarOpen, sidebarWidth]);
+  }, [isSidebarOpen, sidebarWidth, position]);
 
   const headerElement = renderSlot(header, CopilotModalHeader, {});
   const toggleButtonElement = renderSlot(
     toggleButton,
     CopilotChatToggleButton,
-    {},
+    position === "left" ? { className: "cpk:left-6 cpk:right-auto" } : {},
   );
 
   return (
@@ -151,18 +160,23 @@ function CopilotSidebarViewInternal({
         data-copilotkit
         data-testid="copilot-sidebar"
         data-copilot-sidebar
+        data-position={position}
         className={cn(
           "copilotKitSidebar copilotKitWindow",
-          "cpk:fixed cpk:right-0 cpk:top-0 cpk:z-[1200] cpk:flex",
+          "cpk:fixed cpk:top-0 cpk:z-[1200] cpk:flex",
+          position === "left" ? "cpk:left-0" : "cpk:right-0",
           // Height with dvh fallback and safe area support
           "cpk:h-[100vh] cpk:h-[100dvh] cpk:max-h-screen",
           // Responsive width: full on mobile, custom on desktop
           "cpk:w-full",
-          "cpk:border-l cpk:border-border cpk:bg-background cpk:text-foreground cpk:shadow-xl",
+          position === "left" ? "cpk:border-r" : "cpk:border-l",
+          "cpk:border-border cpk:bg-background cpk:text-foreground cpk:shadow-xl",
           "cpk:transition-transform cpk:duration-300 cpk:ease-out",
           isSidebarOpen
             ? "cpk:translate-x-0"
-            : "cpk:translate-x-full cpk:pointer-events-none",
+            : position === "left"
+              ? "cpk:-translate-x-full cpk:pointer-events-none"
+              : "cpk:translate-x-full cpk:pointer-events-none",
         )}
         style={
           {

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

@@ -115,6 +115,74 @@ describe("CopilotChat perf — re-render regression", () => {
     renderCounts.clear();
   });
 
+  // @tanstack/virtual-core 3.13.18 has a latent bug: `scrollToIndex` schedules
+  // a nested rAF that calls `this.targetWindow.requestAnimationFrame(verify)`
+  // with no null-check. The virtualizer's cleanup (run on React unmount) sets
+  // `targetWindow = null`, so if the outer rAF fires after unmount, the inner
+  // schedule throws `Cannot read properties of null (reading 'requestAnimationFrame')`.
+  //
+  // Vitest reports this as an unhandled error and exits non-zero even though
+  // every test passes. We wrap rAF (on BOTH globalThis and window — they're
+  // separate bindings in vitest+jsdom; tanstack uses `targetWindow.rAF` which
+  // resolves to `window.rAF`) so callbacks that hit the known tanstack bug
+  // are swallowed. After each test we drain pending callbacks and replace rAF
+  // with a no-op to keep stragglers from leaking into the next test.
+  const realRAF = globalThis.requestAnimationFrame;
+  const realWindowRAF =
+    typeof window !== "undefined" ? window.requestAnimationFrame : realRAF;
+
+  const isKnownTanstackTeardownError = (err: unknown): boolean => {
+    const message =
+      (err as { message?: string } | null | undefined)?.message ?? "";
+    return (
+      message.includes("Cannot read properties of null") &&
+      message.includes("requestAnimationFrame")
+    );
+  };
+
+  const wrapRAF = (real: typeof requestAnimationFrame) =>
+    ((cb: FrameRequestCallback) =>
+      real((time) => {
+        try {
+          cb(time);
+        } catch (err) {
+          if (isKnownTanstackTeardownError(err)) return;
+          throw err;
+        }
+      })) as typeof requestAnimationFrame;
+
+  const noopRAF = ((_cb: FrameRequestCallback) =>
+    0) as typeof requestAnimationFrame;
+
+  const installSafeRAF = () => {
+    globalThis.requestAnimationFrame = wrapRAF(realRAF);
+    if (typeof window !== "undefined") {
+      window.requestAnimationFrame = wrapRAF(realWindowRAF);
+    }
+  };
+
+  const installNoopRAF = () => {
+    globalThis.requestAnimationFrame = noopRAF;
+    if (typeof window !== "undefined") {
+      window.requestAnimationFrame = noopRAF;
+    }
+  };
+
+  afterEach(async () => {
+    // Best-effort drain of already-queued rAF callbacks.
+    await act(async () => {
+      await new Promise<void>((r) => realRAF(() => r()));
+      await new Promise<void>((r) => realRAF(() => r()));
+    });
+    // Neuter rAF so callbacks scheduled during RTL cleanup are harmless.
+    installNoopRAF();
+  });
+
+  beforeEach(() => {
+    // Install the error-swallowing wrap on rAF for the upcoming test.
+    installSafeRAF();
+  });
+
   it("completed messages do not re-render when a new message is added", async () => {
     const agent = new MockStepwiseAgent();
     renderWithSpy(agent);

package/src/v2/components/chat/__tests__/CopilotSidebarView.position.test.tsx

@@ -0,0 +1,159 @@
+import React from "react";
+import { render } from "@testing-library/react";
+import { describe, it, expect } from "vitest";
+import { CopilotSidebarView } from "../CopilotSidebarView";
+import { CopilotSidebar } from "../CopilotSidebar";
+import { CopilotKitProvider } from "../../../providers/CopilotKitProvider";
+import { CopilotChatConfigurationProvider } from "../../../providers/CopilotChatConfigurationProvider";
+import {
+  MockStepwiseAgent,
+  renderWithCopilotKit,
+} from "../../../__tests__/utils/test-helpers";
+
+const TestWrapper: React.FC<{ children: React.ReactNode }> = ({ children }) => (
+  <CopilotKitProvider>
+    <CopilotChatConfigurationProvider threadId="test-thread">
+      {children}
+    </CopilotChatConfigurationProvider>
+  </CopilotKitProvider>
+);
+
+const sampleMessages = [{ id: "1", role: "user" as const, content: "Hello" }];
+
+function getSidebarAside(container: HTMLElement) {
+  const sidebar = container.querySelector("[data-copilot-sidebar]");
+  if (!sidebar) throw new Error("sidebar aside not found");
+  return sidebar;
+}
+
+describe("CopilotSidebarView position prop", () => {
+  describe("CopilotSidebarView", () => {
+    it("defaults to right-anchored when position is omitted", () => {
+      const { container } = render(
+        <TestWrapper>
+          <CopilotSidebarView messages={sampleMessages} />
+        </TestWrapper>,
+      );
+
+      const aside = getSidebarAside(container);
+      expect(aside.classList.contains("cpk:right-0")).toBe(true);
+      expect(aside.classList.contains("cpk:border-l")).toBe(true);
+      expect(aside.classList.contains("cpk:left-0")).toBe(false);
+      expect(aside.classList.contains("cpk:border-r")).toBe(false);
+    });
+
+    it('renders right-anchored when position="right" explicitly', () => {
+      const { container } = render(
+        <TestWrapper>
+          <CopilotSidebarView messages={sampleMessages} position="right" />
+        </TestWrapper>,
+      );
+
+      const aside = getSidebarAside(container);
+      expect(aside.classList.contains("cpk:right-0")).toBe(true);
+      expect(aside.classList.contains("cpk:border-l")).toBe(true);
+      expect(aside.classList.contains("cpk:left-0")).toBe(false);
+      expect(aside.classList.contains("cpk:border-r")).toBe(false);
+    });
+
+    it('renders left-anchored when position="left"', () => {
+      const { container } = render(
+        <TestWrapper>
+          <CopilotSidebarView messages={sampleMessages} position="left" />
+        </TestWrapper>,
+      );
+
+      const aside = getSidebarAside(container);
+      expect(aside.classList.contains("cpk:left-0")).toBe(true);
+      expect(aside.classList.contains("cpk:border-r")).toBe(true);
+      expect(aside.classList.contains("cpk:right-0")).toBe(false);
+      expect(aside.classList.contains("cpk:border-l")).toBe(false);
+    });
+
+    it('translates off-screen to the right when closed and position="right"', () => {
+      const { container } = render(
+        <TestWrapper>
+          <CopilotSidebarView
+            messages={sampleMessages}
+            defaultOpen={false}
+            position="right"
+          />
+        </TestWrapper>,
+      );
+
+      const aside = getSidebarAside(container);
+      expect(aside.classList.contains("cpk:translate-x-full")).toBe(true);
+      expect(aside.classList.contains("cpk:-translate-x-full")).toBe(false);
+    });
+
+    it('translates off-screen to the left when closed and position="left"', () => {
+      const { container } = render(
+        <TestWrapper>
+          <CopilotSidebarView
+            messages={sampleMessages}
+            defaultOpen={false}
+            position="left"
+          />
+        </TestWrapper>,
+      );
+
+      const aside = getSidebarAside(container);
+      expect(aside.classList.contains("cpk:-translate-x-full")).toBe(true);
+      expect(aside.classList.contains("cpk:translate-x-full")).toBe(false);
+    });
+
+    it('anchors the toggle button to the left when position="left"', () => {
+      const { container } = render(
+        <TestWrapper>
+          <CopilotSidebarView messages={sampleMessages} position="left" />
+        </TestWrapper>,
+      );
+
+      const toggle = container.querySelector(
+        '[data-slot="chat-toggle-button"]',
+      );
+      if (!toggle) throw new Error("toggle button not found");
+      expect(toggle.classList.contains("cpk:left-6")).toBe(true);
+      expect(toggle.classList.contains("cpk:right-auto")).toBe(true);
+    });
+
+    it("keeps the toggle button right-anchored by default", () => {
+      const { container } = render(
+        <TestWrapper>
+          <CopilotSidebarView messages={sampleMessages} />
+        </TestWrapper>,
+      );
+
+      const toggle = container.querySelector(
+        '[data-slot="chat-toggle-button"]',
+      );
+      if (!toggle) throw new Error("toggle button not found");
+      expect(toggle.classList.contains("cpk:right-6")).toBe(true);
+      expect(toggle.classList.contains("cpk:left-6")).toBe(false);
+    });
+  });
+
+  describe("CopilotSidebar wrapper", () => {
+    it('forwards position="left" through to CopilotSidebarView', () => {
+      const { container } = renderWithCopilotKit({
+        agent: new MockStepwiseAgent(),
+        children: <CopilotSidebar position="left" />,
+      });
+
+      const aside = getSidebarAside(container);
+      expect(aside.classList.contains("cpk:left-0")).toBe(true);
+      expect(aside.classList.contains("cpk:border-r")).toBe(true);
+    });
+
+    it("defaults to right-anchored when position is omitted", () => {
+      const { container } = renderWithCopilotKit({
+        agent: new MockStepwiseAgent(),
+        children: <CopilotSidebar />,
+      });
+
+      const aside = getSidebarAside(container);
+      expect(aside.classList.contains("cpk:right-0")).toBe(true);
+      expect(aside.classList.contains("cpk:border-l")).toBe(true);
+    });
+  });
+});

package/src/v2/headless.ts

@@ -26,7 +26,13 @@ export { useAgent, type UseAgentUpdate } from "./hooks/use-agent";
 export { useFrontendTool } from "./hooks/use-frontend-tool";
 export { useComponent } from "./hooks/use-component";
 export { useHumanInTheLoop } from "./hooks/use-human-in-the-loop";
-export { useInterrupt, type UseInterruptConfig } from "./hooks/use-interrupt";
+export {
+  useInterrupt,
+  type UseInterruptConfig,
+  type InterruptEvent,
+  type InterruptHandlerProps,
+  type InterruptRenderProps,
+} from "./hooks/use-interrupt";
 export { useSuggestions } from "./hooks/use-suggestions";
 export { useConfigureSuggestions } from "./hooks/use-configure-suggestions";
 export {
@@ -40,3 +46,19 @@ export {
   type UseThreadsInput,
   type UseThreadsResult,
 } from "./hooks/use-threads";
+
+export {
+  useRenderTool,
+  type RenderToolProps,
+  type RenderToolInProgressProps,
+  type RenderToolExecutingProps,
+  type RenderToolCompleteProps,
+} from "./hooks/use-render-tool";
+export { defineToolCallRenderer } from "./types/defineToolCallRenderer";
+
+// Platform-agnostic types
+export type { ReactFrontendTool } from "./types/frontend-tool";
+export type { ReactHumanInTheLoop } from "./types/human-in-the-loop";
+
+// Platform-agnostic capability introspection
+export { useCapabilities } from "./hooks/use-capabilities";

package/src/v2/hooks/__tests__/use-component.test.tsx

@@ -45,7 +45,7 @@ describe("useComponent", () => {
     );
   });
 
-  it("appends custom description and forwards parameters, agentId, and deps", () => {
+  it("appends custom description and forwards parameters, agentId, deps, and followUp", () => {
     const weatherSchema = z.object({
       city: z.string(),
       unit: z.enum(["c", "f"]),
@@ -65,6 +65,7 @@ describe("useComponent", () => {
           parameters: weatherSchema,
           render: DemoComponent,
           agentId: "weather-agent",
+          followUp: false,
         },
         deps,
       );
@@ -79,6 +80,7 @@ describe("useComponent", () => {
         description: string;
         parameters: typeof weatherSchema;
         agentId?: string;
+        followUp?: boolean;
       },
       ReadonlyArray<unknown>,
     ];
@@ -91,6 +93,7 @@ describe("useComponent", () => {
     );
     expect(toolConfig.parameters).toBe(weatherSchema);
     expect(toolConfig.agentId).toBe("weather-agent");
+    expect(toolConfig.followUp).toBe(false);
     expect(forwardedDeps).toBe(deps);
   });
 

package/src/v2/hooks/use-component.tsx

@@ -65,6 +65,7 @@ export function useComponent<
     parameters?: TSchema;
     render: ComponentType<NoInfer<InferRenderProps<TSchema>>>;
     agentId?: string;
+    followUp?: boolean;
   },
   deps?: ReadonlyArray<unknown>,
 ): void {
@@ -83,6 +84,7 @@ export function useComponent<
         return <Component {...(args as InferRenderProps<TSchema>)} />;
       },
       agentId: config.agentId,
+      followUp: config.followUp,
     },
     deps,
   );

package/src/v2/hooks/use-default-render-tool.tsx

@@ -63,7 +63,7 @@ export function useDefaultRenderTool(
   );
 }
 
-function DefaultToolCallRenderer({
+export function DefaultToolCallRenderer({
   name,
   parameters,
   status,
@@ -86,6 +86,11 @@ function DefaultToolCallRenderer({
 
   return (
     <div
+      data-testid="copilot-tool-render"
+      data-tool-name={name}
+      data-status={statusString}
+      data-args={safeStringifyForAttr(parameters)}
+      data-result={safeStringifyForAttr(result)}
       style={{
         marginTop: "8px",
         paddingBottom: "8px",
@@ -150,6 +155,7 @@ function DefaultToolCallRenderer({
               }}
             />
             <span
+              data-testid="copilot-tool-render-name"
               style={{
                 fontSize: "13px",
                 fontWeight: 600,
@@ -164,6 +170,7 @@ function DefaultToolCallRenderer({
           </div>
 
           <span
+            data-testid="copilot-tool-render-status"
             style={{
               display: "inline-flex",
               alignItems: "center",
@@ -252,3 +259,13 @@ function DefaultToolCallRenderer({
     </div>
   );
 }
+
+function safeStringifyForAttr(value: unknown): string {
+  if (value === undefined || value === null) return "";
+  if (typeof value === "string") return value;
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+}

package/src/v2/hooks/use-render-tool-call.tsx

@@ -6,6 +6,7 @@ import { useCopilotChatConfiguration } from "../providers/CopilotChatConfigurati
 import { DEFAULT_AGENT_ID } from "@copilotkit/shared";
 import { partialJSONParse } from "@copilotkit/shared";
 import { ReactToolCallRenderer } from "../types/react-tool-call-renderer";
+import { DefaultToolCallRenderer } from "./use-default-render-tool";
 
 export interface UseRenderToolCallProps {
   toolCall: ToolCall;
@@ -153,11 +154,12 @@ export function useRenderToolCall() {
         exactMatches[0] ||
         renderToolCalls.find((rc) => rc.name === "*");
 
-      if (!renderConfig) {
-        return null;
-      }
-
-      const RenderComponent = renderConfig.render;
+      // Fall back to the framework's built-in default tool-call renderer
+      // when neither a per-tool nor a wildcard renderer has been
+      // registered. This makes "zero custom renderers" demos paint tool
+      // calls out-of-the-box instead of going invisible.
+      const RenderComponent = (renderConfig?.render ??
+        defaultToolCallRenderAdapter) as ReactToolCallRenderer<unknown>["render"];
       const isExecuting = executingToolCallIds.has(toolCall.id);
 
       // Use the memoized ToolCallRenderer component to prevent unnecessary re-renders
@@ -176,3 +178,31 @@ export function useRenderToolCall() {
 
   return renderToolCall;
 }
+
+// Adapter that bridges the ReactToolCallRenderer signature
+// (`{ name, args, status, result, toolCallId }`) to the
+// `DefaultToolCallRenderer` signature (`{ name, parameters, status,
+// result }`) so the latter can be used as a zero-config fallback when
+// no `*` renderer is registered.
+function defaultToolCallRenderAdapter(props: {
+  name: string;
+  args: unknown;
+  status: ToolCallStatus;
+  result: string | undefined;
+  toolCallId: string;
+}): React.ReactElement {
+  const status =
+    props.status === ToolCallStatus.Complete
+      ? "complete"
+      : props.status === ToolCallStatus.Executing
+        ? "executing"
+        : "inProgress";
+  return (
+    <DefaultToolCallRenderer
+      name={props.name}
+      parameters={props.args}
+      status={status}
+      result={props.result}
+    />
+  );
+}