ratatui_ruby 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6c258db0dbb30641f2813c23f6212a3e6e3ee56c8aa3b56a428e67d4b97bcae1
-  data.tar.gz: 7dbbec9b16667b25a148bff938ea3448611689f04dae722a24600d6ebc29d9ef
+  metadata.gz: f566d7a4eb721ae0c356c7f19f60b5a91a2dd908d03b3711c655cbe61c6410b8
+  data.tar.gz: dd5fddbd898e842aef046aab8f58c85f507418edfccc6d7ff903b129329b3d3e
 SHA512:
-  metadata.gz: 9d395bce840eb550abf6f91567c1ca1952c6b7e184749c3bd7db3188d71f97a9c876af535d71cf21606e28aa23e780f5294595b54baf1640620743d8de8ef664
-  data.tar.gz: 385435bf381ba2602f8e306c74cb8842416c1bb39100cd576abedf9c0cf3421c79d688a58abd1b8a1b4915caaae781288d490a02077f3fbc04a161b891583add
+  metadata.gz: c24e93fb6fc88103b336eef4283c5d434f2625529e0a2aac8b5951fb8ae52c5ac05009beef8f72e6acd4a38534bb7b075bb21cc469c039d198b3f7fd87cfa8e7
+  data.tar.gz: 8ac6aaf12d96cba46f4ae9f6af3f7fb5e0ad9bdfacda6bef381d31a857c0f9d8c65cd7fb079f22e2961a31dad68f39744dfe7d3842b9e0e879ba568f0e820d3a

data/.builds/ruby-3.2.yml

@@ -1,22 +1,22 @@
 # SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-image: alpine/edge
+image: archlinux
 packages:
   - bash
-  - build-base
+  - base-devel
   - curl
-  - openssl-dev
-  - yaml-dev
-  - zlib-dev
-  - readline-dev
-  - gdbm-dev
-  - ncurses-dev
-  - libffi-dev
-  - clang-dev
+  - openssl
+  - libyaml
+  - zlib
+  - readline
+  - gdbm
+  - ncurses
+  - libffi
+  - clang
   - git
 artifacts:
-  - ratatui_ruby/pkg/ratatui_ruby-0.3.1.gem
+  - ratatui_ruby/pkg/ratatui_ruby-0.4.0.gem
 sources:
   - https://git.sr.ht/~kerrick/ratatui_ruby
 tasks:
@@ -24,8 +24,10 @@ tasks:
       curl https://mise.jdx.dev/install.sh | sh
       echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.buildenv
       echo 'eval "$($HOME/.local/bin/mise activate bash)"' >> ~/.buildenv
+      echo 'export LANG="en_US.UTF-8"' >> ~/.buildenv
+      echo 'export LC_ALL="en_US.UTF-8"' >> ~/.buildenv
+      echo 'export BINDGEN_EXTRA_CLANG_ARGS="-include stdbool.h"' >> ~/.buildenv
       . ~/.buildenv
-      export RUSTFLAGS="-C target-feature=-crt-static"
       export CI="true"
       cd ratatui_ruby
       sed -i 's/ruby = .*/ruby = "3.2"/' mise.toml

data/.builds/ruby-3.3.yml

@@ -1,22 +1,22 @@
 # SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-image: alpine/edge
+image: archlinux
 packages:
   - bash
-  - build-base
+  - base-devel
   - curl
-  - openssl-dev
-  - yaml-dev
-  - zlib-dev
-  - readline-dev
-  - gdbm-dev
-  - ncurses-dev
-  - libffi-dev
-  - clang-dev
+  - openssl
+  - libyaml
+  - zlib
+  - readline
+  - gdbm
+  - ncurses
+  - libffi
+  - clang
   - git
 artifacts:
-  - ratatui_ruby/pkg/ratatui_ruby-0.3.1.gem
+  - ratatui_ruby/pkg/ratatui_ruby-0.4.0.gem
 sources:
   - https://git.sr.ht/~kerrick/ratatui_ruby
 tasks:
@@ -24,8 +24,10 @@ tasks:
       curl https://mise.jdx.dev/install.sh | sh
       echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.buildenv
       echo 'eval "$($HOME/.local/bin/mise activate bash)"' >> ~/.buildenv
+      echo 'export LANG="en_US.UTF-8"' >> ~/.buildenv
+      echo 'export LC_ALL="en_US.UTF-8"' >> ~/.buildenv
+      echo 'export BINDGEN_EXTRA_CLANG_ARGS="-include stdbool.h"' >> ~/.buildenv
       . ~/.buildenv
-      export RUSTFLAGS="-C target-feature=-crt-static"
       export CI="true"
       cd ratatui_ruby
       sed -i 's/ruby = .*/ruby = "3.3"/' mise.toml

data/.builds/ruby-3.4.yml

@@ -1,22 +1,22 @@
 # SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-image: alpine/edge
+image: archlinux
 packages:
   - bash
-  - build-base
+  - base-devel
   - curl
