feat: optimize chat think

packages/client/AGENTS.md

@@ -51,7 +51,7 @@ Non-negotiables across the layers:
 
 - **Business data lives in the object layer, never a store.** Entry-declared stores carry shared viewing/interaction state (selection, drafts, panel widths); sessions, frames, and connections stay in the object layer.
 - **rpcId is strictly bidirectional**: the initiator mints, the responder echoes; business signatures see only `RpcRequest<P>`, minting stays in the carrier layer ([layering and RPC protocol note](../../.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md)).
-- **Notifier dual-channel discipline**: `notifyNow` only as the direct echo of a user gesture; frame-driven updates always go through `markDirty` (microtask-batched). See `runtime/src/client/sessions/notifier.ts`.
+- **Notifier publication discipline**: `notifyNow` is only the direct echo of a user gesture; structural updates use microtask-batched `markDirty`, while visible streaming chunks use cumulative `markFrameDirty`. See `runtime/src/client/sessions/notifier.ts`.
 - **The web layer is pure presentation.** Nothing that is "how to draw" (tool-card views, queue states) enters the session log; the host computes such data per frame or pushes it live, and replay recomputes it — falling back to the generic form when it can't. A new *model-visible* input still requires a session event (repo-wide rule).
 
 ## Directory regime (plugin packages)

packages/client/runtime/src/client/session-history/source.ts

@@ -8,7 +8,7 @@ import type {
 } from '../contract/session-history.ts'
 import { createHistoryInspection } from '../sessions/history.ts'
 import { Notifier } from '../sessions/notifier.ts'
-import { PartialAccumulator } from '../sessions/partial.ts'
+import { isVisibleAssistantChunk, PartialAccumulator } from '../sessions/partial.ts'
 
 const HISTORY_PAGE_MESSAGES = 50
 
@@ -431,11 +431,3 @@ export class SessionHistorySource implements SessionHistoryFace {
     return this.inspectionCache.value
   }
 }
-
-function isVisibleAssistantChunk(type: string): boolean {
-  return type === 'block-start'
-    || type === 'text-delta'
-    || type === 'reasoning-delta'
-    || type === 'tool-call-delta'
-    || type === 'block-end'
-}

packages/client/runtime/src/client/sessions/notifier.ts

@@ -1,5 +1,6 @@
-// Notifier: subscription + microtask-batched notification primitive shared by Session and
-// SessionManager. Semantics: N markDirty calls collapse into one microtask flush;
+// Notifier: subscription + batched notification primitive shared by Session and
+// SessionManager. Semantics: N markDirty calls collapse into one microtask flush, while
+// N markFrameDirty calls collapse into one animation-frame flush;
 // the flush rebuilds the snapshot cache BEFORE notifying (useSyncExternalStore requires a stable
 // getSnapshot reference). With no listeners the rebuild is skipped and only the dirty bit is set
 // (keeps frame storms cheap); the next getSnapshot rebuilds lazily.
@@ -9,12 +10,13 @@
 // swallow the notification — push subscribers (object-layer watchers) would
 // otherwise starve whenever any reader pulls first.
 
