feat(ui): dynamically generate all keybinding hints

[scidomino]

Summary

Dynamically generate all keybinding hints

Details

• Centralized Platform Logic: Refactored keybindingUtils.ts to use platform-specific maps. macOS now correctly identifies Option and Cmd, while Windows and Linux use Alt, Win, and Super.
• Dynamic UI Hints: Audited and updated all major components (ShortcutsHelp, Help, ApprovalModeIndicator, RawMarkdownIndicator, and TodoTray) to resolve keybindings dynamically via formatCommand.
• Documentation Sync: Updated the generate-keybindings-doc.ts script to use the same centralized logic, ensuring keyboard-shortcuts.md always reflects the actual CLI behavior accurately.
• Testing Integrity:
  • Added a stable 'default' platform fallback when FORCE_GENERIC_KEYBINDING_HINTS is set in the environment to prevent cross-OS snapshot thrashing.
  • Updated ShortcutsHelp.test.tsx and RawMarkdownIndicator.test.tsx with beforeAll hooks to explicitly clear the stub and test platform variations.
  • Consolidated keybindingUtils.test.ts into a parameterized suite for robustness.

Related Issues

For #21294.

How to Validate

Verify hints show properly.

Pre-Merge Checklist

• Updated relevant documentation and README (if needed)
• Added/updated tests (if needed)
• Noted breaking changes (if any)
• Validated on required platforms/methods:
  • MacOS
    • npm run
    • npx
    • Docker
    • Podman
    • Seatbelt
  • Windows
    • npm run
    • npx
    • Docker
  • Linux
    • npm run
    • npx
    • Docker

[gemini-code-assist]

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 significantly enhances the user experience by introducing context-aware keybinding hints across the CLI's user interface. Instead of static, potentially incorrect key labels, the system now dynamically displays the appropriate key combinations for the user's operating system. This change centralizes keybinding formatting logic, improves consistency between the UI and documentation, and strengthens testing robustness for platform-dependent features.

Highlights

• Context-Aware Keybinding UI Hints: Implemented dynamic resolution of keybinding labels in the UI based on the user's operating system and configuration, replacing previously hardcoded strings. This ensures that users see the correct modifier keys (e.g., 'Option' on macOS, 'Alt' on Windows/Linux) for commands.
• Centralized Keybinding Logic: Refactored keybindingUtils.ts to include platform-specific modifier key mappings (e.g., Cmd for macOS, Win for Windows, Super for Linux) and a unified formatKeyBinding function to generate human-readable key combinations.
• UI Component Updates: Audited and updated several UI components, including ShortcutsHelp, Help, ApprovalModeIndicator, RawMarkdownIndicator, and TodoTray, to utilize the new formatCommand utility for dynamically displaying keybinding hints.
• Documentation and Testing Alignment: The generate-keybindings-doc.ts script was updated to use the same centralized keybinding logic, ensuring that the keyboard-shortcuts.md documentation accurately reflects the CLI's behavior. Testing was also enhanced with platform-specific checks and environment stubs to prevent cross-OS snapshot inconsistencies.

Changelog

