Merge remote-tracking branch 'origin/master' into xtr/react-loop-simplification

# Conflicts:
#	packages/client/runtime/tests/session.spec.ts

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/connection/src/client/fixture.ts

@@ -1168,6 +1168,16 @@ interface StreamConn<F> {
   push(envelope: RpcRequest<F>): void
 }
 
+interface ReasoningChunkStormState {
+  sessionId: string
+  chunkCount: number
+  chunksPerInterval: number
+  intervalMs: number
+  emitted: number
+  marker: string
+  emitting: boolean
+}
+
 /** Deterministic fixture branches used by keyless Web assembly tests. */
 export interface FixtureOptions {
   /** Start with no real Workspace or Session. */
@@ -1444,6 +1454,8 @@ export function createFixtureApi(options: FixtureOptions = {}): ApiProxy {
   const streamBreakers = new Set<() => void>()
   /** Retry scenarios opened by timing hooks and completed in a later browser assertion phase. */
   const retryScenarios = new Map<SessionId, { turn: number; stepStarted: boolean }>()
+  /** The single opt-in browser stress producer; normal fixture journeys never start it. */
+  let activeReasoningChunkStorm: ReasoningChunkStormState | null = null
 
   // Timing-acceptance hooks (browser test backdoor): the in-memory fixture is ideally timed, which
   // is exactly what masked the open-window and reconnect-gap bugs (audit S1/S3). These let
@@ -1467,6 +1479,86 @@ export function createFixtureApi(options: FixtureOptions = {}): ApiProxy {
       const messageSeqs = log.filter(event => event.type === 'user/message').map(event => event.seq)
       append(sid(id), { type: 'session/title', data: { title, messageSeqs, source: { kind: 'provider', provider: 'fixture' } } })
     },
+    /** Start an externally paced reasoning stream for the opt-in browser stress lane. */
+    startReasoningChunkStorm(
+      id: string,
+      chunkCount: number,
+      chunksPerInterval: number,
+      intervalMs: number,
+    ): string {
+      if (!Number.isSafeInteger(chunkCount) || chunkCount < 1) {
+        throw new Error('fixture: reasoning chunk count must be a positive safe integer')
+      }
+      if (!Number.isSafeInteger(chunksPerInterval) || chunksPerInterval < 1) {
+        throw new Error('fixture: reasoning chunks per interval must be a positive safe integer')
+      }
+      if (!Number.isSafeInteger(intervalMs) || intervalMs < 1) {
+        throw new Error('fixture: reasoning interval must be a positive safe integer')
+      }
+      if (activeReasoningChunkStorm?.emitting === true) {
+        throw new Error('fixture: reasoning chunk storm already running')
+      }
+
+      const sessionId = sid(id)
+      const log = logOf(sessionId)
+      let turn = nextTurn.get(sessionId) ?? 0
+      for (const event of log) {
+        const candidate = (event as unknown as { data?: { turn?: unknown } }).data?.turn
+        if (typeof candidate === 'number') turn = Math.max(turn, candidate + 1)
+      }
+      nextTurn.set(sessionId, turn + 1)
+      const marker = `REASONING_STRESS_COMPLETE:${String(turn)}:${String(chunkCount)}`
+      const state: ReasoningChunkStormState = {
+        sessionId: id,
+        chunkCount,
+        chunksPerInterval,
+        intervalMs,
+        emitted: 0,
+        marker,
+        emitting: true,
+      }
+      activeReasoningChunkStorm = state
+
+      setRunning(sessionId, true)
+      append(sessionId, { type: 'turn/start', data: { turn, trigger: { kind: 'message', source: { kind: 'user' } } } })
+      append(sessionId, {
+        type: 'user/message', surfaceOp: 'append',
+        data: userMessage(text(`Reasoning chunk stress: ${String(chunkCount)} chunks.`)),
+      })
+      append(sessionId, { type: 'step/start', data: { turn, step: 0 } })
+      append(sessionId, {
+        type: 'assistant/chunk',
+        data: { turn, step: 0, chunk: { type: 'block-start', index: 0, blockType: 'reasoning' } },
+      })
+
+      const startedAt = Date.now()
+      const pump = (): void => {
+        const elapsedIntervals = Math.floor((Date.now() - startedAt) / intervalMs) + 1
+        const due = Math.max(state.emitted + chunksPerInterval, elapsedIntervals * chunksPerInterval)
+        const end = Math.min(due, chunkCount)
+        for (let index = state.emitted; index < end; index++) {
+          const chunkText = index === chunkCount - 1
+            ? `\n${marker}`
+            : index % 64 === 63 ? '推理\n' : '推理'
+          append(sessionId, {
+            type: 'assistant/chunk',
+            data: { turn, step: 0, chunk: { type: 'reasoning-delta', index: 0, text: chunkText } },
+          })
+        }
+        state.emitted = end
+        if (end < chunkCount) {
+          setTimeout(pump, intervalMs)
+        } else {
+          state.emitting = false
+        }
+      }
+      setTimeout(pump, 0)
+      return marker
+    },
+    /** Return a copy so browser probes cannot mutate the active producer. */
+    reasoningChunkStormState(): ReasoningChunkStormState | null {
+      return activeReasoningChunkStorm === null ? null : { ...activeReasoningChunkStorm }
+    },
     /** Open one failed model step whose partial remains visible until llm/retry arrives. */
     beginModelRetry(id: string): void {
       const sessionId = sid(id)

packages/client/connection/tests/fixture.spec.ts

@@ -19,6 +19,16 @@ interface TimingHooks {
   failNextHistory(): void
   appendUser(id: string, msg: string): void
   appendTitle(id: string, title: string): void
+  startReasoningChunkStorm(id: string, chunkCount: number, chunksPerInterval: number, intervalMs: number): string
+  reasoningChunkStormState(): {
+    sessionId: string
+    chunkCount: number
+    chunksPerInterval: number
+    intervalMs: number
+    emitted: number
+    marker: string
+    emitting: boolean
+  } | null
   beginModelRetry(id: string): void
   scheduleModelRetry(id: string, retry?: number, delayMs?: number): void
   cancelModelRetryDuringBackoff(id: string, delayMs?: number): void
@@ -873,6 +883,50 @@ describe('createFixtureApi', () => {
     expect(abort.signal.aborted).toBe(false)
     expect(habort.signal.aborted).toBe(false)
   })
+
+  it('paces the opt-in reasoning stress hook from an external interval', async () => {
+    vi.useFakeTimers()
+    vi.setSystemTime(0)
+    const api = createFixtureApi()
+    const hooks = timing()
+    expect(hooks.reasoningChunkStormState()).toBeNull()
+    expect(() => hooks.startReasoningChunkStorm('fx-alpha', 0, 1, 16)).toThrow(/chunk count/)
+    expect(() => hooks.startReasoningChunkStorm('fx-alpha', 1, 0, 16)).toThrow(/chunks per interval/)
+    expect(() => hooks.startReasoningChunkStorm('fx-alpha', 1, 1, 0)).toThrow(/reasoning interval/)
+    const abort = new AbortController()
+    try {
+      const streamed = collect(api.events.mux(req({}), abort.signal), abort, frames => frames.some(frame => (
+        frame.type === 'session/event'
+        && frame.event.type === 'assistant/chunk'
+        && frame.event.data.chunk.type === 'reasoning-delta'
+        && frame.event.data.chunk.text.includes('REASONING_STRESS_COMPLETE')
+      )))
+      const marker = hooks.startReasoningChunkStorm('fx-alpha', 3, 2, 16)
+      expect(() => hooks.startReasoningChunkStorm('fx-alpha', 1, 1, 16)).toThrow(/already running/)
+      expect(hooks.reasoningChunkStormState()).toMatchObject({ emitted: 0, emitting: true, marker })
+
+      await vi.advanceTimersByTimeAsync(0)
+      expect(hooks.reasoningChunkStormState()).toMatchObject({ emitted: 2, emitting: true })
+      await vi.advanceTimersByTimeAsync(16)
+      expect(hooks.reasoningChunkStormState()).toEqual({
+        sessionId: 'fx-alpha', chunkCount: 3, chunksPerInterval: 2, intervalMs: 16,
+        emitted: 3, marker, emitting: false,
+      })
+
+      const frames = await streamed
+      const deltas = frames.flatMap(frame => (
+        frame.type === 'session/event'
+        && frame.event.type === 'assistant/chunk'
+        && frame.event.data.chunk.type === 'reasoning-delta'
+          ? [frame.event.data.chunk.text]
+          : []
+      ))
+      expect(deltas).toEqual(['推理', '推理', `\n${marker}`])
+    } finally {
+      abort.abort()
+      vi.useRealTimers()
+    }
+  })
 })
 
 describe('FixtureApiClient (protocol-level fake carrier)', () => {

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'
 
@@ -690,6 +690,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-attempt partial and starts the retry on new chunk evidence', 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)