fix(extension,mcp): improve scroll pin behavior and cap MCP search page

- Use <= threshold in isScrollPinnedToBottom and raise threshold to 160px
- Switch useScrollPinToBottom to useLayoutEffect and direct scrollTop assignment
  to avoid rAF/scrollIntoView jitter during streaming
- Cap SearchContentTool page to MAX_LUCENE_RESULT_WINDOW/MAX_LIMIT (20) to keep
  Lucene collection bounded; reflect constraint in schema and execute clamping
- Add comprehensive hook integration tests and page-clamping unit test

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: lcomplete

app/extension/src/__tests__/sidepanelScrollToBottom.test.ts

@@ -1,18 +1,191 @@
+/** @jest-environment jsdom */
+
+import React from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { act } from "react-dom/test-utils";
 import {
   isScrollPinnedToBottom,
   shouldShowScrollToBottomButton,
 } from "../sidepanel/utils/scrollToBottom";
+import { useScrollPinToBottom } from "../sidepanel/hooks/useScrollPinToBottom";
+
+(
+  globalThis as typeof globalThis & {
+    IS_REACT_ACT_ENVIRONMENT?: boolean;
+  }
+).IS_REACT_ACT_ENVIRONMENT = true;
+
+type ScrollHookSnapshot = {
+  handleScroll: () => void;
+  scrollToBottom: (behavior?: ScrollBehavior) => void;
+};
+
+const TEST_THRESHOLD_PX = 160;
+
+let latestHook: ScrollHookSnapshot | null = null;
+
+function ScrollHarness({ messages }: { messages: string[] }) {
+  const hook = useScrollPinToBottom({
+    messages,
+    thresholdPx: TEST_THRESHOLD_PX,
+  });
+  latestHook = hook;
+
+  return React.createElement(
+    "div",
+    { ref: hook.scrollContainerRef, "data-testid": "scroll-container" },
+    React.createElement(
+      "div",
+      null,
+      React.createElement("div", { ref: hook.messagesEndRef })
+    )
+  );
+}
+
+function renderScrollHarness(messages: string[] = ["hello"]) {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const root = createRoot(container);
+
+  act(() => {
+    root.render(React.createElement(ScrollHarness, { messages }));
+  });
+
+  const scrollContainer = container.querySelector(
+    '[data-testid="scroll-container"]'
+  );
+  if (!(scrollContainer instanceof HTMLDivElement)) {
+    throw new Error("Scroll container not found");
+  }
+
+  return { container, root, scrollContainer };
+}
+
+function rerenderScrollHarness(root: Root, messages: string[]) {
+  act(() => {
+    root.render(React.createElement(ScrollHarness, { messages }));
+  });
+}
+
+function setScrollMetrics(
+  element: HTMLDivElement,
+  metrics: { clientHeight: number; scrollHeight: number; scrollTop: number }
+) {
+  Object.defineProperty(element, "clientHeight", {
+    configurable: true,
+    value: metrics.clientHeight,
+  });
+  Object.defineProperty(element, "scrollHeight", {
+    configurable: true,
+    value: metrics.scrollHeight,
+  });
+  Object.defineProperty(element, "scrollTop", {
+    configurable: true,
+    value: metrics.scrollTop,
+    writable: true,
+  });
+}
+
+function unmount(root: Root, container: HTMLDivElement) {
+  act(() => {
+    root.unmount();
+  });
+  container.remove();
+}
+
+beforeEach(() => {
+  latestHook = null;
+});
+
+afterEach(() => {
+  document.body.innerHTML = "";
+});
 
 describe("sidepanel scroll-to-bottom helpers", () => {
   it("treats positions within the threshold as pinned to the bottom", () => {
     expect(isScrollPinnedToBottom(12, 96)).toBe(true);
     expect(isScrollPinnedToBottom(95, 96)).toBe(true);
-    expect(isScrollPinnedToBottom(96, 96)).toBe(false);
+    expect(isScrollPinnedToBottom(96, 96)).toBe(true);
+    expect(isScrollPinnedToBottom(97, 96)).toBe(false);
   });
 
   it("shows the down-arrow button only when there are messages and the view is not pinned", () => {
     expect(shouldShowScrollToBottomButton(0, false)).toBe(false);
     expect(shouldShowScrollToBottomButton(3, true)).toBe(false);
     expect(shouldShowScrollToBottomButton(3, false)).toBe(true);
   });
-});
+});
+
+describe("useScrollPinToBottom", () => {
+  it("keeps output pinned to the bottom while already at the bottom", () => {
+    const { container, root, scrollContainer } = renderScrollHarness();
+    setScrollMetrics(scrollContainer, {
+      clientHeight: 300,
+      scrollHeight: 720,
+      scrollTop: 420,
+    });
+
+    Object.defineProperty(scrollContainer, "scrollHeight", {
+      configurable: true,
+      value: 900,
+    });
+    rerenderScrollHarness(root, ["hello", "streaming"]);
+
+    expect(scrollContainer.scrollTop).toBe(600);
+    unmount(root, container);
+  });
+
+  it("stops auto-scrolling after the user scrolls away", () => {
+    const { container, root, scrollContainer } = renderScrollHarness();
+    setScrollMetrics(scrollContainer, {
+      clientHeight: 300,
+      scrollHeight: 720,
+      scrollTop: 120,
+    });
+
+    act(() => {
+      latestHook?.handleScroll();
+    });
+
+    Object.defineProperty(scrollContainer, "scrollHeight", {
+      configurable: true,
+      value: 900,
+    });
+    rerenderScrollHarness(root, ["hello", "streaming"]);
+
+    expect(scrollContainer.scrollTop).toBe(120);
+    unmount(root, container);
+  });
+
+  it("resumes auto-scrolling when the user returns near the bottom", () => {
+    const { container, root, scrollContainer } = renderScrollHarness();
+    setScrollMetrics(scrollContainer, {
+      clientHeight: 300,
+      scrollHeight: 720,
+      scrollTop: 120,
+    });
+
+    act(() => {
+      latestHook?.handleScroll();
+    });
+
+    setScrollMetrics(scrollContainer, {
+      clientHeight: 300,
+      scrollHeight: 900,
+      scrollTop: 460,
+    });
+
+    act(() => {
+      latestHook?.handleScroll();
+    });
+
+    Object.defineProperty(scrollContainer, "scrollHeight", {
+      configurable: true,
+      value: 1000,
+    });
+    rerenderScrollHarness(root, ["hello", "streaming"]);
+
+    expect(scrollContainer.scrollTop).toBe(700);
+    unmount(root, container);
+  });
+});

