@assistant-ui/react 0.12.28 → 0.14.0

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();
+  };
+};

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

@@ -0,0 +1,46 @@
+import { describe, expect, it } from "vitest";
+import {
+  getActiveTopAnchorAnchorId,
+  getActiveTopAnchorTargetId,
+  getActiveTopAnchorTurn,
+} from "./topAnchorTurn";
+
+describe("topAnchorTurn", () => {
+  it("does not activate history-loaded messages", () => {
+    const messages = [
+      { id: "user-1", role: "user" },
+      { id: "assistant-1", role: "assistant" },
+    ];
+
+    expect(getActiveTopAnchorTurn({ isRunning: false, messages })).toBe(null);
+  });
+
+  it("activates the live user/assistant pair while running", () => {
+    const messages = [
+      { id: "assistant-1", role: "assistant" },
+      { id: "user-2", role: "user" },
+      { id: "assistant-2", role: "assistant" },
+    ];
+
+    expect(getActiveTopAnchorTurn({ isRunning: true, messages })).toEqual({
+      anchorId: "user-2",
+      targetId: "assistant-2",
+    });
+    expect(getActiveTopAnchorAnchorId({ isRunning: true, messages })).toBe(
+      "user-2",
+    );
+    expect(getActiveTopAnchorTargetId({ isRunning: true, messages })).toBe(
+      "assistant-2",
+    );
+  });
+
+  it("ignores running states without a trailing user/assistant pair", () => {
+    const messages = [
+      { id: "user-1", role: "user" },
+      { id: "assistant-1", role: "assistant" },
+      { id: "user-2", role: "user" },
+    ];
+
+    expect(getActiveTopAnchorTurn({ isRunning: true, messages })).toBe(null);
+  });
+});

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

@@ -0,0 +1,30 @@
+"use client";
+
+type TopAnchorTurnMessage = {
+  readonly id: string;
+  readonly role: string;
+};
+
+export const getActiveTopAnchorTurn = ({
+  isRunning,
+  messages,
+}: {
+  readonly isRunning: boolean;
+  readonly messages: readonly TopAnchorTurnMessage[];
+}) => {
+  if (!isRunning) return null;
+
+  const target = messages.at(-1);
+  const anchor = messages.at(-2);
+  if (anchor?.role !== "user" || target?.role !== "assistant") return null;
+
+  return { anchorId: anchor.id, targetId: target.id };
+};
+
+export const getActiveTopAnchorAnchorId = (
+  options: Parameters<typeof getActiveTopAnchorTurn>[0],
+) => getActiveTopAnchorTurn(options)?.anchorId;
+
+export const getActiveTopAnchorTargetId = (
+  options: Parameters<typeof getActiveTopAnchorTurn>[0],
+) => getActiveTopAnchorTurn(options)?.targetId;

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

