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.tsxindex 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.tsindex 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.tsindex 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);+ });+});