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

package/package.json

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

package/src/components/copilot-provider/__tests__/v1-explicit-threadid-bridge.test.tsx

@@ -0,0 +1,107 @@
+import React from "react";
+import { render, screen, act } from "@testing-library/react";
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { CopilotKit } from "../copilotkit";
+import { useCopilotContext } from "../../../context/copilot-context";
+import { useCopilotChatConfiguration } from "../../../v2";
+import type { CopilotKitProps } from "../copilotkit-props";
+
+/**
+ * Probe that reads hasExplicitThreadId from the CopilotChatConfigurationProvider
+ * that the v1 <CopilotKit> bridge renders. This is the surface CopilotChat
+ * itself reads from to gate /connect and the welcome screen.
+ */
+function ExplicitProbe() {
+  const config = useCopilotChatConfiguration();
+  return (
+    <>
+      <div data-testid="explicit">{String(config?.hasExplicitThreadId)}</div>
+      <div data-testid="threadId">{config?.threadId ?? ""}</div>
+    </>
+  );
+}
+
+/**
+ * Exposes the v1 context's setThreadId so tests can drive the
+ * auto → explicit transition from outside React.
+ */
+function SetThreadIdButton({ nextId }: { nextId: string }) {
+  const { setThreadId } = useCopilotContext();
+  return (
+    <button data-testid="setThread" onClick={() => setThreadId(nextId)}>
+      set
+    </button>
+  );
+}
+
+// `agents__unsafe_dev_only` isn't declared on v1 CopilotKitProps but is
+// forwarded via spread to the v2 provider underneath. Cast once here rather
+// than every render.
+type V1Props = CopilotKitProps & {
+  agents__unsafe_dev_only?: Record<string, unknown>;
+};
+const CopilotKitAny = CopilotKit as unknown as React.FC<V1Props>;
+
+/**
+ * Regression coverage for fix/welcome-not-showing-at-all at the v1 bridge
+ * boundary. The v1 <CopilotKit> wrapper pipes a ThreadsProvider-minted UUID
+ * through as `threadId`, but that UUID is NOT a caller choice — the bridge
+ * must mark it as non-explicit so downstream consumers don't treat it as a
+ * real backend thread. These tests verify the signal makes it all the way
+ * through to CopilotChatConfigurationProvider.
+ */
+describe("v1 <CopilotKit> bridge → hasExplicitThreadId", () => {
+  // Silence the in-dev/test "missing runtimeUrl" warning — we pass publicApiKey.
+  let warnSpy: ReturnType<typeof vi.spyOn>;
+  beforeEach(() => {
+    warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+  });
+  afterEach(() => {
+    warnSpy.mockRestore();
+  });
+
+  it("is false on mount when no threadId prop is supplied", () => {
+    render(
+      <CopilotKitAny publicApiKey="test-key">
+        <ExplicitProbe />
+      </CopilotKitAny>,
+    );
+
+    // ThreadsProvider auto-minted the UUID — it's not a caller-picked thread.
+    expect(screen.getByTestId("explicit").textContent).toBe("false");
+    // threadId still resolves to a value (mock-thread-id from setupTests),
+    // but downstream consumers must NOT treat it as real.
+    expect(screen.getByTestId("threadId").textContent).toBe("mock-thread-id");
+  });
+
+  it("is true when threadId prop is supplied to <CopilotKit>", () => {
+    render(
+      <CopilotKitAny publicApiKey="test-key" threadId="caller-thread">
+        <ExplicitProbe />
+      </CopilotKitAny>,
+    );
+
+    expect(screen.getByTestId("explicit").textContent).toBe("true");
+    expect(screen.getByTestId("threadId").textContent).toBe("caller-thread");
+  });
+
+  it("flips from false to true after setThreadId() is called on the v1 context", () => {
+    render(
+      <CopilotKitAny publicApiKey="test-key">
+        <ExplicitProbe />
+        <SetThreadIdButton nextId="user-picked-thread" />
+      </CopilotKitAny>,
+    );
+
+    expect(screen.getByTestId("explicit").textContent).toBe("false");
+
+    act(() => {
+      screen.getByTestId("setThread").click();
+    });
+
+    expect(screen.getByTestId("threadId").textContent).toBe(
+      "user-picked-thread",
+    );
+    expect(screen.getByTestId("explicit").textContent).toBe("true");
+  });
+});

