refactor(ui-chat): separate viewport and scroll navigation policies

This commit is contained in:
imccyu committed 2026-09-18 14:13:47 +08:00
1 parent f89cd786aa
commit e22b0d75e8
12 files changed
+1104 -663

No files matched your search

+15 -15
View File
@@ -198,35 +198,35 @@ describe('web e2e: long Chat interaction contract', () => {
const turnNavigation = page.getByRole('navigation', { name: 'Turn navigation' })
await turnNavigation.waitFor({ state: 'visible', timeout: 15_000 })
// The whole-log outline offers every fixture turn before any paging, with
// the live tail mark current.
const marks = turnNavigation.getByRole('button')
await expect.poll(() => marks.count(), { timeout: 15_000 }).toBe(FIXTURE_TURNS)
expect(await marks.last().getAttribute('aria-current')).toBe('true')
await expect.poll(() => marks.last().getAttribute('aria-current'), { timeout: 15_000 }).toBe('true')
expect(await marks.count()).toBeLessThan(FIXTURE_TURNS)
// The oldest turn is an unloaded mark whose outline preview already
// carries both the prompt and the settled response.
const firstTurnButton = turnNavigation
.getByRole('button', { name: 'Load and jump to turn 1', exact: true })
const railScroller = turnNavigation.locator('[class*="scroller"]')
await railScroller.hover()
await page.mouse.wheel(0, -FIXTURE_TURNS * 10)
await firstTurnButton.focus()
const preview = page.getByRole('tooltip')
await preview.waitFor({ state: 'visible', timeout: 5_000 })
expect(await preview.textContent()).toContain(FIXTURE.markers.user(1))
expect(await preview.textContent()).toContain(FIXTURE.markers.assistant(1))
const firstTurnPosition = await firstTurnButton.evaluate(button => (
button.parentElement?.style.getPropertyValue('--turn-natural-position') ?? ''
const markPitch = () => turnNavigation.getByRole('button').evaluateAll(buttons => (
buttons[1]!.getBoundingClientRect().top - buttons[0]!.getBoundingClientRect().top
))
expect(firstTurnPosition).toBe('0px')
expect(await markPitch()).toBe(10)
const loadEarlier = page.getByRole('button', { name: 'Load earlier', exact: true })
const loadedMarks = turnNavigation.getByRole('button', { name: /^Jump to turn / })
const loadedBefore = await loadedMarks.count()
const loadedRows = page.locator('[data-chat-flow-key]')
const loadedBefore = await loadedRows.count()
await loadEarlier.click()
// Paging converts marks to their loaded form without moving the
// fixed-pitch ladder.
await expect.poll(() => loadedMarks.count(), { timeout: 15_000 }).toBeGreaterThan(loadedBefore)
expect(await firstTurnButton.evaluate(button => (
button.parentElement?.style.getPropertyValue('--turn-natural-position') ?? ''
))).toBe(firstTurnPosition)
await expect.poll(() => loadedRows.count(), { timeout: 15_000 }).toBeGreaterThan(loadedBefore)
await railScroller.hover()
await page.mouse.wheel(0, -FIXTURE_TURNS * 10)
await firstTurnButton.waitFor({ state: 'visible' })
expect(await markPitch()).toBe(10)
// Activating the still-unloaded oldest mark pages the rest in and lands
// on the turn's own row.
await firstTurnButton.focus()
+10 -14
View File
@@ -587,7 +587,7 @@ describe('web e2e: long Chat scroll contract', () => {
})
}, 180_000)
it.skipIf(MODE === 'record')('offers every outline turn on the rail and jumps to an unloaded one', async () => {
it.skipIf(MODE === 'record')('virtualizes the outline rail and jumps to an unloaded turn', async () => {
await withScrollWorld({
failureShot: 'web-e2e-turn-rail-jump',
seeds: [{ fixture: HISTORY_FIXTURE, id: RAIL_SESSION_ID }],
@@ -595,25 +595,21 @@ describe('web e2e: long Chat scroll contract', () => {
await openSeed(world.page, HISTORY_FIXTURE, HISTORY_FIXTURE.markers.assistant(HISTORY_FIXTURE.turns))
await expectBottom(world.page)
// The whole-log outline reaches the rail before any paging: one mark
// per fixture turn, the oldest still in its load-and-jump form.
const rail = world.page.getByRole('navigation', { name: 'Turn navigation' })
await expect.poll(() => rail.getByRole('button').count(), { timeout: 15_000 })
.toBe(HISTORY_FIXTURE.turns)
const latest = rail.getByRole('button', { name: `Jump to turn ${String(HISTORY_FIXTURE.turns)}`, exact: true })
await expect.poll(() => latest.getAttribute('aria-current'), { timeout: 15_000 }).toBe('true')
expect(await rail.getByRole('button').count()).toBeLessThan(HISTORY_FIXTURE.turns)
const firstUnloaded = rail.getByRole('button', { name: 'Load and jump to turn 1', exact: true })
expect(await firstUnloaded.count()).toBe(1)
// Fixed pitch: the ladder keeps its natural height, scrolls inside the
// frame, and (following the active tail mark) fades its upper end.
expect(await rail.evaluate(nav => nav.style.getPropertyValue('--turn-natural-height')))
.toBe(`${String((HISTORY_FIXTURE.turns - 1) * 10 + 12)}px`)
expect(await firstUnloaded.count()).toBe(0)
const railScroller = rail.locator('[class*="scroller"]')
await expect.poll(() => railScroller.evaluate(el => el.scrollHeight > el.clientHeight)).toBe(true)
await expect.poll(() => rail.locator('[class*="fadeTop"]').count(), { timeout: 15_000 }).toBe(1)
const bodyBeforeRailScroll = await scrollGeometry(world.page)
await railScroller.hover()
await world.page.mouse.wheel(0, -HISTORY_FIXTURE.turns * 10)
await firstUnloaded.waitFor({ state: 'visible' })
expect((await scrollGeometry(world.page)).scrollTop).toBe(bodyBeforeRailScroll.scrollTop)
// Activate the unloaded mark by keyboard: pointer input belongs to the
// rail frame, while each mark is the keyboard/AT destination. Focus
// first shows the outline-backed preview: prompt and settled response
// both travel ahead of the events.
const beforeRows = await loadedFlowRows(world.page)
await firstUnloaded.focus()
const tooltip = world.page.getByRole('tooltip')
+17
View File
@@ -458,6 +458,23 @@ describe('web e2e: seeded history renders through cold resume', () => {
await expect.poll(() => disclosure.getAttribute('aria-expanded')).toBe('false')
})
it.skipIf(MODE === 'record')('restores the active turn rail mark across Chat and Trajectory', async () => {
const rail = page.getByRole('navigation', { name: 'Turn navigation' })
const current = rail.locator('[aria-current="true"]')
await current.waitFor({ state: 'visible' })
const active = await current.getAttribute('aria-label')
const scroller = page.locator('[data-conversation-scroll]')
const top = await scroller.evaluate(element => element.scrollTop)
await page.getByRole('tab', { name: 'Trajectory', exact: true }).click()
await page.getByLabel('Trajectory timeline', { exact: true }).waitFor({ state: 'visible' })
await page.getByRole('tab', { name: 'Chat', exact: true }).click()
await expect.poll(() => current.getAttribute('aria-label')).toBe(active)
await expect.poll(async () => Math.abs(await scroller.evaluate(element => element.scrollTop) - top)).toBeLessThanOrEqual(2)
expect(tripwire.pageErrors).toEqual([])
})
it.skipIf(MODE === 'record')('file-path tool rows rebuilt from the cold log open the right Sidebar', async () => {
onTestFailed(async () => {
await mkdir(fileURLToPath(new URL('../../../.artifacts/screenshots/0907-2205-sidebar', import.meta.url)), { recursive: true })
+2 -2
View File
@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write packages/client/ui-chat/README.md
README.md: 92c71663e9193e24657a31e57204a9bf076e19c3
README.zh.md: 702042384b81d028b7db40275e5ee705dc949fb2
README.md: 437bd8b91dbe8d9b6c8eecaf4d891c112e20b920
README.zh.md: 94eda5e4fa5708320e8bced9f1421950aa75f07d
+9
View File
@@ -74,6 +74,15 @@ Settings → General exposes a persisted, localized `Normal` / `Compact` convers
Chat restores semantic anchors across history prepend and renderer remounts. Pinned scroll deliveries without reader movement update follow ownership immediately, before subsequent layout changes can invalidate their floor. Reader movement remains pending until the sampling interval or `scrollend`, even inside the follow threshold, so layout growth cannot erase small scroll gestures. While the reader is pinned to the floor, `ResizeObserver` follows the new floor and selects the latest loaded Turn without reading row geometry. Once the reader moves away, flow-height changes preserve the top position and the reading-line geometry selects the active Turn. Turn-rail previews paint above sticky Markdown code-block banners, while the rail frame remains inside the transcript band above the composer.
The turn rail mounts only visible marks, overscan, and the focused mark's neighbors. Its fixed pitch and observed viewport size determine scroll offsets without reading the DOM scroll extent. Initial placement waits for the body's restored active Turn and the rail's first usable viewport size. The ref controls activate a Turn or scroll the rail independently; the transcript itself remains fully mounted.
<details>
<summary>Scroll implementation — click to expand</summary>
`useChatViewport` owns turn-aware DOM reads, clamped writes, and native events. `useChatReading` owns follow policy, sampled reader input, and semantic memory; `useChatNavigation` owns turn jumps and history-prepend preservation. `useChatScroll` coordinates their committed inputs. Explicit navigation carries its measured landing into reading policy, so it does not rediscover the known target with a hit test.
</details>
-----
<a id="model-experience"></a>
+9
View File
@@ -74,6 +74,15 @@ Assistant 回复结算后,已完成轮次的计时对话框不显示 TTFT 和
Chat 会在历史前插与 renderer 重新挂载时恢复语义锚点。没有读者移动的贴底滚动事件会立即更新跟随归属,避免后续布局变化使其底部位置失效。读者移动即使位于跟随阈值内,也保持待处理直到采样周期或 `scrollend`,防止布局增长抵消小幅滚动操作。读者跟随底部时,`ResizeObserver` 追随新的底部,并且无需读取行几何就选中最后一个已加载轮次;读者离开底部后,高度变化会保持顶部位置,再由阅读线几何选择活跃轮次。轮次导航预览位于 Markdown 代码块粘性头栏上方,而导航外框始终处于 composer 上方的 transcript 区域内。
轮次轨道只挂载可见刻度、预加载范围及键盘焦点刻度的相邻项。固定间距和观察到的视口尺寸决定滚动偏移,不读取 DOM 滚动总高度。初始定位等待正文恢复活跃轮次,以及轨道首次获得可用视口尺寸。ref 控制接口分别支持激活轮次和仅滚动轨道;正文自身仍完整挂载。
<details>
<summary>滚动实现——点击展开</summary>
`useChatViewport` 负责识别轮次的 DOM 读取、限制范围后的写入与原生事件。`useChatReading` 负责跟随策略、读者输入采样和语义位置记忆;`useChatNavigation` 负责轮次跳转与历史前插时的位置保持。`useChatScroll` 协调已提交的输入。显式导航把测得的落点交给阅读策略,因此无需通过命中测试重新寻找已知目标。
</details>
-----
<a id="model-experience"></a>
@@ -1,11 +1,10 @@
// An enclosing `[data-conversation-scroll]` owns scrolling when present;
// otherwise this view owns it. Each row subscribes to one stable node key.
import { memo, useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, type ComponentProps } from 'react'
import { memo, useCallback, useEffect, useMemo, useRef, useState, type ComponentProps } from 'react'
import type {
ConversationTimelineSnapshot, RenderMessageImages,
} from '@deepseek-ai/dsh-client-ui-conversation/client'
import type { SessionSeq } from '@deepseek-ai/dsh-session/types'
import type { InboxState } from '@deepseek-ai/dsh-agent/types'
import {
Button, IconChevronDownOutlineRegular, MarkdownDelegateProvider, Modal,
@@ -15,117 +14,11 @@ import type { ChatSnapshot } from '../contract/snapshot.ts'
import { PendingSteeringBubble, PendingSubmissionBubble } from './MessageItem.tsx'
import { ChatNodeSeat } from './ChatNodeSeat.tsx'
import { TurnNavigator } from './TurnNavigator.tsx'
import { mergeTurnRailItems, type TurnRailItem } from './turn-rail-items.ts'
import { mergeTurnRailItems } from './turn-rail-items.ts'
import { useChatScroll } from './use-chat-scroll.ts'
import { formatRunDuration } from './message-chrome.ts'
import css from './ChatView.module.css'
const FOLLOW_THRESHOLD = 24
const SCROLL_SAMPLE_INTERVAL_MS = 500
/** Active column host when present; otherwise the view-local scroller. */
function scrollerOf(from: HTMLElement): HTMLElement {
return (from.closest('[data-conversation-scroll]')) ?? from
}
/** Browser shrink clamps and recorded writes do not transfer scroll ownership. */
function readerMovedScroll(top: number, floor: number, observedTop: number): boolean {
return Math.abs(top - Math.min(observedTop, floor)) > 0.5
}
interface PagingAnchor {
/** Stable node/call identity, independent of boundary-spanning group keys. */
key: string
/** Row top relative to the scrollport after the latest user scroll. */
top: number
}
/** Find an already-rendered row without interpolating a selector. */
function anchorElement(list: HTMLElement, key: string): HTMLElement | null {
for (const row of list.querySelectorAll<HTMLElement>('[data-chat-anchor-key]:not([hidden])')) {
if (row.dataset.chatAnchorKey === key) return row
}
return null
}
/**
* Turn owning the row at a scrollport line. Scroll frames are hot, so this
* hit-tests the line first and falls back to one row scan when layout cannot
* answer (jsdom, pre-paint); neither path queries per navigation item.
* @param list - the ChatView list element.
* @param line - viewport y of the reading line.
* @returns the Turn number, or null when no loaded row covers the line.
*/
function turnAtLine(list: HTMLElement, line: number): number | null {
const content = list.getBoundingClientRect()
if (typeof document.elementsFromPoint === 'function' && content.width > 0) {
for (const element of document.elementsFromPoint(content.left + content.width / 2, line)) {
const row = element instanceof HTMLElement ? element.closest<HTMLElement>('[data-chat-turn]') : null
const turn = Number(row?.dataset.chatTurn)
if (row !== null && list.contains(row) && Number.isSafeInteger(turn)) return turn
}
}
let found: number | null = null
for (const row of list.querySelectorAll<HTMLElement>('[data-chat-turn]')) {
if (row.getBoundingClientRect().top > line) break
const turn = Number(row.dataset.chatTurn)
if (Number.isSafeInteger(turn)) found = turn
}
return found
}
/** Row position in scrollport coordinates (viewport-independent). */
function flowTop(row: HTMLElement, scrollport: HTMLElement): number {
return row.getBoundingClientRect().top - scrollport.getBoundingClientRect().top
}
/** Select a visible stable node/call identity, falling back only when layout
* has not exposed a visible box yet. */
function pagingAnchor(list: HTMLElement, scrollport: HTMLElement): HTMLElement | null {
const viewport = scrollport.getBoundingClientRect()
const composer = scrollport.querySelector<HTMLElement>('[data-composer-seat]')
const visibleBottom = composer?.getBoundingClientRect().top ?? viewport.bottom
// The leading edge preserves nested call identity when it hits a row.
// Chrome/gap misses use logarithmic layout reads over the ordered flex rows.
if (typeof document.elementsFromPoint === 'function' && visibleBottom > viewport.top) {
const content = list.getBoundingClientRect()
const left = Math.max(viewport.left, content.left)
const right = Math.min(viewport.right, content.right)
const x = left + Math.max(0, right - left) / 2
for (const element of document.elementsFromPoint(x, viewport.top + 1)) {
const row = element instanceof HTMLElement
? element.closest<HTMLElement>('[data-chat-anchor-key]')
: null
if (row !== null && list.contains(row)) return row
}
}
const rows = list.querySelectorAll<HTMLElement>(
'[data-chat-flow] > [data-chat-flow-key]:not(:empty):not([hidden])',
)
let low = 0
let high = rows.length
while (low < high) {
const middle = (low + high) >>> 1
if (rows.item(middle).getBoundingClientRect().bottom > viewport.top) high = middle
else low = middle + 1
}
const row = rows[low]
return row !== undefined && row.getBoundingClientRect().top < visibleBottom ? row : rows[0] ?? null
}
type ChatScrollPosition = NonNullable<ReturnType<ChatViewSlotProps['chatScroll']['read']>>
/** Capture a reflow-resistant reader position from the current rendered window. */
function scrollPosition(list: HTMLElement, scrollport: HTMLElement): ChatScrollPosition | null {
const row = pagingAnchor(list, scrollport)
const anchorKey = row?.dataset.chatAnchorKey
if (row === null || anchorKey === undefined) return null
return {
anchorKey,
anchorTop: flowTop(row, scrollport),
scrollTop: scrollport.scrollTop,
}
}
/** Host/OS refusal text for the file-open dialog; empty throws keep a locale fallback. */
function openFailureMessage(error: unknown, fallback: string): string {
const message = error instanceof Error ? error.message : String(error)
@@ -301,473 +194,31 @@ export function ChatView({
)
const runningTurnStart = useMemo(() => runningTurnStartTime(timeline), [timeline])
const listRef = useRef<HTMLDivElement | null>(null)
const columnRef = useRef<HTMLDivElement | null>(null)
// A saved position starts disarmed; the first layout effect synchronously
// restores it and normalizes a floor-clamped position back to following.
const [atBottom, setAtBottom] = useState(() => chatScroll.read() === null)
const atBottomRef = useRef(atBottom)
const scrollSamplePendingRef = useRef(false)
const [, setScrollSampleTick] = useState(0)
const [activeTurn, setActiveTurn] = useState<number | null>(
() => turnNavigationItems.at(-1)?.turn ?? null,
)
/** Last position delivered or written on the main thread. */
const observedTopRef = useRef(0)
/** Paging anchor: semantic row/position at click, updated by reader scrolls
* while the request is pending and restored after the prepend lands. */
const anchorRef = useRef<PagingAnchor | null>(null)
/** Unloaded-turn jump in flight: target turn plus its load-through seq. */
const pendingJumpRef = useRef<{ turn: number; seq: SessionSeq } | null>(null)
/** Whether the in-flight jump already landed mid-paging (settle then only corrects an untouched landing). */
const jumpLandedRef = useRef(false)
const [busyJumpTurn, setBusyJumpTurn] = useState<number | null>(null)
/** Bumped when a loadThrough completion settles, after its last page's commit. */
const [jumpSettleTick, setJumpSettleTick] = useState(0)
/** Window head at the last settle-time repage; an unmoved head falls back instead of repaging forever. */
const jumpRepageHeadRef = useRef<number | null>(null)
const firstSeqRef = useRef<number | null>(null)
const openedRef = useRef(false)
const lastKeyRef = useRef<string | null>(null)
const lastSteeringIdRef = useRef<string | null>(null)
const lastSubmissionIdRef = useRef<string | null>(null)
/** Flow tip signature — follow-scroll only when this moves, never on a
* scroll-driven at-bottom chrome re-render (which would snap inertial
* scrolls the rest of the way to the floor). */
const followSigRef = useRef<string | null>(null)
const firstKey = order[0]
const firstSeq = firstKey === undefined ? null : nodeStore.get(firstKey)?.anchorSeq ?? null
const lastKey = order.at(-1) ?? null
const lastNode = lastKey === null ? undefined : nodeStore.get(lastKey)
const lastSteeringId = pendingSteering[pendingSteering.length - 1]?.id ?? null
const lastSubmissionId = visibleSubmissions[visibleSubmissions.length - 1]?.requestId ?? null
const followSig = `${openState}:${firstSeq}:${lastKey}:${order.length}:${running ? 1 : 0}:${lastSteeringId ?? ''}:${lastSubmissionId ?? ''}`
const syncActiveTurn = useCallback((): void => {
if (scrollSamplePendingRef.current) return
const local = listRef.current
const first = turnNavigationItems[0]
if (local === null || first === undefined) {
setActiveTurn(null)
return
}
const el = scrollerOf(local)
if (el.scrollHeight - el.scrollTop - el.clientHeight <= FOLLOW_THRESHOLD + 1) {
const latest = turnNavigationItems.at(-1)?.turn ?? first.turn
setActiveTurn(current => current === latest ? current : latest)
return
}
const readingLine = el.getBoundingClientRect().top + Math.min(96, el.clientHeight * 0.2)
const reading = turnAtLine(local, readingLine)
// No row reaches the line yet: the flow head still owns the mark. Otherwise
// the row's Turn may be one the rail does not offer (all its nodes hidden),
// so the newest offered Turn at or above it owns the mark.
let next = first.turn
if (reading !== null) {
for (const item of turnNavigationItems) {
if (item.turn > reading) break
next = item.turn
}
}
setActiveTurn(current => current === next ? current : next)
}, [turnNavigationItems])
const activeTurnRef = useRef<(() => void) | null>(null)
const activeFrameRef = useRef<number | null>(null)
const scheduleActiveTurn = useCallback((): void => {
if (activeFrameRef.current !== null) return
if (typeof requestAnimationFrame === 'undefined') {
syncActiveTurn()
return
}
activeFrameRef.current = requestAnimationFrame(() => {
activeFrameRef.current = null
syncActiveTurn()
})
}, [syncActiveTurn])
useEffect(() => () => {
if (activeFrameRef.current !== null && typeof cancelAnimationFrame !== 'undefined') {
cancelAnimationFrame(activeFrameRef.current)
}
}, [])
activeTurnRef.current = scheduleActiveTurn
useLayoutEffect(() => {
scheduleActiveTurn()
}, [scheduleActiveTurn])
const toBottom = (el: HTMLElement): void => {
anchorRef.current = null
// Returning to the live tail supersedes a jump still landing.
pendingJumpRef.current = null
setBusyJumpTurn(current => current === null ? current : null)
el.scrollTop = el.scrollHeight
observedTopRef.current = el.scrollTop
atBottomRef.current = true
setAtBottom(true)
chatScroll.save(null)
setActiveTurn(turnNavigationItems.at(-1)?.turn ?? null)
}
// Land a row at the reading line and republish scroll-derived state. A
// latest-ref, so navigateToTurn's identity stays stable for the memoized rail.
const landOnRowRef = useRef<(local: HTMLElement, el: HTMLElement, row: HTMLElement, turn: number) => void>(
() => {},
)
landOnRowRef.current = (local, el, row, turn) => {
el.scrollTop += flowTop(row, el) - 24
observedTopRef.current = el.scrollTop
const isAtBottom = el.scrollHeight - el.scrollTop - el.clientHeight <= FOLLOW_THRESHOLD + 1
atBottomRef.current = isAtBottom
setAtBottom(isAtBottom)
setActiveTurn(turn)
const position = isAtBottom ? null : scrollPosition(local, el)
if (isAtBottom) chatScroll.save(null)
else if (position !== null) chatScroll.save(position)
}
/**
* Land the pending jump once its Turn has a rendered anchor row; false
* while it must keep waiting. Mid-jump landings (`settle` false) keep the
* jump armed with the target row as the paging anchor, so later chunks and
* the load-earlier button's unmount re-land on the same row; the settling
* call clears the jump.
*/
const realizePendingJump = (local: HTMLElement, el: HTMLElement, settle: boolean): boolean => {
const pending = pendingJumpRef.current
if (pending === null) return true
const item = railItems.find(candidate => candidate.turn === pending.turn)
if (item === undefined || item.anchor.kind !== 'loaded') return false
const row = anchorElement(local, item.anchor.key)
if (row === null) return false
if (settle) {
pendingJumpRef.current = null
setBusyJumpTurn(null)
const held = anchorRef.current
const landedEarlier = jumpLandedRef.current
jumpLandedRef.current = false
anchorRef.current = null
// A reader who moved off an already-landed target mid-jump keeps their
// place; a first landing, or an untouched one, takes the correction.
if (!landedEarlier || held?.key === item.anchor.key) {
landOnRowRef.current(local, el, row, pending.turn)
}
return true
}
landOnRowRef.current(local, el, row, pending.turn)
jumpLandedRef.current = true
anchorRef.current = { key: item.anchor.key, top: flowTop(row, el) }
return true
}
useLayoutEffect(() => {
if (scrollSamplePendingRef.current) return
const local = listRef.current
/* v8 ignore next -- ref-null guard: React attaches the ref before layout effects run. */
if (local === null) return
const el = scrollerOf(local)
// Open completed: jump to the bottom once — unless a scroll position
// survives from a previous mount (view-tab switch away and back), which
// is restored instead of snapping the reader back to the floor.
if (openState === 'open' && !openedRef.current) {
openedRef.current = true
const saved = chatScroll.read()
if (saved === null) {
toBottom(el)
} else {
el.scrollTop = saved.scrollTop
const row = anchorElement(local, saved.anchorKey)
if (row !== null) el.scrollTop += flowTop(row, el) - saved.anchorTop
observedTopRef.current = el.scrollTop
const isAtBottom = el.scrollHeight - el.scrollTop - el.clientHeight <= FOLLOW_THRESHOLD + 1
atBottomRef.current = isAtBottom
setAtBottom(isAtBottom)
const normalized = isAtBottom ? null : scrollPosition(local, el)
if (isAtBottom) chatScroll.save(null)
else if (normalized !== null) chatScroll.save(normalized)
}
firstSeqRef.current = firstSeq
lastKeyRef.current = lastKey
lastSteeringIdRef.current = lastSteeringId
lastSubmissionIdRef.current = lastSubmissionId
followSigRef.current = followSig
return
}
// Prepend (head seq decreased): preserve the same settled row at the
// position established by the reader's latest scroll. This excludes
// unrelated tail/composer growth while the request was in flight.
if (anchorRef.current !== null && firstSeq !== null && firstSeqRef.current !== null && firstSeq < firstSeqRef.current) {
const anchor = anchorRef.current
anchorRef.current = null
const row = anchorElement(local, anchor.key)
if (row !== null) el.scrollTop += flowTop(row, el) - anchor.top
observedTopRef.current = el.scrollTop
// A jump chunk lands here: scroll to the target once its rows exist;
// until then keep holding the reader's row for the next chunk.
if (!realizePendingJump(local, el, false) && row !== null) {
anchorRef.current = { key: anchor.key, top: flowTop(row, el) }
}
firstSeqRef.current = firstSeq
/* v8 ignore next -- ?? arm: a prepend adds nodes, so the flow list here is never empty. */
lastKeyRef.current = lastKey
lastSteeringIdRef.current = lastSteeringId
lastSubmissionIdRef.current = lastSubmissionId
followSigRef.current = followSig
return
}
firstSeqRef.current = firstSeq
// Own words must be visible: a new trailing user node force-scrolls
// (send lives in the composer, so arrival is detected here, not armed there).
const appendedUser = lastKey !== lastKeyRef.current && lastNode?.kind === 'user'
const appendedSteering = lastSteeringId !== null && lastSteeringId !== lastSteeringIdRef.current
const appendedSubmission = lastSubmissionId !== null && lastSubmissionId !== lastSubmissionIdRef.current
const tipMoved = followSigRef.current !== followSig
lastKeyRef.current = lastKey
lastSteeringIdRef.current = lastSteeringId
lastSubmissionIdRef.current = lastSubmissionId
followSigRef.current = followSig
// Follow new flow content while pinned; do NOT re-pin on every render
// merely because atBottomRef is true (scroll threshold → setState → snap).
if (appendedUser || appendedSteering || appendedSubmission || (tipMoved && atBottomRef.current)) {
toBottom(el)
return
}
// A jump whose target committed outside the anchored-prepend path (for
// example after a mid-jump toBottom dropped the held anchor) lands here.
if (pendingJumpRef.current !== null) realizePendingJump(local, el, false)
const scroll = useChatScroll({
ready: openState === 'open',
order, firstSeq, lastKey, running, loadingOlder, hasMore, chatScroll, loadOlder, loadThrough,
lastIsUser: lastKey !== null && nodeStore.get(lastKey)?.kind === 'user',
steeringId: pendingSteering.at(-1)?.id ?? null,
submissionId: visibleSubmissions.at(-1)?.requestId ?? null,
loadedTurns: turnNavigationItems,
})
const onScrollRef = useRef(() => {})
onScrollRef.current = () => {
const local = listRef.current
/* v8 ignore next -- ref-null guard: the handler only fires while mounted. */
if (local === null) return
const el = scrollerOf(local)
// Only reader input may make raw scroll geometry change follow ownership:
// a delivered position that deviates from the observed-top ledger (every
// programmatic write records itself there synchronously). This covers
// wheel, touch, scrollbar, and keyboard alike without naming devices.
// Browser shrink-clamps land exactly on the floor min and delayed
// programmatic deliveries land on the ledger itself, so both preserve
// the current ownership state.
const floor = Math.max(0, el.scrollHeight - el.clientHeight)
const movedByReader = readerMovedScroll(el.scrollTop, floor, observedTopRef.current)
const isAtBottom = movedByReader
? floor - el.scrollTop <= FOLLOW_THRESHOLD + 1
: atBottomRef.current
if (!movedByReader && isAtBottom) {
toBottom(el)
return
}
atBottomRef.current = isAtBottom
setAtBottom(isAtBottom)
const position = isAtBottom ? null : scrollPosition(local, el)
if (isAtBottom) {
anchorRef.current = null
} else if (anchorRef.current !== null && position !== null) {
anchorRef.current = { key: position.anchorKey, top: position.anchorTop }
}
// Continuous save (unmount happens after ref detach, so saving there is
// too late); pinned-to-bottom clears so a remount keeps following.
if (isAtBottom) chatScroll.save(null)
else if (position !== null) chatScroll.save(position)
observedTopRef.current = el.scrollTop
scheduleActiveTurn()
}
// Non-reader pinned deliveries must settle before layout growth invalidates
// their floor. Reader movement stays pending even inside the follow threshold,
// so growth cannot erase small gestures before they accumulate off the floor.
useEffect(() => {
const local = listRef.current
/* v8 ignore next -- ref-null guard: effect runs after the list node commits. */
if (local === null) return
const el = scrollerOf(local)
let sampleTimer: number | undefined
const sample = (): void => {
if (!scrollSamplePendingRef.current) return
scrollSamplePendingRef.current = false
if (sampleTimer !== undefined) window.clearTimeout(sampleTimer)
sampleTimer = undefined
onScrollRef.current()
setScrollSampleTick(tick => tick + 1)
}
const onScroll = (): void => {
scrollSamplePendingRef.current = true
if (atBottomRef.current) {
const floor = Math.max(0, el.scrollHeight - el.clientHeight)
if (!readerMovedScroll(el.scrollTop, floor, observedTopRef.current)) {
sample()
return
}
}
sampleTimer ??= window.setTimeout(sample, SCROLL_SAMPLE_INTERVAL_MS)
}
el.addEventListener('scroll', onScroll, { passive: true })
el.addEventListener('scrollend', sample, { passive: true })
return () => {
el.removeEventListener('scroll', onScroll)
el.removeEventListener('scrollend', sample)
if (sampleTimer !== undefined) window.clearTimeout(sampleTimer)
scrollSamplePendingRef.current = false
}
}, [])
// The ref starts null and is assigned every render, so the placeholder
// initializer a function initial value would need never exists.
const followRef = useRef<(() => void) | null>(null)
followRef.current = () => {
if (scrollSamplePendingRef.current) return
const local = listRef.current
if (local !== null && atBottomRef.current) {
const el = scrollerOf(local)
el.scrollTop = el.scrollHeight
observedTopRef.current = el.scrollTop
chatScroll.save(null)
}
}
// Streaming, tool disclosures, and other flow changes resize the column;
// the sticky composer resizes outside it. This observer owns ChatView's
// dynamic-height follow decisions and writes only while the reader is pinned.
useEffect(() => {
const column = columnRef.current
const local = listRef.current
if (column === null || local === null || typeof ResizeObserver === 'undefined') return
const scrollport = scrollerOf(local)
const composer = scrollport.querySelector<HTMLElement>('[data-composer-seat]')
// Flow-height changes (image loads, tool disclosures) move rows across the
// reading line without a scroll event, so the active mark resyncs here too.
const observer = new ResizeObserver(() => {
followRef.current?.()
activeTurnRef.current?.()
})
observer.observe(column)
if (composer !== null) observer.observe(composer)
return () => { observer.disconnect() }
}, [])
// A failed/empty page leaves the head unchanged. Once the request leaves
// its busy state there is no future prepend for the saved anchor to own.
useEffect(() => {
if (!loadingOlder) anchorRef.current = null
}, [loadingOlder])
// Jump settlement: every loadThrough completion bumps the tick after its
// last page's commit, and a plain pull's loadingOlder flip re-settles a
// jump it made wait. A still-pending jump is realized now, held while a
// plain load-earlier pull owns the pager (its completion retries below),
// repaged once per head movement, or landed on the nearest rendered Turn
// at or after the target (failure, exhausted history, or a Turn with no
// visible row).
useEffect(() => {
const pending = pendingJumpRef.current
const local = listRef.current
if (pending === null || local === null) return
const el = scrollerOf(local)
// The settling landing runs after the load-earlier button's unmount
// commit, so the target row cannot drift once the jump clears.
if (realizePendingJump(local, el, true)) return
const uncovered = firstSeq === null || firstSeq > pending.seq
if (uncovered && hasMore) {
// A plain pull owns the pager right now: hold the jump (busy stays)
// instead of degrading to a wrong landing.
if (loadingOlder) return
if (jumpRepageHeadRef.current !== firstSeq) {
jumpRepageHeadRef.current = firstSeq
const held = pagingAnchor(local, el)
if (held !== null && held.dataset.chatAnchorKey !== undefined) {
anchorRef.current = { key: held.dataset.chatAnchorKey, top: flowTop(held, el) }
}
void loadThrough(pending.seq).finally(() => { setJumpSettleTick(tick => tick + 1) })
return
}
}
for (const row of local.querySelectorAll<HTMLElement>('[data-chat-turn]:not([hidden])')) {
const turn = Number(row.dataset.chatTurn)
if (!Number.isSafeInteger(turn) || turn < pending.turn) continue
landOnRowRef.current(local, el, row, turn)
break
}
pendingJumpRef.current = null
setBusyJumpTurn(null)
// Snapshot values are read at settle time; the completion tick is the trigger.
}, [jumpSettleTick])
// A jump held while a plain pull owned the pager waits in the effect
// above; the pull's completion is its retry signal.
useEffect(() => {
if (!loadingOlder && pendingJumpRef.current !== null) setJumpSettleTick(tick => tick + 1)
}, [loadingOlder])
const loadOlderAnchored = (): void => {
const local = listRef.current
/* v8 ignore next -- ref-null guard: the paging button renders inside the list tree. */
if (local !== null) {
const el = scrollerOf(local)
const row = pagingAnchor(local, el)
if (row !== null && row.dataset.chatAnchorKey !== undefined) {
anchorRef.current = {
key: row.dataset.chatAnchorKey,
top: flowTop(row, el),
}
}
}
loadOlder()
}
// Identity feeds the memoized rail; a fresh closure per render would defeat it.
const navigateToTurn = useCallback((item: TurnRailItem): void => {
const local = listRef.current
if (local === null) return
const el = scrollerOf(local)
if (item.anchor.kind === 'unloaded') {
// Jumping into history is leaving the live tail: release bottom
// ownership on the click itself, or the pinned-scroll snap (a
// non-reader scroll delivery during the first prepend's compensation)
// would call toBottom and cancel the jump.
atBottomRef.current = false
setAtBottom(false)
// Hold the reader's place through the paging chunks; the layout effect
// lands on the target once its rows commit.
const held = pagingAnchor(local, el)
if (held !== null && held.dataset.chatAnchorKey !== undefined) {
anchorRef.current = { key: held.dataset.chatAnchorKey, top: flowTop(held, el) }
}
pendingJumpRef.current = { turn: item.turn, seq: item.anchor.seq }
jumpRepageHeadRef.current = null
jumpLandedRef.current = false
setBusyJumpTurn(item.turn)
void loadThrough(item.anchor.seq).finally(() => { setJumpSettleTick(tick => tick + 1) })
return
}
const row = anchorElement(local, item.anchor.key)
if (row === null) return
// A loaded-mark click supersedes any jump still landing.
pendingJumpRef.current = null
setBusyJumpTurn(current => current === null ? current : null)
landOnRowRef.current(local, el, row, item.turn)
// A pending older page still has to compensate the prepended height, so
// navigation moves that anchor to the new position instead of dropping it.
const landed = loadingOlder ? pagingAnchor(local, el) : null
anchorRef.current = landed === null || landed.dataset.chatAnchorKey === undefined
? null
: { key: landed.dataset.chatAnchorKey, top: flowTop(landed, el) }
}, [loadingOlder, loadThrough])
return (
<div className={css.root}>
<div ref={listRef} className={css.scroll}>
<TurnNavigator
items={railItems}
activeTurn={activeTurn}
busyTurn={busyJumpTurn}
onNavigate={navigateToTurn}
t={t}
/>
<div ref={columnRef} className={css.column} data-chat-flow="">
<div ref={scroll.listRef} className={css.scroll}>
{scroll.initialized && (
<TurnNavigator
items={railItems}
activeTurn={scroll.activeTurn}
busyTurn={scroll.busyTurn}
onNavigate={scroll.navigateToTurn}
t={t}
/>
)}
<div ref={scroll.columnRef} className={css.column} data-chat-flow="">
{openState === 'loading' && <div className={css.hint}>{t('chat.loadingHistory')}</div>}
{openState === 'error' && openError !== null && (
<div className={css.openError}>
@@ -776,7 +227,7 @@ export function ChatView({
)}
{hasMore && (
<div className={css.older}>
<button type="button" disabled={loadingOlder} onClick={loadOlderAnchored}>
<button type="button" disabled={loadingOlder} onClick={scroll.loadEarlier}>
{loadingOlder ? t('loading') : t('chat.loadOlder')}
</button>
</div>
@@ -825,17 +276,13 @@ export function ChatView({
/>
))}
</div>
{!atBottom && (
{!scroll.followingTail && (
<div className={css.toBottomSlot}>
<button
type="button"
className={css.toBottom}
aria-label={t('chat.toBottom')}
onClick={() => {
const local = listRef.current
/* v8 ignore next -- ref-null guard: the button only renders alongside the mounted list. */
if (local !== null) toBottom(scrollerOf(local))
}}
onClick={scroll.returnToBottom}
>
<IconChevronDownOutlineRegular />
</button>
@@ -0,0 +1,209 @@
/** Turn jumps and history-prepend anchoring, independent of DOM measurement. */
import { useLayoutEffect, useState } from 'react'
import type { SessionSeq } from '@deepseek-ai/dsh-session/types'
import type { ChatNode } from '../contract/chat-nodes.ts'
import type { ChatScrollPosition, ChatViewSlotProps } from '../contract/slots.ts'
import type { TurnRailItem } from './turn-rail-items.ts'
import type { ChatReading, ReadingSample } from './use-chat-reading.ts'
import type { ChatViewport } from './use-chat-viewport.ts'
/** History availability and loading operations for the committed Chat window. */
export interface ChatNavigationInput extends Pick<ChatViewSlotProps, 'loadOlder' | 'loadThrough'> {
readonly firstSeq: ChatNode['anchorSeq'] | null
readonly hasMore: boolean
readonly loadingOlder: boolean
}
interface TurnJump {
readonly turn: number
readonly seq: SessionSeq
phase: 'loading' | 'settled'
landing: 'pending' | 'landed' | 'interrupted'
repageHead: ChatNavigationInput['firstSeq']
}
/** Owns one replaceable turn jump and the anchor retained while history loads. */
export class ChatNavigation {
private jump: TurnJump | null = null
private anchor: ChatScrollPosition | null = null
private committed: Pick<ChatNavigationInput, 'firstSeq' | 'loadingOlder'>
private settleFrame: number | null = null
constructor(
private readonly viewport: ChatViewport,
private readonly reading: ChatReading,
private input: ChatNavigationInput,
private readonly onBusyTurn: (turn: number | null) => void,
) {
this.committed = input
}
/**
* Adopt committed history availability without starting a request.
* @param input - history state from the latest committed render.
*/
setInput(input: ChatNavigationInput): void { this.input = input }
/** Cancel navigation and establish the current history window as the baseline. */
reset(): void {
this.cancel()
this.committed = this.input
}
/** Cancel local callbacks; late history completions cannot revive a task. */
dispose(): void {
this.clearTask()
}
/** Release the jump, paging anchor, and busy indicator without cancelling shared history I/O. */
cancel(): void {
this.clearTask()
this.onBusyTurn(null)
}
private clearTask(): void {
this.cancelFrame()
this.jump = null
this.anchor = null
}
/**
* Replace the current jump with an explicit turn selection.
* @param item - loaded anchor or unloaded turn to fetch before landing.
*/
readonly navigateToTurn = (item: TurnRailItem): void => {
if (item.anchor.kind === 'loaded') {
const landing = this.viewport.scrollToTurn(item.turn)
if (landing === null) return
this.cancel()
this.reading.acceptNavigation(landing)
this.anchor = this.input.loadingOlder ? landing.position : null
return
}
this.cancelFrame()
this.anchor = this.viewport.capturePosition()
this.reading.pauseFollowing()
const jump: TurnJump = {
turn: item.turn,
seq: item.anchor.seq,
phase: 'loading',
landing: 'pending',
repageHead: null,
}
this.jump = jump
this.onBusyTurn(jump.turn)
this.request(jump)
}
/** Request one older page while retaining the current semantic position. */
readonly loadEarlier = (): void => {
this.anchor = this.viewport.capturePosition()
this.input.loadOlder()
}
/**
* Preserve reader ownership across pending history work.
* @param sample - settled reader movement that can update or interrupt an anchor.
*/
readerSampled(sample: ReadingSample): void {
if (sample.movedByReader && this.jump?.landing === 'landed') this.jump.landing = 'interrupted'
if (sample.followingTail) this.anchor = null
else if (this.anchor !== null && sample.position !== null) this.anchor = sample.position
}
/**
* Reconcile a newly committed history head with any retained anchor.
* @returns whether a prepended window consumed the current position-preservation operation.
*/
contentCommitted(): boolean {
const previous = this.committed
this.committed = this.input
if (this.anchor !== null && this.input.firstSeq !== null && previous.firstSeq !== null
&& this.input.firstSeq < previous.firstSeq) {
if (this.landJump(false)) return true
const landing = this.viewport.preserve(this.anchor)
this.anchor = this.jump === null ? null : landing?.position ?? null
if (landing !== null) this.reading.preservePosition(landing)
return true
}
if (previous.loadingOlder && !this.input.loadingOlder && this.jump === null) this.anchor = null
return false
}
/** Land, retry, or complete the current jump against the committed window. */
reconcile(): void {
const jump = this.jump
if (jump === null || this.reading.pending) return
if (jump.phase === 'loading') {
if (jump.landing === 'pending') this.landJump(false)
return
}
if (this.input.loadingOlder) return
if (this.landJump(true)) return
const uncovered = this.input.firstSeq === null || this.input.firstSeq > jump.seq
if (uncovered && this.input.hasMore && jump.repageHead !== this.input.firstSeq) {
jump.repageHead = this.input.firstSeq
this.anchor = this.viewport.capturePosition()
this.request(jump)
return
}
const fallback = this.viewport.scrollToTurnAtOrAfter(jump.turn)
this.cancel()
if (fallback !== null) this.reading.acceptNavigation(fallback)
}
private landJump(settle: boolean): boolean {
const jump = this.jump
if (jump === null) return false
if (jump.landing === 'interrupted') {
if (settle) { this.cancel(); return true }
return false
}
const landing = this.viewport.scrollToTurn(jump.turn)
if (landing === null) return false
this.reading.acceptNavigation(landing)
if (settle) this.cancel()
else {
this.anchor = landing.position
jump.landing = 'landed'
}
return true
}
private request(jump: TurnJump): void {
jump.phase = 'loading'
const settled = (): void => {
if (this.jump !== jump) return
jump.phase = 'settled'
this.cancelFrame()
if (typeof requestAnimationFrame !== 'function') this.reconcile()
else this.settleFrame = requestAnimationFrame(() => {
this.settleFrame = null
if (this.jump === jump) this.reconcile()
})
}
void this.input.loadThrough(jump.seq).then(settled, settled)
}
private cancelFrame(): void {
if (this.settleFrame !== null && typeof cancelAnimationFrame === 'function') cancelAnimationFrame(this.settleFrame)
this.settleFrame = null
}
}
/**
* Retain one navigation owner for the component's lifetime.
* @param viewport - turn-aware DOM operations.
* @param reading - reading and follow policy receiving navigation landings.
* @param input - committed history state and load operations.
* @returns the navigation owner and its visible busy turn.
*/
export function useChatNavigation(
viewport: ChatViewport, reading: ChatReading, input: ChatNavigationInput,
): { navigation: ChatNavigation; busyTurn: number | null } {
const [busyTurn, setBusyTurn] = useState<number | null>(null)
const [navigation] = useState(() => new ChatNavigation(viewport, reading, input, setBusyTurn))
useLayoutEffect(() => { navigation.setInput(input) }, [navigation, input])
useLayoutEffect(() => () => { navigation.dispose() }, [navigation])
return { navigation, busyTurn }
}
@@ -0,0 +1,228 @@
/** Follow-tail ownership, saved-position restoration, and sampled reader movement. */
import { useLayoutEffect, useState } from 'react'
import type { ChatScrollPosition, ChatViewSlotProps } from '../contract/slots.ts'
import type { ChatViewport, ViewportLanding, ViewportMetrics, ViewportScroll } from './use-chat-viewport.ts'
const FOLLOW_THRESHOLD = 24
const SCROLL_SAMPLE_INTERVAL_MS = 500
/** Reading facts that affect Chat chrome and initial rail placement. */
export interface ChatReadingState {
readonly initialized: boolean
readonly followingTail: boolean
readonly activeTurn: number | null
}
/** Settled reader position delivered to history-navigation policy. */
export interface ReadingSample {
readonly position: ChatScrollPosition | null
readonly movedByReader: boolean
readonly followingTail: boolean
}
type PositionStore = ChatViewSlotProps['chatScroll']
/** Owns reading policy and its cancellable sampling work, without DOM access. */
export class ChatReading {
private sampleTimer: number | null = null
private probeFrame: number | null = null
private sampled: ((sample: ReadingSample) => void) | null = null
constructor(
private readonly viewport: ChatViewport,
private store: PositionStore,
private state: ChatReadingState,
private readonly onChange: (state: ChatReadingState) => void,
) {}
/**
* Expose pending reader ownership to navigation and resize handlers.
* @returns whether reader input still awaits interval or scrollend sampling.
*/
get pending(): boolean { return this.sampleTimer !== null }
/**
* Expose the active follow policy.
* @returns whether content growth retains bottom-follow ownership.
*/
get followingTail(): boolean { return this.state.followingTail }
/**
* Adopt the committed Session's scroll memory.
* @param store - scroll memory for the current Session.
*/
setStore(store: PositionStore): void { this.store = store }
/**
* Connect history policy to settled reading observations.
* @param sampled - receives settled reader positions.
* @returns a disposer that disconnects only this listener.
*/
connect(sampled: (sample: ReadingSample) => void): () => void {
this.sampled = sampled
return () => { if (this.sampled === sampled) this.sampled = null }
}
/** Cancel timers and animation frames and detach the sample listener. */
dispose(): void {
this.cancelPending()
this.sampled = null
}
/** Release bottom follow and pending sampling for an explicit navigation. */
pauseFollowing(): void {
this.cancelPending()
this.publish({ ...this.state, followingTail: false })
}
/** Land at the current floor and clear saved reader position. */
followTail(): void {
const landing = this.viewport.scrollToBottom()
if (landing === null) return
this.cancelPending()
this.commit(landing, true, this.viewport.latestTurn)
}
/** Restore the Session's semantic position, or follow the tail when none is saved. */
restore(): void {
const saved = this.store.read()
if (saved === null) { this.followTail(); return }
const landing = this.viewport.restore(saved)
if (landing === null) return
this.cancelPending()
const following = this.nearBottom(landing.metrics)
this.commit(landing, following, following ? this.viewport.latestTurn : this.state.activeTurn, following)
if (!this.state.followingTail && landing.position === null) {
const position = this.viewport.capturePosition()
if (position !== null) this.store.save(position)
}
this.refreshActiveTurn()
}
/**
* Adopt a known landing without rediscovering its anchor.
* @param landing - measured navigation result that replaces pending reader input.
*/
acceptNavigation(landing: ViewportLanding): void {
this.cancelPending()
const following = this.nearBottom(landing.metrics)
this.commit(landing, following, landing.turn ?? (following ? this.viewport.latestTurn : this.state.activeTurn))
}
/**
* Retain reading policy while history changes the anchor's geometry.
* @param landing - compensated position that retains the current reading policy.
*/
preservePosition(landing: ViewportLanding): void {
this.cancelPending()
this.commit(landing, this.state.followingTail, this.state.activeTurn)
}
/**
* Handle pinned layout movement immediately and defer genuine reader sampling.
* @param scroll - attributed scroll delivery; reader movement remains pending until sampled.
*/
readonly onScroll = (scroll: ViewportScroll): void => {
if (this.state.followingTail && !scroll.movedByReader) {
this.followTail()
this.sampled?.({ position: null, movedByReader: false, followingTail: true })
return
}
this.sampleTimer ??= window.setTimeout(this.flushSample, SCROLL_SAMPLE_INTERVAL_MS)
}
/** Settle pending reader movement at the browser's scrollend. */
readonly onScrollEnd = (): void => { this.flushSample() }
/** Reconcile a layout change without overriding unsampled reader input. */
onResize(): void {
if (this.pending) return
if (this.state.followingTail) this.followTail()
else this.refreshActiveTurn()
}
/** Resolve the active turn from tail ownership or a coalesced reading-line probe. */
refreshActiveTurn(): void {
if (this.pending) return
if (this.state.followingTail) {
this.publish({ ...this.state, initialized: true, activeTurn: this.viewport.latestTurn })
return
}
if (this.probeFrame !== null) return
if (typeof requestAnimationFrame !== 'function') this.probe()
else this.probeFrame = requestAnimationFrame(this.probe)
}
private nearBottom(metrics: ViewportMetrics): boolean {
return metrics.floor - metrics.top <= FOLLOW_THRESHOLD + 1
}
private commit(
landing: ViewportLanding, followingTail: boolean, activeTurn: number | null, initialized = true,
): void {
if (followingTail) this.store.save(null)
else if (landing.position !== null) this.store.save(landing.position)
this.publish({ initialized, followingTail, activeTurn })
}
private publish(state: ChatReadingState): void {
if (state.initialized === this.state.initialized && state.followingTail === this.state.followingTail
&& state.activeTurn === this.state.activeTurn) return
this.state = state
this.onChange(state)
}
private cancelPending(): void {
if (this.sampleTimer !== null) window.clearTimeout(this.sampleTimer)
if (this.probeFrame !== null && typeof cancelAnimationFrame === 'function') cancelAnimationFrame(this.probeFrame)
this.sampleTimer = null
this.probeFrame = null
}
private readonly probe = (): void => {
this.probeFrame = null
if (this.pending) return
const scroll = this.viewport.readScroll()
if (scroll === null) return
const activeTurn = this.nearBottom(scroll.metrics) ? this.viewport.latestTurn : this.viewport.readVisibleTurn(scroll.metrics)
this.publish({ ...this.state, initialized: true, activeTurn })
}
private readonly flushSample = (): void => {
if (!this.pending) return
this.cancelPending()
const scroll = this.viewport.readScroll()
if (scroll === null) return
const followingTail = scroll.movedByReader ? this.nearBottom(scroll.metrics) : this.state.followingTail
let position: ChatScrollPosition | null = null
if (!scroll.movedByReader && followingTail) this.followTail()
else {
position = followingTail ? null : this.viewport.capturePosition()
this.viewport.acknowledge(scroll.metrics)
if (followingTail || position !== null) this.store.save(position)
const activeTurn = this.nearBottom(scroll.metrics) ? this.viewport.latestTurn : this.viewport.readVisibleTurn(scroll.metrics)
this.publish({ initialized: true, followingTail, activeTurn })
}
this.sampled?.({ position, movedByReader: scroll.movedByReader, followingTail })
}
}
/**
* Retain reading policy and expose only changes in visible reading state.
* @param viewport - turn-aware DOM operations.
* @param store - Session-owned semantic scroll memory.
* @param initialTurn - latest loaded turn before the first landing.
* @returns the reading owner and its React-visible state.
*/
export function useChatReading(
viewport: ChatViewport, store: PositionStore, initialTurn: number | null,
): { reading: ChatReading; state: ChatReadingState } {
const [state, setState] = useState<ChatReadingState>(() => ({
initialized: false,
followingTail: store.read() === null,
activeTurn: initialTurn,
}))
const [reading] = useState(() => new ChatReading(viewport, store, state, setState))
useLayoutEffect(() => { reading.setStore(store) }, [reading, store])
useLayoutEffect(() => () => { reading.dispose() }, [reading])
return { reading, state }
}
@@ -0,0 +1,126 @@
/** Composes viewport operations, reading policy, and history navigation for Chat. */
import { useCallback, useLayoutEffect, useMemo, useRef, type RefObject } from 'react'
import type { ChatSnapshot } from '../contract/snapshot.ts'
import type { ChatViewSlotProps } from '../contract/slots.ts'
import { useChatNavigation, type ChatNavigation, type ChatNavigationInput } from './use-chat-navigation.ts'
import { useChatReading, type ChatReadingState } from './use-chat-reading.ts'
import { useChatViewport } from './use-chat-viewport.ts'
/** Committed content and Session operations used to reconcile scroll ownership. */
export interface ChatScrollInput extends ChatNavigationInput {
readonly chatScroll: ChatViewSlotProps['chatScroll']
readonly ready: boolean
readonly order: readonly string[]
readonly lastKey: string | null
readonly lastIsUser: boolean
readonly steeringId: string | null
readonly submissionId: string | null
readonly running: boolean
readonly loadedTurns: ReturnType<ChatSnapshot['navigation']['items']>
}
interface ChatScrollState extends ChatReadingState {
readonly listRef: RefObject<HTMLDivElement>
readonly columnRef: RefObject<HTMLDivElement>
readonly busyTurn: number | null
readonly navigateToTurn: ChatNavigation['navigateToTurn']
readonly loadEarlier: ChatNavigation['loadEarlier']
readonly returnToBottom: () => void
}
/**
* Coordinate scroll policy after Chat content commits.
* @param input - current Chat content, scroll memory, and history operations.
* @returns element refs, visible reading state, and navigation callbacks.
*/
export function useChatScroll(input: ChatScrollInput): ChatScrollState {
const {
ready, order, firstSeq, lastKey, lastIsUser, steeringId, submissionId, running,
loadedTurns, chatScroll, hasMore, loadingOlder, loadOlder, loadThrough,
} = input
const { viewport, listRef, columnRef } = useChatViewport()
const { reading, state } = useChatReading(viewport, chatScroll, loadedTurns.at(-1)?.turn ?? null)
const navigationInput = useMemo(() => ({
firstSeq, loadingOlder, hasMore, loadOlder, loadThrough,
}), [firstSeq, loadingOlder, hasMore, loadOlder, loadThrough])
const { navigation, busyTurn } = useChatNavigation(viewport, reading, navigationInput)
const content = useRef<{ input: ChatScrollInput; applied: ChatScrollInput | null; opened: boolean }>({
input, applied: null, opened: false,
})
const processContent = useCallback(() => {
if (reading.pending) return
const current = content.current.input
const previous = content.current.applied
content.current.applied = current
if (current.ready && !content.current.opened) {
content.current.opened = true
navigation.reset()
reading.restore()
return
}
if (navigation.contentCommitted()) {
navigation.reconcile()
return
}
const ownInput = (current.lastIsUser && current.lastKey !== previous?.lastKey)
|| (current.steeringId !== null && current.steeringId !== previous?.steeringId)
|| (current.submissionId !== null && current.submissionId !== previous?.submissionId)
const tipChanged = previous === null || current.ready !== previous.ready
|| current.firstSeq !== previous.firstSeq || current.lastKey !== previous.lastKey
|| current.order.length !== previous.order.length || current.running !== previous.running
|| current.steeringId !== previous.steeringId || current.submissionId !== previous.submissionId
if (ownInput || (tipChanged && reading.followingTail)) {
navigation.cancel()
reading.followTail()
} else navigation.reconcile()
}, [reading, navigation])
useLayoutEffect(() => {
const disconnectViewport = viewport.connect({
scroll: reading.onScroll,
scrollEnd: reading.onScrollEnd,
resize: () => {
reading.onResize()
navigation.reconcile()
},
})
const disconnectReading = reading.connect((sample) => {
navigation.readerSampled(sample)
processContent()
})
return () => {
disconnectViewport()
disconnectReading()
content.current.opened = false
content.current.applied = null
}
}, [viewport, reading, navigation, processContent])
useLayoutEffect(() => {
const previous = content.current.input
content.current.input = {
ready, order, lastKey, lastIsUser, steeringId, submissionId, running, loadedTurns, chatScroll, ...navigationInput,
}
viewport.updateTurns(loadedTurns)
const layoutChanged = previous.order !== order || previous.ready !== ready
if (layoutChanged) viewport.invalidate()
processContent()
if (layoutChanged) reading.refreshActiveTurn()
}, [
viewport, reading, processContent, navigationInput, ready, order, lastKey, lastIsUser,
steeringId, submissionId, running, loadedTurns, chatScroll,
])
const returnToBottom = useCallback(() => {
navigation.cancel()
reading.followTail()
}, [navigation, reading])
return {
listRef, columnRef, ...state, busyTurn,
navigateToTurn: navigation.navigateToTurn,
loadEarlier: navigation.loadEarlier,
returnToBottom,
}
}
@@ -0,0 +1,346 @@
/** Turn-aware DOM scrolling and geometry, without history-loading or follow policy. */
import { useLayoutEffect, useRef, useState, type RefObject } from 'react'
import type { ChatScrollPosition } from '../contract/slots.ts'
import type { ChatSnapshot } from '../contract/snapshot.ts'
/** Scroll position, maximum top, and viewport height from one geometry read. */
export interface ViewportMetrics {
readonly top: number
readonly floor: number
readonly height: number
}
/** Scroll geometry attributed against the last acknowledged position. */
export interface ViewportScroll {
readonly metrics: ViewportMetrics
readonly movedByReader: boolean
}
/** Actual clamped scroll result, including any known semantic anchor and turn. */
export interface ViewportLanding {
readonly metrics: ViewportMetrics
readonly position: ChatScrollPosition | null
readonly turn: number | null
}
interface ViewportEvents {
scroll: (event: ViewportScroll) => void
scrollEnd: () => void
resize: () => void
}
interface ViewportElements {
readonly list: HTMLElement
readonly scroller: HTMLElement
readonly composer: HTMLElement | null
}
/** Owns one Chat scrollport's DOM operations, event listeners, and size observer. */
export class ChatViewport {
private elements: ViewportElements | null = null
private observer: ResizeObserver | null = null
private events: ViewportEvents | null = null
private turns: ReturnType<ChatSnapshot['navigation']['items']> = []
private observation: { top: number; landing: ViewportLanding | null } = { top: 0, landing: null }
/**
* Bind to the containing scrollport and observe content and viewport sizes.
* @param list - Chat root inside an optional shared conversation scrollport.
* @param column - content column whose size changes invalidate cached landings.
*/
attach(list: HTMLElement, column: HTMLElement): void {
this.detach()
const scroller = list.closest<HTMLElement>('[data-conversation-scroll]') ?? list
const composer = scroller.querySelector<HTMLElement>('[data-composer-seat]')
const elements = { list, scroller, composer }
this.elements = elements
scroller.addEventListener('scroll', this.onScroll, { passive: true })
scroller.addEventListener('scrollend', this.onScrollEnd, { passive: true })
if (typeof ResizeObserver !== 'undefined') {
this.observer = new ResizeObserver(() => {
if (this.elements !== elements) return
this.invalidate()
this.events?.resize()
})
this.observer.observe(column)
this.observer.observe(scroller)
if (composer !== null) this.observer.observe(composer)
}
}
/** Disconnect DOM resources and clear observations for the detached view. */
detach(): void {
this.elements?.scroller.removeEventListener('scroll', this.onScroll)
this.elements?.scroller.removeEventListener('scrollend', this.onScrollEnd)
this.observer?.disconnect()
this.observer = null
this.elements = null
this.events = null
this.turns = []
this.observation = { top: 0, landing: null }
}
/**
* Connect business policy without changing DOM listener ownership.
* @param events - business handlers for scroll and layout changes.
* @returns a disposer that disconnects only these handlers.
*/
connect(events: ViewportEvents): () => void {
this.events = events
return () => { if (this.events === events) this.events = null }
}
/**
* Adopt the loaded turn anchors without querying the DOM.
* @param turns - ordered loaded turns from the committed Chat snapshot.
*/
updateTurns(turns: ReturnType<ChatSnapshot['navigation']['items']>): void {
this.turns = turns
}
/**
* Resolve the tail from the committed turn index.
* @returns the latest loaded turn, or null for an empty window.
*/
get latestTurn(): number | null {
return this.turns.at(-1)?.turn ?? null
}
/** Discard geometry-dependent landing knowledge while retaining scroll attribution. */
invalidate(): void {
this.observation.landing = null
}
/**
* Accept a sampled reader position without retaining a known landing.
* @param metrics - settled reader position used as the next attribution baseline.
*/
acknowledge(metrics: ViewportMetrics): void {
this.observation = { top: metrics.top, landing: null }
}
/**
* Compare the current scroll geometry with the last acknowledged position.
* @returns current metrics and movement attribution, or null while detached.
*/
readScroll(): ViewportScroll | null {
const metrics = this.metrics()
if (metrics === null) return null
return {
metrics,
movedByReader: Math.abs(metrics.top - Math.min(this.observation.top, metrics.floor)) > 0.5,
}
}
private metrics(): ViewportMetrics | null {
const scroller = this.elements?.scroller
if (scroller === undefined) return null
const height = scroller.clientHeight
return { top: scroller.scrollTop, height, floor: Math.max(0, scroller.scrollHeight - height) }
}
private anchor(key: string): HTMLElement | null {
if (this.elements === null) return null
for (const row of this.elements.list.querySelectorAll<HTMLElement>('[data-chat-anchor-key]:not([hidden])')) {
if (row.dataset.chatAnchorKey === key) return row
}
return null
}
/**
* Capture the reader's position using visible transcript rows.
* @returns a visible semantic anchor, or null when no anchor can be resolved.
*/
capturePosition(): ChatScrollPosition | null {
const elements = this.elements
if (elements === null) return null
const { list, scroller, composer } = elements
const viewport = scroller.getBoundingClientRect()
const bottom = composer?.getBoundingClientRect().top ?? viewport.bottom
let anchor: HTMLElement | null = null
if (typeof document.elementsFromPoint === 'function' && bottom > viewport.top) {
const content = list.getBoundingClientRect()
const left = Math.max(viewport.left, content.left)
const right = Math.min(viewport.right, content.right)
for (const element of document.elementsFromPoint(left + Math.max(0, right - left) / 2, viewport.top + 1)) {
const row = element instanceof HTMLElement ? element.closest<HTMLElement>('[data-chat-anchor-key]') : null
if (row !== null && list.contains(row)) { anchor = row; break }
}
}
if (anchor === null) {
const rows = list.querySelectorAll<HTMLElement>(
'[data-chat-flow] > [data-chat-flow-key]:not(:empty):not([hidden])',
)
let low = 0
let high = rows.length
while (low < high) {
const middle = (low + high) >>> 1
if (rows.item(middle).getBoundingClientRect().bottom > viewport.top) high = middle
else low = middle + 1
}
const row = rows[low]
anchor = row !== undefined && row.getBoundingClientRect().top < bottom ? row : rows[0] ?? null
}
const key = anchor?.dataset.chatAnchorKey
return anchor === null || key === undefined ? null : {
anchorKey: key,
anchorTop: anchor.getBoundingClientRect().top - viewport.top,
scrollTop: scroller.scrollTop,
}
}
/**
* Resolve the active turn, reusing a known landing when its position is unchanged.
* @param metrics - reusable scroll metrics; omitted callers request a fresh read.
* @returns the loaded turn at the reading line, or null while detached or empty.
*/
readVisibleTurn(metrics = this.metrics()): number | null {
const knownTurn = this.observation.landing?.turn
if (knownTurn != null && metrics?.top === this.observation.top) return knownTurn
const elements = this.elements
const first = this.turns[0]
if (elements === null || metrics === null || first === undefined) return null
const line = elements.scroller.getBoundingClientRect().top + Math.min(96, metrics.height * 0.2)
const content = elements.list.getBoundingClientRect()
let reading: number | null = null
if (typeof document.elementsFromPoint === 'function' && content.width > 0) {
for (const element of document.elementsFromPoint(content.left + content.width / 2, line)) {
const row = element instanceof HTMLElement ? element.closest<HTMLElement>('[data-chat-turn]') : null
const turn = Number(row?.dataset.chatTurn)
if (row !== null && elements.list.contains(row) && Number.isSafeInteger(turn)) { reading = turn; break }
}
}
if (reading === null) {
for (const row of elements.list.querySelectorAll<HTMLElement>('[data-chat-turn]')) {
if (row.getBoundingClientRect().top > line) break
const turn = Number(row.dataset.chatTurn)
if (Number.isSafeInteger(turn)) reading = turn
}
}
let result = first.turn
if (reading !== null) {
for (const item of this.turns) {
if (item.turn > reading) break
result = item.turn
}
}
return result
}
/**
* Align a known loaded turn and return its actual clamped position.
* @param turn - loaded turn to align below the scrollport's top edge.
* @returns the actual landing, or null when its anchor is unavailable.
*/
scrollToTurn(turn: number): ViewportLanding | null {
const item = this.turns.find(candidate => candidate.turn === turn)
if (item === undefined) return null
const row = this.anchor(item.anchorKey)
return row === null ? null : this.align(row, 24, turn)
}
/**
* Align the nearest available fallback for an unavailable turn anchor.
* @param turn - minimum turn number for a mounted fallback row.
* @returns the fallback landing, or null when no eligible row exists.
*/
scrollToTurnAtOrAfter(turn: number): ViewportLanding | null {
if (this.elements === null) return null
for (const row of this.elements.list.querySelectorAll<HTMLElement>('[data-chat-turn]:not([hidden])')) {
const candidate = Number(row.dataset.chatTurn)
if (Number.isSafeInteger(candidate) && candidate >= turn) return this.align(row, 24, candidate)
}
return null
}
/**
* Restore a semantic anchor with a raw-position fallback.
* @param position - semantic scroll memory; raw top is used only if its row is absent.
* @returns the actual landing, or null while detached.
*/
restore(position: ChatScrollPosition): ViewportLanding | null {
const row = this.anchor(position.anchorKey)
if (row !== null) return this.align(row, position.anchorTop, null)
const metrics = this.metrics()
return metrics === null ? null : this.write(position.scrollTop, metrics, null)
}
/**
* Preserve an existing anchor without falling back to an unrelated row.
* @param position - semantic anchor to retain after content changes.
* @returns the compensated landing, or null if the anchor is unavailable.
*/
preserve(position: ChatScrollPosition): ViewportLanding | null {
const row = this.anchor(position.anchorKey)
return row === null ? null : this.align(row, position.anchorTop, null)
}
/**
* Align the scrollport with its current floor.
* @returns the actual floor landing, or null while detached.
*/
scrollToBottom(): ViewportLanding | null {
const metrics = this.metrics()
return metrics === null ? null : this.write(metrics.floor, metrics, this.latestTurn)
}
private align(row: HTMLElement, offset: number, turn: number | null): ViewportLanding | null {
const metrics = this.metrics()
if (metrics === null || this.elements === null) return null
const top = row.getBoundingClientRect().top - this.elements.scroller.getBoundingClientRect().top
return this.write(metrics.top + top - offset, metrics, turn, { key: row.dataset.chatAnchorKey, top })
}
private write(
target: number, metrics: ViewportMetrics, turn: number | null,
anchor?: { key: string | undefined; top: number },
): ViewportLanding | null {
if (this.elements === null) return null
const top = Math.max(0, Math.min(metrics.floor, target))
if (top !== metrics.top) this.elements.scroller.scrollTop = top
const actual = this.elements.scroller.scrollTop
const landing: ViewportLanding = {
metrics: { ...metrics, top: actual },
turn,
position: anchor?.key === undefined ? null : {
anchorKey: anchor.key,
anchorTop: anchor.top - (actual - metrics.top),
scrollTop: actual,
},
}
this.observation = { top: actual, landing }
return landing
}
private readonly onScroll = (event: Event): void => {
if (this.elements === null || event.target !== this.elements.scroller) return
if (this.observation.landing !== null && this.elements.scroller.scrollTop === this.observation.top) return
this.invalidate()
const scroll = this.readScroll()
if (scroll !== null) this.events?.scroll(scroll)
}
private readonly onScrollEnd = (event: Event): void => {
if (event.target === this.elements?.scroller) this.events?.scrollEnd()
}
}
/**
* Bind viewport resource ownership to the component's layout lifetime.
* @returns one viewport owner and the element refs attached for this mount.
*/
export function useChatViewport(): {
viewport: ChatViewport
listRef: RefObject<HTMLDivElement>
columnRef: RefObject<HTMLDivElement>
} {
const listRef = useRef<HTMLDivElement | null>(null)
const columnRef = useRef<HTMLDivElement | null>(null)
const [viewport] = useState(() => new ChatViewport())
useLayoutEffect(() => {
if (listRef.current === null || columnRef.current === null) return
viewport.attach(listRef.current, columnRef.current)
return () => { viewport.detach() }
}, [viewport])
return { viewport, listRef, columnRef }
}
@@ -45,18 +45,21 @@ import { formatRunDuration } from '../src/client/chat/message-chrome.ts'
import { ChatSnapshotBuilder } from '../src/client/conversation-nodes/chat-snapshot-builder.ts'
import type { TurnProcessSpec } from '../src/client/contract/turn-process.ts'
import { chatSnapshotFixture } from './chat-snapshot-fixture.client.ts'
import { installTurnNavigatorObserver } from './turn-navigator-fixture.ts'
// Every session-scope fixture carries the resource hook the resources plugin merges into GlobalStandardProps.
const useResource = (() => ({ status: 'none' as const, value: undefined, failure: undefined })) as GlobalStandardProps['useResource']
afterEach(() => {
cleanup()
vi.restoreAllMocks()
vi.unstubAllGlobals()
})
// Keyless create() persists under the bare declared key; clear between cases
// so one harness's selection cannot rehydrate into the next.
beforeEach(() => {
localStorage.clear()
installTurnNavigatorObserver()
})
const SID = 's1' as SessionId
@@ -601,7 +604,7 @@ describe('ChatView', () => {
expect(railRenders).toBe(afterMount)
})
it('projects loaded turns into prompt and response navigation previews', () => {
it('projects loaded turns into prompt and response navigation previews', async () => {
const snapshot = chatSnapshotFixture({
nodes: [
userInTurn(1, 'first prompt', 1),
@@ -618,11 +621,11 @@ describe('ChatView', () => {
const h = makeHarness({}, {}, snapshot)
const view = render(<h.ChatView {...h.props} />)
const navigation = view.getByRole('navigation', { name: '轮次导航' })
expect(navigation.style.getPropertyValue('--turn-natural-height')).toBe('22px')
const first = view.getByRole('button', { name: '跳转到第 1 轮' })
const first = await view.findByRole('button', { name: '跳转到第 1 轮' })
expect(within(navigation).getAllByRole('button').map(mark => mark.getAttribute('aria-label'))).toEqual([
'跳转到第 1 轮', '跳转到第 2 轮',
])
const second = view.getByRole('button', { name: '跳转到第 2 轮' })
expect(first.parentElement?.style.getPropertyValue('--turn-natural-position')).toBe('0px')
expect(second.parentElement?.style.getPropertyValue('--turn-natural-position')).toBe('10px')
expect(second.getAttribute('aria-current')).toBe('true')
fireEvent.focus(first)
const preview = view.getByRole('tooltip')
@@ -630,16 +633,14 @@ describe('ChatView', () => {
expect(preview.textContent).toContain('first response')
})
it('jumps to a turn anchor and reflows stable marks after an older page arrives', () => {
it('jumps to a turn anchor and reflows stable marks after an older page arrives', async () => {
const later = [
userInTurn(4, 'second prompt', 2), assistant(5, 'second response', 2),
userInTurn(7, 'third prompt', 3), assistant(8, 'third response', 3),
]
const h = makeHarness({ nodes: later }, { hasMore: true })
const view = render(<h.ChatView {...h.props} />)
const second = view.getByRole('button', { name: '跳转到第 2 轮' })
const secondPosition = second.parentElement as HTMLElement
expect(secondPosition.style.getPropertyValue('--turn-natural-position')).toBe('0px')
const second = await view.findByRole('button', { name: '跳转到第 2 轮' })
const scroller = view.container.querySelector('[class*="scroll"]') as HTMLDivElement
const metrics = installScrollMetrics(scroller, 1_000, 300)
@@ -658,9 +659,10 @@ describe('ChatView', () => {
})
})
const movedSecond = view.getByRole('button', { name: '跳转到第 2 轮' })
expect(movedSecond.parentElement).toBe(secondPosition)
// Fixed pitch: the mark moves one slot down and never compresses.
expect(secondPosition.style.getPropertyValue('--turn-natural-position')).toBe('10px')
expect(movedSecond).toBe(second)
expect(within(view.getByRole('navigation')).getAllByRole('button').map(mark => mark.getAttribute('aria-label'))).toEqual([
'跳转到第 1 轮', '跳转到第 2 轮', '跳转到第 3 轮',
])
})
it('extends the rail with unloaded outline turns, pages on click, and falls back when nothing lands', async () => {
@@ -672,7 +674,7 @@ describe('ChatView', () => {
{ turn: 3, seq: 8, prompt: 'third prompt', response: 'third response' },
])
const view = render(<h.ChatView {...h.props} />)
const first = view.getByRole('button', { name: '加载并跳转到第 1 轮' })
const first = await view.findByRole('button', { name: '加载并跳转到第 1 轮' })
view.getByRole('button', { name: '加载并跳转到第 2 轮' })
const third = view.getByRole('button', { name: '跳转到第 3 轮' })
expect(third.getAttribute('aria-current')).toBe('true')
@@ -687,12 +689,48 @@ describe('ChatView', () => {
// The fake loader never delivers rows: settlement repages once for the
// unmoved head, then lands on the nearest rendered turn and un-busies.
await act(async () => {})
await waitFor(() => { expect(first.getAttribute('aria-busy')).toBeNull() })
expect(h.loadThrough.mock.calls).toEqual([[0], [0]])
expect(first.getAttribute('aria-busy')).toBeNull()
expect(view.getByRole('button', { name: '跳转到第 3 轮' }).getAttribute('aria-current')).toBe('true')
})
it('uses a known turn landing without hit testing or consuming rail scroll as transcript input', async () => {
const original = Object.getOwnPropertyDescriptor(document, 'elementsFromPoint')
const hitTest = vi.fn((): Element[] => [])
Object.defineProperty(document, 'elementsFromPoint', { configurable: true, value: hitTest })
try {
const h = makeHarness({ nodes: [
userInTurn(1, 'first', 1), assistant(2, 'first answer', 1),
userInTurn(4, 'second', 2), assistant(5, 'second answer', 2),
] })
const view = render(<h.ChatView {...h.props} />)
const first = await view.findByRole('button', { name: '跳转到第 1 轮' })
const scroller = view.container.querySelector('[class*="scroll"]') as HTMLDivElement
installScrollMetrics(scroller, 1_500, 300)
const row = view.container.querySelector('[data-chat-anchor-key="fixture:user:1"]') as HTMLElement
vi.spyOn(scroller, 'getBoundingClientRect').mockReturnValue(new DOMRect(0, 0, 800, 300))
vi.spyOn(row, 'getBoundingClientRect').mockImplementation(() => new DOMRect(0, 100 - scroller.scrollTop, 800, 40))
readerScroll(scroller, 600)
scroller.scrollTop = 500
fireEvent.scroll(scroller)
hitTest.mockClear()
fireEvent.click(first)
fireEvent.scroll(scroller)
fireEvent(scroller, new Event('scrollend'))
const rail = view.getByRole('navigation').firstElementChild as HTMLElement
fireEvent.scroll(rail)
fireEvent(rail, new Event('scrollend', { bubbles: true }))
expect(scroller.scrollTop).toBe(76)
expect(first.getAttribute('aria-current')).toBe('true')
expect(hitTest).not.toHaveBeenCalled()
} finally {
if (original === undefined) Reflect.deleteProperty(document, 'elementsFromPoint')
else Object.defineProperty(document, 'elementsFromPoint', original)
}
})
it('a jump from the pinned tail releases bottom ownership so the follow snap cannot cancel it', async () => {
const later = [userInTurn(8, 'third prompt', 3), assistant(9, 'third response', 3)]
const h = makeHarness({ nodes: later }, { hasMore: true })
@@ -706,7 +744,7 @@ describe('ChatView', () => {
// Pinned to the tail on open: the back-to-bottom control is absent.
expect(view.queryByRole('button', { name: '回到底部' })).toBeNull()
const first = view.getByRole('button', { name: '加载并跳转到第 1 轮' })
const first = await view.findByRole('button', { name: '加载并跳转到第 1 轮' })
fireEvent.click(first)
// The click itself leaves the tail...
expect(view.getByRole('button', { name: '回到底部' })).toBeTruthy()
@@ -726,7 +764,7 @@ describe('ChatView', () => {
{ turn: 3, seq: 8, prompt: 'third prompt', response: '' },
])
const view = render(<h.ChatView {...h.props} />)
const first = view.getByRole('button', { name: '加载并跳转到第 1 轮' })
const first = await view.findByRole('button', { name: '加载并跳转到第 1 轮' })
fireEvent.click(first)
// The session-side guard refuses the busy-pager jump instantly, yet the
// mark stays busy instead of degrading to the nearest loaded turn.
@@ -736,12 +774,11 @@ describe('ChatView', () => {
// The plain pull settles: the flip re-settles the jump, which repages.
act(() => { h.setSession({ loadingOlder: false }) })
await act(async () => {})
await waitFor(() => { expect(first.getAttribute('aria-busy')).toBeNull() })
expect(h.loadThrough.mock.calls).toEqual([[0], [0]])
expect(first.getAttribute('aria-busy')).toBeNull()
})
it('scrolls the fixed-pitch rail inside its frame with gradient fades at the scrollable ends', () => {
it('scrolls the fixed-pitch rail inside its frame with gradient fades at the scrollable ends', async () => {
const h = makeHarness(
{ nodes: [userInTurn(8, 'latest prompt', 60), assistant(9, 'latest response', 60)] },
{ hasMore: true },
@@ -754,11 +791,11 @@ describe('ChatView', () => {
})))
const view = render(<h.ChatView {...h.props} />)
const nav = view.getByRole('navigation', { name: '轮次导航' })
// 60 marks at the fixed 10px pitch: the ladder keeps its natural height.
expect(nav.style.getPropertyValue('--turn-natural-height')).toBe('602px')
const scroller = nav.querySelector('[class*="scroller"]') as HTMLElement
Object.defineProperty(scroller, 'scrollHeight', { value: 602, configurable: true })
Object.defineProperty(scroller, 'clientHeight', { value: 300, configurable: true })
const latest = await within(nav).findByRole('button', { name: '跳转到第 60 轮' })
expect(scroller.scrollTop).toBe(302)
expect(within(nav).getAllByRole('button').length).toBeLessThan(60)
expect(latest.getAttribute('aria-current')).toBe('true')
scroller.scrollTop = 0
fireEvent.scroll(scroller)
expect(scroller.className).toContain('fadeBottom')
@@ -768,12 +805,7 @@ describe('ChatView', () => {
fireEvent.scroll(scroller)
expect(scroller.className).toContain('fadeTop')
expect(scroller.className).toContain('fadeBottom')
expect(nav.style.getPropertyValue('--turn-scroll-top')).toBe('150px')
// Pointer mapping subtracts the rail scroll: y=94 with scrollTop 150 is
// natural offset 238px → the 25th mark.
vi.spyOn(nav, 'getBoundingClientRect').mockReturnValue({ top: 0 } as DOMRect)
fireEvent.pointerMove(nav, { clientY: 94 })
fireEvent.pointerEnter(within(nav).getByRole('button', { name: '加载并跳转到第 25 轮' }))
expect(view.getByRole('tooltip').textContent).toContain('p25')
})
@@ -787,8 +819,18 @@ describe('ChatView', () => {
let releaseJump: (() => void) | undefined
h.loadThrough.mockImplementation(() => new Promise<void>((resolve) => { releaseJump = resolve }))
const view = render(<h.ChatView {...h.props} />)
const scroller = view.container.querySelector('[class*="scroll"]') as HTMLDivElement
installScrollMetrics(scroller, 1_000, 300)
scroller.scrollTop = 700
vi.spyOn(HTMLElement.prototype, 'getBoundingClientRect').mockImplementation(function (this: HTMLElement) {
if (this.dataset.chatAnchorKey === 'fixture:user:0') {
const top = 100 - scroller.scrollTop
return { top, bottom: top + 40 } as DOMRect
}
return { top: 0, bottom: 300 } as DOMRect
})
fireEvent.click(view.getByRole('button', { name: '加载并跳转到第 1 轮' }))
fireEvent.click(await view.findByRole('button', { name: '加载并跳转到第 1 轮' }))
expect(h.loadThrough).toHaveBeenCalledWith(0)
// The paged window commits: turn 1's rows and rail item enter the snapshot.
@@ -800,15 +842,14 @@ describe('ChatView', () => {
})
const first = view.getByRole('button', { name: '跳转到第 1 轮' })
expect(first.getAttribute('aria-current')).toBe('true')
expect(scroller.scrollTop).toBe(76)
// The mark stays busy until the jump settles: the loader's completion
// runs the final landing correction after the load-earlier button leaves.
expect(first.getAttribute('aria-busy')).toBe('true')
await act(async () => { releaseJump?.() })
// Only the busy lifecycle is asserted after settlement: jsdom's zero
// geometry makes the rAF active-turn resync read "at bottom" and hand the
// mark to the last turn, so aria-current here is timing-dependent under
// instrumentation; the landing position contract lives in the browser e2e.
expect(first.getAttribute('aria-busy')).toBeNull()
await waitFor(() => { expect(first.getAttribute('aria-busy')).toBeNull() })
expect(first.getAttribute('aria-current')).toBe('true')
expect(scroller.scrollTop).toBe(76)
})
it('hands a windowless tool result to the Tool seat with an empty tool name', () => {
@@ -2365,7 +2406,7 @@ describe('ChatView', () => {
nodes: [user(1, 'old'), assistant(2, 'b'), user(5, 'later'), assistant(6, 'a'), user(9, 'mine')],
})
})
expect(scroller.scrollTop).toBe(1600)
expect(scroller.scrollTop).toBe(1200)
})
it('back-to-bottom cancels an in-flight paging anchor', () => {
@@ -2379,7 +2420,7 @@ describe('ChatView', () => {
fireEvent.click(view.getByLabelText('回到底部'))
Object.defineProperty(scroller, 'scrollHeight', { value: 1_300, writable: true })
act(() => { h.setChat({ nodes: [assistant(2, 'older'), user(9, 'late')] }) })
expect(scroller.scrollTop).toBe(1_300)
expect(scroller.scrollTop).toBe(1_100)
expect(h.chatScroll.read()).toBeNull()
})
@@ -2398,7 +2439,7 @@ describe('ChatView', () => {
})
expect(scroller.scrollTop).toBe(100)
fireEvent.click(backButton)
expect(scroller.scrollTop).toBe(1000)
expect(scroller.scrollTop).toBe(700)
// At the bottom again: follow re-arms and the button unmounts.
expect(view.queryByLabelText('回到底部')).toBeNull()
})
@@ -2601,7 +2642,7 @@ describe('ChatView', () => {
it('one ResizeObserver owns pinned dynamic-height follow and ignores growth while away', () => {
let notify: (() => void) | undefined
const observe = vi.fn()
const observe = vi.fn<(element: Element) => void>()
class ResizeObserverStub {
constructor(callback: ResizeObserverCallback) {
notify = () => { callback([], this as unknown as ResizeObserver) }
@@ -2621,15 +2662,17 @@ describe('ChatView', () => {
fireEvent(scroller, new Event('scrollend'))
Object.defineProperty(scroller, 'scrollHeight', { value: 1_200, writable: true })
act(() => { notify?.() })
expect(scroller.scrollTop).toBe(1_200)
expect(scroller.scrollTop).toBe(900)
readerScroll(scroller, 200)
Object.defineProperty(scroller, 'scrollHeight', { value: 1_400, writable: true })
act(() => { notify?.() })
expect(scroller.scrollTop).toBe(200)
expect(observe).toHaveBeenCalledTimes(1)
expect(observe.mock.calls.map(([element]) => element)).toEqual([
view.container.querySelector('[data-chat-flow]'), scroller,
])
})
it('pinned dynamic-height updates select the latest Turn without reading row geometry', () => {
it('pinned dynamic-height updates select the latest Turn without reading row geometry', async () => {
let notify: (() => void) | undefined
let nextFrame = 0
const frames = new Map<number, FrameRequestCallback>()
@@ -2639,13 +2682,19 @@ describe('ChatView', () => {
return nextFrame
})
vi.stubGlobal('cancelAnimationFrame', (id: number) => { frames.delete(id) })
class ResizeObserverStub {
const RailObserver = ResizeObserver
class ResizeObserverStub extends RailObserver {
private readonly onResize: () => void
constructor(callback: ResizeObserverCallback) {
notify = () => { callback([], this as unknown as ResizeObserver) }
super(callback)
this.onResize = () => { callback([], this) }
}
observe = vi.fn()
disconnect = vi.fn()
override observe(element: Element): void {
super.observe(element)
if (element.closest('nav') === null) notify = this.onResize
}
}
vi.stubGlobal('ResizeObserver', ResizeObserverStub)
const rect = vi.spyOn(HTMLElement.prototype, 'getBoundingClientRect')
@@ -2658,6 +2707,7 @@ describe('ChatView', () => {
turnEnds: new Map([[1, 3], [2, 6]]),
})
const view = render(<h.ChatView {...h.props} />)
await view.findByRole('button', { name: '跳转到第 2 轮' })
const scroller = view.container.querySelector('[class*="scroll"]') as HTMLDivElement
const metrics = installScrollMetrics(scroller, 1_000, 300)
scroller.scrollTop = 700
@@ -2705,11 +2755,11 @@ describe('ChatView', () => {
const h = makeHarness({ nodes: [user(1, 'q'), assistant(2, 'a')] })
const view = render(<h.ChatView {...h.props} />, { container: host })
// Open jump uses the host, not the local .scroll node.
expect(host.scrollTop).toBe(2000)
expect(host.scrollTop).toBe(1500)
readerScroll(host, 100)
expect(view.getByLabelText('回到底部')).toBeTruthy()
fireEvent.click(view.getByLabelText('回到底部'))
expect(host.scrollTop).toBe(2000)
expect(host.scrollTop).toBe(1500)
} finally {
host.remove()
}
@@ -2722,12 +2772,13 @@ describe('ChatView', () => {
Object.defineProperty(host, 'clientHeight', { value: 500, writable: true, configurable: true })
Object.defineProperty(host, 'scrollTop', { value: 0, writable: true, configurable: true })
document.body.appendChild(host)
let anchorTop = 80
let anchorOffset = 180
vi.spyOn(host, 'getBoundingClientRect').mockImplementation(
() => ({ top: 0, bottom: 500 } as DOMRect),
)
const rect = vi.spyOn(HTMLElement.prototype, 'getBoundingClientRect').mockImplementation(function (this: HTMLElement) {
if (this.dataset.chatAnchorKey === 'fixture:user:1') {
const anchorTop = anchorOffset - host.scrollTop
return { top: anchorTop, bottom: anchorTop + 40 } as DOMRect
}
return { top: 0, bottom: 40 } as DOMRect
@@ -2736,15 +2787,15 @@ describe('ChatView', () => {
const h = makeHarness({ nodes: [user(1, 'q'), assistant(2, 'a')] })
// Fresh open (nothing saved): the bottom jump stands.
const view = render(<h.ChatView {...h.props} />, { container: host })
expect(host.scrollTop).toBe(2000)
expect(host.scrollTop).toBe(1500)
// Reader scrolls up; the position is recorded continuously.
readerScroll(host, 100)
// View-tab switch away and back: the view unmounts, then remounts.
view.rerender(<div />)
anchorTop = 560
anchorOffset = 660
host.scrollTop = 0
view.rerender(<h.ChatView {...h.props} />)
expect(host.scrollTop).toBe(580) // approximate 100 + the row's 480px reflow shift
expect(host.scrollTop).toBe(580)
// The restored position is above the floor: follow stays disarmed.
expect(view.getByLabelText('回到底部')).toBeTruthy()
} finally {
@@ -2766,7 +2817,10 @@ describe('ChatView', () => {
})
document.body.appendChild(host)
const rect = vi.spyOn(HTMLElement.prototype, 'getBoundingClientRect').mockImplementation(function (this: HTMLElement) {
if (this.dataset.chatAnchorKey === 'fixture:user:1') return { top: 300, bottom: 340 } as DOMRect
if (this.dataset.chatAnchorKey === 'fixture:user:1') {
const top = 1_700 - host.scrollTop
return { top, bottom: top + 40 } as DOMRect
}
return { top: 0, bottom: 500 } as DOMRect
})
try {
@@ -2801,7 +2855,7 @@ describe('ChatView', () => {
view.rerender(<div />)
host.scrollTop = 0
view.rerender(<h.ChatView {...h.props} />)
expect(host.scrollTop).toBe(2000)
expect(host.scrollTop).toBe(1500)
} finally {
host.remove()
}