@agents24/chat-react 0.1.4 → 0.1.6

package/dist/index.d.ts

@@ -405,6 +405,7 @@ type FetchChatTransportOptions = {
 };
 declare const createFetchChatTransport: ({ routes, fetchImpl, headers, streamBody, }: FetchChatTransportOptions) => ChatTransport;
 
+type LatestFollowState = "following" | "detached";
 declare const isScrollable: (element: Pick<HTMLDivElement, "scrollHeight" | "clientHeight">) => boolean;
 declare const isAtTimelineLatestEdge: (element: Pick<HTMLDivElement, "scrollHeight" | "clientHeight" | "scrollTop">, isTopOrigin: boolean) => boolean;
 declare const shouldPrefetchOlder: (element: Pick<HTMLDivElement, "scrollHeight" | "clientHeight" | "scrollTop">) => boolean;
@@ -414,6 +415,11 @@ declare const shouldUseTopOriginTimeline: ({ hasOlder, itemCount, topOriginMaxIt
     itemCount: number;
     topOriginMaxItems?: number;
 }) => boolean;
+declare const nextLatestFollowStateOnScroll: ({ atLatest, current, isProgrammatic, }: {
+    atLatest: boolean;
+    current: LatestFollowState;
+    isProgrammatic: boolean;
+}) => LatestFollowState;
 type UseLatestThreadViewportOptions = {
     itemCount: number;
     hasOlder: boolean;
@@ -426,15 +432,22 @@ type UseLatestThreadViewportOptions = {
 type LatestThreadViewportState = {
     scrollContainerRef: RefObject<HTMLDivElement | null>;
     isAtLatest: boolean;
+    isFollowingLatest: boolean;
     isTopOrigin: boolean;
     shouldShowLatestButton: boolean;
     handleScroll: (event: UIEvent<HTMLDivElement>) => void;
-    scrollToLatest: () => void;
+    handleUserScrollIntent: () => void;
+    scrollToLatest: (options?: {
+        reattach?: boolean;
+    }) => void;
+    detachFromLatest: () => void;
+    reattachToLatest: () => void;
     preserveIntrinsicResize: () => void;
 };
 declare function useLatestThreadViewport({ itemCount, hasOlder, isLoadingOlder, onLoadOlder, activeStreamKey, shouldAutoFollow, topOriginMaxItems, }: UseLatestThreadViewportOptions): LatestThreadViewportState;
 type LatestThreadViewportRenderContext = {
     preserveIntrinsicResize: () => void;
+    isFollowingLatest: boolean;
     isTopOrigin: boolean;
 };
 type LatestThreadViewportProps<T> = {
@@ -450,4 +463,4 @@ type LatestThreadViewportProps<T> = {
 };
 declare function LatestThreadViewport<T>({ items, hasOlder, isLoadingOlder, onLoadOlder, activeStreamKey, className, latestSpacer, trailingSpacer, renderItem, }: LatestThreadViewportProps<T>): react.JSX.Element;
 
-export { type Agents24ChatRenderOptions, type ChatActiveRun, type ChatApprovalPart, type ChatAttachment, type ChatCitation, type ChatContextWindow, type ChatController, type ChatDataPart, type ChatErrorPart, type ChatMessage, type ChatPart, type ChatReasoningPart, type ChatReasoningStep, type ChatRunStatus, type ChatRuntimeEvent, type ChatStorageAdapter, type ChatStreamResult, type ChatTextPart, type ChatThreadDetail, type ChatThreadSummary, type ChatThreadTurn, type ChatToolPart, type ChatToolState, type ChatTransport, type ChatUiBlocksPart, DEFAULT_THREAD_PAGE_SIZE, DefaultChatPart, DefaultToolPart, type FetchChatTransportOptions, type FetchChatTransportRoutes, LatestThreadViewport, type LatestThreadViewportProps, type LatestThreadViewportRenderContext, type LatestThreadViewportState, type StoredChatThread, type StreamingTextCache, type StreamingTextMode, type ToolPresentation, type ToolRenderer, type UseAgents24ChatControllerOptions, type UseLatestThreadViewportOptions, type UseStreamingTextOptions, type UseStreamingTextResult, activeRunIdFromThread, activeRunIdFromThreadDetail, assistantTextFromParts, assistantTextFromResponseBlocks, consumeSseResponse, createChatId, createFetchChatTransport, getActiveStreamingTextPartId, getLatestScrollTop, hasStaleUnfinishedAssistantCache, hasUnfinishedAssistantMessage, isActiveStreamingTextPart, isAtTimelineLatestEdge, isRunningThreadStatus, isScrollable, latestContextWindowFromThread, mergeReasoningSteps, parseSseBlock, partsFromResponseBlocks, reasoningStepsFromParts, renderChatPart, shouldPrefetchOlder, shouldUseTopOriginTimeline, textFromFinalOutput, threadActivityDate, threadDetailToMessages, threadPaging, titleFromMessage, toolStateFromStatus, useAgents24ChatController, useLatestThreadViewport, useStreamingText };
+export { type Agents24ChatRenderOptions, type ChatActiveRun, type ChatApprovalPart, type ChatAttachment, type ChatCitation, type ChatContextWindow, type ChatController, type ChatDataPart, type ChatErrorPart, type ChatMessage, type ChatPart, type ChatReasoningPart, type ChatReasoningStep, type ChatRunStatus, type ChatRuntimeEvent, type ChatStorageAdapter, type ChatStreamResult, type ChatTextPart, type ChatThreadDetail, type ChatThreadSummary, type ChatThreadTurn, type ChatToolPart, type ChatToolState, type ChatTransport, type ChatUiBlocksPart, DEFAULT_THREAD_PAGE_SIZE, DefaultChatPart, DefaultToolPart, type FetchChatTransportOptions, type FetchChatTransportRoutes, type LatestFollowState, LatestThreadViewport, type LatestThreadViewportProps, type LatestThreadViewportRenderContext, type LatestThreadViewportState, type StoredChatThread, type StreamingTextCache, type StreamingTextMode, type ToolPresentation, type ToolRenderer, type UseAgents24ChatControllerOptions, type UseLatestThreadViewportOptions, type UseStreamingTextOptions, type UseStreamingTextResult, activeRunIdFromThread, activeRunIdFromThreadDetail, assistantTextFromParts, assistantTextFromResponseBlocks, consumeSseResponse, createChatId, createFetchChatTransport, getActiveStreamingTextPartId, getLatestScrollTop, hasStaleUnfinishedAssistantCache, hasUnfinishedAssistantMessage, isActiveStreamingTextPart, isAtTimelineLatestEdge, isRunningThreadStatus, isScrollable, latestContextWindowFromThread, mergeReasoningSteps, nextLatestFollowStateOnScroll, parseSseBlock, partsFromResponseBlocks, reasoningStepsFromParts, renderChatPart, shouldPrefetchOlder, shouldUseTopOriginTimeline, textFromFinalOutput, threadActivityDate, threadDetailToMessages, threadPaging, titleFromMessage, toolStateFromStatus, useAgents24ChatController, useLatestThreadViewport, useStreamingText };

package/dist/index.js

@@ -1274,6 +1274,14 @@ var shouldUseTopOriginTimeline = ({
   itemCount,
   topOriginMaxItems = 4
 }) => !hasOlder && itemCount > 0 && itemCount <= topOriginMaxItems;
+var nextLatestFollowStateOnScroll = ({
+  atLatest,
+  current,
+  isProgrammatic
+}) => {
+  if (isProgrammatic) return current;
+  return atLatest ? "following" : "detached";
+};
 function useLatestThreadViewport({
   itemCount,
   hasOlder,
@@ -1287,12 +1295,19 @@ function useLatestThreadViewport({
   const olderPagePreserveRef = useRef3(null);
   const olderPageRequestInFlightRef = useRef3(false);
   const intrinsicResizePreserveRef = useRef3(null);
-  const autoFollowLatestRef = useRef3(true);
+  const followStateRef = useRef3("following");
   const programmaticScrollRef = useRef3(false);
   const programmaticScrollTimeoutRef = useRef3(null);
   const activeStreamKeyRef = useRef3(null);
+  const observedScrollHeightRef = useRef3(null);
   const [isAtLatest, setIsAtLatest] = useState3(true);
+  const [followState, setFollowState] = useState3("following");
   const isTopOrigin = shouldUseTopOriginTimeline({ hasOlder, itemCount, topOriginMaxItems });
+  const setLatestFollowState = useCallback2((next) => {
+    if (followStateRef.current === next) return;
+    followStateRef.current = next;
+    setFollowState(next);
+  }, []);
   const markProgrammaticScroll = useCallback2(() => {
     programmaticScrollRef.current = true;
     if (programmaticScrollTimeoutRef.current) clearTimeout(programmaticScrollTimeoutRef.current);
@@ -1301,13 +1316,26 @@ function useLatestThreadViewport({
       programmaticScrollTimeoutRef.current = null;
     }, 80);
   }, []);
-  const scrollToLatest = useCallback2(() => {
+  const scrollToLatest = useCallback2((options) => {
     const element = scrollContainerRef.current;
     if (!element) return;
+    if (options?.reattach !== false) setLatestFollowState("following");
     markProgrammaticScroll();
     element.scrollTop = getLatestScrollTop(element, isTopOrigin);
     setIsAtLatest(true);
-  }, [isTopOrigin, markProgrammaticScroll]);
+    observedScrollHeightRef.current = element.scrollHeight;
+  }, [isTopOrigin, markProgrammaticScroll, setLatestFollowState]);
+  const detachFromLatest = useCallback2(() => {
+    setLatestFollowState("detached");
+  }, [setLatestFollowState]);
+  const reattachToLatest = useCallback2(() => {
+    scrollToLatest({ reattach: true });
+  }, [scrollToLatest]);
+  const handleUserScrollIntent = useCallback2(() => {
+    const element = scrollContainerRef.current;
+    if (!activeStreamKey || !element) return;
+    if (!isAtTimelineLatestEdge(element, isTopOrigin)) detachFromLatest();
+  }, [activeStreamKey, detachFromLatest, isTopOrigin]);
   useEffect3(() => {
     return () => {
       if (programmaticScrollTimeoutRef.current) clearTimeout(programmaticScrollTimeoutRef.current);
@@ -1319,6 +1347,7 @@ function useLatestThreadViewport({
     const element = scrollContainerRef.current;
     const preserve = olderPagePreserveRef.current;
     if (!element) return;
+    observedScrollHeightRef.current = element.scrollHeight;
     if (!preserve) {
       setIsAtLatest(isAtTimelineLatestEdge(element, isTopOrigin));
       return;
@@ -1335,7 +1364,13 @@ function useLatestThreadViewport({
       const element = event.currentTarget;
       const atLatest = isAtTimelineLatestEdge(element, isTopOrigin);
       setIsAtLatest(atLatest);
-      if (!programmaticScrollRef.current) autoFollowLatestRef.current = atLatest;
+      setLatestFollowState(
+        nextLatestFollowStateOnScroll({
+          atLatest,
+          current: followStateRef.current,
+          isProgrammatic: programmaticScrollRef.current
+        })
+      );
       if (isTopOrigin || !hasOlder || isLoadingOlder || olderPageRequestInFlightRef.current || !shouldPrefetchOlder(element)) {
         return;
       }
@@ -1352,7 +1387,7 @@ function useLatestThreadViewport({
         });
       });
     },
-    [hasOlder, isLoadingOlder, isTopOrigin, onLoadOlder]
+    [hasOlder, isLoadingOlder, isTopOrigin, onLoadOlder, setLatestFollowState]
   );
   const preserveIntrinsicResize = useCallback2(() => {
     const element = scrollContainerRef.current;
@@ -1383,37 +1418,73 @@ function useLatestThreadViewport({
     };
     intrinsicResizePreserveRef.current.frame = requestAnimationFrame(preserveFrame);
   }, [isTopOrigin, markProgrammaticScroll]);
-  useEffect3(() => {
+  useLayoutEffect(() => {
     const key = activeStreamKey || null;
-    if (!key || activeStreamKeyRef.current === key) {
-      activeStreamKeyRef.current = key;
+    const previousKey = activeStreamKeyRef.current;
+    if (!key) {
+      activeStreamKeyRef.current = null;
+      if (previousKey && shouldAutoFollow && followStateRef.current === "following" && !isLoadingOlder && !olderPageRequestInFlightRef.current) {
+        const frame2 = requestAnimationFrame(() => {
+          if (followStateRef.current === "following" && !isLoadingOlder && !olderPageRequestInFlightRef.current) {
+            scrollToLatest({ reattach: false });
+          }
+        });
+        return () => cancelAnimationFrame(frame2);
+      }
       return;
     }
-    autoFollowLatestRef.current = true;
-    if (isTopOrigin) {
+    if (previousKey === key) {
       activeStreamKeyRef.current = key;
       return;
     }
-    const frame = requestAnimationFrame(scrollToLatest);
+    setLatestFollowState("following");
+    const frame = requestAnimationFrame(() => scrollToLatest());
     activeStreamKeyRef.current = key;
     return () => cancelAnimationFrame(frame);
-  }, [activeStreamKey, isTopOrigin, scrollToLatest]);
+  }, [activeStreamKey, isLoadingOlder, scrollToLatest, setLatestFollowState, shouldAutoFollow]);
   useLayoutEffect(() => {
-    if (isTopOrigin) return;
-    if (!activeStreamKey || !shouldAutoFollow || !autoFollowLatestRef.current) return;
+    if (!activeStreamKey || !shouldAutoFollow || followStateRef.current !== "following") return;
     if (isLoadingOlder || olderPageRequestInFlightRef.current) return;
     const frame = requestAnimationFrame(() => {
-      if (autoFollowLatestRef.current && !isLoadingOlder && !olderPageRequestInFlightRef.current) scrollToLatest();
+      if (followStateRef.current === "following" && !isLoadingOlder && !olderPageRequestInFlightRef.current) {
+        scrollToLatest({ reattach: false });
+      }
     });
     return () => cancelAnimationFrame(frame);
-  }, [activeStreamKey, isLoadingOlder, isTopOrigin, itemCount, scrollToLatest, shouldAutoFollow]);
+  }, [activeStreamKey, isLoadingOlder, itemCount, scrollToLatest, shouldAutoFollow]);
+  useEffect3(() => {
+    if (!activeStreamKey) {
+      observedScrollHeightRef.current = scrollContainerRef.current?.scrollHeight ?? null;
+      return;
+    }
+    let frame = null;
+    const watchStreamResize = () => {
+      const element = scrollContainerRef.current;
+      if (!element) return;
+      const previousHeight = observedScrollHeightRef.current;
+      const nextHeight = element.scrollHeight;
+      observedScrollHeightRef.current = nextHeight;
+      if (previousHeight !== null && Math.abs(nextHeight - previousHeight) >= 1 && shouldAutoFollow && followStateRef.current === "following" && !isLoadingOlder && !olderPageRequestInFlightRef.current) {
+        scrollToLatest({ reattach: false });
+      }
+      frame = requestAnimationFrame(watchStreamResize);
+    };
+    frame = requestAnimationFrame(watchStreamResize);
+    return () => {
+      if (frame !== null) cancelAnimationFrame(frame);
+    };
+  }, [activeStreamKey, isLoadingOlder, scrollToLatest, shouldAutoFollow]);
   return {
     scrollContainerRef,
     isAtLatest,
+    isFollowingLatest: followState === "following",
     isTopOrigin,
     shouldShowLatestButton: !isAtLatest,
     handleScroll,
+    handleUserScrollIntent,
     scrollToLatest,
+    detachFromLatest,
+    reattachToLatest,
     preserveIntrinsicResize
   };
 }
@@ -1441,7 +1512,10 @@ function LatestThreadViewport({
     {
       ref: viewport.scrollContainerRef,
       className,
+      onKeyDown: viewport.handleUserScrollIntent,
       onScroll: viewport.handleScroll,
+      onTouchMove: viewport.handleUserScrollIntent,
+      onWheel: viewport.handleUserScrollIntent,
       role: "log",
       style: { overflowAnchor: "none" },
       children: [
@@ -1474,6 +1548,7 @@ export {
   isScrollable,
   latestContextWindowFromThread,
   mergeReasoningSteps,
+  nextLatestFollowStateOnScroll,
   parseSseBlock,
   partsFromResponseBlocks,
   reasoningStepsFromParts,