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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@copilotkit/react-core",
-  "version": "1.56.1",
+  "version": "1.56.2-canary.pin-to-send",
   "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/core": "1.56.2-canary.pin-to-send",
+    "@copilotkit/shared": "1.56.2-canary.pin-to-send",
+    "@copilotkit/runtime-client-gql": "1.56.2-canary.pin-to-send",
+    "@copilotkit/web-inspector": "1.56.2-canary.pin-to-send",
+    "@copilotkit/a2ui-renderer": "1.56.2-canary.pin-to-send"
   },
   "devDependencies": {
     "@tailwindcss/cli": "^4.1.11",

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,9 +101,10 @@ 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],
   );
 
   const { agent } = useAgent({
@@ -191,7 +196,24 @@ 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 =
+    !!providedThreadId && lastConnectedThreadId !== resolvedThreadId;
+
   useEffect(() => {
+    // When no threadId was supplied by the caller, resolvedThreadId is a UUID
+    // minted in this browser tab. 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 (!providedThreadId) return;
+
     let detached = false;
 
     // Create a fresh AbortController so we can cancel the HTTP request on cleanup.
@@ -212,6 +234,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 +270,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, providedThreadId]);
 
   const onSubmitInput = useCallback(
     async (value: string) => {
@@ -497,6 +538,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 +593,8 @@ export function CopilotChat({
     onDragOver: handleDragOver,
     onDragLeave: handleDragLeave,
     onDrop: handleDrop,
+    isConnecting,
+    hasExplicitThreadId: !!providedThreadId,
   };
 
   // Always create a provider with merged values
@@ -564,7 +638,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}
     >

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