ratatui_ruby 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c8ee9b7928a67c0f332a1fdfd2870972ba9f37c6219879d427a5225f71a24b54
-  data.tar.gz: 42ef63b4ca0dafb3220034af83a1d5d0acab49123378e0c5909b21c9baf60f52
+  metadata.gz: e4af7cd6e9b1850a0abe3099f29c1dbf4d9e4f01cd1782196b0948c8591d9ba3
+  data.tar.gz: 7e68a66603d410baaad20d9267b3da083bff66a1a9c7d3dd9d0142a4b89fca9f
 SHA512:
-  metadata.gz: 68ec1dcf33fa00b9bb53852d5cc4c92c680f10924b13594854c34bc3e597db6214603c1513427cad35e31895d08cc7dd59e2ac1166dcd44f525043588b23407d
-  data.tar.gz: c9cfbe2d111ca45cfe003fc28dea7d23f12dac8c14424701a8532d964d905e80d2fbdd2fdb2a749a291a23ef4e168e2ab0fac14c55ef874b5e1b357d75f4b66f
+  metadata.gz: b3790091fe5de4276ff383caffc753012efc7d8646eb7d2d5a2467e73518dbd8584c692ffec368a374d6cf9a11981be6af0d3d51a1421e48f4afe1e528547618
+  data.tar.gz: f63f2bbb7abf4462be09d17aabc8bdf7737853b79e4ff5d55425a2246687a23c47e5a04c19bd41405171f0e14f94749ba70e5fe07578ffcb5ffec1e248f43246

data/.builds/ruby-3.2.yml

@@ -16,7 +16,7 @@ packages:
   - clang
   - git
 artifacts:
-  - ratatui_ruby/pkg/ratatui_ruby-1.0.0.gem
+  - ratatui_ruby/pkg/ratatui_ruby-1.1.0.gem
 sources:
   - https://git.sr.ht/~kerrick/ratatui_ruby
 tasks:

data/.builds/ruby-3.3.yml

@@ -16,7 +16,7 @@ packages:
   - clang
   - git
 artifacts:
-  - ratatui_ruby/pkg/ratatui_ruby-1.0.0.gem
+  - ratatui_ruby/pkg/ratatui_ruby-1.1.0.gem
 sources:
   - https://git.sr.ht/~kerrick/ratatui_ruby
 tasks:

data/.builds/ruby-3.4.yml

@@ -16,7 +16,7 @@ packages:
   - clang
   - git
 artifacts:
-  - ratatui_ruby/pkg/ratatui_ruby-1.0.0.gem
+  - ratatui_ruby/pkg/ratatui_ruby-1.1.0.gem
 sources:
   - https://git.sr.ht/~kerrick/ratatui_ruby
 tasks:

data/.builds/ruby-4.0.0.yml

@@ -16,7 +16,7 @@ packages:
   - clang
   - git
 artifacts:
-  - ratatui_ruby/pkg/ratatui_ruby-1.0.0.gem
+  - ratatui_ruby/pkg/ratatui_ruby-1.1.0.gem
 sources:
   - https://git.sr.ht/~kerrick/ratatui_ruby
 tasks:

data/AGENTS.md

@@ -27,6 +27,7 @@ Architecture:
 
 ### STRICT REQUIREMENTS
 
+- **Check Before Implementing:** FIRST check tests for existing coverage. If it works, say so and point to the test.
 - Every file MUST begin with an SPDX-compliant header. Use `AGPL-3.0-or-later` for code; `CC-BY-SA-4.0` for documentation. `reuse annotate` can help you generate the header. **For Ruby files**, wrap SPDX comments in `#--` / `#++` to hide them from RDoc output.
 - Every line of Ruby MUST be covered by tests that would stand up to mutation testing.
   - Tests must be meaningful and verify specific behavior or rendering output; simply verifying that code "doesn't crash" is insufficient and unacceptable.
