Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

fix(web): always land at bottom when entering a conversation (#270)

Yaowei Zheng7d237349d3bb
diff --git a/packages/web/src/features/chat/message-stream.tsx b/packages/web/src/features/chat/message-stream.tsx
index 2b4f1bda..bbd4ab50 100644
--- a/packages/web/src/features/chat/message-stream.tsx
+++ b/packages/web/src/features/chat/message-stream.tsx
@@ -14,7 +14,7 @@ import type { PendingApproval } from "./use-session-stream";
import { EmptyState } from "../../components/ui/empty-state";
import { MessageItem } from "./message-item";
import { WorkGroup, isWorkItem } from "./work-group";
-import { createStreamFollow } from "./stream-follow";
+import { createStreamFollow, stickToBottom } from "./stream-follow";
import type { StreamFollow } from "./stream-follow";
/** Context passed down to nested rendering (pending approvals + approval submit callback + current origin chain). */
@@ -273,6 +273,10 @@ export function MessageStream({
// Layout effect (not useEffect): the stick-to-bottom snap must land before paint, otherwise
// fast streams show the bottom edge "catching up" by the growth of each commit. Suppressed
// during the animated return — the glide owns the scroll position until it arrives.
+ // Every snap goes through stickToBottom, which reports the landed position to the follow
+ // model synchronously — the snap's async scroll event otherwise races late content growth
+ // and could misinitialize follow as "parked above the bottom" right after entering a
+ // conversation (see stream-follow.ts).
useLayoutEffect(() => {
const el = scrollRef.current;
// Prepend scroll anchoring: when older windows land ABOVE the viewport, keep the
@@ -288,7 +292,7 @@ export function MessageStream({
}
lastPrependedRef.current = prepended;
if (el) lastHeightRef.current = el.scrollHeight;
- if (el && follow.stick && !returningRef.current) el.scrollTop = el.scrollHeight;
+ if (el && follow.stick && !returningRef.current) stickToBottom(el, follow);
syncJump();
// syncJump is recreated per render; the effect intentionally keys on stream growth only.
// eslint-disable-next-line react-hooks/exhaustive-deps
@@ -306,7 +310,7 @@ export function MessageStream({
if (!el || typeof ResizeObserver === "undefined") return;
const ro = new ResizeObserver(() => {
lastHeightRef.current = el.scrollHeight;
- if (follow.stick && !returningRef.current) el.scrollTop = el.scrollHeight;
+ if (follow.stick && !returningRef.current) stickToBottom(el, follow);
syncJump();
});
ro.observe(el);
@@ -324,7 +328,7 @@ export function MessageStream({
if (!el) return;
if (window.matchMedia("(prefers-reduced-motion: reduce)").matches) {
follow.resume();
- el.scrollTop = el.scrollHeight;
+ stickToBottom(el, follow);
syncJump();
return;
}
@@ -345,7 +349,7 @@ export function MessageStream({
if (remaining <= 1) {
returningRef.current = false;
follow.resume();
- live.scrollTop = live.scrollHeight;
+ stickToBottom(live, follow);
syncJump();
return;
}
diff --git a/packages/web/src/features/chat/stream-follow.ts b/packages/web/src/features/chat/stream-follow.ts
index 38a44d48..cc824407 100644
--- a/packages/web/src/features/chat/stream-follow.ts
+++ b/packages/web/src/features/chat/stream-follow.ts
@@ -16,7 +16,10 @@
* - The first scroll event has no direction to judge from, so it initializes from position
* (≥80px from bottom is treated as being at a historical position, i.e. not following) — this
* doesn't depend on the call-ordering guarantee of "must stick to bottom programmatically right
- * after mount."
+ * after mount." Programmatic sticks therefore go through stickToBottom, which reports the
+ * landed position synchronously: the snap's own scroll event only arrives at the next
+ * rendering update, and content growing in between (an image decoding, a font swap) would
+ * otherwise make that first event look like a historical position and wrongly exit follow.
*/
export interface ScrollMetrics {
scrollTop: number;
@@ -82,3 +85,32 @@ export function createStreamFollow(): StreamFollow {
},
};
}
+
+/** Minimal mutable view of a scroll container (structurally satisfied by HTMLElement; fakeable in unit tests). */
+export interface ScrollContainer {
+ scrollTop: number;
+ readonly scrollHeight: number;
+ readonly clientHeight: number;
+}
+
+/**
+ * Programmatic stick-to-bottom: snap the container to its bottom AND synchronously report the
+ * landed position to the follow model. The report is the point (the fix for entering a
+ * conversation occasionally not landing at the bottom): the browser dispatches the snap's
+ * scroll event asynchronously at the next rendering update, and late content growth (an image
+ * finishing decode, a font swap, a code block settling) can land in between. That event then
+ * reads a live position ≥80px above the new bottom with an unchanged scrollTop, and — as the
+ * first scrolled() call — the position initialization would misread it as the user parked at a
+ * historical position and exit follow; every later re-snap is gated on `stick`, so the view
+ * stayed off-bottom until manual scrolling. Reporting synchronously seeds the model with the
+ * snap itself, so the delayed event goes down the ordinary no-regression path and follow
+ * survives (growth with an unchanged scrollTop never exits).
+ */
+export function stickToBottom(el: ScrollContainer, follow: StreamFollow): void {
+ el.scrollTop = el.scrollHeight; // The browser clamps to the real bottom; read back the clamped value below.
+ follow.scrolled({
+ scrollTop: el.scrollTop,
+ scrollHeight: el.scrollHeight,
+ clientHeight: el.clientHeight,
+ });
+}
diff --git a/packages/web/test/stream-follow.test.ts b/packages/web/test/stream-follow.test.ts
index 8b840193..630c50bd 100644
--- a/packages/web/test/stream-follow.test.ts
+++ b/packages/web/test/stream-follow.test.ts
@@ -3,10 +3,12 @@
* slack < 80px), scrolling up immediately exits auto-stick-to-bottom; staying at
* a historical position, streaming increments don't override that intent; the
* user can scroll back down to resume; content-shrink clamping isn't
- * misread as an upward scroll.
+ * misread as an upward scroll. Plus stickToBottom: programmatic snaps report the
+ * landed position synchronously, so content growth racing the snap's async scroll
+ * event can't make entering a conversation land off-bottom.
*/
import { describe, expect, it } from "vitest";
-import { createStreamFollow } from "../src/features/chat/stream-follow";
+import { createStreamFollow, stickToBottom } from "../src/features/chat/stream-follow";
/** Short scroll area: content 500px, viewport 460px, scrollable slack only 40px (always under the 80px threshold). */
const SHORT = { scrollHeight: 500, clientHeight: 460 };
@@ -92,3 +94,78 @@ describe("createStreamFollow", () => {
expect(f.stick).toBe(true);
});
});
+
+/** Fake scroll container: clamps scrollTop into [0, scrollHeight - clientHeight] like a real element. */
+function fakeContainer(scrollHeight: number, clientHeight: number) {
+ let top = 0;
+ return {
+ scrollHeight,
+ clientHeight,
+ get scrollTop() {
+ return top;
+ },
+ set scrollTop(v: number) {
+ top = Math.max(0, Math.min(v, this.scrollHeight - this.clientHeight));
+ },
+ metrics() {
+ return { scrollTop: top, scrollHeight: this.scrollHeight, clientHeight: this.clientHeight };
+ },
+ };
+}
+
+describe("stickToBottom", () => {
+ it("entry race: growth landing between the mount snap and its async scroll event keeps follow (and the next snap reaches the new bottom)", () => {
+ const f = createStreamFollow();
+ const el = fakeContainer(2000, 460);
+ // Entering a conversation: the mount layout effect snaps and reports synchronously.
+ stickToBottom(el, f);
+ expect(el.scrollTop).toBe(1540);
+ expect(f.stick).toBe(true);
+ // An image finishes decoding before the browser dispatches the snap's scroll event:
+ // content grows 300px below the viewport, scrollTop stays put.
+ el.scrollHeight += 300;
+ // The delayed scroll event reads LIVE metrics — 300px above the bottom. Before the fix
+ // this was the FIRST scrolled() call, so the position initialization treated it as a
+ // historical position and exited follow; with the snap reported first it takes the
+ // ordinary path (scrollTop unchanged = no upward intent) and follow survives.
+ f.scrolled(el.metrics());
+ expect(f.stick).toBe(true);
+ // The ResizeObserver re-snap on that growth then lands the view at the new bottom.
+ stickToBottom(el, f);
+ expect(el.scrollTop).toBe(1840);
+ expect(f.stick).toBe(true);
+ });
+
+ it("content that fits the viewport: snap clamps to 0 and stays following", () => {
+ const f = createStreamFollow();
+ const el = fakeContainer(300, 460);
+ stickToBottom(el, f);
+ expect(el.scrollTop).toBe(0);
+ expect(f.stick).toBe(true);
+ });
+
+ it("a real upward scroll right after the reported snap still exits immediately", () => {
+ const f = createStreamFollow();
+ const el = fakeContainer(2000, 460);
+ stickToBottom(el, f);
+ el.scrollTop = 1200; // scrollbar drag up
+ f.scrolled(el.metrics());
+ expect(f.stick).toBe(false);
+ });
+
+ it("back-to-bottom (resume + snap): growth before the jump's scroll event keeps follow too", () => {
+ const f = createStreamFollow();
+ const el = fakeContainer(2000, 460);
+ stickToBottom(el, f);
+ el.scrollTop = 200; // dragged far up, exits.
+ f.scrolled(el.metrics());
+ expect(f.stick).toBe(false);
+ // The jump button: resume() forgets lastTop, then the snap re-seeds it — so growth
+ // racing the jump's scroll event can't re-trigger the first-event misread either.
+ f.resume();
+ stickToBottom(el, f);
+ el.scrollHeight += 300;
+ f.scrolled(el.metrics());
+ expect(f.stick).toBe(true);
+ });
+});