@agents24/chat-react 0.1.3 → 0.1.5

package/README.md

@@ -1,6 +1,6 @@
 # Agents24 Chat React
 
-Last Updated: 2026-06-10
+Last Updated: 2026-06-17
 
 Headless React primitives for Agents24 chat surfaces.
 
@@ -11,6 +11,9 @@ The package owns thread hydration, older-page pagination, stream/reattach state,
 - `useAgents24ChatController(options)`
 - `useLatestThreadViewport(options)`
 - `LatestThreadViewport`
+- `useStreamingText(options)`
+- `getActiveStreamingTextPartId(message, streamingMessageId)`
+- `isActiveStreamingTextPart(message, part, streamingMessageId)`
 - `createFetchChatTransport(options)`
 - `consumeSseResponse(response, onEvent)`
 - normalized chat message, part, transport, and storage types
@@ -19,4 +22,18 @@ The package owns thread hydration, older-page pagination, stream/reattach state,
 
 `ChatMessage.parts` is the only render model. Backend `response_blocks` are normalized into ordered parts such as `text`, `tool-get_meteo`, `ui-blocks`, `reasoning`, `approval`, `error`, and `data`. Tool UI is client-owned through `renderPart`, `toolRenderers`, and `fallbackToolRenderer`; the package does not infer English tool labels or group tool rows.
 
