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

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

@@ -33,10 +33,34 @@ import {
   CopilotChatDefaultLabels,
 } from "../../providers/CopilotChatConfigurationProvider";
 import { useKeyboardHeight } from "../../hooks/use-keyboard-height";
+import { normalizeAutoScroll } from "./normalize-auto-scroll";
+import type { AutoScrollMode } from "./normalize-auto-scroll";
+import { usePinToSend } from "../../hooks/use-pin-to-send";
 
 // Height of the feather gradient overlay (h-24 = 6rem = 96px)
 const FEATHER_HEIGHT = 96;
 
+// Pin-to-send uses a softer, shorter feather than pin-to-bottom so readable
+// content isn't obscured (h-12 = 3rem = 48px).
+const PIN_TO_SEND_FEATHER_HEIGHT = 48;
+
+const PinToSendSoftFeather: React.FC<React.HTMLAttributes<HTMLDivElement>> = ({
+  className,
+  style,
+  ...props
+}) => (
+  <div
+    className={cn(
+      "cpk:absolute cpk:bottom-0 cpk:left-0 cpk:right-4 cpk:h-12 cpk:pointer-events-none cpk:z-10 cpk:bg-gradient-to-t",
+      "cpk:from-white cpk:to-transparent",
+      "cpk:dark:from-[rgb(33,33,33)]",
+      className,
+    )}
+    style={style}
+    {...props}
+  />
+);
+
 // Forward declaration for WelcomeScreen component type
 export type WelcomeScreenProps = WithSlots<
   {
@@ -57,7 +81,7 @@ export type CopilotChatViewProps = WithSlots<
   },
   {
     messages?: Message[];
-    autoScroll?: boolean;
+    autoScroll?: AutoScrollMode | boolean;
     isRunning?: boolean;
     suggestions?: Suggestion[];
     suggestionLoadingIndexes?: ReadonlyArray<number>;
@@ -81,6 +105,21 @@ export type CopilotChatViewProps = WithSlots<
     onDragOver?: (e: React.DragEvent) => void;
     onDragLeave?: (e: React.DragEvent) => void;
     onDrop?: (e: React.DragEvent) => void;
+    /**
+     * When `true`, suppresses the welcome screen while a thread's initial
+     * connect is in flight. Prevents the "How can I help you today?" flash
+     * that would otherwise appear between mounting an empty cloned agent and
+     * the bootstrap messages arriving from /connect.
+     */
+    isConnecting?: boolean;
+    /**
+     * When `true`, the caller has explicitly picked a thread (via `threadId`
+     * prop or `CopilotChatConfigurationProvider`). Suppresses the welcome
+     * screen unconditionally — a caller-managed thread targets a specific
+     * conversation and should render its messages (or an empty panel during
+     * connect) rather than a generic "start a new chat" greeting.
+     */
+    hasExplicitThreadId?: boolean;
     /**
      * @deprecated Use the `input` slot's `disclaimer` prop instead:
      * ```tsx
@@ -139,6 +178,8 @@ export function CopilotChatView({
   onDragOver,
   onDragLeave,
   onDrop,
+  isConnecting = false,
+  hasExplicitThreadId = false,
   // Deprecated — forwarded to input slot
   disclaimer,
   children,
@@ -219,10 +260,22 @@ export function CopilotChatView({
     keyboardHeight: isKeyboardOpen ? keyboardHeight : 0,
     containerRef: inputContainerRef,
     showDisclaimer: true,
+    // This input is the last flex child of the chat column, so it sits at
+    // the bottom where the license banner would overlap. The welcome-screen
+    // input (below) intentionally omits this flag.
+    bottomAnchored: true,
     ...(disclaimer !== undefined ? { disclaimer } : {}),
   } as CopilotChatInputProps);
 
-  const hasSuggestions = Array.isArray(suggestions) && suggestions.length > 0;
+  // Hide suggestions while a thread is connecting or a run is in flight.
+  // Otherwise, mid-replay (bootstrap stream from /connect) or mid-run, the
+  // suggestions would render against a still-assembling message tree and
+  // visibly jump as each final text chunk reflows the layout.
+  const hasSuggestions =
+    !isConnecting &&
+    !isRunning &&
+    Array.isArray(suggestions) &&
+    suggestions.length > 0;
   const BoundSuggestionView = hasSuggestions
     ? renderSlot(suggestionView, CopilotChatSuggestionView, {
         suggestions,
@@ -258,7 +311,13 @@ export function CopilotChatView({
   const isEmpty = messages.length === 0;
   // Type assertion needed because TypeScript doesn't fully propagate `| boolean` through WithSlots
   const welcomeScreenDisabled = (welcomeScreen as unknown) === false;
-  const shouldShowWelcomeScreen = isEmpty && !welcomeScreenDisabled;
+  // Suppress the welcome screen (1) while the initial connect is in flight
+  // and (2) whenever the caller has picked a specific thread. The caller-
+  // managed case targets a conversation directly, so the generic welcome
+  // greeting is never the right thing to show — even for a thread that
+  // happens to have no messages yet.
+  const shouldShowWelcomeScreen =
+    isEmpty && !welcomeScreenDisabled && !isConnecting && !hasExplicitThreadId;
 
   if (shouldShowWelcomeScreen) {
     // Create a separate input for welcome screen with static positioning and disclaimer visible
@@ -442,9 +501,114 @@ export namespace CopilotChatView {
     );
   };
 
+  // Internal component for pin-to-send scroll behavior — not exported on CopilotChatView.
+  const PinToSendScrollContainer: React.FC<
+    React.HTMLAttributes<HTMLDivElement> & {
+      scrollRef: React.MutableRefObject<HTMLElement | null>;
+      contentRef: React.MutableRefObject<HTMLElement | null>;
+      scrollToBottom: () => void;
+      scrollToBottomButton?: SlotValue<
+        React.FC<React.ButtonHTMLAttributes<HTMLButtonElement>>
+      >;
+      feather?: SlotValue<React.FC<React.HTMLAttributes<HTMLDivElement>>>;
+      inputContainerHeight: number;
+      isResizing: boolean;
+      nonAutoScrollEl: HTMLElement | null;
+      nonAutoScrollRefCallback: (el: HTMLElement | null) => void;
+      showScrollButton: boolean;
+    }
+  > = ({
+    children,
+    scrollRef,
+    contentRef,
+    scrollToBottom,
+    scrollToBottomButton,
+    feather,
+    inputContainerHeight,
+    isResizing,
+    nonAutoScrollEl,
+    nonAutoScrollRefCallback,
+    showScrollButton,
+    className,
+    ...props
+  }) => {
+    const spacerRef = useRef<HTMLDivElement>(null);
+
+    usePinToSend({
+      scrollRef,
+      contentRef,
+      spacerRef,
+      topOffset: 16,
+    });
+
+    // Pin-to-send uses a SOFTER feather than pin-to-bottom:
+    //   - default: h-24 + from-white via-white to-transparent (fully opaque
+    //     bottom half, aggressive). Good for streaming-to-bottom where
+    //     the edge is always churning.
+    //   - pin-to-send: h-12 + from-white to-transparent (gradual fade,
+    //     no opaque midline). Gives a visual soft edge above the input
+    //     without obscuring otherwise-readable content.
+    // Consumers can still override with the `feather` slot.
+    const BoundFeather = renderSlot(feather, PinToSendSoftFeather, {});
+
+    // Feather and scroll-to-bottom button live OUTSIDE the scroll container.
+    // `position: absolute` children of an `overflow: auto` element are
+    // positioned relative to the scroll *content*, which means they scroll
+    // away with it. Placing them as siblings of the scroll container
+    // (inside a `relative` wrapper) keeps them pinned to the viewport bottom.
+    return (
+      <ScrollElementContext.Provider value={nonAutoScrollEl}>
+        <div
+          className={cn(
+            "cpk:h-full cpk:max-h-full cpk:flex cpk:flex-col cpk:min-h-0 cpk:relative",
+            className,
+          )}
+        >
+          <div
+            ref={nonAutoScrollRefCallback}
+            className="cpk:flex-1 cpk:min-h-0 cpk:overflow-y-auto cpk:overflow-x-hidden"
+            {...props}
+          >
+            <div
+              ref={contentRef}
+              className="cpk:px-4 cpk:sm:px-0 cpk:[div[data-sidebar-chat]_&]:px-8 cpk:[div[data-popup-chat]_&]:px-6"
+            >
+              {children}
+            </div>
+            <div
+              ref={spacerRef}
+              data-pin-to-send-spacer
+              aria-hidden="true"
+              style={{ height: 0, flex: "0 0 auto" }}
+            />
+          </div>
+          {/* Soft feather — pinned to wrapper bottom */}
+          {BoundFeather}
+          {/* Scroll to bottom button */}
+          {showScrollButton && !isResizing && (
+            <div
+              className="cpk:absolute cpk:inset-x-0 cpk:flex cpk:justify-center cpk:z-30 cpk:pointer-events-none"
+              style={{
+                bottom: `${inputContainerHeight + PIN_TO_SEND_FEATHER_HEIGHT + 16}px`,
+              }}
+            >
+              {renderSlot(
+                scrollToBottomButton,
+                CopilotChatView.ScrollToBottomButton,
+                {
+                  onClick: () => scrollToBottom(),
+                },
+              )}
+            </div>
+          )}
+        </div>
+      </ScrollElementContext.Provider>
+    );
+  };
+
   export const ScrollView: React.FC<
     React.HTMLAttributes<HTMLDivElement> & {
-      autoScroll?: boolean;
+      autoScroll?: AutoScrollMode | boolean;
       scrollToBottomButton?: SlotValue<
         React.FC<React.ButtonHTMLAttributes<HTMLButtonElement>>
       >;
@@ -454,7 +618,7 @@ export namespace CopilotChatView {
     }
   > = ({
     children,
-    autoScroll = true,
+    autoScroll = "pin-to-bottom",
     scrollToBottomButton,
     feather,
     inputContainerHeight = 0,
@@ -462,8 +626,18 @@ export namespace CopilotChatView {
     className,
     ...props
   }) => {
+    const mode = normalizeAutoScroll(autoScroll);
     const [hasMounted, setHasMounted] = useState(false);
-    const { scrollRef, contentRef, scrollToBottom } = useStickToBottom();
+    // Plain refs for the "none" and "pin-to-send" paths. Do NOT use
+    // useStickToBottom() here — its internal effects would attach scroll-following
+    // behavior to these refs and fight pin-to-send. The "pin-to-bottom" path
+    // gets its refs via <StickToBottom> below, scoped to that branch only.
+    const scrollRef = useRef<HTMLElement | null>(null);
+    const contentRef = useRef<HTMLElement | null>(null);
+    const scrollToBottom = useCallback(() => {
+      const el = scrollRef.current;
+      if (el) el.scrollTo({ top: el.scrollHeight, behavior: "smooth" });
+    }, []);
     const [showScrollButton, setShowScrollButton] = useState(false);
     // Tracks the scroll container element for the non-autoScroll path so the
     // context value is reactive (element state, not a ref).
@@ -478,7 +652,7 @@ export namespace CopilotChatView {
         scrollRef.current = el;
         setNonAutoScrollEl(el);
       },
-      // scrollRef is a stable object from useStickToBottom; safe to omit.
+      // scrollRef is a stable ref object; safe to omit.
       // eslint-disable-next-line react-hooks/exhaustive-deps
       [],
     );
@@ -489,7 +663,7 @@ export namespace CopilotChatView {
 
     // Monitor scroll position for non-autoscroll mode
     useEffect(() => {
-      if (autoScroll) return; // Skip for autoscroll mode
+      if (mode === "pin-to-bottom") return; // Skip for autoscroll mode
 
       const scrollElement = scrollRef.current;
       if (!scrollElement) return;
@@ -514,7 +688,7 @@ export namespace CopilotChatView {
         scrollElement.removeEventListener("scroll", checkScroll);
         resizeObserver.disconnect();
       };
-    }, [scrollRef, autoScroll]);
+    }, [scrollRef, mode]);
 
     if (!hasMounted) {
       return (
@@ -526,8 +700,7 @@ export namespace CopilotChatView {
       );
     }
 
-    // When autoScroll is false, we don't use StickToBottom
-    if (!autoScroll) {
+    if (mode === "none") {
       const BoundFeather = renderSlot(feather, CopilotChatView.Feather, {});
 
       return (
@@ -574,6 +747,28 @@ export namespace CopilotChatView {
       );
     }
 
+    if (mode === "pin-to-send") {
+      return (
+        <PinToSendScrollContainer
+          scrollRef={scrollRef}
+          contentRef={contentRef}
+          scrollToBottom={scrollToBottom}
+          scrollToBottomButton={scrollToBottomButton}
+          feather={feather}
+          inputContainerHeight={inputContainerHeight}
+          isResizing={isResizing}
+          nonAutoScrollEl={nonAutoScrollEl}
+          nonAutoScrollRefCallback={nonAutoScrollRefCallback}
+          showScrollButton={showScrollButton}
+          className={className}
+          {...props}
+        >
+          {children}
+        </PinToSendScrollContainer>
+      );
+    }
+
+    // mode === "pin-to-bottom" (default)
     return (
       <StickToBottom
         className={cn(

package/src/v2/components/chat/__tests__/CopilotChat.absentThreadConnect.test.tsx

@@ -0,0 +1,66 @@
+import React from "react";
+import { describe, it, expect, vi } from "vitest";
+import { render } from "@testing-library/react";
+import { EMPTY, Observable } from "rxjs";
+import { type BaseEvent, type RunAgentInput } from "@ag-ui/client";
+import { MockStepwiseAgent } from "../../../__tests__/utils/test-helpers";
+import { CopilotKitProvider } from "../../../providers/CopilotKitProvider";
+import { CopilotChatConfigurationProvider } from "../../../providers/CopilotChatConfigurationProvider";
+import { CopilotChat } from "../CopilotChat";
+
+describe("CopilotChat avoids /connect for locally-generated threadIds (ENT-314)", () => {
+  function buildAgentWithConnectSpy(): {
+    agent: MockStepwiseAgent;
+    connectSpy: ReturnType<typeof vi.fn>;
+  } {
+    const connectSpy = vi.fn();
+    class SpyAgent extends MockStepwiseAgent {
+      connect(input: RunAgentInput): Observable<BaseEvent> {
+        connectSpy(input);
+        return EMPTY;
+      }
+    }
+    return { agent: new SpyAgent(), connectSpy };
+  }
+
+  it("does not call connect() when no threadId is supplied", async () => {
+    const { agent, connectSpy } = buildAgentWithConnectSpy();
+
+    render(
+      <CopilotKitProvider agents__unsafe_dev_only={{ default: agent }}>
+        <CopilotChat welcomeScreen={false} />
+      </CopilotKitProvider>,
+    );
+
+    await new Promise((resolve) => setTimeout(resolve, 50));
+    expect(connectSpy).not.toHaveBeenCalled();
+  });
+
+  it("calls connect() when a threadId is supplied via props", async () => {
+    const { agent, connectSpy } = buildAgentWithConnectSpy();
+
+    render(
+      <CopilotKitProvider agents__unsafe_dev_only={{ default: agent }}>
+        <CopilotChat welcomeScreen={false} threadId="user-thread-abc" />
+      </CopilotKitProvider>,
+    );
+
+    await new Promise((resolve) => setTimeout(resolve, 50));
+    expect(connectSpy).toHaveBeenCalled();
+  });
+
+  it("calls connect() when a threadId is supplied via configuration provider", async () => {
+    const { agent, connectSpy } = buildAgentWithConnectSpy();
+
+    render(
+      <CopilotKitProvider agents__unsafe_dev_only={{ default: agent }}>
+        <CopilotChatConfigurationProvider threadId="config-thread-xyz">
+          <CopilotChat welcomeScreen={false} />
+        </CopilotChatConfigurationProvider>
+      </CopilotKitProvider>,
+    );
+
+    await new Promise((resolve) => setTimeout(resolve, 50));
+    expect(connectSpy).toHaveBeenCalled();
+  });
+});

package/src/v2/components/chat/__tests__/CopilotChat.welcomeGate.test.tsx

@@ -0,0 +1,186 @@
+import React from "react";
+import { render, screen, waitFor } from "@testing-library/react";
+import { describe, it, expect, beforeEach } from "vitest";
+import { CopilotKitProvider } from "../../../providers/CopilotKitProvider";
+import { CopilotChatConfigurationProvider } from "../../../providers/CopilotChatConfigurationProvider";
+import { CopilotChat } from "../CopilotChat";
+import { MockStepwiseAgent } from "../../../__tests__/utils/test-helpers";
+import { DEFAULT_AGENT_ID } from "@copilotkit/shared";
+
+/**
+ * Mock agent that records every connectAgent() invocation and resolves
+ * immediately with an empty run result. Tracking lives on the class so
+ * per-thread clones (from useAgent's WeakMap) share the counter.
+ */
+class TrackingAgent extends MockStepwiseAgent {
+  static connectCalls: Array<{
+    threadId: string | undefined;
+    agentId: string | undefined;
+  }> = [];
+
+  static reset() {
+    TrackingAgent.connectCalls = [];
+  }
+
+  async connectAgent(
+    _params: unknown,
+    _subscriber: unknown,
+  ): Promise<{ result: unknown; newMessages: [] }> {
+    TrackingAgent.connectCalls.push({
+      threadId: this.threadId,
+      agentId: this.agentId,
+    });
+    return { result: undefined, newMessages: [] };
+  }
+}
+
+function renderWithKit(ui: React.ReactNode, agent: TrackingAgent) {
+  return render(
+    <CopilotKitProvider agents__unsafe_dev_only={{ [DEFAULT_AGENT_ID]: agent }}>
+      <div style={{ height: 400 }}>{ui}</div>
+    </CopilotKitProvider>,
+  );
+}
+
+/**
+ * Regression coverage for fix/welcome-not-showing-at-all.
+ *
+ * The underlying bug: the v1 <CopilotKit> wrapper pipes a ThreadsProvider-
+ * minted UUID through to CopilotChatConfigurationProvider as `threadId`.
+ * CopilotChat previously treated any non-empty providedThreadId as "caller
+ * supplied a real backend thread" and (a) fired /connect (→ 404 for an
+ * auto-minted UUID) and (b) suppressed the welcome screen forever. The
+ * fix threads an `hasExplicitThreadId` signal through the provider chain;
+ * these tests pin the contract that /connect and welcome-screen gating
+ * now follow that signal rather than `!!threadId`.
+ */
+describe("CopilotChat welcome / connect integration", () => {
+  beforeEach(() => {
+    TrackingAgent.reset();
+  });
+
+  describe("v1 bridge scenario (config provider marks threadId as non-explicit)", () => {
+    it("does not call connectAgent and shows the welcome screen", async () => {
+      const agent = new TrackingAgent();
+      agent.agentId = DEFAULT_AGENT_ID;
+
+      renderWithKit(
+        <CopilotChatConfigurationProvider
+          threadId="auto-minted-uuid"
+          hasExplicitThreadId={false}
+        >
+          <CopilotChat />
+        </CopilotChatConfigurationProvider>,
+        agent,
+      );
+
+      // Give the connect-effect a chance to misfire.
+      await new Promise((r) => setTimeout(r, 50));
+
+      expect(TrackingAgent.connectCalls).toHaveLength(0);
+      expect(screen.getByTestId("copilot-welcome-screen")).toBeDefined();
+    });
+  });
+
+  describe("plain CopilotChat (no threadId anywhere)", () => {
+    it("does not call connectAgent and shows the welcome screen", async () => {
+      const agent = new TrackingAgent();
+      agent.agentId = DEFAULT_AGENT_ID;
+
+      renderWithKit(<CopilotChat />, agent);
+
+      await new Promise((r) => setTimeout(r, 50));
+
+      expect(TrackingAgent.connectCalls).toHaveLength(0);
+      expect(screen.getByTestId("copilot-welcome-screen")).toBeDefined();
+    });
+  });
+
+  describe("explicit threadId via CopilotChat prop", () => {
+    it("calls connectAgent with that threadId and suppresses the welcome screen", async () => {
+      const agent = new TrackingAgent();
+      agent.agentId = DEFAULT_AGENT_ID;
+
+      renderWithKit(<CopilotChat threadId="real-thread" />, agent);
+
+      await waitFor(() => {
+        expect(TrackingAgent.connectCalls.length).toBeGreaterThan(0);
+      });
+
+      // The per-thread clone carries threadId; agentId is the default.
+      expect(
+        TrackingAgent.connectCalls.some((c) => c.threadId === "real-thread"),
+      ).toBe(true);
+
+      // Welcome screen is suppressed even after connect resolves, because the
+      // thread was caller-picked (hasExplicitThreadId=true).
+      expect(screen.queryByTestId("copilot-welcome-screen")).toBeNull();
+    });
+  });
+
+  describe("explicit threadId via wrapping CopilotChatConfigurationProvider", () => {
+    it("inherits explicitness from the provider and connects", async () => {
+      const agent = new TrackingAgent();
+      agent.agentId = DEFAULT_AGENT_ID;
+
+      renderWithKit(
+        <CopilotChatConfigurationProvider threadId="from-config">
+          <CopilotChat />
+        </CopilotChatConfigurationProvider>,
+        agent,
+      );
+
+      await waitFor(() => {
+        expect(TrackingAgent.connectCalls.length).toBeGreaterThan(0);
+      });
+
+      expect(
+        TrackingAgent.connectCalls.some((c) => c.threadId === "from-config"),
+      ).toBe(true);
+      expect(screen.queryByTestId("copilot-welcome-screen")).toBeNull();
+    });
+  });
+
+  describe("thread switch between two explicit threads", () => {
+    it("keeps the welcome screen hidden across the switch", async () => {
+      const agent = new TrackingAgent();
+      agent.agentId = DEFAULT_AGENT_ID;
+
+      const { rerender } = renderWithKit(
+        <CopilotChat threadId="thread-a" />,
+        agent,
+      );
+
+      await waitFor(() => {
+        expect(
+          TrackingAgent.connectCalls.some((c) => c.threadId === "thread-a"),
+        ).toBe(true);
+      });
+      // After thread-a's connect resolves, welcome must still be hidden
+      // because the thread is caller-picked.
+      expect(screen.queryByTestId("copilot-welcome-screen")).toBeNull();
+
+      rerender(
+        <CopilotKitProvider
+          agents__unsafe_dev_only={{ [DEFAULT_AGENT_ID]: agent }}
+        >
+          <div style={{ height: 400 }}>
+            <CopilotChat threadId="thread-b" />
+          </div>
+        </CopilotKitProvider>,
+      );
+
+      // During the switch (lastConnected="thread-a" !== "thread-b") isConnecting
+      // is true — welcome must not flash.
+      expect(screen.queryByTestId("copilot-welcome-screen")).toBeNull();
+
+      await waitFor(() => {
+        expect(
+          TrackingAgent.connectCalls.some((c) => c.threadId === "thread-b"),
+        ).toBe(true);
+      });
+      // And after thread-b's connect resolves.
+      expect(screen.queryByTestId("copilot-welcome-screen")).toBeNull();
+    });
+  });
+});