fix(web): keep queued transcript snaps reader-safe

apps/web/src/lib/transcript-scroll.test.ts

@@ -1,5 +1,9 @@
 import { describe, expect, it } from "vitest";
-import { transcriptIsNearEnd } from "./transcript-scroll.js";
+import {
+  transcriptCanSnapAfterFrame,
+  transcriptIsNearEnd,
+  transcriptMovedDown,
+} from "./transcript-scroll.js";
 
 describe("transcriptIsNearEnd", () => {
   it("follows only while the viewport is within 80px of the latest message", () => {
@@ -11,3 +15,26 @@ describe("transcriptIsNearEnd", () => {
     );
   });
 });
+
+describe("transcriptCanSnapAfterFrame", () => {
+  it("does not snap after the reader moves while the frame is queued", () => {
+    const transcript = { scrollTop: 950 };
+    expect(transcriptCanSnapAfterFrame(transcript, transcript, 950)).toBe(true);
+    transcript.scrollTop = 920;
+    expect(transcriptCanSnapAfterFrame(transcript, transcript, 950)).toBe(false);
+  });
+
+  it("does not snap a replacement transcript", () => {
+    const queuedTranscript = { scrollTop: 950 };
+    const replacementTranscript = { scrollTop: 950 };
+    expect(transcriptCanSnapAfterFrame(replacementTranscript, queuedTranscript, 950)).toBe(false);
+  });
+});
+
+describe("transcriptMovedDown", () => {
+  it("does not treat an uninitialized baseline as downward movement", () => {
+    expect(transcriptMovedDown(null, 920)).toBe(false);
+    expect(transcriptMovedDown(950, 920)).toBe(false);
+    expect(transcriptMovedDown(920, 950)).toBe(true);
+  });
+});

apps/web/src/lib/transcript-scroll.ts

@@ -3,3 +3,15 @@ export function transcriptIsNearEnd(
 ): boolean {
   return element.scrollHeight - element.scrollTop - element.clientHeight < 80;
 }
+
+export function transcriptCanSnapAfterFrame(
+  element: Pick<HTMLElement, "scrollTop"> | null,
+  queuedElement: Pick<HTMLElement, "scrollTop">,
+  queuedScrollTop: number,
+): boolean {
+  return element === queuedElement && queuedElement.scrollTop === queuedScrollTop;
+}
+
+export function transcriptMovedDown(previousScrollTop: number | null, scrollTop: number): boolean {
+  return previousScrollTop !== null && scrollTop >= previousScrollTop;
+}

apps/web/src/pages/Shell.tsx

@@ -140,7 +140,11 @@ import {
   reduceThreadSnapshot,
   userHoldsComputerControl,
 } from "../lib/thread-events";
-import { transcriptIsNearEnd } from "../lib/transcript-scroll";
+import {
+  transcriptCanSnapAfterFrame,
+  transcriptIsNearEnd,
+  transcriptMovedDown,
+} from "../lib/transcript-scroll";
 import { speaker } from "../lib/tts";
 import { ActivityList } from "./ActivityList";
 import type { ContextMenuPosition } from "./BotContextMenu";
@@ -474,6 +478,18 @@ export function ShellPage() {
     [navigate],
   );
 
+  function snapTranscriptToEndAfterFrame() {
+    const queuedElement = messageScroll.current;
+    if (!queuedElement) return;
+    const queuedScrollTop = queuedElement.scrollTop;
+    window.requestAnimationFrame(() => {
+      const element = messageScroll.current;
+      if (transcriptCanSnapAfterFrame(element, queuedElement, queuedScrollTop)) {
+        queuedElement.scrollTop = queuedElement.scrollHeight;
+      }
+    });
+  }
+
   async function refreshGroupThread(id: string) {
     const scrollElement = messageScroll.current;
     const stickToEnd = !scrollElement || transcriptIsNearEnd(scrollElement);
@@ -498,10 +514,7 @@ export function ShellPage() {
       (!scrollElement || transcriptIsNearEnd(scrollElement)) &&
       expandedHistoryThread.current !== snap.threadId
     ) {
-      window.requestAnimationFrame(() => {
-        const element = messageScroll.current;
-        if (element) element.scrollTop = element.scrollHeight;
-      });
+      snapTranscriptToEndAfterFrame();
     }
     return snap;
   }
@@ -537,10 +550,7 @@ export function ShellPage() {
       (!scrollElement || transcriptIsNearEnd(scrollElement)) &&
       expandedHistoryThread.current !== snap.threadId
     ) {
-      window.requestAnimationFrame(() => {
-        const element = messageScroll.current;
-        if (element) element.scrollTop = element.scrollHeight;
-      });
+      snapTranscriptToEndAfterFrame();
     }
     const [routines, skills] = await Promise.all([
       rpc.routines.list({ botId: id }),
@@ -3103,7 +3113,7 @@ const Transcript = memo(function Transcript({
   const [atEnd, setAtEnd] = useState(true);
   const following = useRef(true);
   const autoScrolling = useRef(false);
-  const lastScrollTop = useRef(0);
+  const lastScrollTop = useRef<number | null>(null);
   const autoScrollTimer = useRef<number | undefined>(undefined);
   const jumpButtonRef = useRef<HTMLButtonElement>(null);
   const messageById = useMemo(
@@ -3185,22 +3195,28 @@ const Transcript = memo(function Transcript({
       <div
         ref={scrollRef}
         data-testid="transcript"
-        onPointerDown={() => {
+        onPointerDown={(event) => {
+          lastScrollTop.current = event.currentTarget.scrollTop;
           autoScrolling.current = false;
           following.current = false;
         }}
-        onTouchStart={() => {
+        onTouchStart={(event) => {
+          lastScrollTop.current = event.currentTarget.scrollTop;
           autoScrolling.current = false;
           following.current = false;
         }}
         onWheel={(event) => {
           if (event.deltaY < 0) {
+            lastScrollTop.current = event.currentTarget.scrollTop;
             autoScrolling.current = false;
             following.current = false;
           }
         }}
         onScroll={(event) => {
-          const scrolledDown = event.currentTarget.scrollTop >= lastScrollTop.current;
+          const scrolledDown = transcriptMovedDown(
+            lastScrollTop.current,
+            event.currentTarget.scrollTop,
+          );
           lastScrollTop.current = event.currentTarget.scrollTop;
           const nearEnd = transcriptIsNearEnd(event.currentTarget);
           setAtEnd(nearEnd);