@@ -62,14 +63,14 @@ Architecture:
 - Every public Ruby class/method must be documented for humans in RDoc (preferred)--**not** YARD--or markdown files (fallback), and must have `*.rbs` types defined.
 - Every significant architectural and design decision must be documented for contributors in markdown files. Mermaid is allowed.
 - **Rust-backed methods:** For methods implemented in Rust (magnus bindings), use RDoc directives instead of empty method bodies. Use `##` followed by `:method:`, `:call-seq:`, and prose. End with `(Native method implemented in Rust)`. See `lib/ratatui_ruby.rb` for examples.
-- Refer to [docs/contributors/design/ruby_frontend.md](docs/contributors/design/ruby_frontend.md) for detailed design philosophy regarding the Immediate Mode paradigm including Data-Driven UI and Frames.
+- Refer to [doc/contributors/design/ruby_frontend.md](doc/contributors/design/ruby_frontend.md) for detailed design philosophy regarding the Immediate Mode paradigm including Data-Driven UI and Frames.
 
 ### Rust Standards
 
 - **Crate Type:** `cdylib`.
 - **Bindings:** Use [magnus](https://github.com/matsadler/magnus).
 - **Platform:** Support macOS (Apple Silicon), Linux, and Windows.
-- Refer to [docs/contributors/design/rust_backend.md](docs/contributors/design/rust_backend.md) for detailed implementation guidelines, module structure, and rendering logic.
+- Refer to [doc/contributors/design/rust_backend.md](doc/contributors/design/rust_backend.md) for detailed implementation guidelines, module structure, and rendering logic.
 
 ## 2. Directory Structure Convention
 

data/CHANGELOG.md

@@ -18,15 +18,41 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ### Removed
 
+## [1.1.0] - 2026-01-25
+
+### Added
+
+- **Terminal Capability Detection**: New class methods on `RatatuiRuby::Terminal` for environment-based capability detection before initializing TUI mode:
+  - `Terminal.tty?` — checks if stdout is connected to a terminal
+  - `Terminal.dumb?` — checks if TERM is explicitly set to "dumb"
+  - `Terminal.no_color?` — checks if NO_COLOR environment variable is set (respects the [NO_COLOR standard](https://no-color.org/))
+  - `Terminal.force_color?` — checks if FORCE_COLOR environment variable is set
+  - `Terminal.interactive?` — returns true only when tty? and not dumb?
+  - `Terminal.available_color_count` — returns color support level (8, 256, or 65535) via crossterm detection
+  - `Terminal.color_support` — convenience method returning `:none`, `:basic`, `:ansi256`, or `:truecolor`
+  - `Terminal.supports_keyboard_enhancement?` — checks for Kitty keyboard protocol support
+  - `Backend.window_size` — returns terminal dimensions as `Backend::WindowSize` with both character grid (`columns_rows`) and pixel (`pixels`) sizes as `Layout::Size` instances; mirrors upstream Ratatui's `backend::WindowSize` struct
+  - `Terminal.force_color_output(enable)` — globally overrides NO_COLOR detection for `--color=always` flags
+- **Alignment Constants**: New `RatatuiRuby::Layout::HorizontalAlignment` and `RatatuiRuby::Layout::VerticalAlignment` modules with discoverable constants (`LEFT`, `CENTER`, `RIGHT`, `TOP`, `BOTTOM`). `Layout::Alignment` is an alias for `HorizontalAlignment`. Use the constants for IDE discoverability, or continue passing symbols (`:left`, `:center`, etc.) directly—both work.
+- **Frame Count Query**: `RatatuiRuby.frame_count` returns the number of frames drawn since terminal initialization. The count starts at 0 when the terminal is created, increments by 1 after each draw, and resets when the terminal is restored and re-initialized.
+- **Mouse and Resize Symbol Comparison**: `Event::Mouse` and `Event::Resize` now support symbol comparison via `to_sym` and `==`, matching `Event::Key`. Use `event == :mouse_left_down`, `event == :scroll_up`, or `event == :resize` for cleaner event handling.
+- **Key Event DWIM Predicates**: `Event::Key` now supports alternate predicate forms for disambiguation and case handling. Arrow key aliases (`arrow_up?`, `up_arrow?`) distinguish keyboard input from `Mouse#up?`/`Mouse#down?`. The `key_` prefix and `_key` suffix (`key_up?`, `q_key?`) provide explicit key event matching in mixed event contexts. Capital letters match their shifted form naturally (`G?` matches `code="G"` with shift), and uppercase in predicates implies shift (`alt_B?` matches `alt_shift_B`).
+- **Generated RBS Predicate Declarations**: New `rake rbs:predicates` task generates RBS type declarations for all 1,328 `Event::Key` predicate methods (base keys, modifiers, characters, function keys, and all modifier combinations). Predicates are derived from a single source of truth in Rust FFI.
+
+### Changed
+
+### Fixed
+
+### Removed
+
 ## [1.0.0] - 2026-01-25
-This release is functionally equivalent to v0.10.3, with additional bug fixes.
-The version bump signals the beginning of the 1.0 release series.
 
 ### Added
 
 ### Changed
 
 ### Fixed
+
 - **back_tab? DWIM**: `back_tab?` and `backtab?` predicates now match events with code "back_tab" regardless of whether the shift modifier is explicitly present, since back_tab semantically implies shift.
 - **Terminal Queries During Draw (Deadlock)**: Calling `viewport_area`, `terminal_size`, `get_cell_at`, `poll_event`, `get_cursor_position`, or `get_viewport_type` from inside a `draw()` block previously caused the application to freeze forever. The thread blocked on a Mutex. Ruby's `Timeout` could not interrupt it. The only recovery was `kill -9`. These reads now work via a snapshot captured before rendering.
 - **Terminal Mutations During Draw (Deadlock)**: Calling `insert_before`, `set_cursor_position`, or `resize_terminal` from inside a `draw()` block previously caused the same silent freeze. These writes now raise `Error::Invariant` with a clear message.
@@ -34,6 +60,8 @@ The version bump signals the beginning of the 1.0 release series.
 - **Event Injection During Draw (Deadlock)**: Calling `inject_test_event` from inside a `draw()` block previously froze the application. Event injection now works correctly during draw.
 - **TableState Row Navigation Methods**: Added missing row navigation methods (`select_next`, `select_previous`, `select_first`, `select_last`) that should have been included alongside the column navigation methods added in v0.10.0. These methods match `ListState`'s navigation API and are used in the `app_stateful_interaction` example.
 
+### Removed
+
 ## [0.10.3] - 2026-01-16
 
 ### Added
@@ -348,7 +376,7 @@ The version bump signals the beginning of the 1.0 release series.
 ## [0.7.0] - 2026-01-03
 
 > [!WARNING]
-> v0.7.0 contains significant breaking changes. See the [Migration Guide](doc/v0.7.0_migration.md) for upgrade instructions.
+> v0.7.0 contains significant breaking changes. See the [Migration Guide](https://man.sr.ht/~kerrick/ratatui_ruby/history/migrations/v0_7_0.md) for upgrade instructions.
 
 ### Added
 
@@ -360,7 +388,7 @@ The version bump signals the beginning of the 1.0 release series.
 
 ### Changed
 
-- **Namespace Restructure (Breaking)**: Classes reorganized to match Ratatui's module hierarchy. See [Migration Guide](doc/v0.7.0_migration.md) for details:
+- **Namespace Restructure (Breaking)**: Classes reorganized to match Ratatui's module hierarchy. See [Migration Guide](https://man.sr.ht/~kerrick/ratatui_ruby/history/migrations/v0_7_0.md) for details:
   - `RatatuiRuby::Rect` → `RatatuiRuby::Layout::Rect`
   - `RatatuiRuby::Constraint` → `RatatuiRuby::Layout::Constraint`
   - `RatatuiRuby::Layout` → `RatatuiRuby::Layout::Layout`
@@ -683,10 +711,8 @@ The version bump signals the beginning of the 1.0 release series.
 - **Testing Support**: Included `RatatuiRuby::TestHelper` and RSpec integration to make testing your TUI applications possible.
 
 [Unreleased]: https://git.sr.ht/~kerrick/ratatui_ruby/refs/HEAD
+[1.1.0]: https://git.sr.ht/~kerrick/ratatui_ruby/refs/v1.1.0
 [1.0.0]: https://git.sr.ht/~kerrick/ratatui_ruby/refs/v1.0.0
-[1.0.0-beta.3]: https://git.sr.ht/~kerrick/ratatui_ruby/refs/v1.0.0-beta.3
-[1.0.0-beta.2]: https://git.sr.ht/~kerrick/ratatui_ruby/refs/v1.0.0-beta.2
-[1.0.0-beta.1]: https://git.sr.ht/~kerrick/ratatui_ruby/refs/v1.0.0-beta.1
 [0.10.3]: https://git.sr.ht/~kerrick/ratatui_ruby/refs/v0.10.3
 [0.10.2]: https://git.sr.ht/~kerrick/ratatui_ruby/refs/v0.10.2
 [0.10.1]: https://git.sr.ht/~kerrick/ratatui_ruby/refs/v0.10.1

data/Steepfile

@@ -46,4 +46,5 @@ target :lib do
   library "fileutils"
   library "minitest"
   library "date"
+  library "timeout"
 end

data/doc/concepts/application_testing.md

@@ -76,7 +76,7 @@ end
 ```
 <!-- SPDX-SnippetEnd -->
 
-For the full API list, including `buffer_content` and `cursor_position`, see [RatatuiRuby::TestHelper::Terminal](../lib/ratatui_ruby/test_helper/terminal.rb).
+For the full API list, including `buffer_content` and `cursor_position`, see [RatatuiRuby::TestHelper::Terminal](../../lib/ratatui_ruby/test_helper/terminal.rb).
 
 ## Verifying Styles
 
@@ -99,7 +99,7 @@ assert_area_style({ x: 0, y: 0, w: 10, h: 1 }, bg: :blue)
 ```
 <!-- SPDX-SnippetEnd -->
 
-See [RatatuiRuby::TestHelper::StyleAssertions](../lib/ratatui_ruby/test_helper/style_assertions.rb) for the comprehensive list of style helpers.
+See [RatatuiRuby::TestHelper::StyleAssertions](../../lib/ratatui_ruby/test_helper/style_assertions.rb) for the comprehensive list of style helpers.
 
 ## Simulating Input
 
@@ -127,7 +127,7 @@ end
 ```
 <!-- SPDX-SnippetEnd -->
 
-See [RatatuiRuby::TestHelper::EventInjection](../lib/ratatui_ruby/test_helper/event_injection.rb) for helper methods like `inject_keys` and `inject_click`.
+See [RatatuiRuby::TestHelper::EventInjection](../../lib/ratatui_ruby/test_helper/event_injection.rb) for helper methods like `inject_keys` and `inject_click`.
 
 ## Snapshot Testing
 
@@ -158,7 +158,7 @@ To prevent this:
 1.  **Seed Randomness:** Use a fixed seed for any RNG.
 2.  **Stub Time:** Force the application to use a static time.
 
-For detailed strategies and code examples, see [RatatuiRuby::TestHelper::Snapshot](../lib/ratatui_ruby/test_helper/snapshot.rb).
+For detailed strategies and code examples, see [RatatuiRuby::TestHelper::Snapshot](../../lib/ratatui_ruby/test_helper/snapshot.rb).
 
 ## Isolated View Testing
 
@@ -186,7 +186,7 @@ end
 ```
 <!-- SPDX-SnippetEnd -->
 
-See [RatatuiRuby::TestHelper::TestDoubles](../lib/ratatui_ruby/test_helper/test_doubles.rb).
+See [RatatuiRuby::TestHelper::TestDoubles](../../lib/ratatui_ruby/test_helper/test_doubles.rb).
 
 ## Example
 

data/doc/concepts/event_handling.md

@@ -27,7 +27,7 @@ For simple key events, `RatatuiRuby::Event::Key` objects can be compared directl
 > [!NOTE]
 > On macOS, the **Option** key is mapped to `alt`. The **Command** key is typically intercepted by the terminal emulator and may not be sent to the application, or it may be mapped to Meta/Alt depending on your terminal settings.
 
-For a complete list of supported keys, modifiers, and event types, please refer to the [API Documentation for RatatuiRuby::Event](file:///Users/kerrick/Developer/ratatui_ruby/lib/ratatui_ruby/event.rb).
+For a complete list of supported keys, modifiers, and event types, please refer to the [API Documentation for RatatuiRuby::Event](../../lib/ratatui_ruby/event.rb).
 
 <!-- SPDX-SnippetBegin -->
 <!--

data/doc/contributors/design/ruby_frontend.md

@@ -9,25 +9,53 @@ This document describes the architectural design and guiding principles of the R
 
 ## Guiding Design Principles
 
-### 1. Ratatui Alignment
+### 1. Three-Tier Namespace Architecture
 
-The Ruby namespace structure mirrors Ratatui's Rust module hierarchy exactly. This is a deliberate architectural choice with specific benefits:
+The gem provides three distinct namespaces, each with a specific purpose:
 
-- **Documentation Mapping**: A contributor reading Ratatui's docs for `ratatui::widgets::Table` immediately knows to look at `RatatuiRuby::Widgets::Table`.
-- **Predictability**: No mental translation required between Rust and Ruby codebases.
-- **Scalability**: As Ratatui adds new types, the Ruby placement is deterministic.
+**Tier 1: `Ratatui::` — Upstream Alignment**
 
-**Module Mapping:**
+Pure upstream Ratatui types with 1:1 API correspondence. If it exists in Rust Ratatui, it has the same name and location here.
 
 | Rust Module | Ruby Module | Purpose |
 |-------------|-------------|---------|
-| `ratatui::layout` | `RatatuiRuby::Layout` | Rect, Constraint, Layout |
-| `ratatui::widgets` | `RatatuiRuby::Widgets` | All widgets (Table, List, Paragraph, Block, etc.) |
-| `ratatui::style` | `RatatuiRuby::Style` | Style, Color |
-| `ratatui::text` | `RatatuiRuby::Text` | Span, Line |
-| `ratatui::buffer` | `RatatuiRuby::Buffer` | Cell (for buffer inspection) |
+| `ratatui::layout` | `Ratatui::Layout` | Rect, Constraint, Layout, Position, Size |
+| `ratatui::widgets` | `Ratatui::Widgets` | All widgets (Table, List, Paragraph, Block, etc.) |
+| `ratatui::style` | `Ratatui::Style` | Style, Color |
+| `ratatui::text` | `Ratatui::Text` | Span, Line |
+| `ratatui::buffer` | `Ratatui::Buffer` | Cell (for buffer inspection) |
+| `ratatui::backend` | `Ratatui::Backend` | WindowSize |
+| `ratatui::Terminal` | `Ratatui::Terminal` | Terminal lifecycle (draw, size, cursor) |
+| `ratatui::Frame` | `Ratatui::Frame` | Frame object for render callbacks |
 
-This structure resolves name collisions that would otherwise require arbitrary prefixes. For example, `Buffer::Cell` (terminal cell inspection) vs `Widgets::Cell` (table cell construction) are clearly distinct.
+**Tier 2: `Crossterm::` — Backend Alignment**
+
+Direct exposure of crossterm functionality. These are terminal I/O primitives that Ratatui builds upon.
+
+| Rust Module | Ruby Module | Purpose |
+|-------------|-------------|---------|
+| `crossterm::terminal` | `Crossterm::Terminal` | `supports_keyboard_enhancement?`, `window_size` |
+| `crossterm::style` | `Crossterm::Style` | `available_color_count`, `force_color_output` |
+
+**Tier 3: `RatatuiRuby::` — Ruby Convenience Layer**
+
+Ruby-specific conveniences, the main entry point, and the TUI DSL facade. This is where Ruby idioms live.
+
+- `RatatuiRuby.run { |tui| ... }` — Main entry point with setup/teardown
+- `RatatuiRuby.tty?`, `RatatuiRuby.dumb?`, `RatatuiRuby.interactive?` — Environment detection (Ruby-specific)
+- `RatatuiRuby::TUI` — DSL facade with shorthand factory methods
+- `RatatuiRuby::TestHelper` — Testing utilities
+- `RatatuiRuby::Error` — Exception hierarchy
+
+**Why Three Tiers?**
+
+1. **Upstream Purity**: Users who want exact Ratatui API parity use `Ratatui::` and `Crossterm::` namespaces.
+2. **Ruby Idioms**: Users who want convenience use `RatatuiRuby.run`, the TUI facade, and helper methods.
+3. **Documentation Mapping**: A contributor reading Ratatui's Rust docs immediately knows where to find the Ruby equivalent.
+4. **Predictability**: As upstream adds types, their Ruby placement is deterministic.
+
+> [!NOTE]
+> This three-tier architecture will be rolled out incrementally as 1.x releases. The `Ratatui::` and `Crossterm::` namespaces are additive—`RatatuiRuby::` will continue to work by delegating to them. No breaking changes required.
 
 ### 2. Two-Layer Architecture
 

data/doc/contributors/design/rust_backend.md

@@ -166,11 +166,20 @@ Defines the Ruby module hierarchy using `magnus` and exports public functions (`
 
 Manages the global `TERMINAL` singleton (mutex-wrapped `CrosstermBackend<Stdout>`).
 
-Key functions:
+**Lifecycle Functions:**
 - `init()` — Enter raw mode, enable mouse capture, switch to alternate screen
 - `restore()` — Disable raw mode, restore main screen
 - `get_cell_at(x, y)` — Return buffer cell as Ruby `Buffer::Cell` object
 
+**Crossterm Capability Queries:**
+
+These functions expose crossterm's terminal capability detection to Ruby. In the three-tier architecture, they'll be surfaced via the `Crossterm::` namespace:
+
+- `terminal_window_size()` — Returns `(columns, rows, pixel_width, pixel_height)` via `crossterm::terminal::window_size()`
+- `available_color_count()` — Returns color depth (8/256/65535) via crossterm's `COLORTERM`/`TERM` detection
+- `supports_keyboard_enhancement()` — Queries Kitty keyboard protocol support
+- `force_color_output(enable)` — Overrides `NO_COLOR` detection via `crossterm::style::force_color_output()`
+
 **Safety Note:** The terminal is a global mutable resource. All access goes through a mutex. Holding the lock across Ruby calls risks deadlock—release the lock before calling back into Ruby.
 
 ### `frame.rs` — Frame Wrapper
@@ -230,6 +239,9 @@ pub fn render_widget(frame: &mut Frame, area: Rect, node: Value) -> Result<(), E
 
 **Namespace Pattern:** All built-in widgets use the `RatatuiRuby::Widgets::*` namespace. The dispatcher matches on full class names, not prefixes.
 
+> [!NOTE]
+> The dispatcher will be updated to also match `Ratatui::Widgets::*` class names when the three-tier namespace architecture rolls out. This is additive—existing `RatatuiRuby::` names will continue to work. See [Ruby Frontend Design](./ruby_frontend.md) for details.
+
 ### `widgets/*.rs` — Widget Renderers
 
 Each widget has its own module with a standard interface:

data/doc/contributors/releasing.md

@@ -0,0 +1,215 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Releasing
+
+This guide documents RatatuiRuby's release workflow. We use
+[trunk-based development](https://trunkbaseddevelopment.com/committing-straight-to-the-trunk/)
+with [release branches](https://trunkbaseddevelopment.com/branch-for-release/).
+
+## Overview
+
+- **`trunk`** — Active development. Features land here first.
+- **`release/X.Y`** — Release series branches (e.g., `release/1.0`).
+- **`stable`** — Always points to the latest stable release.
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```
+trunk        ──●──●──●──●──●──●──●──●──●──  (future work)
+               \           \
+release/1.0  ───●──●──●     \              (1.0.0, 1.0.1, ...)
+                             \
+release/1.1                   ●──●──●──    (1.1.0, 1.1.1, ...)
+```
+<!-- SPDX-SnippetEnd -->
+
+## Versioning Philosophy
+
+We follow strict SemVer without ceremony:
+
+- **Breaking change?** → Bump major
+- **New feature?** → Bump minor
+- **Bug fix?** → Bump patch
+
+Version numbers are technical artifacts, not marketing. If we end up at v50 by
+year's end, so be it.
+
+## Changelog Management
+
+Trunk maintains the canonical project history. Each release branch maintains
+its own changelog during development, then syncs back to trunk.
+
+### During Beta/RC Cycles
+
+The release branch (`release/1.0`) tracks granular changes:
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```markdown
+## [Unreleased]
+
+## [1.0.0-beta.2] - 2026-01-20
+### Fixed
+- TableState row navigation methods
+
+## [1.0.0-beta.1] - 2026-01-20
+- Initial 1.0 beta release
+```
+<!-- SPDX-SnippetEnd -->
+
+Trunk's `[Unreleased]` section accumulates features for the next minor:
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```markdown
+## [Unreleased]
+### Added
+- Terminal Capability Detection
+
+### Fixed
+- TableState row navigation methods
+```
+<!-- SPDX-SnippetEnd -->
+
+The fix appears in both places. This is correct — both branches contain it.
+
+### When Final Ships
+
+When `1.0.0` final releases, **consolidate** all beta entries into one section
+on both branches:
+
+**release/1.0:**
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```markdown
+## [1.0.0] - 2026-xx-xx
+### Fixed
+- TableState row navigation methods
+
+## [0.10.3] - 2026-01-16
+...
+```
+<!-- SPDX-SnippetEnd -->
+
+**trunk (synced):**
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```markdown
+## [Unreleased]
+### Added
+- Terminal Capability Detection
+
+## [1.0.0] - 2026-xx-xx
+### Fixed
+- TableState row navigation methods
+
+## [0.10.3] - 2026-01-16
+...
+```
+<!-- SPDX-SnippetEnd -->
+
+The beta granularity served its purpose during testing. Git tags preserve the
+detailed history.
+
+## Release Workflows
+
+### Bugfix (Patch) Release
+
+For bugs affecting a released version:
+
+1. **Fix on trunk first** — All bugs get fixed on trunk.
+2. **Cherry-pick to release branch** with provenance:
+   ```bash
+   git checkout release/1.0
+   git cherry-pick -x <commit>   # -x adds "cherry picked from" trailer
+   ```
+3. **Update the changelog** on the release branch.
+4. **Bump and release:**
+   ```bash
+   bundle exec rake bump:patch
+   bundle exec rake release
+   ```
+
+### New Version (Major/Minor)
+
+When trunk is ready for a new release series:
+
+1. **Decide version** based on changes:
+   - Breaking changes → Major (2.0.0)
+   - New features only → Minor (1.1.0)
+
+2. **Create release branch:**
+   ```bash
+   git checkout trunk
+   git checkout -b release/1.1  # or release/2.0
+   ```
+
+3. **Release from the branch:**
+   ```bash
+   bundle exec rake bump:exact[1.1.0-beta.1]
+   bundle exec rake release
+   ```
+
+4. **Bump trunk** to the next dev version if desired.
+
+5. **Iterate** through betas/RCs as needed, then ship final.
+
+6. **Sync changelog** — When final ships, add the consolidated section to trunk.
+
+### Prerelease Notes
+
+RubyGems normalizes prerelease versions. Our `rake release` task automatically:
+
+1. Lets Bundler create the normalized tag (e.g., `v1.0.0.pre.beta.1`)
+2. Deletes it locally and remotely
+3. Creates the SemVer tag (e.g., `v1.0.0-beta.1`) and pushes it
+
+This keeps our Git tags strictly SemVer-compliant.
+
+## Commands Reference
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```bash
+# Bump version
+bundle exec rake bump:patch           # 1.0.0 → 1.0.1
+bundle exec rake bump:minor           # 1.0.0 → 1.1.0
+bundle exec rake bump:major           # 1.0.0 → 2.0.0
+bundle exec rake bump:exact[1.0.0-beta.1]
+
+# Release (builds, tags, pushes gem, updates stable branch)
+bundle exec rake release
+
+# Watch builds
+bin/hbs                               # Wait for SourceHut builds
+bin/hbs && bundle exec rake release   # Release only if builds pass
+```
+<!-- SPDX-SnippetEnd -->
+
+## Further Reading
+
+- [Trunk-Based Development](https://trunkbaseddevelopment.com/)
+- [Branch for Release](https://trunkbaseddevelopment.com/branch-for-release/)
+- [SemVer Specification](https://semver.org/)
+- [Keep a Changelog](https://keepachangelog.com/)

data/doc/contributors/todo/align/api_completeness_audit-finished.md

@@ -62,6 +62,12 @@ These documents catalog EVERY public feature, method, function, enum variant, an
 | Direction::Vertical | ratatui-core/src/layout/direction.rs:20 | ✅ |
 | Position struct | ratatui-core/src/layout/position.rs:57 | ✅ |
 | Size struct | ratatui-core/src/layout/size.rs:46 | ✅ |
+| HorizontalAlignment::Left | ratatui-core/src/layout/alignment.rs:25 | ✅ |
+| HorizontalAlignment::Center | ratatui-core/src/layout/alignment.rs:26 | ✅ |
+| HorizontalAlignment::Right | ratatui-core/src/layout/alignment.rs:27 | ✅ |
+| VerticalAlignment::Top | ratatui-core/src/layout/alignment.rs:40 | ✅ |
+| VerticalAlignment::Center | ratatui-core/src/layout/alignment.rs:41 | ✅ |
+| VerticalAlignment::Bottom | ratatui-core/src/layout/alignment.rs:42 | ✅ |
 | Rect struct | ratatui-core/src/layout/rect.rs:134 | ✅ |
 | Rect::new | ratatui-core/src/layout/rect.rs:166 | ✅ |
 | Rect::area | ratatui-core/src/layout/rect.rs:190 | ✅ |

data/doc/contributors/todo/align/api_completeness_audit-unfinished.md

@@ -29,19 +29,13 @@ These documents catalog EVERY public feature, method, function, enum variant, an
 
 **Notes:**
 - **Terminal struct**: No direct Terminal object; abstracted behind `RatatuiRuby` module methods
-- **Terminal::get_cursor_position/set_cursor_position**: Only available via [Frame](file:///Users/kerrick/Developer/ratatui_ruby/lib/ratatui_ruby/frame.rb#72-257) during draw, not on Terminal
+- **Terminal::get_cursor_position/set_cursor_position**: Only available via [Frame](../../../../lib/ratatui_ruby/frame.rb#72-257) during draw, not on Terminal
 
 ## Layout Features
 
 | Feature Name | File/Line | Status |
 |--------------|-----------|--------|
 | Spacing enum | ratatui-core/src/layout/layout.rs:80 | ❌ |
-| HorizontalAlignment::Left | ratatui-core/src/layout/alignment.rs:25 | ❌ |
-| HorizontalAlignment::Center | ratatui-core/src/layout/alignment.rs:26 | ❌ |
-| HorizontalAlignment::Right | ratatui-core/src/layout/alignment.rs:27 | ❌ |
-| VerticalAlignment::Top | ratatui-core/src/layout/alignment.rs:40 | ❌ |
-| VerticalAlignment::Center | ratatui-core/src/layout/alignment.rs:41 | ❌ |
-| VerticalAlignment::Bottom | ratatui-core/src/layout/alignment.rs:42 | ❌ |
 | Offset struct | ratatui-core/src/layout/offset.rs:10 | ❌ |
 | Margin struct | ratatui-core/src/layout/margin.rs:38 | ❌ |