-  - openssl-dev
-  - yaml-dev
-  - zlib-dev
-  - readline-dev
-  - gdbm-dev
-  - ncurses-dev
-  - libffi-dev
-  - clang-dev
+  - openssl
+  - libyaml
+  - zlib
+  - readline
+  - gdbm
+  - ncurses
+  - libffi
+  - clang
   - git
 artifacts:
-  - ratatui_ruby/pkg/ratatui_ruby-0.3.1.gem
+  - ratatui_ruby/pkg/ratatui_ruby-0.4.0.gem
 sources:
   - https://git.sr.ht/~kerrick/ratatui_ruby
 tasks:
@@ -24,8 +24,10 @@ tasks:
       curl https://mise.jdx.dev/install.sh | sh
       echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.buildenv
       echo 'eval "$($HOME/.local/bin/mise activate bash)"' >> ~/.buildenv
+      echo 'export LANG="en_US.UTF-8"' >> ~/.buildenv
+      echo 'export LC_ALL="en_US.UTF-8"' >> ~/.buildenv
+      echo 'export BINDGEN_EXTRA_CLANG_ARGS="-include stdbool.h"' >> ~/.buildenv
       . ~/.buildenv
-      export RUSTFLAGS="-C target-feature=-crt-static"
       export CI="true"
       cd ratatui_ruby
       sed -i 's/ruby = .*/ruby = "3.4"/' mise.toml

data/.builds/ruby-4.0.0.yml

@@ -1,22 +1,22 @@
 # SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-image: alpine/edge
+image: archlinux
 packages:
   - bash
-  - build-base
+  - base-devel
   - curl
-  - openssl-dev
-  - yaml-dev
-  - zlib-dev
-  - readline-dev
-  - gdbm-dev
-  - ncurses-dev
-  - libffi-dev
-  - clang-dev
+  - openssl
+  - libyaml
+  - zlib
+  - readline
+  - gdbm
+  - ncurses
+  - libffi
+  - clang
   - git
 artifacts:
-  - ratatui_ruby/pkg/ratatui_ruby-0.3.1.gem
+  - ratatui_ruby/pkg/ratatui_ruby-0.4.0.gem
 sources:
   - https://git.sr.ht/~kerrick/ratatui_ruby
 tasks:
@@ -24,8 +24,10 @@ tasks:
       curl https://mise.jdx.dev/install.sh | sh
       echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.buildenv
       echo 'eval "$($HOME/.local/bin/mise activate bash)"' >> ~/.buildenv
+      echo 'export LANG="en_US.UTF-8"' >> ~/.buildenv
+      echo 'export LC_ALL="en_US.UTF-8"' >> ~/.buildenv
+      echo 'export BINDGEN_EXTRA_CLANG_ARGS="-include stdbool.h"' >> ~/.buildenv
       . ~/.buildenv
-      export RUSTFLAGS="-C target-feature=-crt-static"
       export CI="true"
       cd ratatui_ruby
       sed -i 's/ruby = .*/ruby = "4.0.0"/' mise.toml

data/AGENTS.md

@@ -16,6 +16,13 @@ Architecture:
 -   **Frontend (Ruby):** Pure `Data` objects (Ruby 3.2+) defining the View Tree. Immediate mode.
 -   **Backend (Rust):** A generic renderer using `ratatui` and `magnus` that traverses the Ruby `Data` tree and renders to the terminal buffer.
 
+## Stability & Compatibility
+
+-   **Project Status:** Pre-1.0. 
+-   **User Base:** 0 users (internal/experimental).
+-   **Breaking Changes:** Backward compatibility is **NOT** a priority at this stage. Since there are no external users, you are encouraged to refactor APIs for better ergonomics and performance even if it breaks existing code.
+-   **Requirement:** All breaking changes **MUST** be explicitly documented in the [CHANGELOG.md](CHANGELOG.md)'s **Unreleased** section to ensure transparency as the project evolves toward 1.0.
+
 ## 1. File & Coding Standards
 
 ### Licensing & Copyright (Strict)
@@ -36,7 +43,18 @@ Every file must begin with an SPDX-compliant header. Use the following format:
 ### Ruby Standards
 
 -   **Version:** Tested against the latest releases of Ruby 3.2, 3.3, 3.4, and 4.0, and must work on all of them. Local development happens on the latest stable release.
--   **Linter:** Run via `bundle exec rake lint`. You are not done until all linting passes.
+-   **Linter & Testing (CRITICAL):**
+    -   **ALWAYS use `bin/agent_rake`** for running tests, linting, or checking compilation.
+    -   **NEVER** run `bundle exec rake` directly. **NEVER** run `bundle exec ruby -Ilib:test ...` directly.
+    -   **VIOLATION OF THIS RULE IS A CRITICAL ERROR.**
+    -   **Why?**
+        1.  **Noise Reduction:** Standard `rake` output includes massive amounts of Rust compilation noise that floods your context window, truncating the actual error message. `bin/agent_rake` captures this silently.
+        2.  **Atomic Dump:** Agents work best with a single "Atomic Dump" of the failure. `bin/agent_rake` provides this by swallowing successful output and only printing the failure log if something goes wrong.
+        3.  **Merged Output:** It correctly merges stdout (Minitest failures) and stderr (Rust warnings) so you see them in temporal order.
+    -   **Usage:**
+        -   Runs default task (compile + test + lint): `bin/agent_rake`
+        -   Runs specific task: `bin/agent_rake test:ruby` (for example)
+    -   **Interpretation:** If the User says "rake test fails" or "fix the build" or "bin/agent_rake fails", they IMPLICITLY mean "run `bin/agent_rake` and fix the reported errors". Do not ask for clarification; just use `bin/agent_rake`.
 -   **Style:**
     -   Use `Data.define` for all value objects (UI Nodes). (Prefer `class Foo < Data.define()` over `Foo = Data.define() do`).
     -   Prefer `frozen_string_literal: true`.
