Skip to content

Commit d475722

Browse files
wesbillmanPinkyBrain
authored
Smooth channel loading: single-surface timeline state machine (#1099)
Signed-off-by: Wes <[email protected]> Co-authored-by: Pinky <44b8e82baa6e0e254e0208d68f335c283c94e7b78dd1fa10d5a49d3f13dd0435@sprout-oss.stage.blox.sqprod.co> Co-authored-by: Brain <21994759fc7a6fa6b965551d35cfd7897d262f2495467f2d78694ddcfa6a5c7e@sprout-oss.stage.blox.sqprod.co>
1 parent 5004758 commit d475722

8 files changed

Lines changed: 401 additions & 62 deletions

File tree

‎desktop/src/features/channels/ui/ChannelScreen.tsx‎

Lines changed: 24 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,10 @@ import {
3535
} from "@/features/messages/lib/formatTimelineMessages";
3636
import { getThreadReference } from "@/features/messages/lib/threading";
3737
import { imetaMediaFromTags } from "@/features/messages/lib/imetaMediaMarkdown";
38+
import {
39+
resolveTimelineLoadingLatch,
40+
selectTimelineLoadingState,
41+
} from "@/features/messages/lib/timelineLoadingState";
3842
import { useFetchOlderMessages } from "@/features/messages/useFetchOlderMessages";
3943
import { useLoadMissingAncestors } from "@/features/messages/useLoadMissingAncestors";
4044
import { useChannelTyping } from "@/features/messages/useChannelTyping";
@@ -474,13 +478,27 @@ export function ChannelScreen({
474478
setThreadReplyTargetId,
475479
setThreadScrollTargetId,
476480
});
477-
const hasTimelineData = messagesQuery.data !== undefined;
478-
const isTimelineLoading =
481+
// `data !== undefined` is not "loaded": the cache is seeded early by stale
482+
// placeholders and the live subscription. Wait for the history fetch to settle.
483+
const timelineLoadingNow =
479484
activeChannel !== null &&
480485
activeChannel.channelType !== "forum" &&
481-
!hasTimelineData &&
482-
messagesQuery.isPending;
483-
const shouldShowInitialChannelLoading = isTimelineLoading;
486+
selectTimelineLoadingState({
487+
isPending: messagesQuery.isPending,
488+
isFetching: messagesQuery.isFetching,
489+
isPlaceholderData: messagesQuery.isPlaceholderData,
490+
dataLength: messagesQuery.data?.length ?? null,
491+
});
492+
// Latch loaded per channel so a later background refetch can't flip back to
493+
// the skeleton — that re-flip is the "skeleton bouncing up and down" on entry.
494+
const settledChannelIdRef = React.useRef<string | null>(null);
495+
const { settledChannelId, isLoading: isTimelineLoading } =
496+
resolveTimelineLoadingLatch(
497+
settledChannelIdRef.current,
498+
activeChannelId,
499+
timelineLoadingNow,
500+
);
501+
settledChannelIdRef.current = settledChannelId;
484502
// Panel identity (thread/profile/agent session) lives in the URL search
485503
// params, so channel changes and back/forward traversals carry it per
486504
// history entry — only the local ephemeral targets need resetting here.
@@ -607,9 +625,7 @@ export function ChannelScreen({
607625
ref={channelContentRef}
608626
>
609627
{activeChannel ? (
610-
shouldShowInitialChannelLoading ? (
611-
<ViewLoadingFallback includeHeader kind="channel" />
612-
) : activeChannel.channelType === "forum" ? (
628+
activeChannel.channelType === "forum" ? (
613629
<>
614630
{channelHeader}
615631
<React.Suspense fallback={<ViewLoadingFallback kind="forum" />}>
Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
import assert from "node:assert/strict";
2+
import test from "node:test";
3+
4+
import { selectTimelineLoadingState } from "./timelineLoadingState.ts";
5+
6+
const settled = {
7+
isPending: false,
8+
isFetching: false,
9+
isPlaceholderData: false,
10+
dataLength: null,
11+
};
12+
13+
test("pending first fetch with no cache is loading", () => {
14+
assert.equal(
15+
selectTimelineLoadingState({ ...settled, isPending: true }),
16+
true,
17+
);
18+
});
19+
20+
test("stale placeholder while refetching is loading", () => {
21+
// Revisited within gcTime: placeholderData hands back a cached array while the
22+
// authoritative fetch runs. Must keep the skeleton up, not flash the intro.
23+
assert.equal(
24+
selectTimelineLoadingState({
25+
...settled,
26+
isFetching: true,
27+
isPlaceholderData: true,
28+
dataLength: 0,
29+
}),
30+
true,
31+
);
32+
});
33+
34+
test("subscription-seeded empty cache while fetching is loading", () => {
35+
// The live subscription's setQueryData seeds [] before history settles, so
36+
// data is defined but empty and a fetch is still in flight.
37+
assert.equal(
38+
selectTimelineLoadingState({
39+
...settled,
40+
isFetching: true,
41+
isPlaceholderData: false,
42+
dataLength: 0,
43+
}),
44+
true,
45+
);
46+
});
47+
48+
test("settled with rows is not loading", () => {
49+
assert.equal(
50+
selectTimelineLoadingState({ ...settled, dataLength: 5 }),
51+
false,
52+
);
53+
});
54+
55+
test("settled and genuinely empty is not loading (real empty channel)", () => {
56+
assert.equal(
57+
selectTimelineLoadingState({ ...settled, dataLength: 0 }),
58+
false,
59+
);
60+
});
61+
62+
test("background refetch of a populated channel is not loading", () => {
63+
// staleTime expiry can trigger a background refetch; with rows already present
64+
// we are loaded and must not re-show the skeleton.
65+
assert.equal(
66+
selectTimelineLoadingState({
67+
...settled,
68+
isFetching: true,
69+
dataLength: 12,
70+
}),
71+
false,
72+
);
73+
});
74+
75+
import { resolveTimelineLoadingLatch } from "./timelineLoadingState.ts";
76+
77+
test("latch: loading on first entry to a channel", () => {
78+
const r = resolveTimelineLoadingLatch(null, "chan-a", true);
79+
assert.equal(r.isLoading, true);
80+
assert.equal(r.settledChannelId, null);
81+
});
82+
83+
test("latch: settles when loadingNow turns false, recording the channel", () => {
84+
const r = resolveTimelineLoadingLatch(null, "chan-a", false);
85+
assert.equal(r.isLoading, false);
86+
assert.equal(r.settledChannelId, "chan-a");
87+
});
88+
89+
test("latch: background refetch blip stays loaded once settled", () => {
90+
// settled for chan-a, then loadingNow blips true (isFetching) — must NOT
91+
// re-show the skeleton (the bounce Wes reported).
92+
const r = resolveTimelineLoadingLatch("chan-a", "chan-a", true);
93+
assert.equal(r.isLoading, false);
94+
assert.equal(r.settledChannelId, "chan-a");
95+
});
96+
97+
test("latch: switching channels resets and loads the new one", () => {
98+
const r = resolveTimelineLoadingLatch("chan-a", "chan-b", true);
99+
assert.equal(r.isLoading, true);
100+
assert.equal(r.settledChannelId, "chan-a"); // not yet settled for b
101+
});
102+
103+
test("latch: no active channel passes loadingNow through untouched", () => {
104+
assert.equal(
105+
resolveTimelineLoadingLatch("chan-a", null, true).isLoading,
106+
true,
107+
);
108+
assert.equal(
109+
resolveTimelineLoadingLatch("chan-a", null, false).isLoading,
110+
false,
111+
);
112+
});
Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
/**
2+
* Pure decision for "is the channel timeline still doing its initial load."
3+
*
4+
* Extracted so the windows below are covered by the lib `*.test.mjs` suite.
5+
* The trap: `data !== undefined` looks like "loaded" but the per-channel query
6+
* cache is seeded early — by a stale `placeholderData` on revisit, and by the
7+
* live subscription's `setQueryData` — before the authoritative history fetch
8+
* settles. Treating that as loaded flashes the channel intro/empty state over a
9+
* list that is about to stream in.
10+
*/
11+
export type TimelineQueryStatus = {
12+
isPending: boolean;
13+
isFetching: boolean;
14+
isPlaceholderData: boolean;
15+
dataLength: number | null;
16+
};
17+
18+
export function selectTimelineLoadingState(
19+
status: TimelineQueryStatus,
20+
): boolean {
21+
if (status.isPending) {
22+
return true;
23+
}
24+
// A fetch is in flight; keep loading while what we'd show is a placeholder or
25+
// still empty. Once real rows are present we are loaded, even mid-refetch.
26+
return (
27+
status.isFetching &&
28+
(status.isPlaceholderData || (status.dataLength ?? 0) === 0)
29+
);
30+
}
31+
32+
/**
33+
* Monotonic loading latch keyed by channel. Once a channel has settled (loaded),
34+
* `loadingNow` blipping true again (a background refetch) must not re-show the
35+
* skeleton — that re-flip is the visible skeleton bounce on entry. A different
36+
* channel id resets the latch so the new channel loads fresh.
37+
*/
38+
export function resolveTimelineLoadingLatch(
39+
settledChannelId: string | null,
40+
activeChannelId: string | null,
41+
loadingNow: boolean,
42+
): { settledChannelId: string | null; isLoading: boolean } {
43+
if (activeChannelId === null) {
44+
return { settledChannelId, isLoading: loadingNow };
45+
}
46+
if (settledChannelId === activeChannelId) {
47+
// Already settled for this channel — stay loaded through refetch blips.
48+
return { settledChannelId, isLoading: false };
49+
}
50+
if (!loadingNow) {
51+
// First settle for this channel; latch it.
52+
return { settledChannelId: activeChannelId, isLoading: false };
53+
}
54+
return { settledChannelId, isLoading: true };
55+
}

‎desktop/src/features/messages/lib/timelineSnapshot.test.mjs‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,8 @@ import {
88
resolveDeepLinkTarget,
99
selectDeferredListRenderState,
1010
selectLatestMessageKey,
11+
selectTimelineBodySurface,
12+
selectTimelineIntroSurface,
1113
} from "./timelineSnapshot.ts";
1214

1315
// Local-midnight unix-second timestamps so isSameDay (local time) is stable
@@ -287,3 +289,96 @@ test("deferred-render: keys the empty decision off the live count, not deferred"
287289
assert.equal(selectDeferredListRenderState(0, 0), "empty");
288290
assert.equal(selectDeferredListRenderState(0, 1), "pending");
289291
});
292+
293+
test("timeline-body-surface: loading and deferred-pending both paint the single static skeleton", () => {
294+
assert.equal(
295+
selectTimelineBodySurface({
296+
deferredCount: 0,
297+
isLoading: true,
298+
liveCount: 0,
299+
}),
300+
"skeleton",
301+
);
302+
assert.equal(
303+
selectTimelineBodySurface({
304+
deferredCount: 0,
305+
isLoading: false,
306+
liveCount: 3,
307+
}),
308+
"skeleton",
309+
);
310+
});
311+
312+
test("timeline-body-surface: deferred rows paint the message list", () => {
313+
assert.equal(
314+
selectTimelineBodySurface({
315+
deferredCount: 2,
316+
isLoading: false,
317+
liveCount: 2,
318+
}),
319+
"list",
320+
);
321+
});
322+
323+
test("timeline-body-surface: empty only when live and deferred rows are empty", () => {
324+
assert.equal(
325+
selectTimelineBodySurface({
326+
deferredCount: 0,
327+
isLoading: false,
328+
liveCount: 0,
329+
}),
330+
"empty",
331+
);
332+
});
333+
334+
test("timeline-intro-surface: skeleton suppresses intro while loading", () => {
335+
assert.equal(
336+
selectTimelineIntroSurface({
337+
hasChannelIntro: true,
338+
hasDirectMessageIntro: false,
339+
isSkeletonVisible: true,
340+
}),
341+
null,
342+
);
343+
});
344+
345+
test("timeline-intro-surface: intro may coexist with the message list", () => {
346+
assert.equal(
347+
selectTimelineBodySurface({
348+
deferredCount: 2,
349+
isLoading: false,
350+
liveCount: 2,
351+
}),
352+
"list",
353+
);
354+
assert.equal(
355+
selectTimelineIntroSurface({
356+
hasChannelIntro: true,
357+
hasDirectMessageIntro: false,
358+
isSkeletonVisible: false,
359+
}),
360+
"channel-intro",
361+
);
362+
});
363+
364+
test("timeline-intro-surface: direct-message intro wins over channel intro", () => {
365+
assert.equal(
366+
selectTimelineIntroSurface({
367+
hasChannelIntro: true,
368+
hasDirectMessageIntro: true,
369+
isSkeletonVisible: false,
370+
}),
371+
"direct-message-intro",
372+
);
373+
});
374+
375+
test("timeline-intro-surface: no intro without an intro model", () => {
376+
assert.equal(
377+
selectTimelineIntroSurface({
378+
hasChannelIntro: false,
379+
hasDirectMessageIntro: false,
380+
isSkeletonVisible: false,
381+
}),
382+
null,
383+
);
384+
});

‎desktop/src/features/messages/lib/timelineSnapshot.ts‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -148,3 +148,51 @@ export function selectDeferredListRenderState(
148148
}
149149
return "pending";
150150
}
151+
152+
export type TimelineBodySurface = "skeleton" | "empty" | "list";
153+
154+
export function selectTimelineBodySurface({
155+
deferredCount,
156+
isLoading,
157+
liveCount,
158+
}: {
159+
deferredCount: number;
160+
isLoading: boolean;
161+
liveCount: number;
162+
}): TimelineBodySurface {
163+
if (isLoading) {
164+
return "skeleton";
165+
}
166+
167+
const renderState = selectDeferredListRenderState(deferredCount, liveCount);
168+
if (renderState === "pending") {
169+
return "skeleton";
170+
}
171+
return renderState;
172+
}
173+
174+
export type TimelineIntroSurface =
175+
| "direct-message-intro"
176+
| "channel-intro"
177+
| null;
178+
179+
export function selectTimelineIntroSurface({
180+
hasChannelIntro,
181+
hasDirectMessageIntro,
182+
isSkeletonVisible,
183+
}: {
184+
hasChannelIntro: boolean;
185+
hasDirectMessageIntro: boolean;
186+
isSkeletonVisible: boolean;
187+
}): TimelineIntroSurface {
188+
if (isSkeletonVisible) {
189+
return null;
190+
}
191+
if (hasDirectMessageIntro) {
192+
return "direct-message-intro";
193+
}
194+
if (hasChannelIntro) {
195+
return "channel-intro";
196+
}
197+
return null;
198+
}

‎desktop/src/features/messages/ui/MessageThreadPanel.tsx‎

Lines changed: 1 addition & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -428,14 +428,7 @@ export function MessageThreadPanel({
428428
<div className="px-3 pb-3 pt-1" data-testid="message-thread-replies">
429429
{repliesRenderState === "list" ? (
430430
<div
431-
className={cn(
432-
"space-y-2.5",
433-
// While a deferred render is in flight the painted reply list
434-
// lags the latest `threadReplies`. Dim it slightly so the
435-
// streaming-in reads as intentional instead of frozen — mirrors
436-
// the main timeline.
437-
isRepliesPending && "opacity-60 transition-opacity",
438-
)}
431+
className="space-y-2.5"
439432
data-render-pending={isRepliesPending ? "true" : undefined}
440433
>
441434
{deferredThreadReplies.map((entry, index) => {

0 commit comments

Comments
 (0)