@agents24/chat-react 0.1.4 → 0.1.5

package/README.md

@@ -1,6 +1,6 @@
 # Agents24 Chat React
 
-Last Updated: 2026-06-14
+Last Updated: 2026-06-17
 
 Headless React primitives for Agents24 chat surfaces.
 
@@ -25,3 +25,15 @@ The package owns thread hydration, older-page pagination, stream/reattach state,
 `useStreamingText` owns reusable visual pacing for active assistant text. It returns `displayedText`, `isAnimating`, `mode`, and `parseIncompleteMarkdown` so host renderers can pass those values into their markdown component without the package depending on any markdown/UI library. The package only chooses text timing, cache behavior, reduced-motion handling, and active text-part helpers.
 
 Network access is always injected by the host. This browser package never requires platform API keys.
+
+## Latest Viewport Behavior
+
+The package owns the standard streaming scroll policy:
+
+- a new active stream starts in latest-follow mode
+- streaming text growth stays pinned to latest while the user remains there
+- user scrolling away detaches latest-follow mode
+- manually reaching latest again, or clicking the latest button, reattaches follow mode
+- older-page prepends preserve the visible viewport instead of snapping to latest
+
+Hosts should wire `handleScroll` and `scrollToLatest` from `useLatestThreadViewport`, or use `LatestThreadViewport` directly. `handleUserScrollIntent` is available for hosts that need to mark wheel, touch, or keyboard intent before a scroll event lands.

package/dist/index.cjs

@@ -41,6 +41,7 @@ __export(index_exports, {
   isScrollable: () => isScrollable,
   latestContextWindowFromThread: () => latestContextWindowFromThread,
   mergeReasoningSteps: () => mergeReasoningSteps,
+  nextLatestFollowStateOnScroll: () => nextLatestFollowStateOnScroll,
   parseSseBlock: () => parseSseBlock,
   partsFromResponseBlocks: () => partsFromResponseBlocks,
   reasoningStepsFromParts: () => reasoningStepsFromParts,
@@ -1328,6 +1329,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,
@@ -1341,12 +1350,19 @@ function useLatestThreadViewport({
   const olderPagePreserveRef = (0, import_react3.useRef)(null);
   const olderPageRequestInFlightRef = (0, import_react3.useRef)(false);
   const intrinsicResizePreserveRef = (0, import_react3.useRef)(null);
-  const autoFollowLatestRef = (0, import_react3.useRef)(true);
+  const followStateRef = (0, import_react3.useRef)("following");
   const programmaticScrollRef = (0, import_react3.useRef)(false);
   const programmaticScrollTimeoutRef = (0, import_react3.useRef)(null);
   const activeStreamKeyRef = (0, import_react3.useRef)(null);
+  const observedScrollHeightRef = (0, import_react3.useRef)(null);
   const [isAtLatest, setIsAtLatest] = (0, import_react3.useState)(true);
+  const [followState, setFollowState] = (0, import_react3.useState)("following");
   const isTopOrigin = shouldUseTopOriginTimeline({ hasOlder, itemCount, topOriginMaxItems });
+  const setLatestFollowState = (0, import_react3.useCallback)((next) => {
+    if (followStateRef.current === next) return;
+    followStateRef.current = next;
+    setFollowState(next);
+  }, []);
   const markProgrammaticScroll = (0, import_react3.useCallback)(() => {
     programmaticScrollRef.current = true;
     if (programmaticScrollTimeoutRef.current) clearTimeout(programmaticScrollTimeoutRef.current);
@@ -1355,13 +1371,26 @@ function useLatestThreadViewport({
       programmaticScrollTimeoutRef.current = null;
     }, 80);
   }, []);
-  const scrollToLatest = (0, import_react3.useCallback)(() => {
+  const scrollToLatest = (0, import_react3.useCallback)((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 = (0, import_react3.useCallback)(() => {
+    setLatestFollowState("detached");
+  }, [setLatestFollowState]);
+  const reattachToLatest = (0, import_react3.useCallback)(() => {
+    scrollToLatest({ reattach: true });
+  }, [scrollToLatest]);
+  const handleUserScrollIntent = (0, import_react3.useCallback)(() => {
+    const element = scrollContainerRef.current;
+    if (!activeStreamKey || !element) return;
+    if (!isAtTimelineLatestEdge(element, isTopOrigin)) detachFromLatest();
+  }, [activeStreamKey, detachFromLatest, isTopOrigin]);
   (0, import_react3.useEffect)(() => {
     return () => {
       if (programmaticScrollTimeoutRef.current) clearTimeout(programmaticScrollTimeoutRef.current);
@@ -1373,6 +1402,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;
@@ -1389,7 +1419,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;
       }
@@ -1406,7 +1442,7 @@ function useLatestThreadViewport({
         });
       });
     },
-    [hasOlder, isLoadingOlder, isTopOrigin, onLoadOlder]
+    [hasOlder, isLoadingOlder, isTopOrigin, onLoadOlder, setLatestFollowState]
   );
   const preserveIntrinsicResize = (0, import_react3.useCallback)(() => {
     const element = scrollContainerRef.current;
@@ -1443,31 +1479,54 @@ function useLatestThreadViewport({
       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]);
   (0, import_react3.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]);
+  (0, import_react3.useEffect)(() => {
+    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
   };
 }
@@ -1495,7 +1554,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: [
@@ -1529,6 +1591,7 @@ function LatestThreadViewport({
   isScrollable,
   latestContextWindowFromThread,
   mergeReasoningSteps,
+  nextLatestFollowStateOnScroll,
   parseSseBlock,
   partsFromResponseBlocks,
   reasoningStepsFromParts,