app/extension/src/sidepanel/SidepanelApp.tsx

@@ -140,7 +140,7 @@ function getChromeApi(): ChromeApi | undefined {
   return (globalThis as typeof globalThis & { chrome?: ChromeApi }).chrome;
 }
 
-const SCROLL_PIN_THRESHOLD_PX = 96;
+const SCROLL_PIN_THRESHOLD_PX = 160;
 
 export const SidepanelApp: FC = () => {
   const { t } = useI18n();

app/extension/src/sidepanel/hooks/useScrollPinToBottom.ts

@@ -1,4 +1,10 @@
-import { useCallback, useEffect, useRef, useState, type RefObject } from "react";
+import {
+  useCallback,
+  useLayoutEffect,
+  useRef,
+  useState,
+  type RefObject,
+} from "react";
 
 import {
   isScrollPinnedToBottom,
@@ -39,7 +45,24 @@ export function useScrollPinToBottom<T>(
   const scrollToBottom = useCallback((behavior: ScrollBehavior = "smooth") => {
     pinnedRef.current = true;
     setShowScrollToBottom(false);
-    messagesEndRef.current?.scrollIntoView({ block: "end", behavior });
+
+    const scrollContainer = scrollContainerRef.current;
+    if (!scrollContainer) {
+      messagesEndRef.current?.scrollIntoView({ block: "end", behavior });
+      return;
+    }
+
+    const top = Math.max(
+      scrollContainer.scrollHeight - scrollContainer.clientHeight,
+      0
+    );
+
+    if (behavior === "auto" || typeof scrollContainer.scrollTo !== "function") {
+      scrollContainer.scrollTop = top;
+      return;
+    }
+
+    scrollContainer.scrollTo({ top, behavior });
   }, []);
 
   const handleScroll = useCallback(() => {
@@ -58,7 +81,7 @@ export function useScrollPinToBottom<T>(
     );
   }, [messages.length, thresholdPx]);
 
-  useEffect(() => {
+  useLayoutEffect(() => {
     if (messages.length === 0) {
       pinnedRef.current = true;
       setShowScrollToBottom(false);
@@ -72,8 +95,7 @@ export function useScrollPinToBottom<T>(
       return;
     }
 
-    const frame = window.requestAnimationFrame(() => scrollToBottom("auto"));
-    return () => window.cancelAnimationFrame(frame);
+    scrollToBottom("auto");
   }, [messages, scrollToBottom]);
 
   return {

app/extension/src/sidepanel/utils/scrollToBottom.ts

@@ -2,7 +2,7 @@ export function isScrollPinnedToBottom(
   distanceToBottom: number,
   thresholdPx: number
 ): boolean {
-  return distanceToBottom < thresholdPx;
+  return distanceToBottom <= thresholdPx;
 }
 
 export function shouldShowScrollToBottomButton(

app/server/huntly-server/src/main/java/com/huntly/server/mcp/tool/SearchContentTool.java

@@ -4,6 +4,7 @@
 import com.huntly.interfaces.external.query.SearchQuery;
 import com.huntly.server.mcp.McpUtils;
 import com.huntly.server.service.LuceneService;
+import com.huntly.server.util.PageSizeUtils;
 import org.apache.commons.lang3.StringUtils;
 import org.springframework.stereotype.Component;
 
@@ -19,6 +20,10 @@
 @Component
 public class SearchContentTool implements McpTool {
 
+    private static final int MAX_LIMIT = PageSizeUtils.MAX_PAGE_SIZE;
+    private static final int MAX_LUCENE_RESULT_WINDOW = 10_000;
+    private static final int MAX_PAGE = Math.max(1, MAX_LUCENE_RESULT_WINDOW / MAX_LIMIT);
+
     private final LuceneService luceneService;
     private final McpUtils mcpUtils;
 
@@ -84,14 +89,15 @@ public Map<String, Object> getInputSchema() {
         properties.put("limit", Map.of(
                 "type", "integer",
                 "minimum", 1,
-                "maximum", 500,
+                "maximum", MAX_LIMIT,
                 "description", "Number of results to return, max 500"
         ));
         properties.put("page", Map.of(
                 "type", "integer",
                 "minimum", 1,
+                "maximum", MAX_PAGE,
                 "default", 1,
-                "description", "Page number for search results, starting from 1. Use with limit to inspect additional pages."
+                "description", "Page number for search results, starting from 1. Use with limit to inspect additional pages. Capped to " + MAX_PAGE + " so Lucene collection stays bounded when limit is at its maximum."
         ));
         properties.put("title_only", Map.of(
                 "type", "boolean",
@@ -114,8 +120,8 @@ public Object execute(Map<String, Object> arguments) {
         String startDate = mcpUtils.getStringArg(arguments, "start_date");
         String endDate = mcpUtils.getStringArg(arguments, "end_date");
         String dateField = mcpUtils.getStringArg(arguments, "date_field");
-        int limit = Math.min(Math.max(mcpUtils.getIntArg(arguments, "limit", 50), 1), 500);
-        int page = Math.max(mcpUtils.getIntArg(arguments, "page", 1), 1);
+        int limit = Math.min(Math.max(mcpUtils.getIntArg(arguments, "limit", 50), 1), MAX_LIMIT);
+        int page = Math.min(Math.max(mcpUtils.getIntArg(arguments, "page", 1), 1), MAX_PAGE);
         boolean titleOnly = mcpUtils.getBoolArg(arguments, "title_only", false);
 
         if (StringUtils.isBlank(query)) {

app/server/huntly-server/src/test/java/com/huntly/server/mcp/SearchContentToolTest.java

@@ -29,6 +29,7 @@ void inputSchemaDocumentsAdvancedSearchQuotingAndUnsortedPagination() {
         Map<String, Object> query = asMap(properties.get("query"));
         Map<String, Object> libraryFilter = asMap(properties.get("library_filter"));
         Map<String, Object> dateField = asMap(properties.get("date_field"));
+        Map<String, Object> page = asMap(properties.get("page"));
 
         assertThat(tool.getDescription())
                 .contains("collection:\"Daily Reads\"")
@@ -40,6 +41,7 @@ void inputSchemaDocumentsAdvancedSearchQuotingAndUnsortedPagination() {
         assertThat(properties).containsKeys("start_date", "end_date", "date_field");
         assertThat(asList(dateField.get("enum"))).contains("created_at", "collected_at", "last_read_at");
         assertThat(properties).containsKey("page");
+        assertThat(page.get("maximum")).isEqualTo(20);
     }
 
     @Test
@@ -96,6 +98,31 @@ void executeMapsFiltersAndReturnsPaginationMetadata() {
         assertThat(items).extracting(McpPageItem::getId).containsExactly(7L);
     }
 
+    @Test
+    void executeClampsPageToSafeMaximumForLuceneCollection() {
+        LuceneService luceneService = mock(LuceneService.class);
+        SearchContentTool tool = new SearchContentTool(luceneService, new McpUtils());
+        PageSearchResult searchResult = new PageSearchResult();
+        searchResult.setItems(List.of());
+        when(luceneService.searchPages(any(SearchQuery.class))).thenReturn(searchResult);
+
+        Object rawResponse = tool.execute(Map.of(
+                "query", "machine learning",
+                "limit", 500,
+                "page", Integer.MAX_VALUE
+        ));
+
+        ArgumentCaptor<SearchQuery> queryCaptor = ArgumentCaptor.forClass(SearchQuery.class);
+        verify(luceneService).searchPages(queryCaptor.capture());
+        SearchQuery searchQuery = queryCaptor.getValue();
+        assertThat(searchQuery.getSize()).isEqualTo(500);
+        assertThat(searchQuery.getPage()).isEqualTo(20);
+
+        Map<String, Object> response = asMap(rawResponse);
+        assertThat(response.get("page")).isEqualTo(20);
+        assertThat(response.get("page_size")).isEqualTo(500);
+    }
+
     @SuppressWarnings("unchecked")
     private Map<String, Object> asMap(Object value) {
         return (Map<String, Object>) value;