fix(patch): cherry-pick ec5836c to release/v0.28.0-preview.4-pr-18343 to patch version v0.28.0-preview.4 and create version 0.28.0-preview.5

[gemini-cli-robot]

This PR automatically cherry-picks commit ec5836c to patch version v0.28.0-preview.4 in the preview release to create version 0.28.0-preview.5.

[gemini-code-assist]

Summary of Changes

Hello @gemini-cli-robot, 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 focuses on enhancing the user experience by refining keyboard shortcut behaviors and improving the clarity of their descriptions within the CLI. The changes centralize focus management for shell interactions, making the Tab and Shift+Tab keys more intuitive for navigating between the main input and embedded shells. Additionally, it introduces a new utility to standardize how keybindings are displayed across the application, contributing to a more polished and user-friendly interface.

Highlights

• Improved Keyboard Shortcut Clarity and Consistency: Updated documentation and UI elements to provide clearer descriptions and consistent formatting for keyboard shortcuts, especially those related to shell interaction and focus management. A new utility for formatting keybindings has been introduced to ensure uniformity.
• Refined Shell Focus Handling: The logic for focusing and unfocusing embedded and background shells using Tab and Shift+Tab has been centralized and enhanced within AppContainer.tsx. This includes more explicit control over focus, conditional warnings, and better integration with background shell toggling (Ctrl+B).
• Enhanced Test Coverage for UI Interactions: New tests have been added to AppContainer.test.tsx to cover the updated focus handling and background shell toggling behaviors, ensuring the reliability of these critical UI interactions.
• Code Cleanup and Refactoring: Removed redundant focus management logic from BackgroundShellDisplay.tsx and ShellToolMessage.tsx, as these concerns are now handled at a higher level in AppContainer.tsx. Event listener cleanup has also been refactored for better management.

Changelog

• docs/cli/keyboard-shortcuts.md
  • Updated descriptions for various keyboard shortcuts related to shell visibility, focus, and management (e.g., Ctrl+B, Ctrl+L, Ctrl+K, Enter, Esc, Tab, Shift+Tab).
• packages/cli/src/config/keyBindings.ts
  • Added new command SHOW_SHELL_INPUT_UNFOCUS_WARNING.
  • Modified keybinding for UNFOCUS_SHELL_INPUT to explicitly require Shift+Tab.
  • Updated command descriptions for better clarity.
• packages/cli/src/ui/AppContainer.test.tsx
  • Added new test suites for 'Focus Handling (Tab / Shift+Tab)' and 'Background Shell Toggling (CTRL+B)'.
  • Implemented tests for focusing/unfocusing shell input, auto-unfocus on PTY deactivation, and correct background shell toggling behavior.
• packages/cli/src/ui/AppContainer.tsx
  • Refactored useEffect hooks for warning and tab focus timeout cleanup into a dedicated cleanup effect.
  • Modified global keypress handler to centralize Tab and Shift+Tab focus logic, including conditional warnings and explicit focus/unfocus actions.
  • Adjusted Ctrl+B handling for background shell toggling to explicitly manage focus state.
  • Set priority: true for the global useKeypress hook to ensure it takes precedence.
• packages/cli/src/ui/components/BackgroundShellDisplay.test.tsx
  • Removed tests for Shift+Tab unfocusing and Tab warning, as this logic is now handled in AppContainer.tsx.
• packages/cli/src/ui/components/BackgroundShellDisplay.tsx
  • Removed handleWarning and setEmbeddedShellFocused from useUIActions destructuring.
  • Removed local keypress handling for UNFOCUS_BACKGROUND_SHELL, UNFOCUS_BACKGROUND_SHELL_LIST, and SHOW_BACKGROUND_SHELL_UNFOCUS_WARNING.
  • Updated help text rendering to use the new formatCommand utility for consistent keybinding display.
  • Changed TOGGLE_BACKGROUND_SHELL keypress handler to return false to allow bubbling.
• packages/cli/src/ui/components/InputPrompt.tsx
  • Added a check for TOGGLE_BACKGROUND_SHELL to return false to allow the event to bubble up.
  • Modified FOCUS_SHELL_INPUT keypress handler to return true if focus is successfully set, false otherwise.
