feat(ux): added text wrapping capabilities to markdown tables

[devr0306]

Summary

This pull request enhances the rendering of markdown tables in the CLI by introducing robust text wrapping capabilities and a more intelligent column width allocation algorithm. These changes ensure that table content, especially long strings, is displayed clearly and legibly within the terminal's constraints, improving the overall user experience for data presentation.

Details

Text Wrapping: Implemented text wrapping for long content within markdown table cells using the ink wrapping library(already in the project) to prevent overflow and improve readability.
Flexible Column Widths: Introduced a new algorithm to dynamically calculate column widths. The longest word in each column is used to set the minimum width for the respective column and if there is additional space after every column has been allocated a width, it is distributed among the long columns.
New Test Coverage: Added dedicated test cases to verify the correct wrapping behavior of long cell content.

Related Issues

Fixes #3080

How to Validate

1. Ask Gemini CLI "Can you create a table with 3 rows and 4 columns? But make 2 of the columns short and 2 of the columns long. no code, just give me an example" (might have to use Gemini 3)
2. Can also ask for variations like every column being long, long headers, punctuation, etc

Screenshots of outputs:

Emoji/Special Character Screenshots(They don't look proper in the snapshots file)

The one with only emojis doesn't look proper due to an issue with ink

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-cli]

Hi @devr0306, thank you so much for your contribution to Gemini CLI! We really appreciate the time and effort you've put into this.

We're making some updates to our contribution process to improve how we track and review changes. Please take a moment to review our recent discussion post: Improving Our Contribution Process & Introducing New Guidelines.

Key Update: Starting January 26, 2026, the Gemini CLI project will require all pull requests to be associated with an existing issue. Any pull requests not linked to an issue by that date will be automatically closed.

Thank you for your understanding and for being a part of our community!

[gemini-code-assist]

Summary of Changes

Hello @devr0306, 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 rendering of markdown tables in the CLI by introducing robust text wrapping capabilities and a more intelligent column width allocation algorithm. These changes ensure that table content, especially long strings, is displayed clearly and legibly within the terminal's constraints, greatly improving the overall user experience for data presentation.

Highlights

• Text Wrapping: Implemented text wrapping for long content within markdown table cells to prevent overflow and improve readability.
• Flexible Column Widths: Introduced a new algorithm to dynamically calculate column widths, allowing them to flex based on content, header length, longest word, and available terminal space.
• Improved Readability: Enhanced the user experience by ensuring table content is fully visible and properly formatted within the terminal, even with extensive text.
• New Test Coverage: Added a dedicated test case to verify the correct wrapping behavior of long cell content.

Changelog

• packages/cli/src/ui/utils/TableRenderer.test.tsx
  • Added a new test case wraps long cell content correctly to validate the new text wrapping functionality.
  • Updated existing snapshot tests to reflect changes in table rendering.
• packages/cli/src/ui/utils/TableRenderer.tsx
  • Imported the wrap-ansi library for handling text wrapping with ANSI escape codes.
  • Replaced the previous column width calculation logic with a new three-step algorithm (Define Constraints, Calculate Available Space, Allocation Algorithm) that considers minimum (header/longest word) and maximum (full content) widths for flexible distribution.
  • Removed the old truncation logic, as content is now wrapped instead of cut off.
  • Refactored row rendering into renderVisualRow (for a single line of a row) and renderDataRow (which handles multi-line wrapped content for a logical row).
• packages/cli/src/ui/utils/snapshots/TableRenderer.test.tsx.snap
  • Updated snapshots for existing table rendering tests to match the new column width calculations.
  • Added a new snapshot for the wraps long cell content correctly test case.

Activity

• The author has provided clear validation steps, including specific Gemini CLI prompts, to test the new table rendering.
• Screenshots demonstrating the improved table formatting with wrapped text have been included in the PR description.
• The author has confirmed that tests have been added/updated for these changes by marking the relevant checklist item.

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. ↩

[github-actions]

Size Change: +2.37 kB (+0.01%)

Total Size: 23.7 MB

Filename	Size	Change
./bundle/gemini.js	23.7 MB	+2.37 kB (+0.01%)

ℹ️ 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}

[gemini-code-assist]

Code Review

This pull request introduces a significant improvement to the CLI's table rendering by adding text wrapping and flexible column widths. The new algorithm for calculating column widths based on min/max constraints and distributing available space is a robust approach. The implementation of text wrapping, including handling very long words, is well-executed. Overall, this is a great enhancement to the user experience. I have one suggestion to refine the width allocation logic to ensure it utilizes all available terminal space optimally.

[jacob314]

We should reuse the logic from
src/text-wrap.ts
in Ink rather than implementing our own incomplete text wrapping.
As is, this logic has some significant challenges for edge cases where content does not wrap easily.

[devr0306]

Review of Table Wrapping Implementation

