@assistant-ui/react 0.14.4 → 0.14.6

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