@assistant-ui/react 0.15.14 → 0.15.16

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

@@ -0,0 +1,251 @@
+// @vitest-environment jsdom
+
+import { act, render, screen, waitFor } from "@testing-library/react";
+import type { FC, PropsWithChildren } from "react";
+import { describe, expect, it, vi } from "vitest";
+import { AssistantRuntimeProvider } from "../../context";
+import { useLocalRuntime } from "../../legacy-runtime/runtime-cores/local/useLocalRuntime";
+import type {
+  ChatModelAdapter,
+  SpeechSynthesisAdapter,
+  ThreadMessageLike,
+} from "../../index";
+import { ComposerPrimitiveInput } from "../composer/ComposerInput";
+import { ThreadPrimitiveRoot } from "./ThreadRoot";
+
+const noOpAdapter: ChatModelAdapter = {
+  async *run() {},
+};
+
+const waitForAbortAdapter: ChatModelAdapter = {
+  async *run({ abortSignal }) {
+    await new Promise<void>((resolve) => {
+      if (abortSignal.aborted) {
+        resolve();
+        return;
+      }
+      abortSignal.addEventListener("abort", () => resolve(), { once: true });
+    });
+  },
+};
+
+const initialMessages: ThreadMessageLike[] = [
+  {
+    role: "assistant",
+    content: [{ type: "text", text: "Hello" }],
+    status: { type: "complete", reason: "stop" },
+  },
+];
+
+const createSpeechAdapter = () => {
+  const cancel = vi.fn();
+  const subscribers = new Set<() => void>();
+  const utterance: SpeechSynthesisAdapter.Utterance = {
+    status: { type: "running" },
+    cancel,
+    subscribe: (callback) => {
+      subscribers.add(callback);
+      return () => subscribers.delete(callback);
+    },
+  };
+  const adapter: SpeechSynthesisAdapter = {
+    speak: vi.fn(() => utterance),
+  };
+  const finish = () => {
+    utterance.status = { type: "ended", reason: "finished" };
+    for (const subscriber of subscribers) subscriber();
+  };
+
+  return { adapter, cancel, finish };
+};
+
+type RuntimeRef = {
+  current: ReturnType<typeof useLocalRuntime> | null;
+};
+
+const RuntimeProvider: FC<
+  PropsWithChildren<{
+    runtimeRef: RuntimeRef;
+    speech: SpeechSynthesisAdapter;
+    chatModel?: ChatModelAdapter | undefined;
+  }>
+> = ({ children, runtimeRef, speech, chatModel = noOpAdapter }) => {
+  const runtime = useLocalRuntime(chatModel, {
+    initialMessages,
+    adapters: { speech },
+  });
+  runtimeRef.current = runtime;
+
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      {children}
+    </AssistantRuntimeProvider>
+  );
+};
+
+const startSpeaking = (runtimeRef: RuntimeRef) => {
+  act(() => {
+    runtimeRef.current!.thread.getMessageByIndex(0).speak();
+  });
+};
+
+const dispatchEscape = (target: EventTarget) => {
+  const event = new KeyboardEvent("keydown", {
+    key: "Escape",
+    bubbles: true,
+    cancelable: true,
+  });
+  act(() => target.dispatchEvent(event));
+  return event;
+};
+
+describe("ThreadPrimitiveRoot", () => {
+  it("stops active speech after the initiating control unmounts", async () => {
+    const speech = createSpeechAdapter();
+    const runtimeRef: RuntimeRef = { current: null };
+    const App = ({ showControl }: { showControl: boolean }) => (
+      <RuntimeProvider runtimeRef={runtimeRef} speech={speech.adapter}>
+        <ThreadPrimitiveRoot>
+          {showControl && <button data-testid="speak-control" />}
+        </ThreadPrimitiveRoot>
+      </RuntimeProvider>
+    );
+    const view = render(<App showControl />);
+
+    const control = screen.getByTestId("speak-control");
+    control.focus();
+    startSpeaking(runtimeRef);
+    await waitFor(() => {
+      expect(runtimeRef.current!.thread.getState().speech).toBeDefined();
+    });
+
+    view.rerender(<App showControl={false} />);
+    const event = dispatchEscape(document.body);
+
+    expect(speech.cancel).toHaveBeenCalledOnce();
+    expect(event.defaultPrevented).toBe(true);
+  });
+
+  it("does not consume Escape when no speech is active", () => {
+    const speech = createSpeechAdapter();
+    const runtimeRef: RuntimeRef = { current: null };
+    render(
+      <RuntimeProvider runtimeRef={runtimeRef} speech={speech.adapter}>
+        <ThreadPrimitiveRoot>
+          <button data-testid="thread-control" />
+        </ThreadPrimitiveRoot>
+      </RuntimeProvider>,
+    );
+
+    const event = dispatchEscape(screen.getByTestId("thread-control"));
+
+    expect(speech.cancel).not.toHaveBeenCalled();
+    expect(event.defaultPrevented).toBe(false);
+  });
+
+  it("stops speech from outside the only mounted thread", async () => {
+    const speech = createSpeechAdapter();
+    const runtimeRef: RuntimeRef = { current: null };
+    render(
+      <>
+        <RuntimeProvider runtimeRef={runtimeRef} speech={speech.adapter}>
+          <ThreadPrimitiveRoot />
+        </RuntimeProvider>
+        <button data-testid="outside-control" />
+      </>,
+    );
+    startSpeaking(runtimeRef);
+    await waitFor(() => {
+      expect(runtimeRef.current!.thread.getState().speech).toBeDefined();
+    });
+
+    const event = dispatchEscape(screen.getByTestId("outside-control"));
+
+    expect(speech.cancel).toHaveBeenCalledOnce();
+    expect(event.defaultPrevented).toBe(true);
+  });
+
+  it("ignores speech ending between the rendered state and Escape", async () => {
+    const speech = createSpeechAdapter();
+    const runtimeRef: RuntimeRef = { current: null };
+    render(
+      <RuntimeProvider runtimeRef={runtimeRef} speech={speech.adapter}>
+        <ThreadPrimitiveRoot />
+      </RuntimeProvider>,
+    );
+    startSpeaking(runtimeRef);
+    await waitFor(() => {
+      expect(runtimeRef.current!.thread.getState().speech).toBeDefined();
+    });
+
+    expect(() => {
+      act(() => {
+        speech.finish();
+        document.body.dispatchEvent(
+          new KeyboardEvent("keydown", {
+            key: "Escape",
+            bubbles: true,
+            cancelable: true,
+          }),
+        );
+      });
+    }).not.toThrow();
+    expect(speech.cancel).not.toHaveBeenCalled();
+  });
+
+  it("lets a composer mounted after the root consume Escape first", async () => {
+    const speech = createSpeechAdapter();
+    const runtimeRef: RuntimeRef = { current: null };
+    const App = ({ showComposer }: { showComposer: boolean }) => (
+      <RuntimeProvider
+        runtimeRef={runtimeRef}
+        speech={speech.adapter}
+        chatModel={waitForAbortAdapter}
+      >
+        <ThreadPrimitiveRoot>
+          {showComposer && <ComposerPrimitiveInput data-testid="composer" />}
+        </ThreadPrimitiveRoot>
+      </RuntimeProvider>
+    );
+    const view = render(<App showComposer={false} />);
+    startSpeaking(runtimeRef);
+    act(() => {
+      runtimeRef.current!.thread.append("Run");
+    });
+    await waitFor(() => {
+      expect(runtimeRef.current!.thread.getState().speech).toBeDefined();
+      expect(runtimeRef.current!.thread.getState().isRunning).toBe(true);
+    });
+
+    view.rerender(<App showComposer />);
+    const event = dispatchEscape(screen.getByTestId("composer"));
+
+    await waitFor(() => {
+      expect(runtimeRef.current!.thread.getState().isRunning).toBe(false);
+    });
+    expect(speech.cancel).not.toHaveBeenCalled();
+    expect(event.defaultPrevented).toBe(true);
+  });
+
+  it("lets an idle composer fall through so Escape still stops speech", async () => {
+    const speech = createSpeechAdapter();
+    const runtimeRef: RuntimeRef = { current: null };
+    render(
+      <RuntimeProvider runtimeRef={runtimeRef} speech={speech.adapter}>
+        <ThreadPrimitiveRoot>
+          <ComposerPrimitiveInput data-testid="composer" />
+        </ThreadPrimitiveRoot>
+      </RuntimeProvider>,
+    );
+    startSpeaking(runtimeRef);
+    await waitFor(() => {
+      expect(runtimeRef.current!.thread.getState().speech).toBeDefined();
+    });
+
+    const event = dispatchEscape(screen.getByTestId("composer"));
+
+    expect(speech.cancel).toHaveBeenCalledOnce();
+    expect(event.defaultPrevented).toBe(true);
+    expect(runtimeRef.current!.thread.getState().isRunning).toBe(false);
+  });
+});

