chore: release

Resolves https://github.com/ratatui/ratatui/issues/2264

.cliffignore

@@ -0,0 +1,115 @@
+# skip entries from <https://github.com/ratatui/ratatui/pull/1652>
+50af9a5d80ed5446f3e6cc554911f606580edde9
+272e9709c6eed45cd7e0c183624b7898f4e0ae69
+adc8fdc35aa57d6dad2ae8dd30ec2e9256576c09
+31711dbf82a4c7bb3b78692da34d9f469725dd6e
+b6356aa7a529a491d63dd6628b8985adae337f16
+885558b6f89df642317d39c5b44c94c742d1e0c8
+6440eb9d76379340953420629ab0a3d9039d6c48
+3870583ea868452191857f9bda97a3d5c35d0a4f
+487edc8399683fb8a9a66359729c015780d248f2
+250c222cc4aaab09184a28efc68f75ca03133794
+590a392ab11c1a215767614931036781f4cf6a29
+6443f7408af4a8834bc68cd35d2ba9be47e45f38
+8339cce10a51c9c951b3c9750d527d80168626eb
+ac342231c344e893f2f630ee38167aab28c736a6
+0fb103680028a6e26a1923f87b60bde51acaec4f
+4335a90a00aeeedb69a92442c7f2711727944017
+71480242a926f98e9081ed6e2dc8c381757b3a42
+e1a31db55913bd690bcaef380e9dbc3b6a5dc175
+38490ff8da6f11e309ba1bcb3e88a562f7c953c5
+a4bb143e4767137d6a9e9927d3da66562611f86f
+bc73f2dcbe5ea48fc4d1555a8e931f40d7b0e03f
+77dea441e5637b1c428c2aa71ea67fb3aac20c12
+06af14107e70e49a4cba3babb8ab0a0c57b4bdf8
+9acdab32df69517b93dd2b861b85586d47c71540
+2e684c6500be61fbe69744d183c8086564ac0051
+b7f8ec0ff9659473d936eae53a57cd9de38cec1f
+31a2c4548c304270a8c852f19baa7a4eaac5e75c
+57b681b053c019b66e0ed92959638997fea731b1
+131b9ec41751163d43d94564363247b60f031486
+8b32f82b4dd526580d00fa13f053bf507e8ea933
+76d1e5b1733d47a7f05acf563db26cb1a66b540d
+57a0a34f924e0d488c9e9f917900e677c3488dc4
+12aa58601ddd0704256c56019bd2c7139d41f7a2
+2dc81833c60951d16f9bd60f3da003edfc9a11f5
+20e41f1d1da6db8abbc2504814531d4d97bdf94b
+68b55a12a29e70ebfcc063c2d5d5845de3b5a27e
+693003314a25e792ffc5d53146b28bfb6a4582e3
+63441e259bc38b56e0369197bed14788b2cb3d54
+fa88152c808eeb6c9d9b3662361aab1e57e1b1bf
+30d9daa59b1843786cde00e25c3e69cfe818b80b
+92540b2f6ab25f3a5400aebb28af3c498ac793a4
+29edc3a7a38c512611a80cf5d8d42027558419b2
+819499d6ffc0e8453ed3220067645933a4882a74
+4756526829a4e849d9e256b6cf821eb66afe3ade
+8f35437d5ad78d31cd45c4af888f20f0b5ab4196
+39bd72b1f702dadb1ebbaf4e77ad2fada166ac49
+c6d2cee3e967c9234176c5229858512b0c79d6a9
+bd90e3d928e0f9f0b915933ebbc32c2256fe8cfa
+b820c0c7e4c576c1e39b5e482a8aac08076a039c
+74194759756bb111b4da3e9a5cdb968275a2fab0
+38b2f27efe0e1829bc503df7fd64b94b7bb80d97
+21aa3232d762d6e3f81f15fc5b66ba462385ac05
+903bb0ae32d22393783edfda96db900739864f0a
+5cee13ab6d9c49751cf9283d9099e37f0cc3632c
+0a0997702dd4cf2217160f5652f5c39cbd4a1010
+778f2f5ec511bef431b54157242b91d083ea9840
+7d23bd2ceaf96e81972b5f746fdcba0d17f6391f
+2c02a56bce31519386303571e0b66b7d4beb378e
+f33d51e7d9ccf9fe52ec3289d04d97c722d9ee17
+91cd81aaa032887bb2327bc3fe3cad6b3c9fbacf
+5d5a1ccb0b4e2f293f215ce026fba33f1c069689
+6b9417db5f2adbdc60e9dd8dc5acbbe2a1f77ba9
+dce1e4b138eb1333c9e773bacd579a8cdddd73fb
+b4aacb045e2200896b0d0136a2b8688b47828d73
+dcba0bcd5d5d6e33ddc1fa94ebb94819fdda600e
+6f52350ecfb62e3a5bac16f0824e74b757cc6cd2
+2c6f324b9aa5034771e00758b143fd8df94d859d
+bf0210602948f8d26ae323996fe7b22fb218a446
+07aff91b015b5e7e0504680c12edbce70d7dba1e
+f6d49dde14af73ed467d75d8f6ec0f502db2908f
+9a7467b30576d5cb7491ea6e09efcae97eadf9bb
+a0c35f1d7bcce10e092582b95f5b0a3f20ad7bf3
+d24747d46982192b575a40b8cc18d1c948fac3d7
+8060f7bc578b29dde6ca0c4c64569f9c73218f46
+0dc5b2d2e0aa6438ffc1b3965b1ab31c721adbcc
+8ecdd892f53d7db95bbb53a61700d36e3fcefdd4
+570c35868147a2400a13331e85d562d1ef96a011
+3855c3a84a77037aeee40dbe9e52454fb1f9afee
+93372f35c1669da0138ca776890f3ff3d38a6539
+6cf08d4a2f0398856fd593f50bf077fd59b08230
+f78d3bfec32d07c1124eee8d0249477ce3fb0884
+204307fa50aaaa373946342084f7fd3af39f3cd3
+c50b01d098e5ab405a50c3e14e858da27d606e8f
+f71d1ac73e8290f37d55a67d6a6507a3653ec174
+ae2868c0e0b1ac8b5126fd43269383fa533d87b5
+be8def963956c605bca28bcd8df673bd7ec3740b
+4ac4d9d3ab97176d71e287bcdd6d41e66f2f7ccb
+fafabb8dab84e9460a076199ea646262e51c855b
+2f97d35bd8618e8c0cc006cb1d4a9b151c1b9b4a
+39d5a745acbbd3510de707d4e7c471c17e02ae59
+a1acdcdc4c002390a76f01699cfa006a36cf3f56
+ad54cf29ad1a4335ba208fb94a8fc5dfbba260e3
+c7649575e7b199794be4252f79da80aaecdcee28
+8913e2ce1f40d451ddb4527f08ec75f198d5063c
+1b9e310300f22bfc72364f027a9caeddadf61a99
+89d7dd46031511f0556b2d29ab34035f42e3a24c
+ca4fa0b9bf5ba707aa0447ba7c38fbacdadb7eec
+8cecfdf2f6dd5b0de507f79b469517cc0fb42add
+7eeb6afb3dbc56e52f9387a74f826b186cd19137
+d0f75eb371a96f8d5f174e23de074efd840e9e44
+f8a70ea9da8e6df2bf7a5f74cce45615fc292afe
+f28b9730061bffadb9d87ad63edf7d10b245d2c1
+afc5cf2140f22fea6bd6933dd0f9c302229a1980
+b75df78cdca58d5dca0c51fb8e106067aa6cb752
+28f5a6dbd4091aa3efa86eed6767eeb44a655f0f
+345e6a1ebd853858463a33953585ce407a60378c
+c45a4de47c601554f6b981d211181468b4798e41
+bbaa9a5432ff6ad5518344123c3b56f349347e99
+f804c90f96221f334371ccd01b0e6df7b1cfc1e8
+16ba867c5877d8c97968987ecb5f8bff966d0a82
+38a1474ca12aa6a796afc1e277882d997a999e14
+92c4078413fc79fcc83f5d3d8708abb58696ff1a
+d4415204e1eb3aed2a74a722aeaaa274975dd2d7
+e48bcf5f21f14acb27996fdc02231c140f5b817c

.github/copilot-instructions.md

@@ -0,0 +1,81 @@
+# GitHub Copilot Code Review Instructions
+
+## General Review Principles
+
+### Pull Request Size and Scope
+- **Flag large PRs**: Comment if a PR changes more than 500 lines or touches many unrelated areas
+- **Suggest splitting**: Recommend breaking large changes into smaller, focused PRs
+- **Question scope creep**: Ask about unrelated changes that seem outside the PR's stated purpose
+
+### Code Quality and Style
+- **Check adherence to style guidelines**: Verify changes follow the project's Rust conventions in [CONTRIBUTING.md](https://github.com/ratatui/ratatui/blob/main/CONTRIBUTING.md#code-formatting)
+- **Verify xtask compliance**: Ensure `cargo xtask format` and `cargo xtask lint` would pass
+- **Look for AI-generated patterns**: Be suspicious of verbose, overly-commented, or non-idiomatic code
+
+### Architectural Considerations
+- **Reference ARCHITECTURE.md**: Point to [ARCHITECTURE.md](https://github.com/ratatui/ratatui/blob/main/ARCHITECTURE.md) for changes affecting crate boundaries
+- **Question fundamental changes**: Flag modifications to core configuration, linting rules, or build setup without clear justification
+- **Verify appropriate crate placement**: Ensure changes are in the correct crate per the modular structure
+
+### Breaking Changes and Deprecation
+- **Require deprecation**: Insist on deprecation warnings rather than immediate removal of public APIs
+- **Ask for migration path**: Request clear upgrade instructions for breaking changes
+- **Suggest feature flags**: Recommend feature flags for experimental or potentially disruptive changes
+- **Reference versioning policy**: Point to the requirement of at least one version notice before removal
+
+### Testing and Documentation
+- **Verify test coverage**: Ensure new functionality includes appropriate tests
+- **Check for test removal**: Question any removal of existing tests without clear justification
+- **Require documentation**: Ensure public APIs are documented with examples
+- **Validate examples**: Check that code examples are minimal and follow project style
+
+### Specific Areas of Concern
+
+#### Configuration Changes
+- **Lint configuration**: Question changes to `.clippy.toml`, `rustfmt.toml`, or CI configuration
+- **Cargo.toml modifications**: Scrutinize dependency changes or workspace modifications
+- **Build system changes**: Require justification for xtask or build process modifications
+
+#### Large Code Additions
+- **Question necessity**: Ask if large code additions could be implemented more simply
+- **Check for duplication**: Look for code that duplicates existing functionality
+- **Verify integration**: Ensure new code integrates well with existing patterns
+
+#### File Organization
+- **Validate module structure**: Ensure new modules follow the project's organization
+- **Check import organization**: Verify imports follow the std/external/local grouping pattern
+- **Review file placement**: Confirm files are in appropriate locations per ARCHITECTURE.md
+
+## Comment Templates
+
+### For Large PRs
+```
+This PR seems quite large with changes across multiple areas. Consider splitting it into smaller, focused PRs:
+- Core functionality changes
+- Documentation updates  
+- Test additions
+- Configuration changes
+
+See our [contribution guidelines](https://github.com/ratatui/ratatui/blob/main/CONTRIBUTING.md#keep-prs-small-intentional-and-focused) for more details.
+```
+
+### For Breaking Changes
+```
+This appears to introduce breaking changes. Please consider:
+- Adding deprecation warnings instead of immediate removal
+- Providing a clear migration path in the PR description
+- Following our [deprecation policy](https://github.com/ratatui/ratatui/blob/main/CONTRIBUTING.md#deprecation-notice)
+```
+
+### For Configuration Changes
+```
+Changes to project configuration (linting, formatting, build) should be discussed first. Please explain:
+- Why this change is necessary
+- What problem it solves
+- Whether it affects contributor workflow
+```
+
+### For Style Issues
+```
+Please run `cargo xtask format` and `cargo xtask lint` to ensure code follows our style guidelines. See [CONTRIBUTING.md](https://github.com/ratatui/ratatui/blob/main/CONTRIBUTING.md#code-formatting) for details.
+```

.github/workflows/calculate-alpha-release.bash

@@ -1,52 +0,0 @@
-#!/bin/bash
-
-# Exit on error. Append "|| true" if you expect an error.
-set -o errexit
-# Exit on error inside any functions or subshells.
-set -o errtrace
-# Do not allow use of undefined vars. Use ${VAR:-} to use an undefined VAR
-set -o nounset
-# Catch the error in case mysqldump fails (but gzip succeeds) in `mysqldump |gzip`
-set -o pipefail
-# Turn on traces, useful while debugging but commented out by default
-# set -o xtrace
-
-last_release="$(git tag --sort=committerdate | grep -P "v0+\.\d+\.\d+$" | tail -1)"
-echo "🐭 Last release: ${last_release}"
-
-# detect breaking changes
-if [ -n "$(git log --oneline ${last_release}..HEAD | grep '!:')" ]; then
-    echo "🐭 Breaking changes detected since ${last_release}"
-    git log --oneline ${last_release}..HEAD | grep '!:'
-    # increment the minor version
-    minor="${last_release##v0.}"
-    minor="${minor%.*}"
-    next_minor="$((minor + 1))"
-    next_release="v0.${next_minor}.0"
-else
-    # increment the patch version
-    patch="${last_release##*.}"
-    next_patch="$((patch + 1))"
-    next_release="${last_release/%${patch}/${next_patch}}"
-fi
-echo "🐭 Next release: ${next_release}"
-
-suffix="alpha"
-last_tag="$(git tag --sort=committerdate | tail -1)"
-if [[ "${last_tag}" = "${next_release}-${suffix}"* ]]; then
-    echo "🐭 Last alpha release: ${last_tag}"
-    # increment the alpha version
-    # e.g. v0.22.1-alpha.12 -> v0.22.1-alpha.13
-    alpha="${last_tag##*-${suffix}.}"
-    next_alpha="$((alpha + 1))"
-    next_tag="${last_tag/%${alpha}/${next_alpha}}"
-else
-    # increment the patch and start the alpha version from 0
-    # e.g. v0.22.0 -> v0.22.1-alpha.0
-    next_tag="${next_release}-${suffix}.0"
-fi
-# update the crate version
-msg="# crate version"
-sed -E -i "s/^version = .* ${msg}$/version = \"${next_tag#v}\" ${msg}/" Cargo.toml
-echo "NEXT_TAG=${next_tag}" >> $GITHUB_ENV
-echo "🐭 Next alpha release: ${next_tag}"

.github/workflows/check-pr.yml

@@ -1,6 +1,13 @@
 name: Check Pull Requests
 
+# Set the permissions of the github token to the minimum and only enable what is needed
+# See https://docs.github.com/en/actions/security-guides/automatic-token-authentication#permissions
+permissions: {}
+
 on:
+  # this workflow is required to be run on pull_request_target as it modifies the PR comments
+  # care should be taken that the jobs do not run any untrusted input
+  # zizmor: ignore[dangerous-triggers]
   pull_request_target:
     types:
       - opened
@@ -8,23 +15,21 @@ on:
       - synchronize
       - labeled
       - unlabeled
-  merge_group:
-
-permissions:
-  pull-requests: write
 
 jobs:
   check-title:
+    permissions:
+      pull-requests: write
     runs-on: ubuntu-latest
     steps:
       - name: Check PR title
         if: github.event_name == 'pull_request_target'
-        uses: amannn/action-semantic-pull-request@v5
+        uses: amannn/action-semantic-pull-request@48f256284bd46cdaab1048c3721360e808335d50 # v5
         id: check_pr_title
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       # Add comment indicating we require pull request titles to follow conventional commits specification
-      - uses: marocchino/sticky-pull-request-comment@v2
+      - uses: marocchino/sticky-pull-request-comment@773744901bac0e8cbb5a0dc842800d45e9b2b405 # v2
         if: always() && (steps.check_pr_title.outputs.error_message != null)
         with:
           header: pr-title-lint-error
@@ -39,40 +44,42 @@ jobs:
 
       # Delete a previous comment when the issue has been resolved
       - if: ${{ steps.check_pr_title.outputs.error_message == null }}
-        uses: marocchino/sticky-pull-request-comment@v2
+        uses: marocchino/sticky-pull-request-comment@773744901bac0e8cbb5a0dc842800d45e9b2b405 # v2
         with:
           header: pr-title-lint-error
           delete: true
 
   check-breaking-change-label:
+    permissions:
+      pull-requests: write
     runs-on: ubuntu-latest
     env:
       # use an environment variable to pass untrusted input to the script
       # see https://securitylab.github.com/research/github-actions-untrusted-input/
       PR_TITLE: ${{ github.event.pull_request.title }}
     steps:
-    - name: Check breaking change label
-      id: check_breaking_change
-      run: |
-        pattern='^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(\(\w+\))?!:'
-        # Check if pattern matches
-        if echo "${PR_TITLE}" | grep -qE "$pattern"; then
-          echo "breaking_change=true" >> $GITHUB_OUTPUT
-        else
-          echo "breaking_change=false" >> $GITHUB_OUTPUT
-        fi
-    - name: Add label
-      if: steps.check_breaking_change.outputs.breaking_change == 'true'
-      uses: actions/github-script@v7
-      with:
-        github-token: ${{ secrets.GITHUB_TOKEN }}
-        script: |
-          github.rest.issues.addLabels({
-            issue_number: context.issue.number,
-            owner: context.repo.owner,
-            repo: context.repo.repo,
-            labels: ['Type: Breaking Change']
-          })
+      - name: Check breaking change label
+        id: check_breaking_change
+        run: |
+          pattern='^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(\(\w+\))?!:'
+          # Check if pattern matches
+          if echo "${PR_TITLE}" | grep -qE "$pattern"; then
+            echo "breaking_change=true" >> $GITHUB_OUTPUT
+          else
+            echo "breaking_change=false" >> $GITHUB_OUTPUT
+          fi
+      - name: Add label
+        if: steps.check_breaking_change.outputs.breaking_change == 'true'
+        uses: actions/github-script@v8
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            github.rest.issues.addLabels({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              labels: ['Type: Breaking Change']
+            })
 
   do-not-merge:
     if: ${{ contains(github.event.*.labels.*.name, 'do not merge') }}

.github/workflows/check-semver.yml

@@ -1,5 +1,9 @@
 name: Check Semver
 
+# Set the permissions of the github token to the minimum and only enable what is needed
+# See https://docs.github.com/en/actions/security-guides/automatic-token-authentication#permissions
+permissions: {}
+
 on:
   pull_request:
     branches:
@@ -11,6 +15,8 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout the repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        with:
+          persist-credentials: false
       - name: Check semver
-        uses: obi1kenobi/cargo-semver-checks-action@v2
+        uses: obi1kenobi/cargo-semver-checks-action@5b298c9520f7096a4683c0bd981a7ac5a7e249ae # v2

.github/workflows/ci.yml

@@ -1,5 +1,9 @@
 name: Continuous Integration
 
+# Set the permissions of the github token to the minimum and only enable what is needed
+# See https://docs.github.com/en/actions/security-guides/automatic-token-authentication#permissions
+permissions: {}
+
 on:
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
@@ -25,11 +29,15 @@ jobs:
     name: Check Formatting
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: dtolnay/rust-toolchain@nightly
-        with: { components: rustfmt }
-      - uses: Swatinem/rust-cache@v2
-      - uses: taiki-e/install-action@v2
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        with:
+          persist-credentials: false
+      - uses: dtolnay/rust-toolchain@0b1efabc08b657293548b77fb76cc02d26091c7e # master
+        with:
+          toolchain: nightly
+          components: rustfmt
+      - uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5 # v2
+      - uses: taiki-e/install-action@50708e9ba8d7b6587a2cb575ddaa9a62e927bc06 # v2
         with:
           tool: taplo-cli
       - run: cargo xtask format --check
@@ -40,19 +48,32 @@ jobs:
     name: Check Typos
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: crate-ci/typos@master
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        with:
+          persist-credentials: false
+      - uses: crate-ci/typos@2d0ce569feab1f8752f1dde43cc2f2aa53236e06 # 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@v4
-      - uses: dtolnay/rust-toolchain@stable
-      - uses: taiki-e/install-action@cargo-deny
-      - run: cargo deny --log-level info --all-features check
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        with:
+          persist-credentials: false
+      - uses: EmbarkStudios/cargo-deny-action@76cd80eb775d7bbbd2d80292136d74d39e1b4918 # v2
+        with:
+          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/>
@@ -60,8 +81,10 @@ jobs:
     name: Check Unused Dependencies
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: bnjbvr/cargo-machete@v0.8.0
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        with:
+          persist-credentials: false
+      - uses: bnjbvr/cargo-machete@7959c845782fed02ee69303126d4a12d64f1db18 # v0.9.1
 
   # Run cargo clippy.
   #
@@ -77,21 +100,27 @@ jobs:
         toolchain: ["stable", "beta"]
     continue-on-error: ${{ matrix.toolchain == 'beta' }}
     steps:
-      - uses: actions/checkout@v4
-      - uses: dtolnay/rust-toolchain@master
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        with:
+          persist-credentials: false
+      - uses: dtolnay/rust-toolchain@0b1efabc08b657293548b77fb76cc02d26091c7e # master
         with:
           toolchain: ${{ matrix.toolchain }}
           components: clippy
-      - uses: Swatinem/rust-cache@v2
+      - uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5 # v2
       - run: cargo xtask clippy
+        env:
+          RUSTUP_TOOLCHAIN: ${{ matrix.toolchain }}
 
   # Run markdownlint on all markdown files in the repository.
   lint-markdown:
     name: Check Markdown
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: DavidAnson/markdownlint-cli2-action@v19
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        with:
+          persist-credentials: false
+      - uses: DavidAnson/markdownlint-cli2-action@30a0e04f1870d58f8d717450cc6134995f993c63 # v21
         with:
           globs: |
             '**/*.md'
@@ -103,14 +132,19 @@ jobs:
     name: Coverage Report
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: dtolnay/rust-toolchain@stable
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
         with:
+          persist-credentials: false
+      - uses: dtolnay/rust-toolchain@0b1efabc08b657293548b77fb76cc02d26091c7e # master
+        with:
+          toolchain: stable
           components: llvm-tools
-      - uses: taiki-e/install-action@cargo-llvm-cov
-      - uses: Swatinem/rust-cache@v2
+      - uses: taiki-e/install-action@50708e9ba8d7b6587a2cb575ddaa9a62e927bc06 # v2
+        with:
+          tool: cargo-llvm-cov
+      - uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5 # v2
       - run: cargo xtask coverage
-      - uses: codecov/codecov-action@v5
+      - uses: codecov/codecov-action@5a1091511ad55cbe89839c7260b706298ca349f7 # v5
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
           fail_ci_if_error: true
@@ -122,31 +156,43 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, windows-latest, macos-latest]
-        toolchain: ["1.74.0", "stable"]
+        toolchain: ["1.86.0", "stable"]
     runs-on: ${{ matrix.os }}
     steps:
-      - uses: actions/checkout@v4
-      - uses: dtolnay/rust-toolchain@master
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        with:
+          persist-credentials: false
+      - uses: dtolnay/rust-toolchain@0b1efabc08b657293548b77fb76cc02d26091c7e # master
         with:
           toolchain: ${{ matrix.toolchain }}
-      - uses: Swatinem/rust-cache@v2
+      - uses: taiki-e/install-action@50708e9ba8d7b6587a2cb575ddaa9a62e927bc06 # v2
+        with:
+          tool: cargo-hack
+      - uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5 # v2
       - run: cargo xtask check --all-features
+        env:
+          RUSTUP_TOOLCHAIN: ${{ matrix.toolchain }}
 
   build-no-std:
     name: Build No-Std
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: dtolnay/rust-toolchain@stable
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
         with:
+          persist-credentials: false
+      - uses: dtolnay/rust-toolchain@0b1efabc08b657293548b77fb76cc02d26091c7e # master
+        with:
+          toolchain: stable
           targets: x86_64-unknown-none
-      - uses: Swatinem/rust-cache@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
+      - run: cargo tree --target x86_64-unknown-none -p ratatui-macros
       - run: cargo tree --target x86_64-unknown-none -p ratatui --no-default-features
       - run: cargo build --target x86_64-unknown-none -p ratatui-core
       - run: cargo build --target x86_64-unknown-none -p ratatui-widgets
+      - run: cargo build --target x86_64-unknown-none -p ratatui-macros
       - run: cargo build --target x86_64-unknown-none -p ratatui --no-default-features
 
   # Check if README.md is up-to-date with the crate's documentation.
@@ -154,9 +200,13 @@ jobs:
     name: Check README
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: Swatinem/rust-cache@v2
-      - uses: taiki-e/install-action@cargo-rdme
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        with:
+          persist-credentials: false
+      - uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5 # v2
+      - uses: taiki-e/install-action@50708e9ba8d7b6587a2cb575ddaa9a62e927bc06 # v2
+        with:
+          tool: cargo-rdme
       - run: cargo xtask readme --check
 
   # Run cargo rustdoc with the same options that would be used by docs.rs, taking into account the
@@ -167,10 +217,19 @@ jobs:
     env:
       RUSTDOCFLAGS: -Dwarnings
     steps:
-      - uses: actions/checkout@v4
-      - uses: dtolnay/rust-toolchain@nightly
-      - uses: dtolnay/install@cargo-docs-rs
-      - uses: Swatinem/rust-cache@v2
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        with:
+          persist-credentials: false
+      - uses: dtolnay/rust-toolchain@0b1efabc08b657293548b77fb76cc02d26091c7e # master
+        with:
+          toolchain: nightly
+      - uses: dtolnay/install@74f735cdf643820234e37ae1c4089a08fd266d8a # master
+        with:
+          crate: cargo-docs-rs
+      - uses: taiki-e/install-action@50708e9ba8d7b6587a2cb575ddaa9a62e927bc06 # v2
+        with:
+          tool: cargo-hack
+      - 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
@@ -179,9 +238,16 @@ jobs:
     name: Test Docs
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: dtolnay/rust-toolchain@stable
-      - uses: Swatinem/rust-cache@v2
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        with:
+          persist-credentials: false
+      - uses: dtolnay/rust-toolchain@0b1efabc08b657293548b77fb76cc02d26091c7e # master
+        with:
+          toolchain: stable
+      - uses: taiki-e/install-action@50708e9ba8d7b6587a2cb575ddaa9a62e927bc06 # v2
+        with:
+          tool: cargo-hack
+      - uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5 # v2
       - run: cargo xtask test-docs
 
   # Run cargo test on the libraries of the crate.
@@ -191,11 +257,18 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        toolchain: ["1.74.0", "stable"]
+        toolchain: ["1.86.0", "stable"]
     steps:
-      - uses: actions/checkout@v4
-      - uses: dtolnay/rust-toolchain@stable
-      - uses: Swatinem/rust-cache@v2
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        with:
+          persist-credentials: false
+      - uses: dtolnay/rust-toolchain@0b1efabc08b657293548b77fb76cc02d26091c7e # master
+        with:
+          toolchain: stable
+      - uses: taiki-e/install-action@50708e9ba8d7b6587a2cb575ddaa9a62e927bc06 # v2
+        with:
+          tool: cargo-hack
+      - uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5 # v2
       - run: cargo xtask test-libs
 
   # Run cargo test on all the backends.
@@ -212,7 +285,11 @@ jobs:
           - os: windows-latest
             backend: termion
     steps:
-      - uses: actions/checkout@v4
-      - uses: dtolnay/rust-toolchain@stable
-      - uses: Swatinem/rust-cache@v2
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        with:
+          persist-credentials: false
+      - uses: dtolnay/rust-toolchain@0b1efabc08b657293548b77fb76cc02d26091c7e # master
+        with:
+          toolchain: stable
+      - uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5 # v2
       - run: cargo xtask test-backend ${{ matrix.backend }}

.github/workflows/release-alpha.yml

@@ -1,48 +0,0 @@
-name: Release alpha version
-
-on:
-  workflow_dispatch:
-  schedule:
-    # At 00:00 on Saturday
-    # https://crontab.guru/#0_0_*_*_6
-    - cron: "0 0 * * 6"
-
-defaults:
-  run:
-    shell: bash
-
-jobs:
-  publish-alpha:
-    name: Create an alpha release
-    runs-on: ubuntu-latest
-    permissions:
-      contents: write
-    steps:
-      - name: Checkout the repository
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: Calculate the next release
-        run: .github/workflows/calculate-alpha-release.bash
-
-      - name: Install Rust stable
-        uses: dtolnay/rust-toolchain@stable
-
-      - name: Publish
-        run: cargo publish --allow-dirty --token ${{ secrets.CARGO_TOKEN }}
-
-      - name: Generate a changelog
-        uses: orhun/git-cliff-action@v4
-        with:
-          config: cliff.toml
-          args: --unreleased --tag ${{ env.NEXT_TAG }} --strip header
-        env:
-          OUTPUT: BODY.md
-
-      - name: Publish on GitHub
-        uses: ncipollo/release-action@v1
-        with:
-          tag: ${{ env.NEXT_TAG }}
-          prerelease: true
-          bodyFile: BODY.md

.github/workflows/release-plz.yml

@@ -1,8 +1,8 @@
 name: Release-plz
 
-permissions:
-  pull-requests: write
-  contents: write
+# Set the permissions of the github token to the minimum and only enable what is needed
+# See https://docs.github.com/en/actions/security-guides/automatic-token-authentication#permissions
+permissions: {}
 
 on:
   push:
@@ -14,26 +14,39 @@ jobs:
   # Release unpublished packages.
   release-plz-release:
     name: Release-plz release
+    environment: release
+    permissions:
+      pull-requests: write
+      contents: write
+      id-token: write
     runs-on: ubuntu-latest
     if: ${{ github.repository_owner == 'ratatui' }}
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
         with:
           fetch-depth: 0
+          persist-credentials: false
       - name: Install Rust toolchain
-        uses: dtolnay/rust-toolchain@stable
+        uses: dtolnay/rust-toolchain@0b1efabc08b657293548b77fb76cc02d26091c7e # master
+        with:
+          toolchain: stable
+      - uses: rust-lang/crates-io-auth-action@b7e9a28eded4986ec6b1fa40eeee8f8f165559ec # v1
+        id: auth
       - name: Run release-plz
-        uses: release-plz/action@v0.5
+        uses: release-plz/action@487eb7b5c085a664d5c5ca05f4159bd9b591182a # v0.5
         with:
           command: release
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_TOKEN }}
+          CARGO_REGISTRY_TOKEN: ${{ steps.auth.outputs.token }}
 
   # Create a PR with the new versions and changelog, preparing the next release.
   release-plz-pr:
     name: Release-plz PR
+    permissions:
+      pull-requests: write
+      contents: write
     runs-on: ubuntu-latest
     if: ${{ github.repository_owner == 'ratatui' }}
     concurrency:
@@ -41,13 +54,16 @@ jobs:
       cancel-in-progress: false
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
         with:
           fetch-depth: 0
+          persist-credentials: false
       - name: Install Rust toolchain
-        uses: dtolnay/rust-toolchain@stable
+        uses: dtolnay/rust-toolchain@0b1efabc08b657293548b77fb76cc02d26091c7e # master
+        with:
+          toolchain: stable
       - name: Run release-plz
-        uses: release-plz/action@v0.5
+        uses: release-plz/action@487eb7b5c085a664d5c5ca05f4159bd9b591182a # v0.5
         with:
           command: release-pr
         env:

