From 0400b30cc159fb470eca2f9cd9a626a84907f1de Mon Sep 17 00:00:00 2001
From: zhangmo8 <zhangmo8@users.noreply.github.com>
Date: Thu, 16 Jul 2026 13:04:48 +0800
Subject: [PATCH 01/14] refactor(chat): extract plan-lifecycle and
 display-messages composables

---
 .../chatpage-decomposition/spec.md            |  52 ++
 src/renderer/src/composables/message/types.ts |  17 -
 .../composables/message/useMessageScroll.ts   | 339 ---------
 src/renderer/src/pages/ChatPage.vue           | 662 +-----------------
 .../src/pages/chat-page/useDisplayMessages.ts | 494 +++++++++++++
 .../pages/chat-page/usePlanFloatLifecycle.ts  | 244 +++++++
 6 files changed, 826 insertions(+), 982 deletions(-)
 create mode 100644 docs/architecture/chatpage-decomposition/spec.md
 delete mode 100644 src/renderer/src/composables/message/useMessageScroll.ts
 create mode 100644 src/renderer/src/pages/chat-page/useDisplayMessages.ts
 create mode 100644 src/renderer/src/pages/chat-page/usePlanFloatLifecycle.ts

diff --git a/docs/architecture/chatpage-decomposition/spec.md b/docs/architecture/chatpage-decomposition/spec.md
new file mode 100644
index 0000000000..418d267ae4
--- /dev/null
+++ b/docs/architecture/chatpage-decomposition/spec.md
@@ -0,0 +1,52 @@
+# ChatPage 分解与竞态治理
+
+## 背景
+
+`src/renderer/src/pages/ChatPage.vue` 已膨胀到 3050 行，单个 `<script setup>` 承载 10+ 个关注点：
+会话恢复、消息记录转换、虚拟窗口、测量批处理、手势/滚动、占位符状态机、Plan 快照生命周期、
+会话内搜索、语音输入、发送/排队/steer、消息操作。竞态治理靠散落的手写令牌
+（`sessionRestoreRequestId`、`voiceInputConfigToken`、`attachmentFilterToken`、
+`chatScrollSessionEpoch`、`pendingAssistantPlaceholderSeq`）和大量模块级 `let`，理解成本极高。
+
+## 现状边界（已良好分层，不动）
+
+滚动仲裁已是成熟架构，本次仅把 ChatPage 内的胶水调用归拢，不改其内部时序：
+
+- `useChatScrollController` — 独占滚动通道、状态机驱动、rAF commit/verify。
+- `chatScrollState` — 纯 reducer 状态机（mode/userOwned/nearBottom/activeGesture）。
+- `chatScrollOperationArbiter` — 物理滚动条独占所有权 + 优先级抢占。
+- `chatScrollRequestQueue` — 单槽优先级队列。
+- `useMessageWindow` — 虚拟列表布局、测量高度、快照捕获/恢复。
+- `recentMessageMeasurementCache` — 最近会话测量 LRU 缓存。
+
+## 目标
+
+1. 主文件收缩到 ~400 行，只做装配 + 模板。
+2. 每类竞态由一个自持 epoch/token 的 composable 独立治理，边界清晰。
+3. 删除确认的死代码。
+4. 行为零漂移：每抽一个 composable 即 typecheck；最终 lint/test/真实应用验证。
+
+## 死代码（确认零引用）
+
+- `composables/message/useMessageScroll.ts`（339 行）— 全项目零引用，旧 vue-virtual-scroller 实现。
+- `composables/message/types.ts` 中的 `ScrollInfo` 接口 — 仅被上文件引用（`CaptureOptions` 仍在用，保留）。
+
+## 分解目标（7 个 composable）
+
+| composable | 职责 | 收编的状态/竞态 |
+|---|---|---|
+| `useSessionRestore` | 会话切换、令牌 gate、恢复 | `sessionRestoreRequestId`、`canWriteSessionView`、恢复 watch |
+| `useDisplayMessages` | 记录→DisplayMessage、稳定/流式分离、缓存 | `displayMessageCache`、`assistantRenderKeyByMessageId` |
+| `useAssistantPlaceholder` | 占位符四态机 + renderKey 交接 | `pendingAssistantPlaceholder` 全套 |
+| `useMessageVirtualization` | 窗口范围、测量批处理、锚点补偿、几何观测 | `pendingMeasureQueue`、rAF flush |
+| `useListGestures` | wheel/touch/pointer/键盘手势 → 控制器 | ~15 handler、`isListScrolling` |
+| `usePlanFloatLifecycle` | Plan 快照跨会话生命周期 + 延迟清除 | `planSnapshotClearTimers`、3 lifecycleKey |
+| `useChatSearch` | 会话内搜索（包 `lib/chatSearch`） | 搜索 rAF、highlight 调度 |
+| `useComposerSubmit` | 发送/排队/steer/命令/compaction | 统一 gate 后的提交路径 |
+
+## 约束
+
+- 每个 composable 自持一个防竞态 epoch/token，替代散落的模块级令牌。
+- 不改 `useChatScrollController` 及其协作模块的对外时序契约。
+- 优先 shadcn-vue / VueUse（`useEventListener`、`useRafFn` 等）替代手写 rAF/监听器。
+- i18n key 不新增；用户可见字符串沿用现有 key。
diff --git a/src/renderer/src/composables/message/types.ts b/src/renderer/src/composables/message/types.ts
index f9e81bcf09..ae8094b925 100644
--- a/src/renderer/src/composables/message/types.ts
+++ b/src/renderer/src/composables/message/types.ts
@@ -1,9 +1,3 @@
-export interface ScrollInfo {
-  viewportHeight: number
-  contentHeight: number
-  scrollTop: number
-}
-
 export interface CaptureOptions {
   messageId: string
   parentId?: string
@@ -13,14 +7,3 @@ export interface CaptureOptions {
     model_provider: string
   }
 }
-
-export interface WatermarkConfig {
-  isDark: boolean
-  version: string
-  texts: {
-    brand: string
-    tip: string
-    model?: string
-    provider?: string
-  }
-}
diff --git a/src/renderer/src/composables/message/useMessageScroll.ts b/src/renderer/src/composables/message/useMessageScroll.ts
deleted file mode 100644
index 972d16c6c8..0000000000
--- a/src/renderer/src/composables/message/useMessageScroll.ts
+++ /dev/null
@@ -1,339 +0,0 @@
-import { ref, reactive, readonly, onBeforeUnmount, nextTick, type Ref } from 'vue'
-import { useDebounceFn } from '@vueuse/core'
-import type { ScrollInfo } from './types'
-
-// === Constants ===
-const MESSAGE_HIGHLIGHT_CLASS = 'message-highlight'
-const MAX_SCROLL_RETRIES = 12
-const SCROLL_RETRY_DELAY = 80
-const HIGHLIGHT_DURATION = 2000
-const PLACEHOLDER_POSITION_THRESHOLD = 5000
-
-type DynamicScrollerHandle = {
-  scrollToBottom?: () => void
-  scrollToItem?: (index: number) => void
-}
-
-export interface UseMessageScrollOptions {
-  dynamicScrollerRef?: Ref<DynamicScrollerHandle | null>
-  shouldAutoFollow?: Ref<boolean>
-  autoScrollEnabled?: Ref<boolean>
-  scrollAnchor?: Ref<HTMLDivElement | undefined>
-}
-
-export function useMessageScroll(options?: UseMessageScrollOptions) {
-  const messagesContainer = ref<HTMLDivElement>()
-  const scrollAnchor = options?.scrollAnchor ?? ref<HTMLDivElement>()
-  const aboveThreshold = ref(false)
-
-  const scrollInfo = reactive<ScrollInfo>({
-    viewportHeight: 0,
-    contentHeight: 0,
-    scrollTop: 0
-  })
-
-  let intersectionObserver: IntersectionObserver | null = null
-  let scrollRetryTimer: number | null = null
-  let scrollRetryToken = 0
-  let bottomScrollRetryTimer: number | null = null
-  let bottomScrollCancelToken = 0
-  let pendingScrollTargetId: string | null = null
-
-  const updateScrollInfoImmediate = () => {
-    const container = messagesContainer.value
-    if (!container) return
-    scrollInfo.viewportHeight = container.clientHeight
-    scrollInfo.contentHeight = container.scrollHeight
-    scrollInfo.scrollTop = container.scrollTop
-  }
-
-  // Debounced version for scroll events (~60fps)
-  const updateScrollInfo = useDebounceFn(updateScrollInfoImmediate, 16)
-
-  const handleScroll = () => {
-    updateScrollInfo()
-  }
-
-  /**
-   * Fallback scroll to bottom (non-virtual scroll)
-   */
-  const scrollToBottomBase = (_smooth = false) => {
-    const container = messagesContainer.value
-    if (!container) return
-
-    const targetTop = Math.max(container.scrollHeight - container.clientHeight, 0)
-    container.scrollTop = targetTop
-    updateScrollInfoImmediate()
-  }
-
-  /**
-   * Schedule scroll to bottom with retry mechanism for virtual scroller
-   */
-  const scheduleScrollToBottom = (force = false) => {
-    if (bottomScrollRetryTimer) {
-      clearTimeout(bottomScrollRetryTimer)
-      bottomScrollRetryTimer = null
-    }
-    const currentBottomToken = ++bottomScrollCancelToken
-
-    nextTick(() => {
-      const shouldAutoFollow = options?.shouldAutoFollow
-      const autoScrollEnabled = options?.autoScrollEnabled
-      const canAutoFollow = autoScrollEnabled ? autoScrollEnabled.value : true
-      if (force && shouldAutoFollow) {
-        if (canAutoFollow) {
-          shouldAutoFollow.value = true
-        }
-      }
-
-      if (!force && !canAutoFollow) {
-        updateScrollInfo()
-        return
-      }
-
-      if (!force && shouldAutoFollow && !shouldAutoFollow.value) {
-        updateScrollInfo()
-        return
-      }
-
-      const dynamicScrollerRef = options?.dynamicScrollerRef
-      const scroller = dynamicScrollerRef?.value
-      const scrollToBottomFn = scroller?.scrollToBottom
-
-      if (scrollToBottomFn) {
-        // Virtual scroll with retry mechanism
-        let retryCount = 0
-        let lastScrollHeight = 0
-
-        const attemptScrollToBottom = () => {
-          if (currentBottomToken !== bottomScrollCancelToken) return
-          scrollToBottomFn()
-
-          nextTick(() => {
-            bottomScrollRetryTimer = window.setTimeout(() => {
-              bottomScrollRetryTimer = null
-              if (currentBottomToken !== bottomScrollCancelToken) return
-
-              const container = messagesContainer.value
-              if (!container) {
-                updateScrollInfo()
-                return
-              }
-
-              const currentScrollHeight = container.scrollHeight
-              const currentScrollTop = container.scrollTop
-              const viewportHeight = container.clientHeight
-              const distanceToBottom = currentScrollHeight - currentScrollTop - viewportHeight
-
-              const isAtBottom = distanceToBottom <= 1
-              const heightStillChanging = currentScrollHeight !== lastScrollHeight
-              lastScrollHeight = currentScrollHeight
-
-              if (!isAtBottom && heightStillChanging && retryCount < MAX_SCROLL_RETRIES) {
-                retryCount++
-                attemptScrollToBottom()
-              } else {
-                updateScrollInfo()
-              }
-            }, SCROLL_RETRY_DELAY)
-          })
-        }
-
-        attemptScrollToBottom()
-      } else {
-        // Fallback to base scroll
-        scrollToBottomBase()
-      }
-    })
-  }
-
-  /**
-   * Public scroll to bottom API
-   */
-  const scrollToBottom = (force = false) => scheduleScrollToBottom(force)
-
-  /**
-   * Highlight a message element
-   */
-  const highlightMessage = (target: HTMLElement) => {
-    target.classList.add(MESSAGE_HIGHLIGHT_CLASS)
-    setTimeout(() => target.classList.remove(MESSAGE_HIGHLIGHT_CLASS), HIGHLIGHT_DURATION)
-  }
-
-  /**
-   * Fallback scroll to message (non-virtual scroll)
-   */
-  const scrollToMessageBase = (messageId: string) => {
-    nextTick(() => {
-      const messageElement = document.querySelector(
-        `[data-message-id="${messageId}"]`
-      ) as HTMLElement | null
-      if (messageElement) {
-        messageElement.scrollIntoView({ block: 'start' })
-        highlightMessage(messageElement)
-      }
-      updateScrollInfoImmediate()
-    })
-  }
-
-  /**
-   * Scroll to specific message with retry mechanism for virtual scroller
-   */
-  const scrollToMessage = (messageId: string, itemsGetter?: () => Array<{ id: string }>) => {
-    const dynamicScrollerRef = options?.dynamicScrollerRef
-    const scroller = dynamicScrollerRef?.value
-    const scrollToItemFn = scroller?.scrollToItem
-
-    if (!scrollToItemFn || !itemsGetter) {
-      scrollToMessageBase(messageId)
-      return
-    }
-
-    const items = itemsGetter()
-    const index = items.findIndex((item) => item.id === messageId)
-
-    if (index === -1) return
-
-    pendingScrollTargetId = messageId
-
-    const tryApplyCenterAndHighlight = () => {
-      const container = messagesContainer.value
-      if (!container) return false
-
-      const target = container.querySelector(
-        `[data-message-id="${messageId}"]`
-      ) as HTMLElement | null
-      if (!target) return false
-
-      const targetRect = target.getBoundingClientRect()
-      const containerRect = container.getBoundingClientRect()
-      const targetTop = targetRect.top - containerRect.top + container.scrollTop
-
-      // Check if element is actually rendered (not in placeholder state)
-      if (
-        Math.abs(targetTop) > PLACEHOLDER_POSITION_THRESHOLD &&
-        (targetTop < 0 || targetTop > container.scrollHeight)
-      ) {
-        return false
-      }
-
-      target.scrollIntoView({ block: 'start', behavior: 'instant' })
-      updateScrollInfo()
-      highlightMessage(target)
-      pendingScrollTargetId = null
-      return true
-    }
-
-    if (scrollRetryTimer) clearTimeout(scrollRetryTimer)
-    scrollRetryTimer = null
-
-    const currentToken = ++scrollRetryToken
-    let retryCount = 0
-
-    const attemptScroll = () => {
-      if (currentToken !== scrollRetryToken) return
-
-      scrollToItemFn(index)
-      nextTick(() => {
-        setTimeout(() => {
-          if (tryApplyCenterAndHighlight()) return
-
-          if (++retryCount < MAX_SCROLL_RETRIES) {
-            scrollRetryTimer = window.setTimeout(() => {
-              scrollRetryTimer = null
-              attemptScroll()
-            }, SCROLL_RETRY_DELAY)
-          } else {
-            pendingScrollTargetId = null
-          }
-        }, SCROLL_RETRY_DELAY)
-      })
-    }
-
-    attemptScroll()
-  }
-
-  /**
-   * Handle virtual scroll update
-   */
-  const handleVirtualScrollUpdate = () => {
-    if (!pendingScrollTargetId) return
-    const container = messagesContainer.value
-    if (!container) return
-
-    const target = container.querySelector(
-      `[data-message-id="${pendingScrollTargetId}"]`
-    ) as HTMLElement | null
-    if (!target) return
-
-    const messageId = pendingScrollTargetId
-    pendingScrollTargetId = null
-    scrollToMessageBase(messageId)
-  }
-
-  const setupScrollObserver = () => {
-    if (intersectionObserver) {
-      intersectionObserver.disconnect()
-    }
-
-    intersectionObserver = new IntersectionObserver(
-      (entries) => {
-        const entry = entries[0]
-        aboveThreshold.value = !entry.isIntersecting
-        updateScrollInfoImmediate()
-      },
-      {
-        root: messagesContainer.value,
-        rootMargin: '0px 0px 20px 0px',
-        threshold: 0
-      }
-    )
-
-    if (scrollAnchor.value) {
-      intersectionObserver.observe(scrollAnchor.value)
-    }
-
-    updateScrollInfoImmediate()
-  }
-
-  onBeforeUnmount(() => {
-    if (intersectionObserver) {
-      intersectionObserver.disconnect()
-      intersectionObserver = null
-    }
-
-    if (scrollRetryTimer) {
-      clearTimeout(scrollRetryTimer)
-      scrollRetryTimer = null
-    }
-
-    if (bottomScrollRetryTimer) {
-      clearTimeout(bottomScrollRetryTimer)
-      bottomScrollRetryTimer = null
-    }
-    bottomScrollCancelToken++
-
-    pendingScrollTargetId = null
-  })
-
-  return {
-    // Refs
-    messagesContainer,
-    scrollAnchor,
-    aboveThreshold: readonly(aboveThreshold),
-
-    // Scroll info (readonly to prevent external mutation)
-    scrollInfo: readonly(scrollInfo),
-
-    // Methods
-    scrollToBottom,
-    scrollToBottomBase,
-    scrollToMessage,
-    scrollToMessageBase,
-    handleScroll,
-    updateScrollInfo: updateScrollInfoImmediate,
-    setupScrollObserver,
-    handleVirtualScrollUpdate,
-    highlightMessage
-  }
-}
diff --git a/src/renderer/src/pages/ChatPage.vue b/src/renderer/src/pages/ChatPage.vue
index 216d90b4e9..b8c0f595bd 100644
--- a/src/renderer/src/pages/ChatPage.vue
+++ b/src/renderer/src/pages/ChatPage.vue
@@ -264,15 +264,7 @@ import ChatTopBar from '@/components/chat/ChatTopBar.vue'
 import ChatSearchBar from '@/components/chat/ChatSearchBar.vue'
 import ChatSessionSkeleton from '@/components/chat/ChatSessionSkeleton.vue'
 import MessageList from '@/components/chat/MessageList.vue'
-import type {
-  DisplayAssistantMessageBlock,
-  DisplayMessage,
-  DisplayMessageUsage
-} from '@/components/chat/messageListItems'
-import {
-  filterRenderableAssistantBlocks,
-  hasRenderableAssistantBlocks
-} from '@/components/chat/messageListItems'
+import type { DisplayAssistantMessageBlock } from '@/components/chat/messageListItems'
 import ChatInputBox from '@/components/chat/ChatInputBox.vue'
 import ChatInputToolbar from '@/components/chat/ChatInputToolbar.vue'
 import AgentProgressFloat from '@/components/chat/AgentProgressFloat.vue'
@@ -315,12 +307,11 @@ import { markChatSessionPerformance } from '@/composables/chat/chatSessionPerfor
 import { type ChatScrollReason, type ChatScrollTarget } from '@/composables/chat/chatScrollState'
 import { playChatInputHeroFlight } from '@/lib/chatInputHero'
 import { scheduleStartupDeferredTask } from '@/lib/startupDeferred'
+import { usePlanFloatLifecycle } from './chat-page/usePlanFloatLifecycle'
+import { useDisplayMessages } from './chat-page/useDisplayMessages'
 import type {
-  ChatMessageRecord,
-  AssistantMessageBlock,
   MessageFile,
   UserMessageInlineItem,
-  MessageMetadata,
   SendMessageInput,
   ToolInteractionResponse
 } from '@shared/types/agent-interface'
@@ -366,7 +357,6 @@ const MESSAGE_INITIAL_WINDOW_COUNT = 90
 const MESSAGE_WINDOW_OVERSCAN_PX = 2400
 /** After the user stops scrolling, wait this long before resuming windowing/measure. */
 const SCROLL_IDLE_MS = 140
