From d2613e7065676142e6e883d25e0af36e1d8077bb Mon Sep 17 00:00:00 2001
From: jarvis24young <749843026@qq.com>
Date: Fri, 22 May 2026 09:17:59 +0800
Subject: [PATCH] feat(mobile-web): add scroll-to-bottom floating button

A floating button appears when the user scrolls up from the message list.
Tapping it smoothly scrolls back to the latest messages. Uses
programmaticScrollRef guard and ref-based change detection to suppress
button flicker during auto-scroll (new messages, streaming updates).
---
 src/mobile-web/src/i18n/messages.ts           |  3 ++
 src/mobile-web/src/pages/ChatPage.tsx         | 42 ++++++++++++++++-
 .../src/styles/components/chat.scss           | 46 +++++++++++++++++++
 3 files changed, 90 insertions(+), 1 deletion(-)

diff --git a/src/mobile-web/src/i18n/messages.ts b/src/mobile-web/src/i18n/messages.ts
index 5df952386..c050f6f8e 100644
--- a/src/mobile-web/src/i18n/messages.ts
+++ b/src/mobile-web/src/i18n/messages.ts
@@ -143,6 +143,7 @@ export const messages: Record<MobileLanguage, MessageTree> = {
       fileDownloading: 'Downloading...',
       fileDownloaded: 'Downloaded',
       clickToDownload: 'Click to download',
+      scrollToBottom: 'Scroll to bottom',
     },
     tools: {
       explore: 'Explore',
@@ -297,6 +298,7 @@ export const messages: Record<MobileLanguage, MessageTree> = {
       fileDownloading: '下载中...',
       fileDownloaded: '已下载',
       clickToDownload: '点击下载',
+      scrollToBottom: '滚动到底部',
     },
     tools: {
       explore: '探索',
@@ -451,6 +453,7 @@ export const messages: Record<MobileLanguage, MessageTree> = {
       fileDownloading: '下載中...',
       fileDownloaded: '已下載',
       clickToDownload: '點擊下載',
+      scrollToBottom: '捲動到底部',
     },
     tools: {
       explore: '探索',
diff --git a/src/mobile-web/src/pages/ChatPage.tsx b/src/mobile-web/src/pages/ChatPage.tsx
index 538fad9f0..992f23e51 100644
--- a/src/mobile-web/src/pages/ChatPage.tsx
+++ b/src/mobile-web/src/pages/ChatPage.tsx
@@ -2001,6 +2001,7 @@ const ChatPage: React.FC<ChatPageProps> = ({ sessionMgr, sessionId, sessionName,
   const messagesContainerRef = useRef<HTMLDivElement>(null);
   const [expandedMsgIds, setExpandedMsgIds] = useState<Set<string>>(new Set());
   const [infoToast, setInfoToast] = useState<string | null>(null);
+  const [showScrollToBottom, setShowScrollToBottom] = useState(false);
 
   const isStreaming = activeTurn != null && activeTurn.status === 'active';
 
@@ -2137,6 +2138,8 @@ const ChatPage: React.FC<ChatPageProps> = ({ sessionMgr, sessionId, sessionName,
   }, [sessionMgr, sessionId, setMessages, setError, getMessages]);
 
   const isNearBottomRef = useRef(true);
+  const programmaticScrollRef = useRef(false);
+  const lastShowScrollToBottomRef = useRef(false);
   const BOTTOM_THRESHOLD = 80;
 
   const handleScroll = useCallback(() => {
@@ -2144,7 +2147,18 @@ const ChatPage: React.FC<ChatPageProps> = ({ sessionMgr, sessionId, sessionName,
     if (!container) return;
 
     const gap = container.scrollHeight - container.scrollTop - container.clientHeight;
-    isNearBottomRef.current = gap < BOTTOM_THRESHOLD;
+    const nearBottom = gap < BOTTOM_THRESHOLD;
+    isNearBottomRef.current = nearBottom;
+    if (nearBottom) {
+      programmaticScrollRef.current = false;
+    }
+    if (!programmaticScrollRef.current) {
+      const show = !nearBottom;
+      if (show !== lastShowScrollToBottomRef.current) {
+        lastShowScrollToBottomRef.current = show;
+        setShowScrollToBottom(show);
+      }
+    }
 
     if (container.scrollTop < 100 && hasMore && !isLoadingMore) {
       const msgs = getMessages(sessionId);
@@ -2152,6 +2166,14 @@ const ChatPage: React.FC<ChatPageProps> = ({ sessionMgr, sessionId, sessionName,
     }
   }, [hasMore, isLoadingMore, getMessages, sessionId, loadMessages]);
 
+  const scrollToBottom = useCallback(() => {
+    programmaticScrollRef.current = true;
+    isNearBottomRef.current = true;
+    setShowScrollToBottom(false);
+    lastShowScrollToBottomRef.current = false;
+    messagesEndRef.current?.scrollIntoView({ behavior: 'smooth' });
+  }, []);
+
   // Initial load + start poller
   const initialScrollDone = useRef(false);
   const pendingInitialScroll = useRef(false);
@@ -2231,6 +2253,7 @@ const ChatPage: React.FC<ChatPageProps> = ({ sessionMgr, sessionId, sessionName,
       const isNewAppend = messages.length > prevMsgCountRef.current;
       prevMsgCountRef.current = messages.length;
       if (isNewAppend && !isLoadingMore && isNearBottomRef.current) {
+        programmaticScrollRef.current = true;
         messagesEndRef.current?.scrollIntoView({ behavior: 'smooth' });
       }
     }
@@ -2239,11 +2262,13 @@ const ChatPage: React.FC<ChatPageProps> = ({ sessionMgr, sessionId, sessionName,
   useEffect(() => {
     if (!initialScrollDone.current || !isStreaming) return;
     if (!isNearBottomRef.current) return;
+    programmaticScrollRef.current = true;
     messagesEndRef.current?.scrollIntoView({ behavior: 'auto' });
   }, [activeTurn, isStreaming]);
 
   useEffect(() => {
     if (optimisticMsg) {
+      programmaticScrollRef.current = true;
       isNearBottomRef.current = true;
       messagesEndRef.current?.scrollIntoView({ behavior: 'smooth' });
     }
@@ -2257,6 +2282,7 @@ const ChatPage: React.FC<ChatPageProps> = ({ sessionMgr, sessionId, sessionName,
       if (!isNearBottomRef.current) return;
       const gap = container.scrollHeight - container.scrollTop - container.clientHeight;
       if (gap > 10 && gap < 400) {
+        programmaticScrollRef.current = true;
         container.scrollTo({ top: container.scrollHeight, behavior: 'smooth' });
       }
     }, 300);
@@ -2692,8 +2718,22 @@ const ChatPage: React.FC<ChatPageProps> = ({ sessionMgr, sessionId, sessionName,
         )}
 
         <div ref={messagesEndRef} />
+
       </div>
 
+      {showScrollToBottom && (
+        <button
+          type="button"
+          className="chat-page__scroll-to-bottom"
+          onClick={scrollToBottom}
+          aria-label={t('chat.scrollToBottom')}
+        >
+          <svg aria-hidden="true" focusable="false" width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+            <polyline points="6 9 12 15 18 9" />
+          </svg>
+        </button>
+      )}
+
       {/* Floating Input Bar — two-stage (matches desktop ChatInput) */}
       <input
         ref={fileInputRef}
diff --git a/src/mobile-web/src/styles/components/chat.scss b/src/mobile-web/src/styles/components/chat.scss
index 60246b57a..499983f39 100644
--- a/src/mobile-web/src/styles/components/chat.scss
+++ b/src/mobile-web/src/styles/components/chat.scss
@@ -133,6 +133,7 @@
   display: flex;
   flex-direction: column;
   gap: var(--size-gap-4);
+  position: relative;
 }
 
 .chat-page__load-more-indicator {
@@ -142,6 +143,51 @@
   padding: var(--size-gap-2) 0;
 }
 
+.chat-page__scroll-to-bottom {
+  position: fixed;
+  bottom: 110px;
+  left: 50%;
+  transform: translateX(-50%);
+  width: 40px;
+  height: 40px;
+  border-radius: 50%;
+  border: 1px solid var(--border-subtle);
+  background: var(--color-bg-elevated);
+  color: var(--color-text-primary);
+  box-shadow: var(--shadow-md);
+  cursor: pointer;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  z-index: 15;
+  animation: scrollBtnIn 200ms var(--easing-standard);
+
+  &:active {
+    transform: translateX(-50%) scale(0.92);
+    box-shadow: var(--shadow-sm);
+  }
+
+  &:focus-visible {
+    outline: 2px solid var(--color-accent-500);
+    outline-offset: 2px;
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    animation: none;
+  }
+
+  @media (forced-colors: active) {
+    border: 2px solid ButtonText;
+    background: ButtonFace;
+    color: ButtonText;
+  }
+}
+
+@keyframes scrollBtnIn {
+  from { opacity: 0; transform: translateX(-50%) scale(0.7); }
+  to   { opacity: 1; transform: translateX(-50%) scale(1); }
+}
+
 // Message items — FlowChat style (no bubbles)
 .chat-msg {
   display: flex;