@assistant-ui/react 0.12.28 → 0.14.0

package/src/primitives/message/MessageRoot.tsx

@@ -5,14 +5,21 @@ import {
   type ComponentRef,
   forwardRef,
   type ComponentPropsWithoutRef,
+  type ForwardedRef,
   useCallback,
 } from "react";
 import { useAui, useAuiState } from "@assistant-ui/store";
 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";
+import {
+  useThreadViewport,
+  useThreadViewportStore,
+} from "../../context/react/ThreadViewportContext";
+import { parseCssLength } from "../thread/topAnchor/topAnchorUtils";
+
+type ThreadViewportStore = NonNullable<
+  ReturnType<typeof useThreadViewportStore>
+>;
 
 const useIsHoveringRef = () => {
   const aui = useAui();
@@ -47,54 +54,126 @@ 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 = useAuiState(
+const useIsTopAnchorUser = () => {
+  const activeAnchorId = useThreadViewport((s) => s.topAnchorTurn?.anchorId);
+  return useAuiState(
     (s) =>
-      turnAnchor === "top" &&
       s.message.role === "user" &&
+      s.message.index > 0 &&
       s.message.index === s.thread.messages.length - 2 &&
-      s.thread.messages.at(-1)?.role === "assistant",
+      s.thread.messages.at(-1)?.role === "assistant" &&
+      (s.message.id === activeAnchorId || s.thread.isRunning),
   );
+};
 
-  const getHeight = useCallback((el: HTMLElement) => el.offsetHeight, []);
+const useIsTopAnchorTarget = () => {
+  const activeTargetId = useThreadViewport((s) => s.topAnchorTurn?.targetId);
+  return useAuiState(
+    (s) =>
+      s.message.isLast &&
+      s.message.role === "assistant" &&
+      s.message.index >= 1 &&
+      s.thread.messages.at(s.message.index - 1)?.role === "user" &&
+      (s.message.id === activeTargetId || s.thread.isRunning),
+  );
+};
 
-  return useSizeHandle(
-    shouldRegisterAsInset ? registerUserHeight : null,
-    getHeight,
+const useTopAnchorUserRef = (
+  active: boolean,
+  threadViewportStore: ThreadViewportStore,
+) => {
+  const callback = useCallback(
+    (el: HTMLElement) => {
+      if (!active) return;
+      return threadViewportStore.getState().registerAnchorElement(el);
+    },
+    [active, threadViewportStore],
   );
+
+  return useManagedRef<HTMLElement>(callback);
+};
+
+const useTopAnchorTargetRef = ({
+  active,
+  threadViewportStore,
+}: {
+  active: boolean;
+  threadViewportStore: ThreadViewportStore;
+}) => {
+  const targetRefCallback = useCallback(
+    (el: HTMLElement) => {
+      if (!active) return;
+      const state = threadViewportStore.getState();
+      const clamp = state.topAnchorMessageClamp;
+
+      return state.registerAnchorTargetElement(el, {
+        tallerThan: parseCssLength(clamp.tallerThan, el),
+        visibleHeight: parseCssLength(clamp.visibleHeight, el),
+      });
+    },
+    [active, threadViewportStore],
+  );
+
+  return useManagedRef<HTMLElement>(targetRefCallback);
 };
 
 export namespace MessagePrimitiveRoot {
   export type Element = ComponentRef<typeof Primitive.div>;
-  /**
-   * Props for the MessagePrimitive.Root component.
-   * Accepts all standard div element props plus optional viewport slack tuning.
-   */
-  export type Props = ComponentPropsWithoutRef<typeof Primitive.div> & {
-    /**
-     * Threshold at which the user message height clamps to the offset.
-     * @default "10em"
-     */
-    fillClampThreshold?: string | undefined;
-    /**
-     * Offset used when clamping large user messages.
-     * @default "6em"
-     */
-    fillClampOffset?: string | undefined;
-  };
+  export type Props = ComponentPropsWithoutRef<typeof Primitive.div>;
 }
 
+type MessagePrimitiveRootInternalProps = MessagePrimitiveRoot.Props & {
+  forwardedRef: ForwardedRef<MessagePrimitiveRoot.Element>;
+};
+
+const MessagePrimitiveRootDefault = ({
+  forwardedRef,
+  ...props
+}: MessagePrimitiveRootInternalProps) => {
+  const isHoveringRef = useIsHoveringRef();
+  const ref = useComposedRefs<HTMLDivElement>(forwardedRef, isHoveringRef);
+  const messageId = useAuiState((s) => s.message.id);
+
+  return <Primitive.div {...props} ref={ref} data-message-id={messageId} />;
+};
+
+const MessagePrimitiveRootTopAnchor = ({
+  forwardedRef,
+  threadViewportStore,
+  ...props
+}: MessagePrimitiveRootInternalProps & {
+  threadViewportStore: ThreadViewportStore;
+}) => {
+  const isHoveringRef = useIsHoveringRef();
+  const isTopAnchorUser = useIsTopAnchorUser();
+  const isTopAnchorTarget = useIsTopAnchorTarget();
+  const topAnchorUserRef = useTopAnchorUserRef(
+    isTopAnchorUser,
+    threadViewportStore,
+  );
+  const topAnchorTargetRef = useTopAnchorTargetRef({
+    active: isTopAnchorTarget,
+    threadViewportStore,
+  });
+  const ref = useComposedRefs<HTMLDivElement>(
+    forwardedRef,
+    isHoveringRef,
+    topAnchorUserRef,
+    topAnchorTargetRef,
+  );
+  const messageId = useAuiState((s) => s.message.id);
+
+  return (
+    <Primitive.div
+      {...props}
+      ref={ref}
+      data-message-id={messageId}
+      data-aui-top-anchor-user={isTopAnchorUser ? "" : undefined}
+      data-aui-top-anchor-target={isTopAnchorTarget ? "" : undefined}
+    />
+  );
+};
+
 /**
  * The root container component for a message.
  *
@@ -102,8 +181,10 @@ 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.
+ * When `turnAnchor="top"` is set on the viewport, this component automatically
+ * registers itself as the top-anchor user message (when it's the previous user
+ * message) or as the top-anchor target (when it's the streaming assistant
+ * response). No additional component is required.
  *
  * @example
  * ```tsx
@@ -119,24 +200,21 @@ export namespace MessagePrimitiveRoot {
 export const MessagePrimitiveRoot = forwardRef<
   MessagePrimitiveRoot.Element,
   MessagePrimitiveRoot.Props
->(({ fillClampThreshold, fillClampOffset, ...props }, forwardRef) => {
-  const isHoveringRef = useIsHoveringRef();
-  const anchorUserMessageRef = useMessageViewportRef();
-  const ref = useComposedRefs<HTMLDivElement>(
-    forwardRef,
-    isHoveringRef,
-    anchorUserMessageRef,
-  );
-  const messageId = useAuiState((s) => s.message.id);
+>((props, forwardedRef) => {
+  const threadViewportStore = useThreadViewportStore();
+  // turnAnchor is initial-only viewport config (see ThreadViewportProvider).
+  const turnAnchor = threadViewportStore.getState().turnAnchor;
 
-  return (
-    <ThreadPrimitiveViewportSlack
-      fillClampThreshold={fillClampThreshold}
-      fillClampOffset={fillClampOffset}
-    >
-      <Primitive.div {...props} ref={ref} data-message-id={messageId} />
-    </ThreadPrimitiveViewportSlack>
-  );
+  if (turnAnchor === "top") {
+    return (
+      <MessagePrimitiveRootTopAnchor
+        {...props}
+        forwardedRef={forwardedRef}
+        threadViewportStore={threadViewportStore}
+      />
+    );
+  }
+  return <MessagePrimitiveRootDefault {...props} forwardedRef={forwardedRef} />;
 });
 
 MessagePrimitiveRoot.displayName = "MessagePrimitive.Root";

package/src/primitives/thread/ThreadViewport.tsx

@@ -7,11 +7,23 @@ import {
   forwardRef,
   type ComponentPropsWithoutRef,
   useCallback,
+  useLayoutEffect,
+  useMemo,
 } from "react";
+import { useAuiEvent, useAuiState } from "@assistant-ui/store";
+import { useManagedRef } from "../../utils/hooks/useManagedRef";
 import { useThreadViewportAutoScroll } from "./useThreadViewportAutoScroll";
 import { ThreadPrimitiveViewportProvider } from "../../context/providers/ThreadViewportProvider";
 import { useSizeHandle } from "../../utils/hooks/useSizeHandle";
-import { useThreadViewport } from "../../context/react/ThreadViewportContext";
+import {
+  useThreadViewport,
+  useThreadViewportStore,
+} from "../../context/react/ThreadViewportContext";
+import { useTopAnchorReserve } from "./topAnchor/useTopAnchorReserve";
+import {
+  getActiveTopAnchorAnchorId,
+  getActiveTopAnchorTargetId,
+} from "./topAnchor/topAnchorTurn";
 
 export namespace ThreadPrimitiveViewport {
   export type Element = ComponentRef<typeof Primitive.div>;
@@ -31,6 +43,26 @@ export namespace ThreadPrimitiveViewport {
      */
     turnAnchor?: "top" | "bottom" | undefined;
 
+    /**
+     * Clamps tall user messages so the assistant response stays in view.
+     *
+     * @default { tallerThan: "10em", visibleHeight: "6em" }
+     */
+    topAnchorMessageClamp?: {
+      /**
+       * Clamp messages taller than this. Supports `px`, `em`, and `rem`.
+       *
+       * @default "10em"
+       */
+      tallerThan?: string;
+      /**
+       * Visible portion of clamped messages. Supports `px`, `em`, and `rem`.
+       *
+       * @default "6em"
+       */
+      visibleHeight?: string;
+    };
+
     /**
      * Whether to scroll to bottom when a new run starts.
      *
@@ -60,6 +92,52 @@ const useViewportSizeRef = () => {
   return useSizeHandle(register, getHeight);
 };
 
+const useViewportElementRef = () => {
+  const registerViewportElement = useThreadViewport(
+    (s) => s.registerViewportElement,
+  );
+
+  return useManagedRef(registerViewportElement);
+};
+
+const useTopAnchorTurn = (enabled: boolean) => {
+  const threadViewportStore = useThreadViewportStore();
+  const activeAnchorId = useAuiState((s) => {
+    if (!enabled) return undefined;
+    return getActiveTopAnchorAnchorId(s.thread);
+  });
+  const activeTargetId = useAuiState((s) => {
+    if (!enabled) return undefined;
+    return getActiveTopAnchorTargetId(s.thread);
+  });
+  const activeTurn = useMemo(() => {
+    if (!activeAnchorId || !activeTargetId) return null;
+    return { anchorId: activeAnchorId, targetId: activeTargetId };
+  }, [activeAnchorId, activeTargetId]);
+
+  useLayoutEffect(() => {
+    if (!activeTurn) return;
+
+    const state = threadViewportStore.getState();
+    const current = state.topAnchorTurn;
+    if (
+      current?.anchorId === activeTurn.anchorId &&
+      current.targetId === activeTurn.targetId
+    ) {
+      return;
+    }
+
+    state.setTopAnchorTurn(activeTurn);
+  }, [activeTurn, threadViewportStore]);
+
+  const clearTopAnchorTurn = useCallback(() => {
+    threadViewportStore.getState().setTopAnchorTurn(null);
+  }, [threadViewportStore]);
+
+  useAuiEvent("thread.initialize", clearTopAnchorTurn);
+  useAuiEvent("threadListItem.switchedTo", clearTopAnchorTurn);
+};
+
 const ThreadPrimitiveViewportScrollable = forwardRef<
   ThreadPrimitiveViewport.Element,
   ThreadPrimitiveViewport.Props
@@ -82,7 +160,18 @@ const ThreadPrimitiveViewportScrollable = forwardRef<
       scrollToBottomOnThreadSwitch,
     });
     const viewportSizeRef = useViewportSizeRef();
-    const ref = useComposedRefs(forwardedRef, autoScrollRef, viewportSizeRef);
+    const viewportElementRef = useViewportElementRef();
+    const threadViewportStore = useThreadViewportStore();
+    const turnAnchor = threadViewportStore.getState().turnAnchor;
+    const topAnchorEnabled = turnAnchor === "top";
+    useTopAnchorTurn(topAnchorEnabled);
+    useTopAnchorReserve(topAnchorEnabled);
+    const ref = useComposedRefs(
+      forwardedRef,
+      autoScrollRef,
+      viewportSizeRef,
+      viewportElementRef,
+    );
 
     return (
       <Primitive.div {...rest} ref={ref}>
@@ -114,9 +203,11 @@ ThreadPrimitiveViewportScrollable.displayName =
 export const ThreadPrimitiveViewport = forwardRef<
   ThreadPrimitiveViewport.Element,
   ThreadPrimitiveViewport.Props
->(({ turnAnchor, ...props }, ref) => {
+>(({ turnAnchor, topAnchorMessageClamp, ...props }, ref) => {
   return (
-    <ThreadPrimitiveViewportProvider options={{ turnAnchor }}>
+    <ThreadPrimitiveViewportProvider
+      options={{ turnAnchor, topAnchorMessageClamp }}
+    >
       <ThreadPrimitiveViewportScrollable {...props} ref={ref} />
     </ThreadPrimitiveViewportProvider>
   );

package/src/primitives/thread/ThreadViewportFooter.tsx

@@ -20,7 +20,8 @@ export namespace ThreadPrimitiveViewportFooter {
  * 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).
+ * so the auto-scroll system can account for any sticky footer overlapping the
+ * message list.
  *
  * Multiple ViewportFooter components can be used - their heights are summed.
  *

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

@@ -0,0 +1,131 @@
+import { describe, expect, it } from "vitest";
+import {
+  computeTopAnchorReserve,
+  computeTopAnchorTargetScrollTop,
+} from "./computeTopAnchorSlack";
+
+const makeElement = ({
+  top = 0,
+  height = 0,
+  scrollTop = 0,
+  scrollHeight = 0,
+  clientHeight = 0,
+  offsetHeight = height,
+  offsetTop = top,
+  offsetParent = null,
+}: {
+  top?: number;
+  height?: number;
+  scrollTop?: number;
+  scrollHeight?: number;
+  clientHeight?: number;
+  offsetHeight?: number;
+  offsetTop?: number;
+  offsetParent?: HTMLElement | null;
+}) =>
+  ({
+    scrollTop,
+    scrollHeight,
+    clientHeight,
+    offsetHeight,
+    offsetTop,
+    offsetParent,
+    getBoundingClientRect: () => ({
+      top,
+      height,
+    }),
+  }) as HTMLElement;
+
+describe("computeTopAnchorTargetScrollTop", () => {
+  it("uses layout offset geometry instead of the anchor's transformed visual position", () => {
+    const viewport = makeElement({ offsetTop: 0 });
+    const anchor = makeElement({
+      top: 160,
+      height: 60,
+      offsetTop: 156,
+      offsetParent: viewport,
+    });
+
+    expect(
+      computeTopAnchorTargetScrollTop({
+        viewport,
+        anchor,
+        tallerThan: 160,
+        visibleHeight: 96,
+      }),
+    ).toBe(156);
+  });
+
+  it("over-scrolls tall anchors so only visibleHeight is visible", () => {
+    const viewport = makeElement({ offsetTop: 0 });
+    const anchor = makeElement({ height: 240, offsetTop: 200 });
+
+    // 240 > 160 threshold => keep 96 visible => over-scroll by 240 - 96 = 144
+    expect(
+      computeTopAnchorTargetScrollTop({
+        viewport,
+        anchor,
+        tallerThan: 160,
+        visibleHeight: 96,
+      }),
+    ).toBe(200 + 144);
+  });
+});
+
+describe("computeTopAnchorReserve", () => {
+  it("reserves only the extra height needed to make the anchor target reachable", () => {
+    const viewport = makeElement({
+      offsetTop: 0,
+      scrollTop: 0,
+      scrollHeight: 560,
+      clientHeight: 400,
+    });
+    const anchor = makeElement({ height: 64, offsetTop: 220 });
+    const reserve = makeElement({ offsetHeight: 0 });
+
+    expect(
+      computeTopAnchorReserve({
+        viewport,
+        anchor,
+        reserve,
+        tallerThan: 160,
+        visibleHeight: 96,
+      }),
+    ).toBe(60);
+  });
+
+  it("shrinks as the response content grows", () => {
+    const anchor = makeElement({ height: 64, offsetTop: 220 });
+    const reserve = makeElement({ offsetHeight: 60 });
+
+    expect(
+      computeTopAnchorReserve({
+        viewport: makeElement({
+          offsetTop: 0,
+          scrollTop: 0,
+          scrollHeight: 620,
+          clientHeight: 400,
+        }),
+        anchor,
+        reserve,
+        tallerThan: 160,
+        visibleHeight: 96,
+      }),
+    ).toBe(60);
+
+    expect(
+      computeTopAnchorReserve({
+        viewport: makeElement({
+          offsetTop: 0,
+          scrollTop: 0,
+          scrollHeight: 680,
+          clientHeight: 400,
+        }),
+        anchor,
+        reserve,
+        tallerThan: 160,
+        visibleHeight: 96,
+      }),
+    ).toBe(0);
+  });
+});

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

@@ -0,0 +1,94 @@
+"use client";
+
+export type ComputeTopAnchorTargetOptions = {
+  viewport: HTMLElement;
+  anchor: HTMLElement;
+  tallerThan: number;
+  visibleHeight: number;
+};
+
+export type ComputeTopAnchorReserveOptions = ComputeTopAnchorTargetOptions & {
+  reserve: HTMLElement;
+};
+
+type ComputeTopAnchorSlackOptions = ComputeTopAnchorTargetOptions & {
+  scrollHeight: number;
+};
+
+const getDocumentOffsetTop = (element: HTMLElement): number => {
+  let top = 0;
+  let current: HTMLElement | null = element;
+
+  while (current) {
+    top += current.offsetTop;
+    current = current.offsetParent as HTMLElement | null;
+  }
+
+  return top;
+};
+
+const getLayoutOffsetTop = (
+  element: HTMLElement,
+  ancestor: HTMLElement,
+): number => {
+  // Use layout geometry, not visual rects, so entrance transforms/animations
+  // on the anchor do not shift the scroll target while they settle.
+  let top = 0;
+  let current: HTMLElement | null = element;
+
+  while (current && current !== ancestor) {
+    top += current.offsetTop;
+    current = current.offsetParent as HTMLElement | null;
+  }
+
+  if (current === ancestor) return top;
+
+  return getDocumentOffsetTop(element) - getDocumentOffsetTop(ancestor);
+};
+
+/**
+ * Compute the scroll position that pins the anchor (last user message) to the
+ * top of the viewport. For tall user messages the anchor is intentionally
+ * over-scrolled so only `visibleHeight` of it remains visible, leaving room
+ * for the assistant message below.
+ *
+ * Depends only on the anchor's offset within the scroll content; never reads
+ * `viewport.scrollHeight` (which is volatile while the assistant message
+ * streams in).
+ */
+export const computeTopAnchorTargetScrollTop = ({
+  viewport,
+  anchor,
+  tallerThan,
+  visibleHeight,
+}: ComputeTopAnchorTargetOptions): number => {
+  const anchorTop = getLayoutOffsetTop(anchor, viewport);
+  const anchorHeight = anchor.offsetHeight;
+  const visibleAnchorHeight =
+    anchorHeight <= tallerThan ? anchorHeight : visibleHeight;
+
+  return anchorTop + Math.max(0, anchorHeight - visibleAnchorHeight);
+};
+
+const computeTopAnchorSlack = ({
+  scrollHeight,
+  ...targetOptions
+}: ComputeTopAnchorSlackOptions): number => {
+  const { viewport } = targetOptions;
+  const targetScrollTop = computeTopAnchorTargetScrollTop(targetOptions);
+  const targetScrollHeight = targetScrollTop + viewport.clientHeight;
+
+  return Math.max(0, targetScrollHeight - scrollHeight);
+};
+
+export const computeTopAnchorReserve = ({
+  viewport,
+  reserve,
+  ...targetOptions
+}: ComputeTopAnchorReserveOptions): number => {
+  return computeTopAnchorSlack({
+    viewport,
+    ...targetOptions,
+    scrollHeight: viewport.scrollHeight - reserve.offsetHeight,
+  });
+};

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

@@ -0,0 +1,50 @@
+"use client";
+
+export const createReserveObservers = (onChange: () => void) => {
+  const resizeObserver = new ResizeObserver(onChange);
+  const mutationObserver = new MutationObserver(onChange);
+
+  let observedViewport: HTMLElement | null = null;
+  let observedAnchor: HTMLElement | null = null;
+  let observedTarget: HTMLElement | null = null;
+
+  const disconnect = () => {
+    resizeObserver.disconnect();
+    mutationObserver.disconnect();
+    observedViewport = null;
+    observedAnchor = null;
+    observedTarget = null;
+  };
+
+  return {
+    target: (
+      viewport: HTMLElement,
+      anchor: HTMLElement,
+      target: HTMLElement,
+    ) => {
+      if (
+        observedViewport === viewport &&
+        observedAnchor === anchor &&
+        observedTarget === target
+      ) {
+        return;
+      }
+
+      disconnect();
+
+      resizeObserver.observe(viewport);
+      resizeObserver.observe(anchor);
+      resizeObserver.observe(target);
+      mutationObserver.observe(target, {
+        childList: true,
+        subtree: true,
+        characterData: true,
+      });
+
+      observedViewport = viewport;
+      observedAnchor = anchor;
+      observedTarget = target;
+    },
+    disconnect,
+  };
+};