package/src/components/copilot-provider/copilotkit.tsx

@@ -478,7 +478,11 @@ export function CopilotKitInternal(cpkProps: CopilotKitProps) {
     }
   }, [props.agent]);
 
-  const { threadId, setThreadId: setInternalThreadId } = useThreads();
+  const {
+    threadId,
+    setThreadId: setInternalThreadId,
+    isThreadIdExplicit,
+  } = useThreads();
 
   const setThreadId = useCallback(
     (value: SetStateAction<string>) => {
@@ -757,6 +761,7 @@ export function CopilotKitInternal(cpkProps: CopilotKitProps) {
       // isModalDefaultOpen={isModalDefaultOpen}
       agentId={props.agent ?? "default"}
       threadId={threadId}
+      hasExplicitThreadId={isThreadIdExplicit}
     >
       <CopilotContext.Provider value={copilotContextValue}>
         <CopilotListeners />

package/src/context/__tests__/threads-context.test.tsx

@@ -1,10 +1,26 @@
 import React from "react";
-import { render, screen } from "@testing-library/react";
+import { render, screen, act } from "@testing-library/react";
+import { describe, it, expect } from "vitest";
 import { ThreadsProvider, useThreads } from "../threads-context";
 
 function ThreadIdViewer() {
-  const { threadId } = useThreads();
-  return <div data-testid="threadId">{threadId}</div>;
+  const { threadId, isThreadIdExplicit } = useThreads();
+  return (
+    <>
+      <div data-testid="threadId">{threadId}</div>
+      <div data-testid="isExplicit">{String(isThreadIdExplicit)}</div>
+    </>
+  );
+}
+
+// Exposes setThreadId to the test so it can trigger the auto→explicit flip.
+function ThreadIdController({ nextId }: { nextId: string }) {
+  const { setThreadId } = useThreads();
+  return (
+    <button data-testid="setThread" onClick={() => setThreadId(nextId)}>
+      set
+    </button>
+  );
 }
 
 describe("ThreadsProvider", () => {
@@ -25,4 +41,101 @@ describe("ThreadsProvider", () => {
 
     expect(screen.getByTestId("threadId").textContent).toBe("customer-thread");
   });
+
+  describe("isThreadIdExplicit", () => {
+    it("is false on first mount when no threadId prop is supplied", () => {
+      // Auto-minted UUID — the backend has never seen it, so downstream
+      // consumers (e.g. /connect) must NOT treat this as a real thread.
+      render(
+        <ThreadsProvider>
+          <ThreadIdViewer />
+        </ThreadsProvider>,
+      );
+
+      expect(screen.getByTestId("threadId").textContent).toBe("mock-thread-id");
+      expect(screen.getByTestId("isExplicit").textContent).toBe("false");
+    });
+
+    it("is true when threadId prop is supplied on mount", () => {
+      render(
+        <ThreadsProvider threadId="customer-thread">
+          <ThreadIdViewer />
+        </ThreadsProvider>,
+      );
+
+      expect(screen.getByTestId("threadId").textContent).toBe(
+        "customer-thread",
+      );
+      expect(screen.getByTestId("isExplicit").textContent).toBe("true");
+    });
+
+    it("flips from false to true after setThreadId() is called", () => {
+      render(
+        <ThreadsProvider>
+          <ThreadIdViewer />
+          <ThreadIdController nextId="user-picked-thread" />
+        </ThreadsProvider>,
+      );
+
+      expect(screen.getByTestId("isExplicit").textContent).toBe("false");
+
+      act(() => {
+        screen.getByTestId("setThread").click();
+      });
+
+      expect(screen.getByTestId("threadId").textContent).toBe(
+        "user-picked-thread",
+      );
+      expect(screen.getByTestId("isExplicit").textContent).toBe("true");
+    });
+
+    it("reverts to false when an explicit prop is removed and setThreadId was never called", () => {
+      // Current contract: explicitness via the `threadId` prop is prop-derived,
+      // so removing the prop returns the provider to its auto-minted state.
+      // Pinning this guards against an accidental "sticky explicit" regression.
+      const { rerender } = render(
+        <ThreadsProvider threadId="customer-thread">
+          <ThreadIdViewer />
+        </ThreadsProvider>,
+      );
+
+      expect(screen.getByTestId("isExplicit").textContent).toBe("true");
+
+      rerender(
+        <ThreadsProvider>
+          <ThreadIdViewer />
+        </ThreadsProvider>,
+      );
+
+      expect(screen.getByTestId("threadId").textContent).toBe("mock-thread-id");
+      expect(screen.getByTestId("isExplicit").textContent).toBe("false");
+    });
+
+    it("stays true after prop is removed if setThreadId was called while prop was present", () => {
+      // Once the caller has touched setThreadId, explicitness is sticky —
+      // the internal "user picked a thread" flag outlives any prop churn.
+      const { rerender } = render(
+        <ThreadsProvider threadId="customer-thread">
+          <ThreadIdViewer />
+          <ThreadIdController nextId="user-picked-thread" />
+        </ThreadsProvider>,
+      );
+
+      act(() => {
+        screen.getByTestId("setThread").click();
+      });
+
+      rerender(
+        <ThreadsProvider>
+          <ThreadIdViewer />
+          <ThreadIdController nextId="user-picked-thread" />
+        </ThreadsProvider>,
+      );
+
+      expect(screen.getByTestId("threadId").textContent).toBe(
+        "user-picked-thread",
+      );
+      expect(screen.getByTestId("isExplicit").textContent).toBe("true");
+    });
+  });
 });

package/src/context/threads-context.tsx

@@ -1,5 +1,6 @@
 import React, {
   createContext,
+  useCallback,
   useContext,
   useState,
   ReactNode,
@@ -10,6 +11,12 @@ import { randomUUID } from "@copilotkit/shared";
 export interface ThreadsContextValue {
   threadId: string;
   setThreadId: (value: SetStateAction<string>) => void;
+  // True when the current threadId was chosen by the caller — either via
+  // the `threadId` prop on <CopilotKit> / <ThreadsProvider>, or via a later
+  // setThreadId() call. False when the provider minted a UUID on first
+  // mount so downstream consumers don't have to treat that placeholder as
+  // a real backend thread.
+  isThreadIdExplicit: boolean;
 }
 
 const ThreadsContext = createContext<ThreadsContextValue | undefined>(
@@ -25,15 +32,25 @@ export function ThreadsProvider({
   children,
   threadId: explicitThreadId,
 }: ThreadsProviderProps) {
-  const [internalThreadId, setThreadId] = useState<string>(() => randomUUID());
+  const [internalThreadId, setInternalThreadId] = useState<string>(() =>
+    randomUUID(),
+  );
+  const [internalIsExplicit, setInternalIsExplicit] = useState<boolean>(false);
 
   const threadId = explicitThreadId ?? internalThreadId;
+  const isThreadIdExplicit = explicitThreadId != null || internalIsExplicit;
+
+  const setThreadId = useCallback((value: SetStateAction<string>) => {
+    setInternalThreadId(value);
+    setInternalIsExplicit(true);
+  }, []);
 
   return (
     <ThreadsContext.Provider
       value={{
         threadId,
         setThreadId,
+        isThreadIdExplicit,
       }}
     >
       {children}

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

@@ -33,6 +33,10 @@ import {
   transcribeAudio,
   TranscriptionError,
 } from "../../lib/transcription-client";
+import {
+  LastUserMessageContext,
+  type LastUserMessageState,
+} from "./last-user-message-context";
 
 export type CopilotChatProps = Omit<
   CopilotChatViewProps,
@@ -97,10 +101,20 @@ export function CopilotChat({
   // Apply priority: props > existing config > defaults
   const resolvedAgentId =
     agentId ?? existingConfig?.agentId ?? DEFAULT_AGENT_ID;
+  const providedThreadId = threadId ?? existingConfig?.threadId;
   const resolvedThreadId = useMemo(
-    () => threadId ?? existingConfig?.threadId ?? randomUUID(),
-    [threadId, existingConfig?.threadId],
+    () => providedThreadId ?? randomUUID(),
+    [providedThreadId],
   );
+  // "Explicit" means a caller actually picked this thread — via the
+  // `threadId` prop on CopilotChat or a wrapping provider that marked its
+  // threadId as caller-chosen. An auto-minted UUID leaking down through a
+  // CopilotChatConfigurationProvider (e.g. from the v1 CopilotKit →
+  // ThreadsProvider chain) does NOT count; treating it as explicit is
+  // what made /connect fire against 404s and the welcome screen stay
+  // hidden for fresh empty chats.
+  const hasExplicitThreadId =
+    !!threadId || !!existingConfig?.hasExplicitThreadId;
 
   const { agent } = useAgent({
     agentId: resolvedAgentId,
@@ -191,7 +205,25 @@ export function CopilotChat({
     ...restProps
   } = props;
 
+  // Tracks the last threadId for which connectAgent has completed (success or
+  // failure). When the user supplies a threadId, we're in "resume existing
+  // thread" mode — the welcome screen should be suppressed until the connect
+  // resolves, otherwise switching threads flashes the welcome screen while the
+  // new thread's messages are still en route.
+  const [lastConnectedThreadId, setLastConnectedThreadId] = useState<
+    string | null
+  >(null);
+  const isConnecting =
+    hasExplicitThreadId && lastConnectedThreadId !== resolvedThreadId;
+
   useEffect(() => {
+    // When the caller hasn't picked a specific thread, resolvedThreadId is a
+    // UUID minted locally (either in this CopilotChat or in a wrapping
+    // ThreadsProvider). The backend has never seen it, so /connect would
+    // always 404 — skip the call. A real thread is only created once the
+    // user runs the agent for the first time.
+    if (!hasExplicitThreadId) return;
+
     let detached = false;
 
     // Create a fresh AbortController so we can cancel the HTTP request on cleanup.
@@ -212,6 +244,25 @@ export function CopilotChat({
         // connectAgent already emits via the subscriber system, but catch
         // here to prevent unhandled rejections from unexpected errors.
         console.error("CopilotChat: connectAgent failed", error);
+      } finally {
+        // Whether the connect succeeded or failed, we're no longer in the
+        // transitional "connecting" state for this thread — unblock the
+        // welcome-screen-suppression so the view can settle.
+        //
+        // Defer one animation frame so any trailing React commits from the
+        // bootstrap replay (final assistant message content) paint before
+        // isConnecting flips off. Without this, suggestions + copy button
+        // can briefly appear against an incompletely-laid-out message tree
+        // and visibly snap once the last text chunk lands.
+        if (!detached) {
+          const raf =
+            typeof requestAnimationFrame === "function"
+              ? requestAnimationFrame
+              : (cb: () => void) => setTimeout(cb, 16);
+          raf(() => {
+            if (!detached) setLastConnectedThreadId(resolvedThreadId);
+          });
+        }
       }
     };
     connect(agent);
@@ -229,7 +280,7 @@ export function CopilotChat({
     };
     // copilotkit is intentionally excluded — it is a stable ref that never changes.
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [resolvedThreadId, agent, resolvedAgentId]);
+  }, [resolvedThreadId, agent, resolvedAgentId, hasExplicitThreadId]);
 
   const onSubmitInput = useCallback(
     async (value: string) => {
@@ -497,6 +548,37 @@ export function CopilotChat({
     [messagesMemoKey],
   );
 
+  // Compute the ID of the last user message for scroll-pinning logic.
+  const lastUserMessageId = useMemo(() => {
+    for (let i = messages.length - 1; i >= 0; i--) {
+      if (messages[i].role === "user") return messages[i].id;
+    }
+    return null;
+  }, [messages]);
+
+  // Track a nonce that increments each time a new user message ID appears.
+  // Using useState ensures the context value propagates correctly on the
+  // render that follows the state update (approach b from the design doc).
+  const [sendNonce, setSendNonce] = useState(0);
+  // Seed with the current value so restoring a thread with existing messages
+  // does not count as a new send. Only later-render id transitions bump.
+  const prevLastUserMessageIdRef = useRef<string | null>(lastUserMessageId);
+
+  useEffect(() => {
+    if (
+      lastUserMessageId &&
+      lastUserMessageId !== prevLastUserMessageIdRef.current
+    ) {
+      setSendNonce((n) => n + 1);
+      prevLastUserMessageIdRef.current = lastUserMessageId;
+    }
+  }, [lastUserMessageId]);
+
+  const lastUserMessageState = useMemo<LastUserMessageState>(
+    () => ({ id: lastUserMessageId, sendNonce }),
+    [lastUserMessageId, sendNonce],
+  );
+
   const finalProps: CopilotChatViewProps = {
     ...mergedProps,
     messages,
@@ -521,6 +603,8 @@ export function CopilotChat({
     onDragOver: handleDragOver,
     onDragLeave: handleDragLeave,
     onDrop: handleDrop,
+    isConnecting,
+    hasExplicitThreadId,
   };
 
   // Always create a provider with merged values
@@ -531,6 +615,7 @@ export function CopilotChat({
     <CopilotChatConfigurationProvider
       agentId={resolvedAgentId}
       threadId={resolvedThreadId}
+      hasExplicitThreadId={hasExplicitThreadId}
       labels={labels}
       isModalDefaultOpen={isModalDefaultOpen}
     >
@@ -564,7 +649,9 @@ export function CopilotChat({
             {transcriptionError}
           </div>
         )}
-        {RenderedChatView}
+        <LastUserMessageContext.Provider value={lastUserMessageState}>
+          {RenderedChatView}
+        </LastUserMessageContext.Provider>
       </div>
     </CopilotChatConfigurationProvider>
   );

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

@@ -87,6 +87,19 @@ type CopilotChatInputRestProps = {
   containerRef?: React.Ref<HTMLDivElement>;
   /** Whether to show the disclaimer. Default: true for absolute positioning, false for static */
   showDisclaimer?: boolean;
+  /**
+   * Set to `true` when the input sits at the bottom of its container as a
+   * flex-last-child (visible position is driven by layout, not CSS
+   * positioning). Triggers reservation of bottom space for the fixed
+   * CopilotKit license banner via the
+   * `--copilotkit-license-banner-offset` CSS var so the two don't overlap.
+   *
+   * Not needed when `positioning === "absolute"`; that mode already pins the
+   * input to the bottom and picks up the same reservation automatically.
+   * Leave unset (default `false`) for inputs rendered mid-layout such as the
+   * welcome screen, where the banner offset would push the input off-center.
+   */
+  bottomAnchored?: boolean;
 } & Omit<React.HTMLAttributes<HTMLDivElement>, "onChange">;
 
 type CopilotChatInputBaseProps = WithSlots<
@@ -130,6 +143,7 @@ export function CopilotChatInput({
   keyboardHeight = 0,
   containerRef,
   showDisclaimer,
+  bottomAnchored = false,
   textArea,
   sendButton,
   startTranscribeButton,
@@ -1097,6 +1111,14 @@ export function CopilotChatInput({
         transform:
           keyboardHeight > 0 ? `translateY(-${keyboardHeight}px)` : undefined,
         transition: "transform 0.2s ease-out",
+        // Reserve room when the fixed license banner is visible so it doesn't
+        // overlap the input. Applied only for bottom-anchored inputs (either
+        // `positioning === "absolute"`, or an explicitly-flagged flex-last-child
+        // input in run state). The welcome-screen input sits mid-layout and
+        // must stay still when the banner is present.
+        ...(positioning === "absolute" || bottomAnchored
+          ? { paddingBottom: "var(--copilotkit-license-banner-offset, 0px)" }
+          : {}),
       }}
       {...props}
     >