@@ -0,0 +1,58 @@
+"use client";
+
+/**
+ * Convert a supported CSS length string (`px`, `em`, `rem`) into pixels,
+ * resolving font-relative units against the supplied element's computed style.
+ * Unsupported or malformed values disable the tall-message clamp.
+ *
+ * Part of the top-anchor package's public input contract: consumers may pass
+ * clamp configuration as supported CSS-length strings, and this function is the
+ * single place that converts them into the pixel values the package operates on.
+ */
+export const parseCssLength = (value: string, element: HTMLElement): number => {
+  const match = value.trim().match(/^(\d+(?:\.\d+)?|\.\d+)(em|px|rem)$/);
+  if (!match) return Number.POSITIVE_INFINITY;
+
+  const num = Number(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 Number.POSITIVE_INFINITY;
+};
+
+export const getAnchorId = (anchor: HTMLElement) => anchor.dataset.messageId;
+
+export const createReserveElement = () => {
+  const reserve = document.createElement("div");
+  reserve.dataset.auiTopAnchorReserve = "";
+  reserve.style.height = "0px";
+  reserve.style.flexShrink = "0";
+  reserve.style.pointerEvents = "none";
+  reserve.setAttribute("aria-hidden", "true");
+
+  return reserve;
+};
+
+export const setReserveHeight = (reserve: HTMLElement, height: number) => {
+  const nextHeight = `${height}px`;
+  if (reserve.style.height !== nextHeight) {
+    reserve.style.height = nextHeight;
+    return true;
+  }
+
+  return false;
+};
+
+export const snapScrollTop = (top: number) => {
+  const pixelRatio = window.devicePixelRatio || 1;
+  return Math.round(top * pixelRatio) / pixelRatio;
+};

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

@@ -0,0 +1,19 @@
+"use client";
+
+import { useLayoutEffect } from "react";
+import { useThreadViewportStore } from "../../../context/react/ThreadViewportContext";
+import { mountTopAnchorReserve } from "./mountTopAnchorReserve";
+
+/**
+ * Mounts the top-turn-anchor reserve element against the active
+ * `ThreadViewport` store. Call this from inside the scrollable viewport so
+ * the reserve `<div>` is appended next to the streaming assistant message.
+ */
+export const useTopAnchorReserve = (enabled: boolean) => {
+  const threadViewportStore = useThreadViewportStore();
+
+  useLayoutEffect(() => {
+    if (!enabled) return;
+    return mountTopAnchorReserve(threadViewportStore);
+  }, [enabled, threadViewportStore]);
+};

package/src/primitives/thread/useThreadViewportAutoScroll.ts

@@ -70,6 +70,15 @@ export const useThreadViewportAutoScroll = <TElement extends HTMLElement>({
     div.scrollTo({ top: div.scrollHeight, behavior });
   }, []);
 
+  const hasActiveTopAnchor = useCallback(() => {
+    const state = threadViewportStore.getState();
+    return (
+      state.turnAnchor === "top" &&
+      state.element.viewport === divRef.current &&
+      state.element.anchor !== null
+    );
+  }, [threadViewportStore]);
+
   const handleScroll = () => {
     const div = divRef.current;
     if (!div) return;
@@ -101,7 +110,10 @@ export const useThreadViewportAutoScroll = <TElement extends HTMLElement>({
 
   const resizeRef = useOnResizeContent(() => {
     const scrollBehavior = scrollingToBottomBehaviorRef.current;
-    if (scrollBehavior) {
+    if (scrollBehavior && hasActiveTopAnchor()) {
+      // Let the top-anchor reserve own scrolling while a run starts to avoid a bottom-scroll race.
+      scrollingToBottomBehaviorRef.current = null;
+    } else if (scrollBehavior) {
       scrollToBottom(scrollBehavior);
     } else if (autoScroll && threadViewportStore.getState().isAtBottom) {
       scrollToBottom("instant");
@@ -124,6 +136,8 @@ export const useThreadViewportAutoScroll = <TElement extends HTMLElement>({
   // autoscroll on run start
   useAuiEvent("thread.runStart", () => {
     if (!scrollToBottomOnRunStart) return;
+    if (threadViewportStore.getState().turnAnchor === "top") return;
+
     scrollingToBottomBehaviorRef.current = "auto";
     requestAnimationFrame(() => {
       scrollToBottom("auto");

package/src/primitives/thread.ts

@@ -4,7 +4,6 @@ export { ThreadPrimitiveIf as If } from "./thread/ThreadIf";
 export { ThreadPrimitiveViewport as Viewport } from "./thread/ThreadViewport";
 export { ThreadPrimitiveViewportProvider as ViewportProvider } from "../context/providers/ThreadViewportProvider";
 export { ThreadPrimitiveViewportFooter as ViewportFooter } from "./thread/ThreadViewportFooter";
-export { ThreadPrimitiveViewportSlack as ViewportSlack } from "./thread/ThreadViewportSlack";
 export { ThreadPrimitiveMessages as Messages } from "./thread/ThreadMessages";
 export { ThreadPrimitiveMessageByIndex as MessageByIndex } from "./thread/ThreadMessages";
 export { ThreadPrimitiveScrollToBottom as ScrollToBottom } from "./thread/ThreadScrollToBottom";

package/src/primitives/threadList/ThreadListLoadMore.tsx

@@ -0,0 +1,24 @@
+"use client";
+
+import {
+  type ActionButtonElement,
+  type ActionButtonProps,
+  createActionButton,
+} from "../../utils/createActionButton";
+import { useThreadListLoadMore as useThreadListLoadMoreBehavior } from "@assistant-ui/core/react";
+
+const useThreadListLoadMore = () => {
+  const { loadMore, disabled } = useThreadListLoadMoreBehavior();
+  if (disabled) return null;
+  return loadMore;
+};
+
+export namespace ThreadListPrimitiveLoadMore {
+  export type Element = ActionButtonElement;
+  export type Props = ActionButtonProps<typeof useThreadListLoadMore>;
+}
+
+export const ThreadListPrimitiveLoadMore = createActionButton(
+  "ThreadListPrimitive.LoadMore",
+  useThreadListLoadMore,
+);

package/src/primitives/threadList.ts

@@ -1,4 +1,5 @@
 export { ThreadListPrimitiveNew as New } from "./threadList/ThreadListNew";
 export { ThreadListPrimitiveItems as Items } from "./threadList/ThreadListItems";
 export { ThreadListPrimitiveItemByIndex as ItemByIndex } from "./threadList/ThreadListItems";
+export { ThreadListPrimitiveLoadMore as LoadMore } from "./threadList/ThreadListLoadMore";
 export { ThreadListPrimitiveRoot as Root } from "./threadList/ThreadListRoot";

package/src/tests/RemoteThreadListRuntime.adapterProvider.test.tsx

@@ -0,0 +1,138 @@
+// @vitest-environment jsdom
+
+import { act, render, waitFor } from "@testing-library/react";
+import type { FC, PropsWithChildren } from "react";
+import { describe, expect, it } from "vitest";
+import {
+  RuntimeAdapterProvider,
+  useRemoteThreadListRuntime,
+  useRuntimeAdapters,
+} from "@assistant-ui/core/react";
+import { makeAdapter } from "./remote-thread-list-test-helpers";
+import { useLocalRuntime } from "../legacy-runtime/runtime-cores/local/useLocalRuntime";
+import { AssistantRuntimeProvider } from "../context";
+import type { ChatModelAdapter, RemoteThreadListAdapter } from "../index";
+import type {
+  RuntimeAdapters as RuntimeAdaptersShape,
+  ThreadHistoryAdapter,
+} from "@assistant-ui/core";
+
+type CapturedAdapters = RuntimeAdaptersShape | null;
+
+const noOpAdapter: ChatModelAdapter = {
+  async *run() {},
+};
+
+const dummyHistory: ThreadHistoryAdapter = {
+  load: async () => ({ messages: [] }),
+  append: async () => {},
+};
+
+const makeRuntimeHook = (capture: { adapters: CapturedAdapters }) =>
+  function useTestRuntimeHook() {
+    capture.adapters = useRuntimeAdapters();
+    return useLocalRuntime(noOpAdapter);
+  };
+
+async function renderAndWaitForBinder(
+  adapter: RemoteThreadListAdapter,
+  capture: { adapters: CapturedAdapters },
+) {
+  const Inner: FC = () => {
+    const runtime = useRemoteThreadListRuntime({
+      runtimeHook: makeRuntimeHook(capture),
+      adapter,
+    });
+    return (
+      <AssistantRuntimeProvider runtime={runtime}>
+        {null}
+      </AssistantRuntimeProvider>
+    );
+  };
+
+  // first thread instance arrives asynchronously via switchToNewThread.
+  await act(async () => {
+    render(<Inner />);
+  });
+  await waitFor(() => expect(capture.adapters).not.toBeNull());
+}
+
+const wrapInRuntimeAdapterProvider = (
+  history: ThreadHistoryAdapter,
+): FC<PropsWithChildren> =>
+  function Provider({ children }) {
+    return (
+      <RuntimeAdapterProvider adapters={{ history }}>
+        {children}
+      </RuntimeAdapterProvider>
+    );
+  };
+
+describe("RemoteThreadListAdapter.unstable_Provider", () => {
+  it("makes RuntimeAdapterProvider context visible to the runtime hook", async () => {
+    const capture: { adapters: CapturedAdapters } = { adapters: null };
+    const adapter = makeAdapter({
+      unstable_Provider: wrapInRuntimeAdapterProvider(dummyHistory),
+    });
+    await renderAndWaitForBinder(adapter, capture);
+
+    expect(capture.adapters?.history).toBe(dummyHistory);
+  });
+
+  it("preserves modelContext from the outer runtime-core RuntimeAdapterProvider", async () => {
+    const capture: { adapters: CapturedAdapters } = { adapters: null };
+    const adapter = makeAdapter({
+      unstable_Provider: wrapInRuntimeAdapterProvider(dummyHistory),
+    });
+    await renderAndWaitForBinder(adapter, capture);
+
+    expect(capture.adapters?.history).toBe(dummyHistory);
+    expect(capture.adapters?.modelContext).toBeDefined();
+  });
+
+  it("returns no history when no Provider is supplied", async () => {
+    const capture: { adapters: CapturedAdapters } = { adapters: null };
+    const adapter = makeAdapter();
+    await renderAndWaitForBinder(adapter, capture);
+
+    expect(capture.adapters?.history).toBeUndefined();
+  });
+
+  it("picks up a swapped Provider on re-render", async () => {
+    const capture: { adapters: CapturedAdapters } = { adapters: null };
+    const firstHistory: ThreadHistoryAdapter = {
+      load: async () => ({ messages: [] }),
+      append: async () => {},
+    };
+    const secondHistory: ThreadHistoryAdapter = {
+      load: async () => ({ messages: [] }),
+      append: async () => {},
+    };
+
+    const Inner: FC<{ history: ThreadHistoryAdapter }> = ({ history }) => {
+      const adapter = makeAdapter({
+        unstable_Provider: wrapInRuntimeAdapterProvider(history),
+      });
+      const runtime = useRemoteThreadListRuntime({
+        runtimeHook: makeRuntimeHook(capture),
+        adapter,
+      });
+      return (
+        <AssistantRuntimeProvider runtime={runtime}>
+          {null}
+        </AssistantRuntimeProvider>
+      );
+    };
+
+    let result: ReturnType<typeof render>;
+    await act(async () => {
+      result = render(<Inner history={firstHistory} />);
+    });
+    await waitFor(() => expect(capture.adapters?.history).toBe(firstHistory));
+
+    await act(async () => {
+      result!.rerender(<Inner history={secondHistory} />);
+    });
+    await waitFor(() => expect(capture.adapters?.history).toBe(secondHistory));
+  });
+});