@blade-hq/agent-react 2610.0.0-beta.64 → 2610.0.0-beta.66

package/README.md

@@ -380,6 +380,10 @@ blade-chat { --primary: 262 83% 58%; height: 640px; }
 
 `ChatView`、`AgentChat` 和 `LlmChat` 已经处理好用户发言顶置，不用额外配置。自建消息列表时可用 `useMessagePin` 复用同一套触发、补白、视口 resize 和手动滚动接管逻辑；调用方只需提供滚动容器、目标消息与 spacer 的读写函数。完整参数见 [public-api.md](./public-api.md#usemessagepin-function)。
 
+## 打字机式显示节流
+
+`ChatView`、`AgentChat` 和 `LlmChat` 已经内置这套节流，不用额外配置。服务端到达速率天然不均匀（一次推 5 个字、一次推 20 个字），直接原样渲染会显得忽快忽慢；`useTypewriterReveal(targetText, isLive, resetKey)` 按估算到达速度、留一个很小的固定滞后量匀速播放，返回 `{ displayedText, isRevealing, flushNow }`——自建消息列表时可以直接复用。`isLive` 传 `false`（历史加载 / 回放）时永远整段直接显示；`resetKey`（比如消息的 `entry_id`）变化时播放状态从头开始；`flushNow()` 用于用户点了停止时立即整段显示已到达内容。完整参数见 [public-api.md](./public-api.md#usetypewriterreveal-function)。
+
 ## 纯静态 HTML / Vue？
 
 不需要本包——用后端托管的单文件产物 `<script src=".../sdk/blade-agent.js">` + `<blade-chat>` 自定义元素，行为与 `ChatView` 一致；详见 agent-client README 与接入文档。
@@ -395,7 +399,7 @@ blade-chat { --primary: 262 83% 58%; height: 640px; }
 
 为方便单包引入，本包 re-export 了 agent-client 的全部公开声明（`BladeClient`、`AgentSession`、`SessionState`、协议类型等），文档一律见 [agent-client 的 README](../agent-client/README.md)。完整签名见 [public-api.md](./public-api.md)。
 
-本包自有声明：`BladeProvider`、`BladeProviderProps`、`useBladeClient`、`useAgentSession`、`UseAgentSessionOptions`、`UseAgentSessionResult`、`useMessagePin`、`UseMessagePinOptions`、`useReplay`、`UseReplayResult`、`ReplayMismatch`、`ReplayBar`、`ReplayBarProps`、`ReplayMismatchPrompt`、`ReplayMismatchPromptProps`、`ChatView`、`ChatViewProps`、`ChatViewClassNames`、`ChatViewRenderers`、`ChatViewSlots`、`FollowupInteractionEvent`、`ToolCallRenderer`、`CurrentPlanPanel`、`PlanUpdateBlock`、`PlanUpdateData`、`PlanUpdateDisplayState`、`PlanStepStatus`、`getPlanUpdateDisplayState`、`isPlanUpdateTool`、`parsePlanUpdate`、`pickCurrentPlanStep`、`PLAN_AUTO_COLLAPSE_MS`、`MarkdownContent`、`MarkdownContentProps`、`parseWhatIfPrompt`、`ParsedWhatIfPrompt`、`WhatIfQuote`、`WhatIfUserBubble`、`WhatIfUserBubbleProps`、`SessionQueuePanel`、`SessionQueuePanelProps`。
+本包自有声明：`BladeProvider`、`BladeProviderProps`、`useBladeClient`、`useAgentSession`、`UseAgentSessionOptions`、`UseAgentSessionResult`、`useMessagePin`、`UseMessagePinOptions`、`useTypewriterReveal`、`UseTypewriterRevealResult`、`useReplay`、`UseReplayResult`、`ReplayMismatch`、`ReplayBar`、`ReplayBarProps`、`ReplayMismatchPrompt`、`ReplayMismatchPromptProps`、`ChatView`、`ChatViewProps`、`ChatViewClassNames`、`ChatViewRenderers`、`ChatViewSlots`、`FollowupInteractionEvent`、`ToolCallRenderer`、`CurrentPlanPanel`、`PlanUpdateBlock`、`PlanUpdateData`、`PlanUpdateDisplayState`、`PlanStepStatus`、`getPlanUpdateDisplayState`、`isPlanUpdateTool`、`parsePlanUpdate`、`pickCurrentPlanStep`、`PLAN_AUTO_COLLAPSE_MS`、`MarkdownContent`、`MarkdownContentProps`、`parseWhatIfPrompt`、`ParsedWhatIfPrompt`、`WhatIfQuote`、`WhatIfUserBubble`、`WhatIfUserBubbleProps`、`SessionQueuePanel`、`SessionQueuePanelProps`。
 
 ## 会话消息队列
 

package/dist/components/ChatSurface.d.ts

@@ -69,6 +69,13 @@ interface ChatSurfaceProps extends ChatPresentationProps {
     };
     /** 连接状态条下方的横幅（回放模式条用）。不传时不渲染任何节点。 */
     banner?: ReactNode;
+    /**
+     * 打字机式显示节流是否还没追平目标全文——调用方需要跟 isStreaming 做
+     * `||` 判断输入框"运行中"状态。
+     */
+    onRevealingChange?: (revealing: boolean) => void;
+    /** 是否正在回放（演示 / 彩排）而非真正的实时直播——透传给 MessageList。 */
+    isReplay?: boolean;
 }
 /**
  * 消息流 + 输入框：智能体模式与纯 LLM 模式共用同一套外观，差别只在谁喂数据。
@@ -76,5 +83,5 @@ interface ChatSurfaceProps extends ChatPresentationProps {
  * 这里的 DOM 结构受 tests/chat-view-compat.test.tsx 的快照保护——接入方拿
  * .blade-chat-* 类名写了自己的样式，结构一动他们的页面就歪。
  */
-export declare function ChatSurface({ theme, classNames, renderers, slots, placeholder, connection, errorMessage, messages, postChatFollowup, isStreaming, isStopping, inputText, onInputChange, onSuggestion, onSend, onStop, sessionStatus, askAnswers, onAnswer, sessionId, isViewer, resultFeedbackByEntry, onResultFeedbackSaved, onFollowupInteraction, beforeInput, queuePanel, showPlanUpdates, planRevealRevision, historyPaging, banner, }: ChatSurfaceProps): import("react/jsx-runtime").JSX.Element;
+export declare function ChatSurface({ theme, classNames, renderers, slots, placeholder, connection, errorMessage, messages, postChatFollowup, isStreaming, isStopping, inputText, onInputChange, onSuggestion, onSend, onStop, sessionStatus, askAnswers, onAnswer, sessionId, isViewer, resultFeedbackByEntry, onResultFeedbackSaved, onFollowupInteraction, beforeInput, queuePanel, showPlanUpdates, planRevealRevision, historyPaging, banner, onRevealingChange, isReplay, }: ChatSurfaceProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/components/MessageList.d.ts

@@ -26,10 +26,28 @@ interface Props {
         /** Resolves true only when the paging cursor advanced. */
         loadOlder: (beforeCommit?: () => void) => Promise<boolean>;
     };
+    /**
+     * 用户点了停止（还没等服务端确认）——打字机式显示节流要在这一刻立刻整段
+     * 显示已到达内容，不能等 chat:stop 的服务端回包才响应。跟 isStreaming
+     * 翻转成 false 不是一回事：那个信号来得晚，点击到服务端确认之间有一段
+     * 网络往返，这段时间里节流动画不该继续播。
+     */
+    isStopping?: boolean;
+    /**
+     * 打字机式显示节流是否还没追平目标全文——调用方需要跟 isStreaming 做
+     * `||` 判断输入框"运行中"状态，否则输入框会先于文字播完就翻回可输入。
+     */
+    onRevealingChange?: (revealing: boolean) => void;
+    /**
+     * 是否正在回放（演示 / 彩排）而非真正的实时直播——回放期间即使内容在
+     * 增长也不进入打字机式节流，直接整段显示：这是"流式与历史必须产生相同
+     * 结果"这条硬规则的一部分，节流只在真正的实时直播里生效。
+     */
+    isReplay?: boolean;
 }
 /**
  * 消息列表：use-stick-to-bottom 自动滚动 + 按轮次分组渲染。
  * 相比第一方版本去掉了轮次导航栏、吸顶状态条与规划摘要卡片。
  */
-export declare function MessageList({ messages, postChatFollowup, onSuggestion, isStreaming, sessionStatus, askAnswers, onAnswer, toolCallRenderer, hidePlanUpdateTools, emptyState, className, sessionId, isViewer, onFollowupInteraction, resultFeedbackByEntry, onResultFeedbackSaved, historyPaging, }: Props): import("react/jsx-runtime").JSX.Element;
+export declare function MessageList({ messages, postChatFollowup, onSuggestion, isStreaming, sessionStatus, askAnswers, onAnswer, toolCallRenderer, hidePlanUpdateTools, emptyState, className, sessionId, isViewer, onFollowupInteraction, resultFeedbackByEntry, onResultFeedbackSaved, historyPaging, isStopping, onRevealingChange, isReplay, }: Props): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/hooks/use-typewriter-reveal.d.ts

@@ -0,0 +1,32 @@
+export interface UseTypewriterRevealResult {
+    /** 当前应该渲染的文字——被截断到"已显示长度"，不是目标全文。 */
+    displayedText: string;
+    /** 缓冲池是否还没追平目标全文；跟 isStreaming 做 || 判断输入框状态用。 */
+    isRevealing: boolean;
+    /**
+     * 立即把 displayedText 设成当前目标全文、取消播放循环——用户主动点了
+     * 停止，或者这一路因为中断/出错结束时调用。到达的内容不能丢，只是不再
+     * 需要"看起来在打字"这个动画效果。
+     */
+    flushNow: () => void;
+}
+/**
+ * 打字机式显示节流：服务端到达速率天然不均匀（一次推 5 个字、一次推 20
+ * 个字），直接原样渲染会显得忽快忽慢。按估算到达速度、留一个很小的固定
+ * 滞后量匀速播放 targetText。
+ *
+ * 纯渲染层的本地播放状态，不触碰 AgentSession/chat-store 的任何内部状态——
+ * 调用方从各自现有的、没有改动过的数据里取 targetText，这里只负责"这一帧
+ * 该显示到第几个字"。
+ *
+ * @param targetText 当前已到达的完整（未截断）文本。
+ * @param isLive 是否是真正的实时直播（不是历史加载 / rewind / replay）——
+ *   非直播场景永远整段直接显示，这是"流式与历史必须产生相同结果"这条硬
+ *   规则唯一允许的例外，只在真正的实时直播里生效。
+ * @param resetKey 标识"这是哪一段正在增长的内容"（比如 turn_id 或者
+ *   `${turnId}:${blockIndex}`）——变化时说明换了一段全新的内容（比如上一个
+ *   block 已经交付完、轮到下一个 block 在长，或者切到了新的一轮），播放
+ *   状态要重新从头开始，不能带着上一段的进度继续，否则会出现"从上一段的
+ *   长度往下掉"这种回退闪烁。
+ */
+export declare function useTypewriterReveal(targetText: string, isLive: boolean, resetKey: string | null): UseTypewriterRevealResult;

package/dist/index.d.ts

@@ -7,6 +7,8 @@ export type { ReplayMismatch, UseReplayResult } from "./hooks/use-replay";
 export { useLlmChat } from "./hooks/use-llm-chat";
 export { useMessagePin } from "./hooks/use-message-pin";
 export type { UseMessagePinOptions } from "./hooks/use-message-pin";
+export { useTypewriterReveal } from "./hooks/use-typewriter-reveal";
+export type { UseTypewriterRevealResult } from "./hooks/use-typewriter-reveal";
 export type { ChatCompletionTool, LlmChatOptions, LlmToolCall, UseLlmChatResult, } from "./hooks/use-llm-chat";
 export { ChatView } from "./components/ChatView";
 export type { ChatViewClassNames, ChatViewProps, ChatViewRenderers, ChatViewSlots, FollowupInteractionEvent, } from "./components/ChatView";