fix: Align clear() semantics with contract (#2320)

Bumps
[taiki-e/install-action](https://github.com/taiki-e/install-action) from
2.65.13 to 2.66.1.
<details>
<summary>Release notes</summary>
<p><em>Sourced from <a
href="https://github.com/taiki-e/install-action/releases">taiki-e/install-action's
releases</a>.</em></p>
<blockquote>
<h2>2.66.1</h2>
<ul>
<li>
<p>Update <code>tombi@latest</code> to 0.7.18.</p>
</li>
<li>
<p>Update <code>ubi@latest</code> to 0.9.0.</p>
</li>
</ul>
<h2>2.66.0</h2>
<ul>
<li>
<p>Support <code>mdbook-mermaid-ssr</code>. (<a
href="https://redirect.github.com/taiki-e/install-action/pull/1400">#1400</a>,
thanks <a
href="https://github.com/CommanderStorm"><code>@​CommanderStorm</code></a>)</p>
</li>
<li>
<p>Improve support for Windows with MSYS2 bash.</p>
</li>
<li>
<p>Documentation improvements.</p>
</li>
</ul>
<h2>2.65.16</h2>
<ul>
<li>
<p>Update <code>zola@latest</code> to 0.22.0.</p>
</li>
<li>
<p>Update <code>wasmtime@latest</code> to 40.0.1.</p>
</li>
<li>
<p>Update <code>vacuum@latest</code> to 0.23.2.</p>
</li>
<li>
<p>Update <code>uv@latest</code> to 0.9.24.</p>
</li>
<li>
<p>Update <code>typos@latest</code> to 1.42.0.</p>
</li>
<li>
<p>Update <code>tombi@latest</code> to 0.7.16.</p>
</li>
<li>
<p>Update <code>syft@latest</code> to 1.40.0.</p>
</li>
<li>
<p>Update <code>protoc@latest</code> to 3.33.3.</p>
</li>
<li>
<p>Update <code>prek@latest</code> to 0.2.27.</p>
</li>
<li>
<p>Update <code>mise@latest</code> to 2026.1.1.</p>
</li>
<li>
<p>Update <code>cargo-nextest@latest</code> to 0.9.120.</p>
</li>
<li>
<p>Update <code>cargo-deny@latest</code> to 0.19.0.</p>
</li>
</ul>
<h2>2.65.15</h2>
<ul>
<li>
<p>Update <code>parse-dockerfile@latest</code> to 0.1.3.</p>
</li>
<li>
<p>Update <code>parse-changelog@latest</code> to 0.6.15.</p>
</li>
<li>
<p>Update <code>cargo-llvm-cov@latest</code> to 0.6.23.</p>
</li>
<li>
<p>Update <code>cargo-hack@latest</code> to 0.6.41.</p>
</li>
<li>
<p>Update <code>cargo-minimal-versions@latest</code> to 0.1.35.</p>
</li>
<li>
<p>Update <code>cargo-no-dev-deps@latest</code> to 0.2.20.</p>
</li>
</ul>
<!-- raw HTML omitted -->
</blockquote>
<p>... (truncated)</p>
</details>
<details>
<summary>Changelog</summary>
<p><em>Sourced from <a
href="https://github.com/taiki-e/install-action/blob/main/CHANGELOG.md">taiki-e/install-action's
changelog</a>.</em></p>
<blockquote>
<h1>Changelog</h1>
<p>All notable changes to this project will be documented in this
file.</p>
<p>This project adheres to <a href="https://semver.org">Semantic
Versioning</a>.</p>
<!-- raw HTML omitted -->
<h2>[Unreleased]</h2>
<ul>
<li>
<p>Update <code>protoc@latest</code> to 3.33.4.</p>
</li>
<li>
<p>Update <code>knope@latest</code> to 0.22.0.</p>
</li>
</ul>
<h2>[2.66.1] - 2026-01-11</h2>
<ul>
<li>
<p>Update <code>tombi@latest</code> to 0.7.18.</p>
</li>
<li>
<p>Update <code>ubi@latest</code> to 0.9.0.</p>
</li>
</ul>
<h2>[2.66.0] - 2026-01-10</h2>
<ul>
<li>
<p>Support <code>mdbook-mermaid-ssr</code>. (<a
href="https://redirect.github.com/taiki-e/install-action/pull/1400">#1400</a>,
thanks <a
href="https://github.com/CommanderStorm"><code>@​CommanderStorm</code></a>)</p>
</li>
<li>
<p>Improve support for Windows with MSYS2 bash.</p>
</li>
<li>
<p>Documentation improvements.</p>
</li>
</ul>
<h2>[2.65.16] - 2026-01-10</h2>
<ul>
<li>
<p>Update <code>zola@latest</code> to 0.22.0.</p>
</li>
<li>
<p>Update <code>wasmtime@latest</code> to 40.0.1.</p>
</li>
<li>
<p>Update <code>vacuum@latest</code> to 0.23.2.</p>
</li>
<li>
<p>Update <code>uv@latest</code> to 0.9.24.</p>
</li>
<li>
<p>Update <code>typos@latest</code> to 1.42.0.</p>
</li>
<li>
<p>Update <code>tombi@latest</code> to 0.7.16.</p>
</li>
<li>
<p>Update <code>syft@latest</code> to 1.40.0.</p>
</li>
<li>
<p>Update <code>protoc@latest</code> to 3.33.3.</p>
</li>
<li>
<p>Update <code>prek@latest</code> to 0.2.27.</p>
</li>
</ul>
<!-- raw HTML omitted -->
</blockquote>
<p>... (truncated)</p>
</details>
<details>
<summary>Commits</summary>
<ul>
<li><a
href="3522286d40"><code>3522286</code></a>
Release 2.66.1</li>
<li><a
href="0ed1c967ed"><code>0ed1c96</code></a>
Update changelog</li>
<li><a
href="e69513dca4"><code>e69513d</code></a>
Update <code>tombi@latest</code> to 0.7.18</li>
<li><a
href="4c5e3dc538"><code>4c5e3dc</code></a>
Update <code>ubi@latest</code> to 0.9.0</li>
<li><a
href="e2cc276530"><code>e2cc276</code></a>
Update <code>tombi@latest</code> to 0.7.17</li>
<li><a
href="8fb4e4b842"><code>8fb4e4b</code></a>
Update .deny.toml</li>
<li><a
href="83961fc0a2"><code>83961fc</code></a>
Release 2.66.0</li>
<li><a
href="c761556c39"><code>c761556</code></a>
Update changelog</li>
<li><a
href="f19ed92a93"><code>f19ed92</code></a>
Workaround MSYS2 bash issue</li>
<li><a
href="e53d9e37e3"><code>e53d9e3</code></a>
docs: Clarify &quot;tool is supported&quot; doesn't mean &quot;tool is
trusted or reviewed b...</li>
<li>Additional commits viewable in <a
href="0e76c5c569...3522286d40">compare
view</a></li>
</ul>
</details>
<br />


[![Dependabot compatibility
score](https://dependabot-badges.githubapp.com/badges/compatibility_score?dependency-name=taiki-e/install-action&package-manager=github_actions&previous-version=2.65.13&new-version=2.66.1)](https://docs.github.com/en/github/managing-security-vulnerabilities/about-dependabot-security-updates#about-compatibility-scores)

Dependabot will resolve any conflicts with this PR as long as you don't
alter it yourself. You can also trigger a rebase manually by commenting
`@dependabot rebase`.

[//]: # (dependabot-automerge-start)
[//]: # (dependabot-automerge-end)

---

<details>
<summary>Dependabot commands and options</summary>
<br />

You can trigger Dependabot actions by commenting on this PR:
- `@dependabot rebase` will rebase this PR
- `@dependabot recreate` will recreate this PR, overwriting any edits
that have been made to it
- `@dependabot merge` will merge this PR after your CI passes on it
- `@dependabot squash and merge` will squash and merge this PR after
your CI passes on it
- `@dependabot cancel merge` will cancel a previously requested merge
and block automerging
- `@dependabot reopen` will reopen this PR if it is closed
- `@dependabot close` will close this PR and stop Dependabot recreating
it. You can achieve the same result by closing it manually
- `@dependabot show <dependency name> ignore conditions` will show all
of the ignore conditions of the specified dependency
- `@dependabot ignore this major version` will close this PR and stop
Dependabot creating any more for this major version (unless you reopen
the PR or upgrade to it yourself)
- `@dependabot ignore this minor version` will close this PR and stop
Dependabot creating any more for this minor version (unless you reopen
the PR or upgrade to it yourself)
- `@dependabot ignore this dependency` will close this PR and stop
Dependabot creating any more for this dependency (unless you reopen the
PR or upgrade to it yourself)


</details>

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

.github/ISSUE_TEMPLATE/bug_report.md

@@ -13,27 +13,43 @@ A detailed and complete issue is more likely to be processed quickly.
 -->
 
 ## Description
+
 <!--
 A clear and concise description of what the bug is.
 -->
 
 ## To Reproduce
+
 <!--
 Try to reduce the issue to a simple code sample exhibiting the problem.
 Ideally, fork the project and add a test or an example.
 -->
 
 ## Expected behavior
+
 <!--
 A clear and concise description of what you expected to happen.
 -->
 
 ## Screenshots
+
 <!--
 If applicable, add screenshots, gifs or videos to help explain your problem.
 -->
 
+## Are you willing to contribute a fix?
+
+<!--
+If you would like to work on a fix, check one of the boxes below. Maintainers can help point
+you to the right place in the codebase.
+-->
+
+- [ ] I am willing to open a PR for this bug.
+- [ ] I can try to investigate, but I will need guidance.
+- [ ] I am not able to work on a fix right now.
+
 ## Environment
+
 <!--
 Add a description of the systems where you are observing the issue. For example:
 - OS: Linux
@@ -50,6 +66,7 @@ Add a description of the systems where you are observing the issue. For example:
 - Backend:
 
 ## Additional context
+
 <!--
 Add any other context about the problem here.
 If you already looked into the issue, include all the leads you have explored.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -8,11 +8,13 @@ assignees: ''
 ---
 
 ## Problem
+
 <!--
 A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
 -->
 
 ## Solution
+
 <!--
 A clear and concise description of what you want to happen.
 Things to consider:
@@ -22,11 +24,24 @@ Things to consider:
 -->
 
 ## Alternatives
+
 <!--
 A clear and concise description of any alternative solutions or features you've considered.
 -->
 
+## Are you willing to contribute an implementation?
+
+<!--
+If you would like to work on this, check one of the boxes below. Maintainers can help refine
+the scope and discuss approach.
+-->
+
+- [ ] I am willing to open a PR implementing this.
+- [ ] I can try to implement it, but I will need guidance.
+- [ ] I am not able to implement this right now.
+
 ## Additional context
+
 <!--
 Add any other context or screenshots about the feature request here.
 -->

.github/workflows/check-semver.yml

@@ -15,7 +15,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout the repository
-        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
         with:
           persist-credentials: false
       - name: Check semver

.github/workflows/ci.yml

@@ -29,15 +29,15 @@ jobs:
     name: Check Formatting
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
         with:
           persist-credentials: false
-      - uses: dtolnay/rust-toolchain@6d653acede28d24f02e3cd41383119e8b1b35921 # master
+      - uses: dtolnay/rust-toolchain@f7ccc83f9ed1e5b9c81d8a67d7ad1a747e22a561 # master
         with:
           toolchain: nightly
           components: rustfmt
-      - uses: Swatinem/rust-cache@f13886b937689c021905a6b90929199931d60db1 # v2
-      - uses: taiki-e/install-action@c5b1b6f479c32f356cc6f4ba672a47f63853b13b # v2
+      - uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5 # v2
+      - uses: taiki-e/install-action@3522286d40783523f9c7880e33f785905b4c20d0 # v2
         with:
           tool: taplo-cli
       - run: cargo xtask format --check
@@ -48,27 +48,32 @@ jobs:
     name: Check Typos
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
         with:
           persist-credentials: false
-      - uses: crate-ci/typos@80c8a4945eec0f6d464eaf9e65ed98ef085283d1 # master
+      - uses: crate-ci/typos@bb4666ad77b539a6b4ce4eda7ebb6de553704021 # master
 
   # Check for any disallowed dependencies in the codebase due to license / security issues.
   # See <https://github.com/EmbarkStudios/cargo-deny>
-  dependencies:
-    name: Check Dependencies
+  cargo-deny:
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        checks:
+          - advisories
+          - bans licenses sources
+    # Prevent sudden announcement of a new advisory from failing ci:
+    continue-on-error: ${{ matrix.checks == 'advisories' }}
     steps:
-      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
         with:
           persist-credentials: false
-      - uses: dtolnay/rust-toolchain@6d653acede28d24f02e3cd41383119e8b1b35921 # master
+      - uses: EmbarkStudios/cargo-deny-action@3fd3802e88374d3fe9159b834c7714ec57d6c979 # v2
         with:
-          toolchain: stable
-      - uses: taiki-e/install-action@c5b1b6f479c32f356cc6f4ba672a47f63853b13b # v2
-        with:
-          tool: cargo-deny
-      - run: cargo deny --log-level info --all-features check
+          rust-toolchain: stable
+          log-level: info
+          arguments: --all-features --exclude-unpublished
+          command: check ${{ matrix.checks }}
 
   # Check for any unused dependencies in the codebase.
   # See <https://github.com/bnjbvr/cargo-machete/>
@@ -76,7 +81,7 @@ jobs:
     name: Check Unused Dependencies
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
         with:
           persist-credentials: false
       - uses: bnjbvr/cargo-machete@7959c845782fed02ee69303126d4a12d64f1db18 # v0.9.1
@@ -95,14 +100,14 @@ jobs:
         toolchain: ["stable", "beta"]
     continue-on-error: ${{ matrix.toolchain == 'beta' }}
     steps:
-      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
         with:
           persist-credentials: false
-      - uses: dtolnay/rust-toolchain@6d653acede28d24f02e3cd41383119e8b1b35921 # master
+      - uses: dtolnay/rust-toolchain@f7ccc83f9ed1e5b9c81d8a67d7ad1a747e22a561 # master
         with:
           toolchain: ${{ matrix.toolchain }}
           components: clippy
-      - uses: Swatinem/rust-cache@f13886b937689c021905a6b90929199931d60db1 # v2
+      - uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5 # v2
       - run: cargo xtask clippy
         env:
           RUSTUP_TOOLCHAIN: ${{ matrix.toolchain }}
@@ -112,10 +117,10 @@ jobs:
     name: Check Markdown
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
         with:
           persist-credentials: false
-      - uses: DavidAnson/markdownlint-cli2-action@992badcdf24e3b8eb7e87ff9287fe931bcb00c6e # v20
+      - uses: DavidAnson/markdownlint-cli2-action@07035fd053f7be764496c0f8d8f9f41f98305101 # v21
         with:
           globs: |
             '**/*.md'
@@ -127,19 +132,19 @@ jobs:
     name: Coverage Report
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
         with:
           persist-credentials: false
-      - uses: dtolnay/rust-toolchain@6d653acede28d24f02e3cd41383119e8b1b35921 # master
+      - uses: dtolnay/rust-toolchain@f7ccc83f9ed1e5b9c81d8a67d7ad1a747e22a561 # master
         with:
           toolchain: stable
           components: llvm-tools
-      - uses: taiki-e/install-action@c5b1b6f479c32f356cc6f4ba672a47f63853b13b # v2
+      - uses: taiki-e/install-action@3522286d40783523f9c7880e33f785905b4c20d0 # v2
         with:
           tool: cargo-llvm-cov
-      - uses: Swatinem/rust-cache@f13886b937689c021905a6b90929199931d60db1 # v2
+      - uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5 # v2
       - run: cargo xtask coverage
-      - uses: codecov/codecov-action@5a1091511ad55cbe89839c7260b706298ca349f7 # v5
+      - uses: codecov/codecov-action@671740ac38dd9b0130fbe1cec585b89eea48d3de # v5
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
           fail_ci_if_error: true
@@ -151,19 +156,19 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, windows-latest, macos-latest]
-        toolchain: ["1.85.0", "stable"]
+        toolchain: ["1.86.0", "stable"]
     runs-on: ${{ matrix.os }}
     steps:
-      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
         with:
           persist-credentials: false
-      - uses: dtolnay/rust-toolchain@6d653acede28d24f02e3cd41383119e8b1b35921 # master
+      - uses: dtolnay/rust-toolchain@f7ccc83f9ed1e5b9c81d8a67d7ad1a747e22a561 # master
         with:
           toolchain: ${{ matrix.toolchain }}
-      - uses: taiki-e/install-action@c5b1b6f479c32f356cc6f4ba672a47f63853b13b # v2
+      - uses: taiki-e/install-action@3522286d40783523f9c7880e33f785905b4c20d0 # v2
         with:
           tool: cargo-hack
-      - uses: Swatinem/rust-cache@f13886b937689c021905a6b90929199931d60db1 # v2
+      - uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5 # v2
       - run: cargo xtask check --all-features
         env:
           RUSTUP_TOOLCHAIN: ${{ matrix.toolchain }}
@@ -172,14 +177,14 @@ jobs:
     name: Build No-Std
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
         with:
           persist-credentials: false
-      - uses: dtolnay/rust-toolchain@6d653acede28d24f02e3cd41383119e8b1b35921 # master
+      - uses: dtolnay/rust-toolchain@f7ccc83f9ed1e5b9c81d8a67d7ad1a747e22a561 # master
         with:
           toolchain: stable
           targets: x86_64-unknown-none
-      - uses: Swatinem/rust-cache@f13886b937689c021905a6b90929199931d60db1 # v2
+      - uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5 # v2
       # This makes it easier to debug the exact versions of the dependencies
       - run: cargo tree --target x86_64-unknown-none -p ratatui-core
       - run: cargo tree --target x86_64-unknown-none -p ratatui-widgets
@@ -195,11 +200,11 @@ jobs:
     name: Check README
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
         with:
           persist-credentials: false
-      - uses: Swatinem/rust-cache@f13886b937689c021905a6b90929199931d60db1 # v2
-      - uses: taiki-e/install-action@c5b1b6f479c32f356cc6f4ba672a47f63853b13b # v2
+      - uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5 # v2
+      - uses: taiki-e/install-action@3522286d40783523f9c7880e33f785905b4c20d0 # v2
         with:
           tool: cargo-rdme
       - run: cargo xtask readme --check
@@ -212,19 +217,19 @@ jobs:
     env:
       RUSTDOCFLAGS: -Dwarnings
     steps:
-      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
         with:
           persist-credentials: false
-      - uses: dtolnay/rust-toolchain@6d653acede28d24f02e3cd41383119e8b1b35921 # master
+      - uses: dtolnay/rust-toolchain@f7ccc83f9ed1e5b9c81d8a67d7ad1a747e22a561 # master
         with:
           toolchain: nightly
       - uses: dtolnay/install@74f735cdf643820234e37ae1c4089a08fd266d8a # master
         with:
           crate: cargo-docs-rs
-      - uses: taiki-e/install-action@c5b1b6f479c32f356cc6f4ba672a47f63853b13b # v2
+      - uses: taiki-e/install-action@3522286d40783523f9c7880e33f785905b4c20d0 # v2
         with:
           tool: cargo-hack
-      - uses: Swatinem/rust-cache@f13886b937689c021905a6b90929199931d60db1 # v2
+      - uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5 # v2
       - run: cargo xtask docs
 
   # Run cargo test on the documentation of the crate. This will catch any code examples that don't
@@ -233,16 +238,16 @@ jobs:
     name: Test Docs
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
         with:
           persist-credentials: false
-      - uses: dtolnay/rust-toolchain@6d653acede28d24f02e3cd41383119e8b1b35921 # master
+      - uses: dtolnay/rust-toolchain@f7ccc83f9ed1e5b9c81d8a67d7ad1a747e22a561 # master
         with:
           toolchain: stable
-      - uses: taiki-e/install-action@c5b1b6f479c32f356cc6f4ba672a47f63853b13b # v2
+      - uses: taiki-e/install-action@3522286d40783523f9c7880e33f785905b4c20d0 # v2
         with:
           tool: cargo-hack
-      - uses: Swatinem/rust-cache@f13886b937689c021905a6b90929199931d60db1 # v2
+      - uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5 # v2
       - run: cargo xtask test-docs
 
   # Run cargo test on the libraries of the crate.
@@ -252,18 +257,18 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        toolchain: ["1.85.0", "stable"]
+        toolchain: ["1.86.0", "stable"]
     steps:
-      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
         with:
           persist-credentials: false
-      - uses: dtolnay/rust-toolchain@6d653acede28d24f02e3cd41383119e8b1b35921 # master
+      - uses: dtolnay/rust-toolchain@f7ccc83f9ed1e5b9c81d8a67d7ad1a747e22a561 # master
         with:
           toolchain: stable
-      - uses: taiki-e/install-action@c5b1b6f479c32f356cc6f4ba672a47f63853b13b # v2
+      - uses: taiki-e/install-action@3522286d40783523f9c7880e33f785905b4c20d0 # v2
         with:
           tool: cargo-hack
-      - uses: Swatinem/rust-cache@f13886b937689c021905a6b90929199931d60db1 # v2
+      - uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5 # v2
       - run: cargo xtask test-libs
 
   # Run cargo test on all the backends.
@@ -280,11 +285,11 @@ jobs:
           - os: windows-latest
             backend: termion
     steps:
-      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
         with:
           persist-credentials: false
-      - uses: dtolnay/rust-toolchain@6d653acede28d24f02e3cd41383119e8b1b35921 # master
+      - uses: dtolnay/rust-toolchain@f7ccc83f9ed1e5b9c81d8a67d7ad1a747e22a561 # master
         with:
           toolchain: stable
-      - uses: Swatinem/rust-cache@f13886b937689c021905a6b90929199931d60db1 # v2
+      - uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5 # v2
       - run: cargo xtask test-backend ${{ matrix.backend }}

.github/workflows/release-plz.yml

@@ -23,18 +23,18 @@ jobs:
     if: ${{ github.repository_owner == 'ratatui' }}
     steps:
       - name: Checkout repository
-        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
         with:
           fetch-depth: 0
           persist-credentials: false
       - name: Install Rust toolchain
-        uses: dtolnay/rust-toolchain@6d653acede28d24f02e3cd41383119e8b1b35921 # master
+        uses: dtolnay/rust-toolchain@f7ccc83f9ed1e5b9c81d8a67d7ad1a747e22a561 # master
         with:
           toolchain: stable
-      - uses: rust-lang/crates-io-auth-action@041cce5b4b821e6b0ebc9c9c38b58cac4e34dcc2 # v1
+      - uses: rust-lang/crates-io-auth-action@b7e9a28eded4986ec6b1fa40eeee8f8f165559ec # v1
         id: auth
       - name: Run release-plz
-        uses: release-plz/action@d529f731ae3e89610ada96eda34e5c6ba3b12214 # v0.5
+        uses: release-plz/action@487eb7b5c085a664d5c5ca05f4159bd9b591182a # v0.5
         with:
           command: release
         env:
@@ -54,16 +54,16 @@ jobs:
       cancel-in-progress: false
     steps:
       - name: Checkout repository
-        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
         with:
           fetch-depth: 0
           persist-credentials: false
       - name: Install Rust toolchain
-        uses: dtolnay/rust-toolchain@6d653acede28d24f02e3cd41383119e8b1b35921 # master
+        uses: dtolnay/rust-toolchain@f7ccc83f9ed1e5b9c81d8a67d7ad1a747e22a561 # master
         with:
           toolchain: stable
       - name: Run release-plz
-        uses: release-plz/action@d529f731ae3e89610ada96eda34e5c6ba3b12214 # v0.5
+        uses: release-plz/action@487eb7b5c085a664d5c5ca05f4159bd9b591182a # v0.5
         with:
           command: release-pr
         env:

.github/workflows/zizmor.yml

@@ -18,9 +18,9 @@ jobs:
       security-events: write
     steps:
       - name: Checkout repository
-        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
         with:
           persist-credentials: false
 
       - name: Run zizmor 🌈
-        uses: zizmorcore/zizmor-action@e673c3917a1aef3c65c972347ed84ccd013ecda4 # v0.2.0
+        uses: zizmorcore/zizmor-action@e639db99335bc9038abc0e066dfcd72e23d26fb4 # v0.3.0

BREAKING-CHANGES.md

@@ -10,7 +10,9 @@ GitHub with a [breaking change] label.
 
 This is a quick summary of the sections below:
 
-- [v0.30.0 Unreleased](#v0300-unreleased)
+- [v0.30.1](#v0301)
+  - Adding `AsRef` impls for widgets may affect type inference in rare cases
+- [v0.30.0](#v0300)
   - `Flex::SpaceAround` now mirrors flexbox: space between items is twice the size of the outer gaps
     are twice the size of first and last elements
   - `block::Title` no longer exists
@@ -18,7 +20,7 @@ This is a quick summary of the sections below:
   - `FrameExt` trait for `unstable-widget-ref` feature
   - `List::highlight_symbol` now accepts `Into<Line>` instead of `&str`
   - 'layout::Alignment' is renamed to 'layout::HorizontalAlignment'
-  - The MSRV is now 1.85.0
+  - MSRV is now 1.86.0
   - `Backend` now requires an associated `Error` type and `clear_region` method
   - `TestBackend` now uses `core::convert::Infallible` for error handling instead of `std::io::Error`
   - Disabling `default-features` will now disable layout cache, which can have a negative impact on performance
@@ -27,6 +29,9 @@ This is a quick summary of the sections below:
   - Disabling `default-features` suppresses the error message if `show_cursor()` fails when dropping
     `Terminal`
   - Support a broader range for `unicode-width` version
+  - `Marker` is now non-exhaustive
+  - `symbols::braille::BLANK` and `symbols::braille::DOTS` have been removed in favor of an ordered
+    array of all Braille characters
 - [v0.29.0](#v0290)
   - `Sparkline::data` takes `IntoIterator<Item = SparklineBar>` instead of `&[u64]` and is no longer
     const
@@ -90,7 +95,36 @@ This is a quick summary of the sections below:
   - MSRV is now 1.63.0
   - `List` no longer ignores empty strings
 
-## v0.30.0 Unreleased
+## [v0.30.1](https://github.com/ratatui/ratatui/releases/tag/ratatui-v0.30.1)
+
+### Adding `AsRef` impls for widgets may affect type inference ([#2297])
+
+[#2297]: https://github.com/ratatui/ratatui/pull/2297
+
+Adding `AsRef<Self>` for built-in widgets can change type inference outcomes in rare cases where
+`AsRef` is part of a trait bound, and can also conflict with downstream blanket or manual `AsRef`
+impls for widget types. If you hit new ambiguity errors, add explicit type annotations or specify
+the concrete widget type to guide inference, and remove any redundant `AsRef` impls.
+
+## [v0.30.0](https://github.com/ratatui/ratatui/releases/tag/ratatui-v0.30.0)
+
+### `Marker` is now non-exhaustive ([#2236])
+
+[#2236]: https://github.com/ratatui/ratatui/pull/2236
+
+The `Marker` enum is now marked as `#[non_exhaustive]`, if you were matching on `Marker` exhaustively,
+you will need to add a wildcard arm:
+
+```diff
+  match marker {
+      Marker::Dot => { /* ... */ }
+      Marker::Block => { /* ... */ }
+      Marker::Bar => { /* ... */ }
+      Marker::Braille => { /* ... */ }
+      Marker::HalfBlock => { /* ... */ }
++     _ => { /* ... */ }
+  }
+```
 
 ### `Flex::SpaceAround` now mirrors flexbox: space between items is twice the size of the outer gaps ([#1952])
 
@@ -235,11 +269,11 @@ instead.
 + fn run(mut terminal: DefaultTerminal) -> io::Result<()> {
 ```
 
-### The MSRV is now 1.85.0 ([#1860])
+### MSRV is now 1.86.0 ([#2230])
 
-[#1860]: https://github.com/ratatui/ratatui/pull/1860
+[#2230]: https://github.com/ratatui/ratatui/pull/2230
 
-The minimum supported Rust version (MSRV) is now 1.85.0.
+The minimum supported Rust version (MSRV) is now 1.86.0.
 
 ### `layout::Alignment` is renamed to `layout::HorizontalAlignment` ([#1735])
 
@@ -1087,7 +1121,7 @@ previously did not need to use type annotations to fail to compile. To fix this,
 
 [#133]: https://github.com/ratatui/ratatui/issues/133
 
-Code using the `Block` marker that previously rendered using a half block character (`'▀'``) now
+Code using the `Block` marker that previously rendered using a half block character (`'▀'`) now
 renders using the full block character (`'█'`). A new marker variant`Bar` is introduced to replace
 the existing code.
 

Cargo.toml

@@ -25,7 +25,7 @@ readme = "README.md"
 license = "MIT"
 exclude = ["assets/*", ".github", "Makefile.toml", "CONTRIBUTING.md", "*.log", "tags"]
 edition = "2024"
-rust-version = "1.85.0"
+rust-version = "1.86.0"
 
 [workspace.dependencies]
 anstyle = "1"
@@ -33,7 +33,7 @@ bitflags = "2.10"
 clap = { version = "4.5", features = ["derive"] }
 color-eyre = "0.6"
 compact_str = { version = "0.9", default-features = false }
-criterion = { version = "0.7", features = ["html_reports"] }
+criterion = { version = "0.8", features = ["html_reports"] }
 crossterm = "0.29"
 document-features = "0.2"
 fakeit = "1"
@@ -45,18 +45,18 @@ itertools = { version = "0.14", default-features = false, features = ["use_alloc
 kasuari = { version = "0.4", default-features = false }
 line-clipping = "0.3"
 lru = "0.16"
-octocrab = "0.47"
+octocrab = "0.49"
 palette = "0.7"
 pretty_assertions = "1"
 rand = "0.9"
 rand_chacha = "0.9"
-ratatui = { path = "ratatui", version = "0.30.0-beta.0" }
-ratatui-core = { path = "ratatui-core", version = "0.1.0-beta.0" }
-ratatui-crossterm = { path = "ratatui-crossterm", version = "0.1.0-beta.0" }
-ratatui-macros = { path = "ratatui-macros", version = "0.7.0-beta.0" }
-ratatui-termion = { path = "ratatui-termion", version = "0.1.0-beta.0" }
-ratatui-termwiz = { path = "ratatui-termwiz", version = "0.1.0-beta.0" }
-ratatui-widgets = { path = "ratatui-widgets", version = "0.3.0-beta.0" }
+ratatui = { path = "ratatui", version = "0.30.0" }
+ratatui-core = { path = "ratatui-core", version = "0.1.0" }
+ratatui-crossterm = { path = "ratatui-crossterm", version = "0.1.0" }
+ratatui-macros = { path = "ratatui-macros", version = "0.7.0" }
+ratatui-termion = { path = "ratatui-termion", version = "0.1.0" }
+ratatui-termwiz = { path = "ratatui-termwiz", version = "0.1.0" }
+ratatui-widgets = { path = "ratatui-widgets", version = "0.3.0" }
 rstest = "0.26"
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
@@ -64,7 +64,7 @@ strum = { version = "0.27", default-features = false, features = ["derive"] }
 termion = "4"
 termwiz = "0.23"
 thiserror = { version = "2", default-features = false }
-time = { version = "0.3", default-features = false }
+time = { version = "0.3.37", default-features = false }
 tokio = "1"
 tokio-stream = "0.1"
 tracing = "0.1"
@@ -107,6 +107,7 @@ empty_line_after_doc_comments = "warn"
 equatable_if_let = "warn"
 fn_to_numeric_cast_any = "warn"
 format_push_string = "warn"
+implicit_clone = "warn"
 map_err_ignore = "warn"
 missing_const_for_fn = "warn"
 mixed_read_write_in_expression = "warn"
@@ -118,6 +119,5 @@ redundant_type_annotations = "warn"
 rest_pat_in_fully_bound_structs = "warn"
 string_lit_chars_any = "warn"
 string_slice = "warn"
-string_to_string = "warn"
 unnecessary_self_imports = "warn"
 use_self = "warn"

cliff.toml

@@ -34,7 +34,7 @@ body = """
 {% macro commit(commit) -%}
 - [{{ commit.id | truncate(length=7, end="") }}]({{ "https://github.com/ratatui/ratatui/commit/" ~ commit.id }}) \
   *({{commit.scope | default(value = "uncategorized") | lower }})* {{ commit.message | upper_first | trim }}\
-  {% if commit.remote.username %} by @{{ commit.remote.username }}{%- endif -%}\
+  {% if commit.remote.username %} by `@{{ commit.remote.username }}`{%- endif -%}\
   {% if commit.remote.pr_number %} in [#{{ commit.remote.pr_number }}]({{ self::remote_url() }}/pull/{{ commit.remote.pr_number }}){%- endif %}\
 {%- if commit.breaking %} [**breaking**]{% endif %}
 {%- if commit.body %}\n\n{{ commit.body | indent(prefix="  > ", first=true, blank=true) }}
@@ -123,6 +123,7 @@ commit_preprocessors = [
   { pattern = '\<[f]eatuers\>', replace = "features" },
   { pattern = '\<[s]pecically\>', replace = "specially" },
   { pattern = '\<[g]ague\>', replace = "gauge" },
+  { pattern = '\<[a]rithmentic\>', replace = "arithmetic" },
   { pattern = '\<[i]ntructions\>', replace = "instructions" },
   { pattern = '\<[i]mplementated\>', replace = "implemented" },
 ]

examples/README.md

@@ -206,7 +206,7 @@ Shows how to use the [tracing](https://crates.io/crates/tracing) crate to log to
 
 ## User Input
 
-Shows how to handle user input. [Source](./apps/user-input/). [Source](./apps/user-input/).
+Shows how to handle user input. [Source](./apps/user-input/).
 
 ![User input demo][user-input.gif]
 

examples/apps/canvas/src/main.rs

@@ -122,8 +122,12 @@ impl App {
             Marker::Dot => Marker::Braille,
             Marker::Braille => Marker::Block,
             Marker::Block => Marker::HalfBlock,
-            Marker::HalfBlock => Marker::Bar,
+            Marker::HalfBlock => Marker::Quadrant,
+            Marker::Quadrant => Marker::Sextant,
+            Marker::Sextant => Marker::Octant,
+            Marker::Octant => Marker::Bar,
             Marker::Bar => Marker::Dot,
+            _ => unreachable!(),
         };
     }
 

examples/apps/constraint-explorer/src/main.rs

@@ -1,3 +1,5 @@
+use std::cmp::Ordering;
+
 /// A Ratatui example that demonstrates how different layout constraints work.
 ///
 /// It also supports swapping constraints, adding and removing blocks, and changing the spacing
@@ -30,7 +32,7 @@ fn main() -> Result<()> {
 #[derive(Default)]
 struct App {
     mode: AppMode,
-    spacing: u16,
+    spacing: i16,
     constraints: Vec<Constraint>,
     selected_index: usize,
     value: u16,
@@ -269,7 +271,7 @@ impl App {
     }
 
     fn instructions() -> impl Widget {
-        let text = "◄ ►: select, ▲ ▼: edit, 1-6: swap, a: add, x: delete, q: quit, + -: spacing";
+        let text = "◄ ►: select, ▲ ▼: edit, 1-6: swap, a: add, x: delete, q: quit, +/-: spacing";
         Paragraph::new(text)
             .fg(Self::TEXT_COLOR)
             .centered()
@@ -307,10 +309,12 @@ impl App {
     ///
     /// Only shows the gap when spacing is not zero
     fn axis(&self, width: u16) -> impl Widget {
-        let label = if self.spacing != 0 {
-            format!("{} px (gap: {} px)", width, self.spacing)
-        } else {
-            format!("{width} px")
+        let label = match self.spacing.cmp(&0) {
+            Ordering::Greater => format!("{width} px (gap: {} px)", self.spacing),
+            Ordering::Less => {
+                format!("{width} px (overlap: {} px)", self.spacing.unsigned_abs())
+            }
+            Ordering::Equal => format!("{width} px"),
         };
         let bar_width = width.saturating_sub(2) as usize; // we want to `<` and `>` at the ends
         let width_bar = format!("<{label:-^bar_width$}>");

examples/apps/input-form/src/main.rs

@@ -123,9 +123,9 @@ impl InputForm {
         frame.render_widget(&self.age, age_area);
 
         let cursor_position = match self.focus {
-            Focus::FirstName => first_name_area.offset(self.first_name.cursor_offset()),
-            Focus::LastName => last_name_area.offset(self.last_name.cursor_offset()),
-            Focus::Age => age_area.offset(self.age.cursor_offset()),
+            Focus::FirstName => first_name_area + self.first_name.cursor_offset(),
+            Focus::LastName => last_name_area + self.last_name.cursor_offset(),
+            Focus::Age => age_area + self.age.cursor_offset(),
         };
         frame.set_cursor_position(cursor_position);
     }

examples/apps/popup/src/main.rs

@@ -11,10 +11,10 @@
 use color_eyre::Result;
 use crossterm::event::{self, KeyCode};
 use ratatui::Frame;
-use ratatui::layout::{Constraint, Flex, Layout, Rect};
+use ratatui::layout::{Constraint, Layout};
 use ratatui::style::Stylize;
 use ratatui::text::Line;
-use ratatui::widgets::{Block, Clear};
+use ratatui::widgets::{Block, Clear, Paragraph};
 
 fn main() -> Result<()> {
     color_eyre::install()?;
@@ -52,19 +52,14 @@ fn render(frame: &mut Frame, show_popup: bool) {
     frame.render_widget(Block::bordered().title("Content").on_blue(), content);
 
     if show_popup {
-        let popup = Block::bordered().title("Popup");
-        let popup_area = centered_area(area, 60, 20);
+        let popup_block = Block::bordered().title("Popup");
+        let centered_area = area.centered(Constraint::Percentage(60), Constraint::Percentage(20));
         // clears out any background in the area before rendering the popup
-        frame.render_widget(Clear, popup_area);
-        frame.render_widget(popup, popup_area);
+        frame.render_widget(Clear, centered_area);
+        let paragraph = Paragraph::new("Lorem ipsum").block(popup_block);
+        frame.render_widget(paragraph, centered_area);
+        // another solution is to use the inner area of the block
+        // let inner_area = popup_block.inner(centered_area);
+        // frame.render_widget(your_widget, inner_area);
     }
 }
-
-/// Create a centered rect using up certain percentage of the available rect
-fn centered_area(area: Rect, percent_x: u16, percent_y: u16) -> Rect {
-    let vertical = Layout::vertical([Constraint::Percentage(percent_y)]).flex(Flex::Center);
-    let horizontal = Layout::horizontal([Constraint::Percentage(percent_x)]).flex(Flex::Center);
-    let [area] = area.layout(&vertical);
-    let [area] = area.layout(&horizontal);
-    area
-}

examples/apps/table/src/main.rs

@@ -222,6 +222,19 @@ impl App {
             let item = data.ref_array();
             item.into_iter()
                 .map(|content| Cell::from(Text::from(format!("\n{content}\n"))))
+                .enumerate()
+                .map(|(idx, cell)| {
+                    if i == 3 && idx == 1 {
+                        Cell::from(Text::from(
+                            // Gratuitously long error message to demonstrate column_span(2)
+                            "\n[no address or email address is available for this person]\n"
+                                .to_string(),
+                        ))
+                        .column_span(2)
+                    } else {
+                        cell
+                    }
+                })
                 .collect::<Row>()
                 .style(Style::new().fg(self.colors.row_fg).bg(color))
                 .height(4)

examples/vhs/demo2.tape

@@ -6,7 +6,8 @@ Set Theme "Aardvark Blue"
 # The reason for this strange size is that the social preview image for this
 # demo is 1280x64 with 80 pixels of padding on each side. We want a version
 # without the padding for README.md, etc.
-Set Width 1120
+# Please note that based on the width the demo may wrap and look corrupted.
+Set Width 1160
 Set Height 480
 Set Padding 0
 Hide

ratatui-core/Cargo.toml

@@ -1,13 +1,13 @@
 [package]
 name = "ratatui-core"
+version = "0.1.0"
 description = """
     Core types and traits for the Ratatui Terminal UI library.
     Widget libraries should use this crate. Applications should use the main Ratatui crate.
 """
-version = "0.1.0-beta.0"
+documentation = "https://docs.rs/ratatui-core"
 readme = "README.md"
 authors.workspace = true
-documentation.workspace = true
 repository.workspace = true
 homepage.workspace = true
 keywords.workspace = true

ratatui-core/src/backend.rs

@@ -109,19 +109,28 @@ use crate::layout::{Position, Size};
 mod test;
 pub use self::test::TestBackend;
 
-/// Enum representing the different types of clearing operations that can be performed
-/// on the terminal screen.
+/// Defines which region of the terminal's visible display area is cleared.
+///
+/// Clearing operates on character cells in the active display surface. It does not move, hide, or
+/// reset the cursor position. If the cursor lies inside the cleared region, the character cell at
+/// the cursor position is cleared as well.
+///
+/// Clearing applies to the terminal's visible display area, not just content previously drawn by
+/// Ratatui. No guarantees are made about scrollback, history, or off-screen buffers.
 #[derive(Debug, Display, EnumString, Clone, Copy, Eq, PartialEq, Hash)]
 pub enum ClearType {
-    /// Clear the entire screen.
+    /// Clears all character cells in the visible display area.
     All,
-    /// Clear everything after the cursor.
+    /// Clears all character cells from the cursor position (inclusive) through the end of the
+    /// display area.
     AfterCursor,
-    /// Clear everything before the cursor.
+    /// Clears all character cells from the start of the display area through the cursor position
+    /// (inclusive).
     BeforeCursor,
-    /// Clear the current line.
+    /// Clears all character cells in the cursor's current line.
     CurrentLine,
-    /// Clear everything from the cursor until the next newline.
+    /// Clears all character cells from the cursor position (inclusive) to the end of the current
+    /// line.
     UntilNewLine,
 }
 
@@ -237,7 +246,14 @@ pub trait Backend {
         self.set_cursor_position(Position { x, y })
     }
 
-    /// Clears the whole terminal screen
+    /// Clears all character cells in the terminal's visible display area.
+    ///
+    /// This operation preserves the cursor position. If the cursor lies within the cleared
+    /// region, the character cell at the cursor position is cleared. No guarantees are made about
+    /// scrollback, history, or off-screen buffers.
+    ///
+    /// This is equivalent to calling [`clear_region`](Self::clear_region) with
+    /// [`ClearType::All`].
     ///
     /// # Example
     ///
@@ -251,7 +267,13 @@ pub trait Backend {
     /// ```
     fn clear(&mut self) -> Result<(), Self::Error>;
 
-    /// Clears a specific region of the terminal specified by the [`ClearType`] parameter
+    /// Clears a specific region of the terminal's visible display area, as defined by
+    /// [`ClearType`].
+    ///
+    /// This operation preserves the cursor position. If the cursor lies within the cleared
+    /// region, the character cell at the cursor position is cleared. Clearing applies to the
+    /// active display surface only and does not make guarantees about scrollback, history, or
+    /// off-screen buffers.
     ///
     /// This method is optional and may not be implemented by all backends. The default
     /// implementation calls [`clear`] if the `clear_type` is [`ClearType::All`] and returns an

ratatui-core/src/backend/test.rs

@@ -105,6 +105,19 @@ impl TestBackend {
         &self.buffer
     }
 
+    /// Returns whether the cursor is visible.
+    pub const fn cursor_visible(&self) -> bool {
+        self.cursor
+    }
+
+    /// Returns the current cursor position.
+    pub const fn cursor_position(&self) -> Position {
+        Position {
+            x: self.pos.0,
+            y: self.pos.1,
+        }
+    }
+
     /// Returns a reference to the internal scrollback buffer of the `TestBackend`.
     ///
     /// The scrollback buffer represents the part of the screen that is currently hidden from view,
@@ -275,12 +288,12 @@ impl Backend for TestBackend {
         let region = match clear_type {
             ClearType::All => return self.clear(),
             ClearType::AfterCursor => {
-                let index = self.buffer.index_of(self.pos.0, self.pos.1) + 1;
+                let index = self.buffer.index_of(self.pos.0, self.pos.1);
                 &mut self.buffer.content[index..]
             }
             ClearType::BeforeCursor => {
                 let index = self.buffer.index_of(self.pos.0, self.pos.1);
-                &mut self.buffer.content[..index]
+                &mut self.buffer.content[..=index]
             }
             ClearType::CurrentLine => {
                 let line_start_index = self.buffer.index_of(0, self.pos.1);
@@ -620,7 +633,7 @@ mod tests {
         backend.assert_buffer_lines([
             "aaaaaaaaaa",
             "aaaaaaaaaa",
-            "aaaa      ",
+            "aaa       ",
             "          ",
             "          ",
         ]);
@@ -644,7 +657,7 @@ mod tests {
             "          ",
             "          ",
             "          ",
-            "     aaaaa",
+            "      aaaa",
             "aaaaaaaaaa",
         ]);
     }

ratatui-core/src/buffer/buffer.rs

@@ -25,7 +25,7 @@ use crate::text::{Line, Span};
 /// use ratatui_core::layout::{Position, Rect};
 /// use ratatui_core::style::{Color, Style};
 ///
-/// # fn foo() -> Option<()> {
+/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
 /// let mut buf = Buffer::empty(Rect {
 ///     x: 0,
 ///     y: 0,
@@ -39,13 +39,15 @@ use crate::text::{Line, Span};
 ///
 /// // indexing using (x, y) tuple (which is converted to Position)
 /// buf[(0, 1)].set_symbol("B");
-/// assert_eq!(buf[(0, 1)].symbol(), "x");
+/// assert_eq!(buf[(0, 1)].symbol(), "B");
 ///
 /// // getting an Option instead of panicking if the position is outside the buffer
-/// let cell = buf.cell_mut(Position { x: 0, y: 2 })?;
+/// let cell = buf
+///     .cell_mut(Position { x: 0, y: 2 })
+///     .ok_or("cell not found")?;
 /// cell.set_symbol("C");
 ///
-/// let cell = buf.cell(Position { x: 0, y: 2 })?;
+/// let cell = buf.cell(Position { x: 0, y: 2 }).ok_or("cell not found")?;
 /// assert_eq!(cell.symbol(), "C");
 ///
 /// buf.set_string(
@@ -58,7 +60,7 @@ use crate::text::{Line, Span};
 /// assert_eq!(cell.symbol(), "r");
 /// assert_eq!(cell.fg, Color::Red);
 /// assert_eq!(cell.bg, Color::White);
-/// # Some(())
+/// # Ok(())
 /// # }
 /// ```
 #[derive(Default, Clone, Eq, PartialEq, Hash)]
@@ -216,6 +218,9 @@ impl Buffer {
     ///
     /// Global coordinates are offset by the Buffer's area offset (`x`/`y`).
     ///
+    /// Usage discouraged, as it exposes `self.content` as a linearly indexable array, which limits
+    /// potential future abstractions. See <https://github.com/ratatui/ratatui/issues/1122>.
+    ///
     /// # Examples
     ///
     /// ```
@@ -269,10 +274,13 @@ impl Buffer {
         Some(y * width + x)
     }
 
-    /// Returns the (global) coordinates of a cell given its index
+    /// Returns the (global) coordinates of a cell given its index.
     ///
     /// Global coordinates are offset by the Buffer's area offset (`x`/`y`).
     ///
+    /// Usage discouraged, as it exposes `self.content` as a linearly indexable array, which limits
+    /// potential future abstractions. See <https://github.com/ratatui/ratatui/issues/1122>.
+    ///
     /// # Examples
     ///
     /// ```

ratatui-core/src/layout.rs

@@ -316,6 +316,7 @@ mod direction;
 mod flex;
 mod layout;
 mod margin;
+mod offset;
 mod position;
 mod rect;
 mod size;
@@ -326,6 +327,7 @@ pub use direction::Direction;
 pub use flex::Flex;
 pub use layout::{Layout, Spacing};
 pub use margin::Margin;
+pub use offset::Offset;
 pub use position::Position;
-pub use rect::{Columns, Offset, Positions, Rect, Rows};
+pub use rect::{Columns, Positions, Rect, Rows};
 pub use size::Size;

ratatui-core/src/layout/direction.rs

@@ -12,11 +12,27 @@ use strum::{Display, EnumString};
 #[derive(Debug, Default, Display, EnumString, Clone, Copy, Eq, PartialEq, Hash)]
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 pub enum Direction {
+    /// Layout segments are arranged side by side (left to right).
     Horizontal,
+    /// Layout segments are arranged top to bottom (default).
     #[default]
     Vertical,
 }
 
+impl Direction {
+    /// The perpendicular direction to this direction.
+    ///
+    /// `Horizontal` returns `Vertical`, and `Vertical` returns `Horizontal`.
+    #[inline]
+    #[must_use = "returns the perpendicular direction"]
+    pub const fn perpendicular(self) -> Self {
+        match self {
+            Self::Horizontal => Self::Vertical,
+            Self::Vertical => Self::Horizontal,
+        }
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use alloc::string::ToString;
@@ -37,4 +53,11 @@ mod tests {
         assert_eq!("Vertical".parse::<Direction>(), Ok(Direction::Vertical));
         assert_eq!("".parse::<Direction>(), Err(ParseError::VariantNotFound));
     }
+
+    #[test]
+    fn other() {
+        use Direction::*;
+        assert_eq!(Horizontal.perpendicular(), Vertical);
+        assert_eq!(Vertical.perpendicular(), Horizontal);
+    }
 }

ratatui-core/src/layout/offset.rs

@@ -0,0 +1,66 @@
+use crate::layout::Position;
+
+/// Amounts by which to move a [`Rect`](crate::layout::Rect).
+///
+/// Positive numbers move to the right/bottom and negative to the left/top.
+///
+/// See [`Rect::offset`](crate::layout::Rect::offset) for usage.
+#[derive(Debug, Default, Clone, Copy, Eq, PartialEq, Hash)]
+#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
+pub struct Offset {
+    /// How much to move on the X axis
+    pub x: i32,
+
+    /// How much to move on the Y axis
+    pub y: i32,
+}
+
+impl Offset {
+    /// A zero offset
+    pub const ZERO: Self = Self::new(0, 0);
+
+    /// The minimum offset
+    pub const MIN: Self = Self::new(i32::MIN, i32::MIN);
+
+    /// The maximum offset
+    pub const MAX: Self = Self::new(i32::MAX, i32::MAX);
+
+    /// Creates a new `Offset` with the given values.
+    pub const fn new(x: i32, y: i32) -> Self {
+        Self { x, y }
+    }
+}
+
+impl From<Position> for Offset {
+    fn from(position: Position) -> Self {
+        Self {
+            x: i32::from(position.x),
+            y: i32::from(position.y),
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn new_sets_components() {
+        assert_eq!(Offset::new(-3, 7), Offset { x: -3, y: 7 });
+    }
+
+    #[test]
+    fn constants_match_expected_values() {
+        assert_eq!(Offset::ZERO, Offset::new(0, 0));
+        assert_eq!(Offset::MIN, Offset::new(i32::MIN, i32::MIN));
+        assert_eq!(Offset::MAX, Offset::new(i32::MAX, i32::MAX));
+    }
+
+    #[test]
+    fn from_position_converts_coordinates() {
+        let position = Position::new(4, 9);
+        let offset = Offset::from(position);
+
+        assert_eq!(offset, Offset::new(4, 9));
+    }
+}

ratatui-core/src/layout/position.rs

@@ -1,7 +1,8 @@
 #![warn(missing_docs)]
 use core::fmt;
+use core::ops::{Add, AddAssign, Sub, SubAssign};
 
-use crate::layout::Rect;
+use crate::layout::{Offset, Rect};
 
 /// Position in the terminal coordinate system.
 ///
@@ -23,10 +24,18 @@ use crate::layout::Rect;
 /// - [`from(Rect)`](Self::from) - Create from [`Rect`] (uses top-left corner)
 /// - [`into((u16, u16))`] - Convert to `(u16, u16)` tuple
 ///
+/// # Movement
+///
+/// - [`offset`](Self::offset) - Move by an [`Offset`]
+/// - [`Add<Offset>`](core::ops::Add) and [`Sub<Offset>`](core::ops::Sub) - Shift by offsets with
+///   clamping
+/// - [`AddAssign<Offset>`](core::ops::AddAssign) and [`SubAssign<Offset>`](core::ops::SubAssign) -
+///   In-place shifting
+///
 /// # Examples
 ///
 /// ```
-/// use ratatui_core::layout::{Position, Rect};
+/// use ratatui_core::layout::{Offset, Position, Rect};
 ///
 /// // the following are all equivalent
 /// let position = Position { x: 1, y: 2 };
@@ -36,6 +45,10 @@ use crate::layout::Rect;
 ///
 /// // position can be converted back into the components when needed
 /// let (x, y) = position.into();
+///
+/// // movement by offsets
+/// let position = Position::new(5, 5) + Offset::new(2, -3);
+/// assert_eq!(position, Position::new(7, 2));
 /// ```
 ///
 /// For comprehensive layout documentation and examples, see the [`layout`](crate::layout) module.
@@ -57,12 +70,27 @@ pub struct Position {
 
 impl Position {
     /// Position at the origin, the top left edge at 0,0
-    pub const ORIGIN: Self = Self { x: 0, y: 0 };
+    pub const ORIGIN: Self = Self::new(0, 0);
+
+    /// Position at the minimum x and y values
+    pub const MIN: Self = Self::ORIGIN;
+
+    /// Position at the maximum x and y values
+    pub const MAX: Self = Self::new(u16::MAX, u16::MAX);
 
     /// Create a new position
     pub const fn new(x: u16, y: u16) -> Self {
         Self { x, y }
     }
+
+    /// Moves the position by the given offset.
+    ///
+    /// Positive offsets move right and down, negative offsets move left and up. Values that would
+    /// move the position outside the `u16` range are clamped to the nearest edge.
+    #[must_use = "method returns the modified value"]
+    pub fn offset(self, offset: Offset) -> Self {
+        self + offset
+    }
 }
 
 impl From<(u16, u16)> for Position {
@@ -89,6 +117,68 @@ impl fmt::Display for Position {
     }
 }
 
+impl Add<Offset> for Position {
+    type Output = Self;
+
+    /// Moves the position by the given offset.
+    ///
+    /// Values that would move the position outside the `u16` range are clamped to the nearest
+    /// edge.
+    fn add(self, offset: Offset) -> Self {
+        let max = i32::from(u16::MAX);
+        let x = i32::from(self.x).saturating_add(offset.x).clamp(0, max) as u16;
+        let y = i32::from(self.y).saturating_add(offset.y).clamp(0, max) as u16;
+        Self { x, y }
+    }
+}
+
+impl Add<Position> for Offset {
+    type Output = Position;
+
+    /// Moves the position by the given offset.
+    ///
+    /// Values that would move the position outside the `u16` range are clamped to the nearest
+    /// edge.
+    fn add(self, position: Position) -> Position {
+        position + self
+    }
+}
+
+impl Sub<Offset> for Position {
+    type Output = Self;
+
+    /// Moves the position by the inverse of the given offset.
+    ///
+    /// Values that would move the position outside the `u16` range are clamped to the nearest
+    /// edge.
+    fn sub(self, offset: Offset) -> Self {
+        let max = i32::from(u16::MAX);
+        let x = i32::from(self.x).saturating_sub(offset.x).clamp(0, max) as u16;
+        let y = i32::from(self.y).saturating_sub(offset.y).clamp(0, max) as u16;
+        Self { x, y }
+    }
+}
+
+impl AddAssign<Offset> for Position {
+    /// Moves the position in place by the given offset.
+    ///
+    /// Values that would move the position outside the `u16` range are clamped to the nearest
+    /// edge.
+    fn add_assign(&mut self, offset: Offset) {
+        *self = *self + offset;
+    }
+}
+
+impl SubAssign<Offset> for Position {
+    /// Moves the position in place by the inverse of the given offset.
+    ///
+    /// Values that would move the position outside the `u16` range are clamped to the nearest
+    /// edge.
+    fn sub_assign(&mut self, offset: Offset) {
+        *self = *self - offset;
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use alloc::string::ToString;
@@ -98,15 +188,15 @@ mod tests {
     #[test]
     fn new() {
         let position = Position::new(1, 2);
-        assert_eq!(position.x, 1);
-        assert_eq!(position.y, 2);
+
+        assert_eq!(position, Position { x: 1, y: 2 });
     }
 
     #[test]
     fn from_tuple() {
         let position = Position::from((1, 2));
-        assert_eq!(position.x, 1);
-        assert_eq!(position.y, 2);
+
+        assert_eq!(position, Position { x: 1, y: 2 });
     }
 
     #[test]
@@ -121,8 +211,8 @@ mod tests {
     fn from_rect() {
         let rect = Rect::new(1, 2, 3, 4);
         let position = Position::from(rect);
-        assert_eq!(position.x, 1);
-        assert_eq!(position.y, 2);
+
+        assert_eq!(position, Position { x: 1, y: 2 });
     }
 
     #[test]
@@ -130,4 +220,34 @@ mod tests {
         let position = Position::new(1, 2);
         assert_eq!(position.to_string(), "(1, 2)");
     }
+
+    #[test]
+    fn offset_moves_position() {
+        let position = Position::new(2, 3).offset(Offset::new(5, 7));
+
+        assert_eq!(position, Position::new(7, 10));
+    }
+
+    #[test]
+    fn offset_clamps_to_bounds() {
+        let position = Position::new(1, 1).offset(Offset::MAX);
+
+        assert_eq!(position, Position::MAX);
+    }
+
+    #[test]
+    fn add_and_subtract_offset() {
+        let position = Position::new(10, 10) + Offset::new(-3, 4) - Offset::new(5, 20);
+
+        assert_eq!(position, Position::new(2, 0));
+    }
+
+    #[test]
+    fn add_assign_and_sub_assign_offset() {
+        let mut position = Position::new(5, 5);
+        position += Offset::new(2, 3);
+        position -= Offset::new(10, 1);
+
+        assert_eq!(position, Position::new(0, 7));
+    }
 }

ratatui-core/src/layout/rect.rs

@@ -3,10 +3,11 @@ use core::array::TryFromSliceError;
 use core::cmp::{max, min};
 use core::fmt;
 
-use crate::layout::{Margin, Position, Size};
+pub use self::iter::{Columns, Positions, Rows};
+use crate::layout::{Margin, Offset, Position, Size};
 
 mod iter;
-pub use iter::*;
+mod ops;
 
 use super::{Constraint, Flex, Layout};
 
@@ -45,6 +46,7 @@ use super::{Constraint, Flex, Layout};
 ///
 /// - [`inner`](Self::inner), [`outer`](Self::outer) - Apply margins to shrink or expand
 /// - [`offset`](Self::offset) - Move the rectangle by a relative amount
+/// - [`resize`](Self::resize) - Change the rectangle size while keeping the bottom/right in range
 /// - [`union`](Self::union) - Combine with another rectangle to create a bounding box
 /// - [`intersection`](Self::intersection) - Find the overlapping area with another rectangle
 /// - [`clamp`](Self::clamp) - Constrain the rectangle to fit within another
@@ -66,21 +68,67 @@ use super::{Constraint, Flex, Layout};
 ///
 /// # Examples
 ///
+/// To create a new `Rect`, use [`Rect::new`]. The size of the `Rect` will be clamped to keep the
+/// right and bottom coordinates within `u16`. Note that this clamping does not occur when creating
+/// a `Rect` directly.
+///
+/// ```rust
+/// use ratatui_core::layout::Rect;
+///
+/// let rect = Rect::new(1, 2, 3, 4);
+/// assert_eq!(
+///     rect,
+///     Rect {
+///         x: 1,
+///         y: 2,
+///         width: 3,
+///         height: 4
+///     }
+/// );
+/// ```
+///
+/// You can also create a `Rect` from a [`Position`] and a [`Size`].
+///
 /// ```rust
 /// use ratatui_core::layout::{Position, Rect, Size};
 ///
-/// // Create a rectangle manually
-/// let rect = Rect::new(10, 5, 80, 20);
-/// assert_eq!(rect.x, 10);
-/// assert_eq!(rect.y, 5);
-/// assert_eq!(rect.width, 80);
-/// assert_eq!(rect.height, 20);
+/// let position = Position::new(1, 2);
+/// let size = Size::new(3, 4);
+/// let rect = Rect::from((position, size));
+/// assert_eq!(
+///     rect,
+///     Rect {
+///         x: 1,
+///         y: 2,
+///         width: 3,
+///         height: 4
+///     }
+/// );
+/// ```
 ///
-/// // Create from position and size
-/// let rect = Rect::from((Position::new(10, 5), Size::new(80, 20)));
+/// To move a `Rect` without modifying its size, add or subtract an [`Offset`] to it.
+///
+/// ```rust
+/// use ratatui_core::layout::{Offset, Rect};
+///
+/// let rect = Rect::new(1, 2, 3, 4);
+/// let offset = Offset::new(5, 6);
+/// let moved_rect = rect + offset;
+/// assert_eq!(moved_rect, Rect::new(6, 8, 3, 4));
+/// ```
+///
+/// To resize a `Rect` while ensuring it stays within bounds, use [`Rect::resize`]. The size is
+/// clamped so that `right()` and `bottom()` do not exceed `u16::MAX`.
+///
+/// ```rust
+/// use ratatui_core::layout::{Rect, Size};
+///
+/// let rect = Rect::new(u16::MAX - 1, u16::MAX - 1, 1, 1).resize(Size::new(10, 10));
+/// assert_eq!(rect, Rect::new(u16::MAX - 1, u16::MAX - 1, 1, 1));
 /// ```
 ///
 /// For comprehensive layout documentation and examples, see the [`layout`](crate::layout) module.
+
 #[derive(Debug, Default, Clone, Copy, Eq, PartialEq, Hash)]
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 pub struct Rect {
@@ -94,30 +142,6 @@ pub struct Rect {
     pub height: u16,
 }
 
-/// Amounts by which to move a [`Rect`](crate::layout::Rect).
-///
-/// Positive numbers move to the right/bottom and negative to the left/top.
-///
-/// See [`Rect::offset`]
-#[derive(Debug, Default, Clone, Copy, Eq, PartialEq, Hash)]
-#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
-pub struct Offset {
-    /// How much to move on the X axis
-    pub x: i32,
-    /// How much to move on the Y axis
-    pub y: i32,
-}
-
-impl Offset {
-    /// A zero offset
-    pub const ZERO: Self = Self { x: 0, y: 0 };
-
-    /// Creates a new `Offset` with the given values.
-    pub const fn new(x: i32, y: i32) -> Self {
-        Self { x, y }
-    }
-}
-
 impl fmt::Display for Rect {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         write!(f, "{}x{}+{}+{}", self.width, self.height, self.x, self.y)
@@ -133,6 +157,12 @@ impl Rect {
         height: 0,
     };
 
+    /// The minimum possible Rect
+    pub const MIN: Self = Self::ZERO;
+
+    /// The maximum possible Rect
+    pub const MAX: Self = Self::new(0, 0, u16::MAX, u16::MAX);
+
     /// Creates a new `Rect`, with width and height limited to keep both bounds within `u16`.
     ///
     /// If the width or height would cause the right or bottom coordinate to be larger than the
@@ -147,15 +177,8 @@ impl Rect {
     /// let rect = Rect::new(1, 2, 3, 4);
     /// ```
     pub const fn new(x: u16, y: u16, width: u16, height: u16) -> Self {
-        // these calculations avoid using min so that this function can be const
-        let max_width = u16::MAX - x;
-        let max_height = u16::MAX - y;
-        let width = if width > max_width { max_width } else { width };
-        let height = if height > max_height {
-            max_height
-        } else {
-            height
-        };
+        let width = x.saturating_add(width) - x;
+        let height = y.saturating_add(height) - y;
         Self {
             x,
             y,
@@ -260,13 +283,19 @@ impl Rect {
     /// See [`Offset`] for details.
     #[must_use = "method returns the modified value"]
     pub fn offset(self, offset: Offset) -> Self {
+        self + offset
+    }
+
+    /// Resizes the `Rect`, clamping to keep the right and bottom within `u16::MAX`.
+    ///
+    /// The position is preserved. If the requested size would push the `Rect` beyond the bounds of
+    /// `u16`, the width or height is reduced so that [`right`](Self::right) and
+    /// [`bottom`](Self::bottom) remain within range.
+    #[must_use = "method returns the modified value"]
+    pub const fn resize(self, size: Size) -> Self {
         Self {
-            x: i32::from(self.x)
-                .saturating_add(offset.x)
-                .clamp(0, i32::from(u16::MAX - self.width)) as u16,
-            y: i32::from(self.y)
-                .saturating_add(offset.y)
-                .clamp(0, i32::from(u16::MAX - self.height)) as u16,
+            width: self.x.saturating_add(size.width).saturating_sub(self.x),
+            height: self.y.saturating_add(size.height).saturating_sub(self.y),
             ..self
         }
     }
@@ -811,6 +840,16 @@ mod tests {
         assert!(!Rect::new(1, 2, 3, 4).intersects(Rect::new(5, 6, 7, 8)));
     }
 
+    #[rstest]
+    #[case::corner(Rect::new(0, 0, 10, 10), Rect::new(10, 10, 20, 20))]
+    #[case::edge(Rect::new(0, 0, 10, 10), Rect::new(10, 0, 20, 10))]
+    #[case::no_intersect(Rect::new(0, 0, 10, 10), Rect::new(11, 11, 20, 20))]
+    #[case::contains(Rect::new(0, 0, 20, 20), Rect::new(5, 5, 10, 10))]
+    fn mutual_intersect(#[case] rect0: Rect, #[case] rect1: Rect) {
+        assert_eq!(rect0.intersection(rect1), rect1.intersection(rect0));
+        assert_eq!(rect0.intersects(rect1), rect1.intersects(rect0));
+    }
+
     // the bounds of this rect are x: [1..=3], y: [2..=5]
     #[rstest]
     #[case::inside_top_left(Rect::new(1, 2, 3, 4), Position { x: 1, y: 2 }, true)]
@@ -857,6 +896,18 @@ mod tests {
         );
     }
 
+    #[test]
+    fn resize_updates_size() {
+        let rect = Rect::new(10, 20, 5, 5).resize(Size::new(30, 40));
+        assert_eq!(rect, Rect::new(10, 20, 30, 40));
+    }
+
+    #[test]
+    fn resize_clamps_at_bounds() {
+        let rect = Rect::new(u16::MAX - 2, u16::MAX - 3, 1, 1).resize(Size::new(10, 10));
+        assert_eq!(rect, Rect::new(u16::MAX - 2, u16::MAX - 3, 2, 3));
+    }
+
     #[test]
     fn can_be_const() {
         const RECT: Rect = Rect {

ratatui-core/src/layout/rect/ops.rs

@@ -0,0 +1,136 @@
+use core::ops::{Add, AddAssign, Neg, Sub, SubAssign};
+
+use super::{Offset, Rect};
+
+impl Neg for Offset {
+    type Output = Self;
+
+    /// Negates the offset.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the negated value overflows (i.e. `x` or `y` is `i32::MIN`).
+    fn neg(self) -> Self {
+        Self {
+            x: self.x.neg(),
+            y: self.y.neg(),
+        }
+    }
+}
+
+impl Add<Offset> for Rect {
+    type Output = Self;
+
+    /// Moves the rect by an offset without changing its size.
+    ///
+    /// If the offset would move the any of the rect's edges outside the bounds of `u16`, the
+    /// rect's position is clamped to the nearest edge.
+    fn add(self, offset: Offset) -> Self {
+        let max_x = i32::from(u16::MAX - self.width);
+        let max_y = i32::from(u16::MAX - self.height);
+        let x = i32::from(self.x).saturating_add(offset.x).clamp(0, max_x) as u16;
+        let y = i32::from(self.y).saturating_add(offset.y).clamp(0, max_y) as u16;
+        Self { x, y, ..self }
+    }
+}
+
+impl Add<Rect> for Offset {
+    type Output = Rect;
+
+    /// Moves the rect by an offset without changing its size.
+    ///
+    /// If the offset would move the any of the rect's edges outside the bounds of `u16`, the
+    /// rect's position is clamped to the nearest edge.
+    fn add(self, rect: Rect) -> Rect {
+        rect + self
+    }
+}
+
+impl Sub<Offset> for Rect {
+    type Output = Self;
+
+    /// Subtracts an offset from the rect without changing its size.
+    ///
+    /// If the offset would move the any of the rect's edges outside the bounds of `u16`, the
+    /// rect's position is clamped to the nearest
+    fn sub(self, offset: Offset) -> Self {
+        // Note this cannot be simplified to `self + -offset` because `Offset::MIN` would overflow
+        let max_x = i32::from(u16::MAX - self.width);
+        let max_y = i32::from(u16::MAX - self.height);
+        let x = i32::from(self.x).saturating_sub(offset.x).clamp(0, max_x) as u16;
+        let y = i32::from(self.y).saturating_sub(offset.y).clamp(0, max_y) as u16;
+        Self { x, y, ..self }
+    }
+}
+
+impl AddAssign<Offset> for Rect {
+    /// Moves the rect by an offset in place without changing its size.
+    ///
+    /// If the offset would move the any of the rect's edges outside the bounds of `u16`, the
+    /// rect's position is clamped to the nearest edge.
+    fn add_assign(&mut self, offset: Offset) {
+        *self = *self + offset;
+    }
+}
+
+impl SubAssign<Offset> for Rect {
+    /// Moves the rect by an offset in place without changing its size.
+    ///
+    /// If the offset would move the any of the rect's edges outside the bounds of `u16`, the
+    /// rect's position is clamped to the nearest edge.
+    fn sub_assign(&mut self, offset: Offset) {
+        *self = *self - offset;
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use rstest::rstest;
+
+    use super::*;
+
+    #[rstest]
+    #[case::zero(Rect::new(3, 4, 5, 6), Offset::ZERO, Rect::new(3, 4, 5, 6))]
+    #[case::positive(Rect::new(3, 4, 5, 6), Offset::new(1, 2), Rect::new(4, 6, 5, 6))]
+    #[case::negative(Rect::new(3, 4, 5, 6), Offset::new(-1, -2), Rect::new(2, 2, 5, 6))]
+    #[case::saturate_negative(Rect::new(3, 4, 5, 6), Offset::MIN, Rect::new(0, 0, 5, 6))]
+    #[case::saturate_positive(Rect::new(3, 4, 5, 6), Offset::MAX, Rect::new(u16::MAX- 5, u16::MAX - 6, 5, 6))]
+    fn add_offset(#[case] rect: Rect, #[case] offset: Offset, #[case] expected: Rect) {
+        assert_eq!(rect + offset, expected);
+        assert_eq!(offset + rect, expected);
+    }
+
+    #[rstest]
+    #[case::zero(Rect::new(3, 4, 5, 6), Offset::ZERO, Rect::new(3, 4, 5, 6))]
+    #[case::positive(Rect::new(3, 4, 5, 6), Offset::new(1, 2), Rect::new(2, 2, 5, 6))]
+    #[case::negative(Rect::new(3, 4, 5, 6), Offset::new(-1, -2), Rect::new(4, 6, 5, 6))]
+    #[case::saturate_negative(Rect::new(3, 4, 5, 6), Offset::MAX, Rect::new(0, 0, 5, 6))]
+    #[case::saturate_positive(Rect::new(3, 4, 5, 6), -Offset::MAX, Rect::new(u16::MAX - 5, u16::MAX - 6, 5, 6))]
+    fn sub_offset(#[case] rect: Rect, #[case] offset: Offset, #[case] expected: Rect) {
+        assert_eq!(rect - offset, expected);
+    }
+
+    #[rstest]
+    #[case::zero(Rect::new(3, 4, 5, 6), Offset::ZERO, Rect::new(3, 4, 5, 6))]
+    #[case::positive(Rect::new(3, 4, 5, 6), Offset::new(1, 2), Rect::new(4, 6, 5, 6))]
+    #[case::negative(Rect::new(3, 4, 5, 6), Offset::new(-1, -2), Rect::new(2, 2, 5, 6))]
+    #[case::saturate_negative(Rect::new(3, 4, 5, 6), Offset::MIN, Rect::new(0, 0, 5, 6))]
+    #[case::saturate_positive(Rect::new(3, 4, 5, 6), Offset::MAX, Rect::new(u16::MAX - 5, u16::MAX - 6, 5, 6))]
+    fn add_assign_offset(#[case] rect: Rect, #[case] offset: Offset, #[case] expected: Rect) {
+        let mut rect = rect;
+        rect += offset;
+        assert_eq!(rect, expected);
+    }
+
+    #[rstest]
+    #[case::zero(Rect::new(3, 4, 5, 6), Offset::ZERO, Rect::new(3, 4, 5, 6))]
+    #[case::positive(Rect::new(3, 4, 5, 6), Offset::new(1, 2), Rect::new(2, 2, 5, 6))]
+    #[case::negative(Rect::new(3, 4, 5, 6), Offset::new(-1, -2), Rect::new(4, 6, 5, 6))]
+    #[case::saturate_negative(Rect::new(3, 4, 5, 6), Offset::MAX, Rect::new(0, 0, 5, 6))]
+    #[case::saturate_positive(Rect::new(3, 4, 5, 6), -Offset::MAX, Rect::new(u16::MAX - 5, u16::MAX - 6, 5, 6))]
+    fn sub_assign_offset(#[case] rect: Rect, #[case] offset: Offset, #[case] expected: Rect) {
+        let mut rect = rect;
+        rect -= offset;
+        assert_eq!(rect, expected);
+    }
+}

ratatui-core/src/layout/size.rs

@@ -24,14 +24,20 @@ use crate::layout::Rect;
 /// - [`from(Rect)`](Self::from) - Create from [`Rect`] (uses width and height)
 /// - [`into((u16, u16))`] - Convert to `(u16, u16)` tuple
 ///
+/// # Computation
+///
+/// - [`area`](Self::area) - Compute the total number of cells covered by the size
+///
 /// # Examples
 ///
 /// ```rust
 /// use ratatui_core::layout::{Rect, Size};
 ///
 /// let size = Size::new(80, 24);
+/// assert_eq!(size.area(), 1920);
 /// let size = Size::from((80, 24));
 /// let size = Size::from(Rect::new(0, 0, 80, 24));
+/// assert_eq!(size.area(), 1920);
 /// ```
 ///
 /// For comprehensive layout documentation and examples, see the [`layout`](crate::layout) module.
@@ -48,10 +54,24 @@ impl Size {
     /// A zero sized Size
     pub const ZERO: Self = Self::new(0, 0);
 
+    /// The minimum possible Size
+    pub const MIN: Self = Self::ZERO;
+
+    /// The maximum possible Size
+    pub const MAX: Self = Self::new(u16::MAX, u16::MAX);
+
     /// Create a new `Size` struct
     pub const fn new(width: u16, height: u16) -> Self {
         Self { width, height }
     }
+
+    /// Compute the total area of the size as a `u32`.
+    ///
+    /// The multiplication uses `u32` to avoid overflow when the width and height are at their
+    /// `u16` maximum values.
+    pub const fn area(self) -> u32 {
+        self.width as u32 * self.height as u32
+    }
 }
 
 impl From<(u16, u16)> for Size {
@@ -60,6 +80,12 @@ impl From<(u16, u16)> for Size {
     }
 }
 
+impl From<Size> for (u16, u16) {
+    fn from(size: Size) -> Self {
+        (size.width, size.height)
+    }
+}
+
 impl From<Rect> for Size {
     fn from(rect: Rect) -> Self {
         rect.as_size()
@@ -92,6 +118,14 @@ mod tests {
         assert_eq!(size.height, 20);
     }
 
+    #[test]
+    fn to_tuple() {
+        let size = Size::from((10, 20));
+        let (width, height) = size.into();
+        assert_eq!(size.width, width);
+        assert_eq!(size.height, height);
+    }
+
     #[test]
     fn from_rect() {
         let size = Size::from(Rect::new(0, 0, 10, 20));
@@ -103,4 +137,11 @@ mod tests {
     fn display() {
         assert_eq!(Size::new(10, 20).to_string(), "10x20");
     }
+
+    #[test]
+    fn area() {
+        assert_eq!(Size::new(10, 20).area(), 200);
+        assert_eq!(Size::new(0, 0).area(), 0);
+        assert_eq!(Size::new(u16::MAX, u16::MAX).area(), 4_294_836_225_u32);
+    }
 }

ratatui-core/src/style.rs

@@ -250,17 +250,41 @@ pub struct Style {
     /// The modifiers to add.
     #[cfg_attr(
         feature = "serde",
-        serde(default, skip_serializing_if = "Modifier::is_empty")
+        serde(
+            default,
+            skip_serializing_if = "Modifier::is_empty",
+            deserialize_with = "deserialize_modifier"
+        )
     )]
     pub add_modifier: Modifier,
     /// The modifiers to remove.
     #[cfg_attr(
         feature = "serde",
-        serde(default, skip_serializing_if = "Modifier::is_empty")
+        serde(
+            default,
+            skip_serializing_if = "Modifier::is_empty",
+            deserialize_with = "deserialize_modifier"
+        )
     )]
     pub sub_modifier: Modifier,
 }
 
+#[cfg(feature = "serde")]
+/// Deserialize a [`Modifier`] while treating missing or `null` values as empty.
+///
+/// This helper is used with serde to coerce absent or `null` modifier fields to
+/// [`Modifier::empty`], allowing configuration files to omit these fields
+/// without triggering deserialization errors.
+fn deserialize_modifier<'de, D>(deserializer: D) -> Result<Modifier, D::Error>
+where
+    D: serde::Deserializer<'de>,
+{
+    use serde::Deserialize;
+
+    Option::<Modifier>::deserialize(deserializer)
+        .map(|modifier| modifier.unwrap_or_else(Modifier::empty))
+}
+
 /// A custom debug implementation that prints only the fields that are not the default, and unwraps
 /// the `Option`s.
 impl fmt::Debug for Style {
@@ -409,6 +433,22 @@ impl Style {
         self
     }
 
+    /// Returns `true` if the style has the given modifier set.
+    ///
+    /// ## Examples
+    ///
+    /// ```rust
+    /// use ratatui_core::style::{Modifier, Style};
+    ///
+    /// let style = Style::default().add_modifier(Modifier::BOLD | Modifier::ITALIC);
+    /// assert!(style.has_modifier(Modifier::BOLD));
+    /// assert!(style.has_modifier(Modifier::ITALIC));
+    /// assert!(!style.has_modifier(Modifier::UNDERLINED));
+    /// ```
+    pub const fn has_modifier(self, modifier: Modifier) -> bool {
+        self.add_modifier.contains(modifier) && !self.sub_modifier.contains(modifier)
+    }
+
     /// Results in a combined style that is equivalent to applying the two individual styles to
     /// a style one after the other.
     ///
@@ -788,6 +828,28 @@ mod tests {
         assert_eq!(ALL, ALL_SHORT);
     }
 
+    #[test]
+    fn has_modifier_checks() {
+        // basic presence
+        let style = Style::new().add_modifier(Modifier::BOLD | Modifier::ITALIC);
+        assert!(style.has_modifier(Modifier::BOLD));
+        assert!(style.has_modifier(Modifier::ITALIC));
+        assert!(!style.has_modifier(Modifier::UNDERLINED));
+
+        // removal prevents the modifier from being reported as present
+        let style = Style::new()
+            .add_modifier(Modifier::BOLD | Modifier::ITALIC)
+            .remove_modifier(Modifier::ITALIC);
+        assert!(style.has_modifier(Modifier::BOLD));
+        assert!(!style.has_modifier(Modifier::ITALIC));
+
+        // patching with a style that removes a modifier clears it
+        let style = Style::new().add_modifier(Modifier::BOLD | Modifier::ITALIC);
+        let patched = style.patch(Style::new().remove_modifier(Modifier::ITALIC));
+        assert!(patched.has_modifier(Modifier::BOLD));
+        assert!(!patched.has_modifier(Modifier::ITALIC));
+    }
+
     #[rstest]
     #[case(Style::new().black(), Color::Black)]
     #[case(Style::new().red(), Color::Red)]
@@ -989,4 +1051,19 @@ mod tests {
         let deserialized: Style = serde_json::from_str(&json_str).unwrap();
         assert_eq!(deserialized, style);
     }
+
+    #[cfg(feature = "serde")]
+    #[test]
+    fn deserialize_null_modifiers() {
+        let json_value = serde_json::json!({
+            "add_modifier": serde_json::Value::Null,
+            "sub_modifier": serde_json::Value::Null
+        });
+        let json_str = serde_json::to_string(&json_value).unwrap();
+
+        let style: Style = serde_json::from_str(&json_str).unwrap();
+
+        assert!(style.add_modifier.is_empty());
+        assert!(style.sub_modifier.is_empty());
+    }
 }

ratatui-core/src/symbols.rs

@@ -10,5 +10,6 @@ pub mod half_block;
 pub mod line;
 pub mod marker;
 pub mod merge;
+pub mod pixel;
 pub mod scrollbar;
 pub mod shade;

ratatui-core/src/symbols/braille.rs

@@ -1,7 +1,21 @@
-pub const BLANK: u16 = 0x2800;
-pub const DOTS: [[u16; 2]; 4] = [
-    [0x0001, 0x0008],
-    [0x0002, 0x0010],
-    [0x0004, 0x0020],
-    [0x0040, 0x0080],
+//! Braille symbols.
+//!
+//! Note that the symbols are not listed according to their unicode codepoint but according to the
+//! corresponding bit pattern in row-major order.
+
+pub const BRAILLE: [char; 256] = [
+    '⠀', '⠁', '⠈', '⠉', '⠂', '⠃', '⠊', '⠋', '⠐', '⠑', '⠘', '⠙', '⠒', '⠓', '⠚', '⠛', '⠄', '⠅', '⠌',
+    '⠍', '⠆', '⠇', '⠎', '⠏', '⠔', '⠕', '⠜', '⠝', '⠖', '⠗', '⠞', '⠟', '⠠', '⠡', '⠨', '⠩', '⠢', '⠣',
+    '⠪', '⠫', '⠰', '⠱', '⠸', '⠹', '⠲', '⠳', '⠺', '⠻', '⠤', '⠥', '⠬', '⠭', '⠦', '⠧', '⠮', '⠯', '⠴',
+    '⠵', '⠼', '⠽', '⠶', '⠷', '⠾', '⠿', '⡀', '⡁', '⡈', '⡉', '⡂', '⡃', '⡊', '⡋', '⡐', '⡑', '⡘', '⡙',
+    '⡒', '⡓', '⡚', '⡛', '⡄', '⡅', '⡌', '⡍', '⡆', '⡇', '⡎', '⡏', '⡔', '⡕', '⡜', '⡝', '⡖', '⡗', '⡞',
+    '⡟', '⡠', '⡡', '⡨', '⡩', '⡢', '⡣', '⡪', '⡫', '⡰', '⡱', '⡸', '⡹', '⡲', '⡳', '⡺', '⡻', '⡤', '⡥',
+    '⡬', '⡭', '⡦', '⡧', '⡮', '⡯', '⡴', '⡵', '⡼', '⡽', '⡶', '⡷', '⡾', '⡿', '⢀', '⢁', '⢈', '⢉', '⢂',
+    '⢃', '⢊', '⢋', '⢐', '⢑', '⢘', '⢙', '⢒', '⢓', '⢚', '⢛', '⢄', '⢅', '⢌', '⢍', '⢆', '⢇', '⢎', '⢏',
+    '⢔', '⢕', '⢜', '⢝', '⢖', '⢗', '⢞', '⢟', '⢠', '⢡', '⢨', '⢩', '⢢', '⢣', '⢪', '⢫', '⢰', '⢱', '⢸',
+    '⢹', '⢲', '⢳', '⢺', '⢻', '⢤', '⢥', '⢬', '⢭', '⢦', '⢧', '⢮', '⢯', '⢴', '⢵', '⢼', '⢽', '⢶', '⢷',
+    '⢾', '⢿', '⣀', '⣁', '⣈', '⣉', '⣂', '⣃', '⣊', '⣋', '⣐', '⣑', '⣘', '⣙', '⣒', '⣓', '⣚', '⣛', '⣄',
+    '⣅', '⣌', '⣍', '⣆', '⣇', '⣎', '⣏', '⣔', '⣕', '⣜', '⣝', '⣖', '⣗', '⣞', '⣟', '⣠', '⣡', '⣨', '⣩',
+    '⣢', '⣣', '⣪', '⣫', '⣰', '⣱', '⣸', '⣹', '⣲', '⣳', '⣺', '⣻', '⣤', '⣥', '⣬', '⣭', '⣦', '⣧', '⣮',
+    '⣯', '⣴', '⣵', '⣼', '⣽', '⣶', '⣷', '⣾', '⣿',
 ];

ratatui-core/src/symbols/marker.rs

@@ -4,6 +4,7 @@ pub const DOT: &str = "•";
 
 /// Marker to use when plotting data points
 #[derive(Debug, Default, Display, EnumString, Clone, Copy, Eq, PartialEq, Hash)]
+#[non_exhaustive]
 pub enum Marker {
     /// One point per cell in shape of dot (`•`)
     #[default]
@@ -25,6 +26,33 @@ pub enum Marker {
     /// a grid that is double the resolution of the terminal. Because each terminal cell is
     /// generally about twice as tall as it is wide, this allows for a square grid of pixels.
     HalfBlock,
+    /// Use quadrant characters to represent data points.
+    ///
+    /// Quadrant characters display densely packed and regularly spaced pseudo-pixels with a 2x2
+    /// resolution per character, without visible bands between cells.
+    Quadrant,
+    /// Use sextant characters from the [Unicode Symbols for Legacy Computing
+    /// Supplement](https://en.wikipedia.org/wiki/Symbols_for_Legacy_Computing_Supplement) to
+    /// represent data points.
+    ///
+    /// Sextant characters display densely packed and regularly spaced pseudo-pixels with a 2x3
+    /// resolution per character, without visible bands between cells.
+    ///
+    /// Note: the Symbols for Legacy Computing Supplement block is a relatively recent addition to
+    /// unicode that is less broadly supported than Braille dots. If your terminal does not support
+    /// this, you will see unicode replacement characters (`<60>`) instead of sextants (`🬌`, `🬲`, `🬑`).
+    Sextant,
+    /// Use octant characters from the [Unicode Symbols for Legacy Computing
+    /// Supplement](https://en.wikipedia.org/wiki/Symbols_for_Legacy_Computing_Supplement) to
+    /// represent data points.
+    ///
+    /// Octant characters have the same 2x4 resolution as Braille characters but display densely
+    /// packed and regularly spaced pseudo-pixels, without visible bands between cells.
+    ///
+    /// Note: the Symbols for Legacy Computing Supplement block is a relatively recent addition to
+    /// unicode that is less broadly supported than Braille dots. If your terminal does not support
+    /// this, you will see unicode replacement characters (`<60>`) instead of octants (`𜴇`, `𜷀`, `𜴷`).
+    Octant,
 }
 
 #[cfg(test)]

ratatui-core/src/symbols/pixel.rs

@@ -0,0 +1,30 @@
+//! Pseudo-pixel symbols: quadrant, sextant and octant characters.
+//!
+//! Note that the symbols are not listed according to their unicode codepoint but according to the
+//! corresponding bit pattern in row-major order.
+
+pub const QUADRANTS: [char; 16] = [
+    ' ', '▘', '▝', '▀', '▖', '▌', '▞', '▛', '▗', '▚', '▐', '▜', '▄', '▙', '▟', '█',
+];
+pub const SEXTANTS: [char; 64] = [
+    ' ', '🬀', '🬁', '🬂', '🬃', '🬄', '🬅', '🬆', '🬇', '🬈', '🬉', '🬊', '🬋', '🬌', '🬍', '🬎', '🬏', '🬐', '🬑',
+    '🬒', '🬓', '▌', '🬔', '🬕', '🬖', '🬗', '🬘', '🬙', '🬚', '🬛', '🬜', '🬝', '🬞', '🬟', '🬠', '🬡', '🬢', '🬣',
+    '🬤', '🬥', '🬦', '🬧', '▐', '🬨', '🬩', '🬪', '🬫', '🬬', '🬭', '🬮', '🬯', '🬰', '🬱', '🬲', '🬳', '🬴', '🬵',
+    '🬶', '🬷', '🬸', '🬹', '🬺', '🬻', '█',
+];
+pub const OCTANTS: [char; 256] = [
+    ' ', '𜺨', '𜺫', '🮂', '𜴀', '▘', '𜴁', '𜴂', '𜴃', '𜴄', '▝', '𜴅', '𜴆', '𜴇', '𜴈', '▀', '𜴉', '𜴊', '𜴋',
+    '𜴌', '🯦', '𜴍', '𜴎', '𜴏', '𜴐', '𜴑', '𜴒', '𜴓', '𜴔', '𜴕', '𜴖', '𜴗', '𜴘', '𜴙', '𜴚', '𜴛', '𜴜', '𜴝',
+    '𜴞', '𜴟', '🯧', '𜴠', '𜴡', '𜴢', '𜴣', '𜴤', '𜴥', '𜴦', '𜴧', '𜴨', '𜴩', '𜴪', '𜴫', '𜴬', '𜴭', '𜴮', '𜴯',
+    '𜴰', '𜴱', '𜴲', '𜴳', '𜴴', '𜴵', '🮅', '𜺣', '𜴶', '𜴷', '𜴸', '𜴹', '𜴺', '𜴻', '𜴼', '𜴽', '𜴾', '𜴿', '𜵀',
+    '𜵁', '𜵂', '𜵃', '𜵄', '▖', '𜵅', '𜵆', '𜵇', '𜵈', '▌', '𜵉', '𜵊', '𜵋', '𜵌', '▞', '𜵍', '𜵎', '𜵏', '𜵐',
+    '▛', '𜵑', '𜵒', '𜵓', '𜵔', '𜵕', '𜵖', '𜵗', '𜵘', '𜵙', '𜵚', '𜵛', '𜵜', '𜵝', '𜵞', '𜵟', '𜵠', '𜵡', '𜵢',
+    '𜵣', '𜵤', '𜵥', '𜵦', '𜵧', '𜵨', '𜵩', '𜵪', '𜵫', '𜵬', '𜵭', '𜵮', '𜵯', '𜵰', '𜺠', '𜵱', '𜵲', '𜵳', '𜵴',
+    '𜵵', '𜵶', '𜵷', '𜵸', '𜵹', '𜵺', '𜵻', '𜵼', '𜵽', '𜵾', '𜵿', '𜶀', '𜶁', '𜶂', '𜶃', '𜶄', '𜶅', '𜶆', '𜶇',
+    '𜶈', '𜶉', '𜶊', '𜶋', '𜶌', '𜶍', '𜶎', '𜶏', '▗', '𜶐', '𜶑', '𜶒', '𜶓', '▚', '𜶔', '𜶕', '𜶖', '𜶗', '▐',
+    '𜶘', '𜶙', '𜶚', '𜶛', '▜', '𜶜', '𜶝', '𜶞', '𜶟', '𜶠', '𜶡', '𜶢', '𜶣', '𜶤', '𜶥', '𜶦', '𜶧', '𜶨', '𜶩',
+    '𜶪', '𜶫', '▂', '𜶬', '𜶭', '𜶮', '𜶯', '𜶰', '𜶱', '𜶲', '𜶳', '𜶴', '𜶵', '𜶶', '𜶷', '𜶸', '𜶹', '𜶺', '𜶻',
+    '𜶼', '𜶽', '𜶾', '𜶿', '𜷀', '𜷁', '𜷂', '𜷃', '𜷄', '𜷅', '𜷆', '𜷇', '𜷈', '𜷉', '𜷊', '𜷋', '𜷌', '𜷍', '𜷎',
+    '𜷏', '𜷐', '𜷑', '𜷒', '𜷓', '𜷔', '𜷕', '𜷖', '𜷗', '𜷘', '𜷙', '𜷚', '▄', '𜷛', '𜷜', '𜷝', '𜷞', '▙', '𜷟',
+    '𜷠', '𜷡', '𜷢', '▟', '𜷣', '▆', '𜷤', '𜷥', '█',
+];

ratatui-core/src/terminal.rs

@@ -31,10 +31,381 @@
 //! [`Backend`]: crate::backend::Backend
 //! [`Buffer`]: crate::buffer::Buffer
 
+mod backend;
+mod buffers;
+mod cursor;
 mod frame;
-mod terminal;
+mod init;
+mod inline;
+mod render;
+mod resize;
 mod viewport;
 
 pub use frame::{CompletedFrame, Frame};
-pub use terminal::{Options as TerminalOptions, Terminal};
 pub use viewport::Viewport;
+
+use crate::backend::Backend;
+use crate::buffer::Buffer;
+use crate::layout::{Position, Rect};
+
+/// An interface to interact and draw [`Frame`]s on the user's terminal.
+///
+/// This is the main entry point for Ratatui. It is responsible for drawing and maintaining the
+/// state of the buffers, cursor and viewport.
+///
+/// If you're building a fullscreen application with the `ratatui` crate's default backend
+/// ([Crossterm]), prefer [`ratatui::run`] (or [`ratatui::init`] + [`ratatui::restore`]) over
+/// constructing `Terminal` directly. These helpers enable common terminal modes (raw mode +
+/// alternate screen) and restore them on exit and on panic.
+///
+/// ```rust,ignore
+/// ratatui::run(|terminal| {
+///     let mut should_quit = false;
+///     while !should_quit {
+///         terminal.draw(|frame| {
+///             frame.render_widget("Hello, World!", frame.area());
+///         })?;
+///
+///         // Handle events, update application state, and set `should_quit = true` to exit.
+///     }
+///     Ok(())
+/// })?;
+/// ```
+///
+/// # Typical Usage
+///
+/// In a typical application, the flow is: set up a terminal, run an event loop, update state, and
+/// draw each frame.
+///
+/// 1. Choose a setup path for a `Terminal`. Most apps call [`ratatui::run`], which passes a
+///    preconfigured `Terminal` into your callback. If you need more control, use [`ratatui::init`]
+///    and [`ratatui::restore`], or construct a `Terminal` manually via [`Terminal::new`]
+///    (fullscreen) or [`Terminal::with_options`] (select a [`Viewport`]).
+/// 2. Enter your application's event loop and call [`Terminal::draw`] (or [`Terminal::try_draw`])
+///    to render the current UI state into a [`Frame`].
+/// 3. Handle input and application state updates between draw calls.
+/// 4. If the terminal is resized, call [`Terminal::draw`] again. Ratatui automatically resizes
+///    fullscreen and inline viewports during `draw`; fixed viewports require an explicit call to
+///    [`Terminal::resize`] if you want the region to change.
+///
+/// # Rendering Pipeline
+///
+/// A single call to [`Terminal::draw`] (or [`Terminal::try_draw`]) represents one render pass. In
+/// broad strokes, Ratatui:
+///
+/// 1. Checks whether the underlying terminal size changed (see [`Terminal::autoresize`]).
+/// 2. Creates a [`Frame`] backed by the current buffer (see [`Terminal::get_frame`]).
+/// 3. Runs your render callback to populate that buffer.
+/// 4. Diffs the current buffer against the previous buffer and writes the changes (see
+///    [`Terminal::flush`]).
+/// 5. Applies cursor visibility and position requested by the frame (see
+///    [`Frame::set_cursor_position`]).
+/// 6. Swaps the buffers to prepare for the next render pass (see [`Terminal::swap_buffers`]).
+/// 7. Flushes the backend (see [`Backend::flush`]).
+///
+/// Each render pass starts with an empty buffer for the current viewport. Your render callback
+/// should render everything that should be visible in [`Frame::area`], even if it is unchanged
+/// from the previous frame. Ratatui diffs the current and previous buffers and only writes the
+/// changes; anything you don't render is treated as empty and may clear previously drawn content.
+///
+/// If the viewport size changes between render passes (for example via [`Terminal::autoresize`] or
+/// an explicit [`Terminal::resize`]), Ratatui clears the viewport and resets the previous buffer so
+/// the next `draw` is treated as a full redraw.
+///
+/// Most applications should use [`Terminal::draw`] / [`Terminal::try_draw`]. For manual rendering
+/// (primarily for tests), you can build a frame with [`Terminal::get_frame`], write diffs with
+/// [`Terminal::flush`], then call [`Terminal::swap_buffers`]. If your backend buffers output, also
+/// call [`Backend::flush`].
+///
+/// ```rust,no_run
+/// # mod ratatui {
+/// #     pub use ratatui_core::backend;
+/// #     pub use ratatui_core::terminal::Terminal;
+/// # }
+/// use ratatui::Terminal;
+/// use ratatui::backend::{Backend, TestBackend};
+///
+/// let backend = TestBackend::new(10, 10);
+/// let mut terminal = Terminal::new(backend)?;
+///
+/// // Manual render pass (roughly what `Terminal::draw` does internally).
+/// {
+///     let mut frame = terminal.get_frame();
+///     frame.render_widget("Hello World!", frame.area());
+/// }
+///
+/// terminal.flush()?;
+/// terminal.swap_buffers();
+/// terminal.backend_mut().flush()?;
+/// # Ok::<(), Box<dyn std::error::Error>>(())
+/// ```
+///
+/// # Viewports
+///
+/// The viewport controls *where* Ratatui draws and therefore what [`Frame::area`] represents.
+/// Most applications use [`Viewport::Fullscreen`], but Ratatui also supports [`Viewport::Inline`]
+/// and [`Viewport::Fixed`].
+///
+/// Choose a viewport at initialization time with [`Terminal::with_options`] and
+/// [`TerminalOptions`].
+///
+/// In [`Viewport::Fullscreen`], the viewport is the entire terminal and `Frame::area` starts at
+/// (0, 0). Ratatui automatically resizes the internal buffers when the terminal size changes.
+///
+/// In [`Viewport::Fixed`], the viewport is a user-provided [`Rect`] in terminal coordinates.
+/// `Frame::area` is that exact rectangle (including its `x`/`y` offset). Fixed viewports are not
+/// automatically resized; if the region should change, call [`Terminal::resize`].
+///
+/// In [`Viewport::Inline`], Ratatui draws into a rectangle anchored to where the UI started. This
+/// mode is described in more detail in the "Inline Viewport" section below.
+///
+/// ```rust,ignore
+/// use ratatui::{layout::Rect, Terminal, TerminalOptions, Viewport};
+/// use ratatui::backend::CrosstermBackend;
+///
+/// // Fullscreen (most common):
+/// let fullscreen = Terminal::new(CrosstermBackend::new(std::io::stdout()))?;
+///
+/// // Fixed region (your app manages the coordinates):
+/// let viewport = Viewport::Fixed(Rect::new(0, 0, 30, 10));
+/// let fixed = Terminal::with_options(
+///     CrosstermBackend::new(std::io::stdout()),
+///     TerminalOptions { viewport },
+/// )?;
+/// ```
+///
+/// Applications should detect terminal resizes and call [`Terminal::draw`] to redraw the
+/// application with the new size. This will automatically resize the internal buffers to match the
+/// new size for inline and fullscreen viewports. Fixed viewports are not resized automatically.
+///
+/// # Inline Viewport
+///
+/// Inline mode is designed for applications that want to embed a UI into a larger CLI flow. In
+/// [`Viewport::Inline`], Ratatui anchors the viewport to the backend cursor row at initialization
+/// time and always starts drawing at column 0.
+///
+/// To reserve vertical space for the requested height, Ratatui may append lines. When the cursor is
+/// near the bottom edge, terminals scroll; Ratatui accounts for that scrolling by shifting the
+/// computed viewport origin upward so the viewport stays fully visible.
+///
+/// While running in inline mode, [`Terminal::insert_before`] can be used to print output above the
+/// viewport without disturbing the UI.
+/// When Ratatui is built with the `scrolling-regions` feature, `insert_before` can do this without
+/// clearing and redrawing the viewport.
+///
+/// ```rust,ignore
+/// use ratatui::{TerminalOptions, Viewport};
+///
+/// println!("Some output above the UI");
+///
+/// let options = TerminalOptions {
+///     viewport: Viewport::Inline(10),
+/// };
+/// let mut terminal = ratatui::try_init_with_options(options)?;
+///
+/// terminal.insert_before(1, |buf| {
+///     // Render a single line of output into `buf` before the UI.
+///     // (For example: logs, status updates, or command output.)
+/// })?;
+/// ```
+///
+/// # More Information
+///
+/// - Choosing a viewport: [`Terminal::with_options`], [`TerminalOptions`], and [`Viewport`]
+/// - The rendering pipeline: [`Terminal::draw`] and [`Terminal::try_draw`]
+/// - Resize handling: [`Terminal::autoresize`] and [`Terminal::resize`]
+/// - Manual rendering and testing: [`Terminal::get_frame`], [`Terminal::flush`], and
+///   [`Terminal::swap_buffers`]
+/// - Printing above an inline UI: [`Terminal::insert_before`]
+///
+/// # Initialization
+///
+/// Most interactive TUIs need process-wide terminal setup (for example: raw mode and an alternate
+/// screen) and matching teardown on exit and on panic. In Ratatui, that setup lives in the
+/// `ratatui` crate; `Terminal` itself focuses on rendering and does not implicitly change those
+/// modes.
+///
+/// If you're using the `ratatui` crate with its default backend ([Crossterm]), there are three
+/// common entry points:
+///
+/// - [`ratatui::run`]: recommended for most applications. Provides a [`ratatui::DefaultTerminal`],
+///   runs your closure, and restores terminal state on exit and on panic.
+/// - [`ratatui::init`] + [`ratatui::restore`]: like `run`, but you control the event loop and
+///   decide when to restore.
+/// - [`Terminal::new`] / [`Terminal::with_options`]: manual construction (for example: custom
+///   backends such as [Termion] / [Termwiz], inline UIs, or fixed viewports). You are responsible
+///   for terminal mode setup and teardown.
+///
+/// [`ratatui::run`] was introduced in Ratatui 0.30, so older tutorials may use `init`/`restore` or
+/// manual construction.
+///
+/// Some applications install a custom panic hook to log a crash report, print a friendlier error,
+/// or integrate with error reporting. If you do, install it before calling [`ratatui::init`] /
+/// [`ratatui::run`]. Ratatui wraps the current hook so it can restore terminal state first (for
+/// example: leaving the alternate screen and disabling raw mode) and then delegate to your hook.
+///
+/// Crossterm is cross-platform and is what most Ratatui applications use by default. Ratatui also
+/// supports other backends such as [Termion] and [Termwiz], and third-party backends can integrate
+/// by implementing [`Backend`].
+///
+/// # How it works
+///
+/// `Terminal` ties together a [`Backend`], a [`Viewport`], and a double-buffered diffing renderer.
+/// The high-level flow is described in the "Rendering Pipeline" section above; this section focuses
+/// on how that pipeline is implemented.
+///
+/// `Terminal` is generic over a [`Backend`] implementation and does not depend on a particular
+/// terminal library. It relies on the backend to:
+///
+/// - report the current screen size (used by [`Terminal::autoresize`])
+/// - draw cell updates (used by [`Terminal::flush`])
+/// - clear regions (used by [`Terminal::clear`] and [`Terminal::resize`])
+/// - move and show/hide the cursor (used by [`Terminal::try_draw`])
+/// - optionally append lines (used by inline viewports and by [`Terminal::insert_before`])
+///
+/// ## Buffers and diffing
+///
+/// The `Terminal` maintains two [`Buffer`]s sized to the current viewport. During a render pass,
+/// widgets draw into the "current" buffer via the [`Frame`] passed to your callback. At the end of
+/// the pass, [`Terminal::flush`] diffs the current buffer against the previous buffer and sends
+/// only the changed cells to the backend.
+///
+/// After flushing, [`Terminal::swap_buffers`] flips which buffer is considered "current" and resets
+/// the next buffer. This is why each render pass starts from an empty buffer: your callback is
+/// expected to fully redraw the viewport every time.
+///
+/// The [`CompletedFrame`] returned from [`Terminal::draw`] / [`Terminal::try_draw`] provides a
+/// reference to the buffer that was just rendered, which can be useful for assertions in tests.
+///
+/// ## Viewport state and resizing
+///
+/// The active [`Viewport`] controls how the viewport area is computed:
+///
+/// - Fullscreen: `Frame::area` covers the full backend size.
+/// - Fixed: `Frame::area` is the exact rectangle you provided in terminal coordinates.
+/// - Inline: `Frame::area` is a rectangle anchored to the backend cursor row.
+///
+/// For fullscreen and inline viewports, [`Terminal::autoresize`] checks the backend size during
+/// every render pass and calls [`Terminal::resize`] when it changes. Resizing updates the internal
+/// buffer sizes and clears the affected region; it also resets the previous buffer so the next draw
+/// is treated as a full redraw.
+///
+/// ## Cursor tracking
+///
+/// The cursor position requested by [`Frame::set_cursor_position`] is applied after
+/// [`Terminal::flush`] so the cursor ends up on top of the rendered UI. `Terminal` also tracks a
+/// "last known cursor position" as a best-effort record of where it last wrote, and uses that
+/// information when recomputing inline viewports on resize.
+///
+/// ## Inline-specific behavior
+///
+/// Inline viewports reserve vertical space by calling [`Backend::append_lines`]. If the cursor is
+/// close enough to the bottom edge, terminals scroll as lines are appended. Ratatui accounts for
+/// that scrolling by shifting the computed viewport origin upward so the viewport remains fully
+/// visible. On resize, Ratatui recomputes the inline origin while trying to keep the cursor at the
+/// same relative row inside the viewport.
+///
+/// When Ratatui is built with the `scrolling-regions` feature, [`Terminal::insert_before`] uses
+/// terminal scrolling regions to insert content above an inline viewport without clearing and
+/// redrawing it.
+///
+/// [Crossterm]: https://crates.io/crates/crossterm
+/// [Termion]: https://crates.io/crates/termion
+/// [Termwiz]: https://crates.io/crates/termwiz
+/// [`backend`]: crate::backend
+/// [`Backend`]: crate::backend::Backend
+/// [`Backend::flush`]: crate::backend::Backend::flush
+/// [`Buffer`]: crate::buffer::Buffer
+/// [`ratatui::DefaultTerminal`]: https://docs.rs/ratatui/latest/ratatui/type.DefaultTerminal.html
+/// [`ratatui::init`]: https://docs.rs/ratatui/latest/ratatui/fn.init.html
+/// [`ratatui::restore`]: https://docs.rs/ratatui/latest/ratatui/fn.restore.html
+/// [`ratatui::run`]: https://docs.rs/ratatui/latest/ratatui/fn.run.html
+#[derive(Debug, Default, Clone, Eq, PartialEq, Hash)]
+pub struct Terminal<B>
+where
+    B: Backend,
+{
+    /// The backend used to write updates to the terminal.
+    ///
+    /// Most application code does not need to interact with the backend directly; see
+    /// [`Terminal::draw`]. Accessing the backend can be useful for backend-specific testing and
+    /// inspection (see [`Terminal::backend`]).
+    backend: B,
+    /// Double-buffered render state.
+    ///
+    /// [`Terminal::flush`] diffs `buffers[current]` against the other buffer to compute a minimal
+    /// set of updates to send to the backend.
+    buffers: [Buffer; 2],
+    /// Index of the "current" buffer in [`Terminal::buffers`].
+    ///
+    /// This toggles between 0 and 1 and is updated by [`Terminal::swap_buffers`].
+    current: usize,
+    /// Whether Ratatui believes it has hidden the cursor.
+    ///
+    /// This is tracked so [`Drop`] can attempt to restore cursor visibility.
+    hidden_cursor: bool,
+    /// The configured [`Viewport`] mode.
+    ///
+    /// This determines how the initial viewport area is computed during construction, whether
+    /// [`Terminal::autoresize`] runs, how [`Terminal::clear`] behaves, and whether operations like
+    /// [`Terminal::insert_before`] have any effect.
+    viewport: Viewport,
+    /// The current viewport rectangle in terminal coordinates.
+    ///
+    /// This is the area returned by [`Frame::area`] and the size of the internal buffers. It is
+    /// set during construction and updated by [`Terminal::resize`]. In inline mode, calls to
+    /// [`Terminal::insert_before`] can also move the viewport vertically.
+    viewport_area: Rect,
+    /// Last known renderable "screen" area.
+    ///
+    /// For fullscreen and inline viewports this tracks the backend-reported terminal size. For
+    /// fixed viewports, this tracks the user-provided fixed area.
+    ///
+    /// This is used by [`Terminal::autoresize`] and is reported via [`CompletedFrame::area`].
+    last_known_area: Rect,
+    /// Last known cursor position in terminal coordinates.
+    ///
+    /// This is updated when:
+    ///
+    /// - [`Terminal::set_cursor_position`] is called directly.
+    /// - [`Frame::set_cursor_position`] is used during [`Terminal::draw`].
+    /// - [`Terminal::flush`] observes a diff update (used as a proxy for the "last written" cell).
+    ///
+    /// Inline viewports use this during [`Terminal::resize`] to preserve the cursor's relative
+    /// position within the viewport.
+    last_known_cursor_pos: Position,
+    /// Number of frames rendered so far.
+    ///
+    /// This increments after each successful [`Terminal::draw`] / [`Terminal::try_draw`] and wraps
+    /// at `usize::MAX`.
+    frame_count: usize,
+}
+
+/// Options to pass to [`Terminal::with_options`]
+///
+/// Most applications can use [`Terminal::new`]. Use `TerminalOptions` when you need to configure a
+/// non-default [`Viewport`] at initialization time (see [`Terminal`] for an overview).
+#[derive(Debug, Default, Clone, Eq, PartialEq, Hash)]
+pub struct TerminalOptions {
+    /// Viewport used to draw to the terminal.
+    ///
+    /// See [`Terminal`] for a higher-level overview, and [`Viewport`] for the per-variant
+    /// definition.
+    pub viewport: Viewport,
+}
+
+impl<B> Drop for Terminal<B>
+where
+    B: Backend,
+{
+    fn drop(&mut self) {
+        // Attempt to restore the cursor state
+        if self.hidden_cursor {
+            #[allow(unused_variables)]
+            if let Err(err) = self.show_cursor() {
+                #[cfg(feature = "std")]
+                std::eprintln!("Failed to show the cursor: {err}");
+            }
+        }
+    }
+}

ratatui-core/src/terminal/backend.rs

@@ -0,0 +1,75 @@
+use crate::backend::Backend;
+use crate::layout::Size;
+use crate::terminal::Terminal;
+
+impl<B: Backend> Terminal<B> {
+    /// Returns a shared reference to the backend.
+    ///
+    /// This is primarily useful for backend-specific inspection in tests (e.g. reading
+    /// [`TestBackend`]'s buffer). Most applications should interact with the terminal via
+    /// [`Terminal::draw`] rather than calling backend methods directly.
+    ///
+    /// [`TestBackend`]: crate::backend::TestBackend
+    pub const fn backend(&self) -> &B {
+        &self.backend
+    }
+
+    /// Returns a mutable reference to the backend.
+    ///
+    /// This is an advanced escape hatch. Mutating the backend directly can desynchronize Ratatui's
+    /// internal buffers from what's on-screen; if you do this, you may need to call
+    /// [`Terminal::clear`] to force a full redraw.
+    pub const fn backend_mut(&mut self) -> &mut B {
+        &mut self.backend
+    }
+
+    /// Queries the real size of the backend.
+    ///
+    /// This returns the size of the underlying terminal. The current renderable area depends on
+    /// the configured [`Viewport`]; use [`Frame::area`] inside [`Terminal::draw`] if you want the
+    /// area you should render into.
+    ///
+    /// [`Frame::area`]: crate::terminal::Frame::area
+    /// [`Terminal::draw`]: crate::terminal::Terminal::draw
+    /// [`Viewport`]: crate::terminal::Viewport
+    pub fn size(&self) -> Result<Size, B::Error> {
+        self.backend.size()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use crate::backend::TestBackend;
+    use crate::layout::{Position, Size};
+    use crate::terminal::Terminal;
+
+    #[test]
+    fn backend_returns_shared_reference() {
+        let backend = TestBackend::new(3, 2);
+        let terminal = Terminal::new(backend).unwrap();
+
+        assert_eq!(terminal.backend().cursor_position(), Position::ORIGIN);
+    }
+
+    #[test]
+    fn backend_mut_allows_mutating_backend_state() {
+        let backend = TestBackend::new(3, 2);
+        let mut terminal = Terminal::new(backend).unwrap();
+
+        terminal.backend_mut().resize(4, 3);
+
+        assert_eq!(terminal.size().unwrap(), Size::new(4, 3));
+        terminal
+            .backend()
+            .assert_buffer_lines(["    ", "    ", "    "]);
+    }
+
+    #[test]
+    fn size_queries_underlying_backend_size() {
+        let mut backend = TestBackend::new(3, 2);
+        backend.resize(4, 3);
+        let terminal = Terminal::new(backend).unwrap();
+
+        assert_eq!(terminal.size().unwrap(), Size::new(4, 3));
+    }
+}

ratatui-core/src/terminal/buffers.rs

@@ -0,0 +1,380 @@
+use crate::backend::{Backend, ClearType};
+use crate::buffer::{Buffer, Cell};
+use crate::layout::{Position, Rect};
+use crate::terminal::{Frame, Terminal, Viewport};
+
+impl<B: Backend> Terminal<B> {
+    /// Returns a [`Frame`] for manual rendering.
+    ///
+    /// Most applications should render via [`Terminal::draw`] / [`Terminal::try_draw`]. This method
+    /// exposes the frame construction step used by [`Terminal::try_draw`] so tests and advanced
+    /// callers can render without running the full draw pipeline.
+    ///
+    /// Unlike `draw` / `try_draw`, this does not call [`Terminal::autoresize`], does not write
+    /// updates to the backend, and does not apply any cursor changes. After rendering, you
+    /// typically call [`Terminal::flush`], [`Terminal::swap_buffers`], and [`Backend::flush`].
+    ///
+    /// The returned `Frame` mutably borrows the current buffer, so it must be dropped before you
+    /// can call methods like [`Terminal::flush`]. The example below uses a scope to make that
+    /// explicit.
+    ///
+    /// # Example
+    ///
+    /// ```rust,no_run
+    /// # mod ratatui {
+    /// #     pub use ratatui_core::backend;
+    /// #     pub use ratatui_core::terminal::Terminal;
+    /// # }
+    /// use ratatui::Terminal;
+    /// use ratatui::backend::{Backend, TestBackend};
+    ///
+    /// let backend = TestBackend::new(30, 5);
+    /// let mut terminal = Terminal::new(backend)?;
+    /// {
+    ///     let mut frame = terminal.get_frame();
+    ///     frame.render_widget("Hello", frame.area());
+    /// }
+    /// // When not using `draw`, present the buffer manually:
+    /// terminal.flush()?;
+    /// terminal.swap_buffers();
+    /// terminal.backend_mut().flush()?;
+    /// # Ok::<(), Box<dyn std::error::Error>>(())
+    /// ```
+    ///
+    /// [`Backend::flush`]: crate::backend::Backend::flush
+    pub const fn get_frame(&mut self) -> Frame<'_> {
+        let count = self.frame_count;
+        Frame {
+            cursor_position: None,
+            viewport_area: self.viewport_area,
+            buffer: self.current_buffer_mut(),
+            count,
+        }
+    }
+
+    /// Gets the current buffer as a mutable reference.
+    ///
+    /// This is the buffer that the next [`Frame`] will render into (see [`Terminal::get_frame`]).
+    /// Most applications should render inside [`Terminal::draw`] and access the buffer via
+    /// [`Frame::buffer_mut`] instead.
+    pub const fn current_buffer_mut(&mut self) -> &mut Buffer {
+        &mut self.buffers[self.current]
+    }
+
+    /// Writes the current buffer to the backend using a diff against the previous buffer.
+    ///
+    /// This is one of the building blocks used by [`Terminal::draw`] / [`Terminal::try_draw`]. It
+    /// does not swap buffers or flush the backend; see [`Terminal::swap_buffers`] and
+    /// [`Backend::flush`].
+    ///
+    /// Implementation note: when there are updates, Ratatui records the position of the last
+    /// updated cell as the "last known cursor position". Inline viewports use this to preserve the
+    /// cursor's relative position within the viewport across resizes.
+    ///
+    /// [`Backend::flush`]: crate::backend::Backend::flush
+    pub fn flush(&mut self) -> Result<(), B::Error> {
+        let previous_buffer = &self.buffers[1 - self.current];
+        let current_buffer = &self.buffers[self.current];
+        let updates = previous_buffer.diff(current_buffer);
+        if let Some((col, row, _)) = updates.last() {
+            self.last_known_cursor_pos = Position { x: *col, y: *row };
+        }
+        self.backend.draw(updates.into_iter())
+    }
+
+    /// Clears the inactive buffer and swaps it with the current buffer.
+    ///
+    /// This is part of the standard rendering flow (see [`Terminal::try_draw`]). If you render
+    /// manually using [`Terminal::get_frame`] and [`Terminal::flush`], call this afterward so the
+    /// next flush can compute diffs against the correct "previous" buffer.
+    pub fn swap_buffers(&mut self) {
+        self.buffers[1 - self.current].reset();
+        self.current = 1 - self.current;
+    }
+
+    /// Clear the terminal and force a full redraw on the next draw call.
+    ///
+    /// What gets cleared depends on the active [`Viewport`]:
+    ///
+    /// - [`Viewport::Fullscreen`]: clears the entire terminal.
+    /// - [`Viewport::Fixed`]: clears only the viewport region.
+    /// - [`Viewport::Inline`]: clears after the viewport's origin, leaving any content above the
+    ///   viewport untouched.
+    ///
+    /// Current behavior: for [`Viewport::Inline`], clearing runs from the viewport origin through
+    /// the end of the visible display area, not just the viewport's rectangle. This is an
+    /// implementation detail rather than a contract; do not rely on it.
+    ///
+    /// This preserves the cursor position.
+    ///
+    /// This also resets the "previous" buffer so the next [`Terminal::flush`] redraws the full
+    /// viewport. [`Terminal::resize`] calls this internally.
+    ///
+    /// Implementation note: this uses [`ClearType::AfterCursor`] starting at the viewport origin.
+    pub fn clear(&mut self) -> Result<(), B::Error> {
+        let original_cursor = self.backend.get_cursor_position()?;
+        match self.viewport {
+            Viewport::Fullscreen => self.backend.clear_region(ClearType::All)?,
+            Viewport::Inline(_) => {
+                self.backend
+                    .set_cursor_position(self.viewport_area.as_position())?;
+                self.backend.clear_region(ClearType::AfterCursor)?;
+            }
+            Viewport::Fixed(_) => {
+                let area = self.viewport_area;
+                self.clear_fixed_viewport(area)?;
+            }
+        }
+        self.backend.set_cursor_position(original_cursor)?;
+        // Reset the back buffer to make sure the next update will redraw everything.
+        self.buffers[1 - self.current].reset();
+        Ok(())
+    }
+
+    /// Clears a fixed viewport using terminal clear commands when possible.
+    ///
+    /// Terminal clear commands can be faster than per-cell updates.
+    fn clear_fixed_viewport(&mut self, area: Rect) -> Result<(), B::Error> {
+        if area.is_empty() {
+            return Ok(());
+        }
+        let size = self.backend.size()?;
+        let is_full_width = area.x == 0 && area.width == size.width;
+        let ends_at_bottom = area.bottom() == size.height;
+        if is_full_width && ends_at_bottom {
+            self.backend.set_cursor_position(area.as_position())?;
+            self.backend.clear_region(ClearType::AfterCursor)?;
+        } else if is_full_width {
+            self.clear_full_width_rows(area)?;
+        } else {
+            self.clear_region_cells(area)?;
+        }
+        Ok(())
+    }
+
+    /// Clears full-width rows using line clear commands.
+    ///
+    /// This avoids per-cell writes when the viewport spans the full width.
+    fn clear_full_width_rows(&mut self, area: Rect) -> Result<(), B::Error> {
+        for y in area.top()..area.bottom() {
+            self.backend.set_cursor_position(Position { x: 0, y })?;
+            self.backend.clear_region(ClearType::CurrentLine)?;
+        }
+        Ok(())
+    }
+
+    /// Clears a non-full-width region by writing empty cells directly.
+    ///
+    /// This is used when line-based clears would affect cells outside the viewport.
+    fn clear_region_cells(&mut self, area: Rect) -> Result<(), B::Error> {
+        let clear_cell = Cell::default();
+        let updates = area.positions().map(|pos| (pos.x, pos.y, &clear_cell));
+        self.backend.draw(updates)?;
+        Ok(())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use crate::backend::{Backend, TestBackend};
+    use crate::buffer::{Buffer, Cell};
+    use crate::layout::{Position, Rect};
+    use crate::terminal::{Terminal, TerminalOptions, Viewport};
+
+    #[test]
+    fn get_frame_uses_current_viewport_and_frame_count() {
+        let backend = TestBackend::new(5, 3);
+        let mut terminal = Terminal::new(backend).unwrap();
+
+        let frame = terminal.get_frame();
+        assert_eq!(frame.count, 0);
+        assert_eq!(frame.area().width, 5);
+        assert_eq!(frame.area().height, 3);
+        assert_eq!(frame.buffer.area, frame.area());
+    }
+
+    #[test]
+    fn flush_writes_updates_and_tracks_last_updated_cell() {
+        let backend = TestBackend::new(3, 2);
+        let mut terminal = Terminal::new(backend).unwrap();
+
+        {
+            let frame = terminal.get_frame();
+            frame.buffer[(1, 0)].set_symbol("x");
+        }
+
+        terminal.flush().unwrap();
+        terminal.backend().assert_buffer_lines([" x ", "   "]);
+        assert_eq!(terminal.last_known_cursor_pos, Position { x: 1, y: 0 });
+    }
+
+    #[test]
+    fn flush_with_no_updates_does_not_change_last_known_cursor_pos() {
+        let backend = TestBackend::new(3, 2);
+        let mut terminal = Terminal::new(backend).unwrap();
+        terminal.set_cursor_position((2, 1)).unwrap();
+
+        terminal.flush().unwrap();
+
+        assert_eq!(terminal.last_known_cursor_pos, Position { x: 2, y: 1 });
+    }
+
+    #[test]
+    fn swap_buffers_resets_new_current_buffer() {
+        let backend = TestBackend::new(3, 2);
+        let mut terminal = Terminal::new(backend).unwrap();
+
+        terminal.buffers[1][(0, 0)].set_symbol("x");
+        terminal.swap_buffers();
+
+        assert_eq!(terminal.current, 1);
+        assert_eq!(
+            terminal.buffers[terminal.current],
+            Buffer::empty(terminal.viewport_area)
+        );
+    }
+
+    #[test]
+    fn clear_fullscreen_clears_backend_and_resets_back_buffer() {
+        let backend = TestBackend::new(3, 2);
+        let mut terminal = Terminal::new(backend).unwrap();
+
+        {
+            let frame = terminal.get_frame();
+            frame.buffer[(0, 0)] = Cell::new("x");
+        }
+        terminal.flush().unwrap();
+        terminal.backend().assert_buffer_lines(["x  ", "   "]);
+
+        terminal.buffers[1][(2, 1)] = Cell::new("y");
+        terminal.clear().unwrap();
+
+        terminal.backend().assert_buffer_lines(["   ", "   "]);
+        assert_eq!(
+            terminal.buffers[1 - terminal.current],
+            Buffer::empty(terminal.viewport_area)
+        );
+    }
+
+    #[test]
+    fn clear_inline_clears_after_viewport_origin_and_resets_back_buffer() {
+        // Inline clear is implemented as:
+        //   1) move the backend cursor to the viewport origin
+        //   2) call ClearType::AfterCursor once
+        let mut backend = TestBackend::with_lines([
+            "before 1  ",
+            "before 2  ",
+            "viewport 1",
+            "viewport 2",
+            "after 1   ",
+            "after 2   ",
+        ]);
+        backend
+            .set_cursor_position(Position { x: 2, y: 2 })
+            .unwrap();
+        let options = TerminalOptions {
+            viewport: Viewport::Inline(2),
+        };
+        let mut terminal = Terminal::with_options(backend, options).unwrap();
+        terminal
+            .backend_mut()
+            .set_cursor_position(Position { x: 2, y: 2 })
+            .unwrap();
+
+        terminal.buffers[1][(2, 2)] = Cell::new("x");
+        terminal.clear().unwrap();
+
+        // Inline viewport is anchored to the cursor row (y = 2) with height 2. Clear runs from
+        // the viewport origin through the end of the display, including the rows after it.
+        terminal.backend().assert_buffer_lines([
+            "before 1  ",
+            "before 2  ",
+            "          ",
+            "          ",
+            "          ",
+            "          ",
+        ]);
+        assert_eq!(
+            terminal.buffers[1 - terminal.current],
+            Buffer::empty(terminal.viewport_area)
+        );
+        assert_eq!(
+            terminal.backend().cursor_position(),
+            Position { x: 2, y: 2 }
+        );
+    }
+
+    #[test]
+    fn clear_fixed_clears_viewport_rows_and_resets_back_buffer() {
+        // For full-width fixed viewports that reach the terminal bottom, clear uses
+        // ClearType::AfterCursor starting at the viewport origin.
+        let mut backend = TestBackend::with_lines(["before 1  ", "viewport 1", "viewport 2"]);
+        backend.set_cursor_position((2, 0)).unwrap();
+        let options = TerminalOptions {
+            viewport: Viewport::Fixed(Rect::new(0, 1, 10, 2)),
+        };
+        let mut terminal = Terminal::with_options(backend, options).unwrap();
+
+        terminal.clear().unwrap();
+
+        terminal
+            .backend()
+            .assert_buffer_lines(["before 1  ", "          ", "          "]);
+        assert_eq!(
+            terminal.buffers[1 - terminal.current],
+            Buffer::empty(terminal.viewport_area)
+        );
+        assert_eq!(
+            terminal.backend().cursor_position(),
+            Position { x: 2, y: 0 }
+        );
+    }
+
+    #[test]
+    fn clear_fixed_full_width_not_at_bottom() {
+        let mut backend =
+            TestBackend::with_lines(["before 1  ", "viewport 1", "viewport 2", "after 1   "]);
+        backend.set_cursor_position((1, 0)).unwrap();
+        let options = TerminalOptions {
+            viewport: Viewport::Fixed(Rect::new(0, 1, 10, 2)),
+        };
+        let mut terminal = Terminal::with_options(backend, options).unwrap();
+
+        terminal.clear().unwrap();
+
+        terminal.backend().assert_buffer_lines([
+            "before 1  ",
+            "          ",
+            "          ",
+            "after 1   ",
+        ]);
+        assert_eq!(
+            terminal.backend().cursor_position(),
+            Position { x: 1, y: 0 }
+        );
+    }
+
+    #[test]
+    fn clear_fixed_respects_non_full_width_viewport() {
+        let mut backend =
+            TestBackend::with_lines(["before 1  ", "viewport 1", "viewport 2", "after 1   "]);
+        backend.set_cursor_position((3, 0)).unwrap();
+        let options = TerminalOptions {
+            viewport: Viewport::Fixed(Rect::new(1, 1, 3, 2)),
+        };
+        let mut terminal = Terminal::with_options(backend, options).unwrap();
+
+        terminal.clear().unwrap();
+
+        terminal.backend().assert_buffer_lines([
+            "before 1  ",
+            "v   port 1",
+            "v   port 2",
+            "after 1   ",
+        ]);
+        assert_eq!(
+            terminal.backend().cursor_position(),
+            Position { x: 3, y: 0 }
+        );
+    }
+}

ratatui-core/src/terminal/cursor.rs

@@ -0,0 +1,151 @@
+use crate::backend::Backend;
+use crate::layout::Position;
+use crate::terminal::Terminal;
+
+impl<B: Backend> Terminal<B> {
+    /// Hides the cursor.
+    ///
+    /// When using [`Terminal::draw`], prefer controlling the cursor with
+    /// [`Frame::set_cursor_position`]. Mixing the APIs can lead to surprising results.
+    ///
+    /// [`Frame::set_cursor_position`]: crate::terminal::Frame::set_cursor_position
+    /// [`Terminal::draw`]: crate::terminal::Terminal::draw
+    pub fn hide_cursor(&mut self) -> Result<(), B::Error> {
+        self.backend.hide_cursor()?;
+        self.hidden_cursor = true;
+        Ok(())
+    }
+
+    /// Shows the cursor.
+    ///
+    /// When using [`Terminal::draw`], prefer controlling the cursor with
+    /// [`Frame::set_cursor_position`]. Mixing the APIs can lead to surprising results.
+    ///
+    /// [`Frame::set_cursor_position`]: crate::terminal::Frame::set_cursor_position
+    /// [`Terminal::draw`]: crate::terminal::Terminal::draw
+    pub fn show_cursor(&mut self) -> Result<(), B::Error> {
+        self.backend.show_cursor()?;
+        self.hidden_cursor = false;
+        Ok(())
+    }
+
+    /// Gets the current cursor position.
+    ///
+    /// This is the position of the cursor after the last draw call and is returned as a tuple of
+    /// `(x, y)` coordinates.
+    #[deprecated = "use `get_cursor_position()` instead which returns `Result<Position>`"]
+    pub fn get_cursor(&mut self) -> Result<(u16, u16), B::Error> {
+        let Position { x, y } = self.get_cursor_position()?;
+        Ok((x, y))
+    }
+
+    /// Sets the cursor position.
+    #[deprecated = "use `set_cursor_position((x, y))` instead which takes `impl Into<Position>`"]
+    pub fn set_cursor(&mut self, x: u16, y: u16) -> Result<(), B::Error> {
+        self.set_cursor_position(Position { x, y })
+    }
+
+    /// Gets the current cursor position.
+    ///
+    /// This queries the backend for the current cursor position.
+    ///
+    /// When using [`Terminal::draw`], prefer controlling the cursor with
+    /// [`Frame::set_cursor_position`]. For direct control, see [`Terminal::set_cursor_position`].
+    ///
+    /// [`Frame::set_cursor_position`]: crate::terminal::Frame::set_cursor_position
+    /// [`Terminal::draw`]: crate::terminal::Terminal::draw
+    pub fn get_cursor_position(&mut self) -> Result<Position, B::Error> {
+        self.backend.get_cursor_position()
+    }
+
+    /// Sets the cursor position.
+    ///
+    /// This updates the backend cursor and Ratatui's internal cursor tracking. Inline viewports
+    /// use that tracking when recomputing the viewport on resize.
+    ///
+    /// When using [`Terminal::draw`], consider using [`Frame::set_cursor_position`] instead so the
+    /// cursor is updated as part of the normal rendering flow.
+    ///
+    /// [`Frame::set_cursor_position`]: crate::terminal::Frame::set_cursor_position
+    /// [`Terminal::draw`]: crate::terminal::Terminal::draw
+    pub fn set_cursor_position<P: Into<Position>>(&mut self, position: P) -> Result<(), B::Error> {
+        let position = position.into();
+        self.backend.set_cursor_position(position)?;
+        self.last_known_cursor_pos = position;
+        Ok(())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use crate::backend::{Backend, TestBackend};
+    use crate::layout::Position;
+    use crate::terminal::Terminal;
+
+    #[test]
+    fn hide_cursor_updates_terminal_state() {
+        let backend = TestBackend::new(10, 5);
+        let mut terminal = Terminal::new(backend).unwrap();
+
+        terminal.hide_cursor().unwrap();
+
+        assert!(terminal.hidden_cursor);
+        assert!(!terminal.backend().cursor_visible());
+    }
+
+    #[test]
+    fn show_cursor_updates_terminal_state() {
+        let backend = TestBackend::new(10, 5);
+        let mut terminal = Terminal::new(backend).unwrap();
+
+        terminal.hide_cursor().unwrap();
+        terminal.show_cursor().unwrap();
+
+        assert!(!terminal.hidden_cursor);
+        assert!(terminal.backend().cursor_visible());
+    }
+
+    #[test]
+    fn set_cursor_position_updates_backend_and_tracking() {
+        let backend = TestBackend::new(10, 5);
+        let mut terminal = Terminal::new(backend).unwrap();
+
+        terminal.set_cursor_position((3, 4)).unwrap();
+
+        assert_eq!(terminal.last_known_cursor_pos, Position { x: 3, y: 4 });
+        terminal
+            .backend_mut()
+            .assert_cursor_position(Position { x: 3, y: 4 });
+    }
+
+    #[test]
+    fn get_cursor_position_queries_backend() {
+        let backend = TestBackend::new(10, 5);
+        let mut terminal = Terminal::new(backend).unwrap();
+
+        terminal
+            .backend_mut()
+            .set_cursor_position(Position { x: 7, y: 2 })
+            .unwrap();
+
+        assert_eq!(
+            terminal.get_cursor_position().unwrap(),
+            Position { x: 7, y: 2 }
+        );
+    }
+
+    #[test]
+    #[allow(deprecated)]
+    fn deprecated_cursor_wrappers_delegate_to_position_apis() {
+        let backend = TestBackend::new(10, 5);
+        let mut terminal = Terminal::new(backend).unwrap();
+
+        terminal.set_cursor(4, 1).unwrap();
+
+        assert_eq!(terminal.get_cursor().unwrap(), (4, 1));
+        assert_eq!(terminal.last_known_cursor_pos, Position { x: 4, y: 1 });
+        terminal
+            .backend_mut()
+            .assert_cursor_position(Position { x: 4, y: 1 });
+    }
+}

ratatui-core/src/terminal/init.rs

@@ -0,0 +1,236 @@
+use crate::backend::Backend;
+use crate::buffer::Buffer;
+use crate::layout::Position;
+use crate::terminal::inline::compute_inline_size;
+use crate::terminal::{Terminal, TerminalOptions, Viewport};
+
+impl<B: Backend> Terminal<B> {
+    /// Creates a new [`Terminal`] with the given [`Backend`] with a full screen viewport.
+    ///
+    /// This is a convenience for [`Terminal::with_options`] with [`Viewport::Fullscreen`].
+    ///
+    /// After creating a terminal, call [`Terminal::draw`] (or [`Terminal::try_draw`]) in a loop to
+    /// render your UI.
+    ///
+    /// Note that unlike [`ratatui::init`], this does not install a panic hook, so it is
+    /// recommended to do that manually when using this function, otherwise any panic messages will
+    /// be printed to the alternate screen and the terminal may be left in an unusable state.
+    ///
+    /// See [how to set up panic hooks](https://ratatui.rs/recipes/apps/panic-hooks/) and
+    /// [`better-panic` example](https://ratatui.rs/recipes/apps/better-panic/) for more
+    /// information.
+    ///
+    /// # Example
+    ///
+    /// ```rust,no_run
+    /// # #![allow(unexpected_cfgs)]
+    /// # #[cfg(feature = "crossterm")]
+    /// # {
+    /// use std::io::stdout;
+    ///
+    /// use ratatui::Terminal;
+    /// use ratatui::backend::CrosstermBackend;
+    ///
+    /// let backend = CrosstermBackend::new(stdout());
+    /// let _terminal = Terminal::new(backend)?;
+    ///
+    /// // Optionally set up a panic hook to restore the terminal on panic.
+    /// let old_hook = std::panic::take_hook();
+    /// std::panic::set_hook(Box::new(move |info| {
+    ///     ratatui::restore();
+    ///     old_hook(info);
+    /// }));
+    /// # }
+    /// # #[cfg(not(feature = "crossterm"))]
+    /// # {
+    /// # use ratatui_core::{backend::TestBackend, terminal::Terminal};
+    /// # let backend = TestBackend::new(10, 10);
+    /// # let _terminal = Terminal::new(backend)?;
+    /// # }
+    /// # Ok::<(), Box<dyn std::error::Error>>(())
+    /// ```
+    ///
+    /// [`ratatui::init`]: https://docs.rs/ratatui/latest/ratatui/fn.init.html
+    pub fn new(backend: B) -> Result<Self, B::Error> {
+        Self::with_options(
+            backend,
+            TerminalOptions {
+                viewport: Viewport::Fullscreen,
+            },
+        )
+    }
+
+    /// Creates a new [`Terminal`] with the given [`Backend`] and [`TerminalOptions`].
+    ///
+    /// The viewport determines what area is exposed to widgets via [`Frame::area`]. See
+    /// [`Viewport`] for an overview of the available modes.
+    ///
+    /// [`Frame::area`]: crate::terminal::Frame::area
+    ///
+    /// After creating a terminal, call [`Terminal::draw`] (or [`Terminal::try_draw`]) in a loop to
+    /// render your UI.
+    ///
+    /// Resize behavior depends on the selected viewport:
+    ///
+    /// - [`Viewport::Fullscreen`] and [`Viewport::Inline`] are automatically resized during
+    ///   [`Terminal::draw`] (via [`Terminal::autoresize`]).
+    /// - [`Viewport::Fixed`] is not automatically resized; call [`Terminal::resize`] if the region
+    ///   should change.
+    ///
+    /// # Example
+    ///
+    /// ```rust,no_run
+    /// # #![allow(unexpected_cfgs)]
+    /// # #[cfg(feature = "crossterm")]
+    /// # {
+    /// use std::io::stdout;
+    ///
+    /// use ratatui::backend::CrosstermBackend;
+    /// use ratatui::layout::Rect;
+    /// use ratatui::{Terminal, TerminalOptions, Viewport};
+    ///
+    /// let backend = CrosstermBackend::new(stdout());
+    /// let viewport = Viewport::Fixed(Rect::new(0, 0, 10, 10));
+    /// let _terminal = Terminal::with_options(backend, TerminalOptions { viewport })?;
+    /// # }
+    /// # #[cfg(not(feature = "crossterm"))]
+    /// # {
+    /// # use ratatui_core::{
+    /// #     backend::TestBackend,
+    /// #     layout::Rect,
+    /// #     terminal::{Terminal, TerminalOptions, Viewport},
+    /// # };
+    /// # let backend = TestBackend::new(10, 10);
+    /// # let viewport = Viewport::Fixed(Rect::new(0, 0, 10, 10));
+    /// # let _terminal = Terminal::with_options(backend, TerminalOptions { viewport })?;
+    /// # }
+    /// # Ok::<(), Box<dyn std::error::Error>>(())
+    /// ```
+    ///
+    /// When the viewport is [`Viewport::Inline`], Ratatui anchors the viewport to the current
+    /// cursor row at initialization time (always starting at column 0). Ratatui may scroll the
+    /// terminal to make enough room for the requested height so the viewport stays fully visible.
+    pub fn with_options(mut backend: B, options: TerminalOptions) -> Result<Self, B::Error> {
+        let area = match options.viewport {
+            Viewport::Fullscreen | Viewport::Inline(_) => backend.size()?.into(),
+            Viewport::Fixed(area) => area,
+        };
+        let (viewport_area, cursor_pos) = match options.viewport {
+            Viewport::Fullscreen => (area, Position::ORIGIN),
+            Viewport::Inline(height) => {
+                compute_inline_size(&mut backend, height, area.as_size(), 0)?
+            }
+            Viewport::Fixed(area) => (area, area.as_position()),
+        };
+        Ok(Self {
+            backend,
+            buffers: [Buffer::empty(viewport_area), Buffer::empty(viewport_area)],
+            current: 0,
+            hidden_cursor: false,
+            viewport: options.viewport,
+            viewport_area,
+            last_known_area: area,
+            last_known_cursor_pos: cursor_pos,
+            frame_count: 0,
+        })
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use crate::backend::{Backend, TestBackend};
+    use crate::layout::{Position, Rect};
+    use crate::terminal::{Terminal, TerminalOptions, Viewport};
+
+    #[test]
+    fn new_fullscreen_initializes_state() {
+        let backend = TestBackend::new(10, 5);
+        let terminal = Terminal::new(backend).unwrap();
+
+        assert_eq!(terminal.viewport, Viewport::Fullscreen);
+        assert_eq!(terminal.viewport_area, Rect::new(0, 0, 10, 5));
+        assert_eq!(terminal.last_known_area, Rect::new(0, 0, 10, 5));
+        assert_eq!(terminal.last_known_cursor_pos, Position::ORIGIN);
+        assert_eq!(terminal.current, 0);
+        assert!(!terminal.hidden_cursor);
+        assert_eq!(terminal.frame_count, 0);
+        assert_eq!(terminal.buffers[0].area, terminal.viewport_area);
+        assert_eq!(terminal.buffers[1].area, terminal.viewport_area);
+    }
+
+    #[test]
+    fn with_options_fixed_uses_fixed_area() {
+        let backend = TestBackend::new(10, 10);
+        let viewport = Viewport::Fixed(Rect::new(2, 3, 5, 4));
+        let terminal = Terminal::with_options(
+            backend,
+            TerminalOptions {
+                viewport: viewport.clone(),
+            },
+        )
+        .unwrap();
+
+        assert_eq!(terminal.viewport, viewport);
+        assert_eq!(terminal.viewport_area, Rect::new(2, 3, 5, 4));
+        assert_eq!(terminal.last_known_area, Rect::new(2, 3, 5, 4));
+        assert_eq!(terminal.last_known_cursor_pos, Position { x: 2, y: 3 });
+        assert_eq!(terminal.buffers[0].area, terminal.viewport_area);
+        assert_eq!(terminal.buffers[1].area, terminal.viewport_area);
+    }
+
+    #[test]
+    fn with_options_inline_anchors_to_cursor_when_space_available() {
+        let mut backend = TestBackend::new(10, 10);
+        backend
+            .set_cursor_position(Position { x: 0, y: 3 })
+            .unwrap();
+
+        let terminal = Terminal::with_options(
+            backend,
+            TerminalOptions {
+                viewport: Viewport::Inline(4),
+            },
+        )
+        .unwrap();
+
+        assert_eq!(terminal.viewport_area, Rect::new(0, 3, 10, 4));
+        assert_eq!(terminal.last_known_cursor_pos, Position { x: 0, y: 3 });
+    }
+
+    #[test]
+    fn with_options_inline_shifts_up_when_near_bottom() {
+        let mut backend = TestBackend::new(10, 10);
+        backend
+            .set_cursor_position(Position { x: 0, y: 8 })
+            .unwrap();
+
+        let terminal = Terminal::with_options(
+            backend,
+            TerminalOptions {
+                viewport: Viewport::Inline(4),
+            },
+        )
+        .unwrap();
+
+        assert_eq!(terminal.viewport_area, Rect::new(0, 6, 10, 4));
+        assert_eq!(terminal.last_known_cursor_pos, Position { x: 0, y: 8 });
+    }
+
+    #[test]
+    fn with_options_inline_clamps_height_to_terminal() {
+        let mut backend = TestBackend::new(10, 3);
+        backend
+            .set_cursor_position(Position { x: 0, y: 0 })
+            .unwrap();
+
+        let terminal = Terminal::with_options(
+            backend,
+            TerminalOptions {
+                viewport: Viewport::Inline(10),
+            },
+        )
+        .unwrap();
+
+        assert_eq!(terminal.viewport_area, Rect::new(0, 0, 10, 3));
+    }
+}

ratatui-core/src/terminal/inline.rs

@@ -0,0 +1,927 @@
+use crate::backend::Backend;
+use crate::buffer::{Buffer, Cell};
+use crate::layout::{Position, Rect, Size};
+use crate::terminal::{Terminal, Viewport};
+
+impl<B: Backend> Terminal<B> {
+    /// Insert some content before the current inline viewport. This has no effect when the
+    /// viewport is not inline.
+    ///
+    /// This is intended for inline UIs that want to print output (e.g. logs or status messages)
+    /// above the UI without breaking it. See [`Viewport::Inline`] for how inline viewports are
+    /// anchored.
+    ///
+    /// The `draw_fn` closure will be called to draw into a writable `Buffer` that is `height`
+    /// lines tall. The content of that `Buffer` will then be inserted before the viewport.
+    ///
+    /// When Ratatui is built with the `scrolling-regions` feature, this can be done without
+    /// clearing and redrawing the viewport. Without `scrolling-regions`, Ratatui falls back to a
+    /// more portable approach and clears the viewport so the next [`Terminal::draw`] repaints it.
+    ///
+    /// If the viewport isn't yet at the bottom of the screen, inserted lines will push it towards
+    /// the bottom. Once the viewport is at the bottom of the screen, inserted lines will scroll
+    /// the area of the screen above the viewport upwards.
+    ///
+    /// Before:
+    /// ```text
+    /// +---------------------+
+    /// | pre-existing line 1 |
+    /// | pre-existing line 2 |
+    /// +---------------------+
+    /// |       viewport      |
+    /// +---------------------+
+    /// |                     |
+    /// |                     |
+    /// +---------------------+
+    /// ```
+    ///
+    /// After inserting 2 lines:
+    /// ```text
+    /// +---------------------+
+    /// | pre-existing line 1 |
+    /// | pre-existing line 2 |
+    /// |   inserted line 1   |
+    /// |   inserted line 2   |
+    /// +---------------------+
+    /// |       viewport      |
+    /// +---------------------+
+    /// +---------------------+
+    /// ```
+    ///
+    /// After inserting 2 more lines:
+    /// ```text
+    /// +---------------------+
+    /// | pre-existing line 2 |
+    /// |   inserted line 1   |
+    /// |   inserted line 2   |
+    /// |   inserted line 3   |
+    /// |   inserted line 4   |
+    /// +---------------------+
+    /// |       viewport      |
+    /// +---------------------+
+    /// ```
+    ///
+    /// If more lines are inserted than there is space on the screen, then the top lines will go
+    /// directly into the terminal's scrollback buffer. At the limit, if the viewport takes up the
+    /// whole screen, all lines will be inserted directly into the scrollback buffer.
+    ///
+    /// # Examples
+    ///
+    /// ## Insert a single line before the current viewport
+    ///
+    /// ```rust,no_run
+    /// # mod ratatui {
+    /// #     pub use ratatui_core::backend;
+    /// #     pub use ratatui_core::layout;
+    /// #     pub use ratatui_core::style;
+    /// #     pub use ratatui_core::terminal::{Terminal, TerminalOptions, Viewport};
+    /// #     pub use ratatui_core::text;
+    /// #     pub use ratatui_core::widgets;
+    /// # }
+    /// use ratatui::backend::{Backend, TestBackend};
+    /// use ratatui::layout::Position;
+    /// use ratatui::style::{Color, Style};
+    /// use ratatui::text::{Line, Span};
+    /// use ratatui::widgets::Widget;
+    /// use ratatui::{Terminal, TerminalOptions, Viewport};
+    ///
+    /// let mut backend = TestBackend::new(10, 10);
+    /// // Simulate existing output above the inline UI.
+    /// backend.set_cursor_position(Position::new(0, 3))?;
+    /// let mut terminal = Terminal::with_options(
+    ///     backend,
+    ///     TerminalOptions {
+    ///         viewport: Viewport::Inline(4),
+    ///     },
+    /// )?;
+    ///
+    /// terminal.insert_before(1, |buf| {
+    ///     Line::from(vec![
+    ///         Span::raw("This line will be added "),
+    ///         Span::styled("before", Style::default().fg(Color::Blue)),
+    ///         Span::raw(" the current viewport"),
+    ///     ])
+    ///     .render(buf.area, buf);
+    /// })?;
+    /// # Ok::<(), Box<dyn std::error::Error>>(())
+    /// ```
+    pub fn insert_before<F>(&mut self, height: u16, draw_fn: F) -> Result<(), B::Error>
+    where
+        F: FnOnce(&mut Buffer),
+    {
+        match self.viewport {
+            #[cfg(feature = "scrolling-regions")]
+            Viewport::Inline(_) => self.insert_before_scrolling_regions(height, draw_fn),
+            #[cfg(not(feature = "scrolling-regions"))]
+            Viewport::Inline(_) => self.insert_before_no_scrolling_regions(height, draw_fn),
+            _ => Ok(()),
+        }
+    }
+
+    /// Implement `Self::insert_before` using standard backend capabilities.
+    ///
+    /// This is the fallback implementation when the `scrolling-regions` feature is disabled. It
+    /// renders the inserted lines into a temporary [`Buffer`], then draws them directly to the
+    /// backend in chunks, scrolling the terminal as needed.
+    ///
+    /// See [`Terminal::insert_before`] for the public API contract.
+    #[cfg(not(feature = "scrolling-regions"))]
+    fn insert_before_no_scrolling_regions(
+        &mut self,
+        height: u16,
+        draw_fn: impl FnOnce(&mut Buffer),
+    ) -> Result<(), B::Error> {
+        let area = Rect {
+            x: 0,
+            y: 0,
+            width: self.viewport_area.width,
+            height,
+        };
+        let mut buffer = Buffer::empty(area);
+        draw_fn(&mut buffer);
+        let mut buffer = buffer.content.as_slice();
+
+        // Use i32 variables so we don't have worry about overflowed u16s when adding, or about
+        // negative results when subtracting.
+        let mut drawn_height: i32 = self.viewport_area.top().into();
+        let mut buffer_height: i32 = height.into();
+        let viewport_height: i32 = self.viewport_area.height.into();
+        let screen_height: i32 = self.last_known_area.height.into();
+
+        // The algorithm here is to loop, drawing large chunks of text (up to a screen-full at a
+        // time), until the remainder of the buffer plus the viewport fits on the screen. We choose
+        // this loop condition because it guarantees that we can write the remainder of the buffer
+        // with just one call to Self::draw_lines().
+        while buffer_height + viewport_height > screen_height {
+            // We will draw as much of the buffer as possible on this iteration in order to make
+            // forward progress. So we have:
+            //
+            //     to_draw = min(buffer_height, screen_height)
+            //
+            // We may need to scroll the screen up to make room to draw. We choose the minimal
+            // possible scroll amount so we don't end up with the viewport sitting in the middle of
+            // the screen when this function is done. The amount to scroll by is:
+            //
+            //     scroll_up = max(0, drawn_height + to_draw - screen_height)
+            //
+            // We want `scroll_up` to be enough so that, after drawing, we have used the whole
+            // screen (drawn_height - scroll_up + to_draw = screen_height). However, there might
+            // already be enough room on the screen to draw without scrolling (drawn_height +
+            // to_draw <= screen_height). In this case, we just don't scroll at all.
+            let to_draw = buffer_height.min(screen_height);
+            let scroll_up = 0.max(drawn_height + to_draw - screen_height);
+            self.scroll_up(scroll_up as u16)?;
+            buffer = self.draw_lines((drawn_height - scroll_up) as u16, to_draw as u16, buffer)?;
+            drawn_height += to_draw - scroll_up;
+            buffer_height -= to_draw;
+        }
+
+        // There is now enough room on the screen for the remaining buffer plus the viewport,
+        // though we may still need to scroll up some of the existing text first. It's possible
+        // that by this point we've drained the buffer, but we may still need to scroll up to make
+        // room for the viewport.
+        //
+        // We want to scroll up the exact amount that will leave us completely filling the screen.
+        // However, it's possible that the viewport didn't start on the bottom of the screen and
+        // the added lines weren't enough to push it all the way to the bottom. We deal with this
+        // case by just ensuring that our scroll amount is non-negative.
+        //
+        // We want:
+        //   screen_height = drawn_height - scroll_up + buffer_height + viewport_height
+        // Or, equivalently:
+        //   scroll_up = drawn_height + buffer_height + viewport_height - screen_height
+        let scroll_up = 0.max(drawn_height + buffer_height + viewport_height - screen_height);
+        self.scroll_up(scroll_up as u16)?;
+        self.draw_lines(
+            (drawn_height - scroll_up) as u16,
+            buffer_height as u16,
+            buffer,
+        )?;
+        drawn_height += buffer_height - scroll_up;
+
+        self.set_viewport_area(Rect {
+            y: drawn_height as u16,
+            ..self.viewport_area
+        });
+
+        // Clear the viewport off the screen. We didn't clear earlier for two reasons. First, it
+        // wasn't necessary because the buffer we drew out of isn't sparse, so it overwrote
+        // whatever was on the screen. Second, there is a weird bug with tmux where a full screen
+        // clear plus immediate scrolling causes some garbage to go into the scrollback.
+        self.clear()?;
+
+        Ok(())
+    }
+
+    /// Implement `Self::insert_before` using scrolling regions.
+    ///
+    /// If a terminal supports scrolling regions, it means that we can define a subset of rows of
+    /// the screen, and then tell the terminal to scroll up or down just within that region. The
+    /// rows outside of the region are not affected.
+    ///
+    /// This function utilizes this feature to avoid having to redraw the viewport. This is done
+    /// either by splitting the screen at the top of the viewport, and then creating a gap by
+    /// either scrolling the viewport down, or scrolling the area above it up. The lines to insert
+    /// are then drawn into the gap created.
+    #[cfg(feature = "scrolling-regions")]
+    fn insert_before_scrolling_regions(
+        &mut self,
+        mut height: u16,
+        draw_fn: impl FnOnce(&mut Buffer),
+    ) -> Result<(), B::Error> {
+        let area = Rect {
+            x: 0,
+            y: 0,
+            width: self.viewport_area.width,
+            height,
+        };
+        let mut buffer = Buffer::empty(area);
+        draw_fn(&mut buffer);
+        let mut buffer = buffer.content.as_slice();
+
+        // Handle the special case where the viewport takes up the whole screen.
+        if self.viewport_area.height == self.last_known_area.height {
+            // "Borrow" the top line of the viewport. Draw over it, then immediately scroll it into
+            // scrollback. Do this repeatedly until the whole buffer has been put into scrollback.
+            let mut first = true;
+            while !buffer.is_empty() {
+                buffer = if first {
+                    self.draw_lines(0, 1, buffer)?
+                } else {
+                    self.draw_lines_over_cleared(0, 1, buffer)?
+                };
+                first = false;
+                self.backend.scroll_region_up(0..1, 1)?;
+            }
+
+            // Redraw the top line of the viewport.
+            let width = self.viewport_area.width as usize;
+            let top_line = self.buffers[1 - self.current].content[0..width].to_vec();
+            self.draw_lines_over_cleared(0, 1, &top_line)?;
+            return Ok(());
+        }
+
+        // Handle the case where the viewport isn't yet at the bottom of the screen.
+        {
+            let viewport_top = self.viewport_area.top();
+            let viewport_bottom = self.viewport_area.bottom();
+            let screen_bottom = self.last_known_area.bottom();
+            if viewport_bottom < screen_bottom {
+                let to_draw = height.min(screen_bottom - viewport_bottom);
+                self.backend
+                    .scroll_region_down(viewport_top..viewport_bottom + to_draw, to_draw)?;
+                buffer = self.draw_lines_over_cleared(viewport_top, to_draw, buffer)?;
+                self.set_viewport_area(Rect {
+                    y: viewport_top + to_draw,
+                    ..self.viewport_area
+                });
+                height -= to_draw;
+            }
+        }
+
+        let viewport_top = self.viewport_area.top();
+        while height > 0 {
+            let to_draw = height.min(viewport_top);
+            self.backend.scroll_region_up(0..viewport_top, to_draw)?;
+            buffer = self.draw_lines_over_cleared(viewport_top - to_draw, to_draw, buffer)?;
+            height -= to_draw;
+        }
+
+        Ok(())
+    }
+
+    /// Draw lines at the given vertical offset. The slice of cells must contain enough cells
+    /// for the requested lines. A slice of the unused cells are returned.
+    ///
+    /// This is a small internal helper used by [`Terminal::insert_before`]. It writes cells
+    /// directly to the backend in terminal coordinates (not viewport coordinates).
+    fn draw_lines<'a>(
+        &mut self,
+        y_offset: u16,
+        lines_to_draw: u16,
+        cells: &'a [Cell],
+    ) -> Result<&'a [Cell], B::Error> {
+        let width: usize = self.last_known_area.width.into();
+        let (to_draw, remainder) = cells.split_at(width * lines_to_draw as usize);
+        if lines_to_draw > 0 {
+            let iter = to_draw
+                .iter()
+                .enumerate()
+                .map(|(i, c)| ((i % width) as u16, y_offset + (i / width) as u16, c));
+            self.backend.draw(iter)?;
+            self.backend.flush()?;
+        }
+        Ok(remainder)
+    }
+
+    /// Draw lines at the given vertical offset, assuming that the lines they are replacing on the
+    /// screen are cleared. The slice of cells must contain enough cells for the requested lines. A
+    /// slice of the unused cells are returned.
+    ///
+    /// This is used by the `scrolling-regions` implementation of [`Terminal::insert_before`] to
+    /// avoid relying on a full-screen clear while updating only part of the terminal.
+    #[cfg(feature = "scrolling-regions")]
+    fn draw_lines_over_cleared<'a>(
+        &mut self,
+        y_offset: u16,
+        lines_to_draw: u16,
+        cells: &'a [Cell],
+    ) -> Result<&'a [Cell], B::Error> {
+        let width: usize = self.last_known_area.width.into();
+        let (to_draw, remainder) = cells.split_at(width * lines_to_draw as usize);
+        if lines_to_draw > 0 {
+            let area = Rect::new(0, y_offset, width as u16, y_offset + lines_to_draw);
+            let old = Buffer::empty(area);
+            let new = Buffer {
+                area,
+                content: to_draw.to_vec(),
+            };
+            self.backend.draw(old.diff(&new).into_iter())?;
+            self.backend.flush()?;
+        }
+        Ok(remainder)
+    }
+
+    /// Scroll the whole screen up by the given number of lines.
+    ///
+    /// This is used by [`Terminal::insert_before`] when the `scrolling-regions` feature is
+    /// disabled.
+    /// It scrolls by moving the cursor to the last row and calling [`Backend::append_lines`].
+    #[cfg(not(feature = "scrolling-regions"))]
+    fn scroll_up(&mut self, lines_to_scroll: u16) -> Result<(), B::Error> {
+        if lines_to_scroll > 0 {
+            self.set_cursor_position(Position::new(
+                0,
+                self.last_known_area.height.saturating_sub(1),
+            ))?;
+            self.backend.append_lines(lines_to_scroll)?;
+        }
+        Ok(())
+    }
+}
+
+/// Compute the on-screen area for an inline viewport.
+///
+/// This helper is used by [`Terminal::with_options`] (initialization) and [`Terminal::resize`]
+/// (after a terminal resize) to translate `Viewport::Inline(height)` into a concrete [`Rect`].
+///
+/// This returns the computed viewport area and the cursor position observed at the start of the
+/// call.
+///
+/// Inline viewports always start at column 0, span the full terminal width, and are anchored to the
+/// backend cursor row at the time of the call. The requested height is clamped to the current
+/// terminal height.
+///
+/// Ratatui reserves vertical space for the requested height by calling [`Backend::append_lines`].
+/// If the cursor is close enough to the bottom that appending would run past the last row,
+/// terminals scroll; in that case we shift the computed `y` upward by the number of rows scrolled
+/// so the viewport remains fully visible.
+///
+/// `offset_in_previous_viewport` is used by [`Terminal::resize`] to keep the cursor at the same
+/// relative row within the viewport across resizes.
+///
+/// Related viewport code lives in:
+///
+/// - [`Terminal::with_options`] (selects the viewport and computes the initial area)
+/// - [`Terminal::autoresize`] (detects backend size changes during [`Terminal::draw`])
+/// - [`Terminal::resize`] (recomputes the viewport and clears before the next draw)
+pub(crate) fn compute_inline_size<B: Backend>(
+    backend: &mut B,
+    height: u16,
+    size: Size,
+    offset_in_previous_viewport: u16,
+) -> Result<(Rect, Position), B::Error> {
+    let pos = backend.get_cursor_position()?;
+    let mut row = pos.y;
+
+    let max_height = size.height.min(height);
+
+    let lines_after_cursor = height
+        .saturating_sub(offset_in_previous_viewport)
+        .saturating_sub(1);
+
+    backend.append_lines(lines_after_cursor)?;
+
+    let available_lines = size.height.saturating_sub(row).saturating_sub(1);
+    let missing_lines = lines_after_cursor.saturating_sub(available_lines);
+    if missing_lines > 0 {
+        row = row.saturating_sub(missing_lines);
+    }
+    row = row.saturating_sub(offset_in_previous_viewport);
+
+    Ok((
+        Rect {
+            x: 0,
+            y: row,
+            width: size.width,
+            height: max_height,
+        },
+        pos,
+    ))
+}
+
+#[cfg(test)]
+mod tests {
+    use crate::backend::{Backend, TestBackend};
+    use crate::layout::{Position, Rect, Size};
+    use crate::style::Style;
+    use crate::terminal::inline::compute_inline_size;
+    use crate::terminal::{Terminal, TerminalOptions, Viewport};
+
+    #[test]
+    fn compute_inline_size_uses_cursor_offset_when_space_available() {
+        // Diagram (terminal height = 10, requested viewport height = 4):
+        //
+        // Cursor at y=6, previous cursor offset within viewport = 1.
+        //
+        // Before (conceptually):
+        //   0
+        //   1
+        //   2
+        //   3
+        //   4
+        //   5  <- viewport top (expected)
+        //   6  <- cursor row (observed_pos.y)
+        //   7
+        //   8
+        //   9
+        //
+        // After: viewport top y = 5 (6 - 1), height = 4 => rows 5..9 (exclusive).
+        let mut backend = TestBackend::new(10, 10);
+        backend
+            .set_cursor_position(Position { x: 0, y: 6 })
+            .unwrap();
+
+        let (area, observed_pos) =
+            compute_inline_size(&mut backend, 4, Size::new(10, 10), 1).unwrap();
+
+        assert_eq!(observed_pos, Position { x: 0, y: 6 });
+        assert_eq!(area, Rect::new(0, 5, 10, 4));
+    }
+
+    #[test]
+    fn compute_inline_size_saturates_when_offset_exceeds_cursor_row() {
+        // Diagram (terminal height = 10, requested viewport height = 4):
+        //
+        // Cursor at y=0, previous cursor offset within viewport = 5 (nonsensical but possible if
+        // callers pass a stale/oversized offset).
+        //
+        // We saturate so the computed viewport top cannot go negative:
+        //   top = cursor_y.saturating_sub(offset) = 0.saturating_sub(5) = 0
+        //
+        // Expected viewport area:
+        //   y=0..4 (fully pinned to the top)
+        let mut backend = TestBackend::new(10, 10);
+        backend
+            .set_cursor_position(Position { x: 0, y: 0 })
+            .unwrap();
+
+        let (area, _observed_pos) =
+            compute_inline_size(&mut backend, 4, Size::new(10, 10), 5).unwrap();
+
+        assert_eq!(area, Rect::new(0, 0, 10, 4));
+    }
+
+    #[cfg(not(feature = "scrolling-regions"))]
+    mod no_scrolling_regions {
+        use super::*;
+
+        #[test]
+        fn insert_before_is_noop_for_non_inline_viewports() {
+            // Diagram:
+            //
+            // Viewport is fullscreen (not inline), so insert_before() is a no-op.
+            //
+            // Screen before:
+            //   x..
+            //   ...
+            //
+            // Screen after:
+            //   x..
+            //   ...
+            let mut terminal = Terminal::new(TestBackend::new(3, 2)).unwrap();
+            {
+                let frame = terminal.get_frame();
+                frame.buffer[(0, 0)].set_symbol("x");
+            }
+            terminal.flush().unwrap();
+
+            let viewport_area = terminal.viewport_area;
+            terminal
+                .insert_before(1, |buf| {
+                    buf.set_string(0, 0, "zzz", Style::default());
+                })
+                .unwrap();
+
+            assert_eq!(terminal.viewport_area, viewport_area);
+            terminal.backend().assert_buffer_lines(["x  ", "   "]);
+        }
+
+        #[test]
+        fn insert_before_pushes_viewport_down_when_space_available() {
+            // Diagram (screen height = 10, viewport height = 4, cursor row = 3):
+            //
+            // Before:
+            //   0: 0000000000
+            //   1: 1111111111
+            //   2: 2222222222
+            //   3: [viewport top] 3333333333
+            //   4:               4444444444
+            //   5:               5555555555
+            //   6:               6666666666
+            //   7: 7777777777
+            //   8: 8888888888
+            //   9: 9999999999
+            //
+            // After inserting 1 line above an inline viewport (no scrolling regions):
+            // - A line is drawn at the old viewport top (y=3)
+            // - The viewport moves down by 1 row (new top y=4)
+            // - The viewport is cleared so it will be redrawn on the next draw()
+            let mut backend = TestBackend::with_lines([
+                "0000000000",
+                "1111111111",
+                "2222222222",
+                "3333333333",
+                "4444444444",
+                "5555555555",
+                "6666666666",
+                "7777777777",
+                "8888888888",
+                "9999999999",
+            ]);
+            backend
+                .set_cursor_position(Position { x: 0, y: 3 })
+                .unwrap();
+            let mut terminal = Terminal::with_options(
+                backend,
+                TerminalOptions {
+                    viewport: Viewport::Inline(4),
+                },
+            )
+            .unwrap();
+
+            terminal
+                .insert_before(1, |buf| {
+                    buf.set_string(0, 0, "INSERTLINE", Style::default());
+                })
+                .unwrap();
+
+            assert_eq!(terminal.viewport_area, Rect::new(0, 4, 10, 4));
+            terminal.backend().assert_buffer_lines([
+                "0000000000",
+                "1111111111",
+                "2222222222",
+                "INSERTLINE",
+                "          ",
+                "          ",
+                "          ",
+                "          ",
+                "          ",
+                "          ",
+            ]);
+        }
+
+        #[test]
+        fn insert_before_scrolls_when_viewport_is_at_bottom() {
+            // Diagram (screen height = 10, viewport height = 4, cursor row = 6):
+            //
+            // Before:
+            //   0: 0000000000
+            //   1: 1111111111
+            //   2: 2222222222
+            //   3: 3333333333
+            //   4: 4444444444
+            //   5: 5555555555
+            //   6: [viewport top] 6666666666
+            //   7:               7777777777
+            //   8:               8888888888
+            //   9:               9999999999
+            //
+            // After inserting 2 lines:
+            // - The area above the viewport scrolls up to make room
+            // - Inserted lines appear immediately above the viewport
+            // - The viewport is cleared so it will be redrawn on the next draw()
+            let mut backend = TestBackend::with_lines([
+                "0000000000",
+                "1111111111",
+                "2222222222",
+                "3333333333",
+                "4444444444",
+                "5555555555",
+                "6666666666",
+                "7777777777",
+                "8888888888",
+                "9999999999",
+            ]);
+            backend
+                .set_cursor_position(Position { x: 0, y: 6 })
+                .unwrap();
+            let mut terminal = Terminal::with_options(
+                backend,
+                TerminalOptions {
+                    viewport: Viewport::Inline(4),
+                },
+            )
+            .unwrap();
+
+            terminal
+                .insert_before(2, |buf| {
+                    buf.set_string(0, 0, "INSERTED1", Style::default());
+                    buf.set_string(0, 1, "INSERTED2", Style::default());
+                })
+                .unwrap();
+
+            assert_eq!(terminal.viewport_area, Rect::new(0, 6, 10, 4));
+            terminal.backend().assert_buffer_lines([
+                "2222222222",
+                "3333333333",
+                "4444444444",
+                "5555555555",
+                "INSERTED1 ",
+                "INSERTED2 ",
+                "          ",
+                "          ",
+                "          ",
+                "          ",
+            ]);
+        }
+
+        #[test]
+        fn insert_before_then_draw_repaints_cleared_viewport() {
+            // Diagram (screen height = 10, viewport height = 4, cursor row = 6):
+            //
+            // 1) Draw a frame into the inline viewport at the bottom:
+            //   6..9: AAAAAAAAAA
+            //
+            // 2) Insert 2 lines above the viewport:
+            //   - Inserts appear at rows 4..5
+            //   - Viewport is cleared (so it is blank on-screen until the next draw)
+            //
+            // 3) Draw again:
+            //   6..9: BBBBBBBBBB
+            //
+            // Expected final screen:
+            //   4: INSERTED00
+            //   5: INSERTED01
+            //   6..9: BBBBBBBBBB
+            let mut backend = TestBackend::new(10, 10);
+            backend
+                .set_cursor_position(Position { x: 0, y: 6 })
+                .unwrap();
+            let mut terminal = Terminal::with_options(
+                backend,
+                TerminalOptions {
+                    viewport: Viewport::Inline(4),
+                },
+            )
+            .unwrap();
+
+            terminal
+                .draw(|frame| {
+                    let area = frame.area();
+                    for y in area.top()..area.bottom() {
+                        frame
+                            .buffer
+                            .set_string(area.x, y, "AAAAAAAAAA", Style::default());
+                    }
+                })
+                .unwrap();
+
+            terminal
+                .insert_before(2, |buf| {
+                    buf.set_string(0, 0, "INSERTED00", Style::default());
+                    buf.set_string(0, 1, "INSERTED01", Style::default());
+                })
+                .unwrap();
+
+            terminal
+                .draw(|frame| {
+                    let area = frame.area();
+                    for y in area.top()..area.bottom() {
+                        frame
+                            .buffer
+                            .set_string(area.x, y, "BBBBBBBBBB", Style::default());
+                    }
+                })
+                .unwrap();
+
+            terminal.backend().assert_buffer_lines([
+                "          ",
+                "          ",
+                "          ",
+                "          ",
+                "INSERTED00",
+                "INSERTED01",
+                "BBBBBBBBBB",
+                "BBBBBBBBBB",
+                "BBBBBBBBBB",
+                "BBBBBBBBBB",
+            ]);
+        }
+    }
+
+    #[cfg(feature = "scrolling-regions")]
+    mod scrolling_regions {
+        use super::*;
+
+        #[test]
+        fn insert_before_moves_viewport_down_without_clearing() {
+            // Diagram (screen height = 10, viewport height = 4, cursor row = 3):
+            //
+            // With scrolling regions enabled, we can create a gap and draw the inserted line
+            // without clearing the viewport content.
+            //
+            // Before:
+            //   2: 2222222222
+            //   3: [viewport top] 3333333333
+            //   4:               4444444444
+            //
+            // After:
+            //   3: INSERTLINE
+            //   4: 3333333333  (viewport content preserved)
+            let mut backend = TestBackend::with_lines([
+                "0000000000",
+                "1111111111",
+                "2222222222",
+                "3333333333",
+                "4444444444",
+                "5555555555",
+                "6666666666",
+                "7777777777",
+                "8888888888",
+                "9999999999",
+            ]);
+            backend
+                .set_cursor_position(Position { x: 0, y: 3 })
+                .unwrap();
+            let mut terminal = Terminal::with_options(
+                backend,
+                TerminalOptions {
+                    viewport: Viewport::Inline(4),
+                },
+            )
+            .unwrap();
+
+            terminal
+                .insert_before(1, |buf| {
+                    buf.set_string(0, 0, "INSERTLINE", Style::default());
+                })
+                .unwrap();
+
+            assert_eq!(terminal.viewport_area, Rect::new(0, 4, 10, 4));
+            terminal.backend().assert_buffer_lines([
+                "0000000000",
+                "1111111111",
+                "2222222222",
+                "INSERTLINE",
+                "3333333333",
+                "4444444444",
+                "5555555555",
+                "6666666666",
+                "8888888888",
+                "9999999999",
+            ]);
+        }
+
+        #[test]
+        fn insert_before_when_viewport_is_at_bottom_preserves_viewport() {
+            // Diagram (screen height = 10, viewport height = 4, viewport top = 6):
+            //
+            // With scrolling regions enabled and the viewport already at the bottom:
+            // - The region above the viewport (rows 0..6) scrolls up to make room.
+            // - Inserted lines are drawn into the cleared space immediately above the viewport.
+            // - The viewport itself is not cleared and stays on-screen.
+            //
+            // Before (after drawing V into the viewport):
+            //   0: 0000000000
+            //   1: 1111111111
+            //   2: 2222222222
+            //   3: 3333333333
+            //   4: 4444444444
+            //   5: 5555555555
+            //   6..9: VVVVVVVVVV
+            //
+            // After inserting 2 lines:
+            //   0..3: previous 2..5
+            //   4: AAAAAAAAAA
+            //   5: BBBBBBBBBB
+            //   6..9: VVVVVVVVVV
+            //
+            // The scrolled-off lines are appended to scrollback (previous 0 and 1).
+            let mut backend = TestBackend::with_lines([
+                "0000000000",
+                "1111111111",
+                "2222222222",
+                "3333333333",
+                "4444444444",
+                "5555555555",
+                "6666666666",
+                "7777777777",
+                "8888888888",
+                "9999999999",
+            ]);
+            backend
+                .set_cursor_position(Position { x: 0, y: 6 })
+                .unwrap();
+            let mut terminal = Terminal::with_options(
+                backend,
+                TerminalOptions {
+                    viewport: Viewport::Inline(4),
+                },
+            )
+            .unwrap();
+
+            terminal
+                .draw(|frame| {
+                    let area = frame.area();
+                    for y in area.top()..area.bottom() {
+                        frame
+                            .buffer
+                            .set_string(area.x, y, "VVVVVVVVVV", Style::default());
+                    }
+                })
+                .unwrap();
+
+            terminal
+                .insert_before(2, |buf| {
+                    buf.set_string(0, 0, "AAAAAAAAAA", Style::default());
+                    buf.set_string(0, 1, "BBBBBBBBBB", Style::default());
+                })
+                .unwrap();
+
+            terminal.backend().assert_buffer_lines([
+                "2222222222",
+                "3333333333",
+                "4444444444",
+                "5555555555",
+                "AAAAAAAAAA",
+                "BBBBBBBBBB",
+                "VVVVVVVVVV",
+                "VVVVVVVVVV",
+                "VVVVVVVVVV",
+                "VVVVVVVVVV",
+            ]);
+            terminal
+                .backend()
+                .assert_scrollback_lines(["0000000000", "1111111111"]);
+        }
+
+        #[test]
+        fn insert_before_when_viewport_is_fullscreen_appends_to_scrollback() {
+            // Diagram (screen height = 4, viewport height = 4):
+            //
+            // When the viewport takes the whole screen, there is no visible "area above" it.
+            // The scrolling-regions implementation handles this by repeatedly:
+            // - drawing one line over the top row
+            // - immediately scrolling that row into scrollback
+            //
+            // The viewport content stays on-screen; inserted lines end up in scrollback.
+            let mut backend = TestBackend::new(10, 4);
+            backend
+                .set_cursor_position(Position { x: 0, y: 0 })
+                .unwrap();
+            let mut terminal = Terminal::with_options(
+                backend,
+                TerminalOptions {
+                    viewport: Viewport::Inline(4),
+                },
+            )
+            .unwrap();
+
+            terminal
+                .draw(|frame| {
+                    let area = frame.area();
+                    frame
+                        .buffer
+                        .set_string(area.x, area.y, "VIEWLINE00", Style::default());
+                    frame
+                        .buffer
+                        .set_string(area.x, area.y + 1, "VIEWLINE01", Style::default());
+                    frame
+                        .buffer
+                        .set_string(area.x, area.y + 2, "VIEWLINE02", Style::default());
+                    frame
+                        .buffer
+                        .set_string(area.x, area.y + 3, "VIEWLINE03", Style::default());
+                })
+                .unwrap();
+
+            terminal
+                .insert_before(2, |buf| {
+                    buf.set_string(0, 0, "INSERTED00", Style::default());
+                    buf.set_string(0, 1, "INSERTED01", Style::default());
+                })
+                .unwrap();
+
+            terminal.backend().assert_buffer_lines([
+                "VIEWLINE00",
+                "VIEWLINE01",
+                "VIEWLINE02",
+                "VIEWLINE03",
+            ]);
+            terminal
+                .backend()
+                .assert_scrollback_lines(["INSERTED00", "INSERTED01"]);
+        }
+    }
+}

ratatui-core/src/terminal/render.rs

@@ -0,0 +1,737 @@
+use crate::backend::Backend;
+use crate::terminal::{CompletedFrame, Frame, Terminal};
+
+impl<B: Backend> Terminal<B> {
+    /// Draws a single frame to the terminal.
+    ///
+    /// Returns a [`CompletedFrame`] if successful, otherwise a backend error (`B::Error`).
+    ///
+    /// If the render callback passed to this method can fail, use [`try_draw`] instead.
+    ///
+    /// Applications should call `draw` or [`try_draw`] in a loop to continuously render the
+    /// terminal. These methods are the main entry points for drawing to the terminal.
+    ///
+    /// [`try_draw`]: Terminal::try_draw
+    ///
+    /// The [`Frame`] passed to the render callback represents the currently configured
+    /// [`Viewport`] (see [`Frame::area`] and [`Terminal::with_options`]).
+    ///
+    /// Build layout relative to the [`Rect`] returned by [`Frame::area`] rather than assuming the
+    /// origin is `(0, 0)`, so the same rendering code works for fixed and inline viewports.
+    ///
+    /// [`Frame::area`]: crate::terminal::Frame::area
+    /// [`Rect`]: crate::layout::Rect
+    /// [`Viewport`]: crate::terminal::Viewport
+    ///
+    /// This method will:
+    ///
+    /// - call [`Terminal::autoresize`] if necessary
+    /// - call the render callback, passing it a [`Frame`] reference to render to
+    /// - call [`Terminal::flush`] to write changes to the backend
+    /// - show/hide the cursor based on [`Frame::set_cursor_position`]
+    /// - call [`Terminal::swap_buffers`] to prepare for the next render pass
+    /// - call [`Backend::flush`]
+    /// - return a [`CompletedFrame`] with the current buffer and the area used for rendering
+    ///
+    /// The [`CompletedFrame`] returned by this method can be useful for debugging or testing
+    /// purposes, but it is often not used in regular applications.
+    ///
+    /// The render callback should fully render the entire frame when called, including areas that
+    /// are unchanged from the previous frame. This is because each frame is compared to the
+    /// previous frame to determine what has changed, and only the changes are written to the
+    /// terminal. If the render callback does not fully render the frame, the terminal will not be
+    /// in a consistent state.
+    ///
+    /// # Examples
+    ///
+    /// ```rust,no_run
+    /// # mod ratatui {
+    /// #     pub use ratatui_core::backend;
+    /// #     pub use ratatui_core::layout;
+    /// #     pub use ratatui_core::terminal::{Frame, Terminal};
+    /// # }
+    /// use ratatui::backend::TestBackend;
+    /// use ratatui::layout::Position;
+    /// use ratatui::{Frame, Terminal};
+    ///
+    /// let backend = TestBackend::new(10, 10);
+    /// let mut terminal = Terminal::new(backend)?;
+    ///
+    /// // With a closure.
+    /// terminal.draw(|frame| {
+    ///     let area = frame.area();
+    ///     frame.render_widget("Hello World!", area);
+    ///     frame.set_cursor_position(Position { x: 0, y: 0 });
+    /// })?;
+    ///
+    /// // Or with a function.
+    /// terminal.draw(render)?;
+    ///
+    /// fn render(frame: &mut Frame<'_>) {
+    ///     frame.render_widget("Hello World!", frame.area());
+    /// }
+    /// # Ok::<(), Box<dyn std::error::Error>>(())
+    /// ```
+    ///
+    /// [`Backend::flush`]: crate::backend::Backend::flush
+    pub fn draw<F>(&mut self, render_callback: F) -> Result<CompletedFrame<'_>, B::Error>
+    where
+        F: FnOnce(&mut Frame),
+    {
+        self.try_draw(|frame| {
+            render_callback(frame);
+            Ok::<(), B::Error>(())
+        })
+    }
+
+    /// Tries to draw a single frame to the terminal.
+    ///
+    /// Returns [`Result::Ok`] containing a [`CompletedFrame`] if successful, otherwise
+    /// [`Result::Err`] containing the backend error (`B::Error`) that caused the failure.
+    ///
+    /// This is the equivalent of [`Terminal::draw`] but the render callback is a function or
+    /// closure that returns a `Result` instead of nothing.
+    ///
+    /// Applications should call `try_draw` or [`draw`] in a loop to continuously render the
+    /// terminal. These methods are the main entry points for drawing to the terminal.
+    ///
+    /// [`draw`]: Terminal::draw
+    ///
+    /// The [`Frame`] passed to the render callback represents the currently configured
+    /// [`Viewport`] (see [`Frame::area`] and [`Terminal::with_options`]).
+    ///
+    /// Build layout relative to the [`Rect`] returned by [`Frame::area`] rather than assuming the
+    /// origin is `(0, 0)`, so the same rendering code works for fixed and inline viewports.
+    ///
+    /// [`Frame::area`]: crate::terminal::Frame::area
+    /// [`Rect`]: crate::layout::Rect
+    /// [`Viewport`]: crate::terminal::Viewport
+    ///
+    /// This method will:
+    ///
+    /// - call [`Terminal::autoresize`] if necessary
+    /// - call the render callback, passing it a [`Frame`] reference to render to
+    /// - call [`Terminal::flush`] to write changes to the backend
+    /// - show/hide the cursor based on [`Frame::set_cursor_position`]
+    /// - call [`Terminal::swap_buffers`] to prepare for the next render pass
+    /// - call [`Backend::flush`]
+    /// - return a [`CompletedFrame`] with the current buffer and the area used for rendering
+    ///
+    /// The render callback passed to `try_draw` can return any [`Result`] with an error type that
+    /// can be converted into `B::Error` using the [`Into`] trait. This makes it possible to use the
+    /// `?` operator to propagate errors that occur during rendering. If the render callback returns
+    /// an error, the error will be returned from `try_draw` and the terminal will not be updated.
+    ///
+    /// The [`CompletedFrame`] returned by this method can be useful for debugging or testing
+    /// purposes, but it is often not used in regular applications.
+    ///
+    /// The render callback should fully render the entire frame when called, including areas that
+    /// are unchanged from the previous frame. This is because each frame is compared to the
+    /// previous frame to determine what has changed, and only the changes are written to the
+    /// terminal. If the render function does not fully render the frame, the terminal will not be
+    /// in a consistent state.
+    ///
+    /// # Examples
+    ///
+    /// ```rust,no_run
+    /// # #![allow(unexpected_cfgs)]
+    /// # #[cfg(feature = "crossterm")]
+    /// # {
+    /// use std::io;
+    ///
+    /// use ratatui::backend::CrosstermBackend;
+    /// use ratatui::layout::Position;
+    /// use ratatui::{Frame, Terminal};
+    ///
+    /// let backend = CrosstermBackend::new(std::io::stdout());
+    /// let mut terminal = Terminal::new(backend)?;
+    ///
+    /// // With a closure that returns `Result`.
+    /// terminal.try_draw(|frame| -> io::Result<()> {
+    ///     let _value: u8 = "42".parse().map_err(io::Error::other)?;
+    ///     let area = frame.area();
+    ///     frame.render_widget("Hello World!", area);
+    ///     frame.set_cursor_position(Position { x: 0, y: 0 });
+    ///     Ok(())
+    /// })?;
+    ///
+    /// // Or with a function.
+    /// terminal.try_draw(render)?;
+    ///
+    /// fn render(frame: &mut Frame<'_>) -> io::Result<()> {
+    ///     frame.render_widget("Hello World!", frame.area());
+    ///     Ok(())
+    /// }
+    /// # }
+    /// # #[cfg(not(feature = "crossterm"))]
+    /// # {
+    /// # use ratatui_core::{backend::TestBackend, terminal::Terminal};
+    /// # let backend = TestBackend::new(10, 10);
+    /// # let mut terminal = Terminal::new(backend)?;
+    /// # terminal
+    /// #     .try_draw(|frame| {
+    /// #         frame.render_widget("Hello World!", frame.area());
+    /// #         Ok::<(), core::convert::Infallible>(())
+    /// #     })
+    /// #     ?;
+    /// # }
+    /// # Ok::<(), Box<dyn std::error::Error>>(())
+    /// ```
+    ///
+    /// [`Backend::flush`]: crate::backend::Backend::flush
+    pub fn try_draw<F, E>(&mut self, render_callback: F) -> Result<CompletedFrame<'_>, B::Error>
+    where
+        F: FnOnce(&mut Frame) -> Result<(), E>,
+        E: Into<B::Error>,
+    {
+        // Autoresize - otherwise we get glitches if shrinking or potential desync between widgets
+        // and the terminal (if growing), which may OOB.
+        self.autoresize()?;
+
+        let mut frame = self.get_frame();
+
+        render_callback(&mut frame).map_err(Into::into)?;
+
+        // We can't change the cursor position right away because we have to flush the frame to
+        // stdout first. But we also can't keep the frame around, since it holds a &mut to
+        // Buffer. Thus, we're taking the important data out of the Frame and dropping it.
+        let cursor_position = frame.cursor_position;
+
+        // Apply the buffer diff to the backend (this is the terminal's "flush" step, distinct
+        // from `Backend::flush` below which flushes the backend's output).
+        self.flush()?;
+
+        match cursor_position {
+            None => self.hide_cursor()?,
+            Some(position) => {
+                self.show_cursor()?;
+                self.set_cursor_position(position)?;
+            }
+        }
+
+        self.swap_buffers();
+
+        // Flush any buffered backend output.
+        self.backend.flush()?;
+
+        let completed_frame = CompletedFrame {
+            buffer: &self.buffers[1 - self.current],
+            area: self.last_known_area,
+            count: self.frame_count,
+        };
+
+        // increment frame count before returning from draw
+        self.frame_count = self.frame_count.wrapping_add(1);
+
+        Ok(completed_frame)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use core::fmt;
+
+    use crate::backend::{Backend, ClearType, TestBackend, WindowSize};
+    use crate::buffer::{Buffer, Cell};
+    use crate::layout::{Position, Rect};
+    use crate::terminal::{Terminal, TerminalOptions, Viewport};
+
+    #[derive(Debug, Clone, Eq, PartialEq)]
+    struct TestError(&'static str);
+
+    impl fmt::Display for TestError {
+        fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+            write!(f, "{}", self.0)
+        }
+    }
+
+    impl core::error::Error for TestError {}
+
+    /// A thin wrapper around [`TestBackend`] with a fallible error type.
+    ///
+    /// [`TestBackend`] uses [`core::convert::Infallible`] as its associated `Backend::Error`, which
+    /// is ideal for most tests but makes it impossible to write a `try_draw` callback that returns
+    /// an error (because `E: Into<B::Error>` would require converting a real error into
+    /// `Infallible`). This wrapper keeps the same observable backend behavior (buffer + cursor)
+    /// while allowing tests to exercise `Terminal::try_draw`'s error path.
+    #[derive(Debug, Clone, Eq, PartialEq)]
+    struct FallibleTestBackend {
+        inner: TestBackend,
+    }
+
+    impl FallibleTestBackend {
+        fn new(inner: TestBackend) -> Self {
+            Self { inner }
+        }
+    }
+
+    impl Backend for FallibleTestBackend {
+        type Error = TestError;
+
+        fn draw<'a, I>(&mut self, content: I) -> Result<(), Self::Error>
+        where
+            I: Iterator<Item = (u16, u16, &'a crate::buffer::Cell)>,
+        {
+            self.inner.draw(content).map_err(|err| match err {})
+        }
+
+        fn append_lines(&mut self, n: u16) -> Result<(), Self::Error> {
+            self.inner.append_lines(n).map_err(|err| match err {})
+        }
+
+        fn hide_cursor(&mut self) -> Result<(), Self::Error> {
+            self.inner.hide_cursor().map_err(|err| match err {})
+        }
+
+        fn show_cursor(&mut self) -> Result<(), Self::Error> {
+            self.inner.show_cursor().map_err(|err| match err {})
+        }
+
+        fn get_cursor_position(&mut self) -> Result<Position, Self::Error> {
+            self.inner.get_cursor_position().map_err(|err| match err {})
+        }
+
+        fn set_cursor_position<P: Into<Position>>(
+            &mut self,
+            position: P,
+        ) -> Result<(), Self::Error> {
+            self.inner
+                .set_cursor_position(position)
+                .map_err(|err| match err {})
+        }
+
+        fn clear(&mut self) -> Result<(), Self::Error> {
+            self.inner.clear().map_err(|err| match err {})
+        }
+
+        fn clear_region(&mut self, clear_type: ClearType) -> Result<(), Self::Error> {
+            self.inner
+                .clear_region(clear_type)
+                .map_err(|err| match err {})
+        }
+
+        fn size(&self) -> Result<crate::layout::Size, Self::Error> {
+            self.inner.size().map_err(|err| match err {})
+        }
+
+        fn window_size(&mut self) -> Result<WindowSize, Self::Error> {
+            self.inner.window_size().map_err(|err| match err {})
+        }
+
+        fn flush(&mut self) -> Result<(), Self::Error> {
+            self.inner.flush().map_err(|err| match err {})
+        }
+
+        #[cfg(feature = "scrolling-regions")]
+        fn scroll_region_up(
+            &mut self,
+            region: core::ops::Range<u16>,
+            line_count: u16,
+        ) -> Result<(), Self::Error> {
+            self.inner
+                .scroll_region_up(region, line_count)
+                .map_err(|err| match err {})
+        }
+
+        #[cfg(feature = "scrolling-regions")]
+        fn scroll_region_down(
+            &mut self,
+            region: core::ops::Range<u16>,
+            line_count: u16,
+        ) -> Result<(), Self::Error> {
+            self.inner
+                .scroll_region_down(region, line_count)
+                .map_err(|err| match err {})
+        }
+    }
+
+    /// `draw` hides the cursor when the frame does not request a cursor position.
+    ///
+    /// This asserts the end-to-end effect on the backend (buffer contents + cursor state) as well
+    /// as internal frame counting.
+    #[test]
+    fn draw_hides_cursor_when_frame_cursor_is_not_set() {
+        let backend = TestBackend::new(3, 2);
+        let mut terminal = Terminal::new(backend).unwrap();
+
+        terminal.show_cursor().unwrap();
+
+        let completed = terminal
+            .draw(|frame| {
+                // Ensure the frame produces updates so `Terminal::flush` writes to the backend.
+                frame.buffer_mut()[(0, 0)] = Cell::new("x");
+            })
+            .unwrap();
+
+        assert_eq!(completed.count, 0, "first draw returns count 0");
+        assert_eq!(
+            completed.area,
+            Rect::new(0, 0, 3, 2),
+            "completed area matches terminal size in fullscreen mode"
+        );
+        assert_eq!(
+            completed.buffer,
+            &Buffer::with_lines(["x  ", "   "]),
+            "completed buffer contains the rendered content"
+        );
+
+        assert!(terminal.hidden_cursor);
+        assert!(!terminal.backend().cursor_visible());
+        assert_eq!(
+            terminal.frame_count, 1,
+            "successful draw increments frame_count"
+        );
+    }
+
+    /// `draw` applies the cursor requested by `Frame::set_cursor_position`.
+    ///
+    /// The cursor is updated after rendering has been flushed, so it appears on top of the drawn
+    /// UI.
+    #[test]
+    fn draw_shows_and_positions_cursor_when_frame_cursor_is_set() {
+        let backend = TestBackend::new(3, 2);
+        let mut terminal = Terminal::new(backend).unwrap();
+
+        terminal.hide_cursor().unwrap();
+
+        terminal
+            .draw(|frame| {
+                // The cursor is applied after the frame is flushed.
+                frame.set_cursor_position(Position { x: 2, y: 1 });
+                frame.buffer_mut()[(1, 0)] = Cell::new("y");
+            })
+            .unwrap();
+
+        assert!(!terminal.hidden_cursor);
+        assert!(terminal.backend().cursor_visible());
+        assert_eq!(
+            terminal.backend().cursor_position(),
+            Position { x: 2, y: 1 },
+            "backend cursor is positioned after flushing"
+        );
+        assert_eq!(
+            terminal.last_known_cursor_pos,
+            Position { x: 2, y: 1 },
+            "terminal cursor tracking matches the final cursor position"
+        );
+    }
+
+    /// When the render callback returns an error, `try_draw` does not update the terminal.
+    ///
+    /// This is a characterization of the "no partial updates" behavior: backend contents and
+    /// cursor state are unchanged and `frame_count` does not advance.
+    #[test]
+    fn try_draw_propagates_render_errors_without_updating_backend() {
+        let backend = FallibleTestBackend::new(TestBackend::with_lines(["aaa", "bbb"]));
+        let mut terminal = Terminal::new(backend).unwrap();
+
+        terminal.show_cursor().unwrap();
+
+        let was_hidden = terminal.hidden_cursor;
+        let cursor_visible = terminal.backend().inner.cursor_visible();
+        let cursor_position = terminal.backend().inner.cursor_position();
+
+        let result = terminal.try_draw(|_frame| Err::<(), _>(TestError("render failed")));
+
+        assert_eq!(
+            result.unwrap_err(),
+            TestError("render failed"),
+            "try_draw returns the render callback error"
+        );
+
+        assert_eq!(terminal.frame_count, 0, "frame_count is unchanged on error");
+        assert_eq!(
+            terminal.backend().inner.buffer(),
+            &Buffer::with_lines(["aaa", "bbb"]),
+            "backend buffer is unchanged on error"
+        );
+        assert_eq!(
+            terminal.hidden_cursor, was_hidden,
+            "terminal cursor state is unchanged on error"
+        );
+        assert_eq!(
+            terminal.backend().inner.cursor_visible(),
+            cursor_visible,
+            "backend cursor visibility is unchanged on error"
+        );
+        assert_eq!(
+            terminal.backend().inner.cursor_position(),
+            cursor_position,
+            "backend cursor position is unchanged on error"
+        );
+    }
+
+    /// `draw` autoresizes fullscreen terminals and clears before rendering.
+    ///
+    /// This simulates the backend resizing between draw calls; `draw` runs `autoresize()` first
+    /// (which calls `resize()` and clears) so the frame renders into a fresh, correctly-sized
+    /// region.
+    #[test]
+    fn draw_clears_on_fullscreen_resize_before_rendering() {
+        let backend = TestBackend::with_lines(["xxx", "yyy"]);
+        let mut terminal = Terminal::new(backend).unwrap();
+
+        terminal.backend_mut().resize(4, 3);
+
+        terminal
+            .draw(|frame| {
+                // Render a marker to show we rendered after the clear.
+                frame.buffer_mut()[(0, 0)] = Cell::new("x");
+            })
+            .unwrap();
+
+        assert_eq!(
+            terminal.viewport_area,
+            Rect::new(0, 0, 4, 3),
+            "viewport area tracks the resized terminal size"
+        );
+        assert_eq!(
+            terminal.last_known_area,
+            Rect::new(0, 0, 4, 3),
+            "last_known_area tracks the resized terminal size"
+        );
+        terminal
+            .backend()
+            .assert_buffer_lines(["x   ", "    ", "    "]);
+    }
+
+    /// In fixed viewports, `Frame::area` is an absolute terminal rectangle.
+    ///
+    /// This asserts that rendering at `frame.area().x/y` updates the backend at that absolute
+    /// position.
+    #[test]
+    fn draw_uses_fixed_viewport_coordinates() {
+        let backend = TestBackend::new(5, 3);
+        let mut terminal = Terminal::with_options(
+            backend,
+            TerminalOptions {
+                viewport: Viewport::Fixed(Rect::new(2, 1, 2, 1)),
+            },
+        )
+        .unwrap();
+
+        terminal
+            .draw(|frame| {
+                assert_eq!(
+                    frame.area(),
+                    Rect::new(2, 1, 2, 1),
+                    "frame area matches the configured fixed viewport"
+                );
+                let area = frame.area();
+                frame.buffer_mut()[(area.x, area.y)] = Cell::new("z");
+            })
+            .unwrap();
+
+        terminal
+            .backend()
+            .assert_buffer_lines(["     ", "  z  ", "     "]);
+    }
+
+    /// Inline viewports render into a sub-rectangle, but `CompletedFrame::area` reports terminal
+    /// size.
+    ///
+    /// This asserts that the `CompletedFrame` returned from `draw` reports the full terminal
+    /// size while its buffer is sized to the inline viewport, and that rendering uses the inline
+    /// viewport's absolute origin.
+    #[test]
+    fn draw_inline_completed_frame_reports_terminal_size() {
+        let mut inner = TestBackend::new(6, 5);
+        inner.set_cursor_position((0, 2)).unwrap();
+        let mut terminal = Terminal::with_options(
+            inner,
+            TerminalOptions {
+                viewport: Viewport::Inline(3),
+            },
+        )
+        .unwrap();
+
+        let viewport_area = terminal.viewport_area;
+        {
+            // `CompletedFrame` borrows the terminal, so backend assertions happen after it drops.
+            let completed = terminal
+                .draw(|frame| {
+                    assert_eq!(
+                        frame.area(),
+                        viewport_area,
+                        "inline frame area matches the computed viewport"
+                    );
+                    frame.buffer_mut()[(viewport_area.x, viewport_area.y)] = Cell::new("i");
+                })
+                .unwrap();
+
+            assert_eq!(
+                completed.area,
+                Rect::new(0, 0, 6, 5),
+                "completed area reports the full terminal size"
+            );
+            assert_eq!(
+                completed.buffer.area, viewport_area,
+                "completed buffer is sized to the inline viewport"
+            );
+        }
+
+        assert_eq!(
+            terminal.backend().buffer()[(viewport_area.x, viewport_area.y)].symbol(),
+            "i"
+        );
+    }
+
+    /// Inline viewports are autoresized during `draw`.
+    ///
+    /// This asserts that when the backend reports a different terminal size, `draw` recomputes the
+    /// inline viewport rectangle and renders into the new viewport area.
+    #[test]
+    fn draw_inline_autoresize_recomputes_viewport_on_grow() {
+        let mut backend = TestBackend::new(6, 5);
+        backend
+            .set_cursor_position(Position { x: 0, y: 2 })
+            .unwrap();
+        let mut terminal = Terminal::with_options(
+            backend,
+            TerminalOptions {
+                viewport: Viewport::Inline(3),
+            },
+        )
+        .unwrap();
+
+        terminal
+            .draw(|frame| {
+                let area = frame.area();
+                frame.set_cursor_position(Position {
+                    x: area.x,
+                    y: area.y.saturating_add(1),
+                });
+                frame.buffer_mut()[(area.x, area.y)] = Cell::new("a");
+            })
+            .unwrap();
+
+        terminal.backend_mut().resize(8, 7);
+        let new_area = Rect::new(0, 0, 8, 7);
+
+        let previous_viewport = terminal.viewport_area;
+        terminal
+            .draw(|frame| {
+                let area = frame.area();
+                frame.buffer_mut()[(area.x, area.y)] = Cell::new("g");
+            })
+            .unwrap();
+
+        assert_eq!(
+            terminal.last_known_area, new_area,
+            "inline last_known_area tracks the resized terminal size"
+        );
+        assert_eq!(
+            terminal.viewport_area.width, 8,
+            "inline viewport width tracks the resized terminal width"
+        );
+        assert_eq!(
+            terminal.viewport_area.height, 3,
+            "inline viewport height is capped by the configured inline height"
+        );
+        assert_eq!(
+            terminal.viewport_area.y, previous_viewport.y,
+            "inline viewport stays anchored relative to the cursor across a grow"
+        );
+        assert_eq!(
+            terminal.backend().buffer()[(terminal.viewport_area.x, terminal.viewport_area.y)]
+                .symbol(),
+            "g",
+            "render output lands at the recomputed viewport origin"
+        );
+    }
+
+    /// Inline viewports are autoresized during `draw`.
+    ///
+    /// This asserts that shrinking the backend terminal size causes `draw` to recompute the inline
+    /// viewport origin so it stays visible, and that rendering uses the new viewport origin.
+    #[test]
+    fn draw_inline_autoresize_recomputes_viewport_on_shrink() {
+        let mut backend = TestBackend::new(6, 6);
+        backend
+            .set_cursor_position(Position { x: 0, y: 4 })
+            .unwrap();
+        let mut terminal = Terminal::with_options(
+            backend,
+            TerminalOptions {
+                viewport: Viewport::Inline(4),
+            },
+        )
+        .unwrap();
+
+        terminal
+            .draw(|frame| {
+                let area = frame.area();
+                frame.set_cursor_position(Position {
+                    x: area.x,
+                    y: area.y.saturating_add(2),
+                });
+                frame.buffer_mut()[(area.x, area.y)] = Cell::new("a");
+            })
+            .unwrap();
+
+        terminal.backend_mut().resize(6, 5);
+        let new_area = Rect::new(0, 0, 6, 5);
+
+        terminal
+            .draw(|frame| {
+                let area = frame.area();
+                frame.buffer_mut()[(area.x, area.y)] = Cell::new("s");
+            })
+            .unwrap();
+
+        assert_eq!(
+            terminal.last_known_area, new_area,
+            "inline last_known_area tracks the resized terminal size"
+        );
+        assert_eq!(
+            terminal.viewport_area,
+            Rect::new(0, 1, 6, 4),
+            "inline viewport is recomputed to stay visible after a shrink"
+        );
+        assert_eq!(
+            terminal.backend().buffer()[(terminal.viewport_area.x, terminal.viewport_area.y)]
+                .symbol(),
+            "s",
+            "render output lands at the recomputed viewport origin"
+        );
+    }
+
+    /// `CompletedFrame` is only valid until the next draw call.
+    ///
+    /// This asserts that each `draw` returns the buffer for the frame that was just rendered
+    /// and that the count increments after each successful draw.
+    #[test]
+    fn draw_returns_completed_frame_for_current_render_pass() {
+        let backend = TestBackend::new(3, 2);
+        let mut terminal = Terminal::new(backend).unwrap();
+
+        {
+            // `CompletedFrame` borrows the terminal, and is only valid until the next draw call.
+            let first = terminal
+                .draw(|frame| {
+                    frame.buffer_mut()[(0, 0)] = Cell::new("a");
+                })
+                .unwrap();
+
+            assert_eq!(first.count, 0, "first CompletedFrame has count 0");
+            assert_eq!(
+                first.buffer,
+                &Buffer::with_lines(["a  ", "   "]),
+                "first frame's buffer contains the first render output"
+            );
+        }
+
+        let second = terminal
+            .draw(|frame| {
+                frame.buffer_mut()[(0, 0)] = Cell::new("b");
+            })
+            .unwrap();
+
+        assert_eq!(second.count, 1, "second CompletedFrame has count 1");
+        assert_eq!(
+            second.buffer,
+            &Buffer::with_lines(["b  ", "   "]),
+            "second frame's buffer contains the second render output"
+        );
+    }
+}

ratatui-core/src/terminal/resize.rs

@@ -0,0 +1,255 @@
+use crate::backend::Backend;
+use crate::layout::Rect;
+use crate::terminal::inline::compute_inline_size;
+use crate::terminal::{Terminal, Viewport};
+
+impl<B: Backend> Terminal<B> {
+    /// Updates the Terminal so that internal buffers match the requested area.
+    ///
+    /// This updates the buffer size used for rendering and triggers a full clear so the next
+    /// [`Terminal::draw`] paints into a consistent area.
+    ///
+    /// When the viewport is [`Viewport::Inline`], the `area` argument is treated as the new
+    /// terminal size and the viewport origin is recomputed relative to the current cursor position.
+    /// Ratatui attempts to keep the cursor at the same relative row within the viewport across
+    /// resizes.
+    ///
+    /// See also: [`Terminal::autoresize`] (automatic resizing during [`Terminal::draw`]).
+    pub fn resize(&mut self, area: Rect) -> Result<(), B::Error> {
+        let next_area = match self.viewport {
+            Viewport::Inline(height) => {
+                let offset_in_previous_viewport = self
+                    .last_known_cursor_pos
+                    .y
+                    .saturating_sub(self.viewport_area.top());
+                compute_inline_size(
+                    &mut self.backend,
+                    height,
+                    area.as_size(),
+                    offset_in_previous_viewport,
+                )?
+                .0
+            }
+            Viewport::Fixed(_) | Viewport::Fullscreen => area,
+        };
+        self.set_viewport_area(next_area);
+        self.clear()?;
+
+        self.last_known_area = area;
+        Ok(())
+    }
+
+    /// Queries the backend for size and resizes if it doesn't match the previous size.
+    ///
+    /// This is called automatically during [`Terminal::draw`] for fullscreen and inline viewports.
+    /// Fixed viewports are not automatically resized.
+    ///
+    /// If the size changed, this calls [`Terminal::resize`] (which clears the screen).
+    pub fn autoresize(&mut self) -> Result<(), B::Error> {
+        // fixed viewports do not get autoresized
+        if matches!(self.viewport, Viewport::Fullscreen | Viewport::Inline(_)) {
+            let area = self.size()?.into();
+            if area != self.last_known_area {
+                self.resize(area)?;
+            }
+        }
+        Ok(())
+    }
+
+    /// Resize internal buffers and update the current viewport area.
+    ///
+    /// This is an internal helper used by [`Terminal::with_options`] and [`Terminal::resize`].
+    pub(crate) fn set_viewport_area(&mut self, area: Rect) {
+        self.buffers[self.current].resize(area);
+        self.buffers[1 - self.current].resize(area);
+        self.viewport_area = area;
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use crate::backend::{Backend, TestBackend};
+    use crate::buffer::Buffer;
+    use crate::layout::{Position, Rect};
+    use crate::terminal::{Terminal, TerminalOptions, Viewport};
+
+    #[test]
+    fn resize_fullscreen_updates_viewport_and_buffer_areas() {
+        let backend = TestBackend::new(3, 2);
+        let mut terminal = Terminal::new(backend).unwrap();
+
+        terminal.backend_mut().resize(4, 3);
+        let new_area = Rect::new(0, 0, 4, 3);
+        terminal.resize(new_area).unwrap();
+
+        assert_eq!(terminal.viewport_area, new_area);
+        assert_eq!(terminal.last_known_area, new_area);
+        assert_eq!(terminal.buffers[terminal.current].area, new_area);
+        assert_eq!(terminal.buffers[1 - terminal.current].area, new_area);
+    }
+
+    #[test]
+    fn resize_fullscreen_triggers_clear_and_resets_back_buffer() {
+        // This test is specifically about the side effects of `resize`:
+        // - it calls `clear` to force a full redraw
+        // - it resets the "previous" buffer
+        let backend = TestBackend::new(3, 2);
+        let mut terminal = Terminal::new(backend).unwrap();
+
+        // Put visible content on the backend so we can tell whether a clear happened.
+        {
+            let frame = terminal.get_frame();
+            frame.buffer[(0, 0)].set_symbol("x");
+        }
+        terminal.flush().unwrap();
+        terminal.backend().assert_buffer_lines(["x  ", "   "]);
+
+        terminal.backend_mut().resize(4, 3);
+        let new_area = Rect::new(0, 0, 4, 3);
+        terminal.resize(new_area).unwrap();
+
+        terminal
+            .backend()
+            .assert_buffer_lines(["    ", "    ", "    "]);
+        assert_eq!(
+            terminal.buffers[1 - terminal.current],
+            Buffer::empty(new_area)
+        );
+    }
+
+    #[test]
+    fn autoresize_fullscreen_uses_backend_size_when_changed() {
+        let backend = TestBackend::new(3, 2);
+        let mut terminal = Terminal::new(backend).unwrap();
+
+        {
+            let frame = terminal.get_frame();
+            frame.buffer[(0, 0)].set_symbol("x");
+        }
+        terminal.flush().unwrap();
+
+        terminal.backend_mut().resize(4, 3);
+        terminal.autoresize().unwrap();
+
+        assert_eq!(terminal.viewport_area, Rect::new(0, 0, 4, 3));
+        assert_eq!(terminal.last_known_area, Rect::new(0, 0, 4, 3));
+        terminal
+            .backend()
+            .assert_buffer_lines(["    ", "    ", "    "]);
+    }
+
+    #[test]
+    fn autoresize_fixed_does_not_change_viewport() {
+        let backend = TestBackend::with_lines(["xxx", "yyy"]);
+        let mut terminal = Terminal::with_options(
+            backend,
+            TerminalOptions {
+                viewport: Viewport::Fixed(Rect::new(1, 0, 2, 2)),
+            },
+        )
+        .unwrap();
+
+        terminal.autoresize().unwrap();
+
+        assert_eq!(terminal.viewport_area, Rect::new(1, 0, 2, 2));
+        assert_eq!(terminal.last_known_area, Rect::new(1, 0, 2, 2));
+        terminal.backend().assert_buffer_lines(["xxx", "yyy"]);
+    }
+
+    #[test]
+    fn resize_fixed_changes_viewport_area_and_buffer_sizes() {
+        let backend = TestBackend::new(5, 3);
+        let mut terminal = Terminal::with_options(
+            backend,
+            TerminalOptions {
+                viewport: Viewport::Fixed(Rect::new(1, 1, 2, 1)),
+            },
+        )
+        .unwrap();
+
+        terminal.resize(Rect::new(0, 0, 3, 2)).unwrap();
+
+        assert_eq!(terminal.viewport_area, Rect::new(0, 0, 3, 2));
+        assert_eq!(terminal.last_known_area, Rect::new(0, 0, 3, 2));
+        assert_eq!(
+            terminal.buffers[terminal.current].area,
+            terminal.viewport_area
+        );
+        assert_eq!(
+            terminal.buffers[1 - terminal.current].area,
+            terminal.viewport_area
+        );
+    }
+
+    #[test]
+    fn resize_inline_recomputes_origin_using_previous_cursor_offset() {
+        let mut backend = TestBackend::new(10, 10);
+        backend
+            .set_cursor_position(Position { x: 0, y: 4 })
+            .unwrap();
+        let mut terminal = Terminal::with_options(
+            backend,
+            TerminalOptions {
+                viewport: Viewport::Inline(4),
+            },
+        )
+        .unwrap();
+
+        assert_eq!(terminal.viewport_area, Rect::new(0, 4, 10, 4));
+
+        // Characterization test:
+        // This test simulates a terminal resize (increasing the terminal height) while an inline
+        // viewport is active. The key behavior being exercised is that the viewport remains
+        // anchored to the backend cursor row and preserves the cursor's relative offset within the
+        // previous viewport.
+        //
+        // For inline viewports, `Terminal::resize(area)` interprets `area` as the *new terminal
+        // size*, then recomputes the viewport origin based on:
+        // - the backend cursor position at the time of the call
+        // - the cursor offset within the *previous* viewport (`last_known_cursor_pos -
+        //   viewport_top`)
+        //
+        // This means `resize(Rect { .. })` can update `viewport_area.y` even when the passed-in
+        // `area.y` is 0, because `viewport_area` is anchored to the cursor row, not the terminal
+        // origin.
+        terminal.last_known_cursor_pos = Position { x: 0, y: 5 };
+        terminal
+            .backend_mut()
+            .set_cursor_position(Position { x: 0, y: 6 })
+            .unwrap();
+
+        terminal.backend_mut().resize(10, 12);
+        let new_terminal_area = Rect::new(0, 0, 10, 12);
+        terminal.resize(new_terminal_area).unwrap();
+
+        // Previous viewport top was y=4, and last_known_cursor_pos was y=5, so the cursor offset
+        // within the viewport is 1 row. At the time of resize the backend cursor is at y=6, so the
+        // new viewport top becomes 6 - 1 = 5.
+        assert_eq!(terminal.viewport_area, Rect::new(0, 5, 10, 4));
+        assert_eq!(terminal.last_known_area, new_terminal_area);
+    }
+
+    #[test]
+    fn resize_inline_clamps_height_to_terminal_height() {
+        // Characterization test:
+        // This test simulates a terminal resize that *reduces* the terminal height. Inline
+        // viewports clamp their height to the new terminal size so the viewport remains fully
+        // visible.
+        let mut backend = TestBackend::new(10, 10);
+        backend
+            .set_cursor_position(Position { x: 0, y: 0 })
+            .unwrap();
+        let mut terminal = Terminal::with_options(
+            backend,
+            TerminalOptions {
+                viewport: Viewport::Inline(10),
+            },
+        )
+        .unwrap();
+
+        terminal.backend_mut().resize(10, 3);
+        terminal.resize(Rect::new(0, 0, 10, 3)).unwrap();
+
+        assert_eq!(terminal.viewport_area, Rect::new(0, 0, 10, 3));
+    }
+}

ratatui-core/src/terminal/terminal.rs

@@ -1,926 +0,0 @@
-use crate::backend::{Backend, ClearType};
-use crate::buffer::{Buffer, Cell};
-use crate::layout::{Position, Rect, Size};
-use crate::terminal::{CompletedFrame, Frame, TerminalOptions, Viewport};
-
-/// An interface to interact and draw [`Frame`]s on the user's terminal.
-///
-/// This is the main entry point for Ratatui. It is responsible for drawing and maintaining the
-/// state of the buffers, cursor and viewport.
-///
-/// The [`Terminal`] is generic over a [`Backend`] implementation which is used to interface with
-/// the underlying terminal library. The [`Backend`] trait is implemented for three popular Rust
-/// terminal libraries: [Crossterm], [Termion] and [Termwiz]. See the [`backend`] module for more
-/// information.
-///
-/// The `Terminal` struct maintains two buffers: the current and the previous.
-/// When the widgets are drawn, the changes are accumulated in the current buffer.
-/// At the end of each draw pass, the two buffers are compared, and only the changes
-/// between these buffers are written to the terminal, avoiding any redundant operations.
-/// After flushing these changes, the buffers are swapped to prepare for the next draw cycle.
-///
-/// The terminal also has a viewport which is the area of the terminal that is currently visible to
-/// the user. It can be either fullscreen, inline or fixed. See [`Viewport`] for more information.
-///
-/// Applications should detect terminal resizes and call [`Terminal::draw`] to redraw the
-/// application with the new size. This will automatically resize the internal buffers to match the
-/// new size for inline and fullscreen viewports. Fixed viewports are not resized automatically.
-///
-/// # Initialization
-///
-/// For most applications, consider using the convenience functions `ratatui::run()`,
-/// `ratatui::init()`, and `ratatui::restore()` (available since version 0.28.1) along with the
-/// `DefaultTerminal` type alias instead of constructing `Terminal` instances manually. These
-/// functions handle the common setup and teardown tasks automatically. Manual construction
-/// using `Terminal::new()` or `Terminal::with_options()` is still supported for applications
-/// that need fine-grained control over initialization.
-///
-/// # Examples
-///
-/// ## Using convenience functions (recommended for most applications)
-///
-/// ```rust,ignore
-/// // Modern approach using convenience functions
-/// ratatui::run(|terminal| {
-///     terminal.draw(|frame| {
-///         let area = frame.area();
-///         frame.render_widget(Paragraph::new("Hello World!"), area);
-///     })?;
-///     Ok(())
-/// })?;
-/// ```
-///
-/// ## Manual construction (for fine-grained control)
-///
-/// ```rust,ignore
-/// use std::io::stdout;
-///
-/// use ratatui::{backend::CrosstermBackend, widgets::Paragraph, Terminal};
-///
-/// let backend = CrosstermBackend::new(stdout());
-/// let mut terminal = Terminal::new(backend)?;
-/// terminal.draw(|frame| {
-///     let area = frame.area();
-///     frame.render_widget(Paragraph::new("Hello World!"), area);
-/// })?;
-/// # std::io::Result::Ok(())
-/// ```
-///
-/// [Crossterm]: https://crates.io/crates/crossterm
-/// [Termion]: https://crates.io/crates/termion
-/// [Termwiz]: https://crates.io/crates/termwiz
-/// [`backend`]: crate::backend
-/// [`Backend`]: crate::backend::Backend
-/// [`Buffer`]: crate::buffer::Buffer
-#[derive(Debug, Default, Clone, Eq, PartialEq, Hash)]
-pub struct Terminal<B>
-where
-    B: Backend,
-{
-    /// The backend used to interface with the terminal
-    backend: B,
-    /// Holds the results of the current and previous draw calls. The two are compared at the end
-    /// of each draw pass to output the necessary updates to the terminal
-    buffers: [Buffer; 2],
-    /// Index of the current buffer in the previous array
-    current: usize,
-    /// Whether the cursor is currently hidden
-    hidden_cursor: bool,
-    /// Viewport
-    viewport: Viewport,
-    /// Area of the viewport
-    viewport_area: Rect,
-    /// Last known area of the terminal. Used to detect if the internal buffers have to be resized.
-    last_known_area: Rect,
-    /// Last known position of the cursor. Used to find the new area when the viewport is inlined
-    /// and the terminal resized.
-    last_known_cursor_pos: Position,
-    /// Number of frames rendered up until current time.
-    frame_count: usize,
-}
-
-/// Options to pass to [`Terminal::with_options`]
-#[derive(Debug, Default, Clone, Eq, PartialEq, Hash)]
-pub struct Options {
-    /// Viewport used to draw to the terminal
-    pub viewport: Viewport,
-}
-
-impl<B> Drop for Terminal<B>
-where
-    B: Backend,
-{
-    fn drop(&mut self) {
-        // Attempt to restore the cursor state
-        if self.hidden_cursor {
-            #[allow(unused_variables)]
-            if let Err(err) = self.show_cursor() {
-                #[cfg(feature = "std")]
-                std::eprintln!("Failed to show the cursor: {err}");
-            }
-        }
-    }
-}
-
-impl<B> Terminal<B>
-where
-    B: Backend,
-{
-    /// Creates a new [`Terminal`] with the given [`Backend`] with a full screen viewport.
-    ///
-    /// Note that unlike `ratatui::init`, this does not install a panic hook, so it is recommended
-    /// to do that manually when using this function, otherwise any panic messages will be printed
-    /// to the alternate screen and the terminal may be left in an unusable state.
-    ///
-    /// See [how to set up panic hooks](https://ratatui.rs/recipes/apps/panic-hooks/) and
-    /// [`better-panic` example](https://ratatui.rs/recipes/apps/better-panic/) for more
-    /// information.
-    ///
-    /// # Example
-    ///
-    /// ```rust,ignore
-    /// use std::io::stdout;
-    ///
-    /// use ratatui::{backend::CrosstermBackend, Terminal};
-    ///
-    /// let backend = CrosstermBackend::new(stdout());
-    /// let terminal = Terminal::new(backend)?;
-    ///
-    /// // Optionally set up a panic hook to restore the terminal on panic.
-    /// let old_hook = std::panic::take_hook();
-    /// std::panic::set_hook(Box::new(move |info| {
-    ///     ratatui::restore();
-    ///     old_hook(info);
-    /// }));
-    /// # std::io::Result::Ok(())
-    /// ```
-    pub fn new(backend: B) -> Result<Self, B::Error> {
-        Self::with_options(
-            backend,
-            TerminalOptions {
-                viewport: Viewport::Fullscreen,
-            },
-        )
-    }
-
-    /// Creates a new [`Terminal`] with the given [`Backend`] and [`TerminalOptions`].
-    ///
-    /// # Example
-    ///
-    /// ```rust,ignore
-    /// use std::io::stdout;
-    ///
-    /// use ratatui::{backend::CrosstermBackend, layout::Rect, Terminal, TerminalOptions, Viewport};
-    ///
-    /// let backend = CrosstermBackend::new(stdout());
-    /// let viewport = Viewport::Fixed(Rect::new(0, 0, 10, 10));
-    /// let terminal = Terminal::with_options(backend, TerminalOptions { viewport })?;
-    /// # std::io::Result::Ok(())
-    /// ```
-    pub fn with_options(mut backend: B, options: TerminalOptions) -> Result<Self, B::Error> {
-        let area = match options.viewport {
-            Viewport::Fullscreen | Viewport::Inline(_) => backend.size()?.into(),
-            Viewport::Fixed(area) => area,
-        };
-        let (viewport_area, cursor_pos) = match options.viewport {
-            Viewport::Fullscreen => (area, Position::ORIGIN),
-            Viewport::Inline(height) => {
-                compute_inline_size(&mut backend, height, area.as_size(), 0)?
-            }
-            Viewport::Fixed(area) => (area, area.as_position()),
-        };
-        Ok(Self {
-            backend,
-            buffers: [Buffer::empty(viewport_area), Buffer::empty(viewport_area)],
-            current: 0,
-            hidden_cursor: false,
-            viewport: options.viewport,
-            viewport_area,
-            last_known_area: area,
-            last_known_cursor_pos: cursor_pos,
-            frame_count: 0,
-        })
-    }
-
-    /// Get a Frame object which provides a consistent view into the terminal state for rendering.
-    ///
-    /// # Note
-    ///
-    /// This exists to support more advanced use cases. Most cases should be fine using
-    /// [`Terminal::draw`].
-    ///
-    /// [`Terminal::get_frame`] should be used when you need direct access to the frame buffer
-    /// outside of draw closure, for example:
-    ///
-    /// - Unit testing widgets
-    /// - Buffer state inspection
-    /// - Cursor manipulation
-    /// - Multiple rendering passes/Buffer Manipulation
-    /// - Custom frame lifecycle management
-    /// - Buffer exporting
-    ///
-    /// # Example
-    ///
-    /// Getting the buffer and asserting on some cells after rendering a widget.
-    ///
-    /// ```rust,ignore
-    /// use ratatui::{backend::TestBackend, Terminal};
-    /// use ratatui::widgets::Paragraph;
-    /// let backend = TestBackend::new(30, 5);
-    /// let mut terminal = Terminal::new(backend).unwrap();
-    /// {
-    ///     let mut frame = terminal.get_frame();
-    ///     frame.render_widget(Paragraph::new("Hello"), frame.area());
-    /// }
-    /// // When not using `draw`, present the buffer manually:
-    /// terminal.flush().unwrap();
-    /// terminal.swap_buffers();
-    /// terminal.backend_mut().flush().unwrap();
-    /// ```
-    pub const fn get_frame(&mut self) -> Frame<'_> {
-        let count = self.frame_count;
-        Frame {
-            cursor_position: None,
-            viewport_area: self.viewport_area,
-            buffer: self.current_buffer_mut(),
-            count,
-        }
-    }
-
-    /// Gets the current buffer as a mutable reference.
-    pub const fn current_buffer_mut(&mut self) -> &mut Buffer {
-        &mut self.buffers[self.current]
-    }
-
-    /// Gets the backend
-    pub const fn backend(&self) -> &B {
-        &self.backend
-    }
-
-    /// Gets the backend as a mutable reference
-    pub const fn backend_mut(&mut self) -> &mut B {
-        &mut self.backend
-    }
-
-    /// Obtains a difference between the previous and the current buffer and passes it to the
-    /// current backend for drawing.
-    pub fn flush(&mut self) -> Result<(), B::Error> {
-        let previous_buffer = &self.buffers[1 - self.current];
-        let current_buffer = &self.buffers[self.current];
-        let updates = previous_buffer.diff(current_buffer);
-        if let Some((col, row, _)) = updates.last() {
-            self.last_known_cursor_pos = Position { x: *col, y: *row };
-        }
-        self.backend.draw(updates.into_iter())
-    }
-
-    /// Updates the Terminal so that internal buffers match the requested area.
-    ///
-    /// Requested area will be saved to remain consistent when rendering. This leads to a full clear
-    /// of the screen.
-    pub fn resize(&mut self, area: Rect) -> Result<(), B::Error> {
-        let next_area = match self.viewport {
-            Viewport::Inline(height) => {
-                let offset_in_previous_viewport = self
-                    .last_known_cursor_pos
-                    .y
-                    .saturating_sub(self.viewport_area.top());
-                compute_inline_size(
-                    &mut self.backend,
-                    height,
-                    area.as_size(),
-                    offset_in_previous_viewport,
-                )?
-                .0
-            }
-            Viewport::Fixed(_) | Viewport::Fullscreen => area,
-        };
-        self.set_viewport_area(next_area);
-        self.clear()?;
-
-        self.last_known_area = area;
-        Ok(())
-    }
-
-    fn set_viewport_area(&mut self, area: Rect) {
-        self.buffers[self.current].resize(area);
-        self.buffers[1 - self.current].resize(area);
-        self.viewport_area = area;
-    }
-
-    /// Queries the backend for size and resizes if it doesn't match the previous size.
-    pub fn autoresize(&mut self) -> Result<(), B::Error> {
-        // fixed viewports do not get autoresized
-        if matches!(self.viewport, Viewport::Fullscreen | Viewport::Inline(_)) {
-            let area = self.size()?.into();
-            if area != self.last_known_area {
-                self.resize(area)?;
-            }
-        }
-        Ok(())
-    }
-
-    /// Draws a single frame to the terminal.
-    ///
-    /// Returns a [`CompletedFrame`] if successful, otherwise a [`std::io::Error`].
-    ///
-    /// If the render callback passed to this method can fail, use [`try_draw`] instead.
-    ///
-    /// Applications should call `draw` or [`try_draw`] in a loop to continuously render the
-    /// terminal. These methods are the main entry points for drawing to the terminal.
-    ///
-    /// [`try_draw`]: Terminal::try_draw
-    ///
-    /// This method will:
-    ///
-    /// - autoresize the terminal if necessary
-    /// - call the render callback, passing it a [`Frame`] reference to render to
-    /// - flush the current internal state by copying the current buffer to the backend
-    /// - move the cursor to the last known position if it was set during the rendering closure
-    /// - return a [`CompletedFrame`] with the current buffer and the area of the terminal
-    ///
-    /// The [`CompletedFrame`] returned by this method can be useful for debugging or testing
-    /// purposes, but it is often not used in regular applications.
-    ///
-    /// The render callback should fully render the entire frame when called, including areas that
-    /// are unchanged from the previous frame. This is because each frame is compared to the
-    /// previous frame to determine what has changed, and only the changes are written to the
-    /// terminal. If the render callback does not fully render the frame, the terminal will not be
-    /// in a consistent state.
-    ///
-    /// # Examples
-    ///
-    /// ```rust,ignore
-    /// # let backend = ratatui::backend::TestBackend::new(10, 10);
-    /// # let mut terminal = ratatui::Terminal::new(backend)?;
-    /// use ratatui::{layout::Position, widgets::Paragraph};
-    ///
-    /// // with a closure
-    /// terminal.draw(|frame| {
-    ///     let area = frame.area();
-    ///     frame.render_widget(Paragraph::new("Hello World!"), area);
-    ///     frame.set_cursor_position(Position { x: 0, y: 0 });
-    /// })?;
-    ///
-    /// // or with a function
-    /// terminal.draw(render)?;
-    ///
-    /// fn render(frame: &mut ratatui::Frame) {
-    ///     frame.render_widget(Paragraph::new("Hello World!"), frame.area());
-    /// }
-    /// # std::io::Result::Ok(())
-    /// ```
-    pub fn draw<F>(&mut self, render_callback: F) -> Result<CompletedFrame<'_>, B::Error>
-    where
-        F: FnOnce(&mut Frame),
-    {
-        self.try_draw(|frame| {
-            render_callback(frame);
-            Ok::<(), B::Error>(())
-        })
-    }
-
-    /// Tries to draw a single frame to the terminal.
-    ///
-    /// Returns [`Result::Ok`] containing a [`CompletedFrame`] if successful, otherwise
-    /// [`Result::Err`] containing the [`std::io::Error`] that caused the failure.
-    ///
-    /// This is the equivalent of [`Terminal::draw`] but the render callback is a function or
-    /// closure that returns a `Result` instead of nothing.
-    ///
-    /// Applications should call `try_draw` or [`draw`] in a loop to continuously render the
-    /// terminal. These methods are the main entry points for drawing to the terminal.
-    ///
-    /// [`draw`]: Terminal::draw
-    ///
-    /// This method will:
-    ///
-    /// - autoresize the terminal if necessary
-    /// - call the render callback, passing it a [`Frame`] reference to render to
-    /// - flush the current internal state by copying the current buffer to the backend
-    /// - move the cursor to the last known position if it was set during the rendering closure
-    /// - return a [`CompletedFrame`] with the current buffer and the area of the terminal
-    ///
-    /// The render callback passed to `try_draw` can return any [`Result`] with an error type that
-    /// can be converted into an [`std::io::Error`] using the [`Into`] trait. This makes it possible
-    /// to use the `?` operator to propagate errors that occur during rendering. If the render
-    /// callback returns an error, the error will be returned from `try_draw` as an
-    /// [`std::io::Error`] and the terminal will not be updated.
-    ///
-    /// The [`CompletedFrame`] returned by this method can be useful for debugging or testing
-    /// purposes, but it is often not used in regular applications.
-    ///
-    /// The render callback should fully render the entire frame when called, including areas that
-    /// are unchanged from the previous frame. This is because each frame is compared to the
-    /// previous frame to determine what has changed, and only the changes are written to the
-    /// terminal. If the render function does not fully render the frame, the terminal will not be
-    /// in a consistent state.
-    ///
-    /// # Examples
-    ///
-    /// ```ignore
-    /// # use ratatui::layout::Position;;
-    /// # let backend = ratatui::backend::TestBackend::new(10, 10);
-    /// # let mut terminal = ratatui::Terminal::new(backend)?;
-    /// use std::io;
-    ///
-    /// use ratatui::widgets::Paragraph;
-    ///
-    /// // with a closure
-    /// terminal.try_draw(|frame| {
-    ///     let value: u8 = "not a number".parse().map_err(io::Error::other)?;
-    ///     let area = frame.area();
-    ///     frame.render_widget(Paragraph::new("Hello World!"), area);
-    ///     frame.set_cursor_position(Position { x: 0, y: 0 });
-    ///     io::Result::Ok(())
-    /// })?;
-    ///
-    /// // or with a function
-    /// terminal.try_draw(render)?;
-    ///
-    /// fn render(frame: &mut ratatui::Frame) -> io::Result<()> {
-    ///     let value: u8 = "not a number".parse().map_err(io::Error::other)?;
-    ///     frame.render_widget(Paragraph::new("Hello World!"), frame.area());
-    ///     Ok(())
-    /// }
-    /// # io::Result::Ok(())
-    /// ```
-    pub fn try_draw<F, E>(&mut self, render_callback: F) -> Result<CompletedFrame<'_>, B::Error>
-    where
-        F: FnOnce(&mut Frame) -> Result<(), E>,
-        E: Into<B::Error>,
-    {
-        // Autoresize - otherwise we get glitches if shrinking or potential desync between widgets
-        // and the terminal (if growing), which may OOB.
-        self.autoresize()?;
-
-        let mut frame = self.get_frame();
-
-        render_callback(&mut frame).map_err(Into::into)?;
-
-        // We can't change the cursor position right away because we have to flush the frame to
-        // stdout first. But we also can't keep the frame around, since it holds a &mut to
-        // Buffer. Thus, we're taking the important data out of the Frame and dropping it.
-        let cursor_position = frame.cursor_position;
-
-        // Draw to stdout
-        self.flush()?;
-
-        match cursor_position {
-            None => self.hide_cursor()?,
-            Some(position) => {
-                self.show_cursor()?;
-                self.set_cursor_position(position)?;
-            }
-        }
-
-        self.swap_buffers();
-
-        // Flush
-        self.backend.flush()?;
-
-        let completed_frame = CompletedFrame {
-            buffer: &self.buffers[1 - self.current],
-            area: self.last_known_area,
-            count: self.frame_count,
-        };
-
-        // increment frame count before returning from draw
-        self.frame_count = self.frame_count.wrapping_add(1);
-
-        Ok(completed_frame)
-    }
-
-    /// Hides the cursor.
-    pub fn hide_cursor(&mut self) -> Result<(), B::Error> {
-        self.backend.hide_cursor()?;
-        self.hidden_cursor = true;
-        Ok(())
-    }
-
-    /// Shows the cursor.
-    pub fn show_cursor(&mut self) -> Result<(), B::Error> {
-        self.backend.show_cursor()?;
-        self.hidden_cursor = false;
-        Ok(())
-    }
-
-    /// Gets the current cursor position.
-    ///
-    /// This is the position of the cursor after the last draw call and is returned as a tuple of
-    /// `(x, y)` coordinates.
-    #[deprecated = "use `get_cursor_position()` instead which returns `Result<Position>`"]
-    pub fn get_cursor(&mut self) -> Result<(u16, u16), B::Error> {
-        let Position { x, y } = self.get_cursor_position()?;
-        Ok((x, y))
-    }
-
-    /// Sets the cursor position.
-    #[deprecated = "use `set_cursor_position((x, y))` instead which takes `impl Into<Position>`"]
-    pub fn set_cursor(&mut self, x: u16, y: u16) -> Result<(), B::Error> {
-        self.set_cursor_position(Position { x, y })
-    }
-
-    /// Gets the current cursor position.
-    ///
-    /// This is the position of the cursor after the last draw call.
-    pub fn get_cursor_position(&mut self) -> Result<Position, B::Error> {
-        self.backend.get_cursor_position()
-    }
-
-    /// Sets the cursor position.
-    pub fn set_cursor_position<P: Into<Position>>(&mut self, position: P) -> Result<(), B::Error> {
-        let position = position.into();
-        self.backend.set_cursor_position(position)?;
-        self.last_known_cursor_pos = position;
-        Ok(())
-    }
-
-    /// Clear the terminal and force a full redraw on the next draw call.
-    pub fn clear(&mut self) -> Result<(), B::Error> {
-        match self.viewport {
-            Viewport::Fullscreen => self.backend.clear_region(ClearType::All)?,
-            Viewport::Inline(_) => {
-                self.backend
-                    .set_cursor_position(self.viewport_area.as_position())?;
-                self.backend.clear_region(ClearType::AfterCursor)?;
-            }
-            Viewport::Fixed(_) => {
-                let area = self.viewport_area;
-                for y in area.top()..area.bottom() {
-                    self.backend.set_cursor_position(Position { x: 0, y })?;
-                    self.backend.clear_region(ClearType::AfterCursor)?;
-                }
-            }
-        }
-        // Reset the back buffer to make sure the next update will redraw everything.
-        self.buffers[1 - self.current].reset();
-        Ok(())
-    }
-
-    /// Clears the inactive buffer and swaps it with the current buffer
-    pub fn swap_buffers(&mut self) {
-        self.buffers[1 - self.current].reset();
-        self.current = 1 - self.current;
-    }
-
-    /// Queries the real size of the backend.
-    pub fn size(&self) -> Result<Size, B::Error> {
-        self.backend.size()
-    }
-
-    /// Insert some content before the current inline viewport. This has no effect when the
-    /// viewport is not inline.
-    ///
-    /// The `draw_fn` closure will be called to draw into a writable `Buffer` that is `height`
-    /// lines tall. The content of that `Buffer` will then be inserted before the viewport.
-    ///
-    /// If the viewport isn't yet at the bottom of the screen, inserted lines will push it towards
-    /// the bottom. Once the viewport is at the bottom of the screen, inserted lines will scroll
-    /// the area of the screen above the viewport upwards.
-    ///
-    /// Before:
-    /// ```ignore
-    /// +---------------------+
-    /// | pre-existing line 1 |
-    /// | pre-existing line 2 |
-    /// +---------------------+
-    /// |       viewport      |
-    /// +---------------------+
-    /// |                     |
-    /// |                     |
-    /// +---------------------+
-    /// ```
-    ///
-    /// After inserting 2 lines:
-    /// ```ignore
-    /// +---------------------+
-    /// | pre-existing line 1 |
-    /// | pre-existing line 2 |
-    /// |   inserted line 1   |
-    /// |   inserted line 2   |
-    /// +---------------------+
-    /// |       viewport      |
-    /// +---------------------+
-    /// +---------------------+
-    /// ```
-    ///
-    /// After inserting 2 more lines:
-    /// ```ignore
-    /// +---------------------+
-    /// | pre-existing line 2 |
-    /// |   inserted line 1   |
-    /// |   inserted line 2   |
-    /// |   inserted line 3   |
-    /// |   inserted line 4   |
-    /// +---------------------+
-    /// |       viewport      |
-    /// +---------------------+
-    /// ```
-    ///
-    /// If more lines are inserted than there is space on the screen, then the top lines will go
-    /// directly into the terminal's scrollback buffer. At the limit, if the viewport takes up the
-    /// whole screen, all lines will be inserted directly into the scrollback buffer.
-    ///
-    /// # Examples
-    ///
-    /// ## Insert a single line before the current viewport
-    ///
-    /// ```rust,ignore
-    /// use ratatui::{
-    ///     backend::TestBackend,
-    ///     style::{Color, Style},
-    ///     text::{Line, Span},
-    ///     widgets::{Paragraph, Widget},
-    ///     Terminal,
-    /// };
-    /// # let backend = TestBackend::new(10, 10);
-    /// # let mut terminal = Terminal::new(backend).unwrap();
-    /// terminal.insert_before(1, |buf| {
-    ///     Paragraph::new(Line::from(vec![
-    ///         Span::raw("This line will be added "),
-    ///         Span::styled("before", Style::default().fg(Color::Blue)),
-    ///         Span::raw(" the current viewport"),
-    ///     ]))
-    ///     .render(buf.area, buf);
-    /// });
-    /// ```
-    pub fn insert_before<F>(&mut self, height: u16, draw_fn: F) -> Result<(), B::Error>
-    where
-        F: FnOnce(&mut Buffer),
-    {
-        match self.viewport {
-            #[cfg(feature = "scrolling-regions")]
-            Viewport::Inline(_) => self.insert_before_scrolling_regions(height, draw_fn),
-            #[cfg(not(feature = "scrolling-regions"))]
-            Viewport::Inline(_) => self.insert_before_no_scrolling_regions(height, draw_fn),
-            _ => Ok(()),
-        }
-    }
-
-    /// Implement `Self::insert_before` using standard backend capabilities.
-    #[cfg(not(feature = "scrolling-regions"))]
-    fn insert_before_no_scrolling_regions(
-        &mut self,
-        height: u16,
-        draw_fn: impl FnOnce(&mut Buffer),
-    ) -> Result<(), B::Error> {
-        // The approach of this function is to first render all of the lines to insert into a
-        // temporary buffer, and then to loop drawing chunks from the buffer to the screen. drawing
-        // this buffer onto the screen.
-        let area = Rect {
-            x: 0,
-            y: 0,
-            width: self.viewport_area.width,
-            height,
-        };
-        let mut buffer = Buffer::empty(area);
-        draw_fn(&mut buffer);
-        let mut buffer = buffer.content.as_slice();
-
-        // Use i32 variables so we don't have worry about overflowed u16s when adding, or about
-        // negative results when subtracting.
-        let mut drawn_height: i32 = self.viewport_area.top().into();
-        let mut buffer_height: i32 = height.into();
-        let viewport_height: i32 = self.viewport_area.height.into();
-        let screen_height: i32 = self.last_known_area.height.into();
-
-        // The algorithm here is to loop, drawing large chunks of text (up to a screen-full at a
-        // time), until the remainder of the buffer plus the viewport fits on the screen. We choose
-        // this loop condition because it guarantees that we can write the remainder of the buffer
-        // with just one call to Self::draw_lines().
-        while buffer_height + viewport_height > screen_height {
-            // We will draw as much of the buffer as possible on this iteration in order to make
-            // forward progress. So we have:
-            //
-            //     to_draw = min(buffer_height, screen_height)
-            //
-            // We may need to scroll the screen up to make room to draw. We choose the minimal
-            // possible scroll amount so we don't end up with the viewport sitting in the middle of
-            // the screen when this function is done. The amount to scroll by is:
-            //
-            //     scroll_up = max(0, drawn_height + to_draw - screen_height)
-            //
-            // We want `scroll_up` to be enough so that, after drawing, we have used the whole
-            // screen (drawn_height - scroll_up + to_draw = screen_height). However, there might
-            // already be enough room on the screen to draw without scrolling (drawn_height +
-            // to_draw <= screen_height). In this case, we just don't scroll at all.
-            let to_draw = buffer_height.min(screen_height);
-            let scroll_up = 0.max(drawn_height + to_draw - screen_height);
-            self.scroll_up(scroll_up as u16)?;
-            buffer = self.draw_lines((drawn_height - scroll_up) as u16, to_draw as u16, buffer)?;
-            drawn_height += to_draw - scroll_up;
-            buffer_height -= to_draw;
-        }
-
-        // There is now enough room on the screen for the remaining buffer plus the viewport,
-        // though we may still need to scroll up some of the existing text first. It's possible
-        // that by this point we've drained the buffer, but we may still need to scroll up to make
-        // room for the viewport.
-        //
-        // We want to scroll up the exact amount that will leave us completely filling the screen.
-        // However, it's possible that the viewport didn't start on the bottom of the screen and
-        // the added lines weren't enough to push it all the way to the bottom. We deal with this
-        // case by just ensuring that our scroll amount is non-negative.
-        //
-        // We want:
-        //   screen_height = drawn_height - scroll_up + buffer_height + viewport_height
-        // Or, equivalently:
-        //   scroll_up = drawn_height + buffer_height + viewport_height - screen_height
-        let scroll_up = 0.max(drawn_height + buffer_height + viewport_height - screen_height);
-        self.scroll_up(scroll_up as u16)?;
-        self.draw_lines(
-            (drawn_height - scroll_up) as u16,
-            buffer_height as u16,
-            buffer,
-        )?;
-        drawn_height += buffer_height - scroll_up;
-
-        self.set_viewport_area(Rect {
-            y: drawn_height as u16,
-            ..self.viewport_area
-        });
-
-        // Clear the viewport off the screen. We didn't clear earlier for two reasons. First, it
-        // wasn't necessary because the buffer we drew out of isn't sparse, so it overwrote
-        // whatever was on the screen. Second, there is a weird bug with tmux where a full screen
-        // clear plus immediate scrolling causes some garbage to go into the scrollback.
-        self.clear()?;
-
-        Ok(())
-    }
-
-    /// Implement `Self::insert_before` using scrolling regions.
-    ///
-    /// If a terminal supports scrolling regions, it means that we can define a subset of rows of
-    /// the screen, and then tell the terminal to scroll up or down just within that region. The
-    /// rows outside of the region are not affected.
-    ///
-    /// This function utilizes this feature to avoid having to redraw the viewport. This is done
-    /// either by splitting the screen at the top of the viewport, and then creating a gap by
-    /// either scrolling the viewport down, or scrolling the area above it up. The lines to insert
-    /// are then drawn into the gap created.
-    #[cfg(feature = "scrolling-regions")]
-    fn insert_before_scrolling_regions(
-        &mut self,
-        mut height: u16,
-        draw_fn: impl FnOnce(&mut Buffer),
-    ) -> Result<(), B::Error> {
-        // The approach of this function is to first render all of the lines to insert into a
-        // temporary buffer, and then to loop drawing chunks from the buffer to the screen. drawing
-        // this buffer onto the screen.
-        let area = Rect {
-            x: 0,
-            y: 0,
-            width: self.viewport_area.width,
-            height,
-        };
-        let mut buffer = Buffer::empty(area);
-        draw_fn(&mut buffer);
-        let mut buffer = buffer.content.as_slice();
-
-        // Handle the special case where the viewport takes up the whole screen.
-        if self.viewport_area.height == self.last_known_area.height {
-            // "Borrow" the top line of the viewport. Draw over it, then immediately scroll it into
-            // scrollback. Do this repeatedly until the whole buffer has been put into scrollback.
-            let mut first = true;
-            while !buffer.is_empty() {
-                buffer = if first {
-                    self.draw_lines(0, 1, buffer)?
-                } else {
-                    self.draw_lines_over_cleared(0, 1, buffer)?
-                };
-                first = false;
-                self.backend.scroll_region_up(0..1, 1)?;
-            }
-
-            // Redraw the top line of the viewport.
-            let width = self.viewport_area.width as usize;
-            let top_line = self.buffers[1 - self.current].content[0..width].to_vec();
-            self.draw_lines_over_cleared(0, 1, &top_line)?;
-            return Ok(());
-        }
-
-        // Handle the case where the viewport isn't yet at the bottom of the screen.
-        {
-            let viewport_top = self.viewport_area.top();
-            let viewport_bottom = self.viewport_area.bottom();
-            let screen_bottom = self.last_known_area.bottom();
-            if viewport_bottom < screen_bottom {
-                let to_draw = height.min(screen_bottom - viewport_bottom);
-                self.backend
-                    .scroll_region_down(viewport_top..viewport_bottom + to_draw, to_draw)?;
-                buffer = self.draw_lines_over_cleared(viewport_top, to_draw, buffer)?;
-                self.set_viewport_area(Rect {
-                    y: viewport_top + to_draw,
-                    ..self.viewport_area
-                });
-                height -= to_draw;
-            }
-        }
-
-        let viewport_top = self.viewport_area.top();
-        while height > 0 {
-            let to_draw = height.min(viewport_top);
-            self.backend.scroll_region_up(0..viewport_top, to_draw)?;
-            buffer = self.draw_lines_over_cleared(viewport_top - to_draw, to_draw, buffer)?;
-            height -= to_draw;
-        }
-
-        Ok(())
-    }
-
-    /// Draw lines at the given vertical offset. The slice of cells must contain enough cells
-    /// for the requested lines. A slice of the unused cells are returned.
-    fn draw_lines<'a>(
-        &mut self,
-        y_offset: u16,
-        lines_to_draw: u16,
-        cells: &'a [Cell],
-    ) -> Result<&'a [Cell], B::Error> {
-        let width: usize = self.last_known_area.width.into();
-        let (to_draw, remainder) = cells.split_at(width * lines_to_draw as usize);
-        if lines_to_draw > 0 {
-            let iter = to_draw
-                .iter()
-                .enumerate()
-                .map(|(i, c)| ((i % width) as u16, y_offset + (i / width) as u16, c));
-            self.backend.draw(iter)?;
-            self.backend.flush()?;
-        }
-        Ok(remainder)
-    }
-
-    /// Draw lines at the given vertical offset, assuming that the lines they are replacing on the
-    /// screen are cleared. The slice of cells must contain enough cells for the requested lines. A
-    /// slice of the unused cells are returned.
-    #[cfg(feature = "scrolling-regions")]
-    fn draw_lines_over_cleared<'a>(
-        &mut self,
-        y_offset: u16,
-        lines_to_draw: u16,
-        cells: &'a [Cell],
-    ) -> Result<&'a [Cell], B::Error> {
-        let width: usize = self.last_known_area.width.into();
-        let (to_draw, remainder) = cells.split_at(width * lines_to_draw as usize);
-        if lines_to_draw > 0 {
-            let area = Rect::new(0, y_offset, width as u16, y_offset + lines_to_draw);
-            let old = Buffer::empty(area);
-            let new = Buffer {
-                area,
-                content: to_draw.to_vec(),
-            };
-            self.backend.draw(old.diff(&new).into_iter())?;
-            self.backend.flush()?;
-        }
-        Ok(remainder)
-    }
-
-    /// Scroll the whole screen up by the given number of lines.
-    #[cfg(not(feature = "scrolling-regions"))]
-    fn scroll_up(&mut self, lines_to_scroll: u16) -> Result<(), B::Error> {
-        if lines_to_scroll > 0 {
-            self.set_cursor_position(Position::new(
-                0,
-                self.last_known_area.height.saturating_sub(1),
-            ))?;
-            self.backend.append_lines(lines_to_scroll)?;
-        }
-        Ok(())
-    }
-}
-
-fn compute_inline_size<B: Backend>(
-    backend: &mut B,
-    height: u16,
-    size: Size,
-    offset_in_previous_viewport: u16,
-) -> Result<(Rect, Position), B::Error> {
-    let pos = backend.get_cursor_position()?;
-    let mut row = pos.y;
-
-    let max_height = size.height.min(height);
-
-    let lines_after_cursor = height
-        .saturating_sub(offset_in_previous_viewport)
-        .saturating_sub(1);
-
-    backend.append_lines(lines_after_cursor)?;
-
-    let available_lines = size.height.saturating_sub(row).saturating_sub(1);
-    let missing_lines = lines_after_cursor.saturating_sub(available_lines);
-    if missing_lines > 0 {
-        row = row.saturating_sub(missing_lines);
-    }
-    row = row.saturating_sub(offset_in_previous_viewport);
-
-    Ok((
-        Rect {
-            x: 0,
-            y: row,
-            width: size.width,
-            height: max_height,
-        },
-        pos,
-    ))
-}

ratatui-core/src/terminal/viewport.rs

@@ -2,31 +2,67 @@ use core::fmt;
 
 use crate::layout::Rect;
 
-/// Represents the viewport of the terminal. The viewport is the area of the terminal that is
-/// currently visible to the user. It can be either fullscreen, inline or fixed.
+/// The area of the terminal that Ratatui draws into.
 ///
-/// When the viewport is fullscreen, the whole terminal is used to draw the application.
+/// A [`Viewport`] controls where widgets render and what [`Frame::area`] returns.
 ///
-/// When the viewport is inline, it is drawn inline with the rest of the terminal. The height of
-/// the viewport is fixed, but the width is the same as the terminal width.
+/// For a higher-level overview of viewports in the context of an application (including
+/// examples), see [`Terminal`].
 ///
-/// When the viewport is fixed, it is drawn in a fixed area of the terminal. The area is specified
-/// by a [`Rect`].
+/// Most applications use [`Viewport::Fullscreen`]. Use [`Viewport::Inline`] when you want to embed
+/// a UI into a larger CLI flow (for example: print some text, then start an interactive UI below
+/// it). Use [`Viewport::Fixed`] when you want Ratatui to render into a specific region of the
+/// terminal.
 ///
-/// See [`Terminal::with_options`] for more information.
+/// In fullscreen mode, the viewport starts at (0, 0). In inline and fixed mode, the viewport may
+/// have a non-zero `x`/`y` origin; prefer using `Frame::area()` as your root layout rectangle.
 ///
+/// See [`Terminal::with_options`] for how to select a viewport, and [`Terminal::resize`] /
+/// [`Terminal::autoresize`] for resize behavior.
+///
+/// [`Frame::area`]: crate::terminal::Frame::area
+/// [`Terminal`]: crate::terminal::Terminal
 /// [`Terminal::with_options`]: crate::terminal::Terminal::with_options
+/// [`Terminal::resize`]: crate::terminal::Terminal::resize
+/// [`Terminal::autoresize`]: crate::terminal::Terminal::autoresize
 #[derive(Debug, Default, Clone, Eq, PartialEq, Hash)]
 pub enum Viewport {
-    /// The viewport is fullscreen
+    /// Draw into the entire terminal.
+    ///
+    /// This is the default viewport used by [`Terminal::new`].
+    ///
+    /// When the terminal size changes, Ratatui automatically resizes internal buffers during
+    /// [`Terminal::draw`].
+    ///
+    /// `Frame::area()` always starts at (0, 0).
+    ///
+    /// [`Terminal::new`]: crate::terminal::Terminal::new
+    /// [`Terminal::draw`]: crate::terminal::Terminal::draw
     #[default]
     Fullscreen,
-    /// The viewport is inline with the rest of the terminal.
+    /// Draw the application inline with the rest of the terminal output.
     ///
-    /// The viewport's height is fixed and specified in number of lines. The width is the same as
-    /// the terminal's width. The viewport is drawn below the cursor position.
+    /// The viewport spans the full terminal width and its top-left corner is anchored to column 0
+    /// of the current cursor row when the terminal is created (and when it is resized). Ratatui
+    /// reserves space for the requested height; if the cursor is near the bottom of the screen,
+    /// this may scroll the terminal so the viewport remains fully visible.
+    ///
+    /// The height is specified in rows and is clamped to the current terminal height.
     Inline(u16),
-    /// The viewport is drawn in a fixed area of the terminal. The area is specified by a [`Rect`].
+    /// Draw into a fixed region of the terminal.
+    ///
+    /// This can be useful when Ratatui is responsible for only part of the screen (for example, a
+    /// status panel beside another renderer), or when you want to manage the overall layout
+    /// yourself.
+    ///
+    /// Fixed viewports are not automatically resized. If the region should change (for example, on
+    /// terminal resize), call [`Terminal::resize`] yourself.
+    ///
+    /// The area is specified as a [`Rect`] in terminal coordinates.
+    ///
+    /// `Frame::area()` returns this rectangle as-is (including its `x`/`y` offset).
+    ///
+    /// [`Terminal::resize`]: crate::terminal::Terminal::resize
     Fixed(Rect),
 }
 

ratatui-core/src/text/line.rs

@@ -803,7 +803,7 @@ fn spans_after_width<'a>(
 /// A trait for converting a value to a [`Line`].
 ///
 /// This trait is automatically implemented for any type that implements the [`Display`] trait. As
-/// such, `ToLine` shouln't be implemented directly: [`Display`] should be implemented instead, and
+/// such, `ToLine` shouldn't be implemented directly: [`Display`] should be implemented instead, and
 /// you get the `ToLine` implementation for free.
 ///
 /// [`Display`]: std::fmt::Display

ratatui-core/src/text/span.rs

@@ -474,7 +474,7 @@ impl Widget for &Span<'_> {
 /// A trait for converting a value to a [`Span`].
 ///
 /// This trait is automatically implemented for any type that implements the [`Display`] trait. As
-/// such, `ToSpan` shouln't be implemented directly: [`Display`] should be implemented instead, and
+/// such, `ToSpan` shouldn't be implemented directly: [`Display`] should be implemented instead, and
 /// you get the `ToSpan` implementation for free.
 ///
 /// [`Display`]: std::fmt::Display

ratatui-core/tests/rect.rs

@@ -72,7 +72,7 @@ fn outer() {
 #[test]
 fn offset() {
     let base = Rect::new(2, 2, 5, 3);
-    let moved = base.offset(Offset { x: 4, y: 2 });
+    let moved = base + Offset::new(4, 2);
 
     let mut buf = Buffer::empty(Rect::new(0, 0, 15, 10));
     Filled { symbol: "░" }.render(base, &mut buf);

ratatui-crossterm/Cargo.toml

@@ -1,8 +1,8 @@
 [package]
 name = "ratatui-crossterm"
-version = "0.1.0-beta.0"
+version = "0.1.0"
 description = "Crossterm backend for the Ratatui Terminal UI library."
-documentation = "https://docs.rs/ratatui-crossterm/"
+documentation = "https://docs.rs/ratatui-crossterm"
 readme = "README.md"
 authors.workspace = true
 repository.workspace = true

ratatui-crossterm/src/lib.rs

@@ -423,6 +423,79 @@ impl IntoCrossterm<CrosstermColor> for Color {
     }
 }
 
+impl IntoCrossterm<ContentStyle> for Style {
+    fn into_crossterm(self) -> ContentStyle {
+        let mut attributes = CrosstermAttributes::default();
+
+        // Add modifiers
+        if self.add_modifier.contains(Modifier::BOLD) {
+            attributes.set(CrosstermAttribute::Bold);
+        }
+        if self.add_modifier.contains(Modifier::DIM) {
+            attributes.set(CrosstermAttribute::Dim);
+        }
+        if self.add_modifier.contains(Modifier::ITALIC) {
+            attributes.set(CrosstermAttribute::Italic);
+        }
+        if self.add_modifier.contains(Modifier::UNDERLINED) {
+            attributes.set(CrosstermAttribute::Underlined);
+        }
+        if self.add_modifier.contains(Modifier::SLOW_BLINK) {
+            attributes.set(CrosstermAttribute::SlowBlink);
+        }
+        if self.add_modifier.contains(Modifier::RAPID_BLINK) {
+            attributes.set(CrosstermAttribute::RapidBlink);
+        }
+        if self.add_modifier.contains(Modifier::REVERSED) {
+            attributes.set(CrosstermAttribute::Reverse);
+        }
+        if self.add_modifier.contains(Modifier::HIDDEN) {
+            attributes.set(CrosstermAttribute::Hidden);
+        }
+        if self.add_modifier.contains(Modifier::CROSSED_OUT) {
+            attributes.set(CrosstermAttribute::CrossedOut);
+        }
+
+        // Sub modifiers (remove modifiers)
+        if self.sub_modifier.contains(Modifier::BOLD) {
+            attributes.set(CrosstermAttribute::NoBold);
+        }
+        if self.sub_modifier.contains(Modifier::DIM) {
+            attributes.set(CrosstermAttribute::NormalIntensity);
+        }
+        if self.sub_modifier.contains(Modifier::ITALIC) {
+            attributes.set(CrosstermAttribute::NoItalic);
+        }
+        if self.sub_modifier.contains(Modifier::UNDERLINED) {
+            attributes.set(CrosstermAttribute::NoUnderline);
+        }
+        if self.sub_modifier.contains(Modifier::SLOW_BLINK)
+            || self.sub_modifier.contains(Modifier::RAPID_BLINK)
+        {
+            attributes.set(CrosstermAttribute::NoBlink);
+        }
+        if self.sub_modifier.contains(Modifier::REVERSED) {
+            attributes.set(CrosstermAttribute::NoReverse);
+        }
+        if self.sub_modifier.contains(Modifier::HIDDEN) {
+            attributes.set(CrosstermAttribute::NoHidden);
+        }
+        if self.sub_modifier.contains(Modifier::CROSSED_OUT) {
+            attributes.set(CrosstermAttribute::NotCrossedOut);
+        }
+
+        ContentStyle {
+            foreground_color: self.fg.map(IntoCrossterm::into_crossterm),
+            background_color: self.bg.map(IntoCrossterm::into_crossterm),
+            #[cfg(feature = "underline-color")]
+            underline_color: self.underline_color.map(IntoCrossterm::into_crossterm),
+            #[cfg(not(feature = "underline-color"))]
+            underline_color: None,
+            attributes,
+        }
+    }
+}
+
 impl FromCrossterm<CrosstermColor> for Color {
     fn from_crossterm(value: CrosstermColor) -> Self {
         match value {
@@ -876,4 +949,176 @@ mod tests {
             Style::default().underline_color(Color::Red)
         );
     }
+
+    #[rstest]
+    #[case(Style::default(), ContentStyle::default())]
+    #[case(
+        Style::default().fg(Color::Yellow),
+        ContentStyle {
+            foreground_color: Some(CrosstermColor::DarkYellow),
+            ..Default::default()
+        }
+    )]
+    #[case(
+        Style::default().bg(Color::Yellow),
+        ContentStyle {
+            background_color: Some(CrosstermColor::DarkYellow),
+            ..Default::default()
+        }
+    )]
+    #[case(
+        Style::default().add_modifier(Modifier::BOLD),
+        ContentStyle {
+            attributes: CrosstermAttributes::from(CrosstermAttribute::Bold),
+            ..Default::default()
+        }
+    )]
+    #[case(
+        Style::default().remove_modifier(Modifier::BOLD),
+        ContentStyle {
+            attributes: CrosstermAttributes::from(CrosstermAttribute::NoBold),
+            ..Default::default()
+        }
+    )]
+    #[case(
+        Style::default().add_modifier(Modifier::ITALIC),
+        ContentStyle {
+            attributes: CrosstermAttributes::from(CrosstermAttribute::Italic),
+            ..Default::default()
+        }
+    )]
+    #[case(
+        Style::default().remove_modifier(Modifier::ITALIC),
+        ContentStyle {
+            attributes: CrosstermAttributes::from(CrosstermAttribute::NoItalic),
+            ..Default::default()
+        }
+    )]
+    #[case(
+        Style::default().add_modifier(Modifier::UNDERLINED),
+        ContentStyle {
+            attributes: CrosstermAttributes::from(CrosstermAttribute::Underlined),
+            ..Default::default()
+        }
+    )]
+    #[case(
+        Style::default().remove_modifier(Modifier::UNDERLINED),
+        ContentStyle {
+            attributes: CrosstermAttributes::from(CrosstermAttribute::NoUnderline),
+            ..Default::default()
+        }
+    )]
+    #[case(
+        Style::default().add_modifier(Modifier::DIM),
+        ContentStyle {
+            attributes: CrosstermAttributes::from(CrosstermAttribute::Dim),
+            ..Default::default()
+        }
+    )]
+    #[case(
+        Style::default().remove_modifier(Modifier::DIM),
+        ContentStyle {
+            attributes: CrosstermAttributes::from(CrosstermAttribute::NormalIntensity),
+            ..Default::default()
+        }
+    )]
+    #[case(
+        Style::default().add_modifier(Modifier::SLOW_BLINK),
+        ContentStyle {
+            attributes: CrosstermAttributes::from(CrosstermAttribute::SlowBlink),
+            ..Default::default()
+        }
+    )]
+    #[case(
+        Style::default().add_modifier(Modifier::RAPID_BLINK),
+        ContentStyle {
+            attributes: CrosstermAttributes::from(CrosstermAttribute::RapidBlink),
+            ..Default::default()
+        }
+    )]
+    #[case(
+        Style::default().remove_modifier(Modifier::SLOW_BLINK),
+        ContentStyle {
+            attributes: CrosstermAttributes::from(CrosstermAttribute::NoBlink),
+            ..Default::default()
+        }
+    )]
+    #[case(
+        Style::default().add_modifier(Modifier::REVERSED),
+        ContentStyle {
+            attributes: CrosstermAttributes::from(CrosstermAttribute::Reverse),
+            ..Default::default()
+        }
+    )]
+    #[case(
+        Style::default().remove_modifier(Modifier::REVERSED),
+        ContentStyle {
+            attributes: CrosstermAttributes::from(CrosstermAttribute::NoReverse),
+            ..Default::default()
+        }
+    )]
+    #[case(
+        Style::default().add_modifier(Modifier::HIDDEN),
+        ContentStyle {
+            attributes: CrosstermAttributes::from(CrosstermAttribute::Hidden),
+            ..Default::default()
+        }
+    )]
+    #[case(
+        Style::default().remove_modifier(Modifier::HIDDEN),
+        ContentStyle {
+            attributes: CrosstermAttributes::from(CrosstermAttribute::NoHidden),
+            ..Default::default()
+        }
+    )]
+    #[case(
+        Style::default().add_modifier(Modifier::CROSSED_OUT),
+        ContentStyle {
+            attributes: CrosstermAttributes::from(CrosstermAttribute::CrossedOut),
+            ..Default::default()
+        }
+    )]
+    #[case(
+        Style::default().remove_modifier(Modifier::CROSSED_OUT),
+        ContentStyle {
+            attributes: CrosstermAttributes::from(CrosstermAttribute::NotCrossedOut),
+            ..Default::default()
+        }
+    )]
+    #[case(
+        Style::default()
+            .add_modifier(Modifier::BOLD)
+            .add_modifier(Modifier::ITALIC),
+        ContentStyle {
+            attributes: CrosstermAttributes::from(
+                [CrosstermAttribute::Bold, CrosstermAttribute::Italic].as_ref()
+            ),
+            ..Default::default()
+        }
+    )]
+    #[case(
+        Style::default()
+            .remove_modifier(Modifier::BOLD)
+            .remove_modifier(Modifier::ITALIC),
+        ContentStyle {
+            attributes: CrosstermAttributes::from(
+                [CrosstermAttribute::NoBold, CrosstermAttribute::NoItalic].as_ref()
+            ),
+            ..Default::default()
+        }
+    )]
+    fn into_crossterm_content_style(#[case] style: Style, #[case] content_style: ContentStyle) {
+        assert_eq!(style.into_crossterm(), content_style);
+    }
+
+    #[test]
+    #[cfg(feature = "underline-color")]
+    fn into_crossterm_content_style_underline() {
+        let style = Style::default().underline_color(Color::Red);
+        let content_style = ContentStyle {
+            underline_color: Some(CrosstermColor::DarkRed),
+            ..Default::default()
+        };
+        assert_eq!(style.into_crossterm(), content_style);
+    }
 }

ratatui-macros/Cargo.toml

@@ -1,9 +1,9 @@
 [package]
 name = "ratatui-macros"
-version = "0.7.0-beta.0"
+version = "0.7.0"
+description = "Macros for Ratatui"
 edition.workspace = true
 authors = ["The Ratatui Developers"]
-description = "Macros for Ratatui"
 license = "MIT"
 repository = "https://github.com/ratatui/ratatui"
 documentation = "https://docs.rs/ratatui-macros"

ratatui-termion/Cargo.toml

@@ -1,8 +1,8 @@
 [package]
 name = "ratatui-termion"
-version = "0.1.0-beta.0"
+version = "0.1.0"
 description = "Termion backend for the Ratatui Terminal UI library."
-documentation = "https://docs.rs/ratatui-termion/"
+documentation = "https://docs.rs/ratatui-termion"
 readme = "README.md"
 authors.workspace = true
 repository.workspace = true

ratatui-termwiz/Cargo.toml

@@ -1,8 +1,8 @@
 [package]
 name = "ratatui-termwiz"
-version = "0.1.0-beta.0"
+version = "0.1.0"
 description = "Termwiz backend for the Ratatui Terminal UI library."
-documentation = "https://docs.rs/ratatui-termwiz/"
+documentation = "https://docs.rs/ratatui-termwiz"
 readme = "README.md"
 authors.workspace = true
 repository.workspace = true

ratatui-widgets/Cargo.toml

@@ -1,12 +1,12 @@
 [package]
 name = "ratatui-widgets"
-description = "A collection of Ratatui widgets for building terminal user interfaces using Ratatui."
 # Note that this started at 0.3.0 as there was a previous crate using the name `ratatui-widgets`.
 # <https://github.com/joshka/ratatui-widgets/issues/46>
-version = "0.3.0-beta.0"
+version = "0.3.0"
+description = "A collection of Ratatui widgets for building terminal user interfaces using Ratatui."
+documentation = "https://docs.rs/ratatui-widgets"
 readme = "README.md"
 authors.workspace = true
-documentation.workspace = true
 repository.workspace = true
 homepage.workspace = true
 keywords.workspace = true
@@ -18,7 +18,6 @@ rust-version.workspace = true
 
 [package.metadata.docs.rs]
 all-features = true
-cargo-args = ["-Zunstable-options", "-Zrustdoc-scrape-examples"]
 rustdoc-args = ["--cfg", "docsrs"]
 
 [features]
@@ -73,8 +72,3 @@ rstest.workspace = true
 
 [lints]
 workspace = true
-
-# Adding a single example is enough for activating rustdoc-scrape-examples
-[[example]]
-name = "barchart"
-doc-scrape-examples = true

ratatui-widgets/examples/tabs.rs

@@ -53,7 +53,7 @@ fn render(frame: &mut Frame, selected_tab: usize) {
     frame.render_widget(title.centered(), top);
 
     render_content(frame, main, selected_tab);
-    render_tabs(frame, main.offset(Offset { x: 1, y: 0 }), selected_tab);
+    render_tabs(frame, main + Offset::new(1, 0), selected_tab);
 }
 
 /// Render the tabs.

ratatui-widgets/src/as_ref.rs

@@ -0,0 +1,111 @@
+/// Implement `AsRef<Self>` for widget types to enable `as_ref()` in generic contexts.
+///
+/// This keeps widget rendering ergonomic when APIs accept `AsRef<WidgetType>` bounds, avoiding
+/// the need for `(&widget).render(...)` just to satisfy a trait bound.
+///
+/// # Example
+///
+/// ```rust
+/// use ratatui_widgets::block::Block;
+///
+/// let block = Block::default();
+/// let block_ref: &Block<'_> = block.as_ref();
+/// ```
+///
+/// # Generated impls
+///
+/// ```rust,ignore
+/// // Non-generic widgets (e.g. Clear, RatatuiLogo).
+/// impl AsRef<Clear> for Clear {
+///     fn as_ref(&self) -> &Clear {
+///         self
+///     }
+/// }
+///
+/// // Generic widgets (e.g. Block with a lifetime, Canvas with a lifetime + type parameter).
+/// impl<'a> AsRef<Block<'a>> for Block<'a> {
+///     fn as_ref(&self) -> &Block<'a> {
+///         self
+///     }
+/// }
+///
+/// impl<'a, F> AsRef<Canvas<'a, F>> for Canvas<'a, F>
+/// where
+///     F: Fn(&mut Context),
+/// {
+///     fn as_ref(&self) -> &Canvas<'a, F> {
+///         self
+///     }
+/// }
+/// ```
+macro_rules! impl_as_ref {
+    ($type:ty, <$($gen:tt),+> $(where $($bounds:tt)+)?) => {
+        impl<$($gen),+> AsRef<$type> for $type $(where $($bounds)+)? {
+            fn as_ref(&self) -> &$type {
+                self
+            }
+        }
+    };
+    ($type:ty) => {
+        impl AsRef<$type> for $type {
+            fn as_ref(&self) -> &$type {
+                self
+            }
+        }
+    };
+}
+
+impl_as_ref!(crate::barchart::BarChart<'a>, <'a>);
+impl_as_ref!(crate::block::Block<'a>, <'a>);
+impl_as_ref!(crate::canvas::Canvas<'a, F>, <'a, F> where F: Fn(&mut crate::canvas::Context));
+impl_as_ref!(crate::chart::Chart<'a>, <'a>);
+impl_as_ref!(crate::clear::Clear);
+impl_as_ref!(crate::gauge::Gauge<'a>, <'a>);
+impl_as_ref!(crate::gauge::LineGauge<'a>, <'a>);
+impl_as_ref!(crate::list::List<'a>, <'a>);
+impl_as_ref!(crate::logo::RatatuiLogo);
+impl_as_ref!(crate::mascot::RatatuiMascot);
+impl_as_ref!(crate::paragraph::Paragraph<'a>, <'a>);
+impl_as_ref!(crate::scrollbar::Scrollbar<'a>, <'a>);
+impl_as_ref!(crate::sparkline::Sparkline<'a>, <'a>);
+impl_as_ref!(crate::table::Table<'a>, <'a>);
+impl_as_ref!(crate::tabs::Tabs<'a>, <'a>);
+#[cfg(feature = "calendar")]
+impl_as_ref!(
+    crate::calendar::Monthly<'a, DS>,
+    <'a, DS> where DS: crate::calendar::DateStyler
+);
+
+#[cfg(test)]
+mod tests {
+    use alloc::vec;
+
+    #[test]
+    fn widgets_implement_as_ref() {
+        let _ = crate::barchart::BarChart::default().as_ref();
+        let _ = crate::block::Block::new().as_ref();
+        let _ = crate::canvas::Canvas::default().paint(|_| {}).as_ref();
+        let _ = crate::chart::Chart::new(vec![]).as_ref();
+        let _ = crate::clear::Clear.as_ref();
+        let _ = crate::gauge::Gauge::default().as_ref();
+        let _ = crate::gauge::LineGauge::default().as_ref();
+        let _ = crate::list::List::new(["foo"]).as_ref();
+        let _ = crate::logo::RatatuiLogo::default().as_ref();
+        let _ = crate::mascot::RatatuiMascot::default().as_ref();
+        let _ = crate::paragraph::Paragraph::new("").as_ref();
+        let _ = crate::scrollbar::Scrollbar::default().as_ref();
+        let _ = crate::sparkline::Sparkline::default().as_ref();
+        let _ = crate::table::Table::default().as_ref();
+        let _ = crate::tabs::Tabs::default().as_ref();
+    }
+
+    #[cfg(feature = "calendar")]
+    #[test]
+    fn calendar_widget_implements_as_ref() {
+        use time::{Date, Month};
+
+        let date = Date::from_calendar_date(2024, Month::January, 1).unwrap();
+        let _ = crate::calendar::Monthly::new(date, crate::calendar::CalendarEventStore::default())
+            .as_ref();
+    }
+}

ratatui-widgets/src/block.rs

@@ -1951,18 +1951,18 @@ mod tests {
         let mut offset = Offset::ZERO;
         for (border_type_1, border_type_2) in iproduct!(border_types, border_types) {
             let title = format!("{border_type_1} + {border_type_2}");
-            let title_area = Rect::new(0, 0, 43, 1).offset(offset);
+            let title_area = Rect::new(0, 0, 43, 1) + offset;
             title.render(title_area, &mut buffer);
             offset.y += 1;
             for (rect_1, rect_2) in rects {
                 Block::bordered()
                     .border_type(border_type_1)
                     .merge_borders(strategy)
-                    .render(rect_1.offset(offset), &mut buffer);
+                    .render(rect_1 + offset, &mut buffer);
                 Block::bordered()
                     .border_type(border_type_2)
                     .merge_borders(strategy)
-                    .render(rect_2.offset(offset), &mut buffer);
+                    .render(rect_2 + offset, &mut buffer);
             }
             offset.y += 9;
         }

ratatui-widgets/src/calendar.rs

@@ -104,6 +104,36 @@ impl<'a, DS: DateStyler> Monthly<'a, DS> {
         self
     }
 
+    /// Return the width required to render the calendar.
+    #[must_use]
+    pub fn width(&self) -> u16 {
+        const DAYS_PER_WEEK: u16 = 7;
+        const GUTTER_WIDTH: u16 = 1;
+        const DAY_WIDTH: u16 = 2;
+
+        let mut width = DAYS_PER_WEEK * (GUTTER_WIDTH + DAY_WIDTH);
+        if let Some(block) = &self.block {
+            let (left, right) = block.horizontal_space();
+            width = width.saturating_add(left).saturating_add(right);
+        }
+        width
+    }
+
+    /// Return the height required to render the calendar.
+    #[must_use]
+    pub fn height(&self) -> u16 {
+        let mut height = u16::from(sunday_based_weeks(self.display_date))
+            .saturating_add(u16::from(self.show_month.is_some()))
+            .saturating_add(u16::from(self.show_weekday.is_some()));
+
+        if let Some(block) = &self.block {
+            let (top, bottom) = block.vertical_space();
+            height = height.saturating_add(top).saturating_add(bottom);
+        }
+
+        height
+    }
+
     /// Return a style with only the background from the default style
     const fn default_bg(&self) -> Style {
         match self.default_style.bg {
@@ -200,6 +230,22 @@ impl<DS: DateStyler> Monthly<'_, DS> {
     }
 }
 
+/// Compute how many Sunday-based week rows are needed to render `display_date`.
+///
+/// Mirrors the rendering logic by taking the difference between the first and last day
+/// Sunday-based week numbers (inclusive).
+fn sunday_based_weeks(display_date: Date) -> u8 {
+    let first_of_month = display_date
+        .replace_day(1)
+        .expect("valid first day of month");
+    let last_of_month = first_of_month
+        .replace_day(first_of_month.month().length(first_of_month.year()))
+        .expect("valid last of month");
+    let first_week = first_of_month.sunday_based_week();
+    let last_week = last_of_month.sunday_based_week();
+    last_week.saturating_sub(first_week) + 1
+}
+
 /// Provides a method for styling a given date. [Monthly] is generic on this trait, so any type
 /// that implements this trait can be used.
 pub trait DateStyler {
@@ -268,10 +314,11 @@ impl Default for CalendarEventStore {
 
 #[cfg(test)]
 mod tests {
-    use ratatui_core::style::Color;
+    use ratatui_core::style::{Color, Style};
     use time::Month;
 
     use super::*;
+    use crate::block::{Block, Padding};
 
     #[test]
     fn event_store() {
@@ -325,4 +372,87 @@ mod tests {
         // This should not panic, even if the buffer has zero size.
         calendar.render(buffer.area, &mut buffer);
     }
+
+    #[test]
+    fn calendar_width_reflects_grid_layout() {
+        let date = Date::from_calendar_date(2023, Month::January, 1).unwrap();
+        let calendar = Monthly::new(date, CalendarEventStore::default());
+        assert_eq!(calendar.width(), 21);
+    }
+
+    #[test]
+    fn calendar_height_counts_weeks_and_headers() {
+        let date = Date::from_calendar_date(2015, Month::February, 1).unwrap();
+        let base_calendar = Monthly::new(date, CalendarEventStore::default());
+        assert_eq!(base_calendar.height(), 4);
+
+        let decorated_calendar = Monthly::new(date, CalendarEventStore::default())
+            .show_month_header(Style::default())
+            .show_weekdays_header(Style::default());
+        assert_eq!(decorated_calendar.height(), 6);
+    }
+
+    #[test]
+    fn calendar_dimensions_examples() {
+        // Feb 2015 starts Sunday and spans 4 rows.
+        let feb_2015 = Date::from_calendar_date(2015, Month::February, 1).unwrap();
+        let cal = Monthly::new(feb_2015, CalendarEventStore::default());
+        assert_eq!(cal.width(), 21, "4w base width");
+        assert_eq!(cal.height(), 4, "Feb 2015 rows");
+
+        let cal = Monthly::new(feb_2015, CalendarEventStore::default())
+            .show_month_header(Style::default())
+            .show_weekdays_header(Style::default());
+        assert_eq!(cal.height(), 6, "Headers add 2 rows");
+
+        let block = Block::bordered().padding(Padding::new(2, 3, 1, 2));
+        let cal = Monthly::new(feb_2015, CalendarEventStore::default()).block(block);
+        assert_eq!(cal.width(), 28, "Padding widens width");
+        assert_eq!(cal.height(), 9, "Padding grows height");
+
+        // Feb 2024 starts Thursday and spans 5 rows.
+        let feb_2024 = Date::from_calendar_date(2024, Month::February, 1).unwrap();
+        let cal = Monthly::new(feb_2024, CalendarEventStore::default());
+        assert_eq!(cal.width(), 21, "5w base width");
+        assert_eq!(cal.height(), 5, "Feb 2024 rows");
+
+        let cal = Monthly::new(feb_2024, CalendarEventStore::default())
+            .show_month_header(Style::default())
+            .show_weekdays_header(Style::default());
+        assert_eq!(cal.height(), 7, "Headers add 2 rows (5w)");
+
+        let cal = Monthly::new(feb_2024, CalendarEventStore::default()).block(Block::bordered());
+        assert_eq!(cal.width(), 23, "Border adds 2 cols");
+        assert_eq!(cal.height(), 7, "Border adds 2 rows");
+
+        // Apr 2023 starts Saturday and spans 6 rows.
+        let apr_2023 = Date::from_calendar_date(2023, Month::April, 1).unwrap();
+        let cal = Monthly::new(apr_2023, CalendarEventStore::default());
+        assert_eq!(cal.width(), 21, "6w base width");
+        assert_eq!(cal.height(), 6, "Apr 2023 rows");
+
+        let cal = Monthly::new(apr_2023, CalendarEventStore::default())
+            .show_month_header(Style::default())
+            .show_weekdays_header(Style::default());
+        assert_eq!(cal.height(), 8, "Headers add 2 rows (6w)");
+
+        let block = Block::bordered().padding(Padding::symmetric(1, 1));
+        let cal = Monthly::new(apr_2023, CalendarEventStore::default()).block(block);
+        assert_eq!(cal.width(), 25, "Symmetric padding width");
+        assert_eq!(cal.height(), 10, "Symmetric padding height");
+    }
+
+    #[test]
+    fn sunday_based_weeks_shapes() {
+        let sunday_start =
+            Date::from_calendar_date(2015, Month::February, 11).expect("valid test date");
+        let saturday_start =
+            Date::from_calendar_date(2023, Month::April, 9).expect("valid test date");
+        let leap_year =
+            Date::from_calendar_date(2024, Month::February, 29).expect("valid test date");
+
+        assert_eq!(sunday_based_weeks(sunday_start), 4);
+        assert_eq!(sunday_based_weeks(saturday_start), 6);
+        assert_eq!(sunday_based_weeks(leap_year), 5);
+    }
 }

ratatui-widgets/src/canvas.rs

@@ -14,7 +14,6 @@
 //! You can also implement your own custom [`Shape`]s.
 
 use alloc::boxed::Box;
-use alloc::string::String;
 use alloc::vec;
 use alloc::vec::Vec;
 use core::fmt;
@@ -24,6 +23,8 @@ use itertools::Itertools;
 use ratatui_core::buffer::Buffer;
 use ratatui_core::layout::Rect;
 use ratatui_core::style::{Color, Style};
+use ratatui_core::symbols::braille::BRAILLE;
+use ratatui_core::symbols::pixel::{OCTANTS, QUADRANTS, SEXTANTS};
 use ratatui_core::symbols::{self, Marker};
 use ratatui_core::text::Line as TextLine;
 use ratatui_core::widgets::Widget;
@@ -69,11 +70,20 @@ pub struct Label<'a> {
 /// multiple shapes on the canvas in specific order.
 #[derive(Debug)]
 struct Layer {
-    // A string of characters representing the grid. This will be wrapped to the width of the grid
-    // when rendering
-    string: String,
-    // Colors for foreground and background of each cell
-    colors: Vec<(Color, Color)>,
+    contents: Vec<LayerCell>,
+}
+
+/// A cell within a layer.
+///
+/// If a [`Context`] contains multiple layers, then the symbol, foreground, and background colors
+/// for a character will be determined by the top-most layer that provides a value for that
+/// character. For example, a chart drawn with [`Marker::Block`] may provide the background color,
+/// and a later chart drawn with [`Marker::Braille`] may provide the symbol and foreground color.
+#[derive(Debug)]
+struct LayerCell {
+    symbol: Option<char>,
+    fg: Option<Color>,
+    bg: Option<Color>,
 }
 
 /// A grid of cells that can be painted on.
@@ -100,73 +110,111 @@ trait Grid: fmt::Debug {
     fn reset(&mut self);
 }
 
-/// The `BrailleGrid` is a grid made up of cells each containing a Braille pattern.
+/// The pattern and color of a `PatternGrid` cell.
+#[derive(Copy, Clone, Debug, Default)]
+struct PatternCell {
+    /// The pattern of a grid character.
+    ///
+    /// The pattern is stored in the lower bits in a row-major order. For instance, for a 2x4
+    /// pattern marker, bits 0 to 7 of this field should represent the following pseudo-pixels:
+    ///
+    /// | 0 1 |
+    /// | 2 3 |
+    /// | 4 5 |
+    /// | 6 7 |
+    pattern: u8,
+    /// The color of a cell only supports foreground colors for now as there's no way to
+    /// individually set the background color of each pseudo-pixel in a pattern character.
+    color: Option<Color>,
+}
+
+/// The `PatternGrid` is a grid made up of cells each containing a `W`x`H` pattern character.
 ///
-/// This makes it possible to draw shapes with a resolution of 2x4 dots per cell. This is useful
-/// when you want to draw shapes with a high resolution. Font support for Braille patterns is
-/// required to see the dots. If your terminal or font does not support this unicode block, you
-/// will see unicode replacement characters (<28>) instead of braille dots.
+/// This makes it possible to draw shapes with a resolution of e.g. 2x4 (Braille or unicode octant)
+/// per cell.
+/// Font support for the relevant pattern character is required. If your terminal or font does not
+/// support the relevant unicode block, you will see unicode replacement characters (<28>) instead.
 ///
-/// This grid type only supports a single foreground color for each 2x4 dots cell. There is no way
-/// to set the individual color of each dot in the braille pattern.
+/// This grid type only supports a single foreground color for each `W`x`H` pattern character.
+/// There is no way to set the individual color of each pseudo-pixel.
 #[derive(Debug)]
-struct BrailleGrid {
+struct PatternGrid<const W: usize, const H: usize> {
     /// Width of the grid in number of terminal columns
     width: u16,
     /// Height of the grid in number of terminal rows
     height: u16,
-    /// Represents the unicode braille patterns. Will take a value between `0x2800` and `0x28FF`
-    /// this is converted to an utf16 string when converting to a layer. See
-    /// <https://en.wikipedia.org/wiki/Braille_Patterns> for more info.
-    utf16_code_points: Vec<u16>,
-    /// The color of each cell only supports foreground colors for now as there's no way to
-    /// individually set the background color of each dot in the braille pattern.
-    colors: Vec<Color>,
+    /// Pattern and color of the cells.
+    cells: Vec<PatternCell>,
+    /// Lookup table mapping patterns to characters.
+    char_table: &'static [char],
 }
 
-impl BrailleGrid {
-    /// Create a new `BrailleGrid` with the given width and height measured in terminal columns and
-    /// rows respectively.
-    fn new(width: u16, height: u16) -> Self {
+impl<const W: usize, const H: usize> PatternGrid<W, H> {
+    /// Statically check that the dimension of the pattern is supported.
+    const _PATTERN_DIMENSION_CHECK: usize = u8::BITS as usize - W * H;
+
+    /// Create a new `PatternGrid` with the given width and height measured in terminal columns
+    /// and rows respectively.
+    fn new(width: u16, height: u16, char_table: &'static [char]) -> Self {
+        // Cause a static error if the pattern doesn't fit within 8 bits.
+        let _ = Self::_PATTERN_DIMENSION_CHECK;
+
         let length = usize::from(width) * usize::from(height);
         Self {
             width,
             height,
-            utf16_code_points: vec![symbols::braille::BLANK; length],
-            colors: vec![Color::Reset; length],
+            cells: vec![PatternCell::default(); length],
+            char_table,
         }
     }
 }
 
-impl Grid for BrailleGrid {
+impl<const W: usize, const H: usize> Grid for PatternGrid<W, H> {
     fn resolution(&self) -> (f64, f64) {
-        (f64::from(self.width) * 2.0, f64::from(self.height) * 4.0)
+        (
+            f64::from(self.width) * W as f64,
+            f64::from(self.height) * H as f64,
+        )
     }
 
     fn save(&self) -> Layer {
-        let string = String::from_utf16(&self.utf16_code_points).unwrap();
-        // the background color is always reset for braille patterns
-        let colors = self.colors.iter().map(|c| (*c, Color::Reset)).collect();
-        Layer { string, colors }
+        let contents = self
+            .cells
+            .iter()
+            .map(|&cell| {
+                let symbol = match cell.pattern {
+                    // Skip rendering blank patterns to allow layers underneath
+                    // to show through.
+                    0 => None,
+                    idx => Some(self.char_table[idx as usize]),
+                };
+
+                LayerCell {
+                    symbol,
+                    fg: cell.color,
+                    // Patterns only affect foreground.
+                    bg: None,
+                }
+            })
+            .collect();
+
+        Layer { contents }
     }
 
     fn reset(&mut self) {
-        self.utf16_code_points.fill(symbols::braille::BLANK);
-        self.colors.fill(Color::Reset);
+        self.cells.fill_with(Default::default);
     }
 
     fn paint(&mut self, x: usize, y: usize, color: Color) {
         let index = y
-            .saturating_div(4)
+            .saturating_div(H)
             .saturating_mul(self.width as usize)
-            .saturating_add(x.saturating_div(2));
+            .saturating_add(x.saturating_div(W));
         // using get_mut here because we are indexing the vector with usize values
         // and we want to make sure we don't panic if the index is out of bounds
-        if let Some(c) = self.utf16_code_points.get_mut(index) {
-            *c |= symbols::braille::DOTS[y % 4][x % 2];
-        }
-        if let Some(c) = self.colors.get_mut(index) {
-            *c = color;
+        if let Some(cell) = self.cells.get_mut(index) {
+            cell.pattern |= 1u8 << ((x % W) + W * (y % H));
+            cell.color = Some(color);
         }
     }
 }
@@ -181,12 +229,16 @@ struct CharGrid {
     width: u16,
     /// Height of the grid in number of terminal rows
     height: u16,
-    /// Represents a single character for each cell
-    cells: Vec<char>,
     /// The color of each cell
-    colors: Vec<Color>,
+    cells: Vec<Option<Color>>,
+
     /// The character to use for every cell - e.g. a block, dot, etc.
     cell_char: char,
+
+    /// If true, apply the color to the background as well as the foreground. This is used for
+    /// [`Marker::Block`], so that it will overwrite any previous foreground character, but also
+    /// leave a background that can be overlaid with an additional foreground character.
+    apply_color_to_bg: bool,
 }
 
 impl CharGrid {
@@ -197,9 +249,16 @@ impl CharGrid {
         Self {
             width,
             height,
-            cells: vec![' '; length],
-            colors: vec![Color::Reset; length],
+            cells: vec![None; length],
             cell_char,
+            apply_color_to_bg: false,
+        }
+    }
+
+    fn apply_color_to_bg(self) -> Self {
+        Self {
+            apply_color_to_bg: true,
+            ..self
         }
     }
 }
@@ -211,14 +270,20 @@ impl Grid for CharGrid {
 
     fn save(&self) -> Layer {
         Layer {
-            string: self.cells.iter().collect(),
-            colors: self.colors.iter().map(|c| (*c, Color::Reset)).collect(),
+            contents: self
+                .cells
+                .iter()
+                .map(|&color| LayerCell {
+                    symbol: color.map(|_| self.cell_char),
+                    fg: color,
+                    bg: color.filter(|_| self.apply_color_to_bg),
+                })
+                .collect(),
         }
     }
 
     fn reset(&mut self) {
-        self.cells.fill(' ');
-        self.colors.fill(Color::Reset);
+        self.cells.fill(None);
     }
 
     fn paint(&mut self, x: usize, y: usize, color: Color) {
@@ -226,10 +291,7 @@ impl Grid for CharGrid {
         // using get_mut here because we are indexing the vector with usize values
         // and we want to make sure we don't panic if the index is out of bounds
         if let Some(c) = self.cells.get_mut(index) {
-            *c = self.cell_char;
-        }
-        if let Some(c) = self.colors.get_mut(index) {
-            *c = color;
+            *c = Some(color);
         }
     }
 }
@@ -244,7 +306,7 @@ impl Grid for CharGrid {
 /// and lower half of each cell. This allows us to draw shapes with a resolution of 1x2 "pixels" per
 /// cell.
 ///
-/// This allows for more flexibility than the `BrailleGrid` which only supports a single
+/// This allows for more flexibility than the `PatternGrid` which only supports a single
 /// foreground color for each 2x4 dots cell, and the `CharGrid` which only supports a single
 /// character for each cell.
 #[derive(Debug)]
@@ -254,7 +316,7 @@ struct HalfBlockGrid {
     /// Height of the grid in number of terminal rows
     height: u16,
     /// Represents a single color for each "pixel" arranged in column, row order
-    pixels: Vec<Vec<Color>>,
+    pixels: Vec<Vec<Option<Color>>>,
 }
 
 impl HalfBlockGrid {
@@ -264,7 +326,7 @@ impl HalfBlockGrid {
         Self {
             width,
             height,
-            pixels: vec![vec![Color::Reset; width as usize]; (height as usize) * 2],
+            pixels: vec![vec![None; width as usize]; (height as usize) * 2],
         }
     }
 }
@@ -302,45 +364,34 @@ impl Grid for HalfBlockGrid {
             .tuples()
             .flat_map(|(upper_row, lower_row)| zip(upper_row, lower_row));
 
-        // then we work out what character to print for each pair of pixels
-        let string = vertical_color_pairs
-            .clone()
-            .map(|(upper, lower)| match (upper, lower) {
-                (Color::Reset, Color::Reset) => ' ',
-                (Color::Reset, _) => symbols::half_block::LOWER,
-                (_, Color::Reset) => symbols::half_block::UPPER,
-                (&lower, &upper) => {
-                    if lower == upper {
-                        symbols::half_block::FULL
-                    } else {
-                        symbols::half_block::UPPER
-                    }
-                }
-            })
-            .collect();
-
-        // then we convert these each vertical pair of pixels into a foreground and background color
-        let colors = vertical_color_pairs
+        // Then we determine the character to print for each pair, along with the color of the
+        // foreground and background.
+        let contents = vertical_color_pairs
             .map(|(upper, lower)| {
-                let (fg, bg) = match (upper, lower) {
-                    (Color::Reset, Color::Reset) => (Color::Reset, Color::Reset),
-                    (Color::Reset, &lower) => (lower, Color::Reset),
-                    (&upper, Color::Reset) => (upper, Color::Reset),
-                    (&upper, &lower) => (upper, lower),
+                let (symbol, fg, bg) = match (upper, lower) {
+                    (None, None) => (None, None, None),
+                    (None, Some(lower)) => (Some(symbols::half_block::LOWER), Some(*lower), None),
+                    (Some(upper), None) => (Some(symbols::half_block::UPPER), Some(*upper), None),
+                    (Some(upper), Some(lower)) if lower == upper => {
+                        (Some(symbols::half_block::FULL), Some(*upper), Some(*lower))
+                    }
+                    (Some(upper), Some(lower)) => {
+                        (Some(symbols::half_block::UPPER), Some(*upper), Some(*lower))
+                    }
                 };
-                (fg, bg)
+                LayerCell { symbol, fg, bg }
             })
             .collect();
 
-        Layer { string, colors }
+        Layer { contents }
     }
 
     fn reset(&mut self) {
-        self.pixels.fill(vec![Color::Reset; self.width as usize]);
+        self.pixels.fill(vec![None; self.width as usize]);
     }
 
     fn paint(&mut self, x: usize, y: usize, color: Color) {
-        self.pixels[y][x] = color;
+        self.pixels[y][x] = Some(color);
     }
 }
 
@@ -462,7 +513,17 @@ impl<'a, 'b> From<&'a mut Context<'b>> for Painter<'a, 'b> {
 /// this as similar to the `Frame` struct that is used to draw widgets on the terminal.
 #[derive(Debug)]
 pub struct Context<'a> {
+    // Width of the canvas in cells.
+    //
+    // This is NOT the resolution in dots/pixels as this varies by marker type.
+    width: u16,
+    // Height of the canvas in cells.
+    //
+    // This is NOT the resolution in dots/pixels as this varies by marker type.
+    height: u16,
+    // Canvas coordinate system width
     x_bounds: [f64; 2],
+    // Canvas coordinate system height
     y_bounds: [f64; 2],
     grid: Box<dyn Grid>,
     dirty: bool,
@@ -501,17 +562,10 @@ impl<'a> Context<'a> {
         y_bounds: [f64; 2],
         marker: Marker,
     ) -> Self {
-        let dot = symbols::DOT.chars().next().unwrap();
-        let block = symbols::block::FULL.chars().next().unwrap();
-        let bar = symbols::bar::HALF.chars().next().unwrap();
-        let grid: Box<dyn Grid> = match marker {
-            Marker::Dot => Box::new(CharGrid::new(width, height, dot)),
-            Marker::Block => Box::new(CharGrid::new(width, height, block)),
-            Marker::Bar => Box::new(CharGrid::new(width, height, bar)),
-            Marker::Braille => Box::new(BrailleGrid::new(width, height)),
-            Marker::HalfBlock => Box::new(HalfBlockGrid::new(width, height)),
-        };
+        let grid = Self::marker_to_grid(width, height, marker);
         Self {
+            width,
+            height,
             x_bounds,
             y_bounds,
             grid,
@@ -521,6 +575,30 @@ impl<'a> Context<'a> {
         }
     }
 
+    fn marker_to_grid(width: u16, height: u16, marker: Marker) -> Box<dyn Grid> {
+        let dot = symbols::DOT.chars().next().unwrap();
+        let block = symbols::block::FULL.chars().next().unwrap();
+        let bar = symbols::bar::HALF.chars().next().unwrap();
+        match marker {
+            Marker::Block => Box::new(CharGrid::new(width, height, block).apply_color_to_bg()),
+            Marker::Bar => Box::new(CharGrid::new(width, height, bar)),
+            Marker::Braille => Box::new(PatternGrid::<2, 4>::new(width, height, &BRAILLE)),
+            Marker::HalfBlock => Box::new(HalfBlockGrid::new(width, height)),
+            Marker::Quadrant => Box::new(PatternGrid::<2, 2>::new(width, height, &QUADRANTS)),
+            Marker::Sextant => Box::new(PatternGrid::<2, 3>::new(width, height, &SEXTANTS)),
+            Marker::Octant => Box::new(PatternGrid::<2, 4>::new(width, height, &OCTANTS)),
+            Marker::Dot | _ => Box::new(CharGrid::new(width, height, dot)),
+        }
+    }
+
+    /// Change the marker being used in this context.
+    ///
+    /// This will save the last layer if necessary and reset the grid to use the new marker.
+    pub fn marker(&mut self, marker: Marker) {
+        self.finish();
+        self.grid = Self::marker_to_grid(self.width, self.height, marker);
+    }
+
     /// Draw the given [`Shape`] in this context
     pub fn draw<S>(&mut self, shape: &S)
     where
@@ -573,16 +651,25 @@ impl<'a> Context<'a> {
 ///
 /// By default the grid is made of Braille patterns but you may change the marker to use a different
 /// set of symbols. If your terminal or font does not support this unicode block, you will see
-/// unicode replacement characters (<28>) instead of braille dots. The Braille patterns provide a more
-/// fine grained result (2x4 dots) but you might want to use a simple dot, block, or bar instead by
-/// calling the [`marker`] method if your target environment does not support those symbols.
+/// unicode replacement characters (<28>) instead of braille dots. The Braille patterns (as well the
+/// octant character patterns) provide a more fine grained result with a 2x4 resolution per
+/// character, but you might want to use a simple dot, block, or bar instead by calling the
+/// [`marker`] method if your target environment does not support those symbols.
 ///
 /// See [Unicode Braille Patterns](https://en.wikipedia.org/wiki/Braille_Patterns) for more info.
 ///
+/// The `Octant` marker is similar to the `Braille` marker but, instead of sparse dots, displays
+/// densely packed and regularly spaced pseudo-pixels, without visible bands between rows and
+/// columns. However, it uses characters that are not yet as widely supported as the Braille
+/// unicode block.
+///
+/// The `Quadrant` and `Sextant` markers are in turn akin to the `Octant` marker, but with a 2x2
+/// and 2x3 resolution, respectively.
+///
 /// The `HalfBlock` marker is useful when you want to draw shapes with a higher resolution than a
-/// `CharGrid` but lower than a `BrailleGrid`. This grid type supports a foreground and background
-/// color for each terminal cell. This allows for more flexibility than the `BrailleGrid` which only
-/// supports a single foreground color for each 2x4 dots cell.
+/// `CharGrid` but lower than a `PatternGrid`. This grid type supports a foreground and background
+/// color for each terminal cell. This allows for more flexibility than the `PatternGrid` which
+/// only supports a single foreground color for each 2x4 dots cell.
 ///
 /// The Canvas widget is used by calling the [`Canvas::paint`] method and passing a closure that
 /// will be used to draw on the canvas. The closure will be passed a [`Context`] object that can be
@@ -723,7 +810,7 @@ where
     /// The [`HalfBlock`] marker is useful when you want to draw shapes with a higher resolution
     /// than with a grid of characters (e.g. with [`Block`] or [`Dot`]) but lower than with
     /// [`Braille`]. This grid type supports a foreground and background color for each terminal
-    /// cell. This allows for more flexibility than the `BrailleGrid` which only supports a single
+    /// cell. This allows for more flexibility than the `PatternGrid` which only supports a single
     /// foreground color for each 2x4 dots cell.
     ///
     /// [`Braille`]: ratatui_core::symbols::Marker::Braille
@@ -802,19 +889,21 @@ where
 
         // Retrieve painted points for each layer
         for layer in ctx.layers {
-            for (index, (ch, colors)) in layer.string.chars().zip(layer.colors).enumerate() {
-                if ch != ' ' && ch != '\u{2800}' {
-                    let (x, y) = (
-                        (index % width) as u16 + canvas_area.left(),
-                        (index / width) as u16 + canvas_area.top(),
-                    );
-                    let cell = buf[(x, y)].set_char(ch);
-                    if colors.0 != Color::Reset {
-                        cell.set_fg(colors.0);
-                    }
-                    if colors.1 != Color::Reset {
-                        cell.set_bg(colors.1);
-                    }
+            for (index, layer_cell) in layer.contents.iter().enumerate() {
+                let (x, y) = (
+                    (index % width) as u16 + canvas_area.left(),
+                    (index / width) as u16 + canvas_area.top(),
+                );
+                let cell = &mut buf[(x, y)];
+
+                if let Some(symbol) = layer_cell.symbol {
+                    cell.set_char(symbol);
+                }
+                if let Some(fg) = layer_cell.fg {
+                    cell.set_fg(fg);
+                }
+                if let Some(bg) = layer_cell.bg {
+                    cell.set_bg(bg);
                 }
             }
         }
@@ -847,12 +936,76 @@ where
 mod tests {
     use indoc::indoc;
     use ratatui_core::buffer::Cell;
+    use rstest::rstest;
 
     use super::*;
 
-    // helper to test the canvas checks that drawing a vertical and horizontal line
-    // results in the expected output
-    fn test_marker(marker: Marker, expected: &str) {
+    #[rstest]
+    #[case::block(Marker::Block, indoc!(
+                "
+                █xxxx
+                █xxxx
+                █xxxx
+                █xxxx
+                █████"
+            ))]
+    #[case::half_block(Marker::HalfBlock, indoc!(
+                "
+                █xxxx
+                █xxxx
+                █xxxx
+                █xxxx
+                █▄▄▄▄"
+            ))]
+    #[case::bar(Marker::Bar, indoc!(
+                "
+                ▄xxxx
+                ▄xxxx
+                ▄xxxx
+                ▄xxxx
+                ▄▄▄▄▄"
+            ))]
+    #[case::braille(Marker::Braille, indoc!(
+                "
+                ⡇xxxx
+                ⡇xxxx
+                ⡇xxxx
+                ⡇xxxx
+                ⣇⣀⣀⣀⣀"
+            ))]
+    #[case::quadrant(Marker::Quadrant, indoc!(
+                "
+                ▌xxxx
+                ▌xxxx
+                ▌xxxx
+                ▌xxxx
+                ▙▄▄▄▄"
+            ))]
+    #[case::sextant(Marker::Sextant, indoc!(
+                "
+                ▌xxxx
+                ▌xxxx
+                ▌xxxx
+                ▌xxxx
+                🬲🬭🬭🬭🬭"
+            ))]
+    #[case::octant(Marker::Octant, indoc!(
+                "
+                ▌xxxx
+                ▌xxxx
+                ▌xxxx
+                ▌xxxx
+                𜷀▂▂▂▂"
+            ))]
+    #[case::dot(Marker::Dot, indoc!(
+                "
+                •xxxx
+                •xxxx
+                •xxxx
+                •xxxx
+                •••••"
+            ))]
+    fn test_horizontal_with_vertical(#[case] marker: Marker, #[case] expected: &'static str) {
         let area = Rect::new(0, 0, 5, 5);
         let mut buf = Buffer::filled(area, Cell::new("x"));
         let horizontal_line = Line {
@@ -881,71 +1034,104 @@ mod tests {
         assert_eq!(buf, Buffer::with_lines(expected.lines()));
     }
 
-    #[test]
-    fn test_bar_marker() {
-        test_marker(
-            Marker::Bar,
-            indoc!(
+    #[rstest]
+    #[case::block(Marker::Block, indoc!(
                 "
-                ▄xxxx
-                ▄xxxx
-                ▄xxxx
-                ▄xxxx
-                ▄▄▄▄▄"
-            ),
-        );
-    }
-
-    #[test]
-    fn test_block_marker() {
-        test_marker(
-            Marker::Block,
-            indoc!(
+                █xxx█
+                x█x█x
+                xx█xx
+                x█x█x
+                █xxx█"))]
+    #[case::half_block(Marker::HalfBlock,
+           indoc!(
                 "
-                █xxxx
-                █xxxx
-                █xxxx
-                █xxxx
-                █████"
-            ),
-        );
-    }
-
-    #[test]
-    fn test_braille_marker() {
-        test_marker(
-            Marker::Braille,
-            indoc!(
+                █xxx█
+                x█x█x
+                xx█xx
+                x█x█x
+                █xxx█")
+    )]
+    #[case::bar(Marker::Bar, indoc!(
                 "
-                ⡇xxxx
-                ⡇xxxx
-                ⡇xxxx
-                ⡇xxxx
-                ⣇⣀⣀⣀⣀"
-            ),
-        );
-    }
-
-    #[test]
-    fn test_dot_marker() {
-        test_marker(
-            Marker::Dot,
-            indoc!(
+                ▄xxx▄
+                x▄x▄x
+                xx▄xx
+                x▄x▄x
+                ▄xxx▄"))]
+    #[case::braille(Marker::Braille, indoc!(
                 "
-                •xxxx
-                •xxxx
-                •xxxx
-                •xxxx
-                •••••"
-            ),
-        );
+                ⢣xxx⡜
+                x⢣x⡜x
+                xx⣿xx
+                x⡜x⢣x
+                ⡜xxx⢣"
+            ))]
+    #[case::quadrant(Marker::Quadrant, indoc!(
+                "
+                ▚xxx▞
+                x▚x▞x
+                xx█xx
+                x▞x▚x
+                ▞xxx▚"
+            ))]
+    #[case::sextant(Marker::Sextant, indoc!(
+                "
+                🬧xxx🬔
+                x🬧x🬔x
+                xx█xx
+                x🬘x🬣x
+                🬘xxx🬣"
+            ))]
+    #[case::octant(Marker::Octant, indoc!(
+                "
+                ▚xxx▞
+                x▚x▞x
+                xx█xx
+                x▞x▚x
+                ▞xxx▚"
+            ))]
+    #[case::dot(Marker::Dot, indoc!(
+                "
+                •xxx•
+                x•x•x
+                xx•xx
+                x•x•x
+                •xxx•"
+            ))]
+    fn test_diagonal_lines(#[case] marker: Marker, #[case] expected: &'static str) {
+        let area = Rect::new(0, 0, 5, 5);
+        let mut buf = Buffer::filled(area, Cell::new("x"));
+        let diagonal_up = Line {
+            x1: 0.0,
+            y1: 0.0,
+            x2: 10.0,
+            y2: 10.0,
+            color: Color::Reset,
+        };
+        let diagonal_down = Line {
+            x1: 0.0,
+            y1: 10.0,
+            x2: 10.0,
+            y2: 0.0,
+            color: Color::Reset,
+        };
+        Canvas::default()
+            .marker(marker)
+            .paint(|ctx| {
+                ctx.draw(&diagonal_down);
+                ctx.draw(&diagonal_up);
+            })
+            .x_bounds([0.0, 10.0])
+            .y_bounds([0.0, 10.0])
+            .render(area, &mut buf);
+        assert_eq!(buf, Buffer::with_lines(expected.lines()));
     }
 
     // The canvas methods work a lot with arithmetic so here we enter various width and height
     // values to check if there are any integer overflows we just initialize the canvas painters
     #[test]
     fn check_canvas_paint_max() {
-        let mut b_grid = BrailleGrid::new(u16::MAX, 2);
+        let mut b_grid = PatternGrid::<2, 4>::new(u16::MAX, 2, &OCTANTS);
         let mut c_grid = CharGrid::new(u16::MAX, 2, 'd');
 
         let max = u16::MAX as usize;
@@ -964,7 +1150,7 @@ mod tests {
     // We delibately cause integer overflow to check if we don't panic and don't get weird behavior
     #[test]
     fn check_canvas_paint_overflow() {
-        let mut b_grid = BrailleGrid::new(u16::MAX, 3);
+        let mut b_grid = PatternGrid::<2, 4>::new(u16::MAX, 3, &BRAILLE);
         let mut c_grid = CharGrid::new(u16::MAX, 3, 'd');
 
         let max = u16::MAX as usize + 10;

ratatui-widgets/src/canvas/map.rs

@@ -31,7 +31,7 @@ impl MapResolution {
     }
 }
 
-/// A world map
+/// A world map. It represents the world using the [EPSG:4326 coordinate reference system](https://en.wikipedia.org/wiki/EPSG_Geodetic_Parameter_Dataset).
 ///
 /// A world map can be rendered with different [resolutions](MapResolution) and [colors](Color).
 #[derive(Debug, Default, Clone, Eq, PartialEq, Hash)]

ratatui-widgets/src/canvas/rectangle.rs

@@ -115,7 +115,7 @@ mod tests {
             "█        █",
             "██████████",
         ]);
-        expected.set_style(buffer.area, Style::new().red());
+        expected.set_style(buffer.area, Style::new().red().on_red());
         expected.set_style(buffer.area.inner(Margin::new(1, 1)), Style::reset());
         assert_eq!(buffer, expected);
     }

ratatui-widgets/src/chart.rs

@@ -1017,16 +1017,18 @@ impl Widget for &Chart<'_> {
             }
         }
 
-        for dataset in &self.datasets {
-            Canvas::default()
-                .background_color(self.style.bg.unwrap_or(Color::Reset))
-                .x_bounds(self.x_axis.bounds)
-                .y_bounds(self.y_axis.bounds)
-                .marker(dataset.marker)
-                .paint(|ctx| {
+        Canvas::default()
+            .background_color(self.style.bg.unwrap_or(Color::Reset))
+            .x_bounds(self.x_axis.bounds)
+            .y_bounds(self.y_axis.bounds)
+            .paint(|ctx| {
+                for dataset in &self.datasets {
+                    ctx.marker(dataset.marker);
+
+                    let color = dataset.style.fg.unwrap_or(Color::Reset);
                     ctx.draw(&Points {
                         coords: dataset.data,
-                        color: dataset.style.fg.unwrap_or(Color::Reset),
+                        color,
                     });
                     match dataset.graph_type {
                         GraphType::Line => {
@@ -1036,7 +1038,7 @@ impl Widget for &Chart<'_> {
                                     y1: data[0].1,
                                     x2: data[1].0,
                                     y2: data[1].1,
-                                    color: dataset.style.fg.unwrap_or(Color::Reset),
+                                    color,
                                 });
                             }
                         }
@@ -1047,15 +1049,15 @@ impl Widget for &Chart<'_> {
                                     y1: 0.0,
                                     x2: *x,
                                     y2: *y,
-                                    color: dataset.style.fg.unwrap_or(Color::Reset),
+                                    color,
                                 });
                             }
                         }
                         GraphType::Scatter => {}
                     }
-                })
-                .render(graph_area, buf);
-        }
+                }
+            })
+            .render(graph_area, buf);
 
         if let Some(Position { x, y }) = layout.title_x {
             let title = self.x_axis.title.as_ref().unwrap();
@@ -1548,6 +1550,62 @@ mod tests {
         assert_eq!(buffer, expected);
     }
 
+    #[rstest]
+    #[case::dot(symbols::Marker::Dot, '•')]
+    #[case::dot(symbols::Marker::Braille, '⢣')]
+    fn overlapping_lines(#[case] marker: symbols::Marker, #[case] symbol: char) {
+        let data_diagonal_up = [(0.0, 0.0), (5.0, 5.0)];
+        let data_diagonal_down = [(0.0, 5.0), (5.0, 0.0)];
+        let lines = vec![
+            Dataset::default()
+                .data(&data_diagonal_up)
+                .marker(symbols::Marker::Block)
+                .graph_type(GraphType::Line)
+                .blue(),
+            Dataset::default()
+                .data(&data_diagonal_down)
+                .marker(marker)
+                .graph_type(GraphType::Line)
+                .red(),
+        ];
+        let chart = Chart::new(lines)
+            .x_axis(Axis::default().bounds([0.0, 5.0]))
+            .y_axis(Axis::default().bounds([0.0, 5.0]));
+        let area = Rect::new(0, 0, 5, 5);
+        let mut buffer = Buffer::empty(area);
+        chart.render(buffer.area, &mut buffer);
+        #[rustfmt::skip]
+        let mut expected = Buffer::with_lines([
+            format!("{symbol}   █"),
+            format!(" {symbol} █ "),
+            format!("  {symbol}  "),
+            format!(" █ {symbol} "),
+            format!("█   {symbol}"),
+        ]);
+        for i in 0..5 {
+            // The Marker::Dot and Marker::Braille tiles have the
+            // foreground set to Red.
+            expected.set_style(Rect::new(i, i, 1, 1), Style::new().fg(Color::Red));
+            // The Marker::Block tiles have both the foreground and
+            // background set to Blue.
+            expected.set_style(
+                Rect::new(i, 4 - i, 1, 1),
+                Style::new().fg(Color::Blue).bg(Color::Blue),
+            );
+        }
+        // Where the Marker::Dot/Braille overlaps with Marker::Block,
+        // the background is set to blue from the Block, but the
+        // foreground is set to red from the Dot/Braille.  This allows
+        // two line plots to overlap, so long as one of them is a
+        // Block.
+        expected.set_style(
+            Rect::new(2, 2, 1, 1),
+            Style::new().fg(Color::Red).bg(Color::Blue),
+        );
+
+        assert_eq!(buffer, expected);
+    }
+
     #[test]
     fn render_in_minimal_buffer() {
         let mut buffer = Buffer::empty(Rect::new(0, 0, 1, 1));

ratatui-widgets/src/lib.rs

@@ -130,5 +130,6 @@ pub mod tabs;
 mod polyfills;
 mod reflow;
 
+mod as_ref;
 #[cfg(feature = "calendar")]
 pub mod calendar;

ratatui-widgets/src/list.rs

@@ -403,7 +403,7 @@ impl<'a> List<'a> {
     ///
     /// # Example
     ///
-    /// A padding value of 1 will keep 1 item above and 1 item bellow visible if possible
+    /// A padding value of 1 will keep 1 item above and 1 item below visible if possible
     ///
     /// ```rust
     /// use ratatui::widgets::List;

ratatui-widgets/src/list/rendering.rs

@@ -220,7 +220,7 @@ impl List<'_> {
         let last_valid_index = self.items.len().saturating_sub(1);
         let selected = selected?.min(last_valid_index);
 
-        // The bellow loop handles situations where the list item sizes may not be consistent,
+        // The below loop handles situations where the list item sizes may not be consistent,
         // where the offset would have excluded some items that we want to include, or could
         // cause the offset value to be set to an inconsistent value each time we render.
         // The padding value will be reduced in case any of these issues would occur
@@ -1219,7 +1219,7 @@ mod tests {
         assert_eq!(buffer, Buffer::with_lines(expected));
     }
 
-    // Tests to make sure when it's pushing back the first visible index value that it doesnt
+    // Tests to make sure when it's pushing back the first visible index value that it doesn't
     // include an item that's too large
     #[test]
     fn padding_offset_pushback_break() {

ratatui-widgets/src/table.rs

@@ -776,7 +776,7 @@ impl StatefulWidget for &Table<'_> {
 
         self.render_header(header_area, buf, &column_widths);
 
-        self.render_rows(rows_area, buf, state, selection_width, &column_widths);
+        self.render_rows(rows_area, buf, selection_width, state, &column_widths);
 
         self.render_footer(footer_area, buf, &column_widths);
     }
@@ -806,31 +806,47 @@ impl Table<'_> {
         (header_area, rows_area, footer_area)
     }
 
-    fn render_header(&self, area: Rect, buf: &mut Buffer, column_widths: &[(u16, u16)]) {
+    /// Render the header cells, if they are not `None`
+    ///
+    /// The `x` and `width` fields of each `Rect` in `column_widths` denote the starting
+    /// x-coordinate and width of each column in the table.
+    fn render_header(&self, area: Rect, buf: &mut Buffer, column_widths: &[Rect]) {
         if let Some(ref header) = self.header {
             buf.set_style(area, header.style);
-            for ((x, width), cell) in column_widths.iter().zip(header.cells.iter()) {
-                cell.render(Rect::new(area.x + x, area.y, *width, area.height), buf);
+            for (cell_area, cell) in column_widths.iter().zip(header.cells.iter()) {
+                let new_x = area.x + cell_area.x;
+                let area_to_render = Rect::new(new_x, area.y, cell_area.width, area.height);
+                cell.render(area_to_render, buf);
             }
         }
     }
 
-    fn render_footer(&self, area: Rect, buf: &mut Buffer, column_widths: &[(u16, u16)]) {
+    /// Render the footer cells, if they are not `None`
+    ///
+    /// The `x` and `width` fields of each `Rect` in `column_widths` denote the starting
+    /// x-coordinate and width of each column in the table.
+    fn render_footer(&self, area: Rect, buf: &mut Buffer, column_widths: &[Rect]) {
         if let Some(ref footer) = self.footer {
             buf.set_style(area, footer.style);
-            for ((x, width), cell) in column_widths.iter().zip(footer.cells.iter()) {
-                cell.render(Rect::new(area.x + x, area.y, *width, area.height), buf);
+            for (cell_area, cell) in column_widths.iter().zip(footer.cells.iter()) {
+                let new_x = area.x + cell_area.x;
+                let area_to_render = Rect::new(new_x, area.y, cell_area.width, area.height);
+                cell.render(area_to_render, buf);
             }
         }
     }
 
+    /// Render the table rows
+    ///
+    /// The `x` and `width` fields of each `Rect` in `column_widths` denote the starting
+    /// x-coordinate and width of each column in the table.
     fn render_rows(
         &self,
         area: Rect,
         buf: &mut Buffer,
-        state: &mut TableState,
         selection_width: u16,
-        columns_widths: &[(u16, u16)],
+        state: &mut TableState,
+        columns_widths: &[Rect],
     ) {
         if self.rows.is_empty() {
             return;
@@ -856,19 +872,9 @@ impl Table<'_> {
 
             let is_selected = state.selected.is_some_and(|index| index == i);
             if selection_width > 0 && is_selected {
-                let selection_area = Rect {
-                    width: selection_width,
-                    ..row_area
-                };
-                buf.set_style(selection_area, row.style);
-                (&self.highlight_symbol).render(selection_area, buf);
-            }
-            for ((x, width), cell) in columns_widths.iter().zip(row.cells.iter()) {
-                cell.render(
-                    Rect::new(row_area.x + x, row_area.y, *width, row_area.height),
-                    buf,
-                );
+                self.set_selection_style(buf, selection_width, row_area, row);
             }
+            self.render_row_cells(buf, columns_widths.iter().collect(), &row.cells, row_area);
             if is_selected {
                 selected_row_area = Some(row_area);
             }
@@ -878,9 +884,9 @@ impl Table<'_> {
         let selected_column_area = state.selected_column.and_then(|s| {
             // The selection is clamped by the column count. Since a user can manually specify an
             // incorrect number of widths, we should use panic free methods.
-            columns_widths.get(s).map(|(x, width)| Rect {
-                x: x + area.x,
-                width: *width,
+            columns_widths.get(s).map(|cell_area| Rect {
+                x: cell_area.x + area.x,
+                width: cell_area.width,
                 ..area
             })
         });
@@ -902,6 +908,83 @@ impl Table<'_> {
         }
     }
 
+    /// Render cells into the columns of a row
+    ///
+    /// Render `Cell`s from `cells` into columns specified by `column_widths`, stopping
+    /// if either of these iterators are finished.  Each `Cell` gets rendered across
+    /// [`Cell::get_column_span`] columns plus the gaps between them, if this value is > 1.
+    fn render_row_cells(
+        &self,
+        buf: &mut Buffer,
+        column_widths: Vec<&Rect>,
+        cells: &Vec<Cell>,
+        row_area: Rect,
+    ) {
+        let mut column_widths_iterator = column_widths.into_iter();
+        for current_cell in cells {
+            if let Some(cell_area) = Self::get_cell_area(
+                &mut column_widths_iterator,
+                current_cell.column_span,
+                self.column_spacing,
+            ) {
+                let new_x = row_area.x + cell_area.x;
+                let area_to_render = Rect::new(new_x, row_area.y, cell_area.width, row_area.height);
+                current_cell.render(area_to_render, buf);
+            }
+        }
+    }
+
+    /// Set the row style and render the highlight symbol
+    fn set_selection_style(
+        &self,
+        buf: &mut Buffer,
+        selection_width: u16,
+        row_area: Rect,
+        row: &Row,
+    ) {
+        let selection_area = Rect {
+            width: selection_width,
+            ..row_area
+        };
+        buf.set_style(selection_area, row.style);
+        (&self.highlight_symbol).render(selection_area, buf);
+    }
+
+    /// Return the area that a [`Cell`] should occupy, taking into account its
+    /// [`Cell::column_span`].
+    ///
+    /// Returns `None` when there are no more columns for the [`Cell`] to occupy.
+    ///
+    /// Otherwise, returns `Some(Rect{x, y = 0, width, height = 0})`, representing the start
+    /// x-coordinate and width of the [`Cell`].
+    ///
+    /// This function consumes `cell_column_span` `Rect`s from `column_widths_iterator` (or all the
+    /// `Rects` if the iterator is less than `cell_column_span` `Rect`s long). This function adds
+    /// the width of each `Rect` plus `column_spacing` to a running total of the final width.  The
+    /// return value is the original x coordinate and the final width, or `None` if
+    /// `column_widths_iterator` is empty or `cell_column_span` is `0`.
+    fn get_cell_area<'a, T>(
+        column_widths_iterator: &mut T,
+        cell_column_span: u16,
+        column_spacing: u16,
+    ) -> Option<Rect>
+    where
+        T: Iterator<Item = &'a Rect>,
+    {
+        if cell_column_span == 0 {
+            return None;
+        }
+        let first = column_widths_iterator.next()?;
+        let (n_columns_taken, all_columns_width) = column_widths_iterator
+            .take((cell_column_span - 1).into())
+            .map(|rect| (1, rect.width))
+            .fold((1, first.width), |so_far, next_column| {
+                (next_column.0 + so_far.0, next_column.1 + so_far.1)
+            });
+        let width = all_columns_width + (n_columns_taken - 1) * column_spacing;
+        Some(Rect::new(first.x, first.y, width, 1))
+    }
+
     /// Return the indexes of the visible rows.
     ///
     /// The algorithm works as follows:
@@ -960,7 +1043,7 @@ impl Table<'_> {
         max_width: u16,
         selection_width: u16,
         col_count: usize,
-    ) -> Vec<(u16, u16)> {
+    ) -> Vec<Rect> {
         let widths = if self.widths.is_empty() {
             // Divide the space between each column equally
             vec![Constraint::Length(max_width / col_count.max(1) as u16); col_count]
@@ -975,7 +1058,10 @@ impl Table<'_> {
             .flex(self.flex)
             .spacing(self.column_spacing)
             .split(columns_area);
-        rects.iter().map(|c| (c.x, c.width)).collect()
+        rects
+            .iter()
+            .map(|c| Rect::new(c.x, 0, c.width, 1))
+            .collect()
     }
 
     fn column_count(&self) -> usize {
@@ -1352,6 +1438,101 @@ mod tests {
             assert_eq!(buf, expected);
         }
 
+        #[rstest]
+        #[case(15, 5, vec![
+                Row::new(vec![
+                    Cell::new("Cell1").column_span(1),
+                    Cell::new("Cell2").column_span(1),
+                ]),
+                Row::new(vec![
+                    Cell::new("Cell3").column_span(1),
+                    Cell::new("Cell4").column_span(1),
+                ]),
+            ],
+            &Buffer::with_lines(["Cell1 Cell2    ", "Cell3 Cell4    "]))]
+        #[case(15, 5, vec![
+                Row::new(vec![
+                    Cell::new("Cell1").column_span(0),
+                    Cell::new("Cell2").column_span(1),
+                ]),
+                Row::new(vec![
+                    Cell::new("Cell3").column_span(1),
+                    Cell::new("Cell4").column_span(1),
+                ]),
+            ], &Buffer::with_lines(["Cell2          ", "Cell3 Cell4    "]))]
+        #[case(15, 5, vec![
+                Row::new(vec![
+                    Cell::new("Cell1").column_span(2),
+                    Cell::new("Cell2").column_span(1),
+                ]),
+                Row::new(vec![
+                    Cell::new("Cell3").column_span(1),
+                    Cell::new("Cell4").column_span(1),
+                ]),
+            ], &Buffer::with_lines(["Cell1          ", "Cell3 Cell4    "]))]
+        fn test_colspans_2_cols<'rows, Rows>(
+            #[case] width: u16,
+            #[case] column_width: u16,
+            #[case] rows: Rows,
+            #[case] expected: &Buffer,
+        ) where
+            Rows: IntoIterator<Item = Row<'rows>>,
+        {
+            let mut buf = Buffer::empty(Rect::new(0, 0, width, 2));
+            let table = Table::new(rows, [Constraint::Length(column_width); 2]);
+            Widget::render(table, Rect::new(0, 0, width, 2), &mut buf);
+            assert_eq!(buf, *expected);
+        }
+
+        #[rstest]
+        #[case(17, 5, vec![
+                Row::new(vec![
+                    Cell::new("Cell1").column_span(2),
+                    Cell::new("Cell2").column_span(1),
+                ]),
+                Row::new(vec![
+                    Cell::new("Cell3").column_span(1),
+                    Cell::new("Cell4").column_span(1),
+                    Cell::new("Cell5").column_span(1),
+                ]),
+            ], &Buffer::with_lines(["Cell1       Cell2", "Cell3 Cell4 Cell5"]))]
+        #[case(17, 5, vec![
+                Row::new(vec![
+                    Cell::new("Cell1").column_span(1),
+                    Cell::new("Cell2").column_span(2),
+                    Cell::new("Cell3").column_span(1),
+                ]),
+                Row::new(vec![
+                    Cell::new("Cell4").column_span(1),
+                    Cell::new("Cell5").column_span(1),
+                    Cell::new("Cell6").column_span(1),
+                ]),
+            ], &Buffer::with_lines(["Cell1 Cell2      ", "Cell4 Cell5 Cell6"]))]
+        #[case(15, 5, vec![
+                Row::new(vec![
+                    Cell::new("11111111111111111111").column_span(2),
+                    Cell::new("22222222222222222222").column_span(1),
+                ]),
+                Row::new(vec![
+                    Cell::new("33333333333333333333").column_span(1),
+                    Cell::new("44444444444444444444").column_span(2),
+                    Cell::new("55555555555555555555").column_span(1),
+                ]),
+            ], &Buffer::with_lines(["1111111111 2222", "3333 4444444444"]))]
+        fn test_colspans_3_cols<'rows, Rows>(
+            #[case] width: u16,
+            #[case] column_width: u16,
+            #[case] rows: Rows,
+            #[case] expected: &Buffer,
+        ) where
+            Rows: IntoIterator<Item = Row<'rows>>,
+        {
+            let mut buf = Buffer::empty(Rect::new(0, 0, width, 2));
+            let table = Table::new(rows, [Constraint::Length(column_width); 3]);
+            Widget::render(table, Rect::new(0, 0, width, 2), &mut buf);
+            assert_eq!(buf, *expected);
+        }
+
         #[test]
         fn render_with_header() {
             let mut buf = Buffer::empty(Rect::new(0, 0, 15, 3));
@@ -1676,15 +1857,24 @@ mod tests {
         fn length_constraint() {
             // without selection, more than needed width
             let table = Table::default().widths([Length(4), Length(4)]);
-            assert_eq!(table.get_column_widths(20, 0, 0), [(0, 4), (5, 4)]);
+            assert_eq!(
+                table.get_column_widths(20, 0, 0),
+                [Rect::new(0, 0, 4, 1), Rect::new(5, 0, 4, 1),]
+            );
 
             // with selection, more than needed width
             let table = Table::default().widths([Length(4), Length(4)]);
-            assert_eq!(table.get_column_widths(20, 3, 0), [(3, 4), (8, 4)]);
+            assert_eq!(
+                table.get_column_widths(20, 3, 0),
+                [Rect::new(3, 0, 4, 1), Rect::new(8, 0, 4, 1)]
+            );
 
             // without selection, less than needed width
             let table = Table::default().widths([Length(4), Length(4)]);
-            assert_eq!(table.get_column_widths(7, 0, 0), [(0, 3), (4, 3)]);
+            assert_eq!(
+                table.get_column_widths(7, 0, 0),
+                [Rect::new(0, 0, 3, 1), Rect::new(4, 0, 3, 1)]
+            );
 
             // with selection, less than needed width
             // <--------7px-------->
@@ -1693,26 +1883,41 @@ mod tests {
             // └────────┘x└────────┘
             // column spacing (i.e. `x`) is always prioritized
             let table = Table::default().widths([Length(4), Length(4)]);
-            assert_eq!(table.get_column_widths(7, 3, 0), [(3, 2), (6, 1)]);
+            assert_eq!(
+                table.get_column_widths(7, 3, 0),
+                [Rect::new(3, 0, 2, 1), Rect::new(6, 0, 1, 1)]
+            );
         }
 
         #[test]
         fn max_constraint() {
             // without selection, more than needed width
             let table = Table::default().widths([Max(4), Max(4)]);
-            assert_eq!(table.get_column_widths(20, 0, 0), [(0, 4), (5, 4)]);
+            assert_eq!(
+                table.get_column_widths(20, 0, 0),
+                [Rect::new(0, 0, 4, 1), Rect::new(5, 0, 4, 1)]
+            );
 
             // with selection, more than needed width
             let table = Table::default().widths([Max(4), Max(4)]);
-            assert_eq!(table.get_column_widths(20, 3, 0), [(3, 4), (8, 4)]);
+            assert_eq!(
+                table.get_column_widths(20, 3, 0),
+                [Rect::new(3, 0, 4, 1), Rect::new(8, 0, 4, 1)]
+            );
 
             // without selection, less than needed width
             let table = Table::default().widths([Max(4), Max(4)]);
-            assert_eq!(table.get_column_widths(7, 0, 0), [(0, 3), (4, 3)]);
+            assert_eq!(
+                table.get_column_widths(7, 0, 0),
+                [Rect::new(0, 0, 3, 1), Rect::new(4, 0, 3, 1)]
+            );
 
             // with selection, less than needed width
             let table = Table::default().widths([Max(4), Max(4)]);
-            assert_eq!(table.get_column_widths(7, 3, 0), [(3, 2), (6, 1)]);
+            assert_eq!(
+                table.get_column_widths(7, 3, 0),
+                [Rect::new(3, 0, 2, 1), Rect::new(6, 0, 1, 1)]
+            );
         }
 
         #[test]
@@ -1723,42 +1928,66 @@ mod tests {
 
             // without selection, more than needed width
             let table = Table::default().widths([Min(4), Min(4)]);
-            assert_eq!(table.get_column_widths(20, 0, 0), [(0, 10), (11, 9)]);
+            assert_eq!(
+                table.get_column_widths(20, 0, 0),
+                [Rect::new(0, 0, 10, 1), Rect::new(11, 0, 9, 1)]
+            );
 
             // with selection, more than needed width
             let table = Table::default().widths([Min(4), Min(4)]);
-            assert_eq!(table.get_column_widths(20, 3, 0), [(3, 8), (12, 8)]);
+            assert_eq!(
+                table.get_column_widths(20, 3, 0),
+                [Rect::new(3, 0, 8, 1), Rect::new(12, 0, 8, 1)]
+            );
 
             // without selection, less than needed width
             // allocates spacer
             let table = Table::default().widths([Min(4), Min(4)]);
-            assert_eq!(table.get_column_widths(7, 0, 0), [(0, 3), (4, 3)]);
+            assert_eq!(
+                table.get_column_widths(7, 0, 0),
+                [Rect::new(0, 0, 3, 1), Rect::new(4, 0, 3, 1)]
+            );
 
             // with selection, less than needed width
             // always allocates selection and spacer
             let table = Table::default().widths([Min(4), Min(4)]);
-            assert_eq!(table.get_column_widths(7, 3, 0), [(3, 2), (6, 1)]);
+            assert_eq!(
+                table.get_column_widths(7, 3, 0),
+                [Rect::new(3, 0, 2, 1), Rect::new(6, 0, 1, 1)]
+            );
         }
 
         #[test]
         fn percentage_constraint() {
             // without selection, more than needed width
             let table = Table::default().widths([Percentage(30), Percentage(30)]);
-            assert_eq!(table.get_column_widths(20, 0, 0), [(0, 6), (7, 6)]);
+            assert_eq!(
+                table.get_column_widths(20, 0, 0),
+                [Rect::new(0, 0, 6, 1), Rect::new(7, 0, 6, 1)]
+            );
 
             // with selection, more than needed width
             let table = Table::default().widths([Percentage(30), Percentage(30)]);
-            assert_eq!(table.get_column_widths(20, 3, 0), [(3, 5), (9, 5)]);
+            assert_eq!(
+                table.get_column_widths(20, 3, 0),
+                [Rect::new(3, 0, 5, 1), Rect::new(9, 0, 5, 1)]
+            );
 
             // without selection, less than needed width
             // rounds from positions: [0.0, 0.0, 2.1, 3.1, 5.2, 7.0]
             let table = Table::default().widths([Percentage(30), Percentage(30)]);
-            assert_eq!(table.get_column_widths(7, 0, 0), [(0, 2), (3, 2)]);
+            assert_eq!(
+                table.get_column_widths(7, 0, 0),
+                [Rect::new(0, 0, 2, 1), Rect::new(3, 0, 2, 1)]
+            );
 
             // with selection, less than needed width
             // rounds from positions: [0.0, 3.0, 5.1, 6.1, 7.0, 7.0]
             let table = Table::default().widths([Percentage(30), Percentage(30)]);
-            assert_eq!(table.get_column_widths(7, 3, 0), [(3, 1), (5, 1)]);
+            assert_eq!(
+                table.get_column_widths(7, 3, 0),
+                [Rect::new(3, 0, 1, 1), Rect::new(5, 0, 1, 1)]
+            );
         }
 
         #[test]
@@ -1766,22 +1995,34 @@ mod tests {
             // without selection, more than needed width
             // rounds from positions: [0.00, 0.00, 6.67, 7.67, 14.33]
             let table = Table::default().widths([Ratio(1, 3), Ratio(1, 3)]);
-            assert_eq!(table.get_column_widths(20, 0, 0), [(0, 7), (8, 6)]);
+            assert_eq!(
+                table.get_column_widths(20, 0, 0),
+                [Rect::new(0, 0, 7, 1), Rect::new(8, 0, 6, 1)]
+            );
 
             // with selection, more than needed width
             // rounds from positions: [0.00, 3.00, 10.67, 17.33, 20.00]
             let table = Table::default().widths([Ratio(1, 3), Ratio(1, 3)]);
-            assert_eq!(table.get_column_widths(20, 3, 0), [(3, 6), (10, 5)]);
+            assert_eq!(
+                table.get_column_widths(20, 3, 0),
+                [Rect::new(3, 0, 6, 1), Rect::new(10, 0, 5, 1)]
+            );
 
             // without selection, less than needed width
             // rounds from positions: [0.00, 2.33, 3.33, 5.66, 7.00]
             let table = Table::default().widths([Ratio(1, 3), Ratio(1, 3)]);
-            assert_eq!(table.get_column_widths(7, 0, 0), [(0, 2), (3, 3)]);
+            assert_eq!(
+                table.get_column_widths(7, 0, 0),
+                [Rect::new(0, 0, 2, 1), Rect::new(3, 0, 3, 1)]
+            );
 
             // with selection, less than needed width
             // rounds from positions: [0.00, 3.00, 5.33, 6.33, 7.00, 7.00]
             let table = Table::default().widths([Ratio(1, 3), Ratio(1, 3)]);
-            assert_eq!(table.get_column_widths(7, 3, 0), [(3, 1), (5, 2)]);
+            assert_eq!(
+                table.get_column_widths(7, 3, 0),
+                [Rect::new(3, 0, 1, 1), Rect::new(5, 0, 2, 1)]
+            );
         }
 
         /// When more width is available than requested, the behavior is controlled by flex
@@ -1790,7 +2031,11 @@ mod tests {
             let table = Table::default().widths([Min(10), Min(10), Min(1)]);
             assert_eq!(
                 table.get_column_widths(62, 0, 0),
-                &[(0, 20), (21, 20), (42, 20)]
+                &[
+                    Rect::new(0, 0, 20, 1),
+                    Rect::new(21, 0, 20, 1),
+                    Rect::new(42, 0, 20, 1)
+                ]
             );
 
             let table = Table::default()
@@ -1798,7 +2043,11 @@ mod tests {
                 .flex(Flex::Legacy);
             assert_eq!(
                 table.get_column_widths(62, 0, 0),
-                &[(0, 10), (11, 10), (22, 40)]
+                &[
+                    Rect::new(0, 0, 10, 1),
+                    Rect::new(11, 0, 10, 1),
+                    Rect::new(22, 0, 40, 1)
+                ]
             );
 
             let table = Table::default()
@@ -1806,7 +2055,11 @@ mod tests {
                 .flex(Flex::SpaceBetween);
             assert_eq!(
                 table.get_column_widths(62, 0, 0),
-                &[(0, 20), (21, 20), (42, 20)]
+                &[
+                    Rect::new(0, 0, 20, 1),
+                    Rect::new(21, 0, 20, 1),
+                    Rect::new(42, 0, 20, 1)
+                ]
             );
         }
 
@@ -1815,7 +2068,11 @@ mod tests {
             let table = Table::default().widths([Min(10), Min(10), Min(1)]);
             assert_eq!(
                 table.get_column_widths(62, 0, 0),
-                &[(0, 20), (21, 20), (42, 20)]
+                &[
+                    Rect::new(0, 0, 20, 1),
+                    Rect::new(21, 0, 20, 1),
+                    Rect::new(42, 0, 20, 1)
+                ]
             );
 
             let table = Table::default()
@@ -1823,7 +2080,11 @@ mod tests {
                 .flex(Flex::Legacy);
             assert_eq!(
                 table.get_column_widths(62, 0, 0),
-                &[(0, 10), (11, 10), (22, 40)]
+                &[
+                    Rect::new(0, 0, 10, 1),
+                    Rect::new(11, 0, 10, 1),
+                    Rect::new(22, 0, 40, 1)
+                ]
             );
         }
 
@@ -1840,7 +2101,11 @@ mod tests {
                 .column_spacing(0);
             assert_eq!(
                 table.get_column_widths(30, 0, 3),
-                &[(0, 10), (10, 10), (20, 10)]
+                &[
+                    Rect::new(0, 0, 10, 1),
+                    Rect::new(10, 0, 10, 1),
+                    Rect::new(20, 0, 10, 1)
+                ]
             );
         }
 
@@ -1850,7 +2115,10 @@ mod tests {
                 .rows(vec![])
                 .header(Row::new(vec!["f", "g"]))
                 .column_spacing(0);
-            assert_eq!(table.get_column_widths(10, 0, 2), [(0, 5), (5, 5)]);
+            assert_eq!(
+                table.get_column_widths(10, 0, 2),
+                [Rect::new(0, 0, 5, 1), Rect::new(5, 0, 5, 1)]
+            );
         }
 
         #[test]
@@ -1859,7 +2127,10 @@ mod tests {
                 .rows(vec![])
                 .footer(Row::new(vec!["h", "i"]))
                 .column_spacing(0);
-            assert_eq!(table.get_column_widths(10, 0, 2), [(0, 5), (5, 5)]);
+            assert_eq!(
+                table.get_column_widths(10, 0, 2),
+                [Rect::new(0, 0, 5, 1), Rect::new(5, 0, 5, 1)]
+            );
         }
 
         #[track_caller]
@@ -2302,4 +2573,145 @@ mod tests {
         // This should not panic, even if the buffer has zero size.
         Widget::render(table, buffer.area, &mut buffer);
     }
+
+    #[test]
+    fn get_area_for_column_span_one_no_more_columns() {
+        let columns = [];
+        let column_span = Table::get_cell_area(&mut columns.iter(), 1, 1);
+        assert!(column_span.is_none());
+    }
+
+    #[test]
+    fn get_area_for_column_span_two_no_more_columns() {
+        let columns = [];
+        let column_span = Table::get_cell_area(&mut columns.iter(), 2, 1);
+        assert!(column_span.is_none());
+    }
+
+    #[rstest]
+    #[case(&[Rect{x: 3, width: 2, y: 0, height: 1}, Rect{x: 3, width: 2, y: 0, height: 1}, Rect{x: 3, width: 2, y: 0, height: 1}], 2, 5)]
+    #[case(&[Rect{x: 3, width: 2, y: 0, height: 1}, Rect{x: 3, width: 2, y: 0, height: 1}], 2, 5,)]
+    #[case(&[Rect{x: 3, width: 2, y: 0, height: 1}, Rect{x: 3, width: 2, y: 0, height: 1}], 1, 2)]
+    #[case(&[Rect{x: 3, width: 2, y: 0, height: 1}, Rect{x: 3, width: 2, y: 0, height: 1}], 3, 5)]
+    #[case(&[Rect{x: 3, width: 2, y: 0, height: 1}], 1, 2)]
+    #[case(&[Rect{x: 3, width: 2, y: 0, height: 1}], 2, 2)]
+    #[case(&[
+        Rect{x: 3, width: 2, y: 0, height: 1},
+        Rect{x: 3, width: 2, y: 0, height: 1},
+        Rect{x: 3, width: 2, y: 0, height: 1},
+        Rect{x: 3, width: 2, y: 0, height: 1},
+            ], 3, 8)]
+    #[case(&[
+        Rect{x: 3, width: 2, y: 0, height: 1},
+        Rect{x: 3, width: 2, y: 0, height: 1},
+        Rect{x: 3, width: 2, y: 0, height: 1},
+            ], 3, 8)]
+    fn test_colspan_width_single_column_spacing(
+        #[case] columns: &[Rect],
+        #[case] column_span: u16,
+        #[case] expected_column_width: u16,
+    ) {
+        let column_span = Table::get_cell_area(&mut columns.iter(), column_span, 1);
+        assert!(column_span.is_some());
+        assert_eq!(column_span.unwrap().width, expected_column_width);
+    }
+
+    #[rstest]
+    #[case(&[Rect{x: 3, width: 2, y: 0, height: 1}, Rect{x: 3, width: 2, y: 0, height: 1}, Rect{x: 3, width: 2, y: 0, height: 1}], 3, 10)]
+    #[case(&[Rect{x: 3, width: 2, y: 0, height: 1}], 3, 2)]
+    fn test_colspan_width_two_column_spacing(
+        #[case] columns: &[Rect],
+        #[case] column_span: u16,
+        #[case] expected_column_width: u16,
+    ) {
+        let column_span = Table::get_cell_area(&mut columns.iter(), column_span, 2);
+        assert!(column_span.is_some());
+        assert_eq!(column_span.unwrap().width, expected_column_width);
+    }
+
+    #[rstest]
+    #[case(
+        HighlightSpacing::Always,
+        15,   // width
+        1,    // spacing
+        None, // selection
+        [
+            Cell::new("ABCDEFGHIJK").column_span(2),
+            Cell::new("12345678901"),
+            Cell::new("XYZXYZXYZXY"),
+        ],
+        [
+            "   ABCDEFGH 123",
+            "               ", // row 2
+            "               ", // row 3
+        ])]
+    #[case(
+        HighlightSpacing::Always,
+        15,      // width
+        1,       // spacing
+        Some(0), // selection
+        [
+            Cell::new("ABCDEFGHIJK").column_span(2),
+            Cell::new("12345678901"),
+            Cell::new("XYZXYZXYZXY"),
+        ],
+        [
+            ">>>ABCDEFGH 123",
+            "               ", // row 2
+            "               ", // row 3
+        ])]
+    #[case(
+        HighlightSpacing::WhenSelected,
+        15,   // width
+        1,    // spacing
+        None, // selection
+        [
+            Cell::new("ABCDEFGHIJK").column_span(2),
+            Cell::new("12345678901"),
+            Cell::new("XYZXYZXYZXY"),
+        ],
+        [
+            "ABCDEFGHIJ 1234",
+            "               ", // row 2
+            "               ", // row 3
+        ])]
+    #[case(
+        HighlightSpacing::WhenSelected,
+        15,      // width
+        1,       // spacing
+        Some(0), // selection
+        [
+            Cell::new("ABCDEFGHIJK").column_span(2),
+            Cell::new("12345678901"),
+            Cell::new("XYZXYZXYZXY"),
+        ],
+        [
+            ">>>ABCDEFGH 123",
+            "               ", // row 2
+            "               ", // row 3
+        ])]
+    fn test_table_with_selection_and_column_spans<'line, 'cell, Lines, Cells>(
+        #[case] highlight_spacing: HighlightSpacing,
+        #[case] columns: u16,
+        #[case] spacing: u16,
+        #[case] selection: Option<usize>,
+        #[case] cells: Cells,
+        #[case] expected: Lines,
+    ) where
+        Cells: IntoIterator,
+        Cells::Item: Into<Cell<'cell>>,
+        Lines: IntoIterator,
+        Lines::Item: Into<Line<'line>>,
+    {
+        let table = Table::default()
+            .rows(vec![Row::new(cells)])
+            .highlight_spacing(highlight_spacing)
+            .highlight_symbol(">>>")
+            .column_spacing(spacing);
+        let area = Rect::new(0, 0, columns, 3);
+        let mut buf = Buffer::empty(area);
+        let mut state = TableState::default().with_selected(selection);
+        StatefulWidget::render(table, area, &mut buf, &mut state);
+        assert_eq!(buf, Buffer::with_lines(expected));
+    }
 }

ratatui-widgets/src/table/cell.rs

@@ -51,6 +51,8 @@ use ratatui_core::widgets::Widget;
 pub struct Cell<'a> {
     content: Text<'a>,
     style: Style,
+    /// The number of columns this cell will extend over
+    pub(crate) column_span: u16,
 }
 
 impl<'a> Cell<'a> {
@@ -80,6 +82,7 @@ impl<'a> Cell<'a> {
         Self {
             content: content.into(),
             style: Style::default(),
+            column_span: 1,
         }
     }
 
@@ -113,6 +116,26 @@ impl<'a> Cell<'a> {
         self
     }
 
+    /// Set the `column_span` of this cell
+    ///
+    /// This is a fluent setter method which must be chained or used as it consumes self
+    ///
+    /// # Example
+    /// ```rust
+    /// use ratatui::widgets::{Cell, Row};
+    /// let rows = vec![
+    ///     Row::new(vec![Cell::new("12345").column_span(2)]),
+    ///     Row::new(vec![Cell::new("xx"), Cell::new("yy")]),
+    /// ];
+    /// // "12345",
+    /// // "xx yy",
+    /// ```
+    #[must_use = "method moves the value of self and returns the modified value"]
+    pub const fn column_span(mut self, column_span: u16) -> Self {
+        self.column_span = column_span;
+        self
+    }
+
     /// Set the `Style` of this cell
     ///
     /// `style` accepts any type that is convertible to [`Style`] (e.g. [`Style`], [`Color`], or
@@ -167,6 +190,7 @@ where
         Self {
             content: content.into(),
             style: Style::default(),
+            column_span: 1,
         }
     }
 }

ratatui/Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 name = "ratatui"
 description = "A library that's all about cooking up terminal user interfaces"
-version = "0.30.0-beta.0"
+version = "0.30.0"
 authors.workspace = true
 documentation.workspace = true
 repository.workspace = true
@@ -32,6 +32,10 @@ default = ["crossterm", "underline-color", "all-widgets", "macros", "layout-cach
 #! Generally an application will only use one backend, so you should only enable one of the following features:
 ## enables the [`CrosstermBackend`](backend::CrosstermBackend) backend and adds a dependency on [`crossterm`].
 crossterm = ["std", "dep:ratatui-crossterm"]
+## selects the crossterm 0.28.x backend implementation
+crossterm_0_28 = ["crossterm", "ratatui-crossterm/crossterm_0_28"]
+## selects the crossterm 0.29.x backend implementation (default)
+crossterm_0_29 = ["crossterm", "ratatui-crossterm/crossterm_0_29"]
 ## enables the [`TermionBackend`](backend::TermionBackend) backend and adds a dependency on [`termion`].
 termion = ["std", "dep:ratatui-termion"]
 ## enables the [`TermwizBackend`](backend::TermwizBackend) backend and adds a dependency on [`termwiz`].

ratatui/benches/main.rs

@@ -3,6 +3,7 @@ pub mod main {
     pub mod block;
     pub mod buffer;
     pub mod constraints;
+    pub mod gauge;
     pub mod line;
     pub mod list;
     pub mod paragraph;
@@ -25,4 +26,5 @@ criterion::criterion_main!(
     table::benches,
     text::benches,
     constraints::benches,
+    gauge::benches,
 );

ratatui/benches/main/barchart.rs

@@ -52,7 +52,7 @@ fn barchart(c: &mut Criterion) {
     group.finish();
 }
 
-/// Render the widget in a classical size buffer
+/// Render the widget in a classical size buffer.
 fn render(bencher: &mut Bencher, barchart: &BarChart) {
     let mut buffer = Buffer::empty(Rect::new(0, 0, 200, 50));
     // We use `iter_batched` to clone the value in the setup function.

ratatui/benches/main/block.rs

@@ -36,7 +36,7 @@ fn block(c: &mut Criterion) {
     group.finish();
 }
 
-/// render the block into a buffer of the given `size`
+/// Render the block into a buffer of the given `size`.
 fn render(bencher: &mut Bencher, block: &Block, size: Rect) {
     let mut buffer = Buffer::empty(size);
     // We use `iter_batched` to clone the value in the setup function.

ratatui/benches/main/gauge.rs

@@ -0,0 +1,58 @@
+use criterion::{BatchSize, Criterion, criterion_group};
+use ratatui::buffer::Buffer;
+use ratatui::layout::Rect;
+use ratatui::style::Style;
+use ratatui::widgets::{Block, Gauge, Widget};
+
+/// Benchmark for rendering a gauge.
+fn gauge(c: &mut Criterion) {
+    let mut group = c.benchmark_group("gauge");
+
+    let (width, height) = (200, 50); // 1080p fullscreen with medium font
+    let buffer_size = Rect::new(0, 0, width, height);
+
+    // Render an empty gauge
+    group.bench_with_input(
+        format!("render_empty/{width}x{height}"),
+        &Gauge::default(),
+        |b, gauge| {
+            let mut buffer = Buffer::empty(buffer_size);
+            // We use `iter_batched` to clone the value in the setup function because
+            // `Widget::render` consumes the widget.
+            b.iter_batched(
+                || gauge.to_owned(),
+                |bench_gauge| {
+                    bench_gauge.render(buffer.area, &mut buffer);
+                },
+                BatchSize::SmallInput,
+            );
+        },
+    );
+
+    // Render with all features
+    group.bench_with_input(
+        format!("render_all_feature/{width}x{height}"),
+        &Gauge::default()
+            .block(Block::bordered().title("Progress"))
+            .gauge_style(Style::new().white().on_black().italic())
+            .percent(20)
+            .label("20%")
+            .use_unicode(true),
+        |b, gauge| {
+            let mut buffer = Buffer::empty(buffer_size);
+            // We use `iter_batched` to clone the value in the setup function because
+            // `Widget::render` consumes the widget.
+            b.iter_batched(
+                || gauge.to_owned(),
+                |bench_gauge| {
+                    bench_gauge.render(buffer.area, &mut buffer);
+                },
+                BatchSize::SmallInput,
+            );
+        },
+    );
+
+    group.finish();
+}
+
+criterion_group!(benches, gauge);

ratatui/benches/main/list.rs

@@ -39,7 +39,7 @@ fn list(c: &mut Criterion) {
     group.finish();
 }
 
-/// render the list into a common size buffer
+/// Render the list into a common size buffer.
 fn render(bencher: &mut Bencher, list: &List) {
     let mut buffer = Buffer::empty(Rect::new(0, 0, 200, 50));
     // We use `iter_batched` to clone the value in the setup function.

ratatui/benches/main/paragraph.rs

@@ -67,7 +67,7 @@ fn paragraph(c: &mut Criterion) {
     group.finish();
 }
 
-/// render the paragraph into a buffer with the given width
+/// Render the paragraph into a buffer with the given width.
 fn render(bencher: &mut Bencher, paragraph: &Paragraph, width: u16) {
     let mut buffer = Buffer::empty(Rect::new(0, 0, width, PARAGRAPH_DEFAULT_HEIGHT));
     // We use `iter_batched` to clone the value in the setup function.

ratatui/benches/main/sparkline.rs

@@ -25,7 +25,7 @@ fn sparkline(c: &mut Criterion) {
     group.finish();
 }
 
-/// render the block into a buffer of the given `size`
+/// Render the block into a buffer of the given `size`.
 fn render(bencher: &mut Bencher, sparkline: &Sparkline) {
     let mut buffer = Buffer::empty(Rect::new(0, 0, 200, 50));
     // We use `iter_batched` to clone the value in the setup function.

ratatui/benches/main/text.rs

@@ -46,7 +46,7 @@ fn text(c: &mut Criterion) {
     group.finish();
 }
 
-/// Renders the text into a buffer of the given `size`
+/// Render the text into a buffer of the given `size`.
 fn render(bencher: &mut Bencher, text: &Text, size: Rect) {
     let mut buffer = Buffer::empty(size);
     // We use `iter_batched` to clone the value in the setup function.

ratatui/src/widgets.rs

@@ -616,6 +616,9 @@
 //! library `no_std` compatible. This is often easier than you might expect and broadens the range
 //! of projects that can use your widgets.
 //!
+//! For more detail on advantages of this, maintenance tips and feature flags, see the
+//! [no-std concept guide].
+//!
 //! To implement `no_std` compatibility, add the `#![no_std]` attribute at the top of your `lib.rs`.
 //! When working in a `no_std` environment, you'll need to make a few adjustments:
 //!
@@ -658,6 +661,7 @@
 //!   straightforward to implement
 //!
 //! [`ratatui-core`]: https://crates.io/crates/ratatui-core
+//! [no-std concept guide]: https://ratatui.rs/concepts/no-std/
 
 pub use ratatui_core::widgets::{StatefulWidget, Widget};
 pub use ratatui_widgets::barchart::{Bar, BarChart, BarGroup};

typos.toml

@@ -2,6 +2,7 @@
 
 [default.extend-words]
 ratatui = "ratatui"
+sectore = "sectore" # https://github.com/sectore
 
 [type.md]
 extend-ignore-re = [