.github/workflows/release-stable.yml

@@ -1,45 +0,0 @@
-name: Release stable version
-
-on:
-  push:
-    tags:
-      - "v*.*.*"
-
-jobs:
-  publish-stable:
-    name: Create an stable release
-    runs-on: ubuntu-latest
-    permissions:
-      contents: write
-    steps:
-      - name: Checkout the repository
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: Generate a changelog
-        uses: orhun/git-cliff-action@v4
-        with:
-          config: cliff.toml
-          args: --latest --strip header
-        env:
-          OUTPUT: BODY.md
-
-      - name: Publish on GitHub
-        uses: ncipollo/release-action@v1
-        with:
-          prerelease: false
-          bodyFile: BODY.md
-
-  publish-crate:
-    name: Publish crate
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout the repository
-        uses: actions/checkout@v4
-
-      - name: Install Rust stable
-        uses: dtolnay/rust-toolchain@stable
-
-      - name: Publish
-        run: cargo publish --token ${{ secrets.CARGO_TOKEN }}

.github/workflows/zizmor.yml

@@ -0,0 +1,26 @@
+name: GitHub Actions Security Analysis with zizmor 🌈
+
+# docs https://docs.zizmor.sh/integrations/#github-actions
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["**"]
+
+permissions: {}
+
+jobs:
+  zizmor:
+    name: Run zizmor 🌈
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        with:
+          persist-credentials: false
+
+      - name: Run zizmor 🌈
+        uses: zizmorcore/zizmor-action@e639db99335bc9038abc0e066dfcd72e23d26fb4 # v0.3.0

.gitignore

@@ -3,3 +3,4 @@ target
 *.rs.rustfmt
 .gdb_history
 .idea/
+.env

ARCHITECTURE.md

