DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Python ai-agentsai-tutorclawbotcli-tooldeepresearchinteractive-learninglearningmulti-agent-systemsrag
fix(chat): preserve follow state across delayed layout changes
yepyhunfd2e9e909aaa
diff --git a/web/hooks/useChatAutoScroll.ts b/web/hooks/useChatAutoScroll.tsindex 8fdaca47f..08db25e18 100644--- a/web/hooks/useChatAutoScroll.ts+++ b/web/hooks/useChatAutoScroll.ts@@ -11,317 +11,131 @@ interface AutoScrollOptions {lastEventCount?: number;}-/**- * "Pin to bottom" autoscroll, designed for jitter-free LLM streaming.- *- * The implementation deliberately collapses what used to be three- * separate scroll paths (a throttled timer, a rAF tick, a smooth-vs-- * instant branch on stream state) into one: a single- * ``useLayoutEffect`` that assigns ``scrollTop = scrollHeight`` while- * ``autoFollow`` is true. That is the only writer to ``scrollTop``- * during streaming, which removes all the races that previously made- * the viewport visibly stutter — smooth-scroll animation interrupted- * by the next delta's instant snap, throttle + rAF firing within the- * same frame, the browser's built-in scroll anchoring tugging back at- * the manual pin while mid-stream code blocks / KaTeX / dynamic- * viewers reflow above the cursor, etc.- *- * Three companion mechanisms keep behaviour correct in edge cases:- *- * - ``handleScroll`` watches the user's scroll position. The instant- * they move more than 80px above the bottom we release the pin so- * they can browse history without being yanked back. Scrolling- * back near the bottom re-arms it.- * - ``composerHeight`` changes (e.g. when the composer grows for a- * multi-line draft) re-pin once via a layout effect so the freshly-- * revealed content stays on screen.- * - A short post-stream window watches for ``childList`` mutations.- * Several capability viewers (MathAnimator, Quiz, Visualize) are- * loaded via ``next/dynamic({ssr:false})`` and only mount after the- * final result event lands; if the user is still pinned we follow- * those late-mounting heights downward.- *- * The scroll container must also opt into ``overflow-anchor: none``- * (set globally on ``[data-chat-scroll-root="true"]``). Without it,- * the browser's default scroll-anchoring tries to keep an in-viewport- * element fixed in screen space when content above it grows — which- * fights this hook every time a code block expands.+/** Follow layout changes until the reader intentionally leaves the live end.+ * Observe content size, not an arbitrary post-stream timeout: markdown, images+ * and disclosure animations can settle independently of the transport.+ * The scroll root must retain overflow-anchor: none to avoid competing writers.*/export function useChatAutoScroll({- hasMessages,- isStreaming,- composerHeight,- messageCount,- lastMessageContent,- lastEventCount,+ hasMessages, isStreaming, composerHeight, messageCount,+ lastMessageContent, lastEventCount,}: AutoScrollOptions) {const containerRef = useRef<HTMLDivElement>(null);const endRef = useRef<HTMLDivElement>(null);const shouldAutoScrollRef = useRef(true);+ const positionRef = useRef({ top: 0, height: 0, viewport: 0 });++ const rememberPosition = useCallback((container: HTMLDivElement) => {+ positionRef.current = {+ top: container.scrollTop,+ height: container.scrollHeight,+ viewport: container.clientHeight,+ };+ }, []);const pinToBottom = useCallback(() => {const container = containerRef.current;if (!container) return;- // Direct assignment, not ``scrollTo({behavior})``. The browser- // applies it synchronously inside the same layout pass which- // means the user never sees the in-between frame where new- // content has rendered but the scroll position is still stale.container.scrollTop = container.scrollHeight;- }, []);+ rememberPosition(container);+ }, [rememberPosition]);- // Primary pin: runs in layout phase after every render that bumps- // message count / streaming content / events / composer height /- // mount. ``useLayoutEffect`` (not ``useEffect``) is required so the- // assignment happens before the browser paints — otherwise the- // viewer briefly shows the new layout at the old scroll position- // and we observe a flash.useLayoutEffect(() => {- if (!hasMessages || !shouldAutoScrollRef.current) return;- pinToBottom();- }, [- pinToBottom,- hasMessages,- isStreaming,- messageCount,- lastMessageContent,- lastEventCount,- composerHeight,- ]);+ if (hasMessages && shouldAutoScrollRef.current) pinToBottom();+ }, [pinToBottom, hasMessages, isStreaming, messageCount,+ lastMessageContent, lastEventCount, composerHeight]);- // Companion pin: content-change-driven, active ONLY while the turn is- // streaming. ``useLayoutEffect`` above already pins on every page-level- // state change (new delta, new event, new message), but there is a class- // of height growth that doesn't bubble up to the page:- //- // 1. ``useSmoothStreamText`` advances the visible markdown inside- // a child component between WebSocket deltas. Those frames- // grow the inner content but the page's deps don't change, so- // the layout effect above doesn't re-fire on them.- // 2. KaTeX, code blocks, Mermaid, and the late-mount viewer- // ``next/dynamic`` chunks all change the height of the message- // area asynchronously when they finish hydrating mid-stream.- // 3. Images/iframes finishing their network load grow the content- // without mutating the DOM tree at all.- //- // We can't use ``ResizeObserver`` on the scroll container itself because- // it observes border-box, not scrollHeight; overflow growth doesn't fire- // it. This used to be a per-frame rAF loop instead — 60 unconditional- // ``scrollHeight`` reads per second, each a forced synchronous layout of- // the whole transcript, which grew with conversation length and kept the- // main thread busy even in the idle window between the last token and the- // turn's ``done`` event. A MutationObserver (cases 1–2) plus a capture-- // phase ``load`` listener (case 3), coalesced to at most one pin per- // frame, covers the same growth for a cost proportional to actual change.- useEffect(() => {- if (!isStreaming || !hasMessages) return;+ const handleScroll = useCallback(() => {const container = containerRef.current;if (!container) return;- let rafId = 0;- // ``scrollTop`` this effect last pinned. A position below it means the- // user moved up by some means the gesture listeners below don't cover —- // dragging the scrollbar thumb, PageUp/Home, arrow keys — so we release- // the pin instead of yanking them back to the bottom (issue #649).- // Comparing against our own last write (rather than raw ``scrollTop``)- // is what makes this immune to the pin-vs-user fight: content growth- // never lowers ``scrollTop`` (the container opts into- // ``overflow-anchor: none``), so a decrease is always user intent.- let lastPinned: number | null = null;-- const pin = () => {- rafId = 0;- if (!shouldAutoScrollRef.current) return;- if (lastPinned !== null && container.scrollTop < lastPinned - 4) {- shouldAutoScrollRef.current = false;- return;+ const previous = positionRef.current;+ const sameLayout = previous.height === container.scrollHeight &&+ previous.viewport === container.clientHeight;+ // The browser clamps scrollTop when content shrinks. That is not a user+ // gesture. Neither clamping nor delayed growth may release/re-arm follow.+ if (sameLayout) {+ const remaining = container.scrollHeight - container.scrollTop - container.clientHeight;+ if (remaining < 80 && (shouldAutoScrollRef.current || container.scrollTop > previous.top + 4)) {+ shouldAutoScrollRef.current = true;}- container.scrollTop = container.scrollHeight;- lastPinned = container.scrollTop;- };- const schedule = () => {- if (!rafId) rafId = requestAnimationFrame(pin);- };- // The user's own scrolls fire this too; our pins write- // ``scrollTop === lastPinned`` so they never trip the release check.- const onScroll = () => {- if (lastPinned !== null && container.scrollTop < lastPinned - 4) {- shouldAutoScrollRef.current = false;- }- };+ else if (container.scrollTop < previous.top - 4) shouldAutoScrollRef.current = false;+ }+ rememberPosition(container);+ }, [rememberPosition]);- const mo = new MutationObserver(schedule);- mo.observe(container, {- childList: true,- subtree: true,- characterData: true,- });- container.addEventListener("load", schedule, true);- container.addEventListener("scroll", onScroll, { passive: true });- schedule();- return () => {- mo.disconnect();- container.removeEventListener("load", schedule, true);- container.removeEventListener("scroll", onScroll);- if (rafId) cancelAnimationFrame(rafId);- };- }, [isStreaming, hasMessages]);-- // After streaming ends, capability viewers loaded via ``next/dynamic``- // (MathAnimatorViewer, QuizViewer, VisualizationViewer, RichCodeBlock,- // Mermaid …) finish hydrating and grow the content height. The user- // expects to land at the bottom so they see the full result.- //- // The window is intentionally short (4s after stream stop): a longer one- // would mis-classify post-turn user interactions (expanding a trace- // ``<details>``, clicking a citation) as "streaming-style growth" and rip- // the user back to the bottom.- //- // Viewers that tag themselves ``[data-chat-grow]`` are the one exception.- // Their first JS chunk can land after the short window (issue #955),- // leaving the card below the fold until the user scrolls. A *newly- // appearing* tagged node is an unambiguous "this growth is not the user"- // signal, so it — and nothing else — extends the window.- const POST_STREAM_AUTOSCROLL_WINDOW_MS = 4000;- const LATE_VIEWER_AUTOSCROLL_WINDOW_MS = 12_000;useEffect(() => {- if (isStreaming) return;if (!hasMessages) return;-const container = containerRef.current;if (!container) return;-- let prevHeight = container.scrollHeight;let rafId = 0;- let stopTimer = 0;- const startedAt = performance.now();- let deadline = startedAt + POST_STREAM_AUTOSCROLL_WINDOW_MS;- let growTargets = container.querySelectorAll("[data-chat-grow]").length;-- const stop = () => {- mo.disconnect();- container.removeEventListener("load", check, true);- if (rafId) cancelAnimationFrame(rafId);- if (stopTimer) window.clearTimeout(stopTimer);- stopTimer = 0;- };-- // Keep the teardown pinned to whatever the current deadline is, so the- // common case (no late viewer) still stops observing after 4s.- const armStop = () => {- if (stopTimer) window.clearTimeout(stopTimer);- stopTimer = window.setTimeout(- stop,- Math.max(0, deadline - performance.now()),- );- };-- const check = () => {+ const schedule = () => {if (rafId) return;rafId = requestAnimationFrame(() => {rafId = 0;- const tagged = container.querySelectorAll("[data-chat-grow]").length;- if (tagged > growTargets) {- growTargets = tagged;- const extended = startedAt + LATE_VIEWER_AUTOSCROLL_WINDOW_MS;- if (extended > deadline) {- deadline = extended;- armStop();- }- }- if (performance.now() > deadline) return;- const curHeight = container.scrollHeight;- if (curHeight > prevHeight && shouldAutoScrollRef.current) {- pinToBottom();- }- prevHeight = curHeight;+ if (shouldAutoScrollRef.current) pinToBottom();+ else rememberPosition(container);});};-- const mo = new MutationObserver(check);- mo.observe(container, { childList: true, subtree: true });- // An image or iframe finishing its network load grows the content- // without mutating the DOM, so the MutationObserver above never sees- // it — a turn that ends with a generated image would settle just- // above the bottom. The streaming branch already listens for this;- // mirror it here for the window right after the stream stops.- // (Opening a history session is not this path: that effect does not- // re-run on a session switch, so the page re-pins there itself.)- container.addEventListener("load", check, true);- armStop();-- return stop;- }, [hasMessages, isStreaming, pinToBottom]);-- const handleScroll = useCallback(() => {- const container = containerRef.current;- if (!container) return;- const distanceFromBottom =- container.scrollHeight - container.scrollTop - container.clientHeight;- shouldAutoScrollRef.current = distanceFromBottom < 80;- }, []);-- // Intent-based release. During dense streaming the pin above re-snaps to- // ``scrollHeight`` on every content change, so the position-only- // ``handleScroll`` check can rarely observe the user trying to scroll up- // mid-stream: the pin snaps them back to the bottom before the ``scroll``- // event is even handled, so ``distanceFromBottom`` always reads ~0 and the- // pin never releases — the viewport feels frozen. We therefore release the- // pin the instant we see an UPWARD scroll *gesture* (wheel up, or a touch- // drag that pulls earlier content into view), which is unambiguous user- // intent and independent of where the pin has parked the scroll position.- // Once released the pin stops fighting, the user is free to browse, and- // ``handleScroll`` re-arms the pin when they return near the bottom.- useEffect(() => {- const container = containerRef.current;- if (!container) return;-- const release = () => {- shouldAutoScrollRef.current = false;- };-- const onWheel = (event: WheelEvent) => {- if (event.deltaY < 0) release();+ // A scrollport's own box does not grow with scrollHeight. Observe its+ // content children too: main chat has a wrapper, PartnerChat has rows.+ const observed = new Set<Element>();+ const resize = new ResizeObserver(schedule);+ const observeContent = () => {+ const targets = new Set<Element>([container, ...container.children]);+ for (const target of observed) {+ if (!targets.has(target)) { resize.unobserve(target); observed.delete(target); }+ }+ for (const target of targets) {+ if (!observed.has(target)) { resize.observe(target); observed.add(target); }+ }+ schedule();};+ const mutations = new MutationObserver(observeContent);+ mutations.observe(container, { childList: true, subtree: true });+ container.addEventListener("load", schedule, true);+ observeContent();+ const release = () => { shouldAutoScrollRef.current = false; };+ const onWheel = (event: WheelEvent) => { if (event.deltaY < 0) release(); };let touchY = 0;- const onTouchStart = (event: TouchEvent) => {- touchY = event.touches[0]?.clientY ?? 0;- };+ const onTouchStart = (event: TouchEvent) => { touchY = event.touches[0]?.clientY ?? 0; };const onTouchMove = (event: TouchEvent) => {const y = event.touches[0]?.clientY ?? 0;- // Finger dragging downward scrolls the content up (reveals earlier- // messages) — an explicit "let me read back" gesture.if (y - touchY > 4) release();touchY = y;};-+ const onKeyDown = (event: KeyboardEvent) => {+ const target = event.target;+ if (target instanceof Element && target.closest("input,textarea,[contenteditable='true']")) return;+ if (["ArrowUp", "PageUp", "Home"].includes(event.key) || (event.key === " " && event.shiftKey)) release();+ };+ const onPointerDown = (event: PointerEvent) => {+ // Opening a trace/citation is deliberate browsing, not late model output.+ // Sending/answering re-arms follow at the existing caller-owned boundary.+ const target = event.target;+ if (target instanceof Element && target.closest("button,a,summary,[role='button']")) release();+ };container.addEventListener("wheel", onWheel, { passive: true });container.addEventListener("touchstart", onTouchStart, { passive: true });container.addEventListener("touchmove", onTouchMove, { passive: true });+ container.addEventListener("keydown", onKeyDown);+ container.addEventListener("pointerdown", onPointerDown, true);return () => {+ resize.disconnect(); mutations.disconnect();+ container.removeEventListener("load", schedule, true);container.removeEventListener("wheel", onWheel);container.removeEventListener("touchstart", onTouchStart);container.removeEventListener("touchmove", onTouchMove);+ container.removeEventListener("keydown", onKeyDown);+ container.removeEventListener("pointerdown", onPointerDown, true);+ if (rafId) cancelAnimationFrame(rafId);};- // Re-attach when the scroll container (re)mounts — it only exists once- // there are messages to show.- }, [hasMessages]);+ }, [hasMessages, pinToBottom, rememberPosition]);- // ``scrollToBottom`` is preserved as a public escape hatch (e.g. an- // imperative "jump to latest" button) but kept ``instant`` so it- // never animates against an active stream.- const scrollToBottom = useCallback(- (_behavior: ScrollBehavior) => {- void _behavior;- pinToBottom();- },- [pinToBottom],- );+ const scrollToBottom = useCallback((_behavior: ScrollBehavior) => {+ void _behavior;+ pinToBottom();+ }, [pinToBottom]);- return {- containerRef,- endRef,- shouldAutoScrollRef,- scrollToBottom,- handleScroll,- };+ return { containerRef, endRef, shouldAutoScrollRef, scrollToBottom, handleScroll };}diff --git a/web/tests/chat-autoscroll-layout.spec.tsx b/web/tests/chat-autoscroll-layout.spec.tsxnew file mode 100644index 000000000..ca6689e78--- /dev/null+++ b/web/tests/chat-autoscroll-layout.spec.tsx@@ -0,0 +1,115 @@+import { act, fireEvent, render, screen } from "@testing-library/react";+import { afterEach, beforeEach, expect, it, vi } from "vitest";+import { useChatAutoScroll } from "@/hooks/useChatAutoScroll";+import { useLayoutEffect } from "react";++let height: number;+let top: number;+let following: { current: boolean };+let frames: Map<number, FrameRequestCallback>;+let nextFrame: number;+let mutations: Array<() => void>;+let resizes: Array<() => void>;++function flushLayout() {+ act(() => {+ mutations.forEach(callback => callback());+ resizes.forEach(callback => callback());+ const pending = [...frames.values()];+ frames.clear();+ pending.forEach(callback => callback(performance.now()));+ });+}++function Harness({ streaming = true }: { streaming?: boolean }) {+ const { containerRef, endRef, handleScroll, shouldAutoScrollRef } = useChatAutoScroll({ hasMessages: true, isStreaming: streaming,+ composerHeight: 0, messageCount: 2, lastMessageContent: "Reply" });+ useLayoutEffect(() => { following = shouldAutoScrollRef; }, [shouldAutoScrollRef]);+ return <div data-testid="scroll" onScroll={handleScroll} ref={containerRef}>+ <div><p>Question</p><p>Reply</p><button>Open working notes</button><div ref={endRef} /></div>+ </div>;+}++beforeEach(() => {+ height = 1000; top = 0; nextFrame = 0;+ frames = new Map(); mutations = []; resizes = [];+ vi.spyOn(Element.prototype, "clientHeight", "get").mockReturnValue(200);+ vi.spyOn(Element.prototype, "scrollHeight", "get").mockImplementation(() => height);+ vi.spyOn(Element.prototype, "scrollTop", "get").mockImplementation(() => top);+ vi.spyOn(Element.prototype, "scrollTop", "set").mockImplementation(value => {+ top = Math.max(0, Math.min(value, height - 200));+ });+ vi.useFakeTimers();+ vi.stubGlobal("requestAnimationFrame", (callback: FrameRequestCallback) => {+ frames.set(++nextFrame, callback); return nextFrame;+ });+ vi.stubGlobal("cancelAnimationFrame", (id: number) => frames.delete(id));+ vi.stubGlobal("MutationObserver", class {+ callback: () => void;+ constructor(callback: () => void) { this.callback = callback; }+ observe() { mutations.push(this.callback); }+ disconnect() { mutations = mutations.filter(callback => callback !== this.callback); }+ });+ vi.stubGlobal("ResizeObserver", class {+ callback: () => void;+ constructor(callback: () => void) { this.callback = callback; }+ observe() { resizes.push(this.callback); }+ unobserve() {}+ disconnect() { resizes = resizes.filter(callback => callback !== this.callback); }+ });+});+afterEach(() => { vi.useRealTimers(); vi.unstubAllGlobals(); });++it("does not mistake automatic scroll clamping on a collapsing trace for user scrolling", () => {+ render(<Harness />); flushLayout();+ expect(top).toBe(800);+ // The browser clamps scrollTop when a disclosure makes the document shorter.+ height = 500; top = 300;+ fireEvent.scroll(screen.getByTestId("scroll")); flushLayout();+ expect(following.current).toBe(true);+ height = 1400; flushLayout();+ expect(top).toBe(1200);+});++it("keeps the latest messages in view when late content grows after stream settlement", () => {+ render(<Harness streaming={false} />); flushLayout();+ act(() => vi.advanceTimersByTime(15000));+ height = 1800; flushLayout();+ expect(top).toBe(1600);+});++it("does not pull a reader back down after an upward wheel gesture", () => {+ render(<Harness />); flushLayout();+ fireEvent.wheel(screen.getByTestId("scroll"), { deltaY: -20 });+ top = 400; fireEvent.scroll(screen.getByTestId("scroll"));+ height = 1800; flushLayout();+ expect(top).toBe(400);+ expect(following.current).toBe(false);+});++it("recognizes manual scrollbar movement without requiring a wheel gesture", () => {+ render(<Harness />); flushLayout();+ top = 400; fireEvent.scroll(screen.getByTestId("scroll"));+ height = 1800; flushLayout();+ expect(top).toBe(400);+ expect(following.current).toBe(false);+});++it("respects even a small deliberate upward scroll near the live end", () => {+ render(<Harness />); flushLayout();+ fireEvent.wheel(screen.getByTestId("scroll"), { deltaY: -20 });+ top = 780; fireEvent.scroll(screen.getByTestId("scroll"));+ height = 1800; flushLayout();+ expect(top).toBe(780);+ expect(following.current).toBe(false);+ top = 1600; fireEvent.scroll(screen.getByTestId("scroll"));+ expect(following.current).toBe(true);+});++it("does not yank the viewport when the reader opens working notes", () => {+ render(<Harness streaming={false} />); flushLayout();+ fireEvent.pointerDown(screen.getByRole("button", { name: "Open working notes" }));+ height = 1800; flushLayout();+ expect(top).toBe(800);+ expect(following.current).toBe(false);+});diff --git a/web/tests/quiz-autoscroll.test.ts b/web/tests/quiz-autoscroll.test.tsindex c0077a477..afcd728fe 100644--- a/web/tests/quiz-autoscroll.test.ts+++ b/web/tests/quiz-autoscroll.test.ts@@ -16,18 +16,14 @@ test("QuizViewer marks itself as late-growing chat content", () => {assert.match(quizViewer, /data-chat-grow="quiz"/);});-test("the post-stream window extends only for late-mounted viewers", () => {- assert.match(autoScroll, /POST_STREAM_AUTOSCROLL_WINDOW_MS = 4000/);- assert.match(autoScroll, /LATE_VIEWER_AUTOSCROLL_WINDOW_MS = 12_000/);- // The extension must be gated on a newly appearing tagged node, not on one- // merely being present — an old quiz card must not keep re-pinning the user.- assert.match(autoScroll, /\[data-chat-grow\]/);- assert.match(autoScroll, /tagged > growTargets/);+test("late-growing viewers use native content-size observation, not a deadline", () => {+ assert.match(autoScroll, /new ResizeObserver\(schedule\)/);+ assert.match(autoScroll, /container\.children/);+ assert.doesNotMatch(autoScroll, /AUTOSCROLL_WINDOW_MS/);});-test("one post-stream observer owns the pin, not two", () => {- // A second parallel observer would race the first and re-pin post-turn user- // interactions that the short window deliberately excludes.+test("one observer lifecycle owns follow throughout streaming and settlement", () => {const observers = autoScroll.match(/new MutationObserver\(/g) ?? [];- assert.equal(observers.length, 2, "expected one streaming + one post-stream");+ assert.equal(observers.length, 1, "expected one content observer lifecycle");+ assert.match(autoScroll, /pointerdown/);});diff --git a/web/tests/setup/rendered.ts b/web/tests/setup/rendered.tsindex e25ad4b01..592d631ee 100644--- a/web/tests/setup/rendered.ts+++ b/web/tests/setup/rendered.ts@@ -2,6 +2,17 @@ import "@testing-library/jest-dom/vitest";import { cleanup } from "@testing-library/react";import { afterEach, beforeEach, vi } from "vitest";+// jsdom has no layout/ResizeObserver implementation. Geometry-specific tests+// replace this with a controlled observer; unrelated component tests need only+// the browser API shape so mounting the shared scroll hook remains possible.+if (typeof globalThis.ResizeObserver === "undefined") {+ globalThis.ResizeObserver = class {+ observe() {}+ unobserve() {}+ disconnect() {}+ };+}+Object.defineProperty(globalThis, "IS_REACT_ACT_ENVIRONMENT", {configurable: true,value: true,