package/src/primitives/thread/ThreadRoot.tsx

@@ -5,7 +5,9 @@ import {
   type ComponentRef,
   forwardRef,
   type ComponentPropsWithoutRef,
+  useEffect,
 } from "react";
+import { useAui } from "@assistant-ui/store";
 
 export namespace ThreadPrimitiveRoot {
   export type Element = ComponentRef<typeof Primitive.div>;
@@ -22,6 +24,9 @@ export namespace ThreadPrimitiveRoot {
  * This component serves as the foundational wrapper for all thread-related components.
  * It provides the basic structure and context needed for thread functionality.
  *
+ * While this component is mounted, an unhandled Escape keydown stops active speech, even if
+ * the action bar that started it is no longer mounted.
+ *
  * @example
  * ```tsx
  * <ThreadPrimitive.Root>
@@ -37,6 +42,34 @@ export const ThreadPrimitiveRoot = forwardRef<
   ThreadPrimitiveRoot.Element,
   ThreadPrimitiveRoot.Props
 >((props, ref) => {
+  const aui = useAui();
+
+  useEffect(() => {
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key !== "Escape") return;
+      if (event.defaultPrevented || aui.thread.source === null) return;
+      if (aui.thread.getState().speech == null) return;
+      event.preventDefault();
+      try {
+        aui.thread.stopSpeaking();
+      } catch (error) {
+        // getState() is the last rendered snapshot, so speech can finish before this call.
+        if (
+          !(error instanceof Error) ||
+          error.message !== "No message is being spoken"
+        ) {
+          throw error;
+        }
+      }
+    };
+
+    // Bubble phase lets capture-phase Escape handlers consume the event first.
+    document.addEventListener("keydown", handleKeyDown);
+    return () => {
+      document.removeEventListener("keydown", handleKeyDown);
+    };
+  }, [aui]);
+
   return <Primitive.div {...props} ref={ref} />;
 });
 

package/src/primitives/thread/ThreadViewport.tsx

@@ -10,7 +10,7 @@ import {
   useLayoutEffect,
   useMemo,
 } from "react";
-import { useAuiEvent, useAuiState } from "@assistant-ui/store";
+import { useAuiState } from "@assistant-ui/store";
 import { useManagedRef } from "../../utils/hooks/useManagedRef";
 import { useThreadViewportAutoScroll } from "./useThreadViewportAutoScroll";
 import { ThreadPrimitiveViewportProvider } from "../../context/providers/ThreadViewportProvider";
@@ -144,13 +144,6 @@ const useTopAnchorTurn = (enabled: boolean) => {
 
     state.setTopAnchorTurn(activeTurn);
   }, [activeTurn, threadViewportStore]);
-
-  const clearTopAnchorTurn = useCallback(() => {
-    threadViewportStore.getState().setTopAnchorTurn(null);
-  }, [threadViewportStore]);
-
-  useAuiEvent("thread.initialize", clearTopAnchorTurn);
-  useAuiEvent("threadListItem.switchedTo", clearTopAnchorTurn);
 };
 
 const ThreadPrimitiveViewportScrollable = forwardRef<

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

@@ -13,6 +13,7 @@ import {
 import { useEffect, useState, type FC, type PropsWithChildren } from "react";
 import { useAuiState } from "@assistant-ui/store";
 import { AssistantRuntimeProvider } from "../../context";
+import { useThreadViewport } from "../../context/react/ThreadViewportContext";
 import * as MessagePrimitive from "../message";
 import { ThreadPrimitiveMessages } from "./ThreadMessages";
 import { ThreadPrimitiveRoot } from "./ThreadRoot";
@@ -152,6 +153,11 @@ const Message: FC = () => (
   </MessagePrimitive.Root>
 );
 
+const AtBottom: FC = () => {
+  const isAtBottom = useThreadViewport((s) => s.isAtBottom);
+  return <output data-testid="is-at-bottom">{String(isAtBottom)}</output>;
+};
+
 const Thread = ({
   autoScroll,
   scrollToBottomOnInitialize,
@@ -167,6 +173,7 @@ const Thread = ({
       scrollToBottomOnInitialize={scrollToBottomOnInitialize}
     >
       <ThreadPrimitiveMessages components={{ Message }} />
+      <AtBottom />
     </ThreadPrimitiveViewport>
   </ThreadPrimitiveRoot>
 );
@@ -175,6 +182,7 @@ const BottomAnchorThread = () => (
   <ThreadPrimitiveRoot>
     <ThreadPrimitiveViewport data-testid="viewport">
       <ThreadPrimitiveMessages components={{ Message }} />
+      <AtBottom />
     </ThreadPrimitiveViewport>
   </ThreadPrimitiveRoot>
 );
@@ -312,6 +320,147 @@ describe("useThreadViewportAutoScroll", () => {
     scrollToSpy.mockRestore();
   });
 
+  it("keeps following after a content-growth burst undershoots the bottom", async () => {
+    render(
+      <SyncRuntimeProvider>
+        <BottomAnchorThread />
+      </SyncRuntimeProvider>,
+    );
+
+    const viewport = getViewport();
+    await waitFor(() => {
+      expect(screen.getAllByTestId("thread-message")).toHaveLength(
+        messages.length,
+      );
+      expect(viewport.scrollTop).toBe(getMaxScrollTop(viewport));
+    });
+
+    const scrollTopBeforeBurst = viewport.scrollTop;
+    viewportMeasurementOffset += 164;
+    act(() => {
+      viewport.scrollTop = scrollTopBeforeBurst + 106;
+      viewport.dispatchEvent(new Event("scroll"));
+      viewport.dispatchEvent(new Event("scroll"));
+    });
+    expect(viewport.scrollTop).toBeLessThan(getMaxScrollTop(viewport));
+
+    viewportMeasurementOffset += 200;
+    act(notifyResizeObservers);
+
+    expect(viewport.scrollTop).toBe(getMaxScrollTop(viewport));
+    expect(screen.getByTestId("is-at-bottom").textContent).toBe("true");
+  });
+
+  it("keeps following after a pointerdown that does not scroll the viewport", async () => {
+    render(
+      <SyncRuntimeProvider>
+        <BottomAnchorThread />
+      </SyncRuntimeProvider>,
+    );
+
+    const viewport = getViewport();
+    await waitFor(() => {
+      expect(viewport.scrollTop).toBe(getMaxScrollTop(viewport));
+    });
+
+    act(() => {
+      viewport.dispatchEvent(new Event("pointerdown"));
+    });
+    viewportMeasurementOffset += 200;
+    act(notifyResizeObservers);
+
+    expect(viewport.scrollTop).toBe(getMaxScrollTop(viewport));
+    expect(screen.getByTestId("is-at-bottom").textContent).toBe("true");
+  });
+
+  it("cancels a queued bottom scroll when the user scrolls up", async () => {
+    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;
+    });
+    const cancelAnimationFrame = vi.fn((id: number) => {
+      if (pendingFrame?.id === id) pendingFrame = null;
+    });
+    vi.stubGlobal("cancelAnimationFrame", cancelAnimationFrame);
+
+    try {
+      render(
+        <SyncRuntimeProvider>
+          <BottomAnchorThread />
+        </SyncRuntimeProvider>,
+      );
+
+      const viewport = getViewport();
+      await waitFor(() => {
+        expect(screen.getAllByTestId("thread-message")).toHaveLength(
+          messages.length,
+        );
+        expect(pendingFrame).not.toBeNull();
+      });
+
+      let scrollTopAfterLeave = 0;
+      act(() => {
+        viewport.scrollTop = getMaxScrollTop(viewport);
+        viewport.dispatchEvent(new Event("scroll"));
+        viewport.scrollTop -= 80;
+        scrollTopAfterLeave = viewport.scrollTop;
+        viewport.dispatchEvent(new Event("scroll"));
+      });
+
+      const frame = pendingFrame as {
+        id: number;
+        callback: FrameRequestCallback;
+      } | null;
+      if (frame) {
+        act(() => {
+          frame.callback(performance.now());
+        });
+      }
+
+      expect(viewport.scrollTop).toBe(scrollTopAfterLeave);
+      expect(screen.getByTestId("is-at-bottom").textContent).toBe("false");
+      expect(cancelAnimationFrame).toHaveBeenCalledWith(expect.any(Number));
+    } finally {
+      vi.stubGlobal("requestAnimationFrame", originalRequestAnimationFrame);
+      vi.stubGlobal("cancelAnimationFrame", originalCancelAnimationFrame);
+    }
+  });
+
+  it("does not resume bottom follow after a stable-height user scroll-up", async () => {
+    render(
+      <SyncRuntimeProvider>
+        <BottomAnchorThread />
+      </SyncRuntimeProvider>,
+    );
+
+    const viewport = getViewport();
+    await waitFor(() => {
+      expect(viewport.scrollTop).toBe(getMaxScrollTop(viewport));
+    });
+
+    act(() => {
+      viewport.scrollTop = viewport.scrollTop - 80;
+      viewport.dispatchEvent(new Event("scroll"));
+    });
+
+    const scrollTopAfterLeave = viewport.scrollTop;
+    viewportMeasurementOffset += 200;
+    act(notifyResizeObservers);
+
+    expect(viewport.scrollTop).toBe(scrollTopAfterLeave);
+    expect(viewport.scrollTop).toBeLessThan(getMaxScrollTop(viewport));
+    expect(screen.getByTestId("is-at-bottom").textContent).toBe("false");
+  });
+
   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) => {
@@ -401,5 +550,8 @@ describe("useThreadViewportAutoScroll", () => {
     });
 
     expect(getViewport().scrollTop).toBe(0);
+    viewportMeasurementOffset += 200;
+    act(notifyResizeObservers);
+    expect(screen.getByTestId("is-at-bottom").textContent).toBe("false");
   });
 });

package/src/primitives/thread/useThreadViewportAutoScroll.ts

@@ -3,6 +3,7 @@
 import { useComposedRefs } from "@radix-ui/react-compose-refs";
 import { useCallback, useLayoutEffect, useRef, type RefCallback } from "react";
 import { useAuiEvent, useAuiState } from "@assistant-ui/store";
+import { isUserScrollUp } from "@assistant-ui/store/client";
 import { useOnResizeContent } from "../../utils/hooks/useOnResizeContent";
 import { useOnScrollToBottom } from "../../utils/hooks/useOnScrollToBottom";
 import { useManagedRef } from "../../utils/hooks/useManagedRef";
@@ -68,37 +69,36 @@ export const useThreadViewportAutoScroll = <TElement extends HTMLElement>({
   // triggers, cleared when handleScroll confirms we reached bottom, or when the
   // user actively scrolls up while content size is stable.
   const scrollingToBottomBehaviorRef = useRef<ScrollBehavior | null>(null);
+  const followBottomRef = useRef(autoScroll);
 
   const scrollToBottom = useCallback((behavior: ScrollBehavior) => {
     const div = divRef.current;
     if (!div) return;
 
+    followBottomRef.current = true;
     scrollingToBottomBehaviorRef.current = behavior;
     div.scrollTo({ top: div.scrollHeight, behavior });
   }, []);
 
+  const cancelScheduledFrame = useCallback(() => {
+    if (scheduledFrameRef.current === null) return;
+    cancelAnimationFrame(scheduledFrameRef.current);
+    scheduledFrameRef.current = null;
+  }, []);
+
   const scheduleScrollToBottom = useCallback(
     (behavior: ScrollBehavior) => {
       scrollingToBottomBehaviorRef.current = behavior;
-      if (scheduledFrameRef.current !== null) {
-        cancelAnimationFrame(scheduledFrameRef.current);
-      }
+      cancelScheduledFrame();
       scheduledFrameRef.current = requestAnimationFrame(() => {
         scheduledFrameRef.current = null;
         scrollToBottom(behavior);
       });
     },
-    [scrollToBottom],
+    [cancelScheduledFrame, scrollToBottom],
   );
 
-  useLayoutEffect(
-    () => () => {
-      if (scheduledFrameRef.current !== null) {
-        cancelAnimationFrame(scheduledFrameRef.current);
-      }
-    },
-    [],
-  );
+  useLayoutEffect(() => () => cancelScheduledFrame(), [cancelScheduledFrame]);
 
   const hasActiveTopAnchor = useCallback(() => {
     const state = threadViewportStore.getState();
@@ -124,6 +124,14 @@ export const useThreadViewportAutoScroll = <TElement extends HTMLElement>({
       // no-op: a smooth scroll-to-bottom fires many midpoint scroll events
       // before landing, don't flicker isAtBottom or clear intent mid-animation
     } else {
+      const userScrolledUp = isUserScrollUp(
+        {
+          scrollTop: lastScrollTop.current,
+          scrollHeight: lastScrollHeight.current,
+        },
+        div,
+      );
+
       if (newIsAtBottom) {
         // newIsAtBottom is ambiguous when the viewport doesn't overflow —
         // keep intent alive until content can actually scroll
@@ -131,12 +139,11 @@ export const useThreadViewportAutoScroll = <TElement extends HTMLElement>({
         if (viewportOverflows) {
           scrollingToBottomBehaviorRef.current = null;
         }
-      } else if (
-        lastScrollTop.current > div.scrollTop &&
-        lastScrollHeight.current === div.scrollHeight
-      ) {
-        // scrollHeight equality rules out content-driven shifts being misread as user scroll-up
+        if (autoScroll) followBottomRef.current = true;
+      } else if (userScrolledUp) {
+        cancelScheduledFrame();
         scrollingToBottomBehaviorRef.current = null;
+        followBottomRef.current = false;
       }
 
       const shouldUpdate =
@@ -176,7 +183,7 @@ export const useThreadViewportAutoScroll = <TElement extends HTMLElement>({
     } else if (
       autoScroll &&
       !(isRunning && hasActiveTopAnchor()) &&
-      threadViewportStore.getState().isAtBottom
+      followBottomRef.current
     ) {
       scrollToBottom("instant");
     }
@@ -224,7 +231,7 @@ export const useThreadViewportAutoScroll = <TElement extends HTMLElement>({
     scheduleScrollToBottom("auto");
   });
 
-  useAuiEvent("threadListItem.switchedTo", () => {
+  useAuiEvent("threads.selectionChanged", () => {
     if (!scrollToBottomOnThreadSwitch) return;
     scheduleScrollToBottom("instant");
   });