@assistant-ui/react 0.15.21 → 0.15.22

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

@@ -7,6 +7,10 @@ import {
 } from "./mountTopAnchorReserve";
 
 class ResizeObserverMock {
+  static callbacks: (() => void)[] = [];
+  constructor(callback: () => void) {
+    ResizeObserverMock.callbacks.push(callback);
+  }
   observe = vi.fn();
   disconnect = vi.fn();
 }
@@ -48,6 +52,7 @@ const activeTopAnchorTurn = { anchorId: "user-1", targetId: "assistant-1" };
 describe("mountTopAnchorReserve", () => {
   beforeEach(() => {
     vi.useFakeTimers();
+    ResizeObserverMock.callbacks = [];
     vi.stubGlobal("ResizeObserver", ResizeObserverMock);
     vi.stubGlobal("MutationObserver", MutationObserverMock);
   });
@@ -331,6 +336,197 @@ describe("mountTopAnchorReserve", () => {
     expect(reserve.style.height).toBe("0px");
   });
 
+  const mountPinnedViewport = () => {
+    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);
+
+    let naturalScrollHeight = 560;
+
+    defineReadonlyNumber(viewport, "offsetTop", 0);
+    defineReadonlyNumber(viewport, "clientHeight", 400);
+    Object.defineProperty(viewport, "scrollHeight", {
+      configurable: true,
+      get: () => {
+        const reserve = document.querySelector<HTMLElement>(
+          "[data-aui-top-anchor-reserve]",
+        );
+        return (
+          naturalScrollHeight + Number.parseFloat(reserve?.style.height || "0")
+        );
+      },
+    });
+    defineReadonlyNumber(anchor, "offsetTop", 220);
+    defineReadonlyNumber(anchor, "offsetHeight", 64);
+    anchor.dataset.messageId = "msg-1";
+    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<HTMLElement>(
+      "[data-aui-top-anchor-reserve]",
+    )!;
+    Object.defineProperty(reserve, "offsetHeight", {
+      configurable: true,
+      get: () => Number.parseFloat(reserve.style.height || "0"),
+    });
+    vi.runOnlyPendingTimers();
+
+    expect(viewport.scrollTo).toHaveBeenCalledTimes(1);
+    expect(viewport.scrollTo).toHaveBeenLastCalledWith({
+      top: 220,
+      behavior: "smooth",
+    });
+
+    viewport.scrollTop = 220;
+    viewport.dispatchEvent(new Event("scroll"));
+
+    return {
+      viewport,
+      anchor,
+      target,
+      store,
+      setState,
+      unmount,
+      notifyLayout: () => ResizeObserverMock.callbacks.at(-1)!(),
+      setNaturalScrollHeight: (height: number) => {
+        naturalScrollHeight = height;
+      },
+    };
+  };
+
+  it("restores the pre-clamp position when the old offset becomes unreachable", () => {
+    const { viewport, setNaturalScrollHeight } = mountPinnedViewport();
+
+    setNaturalScrollHeight(400);
+    viewport.scrollTop = 60;
+    viewport.dispatchEvent(new Event("scroll"));
+    setNaturalScrollHeight(560);
+    vi.runOnlyPendingTimers();
+
+    expect(viewport.scrollTo).toHaveBeenCalledTimes(2);
+    expect(viewport.scrollTo).toHaveBeenLastCalledWith({
+      top: 220,
+      behavior: "instant",
+    });
+  });
+
+  it("does not undo a reachable scrollIntoView movement", () => {
+    const { viewport, target, notifyLayout } = mountPinnedViewport();
+    target.scrollIntoView = vi.fn(() => {
+      viewport.scrollTop = 100;
+      viewport.dispatchEvent(new Event("scroll"));
+    });
+
+    target.scrollIntoView();
+    notifyLayout();
+    vi.runOnlyPendingTimers();
+
+    expect(viewport.scrollTo).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not undo reachable focus scrolling", () => {
+    const { viewport, target, notifyLayout } = mountPinnedViewport();
+    const input = document.createElement("input");
+    target.append(input);
+
+    input.focus();
+    viewport.scrollTop = 100;
+    viewport.dispatchEvent(new Event("scroll"));
+    notifyLayout();
+    vi.runOnlyPendingTimers();
+
+    expect(viewport.scrollTo).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not restore an out-of-range movement that did not land at the maximum", () => {
+    const { viewport, setNaturalScrollHeight, notifyLayout } =
+      mountPinnedViewport();
+
+    setNaturalScrollHeight(400);
+    viewport.scrollTop = 40;
+    viewport.dispatchEvent(new Event("scroll"));
+    setNaturalScrollHeight(560);
+    notifyLayout();
+    vi.runOnlyPendingTimers();
+
+    expect(viewport.scrollTo).toHaveBeenCalledTimes(1);
+  });
+
+  it("restores at most once per anchor turn", () => {
+    const { viewport, setNaturalScrollHeight, notifyLayout } =
+      mountPinnedViewport();
+
+    setNaturalScrollHeight(400);
+    viewport.scrollTop = 60;
+    viewport.dispatchEvent(new Event("scroll"));
+    setNaturalScrollHeight(560);
+    vi.runOnlyPendingTimers();
+    expect(viewport.scrollTo).toHaveBeenCalledTimes(2);
+
+    viewport.scrollTop = 220;
+    viewport.dispatchEvent(new Event("scroll"));
+    setNaturalScrollHeight(400);
+    viewport.scrollTop = 60;
+    viewport.dispatchEvent(new Event("scroll"));
+    setNaturalScrollHeight(560);
+    notifyLayout();
+    vi.runOnlyPendingTimers();
+
+    expect(viewport.scrollTo).toHaveBeenCalledTimes(2);
+  });
+
+  it("drops a pending restore across an anchor-gap thread transition", () => {
+    const { viewport, setState, setNaturalScrollHeight } =
+      mountPinnedViewport();
+
+    setNaturalScrollHeight(400);
+    viewport.scrollTop = 60;
+    viewport.dispatchEvent(new Event("scroll"));
+
+    setState({
+      turnAnchor: "top",
+      element: { viewport, anchor: null, target: null },
+      targetConfig: null,
+      topAnchorTurn: activeTopAnchorTurn,
+    });
+    vi.runOnlyPendingTimers();
+
+    const nextAnchor = document.createElement("div");
+    const nextTarget = document.createElement("div");
+    document.body.append(nextTarget);
+    defineReadonlyNumber(nextAnchor, "offsetTop", 480);
+    defineReadonlyNumber(nextAnchor, "offsetHeight", 64);
+    nextAnchor.dataset.messageId = "msg-2";
+
+    setState({
+      turnAnchor: "top",
+      element: { viewport, anchor: nextAnchor, target: nextTarget },
+      targetConfig: numericClamp,
+      topAnchorTurn: { anchorId: "user-2", targetId: "assistant-2" },
+    });
+    setNaturalScrollHeight(560);
+    vi.runOnlyPendingTimers();
+    vi.runOnlyPendingTimers();
+
+    expect(viewport.scrollTo).toHaveBeenCalledTimes(2);
+    expect(viewport.scrollTo).toHaveBeenLastCalledWith({
+      top: 480,
+      behavior: "smooth",
+    });
+  });
+
   it("does not repeat the smooth top-anchor scroll for the same message", () => {
     const viewport = document.createElement("div");
     const anchor = document.createElement("div");

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

@@ -61,13 +61,67 @@ export const mountTopAnchorReserve = (store: TopAnchorStore) => {
   let reserve: HTMLElement | null = null;
   let lastScrolledAnchorId: string | undefined;
 
+  let listenedViewport: HTMLElement | null = null;
+  let lastScrollTop = 0;
+  let restoreScrollTop: number | null = null;
+  let restoredThisTurn = false;
+  let lastAppliedTarget: number | null = null;
+
+  const clearRestore = () => {
+    restoreScrollTop = null;
+    lastAppliedTarget = null;
+  };
+
+  const wasPinnedAtLastScroll = () =>
+    lastAppliedTarget !== null &&
+    Math.abs(lastScrollTop - lastAppliedTarget) <= 1;
+
+  const handleScroll = () => {
+    const viewport = listenedViewport;
+    if (!viewport) return;
+    const scrollTop = viewport.scrollTop;
+    const maxScrollTop = Math.max(
+      0,
+      viewport.scrollHeight - viewport.clientHeight,
+    );
+    // A range clamp starts beyond the new maximum and lands on it.
+    const isRangeClamp =
+      scrollTop < lastScrollTop &&
+      lastScrollTop > maxScrollTop + 1 &&
+      Math.abs(scrollTop - maxScrollTop) <= 1;
+
+    if (isRangeClamp && wasPinnedAtLastScroll() && !restoredThisTurn) {
+      restoreScrollTop ??= lastScrollTop;
+      scheduler.schedule();
+    }
+
+    lastScrollTop = scrollTop;
+  };
+
+  const listenViewport = (viewport: HTMLElement | null) => {
+    if (listenedViewport === viewport) return;
+    if (listenedViewport) {
+      listenedViewport.removeEventListener("scroll", handleScroll);
+    }
+    listenedViewport = viewport;
+    restoredThisTurn = false;
+    clearRestore();
+    if (viewport) {
+      viewport.addEventListener("scroll", handleScroll, { passive: true });
+      lastScrollTop = viewport.scrollTop;
+    }
+  };
+
   function apply() {
     const state = store.getState();
     const { viewport, anchor, target } = state.element;
     const clamp = state.targetConfig;
 
+    listenViewport(state.turnAnchor === "top" ? viewport : null);
+
     if (state.turnAnchor !== "top" || !viewport) {
       observers.disconnect();
+      clearRestore();
       if (reserve) {
         setReserveHeight(reserve, 0);
         reserve.remove();
@@ -80,6 +134,7 @@ export const mountTopAnchorReserve = (store: TopAnchorStore) => {
       // 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();
+      clearRestore();
       if (
         reserve?.parentElement &&
         reserve.parentElement.lastElementChild !== reserve
@@ -91,6 +146,7 @@ export const mountTopAnchorReserve = (store: TopAnchorStore) => {
 
     if (!anchor || !target || !clamp) {
       observers.disconnect();
+      clearRestore();
       if (reserve) {
         setReserveHeight(reserve, 0);
         reserve.remove();
@@ -120,17 +176,33 @@ export const mountTopAnchorReserve = (store: TopAnchorStore) => {
     }
 
     const anchorId = getAnchorId(anchor);
-    if (anchorId !== undefined && lastScrolledAnchorId === anchorId) return;
-
     const targetScrollTop = snapScrollTop(
       computeTopAnchorTargetScrollTop({ viewport, anchor, ...clamp }),
     );
 
-    if (Math.abs(viewport.scrollTop - targetScrollTop) > 1) {
-      viewport.scrollTo({ top: targetScrollTop, behavior: "smooth" });
+    if (anchorId === undefined || anchorId !== lastScrolledAnchorId) {
+      restoreScrollTop = null;
+      restoredThisTurn = false;
+      if (Math.abs(viewport.scrollTop - targetScrollTop) > 1) {
+        viewport.scrollTo({ top: targetScrollTop, behavior: "smooth" });
+      }
+      if (anchorId !== undefined) lastScrolledAnchorId = anchorId;
+    } else if (restoreScrollTop !== null && lastAppliedTarget !== null) {
+      // Restore the anchor-relative position: if content above the anchor
+      // changed height and the browser already adjusted scrollTop to match
+      // (scroll anchoring), the desired offset equals the current one and
+      // this is a no-op.
+      const desired = snapScrollTop(
+        restoreScrollTop + (targetScrollTop - lastAppliedTarget),
+      );
+      restoreScrollTop = null;
+      restoredThisTurn = true;
+      if (Math.abs(viewport.scrollTop - desired) > 1) {
+        viewport.scrollTo({ top: desired, behavior: "instant" });
+      }
     }
 
-    if (anchorId !== undefined) lastScrolledAnchorId = anchorId;
+    lastAppliedTarget = targetScrollTop;
   }
 
   const scheduler = createFrameScheduler(apply);
@@ -143,6 +215,7 @@ export const mountTopAnchorReserve = (store: TopAnchorStore) => {
     scheduler.cancel();
     unsubscribe();
     observers.disconnect();
+    listenViewport(null);
     reserve?.remove();
   };
 };

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

@@ -182,6 +182,16 @@ const Thread = ({
     >
       <ThreadPrimitiveMessages components={{ Message }} />
       <AtBottom />
+      {/* The canonical Thread renders its composer inside the viewport, so
+          composer keystrokes bubble to the viewport's keydown listener. */}
+      <textarea data-testid="composer" />
+      {/* An input that activates on a key, and a `contenteditable="false"`
+          element in message content, both act on content rather than accept
+          text. Neither is a text-entry surface. */}
+      <input type="checkbox" data-testid="checkbox" />
+      <span contentEditable={false} data-testid="readonly-island" tabIndex={0}>
+        tool call
+      </span>
     </ThreadPrimitiveViewport>
   </ThreadPrimitiveRoot>
 );
@@ -410,6 +420,218 @@ describe("useThreadViewportAutoScroll", () => {
     expect(screen.getByTestId("is-at-bottom").textContent).toBe("true");
   });
 
+  it.each([
+    { label: "pointerdown", make: () => new Event("pointerdown") },
+    {
+      label: "Enter keydown",
+      make: () => new KeyboardEvent("keydown", { key: "Enter" }),
+    },
+    {
+      label: "Space keydown",
+      make: () => new KeyboardEvent("keydown", { key: " " }),
+    },
+  ])(
+    "drops pending bottom-scroll intent after a $label in a thread that cannot scroll",
+    async ({ make }) => {
+      // the viewport never overflows, so handleScroll keeps the intent alive
+      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);
+
+      // the user activates something in the thread, e.g. a collapsible tool call
+      act(() => {
+        getViewport().dispatchEvent(make());
+      });
+
+      // that activation grows the content
+      forceShortViewportMeasurement = false;
+      act(notifyResizeObservers);
+
+      expect(getViewport().scrollTop).toBe(0);
+    },
+  );
+
+  it.each([
+    { label: "pointerdown", make: () => new Event("pointerdown") },
+    {
+      label: "Enter keydown",
+      make: () => new KeyboardEvent("keydown", { key: "Enter" }),
+    },
+    {
+      label: "Space keydown",
+      make: () => new KeyboardEvent("keydown", { key: " " }),
+    },
+  ])(
+    "cancels the frame a pending bottom scroll queued when a $label arrives first",
+    async ({ make }) => {
+      let nextFrameId = 0;
+      let pendingFrame: {
+        id: number;
+        callback: FrameRequestCallback;
+      } | null = null;
+      const originalRequestAnimationFrame = globalThis.requestAnimationFrame;
+      const originalCancelAnimationFrame = globalThis.cancelAnimationFrame;
+
+      vi.stubGlobal(
+        "requestAnimationFrame",
+        (callback: FrameRequestCallback) => {
+          const id = ++nextFrameId;
+          pendingFrame = { id, callback };
+          return id;
+        },
+      );
+      vi.stubGlobal(
+        "cancelAnimationFrame",
+        vi.fn((id: number) => {
+          if (pendingFrame?.id === id) pendingFrame = null;
+        }),
+      );
+
+      try {
+        render(
+          <SyncRuntimeProvider>
+            <BottomAnchorThread />
+          </SyncRuntimeProvider>,
+        );
+
+        const viewport = getViewport();
+        await waitFor(() => {
+          expect(screen.getAllByTestId("thread-message")).toHaveLength(
+            messages.length,
+          );
+          expect(pendingFrame).not.toBeNull();
+        });
+
+        // the gesture lands before the queued frame runs
+        act(() => {
+          viewport.dispatchEvent(make());
+        });
+
+        // clearing the ref alone would leave this frame to re-plant the intent
+        expect(pendingFrame).toBeNull();
+      } finally {
+        vi.stubGlobal("requestAnimationFrame", originalRequestAnimationFrame);
+        vi.stubGlobal("cancelAnimationFrame", originalCancelAnimationFrame);
+      }
+    },
+  );
+
+  it.each([
+    "Shift",
+    "Control",
+    "Meta",
+    "Tab",
+    "ArrowDown",
+    "PageDown",
+    "Escape",
+    "a",
+  ])("keeps pending bottom-scroll intent through a %s press", async (key) => {
+    forceShortViewportMeasurement = true;
+
+    render(
+      <AsyncRuntimeProvider>
+        <Thread />
+      </AsyncRuntimeProvider>,
+    );
+
+    await waitFor(() => {
+      expect(screen.getAllByTestId("thread-message")).toHaveLength(
+        messages.length,
+      );
+    });
+    await new Promise((resolve) => setTimeout(resolve, 0));
+
+    // neither an activation key nor consumed by a text field
+    act(() => {
+      getViewport().dispatchEvent(new KeyboardEvent("keydown", { key }));
+    });
+
+    forceShortViewportMeasurement = false;
+    act(notifyResizeObservers);
+
+    expect(getViewport().scrollTop).toBe(getMaxScrollTop(getViewport()));
+  });
+
+  it("keeps pending bottom-scroll intent while the user types in the composer", async () => {
+    forceShortViewportMeasurement = true;
+
+    render(
+      <AsyncRuntimeProvider>
+        <Thread />
+      </AsyncRuntimeProvider>,
+    );
+
+    await waitFor(() => {
+      expect(screen.getAllByTestId("thread-message")).toHaveLength(
+        messages.length,
+      );
+    });
+    await new Promise((resolve) => setTimeout(resolve, 0));
+
+    act(() => {
+      screen
+        .getByTestId("composer")
+        // Space is an activation key, so this reaches the text-entry check
+        // instead of short-circuiting on the allowlist
+        .dispatchEvent(
+          new KeyboardEvent("keydown", { key: " ", bubbles: true }),
+        );
+    });
+
+    forceShortViewportMeasurement = false;
+    act(notifyResizeObservers);
+
+    expect(getViewport().scrollTop).toBe(getMaxScrollTop(getViewport()));
+  });
+
+  it.each([
+    { label: "a checkbox", testid: "checkbox" },
+    { label: "a non-editable element", testid: "readonly-island" },
+  ])(
+    "drops pending bottom-scroll intent when a key activates $label",
+    async ({ testid }) => {
+      forceShortViewportMeasurement = true;
+
+      render(
+        <AsyncRuntimeProvider>
+          <Thread />
+        </AsyncRuntimeProvider>,
+      );
+
+      await waitFor(() => {
+        expect(screen.getAllByTestId("thread-message")).toHaveLength(
+          messages.length,
+        );
+      });
+      await new Promise((resolve) => setTimeout(resolve, 0));
+
+      act(() => {
+        screen
+          .getByTestId(testid)
+          .dispatchEvent(
+            new KeyboardEvent("keydown", { key: " ", bubbles: true }),
+          );
+      });
+
+      forceShortViewportMeasurement = false;
+      act(notifyResizeObservers);
+
+      expect(getViewport().scrollTop).toBe(0);
+    },
+  );
+
   it("cancels a queued bottom scroll when the user scrolls up", async () => {
     let nextFrameId = 0;
     let pendingFrame: {

package/src/primitives/thread/useThreadViewportAutoScroll.ts

@@ -14,6 +14,25 @@ import { useManagedRef } from "../../utils/hooks/useManagedRef";
 import { writableStore } from "../../context/ReadonlyStore";
 import { useThreadViewportStore } from "../../context/react/ThreadViewportContext";
 
+// Enter and Space activate a focused control, which is how a collapsible tool
+// call expands without a pointer event ever firing. No other key changes thread
+// content: the keys that scroll the viewport reach handleScroll, which already
+// clears the intent when the user scrolls up.
+const ACTIVATION_KEYS = new Set(["Enter", " "]);
+
+// A control that consumes the activation key itself instead of acting on thread
+// content. `contenteditable="false"` marks a non-editable island inside an
+// editable tree, so it is excluded the way ComposerRoot already excludes it;
+// the input types left out are the ones a key activates rather than fills.
+const TEXT_ENTRY_SELECTOR = [
+  "textarea",
+  "select",
+  "[contenteditable]:not([contenteditable='false'])",
+  "input:not([type='checkbox']):not([type='radio']):not([type='button'])" +
+    ":not([type='submit']):not([type='reset']):not([type='image'])" +
+    ":not([type='range']):not([type='file']):not([type='color'])",
+].join(", ");
+
 export namespace useThreadViewportAutoScroll {
   export type Options = {
     /**
@@ -203,17 +222,33 @@ export const useThreadViewportAutoScroll = <TElement extends HTMLElement>({
   });
 
   const scrollRef = useManagedRef<HTMLElement>((el) => {
-    // A pointer gesture invalidates pending bottom-scroll intent; otherwise an
+    // A user gesture invalidates pending bottom-scroll intent; otherwise an
     // intent kept alive by a non-overflowing thread (see handleScroll) hijacks
-    // the next content growth, e.g. expanding a collapsible tool call.
+    // the next content growth, e.g. expanding a collapsible tool call. Keyboard
+    // activation reaches that same content without ever emitting a pointer
+    // event, so it has to cancel the intent too.
     const cancelPendingScrollToBottom = () => {
+      // A scheduled frame re-plants the intent when it runs, so clearing the
+      // ref alone leaves the gesture undone.
+      cancelScheduledFrame();
       scrollingToBottomBehaviorRef.current = null;
     };
+    // The composer renders inside the viewport, so its keystrokes bubble here;
+    // only an activation key aimed at something other than a text field is a
+    // gesture on thread content.
+    const cancelOnKeyDown = (event: KeyboardEvent) => {
+      if (!ACTIVATION_KEYS.has(event.key)) return;
+      const target = event.target as Element | null;
+      if (target?.closest?.(TEXT_ENTRY_SELECTOR)) return;
+      cancelPendingScrollToBottom();
+    };
     el.addEventListener("scroll", handleScroll);
     el.addEventListener("pointerdown", cancelPendingScrollToBottom);
+    el.addEventListener("keydown", cancelOnKeyDown);
     return () => {
       el.removeEventListener("scroll", handleScroll);
       el.removeEventListener("pointerdown", cancelPendingScrollToBottom);
+      el.removeEventListener("keydown", cancelOnKeyDown);
     };
   });
 

package/src/tests/augmentations.test.ts

@@ -2,6 +2,7 @@ import { describe, expectTypeOf, it } from "vitest";
 import type { UserCommands, UserExternalState } from "../augmentations";
 import type {
   AssistantTransportCommand,
+  SendCommandsRequestBody,
   useAssistantTransportRuntime,
   useAssistantTransportSendCommand,
   useAssistantTransportState,
@@ -85,4 +86,10 @@ describe("Assistant augmentations", () => {
       >[0]["commands"][number]
     >();
   });
+
+  it("the react request body keeps the core request fields", () => {
+    expectTypeOf<Pick<SendCommandsRequestBody, "threadId">>().toEqualTypeOf<{
+      threadId?: string;
+    }>();
+  });
 });