@assistant-ui/react 0.11.41 → 0.11.44

package/src/primitives/message/MessageRoot.tsx

@@ -9,7 +9,10 @@ import {
 } from "react";
 import { useAssistantApi, useAssistantState } from "../../context";
 import { useManagedRef } from "../../utils/hooks/useManagedRef";
+import { useSizeHandle } from "../../utils/hooks/useSizeHandle";
 import { useComposedRefs } from "@radix-ui/react-compose-refs";
+import { useThreadViewport } from "../../context/react/ThreadViewportContext";
+import { ThreadPrimitiveViewportSlack } from "../thread/ThreadViewportSlack";
 
 const useIsHoveringRef = () => {
   const api = useAssistantApi();
@@ -41,6 +44,34 @@ const useIsHoveringRef = () => {
   return useManagedRef(callbackRef);
 };
 
+/**
+ * Hook that registers the anchor user message as a content inset.
+ * Only registers if: user message, at index messages.length-2, and last message is assistant.
+ */
+const useMessageViewportRef = () => {
+  const turnAnchor = useThreadViewport((s) => s.turnAnchor);
+  const registerUserHeight = useThreadViewport(
+    (s) => s.registerUserMessageHeight,
+  );
+
+  // inset rules:
+  // - the previous user message before the last assistant message registers its full height
+  const shouldRegisterAsInset = useAssistantState(
+    ({ thread, message }) =>
+      turnAnchor === "top" &&
+      message.role === "user" &&
+      message.index === thread.messages.length - 2 &&
+      thread.messages.at(-1)?.role === "assistant",
+  );
+
+  const getHeight = useCallback((el: HTMLElement) => el.offsetHeight, []);
+
+  return useSizeHandle(
+    shouldRegisterAsInset ? registerUserHeight : null,
+    getHeight,
+  );
+};
+
 export namespace MessagePrimitiveRoot {
   export type Element = ComponentRef<typeof Primitive.div>;
   /**
@@ -57,6 +88,9 @@ export namespace MessagePrimitiveRoot {
  * hover state management for the message. It automatically tracks when the user
  * is hovering over the message, which can be used by child components like action bars.
  *
+ * When `turnAnchor="top"` is set on the viewport, this component
+ * registers itself as the scroll anchor if it's the last user message.
+ *
  * @example
  * ```tsx
  * <MessagePrimitive.Root>
@@ -73,9 +107,18 @@ export const MessagePrimitiveRoot = forwardRef<
   MessagePrimitiveRoot.Props
 >((props, forwardRef) => {
   const isHoveringRef = useIsHoveringRef();
-  const ref = useComposedRefs<HTMLDivElement>(forwardRef, isHoveringRef);
+  const anchorUserMessageRef = useMessageViewportRef();
+  const ref = useComposedRefs<HTMLDivElement>(
+    forwardRef,
+    isHoveringRef,
+    anchorUserMessageRef,
+  );
 
-  return <Primitive.div {...props} ref={ref} />;
+  return (
+    <ThreadPrimitiveViewportSlack>
+      <Primitive.div {...props} ref={ref} />
+    </ThreadPrimitiveViewportSlack>
+  );
 });
 
 MessagePrimitiveRoot.displayName = "MessagePrimitive.Root";

package/src/primitives/thread/ThreadScrollToBottom.tsx

@@ -11,14 +11,22 @@ import {
   useThreadViewportStore,
 } from "../../context/react/ThreadViewportContext";
 
-const useThreadScrollToBottom = () => {
+export namespace useThreadScrollToBottom {
+  export type Options = {
+    behavior?: ScrollBehavior | undefined;
+  };
+}
+
+const useThreadScrollToBottom = ({
+  behavior,
+}: useThreadScrollToBottom.Options = {}) => {
   const isAtBottom = useThreadViewport((s) => s.isAtBottom);
 
   const threadViewportStore = useThreadViewportStore();
 
   const handleScrollToBottom = useCallback(() => {
-    threadViewportStore.getState().scrollToBottom();
-  }, [threadViewportStore]);
+    threadViewportStore.getState().scrollToBottom({ behavior });
+  }, [threadViewportStore, behavior]);
 
   if (isAtBottom) return null;
   return handleScrollToBottom;
@@ -32,4 +40,5 @@ export namespace ThreadPrimitiveScrollToBottom {
 export const ThreadPrimitiveScrollToBottom = createActionButton(
   "ThreadPrimitive.ScrollToBottom",
   useThreadScrollToBottom,
+  ["behavior"],
 );

package/src/primitives/thread/ThreadViewport.tsx

@@ -2,9 +2,16 @@
 
 import { useComposedRefs } from "@radix-ui/react-compose-refs";
 import { Primitive } from "@radix-ui/react-primitive";
-import { type ComponentRef, forwardRef, ComponentPropsWithoutRef } from "react";
+import {
+  type ComponentRef,
+  forwardRef,
+  ComponentPropsWithoutRef,
+  useCallback,
+} from "react";
 import { useThreadViewportAutoScroll } from "./useThreadViewportAutoScroll";
-import { ThreadViewportProvider } from "../../context/providers/ThreadViewportProvider";
+import { ThreadPrimitiveViewportProvider } from "../../context/providers/ThreadViewportProvider";
+import { useSizeHandle } from "../../utils/hooks/useSizeHandle";
+import { useThreadViewport } from "../../context/react/ThreadViewportContext";
 
 export namespace ThreadPrimitiveViewport {
   export type Element = ComponentRef<typeof Primitive.div>;
@@ -12,12 +19,31 @@ export namespace ThreadPrimitiveViewport {
     /**
      * Whether to automatically scroll to the bottom when new messages are added.
      * When enabled, the viewport will automatically scroll to show the latest content.
-     * @default true
+     *
+     * Default false if `turnAnchor` is "top", otherwise defaults to true.
      */
     autoScroll?: boolean | undefined;
+
+    /**
+     * Controls scroll anchoring behavior for new messages.
+     * - "bottom" (default): Messages anchor at the bottom, classic chat behavior.
+     * - "top": New user messages anchor at the top of the viewport for a focused reading experience.
+     */
+    turnAnchor?: "top" | "bottom" | undefined;
   };
 }
 