@@ -64,7 +82,7 @@ The project follows a standard Gem layout with an `ext/` directory for Rust code
 ├── .cargo/                 # Cargo configuration (linker flags)
 ├── .github/                # CI/CD workflows
 ├── bin/                    # Executables (console, setup)
-├── docs/                   # Documentation tree
+├── doc/                    # Documentation source (markdown for RDoc)
 │   ├── contributors/       # Design docs, ecosystem notes
 │   └── index.md
 ├── ext/
@@ -94,15 +112,15 @@ The project follows a standard Gem layout with an `ext/` directory for Rust code
 ### Development Environment
 
 -   **Setup:** `bin/setup` must handle both Bundler and Cargo dependencies.
--   **Pre-commit:** Use `.pre-commit-config.yaml` to enforce `bundle exec rake` and `cargo fmt`.
+-   **Pre-commit:** Use `bin/agent_rake` to ensure commit-readiness. See Ruby Standards for detailed instructions.
 
 ### Documentation
 
--   Follow the `docs/` structure: `index.md` -> `contributors/` | `quickstart.md`.
+-   **The `doc/` folder contains source markdown files** that are included in RDoc output. Follow the structure: `index.md` -> `contributors/` | `quickstart.md`.
+-   **The `tmp/rdoc/` folder is auto-generated** by `bundle exec rake rerdoc`. Never edit files in `tmp/rdoc/` directly.
 -   Documentation should separate "User Guide" (Ruby API for TUI developers) from "Contributor Guide" (Ruby/Rust/Magnus internals).
+-   **Style Guide:** You **MUST** follow the [Documentation Style Guide](doc/contributors/documentation_style.md). This dictates the Alexandrian/Zinsser prose style and strict RDoc formatting required for all public API documentation.
 -   Don't write .md files for something RDoc (Ruby) or rustdoc (Rust) can generate.
--   **The `doc/` folder contains source markdown files** that are included in RDoc output. You can edit these files.
--   **The `tmp/rdoc/` folder is auto-generated** by `bundle exec rake rerdoc`. Never edit files in `tmp/rdoc/` directly.
 
 ## 4. The Ruby <-> Rust Bridge Contract
 
@@ -119,17 +137,24 @@ The project follows a standard Gem layout with an `ext/` directory for Rust code
 -   The gem builds a native extension.
 -   Artifact naming: Ensure the output shared library matches Ruby's expectation on macOS (rename `.dylib`to `.bundle` if necessary during the build process in `extconf.rb` or `Rakefile`).
 
-## 6. Source Control Standards
+## 6. Commit Message
 
 -   **Commits:**
-    -   Who commits: Only humans should affect the git index and history. Rather than staging and/or committing, you should suggest a commit message.
+    -   Who commits: Only humans should affect the git index and history. Do not stage (do not `git add`). Do not commit. Just suggest a commit message.
     -   When: At the end of each task, before reporting the task as complete to the user, suggest the commit message.
+    -   What: Consider not just what you remember, but also everything in the `git diff` and `git diff --cached`.
 -   **Format:**
