The best way to control Claude Code, Codex and more from any computer or phone
fix(web): constrain minimap highlights to visible rows (#16191)
Co-authored-by: Julius Marminge <julius0216@outlook.com>
Utkarsh Patil committed
Oct 20, 2026 at 11:38 UTC
bce474e35dc051efa31eb5f85fa3b11ce0bdb2af
3 files changed
+189
-79
apps/web/src/components/chat/MessagesTimeline.logic.test.ts
+61
@@ -35,6 +35,9 @@ import {
35
normalizeCompactToolLabel,
36
resolveAssistantMessageCopyState,
37
resolveTimelineIsAtEnd,
38
+ isTimelineMinimapRowVisible,
39
+ resolveTimelineMinimapCurrentIndex,
40
+ resolveTimelineMinimapVisibleRange,
41
resolveTimelineMinimapHasPersistentGutter,
42
resolveTimelineMinimapHeightStyle,
43
resolveTimelineMinimapHitStripWidth,
@@ -5636,6 +5639,64 @@ describe("shouldCollapseUserMessage", () => {
5639
});
5640
5641
describe("timeline end and minimap geometry", () => {
5642
+ it("highlights only visible rows inside the rendered buffer despite stale offscreen geometry", () => {
5643
+ const range = resolveTimelineMinimapVisibleRange({
5644
+ startBuffered: 9,
5645
+ endBuffered: 12,
5646
+ scroll: 1000,
5647
+ scrollLength: 200,
5648
+ // Both earlier and later unmounted rows retain coordinates inside the viewport.
5649
+ positionAtIndex: (index) => (index < 9 || index > 12 ? 1050 : index * 100),
5650
+ sizeAtIndex: () => 100,
5651
+ });
5652
+ expect(range).toEqual({ start: 10, end: 11 });
5653
+ const rowIndices = [0, 9, 10, 11, 12, 20];
5654
+ expect(
5655
+ rowIndices.filter((index) => isTimelineMinimapRowVisible(index, range.start, range.end)),
5656
+ ).toEqual([10, 11]);
5657
+ expect(
5658
+ resolveTimelineMinimapCurrentIndex({
5659
+ visibleStart: range.start,
5660
+ visibleEnd: range.end,
5661
+ rowIndices,
5662
+ }),
5663
+ ).toBe(2);
5664
+ });
5665
+
5666
+ it("refreshes the visible rows after scrolling and measurement within the same buffer", () => {
5667
+ const state = {
5668
+ startBuffered: 0,
5669
+ endBuffered: 2,
5670
+ scroll: 0,
5671
+ scrollLength: 200,
5672
+ positionAtIndex: (index: number) => [50, 150, 300][index],
5673
+ sizeAtIndex: (): number | undefined => undefined,
5674
+ };
5675
+ expect(resolveTimelineMinimapVisibleRange(state)).toEqual({ start: 0, end: 1 });
5676
+ const scrolled = { ...state, scroll: 100 };
5677
+ expect(resolveTimelineMinimapVisibleRange(scrolled)).toEqual({ start: 1, end: 1 });
5678
+ expect(resolveTimelineMinimapVisibleRange({ ...scrolled, sizeAtIndex: () => 100 })).toEqual({
5679
+ start: 0,
5680
+ end: 1,
5681
+ });
5682
+ expect(
5683
+ resolveTimelineMinimapVisibleRange({ ...scrolled, scroll: 400, sizeAtIndex: () => 100 }),
5684
+ ).toEqual({ start: null, end: null });
5685
+ });
5686
+
5687
+ it("navigates from the first visible user message or the preceding turn when only its response is visible", () => {
5688
+ const rowIndices = [0, 10, 20, 30, 40];
5689
+ const currentIndex = (visibleStart: number | null, visibleEnd: number | null) =>
5690
+ resolveTimelineMinimapCurrentIndex({ visibleStart, visibleEnd, rowIndices });
5691
+
5692
+ expect(currentIndex(19, 31)).toBe(2);
5693
+ expect(currentIndex(21, 29)).toBe(2);
5694
+ expect(currentIndex(41, 45)).toBe(4);
5695
+ expect(currentIndex(0, 0)).toBe(0);
5696
+ expect(currentIndex(null, null)).toBeNull();
5697
+ expect(isTimelineMinimapRowVisible(20, null, null)).toBe(false);
5698
+ });
5699
+
5700
it("treats the follow re-arm band above the content bottom as the live edge", () => {
5701
expect(resolveTimelineIsAtEnd({ isAtEnd: true })).toBe(true);
5702
expect(resolveTimelineIsAtEnd(undefined)).toBeUndefined();
apps/web/src/components/chat/MessagesTimeline.logic.ts
+52
-19
@@ -369,30 +369,63 @@ export function resolveTimelineMinimapIndexFromPointer(input: {
369
return Math.max(0, Math.min(input.itemCount - 1, Math.round(progress * (input.itemCount - 1))));
370
}
371
372
+/** Recheck the rendered buffer: LegendList's unbuffered range can lag during scrolling. */
373
+export function resolveTimelineMinimapVisibleRange(state: {
374
+ readonly startBuffered: number | null | undefined;
375
+ readonly endBuffered: number | null | undefined;
376
+ readonly scroll: number;
377
+ readonly scrollLength: number;
378
+ readonly positionAtIndex: (index: number) => number | undefined;
379
+ readonly sizeAtIndex: (index: number) => number | undefined;
380
+}) {
381
+ let start: number | null = null;
382
+ let end: number | null = null;
383
+ if (state.startBuffered == null || state.endBuffered == null || state.startBuffered < 0) {
384
+ return { start, end };
385
+ }
386
+ const bottom = state.scroll + state.scrollLength;
387
+ for (let index = state.startBuffered; index <= state.endBuffered; index += 1) {
388
+ const top = state.positionAtIndex(index);
389
+ const height = state.sizeAtIndex(index);
390
+ if (
391
+ top != null &&
392
+ Number.isFinite(top) &&
393
+ top < bottom &&
394
+ top + Math.max(1, height != null && Number.isFinite(height) ? height : 1) > state.scroll
395
+ ) {
396
+ start ??= index;
397
+ end = index;
398
+ }
399
+ }
400
+ return { start, end };
401
+}
402
+
403
+export function isTimelineMinimapRowVisible(
404
+ rowIndex: number,
405
+ visibleStart: number | null | undefined,
406
+ visibleEnd: number | null | undefined,
407
+): boolean {
408
+ return (
409
+ visibleStart != null && visibleEnd != null && rowIndex >= visibleStart && rowIndex <= visibleEnd
410
+ );
411
+}
412
+
413
export function resolveTimelineMinimapCurrentIndex(input: {
373
- readonly scrollTop: number;
374
- readonly scrollBottom: number;
375
- readonly itemBounds: ReadonlyArray<{
376
- readonly top: number | null;
377
- readonly height: number | null;
378
- }>;
414
+ readonly visibleStart: number | null | undefined;
415
+ readonly visibleEnd: number | null | undefined;
416
+ readonly rowIndices: ReadonlyArray<number>;
417
}): number | null {
418
+ if (input.visibleStart == null || input.visibleEnd == null) {
419
+ return null;
420
+ }
421
let precedingIndex: number | null = null;
381
-
382
- for (const [index, item] of input.itemBounds.entries()) {
383
- if (item.top === null) {
384
- continue;
385
- }
386
- const inView =
387
- item.top < input.scrollBottom && item.top + Math.max(1, item.height ?? 1) > input.scrollTop;
388
- if (inView) {
389
- return index;
390
- }
391
- if (item.top <= input.scrollTop) {
392
- precedingIndex = index;
422
+ for (const [index, rowIndex] of input.rowIndices.entries()) {
423
+ if (rowIndex >= input.visibleStart) {
424
+ // Prefer the first visible user message, otherwise the turn being read.
425
+ return rowIndex <= input.visibleEnd ? index : precedingIndex;
426
}
427
+ precedingIndex = index;
428
}
395
-
429
return precedingIndex;
430
}
431
apps/web/src/components/chat/MessagesTimeline.tsx
+76
-60
@@ -61,6 +61,7 @@ import {
61
} from "@t3tools/client-runtime/state/subagent-display";
62
import type { WorkflowOpening } from "@t3tools/client-runtime/state/subagentRuntime";
63
import { observeResize } from "~/lib/observeResize";
64
+import { useStableCallback } from "~/hooks/useStableCallback";
65
66
const NOOP_USE_ARTIFACT_TEMPLATE = () => {};
67
const NOOP_OPEN_ATTACHMENT = (_attachment: ChatFileAttachment) => {};
@@ -208,6 +209,8 @@ import {
209
resolveTimelineIsAtEnd,
210
resolveTimelineMinimapHasPersistentGutter,
211
resolveTimelineMinimapCurrentIndex,
212
+ isTimelineMinimapRowVisible,
213
+ resolveTimelineMinimapVisibleRange,
214
resolveTimelineMinimapHeightStyle,
215
resolveTimelineMinimapHitStripWidth,
216
resolveTimelineMinimapIndexFromPointer,
@@ -870,6 +873,7 @@ const ConversationTimeline = memo(function ConversationTimeline({
873
// must not change with them or every timeline row re-renders per event.
874
const runs = useStableHandoffRuns(runsProp);
875
const minimapItems = deriveTimelineMinimapItems(rows);
876
+ const minimapRowIndices = minimapItems.map((item) => item.rowIndex);
877
// Preserve initialScrollAtEnd's measured target until the list is reused
878
// for another thread; scrollToEnd would replace it with an estimated offset.
879
const listOpenedOnRef = useRef<{
@@ -1126,13 +1130,6 @@ const ConversationTimeline = memo(function ConversationTimeline({
1130
onContentOverflowChange(measureContentOverflow());
1131
});
1132
};
1129
- const handleItemSizeChanged = () => {
1130
- if (disclosurePinsEndRef.current) {
1131
- queueMicrotask(pinDisclosureToEnd);
1132
- scheduleDisclosureSettle();
1133
- }
1134
- reportContentOverflow();
1135
- };
1133
useEffect(() => cancelContentOverflowFrame, [cancelContentOverflowFrame]);
1134
useLayoutEffect(() => {
1135
cancelContentOverflowFrame();
@@ -1140,6 +1137,60 @@ const ConversationTimeline = memo(function ConversationTimeline({
1137
// oxlint-disable-next-line react/exhaustive-effect-dependencies -- Added or removed rows change the content height.
1138
}, [cancelContentOverflowFrame, measureContentOverflow, onContentOverflowChange, rows.length]);
1139
1140
+ const refreshMinimap = useStableCallback(() => {
1141
+ const state = listRef.current?.getState?.();
1142
+ if (restoringThreadPosition || state?.data !== rows) return;
1143
+ if (!state || minimapItems.length === 0) {
1144
+ return;
1145
+ }
1146
+
1147
+ const firstBufferedIndex = state.startBuffered;
1148
+ const firstBufferedRow: HTMLElement | undefined =
1149
+ firstBufferedIndex == null ? undefined : state.elementAtIndex(firstBufferedIndex);
1150
+ const firstBufferedTop =
1151
+ firstBufferedIndex == null ? undefined : state.positionAtIndex(firstBufferedIndex);
1152
+ const viewport: HTMLElement | undefined = listRef.current?.getScrollableNode();
1153
+ // Cached row positions exclude the header and pending scroll adjustments.
1154
+ const scroll =
1155
+ firstBufferedRow && viewport && firstBufferedTop !== undefined
1156
+ ? firstBufferedTop +
1157
+ viewport.getBoundingClientRect().top -
1158
+ firstBufferedRow.getBoundingClientRect().top
1159
+ : state.scroll;
1160
+ const visibleRange = resolveTimelineMinimapVisibleRange({ ...state, scroll });
1161
+ for (const item of minimapItems) {
1162
+ const strip = minimapStripMap.get(item.id);
1163
+ const inView = isTimelineMinimapRowVisible(
1164
+ item.rowIndex,
1165
+ visibleRange.start,
1166
+ visibleRange.end,
1167
+ );
1168
+ const next = inView ? "true" : "false";
1169
+ // Avoid dirtying style state on every scroll tick for unchanged strips.
1170
+ if (strip && strip.dataset.inView !== next) {
1171
+ strip.dataset.inView = next;
1172
+ }
1173
+ }
1174
+ const nextCurrentIndex = resolveTimelineMinimapCurrentIndex({
1175
+ visibleStart: visibleRange.start,
1176
+ visibleEnd: visibleRange.end,
1177
+ rowIndices: minimapRowIndices,
1178
+ });
1179
+ setMinimapCurrentIndex((current) =>
1180
+ current === nextCurrentIndex ? current : nextCurrentIndex,
1181
+ );
1182
+ });
1183
+
1184
+ const minimapRefreshFrameRef = useRef<number | null>(null);
1185
+ const scheduleMinimapRefresh = () => {
1186
+ if (minimapRefreshFrameRef.current !== null) return;
1187
+ // LegendList recycles row containers before React commits their positions.
1188
+ minimapRefreshFrameRef.current = requestAnimationFrame(() => {
1189
+ minimapRefreshFrameRef.current = null;
1190
+ refreshMinimap();
1191
+ });
1192
+ };
1193
+
1194
const handleScroll = () => {
1195
const state = listRef.current?.getState?.();
1196
if (restoringThreadPosition || state?.data !== rows) return;
@@ -1172,45 +1223,28 @@ const ConversationTimeline = memo(function ConversationTimeline({
1223
onIsAtEndChange(isAtEnd);
1224
}
1225
reportContentOverflow();
1175
- if (!state || minimapItems.length === 0) {
1176
- return;
1177
- }
1178
-
1179
- const scrollTop = state.scroll ?? 0;
1180
- const scrollBottom = scrollTop + (state.scrollLength ?? 0);
1181
-
1182
- const itemBounds = minimapItems.map((item) => ({
1183
- top: resolveTimelineRowTop(state, item.rowIndex),
1184
- height: resolveTimelineRowHeight(state, item.rowIndex),
1185
- }));
1226
+ scheduleMinimapRefresh();
1227
+ };
1228
1187
- for (const [index, item] of minimapItems.entries()) {
1188
- const strip = minimapStripMap.get(item.id);
1189
- const bounds = itemBounds[index];
1190
- const rowTop = bounds?.top ?? null;
1191
- const rowHeight = bounds?.height ?? null;
1192
- const inView =
1193
- rowTop !== null &&
1194
- rowTop < scrollBottom &&
1195
- rowTop + Math.max(1, rowHeight ?? 1) > scrollTop;
1196
-
1197
- // Skip no-op attribute writes: this runs for every strip on every scroll
1198
- // tick, and rewriting an unchanged attribute still dirties style state.
1199
- const next = inView ? "true" : "false";
1200
- if (strip && strip.dataset.inView !== next) {
1201
- strip.dataset.inView = next;
1202
- }
1229
+ const handleItemSizeChanged = () => {
1230
+ if (disclosurePinsEndRef.current) {
1231
+ queueMicrotask(pinDisclosureToEnd);
1232
+ scheduleDisclosureSettle();
1233
}
1204
- const nextCurrentIndex = resolveTimelineMinimapCurrentIndex({
1205
- scrollTop,
1206
- scrollBottom,
1207
- itemBounds,
1208
- });
1209
- setMinimapCurrentIndex((current) =>
1210
- current === nextCurrentIndex ? current : nextCurrentIndex,
1211
- );
1234
+ reportContentOverflow();
1235
+ scheduleMinimapRefresh();
1236
};
1237
1238
+ useEffect(
1239
+ () => () => {
1240
+ if (minimapRefreshFrameRef.current !== null) {
1241
+ cancelAnimationFrame(minimapRefreshFrameRef.current);
1242
+ minimapRefreshFrameRef.current = null;
1243
+ }
1244
+ },
1245
+ [],
1246
+ );
1247
+
1248
useEffect(() => {
1249
const frame = requestAnimationFrame(handleScroll);
1250
return () => cancelAnimationFrame(frame);
@@ -1613,24 +1647,6 @@ function getItemType(item: MessagesTimelineRow) {
1647
return `message:${item.message.role}:${lengthBucket}`;
1648
}
1649
1616
-interface TimelinePositionState {
1617
- readonly contentLength?: number;
1618
- readonly scroll?: number;
1619
- readonly scrollLength?: number;
1620
- readonly positionAtIndex?: (index: number) => number | undefined;
1621
- readonly sizeAtIndex?: (index: number) => number | undefined;
1622
-}
1623
-
1624
-function resolveTimelineRowTop(state: TimelinePositionState, rowIndex: number) {
1625
- const top = state.positionAtIndex?.(rowIndex);
1626
- return typeof top === "number" && Number.isFinite(top) ? top : null;
1627
-}
1628
-
1629
-function resolveTimelineRowHeight(state: TimelinePositionState, rowIndex: number) {
1630
- const height = state.sizeAtIndex?.(rowIndex);
1631
- return typeof height === "number" && Number.isFinite(height) ? height : null;
1632
-}
1633
-
1650
function timelineMinimapEventTargetsPreview(target: EventTarget): boolean {
1651
return target instanceof Element && target.closest("[data-minimap-preview]") !== null;
1652
}