@assistant-ui/react 0.12.28 → 0.14.2

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,
+  };
+};

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

@@ -0,0 +1,131 @@
+// @vitest-environment jsdom
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  mountTopAnchorReserve,
+  type TopAnchorStore,
+} from "./mountTopAnchorReserve";
+
+class ResizeObserverMock {
+  observe = vi.fn();
+  disconnect = vi.fn();
+}
+
+class MutationObserverMock {
+  observe = vi.fn();
+  disconnect = vi.fn();
+}
+
+const defineReadonlyNumber = (
+  element: HTMLElement,
+  key: "clientHeight" | "scrollHeight" | "offsetHeight" | "offsetTop",
+  value: number,
+) => {
+  Object.defineProperty(element, key, { configurable: true, value });
+};
+
+const makeStore = (state: ReturnType<TopAnchorStore["getState"]>) => {
+  const listeners = new Set<() => void>();
+
+  return {
+    store: {
+      getState: () => state,
+      subscribe: (listener: () => void) => {
+        listeners.add(listener);
+        return () => listeners.delete(listener);
+      },
+    } satisfies TopAnchorStore,
+    setState: (nextState: ReturnType<TopAnchorStore["getState"]>) => {
+      state = nextState;
+      for (const listener of listeners) listener();
+    },
+  };
+};
+
+const numericClamp = { tallerThan: 160, visibleHeight: 96 };
+
+describe("mountTopAnchorReserve", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.stubGlobal("ResizeObserver", ResizeObserverMock);
+    vi.stubGlobal("MutationObserver", MutationObserverMock);
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.unstubAllGlobals();
+    document.body.replaceChildren();
+  });
+
+  it("adds enough stable reserve after the active assistant turn to make the top anchor reachable", () => {
+    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 } = makeStore({
+      turnAnchor: "top",
+      element: { viewport, anchor, target },
+      targetConfig: numericClamp,
+    });
+
+    mountTopAnchorReserve(store);
+    vi.runOnlyPendingTimers();
+
+    const reserve = reserveHost.querySelector(
+      "[data-aui-top-anchor-reserve]",
+    ) as HTMLElement;
+
+    expect(reserve).not.toBe(null);
+    expect(reserve.previousElementSibling).toBe(target);
+    expect(reserve.style.height).toBe("60px");
+  });
+
+  it("does not repeat the smooth top-anchor scroll for the same message", () => {
+    const viewport = document.createElement("div");
+    const anchor = document.createElement("div");
+    const target = document.createElement("div");
+    document.body.append(target);
+
+    defineReadonlyNumber(viewport, "offsetTop", 0);
+    defineReadonlyNumber(viewport, "clientHeight", 400);
+    defineReadonlyNumber(viewport, "scrollHeight", 560);
+    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,
+    });
+
+    mountTopAnchorReserve(store);
+    vi.runOnlyPendingTimers();
+
+    expect(viewport.scrollTo).not.toHaveBeenCalled();
+
+    vi.runOnlyPendingTimers();
+
+    expect(viewport.scrollTo).toHaveBeenCalledTimes(1);
+
+    setState({
+      turnAnchor: "top",
+      element: { viewport, anchor, target },
+      targetConfig: numericClamp,
+    });
+    vi.runOnlyPendingTimers();
+
+    expect(viewport.scrollTo).toHaveBeenCalledTimes(1);
+  });
+});

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

@@ -0,0 +1,127 @@
+"use client";
+
+import {
+  computeTopAnchorReserve,
+  computeTopAnchorTargetScrollTop,
+} from "./computeTopAnchorSlack";
+import { createReserveObservers } from "./createReserveObservers";
+import {
+  createReserveElement,
+  getAnchorId,
+  setReserveHeight,
+  snapScrollTop,
+} from "./topAnchorUtils";
+
+/**
+ * Minimal slice of `ThreadViewportStore` that the top-anchor reserve needs.
+ * Decoupling from the full store keeps `mountTopAnchorReserve` testable in
+ * isolation and re-usable from any consumer that can adapt to this shape.
+ */
+export type TopAnchorStore = {
+  getState(): {
+    turnAnchor: "top" | "bottom";
+    element: {
+      viewport: HTMLElement | null;
+      anchor: HTMLElement | null;
+      target: HTMLElement | null;
+    };
+    targetConfig: {
+      tallerThan: number;
+      visibleHeight: number;
+    } | null;
+  };
+  subscribe(fn: () => void): () => void;
+};
+
+const createFrameScheduler = (fn: () => void) => {
+  let frame: number | null = null;
+
+  return {
+    schedule: () => {
+      if (frame !== null) return;
+      frame = requestAnimationFrame(() => {
+        frame = null;
+        fn();
+      });
+    },
+    cancel: () => {
+      if (frame !== null) {
+        cancelAnimationFrame(frame);
+        frame = null;
+      }
+    },
+  };
+};
+
+export const mountTopAnchorReserve = (store: TopAnchorStore) => {
+  let reserve: HTMLElement | null = null;
+  let lastScrolledAnchorId: string | undefined;
+
+  function apply() {
+    const state = store.getState();
+    const { viewport, anchor, target } = state.element;
+    const clamp = state.targetConfig;
+
+    if (
+      state.turnAnchor !== "top" ||
+      !viewport ||
+      !anchor ||
+      !target ||
+      !clamp
+    ) {
+      observers.disconnect();
+      if (reserve) {
+        setReserveHeight(reserve, 0);
+        reserve.remove();
+      }
+      return;
+    }
+
+    reserve ??= createReserveElement();
+
+    if (
+      reserve.parentElement !== target.parentElement ||
+      reserve.previousElementSibling !== target
+    ) {
+      target.after(reserve);
+    }
+
+    observers.target(viewport, anchor, target);
+
+    const reserveChanged = setReserveHeight(
+      reserve,
+      computeTopAnchorReserve({ viewport, anchor, reserve, ...clamp }),
+    );
+
+    if (reserveChanged) {
+      scheduler.schedule();
+      return;
+    }
+
+    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) lastScrolledAnchorId = anchorId;
+  }
+
+  const scheduler = createFrameScheduler(apply);
+  const observers = createReserveObservers(scheduler.schedule);
+
+  scheduler.schedule();
+  const unsubscribe = store.subscribe(scheduler.schedule);
+
+  return () => {
+    scheduler.cancel();
+    unsubscribe();
+    observers.disconnect();
+    reserve?.remove();
+  };
+};