-/** Subscription + microtask-batched notification primitive (shared by Session and SessionManager). */
+/** Subscription + batched notification primitive (shared by Session and SessionManager). */
 export class Notifier {
   private listeners = new Set<() => void>()
   private dirty = false
   private notifyPending = false
-  private scheduled = false
+  private scheduled: 'none' | 'microtask' | 'frame' = 'none'
+  private scheduleGeneration = 0
 
   /** @param rebuild - snapshot rebuild function injected by the owner (writes the owner's snapshotCache). */
   constructor(private readonly rebuild: () => void) {}
@@ -35,19 +37,16 @@ export class Notifier {
   markDirty(): void {
     this.dirty = true
     this.notifyPending = true
-    if (this.scheduled) return
-    this.scheduled = true
-    queueMicrotask(() => {
-      this.scheduled = false
-      if (!this.notifyPending) return
-      if (this.listeners.size === 0) return // lazy: no subscribers; dirty (if still set) rebuilds on next getSnapshot
-      this.notifyPending = false
-      if (this.dirty) {
-        this.dirty = false
-        this.rebuild()
-      }
-      for (const listener of this.listeners) listener()
-    })
+    if (this.scheduled === 'microtask') return
+    this.schedule('microtask')
+  }
+
+  /** Stream-change entry: mark dirty and publish the cumulative state at most once per frame. */
+  markFrameDirty(): void {
+    this.dirty = true
+    this.notifyPending = true
+    if (this.scheduled !== 'none') return
+    this.schedule(typeof globalThis.requestAnimationFrame === 'function' ? 'frame' : 'microtask')
   }
 
   /**
@@ -57,11 +56,8 @@ export class Notifier {
   notifyNow(): void {
     this.dirty = true
     this.notifyPending = true
-    if (this.listeners.size === 0) return // lazy: same as markDirty, next getSnapshot rebuilds
-    this.notifyPending = false
-    this.dirty = false
-    this.rebuild()
-    for (const listener of this.listeners) listener()
+    this.invalidateSchedule()
+    this.flush()
   }
 
   /**
@@ -73,4 +69,35 @@ export class Notifier {
     this.dirty = false
     this.rebuild()
   }
+
+  private schedule(kind: 'microtask' | 'frame'): void {
+    const generation = ++this.scheduleGeneration
+    this.scheduled = kind
+    const publish = () => {
+      if (generation !== this.scheduleGeneration) return
+      this.scheduled = 'none'
+      this.flush()
+    }
+    if (kind === 'frame') {
+      globalThis.requestAnimationFrame(publish)
+    } else {
+      queueMicrotask(publish)
+    }
+  }
+
+  private invalidateSchedule(): void {
+    this.scheduleGeneration++
+    this.scheduled = 'none'
+  }
+
+  private flush(): void {
+    if (!this.notifyPending) return
+    if (this.listeners.size === 0) return // lazy: dirty (if still set) rebuilds on next getSnapshot
+    this.notifyPending = false
+    if (this.dirty) {
+      this.dirty = false
+      this.rebuild()
+    }
+    for (const listener of this.listeners) listener()
+  }
 }

packages/client/runtime/src/client/sessions/partial.ts

@@ -6,6 +6,19 @@ import type { StreamChunk } from '@deepseek-ai/dsh-llm/types'
 import type { AssistantBlock, PartialAssistant } from './conversation.ts'
 import { toAssistantBlock } from './conversation.ts'
 
+/**
+ * Whether a stream chunk changes the partial assistant projection shown by the UI.
+ * @param type - Stream chunk discriminant.
+ * @returns Whether publishing the accumulated partial can change the visible snapshot.
+ */
+export function isVisibleAssistantChunk(type: string): boolean {
+  return type === 'block-start'
+    || type === 'text-delta'
+    || type === 'reasoning-delta'
+    || type === 'tool-call-delta'
+    || type === 'block-end'
+}
+
 /** assistant/chunk accumulator: folds StreamChunks into AssistantBlock[] with block-level immutability. */
 export class PartialAccumulator {
   // Sparse on purpose: block-start may arrive out of order, leaving holes until compaction.

packages/client/runtime/src/client/sessions/session.ts

@@ -21,7 +21,7 @@ import { PendingWait } from './pending.ts'
 import { TranscriptAdapter } from './transcript-adapter.ts'
 import { displayFailureMessage } from './failure-display.ts'
 import { Notifier } from './notifier.ts'
-import { PartialAccumulator } from './partial.ts'
+import { isVisibleAssistantChunk, PartialAccumulator } from './partial.ts'
 import { ProjectionValueStore } from './projection-store.ts'
 import type { ProjectionsBaseline } from './projection-store.ts'
 
@@ -687,6 +687,10 @@ export class Session implements SessionFace {
       return
     }
     this.appendLive(event, view)
+    if (event.type === 'assistant/chunk') {
+      if (isVisibleAssistantChunk(event.data.chunk.type)) this.notifier.markFrameDirty()
+      return
+    }
     this.notifier.markDirty()
   }
 

packages/client/runtime/tests/notifier.spec.ts

@@ -1,13 +1,17 @@
 /**
- * Notifier: microtask batching, rebuild-before-notify ordering, no-listener
- * laziness, synchronous notifyNow, and unsubscribe.
+ * Notifier: microtask/frame batching, rebuild-before-notify ordering,
+ * no-listener laziness, synchronous notifyNow, and unsubscribe.
  */
 
-import { describe, expect, it } from 'vitest'
+import { afterEach, describe, expect, it, vi } from 'vitest'
 import { Notifier } from '../src/client/sessions/notifier.ts'
 
 const microtask = (): Promise<void> => new Promise((resolve) => { queueMicrotask(resolve) })
 
+afterEach(() => {
+  vi.unstubAllGlobals()
+})
+
 describe('Notifier', () => {
   it('collapses N markDirty calls into one flush, rebuilding before notifying', async () => {
     const order: string[] = []
@@ -60,6 +64,57 @@ describe('Notifier', () => {
     expect(rebuilds).toBe(1)
   })
 
+  it('collapses frame-dirty changes into one cumulative frame publication', () => {
+    const frames: FrameRequestCallback[] = []
+    vi.stubGlobal('requestAnimationFrame', (callback: FrameRequestCallback) => {
+      frames.push(callback)
+      return frames.length
+    })
+    const order: string[] = []
+    const notifier = new Notifier(() => order.push('rebuild'))
+    notifier.subscribe(() => order.push('notify'))
+
+    notifier.markFrameDirty()
+    notifier.markFrameDirty()
+    notifier.markFrameDirty()
+
+    expect(order).toEqual([])
+    expect(frames).toHaveLength(1)
+    frames.shift()!(0)
+    expect(order).toEqual(['rebuild', 'notify'])
+  })
+
+  it('lets a structural microtask publication supersede a pending frame', async () => {
+    const frames: FrameRequestCallback[] = []
+    vi.stubGlobal('requestAnimationFrame', (callback: FrameRequestCallback) => {
+      frames.push(callback)
+      return frames.length
+    })
+    let notifications = 0
+    const notifier = new Notifier(() => undefined)
+    notifier.subscribe(() => { notifications++ })
+
+    notifier.markFrameDirty()
+    notifier.markDirty()
+    await microtask()
+    expect(notifications).toBe(1)
+
+    frames.shift()!(0)
+    expect(notifications).toBe(1)
+  })
+
+  it('falls back to microtask batching when animation frames are unavailable', async () => {
+    let notifications = 0
+    const notifier = new Notifier(() => undefined)
+    notifier.subscribe(() => { notifications++ })
+
+    notifier.markFrameDirty()
+    notifier.markFrameDirty()
+    expect(notifications).toBe(0)
+    await microtask()
+    expect(notifications).toBe(1)
+  })
+
   it('unsubscribed listeners stop receiving notifications', async () => {
     let calls = 0
     const notifier = new Notifier(() => undefined)

packages/client/runtime/tests/session.spec.ts

@@ -6,7 +6,7 @@
  * enough.
  */
 
-import { describe, expect, it, vi } from 'vitest'
+import { afterEach, describe, expect, it, vi } from 'vitest'
 import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
 import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
 import type { SessionId } from '@deepseek-ai/dsh-client-connection/client'
@@ -20,6 +20,10 @@ const at = (seq: number, e: Record<string, unknown>): SessionEvent =>
 const SID = 'fk-s1' as SessionId
 const PARENT = 'fk-parent' as SessionId
 
+afterEach(() => {
+  vi.unstubAllGlobals()
+})
+
 function makeSession(api = new FakeApiClient()): { api: FakeApiClient; session: Session } {
   return { api, session: new Session(SID, api) }
 }
@@ -163,6 +167,40 @@ describe('live event path', () => {
     expect((last as { interrupted?: true }).interrupted).toBeUndefined()
   })
 
+  it('publishes cumulative chunks once per frame and lets finalization supersede the pending frame', async () => {
+    const frames: FrameRequestCallback[] = []
+    vi.stubGlobal('requestAnimationFrame', (callback: FrameRequestCallback) => {
+      frames.push(callback)
+      return frames.length
+    })
+    const { session } = await opened()
+    const published: Array<string | null> = []
+    session.subscribe(() => {
+      const block = session.getSnapshot().partial?.blocks[0]
+      published.push(block?.kind === 'text' ? block.text : null)
+    })
+    const feed = (event: SessionEvent) => {
+      session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event })
+    }
+
+    feed(ev.chunkStart(6, 1))
+    feed(ev.chunkText(7, 1, '累'))
+    feed(ev.chunkText(8, 1, '计'))
+    expect(published).toEqual([])
+    expect(frames).toHaveLength(1)
+
+    frames.shift()!(0)
+    expect(published).toEqual(['累计'])
+
+    feed(ev.chunkText(9, 1, '完成'))
+    feed(ev.assistant(10, 1, '累计完成'))
+    await Promise.resolve()
+    expect(published).toEqual(['累计', null])
+
+    frames.shift()!(0)
+    expect(published).toEqual(['累计', null])
+  })
+
   it('retracts the failed step partial on retry and keeps a replayable notice before the recovered response', async () => {
     const { session } = await opened()
     const feed = (event: SessionEvent) => { session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event }) }

packages/client/ui-conversation/src/client/chat/ToolRow.tsx

@@ -20,7 +20,7 @@
 // independent); an error row's collapsed summary is the failure's first line in
 // the error color.
 
-import { useLayoutEffect, useRef, useState, type KeyboardEvent, type MouseEvent, type ReactNode } from 'react'
+import { useEffect, useRef, useState, type KeyboardEvent, type MouseEvent, type ReactNode } from 'react'
 import clsx from 'clsx'
 import {
   CodeBlock, DiffBlock, ReadBlock, SearchBlock, StateDot, TerminalBlock, WebBlock,
@@ -33,6 +33,7 @@ import { CHAT_SEARCH_MAX_LINES, type SearchCardModel } from '../contract/search-
 import { terminalBlockLabels, type TerminalCardModel } from '../contract/terminal-card-model.ts'
 import type { ToolRowState, ToolRowVariant } from '../contract/tool-call-model.ts'
 import { DisclosureRow } from './DisclosureRow.tsx'
+import { useThrottledVisualUpdate } from './use-throttled-visual-update.ts'
 import css from './ToolRow.module.css'
 
 export interface ToolRowProps {
@@ -176,13 +177,17 @@ export function ToolRow({
   const fileLink = filePath !== undefined && onOpenFile !== undefined && failureLine === null
   const isThink = variant === 'think'
   const followSummaryEnd = isThink && state === 'running' && !open
-  useLayoutEffect(() => {
+  const scheduleSummaryScroll = useThrottledVisualUpdate(() => {
     const summaryElement = summaryRef.current
     if (summaryElement === null) return
     summaryElement.scrollLeft = followSummaryEnd
       ? summaryElement.scrollWidth - summaryElement.clientWidth
       : 0
-  }, [followSummaryEnd, summaryText])
+  })
+  useEffect(() => {
+    if (!isThink) return
+    scheduleSummaryScroll()
+  }, [followSummaryEnd, isThink, scheduleSummaryScroll, summaryText])
   const toggleExpand = () => {
     setExpanded(v => !v)
   }

packages/client/ui-conversation/src/client/chat/use-throttled-visual-update.ts

@@ -0,0 +1,42 @@
+/** Frame-throttled scheduling for non-essential visual alignment. */
+
+import { useCallback, useLayoutEffect, useRef } from 'react'
+
+const DEFAULT_INTERVAL_FRAMES = 3
+
+/**
+ * Return a stable scheduler that coalesces visual updates over a frame interval.
+ * Repeated calls retain the latest callback, and unmount cancels pending work.
+ * @param update - DOM alignment to run after the throttle interval.
+ * @param intervalFrames - Frames to wait before applying the latest alignment.
+ * @returns a stable function that schedules the latest update.
+ */
+export function useThrottledVisualUpdate(
+  update: () => void,
+  intervalFrames = DEFAULT_INTERVAL_FRAMES,
+): () => void {
+  const updateRef = useRef(update)
+  updateRef.current = update
+  const pendingFrameRef = useRef<number | null>(null)
+
+  useLayoutEffect(() => () => {
+    if (pendingFrameRef.current === null) return
+    cancelAnimationFrame(pendingFrameRef.current)
+    pendingFrameRef.current = null
+  }, [])
+
+  return useCallback(() => {
+    if (pendingFrameRef.current !== null) return
+    let remainingFrames = intervalFrames
+    const advance = (): void => {
+      remainingFrames -= 1
+      if (remainingFrames > 0) {
+        pendingFrameRef.current = requestAnimationFrame(advance)
+        return
+      }
+      pendingFrameRef.current = null
+      updateRef.current()
+    }
+    pendingFrameRef.current = requestAnimationFrame(advance)
+  }, [intervalFrames])
+}

packages/client/ui-conversation/tests/chat-tool-row.spec.tsx

@@ -1,8 +1,7 @@
 // @vitest-environment jsdom
-import { afterEach, describe, expect, it, vi } from 'vitest'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { cleanup, fireEvent, render } from '@testing-library/react'
 
-afterEach(cleanup)
 import type { RunningToolCall, ToolResultNode } from '@deepseek-ai/dsh-client-runtime/client'
 import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
 import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
@@ -12,6 +11,36 @@ import { ToolRow } from '../src/client/chat/ToolRow.tsx'
 import { GenericToolCard, type GenericToolCardProps } from '../src/client/chat/GenericToolCard.tsx'
 import { zh } from '../src/client/locales.ts'
 
+let nextAnimationFrameId = 1
+let animationFrames = new Map<number, FrameRequestCallback>()
+
+function flushAnimationFrames(count: number): void {
+  for (let index = 0; index < count; index += 1) {
+    const callbacks = [...animationFrames.values()]
+    animationFrames.clear()
+    for (const callback of callbacks) callback(index)
+  }
+}
+
+beforeEach(() => {
+  nextAnimationFrameId = 1
+  animationFrames = new Map()
+  vi.stubGlobal('requestAnimationFrame', (callback: FrameRequestCallback) => {
+    const id = nextAnimationFrameId
+    nextAnimationFrameId += 1
+    animationFrames.set(id, callback)
+    return id
+  })
+  vi.stubGlobal('cancelAnimationFrame', (id: number) => {
+    animationFrames.delete(id)
+  })
+})
+
+afterEach(() => {
+  cleanup()
+  vi.unstubAllGlobals()
+})
+
 // Mirrors the real lookup chain (conversation namespace, then common).
 const t: GenericToolCardProps['t'] = makeTranslate(zh, commonZh)
 
@@ -341,6 +370,10 @@ describe('ThinkRow', () => {
         streaming
       />,
     )
+    expect(summary.scrollLeft).toBe(0)
+    flushAnimationFrames(2)
+    expect(summary.scrollLeft).toBe(0)
+    flushAnimationFrames(1)
     expect(summary.scrollLeft).toBe(200)
     expect(summary.getAttribute('data-follow-end')).toBe('true')
 
@@ -351,6 +384,7 @@ describe('ThinkRow', () => {
         streaming={false}
       />,
     )
+    flushAnimationFrames(3)
     expect(view.getByText('Inspect the session')).toBeTruthy()
     expect(summary.scrollLeft).toBe(0)
     expect(summary.hasAttribute('data-follow-end')).toBe(false)