-    -   Subject line: Concise summary (50 chars or less).
-    -   Body: Detailed explanation if necessary (wrap at 72 chars). Explain why this is the implementation, as opposed to other possible implementations. Skip the body entirely if it's rote, a duplication of the diff, or otherwise unhelpful. **Do not simply list the files changed or the minor edits made to them.** Do not use markdown, except as required in AI Attribution.
+    -   Format: Use [Conventional Commits](https://www.conventionalcommits.org/).
+        -   Structure: `type(scope): description` (e.g., `feat(widget): add Gauge widget`).
+        -   Subject line: Concise summary (50 chars or less).
+    -   Body: Explanation if necessary (wrap at 72 chars).
+        -   Explain why this is the implementation, as opposed to other possible implementations.
+        -   Skip the body entirely if it's rote, a duplication of the diff, or otherwise unhelpful.
+        -   **DO NOT list the files changed or the edits made in the body.** Do not provide a bulleted list of changes. Use prose to explain the problem and the solution.
+        -   **Do not use markdown syntax** (no backticks, no bolding, no lists, no links), except as required in AI Attribution. The commit message must be plain text.
     -   Footer: AI attribution if generated by an agent, sourcehut ticket if implemented by a ticket, or both.
 -   **AI Attribution:**
-     -   **Always include AI attribution** in the footer if the commit was generated or significantly assisted by an AI agent. This is mandatory for transparency and compliance.
+     -   **Always include AI attribution** in the footer if the commit was generated or significantly assisted by an AI agent. This is mandatory for transparency and compliance. **This is NOT optional.**
      -   **Amp:**
          ```
          Generated with [Amp](https://ampcode.com)
@@ -162,13 +187,29 @@ The project follows a standard Gem layout with an `ext/` directory for Rust code
          ```
 -   **Sourcehut Tickets:**
     - If the commit implements a specific ticket, include a footer: `Implements: https://todo.sr.ht/~kerrick/ratatui_ruby/<id>`
+    - **Do NOT** include this footer if you were not given a specific ticket ID or URL. Do not hallucinate or guess ticket URLs.
     - This must be the **last** item in the footer, if present.
 
 ## 7. Definition of Done
 
 Before considering a task complete and returning control to the user, you **MUST** ensure:
 
-1.  **Tests & Linting Pass:** Run `bundle exec rake` and confirm it passes. No new errors **or warnings** should be introduced.
+1.  **Default Rake Task Passes:** Run `bin/agent_rake` to execute **ALL** tests and linting. Do not rely on partial test runs, or `rake test`, or `rake lint` alone. Confirm it passes with no new errors **or warnings**.
 2.  **Documentation Updated:** If public APIs or observable behavior changed, update relevant `doc/` files, `README.md`, and/or `ratatui_ruby-wiki` files,.
-3.  **Changelog Updated:** If public APIs, observable behavior, or gemspec dependencies changed, update [CHANGELOG.md](CHANGELOG.md)'s **Unreleased** section according to the [Semantic Versioning](https://semver.org/) and [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) specifications. Changelogs should be useful to human users of the library, not simple restatements of diffs or commit messages. **Do not add entries for internal tooling, CI, or build configuration changes that do not affect the distributed gem.**
+3.  **Changelog Updated:** If public APIs, observable behavior, or gemspec dependencies changed, update [CHANGELOG.md](CHANGELOG.md)'s **Unreleased** section according to the [Semantic Versioning](https://semver.org/) and [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) specifications. 
+    - **What belongs in CHANGELOG:** Only changes that affect **application developers** or **library developers** who use or depend on ratatui_ruby:
+      - New public APIs or widget parameters
+      - Observable behavior changes (rendering, styling, layout)
+      - Deprecations and removals
+      - Breaking changes
+      - New public examples (if they demonstrate significant features)
+      - Performance improvements that affect applications
+    - **What does NOT belong in CHANGELOG:** Internal changes that don't affect downstream users:
+      - Test additions or improvements
+      - Documentation updates, RDoc fixes, markdown clarifications
+      - Refactors of internal code
+      - New or modified example code (unless the example itself is a major feature)
+      - Internal tooling, CI/CD, or build configuration changes
+      - Code style, linting, or type signature changes
+    - Changelogs should be useful to downstream developers (both app and library developers), not simple restatements of diffs or commit messages.
 4.  **Commit Message Suggested:** You **MUST** ensure the final message to the user includes a suggested commit message block. This is NOT optional.

data/CHANGELOG.md

@@ -18,6 +18,188 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ### Removed
 
+## [0.4.0] - 2025-12-30
+
+### Added
+
+#### Hex Color Support
+
+- **Style**: `fg` and `bg` parameters now accept hex color strings (e.g., `"#ff0000"` for red). Requires a 24-bit true color capable terminal (Kitty, iTerm2, modern Terminal.app). Terminals without true color support will gracefully fall back to the closest ANSI color.
+
+#### RatatuiMascot Widget
+
+- **RatatuiMascot**: New widget to display the Ratatui mascot (Ferris).
+
+#### RatatuiLogo Widget
+
+- **RatatuiLogo**: New widget to display the Ratatui logo.
+
+
+#### Duck-Typed Numeric Coercion
+
+- All numeric parameters now accept any object that responds to `to_f` (for floats) or `to_int`/`to_i` (for integers). This provides idiomatic Ruby interoperability with `BigDecimal`, `Rational`, and custom numeric types. Uses Ruby's built-in `Float()` and `Integer()` Kernel methods for proper duck-type handling.
+
+#### Paragraph Widget
+
+- `alignment`: **Breaking Change**: Renamed `align` to `alignment` to match Ratatui 0.30 API.
+
+#### Custom Widgets
+
+- **Draw Command API**: Custom widgets now return an array of `Draw` commands instead of writing to a buffer. Use `RatatuiRuby::Draw.string(x, y, string, style)` and `RatatuiRuby::Draw.cell(x, y, cell)` to create draw commands. This eliminates use-after-free bugs by keeping all pointers inside Rust while Ruby works with pure data objects. **Breaking:** The `render` method signature changed from `render(area, buffer)` to `render(area)`.
+
+#### BarChart Widget
+
+- `bar_set`: Customize bar characters (digits, symbols, blocks).
+- `group_gap`: Control spacing between groups in grouped bar charts.
+- `data`: Now accepts an Array of `BarGroup` objects, enabling grouped bar charts.
+- `Bar` and `BarGroup`: New schema classes for defining grouped bar data.
+
+#### Block Widget
+
+- `border_type`: Customize border style (`:plain`, `:rounded`, `:double`, `:thick`, `:quadrant_inside`, `:quadrant_outside`).
+- `border_set`: Customize border characters (e.g., digits, symbols).
+- `border_style`: Apply full style support (colors and modifiers) to borders. Takes precedence over `border_color`.
+- `children`: Declare child widgets within the block's area for composable UI structures.
+- Multiple `titles`: Display multiple titles with individual alignment (`:left`, `:center`, `:right`) and vertical positioning (`:top`, `:bottom`). Each title supports its own `style`.
+- `title_style`: Base style applied to all titles.
+- `style`: Base style applied to the entire block.
+- `padding`: Directional padding via a single integer (uniform) or array of 4 integers (`[left, right, top, bottom]`).
+- `line_count(width)`: **(Experimental)** Calculate rendered lines (including borders/padding) for a given width. Delegates to Ratatui's underlying unstable `line_count`.
+- `line_width`: **(Experimental)** Calculate minimum width to avoid wrapping (including borders/padding). Delegates to Ratatui's underlying unstable `line_width`.
+
+#### Calendar Widget
+
+- `events`: Hash mapping `Date` objects to `Style` objects for highlighting specific dates.
+- `show_month_header`: Toggle month header visibility (defaults to `false`). **Breaking:** Previously always shown.
+- `show_weekdays_header`: Toggle weekday names (Mon, Tue, etc.) visibility (defaults to `true`).
+- `show_surrounding`: Optional `Style` to display dates from adjacent months, or `nil` to hide them.
+
+#### Chart Widget
+
+- `legend_position`: Position legend at `:top_left`, `:top_right`, `:bottom_left`, or `:bottom_right` (defaults to `:top_right`).
+- `hidden_legend_constraints`: Array of two `Constraint` objects to hide the legend when chart area is too small.
+- **Axis**: `labels_alignment` to control horizontal alignment (`:left`, `:center`, `:right`) of axis labels.
+- `Dataset`: `style` parameter replaces `color`, enabling full styling (fg, bg, modifiers) for chart datasets. **Breaking**: `color` parameter removed.
+
+#### Gauge Widget
+
+- `style`: Base style applied to the entire gauge background.
+- `gauge_style`: Style applied specifically to the filled bar. **Breaking:** Use this instead of `style` if you want bar coloring; `style` no longer defaults to `Style.default`.
+- `percent`: Convenience parameter alternative to `ratio` for initialization.
+- `use_unicode`: Explicitly toggle between unicode blocks and ASCII rendering (defaults to `true`).
+
+#### LineGauge Widget
+
+- `style`: Base style applied to the entire gauge area.
+
+#### List Widget
+
+- `scroll_padding`: Number of items to keep visible above and below the selected item during scrolling.
+- `repeat_highlight_symbol`: When `true`, repeat highlight symbol on each line of multi-line selections.
+- `highlight_spacing`: Control selection column reservation (`:always`, `:when_selected`, `:never`).
+- `direction`: List orientation (`:top_to_bottom` or `:bottom_to_top`).
+
+#### Sparkline Widget
+
+- `absent_value_symbol` and `absent_value_style`: Customize rendering of `nil` values (distinct from `0`).
+- `direction`: Rendering direction (`:left_to_right` or `:right_to_left`).
+- `bar_set`: Customize bar characters.
+
+#### Table Widget
+
+- `style`: Base style applied to the entire table.
+- `column_spacing`: Horizontal spacing between columns.
+- `footer`: Summary rows at the bottom of the table.
+- `flex`: Layout distribution mode (`:legacy`, `:start`, `:center`, `:end`, `:space_between`, `:space_around`, `:space_evenly`).
+- `highlight_spacing`: Control selection column reservation (`:always`, `:when_selected`, `:never`).
+- `column_highlight_style`: Style applied to the selected column.
+- `cell_highlight_style`: Style applied to the selected cell (intersection of row and column).
+- `selected_column`: Index of the selected column (Integer or nil).
+- `widths`: Now support all constraint types (`:max`, `:fill`, `:ratio`) with full flexibility.
+
+#### Tabs Widget
+
+- `style`: Base style applied to the entire tabs area.
+- `padding_left` and `padding_right`: Horizontal padding around tab titles.
+- `width`: Calculate total width of the tabs (including dividers/padding).
+
+#### Canvas Widget
+
+- `background_color`: Set canvas background color.
+- `:half_block` marker: Block-based rendering using half-height blocks.
+- `:quadrant`, `:sextant`, `:octant` markers: High-resolution pseudo-pixel rendering.
+- `Shape::Label`: Text labels at canvas coordinates with optional styling.
+
+#### Scrollbar Widget
+
+- Full styling support: `thumb_style`, `track_symbol`, `track_style`, `begin_symbol`, `begin_style`, `end_symbol`, `end_style`, `style`.
+- All orientation variants: `:vertical_left`, `:vertical_right`, `:horizontal_top`, `:horizontal_bottom` (`:vertical` and `:horizontal` remain as aliases).
+
+#### Layout & Constraints
+
+- `Constraint.ratio(numerator, denominator)`: Proportional constraints with explicit ratio.
+- `Constraint.fill(weight)`: Distribute remaining space proportionally. Use multiple `Fill` to split space (e.g., `Fill(1)` and `Fill(3)` split 1:3).
+- `Constraint.max(value)`: Cap maximum size of a section.
+- `Layout.split(area, direction:, constraints:, flex:)`: Compute layout rectangles without rendering, enabling hit testing.
+- `Flex::SpaceEvenly`: New layout mode for `Layout` widget.
+- `flex` parameter: All layout options (`:legacy`, `:start`, `:center`, `:end`, `:space_between`, `:space_around`, `:space_evenly`).
+
+#### Rich Text & Text Components
+
+- `Text::Span` and `Text::Line`: Styled text with inline formatting. Combine spans into lines with optional alignment.
+- `Shape` module: Canvas shape primitives (`Shape::Line`, `Shape::Circle`, `Shape::Rectangle`, `Shape::Point`, `Shape::Map`) to avoid naming conflicts with `Text::Line`.
+
+#### Event System
+
+- Typed `Event` API: `RatatuiRuby.poll_event` returns typed objects (`Event::Key`, `Event::Mouse`, `Event::Resize`, `Event::Paste`, `Event::FocusGained`, `Event::FocusLost`).
+- Predicate methods: `key?`, `mouse?`, `ctrl?`, etc. for cleaner event handling.
+- Pattern matching support and discriminator pattern via `type:` key in `#deconstruct_keys`.
+- `Event::Resize`: Terminal resize events with `width` and `height` attributes.
+- `Event::Paste`: Bracketed paste as atomic event with `content:`.
+- `Event::FocusGained` and `Event::FocusLost`: Terminal focus changes.
+- `Event::Mouse.new` accepts `nil` for `button` parameter (treated as `"none"`).
+
+#### Geometry & Hit Testing
+
+- `Rect#contains?(x, y)`: Test whether a point is inside a rectangle. Essential for mouse click handlers.
+- `Layout.split`: Enables calculating widget positions before rendering.
+
+#### Testing
+
+- `RatatuiRuby::TestHelper#inject_keys`: Concise event injection helper.
+- `RatatuiRuby::TestHelper#get_cell` and `#assert_cell_style`: Inspect terminal cell attributes (colors, characters).
+- `with_test_terminal`: Default timeout of 2 seconds to prevent hanging tests. **Breaking:** Default size is now 80×24 (VT100 standard) instead of 20×10.
+- Error on `inject_event`/`inject_keys` outside `with_test_terminal`: Prevents test hangs from race conditions.
+- Value equality (`==`) for `Event` objects: Simplify assertions.
+
+#### Lifecycle & Application Structure
+
+- `RatatuiRuby.run`: New context manager that initializes terminal, yields session, and restores on exit. Allows custom event loop control.
+- **Session** class: Renamed from `DSL` to better reflect its purpose as a managed terminal session with convenience methods.
+- Focus and Bracketed Paste events: Enabled by default in `RatatuiRuby.run` and `RatatuiRuby.init_terminal` (disable with `focus_events: false` or `bracketed_paste: false`).
+
+#### Documentation & Examples
+
+- **Cached Layout Pattern**: Documented in `doc/interactive_design.md`. Three-phase lifecycle pattern (`calculate_layout`, `render`, `handle_input`) solves layout duplication in immediate-mode UI. Foundation for Component architecture in Gem 1.5.
+
+### Changed
+
+- **Calendar:** Renamed `day_style` to `default_style` to match Ratatui 0.30 API. This is a breaking change. [Kerrick Long]
+
+- **Custom Widget `render` Method (Breaking)**: Changed signature from `render(area, buffer)` to `render(area)`, with render methods now returning an array of `Draw` commands instead of writing directly to a buffer. This change improves memory safety by eliminating use-after-free risks.
+- **Ratatui Upgraded to 0.30.0**: Underlying `ratatui` library upgraded from 0.29, bringing modularized crates, `no_std` support for embedded targets, and major widget/layout enhancements. Layout cache explicitly enabled for performance.
+- **Event API (Breaking)**: `RatatuiRuby.poll_event` returns typed `Event` objects instead of raw Hashes. Code using `event[:type]` must change to `event.key?`, `event.code`, etc.
+- **RatatuiRuby.main_loop Removed (Breaking)**: Removed in favor of `RatatuiRuby.run` for more explicit lifecycle control.
+- **TestHelper Terminal Size (Breaking)**: `with_test_terminal` defaults to 80×24 instead of 20×10.
+- **Calendar Month Header Default (Breaking)**: `show_month_header` defaults to `false` (previously always shown). Set `show_month_header: true` if relying on the old behavior.
+- **Gauge `style` Default (Breaking)**: No longer defaults to `Style.default`. Use `gauge_style` for bar coloring instead.
+
+### Fixed
+
+- **Alpine Linux Support**: Fixed gem installation failures on Alpine Linux (musl targets) by properly configuring `crate-type` to support static linking where dynamic linking is unsupported.
+- **Rust Safety**: Convert `class.name()` results to owned strings for proper GC safety with Magnus 0.8.
+- **Terminal Preview Detection**: Detect staged changes correctly in preview generation.
+
 ## [0.3.1] - 2025-12-28
 
 ### Added
@@ -28,10 +210,12 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ### Added
 
+- **Custom Widget API (Breaking)**: Custom widgets that define a `render` method now receive only `area` (not `buffer`) and must return an array of `Draw` commands. Use `RatatuiRuby::Draw.string(x, y, string, style)` and `RatatuiRuby::Draw.cell(x, y, cell)` instead of `buffer.set_string` and `buffer.set_cell`. This eliminates a class of use-after-free bugs by ensuring Ruby never holds pointers to Rust-owned memory. Widgets can now be unit tested by asserting on the returned array.
 - **The Escape Hatch (Ruby Render Callback)**: Added the ability to define custom widgets in pure Ruby by implementing a `render(area, buffer)` method. The `Buffer` object provides low-level drawing primitives like `set_string`, allowing developers to create custom TUI components without writing Rust code.
 - **Clear Widget**: Added the `Clear` widget, which resets the terminal buffer in the area it is rendered. This is essential for creating opaque popups and modals that prevent background styles from "bleeding" through transparent widgets.
 - **Interactive Table Selection**: The `Table` widget now supports row selection with `selected_row`, `highlight_style`, and `highlight_symbol` parameters. This enables building interactive data grids and file explorers where users can navigate through rows using keyboard input.
 - **Scrollable Paragraphs**: The `Paragraph` widget now supports a `scroll` parameter that accepts a `(y, x)` array to scroll content vertically and horizontally. This enables viewing long text content that exceeds the visible area, such as logs or documents. The parameter order matches ratatui's convention.
+- **Enhanced Tabs Customization**: The `Tabs` widget now supports `highlight_style` for the selected tab and a customizable `divider` string (defaulting to the standard pipe `|`). This allows for richer visual feedback in tabbed interfaces.
 
 ### Changed
 
@@ -65,7 +249,8 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 - **Input Handling**: Robust handling for both Keyboard and Mouse events.
 - **Testing Support**: Included `RatatuiRuby::TestHelper` and RSpec integration to make testing your TUI applications possible.
 
-[Unreleased]: https://git.sr.ht/~kerrick/ratatui_ruby/compare/v0.3.1...HEAD
+[Unreleased]: https://git.sr.ht/~kerrick/ratatui_ruby/compare/v0.4.0...HEAD
+[0.4.0]: https://git.sr.ht/~kerrick/ratatui_ruby/compare/v0.3.1...v0.4.0
 [0.3.1]: https://git.sr.ht/~kerrick/ratatui_ruby/compare/v0.3.0...v0.3.1
 [0.3.0]: https://git.sr.ht/~kerrick/ratatui_ruby/compare/v0.2.0...v0.3.0
 [0.2.0]: https://git.sr.ht/~kerrick/ratatui_ruby/compare/v0.1.0...v0.2.0

data/README.md

@@ -9,7 +9,7 @@ builds.sr.ht status](https://builds.sr.ht/~kerrick/ratatui_ruby.svg)](https://bu
 License](https://img.shields.io/badge/dynamic/regex?url=https%3A%2F%2Fgit.sr.ht%2F~kerrick%2Fratatui_ruby%2Fblob%2Fmain%2Fratatui_ruby.gemspec&search=spec%5C.license%20%3D%20%22(.*)%22&replace=%241&label=License&color=a2c93e)](https://spdx.org/licenses/AGPL-3.0-or-later.html) [![
 Gem Total Downloads](https://img.shields.io/gem/dt/ratatui_ruby)](https://rubygems.org/gems/ratatui_ruby) [![
 Gem Version](https://img.shields.io/gem/v/ratatui_ruby)](https://rubygems.org/gems/ratatui_ruby) [![
-Ratatui Version](https://img.shields.io/badge/dynamic/toml?url=https%3A%2F%2Fgit.sr.ht%2F~kerrick%2Fratatui_ruby%2Fblob%2Fmain%2Fext%2Fratatui_ruby%2FCargo.toml&query=%24.dependencies.ratatui.version&prefix=v&logo=ratatui&label=Ratatui)](https://crates.io/crates/ratatui/0.26.3) [![
+Ratatui Version](https://img.shields.io/badge/dynamic/toml?url=https%3A%2F%2Fgit.sr.ht%2F~kerrick%2Fratatui_ruby%2Fblob%2Fmain%2Fext%2Fratatui_ruby%2FCargo.toml&query=%24.dependencies.ratatui.version&prefix=v&logo=ratatui&label=Ratatui)](https://crates.io/crates/ratatui/0.30) [![
 Mailing List: Discussion](https://img.shields.io/badge/mailing_list-discussion-5865F2.svg?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJub25lIiBzdHJva2U9IiNmZmZmZmYiIHN0cm9rZS13aWR0aD0iMiIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIiBzdHJva2UtbGluZWpvaW49InJvdW5kIiBjbGFzcz0iaWNvbiBpY29uLXRhYmxlciBpY29ucy10YWJsZXItb3V0bGluZSBpY29uLXRhYmxlci1tYWlsIj48cGF0aCBzdHJva2U9Im5vbmUiIGQ9Ik0wIDBoMjR2MjRIMHoiIGZpbGw9Im5vbmUiLz48cGF0aCBkPSJNMyA3YTIgMiAwIDAgMSAyIC0yaDE0YTIgMiAwIDAgMSAyIDJ2MTBhMiAyIDAgMCAxIC0yIDJoLTE0YTIgMiAwIDAgMSAtMiAtMnYtMTB6IiAvPjxwYXRoIGQ9Ik0zIDdsOSA2bDkgLTYiIC8+PC9zdmc+Cg==)](https://lists.sr.ht/~kerrick/ratatui_ruby-discuss) [![
 Mailing List: Development](https://img.shields.io/badge/mailing_list-development-4954d5.svg?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJub25lIiBzdHJva2U9IiNmZmZmZmYiIHN0cm9rZS13aWR0aD0iMiIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIiBzdHJva2UtbGluZWpvaW49InJvdW5kIiBjbGFzcz0iaWNvbiBpY29uLXRhYmxlciBpY29ucy10YWJsZXItb3V0bGluZSBpY29uLXRhYmxlci1tYWlsIj48cGF0aCBzdHJva2U9Im5vbmUiIGQ9Ik0wIDBoMjR2MjRIMHoiIGZpbGw9Im5vbmUiLz48cGF0aCBkPSJNMyA3YTIgMiAwIDAgMSAyIC0yaDE0YTIgMiAwIDAgMSAyIDJ2MTBhMiAyIDAgMCAxIC0yIDJoLTE0YTIgMiAwIDAgMSAtMiAtMnYtMTB6IiAvPjxwYXRoIGQ9Ik0zIDdsOSA2bDkgLTYiIC8+PC9zdmc+Cg==)](https://lists.sr.ht/~kerrick/ratatui_ruby-devel) [![
 Mailing List: Announcements](https://img.shields.io/badge/mailing_list-announcements-3b44ac.svg?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJub25lIiBzdHJva2U9IiNmZmZmZmYiIHN0cm9rZS13aWR0aD0iMiIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIiBzdHJva2UtbGluZWpvaW49InJvdW5kIiBjbGFzcz0iaWNvbiBpY29uLXRhYmxlciBpY29ucy10YWJsZXItb3V0bGluZSBpY29uLXRhYmxlci1tYWlsIj48cGF0aCBzdHJva2U9Im5vbmUiIGQ9Ik0wIDBoMjR2MjRIMHoiIGZpbGw9Im5vbmUiLz48cGF0aCBkPSJNMyA3YTIgMiAwIDAgMSAyIC0yaDE0YTIgMiAwIDAgMSAyIDJ2MTBhMiAyIDAgMCAxIC0yIDJoLTE0YTIgMiAwIDAgMSAtMiAtMnYtMTB6IiAvPjxwYXRoIGQ9Ik0zIDdsOSA2bDkgLTYiIC8+PC9zdmc+Cg==)](https://lists.sr.ht/~kerrick/ratatui_ruby-announce)
@@ -21,7 +21,7 @@ Mailing List: Announcements](https://img.shields.io/badge/mailing_list-announcem
 **ratatui_ruby** is a community wrapper that is not affiliated with [the Ratatui team](https://github.com/orgs/ratatui/people).
 
 > [!WARNING]  
-> **ratatui_ruby** is currently in an early stage of development. Use at your own risk.
+> **ratatui_ruby** is currently in **BETA**. The API may change between minor versions.
 
 Please join the **announce** mailing list at https://lists.sr.ht/~kerrick/ratatui_ruby-announce to stay up-to-date on new releases and announcements.
 
@@ -65,22 +65,24 @@ gem install ratatui_ruby
 
 ```ruby
 require "ratatui_ruby"
-RatatuiRuby.main_loop do |tui|
-  tui.draw \
-    tui.paragraph \
-        text: "Hello, Ratatui! Press 'q' to quit.",
-        align: :center,
-        block: tui.block(
-          title: "My Ruby TUI App",
-          borders: [:all],
-          border_color: "cyan"
-        )
-  event = tui.poll_event
-  break if event && event[:type] == :key && event[:code] == "q"
+RatatuiRuby.run do |tui|
+  loop do
+    tui.draw \
+      tui.paragraph \
+          text: "Hello, Ratatui! Press 'q' to quit.",
+          alignment: :center,
+          block: tui.block(
+            title: "My Ruby TUI App",
+            borders: [:all],
+            border_color: "cyan"
+          )
+    event = tui.poll_event
+    break if event == "q" || event == :ctrl_c
+  end
 end
 ```
 
-For a full tutorial, see [the Quickstart](./doc/quickstart.md).
+For a full tutorial, see [the Quickstart](./doc/quickstart.md). For an explanation of the application architecture, see [Application Architecture](./doc/application_architecture.md).
 
 
 ## Documentation