feat(webapp): pause deployment log auto-scroll on scroll-up (#4776)

Auto-scroll now only follows while you are at the bottom. Scrolling up
pauses it; scrolling back to the bottom, or clicking the new
scroll-to-bottom button in the log header, resumes it. When you are at
the bottom the same button scrolls to the top. Switching to another
deployment starts at the bottom again.

Author: myftija

.server-changes/deployment-logs-follow-scroll.md

@@ -0,0 +1,6 @@
+---
+area: webapp
+type: feature
+---
+
+Deployment logs no longer jump to the bottom while you are reading earlier output. Scroll up to pause auto-scroll, and scroll back down or use the new scroll-to-bottom button in the log header to resume following.

apps/webapp/app/hooks/useFollowScroll.ts

@@ -0,0 +1,100 @@
+import { useEffect, useLayoutEffect, useRef, useState, type RefObject } from "react";
+
+const AT_BOTTOM_TOLERANCE_PX = 4;
+
+type FollowState = {
+  follow: boolean;
+  pinnedScrollTop: number | null;
+  lastScrollTop: number;
+  lastClientHeight: number;
+};
+
+export function useFollowScroll(containerRef: RefObject<HTMLElement | null>, content: unknown) {
+  const [isAtBottom, setIsAtBottom] = useState(true);
+  const stateRef = useRef<FollowState>({
+    follow: true,
+    pinnedScrollTop: null,
+    lastScrollTop: 0,
+    lastClientHeight: 0,
+  });
+
+  useEffect(() => {
+    const container = containerRef.current;
+    if (!container) return;
+
+    const state = stateRef.current;
+    state.lastScrollTop = container.scrollTop;
+    state.lastClientHeight = container.clientHeight;
+
+    const onScroll = () => {
+      const { scrollTop, scrollHeight, clientHeight } = container;
+      const isEcho = scrollTop === state.pinnedScrollTop;
+      const movedUp = scrollTop < state.lastScrollTop && clientHeight <= state.lastClientHeight;
+      state.pinnedScrollTop = null;
+      state.lastScrollTop = scrollTop;
+      state.lastClientHeight = clientHeight;
+      if (isEcho) return;
+
+      state.follow = !movedUp && scrollHeight - scrollTop - clientHeight <= AT_BOTTOM_TOLERANCE_PX;
+      setIsAtBottom(state.follow);
+    };
+
+    const onWheel = (event: WheelEvent) => {
+      if (event.deltaY >= 0 || !canScroll(container)) return;
+      state.follow = false;
+      setIsAtBottom(false);
+    };
+
+    container.addEventListener("scroll", onScroll, { passive: true });
+    container.addEventListener("wheel", onWheel, { passive: true });
+    return () => {
+      container.removeEventListener("scroll", onScroll);
+      container.removeEventListener("wheel", onWheel);
+    };
+  }, [containerRef]);
+
+  useLayoutEffect(() => {
+    const container = containerRef.current;
+    if (container && stateRef.current.follow) pinToBottom(container, stateRef.current);
+  }, [containerRef, isAtBottom, content]);
+
+  useEffect(() => {
+    const container = containerRef.current;
+    if (!container) return;
+
+    const observer = new ResizeObserver(() => {
+      if (stateRef.current.follow) pinToBottom(container, stateRef.current);
+    });
+    observer.observe(container);
+    return () => observer.disconnect();
+  }, [containerRef]);
+
+  const scrollToBottom = () => {
+    const container = containerRef.current;
+    if (!container) return;
+    stateRef.current.follow = true;
+    setIsAtBottom(true);
+    pinToBottom(container, stateRef.current);
+  };
+
+  const scrollToTop = () => {
+    const container = containerRef.current;
+    if (!container || !canScroll(container)) return;
+    stateRef.current.follow = false;
+    setIsAtBottom(false);
+    container.scrollTop = 0;
+  };
+
+  return { isAtBottom, scrollToBottom, scrollToTop };
+}
+
+function pinToBottom(container: HTMLElement, state: FollowState) {
+  container.scrollTop = container.scrollHeight;
+  state.pinnedScrollTop = container.scrollTop;
+  state.lastScrollTop = container.scrollTop;
+  state.lastClientHeight = container.clientHeight;
+}
+
+function canScroll(container: HTMLElement) {
+  return container.scrollHeight - container.clientHeight > AT_BOTTOM_TOLERANCE_PX;
+}

apps/webapp/app/routes/_app.orgs.$organizationSlug.projects.$projectParam.env.$envParam.deployments.$deploymentParam/route.tsx

@@ -13,6 +13,8 @@ import {
   ServerIcon,
 } from "lucide-react";
 import { ExitIcon } from "~/assets/icons/ExitIcon";
+import { MoveToBottomIcon } from "~/assets/icons/MoveToBottomIcon";
+import { MoveToTopIcon } from "~/assets/icons/MoveToTopIcon";
 import { GitMetadata } from "~/components/GitMetadata";
 import { VercelLink } from "~/components/integrations/VercelLink";
 import { RuntimeIcon } from "~/components/RuntimeIcon";
@@ -51,6 +53,7 @@ import { v3DeploymentParams, v3DeploymentsPath, v3RunsPath } from "~/utils/pathB
 import { capitalizeWord } from "~/utils/string";
 import { UserTag } from "../_app.orgs.$organizationSlug.projects.$projectParam.env.$envParam.deployments/route";
 import { useDeploymentLogs } from "~/hooks/useDeploymentLogs";
+import { useFollowScroll } from "~/hooks/useFollowScroll";
 import { type DeploymentLogEntry } from "~/components/runs/v3/deploymentLogsCache";
 import { deploymentAgentPageContext } from "~/components/dashboard-agent/suggested-prompts";
 import type { Handle } from "~/utils/handle";
@@ -307,6 +310,7 @@ export default function Page() {
                 <Property.Item>
                   <Property.Label>Logs</Property.Label>
                   <LogsDisplay
+                    key={deployment.id}
                     logs={logs}
                     isStreaming={isStreaming}
                     streamError={streamError}
@@ -525,19 +529,13 @@ function LogsDisplay({
   const [mouseOver, setMouseOver] = useState(false);
   const [collapsed, setCollapsed] = useState(initialCollapsed);
   const logsContainerRef = useRef<HTMLDivElement>(null);
+  const { isAtBottom, scrollToBottom, scrollToTop } = useFollowScroll(logsContainerRef, logs);
 
   useEffect(() => {
     // oxlint-disable-next-line react/set-state-in-effect, react/no-deriving-state-in-effects -- Deployment status changes intentionally reset the user-controlled collapse state.
     setCollapsed(initialCollapsed);
   }, [initialCollapsed]);
 
-  // auto-scroll log container to bottom when new logs arrive
-  useEffect(() => {
-    if (logsContainerRef.current) {
-      logsContainerRef.current.scrollTop = logsContainerRef.current.scrollHeight;
-    }
-  }, [logs]);
-
   const onCopyLogs = useCallback(
     (event: React.MouseEvent<HTMLButtonElement>) => {
       event.preventDefault();
@@ -584,6 +582,27 @@ function LogsDisplay({
         </div>
         {logs.length > 0 && (
           <div className="flex items-center gap-3">
+            <TooltipProvider>
+              <Tooltip disableHoverableContent>
+                <TooltipTrigger
+                  onClick={isAtBottom ? scrollToTop : scrollToBottom}
+                  className={cn(
+                    "transition-colors duration-100 focus-custom hover:cursor-pointer",
+                    "text-text-dimmed hover:text-text-bright"
+                  )}
+                >
+                  {isAtBottom ? (
+                    <MoveToTopIcon className="size-4" />
+                  ) : (
+                    <MoveToBottomIcon className="size-4" />
+                  )}
+                </TooltipTrigger>
+                <TooltipContent side="left" className="text-xs">
+                  {isAtBottom ? "Scroll to top" : "Scroll to bottom"}
+                </TooltipContent>
+              </Tooltip>
+            </TooltipProvider>
+
             <TooltipProvider>
               <Tooltip open={copied || mouseOver} disableHoverableContent>
                 <TooltipTrigger