feat: add Termina backend#2561
Conversation
Codecov Report❌ Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## main #2561 +/- ##
=======================================
- Coverage 92.7% 92.3% -0.4%
=======================================
Files 104 105 +1
Lines 19723 20241 +518
=======================================
+ Hits 18284 18690 +406
- Misses 1439 1551 +112 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
be94294 to
5119b2b
Compare
5119b2b to
2c6d137
Compare
|
great to see this PR! |
f18287a to
1f9e1d2
Compare
|
I wouldn't mind if @the-mikedavis could take a look at the calling patterns here. (No obligation obv.) |
|
Almost all of the code in Helix for the termina integration is in this terminal backend module: https://github.com/helix-editor/helix/blob/master/helix-tui/src/backend/termina.rs The tui crate originally came from tui-rs so there might be some design overlap still, though it was forked a long time ago. I will give this branch a look 👍 |
Thanks. I asked Codex to take a review with the PR in context against that file and the deeper app context in comparison to the example code. Seems this side is reasonable. I looked at both. The PR comment is informational: it points to Helix’s Termina backend and says they’ll review the branch. The useful takeaways from Helix:
No further code change looks required from that comment beyond the macro cleanup already pushed. I looked at Helix beyond the backend. The important bit is that Helix’s backend example is not really comparable to our short example: Helix has an app-owned terminal lifecycle. Sources checked:
What Helix does:
Compared to our example:
My read: no code change is needed from this comparison. Helix reinforces that the Ratatui example should stay explicit and small, while the richer claim/restore/panic-hook lifecycle belongs in real applications or a separate higher-level session abstraction, not in the backend example itself. |
1f9e1d2 to
a62f2bb
Compare
|
I added the termina backend version of the demo app in 3cced2c - I hope you don't mind :) |
a857cdc to
88e2947
Compare
orhun
left a comment
There was a problem hiding this comment.
LGTM
Anything blocking on this one?
I'd say let's include this in 0.30.2 and let the users try it out.
8d460aa to
0f08bdc
Compare
## 🤖 New release * `ratatui-core`: 0.1.1 -> 0.1.2 * `ratatui-crossterm`: 0.1.1 -> 0.1.2 * `ratatui-widgets`: 0.3.1 -> 0.3.2 * `ratatui-termina`: 0.1.0 * `ratatui-termwiz`: 0.1.1 -> 0.1.2 * `ratatui-termion`: 0.1.1 -> 0.1.2 * `ratatui`: 0.30.1 -> 0.30.2 * `ratatui-macros`: 0.7.1 -> 0.7.2 <details><summary><i><b>Changelog</b></i></summary><p> ## `ratatui-core` <blockquote> ## [0.1.2+ratatui-core](ratatui-core-v0.1.1...ratatui-core-v0.1.2) - 2026-06-19 ### Features - [90639c1](90639c1) *(uncategorized)* Add Termina backend by `@joshka` in [#2561]( #2561) > ## Summary > > - add the `ratatui-termina` backend crate using the published `termina` > crate > - expose the backend through the `termina` feature and Ratatui > prelude/backend re-exports > - add a small Termina event-loop example and wire the backend into CI, > xtask, README generation, and docs > > Refs #1784 > > ## Validation > > - `cargo +nightly fmt` > - `cargo check -p ratatui-termina --all-features --all-targets` > - `cargo check -p ratatui --no-default-features --features termina` > - `cargo check -p xtask` > - `cargo check -p release-header` > - `cargo xtask check-backend termina` > - `cargo xtask test-backend termina` > - `cargo xtask rdme --check` > - `markdownlint-cli2 ARCHITECTURE.md ratatui-termina/README.md > .github/ISSUE_TEMPLATE/bug_report.md` > > --------- ### Bug Fixes - [e306ce6](e306ce6) *(buffer)* Create updates for "uncovered" cells by `@benjajaja` in [#2587]( #2587) > When a wide cell from the previous buffer is replaced by a short/normal > cell, the trailing cell does not get an update if its content does not > change. But if the wide cell has a background (or other) style, the > terminal *did* render the trailing cell with that style. > > Force trailing cells to update if background, underline, or modifiers > are different than the wide cell. We can ignore foreground. > > Fixes #2585 (see that for the detailed visual reports) ### Miscellaneous Tasks - [c75d778](c75d778) *(ci)* Add cargo-udeps dependency check by `@joshka` in [#2599]( #2599) > Adds cargo xtask udeps and runs it from CI as a required job. > > This complements cargo-machete rather than replacing it. cargo-machete > is a fast static source scan, which is why it missed the package-level > unused deps fixed in #2598 when the same dependency names were still > referenced by example crates. cargo-udeps compiles the workspace and > checks rustc dep-info, so it can catch unused dependency declarations > for the package being checked. > > To make the new job pass, this also removes the remaining true-positive > unused dev-deps and records explicit cargo-udeps ignores for current > false positives / intentional cases: ratatui-core critical-section, > ratatui-crossterm's duplicate crossterm version feature shape, and > ratatui-termwiz's doc-example-only ratatui dev-dependency. > > I searched existing issues and PRs for udeps / cargo-udeps / "cargo > udeps". I did not find prior ratatui discussion about adopting > cargo-udeps; the only hits were Dependabot PR bodies for > taiki-e/install-action release notes mentioning cargo-udeps version > updates, for example #1971, #2095, #2194, and #2522. > > Validation:- cargo xtask udeps > - cargo xtask format --check > > --------- - [4a63d41](4a63d41) *(uncategorized)* Remove unused dependencies by `@KikiKian` in [#2598]( #2598) > Audit removes these dependencies that are not used: > > ratatui/Cargo.toml — Removed from [dev-dependencies]: > - futures > - rand_chacha > - tokio > - tracing > - tracing-appender > - tracing-subscriber > > ratatui-core/Cargo.toml — Moved from [dependencies] → > [dev-dependencies]: > - indoc > > --------- **Full Changelog**: ratatui-core-v0.1.1...ratatui-core-v0.1.2 </blockquote> ## `ratatui-crossterm` <blockquote> ## [0.1.2+ratatui-crossterm](ratatui-crossterm-v0.1.1...ratatui-crossterm-v0.1.2) - 2026-06-19 ### Miscellaneous Tasks - [c75d778](c75d778) *(ci)* Add cargo-udeps dependency check by `@joshka` in [#2599]( #2599) > Adds cargo xtask udeps and runs it from CI as a required job. > > This complements cargo-machete rather than replacing it. cargo-machete > is a fast static source scan, which is why it missed the package-level > unused deps fixed in #2598 when the same dependency names were still > referenced by example crates. cargo-udeps compiles the workspace and > checks rustc dep-info, so it can catch unused dependency declarations > for the package being checked. > > To make the new job pass, this also removes the remaining true-positive > unused dev-deps and records explicit cargo-udeps ignores for current > false positives / intentional cases: ratatui-core critical-section, > ratatui-crossterm's duplicate crossterm version feature shape, and > ratatui-termwiz's doc-example-only ratatui dev-dependency. > > I searched existing issues and PRs for udeps / cargo-udeps / "cargo > udeps". I did not find prior ratatui discussion about adopting > cargo-udeps; the only hits were Dependabot PR bodies for > taiki-e/install-action release notes mentioning cargo-udeps version > updates, for example #1971, #2095, #2194, and #2522. > > Validation:- cargo xtask udeps > - cargo xtask format --check > > --------- **Full Changelog**: ratatui-crossterm-v0.1.1...ratatui-crossterm-v0.1.2 </blockquote> ## `ratatui-widgets` <blockquote> ## [0.3.2+ratatui-widgets](ratatui-widgets-v0.3.1...ratatui-widgets-v0.3.2) - 2026-06-19 ### Bug Fixes - [81e667f](81e667f) *(scrollbar)* Keep a large thumb within the track at the end by `@satyakwok` in [#2594]( #2594) > > Closes #2582. > > ## Problem > > When the content is shorter than the viewport, the thumb is large > relative to the track. With the position at the end, `part_lengths` > clamped `thumb_start` to `track_length - 1` while `thumb_length` was > clamped independently to `[1, track_length]`, so `thumb_start + > thumb_length` could exceed `track_length`. > > `bar_symbols` lays out `begin + track_start + thumb + track_end + end` > and zips it against the cells of the area. When the thumb overruns the > track, `track_end` saturates to `0` but the thumb still emits more cells > than the track can hold, so the trailing `end` symbol is pushed past the > end of the area. The last visible cell ends up being a thumb (`█`) where > the end arrow (`▼`) should be. > > Concretely, for the issue's repro (`VerticalRight`, `content_length = > 9`, `position = 8`, height `24`): track is `22`, `thumb_length = 17`, > `thumb_start = 6`, and `6 + 17 = 23 > 22`. > > This is a regression from v0.30.0, where `thumb_length` was derived as > `thumb_end - thumb_start` and therefore always fit within the track. > > ## Fix > > Clamp `thumb_start` to `track_length - thumb_length` (instead of > `track_length - 1`) so the thumb always fits within the track and the > end symbol is preserved. > > ## Test > > Two regression tests, both fail on `main` and pass with the fix: > > - `thumb_stays_within_track_for_large_thumb_at_end` checks > `part_lengths` directly with the issue's parameters — asserts > `thumb_start + thumb_length <= track_length` and that the parts sum to > the track length. > - `render_scrollbar_keeps_end_symbol_for_large_thumb` renders the #2582 > case (both arrows, large thumb at the end) and asserts the end symbol is > drawn rather than overwritten by a thumb cell. > > All existing scrollbar tests still pass. - [fce3c80](fce3c80) *(widgets)* Require thread-safe shadow effects by `@joshka` in [#2584]( #2584) > ## Summary > > - require custom shadow effects to preserve the auto traits expected by > Block-backed widgets > - document the CellEffect auto-trait contract > - add a public widget regression test for the affected ratatui::widgets > re-exports > > Fixes #2583 > > --------- **Full Changelog**: ratatui-widgets-v0.3.1...ratatui-widgets-v0.3.2 </blockquote> ## `ratatui-termina` <blockquote> ## [0.1.0+ratatui-termina](https://github.com/ratatui/ratatui/releases/tag/ratatui-termina-v0.1.0) - 2026-06-19 ### Features - [90639c1](90639c1) *(uncategorized)* Add Termina backend by `@joshka` in [#2561]( #2561) > ## Summary > > - add the `ratatui-termina` backend crate using the published `termina` > crate > - expose the backend through the `termina` feature and Ratatui > prelude/backend re-exports > - add a small Termina event-loop example and wire the backend into CI, > xtask, README generation, and docs > > Refs #1784 > > ## Validation > > - `cargo +nightly fmt` > - `cargo check -p ratatui-termina --all-features --all-targets` > - `cargo check -p ratatui --no-default-features --features termina` > - `cargo check -p xtask` > - `cargo check -p release-header` > - `cargo xtask check-backend termina` > - `cargo xtask test-backend termina` > - `cargo xtask rdme --check` > - `markdownlint-cli2 ARCHITECTURE.md ratatui-termina/README.md > .github/ISSUE_TEMPLATE/bug_report.md` > > --------- ### Miscellaneous Tasks - [c75d778](c75d778) *(ci)* Add cargo-udeps dependency check by `@joshka` in [#2599]( #2599) > Adds cargo xtask udeps and runs it from CI as a required job. > > This complements cargo-machete rather than replacing it. cargo-machete > is a fast static source scan, which is why it missed the package-level > unused deps fixed in #2598 when the same dependency names were still > referenced by example crates. cargo-udeps compiles the workspace and > checks rustc dep-info, so it can catch unused dependency declarations > for the package being checked. > > To make the new job pass, this also removes the remaining true-positive > unused dev-deps and records explicit cargo-udeps ignores for current > false positives / intentional cases: ratatui-core critical-section, > ratatui-crossterm's duplicate crossterm version feature shape, and > ratatui-termwiz's doc-example-only ratatui dev-dependency. > > I searched existing issues and PRs for udeps / cargo-udeps / "cargo > udeps". I did not find prior ratatui discussion about adopting > cargo-udeps; the only hits were Dependabot PR bodies for > taiki-e/install-action release notes mentioning cargo-udeps version > updates, for example #1971, #2095, #2194, and #2522. > > Validation:- cargo xtask udeps > - cargo xtask format --check > > --------- </blockquote> ## `ratatui-termwiz` <blockquote> ## [0.1.2+ratatui-termwiz](ratatui-termwiz-v0.1.1...ratatui-termwiz-v0.1.2) - 2026-06-19 ### Miscellaneous Tasks - [c75d778](c75d778) *(ci)* Add cargo-udeps dependency check by `@joshka` in [#2599]( #2599) > Adds cargo xtask udeps and runs it from CI as a required job. > > This complements cargo-machete rather than replacing it. cargo-machete > is a fast static source scan, which is why it missed the package-level > unused deps fixed in #2598 when the same dependency names were still > referenced by example crates. cargo-udeps compiles the workspace and > checks rustc dep-info, so it can catch unused dependency declarations > for the package being checked. > > To make the new job pass, this also removes the remaining true-positive > unused dev-deps and records explicit cargo-udeps ignores for current > false positives / intentional cases: ratatui-core critical-section, > ratatui-crossterm's duplicate crossterm version feature shape, and > ratatui-termwiz's doc-example-only ratatui dev-dependency. > > I searched existing issues and PRs for udeps / cargo-udeps / "cargo > udeps". I did not find prior ratatui discussion about adopting > cargo-udeps; the only hits were Dependabot PR bodies for > taiki-e/install-action release notes mentioning cargo-udeps version > updates, for example #1971, #2095, #2194, and #2522. > > Validation:- cargo xtask udeps > - cargo xtask format --check > > --------- **Full Changelog**: ratatui-termwiz-v0.1.1...ratatui-termwiz-v0.1.2 </blockquote> ## `ratatui-termion` <blockquote> ## [0.1.2+ratatui-termion](ratatui-termion-v0.1.1...ratatui-termion-v0.1.2) - 2026-06-19 ### Miscellaneous Tasks - [c75d778](c75d778) *(ci)* Add cargo-udeps dependency check by `@joshka` in [#2599]( #2599) > Adds cargo xtask udeps and runs it from CI as a required job. > > This complements cargo-machete rather than replacing it. cargo-machete > is a fast static source scan, which is why it missed the package-level > unused deps fixed in #2598 when the same dependency names were still > referenced by example crates. cargo-udeps compiles the workspace and > checks rustc dep-info, so it can catch unused dependency declarations > for the package being checked. > > To make the new job pass, this also removes the remaining true-positive > unused dev-deps and records explicit cargo-udeps ignores for current > false positives / intentional cases: ratatui-core critical-section, > ratatui-crossterm's duplicate crossterm version feature shape, and > ratatui-termwiz's doc-example-only ratatui dev-dependency. > > I searched existing issues and PRs for udeps / cargo-udeps / "cargo > udeps". I did not find prior ratatui discussion about adopting > cargo-udeps; the only hits were Dependabot PR bodies for > taiki-e/install-action release notes mentioning cargo-udeps version > updates, for example #1971, #2095, #2194, and #2522. > > Validation:- cargo xtask udeps > - cargo xtask format --check > > --------- **Full Changelog**: ratatui-termion-v0.1.1...ratatui-termion-v0.1.2 </blockquote> ## `ratatui` <blockquote> ## [0.30.2+ratatui](ratatui-v0.30.1...ratatui-v0.30.2) - 2026-06-19 ### Features - [90639c1](90639c1) *(uncategorized)* Add Termina backend by `@joshka` in [#2561]( #2561) > ## Summary > > - add the `ratatui-termina` backend crate using the published `termina` > crate > - expose the backend through the `termina` feature and Ratatui > prelude/backend re-exports > - add a small Termina event-loop example and wire the backend into CI, > xtask, README generation, and docs > > Refs #1784 > > ## Validation > > - `cargo +nightly fmt` > - `cargo check -p ratatui-termina --all-features --all-targets` > - `cargo check -p ratatui --no-default-features --features termina` > - `cargo check -p xtask` > - `cargo check -p release-header` > - `cargo xtask check-backend termina` > - `cargo xtask test-backend termina` > - `cargo xtask rdme --check` > - `markdownlint-cli2 ARCHITECTURE.md ratatui-termina/README.md > .github/ISSUE_TEMPLATE/bug_report.md` > > --------- ### Miscellaneous Tasks - [c75d778](c75d778) *(ci)* Add cargo-udeps dependency check by `@joshka` in [#2599]( #2599) > Adds cargo xtask udeps and runs it from CI as a required job. > > This complements cargo-machete rather than replacing it. cargo-machete > is a fast static source scan, which is why it missed the package-level > unused deps fixed in #2598 when the same dependency names were still > referenced by example crates. cargo-udeps compiles the workspace and > checks rustc dep-info, so it can catch unused dependency declarations > for the package being checked. > > To make the new job pass, this also removes the remaining true-positive > unused dev-deps and records explicit cargo-udeps ignores for current > false positives / intentional cases: ratatui-core critical-section, > ratatui-crossterm's duplicate crossterm version feature shape, and > ratatui-termwiz's doc-example-only ratatui dev-dependency. > > I searched existing issues and PRs for udeps / cargo-udeps / "cargo > udeps". I did not find prior ratatui discussion about adopting > cargo-udeps; the only hits were Dependabot PR bodies for > taiki-e/install-action release notes mentioning cargo-udeps version > updates, for example #1971, #2095, #2194, and #2522. > > Validation:- cargo xtask udeps > - cargo xtask format --check > > --------- - [4a63d41](4a63d41) *(uncategorized)* Remove unused dependencies by `@KikiKian` in [#2598]( #2598) > Audit removes these dependencies that are not used: > > ratatui/Cargo.toml — Removed from [dev-dependencies]: > - futures > - rand_chacha > - tokio > - tracing > - tracing-appender > - tracing-subscriber > > ratatui-core/Cargo.toml — Moved from [dependencies] → > [dev-dependencies]: > - indoc > > --------- **Full Changelog**: ratatui-v0.30.1...ratatui-v0.30.2 </blockquote> ## `ratatui-macros` <blockquote> ## [0.7.2+ratatui-macros](ratatui-macros-v0.7.1...ratatui-macros-v0.7.2) - 2026-06-19 **Full Changelog**: ratatui-macros-v0.7.1...ratatui-macros-v0.7.2 </blockquote> </p></details> --- This PR was generated with [release-plz](https://github.com/release-plz/release-plz/). --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Orhun Parmaksız <[email protected]>
Summary
ratatui-terminabackend crate using the publishedterminacrateterminafeature and Ratatui prelude/backend re-exportsRefs #1784
Validation
cargo +nightly fmtcargo check -p ratatui-termina --all-features --all-targetscargo check -p ratatui --no-default-features --features terminacargo check -p xtaskcargo check -p release-headercargo xtask check-backend terminacargo xtask test-backend terminacargo xtask rdme --checkmarkdownlint-cli2 ARCHITECTURE.md ratatui-termina/README.md .github/ISSUE_TEMPLATE/bug_report.md