fix(cli): preserve scroll position and partition pending height budget - #29520

📊 PR Size: size/L

• Lines changed: 628
• Additions: +542
• Deletions: -86
• Files changed: 7

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request improves the stability and predictability of the Gemini CLI user interface. By refining how the terminal handles scroll positions, layout height budgets, and keyboard navigation, it ensures that users can interact with tools and review conversation history without the viewport unexpectedly resetting or collapsing.

Highlights

• Scroll Preservation: Updated the virtualized list to only auto-scroll to the bottom when the user is already pinned to the bottom, preventing unexpected jumps when reviewing history.
• Layout Budgeting: Implemented a height partitioning strategy in the standard buffer to allocate space between pending history items and the tool confirmation queue, preventing UI overflow.
• Navigation Stability: Restricted unconstrained height mode toggling so that standard navigation keys no longer trigger layout collapses, reserving this behavior for explicit commands.

/gemini review

/gemini review

/gemini review

/gemini review

/gemini review

/gemini review

Findings

🔴 Critical: Scroll Preservation Guard is Bypassed in Production by Composer.tsx

While the check in packages/cli/src/ui/components/MainContent.tsx correctly checks whether the user is at the bottom:

useEffect(() => {
  if (showConfirmationQueue && scrollableListRef.current) {
    const scrollState = scrollableListRef.current.getScrollState?.();
    const isAtBottom = scrollState
      ? scrollState.scrollHeight -
          scrollState.innerHeight -
          scrollState.scrollTop <=
        1
      : true;
    if (isAtBottom) {
      scrollableListRef.current.scrollToEnd();
    }
  }
}, [showConfirmationQueue, confirmingToolCallId]);

There is an active second path in packages/cli/src/ui/components/Composer.tsx (lines 61–65):

useEffect(() => {
  if (hasPendingActionRequired) {
    appEvents.emit(AppEvent.ScrollToBottom);
  }
}, [hasPendingActionRequired]);

Where hasPendingActionRequired is computed by useComposerStatus (lines 25–39) as:

const hasPendingToolConfirmation = useMemo(
  () =>
    (uiState.pendingHistoryItems ?? [])
      .filter((item): item is HistoryItemToolGroup => item.type === 'tool_group')
      .some((item) => item.tools.some((tool) => tool.status === CoreToolCallStatus.AwaitingApproval)),
  [uiState.pendingHistoryItems],
);

const hasPendingActionRequired =
  hasPendingToolConfirmation || ...

And MainContent.tsx listens to AppEvent.ScrollToBottom directly (lines 89–97):

useEffect(() => {
  const handleScroll = () => {
    scrollableListRef.current?.scrollToEnd();
  };
  appEvents.on(AppEvent.ScrollToBottom, handleScroll);
  return () => {
    appEvents.off(AppEvent.ScrollToBottom, handleScroll);
  };
}, []);

Impact:
When Composer and MainContent are mounted together in the app layout (e.g. DefaultAppLayout), any tool confirmation arriving sets hasPendingToolConfirmation = true, which sets hasPendingActionRequired = true. Composer immediately emits AppEvent.ScrollToBottom, and MainContent's handleScroll handler unconditionally calls scrollToEnd(), completely overriding the isAtBottom guard in MainContent.

The unit test in MainContent.test.tsx passed because it renders <MainContent /> in isolation without <Composer />.

Recommendation:
Prevent Composer.tsx from emitting AppEvent.ScrollToBottom when the pending action is a tool confirmation (since MainContent manages its own confirmation queue scroll positioning), or make handleScroll in MainContent also respect isAtBottom.

🟡 Improvements

1. Dead variable in AppContainer.tsx (enteringConstrainHeightMode):
   In packages/cli/src/ui/AppContainer.tsx (lines 1917–1932):

   let enteringConstrainHeightMode = false;
   if (
     !constrainHeight &&
     (keyMatchers[Command.SHOW_MORE_LINES](key) ||
       (keyMatchers[Command.ESCAPE](key) && !dialogsVisible))
   ) {
     enteringConstrainHeightMode = true;
     setConstrainHeight(true);
     if (keyMatchers[Command.SHOW_MORE_LINES](key)) {
       toggleLastTurnTools();
     }
     if (!isAlternateBuffer) {
       refreshStatic();
     }
     return true;
   }

   Because this block returns return true;, execution never continues down to line 1972 (keyMatchers[Command.SHOW_MORE_LINES](key) && !enteringConstrainHeightMode) when enteringConstrainHeightMode is true. When execution does reach line 1972, enteringConstrainHeightMode is guaranteed to be false.
   Suggestion: Remove let enteringConstrainHeightMode = false; and simplify line 1972 to keyMatchers[Command.SHOW_MORE_LINES](key).

