@agents24/chat-react 0.1.3 → 0.1.5

package/dist/index.d.ts

@@ -349,6 +349,30 @@ declare const renderChatPart: (part: ChatPart, message: ChatMessage, renderOptio
 declare const parseSseBlock: (block: string) => ChatRuntimeEvent | null;
 declare const consumeSseResponse: (response: Response, onEvent: (event: ChatRuntimeEvent) => void | Promise<void>) => Promise<ChatStreamResult>;
 
+type StreamingTextMode = "streaming" | "static";
+type StreamingTextCache = {
+    get: (id: string) => string | undefined;
+    set: (id: string, text: string) => void;
+};
+type UseStreamingTextOptions = {
+    id: string;
+    isStreaming: boolean;
+    text: string;
+    cache?: StreamingTextCache | false;
+    charsPerSecond?: number;
+    catchupThreshold?: number;
+    maxCatchupChars?: number;
+};
+type UseStreamingTextResult = {
+    displayedText: string;
+    isAnimating: boolean;
+    mode: StreamingTextMode;
+    parseIncompleteMarkdown: boolean;
+};
+declare const getActiveStreamingTextPartId: (message: ChatMessage, streamingMessageId: string | null) => string | null;
+declare const isActiveStreamingTextPart: (message: ChatMessage, part: ChatPart, streamingMessageId: string | null) => boolean;
+declare function useStreamingText({ id, isStreaming, text, cache, charsPerSecond, catchupThreshold, maxCatchupChars, }: UseStreamingTextOptions): UseStreamingTextResult;
+
 type MaybePromise<T> = T | Promise<T>;
 type FetchChatTransportRoutes = {
     listThreads: () => string;
@@ -381,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;
@@ -390,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;
@@ -402,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> = {
@@ -426,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 ToolPresentation, type ToolRenderer, type UseAgents24ChatControllerOptions, type UseLatestThreadViewportOptions, activeRunIdFromThread, activeRunIdFromThreadDetail, assistantTextFromParts, assistantTextFromResponseBlocks, consumeSseResponse, createChatId, createFetchChatTransport, getLatestScrollTop, hasStaleUnfinishedAssistantCache, hasUnfinishedAssistantMessage, isAtTimelineLatestEdge, isRunningThreadStatus, isScrollable, latestContextWindowFromThread, mergeReasoningSteps, parseSseBlock, partsFromResponseBlocks, reasoningStepsFromParts, renderChatPart, shouldPrefetchOlder, shouldUseTopOriginTimeline, textFromFinalOutput, threadActivityDate, threadDetailToMessages, threadPaging, titleFromMessage, toolStateFromStatus, useAgents24ChatController, useLatestThreadViewport };
+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

@@ -1035,6 +1035,140 @@ var consumeSseResponse = async (response, onEvent) => {
   return { threadId, runId };
 };
 
+// src/streaming-text.ts
+import { useEffect as useEffect2, useRef as useRef2, useState as useState2 } from "react";
+var DEFAULT_COMPLETED_TEXT_CACHE_SIZE = 200;
+var defaultCompletedTextCache = /* @__PURE__ */ new Map();
+var defaultStreamingTextCache = {
+  get: (id) => defaultCompletedTextCache.get(id),
+  set: (id, text) => {
+    defaultCompletedTextCache.set(id, text);
+    if (defaultCompletedTextCache.size > DEFAULT_COMPLETED_TEXT_CACHE_SIZE) {
+      const firstKey = defaultCompletedTextCache.keys().next().value;
+      if (firstKey) defaultCompletedTextCache.delete(firstKey);
+    }
+  }
+};
+var getActiveStreamingTextPartId = (message, streamingMessageId) => {
+  if (message.role !== "assistant" || streamingMessageId !== message.id) return null;
+  return message.parts.slice().reverse().find((part) => part.kind === "text")?.id || null;
+};
+var isActiveStreamingTextPart = (message, part, streamingMessageId) => part.kind === "text" && part.id === getActiveStreamingTextPartId(message, streamingMessageId);
+function useStreamingText({
+  id,
+  isStreaming,
+  text,
+  cache = defaultStreamingTextCache,
+  charsPerSecond = 72,
+  catchupThreshold = 40,
+  maxCatchupChars = 20
+}) {
+  const cacheAdapter = cache === false ? null : cache;
+  const [displayedText, setDisplayedText] = useState2(() => {
+    const cachedText = cacheAdapter?.get(id);
+    return isStreaming && cachedText !== text ? "" : text;
+  });
+  const targetRef = useRef2(text);
+  const displayedRef = useRef2(displayedText);
+  const rafRef = useRef2(null);
+  const lastFrameAtRef = useRef2(null);
+  const idRef = useRef2(id);
+  const shouldAnimateRef = useRef2(isStreaming);
+  useEffect2(() => {
+    if (isStreaming || !text) return;
+    cacheAdapter?.set(id, text);
+  }, [cacheAdapter, id, isStreaming, text]);
+  useEffect2(() => {
+    targetRef.current = text;
+  }, [text]);
+  useEffect2(() => {
+    if (idRef.current === id) return;
+    idRef.current = id;
+    const cachedText = cacheAdapter?.get(id);
+    const initial = isStreaming && cachedText !== text ? "" : text;
+    shouldAnimateRef.current = isStreaming && initial !== text;
+    displayedRef.current = initial;
+    setDisplayedText(initial);
+    if (rafRef.current !== null) {
+      cancelAnimationFrame(rafRef.current);
+      rafRef.current = null;
+    }
+    lastFrameAtRef.current = null;
+  }, [cacheAdapter, id, isStreaming, text]);
+  useEffect2(() => {
+    if (typeof window === "undefined") {
+      displayedRef.current = text;
+      setDisplayedText(text);
+      return;
+    }
+    const reduceMotion = typeof window.matchMedia === "function" && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+    if (reduceMotion) {
+      displayedRef.current = text;
+      setDisplayedText(text);
+      shouldAnimateRef.current = false;
+      return;
+    }
+    const cachedText = cacheAdapter?.get(id);
+    if (cachedText === text) {
+      displayedRef.current = text;
+      setDisplayedText(text);
+      shouldAnimateRef.current = false;
+      return;
+    }
+    if (isStreaming) {
+      shouldAnimateRef.current = true;
+    }
+    if (!shouldAnimateRef.current) {
+      displayedRef.current = text;
+      setDisplayedText(text);
+      return;
+    }
+    if (!text.startsWith(displayedRef.current)) {
+      displayedRef.current = "";
+      setDisplayedText("");
+    }
+    const tick = (timestamp) => {
+      const previousTimestamp = lastFrameAtRef.current ?? timestamp;
+      lastFrameAtRef.current = timestamp;
+      const target = targetRef.current;
+      const current = displayedRef.current;
+      if (current.length >= target.length) {
+        shouldAnimateRef.current = false;
+        rafRef.current = null;
+        return;
+      }
+      const elapsedMs = Math.max(8, timestamp - previousTimestamp);
+      const charsFromTime = Math.max(1, Math.floor(elapsedMs / 1e3 * charsPerSecond));
+      const gap = target.length - current.length;
+      const catchupStep = gap > catchupThreshold ? Math.min(maxCatchupChars, Math.ceil(gap / 10)) : charsFromTime;
+      const nextLength = Math.min(
+        target.length,
+        current.length + Math.max(charsFromTime, catchupStep)
+      );
+      const next = target.slice(0, nextLength);
+      displayedRef.current = next;
+      setDisplayedText(next);
+      rafRef.current = window.requestAnimationFrame(tick);
+    };
+    if (rafRef.current === null && displayedRef.current.length < text.length) {
+      rafRef.current = window.requestAnimationFrame(tick);
+    }
+    return () => {
+      if (rafRef.current !== null) {
+        cancelAnimationFrame(rafRef.current);
+        rafRef.current = null;
+      }
+      lastFrameAtRef.current = null;
+    };
+  }, [cacheAdapter, catchupThreshold, charsPerSecond, id, isStreaming, maxCatchupChars, text]);
+  return {
+    displayedText,
+    isAnimating: isStreaming,
+    mode: isStreaming ? "streaming" : "static",
+    parseIncompleteMarkdown: isStreaming
+  };
+}
+
 // src/transport.ts
 var jsonHeaders = (headers) => ({
   ...headers || {},
@@ -1118,11 +1252,11 @@ var createFetchChatTransport = ({
 // src/viewport.tsx
 import {
   useCallback as useCallback2,
-  useEffect as useEffect2,
+  useEffect as useEffect3,
   useLayoutEffect,
   useMemo as useMemo2,
-  useRef as useRef2,
-  useState as useState2
+  useRef as useRef3,
+  useState as useState3
 } from "react";
 import { jsxs as jsxs2 } from "react/jsx-runtime";
 var LATEST_EDGE_THRESHOLD_PX = 2;
@@ -1140,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,
@@ -1149,16 +1291,23 @@ function useLatestThreadViewport({
   shouldAutoFollow = true,
   topOriginMaxItems = 4
 }) {
-  const scrollContainerRef = useRef2(null);
-  const olderPagePreserveRef = useRef2(null);
-  const olderPageRequestInFlightRef = useRef2(false);
-  const intrinsicResizePreserveRef = useRef2(null);
-  const autoFollowLatestRef = useRef2(true);
-  const programmaticScrollRef = useRef2(false);
-  const programmaticScrollTimeoutRef = useRef2(null);
-  const activeStreamKeyRef = useRef2(null);
-  const [isAtLatest, setIsAtLatest] = useState2(true);
+  const scrollContainerRef = useRef3(null);
+  const olderPagePreserveRef = useRef3(null);
+  const olderPageRequestInFlightRef = useRef3(false);
+  const intrinsicResizePreserveRef = useRef3(null);
+  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);
@@ -1167,14 +1316,27 @@ 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]);
-  useEffect2(() => {
+    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);
       const preserve = intrinsicResizePreserveRef.current;
@@ -1185,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;
@@ -1201,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;
       }
@@ -1218,7 +1387,7 @@ function useLatestThreadViewport({
         });
       });
     },
-    [hasOlder, isLoadingOlder, isTopOrigin, onLoadOlder]
+    [hasOlder, isLoadingOlder, isTopOrigin, onLoadOlder, setLatestFollowState]
   );
   const preserveIntrinsicResize = useCallback2(() => {
     const element = scrollContainerRef.current;
@@ -1249,37 +1418,60 @@ function useLatestThreadViewport({
     };
     intrinsicResizePreserveRef.current.frame = requestAnimationFrame(preserveFrame);
   }, [isTopOrigin, markProgrammaticScroll]);
-  useEffect2(() => {
+  useEffect3(() => {
     const key = activeStreamKey || null;
     if (!key || activeStreamKeyRef.current === key) {
       activeStreamKeyRef.current = key;
       return;
     }
-    autoFollowLatestRef.current = true;
-    if (isTopOrigin) {
-      activeStreamKeyRef.current = key;
-      return;
-    }
-    const frame = requestAnimationFrame(scrollToLatest);
+    setLatestFollowState("following");
+    const frame = requestAnimationFrame(() => scrollToLatest());
     activeStreamKeyRef.current = key;
     return () => cancelAnimationFrame(frame);
-  }, [activeStreamKey, isTopOrigin, scrollToLatest]);
+  }, [activeStreamKey, scrollToLatest, setLatestFollowState]);
   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
   };
 }
@@ -1307,7 +1499,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: [
@@ -1330,14 +1525,17 @@ export {
   consumeSseResponse,
   createChatId,
   createFetchChatTransport,
+  getActiveStreamingTextPartId,
   getLatestScrollTop,
   hasStaleUnfinishedAssistantCache,
   hasUnfinishedAssistantMessage,
+  isActiveStreamingTextPart,
   isAtTimelineLatestEdge,
   isRunningThreadStatus,
   isScrollable,
   latestContextWindowFromThread,
   mergeReasoningSteps,
+  nextLatestFollowStateOnScroll,
   parseSseBlock,
   partsFromResponseBlocks,
   reasoningStepsFromParts,
@@ -1351,6 +1549,7 @@ export {
   titleFromMessage,
   toolStateFromStatus,
   useAgents24ChatController,
-  useLatestThreadViewport
+  useLatestThreadViewport,
+  useStreamingText
 };
 //# sourceMappingURL=index.js.map