@assistant-ui/react 0.14.5 → 0.14.7

package/src/primitives/messagePart/useMessagePartReasoning.ts

@@ -6,6 +6,21 @@ import type {
 } from "@assistant-ui/core";
 import { useAuiState } from "@assistant-ui/store";
 
+/**
+ * @deprecated Use {@link useAuiState} to select and narrow `s.part`.
+ * Return `null` for optional rendering, or throw inside the selector to
+ * preserve the old hook's strict behavior.
+ *
+ * @example
+ * ```tsx
+ * const reasoning = useAuiState((s) => {
+ *   if (s.part.type !== "reasoning") return null;
+ *   return s.part;
+ * });
+ * ```
+ *
+ * See the {@link https://assistant-ui.com/docs/migrations/v0-12 migration guide}.
+ */
 export const useMessagePartReasoning = () => {
   const text = useAuiState((s) => {
     if (s.part.type !== "reasoning")

package/src/primitives/messagePart/useMessagePartSource.ts

@@ -3,6 +3,21 @@
 import type { SourceMessagePart, MessagePartState } from "@assistant-ui/core";
 import { useAuiState } from "@assistant-ui/store";
 
+/**
+ * @deprecated Use {@link useAuiState} to select and narrow `s.part`.
+ * Return `null` for optional rendering, or throw inside the selector to
+ * preserve the old hook's strict behavior.
+ *
+ * @example
+ * ```tsx
+ * const source = useAuiState((s) => {
+ *   if (s.part.type !== "source") return null;
+ *   return s.part;
+ * });
+ * ```
+ *
+ * See the {@link https://assistant-ui.com/docs/migrations/v0-12 migration guide}.
+ */
 export const useMessagePartSource = () => {
   const source = useAuiState((s) => {
     if (s.part.type !== "source")

package/src/primitives/messagePart/useMessagePartText.ts

@@ -7,6 +7,21 @@ import type {
 } from "@assistant-ui/core";
 import { useAuiState } from "@assistant-ui/store";
 
+/**
+ * @deprecated Use {@link useAuiState} to select and narrow `s.part`.
+ * Return `null` for optional rendering, or throw inside the selector to
+ * preserve the old hook's strict behavior.
+ *
+ * @example
+ * ```tsx
+ * const text = useAuiState((s) => {
+ *   if (s.part.type !== "text" && s.part.type !== "reasoning") return null;
+ *   return s.part;
+ * });
+ * ```
+ *
+ * See the {@link https://assistant-ui.com/docs/migrations/v0-12 migration guide}.
+ */
 export const useMessagePartText = () => {
   const text = useAuiState((s) => {
     if (s.part.type !== "text" && s.part.type !== "reasoning")

package/src/primitives/thread/useThreadViewportAutoScroll.test.tsx

@@ -0,0 +1,320 @@
+// @vitest-environment jsdom
+
+import { act, cleanup, render, screen, waitFor } from "@testing-library/react";
+import {
+  afterAll,
+  afterEach,
+  beforeAll,
+  describe,
+  expect,
+  it,
+  vi,
+} from "vitest";
+import { useEffect, useState, type FC, type PropsWithChildren } from "react";
+import { AssistantRuntimeProvider } from "../../context";
+import * as MessagePrimitive from "../message";
+import { ThreadPrimitiveMessages } from "./ThreadMessages";
+import { ThreadPrimitiveRoot } from "./ThreadRoot";
+import { ThreadPrimitiveViewport } from "./ThreadViewport";
+import {
+  ExportedMessageRepository,
+  useLocalRuntime,
+  type ChatModelAdapter,
+  type ThreadHistoryAdapter,
+  type ThreadMessageLike,
+} from "../../index";
+
+const adapter: ChatModelAdapter = {
+  async *run() {},
+};
+
+const messages: ThreadMessageLike[] = Array.from({ length: 8 }, (_, index) => ({
+  role: index % 2 === 0 ? "user" : "assistant",
+  content: [{ type: "text", text: `Message ${index + 1}` }],
+}));
+
+const getViewport = () => screen.getByTestId("viewport");
+
+const getMaxScrollTop = (element: Element) =>
+  Math.max(0, element.scrollHeight - element.clientHeight);
+
+let forceShortViewportMeasurement = false;
+const resizeObserverCallbacks = new Set<ResizeObserverCallback>();
+
+class TestResizeObserver {
+  private callback: ResizeObserverCallback;
+
+  constructor(callback: ResizeObserverCallback) {
+    this.callback = callback;
+    resizeObserverCallbacks.add(callback);
+  }
+
+  observe() {}
+  disconnect() {
+    resizeObserverCallbacks.delete(this.callback);
+  }
+}
+
+const notifyResizeObservers = () => {
+  for (const callback of resizeObserverCallbacks) {
+    callback([], {} as ResizeObserver);
+  }
+};
+
+const descriptors = {
+  scrollTop: Object.getOwnPropertyDescriptor(
+    HTMLElement.prototype,
+    "scrollTop",
+  ),
+  scrollHeight: Object.getOwnPropertyDescriptor(
+    HTMLElement.prototype,
+    "scrollHeight",
+  ),
+  clientHeight: Object.getOwnPropertyDescriptor(
+    HTMLElement.prototype,
+    "clientHeight",
+  ),
+  scrollTo: Object.getOwnPropertyDescriptor(HTMLElement.prototype, "scrollTo"),
+};
+
+const scrollTopByElement = new WeakMap<Element, number>();
+
+beforeAll(() => {
+  vi.stubGlobal("ResizeObserver", TestResizeObserver);
+  vi.stubGlobal("requestAnimationFrame", (callback: FrameRequestCallback) =>
+    window.setTimeout(() => callback(performance.now()), 0),
+  );
+  vi.stubGlobal("cancelAnimationFrame", (id: number) =>
+    window.clearTimeout(id),
+  );
+
+  Object.defineProperty(HTMLElement.prototype, "scrollTop", {
+    configurable: true,
+    get() {
+      return scrollTopByElement.get(this) ?? 0;
+    },
+    set(value: number) {
+      scrollTopByElement.set(this, value);
+    },
+  });
+
+  Object.defineProperty(HTMLElement.prototype, "clientHeight", {
+    configurable: true,
+    get() {
+      return this.getAttribute("data-testid") === "viewport" ? 100 : 0;
+    },
+  });
+
+  Object.defineProperty(HTMLElement.prototype, "scrollHeight", {
+    configurable: true,
+    get() {
+      if (this.getAttribute("data-testid") !== "viewport") return 0;
+      if (forceShortViewportMeasurement) return this.clientHeight;
+      return (
+        document.querySelectorAll('[data-testid="thread-message"]').length * 80
+      );
+    },
+  });
+
+  Object.defineProperty(HTMLElement.prototype, "scrollTo", {
+    configurable: true,
+    value({ top = 0 }: ScrollToOptions) {
+      this.scrollTop = Math.min(Number(top), getMaxScrollTop(this));
+      this.dispatchEvent(new Event("scroll"));
+    },
+  });
+});
+
+afterEach(() => {
+  forceShortViewportMeasurement = false;
+  resizeObserverCallbacks.clear();
+  cleanup();
+});
+
+afterAll(() => {
+  vi.unstubAllGlobals();
+
+  for (const [key, descriptor] of Object.entries(descriptors)) {
+    if (descriptor) {
+      Object.defineProperty(HTMLElement.prototype, key, descriptor);
+    }
+  }
+});
+
+const Message: FC = () => (
+  <MessagePrimitive.Root data-testid="thread-message">
+    <MessagePrimitive.Content />
+  </MessagePrimitive.Root>
+);
+
+const Thread = ({
+  autoScroll,
+  scrollToBottomOnInitialize,
+}: {
+  autoScroll?: boolean | undefined;
+  scrollToBottomOnInitialize?: boolean | undefined;
+}) => (
+  <ThreadPrimitiveRoot>
+    <ThreadPrimitiveViewport
+      autoScroll={autoScroll}
+      data-testid="viewport"
+      turnAnchor="top"
+      scrollToBottomOnInitialize={scrollToBottomOnInitialize}
+    >
+      <ThreadPrimitiveMessages components={{ Message }} />
+    </ThreadPrimitiveViewport>
+  </ThreadPrimitiveRoot>
+);
+
+const BottomAnchorThread = () => (
+  <ThreadPrimitiveRoot>
+    <ThreadPrimitiveViewport data-testid="viewport">
+      <ThreadPrimitiveMessages components={{ Message }} />
+    </ThreadPrimitiveViewport>
+  </ThreadPrimitiveRoot>
+);
+
+const SyncRuntimeProvider: FC<PropsWithChildren> = ({ children }) => {
+  const runtime = useLocalRuntime(adapter, { initialMessages: messages });
+
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      {children}
+    </AssistantRuntimeProvider>
+  );
+};
+
+const AsyncRuntimeProvider: FC<PropsWithChildren> = ({ children }) => {
+  const history: ThreadHistoryAdapter = {
+    async load() {
+      await Promise.resolve();
+      return ExportedMessageRepository.fromArray(messages);
+    },
+    async append() {},
+  };
+  const runtime = useLocalRuntime(adapter, { adapters: { history } });
+
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      {children}
+    </AssistantRuntimeProvider>
+  );
+};
+
+const DelayedThread = ({
+  autoScroll,
+  scrollToBottomOnInitialize,
+}: {
+  autoScroll?: boolean | undefined;
+  scrollToBottomOnInitialize?: boolean | undefined;
+}) => {
+  const [showThread, setShowThread] = useState(false);
+
+  useEffect(() => {
+    setShowThread(true);
+  }, []);
+
+  if (!showThread) return null;
+  return (
+    <Thread
+      autoScroll={autoScroll}
+      scrollToBottomOnInitialize={scrollToBottomOnInitialize}
+    />
+  );
+};
+
+describe("useThreadViewportAutoScroll", () => {
+  it("scrolls sync initialMessages to the bottom when the viewport mounts after initialization", async () => {
+    render(
+      <SyncRuntimeProvider>
+        <DelayedThread />
+      </SyncRuntimeProvider>,
+    );
+
+    await waitFor(() => {
+      expect(screen.getAllByTestId("thread-message")).toHaveLength(
+        messages.length,
+      );
+      expect(getViewport().scrollTop).toBe(getMaxScrollTop(getViewport()));
+    });
+  });
+
+  it("keeps async history initialization scroll pending until imported messages are measurable", async () => {
+    forceShortViewportMeasurement = true;
+
+    render(
+      <AsyncRuntimeProvider>
+        <Thread />
+      </AsyncRuntimeProvider>,
+    );
+
+    await waitFor(() => {
+      expect(screen.getAllByTestId("thread-message")).toHaveLength(
+        messages.length,
+      );
+    });
+
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    expect(getViewport().scrollTop).toBe(0);
+
+    forceShortViewportMeasurement = false;
+    notifyResizeObservers();
+
+    await waitFor(() => {
+      expect(getViewport().scrollTop).toBe(getMaxScrollTop(getViewport()));
+    });
+  });
+
+  it("preserves run-start's auto behavior on the first message of an empty thread", async () => {
+    const scrollToSpy = vi.spyOn(HTMLElement.prototype, "scrollTo");
+
+    let runtime: ReturnType<typeof useLocalRuntime> | null = null;
+    const Harness: FC = () => {
+      runtime = useLocalRuntime(adapter);
+      return (
+        <AssistantRuntimeProvider runtime={runtime}>
+          <BottomAnchorThread />
+        </AssistantRuntimeProvider>
+      );
+    };
+
+    render(<Harness />);
+
+    expect(screen.queryAllByTestId("thread-message")).toHaveLength(0);
+
+    await act(async () => {
+      runtime!.thread.append({
+        role: "user",
+        content: [{ type: "text", text: "hello" }],
+      });
+    });
+
+    await waitFor(() => {
+      expect(scrollToSpy).toHaveBeenCalled();
+    });
+
+    const behaviors = scrollToSpy.mock.calls.map(
+      (call) => (call[0] as ScrollToOptions).behavior,
+    );
+    expect(behaviors[0]).toBe("auto");
+    expect(behaviors).not.toContain("instant");
+
+    scrollToSpy.mockRestore();
+  });
+
+  it("does not scroll initial messages when initialize scrolling is disabled", async () => {
+    render(
+      <SyncRuntimeProvider>
+        <Thread autoScroll={false} scrollToBottomOnInitialize={false} />
+      </SyncRuntimeProvider>,
+    );
+
+    await waitFor(() => {
+      expect(screen.getAllByTestId("thread-message")).toHaveLength(
+        messages.length,
+      );
+    });
+
+    expect(getViewport().scrollTop).toBe(0);
+  });
+});

package/src/primitives/thread/useThreadViewportAutoScroll.ts

@@ -1,8 +1,8 @@
 "use client";
 
 import { useComposedRefs } from "@radix-ui/react-compose-refs";
-import { useCallback, useRef, type RefCallback } from "react";
-import { useAuiEvent } from "@assistant-ui/store";
+import { useCallback, useLayoutEffect, useRef, type RefCallback } from "react";
+import { useAuiEvent, useAuiState } from "@assistant-ui/store";
 import { useOnResizeContent } from "../../utils/hooks/useOnResizeContent";
 import { useOnScrollToBottom } from "../../utils/hooks/useOnScrollToBottom";
 import { useManagedRef } from "../../utils/hooks/useManagedRef";
@@ -27,7 +27,7 @@ export namespace useThreadViewportAutoScroll {
     scrollToBottomOnRunStart?: boolean | undefined;
 
     /**
-     * Whether to scroll to bottom when thread history is first loaded.
+     * Whether to scroll to bottom when messages first appear in the thread.
      *
      * Defaults to true.
      */
@@ -49,6 +49,9 @@ export const useThreadViewportAutoScroll = <TElement extends HTMLElement>({
   scrollToBottomOnThreadSwitch = true,
 }: useThreadViewportAutoScroll.Options): RefCallback<TElement> => {
   const divRef = useRef<TElement>(null);
+  const hasMessages = useAuiState((s) => s.thread.messages.length > 0);
+  const initializeScrollRequestedRef = useRef(false);
+  const scheduledFrameRef = useRef<number | null>(null);
 
   const threadViewportStore = useThreadViewportStore();
   if (autoScroll === undefined) {
@@ -57,9 +60,8 @@ export const useThreadViewportAutoScroll = <TElement extends HTMLElement>({
 
   const lastScrollTop = useRef<number>(0);
 
-  // bug: when ScrollToBottom's button changes its disabled state, the scroll stops
-  // fix: delay the state change until the scroll is done
-  // stores the scroll behavior to reuse during content resize, or null if not scrolling
+  // Pending bottom-scroll intent. Planted by initialize/run-start/switch/button
+  // triggers, cleared only when handleScroll confirms we reached bottom.
   const scrollingToBottomBehaviorRef = useRef<ScrollBehavior | null>(null);
 
   const scrollToBottom = useCallback((behavior: ScrollBehavior) => {
@@ -70,6 +72,29 @@ export const useThreadViewportAutoScroll = <TElement extends HTMLElement>({
     div.scrollTo({ top: div.scrollHeight, behavior });
   }, []);
 
+  const scheduleScrollToBottom = useCallback(
+    (behavior: ScrollBehavior) => {
+      scrollingToBottomBehaviorRef.current = behavior;
+      if (scheduledFrameRef.current !== null) {
+        cancelAnimationFrame(scheduledFrameRef.current);
+      }
+      scheduledFrameRef.current = requestAnimationFrame(() => {
+        scheduledFrameRef.current = null;
+        scrollToBottom(behavior);
+      });
+    },
+    [scrollToBottom],
+  );
+
+  useLayoutEffect(
+    () => () => {
+      if (scheduledFrameRef.current !== null) {
+        cancelAnimationFrame(scheduledFrameRef.current);
+      }
+    },
+    [],
+  );
+
   const hasActiveTopAnchor = useCallback(() => {
     const state = threadViewportStore.getState();
     return (
@@ -88,11 +113,19 @@ export const useThreadViewportAutoScroll = <TElement extends HTMLElement>({
       Math.abs(div.scrollHeight - div.scrollTop - div.clientHeight) < 1 ||
       div.scrollHeight <= div.clientHeight;
 
-    if (!newIsAtBottom && lastScrollTop.current < div.scrollTop) {
-      // ignore scroll down
+    const isInFlightDownwardScroll =
+      !newIsAtBottom && lastScrollTop.current < div.scrollTop;
+    if (isInFlightDownwardScroll) {
+      // no-op: a smooth scroll-to-bottom fires many midpoint scroll events
+      // before landing, don't flicker isAtBottom or clear intent mid-animation
     } else {
       if (newIsAtBottom) {
-        scrollingToBottomBehaviorRef.current = null;
+        // newIsAtBottom is ambiguous when the viewport doesn't overflow —
+        // keep intent alive until content can actually scroll
+        const viewportOverflows = div.scrollHeight > div.clientHeight + 1;
+        if (viewportOverflows) {
+          scrollingToBottomBehaviorRef.current = null;
+        }
       }
 
       const shouldUpdate =
@@ -129,37 +162,34 @@ export const useThreadViewportAutoScroll = <TElement extends HTMLElement>({
     };
   });
 
+  useLayoutEffect(() => {
+    if (!scrollToBottomOnInitialize) return;
+    if (!hasMessages) {
+      initializeScrollRequestedRef.current = false;
+      return;
+    }
+    if (initializeScrollRequestedRef.current) return;
+
+    initializeScrollRequestedRef.current = true;
+    // defer to an in-flight run (e.g. first message on a new thread) that
+    // already planted intent — otherwise we'd downgrade its "auto" to "instant"
+    if (scrollingToBottomBehaviorRef.current !== null) return;
+    scheduleScrollToBottom("instant");
+  }, [hasMessages, scheduleScrollToBottom, scrollToBottomOnInitialize]);
+
   useOnScrollToBottom(({ behavior }) => {
     scrollToBottom(behavior);
   });
 
-  // autoscroll on run start
   useAuiEvent("thread.runStart", () => {
     if (!scrollToBottomOnRunStart) return;
     if (threadViewportStore.getState().turnAnchor === "top") return;
-
-    scrollingToBottomBehaviorRef.current = "auto";
-    requestAnimationFrame(() => {
-      scrollToBottom("auto");
-    });
-  });
-
-  // scroll to bottom instantly when thread history is first loaded
-  useAuiEvent("thread.initialize", () => {
-    if (!scrollToBottomOnInitialize) return;
-    scrollingToBottomBehaviorRef.current = "instant";
-    requestAnimationFrame(() => {
-      scrollToBottom("instant");
-    });
+    scheduleScrollToBottom("auto");
   });
 
-  // scroll to bottom instantly when switching threads
   useAuiEvent("threadListItem.switchedTo", () => {
     if (!scrollToBottomOnThreadSwitch) return;
-    scrollingToBottomBehaviorRef.current = "instant";
-    requestAnimationFrame(() => {
-      scrollToBottom("instant");
-    });
+    scheduleScrollToBottom("instant");
   });
 
   const autoScrollRef = useComposedRefs<TElement>(resizeRef, scrollRef, divRef);

package/src/tests/BaseComposerRuntimeCore.test.ts

@@ -114,7 +114,7 @@ describe("BaseComposerRuntimeCore", () => {
   });
 
   it("sets and gets runConfig", () => {
-    const config = { custom: { model: "gpt-4" } };
+    const config = { custom: { model: "gpt-5.4-nano" } };
     composer.setRunConfig(config);
     expect(composer.runConfig).toBe(config);
   });

package/src/utils/smooth/useSmooth.ts

@@ -1,7 +1,7 @@
 "use client";
 
 import { useEffect, useMemo, useRef, useState } from "react";
-import { useAuiState } from "@assistant-ui/store";
+import { useAui, useAuiState } from "@assistant-ui/store";
 import type {
   MessagePartStatus,
   ReasoningMessagePart,
@@ -75,13 +75,28 @@ export const useSmooth = (
   smooth: boolean = false,
 ): MessagePartState & (TextMessagePart | ReasoningMessagePart) => {
   const { text } = state;
-  const id = useAuiState((s) => s.message.id);
 
-  const idRef = useRef(id);
   const [displayedText, setDisplayedText] = useState(
     state.status.type === "running" ? "" : text,
   );
 
+  // Render-phase resync on part flip or text discontinuity, so the
+  // first paint after a thread switch never shows the previous
+  // part's text (#4051). `displayedText` is already a prefix of
+  // `text` during normal streaming, so use it as the previous-text
+  // reference instead of carrying separate state — avoids the
+  // double render per streaming token. Read part identity through
+  // `useAuiState` so we actually subscribe to its changes instead
+  // of relying on a render-time proxy reference that may be stable
+  // across thread swaps.
+  const aui = useAui();
+  const part = useAuiState(() => aui.part());
+  const [prevPart, setPrevPart] = useState(part);
+  if (part !== prevPart || !text.startsWith(displayedText)) {
+    setPrevPart(part);
+    setDisplayedText(state.status.type === "running" ? "" : text);
+  }
+
   const smoothStatusStore = useSmoothStatusStore({ optional: true });
   const setText = useCallbackRef((text: string) => {
     setDisplayedText(text);
@@ -109,35 +124,36 @@ export const useSmooth = (
     new TextStreamAnimator(displayedText, setText),
   );
 
+  const animatorPartRef = useRef(part);
   useEffect(() => {
     if (!smooth) {
       animatorRef.stop();
       return;
     }
 
-    if (idRef.current !== id || !text.startsWith(animatorRef.targetText)) {
-      idRef.current = id;
-
+    // Discontinuity: part flipped, or new text breaks continuation
+    // of the animator's current target. Either case requires
+    // resetting the cursor — without the part check, a new part
+    // whose text happens to share a prefix with the previous target
+    // would keep the stale cursor and flicker.
+    const partChanged = animatorPartRef.current !== part;
+    animatorPartRef.current = part;
+    if (partChanged || !text.startsWith(animatorRef.targetText)) {
       if (state.status.type === "running") {
-        // New streaming message → animate from empty string
-        setText("");
         animatorRef.currentText = "";
         animatorRef.targetText = text;
         animatorRef.start();
       } else {
-        // Completed message → display immediately
-        setText(text);
         animatorRef.currentText = text;
         animatorRef.targetText = text;
         animatorRef.stop();
       }
-
       return;
     }
 
     animatorRef.targetText = text;
     animatorRef.start();
-  }, [setText, animatorRef, id, smooth, text, state.status.type]);
+  }, [animatorRef, smooth, text, state.status.type, part]);
 
   useEffect(() => {
     return () => {