This looks like a solid improvement to the table rendering logic! The move to use ink's internal wrapping utilities is a great choice and simplifies the logic significantly.

I have verified the logic and tests, and everything looks consistent with the project standards.

Logic

• Column Allocation: The algorithm for "Case A" (constrained width) and "Case B" (surplus width) looks robust.
• Short Column Handling: The logic to protect "short columns" (<= 10 chars) from being squashed in tight layouts is a nice touch. The check for totalShortColumnWidth >= availableWidth correctly prevents potential divide-by-zero or negative scaling issues in edge cases.

Tests

• Coverage: The added tests cover the main wrapping scenarios well.
• Edge Case: Consider adding one test case for a very narrow terminal (e.g., width=15 or width=20 with multiple columns) to explicitly verify that the "Case A" logic (where totalMinWidth > availableWidth) functions as expected without throwing errors.

General

• Dependencies: The bump to ink@6.4.9 is noted and appropriate for accessing the wrapping utilities.
• Conventions: The React code is stateless and follows our patterns. Tests use renderWithProviders and snapshots correctly.

Great work!

[jacob314]

PR Review: Table Text Wrapping & Intelligent Scaling

This PR significantly improves the data presentation in the CLI by introducing text wrapping for Markdown tables and a dynamic column allocation algorithm.

Key Strengths

• UX Improvement: Implementing text wrapping instead of truncation makes table content much more readable, especially for long descriptions or data points.
• Robust Column Allocation: The algorithm handles both narrow and wide terminals gracefully, ensuring minimum widths for columns while distributing surplus space.
• Header Cleaning: Removing bold markers from headers is a smart move to prevent layout breakage and redundant styling.
• Test Coverage: Great usage of renderWithProviders and toMatchSnapshot. The new test cases cover complex scenarios like punctuation and varying content lengths effectively.
• React Patterns: The implementation follows project conventions, avoiding setState side effects and ensuring pure rendering logic.

Suggestions for Improvement

• Compact Table Support: In wide terminals, the current algorithm distributes all surplus space, causing even small tables (with low maxWidth) to stretch to the full terminal width. Consider capping the allocation at the maxWidth when surplus is abundant to maintain a more compact look for smaller tables.
• Markdown Wrapping Edge Cases: Since wrapStyledChars operates on the raw string, there's a risk that a Markdown marker (like a link or a bold tag) could be split across lines, potentially breaking the inline rendering. While this is a known limitation of terminal-based wrapping, it's worth keeping in mind.
• Calculation Robustness: In the scaling logic:

  const scale = (availableWidth - finalTotalShortColumnWidth) / (totalMinWidth - finalTotalShortColumnWidth);

  Ensure there is an explicit guard against division by zero if totalMinWidth equals finalTotalShortColumnWidth.
• Typing: Ensure all parameters in the new tests and utility functions have explicit types to maintain type safety.

---

Comments are from /review-frontend audited by Jacob

[github-actions]

Size Change: +3.66 kB (+0.02%)

Total Size: 23.9 MB

Filename	Size	Change
./bundle/gemini.js	23.9 MB	+3.66 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}

[jacob314]

rather than this we should avoid scaling columns where none of the lines wrapped. That will result in ore efficient use of space. add tests that verify.

[devr0306]

Will resolve in a separate PR

[jacob314]

Review from /review-frontend, reviewed manually by Jacob:

1. Markdown Marker Handling (Critical): Switching to toStyledCharacters and styledCharsWidth counts markdown markers (like **, *, ) as literal characters. This leads to incorrect column widths because the renderer doesn't account for these markers being hidden or transformed by RenderInline`.

2. Broken Markdown Wrapping: Applying wrapStyledChars to raw markdown strings can split markers across lines (e.g., **word on one line and ** on the next). This breaks RenderInline's ability to recognize and apply the styling, resulting in broken literal markers in the output.

3. Inconsistent Width Calculation: The new calculateWidths utility diverges from the project's established getPlainTextLength in InlineMarkdownRenderer.tsx. We should maintain consistency by using a shared, markdown-aware width calculation that also handles non-ASCII characters correctly.

4. Rendering Performance: The use of useMemo for caching the wrapping logic and the introduction of ProcessedLine to avoid redundant parsing are great improvements to the component's efficiency.

5. Parameterized Tests: The new tests are quite repetitive. Consider consolidating the emoji and Asian script variations into parameterized tests (it.each) to improve maintainability and readability.

[jacob314]

This is very close to being ready to land.

Here is a screenshot showing somewhat odd table rendering behavior. Notice how the two tables have uneven widths likely due to the rounding issue bug. Also note that the second table isn't the full window width even though its content could use it.

What I would suggest is calculating the maximum length of a line in a column if no words were wrapped and use that to compute the maximum size the line wants to grow to.

[jacob314]