Stage 325: PR #1929 — feat: add opt-in session endless scroll by @ai-ag2026

Conflict resolution: both #1928 (session jump buttons) and #1929 (endless
scroll) add their own settings/UI/i18n keys. Resolved by keeping both —
the features are independent opt-in toggles.

api/config.py

@@ -3683,6 +3683,7 @@ _SETTINGS_DEFAULTS = {
     "skin": "default",  # accent color skin: default | ares | mono | slate | poseidon | sisyphus | charizard
     "font_size": "default",  # small | default | large
     "session_jump_buttons": False,  # show Start/End transcript jump pills
+    "session_endless_scroll": False,  # auto-load older transcript pages while scrolling upward
     "language": "en",  # UI locale code; must match a key in static/i18n.js LOCALES
     "bot_name": os.getenv(
         "HERMES_WEBUI_BOT_NAME", "Hermes"
@@ -3812,6 +3813,7 @@ _SETTINGS_BOOL_KEYS = {
     "simplified_tool_calling",
     "api_redact_enabled",
     "session_jump_buttons",
+    "session_endless_scroll",
 }
 # Language codes are validated as short alphanumeric BCP-47-like tags (e.g. 'en', 'zh', 'fr')
 _SETTINGS_LANG_RE = __import__("re").compile(r"^[a-zA-Z]{2,10}(-[a-zA-Z0-9]{2,8})?$")

static/boot.js

@@ -1310,6 +1310,7 @@ function applyBotName(){
     window._simplifiedToolCalling=s.simplified_tool_calling!==false;
     window._sidebarDensity=(s.sidebar_density==='detailed'?'detailed':'compact');
     window._busyInputMode=(s.busy_input_mode||'queue');
+    window._sessionEndlessScrollEnabled=!!s.session_endless_scroll;
     window._botName=s.bot_name||'Hermes';
     if(s.default_model) window._defaultModel=s.default_model;
     // Persist default workspace so the blank new-chat page can show it
@@ -1346,6 +1347,7 @@ function applyBotName(){
     window._sessionJumpButtonsEnabled=false;
     window._sidebarDensity='compact';
     window._busyInputMode='queue';
+    window._sessionEndlessScrollEnabled=false;
     window._botName='Hermes';
     _bootSettings={check_for_updates:false};
     if(typeof setLocale==='function'){

static/i18n.js

@@ -434,6 +434,10 @@ const LOCALES = {
     settings_desc_workspace_panel_open: 'When enabled, the workspace / file browser panel opens automatically with each new session. You can still close it manually at any time.',
     settings_label_session_jump_buttons: 'Show session jump buttons',
     settings_desc_session_jump_buttons: 'Show floating Start and End buttons while reading long session histories.',
+
+    settings_label_session_endless_scroll: 'Load older messages while scrolling up',
+
+    settings_desc_session_endless_scroll: 'When enabled, older messages load automatically as you scroll upward. When disabled, use the older-messages button.',
     open_in_browser: 'Open in browser',
     settings_dropdown_conversation: 'Conversation',
     settings_dropdown_appearance: 'Appearance',
@@ -1468,6 +1472,10 @@ const LOCALES = {
     settings_desc_workspace_panel_open: '有効にすると、新しいセッションごとにワークスペース/ファイルブラウザパネルが自動で開きます。手動でいつでも閉じられます。',
     settings_label_session_jump_buttons: 'Show session jump buttons',
     settings_desc_session_jump_buttons: 'Show floating Start and End buttons while reading long session histories.',
+
+    settings_label_session_endless_scroll: '上スクロールで古いメッセージを読み込む',
+
+    settings_desc_session_endless_scroll: '有効にすると、上にスクロールしたとき古いメッセージを自動で読み込みます。無効の場合は古いメッセージボタンを使います。',
     open_in_browser: 'ブラウザで開く',
     settings_dropdown_conversation: '会話',
     settings_dropdown_appearance: '外観',
@@ -2919,6 +2927,10 @@ const LOCALES = {
     settings_desc_workspace_panel_open: 'При включении панель файлов будет открываться автоматически в каждой новой сессии.',
     settings_label_session_jump_buttons: 'Show session jump buttons',
     settings_desc_session_jump_buttons: 'Show floating Start and End buttons while reading long session histories.',
+
+    settings_label_session_endless_scroll: 'Загружать старые сообщения при прокрутке вверх',
+
+    settings_desc_session_endless_scroll: 'Если включено, старые сообщения загружаются автоматически при прокрутке вверх. Если выключено, используйте кнопку загрузки старых сообщений.',
     open_in_browser: 'Открыть в браузере',
     settings_section_system_title: 'System',
     settings_tab_appearance: 'Appearance',
@@ -3875,6 +3887,10 @@ const LOCALES = {
     settings_desc_workspace_panel_open: 'Al activar, el panel de archivos se abre automáticamente en cada nueva sesión. Aún puedes cerrarlo manualmente.',
     settings_label_session_jump_buttons: 'Show session jump buttons',
     settings_desc_session_jump_buttons: 'Show floating Start and End buttons while reading long session histories.',
+
+    settings_label_session_endless_scroll: 'Cargar mensajes antiguos al desplazarse hacia arriba',
+
+    settings_desc_session_endless_scroll: 'Si está activado, los mensajes antiguos se cargan automáticamente al desplazarte hacia arriba. Si está desactivado, usa el botón de mensajes antiguos.',
     open_in_browser: 'Abrir en el navegador',
     settings_section_system_title: 'System',
     settings_tab_appearance: 'Appearance',
@@ -4577,6 +4593,10 @@ const LOCALES = {
     settings_label_session_jump_buttons: 'Show session jump buttons',
     settings_desc_session_jump_buttons: 'Show floating Start and End buttons while reading long session histories.',
 
+    settings_label_session_endless_scroll: 'Ältere Nachrichten beim Hochscrollen laden',
+
+    settings_desc_session_endless_scroll: 'Wenn aktiviert, werden ältere Nachrichten beim Hochscrollen automatisch geladen. Wenn deaktiviert, nutzt du den Button für ältere Nachrichten.',
+
     workspace_drag_hint: 'Ziehen zum Neuordnen',
     workspace_reorder_failed: 'Neuordnen fehlgeschlagen',
     open_in_browser: 'Im Browser öffnen',
@@ -5808,6 +5828,10 @@ const LOCALES = {
     settings_desc_workspace_panel_open: '启用后，工作区/文件浏览器面板会在每次新会话时自动打开。您仍可随时手动关闭。',
     settings_label_session_jump_buttons: 'Show session jump buttons',
     settings_desc_session_jump_buttons: 'Show floating Start and End buttons while reading long session histories.',
+
+    settings_label_session_endless_scroll: '向上滚动时加载更早的消息',
+
+    settings_desc_session_endless_scroll: '启用后，向上滚动时会自动加载更早的消息。禁用时请使用加载更早消息按钮。',
     open_in_browser: '在浏览器中打开',
     settings_section_system_title: 'System',
     settings_tab_appearance: 'Appearance',
@@ -6220,6 +6244,10 @@ const LOCALES = {
     settings_desc_workspace_panel_open: '啟用後，工作區/檔案瀏覽器面板會在每次新會話時自動開啓。您仍可隨時手動關閉。',
     settings_label_session_jump_buttons: 'Show session jump buttons',
     settings_desc_session_jump_buttons: 'Show floating Start and End buttons while reading long session histories.',
+
+    settings_label_session_endless_scroll: '向上捲動時載入較早訊息',
+
+    settings_desc_session_endless_scroll: '啟用後，向上捲動時會自動載入較早訊息。停用時請使用載入較早訊息按鈕。',
     open_in_browser: '在瀏覽器中開啓',
     settings_dropdown_conversation: '對話',
     settings_dropdown_appearance: '外觀',
@@ -7271,6 +7299,10 @@ const LOCALES = {
     settings_desc_workspace_panel_open: 'Quando ativo, o painel workspace abre automaticamente com cada nova sessão.',
     settings_label_session_jump_buttons: 'Show session jump buttons',
     settings_desc_session_jump_buttons: 'Show floating Start and End buttons while reading long session histories.',
+
+    settings_label_session_endless_scroll: 'Carregar mensagens antigas ao rolar para cima',
+
+    settings_desc_session_endless_scroll: 'Quando ativado, mensagens antigas carregam automaticamente ao rolar para cima. Quando desativado, use o botão de mensagens antigas.',
     open_in_browser: 'Abrir no navegador',
     settings_dropdown_conversation: 'Conversa',
     settings_dropdown_appearance: 'Aparência',
@@ -8203,6 +8235,10 @@ const LOCALES = {
     settings_desc_workspace_panel_open: '활성화하면 새 세션마다 워크스페이스/파일 브라우저 패널이 자동으로 열립니다. 언제든지 수동으로 닫을 수 있습니다.',
     settings_label_session_jump_buttons: 'Show session jump buttons',
     settings_desc_session_jump_buttons: 'Show floating Start and End buttons while reading long session histories.',
+
+    settings_label_session_endless_scroll: '위로 스크롤할 때 이전 메시지 불러오기',
+
+    settings_desc_session_endless_scroll: '활성화하면 위로 스크롤할 때 이전 메시지를 자동으로 불러옵니다. 비활성화하면 이전 메시지 버튼을 사용합니다.',
     open_in_browser: '브라우저에서 열기',
     settings_dropdown_conversation: '대화',
     settings_dropdown_appearance: '외형',

static/index.html

@@ -878,6 +878,10 @@
                 <span data-i18n="settings_label_session_jump_buttons">Show session jump buttons</span>
               </label>
               <div style="font-size:11px;color:var(--muted);margin-top:4px" data-i18n="settings_desc_session_jump_buttons">Show floating Start and End buttons while reading long session histories.</div>
+                <input type="checkbox" id="settingsSessionEndlessScroll" style="width:15px;height:15px;accent-color:var(--accent)">
+                <span data-i18n="settings_label_session_endless_scroll">Load older messages while scrolling up</span>
+              </label>
+              <div style="font-size:11px;color:var(--muted);margin-top:4px" data-i18n="settings_desc_session_endless_scroll">When enabled, older messages load automatically as you scroll upward. When disabled, use the older-messages button.</div>
             </div>
             <div id="settingsAppearanceAutosaveStatus" class="settings-autosave-status" aria-live="polite"></div>
           </div>

static/panels.js

@@ -4252,6 +4252,7 @@ function _appearancePayloadFromUi(){
     skin: ($('settingsSkin')||{}).value || localStorage.getItem('hermes-skin') || 'default',
     font_size: ($('settingsFontSize')||{}).value || localStorage.getItem('hermes-font-size') || 'default',
     session_jump_buttons: !!($('settingsSessionJumpButtons')||{}).checked,
+    session_endless_scroll: !!($('settingsSessionEndlessScroll')||{}).checked,
   };
 }
 
@@ -4303,6 +4304,7 @@ async function _autosaveAppearanceSettings(payload){
       window._sessionJumpButtonsEnabled=!!saved.session_jump_buttons;
       if(typeof _applySessionNavigationPrefs==='function') _applySessionNavigationPrefs();
     }
+    window._sessionEndlessScrollEnabled=!!(saved&&saved.session_endless_scroll);
     _setAppearanceAutosaveStatus('saved');
   }catch(e){
     console.warn('[settings] appearance autosave failed', e);
@@ -4486,6 +4488,15 @@ async function loadSettingsPanel(){
         else if(!open&&_workspacePanelMode!=='closed') toggleWorkspacePanel(false);
       };
     }
+    const endlessScrollCb=$('settingsSessionEndlessScroll');
+    if(endlessScrollCb){
+      endlessScrollCb.checked=!!settings.session_endless_scroll;
+      window._sessionEndlessScrollEnabled=endlessScrollCb.checked;
+      endlessScrollCb.onchange=function(){
+        window._sessionEndlessScrollEnabled=this.checked;
+        _scheduleAppearanceAutosave();
+      };
+    }
     const resolvedLanguage=(typeof resolvePreferredLocale==='function')
       ? resolvePreferredLocale(settings.language, localStorage.getItem('hermes-lang'))
       : (settings.language || localStorage.getItem('hermes-lang') || 'en');
@@ -5144,6 +5155,7 @@ function _applySavedSettingsUi(saved, body, opts){
   if(typeof _applySessionNavigationPrefs==='function') _applySessionNavigationPrefs();
   window._sidebarDensity=sidebarDensity==='detailed'?'detailed':'compact';
   window._busyInputMode=body.busy_input_mode||'queue';
+  window._sessionEndlessScrollEnabled=!!body.session_endless_scroll;
   window._botName=body.bot_name||'Hermes';
   if(typeof applyBotName==='function') applyBotName();
   if(typeof setLocale==='function') setLocale(language);
@@ -5240,6 +5252,7 @@ async function saveSettings(andClose){
   body.skin=skin;
   body.font_size=fontSize;
   body.session_jump_buttons=!!($('settingsSessionJumpButtons')||{}).checked;
+  body.session_endless_scroll=!!($('settingsSessionEndlessScroll')||{}).checked;
   body.language=language;
   body.show_token_usage=showTokenUsage;
   body.show_tps=showTps;

static/ui.js

@@ -284,6 +284,9 @@ function _messageRenderableMessageCount(){
 function _messageHiddenBeforeCount(){
   return Math.max(0,_messageRenderableMessageCount()-_currentMessageRenderWindowSize());
 }
+function _isSessionEndlessScrollEnabled(){
+  return window._sessionEndlessScrollEnabled===true;
+}
 function _wireMessageWindowLoadEarlierButton(){
   const indicator=$('loadOlderIndicator');
   if(!indicator) return;
@@ -1716,8 +1719,11 @@ if (typeof window !== 'undefined') window._resetScrollDirectionTracker = _resetS
       const btn=$('scrollToBottomBtn');
       if(btn) btn.style.display=_scrollPinned?'none':'flex';
       if(typeof _updateSessionStartJumpButton==='function') _updateSessionStartJumpButton();
-      // Load older messages when scrolled near the top
-      if(el.scrollTop<80 && typeof _messagesTruncated!=='undefined' && _messagesTruncated && typeof _loadOlderMessages==='function'){
+      // Prefetch older messages before the reader hits the hard top. Prepending
+      // then preserving scrollTop is seamless only if there is runway left for
+      // the user's continued upward wheel/touch movement.
+      const olderPrefetchPx=Math.max(600,el.clientHeight*1.5);
+      if(_isSessionEndlessScrollEnabled()&&el.scrollTop<olderPrefetchPx && typeof _messagesTruncated!=='undefined' && _messagesTruncated && typeof _loadOlderMessages==='function'){
         _loadOlderMessages();
       }
     });

tests/test_parallel_session_switch.py

@@ -427,10 +427,11 @@ class TestMessagePaginationFrontend:
         assert "async function _ensureAllMessagesLoaded" in SESSIONS_JS
 
     def test_scroll_to_top_triggers_loading(self):
-        """Scroll event handler must trigger _loadOlderMessages near top."""
+        """Scroll event handler must trigger _loadOlderMessages near top when opt-in is enabled."""
         UI_JS = (REPO / "static" / "ui.js").read_text(encoding="utf-8")
 
-        assert "el.scrollTop<80" in UI_JS
+        assert "const olderPrefetchPx=Math.max(600,el.clientHeight*1.5)" in UI_JS
+        assert "_isSessionEndlessScrollEnabled()&&el.scrollTop<olderPrefetchPx" in UI_JS
         assert "_loadOlderMessages" in UI_JS
 
     def test_load_older_indicator_in_render(self):

tests/test_session_endless_scroll.py

@@ -0,0 +1,32 @@
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+CONFIG_PY = (ROOT / "api" / "config.py").read_text(encoding="utf-8")
+BOOT_JS = (ROOT / "static" / "boot.js").read_text(encoding="utf-8")
+INDEX_HTML = (ROOT / "static" / "index.html").read_text(encoding="utf-8")
+PANELS_JS = (ROOT / "static" / "panels.js").read_text(encoding="utf-8")
+UI_JS = (ROOT / "static" / "ui.js").read_text(encoding="utf-8")
+I18N_JS = (ROOT / "static" / "i18n.js").read_text(encoding="utf-8")
+
+
+def test_endless_scroll_is_opt_in_setting():
+    assert '"session_endless_scroll": False' in CONFIG_PY
+    assert '"session_endless_scroll"' in CONFIG_PY
+    assert 'id="settingsSessionEndlessScroll"' in INDEX_HTML
+    assert 'data-i18n="settings_label_session_endless_scroll"' in INDEX_HTML
+    assert 'data-i18n="settings_desc_session_endless_scroll"' in INDEX_HTML
+    assert "session_endless_scroll: !!($('settingsSessionEndlessScroll')||{}).checked" in PANELS_JS
+    assert "window._sessionEndlessScrollEnabled=!!s.session_endless_scroll" in BOOT_JS
+    assert "window._sessionEndlessScrollEnabled=false" in BOOT_JS
+
+
+def test_scroll_listener_prefetches_older_messages_only_when_enabled():
+    assert "function _isSessionEndlessScrollEnabled" in UI_JS
+    assert "const olderPrefetchPx=Math.max(600,el.clientHeight*1.5)" in UI_JS
+    assert "_isSessionEndlessScrollEnabled()&&el.scrollTop<olderPrefetchPx" in UI_JS
+    assert "el.scrollTop<80 && typeof _messagesTruncated" not in UI_JS
+
+
+def test_endless_scroll_i18n_keys_exist_for_each_locale():
+    assert I18N_JS.count("settings_label_session_endless_scroll") == I18N_JS.count("settings_label_workspace_panel_open")
+    assert I18N_JS.count("settings_desc_session_endless_scroll") == I18N_JS.count("settings_desc_workspace_panel_open")