• packages/cli/src/ui/components/ShellInputPrompt.test.tsx
  • Added mock for useUIActions context.
  • Added a test case to verify that the Tab key sequence is sent to the PTY when focused.
• packages/cli/src/ui/components/ShellInputPrompt.tsx
  • Added a check for UNFOCUS_SHELL_INPUT to return false, allowing the unfocus command to bubble up to the global handler.
• packages/cli/src/ui/components/messages/ShellToolMessage.test.tsx
  • Removed renderWithContext helper function.
  • Removed test case for resetting focus when a shell finishes, as this logic has been refactored to AppContainer.tsx.
• packages/cli/src/ui/components/messages/ShellToolMessage.tsx
  • Removed the wasFocusedRef and its associated useEffect responsible for resetting focus on shell completion, as this is now managed by AppContainer.tsx.
• packages/cli/src/ui/components/messages/ToolMessageFocusHint.test.tsx
  • Updated snapshots to reflect the new keybinding display format (e.g., (Tab to focus) instead of (tab to focus)).
• packages/cli/src/ui/components/messages/ToolShared.tsx
  • Imported formatCommand and Command.
  • Updated the FocusHint component to use formatCommand for dynamically displaying focus/unfocus keybindings (e.g., (Shift+Tab to unfocus)).
• packages/cli/src/ui/hooks/shellReducer.ts
  • Ensured lastShellOutputTime is updated whenever a shell produces output, regardless of background shell visibility.
• packages/cli/src/ui/hooks/useGeminiStream.ts
  • Removed useEffect that automatically unfocused shell input when activePtyId became null, as this logic is now handled in AppContainer.tsx.
• packages/cli/src/ui/utils/keybindingUtils.test.ts
  • New file: Added unit tests for formatKeyBinding and formatCommand utilities.
• packages/cli/src/ui/utils/keybindingUtils.ts
  • New file: Introduced formatKeyBinding and formatCommand utility functions to provide consistent, human-readable representations of keyboard shortcuts.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a significant and well-executed refactoring of keyboard handling, particularly for focus management between the main input and shell components. The changes centralize logic, improve code clarity, and enhance user-facing documentation and hints. I've identified a keybinding conflict with Ctrl + L that makes one feature inaccessible, and a potential UX issue where Tab can unexpectedly unfocus an idle shell. Addressing these points will further solidify the improvements made in this PR.

[gemini-code-assist]

The Ctrl + L shortcut is assigned to both 'Toggle background shell list' (line 110) and 'Clear the terminal screen and redraw the UI' (line 120). This conflict will likely make one of the commands inaccessible. Please assign a unique shortcut to one of these actions to ensure both are usable.

[gemini-code-assist]

The current logic allows Tab to unfocus an idle shell, which can be surprising for users who expect Tab to always be passed to the shell for indentation or navigation. The documented way to unfocus is Shift+Tab. To make the behavior more predictable, Tab should not unfocus the shell. A warning can still be shown when the shell is active (e.g., for autocomplete) to guide the user.

          tabFocusTimeoutRef.current = setTimeout(() => {
            if (lastOutputTimeRef.current !== capturedTime) {
              handleWarning('Use Shift+Tab to unfocus');
            }
          }, 150);

[github-actions]

Size Change: -5.17 kB (-0.02%)

Total Size: 23.7 MB

Filename	Size	Change
./bundle/gemini.js	23.7 MB	-5.17 kB (-0.02%)

ℹ️ View Unchanged

Filename	Size
./bundle/sandbox-macos-permissive-closed.sb	1.03 kB
./bundle/sandbox-macos-permissive-open.sb	890 B
./bundle/sandbox-macos-permissive-proxied.sb	1.31 kB
./bundle/sandbox-macos-restrictive-closed.sb	3.29 kB
./bundle/sandbox-macos-restrictive-open.sb	3.36 kB
./bundle/sandbox-macos-restrictive-proxied.sb	3.56 kB

_{compressed-size-action}