-const PLAN_FLOAT_CLEAR_DELAY_MS = 1200
 const isAcpWorkdirMissing = computed(() => {
   const activeSession = sessionStore.activeSession
   if (!activeSession || activeSession.providerId !== 'acp') {
@@ -414,7 +404,6 @@ async function restoreSessionMessages(id: string, requestId: number) {
 // --- Auto-scroll ---
 const scrollContainer = ref<HTMLDivElement | null>(null)
 const messageSearchRoot = ref<HTMLDivElement | null>(null)
-const planFloatLingerBySession = ref<Record<string, boolean>>({})
 const chatInputHeroHostRef = ref<HTMLDivElement | null>(null)
 let chatScrollSessionEpoch = 0
 
@@ -435,15 +424,6 @@ const chatScrollController = useChatScrollController({
 })
 const pendingDeleteMessageId = ref<string | null>(null)
 const showDeleteMessageDialog = computed(() => Boolean(pendingDeleteMessageId.value))
-const pendingAssistantPlaceholder = ref<{
-  id: string
-  sessionId: string
-  baselineAssistantMessageIds: Set<string>
-  baselineMessageOrderSeq: number
-  baselineCreatedAt: number
-} | null>(null)
-const assistantRenderKeyByMessageId = ref<Record<string, string>>({})
-let pendingAssistantPlaceholderSeq = 0
 const scrollViewportTop = ref(0)
 const scrollViewportHeight = ref(0)
 const messageWindowOriginTop = ref(0)
@@ -471,19 +451,6 @@ let isListGestureActive = false
 let pendingHistoryLoadAtIdle = false
 let hasUpwardPaginationIntent = false
 let lastGestureClientY: number | null = null
-const displayMessageCache = new Map<
-  string,
-  {
-    updatedAt: number
-    content: ChatMessageRecord['content']
-    metadata: ChatMessageRecord['metadata']
-    modelId: string
-    providerId: string
-    status: DisplayMessage['status']
-    renderKey?: string
-    message: DisplayMessage
-  }
->()
 const traceMessageId = ref<string | null>(null)
 const isChatSearchOpen = ref(false)
 const chatSearchQuery = ref('')
@@ -1043,10 +1010,8 @@ watch(
     hasUpwardPaginationIntent = false
     lastGestureClientY = null
     pendingDeleteMessageId.value = null
-    pendingAssistantPlaceholder.value = null
     clearChatSearchState()
-    displayMessageCache.clear()
-    assistantRenderKeyByMessageId.value = {}
+    resetDisplayMessagesForSessionChange()
     sessionRestoreRequestId += 1
     chatScrollSessionEpoch = chatScrollController.beginSession(id)
     markChatSessionPerformance('selected', id, chatScrollSessionEpoch)
@@ -1120,406 +1085,24 @@ watch(
   { immediate: true, flush: 'post' }
 )
 
-function resolveAssistantModelName(modelId: string): string {
-  if (!modelId) {
-    return 'Assistant'
-  }
-  const found = modelStore.findModelByIdOrName(modelId)
-  return found?.model?.name || modelId
-}
-
-function buildUsage(metadata: MessageMetadata): DisplayMessageUsage {
-  return {
-    context_usage: 0,
-    tokens_per_second: metadata.tokensPerSecond ?? 0,
-    total_tokens: metadata.totalTokens ?? 0,
-    generation_time: metadata.generationTime ?? 0,
-    first_token_time: metadata.firstTokenTime ?? 0,
-    reasoning_start_time: metadata.reasoningStartTime ?? 0,
-    reasoning_end_time: metadata.reasoningEndTime ?? 0,
-    input_tokens: metadata.inputTokens ?? 0,
-    output_tokens: metadata.outputTokens ?? 0
-  }
-}
-
-function toDisplayMessage(record: ChatMessageRecord): DisplayMessage {
-  const metadata = messageStore.getMessageMetadata(record)
-  const modelId = metadata.model || sessionStore.activeSession?.modelId || ''
-  const providerId = metadata.provider || sessionStore.activeSession?.providerId || ''
-  const cached = displayMessageCache.get(record.id)
-  if (
-    cached &&
-    cached.updatedAt === record.updatedAt &&
-    cached.content === record.content &&
-    cached.metadata === record.metadata &&
-    cached.modelId === modelId &&
-    cached.providerId === providerId &&
-    cached.status === record.status &&
-    cached.renderKey === assistantRenderKeyByMessageId.value[record.id]
-  ) {
-    return cached.message
-  }
-
-  const modelName = record.role === 'assistant' ? resolveAssistantModelName(modelId) : ''
-  const baseMessage = {
-    id: record.id,
-    timestamp: record.createdAt,
-    updatedAt: record.updatedAt,
-    avatar: '',
-    name: record.role === 'user' ? 'You' : 'Assistant',
-    model_name: modelName,
-    model_id: modelId,
-    model_provider: providerId,
-    status: record.status,
-    error: '',
-    usage: buildUsage(metadata),
-    conversationId: record.sessionId,
-    is_variant: 0,
-    orderSeq: record.orderSeq,
-    messageType: metadata.messageType === 'compaction' ? 'compaction' : 'normal',
-    compactionStatus: metadata.compactionStatus,
-    summaryUpdatedAt: metadata.summaryUpdatedAt ?? null
-  } as const
-
-  const streamingRenderKey = assistantRenderKeyByMessageId.value[record.id]
-  const nextMessage =
-    record.role === 'assistant'
-      ? ({
-          ...baseMessage,
-          ...(streamingRenderKey ? { renderKey: streamingRenderKey } : {}),
-          role: 'assistant',
-          content: filterRenderableAssistantBlocks(messageStore.getAssistantMessageBlocks(record))
-        } as DisplayMessage)
-      : ({
-          ...baseMessage,
-          role: 'user',
-          content: messageStore.getUserMessageContent(record)
-        } as DisplayMessage)
-
-  displayMessageCache.set(record.id, {
-    updatedAt: record.updatedAt,
-    content: record.content,
-    metadata: record.metadata,
-    modelId,
-    providerId,
-    status: record.status,
-    renderKey: streamingRenderKey,
-    message: nextMessage
-  })
-
-  return nextMessage
-}
-
-// Build a streaming assistant message from live blocks
-function toStreamingMessage(
-  blocks: AssistantMessageBlock[],
-  messageId?: string | null
-): DisplayMessage {
-  const modelId = sessionStore.activeSession?.modelId ?? ''
-  const now = Date.now()
-  const renderableBlocks = filterRenderableAssistantBlocks(blocks as DisplayAssistantMessageBlock[])
-  return {
-    // Key the streaming row by the real message id when we have one, so that when
-    // the persisted copy arrives at stream end Vue patches the SAME node in place
-    // (markdown DOM reused) instead of unmount/remount — no completion flash.
-    // Falls back to a synthetic id only when the backend hasn't assigned one yet.
-    id: messageId ?? '__streaming__',
-    content: renderableBlocks,
-    role: 'assistant',
-    timestamp: now,
-    updatedAt: now,
-    avatar: '',
-    name: 'Assistant',
-    model_name: resolveAssistantModelName(modelId),
-    model_id: modelId,
-    model_provider: sessionStore.activeSession?.providerId ?? '',
-    status: 'pending',
-    error: '',
-    usage: buildUsage({}),
-    conversationId: props.sessionId,
-    is_variant: 0,
-    orderSeq: Number.MAX_SAFE_INTEGER
-  }
-}
-
-function shouldRenderDisplayMessage(message: DisplayMessage): boolean {
-  if (message.role !== 'assistant') {
-    return true
-  }
-
-  if (message.messageType === 'compaction') {
-    return true
-  }
-
-  if (message.status === 'pending') {
-    return true
-  }
-
-  return hasRenderableAssistantBlocks(message.content)
-}
-
-const hasInlineStreamingTarget = computed(() => {
-  if (!isCurrentSessionStreaming.value) return false
-  const messageId = messageStore.currentStreamMessageId
-  if (!messageId) return false
-  return messageStore.messageCache.get(messageId)?.sessionId === props.sessionId
-})
-const hasFirstStreamingContent = computed(
-  () => messageStore.streamingBlocks.length > 0 && hasInlineStreamingTarget.value
-)
-
-const ephemeralRateLimitMessageId = computed(() => {
-  const messageId = messageStore.currentStreamMessageId
-  if (
-    !isCurrentSessionStreaming.value ||
-    !messageId ||
-    !messageId.startsWith(RATE_LIMIT_STREAM_MESSAGE_PREFIX)
-  ) {
-    return null
-  }
-
-  return messageId
-})
-
-const ephemeralRateLimitBlock = computed<DisplayAssistantMessageBlock | null>(() => {
-  if (!ephemeralRateLimitMessageId.value || messageStore.streamingBlocks.length === 0) {
-    return null
-  }
-
-  const [firstBlock] = messageStore.streamingBlocks as DisplayAssistantMessageBlock[]
-  if (
-    messageStore.streamingBlocks.length !== 1 ||
-    firstBlock?.type !== 'action' ||
-    firstBlock.action_type !== 'rate_limit'
-  ) {
-    return null
-  }
-
-  return firstBlock
-})
-
-const hasNewAssistantMessageAfterPendingPlaceholder = computed(() => {
-  const pending = pendingAssistantPlaceholder.value
-  if (!pending || pending.sessionId !== props.sessionId) return false
-
-  return messageStore.messages.some(
-    (message) =>
-      message.role === 'assistant' &&
-      !pending.baselineAssistantMessageIds.has(message.id) &&
-      isMessageAfterPendingAssistantBaseline(message, pending)
-  )
-})
-
-const shouldShowPendingAssistantPlaceholder = computed(() => {
-  const pending = pendingAssistantPlaceholder.value
-  return Boolean(
-    pending &&
-    pending.sessionId === props.sessionId &&
-    !hasFirstStreamingContent.value &&
-    !hasNewAssistantMessageAfterPendingPlaceholder.value &&
-    !ephemeralRateLimitBlock.value
-  )
-})
-
-const hasPendingAssistantMessage = computed(() =>
-  messageStore.messages.some(
-    (message) => message.role === 'assistant' && message.status === 'pending'
-  )
-)
-
-const shouldShowGeneratingAssistantPlaceholder = computed(
-  () =>
-    isGenerating.value &&
-    !shouldShowPendingAssistantPlaceholder.value &&
-    !hasFirstStreamingContent.value &&
-    !hasPendingAssistantMessage.value &&
-    !ephemeralRateLimitBlock.value
-)
-
-watch(
-  () => hasFirstStreamingContent.value || hasNewAssistantMessageAfterPendingPlaceholder.value,
-  (shouldClearPendingAssistant) => {
-    if (shouldClearPendingAssistant) {
-      bindPendingAssistantRenderKey()
-      pendingAssistantPlaceholder.value = null
-    }
-  }
-)
-
-function onDismissPlanFloat() {
-  agentPlanStore.dismiss(props.sessionId)
-}
-
-function createPendingAssistantPlaceholder(sessionId: string): string {
-  const id = `__pending_assistant_${Date.now()}_${++pendingAssistantPlaceholderSeq}`
-  const loadedMessages = messageStore.messages
-  const baselineAssistantMessageIds = new Set(
-    loadedMessages.filter((message) => message.role === 'assistant').map((message) => message.id)
-  )
-  const baselineMessageOrderSeq = Math.max(
-    Number.NEGATIVE_INFINITY,
-    ...loadedMessages.map((message) =>
-      Number.isFinite(message.orderSeq) ? message.orderSeq : Number.NEGATIVE_INFINITY
-    )
-  )
-  pendingAssistantPlaceholder.value = {
-    id,
-    sessionId,
-    baselineAssistantMessageIds,
-    baselineMessageOrderSeq,
-    baselineCreatedAt: Date.now()
-  }
-  return id
-}
-
-function isMessageAfterPendingAssistantBaseline(
-  message: ChatMessageRecord,
-  pending: NonNullable<typeof pendingAssistantPlaceholder.value>
-): boolean {
-  if (Number.isFinite(pending.baselineMessageOrderSeq) && Number.isFinite(message.orderSeq)) {
-    return message.orderSeq > pending.baselineMessageOrderSeq
-  }
-
-  return message.createdAt > pending.baselineCreatedAt
-}
-
-function clearPendingAssistantPlaceholder(id?: string): void {
-  if (!id || pendingAssistantPlaceholder.value?.id === id) {
-    pendingAssistantPlaceholder.value = null
-  }
-}
-
-function bindPendingAssistantRenderKey(): void {
-  const pending = pendingAssistantPlaceholder.value
-  const streamMessageId = messageStore.currentStreamMessageId
-  if (
-    !pending ||
-    pending.sessionId !== props.sessionId ||
-    !streamMessageId ||
-    !hasInlineStreamingTarget.value ||
-    assistantRenderKeyByMessageId.value[streamMessageId] === pending.id
-  ) {
-    return
-  }
-  assistantRenderKeyByMessageId.value = {
-    ...assistantRenderKeyByMessageId.value,
-    [streamMessageId]: pending.id
-  }
-}
-
-watch(
-  () => [messageStore.currentStreamMessageId, hasInlineStreamingTarget.value] as const,
-  bindPendingAssistantRenderKey
-)
-
-/**
- * Stable history list: intentionally does NOT read streamRevision / streamingBlocks,
- * so token-level updates do not rebuild every display message in long sessions.
- * The in-flight assistant row is owned by streamingDisplayTail instead.
- */
-const stableDisplayMessages = computed(() => {
-  void messageStore.lastPersistedRevision
-  if (!isSessionViewCommitted.value) {
-    return []
-  }
-  const streamId =
-    isCurrentSessionStreaming.value && hasInlineStreamingTarget.value
-      ? messageStore.currentStreamMessageId
-      : null
-
-  const msgs: DisplayMessage[] = []
-  const activeMessageIds = new Set<string>()
-  const cache = messageStore.messageCache
-
-  for (const id of messageStore.messageIds) {
-    if (streamId && id === streamId) {
-      continue
-    }
-    const message = cache.get(id)
-    if (!message || message.sessionId !== props.sessionId) continue
-    activeMessageIds.add(message.id)
-    const displayMessage = toDisplayMessage(message)
-    if (shouldRenderDisplayMessage(displayMessage)) {
-      msgs.push(displayMessage)
-    }
-  }
-
-  for (const cachedId of displayMessageCache.keys()) {
-    if (!activeMessageIds.has(cachedId) && cachedId !== streamId) {
-      displayMessageCache.delete(cachedId)
-    }
-  }
-
-  return msgs
-})
-
-/** High-frequency streaming row + pending placeholder only. */
-const streamingDisplayTail = computed(() => {
-  void messageStore.streamRevision
-  if (!isSessionViewCommitted.value) {
-    return []
-  }
-  const msgs: DisplayMessage[] = []
-
-  // Single-track: stream blocks are folded into the message record in place, so the
-  // generating message is the same id/node through completion (no flash).
-  if (isCurrentSessionStreaming.value && hasInlineStreamingTarget.value) {
-    const streamId = messageStore.currentStreamMessageId
-    const record = streamId ? messageStore.messageCache.get(streamId) : undefined
-    if (record) {
-      const displayMessage = toDisplayMessage(record)
-      if (shouldRenderDisplayMessage(displayMessage)) {
-        msgs.push(displayMessage)
-      }
-    }
-  } else if (
-    isCurrentSessionStreaming.value &&
-    messageStore.streamingBlocks.length > 0 &&
-    !hasInlineStreamingTarget.value &&
-    !ephemeralRateLimitBlock.value
-  ) {
-    msgs.push(toStreamingMessage(messageStore.streamingBlocks, messageStore.currentStreamMessageId))
-  }
-
-  if (shouldShowPendingAssistantPlaceholder.value && pendingAssistantPlaceholder.value) {
-    msgs.push(toStreamingMessage([], pendingAssistantPlaceholder.value.id))
-  } else if (shouldShowGeneratingAssistantPlaceholder.value) {
-    msgs.push(toStreamingMessage([], `__pending_assistant_generating_${props.sessionId}`))
-  }
-
-  return msgs
-})
-
-const displayMessages = computed(() => {
-  const stable = stableDisplayMessages.value
-  const tail = streamingDisplayTail.value
-  if (tail.length === 0) {
-    return stable
-  }
-
-  const streamId = messageStore.currentStreamMessageId
-  // Common path: virtual/fallback streaming rows and pending placeholders append at end.
-  if (!(streamId && hasInlineStreamingTarget.value && tail[0]?.id === streamId)) {
-    return stable.concat(tail)
-  }
-
-  // Re-insert the in-flight row at its messageIds order while reusing stable objects.
-  const stableById = new Map(stable.map((message) => [message.id, message]))
-  const ordered: DisplayMessage[] = []
-  for (const id of messageStore.messageIds) {
-    if (id === streamId) {
-      ordered.push(tail[0])
-      continue
-    }
-    const item = stableById.get(id)
-    if (item) {
-      ordered.push(item)
-    }
-  }
-  for (let i = 1; i < tail.length; i += 1) {
-    ordered.push(tail[i])
-  }
-  return ordered
+const {
+  displayMessages,
+  ephemeralRateLimitBlock,
+  ephemeralRateLimitMessageId,
+  hasFirstStreamingContent,
+  hasInlineStreamingTarget,
+  pendingAssistantPlaceholder,
+  createPendingAssistantPlaceholder,
+  clearPendingAssistantPlaceholder,
+  resetForSessionChange: resetDisplayMessagesForSessionChange
+} = useDisplayMessages({
+  sessionId: () => props.sessionId,
+  messageStore,
+  sessionStore,
+  modelStore,
+  isGenerating,
+  isSessionViewCommitted,
+  isCurrentSessionStreaming
 })
 
 const messageWindow = useMessageWindow({
@@ -2116,195 +1699,22 @@ const pendingInteractions = computed<PendingInteractionView[]>(() => {
 
 const activePendingInteraction = computed(() => pendingInteractions.value[0] ?? null)
 
-function readSessionStatus(sessionId: string): 'working' | 'completed' | 'error' | 'none' | null {
-  if (sessionStore.activeSession?.id === sessionId) {
-    return sessionStore.activeSession.status
-  }
-
-  return sessionStore.sessions.find((session) => session.id === sessionId)?.status ?? null
-}
-
-function hasPendingInteractionForSession(sessionId: string): boolean {
-  return pendingInteractions.value.some((interaction) => interaction.sessionId === sessionId)
-}
-
-function isSessionPlanActive(sessionId: string): boolean {
-  if (sessionId === props.sessionId && isCurrentSessionStreaming.value) {
-    return true
-  }
-
-  return readSessionStatus(sessionId) === 'working'
-}
-
-function isPlanFloatLingerActive(sessionId: string): boolean {
-  return planFloatLingerBySession.value[sessionId] === true
-}
-
-function setPlanFloatLingerActive(sessionId: string, active: boolean): void {
-  const current = planFloatLingerBySession.value[sessionId] === true
-  if (current === active) {
-    return
-  }
-
-  const next = { ...planFloatLingerBySession.value }
-  if (active) {
-    next[sessionId] = true
-  } else {
-    delete next[sessionId]
-  }
-  planFloatLingerBySession.value = next
-}
-
-function shouldShowPlanSnapshotForSession(sessionId: string): boolean {
-  return (
-    isSessionPlanActive(sessionId) ||
-    hasPendingInteractionForSession(sessionId) ||
-    isPlanFloatLingerActive(sessionId)
-  )
-}
-
-const latestPlanSnapshot = computed(() => {
-  if (!shouldShowPlanSnapshotForSession(props.sessionId)) {
-    return null
-  }
-
-  if (!agentPlanStore.isVisible(props.sessionId)) {
-    return null
-  }
-
-  const snapshot = agentPlanStore.snapshots[props.sessionId]
-  if (!snapshot || snapshot.plan.length === 0) {
-    return null
-  }
-  return snapshot
-})
-
-const isPlanFloatCollapsed = computed(() => agentPlanStore.isCollapsed(props.sessionId))
-
-function cancelPlanSnapshotClearTimer(sessionId: string) {
-  const timer = planSnapshotClearTimers.get(sessionId)
-  if (timer === undefined) {
-    return
-  }
-
-  window.clearTimeout(timer)
-  planSnapshotClearTimers.delete(sessionId)
-}
-
-function cancelAllPlanSnapshotClearTimers() {
-  for (const timer of planSnapshotClearTimers.values()) {
-    window.clearTimeout(timer)
-  }
-  planSnapshotClearTimers.clear()
-}
-
-function canLingerPlanSnapshot(sessionId: string): boolean {
-  const snapshot = agentPlanStore.snapshots[sessionId]
-  if (!snapshot || snapshot.plan.length === 0) {
-    return false
-  }
-
-  return (
-    Boolean(snapshot.terminalReason) || snapshot.plan.every((entry) => entry.status === 'completed')
-  )
-}
-
-function scheduleInactivePlanSnapshotClear(sessionId: string = props.sessionId) {
-  const snapshot = agentPlanStore.snapshots[sessionId]
-  if (!snapshot) {
-    cancelPlanSnapshotClearTimer(sessionId)
-    setPlanFloatLingerActive(sessionId, false)
-    return
-  }
-
-  if (isSessionPlanActive(sessionId) || hasPendingInteractionForSession(sessionId)) {
-    cancelPlanSnapshotClearTimer(sessionId)
-    setPlanFloatLingerActive(sessionId, false)
-    return
-  }
-
-  cancelPlanSnapshotClearTimer(sessionId)
-
-  if (!canLingerPlanSnapshot(sessionId)) {
-    setPlanFloatLingerActive(sessionId, false)
-    return
-  }
-
-  setPlanFloatLingerActive(sessionId, true)
-  const timer = window.setTimeout(() => {
-    planSnapshotClearTimers.delete(sessionId)
-    if (!isSessionPlanActive(sessionId) && !hasPendingInteractionForSession(sessionId)) {
-      agentPlanStore.clearSnapshot(sessionId)
-      setPlanFloatLingerActive(sessionId, false)
-    }
-  }, PLAN_FLOAT_CLEAR_DELAY_MS)
-  planSnapshotClearTimers.set(sessionId, timer)
-}
-
-function resetPlanSnapshotLifecycle(sessionId: string): void {
-  cancelPlanSnapshotClearTimer(sessionId)
-  setPlanFloatLingerActive(sessionId, false)
-}
-
-function beginPlanTurn(sessionId: string): void {
-  resetPlanSnapshotLifecycle(sessionId)
-  agentPlanStore.beginTurn(sessionId)
-}
-
-function clearPlanSnapshotForDeletedMessage(sessionId: string, messageId: string): void {
-  const snapshot = agentPlanStore.snapshots[sessionId]
-  if (snapshot?.messageId !== messageId) {
-    return
-  }
-
-  resetPlanSnapshotLifecycle(sessionId)
-  agentPlanStore.clearSnapshot(sessionId)
-}
-
-const planSnapshotLifecycleKey = computed(() =>
-  Object.values(agentPlanStore.snapshots)
-    .map((snapshot) => {
-      const terminal = snapshot.terminalReason ?? ''
-      const statuses = snapshot.plan.map((entry) => entry.status).join(',')
-      return `${snapshot.sessionId}:${snapshot.messageId ?? ''}:${snapshot.revision}:${terminal}:${statuses}`
-    })
-    .join('|')
-)
-
-const sessionStatusLifecycleKey = computed(() => {
-  const entries = sessionStore.sessions.map((session) => `${session.id}:${session.status}`)
-  const active = sessionStore.activeSession
-  if (active) {
-    entries.push(`${active.id}:${active.status}`)
-  }
-  entries.push(
-    `${props.sessionId}:${isCurrentSessionStreaming.value ? 'streaming' : 'not-streaming'}`
-  )
-  return entries.sort().join('|')
+const {
+  latestPlanSnapshot,
+  isPlanFloatCollapsed,
+  beginPlanTurn,
+  clearPlanSnapshotForDeletedMessage,
+  scheduleInactivePlanSnapshotClear,
+  cancelAllPlanSnapshotClearTimers,
+  onDismissPlanFloat
+} = usePlanFloatLifecycle({
+  sessionId: () => props.sessionId,
+  agentPlanStore,
+  sessionStore,
+  isCurrentSessionStreaming,
+  pendingInteractions
 })
 
-const pendingInteractionLifecycleKey = computed(() =>
-  pendingInteractions.value
-    .map(
-      (interaction) => `${interaction.sessionId}:${interaction.messageId}:${interaction.toolCallId}`
-    )
-    .join('|')
-)
-
-function syncPlanSnapshotLifecycle(): void {
-  for (const sessionId of Object.keys(agentPlanStore.snapshots)) {
-    scheduleInactivePlanSnapshotClear(sessionId)
-  }
-}
-
-watch(
-  [planSnapshotLifecycleKey, sessionStatusLifecycleKey, pendingInteractionLifecycleKey],
-  () => {
-    syncPlanSnapshotLifecycle()
-  },
-  { flush: 'post' }
-)
-
 const hasInputText = computed(() => Boolean(message.value.trim()))
 const hasAttachments = computed(() => attachedFiles.value.length > 0)
 const hasDraftInput = computed(() => hasInputText.value || hasAttachments.value)
diff --git a/src/renderer/src/pages/chat-page/useDisplayMessages.ts b/src/renderer/src/pages/chat-page/useDisplayMessages.ts
new file mode 100644
index 0000000000..dd4bc7483f
--- /dev/null
+++ b/src/renderer/src/pages/chat-page/useDisplayMessages.ts
@@ -0,0 +1,494 @@
+import { computed, ref, watch, type ComputedRef, type Ref } from 'vue'
+import type { useMessageStore } from '@/stores/ui/message'
+import type { useSessionStore } from '@/stores/ui/session'
+import type { useModelStore } from '@/stores/modelStore'
+import type {
+  DisplayAssistantMessageBlock,
+  DisplayMessage,
+  DisplayMessageUsage
+} from '@/components/chat/messageListItems'
+import {
+  filterRenderableAssistantBlocks,
+  hasRenderableAssistantBlocks
+} from '@/components/chat/messageListItems'
+import type { ChatMessageRecord, MessageMetadata } from '@shared/types/agent-interface'
+
+type MessageStore = ReturnType<typeof useMessageStore>
+type SessionStore = ReturnType<typeof useSessionStore>
+type ModelStore = ReturnType<typeof useModelStore>
+
+const RATE_LIMIT_STREAM_MESSAGE_PREFIX = '__rate_limit__:'
+
+type UseDisplayMessagesOptions = {
+  sessionId: () => string
+  messageStore: MessageStore
+  sessionStore: SessionStore
+  modelStore: ModelStore
+  isGenerating: Ref<boolean>
+  isSessionViewCommitted: ComputedRef<boolean>
+  isCurrentSessionStreaming: ComputedRef<boolean>
+}
+
+/**
+ * Owns everything that turns persisted + streaming message state into the ordered
+ * `DisplayMessage[]` the list renders:
+ *
+ * - `toDisplayMessage` conversion with an identity cache so token updates don't
+ *   rebuild settled rows.
+ * - Stable history list (reads only `lastPersistedRevision`) vs. the high-frequency
+ *   streaming tail (reads `streamRevision`) — kept separate so long sessions don't
+ *   rebuild every row on each token.
+ * - The pending-assistant placeholder state machine and its renderKey handoff, which
+ *   hands the placeholder's identity to the real streaming row so completion patches
+ *   the same DOM node instead of unmount/remount.
+ */
+export function useDisplayMessages(options: UseDisplayMessagesOptions) {
+  const { messageStore, sessionStore, modelStore, isGenerating } = options
+  const { isSessionViewCommitted, isCurrentSessionStreaming } = options
+  const currentSessionId = () => options.sessionId()
+
+  const pendingAssistantPlaceholder = ref<{
+    id: string
+    sessionId: string
+    baselineAssistantMessageIds: Set<string>
+    baselineMessageOrderSeq: number
+    baselineCreatedAt: number
+  } | null>(null)
+  const assistantRenderKeyByMessageId = ref<Record<string, string>>({})
+  let pendingAssistantPlaceholderSeq = 0
+
+  const displayMessageCache = new Map<
+    string,
+    {
+      updatedAt: number
+      content: ChatMessageRecord['content']
+      metadata: ChatMessageRecord['metadata']
+      modelId: string
+      providerId: string
+      status: DisplayMessage['status']
+      renderKey?: string
+      message: DisplayMessage
+    }
+  >()
+
+  function resolveAssistantModelName(modelId: string): string {
+    if (!modelId) {
+      return 'Assistant'
+    }
+    const found = modelStore.findModelByIdOrName(modelId)
+    return found?.model?.name || modelId
+  }
+
+  function buildUsage(metadata: MessageMetadata): DisplayMessageUsage {
+    return {
+      context_usage: 0,
+      tokens_per_second: metadata.tokensPerSecond ?? 0,
+      total_tokens: metadata.totalTokens ?? 0,
+      generation_time: metadata.generationTime ?? 0,
+      first_token_time: metadata.firstTokenTime ?? 0,
+      reasoning_start_time: metadata.reasoningStartTime ?? 0,
+      reasoning_end_time: metadata.reasoningEndTime ?? 0,
+      input_tokens: metadata.inputTokens ?? 0,
+      output_tokens: metadata.outputTokens ?? 0
+    }
+  }
+
+  function toDisplayMessage(record: ChatMessageRecord): DisplayMessage {
+    const metadata = messageStore.getMessageMetadata(record)
+    const modelId = metadata.model || sessionStore.activeSession?.modelId || ''
+    const providerId = metadata.provider || sessionStore.activeSession?.providerId || ''
+    const cached = displayMessageCache.get(record.id)
+    if (
+      cached &&
+      cached.updatedAt === record.updatedAt &&
+      cached.content === record.content &&
+      cached.metadata === record.metadata &&
+      cached.modelId === modelId &&
+      cached.providerId === providerId &&
+      cached.status === record.status &&
+      cached.renderKey === assistantRenderKeyByMessageId.value[record.id]
+    ) {
+      return cached.message
+    }
+
+    const modelName = record.role === 'assistant' ? resolveAssistantModelName(modelId) : ''
+    const baseMessage = {
+      id: record.id,
+      timestamp: record.createdAt,
+      updatedAt: record.updatedAt,
+      avatar: '',
+      name: record.role === 'user' ? 'You' : 'Assistant',
+      model_name: modelName,
+      model_id: modelId,
+      model_provider: providerId,
+      status: record.status,
+      error: '',
+      usage: buildUsage(metadata),
+      conversationId: record.sessionId,
+      is_variant: 0,
+      orderSeq: record.orderSeq,
+      messageType: metadata.messageType === 'compaction' ? 'compaction' : 'normal',
+      compactionStatus: metadata.compactionStatus,
+      summaryUpdatedAt: metadata.summaryUpdatedAt ?? null
+    } as const
+
+    const streamingRenderKey = assistantRenderKeyByMessageId.value[record.id]
+    const nextMessage =
+      record.role === 'assistant'
+        ? ({
+            ...baseMessage,
+            ...(streamingRenderKey ? { renderKey: streamingRenderKey } : {}),
+            role: 'assistant',
+            content: filterRenderableAssistantBlocks(messageStore.getAssistantMessageBlocks(record))
+          } as DisplayMessage)
+        : ({
+            ...baseMessage,
+            role: 'user',
+            content: messageStore.getUserMessageContent(record)
+          } as DisplayMessage)
+
+    displayMessageCache.set(record.id, {
+      updatedAt: record.updatedAt,
+      content: record.content,
+      metadata: record.metadata,
+      modelId,
+      providerId,
+      status: record.status,
+      renderKey: streamingRenderKey,
+      message: nextMessage
+    })
+
+    return nextMessage
+  }
+
+  // Build a streaming assistant message from live blocks
+  function toStreamingMessage(
+    blocks: DisplayAssistantMessageBlock[],
+    messageId?: string | null
+  ): DisplayMessage {
+    const modelId = sessionStore.activeSession?.modelId ?? ''
+    const now = Date.now()
+    const renderableBlocks = filterRenderableAssistantBlocks(blocks)
+    return {
+      // Key the streaming row by the real message id when we have one, so that when
+      // the persisted copy arrives at stream end Vue patches the SAME node in place
+      // (markdown DOM reused) instead of unmount/remount — no completion flash.
+      // Falls back to a synthetic id only when the backend hasn't assigned one yet.
+      id: messageId ?? '__streaming__',
+      content: renderableBlocks,
+      role: 'assistant',
+      timestamp: now,
+      updatedAt: now,
+      avatar: '',
+      name: 'Assistant',
+      model_name: resolveAssistantModelName(modelId),
+      model_id: modelId,
+      model_provider: sessionStore.activeSession?.providerId ?? '',
+      status: 'pending',
+      error: '',
+      usage: buildUsage({}),
+      conversationId: currentSessionId(),
+      is_variant: 0,
+      orderSeq: Number.MAX_SAFE_INTEGER
+    }
+  }
+
+  function shouldRenderDisplayMessage(message: DisplayMessage): boolean {
+    if (message.role !== 'assistant') {
+      return true
+    }
+
+    if (message.messageType === 'compaction') {
+      return true
+    }
+
+    if (message.status === 'pending') {
+      return true
+    }
+
+    return hasRenderableAssistantBlocks(message.content)
+  }
+
+  const hasInlineStreamingTarget = computed(() => {
+    if (!isCurrentSessionStreaming.value) return false
+    const messageId = messageStore.currentStreamMessageId
+    if (!messageId) return false
+    return messageStore.messageCache.get(messageId)?.sessionId === currentSessionId()
+  })
+  const hasFirstStreamingContent = computed(
+    () => messageStore.streamingBlocks.length > 0 && hasInlineStreamingTarget.value
+  )
+
+  const ephemeralRateLimitMessageId = computed(() => {
+    const messageId = messageStore.currentStreamMessageId
+    if (
+      !isCurrentSessionStreaming.value ||
+      !messageId ||
+      !messageId.startsWith(RATE_LIMIT_STREAM_MESSAGE_PREFIX)
+    ) {
+      return null
+    }
+
+    return messageId
+  })
+
+  const ephemeralRateLimitBlock = computed<DisplayAssistantMessageBlock | null>(() => {
+    if (!ephemeralRateLimitMessageId.value || messageStore.streamingBlocks.length === 0) {
+      return null
+    }
+
+    const [firstBlock] = messageStore.streamingBlocks as DisplayAssistantMessageBlock[]
+    if (
+      messageStore.streamingBlocks.length !== 1 ||
+      firstBlock?.type !== 'action' ||
+      firstBlock.action_type !== 'rate_limit'
+    ) {
+      return null
+    }
+
+    return firstBlock
+  })
+
+  const hasNewAssistantMessageAfterPendingPlaceholder = computed(() => {
+    const pending = pendingAssistantPlaceholder.value
+    if (!pending || pending.sessionId !== currentSessionId()) return false
+
+    return messageStore.messages.some(
+      (message) =>
+        message.role === 'assistant' &&
+        !pending.baselineAssistantMessageIds.has(message.id) &&
+        isMessageAfterPendingAssistantBaseline(message, pending)
+    )
+  })
+
+  const shouldShowPendingAssistantPlaceholder = computed(() => {
+    const pending = pendingAssistantPlaceholder.value
+    return Boolean(
+      pending &&
+        pending.sessionId === currentSessionId() &&
+        !hasFirstStreamingContent.value &&
+        !hasNewAssistantMessageAfterPendingPlaceholder.value &&
+        !ephemeralRateLimitBlock.value
+    )
+  })
+
+  const hasPendingAssistantMessage = computed(() =>
+    messageStore.messages.some(
+      (message) => message.role === 'assistant' && message.status === 'pending'
+    )
+  )
+
+  const shouldShowGeneratingAssistantPlaceholder = computed(
+    () =>
+      isGenerating.value &&
+      !shouldShowPendingAssistantPlaceholder.value &&
+      !hasFirstStreamingContent.value &&
+      !hasPendingAssistantMessage.value &&
+      !ephemeralRateLimitBlock.value
+  )
+
+  watch(
+    () => hasFirstStreamingContent.value || hasNewAssistantMessageAfterPendingPlaceholder.value,
+    (shouldClearPendingAssistant) => {
+      if (shouldClearPendingAssistant) {
+        bindPendingAssistantRenderKey()
+        pendingAssistantPlaceholder.value = null
+      }
+    }
+  )
+
+  function createPendingAssistantPlaceholder(sessionId: string): string {
+    const id = `__pending_assistant_${Date.now()}_${++pendingAssistantPlaceholderSeq}`
+    const loadedMessages = messageStore.messages
+    const baselineAssistantMessageIds = new Set(
+      loadedMessages.filter((message) => message.role === 'assistant').map((message) => message.id)
+    )
+    const baselineMessageOrderSeq = Math.max(
+      Number.NEGATIVE_INFINITY,
+      ...loadedMessages.map((message) =>
+        Number.isFinite(message.orderSeq) ? message.orderSeq : Number.NEGATIVE_INFINITY
+      )
+    )
+    pendingAssistantPlaceholder.value = {
+      id,
+      sessionId,
+      baselineAssistantMessageIds,
+      baselineMessageOrderSeq,
+      baselineCreatedAt: Date.now()
+    }
+    return id
+  }
+
+  function isMessageAfterPendingAssistantBaseline(
+    message: ChatMessageRecord,
+    pending: NonNullable<typeof pendingAssistantPlaceholder.value>
+  ): boolean {
+    if (Number.isFinite(pending.baselineMessageOrderSeq) && Number.isFinite(message.orderSeq)) {
+      return message.orderSeq > pending.baselineMessageOrderSeq
+    }
+
+    return message.createdAt > pending.baselineCreatedAt
+  }
+
+  function clearPendingAssistantPlaceholder(id?: string): void {
+    if (!id || pendingAssistantPlaceholder.value?.id === id) {
+      pendingAssistantPlaceholder.value = null
+    }
+  }
+
+  function bindPendingAssistantRenderKey(): void {
+    const pending = pendingAssistantPlaceholder.value
+    const streamMessageId = messageStore.currentStreamMessageId
+    if (
+      !pending ||
+      pending.sessionId !== currentSessionId() ||
+      !streamMessageId ||
+      !hasInlineStreamingTarget.value ||
+      assistantRenderKeyByMessageId.value[streamMessageId] === pending.id
+    ) {
+      return
+    }
+    assistantRenderKeyByMessageId.value = {
+      ...assistantRenderKeyByMessageId.value,
+      [streamMessageId]: pending.id
+    }
+  }
+
+  watch(
+    () => [messageStore.currentStreamMessageId, hasInlineStreamingTarget.value] as const,
+    bindPendingAssistantRenderKey
+  )
+
+  /**
+   * Stable history list: intentionally does NOT read streamRevision / streamingBlocks,
+   * so token-level updates do not rebuild every display message in long sessions.
+   * The in-flight assistant row is owned by streamingDisplayTail instead.
+   */
+  const stableDisplayMessages = computed(() => {
+    void messageStore.lastPersistedRevision
+    if (!isSessionViewCommitted.value) {
+      return []
+    }
+    const streamId =
+      isCurrentSessionStreaming.value && hasInlineStreamingTarget.value
+        ? messageStore.currentStreamMessageId
+        : null
+
+    const msgs: DisplayMessage[] = []
+    const activeMessageIds = new Set<string>()
+    const cache = messageStore.messageCache
+
+    for (const id of messageStore.messageIds) {
+      if (streamId && id === streamId) {
+        continue
+      }
+      const message = cache.get(id)
+      if (!message || message.sessionId !== currentSessionId()) continue
+      activeMessageIds.add(message.id)
+      const displayMessage = toDisplayMessage(message)
+      if (shouldRenderDisplayMessage(displayMessage)) {
+        msgs.push(displayMessage)
+      }
+    }
+
+    for (const cachedId of displayMessageCache.keys()) {
+      if (!activeMessageIds.has(cachedId) && cachedId !== streamId) {
+        displayMessageCache.delete(cachedId)
+      }
+    }
+
+    return msgs
+  })
+
+  /** High-frequency streaming row + pending placeholder only. */
+  const streamingDisplayTail = computed(() => {
+    void messageStore.streamRevision
+    if (!isSessionViewCommitted.value) {
+      return []
+    }
+    const msgs: DisplayMessage[] = []
+
+    // Single-track: stream blocks are folded into the message record in place, so the
+    // generating message is the same id/node through completion (no flash).
+    if (isCurrentSessionStreaming.value && hasInlineStreamingTarget.value) {
+      const streamId = messageStore.currentStreamMessageId
+      const record = streamId ? messageStore.messageCache.get(streamId) : undefined
+      if (record) {
+        const displayMessage = toDisplayMessage(record)
+        if (shouldRenderDisplayMessage(displayMessage)) {
+          msgs.push(displayMessage)
+        }
+      }
+    } else if (
+      isCurrentSessionStreaming.value &&
+      messageStore.streamingBlocks.length > 0 &&
+      !hasInlineStreamingTarget.value &&
+      !ephemeralRateLimitBlock.value
+    ) {
+      msgs.push(
+        toStreamingMessage(
+          messageStore.streamingBlocks as DisplayAssistantMessageBlock[],
+          messageStore.currentStreamMessageId
+        )
+      )
+    }
+
+    if (shouldShowPendingAssistantPlaceholder.value && pendingAssistantPlaceholder.value) {
+      msgs.push(toStreamingMessage([], pendingAssistantPlaceholder.value.id))
+    } else if (shouldShowGeneratingAssistantPlaceholder.value) {
+      msgs.push(toStreamingMessage([], `__pending_assistant_generating_${currentSessionId()}`))
+    }
+
+    return msgs
+  })
+
+  const displayMessages = computed(() => {
+    const stable = stableDisplayMessages.value
+    const tail = streamingDisplayTail.value
+    if (tail.length === 0) {
+      return stable
+    }
+
+    const streamId = messageStore.currentStreamMessageId
+    // Common path: virtual/fallback streaming rows and pending placeholders append at end.
+    if (!(streamId && hasInlineStreamingTarget.value && tail[0]?.id === streamId)) {
+      return stable.concat(tail)
+    }
+
+    // Re-insert the in-flight row at its messageIds order while reusing stable objects.
+    const stableById = new Map(stable.map((message) => [message.id, message]))
+    const ordered: DisplayMessage[] = []
+    for (const id of messageStore.messageIds) {
+      if (id === streamId) {
+        ordered.push(tail[0])
+        continue
+      }
+      const item = stableById.get(id)
+      if (item) {
+        ordered.push(item)
+      }
+    }
+    for (let i = 1; i < tail.length; i += 1) {
+      ordered.push(tail[i])
+    }
+    return ordered
+  })
+
+  function resetForSessionChange(): void {
+    displayMessageCache.clear()
+    assistantRenderKeyByMessageId.value = {}
+    pendingAssistantPlaceholder.value = null
+  }
+
+  return {
+    displayMessages,
+    ephemeralRateLimitBlock,
+    ephemeralRateLimitMessageId,
+    hasFirstStreamingContent,
+    hasInlineStreamingTarget,
+    pendingAssistantPlaceholder,
+    createPendingAssistantPlaceholder,
+    clearPendingAssistantPlaceholder,
+    resetForSessionChange
+  }
+}
diff --git a/src/renderer/src/pages/chat-page/usePlanFloatLifecycle.ts b/src/renderer/src/pages/chat-page/usePlanFloatLifecycle.ts
new file mode 100644
index 0000000000..b705a14c74
--- /dev/null
+++ b/src/renderer/src/pages/chat-page/usePlanFloatLifecycle.ts
@@ -0,0 +1,244 @@
+import { computed, watch, type ComputedRef, type Ref } from 'vue'
+import type { useAgentPlanStore } from '@/stores/ui/agentPlan'
+import type { useSessionStore } from '@/stores/ui/session'
+
+type AgentPlanStore = ReturnType<typeof useAgentPlanStore>
+type SessionStore = ReturnType<typeof useSessionStore>
+
+type PendingInteractionLike = {
+  sessionId: string
+  messageId: string
+  toolCallId: string
+}
+
+const PLAN_FLOAT_CLEAR_DELAY_MS = 1200
+
+type UsePlanFloatLifecycleOptions = {
+  sessionId: () => string
+  agentPlanStore: AgentPlanStore
+  sessionStore: SessionStore
+  isCurrentSessionStreaming: Ref<boolean>
+  pendingInteractions: ComputedRef<PendingInteractionLike[]>
+}
+
+/**
+ * Owns the plan-float snapshot lifecycle across sessions: when a plan snapshot
+ * should be visible, when it may linger after completion, and the delayed clear
+ * that fires once a session is no longer active and has no pending interaction.
+ *
+ * The linger map and clear timers are keyed per session so multiple sessions can
+ * hold snapshots simultaneously without racing each other's timers.
+ */
+export function usePlanFloatLifecycle(options: UsePlanFloatLifecycleOptions) {
+  const { agentPlanStore, sessionStore, isCurrentSessionStreaming, pendingInteractions } = options
+  const currentSessionId = () => options.sessionId()
+
+  const planFloatLingerBySession: Record<string, boolean> = {}
+  const planSnapshotClearTimers = new Map<string, number>()
+
+  function readSessionStatus(
+    sessionId: string
+  ): 'working' | 'completed' | 'error' | 'none' | null {
+    if (sessionStore.activeSession?.id === sessionId) {
+      return sessionStore.activeSession.status
+    }
+
+    return sessionStore.sessions.find((session) => session.id === sessionId)?.status ?? null
+  }
+
+  function hasPendingInteractionForSession(sessionId: string): boolean {
+    return pendingInteractions.value.some((interaction) => interaction.sessionId === sessionId)
+  }
+
+  function isSessionPlanActive(sessionId: string): boolean {
+    if (sessionId === currentSessionId() && isCurrentSessionStreaming.value) {
+      return true
+    }
+
+    return readSessionStatus(sessionId) === 'working'
+  }
+
+  function isPlanFloatLingerActive(sessionId: string): boolean {
+    return planFloatLingerBySession[sessionId] === true
+  }
+
+  function setPlanFloatLingerActive(sessionId: string, active: boolean): void {
+    const current = planFloatLingerBySession[sessionId] === true
+    if (current === active) {
+      return
+    }
+
+    if (active) {
+      planFloatLingerBySession[sessionId] = true
+    } else {
+      delete planFloatLingerBySession[sessionId]
+    }
+  }
+
+  function shouldShowPlanSnapshotForSession(sessionId: string): boolean {
+    return (
+      isSessionPlanActive(sessionId) ||
+      hasPendingInteractionForSession(sessionId) ||
+      isPlanFloatLingerActive(sessionId)
+    )
+  }
+
+  const latestPlanSnapshot = computed(() => {
+    const sessionId = currentSessionId()
+    if (!shouldShowPlanSnapshotForSession(sessionId)) {
+      return null
+    }
+
+    if (!agentPlanStore.isVisible(sessionId)) {
+      return null
+    }
+
+    const snapshot = agentPlanStore.snapshots[sessionId]
+    if (!snapshot || snapshot.plan.length === 0) {
+      return null
+    }
+    return snapshot
+  })
+
+  const isPlanFloatCollapsed = computed(() => agentPlanStore.isCollapsed(currentSessionId()))
+
+  function cancelPlanSnapshotClearTimer(sessionId: string) {
+    const timer = planSnapshotClearTimers.get(sessionId)
+    if (timer === undefined) {
+      return
+    }
+
+    window.clearTimeout(timer)
+    planSnapshotClearTimers.delete(sessionId)
+  }
+
+  function cancelAllPlanSnapshotClearTimers() {
+    for (const timer of planSnapshotClearTimers.values()) {
+      window.clearTimeout(timer)
+    }
+    planSnapshotClearTimers.clear()
+  }
+
+  function canLingerPlanSnapshot(sessionId: string): boolean {
+    const snapshot = agentPlanStore.snapshots[sessionId]
+    if (!snapshot || snapshot.plan.length === 0) {
+      return false
+    }
+
+    return (
+      Boolean(snapshot.terminalReason) ||
+      snapshot.plan.every((entry) => entry.status === 'completed')
+    )
+  }
+
+  function scheduleInactivePlanSnapshotClear(sessionId: string = currentSessionId()) {
+    const snapshot = agentPlanStore.snapshots[sessionId]
+    if (!snapshot) {
+      cancelPlanSnapshotClearTimer(sessionId)
+      setPlanFloatLingerActive(sessionId, false)
+      return
+    }
+
+    if (isSessionPlanActive(sessionId) || hasPendingInteractionForSession(sessionId)) {
+      cancelPlanSnapshotClearTimer(sessionId)
+      setPlanFloatLingerActive(sessionId, false)
+      return
+    }
+
+    cancelPlanSnapshotClearTimer(sessionId)
+
+    if (!canLingerPlanSnapshot(sessionId)) {
+      setPlanFloatLingerActive(sessionId, false)
+      return
+    }
+
+    setPlanFloatLingerActive(sessionId, true)
+    const timer = window.setTimeout(() => {
+      planSnapshotClearTimers.delete(sessionId)
+      if (!isSessionPlanActive(sessionId) && !hasPendingInteractionForSession(sessionId)) {
+        agentPlanStore.clearSnapshot(sessionId)
+        setPlanFloatLingerActive(sessionId, false)
+      }
+    }, PLAN_FLOAT_CLEAR_DELAY_MS)
+    planSnapshotClearTimers.set(sessionId, timer)
+  }
+
+  function resetPlanSnapshotLifecycle(sessionId: string): void {
+    cancelPlanSnapshotClearTimer(sessionId)
+    setPlanFloatLingerActive(sessionId, false)
+  }
+
+  function beginPlanTurn(sessionId: string): void {
+    resetPlanSnapshotLifecycle(sessionId)
+    agentPlanStore.beginTurn(sessionId)
+  }
+
+  function clearPlanSnapshotForDeletedMessage(sessionId: string, messageId: string): void {
+    const snapshot = agentPlanStore.snapshots[sessionId]
+    if (snapshot?.messageId !== messageId) {
+      return
+    }
+
+    resetPlanSnapshotLifecycle(sessionId)
+    agentPlanStore.clearSnapshot(sessionId)
+  }
+
+  function onDismissPlanFloat() {
+    agentPlanStore.dismiss(currentSessionId())
+  }
+
+  const planSnapshotLifecycleKey = computed(() =>
+    Object.values(agentPlanStore.snapshots)
+      .map((snapshot) => {
+        const terminal = snapshot.terminalReason ?? ''
+        const statuses = snapshot.plan.map((entry) => entry.status).join(',')
+        return `${snapshot.sessionId}:${snapshot.messageId ?? ''}:${snapshot.revision}:${terminal}:${statuses}`
+      })
+      .join('|')
+  )
+
+  const sessionStatusLifecycleKey = computed(() => {
+    const entries = sessionStore.sessions.map((session) => `${session.id}:${session.status}`)
+    const active = sessionStore.activeSession
+    if (active) {
+      entries.push(`${active.id}:${active.status}`)
+    }
+    entries.push(
+      `${currentSessionId()}:${isCurrentSessionStreaming.value ? 'streaming' : 'not-streaming'}`
+    )
+    return entries.sort().join('|')
+  })
+
+  const pendingInteractionLifecycleKey = computed(() =>
+    pendingInteractions.value
+      .map(
+        (interaction) =>
+          `${interaction.sessionId}:${interaction.messageId}:${interaction.toolCallId}`
+      )
+      .join('|')
+  )
+
+  function syncPlanSnapshotLifecycle(): void {
+    for (const sessionId of Object.keys(agentPlanStore.snapshots)) {
+      scheduleInactivePlanSnapshotClear(sessionId)
+    }
+  }
+
+  watch(
+    [planSnapshotLifecycleKey, sessionStatusLifecycleKey, pendingInteractionLifecycleKey],
+    () => {
+      syncPlanSnapshotLifecycle()
+    },
+    { flush: 'post' }
+  )
+
+  return {
+    latestPlanSnapshot,
+    isPlanFloatCollapsed,
+    beginPlanTurn,
+    clearPlanSnapshotForDeletedMessage,
+    scheduleInactivePlanSnapshotClear,
+    cancelAllPlanSnapshotClearTimers,
+    onDismissPlanFloat
+  }
+}

From 553b4b821b78702dfd7d7547243a103bdc637cba Mon Sep 17 00:00:00 2001
From: zhangmo8 <zhangmo8@users.noreply.github.com>
Date: Thu, 16 Jul 2026 13:28:48 +0800
Subject: [PATCH 02/14] refactor(chat): extract useChatSearch composable

---
 src/renderer/src/pages/ChatPage.vue           | 226 +++-------------
 .../src/pages/chat-page/useChatSearch.ts      | 252 ++++++++++++++++++
 .../src/pages/chat-page/useDisplayMessages.ts |   8 +-
 .../pages/chat-page/usePlanFloatLifecycle.ts  |   4 +-
 4 files changed, 288 insertions(+), 202 deletions(-)
 create mode 100644 src/renderer/src/pages/chat-page/useChatSearch.ts

diff --git a/src/renderer/src/pages/ChatPage.vue b/src/renderer/src/pages/ChatPage.vue
index b8c0f595bd..9d719b57d9 100644
--- a/src/renderer/src/pages/ChatPage.vue
+++ b/src/renderer/src/pages/ChatPage.vue
@@ -286,13 +286,7 @@ import { useSpotlightStore } from '@/stores/ui/spotlight'
 import { useModelStore } from '@/stores/modelStore'
 import { createSessionClient } from '@api/SessionClient'
 import { isManualCompactionCommand } from '@/components/chat/mentions/utils'
-import {
-  applyChatSearchHighlights,
-  collectChatSearchResults,
-  clearChatSearchHighlights,
-  setActiveChatSearchResult,
-  type ChatSearchResult
-} from '@/lib/chatSearch'
+import { clearChatSearchHighlights } from '@/lib/chatSearch'
 
 import { WORKSPACE_EVENTS } from '@/events'
 import { filterUnsupportedAudioAttachments } from '@/lib/audioInputSupport'
@@ -309,6 +303,7 @@ import { playChatInputHeroFlight } from '@/lib/chatInputHero'
 import { scheduleStartupDeferredTask } from '@/lib/startupDeferred'
 import { usePlanFloatLifecycle } from './chat-page/usePlanFloatLifecycle'
 import { useDisplayMessages } from './chat-page/useDisplayMessages'
+import { useChatSearch } from './chat-page/useChatSearch'
 import type {
   MessageFile,
   UserMessageInlineItem,
@@ -452,18 +447,8 @@ let pendingHistoryLoadAtIdle = false
 let hasUpwardPaginationIntent = false
 let lastGestureClientY: number | null = null
 const traceMessageId = ref<string | null>(null)
-const isChatSearchOpen = ref(false)
-const chatSearchQuery = ref('')
-const activeChatSearchIndex = ref(0)
-const chatSearchBarRef = ref<{
-  focusInput: () => void
-  selectInput: () => void
-} | null>(null)
 let spotlightJumpTimer: number | null = null
 let scrollReadFrame: number | null = null
-const planSnapshotClearTimers = new Map<string, number>()
-let chatSearchRefreshFrame: number | null = null
-let pendingChatSearchReveal = false
 let cancelSessionRestoreTask: (() => void) | null = null
 let hasScheduledInitialSessionRestore = false
 let cancelPlanUpdatedListener: (() => void) | null = null
@@ -476,6 +461,10 @@ let pendingMessageWindowMeasurements: MessageMeasurementSnapshot | null = null
 let restoreMessageWindowMeasurements = (snapshot: MessageMeasurementSnapshot) => {
   pendingMessageWindowMeasurements = snapshot
 }
+// Rebound after useChatSearch is created below (it needs the message window, which
+// is set up after the session-change watch that calls these on first run).
+let clearChatSearchStateRef = () => {}
+let cancelScheduledChatSearchRefreshRef = () => {}
 let measurementSessionId = ''
 let sessionRestoreRequestId = 0
 let isChatPageActive = true
@@ -1010,7 +999,7 @@ watch(
     hasUpwardPaginationIntent = false
     lastGestureClientY = null
     pendingDeleteMessageId.value = null
-    clearChatSearchState()
+    clearChatSearchStateRef()
     resetDisplayMessagesForSessionChange()
     sessionRestoreRequestId += 1
     chatScrollSessionEpoch = chatScrollController.beginSession(id)
@@ -1191,9 +1180,29 @@ const visibleDisplayMessages = computed(() =>
 )
 const messageWindowBeforeHeight = computed(() => messageWindowRange.value.before)
 const messageWindowAfterHeight = computed(() => messageWindowRange.value.after)
-const chatSearchResults = computed(() =>
-  collectChatSearchResults(displayMessages.value, chatSearchQuery.value)
-)
+
+const {
+  isChatSearchOpen,
+  chatSearchQuery,
+  activeChatSearchIndex,
+  chatSearchBarRef,
+  chatSearchResults,
+  closeChatSearch,
+  clearChatSearchState,
+  goToNextChatSearchMatch,
+  goToPreviousChatSearchMatch,
+  handleSearchKeydown,
+  cancelScheduledChatSearchRefresh
+} = useChatSearch({
+  messageSearchRoot,
+  displayMessages,
+  visibleDisplayMessages,
+  hasWindowEntry: (messageId) => Boolean(messageWindow.getEntry(messageId)),
+  requestChatScroll,
+  waitForNextAnimationFrame
+})
+clearChatSearchStateRef = clearChatSearchState
+cancelScheduledChatSearchRefreshRef = cancelScheduledChatSearchRefresh
 
 function applyMessageMeasures(payloads: Array<{ messageId: string; height: number }>) {
   if (payloads.length === 0) return
@@ -1264,138 +1273,6 @@ watch(
   { flush: 'post' }
 )
 
-async function refreshChatSearchHighlights(revealActive: boolean) {
-  if (!isChatSearchOpen.value) {
-    return
-  }
-
-  await nextTick()
-  if (!isChatSearchOpen.value) {
-    return
-  }
-
-  const root = messageSearchRoot.value
-  applyChatSearchHighlights(root, chatSearchQuery.value)
-
-  if (chatSearchResults.value.length === 0) {
-    activeChatSearchIndex.value = 0
-    return
-  }
-
-  const nextIndex = Math.min(activeChatSearchIndex.value, chatSearchResults.value.length - 1)
-  activeChatSearchIndex.value = nextIndex
-  const activeResult = chatSearchResults.value[nextIndex]
-  if (revealActive) {
-    await revealChatSearchResult(activeResult, 'auto')
-  } else {
-    setActiveChatSearchResult(root, activeResult, { scroll: false })
-  }
-}
-
-async function revealChatSearchResult(
-  result: ChatSearchResult | undefined,
-  behavior: ScrollBehavior = 'auto'
-) {
-  if (!result) return
-
-  await nextTick()
-  const root = messageSearchRoot.value
-  applyChatSearchHighlights(root, chatSearchQuery.value)
-
-  const entry = messageWindow.getEntry(result.messageId)
-  if (!entry) return
-  const requestId = requestChatScroll('search-navigation', {
-    kind: 'message',
-    messageId: result.messageId,
-    align: 'one-third'
-  })
-  if (requestId === null) return
-  await waitForNextAnimationFrame()
-  await nextTick()
-  applyChatSearchHighlights(root, chatSearchQuery.value)
-  setActiveChatSearchResult(root, result, { behavior, scroll: false })
-}
-
-function cancelScheduledChatSearchRefresh() {
-  pendingChatSearchReveal = false
-  if (chatSearchRefreshFrame === null) {
-    return
-  }
-
-  window.cancelAnimationFrame(chatSearchRefreshFrame)
-  chatSearchRefreshFrame = null
-}
-
-function scheduleChatSearchHighlights(revealActive = false) {
-  if (!isChatSearchOpen.value) {
-    return
-  }
-  pendingChatSearchReveal ||= revealActive
-  if (chatSearchRefreshFrame !== null) return
-
-  chatSearchRefreshFrame = window.requestAnimationFrame(() => {
-    chatSearchRefreshFrame = null
-    const shouldReveal = pendingChatSearchReveal
-    pendingChatSearchReveal = false
-    void refreshChatSearchHighlights(shouldReveal)
-  })
-}
-
-function focusChatSearchInput() {
-  nextTick(() => {
-    chatSearchBarRef.value?.selectInput()
-  })
-}
-
-function clearChatSearchState() {
-  cancelScheduledChatSearchRefresh()
-  clearChatSearchHighlights(messageSearchRoot.value)
-  chatSearchQuery.value = ''
-  activeChatSearchIndex.value = 0
-  isChatSearchOpen.value = false
-}
-
-function openChatSearch() {
-  isChatSearchOpen.value = true
-  focusChatSearchInput()
-  void refreshChatSearchHighlights(true)
-}
-
-function closeChatSearch() {
-  clearChatSearchState()
-}
-
-function activateChatSearchMatch(index: number, behavior: ScrollBehavior = 'auto') {
-  if (chatSearchResults.value.length === 0) {
-    activeChatSearchIndex.value = 0
-    return
-  }
-
-  const normalizedIndex =
-    ((index % chatSearchResults.value.length) + chatSearchResults.value.length) %
-    chatSearchResults.value.length
-
-  activeChatSearchIndex.value = normalizedIndex
-  void revealChatSearchResult(chatSearchResults.value[normalizedIndex], behavior)
-}
-
-function goToNextChatSearchMatch() {
-  activateChatSearchMatch(activeChatSearchIndex.value + 1)
-}
-
-function goToPreviousChatSearchMatch() {
-  activateChatSearchMatch(activeChatSearchIndex.value - 1)
-}
-
-function isEditableTarget(target: EventTarget | null): boolean {
-  const element = target instanceof HTMLElement ? target : null
-  if (!element) {
-    return false
-  }
-
-  return Boolean(element.closest('input, textarea, select, [contenteditable="true"]'))
-}
-
 function handleWindowKeydown(event: KeyboardEvent) {
   if (isSessionRestoreKeyboardScrollIntent(event)) {
     chatScrollController.notifyUserGestureStart('keyboard')
@@ -1405,50 +1282,9 @@ function handleWindowKeydown(event: KeyboardEvent) {
     markListScrolling()
   }
 
-  if ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === 'f') {
-    event.preventDefault()
-    openChatSearch()
-    return
-  }
-
-  if (!isChatSearchOpen.value) {
-    return
-  }
-
-  if (event.key === 'Escape') {
-    event.preventDefault()
-    closeChatSearch()
-    return
-  }
-
-  if (event.key === 'Enter' && !isEditableTarget(event.target)) {
-    event.preventDefault()
-    if (event.shiftKey) {
-      goToPreviousChatSearchMatch()
-      return
-    }
-
-    goToNextChatSearchMatch()
-  }
+  handleSearchKeydown(event)
 }
 
-watch(chatSearchQuery, () => {
-  activeChatSearchIndex.value = 0
-  scheduleChatSearchHighlights(true)
-})
-
-watch(
-  [visibleDisplayMessages, chatSearchResults],
-  () => {
-    if (!isChatSearchOpen.value) {
-      return
-    }
-
-    scheduleChatSearchHighlights(false)
-  },
-  { flush: 'post' }
-)
-
 const message = ref('')
 const attachedFiles = ref<MessageFile[]>([])
 const chatInputRef = ref<{
diff --git a/src/renderer/src/pages/chat-page/useChatSearch.ts b/src/renderer/src/pages/chat-page/useChatSearch.ts
new file mode 100644
index 0000000000..2601792595
--- /dev/null
+++ b/src/renderer/src/pages/chat-page/useChatSearch.ts
@@ -0,0 +1,252 @@
+import { computed, nextTick, ref, watch, type ComputedRef, type Ref } from 'vue'
+import {
+  applyChatSearchHighlights,
+  collectChatSearchResults,
+  clearChatSearchHighlights,
+  setActiveChatSearchResult,
+  type ChatSearchResult
+} from '@/lib/chatSearch'
+import type { DisplayMessage } from '@/components/chat/messageListItems'
+import type { ChatScrollTarget, ChatScrollReason } from '@/composables/chat/chatScrollState'
+
+type UseChatSearchOptions = {
+  messageSearchRoot: Ref<HTMLElement | null>
+  displayMessages: ComputedRef<DisplayMessage[]>
+  visibleDisplayMessages: ComputedRef<DisplayMessage[]>
+  hasWindowEntry: (messageId: string) => boolean
+  requestChatScroll: (
+    reason: ChatScrollReason,
+    target: ChatScrollTarget,
+    immediate?: boolean
+  ) => number | null
+  waitForNextAnimationFrame: () => Promise<void>
+}
+
+/**
+ * Owns in-session find (Cmd/Ctrl+F): open state, query, active match index,
+ * highlight application, and rAF-coalesced refresh. Navigation reuses the shared
+ * scroll controller via `requestChatScroll('search-navigation', …)` so it never
+ * fights auto-follow for the scrollbar.
+ */
+export function useChatSearch(options: UseChatSearchOptions) {
+  const {
+    messageSearchRoot,
+    displayMessages,
+    visibleDisplayMessages,
+    hasWindowEntry,
+    requestChatScroll,
+    waitForNextAnimationFrame
+  } = options
+
+  const isChatSearchOpen = ref(false)
+  const chatSearchQuery = ref('')
+  const activeChatSearchIndex = ref(0)
+  const chatSearchBarRef = ref<{
+    focusInput: () => void
+    selectInput: () => void
+  } | null>(null)
+
+  let chatSearchRefreshFrame: number | null = null
+  let pendingChatSearchReveal = false
+
+  const chatSearchResults = computed(() =>
+    collectChatSearchResults(displayMessages.value, chatSearchQuery.value)
+  )
+
+  async function refreshChatSearchHighlights(revealActive: boolean) {
+    if (!isChatSearchOpen.value) {
+      return
+    }
+
+    await nextTick()
+    if (!isChatSearchOpen.value) {
+      return
+    }
+
+    const root = messageSearchRoot.value
+    applyChatSearchHighlights(root, chatSearchQuery.value)
+
+    if (chatSearchResults.value.length === 0) {
+      activeChatSearchIndex.value = 0
+      return
+    }
+
+    const nextIndex = Math.min(activeChatSearchIndex.value, chatSearchResults.value.length - 1)
+    activeChatSearchIndex.value = nextIndex
+    const activeResult = chatSearchResults.value[nextIndex]
+    if (revealActive) {
+      await revealChatSearchResult(activeResult, 'auto')
+    } else {
+      setActiveChatSearchResult(root, activeResult, { scroll: false })
+    }
+  }
+
+  async function revealChatSearchResult(
+    result: ChatSearchResult | undefined,
+    behavior: ScrollBehavior = 'auto'
+  ) {
+    if (!result) return
+
+    await nextTick()
+    const root = messageSearchRoot.value
+    applyChatSearchHighlights(root, chatSearchQuery.value)
+
+    if (!hasWindowEntry(result.messageId)) return
+    const requestId = requestChatScroll('search-navigation', {
+      kind: 'message',
+      messageId: result.messageId,
+      align: 'one-third'
+    })
+    if (requestId === null) return
+    await waitForNextAnimationFrame()
+    await nextTick()
+    applyChatSearchHighlights(root, chatSearchQuery.value)
+    setActiveChatSearchResult(root, result, { behavior, scroll: false })
+  }
+
+  function cancelScheduledChatSearchRefresh() {
+    pendingChatSearchReveal = false
+    if (chatSearchRefreshFrame === null) {
+      return
+    }
+
+    window.cancelAnimationFrame(chatSearchRefreshFrame)
+    chatSearchRefreshFrame = null
+  }
+
+  function scheduleChatSearchHighlights(revealActive = false) {
+    if (!isChatSearchOpen.value) {
+      return
+    }
+    pendingChatSearchReveal ||= revealActive
+    if (chatSearchRefreshFrame !== null) return
+
+    chatSearchRefreshFrame = window.requestAnimationFrame(() => {
+      chatSearchRefreshFrame = null
+      const shouldReveal = pendingChatSearchReveal
+      pendingChatSearchReveal = false
+      void refreshChatSearchHighlights(shouldReveal)
+    })
+  }
+
+  function focusChatSearchInput() {
+    nextTick(() => {
+      chatSearchBarRef.value?.selectInput()
+    })
+  }
+
+  function clearChatSearchState() {
+    cancelScheduledChatSearchRefresh()
+    clearChatSearchHighlights(messageSearchRoot.value)
+    chatSearchQuery.value = ''
+    activeChatSearchIndex.value = 0
+    isChatSearchOpen.value = false
+  }
+
+  function openChatSearch() {
+    isChatSearchOpen.value = true
+    focusChatSearchInput()
+    void refreshChatSearchHighlights(true)
+  }
+
+  function closeChatSearch() {
+    clearChatSearchState()
+  }
+
+  function activateChatSearchMatch(index: number, behavior: ScrollBehavior = 'auto') {
+    if (chatSearchResults.value.length === 0) {
+      activeChatSearchIndex.value = 0
+      return
+    }
+
+    const normalizedIndex =
+      ((index % chatSearchResults.value.length) + chatSearchResults.value.length) %
+      chatSearchResults.value.length
+
+    activeChatSearchIndex.value = normalizedIndex
+    void revealChatSearchResult(chatSearchResults.value[normalizedIndex], behavior)
+  }
+
+  function goToNextChatSearchMatch() {
+    activateChatSearchMatch(activeChatSearchIndex.value + 1)
+  }
+
+  function goToPreviousChatSearchMatch() {
+    activateChatSearchMatch(activeChatSearchIndex.value - 1)
+  }
+
+  function isEditableTarget(target: EventTarget | null): boolean {
+    const element = target instanceof HTMLElement ? target : null
+    if (!element) {
+      return false
+    }
+
+    return Boolean(element.closest('input, textarea, select, [contenteditable="true"]'))
+  }
+
+  /**
+   * Handles the search-specific keyboard shortcuts. Returns true when the event
+   * was consumed so the caller can skip its own handling.
+   */
+  function handleSearchKeydown(event: KeyboardEvent): boolean {
+    if ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === 'f') {
+      event.preventDefault()
+      openChatSearch()
+      return true
+    }
+
+    if (!isChatSearchOpen.value) {
+      return false
+    }
+
+    if (event.key === 'Escape') {
+      event.preventDefault()
+      closeChatSearch()
+      return true
+    }
+
+    if (event.key === 'Enter' && !isEditableTarget(event.target)) {
+      event.preventDefault()
+      if (event.shiftKey) {
+        goToPreviousChatSearchMatch()
+      } else {
+        goToNextChatSearchMatch()
+      }
+      return true
+    }
+
+    return false
+  }
+
+  watch(chatSearchQuery, () => {
+    activeChatSearchIndex.value = 0
+    scheduleChatSearchHighlights(true)
+  })
+
+  watch(
+    [visibleDisplayMessages, chatSearchResults],
+    () => {
+      if (!isChatSearchOpen.value) {
+        return
+      }
+
+      scheduleChatSearchHighlights(false)
+    },
+    { flush: 'post' }
+  )
+
+  return {
+    isChatSearchOpen,
+    chatSearchQuery,
+    activeChatSearchIndex,
+    chatSearchBarRef,
+    chatSearchResults,
+    openChatSearch,
+    closeChatSearch,
+    clearChatSearchState,
+    goToNextChatSearchMatch,
+    goToPreviousChatSearchMatch,
+    handleSearchKeydown,
+    cancelScheduledChatSearchRefresh
+  }
+}
diff --git a/src/renderer/src/pages/chat-page/useDisplayMessages.ts b/src/renderer/src/pages/chat-page/useDisplayMessages.ts
index dd4bc7483f..4f8ab102b0 100644
--- a/src/renderer/src/pages/chat-page/useDisplayMessages.ts
+++ b/src/renderer/src/pages/chat-page/useDisplayMessages.ts
@@ -265,10 +265,10 @@ export function useDisplayMessages(options: UseDisplayMessagesOptions) {
     const pending = pendingAssistantPlaceholder.value
     return Boolean(
       pending &&
-        pending.sessionId === currentSessionId() &&
-        !hasFirstStreamingContent.value &&
-        !hasNewAssistantMessageAfterPendingPlaceholder.value &&
-        !ephemeralRateLimitBlock.value
+      pending.sessionId === currentSessionId() &&
+      !hasFirstStreamingContent.value &&
+      !hasNewAssistantMessageAfterPendingPlaceholder.value &&
+      !ephemeralRateLimitBlock.value
     )
   })
 
diff --git a/src/renderer/src/pages/chat-page/usePlanFloatLifecycle.ts b/src/renderer/src/pages/chat-page/usePlanFloatLifecycle.ts
index b705a14c74..580f6ed62f 100644
--- a/src/renderer/src/pages/chat-page/usePlanFloatLifecycle.ts
+++ b/src/renderer/src/pages/chat-page/usePlanFloatLifecycle.ts
@@ -36,9 +36,7 @@ export function usePlanFloatLifecycle(options: UsePlanFloatLifecycleOptions) {
   const planFloatLingerBySession: Record<string, boolean> = {}
   const planSnapshotClearTimers = new Map<string, number>()
 
-  function readSessionStatus(
-    sessionId: string
-  ): 'working' | 'completed' | 'error' | 'none' | null {
+  function readSessionStatus(sessionId: string): 'working' | 'completed' | 'error' | 'none' | null {
     if (sessionStore.activeSession?.id === sessionId) {
       return sessionStore.activeSession.status
     }

From 955f7d740c1076ac544e08538bf83699615a5b69 Mon Sep 17 00:00:00 2001
From: zhangmo8 <zhangmo8@users.noreply.github.com>
Date: Thu, 16 Jul 2026 13:59:33 +0800
Subject: [PATCH 03/14] refactor(chat): add useListGestures and
 useMessageVirtualization atoms

---
 .../src/pages/chat-page/useListGestures.ts    | 247 ++++++++++++++++++
 .../chat-page/useMessageVirtualization.ts     | 241 +++++++++++++++++
 2 files changed, 488 insertions(+)
 create mode 100644 src/renderer/src/pages/chat-page/useListGestures.ts
 create mode 100644 src/renderer/src/pages/chat-page/useMessageVirtualization.ts

diff --git a/src/renderer/src/pages/chat-page/useListGestures.ts b/src/renderer/src/pages/chat-page/useListGestures.ts
new file mode 100644
index 0000000000..f8fcf81578
--- /dev/null
+++ b/src/renderer/src/pages/chat-page/useListGestures.ts
@@ -0,0 +1,247 @@
+import { ref, type Ref } from 'vue'
+
+type GestureKind = 'wheel' | 'touch' | 'pointer' | 'keyboard'
+
+type UseListGesturesOptions = {
+  viewport: Ref<HTMLElement | null>
+  /** ms to wait after the last scroll signal before declaring the list settled. */
+  scrollIdleMs: number
+  /** scrollTop at/below which an upward drag should arm history pagination. */
+  topHistoryThreshold: number
+  /** Notifies the scroll controller that a user gesture began (suspends auto-follow). */
+  onGestureStart: (kind: GestureKind) => void
+  /** Notifies the scroll controller that the user gesture ended. */
+  onGestureEnd: () => void
+  /** Called once when scrolling starts, to pin the overscan window around the gesture. */
+  onScrollingStart: () => void
+  /** Called once the list has settled (no active gesture, idle elapsed). */
+  onScrollingSettled: () => void
+  /** Called on settle when an upward-pagination intent is armed at the top. */
+  onIdleHistoryLoad: () => void
+}
+
+/**
+ * Single-responsibility atom: translates raw DOM pointer/touch/wheel/keyboard
+ * activity into a small intent surface — `isListScrolling`, an "active gesture"
+ * flag, and an armed upward-pagination intent — and fires lifecycle callbacks at
+ * the right moments. It owns NO window, geometry, or history state; the composing
+ * hook wires those in through callbacks so this atom stays free of cross-concern
+ * coupling.
+ */
+export function useListGestures(options: UseListGesturesOptions) {
+  const { viewport, scrollIdleMs, topHistoryThreshold } = options
+
+  const isListScrolling = ref(false)
+
+  let scrollIdleTimer: number | null = null
+  let isListGestureActive = false
+  let pendingHistoryLoadAtIdle = false
+  let hasUpwardPaginationIntent = false
+  let lastGestureClientY: number | null = null
+
+  function finishListScrollingNow(): void {
+    isListScrolling.value = false
+    options.onGestureEnd()
+    options.onScrollingSettled()
+    if (pendingHistoryLoadAtIdle) {
+      pendingHistoryLoadAtIdle = false
+      options.onIdleHistoryLoad()
+    }
+  }
+
+  function finishListScrollingAfterIdle(delay = scrollIdleMs): void {
+    if (scrollIdleTimer !== null) {
+      window.clearTimeout(scrollIdleTimer)
+      scrollIdleTimer = null
+    }
+    if (delay <= 0 && !isListGestureActive) {
+      finishListScrollingNow()
+      return
+    }
+    scrollIdleTimer = window.setTimeout(() => {
+      scrollIdleTimer = null
+      if (isListGestureActive) {
+        finishListScrollingAfterIdle()
+        return
+      }
+      finishListScrollingNow()
+    }, delay)
+  }
+
+  function markListScrolling(): void {
+    if (!isListScrolling.value) {
+      isListScrolling.value = true
+      options.onScrollingStart()
+    }
+
+    if (isListGestureActive) {
+      if (scrollIdleTimer !== null) {
+        window.clearTimeout(scrollIdleTimer)
+        scrollIdleTimer = null
+      }
+      return
+    }
+
+    finishListScrollingAfterIdle()
+  }
+
+  function beginListGesture(kind: 'touch' | 'pointer', clientY?: number): void {
+    options.onGestureStart(kind)
+    isListGestureActive = true
+    lastGestureClientY = clientY ?? null
+    markListScrolling()
+  }
+
+  function updateUpwardPaginationIntent(isUpward: boolean): void {
+    hasUpwardPaginationIntent = isUpward
+    if (!isUpward) {
+      pendingHistoryLoadAtIdle = false
+      return
+    }
+
+    if ((viewport.value?.scrollTop ?? Number.POSITIVE_INFINITY) <= topHistoryThreshold) {
+      pendingHistoryLoadAtIdle = true
+    }
+  }
+
+  function endListGesture(): void {
+    if (!isListGestureActive) {
+      lastGestureClientY = null
+      return
+    }
+    isListGestureActive = false
+    lastGestureClientY = null
+    finishListScrollingAfterIdle(0)
+  }
+
+  function onListTouchStart(event: TouchEvent): void {
+    lastGestureClientY = event.touches[0]?.clientY ?? null
+  }
+
+  function onListTouchMove(event: TouchEvent): void {
+    const clientY = event.touches[0]?.clientY
+    if (clientY !== undefined && lastGestureClientY !== null) {
+      updateUpwardPaginationIntent(clientY > lastGestureClientY)
+    }
+    if (!isListGestureActive) {
+      beginListGesture('touch', clientY)
+      return
+    }
+    lastGestureClientY = clientY ?? lastGestureClientY
+    markListScrolling()
+  }
+
+  function onListTouchEnd(): void {
+    if (!isListGestureActive) {
+      lastGestureClientY = null
+      return
+    }
+    isListGestureActive = false
+    lastGestureClientY = null
+    finishListScrollingAfterIdle()
+  }
+
+  function onListTouchCancel(): void {
+    endListGesture()
+  }
+
+  function onListPointerDown(event: PointerEvent): void {
+    const el = viewport.value
+    if (!el || el.scrollHeight <= el.clientHeight) return
+    const rect = el.getBoundingClientRect()
+    const scrollbarHitWidth = Math.max(el.offsetWidth - el.clientWidth, 12)
+    if (event.clientX < rect.right - scrollbarHitWidth) return
+    beginListGesture('pointer', event.clientY)
+  }
+
+  function onListPointerMove(event: PointerEvent): void {
+    if (isListGestureActive && event.buttons !== 0) {
+      if (lastGestureClientY !== null) {
+        updateUpwardPaginationIntent(event.clientY < lastGestureClientY)
+      }
+      lastGestureClientY = event.clientY
+      markListScrolling()
+    }
+  }
+
+  function onListPointerEnd(): void {
+    endListGesture()
+  }
+
+  function onListScrollEnd(): void {
+    if (!isListGestureActive) {
+      finishListScrollingAfterIdle(0)
+    }
+  }
+
+  /**
+   * Keyboard scroll intent (arrow/page/home/end) routed through the same gesture
+   * lifecycle so auto-follow yields to the user identically to pointer input.
+   */
+  function markKeyboardScrollIntent(isUpward: boolean): void {
+    options.onGestureStart('keyboard')
+    updateUpwardPaginationIntent(isUpward)
+    markListScrolling()
+  }
+
+  /** Wheel intent: arm pagination direction and keep the scrolling state warm. */
+  function markWheelScrollIntent(isUpward: boolean): void {
+    updateUpwardPaginationIntent(isUpward)
+    markListScrolling()
+  }
+
+  function isGestureActive(): boolean {
+    return isListGestureActive
+  }
+
+  function consumeUpwardPaginationIntent(): boolean {
+    const armed = hasUpwardPaginationIntent
+    hasUpwardPaginationIntent = false
+    return armed
+  }
+
+  function armPendingHistoryLoadAtIdle(): void {
+    pendingHistoryLoadAtIdle = true
+  }
+
+  function reset(): void {
+    if (scrollIdleTimer !== null) {
+      window.clearTimeout(scrollIdleTimer)
+      scrollIdleTimer = null
+    }
+    isListScrolling.value = false
+    isListGestureActive = false
+    pendingHistoryLoadAtIdle = false
+    hasUpwardPaginationIntent = false
+    lastGestureClientY = null
+  }
+
+  function resetIntentForSessionChange(): void {
+    pendingHistoryLoadAtIdle = false
+    hasUpwardPaginationIntent = false
+    lastGestureClientY = null
+  }
+
+  return {
+    isListScrolling,
+    // DOM event handlers (bound in template)
+    onListTouchStart,
+    onListTouchMove,
+    onListTouchEnd,
+    onListTouchCancel,
+    onListPointerDown,
+    onListPointerMove,
+    onListPointerEnd,
+    onListScrollEnd,
+    // intent helpers used by wheel/keyboard/native-scroll paths
+    markListScrolling,
+    markWheelScrollIntent,
+    markKeyboardScrollIntent,
+    updateUpwardPaginationIntent,
+    consumeUpwardPaginationIntent,
+    armPendingHistoryLoadAtIdle,
+    isGestureActive,
+    reset,
+    resetIntentForSessionChange
+  }
+}
diff --git a/src/renderer/src/pages/chat-page/useMessageVirtualization.ts b/src/renderer/src/pages/chat-page/useMessageVirtualization.ts
new file mode 100644
index 0000000000..99660485f1
--- /dev/null
+++ b/src/renderer/src/pages/chat-page/useMessageVirtualization.ts
@@ -0,0 +1,241 @@
+import { computed, ref, type ComputedRef, type Ref } from 'vue'
+import type { useMessageWindow } from '@/composables/message/useMessageWindow'
+import type { DisplayMessage } from '@/components/chat/messageListItems'
+
+type MessageWindow = ReturnType<typeof useMessageWindow>
+
+type LogicalViewportAnchor = {
+  messageId: string
+  layoutTop: number
+}
+
+type UseMessageVirtualizationOptions = {
+  viewport: Ref<HTMLElement | null>
+  displayMessages: ComputedRef<DisplayMessage[]>
+  messageWindow: MessageWindow
+  windowingThreshold: number
+  initialWindowCount: number
+  overscanPx: number
+  /** Reads the logical origin top of the window inside the scroll container. */
+  getWindowOriginTop: (el: HTMLElement) => number | null
+  /** True while a user gesture freezes windowing/measurement. */
+  isListScrolling: Ref<boolean>
+  /** True when the list is pinned to the bottom (auto-follow / restoring). */
+  isBottomFollowingMode: () => boolean
+  /** Scrolls to keep bottom pinned; mirrors ChatPage.scrollToBottom. */
+  scrollToBottom: (force?: boolean) => void
+  /** Requests an absolute-top anchor correction through the scroll controller. */
+  requestAnchorScroll: (top: number) => void
+  currentScrollMode: () => string
+}
+
+/**
+ * Single-responsibility atom for message virtualization: computes the rendered
+ * window range from the shared geometry refs, batches ResizeObserver measurements
+ * into one rAF commit, and preserves the reading position across height changes
+ * with a logical (not DOM-rect) anchor. It owns no gesture or session state.
+ */
+export function useMessageVirtualization(options: UseMessageVirtualizationOptions) {
+  const { viewport, displayMessages, messageWindow } = options
+  const { windowingThreshold, initialWindowCount, overscanPx } = options
+
+  // Shared geometry, written by the composing hook's scroll/resize reads.
+  const scrollViewportTop = ref(0)
+  const scrollViewportHeight = ref(0)
+  const messageWindowOriginTop = ref(0)
+
+  const pendingMeasureQueue = new Map<string, number>()
+  let pendingMeasureFlushFrame: number | null = null
+
+  const findFirstEntryWithBottomAtOrAfter = (
+    entries: Array<{ bottom: number }>,
+    target: number
+  ): number => {
+    let low = 0
+    let high = entries.length
+    while (low < high) {
+      const middle = Math.floor((low + high) / 2)
+      if (entries[middle].bottom >= target) {
+        high = middle
+      } else {
+        low = middle + 1
+      }
+    }
+    return low
+  }
+
+  const findFirstEntryWithTopAfter = (entries: Array<{ top: number }>, target: number): number => {
+    let low = 0
+    let high = entries.length
+    while (low < high) {
+      const middle = Math.floor((low + high) / 2)
+      if (entries[middle].top > target) {
+        high = middle
+      } else {
+        low = middle + 1
+      }
+    }
+    return low
+  }
+
+  const messageWindowRange = computed(() => {
+    const entries = messageWindow.entries.value
+    const total = entries.length
+    if (total === 0) {
+      return { start: 0, end: 0, before: 0, after: 0 }
+    }
+
+    if (total <= windowingThreshold) {
+      return { start: 0, end: total, before: 0, after: 0 }
+    }
+
+    const viewportHeight = scrollViewportHeight.value
+    if (viewportHeight <= 0) {
+      const start = Math.max(0, total - initialWindowCount)
+      return {
+        start,
+        end: total,
+        before: entries[start]?.top ?? 0,
+        after: 0
+      }
+    }
+
+    const viewportTop = Math.max(scrollViewportTop.value - messageWindowOriginTop.value, 0)
+    const windowTop = Math.max(0, viewportTop - overscanPx)
+    const windowBottom = viewportTop + viewportHeight + overscanPx
+    let start = findFirstEntryWithBottomAtOrAfter(entries, windowTop)
+    if (start >= total) start = Math.max(0, total - initialWindowCount)
+
+    let end = findFirstEntryWithTopAfter(entries, windowBottom)
+    end = Math.min(total, Math.max(end, start + 1))
+
+    return {
+      start,
+      end,
+      before: entries[start]?.top ?? 0,
+      after: Math.max((messageWindow.totalHeight.value ?? 0) - (entries[end - 1]?.bottom ?? 0), 0)
+    }
+  })
+
+  const visibleDisplayMessages = computed(() =>
+    displayMessages.value.slice(messageWindowRange.value.start, messageWindowRange.value.end)
+  )
+  const messageWindowBeforeHeight = computed(() => messageWindowRange.value.before)
+  const messageWindowAfterHeight = computed(() => messageWindowRange.value.after)
+
+  const usesWindowedMessages = () => messageWindow.entries.value.length > windowingThreshold
+
+  function captureLogicalViewportAnchor(): LogicalViewportAnchor | null {
+    const container = viewport.value
+    if (!container) return null
+
+    const originTop = options.getWindowOriginTop(container)
+    if (originTop === null) return null
+    const layoutViewportTop = Math.max(container.scrollTop - originTop, 0)
+    const entries = messageWindow.entries.value
+    const anchorIndex = findFirstEntryWithBottomAtOrAfter(entries, layoutViewportTop)
+    const anchor = entries[Math.min(anchorIndex, entries.length - 1)]
+    return anchor ? { messageId: anchor.id, layoutTop: anchor.top } : null
+  }
+
+  function restoreLogicalViewportAnchor(anchor: LogicalViewportAnchor | null): void {
+    if (!anchor || options.isBottomFollowingMode() || options.isListScrolling.value) return
+
+    const container = viewport.value
+    const nextAnchor = messageWindow.getEntry(anchor.messageId)
+    if (!container || !nextAnchor) return
+
+    const delta = nextAnchor.top - anchor.layoutTop
+    if (Math.abs(delta) < 1) return
+
+    options.requestAnchorScroll(container.scrollTop + delta)
+  }
+
+  function applyMessageMeasures(payloads: Array<{ messageId: string; height: number }>) {
+    if (payloads.length === 0) return
+
+    // Snapshot the logical entry before changing the height map. DOM rects are
+    // intentionally not used here: waiting for a later rendered rect produces a
+    // visible drift frame before the corrective scroll.
+    const isBottomFollowing = options.isBottomFollowingMode()
+    const windowed = usesWindowedMessages()
+    const preChangeAnchor =
+      isBottomFollowing || !windowed ? null : captureLogicalViewportAnchor()
+
+    let changed = false
+    for (const payload of payloads) {
+      const delta = messageWindow.setMeasuredHeight(payload.messageId, payload.height)
+      if (delta === 0) continue
+      changed = true
+    }
+    if (!changed) return
+    messageWindow.flushMeasurements()
+
+    if (isBottomFollowing) {
+      // Unified coalesced auto-follow path (same as streamRevision watcher).
+      options.scrollToBottom(options.currentScrollMode() === 'restoring')
+    } else if (windowed) {
+      restoreLogicalViewportAnchor(preChangeAnchor)
+    }
+  }
+
+  function flushPendingMeasures(): void {
+    if (pendingMeasureFlushFrame !== null || pendingMeasureQueue.size === 0) return
+
+    pendingMeasureFlushFrame = window.requestAnimationFrame(() => {
+      pendingMeasureFlushFrame = null
+      const batch = Array.from(pendingMeasureQueue, ([messageId, height]) => ({ messageId, height }))
+      pendingMeasureQueue.clear()
+      applyMessageMeasures(batch)
+      flushPendingMeasures()
+    })
+  }
+
+  function onMessageMeasure(payload: { messageId: string; height: number }) {
+    // Always batch row measurements. Window mounts commonly emit many ResizeObserver
+    // callbacks in the same frame; committing them one-by-one makes the spacer and
+    // rendered range chase each other.
+    pendingMeasureQueue.set(payload.messageId, payload.height)
+    if (!options.isListScrolling.value) {
+      flushPendingMeasures()
+    }
+  }
+
+  /** Pin the current window around the start of a gesture so overscan is centered. */
+  function pinWindowToViewport(): void {
+    const el = viewport.value
+    if (el) {
+      scrollViewportTop.value = el.scrollTop
+      scrollViewportHeight.value = el.clientHeight
+    }
+  }
+
+  function cancelPendingMeasureFlush(): void {
+    if (pendingMeasureFlushFrame !== null) {
+      window.cancelAnimationFrame(pendingMeasureFlushFrame)
+      pendingMeasureFlushFrame = null
+    }
+    pendingMeasureQueue.clear()
+  }
+
+  return {
+    // geometry refs (written by the composing hook's metric sync)
+    scrollViewportTop,
+    scrollViewportHeight,
+    messageWindowOriginTop,
+    // rendered window
+    messageWindowRange,
+    visibleDisplayMessages,
+    messageWindowBeforeHeight,
+    messageWindowAfterHeight,
+    usesWindowedMessages,
+    // measurement pipeline
+    onMessageMeasure,
+    flushPendingMeasures,
+    cancelPendingMeasureFlush,
+    // anchors
+    captureLogicalViewportAnchor,
+    restoreLogicalViewportAnchor,
+    pinWindowToViewport
+  }
+}

From b9d4bbb62bca9f03f24da722217ab981edaaa379 Mon Sep 17 00:00:00 2001
From: zhangmo8 <zhangmo8@users.noreply.github.com>
Date: Thu, 16 Jul 2026 14:56:25 +0800
Subject: [PATCH 04/14] refactor(chat): compose list-gesture and virtualization
 atoms

---
 src/renderer/src/pages/ChatPage.vue           | 419 +++---------------
 .../chat-page/useMessageVirtualization.ts     |   8 +-
 2 files changed, 67 insertions(+), 360 deletions(-)

diff --git a/src/renderer/src/pages/ChatPage.vue b/src/renderer/src/pages/ChatPage.vue
index 9d719b57d9..03fef934d5 100644
--- a/src/renderer/src/pages/ChatPage.vue
+++ b/src/renderer/src/pages/ChatPage.vue
@@ -37,16 +37,16 @@
           class="message-list-container relative h-full min-h-0 w-full min-w-0 overflow-y-auto"
           :class="{ 'dc-list-scrolling': isListScrolling }"
           @scroll.passive="onScroll"
-          @scrollend.passive="onListScrollEnd"
+          @scrollend.passive="listGestures.onListScrollEnd"
           @wheel.passive="onWheel"
-          @touchstart.passive="onListTouchStart"
-          @touchmove.passive="onListTouchMove"
-          @touchend.passive="onListTouchEnd"
-          @touchcancel.passive="onListTouchCancel"
-          @pointerdown.passive="onListPointerDown"
-          @pointermove.passive="onListPointerMove"
-          @pointerup.passive="onListPointerEnd"
-          @pointercancel.passive="onListPointerEnd"
+          @touchstart.passive="listGestures.onListTouchStart"
+          @touchmove.passive="listGestures.onListTouchMove"
+          @touchend.passive="listGestures.onListTouchEnd"
+          @touchcancel.passive="listGestures.onListTouchCancel"
+          @pointerdown.passive="listGestures.onListPointerDown"
+          @pointermove.passive="listGestures.onListPointerMove"
+          @pointerup.passive="listGestures.onListPointerEnd"
+          @pointercancel.passive="listGestures.onListPointerEnd"
         >
           <div ref="messageSearchRoot" class="min-h-full">
             <div
@@ -304,6 +304,8 @@ import { scheduleStartupDeferredTask } from '@/lib/startupDeferred'
 import { usePlanFloatLifecycle } from './chat-page/usePlanFloatLifecycle'
 import { useDisplayMessages } from './chat-page/useDisplayMessages'
 import { useChatSearch } from './chat-page/useChatSearch'
+import { useListGestures } from './chat-page/useListGestures'
+import { useMessageVirtualization } from './chat-page/useMessageVirtualization'
 import type {
   MessageFile,
   UserMessageInlineItem,
@@ -419,12 +421,6 @@ const chatScrollController = useChatScrollController({
 })
 const pendingDeleteMessageId = ref<string | null>(null)
 const showDeleteMessageDialog = computed(() => Boolean(pendingDeleteMessageId.value))
-const scrollViewportTop = ref(0)
-const scrollViewportHeight = ref(0)
-const messageWindowOriginTop = ref(0)
-/** True while the user is actively flinging/dragging the list — freezes windowing/measure. */
-const isListScrolling = ref(false)
-const NEAR_BOTTOM_THRESHOLD = 80 // px
 const TOP_HISTORY_THRESHOLD = 80
 const MESSAGE_JUMP_RETRY_INTERVAL = 80
 const MESSAGE_HIGHLIGHT_DURATION = 2000
@@ -439,13 +435,6 @@ const SESSION_RESTORE_SCROLL_INTENT_KEYS = new Set([
   ' ',
   'Spacebar'
 ])
-const pendingMeasureQueue = new Map<string, number>()
-let scrollIdleTimer: number | null = null
-let pendingMeasureFlushFrame: number | null = null
-let isListGestureActive = false
-let pendingHistoryLoadAtIdle = false
-let hasUpwardPaginationIntent = false
-let lastGestureClientY: number | null = null
 const traceMessageId = ref<string | null>(null)
 let spotlightJumpTimer: number | null = null
 let scrollReadFrame: number | null = null
@@ -469,10 +458,6 @@ let measurementSessionId = ''
 let sessionRestoreRequestId = 0
 let isChatPageActive = true
 let handledCommittedSessionId: string | null = null
-type LogicalViewportAnchor = {
-  messageId: string
-  layoutTop: number
-}
 type HistoryLayoutAnchor = {
   messageId: string
   layoutTop: number
@@ -505,19 +490,6 @@ function isSessionRestoreKeyboardScrollIntent(event: KeyboardEvent): boolean {
   )
 }
 
-function captureLogicalViewportAnchor(): LogicalViewportAnchor | null {
-  const container = scrollContainer.value
-  if (!container) return null
-
-  const originTop = getMessageWindowOriginTop(container)
-  if (originTop === null) return null
-  const layoutViewportTop = Math.max(container.scrollTop - originTop, 0)
-  const entries = messageWindow.entries.value
-  const anchorIndex = findFirstEntryWithBottomAtOrAfter(entries, layoutViewportTop)
-  const anchor = entries[Math.min(anchorIndex, entries.length - 1)]
-  return anchor ? { messageId: anchor.id, layoutTop: anchor.top } : null
-}
-
 function messageIdSelector(messageId: string): string {
   const escapedMessageId =
     typeof CSS !== 'undefined' && typeof CSS.escape === 'function'
@@ -535,26 +507,6 @@ function isBottomFollowingMode(): boolean {
   )
 }
 
-function restoreLogicalViewportAnchor(anchor: LogicalViewportAnchor | null): void {
-  if (!anchor || isBottomFollowingMode() || isListScrolling.value) return
-
-  const container = scrollContainer.value
-  const nextAnchor = messageWindow.getEntry(anchor.messageId)
-  if (!container || !nextAnchor) return
-
-  const delta = nextAnchor.top - anchor.layoutTop
-  if (Math.abs(delta) < 1) return
-
-  requestChatScroll(
-    'measurement-anchor',
-    {
-      kind: 'absolute',
-      top: container.scrollTop + delta
-    },
-    true
-  )
-}
-
 function requestChatScroll(
   reason: ChatScrollReason,
   target: ChatScrollTarget,
@@ -574,12 +526,6 @@ function waitForNextAnimationFrame(): Promise<void> {
   })
 }
 
-function isAtBottom(): boolean {
-  const el = scrollContainer.value
-  if (!el) return true
-  return el.scrollHeight - el.scrollTop - el.clientHeight <= NEAR_BOTTOM_THRESHOLD
-}
-
 function getMessageWindowOriginTop(el: HTMLElement): number | null {
   const origin = messageSearchRoot.value?.querySelector<HTMLElement>('[data-message-window-origin]')
   if (!origin) return null
@@ -624,162 +570,6 @@ function connectChatGeometryObserver(): void {
   viewportResizeObserver.observe(messageRoot)
 }
 
-function flushPendingMeasures(): void {
-  if (pendingMeasureFlushFrame !== null || pendingMeasureQueue.size === 0) return
-
-  pendingMeasureFlushFrame = window.requestAnimationFrame(() => {
-    pendingMeasureFlushFrame = null
-    const batch = Array.from(pendingMeasureQueue, ([messageId, height]) => ({ messageId, height }))
-    pendingMeasureQueue.clear()
-    applyMessageMeasures(batch)
-    flushPendingMeasures()
-  })
-}
-
-function finishListScrollingNow(): void {
-  isListScrolling.value = false
-  chatScrollController.notifyUserGestureEnd()
-  const el = scrollContainer.value
-  if (el) {
-    syncMessageViewportMetrics(el)
-  }
-  flushPendingMeasures()
-  if (pendingHistoryLoadAtIdle) {
-    pendingHistoryLoadAtIdle = false
-    void loadOlderMessagesAtTop()
-  }
-}
-
-function finishListScrollingAfterIdle(delay = SCROLL_IDLE_MS): void {
-  if (scrollIdleTimer !== null) {
-    window.clearTimeout(scrollIdleTimer)
-    scrollIdleTimer = null
-  }
-  if (delay <= 0 && !isListGestureActive) {
-    finishListScrollingNow()
-    return
-  }
-  scrollIdleTimer = window.setTimeout(() => {
-    scrollIdleTimer = null
-    if (isListGestureActive) {
-      finishListScrollingAfterIdle()
-      return
-    }
-    finishListScrollingNow()
-  }, delay)
-}
-
-function markListScrolling(): void {
-  if (!isListScrolling.value) {
-    isListScrolling.value = true
-    // Pin the current window around the start of the gesture so overscan is centered.
-    const el = scrollContainer.value
-    if (el) {
-      scrollViewportTop.value = el.scrollTop
-      scrollViewportHeight.value = el.clientHeight
-    }
-  }
-
-  if (isListGestureActive) {
-    if (scrollIdleTimer !== null) {
-      window.clearTimeout(scrollIdleTimer)
-      scrollIdleTimer = null
-    }
-    return
-  }
-
-  finishListScrollingAfterIdle()
-}
-
-function beginListGesture(kind: 'touch' | 'pointer', clientY?: number): void {
-  chatScrollController.notifyUserGestureStart(kind)
-  isListGestureActive = true
-  lastGestureClientY = clientY ?? null
-  markListScrolling()
-}
-
-function updateUpwardPaginationIntent(isUpward: boolean): void {
-  hasUpwardPaginationIntent = isUpward
-  if (!isUpward) {
-    pendingHistoryLoadAtIdle = false
-    return
-  }
-
-  if ((scrollContainer.value?.scrollTop ?? Number.POSITIVE_INFINITY) <= TOP_HISTORY_THRESHOLD) {
-    pendingHistoryLoadAtIdle = true
-  }
-}
-
-function endListGesture(): void {
-  if (!isListGestureActive) {
-    lastGestureClientY = null
-    return
-  }
-  isListGestureActive = false
-  lastGestureClientY = null
-  finishListScrollingAfterIdle(0)
-}
-
-function onListTouchStart(event: TouchEvent): void {
-  lastGestureClientY = event.touches[0]?.clientY ?? null
-}
-
-function onListTouchMove(event: TouchEvent): void {
-  const clientY = event.touches[0]?.clientY
-  if (clientY !== undefined && lastGestureClientY !== null) {
-    updateUpwardPaginationIntent(clientY > lastGestureClientY)
-  }
-  if (!isListGestureActive) {
-    beginListGesture('touch', clientY)
-    return
-  }
-  lastGestureClientY = clientY ?? lastGestureClientY
-  markListScrolling()
-}
-
-function onListTouchEnd(): void {
-  if (!isListGestureActive) {
-    lastGestureClientY = null
-    return
-  }
-  isListGestureActive = false
-  lastGestureClientY = null
-  finishListScrollingAfterIdle()
-}
-
-function onListTouchCancel(): void {
-  endListGesture()
-}
-
-function onListPointerDown(event: PointerEvent): void {
-  const viewport = scrollContainer.value
-  if (!viewport || viewport.scrollHeight <= viewport.clientHeight) return
-  const rect = viewport.getBoundingClientRect()
-  const scrollbarHitWidth = Math.max(viewport.offsetWidth - viewport.clientWidth, 12)
-  if (event.clientX < rect.right - scrollbarHitWidth) return
-  beginListGesture('pointer', event.clientY)
-}
-
-function onListPointerMove(event: PointerEvent): void {
-  if (isListGestureActive && event.buttons !== 0) {
-    if (lastGestureClientY !== null) {
-      updateUpwardPaginationIntent(event.clientY < lastGestureClientY)
-    }
-    lastGestureClientY = event.clientY
-    markListScrolling()
-  }
-}
-
-function onListPointerEnd(): void {
-  endListGesture()
-}
-
-function onListScrollEnd(): void {
-  if (!isListGestureActive) {
-    finishListScrollingAfterIdle(0)
-  }
-}
-
 function scrollDomToBottom(reason: ChatScrollReason): void {
   requestChatScroll(reason, { kind: 'bottom' })
 }
@@ -812,8 +602,7 @@ function scheduleScrollMetricsRead() {
 function onWheel(event: WheelEvent) {
   if (event.deltaY === 0) return
   chatScrollController.notifyUserGestureStart('wheel')
-  updateUpwardPaginationIntent(event.deltaY < 0)
-  markListScrolling()
+  listGestures.markWheelScrollIntent(event.deltaY < 0)
 }
 
 function onScroll() {
@@ -823,20 +612,22 @@ function onScroll() {
   const source = chatScrollController.notifyViewportScroll()
   const userInitiatedScroll = source === 'user'
   const hadUpwardPaginationIntent =
-    userInitiatedScroll && chatScrollController.state.value.userOwned && hasUpwardPaginationIntent
+    userInitiatedScroll && chatScrollController.state.value.userOwned
 
   scheduleScrollMetricsRead()
   if (userInitiatedScroll && chatScrollController.state.value.activeGesture) {
-    markListScrolling()
+    listGestures.markListScrolling()
   }
 
   if (el.scrollTop <= TOP_HISTORY_THRESHOLD && hadUpwardPaginationIntent) {
+    if (!listGestures.consumeUpwardPaginationIntent()) {
+      return
+    }
     if (chatScrollController.state.value.activeGesture || isListScrolling.value) {
-      pendingHistoryLoadAtIdle = true
+      listGestures.armPendingHistoryLoadAtIdle()
     } else {
       void loadOlderMessagesAtTop()
     }
-    hasUpwardPaginationIntent = false
   }
 }
 
@@ -995,9 +786,7 @@ watch(
       cacheCurrentMessageMeasurements()
     }
     measurementSessionId = id
-    pendingHistoryLoadAtIdle = false
-    hasUpwardPaginationIntent = false
-    lastGestureClientY = null
+    listGestures.resetIntentForSessionChange()
     pendingDeleteMessageId.value = null
     clearChatSearchStateRef()
     resetDisplayMessagesForSessionChange()
@@ -1105,81 +894,49 @@ if (pendingMessageWindowMeasurements) {
   pendingMessageWindowMeasurements = null
 }
 
-const findFirstEntryWithBottomAtOrAfter = (
-  entries: Array<{ bottom: number }>,
-  target: number
-): number => {
-  let low = 0
-  let high = entries.length
-  while (low < high) {
-    const middle = Math.floor((low + high) / 2)
-    if (entries[middle].bottom >= target) {
-      high = middle
-    } else {
-      low = middle + 1
-    }
-  }
-  return low
-}
-
-const findFirstEntryWithTopAfter = (entries: Array<{ top: number }>, target: number): number => {
-  let low = 0
-  let high = entries.length
-  while (low < high) {
-    const middle = Math.floor((low + high) / 2)
-    if (entries[middle].top > target) {
-      high = middle
-    } else {
-      low = middle + 1
-    }
-  }
-  return low
-}
-
-const messageWindowRange = computed(() => {
-  const entries = messageWindow.entries.value
-  const total = entries.length
-  if (total === 0) {
-    return { start: 0, end: 0, before: 0, after: 0 }
-  }
-
-  if (total <= MESSAGE_WINDOWING_THRESHOLD) {
-    return { start: 0, end: total, before: 0, after: 0 }
-  }
-
-  const viewportHeight = scrollViewportHeight.value
-  if (viewportHeight <= 0) {
-    const start = Math.max(0, total - MESSAGE_INITIAL_WINDOW_COUNT)
-    return {
-      start,
-      end: total,
-      before: entries[start]?.top ?? 0,
-      after: 0
-    }
-  }
-
-  const viewportTop = Math.max(scrollViewportTop.value - messageWindowOriginTop.value, 0)
-  const windowTop = Math.max(0, viewportTop - MESSAGE_WINDOW_OVERSCAN_PX)
-  const windowBottom = viewportTop + viewportHeight + MESSAGE_WINDOW_OVERSCAN_PX
-  let start = findFirstEntryWithBottomAtOrAfter(entries, windowTop)
-  if (start >= total) start = Math.max(0, total - MESSAGE_INITIAL_WINDOW_COUNT)
-
-  let end = findFirstEntryWithTopAfter(entries, windowBottom)
-  end = Math.min(total, Math.max(end, start + 1))
-
-  return {
-    start,
-    end,
-    before: entries[start]?.top ?? 0,
-    after: Math.max((messageWindow.totalHeight.value ?? 0) - (entries[end - 1]?.bottom ?? 0), 0)
+const listGestures = useListGestures({
+  viewport: scrollContainer,
+  scrollIdleMs: SCROLL_IDLE_MS,
+  topHistoryThreshold: TOP_HISTORY_THRESHOLD,
+  onGestureStart: (kind) => chatScrollController.notifyUserGestureStart(kind),
+  onGestureEnd: () => chatScrollController.notifyUserGestureEnd(),
+  onScrollingStart: () => virtualization.pinWindowToViewport(),
+  onScrollingSettled: () => {
+    const el = scrollContainer.value
+    if (el) syncMessageViewportMetrics(el)
+    virtualization.flushPendingMeasures()
+  },
+  onIdleHistoryLoad: () => {
+    void loadOlderMessagesAtTop()
   }
 })
+const isListScrolling = listGestures.isListScrolling
 
-const visibleDisplayMessages = computed(() =>
-  displayMessages.value.slice(messageWindowRange.value.start, messageWindowRange.value.end)
-)
-const messageWindowBeforeHeight = computed(() => messageWindowRange.value.before)
-const messageWindowAfterHeight = computed(() => messageWindowRange.value.after)
+const virtualization = useMessageVirtualization({
+  viewport: scrollContainer,
+  displayMessages,
+  messageWindow,
+  windowingThreshold: MESSAGE_WINDOWING_THRESHOLD,
+  initialWindowCount: MESSAGE_INITIAL_WINDOW_COUNT,
+  overscanPx: MESSAGE_WINDOW_OVERSCAN_PX,
+  getWindowOriginTop: getMessageWindowOriginTop,
+  isListScrolling,
+  isBottomFollowingMode,
+  scrollToBottom: (force) => scrollToBottom(Boolean(force)),
+  requestAnchorScroll: (top) => {
+    requestChatScroll('measurement-anchor', { kind: 'absolute', top }, true)
+  },
+  currentScrollMode: () => chatScrollController.state.value.mode
+})
+const {
+  scrollViewportTop,
+  scrollViewportHeight,
+  messageWindowOriginTop,
+  visibleDisplayMessages,
+  messageWindowBeforeHeight,
+  messageWindowAfterHeight,
+  onMessageMeasure
+} = virtualization
 
 const {
   isChatSearchOpen,
@@ -1204,44 +961,6 @@ const {
 clearChatSearchStateRef = clearChatSearchState
 cancelScheduledChatSearchRefreshRef = cancelScheduledChatSearchRefresh
 
-function applyMessageMeasures(payloads: Array<{ messageId: string; height: number }>) {
-  if (payloads.length === 0) return
-
-  // Snapshot the logical entry before changing the height map. DOM rects are
-  // intentionally not used here: waiting for a later rendered rect produces a
-  // visible drift frame before the corrective scroll.
-  const isBottomFollowing = isBottomFollowingMode()
-  const usesWindowedMessages = messageWindow.entries.value.length > MESSAGE_WINDOWING_THRESHOLD
-  const preChangeAnchor =
-    isBottomFollowing || !usesWindowedMessages ? null : captureLogicalViewportAnchor()
-
-  let changed = false
-  for (const payload of payloads) {
-    const delta = messageWindow.setMeasuredHeight(payload.messageId, payload.height)
-    if (delta === 0) continue
-    changed = true
-  }
-  if (!changed) return
-  messageWindow.flushMeasurements()
-
-  if (isBottomFollowing) {
-    // Unified coalesced auto-follow path (same as streamRevision watcher).
-    scrollToBottom(chatScrollController.state.value.mode === 'restoring')
-  } else if (usesWindowedMessages) {
-    restoreLogicalViewportAnchor(preChangeAnchor)
-  }
-}
-
-function onMessageMeasure(payload: { messageId: string; height: number }) {
-  // Always batch row measurements. Window mounts commonly emit many ResizeObserver
-  // callbacks in the same frame; committing them one-by-one makes the spacer and
-  // rendered range chase each other.
-  pendingMeasureQueue.set(payload.messageId, payload.height)
-  if (!isListScrolling.value) {
-    flushPendingMeasures()
-  }
-}
-
 const traceMessageIds = computed(() =>
   messageStore.messages
     .filter((msg) => msg.role === 'assistant' && (msg.traceCount ?? 0) > 0)
@@ -1275,11 +994,9 @@ watch(
 
 function handleWindowKeydown(event: KeyboardEvent) {
   if (isSessionRestoreKeyboardScrollIntent(event)) {
-    chatScrollController.notifyUserGestureStart('keyboard')
-    updateUpwardPaginationIntent(
+    listGestures.markKeyboardScrollIntent(
       event.key === 'ArrowUp' || event.key === 'PageUp' || event.key === 'Home'
     )
-    markListScrolling()
   }
 
   handleSearchKeydown(event)
@@ -2100,20 +1817,8 @@ onUnmounted(() => {
     window.cancelAnimationFrame(scrollReadFrame)
     scrollReadFrame = null
   }
-  if (scrollIdleTimer !== null) {
-    window.clearTimeout(scrollIdleTimer)
-    scrollIdleTimer = null
-  }
-  if (pendingMeasureFlushFrame !== null) {
-    window.cancelAnimationFrame(pendingMeasureFlushFrame)
-    pendingMeasureFlushFrame = null
-  }
-  isListScrolling.value = false
-  isListGestureActive = false
-  pendingHistoryLoadAtIdle = false
-  hasUpwardPaginationIntent = false
-  lastGestureClientY = null
-  pendingMeasureQueue.clear()
+  listGestures.reset()
+  virtualization.cancelPendingMeasureFlush()
   cancelScheduledChatSearchRefresh()
   pendingInputStore.clear()
 })
diff --git a/src/renderer/src/pages/chat-page/useMessageVirtualization.ts b/src/renderer/src/pages/chat-page/useMessageVirtualization.ts
index 99660485f1..ba06deee23 100644
--- a/src/renderer/src/pages/chat-page/useMessageVirtualization.ts
+++ b/src/renderer/src/pages/chat-page/useMessageVirtualization.ts
@@ -159,8 +159,7 @@ export function useMessageVirtualization(options: UseMessageVirtualizationOption
     // visible drift frame before the corrective scroll.
     const isBottomFollowing = options.isBottomFollowingMode()
     const windowed = usesWindowedMessages()
-    const preChangeAnchor =
-      isBottomFollowing || !windowed ? null : captureLogicalViewportAnchor()
+    const preChangeAnchor = isBottomFollowing || !windowed ? null : captureLogicalViewportAnchor()
 
     let changed = false
     for (const payload of payloads) {
@@ -184,7 +183,10 @@ export function useMessageVirtualization(options: UseMessageVirtualizationOption
 
     pendingMeasureFlushFrame = window.requestAnimationFrame(() => {
       pendingMeasureFlushFrame = null
-      const batch = Array.from(pendingMeasureQueue, ([messageId, height]) => ({ messageId, height }))
+      const batch = Array.from(pendingMeasureQueue, ([messageId, height]) => ({
+        messageId,
+        height
+      }))
       pendingMeasureQueue.clear()
       applyMessageMeasures(batch)
       flushPendingMeasures()

From f905eaf2e7923d5f9f765d104715dc9c8333e96a Mon Sep 17 00:00:00 2001
From: zhangmo8 <zhangmo8@users.noreply.github.com>
Date: Thu, 16 Jul 2026 15:15:15 +0800
Subject: [PATCH 05/14] refactor(chat): order composables before session
 watches

---
 src/renderer/src/pages/ChatPage.vue | 172 ++++++++++++++--------------
 1 file changed, 86 insertions(+), 86 deletions(-)

diff --git a/src/renderer/src/pages/ChatPage.vue b/src/renderer/src/pages/ChatPage.vue
index 03fef934d5..1d87c332c8 100644
--- a/src/renderer/src/pages/ChatPage.vue
+++ b/src/renderer/src/pages/ChatPage.vue
@@ -777,92 +777,6 @@ function cacheCurrentMessageMeasurements(): void {
   recentMessageMeasurementCache.set(measurementSessionId, captureMessageWindowMeasurements())
 }
 
-// Load messages when sessionId changes, then scroll to bottom
-watch(
-  () => props.sessionId,
-  async (id) => {
-    handledCommittedSessionId = null
-    if (measurementSessionId && measurementSessionId !== id) {
-      cacheCurrentMessageMeasurements()
-    }
-    measurementSessionId = id
-    listGestures.resetIntentForSessionChange()
-    pendingDeleteMessageId.value = null
-    clearChatSearchStateRef()
-    resetDisplayMessagesForSessionChange()
-    sessionRestoreRequestId += 1
-    chatScrollSessionEpoch = chatScrollController.beginSession(id)
-    markChatSessionPerformance('selected', id, chatScrollSessionEpoch)
-    markChatSessionPerformance('preparation-started', id, chatScrollSessionEpoch)
-    cancelSessionRestoreTask?.()
-    cancelSessionRestoreTask = null
-    clearMessageWindowMeasurements()
-    const activatedFromCache = id ? (messageStore.activateRecentSessionView?.(id) ?? false) : false
-    const cachedMeasurements = activatedFromCache ? recentMessageMeasurementCache.get(id) : null
-    if (cachedMeasurements) {
-      restoreMessageWindowMeasurements(cachedMeasurements)
-    }
-    messageStore.clearStreamingStateForOtherSession(id)
-    if (activatedFromCache) {
-      markChatSessionPerformance('cache-committed', id, chatScrollSessionEpoch)
-    }
-    pendingInputStore.clear()
-    if (id) {
-      const requestId = sessionRestoreRequestId
-      const runRestore = () => restoreSessionMessages(id, requestId)
-      if (!hasScheduledInitialSessionRestore) {
-        hasScheduledInitialSessionRestore = true
-        cancelSessionRestoreTask = scheduleStartupDeferredTask(runRestore)
-      } else {
-        void runRestore()
-      }
-      return
-    }
-  },
-  { immediate: true }
-)
-
-watch(
-  [() => props.sessionId, () => messageStore.committedSessionId],
-  async ([id, committedSessionId]) => {
-    if (!id || committedSessionId !== id || handledCommittedSessionId === id) {
-      return
-    }
-
-    handledCommittedSessionId = id
-    markChatSessionPerformance('messages-prepared', id, chatScrollSessionEpoch)
-    markChatSessionPerformance('messages-committed', id, chatScrollSessionEpoch)
-    if (messageStore.committedSession?.id === id) {
-      applyRestoredSessionSummary(messageStore.committedSession)
-    }
-
-    await nextTick()
-    if (
-      props.sessionId !== id ||
-      messageStore.currentSessionId !== id ||
-      messageStore.committedSessionId !== id
-    ) {
-      return
-    }
-
-    window.requestAnimationFrame(() => {
-      if (
-        props.sessionId === id &&
-        messageStore.currentSessionId === id &&
-        messageStore.committedSessionId === id
-      ) {
-        markChatSessionPerformance('first-message-paint', id, chatScrollSessionEpoch)
-      }
-    })
-    if (spotlightStore.pendingMessageJump?.sessionId === id) {
-      void focusPendingSpotlightMessageJump()
-      return
-    }
-    requestChatScroll('session-restore', { kind: 'bottom' })
-  },
-  { immediate: true, flush: 'post' }
-)
-
 const {
   displayMessages,
   ephemeralRateLimitBlock,
@@ -961,6 +875,92 @@ const {
 clearChatSearchStateRef = clearChatSearchState
 cancelScheduledChatSearchRefreshRef = cancelScheduledChatSearchRefresh
 
+// Load messages when sessionId changes, then scroll to bottom
+watch(
+  () => props.sessionId,
+  async (id) => {
+    handledCommittedSessionId = null
+    if (measurementSessionId && measurementSessionId !== id) {
+      cacheCurrentMessageMeasurements()
+    }
+    measurementSessionId = id
+    listGestures.resetIntentForSessionChange()
+    pendingDeleteMessageId.value = null
+    clearChatSearchStateRef()
+    resetDisplayMessagesForSessionChange()
+    sessionRestoreRequestId += 1
+    chatScrollSessionEpoch = chatScrollController.beginSession(id)
+    markChatSessionPerformance('selected', id, chatScrollSessionEpoch)
+    markChatSessionPerformance('preparation-started', id, chatScrollSessionEpoch)
+    cancelSessionRestoreTask?.()
+    cancelSessionRestoreTask = null
+    clearMessageWindowMeasurements()
+    const activatedFromCache = id ? (messageStore.activateRecentSessionView?.(id) ?? false) : false
+    const cachedMeasurements = activatedFromCache ? recentMessageMeasurementCache.get(id) : null
+    if (cachedMeasurements) {
+      restoreMessageWindowMeasurements(cachedMeasurements)
+    }
+    messageStore.clearStreamingStateForOtherSession(id)
+    if (activatedFromCache) {
+      markChatSessionPerformance('cache-committed', id, chatScrollSessionEpoch)
+    }
+    pendingInputStore.clear()
+    if (id) {
+      const requestId = sessionRestoreRequestId
+      const runRestore = () => restoreSessionMessages(id, requestId)
+      if (!hasScheduledInitialSessionRestore) {
+        hasScheduledInitialSessionRestore = true
+        cancelSessionRestoreTask = scheduleStartupDeferredTask(runRestore)
+      } else {
+        void runRestore()
+      }
+      return
+    }
+  },
+  { immediate: true }
+)
+
+watch(
+  [() => props.sessionId, () => messageStore.committedSessionId],
+  async ([id, committedSessionId]) => {
+    if (!id || committedSessionId !== id || handledCommittedSessionId === id) {
+      return
+    }
+
+    handledCommittedSessionId = id
+    markChatSessionPerformance('messages-prepared', id, chatScrollSessionEpoch)
+    markChatSessionPerformance('messages-committed', id, chatScrollSessionEpoch)
+    if (messageStore.committedSession?.id === id) {
+      applyRestoredSessionSummary(messageStore.committedSession)
+    }
+
+    await nextTick()
+    if (
+      props.sessionId !== id ||
+      messageStore.currentSessionId !== id ||
+      messageStore.committedSessionId !== id
+    ) {
+      return
+    }
+
+    window.requestAnimationFrame(() => {
+      if (
+        props.sessionId === id &&
+        messageStore.currentSessionId === id &&
+        messageStore.committedSessionId === id
+      ) {
+        markChatSessionPerformance('first-message-paint', id, chatScrollSessionEpoch)
+      }
+    })
+    if (spotlightStore.pendingMessageJump?.sessionId === id) {
+      void focusPendingSpotlightMessageJump()
+      return
+    }
+    requestChatScroll('session-restore', { kind: 'bottom' })
+  },
+  { immediate: true, flush: 'post' }
+)
+
 const traceMessageIds = computed(() =>
   messageStore.messages
     .filter((msg) => msg.role === 'assistant' && (msg.traceCount ?? 0) > 0)

From c17a05b9190e7a52a24683280343a5e9407783be Mon Sep 17 00:00:00 2001
From: zhangmo8 <zhangmo8@users.noreply.github.com>
Date: Thu, 16 Jul 2026 15:40:13 +0800
Subject: [PATCH 06/14] test(chat): drop deleted useMessageScroll from scroll
 inventory

---
 .../composables/chat/chatScrollArchitecture.test.ts         | 6 ------
 1 file changed, 6 deletions(-)

diff --git a/test/renderer/composables/chat/chatScrollArchitecture.test.ts b/test/renderer/composables/chat/chatScrollArchitecture.test.ts
index d279ad7541..620ab874df 100644
--- a/test/renderer/composables/chat/chatScrollArchitecture.test.ts
+++ b/test/renderer/composables/chat/chatScrollArchitecture.test.ts
@@ -29,12 +29,6 @@ const allowedDirectScrollWrites: Record<string, ScrollWriteKind[]> = {
     'scrollIntoView'
   ],
   'src/renderer/src/components/spotlight/SpotlightOverlay.vue': ['scrollIntoView'],
-  'src/renderer/src/composables/message/useMessageScroll.ts': [
-    'scrollTop',
-    'scrollTop',
-    'scrollIntoView',
-    'scrollIntoView'
-  ],
   'src/renderer/src/composables/usePageCapture.ts': ['scrollTop', 'scrollTo'],
   'src/renderer/src/lib/chatSearch.ts': ['scrollIntoView', 'scrollIntoView']
 }

From dc077425c4cf31af545231f420423e6ee375af08 Mon Sep 17 00:00:00 2001
From: zhangmo8 <zhangmo8@users.noreply.github.com>
Date: Thu, 16 Jul 2026 15:52:47 +0800
Subject: [PATCH 07/14] test(chat): remove orphan useMessageScroll test

---
 .../composables/useMessageScroll.test.ts      | 59 -------------------
 1 file changed, 59 deletions(-)
 delete mode 100644 test/renderer/composables/useMessageScroll.test.ts

diff --git a/test/renderer/composables/useMessageScroll.test.ts b/test/renderer/composables/useMessageScroll.test.ts
deleted file mode 100644
index fec71859ca..0000000000
--- a/test/renderer/composables/useMessageScroll.test.ts
+++ /dev/null
@@ -1,59 +0,0 @@
-import { describe, it, expect, beforeEach } from 'vitest'
-import { useMessageScroll } from '@/composables/message/useMessageScroll'
-
-class IO {
-  cb: any
-  constructor(cb: any) {
-    this.cb = cb
-  }
-  observe() {
-    this.cb([{ isIntersecting: false }])
-  }
-  unobserve() {}
-  disconnect() {}
-}
-beforeEach(() => {
-  // @ts-ignore
-  global.IntersectionObserver = IO as any
-})
-
-describe('useMessageScroll', () => {
-  it('updates scroll info and threshold, supports scrolling to bottom/message', async () => {
-    const api = useMessageScroll()
-    const container = document.createElement('div')
-    const anchor = document.createElement('div')
-    Object.defineProperty(container, 'clientHeight', { value: 500 })
-    Object.defineProperty(container, 'scrollHeight', { value: 2000, configurable: true })
-    Object.defineProperty(container, 'scrollTop', {
-      get() {
-        return this._st || 0
-      },
-      set(v) {
-        this._st = v
-      }
-    })
-
-    api.messagesContainer.value = container as any
-    api.scrollAnchor.value = anchor as any
-
-    api.setupScrollObserver()
-    expect(api.aboveThreshold.value).toBe(true)
-
-    api.scrollToBottom(false)
-    // allow nextTick chain to run
-    await Promise.resolve()
-    expect((container as any)._st).toBe(1500)
-
-    // add a target to scroll to
-    const msg = document.createElement('div')
-    msg.setAttribute('data-message-id', 'm-1')
-
-    // Mock scrollIntoView method
-    msg.scrollIntoView = () => {}
-
-    document.body.appendChild(msg)
-    api.scrollToMessage('m-1')
-    await Promise.resolve()
-    document.body.removeChild(msg)
-  })
-})

From 8a978397cfce66411f05982ede172cc08dbac0b2 Mon Sep 17 00:00:00 2001
From: zhangmo8 <zhangmo8@users.noreply.github.com>
Date: Thu, 16 Jul 2026 17:51:38 +0800
Subject: [PATCH 08/14] refactor(chat): extract useComposerSubmit composable

---
 src/renderer/src/pages/ChatPage.vue           | 335 ++------------
 .../src/pages/chat-page/useComposerSubmit.ts  | 412 ++++++++++++++++++
 2 files changed, 455 insertions(+), 292 deletions(-)
 create mode 100644 src/renderer/src/pages/chat-page/useComposerSubmit.ts

diff --git a/src/renderer/src/pages/ChatPage.vue b/src/renderer/src/pages/ChatPage.vue
index 1d87c332c8..3b0858cdd3 100644
--- a/src/renderer/src/pages/ChatPage.vue
+++ b/src/renderer/src/pages/ChatPage.vue
@@ -306,6 +306,7 @@ import { useDisplayMessages } from './chat-page/useDisplayMessages'
 import { useChatSearch } from './chat-page/useChatSearch'
 import { useListGestures } from './chat-page/useListGestures'
 import { useMessageVirtualization } from './chat-page/useMessageVirtualization'
+import { useComposerSubmit } from './chat-page/useComposerSubmit'
 import type {
   MessageFile,
   UserMessageInlineItem,
@@ -1002,8 +1003,6 @@ function handleWindowKeydown(event: KeyboardEvent) {
   handleSearchKeydown(event)
 }
 
-const message = ref('')
-const attachedFiles = ref<MessageFile[]>([])
 const chatInputRef = ref<{
   triggerAttach: () => void
   insertRecognizedText?: (text: string) => void
@@ -1067,7 +1066,6 @@ const voiceInput = useSpeechRecognition({
 const isVoiceInputListening = computed(() => voiceInput.isListening.value)
 const isVoiceInputTranscribing = computed(() => voiceInput.isTranscribing.value)
 let voiceInputConfigToken = 0
-let attachmentFilterToken = 0
 
 async function refreshVoiceInputAvailability() {
   const selection = getActiveModelSelection()
@@ -1268,36 +1266,6 @@ const {
   pendingInteractions
 })
 
-const hasInputText = computed(() => Boolean(message.value.trim()))
-const hasAttachments = computed(() => attachedFiles.value.length > 0)
-const hasDraftInput = computed(() => hasInputText.value || hasAttachments.value)
-const isQueueSubmitDisabled = computed(
-  () =>
-    isSessionViewPreparing.value ||
-    isAcpWorkdirMissing.value ||
-    !hasDraftInput.value ||
-    Boolean(activePendingInteraction.value) ||
-    isHandlingInteraction.value ||
-    pendingInputStore.isAtCapacity
-)
-const isInputSubmitDisabled = computed(
-  () =>
-    isSessionViewPreparing.value ||
-    isAcpWorkdirMissing.value ||
-    Boolean(activePendingInteraction.value) ||
-    isHandlingInteraction.value ||
-    (isGenerating.value && pendingInputStore.isAtCapacity) ||
-    !hasDraftInput.value
-)
-const disableQueueSteerAction = computed(
-  () =>
-    isSessionViewPreparing.value ||
-    !isGenerating.value ||
-    isAcpWorkdirMissing.value ||
-    Boolean(activePendingInteraction.value) ||
-    isHandlingInteraction.value
-)
-
 function getActiveModelSelection(): { providerId: string; modelId: string } | null {
   const activeSession = sessionStore.activeSession
   if (!activeSession?.providerId || !activeSession?.modelId) {
@@ -1310,71 +1278,6 @@ function getActiveModelSelection(): { providerId: string; modelId: string } | nu
   }
 }
 
-function notifyUnsupportedAudioAttachments(
-  selection: { providerId: string; modelId: string },
-  rejectedAudioFiles: MessageFile[]
-) {
-  if (rejectedAudioFiles.length === 0) {
-    return
-  }
-
-  const modelLabel =
-    modelStore.findChatSelectableModel(selection.providerId, selection.modelId)?.model.name ??
-    selection.modelId
-
-  toast({
-    title: t('chat.input.audioInputUnsupportedTitle'),
-    description: t('chat.input.audioInputUnsupportedDescription', {
-      count: rejectedAudioFiles.length,
-      model: modelLabel
-    })
-  })
-}
-
-async function prepareFilesForCurrentModel(files: MessageFile[]): Promise<MessageFile[]> {
-  const selection = getActiveModelSelection()
-  if (!selection || files.length === 0) {
-    return files
-  }
-
-  try {
-    const capabilities = await modelClient.getCapabilities(selection.providerId, selection.modelId)
-    if (capabilities.supportsAudioInput !== false) {
-      return files
-    }
-
-    const { acceptedFiles, rejectedAudioFiles } = filterUnsupportedAudioAttachments(files, false)
-    notifyUnsupportedAudioAttachments(selection, rejectedAudioFiles)
-    return acceptedFiles
-  } catch (error) {
-    console.warn('[ChatPage] Failed to resolve audio input capability:', error)
-    return files
-  }
-}
-
-const getComposerSkillsSnapshot = (): string[] => {
-  return Array.from(new Set(chatInputRef.value?.getPendingSkillsSnapshot?.() ?? []))
-}
-
-const clearComposerSkills = () => {
-  chatInputRef.value?.clearPendingSkills?.()
-}
-
-const getComposerInlineItemsSnapshot = (): UserMessageInlineItem[] => {
-  return chatInputRef.value?.getInlineItemsSnapshot?.() ?? []
-}
-
-const withMessageSkills = (text: string, files: MessageFile[]) => {
-  const activeSkills = getComposerSkillsSnapshot()
-  const inlineItems = getComposerInlineItemsSnapshot()
-  return {
-    text,
-    files,
-    ...(activeSkills.length > 0 ? { activeSkills } : {}),
-    ...(inlineItems.length > 0 ? { inlineItems } : {})
-  }
-}
-
 function canWriteSessionView(sessionId: string, restoreRequestId: number): boolean {
   return (
     isChatPageActive &&
@@ -1385,189 +1288,47 @@ function canWriteSessionView(sessionId: string, restoreRequestId: number): boole
   )
 }
 
-function beginOutgoingTurnFeedback(sessionId: string, payload: SendMessageInput) {
-  const optimisticUserMessageId = messageStore.addOptimisticUserMessage(sessionId, payload)
-  if (!optimisticUserMessageId) return null
-
-  const pendingAssistantPlaceholderId = createPendingAssistantPlaceholder(sessionId)
-  beginPlanTurn(sessionId)
-  return { optimisticUserMessageId, pendingAssistantPlaceholderId }
-}
-
-async function sendMessageWithOutgoingTurnFeedback(
-  sessionId: string,
-  payload: SendMessageInput,
-  feedback: NonNullable<ReturnType<typeof beginOutgoingTurnFeedback>>
-) {
-  try {
-    await chatClient.sendMessage(sessionId, payload)
-  } catch (error) {
-    clearPendingAssistantPlaceholder(feedback.pendingAssistantPlaceholderId)
-    messageStore.removeOptimisticMessage(feedback.optimisticUserMessageId, sessionId)
-    console.error('[ChatPage] send message failed:', error)
-  }
-}
-
-async function onSubmit() {
-  if (isReadOnlySession.value) return
-  if (isSessionViewPreparing.value) return
-  if (isAcpWorkdirMissing.value) return
-  if (activePendingInteraction.value || isHandlingInteraction.value) return
-  const sessionId = props.sessionId
-  const restoreRequestId = sessionRestoreRequestId
-  const text = message.value.trim()
-  const files = (await prepareFilesForCurrentModel([...attachedFiles.value])).map((f) => toRaw(f))
-  if (!canWriteSessionView(sessionId, restoreRequestId)) return
-  if (!text && files.length === 0) return
-  const handledCompaction = await handleManualCompactionCommand(text, sessionId, restoreRequestId)
-  if (!canWriteSessionView(sessionId, restoreRequestId)) return
-  if (handledCompaction) {
-    if (!isGenerating.value) {
-      message.value = ''
-    }
-    return
-  }
-  const payload = withMessageSkills(text, files)
-  if (isGenerating.value) {
-    await pendingInputStore.queueInput(sessionId, payload)
-    if (!canWriteSessionView(sessionId, restoreRequestId)) return
-    message.value = ''
-    attachedFiles.value = []
-    clearComposerSkills()
-    schedulePostSubmitScrollToBottom()
-  } else {
-    const feedback = beginOutgoingTurnFeedback(sessionId, payload)
-    if (!feedback) return
-    message.value = ''
-    attachedFiles.value = []
-    clearComposerSkills()
-    schedulePostSubmitScrollToBottom()
-    await sendMessageWithOutgoingTurnFeedback(sessionId, payload, feedback)
-  }
-}
-
-async function onCommandSubmit(command: string) {
-  if (isReadOnlySession.value) return
-  if (isSessionViewPreparing.value) return
-  if (isAcpWorkdirMissing.value) return
-  if (activePendingInteraction.value || isHandlingInteraction.value) return
-  const sessionId = props.sessionId
-  const restoreRequestId = sessionRestoreRequestId
-  const text = command.trim()
-  if (!text) return
-
-  const handledCompaction = await handleManualCompactionCommand(text, sessionId, restoreRequestId)
-  if (!canWriteSessionView(sessionId, restoreRequestId)) return
-  if (handledCompaction) {
-    return
-  }
-
-  const files = await prepareFilesForCurrentModel([...attachedFiles.value])
-  if (!canWriteSessionView(sessionId, restoreRequestId)) return
-  const payload = withMessageSkills(text, files)
-  if (isGenerating.value) {
-    await pendingInputStore.queueInput(sessionId, payload)
-    if (!canWriteSessionView(sessionId, restoreRequestId)) return
-    attachedFiles.value = []
-    clearComposerSkills()
-    schedulePostSubmitScrollToBottom()
-    return
-  }
-  const feedback = beginOutgoingTurnFeedback(sessionId, payload)
-  if (!feedback) return
-  attachedFiles.value = []
-  clearComposerSkills()
-  schedulePostSubmitScrollToBottom()
-  await sendMessageWithOutgoingTurnFeedback(sessionId, payload, feedback)
-}
-
-async function handleManualCompactionCommand(
-  text: string,
-  sessionId: string,
-  restoreRequestId: number
-): Promise<boolean> {
-  if (!isManualCompactionCommand(text)) {
-    return false
-  }
-  if (sessionStore.activeSession?.providerId === 'acp') {
-    return false
-  }
-  if (isGenerating.value) {
-    return true
-  }
-  if (!canWriteSessionView(sessionId, restoreRequestId)) {
-    return true
-  }
-
-  try {
-    const result = await sessionClient.compactSession(sessionId)
-    if (!canWriteSessionView(sessionId, restoreRequestId)) return true
-    const restoredSession = await loadMessagesForSession(sessionId)
-    if (!canWriteSessionView(sessionId, restoreRequestId) || restoredSession === null) return true
-    applyRestoredSessionSummary(restoredSession)
-    if (!result.compacted) {
-      toast({
-        title: t('chat.compaction.noopTitle'),
-        description: t('chat.compaction.noopDescription')
-      })
-    }
-  } catch (error) {
-    console.error('[ChatPage] manual compaction failed:', error)
-    toast({
-      title: t('chat.compaction.failedTitle'),
-      description: error instanceof Error ? error.message : String(error),
-      variant: 'destructive'
-    })
-  }
-  return true
-}
-
-async function onQueueSubmit() {
-  if (isReadOnlySession.value) return
-  if (isSessionViewPreparing.value) return
-  if (isAcpWorkdirMissing.value) return
-  if (activePendingInteraction.value || isHandlingInteraction.value) return
-  const sessionId = props.sessionId
-  const restoreRequestId = sessionRestoreRequestId
-  const text = message.value.trim()
-  const files = (await prepareFilesForCurrentModel([...attachedFiles.value])).map((f) => toRaw(f))
-  if (!canWriteSessionView(sessionId, restoreRequestId)) return
-  if (!text && files.length === 0) return
-  const handledCompaction = await handleManualCompactionCommand(text, sessionId, restoreRequestId)
-  if (!canWriteSessionView(sessionId, restoreRequestId)) return
-  if (handledCompaction) {
-    return
-  }
-  await pendingInputStore.queueInput(sessionId, withMessageSkills(text, files))
-  if (!canWriteSessionView(sessionId, restoreRequestId)) return
-  message.value = ''
-  attachedFiles.value = []
-  clearComposerSkills()
-}
-
-async function onSteer() {
-  if (isReadOnlySession.value) return
-  if (isSessionViewPreparing.value) return
-  if (isAcpWorkdirMissing.value) return
-  if (activePendingInteraction.value || isHandlingInteraction.value) return
-  const sessionId = props.sessionId
-  const restoreRequestId = sessionRestoreRequestId
-  const text = message.value.trim()
-  const files = (await prepareFilesForCurrentModel([...attachedFiles.value])).map((f) => toRaw(f))
-  if (!canWriteSessionView(sessionId, restoreRequestId)) return
-  if (!text && files.length === 0) return
-  const handledCompaction = await handleManualCompactionCommand(text, sessionId, restoreRequestId)
-  if (!canWriteSessionView(sessionId, restoreRequestId)) return
-  if (handledCompaction) {
-    return
-  }
-  beginPlanTurn(sessionId)
-  await chatClient.steerActiveTurn(sessionId, withMessageSkills(text, files))
-  if (!canWriteSessionView(sessionId, restoreRequestId)) return
-  message.value = ''
-  attachedFiles.value = []
-  clearComposerSkills()
-}
+const {
+  message,
+  attachedFiles,
+  hasDraftInput,
+  isQueueSubmitDisabled,
+  isInputSubmitDisabled,
+  disableQueueSteerAction,
+  onSubmit,
+  onCommandSubmit,
+  onQueueSubmit,
+  onSteer,
+  onFilesChange,
+  invalidatePendingAttachmentFilter
+} = useComposerSubmit({
+  sessionId: () => props.sessionId,
+  currentRestoreRequestId: () => sessionRestoreRequestId,
+  canWriteSessionView,
+  messageStore,
+  sessionStore,
+  modelStore,
+  pendingInputStore,
+  chatClient,
+  sessionClient,
+  modelClient,
+  chatInputRef,
+  isReadOnlySession,
+  isSessionViewPreparing,
+  isAcpWorkdirMissing,
+  isGenerating,
+  hasBlockingInteraction: () =>
+    Boolean(activePendingInteraction.value) || isHandlingInteraction.value,
+  getActiveModelSelection,
+  createPendingAssistantPlaceholder,
+  clearPendingAssistantPlaceholder,
+  beginPlanTurn,
+  schedulePostSubmitScrollToBottom,
+  loadMessagesForSession,
+  applyRestoredSessionSummary,
+  toast,
+  t
+})
 
 function onAttach() {
   chatInputRef.value?.triggerAttach()
@@ -1581,16 +1342,6 @@ function onToggleVoiceInput() {
   void voiceInput.toggle()
 }
 
-async function onFilesChange(files: MessageFile[]) {
-  const token = ++attachmentFilterToken
-  const filteredFiles = await prepareFilesForCurrentModel(files)
-  if (token !== attachmentFilterToken) {
-    return
-  }
-
-  attachedFiles.value = filteredFiles
-}
-
 async function onToolInteractionRespond(response: ToolInteractionResponse) {
   if (isReadOnlySession.value) {
     return
@@ -1790,7 +1541,7 @@ onMounted(() => {
 onUnmounted(() => {
   isChatPageActive = false
   sessionRestoreRequestId += 1
-  attachmentFilterToken += 1
+  invalidatePendingAttachmentFilter()
   cacheCurrentMessageMeasurements()
   removeModelConfigChangedListener()
   cancelAllPlanSnapshotClearTimers()
diff --git a/src/renderer/src/pages/chat-page/useComposerSubmit.ts b/src/renderer/src/pages/chat-page/useComposerSubmit.ts
new file mode 100644
index 0000000000..a4cc7dc081
--- /dev/null
+++ b/src/renderer/src/pages/chat-page/useComposerSubmit.ts
@@ -0,0 +1,412 @@
+import { computed, ref, toRaw, type ComputedRef, type Ref } from 'vue'
+import type { useMessageStore } from '@/stores/ui/message'
+import type { useSessionStore } from '@/stores/ui/session'
+import type { useModelStore } from '@/stores/modelStore'
+import type { usePendingInputStore } from '@/stores/ui/pendingInput'
+import { isManualCompactionCommand } from '@/components/chat/mentions/utils'
+import { filterUnsupportedAudioAttachments } from '@/lib/audioInputSupport'
+import type {
+  MessageFile,
+  SendMessageInput,
+  UserMessageInlineItem
+} from '@shared/types/agent-interface'
+
+type MessageStore = ReturnType<typeof useMessageStore>
+type SessionStore = ReturnType<typeof useSessionStore>
+type ModelStore = ReturnType<typeof useModelStore>
+type PendingInputStore = ReturnType<typeof usePendingInputStore>
+
+type ChatClientLike = {
+  sendMessage: (sessionId: string, payload: SendMessageInput) => Promise<unknown>
+  steerActiveTurn: (sessionId: string, payload: SendMessageInput) => Promise<unknown>
+}
+
+type SessionClientLike = {
+  compactSession: (sessionId: string) => Promise<{ compacted: boolean }>
+}
+
+type ModelClientLike = {
+  getCapabilities: (
+    providerId: string,
+    modelId: string
+  ) => Promise<{ supportsAudioInput?: boolean | null }>
+}
+
+type ComposerInputHandle = {
+  getInlineItemsSnapshot?: () => UserMessageInlineItem[]
+  getPendingSkillsSnapshot?: () => string[]
+  clearPendingSkills?: () => void
+}
+
+type ToastFn = (options: {
+  title: string
+  description?: string
+  variant?: 'destructive'
+}) => unknown
+
+type UseComposerSubmitOptions = {
+  sessionId: () => string
+  /** Session-view write gate; both values captured before every await chain. */
+  currentRestoreRequestId: () => number
+  canWriteSessionView: (sessionId: string, restoreRequestId: number) => boolean
+  messageStore: MessageStore
+  sessionStore: SessionStore
+  modelStore: ModelStore
+  pendingInputStore: PendingInputStore
+  chatClient: ChatClientLike
+  sessionClient: SessionClientLike
+  modelClient: ModelClientLike
+  chatInputRef: Ref<ComposerInputHandle | null>
+  isReadOnlySession: ComputedRef<boolean>
+  isSessionViewPreparing: ComputedRef<boolean>
+  isAcpWorkdirMissing: ComputedRef<boolean>
+  isGenerating: ComputedRef<boolean>
+  hasBlockingInteraction: () => boolean
+  getActiveModelSelection: () => { providerId: string; modelId: string } | null
+  /** Outgoing-turn UX: pending-assistant placeholder + plan turn reset. */
+  createPendingAssistantPlaceholder: (sessionId: string) => string
+  clearPendingAssistantPlaceholder: (id?: string) => void
+  beginPlanTurn: (sessionId: string) => void
+  schedulePostSubmitScrollToBottom: () => void
+  loadMessagesForSession: (sessionId: string, count?: number) => Promise<unknown>
+  applyRestoredSessionSummary: (session: unknown) => void
+  toast: ToastFn
+  t: (key: string, params?: Record<string, unknown>) => string
+}
+
+/**
+ * Owns the composer draft (text + attachments) and every submit path — send,
+ * queue, steer, slash-command, manual compaction — with the session-view write
+ * gate re-checked after every await so a mid-flight session switch can never
+ * write into the wrong session. Send-vs-queue-vs-steer priority given
+ * `isGenerating` is decided here, in one place.
+ */
+export function useComposerSubmit(options: UseComposerSubmitOptions) {
+  const {
+    messageStore,
+    sessionStore,
+    modelStore,
+    pendingInputStore,
+    chatClient,
+    sessionClient,
+    modelClient,
+    chatInputRef,
+    isReadOnlySession,
+    isSessionViewPreparing,
+    isAcpWorkdirMissing,
+    isGenerating,
+    toast,
+    t
+  } = options
+
+  const message = ref('')
+  const attachedFiles = ref<MessageFile[]>([])
+  let attachmentFilterToken = 0
+
+  const hasInputText = computed(() => Boolean(message.value.trim()))
+  const hasAttachments = computed(() => attachedFiles.value.length > 0)
+  const hasDraftInput = computed(() => hasInputText.value || hasAttachments.value)
+  const isQueueSubmitDisabled = computed(
+    () =>
+      isSessionViewPreparing.value ||
+      isAcpWorkdirMissing.value ||
+      !hasDraftInput.value ||
+      options.hasBlockingInteraction() ||
+      pendingInputStore.isAtCapacity
+  )
+  const isInputSubmitDisabled = computed(
+    () =>
+      isSessionViewPreparing.value ||
+      isAcpWorkdirMissing.value ||
+      options.hasBlockingInteraction() ||
+      (isGenerating.value && pendingInputStore.isAtCapacity) ||
+      !hasDraftInput.value
+  )
+  const disableQueueSteerAction = computed(
+    () =>
+      isSessionViewPreparing.value ||
+      !isGenerating.value ||
+      isAcpWorkdirMissing.value ||
+      options.hasBlockingInteraction()
+  )
+
+  function notifyUnsupportedAudioAttachments(
+    selection: { providerId: string; modelId: string },
+    rejectedAudioFiles: MessageFile[]
+  ) {
+    if (rejectedAudioFiles.length === 0) {
+      return
+    }
+
+    const modelLabel =
+      modelStore.findChatSelectableModel(selection.providerId, selection.modelId)?.model.name ??
+      selection.modelId
+
+    toast({
+      title: t('chat.input.audioInputUnsupportedTitle'),
+      description: t('chat.input.audioInputUnsupportedDescription', {
+        count: rejectedAudioFiles.length,
+        model: modelLabel
+      })
+    })
+  }
+
+  async function prepareFilesForCurrentModel(files: MessageFile[]): Promise<MessageFile[]> {
+    const selection = options.getActiveModelSelection()
+    if (!selection || files.length === 0) {
+      return files
+    }
+
+    try {
+      const capabilities = await modelClient.getCapabilities(
+        selection.providerId,
+        selection.modelId
+      )
+      if (capabilities.supportsAudioInput !== false) {
+        return files
+      }
+
+      const { acceptedFiles, rejectedAudioFiles } = filterUnsupportedAudioAttachments(files, false)
+      notifyUnsupportedAudioAttachments(selection, rejectedAudioFiles)
+      return acceptedFiles
+    } catch (error) {
+      console.warn('[ChatPage] Failed to resolve audio input capability:', error)
+      return files
+    }
+  }
+
+  const getComposerSkillsSnapshot = (): string[] => {
+    return Array.from(new Set(chatInputRef.value?.getPendingSkillsSnapshot?.() ?? []))
+  }
+
+  const clearComposerSkills = () => {
+    chatInputRef.value?.clearPendingSkills?.()
+  }
+
+  const getComposerInlineItemsSnapshot = (): UserMessageInlineItem[] => {
+    return chatInputRef.value?.getInlineItemsSnapshot?.() ?? []
+  }
+
+  const withMessageSkills = (text: string, files: MessageFile[]) => {
+    const activeSkills = getComposerSkillsSnapshot()
+    const inlineItems = getComposerInlineItemsSnapshot()
+    return {
+      text,
+      files,
+      ...(activeSkills.length > 0 ? { activeSkills } : {}),
+      ...(inlineItems.length > 0 ? { inlineItems } : {})
+    }
+  }
+
+  function canSubmitNow(): boolean {
+    if (isReadOnlySession.value) return false
+    if (isSessionViewPreparing.value) return false
+    if (isAcpWorkdirMissing.value) return false
+    if (options.hasBlockingInteraction()) return false
+    return true
+  }
+
+  function beginOutgoingTurnFeedback(sessionId: string, payload: SendMessageInput) {
+    const optimisticUserMessageId = messageStore.addOptimisticUserMessage(sessionId, payload)
+    if (!optimisticUserMessageId) return null
+
+    const pendingAssistantPlaceholderId = options.createPendingAssistantPlaceholder(sessionId)
+    options.beginPlanTurn(sessionId)
+    return { optimisticUserMessageId, pendingAssistantPlaceholderId }
+  }
+
+  async function sendMessageWithOutgoingTurnFeedback(
+    sessionId: string,
+    payload: SendMessageInput,
+    feedback: NonNullable<ReturnType<typeof beginOutgoingTurnFeedback>>
+  ) {
+    try {
+      await chatClient.sendMessage(sessionId, payload)
+    } catch (error) {
+      options.clearPendingAssistantPlaceholder(feedback.pendingAssistantPlaceholderId)
+      messageStore.removeOptimisticMessage(feedback.optimisticUserMessageId, sessionId)
+      console.error('[ChatPage] send message failed:', error)
+    }
+  }
+
+  async function handleManualCompactionCommand(
+    text: string,
+    sessionId: string,
+    restoreRequestId: number
+  ): Promise<boolean> {
+    if (!isManualCompactionCommand(text)) {
+      return false
+    }
+    if (sessionStore.activeSession?.providerId === 'acp') {
+      return false
+    }
+    if (isGenerating.value) {
+      return true
+    }
+    if (!options.canWriteSessionView(sessionId, restoreRequestId)) {
+      return true
+    }
+
+    try {
+      const result = await sessionClient.compactSession(sessionId)
+      if (!options.canWriteSessionView(sessionId, restoreRequestId)) return true
+      const restoredSession = await options.loadMessagesForSession(sessionId)
+      if (!options.canWriteSessionView(sessionId, restoreRequestId) || restoredSession === null) {
+        return true
+      }
+      options.applyRestoredSessionSummary(restoredSession)
+      if (!result.compacted) {
+        toast({
+          title: t('chat.compaction.noopTitle'),
+          description: t('chat.compaction.noopDescription')
+        })
+      }
+    } catch (error) {
+      console.error('[ChatPage] manual compaction failed:', error)
+      toast({
+        title: t('chat.compaction.failedTitle'),
+        description: error instanceof Error ? error.message : String(error),
+        variant: 'destructive'
+      })
+    }
+    return true
+  }
+
+  async function onSubmit() {
+    if (!canSubmitNow()) return
+    const sessionId = options.sessionId()
+    const restoreRequestId = options.currentRestoreRequestId()
+    const text = message.value.trim()
+    const files = (await prepareFilesForCurrentModel([...attachedFiles.value])).map((f) => toRaw(f))
+    if (!options.canWriteSessionView(sessionId, restoreRequestId)) return
+    if (!text && files.length === 0) return
+    const handledCompaction = await handleManualCompactionCommand(text, sessionId, restoreRequestId)
+    if (!options.canWriteSessionView(sessionId, restoreRequestId)) return
+    if (handledCompaction) {
+      if (!isGenerating.value) {
+        message.value = ''
+      }
+      return
+    }
+    const payload = withMessageSkills(text, files)
+    if (isGenerating.value) {
+      await pendingInputStore.queueInput(sessionId, payload)
+      if (!options.canWriteSessionView(sessionId, restoreRequestId)) return
+      message.value = ''
+      attachedFiles.value = []
+      clearComposerSkills()
+      options.schedulePostSubmitScrollToBottom()
+    } else {
+      const feedback = beginOutgoingTurnFeedback(sessionId, payload)
+      if (!feedback) return
+      message.value = ''
+      attachedFiles.value = []
+      clearComposerSkills()
+      options.schedulePostSubmitScrollToBottom()
+      await sendMessageWithOutgoingTurnFeedback(sessionId, payload, feedback)
+    }
+  }
+
+  async function onCommandSubmit(command: string) {
+    if (!canSubmitNow()) return
+    const sessionId = options.sessionId()
+    const restoreRequestId = options.currentRestoreRequestId()
+    const text = command.trim()
+    if (!text) return
+
+    const handledCompaction = await handleManualCompactionCommand(text, sessionId, restoreRequestId)
+    if (!options.canWriteSessionView(sessionId, restoreRequestId)) return
+    if (handledCompaction) {
+      return
+    }
+
+    const files = await prepareFilesForCurrentModel([...attachedFiles.value])
+    if (!options.canWriteSessionView(sessionId, restoreRequestId)) return
+    const payload = withMessageSkills(text, files)
+    if (isGenerating.value) {
+      await pendingInputStore.queueInput(sessionId, payload)
+      if (!options.canWriteSessionView(sessionId, restoreRequestId)) return
+      attachedFiles.value = []
+      clearComposerSkills()
+      options.schedulePostSubmitScrollToBottom()
+      return
+    }
+    const feedback = beginOutgoingTurnFeedback(sessionId, payload)
+    if (!feedback) return
+    attachedFiles.value = []
+    clearComposerSkills()
+    options.schedulePostSubmitScrollToBottom()
+    await sendMessageWithOutgoingTurnFeedback(sessionId, payload, feedback)
+  }
+
+  async function onQueueSubmit() {
+    if (!canSubmitNow()) return
+    const sessionId = options.sessionId()
+    const restoreRequestId = options.currentRestoreRequestId()
+    const text = message.value.trim()
+    const files = (await prepareFilesForCurrentModel([...attachedFiles.value])).map((f) => toRaw(f))
+    if (!options.canWriteSessionView(sessionId, restoreRequestId)) return
+    if (!text && files.length === 0) return
+    const handledCompaction = await handleManualCompactionCommand(text, sessionId, restoreRequestId)
+    if (!options.canWriteSessionView(sessionId, restoreRequestId)) return
+    if (handledCompaction) {
+      return
+    }
+    await pendingInputStore.queueInput(sessionId, withMessageSkills(text, files))
+    if (!options.canWriteSessionView(sessionId, restoreRequestId)) return
+    message.value = ''
+    attachedFiles.value = []
+    clearComposerSkills()
+  }
+
+  async function onSteer() {
+    if (!canSubmitNow()) return
+    const sessionId = options.sessionId()
+    const restoreRequestId = options.currentRestoreRequestId()
+    const text = message.value.trim()
+    const files = (await prepareFilesForCurrentModel([...attachedFiles.value])).map((f) => toRaw(f))
+    if (!options.canWriteSessionView(sessionId, restoreRequestId)) return
+    if (!text && files.length === 0) return
+    const handledCompaction = await handleManualCompactionCommand(text, sessionId, restoreRequestId)
+    if (!options.canWriteSessionView(sessionId, restoreRequestId)) return
+    if (handledCompaction) {
+      return
+    }
+    options.beginPlanTurn(sessionId)
+    await chatClient.steerActiveTurn(sessionId, withMessageSkills(text, files))
+    if (!options.canWriteSessionView(sessionId, restoreRequestId)) return
+    message.value = ''
+    attachedFiles.value = []
+    clearComposerSkills()
+  }
+
+  async function onFilesChange(files: MessageFile[]) {
+    const token = ++attachmentFilterToken
+    const filteredFiles = await prepareFilesForCurrentModel(files)
+    if (token !== attachmentFilterToken) {
+      return
+    }
+
+    attachedFiles.value = filteredFiles
+  }
+
+  /** Drops in-flight attachment filtering when the page unmounts. */
+  function invalidatePendingAttachmentFilter(): void {
+    attachmentFilterToken += 1
+  }
+
+  return {
+    message,
+    attachedFiles,
+    hasDraftInput,
+    isQueueSubmitDisabled,
+    isInputSubmitDisabled,
+    disableQueueSteerAction,
+    onSubmit,
+    onCommandSubmit,
+    onQueueSubmit,
+    onSteer,
+    onFilesChange,
+    invalidatePendingAttachmentFilter
+  }
+}

From b08f35408f23583f7c9145d5194d96ea87c193ff Mon Sep 17 00:00:00 2001
From: zhangmo8 <zhangmo8@users.noreply.github.com>
Date: Thu, 16 Jul 2026 19:37:37 +0800
Subject: [PATCH 09/14] refactor(chat): extract useSessionRestore composable

---
 src/renderer/src/pages/ChatPage.vue           | 100 +++++---------
 .../src/pages/chat-page/useSessionRestore.ts  | 122 ++++++++++++++++++
 2 files changed, 152 insertions(+), 70 deletions(-)
 create mode 100644 src/renderer/src/pages/chat-page/useSessionRestore.ts

diff --git a/src/renderer/src/pages/ChatPage.vue b/src/renderer/src/pages/ChatPage.vue
index 3b0858cdd3..70e3be05c0 100644
--- a/src/renderer/src/pages/ChatPage.vue
+++ b/src/renderer/src/pages/ChatPage.vue
@@ -300,13 +300,13 @@ import { useChatScrollController } from '@/composables/chat/useChatScrollControl
 import { markChatSessionPerformance } from '@/composables/chat/chatSessionPerformance'
 import { type ChatScrollReason, type ChatScrollTarget } from '@/composables/chat/chatScrollState'
 import { playChatInputHeroFlight } from '@/lib/chatInputHero'
-import { scheduleStartupDeferredTask } from '@/lib/startupDeferred'
 import { usePlanFloatLifecycle } from './chat-page/usePlanFloatLifecycle'
 import { useDisplayMessages } from './chat-page/useDisplayMessages'
 import { useChatSearch } from './chat-page/useChatSearch'
 import { useListGestures } from './chat-page/useListGestures'
 import { useMessageVirtualization } from './chat-page/useMessageVirtualization'
 import { useComposerSubmit } from './chat-page/useComposerSubmit'
+import { useSessionRestore } from './chat-page/useSessionRestore'
 import type {
   MessageFile,
   UserMessageInlineItem,
@@ -363,41 +363,23 @@ const isAcpWorkdirMissing = computed(() => {
   return !activeSession.projectDir?.trim()
 })
 
-const applyRestoredSessionSummary = (session: unknown) => {
-  const applyRestoredSession = (
-    sessionStore as typeof sessionStore & {
-      applyRestoredSession?: (session: unknown) => void
-    }
-  ).applyRestoredSession
-
-  if (typeof applyRestoredSession === 'function') {
-    applyRestoredSession(session)
-  }
-}
-
-async function loadMessagesForSession(sessionId: string, count?: number) {
-  const restoredSession = await messageStore.loadMessages(sessionId, count)
-  return restoredSession
-}
-
-async function restoreSessionMessages(id: string, requestId: number) {
-  console.info(`[Startup][Renderer] ChatPage restoring session ${id}`)
-  const pendingInputsPromise = pendingInputStore.loadPendingInputs(id)
-  const restoredSession = await loadMessagesForSession(id, INITIAL_MESSAGE_RESTORE_COUNT)
-
-  if (requestId !== sessionRestoreRequestId) {
-    return
-  }
-
-  if (restoredSession !== null) {
-    applyRestoredSessionSummary(restoredSession)
-  }
-  void pendingInputsPromise.then(() => {
-    if (requestId === sessionRestoreRequestId) {
-      markChatSessionPerformance('secondary-state-ready', id, chatScrollSessionEpoch)
-    }
-  })
-}
+const {
+  applyRestoredSessionSummary,
+  loadMessagesForSession,
+  currentRestoreRequestId,
+  canWriteSessionView,
+  beginSessionChange,
+  scheduleRestore,
+  deactivate: deactivateSessionRestore
+} = useSessionRestore({
+  sessionId: () => props.sessionId,
+  messageStore,
+  sessionStore,
+  pendingInputStore,
+  initialRestoreCount: INITIAL_MESSAGE_RESTORE_COUNT,
+  onSecondaryStateReady: (id) =>
+    markChatSessionPerformance('secondary-state-ready', id, chatScrollSessionEpoch)
+})
 
 // --- Auto-scroll ---
 const scrollContainer = ref<HTMLDivElement | null>(null)
@@ -439,8 +421,6 @@ const SESSION_RESTORE_SCROLL_INTENT_KEYS = new Set([
 const traceMessageId = ref<string | null>(null)
 let spotlightJumpTimer: number | null = null
 let scrollReadFrame: number | null = null
-let cancelSessionRestoreTask: (() => void) | null = null
-let hasScheduledInitialSessionRestore = false
 let cancelPlanUpdatedListener: (() => void) | null = null
 // The immediate session watcher can call clearMessageWindowMeasurements before
 // messageWindow exists; keep this no-op forward reference and rebind it to
@@ -456,8 +436,6 @@ let restoreMessageWindowMeasurements = (snapshot: MessageMeasurementSnapshot) =>
 let clearChatSearchStateRef = () => {}
 let cancelScheduledChatSearchRefreshRef = () => {}
 let measurementSessionId = ''
-let sessionRestoreRequestId = 0
-let isChatPageActive = true
 let handledCommittedSessionId: string | null = null
 type HistoryLayoutAnchor = {
   messageId: string
@@ -656,7 +634,7 @@ async function loadOlderMessagesAtTop(): Promise<void> {
   }
 
   const sessionId = props.sessionId
-  const requestId = sessionRestoreRequestId
+  const requestId = currentRestoreRequestId()
   const previousScrollHeight = el.scrollHeight
   const previousEntryCount = messageWindow.entries.value.length
   // Use a stable row in the virtual layout as the pagination anchor. DOM scrollHeight
@@ -668,7 +646,11 @@ async function loadOlderMessagesAtTop(): Promise<void> {
     ? { messageId: firstExistingEntry.id, layoutTop: firstExistingEntry.top }
     : null
   const loadedCount = await messageStore.loadOlderMessages()
-  if (loadedCount === 0 || props.sessionId !== sessionId || sessionRestoreRequestId !== requestId) {
+  if (
+    loadedCount === 0 ||
+    props.sessionId !== sessionId ||
+    currentRestoreRequestId() !== requestId
+  ) {
     return
   }
 
@@ -685,7 +667,7 @@ async function loadOlderMessagesAtTop(): Promise<void> {
 
   if (!usesWindowedMessages || !historyAnchor || !nextAnchorEntry) {
     await nextTick()
-    if (props.sessionId !== sessionId || sessionRestoreRequestId !== requestId) {
+    if (props.sessionId !== sessionId || currentRestoreRequestId() !== requestId) {
       return
     }
 
@@ -715,7 +697,7 @@ async function loadOlderMessagesAtTop(): Promise<void> {
   scrollViewportHeight.value = container.clientHeight
 
   await nextTick()
-  if (props.sessionId !== sessionId || sessionRestoreRequestId !== requestId) {
+  if (props.sessionId !== sessionId || currentRestoreRequestId() !== requestId) {
     return
   }
 
@@ -889,12 +871,10 @@ watch(
     pendingDeleteMessageId.value = null
     clearChatSearchStateRef()
     resetDisplayMessagesForSessionChange()
-    sessionRestoreRequestId += 1
+    beginSessionChange()
     chatScrollSessionEpoch = chatScrollController.beginSession(id)
     markChatSessionPerformance('selected', id, chatScrollSessionEpoch)
     markChatSessionPerformance('preparation-started', id, chatScrollSessionEpoch)
-    cancelSessionRestoreTask?.()
-    cancelSessionRestoreTask = null
     clearMessageWindowMeasurements()
     const activatedFromCache = id ? (messageStore.activateRecentSessionView?.(id) ?? false) : false
     const cachedMeasurements = activatedFromCache ? recentMessageMeasurementCache.get(id) : null
@@ -907,14 +887,7 @@ watch(
     }
     pendingInputStore.clear()
     if (id) {
-      const requestId = sessionRestoreRequestId
-      const runRestore = () => restoreSessionMessages(id, requestId)
-      if (!hasScheduledInitialSessionRestore) {
-        hasScheduledInitialSessionRestore = true
-        cancelSessionRestoreTask = scheduleStartupDeferredTask(runRestore)
-      } else {
-        void runRestore()
-      }
+      scheduleRestore(id)
       return
     }
   },
@@ -1278,16 +1251,6 @@ function getActiveModelSelection(): { providerId: string; modelId: string } | nu
   }
 }
 
-function canWriteSessionView(sessionId: string, restoreRequestId: number): boolean {
-  return (
-    isChatPageActive &&
-    sessionRestoreRequestId === restoreRequestId &&
-    props.sessionId === sessionId &&
-    messageStore.currentSessionId === sessionId &&
-    messageStore.committedSessionId === sessionId
-  )
-}
-
 const {
   message,
   attachedFiles,
@@ -1303,7 +1266,7 @@ const {
   invalidatePendingAttachmentFilter
 } = useComposerSubmit({
   sessionId: () => props.sessionId,
-  currentRestoreRequestId: () => sessionRestoreRequestId,
+  currentRestoreRequestId,
   canWriteSessionView,
   messageStore,
   sessionStore,
@@ -1539,16 +1502,13 @@ onMounted(() => {
 })
 
 onUnmounted(() => {
-  isChatPageActive = false
-  sessionRestoreRequestId += 1
+  deactivateSessionRestore()
   invalidatePendingAttachmentFilter()
   cacheCurrentMessageMeasurements()
   removeModelConfigChangedListener()
   cancelAllPlanSnapshotClearTimers()
   cancelPlanUpdatedListener?.()
   cancelPlanUpdatedListener = null
-  cancelSessionRestoreTask?.()
-  cancelSessionRestoreTask = null
   voiceInput.cleanup()
   window.removeEventListener('context-menu-ask-ai', handleContextMenuAskAI)
   window.removeEventListener(
diff --git a/src/renderer/src/pages/chat-page/useSessionRestore.ts b/src/renderer/src/pages/chat-page/useSessionRestore.ts
new file mode 100644
index 0000000000..7eb8d0de60
--- /dev/null
+++ b/src/renderer/src/pages/chat-page/useSessionRestore.ts
@@ -0,0 +1,122 @@
+import type { useMessageStore } from '@/stores/ui/message'
+import type { useSessionStore } from '@/stores/ui/session'
+import type { usePendingInputStore } from '@/stores/ui/pendingInput'
+import { scheduleStartupDeferredTask } from '@/lib/startupDeferred'
+
+type MessageStore = ReturnType<typeof useMessageStore>
+type SessionStore = ReturnType<typeof useSessionStore>
+type PendingInputStore = ReturnType<typeof usePendingInputStore>
+
+type UseSessionRestoreOptions = {
+  sessionId: () => string
+  messageStore: MessageStore
+  sessionStore: SessionStore
+  pendingInputStore: PendingInputStore
+  /** How many messages the initial restore of a session fetches. */
+  initialRestoreCount: number
+  /** Fired when pending inputs finish loading while the restore is still current. */
+  onSecondaryStateReady: (sessionId: string) => void
+}
+
+/**
+ * Owns the session-restore epoch. Every async write into the session view must
+ * capture `currentRestoreRequestId()` before its first await and re-check via
+ * `canWriteSessionView` after each one; `beginSessionChange` / `deactivate`
+ * bump the epoch so captured tokens from a previous session (or an unmounted
+ * page) can never win the race. The first restore after startup is deferred
+ * until the window is idle; later session switches restore immediately.
+ */
+export function useSessionRestore(options: UseSessionRestoreOptions) {
+  const { messageStore, sessionStore, pendingInputStore } = options
+
+  let restoreRequestId = 0
+  let isViewActive = true
+  let cancelScheduledRestore: (() => void) | null = null
+  let hasScheduledInitialRestore = false
+
+  const applyRestoredSessionSummary = (session: unknown) => {
+    const applyRestoredSession = (
+      sessionStore as typeof sessionStore & {
+        applyRestoredSession?: (session: unknown) => void
+      }
+    ).applyRestoredSession
+
+    if (typeof applyRestoredSession === 'function') {
+      applyRestoredSession(session)
+    }
+  }
+
+  async function loadMessagesForSession(sessionId: string, count?: number) {
+    const restoredSession = await messageStore.loadMessages(sessionId, count)
+    return restoredSession
+  }
+
+  async function restoreSessionMessages(id: string, requestId: number) {
+    console.info(`[Startup][Renderer] ChatPage restoring session ${id}`)
+    const pendingInputsPromise = pendingInputStore.loadPendingInputs(id)
+    const restoredSession = await loadMessagesForSession(id, options.initialRestoreCount)
+
+    if (requestId !== restoreRequestId) {
+      return
+    }
+
+    if (restoredSession !== null) {
+      applyRestoredSessionSummary(restoredSession)
+    }
+    void pendingInputsPromise.then(() => {
+      if (requestId === restoreRequestId) {
+        options.onSecondaryStateReady(id)
+      }
+    })
+  }
+
+  function currentRestoreRequestId(): number {
+    return restoreRequestId
+  }
+
+  function canWriteSessionView(sessionId: string, requestId: number): boolean {
+    return (
+      isViewActive &&
+      restoreRequestId === requestId &&
+      options.sessionId() === sessionId &&
+      messageStore.currentSessionId === sessionId &&
+      messageStore.committedSessionId === sessionId
+    )
+  }
+
+  /** Invalidates in-flight restores and drops any still-deferred restore task. */
+  function beginSessionChange(): void {
+    restoreRequestId += 1
+    cancelScheduledRestore?.()
+    cancelScheduledRestore = null
+  }
+
+  function scheduleRestore(id: string): void {
+    const requestId = restoreRequestId
+    const runRestore = () => restoreSessionMessages(id, requestId)
+    if (!hasScheduledInitialRestore) {
+      hasScheduledInitialRestore = true
+      cancelScheduledRestore = scheduleStartupDeferredTask(runRestore)
+    } else {
+      void runRestore()
+    }
+  }
+
+  /** Unmount path: closes the write gate for every captured token. */
+  function deactivate(): void {
+    isViewActive = false
+    restoreRequestId += 1
+    cancelScheduledRestore?.()
+    cancelScheduledRestore = null
+  }
+
+  return {
+    applyRestoredSessionSummary,
+    loadMessagesForSession,
+    currentRestoreRequestId,
+    canWriteSessionView,
+    beginSessionChange,
+    scheduleRestore,
+    deactivate
+  }
+}

From 8cf08065c8c45e8807f82017158455c61e7f305d Mon Sep 17 00:00:00 2001
From: zhangmo8 <zhangmo8@users.noreply.github.com>
Date: Thu, 16 Jul 2026 19:56:00 +0800
Subject: [PATCH 10/14] docs(chat): record placeholder merge decision in spec

---
 docs/architecture/chatpage-decomposition/spec.md | 14 +++++++++-----
 1 file changed, 9 insertions(+), 5 deletions(-)

diff --git a/docs/architecture/chatpage-decomposition/spec.md b/docs/architecture/chatpage-decomposition/spec.md
index 418d267ae4..743f4a6835 100644
--- a/docs/architecture/chatpage-decomposition/spec.md
+++ b/docs/architecture/chatpage-decomposition/spec.md
@@ -31,18 +31,22 @@
 - `composables/message/useMessageScroll.ts`（339 行）— 全项目零引用，旧 vue-virtual-scroller 实现。
 - `composables/message/types.ts` 中的 `ScrollInfo` 接口 — 仅被上文件引用（`CaptureOptions` 仍在用，保留）。
 
-## 分解目标（7 个 composable）
+## 分解目标（8 个关注点 → 7 个 composable）
 
 | composable | 职责 | 收编的状态/竞态 |
 |---|---|---|
-| `useSessionRestore` | 会话切换、令牌 gate、恢复 | `sessionRestoreRequestId`、`canWriteSessionView`、恢复 watch |
-| `useDisplayMessages` | 记录→DisplayMessage、稳定/流式分离、缓存 | `displayMessageCache`、`assistantRenderKeyByMessageId` |
-| `useAssistantPlaceholder` | 占位符四态机 + renderKey 交接 | `pendingAssistantPlaceholder` 全套 |
+| `useSessionRestore` | 会话切换、令牌 gate、恢复 | `sessionRestoreRequestId`、`canWriteSessionView`、启动延迟恢复调度 |
+| `useDisplayMessages` | 记录→DisplayMessage、稳定/流式分离、缓存；**并含占位符四态机** | `displayMessageCache`、`assistantRenderKeyByMessageId`、`pendingAssistantPlaceholder` 全套 |
 | `useMessageVirtualization` | 窗口范围、测量批处理、锚点补偿、几何观测 | `pendingMeasureQueue`、rAF flush |
 | `useListGestures` | wheel/touch/pointer/键盘手势 → 控制器 | ~15 handler、`isListScrolling` |
 | `usePlanFloatLifecycle` | Plan 快照跨会话生命周期 + 延迟清除 | `planSnapshotClearTimers`、3 lifecycleKey |
 | `useChatSearch` | 会话内搜索（包 `lib/chatSearch`） | 搜索 rAF、highlight 调度 |
-| `useComposerSubmit` | 发送/排队/steer/命令/compaction | 统一 gate 后的提交路径 |
+| `useComposerSubmit` | 发送/排队/steer/命令/compaction | 统一 gate 后的提交路径、`attachmentFilterToken` |
+
+> 决策记录：原计划独立的 `useAssistantPlaceholder` 并入 `useDisplayMessages`。占位符的
+> renderKey 交接直接写入消息转换缓存读取的 `assistantRenderKeyByMessageId`，显隐判定依赖
+> `hasFirstStreamingContent` / `ephemeralRateLimitBlock`，占位符行本身注入流式尾部组装；
+> 强拆会造成两个 composable 双向共享三份可变状态，不如单一所有者边界清晰。
 
 ## 约束
 

From 3b32780a2869407b4a43863d8a7b7bcc7cdbf1e8 Mon Sep 17 00:00:00 2001
From: zhangmo8 <zhangmo8@users.noreply.github.com>
Date: Thu, 16 Jul 2026 20:08:36 +0800
Subject: [PATCH 11/14] docs(chat): add chatpage-decomposition plan and tasks

---
 .../chatpage-decomposition/plan.md            | 32 +++++++++++++++++++
 .../chatpage-decomposition/tasks.md           | 16 ++++++++++
 2 files changed, 48 insertions(+)
 create mode 100644 docs/architecture/chatpage-decomposition/plan.md
 create mode 100644 docs/architecture/chatpage-decomposition/tasks.md

diff --git a/docs/architecture/chatpage-decomposition/plan.md b/docs/architecture/chatpage-decomposition/plan.md
new file mode 100644
index 0000000000..09d8e12d75
--- /dev/null
+++ b/docs/architecture/chatpage-decomposition/plan.md
@@ -0,0 +1,32 @@
+# Plan: ChatPage 分解与竞态治理
+
+## 实施顺序
+
+按"每抽一个 composable 即 typecheck + 测试"的节奏,从耦合最少的关注点开始,
+逐步收编模块级令牌;滚动仲裁族(`useChatScrollController` 等)保持不动,只归拢胶水调用。
+
+1. **死代码清理** — 删除零引用的 `composables/message/useMessageScroll.ts`(339 行,
+   旧 vue-virtual-scroller 实现)及其孤儿测试、`ScrollInfo` 类型。
+2. **useDisplayMessages + usePlanFloatLifecycle** — 记录→DisplayMessage 转换、
+   稳定/流式分离、占位符四态机(见 spec 决策记录)、Plan 快照生命周期。
+3. **useChatSearch** — 会话内搜索,包装 `lib/chatSearch` 的 rAF/highlight 调度。
+4. **useListGestures + useMessageVirtualization** — 手势原子与虚拟化原子,
+   再组合接入主文件;composable 声明顺序移到会话 watch 之前。
+5. **useComposerSubmit** — 发送/排队/steer/命令/compaction 统一提交路径,
+   自持 `attachmentFilterToken`;四个提交入口的重复守卫收敛为 `canSubmitNow()`。
+6. **useSessionRestore** — 会话恢复 epoch(`restoreRequestId`)、`canWriteSessionView`
+   写 gate、启动延迟恢复调度、`deactivate()` 卸载语义;主文件通过
+   `currentRestoreRequestId()` 读取最新令牌。
+
+## 验证策略
+
+- 每步:`pnpm run typecheck:web` + `ChatPage.test.ts`(82 用例)。
+- 收尾:`pnpm run format` / `lint` / `i18n` / `test:renderer` 全量,
+  与 origin/dev 对照隔离既有失败。
+- 行为零漂移由测试 + 逐行 diff 审查共同保证;竞态令牌语义(闭包内最新值 vs 快照)
+  单独走一轮对抗性 review。
+
+## 回滚
+
+每个 composable 一个独立 commit,可单独 revert;滚动仲裁契约未动,
+回滚任一步不影响其他步骤。
diff --git a/docs/architecture/chatpage-decomposition/tasks.md b/docs/architecture/chatpage-decomposition/tasks.md
new file mode 100644
index 0000000000..beb4437ae5
--- /dev/null
+++ b/docs/architecture/chatpage-decomposition/tasks.md
@@ -0,0 +1,16 @@
+# Tasks: ChatPage 分解与竞态治理
+
+- [x] 写 `spec.md` / `plan.md` / `tasks.md`
+- [x] 删除死代码 `useMessageScroll.ts`(339 行)+ 孤儿测试 + `ScrollInfo` 类型
+- [x] 抽取 `useDisplayMessages`(含占位符四态机,见 spec 决策记录)
+- [x] 抽取 `usePlanFloatLifecycle`
+- [x] 抽取 `useChatSearch`
+- [x] 抽取 `useListGestures` / `useMessageVirtualization` 原子并组合接入
+- [x] composable 声明顺序移到会话 watch 之前
+- [x] 抽取 `useComposerSubmit`(自持 `attachmentFilterToken`,守卫收敛 `canSubmitNow()`)
+- [x] 抽取 `useSessionRestore`(自持 `restoreRequestId` epoch + `deactivate()` 卸载语义)
+- [x] `useAssistantPlaceholder` 决策:并入 `useDisplayMessages`,不单独成文件(spec 有记录)
+- [x] 全量验证:typecheck / lint / format / i18n / `ChatPage.test.ts` 82 用例
+- [x] 合并 origin/dev 并复核(Settings/Provider/sidepanel 的 18 个失败为 dev 既有,与本分支无关)
+- [ ] 后续(可选):主文件继续向 ~400 行收缩(语音输入、消息操作 handler、
+      工具交互 respond 等仍在主文件;当前 ~1710 行,较 3050 行已收缩 44%)

From d9fa944cbca9fe17bc7d17cafc01b6c3aa9f68cc Mon Sep 17 00:00:00 2001
From: zhangmo8 <zhangmo8@users.noreply.github.com>
Date: Fri, 17 Jul 2026 07:49:59 +0800
Subject: [PATCH 12/14] fix(chat): restore plan float linger reactivity

---
 .../pages/chat-page/usePlanFloatLifecycle.ts    | 17 +++++++++++------
 1 file changed, 11 insertions(+), 6 deletions(-)

diff --git a/src/renderer/src/pages/chat-page/usePlanFloatLifecycle.ts b/src/renderer/src/pages/chat-page/usePlanFloatLifecycle.ts
index 580f6ed62f..26981708f3 100644
--- a/src/renderer/src/pages/chat-page/usePlanFloatLifecycle.ts
+++ b/src/renderer/src/pages/chat-page/usePlanFloatLifecycle.ts
@@ -1,4 +1,4 @@
-import { computed, watch, type ComputedRef, type Ref } from 'vue'
+import { computed, ref, watch, type ComputedRef, type Ref } from 'vue'
 import type { useAgentPlanStore } from '@/stores/ui/agentPlan'
 import type { useSessionStore } from '@/stores/ui/session'
 
@@ -33,7 +33,10 @@ export function usePlanFloatLifecycle(options: UsePlanFloatLifecycleOptions) {
   const { agentPlanStore, sessionStore, isCurrentSessionStreaming, pendingInteractions } = options
   const currentSessionId = () => options.sessionId()
 
-  const planFloatLingerBySession: Record<string, boolean> = {}
+  // Reactive on purpose: latestPlanSnapshot must recompute when the linger flag
+  // flips in the post-flush lifecycle watch, or the float vanishes instead of
+  // lingering after a session completes. Writes replace the whole object.
+  const planFloatLingerBySession = ref<Record<string, boolean>>({})
   const planSnapshotClearTimers = new Map<string, number>()
 
   function readSessionStatus(sessionId: string): 'working' | 'completed' | 'error' | 'none' | null {
@@ -57,20 +60,22 @@ export function usePlanFloatLifecycle(options: UsePlanFloatLifecycleOptions) {
   }
 
   function isPlanFloatLingerActive(sessionId: string): boolean {
-    return planFloatLingerBySession[sessionId] === true
+    return planFloatLingerBySession.value[sessionId] === true
   }
 
   function setPlanFloatLingerActive(sessionId: string, active: boolean): void {
-    const current = planFloatLingerBySession[sessionId] === true
+    const current = planFloatLingerBySession.value[sessionId] === true
     if (current === active) {
       return
     }
 
+    const next = { ...planFloatLingerBySession.value }
     if (active) {
-      planFloatLingerBySession[sessionId] = true
+      next[sessionId] = true
     } else {
-      delete planFloatLingerBySession[sessionId]
+      delete next[sessionId]
     }
+    planFloatLingerBySession.value = next
   }
 
   function shouldShowPlanSnapshotForSession(sessionId: string): boolean {

From 62d863986bb4cd02dea09b0f8139f7e03290afbe Mon Sep 17 00:00:00 2001
From: zhangmo8 <zhangmo8@users.noreply.github.com>
Date: Fri, 17 Jul 2026 07:57:43 +0800
Subject: [PATCH 13/14] docs(chat): record review findings in tasks

---
 docs/architecture/chatpage-decomposition/tasks.md | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/docs/architecture/chatpage-decomposition/tasks.md b/docs/architecture/chatpage-decomposition/tasks.md
index beb4437ae5..c84570e376 100644
--- a/docs/architecture/chatpage-decomposition/tasks.md
+++ b/docs/architecture/chatpage-decomposition/tasks.md
@@ -11,6 +11,9 @@
 - [x] 抽取 `useSessionRestore`(自持 `restoreRequestId` epoch + `deactivate()` 卸载语义)
 - [x] `useAssistantPlaceholder` 决策:并入 `useDisplayMessages`,不单独成文件(spec 有记录)
 - [x] 全量验证:typecheck / lint / format / i18n / `ChatPage.test.ts` 82 用例
+- [x] 对抗性 review(逐行对照基线 `8b121ede8`):发现并修复 `usePlanFloatLifecycle`
+      中 linger 状态从 `ref` 降级为普通对象导致的响应性回归(完成后浮窗不再驻留 1200ms);
+      其余确认零漂移
 - [x] 合并 origin/dev 并复核(Settings/Provider/sidepanel 的 18 个失败为 dev 既有,与本分支无关)
 - [ ] 后续(可选):主文件继续向 ~400 行收缩(语音输入、消息操作 handler、
       工具交互 respond 等仍在主文件;当前 ~1710 行,较 3050 行已收缩 44%)

From 5d055fb387c323dde1a9d10097372975a8997d75 Mon Sep 17 00:00:00 2001
From: zhangmo8 <zhangmo8@users.noreply.github.com>
Date: Fri, 17 Jul 2026 08:58:16 +0800
Subject: [PATCH 14/14] docs(chat): clarify rollback order and module location

---
 docs/architecture/chatpage-decomposition/plan.md | 6 ++++--
 docs/architecture/chatpage-decomposition/spec.md | 8 ++++++++
 2 files changed, 12 insertions(+), 2 deletions(-)

diff --git a/docs/architecture/chatpage-decomposition/plan.md b/docs/architecture/chatpage-decomposition/plan.md
index 09d8e12d75..a64217b489 100644
--- a/docs/architecture/chatpage-decomposition/plan.md
+++ b/docs/architecture/chatpage-decomposition/plan.md
@@ -28,5 +28,7 @@
 
 ## 回滚
 
-每个 composable 一个独立 commit,可单独 revert;滚动仲裁契约未动,
-回滚任一步不影响其他步骤。
+每个 composable 一个独立 commit。因抽取提交之间存在依赖(后一个 composable 的接入
+依赖前面已建立的装配结构与导入),回滚须按提交的**逆序**进行,或连同依赖它的后续
+提交一并回滚,不能孤立 revert 中间某一步。滚动仲裁契约(`useChatScrollController`
+及其协作模块)全程未动,整体回滚到基线不影响该子系统。
diff --git a/docs/architecture/chatpage-decomposition/spec.md b/docs/architecture/chatpage-decomposition/spec.md
index 743f4a6835..b4d9f444e1 100644
--- a/docs/architecture/chatpage-decomposition/spec.md
+++ b/docs/architecture/chatpage-decomposition/spec.md
@@ -54,3 +54,11 @@
 - 不改 `useChatScrollController` 及其协作模块的对外时序契约。
 - 优先 shadcn-vue / VueUse（`useEventListener`、`useRafFn` 等）替代手写 rAF/监听器。
 - i18n key 不新增；用户可见字符串沿用现有 key。
+
+## 模块位置决策
+
+7 个 composable 放在 `pages/chat-page/` 而非全局 `lib/` / `components/`，是有意的
+feature-local 布局：它们是 `ChatPage.vue` 独占的私有逻辑，强耦合页面 props 与页面级
+store 组合，不面向复用。就近放置能让读者一眼看出归属、避免误当作通用工具被其他页面引用。
+`lint:architecture` guard 通过（未对该布局设硬约束）。若后续有第二个页面需要复用其中某个
+composable，再将其上提到 `lib/` 并补通用化改造。