@agents24/chat-react 0.1.3 → 0.1.4

package/README.md

@@ -1,6 +1,6 @@
 # Agents24 Chat React
 
-Last Updated: 2026-06-10
+Last Updated: 2026-06-14
 
 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,6 @@ 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.

package/dist/index.cjs

@@ -31,9 +31,11 @@ __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,
@@ -52,7 +54,8 @@ __export(index_exports, {
   titleFromMessage: () => titleFromMessage,
   toolStateFromStatus: () => toolStateFromStatus,
   useAgents24ChatController: () => useAgents24ChatController,
-  useLatestThreadViewport: () => useLatestThreadViewport
+  useLatestThreadViewport: () => useLatestThreadViewport,
+  useStreamingText: () => useStreamingText
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -1093,6 +1096,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 +1311,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;
@@ -1200,17 +1337,17 @@ 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 autoFollowLatestRef = (0, import_react3.useRef)(true);
+  const programmaticScrollRef = (0, import_react3.useRef)(false);
+  const programmaticScrollTimeoutRef = (0, import_react3.useRef)(null);
+  const activeStreamKeyRef = (0, import_react3.useRef)(null);
+  const [isAtLatest, setIsAtLatest] = (0, import_react3.useState)(true);
   const isTopOrigin = shouldUseTopOriginTimeline({ hasOlder, itemCount, topOriginMaxItems });
-  const markProgrammaticScroll = (0, import_react2.useCallback)(() => {
+  const markProgrammaticScroll = (0, import_react3.useCallback)(() => {
     programmaticScrollRef.current = true;
     if (programmaticScrollTimeoutRef.current) clearTimeout(programmaticScrollTimeoutRef.current);
     programmaticScrollTimeoutRef.current = setTimeout(() => {
@@ -1218,21 +1355,21 @@ function useLatestThreadViewport({
       programmaticScrollTimeoutRef.current = null;
     }, 80);
   }, []);
-  const scrollToLatest = (0, import_react2.useCallback)(() => {
+  const scrollToLatest = (0, import_react3.useCallback)(() => {
     const element = scrollContainerRef.current;
     if (!element) return;
     markProgrammaticScroll();
     element.scrollTop = getLatestScrollTop(element, isTopOrigin);
     setIsAtLatest(true);
   }, [isTopOrigin, markProgrammaticScroll]);
-  (0, import_react2.useEffect)(() => {
+  (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;
@@ -1247,7 +1384,7 @@ 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);
@@ -1271,7 +1408,7 @@ function useLatestThreadViewport({
     },
     [hasOlder, isLoadingOlder, isTopOrigin, onLoadOlder]
   );
-  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,7 +1437,7 @@ 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;
@@ -1315,7 +1452,7 @@ function useLatestThreadViewport({
     activeStreamKeyRef.current = key;
     return () => cancelAnimationFrame(frame);
   }, [activeStreamKey, isTopOrigin, scrollToLatest]);
-  (0, import_react2.useLayoutEffect)(() => {
+  (0, import_react3.useLayoutEffect)(() => {
     if (isTopOrigin) return;
     if (!activeStreamKey || !shouldAutoFollow || !autoFollowLatestRef.current) return;
     if (isLoadingOlder || olderPageRequestInFlightRef.current) return;
@@ -1352,7 +1489,7 @@ 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",
     {
@@ -1382,9 +1519,11 @@ function LatestThreadViewport({
   consumeSseResponse,
   createChatId,
   createFetchChatTransport,
+  getActiveStreamingTextPartId,
   getLatestScrollTop,
   hasStaleUnfinishedAssistantCache,
   hasUnfinishedAssistantMessage,
+  isActiveStreamingTextPart,
   isAtTimelineLatestEdge,
   isRunningThreadStatus,
   isScrollable,
@@ -1403,6 +1542,7 @@ function LatestThreadViewport({
   titleFromMessage,
   toolStateFromStatus,
   useAgents24ChatController,
-  useLatestThreadViewport
+  useLatestThreadViewport,
+  useStreamingText
 });
 //# sourceMappingURL=index.cjs.map