+`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

@@ -31,14 +31,17 @@ __export(index_exports, {
   consumeSseResponse: () => consumeSseResponse,
   createChatId: () => createChatId,
   createFetchChatTransport: () => createFetchChatTransport,
+  getActiveStreamingTextPartId: () => getActiveStreamingTextPartId,
   getLatestScrollTop: () => getLatestScrollTop,
   hasStaleUnfinishedAssistantCache: () => hasStaleUnfinishedAssistantCache,
   hasUnfinishedAssistantMessage: () => hasUnfinishedAssistantMessage,
+  isActiveStreamingTextPart: () => isActiveStreamingTextPart,
   isAtTimelineLatestEdge: () => isAtTimelineLatestEdge,
   isRunningThreadStatus: () => isRunningThreadStatus,
   isScrollable: () => isScrollable,
   latestContextWindowFromThread: () => latestContextWindowFromThread,
   mergeReasoningSteps: () => mergeReasoningSteps,
+  nextLatestFollowStateOnScroll: () => nextLatestFollowStateOnScroll,
   parseSseBlock: () => parseSseBlock,
   partsFromResponseBlocks: () => partsFromResponseBlocks,
   reasoningStepsFromParts: () => reasoningStepsFromParts,
@@ -52,7 +55,8 @@ __export(index_exports, {
   titleFromMessage: () => titleFromMessage,
   toolStateFromStatus: () => toolStateFromStatus,
   useAgents24ChatController: () => useAgents24ChatController,
-  useLatestThreadViewport: () => useLatestThreadViewport
+  useLatestThreadViewport: () => useLatestThreadViewport,
+  useStreamingText: () => useStreamingText
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -1093,6 +1097,140 @@ var consumeSseResponse = async (response, onEvent) => {
   return { threadId, runId };
 };
 
+// src/streaming-text.ts
+var import_react2 = require("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] = (0, import_react2.useState)(() => {
+    const cachedText = cacheAdapter?.get(id);
+    return isStreaming && cachedText !== text ? "" : text;
+  });
+  const targetRef = (0, import_react2.useRef)(text);
+  const displayedRef = (0, import_react2.useRef)(displayedText);
+  const rafRef = (0, import_react2.useRef)(null);
+  const lastFrameAtRef = (0, import_react2.useRef)(null);
+  const idRef = (0, import_react2.useRef)(id);
+  const shouldAnimateRef = (0, import_react2.useRef)(isStreaming);
+  (0, import_react2.useEffect)(() => {
+    if (isStreaming || !text) return;
+    cacheAdapter?.set(id, text);
+  }, [cacheAdapter, id, isStreaming, text]);
+  (0, import_react2.useEffect)(() => {
+    targetRef.current = text;
+  }, [text]);
+  (0, import_react2.useEffect)(() => {
+    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]);
+  (0, import_react2.useEffect)(() => {
+    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 || {},
@@ -1174,7 +1312,7 @@ var createFetchChatTransport = ({
 };
 
 // src/viewport.tsx
-var import_react2 = require("react");
+var import_react3 = require("react");
 var import_jsx_runtime2 = require("react/jsx-runtime");
 var LATEST_EDGE_THRESHOLD_PX = 2;
 var MIN_OLDER_PREFETCH_PX = 320;
@@ -1191,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,
@@ -1200,17 +1346,24 @@ function useLatestThreadViewport({
   shouldAutoFollow = true,
   topOriginMaxItems = 4
 }) {
-  const scrollContainerRef = (0, import_react2.useRef)(null);
-  const olderPagePreserveRef = (0, import_react2.useRef)(null);
-  const olderPageRequestInFlightRef = (0, import_react2.useRef)(false);
-  const intrinsicResizePreserveRef = (0, import_react2.useRef)(null);
-  const autoFollowLatestRef = (0, import_react2.useRef)(true);
-  const programmaticScrollRef = (0, import_react2.useRef)(false);
-  const programmaticScrollTimeoutRef = (0, import_react2.useRef)(null);
-  const activeStreamKeyRef = (0, import_react2.useRef)(null);
-  const [isAtLatest, setIsAtLatest] = (0, import_react2.useState)(true);
+  const scrollContainerRef = (0, import_react3.useRef)(null);
+  const olderPagePreserveRef = (0, import_react3.useRef)(null);
+  const olderPageRequestInFlightRef = (0, import_react3.useRef)(false);
+  const intrinsicResizePreserveRef = (0, import_react3.useRef)(null);
+  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 markProgrammaticScroll = (0, import_react2.useCallback)(() => {
+  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);
     programmaticScrollTimeoutRef.current = setTimeout(() => {
@@ -1218,24 +1371,38 @@ function useLatestThreadViewport({
       programmaticScrollTimeoutRef.current = null;
     }, 80);
   }, []);
-  const scrollToLatest = (0, import_react2.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]);
-  (0, import_react2.useEffect)(() => {
+    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);
       const preserve = intrinsicResizePreserveRef.current;
       if (preserve?.frame !== null && preserve?.frame !== void 0) cancelAnimationFrame(preserve.frame);
     };
   }, []);
-  (0, import_react2.useLayoutEffect)(() => {
+  (0, import_react3.useLayoutEffect)(() => {
     const element = scrollContainerRef.current;
     const preserve = olderPagePreserveRef.current;
     if (!element) return;
+    observedScrollHeightRef.current = element.scrollHeight;
     if (!preserve) {
       setIsAtLatest(isAtTimelineLatestEdge(element, isTopOrigin));
       return;
@@ -1247,12 +1414,18 @@ function useLatestThreadViewport({
     olderPageRequestInFlightRef.current = false;
     setIsAtLatest(isAtTimelineLatestEdge(element, isTopOrigin));
   }, [isTopOrigin, itemCount, markProgrammaticScroll]);
-  const handleScroll = (0, import_react2.useCallback)(
+  const handleScroll = (0, import_react3.useCallback)(
     (event) => {
       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;
       }
@@ -1269,9 +1442,9 @@ function useLatestThreadViewport({
         });
       });
     },
-    [hasOlder, isLoadingOlder, isTopOrigin, onLoadOlder]
+    [hasOlder, isLoadingOlder, isTopOrigin, onLoadOlder, setLatestFollowState]
   );
-  const preserveIntrinsicResize = (0, import_react2.useCallback)(() => {
+  const preserveIntrinsicResize = (0, import_react3.useCallback)(() => {
     const element = scrollContainerRef.current;
     if (!element || isTopOrigin) return;
     const active = intrinsicResizePreserveRef.current;
@@ -1300,37 +1473,60 @@ function useLatestThreadViewport({
     };
     intrinsicResizePreserveRef.current.frame = requestAnimationFrame(preserveFrame);
   }, [isTopOrigin, markProgrammaticScroll]);
-  (0, import_react2.useEffect)(() => {
+  (0, import_react3.useEffect)(() => {
     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]);
-  (0, import_react2.useLayoutEffect)(() => {
-    if (isTopOrigin) return;
-    if (!activeStreamKey || !shouldAutoFollow || !autoFollowLatestRef.current) return;
+  }, [activeStreamKey, scrollToLatest, setLatestFollowState]);
+  (0, import_react3.useLayoutEffect)(() => {
+    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
   };
 }
@@ -1352,13 +1548,16 @@ function LatestThreadViewport({
     onLoadOlder,
     activeStreamKey
   });
-  const timelineItems = (0, import_react2.useMemo)(() => viewport.isTopOrigin ? items : [...items].reverse(), [items, viewport.isTopOrigin]);
+  const timelineItems = (0, import_react3.useMemo)(() => viewport.isTopOrigin ? items : [...items].reverse(), [items, viewport.isTopOrigin]);
   return /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)(
     "div",
     {
       ref: viewport.scrollContainerRef,
       className,
+      onKeyDown: viewport.handleUserScrollIntent,
       onScroll: viewport.handleScroll,
+      onTouchMove: viewport.handleUserScrollIntent,
+      onWheel: viewport.handleUserScrollIntent,
       role: "log",
       style: { overflowAnchor: "none" },
       children: [
@@ -1382,14 +1581,17 @@ function LatestThreadViewport({
   consumeSseResponse,
   createChatId,
   createFetchChatTransport,
+  getActiveStreamingTextPartId,
   getLatestScrollTop,
   hasStaleUnfinishedAssistantCache,
   hasUnfinishedAssistantMessage,
+  isActiveStreamingTextPart,
   isAtTimelineLatestEdge,
   isRunningThreadStatus,
   isScrollable,
   latestContextWindowFromThread,
   mergeReasoningSteps,
+  nextLatestFollowStateOnScroll,
   parseSseBlock,
   partsFromResponseBlocks,
   reasoningStepsFromParts,
@@ -1403,6 +1605,7 @@ function LatestThreadViewport({
   titleFromMessage,
   toolStateFromStatus,
   useAgents24ChatController,
-  useLatestThreadViewport
+  useLatestThreadViewport,
+  useStreamingText
 });
 //# sourceMappingURL=index.cjs.map