@blade-hq/agent-react 2610.0.0-beta.67 → 2610.0.0-beta.69

package/README.md

@@ -399,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`、`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`。
+本包自有声明：`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`、`isQueuePanelVisible`。
 
 ## 会话消息队列
 
@@ -407,6 +407,12 @@ blade-chat { --primary: 262 83% 58%; height: 640px; }
 
 自建布局可直接使用 `<SessionQueuePanel>`，属性类型为 `SessionQueuePanelProps`：传 `snapshot`、`canDeliver`、可选的 `pendingItemId`（提交中的条目禁用操作）与 `notice`（冲突/失败说明），以及 `onResume` / `onCancel` / `onEdit` / `onMove` / `onReorder` / `onDeliver` 回调。上移/下移与拖动排序最终都提交当前 pending 条目的完整 id 顺序。冲突时队列由服务端快照刷新，`ChatView` 会把未保存的正文放回输入框，不会静默丢掉用户编辑的内容。
 
+面板比输入框窄一圈、贴在它上方，所以宽度必须跟输入框一致：用可选属性 `contentWidthClassName` 传入输入框内层的宽度类（不传则按本包输入框的 `max-w-[748px]`）。左右内边距同理——默认值对应本包输入框的 `--blade-chat-gutter`；如果你给输入框根节点换了左右 padding（例如改成 `px-10`），必须用 `rootClassName` 在面板根节点重设 `--blade-chat-queue-gutter` 成同一个值，否则面板会跟输入框错开一圈、在两者相接的缝上露出来。
+
+输入框的 `mergesWithPanelAbove` 为 true 时上两角改直角，跟面板拼成一条完整轮廓；否则输入框的上角圆弧会从较窄的面板两侧露出来，形成两个尖角。**这个值要取面板上报的状态，不要在宿主侧用 `isQueuePanelVisible` 复算**：面板有本地编辑态（编辑到一半、那条等待消息被服务端拿走时仍要留在原地保住草稿，见 `detachedEdit`），这时 snapshot 里没有条目、宿主复算会得到 false，输入框就会在面板还显示着的时候把上角恢复成圆角。用 `onVisibleChange` 拿到面板的真实占位状态，再传给输入框或 `ChatSurface` 的 `queuePanelVisible`。本包的 `AgentChat` 已按这条接好，自建布局照做即可。
+
+拼轮廓的前提是两者**真的相邻**。中间夹着别的内容时（本包的 MCP 暂存内容、内置 Web 的 `composerBanner`），面板下两角与输入框上两角都要圆起来——直角是"被对方接住"的表示，露出直角却中间空着一块，看起来像被削掉一角。面板的 `mergesWithInputBelow` 与输入框的 `mergesWithPanelAbove` 要取同一个判据；`ChatSurface` 会用 context 把这一位传给面板，自建布局直接传即可。
+
 `PollingBackoff` 从 agent-client 重导出，供自定义只读轮询计算退避时间；它不发送或重放请求。用法见 [agent-client 轮询说明](../agent-client/README.md#只读轮询退避)。
 
 ### 会话插件

package/dist/components/ChatInput.d.ts

@@ -11,6 +11,13 @@ interface Props {
      * 比明确提示用户等一等更糟。ChatSurface 按 queuePanel 是否存在传入。
      */
     queueWhileRunning?: boolean;
+    /**
+     * 上方紧贴着一个比自己窄的面板（队列面板）时置 true：上两角改直角。
+     *
+     * 面板比输入框窄一圈，输入框上角留圆弧的话，那两段弧会从面板两侧露出来，
+     * 看着就是两个尖角。跟内置 Web 的 ChatInput 是同一个判据。
+     */
+    mergesWithPanelAbove?: boolean;
     placeholder?: string;
     className?: string;
     queueKey?: string;
@@ -21,5 +28,5 @@ interface Props {
  * 不含第一方版本的富文本编辑、@ 补全、技能菜单、语音输入与模型选择。
  * 内容受控，session.attach() / insertText() 通过 ChatView 注入到这里。
  */
-export declare function ChatInput({ value, onValueChange, onSend, onStop, isStreaming, isStopping, queueWhileRunning, placeholder, className, queueKey, hasAttachments, }: Props): import("react/jsx-runtime").JSX.Element;
+export declare function ChatInput({ value, onValueChange, onSend, onStop, isStreaming, isStopping, queueWhileRunning, mergesWithPanelAbove, placeholder, className, queueKey, hasAttachments, }: Props): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/components/ChatSurface.d.ts

@@ -57,6 +57,14 @@ interface ChatSurfaceProps extends ChatPresentationProps {
     beforeInput?: ReactNode;
     /** 输入框上方的会话队列面板（智能体模式用）。不传时不渲染任何节点。 */
     queuePanel?: ReactNode;
+    /**
+     * 队列面板此刻是否真的占位（由面板的 `onVisibleChange` 上报）。
+     *
+     * 不能用 `queuePanel != null` 代替：面板有本地编辑态（编辑到一半、那条等待
+     * 消息被服务端拿走时仍留在原地保住草稿），这时它显示但 snapshot 里没有条目，
+     * 光看节点是否存在判不出来，输入框上两角就会在面板还开着的时候恢复成圆角。
+     */
+    queuePanelVisible?: boolean;
     /** 仅 Agent 模式启用 Blade 的 update_plan 面板。 */
     showPlanUpdates?: boolean;
     /** 仅实时成功的 update_plan 递增；历史 hydration 不得改变。 */
@@ -83,5 +91,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, onRevealingChange, isReplay, }: 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, queuePanelVisible, showPlanUpdates, planRevealRevision, historyPaging, banner, onRevealingChange, isReplay, }: ChatSurfaceProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/components/SessionQueuePanel.d.ts

@@ -15,7 +15,52 @@ export interface SessionQueuePanelProps {
     onMove: (item: QueuedMessage, delta: -1 | 1) => void;
     onReorder: (orderedIds: string[]) => void;
     onDeliver: (item: QueuedMessage) => void;
+    /**
+     * 队列内容与外层留白的宽度类，要和下面输入框用同一个值。
+     *
+     * 队列卡片是"比输入框窄一圈、露在它上方"的形态，所以这里的宽度必须跟着
+     * 输入框走：输入框宽度由调用方决定（内置 Web 默认 max-w-3xl，软件工厂用
+     * `max-w-[748px]!` 覆盖，SDK 侧是 max-w-[748px]）。写死一个值的话，两种
+     * 布局里总有一种对不齐——之前写死 max-w-[748px] 且外层 px-4，而输入框
+     * 外层是 px-5，软件工厂恰好都是 748 看着还行，普通聊天里输入框是 768，
+     * 队列连缩进一起窄了 22px。
+     */
+    contentWidthClassName?: string;
+    /** 根节点附加类。宿主用它在根上重设 `--blade-chat-queue-gutter`（或别的变量）。 */
+    rootClassName?: string;
+    /**
+     * 面板占位状态变化时回调（true = 正在占位）。
+     *
+     * 面板有本地 `editing` 状态：用户编辑到一半、那条等待消息被服务端拿走后，
+     * 面板仍要留在原地保住没保存的正文（见 `detachedEdit`）。这时 `items` 是空的，
+     * 光凭 snapshot 判不出面板还在，宿主就会把输入框上两角恢复成圆角、接缝上露出
+     * 尖角。让面板自己上报，宿主不必也无法复刻这个判据。
+     */
+    onVisibleChange?: (visible: boolean) => void;
+    /**
+     * 面板是否真的紧贴下面的输入框。
+     *
+     * 中间夹着别的内容时（MCP 暂存内容、内置 Web 的 `composerBanner`）两者并不
+     * 相接，这时面板下两角也要圆起来——直角是"被下面的输入框接住"的表示，露出
+     * 直角却下面空着一块，看起来像被削掉一角。
+     *
+     * 不传时读 context（见 `QueuePanelAdjacencyContext`）：面板通常由宿主创建、
+     * 挂进 `ChatSurface`，而"中间有没有内容"是 `ChatSurface` 内部的 state，
+     * 宿主拿不到。内置 Web 自己管布局，直接把值传进来即可。
+     */
+    mergesWithInputBelow?: boolean;
 }
+/**
+ * 队列面板此刻会不会占位。
+ *
+ * 输入框要据此把自己的上两角改成直角：队列贴在它上方、而且比它窄一圈，
+ * 输入框上角若还是 22px 圆弧，那两段弧会从队列两侧露出来，形成两个尖角。
+ *
+ * 抽成一个函数而不是两边各判一次，是为了让"面板可见"和"输入框顶角改直角"
+ * 永远同步——这正是仓库里反复出现的"改了一个入口漏了另一个"。
+ * 传入的 `editing` 是面板自己的本地编辑态，默认 false。
+ */
+export declare function isQueuePanelVisible(snapshot: Pick<SessionQueueSnapshot, "items" | "paused">, notice: string | null | undefined, editing?: boolean): boolean;
 /**
  * 会话消息队列面板：输入框上方的「待执行 · N」区域。
  *
@@ -26,4 +71,4 @@ export interface SessionQueuePanelProps {
  * 纯展示组件，不持有会话状态；能否编辑/删除/补充全部用 agent-client 的判定函数，
  * 不在本包重写一份。拖动与键盘调整最终都由调用方提交完整的 pending id 顺序。
  */
-export declare function SessionQueuePanel({ snapshot, canDeliver, pendingItemId, notice, onResume, onCancel, onEdit, onRequeue, onMove, onReorder, onDeliver, }: SessionQueuePanelProps): JSX.Element | null;
+export declare function SessionQueuePanel({ snapshot, canDeliver, pendingItemId, notice, onResume, onCancel, onEdit, onRequeue, onMove, onReorder, onDeliver, contentWidthClassName, rootClassName, onVisibleChange, mergesWithInputBelow: mergesWithInputBelowProp, }: SessionQueuePanelProps): JSX.Element | null;

package/dist/components/queue-panel-adjacency.d.ts

@@ -0,0 +1 @@
+export declare const QueuePanelAdjacencyContext: import("react").Context<boolean | null>;

package/dist/index.d.ts

@@ -59,7 +59,7 @@ export { McpAppCard } from "./components/McpAppCard";
 export type { McpAppMessage } from "./components/McpAppCard";
 export { SessionMemoryToggle } from "./components/SessionMemoryToggle";
 export type { SessionMemoryToggleProps } from "./components/SessionMemoryToggle";
-export { SessionQueuePanel } from "./components/SessionQueuePanel";
+export { SessionQueuePanel, isQueuePanelVisible } from "./components/SessionQueuePanel";
 export type { SessionQueuePanelProps } from "./components/SessionQueuePanel";
 export { isAgentComputerCommand, isAgentComputerToolCall, classifyAgentComputerLaunchOutcome, } from "./lib/agent-computer-command";
 export type { AgentComputerLaunchOutcome } from "./lib/agent-computer-command";