fix: prevent chat pagination scroll flicker (#3063)
This commit is contained in:
@@ -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 = () => {};
|
||||
|
||||
@@ -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]);
|
||||
|
||||
@@ -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.
|
||||
+98
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user