Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
import { scrollRangeIntoView } from '@/lib/scrollRangeIntoView';
import { historyAfter } from './historyAfter';
import { readMailCard } from '@cindy/maker-shared/ghost-card-form';
import { animateFocusScroll } from './animateFocusScroll';
import { simplifyBotRenderItems } from '@/features/bots/botConversationPresentation';
import { isVisibleVoiceCallMessage } from '@/features/bots/voice/voiceCallPresentation';
import { MessageViewport, type MessageViewportApi } from './MessageViewport';
import { PAGE_TEXT_NAVIGATION_EVENT } from '@/lib/pageTextAccess';
export { simplifyBotRenderItems } from '@/features/bots/botConversationPresentation';
import { placeBotTaskCardsAfterIntroduction } from '@cindy/maker-shared/botCollaboration';
import { describeToolUse, sourcePathCandidatesFromDescriptor } from '@cindy/maker-shared/tool-use-descriptor';
/**
* MessageStream
* ---------------------------------------------------------------------------
* Vertically scrolling message list with auto-scroll-to-bottom.
*
* F-MSG-1: Message stream container
* - Messages listed top-to-bottom, gap 14px (v2 — F10 halved from 28px)
* - Content area max-width 880px, centered
* - Auto-scroll to bottom on new messages, unless user scrolled up
*
* cc-agent-compact-blocks v2 (F8 / F9): tool_use messages between text
* segments collapse into a single AgentActionsBlock — default collapsed,
* per-block expand state remembered in-memory (not persisted; lost on
* app restart) via useExpandedBlockMemory. Streaming no longer
* auto-expands; the user opens blocks manually if they want to peek live.
* F-SYNC-2: Scroll-to-top pagination with position preservation.
*/
import {
memo,
useCallback,
useEffect,
useLayoutEffect,
useMemo,
useRef,
useState,
useSyncExternalStore,
type CSSProperties,
type ReactNode,
} from 'react';
import {
HistoryViewHandoff,
type HistoryViewController,
type HistoryViewSnapshot,
renderHistoryView,
historyPrefetchThreshold,
historyViewLeaves,
historyWorkSummaries,
} from '@cindy/maker-shared/message-window';
import {
getRemoteHistoryView,
makerChatStore,
type HistoryChatMessage,
} from '@/lib/makerChatStore';
import { isCindyMakeCompletionMessage, isCindyMakePreparationMessage } from '@/lib/cindyMakeComposer';
import { getDataOwnerGeneration } from '@/contexts/dataOwnerGeneration';
import { createPortal, flushSync } from 'react-dom';
import { GitFork } from 'lucide-react';
import { SelectionQuoteButton } from './SelectionQuoteButton';
import {
groupWorkRuns,
isCompletedAssistantMessage,
messageTs,
renderItemStartMs,
type RenderItem,
type WorkChildItem,
type WorkGroupChildItem,
type ToolSegmentRenderItem,
type AgentTaskRenderItem,
type ForkOriginRenderItem,
} from './messageWorkGroups';
export { groupWorkRuns } from './messageWorkGroups';
export type { RenderItem, WorkChildItem } from './messageWorkGroups';
import { useTranslation } from 'react-i18next';
import {
findMessageTodoInsertions,
getLatestMessageTodoState,
isAgentPlanToolName,
isPlanUserBoundary,
isSubagentParentToolUseId,
} from '@cindy/maker-shared/message-render';
import {
extractCachedRenderedMarkdownImageTargets,
extractRenderedMarkdownImageTargets,
type MarkdownImageTargetCache,
} from './markdownImageTargets';
// 子代理卡判据只能有一份:此前桌面自带一份只认 Agent/Task/collab:* 的副本,新增 harness
// (PI 的 subagent)加进共享判据也到不了 AgentTaskCard,会静默落进普通工具组(codex review)。
import {
isAgentTaskToolName,
lookupSubagentRunStatus,
type SubagentRunStatusIndex,
} from '@cindy/maker-shared/agent-task';
import type {
AgentTaskUpdate,
ChatMessage,
ContinuationInFlightProjectionCapability,
} from '@/hooks/useCCAgentChat';
import { findLastUserInputClientId, isAutoResumeRowInFlight } from '@/lib/autoResumePresentation';
import { InputHandoffRecordRow, readInputHandoffRecordData } from '@/features/input-handoff/InputHandoffRecordRow';
export { findLastUserInputClientId, isAutoResumeRowInFlight } from '@/lib/autoResumePresentation';
import { Spinner } from '@/components/ui/spinner';
import { useMessageNavRailPreference } from '@/hooks/useMessageNavRailPreference';
import { HISTORY_GAP_SPLIT_MS } from '@/lib/historyGap';
import { projectRemoteUsers } from '@/lib/remoteUserHandoff';
import { resolveToolFilePath, type KnownLocalFileRef } from '@/lib/localPathResolver';
import type { GeneratedFileRef } from '@/lib/generatedFiles';
import { collectCachedGeneratedFiles } from './generatedFilesProjection';
import {
createMessageMetadataProjection,
createRenderItemMetadataProjection,
createStreamingMessageProjection,
createStreamingWorkGroupProjection,
} from './streamingMessageProjection';
import { useTurnChangeSets } from './useTurnChangeSets';
import {
canCompensateMessageHeight,
findRenderItemElement,
rememberedItemIntrinsicSize,
viewportAnchorCorrection,
} from './messageViewportCompensation';
import { isEditableKeyboardTarget } from '@/lib/editableKeyboardTarget';
import { createLogger } from '@/lib/logger';
import { subscribeWorkLouderCodexAction } from '@/lib/workLouderCodexActions';
import { joystickScrollDelta } from '../../../shared/workLouderCodexScroll';
import { stopAllMedia } from '@/lib/mediaPlaybackBus';
import { basename, cn } from '@/lib/utils';
import {
readSessionScroll,
saveSessionScroll,
type SessionScrollSnapshot,
} from '@/lib/sessionScrollStore';
import {
SHARE_EXCLUDE_ATTR,
SHARE_MESSAGE_ATTR,
SHARE_SESSION_ATTR,
} from '@/lib/shareConversationImage';
import { ShareMessageCheckbox } from './ShareMessageCheckbox';
import {
isShareableMessage,
isShareableToolMedia,
useShareSelectionActive,
} from './shareSelectionStore';
import {
parsePluginInstanceId,
pluginInstallStoragePart,
pluginNewInstallRelId,
pluginStoragePart,
} from '../../../shared/pluginIdentity';
import { isValidGhostId } from '../../../shared/ghost';
import { isValidPluginNamespace } from '@cindy/plugin-protocol';
// perf-baseline: 大 session 切换 first-paint 性能基线,保留用于回归监测。
// 历史:commit ffff3603 (render-window 首引入) 因 687 条 session first-paint
// 80–300ms 卡顿引入临时探针;render-window 重构到 item 轴后(本次)转正成常驻
// 基线日志 — 任何动 MessageStream 渲染路径的改动可直接对比 `stream:first-paint
// elapsed=` 字段做回归判定。日志级 debug:DevTools 默认级别下不显示(归 Verbose),
// dev 的文件日志(main 侧 dev 默认 trace)仍落盘可查。仅 DEV 打点:生产构建里
// logToMain 照样走 IPC 再被 main 按级别丢弃,每次切换白付两次 IPC。无 PII。
const perfLog = createLogger('perf/session-switch');
// jump-down chip 静止隐藏时长 — 用户向下滚动停止后多久淡出。2s 是用户要求,
// 与 prev-msg-jump 的 IDLE_HIDE_MS=3000 区分(向上 chip 显示更长方便回看,
// 向下 chip 是快捷跳转 affordance,短一些不打扰)。
const JUMP_DOWN_IDLE_MS = 2000;
// 方向判断死区 — 1px 内的 scrollTop 变化不算方向。
const SCROLL_DIRECTION_DEAD_ZONE_PX = 1;
const TOUCH_HISTORY_INTENT_THRESHOLD_PX = 8;
const HISTORY_NAVIGATION_KEYS: ReadonlySet<string> = new Set(['PageUp', 'ArrowUp', 'Home']);
type ProgrammaticScrollEndDecision =
'stale' | 'finished' | 'replay-deferred-delete' | 'consume-deferred-delete';
type ChipJumpTarget = {
generation: number;
clientId: string;
selector: 'message' | 'user-message';
topOffset: number;
};
/**
* 程序化滚动结束时的删除补偿裁决。用户接管必须重放延期补偿;显式的新导航有
* 自己的确定落点,可以消费旧补偿;过期 generation 不能触碰后发滚动的状态。
*/
export function resolveProgrammaticScrollEndDecision({
generation,
activeGeneration,
hasDeferredDelete,
consumeDeferredDelete = false,
}: {
generation: number;
activeGeneration: number;
hasDeferredDelete: boolean;
consumeDeferredDelete?: boolean;
}): ProgrammaticScrollEndDecision {
if (generation !== activeGeneration) return 'stale';
if (!hasDeferredDelete) return 'finished';
return consumeDeferredDelete ? 'consume-deferred-delete' : 'replay-deferred-delete';
}
/**
* 贴底时由 auto-follow 独占本轮布局变化,并消费此前记录的视口重锚。
* 返回 true 表示调用方必须立即结束旧视口补偿,避免其覆盖同一提交里的 pinToBottom。
*/
export function consumePendingReanchorForAutoFollow({
isNearBottom,
clearPendingReanchor,
}: {
isNearBottom: boolean;
clearPendingReanchor: () => void;
}): boolean {
if (!isNearBottom) return false;
clearPendingReanchor();
return true;
}
/** 以落定时的最新 DOM 几何重新计算 chip / 导航轨道目标,而不是复用 smooth 开始前的像素。 */
export function resolveChipJumpTargetScrollTop({
scrollTop,
containerTop,
targetTop,
topOffset,
}: {
scrollTop: number;
containerTop: number;
targetTop: number;
topOffset: number;
}): number {
return Math.max(0, scrollTop + targetTop - containerTop - topOffset);
}
/** 搜索目标只有作为精确 DOM 消息锚点跨过视口顶边时,才能覆盖真实顶端量测。 */
export function shouldUseFocusedElementAsViewportAnchor({
focusClientId,
elementClientId,
containerTop,
elementTop,
elementBottom,
}: {
focusClientId: string;
elementClientId?: string;
containerTop: number;
elementTop: number;
elementBottom: number;
}): boolean {
return (
elementClientId === focusClientId && elementTop <= containerTop && elementBottom > containerTop
);
}
// chip jump 抑制 expand/load 的安全兜底时长。正常解抑靠 wheel/touch/keydown,
// 这个 timer 只防"click 后既不滚也不动键盘"的极端情况,够长能覆盖最长 smooth
// scroll(浏览器长距离 ~1s)。
const CHIP_JUMP_SAFETY_MS = 3000;
// 卡片"展开详情"点击后跳过贴底跟随的窗口。click → setState → 重渲 → RO 回调
// 通常 1-2 帧内到达,300ms 富余;窗口过后 auto-follow 原样恢复。
const CARD_EXPAND_PIN_SUPPRESS_MS = 300;
// ── render-window ──
// 切大 session 时一次性 mount 全部 UI 卡会卡(687 条 messages → commit 80–300ms)。
// 先只渲染最后 N 个 render-item(渲染单元 = 已折叠 / 已丢弃后的 UI 卡),用户滚到顶
// 按 GROWTH 继续把更早的 item 纳入窗口;窗口已包含所有内存中的 item 后,才走原有
// F-SYNC-2 onLoadMore 去拉 DB 更早历史。
//
// 关键设计:窗口单位是 **render-item** 而非 message。原因见 commit history (U1/U2 死锁):
// `buildRenderItems` 把 messages 折叠 / 丢弃 / 反向膨胀,密度极不均匀。以消息条数
// 切窗会让"末尾 100 条恰好全是 orphan tool_result / ask_user / AskUserQuestion /
// ExitPlanMode"等场景塌缩到 items=[] 死锁。以 render-item 切窗时这些丢弃类型不会
// 出现在 `allRenderItems` 末尾,死锁同源 bug 一次性消失。
//
// 锚点用 `firstVisibleItemKey`(item 的 stable key,见 RenderItem.key 派生约定),
// 不用 index — DB prepend / 流式追加 / 客户端扩窗都会让 index 漂移,key 稳定。
// export 供 render-window 集成单测复用同一基准值,避免测试里再定义一份靠注释手动同步。
export const RENDER_WINDOW_INITIAL_ITEMS = 80;
// 首屏窗口:切会话(mount)首帧只画末尾 FIRST_PAINT 个 item,首帧提交后的
// 空闲期再把默认窗口扩回 INITIAL —— 首屏 commit 体量减少,补窗那笔开销移出
// 点击关键路径。15 条足以覆盖典型视口(240px/条 × 15 = 3600px > 常见屏幕高度),
// 且锚定恢复路径下 viewportTopKey 就是窗口首条,大小 ≥1 天然满足。
// 安全约束:
// - 扩窗 = 在视口上方 prepend,仅在"仍钉在底部"时执行,pin-to-bottom layout
// effect 会在同一帧把视口重新钉回底,无视觉跳动;
// - 用户在 FIRST_PAINT 阶段就向上滚动时,走既有 expandWindow 锚点路径,
// 默认窗口保持小尺寸不再自动扩(读历史的人不需要底部多 mount 50 条)。
export const RENDER_WINDOW_FIRST_PAINT_ITEMS = 15;
const RENDER_WINDOW_GROWTH_ITEMS = 80;
const RENDER_WINDOW_BOUNDARY_LOOKBACK_ITEMS = 24;
function eventTargetElement(target: EventTarget | null): HTMLElement | null {
if (target instanceof HTMLElement) return target;
if (target instanceof Node) return target.parentElement;
return null;
}
function hasNestedScrollableAncestorThatCanScrollUp(
root: HTMLElement,
target: EventTarget | null,
): boolean {
let el = eventTargetElement(target);
while (el && el !== root) {
if (!root.contains(el)) return false;
const overflowY = window.getComputedStyle(el).overflowY;
const canScroll =
(overflowY === 'auto' || overflowY === 'scroll' || overflowY === 'overlay') &&
el.scrollHeight - el.clientHeight > SCROLL_DIRECTION_DEAD_ZONE_PX &&
el.scrollTop > SCROLL_DIRECTION_DEAD_ZONE_PX;
if (canScroll) return true;
el = el.parentElement;
}
return false;
}
function hasNestedScrollableAncestorThatCanScrollDown(
root: HTMLElement,
target: EventTarget | null,
): boolean {
let el = eventTargetElement(target);
while (el && el !== root) {
if (!root.contains(el)) return false;
const overflowY = window.getComputedStyle(el).overflowY;
const maxScroll = el.scrollHeight - el.clientHeight;
const canScroll =
(overflowY === 'auto' || overflowY === 'scroll' || overflowY === 'overlay') &&
maxScroll > SCROLL_DIRECTION_DEAD_ZONE_PX &&
el.scrollTop < maxScroll - SCROLL_DIRECTION_DEAD_ZONE_PX;
if (canScroll) return true;
el = el.parentElement;
}
return false;
}
import { UserMessage } from './UserMessage';
import { AssistantMessage } from './AssistantMessage';
import { MessageSourceLabels } from './MessageSourceLabels';
import { AskUserQuestionBubble } from './AskUserQuestionBubble';
import type { ErrorDiagnosisSource } from '@/lib/errorDiagnosisPrompt';
import { ErrorMessageCard } from './ErrorMessageCard';
import { APP_EXIT_INTERRUPTED_REASON } from '../../../shared/interruptedTurn';
import { PlanReviewBubble } from './PlanReviewBubble';
import { ToolCallCard, getToolSummary } from './ToolCallCard';
import { McpAppCard } from './McpAppCard';
import { InlinePlanCard } from './TodoListCard';
import { SystemCard } from './SystemCard';
import { NewMessageIndicator } from './NewMessageIndicator';
import { ThinkingCard } from './ThinkingCard';
import { AgentActionsBlock } from './AgentActionsBlock';
import { AgentTaskCard } from './AgentTaskCard';
import { TurnChangesCard } from './TurnChangesCard';
import { useBotGeneratedFileDeliveries } from '@/features/bots/useBotGeneratedFileDeliveries';
import { GeneratedFilesCard, generatedFilesCheckKey } from './GeneratedFilesCard';
import { WorkGroupBlock, type WorkGroupChild } from './WorkGroupBlock';
import {
extractAnchorCardId,
extractGhostCardId,
extractToolResultMedia,
type ToolMediaItem,
} from './AgentActionRow';
import { CARD_EXPAND_TOGGLE_EVENT, GhostToolCard } from './GhostToolCard';
import {
ensureCard,
ensureSessionCards,
getGhostCardSnapshot,
subscribeGhostCards,
type GhostCardSnapshot,
} from '@/cindy-brain/ghostCardStore';
import {
collectGhostCardGalleryImages,
createGhostCardSpawnIndex,
} from '@/cindy-brain/ghostCardGallery';
import { ChatImageView } from './ChatImageView';
import { ImageGalleryContext, type GalleryImage } from './ImageGalleryContext';
import { GhostFulfillmentContext } from './GhostSummonCard';
import { ChatSessionFileProvider, useChatSessionFileValue } from './ChatSessionFileContext';
import { toRemoteMediaOrigin } from '@/lib/sessionFileOrigin';
import { rewriteToRemoteMediaOrigin, type RemoteMediaOrigin } from '@/../shared/remoteMediaUrl';
import { isGhostCallToolName } from '@/../shared/ghost';
import { ChatVideoView } from './ChatVideoView';
import { ChatAudioCard } from './ChatAudioCard';
import { ChatSoundEffectCard } from './ChatSoundEffectCard';
import { PrevMessageJumpChip, firstNonEmptyLine } from './PrevMessageJumpChip';
import { useTopRightChipSlot } from './TopRightChipStack';
import { usePrevUserMessageInView } from './usePrevUserMessageInView';
import { JumpToBottomChip } from './JumpToBottomChip';
import { MessageNavRail } from './MessageNavRail';
import {
NAV_RAIL_BACKFILL_MAX_ROUNDS,
NAV_RAIL_JUMP_TOP_OFFSET_PX,
shouldBackfillForNavRail,
} from './messageNavRailModel';
import { createMessageNavigationProjection } from './messageNavigationProjection';
import { resolveUserDisplayText } from './userMessageDisplayText';
import { detectScrollAnchoringApplied } from './scrollAnchoringDetect';
import { resolveMessageStreamIndicatorBottomOffset } from './messageStreamIndicatorPosition';
import {
decideAutoFillAction,
decideUserIntentFillAction,
MAX_AUTO_LOAD_ATTEMPTS,
TOP_HISTORY_TRIGGER_PX,
NO_SCROLL_TOLERANCE_PX,
} from './viewportFillDetect';
import {
bumpSendFollowCancelGeneration,
collectKnownUserMessageIds,
findLastMatching,
findLastMatchingId,
resolveEffectiveNearBottom,
resolveNearBottomOnScroll,
resolveLastUserMessageObservation,
resolveRenderPinDecision,
resolveSendWindowHandoff,
resolveWindowCoverageLossAction,
selectTailUserMessageId,
readFollowLatestRequestKey,
shouldBumpSendFollowCancelOnScroll,
subscribeFollowLatestRequests,
REPIN_AT_BOTTOM_PX,
isVerticalScrollbarPress,
shouldRepinOnDownIntent,
shouldRepinOnWheel,
shouldUnpinOnScrollbarDrag,
shouldUnpinOnUpIntent,
shouldUnpinOnWheel,
isUpwardWheelIntent,
} from './autoFollowIntent';
import { collectUnreadKeys } from './unreadCount';
const NO_UNREAD_KEYS: ReadonlySet<string> = new Set();
import {
collectBotMessageTimeGroups,
findFirstUnreadBotReplyClientId,
formatBotMessageGroupTime,
} from '@/features/bots/botConversationTimeline';
import { NAVIGATION_KEYS, useNavigationKeyListener } from './useNavigationKeyListener';
export function isScrollNavigationKey(key: string): boolean {
return NAVIGATION_KEYS.has(key);
}
import { suppressScrollbarActivation } from '@/lib/scrollbarAutoHide';
import { useAutomaticHistoryLoadBudget } from './useAutomaticHistoryLoadBudget';
import { collectAssistantTurnUsageDetails } from '@/lib/userTurnUsage';
import type { TurnUsageDetails } from '../../../shared/turnUsageDetails';
import { hasReviewableTurnChanges, type TurnChangeSetSummary } from '../../../shared/turnChangeSet';
interface MessageStreamProps {
/** Content before history, sharing its scrolling and measured content height. */
header?: ReactNode;
historyVisibleAfter?: number;
onAskInSideChat?: (quote: string) => Promise<boolean>;
/** Active session id — used to reset scroll state on session switch. */
sessionId?: string;
/** Active session title, forwarded to handoff cards for return navigation. */
sessionTitle?: string | null;
/** Owning agent kind — propagated to UserMessage so capability gates
* (fork/rewind icon visibility) can read the right agent's capabilities. */
agentKind?: 'cc' | 'codex' | 'pi';
/** Owning session's remote SSH host id (null for local sessions). Forwarded
* so message-level controls can gate features unsupported on remote
* (e.g. rewind on cc-remote daemon sessions). */
remoteHostId?: string | null;
/** Task origin. Personal WeChat must not be told to switch to Full access. */
sessionSource?: string | null;
onDiagnoseError?: (error: ErrorDiagnosisSource) => void;
/** Session working directory; passed down so MarkdownRenderer / UserMessage
* can resolve relative paths in markdown links and inline @-chips
* (text-lightbox-trigger-extension F1 / F2). Stable within a session
* lifecycle — only changes on session switch (which already remounts
* MessageStream via the `key={sessionId}` parent prop), so it never
* triggers extra re-renders mid-session. */
workingDir: string;
/**
* Identity mark drawn to the left of every assistant bubble.
*
* Only a Bot conversation passes one — a normal Cindy task has no "who is
* speaking" question to answer, so it stays undefined and the layout is
* byte-identical to before. The node must be stable across renders (memoize
* it at the owner): it is a prop of the memoized `MessageItem`.
*/
assistantAvatar?: ReactNode;
/** 伙伴专属轻量时间线:隐藏内部工作卡,只保留单一运行状态与分组时间。 */
simplifiedBotConversation?: boolean;
/** Bot read position captured before entry marks the conversation read. */
botUnreadBoundaryAt?: number | null;
onBotReadThrough?: (at: number) => void;
messages: ChatMessage[];
/** The ongoing call appears only in its transcript popover, including history replays. */
activeVoiceCallId?: string | null;
/** This task's preparation card is shown in the composer, including after history reload. */
cindyMakeSessionId?: string;
cindyMakeCompletionInComposer?: boolean;
historyLoaded: boolean;
/** The task shell remains, but all prior message content was intentionally cleared. */
historyCleared?: boolean;
taskUpdates?: ReadonlyMap<string, AgentTaskUpdate>;
/** Host `subagent_runs` status of this task's Subagents (local tasks only). */
subagentRunStatuses?: SubagentRunStatusIndex;
/** Kept for API compatibility. v2 — no longer threaded into render items
* (AgentActionsBlock + ThinkingCard manage their own per-block expand
* state via useExpandedBlockMemory). The session-level "is streaming"
* state lives on each ChatMessage's own `isStreaming` field instead. */
isSessionStreaming?: boolean;
/** 当前 vendor turn 的续跑发起项 clientId;steer 顶替 activeTurn 后仍保持。 */
continuationTurnClientId?: string | null;
/** 旧被控端缺省该字段时才启用兼容兜底;unknown 在首个投影前 fail closed。 */
continuationInFlightProjectionCapability?: ContinuationInFlightProjectionCapability;
/** F-SYNC-2: callback to load older messages; true marks this as an automatic fill. */
onLoadMore?: (automatic?: boolean) => Promise<boolean>;
isLoadingMore?: boolean;
hasMoreMessages?: boolean;
/** 当前逻辑历史窗口中间仍有缺口;与 hasMoreMessages 一样会让父调用归属不可信。 */
historyWindowHasIsland?: boolean;
/** Dynamic bottom padding (px) to reserve space for the input overlay */
bottomPadding?: number;
/** Distance from the chat viewport bottom to the topmost occupied bottom-center layer. */
bottomCenterClearanceOffset?: number;
/** Content width — shared with the input overlay so chat stream + input
* box stay horizontally aligned (same width, same center, symmetric
* padding when the main area is compressed). */
contentWidth?: CSSProperties['maxWidth'];
/** Returns the current numeric content width for geometry consumers without rerendering. */
getContentWidth?: () => number;
/** Message clientId to scroll into view and briefly highlight after search navigation. */
focusMessageClientId?: string | null;
/** Incremented by the parent for each search navigation, including repeated hits. */
focusMessageRequestId?: number;
/** Source marker shown for sessions forked from another conversation. */
forkOrigin?: {
parentSessionId: string;
forkedAtMessageId: string;
forkedSessionCreatedAt: string;
} | null;
/** Opens the parent conversation and focuses the original fork point. */
onOpenForkOrigin?: () => void;
/**
* #2194: whether a user message (by clientId) was sent from this renderer's
* composer. Only such messages force-pin the viewport to the tail; user
* messages injected by other entries (IM channels, a mobile client driving
* the session, scheduler runs) follow the ordinary near-bottom rule.
* Optional — consumers that cannot tell (tests, storybook) keep the legacy
* behavior of treating every new tail user message as a local send.
*/
isLocalUserSend?: (clientId: string) => boolean;
/**
* Whether this stream should consume hardware scroll commands.
* Split panes keep every MessageStream mounted; only the focused owner may act.
*/
ownsHardwareScrollActions?: boolean;
/**
* 当前计划的流内卡是否仍在用户可见区域。父层据此决定 composer 上方的
* 兜底胶囊是否需要接力;key 防止新旧计划切换时沿用上一张卡的可见状态。
*/
onInlinePlanVisibilityChange?: (state: InlinePlanVisibility | null) => void;
}
export interface InlinePlanVisibility {
key: string;
visible: boolean;
}
// ---------------------------------------------------------------------------
// Merged rendering items
// ---------------------------------------------------------------------------
// Item types and pure work grouping live in messageWorkGroups; window/DOM behavior stays here.
function isRenderWindowBoundaryItem(item: RenderItem | undefined): boolean {
return item?.type === 'fork_origin' || (item?.type === 'message' && item.message.role === 'user');
}
/**
* 首帧字节预算:单条 render item 的挂载成本估算(≈ markdown parse 体量)。
* message 正文按字符数计(react-markdown parse 成本与正文长度近似线性);
* 折叠类卡片(tool_segment / agent_task / work_group)默认收拢、不 parse 正文,
* 按小常量计;ghost_card 挂 html 卡体,按较大常量计。
*/
export function estimateRenderItemMountCost(item: RenderItem): number {
if (item.type === 'message') return 200 + item.message.content.length;
if (item.type === 'ghost_card') return 2000;
return 300;
}
/**
* 首帧窗口的内容预算(估算成本单位 ≈ 字符数)。
*
* 条数上限(FIRST_PAINT_ITEMS)防"多而小",本预算防"少而大"——单条 12KB
* 大表格的压测 session,15 条 = ~380ms(dev 构建实测,2026-08-10 perf 日志),
* 条数封顶对它无效。两者先到为准。64k ≈ 5 条大表格 ≈ ~130ms dev、release 减半;
* 普通 session(单条 <2KB)触不到本预算,照走条数上限。
* 被预算推迟的 item 由既有空闲扩窗(FIRST_PAINT → INITIAL)在 ~1s 内补回,
* 不影响内容完整性。
*/
export const RENDER_WINDOW_FIRST_PAINT_BUDGET = 64_000;
/**
* 从末尾向前累计挂载成本,预算耗尽时把窗口起点向后收(渲染更少条)。
* 至少保留最后 1 条(单条超预算也要渲染它)。export 供单测。
*/
export function clampTailWindowStartByBudget(
items: readonly RenderItem[],
countStartIdx: number,
budget = RENDER_WINDOW_FIRST_PAINT_BUDGET,
): number {
let cost = 0;
for (let i = items.length - 1; i >= countStartIdx; i--) {
cost += estimateRenderItemMountCost(items[i]);
if (cost > budget && i < items.length - 1) return i + 1;
}
return countStartIdx;
}
export function resolveAnchoredWindowItemCount(
startIdx: number,
anchorIdx: number,
desiredForwardItems: number,
): number {
return desiredForwardItems + Math.max(0, anchorIdx - startIdx);
}
export function shouldBoostDefaultWindow({
allItemCount,
visibleItemCount,
defaultWindowItems,
}: {
allItemCount: number;
visibleItemCount: number;
defaultWindowItems: number;
}): boolean {
if (defaultWindowItems >= RENDER_WINDOW_INITIAL_ITEMS) return false;
return visibleItemCount < allItemCount;
}
type VisibilityRect = Pick<DOMRect, 'top' | 'right' | 'bottom' | 'left' | 'width' | 'height'>;
/**
* 判定流内计划卡是否至少有一个可见像素。
*
* scroll 容器底部被 composer overlay 覆盖,单看容器的 DOMRect 会把“实际藏在
* 输入框后面”误判为可见,所以把 overlay 高度作为 bottomInset 从可视区扣掉。
*/
export function isPlanCardVisibleInViewport(
card: VisibilityRect,
viewport: VisibilityRect,
bottomInset = 0,
): boolean {
if (card.width <= 0 || card.height <= 0 || viewport.width <= 0 || viewport.height <= 0) {
return false;
}
const safeBottomInset = Math.min(Math.max(0, bottomInset), Math.max(0, viewport.height - 1));
const visibleBottom = viewport.bottom - safeBottomInset;
return (
card.bottom > viewport.top &&
card.top < visibleBottom &&
card.right > viewport.left &&
card.left < viewport.right
);
}
export function planSessionBelongsToLatestUserTurn(
messages: readonly ChatMessage[],
sourceClientIds: readonly string[],
): boolean {
const sourceIds = new Set(sourceClientIds);
let latestNormalUserIndex = -1;
let latestPlanRowIndex = -1;
for (let index = 0; index < messages.length; index += 1) {
const message = messages[index];
if (isPlanUserBoundary(message)) latestNormalUserIndex = index;
if (sourceIds.has(message.clientId)) latestPlanRowIndex = index;
}
return latestPlanRowIndex >= 0 && latestNormalUserIndex <= latestPlanRowIndex;
}
export function resolveDefaultWindowStartIdx({
allItemCount,
defaultWindowItems,
visibleStartIdx,
visibleItemCount,
}: {
allItemCount: number;
defaultWindowItems: number;
visibleStartIdx: number;
visibleItemCount: number;
}): number {
// 首帧字节预算可能让实际 DOM 窗口比声明容量小。用户在 idle boost 前主动
// 向上滚动时,必须从真实 visibleStartIdx 扩,而不是用声明容量反算出 0。
if (visibleItemCount < allItemCount) return visibleStartIdx;
return Math.max(0, allItemCount - defaultWindowItems);
}
// export 仅供 render-window 集成单测使用。窗口默认/扩窗时如果刚好切在
// agent_task / work_group / assistant 中间,顶部会出现无上下文的卡片。
// 向前吸收同一 user turn 的开头,但限制 lookback 防止单个超长 turn 破坏首屏预算。
export function snapRenderWindowStartIdx(
items: readonly RenderItem[],
startIdx: number,
maxLookback = RENDER_WINDOW_BOUNDARY_LOOKBACK_ITEMS,
): number {
if (items.length === 0) return 0;
const clamped = Math.min(Math.max(0, startIdx), items.length - 1);
if (clamped === 0 || isRenderWindowBoundaryItem(items[clamped])) return clamped;
const stop = Math.max(0, clamped - Math.max(0, maxLookback));
for (let i = clamped - 1; i >= stop; i--) {
if (isRenderWindowBoundaryItem(items[i])) return i;
}
return clamped;
}
function ForkOriginMarker({
onClick,
renderItemKey,
}: {
onClick?: () => void;
renderItemKey?: string;
}) {
const { t } = useTranslation();
return (
<div data-render-item-key={renderItemKey} className="flex items-center gap-4 py-3">
<div className="h-px flex-1 bg-[var(--border-default)]" />
<button
type="button"
onClick={onClick}
disabled={!onClick}
className="group inline-flex shrink-0 items-center gap-2 bg-transparent p-0 text-13 font-medium leading-5 text-[var(--text-secondary)] transition-colors hover:text-[var(--text-primary)] hover:underline hover:underline-offset-2 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--focus-ring)] disabled:cursor-default disabled:text-[var(--text-tertiary)] disabled:hover:no-underline"
>
<GitFork size={15} strokeWidth={2} className="shrink-0" aria-hidden="true" />
<span>{t('chat.forkOrigin.label')}</span>
</button>
<div className="h-px flex-1 bg-[var(--border-default)]" />
</div>
);
}
function HistoryClearedMarker() {
const { t } = useTranslation();
return (
<div className="flex items-center gap-4 py-3" role="status">
<div className="h-px flex-1 bg-[var(--border-default)]" />
<span className="shrink-0 text-12 text-[var(--text-tertiary)]">
{t('settings.about.storage.dbSlimmingHistoryCleared')}
</span>
<div className="h-px flex-1 bg-[var(--border-default)]" />
</div>
);
}
function areLocalFileRefsEqual(
a: readonly KnownLocalFileRef[],
b: readonly KnownLocalFileRef[],
): boolean {
if (a.length !== b.length) return false;
for (let i = 0; i < a.length; i++) {
if (a[i].name !== b[i].name || a[i].path !== b[i].path) return false;
}
return true;
}
// export 仅供单测使用。MessageStream 用它在 streaming token 期间复用未变化的
// localFileRefs 引用,避免打破历史 MessageItem 的 memo。
export function collectStableLocalFileRefs(
messages: readonly ChatMessage[],
previousRefs: readonly KnownLocalFileRef[] = [],
): readonly KnownLocalFileRef[] {
const refs: KnownLocalFileRef[] = [];
for (const message of messages) {
if (message.role !== 'user') continue;
for (const file of message.files ?? []) {
refs.push({ name: file.name, path: file.path });
}
}
return areLocalFileRefsEqual(previousRefs, refs) ? previousRefs : refs;
}
export function assistantHasFollowingUserBoundary(
messages: readonly ChatMessage[],
assistantClientId: string,
): boolean {
const idx = messages.findIndex((m) => m.clientId === assistantClientId);
if (idx < 0) return false;
return messages.slice(idx + 1).some((m) => m.role === 'user' && m.delivery !== 'steer');
}
function collectAssistantsWithFollowingUserBoundary(messages: readonly ChatMessage[]): Set<string> {
const out = new Set<string>();
let hasFollowingUser = false;
for (let i = messages.length - 1; i >= 0; i--) {
const message = messages[i];
if (message.role === 'user' && message.delivery !== 'steer') {
hasFollowingUser = true;
} else if (message.role === 'assistant' && hasFollowingUser) {
out.add(message.clientId);
}
}
return out;
}
/**
* 意识"提及 → 兑现"关联(方案 2,渲染期从持久数据推导,重启幂等):
* 逐条扫消息,维护"当前轮的 user 消息",遇到 assistant 的 ghost_call 工具
* 调用就把其 ghost_id 记到当前 user 名下——即"这条 user 触发的那一轮里,
* AI 真的召唤了哪些意识"。软提示徽章据此升级为召唤卡(徽章说'提到了',
* 兑现后才敢说'召唤了')。turn 边界 = 下一条非 steer 的 user 消息。
* 判据全取自会话历史(user 消息 + ghost_call tool_use 都已持久化),不落
* 任何额外状态,重启重算结果一致。
*/
export function collectGhostCallsByUserTurn(
messages: readonly ChatMessage[],
): Map<string, Set<string>> {
const out = new Map<string, Set<string>>();
let currentUserClientId: string | null = null;
for (const m of messages) {
if (m.role === 'user' && m.delivery !== 'steer' && !m.isSyntheticTrigger) {
currentUserClientId = m.clientId;
continue;
}
if (
currentUserClientId &&
isGhostCallToolName(m.toolName) &&
m.toolInput &&
typeof (m.toolInput as Record<string, unknown>).ghost_id === 'string'
) {
const input = m.toolInput as Record<string, unknown>;
const gid = ghostSummonInstanceId(input.ghost_id as string, input.namespace);
if (!gid) continue;
const set = out.get(currentUserClientId) ?? new Set<string>();
set.add(gid);
out.set(currentUserClientId, set);
}
}
return out;
}
/**
* 兑现关联 map 的结构等价判断:用于给 Provider value 做引用缓存。
* messages 数组在流式期间每批 delta 都换新引用,useMemo 会重算出"内容相同
* 但身份全新"的 Map;而 UserMessage 顶层订阅该 context(判定合并形态),
* context 消费按 Object.is 判变、无视 memo——不做等价缓存的话,每批 token
* 都会把全部历史 UserMessage 重渲一遍(规则 10 热路径口径)。fulfillment
* 实际只在 ghost_call 落地时才变化,每 turn 至多一两次。
*/
export function ghostCallMapsEqual(
a: ReadonlyMap<string, ReadonlySet<string>>,
b: ReadonlyMap<string, ReadonlySet<string>>,
): boolean {
if (a === b) return true;
if (a.size !== b.size) return false;
for (const [key, setA] of a) {
const setB = b.get(key);
if (!setB || setA.size !== setB.size) return false;
for (const v of setA) if (!setB.has(v)) return false;
}
return true;
}
/**
* 已加载消息里"整段对话首条 user 消息"的 clientId(判不出则 null)。
* 首条 user 消息要隐藏 Fork/Rewind/编辑(没有 prior assistant 锚点,后端必抛
* NO_PRIOR_ASSISTANT)。关键修正:messages 只是**已加载的尾部切片**(初始 50 条),
* `hasMoreOlderMessages=true` 时真正的首条 user 消息(任何会话的第一行)还在
* 未加载的老页里,切片首条必然不是它——此时返回 null,不把任何已加载消息误判
* 为首条。此前的误判会让"一个长 turn 挤掉切片里更早 user 消息"的会话在滚动
* 加载前丢失最后一条消息的 Fork/Rewind/编辑按钮(hover 只剩复制 + 时间戳)。
* 导出为纯函数供单测直接断言。
*/
export function findFirstUserMessageClientId(
messages: readonly ChatMessage[],
hasMoreOlderMessages: boolean,
): string | null {
if (hasMoreOlderMessages) return null;
for (const m of messages) {
// isSyntheticTrigger 行渲染 null,不能成为可见 affordance 的目标(review P2)。
if (m.role === 'user' && !m.isSyntheticTrigger) return m.clientId;
}
return null;
}
/**
* edit-last-message: 全量消息列表里最后一条 user 消息的 clientId(无则 null)。
* 只有它显示编辑入口——编辑 = rewind 到该条 + 重发,对更早的消息开放会连带
* 丢弃后续轮次。导出为纯函数供单测直接断言。
* (last 与 first 不同,不受向上分页影响——切片永远包含真实的尾部。)
*/
export function findLastUserMessageClientId(messages: readonly ChatMessage[]): string | null {
for (let i = messages.length - 1; i >= 0; i--) {
// isSyntheticTrigger 行渲染 null:它成为"最后一条 user"会让真实最后一条
// user 消息丢失编辑入口(review P2)——可见 affordance 只认可见行。
if (messages[i].role === 'user' && !messages[i].isSyntheticTrigger) return messages[i].clientId;
}
return null;
}
export function shouldBlockAssistantFork(
isSessionStreaming: boolean,
message: ChatMessage,
assistantsWithFollowingUserBoundary: ReadonlySet<string>,
): boolean {
return (
isSessionStreaming &&
message.role === 'assistant' &&
!assistantsWithFollowingUserBoundary.has(message.clientId)
);
}
/**
* 每个 user turn 的「收尾 assistant 正文」clientId 集合 —— action bar
* (复制 / 分叉 / 时间 / 费用)只挂这些消息:任务执行过程中的中间正文不挂,
* 避免每句话下面都占一行操作区(bar 即使 opacity-0 也占 24px 布局高度),
* 保持消息流紧凑。产品口径:只有任务结束的最后一句话才出现这些操作。
* turn 边界与 fork 口径一致(非 steer 的 user 消息);候选口径与
* isAssistantAnswerCandidate 一致(普通 assistant 文本:非 systemCard、非空)。
* 尾部 turn 是否"已结束"由调用方叠加 shouldBlockAssistantFork 判定,本函数
* 只回答"是不是本 turn 最后一条正文"。export 仅供单测使用。
*/
function isGeneratedFilesSubTurnTerminal(message: ChatMessage): boolean {
// 显式失败也是子轮终态:后续没有新工作就该封口复核,不能把失败当成「还在跑」。
return message.turnCompleted === false || isCompletedAssistantMessage(message);
}
/**
* 产物卡封口只看当前尾部子轮。同一可见 user turn 在 turnCompleted 后自动续跑时,
* 前一子轮的收尾信号不得让后续 ready:false 的文件立刻 stat。
* export 仅供单测使用。
*/
export function isGeneratedFilesTurnSealed(
slice: readonly ChatMessage[],
hasFollowingUser: boolean,
): boolean {
if (hasFollowingUser) return true;
let lastTerminalIdx = -1;
for (let i = 0; i < slice.length; i++) {
if (isGeneratedFilesSubTurnTerminal(slice[i])) lastTerminalIdx = i;
}
if (lastTerminalIdx < 0) return false;
for (let i = lastTerminalIdx + 1; i < slice.length; i++) {
const message = slice[i];
if (message.role === 'tool_use') return false;
if (message.role === 'user' && message.isSyntheticTrigger === true) return false;
if (message.role === 'assistant' && !message.systemCardType) return false;
}
return true;
}
export function collectTurnFinalAssistantClientIds(messages: readonly ChatMessage[]): Set<string> {
const out = new Set<string>();
let sealedAnswerFound = false;
let pendingLegacyFallback: string | null = null;
for (let i = messages.length - 1; i >= 0; i--) {
const message = messages[i];
if (message.role === 'user' && message.delivery !== 'steer') {
if (!sealedAnswerFound && pendingLegacyFallback) out.add(pendingLegacyFallback);
sealedAnswerFound = false;
pendingLegacyFallback = null;
continue;
}
if (
message.role !== 'assistant' ||
message.systemCardType ||
message.content.trim().length === 0
) {
continue;
}
if (isCompletedAssistantMessage(message)) {
out.add(message.clientId);
sealedAnswerFound = true;
pendingLegacyFallback = null;
continue;
}
// 倒序扫描先暂存本 user turn 最后一条正文;只有整段没有 seal 时才采用。
pendingLegacyFallback ??= message.clientId;
}
if (!sealedAnswerFound && pendingLegacyFallback) out.add(pendingLegacyFallback);
return out;
}
/**
* Build renderable items from the flat message array.
*
* Single linear pass. v2 — `isSessionStreaming` is no longer threaded into
* tool_segment items because AgentActionsBlock + ThinkingCard now manage
* their own per-block expand state via useExpandedBlockMemory (default
* collapsed; user click → persisted).
*
* Agent plan handling:
* Pass 1 groups TodoWrite / update_plan / Task* calls into logical plan
* sessions. Pass 2 replaces each session's latest tool row with one
* `agent_plan` item in the chat timeline. The composer capsule observes the
* latest inline card and only takes over after that card leaves the viewport.
*/
function deferredWorkContainsClientId(
item: Extract<RenderItem, { type: 'work_group' }>,
clientId: string,
): boolean {
return (
item.deferred?.key
?.split('|')
.some((key) => key === `work-${clientId}` || key === `work-summary-${clientId}`) ?? false
);
}
/**
* 锚点丢失恢复:DB 加载更老历史 prepend 时,若新拉回的末尾是 tool_use 且当前
* 首段 render item 是 tool_segment,segment 会向前合并吸收这些 toolCall —— 原
* `seg-${toolCalls[0].clientId}` 的 toolCalls[0] 变了,key 失效。直接 fallback
* 到 slice(-INITIAL_ITEMS) 会让窗口跳回末尾 80 个,expandWindow 的
* `currentStartIdx<=0` 早返也使 expand 永远 no-op,用户卡死。
*
* 恢复策略:从 lost key 反解 clientId(所有 key 形如 `${prefix}-${clientId}`),
* 扫描 allRenderItems 找哪个 item **现在覆盖**这个 clientId:
* - message: msg.clientId 严格匹配
* - tool_segment: toolCalls.*.clientId 任一匹配(段合并后老 toolCall 仍在新段内)
* - tool_media / ghost_card:用派生 key 后缀匹配
* - agent_plan:除 key 外还保留 session 内全部计划行的 clientId
*
* 找到即返回该 index,visible slice 从这里继续;找不到才退回默认窗口。
*
* 注:此处不更新 firstVisibleItemKey state(避免在 useMemo 里触发 setState 的
* React 警告)— 锚点状态保持 stale 没关系,下次 useMemo / expandWindow 会再
* 走同样的 recover。每次扫描 O(n × m) 其中 m 是平均 toolCalls/segment,典型 n=200
* 时几毫秒,可接受。
*/
export function restoreClientIdFromKey(key: string): string | undefined {
// Synthetic cards are anchored to a real source row, including generated files.
const prefix = [
'work-summary-',
'subagent-media-',
'genfiles-',
'msg-',
'seg-',
'work-',
'media-',
'ghostcard-',
].find((prefix) => key.startsWith(prefix));
return prefix ? key.slice(prefix.length) || undefined : undefined;
}
export function restoreClientIdForItem(item: RenderItem): string | undefined {
if (item.type === 'fork_origin') return undefined;
if (item.type === 'agent_plan') return item.sourceClientIds[0];
if (item.type === 'turn_changes') return item.changeSet.anchorClientId ?? undefined;
if (item.type === 'ghost_card') return item.toolCall.clientId;
if (item.type === 'work_group')
return restoreClientIdFromKey(item.key) ?? collectDeleteAnchorClientIds([item])[0];
return collectDeleteAnchorClientIds([item])[0] ?? restoreClientIdFromKey(item.key);
}
export function viewportRestoreNeedsMoreContent(
desiredScrollTop: number,
scrollHeight: number,
viewportHeight: number,
coversEnd: boolean,
): boolean {
return !coversEnd && desiredScrollTop > Math.max(0, scrollHeight - viewportHeight) + 1;
}
function recoverLostAnchorIdx(items: RenderItem[], lostKey: string): number {
const dashIdx = lostKey.indexOf('-');
if (dashIdx < 0) return -1;
// Completed groups have a compound prefix; the message id can itself contain dashes.
const lostCid = lostKey.startsWith('work-summary-')
? lostKey.slice('work-summary-'.length)
: lostKey.slice(dashIdx + 1);
if (!lostCid) return -1;
for (let i = 0; i < items.length; i++) {
const it = items[i];
if (it.type === 'message') {
if (it.message.clientId === lostCid) return i;
} else if (it.type === 'tool_segment') {
// segment 合并后,老的 toolCall 仍是新段内某条 toolCall
if (it.toolCalls.some((tc) => tc.clientId === lostCid)) return i;
} else if (it.type === 'agent_task') {
if (it.toolCall?.clientId === lostCid) return i;
} else if (it.type === 'agent_plan') {
if (
it.key === lostKey ||
it.key.endsWith(`-${lostCid}`) ||
it.sourceClientIds.includes(lostCid)
) {
return i;
}
} else if (it.type === 'work_group') {
// work_group 可能嵌套完成态时间线 — 老锚点(`seg-${cid}` /
// `msg-${cid}` / `work-${cid}`)递归落到任一后代即由外组接住。
// Remote placeholders can merge and disappear from children; their original
// summary identities remain in deferred.key even when the visible key changes.
if (
it.key === lostKey ||
it.key === `work-${lostCid}` ||
it.key === `work-summary-${lostCid}` ||
deferredWorkContainsClientId(it, lostCid)
)
return i;
// Remote deferred groups retain their key before their children are loaded.
if (recoverLostAnchorIdx(it.children, lostKey) >= 0) return i;
} else if (it.type !== 'fork_origin') {
// tool_media / ghost_card:其 key 派生自 stable message clientId,精确后缀匹配
if (it.key === lostKey || it.key.endsWith(`-${lostCid}`)) return i;
}
}
return -1;
}
export function findRestorableViewportItemIdx(items: RenderItem[], viewportTopKey: string): number {
const exactIdx = items.findIndex((it) => it.key === viewportTopKey);
return exactIdx >= 0 ? exactIdx : recoverLostAnchorIdx(items, viewportTopKey);
}
/**
* 删除补偿的落点选择:视口顶端 item 被删后,取旧序列里它之后第一条存活 item
* (连带删除可能越过多条);无则回退它之前最近的存活 item,再无则落到新末条。
* 返回 null = 旧序列里找不到被删 key(快照过旧),无从补偿。
* 注意:窗口整段被清时 prevKeys 必须是旧**全量**序列——已回退的可见窗没有删除区
* 的邻接信息,fallback 会落到 curKeys 末项(会话尾)。
*/
export function pickDeleteCompensationAnchorKey(
prevKeys: readonly string[],
curKeys: readonly string[],
deletedKey: string,
): string | null {
const deletedIdx = prevKeys.indexOf(deletedKey);
if (deletedIdx < 0) return null;
const alive = new Set(curKeys);
return (
prevKeys.slice(deletedIdx + 1).find((k) => alive.has(k)) ??
prevKeys.slice(0, deletedIdx).findLast((k) => alive.has(k)) ??
curKeys.at(-1) ??
null
);
}
/** 删除补偿落点:精确可见 child 优先;否则落到折叠摘要容器,不用隐藏后代配外层旧 offset。 */
export function resolveDeleteCompensationLanding(input: {
exactVisible: boolean;
fallbackContainerVisible: boolean;
}): 'exact' | 'container' | 'item' {
if (input.exactVisible) return 'exact';
if (input.fallbackContainerVisible) return 'container';
return 'item';
}
export function isVisibleDeleteCompensationElement(
element: { getBoundingClientRect(): { height: number } } | null,
): boolean {
return Boolean(element && element.getBoundingClientRect().height > 0);
}
/**
* 渲染顺序下所有可定位 clientId:message、tool_segment、agent_task、嵌套 work_group。
* 删除补偿与 focus 落点都走这条序列,避免子消息删除时跳过中间的工具行。
*/
export function collectDeleteAnchorClientIds(items: readonly RenderItem[]): string[] {
const ids: string[] = [];
for (const item of items) {
if (item.type === 'message') ids.push(item.message.clientId);
else if (item.type === 'tool_segment') {
for (const toolCall of item.toolCalls) ids.push(toolCall.clientId);
} else if (item.type === 'agent_task' && item.toolCall) {
ids.push(item.toolCall.clientId);
} else if (item.type === 'work_group') {
ids.push(...collectDeleteAnchorClientIds(item.children));
}
}
return ids;
}
function queryMessageElement(root: ParentNode, clientId: string): HTMLElement | null {
return root.querySelector(
`[data-message-client-id="${CSS.escape(clientId)}"]`,
) as HTMLElement | null;
}
/**
* 精确 message / 任务卡优先;否则取 data-message-client-ids 的最内层匹配。
* 工作组容器也会带全量子 id,必须用最内层,否则会滚到组顶而不是中间的工具行。
*/
function queryFocusElement(root: ParentNode, clientId: string): HTMLElement | null {
const exact = queryMessageElement(root, clientId);
if (exact) return exact;
const matches = root.querySelectorAll<HTMLElement>(
`[data-message-client-ids~="${CSS.escape(clientId)}"]`,
);
return matches[matches.length - 1] ?? null;
}
/** 折叠摘要容器:跳过高度为 0 的精确 child,取仍可见的最内层聚合节点。 */
function queryVisibleAggregateContainer(root: ParentNode, clientId: string): HTMLElement | null {
const matches = root.querySelectorAll<HTMLElement>(
`[data-message-client-ids~="${CSS.escape(clientId)}"]`,
);
for (let i = matches.length - 1; i >= 0; i--) {
const element = matches[i];
if (element.getBoundingClientRect().height > 0) return element;
}
return null;
}
/** 精确 id 优先;否则取 data-message-client-ids 的第一个 token(折叠工具块 focus 回退)。 */
export function readAnchorClientId(element: {
dataset: { messageClientId?: string; messageClientIds?: string };
}): string | undefined {
const exact = element.dataset.messageClientId?.trim();
if (exact) return exact;
return element.dataset.messageClientIds?.trim().split(/\s+/).find(Boolean);
}
/** 视口子锚点只认已渲染的精确 id;聚合 token 列表留给 queryFocusElement。 */
export function readViewportChildAnchorClientId(element: {
dataset: { messageClientId?: string; messageClientIds?: string };
}): string | undefined {
return element.dataset.messageClientId?.trim() || undefined;
}
type ChildAnchorRect = {
clientId: string;
top: number;
bottom: number;
};
/** 树序最后一个跨过容器顶边的子锚点(最内层)。 */
export function pickIntersectingChildAnchor(
candidates: readonly ChildAnchorRect[],
containerTop: number,
): { clientId: string; offset: number } | null {
let picked: { clientId: string; offset: number } | null = null;
for (const candidate of candidates) {
if (candidate.bottom - containerTop <= 0 || candidate.top > containerTop) continue;
picked = {
clientId: candidate.clientId,
offset: Math.max(0, containerTop - candidate.top),
};
}
return picked;
}
type ViewportTopSnapshot = {
viewportTopKey: string;
offset: number;
messageClientId?: string;
messageOffset?: number;
};
/** 精确子 DOM 不存在时降级到 render-item 锚点,避免隐藏 child 继续触发删除补偿。 */
export function toRenderItemViewportSnapshot(
snapshot: ViewportTopSnapshot,
offset = snapshot.offset,
): ViewportTopSnapshot {
return { viewportTopKey: snapshot.viewportTopKey, offset };
}
/**
* 展开工作组 / 工具块被折叠后,精确 child DOM 会消失,但 render-item 数据仍在。
* 这时必须重新量测;否则陈旧 messageClientId 会在隐藏 child 被删时误走补偿。
*/
export function shouldRefreshHiddenChildViewportAnchor(input: {
snapshotMessageClientId: string | undefined;
exactChildVisible: boolean;
childStillInRenderItems: boolean;
}): boolean {
return (
input.snapshotMessageClientId !== undefined &&
!input.exactChildVisible &&
input.childStillInRenderItems
);
}
/**
* 折叠组展开后快照往往只有 render-item key。视口顶 item 里已出现可见的精确
* child 时必须重测,否则删这个 child 时补偿看不到 snapshotMessageGone。
*/
export function shouldRefreshExpandedChildViewportAnchor(input: {
snapshotMessageClientId: string | undefined;
viewportTopItemHasVisibleExactChild: boolean;
}): boolean {
return input.snapshotMessageClientId === undefined && input.viewportTopItemHasVisibleExactChild;
}
function hasVisibleExactChildAnchor(itemElement: HTMLElement): boolean {
for (const element of itemElement.querySelectorAll<HTMLElement>('[data-message-client-id]')) {
const rect = element.getBoundingClientRect();
if (rect.bottom > rect.top) return true;
}
return false;
}
/** Prefer the saved card itself before falling back to its source message. */
export function resolveSavedViewportKey(
items: RenderItem[],
snapshot: SessionScrollSnapshot,
): string | null {
const index = findRestorableViewportItemIdx(items, snapshot.viewportTopKey);
if (index >= 0) return items[index].key;
const clientId =
snapshot.restoreClientId ??
snapshot.messageClientId ??
restoreClientIdFromKey(snapshot.viewportTopKey);
return clientId ? renderItemKeyForClientId(items, clientId) : null;
}
/** Restore the reading viewport, not all the offscreen rows expanded before leaving. */
export function resolveRestoredRenderWindow(snapshot: SessionScrollSnapshot | undefined): {
anchor: string | null;
forwardItems: number;
} {
if (!snapshot || snapshot.isNearBottom) {
return { anchor: null, forwardItems: RENDER_WINDOW_FIRST_PAINT_ITEMS };
}
if (snapshot.viewportTopKey) {
return { anchor: snapshot.viewportTopKey, forwardItems: RENDER_WINDOW_FIRST_PAINT_ITEMS };
}
// Legacy snapshots without an exact viewport still need their original window.
return {
anchor: snapshot.windowAnchorKey,
forwardItems:
snapshot.anchoredForwardCount && snapshot.anchoredForwardCount > 0
? snapshot.anchoredForwardCount
: RENDER_WINDOW_FIRST_PAINT_ITEMS,
};
}
/**
* 从全量 render items 里按渲染顺序抽出会话内所有图片的 src,作为 lightbox 翻图
* 的数据源(全量,不受渲染窗口裁剪影响)。只收**结构化、确定会渲染成图**的三类:
* - tool-output 图(art 出图 / 飞书拉图等)→ tool_media item 的 image 项
* - 用户上传图 → user message 的 images(url 或 data:base64,与 UserMessage 同款拼法)
* - 插件生成图 → ghost card 及其衍生卡中会打开 ImageLightbox 的图片
*
* 不收正文 Markdown 内嵌图:用正则扫文本会误抓代码块里当作文本展示的 ![]() 语法,
* 虚增计数 / 让翻页跳到无效图(codex review);要准确得复刻 MarkdownRenderer 的
* AST 渲染规则,成本高且易漂移。Markdown 内嵌图点开仍是单图预览,不进会话画廊。
* 顺序与 DOM 渲染一致(用户消息里上传图在正文之前),便于 lightbox 做位置映射。
*/
export function collectSessionImageSrcs(
items: RenderItem[],
mediaOrigin?: RemoteMediaOrigin,
ghostCards?: GhostCardSnapshot,
isSessionStreaming = false,
): GalleryImage[] {
// 远程会话:画廊 src 必须与渲染出的 <img data-gallery-src> 同样改写到 cindy-remote-media://,
// 否则 ImageLightbox 的画廊 src 匹配对不上、退化成仅当前窗口翻图 + 计数错。
const push = (url: string, meta?: Omit<GalleryImage, 'src'>): void =>
void out.push({ src: rewriteToRemoteMediaOrigin(url, mediaOrigin), ...meta });
const out: GalleryImage[] = [];
const ghostCardSpawnIndex = ghostCards ? createGhostCardSpawnIndex(ghostCards) : undefined;
for (const item of items) {
if (item.type === 'fork_origin') {
continue;
} else if (item.type === 'tool_media') {
for (const m of item.items) {
if (m.kind === 'image' && m.url) push(m.url);
}
} else if (item.type === 'ghost_card') {
if (ghostCards) {
for (const image of collectGhostCardGalleryImages(
item.callId,
ghostCards,
!item.settled && isSessionStreaming,
ghostCardSpawnIndex!,
)) {
push(image.src, { galleryId: image.galleryId });
}
}
// 回锚媒体渲染在卡片及其衍生卡之后,画廊顺序必须与 DOM 一致。
for (const media of item.media ?? []) {
if (media.kind === 'image' && media.url) push(media.url);
}
} else if (item.type === 'message') {
const msg = item.message;
if (msg.role === 'user' && msg.images) {
for (const img of msg.images) {
if ('url' in img) {
// 标注元数据只在本地会话下发:远程会话里 annotationSourceUrl 指向
// 被控端本机缓存,控制端拿不到原图,翻页保持普通烧录图预览(与
// ChatImageView 直接点击分支的 displaySrc !== src 防御同口径)。
const meta =
!mediaOrigin && img.annotationSourceUrl && img.annotationStrokes?.length
? {
annotationSourceUrl: img.annotationSourceUrl,
annotationStrokes: img.annotationStrokes,
}
: undefined;
push(img.url, meta);
} else {
push(`data:${img.mimeType};base64,${img.base64}`);
}
}
} else if (msg.role === 'assistant' && ghostCards) {
// will-assistant-message 出口钩子的自绘卡以消息 clientId 为根 callId。
for (const image of collectGhostCardGalleryImages(
msg.clientId,
ghostCards,
false,
ghostCardSpawnIndex!,
)) {
push(image.src, { galleryId: image.galleryId });
}
}
}
}
return out;
}
// Workflow 工具(Claude Code SDK 多 agent 编排)在父会话事件流里 = 单个 local_workflow
// 任务(内部子 agent 不发独立 task 事件,只有 workflow 级聚合进度)。与 Agent/Task 一样
// 走 agent_task 渲染项;AgentTaskCard 内部按 taskType/toolName 识别为 workflow,展示
// workflowName + 聚合进度(status / tokens / 工具数 / 耗时)。
function isWorkflowToolName(toolName: string): boolean {
return toolName === 'Workflow';
}
function findTaskUpdate(
taskUpdates: ReadonlyMap<string, AgentTaskUpdate> | undefined,
toolCall: ChatMessage,
): AgentTaskUpdate | undefined {
if (!taskUpdates) return undefined;
if (toolCall.toolUseId) {
const byToolUseId = taskUpdates.get(toolCall.toolUseId);
if (byToolUseId) return byToolUseId;
}
return taskUpdates.get(toolCall.clientId);
}
/**
* subagent-model-chip: 构建 parentToolUseId(= 父 Agent/Task 工具调用的 toolUseId)
* → 子代理模型 raw id 的映射。
*
* 数据来源:subagent 的每条子消息都带 `parentToolUseId`(SDK parent_tool_use_id,
* 即派生它的 Agent 工具调用 id)+ `model`(子代理实际跑的模型)。first-writer-wins
* 收敛 —— 同一子代理的所有子消息 model 相同,先到先得即可保持稳定。
*
* 必须喂全量 `messages`:子消息与 Agent 行常落在不同 render item / segment,
* segment-local 扫不全。多个并发 Agent 调用天然各占一条 entry(各自 toolUseId)。
*
* 反查精确性:map 的 key 只可能是 Agent/Task 调用的 toolUseId(普通工具的
* toolUseId 不会被任何子消息当作 parent),所以下游按 row.toolUseId 反查时,
* 只有真正的 Agent/Task 行会命中。
*
* export 仅供单测使用,运行时无外部消费者。
*/
export function buildSubagentModelMap(messages: ChatMessage[]): Map<string, string> {
const out = new Map<string, string>();
for (const m of messages) {
if (m.parentToolUseId && m.model && !out.has(m.parentToolUseId)) {
out.set(m.parentToolUseId, m.model);
}
}
return out;
}
/**
* 子代理内部消息判据:这条消息是不是某个 Agent/Task 调用**内部**产生的,而不是
* 父会话自己说的话。
*
* 数据来源与 buildSubagentModelMap 同一份:SDK 给子代理的每条消息都带
* `parent_tool_use_id`(= 派生它的 Agent 工具调用 id),经 makerChatStore 投影成
* 顶层 `parentToolUseId`(实时事件与历史重载两条路径都投影)。
*
* 形态判据不能省:legacy Claude 导入把普通 transcript 链边(`preceding-user-uuid`
* 这类非 tool-use id)也存进同一个字段,无条件当子代理会把父会话自己的正文一起
* 吞掉。只认 SDK tool-parent 形态,与 maker-shared 的投影判据共用同一个函数。
*/
export function isSubagentInternalMessage(message: ChatMessage): boolean {
const parent = message.parentToolUseId;
return typeof parent === 'string' && parent.length > 0 && isSubagentParentToolUseId(parent);
}
/**
* 「用户实际看得见的那份消息序列」——剔除子代理内部行后的视图。
*
* 所有**面向可见 UI 的派生**都必须吃这一份,不能各自去扫原始数组:turn 边界、
* 「最后一条 user 消息」这类判断一旦把不可见行算进去,可见气泡就会丢掉编辑入口、
* 运行态标记与 action bar —— 同一类坑此前已被 `isSyntheticTrigger` 行踩过一次
* (见 `findLastUserMessageClientId` 的注释),子代理内部行是第二类不可见行
* (review: codex P2)。
*
* 反面:`buildSubagentModelMap` 之类**按子代理归属反查**的派生必须继续吃原始序列,
* 它要的恰恰是这些被隐藏的行。
*
* 没有子代理消息时返回同一个引用,useMemo 下游不产生额外重算。
*/
export function selectVisibleMessages(messages: ChatMessage[]): ChatMessage[] {
return messages.some(isSubagentInternalMessage)
? messages.filter((m) => !isSubagentInternalMessage(m))
: messages;
}
/**
* Cindy Make and /review cards are appended as local assistant system messages,
* but each represents a new command turn for the visible timeline. Treating them
* as boundaries keeps the preceding turn's artifacts and change summary before
* the card instead of below it.
*/
function isRenderTurnBoundary(message: ChatMessage): boolean {
if (message.role === 'user') {
return message.delivery !== 'steer' && !message.isSyntheticTrigger;
}
return (
message.role === 'assistant' &&
(message.systemCardType === 'cindy-make' ||
message.systemCardType === 'cindy-make-doctor' ||
message.systemCardType === 'review')
);
}
function ghostCardInstanceId(ghostId: string, namespace: unknown): string | null {
if (!isValidGhostId(ghostId)) {
const identity = parsePluginInstanceId(ghostId);
return identity && namespace === undefined ? pluginStoragePart(identity) : null;
}
if (namespace === null || namespace === undefined) return ghostId;
return typeof namespace === 'string' && isValidPluginNamespace(namespace)
? pluginStoragePart({ namespace, ghostId })
: null;
}
/** Summon labels retain explicit root identity; card/media anchoring keeps its existing keys. */
function ghostSummonInstanceId(ghostId: string, namespace: unknown): string | null {
const id = ghostCardInstanceId(ghostId, namespace);
if (!id) return null;
const explicitRoot =
namespace === null ||
(namespace === undefined &&
!isValidGhostId(ghostId) &&
parsePluginInstanceId(ghostId)?.namespace === null);
return explicitRoot
? pluginInstallStoragePart(pluginNewInstallRelId({ namespace: null, ghostId: id }))
: id;
}
export function buildRenderItems(
allMessages: ChatMessage[],
taskUpdates?: ReadonlyMap<string, AgentTaskUpdate>,
ghostCards?: GhostCardSnapshot,
opts?: {
/** Live cards must belong to this task; explicit result IDs support history/forks. */
sessionId?: string;
/**
* 还有更老的历史页没加载(= `messages` 只是窗口、不是全量)。为真时,凡靠
* 「父调用在不在 messages 里」做的归属判定都不可信,必须放宽而不是丢弃。
*/
historyWindowIncomplete?: boolean;
/** Main-persisted exact patches, anchored to their visible user message. */
turnChangeSets?: readonly TurnChangeSetSummary[];
/** Session working directory for opaque generated-file fallback chips. */
workingDir?: string;
historyArtifacts?: readonly import('@cindy/maker-shared/message-window').HistoryFileArtifact[];
/** Bot-owned Session: show newly created files as deliverables, not an engineering diff card. */
botSessionId?: string;
activeVoiceCallId?: string | null;
/** Reuse image Markdown extraction for completed assistant messages across stream batches. */
markdownImageTargetCache?: MarkdownImageTargetCache;
/** Keep the stored preparation report out of its own task's visible timeline. */
cindyMakeSessionId?: string;
cindyMakeCompletionInComposer?: boolean;
/** Durable Subagent status; a terminal record outranks the paired result text. */
subagentRunStatuses?: SubagentRunStatusIndex;
},
): {
items: RenderItem[];
singleResultMap: Map<string, string>;
} {
// Modal-only Cindy Make cards are transient UI state. They stay in the
// shared store for the dialog to observe, but never enter the chat timeline.
allMessages = allMessages.filter(
(message) =>
// History snapshots bypass the task view's raw-list filter. Keep this
// rule at the shared render boundary, before time/turn/work grouping.
isVisibleVoiceCallMessage(message, opts?.activeVoiceCallId) &&
message.systemCardData?.modalOnly !== true &&
!(opts?.cindyMakeCompletionInComposer && isCindyMakeCompletionMessage(message)) &&
!isCindyMakePreparationMessage(message, opts?.cindyMakeSessionId),
);
if (opts?.botSessionId) {
allMessages = placeBotTaskCardsAfterIntroduction(allMessages, (message) => {
if (message.role === 'user') {
return message.delivery !== 'steer' || message.isSyntheticTrigger ? 'boundary' : 'other';
}
if (isSubagentInternalMessage(message)) return 'other';
if (message.systemCardType === 'bot-session-task') return 'task';
return message.role === 'assistant' && !message.systemCardType && message.content.trim()
? 'prose'
: 'other';
});
}
// ── Pass -1: 剔除子代理内部消息 ──
// 后台 Agent/Task 跑起来后,SDK 会把子代理自己的 thinking / 正文 / 工具调用一并
// echo 回主流(每条都带 parent_tool_use_id)。这些是**子任务内部的经过**,不是父
// 会话对用户说的话 —— 官方 CLI 界面从不显示它们,Cindy 逐条渲染就等于把整篇子代理
// 报告原样铺进聊天窗口(实测一条子代理正文 5.5k 字符直接刷屏)。
//
// 它们的去处是自己那张 AgentTaskCard(仍由 taskUpdates 正常渲染),不是主流。
// 过滤放在最前面:后续所有 pass(tool_result lookup、段落配对、turn 边界、work-group)
// 看到的都是同一份"用户可见"的消息序列,不会出现"查得到但不渲染"的半吊子状态。
const hasSubagentInternalMessages = allMessages.some(isSubagentInternalMessage);
// 过滤后下标 → 原始下标。**产物**类派生(生成文件 chip、媒体卡)必须回到原始序列取
// turn 切片:子代理用 Write / Bash 建的文件、出图出片工具返回的媒体都是真实产物,
// 只是承载它们的工具行不该渲染;只喂过滤后的切片会让这些卡静默消失(review: codex P2)。
const originalIndexByVisible: number[] = [];
const messages = hasSubagentInternalMessages
? allMessages.filter((m, idx) => {
if (isSubagentInternalMessage(m)) return false;
originalIndexByVisible.push(idx);
return true;
})
: allMessages;
/**
* 把过滤后的 turn 区间 `[lo, hi)` 映射回原始序列的区间,使产物收集能看到被隐藏的
* 子代理工具调用。`hi` 落在末尾时右端取 `allMessages.length`,保证最后一个 turn
* 也覆盖到它后面的子代理尾巴。
*/
const originalTurnSlice = (lo: number, hi: number): readonly ChatMessage[] => {
if (!hasSubagentInternalMessages) return messages.slice(lo, hi);
const start = originalIndexByVisible[lo];
if (start === undefined) return messages.slice(lo, hi);
const end =
hi < originalIndexByVisible.length ? originalIndexByVisible[hi] : allMessages.length;
return allMessages.slice(start, end);
};
// Agent 最终正文中的 Markdown 图片是首选排版;tool_result 媒体仍保留为
// 确定性兜底。只有同一真实 user turn 内确实嵌入了同一 URL,才压掉兜底卡。
const inlineImageUrlsByTurnStart = new Map<number, ReadonlySet<string>>();
const recordTurnInlineImages = (lo: number, hi: number): void => {
if (hi <= lo) return;
const urls = new Set<string>();
for (const message of messages.slice(lo, hi)) {
if (message.role !== 'assistant' || message.systemCardType || message.isStreaming) continue;
const imageTargets = opts?.markdownImageTargetCache
? extractCachedRenderedMarkdownImageTargets(
message.content,
opts.markdownImageTargetCache,
message.clientId,
)
: extractRenderedMarkdownImageTargets(message.content);
for (const url of imageTargets) urls.add(url);
}
inlineImageUrlsByTurnStart.set(lo, urls);
};
let inlineTurnStart = 0;
for (let index = 0; index <= messages.length; index += 1) {
const message = messages[index];
const isBoundary = message ? isRenderTurnBoundary(message) : false;
if (isBoundary && index > inlineTurnStart) {
recordTurnInlineImages(inlineTurnStart, index);
inlineTurnStart = index;
}
if (index === messages.length) recordTurnInlineImages(inlineTurnStart, index);
}
// ── Pass 0: build toolUseId → tool_result.content lookup ──
// Plan/task rendering and regular tool result pairing both need a stable
// lookup by vendor toolUseId. Adjacency remains a fallback in Pass 2.
const resultByToolUseId = new Map<string, string>();
// toolUseId → tool_result.createdAt(ms)。段的结束时间要算进 result,见
// ToolSegmentRenderItem.resultTsMap 的注释。
const resultTsByToolUseId = new Map<string, number>();
// 卡槽③:已被某条 tool_result 认领的卡(xdt_card_id)——活卡锚定要跳过
// 这些,防止 settle 后同一张卡又被别的 in-flight 行启发式抢走。
const settledCardIds = new Set<string>();
for (const m of messages) {
if (m.role === 'tool_result' && typeof m.toolUseId === 'string' && m.toolUseId.length > 0) {
resultByToolUseId.set(m.toolUseId, m.content);
const resultMs = Date.parse(m.createdAt ?? '');
if (Number.isFinite(resultMs)) resultTsByToolUseId.set(m.toolUseId, resultMs);
const cardId = extractGhostCardId(m.content);
if (cardId) settledCardIds.add(cardId);
}
}
// ── Pass 1: group plan events into timeline cards ──
// 分组与 composer 兜底胶囊共用 maker-shared 的同一口径。历史窗口不完整时
// Task* 计划先不画半张卡,等更早页补齐后再由同一 stable key 插入。
const planInsertAt = findMessageTodoInsertions(messages, {
taskHistoryMayBeIncomplete: opts?.historyWindowIncomplete === true,
});
// findMessageTodoInsertions 负责完整历史时间线,不会自行裁掉分页窗口里的半截
// Task session。不能只检查整窗「最新」计划:后面若已有可解析的新 session,
// 较早的半截 Task 卡仍会漏出来。逐个 Task insertion 用其前缀复核,等 prepend
// 补齐标题/早期 TaskCreate 后再由同一 stable key 插回。
let needsTaskHistoryValidation = false;
if (opts?.historyWindowIncomplete === true) {
for (const insertion of planInsertAt.values()) {
if (insertion.source === 'task') {
needsTaskHistoryValidation = true;
break;
}
}
}
// Ordinary tool history and TodoWrite/update_plan need no Task prefix validation.
if (needsTaskHistoryValidation) {
// Build the indexes once. The old validation path rescanned the whole
// prefix and filtered the whole suffix for every Task insertion. A paged
// history window can contain many task rows, so keep message order while
// looking up only plan ids and their late results.
const planToolUseCountAtInsertion = new Map<number, number>();
const toolResultsByUseId = new Map<
string,
Array<{ index: number; message: ChatMessage }>
>();
const planToolUseIds: string[] = [];
for (let messageIndex = 0; messageIndex < messages.length; messageIndex += 1) {
const message = messages[messageIndex];
if (message.role === 'tool_result' && typeof message.toolUseId === 'string') {
const results = toolResultsByUseId.get(message.toolUseId) ?? [];
results.push({ index: messageIndex, message });
toolResultsByUseId.set(message.toolUseId, results);
}
if (
isAgentPlanToolName(message.toolName)
&& typeof message.toolUseId === 'string'
&& message.toolUseId.length > 0
) {
planToolUseIds.push(message.toolUseId);
}
if (planInsertAt.has(messageIndex)) {
planToolUseCountAtInsertion.set(messageIndex, planToolUseIds.length);
}
}
for (const [index, insertion] of planInsertAt) {
if (insertion.source !== 'task') continue;
const prefix = messages.slice(0, index + 1);
const prefixPlanToolUseIds = new Set<string>();
const planToolUseCount = planToolUseCountAtInsertion.get(index) ?? 0;
for (let planIndex = 0; planIndex < planToolUseCount; planIndex += 1) {
prefixPlanToolUseIds.add(planToolUseIds[planIndex]);
}
// TaskList / TaskGet 的权威内容在后续 tool_result 行里。只切到工具行会把
// 已完整的 snapshot 重新判成半截;保留当前前缀中计划调用的匹配结果,但
// 不把后续计划事件带进来,避免改变「正在复核哪张 insertion」的语义。
const lateResults: Array<{ index: number; message: ChatMessage }> = [];
for (const toolUseId of prefixPlanToolUseIds) {
for (const result of toolResultsByUseId.get(toolUseId) ?? []) {
if (result.index > index) lateResults.push(result);
}
}
if (lateResults.length > 1) lateResults.sort((left, right) => left.index - right.index);
const validationMessages = prefix;
for (const result of lateResults) validationMessages.push(result.message);
const stateAtInsertion = getLatestMessageTodoState(validationMessages, {
taskHistoryMayBeIncomplete: true,
});
if (!stateAtInsertion.isResolved || stateAtInsertion.latestInsertionIndex !== index) {
planInsertAt.delete(index);
}
}
}
const isOrcaCommunicationTool = (toolName: string): boolean => {
const normalized = toolName.replace(/^mcp__/, 'mcp:').replace(/__/g, ':');
return (
normalized === 'mcp:orca_worker_bridge:send_to_lead' ||
normalized === 'mcp:orca_worker_bridge:read_lead' ||
normalized === 'mcp:orca_worker_bridge:lead_status' ||
toolName === 'send_to_lead' ||
toolName === 'read_lead' ||
toolName === 'lead_status'
);
};
const isEmptyOrcaCommunicationResult = (content: string): boolean => {
const trimmed = content.trim();
if (!trimmed) return true;
try {
const parsed = JSON.parse(trimmed) as unknown;
if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return false;
const record = parsed as Record<string, unknown>;
const hasUserFacingContent = ['message', 'result', 'text', 'content', 'error', 'detail'].some(
(key) => typeof record[key] === 'string' && record[key].trim().length > 0,
);
if (hasUserFacingContent) return false;
return record.ok === true;
} catch {
return false;
}
};
const shouldHideToolResult = (toolName: string, content: string): boolean =>
isOrcaCommunicationTool(toolName) && isEmptyOrcaCommunicationResult(content);
// ── Pass 1.5: toolUseId lookup already built in Pass 0 ──
// 为什么需要这一步: Pass 2 原本只按"tool_result 紧跟 tool_use"的 adjacency 配对
// (见 while 循环)。但对 SDK 不发 tool_use_summary 的工具(如返回 image content
// block 的 MCP),renderer 在 case 'done' 里自建 orphan
// tool_result 并 append 到 messages 末尾,顺序上不再紧邻 tool_use → adjacency
// 配不上。改用 toolUseId 直接查表(主路径),adjacency 只作为旧数据兜底
// (toolUseId 字段缺失或老消息没存的情况)。
// ── Pass 2: linear build ──
const items: RenderItem[] = [];
const renderedTaskKeys = new Set<string>();
const singleResultMap = new Map<string, string>();
let pendingToolCalls: ChatMessage[] = [];
let pendingResultMap = new Map<string, string>();
// 段内 tool_use clientId → tool_result.createdAt(ms),见 resultTsMap 注释。
let pendingResultTsMap = new Map<string, number>();
// 段内已见过的最晚**结束**时间(调用发起时刻与其 tool_result 时间取 max)。空洞判定用它,
// 增量维护而不是每条调用重扫一遍 pendingToolCalls —— 工具密集的长 turn 里那是 O(n²)
// (#676 review copilot)。flushSegment 时复位。
let pendingSegmentEndMs: number | null = null;
const notePendingSegmentEnd = (ms: number | null | undefined): void => {
if (ms === null || ms === undefined || !Number.isFinite(ms)) return;
pendingSegmentEndMs = pendingSegmentEndMs === null ? ms : Math.max(pendingSegmentEndMs, ms);
};
// 状态判定专用:tool_result 已到达的 tool_use(含被 shouldHideToolResult
// 隐藏、不进 resultMap 的空结果)。
let pendingSettledIds = new Set<string>();
// tool-result-media: 累积当前 segment 内所有 tool_result 提取出的媒体 (image/video),
// segment flush 时单独 push 一个 'tool_media' item,让媒体显示在 tool_segment 外面。
let pendingSegmentMedia: ToolMediaItem[] = [];
// 卡槽③:当前 segment 内累计的意识卡片(与 tool_media 同节奏 flush,
// 每张卡各自锚定自己的 ghost_call clientId,不像媒体那样按段合并)。
let pendingSegmentGhostCards: Extract<RenderItem, { type: 'ghost_card' }>[] = [];
// 本次 build 内已被认领的活卡(claude 精确锚 / codex 启发式各认领一次)。
const claimedLiveCallIds = new Set<string>();
const sessionLiveCards = opts?.sessionId
? ghostCards?.liveCards.filter(lc => lc.sessionId === opts.sessionId) ?? []
: [];
// Mail is a finished document, not plugin progress. Without an exact tool ID,
// wait for its result rather than attach it to a schema/read call by guesswork.
const guessableLiveCards = sessionLiveCards.filter(lc => {
const entry = ghostCards?.byCallId.get(lc.callId);
return !(entry?.status === 'ready' && readMailCard(entry.html));
});
// Old partial history may omit a tool result. It cannot claim a new card just
// because the same plugin was used there. Exact IDs still work across turns.
const latestTurnStart = messages.findLastIndex(isRenderTurnBoundary);
// 媒体回锚:本次 build 已上屏的 ghost_card item 按 callId 索引。后续调用的
// tool_result 带 xdt_anchor_card_id 时按此把媒体挂回对应卡下方(item 是引用,
// flush 进 items 后追加 media 仍然生效)。
const ghostCardItemByCallId = new Map<string, Extract<RenderItem, { type: 'ghost_card' }>>();
const flushSegment = () => {
// 段内全部工具行都因供卡隐身时,段本体不渲染,卡片仍要落地。
if (pendingToolCalls.length === 0) {
for (const gc of pendingSegmentGhostCards) items.push(gc);
pendingSegmentGhostCards = [];
return;
}
// key 派生自 segment 首 toolCall clientId — 与历史 React `key=` (`seg-${...}`)
// 同源,保证流式中新 tool_use 加入现有 segment 时 toolCalls[0] 不变 → key 稳定。
const segmentKey = `seg-${pendingToolCalls[0].clientId}`;
items.push({
type: 'tool_segment',
key: segmentKey,
toolCalls: pendingToolCalls,
resultMap: pendingResultMap,
resultTsMap: pendingResultTsMap,
settledIds: pendingSettledIds,
});
if (pendingSegmentMedia.length > 0) {
// De-dup by url so multi-tool-call segments don't show same image twice.
// Preserve insertion order so the order in chat matches tool-call order.
const seen = new Set<string>();
const dedup = pendingSegmentMedia.filter((m) => {
if (seen.has(m.url)) return false;
seen.add(m.url);
return true;
});
// tool_media 跟其派生来源的 segment 共用首 toolCall id,只是 prefix 不同,
// 保证两个 item 不撞 key,且都跟所属 segment 共生 / 同稳定性。
items.push({
type: 'tool_media',
key: `media-${pendingToolCalls[0].clientId}`,
items: dedup,
});
}
// 意识卡片跟在媒体后(通常互斥:供卡的调用其媒体贡献已被抑制;同段
// 其它工具的媒体仍在上面正常渲染)。
for (const gc of pendingSegmentGhostCards) items.push(gc);
pendingToolCalls = [];
pendingResultMap = new Map<string, string>();
pendingResultTsMap = new Map<string, number>();
pendingSegmentEndMs = null;
pendingSettledIds = new Set<string>();
pendingSegmentMedia = [];
pendingSegmentGhostCards = [];
};
let turnStartIdx = 0;
const flushTurnChanges = (lo: number, hi: number): void => {
if (hi <= lo) return;
const anchorClientId = messages[lo]?.clientId;
if (!anchorClientId) return;
const changeSets = (opts?.turnChangeSets ?? []).filter(
(changeSet) => changeSet.anchorClientId === anchorClientId,
);
const exactPaths = new Set<string>();
const pathKey = (value: string): string => {
const normalized = value.replace(/\\/g, '/');
const windowsShape = /^[a-zA-Z]:[\\/]/.test(value) || value.includes('\\');
return windowsShape ? normalized.toLowerCase() : normalized;
};
for (const changeSet of changeSets) {
for (const file of changeSet.files) {
const resolved = resolveToolFilePath(file.path, changeSet.cwd);
exactPaths.add(pathKey(resolved));
if (file.oldPath) exactPaths.add(pathKey(resolveToolFilePath(file.oldPath, changeSet.cwd)));
}
}
if (!opts?.botSessionId) {
for (const changeSet of changeSets) {
// Zero-file entries have nothing the user can inspect or act on. Keep their
// diagnostic sidecars in Main, but do not add a warning-only chat card.
if (!hasReviewableTurnChanges(changeSet)) continue;
items.push({
type: 'turn_changes',
key: `turnchanges-${changeSet.id}`,
changeSet,
});
}
}
// 子代理工具结果里的媒体产物(出图 / 视频 / 音频 / 模型)。这些工具行本身被隐藏,
// 不进 tool_segment,所以段级的 pendingSegmentMedia 收不到它们;而 AgentTaskUpdate
// 没有承载媒体的字段,不补这一路产物卡就会随内部工具行一起消失(review: codex P2)。
// 归属到 turn 一级,与产物文件卡同一处理方式。
//
// 只收**被隐藏的**那部分:可见工具行的媒体照旧走 tool_segment,不能在这里重复渲染。
// ghost_call 的锚卡逻辑不在这条路径上——子代理不参与意识卡片的开卡/锚定。
if (hasSubagentInternalMessages) {
const hiddenMedia: ToolMediaItem[] = [];
const seenMediaUrls = new Set<string>();
for (const message of originalTurnSlice(lo, hi)) {
if (message.role !== 'tool_result' || !isSubagentInternalMessage(message)) continue;
for (const item of extractToolResultMedia(message.content)) {
if (item.kind === 'image' && inlineImageUrlsByTurnStart.get(lo)?.has(item.url)) {
continue;
}
if (seenMediaUrls.has(item.url)) continue;
seenMediaUrls.add(item.url);
hiddenMedia.push(item);
}
}
if (hiddenMedia.length > 0) {
items.push({
type: 'tool_media',
key: `subagent-media-${anchorClientId}`,
items: hiddenMedia,
});
}
}
const slice = originalTurnSlice(lo, hi);
const generatedByPath = new Map<string, GeneratedFileRef>();
if (opts?.botSessionId) {
for (const changeSet of changeSets) {
for (const file of changeSet.files) {
if (file.status !== 'added') continue;
const resolved = resolveToolFilePath(file.path, changeSet.cwd);
generatedByPath.set(pathKey(resolved), {
path: resolved,
name: basename(file.path),
source: 'tool',
ready: true,
});
}
}
}
const workingDir = opts?.workingDir ?? '';
if (workingDir) {
const start = Date.parse(messages[lo]?.createdAt ?? '');
const end = Date.parse(messages[hi]?.createdAt ?? '');
const artifacts = (opts?.historyArtifacts ?? []).filter((artifact) => {
const time = Date.parse(artifact.createdAt);
return !(Number.isFinite(start) && time < start || Number.isFinite(end) && time >= end);
});
const editedPaths = new Set(artifacts.filter((file) => file.exclude && file.ready)
.map((file) => pathKey(resolveToolFilePath(file.path, workingDir))));
for (const artifact of artifacts) {
const path = resolveToolFilePath(artifact.path, workingDir);
const normalized = pathKey(path);
if (artifact.exclude) {
if (artifact.exclude === 'all' && artifact.ready) generatedByPath.delete(normalized);
continue;
}
if (artifact.source === 'command' && editedPaths.has(normalized)) continue;
if (exactPaths.has(normalized) && changeSets.length > 0) continue;
const previous = generatedByPath.get(normalized);
if (previous?.source === 'tool' && artifact.source === 'command') continue;
generatedByPath.set(normalized, { path, name: basename(path), source: artifact.source, ready: artifact.ready });
}
for (const file of collectCachedGeneratedFiles(slice, workingDir)) {
const normalized = pathKey(file.path);
if (exactPaths.has(normalized) && changeSets.length > 0) continue;
generatedByPath.set(normalized, file);
}
// Delivery tools stay as visible source rows. Preserve their existing
// intermediate-file suppression for paths produced by deferred tools too.
for (const message of slice) {
if (message.role !== 'tool_use') continue;
const descriptor = describeToolUse(message.toolName ?? '', message.toolInput);
for (const path of sourcePathCandidatesFromDescriptor(descriptor)) {
generatedByPath.delete(pathKey(resolveToolFilePath(path, workingDir)));
}
}
}
const generatedFiles = [...generatedByPath.values()];
if (generatedFiles.length === 0) return;
let turnStartMs: number | null = null;
for (const message of slice) {
const timestamp = Date.parse(message.createdAt ?? '');
if (Number.isFinite(timestamp) && (turnStartMs === null || timestamp < turnStartMs)) {
turnStartMs = timestamp;
}
}
const boundaryTimestamp = Date.parse(messages[hi]?.createdAt ?? '');
const hasFollowingUser = hi < messages.length;
const turnSealed = isGeneratedFilesTurnSealed(slice, hasFollowingUser);
items.push({
type: 'generated_files',
key: `genfiles-${messages[lo].clientId}`,
files: generatedFiles,
turnStartMs,
turnEndMs: Number.isFinite(boundaryTimestamp) ? boundaryTimestamp : null,
turnSealed,
});
};
let i = 0;
while (i < messages.length) {
const msg = messages[i];
// Turn boundary: attach the sealed patch after the turn it belongs to.
// Cindy Make cards are local command messages and start their own visible turn,
// so the preceding turn's file-change card stays above them.
if (isRenderTurnBoundary(msg)) {
flushSegment();
flushTurnChanges(turnStartIdx, i);
turnStartIdx = i;
}
// ask_user: pending lives in the bottom input overlay; expired/unanswered
// questions have no user selection to show. Only the answered state surfaces
// in the stream — rendered by AskUserQuestionBubble so the choice the user
// made stays visible after the agent moves on.
if (msg.role === 'ask_user' && msg.askUserStatus !== 'answered') {
i++;
continue;
}
if (msg.role === 'tool_use') {
const toolName = msg.toolName ?? '';
// F7: AskUserQuestion / ExitPlanMode are filtered out entirely. They
// do NOT cut the current tool_segment — surrounding tools stay
// grouped as if these calls never existed.
if (toolName === 'AskUserQuestion' || toolName === 'ExitPlanMode') {
let j = i + 1;
while (j < messages.length && messages[j].role === 'tool_result') j++;
i = j;
continue;
}
// Plan tools (TodoWrite / update_plan / Task*)由流内计划卡取代。只有
// session 的最新快照所在行插卡;中间更新只刷新同一 stable-key 卡片。
if (isAgentPlanToolName(toolName)) {
const insertion = planInsertAt.get(i);
// 与悬浮胶囊保持一致:单步清单不占计划 UI;没有可画卡片时也不切开
// 周围工具段,保留旧的紧凑聚组语义。
if (insertion && insertion.todos.length >= 2) {
flushSegment();
items.push({
type: 'agent_plan',
key: insertion.key,
todos: insertion.todos,
sourceClientIds: insertion.sourceClientIds,
createdAt: msg.createdAt,
});
}
let j = i + 1;
while (j < messages.length && messages[j].role === 'tool_result') j++;
i = j;
continue;
}
if (isAgentTaskToolName(toolName) || isWorkflowToolName(toolName)) {
flushSegment();
let result =
typeof msg.toolUseId === 'string' && msg.toolUseId.length > 0
? resultByToolUseId.get(msg.toolUseId)
: undefined;
// 结束时间:主路径按 toolUseId 查,adjacency 兜底取相邻 tool_result 的最新时间。
let resultTsMs =
typeof msg.toolUseId === 'string' && msg.toolUseId.length > 0
? resultTsByToolUseId.get(msg.toolUseId)
: undefined;
let j = i + 1;
while (j < messages.length && messages[j].role === 'tool_result') {
if (result === undefined && !shouldHideToolResult(toolName, messages[j].content)) {
result = messages[j].content;
}
const adjacentTs = Date.parse(messages[j].createdAt ?? '');
if (
Number.isFinite(adjacentTs) &&
(resultTsMs === undefined || adjacentTs > resultTsMs)
) {
resultTsMs = adjacentTs;
}
j++;
}
const update = findTaskUpdate(taskUpdates, msg);
const durableStatus = lookupSubagentRunStatus(
opts?.subagentRunStatuses,
msg.toolUseId,
update,
);
if (msg.toolUseId) renderedTaskKeys.add(msg.toolUseId);
if (update?.taskId) renderedTaskKeys.add(update.taskId);
if (update?.parentToolUseId) renderedTaskKeys.add(update.parentToolUseId);
items.push({
type: 'agent_task',
key: `task-${msg.clientId}`,
toolCall: msg,
update,
...(msg.agentTaskStatus ? { persistedStatus: msg.agentTaskStatus } : {}),
...(durableStatus ? { durableStatus } : {}),
...(result !== undefined && !shouldHideToolResult(toolName, result) ? { result } : {}),
...(resultTsMs !== undefined ? { resultTsMs } : {}),
});
i = j;
continue;
}
// ── 卡槽③:ghost_call 的卡片配对/锚定(先算,决定行/媒体去留)──
// 卡片是这次调用的**唯一呈现**(2026-07-12 Lizi 定案:行与卡信息重复,
// 合并进卡):配上卡的 ghost_call 不进 tool_segment(工具行隐身),
// 原始调用参数由卡片头带展开区承担;同时抑制自己的媒体贡献。
// settled:tool_result 顶层 xdt_card_id → 卡片库取卡;missing(远程
// 会话/被 GC)完全回退今日渲染(行 + generic 媒体);loading/未知先
// 藏行藏媒体(取件毫秒级落定,避免"行闪现再消失"跳变,规则 7)。
// in-flight:活卡先按 toolUseId 精确锚(claude),再按同 ghostId 的
// 最早未认领活卡启发式锚(codex);settle 后 xdt_card_id 自校正。
let suppressMediaForCard = false;
let hideRowForCard = false;
const maybeQueueGhostCard = (result: string | undefined): void => {
if (!ghostCards || !isGhostCallToolName(toolName)) return;
const inp = (msg.toolInput ?? null) as Record<string, unknown> | null;
const ghostIdFromInput = typeof inp?.ghost_id === 'string' ? inp.ghost_id : '';
const candidateGhostId = ghostCardInstanceId(ghostIdFromInput, inp?.namespace);
const toolFromInput = typeof inp?.tool === 'string' ? inp.tool : '';
if (result !== undefined) {
const cardId = extractGhostCardId(result);
if (!cardId) return;
const entry = ghostCards.byCallId.get(cardId);
if (entry?.status === 'missing') return; // 降级 generic,行照旧
suppressMediaForCard = true;
hideRowForCard = true;
if (entry?.status === 'ready') {
if (readMailCard(entry.html)?.supersededBy) return;
const cardItem: Extract<RenderItem, { type: 'ghost_card' }> = {
type: 'ghost_card',
key: `ghostcard-${msg.clientId}`,
callId: cardId,
ghostId: entry.ghostId,
tool: toolFromInput,
toolCall: msg,
settled: true,
resultTsMs:
typeof msg.toolUseId === 'string'
? resultTsByToolUseId.get(msg.toolUseId)
: undefined,
};
pendingSegmentGhostCards.push(cardItem);
ghostCardItemByCallId.set(cardId, cardItem);
}
return;
}
// in-flight:只认已 ready 的活卡(推送带 html 全量到,ready 是常态)。
const live =
sessionLiveCards.find(
(lc) =>
!claimedLiveCallIds.has(lc.callId) &&
!settledCardIds.has(lc.callId) &&
lc.toolUseId !== null &&
typeof msg.toolUseId === 'string' &&
lc.toolUseId === msg.toolUseId,
) ??
(candidateGhostId && i >= latestTurnStart
? guessableLiveCards.find(
(lc) =>
!claimedLiveCallIds.has(lc.callId) &&
!settledCardIds.has(lc.callId) &&
lc.toolUseId === null &&
((lc.logicalGhostId ?? lc.ghostId) === candidateGhostId ||
(lc.logicalGhostId === undefined && inp?.namespace === undefined &&
lc.ghostId === candidateGhostId)),
)
: undefined);
if (!live) return;
const liveEntry = ghostCards.byCallId.get(live.callId);
if (liveEntry?.status !== 'ready') return;
claimedLiveCallIds.add(live.callId);
hideRowForCard = true;
if (readMailCard(liveEntry.html)?.supersededBy) { suppressMediaForCard = true; return; }
const liveCardItem: Extract<RenderItem, { type: 'ghost_card' }> = {
type: 'ghost_card',
key: `ghostcard-${msg.clientId}`,
callId: live.callId,
ghostId: live.ghostId,
tool: toolFromInput,
toolCall: msg,
settled: false,
};
pendingSegmentGhostCards.push(liveCardItem);
ghostCardItemByCallId.set(live.callId, liveCardItem);
};
// 媒体收集:结果带 xdt_anchor_card_id(ghost_call 的"提交开卡 → 轮询出
// 媒体"跨调用任务)且锚到的是**同一意识**已上屏的卡时,把媒体挂到那张卡
// item 的 media 上(卡正下方渲染,替换"生成中"占位);锚不上(卡 missing/
// 提交消息被 rewind/异 ghost 伪锚)回退今日行为——本调用位置渲染。
const collectResultMedia = (result: string): void => {
let media = extractToolResultMedia(result);
const inlineImageUrls = inlineImageUrlsByTurnStart.get(turnStartIdx);
if (inlineImageUrls?.size) {
media = media.filter((item) => item.kind !== 'image' || !inlineImageUrls.has(item.url));
}
if (media.length === 0) return;
if (isGhostCallToolName(toolName)) {
const anchor = extractAnchorCardId(result);
const inp = (msg.toolInput ?? null) as Record<string, unknown> | null;
const ghostIdFromInput = typeof inp?.ghost_id === 'string' ? inp.ghost_id : '';
const candidateGhostId = ghostCardInstanceId(ghostIdFromInput, inp?.namespace);
const target = anchor ? ghostCardItemByCallId.get(anchor) : undefined;
const targetInput = target?.toolCall.toolInput as Record<string, unknown> | undefined;
const targetGhostId = typeof targetInput?.ghost_id === 'string'
? ghostCardInstanceId(targetInput.ghost_id, targetInput.namespace)
: null;
const physicalOwnerMatches = target && (target.ghostId === ghostIdFromInput ||
((inp?.namespace !== undefined || !isValidGhostId(ghostIdFromInput)) &&
ghostCardInstanceId(target.ghostId, undefined) === candidateGhostId));
const sameGhostTarget = target && candidateGhostId !== null && candidateGhostId === targetGhostId &&
inp?.namespace === targetInput?.namespace && physicalOwnerMatches
? target : undefined;
// 音频入卡令牌(audioInCard)= 意识的**待验证声明**:锚到的同意识卡
// 确实 ready 且 html 真含对应 data-ghost-audio 插槽(播放器已由卡内
// 受信桥渲染)才压掉基座音频卡,防同一首歌双播放器;验证不过(远程
// 控制端无卡、card-update 被静默拒、老历史)保留基座渲染,音频永不
// 消失。URL 在净化器输出里是 escapeAttr 原样(cindy-media 地址无需
// 转义字符),字面量包含判定成立。
if (media.some((m) => m.audioInCard || m.imageInCard)) {
const anchorEntry = anchor ? ghostCards?.byCallId.get(anchor) : undefined;
const cardHtml =
sameGhostTarget && anchorEntry?.status === 'ready' ? anchorEntry.html : '';
media = media.filter(
(m) =>
!(
m.kind === 'audio' &&
m.audioInCard &&
cardHtml.includes(`data-ghost-audio="${m.url}"`)
) &&
// 图片入卡令牌同款验证:锚到的同意识卡 html 真含该图片地址
// (卡内 <img src> 就是 cindy-media 地址原文)才压基座。
!(m.kind === 'image' && m.imageInCard && cardHtml.includes(m.url)),
);
if (media.length === 0) return;
}
if (sameGhostTarget) {
// 同 URL 去重(重复轮询同一 completed 任务会再次带回同一指纹地址)。
const seen = new Set((sameGhostTarget.media ?? []).map((x) => x.url));
const fresh = media.filter((x) => !seen.has(x.url));
if (fresh.length > 0)
sameGhostTarget.media = [...(sameGhostTarget.media ?? []), ...fresh];
return;
}
}
pendingSegmentMedia.push(...media);
};
// 主路径: 按 toolUseId 直接查 orphan/正常 tool_result 内容,不依赖位置
const mainResult =
typeof msg.toolUseId === 'string' && msg.toolUseId.length > 0
? resultByToolUseId.get(msg.toolUseId)
: undefined;
maybeQueueGhostCard(mainResult);
// Regular tool_use — accumulate(配上卡的 ghost_call 不进段,行隐身)。
if (!hideRowForCard) {
// 历史窗口空洞可能正好落在两次工具调用之间(缺的是 user 行):那样两个窗口的
// tool call 会被合进同一个 tool_segment,段首尾时间差直接成了跨空洞的假时长,
// 而 groupWorkRuns 的空洞守卫只看段首时间、发现不了段内部的跳变。所以在段内
// 也按同一阈值切开,让「已工作 Xs」的时长和分组都落在真实连续的动作上。
//
// 锚点是 pendingSegmentEndMs —— 段内所有调用结束时间的**最大值**,不能只看紧邻的
// 上一条:并行工具会乱序完成(A 跑 40 分钟还没回,B 紧随其后一分钟就结束,这时又发起
// C),只比 B 的早结束时间会把 C 误判成空洞、把一段连续工作切碎,段产物(tool_media)
// 也跟着挪到错误的边界上(#676 review codex P1)。groupWorkRuns 的 prevEndMs 早就是
// 单调取 max 的,这里补齐同一口径。
if (pendingToolCalls.length > 0) {
const currentCallMs = messageTs(msg);
if (
pendingSegmentEndMs !== null &&
currentCallMs !== null &&
currentCallMs - pendingSegmentEndMs > HISTORY_GAP_SPLIT_MS
) {
flushSegment();
}
}
pendingToolCalls.push(msg);
notePendingSegmentEnd(messageTs(msg));
if (mainResult !== undefined) {
// result 到了就算 settled,即便内容被隐藏不进 resultMap。
pendingSettledIds.add(msg.clientId);
// 时间戳与内容是否被隐藏无关:段的结束时间靠它算(见 resultTsMap 注释)。
const resultTs =
typeof msg.toolUseId === 'string' ? resultTsByToolUseId.get(msg.toolUseId) : undefined;
if (resultTs !== undefined) {
pendingResultTsMap.set(msg.clientId, resultTs);
notePendingSegmentEnd(resultTs);
}
}
if (mainResult !== undefined && !shouldHideToolResult(toolName, mainResult)) {
pendingResultMap.set(msg.clientId, mainResult);
// 同时把 result 里嵌的媒体 URL (image/video) 累积起来,segment flush
// 时作为独立 'tool_media' item 渲染到 chat 流上(脱离 tool_segment 折叠)。
// 供卡的调用抑制自己的媒体贡献(卡片替换 generic 图卡)。
if (!suppressMediaForCard) {
collectResultMedia(mainResult);
}
}
}
// Adjacency 兜底: 旧数据 toolUseId 缺失时,沿用原有"tool_result 紧跟"配对。
// 即便主路径已命中(或行隐身),这里也跳过相邻 tool_result,免得它们被
// 当 orphan 重渲染。
let j = i + 1;
while (j < messages.length && messages[j].role === 'tool_result') {
if (!hideRowForCard) {
pendingSettledIds.add(msg.clientId);
// adjacency 配对同样要留下 result 时间戳(段结束时间用)。
const adjacencyTs = Date.parse(messages[j].createdAt ?? '');
if (Number.isFinite(adjacencyTs)) {
notePendingSegmentEnd(adjacencyTs);
const known = pendingResultTsMap.get(msg.clientId);
if (known === undefined || adjacencyTs > known) {
pendingResultTsMap.set(msg.clientId, adjacencyTs);
}
}
// 主路径没命中时才用 adjacency 覆盖(后到 last wins,保留原行为)
const result = messages[j].content;
if (!pendingResultMap.has(msg.clientId) && !shouldHideToolResult(toolName, result)) {
pendingResultMap.set(msg.clientId, result);
if (!suppressMediaForCard) {
collectResultMedia(result);
}
}
}
j++;
}
i = j;
} else if (msg.role === 'tool_result') {
// Orphan tool_result — skip
i++;
} else if (msg.role === 'assistant' && !msg.systemCardType && msg.content.trim().length === 0) {
// A leaked model stop token or other empty wrap-up must not become a bubble.
i++;
} else {
// Any non-tool message flushes the pending segment first so tool
// segments appear above their text result, not after it.
flushSegment();
items.push({ type: 'message', key: `msg-${msg.clientId}`, message: msg });
i++;
}
}
// Flush trailing segment — important for streaming, where the turn often
// ends mid-segment (no closing text yet).
flushSegment();
// 末尾 turn 的产出文件卡(没有后续 user 边界触发)。
flushTurnChanges(turnStartIdx, messages.length);
if (taskUpdates) {
// 父会话自己的 Bash 调用集合:local_bash 任务卡(#247 的「后台命令」卡,含
// 停止按钮)的**唯一**渲染来源就是本孤儿循环(Bash toolCall 走 tool_segment,
// 不进 agent_task 配对分支),必须按 parentToolUseId 命中保留;命不中的才是
// workflow / 子 agent 内部启动的后台命令 —— 只进后台任务面板,不进聊天流刷屏
// (对齐官方:聊天流只呈现父会话自己的调用)。
//
// 归属只能靠「父 Bash 调用在不在 messages 里」判定(AgentTaskUpdate 没有
// 结构化的「谁 spawn 的」字段),而 messages 是分页窗口(首屏 50 行)。窗口
// 不完整时父调用可能只是还没翻到,此时**不丢**:宁可临时多显示 workflow 内部
// 的后台命令卡(本 PR 之前就是这个形态),也不能把用户自己还在跑的后台命令
// 及其停止按钮从聊天流里抹掉。翻到旧页 / 加载完历史后过滤自动恢复。
const historyWindowIncomplete = opts?.historyWindowIncomplete === true;
const parentBashToolUseIds = new Set<string>();
for (const m of messages) {
if (
m.role === 'tool_use' &&
m.toolName === 'Bash' &&
typeof m.toolUseId === 'string' &&
m.toolUseId.length > 0
) {
parentBashToolUseIds.add(m.toolUseId);
}
}
const seenTaskIds = new Set<string>();
for (const update of taskUpdates.values()) {
if (
update.taskType === 'local_bash' &&
!historyWindowIncomplete &&
!(update.parentToolUseId && parentBashToolUseIds.has(update.parentToolUseId))
) {
continue;
}
const primaryKey = update.parentToolUseId ?? update.taskId;
if (
seenTaskIds.has(update.taskId) ||
renderedTaskKeys.has(primaryKey) ||
renderedTaskKeys.has(update.taskId)
) {
continue;
}
seenTaskIds.add(update.taskId);
const durableStatus = lookupSubagentRunStatus(opts?.subagentRunStatuses, undefined, update);
const item: AgentTaskRenderItem = {
type: 'agent_task',
key: `task-update-${primaryKey}`,
update,
...(durableStatus ? { durableStatus } : {}),
};
const itemMs = renderItemStartMs(item);
if (itemMs === null) {
items.push(item);
continue;
}
const insertAt = items.findIndex((candidate) => {
const candidateMs = renderItemStartMs(candidate);
return candidateMs !== null && candidateMs > itemMs;
});
if (insertAt < 0) items.push(item);
else items.splice(insertAt, 0, item);
}
}
return { items, singleResultMap };
}
type RenderProjection = ReturnType<typeof buildRenderItems>;
const recentRenderProjections: {
dependencies: readonly unknown[];
projection: RenderProjection;
characters: number;
}[] = [];
let renderProjectionOwner = getDataOwnerGeneration();
/**
* Reuse pure history projection across keyed MessageStream mounts. Retain at
* most three inputs and 32M source characters; no DOM, hooks or subscriptions.
* Dependencies mirror every semantic input to buildRenderItems. In particular
* ghost snapshots (not their mutable byCallId Map) invalidate card decisions.
*/
export function buildCachedRenderItems(
...args: Parameters<typeof buildRenderItems>
): RenderProjection {
const [messages, taskUpdates, ghostCards, opts] = args;
const owner = getDataOwnerGeneration();
if (owner !== renderProjectionOwner) {
recentRenderProjections.length = 0;
renderProjectionOwner = owner;
}
const dependencies = [
messages,
taskUpdates,
ghostCards,
ghostCards?.version,
opts?.sessionId,
opts?.historyWindowIncomplete,
opts?.turnChangeSets,
opts?.workingDir,
opts?.botSessionId,
opts?.activeVoiceCallId,
opts?.subagentRunStatuses,
opts?.historyArtifacts,
opts?.cindyMakeSessionId,
opts?.cindyMakeCompletionInComposer,
];
const index = recentRenderProjections.findIndex((entry) =>
entry.dependencies.every((value, i) => Object.is(value, dependencies[i])),
);
if (index >= 0) {
const [entry] = recentRenderProjections.splice(index, 1);
recentRenderProjections.push(entry);
return entry.projection;
}
const projection = buildRenderItems(...args);
const characters = messages.reduce((sum, message) => sum + message.content.length, 0);
const maxCharacters = 32 * 1024 * 1024;
if (characters <= maxCharacters) {
// Keep only the latest dependencies for a given source array.
const old = recentRenderProjections.findIndex((entry) => entry.dependencies[0] === messages);
if (old >= 0) recentRenderProjections.splice(old, 1);
recentRenderProjections.push({ dependencies, projection, characters });
while (
recentRenderProjections.length > 3 ||
recentRenderProjections.reduce((sum, entry) => sum + entry.characters, 0) > maxCharacters
) {
recentRenderProjections.shift();
}
}
return projection;
}
/** Build the displayed remote history without evaluating the raw transcript fallback. */
export function buildMessageStreamRenderProjection({
historyView,
historySnapshot,
historyLiveMessages,
isSessionStreaming,
handoff,
taskUpdates,
ghostCardSnapshot,
renderOptions,
generatedFilesItemCache,
historyProjection,
buildRaw,
}: {
historyView: HistoryViewController<HistoryChatMessage> | null | undefined;
historySnapshot: HistoryViewSnapshot<HistoryChatMessage> | null;
historyLiveMessages: readonly HistoryChatMessage[];
isSessionStreaming: boolean;
handoff?: ReturnType<HistoryViewHandoff<HistoryChatMessage>['reconcile']> | null;
taskUpdates?: Parameters<typeof buildRenderItems>[1];
ghostCardSnapshot?: Parameters<typeof buildRenderItems>[2];
renderOptions?: Parameters<typeof buildRenderItems>[3];
generatedFilesItemCache: Map<string, GeneratedFilesRenderItemRef>;
/** Mounted-view cache for ready history, separate from the raw fallback. */
historyProjection?: ReturnType<typeof createStreamingMessageProjection>;
buildRaw: () => RenderProjection;
}): RenderProjection {
if (historyView && historySnapshot?.ready) {
const buildHistory = (): RenderProjection => {
// Build only the displayed projection; the raw fallback is lazy below.
const results = new Map<string, string>();
const items = renderHistoryView<HistoryChatMessage, RenderItem>({
view: historyView,
snapshot: historySnapshot,
liveMessages: historyLiveMessages,
streaming: isSessionStreaming,
isLive: (row) => row.isStreaming === true,
pendingHandoff: handoff?.pending,
staleTail: handoff?.tail,
isLocalMessage: (row) => row.isLocalSystemCard === true,
isLocalUser: (row) =>
row.role === 'user' &&
(row.isPendingPersist === true ||
!!row.blockedByGhost ||
!!row.localSendPrecedingClientIds),
build: (rows, _streaming, historyArtifacts) => {
// History chunks are freshly assembled arrays, not reusable source snapshots.
const chunk = buildRenderItems([...rows], taskUpdates, ghostCardSnapshot, {
...renderOptions,
historyWindowIncomplete: true,
historyArtifacts,
});
for (const [key, value] of chunk.singleResultMap) results.set(key, value);
return groupWorkRuns(chunk.items, isSessionStreaming);
},
structure: {
placeholder: (summary) => ({
id: summary.firstMessageId,
clientId: summary.anchorClientId ?? summary.key.slice('work-'.length),
role: 'thinking',
content: '',
createdAt: new Date(summary.startedAtMs).toISOString(),
thinkingDurationMs: Math.max(0, summary.endedAtMs - summary.startedAtMs),
thinkingRedacted: true,
isStreaming: summary.isStreaming,
}),
children: (item) => (item.type === 'work_group' ? item.children : undefined),
sourceIds: (item) =>
item.type === 'message'
? [item.message.clientId]
: item.type === 'tool_segment'
? item.toolCalls.map((tool) => tool.clientId)
: item.type === 'agent_task' && item.toolCall
? [item.toolCall.clientId]
: [],
rebuild: (item, children, deferred) =>
item.type === 'work_group'
? { ...item, children: children as WorkGroupChildItem[], deferred }
: item,
},
});
const keys = new Set<string>();
const unique = items.filter((item) => {
if (keys.has(item.key)) return false;
keys.add(item.key);
return true;
});
return {
items: reuseGeneratedFilesRenderItems(unique, generatedFilesItemCache),
singleResultMap: results,
};
};
if (!historyProjection) return buildHistory();
const tail = historyLiveMessages.at(-1);
return historyProjection(
historyLiveMessages,
[
getDataOwnerGeneration(),
historyView,
historySnapshot,
isSessionStreaming,
taskUpdates,
ghostCardSnapshot,
ghostCardSnapshot?.version,
renderOptions?.sessionId,
renderOptions?.turnChangeSets,
renderOptions?.workingDir,
renderOptions?.botSessionId,
renderOptions?.activeVoiceCallId,
renderOptions?.subagentRunStatuses,
renderOptions?.cindyMakeSessionId,
renderOptions?.cindyMakeCompletionInComposer,
handoff?.pending.size,
...(handoff?.pending ?? []),
handoff?.tail.size,
...(handoff?.tail ?? []),
],
buildHistory,
// Already-grouped history can only replace a standalone unsealed tail.
// Bot ordering and completed-answer grouping remain content dependent.
isSessionStreaming &&
!renderOptions?.botSessionId &&
!!tail &&
!isCompletedAssistantMessage(tail),
true,
);
}
const built = buildRaw();
return {
items: reuseGeneratedFilesRenderItems(built.items, generatedFilesItemCache),
singleResultMap: built.singleResultMap,
};
}
type GeneratedFilesRenderItemRef = Extract<RenderItem, { type: 'generated_files' }>;
/**
* 产物卡内容没变时沿用上一轮 item。buildRenderItems 每次都 new 一个 files
* 数组,不收口的话 memo 住的 GeneratedFilesCard 仍会因 props 引用变化而重渲。
*/
export function reuseGeneratedFilesRenderItems(
items: RenderItem[],
cache: Map<string, GeneratedFilesRenderItemRef>,
): RenderItem[] {
const seen = new Set<string>();
let swapped = false;
const next = items.map((item) => {
if (item.type !== 'generated_files') return item;
seen.add(item.key);
const previous = cache.get(item.key);
if (
previous &&
generatedFilesCheckKey(
previous.files,
previous.turnStartMs,
previous.turnEndMs,
previous.turnSealed,
) === generatedFilesCheckKey(item.files, item.turnStartMs, item.turnEndMs, item.turnSealed)
) {
if (previous !== item) swapped = true;
return previous;
}
cache.set(item.key, item);
return item;
});
for (const key of cache.keys()) {
if (!seen.has(key)) cache.delete(key);
}
return swapped ? next : items;
}
// ---------------------------------------------------------------------------
// Work-group pass(buildRenderItems 之后的第二层后处理)
// ---------------------------------------------------------------------------
/** 工作组容器回退锚点:与删除补偿同一条 clientId 序列。 */
function collectWorkGroupClientIds(children: readonly RenderItem[]): string[] {
return collectDeleteAnchorClientIds(children);
}
export function renderItemContainsClientId(item: RenderItem, clientId: string): boolean {
if (item.type === 'fork_origin') return false;
if (item.type === 'message') return item.message.clientId === clientId;
if (item.type === 'tool_segment')
return item.toolCalls.some((toolCall) => toolCall.clientId === clientId);
if (item.type === 'agent_task') return item.toolCall?.clientId === clientId;
if (item.type === 'agent_plan') return item.sourceClientIds.includes(clientId);
if (item.type === 'work_group') {
// Retained remote identities survive unloaded children; a group key alone
// does not prove that a previously rendered child still exists.
return (
deferredWorkContainsClientId(item, clientId) ||
item.children.some((child) => renderItemContainsClientId(child, clientId))
);
}
return item.key.endsWith(`-${clientId}`);
}
export function insertForkOriginItem(
items: RenderItem[],
forkOrigin: MessageStreamProps['forkOrigin'],
): RenderItem[] {
if (!forkOrigin) return items;
const marker: ForkOriginRenderItem = {
type: 'fork_origin',
key: `fork-origin-${forkOrigin.parentSessionId}-${forkOrigin.forkedAtMessageId}`,
parentSessionId: forkOrigin.parentSessionId,
forkedAtMessageId: forkOrigin.forkedAtMessageId,
};
const forkCreatedMs = Date.parse(forkOrigin.forkedSessionCreatedAt);
if (Number.isNaN(forkCreatedMs)) return items;
let hasLoadedItemBeforeFork = false;
const insertAt = items.findIndex((item) => {
const itemMs = renderItemStartMs(item);
if (itemMs !== null && itemMs < forkCreatedMs) {
hasLoadedItemBeforeFork = true;
return false;
}
return itemMs !== null && itemMs >= forkCreatedMs;
});
if (!hasLoadedItemBeforeFork || insertAt < 0) return items;
return [...items.slice(0, insertAt), marker, ...items.slice(insertAt)];
}
function renderItemKeyForClientId(items: readonly RenderItem[], clientId: string): string | null {
const item = items.find((candidate) => renderItemContainsClientId(candidate, clientId));
return item?.key ?? null;
}
/**
* tool_result 媒体列表(单一来源渲染器):按 kind 分发到 ChatImageView /
* ChatVideoView / ChatAudioCard / ChatSoundEffectCard。两个消费方共用:
* 'tool_media' item(工具段外的产物流)与 'ghost_card' item 的回锚媒体
* (卡正下方)。加新 kind 只需改 extractToolResultMedia + 这里加分支。
*/
function ToolMediaList({ items, sessionId }: { items: ToolMediaItem[]; sessionId?: string }) {
const mediaKeyCounts = new Map<string, number>();
return (
<>
{items.map((m, i) => {
const mediaKeyBase = `${m.kind}-${m.url}`;
const mediaKeyOccurrence = mediaKeyCounts.get(mediaKeyBase) ?? 0;
mediaKeyCounts.set(mediaKeyBase, mediaKeyOccurrence + 1);
const mediaKey =
mediaKeyOccurrence === 0 ? mediaKeyBase : `${mediaKeyBase}-${mediaKeyOccurrence}`;
if (m.kind === 'image') {
return (
<div key={mediaKey} className="flex flex-col gap-1.5">
<ChatImageView
src={m.url}
filename={`tool-image-${i + 1}`}
variant="tool-output"
modelFile={m.modelFile}
sessionId={sessionId}
/>
</div>
);
}
// 视频 / 音频画不进静态分享图,克隆时剔除;同一行的图片照常进图。
if (m.kind === 'video') {
return (
<div
key={mediaKey}
{...{ [SHARE_EXCLUDE_ATTR]: '' }}
className="flex flex-col gap-1.5"
>
<ChatVideoView
src={m.url}
filename={`tool-video-${i + 1}`}
variant="tool-output"
sessionId={sessionId}
/>
</div>
);
}
// kind === 'audio' — 按 track.kind 分发到两种音频卡:
// music → ChatAudioCard (Suno 完整歌曲, 带封面/tags/歌词)
// sound_effect → ChatSoundEffectCard (ElevenLabs 音效, 无封面紧凑布局)
// 两个组件都共享 mediaPlaybackBus + xdt-audio:// 协议 + 右键
// "打开文件夹"菜单, 只是视觉上音效更紧凑没封面。
// Track must be present (extractToolResultMedia synthesises
// an empty one if only xdt_audio_urls came in defensively).
if (m.audioTrack) {
return (
<div key={mediaKey} {...{ [SHARE_EXCLUDE_ATTR]: '' }} className="contents">
{m.audioTrack.kind === 'sound_effect' ? (
<ChatSoundEffectCard track={m.audioTrack} sessionId={sessionId} />
) : (
<ChatAudioCard track={m.audioTrack} sessionId={sessionId} />
)}
</div>
);
}
return null;
})}
</>
);
}
/**
* 工具产物行的分享壳:含图片时与消息行一样挂分享定位属性和复选框,否则 AI 截图、
* 出图等渲染在气泡外的图片永远选不进分享图。shareId 取 render item key,与消息
* clientId 不同形,不会撞号。复选框只在选择模式渲染,进出选择模式不重挂媒体。
*/
function ShareableToolMedia({
shareId,
renderItemKey,
items,
sessionId,
selectionActive,
}: {
shareId: string;
renderItemKey?: string;
items: ToolMediaItem[];
sessionId?: string;
selectionActive: boolean;
}) {
const shareable = Boolean(sessionId) && isShareableToolMedia(items);
return (
<div
{...(renderItemKey ? { 'data-render-item-key': renderItemKey } : {})}
{...(shareable && sessionId
? { [SHARE_SESSION_ATTR]: sessionId, [SHARE_MESSAGE_ATTR]: shareId }
: {})}
className={cn('flex flex-col gap-2', shareable && 'relative')}
>
{shareable && selectionActive ? <ShareMessageCheckbox clientId={shareId} /> : null}
<ToolMediaList items={items} sessionId={sessionId} />
</div>
);
}
function renderWorkGroupChild(
item: Exclude<WorkChildItem, ToolSegmentRenderItem>,
props: {
workingDir: string;
sessionId?: string;
sessionTitle?: string | null;
agentKind?: 'cc' | 'codex' | 'pi';
remoteHostId?: string | null;
sessionSource?: string | null;
onDiagnoseError?: (error: ErrorDiagnosisSource) => void;
isSessionStreaming: boolean;
firstUserMessageClientId: string | null;
lastUserMessageClientId: string | null;
/** 含合成行的最后一条用户侧输入(自愈重连行判断"仍在飞"的兜底判据)。 */
lastUserInputClientId: string | null;
/** 当前 vendor turn 的续跑 owner clientId。 */
continuationTurnClientId: string | null;
/** 旧端缺省 owner 字段时才启用兼容兜底。 */
continuationInFlightProjectionCapability: ContinuationInFlightProjectionCapability;
localFileRefs: readonly KnownLocalFileRef[];
singleResultMap: Map<string, string>;
assistantsWithFollowingUserBoundary: ReadonlySet<string>;
turnFinalAssistantClientIds: ReadonlySet<string>;
subagentModelByToolUseId: ReadonlyMap<string, string>;
userTurnUsageDetailsByAssistantId: ReadonlyMap<string, TurnUsageDetails>;
},
): ReactNode {
if (item.type === 'agent_task') {
return (
<AgentTaskCard
toolCall={item.toolCall}
update={item.update}
result={item.result}
persistedStatus={item.persistedStatus}
durableStatus={item.durableStatus}
sessionAgentKind={props.agentKind}
{...(props.sessionId ? { sessionId: props.sessionId } : {})}
subagentModel={
item.toolCall?.toolUseId
? props.subagentModelByToolUseId.get(item.toolCall.toolUseId)
: undefined
}
/>
);
}
// 工作组里的中间过程文字不挂 assistantAvatar:折叠块里逐条画脸只会变噪音,
// 身份标记只属于对话流里真正的那句回复(见 MessageItem 的 assistantAvatar)。
return (
<div data-message-client-id={item.message.clientId}>
<MessageItem
message={item.message}
toolResult={props.singleResultMap.get(item.message.clientId)}
workingDir={props.workingDir}
sessionId={props.sessionId}
sessionTitle={props.sessionTitle}
agentKind={props.agentKind}
remoteHostId={props.remoteHostId}
sessionSource={props.sessionSource}
onDiagnoseError={props.onDiagnoseError}
sessionRunning={props.isSessionStreaming}
assistantForkBlocked={shouldBlockAssistantFork(
props.isSessionStreaming,
item.message,
props.assistantsWithFollowingUserBoundary,
)}
assistantIsTurnFinal={props.turnFinalAssistantClientIds.has(item.message.clientId)}
userTurnUsageDetails={props.userTurnUsageDetailsByAssistantId.get(item.message.clientId)}
isFirstUserMessage={item.message.clientId === props.firstUserMessageClientId}
isLastUserMessage={item.message.clientId === props.lastUserMessageClientId}
isLastUserInput={item.message.clientId === props.lastUserInputClientId}
isContinuationTurnOwner={item.message.clientId === props.continuationTurnClientId}
continuationInFlightProjectionCapability={props.continuationInFlightProjectionCapability}
localFileRefs={props.localFileRefs}
/>
</div>
);
}
// agent 出图(art / 飞书拉图等)统一走 ChatImageView('tool-output' variant),
// 与用户上传图共用一份组件,样式/交互/错误降级集中维护。
// ---------------------------------------------------------------------------
// Component
// ---------------------------------------------------------------------------
type WorkGroupRenderContext = Parameters<typeof renderWorkGroupChild>[1];
/** Stable completed groups skip child mapping, summary projection and React work. */
export const WorkGroupRenderItemView = memo(function WorkGroupRenderItemView({
item,
context,
compact,
replyColumnSpacer,
}: {
item: Extract<RenderItem, { type: 'work_group' }>;
context: WorkGroupRenderContext;
compact: boolean;
/** 伙伴聊天:隐形头像占位,让工作过程与回复正文同列对齐。 */
replyColumnSpacer?: ReactNode;
}) {
// 完成态外层时间线可包含内层 work_group。递归只负责形状映射,
// 具体折叠 / 直接详情逻辑全部复用 WorkGroupBlock。
const toWorkGroupChild = (child: WorkGroupChildItem): WorkGroupChild => {
if (child.type === 'work_group') {
return {
kind: 'group',
key: child.key,
blockId: `work:${child.key.slice('work-'.length)}`,
durationMs: child.durationMs,
isStreaming: child.isStreaming,
startedAtMs: child.startedAtMs,
deferred: child.deferred,
childItems: child.children.map(toWorkGroupChild),
};
}
if (child.type === 'tool_segment') {
return {
kind: 'tools',
key: child.key,
toolCalls: child.toolCalls,
resultMap: child.resultMap,
settledIds: child.settledIds,
};
}
if (child.type === 'message' && child.message.role === 'thinking') {
return { kind: 'thinking', key: child.key, message: child.message };
}
return {
kind: 'rendered',
key: child.key,
renderNode: () => renderWorkGroupChild(child, context),
};
};
const childItems = item.children.map(toWorkGroupChild);
const block = (
<WorkGroupBlock
// 单层前缀约定 `work:<clientId>` — item.key 形如 `work-<cid>`,
// 去掉 `work-` 后拼 `<role>:<id>`,与 agent: / thinking: 同构。
blockId={`work:${item.key.slice('work-'.length)}`}
durationMs={item.durationMs}
isStreaming={item.isStreaming}
startedAtMs={item.startedAtMs}
childItems={childItems}
compact={compact}
deferred={item.deferred}
fitHeader={Boolean(replyColumnSpacer)}
/>
);
return (
// data-message-client-ids:组折叠时子卡片/聚合块整体 unmount,
// 精确锚点消失 —— 后台任务面板「点行跳聊天」经 ~= 回退查询
// 落到组容器(与 AgentActionsBlock 的容器锚点同一约定)。
// 视口子锚点不读这个聚合列表,只认已渲染的 data-message-client-id。
<div
key={item.key}
data-render-item-key={item.key}
className="scroll-mt-20"
data-message-client-ids={collectWorkGroupClientIds(item.children).join(' ')}
>
{replyColumnSpacer ? withAssistantAvatar(replyColumnSpacer, block) : block}
</div>
);
});
export function MessageStream({
header,
onAskInSideChat,
historyVisibleAfter,
sessionId,
sessionTitle,
agentKind,
remoteHostId,
sessionSource,
onDiagnoseError,
workingDir,
assistantAvatar,
simplifiedBotConversation = false,
botUnreadBoundaryAt = null,
onBotReadThrough,
messages,
activeVoiceCallId = null,
cindyMakeSessionId,
cindyMakeCompletionInComposer,
historyLoaded,
historyCleared = false,
taskUpdates,
subagentRunStatuses,
isSessionStreaming = false,
continuationTurnClientId = null,
continuationInFlightProjectionCapability = 'unknown',
onLoadMore,
isLoadingMore,
hasMoreMessages: fullHasMoreMessages,
historyWindowHasIsland = false,
bottomPadding,
bottomCenterClearanceOffset,
contentWidth,
getContentWidth,
focusMessageClientId,
focusMessageRequestId,
forkOrigin,
onOpenForkOrigin,
isLocalUserSend,
ownsHardwareScrollActions = true,
onInlinePlanVisibilityChange,
}: MessageStreamProps) {
const { i18n, t } = useTranslation();
const historyView = sessionId ? getRemoteHistoryView(sessionId) : undefined;
const fullHistorySnapshot = useSyncExternalStore(
historyView?.subscribe ?? (() => () => undefined),
historyView?.getSnapshot ?? (() => null),
historyView?.getSnapshot ?? (() => null),
);
const historySnapshot = useMemo(() => historyAfter(fullHistorySnapshot, historyVisibleAfter), [fullHistorySnapshot, historyVisibleAfter]);
const hasMoreMessages = historyVisibleAfter !== undefined && historySnapshot
? historySnapshot.hasMore : fullHasMoreMessages;
const displayMessages = useMemo(() => {
if (!historySnapshot) return messages;
const historyIds = new Set(
historyViewLeaves(historySnapshot.items).flatMap((item) =>
item.type === 'messages' ? item.messages.map((row) => row.clientId) : [],
),
);
for (const detail of historySnapshot.details.values()) {
for (const row of detail.messages) historyIds.add(row.clientId);
}
return projectRemoteUsers(messages, historyIds);
}, [historySnapshot, messages]);
const historyHandoff = useMemo(
() => new HistoryViewHandoff<HistoryChatMessage>((row) => row.isStreaming === true),
[historyView],
);
// Observe live rows before the first history page too: a stream can finish
// while that page is in flight. Local tasks retain their existing path.
const historyLiveMessages = useMemo(
() =>
historyView
? displayMessages.map((row) => ({
...row,
id: row.id ?? row.clientId,
createdAt: row.createdAt ?? '',
}))
: [],
[historyView, displayMessages],
);
const handoff = useMemo(
() => (historySnapshot ? historyHandoff.reconcile(historySnapshot, historyLiveMessages) : null),
[historyHandoff, historySnapshot, historyLiveMessages],
);
// 右上角 chip 栈插槽 —— PrevMessageJumpChip 通过 portal 挂到这里,
// 与 DiffPanelToggle 在同一栈中各占一行。Provider 不存在时返回 null,
// 渲染处会兜底跳过(典型场景:其他视图直接用 MessageStream 但不需要栈)。
const chipSlot = useTopRightChipSlot();
// 会话文件来源上下文(local / device-link / SSH):顶层构造一次,经
// ChatSessionFileProvider 下发给整棵消息树;galleryDeviceId 也从这里同源取
// (见 sessionImageSrcs 处注释)。
const sessionFileValue = useChatSessionFileValue(sessionId, workingDir, remoteHostId);
/** 分享选择模式:只驱动整列缩进(低频)。逐条的选中态由每个复选框自己订阅。 */
const shareSelectionActive = useShareSelectionActive(sessionId);
// 滚动容器:原生 div + overflow-y-auto,样式由全局 .is-scrolling 体系接管
// (lib/scrollbarAutoHide.ts 自动加/撤 .is-scrolling 类,globals.css 控制
// thumb 显隐)。data-scroll-container 给 ImageLightbox 等四个 lightbox
// 的全局 querySelector 找锚点用。
const scrollRef = useRef<HTMLDivElement>(null);
const contentRef = useRef<HTMLDivElement>(null);
/** 渲染 item 的内层 flex 容器;按 data-render-item-key 定位,异步卡片可不占 DOM。 */
const itemsRef = useRef<HTMLDivElement>(null);
// ── 切会话恢复浏览位置(默认常开) ──
// 父组件用 key={sessionId} 重挂载本组件,所以这里在 mount 时一次性读取快照即可:
// 该 session 的快照在第一次 render 时确定,后续不再变。
/** 本次 mount 命中的「上次浏览位置」快照(无快照 / 离开时本就在底部 → undefined)。 */
const restoreSnapshotRef = useRef<SessionScrollSnapshot | undefined>(
sessionId ? readSessionScroll(sessionId) : undefined,
);
/** 是否正处于「还原中」:有快照且离开时不在底部。还原中关闭 auto-follow,
* 并在内容异步settle期间持续按锚点重定位,直到用户第一次手动滚动接管。 */
const restoringRef = useRef<boolean>(
restoreSnapshotRef.current ? restoreSnapshotRef.current.isNearBottom === false : false,
);
const restoreLoadRef = useRef<'idle' | 'pending' | 'loaded' | 'failed' | 'settled'>('idle');
const restoreMountedRef = useRef(false);
const [restoreRevision, setRestoreRevision] = useState(0);
const restoreCancelledRef = useRef(false);
const initialHistoryClearedRef = useRef(historyCleared);
if (historyCleared !== initialHistoryClearedRef.current || focusMessageClientId) {
restoreCancelledRef.current = true;
}
useLayoutEffect(() => {
restoreMountedRef.current = true;
return () => {
restoreMountedRef.current = false;
};
}, []);
/** Whether we should keep pinning the viewport to the bottom. */
const isNearBottomRef = useRef(!restoringRef.current);
/** Set while we programmatically change scrollTop, so the scroll handler
* doesn't misread the assignment as user-initiated up-scroll. */
const programmaticScrollRef = useRef(false);
/** 让旧 rAF 不能清掉后发程序化滚动的状态或覆盖其锚点。 */
const programmaticScrollGenerationRef = useRef(0);
/** F-SYNC-2: remembered scrollHeight snapshot taken at the moment we
* trigger `onLoadMore`, used to restore position after prepend. */
const prevScrollHeightRef = useRef(0);
/** F-SYNC-2 anchoring 检测配套:与 `prevScrollHeightRef` 同时刻记录的 scrollTop
* 快照。effect 跑前比对 `el.scrollTop` 与这个快照,大于一定阈值 = 浏览器
* scroll anchoring 已经把 scrollTop 自动加过 delta(无需 React 层再补),
* 避免与浏览器 anchoring 双补偿导致 viewport 被推到底。 */
const prevScrollTopAtLoadRef = useRef(0);
/** Track previous scrollTop to detect scroll direction. */
const prevScrollTopRef = useRef(0);
/** 上一帧 render items。全量序列在窗口回退成尾窗时仍能选到删除区后的邻居。 */
const prevVisibleItemsRef = useRef<readonly RenderItem[]>([]);
const prevAllItemsRef = useRef<readonly RenderItem[]>([]);
/** 最近一次滚动/跳转落定的视口顶端。不读 sessionScrollStore(程序化跳转后会陈旧)。 */
const lastViewportTopRef = useRef<ViewportTopSnapshot | null>(null);
/** 窗口重建后下一提交执行的一次性视口复位。 */
const pendingReanchorScrollRef = useRef<ViewportTopSnapshot | null>(null);
/** 程序化滚动期间到达的删除,待滚动结束后重放补偿。 */
const deferredDeleteCompensationRef = useRef(false);
const [deleteCompensationReplay, setDeleteCompensationReplay] = useState(0);
/** clientId of the last user-role message we've already observed. Used to
* detect a NEW user send → force pin regardless of prior scroll state. */
const lastUserMsgIdRef = useRef<string | null>(
findLastMatchingId(messages, (message) => (message.role === 'user' ? message.clientId : null)),
);
const knownUserMessageIdsRef = useRef<Set<string>>(
collectKnownUserMessageIds(messages, (message) =>
message.role === 'user' ? message.clientId : null,
),
);
const followLatestRequestKey = useSyncExternalStore(
subscribeFollowLatestRequests,
() => readFollowLatestRequestKey(sessionId),
() => 0,
);
const prevFollowLatestRequestKeyRef = useRef(followLatestRequestKey);
// ── render-window state ──
// null = 默认窗口(取末尾 RENDER_WINDOW_INITIAL_ITEMS 个 item);非 null = 锚定到
// 具体的 RenderItem.key,从那个 item 开始 slice 到末尾。expand 时把锚点往前挪
// RENDER_WINDOW_GROWTH_ITEMS 个 item。
//
// 非贴底恢复从 viewportTopKey 附近重建,不重挂之前扩出来的全部离屏条目。
// 边界吸附保留上文,applyRestore 补齐定位所需的下方空间;用户继续滚动时
// 沿既有双向扩窗路径补齐。缺少视口锚点的旧快照仍恢复原窗口。
const [firstVisibleItemKey, setFirstVisibleItemKey] = useState<string | null>(() => {
return resolveRestoredRenderWindow(restoreSnapshotRef.current).anchor;
});
// 默认尾窗首个提交就使用最终容量。若先画 15 条、再在空闲期扩到 80 条,
// 切换任务时会把更早消息插入视口上方并触发一次可见的滚动补偿。
const defaultWindowItems = RENDER_WINDOW_INITIAL_ITEMS;
/**
* 锚点窗口向后的 item 上界(render-window-bidirectional 要点 1)。
* 仅 firstVisibleItemKey !== null 时生效;null(默认窗口)时不参与 slice。
* 锚点变化时重置为 FIRST_PAINT,expandWindow / 向下扩窗时增长。
* 重挂载从视口锚点附近开始;applyRestore 会补齐定位所需的下方空间。
*/
const [anchoredForwardItems, setAnchoredForwardItems] = useState(() => {
return resolveRestoredRenderWindow(restoreSnapshotRef.current).forwardItems;
});
const [highlightMessageClientId, setHighlightMessageClientId] = useState<string | null>(null);
const lastAppliedFocusRef = useRef<string | null>(null);
const lastMissingFocusRef = useRef<{
clientId: string;
requestKey: string;
itemCount: number;
lastItemKey: string | null;
} | null>(null);
const focusScrollTimerRef = useRef<number | null>(null);
const focusHighlightTimerRef = useRef<number | null>(null);
/** 进行中的 focus 跳转。生命周期跨越流式重渲染:接管 / 落定监听在挂载级注册并读
* 本 ref 判定,挂在 reactive effect 里会被内容型重渲染的 cleanup 拆掉且早退分支
* 不再重挂。keysAtJump 供目标在跳转途中被删时选相邻存活落点。 */
const focusJumpRef = useRef<{
requestKey: string;
clientId: string;
targetKey: string;
keysAtJump: readonly string[];
messageClientIdsAtJump: readonly string[];
scrollGeneration: number;
settling?: boolean;
cancelAnimation?: () => void;
} | null>(null);
useEffect(
() => () => {
focusJumpRef.current?.cancelAnimation?.();
focusJumpRef.current = null;
if (focusScrollTimerRef.current !== null) {
window.clearTimeout(focusScrollTimerRef.current);
}
if (focusHighlightTimerRef.current !== null) {
window.clearTimeout(focusHighlightTimerRef.current);
}
},
[],
);
// 意识卡片快照(卡槽③):独立 store,版本号变才触发重建;供片限速 ≥1s/卡,
// 对 build 频率的额外贡献可控。
const ghostCardSnapshot = useSyncExternalStore(subscribeGhostCards, getGhostCardSnapshot);
// 历史回放取卡:会话打开时一次性批量取本会话全部卡(含 tool-call 卡与
// 出口钩子的 turn 级自绘卡,后者 callId = assistant 消息 clientId),让"该气泡
// 被自绘替换"的判定在重启/回放后成立;再对 settled 消息里的 xdt_card_id 逐个
// ensureCard 兜底(幂等,批量已 ready 者直接跳过)。
useEffect(() => {
if (sessionId) ensureSessionCards(sessionId);
}, [sessionId]);
useEffect(() => {
for (const m of messages) {
if (m.role === 'tool_result') {
const cardId = extractGhostCardId(m.content);
if (cardId) ensureCard(cardId);
}
}
}, [messages]);
const turnChangeSets = useTurnChangeSets(sessionId, remoteHostId);
// 「用户实际看得见的那份序列」。turn 边界与 last-user 这类**可见 UI 派生**统一吃它,
// 否则被隐藏的子代理行会被当成 turn 边界或「最后一条 user 消息」,让可见气泡丢掉编辑
// 入口与运行态标记(review: codex P2;同族的 isSyntheticTrigger 坑见
// findLastUserMessageClientId 注释)。按子代理归属反查的派生(buildSubagentModelMap)
// 仍吃原始 messages —— 它要的正是这些被隐藏的行。
const visibleMessages = useMemo(() => selectVisibleMessages(displayMessages), [displayMessages]);
// Text keeps flowing through visibleMessages. Only metadata consumers reuse this snapshot.
const metadataProjection = useMemo(createMessageMetadataProjection, [sessionId]);
const metadataMessages = metadataProjection(displayMessages);
const rawMetadataProjection = useMemo(createMessageMetadataProjection, [sessionId]);
const rawMetadataMessages = rawMetadataProjection(messages);
const visibleMetadataMessages = useMemo(
() => selectVisibleMessages(metadataMessages),
[metadataMessages],
);
const streamProjection = useMemo(createStreamingMessageProjection, [sessionId]);
const historyProjection = useMemo(createStreamingMessageProjection, [sessionId]);
const workGroupProjection = useMemo(createStreamingWorkGroupProjection, [sessionId]);
const renderMetadataProjection = useMemo(createRenderItemMetadataProjection, [sessionId]);
const visibleMetadataProjection = useMemo(createRenderItemMetadataProjection, [sessionId]);
const navigationProjection = useMemo(createMessageNavigationProjection, [sessionId]);
// A plain text-only stream update replaces its row in the previous projection.
// Every structural/metadata change still runs the complete history rules below.
const generatedFilesItemCacheRef = useRef(
new Map<string, Extract<RenderItem, { type: 'generated_files' }>>(),
);
// Completed assistant bodies are immutable for the rest of a turn, while
// the active tail keeps changing on every stream batch. Keep this cache at
// MessageStream scope so history pagination and live deltas can share the
// parsed image targets without retaining state beyond the session mount.
const markdownImageTargetCacheRef = useRef<MarkdownImageTargetCache>(new Map());
const { items: ungroupedRenderItems, singleResultMap } = useMemo(() => buildMessageStreamRenderProjection({
historyView, historySnapshot, historyLiveMessages, isSessionStreaming, handoff,
taskUpdates, ghostCardSnapshot,
historyProjection,
generatedFilesItemCache: generatedFilesItemCacheRef.current,
renderOptions: {
sessionId, turnChangeSets, workingDir,
botSessionId: simplifiedBotConversation ? sessionId : undefined,
activeVoiceCallId,
markdownImageTargetCache: markdownImageTargetCacheRef.current,
cindyMakeSessionId, cindyMakeCompletionInComposer, subagentRunStatuses,
},
buildRaw: () => streamProjection(
displayMessages,
[
getDataOwnerGeneration(),
taskUpdates,
ghostCardSnapshot,
ghostCardSnapshot.version,
historyLoaded,
hasMoreMessages,
historyWindowHasIsland,
turnChangeSets,
workingDir,
simplifiedBotConversation,
activeVoiceCallId,
sessionId,
cindyMakeSessionId,
cindyMakeCompletionInComposer,
subagentRunStatuses,
historyView,
],
() =>
buildCachedRenderItems(displayMessages, taskUpdates, ghostCardSnapshot, {
sessionId,
historyWindowIncomplete:
!historyLoaded || Boolean(hasMoreMessages) || historyWindowHasIsland,
turnChangeSets,
workingDir,
botSessionId: simplifiedBotConversation ? sessionId : undefined,
activeVoiceCallId,
markdownImageTargetCache: markdownImageTargetCacheRef.current,
cindyMakeSessionId,
cindyMakeCompletionInComposer,
subagentRunStatuses,
}),
!simplifiedBotConversation && !historyView,
),
}), [
displayMessages,
activeVoiceCallId,
cindyMakeSessionId,
cindyMakeCompletionInComposer,
historyView,
historySnapshot,
historyLiveMessages,
handoff,
isSessionStreaming,
taskUpdates,
subagentRunStatuses,
ghostCardSnapshot,
historyLoaded,
hasMoreMessages,
historyWindowHasIsland,
turnChangeSets,
workingDir,
simplifiedBotConversation,
sessionId,
streamProjection,
historyProjection,
]);
const assistantsWithFollowingUserBoundary = useMemo(
() => collectAssistantsWithFollowingUserBoundary(visibleMetadataMessages),
[visibleMetadataMessages],
);
// action bar 只挂每个 turn 的收尾 assistant 正文(见 collectTurnFinalAssistantClientIds)。
const turnFinalAssistantClientIds = useMemo(
() => collectTurnFinalAssistantClientIds(visibleMetadataMessages),
[visibleMetadataMessages],
);
// subagent-model-chip: parentToolUseId(Agent/Task 行 id)→ 子代理模型,
// 供 AgentActionsBlock 给 Agent/Task 行反查并渲染模型 chip。
const subagentModelByToolUseId = useMemo(() => {
const models = buildSubagentModelMap(rawMetadataMessages);
for (const summary of historyWorkSummaries(historySnapshot?.items ?? [])) {
if (summary.parentToolUseId && summary.model && !models.has(summary.parentToolUseId)) {
models.set(summary.parentToolUseId, summary.model);
}
}
return models;
}, [rawMetadataMessages, historySnapshot?.items]);
// work-group pass:把最终回答前的工作过程折叠成 work_group,无最终回答时
// 继续走旧的 tool_segment + thinking 折叠兼容路径。
// isSessionStreaming 翻转(每 turn 一次)与 items 变化时重算,O(n) 单扫描。
const { visibleGeneratedFileKeys, onGeneratedFilesVisibilityChange } =
useBotGeneratedFileDeliveries(ungroupedRenderItems, sessionFileValue);
const allRenderItems = useMemo(() => {
const grouped = insertForkOriginItem(
workGroupProjection(
ungroupedRenderItems,
isSessionStreaming,
Boolean(historySnapshot?.ready),
),
forkOrigin,
);
return simplifiedBotConversation
? simplifyBotRenderItems(grouped, isSessionStreaming, visibleGeneratedFileKeys)
: grouped;
}, [
ungroupedRenderItems,
isSessionStreaming,
forkOrigin,
simplifiedBotConversation,
historySnapshot?.ready,
visibleGeneratedFileKeys,
workGroupProjection,
]);
const renderMetadataItems = renderMetadataProjection(allRenderItems);
const botMessageTimeGroups = useMemo(() => {
if (!simplifiedBotConversation) return new Map<string, number>();
return collectBotMessageTimeGroups(
allRenderItems.flatMap((item) => {
if (
item.type !== 'message' ||
(item.message.role !== 'user' && item.message.role !== 'assistant')
) {
return [];
}
return [{ clientId: item.message.clientId, createdAt: item.message.createdAt }];
}),
);
}, [allRenderItems, simplifiedBotConversation]);
const botUnreadBoundaryClientId = useMemo(() => {
if (!simplifiedBotConversation) return null;
return findFirstUnreadBotReplyClientId(
allRenderItems.flatMap((item) =>
item.type === 'message'
? [
{
clientId: item.message.clientId,
createdAt: item.message.createdAt,
role: item.message.role,
systemCardType: item.message.systemCardType,
botPrivateReply: item.message.botPrivateReply,
},
]
: [],
),
botUnreadBoundaryAt,
);
}, [allRenderItems, botUnreadBoundaryAt, simplifiedBotConversation]);
const latestInlinePlan = useMemo(() => {
for (let index = allRenderItems.length - 1; index >= 0; index -= 1) {
const item = allRenderItems[index];
if (item.type === 'agent_plan') return item;
}
return null;
}, [allRenderItems]);
const latestInlinePlanKey = latestInlinePlan?.key ?? null;
const latestInlinePlanBelongsToActiveTurn = useMemo(
() =>
latestInlinePlan
? planSessionBelongsToLatestUserTurn(displayMessages, latestInlinePlan.sourceClientIds)
: false,
[latestInlinePlan, displayMessages],
);
/**
* render-window-bidirectional 已实施:锚定窗口改为双向有界
* `slice(startIdx, startIdx + anchoredForwardItems)`(要点 1)。
* 配合 expandWindow 同步扩上界(要点 4)、handleScroll 向下扩窗(要点 5)、
* windowAtTop 改 visibleStartIdx === 0(要点 2)、isNearBottom 强制非贴底(要点 3)。
* 之前那套 store 侧补齐预算是它落地前的过渡兜底,后续可大幅放宽甚至移除。
*/
/**
* render-window-bidirectional: 锚定窗口从 `slice(startIdx)` 改成
* `slice(startIdx, startIdx + anchoredForwardItems)`,配合向下扩窗(要点 1)。
* 同时导出 startIdx 供 windowAtTop 判定使用(要点 2)。
*/
// ── 切换首帧 ──
// 首个提交直接渲染有界的首屏窗口,保留首屏成本控制;滚动锚点恢复仍由
// layout effect 和 ResizeObserver 处理。
const { items: visibleRenderItems, startIdx: visibleStartIdx } = useMemo(() => {
if (allRenderItems.length === 0) return { items: allRenderItems, startIdx: 0 };
if (firstVisibleItemKey === null) {
// 默认尾窗固定使用 INITIAL 容量;字节预算只在明确的首屏窗口策略中使用。
const countStartIdx = Math.max(0, allRenderItems.length - defaultWindowItems);
const snappedStartIdx = snapRenderWindowStartIdx(allRenderItems, countStartIdx);
return { items: allRenderItems.slice(snappedStartIdx), startIdx: snappedStartIdx };
}
let idx = allRenderItems.findIndex((it) => it.key === firstVisibleItemKey);
if (idx < 0) {
// 锚点 key 失效 — 最常见原因:DB prepend 让 tool_segment 合并,
// toolCalls[0] 变了导致 seg-${cid} key 漂移。recoverLostAnchorIdx 反解
// clientId 找到现在覆盖它的 item,跨段合并的边界仍能续上。
// 真正找不到(消息被删/clear)才退回默认窗口。
idx = recoverLostAnchorIdx(allRenderItems, firstVisibleItemKey);
if (idx < 0) {
// 锚点彻底失效的兜底窗口用全量 INITIAL 而非两段式的 defaultWindowItems:
// 该分支多发生在还原/删改消息的异常路径,宽窗口能最大化保住 viewportTopKey
// 命中率(与"非贴底快照首帧用全量窗口"同理),不吝啬这 50 个 item。
const defaultStartIdx = snapRenderWindowStartIdx(
allRenderItems,
Math.max(0, allRenderItems.length - RENDER_WINDOW_INITIAL_ITEMS),
);
return { items: allRenderItems.slice(defaultStartIdx), startIdx: defaultStartIdx };
}
}
const startIdx = snapRenderWindowStartIdx(allRenderItems, idx);
const windowItemCount = resolveAnchoredWindowItemCount(startIdx, idx, anchoredForwardItems);
return {
items: allRenderItems.slice(startIdx, startIdx + windowItemCount),
startIdx,
};
}, [
allRenderItems,
firstVisibleItemKey,
defaultWindowItems,
anchoredForwardItems,
]);
const visibleMetadataItems = visibleMetadataProjection(visibleRenderItems);
// 镜像 ref:unmount cleanup / ResizeObserver / 落定回调里读最新值(闭包会 stale)。
const visibleRenderItemsRef = useRef(visibleRenderItems);
visibleRenderItemsRef.current = visibleRenderItems;
// Keep complex/stateful cards alive. Plain historical message bodies can be
// replaced by measured-height placeholders without browser display locking.
const viewportEntries = useMemo(() => visibleRenderItems.map(item => ({
key: item.key,
retain: item.type !== 'message' || item.message.isStreaming === true || Boolean(item.message.systemCardType) ||
(item.message.role !== 'user' && item.message.role !== 'assistant') ||
item.message.clientId === focusMessageClientId,
})), [visibleRenderItems, focusMessageClientId]);
const messageViewportRef = useRef<MessageViewportApi>(null);
// Child layout effects run before this ancestor's DOM ref attaches on mount.
// Connecting here schedules the initial measurement before the first paint.
useLayoutEffect(() => { messageViewportRef.current?.connect(); });
const syncMessageViewport = useCallback(() => messageViewportRef.current?.syncViewport(), []);
const reconcileMessageViewport = useCallback(() => messageViewportRef.current?.reconcileViewport(), []);
// 量出当前视口顶端 render-item;若它内部还有已渲染的子消息,再记实际跨过视口顶边
// 的 message clientId。折叠工作组 / 折叠工具块的聚合 data-message-client-ids 只给
// focus 回退用,不参与视口快照,避免把隐藏 child 当成活锚点。
const measureViewportTop = useCallback((): ViewportTopSnapshot | null => {
const container = scrollRef.current;
const items = itemsRef.current;
if (!container || !items) return null;
const cTop = container.getBoundingClientRect().top;
const children = items.children;
for (let i = 0; i < children.length; i++) {
const itemElement = children[i] as HTMLElement;
const rect = itemElement.getBoundingClientRect();
// 第一条「底边还在容器顶边下方」的 item = 正好跨过视口顶边的那条。
if (rect.height > 0 && rect.bottom - cTop > 0) {
const key = children[i].getAttribute('data-render-item-key');
if (!key) return null;
const snapshot: ViewportTopSnapshot = {
viewportTopKey: key,
// Negative offsets retain top padding or a gap above the first visible
// row; clamping to zero pulls that row to the viewport edge on prepend.
offset: cTop - rect.top,
};
const childAnchor = pickIntersectingChildAnchor(
Array.from(
[itemElement, ...itemElement.querySelectorAll<HTMLElement>('[data-message-client-id]')],
(element) => {
const clientId = readViewportChildAnchorClientId(element);
if (!clientId) return null;
const rect = element.getBoundingClientRect();
if (rect.bottom <= rect.top) return null;
return { clientId, top: rect.top, bottom: rect.bottom };
},
).filter((candidate): candidate is ChildAnchorRect => candidate !== null),
cTop,
);
if (childAnchor) {
snapshot.messageClientId = childAnchor.clientId;
snapshot.messageOffset = childAnchor.offset;
} else {
// A root message can start just below the viewport, in the inter-row
// gap. Keep its exact identity and signed gap through regrouping too.
const rootClientId = readViewportChildAnchorClientId(itemElement);
if (rootClientId) {
snapshot.messageClientId = rootClientId;
snapshot.messageOffset = snapshot.offset;
}
}
return snapshot;
}
}
return null;
}, []);
// 量测并写入「删除前快照」,返回结果供同帧复用。用户滚动、非贴底程序化跳转与
// focus 落定经它刷新;贴底态由 auto-follow 接管,无需快照。
const refreshViewportAnchor = useCallback((preserveAligned = false): ViewportTopSnapshot | null => {
const previous = lastViewportTopRef.current;
const container = scrollRef.current;
if (preserveAligned && previous && container) {
const target = previous.messageClientId
? queryMessageElement(container, previous.messageClientId)
: findRenderItemElement(itemsRef.current, previous.viewportTopKey);
const rect = target?.getBoundingClientRect();
const viewport = container.getBoundingClientRect();
const offset = previous.messageClientId ? previous.messageOffset ?? 0 : previous.offset;
// Native anchoring also emits scroll events during prepend/size settling.
// An already aligned reading row must not be replaced by a new offscreen
// row whose content-visibility estimate temporarily crosses the top edge.
if (
rect && rect.height > 0 && rect.bottom > viewport.top && rect.top < viewport.bottom
&& viewportAnchorCorrection(viewport.top, rect.top, offset) === 0
) return previous;
}
const measured = measureViewportTop();
if (measured) lastViewportTopRef.current = measured;
return measured;
}, [measureViewportTop]);
const beginProgrammaticScroll = useCallback((): number => {
programmaticScrollRef.current = true;
programmaticScrollGenerationRef.current += 1;
return programmaticScrollGenerationRef.current;
}, []);
// true = 触发删除补偿重放;false = 正常结束;null = 已被后发滚动取代的旧回调。
const finishProgrammaticScroll = useCallback(
(
generation: number,
{ consumeDeferredDelete = false }: { consumeDeferredDelete?: boolean } = {},
): boolean | null => {
const decision = resolveProgrammaticScrollEndDecision({
generation,
activeGeneration: programmaticScrollGenerationRef.current,
hasDeferredDelete: deferredDeleteCompensationRef.current,
consumeDeferredDelete,
});
if (decision === 'stale') return null;
programmaticScrollGenerationRef.current += 1;
programmaticScrollRef.current = false;
if (decision === 'finished') return false;
deferredDeleteCompensationRef.current = false;
if (decision === 'consume-deferred-delete') return false;
setDeleteCompensationReplay((version) => version + 1);
return true;
},
[],
);
const allRenderItemsRef = useRef(allRenderItems);
allRenderItemsRef.current = allRenderItems;
// 折叠/展开不改 visibleRenderItems。精确 child 被卸掉且数据仍在时降级重测;
// 快照没有子锚点但视口顶 item 已露出精确 child 时也重测(折叠→展开)。
const refreshHiddenChildViewportAnchor = useCallback(() => {
const snapshot = lastViewportTopRef.current;
const clientId = snapshot?.messageClientId;
if (clientId && snapshot) {
const root = scrollRef.current;
const exact = root ? queryMessageElement(root, clientId) : null;
const rect = exact?.getBoundingClientRect();
if (
!shouldRefreshHiddenChildViewportAnchor({
snapshotMessageClientId: clientId,
exactChildVisible: Boolean(rect && rect.bottom > rect.top),
childStillInRenderItems: allRenderItemsRef.current.some((item) =>
renderItemContainsClientId(item, clientId),
),
})
) {
return;
}
lastViewportTopRef.current = toRenderItemViewportSnapshot(snapshot);
refreshViewportAnchor();
return;
}
const itemElement = findRenderItemElement(itemsRef.current, snapshot?.viewportTopKey);
if (
!shouldRefreshExpandedChildViewportAnchor({
snapshotMessageClientId: clientId,
viewportTopItemHasVisibleExactChild: Boolean(
itemElement && hasVisibleExactChildAnchor(itemElement),
),
})
) {
return;
}
refreshViewportAnchor();
}, [refreshViewportAnchor]);
// 瞬时把 key 对应 item 的顶边摆到「容器顶边下方 offset 处」;key 不在当前窗口或
// DOM 未就绪则放弃。删除补偿与 focus 落定共用。
const scrollKeyToViewportTop = useCallback(
(key: string, offset: number) => {
const container = scrollRef.current;
const child = findRenderItemElement(itemsRef.current, key);
if (!container || !child) return false;
const delta = viewportAnchorCorrection(
container.getBoundingClientRect().top,
child.getBoundingClientRect().top,
offset,
);
// 已按真实锚点保位(含零位移)时,不能再叠加同次布局的历史高度补偿。
// 仍在请求中的历史尚未进入 DOM,保留它的快照供返回后补偿。
if (!isLoadingMore) {
prevScrollHeightRef.current = 0;
prevScrollTopAtLoadRef.current = 0;
}
if (delta === 0) return true;
const generation = beginProgrammaticScroll();
container.scrollTop += delta;
requestAnimationFrame(() => finishProgrammaticScroll(generation));
return true;
},
[beginProgrammaticScroll, finishProgrammaticScroll, isLoadingMore],
);
const scrollMessageToViewportTop = useCallback(
(clientId: string, offset: number) => {
const container = scrollRef.current;
// 视口复位只认已渲染的精确 child。聚合 data-message-client-ids 命中折叠组容器
// 会让隐藏 child 继续当活锚点,删除后把组滚到顶。focus 跳转仍走 queryFocusElement。
const target = container ? queryMessageElement(container, clientId) : null;
if (!container || !target) return false;
const rect = target.getBoundingClientRect();
if (rect.height <= 0) return false;
const delta = viewportAnchorCorrection(
container.getBoundingClientRect().top,
rect.top,
offset,
);
if (!isLoadingMore) {
prevScrollHeightRef.current = 0;
prevScrollTopAtLoadRef.current = 0;
}
if (delta === 0) return true;
const generation = beginProgrammaticScroll();
container.scrollTop += delta;
requestAnimationFrame(() => finishProgrammaticScroll(generation));
return true;
},
[beginProgrammaticScroll, finishProgrammaticScroll, isLoadingMore],
);
const restoreViewportSnapshot = useCallback(
(snapshot: ViewportTopSnapshot, itemOffset = snapshot.offset): boolean => {
if (
snapshot.messageClientId &&
scrollMessageToViewportTop(snapshot.messageClientId, snapshot.messageOffset ?? 0)
) {
lastViewportTopRef.current = snapshot;
return true;
}
const itemSnapshot = toRenderItemViewportSnapshot(snapshot, itemOffset);
lastViewportTopRef.current = itemSnapshot;
if (visibleRenderItemsRef.current.some((item) => item.key === itemSnapshot.viewportTopKey)) {
return scrollKeyToViewportTop(itemSnapshot.viewportTopKey, itemSnapshot.offset);
}
return false;
},
[scrollKeyToViewportTop, scrollMessageToViewportTop],
);
const restoreViewportSnapshotOrRebuildWindow = useCallback(
(snapshot: ViewportTopSnapshot, itemOffset = snapshot.offset) => {
if (restoreViewportSnapshot(snapshot, itemOffset)) return;
pendingReanchorScrollRef.current = lastViewportTopRef.current;
const key = lastViewportTopRef.current?.viewportTopKey;
if (key) setFirstVisibleItemKey(key);
},
[restoreViewportSnapshot],
);
const cancelFocusJump = useCallback(
({
consumeDeferredDelete = false,
refreshAnchor = false,
}: {
consumeDeferredDelete?: boolean;
refreshAnchor?: boolean;
} = {}): boolean => {
const jump = focusJumpRef.current;
if (!jump) return false;
jump.cancelAnimation?.();
focusJumpRef.current = null;
if (focusScrollTimerRef.current !== null) {
window.clearTimeout(focusScrollTimerRef.current);
focusScrollTimerRef.current = null;
}
if (focusHighlightTimerRef.current !== null) {
window.clearTimeout(focusHighlightTimerRef.current);
focusHighlightTimerRef.current = null;
}
// 只终止仍由这次 focus 拥有的滚动;过期 focus 不得打断后发滚动。
if (jump.scrollGeneration === programmaticScrollGenerationRef.current) {
const root = scrollRef.current;
if (root) root.scrollTo({ top: root.scrollTop, behavior: 'auto' });
}
const replayingDelete = finishProgrammaticScroll(jump.scrollGeneration, {
consumeDeferredDelete,
});
if (refreshAnchor && replayingDelete === false) refreshViewportAnchor();
return true;
},
[finishProgrammaticScroll, refreshViewportAnchor],
);
// focus 跳转落定收尾(逐帧动画结束与兜底 timer 共用,幂等):动画已跟踪途中高度变化,
// 此处只处理最终布局与所有权交接;目标在跳转途中被删时
// 锚到跳转时序列中它之后第一条存活 item(与删除补偿同语义,落点在窗口外则走窗口
// 重建 + pending 复位);用户已接管则不校正。下一帧再清 programmatic 标记并刷新
// 删除前快照——半途量测会把跳变中的位置误存为锚点。
const settleFocusJump = useCallback(() => {
const jump = focusJumpRef.current;
if (!jump || jump.settling) return;
jump.cancelAnimation?.();
jump.cancelAnimation = undefined;
jump.settling = true;
if (focusScrollTimerRef.current !== null) {
window.clearTimeout(focusScrollTimerRef.current);
focusScrollTimerRef.current = null;
}
if (focusHighlightTimerRef.current !== null) {
window.clearTimeout(focusHighlightTimerRef.current);
focusHighlightTimerRef.current = null;
}
if (jump.scrollGeneration !== programmaticScrollGenerationRef.current) {
focusJumpRef.current = null;
return;
}
// settle 前已观察到的删除由当前目标校正消费;同帧后续删除仍走通用重放。
deferredDeleteCompensationRef.current = false;
// 邻居锚定分支会显式写入快照(窗口重建的 DOM 下一提交才就绪),此时不得再用
// 旧 DOM 量测覆盖。
let snapshotPinned = false;
const root = scrollRef.current;
if (root) {
setHighlightMessageClientId(jump.clientId);
const all = allRenderItemsRef.current;
const target = queryFocusElement(root, jump.clientId);
if (target) {
target.scrollIntoView({ block: 'center' });
syncMessageViewport();
const measured = refreshViewportAnchor();
const rootTop = root.getBoundingClientRect().top;
const targetRect = target.getBoundingClientRect();
if (
jump.messageClientIdsAtJump.includes(jump.clientId) &&
shouldUseFocusedElementAsViewportAnchor({
focusClientId: jump.clientId,
elementClientId: target.dataset.messageClientId,
containerTop: rootTop,
elementTop: targetRect.top,
elementBottom: targetRect.bottom,
})
) {
lastViewportTopRef.current = {
...(measured ?? {
viewportTopKey: renderItemKeyForClientId(all, jump.clientId) ?? jump.targetKey,
offset: 0,
}),
messageClientId: jump.clientId,
messageOffset: Math.max(0, rootTop - targetRect.top),
};
}
} else {
const targetExists = all.some((item) => renderItemContainsClientId(item, jump.clientId));
const landMessageClientId =
!targetExists && jump.messageClientIdsAtJump.includes(jump.clientId)
? pickDeleteCompensationAnchorKey(
jump.messageClientIdsAtJump,
collectDeleteAnchorClientIds(all),
jump.clientId,
)
: null;
let landKey = landMessageClientId
? renderItemKeyForClientId(all, landMessageClientId)
: null;
if (!landKey) {
const recoveredIdx = findRestorableViewportItemIdx(all, jump.targetKey);
landKey =
recoveredIdx >= 0
? (all[recoveredIdx]?.key ?? null)
: pickDeleteCompensationAnchorKey(
jump.keysAtJump,
all.map((item) => item.key),
jump.targetKey,
);
}
if (landKey) {
snapshotPinned = true;
restoreViewportSnapshotOrRebuildWindow({
viewportTopKey: landKey,
offset: 0,
...(landMessageClientId
? { messageClientId: landMessageClientId, messageOffset: 0 }
: {}),
});
}
}
}
let stableFrames = 0;
let frames = 0;
const finishAfterLayout = () => {
if (focusJumpRef.current !== jump) return;
if (!snapshotPinned && jump.scrollGeneration === programmaticScrollGenerationRef.current && root) {
const target = queryFocusElement(root, jump.clientId);
if (target) {
const before = root.scrollTop;
target.scrollIntoView({ block: 'center' });
syncMessageViewport();
stableFrames = Math.abs(root.scrollTop - before) <= 1 ? stableFrames + 1 : 0;
// A native height/scroll update can arrive after the first scrollend.
// Keep ownership while checking consecutive paints, and respect user
// cancellation/replacement on every frame. Bound live-stream settling.
if (++frames < 8 && stableFrames < 3) {
requestAnimationFrame(finishAfterLayout);
return;
}
}
}
focusJumpRef.current = null;
const replayingDelete = finishProgrammaticScroll(jump.scrollGeneration);
if (!snapshotPinned && replayingDelete === false) refreshViewportAnchor();
};
requestAnimationFrame(finishAfterLayout);
}, [finishProgrammaticScroll, refreshViewportAnchor, restoreViewportSnapshotOrRebuildWindow, syncMessageViewport]);
// 接管 / 落定监听挂载级注册一次,读 focusJumpRef 判定,无活跃跳转时空转。挂在下面
// 的 reactive effect 里会被流式重渲染的 cleanup 拆掉且早退分支不再重挂,导致接管
// 失灵、兜底 timer 落定时把用户拽回目标。
useEffect(() => {
const root = scrollRef.current;
if (!root) return;
// 用户中途接管(滚轮 / 触摸 / 按住滚动条 / 键盘导航):浏览器已取消 smooth 动画,
// 立即恢复用户滚动语义,落定时不再校正回目标。
const onUserInput = () => {
// finish 路径会重放 focus 期间延期的删除补偿;不能直接清掉,否则用户接管后
// 会永久保留删除造成的错误位移。
cancelFocusJump();
};
const onNavigationKey = (event: KeyboardEvent) => {
if (event.defaultPrevented) return;
if (!isScrollNavigationKey(event.key)) return;
if (isEditableKeyboardTarget(event.target)) return;
onUserInput();
};
let disposed = false;
const onScrollEnd = () => {
const jump = focusJumpRef.current;
if (!jump || jump.cancelAnimation) return;
// Per-frame writes also emit scrollend. The live-target animation owns
// completion until it releases its handle; then drain pending layout.
requestAnimationFrame(() => requestAnimationFrame(() => {
if (!disposed && focusJumpRef.current === jump) settleFocusJump();
}));
};
root.addEventListener('wheel', onUserInput, { passive: true });
root.addEventListener('touchstart', onUserInput, { passive: true });
root.addEventListener('mousedown', onUserInput);
window.addEventListener('keydown', onNavigationKey);
root.addEventListener('scrollend', onScrollEnd);
return () => {
disposed = true;
root.removeEventListener('wheel', onUserInput);
root.removeEventListener('touchstart', onUserInput);
root.removeEventListener('mousedown', onUserInput);
window.removeEventListener('keydown', onNavigationKey);
root.removeEventListener('scrollend', onScrollEnd);
};
}, [cancelFocusJump, settleFocusJump]);
useLayoutEffect(() => {
const focusRequestKey = focusMessageClientId
? `${focusMessageRequestId ?? 0}:${focusMessageClientId}`
: null;
if (!focusMessageClientId || !focusRequestKey) {
lastAppliedFocusRef.current = null;
lastMissingFocusRef.current = null;
cancelFocusJump({ refreshAnchor: true });
return;
}
// 新请求必须在任何 missing / 扩窗 / DOM 未就绪早退前废弃旧跳转,否则旧 timer
// 或 scrollend 会继续按上一目标落定。requestId 也纳入 key,支持同消息重复跳转。
if (focusJumpRef.current && focusJumpRef.current.requestKey !== focusRequestKey) {
cancelFocusJump({ refreshAnchor: true });
}
if (lastAppliedFocusRef.current === focusRequestKey) return;
const lastItemKey = allRenderItems.at(-1)?.key ?? null;
const missingFocus = lastMissingFocusRef.current;
if (
missingFocus?.clientId === focusMessageClientId &&
missingFocus.requestKey === focusRequestKey &&
missingFocus.itemCount === allRenderItems.length &&
missingFocus.lastItemKey === lastItemKey
) {
return;
}
const targetKey = renderItemKeyForClientId(allRenderItems, focusMessageClientId);
if (!targetKey) {
lastMissingFocusRef.current = {
clientId: focusMessageClientId,
requestKey: focusRequestKey,
itemCount: allRenderItems.length,
lastItemKey,
};
return;
}
lastMissingFocusRef.current = null;
// A search owns the reading position even while rebuilding its window.
// Otherwise a newly clamped history window can be mistaken for tail follow.
restoringRef.current = false;
isNearBottomRef.current = false;
setIsNearBottom(false);
if (!visibleRenderItems.some((item) => item.key === targetKey)) {
setFirstVisibleItemKey(targetKey);
setAnchoredForwardItems(RENDER_WINDOW_FIRST_PAINT_ITEMS);
return;
}
const root = scrollRef.current;
if (!root) return;
const el = queryFocusElement(root, focusMessageClientId);
if (!el) return;
const scrollGeneration = beginProgrammaticScroll();
// 新请求已取消旧动画;保留目标身份与删除前快照,直到逐帧动画完成。
focusJumpRef.current = {
requestKey: focusRequestKey,
clientId: focusMessageClientId,
targetKey,
keysAtJump: allRenderItems.map((item) => item.key),
messageClientIdsAtJump: collectDeleteAnchorClientIds(allRenderItems),
scrollGeneration,
};
const jump = focusJumpRef.current;
jump.cancelAnimation = animateFocusScroll({
root,
getTarget: () => queryFocusElement(root, jump.clientId),
reconcile: syncMessageViewport,
onFinish: () => {
if (focusJumpRef.current !== jump) return;
jump.cancelAnimation = undefined;
settleFocusJump();
},
});
lastAppliedFocusRef.current = focusRequestKey;
if (focusScrollTimerRef.current !== null) {
window.clearTimeout(focusScrollTimerRef.current);
}
if (focusHighlightTimerRef.current !== null) {
window.clearTimeout(focusHighlightTimerRef.current);
}
// 动画主动完成;timer 仅作为安全网,不依赖原生 scrollend 的到达时机。
focusScrollTimerRef.current = window.setTimeout(
settleFocusJump,
2500,
);
// 高亮等落定后再点亮(落定回调里做),点亮后不再自动淡出——停在搜索命中处,直到
// 下次跳转覆盖或切会话。scrollend 未触发(距离为 0 / 环境不支持)时 ~600ms 兜底。
focusHighlightTimerRef.current = window.setTimeout(() => {
setHighlightMessageClientId(focusMessageClientId);
focusHighlightTimerRef.current = null;
}, 600);
}, [
allRenderItems,
focusMessageClientId,
focusMessageRequestId,
visibleRenderItems,
beginProgrammaticScroll,
cancelFocusJump,
settleFocusJump,
syncMessageViewport,
]);
// 会话内全部图片的有序 src(全量,来自未裁剪的 allRenderItems),下发给
// ImageLightbox 做翻图。基于全量而非 visibleRenderItems,这样计数 / 翻页
// 立刻覆盖整个会话,不用先往上滚动加载老图。
// galleryMediaOrigin 与 ChatSessionFileContext 同源(sessionFileValue,订阅式):
// 画廊 src 的远程改写必须和 <img data-gallery-src> 的改写用同一个来源
// (useRemoteMediaUrl 同款 toRemoteMediaOrigin),否则 ImageLightbox 的
// includes 匹配失效;订阅式取值同时修掉了旧实现(render 时一次性
// getSessionDeviceId)在 deviceId 迟到注册时画廊停在未改写 src 的隐患。
const galleryMediaOrigin = useMemo(
() => toRemoteMediaOrigin(sessionFileValue.origin, sessionFileValue.workingDir),
[sessionFileValue],
);
const sessionImageSrcs = useMemo(
() =>
collectSessionImageSrcs(
renderMetadataItems,
galleryMediaOrigin,
ghostCardSnapshot,
isSessionStreaming,
),
[renderMetadataItems, galleryMediaOrigin, ghostCardSnapshot, isSessionStreaming],
);
// 把可见窗口往前(更早)推 RENDER_WINDOW_GROWTH_ITEMS 个 item,用于滚到顶时的客户端扩窗。
// render-window-bidirectional 要点 4: expandWindow 必须同步把上界 +GROWTH,
// 否则 start 前移而上界不动,会把用户视口下方的内容反向截掉。
const expandWindow = useCallback(() => {
if (allRenderItems.length === 0) return;
let currentStartIdx: number;
const wasDefaultWindow = firstVisibleItemKey === null;
if (wasDefaultWindow) {
currentStartIdx = resolveDefaultWindowStartIdx({
allItemCount: allRenderItems.length,
defaultWindowItems,
visibleStartIdx,
visibleItemCount: visibleRenderItems.length,
});
} else {
currentStartIdx = allRenderItems.findIndex((it) => it.key === firstVisibleItemKey);
if (currentStartIdx < 0) {
// 锚点失效场景同 visibleRenderItems useMemo 的注释 —— 先 recover 再继续。
// recover 失败把窗口当作"默认"位置;与 visibleRenderItems 的兜底同口径用全量
// INITIAL(而非两段式 defaultWindowItems),expand 仍能从这往前扩。
currentStartIdx = recoverLostAnchorIdx(allRenderItems, firstVisibleItemKey);
if (currentStartIdx < 0) {
currentStartIdx = Math.max(0, allRenderItems.length - RENDER_WINDOW_INITIAL_ITEMS);
}
}
}
if (currentStartIdx <= 0) return;
const newIdx = Math.max(0, currentStartIdx - RENDER_WINDOW_GROWTH_ITEMS);
const newAnchorIdx = snapRenderWindowStartIdx(allRenderItems, newIdx);
const newAnchor = allRenderItems[newAnchorIdx]?.key ?? null;
if (newAnchor) {
setFirstVisibleItemKey(newAnchor);
if (wasDefaultWindow) {
// 默认窗口 → 锚定窗口:从新锚点到末尾全部可见(数量 = defaultWindowItems + GROWTH,有界)。
setAnchoredForwardItems(allRenderItems.length - newAnchorIdx);
} else {
// P1 fix: 按实际起点位移增长,而非固定 GROWTH。
// snapRenderWindowStartIdx 可能因边界吸附向前多移最多 RENDER_WINDOW_BOUNDARY_LOOKBACK_ITEMS,
// 若上界只 +GROWTH 会把尾部截掉差值条 item。
setAnchoredForwardItems((prev) => prev + (currentStartIdx - newAnchorIdx));
}
}
}, [
allRenderItems,
firstVisibleItemKey,
defaultWindowItems,
visibleStartIdx,
visibleRenderItems.length,
]);
// render-window-bidirectional 要点 2: windowAtTop 改基于 visibleStartIdx === 0。
// 原定义 visible.length === all.length 在双向窗口下即使 start 已到 0 也恒为 false。
const windowAtTop = visibleStartIdx === 0;
// render-window-bidirectional 要点 3/5: 窗口是否已覆盖到内存末尾。
// 默认窗口(firstVisibleItemKey === null)始终覆盖末尾。
const windowCoversEnd =
firstVisibleItemKey === null ||
allRenderItems.length === 0 ||
visibleStartIdx + visibleRenderItems.length >= allRenderItems.length;
// ── 滚动位置 保存 / 还原 的辅助 ──
// 镜像 ref:unmount cleanup 与 ResizeObserver 回调里读最新值(闭包会 stale)。
const windowCoversEndRef = useRef(windowCoversEnd);
windowCoversEndRef.current = windowCoversEnd;
const firstVisibleItemKeyRef = useRef(firstVisibleItemKey);
firstVisibleItemKeyRef.current = firstVisibleItemKey;
const anchoredForwardItemsRef = useRef(anchoredForwardItems);
anchoredForwardItemsRef.current = anchoredForwardItems;
// 新 item 导致锚定窗口不再覆盖末尾时,先保留此前的跟随意图:自动补历史建立的
// 锚点只是实现细节,用户仍在跟随就清锚回默认尾窗;用户已经离底才保留历史窗口。
const prevWindowCoversEndRef = useRef(windowCoversEnd);
useLayoutEffect(() => {
const wasCovering = prevWindowCoversEndRef.current;
prevWindowCoversEndRef.current = windowCoversEnd;
const coverageLossAction = resolveWindowCoverageLossAction({
hasWindowAnchor: firstVisibleItemKey !== null,
wasCoveringEnd: wasCovering,
windowCoversEnd,
wasFollowingTail: isNearBottomRef.current,
});
if (coverageLossAction === 'handoff-to-tail') {
isNearBottomRef.current = true;
setIsNearBottom(true);
setUnreadKeys(NO_UNREAD_KEYS);
setFirstVisibleItemKey(null);
return;
}
if (coverageLossAction === 'preserve-anchor') {
isNearBottomRef.current = false;
setIsNearBottom(false);
return;
}
// 锚定窗向下扩到真正盖住尾部,且用户已经贴在当前窗口底 → 切回默认尾窗并
// 恢复跟随。扩窗发生在本次 scroll 之后,同一帧的 handleScroll 还看不到
// windowCoversEnd=true,没有下一次滚动时会永远停在「已到底、但不跟」。
if (
!restoringRef.current && !programmaticScrollRef.current &&
!wasCovering && windowCoversEnd && firstVisibleItemKey !== null
) {
const el = scrollRef.current;
if (!el) return;
const distanceFromBottom = el.scrollHeight - el.scrollTop - el.clientHeight;
if (distanceFromBottom <= REPIN_AT_BOTTOM_PX) {
isNearBottomRef.current = true;
setIsNearBottom(true);
setUnreadKeys(NO_UNREAD_KEYS);
setFirstVisibleItemKey(null);
}
}
}, [firstVisibleItemKey, windowCoversEnd]);
// Seed Chromium's offscreen estimates before positioning the saved anchor.
// Remounting otherwise forgets the measured sizes and starts every row at
// 240px, which can clamp scrollTop for one paint even with cached cards.
useLayoutEffect(() => {
// The snapshot survives for this mount; streaming updates must stop seeding
// its old estimates once user intent has ended scroll restoration.
if (!restoringRef.current) return;
const items = itemsRef.current;
const sizes = restoreSnapshotRef.current?.itemHeights;
if (!items || !sizes) return;
const width = items.getBoundingClientRect().width;
for (const child of Array.from(items.children)) {
const element = child as HTMLElement;
const key = element.getAttribute('data-render-item-key');
element.style.containIntrinsicBlockSize = key
? (rememberedItemIntrinsicSize(sizes.byKey[key], sizes.width, width) ?? '')
: '';
}
}, [visibleRenderItems]);
// 把视口滚回快照记录的「锚点 item + 偏移」。按条目相对定位,所以即使上方图片 /
// markdown 还没异步渲染完导致高度偏小,也会落在正确的 item 上;settle 期间由
// ResizeObserver 反复调用本函数纠偏(幂等,不漂移)。stable 引用(无依赖)。
const applyRestore = useCallback(() => {
const snap = restoreSnapshotRef.current;
const container = scrollRef.current;
const items = itemsRef.current;
if (!snap || !container || !items) return false;
const idx = findRestorableViewportItemIdx(visibleRenderItemsRef.current, snap.viewportTopKey);
if (idx < 0) return false; // 锚点 item 不在当前窗口(消息被删 / clear)→ 放弃还原,停在默认位置
const child = findRenderItemElement(items, visibleRenderItemsRef.current[idx]?.key);
if (!child) return false;
const messageTarget = snap.messageClientId
? queryMessageElement(container, snap.messageClientId)
: null;
const useMessageTarget = messageTarget && messageTarget.getBoundingClientRect().height > 0;
const target = useMessageTarget ? messageTarget : child;
const offset = useMessageTarget ? (snap.messageOffset ?? 0) : snap.offset;
const desiredScrollTop =
container.scrollTop +
viewportAnchorCorrection(
container.getBoundingClientRect().top,
target.getBoundingClientRect().top,
offset,
);
// A bounded restored window may have some overflow, yet still lack enough
// content below the anchor to place it at its saved offset. Grow forward
// before scrolling so the browser cannot clamp the restored position.
if (
viewportRestoreNeedsMoreContent(
desiredScrollTop,
container.scrollHeight,
container.clientHeight,
windowCoversEndRef.current,
)
) {
restoreLoadRef.current = 'loaded';
// Sparse/null-rendering cards must not require one synchronous commit per
// fixed batch all the way through a long history. Grow geometrically.
const nextCount = Math.max(
anchoredForwardItemsRef.current + RENDER_WINDOW_GROWTH_ITEMS,
anchoredForwardItemsRef.current * 2,
);
setAnchoredForwardItems((count) => Math.max(count, nextCount));
return false;
}
// A work group can remount collapsed or settle internally after its outer
// row was positioned. Prefer the same visible child when it still exists.
if (
snap.messageClientId &&
scrollMessageToViewportTop(snap.messageClientId, snap.messageOffset ?? 0)
) {
restoreLoadRef.current = 'settled';
refreshViewportAnchor();
return true;
}
const cTop = container.getBoundingClientRect().top;
const rect = child.getBoundingClientRect();
// 期望 child 顶端落在 (容器顶边 - offset) 处;向下滚 delta 会让 rect.top 上移 delta。
const delta = rect.top - (cTop - snap.offset);
if (Math.abs(delta) < 1) {
restoreLoadRef.current = 'settled';
refreshViewportAnchor();
return true;
}
const generation = beginProgrammaticScroll();
container.scrollTop += delta;
restoreLoadRef.current = 'settled';
requestAnimationFrame(() => {
if (finishProgrammaticScroll(generation) === false) refreshViewportAnchor();
});
return true;
}, [
beginProgrammaticScroll,
finishProgrammaticScroll,
refreshViewportAnchor,
scrollMessageToViewportTop,
]);
// ResizeObserver 回调用 ref 取最新 applyRestore,避免把它放进 observer 依赖导致
// 流式每 token(visibleRenderItems 变)都 disconnect/reconnect。
const applyRestoreRef = useRef(applyRestore);
applyRestoreRef.current = applyRestore;
// An explicit saved reading position is independent of automatic tail fill.
// Run after intrinsic-size seeding, before paint, so a bounded remount does
// not first display the clamped position and then expand on a later frame.
// Reuse the store's bounded, epoch-guarded local/remote history lookup.
useLayoutEffect(() => {
if (!restoringRef.current || !historyLoaded) return;
if (restoreCancelledRef.current) {
restoringRef.current = false;
return;
}
const snap = restoreSnapshotRef.current;
if (!snap || !sessionId) return;
const clientId =
snap.restoreClientId ?? snap.messageClientId ?? restoreClientIdFromKey(snap.viewportTopKey);
const restoredKey = resolveSavedViewportKey(allRenderItems, snap);
if (restoredKey) {
restoreSnapshotRef.current = { ...snap, viewportTopKey: restoredKey };
if (!visibleRenderItems.some((item) => item.key === restoredKey)) {
restoreLoadRef.current = 'loaded';
setFirstVisibleItemKey(restoredKey);
setAnchoredForwardItems(RENDER_WINDOW_FIRST_PAINT_ITEMS);
} else {
restoreLoadRef.current = applyRestoreRef.current() ? 'settled' : 'loaded';
}
return;
}
if (restoreLoadRef.current === 'pending') return;
if (restoreLoadRef.current === 'idle' && clientId) {
restoreLoadRef.current = 'pending';
const finish = (found: boolean) => {
if (!restoreMountedRef.current || !restoringRef.current || restoreCancelledRef.current)
return;
restoreLoadRef.current = found ? 'loaded' : 'failed';
setRestoreRevision((value) => value + 1);
};
void makerChatStore.loadAroundMessageClientId(sessionId, clientId, { radius: 60 }).then(
(row) => finish(row !== null),
() => finish(false),
);
return;
}
// A deleted/non-displayable anchor must not leave the view stuck restoring.
restoreLoadRef.current = 'settled';
restoringRef.current = false;
isNearBottomRef.current = true;
setIsNearBottom(true);
setFirstVisibleItemKey(null);
}, [
allRenderItems,
visibleRenderItems,
historyLoaded,
historyCleared,
sessionId,
restoreRevision,
]);
// 保存当前浏览位置到 sessionScrollStore,并同步刷新删除前快照(单次量测)。用户
// 滚动时持续调用(DOM 一定存活),unmount cleanup 兜底最后一帧;量测失败则跳过。
const saveRafRef = useRef<number | null>(null);
const saveScrollSnapshot = useCallback(
(includeHeights = false) => {
// Do not overwrite the reading position with the temporary tail while loading it.
if (restoringRef.current && restoreLoadRef.current !== 'settled') return;
const measured = refreshViewportAnchor(true);
if (!sessionId || !measured) return;
const items = itemsRef.current;
let itemHeights: SessionScrollSnapshot['itemHeights'];
const visible = visibleRenderItemsRef.current;
// Only capture sizes on leave, bounded to the last mounted window. Match
// keys because async cards can disappear without occupying a DOM row.
if (includeHeights && !isNearBottomRef.current && items) {
const byKey: Record<string, number> = {};
for (
let index = Math.max(0, visible.length - RENDER_WINDOW_INITIAL_ITEMS);
index < visible.length;
index++
) {
const element = findRenderItemElement(items, visible[index].key);
if (!element) continue;
const style = getComputedStyle(element);
// contain-intrinsic-size describes the content box, excluding padding/borders.
byKey[visible[index].key] =
element.getBoundingClientRect().height -
(parseFloat(style.paddingTop) || 0) -
(parseFloat(style.paddingBottom) || 0) -
(parseFloat(style.borderTopWidth) || 0) -
(parseFloat(style.borderBottomWidth) || 0);
}
itemHeights = { width: items.getBoundingClientRect().width, byKey };
}
saveSessionScroll(sessionId, {
windowAnchorKey: firstVisibleItemKeyRef.current,
viewportTopKey: measured.viewportTopKey,
offset: measured.offset,
messageClientId: measured.messageClientId,
restoreClientId:
measured.messageClientId ??
(() => {
const item = visible.find((item) => item.key === measured.viewportTopKey);
return item ? restoreClientIdForItem(item) : undefined;
})(),
messageOffset: measured.messageOffset,
itemHeights,
isNearBottom: isNearBottomRef.current,
anchoredForwardCount:
firstVisibleItemKeyRef.current !== null ? anchoredForwardItemsRef.current : undefined,
});
},
[sessionId, refreshViewportAnchor],
);
// perf-baseline (见 perfLog 注释):
// 父组件用 key={sessionId} 包了本组件,所以每次切 session 都是全新 mount,
// mountTimeRef 在 component body 初始化即可作为切换时间锚点。
// 度量单位:initialItems/renderedItems = render-item 数(不是消息条数 —— 跟
// 渲染窗口同轴),totalMsgs 仍保留方便定位真实消息规模。
const perfMountTimeRef = useRef<number>(performance.now());
const perfFirstPaintLoggedRef = useRef<boolean>(false);
// biome-ignore lint/correctness/useExhaustiveDependencies: mount-only perf baseline;父组件按 sessionId key 重挂载,依赖变化不应重复打 mount 日志。
useEffect(() => {
if (!import.meta.env.DEV) return;
perfLog.debug(
`stream:mount sid=${sessionId ?? 'null'} initialMsgs=${messages.length} initialItems=${allRenderItems.length} renderedItems=${visibleRenderItems.length}`,
);
// 仅 mount 时跑一次,sessionId 不会在 lifecycle 内变化(parent 用 key 重挂载)
}, []);
// 切 session 兜底:父组件用 key={sessionId} 包本组件,session 切换
// 走整树 unmount → 这里的 cleanup 显式 pause 所有仍在播放的媒体。
// React unmount 移除 DOM 通常会自动停掉 <audio>/<video>,但 chromium
// 偶发存在短暂延迟,显式停一次保证即时静音。
useEffect(() => {
return () => {
stopAllMedia();
};
}, []);
// 切会话兜底:在本组件 unmount(切走该 session)时做最后一次保存,补捉 handleScroll
// 的 rAF 节流来不及落的最后一帧。必须用 useLayoutEffect —— 它的 cleanup 在 commit
// 的 mutation 阶段同步执行,此时本组件子树的 DOM / ref 仍存活,可正常量测;若用
// useEffect,其 cleanup 跑在 passive 阶段(DOM 已移除、ref 已置空),measureViewportTop
// 必拿到 null,快照永远存不进去(这正是「切回会话仍每次滚到底」的根因)。
useLayoutEffect(() => {
return () => {
if (saveRafRef.current !== null) {
cancelAnimationFrame(saveRafRef.current);
saveRafRef.current = null;
}
saveScrollSnapshot(true);
};
// sessionId 在本组件生命周期内不变(parent 用 key 重挂载);saveScrollSnapshot
// 通过 ref 镜像在 cleanup 时读到最新的位置 / 锚点 / nearBottom。
}, [saveScrollSnapshot]);
useLayoutEffect(() => {
if (!import.meta.env.DEV) return;
if (!perfFirstPaintLoggedRef.current && visibleRenderItems.length > 0) {
perfFirstPaintLoggedRef.current = true;
perfLog.debug(
`stream:first-paint sid=${sessionId ?? 'null'} totalMsgs=${messages.length} totalItems=${allRenderItems.length} renderedItems=${visibleRenderItems.length} elapsed=${Math.round(performance.now() - perfMountTimeRef.current)}ms`,
);
}
// first-paint 只打一次;deps 保留日志里读取的计数,ref 负责短路后续变化。
}, [allRenderItems, visibleRenderItems, sessionId, messages.length]);
// ── viewport-fill auto-fill (二段式 mirror handleScroll) ──
// 处理"内容 < viewport 时的滚动死锁": scroll 容器是 h-full(撑满 viewport),
// 短 session 真实渲染高度可能远小于 viewport (item 少 / 单 item 短),
// scrollH = max(content, container) = clientH → scrollbar 不出现 → 用户的
// handleScroll 永远不会进"距顶<50px"分支 → 既不会 expandWindow 也不会
// onLoadMore → 内存里没显示的更老 item 以及 DB 里更老的历史都永远拉不到。
//
// 二段式 (与 handleScroll 里 "二段式加载" 注释段同款逻辑):
// Stage 1 — expand: render-window 还没覆盖内存全部 (visibleItems<allItems) →
// shouldAutoExpandRenderWindow=true → expandWindow() 把 render-window
// 的锚点往前挪 RENDER_WINDOW_GROWTH_ITEMS 个 item (无 IPC, 纯本地,
// 不计 attempt). 这步是必需的 — 否则 onLoadMore prepend 回来的更老
// 消息映射成的 render-item 会被 `slice(-INITIAL_ITEMS)` 切在外面看不见 →
// DOM 不渲染 → contentH 不增长 → scrollH 永远 = clientH → 死锁.
//
// Stage 2 — load: render-window 已覆盖内存全部 (windowAtTop=y) AND DB 还有
// 更老历史 → shouldAutoLoadMoreHistory=true → onLoadMore() 拉 DB
// (走 IPC, 计 attempt). 拉回来后 prepend 进 messages → buildRenderItems
// 重算 → allRenderItems 增长, 下次 effect 重新走 Stage 1 expand
// 把它纳入 visible.
//
// 终止条件 (任一满足):
// 1. scrollH > clientH → 出现滚动条, 用户可手动续翻
// 2. windowAtTop=y AND hasMoreMessages=false → DB 真的没历史了
// 3. attemptCount >= MAX_AUTO_LOAD_ATTEMPTS → 退化保护 (只数 IPC, 不数 expand)
//
// attemptCount 用 ref 持有,让同一次 mount 内仍可按原预算连续补页。第一次真的
// 成功推进缓存窗口后同时在 sessionScrollStore 记 completed;切走再切回的新 mount
// 直接从耗尽态开始,避免 leaveView 裁掉已补前缀后把同一页重新拉一遍。
// 用户明确向上滚动 / 翻页走 decideUserIntentFillAction,不读取这份自动预算。
// useLayoutEffect 而不是 useEffect — 在 commit 同步阶段读 scrollH/clientH,
// 避免 useEffect 滞后一帧导致跟 ResizeObserver/pinToBottom 的副作用错序.
//
// prevScrollHeightRef / prevScrollTopAtLoadRef 在两段都 set, 与 handleScroll
// 完全对称, 让 F-SYNC-2 effect 的 anchoring 检测 + fallback 补偿正常工作.
// 当前触发条件下 (scrollH===clientH) scrollTop 必为 0, 视觉收敛主要靠 line 716
// 的 pinToBottom effect, 这两个 ref 在这是防御层 (避免 IPC race window 里
// handleScroll 误覆盖 ref 用错快照 → F-SYNC-2 算错 delta).
const {
viewportAttemptsRef: autoLoadAttemptCountRef,
navRailRoundsRef: navRailBackfillRoundsRef,
runAutomaticLoad,
} = useAutomaticHistoryLoadBudget(
sessionId,
MAX_AUTO_LOAD_ATTEMPTS,
NAV_RAIL_BACKFILL_MAX_ROUNDS,
{
historyLoaded,
messageCount: messages.length,
firstMessageClientId: messages[0]?.clientId ?? null,
},
);
// MessageStream 只按 sessionId remount。逻辑窗口在同一 mount 内被 reload / reconcile /
// truncate 时,hook 会同步归零两套本地预算;不能只用 messages identity,正常
// push/prepend 同样会换引用。
useLayoutEffect(() => {
const el = scrollRef.current;
if (!el) return;
if (visibleRenderItems.length === 0) return; // first-paint 之前不判
// hasMoreMessages / isLoadingMore 是 props 上的可选 boolean, 统一规整成 boolean
// 再喂给 helper (否则 TS narrow 跨 OR 短路失效).
const action = decideAutoFillAction({
scrollHeight: el.scrollHeight,
clientHeight: el.clientHeight,
windowAtTop,
hasMoreMessages: hasMoreMessages ?? false,
isLoadingMore: isLoadingMore ?? false,
attemptCount: autoLoadAttemptCountRef.current,
});
switch (action) {
case 'expand-window': {
prevScrollHeightRef.current = el.scrollHeight;
prevScrollTopAtLoadRef.current = el.scrollTop;
expandWindow();
return;
}
case 'load-from-db': {
if (!onLoadMore) return; // 父没接 onLoadMore (理论上 decideAutoFillAction
// 不应在这种情况下返 'load-from-db', 这里防御一下)
autoLoadAttemptCountRef.current += 1;
prevScrollHeightRef.current = el.scrollHeight;
prevScrollTopAtLoadRef.current = el.scrollTop;
void runAutomaticLoad(onLoadMore);
return;
}
case 'none':
// render-window-bidirectional: 锚定窗口未覆盖末尾且内容不溢出时,
// expandWindow 只向前扩(向最早方向)、保持窗口尾边不变;对向后
// 方向(锚点后的内容)没有帮助。这里从尾部扩 anchoredForwardItems
// 把锚点后内容逐步纳入 DOM,直到视口撑出滚动条或窗口触及全量末尾。
if (
firstVisibleItemKey !== null &&
!windowCoversEnd &&
Math.abs(el.scrollHeight - el.clientHeight) <= NO_SCROLL_TOLERANCE_PX
) {
setAnchoredForwardItems((prev) => prev + RENDER_WINDOW_GROWTH_ITEMS);
}
return;
}
}, [
visibleRenderItems.length,
bottomPadding,
hasMoreMessages,
isLoadingMore,
onLoadMore,
runAutomaticLoad,
sessionId,
windowAtTop,
expandWindow,
windowCoversEnd,
firstVisibleItemKey,
]);
// ── F2 / new-message-indicator ──
// `isNearBottomRef` 驱动 auto-follow 判定;`isNearBottom` state 只驱动按钮
// 显隐(两者同步更新,任何路径都不允许只更新其中一个)。
// `unreadCount` = 离底期间累计的未读键数(同一回合的回复只算一条,见
// unreadCount.ts),点击按钮 / 自动回底 / 切换会话 → 归零。
// Restored history starts unfollowed. Initialize the indicator from the same
// snapshot as the scroll gate: later input may correctly leave false unchanged.
const [isNearBottom, setIsNearBottom] = useState<boolean>(() => isNearBottomRef.current);
const [unreadKeys, setUnreadKeys] = useState<ReadonlySet<string>>(NO_UNREAD_KEYS);
const unreadCount = unreadKeys.size;
// Only the rendered tail of a canonical Bot chat acknowledges replies. History
// navigation, background windows and streaming work never move its read position.
useEffect(() => {
if (!onBotReadThrough || !historyLoaded || !isNearBottom || isSessionStreaming) return;
const acknowledge = () => {
if (restoringRef.current || document.visibilityState !== 'visible' || !document.hasFocus() || !isNearBottomRef.current) return;
const at = allRenderItems.reduce((latest, item) => {
if (item.type !== 'message' || item.message.role !== 'assistant' || item.message.isStreaming) return latest;
const stamp = new Date(item.message.createdAt ?? '').getTime();
return Number.isFinite(stamp) ? Math.max(latest, stamp) : latest;
}, 0);
if (at > 0) onBotReadThrough(at);
};
const frame = requestAnimationFrame(acknowledge);
window.addEventListener('focus', acknowledge);
document.addEventListener('visibilitychange', acknowledge);
return () => {
cancelAnimationFrame(frame);
window.removeEventListener('focus', acknowledge);
document.removeEventListener('visibilitychange', acknowledge);
};
}, [onBotReadThrough, historyLoaded, isNearBottom, isSessionStreaming, allRenderItems]);
/** 上一次 render 已见过的 clientId 集合,用于 O(n) diff 出"首次出现"的消息。 */
const prevMessageIdsRef = useRef<Set<string>>(new Set());
// ── 意图解除 auto-follow ──
// wheel 上滚 / 触摸下拉 / PageUp 等历史导航键只有用户能产生(程序化 scrollTop
// 赋值不发这些事件),在事件层直接解除跟随:不经过 scroll 事件,不受
// programmaticScrollRef 竞态影响,也不看距离阈值 — 上滚一行(哪怕 1px)立即
// 停止自动滚动。距离阈值只保留给「恢复跟随」与滚动条拖拽的解除兜底
// (见 autoFollowIntent.ts 模块注释与 handleScroll)。
// 是否构成解除条件由各事件路径的纯函数判定(shouldUnpinOnWheel /
// shouldUnpinOnUpIntent),本回调只负责翻转:ref 与 state 同步更新(F2 不
// 变量);unreadCount 不动 — 它只在回底时清零。
const unpinAutoFollowForUserUpIntent = useCallback(() => {
restoringRef.current = false;
if (!isNearBottomRef.current) return;
bumpSendFollowCancelGeneration(sessionId);
isNearBottomRef.current = false;
setIsNearBottom(false);
}, [sessionId]);
// 与 unpin 对称:用户已经贴死底部时的向下意图恢复跟随。不经过 scroll 事件 —
// 贴死底部后再往下滚通常不再改变 scrollTop。历史切片的底不是会话尾,不能从
// 那里开始跟随(与 resolveEffectiveNearBottom 同口径)。覆盖末尾的锚定窗也要
// 一并清掉,否则下一条 token 会 uncover 再 unpin。
const pinAutoFollowForUserDownIntent = useCallback(() => {
restoringRef.current = false;
if (!windowCoversEndRef.current) return;
if (isNearBottomRef.current) return;
isNearBottomRef.current = true;
setIsNearBottom(true);
setUnreadKeys(NO_UNREAD_KEYS);
setFirstVisibleItemKey(null);
}, []);
// 滚动条拖拽:只记按下时的 scrollTop。单纯 mousedown 不解除;上移过死区才 unpin。
// 按下期间停掉流式 pin,避免 programmatic 窗口把拖拽 scroll 吞掉后再钉回。
const scrollbarDragStartTopRef = useRef<number | null>(null);
const pinToBottomRef = useRef<() => void>(() => {});
// 拖拽态必须有界结束:mouseup / blur / pointercancel / 页签隐藏都走这里。
// Alt-Tab 后在别处松手收不到 mouseup,不清理则 pinToBottom 会永久提前返回。
const endScrollbarDrag = useCallback(() => {
if (scrollbarDragStartTopRef.current == null) return;
scrollbarDragStartTopRef.current = null;
if (isNearBottomRef.current) pinToBottomRef.current();
}, []);
// ── jump-to-bottom chip ──
// 用户向下滚动且未到底时显示扁平的"跳到底部" chip,2s 内无滚动自动隐藏。
// 与 NewMessageIndicator 互斥(它有未读时优先)。state 用 setter 直接控制,
// timer 走 ref 持有句柄方便 reset / cleanup。
const [showJumpDown, setShowJumpDown] = useState(false);
const jumpDownIdleTimerRef = useRef<number | null>(null);
// 卸载时清掉 idle timer 防泄漏
useEffect(
() => () => {
if (jumpDownIdleTimerRef.current !== null) {
window.clearTimeout(jumpDownIdleTimerRef.current);
jumpDownIdleTimerRef.current = null;
}
},
[],
);
// ── chip-jump expand/load 抑制 ──
// chip click 跳转的 smooth scroll 期间,如果路径穿过 scrollTop<50 会触发
// expandWindow/onLoadMore,叠加 F-SYNC-2 的 scrollTop+=delta 会把 viewport
// 拽向不可预期位置(疑为"长距离跳转踹回底"现象的源头,见 13:12 日志分析)。
// 抑制策略:click 时设 ref,任何**用户主动滚动意图**(wheel/touch/PageUp 等)
// 立刻解抑,smooth scroll 自身不发这些事件,所以 race 期间稳定抑制,用户一
// 动手就立即通行 — 不会卡住"用 chip 连点上翻"或"跳完立刻 wheel 看更老历史"。
// 3s safety timer 兜底,应对极端 case(用户 click 后既不滚也不动键盘)。
const chipJumpInProgressRef = useRef<boolean>(false);
const chipJumpGenerationRef = useRef<number | null>(null);
const chipJumpTargetRef = useRef<ChipJumpTarget | null>(null);
const chipJumpClearTimerRef = useRef<number | null>(null);
const userHistoryTouchStartYRef = useRef<number | null>(null);
const userIntentLoadInFlightRef = useRef<boolean>(false);
const finishChipJump = useCallback(
(
generation: number,
{
consumeDeferredDelete = false,
refreshAnchor = false,
}: { consumeDeferredDelete?: boolean; refreshAnchor?: boolean } = {},
): boolean | null => {
if (chipJumpGenerationRef.current !== generation) return null;
chipJumpGenerationRef.current = null;
if (chipJumpTargetRef.current?.generation === generation) {
chipJumpTargetRef.current = null;
}
chipJumpInProgressRef.current = false;
if (chipJumpClearTimerRef.current !== null) {
window.clearTimeout(chipJumpClearTimerRef.current);
chipJumpClearTimerRef.current = null;
}
const replayingDelete = finishProgrammaticScroll(generation, { consumeDeferredDelete });
if (refreshAnchor && replayingDelete === false) refreshViewportAnchor();
return replayingDelete;
},
[finishProgrammaticScroll, refreshViewportAnchor],
);
// wheel/touch/键盘接管:结束当前 smooth,但让期间延期的删除补偿重放。
const clearChipJumpSuppression = useCallback(() => {
// Only input intent ends restoration. Chromium's intrinsic-size correction
// also emits scroll events and must not be mistaken for a user scroll.
restoringRef.current = false;
suppressHeightCompensationUntilRef.current = 0;
disclosureAnchorRef.current = null;
// 只在打断真正的导航跳转(chip / focus / 延期删除补偿)时解除跟随。
// 流式 pinToBottom 也会打开 programmaticScrollRef,把它算进接管条件会让
// 生成期间任意滚轮或点滚动条都把跟随掐死;人已经在底部时再也产生不了
// 向下 scroll,跟随就恢复不了。想离开底部走 wheel / 触控 / 键盘的上滚意图。
if (
deferredDeleteCompensationRef.current ||
chipJumpGenerationRef.current !== null ||
focusJumpRef.current
) {
unpinAutoFollowForUserUpIntent();
}
const generation = chipJumpGenerationRef.current;
if (generation !== null) {
finishChipJump(generation);
const root = scrollRef.current;
if (root) root.scrollTo({ top: root.scrollTop, behavior: 'auto' });
return;
}
chipJumpInProgressRef.current = false;
if (chipJumpClearTimerRef.current !== null) {
window.clearTimeout(chipJumpClearTimerRef.current);
chipJumpClearTimerRef.current = null;
}
if (focusJumpRef.current) {
cancelFocusJump();
return;
}
if (programmaticScrollRef.current) {
finishProgrammaticScroll(programmaticScrollGenerationRef.current);
const root = scrollRef.current;
if (root) root.scrollTo({ top: root.scrollTop, behavior: 'auto' });
}
}, [cancelFocusJump, finishChipJump, finishProgrammaticScroll, unpinAutoFollowForUserUpIntent]);
// 正常落定:删除 / 流式更新可能让 smooth 开始时算出的像素落点失效。必须按本次
// generation 保存的目标标识重新查 DOM、瞬时校正后,才能让确定落点消费延期删除补偿。
// 目标已被删 / DOM 不可用时不消费,交给通用删除补偿重放。
const settleChipJump = useCallback(
(expectedGeneration?: number) => {
const generation = expectedGeneration ?? chipJumpGenerationRef.current;
if (generation === null || chipJumpGenerationRef.current !== generation) return;
const target = chipJumpTargetRef.current;
let targetResolved = false;
const root = scrollRef.current;
if (root && target?.generation === generation) {
const selectorAttribute =
target.selector === 'user-message' ? 'data-user-msg-id' : 'data-message-client-id';
const element = root.querySelector<HTMLElement>(
`[${selectorAttribute}="${CSS.escape(target.clientId)}"]`,
);
if (element) {
const correctedScrollTop = resolveChipJumpTargetScrollTop({
scrollTop: root.scrollTop,
containerTop: root.getBoundingClientRect().top,
targetTop: element.getBoundingClientRect().top,
topOffset: target.topOffset,
});
if (Math.abs(correctedScrollTop - root.scrollTop) >= 1)
root.scrollTop = correctedScrollTop;
targetResolved = true;
}
}
// 只消费校正前已观察到的删除;校正后、下一帧 finish 前新到的删除会重新置位,
// 仍由 finish 触发重放,不能被这次导航一并吞掉。
if (targetResolved) deferredDeleteCompensationRef.current = false;
requestAnimationFrame(() => finishChipJump(generation, { refreshAnchor: true }));
},
[finishChipJump],
);
const beginChipJump = useCallback(
(target: Omit<ChipJumpTarget, 'generation'>) => {
restoringRef.current = false;
if (chipJumpClearTimerRef.current !== null) {
window.clearTimeout(chipJumpClearTimerRef.current);
}
chipJumpInProgressRef.current = true;
const generation = beginProgrammaticScroll();
chipJumpGenerationRef.current = generation;
chipJumpTargetRef.current = { ...target, generation };
chipJumpClearTimerRef.current = window.setTimeout(() => {
settleChipJump(generation);
}, CHIP_JUMP_SAFETY_MS);
},
[beginProgrammaticScroll, settleChipJump],
);
useEffect(() => {
const root = scrollRef.current;
if (!root) return;
const navigateText = (event: Event) => {
const range = (event as CustomEvent<Range>).detail;
const element = range?.startContainer?.parentElement?.closest<HTMLElement>('[data-message-client-id]');
const clientId = element?.dataset.messageClientId;
if (!element || !clientId || !root.contains(element)) return;
event.preventDefault();
cancelFocusJump({ consumeDeferredDelete: true });
unpinAutoFollowForUserUpIntent();
// Keep the exact text below the find bar. Reuse message navigation's
// ownership, cancellation and settling, so reaching the oldest loaded
// row is not misread as user intent to fetch another history page.
scrollRangeIntoView(range, root);
const topOffset = Math.min(80, root.clientHeight / 3)
- (range.getBoundingClientRect().top - element.getBoundingClientRect().top);
beginChipJump({ clientId, selector: 'message', topOffset });
root.scrollTop = resolveChipJumpTargetScrollTop({
scrollTop: root.scrollTop, containerTop: root.getBoundingClientRect().top,
targetTop: element.getBoundingClientRect().top, topOffset,
});
syncMessageViewport();
};
root.addEventListener(PAGE_TEXT_NAVIGATION_EVENT, navigateText);
return () => root.removeEventListener(PAGE_TEXT_NAVIGATION_EVENT, navigateText);
}, [beginChipJump, cancelFocusJump, syncMessageViewport, unpinAutoFollowForUserUpIntent]);
useEffect(() => {
const root = scrollRef.current;
if (!root) return;
const onScrollEnd = () => {
settleChipJump();
// Each navigation owner finishes its own generation after correcting its
// target. Generic scrollend must not invalidate a pending focus settle.
if (chipJumpGenerationRef.current !== null || focusJumpRef.current !== null) return;
if (!programmaticScrollRef.current) return;
const generation = programmaticScrollGenerationRef.current;
if (finishProgrammaticScroll(generation) === false) refreshViewportAnchor(true);
};
root.addEventListener('scrollend', onScrollEnd);
return () => root.removeEventListener('scrollend', onScrollEnd);
}, [finishProgrammaticScroll, refreshViewportAnchor, settleChipJump]);
useEffect(() => {
return () => {
if (chipJumpClearTimerRef.current !== null) {
window.clearTimeout(chipJumpClearTimerRef.current);
chipJumpClearTimerRef.current = null;
}
chipJumpGenerationRef.current = null;
chipJumpTargetRef.current = null;
chipJumpInProgressRef.current = false;
};
}, []);
useEffect(() => {
if (isLoadingMore !== true) {
userIntentLoadInFlightRef.current = false;
}
}, [isLoadingMore]);
const triggerUserIntentFill = useCallback(() => {
const el = scrollRef.current;
if (!el) return;
if (visibleRenderItems.length === 0) return; // first-paint 之前不判
if (chipJumpInProgressRef.current) return;
const action = decideUserIntentFillAction({
scrollTop: el.scrollTop,
triggerDistancePx: historyPrefetchThreshold(el.clientHeight),
scrollHeight: el.scrollHeight,
clientHeight: el.clientHeight,
windowAtTop,
hasMoreMessages: hasMoreMessages ?? false,
isLoadingMore: (isLoadingMore ?? false) || userIntentLoadInFlightRef.current,
});
// Input may arrive before the queued scroll snapshot frame. Capture the
// current reading position before expanding or starting a remote read.
if (action !== 'none') refreshViewportAnchor();
switch (action) {
case 'expand-window': {
prevScrollHeightRef.current = el.scrollHeight;
prevScrollTopAtLoadRef.current = el.scrollTop;
expandWindow();
return;
}
case 'load-from-db': {
if (!onLoadMore) return;
userIntentLoadInFlightRef.current = true;
prevScrollHeightRef.current = el.scrollHeight;
prevScrollTopAtLoadRef.current = el.scrollTop;
const release = () => {
userIntentLoadInFlightRef.current = false;
};
void onLoadMore().then(release, release);
return;
}
case 'none':
return;
}
}, [
visibleRenderItems.length,
windowAtTop,
hasMoreMessages,
isLoadingMore,
onLoadMore,
expandWindow,
refreshViewportAnchor,
]);
useEffect(() => {
const root = scrollRef.current;
if (!root) return;
// wheel/touchstart 挂在 scroll 容器上(与上 chip 抑制对称)。容器不可滚时
// 不会产生 scroll 事件,所以用户继续向上滚动的意图必须在这里接住。
const onWheel = (event: WheelEvent) => {
// Chromium reports pinch/modified-wheel zoom as wheel events. Filter at
// the input boundary before navigation, follow-state or history effects.
if (event.ctrlKey || event.metaKey) return;
clearChipJumpSuppression();
if (isUpwardWheelIntent(event)) {
if (hasNestedScrollableAncestorThatCanScrollUp(root, event.target)) return;
if (
shouldUnpinOnWheel({
deltaX: event.deltaX,
deltaY: event.deltaY,
scrollHeight: root.scrollHeight,
clientHeight: root.clientHeight,
})
) {
unpinAutoFollowForUserUpIntent();
}
triggerUserIntentFill();
return;
}
if (event.deltaY > 0) {
if (hasNestedScrollableAncestorThatCanScrollDown(root, event.target)) return;
const distanceFromBottom = root.scrollHeight - root.scrollTop - root.clientHeight;
if (
shouldRepinOnWheel({
deltaX: event.deltaX,
deltaY: event.deltaY,
distanceFromBottom,
})
) {
pinAutoFollowForUserDownIntent();
}
}
};
const onTouchStart = (event: TouchEvent) => {
clearChipJumpSuppression();
userHistoryTouchStartYRef.current = event.touches[0]?.clientY ?? null;
};
const onTouchMove = (event: TouchEvent) => {
const startY = userHistoryTouchStartYRef.current;
const currentY = event.touches[0]?.clientY;
if (startY == null || currentY == null) return;
if (currentY - startY > TOUCH_HISTORY_INTENT_THRESHOLD_PX) {
userHistoryTouchStartYRef.current = currentY;
if (hasNestedScrollableAncestorThatCanScrollUp(root, event.target)) return;
if (
shouldUnpinOnUpIntent({
scrollHeight: root.scrollHeight,
clientHeight: root.clientHeight,
})
) {
unpinAutoFollowForUserUpIntent();
}
triggerUserIntentFill();
return;
}
if (startY - currentY > TOUCH_HISTORY_INTENT_THRESHOLD_PX) {
userHistoryTouchStartYRef.current = currentY;
if (hasNestedScrollableAncestorThatCanScrollDown(root, event.target)) return;
const distanceFromBottom = root.scrollHeight - root.scrollTop - root.clientHeight;
if (shouldRepinOnDownIntent({ distanceFromBottom })) {
pinAutoFollowForUserDownIntent();
}
}
};
const onTouchEnd = () => {
userHistoryTouchStartYRef.current = null;
};
const onMouseDown = (event: MouseEvent) => {
clearChipJumpSuppression();
if (
isVerticalScrollbarPress({
targetIsRoot: event.target === root,
offsetX: event.offsetX,
clientWidth: root.clientWidth,
})
) {
scrollbarDragStartTopRef.current = root.scrollTop;
}
};
const onMouseMove = () => {
const startTop = scrollbarDragStartTopRef.current;
if (startTop == null) return;
if (
shouldUnpinOnScrollbarDrag({
pointerDown: true,
scrollDelta: root.scrollTop - startTop,
directionDeadZonePx: SCROLL_DIRECTION_DEAD_ZONE_PX,
}) &&
shouldUnpinOnUpIntent({ scrollHeight: root.scrollHeight, clientHeight: root.clientHeight })
) {
unpinAutoFollowForUserUpIntent();
}
};
const onMouseUp = () => {
endScrollbarDrag();
};
const onPointerCancel = () => {
endScrollbarDrag();
};
const onWindowBlur = () => {
endScrollbarDrag();
};
const onVisibilityChange = () => {
if (document.hidden) endScrollbarDrag();
};
root.addEventListener('wheel', onWheel, { passive: true });
root.addEventListener('touchstart', onTouchStart, { passive: true });
root.addEventListener('touchmove', onTouchMove, { passive: true });
root.addEventListener('touchend', onTouchEnd, { passive: true });
root.addEventListener('touchcancel', onTouchEnd, { passive: true });
root.addEventListener('mousedown', onMouseDown);
window.addEventListener('mousemove', onMouseMove);
window.addEventListener('mouseup', onMouseUp);
window.addEventListener('pointercancel', onPointerCancel);
window.addEventListener('blur', onWindowBlur);
document.addEventListener('visibilitychange', onVisibilityChange);
return () => {
root.removeEventListener('wheel', onWheel);
root.removeEventListener('touchstart', onTouchStart);
root.removeEventListener('touchmove', onTouchMove);
root.removeEventListener('touchend', onTouchEnd);
root.removeEventListener('touchcancel', onTouchEnd);
root.removeEventListener('mousedown', onMouseDown);
window.removeEventListener('mousemove', onMouseMove);
window.removeEventListener('mouseup', onMouseUp);
window.removeEventListener('pointercancel', onPointerCancel);
window.removeEventListener('blur', onWindowBlur);
document.removeEventListener('visibilitychange', onVisibilityChange);
};
}, [
clearChipJumpSuppression,
endScrollbarDrag,
pinAutoFollowForUserDownIntent,
triggerUserIntentFill,
unpinAutoFollowForUserUpIntent,
]);
useEffect(() => {
const onHistoryNavigationKey = (event: KeyboardEvent) => {
if (!ownsHardwareScrollActions) return;
if (event.defaultPrevented) return;
if (event.key === 'Tab') {
clearChipJumpSuppression();
return;
}
if (!HISTORY_NAVIGATION_KEYS.has(event.key)) return;
if (isEditableKeyboardTarget(event.target)) return;
clearChipJumpSuppression();
const el = scrollRef.current;
if (
el &&
shouldUnpinOnUpIntent({ scrollHeight: el.scrollHeight, clientHeight: el.clientHeight })
) {
unpinAutoFollowForUserUpIntent();
}
triggerUserIntentFill();
};
window.addEventListener('keydown', onHistoryNavigationKey);
return () => {
window.removeEventListener('keydown', onHistoryNavigationKey);
};
}, [
clearChipJumpSuppression,
ownsHardwareScrollActions,
triggerUserIntentFill,
unpinAutoFollowForUserUpIntent,
]);
useNavigationKeyListener(clearChipJumpSuppression, ownsHardwareScrollActions);
const pinToBottom = useCallback((fromLayout = false) => {
const el = scrollRef.current;
if (!el) return;
// 滚动条拖拽中不要钉回,否则滑块上移会被下一帧 pin 吃掉。
if (scrollbarDragStartTopRef.current != null) return;
const generation = beginProgrammaticScroll();
suppressScrollbarActivation(el);
el.scrollTop = el.scrollHeight;
// Layout effects already flush their state updates before paint. Observer
// and input callbacks need an explicit commit before the next scroll event.
if (fromLayout) reconcileMessageViewport();
else syncMessageViewport();
// Clear the flag on the next frame — after the browser has dispatched
// the resulting scroll event. We use rAF (not a microtask) because the
// scroll event is dispatched asynchronously.
requestAnimationFrame(() => {
if (finishProgrammaticScroll(generation) === false && !isNearBottomRef.current) {
refreshViewportAnchor();
}
});
}, [beginProgrammaticScroll, finishProgrammaticScroll, refreshViewportAnchor, reconcileMessageViewport, syncMessageViewport]);
pinToBottomRef.current = pinToBottom;
// Composer send is an explicit "show me the result" intent. Don't wait for
// the tail render item to be a user message — assistant / tool cards often
// land in the same commit and used to hide the send from pin detection.
// This is the only force-follow path: inference must not pin, because an
// optimistic row can appear after the user already scrolled away.
useLayoutEffect(() => {
if (prevFollowLatestRequestKeyRef.current === followLatestRequestKey) return;
prevFollowLatestRequestKeyRef.current = followLatestRequestKey;
cancelFocusJump({ consumeDeferredDelete: true });
const chipJumpGeneration = chipJumpGenerationRef.current;
if (chipJumpGeneration !== null) {
finishChipJump(chipJumpGeneration, { consumeDeferredDelete: true });
}
setFirstVisibleItemKey(null);
restoringRef.current = false;
isNearBottomRef.current = true;
setIsNearBottom(true);
setUnreadKeys(NO_UNREAD_KEYS);
pinToBottom(true);
}, [cancelFocusJump, finishChipJump, followLatestRequestKey, pinToBottom]);
// F3: 平滑滚到底的按钮回调。
// - 乐观更新 unreadCount / isNearBottom / isNearBottomRef → 按钮同一 tick fade-out
// - programmaticScrollRef 打开 → scroll handler 在动画期间不会误判为"用户上滚"
// - 原生 smooth 由浏览器接管(~300ms),不手写 rAF
// - 动画期间 ResizeObserver 仍可正常 pinToBottom,auto-follow 无缝接入
const scrollToBottomSmooth = useCallback(() => {
const el = scrollRef.current;
if (!el) return;
restoringRef.current = false;
// 显式的新导航取代尚未落定的搜索 focus;自身的底部落点会消费此前延期的删除补偿。
cancelFocusJump({ consumeDeferredDelete: true });
const chipJumpGeneration = chipJumpGenerationRef.current;
if (chipJumpGeneration !== null) {
finishChipJump(chipJumpGeneration, { consumeDeferredDelete: true });
}
setUnreadKeys(NO_UNREAD_KEYS);
setIsNearBottom(true);
isNearBottomRef.current = true;
const generation = beginProgrammaticScroll();
// render-window-bidirectional: 清除锚点回到默认尾部窗口(chip/jump-down 语义)。
flushSync(() => setFirstVisibleItemKey(null));
el.scrollTo({ top: el.scrollHeight, behavior: 'smooth' });
syncMessageViewport();
window.setTimeout(() => {
if (finishProgrammaticScroll(generation) === false) refreshViewportAnchor();
}, CHIP_JUMP_SAFETY_MS);
}, [
beginProgrammaticScroll,
cancelFocusJump,
finishChipJump,
finishProgrammaticScroll,
refreshViewportAnchor,
syncMessageViewport,
]);
// ── Codex Micro 摇杆:按住持续滚动 ──
// 摇杆推住时主进程持续送 { type:'scroll', intensity },这里逐帧按速度改
// scrollTop —— 像拖鼠标滚轮,而不是每拨一下跳一屏。速度走平方曲线(见
// shared/workLouderCodexScroll.ts):轻推能微调,推到底才最快。
// 不用 behavior:'smooth' —— 逐帧位移叠加缓动会互相打架,松手后还会惯性飘。
const joystickScrollRef = useRef<{ direction: 'up' | 'down'; intensity: number } | null>(null);
const joystickScrollFrameRef = useRef<number | null>(null);
const stopJoystickScroll = useCallback(() => {
joystickScrollRef.current = null;
if (joystickScrollFrameRef.current !== null) {
cancelAnimationFrame(joystickScrollFrameRef.current);
joystickScrollFrameRef.current = null;
}
}, []);
useEffect(() => stopJoystickScroll, [stopJoystickScroll]);
useEffect(() => {
if (!ownsHardwareScrollActions) stopJoystickScroll();
return subscribeWorkLouderCodexAction((action) => {
if (action.type === 'scroll-stop') {
stopJoystickScroll();
return ownsHardwareScrollActions;
}
if (!ownsHardwareScrollActions) return false;
if (action.type === 'scroll') {
joystickScrollRef.current = { direction: action.direction, intensity: action.intensity };
if (joystickScrollFrameRef.current !== null) return true;
let lastAt = performance.now();
const step = (now: number): void => {
joystickScrollFrameRef.current = null;
const active = joystickScrollRef.current;
const el = scrollRef.current;
if (!active || !el) return;
const delta = joystickScrollDelta(active.intensity, now - lastAt);
lastAt = now;
if (active.direction === 'up') {
// 程序化改 scrollTop 不发 wheel 事件,所以不会自动解除 auto-follow;
// 不显式解除的话,向上滚会被跟随逻辑一路拽回底部。
unpinAutoFollowForUserUpIntent();
el.scrollTop -= delta;
} else {
el.scrollTop += delta;
}
syncMessageViewport();
joystickScrollFrameRef.current = requestAnimationFrame(step);
};
joystickScrollFrameRef.current = requestAnimationFrame(step);
return true;
}
if (action.type !== 'command') return false;
if (action.commandId === 'conversation.scrollBottom') {
scrollToBottomSmooth();
return true;
}
// 键盘快捷键与改绑到其它键的场景仍走这条一次性路径。
if (
action.commandId !== 'conversation.scrollUp' &&
action.commandId !== 'conversation.scrollDown'
) {
return false;
}
const el = scrollRef.current;
if (!el) return false;
const direction = action.commandId === 'conversation.scrollUp' ? -1 : 1;
if (direction < 0) unpinAutoFollowForUserUpIntent();
el.scrollBy({
top: direction * Math.max(160, el.clientHeight * 0.7),
behavior: 'smooth',
});
return true;
});
}, [
ownsHardwareScrollActions,
scrollToBottomSmooth,
stopJoystickScroll,
unpinAutoFollowForUserUpIntent,
syncMessageViewport,
]);
// F2: messages diff → 累计未读键
// - 计数规则抽成纯函数 collectUnreadKeys(见 unreadCount.ts):新 clientId 才计、
// 贴底不计、同一回合的回复只算一条;#2194 起非本端发送的 user 也计。
useEffect(() => {
const prev = prevMessageIdsRef.current;
const currentIds = new Set<string>();
for (const m of messages) currentIds.add(m.clientId);
const { keys: addedKeys, supersedes } = collectUnreadKeys({
prevIds: prev,
messages,
nearBottom: isNearBottomRef.current,
isLocalUserSend,
});
if (addedKeys.length > 0) {
setUnreadKeys((keys) => {
const next = new Set(keys);
for (const key of supersedes) next.delete(key);
for (const key of addedKeys) next.add(key);
return next.size === keys.size && addedKeys.every((key) => keys.has(key)) ? keys : next;
});
}
prevMessageIdsRef.current = currentIds;
}, [messages, isLocalUserSend]);
// ── Synchronous pin-to-bottom on every relevant change. ──
// useLayoutEffect fires before paint, so a new message / bottomPadding change
// never flashes at the old scroll position. Runs on:
// • initial mount (keyed by sessionId in parent → one fresh run per session)
// • messages reference change (new token, new card, etc.)
// • bottomPadding change (overlay re-measured after Plan Viewer expand etc.)
// ResizeObserver below is a safety net for async height growth *after* paint
// (markdown render finish, image/code-highlight completion).
//
// Local send force-follow is only followLatestRequestKey. Inference here
// must not pin or steal the window: attachment prep can insert the
// optimistic row after the user already unpinned.
// biome-ignore lint/correctness/useExhaustiveDependencies: bottomPadding 是触发型依赖;overlay 高度变化时即使 effect 内不读取它,也必须重新 pin 到底。
useLayoutEffect(() => {
const tailUserMessageId = selectTailUserMessageId({
windowCoversEnd,
visibleItems: visibleRenderItems,
allItems: allRenderItems,
userMessageId: (item) =>
item?.type === 'message' && item.message.role === 'user' ? item.message.clientId : null,
});
const lastUserMsg =
tailUserMessageId === null
? null
: findLastMatching(allRenderItems, (item) =>
item.type === 'message' && item.message.clientId === tailUserMessageId
? item.message
: null,
);
// #2194: 未提供回调时按既有语义视为本端发送(测试 / 其它消费方不变);
// 提供了回调就严格以其返回值为准——实现方误返回 undefined(如被 as any
// 绕过)时按外部注入处理,不用 ?? true 掩盖(Copilot review nit)。
const sentFromThisRenderer = lastUserMsg
? isLocalUserSend
? isLocalUserSend(lastUserMsg.clientId) === true
: true
: false;
const userMessageObservation = resolveLastUserMessageObservation({
restoring: restoringRef.current,
tailUserMessageId,
previousTailUserMessageId: lastUserMsgIdRef.current,
knownUserMessageIds: knownUserMessageIdsRef.current,
});
for (const id of collectKnownUserMessageIds(allRenderItems, (item) =>
item.type === 'message' && item.message.role === 'user' ? item.message.clientId : null,
)) {
knownUserMessageIdsRef.current.add(id);
}
lastUserMsgIdRef.current = userMessageObservation.baselineUserMessageId;
const decision = resolveRenderPinDecision({
restoring: restoringRef.current,
newUserSend: false,
sentFromThisRenderer,
nearBottom: isNearBottomRef.current,
});
const windowHandoff = resolveSendWindowHandoff({
isNewUserSend: false,
sentFromThisRenderer,
hasWindowAnchor: firstVisibleItemKey !== null,
windowCoversEnd,
});
if (windowHandoff.clearWindowAnchor) {
setFirstVisibleItemKey(null);
isNearBottomRef.current = true;
setIsNearBottom(true);
setUnreadKeys(NO_UNREAD_KEYS);
}
if (userMessageObservation.isNewUserSend && lastUserMsg) {
lastUserMsgIdRef.current = lastUserMsg.clientId;
}
if (decision.clearRestoring) {
restoringRef.current = false;
isNearBottomRef.current = true;
}
if (decision.pinToBottom && !windowHandoff.deferPinToNextRender) pinToBottom(true);
const el = scrollRef.current;
if (el) prevScrollTopRef.current = el.scrollTop;
}, [
visibleRenderItems,
bottomPadding,
pinToBottom,
firstVisibleItemKey,
windowCoversEnd,
allRenderItems,
]);
// ── 还原浏览位置(layout effect,在上面的 pin-to-bottom effect 之后跑) ──
// mount 首帧 + 还原期间窗口变化时把视口摆回锚点。settle(图片/markdown 异步加载
// 改变高度但不改 visibleRenderItems)由下方 ResizeObserver 兜底纠偏。
// biome-ignore lint/correctness/useExhaustiveDependencies: visibleRenderItems 是触发型依赖;扩窗/加载历史后需要按最新 DOM 重新 applyRestore。
useLayoutEffect(() => {
if (!restoringRef.current) return;
applyRestore();
}, [visibleRenderItems, applyRestore]);
const suppressHeightCompensationUntilRef = useRef(0);
const disclosureAnchorRef = useRef<{ element: Element; offset: number } | null>(null);
const compensateMessageHeight = useCallback(() => {
if (
!canCompensateMessageHeight({
restoring: restoringRef.current,
nearBottom: isNearBottomRef.current,
programmatic: programmaticScrollRef.current,
loadingMore: isLoadingMore === true,
pendingPrepend: prevScrollHeightRef.current > 0,
pendingUserScroll: saveRafRef.current !== null,
dragging: scrollbarDragStartTopRef.current !== null,
expanding: performance.now() < suppressHeightCompensationUntilRef.current,
})
)
return;
const snapshot = lastViewportTopRef.current;
if (!snapshot) {
refreshViewportAnchor();
return;
}
// Missing rows are handled by the existing delete/window restoration path.
if (!visibleRenderItemsRef.current.some((item) => item.key === snapshot.viewportTopKey)) return;
// A deleted child can leave its work-group row intact. Preserve its exact
// anchor for the deletion effect below; restoring the group here would erase
// the child ID before that effect can choose the next surviving message.
// Check data, not DOM: collapsing a group only hides its children.
const messageClientId = snapshot.messageClientId;
if (
messageClientId !== undefined &&
!allRenderItemsRef.current.some((item) => renderItemContainsClientId(item, messageClientId))
)
return;
restoreViewportSnapshot(snapshot);
}, [isLoadingMore, refreshViewportAnchor, restoreViewportSnapshot]);
// Card insertion changes the row sequence before paint; asynchronous work-group
// height changes use the same correction below. Both preserve a measured anchor,
// rather than adding scrollHeight deltas that Chromium may have applied already.
useLayoutEffect(() => {
compensateMessageHeight();
}, [visibleRenderItems, bottomPadding, compensateMessageHeight]);
// ── Continuous auto-follow via ResizeObserver. ──
// Catches every source of content-height growth:
// • streaming tokens appending to an assistant message
// • tool cards / plan viewer expanding
// • markdown / code-highlighting / image loads finalizing async
// • bottomPadding changes (status bar, ask prompts)
// As long as the user hasn't scrolled up, we keep scrollTop pinned to
// scrollHeight. This replaces the old "scroll on messages/bottomPadding
// change" effect, which missed async height settles.
//
// 例外:卡片内用户点击"展开详情"(CARD_EXPAND_TOGGLE_EVENT 冒泡上来)。
// 这是"就地看内容"的意图,贴底时若照常 pin-to-bottom,展开区的高度会把
// 卡片头部顶出视口上方,看起来像"往上展开"。收到事件后开一个短抑制窗口,
// 窗口内保持被点击的标题位置(也抵消浏览器自己的 anchoring);窗口一过
// auto-follow 原样恢复,流式跟随不受影响。
useEffect(() => {
const content = contentRef.current;
if (!content) return;
const onCardExpandToggle = (event: Event, preserveHeader = true) => {
suppressHeightCompensationUntilRef.current = performance.now() + CARD_EXPAND_PIN_SUPPRESS_MS;
restoringRef.current = false;
const header =
preserveHeader && event.target instanceof Element ? event.target.closest('button') : null;
const container = scrollRef.current;
disclosureAnchorRef.current =
header && container
? {
element: header,
offset: container.getBoundingClientRect().top - header.getBoundingClientRect().top,
}
: null;
refreshViewportAnchor();
};
// All disclosures suppress auto-follow, but only opted-in headers stay fixed.
// A long-message footer moves down as text appears above it; following that
// button would scroll past the text the user just chose to read.
const onDisclosureClick = (event: MouseEvent) => {
const button =
event.target instanceof Element ? event.target.closest('button[aria-expanded]') : null;
if (button) {
onCardExpandToggle(event, button.hasAttribute('data-scroll-disclosure-header'));
}
};
content.addEventListener('click', onDisclosureClick, true);
content.addEventListener(CARD_EXPAND_TOGGLE_EVENT, onCardExpandToggle);
const ro = new ResizeObserver(() => {
// 还原中:内容高度因异步渲染 settle 时,持续按锚点纠偏(直到用户手动滚动接管)。
if (restoringRef.current) {
applyRestoreRef.current();
return;
}
if (performance.now() < suppressHeightCompensationUntilRef.current) {
const anchor = disclosureAnchorRef.current;
const container = scrollRef.current;
if (container && anchor?.element.isConnected) {
const delta = viewportAnchorCorrection(
container.getBoundingClientRect().top,
anchor.element.getBoundingClientRect().top,
anchor.offset,
);
if (delta !== 0) {
const generation = beginProgrammaticScroll();
container.scrollTop += delta;
requestAnimationFrame(() => finishProgrammaticScroll(generation));
}
}
refreshViewportAnchor();
return;
}
disclosureAnchorRef.current = null;
if (isNearBottomRef.current) {
pinToBottom();
return;
}
compensateMessageHeight();
refreshHiddenChildViewportAnchor();
});
ro.observe(content);
return () => {
content.removeEventListener(CARD_EXPAND_TOGGLE_EVENT, onCardExpandToggle);
content.removeEventListener('click', onDisclosureClick, true);
ro.disconnect();
};
}, [
pinToBottom,
refreshViewportAnchor,
refreshHiddenChildViewportAnchor,
compensateMessageHeight,
beginProgrammaticScroll,
finishProgrammaticScroll,
]);
// 折叠动画末帧可能已是 0fr,再卸载时内容高度几乎不变,ResizeObserver 不一定
// 再触发。精确 child 节点从 items 子树消失时补一次(数据仍在才重测)。
useEffect(() => {
const items = itemsRef.current;
if (!items) return;
const observer = new MutationObserver(() => {
compensateMessageHeight();
refreshHiddenChildViewportAnchor();
});
observer.observe(items, { childList: true, subtree: true });
return () => observer.disconnect();
}, [compensateMessageHeight, refreshHiddenChildViewportAnchor]);
// F-SYNC-2 + render-window: Preserve scroll position after either
// (a) DB prepend (messages 数组前端追加,触发 isLoadingMore false → render)
// (b) 客户端扩窗 (firstVisibleItemKey 前移,visibleRenderItems 头部增长)
// 两者本质都是"DOM 顶部增长,需要把 scrollTop 加上 delta",共用同一段恢复逻辑。
// 依赖 visibleRenderItems —— 它的引用变化 = DOM 顶部可能变化,触发器一致。
//
// ── 浏览器 scroll anchoring 双补偿防御 ──
//
// Chromium 默认开启 `overflow-anchor`,顶部 prepend 内容时**自动**调整 scrollTop
// 让 viewport 视觉锚点不漂。这条跟 F-SYNC-2 的 `scrollTop += delta` 做同一件事 ——
// 两者叠加 = scrollTop 被加了 2 倍 delta,viewport 直接被推到底。
//
// 防御:effect 入口比对实际 scrollTop 增量与内容高度增量。anchoring 真生效时,
// 浏览器为保持锚点元素视觉位置,scrollTop 增量应该 ≈ 内容高度增量(delta)。
// 若两者接近(差值在容差内),说明 anchoring 已经把 delta 加过了 → skip 手动补偿。
//
// 容差 ANCHORING_TOLERANCE_PX=50:anchoring 在 viewport 内找锚点元素时,如果锚点
// 不是完美贴顶会有几十 px 偏差,留出空间。比"scrollTop > snapshot + 8" 那种宽松
// 判断严格得多 — 反例(用户在 onLoadMore→effect 间隙手动下滑、其它 programmatic
// scroll 等)产生的 scrollTop 增量是随意值,极少恰好 ≈ delta,基本不会误判。
//
// 不直接关 scroll anchoring(CSS overflow-anchor:none) — 那会让 tool 卡展开 /
// 图片异步加载 / markdown 异步渲染等"viewport 上方内容增长"场景失去稳定性,而
// F-SYNC-2 只 cover visibleRenderItems 变化路径,接不住其它来源。保留 anchoring +
// 检测后跳过是最小副作用方案。
// biome-ignore lint/correctness/useExhaustiveDependencies: visibleRenderItems 是触发型依赖;DOM 顶部增长后需要重新检测 scroll anchoring。
useEffect(() => {
const el = scrollRef.current;
if (!el || isLoadingMore) return;
if (prevScrollHeightRef.current > 0) {
// Remote details can settle while a page is loading, so total height is
// not the displacement of the message being read. Prefer its live DOM
// anchor; browser anchoring may already have preserved that position.
const snapshot = lastViewportTopRef.current;
if (!isNearBottomRef.current && snapshot && restoreViewportSnapshot(snapshot)) return;
const newScrollHeight = el.scrollHeight;
const delta = newScrollHeight - prevScrollHeightRef.current;
// [mr-16 review #1] 判定从"scrollTop > snapshot + 8"收紧成"scrollTop 增量
// ≈ delta",避免在 onLoadMore → effect 间隙若有其它 scrollTop 写入(用户
// 手动下滑、其它 programmatic 路径)导致误判 anchoring 已生效 → 漏补偿 →
// viewport 跳变。具体规则与边界 case 见 scrollAnchoringDetect.ts + test。
const anchoringApplied = detectScrollAnchoringApplied({
prevScrollHeight: prevScrollHeightRef.current,
prevScrollTop: prevScrollTopAtLoadRef.current,
currentScrollHeight: newScrollHeight,
currentScrollTop: el.scrollTop,
});
if (delta > 0 && !anchoringApplied) {
// anchoring 没生效(viewport 内没合适锚点元素时 Chromium 会跳过自动调整),
// 由 F-SYNC-2 手动补偿,行为同原版。
const generation = beginProgrammaticScroll();
el.scrollTop += delta;
requestAnimationFrame(() => finishProgrammaticScroll(generation));
}
// anchoringApplied=true 分支无操作 — 浏览器 anchoring 已把 viewport 摆好。
prevScrollHeightRef.current = 0;
prevScrollTopAtLoadRef.current = 0;
}
}, [
visibleRenderItems,
isLoadingMore,
beginProgrammaticScroll,
finishProgrammaticScroll,
restoreViewportSnapshot,
]);
// ── 删除靠前 message 后的视口保位(#2289)──
// 快照来自滚动/跳转落定;删除提交后再量会使 delta 恒为 0。贴底交给 pin-to-bottom。
useLayoutEffect(() => {
const prevVisibleItems = prevVisibleItemsRef.current;
const prevAllItems = prevAllItemsRef.current;
prevVisibleItemsRef.current = visibleRenderItems;
prevAllItemsRef.current = allRenderItems;
// #3067: turn 完成会把运行中工作组重建为完成态分组,key / 数量都可能变化。
// 贴底态必须始终由 auto-follow 接管;若先执行旧锚点恢复,会覆盖上方同一提交里的
// pinToBottom,把视口拉回本轮 user 消息。同步消费待重锚,避免用户稍后上滚时重放旧落点。
if (
consumePendingReanchorForAutoFollow({
isNearBottom: isNearBottomRef.current,
clearPendingReanchor: () => {
pendingReanchorScrollRef.current = null;
},
})
) {
return;
}
const snapshot = lastViewportTopRef.current;
const prevSeq = prevAllItems.length > 0 ? prevAllItems : prevVisibleItems;
const pending = pendingReanchorScrollRef.current;
if (pending) {
pendingReanchorScrollRef.current = null;
restoreViewportSnapshot(pending);
return;
}
const shrank = visibleRenderItems.length < prevVisibleItems.length;
const snapshotKeyGone =
snapshot !== null && !visibleRenderItems.some((it) => it.key === snapshot.viewportTopKey);
const snapshotMessageClientId = snapshot?.messageClientId;
const snapshotMessageGone =
snapshotMessageClientId !== undefined &&
!allRenderItems.some((item) => renderItemContainsClientId(item, snapshotMessageClientId));
if (!shrank && !snapshotKeyGone && !snapshotMessageGone) return;
const recoverableMessageClientId = snapshotMessageClientId;
const recoverableMessageExists =
recoverableMessageClientId !== undefined &&
allRenderItems.some((item) => renderItemContainsClientId(item, recoverableMessageClientId));
const recoveredIdx = snapshot
? findRestorableViewportItemIdx(visibleRenderItems, snapshot.viewportTopKey)
: -1;
const recoveredKey = recoveredIdx >= 0 ? visibleRenderItems[recoveredIdx]?.key : undefined;
const windowAnchorLost =
firstVisibleItemKey !== null &&
findRestorableViewportItemIdx(allRenderItems, firstVisibleItemKey) < 0;
if (snapshot && recoveredKey && !snapshotMessageGone) {
if (recoveredKey !== snapshot.viewportTopKey) {
const rebased: ViewportTopSnapshot = {
...snapshot,
viewportTopKey: recoveredKey,
// A prepended page can rename a surviving work group. Preserve its
// measured offset instead of treating it as a newly selected row.
offset: snapshot.offset,
...(recoverableMessageExists
? {
messageClientId: recoverableMessageClientId,
messageOffset: snapshot.messageOffset ?? snapshot.offset,
}
: {}),
};
lastViewportTopRef.current = rebased;
if (!windowAnchorLost && !programmaticScrollRef.current && !isLoadingMore) {
restoreViewportSnapshot(rebased);
}
}
if (!windowAnchorLost && !programmaticScrollRef.current && !isLoadingMore) return;
}
if (!sessionId) return;
if (programmaticScrollRef.current || isLoadingMore) {
prevVisibleItemsRef.current = prevVisibleItems;
prevAllItemsRef.current = prevAllItems;
if (programmaticScrollRef.current) deferredDeleteCompensationRef.current = true;
return;
}
let anchor = snapshot;
if (restoringRef.current) {
if (restoreLoadRef.current !== 'settled') return;
const snap = restoreSnapshotRef.current;
if (
!snap?.viewportTopKey ||
findRestorableViewportItemIdx(visibleRenderItems, snap.viewportTopKey) >= 0
) {
return;
}
anchor = { viewportTopKey: snap.viewportTopKey, offset: snap.offset };
restoringRef.current = false;
}
if (!anchor) return;
const { viewportTopKey: anchorKey, offset: anchorOffset } = anchor;
const anchorItemStillVisible = visibleRenderItems.some((item) => item.key === anchorKey);
if (anchor.messageClientId && snapshotMessageGone && anchorItemStillVisible) {
const survivorMessageId = pickDeleteCompensationAnchorKey(
collectDeleteAnchorClientIds(prevSeq),
collectDeleteAnchorClientIds(allRenderItems),
anchor.messageClientId,
);
if (survivorMessageId) {
const survivorItemKey = renderItemKeyForClientId(allRenderItems, survivorMessageId);
const root = scrollRef.current;
const exact = root ? queryMessageElement(root, survivorMessageId) : null;
const fallback = root ? queryVisibleAggregateContainer(root, survivorMessageId) : null;
const landing = resolveDeleteCompensationLanding({
exactVisible: isVisibleDeleteCompensationElement(exact),
fallbackContainerVisible: isVisibleDeleteCompensationElement(fallback),
});
if (landing === 'exact') {
const itemOffset = survivorItemKey === anchorKey ? anchorOffset : 0;
restoreViewportSnapshotOrRebuildWindow(
{
viewportTopKey: survivorItemKey ?? anchorKey,
offset: itemOffset,
messageClientId: survivorMessageId,
messageOffset: 0,
},
itemOffset,
);
return;
}
if (landing === 'container' && root && fallback) {
// 折叠摘要行可见,隐藏 child 没有精确 DOM。滚摘要到视口顶,不要复用外层旧 offset。
const delta = fallback.getBoundingClientRect().top - root.getBoundingClientRect().top;
if (Math.abs(delta) >= 1) {
const generation = beginProgrammaticScroll();
root.scrollTop += delta;
requestAnimationFrame(() => finishProgrammaticScroll(generation));
}
lastViewportTopRef.current = toRenderItemViewportSnapshot({
viewportTopKey: survivorItemKey ?? anchorKey,
offset: 0,
});
refreshViewportAnchor();
return;
}
restoreViewportSnapshotOrRebuildWindow(
{ viewportTopKey: survivorItemKey ?? anchorKey, offset: 0 },
0,
);
return;
}
}
if (anchorItemStillVisible) return;
if (windowAnchorLost) {
const aliveIdx = findRestorableViewportItemIdx(allRenderItems, anchorKey);
let targetKey: string | null;
let targetOffset = 0;
if (aliveIdx >= 0) {
targetKey = allRenderItems[aliveIdx]?.key ?? null;
if (targetKey === anchorKey) targetOffset = anchorOffset;
} else {
targetKey = pickDeleteCompensationAnchorKey(
prevSeq.map((it) => it.key),
allRenderItems.map((it) => it.key),
anchorKey,
);
}
if (!targetKey) return;
const targetSnapshot: ViewportTopSnapshot = snapshotMessageGone
? { viewportTopKey: targetKey, offset: targetOffset }
: {
...anchor,
viewportTopKey: targetKey,
offset: targetOffset,
...(recoverableMessageExists
? {
messageClientId: recoverableMessageClientId,
messageOffset: anchor.messageOffset ?? anchor.offset,
}
: {}),
};
lastViewportTopRef.current = targetSnapshot;
pendingReanchorScrollRef.current = targetSnapshot;
setFirstVisibleItemKey(targetKey);
return;
}
const survivorKey = pickDeleteCompensationAnchorKey(
prevVisibleItems.map((it) => it.key),
visibleRenderItems.map((it) => it.key),
anchorKey,
);
if (!survivorKey) return;
restoreViewportSnapshot({ viewportTopKey: survivorKey, offset: 0 });
}, [
visibleRenderItems,
allRenderItems,
firstVisibleItemKey,
sessionId,
isLoadingMore,
deleteCompensationReplay,
restoreViewportSnapshot,
restoreViewportSnapshotOrRebuildWindow,
beginProgrammaticScroll,
finishProgrammaticScroll,
refreshViewportAnchor,
]);
// ── post-load auto-expand ──
// 修一类已知 UX 缺口 (跟 render-window 轴换轴无关,老代码同病):
// 用户滚到顶 → handleScroll 触发 onLoadMore → DB prepend 进 messages →
// allRenderItems 增长但 visibleRenderItems 因为锚点 firstVisibleItemKey 不动
// 而内容不变 → DOM 高度也不变 → 用户停在 scrollTop=0,wheel up 不产生 scroll
// event → handleScroll 不再 fire → 新加载的更老 item 卡在内存里看不到。
//
// 触发器: isLoadingMore 从 true → false 的边沿 + windowAtTop=false (说明 load
// 确实带回了新内容,只是被锚点切在外面)。fire 一次 expandWindow,同时设
// prevScrollHeightRef 快照让上面 F-SYNC-2 effect 在 *下一个* commit (expand
// 的 state setter 触发的) 里读到 expand 前的高度算 delta 做 scroll 恢复 ——
// 用户原本看的内容仍在原 viewport 位置,新内容在它上方可被 wheel up 滚进去。
//
// 与 viewport-fill auto-fill effect 正交: 那条只在 scrollH===clientH 时 fire
// (防"完全不可滚"死锁),这里覆盖"可滚但新内容不在视野"的另一类。两者
// 同 commit 都 fire expand 是安全的 — expandWindow 幂等 (同一 firstVisibleItemKey
// 快照下计算的目标 anchor 相同, React 批处理后 net 等价单次)。
//
// 注册位置必须在 F-SYNC-2 之后: 同 commit 里 F-SYNC-2 先跑会清空
// prevScrollHeightRef (delta=0,因为 DOM 没变),我们再 set 新快照才能让下个
// commit 的 F-SYNC-2 算到 expand 引入的 delta。useEffect 同序按声明顺序触发。
const prevIsLoadingMoreRef = useRef<boolean>(false);
useEffect(() => {
const wasLoading = prevIsLoadingMoreRef.current;
const isNowDone = isLoadingMore === false;
prevIsLoadingMoreRef.current = isLoadingMore === true;
if (!wasLoading || !isNowDone) return;
if (windowAtTop) return; // load 实际没带新 item (DB 返空 / 已被同 commit 其它 expand 消化)
const el = scrollRef.current;
if (!el) return;
prevScrollHeightRef.current = el.scrollHeight;
prevScrollTopAtLoadRef.current = el.scrollTop;
expandWindow();
}, [isLoadingMore, windowAtTop, expandWindow]);
// F-SYNC-2 + F2: 跟随态的 scroll 事件侧迁移。
//
// 「解除跟随」的主路径在事件层(wheel / touch / 键盘意图 →
// unpinAutoFollowForUserUpIntent,见上),不在这里 — scroll 事件在流式期间
// 与 pinToBottom 高频竞态(小幅上滚永远越不过距离阈值就被钉回,且
// programmaticScrollRef 窗口会吞掉部分用户 scroll 事件),距离判定对
// 「上滚一行就停」不可靠。本 handler 只负责:
// - 离底 >= threshold 且明确上滚 → 解除(滚动条拖拽等无 wheel 路径的兜底);
// 已在跟时内容在下方长高不得解除,否则发送后第一块新内容会把跟随掐死;
// - 已解除 + 明确向下滚回阈值带内 → 恢复跟随。
// 迁移规则收敛在 resolveNearBottomOnScroll(纯函数,见 autoFollowIntent.ts)。
// `isNearBottomRef`(auto-follow gate)与 `isNearBottom` state(指示器显隐)
// 仍在同一分支同步更新,不允许失步。
//
// Programmatic scrolls (pinToBottom / scrollToBottomSmooth / load-more
// restore) bypass all state updates — they are our own writes and must not
// be read back as user intent. `prevScrollTopRef` is kept only for the
// load-more prepend restore path further down.
const handleScroll = useCallback(() => {
const el = scrollRef.current;
if (!el) return;
const currentScrollTop = el.scrollTop;
const distanceFromBottom = el.scrollHeight - currentScrollTop - el.clientHeight;
const threshold = 100;
const draggingScrollbar = scrollbarDragStartTopRef.current != null;
if (restoringRef.current && !draggingScrollbar) {
applyRestoreRef.current();
prevScrollTopRef.current = el.scrollTop;
return;
}
const draggingUp =
draggingScrollbar &&
currentScrollTop < prevScrollTopRef.current - SCROLL_DIRECTION_DEAD_ZONE_PX;
if (!programmaticScrollRef.current || draggingScrollbar) {
// 用户手动滚动 = 接管浏览,退出「还原中」,后续恢复正常 auto-follow 判定。
restoringRef.current = false;
// 持续保存浏览位置(rAF 节流,DOM 必然存活),内含删除前快照刷新——纯滚动后
// 快照停在陈旧 key 会让删除补偿失配。
if (isLoadingMore || prevScrollHeightRef.current > 0) {
// A remote response can commit before the next rAF. Keep its restoration
// anchor at the user's latest position throughout the request.
if (saveRafRef.current !== null) cancelAnimationFrame(saveRafRef.current);
saveRafRef.current = null;
saveScrollSnapshot();
} else if (saveRafRef.current === null) {
saveRafRef.current = requestAnimationFrame(() => {
saveRafRef.current = null;
saveScrollSnapshot();
});
}
// 方向增量 — 比较当前 scrollTop 与 prevScrollTopRef(在本函数末尾才会被
// 覆盖,这里读的还是上一次值)。跟随态迁移与 jump-down chip 共用。
// programmatic scroll 不进本分支 — auto-follow 自己滚不该参与判定。
const delta = currentScrollTop - prevScrollTopRef.current;
// 滚动条上拖:前 100px 内 resolveNearBottomOnScroll 会保持跟随。流式 pin
// 下一帧又钉回,必须在这里按拖拽上移立即解除。
if (
shouldUnpinOnScrollbarDrag({
pointerDown: draggingScrollbar,
scrollDelta: delta,
directionDeadZonePx: SCROLL_DIRECTION_DEAD_ZONE_PX,
}) &&
shouldUnpinOnUpIntent({ scrollHeight: el.scrollHeight, clientHeight: el.clientHeight })
) {
unpinAutoFollowForUserUpIntent();
}
// F2: 跟随态迁移(规则见 resolveNearBottomOnScroll 注释)。恢复跟随要求
// 明确向下滚 — 意图解除(wheel 上滚)后紧跟着的上滚 scroll 事件距底仍
// < threshold,只看距离会把刚解除的跟随立刻翻回去。
// ref (auto-follow) 与 state (按钮显隐) 在同一分支同步,永不失步。
// unreadCount 仅在"从非底 → 底"的翻转瞬间清零,避免已累计未读被吞。
const nowNearBottom = resolveNearBottomOnScroll({
wasNearBottom: isNearBottomRef.current,
distanceFromBottom,
scrollDelta: delta,
thresholdPx: threshold,
directionDeadZonePx: SCROLL_DIRECTION_DEAD_ZONE_PX,
});
// 历史切片滚到自己的底 ≠ 会话末尾,不能从这里开始跟随。已经在跟
// (本端发送 / 跳底)时,窗口还没切回尾窗的迟到 scroll 不得把跟随掐死。
const effectiveNearBottom = resolveEffectiveNearBottom({
windowCoversEnd,
nowNearBottom,
wasNearBottom: isNearBottomRef.current,
});
if (
shouldBumpSendFollowCancelOnScroll({
wasNearBottom: isNearBottomRef.current,
effectiveNearBottom,
scrollDelta: delta,
directionDeadZonePx: SCROLL_DIRECTION_DEAD_ZONE_PX,
})
) {
bumpSendFollowCancelGeneration(sessionId);
}
if (effectiveNearBottom !== isNearBottomRef.current) {
isNearBottomRef.current = effectiveNearBottom;
setIsNearBottom(effectiveNearBottom);
if (effectiveNearBottom) {
setUnreadKeys(NO_UNREAD_KEYS);
// Only shrink history when the reader resumes following the tail.
// Ctrl+F / Ctrl+A mount offscreen text and change scroll geometry at
// an already-followed tail; those scroll events must preserve the
// existing logical window, otherwise find/selection loses its text.
if (firstVisibleItemKey !== null && windowCoversEnd) {
setFirstVisibleItemKey(null);
}
}
}
if (effectiveNearBottom) {
// 到底了:无论方向都隐藏 chip,清掉 timer
if (jumpDownIdleTimerRef.current !== null) {
window.clearTimeout(jumpDownIdleTimerRef.current);
jumpDownIdleTimerRef.current = null;
}
setShowJumpDown((cur) => (cur ? false : cur));
} else if (delta > SCROLL_DIRECTION_DEAD_ZONE_PX) {
// 向下滚 + 未到底:显示 chip,reset idle timer
setShowJumpDown((cur) => (cur ? cur : true));
if (jumpDownIdleTimerRef.current !== null) {
window.clearTimeout(jumpDownIdleTimerRef.current);
}
jumpDownIdleTimerRef.current = window.setTimeout(() => {
jumpDownIdleTimerRef.current = null;
setShowJumpDown(false);
}, JUMP_DOWN_IDLE_MS);
} else if (delta < -SCROLL_DIRECTION_DEAD_ZONE_PX) {
// 向上滚:立即隐藏 chip(用户改变方向了,跳底意图消失)
if (jumpDownIdleTimerRef.current !== null) {
window.clearTimeout(jumpDownIdleTimerRef.current);
jumpDownIdleTimerRef.current = null;
}
setShowJumpDown((cur) => (cur ? false : cur));
}
// render-window-bidirectional 要点 5: 向下扩窗。
// 用户向下滚动接近当前窗口下缘时,扩 anchoredForwardItems 纳入更多 item。
// 向下 append 不改变已有内容的滚动偏移,不需要 F-SYNC-2 delta 补偿。
// 扩到覆盖末尾后直接清除锚点,回到默认贴底窗口。
if (
!windowCoversEnd &&
delta > SCROLL_DIRECTION_DEAD_ZONE_PX &&
distanceFromBottom < threshold
) {
const nextForward = anchoredForwardItems + RENDER_WINDOW_GROWTH_ITEMS;
// 最后一批照常渲染:不在此处清除锚点。用户真正滚到窗口底部后,
// 上面 effectiveNearBottom + windowCoversEnd 分支会自然清除锚点、
// 切回默认尾窗并恢复 near-bottom 状态。
setAnchoredForwardItems(nextForward);
}
}
prevScrollTopRef.current = currentScrollTop;
// F3: smooth 滚动完成后清除 programmaticScrollRef,让后续用户滚动能被正确识别。
// - 判据:距底 < 5px(smooth 动画收敛后的稳定值)+ 当前处于 programmatic 态
// - 用 rAF 推迟一帧,避免连续 smooth 滚动的尾帧事件被误判
// 同帧刷新删除前快照:程序化贴底后视口顶端已变,陈旧 key 会让删除补偿早退。
if (
programmaticScrollRef.current &&
focusJumpRef.current === null &&
chipJumpGenerationRef.current === null &&
distanceFromBottom < 5
) {
const generation = programmaticScrollGenerationRef.current;
requestAnimationFrame(() => {
if (finishProgrammaticScroll(generation) === false) refreshViewportAnchor();
});
}
// Scrollbar drags share explicit-input prefetch, without also expanding below.
if (draggingUp) {
triggerUserIntentFill();
return;
}
// 滚到顶 50px 内才触发后续加载逻辑(阈值与 decideUserIntentFillAction 的
// "停在顶部"判定共用 TOP_HISTORY_TRIGGER_PX,两条路径合起来覆盖
// "穿过顶部区间"与"停在顶部继续上滚"的完整触发面)
if (el.scrollTop >= TOP_HISTORY_TRIGGER_PX) return;
// chip / 搜索 focus 期间抑制 — 定位是导航语义不是"想加载更多",而且 smooth
// 路径穿过顶部时叠加 F-SYNC-2 的 scrollTop+=delta 可能把 viewport 拽飞
// (长距离跳转踹回底嫌疑)。用户主动 wheel/touch/keydown 会立刻清掉这个 ref
// (见 mount effect 里的监听),所以"跳完立刻继续往上翻"完全 OK。
if (chipJumpInProgressRef.current || focusJumpRef.current !== null) {
return;
}
// 二段式加载:
// 1. 内存里还有比当前窗口更早的消息 → 客户端扩窗(无 IPC,即时)
// 2. 窗口已经覆盖到内存最早的消息,且 DB 还有更老历史 → 走 onLoadMore 拉 DB
// prevScrollHeightRef 给 F-SYNC-2 + render-window 的统一 scroll 恢复用。
if (!windowAtTop) {
prevScrollHeightRef.current = el.scrollHeight;
prevScrollTopAtLoadRef.current = el.scrollTop;
expandWindow();
return;
}
if (!onLoadMore || isLoadingMore || !hasMoreMessages) return;
prevScrollHeightRef.current = el.scrollHeight;
prevScrollTopAtLoadRef.current = el.scrollTop;
onLoadMore();
}, [
onLoadMore,
isLoadingMore,
hasMoreMessages,
windowAtTop,
expandWindow,
saveScrollSnapshot,
triggerUserIntentFill,
refreshViewportAnchor,
finishProgrammaticScroll,
windowCoversEnd,
anchoredForwardItems,
visibleStartIdx,
allRenderItems.length,
setFirstVisibleItemKey,
setAnchoredForwardItems,
sessionId,
unpinAutoFollowForUserUpIntent,
]);
// 渲染窗口下移到 render-item 轴后,U2 "末尾窗口全是 orphan tool_result"
// 死锁不可能复现:`buildRenderItems(messages)` 喂全量 → orphan / ask_user /
// AskUserQuestion / ExitPlanMode 在 Pass 2 就被丢弃,绝不会出现在
// `allRenderItems` 末尾。`visibleRenderItems = slice(-INITIAL_ITEMS)` 必然
// 落在有效 item 上,自愈 effect 失去存在意义,随之删除(原 effect:
// "renderItems 全空 → 自动扩窗",见 commit 05cafaa7)。
// `allRenderItems` / `singleResultMap` 已在文件上方 useMemo 中声明并参与
// visibleRenderItems / 窗口数学,这里无须再 build 一次。
// ── prev-user-msg-jump ──
// 滚动时右侧浮一个"↑ 上一条提问" pill,点击跳到对应 user 消息的顶端。
// userMessageIds 从 visibleRenderItems 派生 — 保证 Chip 目标永远在 DOM 里,
// scrollIntoView 直接可用,无需扩窗。user 消息总是单独 message item(不进
// segment / 不被丢弃),所以这里只 unwrap type==='message' && role==='user'。
// previewById 同源,截断/去噪都在 PrevMessageJumpChip 的 truncatePreview 里做。
// 预览存显示文本而非原始 content:chip 是导航条缺席/截断时的兜底入口,其
// title/aria 与刻度预览承担同一职责,hook 消息的隐藏 prompt/<thread_context>
// 与 Orca 行的 JSON 原文同样不能裸奔(userMessageDisplayText,PR #830 review)。
const { userMessageIds, previewById } = useMemo(() => {
const ids: string[] = [];
const map = new Map<string, string>();
for (const it of visibleMetadataItems) {
if (it.type !== 'message' || it.message.role !== 'user') continue;
// 合成指令行渲染 null,没有对应 DOM 元素,chip 指向它 scrollIntoView 会
// 静默失效(review P2)。
if (it.message.isSyntheticTrigger) continue;
ids.push(it.message.clientId);
map.set(it.message.clientId, resolveUserDisplayText(it.message));
}
return { userMessageIds: ids, previewById: map };
}, [visibleMetadataItems]);
const { displayId: prevUserMsgId, suppressAfterClick } = usePrevUserMessageInView({
scrollRef,
userMessageIds,
resetKey: sessionId,
});
const handleJumpToPrevUserMsg = useCallback(() => {
const root = scrollRef.current;
if (!root || !prevUserMsgId) return;
const el = root.querySelector(
`[data-user-msg-id="${CSS.escape(prevUserMsgId)}"]`,
) as HTMLElement | null;
if (!el) return;
// portal 不在 scroll root 内,mousedown 接管监听收不到;必须在新 smooth 开始前
// 显式废弃旧 focus,避免其 scrollend 把视口拉回搜索结果。
cancelFocusJump({ consumeDeferredDelete: true });
suppressAfterClick();
// expand/load 抑制:smooth scroll 期间路径如果穿过 scrollTop<50,handleScroll
// 会触发 expandWindow/onLoadMore + F-SYNC-2 scrollTop+=delta,这条 race 可能
// 把 viewport 拽飞。设 ref 让 handleScroll 跳过那分支。解抑靠 wheel/touch/
// keydown(在上面 useEffect 里挂的监听),用户一动手就过去,不会卡"用 chip
// 连点上翻"或"跳完立刻 wheel 看更老历史"。
beginChipJump({
clientId: prevUserMsgId,
selector: 'user-message',
topOffset: 0,
});
el.scrollIntoView({ behavior: 'smooth', block: 'start' });
}, [prevUserMsgId, suppressAfterClick, beginChipJump, cancelFocusJump]);
const prevPreview = prevUserMsgId ? firstNonEmptyLine(previewById.get(prevUserMsgId) ?? '') : '';
// chip 是否需要在右上角栈里出场。栈容器(TopRightChipStack)接管定位,
// 所以不再需要旧的"通知父级 DiffToggle 让位"那套互斥 —— DiffToggle 与
// chip 在栈里各占一行,自然共存。
const prevUserMsgVisible = prevUserMsgId !== null;
// ── message-nav-rail ──
// 左缘"提问导航条":条目覆盖**全量已加载** messages(不同于 chip 的窗口内
// 派生 —— 导航条要给整段历史画刻度)。目标可能在渲染窗口外,跳转走下面的
// layout effect:复用 focus-jump 的"先扩窗到目标、下一轮再滚动"两段式,
// 以及 chip-jump 的 expandWindow/onLoadMore 抑制协议。
// 导航条是普通任务的个性化可选功能(Settings → 个性化 → 小技巧)。
// 伙伴长期对话不显示逐条刻度,也不为导航条派生条目或空闲补页。关闭时
// 不挂载组件(卸载时组件自会把 navRailCoversNav 报回 false,chip 兜底回归),
// 也不做下面的空闲补页。
const { enabled: navRailPreferenceEnabled } = useMessageNavRailPreference();
const navRailEnabled = navRailPreferenceEnabled && !simplifiedBotConversation;
const navRailEntries = useMemo(
() => navigationProjection(visibleMessages, navRailEnabled),
[navigationProjection, visibleMessages, navRailEnabled],
);
// 入口去重:导航条**完整覆盖导航**(出场且刻度未截断)时抑制"跳到上一条
// 提问"chip —— 同一个导航任务只保留一套入口。导航条缺席(短对话 / 窄窗 /
// 矮视口)或截断了更早刻度的超长会话里 chip 回归兜底(PR #830 review)。
const [navRailCoversNav, setNavRailCoversNav] = useState(false);
// ── nav-rail 空闲补页 ──
// 老会话打开时只加载尾部切片,导航条(整段对话的地图)可能凑不齐条目。
// 首屏落定后的空闲期沿现有 onLoadMore 通道自动向前补页,直到提问数达标 /
// 翻到历史起点 / 轮数预算用完(目标与预算的设计依据见
// shouldBackfillForNavRail 一族常量注释)。与"跳转补齐"同属程序化翻页,
// prepend 的滚动补偿照走 F-SYNC-2 协议:调用前快照 scrollHeight/scrollTop。
// 即使当下窗口太窄导航条没出场,补到的历史对搜索/上滚阅读同样有用,
// 且有轮数预算封顶,不做 eligible 门控。但伙伴对话或用户显式关闭导航条
// 时跳过:为一个不存在的 UI 自动翻页不符合默认克制,开关
// 打开后本 effect 依赖变化会重新评估补页。
// 调度 effect 的依赖含 sessionId(与 MessageNavRail 的 resetKey 同款惯例):
// 两个会话的条目数 / hasMore 恰好相同且 onLoadMore 身份未变时,切会话也要
// 取消旧会话待发的空闲回调。轮数预算只在 mount 时按会话记忆恢复一次;
// 不能在 passive effect 再读,否则同一 mount 的 viewport-fill 先 mark 后会
// 提前封死导航条自己的本轮预算。
useEffect(() => {
if (!navRailEnabled) return;
if (!onLoadMore) return;
if (
!shouldBackfillForNavRail({
entryCount: navRailEntries.length,
hasMoreMessages: hasMoreMessages ?? false,
isLoadingMore: isLoadingMore ?? false,
rounds: navRailBackfillRoundsRef.current,
})
) {
return;
}
const run = () => {
const el = scrollRef.current;
if (!el) return;
navRailBackfillRoundsRef.current += 1;
prevScrollHeightRef.current = el.scrollHeight;
prevScrollTopAtLoadRef.current = el.scrollTop;
void runAutomaticLoad(onLoadMore);
};
// 空闲期执行,别跟首屏渲染 / 两段式扩窗抢主线程;测试等无 ric 环境退化。
if (typeof window.requestIdleCallback === 'function') {
const id = window.requestIdleCallback(run, { timeout: 2000 });
return () => window.cancelIdleCallback(id);
}
const id = window.setTimeout(run, 300);
return () => window.clearTimeout(id);
}, [
sessionId,
navRailEnabled,
navRailEntries.length,
hasMoreMessages,
isLoadingMore,
onLoadMore,
runAutomaticLoad,
]);
const railJumpSeqRef = useRef(0);
const [railJumpRequest, setRailJumpRequest] = useState<{ id: string; seq: number } | null>(null);
const lastAppliedRailJumpRef = useRef(0);
const handleNavRailJump = useCallback(
(clientId: string) => {
// 先废弃旧搜索 focus;目标即使需要下一轮扩窗,旧 scrollend/timer 也不能抢回视口。
// 导航条目标要到 layout effect 才能确认仍存在且 DOM 已就绪,因此这里不能提前消费
// focus 期间延期的删除补偿:先重放补偿,目标有效时后续导航再覆盖最终落点。
cancelFocusJump();
// 点击本身就是离开尾部的明确意图,必须在 request 进入下一次 render 前同步写入。
// 否则同一批流式 append 的 coverage-loss layout effect 会先按旧跟随态清掉锚点,
// 当前窗口内、但默认尾窗外的目标会在后续 rail effect 滚动时被卸载。
restoringRef.current = false;
isNearBottomRef.current = false;
setIsNearBottom(false);
railJumpSeqRef.current += 1;
setRailJumpRequest({ id: clientId, seq: railJumpSeqRef.current });
},
[cancelFocusJump],
);
useLayoutEffect(() => {
if (!railJumpRequest) return;
if (lastAppliedRailJumpRef.current === railJumpRequest.seq) return;
const targetKey = renderItemKeyForClientId(allRenderItems, railJumpRequest.id);
if (!targetKey) {
// 条目派生自 messages,拿不到 key 只可能是消息刚被删 / clear — 放弃本次。
lastAppliedRailJumpRef.current = railJumpRequest.seq;
return;
}
if (!visibleRenderItems.some((item) => item.key === targetKey)) {
// 目标在渲染窗口外:先把窗口锚到目标。本 effect 因 visibleRenderItems
// 变化重跑,下一轮走下面的滚动分支(focus-jump 同款两段式)。
setFirstVisibleItemKey(targetKey);
setAnchoredForwardItems(RENDER_WINDOW_FIRST_PAINT_ITEMS);
return;
}
const root = scrollRef.current;
if (!root) return;
const el = root.querySelector(
`[data-message-client-id="${CSS.escape(railJumpRequest.id)}"]`,
) as HTMLElement | null;
if (!el) return;
lastAppliedRailJumpRef.current = railJumpRequest.seq;
// auto-follow 已由点击处理器在 request 进入 render 前解除,避免本轮更早的
// coverage-loss effect 清掉当前窗口内、默认尾窗外的导航目标。
// smooth scroll 途经顶部区域时抑制 expandWindow/onLoadMore(chip-jump 协议,
// 解抑靠用户 wheel/touch/keydown + 安全兜底 timer)。
beginChipJump({
clientId: railJumpRequest.id,
selector: 'message',
topOffset: NAV_RAIL_JUMP_TOP_OFFSET_PX,
});
// 落点手动计算,不走 scrollIntoView:轮次跳转要让视口恰好框住
// "提问 → 回答",提问顶边停在容器顶下方 12px;消息锚点通用的
// scroll-mt-20(80px)是搜索跳转的上文语境预留,对本任务是漏出
// 上一轮尾巴的噪音(设计依据见 NAV_RAIL_JUMP_TOP_OFFSET_PX 注释)。
const targetTop =
root.scrollTop +
(el.getBoundingClientRect().top - root.getBoundingClientRect().top) -
NAV_RAIL_JUMP_TOP_OFFSET_PX;
root.scrollTo({ top: Math.max(0, targetTop), behavior: 'smooth' });
}, [railJumpRequest, allRenderItems, visibleRenderItems, beginChipJump]);
// 第一条 user 消息没有可 fork 的前文(fork 出来等价于复制整条任务),UI 层藏掉 fork 入口。
// 注意:这里要用全量 messages 而不是 visibleRenderItems —— "首条 user" 的语义
// 是整段对话的首条,不是当前窗口的首条;且 messages 本身也只是已加载的尾部
// 切片,还有老页未加载(hasMoreMessages)时不能把切片首条误判为对话首条
// (判定逻辑与陷阱见 findFirstUserMessageClientId 注释)。
const firstUserMessageClientId = useMemo(
() => findFirstUserMessageClientId(metadataMessages, Boolean(hasMoreMessages)),
[metadataMessages, hasMoreMessages],
);
// edit-last-message: 最后一条 user 消息才显示编辑入口(编辑 = rewind 到该条
// + 重发,更早的消息会连带丢弃后续轮次,v1 不开放)。与 first 同理用全量
// messages 判定,不受窗口分页影响。
// 走 visibleMessages:子代理内部的 user 行渲染不出来,让它成为"最后一条 user"
// 会把编辑入口从真实的最后一条可见气泡上抢走 —— 与该 helper 里 isSyntheticTrigger
// 那条同源(review: codex P2)。
const lastUserMessageClientId = useMemo(
() => findLastUserMessageClientId(visibleMetadataMessages),
[visibleMetadataMessages],
);
// 含合成行的"最后一条用户侧输入":自愈重连行据此判断自己是不是仍在飞(见 helper 注释)。
// 同样走可见序列:子代理内部的 user 行不是父会话某个 turn 的发起者,算进来会让
// 在飞的重连行被"夺走归属"、提前停转。
const lastUserInputClientId = useMemo(
() => findLastUserInputClientId(visibleMetadataMessages),
[visibleMetadataMessages],
);
// 使用未过滤子代理的 displayMessages,不走 visibleMessages:子代理消耗的 token 是这个 turn 的
// 真实花费,过滤掉等于把子代理的账从用量里抹掉(成本失真,比显示问题更糟)。
// 归属键 turnFinalAssistantClientIds 已按可见序列算出,聚合区间仍落在正确的 turn 内。
const userTurnUsageDetailsByAssistantId = useMemo(() => {
return collectAssistantTurnUsageDetails(metadataMessages, turnFinalAssistantClientIds);
}, [metadataMessages, turnFinalAssistantClientIds]);
// error-tail-banner:尾部未忽略的 error 行由输入框上方红条独家承载,流内需要
// 知道"是不是最后一条"来跳过重复渲染。走可见序列:尾部挂着子代理内部行时,
// 真实的最后一条可见 error 会因为"不是最后一条"而在流内重复渲染一遍。
const lastMessageClientId =
visibleMessages.length > 0 ? visibleMessages[visibleMessages.length - 1].clientId : undefined;
const previousLocalFileRefsRef = useRef<readonly KnownLocalFileRef[]>([]);
const localFileRefs = useMemo<readonly KnownLocalFileRef[]>(() => {
return collectStableLocalFileRefs(rawMetadataMessages, previousLocalFileRefsRef.current);
}, [rawMetadataMessages]);
useEffect(() => {
previousLocalFileRefsRef.current = localFileRefs;
}, [localFileRefs]);
// 伙伴聊天的工作过程与回复正文同列:只占头像宽度,不重复画脸。memo 住以保持
// WorkGroupRenderItemView 的 memo 比较成立。
const botReplyColumnSpacer = useMemo(
() =>
simplifiedBotConversation && assistantAvatar ? (
<span aria-hidden="true" className="invisible">
{assistantAvatar}
</span>
) : undefined,
[assistantAvatar, simplifiedBotConversation],
);
const workGroupRenderContext = useMemo<WorkGroupRenderContext>(
() => ({
workingDir,
sessionId,
sessionTitle,
agentKind,
remoteHostId,
sessionSource,
onDiagnoseError,
isSessionStreaming,
firstUserMessageClientId,
lastUserMessageClientId,
lastUserInputClientId,
continuationTurnClientId,
continuationInFlightProjectionCapability,
localFileRefs,
singleResultMap,
assistantsWithFollowingUserBoundary,
turnFinalAssistantClientIds,
subagentModelByToolUseId,
userTurnUsageDetailsByAssistantId,
}),
[
workingDir,
sessionId,
sessionTitle,
agentKind,
remoteHostId,
sessionSource,
onDiagnoseError,
isSessionStreaming,
firstUserMessageClientId,
lastUserMessageClientId,
lastUserInputClientId,
continuationTurnClientId,
continuationInFlightProjectionCapability,
localFileRefs,
singleResultMap,
assistantsWithFollowingUserBoundary,
turnFinalAssistantClientIds,
subagentModelByToolUseId,
userTurnUsageDetailsByAssistantId,
],
);
// chip 垂直位置:优先使用父层实测的底部中央避让边界。普通状态行不占中央槽,
// 步骤 / 接管胶囊在场时则把按钮抬到它们上方;旧调用方保留历史兜底。
const resolvedBottomPadding = bottomPadding ?? 200;
const indicatorBottomOffset = resolveMessageStreamIndicatorBottomOffset({
bottomPadding,
bottomCenterClearanceOffset,
});
const latestInlinePlanRendered = Boolean(
latestInlinePlanKey && visibleRenderItems.some((item) => item.key === latestInlinePlanKey),
);
useLayoutEffect(() => {
if (!onInlinePlanVisibilityChange) return;
if (!latestInlinePlanKey) {
onInlinePlanVisibilityChange(null);
return;
}
const root = scrollRef.current;
const card = root
? [...root.querySelectorAll<HTMLElement>('[data-inline-plan-key]')].find(
(candidate) => candidate.dataset.inlinePlanKey === latestInlinePlanKey,
)
: undefined;
if (!root || !card || !latestInlinePlanRendered) {
onInlinePlanVisibilityChange({ key: latestInlinePlanKey, visible: false });
return;
}
const bottomInset = Math.min(
Math.max(0, resolvedBottomPadding),
Math.max(0, root.clientHeight - 1),
);
const reportMeasuredVisibility = () => {
onInlinePlanVisibilityChange({
key: latestInlinePlanKey,
visible: isPlanCardVisibleInViewport(
card.getBoundingClientRect(),
root.getBoundingClientRect(),
bottomInset,
),
});
};
// 首次结果在 paint 前同步给父层,计划刚出现时不会先闪一次悬浮胶囊。
reportMeasuredVisibility();
if (typeof IntersectionObserver !== 'undefined') {
const observer = new IntersectionObserver(reportMeasuredVisibility, {
root,
rootMargin: `0px 0px -${bottomInset}px 0px`,
threshold: 0,
});
observer.observe(card);
return () => observer.disconnect();
}
// Electron 正常支持 IntersectionObserver;测试壳或极老 runtime 缺失时用
// 轻量 scroll/resize 兜底,不能因为能力缺失让胶囊永久不出现。
root.addEventListener('scroll', reportMeasuredVisibility, { passive: true });
window.addEventListener('resize', reportMeasuredVisibility);
const resizeObserver =
typeof ResizeObserver !== 'undefined' ? new ResizeObserver(reportMeasuredVisibility) : null;
resizeObserver?.observe(root);
resizeObserver?.observe(card);
return () => {
root.removeEventListener('scroll', reportMeasuredVisibility);
window.removeEventListener('resize', reportMeasuredVisibility);
resizeObserver?.disconnect();
};
}, [
latestInlinePlanKey,
latestInlinePlanRendered,
onInlinePlanVisibilityChange,
resolvedBottomPadding,
]);
// 「提及 → 兑现」关联(方案 2):从会话历史现算,软提示卡据此升级为召唤卡。
// 引用缓存:内容不变时复用上一个 Map 引用——UserMessage 顶层订阅该
// context,流式期间 messages 每批 delta 都换引用,不缓存会让全部历史
// 消息每批 token 重渲一遍(ghostCallMapsEqual 注释有完整推导)。
// 走可见序列:归属键是**可见的**那条 user 消息(软提示卡挂在它上面),被隐藏的
// 子代理 user 行不该成为归属键,否则该 turn 的召唤卡升级不到任何可见气泡上。
const ghostCallsByUserTurnRaw = useMemo(
() => collectGhostCallsByUserTurn(visibleMetadataMessages),
[visibleMetadataMessages],
);
const ghostCallsCacheRef = useRef(ghostCallsByUserTurnRaw);
if (!ghostCallMapsEqual(ghostCallsCacheRef.current, ghostCallsByUserTurnRaw)) {
ghostCallsCacheRef.current = ghostCallsByUserTurnRaw;
}
const ghostCallsByUserTurn = ghostCallsCacheRef.current;
return (
<ChatSessionFileProvider value={sessionFileValue}>
<GhostFulfillmentContext.Provider value={ghostCallsByUserTurn}>
<ImageGalleryContext.Provider value={sessionImageSrcs}>
<div className="relative h-full w-full">
{/* chat-text-quote:选中消息文字 → 浮出"添加到对话"按钮(portal 到 body)。
绑定本流的滚动容器:协同模式多流并存时,选区归属按各自容器判定。 */}
{sessionId ? (
<SelectionQuoteButton sessionId={sessionId} containerRef={scrollRef} onAskInSideChat={onAskInSideChat} />
) : null}
{/*
原生滚动容器:overflow-y-auto + overflow-x-hidden。
- 滚动条样式由 globals.css 的 ::-webkit-scrollbar + .is-scrolling 规则统一接管,
默认 thumb 透明,scroll/hover gutter 时显形,2s 无活动后淡出
(lib/scrollbarAutoHide.ts 全局 capture 阶段自动加类)。
- data-scroll-container 给 ImageLightbox/TextLightbox/MermaidLightbox/
ToolPayloadLightbox 的全局 querySelector('[data-scroll-container]') 找锚点。
- 50px 视觉边距由 contentRef 的 mx-auto + maxWidth 自然产生。
*/}
<div
ref={scrollRef}
data-scroll-container=""
className="h-full w-full overflow-y-auto overflow-x-hidden [scrollbar-gutter:stable]"
onScroll={handleScroll}
onPointerDownCapture={() => refreshViewportAnchor()}
onKeyDownCapture={() => refreshViewportAnchor()}
>
<div
ref={contentRef}
className="relative mx-auto w-full pt-7"
style={{
paddingBottom: resolvedBottomPadding,
// Match the input overlay's width so chat content + input box
// share the same horizontal bounds. Falls back to 880 only if
// the parent forgot to pass contentWidth.
maxWidth: contentWidth ?? 880,
}}
>
{header ? <div className="mb-3.5">{header}</div> : null}
{historyLoaded && historyCleared && <HistoryClearedMarker />}
{/* Keep pagination feedback inside the existing top padding so
toggling it never changes message positions or scrollHeight. */}
{isLoadingMore && (
<div className="pointer-events-none absolute inset-x-0 top-1 flex items-center justify-center">
<Spinner size={20} className="text-[var(--msg-tool-text)]" />
</div>
)}
{/* F10 (v2): vertical gap halved 28→14px so thinking + tool blocks
read more compactly, matching Claude Code Desktop density.
React `key` 一律取 item.key — stable across builds(派生约定见
RenderItem 类型注释 / buildRenderItems),复用 DOM 节点避免折叠
态丢失 / 滚动锚点漂走。 */}
<MessageViewport apiRef={messageViewportRef} options={{
entries: viewportEntries, scrollRef, itemsRef, followRef: isNearBottomRef,
initialAnchor: restoreSnapshotRef.current?.viewportTopKey,
initialHeights: restoreSnapshotRef.current?.itemHeights?.byKey,
disabled: shareSelectionActive,
// Refresh ownership before virtualization mutates the DOM.
onProgrammaticScroll: () => handleScroll(),
}}>{messageViewport => <div
ref={itemsRef}
data-share-selection-active={shareSelectionActive ? '' : undefined}
className={cn(
// #5406: normal layout avoids the row display-locking condition
// reproduced in Blink AX text-fragment serialization.
// Historical bodies mount near the viewport; keyed height
// placeholders preserve the existing scroll/restore geometry.
'msg-stream-items flex flex-col gap-3.5',
// 分享选择模式:整列内容右移,左侧让出复选框那一列。缩进加在
// 容器上(不是逐条消息),工具卡等不可选的 item 也跟着移,
// 左边缘保持对齐。
shareSelectionActive && 'pl-10',
'transition-[padding] duration-[var(--motion-base)] ease-[var(--motion-ease-move)] motion-reduce:transition-none',
)}
>
{visibleRenderItems.map((item, itemIndex) => {
if (!messageViewport.shouldMount(viewportEntries[itemIndex])) {
return <div key={item.key} data-render-item-key={item.key}
data-message-client-id={item.type === 'message' ? item.message.clientId : undefined}
// Previous-question navigation must still find offscreen user rows.
data-user-msg-id={item.type === 'message' && item.message.role === 'user'
&& !item.message.isSyntheticTrigger ? item.message.clientId : undefined}
data-message-placeholder="" aria-hidden="true"
style={{ height: messageViewport.placeholderHeight(item.key), flexShrink: 0 }} />;
}
if (item.type === 'fork_origin') {
return (
<ForkOriginMarker
renderItemKey={item.key}
key={item.key}
onClick={onOpenForkOrigin}
/>
);
}
if (item.type === 'agent_plan') {
return (
<div
key={item.key}
data-render-item-key={item.key}
data-inline-plan-key={item.key}
>
<InlinePlanCard
todos={item.todos}
animated={
isSessionStreaming &&
latestInlinePlanBelongsToActiveTurn &&
item.key === latestInlinePlanKey
}
/>
</div>
);
}
if (item.type === 'turn_changes') {
if (!sessionId) return null;
return (
<TurnChangesCard
key={item.key}
renderItemKey={item.key}
sessionId={sessionId}
changeSet={item.changeSet}
/>
);
}
if (item.type === 'generated_files') {
return (
<GeneratedFilesCard
key={item.key}
renderItemKey={item.key}
files={item.files}
turnStartMs={item.turnStartMs}
turnEndMs={item.turnEndMs}
turnSealed={item.turnSealed === true}
botArtifacts={simplifiedBotConversation}
onVisibilityChange={
simplifiedBotConversation ? onGeneratedFilesVisibilityChange : undefined
}
/>
);
}
if (item.type === 'tool_segment') {
return (
<AgentActionsBlock
key={item.key}
renderItemKey={item.key}
toolCalls={item.toolCalls}
resultMap={item.resultMap}
settledIds={item.settledIds}
isSessionStreaming={isSessionStreaming}
/>
);
}
if (item.type === 'agent_task') {
return (
<AgentTaskCard
key={item.key}
renderItemKey={item.key}
toolCall={item.toolCall}
update={item.update}
result={item.result}
persistedStatus={item.persistedStatus}
durableStatus={item.durableStatus}
sessionAgentKind={agentKind}
{...(sessionId ? { sessionId } : {})}
subagentModel={
item.toolCall?.toolUseId
? subagentModelByToolUseId.get(item.toolCall.toolUseId)
: undefined
}
/>
);
}
if (item.type === 'work_group') {
return (
<WorkGroupRenderItemView
key={item.key}
item={item}
context={workGroupRenderContext}
// 伙伴聊天与普通任务同一套工作过程:运行中露最近 5 条活动与计时,
// 组头按内容宽;最终答复后保留折叠过程,按需展开。
compact={false}
replyColumnSpacer={botReplyColumnSpacer}
/>
);
}
if (item.type === 'ghost_card') {
// 卡槽③:卡体 html/height 渲染时从 store 现取(换海报 = 推送
// bump version → 本组件重渲,GhostToolCard 原地更新 srcDoc)。
// entry 不 ready(极端竞态:build 后被 reset)静默不渲染,
// 下一次 store 变更自愈。
const entry = ghostCardSnapshot.byCallId.get(item.callId);
if (!entry || entry.status !== 'ready') return null;
if (readMailCard(entry.html)?.supersededBy) return null;
// 常态包一层 div(结构稳定,回锚媒体到达时卡片 iframe 不重挂);
// 回锚媒体(如 mivo 视频)挂卡正下方,与 tool_media 同款间距。
return (
<div
key={item.key}
data-render-item-key={item.key}
className="flex flex-col gap-2"
>
<GhostToolCard
callId={item.callId}
ghostId={item.ghostId}
toolName={item.tool}
toolInput={item.toolCall.toolInput ?? null}
html={entry.html}
animatedHtml={entry.animatedHtml}
height={entry.height}
running={!item.settled && isSessionStreaming}
sessionId={sessionId}
/>
{item.media && item.media.length > 0 ? (
<ShareableToolMedia
shareId={`${item.key}:media`}
items={item.media}
sessionId={sessionId}
selectionActive={shareSelectionActive}
/>
) : null}
</div>
);
}
if (item.type === 'tool_media') {
// tool-result-media: 跳出 tool_segment 折叠卡片,渲染体在
// ToolMediaList(与 ghost_card 回锚媒体共用单一来源)。
return (
<ShareableToolMedia
key={item.key}
renderItemKey={item.key}
shareId={item.key}
items={item.items}
sessionId={sessionId}
selectionActive={shareSelectionActive}
/>
);
}
const msg = item.message;
// v2: ThinkingCard manages its own expand state via
// useExpandedBlockMemory; no need to thread isTurnActive.
// Inline-rendered (not through MessageItem) so the live
// isStreaming flag from the message reaches it directly.
if (msg.role === 'thinking') {
return (
<ThinkingCard
key={item.key}
renderItemKey={item.key}
blockKey={msg.clientId}
content={msg.content}
isStreaming={msg.isStreaming}
startedAt={msg.thinkingStartedAt}
durationMs={msg.thinkingDurationMs}
isRedacted={msg.thinkingRedacted}
/>
);
}
// 分享选择:复选框与光栅化定位属性都挂在这个**既有** wrapper 上,
// 不新增 DOM 层级 —— 多包一层会让 AssistantMessage 子树在进出
// 选择模式时 remount(mermaid 重渲、GhostToolCard iframe 重载)。
const shareable =
Boolean(sessionId) && Boolean(msg.clientId) && isShareableMessage(msg);
const messageNode = (
<MessageItem
message={msg}
toolResult={singleResultMap.get(msg.clientId)}
workingDir={workingDir}
sessionId={sessionId}
sessionTitle={sessionTitle}
agentKind={agentKind}
remoteHostId={remoteHostId}
sessionRunning={isSessionStreaming}
assistantForkBlocked={shouldBlockAssistantFork(
isSessionStreaming,
msg,
assistantsWithFollowingUserBoundary,
)}
assistantIsTurnFinal={turnFinalAssistantClientIds.has(msg.clientId)}
userTurnUsageDetails={userTurnUsageDetailsByAssistantId.get(msg.clientId)}
isFirstUserMessage={msg.clientId === firstUserMessageClientId}
isLastUserMessage={msg.clientId === lastUserMessageClientId}
isLastUserInput={msg.clientId === lastUserInputClientId}
isContinuationTurnOwner={msg.clientId === continuationTurnClientId}
continuationInFlightProjectionCapability={
continuationInFlightProjectionCapability
}
isLastMessage={msg.clientId === lastMessageClientId}
localFileRefs={localFileRefs}
assistantAvatar={assistantAvatar}
simplifiedBotConversation={simplifiedBotConversation}
starterOptionsLocked={Boolean(lastUserMessageClientId)}
sessionSource={sessionSource}
onDiagnoseError={onDiagnoseError}
/>
);
const highlightClass =
highlightMessageClientId === msg.clientId
? 'rounded-xl bg-[hsl(var(--search-match-bg))] ring-1 ring-[var(--border-default)]'
: undefined;
const shareAttributes = shareable
? {
[SHARE_SESSION_ATTR]: sessionId,
[SHARE_MESSAGE_ATTR]: msg.clientId,
}
: {};
if (simplifiedBotConversation) {
// Call cards carry their own date/time in the compact header.
const groupTimestamp =
msg.systemCardType === 'voice-call'
? undefined
: botMessageTimeGroups.get(msg.clientId);
const startsUnread = botUnreadBoundaryClientId === msg.clientId;
return (
<div
key={item.key}
data-render-item-key={item.key}
data-message-client-id={msg.clientId}
className={cn('scroll-mt-20 transition-colors', highlightClass)}
>
{startsUnread ? (
<div
className="mb-3 flex items-center gap-3"
role="separator"
aria-label={t('bots.chat.newMessagesBoundary')}
>
<div className="h-px flex-1 bg-[var(--bot-unread-bg)] opacity-30" />
<span className="shrink-0 text-11 font-medium tracking-[0.08em] text-[var(--bot-unread-bg)]">
{t('bots.chat.newMessagesBoundary')}
</span>
<div className="h-px flex-1 bg-[var(--bot-unread-bg)] opacity-30" />
</div>
) : null}
{groupTimestamp !== undefined ? (
<time
dateTime={new Date(groupTimestamp).toISOString()}
className="mb-3 block text-center text-11 text-[var(--text-tertiary)]"
>
{formatBotMessageGroupTime(
groupTimestamp,
i18n.resolvedLanguage ?? i18n.language,
)}
</time>
) : null}
<div {...shareAttributes} className={cn(shareable && 'relative')}>
{shareable && shareSelectionActive ? (
<ShareMessageCheckbox clientId={msg.clientId} />
) : null}
{messageNode}
</div>
</div>
);
}
return (
<div
key={item.key}
data-render-item-key={item.key}
data-message-client-id={msg.clientId}
{...shareAttributes}
className={cn(
'scroll-mt-20 transition-colors',
shareable && 'relative',
highlightClass,
)}
>
{shareable && shareSelectionActive ? (
<ShareMessageCheckbox clientId={msg.clientId} />
) : null}
{messageNode}
</div>
);
})}
</div>}</MessageViewport>
</div>
</div>
{/* F1 / F3: 新消息悬浮提示——挂在 scrollRef 的 relative wrapper 内部,
与滚动容器平级。visible 由 `!isNearBottom && unreadCount > 0` 双重
守护;bottomOffset 让按钮位于输入框上边缘上方约 6px。 */}
<NewMessageIndicator
visible={!isNearBottom && unreadCount > 0}
count={unreadCount}
onClick={scrollToBottomSmooth}
bottomOffset={indicatorBottomOffset}
/>
{/* jump-to-bottom: 向下滚动时的扁平快捷跳底 pill。
互斥规则:NewMessageIndicator 有未读时优先(信息密度高),所以
unreadCount===0 才显示;isNearBottom=true 时无意义,handleScroll
已经会 reset showJumpDown,这里再叠一层 visible 守护防边界 race。 */}
<JumpToBottomChip
visible={showJumpDown && unreadCount === 0 && !isNearBottom}
onClick={scrollToBottomSmooth}
bottomOffset={indicatorBottomOffset}
/>
{/* message-nav-rail: 左缘提问导航条(每条提问一根刻度,当前项加深,
hover 预览,点击跳转)。仅普通任务按个性化开关挂载;挂载后的
显隐仍由组件自判:提问数 ≥4 且内容列左侧留白足够;窄窗口 / 嵌入面板
自然隐藏,绝不压在气泡上。 */}
{navRailEnabled && (
<MessageNavRail
entries={navRailEntries}
scrollRef={scrollRef}
contentMaxWidth={getContentWidth?.() || 880}
getContentMaxWidth={getContentWidth}
bottomOffset={resolvedBottomPadding}
onJump={handleNavRailJump}
onNavCoverageChange={setNavRailCoversNav}
resetKey={sessionId}
/>
)}
{/* prev-user-msg-jump: 右上角"跳到上一条提问"icon 按钮。
通过 createPortal 挂到祖先的 TopRightChipStack 容器里,与 DiffPanelToggle
各占栈中一行;DiffToggle 在 session 载入时就 mount,本 chip 仅在
上滑时 mount,DOM append 顺序天然落到第二行。仅在 viewport 之上
确实存在 user 消息时(prevUserMsgId !== null)portal 才挂入,
近底时 hook 自然返回 null → 不挂入 → 不占行。 */}
{chipSlot &&
prevUserMsgVisible &&
// 导航条完整覆盖导航时不再挂本 chip(入口去重,见 navRailCoversNav)。
!navRailCoversNav &&
createPortal(
<PrevMessageJumpChip preview={prevPreview} onClick={handleJumpToPrevUserMsg} />,
chipSlot,
)}
</div>
</ImageGalleryContext.Provider>
</GhostFulfillmentContext.Provider>
</ChatSessionFileProvider>
);
}
// memo: during streaming, only the currently-streaming message's content
// changes. Without memo, every token re-renders ALL historical MessageItems.
// workingDir is a stable string within a session lifecycle (the parent
// MessageStream is remounted via key={sessionId} on session switch), so the
// shallow-prop comparison still skips re-render cleanly.
//
// thinking messages are now rendered inline by MessageStream (above) so they
// can receive the live isSessionStreaming flag without breaking this memo.
// The thinking branch below is kept as a defensive fallback only.
/**
* Hang an identity mark to the left of an assistant bubble.
*
* Without a mark (every normal Cindy task) the bubble is returned untouched —
* no extra wrapper element, so the existing layout and its measurements are
* bit-for-bit what they were. With one (a Bot conversation) the row becomes the
* IM shape everyone already knows: avatar, then what they said.
*/
function withAssistantAvatar(avatar: ReactNode | undefined, bubble: ReactNode): ReactNode {
if (!avatar) return bubble;
return (
<div className="flex items-start gap-2.5">
<span className="mt-0.5 shrink-0">{avatar}</span>
<div className="min-w-0 flex-1">{bubble}</div>
</div>
);
}
const MessageItem = memo(function MessageItem({
message,
toolResult,
workingDir,
sessionId,
sessionTitle,
agentKind,
remoteHostId,
sessionRunning,
assistantForkBlocked,
assistantIsTurnFinal,
userTurnUsageDetails,
isFirstUserMessage,
isLastUserMessage,
isLastUserInput,
isContinuationTurnOwner,
continuationInFlightProjectionCapability,
isLastMessage,
localFileRefs,
assistantAvatar,
simplifiedBotConversation,
starterOptionsLocked,
sessionSource,
onDiagnoseError,
}: {
message: ChatMessage;
toolResult?: string;
workingDir: string;
/** Forwarded to User/AssistantMessage so the Fork button can call the IPC. */
sessionId?: string;
/** Forwarded to AssistantMessage so handoff cards can build return state. */
sessionTitle?: string | null;
/** Owning session's remote SSH host id; forwarded to User/AssistantMessage
* to gate Fork/Rewind (unsupported on remote cc daemon sessions). */
remoteHostId?: string | null;
/** Forwarded to User/AssistantMessage so they can read this agent's
* capabilities (gates Fork/Rewind icon visibility). */
agentKind?: 'cc' | 'codex' | 'pi';
/** Whether this session currently has an in-flight SDK turn. Rewind uses it
* to require an idle live query; fork can still target stable history. */
sessionRunning?: boolean;
/** True for assistant messages in the current tail turn while the session is running. */
assistantForkBlocked?: boolean;
/** True iff this assistant message is its turn's final answer text
* (collectTurnFinalAssistantClientIds). Gates the hover action bar —
* mid-turn texts don't mount it, keeping the stream compact. */
assistantIsTurnFinal?: boolean;
/** Aggregated token/cache/model details for this assistant's visible user turn. */
userTurnUsageDetails?: TurnUsageDetails;
/** True iff this message is the first user message in the visible list.
* UserMessage hides the Rewind button for it (no prior assistant to
* resumeSessionAt anchor on — backend would throw NO_PRIOR_ASSISTANT). */
isFirstUserMessage?: boolean;
/** True iff this message is the last user message in the full list —
* edit-last-message: gates the Edit (pencil) entry in UserMessage. */
isLastUserMessage?: boolean;
/**
* True iff this message is the last **user-side input** in the full list, synthetic rows
* included(见 `findLastUserInputClientId`)。自愈重连行用它 + `sessionRunning` 判断
* 「此刻正在跑的 turn 是不是我发起的」,从而决定要不要显示成"重新连接中"。
*/
isLastUserInput?: boolean;
/** 当前 vendor turn 的续跑 owner 是否就是这条消息。 */
isContinuationTurnOwner?: boolean;
/** 当前投影对精确续跑边界字段的支持状态;legacy 才允许启用旧端兼容兜底。 */
continuationInFlightProjectionCapability?: ContinuationInFlightProjectionCapability;
/** True iff this message is the last message in the full list —
* error-tail-banner: a trailing un-dismissed error row is rendered by the
* actionable banner above the composer instead of an inline card. */
isLastMessage?: boolean;
localFileRefs: readonly KnownLocalFileRef[];
/** Bot 对话:assistant 气泡左侧的伙伴头像。普通任务不传。 */
assistantAvatar?: ReactNode;
/** 伙伴对话消息操作栏使用轻量常显变体。 */
simplifiedBotConversation?: boolean;
/** True once the user has written anything in this task, which retires the opening's starter buttons. */
starterOptionsLocked?: boolean;
sessionSource?: string | null;
onDiagnoseError?: (error: ErrorDiagnosisSource) => void;
}) {
// silent-stop 自动续跑行(isSyntheticTrigger + systemCardType):渲染成
// 「已自动继续」分隔线,必须在 synthetic early-return 之前检查,否则分隔线被吞。
if (message.role === 'user' && message.systemCardType === 'input-handoff') {
const record = readInputHandoffRecordData(message.systemCardData);
return record ? <InputHandoffRecordRow record={record} at={message.createdAt} /> : null;
}
if (message.role === 'user' && message.systemCardType) {
return (
<SystemCard
cardType={message.systemCardType}
data={message.systemCardData}
sessionId={sessionId}
workingDir={workingDir}
// 「这条自愈记录此刻真的在飞吗」:main 持有 vendor-turn owner,只有旧端缺省该字段时
// 才回落到兼容启发式;supported / unknown 不再依赖 Renderer 的 sticky memory。
autoResumeInFlight={isAutoResumeRowInFlight({
isContinuationTurnOwner: isContinuationTurnOwner === true,
sessionRunning: sessionRunning === true,
isLastUserInput: isLastUserInput === true,
projectionCapability: continuationInFlightProjectionCapability ?? 'unknown',
})}
/>
);
}
// [UI_ACTION_TRIGGER] 合成指令行:保留在 messages 里参与时序判定(error-tail
// banner 的尾部判定不能忽视它,review P2),但不渲染任何气泡。
if (message.isSyntheticTrigger) return null;
switch (message.role) {
case 'user':
return (
<>
<UserMessage
sharedAuthorName={message.sharedAuthorName}
sharedAuthorMemberId={message.sharedAuthorMemberId}
workingDir={workingDir}
content={message.content}
quotesEncoded={message.quotesEncoded}
agentReferences={message.agentReferences}
pastedTextRanges={message.pastedTextRanges}
slashCommandRanges={message.slashCommandRanges}
images={message.images}
files={message.files}
createdAt={message.createdAt}
sessionId={sessionId}
agentKind={agentKind}
remoteHostId={remoteHostId}
messageClientId={message.clientId}
sessionRunning={sessionRunning}
isFirstUserMessage={isFirstUserMessage}
isLastUserMessage={isLastUserMessage}
automationOrigin={message.automationOrigin}
hookSource={message.hookSource}
sourceDevice={message.sourceDevice}
sourcePlugin={message.sourcePlugin}
delivery={message.delivery}
goalBadge={message.goalBadge}
blockedByGhost={message.blockedByGhost}
simplifiedBotConversation={simplifiedBotConversation}
replyQuote={message.replyQuote}
/>
{message.usageLimitAutoResumeInfo && (
<SystemCard
cardType="auto-resume"
data={message.usageLimitAutoResumeInfo}
sessionId={sessionId}
workingDir={workingDir}
/>
)}
</>
);
case 'assistant':
if (message.systemCardType === 'mcp-app') {
return sessionId ? (
<McpAppCard sessionId={sessionId} clientId={message.clientId}
title={String(message.systemCardData?.title ?? '')}
fallbackText={String(message.systemCardData?.fallbackText ?? '')} />
) : null;
}
if (message.systemCardType) {
const card = (
<SystemCard
cardType={message.systemCardType}
data={message.systemCardData}
sessionId={sessionId}
workingDir={workingDir}
/>
);
return simplifiedBotConversation && (message.systemCardType === 'bot-session-task'
|| message.systemCardType === 'bot-session-task-result'
|| message.systemCardType === 'bot-session-task-message'
|| message.systemCardType === 'bot-direct-message')
? withAssistantAvatar(
assistantAvatar ? (
<span aria-hidden="true" className="invisible">
{assistantAvatar}
</span>
) : undefined,
card,
)
: card;
}
return withAssistantAvatar(
assistantAvatar,
<>
<MessageSourceLabels sourceGroup={message.sourceGroup} align="start" />
<AssistantMessage
workingDir={workingDir}
localFileRefs={localFileRefs}
currentSessionId={sessionId}
currentSessionTitle={sessionTitle}
content={message.content}
isStreaming={message.isStreaming}
createdAt={message.createdAt}
messageClientId={message.clientId}
replyToClientId={message.replyToClientId}
agentKind={agentKind}
remoteHostId={remoteHostId}
forkBlocked={assistantForkBlocked}
sessionRunning={sessionRunning}
// 任务执行过程中(尾部 turn 流式中,forkBlocked=true)不出现操作行;
// turn 结束后只有收尾正文出现 —— 中间句彻底不挂 bar。
showActionBar={Boolean(assistantIsTurnFinal) && !assistantForkBlocked}
turnMoney={message.turnMoney}
turnCostUsd={message.turnCostUsd}
turnCostIsEstimate={message.turnCostIsEstimate}
userTurnMoney={message.userTurnMoney}
userTurnCostUsd={message.userTurnCostUsd}
userTurnCostIsEstimate={message.userTurnCostIsEstimate}
turnUsageDetails={message.turnUsageDetails}
userTurnUsageDetails={userTurnUsageDetails}
modelMismatch={message.modelMismatch}
failedSamplingAttempt={message.failedSamplingAttempt}
ghostReplyPending={message.ghostReplyPending}
simplifiedBotConversation={simplifiedBotConversation}
botLearning={message.botLearning}
botStarterOptions={message.botStarterOptions}
starterOptionsLocked={starterOptionsLocked}
botTaskResults={message.turnCompleted === true ? message.botTaskResults : undefined}
/>
</>,
);
case 'tool_use':
return (
<ToolCallCard
toolName={message.toolName ?? ''}
toolInput={message.toolInput}
summary={getToolSummary(message.toolName ?? '', message.toolInput)}
toolResult={toolResult}
/>
);
case 'tool_result':
// Standalone tool_result — should not normally appear
// (consumed by tool_use card or group), but render as fallback
return null;
case 'ask_user':
return <AskUserQuestionBubble message={message} />;
case 'plan_review':
// 计划正文是会话消息内容,解析上下文与 AssistantMessage 保持一致
// (currentSessionId 缺失会让远程会话里计划内的媒体链接绕过
// cindy-remote-media:// 改写而坏图)。
return (
<PlanReviewBubble
message={message}
workingDir={workingDir}
currentSessionId={sessionId}
currentSessionTitle={sessionTitle}
localFileRefs={localFileRefs}
/>
);
case 'error':
// interrupted-turn-resume:app 退出中断标记行不进消息流(2026-07-05 产品
// 决策)——它作为「会话尾部是否停在中断态」的判定源保留在 messages 数组里,
// 呈现走 CCAgentSessionView 输入框上方的 InterruptedTurnBanner(与 ErrorBanner
// 同风格)+ sidebar 'error' 红点,这里渲染 null。
if (message.errorReason === APP_EXIT_INTERRUPTED_REASON) return null;
// error-tail-banner:普通失败行是尾部消息且未被忽略时,由输入框上方的可操作
// 红条(重试/关闭)独家承载,流内不重复渲染,避免双红条;被忽略或后续有新
// 消息后回落为流内静态历史卡。
if (isLastMessage && !message.errorDismissed) return null;
// 历史里的 turn 失败记录(role='error' 持久化行)——静态时间线卡,
// live 报错仍走输入框上方的 ErrorBanner,两者不会同时出现
// (error 行落库时不广播,只在历史加载路径进入消息流)。
return (
<ErrorMessageCard
message={message.content}
reason={message.errorReason}
providerId={message.errorProviderId}
toolLoop={message.toolLoop}
sessionSource={sessionSource}
onDiagnose={onDiagnoseError}
/>
);
case 'thinking':
// Defensive fallback only — MessageStream renders thinking inline.
return (
<ThinkingCard
content={message.content}
isStreaming={message.isStreaming}
startedAt={message.thinkingStartedAt}
durationMs={message.thinkingDurationMs}
isRedacted={message.thinkingRedacted}
/>
);
default:
return null;
}
});