fix: prevent chat pagination scroll flicker (#3063)

This commit is contained in:
Carlos Florêncio
2026-08-26 20:36:08 +00:00
committed by GitHub
parent 4820d3ede3
commit 64963e061a
12 changed files with 995 additions and 90 deletions
@@ -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;
}
@@ -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<HTMLDivElement | null>,
hasMore: boolean,
blocked: boolean,
isLoadingMore: boolean,
loadMore: () => Promise<number>,
) {
return useSharedLazyLoadSentinel(scrollRef, hasMore, blocked, isLoadingMore, loadMore, {
function useLazyLoadSentinel(params: {
scrollRef: React.RefObject<HTMLDivElement | null>;
items: RenderItem[];
sessionId: string | null;
hasMore: boolean;
blocked: boolean;
isLoadingMore: boolean;
loadMore: () => Promise<number>;
}) {
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<PaginationRequest | null>(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<HTMLDivElement | null>,
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 };
@@ -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<number>;
}) {
const scrollRef = useRef<HTMLDivElement>(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 <div data-testid="native-scroll-management-container" ref={scrollRef} />;
}
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(<NativeScrollManagementHarness items={[]} metrics={metrics} />);
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(<NativeScrollManagementHarness items={[]} />);
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(
<NativeScrollManagementHarness
items={[transcriptActivity("activity-before", "turn-1"), newest]}
loadMore={loadMore}
/>,
);
const wrappedLoadMore = sharedSentinelCalls.at(-1)?.[4] as () => Promise<number>;
await wrappedLoadMore();
rerender(
<NativeScrollManagementHarness
items={[transcriptActivity("activity-after", "turn-1"), newest]}
loadMore={loadMore}
/>,
);
let options = sharedSentinelCalls.at(-1)?.[5] as {
shouldContinueWhileIntersecting: () => boolean;
};
expect(options.shouldContinueWhileIntersecting()).toBe(true);
await wrappedLoadMore();
rerender(
<NativeScrollManagementHarness
items={[transcriptActivity("activity-new", "turn-2"), newest]}
loadMore={loadMore}
/>,
);
options = sharedSentinelCalls.at(-1)?.[5] as {
shouldContinueWhileIntersecting: () => boolean;
};
expect(options.shouldContinueWhileIntersecting()).toBe(false);
});
it("anchors a prepend below a fixed task description row", () => {
@@ -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<number> {
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<number> {
return list.evaluate((element, id) => {
const row = Array.from(element.querySelectorAll<HTMLElement>("[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<number> {
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;
});
}
@@ -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);
@@ -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);
@@ -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<number>((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<number>((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 = () => {};
+107 -21
View File
@@ -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<IntersectionObserver | null>;
sentinelNodeRef: React.MutableRefObject<HTMLDivElement | null>;
@@ -43,7 +72,8 @@ type SentinelMutableRefs = {
fireLoadRef: React.MutableRefObject<(() => void) | null>;
loadInFlightRef: React.MutableRefObject<boolean>;
continuationScheduledRef: React.MutableRefObject<boolean>;
continuationTimerRef: React.MutableRefObject<ReturnType<typeof setTimeout> | null>;
continuationFrameRef: React.MutableRefObject<number | null>;
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<IntersectionObserver | null>(null);
const sentinelNodeRef = useRef<HTMLDivElement | null>(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<ReturnType<typeof setTimeout> | null>(null);
const continuationFrameRef = useRef<number | null>(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]);
+2 -1
View File
@@ -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.
@@ -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.
@@ -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.
@@ -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