• docs/reference/keyboard-shortcuts.md
  • Updated keybinding formatting to use a more consistent style (e.g., Ctrl + [ changed to Ctrl+[), reflecting the output of the updated documentation generation script.
  • Replaced manual key name overrides with dynamic formatting from keybindingUtils.
• packages/cli/src/ui/components/ApprovalModeIndicator.tsx
  • Removed hardcoded keybinding text constants.
  • Imported formatCommand and Command to dynamically generate keybinding hints for approval modes.
• packages/cli/src/ui/components/Help.test.tsx
  • Updated snapshot expectation for 'Page Up/Down' to 'Page Up/Page Down' for consistency.
• packages/cli/src/ui/components/Help.tsx
  • Imported formatCommand and Command.
  • Replaced various hardcoded keybinding strings with dynamic calls to formatCommand for context-aware display.
• packages/cli/src/ui/components/RawMarkdownIndicator.test.tsx
  • Added a beforeAll hook to stub the VITEST environment variable for consistent testing.
  • Updated snapshot expectations to reflect the new capitalized format for modifier keys (e.g., 'option+m' to 'Option+M').
• packages/cli/src/ui/components/RawMarkdownIndicator.tsx
  • Replaced platform-specific hardcoded modKey logic with a call to formatCommand(Command.TOGGLE_MARKDOWN) for dynamic display.
• packages/cli/src/ui/components/ShortcutsHelp.test.tsx
  • Added a beforeAll hook to stub the VITEST environment variable for consistent testing.
  • Updated snapshot expectations for keybinding display, including changing 'Tab Tab' to 'Tab focus UI' and 'Option+M' to 'Alt+M' (when running on a non-macOS test environment).
• packages/cli/src/ui/components/ShortcutsHelp.tsx
  • Imported Command and formatCommand.
  • Refactored buildShortcutItems to use formatCommand for all keybinding descriptions, ensuring dynamic and context-aware hints.
• packages/cli/src/ui/components/snapshots/ApprovalModeIndicator.test.tsx.snap
  • Updated snapshots to reflect the new dynamic keybinding formatting, such as 'shift+tab' becoming 'Shift+Tab' and 'ctrl+y' becoming 'Ctrl+Y'.
• packages/cli/src/ui/components/snapshots/ShortcutsHelp.test.tsx.snap
  • Updated snapshots to reflect dynamic keybinding formatting and the change from 'Tab Tab' to 'Tab focus UI'.
• packages/cli/src/ui/components/snapshots/ToolConfirmationQueue.test.tsx.snap
  • Removed a specific snapshot related to a multiline shell command with syntax highlighting and redirection warning.
• packages/cli/src/ui/components/messages/Todo.tsx
  • Imported formatCommand and Command.
  • Updated the toggleHint for the Todo tray to use formatCommand(Command.SHOW_FULL_TODOS).
• packages/cli/src/ui/components/messages/snapshots/Todo.test.tsx.snap
  • Updated snapshots to reflect the new dynamic keybinding formatting, changing 'ctrl+t' to 'Ctrl+T'.
• packages/cli/src/ui/hooks/useSuspend.test.ts
  • Imported formatCommand and Command.
  • Updated warning messages related to Ctrl+Z suspend and undo functionality to dynamically display keybindings using formatCommand.
• packages/cli/src/ui/hooks/useSuspend.ts
  • Imported formatCommand and Command.
  • Modified warning messages for Ctrl+Z suspend functionality to use dynamically formatted keybinding strings.
• packages/cli/src/ui/utils/keybindingUtils.test.ts
  • Refactored formatKeyBinding tests into a parameterized suite to cover different platforms (darwin, win32, linux, default) and various modifier combinations.
  • Updated formatCommand tests to explicitly specify the platform for consistent testing.
• packages/cli/src/ui/utils/keybindingUtils.ts
  • Imported the process module to determine the current operating system.
  • Introduced MODIFIER_MAPS to define platform-specific names for modifier keys (e.g., 'Cmd' vs 'Win' vs 'Super', 'Option' vs 'Alt').
  • Modified formatKeyBinding to accept an optional platform parameter, defaulting to process.platform or 'default' for testing, and use the appropriate modifier map.
  • Updated formatCommand to pass the platform parameter to formatKeyBinding.
• scripts/generate-keybindings-doc.ts
  • Removed internal KEY_NAME_OVERRIDES and custom formatBinding/formatKeyName functions.
  • Now imports and utilizes the centralized formatKeyBinding utility from packages/cli/src/ui/utils/keybindingUtils.js to generate keybinding documentation, ensuring consistency with the UI.

Activity

• The author, scidomino, has implemented the core logic for context-aware UI hints for keybindings.
• The author has refactored keybinding utilities and updated multiple UI components to use the new dynamic formatting.
• The author has updated the documentation generation script to align with the new keybinding logic.
• The author has added and updated tests to ensure the integrity and cross-platform consistency of the keybinding system.
• The author has validated the changes on macOS using npm run.

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 effectively refactors the keybinding UI hints to be context-aware, centralizing the logic in keybindingUtils.ts and updating various components to use it. This is a great improvement for cross-platform consistency. My review identified a couple of issues: an incorrect test snapshot for the ShortcutsHelp component on macOS, and the removal of a test for ToolConfirmationQueue which appears to hide an unaddressed hardcoded keybinding. Addressing these will ensure the feature is completely and correctly implemented.

I am having trouble creating individual review comments. Click here to see my feedback.

packages/cli/src/ui/components/snapshots/ShortcutsHelp.test.tsx.snap (29)

The snapshot for the narrow mode on macOS incorrectly shows Alt+M for the 'raw markdown mode' shortcut. On macOS, this should be Option+M, as correctly reflected in the wide mode snapshot. This suggests a potential issue in the test setup, possibly related to state leakage between parameterized tests, causing an incorrect platform context to be used. Please investigate and correct the snapshot to ensure the proper keybinding is displayed for macOS users.

packages/cli/src/ui/components/snapshots/ToolConfirmationQueue.test.tsx.snap (93-118)

This snapshot test for ToolConfirmationQueue has been removed. The test, renders a multiline shell command with syntax highlighting and redirection warning (SVG snapshot) 1, was asserting the presence of a hardcoded keybinding hint (Shift+Tab). The removal of this test is concerning because ToolConfirmationQueue.tsx was not updated to use the new dynamic formatCommand utility, and this removal appears to be hiding a regression or an incomplete implementation.

To ensure all user-facing keybinding hints are context-aware as intended by this PR, please reinstate this test and update ToolConfirmationQueue.tsx to use formatCommand for its keybinding hints.

[github-actions]

Size Change: +1.75 kB (+0.01%)

Total Size: 26 MB

Filename	Size	Change
./bundle/gemini.js	25.5 MB	+1.75 kB (+0.01%)

ℹ️ View Unchanged

Filename	Size
./bundle/node_modules/@google/gemini-cli-devtools/dist/client/main.js	221 kB
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/_client-assets.js	227 kB
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/index.js	11.5 kB
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/types.js	132 B
./bundle/sandbox-macos-permissive-open.sb	890 B
./bundle/sandbox-macos-permissive-proxied.sb	1.31 kB
./bundle/sandbox-macos-restrictive-open.sb	3.36 kB
./bundle/sandbox-macos-restrictive-proxied.sb	3.56 kB
./bundle/sandbox-macos-strict-open.sb	4.82 kB
./bundle/sandbox-macos-strict-proxied.sb	5.02 kB

_{compressed-size-action}

[gemini-code-assist]

Code Review

This pull request is a great improvement, centralizing the keybinding logic into a dynamic, platform-aware utility. The changes to the UI components and the documentation generation script create a much more maintainable and consistent system. The enhanced tests also add significant value. I've found one area that appears to have been missed during the refactoring, which I've detailed in a specific comment.

I am having trouble creating individual review comments. Click here to see my feedback.

packages/cli/src/ui/components/snapshots/ToolConfirmationQueue.test.tsx.snap (93-118)

This snapshot, which contains a hardcoded keybinding hint for Shift+Tab, is being deleted. The goal of this PR is to make all keybinding hints dynamic, but it seems the ToolConfirmationQueue component was missed during the audit mentioned in the PR description.

Instead of deleting this test case, please update ToolConfirmationQueue.tsx to use the new formatCommand(Command.CYCLE_APPROVAL_MODE) utility for the hint, and then update the snapshot accordingly. This will ensure all user-facing keybindings are handled dynamically and consistently.

[scidomino]

Code Review

This pull request is a great improvement, centralizing the keybinding logic into a dynamic, platform-aware utility. The changes to the UI components and the documentation generation script create a much more maintainable and consistent system. The enhanced tests also add significant value. I've found one area that appears to have been missed during the refactoring, which I've detailed in a specific comment.

I am having trouble creating individual review comments. Click here to see my feedback.

packages/cli/src/ui/components/snapshots/ToolConfirmationQueue.test.tsx.snap (93-118)

This snapshot, which contains a hardcoded keybinding hint for Shift+Tab, is being deleted. The goal of this PR is to make all keybinding hints dynamic, but it seems the ToolConfirmationQueue component was missed during the audit mentioned in the PR description.

Instead of deleting this test case, please update ToolConfirmationQueue.tsx to use the new formatCommand(Command.CYCLE_APPROVAL_MODE) utility for the hint, and then update the snapshot accordingly. This will ensure all user-facing keybindings are handled dynamically and consistently.

This is a spurious error. The test had been removed in a previous PR but they forgot to remove the snapshot for it.

[alisa-alisa]

This is a spurious error. The test had been removed in a previous PR but they forgot to remove the snapshot for it.

Shouldn't we just remove the snapshot in this case?

[scidomino]

This is a spurious error. The test had been removed in a previous PR but they forgot to remove the snapshot for it.

Shouldn't we just remove the snapshot in this case?

Yes. That's what my PR does. Gemini was confused because it saw me removing the snapshot and thought I had removed the test.