From 64963e061ac09fd822cb602f5cb6331f33eb7836 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Carlos=20Flor=C3=AAncio?= Date: Wed, 26 Aug 2026 20:36:08 +0000 Subject: [PATCH] fix: prevent chat pagination scroll flicker (#3063) --- .../task/chat/message-list-native-boundary.ts | 14 ++ .../task/chat/message-list-native-scroll.ts | 188 ++++++++++++++++-- .../task/chat/message-list-native.test.tsx | 89 ++++++++- .../tests/chat/message-pagination-helpers.ts | 84 +++++++- .../e2e/tests/chat/message-pagination.spec.ts | 107 ++++++++-- .../chat/mobile-message-pagination.spec.ts | 104 ++++++++-- apps/web/hooks/use-lazy-load-sentinel.test.ts | 94 +++++++++ apps/web/hooks/use-lazy-load-sentinel.ts | 128 ++++++++++-- apps/web/lib/debug/log.ts | 3 +- .../chat-scroll-pagination-flicker/plan.md | 136 +++++++++++++ ...-constrain-transcript-pagination-cycles.md | 98 +++++++++ .../task-prompt-transcript-visibility.md | 40 +++- 12 files changed, 995 insertions(+), 90 deletions(-) create mode 100644 apps/web/components/task/chat/message-list-native-boundary.ts create mode 100644 docs/plans/chat-scroll-pagination-flicker/plan.md create mode 100644 docs/plans/chat-scroll-pagination-flicker/task-01-constrain-transcript-pagination-cycles.md diff --git a/apps/web/components/task/chat/message-list-native-boundary.ts b/apps/web/components/task/chat/message-list-native-boundary.ts new file mode 100644 index 0000000000..49488727a4 --- /dev/null +++ b/apps/web/components/task/chat/message-list-native-boundary.ts @@ -0,0 +1,14 @@ +import type { RenderItem } from "@/hooks/use-processed-messages"; +import { TASK_DESCRIPTION_SYNTHETIC_ID } from "@/hooks/use-processed-messages"; + +/** Stable descriptor for the oldest visible row; turn ids survive group extension. */ +export function getOldestVisibleBoundaryKey(items: RenderItem[]): string | null { + const item = items.find( + (candidate) => + candidate.type === "turn_group" || + (candidate.type === "message" && candidate.message.id !== TASK_DESCRIPTION_SYNTHETIC_ID), + ); + if (!item) return null; + if (item.type === "turn_group") return `turn:${item.turnId ?? item.id}`; + return item.type === "message" ? `message:${item.message.id}` : item.id; +} diff --git a/apps/web/components/task/chat/message-list-native-scroll.ts b/apps/web/components/task/chat/message-list-native-scroll.ts index fcffaec8d5..a34b8f2fdd 100644 --- a/apps/web/components/task/chat/message-list-native-scroll.ts +++ b/apps/web/components/task/chat/message-list-native-scroll.ts @@ -2,10 +2,14 @@ import { useCallback, useEffect, useLayoutEffect, useRef } from "react"; import { useDockviewStore } from "@/lib/state/dockview-store"; import { useAppStoreApi } from "@/components/state-provider"; import { getStoredAutoScrollTop } from "@/lib/local-storage"; -import { useLazyLoadSentinel as useSharedLazyLoadSentinel } from "@/hooks/use-lazy-load-sentinel"; +import { + useLazyLoadSentinel as useSharedLazyLoadSentinel, + type LazyLoadSentinelSettleResult, +} from "@/hooks/use-lazy-load-sentinel"; import type { Message } from "@/lib/types/http"; import { TASK_DESCRIPTION_SYNTHETIC_ID, type RenderItem } from "@/hooks/use-processed-messages"; import { getItemKey, shouldAutoScrollToBottom } from "./message-list-shared"; +import { getOldestVisibleBoundaryKey } from "./message-list-native-boundary"; import { isPrependUpdate, hasTranscriptProgressedPastView, @@ -15,6 +19,56 @@ import { createFrameCoalescer, } from "./transcript-auto-scroll"; import { scheduleClampedScrollRestore } from "./clamped-scroll-restore"; +import { createDebugLogger, isDebug } from "@/lib/debug/log"; + +const paginationDebug = createDebugLogger("messages:pagination"); + +type PaginationRequest = { + boundaryBefore: string | null; + debug?: { + generation: number; + scrollTopBefore: number | null; + scrollHeightBefore: number | null; + }; +}; + +type PaginationStopReason = + | "visible-boundary-unchanged" + | "visible-boundary-added" + | "exhausted" + | "no-progress" + | "sentinel-left-preload" + | "disarmed" + | "blocked" + | "stale" + | "not-rearmed"; + +export function resolvePaginationStopReason( + boundaryUnchanged: boolean, + hasMore: boolean, +): PaginationStopReason { + if (!hasMore) return "exhausted"; + return boundaryUnchanged ? "visible-boundary-unchanged" : "visible-boundary-added"; +} + +function resolvePaginationSettleReason( + result: LazyLoadSentinelSettleResult, + boundaryUnchanged: boolean, + hasMore: boolean, +): PaginationStopReason | null { + switch (result.continuation) { + case "continued": + return null; + case "rejected": + case "no-progress": + return "no-progress"; + case "caller-stopped": + case "no-more": + return resolvePaginationStopReason(boundaryUnchanged, hasMore); + default: + return result.continuation; + } +} /** * Continuously captures scroll state via scroll listener. @@ -135,24 +189,121 @@ function capturePrependScrollState(scrollRoot: HTMLElement, anchorKey: string | /** * Observes a sentinel element at the top of the list to trigger lazy loading. - * Delegates to the shared useLazyLoadSentinel hook with positive-result - * automatic re-arming enabled. The transcript still does not join an - * in-flight request: it waits for its current page before observing the next - * one. The explicit button remains the recovery path for errors and no-op - * responses. + * Re-arms only while older pages leave the committed visible boundary + * unchanged, which crosses collapsed activity without cascading through + * standalone messages. The transcript does not join an in-flight request. + * The explicit button remains the recovery path for errors and no-op pages. */ -function useLazyLoadSentinel( - scrollRef: React.RefObject, - hasMore: boolean, - blocked: boolean, - isLoadingMore: boolean, - loadMore: () => Promise, -) { - return useSharedLazyLoadSentinel(scrollRef, hasMore, blocked, isLoadingMore, loadMore, { +function useLazyLoadSentinel(params: { + scrollRef: React.RefObject; + items: RenderItem[]; + sessionId: string | null; + hasMore: boolean; + blocked: boolean; + isLoadingMore: boolean; + loadMore: () => Promise; +}) { + const { scrollRef, items, sessionId, hasMore, blocked, isLoadingMore, loadMore } = params; + const itemsRef = useRef(items); + itemsRef.current = items; + const hasMoreRef = useRef(hasMore); + hasMoreRef.current = hasMore; + const requestGenerationRef = useRef(0); + const requestRef = useRef(null); + + const reportSettle = useCallback( + (result: LazyLoadSentinelSettleResult) => { + if (!isDebug()) return; + const request = requestRef.current; + const requestDebug = request?.debug; + if (!request || !requestDebug) return; + const boundaryAfter = getOldestVisibleBoundaryKey(itemsRef.current); + const scroller = scrollRef.current; + const boundaryUnchanged = request.boundaryBefore === boundaryAfter; + paginationDebug("older page settled", { + sessionId, + trigger: "top-intersection", + generation: requestDebug.generation, + loadedCount: result.count, + boundaryBefore: request.boundaryBefore, + boundaryAfter, + scrollTopBefore: requestDebug.scrollTopBefore, + scrollTopAfter: scroller?.scrollTop ?? null, + scrollHeightBefore: requestDebug.scrollHeightBefore, + scrollHeightAfter: scroller?.scrollHeight ?? null, + continued: result.continuation === "continued", + stopReason: resolvePaginationSettleReason(result, boundaryUnchanged, hasMoreRef.current), + continuation: result.continuation, + }); + }, + [scrollRef, sessionId], + ); + + const loadPage = useCallback(async () => { + const request: PaginationRequest = { + boundaryBefore: getOldestVisibleBoundaryKey(itemsRef.current), + }; + requestRef.current = request; + if (isDebug()) { + const scroller = scrollRef.current; + request.debug = { + generation: ++requestGenerationRef.current, + scrollTopBefore: scroller?.scrollTop ?? null, + scrollHeightBefore: scroller?.scrollHeight ?? null, + }; + paginationDebug("older page started", { + sessionId, + trigger: "top-intersection", + generation: request.debug.generation, + boundaryBefore: request.boundaryBefore, + scrollTopBefore: request.debug.scrollTopBefore, + scrollHeightBefore: request.debug.scrollHeightBefore, + }); + } + return loadMore(); + }, [loadMore, scrollRef, sessionId]); + + const shouldContinueWhileIntersecting = useCallback(() => { + const request = requestRef.current; + if (!request) return false; + const boundaryAfter = getOldestVisibleBoundaryKey(itemsRef.current); + const boundaryUnchanged = request.boundaryBefore === boundaryAfter; + return boundaryUnchanged && hasMoreRef.current; + }, []); + + return useSharedLazyLoadSentinel(scrollRef, hasMore, blocked, isLoadingMore, loadPage, { rearmWhileIntersecting: true, + shouldContinueWhileIntersecting, + onLoadSettled: isDebug() ? reportSettle : undefined, }); } +/** + * Treats an actual upward movement as fresh pagination intent. This is + * modality-independent (wheel, keyboard, scrollbar, or touch) and only calls + * the shared sentinel's guarded retry path; normal armed scrolling remains + * owned by IntersectionObserver. + */ +function useRetryPaginationOnUpwardScroll( + scrollRef: React.RefObject, + onUserGesture: () => void, + isProgrammaticScrollLocked: () => boolean, +) { + useEffect(() => { + const scroller = scrollRef.current; + if (!scroller) return; + let previousScrollTop = scroller.scrollTop; + const onScroll = () => { + const nextScrollTop = scroller.scrollTop; + const movedUp = nextScrollTop < previousScrollTop; + previousScrollTop = nextScrollTop; + if (movedUp && !isProgrammaticScrollLocked()) onUserGesture(); + }; + scroller.addEventListener("scroll", onScroll, { passive: true }); + return () => scroller.removeEventListener("scroll", onScroll); + }, [isProgrammaticScrollLocked, onUserGesture, scrollRef]); +} + /** Duration a programmatic scroll's guard stays held if the browser never * reports `scrollend` (Safari lacks it as of writing; some scroll targets * fire it inconsistently). Comfortably longer than a `scrollIntoView` @@ -631,13 +782,16 @@ export function useNativeScrollManagement(params: { ); const handleScrollToMessage = useScrollToMessage(scrollRef, runGuardedScroll); useScrollPositionOnPrepend(scrollRef, items, isLoadingMore, isProgrammaticScrollLocked); - const { sentinelRef } = useLazyLoadSentinel( + const { sentinelRef, onUserGesture } = useLazyLoadSentinel({ scrollRef, + items, + sessionId, hasMore, - messagesLoading, + blocked: messagesLoading, isLoadingMore, loadMore, - ); + }); + useRetryPaginationOnUpwardScroll(scrollRef, onUserGesture, isProgrammaticScrollLocked); useInitialScrollPosition(scrollRef, items.length, sessionId, enabled, isNearBottomRef); return { handleScrollToMessage, sentinelRef, resyncIsNearBottom, markNotNearBottom }; diff --git a/apps/web/components/task/chat/message-list-native.test.tsx b/apps/web/components/task/chat/message-list-native.test.tsx index e4b823dfc9..0923dcd0af 100644 --- a/apps/web/components/task/chat/message-list-native.test.tsx +++ b/apps/web/components/task/chat/message-list-native.test.tsx @@ -6,11 +6,12 @@ import type { Message } from "@/lib/types/http"; import type { RenderItem } from "@/hooks/use-processed-messages"; const sharedSentinelCalls = vi.hoisted(() => [] as unknown[][]); +const sharedSentinelUserGesture = vi.hoisted(() => vi.fn()); vi.mock("@/hooks/use-lazy-load-sentinel", () => ({ useLazyLoadSentinel: (...args: unknown[]) => { sharedSentinelCalls.push(args); - return { sentinelRef: () => {}, onUserGesture: () => {} }; + return { sentinelRef: () => {}, onUserGesture: sharedSentinelUserGesture }; }, })); @@ -30,6 +31,7 @@ vi.mock("@/components/state-provider", () => ({ import { useScrollToDividerOrBottom } from "./message-list-native"; import { + resolvePaginationStopReason, useAutoScroll, useNativeScrollManagement, useScrollToMessage, @@ -139,6 +141,7 @@ function setScrollMetrics(element: HTMLElement) { afterEach(() => { cleanup(); sharedSentinelCalls.length = 0; + sharedSentinelUserGesture.mockReset(); vi.restoreAllMocks(); }); @@ -146,12 +149,18 @@ function transcriptMessage(id: string): RenderItem { return { type: "message", message: { id } as Message }; } +function transcriptActivity(id: string, turnId = id): RenderItem { + return { type: "turn_group", id, turnId, messages: [] }; +} + function NativeScrollManagementHarness({ items, metrics, + loadMore = async () => 0, }: { items: RenderItem[]; metrics?: { scrollHeight: number; scrollTop: number; clientHeight: number }; + loadMore?: () => Promise; }) { const scrollRef = useRef(null); useNativeScrollManagement({ @@ -165,7 +174,7 @@ function NativeScrollManagementHarness({ messagesLoading: false, hasMore: true, isLoadingMore: false, - loadMore: async () => 0, + loadMore, }); useLayoutEffect(() => { const element = scrollRef.current; @@ -185,12 +194,84 @@ function NativeScrollManagementHarness({ return
; } +describe("resolvePaginationStopReason", () => { + it.each([ + { boundaryUnchanged: true, hasMore: true, expected: "visible-boundary-unchanged" }, + { boundaryUnchanged: false, hasMore: true, expected: "visible-boundary-added" }, + { boundaryUnchanged: true, hasMore: false, expected: "exhausted" }, + { boundaryUnchanged: false, hasMore: false, expected: "exhausted" }, + ])( + "resolves pagination stop reason for $expected", + ({ boundaryUnchanged, hasMore, expected }) => { + expect(resolvePaginationStopReason(boundaryUnchanged, hasMore)).toBe(expected); + }, + ); +}); + describe("useNativeScrollManagement transcript pagination", () => { - it("re-arms the native sentinel without joining its in-flight request", () => { + it("retries a disarmed short page on the next upward scroll", () => { + const metrics = { scrollHeight: 1000, scrollTop: 100, clientHeight: 400 }; + render(); + const scroller = screen.getByTestId("native-scroll-management-container"); + + act(() => { + metrics.scrollTop = 80; + scroller.dispatchEvent(new Event("scroll")); + }); + expect(sharedSentinelUserGesture).toHaveBeenCalledTimes(1); + + act(() => { + metrics.scrollTop = 120; + scroller.dispatchEvent(new Event("scroll")); + }); + expect(sharedSentinelUserGesture).toHaveBeenCalledTimes(1); + }); + + it("re-arms the native sentinel with a visible-boundary continuation decision", () => { render(); const options = sharedSentinelCalls[0]?.[5]; - expect(options).toEqual({ rearmWhileIntersecting: true }); + expect(options).toEqual({ + rearmWhileIntersecting: true, + shouldContinueWhileIntersecting: expect.any(Function), + onLoadSettled: expect.any(Function), + }); + }); + + it("continues only while an older page keeps the same visible boundary", async () => { + const loadMore = vi.fn(async () => 20); + const newest = transcriptMessage("newest"); + const { rerender } = render( + , + ); + const wrappedLoadMore = sharedSentinelCalls.at(-1)?.[4] as () => Promise; + + await wrappedLoadMore(); + rerender( + , + ); + let options = sharedSentinelCalls.at(-1)?.[5] as { + shouldContinueWhileIntersecting: () => boolean; + }; + expect(options.shouldContinueWhileIntersecting()).toBe(true); + + await wrappedLoadMore(); + rerender( + , + ); + options = sharedSentinelCalls.at(-1)?.[5] as { + shouldContinueWhileIntersecting: () => boolean; + }; + expect(options.shouldContinueWhileIntersecting()).toBe(false); }); it("anchors a prepend below a fixed task description row", () => { diff --git a/apps/web/e2e/tests/chat/message-pagination-helpers.ts b/apps/web/e2e/tests/chat/message-pagination-helpers.ts index 810ab8c557..3c5687f85f 100644 --- a/apps/web/e2e/tests/chat/message-pagination-helpers.ts +++ b/apps/web/e2e/tests/chat/message-pagination-helpers.ts @@ -7,6 +7,8 @@ export const INITIAL_PROMPT_MARKER = "INITIAL-PROMPT-MARKER-7Q2X"; export const RECENT_AGENT_MARKER = "RECENT-AGENT-MARKER-4K8P"; export const PRE_PROMPT_MARKER = "HIDDEN-PRE-PROMPT-MARKER-6N3V"; export const EAGER_HISTORY_PROMPT_MARKER = "EAGER-HISTORY-PROMPT-MARKER-3J6W"; +export const VISIBLE_PAGE_MARKER = "VISIBLE-PAGE-MARKER-8D5H"; +export const SHORT_PAGE_BOUNDARY_MARKER = "SHORT-PAGE-BOUNDARY-MARKER-5T1C"; /** Seeds an older prompt followed by a tool-only newest window. */ export async function seedToolHeavyOpeningHistory( @@ -109,6 +111,65 @@ export async function seedCollapsedMessageHistory( return { taskId: task.id, sessionId }; } +/** Seeds several backend pages of standalone messages behind the newest window. */ +export async function seedVisibleMessageHistory( + apiClient: ApiClient, + seedData: SeedData, + title: string, +): Promise<{ taskId: string; sessionId: string }> { + const task = await apiClient.createTask(seedData.workspaceId, title, { + description: TASK_DESCRIPTION_MARKER, + workflow_id: seedData.workflowId, + workflow_step_id: seedData.startStepId, + repository_ids: [seedData.repositoryId], + }); + const { session_id: sessionId } = await apiClient.seedTaskSession(task.id, { + state: "IDLE", + repositoryId: seedData.repositoryId, + }); + await apiClient.seedSessionMessage(sessionId, { + type: "message", + content: INITIAL_PROMPT_MARKER, + authorType: "user", + }); + await apiClient.seedAgentMessages(sessionId, 140, VISIBLE_PAGE_MARKER); + return { taskId: task.id, sessionId }; +} + +/** Seeds a boundary-changing older page whose rendered height stays inside + * the sentinel's 200px preload margin: one short message plus one collapsed + * group containing the other 19 backend rows. */ +export async function seedShortBoundaryPageHistory( + apiClient: ApiClient, + seedData: SeedData, + title: string, +): Promise<{ taskId: string; sessionId: string }> { + const task = await apiClient.createTask(seedData.workspaceId, title, { + description: TASK_DESCRIPTION_MARKER, + workflow_id: seedData.workflowId, + workflow_step_id: seedData.startStepId, + repository_ids: [seedData.repositoryId], + }); + const { session_id: sessionId } = await apiClient.seedTaskSession(task.id, { + state: "IDLE", + repositoryId: seedData.repositoryId, + }); + await apiClient.seedAgentMessages(sessionId, 20, "SHORT-PAGE-OLDER-FILLER"); + await apiClient.seedSessionMessage(sessionId, { + type: "message", + content: SHORT_PAGE_BOUNDARY_MARKER, + }); + for (let index = 0; index < 19; index += 1) { + await apiClient.seedSessionMessage(sessionId, { + type: "tool_call", + content: `short-page completed tool ${index + 1}`, + metadata: { status: "complete" }, + }); + } + await apiClient.seedAgentMessages(sessionId, 100, VISIBLE_PAGE_MARKER); + return { taskId: task.id, sessionId }; +} + /** Reads a rendered standalone message's viewport position from the list. */ export async function readStandaloneMessageTop(list: Locator, marker: string): Promise { return list.evaluate((element, messageMarker) => { @@ -119,12 +180,22 @@ export async function readStandaloneMessageTop(list: Locator, marker: string): P }, marker); } +/** Reads one already-rendered message row by its stable DOM id. */ +export async function readMessageRowTopById(list: Locator, rowId: string): Promise { + return list.evaluate((element, id) => { + const row = Array.from(element.querySelectorAll("[id^='msg-']")).find( + (candidate) => candidate.id === id, + ); + return row?.getBoundingClientRect().top ?? Number.NaN; + }, rowId); +} + /** Scrolls the native transcript to the oldest loaded edge and captures the * anchored row's position before the next older-page request can prepend. */ export async function scrollToOldestLoadedEdge( list: Locator, marker: string, -): Promise<{ rowTop: number; scrollHeight: number }> { +): Promise<{ rowId: string | null; rowTop: number; scrollHeight: number }> { return list.evaluate((element, messageMarker) => { element.scrollTop = 0; element.dispatchEvent(new Event("scroll", { bubbles: true })); @@ -132,8 +203,19 @@ export async function scrollToOldestLoadedEdge( (candidate) => candidate.textContent?.includes(messageMarker), ); return { + rowId: row?.id ?? null, rowTop: row?.getBoundingClientRect().top ?? Number.NaN, scrollHeight: element.scrollHeight, }; }, marker); } + +/** Applies a small upward movement after prepend restoration. */ +export async function scrollUpSlightly(list: Locator): Promise { + return list.evaluate((element) => { + const previous = element.scrollTop; + element.scrollTop = Math.max(0, previous - 24); + element.dispatchEvent(new Event("scroll", { bubbles: true })); + return previous - element.scrollTop; + }); +} diff --git a/apps/web/e2e/tests/chat/message-pagination.spec.ts b/apps/web/e2e/tests/chat/message-pagination.spec.ts index 5f12767d84..2bb220c1ae 100644 --- a/apps/web/e2e/tests/chat/message-pagination.spec.ts +++ b/apps/web/e2e/tests/chat/message-pagination.spec.ts @@ -8,11 +8,17 @@ import { INITIAL_PROMPT_MARKER, PRE_PROMPT_MARKER, RECENT_AGENT_MARKER, + SHORT_PAGE_BOUNDARY_MARKER, TASK_DESCRIPTION_MARKER, + VISIBLE_PAGE_MARKER, + readMessageRowTopById, readStandaloneMessageTop, seedCollapsedMessageHistory, + seedShortBoundaryPageHistory, seedToolHeavyOpeningHistory, + seedVisibleMessageHistory, scrollToOldestLoadedEdge, + scrollUpSlightly, watchOlderMessageRequests, } from "./message-pagination-helpers"; @@ -43,6 +49,76 @@ test.describe("@chat message pagination", () => { expect(olderRequests).toHaveLength(0); }); + test("loads one visible page per upward reach without cascading", async ({ + testPage, + apiClient, + seedData, + }) => { + test.setTimeout(180_000); + + const { taskId, sessionId } = await seedVisibleMessageHistory( + apiClient, + seedData, + "message-pagination-does-not-cascade", + ); + const olderRequests = watchOlderMessageRequests(testPage, sessionId); + + await testPage.goto(`/t/${taskId}`); + const session = new SessionPage(testPage); + await session.waitForLoad(); + await session.waitForChatIdle({ timeout: 30_000 }); + const list = session.activeChat().locator(".chat-message-list"); + const edge = await scrollToOldestLoadedEdge(list, VISIBLE_PAGE_MARKER); + expect(edge.rowId).not.toBeNull(); + expect(Number.isFinite(edge.rowTop)).toBe(true); + + await expect + .poll( + async () => + olderRequests.length === 1 && + (await list.evaluate((element) => element.scrollHeight)) > edge.scrollHeight, + { timeout: 15_000, intervals: [100], message: "One older visible page loaded" }, + ) + .toBe(true); + const afterLoadTop = await readMessageRowTopById(list, edge.rowId!); + expect(Math.abs(afterLoadTop - edge.rowTop)).toBeLessThanOrEqual(8); + await dwell(testPage, 750, "negative-assertion", "observe visible-page pagination cascade"); + expect(olderRequests).toHaveLength(1); + }); + + test("retries a short boundary page on the next upward movement", async ({ + testPage, + apiClient, + seedData, + }) => { + test.setTimeout(180_000); + const { taskId, sessionId } = await seedShortBoundaryPageHistory( + apiClient, + seedData, + "message-pagination-retries-short-page", + ); + const olderRequests = watchOlderMessageRequests(testPage, sessionId); + + await testPage.goto(`/t/${taskId}`); + const session = new SessionPage(testPage); + await session.waitForLoad(); + await session.waitForChatIdle({ timeout: 30_000 }); + const chat = session.activeChat(); + const list = chat.locator(".chat-message-list"); + const edge = await scrollToOldestLoadedEdge(list, VISIBLE_PAGE_MARKER); + + await expect(chat.getByText(SHORT_PAGE_BOUNDARY_MARKER, { exact: true })).toBeVisible(); + await expect.poll(() => olderRequests.length).toBe(1); + const heightAfterShortPage = await list.evaluate((element) => element.scrollHeight); + expect(heightAfterShortPage - edge.scrollHeight).toBeGreaterThan(0); + expect(heightAfterShortPage - edge.scrollHeight).toBeLessThan(200); + await dwell(testPage, 500, "negative-assertion", "observe short-page pagination stop"); + expect(olderRequests).toHaveLength(1); + + expect(await scrollUpSlightly(list)).toBeGreaterThan(0); + await expect.poll(() => olderRequests.length, { timeout: 15_000 }).toBe(2); + }); + test("hides the older control when only hidden pre-prompt rows remain", async ({ testPage, apiClient, @@ -81,12 +157,13 @@ test.describe("@chat message pagination", () => { }) => { test.setTimeout(180_000); - const { taskId } = await seedCollapsedMessageHistory( + const { taskId, sessionId } = await seedCollapsedMessageHistory( apiClient, seedData, "message-pagination-preserves-prepend-anchor", { promptOutsideInitialWindow: true }, ); + const olderRequests = watchOlderMessageRequests(testPage, sessionId); await testPage.goto(`/t/${taskId}`); const session = new SessionPage(testPage); @@ -98,27 +175,15 @@ test.describe("@chat message pagination", () => { await expect(chat.getByText(TASK_DESCRIPTION_MARKER, { exact: true })).toBeVisible(); await expect(chat.getByText(INITIAL_PROMPT_MARKER, { exact: true })).toHaveCount(0); - for (let attempt = 0; attempt < 10; attempt += 1) { - const edge = await scrollToOldestLoadedEdge(list, RECENT_AGENT_MARKER); - expect(Number.isFinite(edge.rowTop)).toBe(true); + const edge = await scrollToOldestLoadedEdge(list, RECENT_AGENT_MARKER); + expect(Number.isFinite(edge.rowTop)).toBe(true); + await expect(chat.getByText(INITIAL_PROMPT_MARKER, { exact: true })).toBeVisible({ + timeout: 15_000, + }); - await expect - .poll( - async () => - (await chat.getByText(INITIAL_PROMPT_MARKER, { exact: true }).count()) === 1 || - (await list.evaluate((element) => element.scrollHeight)) > edge.scrollHeight, - { - timeout: 15_000, - intervals: [300], - message: "Loading older pages until initial prompt", - }, - ) - .toBe(true); - - const afterLoadTop = await readStandaloneMessageTop(list, RECENT_AGENT_MARKER); - expect(Math.abs(afterLoadTop - edge.rowTop)).toBeLessThanOrEqual(8); - if ((await chat.getByText(INITIAL_PROMPT_MARKER, { exact: true }).count()) === 1) break; - } + const afterLoadTop = await readStandaloneMessageTop(list, RECENT_AGENT_MARKER); + expect(Math.abs(afterLoadTop - edge.rowTop)).toBeLessThanOrEqual(8); + expect(olderRequests.length).toBeGreaterThan(1); await expect(chat.getByText(INITIAL_PROMPT_MARKER, { exact: true })).toBeVisible(); await expect(chat.getByText(TASK_DESCRIPTION_MARKER, { exact: true })).toHaveCount(0); diff --git a/apps/web/e2e/tests/chat/mobile-message-pagination.spec.ts b/apps/web/e2e/tests/chat/mobile-message-pagination.spec.ts index 52a9fa33c2..d073e32140 100644 --- a/apps/web/e2e/tests/chat/mobile-message-pagination.spec.ts +++ b/apps/web/e2e/tests/chat/mobile-message-pagination.spec.ts @@ -6,11 +6,17 @@ import { INITIAL_PROMPT_MARKER, PRE_PROMPT_MARKER, RECENT_AGENT_MARKER, + SHORT_PAGE_BOUNDARY_MARKER, TASK_DESCRIPTION_MARKER, + VISIBLE_PAGE_MARKER, + readMessageRowTopById, readStandaloneMessageTop, seedCollapsedMessageHistory, + seedShortBoundaryPageHistory, seedToolHeavyOpeningHistory, + seedVisibleMessageHistory, scrollToOldestLoadedEdge, + scrollUpSlightly, watchOlderMessageRequests, } from "./message-pagination-helpers"; @@ -41,6 +47,73 @@ test.describe("Mobile chat message pagination", () => { expect(olderRequests).toHaveLength(0); }); + test("loads one visible page per upward reach without cascading", async ({ + testPage, + apiClient, + seedData, + }) => { + const { taskId, sessionId } = await seedVisibleMessageHistory( + apiClient, + seedData, + "mobile-message-pagination-does-not-cascade", + ); + const olderRequests = watchOlderMessageRequests(testPage, sessionId); + + await testPage.goto(`/t/${taskId}`); + const session = new SessionPage(testPage); + await session.waitForLoad(); + await session.waitForChatIdle({ timeout: 30_000 }); + const list = session.activeChat().locator(".chat-message-list"); + const edge = await scrollToOldestLoadedEdge(list, VISIBLE_PAGE_MARKER); + expect(edge.rowId).not.toBeNull(); + expect(Number.isFinite(edge.rowTop)).toBe(true); + + await expect + .poll( + async () => + olderRequests.length === 1 && + (await list.evaluate((element) => element.scrollHeight)) > edge.scrollHeight, + { timeout: 15_000, intervals: [100], message: "One older mobile page loaded" }, + ) + .toBe(true); + const afterLoadTop = await readMessageRowTopById(list, edge.rowId!); + expect(Math.abs(afterLoadTop - edge.rowTop)).toBeLessThanOrEqual(8); + await dwell(testPage, 750, "negative-assertion", "observe mobile pagination cascade"); + expect(olderRequests).toHaveLength(1); + }); + + test("retries a short boundary page on the next upward movement", async ({ + testPage, + apiClient, + seedData, + }) => { + const { taskId, sessionId } = await seedShortBoundaryPageHistory( + apiClient, + seedData, + "mobile-message-pagination-retries-short-page", + ); + const olderRequests = watchOlderMessageRequests(testPage, sessionId); + + await testPage.goto(`/t/${taskId}`); + const session = new SessionPage(testPage); + await session.waitForLoad(); + await session.waitForChatIdle({ timeout: 30_000 }); + const chat = session.activeChat(); + const list = chat.locator(".chat-message-list"); + const edge = await scrollToOldestLoadedEdge(list, VISIBLE_PAGE_MARKER); + + await expect(chat.getByText(SHORT_PAGE_BOUNDARY_MARKER, { exact: true })).toBeVisible(); + await expect.poll(() => olderRequests.length).toBe(1); + const heightAfterShortPage = await list.evaluate((element) => element.scrollHeight); + expect(heightAfterShortPage - edge.scrollHeight).toBeGreaterThan(0); + expect(heightAfterShortPage - edge.scrollHeight).toBeLessThan(200); + await dwell(testPage, 500, "negative-assertion", "observe mobile short-page stop"); + expect(olderRequests).toHaveLength(1); + + expect(await scrollUpSlightly(list)).toBeGreaterThan(0); + await expect.poll(() => olderRequests.length, { timeout: 15_000 }).toBe(2); + }); + test("hides the older control when only hidden pre-prompt rows remain", async ({ testPage, apiClient, @@ -75,12 +148,13 @@ test.describe("Mobile chat message pagination", () => { apiClient, seedData, }) => { - const { taskId } = await seedCollapsedMessageHistory( + const { taskId, sessionId } = await seedCollapsedMessageHistory( apiClient, seedData, "mobile-message-pagination-preserves-prepend-anchor", { promptOutsideInitialWindow: true }, ); + const olderRequests = watchOlderMessageRequests(testPage, sessionId); await testPage.goto(`/t/${taskId}`); const session = new SessionPage(testPage); @@ -92,27 +166,15 @@ test.describe("Mobile chat message pagination", () => { await expect(chat.getByText(TASK_DESCRIPTION_MARKER, { exact: true })).toBeVisible(); await expect(chat.getByText(INITIAL_PROMPT_MARKER, { exact: true })).toHaveCount(0); - for (let attempt = 0; attempt < 10; attempt += 1) { - const edge = await scrollToOldestLoadedEdge(list, RECENT_AGENT_MARKER); - expect(Number.isFinite(edge.rowTop)).toBe(true); + const edge = await scrollToOldestLoadedEdge(list, RECENT_AGENT_MARKER); + expect(Number.isFinite(edge.rowTop)).toBe(true); + await expect(chat.getByText(INITIAL_PROMPT_MARKER, { exact: true })).toBeVisible({ + timeout: 15_000, + }); - await expect - .poll( - async () => - (await chat.getByText(INITIAL_PROMPT_MARKER, { exact: true }).count()) === 1 || - (await list.evaluate((element) => element.scrollHeight)) > edge.scrollHeight, - { - timeout: 15_000, - intervals: [300], - message: "Loading mobile history until initial prompt", - }, - ) - .toBe(true); - - const afterLoadTop = await readStandaloneMessageTop(list, RECENT_AGENT_MARKER); - expect(Math.abs(afterLoadTop - edge.rowTop)).toBeLessThanOrEqual(8); - if ((await chat.getByText(INITIAL_PROMPT_MARKER, { exact: true }).count()) === 1) break; - } + const afterLoadTop = await readStandaloneMessageTop(list, RECENT_AGENT_MARKER); + expect(Math.abs(afterLoadTop - edge.rowTop)).toBeLessThanOrEqual(8); + expect(olderRequests.length).toBeGreaterThan(1); await expect(chat.getByText(INITIAL_PROMPT_MARKER, { exact: true })).toBeVisible(); await expect(chat.getByText(TASK_DESCRIPTION_MARKER, { exact: true })).toHaveCount(0); diff --git a/apps/web/hooks/use-lazy-load-sentinel.test.ts b/apps/web/hooks/use-lazy-load-sentinel.test.ts index e8f26b5ed8..a2618d171e 100644 --- a/apps/web/hooks/use-lazy-load-sentinel.test.ts +++ b/apps/web/hooks/use-lazy-load-sentinel.test.ts @@ -1,3 +1,4 @@ +/* eslint-disable max-lines -- sentinel state-machine regressions share one observer harness. */ import { act, cleanup, renderHook, waitFor } from "@testing-library/react"; import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; import { useLazyLoadSentinel } from "./use-lazy-load-sentinel"; @@ -260,6 +261,69 @@ describe("useLazyLoadSentinel — re-arm, disarm, and stale completions", () => // a second IntersectionObserver entry. expect(loadMore).toHaveBeenCalledTimes(2); }); + + it("stops a still-intersecting continuation when the caller reports a new visible boundary", async () => { + const scrollRef = makeScrollRef(); + const loadMore = vi.fn().mockResolvedValueOnce(20).mockResolvedValueOnce(0); + const shouldContinueWhileIntersecting = vi.fn(() => false); + const { result } = renderHook(() => + useLazyLoadSentinel(scrollRef, true, false, false, loadMore, { + rearmWhileIntersecting: true, + shouldContinueWhileIntersecting, + }), + ); + const node = document.createElement("div"); + act(() => result.current.sentinelRef(node)); + + fire(records[0], true, node); + await waitFor(() => expect(shouldContinueWhileIntersecting).toHaveBeenCalledTimes(1)); + expect(loadMore).toHaveBeenCalledTimes(1); + + // A stale true entry cannot restart the stopped cycle. The sentinel must + // leave the preload region before a later user reach can start a new one. + fire(records[0], true, node); + await act(async () => {}); + expect(loadMore).toHaveBeenCalledTimes(1); + fire(records[0], false, node); + fire(records[0], true, node); + await waitFor(() => expect(loadMore).toHaveBeenCalledTimes(2)); + }); + + it("reports the actual continuation outcome after all firing guards", async () => { + const scrollRef = makeScrollRef(); + const onLoadSettled = vi.fn(); + const shouldContinueWhileIntersecting = vi.fn(() => true); + let resolveLoad: (value: number) => void = () => {}; + const loadMore = vi.fn( + () => + new Promise((resolve) => { + resolveLoad = resolve; + }), + ); + const { result } = renderHook(() => + useLazyLoadSentinel(scrollRef, true, false, false, loadMore, { + rearmWhileIntersecting: true, + shouldContinueWhileIntersecting, + onLoadSettled, + }), + ); + const node = document.createElement("div"); + act(() => result.current.sentinelRef(node)); + + fire(records[0], true, node); + fire(records[0], false, node); + await act(async () => resolveLoad(20)); + + await waitFor(() => + expect(onLoadSettled).toHaveBeenCalledWith({ + count: 20, + rejected: false, + continuation: "sentinel-left-preload", + }), + ); + expect(loadMore).toHaveBeenCalledTimes(1); + expect(shouldContinueWhileIntersecting).not.toHaveBeenCalled(); + }); }); describe("useLazyLoadSentinel — stickToBottomWhileLoading", () => { @@ -631,6 +695,36 @@ describe("useLazyLoadSentinel — stale observers", () => { }); describe("useLazyLoadSentinel — stale completions", () => { + it("reports a stale settle when a request completes after unmount", async () => { + const scrollRef = makeScrollRef(); + const onLoadSettled = vi.fn(); + let resolveLoad: (value: number) => void = () => {}; + const loadMore = vi.fn( + () => + new Promise((resolve) => { + resolveLoad = resolve; + }), + ); + const { result, unmount } = renderHook(() => + useLazyLoadSentinel(scrollRef, true, false, false, loadMore, { + rearmWhileIntersecting: true, + onLoadSettled, + }), + ); + const node = document.createElement("div"); + act(() => result.current.sentinelRef(node)); + + fire(records[0], true, node); + unmount(); + await act(async () => resolveLoad(20)); + + expect(onLoadSettled).toHaveBeenCalledWith({ + count: 20, + rejected: false, + continuation: "stale", + }); + }); + it("ignores a stale positive completion after unmount (no re-arm)", async () => { const scrollRef = makeScrollRef(); let resolveLoad: (value: number) => void = () => {}; diff --git a/apps/web/hooks/use-lazy-load-sentinel.ts b/apps/web/hooks/use-lazy-load-sentinel.ts index 95c53061dd..0f1a731ecf 100644 --- a/apps/web/hooks/use-lazy-load-sentinel.ts +++ b/apps/web/hooks/use-lazy-load-sentinel.ts @@ -8,6 +8,15 @@ export type LazyLoadSentinelOptions = { * sentinel so the next page auto-loads without a scroll-away/scroll-back. * Defaults to false (the transcript's no-automatic-re-arm behavior). */ rearmWhileIntersecting?: boolean; + /** Called after a positive page commits, before a still-intersecting + * sentinel starts another page. Return false to stop and require an + * observed exit/re-entry or a later user-gesture retry. Defaults to true + * when re-arm is enabled. */ + shouldContinueWhileIntersecting?: () => boolean; + /** Reports one terminal outcome for each request that started. The + * continuation value reflects the final firing guards, not only the + * caller's boundary decision. */ + onLoadSettled?: (result: LazyLoadSentinelSettleResult) => void; /** Fire (and join) even while an older-page request is in flight. Never * bypasses `blocked`. Defaults to false. */ joinInFlightWhileLoading?: boolean; @@ -20,6 +29,24 @@ export type LazyLoadSentinelOptions = { stickToBottomWhileLoading?: boolean; }; +export type LazyLoadSentinelContinuation = + | "continued" + | "caller-stopped" + | "sentinel-left-preload" + | "disarmed" + | "no-more" + | "blocked" + | "stale" + | "not-rearmed" + | "no-progress" + | "rejected"; + +export type LazyLoadSentinelSettleResult = { + count: number; + rejected: boolean; + continuation: LazyLoadSentinelContinuation; +}; + /** How close to the scroll container's bottom counts as "pinned". */ const STICK_BOTTOM_TOLERANCE_PX = 24; @@ -34,6 +61,8 @@ type SentinelMutableRefs = { rearmWhileIntersecting: boolean; joinInFlightWhileLoading: boolean; stickToBottomWhileLoading: boolean; + shouldContinueWhileIntersecting?: () => boolean; + onLoadSettled?: (result: LazyLoadSentinelSettleResult) => void; }>; observerRef: React.MutableRefObject; sentinelNodeRef: React.MutableRefObject; @@ -43,7 +72,8 @@ type SentinelMutableRefs = { fireLoadRef: React.MutableRefObject<(() => void) | null>; loadInFlightRef: React.MutableRefObject; continuationScheduledRef: React.MutableRefObject; - continuationTimerRef: React.MutableRefObject | null>; + continuationFrameRef: React.MutableRefObject; + pendingContinuationSettleRef: React.MutableRefObject<(() => void) | null>; }; /** Creates and destroys the IntersectionObserver over the scroll container. @@ -134,14 +164,24 @@ function useSentinelSettle(opts: { node: HTMLDivElement, observer: IntersectionObserver, outcome: { count: number; rejected: boolean }, + onLoadSettled: ((result: LazyLoadSentinelSettleResult) => void) | undefined, ) => { - if (!opts.refs.mountedRef.current || opts.refs.observerRef.current !== observer) return; - if (node !== opts.refs.sentinelNodeRef.current) return; + const notify = (continuation: LazyLoadSentinelContinuation) => { + onLoadSettled?.({ ...outcome, continuation }); + }; + if ( + !opts.refs.mountedRef.current || + opts.refs.observerRef.current !== observer || + node !== opts.refs.sentinelNodeRef.current + ) { + notify("stale"); + return; + } if (outcome.count > 0 && !outcome.rejected) { - // Positive progress: re-arm and re-observe (re-arm only when enabled; - // the transcript leaves observation untouched). A gesture retry that - // succeeded while disarmed must arm again so the next page can load - // without another gesture. + // Positive progress: re-arm and re-observe when enabled. A caller can + // stop the deferred continuation after committed content is visible. + // A gesture retry that succeeded while disarmed must arm again so the + // next eligible page can load without another gesture. opts.refs.disarmedRef.current = false; if (opts.refs.optionsRef.current.rearmWhileIntersecting) { opts.refs.observerRef.current.observe(node); @@ -152,26 +192,53 @@ function useSentinelSettle(opts: { // still in the preload region. if (!opts.refs.continuationScheduledRef.current) { opts.refs.continuationScheduledRef.current = true; - opts.refs.continuationTimerRef.current = setTimeout(() => { - opts.refs.continuationTimerRef.current = null; + opts.refs.pendingContinuationSettleRef.current = () => notify("stale"); + opts.refs.continuationFrameRef.current = requestAnimationFrame(() => { + opts.refs.pendingContinuationSettleRef.current = null; + opts.refs.continuationFrameRef.current = null; opts.refs.continuationScheduledRef.current = false; if ( !opts.refs.mountedRef.current || opts.refs.observerRef.current !== observer || - opts.refs.sentinelNodeRef.current !== node || - !opts.refs.intersectingRef.current || - opts.refs.disarmedRef.current + opts.refs.sentinelNodeRef.current !== node ) { + notify("stale"); + return; + } + if (!opts.refs.intersectingRef.current) { + notify("sentinel-left-preload"); + return; + } + if (opts.refs.disarmedRef.current) { + notify("disarmed"); return; } const { hasMore, blocked } = opts.refs.stateRef.current; - if (!hasMore || blocked) return; + if (!hasMore) { + notify("no-more"); + return; + } + if (blocked) { + notify("blocked"); + return; + } + const shouldContinue = + opts.refs.optionsRef.current.shouldContinueWhileIntersecting?.() ?? true; + if (!shouldContinue) { + // The loaded page added a visible boundary. A stale true + // intersection must not chain another page; wait for fresh + // upward movement or an observed exit/re-entry. + opts.refs.disarmedRef.current = true; + notify("caller-stopped"); + return; + } // The just-completed request owns this re-arm. `loadMore` still // applies its own cursor/in-flight guard, so do not reject this // hand-off on a stale loading render from the request that has // already settled. + notify("continued"); opts.refs.fireLoadRef.current?.(); - }, 0); + }); } } // Appended rows push the sentinel below the viewport while the user @@ -184,6 +251,7 @@ function useSentinelSettle(opts: { ) { opts.scrollRef.current.scrollTop = opts.scrollRef.current.scrollHeight; } + if (!opts.refs.optionsRef.current.rearmWhileIntersecting) notify("not-rearmed"); return; } // Rejected or zero-result load: re-observe disarmed. The current @@ -193,6 +261,7 @@ function useSentinelSettle(opts: { if (opts.refs.optionsRef.current.rearmWhileIntersecting) { opts.refs.observerRef.current.observe(node); } + notify(outcome.rejected ? "rejected" : "no-progress"); }, [opts.isPinned, opts.scrollRef], ); @@ -330,6 +399,8 @@ export function useLazyLoadSentinel( rearmWhileIntersecting = false, joinInFlightWhileLoading = false, stickToBottomWhileLoading = false, + shouldContinueWhileIntersecting, + onLoadSettled, } = options ?? {}; const stateRef = useRef({ hasMore, blocked, isLoadingMore }); @@ -340,14 +411,24 @@ export function useLazyLoadSentinel( rearmWhileIntersecting, joinInFlightWhileLoading, stickToBottomWhileLoading, + shouldContinueWhileIntersecting, + onLoadSettled, }); useEffect(() => { optionsRef.current = { rearmWhileIntersecting, joinInFlightWhileLoading, stickToBottomWhileLoading, + shouldContinueWhileIntersecting, + onLoadSettled, }; - }, [rearmWhileIntersecting, joinInFlightWhileLoading, stickToBottomWhileLoading]); + }, [ + rearmWhileIntersecting, + joinInFlightWhileLoading, + stickToBottomWhileLoading, + shouldContinueWhileIntersecting, + onLoadSettled, + ]); const observerRef = useRef(null); const sentinelNodeRef = useRef(null); @@ -355,7 +436,8 @@ export function useLazyLoadSentinel( const fireLoadRef = useRef<(() => void) | null>(null); const loadInFlightRef = useRef(false); const continuationScheduledRef = useRef(false); - const continuationTimerRef = useRef | null>(null); + const continuationFrameRef = useRef(null); + const pendingContinuationSettleRef = useRef<(() => void) | null>(null); /** When true, ignore intersections until an observed exit arms the hook. */ const disarmedRef = useRef(false); const intersectingRef = useRef(false); @@ -365,10 +447,12 @@ export function useLazyLoadSentinel( mountedRef.current = true; return () => { mountedRef.current = false; - if (continuationTimerRef.current !== null) { - clearTimeout(continuationTimerRef.current); - continuationTimerRef.current = null; + if (continuationFrameRef.current !== null) { + cancelAnimationFrame(continuationFrameRef.current); + continuationFrameRef.current = null; } + pendingContinuationSettleRef.current?.(); + pendingContinuationSettleRef.current = null; continuationScheduledRef.current = false; }; }, []); @@ -384,7 +468,8 @@ export function useLazyLoadSentinel( fireLoadRef, loadInFlightRef, continuationScheduledRef, - continuationTimerRef, + continuationFrameRef, + pendingContinuationSettleRef, }; const settleLoad = useSentinelSettle({ scrollRef, isPinned, refs }); @@ -408,12 +493,13 @@ export function useLazyLoadSentinel( } let count = 0; let rejected = false; + const onLoadSettled = optionsRef.current.onLoadSettled; try { count = await loadMore(); } catch { rejected = true; } finally { - settleLoad(node, observer, { count, rejected }); + settleLoad(node, observer, { count, rejected }, onLoadSettled); loadInFlightRef.current = false; } }, [loadMore, refreshPinned, settleLoad]); diff --git a/apps/web/lib/debug/log.ts b/apps/web/lib/debug/log.ts index a6e4cd6b4e..976c8839c5 100644 --- a/apps/web/lib/debug/log.ts +++ b/apps/web/lib/debug/log.ts @@ -197,7 +197,8 @@ * Other * [ws:connection] WS hook mount + status transitions * [dockview:*] layout restore / save / env-switch / session-tabs / task-select - * [messages:*] message fetch / process / lazyload + * [messages:*] message fetch / process / lazyload / pagination + * [messages:pagination] older-page trigger, visible boundary, and scroll geometry * [session:env-mapping] session → environment ID mapping * * Tip: in Chrome devtools the console filter input takes substrings and regex. diff --git a/docs/plans/chat-scroll-pagination-flicker/plan.md b/docs/plans/chat-scroll-pagination-flicker/plan.md new file mode 100644 index 0000000000..c241f77b18 --- /dev/null +++ b/docs/plans/chat-scroll-pagination-flicker/plan.md @@ -0,0 +1,136 @@ +--- +created: 2026-08-26 +status: done +requirements: + - REQ-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001 +system_design: + - ../../specs/ui/system-design/task-prompt-transcript-visibility.md +legacy_specs: [] +--- + +# Implementation Plan: Stop Chat Scroll Pagination Flicker + +## Overview + +The transcript will limit each upward load cycle to the current visible top boundary. + +One upward action can skip tool-only pages that do not add a visible entry. The cycle stops when a page adds a visible entry. + +## Scope + +### In scope + +- Require an upward transcript action before automatic older-page loading starts. +- Stop a load cycle after a page changes the visible top-boundary key. +- Continue the same cycle when a page only extends one collapsed activity group. +- Preserve the current reading position after each prepend. +- Add debug events for the trigger, geometry, boundary change, and stop reason. +- Add desktop and mobile browser evidence for request count and scroll geometry. + +### Out of scope + +- Backend pagination queries, cursors, page size, persistence, or API fields. +- Transcript virtualization or changes to message grouping. +- Removal of the explicit older-page recovery control. +- Changes to the prompt `#1` visible-start boundary. +- Loading the complete transcript before an upward user action. + +## Confirmed root cause + +The native transcript enables `rearmWhileIntersecting` in `message-list-native-scroll.ts`. + +After each positive request, `use-lazy-load-sentinel.ts` schedules a continuation from `intersectingRef`. This value can describe the intersection before the prepend. + +The continuation does not wait for the committed visible boundary. It can start another request after a page adds visible rows and moves the sentinel away. + +A temporary Chromium test seeded 180 visible agent messages behind the newest window. One `scrollTop = 0` action caused five requests in 277 ms. + +The probe recorded these changes: + +- `scrollHeight`: 5,864 px to 10,434 px. +- `scrollTop`: 0 px to 1,143 px, 2,286 px, 3,429 px, and 4,572 px. +- Older-page request count: 5. The expected count was 1. + +The repeated range growth and scroll restoration produced the shrinking scrollbar and visible flicker. The temporary test and browser probe were removed after diagnosis. + +## Technical approach + +### Transcript load-cycle state + +- Record the oldest standalone message key for each older-page request. +- Continue automatically while tool pages leave that visible boundary unchanged. +- Disarm the observer when a page adds a new visible top entry. +- Re-arm from an observed sentinel exit/re-entry or a later actual upward scroll. This covers short pages that remain inside the 200 px preload margin. +- Keep the request generation as a diagnostic correlation label only. It does not control pagination. +- Do not treat prepend restoration or guarded programmatic scroll changes as new user intent. + +### Sentinel continuation + +- Update `use-lazy-load-sentinel.ts` to use a caller-supplied continuation decision. +- Make the decision after the prepended React state commits. +- Do not use a stale `intersectingRef` value as sufficient continuation evidence. +- Keep Prompt History pinned-bottom behavior unchanged. +- Keep request serialization, failure disarm, and explicit retry behavior unchanged. + +### Diagnostics + +- Add `messages:pagination` to the namespace list in `lib/debug/log.ts`. +- Emit one start event and one settle event for each transcript older-page request. +- Include primitive fields for session, trigger, boundary keys, request count, geometry, and stop reason. +- Do not log message content or every scroll event. + +### Browser regression + +- Add a shared seed with several older pages of visible agent messages. +- Record older-page requests after the watcher starts. +- Perform one upward action and wait for the first request to settle. +- Prove that no second request occurs when the page adds visible entries. +- Prove that the anchor row remains within the existing 8 px tolerance. +- Add a collapsed-tool scenario that continues until one new visible entry appears. + +## Tests + +| Acceptance criterion | Test evidence | +| --- | --- | +| `AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.4` | Sentinel and native-scroll unit tests require upward intent at the oldest boundary. | +| `AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.5` | A browser scenario continues through collapsed tool-only pages. | +| `AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.6` | The collapsed scenario reaches the next visible entry without another action. | +| `AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.8` | Desktop and mobile tests prove that one action does not cascade visible pages. | +| `AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.9` | Existing prompt `#1` boundary tests remain green. | + +## E2E tests + +- Desktop: `apps/web/e2e/tests/chat/message-pagination.spec.ts` in the `chromium` project. +- Mobile: `apps/web/e2e/tests/chat/mobile-message-pagination.spec.ts` in the `mobile-chrome` project. +- Shared cues: request count, `scrollTop`, `scrollHeight`, the oldest visible row, and the anchor-row position. + +## Mobile design contract + +- Desktop outcome: one upward boundary action loads only the required older pages. +- Mobile entry point: the existing Chat tab in the full-height task layout. +- Nearest exemplar: `apps/web/components/task/task-layout.tsx` and the current mobile pagination test. +- Hierarchy and surface: the transcript remains the only vertical scroll owner. +- Shared logic: desktop and mobile use one pagination cycle, sentinel, store, and cursor coordinator. +- Mobile proof: the mobile test uses the same visible-page and collapsed-tool scenarios. + +## Work orders + +- [x] [Task 01: Constrain transcript pagination cycles](task-01-constrain-transcript-pagination-cycles.md) + +## Verification results + +- Red evidence: the new desktop cascade test timed out because one top-edge action issued more than one older-page request on the previous implementation. +- Unit tests: 43 passed across the shared sentinel and native transcript scroll suites. +- TypeScript typecheck: passed. +- Targeted ESLint: passed with no warnings. +- Specification lint: passed. +- Desktop Chromium E2E: 4 passed, including one-request visible pagination and automatic collapsed-tool continuation. +- Mobile Chrome E2E: 4 passed with the same pagination and anchor contract. + +## Risks + +- A continuation decision that runs before React commits can read the old boundary key. +- Loading-state rows can change scroll geometry without adding transcript content. +- Gesture tracking must not treat scroll restoration as user intent. +- The shared sentinel also serves Prompt History. Transcript rules must not change its pinned-bottom behavior. +- Touch, keyboard, wheel, and scrollbar navigation must produce the same boundary result. diff --git a/docs/plans/chat-scroll-pagination-flicker/task-01-constrain-transcript-pagination-cycles.md b/docs/plans/chat-scroll-pagination-flicker/task-01-constrain-transcript-pagination-cycles.md new file mode 100644 index 0000000000..b4f7e2482b --- /dev/null +++ b/docs/plans/chat-scroll-pagination-flicker/task-01-constrain-transcript-pagination-cycles.md @@ -0,0 +1,98 @@ +--- +id: "01-constrain-transcript-pagination-cycles" +title: "Constrain transcript pagination cycles" +status: done +wave: 1 +depends_on: [] +plan: "plan.md" +requirements: + - REQ-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001 +acceptance_criteria: + - AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.4 + - AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.5 + - AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.6 + - AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.8 + - AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.9 +system_design: + - ../../specs/ui/system-design/task-prompt-transcript-visibility.md +--- + +# Task 01: Constrain Transcript Pagination Cycles + +## Summary + +Limit one upward transcript action to its visible top boundary. Keep automatic continuation only for pages that do not add a visible entry. + +Add bounded debug events and browser geometry cues. These events make a future pagination cascade visible without message content. + +## In scope + +- Add a failing unit regression for stale-intersection continuation. +- Add failing desktop and mobile regressions for one-action request count. +- Track upward intent and the oldest non-synthetic render-item key. +- Continue through collapsed activity without a second action. +- Preserve the existing prepend anchor tolerance. +- Emit bounded `messages:pagination` debug events. + +## Out of scope + +- Backend, API, database, page-size, and cursor changes. +- Transcript virtualization or message-grouping changes. +- Prompt History behavior changes. +- New user-facing copy or controls. + +## Acceptance + +- One upward action starts one request when the page adds visible transcript entries. +- The same action can cross tool-only pages until one new visible entry appears. +- Desktop and mobile preserve the anchor row and do not load older history on task open. + +## Verification + +```bash +cd apps && pnpm --filter @kandev/web test -- hooks/use-lazy-load-sentinel.test.ts components/task/chat/message-list-native.test.tsx +cd apps && pnpm --filter @kandev/web run typecheck +cd apps/web && pnpm exec eslint hooks/use-lazy-load-sentinel.ts hooks/use-lazy-load-sentinel.test.ts components/task/chat/message-list-native-scroll.ts components/task/chat/message-list-native.test.tsx e2e/tests/chat/message-pagination-helpers.ts e2e/tests/chat/message-pagination.spec.ts e2e/tests/chat/mobile-message-pagination.spec.ts +cd apps/web && pnpm e2e:run --host --project chromium tests/chat/message-pagination.spec.ts -- --retries=0 +cd apps/web && pnpm e2e:run --host --no-build --project mobile-chrome tests/chat/mobile-message-pagination.spec.ts -- --retries=0 +``` + +## Files likely touched + +- `apps/web/hooks/use-lazy-load-sentinel.ts` +- `apps/web/hooks/use-lazy-load-sentinel.test.ts` +- `apps/web/components/task/chat/message-list-native-scroll.ts` +- `apps/web/components/task/chat/message-list-native.test.tsx` +- `apps/web/lib/debug/log.ts` +- `apps/web/e2e/tests/chat/message-pagination-helpers.ts` +- `apps/web/e2e/tests/chat/message-pagination.spec.ts` +- `apps/web/e2e/tests/chat/mobile-message-pagination.spec.ts` + +## Dependencies + +None. + +## Risks + +- React commit timing can make a boundary comparison stale. +- A loading indicator can change geometry without changing the boundary. +- Shared sentinel changes can affect Prompt History. + +## Parallelism + +`sequential` + +## Inputs + +- `REQ-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001` acceptance criteria 4, 5, 6, 8, and 9. +- The upward load-cycle and observability sections in the system design. +- Existing native-scroll, sentinel, desktop, and mobile pagination tests. + +## Results + +- Added a post-commit continuation decision to the shared sentinel. A false decision disarms stale intersection state until the sentinel exits and re-enters the preload region. +- The native transcript now compares the oldest standalone message across a request. It continues through tool-only pages, but stops when a new standalone entry appears or history is exhausted. +- A later actual upward scroll now retries a disarmed sentinel that remains inside the 200 px preload margin. The scroll owner covers wheel, keyboard, scrollbar, and touch movement while excluding guarded programmatic scrolls. +- Added bounded `messages:pagination` start and settle events with request generation, boundary keys, scroll geometry, loaded count, actual continuation outcome, and stop reason. Debug-only geometry and payload work is absent from production. +- Added red-first unit coverage and desktop/mobile browser regressions for request count, collapsed activity, short boundary pages, prompt `#1`, no eager open, and the 8 px prepend-anchor tolerance. +- Verification passed: 50 targeted unit tests, typecheck, targeted ESLint, Prettier, specification lint, 5 desktop Chromium tests, and 5 mobile Chrome tests. diff --git a/docs/specs/ui/system-design/task-prompt-transcript-visibility.md b/docs/specs/ui/system-design/task-prompt-transcript-visibility.md index 424282d34a..b846496814 100644 --- a/docs/specs/ui/system-design/task-prompt-transcript-visibility.md +++ b/docs/specs/ui/system-design/task-prompt-transcript-visibility.md @@ -29,6 +29,8 @@ The design changes no backend query, message order, persistence rule, or API fie - `messages.metaBySession[sessionId].hasMore` keeps the raw backend `has_more` value. - `messages.bySession[sessionId]` supplies the loaded messages and their prompt ordinals. - The native transcript and Prompt History panel consume the shared hook result. +- The native transcript owns the upward-navigation intent and the visible top-boundary key. +- `useLazyLoadSentinel` owns observer lifecycle and request serialization. - Transcript navigation uses only the messages that the transcript already loaded. - The hook also exposes an explicit raw-pagination loader for direct recovery consumers, such as session search. - `requestOlderMessages` keeps request coordination and raw cursor metadata unchanged. @@ -58,6 +60,22 @@ This immediate update stops one multi-page load operation at prompt `#1`. It pre The store keeps the raw backend value. Direct recovery code can use the hook's explicit raw-pagination loader when its contract requires the complete message stream. Session search uses this path because backend search can return a hit from before prompt `#1`. Transcript rendering and navigation continue to use visible pagination, so this recovery path does not restore the older-page control. +## Upward load cycle + +An upward user action starts one transcript load cycle. The cycle starts when the reader reaches the oldest loaded boundary. + +The transcript records the oldest standalone message key before each request. This key excludes the task-description fallback, transient status rows, and collapsed activity-group keys that can change when older tools join the group. + +After React commits the prepended page, the transcript compares the current key with the recorded key: + +- If the key changes, the page added a new visible top entry. The cycle stops until the reader reaches the new boundary. +- If the key does not change, the page only extended the current collapsed activity group. The cycle can request the next page. +- If the request fails, returns no rows, reaches prompt `#1`, or exhausts raw history, the cycle stops. + +The shared sentinel must not continue from a stale intersection value. A completed request must use the committed render boundary before it starts another request. + +Scroll restoration remains part of the same cycle. The transcript restores one stable row after each prepend. The restoration does not create new upward-navigation intent. + ## Control flow 1. The initial message request stores one newest suffix and raw pagination metadata. @@ -65,9 +83,12 @@ The store keeps the raw backend value. Direct recovery code can use the hook's e 3. The user reaches the oldest loaded point. 4. An older-page request prepends messages through the existing coordinator. 5. The native transcript preserves a stable message-row position across the complete request. -6. If the page contains prompt `#1`, the shared hook changes its visible value to false. -7. The transcript removes its sentinel, loading state, and older-page control. -8. Explicit reverse search uses raw pagination when it must backfill a backend search hit. +6. The transcript compares the committed visible top boundary with the request baseline. +7. If the boundary changed, the current load cycle stops. +8. If only a collapsed activity group changed, the same cycle can request another page. +9. If the page contains prompt `#1`, the shared hook changes its visible value to false. +10. The transcript removes its sentinel, loading state, and older-page control. +11. Explicit reverse search uses raw pagination when it must backfill a backend search hit. ## Failure and compatibility @@ -77,11 +98,19 @@ An initial tool-only window completes without an older-page request. The task-de Older payloads can omit `prompt_index`. In this case, the shared hook uses raw `has_more` exhaustion as the compatibility fallback. +## Observability + +The `messages:pagination` debug namespace records one start event and one settle event for each older-page request. + +The events include the session ID, trigger, page count, visible boundary keys, scroll geometry, and the continuation reason. The events do not include message content. + +The settle reason distinguishes collapsed-group continuation from visible-boundary stop, exhaustion, no progress, and request error. + ## Responsive behavior Desktop and mobile use the same native transcript and one vertical scroll owner. This change adds no mobile surface, control, or touch behavior. -The existing full-height mobile task layout remains the nearest mobile exemplar. The mobile pagination scenario proves the same visible start. +The existing full-height mobile task layout remains the nearest mobile exemplar. The mobile pagination scenario proves the same load-cycle boundary. ## Test boundaries @@ -93,6 +122,9 @@ The existing full-height mobile task layout remains the nearest mobile exemplar. - Desktop and mobile browser tests prove that task opening makes no request with an older-page cursor. - A message-fetch test proves that a tool-only initial window completes without automatic backfill. - Separate desktop and mobile browser tests preserve the prepend anchor while loading older pages. +- Desktop and mobile browser tests prove that one upward action loads only one page when that page adds visible entries. +- A collapsed-activity browser scenario proves that the same load cycle continues until a new visible top entry appears. +- Sentinel unit tests prove that stale intersection state cannot start a second visible-page request. ## Related design