@@ -0,0 +1,203 @@
+# Ratatui Architecture
+
+This document provides a comprehensive overview of Ratatui's architecture and crate
+organization, introduced in version 0.30.0.
+
+## Overview
+
+Starting with Ratatui 0.30.0, the project was reorganized from a single monolithic crate into
+a modular workspace consisting of multiple specialized crates. This architectural decision was
+made to improve modularity, reduce compilation times, enable more flexible dependency
+management, and provide better API stability for third-party widget libraries.
+
+## Crate Organization
+
+The Ratatui project is now organized as a Cargo workspace containing the following crates:
+
+### Core Crates
+
+#### `ratatui` (Main Crate)
+
+- **Purpose**: The main entry point that most applications should use
+- **Contents**: Re-exports everything from other crates for convenience, plus experimental features
+- **Target Users**: Application developers building terminal UIs
+- **Key Features**:
+  - Complete widget ecosystem
+  - Backend implementations
+  - Layout system
+  - Terminal management
+  - Experimental `WidgetRef` and `StatefulWidgetRef` traits
+
+#### `ratatui-core`
+
+- **Purpose**: Foundational types and traits for the Ratatui ecosystem
+- **Contents**: Core widget traits, text types, buffer, layout, style, and symbols
+- **Target Users**: Widget library authors, minimalist projects
+- **Key Features**:
+  - `Widget` and `StatefulWidget` traits
+  - Text rendering (`Text`, `Line`, `Span`)
+  - Buffer management
+  - Layout system
+  - Style and color definitions
+  - Symbol collections
+
+#### `ratatui-widgets`
+
+- **Purpose**: Built-in widget implementations
+- **Contents**: All standard widgets like `Block`, `Paragraph`, `List`, `Chart`, etc.
+- **Target Users**: Applications needing standard widgets, widget library authors
+- **Key Features**:
+  - Complete set of built-in widgets
+  - Optimized implementations
+  - Comprehensive documentation and examples
+
+### Backend Crates
+
+#### `ratatui-crossterm`
+
+- **Purpose**: Crossterm backend implementation
+- **Contents**: Cross-platform terminal backend using the `crossterm` crate
+- **Target Users**: Applications targeting multiple platforms
+
+#### `ratatui-termion`
+
+- **Purpose**: Termion backend implementation
+- **Contents**: Unix-specific terminal backend using the `termion` crate
+- **Target Users**: Unix-specific applications requiring low-level control
+
+#### `ratatui-termwiz`
+
+- **Purpose**: Termwiz backend implementation
+- **Contents**: Terminal backend using the `termwiz` crate
+- **Target Users**: Applications needing advanced terminal features
+
+### Utility Crates
+
+#### `ratatui-macros`
+
+- **Purpose**: Declarative macros for common patterns and boilerplate reduction
+- **Contents**: Macros for common patterns and boilerplate reduction
+- **Target Users**: Applications and libraries wanting macro support
+
+## Dependency Relationships
+
+```text
+ratatui
+├── ratatui-core
+├── ratatui-widgets → ratatui-core
+├── ratatui-crossterm → ratatui-core
+├── ratatui-termion → ratatui-core
+├── ratatui-termwiz → ratatui-core
+└── ratatui-macros
+```
+
+### Key Dependencies
+
+- **ratatui-core**: Foundation for all other crates
+- **ratatui-widgets**: Depends on `ratatui-core` for widget traits and types
+- **Backend crates**: Each depends on `ratatui-core` for backend traits and types
+- **ratatui**: Depends on all other crates and re-exports their public APIs
+
+## Design Principles
+
+### Stability and Compatibility
+
+The modular architecture provides different levels of API stability:
+
+- **ratatui-core**: Designed for maximum stability to minimize breaking changes for widget
+  libraries
+- **ratatui-widgets**: Focused on widget implementations with moderate stability requirements
+- **Backend crates**: Isolated from core changes, allowing backend-specific updates
+- **ratatui**: Main crate that can evolve more freely while maintaining backward compatibility
+  through re-exports
+
+### Compilation Performance
+
+The split architecture enables:
+
+- **Reduced compilation times**: Widget libraries only need to compile core types
+- **Parallel compilation**: Different crates can be compiled in parallel
+- **Selective compilation**: Applications can exclude unused backends or widgets
+
+### Ecosystem Benefits
+
+- **Widget Library Authors**: Can depend on stable `ratatui-core` without frequent updates
+- **Application Developers**: Can use the convenient `ratatui` crate with everything included
+- **Minimalist Projects**: Can use only `ratatui-core` for lightweight applications
+
+## Migration Guide
+
+### For Application Developers
+
+Most applications should continue using the main `ratatui` crate with minimal changes:
+
+```rust
+// No changes needed - everything is re-exported
+use ratatui::{
+    widgets::{Block, Paragraph},
+    layout::{Layout, Constraint},
+    Terminal,
+};
+```
+
+### For Widget Library Authors
+
+Consider migrating to `ratatui-core` for better stability:
+
+```rust
+// Before (0.29.x and earlier)
+use ratatui::{
+    widgets::{Widget, StatefulWidget},
+    buffer::Buffer,
+    layout::Rect,
+};
+
+// After (0.30.0+)
+use ratatui_core::{
+    widgets::{Widget, StatefulWidget},
+    buffer::Buffer,
+    layout::Rect,
+};
+```
+
+### Backwards Compatibility
+
+All existing code using the `ratatui` crate will continue to work unchanged, as the main crate
+re-exports all public APIs from the specialized crates.
+
+## Future Considerations
+
+### Potential Enhancements
+
+- **Widget-specific crates**: Further split widgets into individual crates for even more
+  granular dependencies
+- **Plugin system**: Enable dynamic widget loading and third-party widget ecosystems
+- **Feature flags**: More granular feature flags for compile-time customization
+
+### Version Synchronization
+
+Currently, all crates are versioned together for simplicity. Future versions may adopt
+independent versioning once the API stabilizes further.
+
+## Related Issues and PRs
+
+This architecture was developed through extensive discussion and implementation across multiple
+PRs:
+
+- [Issue #1388](https://github.com/ratatui/ratatui/issues/1388): Original RFC for modularization
+- [PR #1459](https://github.com/ratatui/ratatui/pull/1459): Move ratatui crate into workspace
+  folder
+- [PR #1460](https://github.com/ratatui/ratatui/pull/1460): Move core types to ratatui-core
+- [PR #1474](https://github.com/ratatui/ratatui/pull/1474): Move widgets into ratatui-widgets
+  crate
+
+## Contributing
+
+When contributing to the Ratatui project, please consider:
+
+- **Core changes**: Submit PRs against `ratatui-core` for fundamental improvements
+- **Widget changes**: Submit PRs against `ratatui-widgets` for widget-specific improvements
+- **Backend changes**: Submit PRs against the appropriate backend crate
+- **Integration changes**: Submit PRs against the main `ratatui` crate
+
+See the [CONTRIBUTING.md](CONTRIBUTING.md) guide for more details on the contribution process.

BREAKING-CHANGES.md

@@ -10,19 +10,29 @@ GitHub with a [breaking change] label.
 
 This is a quick summary of the sections below:
 
-- [Unreleased](#unreleased)
+- [v0.30.0 Unreleased](#v0300-unreleased)
+  - `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
   - The `From` impls for backend types are now replaced with more specific traits
   - `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.81.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
-  - `Layout::init_cache` and `Layout::DEFAULT_CACHE_SIZE` are now only available if `layout-cache` feature is enabled
-  - Disabling `default-features` suppresses the error message if `show_cursor()` fails when dropping `Terminal`
+  - `Layout::init_cache` and `Layout::DEFAULT_CACHE_SIZE` are now only available if `layout-cache`
+    feature is enabled
+  - 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
+  - `Sparkline::data` takes `IntoIterator<Item = SparklineBar>` instead of `&[u64]` and is no longer
+    const
   - Removed public fields from `Rect` iterators
   - `Line` now implements `From<Cow<str>`
   - `Table::highlight_style` is now `Table::row_highlight_style`
@@ -83,7 +93,100 @@ This is a quick summary of the sections below:
   - MSRV is now 1.63.0
   - `List` no longer ignores empty strings
 
-## Unreleased (0.30.0)
+## v0.30.0 Unreleased
+
+### `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])
+
+[#1952]: https://github.com/ratatui/ratatui/pull/1952
+
+The old `Flex::SpaceAround` behavior has been changed to distribute space evenly around each
+element, with the middle spacers being twice the size of the first and last one. The old
+behavior can be achieved by using `Flex::SpaceEvenly` instead.
+
+```diff
+- let rects = Layout::horizontal([Length(1), Length(2)]).flex(Flex::SpaceAround).split(area);
++ let rects = Layout::horizontal([Length(1), Length(2)]).flex(Flex::SpaceEvenly).split(area);
+```
+
+### `block::Title` no longer exists ([#1926])
+
+[#1926]: https://github.com/ratatui/ratatui/pull/1926
+
+The title alignment is better expressed in the `Line` as this fits more coherently with the rest of
+the library.
+
+- `widgets::block` is no longer exported
+- `widgets::block::Title` no longer exists
+- `widgets::block::Position` is now `widgets::TitlePosition`
+- `Block::title()` now accepts `Into::<Line>` instead of `Into<Title>`
+- `BlockExt` is now exported at widgets::`BlockExt` instead of `widgets::block::BlockExt`
+
+```diff
+- use ratatui::widgets::{Block, block::{Title, Position}};
++ use ratatui::widgets::{Block, TitlePosition};
+
+let block = Block::default()
+-    .title(Title::from("Hello"))
+-    .title(Title::from("Hello").position(Position::Bottom).alignment(Alignment::Center))
+-    .title_position(Position::Bottom);
++    .title(Line::from("Hello"))
++    .title_bottom(Line::from("Hello").centered());
++    .title_position(TitlePosition::Bottom);
+
+- use ratatui::widgets::block::BlockExt;
++ use ratatui::widgets::BlockExt;
+
+struct MyWidget {
+    block: Option<Block>,
+}
+
+impl Widget for &MyWidget {
+    fn render(self, area: Rect, buf: &mut Buffer) {
+        self.block.as_ref().render(area, buf);
+        let area = self.block.inner_if_some();
+        // ...
+    }
+}
+```
+
+### `Style` no longer implements `Styled` ([#1572])
+
+[#1572]: https://github.com/ratatui/ratatui/pull/1572
+
+Any calls to methods implemented by the blanket implementation of `Stylize` are now defined directly
+on `Style`. Remove the `Stylize` import if it is no longer used by your code.
+
+```diff
+- use ratatui::style::Stylize;
+
+let style = Style::new().red();
+```
+
+The `reset()` method does not have a direct replacement, as it clashes with the existing `reset()`
+method. Use the `Style::reset()` method instead.
+
+```diff
+- some_style.reset();
++ Style::reset();
+```
 
 ### Disabling `default-features` suppresses the error message if `show_cursor()` fails when dropping `Terminal` ([#1794])
 
@@ -101,8 +204,6 @@ enabled feature flags.
 
 ### Disabling `default-features` will now disable layout cache, which can have a negative impact on performance ([#1795])
 
-[#1795]: https://github.com/ratatui/ratatui/pull/1795
-
 Layout cache is now opt-in in `ratatui-core` and enabled by default in `ratatui`. If app doesn't
 make use of `no_std`-compatibility, and disables `default-feature`, it is recommended to explicitly
 re-enable layout cache. Not doing so may impact performance.
@@ -129,12 +230,37 @@ and implement the `clear_region` method, which no longer has a default implement
 This change was made to provide greater flexibility for custom backends, particularly to remove the
 explicit dependency on `std::io` for backends that want to support `no_std` targets.
 
-### The MSRV is now 1.81.0 ([#1786])
+If your app or library uses the `Backend` trait directly - for example, by providing a generic
+implementation for many backends - you may need to update the referenced error type.
 
-[#1786]: https://github.com/ratatui/ratatui/pull/1786
+```diff
+- fn run<B: Backend>(mut terminal: Terminal<B>) -> io::Result<()> {
++ fn run<B: Backend>(mut terminal: Terminal<B>) -> Result<(), B::Error> {
+```
 
-The minimum supported Rust version (MSRV) is now 1.81.0. This is due to the use of `#[expect]` in
-the codebase, which is only available in Rust 1.81.0 and later.
+Alternatively, you can explicitly require the associated error to be `std::io::Error`. This approach
+may require fewer changes in user code but is generally not recommended, as it limits compatibility
+with third-party backends. Additionally, the error type used by built-in backends may or may not
+change in the future, making this approach less future-proof compared to the previous one.
+
+```diff
+- fn run<B: Backend>(mut terminal: Terminal<B>) -> io::Result<()> {
++ fn run<B: Backend<Error = io::Error>>(mut terminal: Terminal<B>) -> io::Result<()> {
+```
+
+If your application uses a concrete backend implementation, prefer specifying it explicitly
+instead.
+
+```diff
+- fn run<B: Backend>(mut terminal: Terminal<B>) -> io::Result<()> {
++ fn run(mut terminal: DefaultTerminal) -> io::Result<()> {
+```
+
+### MSRV is now 1.86.0 ([#2230])
+
+[#2230]: https://github.com/ratatui/ratatui/pull/2230
+
+The minimum supported Rust version (MSRV) is now 1.86.0.
 
 ### `layout::Alignment` is renamed to `layout::HorizontalAlignment` ([#1735])
 
@@ -273,6 +399,17 @@ The `termwiz` backend is upgraded from 0.22.0 to 0.23.0.
 This release has a few fixes for hyperlinks and input handling, plus some dependency updates.
 See the [commits](https://github.com/wezterm/wezterm/commits/main/termwiz) for more details.
 
+### Support a broader range for `unicode-width` version ([#1999])
+
+[#1999]: https://github.com/ratatui/ratatui/pull/1999
+
+Ratatui's dependency on `unicode-width`, previously pinned to 0.2.0, has
+expanded to allow version 0.2.1. This comes with 2 behavior changes described in
+[unicode-width#61] and [unicode-width#74].
+
+[unicode-width#61]: https://github.com/unicode-rs/unicode-width/pull/61
+[unicode-width#74]: https://github.com/unicode-rs/unicode-width/pull/74
+
 ## [v0.29.0](https://github.com/ratatui/ratatui/releases/tag/v0.29.0)
 
 ### `Sparkline::data` takes `IntoIterator<Item = SparklineBar>` instead of `&[u64]` and is no longer const ([#1326])
@@ -971,7 +1108,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.
 

CONTRIBUTING.md

@@ -6,6 +6,23 @@ If your contribution is not straightforward, please first discuss the change you
 creating a new issue before making the change, or starting a discussion on
 [discord](https://discord.gg/pMCEU9hNEj).
 
+## AI Generated Content
+
+We welcome high quality PRs, whether they are human generated or made with the assistance of AI
+tools, but we ask that you follow these guidelines:
+
+- **Attribution**: Tell us about your use of AI tools, don't make us guess whether you're using it.
+- **Review**: Make sure you review every line of AI generated content for correctness and relevance.
+- **Quality**: AI-generated content should meet the same quality standards as human-written content.
+- **Quantity**: Avoid submitting large amounts of AI generated content in a single PR. Remember that
+  quality is usually more important than quantity.
+- **License**: Ensure that the AI-generated content is compatible with Ratatui's
+  [License](./LICENSE).
+
+> [!IMPORTANT]
+> Remember that AI tools can assist in generating content, but you are responsible for the final
+> quality and accuracy of the contributions and communicating about it.
+
 ## Reporting issues
 
 Before reporting an issue on the [issue tracker](https://github.com/ratatui/ratatui/issues),
@@ -22,13 +39,33 @@ on the crate or its users should ideally be discussed in a "Feature Request" iss
 
 ### Keep PRs small, intentional, and focused
 
-Try to do one pull request per change. The time taken to review a PR grows exponential with the size
-of the change. Small focused PRs will generally be much more faster to review. PRs that include both
+Try to do one pull request per change. The time taken to review a PR grows exponentially with the size
+of the change. Small focused PRs will generally be much faster to review. PRs that include both
 refactoring (or reformatting) with actual changes are more difficult to review as every line of the
 change becomes a place where a bug may have been introduced. Consider splitting refactoring /
 reformatting changes into a separate PR from those that make a behavioral change, as the tests help
 guarantee that the behavior is unchanged.
 
+Guidelines for PR size:
+
+- Aim for PRs under 500 lines of changes when possible.
+- Split large features into incremental PRs that build on each other.
+- Separate refactoring, formatting, and functional changes into different PRs.
+- If a large PR is unavoidable, clearly explain why in the PR description.
+
+### Breaking changes and backwards compatibility
+
+We prioritize maintaining backwards compatibility and minimizing disruption to users:
+
+- **Prefer deprecation over removal**: Add deprecation warnings rather than immediately removing
+  public APIs
+- **Provide migration paths**: Include clear upgrade instructions for any breaking changes
+- **Follow our deprecation policy**: Wait at least two versions before removing deprecated items
+- **Consider feature flags**: Use feature flags for experimental or potentially disruptive changes
+- **Document breaking changes**: Clearly mark breaking changes in commit messages and PR descriptions
+
+See our [deprecation notice policy](#deprecation-notice) for more details.
+
 ### Code formatting
 
 Run `cargo xtask format` before committing to ensure that code is consistently formatted with
@@ -41,6 +78,10 @@ to be installed when running rustfmt. You can install the nightly version of Rus
 rustup install nightly
 ```
 
+> [!IMPORTANT]
+> Do not modify formatting configuration (`rustfmt.toml`, `.clippy.toml`) without
+> prior discussion. These changes affect all contributors and should be carefully considered.
+
 ### Search `tui-rs` for similar work
 
 The original fork of Ratatui, [`tui-rs`](https://github.com/fdehau/tui-rs/), has a large amount of
@@ -67,6 +108,15 @@ Running `cargo xtask ci` before pushing will perform the same checks that we do
 It's not mandatory to do this before pushing, however it may save you time to do so instead of
 waiting for GitHub to run the checks.
 
+Available xtask commands:
+
+- `cargo xtask ci` - Run all CI checks
+- `cargo xtask format` - Format code
+- `cargo xtask lint` - Run linting checks
+- `cargo xtask test` - Run all tests
+
+Run `cargo xtask --help` to see all available commands.
+
 ### Sign your commits
 
 We use commit signature verification, which will block commits from being merged via the UI unless
@@ -74,6 +124,25 @@ they are signed. To set up your machine to sign commits, see [managing commit si
 verification](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification)
 in GitHub docs.
 
+### Configuration and build system changes
+
+Changes to project configuration files require special consideration:
+
+- Linting configuration (`.clippy.toml`, `rustfmt.toml`): Affects all contributors.
+- CI configuration (`.github/workflows/`): Affects build and deployment.
+- Build system (`xtask/`, `Cargo.toml` workspace config): Affects development workflow.
+- Dependencies: Consider MSRV compatibility and licensing.
+
+Please discuss these changes in an issue before implementing them.
+
+### Collaborative development
+
+We may occasionally make changes directly to your branch—such as force-pushes—to help move a PR
+forward, speed up review, or ensure it meets our quality standards. If you would prefer we do not do
+this, or if your workflow depends on us avoiding force-pushes (for example, if your app points to
+your branch in `Cargo.toml`), please mention this in your PR description and we will respect your
+preference.
+
 ## Implementation Guidelines
 
 ### Setup
@@ -91,6 +160,20 @@ cd ratatui
 cargo xtask build
 ```
 
+### Architecture
+
+For an understanding of the crate organization and design decisions, see [ARCHITECTURE.md]. This
+document explains the modular workspace structure introduced in version 0.30.0 and provides
+guidance on which crate to use for different use cases.
+
+When making changes, consider:
+
+- Which crate should contain your changes per the modular structure,
+- Whether your changes affect the public API of `ratatui-core` (requires extra care),
+- And how your changes fit into the overall architecture.
+
+[ARCHITECTURE.md]: https://github.com/ratatui/ratatui/blob/main/ARCHITECTURE.md
+
 ### Tests
 
 The [test coverage](https://app.codecov.io/gh/ratatui/ratatui) of the crate is reasonably
@@ -98,7 +181,7 @@ good, but this can always be improved. Focus on keeping the tests simple and obv
 tests for all new or modified code. Beside the usual doc and unit tests, one of the most valuable
 test you can write for Ratatui is a test against the `TestBackend`. It allows you to assert the
 content of the output buffer that would have been flushed to the terminal after a given draw call.
-See `widgets_block_renders` in [tests/widgets_block.rs](./tests/widget_block.rs) for an example.
+See `widgets_block_renders` in [ratatui/tests/widgets_block.rs](./ratatui/tests/widgets_block.rs) for an example.
 
 When writing tests, generally prefer to write unit tests and doc tests directly in the code file
 being tested rather than integration tests in the `tests/` folder.
@@ -107,6 +190,10 @@ If an area that you're making a change in is not tested, write tests to characte
 behavior before changing it. This helps ensure that we don't introduce bugs to existing software
 using Ratatui (and helps make it easy to migrate apps still using `tui-rs`).
 
+> [!IMPORTANT]
+> Do not remove existing tests without clear justification. If tests need to be
+> modified due to API changes, explain why in your PR description.
+
 For coverage, we have two [bacon](https://dystroy.org/bacon/) jobs (one for all tests, and one for
 unit tests, keyboard shortcuts `v` and `u` respectively) that run
 [cargo-llvm-cov](https://github.com/taiki-e/cargo-llvm-cov) to report the coverage. Several plugins
@@ -174,6 +261,14 @@ We generally want to wait at least two versions before removing deprecated items
 time to update. However, if a deprecation is blocking for us to implement a new feature we may
 *consider* removing it in a one version notice.
 
+Deprecation process:
+
+1. Add `#[deprecated]` attribute with a clear message.
+2. Update documentation to point to the replacement.
+3. Add an entry to `BREAKING-CHANGES.md` if applicable.
+4. Wait at least two versions before removal.
+5. Consider the impact on the ecosystem before removing.
+
 ### Use of unsafe for optimization purposes
 
 We don't currently use any unsafe code in Ratatui, and would like to keep it that way. However, there

Cargo.toml

@@ -1,6 +1,6 @@
 [workspace]
 resolver = "2"
-members = ["ratatui", "ratatui-*", "xtask", "examples/apps/*"]
+members = ["ratatui", "ratatui-*", "xtask", "examples/apps/*", "examples/concepts/*"]
 default-members = [
   "ratatui",
   "ratatui-core",
@@ -11,6 +11,7 @@ default-members = [
   "ratatui-termwiz",
   "ratatui-widgets",
   "examples/apps/*",
+  "examples/concepts/*",
 ]
 
 [workspace.package]
@@ -23,35 +24,57 @@ categories = ["command-line-interface"]
 readme = "README.md"
 license = "MIT"
 exclude = ["assets/*", ".github", "Makefile.toml", "CONTRIBUTING.md", "*.log", "tags"]
-edition = "2021"
-rust-version = "1.81.0"
+edition = "2024"
+rust-version = "1.86.0"
 
 [workspace.dependencies]
-bitflags = "2.9.0"
-color-eyre = "0.6.3"
-crossterm = "0.29.0"
-document-features = "0.2.11"
-hashbrown = "0.15.3"
-indoc = "2.0.6"
-instability = "0.3.7"
-itertools = { version = "0.13.0", default-features = false, features = ["use_alloc"] }
-pretty_assertions = "1.4.1"
-ratatui = { path = "ratatui", version = "0.30.0-alpha.3" }
-ratatui-core = { path = "ratatui-core", version = "0.1.0-alpha.4" }
-ratatui-crossterm = { path = "ratatui-crossterm", version = "0.1.0-alpha.3" }
-ratatui-macros = { path = "ratatui-macros", version = "0.7.0-alpha.2" }
-ratatui-termion = { path = "ratatui-termion", version = "0.1.0-alpha.3" }
-ratatui-termwiz = { path = "ratatui-termwiz", version = "0.1.0-alpha.3" }
-ratatui-widgets = { path = "ratatui-widgets", version = "0.3.0-alpha.3" }
-rstest = "0.25.0"
-serde = { version = "1.0.219", features = ["derive"] }
-serde_json = "1.0.140"
-strum = { version = "0.26.3", default-features = false, features = ["derive"] }
-termion = "4.0.5"
-termwiz = { version = "0.23.3" }
-unicode-segmentation = "1.12.0"
+anstyle = "1"
+bitflags = "2.10"
+clap = { version = "4.5", features = ["derive"] }
+color-eyre = "0.6"
+compact_str = { version = "0.9", default-features = false }
+criterion = { version = "0.8", features = ["html_reports"] }
+crossterm = "0.29"
+document-features = "0.2"
+fakeit = "1"
+futures = "0.3"
+hashbrown = "0.16"
+indoc = "2"
+instability = "0.3"
+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.48"
+palette = "0.7"
+pretty_assertions = "1"
+rand = "0.9"
+rand_chacha = "0.9"
+ratatui = { path = "ratatui", version = "0.30.0-beta.1" }
+ratatui-core = { path = "ratatui-core", version = "0.1.0-beta.1" }
+ratatui-crossterm = { path = "ratatui-crossterm", version = "0.1.0-beta.1" }
+ratatui-macros = { path = "ratatui-macros", version = "0.7.0-beta.1" }
+ratatui-termion = { path = "ratatui-termion", version = "0.1.0-beta.1" }
+ratatui-termwiz = { path = "ratatui-termwiz", version = "0.1.0-beta.1" }
+ratatui-widgets = { path = "ratatui-widgets", version = "0.3.0-beta.1" }
+rstest = "0.26"
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+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 }
+tokio = "1"
+tokio-stream = "0.1"
+tracing = "0.1"
+tracing-appender = "0.2"
+tracing-subscriber = "0.3"
+trybuild = "1"
+unicode-segmentation = "1"
+unicode-truncate = { version = "2", default-features = false }
 # See <https://github.com/ratatui/ratatui/issues/1271> for information about why we pin unicode-width
-unicode-width = "=0.2.0"
+unicode-width = ">=0.2.0, <=0.2.2"
 
 # Improve benchmark consistency
 [profile.bench]
@@ -84,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"
@@ -95,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"

MAINTAINERS.md

@@ -5,7 +5,7 @@ This file documents current and past maintainers.
 - [orhun](https://github.com/orhun)
 - [joshka](https://github.com/joshka)
 - [kdheepak](https://github.com/kdheepak)
-- [Valentin271](https://github.com/Valentin271)
+- [j-g00da](https://github.com/j-g00da)
 
 ## Past Maintainers
 
@@ -13,3 +13,4 @@ This file documents current and past maintainers.
 - [mindoodoo](https://github.com/mindoodoo)
 - [sayanarijit](https://github.com/sayanarijit)
 - [EdJoPaTo](https://github.com/EdJoPaTo)
+- [Valentin271](https://github.com/Valentin271)

README.md

@@ -12,7 +12,7 @@
 
 </details>
 
-![Demo](https://github.com/ratatui/ratatui/blob/87ae72dbc756067c97f6400d3e2a58eeb383776e/examples/demo2-destroy.gif?raw=true)
+![Release header](https://github.com/ratatui/ratatui/blob/b23480adfa9430697071c906c7ba4d4f9bd37a73/assets/release-header.png?raw=true)
 
 <div align="center">
 
@@ -73,6 +73,7 @@ fn render(frame: &mut Frame) {
 - [Ratatui Forum] - a place to ask questions and discuss the library.
 - [Widget Examples] - a collection of examples that demonstrate how to use the library.
 - [App Examples] - a collection of more complex examples that demonstrate how to build apps.
+- [ARCHITECTURE.md] - explains the crate organization and modular workspace structure.
 - [Changelog] - generated by [git-cliff] utilizing [Conventional Commits].
 - [Breaking Changes] - a list of breaking changes in the library.
 
@@ -112,7 +113,16 @@ There is also a [Matrix](https://matrix.org/) bridge available at
 We rely on GitHub for [bugs][Report a bug] and [feature requests][Request a Feature].
 
 Please make sure you read the [contributing](./CONTRIBUTING.md) guidelines before [creating a pull
-request][Create a Pull Request].
+request][Create a Pull Request]. We accept AI generated code, but please read the [AI Contributions]
+guidelines to ensure compliance.
+
+If you'd like to show your support, you can add the Ratatui badge to your project's README:
+
+```md
+[![Built With Ratatui](https://img.shields.io/badge/Built_With_Ratatui-000?logo=ratatui&logoColor=fff)](https://ratatui.rs/)
+```
+
+[![Built With Ratatui](https://img.shields.io/badge/Built_With_Ratatui-000?logo=ratatui&logoColor=fff)](https://ratatui.rs/)
 
 ## Acknowledgements
 
@@ -133,6 +143,7 @@ This project is licensed under the [MIT License][License].
 [Docs]: https://docs.rs/ratatui
 [Widget Examples]: https://github.com/ratatui/ratatui/tree/main/ratatui-widgets/examples
 [App Examples]: https://github.com/ratatui/ratatui/tree/main/examples
+[ARCHITECTURE.md]: https://github.com/ratatui/ratatui/blob/main/ARCHITECTURE.md
 [Changelog]: https://github.com/ratatui/ratatui/blob/main/CHANGELOG.md
 [git-cliff]: https://git-cliff.org
 [Conventional Commits]: https://www.conventionalcommits.org
@@ -142,6 +153,7 @@ This project is licensed under the [MIT License][License].
 [Request a Feature]: https://github.com/ratatui/ratatui/issues/new?labels=enhancement&projects=&template=feature_request.md
 [Create a Pull Request]: https://github.com/ratatui/ratatui/compare
 [Contributing]: https://github.com/ratatui/ratatui/blob/main/CONTRIBUTING.md
+[AI Contributions]: https://github.com/ratatui/ratatui/blob/main/CONTRIBUTING.md#ai-generated-content
 [Crate]: https://crates.io/crates/ratatui
 [tui-rs]: https://crates.io/crates/tui
 [Sponsors]: https://github.com/sponsors/ratatui

assets/logo-simple.svg

@@ -0,0 +1 @@
+<svg role="img" viewBox="0 0 50 50" xmlns="http://www.w3.org/2000/svg"><title>Ratatui</title><path d="M17 29h1v1h1v1h1v1h1v1h1v1h1v1h1v1h1v1h1v1h1v1h1v1h1v1h1v1h1v1h1v1h1v1h1v1h1v1h1v1h1v1h1v1H5v-1H4v-1H3v-1H2v-1H1v-1H0v-2h1v-1h1v-1h1v-1h1v-1h1v-1h1v-1h1v-1h1v-1h1v-1h1v-1h1v-1h1v-1h1v-1h1v-1h1v-1h2zm-2 14h1v1h1v1h1v-2h-1v-1h-1v-1h-1zm0-6h-3v1h1v1h4v-4h-1v-1h-1zm35-21h-1v4h-1v1h-1v1h-1v1h-2v1h-1v1h-1v1h-1v1h-2v9h5v1h1v9h-1v1h-1v2h-1v1h-1v-1h-1v-1h-1v-1h1v-1h1v-1h1v-5h-1v1h-3v1h-1v3h-1v-1h-1v-1h-1v-1h-1v-1h-1v-1h-1v-1h-1v-1h-1v-1h-1v-1h-1v-1h-1v-1h-1v-1h-1v-2h1v-2h1v-1h-2v1h-4v-1h-1v-1h-1v-1h-1v-2h1v-1h1v-1h2v-1h7v-1h1v-1h1v-1h1v-1h1v-1h1v-1h4v-1h3v-1h10zm-17 2h-1v2h1v1h2v-1h1v-2h-1v-1h-2zM29 1h1v9h1v1h1v2h1v2h-1v1h-1v1h-1v1h-1v1h-1v1h-3v-1h-1v-1h-2v-1h-1v-1h-1v-1h-6v-1h-1V9h1V8h1V7h1V6h1V5h1V4h1V3h1V2h1V1h2V0h6z"/></svg>

assets/logo.svg

@@ -0,0 +1 @@
+<svg role="img" viewBox="0 0 50 50" xmlns="http://www.w3.org/2000/svg"><title>Ratatui</title><path d="M50 16h-1v4h-1v1h-1v1h-1v1h-2v1h-1v1h-1v1h-1v1h-2v9h5v1h1v9h-1v1h-1v2h-1v1h-1v-1h-1v1h-2v-1h-1v-1h-1v-1h-1v-1h-1v-1h-1v-1h-1v-1h-1v-1h-1v-1h-1v-1h-1v-1h-1v-1h-1v-1h-1v-1h-1v-1h-1v-1h-1v-1h-1v-1h-1v-1h-1v-1h-1v-1h-2v1h-1v1h-1v1h-1v1h-1v1h-1v1h-1v1H9v1H8v1H7v1H6v1H5v1H4v1H3v1H2v2h1v1h1v1h1v1h1v1h1v1H5v-1H4v-1H3v-1H2v-1H1v-1H0v-2h1v-1h1v-1h1v-1h1v-1h1v-1h1v-1h1v-1h1v-1h1v-1h1v-1h1v-1h1v-1h1v-1h1v-1h1v-1h1v-1h2v1h1v-1h-1v-1h-1v-2h1v-1h1v-1h2v-1h7v-1h1v-1h1v-1h1v-1h1v-1h1v-1h4v-1h3v-1h10zM39 49h1v-1h-1zm2-8h-3v1h-1v3h-1v-1h-1v1h1v1h1v1h1v1h1v-1h1v-1h1v-1h1v-5h-1zm-7 3h1v-1h-1zm-1-1h1v-1h-1zm-1-1h1v-1h-1zm-1-1h1v-1h-1zm-1-1h1v-1h-1zm-1-1h1v-1h-1zm-1-1h1v-1h-1zm-1-1h1v-1h-1zm-1-1h1v-1h-1zm-1-1h1v-1h-1zm-1-1h1v-1h-1zm-5-5h1v1h1v1h1v1h1v1h1v-2h1v-2h1v-1h-2v1h-4v-1h-1zm14-11h-1v2h1v1h2v-1h1v-2h-1v-1h-2zM18 40h1v1h1v2h-1v-1h-1v-1h-1v-2h1zm0-7h1v4h-4v-1h-1v-1h3v-3h1zM29 1h1v9h1v1h1v2h1v2h-1v1h-1v1h-1v1h-1v1h-1v1h-3v-1h-1v-1h-2v-1h-1v-1h-1v-1h-6v-1h-1V9h1V8h1V7h1V6h1V5h1V4h1V3h1V2h1V1h2V0h6z"/></svg>

bacon.toml

@@ -60,6 +60,22 @@ command = ["cargo", "xtask", "hack"]
 [jobs.format]
 command = ["cargo", "xtask", "format"]
 
+[jobs.zizmor-offline]
+# zizmor checks the workflow files for security issues. The offline version is generally faster, but
+# checks for fewer issues.
+command = ["zizmor", "--color", "always", ".github/workflows", "--offline"]
+need_stdout = true
+default_watch = false
+watch = [".github/workflows/"]
+
+[jobs.zizmor-online]
+# zizmor checks the workflow files for security issues. The online version is a bit slower, but it
+# checks for more issues
+command = ["zizmor", "--color", "always", ".github/workflows"]
+need_stdout = true
+default_watch = false
+watch = [".github/workflows/"]
+
 # You may define here keybindings that would be specific to
 # a project, for example a shortcut to launch a specific job.
 # Shortcuts to internal functions (scrolling, toggling, etc.)
@@ -74,3 +90,5 @@ ctrl-v = "job:coverage-unit-tests-only"
 u = "job:test-unit"
 n = "job:nextest"
 f = "job:format"
+z = "job:zizmor-offline"
+shift-z = "job:zizmor-online"

cliff.toml

@@ -24,7 +24,11 @@ body = """
 {%- if not version %}
 ## [unreleased]
 {% else -%}
+{%- if package -%} {# release-plz specific variable #}
 ## {{ package }} - [{{ version }}]({{ release_link }}) - {{ timestamp | date(format="%Y-%m-%d") }}
+{%- else -%}
+## [{{ version }}]({{ self::remote_url() }}/releases/tag/{{ version }}) - {{ timestamp | date(format="%Y-%m-%d") }}
+{%- endif %}
 {% endif -%}
 
 {% macro commit(commit) -%}
@@ -57,16 +61,36 @@ body = """
 {%- endfor -%}
 {%- endfor %}
 
+{%- if not release_link -%}
+{% if github.contributors | filter(attribute="is_first_time", value=true) | length != 0 %}
+### New Contributors
+{%- endif %}\
+{% for contributor in github.contributors | filter(attribute="is_first_time", value=true) %}
+* @{{ contributor.username }} made their first contribution
+{%- if contributor.pr_number %} in \
+[#{{ contributor.pr_number }}]({{ self::remote_url() }}/pull/{{ contributor.pr_number }}) \
+{%- endif %}
+{%- endfor -%}
+{%- endif -%}
+
 {% if version %}
 {% if previous.version %}
-**Full Changelog**: {{ release_link }}
+{%- if release_link -%}
+**Full Changelog**: {{ release_link }} {# release-plz specific variable #}
+{%- else -%}
+**Full Changelog**: {{ self::remote_url() }}/compare/{{ previous.version }}...{{ version }}
+{% endif %}
 {% endif %}
 {% else -%}
   {% raw %}\n{% endraw %}
 {% endif %}
 
 {%- macro remote_url() -%}
+{%- if remote.owner -%} {# release-plz specific variable #}
 https://github.com/{{ remote.owner }}/{{ remote.repo }}\
+{%- else -%}
+https://github.com/{{ remote.github.owner }}/{{ remote.github.repo }}\
+{%- endif -%}
 {% endmacro %}
 """
 # remove the leading and trailing whitespace from the template
@@ -92,6 +116,15 @@ commit_preprocessors = [
   { pattern = '(Clarify README.md)', replace = "docs(readme): ${1}" },
   { pattern = '(Update README.md)', replace = "docs(readme): ${1}" },
   { pattern = '(fix typos|Fix typos)', replace = "fix: ${1}" },
+  # Typos that squeaked through and which would otherwise trigger the typos linter.
+  # Regex obsfucation is to avoid triggering the linter in this file until there's a per file config
+  # See https://github.com/crate-ci/typos/issues/724
+  { pattern = '\<[d]eatil\>', replace = "detail" },
+  { pattern = '\<[f]eatuers\>', replace = "features" },
+  { pattern = '\<[s]pecically\>', replace = "specially" },
+  { pattern = '\<[g]ague\>', replace = "gauge" },
+  { pattern = '\<[i]ntructions\>', replace = "instructions" },
+  { pattern = '\<[i]mplementated\>', replace = "implemented" },
 ]
 # regex for parsing and grouping commits
 commit_parsers = [
@@ -105,13 +138,16 @@ commit_parsers = [
   { message = "^style", group = "<!-- 05 -->Styling" },
   { message = "^test", group = "<!-- 06 -->Testing" },
   { message = "^chore\\(release\\): prepare for", skip = true },
+  { message = "^chore: release", skip = true },
   { message = "^chore\\(pr\\)", skip = true },
   { message = "^chore\\(pull\\)", skip = true },
   { message = "^chore\\(deps\\)", skip = true },
   { message = "^chore\\(changelog\\)", skip = true },
   { message = "^[cC]hore", group = "<!-- 07 -->Miscellaneous Tasks" },
-  { body = ".*security", group = "<!-- 08 -->Security" },
-  { message = "^build", group = "<!-- 09 -->Build" },
+  { message = "^build\\(deps\\)", skip = true },
+  { message = "^build\\(release\\)", skip = true },
+  { message = "^build", group = "<!-- 08 -->Build" },
+  { body = ".*security", group = "<!-- 09 -->Security" },
   { message = "^ci", group = "<!-- 10 -->Continuous Integration" },
   { message = "^revert", group = "<!-- 11 -->Reverted Commits" },
   # handle some old commits styles from pre 0.4
@@ -126,9 +162,9 @@ filter_commits = false
 # glob pattern for matching git tags
 tag_pattern = "v[0-9]*"
 # regex for skipping tags
-skip_tags = "v0.1.0-rc.1"
+skip_tags = "beta|alpha|v0.1.0-rc.1"
 # regex for ignoring tags
-ignore_tags = "alpha"
+ignore_tags = "rc"
 # sort the tags topologically
 topo_order = false
 # sort the commits inside sections by oldest/newest order

deny.toml

@@ -9,7 +9,6 @@ allow = [
   "BSD-3-Clause",
   "ISC",
   "MIT",
-  "OpenSSL",
   "Unicode-3.0",
   "Unicode-DFS-2016",
   "WTFPL",

examples/README.md

@@ -1,7 +1,9 @@
 # Examples
 
 This folder contains examples that are more application focused.
-There are also [widget examples] in `ratatui-widgets`.
+
+> [!TIP]
+> There are also [widget examples] in `ratatui-widgets`.
 
 [widget examples]: ../ratatui-widgets/examples
 
@@ -11,8 +13,9 @@ You can run these examples using:
 cargo run -p example-name
 ```
 
-This folder might use unreleased code. Consider viewing the examples in the `latest` branch instead
-of the `main` branch for code which is guaranteed to work with the released ratatui version.
+> [!NOTE]
+> This folder might use unreleased code. Consider viewing the examples in the `latest` branch instead
+> of the `main` branch for code which is guaranteed to work with the released Ratatui version.
 
 > [!WARNING]
 >
@@ -203,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/advanced-widget-impl/src/main.rs

@@ -13,18 +13,15 @@ use std::time::{Duration, Instant};
 
 use color_eyre::Result;
 use crossterm::event;
+use ratatui::DefaultTerminal;
 use ratatui::buffer::Buffer;
 use ratatui::layout::{Constraint, Layout, Position, Rect, Size};
 use ratatui::style::{Color, Style};
 use ratatui::widgets::{Widget, WidgetRef};
-use ratatui::DefaultTerminal;
 
 fn main() -> Result<()> {
     color_eyre::install()?;
-    let terminal = ratatui::init();
-    let result = App::default().run(terminal);
-    ratatui::restore();
-    result
+    ratatui::run(|terminal| App::default().run(terminal))
 }
 
 #[derive(Default)]
@@ -36,15 +33,15 @@ struct App {
 }
 
 impl App {
-    fn run(mut self, mut terminal: DefaultTerminal) -> Result<()> {
+    fn run(mut self, terminal: &mut DefaultTerminal) -> Result<()> {
         while !self.should_quit {
-            self.draw(&mut terminal)?;
+            self.render(terminal)?;
             self.handle_events()?;
         }
         Ok(())
     }
 
-    fn draw(&mut self, tui: &mut DefaultTerminal) -> Result<()> {
+    fn render(&mut self, tui: &mut DefaultTerminal) -> Result<()> {
         tui.draw(|frame| frame.render_widget(self, frame.area()))?;
         Ok(())
     }
@@ -71,7 +68,7 @@ impl App {
 impl Widget for &mut App {
     fn render(self, area: Rect, buf: &mut Buffer) {
         let constraints = Constraint::from_lengths([1, 1, 2, 1]);
-        let [greeting, timer, squares, position] = Layout::vertical(constraints).areas(area);
+        let [greeting, timer, squares, position] = area.layout(&Layout::vertical(constraints));
 
         // render an ephemeral greeting widget
         Greeting::new("Ratatui!").render(greeting, buf);
@@ -177,9 +174,9 @@ struct BlueSquare;
 impl Widget for &BoxedSquares {
     fn render(self, area: Rect, buf: &mut Buffer) {
         let constraints = vec![Constraint::Length(4); self.squares.len()];
-        let areas = Layout::horizontal(constraints).split(area);
-        for (widget, area) in self.squares.iter().zip(areas.iter()) {
-            widget.render_ref(*area, buf);
+        let areas = area.layout_vec(&Layout::horizontal(constraints));
+        for (widget, area) in self.squares.iter().zip(areas) {
+            widget.render_ref(area, buf);
         }
     }
 }

examples/apps/async-github/Cargo.toml

@@ -14,9 +14,9 @@ edition.workspace = true
 rust-version.workspace = true
 
 [dependencies]
-color-eyre = "0.6.3"
+color-eyre.workspace = true
 crossterm = { workspace = true, features = ["event-stream"] }
-octocrab = "0.44.0"
+octocrab.workspace = true
 ratatui.workspace = true
-tokio = { version = "1.44.2", features = ["rt-multi-thread", "macros"] }
-tokio-stream = "0.1.17"
+tokio = { workspace = true, features = ["rt-multi-thread", "macros"] }
+tokio-stream.workspace = true

examples/apps/async-github/src/main.rs

@@ -32,9 +32,9 @@ use std::time::Duration;
 
 use color_eyre::Result;
 use crossterm::event::{Event, EventStream, KeyCode};
-use octocrab::params::pulls::Sort;
-use octocrab::params::Direction;
 use octocrab::Page;
+use octocrab::params::Direction;
+use octocrab::params::pulls::Sort;
 use ratatui::buffer::Buffer;
 use ratatui::layout::{Constraint, Layout, Rect};
 use ratatui::style::{Style, Stylize};
@@ -78,8 +78,8 @@ impl App {
     }
 
     fn render(&self, frame: &mut Frame) {
-        let vertical = Layout::vertical([Constraint::Length(1), Constraint::Fill(1)]);
-        let [title_area, body_area] = vertical.areas(frame.area());
+        let layout = Layout::vertical([Constraint::Length(1), Constraint::Fill(1)]);
+        let [title_area, body_area] = frame.area().layout(&layout);
         let title = Line::from("Ratatui async example").centered().bold();
         frame.render_widget(title, title_area);
         frame.render_widget(&self.pull_requests, body_area);

examples/apps/calendar-explorer/Cargo.toml

@@ -9,7 +9,7 @@ rust-version.workspace = true
 color-eyre.workspace = true
 crossterm.workspace = true
 ratatui.workspace = true
-time = { version = "0.3.39", features = ["formatting", "parsing"] }
+time = { workspace = true, features = ["formatting", "parsing"] }
 
 [lints]
 workspace = true

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

@@ -22,21 +22,18 @@ use time::{Date, Month, OffsetDateTime};
 
 fn main() -> Result<()> {
     color_eyre::install()?;
-    let terminal = ratatui::init();
-    let result = run(terminal);
-    ratatui::restore();
-    result
+    ratatui::run(run)
 }
 
 /// Run the application.
-fn run(mut terminal: DefaultTerminal) -> Result<()> {
+fn run(terminal: &mut DefaultTerminal) -> Result<()> {
     let mut selected_date = OffsetDateTime::now_local()?.date();
     let mut calendar_style = StyledCalendar::Default;
     loop {
         terminal.draw(|frame| render(frame, calendar_style, selected_date))?;
         if let Some(key) = event::read()?.as_key_press_event() {
             match key.code {
-                KeyCode::Char('q') | KeyCode::Esc => return Ok(()),
+                KeyCode::Char('q') => break Ok(()),
                 KeyCode::Char('s') => calendar_style = calendar_style.next(),
                 KeyCode::Char('n') | KeyCode::Tab => selected_date = next_month(selected_date),
                 KeyCode::Char('p') | KeyCode::BackTab => selected_date = prev_month(selected_date),
@@ -84,11 +81,10 @@ fn render(frame: &mut Frame, calendar_style: StyledCalendar, selected_date: Date
         )),
     ]);
 
-    let vertical = Layout::vertical([
+    let [text_area, area] = frame.area().layout(&Layout::vertical([
         Constraint::Length(header.height() as u16),
         Constraint::Fill(1),
-    ]);
-    let [text_area, area] = vertical.areas(frame.area());
+    ]));
     frame.render_widget(header.centered(), text_area);
     calendar_style
         .render_year(frame, area, selected_date)
@@ -136,16 +132,13 @@ impl StyledCalendar {
     fn render_year(self, frame: &mut Frame, area: Rect, date: Date) -> Result<()> {
         let events = events(date)?;
 
-        let area = area.inner(Margin {
-            vertical: 1,
-            horizontal: 1,
-        });
-        let rows = Layout::vertical([Constraint::Ratio(1, 3); 3]).split(area);
-        let areas = rows.iter().flat_map(|row| {
-            Layout::horizontal([Constraint::Ratio(1, 4); 4])
-                .split(*row)
-                .to_vec()
-        });
+        let vertical = Layout::vertical([Constraint::Ratio(1, 3); 3]);
+        let horizontal = &Layout::horizontal([Constraint::Ratio(1, 4); 4]);
+        let areas = area
+            .inner(Margin::new(1, 1))
+            .layout_vec(&vertical)
+            .into_iter()
+            .flat_map(|row| row.layout_vec(horizontal));
         for (i, area) in areas.enumerate() {
             let month = date
                 .replace_day(1)

examples/apps/canvas/src/main.rs

@@ -14,10 +14,10 @@ use std::{
 };
 
 use color_eyre::Result;
+use crossterm::ExecutableCommand;
 use crossterm::event::{
     self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode, KeyEvent, MouseEventKind,
 };
-use crossterm::ExecutableCommand;
 use itertools::Itertools;
 use ratatui::layout::{Constraint, Layout, Position, Rect};
 use ratatui::style::{Color, Stylize};
@@ -117,13 +117,17 @@ impl App {
         }
     }
 
-    fn cycle_marker(&mut self) {
+    const fn cycle_marker(&mut self) {
         self.marker = match self.marker {
             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!(),
         };
     }
 
@@ -153,16 +157,15 @@ impl App {
 
         let vertical = Layout::vertical([
             Constraint::Length(header.height() as u16),
-            Constraint::Percentage(50),
-            Constraint::Percentage(50),
+            Constraint::Fill(1),
+            Constraint::Fill(1),
         ]);
-        let [text_area, up, down] = vertical.areas(frame.area());
+        let [text_area, up, down] = frame.area().layout(&vertical);
         frame.render_widget(header.centered(), text_area);
 
-        let horizontal =
-            Layout::horizontal([Constraint::Percentage(50), Constraint::Percentage(50)]);
-        let [draw, pong] = horizontal.areas(up);
-        let [map, boxes] = horizontal.areas(down);
+        let horizontal = Layout::horizontal([Constraint::Fill(1); 2]);
+        let [draw, pong] = up.layout(&horizontal);
+        let [map, boxes] = down.layout(&horizontal);
 
         frame.render_widget(self.map_canvas(), map);
         frame.render_widget(self.draw_canvas(draw), draw);

examples/apps/chart/src/main.rs

@@ -21,10 +21,7 @@ use ratatui::{DefaultTerminal, Frame};
 
 fn main() -> Result<()> {
     color_eyre::install()?;
-    let terminal = ratatui::init();
-    let app_result = App::new().run(terminal);
-    ratatui::restore();
-    app_result
+    ratatui::run(|terminal| App::new().run(terminal))
 }
 
 struct App {
@@ -78,7 +75,7 @@ impl App {
         }
     }
 
-    fn run(mut self, mut terminal: DefaultTerminal) -> Result<()> {
+    fn run(mut self, terminal: &mut DefaultTerminal) -> Result<()> {
         let tick_rate = Duration::from_millis(250);
         let mut last_tick = Instant::now();
         loop {
@@ -111,10 +108,11 @@ impl App {
     }
 
     fn render(&self, frame: &mut Frame) {
-        let [top, bottom] = Layout::vertical([Constraint::Fill(1); 2]).areas(frame.area());
-        let [animated_chart, bar_chart] =
-            Layout::horizontal([Constraint::Fill(1), Constraint::Length(29)]).areas(top);
-        let [line_chart, scatter] = Layout::horizontal([Constraint::Fill(1); 2]).areas(bottom);
+        let vertical = Layout::vertical([Constraint::Fill(1); 2]);
+        let [top, bottom] = frame.area().layout(&vertical);
+        let horizontal = Layout::horizontal([Constraint::Fill(1), Constraint::Length(29)]);
+        let [animated_chart, bar_chart] = top.layout(&horizontal);
+        let [line_chart, scatter] = bottom.layout(&Layout::horizontal([Constraint::Fill(1); 2]));
 
         self.render_animated_chart(frame, animated_chart);
         render_barchart(frame, bar_chart);
@@ -128,7 +126,7 @@ impl App {
                 format!("{}", self.window[0]),
                 Style::default().add_modifier(Modifier::BOLD),
             ),
-            Span::raw(format!("{}", (self.window[0] + self.window[1]) / 2.0)),
+            Span::raw(format!("{}", f64::midpoint(self.window[0], self.window[1]))),
             Span::styled(
                 format!("{}", self.window[1]),
                 Style::default().add_modifier(Modifier::BOLD),
@@ -208,12 +206,14 @@ fn render_barchart(frame: &mut Frame, bar_chart: Rect) {
 }
 
 fn render_line_chart(frame: &mut Frame, area: Rect) {
-    let datasets = vec![Dataset::default()
-        .name("Line from only 2 points".italic())
-        .marker(symbols::Marker::Braille)
-        .style(Style::default().fg(Color::Yellow))
-        .graph_type(GraphType::Line)
-        .data(&[(1., 1.), (4., 4.)])];
+    let datasets = vec![
+        Dataset::default()
+            .name("Line from only 2 points".italic())
+            .marker(symbols::Marker::Braille)
+            .style(Style::default().fg(Color::Yellow))
+            .graph_type(GraphType::Line)
+            .data(&[(1., 1.), (4., 4.)]),
+    ];
 
     let chart = Chart::new(datasets)
         .block(Block::bordered().title(Line::from("Line chart").cyan().bold().centered()))

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

@@ -11,40 +11,35 @@
 use color_eyre::Result;
 use crossterm::event;
 use itertools::Itertools;
+use ratatui::Frame;
 use ratatui::layout::{Alignment, Constraint, Layout, Rect};
 use ratatui::style::{Color, Style, Stylize};
 use ratatui::text::Line;
 use ratatui::widgets::{Block, Borders, Paragraph};
-use ratatui::{DefaultTerminal, Frame};
 
 fn main() -> Result<()> {
     color_eyre::install()?;
-    let terminal = ratatui::init();
-    let app_result = run(terminal);
-    ratatui::restore();
-    app_result
-}
-
-fn run(mut terminal: DefaultTerminal) -> Result<()> {
-    loop {
-        terminal.draw(render)?;
-        if event::read()?.is_key_press() {
-            return Ok(());
+    ratatui::run(|terminal| {
+        loop {
+            terminal.draw(render)?;
+            if event::read()?.is_key_press() {
+                return Ok(());
+            }
         }
-    }
+    })
 }
 
 fn render(frame: &mut Frame) {
-    let layout = Layout::vertical([
+    let [named, indexed_colors, indexed_greys] = Layout::vertical([
         Constraint::Length(30),
         Constraint::Length(17),
         Constraint::Length(2),
     ])
-    .split(frame.area());
+    .areas(frame.area());
 
-    render_named_colors(frame, layout[0]);
-    render_indexed_colors(frame, layout[1]);
-    render_indexed_grayscale(frame, layout[2]);
+    render_named_colors(frame, named);
+    render_indexed_colors(frame, indexed_colors);
+    render_indexed_grayscale(frame, indexed_greys);
 }
 
 const NAMED_COLORS: [Color; 16] = [
@@ -87,12 +82,12 @@ fn render_fg_named_colors(frame: &mut Frame, bg: Color, area: Rect) {
     let inner = block.inner(area);
     frame.render_widget(block, area);
 
-    let vertical = Layout::vertical([Constraint::Length(1); 2]).split(inner);
-    let areas = vertical.iter().flat_map(|area| {
-        Layout::horizontal([Constraint::Ratio(1, 8); 8])
-            .split(*area)
-            .to_vec()
-    });
+    let vertical = Layout::vertical([Constraint::Length(1); 2]);
+    let horizontal = Layout::horizontal([Constraint::Ratio(1, 8); 8]);
+    let areas = inner
+        .layout_vec(&vertical)
+        .into_iter()
+        .flat_map(|area| area.layout_vec(&horizontal));
     for (fg, area) in NAMED_COLORS.into_iter().zip(areas) {
         let color_name = fg.to_string();
         let paragraph = Paragraph::new(color_name).fg(fg).bg(bg);
@@ -105,12 +100,12 @@ fn render_bg_named_colors(frame: &mut Frame, fg: Color, area: Rect) {
     let inner = block.inner(area);
     frame.render_widget(block, area);
 
-    let vertical = Layout::vertical([Constraint::Length(1); 2]).split(inner);
-    let areas = vertical.iter().flat_map(|area| {
-        Layout::horizontal([Constraint::Ratio(1, 8); 8])
-            .split(*area)
-            .to_vec()
-    });
+    let vertical = Layout::vertical([Constraint::Length(1); 2]);
+    let horizontal = Layout::horizontal([Constraint::Ratio(1, 8); 8]);
+    let areas = inner
+        .layout_vec(&vertical)
+        .into_iter()
+        .flat_map(|area| area.layout_vec(&horizontal));
     for (bg, area) in NAMED_COLORS.into_iter().zip(areas) {
         let color_name = bg.to_string();
         let paragraph = Paragraph::new(color_name).fg(fg).bg(bg);
@@ -202,7 +197,7 @@ fn title_block(title: String) -> Block<'static> {
         .borders(Borders::TOP)
         .title_alignment(Alignment::Center)
         .border_style(Style::new().dark_gray())
-        .title_style(Style::new().reset())
+        .title_style(Style::reset())
         .title(title)
 }
 

examples/apps/colors-rgb/Cargo.toml

@@ -8,7 +8,7 @@ rust-version.workspace = true
 [dependencies]
 color-eyre.workspace = true
 crossterm.workspace = true
-palette = "0.7.6"
+palette.workspace = true
 ratatui.workspace = true
 
 [lints]

examples/apps/colors-rgb/src/main.rs

@@ -22,19 +22,16 @@ use color_eyre::Result;
 use crossterm::event;
 use palette::convert::FromColorUnclamped;
 use palette::{Okhsv, Srgb};
+use ratatui::DefaultTerminal;
 use ratatui::buffer::Buffer;
 use ratatui::layout::{Constraint, Layout, Position, Rect};
 use ratatui::style::Color;
 use ratatui::text::Text;
 use ratatui::widgets::Widget;
-use ratatui::DefaultTerminal;
 
 fn main() -> Result<()> {
     color_eyre::install()?;
-    let terminal = ratatui::init();
-    let app_result = App::default().run(terminal);
-    ratatui::restore();
-    app_result
+    ratatui::run(|terminal| App::default().run(terminal))
 }
 
 #[derive(Debug, Default)]
@@ -91,7 +88,7 @@ impl App {
     /// Run the app
     ///
     /// This is the main event loop for the app.
-    pub fn run(mut self, mut terminal: DefaultTerminal) -> Result<()> {
+    pub fn run(mut self, terminal: &mut DefaultTerminal) -> Result<()> {
         while self.is_running() {
             terminal.draw(|frame| frame.render_widget(&mut self, frame.area()))?;
             self.handle_events()?;
@@ -127,8 +124,8 @@ impl App {
 impl Widget for &mut App {
     fn render(self, area: Rect, buf: &mut Buffer) {
         use Constraint::{Length, Min};
-        let [top, colors] = Layout::vertical([Length(1), Min(0)]).areas(area);
-        let [title, fps] = Layout::horizontal([Min(0), Length(8)]).areas(top);
+        let [top, colors] = area.layout(&Layout::vertical([Length(1), Min(0)]));
+        let [title, fps] = top.layout(&Layout::horizontal([Min(0), Length(8)]));
         Text::from("colors_rgb example. Press q to quit")
             .centered()
             .render(title, buf);

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

@@ -11,6 +11,7 @@
 use color_eyre::Result;
 use crossterm::event::{self, KeyCode};
 use itertools::Itertools;
+use ratatui::DefaultTerminal;
 use ratatui::buffer::Buffer;
 use ratatui::layout::Constraint::{self, Fill, Length, Max, Min, Percentage, Ratio};
 use ratatui::layout::{Flex, Layout, Rect};
@@ -19,15 +20,11 @@ use ratatui::style::{Color, Style, Stylize};
 use ratatui::symbols::{self, line};
 use ratatui::text::{Line, Span, Text};
 use ratatui::widgets::{Block, Paragraph, Widget, Wrap};
-use ratatui::DefaultTerminal;
 use strum::{Display, EnumIter, FromRepr};
 
 fn main() -> Result<()> {
     color_eyre::install()?;
-    let terminal = ratatui::init();
-    let app_result = App::default().run(terminal);
-    ratatui::restore();
-    app_result
+    ratatui::run(|terminal| App::default().run(terminal))
 }
 
 #[derive(Default)]
@@ -82,7 +79,7 @@ struct SpacerBlock;
 
 // App behaviour
 impl App {
-    fn run(mut self, mut terminal: DefaultTerminal) -> Result<()> {
+    fn run(mut self, terminal: &mut DefaultTerminal) -> Result<()> {
         self.insert_test_defaults();
 
         while self.is_running() {
@@ -239,15 +236,19 @@ impl From<Constraint> for ConstraintName {
 
 impl Widget for &App {
     fn render(self, area: Rect, buf: &mut Buffer) {
-        let [header_area, instructions_area, swap_legend_area, _, blocks_area] =
-            Layout::vertical([
-                Length(2), // header
-                Length(2), // instructions
-                Length(1), // swap key legend
-                Length(1), // gap
-                Fill(1),   // blocks
-            ])
-            .areas(area);
+        let [
+            header_area,
+            instructions_area,
+            swap_legend_area,
+            _,
+            blocks_area,
+        ] = area.layout(&Layout::vertical([
+            Length(2), // header
+            Length(2), // instructions
+            Length(1), // swap key legend
+            Length(1), // gap
+            Fill(1),   // blocks
+        ]));
 
         App::header().render(header_area, buf);
         App::instructions().render(instructions_area, buf);
@@ -317,20 +318,26 @@ impl App {
     }
 
     fn render_layout_blocks(&self, area: Rect, buf: &mut Buffer) {
-        let [user_constraints, area] = Layout::vertical([Length(3), Fill(1)])
-            .spacing(1)
-            .areas(area);
+        let main_layout = Layout::vertical([Length(3), Fill(1)]).spacing(1);
+        let [user_constraints, area] = area.layout(&main_layout);
 
         self.render_user_constraints_legend(user_constraints, buf);
 
-        let [start, center, end, space_around, space_between] =
-            Layout::vertical([Length(7); 5]).areas(area);
+        let [
+            start,
+            center,
+            end,
+            space_between,
+            space_around,
+            space_evenly,
+        ] = area.layout(&Layout::vertical([Length(7); 6]));
 
         self.render_layout_block(Flex::Start, start, buf);
         self.render_layout_block(Flex::Center, center, buf);
         self.render_layout_block(Flex::End, end, buf);
-        self.render_layout_block(Flex::SpaceAround, space_around, buf);
         self.render_layout_block(Flex::SpaceBetween, space_between, buf);
+        self.render_layout_block(Flex::SpaceAround, space_around, buf);
+        self.render_layout_block(Flex::SpaceEvenly, space_evenly, buf);
     }
 
     fn render_user_constraints_legend(&self, area: Rect, buf: &mut Buffer) {
@@ -344,8 +351,8 @@ impl App {
     }
 
     fn render_layout_block(&self, flex: Flex, area: Rect, buf: &mut Buffer) {
-        let [label_area, axis_area, blocks_area] =
-            Layout::vertical([Length(1), Max(1), Length(4)]).areas(area);
+        let layout = Layout::vertical([Length(1), Max(1), Length(4)]);
+        let [label_area, axis_area, blocks_area] = area.layout(&layout);
 
         if label_area.height > 0 {
             format!("Flex::{flex:?}").bold().render(label_area, buf);

examples/apps/constraints/src/main.rs

@@ -17,7 +17,7 @@ use ratatui::widgets::{
     Block, Padding, Paragraph, Scrollbar, ScrollbarOrientation, ScrollbarState, StatefulWidget,
     Tabs, Widget,
 };
-use ratatui::{symbols, DefaultTerminal};
+use ratatui::{DefaultTerminal, symbols};
 use strum::{Display, EnumIter, FromRepr, IntoEnumIterator};
 
 const SPACER_HEIGHT: u16 = 0;
@@ -36,10 +36,7 @@ const FILL_COLOR: Color = tailwind::SLATE.c950;
 
 fn main() -> Result<()> {
     color_eyre::install()?;
-    let terminal = ratatui::init();
-    let app_result = App::default().run(terminal);
-    ratatui::restore();
-    app_result
+    ratatui::run(|terminal| App::default().run(terminal))
 }
 
 #[derive(Default, Clone, Copy)]
@@ -72,7 +69,7 @@ enum AppState {
 }
 
 impl App {
-    fn run(mut self, mut terminal: DefaultTerminal) -> Result<()> {
+    fn run(mut self, terminal: &mut DefaultTerminal) -> Result<()> {
         self.update_max_scroll_offset();
         while self.is_running() {
             terminal.draw(|frame| frame.render_widget(self, frame.area()))?;
@@ -143,7 +140,7 @@ impl App {
 
 impl Widget for App {
     fn render(self, area: Rect, buf: &mut Buffer) {
-        let [tabs, axis, demo] = Layout::vertical([Length(3), Length(3), Fill(0)]).areas(area);
+        let [tabs, axis, demo] = area.layout(&Layout::vertical([Length(3), Length(3), Fill(0)]));
 
         self.render_tabs(tabs, buf);
         Self::render_axis(axis, buf);
@@ -284,8 +281,8 @@ impl Widget for SelectedTab {
 
 impl SelectedTab {
     fn render_length_example(area: Rect, buf: &mut Buffer) {
-        let [example1, example2, example3, _] =
-            Layout::vertical([Length(EXAMPLE_HEIGHT); 4]).areas(area);
+        let layout = Layout::vertical([Length(EXAMPLE_HEIGHT); 4]);
+        let [example1, example2, example3, _] = area.layout(&layout);
 
         Example::new(&[Length(20), Length(20)]).render(example1, buf);
         Example::new(&[Length(20), Min(20)]).render(example2, buf);
@@ -293,8 +290,8 @@ impl SelectedTab {
     }
 
     fn render_percentage_example(area: Rect, buf: &mut Buffer) {
-        let [example1, example2, example3, example4, example5, _] =
-            Layout::vertical([Length(EXAMPLE_HEIGHT); 6]).areas(area);
+        let layout = Layout::vertical([Length(EXAMPLE_HEIGHT); 6]);
+        let [example1, example2, example3, example4, example5, _] = area.layout(&layout);
 
         Example::new(&[Percentage(75), Fill(0)]).render(example1, buf);
         Example::new(&[Percentage(25), Fill(0)]).render(example2, buf);
@@ -304,8 +301,8 @@ impl SelectedTab {
     }
 
     fn render_ratio_example(area: Rect, buf: &mut Buffer) {
-        let [example1, example2, example3, example4, _] =
-            Layout::vertical([Length(EXAMPLE_HEIGHT); 5]).areas(area);
+        let layout = Layout::vertical([Length(EXAMPLE_HEIGHT); 5]);
+        let [example1, example2, example3, example4, _] = area.layout(&layout);
 
         Example::new(&[Ratio(1, 2); 2]).render(example1, buf);
         Example::new(&[Ratio(1, 4); 4]).render(example2, buf);
@@ -314,15 +311,15 @@ impl SelectedTab {
     }
 
     fn render_fill_example(area: Rect, buf: &mut Buffer) {
-        let [example1, example2, _] = Layout::vertical([Length(EXAMPLE_HEIGHT); 3]).areas(area);
+        let [example1, example2, _] = area.layout(&Layout::vertical([Length(EXAMPLE_HEIGHT); 3]));
 
         Example::new(&[Fill(1), Fill(2), Fill(3)]).render(example1, buf);
         Example::new(&[Fill(1), Percentage(50), Fill(1)]).render(example2, buf);
     }
 
     fn render_min_example(area: Rect, buf: &mut Buffer) {
-        let [example1, example2, example3, example4, example5, _] =
-            Layout::vertical([Length(EXAMPLE_HEIGHT); 6]).areas(area);
+        let layout = Layout::vertical([Length(EXAMPLE_HEIGHT); 6]);
+        let [example1, example2, example3, example4, example5, _] = area.layout(&layout);
 
         Example::new(&[Percentage(100), Min(0)]).render(example1, buf);
         Example::new(&[Percentage(100), Min(20)]).render(example2, buf);
@@ -332,8 +329,8 @@ impl SelectedTab {
     }
 
     fn render_max_example(area: Rect, buf: &mut Buffer) {
-        let [example1, example2, example3, example4, example5, _] =
-            Layout::vertical([Length(EXAMPLE_HEIGHT); 6]).areas(area);
+        let layout = Layout::vertical([Length(EXAMPLE_HEIGHT); 6]);
+        let [example1, example2, example3, example4, example5, _] = area.layout(&layout);
 
         Example::new(&[Percentage(0), Max(0)]).render(example1, buf);
         Example::new(&[Percentage(0), Max(20)]).render(example2, buf);
@@ -357,9 +354,10 @@ impl Example {
 
 impl Widget for Example {
     fn render(self, area: Rect, buf: &mut Buffer) {
-        let [area, _] =
-            Layout::vertical([Length(ILLUSTRATION_HEIGHT), Length(SPACER_HEIGHT)]).areas(area);
-        let blocks = Layout::horizontal(&self.constraints).split(area);
+        let vertical = Layout::vertical([Length(ILLUSTRATION_HEIGHT), Length(SPACER_HEIGHT)]);
+        let horizontal = Layout::horizontal(&self.constraints);
+        let [area, _] = area.layout(&vertical);
+        let blocks = area.layout_vec(&horizontal);
 
         for (block, constraint) in blocks.iter().zip(&self.constraints) {
             Self::illustration(*constraint, block.width).render(*block, buf);

examples/apps/custom-widget/src/main.rs

@@ -15,7 +15,7 @@ use crossterm::event::{
 };
 use crossterm::execute;
 use ratatui::buffer::Buffer;
-use ratatui::layout::{Constraint, Layout, Rect};
+use ratatui::layout::{Constraint, Flex, Layout, Rect};
 use ratatui::style::{Color, Style};
 use ratatui::text::Line;
 use ratatui::widgets::{Paragraph, Widget};
@@ -167,13 +167,13 @@ fn run(mut terminal: DefaultTerminal) -> Result<()> {
 }
 
 fn render(frame: &mut Frame, states: [State; 3]) {
-    let vertical = Layout::vertical([
+    let layout = Layout::vertical([
         Constraint::Length(1),
         Constraint::Max(3),
         Constraint::Length(1),
         Constraint::Min(0), // ignore remaining space
     ]);
-    let [title, buttons, help, _] = vertical.areas(frame.area());
+    let [title, buttons, help, _] = frame.area().layout(&layout);
 
     frame.render_widget(
         Paragraph::new("Custom Widget Example (mouse enabled)"),
@@ -184,13 +184,8 @@ fn render(frame: &mut Frame, states: [State; 3]) {
 }
 
 fn render_buttons(frame: &mut Frame<'_>, area: Rect, states: [State; 3]) {
-    let horizontal = Layout::horizontal([
-        Constraint::Length(15),
-        Constraint::Length(15),
-        Constraint::Length(15),
-        Constraint::Min(0), // ignore remaining space
-    ]);
-    let [red, green, blue, _] = horizontal.areas(area);
+    let layout = Layout::horizontal([Constraint::Length(15); 3]).flex(Flex::Start);
+    let [red, green, blue] = area.layout(&layout);
 
     frame.render_widget(Button::new("Red").theme(RED).state(states[0]), red);
     frame.render_widget(Button::new("Green").theme(GREEN).state(states[1]), green);

examples/apps/demo/Cargo.toml

@@ -12,9 +12,9 @@ termion = ["ratatui/termion", "dep:termion"]
 termwiz = ["ratatui/termwiz", "dep:termwiz"]
 
 [dependencies]
-clap = { version = "4.5.37", features = ["derive"] }
+clap.workspace = true
 crossterm = { workspace = true, optional = true }
-rand = "0.9.1"
+rand.workspace = true
 ratatui.workspace = true
 termwiz = { workspace = true, optional = true }
 

examples/apps/demo/src/crossterm.rs

@@ -5,10 +5,10 @@ use std::time::{Duration, Instant};
 use crossterm::event::{self, DisableMouseCapture, EnableMouseCapture, KeyCode};
 use crossterm::execute;
 use crossterm::terminal::{
-    disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen,
+    EnterAlternateScreen, LeaveAlternateScreen, disable_raw_mode, enable_raw_mode,
 };
-use ratatui::backend::{Backend, CrosstermBackend};
 use ratatui::Terminal;
+use ratatui::backend::{Backend, CrosstermBackend};
 
 use crate::app::App;
 use crate::ui;
@@ -51,7 +51,7 @@ where
 {
     let mut last_tick = Instant::now();
     loop {
-        terminal.draw(|frame| ui::draw(frame, &mut app))?;
+        terminal.draw(|frame| ui::render(frame, &mut app))?;
 
         let timeout = tick_rate.saturating_sub(last_tick.elapsed());
         if !event::poll(timeout)? {

examples/apps/demo/src/termion.rs

@@ -4,8 +4,8 @@ use std::sync::mpsc;
 use std::time::Duration;
 use std::{io, thread};
 
-use ratatui::backend::{Backend, TermionBackend};
 use ratatui::Terminal;
+use ratatui::backend::{Backend, TermionBackend};
 use termion::event::Key;
 use termion::input::{MouseTerminal, TermRead};
 use termion::raw::IntoRawMode;
@@ -42,7 +42,7 @@ where
 {
     let events = events(tick_rate);
     loop {
-        terminal.draw(|frame| ui::draw(frame, &mut app))?;
+        terminal.draw(|frame| ui::render(frame, &mut app))?;
 
         match events.recv()? {
             Event::Input(key) => match key {
@@ -78,12 +78,14 @@ fn events(tick_rate: Duration) -> mpsc::Receiver<Event> {
             }
         }
     });
-    thread::spawn(move || loop {
-        if let Err(err) = tx.send(Event::Tick) {
-            eprintln!("{err}");
-            break;
+    thread::spawn(move || {
+        loop {
+            if let Err(err) = tx.send(Event::Tick) {
+                eprintln!("{err}");
+                break;
+            }
+            thread::sleep(tick_rate);
         }
-        thread::sleep(tick_rate);
     });
     rx
 }

examples/apps/demo/src/termwiz.rs

@@ -2,8 +2,8 @@
 use std::error::Error;
 use std::time::{Duration, Instant};
 
-use ratatui::backend::TermwizBackend;
 use ratatui::Terminal;
+use ratatui::backend::TermwizBackend;
 use termwiz::input::{InputEvent, KeyCode};
 use termwiz::terminal::Terminal as TermwizTerminal;
 
@@ -36,7 +36,7 @@ fn run_app(
 ) -> Result<(), Box<dyn Error>> {
     let mut last_tick = Instant::now();
     loop {
-        terminal.draw(|frame| ui::draw(frame, &mut app))?;
+        terminal.draw(|frame| ui::render(frame, &mut app))?;
 
         let timeout = tick_rate.saturating_sub(last_tick.elapsed());
         if let Some(input) = terminal

examples/apps/demo/src/ui.rs

@@ -6,11 +6,11 @@ use ratatui::widgets::{
     Axis, BarChart, Block, Cell, Chart, Dataset, Gauge, LineGauge, List, ListItem, Paragraph, Row,
     Sparkline, Table, Tabs, Wrap,
 };
-use ratatui::{symbols, Frame};
+use ratatui::{Frame, symbols};
 
 use crate::app::App;
 
-pub fn draw(frame: &mut Frame, app: &mut App) {
+pub fn render(frame: &mut Frame, app: &mut App) {
     let chunks = Layout::vertical([Constraint::Length(3), Constraint::Min(0)]).split(frame.area());
     let tabs = app
         .tabs
@@ -235,7 +235,9 @@ fn draw_charts(frame: &mut Frame, app: &mut App, area: Rect) {
 
 fn draw_text(frame: &mut Frame, area: Rect) {
     let text = vec![
-        text::Line::from("This is a paragraph with several lines. You can change style your text the way you want"),
+        text::Line::from(
+            "This is a paragraph with several lines. You can change style your text the way you want",
+        ),
         text::Line::from(""),
         text::Line::from(vec![
             Span::from("For example: "),
@@ -250,16 +252,17 @@ fn draw_text(frame: &mut Frame, area: Rect) {
             Span::raw("Oh and if you didn't "),
             Span::styled("notice", Style::default().add_modifier(Modifier::ITALIC)),
             Span::raw(" you can "),
-            Span::styled("automatically", Style::default().add_modifier(Modifier::BOLD)),
+            Span::styled(
+                "automatically",
+                Style::default().add_modifier(Modifier::BOLD),
+            ),
             Span::raw(" "),
             Span::styled("wrap", Style::default().add_modifier(Modifier::REVERSED)),
             Span::raw(" your "),
             Span::styled("text", Style::default().add_modifier(Modifier::UNDERLINED)),
-            Span::raw(".")
+            Span::raw("."),
         ]),
-        text::Line::from(
-            "One more thing is that it should display unicode characters: 10€"
-        ),
+        text::Line::from("One more thing is that it should display unicode characters: 10€"),
     ];
     let block = Block::bordered().title(Span::styled(
         "Footer",

examples/apps/demo2/Cargo.toml

@@ -6,14 +6,14 @@ edition.workspace = true
 rust-version.workspace = true
 
 [dependencies]
-color-eyre = "0.6.3"
+color-eyre.workspace = true
 crossterm.workspace = true
 indoc.workspace = true
 itertools.workspace = true
-palette = "0.7.6"
-rand = "0.9.1"
-rand_chacha = "0.9.0"
+palette.workspace = true
+rand.workspace = true
+rand_chacha.workspace = true
 ratatui = { workspace = true, features = ["all-widgets"] }
 strum.workspace = true
-time = "0.3.39"
-unicode-width = "0.2.0"
+time.workspace = true
+unicode-width.workspace = true

examples/apps/demo2/src/app.rs

@@ -1,7 +1,7 @@
 use std::time::Duration;
 
-use color_eyre::eyre::Context;
 use color_eyre::Result;
+use color_eyre::eyre::Context;
 use crossterm::event::{self, KeyCode};
 use itertools::Itertools;
 use ratatui::buffer::Buffer;
@@ -13,7 +13,7 @@ use ratatui::{DefaultTerminal, Frame};
 use strum::{Display, EnumIter, FromRepr, IntoEnumIterator};
 
 use crate::tabs::{AboutTab, EmailTab, RecipeTab, TracerouteTab, WeatherTab};
-use crate::{destroy, THEME};
+use crate::{THEME, destroy};
 
 #[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
 pub struct App {
@@ -129,12 +129,12 @@ impl App {
 /// matter, but for larger apps this can be a significant performance improvement.
 impl Widget for &App {
     fn render(self, area: Rect, buf: &mut Buffer) {
-        let vertical = Layout::vertical([
+        let layout = Layout::vertical([
             Constraint::Length(1),
             Constraint::Min(0),
             Constraint::Length(1),
         ]);
-        let [title_bar, tab, bottom_bar] = vertical.areas(area);
+        let [title_bar, tab, bottom_bar] = area.layout(&layout);
 
         Block::new().style(THEME.root).render(area, buf);
         self.render_title_bar(title_bar, buf);
@@ -146,7 +146,7 @@ impl Widget for &App {
 impl App {
     fn render_title_bar(&self, area: Rect, buf: &mut Buffer) {
         let layout = Layout::horizontal([Constraint::Min(0), Constraint::Length(43)]);
-        let [title, tabs] = layout.areas(area);
+        let [title, tabs] = area.layout(&layout);
 
         Span::styled("Ratatui", THEME.app_title).render(title, buf);
         let titles = Tab::iter().map(Tab::title);

examples/apps/demo2/src/destroy.rs

@@ -1,11 +1,11 @@
 use rand::Rng;
 use rand_chacha::rand_core::SeedableRng;
+use ratatui::Frame;
 use ratatui::buffer::Buffer;
 use ratatui::layout::{Flex, Layout, Rect};
 use ratatui::style::{Color, Style};
 use ratatui::text::Text;
 use ratatui::widgets::Widget;
-use ratatui::Frame;
 
 /// delay the start of the animation so it doesn't start immediately
 const DELAY: usize = 120;
@@ -134,7 +134,7 @@ fn blend(mask_color: Color, cell_color: Color, percentage: f64) -> Color {
 fn centered_rect(area: Rect, width: u16, height: u16) -> Rect {
     let horizontal = Layout::horizontal([width]).flex(Flex::Center);
     let vertical = Layout::vertical([height]).flex(Flex::Center);
-    let [area] = vertical.areas(area);
-    let [area] = horizontal.areas(area);
+    let [area] = area.layout(&vertical);
+    let [area] = area.layout(&horizontal);
     area
 }

examples/apps/demo2/src/main.rs

@@ -34,7 +34,7 @@ use crossterm::terminal::{EnterAlternateScreen, LeaveAlternateScreen};
 use ratatui::layout::Rect;
 use ratatui::{TerminalOptions, Viewport};
 
-pub use self::colors::{color_from_oklab, RgbSwatch};
+pub use self::colors::{RgbSwatch, color_from_oklab};
 pub use self::theme::THEME;
 
 fn main() -> Result<()> {

examples/apps/demo2/src/tabs/about.rs

@@ -24,8 +24,8 @@ impl AboutTab {
 impl Widget for AboutTab {
     fn render(self, area: Rect, buf: &mut Buffer) {
         RgbSwatch.render(area, buf);
-        let horizontal = Layout::horizontal([Constraint::Length(34), Constraint::Min(0)]);
-        let [logo_area, description] = horizontal.areas(area);
+        let layout = Layout::horizontal([Constraint::Length(34), Constraint::Min(0)]);
+        let [logo_area, description] = area.layout(&layout);
         render_crate_description(description, buf);
         let eye_state = if self.row_index % 2 == 0 {
             MascotEyeColor::Default

examples/apps/demo2/src/tabs/email.rs

@@ -71,15 +71,15 @@ impl Widget for EmailTab {
             horizontal: 2,
         });
         Clear.render(area, buf);
-        let vertical = Layout::vertical([Constraint::Length(5), Constraint::Min(0)]);
-        let [inbox, email] = vertical.areas(area);
+        let layout = Layout::vertical([Constraint::Length(5), Constraint::Min(0)]);
+        let [inbox, email] = area.layout(&layout);
         render_inbox(self.row_index, inbox, buf);
         render_email(self.row_index, email, buf);
     }
 }
 fn render_inbox(selected_index: usize, area: Rect, buf: &mut Buffer) {
-    let vertical = Layout::vertical([Constraint::Length(1), Constraint::Min(0)]);
-    let [tabs, inbox] = vertical.areas(area);
+    let layout = Layout::vertical([Constraint::Length(1), Constraint::Min(0)]);
+    let [tabs, inbox] = area.layout(&layout);
     let theme = THEME.email;
     Tabs::new(vec![" Inbox ", " Sent ", " Drafts "])
         .style(theme.tabs)
@@ -130,8 +130,8 @@ fn render_email(selected_index: usize, area: Rect, buf: &mut Buffer) {
     let inner = block.inner(area);
     block.render(area, buf);
     if let Some(email) = email {
-        let vertical = Layout::vertical([Constraint::Length(3), Constraint::Min(0)]);
-        let [headers_area, body_area] = vertical.areas(inner);
+        let layout = Layout::vertical([Constraint::Length(3), Constraint::Min(0)]);
+        let [headers_area, body_area] = inner.layout(&layout);
         let headers = vec![
             Line::from(vec![
                 "From: ".set_style(theme.header),

examples/apps/demo2/src/tabs/recipe.rs

@@ -135,8 +135,8 @@ impl Widget for RecipeTab {
             horizontal: 2,
             vertical: 1,
         });
-        let [recipe, ingredients] =
-            Layout::horizontal([Constraint::Length(44), Constraint::Min(0)]).areas(area);
+        let layout = Layout::horizontal([Constraint::Length(44), Constraint::Min(0)]);
+        let [recipe, ingredients] = area.layout(&layout);
 
         render_recipe(recipe, buf);
         render_ingredients(self.row_index, ingredients, buf);

examples/apps/demo2/src/tabs/traceroute.rs

@@ -39,8 +39,8 @@ impl Widget for TracerouteTab {
         Block::new().style(THEME.content).render(area, buf);
         let horizontal = Layout::horizontal([Constraint::Ratio(1, 2), Constraint::Ratio(1, 2)]);
         let vertical = Layout::vertical([Constraint::Min(0), Constraint::Length(3)]);
-        let [left, map] = horizontal.areas(area);
-        let [hops, pings] = vertical.areas(left);
+        let [left, map] = area.layout(&horizontal);
+        let [hops, pings] = left.layout(&vertical);
 
         render_hops(self.row_index, hops, buf);
         render_ping(self.row_index, pings, buf);

examples/apps/demo2/src/tabs/weather.rs

@@ -2,13 +2,13 @@ use itertools::Itertools;
 use palette::Okhsv;
 use ratatui::buffer::Buffer;
 use ratatui::layout::{Constraint, Direction, Layout, Margin, Rect};
-use ratatui::style::{Color, Style, Stylize};
+use ratatui::style::{Color, Style};
 use ratatui::symbols;
 use ratatui::widgets::calendar::{CalendarEventStore, Monthly};
 use ratatui::widgets::{Bar, BarChart, BarGroup, Block, Clear, LineGauge, Padding, Widget};
 use time::OffsetDateTime;
 
-use crate::{color_from_oklab, RgbSwatch, THEME};
+use crate::{RgbSwatch, THEME, color_from_oklab};
 
 #[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
 pub struct WeatherTab {
@@ -41,16 +41,16 @@ impl Widget for WeatherTab {
             horizontal: 2,
             vertical: 1,
         });
-        let [main, _, gauges] = Layout::vertical([
+        let tab_layout = Layout::vertical([
             Constraint::Min(0),
             Constraint::Length(1),
             Constraint::Length(1),
-        ])
-        .areas(area);
-        let [calendar, charts] =
-            Layout::horizontal([Constraint::Length(23), Constraint::Min(0)]).areas(main);
-        let [simple, horizontal] =
-            Layout::vertical([Constraint::Length(29), Constraint::Min(0)]).areas(charts);
+        ]);
+        let [main, _, gauges] = area.layout(&tab_layout);
+        let main_layout = Layout::horizontal([Constraint::Length(23), Constraint::Min(0)]);
+        let [calendar, charts] = main.layout(&main_layout);
+        let charts_layout = Layout::vertical([Constraint::Length(29), Constraint::Min(0)]);
+        let [simple, horizontal] = charts.layout(&charts_layout);
 
         render_calendar(calendar, buf);
         render_simple_barchart(simple, buf);

examples/apps/flex/src/main.rs

@@ -12,6 +12,7 @@ use std::num::NonZeroUsize;
 
 use color_eyre::Result;
 use crossterm::event::{self, KeyCode};
+use ratatui::DefaultTerminal;
 use ratatui::buffer::Buffer;
 use ratatui::layout::Constraint::{self, Fill, Length, Max, Min, Percentage, Ratio};
 use ratatui::layout::{Alignment, Flex, Layout, Rect};
@@ -22,21 +23,17 @@ use ratatui::text::{Line, Text};
 use ratatui::widgets::{
     Block, Paragraph, Scrollbar, ScrollbarOrientation, ScrollbarState, StatefulWidget, Tabs, Widget,
 };
-use ratatui::DefaultTerminal;
 use strum::{Display, EnumIter, FromRepr, IntoEnumIterator};
 
 fn main() -> Result<()> {
     color_eyre::install()?;
-    let terminal = ratatui::init();
-    let app_result = App::default().run(terminal);
-    ratatui::restore();
-    app_result
+    ratatui::run(|terminal| App::default().run(terminal))
 }
 
 const EXAMPLE_DATA: &[(&str, &[Constraint])] = &[
     (
         "Min(u16) takes any excess space always",
-        &[Length(10), Min(10), Max(10), Percentage(10), Ratio(1,10)],
+        &[Length(10), Min(10), Max(10), Percentage(10), Ratio(1, 10)],
     ),
     (
         "Fill(u16) takes any excess space always",
@@ -44,20 +41,18 @@ const EXAMPLE_DATA: &[(&str, &[Constraint])] = &[
     ),
     (
         "Here's all constraints in one line",
-        &[Length(10), Min(10), Max(10), Percentage(10), Ratio(1,10), Fill(1)],
-    ),
-    (
-        "",
-        &[Max(50), Min(50)],
-    ),
-    (
-        "",
-        &[Max(20), Length(10)],
-    ),
-    (
-        "",
-        &[Max(20), Length(10)],
+        &[
+            Length(10),
+            Min(10),
+            Max(10),
+            Percentage(10),
+            Ratio(1, 10),
+            Fill(1),
+        ],
     ),
+    ("", &[Max(50), Min(50)]),
+    ("", &[Max(20), Length(10)]),
+    ("", &[Max(20), Length(10)]),
     (
         "Min grows always but also allows Fill to grow",
         &[Percentage(50), Fill(1), Fill(2), Min(50)],
@@ -67,44 +62,58 @@ const EXAMPLE_DATA: &[(&str, &[Constraint])] = &[
         &[Length(20), Length(20), Percentage(20)],
     ),
     ("", &[Length(20), Percentage(20), Length(20)]),
-    ("A lowest priority constraint will be broken before a high priority constraint", &[Ratio(1,4), Percentage(20)]),
-    ("`Length` is higher priority than `Percentage`", &[Percentage(20), Length(10)]),
-    ("`Min/Max` is higher priority than `Length`", &[Length(10), Max(20)]),
+    (
+        "A lowest priority constraint will be broken before a high priority constraint",
+        &[Ratio(1, 4), Percentage(20)],
+    ),
+    (
+        "`Length` is higher priority than `Percentage`",
+        &[Percentage(20), Length(10)],
+    ),
+    (
+        "`Min/Max` is higher priority than `Length`",
+        &[Length(10), Max(20)],
+    ),
     ("", &[Length(100), Min(20)]),
-    ("`Length` is higher priority than `Min/Max`", &[Max(20), Length(10)]),
+    (
+        "`Length` is higher priority than `Min/Max`",
+        &[Max(20), Length(10)],
+    ),
     ("", &[Min(20), Length(90)]),
-    ("Fill is the lowest priority and will fill any excess space", &[Fill(1), Ratio(1, 4)]),
-    ("Fill can be used to scale proportionally with other Fill blocks", &[Fill(1), Percentage(20), Fill(2)]),
+    (
+        "Fill is the lowest priority and will fill any excess space",
+        &[Fill(1), Ratio(1, 4)],
+    ),
+    (
+        "Fill can be used to scale proportionally with other Fill blocks",
+        &[Fill(1), Percentage(20), Fill(2)],
+    ),
     ("", &[Ratio(1, 3), Percentage(20), Ratio(2, 3)]),
-    ("Legacy will stretch the last lowest priority constraint\nStretch will only stretch equal weighted constraints", &[Length(20), Length(15)]),
+    (
+        "Legacy will stretch the last lowest priority constraint\nStretch will only stretch equal weighted constraints",
+        &[Length(20), Length(15)],
+    ),
     ("", &[Percentage(20), Length(15)]),
-    ("`Fill(u16)` fills up excess space, but is lower priority to spacers.\ni.e. Fill will only have widths in Flex::Stretch and Flex::Legacy", &[Fill(1), Fill(1)]),
+    (
+        "`Fill(u16)` fills up excess space, but is lower priority to spacers.\ni.e. Fill will only have widths in Flex::Stretch and Flex::Legacy",
+        &[Fill(1), Fill(1)],
+    ),
     ("", &[Length(20), Length(20)]),
     (
         "When not using `Flex::Stretch` or `Flex::Legacy`,\n`Min(u16)` and `Max(u16)` collapse to their lowest values",
         &[Min(20), Max(20)],
     ),
-    (
-        "",
-        &[Max(20)],
-    ),
+    ("", &[Max(20)]),
     ("", &[Min(20), Max(20), Length(20), Length(20)]),
     ("", &[Fill(0), Fill(0)]),
     (
         "`Fill(1)` can be to scale with respect to other `Fill(2)`",
         &[Fill(1), Fill(2)],
     ),
-    (
-        "",
-        &[Fill(1), Min(10), Max(10), Fill(2)],
-    ),
+    ("", &[Fill(1), Min(10), Max(10), Fill(2)]),
     (
         "`Fill(0)` collapses if there are other non-zero `Fill(_)`\nconstraints. e.g. `[Fill(0), Fill(0), Fill(1)]`:",
-        &[
-            Fill(0),
-            Fill(0),
-            Fill(1),
-        ],
+        &[Fill(0), Fill(0), Fill(1)],
     ),
 ];
 
@@ -144,11 +153,12 @@ enum SelectedTab {
     Center,
     End,
     SpaceAround,
+    SpaceEvenly,
     SpaceBetween,
 }
 
 impl App {
-    fn run(mut self, mut terminal: DefaultTerminal) -> Result<()> {
+    fn run(mut self, terminal: &mut DefaultTerminal) -> Result<()> {
         // increase the layout cache to account for the number of layout events. This ensures that
         // layout is not generally reprocessed on every frame (which would lead to possible janky
         // results when there are more than one possible solution to the requested layout). This
@@ -246,7 +256,7 @@ fn example_height() -> u16 {
 impl Widget for App {
     fn render(self, area: Rect, buf: &mut Buffer) {
         let layout = Layout::vertical([Length(3), Length(1), Fill(0)]);
-        let [tabs, axis, demo] = layout.areas(area);
+        let [tabs, axis, demo] = area.layout(&layout);
         self.tabs().render(tabs, buf);
         let scroll_needed = self.render_demo(demo, buf);
         let axis_width = if scroll_needed {
@@ -360,8 +370,9 @@ impl SelectedTab {
             Self::Start => SKY.c400,
             Self::Center => SKY.c300,
             Self::End => SKY.c200,
-            Self::SpaceAround => INDIGO.c400,
+            Self::SpaceEvenly => INDIGO.c400,
             Self::SpaceBetween => INDIGO.c300,
+            Self::SpaceAround => INDIGO.c500,
         };
         format!(" {text} ").fg(color).bg(Color::Black).into()
     }
@@ -376,8 +387,9 @@ impl StatefulWidget for SelectedTab {
             Self::Start => Self::render_examples(area, buf, Flex::Start, spacing),
             Self::Center => Self::render_examples(area, buf, Flex::Center, spacing),
             Self::End => Self::render_examples(area, buf, Flex::End, spacing),
-            Self::SpaceAround => Self::render_examples(area, buf, Flex::SpaceAround, spacing),
+            Self::SpaceEvenly => Self::render_examples(area, buf, Flex::SpaceEvenly, spacing),
             Self::SpaceBetween => Self::render_examples(area, buf, Flex::SpaceBetween, spacing),
+            Self::SpaceAround => Self::render_examples(area, buf, Flex::SpaceAround, spacing),
         }
     }
 }
@@ -409,7 +421,7 @@ impl Widget for Example {
     fn render(self, area: Rect, buf: &mut Buffer) {
         let title_height = get_description_height(&self.description);
         let layout = Layout::vertical([Length(title_height), Fill(0)]);
-        let [title, illustrations] = layout.areas(area);
+        let [title, illustrations] = area.layout(&layout);
 
         let (blocks, spacers) = Layout::horizontal(&self.constraints)
             .flex(self.flex)

examples/apps/gauge/src/main.rs

@@ -9,13 +9,13 @@ use std::time::Duration;
 
 use color_eyre::Result;
 use crossterm::event::{self, KeyCode};
+use ratatui::DefaultTerminal;
 use ratatui::buffer::Buffer;
 use ratatui::layout::{Alignment, Constraint, Layout, Rect};
 use ratatui::style::palette::tailwind;
 use ratatui::style::{Color, Style, Stylize};
 use ratatui::text::{Line, Span};
 use ratatui::widgets::{Block, Borders, Gauge, Padding, Paragraph, Widget};
-use ratatui::DefaultTerminal;
 
 const GAUGE1_COLOR: Color = tailwind::RED.c800;
 const GAUGE2_COLOR: Color = tailwind::GREEN.c800;
@@ -43,14 +43,11 @@ enum AppState {
 
 fn main() -> Result<()> {
     color_eyre::install()?;
-    let terminal = ratatui::init();
-    let app_result = App::default().run(terminal);
-    ratatui::restore();
-    app_result
+    ratatui::run(|terminal| App::default().run(terminal))
 }
 
 impl App {
-    fn run(mut self, mut terminal: DefaultTerminal) -> Result<()> {
+    fn run(mut self, terminal: &mut DefaultTerminal) -> Result<()> {
         while self.state != AppState::Quitting {
             terminal.draw(|frame| frame.render_widget(&self, frame.area()))?;
             self.handle_events()?;
@@ -106,10 +103,10 @@ impl Widget for &App {
     fn render(self, area: Rect, buf: &mut Buffer) {
         use Constraint::{Length, Min, Ratio};
         let layout = Layout::vertical([Length(2), Min(0), Length(1)]);
-        let [header_area, gauge_area, footer_area] = layout.areas(area);
+        let [header_area, gauge_area, footer_area] = area.layout(&layout);
 
         let layout = Layout::vertical([Ratio(1, 4); 4]);
-        let [gauge1_area, gauge2_area, gauge3_area, gauge4_area] = layout.areas(gauge_area);
+        let [gauge1_area, gauge2_area, gauge3_area, gauge4_area] = gauge_area.layout(&layout);
 
         render_header(header_area, buf);
         render_footer(footer_area, buf);
@@ -185,7 +182,7 @@ impl App {
     }
 }
 
-fn title_block(title: &str) -> Block {
+fn title_block(title: &str) -> Block<'_> {
     let title = Line::from(title).centered();
     Block::new()
         .borders(Borders::NONE)

examples/apps/hello-world/src/main.rs

@@ -7,8 +7,8 @@
 /// [`latest`]: https://github.com/ratatui/ratatui/tree/latest
 use std::time::Duration;
 
-use color_eyre::eyre::Context;
 use color_eyre::Result;
+use color_eyre::eyre::Context;
 use crossterm::event::{self, KeyCode};
 use ratatui::widgets::Paragraph;
 use ratatui::{DefaultTerminal, Frame};
@@ -21,17 +21,14 @@ use ratatui::{DefaultTerminal, Frame};
 /// and exits when the user presses 'q'.
 fn main() -> Result<()> {
     color_eyre::install()?; // augment errors / panics with easy to read messages
-    let terminal = ratatui::init();
-    let app_result = run(terminal).context("app loop failed");
-    ratatui::restore();
-    app_result
+    ratatui::run(run).context("failed to run app")
 }
 
 /// Run the application loop. This is where you would handle events and update the application
 /// state. This example exits when the user presses 'q'. Other styles of application loops are
 /// possible, for example, you could have multiple application states and switch between them based
 /// on events, or you could have a single application state and update it based on events.
-fn run(mut terminal: DefaultTerminal) -> Result<()> {
+fn run(terminal: &mut DefaultTerminal) -> Result<()> {
     loop {
         terminal.draw(render)?;
         if should_quit()? {

examples/apps/hyperlink/src/main.rs

@@ -7,46 +7,28 @@
 /// [`latest`]: https://github.com/ratatui/ratatui/tree/latest
 /// [OSC 8]: https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda
 use color_eyre::Result;
-use crossterm::event::{self, KeyCode};
+use crossterm::event;
 use itertools::Itertools;
 use ratatui::buffer::Buffer;
 use ratatui::layout::Rect;
 use ratatui::style::Stylize;
 use ratatui::text::{Line, Text};
 use ratatui::widgets::Widget;
-use ratatui::DefaultTerminal;
 
 fn main() -> Result<()> {
     color_eyre::install()?;
-    let terminal = ratatui::init();
-    let app_result = App::new().run(terminal);
-    ratatui::restore();
-    app_result
-}
 
-struct App {
-    hyperlink: Hyperlink<'static>,
-}
+    let text = Line::from(vec!["Example ".into(), "hyperlink".blue()]);
+    let hyperlink = Hyperlink::new(text, "https://example.com");
 
-impl App {
-    fn new() -> Self {
-        let text = Line::from(vec!["Example ".into(), "hyperlink".blue()]);
-        let hyperlink = Hyperlink::new(text, "https://example.com");
-        Self { hyperlink }
-    }
-
-    fn run(self, mut terminal: DefaultTerminal) -> Result<()> {
+    ratatui::run(|terminal| {
         loop {
-            terminal.draw(|frame| frame.render_widget(&self.hyperlink, frame.area()))?;
-            if event::read()?
-                .as_key_press_event()
-                .is_some_and(|key| matches!(key.code, KeyCode::Char('q') | KeyCode::Esc))
-            {
-                break;
+            terminal.draw(|frame| frame.render_widget(&hyperlink, frame.area()))?;
+            if event::read()?.is_key_press() {
+                break Ok(());
             }
         }
-        Ok(())
-    }
+    })
 }
 
 /// A hyperlink widget that renders a hyperlink in the terminal using [OSC 8].

examples/apps/inline/Cargo.toml

@@ -8,7 +8,7 @@ rust-version.workspace = true
 [dependencies]
 color-eyre.workspace = true
 crossterm.workspace = true
-rand = "0.9.1"
+rand.workspace = true
 ratatui.workspace = true
 
 [lints]

examples/apps/inline/src/main.rs

@@ -22,7 +22,7 @@ use ratatui::layout::{Constraint, Layout, Rect};
 use ratatui::style::{Color, Modifier, Style};
 use ratatui::text::{Line, Span};
 use ratatui::widgets::{Block, Gauge, LineGauge, List, ListItem, Paragraph, Widget};
-use ratatui::{symbols, Frame, Terminal, TerminalOptions, Viewport};
+use ratatui::{Frame, Terminal, TerminalOptions, Viewport, symbols};
 
 fn main() -> Result<()> {
     color_eyre::install()?;
@@ -230,8 +230,8 @@ fn render(frame: &mut Frame, downloads: &Downloads) {
 
     let vertical = Layout::vertical([Constraint::Length(2), Constraint::Length(4)]).margin(1);
     let horizontal = Layout::horizontal([Constraint::Percentage(20), Constraint::Percentage(80)]);
-    let [progress_area, main] = vertical.areas(area);
-    let [list_area, gauge_area] = horizontal.areas(main);
+    let [progress_area, main] = area.layout(&vertical);
+    let [list_area, gauge_area] = main.layout(&horizontal);
 
     // total progress
     let done = NUM_DOWNLOADS - downloads.pending.len() - downloads.in_progress.len();

examples/apps/input-form/README.md

@@ -23,5 +23,5 @@ Some more ideas for handling focus can be found in:
 - [`focusable`](https://crates.io/crates/focusable) (see also [Ratatui forum
   post](https://forum.ratatui.rs/t/focusable-crate-manage-focus-state-for-your-widgets/73))
 - [`rat-focus`](https://crates.io/crates/rat-focus)
-- A useful [`Bevy` discssion](https://github.com/bevyengine/bevy/discussions/15374) about focus
+- A useful [`Bevy` discussion](https://github.com/bevyengine/bevy/discussions/15374) about focus
   more generally.

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

@@ -26,12 +26,8 @@ use serde::Serialize;
 
 fn main() -> Result<()> {
     color_eyre::install()?;
-    let terminal = ratatui::init();
-    let result = App::default().run(terminal);
-    ratatui::restore();
-
     // serialize the form to JSON if the user submitted it, otherwise print "Canceled"
-    match result {
+    match ratatui::run(|terminal| App::default().run(terminal)) {
         Ok(Some(form)) => println!("{}", serde_json::to_string_pretty(&form)?),
         Ok(None) => println!("Canceled"),
         Err(err) => eprintln!("{err}"),
@@ -54,7 +50,7 @@ enum AppState {
 }
 
 impl App {
-    fn run(mut self, mut terminal: DefaultTerminal) -> Result<Option<InputForm>> {
+    fn run(mut self, terminal: &mut DefaultTerminal) -> Result<Option<InputForm>> {
         while self.state == AppState::Running {
             terminal.draw(|frame| self.render(frame))?;
             self.handle_events()?;
@@ -119,17 +115,17 @@ impl InputForm {
     ///
     /// The cursor is placed at the end of the focused field.
     fn render(&self, frame: &mut Frame) {
-        let [first_name_area, last_name_area, age_area] =
-            Layout::vertical(Constraint::from_lengths([1, 1, 1])).areas(frame.area());
+        let layout = Layout::vertical(Constraint::from_lengths([1, 1, 1]));
+        let [first_name_area, last_name_area, age_area] = frame.area().layout(&layout);
 
         frame.render_widget(&self.first_name, first_name_area);
         frame.render_widget(&self.last_name, last_name_area);
         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);
     }
@@ -189,11 +185,11 @@ impl StringField {
 
 impl Widget for &StringField {
     fn render(self, area: Rect, buf: &mut Buffer) {
-        let constraints = [
+        let layout = Layout::horizontal([
             Constraint::Length(self.label.len() as u16 + 2),
             Constraint::Fill(1),
-        ];
-        let [label_area, value_area] = Layout::horizontal(constraints).areas(area);
+        ]);
+        let [label_area, value_area] = area.layout(&layout);
         let label = Line::from_iter([self.label, ": "]).bold();
         label.render(label_area, buf);
         self.value.clone().render(value_area, buf);
@@ -254,11 +250,11 @@ impl AgeField {
 
 impl Widget for &AgeField {
     fn render(self, area: Rect, buf: &mut Buffer) {
-        let constraints = [
+        let layout = Layout::horizontal([
             Constraint::Length(self.label.len() as u16 + 2),
             Constraint::Fill(1),
-        ];
-        let [label_area, value_area] = Layout::horizontal(constraints).areas(area);
+        ]);
+        let [label_area, value_area] = area.layout(&layout);
         let label = Line::from_iter([self.label, ": "]).bold();
         let value = self.value.to_string();
         label.render(label_area, buf);

examples/apps/minimal/src/main.rs

@@ -1,28 +1,23 @@
-/// A minimal example of a Ratatui application.
-///
-/// This is a bare minimum example. There are many approaches to running an application loop,
-/// so this is not meant to be prescriptive. See the [examples] folder for more complete
-/// examples. In particular, the [hello-world] example is a good starting point.
-///
-/// This example runs with the Ratatui library code in the branch that you are currently
-/// reading. See the [`latest`] branch for the code which works with the most recent Ratatui
-/// release.
-///
-/// [`latest`]: https://github.com/ratatui/ratatui/tree/latest
-/// [examples]: https://github.com/ratatui/ratatui/blob/main/examples
-/// [hello-world]: https://github.com/ratatui/ratatui/blob/main/examples/apps/hello-world
-use crossterm::event;
-use ratatui::text::Text;
-
-fn main() {
-    let mut terminal = ratatui::init();
-    loop {
-        terminal
-            .draw(|frame| frame.render_widget(Text::raw("Hello World!"), frame.area()))
-            .expect("failed to draw frame");
-        if event::read().expect("failed to read event").is_key_press() {
-            break;
+//! A minimal example of a Ratatui application.
+//!
+//! This is a bare minimum example. There are many approaches to running an application loop,
+//! so this is not meant to be prescriptive. See the [examples] folder for more complete
+//! examples. In particular, the [hello-world] example is a good starting point.
+//!
+//! This example runs with the Ratatui library code in the branch that you are currently
+//! reading. See the [`latest`] branch for the code which works with the most recent Ratatui
+//! release.
+//!
+//! [`latest`]: https://github.com/ratatui/ratatui/tree/latest
+//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
+//! [hello-world]: https://github.com/ratatui/ratatui/blob/main/examples/apps/hello-world
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    ratatui::run(|terminal| {
+        loop {
+            terminal.draw(|frame| frame.render_widget("Hello World!", frame.area()))?;
+            if crossterm::event::read()?.is_key_press() {
+                break Ok(());
+            }
         }
-    }
-    ratatui::restore();
+    })
 }

examples/apps/modifiers/src/main.rs

@@ -12,34 +12,29 @@ use std::{error::Error, iter::once, result};
 
 use crossterm::event;
 use itertools::Itertools;
+use ratatui::Frame;
 use ratatui::layout::{Constraint, Layout};
 use ratatui::style::{Color, Modifier, Style, Stylize};
 use ratatui::text::Line;
 use ratatui::widgets::Paragraph;
-use ratatui::{DefaultTerminal, Frame};
 
 type Result<T> = result::Result<T, Box<dyn Error>>;
 
 fn main() -> Result<()> {
     color_eyre::install()?;
-    let terminal = ratatui::init();
-    let app_result = run(terminal);
-    ratatui::restore();
-    app_result
-}
-
-fn run(mut terminal: DefaultTerminal) -> Result<()> {
-    loop {
-        terminal.draw(render)?;
-        if event::read()?.is_key_press() {
-            return Ok(());
+    ratatui::run(|terminal| {
+        loop {
+            terminal.draw(render)?;
+            if event::read()?.is_key_press() {
+                break Ok(());
+            }
         }
-    }
+    })
 }
 
 fn render(frame: &mut Frame) {
-    let vertical = Layout::vertical([Constraint::Length(1), Constraint::Min(0)]);
-    let [text_area, main_area] = vertical.areas(frame.area());
+    let layout = Layout::vertical([Constraint::Length(1), Constraint::Min(0)]);
+    let [text_area, main_area] = frame.area().layout(&layout);
     frame.render_widget(
         Paragraph::new("Note: not all terminals support all modifiers")
             .style(Style::default().fg(Color::Red).add_modifier(Modifier::BOLD)),

examples/apps/mouse-drawing/Cargo.toml

@@ -9,8 +9,8 @@ rust-version.workspace = true
 color-eyre.workspace = true
 crossterm.workspace = true
 ## a collection of line drawing algorithms (e.g. Bresenham's line algorithm)
-line_drawing = "1.0.1"
-rand = "0.9.1"
+line_drawing = "1"
+rand.workspace = true
 ratatui.workspace = true
 
 [lints]

examples/apps/mouse-drawing/src/main.rs

@@ -17,14 +17,11 @@ use crossterm::execute;
 use ratatui::layout::{Position, Rect, Size};
 use ratatui::style::{Color, Stylize};
 use ratatui::text::Line;
-use ratatui::{symbols, DefaultTerminal, Frame};
+use ratatui::{DefaultTerminal, Frame, symbols};
 
 fn main() -> Result<()> {
     color_eyre::install()?;
-    let terminal = ratatui::init();
-    let result = MouseDrawingApp::default().run(terminal);
-    ratatui::restore();
-    result
+    ratatui::run(|terminal| MouseDrawingApp::default().run(terminal))
 }
 
 #[derive(Default)]
@@ -40,7 +37,7 @@ struct MouseDrawingApp {
 }
 
 impl MouseDrawingApp {
-    fn run(mut self, mut terminal: DefaultTerminal) -> Result<()> {
+    fn run(mut self, terminal: &mut DefaultTerminal) -> Result<()> {
         execute!(std::io::stdout(), EnableMouseCapture)?;
         while !self.should_exit {
             terminal.draw(|frame| self.render(frame))?;

examples/apps/panic/src/main.rs

@@ -29,71 +29,60 @@
 ///
 /// [`latest`]: https://github.com/ratatui/ratatui/tree/latest
 /// [Color Eyre recipe]: https://ratatui.rs/recipes/apps/color-eyre
-use color_eyre::{eyre::bail, Result};
+use color_eyre::{Result, eyre::bail};
 use crossterm::event::{self, KeyCode};
+use ratatui::Frame;
 use ratatui::text::Line;
 use ratatui::widgets::{Block, Paragraph};
-use ratatui::{DefaultTerminal, Frame};
+
+#[derive(Debug)]
+enum PanicHandlerState {
+    Enabled,
+    Disabled,
+}
 
 fn main() -> Result<()> {
     color_eyre::install()?;
-    let terminal = ratatui::init();
-    let app_result = App::new().run(terminal);
-    ratatui::restore();
-    app_result
-}
-struct App {
-    hook_enabled: bool,
-}
 
-impl App {
-    const fn new() -> Self {
-        Self { hook_enabled: true }
-    }
-
-    fn run(mut self, mut terminal: DefaultTerminal) -> Result<()> {
+    let mut panic_hook_state = PanicHandlerState::Enabled;
+    ratatui::run(|terminal| {
         loop {
-            terminal.draw(|frame| self.render(frame))?;
-
+            terminal.draw(|frame| render(frame, &panic_hook_state))?;
             if let Some(key) = event::read()?.as_key_press_event() {
                 match key.code {
                     KeyCode::Char('p') => panic!("intentional demo panic"),
                     KeyCode::Char('e') => bail!("intentional demo error"),
                     KeyCode::Char('h') => {
                         let _ = std::panic::take_hook();
-                        self.hook_enabled = false;
+                        panic_hook_state = PanicHandlerState::Disabled;
                     }
                     KeyCode::Char('q') => return Ok(()),
                     _ => {}
                 }
             }
         }
-    }
-
-    fn render(&self, frame: &mut Frame) {
-        let text = vec![
-            if self.hook_enabled {
-                Line::from("HOOK IS CURRENTLY **ENABLED**")
-            } else {
-                Line::from("HOOK IS CURRENTLY **DISABLED**")
-            },
-            Line::from(""),
-            Line::from("Press `p` to cause a panic"),
-            Line::from("Press `e` to cause an error"),
-            Line::from("Press `h` to disable the panic hook"),
-            Line::from("Press `q` to quit"),
-            Line::from(""),
-            Line::from("When your app panics without a panic hook, you will likely have to"),
-            Line::from("reset your terminal afterwards with the `reset` command"),
-            Line::from(""),
-            Line::from("Try first with the panic handler enabled, and then with it disabled"),
-            Line::from("to see the difference"),
-        ];
-
-        let paragraph = Paragraph::new(text)
-            .block(Block::bordered().title("Panic Handler Demo"))
-            .centered();
-
-        frame.render_widget(paragraph, frame.area());
-    }
+    })
+}
+
+fn render(frame: &mut Frame, state: &PanicHandlerState) {
+    let text = vec![
+        Line::from(format!("Panic hook is currently: {state:?}")),
+        Line::from(""),
+        Line::from("Press `p` to cause a panic"),
+        Line::from("Press `e` to cause an error"),
+        Line::from("Press `h` to disable the panic hook"),
+        Line::from("Press `q` to quit"),
+        Line::from(""),
+        Line::from("When your app panics without a panic hook, you will likely have to"),
+        Line::from("reset your terminal afterwards with the `reset` command"),
+        Line::from(""),
+        Line::from("Try first with the panic handler enabled, and then with it disabled"),
+        Line::from("to see the difference"),
+    ];
+
+    let paragraph = Paragraph::new(text)
+        .block(Block::bordered().title("Panic Handler Demo"))
+        .centered();
+
+    frame.render_widget(paragraph, frame.area());
 }

examples/apps/popup/src/main.rs

@@ -1,80 +1,70 @@
-/// A Ratatui example that demonstrates how to handle popups.
-// See also https://github.com/joshka/tui-popup and
-// https://github.com/sephiroth74/tui-confirm-dialog
-///
-/// This example runs with the Ratatui library code in the branch that you are currently
-/// reading. See the [`latest`] branch for the code which works with the most recent Ratatui
-/// release.
-///
-/// [`latest`]: https://github.com/ratatui/ratatui/tree/latest
+//! A Ratatui example that demonstrates how to handle popups.
+//! See also:
+//! - <https://github.com/joshka/tui-popup> and
+//! - <https://github.com/sephiroth74/tui-confirm-dialog>
+//!
+//! This example runs with the Ratatui library code in the branch that you are currently
+//! reading. See the [`latest`] branch for the code which works with the most recent Ratatui
+//! release.
+//!
+//! [`latest`]: https://github.com/ratatui/ratatui/tree/latest
 use color_eyre::Result;
 use crossterm::event::{self, KeyCode};
+use ratatui::Frame;
 use ratatui::layout::{Constraint, Flex, Layout, Rect};
 use ratatui::style::Stylize;
-use ratatui::widgets::{Block, Clear, Paragraph, Wrap};
-use ratatui::{DefaultTerminal, Frame};
+use ratatui::text::Line;
+use ratatui::widgets::{Block, Clear};
 
 fn main() -> Result<()> {
     color_eyre::install()?;
-    let terminal = ratatui::init();
-    let app_result = App::default().run(terminal);
-    ratatui::restore();
-    app_result
-}
 
-#[derive(Default)]
-struct App {
-    show_popup: bool,
-}
+    // This flag will be toggled when the user presses 'p'. This could be stored in an app struct
+    // if you have more state to manage than just this flag.
+    let mut show_popup = false;
 
-impl App {
-    fn run(mut self, mut terminal: DefaultTerminal) -> Result<()> {
+    ratatui::run(|terminal| {
         loop {
-            terminal.draw(|frame| self.render(frame))?;
+            terminal.draw(|frame| render(frame, show_popup))?;
 
             if let Some(key) = event::read()?.as_key_press_event() {
                 match key.code {
                     KeyCode::Char('q') => return Ok(()),
-                    KeyCode::Char('p') => self.show_popup = !self.show_popup,
+                    KeyCode::Char('p') => show_popup = !show_popup,
                     _ => {}
                 }
             }
         }
-    }
+    })
+}
 
-    fn render(&self, frame: &mut Frame) {
-        let area = frame.area();
+fn render(frame: &mut Frame, show_popup: bool) {
+    let area = frame.area();
 
-        let vertical = Layout::vertical([Constraint::Percentage(20), Constraint::Percentage(80)]);
-        let [instructions, content] = vertical.areas(area);
+    let layout = Layout::vertical([Constraint::Length(1), Constraint::Fill(1)]);
+    let [instructions, content] = area.layout(&layout);
 
-        let text = if self.show_popup {
-            "Press p to close the popup"
-        } else {
-            "Press p to show the popup"
-        };
-        let paragraph = Paragraph::new(text.slow_blink())
-            .centered()
-            .wrap(Wrap { trim: true });
-        frame.render_widget(paragraph, instructions);
+    frame.render_widget(
+        Line::from("Press 'p' to toggle popup, 'q' to quit").centered(),
+        instructions,
+    );
 
-        let block = Block::bordered().title("Content").on_blue();
-        frame.render_widget(block, content);
+    frame.render_widget(Block::bordered().title("Content").on_blue(), content);
 
-        if self.show_popup {
-            let block = Block::bordered().title("Popup");
-            let area = popup_area(area, 60, 20);
-            frame.render_widget(Clear, area); //this clears out the background
-            frame.render_widget(block, area);
-        }
+    if show_popup {
+        let popup = Block::bordered().title("Popup");
+        let popup_area = centered_area(area, 60, 20);
+        // clears out any background in the area before rendering the popup
+        frame.render_widget(Clear, popup_area);
+        frame.render_widget(popup, popup_area);
     }
 }
 
-/// helper function to create a centered rect using up certain percentage of the available rect `r`
-fn popup_area(area: Rect, percent_x: u16, percent_y: u16) -> Rect {
+/// 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] = vertical.areas(area);
-    let [area] = horizontal.areas(area);
+    let [area] = area.layout(&vertical);
+    let [area] = area.layout(&horizontal);
     area
 }

examples/apps/release-header/Cargo.toml

@@ -0,0 +1,13 @@
+[package]
+name = "release-header"
+publish = false
+license.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+
+[dependencies]
+color-eyre.workspace = true
+ratatui.workspace = true
+
+[lints]
+workspace = true

examples/apps/release-header/README.md

@@ -0,0 +1,13 @@
+# Release Header
+
+Generates a banner for Ratatui releases featuring a Ratatui logo, version info, and a list of crates.
+
+Used for README.md, documentation, and release materials. Updated for every release starting with v0.30.0 "Bryndza".
+
+## Usage
+
+```bash
+cargo run --p release-header
+```
+
+Press any key to exit. Creates a fixed 68x16 terminal viewport.

examples/apps/release-header/src/main.rs

@@ -0,0 +1,171 @@
+//! Generates a terminal banner for Ratatui releases featuring a Ratatui logo, version info, and
+//! a list of crates.
+//!
+//! Used for README.md, documentation, and release materials. Updated for every release starting
+//! with v0.30.0 "Bryndza".
+//!
+//! This example runs with the Ratatui library code in the branch that you are currently
+//! reading. See the [`latest`] branch for the code which works with the most recent Ratatui
+//! release.
+//!
+//! [`latest`]: https://github.com/ratatui/ratatui/tree/latest
+
+use std::io::stdout;
+use std::iter::zip;
+
+use ratatui::crossterm::terminal::{EnterAlternateScreen, LeaveAlternateScreen};
+use ratatui::crossterm::{event, execute};
+use ratatui::layout::{Constraint, Flex, Layout, Margin, Rect, Spacing};
+use ratatui::style::{Color, Stylize};
+use ratatui::symbols::merge::MergeStrategy;
+use ratatui::text::Line;
+use ratatui::widgets::{Block, BorderType, Padding, Paragraph, RatatuiLogo};
+use ratatui::{DefaultTerminal, Frame, TerminalOptions, Viewport};
+
+const SEMVER: &str = "0.30.0";
+const RELEASE_NAME: &str = "Bryndza";
+
+const MAIN_DISHES: [&str; 4] = [
+    "> ratatui",
+    "> ratatui-core",
+    "> ratatui-widgets",
+    "> ratatui-macros",
+];
+const BACKENDS: [&str; 3] = [
+    "> ratatui-crossterm",
+    "> ratatui-termion",
+    "> ratatui-termwiz",
+];
+
+const FG_COLOR: Color = Color::Rgb(246, 214, 187); // #F6D6BB
+const BG_COLOR: Color = Color::Rgb(20, 20, 50); // #141432
+const MENU_BORDER_COLOR: Color = Color::Rgb(255, 255, 160); // #FFFFA0
+
+enum Rainbow {
+    Red,
+    Orange,
+    Yellow,
+    Green,
+    Blue,
+    Indigo,
+    Violet,
+}
+
+fn main() -> color_eyre::Result<()> {
+    color_eyre::install()?;
+    let viewport = Viewport::Fixed(Rect::new(0, 0, 68, 16));
+    let terminal = ratatui::init_with_options(TerminalOptions { viewport });
+    execute!(stdout(), EnterAlternateScreen).expect("failed to enter alternate screen");
+    let result = run(terminal);
+    execute!(stdout(), LeaveAlternateScreen).expect("failed to leave alternate screen");
+    ratatui::restore();
+    result
+}
+
+fn run(mut terminal: DefaultTerminal) -> color_eyre::Result<()> {
+    loop {
+        terminal.draw(render)?;
+        if event::read()?.is_key_press() {
+            break Ok(());
+        }
+    }
+}
+
+fn render(frame: &mut Frame) {
+    let area = frame.area();
+    frame.buffer_mut().set_style(area, (FG_COLOR, BG_COLOR));
+
+    let logo_width = 29;
+    let menu_width = 23;
+    let padding = 2; // Padding between logo and menu
+    let menu_borders = 3;
+    let height = MAIN_DISHES.len() as u16 + BACKENDS.len() as u16 + menu_borders;
+    let width = logo_width + menu_width + padding;
+    let center_area = area.centered(Constraint::Length(width), Constraint::Length(height));
+    let layout = Layout::horizontal(Constraint::from_lengths([logo_width, padding, menu_width]));
+    let [logo_area, _, menu_area] = center_area.layout(&layout);
+
+    render_logo(frame, logo_area);
+    render_menu(frame, menu_area);
+}
+
+fn render_logo(frame: &mut Frame, area: Rect) {
+    let area = area.inner(Margin::new(1, 0));
+    let layout = Layout::vertical(Constraint::from_lengths([6, 2, 1])).flex(Flex::End);
+    let [shadow_area, logo_area, version_area] = area.layout(&layout);
+
+    // Divide the logo into letter sections for individual coloring, then render a block for each
+    // letter with a color based on the row index.
+    let letter_layout = Layout::horizontal(Constraint::from_lengths([5, 4, 4, 4, 4, 5, 1]));
+    for (row_index, row) in shadow_area.rows().enumerate() {
+        for (rainbow, letter_area) in zip(Rainbow::ROYGBIV, row.layout_vec(&letter_layout)) {
+            let color = rainbow.gradient_color(row_index);
+            frame.render_widget(Block::new().style(color), letter_area);
+        }
+        // Render the Ratatui logo truncated.
+        frame.render_widget(RatatuiLogo::small(), row);
+    }
+
+    frame.render_widget(Block::new().style(FG_COLOR), logo_area);
+    frame.render_widget(RatatuiLogo::small(), logo_area);
+    frame.render_widget(format!("v{SEMVER} \"{RELEASE_NAME}\"").dim(), version_area);
+}
+
+impl Rainbow {
+    const RED_GRADIENT: [u8; 6] = [41, 43, 50, 68, 104, 156];
+    const GREEN_GRADIENT: [u8; 6] = [24, 30, 41, 65, 105, 168];
+    const BLUE_GRADIENT: [u8; 6] = [55, 57, 62, 78, 113, 166];
+    const AMBIENT_GRADIENT: [u8; 6] = [17, 18, 20, 25, 40, 60];
+
+    const ROYGBIV: [Self; 7] = [
+        Self::Red,
+        Self::Orange,
+        Self::Yellow,
+        Self::Green,
+        Self::Blue,
+        Self::Indigo,
+        Self::Violet,
+    ];
+
+    fn gradient_color(&self, row: usize) -> Color {
+        let ambient = Self::AMBIENT_GRADIENT[row];
+        let red = Self::RED_GRADIENT[row];
+        let green = Self::GREEN_GRADIENT[row];
+        let blue = Self::BLUE_GRADIENT[row];
+        let blue_sat = Self::AMBIENT_GRADIENT[row].saturating_mul(6 - row as u8);
+        let (r, g, b) = match self {
+            Self::Red => (red, ambient, blue_sat),
+            Self::Orange => (red, green / 2, blue_sat),
+            Self::Yellow => (red, green, blue_sat),
+            Self::Green => (ambient, green, blue_sat),
+            Self::Blue => (ambient, ambient, blue.max(blue_sat)),
+            Self::Indigo => (blue, ambient, blue.max(blue_sat)),
+            Self::Violet => (red, ambient, blue.max(blue_sat)),
+        };
+        Color::Rgb(r, g, b)
+    }
+}
+
+fn render_menu(frame: &mut Frame, area: Rect) {
+    let layout = Layout::vertical(Constraint::from_lengths([
+        MAIN_DISHES.len() as u16 + 2,
+        BACKENDS.len() as u16 + 2,
+    ]))
+    .spacing(Spacing::Overlap(1)); // Overlap to merge borders
+    let [main_dishes_area, backends_area] = area.layout(&layout);
+
+    render_menu_block(frame, main_dishes_area, "Main Courses", &MAIN_DISHES);
+    render_menu_block(frame, backends_area, "Pairings", &BACKENDS);
+}
+
+fn render_menu_block(frame: &mut Frame, area: Rect, title: &str, menu_items: &[&str]) {
+    let menu_block = Block::bordered()
+        .border_type(BorderType::Rounded)
+        .border_style(MENU_BORDER_COLOR)
+        .padding(Padding::horizontal(1))
+        .merge_borders(MergeStrategy::Fuzzy)
+        .title(title);
+
+    let menu_lines: Vec<Line> = menu_items.iter().map(|&item| Line::from(item)).collect();
+    frame.render_widget(Paragraph::new(menu_lines).block(menu_block), area);
+}

examples/apps/scrollbar/src/main.rs

@@ -29,14 +29,11 @@ struct App {
 
 fn main() -> Result<()> {
     color_eyre::install()?;
-    let terminal = ratatui::init();
-    let app_result = App::default().run(terminal);
-    ratatui::restore();
-    app_result
+    ratatui::run(|terminal| App::default().run(terminal))
 }
 
 impl App {
-    fn run(mut self, mut terminal: DefaultTerminal) -> Result<()> {
+    fn run(mut self, terminal: &mut DefaultTerminal) -> Result<()> {
         let tick_rate = Duration::from_millis(250);
         let mut last_tick = Instant::now();
         loop {
@@ -60,24 +57,24 @@ impl App {
         }
     }
 
-    fn scroll_down(&mut self) {
+    const fn scroll_down(&mut self) {
         self.vertical_scroll = self.vertical_scroll.saturating_add(1);
         self.vertical_scroll_state = self.vertical_scroll_state.position(self.vertical_scroll);
     }
 
-    fn scroll_up(&mut self) {
+    const fn scroll_up(&mut self) {
         self.vertical_scroll = self.vertical_scroll.saturating_sub(1);
         self.vertical_scroll_state = self.vertical_scroll_state.position(self.vertical_scroll);
     }
 
-    fn scroll_left(&mut self) {
+    const fn scroll_left(&mut self) {
         self.horizontal_scroll = self.horizontal_scroll.saturating_sub(1);
         self.horizontal_scroll_state = self
             .horizontal_scroll_state
             .position(self.horizontal_scroll);
     }
 
-    fn scroll_right(&mut self) {
+    const fn scroll_right(&mut self) {
         self.horizontal_scroll = self.horizontal_scroll.saturating_add(1);
         self.horizontal_scroll_state = self
             .horizontal_scroll_state

examples/apps/table/Cargo.toml

@@ -8,7 +8,7 @@ rust-version.workspace = true
 [dependencies]
 color-eyre.workspace = true
 crossterm.workspace = true
-fakeit = "1.1"
+fakeit.workspace = true
 itertools.workspace = true
 ratatui.workspace = true
 unicode-width.workspace = true

examples/apps/table/src/main.rs

@@ -34,10 +34,7 @@ const ITEM_HEIGHT: usize = 4;
 
 fn main() -> Result<()> {
     color_eyre::install()?;
-    let terminal = ratatui::init();
-    let app_result = App::new().run(terminal);
-    ratatui::restore();
-    app_result
+    ratatui::run(|terminal| App::new().run(terminal))
 }
 struct TableColors {
     buffer_bg: Color,
@@ -80,20 +77,14 @@ impl Data {
         [&self.name, &self.address, &self.email]
     }
 
-    // https://github.com/rust-lang/rust/issues/139338
-    #[allow(clippy::missing_const_for_fn)]
     fn name(&self) -> &str {
         &self.name
     }
 
-    // https://github.com/rust-lang/rust/issues/139338
-    #[allow(clippy::missing_const_for_fn)]
     fn address(&self) -> &str {
         &self.address
     }
 
-    // https://github.com/rust-lang/rust/issues/139338
-    #[allow(clippy::missing_const_for_fn)]
     fn email(&self) -> &str {
         &self.email
     }
@@ -120,6 +111,7 @@ impl App {
             items: data_vec,
         }
     }
+
     pub fn next_row(&mut self) {
         let i = match self.state.selected() {
             Some(i) => {
@@ -171,7 +163,7 @@ impl App {
         self.colors = TableColors::new(&PALETTES[self.color_index]);
     }
 
-    fn run(mut self, mut terminal: DefaultTerminal) -> Result<()> {
+    fn run(mut self, terminal: &mut DefaultTerminal) -> Result<()> {
         loop {
             terminal.draw(|frame| self.render(frame))?;
 
@@ -194,8 +186,8 @@ impl App {
     }
 
     fn render(&mut self, frame: &mut Frame) {
-        let vertical = &Layout::vertical([Constraint::Min(5), Constraint::Length(4)]);
-        let rects = vertical.split(frame.area());
+        let layout = Layout::vertical([Constraint::Min(5), Constraint::Length(4)]);
+        let rects = frame.area().layout_vec(&layout);
 
         self.set_colors();
 

examples/apps/todo-list/src/main.rs

@@ -16,7 +16,7 @@ use ratatui::widgets::{
     Block, Borders, HighlightSpacing, List, ListItem, ListState, Padding, Paragraph,
     StatefulWidget, Widget, Wrap,
 };
-use ratatui::{symbols, DefaultTerminal};
+use ratatui::{DefaultTerminal, symbols};
 
 const TODO_HEADER_STYLE: Style = Style::new().fg(SLATE.c100).bg(BLUE.c800);
 const NORMAL_ROW_BG: Color = SLATE.c950;
@@ -27,10 +27,7 @@ const COMPLETED_TEXT_FG_COLOR: Color = GREEN.c500;
 
 fn main() -> Result<()> {
     color_eyre::install()?;
-    let terminal = ratatui::init();
-    let app_result = App::default().run(terminal);
-    ratatui::restore();
-    app_result
+    ratatui::run(|terminal| App::default().run(terminal))
 }
 
 /// This struct holds the current state of the app. In particular, it has the `todo_list` field
@@ -67,12 +64,36 @@ impl Default for App {
         Self {
             should_exit: false,
             todo_list: TodoList::from_iter([
-                (Status::Todo, "Rewrite everything with Rust!", "I can't hold my inner voice. He tells me to rewrite the complete universe with Rust"),
-                (Status::Completed, "Rewrite all of your tui apps with Ratatui", "Yes, you heard that right. Go and replace your tui with Ratatui."),
-                (Status::Todo, "Pet your cat", "Minnak loves to be pet by you! Don't forget to pet and give some treats!"),
-                (Status::Todo, "Walk with your dog", "Max is bored, go walk with him!"),
-                (Status::Completed, "Pay the bills", "Pay the train subscription!!!"),
-                (Status::Completed, "Refactor list example", "If you see this info that means I completed this task!"),
+                (
+                    Status::Todo,
+                    "Rewrite everything with Rust!",
+                    "I can't hold my inner voice. He tells me to rewrite the complete universe with Rust",
+                ),
+                (
+                    Status::Completed,
+                    "Rewrite all of your tui apps with Ratatui",
+                    "Yes, you heard that right. Go and replace your tui with Ratatui.",
+                ),
+                (
+                    Status::Todo,
+                    "Pet your cat",
+                    "Minnak loves to be pet by you! Don't forget to pet and give some treats!",
+                ),
+                (
+                    Status::Todo,
+                    "Walk with your dog",
+                    "Max is bored, go walk with him!",
+                ),
+                (
+                    Status::Completed,
+                    "Pay the bills",
+                    "Pay the train subscription!!!",
+                ),
+                (
+                    Status::Completed,
+                    "Refactor list example",
+                    "If you see this info that means I completed this task!",
+                ),
             ]),
         }
     }
@@ -100,7 +121,7 @@ impl TodoItem {
 }
 
 impl App {
-    fn run(mut self, mut terminal: DefaultTerminal) -> Result<()> {
+    fn run(mut self, terminal: &mut DefaultTerminal) -> Result<()> {
         while !self.should_exit {
             terminal.draw(|frame| frame.render_widget(&mut self, frame.area()))?;
             if let Some(key) = event::read()?.as_key_press_event() {
@@ -157,15 +178,15 @@ impl App {
 
 impl Widget for &mut App {
     fn render(self, area: Rect, buf: &mut Buffer) {
-        let [header_area, main_area, footer_area] = Layout::vertical([
+        let main_layout = Layout::vertical([
             Constraint::Length(2),
             Constraint::Fill(1),
             Constraint::Length(1),
-        ])
-        .areas(area);
+        ]);
+        let [header_area, content_area, footer_area] = area.layout(&main_layout);
 
-        let [list_area, item_area] =
-            Layout::vertical([Constraint::Fill(1), Constraint::Fill(1)]).areas(main_area);
+        let content_layout = Layout::vertical([Constraint::Fill(1), Constraint::Fill(1)]);
+        let [list_area, item_area] = content_area.layout(&content_layout);
 
         App::render_header(header_area, buf);
         App::render_footer(footer_area, buf);

examples/apps/tracing/Cargo.toml

@@ -9,9 +9,9 @@ rust-version.workspace = true
 color-eyre.workspace = true
 crossterm.workspace = true
 ratatui.workspace = true
-tracing = "0.1.40"
-tracing-appender = "0.2.3"
-tracing-subscriber = { version = "0.3.18", features = ["env-filter"] }
+tracing.workspace = true
+tracing-appender.workspace = true
+tracing-subscriber = { workspace = true, features = ["env-filter"] }
 
 [lints]
 workspace = true

examples/apps/tracing/src/main.rs

@@ -20,12 +20,12 @@
 /// [`latest`]: https://github.com/ratatui/ratatui/tree/latest
 use std::{fs::File, time::Duration};
 
-use color_eyre::eyre::Context;
 use color_eyre::Result;
+use color_eyre::eyre::Context;
 use crossterm::event::{self, Event, KeyCode};
-use ratatui::widgets::{Block, Paragraph};
 use ratatui::Frame;
-use tracing::{debug, info, instrument, trace, Level};
+use ratatui::widgets::{Block, Paragraph};
+use tracing::{Level, debug, info, instrument, trace};
 use tracing_appender::non_blocking;
 use tracing_appender::non_blocking::WorkerGuard;
 use tracing_subscriber::EnvFilter;

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

@@ -30,10 +30,7 @@ use ratatui::{DefaultTerminal, Frame};
 
 fn main() -> Result<()> {
     color_eyre::install()?;
-    let terminal = ratatui::init();
-    let app_result = App::new().run(terminal);
-    ratatui::restore();
-    app_result
+    ratatui::run(|terminal| App::new().run(terminal))
 }
 
 /// App holds the state of the application
@@ -127,7 +124,7 @@ impl App {
         self.reset_cursor();
     }
 
-    fn run(mut self, mut terminal: DefaultTerminal) -> Result<()> {
+    fn run(mut self, terminal: &mut DefaultTerminal) -> Result<()> {
         loop {
             terminal.draw(|frame| self.render(frame))?;
 
@@ -158,12 +155,12 @@ impl App {
     }
 
     fn render(&self, frame: &mut Frame) {
-        let vertical = Layout::vertical([
+        let layout = Layout::vertical([
             Constraint::Length(1),
             Constraint::Length(3),
             Constraint::Min(1),
         ]);
-        let [help_area, input_area, messages_area] = vertical.areas(frame.area());
+        let [help_area, input_area, messages_area] = frame.area().layout(&layout);
 
         let (msg, style) = match self.input_mode {
             InputMode::Normal => (

examples/apps/weather/Cargo.toml

@@ -8,7 +8,7 @@ rust-version.workspace = true
 [dependencies]
 color-eyre.workspace = true
 crossterm.workspace = true
-rand = "0.9.1"
+rand.workspace = true
 ratatui.workspace = true
 
 [lints]

examples/apps/weather/src/main.rs

@@ -9,67 +9,38 @@
 //! [`BarChart`]: https://docs.rs/ratatui/latest/ratatui/widgets/struct.BarChart.html
 
 use color_eyre::Result;
-use crossterm::event::{self, KeyCode};
-use rand::{rng, Rng};
+use crossterm::event;
+use rand::{Rng, rng};
+use ratatui::Frame;
 use ratatui::layout::{Constraint, Layout};
 use ratatui::style::{Color, Style, Stylize};
 use ratatui::text::Line;
 use ratatui::widgets::{Bar, BarChart, BarGroup};
-use ratatui::{DefaultTerminal, Frame};
 
 fn main() -> Result<()> {
     color_eyre::install()?;
-    let terminal = ratatui::init();
-    let app_result = App::new().run(terminal);
-    ratatui::restore();
-    app_result
+
+    let temperatures: Vec<u8> = (0..24).map(|_| rng().random_range(50..90)).collect();
+    ratatui::run(|terminal| {
+        loop {
+            terminal.draw(|frame| render(frame, &temperatures))?;
+            if event::read()?.is_key_press() {
+                break Ok(());
+            }
+        }
+    })
 }
 
-struct App {
-    should_exit: bool,
-    temperatures: Vec<u8>,
-}
+fn render(frame: &mut Frame, temperatures: &[u8]) {
+    let layout = Layout::vertical([Constraint::Length(1), Constraint::Fill(1)]).spacing(1);
+    let [title, main] = frame.area().layout(&layout);
 
-impl App {
-    fn new() -> Self {
-        let mut rng = rng();
-        let temperatures = (0..24).map(|_| rng.random_range(50..90)).collect();
-        Self {
-            should_exit: false,
-            temperatures,
-        }
-    }
-
-    fn run(mut self, mut terminal: DefaultTerminal) -> Result<()> {
-        while !self.should_exit {
-            terminal.draw(|frame| self.render(frame))?;
-            self.handle_events()?;
-        }
-        Ok(())
-    }
-
-    fn handle_events(&mut self) -> Result<()> {
-        if event::read()?
-            .as_key_press_event()
-            .is_some_and(|key| key.code == KeyCode::Char('q'))
-        {
-            self.should_exit = true;
-        }
-        Ok(())
-    }
-
-    fn render(&self, frame: &mut Frame) {
-        let [title, main] = Layout::vertical([Constraint::Length(1), Constraint::Fill(1)])
-            .spacing(1)
-            .areas(frame.area());
-
-        frame.render_widget("Weather demo".bold().into_centered_line(), title);
-        frame.render_widget(vertical_barchart(&self.temperatures), main);
-    }
+    frame.render_widget("Weather demo".bold().into_centered_line(), title);
+    frame.render_widget(vertical_barchart(temperatures), main);
 }
 
 /// Create a vertical bar chart from the temperatures data.
-fn vertical_barchart(temperatures: &[u8]) -> BarChart {
+fn vertical_barchart(temperatures: &[u8]) -> BarChart<'_> {
     let bars: Vec<Bar> = temperatures
         .iter()
         .enumerate()
@@ -80,7 +51,7 @@ fn vertical_barchart(temperatures: &[u8]) -> BarChart {
         .bar_width(5)
 }
 
-fn vertical_bar(hour: usize, temperature: &u8) -> Bar {
+fn vertical_bar(hour: usize, temperature: &u8) -> Bar<'_> {
     Bar::default()
         .value(u64::from(*temperature))
         .label(Line::from(format!("{hour:>02}:00")))

examples/apps/widget-ref-container/src/main.rs

@@ -1,39 +1,34 @@
-/// An example of how to use [`WidgetRef`] to store heterogeneous widgets in a container.
-///
-/// This example creates a `StackContainer` widget that can hold any number of widgets of
-/// different types. It creates two widgets, `Greeting` and `Farewell`, and stores them in a
-/// `StackContainer` with a vertical layout. The `StackContainer` widget renders each of its
-/// child widgets in the order they were added.
-///
-/// This example runs with the Ratatui library code in the branch that you are currently
-/// reading. See the [`latest`] branch for the code which works with the most recent Ratatui
-/// release.
-///
-/// [`latest`]: https://github.com/ratatui/ratatui/tree/latest
+//! An example of how to use [`WidgetRef`] to store heterogeneous widgets in a container.
+//!
+//! This example creates a `StackContainer` widget that can hold any number of widgets of
+//! different types. It creates two widgets, `Greeting` and `Farewell`, and stores them in a
+//! `StackContainer` with a vertical layout. The `StackContainer` widget renders each of its
+//! child widgets in the order they were added.
+//!
+//! This example runs with the Ratatui library code in the branch that you are currently
+//! reading. See the [`latest`] branch for the code which works with the most recent Ratatui
+//! release.
+//!
+//! [`latest`]: https://github.com/ratatui/ratatui/tree/latest
 use std::iter::zip;
 
 use color_eyre::Result;
 use crossterm::event;
+use ratatui::Frame;
 use ratatui::buffer::Buffer;
 use ratatui::layout::{Constraint, Direction, Layout, Rect};
 use ratatui::widgets::{Block, Paragraph, Widget, WidgetRef};
-use ratatui::{DefaultTerminal, Frame};
 
 fn main() -> Result<()> {
     color_eyre::install()?;
-    let terminal = ratatui::init();
-    let result = run(terminal);
-    ratatui::restore();
-    result
-}
-
-fn run(mut terminal: DefaultTerminal) -> Result<()> {
-    loop {
-        terminal.draw(render)?;
-        if event::read()?.is_key_press() {
-            return Ok(());
+    ratatui::run(|terminal| {
+        loop {
+            terminal.draw(render)?;
+            if event::read()?.is_key_press() {
+                return Ok(());
+            }
         }
-    }
+    })
 }
 
 fn render(frame: &mut Frame) {

examples/concepts/state/Cargo.toml

@@ -0,0 +1,11 @@
+[package]
+name = "ratatui-state-examples"
+publish = false
+license.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+
+[dependencies]
+color-eyre.workspace = true
+crossterm.workspace = true
+ratatui = { workspace = true, features = ["unstable-widget-ref"] }

examples/concepts/state/README.md

@@ -0,0 +1,179 @@
+# Ratatui State Management Examples
+
+This collection demonstrates various patterns for handling both mutable and immutable state in
+Ratatui applications. Each example solves a counter problem - incrementing a counter value - but
+uses different architectural approaches. These patterns represent common solutions to state
+management challenges you'll encounter when building TUI applications.
+
+For more information about widgets in Ratatui, see the [widgets module documentation](https://docs.rs/ratatui/latest/ratatui/widgets/index.html).
+
+## When to Use Each Pattern
+
+Choose the pattern that best fits your application's architecture and complexity:
+
+- **Simple applications**: Use `render-function` or `mutable-widget` patterns
+- **Clean separation**: Consider `stateful-widget` or `component-trait` patterns
+- **Complex hierarchies**: Use `nested-*` patterns for parent-child relationships
+- **Shared state**: Use `refcell` when multiple widgets need access to the same state
+- **Advanced scenarios**: Use `widget-with-mutable-ref` when you understand Rust lifetimes well
+
+## Running the Examples
+
+To run any example, use:
+
+```bash
+cargo run --bin example-name
+```
+
+Press any key (or resize the terminal) to increment the counter. Press `<Esc>` or `q` to exit.
+
+## Examples
+
+### Immutable State Patterns
+
+These patterns keep widget state immutable during rendering, with state updates happening outside
+the render cycle. They're generally easier to reason about and less prone to borrowing issues.
+
+#### [`immutable-function.rs`] - Function-Based Immutable State
+
+**Best for**: Simple applications with pure rendering functions
+**Pros**: Pure functions, easy to test, clear separation of concerns
+**Cons**: Verbose parameter passing, limited integration with Ratatui ecosystem
+
+Uses standalone functions that take immutable references to state. State updates happen in the
+application loop outside of rendering.
+
+#### [`immutable-shared-ref.rs`] - Shared Reference Pattern (Recommended)
+
+**Best for**: Most modern Ratatui applications
+**Pros**: Reusable widgets, efficient, integrates with Ratatui ecosystem, modern best practice
+**Cons**: Requires external state management for dynamic behavior
+
+Implements [`Widget`](https://docs.rs/ratatui/latest/ratatui/widgets/trait.Widget.html) for
+`&T`, allowing widgets to be rendered multiple times by reference without being consumed.
+
+#### [`immutable-consuming.rs`] - Consuming Widget Pattern
+
+**Best for**: Compatibility with older code, simple widgets created fresh each frame
+**Pros**: Simple implementation, widely compatible, familiar pattern
+**Cons**: Widget consumed on each render, requires reconstruction for reuse
+
+Implements [`Widget`](https://docs.rs/ratatui/latest/ratatui/widgets/trait.Widget.html) directly
+on the owned type, consuming the widget when rendered.
+
+### Mutable State Patterns
+
+These patterns allow widgets to modify their state during rendering, useful for widgets that need
+to update state as part of their rendering behavior.
+
+#### [`mutable-function.rs`] - Function-Based Mutable State
+
+**Best for**: Simple applications with minimal mutable state
+**Pros**: Easy to understand, no traits to implement, direct control
+**Cons**: State gets passed around as function parameters, harder to organize as complexity grows
+
+Uses simple functions that accept mutable state references. State is managed at the application
+level and passed down to render functions.
+
+#### [`mutable-widget.rs`] - Mutable Widget Pattern
+
+**Best for**: Self-contained widgets with their own mutable state
+**Pros**: Encapsulates state within the widget, familiar OOP-style approach
+**Cons**: Requires `&mut` references, can be challenging with complex borrowing scenarios
+
+Implements [`Widget`](https://docs.rs/ratatui/latest/ratatui/widgets/trait.Widget.html) for
+`&mut T`, allowing the widget to mutate its own state during rendering.
+
+### Intermediate Patterns
+
+#### [`stateful-widget.rs`] - Stateful Widget Pattern
+
+**Best for**: Clean separation of widget logic from state
+**Pros**: Separates widget logic from state, reusable, idiomatic Ratatui pattern
+**Cons**: State must be managed externally
+
+Uses [`StatefulWidget`](https://docs.rs/ratatui/latest/ratatui/widgets/trait.StatefulWidget.html)
+to keep rendering logic separate from state management.
+
+#### [`component-trait.rs`] - Custom Component Trait
+
+**Best for**: Implementing consistent behavior across multiple widget types
+**Pros**: Flexible, allows custom render signatures, good for widget frameworks
+**Cons**: Non-standard, requires users to learn your custom API
+
+Creates a custom trait similar to [`Widget`](https://docs.rs/ratatui/latest/ratatui/widgets/trait.Widget.html)
+but with a `&mut self` render method for direct mutation.
+
+### Advanced Patterns
+
+#### [`nested-mutable-widget.rs`] - Nested Mutable Widgets
+
+**Best for**: Parent-child widget relationships with mutable state
+**Pros**: Hierarchical organization, each widget manages its own state
+**Cons**: Complex borrowing, requires careful lifetime management
+
+Demonstrates how to nest widgets that both need mutable access to their state.
+
+#### [`nested-stateful-widget.rs`] - Nested Stateful Widgets
+
+**Best for**: Complex applications with hierarchical state management
+**Pros**: Clean separation, composable, scales well with application complexity
+**Cons**: More boilerplate, requires understanding of nested state patterns
+
+Shows how to compose multiple [`StatefulWidget`](https://docs.rs/ratatui/latest/ratatui/widgets/trait.StatefulWidget.html)s
+in a parent-child hierarchy.
+
+#### [`refcell.rs`] - Interior Mutability Pattern
+
+**Best for**: Shared state across multiple widgets, complex state sharing scenarios
+**Pros**: Allows shared mutable access, works with immutable widget references
+**Cons**: Runtime borrow checking, potential panics, harder to debug
+
+Uses [`Rc<RefCell<T>>`](https://doc.rust-lang.org/std/rc/struct.Rc.html) for interior mutability
+when multiple widgets need access to the same state.
+
+#### [`widget-with-mutable-ref.rs`] - Lifetime-Based Mutable References
+
+**Best for**: Advanced users who need precise control over state lifetime
+**Pros**: Zero-cost abstraction, explicit lifetime management
+**Cons**: Complex lifetimes, requires deep Rust knowledge, easy to get wrong
+
+Stores mutable references directly in widget structs using explicit lifetimes.
+
+## Choosing the Right Pattern
+
+**For most applications, start with immutable patterns:**
+
+1. **Simple apps**: Use `immutable-function` for basic rendering with external state management
+2. **Modern Ratatui**: Use `immutable-shared-ref` for reusable, efficient widgets (recommended)
+3. **Legacy compatibility**: Use `immutable-consuming` when working with older code patterns
+
+**Use mutable patterns when widgets need to update state during rendering:**
+
+1. **Simple mutable state**: Begin with `mutable-function` or `mutable-widget` for prototypes
+2. **Clean separation**: Use `stateful-widget` when you want to separate widget logic from state
+3. **Hierarchical widgets**: Use `nested-*` patterns for complex widget relationships
+4. **Shared state**: Use `refcell` when multiple widgets need the same state
+5. **Performance critical**: Consider `widget-with-mutable-ref` for advanced lifetime management
+
+## Common Pitfalls
+
+- **Borrowing issues**: The borrow checker can be challenging with mutable state.
+  [`StatefulWidget`](https://docs.rs/ratatui/latest/ratatui/widgets/trait.StatefulWidget.html)
+  often provides the cleanest solution.
+- **Overengineering**: Don't use complex patterns like `refcell` or `widget-with-mutable-ref`
+  unless you actually need them.
+- **State organization**: Keep state close to where it's used. Don't pass state through many
+  layers unnecessarily.
+
+[`component-trait.rs`]: ./src/bin/component-trait.rs
+[`immutable-consuming.rs`]: ./src/bin/immutable-consuming.rs
+[`immutable-function.rs`]: ./src/bin/immutable-function.rs
+[`immutable-shared-ref.rs`]: ./src/bin/immutable-shared-ref.rs
+[`mutable-widget.rs`]: ./src/bin/mutable-widget.rs
+[`nested-mutable-widget.rs`]: ./src/bin/nested-mutable-widget.rs
+[`nested-stateful-widget.rs`]: ./src/bin/nested-stateful-widget.rs
+[`refcell.rs`]: ./src/bin/refcell.rs
+[`mutable-function.rs`]: ./src/bin/mutable-function.rs
+[`stateful-widget.rs`]: ./src/bin/stateful-widget.rs
+[`widget-with-mutable-ref.rs`]: ./src/bin/widget-with-mutable-ref.rs

examples/concepts/state/src/bin/component-trait.rs

@@ -0,0 +1,83 @@
+//! # Custom Component Trait Pattern
+//!
+//! This example demonstrates using a custom trait instead of the standard `Widget` trait for
+//! handling mutable state during rendering. This pattern is useful when you want to implement
+//! consistent behavior across multiple widget types without implementing the `Widget` trait for
+//! each one.
+//!
+//! This example runs with the Ratatui library code in the branch that you are currently
+//! reading. See the [`latest`] branch for the code which works with the most recent Ratatui
+//! release.
+//!
+//! [`latest`]: https://github.com/ratatui/ratatui/tree/latest
+//!
+//! ## When to Use This Pattern
+//!
+//! - You're building a widget framework or library with custom behavior
+//! - You want a consistent API across multiple widget types
+//! - You need more control over the render method signature
+//! - You're prototyping widget behavior before standardizing on `Widget` or `StatefulWidget`
+//!
+//! ## Trade-offs
+//!
+//! **Pros:**
+//! - Flexible - you can define custom method signatures
+//! - Consistent - enforces the same behavior across widget types
+//! - Simple - no need to understand `StatefulWidget` complexity
+//!
+//! **Cons:**
+//! - Non-standard - users must learn your custom API instead of Ratatui's standard traits
+//! - Less discoverable - doesn't integrate with Ratatui's widget ecosystem
+//! - Limited reuse - can't be used with existing Ratatui functions expecting `Widget`
+//!
+//! ## Example Usage
+//!
+//! The custom `Component` trait allows widgets to mutate their state directly during rendering
+//! by taking `&mut self` instead of `self`. This is similar to the mutable widget pattern but
+//! with a custom trait interface.
+
+use ratatui::Frame;
+use ratatui::layout::Rect;
+use ratatui_state_examples::is_exit_key_pressed;
+
+/// Demonstrates the custom component trait pattern for mutable state management.
+///
+/// Creates a counter widget using a custom `Component` trait and runs the application loop,
+/// updating the counter on each render cycle until the user exits.
+fn main() -> color_eyre::Result<()> {
+    color_eyre::install()?;
+    ratatui::run(|terminal| {
+        let mut counter = Counter::default();
+        loop {
+            terminal.draw(|frame| counter.render(frame, frame.area()))?;
+            if is_exit_key_pressed()? {
+                break Ok(());
+            }
+        }
+    })
+}
+
+/// A custom trait for components that can render themselves while mutating their state.
+///
+/// This trait provides an alternative to the standard `Widget` trait by allowing components to
+/// take `&mut self`, enabling direct state mutation during rendering.
+trait Component {
+    /// Render the component to the given area of the frame.
+    fn render(&mut self, frame: &mut Frame, area: Rect);
+}
+
+/// A simple counter component that increments its value each time it's rendered.
+///
+/// Demonstrates how the custom `Component` trait allows widgets to maintain and mutate
+/// their own state during the rendering process.
+#[derive(Default)]
+struct Counter {
+    count: usize,
+}
+
+impl Component for Counter {
+    fn render(&mut self, frame: &mut Frame, area: Rect) {
+        self.count += 1;
+        frame.render_widget(format!("Counter: {count}", count = self.count), area);
+    }
+}

examples/concepts/state/src/bin/immutable-consuming.rs

@@ -0,0 +1,86 @@
+//! # Consuming Widget Pattern with Immutable State
+//!
+//! This example demonstrates implementing the `Widget` trait directly on the widget type,
+//! causing it to be consumed when rendered. This was the original pattern in Ratatui and
+//! is still commonly used, especially for simple widgets that are created fresh each frame.
+//!
+//! This example runs with the Ratatui library code in the branch that you are currently
+//! reading. See the [`latest`] branch for the code which works with the most recent Ratatui
+//! release.
+//!
+//! [`latest`]: https://github.com/ratatui/ratatui/tree/latest
+//!
+//! ## When to Use This Pattern
+//!
+//! - You're working with existing code that uses this pattern
+//! - Your widgets are simple and created fresh each frame
+//! - You want maximum compatibility with older Ratatui code
+//! - You don't need to reuse widget instances
+//!
+//! ## Trade-offs
+//!
+//! **Pros:**
+//! - Simple - straightforward implementation
+//! - Compatible - works with all Ratatui versions
+//! - Familiar - widely used pattern in existing code
+//! - No borrowing - no need to manage references
+//!
+//! **Cons:**
+//! - Consuming - widget is destroyed after each render
+//! - Inefficient - requires reconstruction for repeated use
+//! - Limited reuse - cannot store and reuse widget instances
+//!
+//! ## Example Usage
+//!
+//! The widget implements `Widget` directly on the owned type, meaning it's consumed
+//! when rendered and must be recreated for subsequent renders.
+
+use ratatui::buffer::Buffer;
+use ratatui::layout::Rect;
+use ratatui::widgets::Widget;
+use ratatui_state_examples::is_exit_key_pressed;
+
+/// Demonstrates the consuming widget pattern for immutable state rendering.
+///
+/// Creates a new counter widget instance each frame, showing how the consuming
+/// pattern works with immutable state that's managed externally.
+fn main() -> color_eyre::Result<()> {
+    color_eyre::install()?;
+    ratatui::run(|terminal| {
+        let mut count = 0;
+        loop {
+            terminal.draw(|frame| {
+                // Widget is created fresh each time and consumed when rendered
+                let counter = Counter::new(count);
+                frame.render_widget(counter, frame.area());
+            })?;
+            // State updates happen outside of widget lifecycle
+            count += 1;
+            if is_exit_key_pressed()? {
+                break Ok(());
+            }
+        }
+    })
+}
+
+/// A simple counter widget that displays a count value.
+///
+/// Implements `Widget` directly on the owned type, meaning the widget is consumed
+/// when rendered. The count state is managed externally and passed in during construction.
+struct Counter {
+    count: usize,
+}
+
+impl Counter {
+    /// Create a new counter widget with the given count.
+    fn new(count: usize) -> Self {
+        Self { count }
+    }
+}
+
+impl Widget for Counter {
+    fn render(self, area: Rect, buf: &mut Buffer) {
+        // Widget is consumed here - self is moved, not borrowed
+        format!("Counter: {}", self.count).render(area, buf);
+    }
+}

examples/concepts/state/src/bin/immutable-function.rs

@@ -0,0 +1,82 @@
+//! # Function-Based Pattern with Immutable State
+//!
+//! This example demonstrates using standalone functions for rendering widgets with immutable
+//! state. This pattern keeps state management completely separate from widget rendering logic,
+//! making it easy to test and reason about.
+//!
+//! This example runs with the Ratatui library code in the branch that you are currently
+//! reading. See the [`latest`] branch for the code which works with the most recent Ratatui
+//! release.
+//!
+//! [`latest`]: https://github.com/ratatui/ratatui/tree/latest
+//!
+//! ## When to Use This Pattern
+//!
+//! - You prefer functional programming approaches
+//! - Your rendering logic is simple and doesn't need complex widget hierarchies
+//! - You want clear separation between state and rendering
+//! - You're building simple UIs or prototyping quickly
+//!
+//! ## Trade-offs
+//!
+//! **Pros:**
+//! - Simple - easy to understand and test
+//! - Pure functions - no side effects in rendering
+//! - Flexible - can easily compose multiple render functions
+//! - Clear separation - state management is completely separate from rendering
+//!
+//! **Cons:**
+//! - Limited - doesn't integrate with Ratatui's widget ecosystem
+//! - Verbose - requires passing state explicitly to every function
+//! - No reuse - can't be used with existing Ratatui widget infrastructure
+//!
+//! ## Example Usage
+//!
+//! The function takes immutable references to both the frame and state, ensuring that
+//! rendering is a pure operation that doesn't modify state.
+
+use ratatui::Frame;
+use ratatui::layout::Rect;
+use ratatui_state_examples::is_exit_key_pressed;
+
+/// Demonstrates the function-based pattern for immutable state rendering.
+///
+/// Creates a counter state and renders it using a pure function, incrementing the counter
+/// in the application loop rather than during rendering.
+fn main() -> color_eyre::Result<()> {
+    color_eyre::install()?;
+    ratatui::run(|terminal| {
+        let mut counter_state = Counter::default();
+        loop {
+            terminal.draw(|frame| render_counter(frame, frame.area(), &counter_state))?;
+            // State updates happen outside of rendering
+            counter_state.increment();
+            if is_exit_key_pressed()? {
+                break Ok(());
+            }
+        }
+    })
+}
+
+/// State for the counter.
+///
+/// This state is managed externally and passed to render functions as an immutable reference.
+#[derive(Default)]
+struct Counter {
+    count: usize,
+}
+
+impl Counter {
+    /// Increment the counter value.
+    fn increment(&mut self) {
+        self.count += 1;
+    }
+}
+
+/// Pure render function that displays the counter state.
+///
+/// Takes immutable references to ensure rendering has no side effects on state.
+/// This function can be easily tested and composed with other render functions.
+fn render_counter(frame: &mut Frame, area: Rect, state: &Counter) {
+    frame.render_widget(format!("Counter: {}", state.count), area);
+}

examples/concepts/state/src/bin/immutable-shared-ref.rs

@@ -0,0 +1,92 @@
+//! # Shared Reference Pattern with Immutable State
+//!
+//! This example demonstrates implementing the `Widget` trait on a shared reference (`&Widget`)
+//! with immutable state. This is the recommended pattern for most widgets in modern Ratatui
+//! applications, as it allows widgets to be reused without being consumed.
+//!
+//! This example runs with the Ratatui library code in the branch that you are currently
+//! reading. See the [`latest`] branch for the code which works with the most recent Ratatui
+//! release.
+//!
+//! [`latest`]: https://github.com/ratatui/ratatui/tree/latest
+//!
+//! ## When to Use This Pattern
+//!
+//! - You want to reuse widgets across multiple renders
+//! - Your widget doesn't need to modify its state during rendering
+//! - You want the benefits of Ratatui's widget ecosystem
+//! - You're building modern, efficient Ratatui applications
+//!
+//! ## Trade-offs
+//!
+//! **Pros:**
+//! - Reusable - widget can be rendered multiple times without reconstruction
+//! - Efficient - no cloning or reconstruction needed
+//! - Standard - integrates with Ratatui's widget ecosystem
+//! - Modern - follows current Ratatui best practices
+//!
+//! **Cons:**
+//! - Immutable - cannot modify widget state during rendering
+//! - External state - requires external state management for dynamic behavior
+//!
+//! ## Example Usage
+//!
+//! The widget implements `Widget for &Counter`, allowing it to be rendered by reference
+//! while keeping its internal data immutable during rendering.
+
+use ratatui::buffer::Buffer;
+use ratatui::layout::Rect;
+use ratatui::widgets::Widget;
+use ratatui_state_examples::is_exit_key_pressed;
+
+/// Demonstrates the shared reference pattern for immutable widget rendering.
+///
+/// Creates a counter widget that can be rendered multiple times by reference,
+/// with state updates happening outside the widget's render method.
+fn main() -> color_eyre::Result<()> {
+    color_eyre::install()?;
+    ratatui::run(|terminal| {
+        let mut counter = Counter::new();
+        loop {
+            terminal.draw(|frame| {
+                // Widget is rendered by reference, can be reused
+                frame.render_widget(&counter, frame.area());
+            })?;
+            // State updates happen outside of rendering
+            counter.increment();
+            if is_exit_key_pressed()? {
+                break Ok(());
+            }
+        }
+    })
+}
+
+/// A counter widget with immutable rendering behavior.
+///
+/// Implements `Widget` on a shared reference, allowing the widget to be rendered
+/// multiple times without being consumed while keeping its data immutable during rendering.
+struct Counter {
+    count: usize,
+}
+
+impl Counter {
+    /// Create a new counter.
+    fn new() -> Self {
+        Self { count: 0 }
+    }
+
+    /// Increment the counter value.
+    ///
+    /// This method modifies the counter's state outside of the rendering process,
+    /// maintaining the separation between state updates and rendering.
+    fn increment(&mut self) {
+        self.count += 1;
+    }
+}
+
+impl Widget for &Counter {
+    fn render(self, area: Rect, buf: &mut Buffer) {
+        // Rendering is immutable - no state changes occur here
+        format!("Counter: {}", self.count).render(area, buf);
+    }
+}

examples/concepts/state/src/bin/mutable-function.rs

@@ -0,0 +1,67 @@
+//! # Render Function Pattern
+//!
+//! This example demonstrates the simplest approach to handling mutable state - using regular
+//! functions that accept mutable state references. This pattern works well for simple applications
+//! and prototypes where you don't need the complexity of widget traits.
+//!
+//! This example runs with the Ratatui library code in the branch that you are currently
+//! reading. See the [`latest`] branch for the code which works with the most recent Ratatui
+//! release.
+//!
+//! [`latest`]: https://github.com/ratatui/ratatui/tree/latest
+//!
+//! ## When to Use This Pattern
+//!
+//! - Simple applications with minimal state management needs
+//! - Prototypes and quick experiments
+//! - When you prefer functional programming over object-oriented approaches
+//! - Applications where state is naturally managed at the top level
+//!
+//! ## Trade-offs
+//!
+//! **Pros:**
+//! - Extremely simple - no traits to implement or understand
+//! - Direct and explicit - state flow is obvious
+//! - Flexible - easy to modify without interface constraints
+//! - Beginner-friendly - uses basic Rust concepts
+//!
+//! **Cons:**
+//! - State must be passed through function parameters
+//! - Harder to organize as application complexity grows
+//! - No encapsulation - state management is scattered
+//! - Less reusable than widget-based approaches
+//! - Can lead to parameter passing through many layers
+//!
+//! ## Example Usage
+//!
+//! State is managed at the application level and passed to render functions as needed.
+//! This approach works well when state is simple and doesn't need complex organization.
+
+use ratatui::Frame;
+use ratatui_state_examples::is_exit_key_pressed;
+
+/// Demonstrates the render function pattern for mutable state management.
+///
+/// Creates a counter using simple functions and runs the application loop,
+/// updating the counter on each render cycle until the user exits.
+fn main() -> color_eyre::Result<()> {
+    color_eyre::install()?;
+    ratatui::run(|terminal| {
+        let mut counter = 0;
+        loop {
+            terminal.draw(|frame| render(frame, &mut counter))?;
+            if is_exit_key_pressed()? {
+                break Ok(());
+            }
+        }
+    })
+}
+
+/// Renders a counter using a simple function-based approach.
+///
+/// Demonstrates the functional approach to state management where state is managed externally
+/// and passed in as a parameter.
+fn render(frame: &mut Frame, counter: &mut usize) {
+    *counter += 1;
+    frame.render_widget(format!("Counter: {counter}"), frame.area());
+}

examples/concepts/state/src/bin/mutable-widget.rs

@@ -0,0 +1,74 @@
+//! # Mutable Widget Pattern
+//!
+//! This example demonstrates implementing the `Widget` trait on a mutable reference (`&mut T`)
+//! to allow direct state mutation during rendering. This is one of the simplest approaches for
+//! widgets that need to maintain their own state.
+//!
+//! This example runs with the Ratatui library code in the branch that you are currently
+//! reading. See the [`latest`] branch for the code which works with the most recent Ratatui
+//! release.
+//!
+//! [`latest`]: https://github.com/ratatui/ratatui/tree/latest
+//!
+//! ## When to Use This Pattern
+//!
+//! - You have self-contained widgets with their own state
+//! - You prefer an object-oriented approach to widget design
+//! - Your widget's state is simple and doesn't need complex sharing
+//! - You want to encapsulate state within the widget itself
+//!
+//! ## Trade-offs
+//!
+//! **Pros:**
+//! - Simple and intuitive - state is encapsulated within the widget
+//! - Familiar pattern for developers coming from OOP backgrounds
+//! - Direct state access without external state management
+//! - Works well with Rust's ownership system for simple cases
+//!
+//! **Cons:**
+//! - Can lead to borrowing challenges in complex scenarios
+//! - Requires mutable access to the widget, which may not always be available
+//! - Less flexible than `StatefulWidget` for shared or complex state patterns
+//! - May require careful lifetime management in nested scenarios
+//!
+//! ## Example Usage
+//!
+//! The widget implements `Widget` for `&mut Self`, allowing it to mutate its internal state
+//! during the render call. Each render increments a counter, demonstrating state mutation.
+
+use ratatui::buffer::Buffer;
+use ratatui::layout::Rect;
+use ratatui::widgets::Widget;
+use ratatui_state_examples::is_exit_key_pressed;
+
+/// Demonstrates the mutable widget pattern for mutable state management.
+///
+/// Creates a counter widget using `Widget` for `&mut Self` and runs the application loop,
+/// updating the counter on each render cycle until the user exits.
+fn main() -> color_eyre::Result<()> {
+    color_eyre::install()?;
+    ratatui::run(|terminal| {
+        let mut counter = Counter::default();
+        loop {
+            terminal.draw(|frame| frame.render_widget(&mut counter, frame.area()))?;
+            if is_exit_key_pressed()? {
+                break Ok(());
+            }
+        }
+    })
+}
+
+/// A counter widget that maintains its own state and increments on each render.
+///
+/// Demonstrates the mutable widget pattern by implementing `Widget` for `&mut Self`.
+#[derive(Default)]
+struct Counter {
+    counter: usize,
+}
+
+impl Widget for &mut Counter {
+    fn render(self, area: Rect, buf: &mut Buffer) {
+        self.counter += 1;
+        format!("Counter: {counter}", counter = self.counter).render(area, buf);
+    }
+}

examples/concepts/state/src/bin/nested-mutable-widget.rs

@@ -0,0 +1,96 @@
+//! # Nested Mutable Widget Pattern
+//!
+//! This example demonstrates nesting widgets that both need mutable access to their state.
+//! This pattern is useful when you have a parent-child widget relationship where both widgets
+//! need to maintain and mutate their own state during rendering.
+//!
+//! This example runs with the Ratatui library code in the branch that you are currently
+//! reading. See the [`latest`] branch for the code which works with the most recent Ratatui
+//! release.
+//!
+//! [`latest`]: https://github.com/ratatui/ratatui/tree/latest
+//!
+//! ## When to Use This Pattern
+//!
+//! - You have hierarchical widget relationships (parent-child)
+//! - Each widget needs to maintain its own distinct state
+//! - You prefer the mutable widget pattern over StatefulWidget
+//! - Widgets have clear ownership of their state
+//!
+//! ## Trade-offs
+//!
+//! **Pros:**
+//! - Clear hierarchical organization
+//! - Each widget encapsulates its own state
+//! - Intuitive parent-child relationships
+//! - State ownership is explicit
+//!
+//! **Cons:**
+//! - Complex borrowing scenarios can arise
+//! - Requires careful lifetime management
+//! - May lead to borrow checker issues in complex hierarchies
+//! - Less flexible than StatefulWidget for state sharing
+//!
+//! ## Example Usage
+//!
+//! The parent `App` widget contains a child `Counter` widget. Both implement `Widget` for
+//! `&mut Self`, allowing them to mutate their respective states during rendering. The parent
+//! delegates rendering to the child while maintaining its own state structure.
+
+use ratatui::DefaultTerminal;
+use ratatui::buffer::Buffer;
+use ratatui::layout::Rect;
+use ratatui::widgets::Widget;
+use ratatui_state_examples::is_exit_key_pressed;
+
+/// Demonstrates the nested mutable widget pattern for mutable state management.
+///
+/// Creates a parent-child widget hierarchy using mutable widgets and runs the application loop,
+/// updating the counter on each render cycle until the user exits.
+fn main() -> color_eyre::Result<()> {
+    color_eyre::install()?;
+    let app = App::default();
+    ratatui::run(|terminal| app.run(terminal))
+}
+
+/// The main application widget that contains and manages child widgets.
+///
+/// Demonstrates the parent widget in a nested mutable widget hierarchy.
+#[derive(Default)]
+struct App {
+    counter: Counter,
+}
+
+impl App {
+    /// Run the application with the given terminal.
+    fn run(mut self, terminal: &mut DefaultTerminal) -> color_eyre::Result<()> {
+        loop {
+            terminal.draw(|frame| frame.render_widget(&mut self, frame.area()))?;
+            if is_exit_key_pressed()? {
+                break Ok(());
+            }
+        }
+    }
+}
+
+impl Widget for &mut App {
+    fn render(self, area: Rect, buf: &mut Buffer) {
+        self.counter.render(area, buf);
+    }
+}
+
+/// A counter widget that maintains its own state within a nested hierarchy.
+///
+/// Can be used standalone or as a child within other widgets, demonstrating
+/// how mutable widgets can be composed together.
+#[derive(Default)]
+struct Counter {
+    count: usize,
+}
+
+impl Widget for &mut Counter {
+    fn render(self, area: Rect, buf: &mut Buffer) {
+        self.count += 1;
+        format!("Counter: {count}", count = self.count).render(area, buf);
+    }
+}

examples/concepts/state/src/bin/nested-stateful-widget.rs

@@ -0,0 +1,103 @@
+//! # Nested StatefulWidget Pattern
+//!
+//! This example demonstrates composing multiple `StatefulWidget`s in a parent-child hierarchy.
+//! This pattern is ideal for complex applications where you need clean separation of concerns
+//! and want to leverage the benefits of the StatefulWidget pattern at multiple levels.
+//!
+//! This example runs with the Ratatui library code in the branch that you are currently
+//! reading. See the [`latest`] branch for the code which works with the most recent Ratatui
+//! release.
+//!
+//! [`latest`]: https://github.com/ratatui/ratatui/tree/latest
+//!
+//! ## When to Use This Pattern
+//!
+//! - Complex applications with hierarchical state management needs
+//! - When you want clean separation between widgets and their state
+//! - Building composable widget systems
+//! - Applications that need testable, reusable widget components
+//!
+//! ## Trade-offs
+//!
+//! **Pros:**
+//! - Excellent separation of concerns
+//! - Highly composable and reusable widgets
+//! - Easy to test individual widgets and their state
+//! - Scales well with application complexity
+//! - Follows idiomatic Ratatui patterns
+//!
+//! **Cons:**
+//! - More boilerplate code than simpler patterns
+//! - Requires understanding of nested state management
+//! - State structures can become complex
+//! - May be overkill for simple applications
+//!
+//! ## Example Usage
+//!
+//! The parent `App` widget manages application-level state while delegating specific
+//! functionality to child widgets like `Counter`. Each widget is responsible for its own
+//! state type and rendering logic, making the system highly modular.
+
+use ratatui::DefaultTerminal;
+use ratatui::buffer::Buffer;
+use ratatui::layout::Rect;
+use ratatui::widgets::{StatefulWidget, Widget};
+use ratatui_state_examples::is_exit_key_pressed;
+
+/// Demonstrates the nested StatefulWidget pattern for mutable state management.
+///
+/// Creates a parent-child widget hierarchy using StatefulWidgets and runs the application loop,
+/// updating the counter on each render cycle until the user exits.
+fn main() -> color_eyre::Result<()> {
+    color_eyre::install()?;
+    ratatui::run(App::run)
+}
+
+/// The main application widget using the StatefulWidget pattern.
+///
+/// Demonstrates how to compose multiple StatefulWidgets together while coordinating
+/// between different child widgets.
+struct App;
+
+impl App {
+    /// Run the application with the given terminal.
+    fn run(terminal: &mut DefaultTerminal) -> color_eyre::Result<()> {
+        let mut state = AppState { counter: 0 };
+
+        loop {
+            terminal.draw(|frame| frame.render_stateful_widget(App, frame.area(), &mut state))?;
+            if is_exit_key_pressed()? {
+                break Ok(());
+            }
+        }
+    }
+}
+
+/// Application state that contains all the state needed by the app and its child widgets.
+///
+/// Demonstrates how to organize hierarchical state in the StatefulWidget pattern.
+struct AppState {
+    counter: usize,
+}
+
+impl StatefulWidget for App {
+    type State = AppState;
+
+    fn render(self, area: Rect, buf: &mut Buffer, state: &mut Self::State) {
+        Counter.render(area, buf, &mut state.counter);
+    }
+}
+
+/// A counter widget that uses StatefulWidget for clean state separation.
+///
+/// Focuses purely on rendering logic and can be reused with different state instances.
+struct Counter;
+
+impl StatefulWidget for Counter {
+    type State = usize;
+
+    fn render(self, area: Rect, buf: &mut Buffer, state: &mut Self::State) {
+        *state += 1;
+        format!("Counter: {state}").render(area, buf);
+    }
+}

examples/concepts/state/src/bin/refcell.rs

@@ -0,0 +1,86 @@
+//! # Interior Mutability Pattern (RefCell)
+//!
+//! This example demonstrates using `Rc<RefCell<T>>` for interior mutability, allowing multiple
+//! widgets to share and mutate the same state. This pattern is useful when you need shared
+//! mutable state but can't use mutable references due to borrowing constraints.
+//!
+//! This example runs with the Ratatui library code in the branch that you are currently
+//! reading. See the [`latest`] branch for the code which works with the most recent Ratatui
+//! release.
+//!
+//! [`latest`]: https://github.com/ratatui/ratatui/tree/latest
+//!
+//! ## When to Use This Pattern
+//!
+//! - Multiple widgets need to access and modify the same state
+//! - You can't use mutable references due to borrowing constraints
+//! - You need shared ownership of mutable data
+//! - Complex widget hierarchies where state needs to be accessed from multiple locations
+//!
+//! ## Trade-offs
+//!
+//! **Pros:**
+//! - Allows shared mutable access to state
+//! - Works with immutable widget references
+//! - Enables complex state sharing patterns
+//! - Can be cloned cheaply (reference counting)
+//!
+//! **Cons:**
+//! - Runtime borrow checking - potential for panics if you violate borrowing rules
+//! - Less efficient than compile-time borrow checking
+//! - Harder to debug when borrow violations occur
+//! - More complex than simpler state management patterns
+//! - Can lead to subtle bugs if not used carefully
+//!
+//! ## Important Safety Notes
+//!
+//! - Only one mutable borrow can exist at a time
+//! - Violating this rule will cause a panic at runtime
+//! - Always minimize the scope of borrows to avoid conflicts
+//!
+//! ## Example Usage
+//!
+//! The widget wraps its state in `Rc<RefCell<T>>`, allowing the state to be shared and mutated
+//! even when the widget itself is used by value (as required by the `Widget` trait).
+
+use std::cell::RefCell;
+use std::ops::AddAssign;
+use std::rc::Rc;
+
+use ratatui::buffer::Buffer;
+use ratatui::layout::Rect;
+use ratatui::widgets::Widget;
+use ratatui_state_examples::is_exit_key_pressed;
+
+/// Demonstrates the interior mutability pattern for mutable state management.
+///
+/// Creates a counter widget using `Rc<RefCell<T>>` and runs the application loop,
+/// updating the counter on each render cycle until the user exits.
+fn main() -> color_eyre::Result<()> {
+    color_eyre::install()?;
+    ratatui::run(|terminal| {
+        let counter = Counter::default();
+        loop {
+            terminal.draw(|frame| frame.render_widget(counter.clone(), frame.area()))?;
+            if is_exit_key_pressed()? {
+                break Ok(());
+            }
+        }
+    })
+}
+
+/// A counter widget that uses interior mutability for shared state management.
+///
+/// Demonstrates how `Rc<RefCell<T>>` enables mutable state access even when the
+/// widget itself is used by value.
+#[derive(Default, Clone)]
+struct Counter {
+    count: Rc<RefCell<usize>>,
+}
+
+impl Widget for Counter {
+    fn render(self, area: Rect, buf: &mut Buffer) {
+        self.count.borrow_mut().add_assign(1);
+        format!("Counter: {count}", count = self.count.borrow()).render(area, buf);
+    }
+}

examples/concepts/state/src/bin/stateful-widget.rs

@@ -0,0 +1,78 @@
+//! # StatefulWidget Pattern (Recommended)
+//!
+//! This example demonstrates the `StatefulWidget` trait, which is the recommended approach for
+//! handling mutable state in Ratatui applications. This pattern separates the widget's rendering
+//! logic from its state, making it more flexible and reusable.
+//!
+//! This example runs with the Ratatui library code in the branch that you are currently
+//! reading. See the [`latest`] branch for the code which works with the most recent Ratatui
+//! release.
+//!
+//! [`latest`]: https://github.com/ratatui/ratatui/tree/latest
+//!
+//! ## When to Use This Pattern
+//!
+//! - Most Ratatui applications (this is the recommended default)
+//! - When building reusable widget libraries
+//! - When you need clean separation between rendering logic and state
+//! - When multiple widgets might share similar state structures
+//! - When you want to follow idiomatic Ratatui patterns
+//!
+//! ## Trade-offs
+//!
+//! **Pros:**
+//! - Clean separation of concerns between widget and state
+//! - Reusable - the same widget can work with different state instances
+//! - Testable - state and rendering logic can be tested independently
+//! - Composable - works well with complex application architectures
+//! - Idiomatic - follows Ratatui's recommended patterns
+//!
+//! **Cons:**
+//! - Slightly more verbose than direct mutation patterns
+//! - Requires understanding of the `StatefulWidget` trait
+//! - State must be managed externally
+//!
+//! ## Example Usage
+//!
+//! The widget defines its rendering behavior through `StatefulWidget`, while the state is
+//! managed separately. This allows the same widget to be used with different state instances
+//! and makes testing easier.
+
+use ratatui::buffer::Buffer;
+use ratatui::layout::Rect;
+use ratatui::widgets::{StatefulWidget, Widget};
+use ratatui_state_examples::is_exit_key_pressed;
+
+/// Demonstrates the StatefulWidget pattern for mutable state management.
+///
+/// Creates a counter widget using `StatefulWidget` and runs the application loop,
+/// updating the counter on each render cycle until the user exits.
+fn main() -> color_eyre::Result<()> {
+    color_eyre::install()?;
+    ratatui::run(|terminal| {
+        let mut counter = 0;
+        loop {
+            terminal.draw(|frame| {
+                frame.render_stateful_widget(CounterWidget, frame.area(), &mut counter)
+            })?;
+            if is_exit_key_pressed()? {
+                break Ok(());
+            }
+        }
+    })
+}
+
+/// A counter widget that uses the StatefulWidget pattern for state management.
+///
+/// Demonstrates the separation of rendering logic from state, making the widget reusable
+/// with different state instances and easier to test.
+struct CounterWidget;
+
+impl StatefulWidget for CounterWidget {
+    type State = usize;
+
+    fn render(self, area: Rect, buf: &mut Buffer, state: &mut Self::State) {
+        *state += 1;
+        format!("Counter: {state}").render(area, buf);
+    }
+}

examples/concepts/state/src/bin/widget-with-mutable-ref.rs

@@ -0,0 +1,84 @@
+//! # Lifetime-Based Mutable References Pattern
+//!
+//! This example demonstrates storing mutable references directly in widget structs using explicit
+//! lifetimes. This is an advanced pattern that provides zero-cost state access but requires
+//! careful lifetime management.
+//!
+//! This example runs with the Ratatui library code in the branch that you are currently
+//! reading. See the [`latest`] branch for the code which works with the most recent Ratatui
+//! release.
+//!
+//! [`latest`]: https://github.com/ratatui/ratatui/tree/latest
+//!
+//! ## When to Use This Pattern
+//!
+//! - You need maximum performance with zero runtime overhead
+//! - You have a good understanding of Rust lifetimes and borrowing
+//! - State lifetime is clearly defined and relatively simple
+//! - You're building performance-critical applications
+//!
+//! ## Trade-offs
+//!
+//! **Pros:**
+//! - Zero runtime cost - no reference counting or runtime borrow checking
+//! - Compile-time safety - borrow checker ensures memory safety
+//! - Direct access to state without indirection
+//! - Maximum performance for state access
+//!
+//! **Cons:**
+//! - Complex lifetime management - requires deep Rust knowledge
+//! - Easy to create compilation errors that are hard to understand
+//! - Inflexible - lifetime constraints can make code harder to refactor
+//! - Not suitable for beginners - requires advanced Rust skills
+//! - Widget structs become less reusable due to lifetime constraints
+//!
+//! ## Important Considerations
+//!
+//! - The widget's lifetime is tied to the state's lifetime
+//! - You must ensure the state outlives the widget
+//! - Lifetime annotations can become complex in larger applications
+//! - Consider simpler patterns unless performance is critical
+//!
+//! ## Example Usage
+//!
+//! The widget stores a mutable reference to external state, allowing direct access without
+//! runtime overhead. The widget must be recreated for each render call due to the lifetime
+//! constraints.
+
+use ratatui::buffer::Buffer;
+use ratatui::layout::Rect;
+use ratatui::widgets::Widget;
+use ratatui_state_examples::is_exit_key_pressed;
+
+/// Demonstrates the lifetime-based mutable references pattern for mutable state management.
+///
+/// Creates a counter widget using mutable references with explicit lifetimes and runs the
+/// application loop, updating the counter on each render cycle until the user exits.
+fn main() -> color_eyre::Result<()> {
+    color_eyre::install()?;
+    ratatui::run(|terminal| {
+        let mut count = 0;
+        loop {
+            let counter = CounterWidget { count: &mut count };
+            terminal.draw(|frame| frame.render_widget(counter, frame.area()))?;
+            if is_exit_key_pressed()? {
+                break Ok(());
+            }
+        }
+    })
+}
+
+/// A counter widget that holds a mutable reference to external state.
+///
+/// Demonstrates the lifetime-based pattern where the widget directly stores a
+/// mutable reference to external state.
+struct CounterWidget<'a> {
+    count: &'a mut usize,
+}
+
+impl Widget for CounterWidget<'_> {
+    fn render(self, area: Rect, buf: &mut Buffer) {
+        *self.count += 1;
+        format!("Counter: {count}", count = self.count).render(area, buf);
+    }
+}

examples/concepts/state/src/lib.rs

@@ -0,0 +1,8 @@
+//! Helper functions for checking if exit keys are pressed
+use crossterm::event::{self, KeyCode};
+
+pub fn is_exit_key_pressed() -> std::io::Result<bool> {
+    Ok(event::read()?
+        .as_key_press_event()
+        .is_some_and(|key| matches!(key.code, KeyCode::Esc | KeyCode::Char('q'))))
+}

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

examples/vhs/release-header.tape

@@ -0,0 +1,19 @@
+# This is a vhs script. See https://github.com/charmbracelet/vhs for more info.
+# To run this script, install vhs and run `vhs ./examples/vhs/release-header.tape`
+# NOTE: Requires VHS 0.6.1 or later for Screenshot support
+# 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 Theme {"background": "#141432"}
+Set FontSize 25
+Set Width 1120
+Set Height 480
+Set Padding 0
+Hide
+Type "cargo run -p release-header"
+Enter
+Sleep 1s
+Show
+Sleep 1s
+Screenshot assets/release-header.png
+Sleep 1s

ratatui-core/Cargo.toml

@@ -1,13 +1,13 @@
 [package]
 name = "ratatui-core"
+version = "0.1.0-beta.1"
 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-alpha.4"
+documentation = "https://docs.rs/ratatui-core"
 readme = "README.md"
 authors.workspace = true
-documentation.workspace = true
 repository.workspace = true
 homepage.workspace = true
 keywords.workspace = true
@@ -41,7 +41,10 @@ layout-cache = ["std"]
 anstyle = ["dep:anstyle"]
 
 ## enables conversions from colors in the [`palette`] crate to [`Color`](crate::style::Color).
-palette = ["dep:palette"]
+palette = ["std", "dep:palette"]
+
+## enables portable-atomic integration for targets that don't support atomic types.
+portable-atomic = ["kasuari/portable-atomic"]
 
 ## enables the backend code that sets the underline color. Underline color is only supported by
 ## the Crossterm backend, and is not supported on Windows 7.
@@ -53,24 +56,24 @@ scrolling-regions = []
 
 ## enables serialization and deserialization of style and color types using the [`serde`] crate.
 ## This is useful if you want to save themes to a file.
-serde = ["dep:serde", "bitflags/serde", "compact_str/serde"]
+serde = ["std", "dep:serde", "bitflags/serde", "compact_str/serde"]
 
 [dependencies]
-anstyle = { version = "1", optional = true }
-bitflags = "2.3"
-compact_str = { version = "0.9.0", default-features = false }
+anstyle = { workspace = true, optional = true }
+bitflags.workspace = true
+compact_str.workspace = true
 document-features = { workspace = true, optional = true }
-hashbrown = "0.15.2"
+hashbrown.workspace = true
 indoc.workspace = true
 itertools.workspace = true
-kasuari = { version = "0.4.6", default-features = false }
-lru = "0.12.0"
-palette = { version = "0.7.6", optional = true }
+kasuari = { workspace = true, default-features = false }
+lru.workspace = true
+palette = { workspace = true, optional = true }
 serde = { workspace = true, optional = true }
 strum.workspace = true
-thiserror = { version = "2", default-features = false }
+thiserror = { workspace = true, default-features = false }
 unicode-segmentation.workspace = true
-unicode-truncate = { version = "2", default-features = false }
+unicode-truncate = { workspace = true, default-features = false }
 unicode-width.workspace = true
 
 [dev-dependencies]

ratatui-core/README.md

@@ -29,6 +29,32 @@ Add `ratatui-core` to your `Cargo.toml`:
 cargo add ratatui-core
 ```
 
+## Crate Organization
+
+`ratatui-core` is part of the Ratatui workspace that was modularized in version 0.30.0 to
+improve compilation times, API stability, and dependency management. This crate provides the
+foundational types and traits that other crates in the workspace depend on.
+
+**When to use `ratatui-core`:**
+
+- Building widget libraries that implement [`Widget`] or [`StatefulWidget`]
+- Creating lightweight applications that don't need built-in widgets
+- You want minimal dependencies and faster compilation times
+- You need maximum API stability (core types change less frequently)
+
+**When to use the main [`ratatui`] crate:**
+
+- Building applications that use built-in widgets
+- You want convenience and don't mind slightly longer compilation times
+- You need backend implementations and terminal management utilities
+
+For detailed information about the workspace organization, see [ARCHITECTURE.md].
+
+[`ratatui`]: https://crates.io/crates/ratatui
+[`Widget`]: widgets::Widget
+[`StatefulWidget`]: widgets::StatefulWidget
+[ARCHITECTURE.md]: https://github.com/ratatui/ratatui/blob/main/ARCHITECTURE.md
+
 ## Contributing
 
 We welcome contributions from the community! Please see our [CONTRIBUTING](../CONTRIBUTING.md)

ratatui-core/src/buffer/buffer.rs

@@ -104,8 +104,6 @@ impl Buffer {
     }
 
     /// Returns the content of the buffer as a slice
-    // https://github.com/rust-lang/rust/issues/139338
-    #[allow(clippy::missing_const_for_fn)]
     pub fn content(&self) -> &[Cell] {
         &self.content
     }
@@ -218,6 +216,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
     ///
     /// ```
@@ -271,10 +272,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
     ///
     /// ```
@@ -497,6 +501,38 @@ impl Buffer {
             if !current.skip && (current != previous || invalidated > 0) && to_skip == 0 {
                 let (x, y) = self.pos_of(i);
                 updates.push((x, y, &next_buffer[i]));
+
+                // If the current cell is multi-width, ensure the trailing cells are explicitly
+                // cleared when they previously contained non-blank content. Some terminals do not
+                // reliably clear the trailing cell(s) when printing a wide grapheme, which can
+                // result in visual artifacts (e.g., leftover characters). Emitting an explicit
+                // update for the trailing cells avoids this.
+                let symbol = current.symbol();
+                let cell_width = symbol.width();
+                // Work around terminals that fail to clear the trailing cell of certain
+                // emoji presentation sequences (those containing VS16 / U+FE0F).
+                // Only emit explicit clears for such sequences to avoid bloating diffs
+                // for standard wide characters (e.g., CJK), which terminals handle well.
+                let contains_vs16 = symbol.chars().any(|c| c == '\u{FE0F}');
+                if cell_width > 1 && contains_vs16 {
+                    for k in 1..cell_width {
+                        let j = i + k;
+                        // Make sure that we are still inside the buffer.
+                        if j >= next_buffer.len() || j >= previous_buffer.len() {
+                            break;
+                        }
+                        let prev_trailing = &previous_buffer[j];
+                        let next_trailing = &next_buffer[j];
+                        if !next_trailing.skip && prev_trailing != next_trailing {
+                            let (tx, ty) = self.pos_of(j);
+                            // Push an explicit update for the trailing cell.
+                            // This is expected to be a blank cell, but we use the actual
+                            // content from the next buffer to handle cases where
+                            // the user has explicitly set something else.
+                            updates.push((tx, ty, next_trailing));
+                        }
+                    }
+                }
             }
 
             to_skip = current.symbol().width().saturating_sub(1);
@@ -1237,7 +1273,7 @@ mod tests {
     }
 
     /// Emojis normally contain various characters which should stay part of the Emoji.
-    /// This should work fine by utilizing unicode_segmentation but a testcase is probably helpful
+    /// This should work fine by utilizing `unicode_segmentation` but a testcase is probably helpful
     /// due to the nature of never perfect Unicode implementations and all of its quirks.
     #[rstest]
     // Shrug without gender or skintone. Has a width of 2 like all emojis have.
@@ -1250,24 +1286,31 @@ mod tests {
     // Both eye and speech bubble include a 'display as emoji' variation selector
     // Prior to unicode-width 0.2, this was incorrectly detected as width 4 for some reason
     #[case::eye_speechbubble("👁️‍🗨️", "👁️‍🗨️xxxxx")]
+    // Keyboard keycap emoji: base symbol + VS16 for emoji presentation
+    // This should render as a single grapheme with width 2.
+    #[case::keyboard_emoji("⌨️", "⌨️xxxxx")]
     fn renders_emoji(#[case] input: &str, #[case] expected: &str) {
         use unicode_width::UnicodeWidthChar;
 
         dbg!(input);
         dbg!(input.len());
-        dbg!(input
-            .graphemes(true)
-            .map(|symbol| (symbol, symbol.escape_unicode().to_string(), symbol.width()))
-            .collect::<Vec<_>>());
-        dbg!(input
-            .chars()
-            .map(|char| (
-                char,
-                char.escape_unicode().to_string(),
-                char.width(),
-                char.is_control()
-            ))
-            .collect::<Vec<_>>());
+        dbg!(
+            input
+                .graphemes(true)
+                .map(|symbol| (symbol, symbol.escape_unicode().to_string(), symbol.width()))
+                .collect::<Vec<_>>()
+        );
+        dbg!(
+            input
+                .chars()
+                .map(|char| (
+                    char,
+                    char.escape_unicode().to_string(),
+                    char.width(),
+                    char.is_control()
+                ))
+                .collect::<Vec<_>>()
+        );
 
         let mut buffer = Buffer::filled(Rect::new(0, 0, 7, 1), Cell::new("x"));
         buffer.set_string(0, 0, input, Style::new());
@@ -1295,4 +1338,34 @@ mod tests {
         assert_eq!(buffer.index_of(255, 256), 65791);
         assert_eq!(buffer.pos_of(65791), (255, 256)); // previously (255, 0)
     }
+
+    #[test]
+    fn diff_clears_trailing_cell_for_wide_grapheme() {
+        // Reproduce: write "ab", then overwrite with a wide emoji like "⌨️"
+        let prev = Buffer::with_lines(["ab"]); // width 2 area inferred
+        assert_eq!(prev.area.width, 2);
+
+        let mut next = Buffer::with_lines(["  "]); // start with blanks
+        next.set_string(0, 0, "⌨️", Style::new());
+
+        // The next buffer contains a wide grapheme occupying cell 0 and implicitly cell 1.
+        // The debug formatting shows the hidden trailing space.
+        let expected_next = Buffer::with_lines(["⌨️"]);
+        assert_eq!(next, expected_next);
+
+        // The diff should include an update for (0,0) to draw the emoji. Depending on
+        // terminal behavior, it may or may not be necessary to explicitly clear (1,0).
+        // At minimum, ensure the first cell is updated and nothing incorrect is emitted.
+        let diff = prev.diff(&next);
+        assert!(
+            diff.iter()
+                .any(|(x, y, c)| *x == 0 && *y == 0 && c.symbol() == "⌨️")
+        );
+        // And it should explicitly clear the trailing cell (1,0) to avoid leftovers on terminals
+        // that don't automatically clear the following cell for wide characters.
+        assert!(
+            diff.iter()
+                .any(|(x, y, c)| *x == 1 && *y == 0 && c.symbol() == " ")
+        );
+    }
 }

ratatui-core/src/buffer/cell.rs

@@ -1,9 +1,10 @@
 use compact_str::CompactString;
 
 use crate::style::{Color, Modifier, Style};
+use crate::symbols::merge::MergeStrategy;
 
 /// A buffer cell
-#[derive(Debug, Clone, Eq, PartialEq, Hash)]
+#[derive(Debug, Default, Clone)]
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 pub struct Cell {
     /// The string to be drawn in the cell.
@@ -14,7 +15,7 @@ pub struct Cell {
     /// buffer for short strings.
     ///
     /// See <https://github.com/ratatui/ratatui/pull/601> for more information.
-    symbol: CompactString,
+    symbol: Option<CompactString>,
 
     /// The foreground color of the cell.
     pub fg: Color,
@@ -35,35 +36,86 @@ pub struct Cell {
 
 impl Cell {
     /// An empty `Cell`
-    pub const EMPTY: Self = Self::new(" ");
+    pub const EMPTY: Self = Self {
+        symbol: None,
+        fg: Color::Reset,
+        bg: Color::Reset,
+        #[cfg(feature = "underline-color")]
+        underline_color: Color::Reset,
+        modifier: Modifier::empty(),
+        skip: false,
+    };
 
     /// Creates a new `Cell` with the given symbol.
     ///
     /// This works at compile time and puts the symbol onto the stack. Fails to build when the
-    /// symbol doesnt fit onto the stack and requires to be placed on the heap. Use
+    /// symbol doesn't fit onto the stack and requires to be placed on the heap. Use
     /// `Self::default().set_symbol()` in that case. See [`CompactString::const_new`] for more
     /// details on this.
     pub const fn new(symbol: &'static str) -> Self {
         Self {
-            symbol: CompactString::const_new(symbol),
-            fg: Color::Reset,
-            bg: Color::Reset,
-            #[cfg(feature = "underline-color")]
-            underline_color: Color::Reset,
-            modifier: Modifier::empty(),
-            skip: false,
+            symbol: Some(CompactString::const_new(symbol)),
+            ..Self::EMPTY
         }
     }
 
     /// Gets the symbol of the cell.
+    ///
+    /// If the cell has no symbol, returns a single space character.
     #[must_use]
     pub fn symbol(&self) -> &str {
-        self.symbol.as_str()
+        self.symbol.as_ref().map_or(" ", |s| s.as_str())
+    }
+
+    /// Merges the symbol of the cell with the one already on the cell, using the provided
+    /// [`MergeStrategy`].
+    ///
+    /// Merges [Box Drawing Unicode block] characters to create a single character representing
+    /// their combination, useful for [border collapsing]. Currently limited to box drawing
+    /// characters, with potential future support for others.
+    ///
+    /// Merging may not be perfect due to Unicode limitations; some symbol combinations might not
+    /// produce a valid character. [`MergeStrategy`] defines how to handle such cases, e.g.,
+    /// `Exact` for valid merges only, or `Fuzzy` for close matches.
+    ///
+    /// If the cell has no symbol set, it will set the symbol to the provided one rather than
+    /// merging.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # use ratatui_core::buffer::Cell;
+    /// use ratatui_core::symbols::merge::MergeStrategy;
+    ///
+    /// assert_eq!(
+    ///     Cell::new("┘")
+    ///         .merge_symbol("┏", MergeStrategy::Exact)
+    ///         .symbol(),
+    ///     "╆",
+    /// );
+    ///
+    /// assert_eq!(
+    ///     Cell::new("╭")
+    ///         .merge_symbol("┘", MergeStrategy::Fuzzy)
+    ///         .symbol(),
+    ///     "┼",
+    /// );
+    /// ```
+    ///
+    /// [border collapsing]: https://ratatui.rs/recipes/layout/collapse-borders/
+    /// [Box Drawing Unicode block]: https://en.wikipedia.org/wiki/Box_Drawing
+    pub fn merge_symbol(&mut self, symbol: &str, strategy: MergeStrategy) -> &mut Self {
+        let merged_symbol = self
+            .symbol
+            .as_ref()
+            .map_or(symbol, |s| strategy.merge(s, symbol));
+        self.symbol = Some(CompactString::new(merged_symbol));
+        self
     }
 
     /// Sets the symbol of the cell.
     pub fn set_symbol(&mut self, symbol: &str) -> &mut Self {
-        self.symbol = CompactString::new(symbol);
+        self.symbol = Some(CompactString::new(symbol));
         self
     }
 
@@ -71,14 +123,14 @@ impl Cell {
     ///
     /// This is particularly useful for adding zero-width characters to the cell.
     pub(crate) fn append_symbol(&mut self, symbol: &str) -> &mut Self {
-        self.symbol.push_str(symbol);
+        self.symbol.get_or_insert_default().push_str(symbol);
         self
     }
 
     /// Sets the symbol of the cell to a single character.
     pub fn set_char(&mut self, ch: char) -> &mut Self {
         let mut buf = [0; 4];
-        self.symbol = CompactString::new(ch.encode_utf8(&mut buf));
+        self.symbol = Some(CompactString::new(ch.encode_utf8(&mut buf)));
         self
     }
 
@@ -139,21 +191,49 @@ impl Cell {
 
     /// Resets the cell to the empty state.
     pub fn reset(&mut self) {
-        self.symbol = CompactString::const_new(" ");
-        self.fg = Color::Reset;
-        self.bg = Color::Reset;
-        #[cfg(feature = "underline-color")]
-        {
-            self.underline_color = Color::Reset;
-        }
-        self.modifier = Modifier::empty();
-        self.skip = false;
+        *self = Self::EMPTY;
     }
 }
 
-impl Default for Cell {
-    fn default() -> Self {
-        Self::EMPTY
+impl PartialEq for Cell {
+    /// Compares two `Cell`s for equality.
+    ///
+    /// Note that cells with no symbol (i.e., `Cell::EMPTY`) are considered equal to cells with a
+    /// single space symbol. This is to ensure that empty cells are treated uniformly,
+    /// regardless of how they were created
+    fn eq(&self, other: &Self) -> bool {
+        // Treat None and Some(" ") as equal
+        let symbols_eq = self.symbol() == other.symbol();
+
+        #[cfg(feature = "underline-color")]
+        let underline_color_eq = self.underline_color == other.underline_color;
+        #[cfg(not(feature = "underline-color"))]
+        let underline_color_eq = true;
+
+        symbols_eq
+            && underline_color_eq
+            && self.fg == other.fg
+            && self.bg == other.bg
+            && self.modifier == other.modifier
+            && self.skip == other.skip
+    }
+}
+
+impl Eq for Cell {}
+
+impl core::hash::Hash for Cell {
+    /// Hashes the cell.
+    ///
+    /// This treats symbols with Some(" ") as equal to None, so that empty cells are
+    /// treated uniformly, regardless of how they were created.
+    fn hash<H: core::hash::Hasher>(&self, state: &mut H) {
+        self.symbol().hash(state);
+        self.fg.hash(state);
+        self.bg.hash(state);
+        #[cfg(feature = "underline-color")]
+        self.underline_color.hash(state);
+        self.modifier.hash(state);
+        self.skip.hash(state);
     }
 }
 
@@ -175,7 +255,7 @@ mod tests {
         assert_eq!(
             cell,
             Cell {
-                symbol: CompactString::const_new("あ"),
+                symbol: Some(CompactString::const_new("あ")),
                 fg: Color::Reset,
                 bg: Color::Reset,
                 #[cfg(feature = "underline-color")]

ratatui-core/src/layout.rs

@@ -1,5 +1,314 @@
 #![warn(clippy::missing_const_for_fn)]
-//! Provides types and traits for working with layout and positioning in the terminal.
+//! Layout and positioning in terminal user interfaces.
+//!
+//! This module provides a comprehensive set of types and traits for working with layout and
+//! positioning in terminal applications. It implements a flexible layout system that allows you to
+//! divide the terminal screen into different areas using constraints, manage positioning and
+//! sizing, and handle complex UI arrangements.
+//!
+//! The layout system in Ratatui is based on the Cassowary constraint solver algorithm, implemented
+//! through the [`kasuari`] crate. This allows for sophisticated constraint-based layouts where
+//! multiple requirements can be satisfied simultaneously, with priorities determining which
+//! constraints take precedence when conflicts arise.
+//!
+//! [`kasuari`]: https://crates.io/crates/kasuari
+//!
+//! # Core Concepts
+//!
+//! ## Coordinate System
+//!
+//! The coordinate system runs left to right, top to bottom, with the origin `(0, 0)` in the top
+//! left corner of the terminal. The x and y coordinates are represented by `u16` values.
+//!
+//! ```text
+//!      x (columns)
+//!   ┌─────────────→
+//! y │ (0,0)
+//!   │
+//! (rows)
+//!   ↓
+//! ```
+//!
+//! ## Layout Fundamentals
+//!
+//! Layouts form the structural foundation of your terminal UI. The [`Layout`] struct divides
+//! available screen space into rectangular areas using a constraint-based approach. You define
+//! multiple constraints for how space should be allocated, and the Cassowary solver determines
+//! the optimal layout that satisfies as many constraints as possible. These areas can then be
+//! used to render widgets or nested layouts.
+//!
+//! Note that the [`Layout`] struct is not required to create layouts - you can also manually
+//! calculate and create [`Rect`] areas using simple mathematics to divide up the terminal space
+//! if you prefer direct control over positioning and sizing.
+//!
+//! ## Rectangular Areas
+//!
+//! All layout operations work with rectangular areas represented by the [`Rect`] type. A [`Rect`]
+//! defines a position and size in the terminal, specified by its top-left corner coordinates and
+//! dimensions.
+//!
+//! # Available Types
+//!
+//! ## Core Layout Types
+//!
+//! - [`Layout`] - The primary layout engine that divides space using constraints and direction
+//! - [`Rect`] - Represents a rectangular area with position and dimensions
+//! - [`Constraint`] - Defines how space should be allocated (length, percentage, ratio, etc.)
+//! - [`Direction`] - Specifies layout orientation (horizontal or vertical)
+//! - [`Flex`] - Controls space distribution when constraints are satisfied
+//!
+//! ## Positioning and Sizing
+//!
+//! - [`Position`] - Represents a point in the terminal coordinate system
+//! - [`Size`] - Represents dimensions (width and height)
+//! - [`Margin`] - Defines spacing around rectangular areas
+//! - [`Offset`] - Represents relative movement in the coordinate system
+//! - [`Spacing`] - Controls spacing or overlap between layout segments
+//!
+//! ## Alignment
+//!
+//! - [`Alignment`] (alias for [`HorizontalAlignment`]) - Horizontal text/content alignment
+//! - [`HorizontalAlignment`] - Horizontal alignment options (left, center, right)
+//! - [`VerticalAlignment`] - Vertical alignment options (top, center, bottom)
+//!
+//! ## Iteration Support
+//!
+//! - [`Rows`] - Iterator over horizontal rows within a rectangular area
+//! - [`Columns`] - Iterator over vertical columns within a rectangular area
+//! - [`Positions`] - Iterator over all positions within a rectangular area
+//!
+//! # Quick Start
+//!
+//! Here's a simple example of creating a basic layout using the [`Layout`] struct:
+//!
+//! ```rust
+//! use ratatui_core::layout::{Constraint, Direction, Layout, Rect};
+//!
+//! // Create a terminal area
+//! let area = Rect::new(0, 0, 80, 24);
+//!
+//! // Divide it vertically into two equal parts using Layout
+//! let layout = Layout::vertical([Constraint::Percentage(50), Constraint::Percentage(50)]);
+//! let [top, bottom] = layout.areas(area);
+//!
+//! // Now you have two areas: top and bottom
+//! ```
+//!
+//! **Note**: When the number of layout areas is known at compile time, use destructuring
+//! assignment with descriptive variable names for better readability:
+//!
+//! ```rust
+//! use ratatui_core::layout::{Constraint, Layout, Rect};
+//!
+//! let area = Rect::new(0, 0, 80, 24);
+//! let [header, content, footer] = Layout::vertical([
+//!     Constraint::Length(3),
+//!     Constraint::Fill(1),
+//!     Constraint::Length(1),
+//! ])
+//! .areas(area);
+//! ```
+//!
+//! Use [`Layout::split`] when the number of areas is only known at runtime.
+//!
+//! Alternatively, you can create layouts manually using mathematics:
+//!
+//! ```rust
+//! use ratatui_core::layout::Rect;
+//!
+//! // Create a terminal area
+//! let area = Rect::new(0, 0, 80, 24);
+//!
+//! // Manually divide into two equal parts
+//! let top_half = Rect::new(area.x, area.y, area.width, area.height / 2);
+//! let bottom_half = Rect::new(
+//!     area.x,
+//!     area.y + area.height / 2,
+//!     area.width,
+//!     area.height / 2,
+//! );
+//! ```
+//!
+//! # Layout Examples
+//!
+//! ## Basic Vertical Split
+//!
+//! ```rust
+//! use ratatui_core::layout::{Constraint, Layout, Rect};
+//!
+//! let area = Rect::new(0, 0, 80, 24);
+//! let [header, content, footer] = Layout::vertical([
+//!     Constraint::Length(3), // Header: fixed height
+//!     Constraint::Fill(1),   // Content: flexible
+//!     Constraint::Length(1), // Footer: fixed height
+//! ])
+//! .areas(area);
+//! ```
+//!
+//! ## Horizontal Sidebar Layout
+//!
+//! ```rust
+//! use ratatui_core::layout::{Constraint, Layout, Rect};
+//!
+//! let area = Rect::new(0, 0, 80, 24);
+//! let [sidebar, main] = Layout::horizontal([
+//!     Constraint::Length(20), // Sidebar: fixed width
+//!     Constraint::Fill(1),    // Main content: flexible
+//! ])
+//! .areas(area);
+//! ```
+//!
+//! ## Complex Nested Layout
+//!
+//! ```rust
+//! use ratatui_core::layout::{Constraint, Layout, Rect};
+//!
+//! fn create_complex_layout(area: Rect) -> [Rect; 4] {
+//!     // First, split vertically
+//!     let [header, body, footer] = Layout::vertical([
+//!         Constraint::Length(3), // Header
+//!         Constraint::Fill(1),   // Body
+//!         Constraint::Length(1), // Footer
+//!     ])
+//!     .areas(area);
+//!
+//!     // Then split the body horizontally
+//!     let [sidebar, main] = Layout::horizontal([
+//!         Constraint::Length(20), // Sidebar
+//!         Constraint::Fill(1),    // Main
+//!     ])
+//!     .areas(body);
+//!
+//!     [header, sidebar, main, footer]
+//! }
+//! ```
+//!
+//! # Working with Constraints
+//!
+//! [`Constraint`]s define how space is allocated within a layout using the Cassowary constraint
+//! solver algorithm. The constraint solver attempts to satisfy all constraints simultaneously,
+//! with priorities determining which constraints take precedence when conflicts arise. Different
+//! constraint types serve different purposes:
+//!
+//! - [`Constraint::Min`] - Minimum size constraint
+//! - [`Constraint::Max`] - Maximum size constraint
+//! - [`Constraint::Length`] - Fixed size in character cells
+//! - [`Constraint::Percentage`] - Relative size as a percentage of available space
+//! - [`Constraint::Ratio`] - Proportional size using ratios
+//! - [`Constraint::Fill`] - Proportional fill of remaining space
+//!
+//! Constraints are resolved in priority order, with [`Constraint::Min`] having the highest
+//! priority and [`Constraint::Fill`] having the lowest. The constraint solver will satisfy as
+//! many constraints as possible while respecting these priorities.
+//!
+//! # Flexible Space Distribution
+//!
+//! The [`Flex`] enum controls how extra space is distributed when constraints are satisfied:
+//!
+//! - [`Flex::Start`] - Align content to the start, leaving excess space at the end
+//! - [`Flex::End`] - Align content to the end, leaving excess space at the start
+//! - [`Flex::Center`] - Center content, distributing excess space equally on both sides
+//! - [`Flex::SpaceBetween`] - Distribute excess space evenly *between* elements, none at the ends
+//! - [`Flex::SpaceAround`] - Distribute space *around* elements: equal padding on both sides of
+//!   each element; gaps between elements are twice the edge spacing
+//! - [`Flex::SpaceEvenly`] - Distribute space *evenly*: equal spacing between all elements,
+//!   including before the first and after the last.
+//! - [`Flex::Legacy`] - Legacy behavior (puts excess space in the last element)
+//!
+//! # Positioning and Alignment
+//!
+//! Use [`Position`] to represent specific points in the terminal, [`Size`] for dimensions, and the
+//! alignment types for controlling content positioning within areas:
+//!
+//! ```rust
+//! use ratatui_core::layout::{Alignment, Position, Rect, Size};
+//!
+//! let pos = Position::new(10, 5);
+//! let size = Size::new(80, 24);
+//! let rect = Rect::new(pos.x, pos.y, size.width, size.height);
+//!
+//! // Alignment for content within areas
+//! let center = Alignment::Center;
+//! ```
+//!
+//! # Advanced Features
+//!
+//! ## Margins and Spacing
+//!
+//! Add spacing around areas using uniform margins or between layout segments using [`Spacing`]:
+//!
+//! ```rust
+//! use ratatui_core::layout::{Constraint, Layout, Margin, Rect, Spacing};
+//!
+//! let layout = Layout::vertical([Constraint::Fill(1), Constraint::Fill(1)])
+//!     .margin(2) // 2-cell margin on all sides
+//!     .spacing(Spacing::Space(1)); // 1-cell spacing between segments
+//!
+//! // For asymmetric margins, use the Rect inner method directly
+//! let area = Rect::new(0, 0, 80, 24).inner(Margin::new(2, 1));
+//! ```
+//!
+//! ## Area Iteration
+//!
+//! Iterate over rows, columns, or all positions within a rectangular area. The `rows()` and
+//! `columns()` iterators return full [`Rect`] regions that can be used to render widgets or
+//! passed to other layout methods for more complex nested layouts. The `positions()` iterator
+//! returns [`Position`] values representing individual cell coordinates:
+//!
+//! ```rust
+//! use ratatui_core::buffer::Buffer;
+//! use ratatui_core::layout::{Constraint, Layout, Rect};
+//! use ratatui_core::widgets::Widget;
+//!
+//! let area = Rect::new(0, 0, 20, 10);
+//! let mut buffer = Buffer::empty(area);
+//!
+//! // Renders "Row 0", "Row 1", etc. in each horizontal row
+//! for (i, row) in area.rows().enumerate() {
+//!     format!("Row {i}").render(row, &mut buffer);
+//! }
+//!
+//! // Renders column indices (0-9 repeating) in each vertical column
+//! for (i, col) in area.columns().enumerate() {
+//!     format!("{}", i % 10).render(col, &mut buffer);
+//! }
+//!
+//! // Renders position indices (0-9 repeating) at each cell position
+//! for (i, pos) in area.positions().enumerate() {
+//!     buffer[pos].set_symbol(&format!("{}", i % 10));
+//! }
+//! ```
+//!
+//! # Performance Considerations
+//!
+//! The layout system includes optional caching to improve performance for repeated layout
+//! calculations. Layout caching is enabled by default in the main `ratatui` crate, but requires
+//! explicitly enabling the `layout-cache` feature when using `ratatui-core` directly. When
+//! enabled, layout results are cached based on the area and layout configuration.
+//!
+//! # Related Documentation
+//!
+//! For more detailed information and practical examples:
+//!
+//! - [Layout Concepts](https://ratatui.rs/concepts/layout/) - Comprehensive guide to layout
+//!   concepts
+//! - [Layout Recipes](https://ratatui.rs/recipes/layout/) - Practical layout examples and patterns
+//! - [Grid Layout Recipe](https://ratatui.rs/recipes/layout/grid/) - Creating grid-based layouts
+//! - [Center a Widget Recipe](https://ratatui.rs/recipes/layout/center-a-widget/) - Centering
+//!   content
+//! - [Dynamic Layouts Recipe](https://ratatui.rs/recipes/layout/dynamic/) - Creating responsive
+//!   layouts
+//!
+//! # Examples
+//!
+//! See the Ratatui repository for complete examples:
+//!
+//! - [`constraints`](https://github.com/ratatui/ratatui/blob/main/examples/apps/constraints/) -
+//!   Demonstrates different constraint types
+//! - [`flex`](https://github.com/ratatui/ratatui/blob/main/examples/apps/flex/) - Shows flex space
+//!   distribution
+//! - [`layout`](https://github.com/ratatui/ratatui/blob/main/examples/apps/layout/) - Basic layout
+//!   examples
 
 mod alignment;
 mod constraint;
@@ -7,6 +316,7 @@ mod direction;
 mod flex;
 mod layout;
 mod margin;
+mod offset;
 mod position;
 mod rect;
 mod size;
@@ -17,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;