2. Integration Test Coverage for Composer + MainContent Interaction:
   Add a test that renders both MainContent and Composer (or verifies that AppEvent.ScrollToBottom is not emitted on tool confirmation when scrolled up) to ensure regressions do not re-introduce scroll resets.

Findings

🔴 Critical: Scroll Preservation Guard is Bypassed in Production by Composer.tsx

While the check in packages/cli/src/ui/components/MainContent.tsx correctly checks whether the user is at the bottom:

useEffect(() => {
  if (showConfirmationQueue && scrollableListRef.current) {
    const scrollState = scrollableListRef.current.getScrollState?.();
    const isAtBottom = scrollState
      ? scrollState.scrollHeight -
          scrollState.innerHeight -
          scrollState.scrollTop <=
        1
      : true;
    if (isAtBottom) {
      scrollableListRef.current.scrollToEnd();
    }
  }
}, [showConfirmationQueue, confirmingToolCallId]);

There is an active second path in packages/cli/src/ui/components/Composer.tsx (lines 61–65):

useEffect(() => {
  if (hasPendingActionRequired) {
    appEvents.emit(AppEvent.ScrollToBottom);
  }
}, [hasPendingActionRequired]);

Where hasPendingActionRequired is computed by useComposerStatus (lines 25–39) as:

const hasPendingToolConfirmation = useMemo(
  () =>
    (uiState.pendingHistoryItems ?? [])
      .filter((item): item is HistoryItemToolGroup => item.type === 'tool_group')
      .some((item) => item.tools.some((tool) => tool.status === CoreToolCallStatus.AwaitingApproval)),
  [uiState.pendingHistoryItems],
);

const hasPendingActionRequired =
  hasPendingToolConfirmation || ...

And MainContent.tsx listens to AppEvent.ScrollToBottom directly (lines 89–97):

useEffect(() => {
  const handleScroll = () => {
    scrollableListRef.current?.scrollToEnd();
  };
  appEvents.on(AppEvent.ScrollToBottom, handleScroll);
  return () => {
    appEvents.off(AppEvent.ScrollToBottom, handleScroll);
  };
}, []);

Impact: When Composer and MainContent are mounted together in the app layout (e.g. DefaultAppLayout), any tool confirmation arriving sets hasPendingToolConfirmation = true, which sets hasPendingActionRequired = true. Composer immediately emits AppEvent.ScrollToBottom, and MainContent's handleScroll handler unconditionally calls scrollToEnd(), completely overriding the isAtBottom guard in MainContent.

The unit test in MainContent.test.tsx passed because it renders <MainContent /> in isolation without <Composer />.

Recommendation: Prevent Composer.tsx from emitting AppEvent.ScrollToBottom when the pending action is a tool confirmation (since MainContent manages its own confirmation queue scroll positioning), or make handleScroll in MainContent also respect isAtBottom.

🟡 Improvements

1. Dead variable in AppContainer.tsx (enteringConstrainHeightMode):
   In packages/cli/src/ui/AppContainer.tsx (lines 1917–1932):

   let enteringConstrainHeightMode = false;
   if (
     !constrainHeight &&
     (keyMatchers[Command.SHOW_MORE_LINES](key) ||
       (keyMatchers[Command.ESCAPE](key) && !dialogsVisible))
   ) {
     enteringConstrainHeightMode = true;
     setConstrainHeight(true);
     if (keyMatchers[Command.SHOW_MORE_LINES](key)) {
       toggleLastTurnTools();
     }
     if (!isAlternateBuffer) {
       refreshStatic();
     }
     return true;
   }

   Because this block returns return true;, execution never continues down to line 1972 (keyMatchers[Command.SHOW_MORE_LINES](key) && !enteringConstrainHeightMode) when enteringConstrainHeightMode is true. When execution does reach line 1972, enteringConstrainHeightMode is guaranteed to be false.
   Suggestion: Remove let enteringConstrainHeightMode = false; and simplify line 1972 to keyMatchers[Command.SHOW_MORE_LINES](key).

2. Integration Test Coverage for Composer + MainContent Interaction:
   Add a test that renders both MainContent and Composer (or verifies that AppEvent.ScrollToBottom is not emitted on tool confirmation when scrolled up) to ensure regressions do not re-introduce scroll resets.

Done.

addressed

/gemini review