+const useViewportSizeRef = () => {
+  const register = useThreadViewport((s) => s.registerViewport);
+  const getHeight = useCallback(
+    (el: HTMLElement) =>
+      el.clientHeight - parseFloat(getComputedStyle(el).paddingTop),
+    [],
+  );
+
+  return useSizeHandle(register, getHeight);
+};
+
 const ThreadPrimitiveViewportScrollable = forwardRef<
   ThreadPrimitiveViewport.Element,
   ThreadPrimitiveViewport.Props
@@ -25,8 +51,8 @@ const ThreadPrimitiveViewportScrollable = forwardRef<
   const autoScrollRef = useThreadViewportAutoScroll<HTMLDivElement>({
     autoScroll,
   });
-
-  const ref = useComposedRefs(forwardedRef, autoScrollRef);
+  const viewportSizeRef = useViewportSizeRef();
+  const ref = useComposedRefs(forwardedRef, autoScrollRef, viewportSizeRef);
 
   return (
     <Primitive.div {...rest} ref={ref}>
@@ -47,7 +73,7 @@ ThreadPrimitiveViewportScrollable.displayName =
  *
  * @example
  * ```tsx
- * <ThreadPrimitive.Viewport autoScroll={true}>
+ * <ThreadPrimitive.Viewport turnAnchor="top">
  *   <ThreadPrimitive.Messages components={{ Message: MyMessage }} />
  * </ThreadPrimitive.Viewport>
  * ```
@@ -55,11 +81,11 @@ ThreadPrimitiveViewportScrollable.displayName =
 export const ThreadPrimitiveViewport = forwardRef<
   ThreadPrimitiveViewport.Element,
   ThreadPrimitiveViewport.Props
->((props, ref) => {
+>(({ turnAnchor, ...props }, ref) => {
   return (
-    <ThreadViewportProvider>
+    <ThreadPrimitiveViewportProvider options={{ turnAnchor }}>
       <ThreadPrimitiveViewportScrollable {...props} ref={ref} />
-    </ThreadViewportProvider>
+    </ThreadPrimitiveViewportProvider>
   );
 });
 

package/src/primitives/thread/ThreadViewportFooter.tsx

@@ -0,0 +1,57 @@
+"use client";
+
+import { useComposedRefs } from "@radix-ui/react-compose-refs";
+import { Primitive } from "@radix-ui/react-primitive";
+import {
+  type ComponentRef,
+  forwardRef,
+  ComponentPropsWithoutRef,
+  useCallback,
+} from "react";
+import { useSizeHandle } from "../../utils/hooks/useSizeHandle";
+import { useThreadViewport } from "../../context/react/ThreadViewportContext";
+
+export namespace ThreadPrimitiveViewportFooter {
+  export type Element = ComponentRef<typeof Primitive.div>;
+  export type Props = ComponentPropsWithoutRef<typeof Primitive.div>;
+}
+
+/**
+ * A footer container that measures its height for scroll calculations.
+ *
+ * This component measures its height and provides it to the viewport context
+ * for use in scroll calculations (e.g., ViewportSlack min-height).
+ *
+ * Multiple ViewportFooter components can be used - their heights are summed.
+ *
+ * Typically used with `className="sticky bottom-0"` to keep the footer
+ * visible at the bottom of the viewport while scrolling.
+ *
+ * @example
+ * ```tsx
+ * <ThreadPrimitive.Viewport>
+ *   <ThreadPrimitive.Messages components={{ ... }} />
+ *   <ThreadPrimitive.ViewportFooter className="sticky bottom-0">
+ *     <Composer />
+ *   </ThreadPrimitive.ViewportFooter>
+ * </ThreadPrimitive.Viewport>
+ * ```
+ */
+export const ThreadPrimitiveViewportFooter = forwardRef<
+  ThreadPrimitiveViewportFooter.Element,
+  ThreadPrimitiveViewportFooter.Props
+>((props, forwardedRef) => {
+  const register = useThreadViewport((s) => s.registerContentInset);
+  const getHeight = useCallback((el: HTMLElement) => {
+    const marginTop = parseFloat(getComputedStyle(el).marginTop) || 0;
+    return el.offsetHeight + marginTop;
+  }, []);
+
+  const resizeRef = useSizeHandle(register, getHeight);
+
+  const ref = useComposedRefs(forwardedRef, resizeRef);
+
+  return <Primitive.div {...props} ref={ref} />;
+});
+
+ThreadPrimitiveViewportFooter.displayName = "ThreadPrimitive.ViewportFooter";

package/src/primitives/thread/ThreadViewportSlack.tsx

@@ -0,0 +1,109 @@
+"use client";
+
+import { Slot } from "@radix-ui/react-slot";
+import {
+  createContext,
+  type FC,
+  type ReactNode,
+  useCallback,
+  useContext,
+} from "react";
+import { useThreadViewportStore } from "../../context/react/ThreadViewportContext";
+import { useAssistantState } from "../../context";
+import { useManagedRef } from "../../utils/hooks/useManagedRef";
+
+const SlackNestingContext = createContext(false);
+
+const parseCssLength = (value: string, element: HTMLElement): number => {
+  const match = value.match(/^([\d.]+)(em|px|rem)$/);
+  if (!match) return 0;
+
+  const num = parseFloat(match[1]!);
+  const unit = match[2];
+
+  if (unit === "px") return num;
+  if (unit === "em") {
+    const fontSize = parseFloat(getComputedStyle(element).fontSize) || 16;
+    return num * fontSize;
+  }
+  if (unit === "rem") {
+    const rootFontSize =
+      parseFloat(getComputedStyle(document.documentElement).fontSize) || 16;
+    return num * rootFontSize;
+  }
+  return 0;
+};
+
+export type ThreadViewportSlackProps = {
+  /** Threshold at which the user message height clamps to the offset */
+  fillClampThreshold?: string;
+  /** Offset used when clamping large user messages */
+  fillClampOffset?: string;
+  children: ReactNode;
+};
+
+/**
+ * A slot component that provides minimum height to enable scroll anchoring.
+ *
+ * When using `turnAnchor="top"`, this component ensures there is
+ * enough scroll room below the anchor point (last user message) for it to scroll
+ * to the top of the viewport. The min-height is applied only to the last
+ * assistant message.
+ *
+ * This component is used internally by MessagePrimitive.Root.
+ */
+export const ThreadPrimitiveViewportSlack: FC<ThreadViewportSlackProps> = ({
+  children,
+  fillClampThreshold = "10em",
+  fillClampOffset = "6em",
+}) => {
+  const isLast = useAssistantState(({ message }) => message.isLast);
+  const threadViewportStore = useThreadViewportStore({ optional: true });
+  const isNested = useContext(SlackNestingContext);
+
+  const callback = useCallback(
+    (el: HTMLElement) => {
+      if (!threadViewportStore || isNested) return;
+
+      const updateMinHeight = () => {
+        const state = threadViewportStore.getState();
+        if (state.turnAnchor === "top" && isLast) {
+          const { viewport, inset, userMessage } = state.height;
+          const threshold = parseCssLength(fillClampThreshold, el);
+          const offset = parseCssLength(fillClampOffset, el);
+          const clampAdjustment =
+            userMessage <= threshold ? userMessage : offset;
+
+          const minHeight = Math.max(0, viewport - inset - clampAdjustment);
+          el.style.minHeight = `${minHeight}px`;
+          el.style.flexShrink = "0";
+          el.style.transition = "min-height 0s";
+        } else {
+          el.style.minHeight = "";
+          el.style.flexShrink = "";
+          el.style.transition = "";
+        }
+      };
+
+      updateMinHeight();
+      return threadViewportStore.subscribe(updateMinHeight);
+    },
+    [
+      threadViewportStore,
+      isLast,
+      isNested,
+      fillClampThreshold,
+      fillClampOffset,
+    ],
+  );
+
+  const ref = useManagedRef<HTMLElement>(callback);
+
+  return (
+    <SlackNestingContext.Provider value={true}>
+      <Slot ref={ref}>{children}</Slot>
+    </SlackNestingContext.Provider>
+  );
+};
+
+ThreadPrimitiveViewportSlack.displayName = "ThreadPrimitive.ViewportSlack";

package/src/primitives/thread/index.ts

@@ -2,6 +2,9 @@ export { ThreadPrimitiveRoot as Root } from "./ThreadRoot";
 export { ThreadPrimitiveEmpty as Empty } from "./ThreadEmpty";
 export { ThreadPrimitiveIf as If } from "./ThreadIf";
 export { ThreadPrimitiveViewport as Viewport } from "./ThreadViewport";
+export { ThreadPrimitiveViewportProvider as ViewportProvider } from "../../context/providers/ThreadViewportProvider";
+export { ThreadPrimitiveViewportFooter as ViewportFooter } from "./ThreadViewportFooter";
+export { ThreadPrimitiveViewportSlack as ViewportSlack } from "./ThreadViewportSlack";
 export { ThreadPrimitiveMessages as Messages } from "./ThreadMessages";
 export { ThreadPrimitiveMessageByIndex as MessageByIndex } from "./ThreadMessages";
 export { ThreadPrimitiveScrollToBottom as ScrollToBottom } from "./ThreadScrollToBottom";

package/src/primitives/thread/useThreadViewportAutoScroll.tsx

@@ -11,28 +11,38 @@ import { useThreadViewportStore } from "../../context/react/ThreadViewportContex
 
 export namespace useThreadViewportAutoScroll {
   export type Options = {
+    /**
+     * Whether to automatically scroll to the bottom when new messages are added.
+     * When enabled, the viewport will automatically scroll to show the latest content.
+     *
+     * Default false if `turnAnchor` is "top", otherwise defaults to true.
+     */
     autoScroll?: boolean | undefined;
   };
 }
 
 export const useThreadViewportAutoScroll = <TElement extends HTMLElement>({
-  autoScroll = true,
+  autoScroll,
 }: useThreadViewportAutoScroll.Options): RefCallback<TElement> => {
   const divRef = useRef<TElement>(null);
 
   const threadViewportStore = useThreadViewportStore();
+  if (autoScroll === undefined) {
+    autoScroll = threadViewportStore.getState().turnAnchor !== "top";
+  }
 
   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
-  const isScrollingToBottomRef = useRef(false);
+  // stores the scroll behavior to reuse during content resize, or null if not scrolling
+  const scrollingToBottomBehaviorRef = useRef<ScrollBehavior | null>(null);
 
   const scrollToBottom = useCallback((behavior: ScrollBehavior) => {
     const div = divRef.current;
     if (!div) return;
 
-    isScrollingToBottomRef.current = true;
+    scrollingToBottomBehaviorRef.current = behavior;
     div.scrollTo({ top: div.scrollHeight, behavior });
   }, []);
 
@@ -49,7 +59,7 @@ export const useThreadViewportAutoScroll = <TElement extends HTMLElement>({
       // ignore scroll down
     } else {
       if (newIsAtBottom) {
-        isScrollingToBottomRef.current = false;
+        scrollingToBottomBehaviorRef.current = null;
       }
 
       if (newIsAtBottom !== isAtBottom) {
@@ -63,11 +73,10 @@ export const useThreadViewportAutoScroll = <TElement extends HTMLElement>({
   };
 
   const resizeRef = useOnResizeContent(() => {
-    if (
-      autoScroll &&
-      (isScrollingToBottomRef.current ||
-        threadViewportStore.getState().isAtBottom)
-    ) {
+    const scrollBehavior = scrollingToBottomBehaviorRef.current;
+    if (scrollBehavior) {
+      scrollToBottom(scrollBehavior);
+    } else if (autoScroll && threadViewportStore.getState().isAtBottom) {
       scrollToBottom("instant");
     }
 
@@ -81,13 +90,16 @@ export const useThreadViewportAutoScroll = <TElement extends HTMLElement>({
     };
   });
 
-  useOnScrollToBottom(() => {
-    scrollToBottom("auto");
+  useOnScrollToBottom(({ behavior }) => {
+    scrollToBottom(behavior);
   });
 
   // autoscroll on run start
   useAssistantEvent("thread.run-start", () => {
-    if (autoScroll) scrollToBottom("auto");
+    scrollingToBottomBehaviorRef.current = "auto";
+    requestAnimationFrame(() => {
+      scrollToBottom("auto");
+    });
   });
 
   const autoScrollRef = useComposedRefs<TElement>(resizeRef, scrollRef, divRef);

package/src/utils/hooks/useOnScrollToBottom.tsx

@@ -4,7 +4,9 @@ import { useCallbackRef } from "@radix-ui/react-use-callback-ref";
 import { useEffect } from "react";
 import { useThreadViewport } from "../../context/react/ThreadViewportContext";
 
-export const useOnScrollToBottom = (callback: () => void) => {
+export const useOnScrollToBottom = (
+  callback: (config: { behavior: ScrollBehavior }) => void,
+) => {
   const callbackRef = useCallbackRef(callback);
   const onScrollToBottom = useThreadViewport((vp) => vp.onScrollToBottom);
 

package/src/utils/hooks/useSizeHandle.ts

@@ -0,0 +1,43 @@
+"use client";
+
+import { useCallback } from "react";
+import { useManagedRef } from "./useManagedRef";
+import type { SizeHandle } from "../../context/stores/ThreadViewport";
+
+/**
+ * Hook that creates a ref for tracking element size via a SizeHandle.
+ * Automatically sets up ResizeObserver and reports height changes.
+ *
+ * @param register - Function that returns a SizeHandle (e.g., registerContentInset)
+ * @param getHeight - Optional function to compute height (defaults to el.offsetHeight)
+ * @returns A ref callback to attach to the element
+ */
+export const useSizeHandle = (
+  register: (() => SizeHandle) | null | undefined,
+  getHeight?: (el: HTMLElement) => number,
+) => {
+  const callbackRef = useCallback(
+    (el: HTMLElement) => {
+      if (!register) return;
+
+      const sizeHandle = register();
+
+      const updateHeight = () => {
+        const height = getHeight ? getHeight(el) : el.offsetHeight;
+        sizeHandle.setHeight(height);
+      };
+
+      const ro = new ResizeObserver(updateHeight);
+      ro.observe(el);
+      updateHeight();
+
+      return () => {
+        ro.disconnect();
+        sizeHandle.unregister();
+      };
+    },
+    [register, getHeight],
+  );
+
+  return useManagedRef(callbackRef);
+};

package/src/utils/tap-store/derived-scopes.ts

@@ -10,7 +10,8 @@ import type {
   AssistantEventCallback,
   AssistantEventSelector,
 } from "../../types/EventTypes";
-import type { ResourceElement, Unsubscribe } from "@assistant-ui/tap";
+import type { ResourceElement } from "@assistant-ui/tap";
+import { Unsubscribe } from "../../types";
 
 /**
  * Extract the API return type from an AssistantApiField

package/src/utils/tap-store/store.ts

@@ -4,8 +4,8 @@ import {
   ResourceElement,
   resource,
   createResource,
-  Unsubscribe,
 } from "@assistant-ui/tap";
+import { Unsubscribe } from "../../types";
 
 export interface Store<TState> {
   /**