@assistant-ui/react 0.14.27 → 0.14.29

package/src/primitives/messagePart/useMessagePartText.ts

@@ -4,13 +4,23 @@ import type {
   TextMessagePart,
   ReasoningMessagePart,
   MessagePartState,
+  MessagePartStatus,
 } from "@assistant-ui/core";
 import { useAuiState } from "@assistant-ui/store";
 
+const COMPLETE_STATUS: MessagePartStatus = Object.freeze({ type: "complete" });
+
+const EMPTY_TEXT_PART: MessagePartState & TextMessagePart = Object.freeze({
+  type: "text",
+  text: "",
+  status: COMPLETE_STATUS,
+});
+
 /**
  * @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.
+ * Return `null` for optional rendering. Do not throw inside the selector:
+ * selectors run inside `useSyncExternalStore`'s `getSnapshot`, so a transient
+ * part mismatch during thread switches can unmount the React root.
  *
  * @example
  * ```tsx
@@ -23,11 +33,11 @@ import { useAuiState } from "@assistant-ui/store";
  * See the {@link https://assistant-ui.com/docs/migrations/v0-12 migration guide}.
  */
 export const useMessagePartText = () => {
+  // Runs inside useSyncExternalStore's getSnapshot, where a throw tears down
+  // the React root; the module-level frozen sentinel keeps snapshots stable.
   const text = useAuiState((s) => {
     if (s.part.type !== "text" && s.part.type !== "reasoning")
-      throw new Error(
-        "MessagePartText can only be used inside text or reasoning message parts.",
-      );
+      return EMPTY_TEXT_PART;
 
     return s.part as MessagePartState &
       (TextMessagePart | ReasoningMessagePart);

package/src/primitives/thread/ThreadViewport.tsx

@@ -23,6 +23,7 @@ import { useTopAnchorReserve } from "./topAnchor/useTopAnchorReserve";
 import {
   getActiveTopAnchorAnchorId,
   getActiveTopAnchorTargetId,
+  isTopAnchorTurnValid,
 } from "./topAnchor/topAnchorTurn";
 
 export namespace ThreadPrimitiveViewport {
@@ -110,11 +111,25 @@ const useTopAnchorTurn = (enabled: boolean) => {
     if (!enabled) return undefined;
     return getActiveTopAnchorTargetId(s.thread);
   });
+  const topAnchorTurn = useThreadViewport((s) => s.topAnchorTurn);
   const activeTurn = useMemo(() => {
     if (!activeAnchorId || !activeTargetId) return null;
     return { anchorId: activeAnchorId, targetId: activeTargetId };
   }, [activeAnchorId, activeTargetId]);
 
+  const topAnchorTurnIsValid = useAuiState(
+    (s) =>
+      enabled &&
+      !!topAnchorTurn &&
+      isTopAnchorTurnValid(topAnchorTurn, s.thread.messages),
+  );
+
+  useLayoutEffect(() => {
+    if (!topAnchorTurn || topAnchorTurnIsValid) return;
+
+    threadViewportStore.getState().setTopAnchorTurn(null);
+  }, [threadViewportStore, topAnchorTurn, topAnchorTurnIsValid]);
+
   useLayoutEffect(() => {
     if (!activeTurn) return;
 

package/src/primitives/thread/topAnchor/mountTopAnchorReserve.test.ts

@@ -43,6 +43,7 @@ const makeStore = (state: ReturnType<TopAnchorStore["getState"]>) => {
 };
 
 const numericClamp = { tallerThan: 160, visibleHeight: 96 };
+const activeTopAnchorTurn = { anchorId: "user-1", targetId: "assistant-1" };
 
 describe("mountTopAnchorReserve", () => {
   beforeEach(() => {
@@ -76,6 +77,7 @@ describe("mountTopAnchorReserve", () => {
       turnAnchor: "top",
       element: { viewport, anchor, target },
       targetConfig: numericClamp,
+      topAnchorTurn: activeTopAnchorTurn,
     });
 
     mountTopAnchorReserve(store);
@@ -90,6 +92,245 @@ describe("mountTopAnchorReserve", () => {
     expect(reserve.style.height).toBe("60px");
   });
 
+  it("preserves the reserve across a transient between-turns anchor gap", () => {
+    const viewport = document.createElement("div");
+    const anchor = document.createElement("div");
+    const target = document.createElement("div");
+    const reserveHost = document.createElement("div");
+    reserveHost.append(target);
+    document.body.append(reserveHost);
+
+    defineReadonlyNumber(viewport, "offsetTop", 0);
+    defineReadonlyNumber(viewport, "clientHeight", 400);
+    defineReadonlyNumber(viewport, "scrollHeight", 560);
+    defineReadonlyNumber(anchor, "offsetTop", 220);
+    defineReadonlyNumber(anchor, "offsetHeight", 64);
+    viewport.scrollTo = vi.fn();
+
+    const { store, setState } = makeStore({
+      turnAnchor: "top",
+      element: { viewport, anchor, target },
+      targetConfig: numericClamp,
+      topAnchorTurn: activeTopAnchorTurn,
+    });
+
+    const unmount = mountTopAnchorReserve(store);
+    vi.runOnlyPendingTimers();
+
+    const reserve = reserveHost.querySelector(
+      "[data-aui-top-anchor-reserve]",
+    ) as HTMLElement;
+    const optimisticUserMessage = document.createElement("div");
+    reserveHost.append(optimisticUserMessage);
+    const appendSpy = vi.spyOn(reserveHost, "append");
+
+    setState({
+      turnAnchor: "top",
+      element: { viewport, anchor: null, target: null },
+      targetConfig: null,
+      topAnchorTurn: activeTopAnchorTurn,
+    });
+    vi.runOnlyPendingTimers();
+
+    expect(reserve.isConnected).toBe(true);
+    expect(reserve.style.height).toBe("60px");
+    expect(reserve.previousElementSibling).toBe(optimisticUserMessage);
+    expect(appendSpy).toHaveBeenCalledTimes(1);
+
+    setState({
+      turnAnchor: "top",
+      element: { viewport, anchor: null, target: null },
+      targetConfig: null,
+      topAnchorTurn: activeTopAnchorTurn,
+    });
+    vi.runOnlyPendingTimers();
+
+    expect(appendSpy).toHaveBeenCalledTimes(1);
+
+    const nextAnchor = document.createElement("div");
+    const nextTarget = document.createElement("div");
+    reserveHost.append(nextTarget);
+    defineReadonlyNumber(nextAnchor, "offsetTop", 236);
+    defineReadonlyNumber(nextAnchor, "offsetHeight", 64);
+
+    setState({
+      turnAnchor: "top",
+      element: { viewport, anchor: nextAnchor, target: nextTarget },
+      targetConfig: numericClamp,
+      topAnchorTurn: activeTopAnchorTurn,
+    });
+    vi.runOnlyPendingTimers();
+
+    expect(reserve.previousElementSibling).toBe(nextTarget);
+
+    unmount();
+    expect(reserve.isConnected).toBe(false);
+  });
+
+  it("removes the reserve when the active turn is no longer valid", () => {
+    const viewport = document.createElement("div");
+    const anchor = document.createElement("div");
+    const target = document.createElement("div");
+    const reserveHost = document.createElement("div");
+    reserveHost.append(target);
+    document.body.append(reserveHost);
+
+    defineReadonlyNumber(viewport, "offsetTop", 0);
+    defineReadonlyNumber(viewport, "clientHeight", 400);
+    defineReadonlyNumber(viewport, "scrollHeight", 560);
+    defineReadonlyNumber(anchor, "offsetTop", 220);
+    defineReadonlyNumber(anchor, "offsetHeight", 64);
+    viewport.scrollTo = vi.fn();
+
+    const { store, setState } = makeStore({
+      turnAnchor: "top",
+      element: { viewport, anchor, target },
+      targetConfig: numericClamp,
+      topAnchorTurn: activeTopAnchorTurn,
+    });
+
+    mountTopAnchorReserve(store);
+    vi.runOnlyPendingTimers();
+
+    const reserve = reserveHost.querySelector(
+      "[data-aui-top-anchor-reserve]",
+    ) as HTMLElement;
+
+    setState({
+      turnAnchor: "top",
+      element: { viewport, anchor: null, target: null },
+      targetConfig: null,
+      topAnchorTurn: null,
+    });
+    vi.runOnlyPendingTimers();
+
+    expect(reserve.isConnected).toBe(false);
+    expect(reserve.style.height).toBe("0px");
+  });
+
+  it("removes the reserve when only the registered anchor unmounts", () => {
+    const viewport = document.createElement("div");
+    const anchor = document.createElement("div");
+    const target = document.createElement("div");
+    const reserveHost = document.createElement("div");
+    reserveHost.append(target);
+    document.body.append(reserveHost);
+
+    defineReadonlyNumber(viewport, "offsetTop", 0);
+    defineReadonlyNumber(viewport, "clientHeight", 400);
+    defineReadonlyNumber(viewport, "scrollHeight", 560);
+    defineReadonlyNumber(anchor, "offsetTop", 220);
+    defineReadonlyNumber(anchor, "offsetHeight", 64);
+    viewport.scrollTo = vi.fn();
+
+    const { store, setState } = makeStore({
+      turnAnchor: "top",
+      element: { viewport, anchor, target },
+      targetConfig: numericClamp,
+      topAnchorTurn: activeTopAnchorTurn,
+    });
+
+    mountTopAnchorReserve(store);
+    vi.runOnlyPendingTimers();
+
+    const reserve = reserveHost.querySelector(
+      "[data-aui-top-anchor-reserve]",
+    ) as HTMLElement;
+
+    setState({
+      turnAnchor: "top",
+      element: { viewport, anchor: null, target },
+      targetConfig: numericClamp,
+      topAnchorTurn: activeTopAnchorTurn,
+    });
+    vi.runOnlyPendingTimers();
+
+    expect(reserve.isConnected).toBe(false);
+    expect(reserve.style.height).toBe("0px");
+  });
+
+  it("removes the reserve when the viewport is unavailable", () => {
+    const viewport = document.createElement("div");
+    const anchor = document.createElement("div");
+    const target = document.createElement("div");
+    const reserveHost = document.createElement("div");
+    reserveHost.append(target);
+    document.body.append(reserveHost);
+
+    defineReadonlyNumber(viewport, "offsetTop", 0);
+    defineReadonlyNumber(viewport, "clientHeight", 400);
+    defineReadonlyNumber(viewport, "scrollHeight", 560);
+    defineReadonlyNumber(anchor, "offsetTop", 220);
+    defineReadonlyNumber(anchor, "offsetHeight", 64);
+    viewport.scrollTo = vi.fn();
+
+    const { store, setState } = makeStore({
+      turnAnchor: "top",
+      element: { viewport, anchor, target },
+      targetConfig: numericClamp,
+      topAnchorTurn: activeTopAnchorTurn,
+    });
+
+    mountTopAnchorReserve(store);
+    vi.runOnlyPendingTimers();
+
+    const reserve = reserveHost.querySelector(
+      "[data-aui-top-anchor-reserve]",
+    ) as HTMLElement;
+
+    setState({
+      turnAnchor: "top",
+      element: { viewport: null, anchor: null, target: null },
+      targetConfig: null,
+      topAnchorTurn: null,
+    });
+    vi.runOnlyPendingTimers();
+
+    expect(reserve.isConnected).toBe(false);
+    expect(reserve.style.height).toBe("0px");
+  });
+
+  it("removes the reserve when top anchoring is disabled", () => {
+    const viewport = document.createElement("div");
+    const anchor = document.createElement("div");
+    const target = document.createElement("div");
+    const reserveHost = document.createElement("div");
+    reserveHost.append(target);
+    document.body.append(reserveHost);
+
+    defineReadonlyNumber(viewport, "offsetTop", 0);
+    defineReadonlyNumber(viewport, "clientHeight", 400);
+    defineReadonlyNumber(viewport, "scrollHeight", 560);
+    defineReadonlyNumber(anchor, "offsetTop", 220);
+    defineReadonlyNumber(anchor, "offsetHeight", 64);
+    viewport.scrollTo = vi.fn();
+
+    const { store, setState } = makeStore({
+      turnAnchor: "top",
+      element: { viewport, anchor, target },
+      targetConfig: numericClamp,
+      topAnchorTurn: activeTopAnchorTurn,
+    });
+
+    mountTopAnchorReserve(store);
+    vi.runOnlyPendingTimers();
+
+    const reserve = reserveHost.querySelector(
+      "[data-aui-top-anchor-reserve]",
+    ) as HTMLElement;
+
+    setState({
+      turnAnchor: "bottom",
+      element: { viewport, anchor: null, target: null },
+      targetConfig: null,
+      topAnchorTurn: null,
+    });
+    vi.runOnlyPendingTimers();
+
+    expect(reserve.isConnected).toBe(false);
+    expect(reserve.style.height).toBe("0px");
+  });
+
   it("does not repeat the smooth top-anchor scroll for the same message", () => {
     const viewport = document.createElement("div");
     const anchor = document.createElement("div");
@@ -108,6 +349,7 @@ describe("mountTopAnchorReserve", () => {
       turnAnchor: "top",
       element: { viewport, anchor, target },
       targetConfig: numericClamp,
+      topAnchorTurn: activeTopAnchorTurn,
     });
 
     mountTopAnchorReserve(store);
@@ -123,6 +365,7 @@ describe("mountTopAnchorReserve", () => {
       turnAnchor: "top",
       element: { viewport, anchor, target },
       targetConfig: numericClamp,
+      topAnchorTurn: activeTopAnchorTurn,
     });
     vi.runOnlyPendingTimers();
 

package/src/primitives/thread/topAnchor/mountTopAnchorReserve.ts

@@ -29,6 +29,10 @@ export type TopAnchorStore = {
       tallerThan: number;
       visibleHeight: number;
     } | null;
+    topAnchorTurn: {
+      readonly anchorId: string;
+      readonly targetId: string;
+    } | null;
   };
   subscribe(fn: () => void): () => void;
 };
@@ -62,13 +66,30 @@ export const mountTopAnchorReserve = (store: TopAnchorStore) => {
     const { viewport, anchor, target } = state.element;
     const clamp = state.targetConfig;
 
-    if (
-      state.turnAnchor !== "top" ||
-      !viewport ||
-      !anchor ||
-      !target ||
-      !clamp
-    ) {
+    if (state.turnAnchor !== "top" || !viewport) {
+      observers.disconnect();
+      if (reserve) {
+        setReserveHeight(reserve, 0);
+        reserve.remove();
+      }
+      return;
+    }
+
+    if (!anchor && !target && !clamp && state.topAnchorTurn) {
+      // ThreadViewport clears this state once the stored pair stops being the
+      // trailing turn (followed at most by pending user messages), so reaching
+      // here means the anchor gap is transient and the next run is imminent.
+      observers.disconnect();
+      if (
+        reserve?.parentElement &&
+        reserve.parentElement.lastElementChild !== reserve
+      ) {
+        reserve.parentElement.append(reserve);
+      }
+      return;
+    }
+
+    if (!anchor || !target || !clamp) {
       observers.disconnect();
       if (reserve) {
         setReserveHeight(reserve, 0);

package/src/primitives/thread/topAnchor/topAnchorTurn.test.ts

@@ -3,6 +3,7 @@ import {
   getActiveTopAnchorAnchorId,
   getActiveTopAnchorTargetId,
   getActiveTopAnchorTurn,
+  isTopAnchorTurnValid,
 } from "./topAnchorTurn";
 
 describe("topAnchorTurn", () => {
@@ -43,4 +44,72 @@ describe("topAnchorTurn", () => {
 
     expect(getActiveTopAnchorTurn({ isRunning: true, messages })).toBe(null);
   });
+
+  it("keeps a completed turn valid while it remains the trailing turn", () => {
+    const turn = { anchorId: "user-2", targetId: "assistant-2" };
+
+    expect(
+      isTopAnchorTurnValid(turn, [
+        { id: "assistant-1", role: "assistant" },
+        { id: "user-2", role: "user" },
+        { id: "assistant-2", role: "assistant" },
+      ]),
+    ).toBe(true);
+  });
+
+  it("keeps a turn valid across the between-turns gap with pending user messages", () => {
+    const turn = { anchorId: "user-2", targetId: "assistant-2" };
+
+    expect(
+      isTopAnchorTurnValid(turn, [
+        { id: "user-2", role: "user" },
+        { id: "assistant-2", role: "assistant" },
+        { id: "user-3", role: "user" },
+        { id: "user-4", role: "user" },
+      ]),
+    ).toBe(true);
+  });
+
+  it.each([
+    [
+      "thread switch",
+      [
+        { id: "other-user", role: "user" },
+        { id: "other-assistant", role: "assistant" },
+      ],
+    ],
+    ["new chat", []],
+    ["last-turn deletion", [{ id: "older-assistant", role: "assistant" }]],
+    [
+      "branch swap",
+      [
+        { id: "branch-user", role: "user" },
+        { id: "branch-assistant", role: "assistant" },
+      ],
+    ],
+    [
+      "an externally synced completed turn",
+      [
+        { id: "user-2", role: "user" },
+        { id: "assistant-2", role: "assistant" },
+        { id: "user-3", role: "user" },
+        { id: "assistant-3", role: "assistant" },
+      ],
+    ],
+    [
+      "a resync separating the pair",
+      [
+        { id: "user-2", role: "user" },
+        { id: "inserted-assistant", role: "assistant" },
+        { id: "assistant-2", role: "assistant" },
+      ],
+    ],
+  ])("invalidates a stored turn after %s", (_transition, messages) => {
+    expect(
+      isTopAnchorTurnValid(
+        { anchorId: "user-2", targetId: "assistant-2" },
+        messages,
+      ),
+    ).toBe(false);
+  });
 });

package/src/primitives/thread/topAnchor/topAnchorTurn.ts

@@ -5,6 +5,35 @@ type TopAnchorTurnMessage = {
   readonly role: string;
 };
 
+export type TopAnchorTurn = {
+  readonly anchorId: string;
+  readonly targetId: string;
+};
+
+/**
+ * A stored turn stays valid only while it is still the trailing turn: the
+ * anchor immediately precedes the target, and anything after the target is a
+ * pending user message awaiting the next run. An assistant message after the
+ * target means the turn was superseded (e.g. an external store synced in a
+ * turn completed elsewhere), so the reserve must be torn down, not preserved.
+ */
+export const isTopAnchorTurnValid = (
+  turn: TopAnchorTurn | null,
+  messages: readonly TopAnchorTurnMessage[],
+) => {
+  if (!turn) return false;
+
+  const targetIndex = messages.findIndex(
+    (message) => message.id === turn.targetId,
+  );
+  if (targetIndex < 1) return false;
+
+  return (
+    messages[targetIndex - 1]?.id === turn.anchorId &&
+    messages.slice(targetIndex + 1).every((message) => message.role === "user")
+  );
+};
+
 export const getActiveTopAnchorTurn = ({
   isRunning,
   messages,

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

@@ -11,6 +11,7 @@ import {
   vi,
 } from "vitest";
 import { useEffect, useState, type FC, type PropsWithChildren } from "react";
+import { useAuiState } from "@assistant-ui/store";
 import { AssistantRuntimeProvider } from "../../context";
 import * as MessagePrimitive from "../message";
 import { ThreadPrimitiveMessages } from "./ThreadMessages";
@@ -39,6 +40,7 @@ const getMaxScrollTop = (element: Element) =>
   Math.max(0, element.scrollHeight - element.clientHeight);
 
 let forceShortViewportMeasurement = false;
+let viewportMeasurementOffset = 0;
 const resizeObserverCallbacks = new Set<ResizeObserverCallback>();
 
 class TestResizeObserver {
@@ -111,7 +113,9 @@ beforeAll(() => {
       if (this.getAttribute("data-testid") !== "viewport") return 0;
       if (forceShortViewportMeasurement) return this.clientHeight;
       return (
-        document.querySelectorAll('[data-testid="thread-message"]').length * 80
+        document.querySelectorAll('[data-testid="thread-message"]').length *
+          80 +
+        viewportMeasurementOffset
       );
     },
   });
@@ -127,6 +131,7 @@ beforeAll(() => {
 
 afterEach(() => {
   forceShortViewportMeasurement = false;
+  viewportMeasurementOffset = 0;
   resizeObserverCallbacks.clear();
   cleanup();
 });
@@ -174,6 +179,11 @@ const BottomAnchorThread = () => (
   </ThreadPrimitiveRoot>
 );
 
+const RunState = () => {
+  const isRunning = useAuiState((s) => s.thread.isRunning);
+  return <output data-testid="run-state">{String(isRunning)}</output>;
+};
+
 const SyncRuntimeProvider: FC<PropsWithChildren> = ({ children }) => {
   const runtime = useLocalRuntime(adapter, { initialMessages: messages });
 
@@ -302,6 +312,81 @@ describe("useThreadViewportAutoScroll", () => {
     scrollToSpy.mockRestore();
   });
 
+  it("defers auto-scroll to an active top anchor only while the run is active", async () => {
+    let releaseRun!: () => void;
+    const runGate = new Promise<void>((resolve) => {
+      releaseRun = resolve;
+    });
+    const deferredAdapter: ChatModelAdapter = {
+      async *run() {
+        await runGate;
+        yield { content: [{ type: "text", text: "done" }] };
+      },
+    };
+    const scrollToSpy = vi.spyOn(HTMLElement.prototype, "scrollTo");
+
+    let runtime: ReturnType<typeof useLocalRuntime> | null = null;
+    const Harness: FC = () => {
+      runtime = useLocalRuntime(deferredAdapter, { initialMessages: messages });
+      return (
+        <AssistantRuntimeProvider runtime={runtime}>
+          <Thread autoScroll scrollToBottomOnInitialize={false} />
+          <RunState />
+        </AssistantRuntimeProvider>
+      );
+    };
+
+    render(<Harness />);
+
+    act(() => {
+      void runtime!.thread.append({
+        role: "user",
+        content: [{ type: "text", text: "hello" }],
+      });
+    });
+
+    await waitFor(() => {
+      expect(
+        document.querySelector("[data-aui-top-anchor-user]"),
+      ).not.toBeNull();
+    });
+
+    scrollToSpy.mockClear();
+    viewportMeasurementOffset = 1;
+    act(notifyResizeObservers);
+
+    expect(
+      scrollToSpy.mock.calls.map(
+        (call) => (call[0] as ScrollToOptions).behavior,
+      ),
+    ).not.toContain("instant");
+
+    await act(async () => {
+      releaseRun();
+    });
+    await waitFor(() => {
+      expect(screen.getByTestId("run-state").textContent).toBe("false");
+    });
+    expect(document.querySelector("[data-aui-top-anchor-user]")).not.toBeNull();
+
+    const viewport = getViewport();
+    act(() => {
+      viewport.scrollTop = getMaxScrollTop(viewport);
+      viewport.dispatchEvent(new Event("scroll"));
+    });
+    scrollToSpy.mockClear();
+    viewportMeasurementOffset = 2;
+    act(notifyResizeObservers);
+
+    expect(
+      scrollToSpy.mock.calls.map(
+        (call) => (call[0] as ScrollToOptions).behavior,
+      ),
+    ).toContain("instant");
+
+    scrollToSpy.mockRestore();
+  });
+
   it("does not scroll initial messages when initialize scrolling is disabled", async () => {
     render(
       <SyncRuntimeProvider>

package/src/primitives/thread/useThreadViewportAutoScroll.ts

@@ -50,6 +50,7 @@ export const useThreadViewportAutoScroll = <TElement extends HTMLElement>({
 }: useThreadViewportAutoScroll.Options): RefCallback<TElement> => {
   const divRef = useRef<TElement>(null);
   const hasMessages = useAuiState((s) => s.thread.messages.length > 0);
+  const isRunning = useAuiState((s) => s.thread.isRunning);
   const initializeScrollRequestedRef = useRef(false);
   const scheduledFrameRef = useRef<number | null>(null);
 
@@ -172,7 +173,11 @@ export const useThreadViewportAutoScroll = <TElement extends HTMLElement>({
       scrollingToBottomBehaviorRef.current = null;
     } else if (scrollBehavior) {
       scrollToBottom(scrollBehavior);
-    } else if (autoScroll && threadViewportStore.getState().isAtBottom) {
+    } else if (
+      autoScroll &&
+      !(isRunning && hasActiveTopAnchor()) &&
+      threadViewportStore.getState().isAtBottom
+    ) {
       scrollToBottom("instant");
     }