rooibos 0.5.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f7a4f2a869c06e70b95a34cac8915f8d8e6543283007fd7c595692cf34bf3329
+  data.tar.gz: c8c0be8e5059b55671baa49105aa7b470dfdfa17647353f4e81ebcf06ecf7f15
+SHA512:
+  metadata.gz: 97556fd7362f24d3d5572da7b11485456b3066bc56ef77994c2448a62085aa62d54c8503c5ffa2cea4472dd556bff1328ececb1dcb0c323cf663fdd1267ac8c9
+  data.tar.gz: c02267ab34497516ee6b6fee6daab08b72fcf26f6d4499aaf5d98162df1f063ee7eeec0464361189d3371a77434cf94d72b030289acea29cbc0d4b972691f1aa

data/.builds/ruby-3.2.yml

@@ -0,0 +1,51 @@
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+
+image: archlinux
+packages:
+  - bash
+  - base-devel
+  - curl
+  - openssl
+  - libyaml
+  - zlib
+  - readline
+  - gdbm
+  - ncurses
+  - libffi
+  - clang
+  - git
+sources:
+  - https://git.sr.ht/~kerrick/ratatui_ruby-tea
+tasks:
+  - setup: |
+      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 CI="true"
+      cd ratatui_ruby-tea
+      sed -i 's/ruby = .*/ruby = "3.2"/' mise.toml
+      mise install
+      mise x -- pip install reuse
+      mise x -- gem install bundler:4.0.3
+      mise reshim
+      mise x -- bundle config set --local frozen 'true'
+      mise x -- bundle install
+  - test: |
+      . ~/.buildenv
+      cd ratatui_ruby-tea
+      echo "Testing Ruby 3.2"
+      mise x -- bundle exec rake test
+  - lint: |
+      . ~/.buildenv
+      cd ratatui_ruby-tea
+      echo "Linting Ruby 3.2"
+      mise x -- bundle exec rake lint
+  - package: |
+      . ~/.buildenv
+      cd ratatui_ruby-tea
+      mise x -- bundle exec rake build

data/.builds/ruby-3.3.yml

@@ -0,0 +1,51 @@
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+
+image: archlinux
+packages:
+  - bash
+  - base-devel
+  - curl
+  - openssl
+  - libyaml
+  - zlib
+  - readline
+  - gdbm
+  - ncurses
+  - libffi
+  - clang
+  - git
+sources:
+  - https://git.sr.ht/~kerrick/ratatui_ruby-tea
+tasks:
+  - setup: |
+      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 CI="true"
+      cd ratatui_ruby-tea
+      sed -i 's/ruby = .*/ruby = "3.3"/' mise.toml
+      mise install
+      mise x -- pip install reuse
+      mise x -- gem install bundler:4.0.3
+      mise reshim
+      mise x -- bundle config set --local frozen 'true'
+      mise x -- bundle install
+  - test: |
+      . ~/.buildenv
+      cd ratatui_ruby-tea
+      echo "Testing Ruby 3.3"
+      mise x -- bundle exec rake test
+  - lint: |
+      . ~/.buildenv
+      cd ratatui_ruby-tea
+      echo "Linting Ruby 3.3"
+      mise x -- bundle exec rake lint
+  - package: |
+      . ~/.buildenv
+      cd ratatui_ruby-tea
+      mise x -- bundle exec rake build

data/.builds/ruby-3.4.yml

@@ -0,0 +1,51 @@
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+
+image: archlinux
+packages:
+  - bash
+  - base-devel
+  - curl
+  - openssl
+  - libyaml
+  - zlib
+  - readline
+  - gdbm
+  - ncurses
+  - libffi
+  - clang
+  - git
+sources:
+  - https://git.sr.ht/~kerrick/ratatui_ruby-tea
+tasks:
+  - setup: |
+      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 CI="true"
+      cd ratatui_ruby-tea
+      sed -i 's/ruby = .*/ruby = "3.4"/' mise.toml
+      mise install
+      mise x -- pip install reuse
+      mise x -- gem install bundler:4.0.3
+      mise reshim
+      mise x -- bundle config set --local frozen 'true'
+      mise x -- bundle install
+  - test: |
+      . ~/.buildenv
+      cd ratatui_ruby-tea
+      echo "Testing Ruby 3.4"
+      mise x -- bundle exec rake test
+  - lint: |
+      . ~/.buildenv
+      cd ratatui_ruby-tea
+      echo "Linting Ruby 3.4"
+      mise x -- bundle exec rake lint
+  - package: |
+      . ~/.buildenv
+      cd ratatui_ruby-tea
+      mise x -- bundle exec rake build

data/.builds/ruby-4.0.0.yml

@@ -0,0 +1,51 @@
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+
+image: archlinux
+packages:
+  - bash
+  - base-devel
+  - curl
+  - openssl
+  - libyaml
+  - zlib
+  - readline
+  - gdbm
+  - ncurses
+  - libffi
+  - clang
+  - git
+sources:
+  - https://git.sr.ht/~kerrick/ratatui_ruby-tea
+tasks:
+  - setup: |
+      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 CI="true"
+      cd ratatui_ruby-tea
+      sed -i 's/ruby = .*/ruby = "4.0.0"/' mise.toml
+      mise install
+      mise x -- pip install reuse
+      mise x -- gem install bundler:4.0.3
+      mise reshim
+      mise x -- bundle config set --local frozen 'true'
+      mise x -- bundle install
+  - test: |
+      . ~/.buildenv
+      cd ratatui_ruby-tea
+      echo "Testing Ruby 4.0.0"
+      mise x -- bundle exec rake test
+  - lint: |
+      . ~/.buildenv
+      cd ratatui_ruby-tea
+      echo "Linting Ruby 4.0.0"
+      mise x -- bundle exec rake lint
+  - package: |
+      . ~/.buildenv
+      cd ratatui_ruby-tea
+      mise x -- bundle exec rake build

data/.pre-commit-config.yaml

@@ -0,0 +1,16 @@
+# SPDX-FileCopyrightText: 2020 Free Software Foundation Europe e.V.
+# SPDX-License-Identifier: CC0-1.0
+repos:
+  - repo: local
+    hooks:
+      -   id: bundle-check
+          name: Check Gemfile.lock
+          entry: bundle check
+          language: system
+          files: (Gemfile|Gemfile\.lock|rooibos\.gemspec)
+          pass_filenames: false
+      -   id: rake
+          name: rake
+          entry: bundle exec rake
+          language: system
+          pass_filenames: false

data/.rubocop.yml

@@ -0,0 +1,8 @@
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+
+inherit_from:
+  - ./vendor/goodcop/base.yml
+
+AllCops:
+  TargetRubyVersion: "3.2"

data/AGENTS.md

@@ -0,0 +1,108 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# AGENTS.md
+
+## Project Identity
+
+Project Name: rooibos
+
+Description: Part of the RatatuiRuby ecosystem.
+
+## 1. Standards
+
+### STRICT REQUIREMENTS
+
+- Every file MUST begin with an SPDX-compliant header. Use `LGPL-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.
+- **Pre-commit:** Use `bundle exec agent_rake` to ensure commit-readiness. See Tools for detailed instructions.
+- **Git Pager:** ALWAYS set `PAGER=cat` for ALL `git` commands (e.g., `PAGER=cat git diff`). This is mandatory.
+
+### Tools
+
+- **NEVER** run `bundle exec rake` directly. **NEVER** run `bundle exec ruby -Ilib:test ...` directly.
+- **ALWAYS use `bundle exec agent_rake`** (provided by the `ratatui_ruby-devtools` gem) for running tests, linting, or checking compilation.
+  - **Usage:**
+    - Runs default task (compile + test + lint): `bundle exec agent_rake`
+    - Runs specific task: `bundle exec agent_rake test:ruby` (for example)
+- **Setup:** `bin/setup` must handle Bundler dependencies.
+- **Git:** ALWAYS set `PAGER=cat` with `git`. **THIS IS CRITICAL!**
+
+### Rooibos-Specific Vocabulary
+
+- **BANNED WORD: "component"** — Reserved for Kit.
+- **Avoid "widget" for Rooibos units** — "Widget" refers to Engine/Ratatui render primitives. In Rooibos, call them **fragments**.
+- **Fragment:** A module containing `Model`, `INITIAL`, `UPDATE`, and `VIEW` constants. Fragments compose: parent fragments delegate to child fragments.
+- Use "model", "update", "view" for the MVU pattern. Use "message" (not "msg") and "command" (not "cmd").
+
+### Ruby Standards
+
+- Use `Data.define` for all value objects (Ruby 3.2+).
+- Define types in `.rbs` files. Don't use `untyped` just because it's easy; be comprehensive and accurate.
+- Every public Ruby class/method must be documented for humans in RDoc.
+
+## 2. Committing
+
+- Who commits: DON'T stage (DON'T `git add`) unless explicitly instructed. DON'T commit unless explicitly instructed. DO suggest a commit message when you finish.
+- **Format:**
+    - Format: Use [Conventional Commits](https://www.conventionalcommits.org/).
+    - Body: Explanation if necessary (wrap at 72 chars).
+        - **DON'T list the files changed or the edits made in the body.**
+        - **DON'T use markdown syntax** (no backticks, no bolding, no lists, no links).
+
+## 3. Definition of Done (DoD)
+
+Before considering a task complete and returning control to the user, you **MUST** ensure:
+
+0. **Production Ready:** RBS types are complete and accurate (no `untyped`), errors are handled with good DX, documentation follows guidelines, high code quality (no "pre-existing debt" excuses).
+1.  **Default Rake Task Passes:** Run `bundle exec agent_rake` (no args). Confirm it passes with ZERO errors **or warnings**.
+  - You will save time if you run `bundle exec agent_rake rubocop:autocorrect` first.
+  - If you think the rake is looking for deleted files, STOP EVERYTHING and tell the user.
+2.  **Documentation Updated:** If public APIs or observable behavior changed, update relevant RDoc, rustdoc, `doc/` files, `README.md`, and/or `ratatui_ruby-wiki` files.
+3.  **Changelog Updated:** If public APIs, observable behavior, or gemspec dependencies have changed, update [CHANGELOG.md](CHANGELOG.md)'s **Unreleased** section.
+4.  **Commit Message Suggested:** You **MUST** ensure the final message to the user includes a suggested commit message block. This is NOT optional.
+  - You MUST also check `git log -n1` to see the current standard AI footer ("Generated  with" and "Co-Authored-By") and include it in your suggested message.
+
+## 4. Committing
+
+- Who commits: DON'T stage (DON'T `git add`) unless explicitly instructed. DON'T commit unless explicitly instructed. DO suggest a commit message when you finish, even if not instructed..
+- When: Before reporting the task as complete to the user, suggest the commit message.
+- What: Consider not what you remember, but EVERYTHING in the `git diff` and `git diff --cached`.
+- **Format:**
+    - Format: Use [Conventional Commits](https://www.conventionalcommits.org/).
+    - 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.
+        - **DON'T list the files changed or the edits made in the body.** Don't provide a bulleted list of changes. Use prose to explain the problem and the solution.
+        - **DON'T use markdown syntax** (no backticks, no bolding, no lists, no links). The commit message must be plain text.
+- **Type conventions by directory:**
+    - `lib/`, `ext/`, `sig/`: Use `feat`, `fix`, `refactor`, `perf` as appropriate.
+    - `bin/`, `tasks/`, `.builds/`, CI/CD: Use `chore` for tooling internal to developing this gem. Use `feat`/`fix` for user-facing executables or changes that affect downstream users.
+    - `examples/`: Always `docs` (documentation by example).
+    - `test/`: Use `test` for new/changed tests, or match the type of the code being tested.
+    - `doc/`: Always `docs`.
+
+### 5. Changelog
+
+- Follow [Semantic Versioning](https://semver.org/)
+- Follow the [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) specification.
+- **What belongs in CHANGELOG:** Only changes that affect **application developers** or **higher-level library developers** who use or depend on `ratatui_ruby`:
+    - New public APIs or widget parameters
+    - Backwards-incompatible type signature changes, or behavioral additions to type signature changes
+    - Observable behavior changes (rendering, styling, layout)
+    - Deprecations and removals
+    - Breaking changes
+- **What does NOT belong in CHANGELOG:** Internal or non-behavioral 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
+    - Internal tooling, CI/CD, or build configuration changes
+    - Code style or linting changes
+    - Performance improvements that affect applications
+- Changelogs should be useful to downstream developers (both app and library developers), not simple restatements of diffs or commit messages.
+- The Unreleased section MUST be considered "since the last git tag". Therefore, if a change was done in one commit and undone in another (both since the last tag), the second commit should remove its changelog entry.
+- **Location:** New entries ALWAYS go in `## [Unreleased]`. Never edit past version sections (e.g., `## [0.4.0]`)—those are frozen history.

data/CHANGELOG.md

@@ -0,0 +1,214 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+
+## [Unreleased]
+
+### Added
+
+### Changed
+
+### Fixed
+
+### Removed
+
+## [0.5.0] - 2026-01-16
+
+### Added
+
+### Changed
+
+- **BREAKING: Rebrand to Rooibos**: The gem is now named `rooibos` and the module is top-level `Rooibos` instead of `RatatuiRuby::Tea`. Update your code, including:
+  - `require "ratatui_ruby/tea"` → `require "rooibos"`
+  - `RatatuiRuby::Tea::*` → `Rooibos::*`
+  - If you need a full migration guide, reach out to [the mailing list](https://lists.sr.ht/~kerrick/ratatui_ruby-discuss)
+
+### Fixed
+
+### Removed
+
+## [0.4.0] - 2026-01-16
+
+### Added
+
+- **Timer Commands**: `Command.wait(seconds, tag)` and `Command.tick(seconds, tag)` for timed events. After the duration, sends `tag` to the update function. Responds to cancellation cooperatively — sends `Command.cancel(self)` when cancelled so you can handle it. Uses `Concurrent::Cancellation.timeout` internally. `Command.tick` is an alias for `Command.wait`; the "recurring tick" pattern is achieved by re-dispatching in the update function.
+
+- **Command.uncancellable Factory**: Creates a fresh `Concurrent::Cancellation` that never fires. Use for commands wrapping non-cancellable blocking I/O (e.g., `Net::HTTP` requests).
+
+- **Command.batch**: Fire-and-forget parallel execution. `Command.batch(cmd1, cmd2)` or `Command.batch([cmds])` runs children in parallel; each child sends its own messages independently. On cancellation, emits `Command.cancel(self)` so you can detect the batch was stopped. Child errors surface as `Command::Error` so you can handle failures in your update function. One failing child does not stop the others. Requires all child commands to be Ractor-shareable.
+
+- **Command.all**: Aggregating parallel execution. `Command.all(:tag, cmd1, cmd2)` or `Command.all(:tag, [cmds])` runs children in parallel and waits for all to complete, then sends a single aggregated message. Array syntax produces `[:tag, [results]]`; variadic syntax splats results as `[:tag, result1, result2]`. On cancellation, emits `Command.cancel(self)`. Child errors surface as `Command::Error`. Requires all child commands to be Ractor-shareable.
+
+- **Outlet#source**: Command composition for multi-step workflows. `out.source(child_command, token, timeout: 30.0)` runs a child command synchronously within a custom command, returning its result (or `nil` if cancelled/timed out). Exceptions from failed children propagate to the caller. Use this to orchestrate sequential API calls, conditional fetches, or any workflow that needs one result before starting the next.
+
+- **Command.http**: Native HTTP client for API calls. Supports GET, POST, PUT, PATCH, DELETE with DWIM syntax: `Command.http(get: 'url')`, `Command.http(:get, 'url', :tag)`, etc. Returns hash-based `HttpResponse` with `deconstruct_keys` for pattern matching: `{ type: :http, envelope:, status:, body:, headers: }` or `{ type: :http, envelope:, error: }`. Optional `parser:` keyword invokes a callable on the response body for JSON, YAML, CSV, or custom parsing. SSL, default 10s timeout, and cancellation-before-request are supported. Parsers and parsed results must be Ractor-shareable.
+
+- **Streaming Command Data Loss Fix**: Fixed race condition in `Command.system(stream: true)` where fast commands could lose stdout/stderr data. Reader threads now `join` instead of `kill` to ensure all output is processed before completion.
+
+- **Message::Predicates Mixin**: Include in custom message types for safe predicate calls. Returns `false` for any unknown predicate method (ending in `?`). Enables pattern matching workflows where messages can respond to predicates like `msg.http?` or `msg.timer?` without raising `NoMethodError`. Includes `respond_to_missing?` for introspection parity.
+
+- **Message::Timer**: Predicate-rich response type for timer commands (`Command.wait`, `Command.tick`). Includes `timer?` predicate and `deconstruct_keys` for pattern matching with `type: :timer` discriminator. Contains `envelope` (routing symbol) and `elapsed` (actual wait time in seconds).
+
+- **Message::HttpResponse**: Moved from `Command::HttpResponse` to `Message::HttpResponse` with added predicates. Includes `http?`, `success?`, and `error?` predicates. Implements `deconstruct_keys` for pattern matching with `type: :http` discriminator.
+
+- **Message::System::Batch**: Response type for `Command.system` (batch mode). Includes `system?`, `success?` (exit 0), and `error?` (non-zero exit) predicates. Contains `envelope`, `stdout`, `stderr`, and `status`. Implements `deconstruct_keys` for pattern matching.
+
+- **Message::System::Stream**: Response type for `Command.system(..., stream: true)`. Includes `system?`, `stdout?`, `stderr?`, and `complete?` predicates. Contains `envelope`, `stream` type (`:stdout`, `:stderr`, `:complete`), `content` (for output lines), and `status` (for completion). Implements conditional `deconstruct_keys` based on stream type.
+
+- **Message::All**: Response type for `Command.all` aggregating parallel execution. Includes `all?` predicate. Contains `envelope`, `results` array, and `nested` boolean. Implements `deconstruct_keys` for pattern matching.
+
+- **Command Parameter Rename**: Renamed `tag` parameter to `envelope` across all commands for consistency: `Command.wait`, `Command.tick`, `Command.system`, and `Command.all`. These now use `envelope:` in their data definitions. Messages emit with `envelope:` for pattern matching.
+
+- **Dependencies**: Added `concurrent-ruby` (~> 1.3) and `concurrent-ruby-edge` (~> 0.7) for robust concurrency primitives.
+
+- **Rooibos.normalize_init Helper**: New `Rooibos.normalize_init(result)` normalizes Init callable returns. Accepts the output of a `Fragment.Init` callable and always returns `[model, command]`. Use when composing child fragment initialization in parent fragments.
+
+### Changed
+
+- **Terminology: "Bag" → "Fragment"**: Renamed Fractal Architecture units from "bags" to "fragments" throughout the codebase. A fragment is a module containing `Model`, `INITIAL`, `UPDATE`, and `VIEW` constants. Parent fragments compose child fragments via routing. The `examples/app_fractal_dashboard/bags/` directory is now `examples/app_fractal_dashboard/fragments/`. All API documentation, code comments, and examples updated to reflect this terminology change.
+
+- **Runtime API Signature (Breaking)**: `Rooibos.run` signature changed:
+  - Fragment parameter is now **positional** instead of keyword: `Rooibos.run(MyApp)` instead of `Rooibos.run(fragment: MyApp)`
+  - Removed `argv:` and `env:` parameters - Runtime now automatically uses `ARGV` and `ENV` globals
+  - Added `fps:` parameter (default 60) for configurable frame rate
+  - Renamed `init:` parameter to `command:` in explicit parameters API for clarity
+
+- **Fragment Convention Rename (Breaking)**: Fragment constants have new naming conventions:
+  - `INITIAL` constant → `Init` callable. The runtime calls `Init.()` to get the initial model.
+  - `UPDATE` constant → `Update` callable (capitalized).
+  - `VIEW` constant → `View` callable (capitalized).
+  - Init is now a lambda/callable instead of a frozen constant. This enables parameterized initialization and returning `[model, command]` tuples for initial commands.
+
+- **Internal Method Rename (Breaking)**: `Runtime.normalize_update_result` renamed to `Runtime.normalize_update_return` for clarity. Only affects code calling private Runtime internals.
+
+- **Command.custom Ractor Validation (Breaking)**: `Command.custom(callable)` now validates in debug mode that the callable is Ractor-shareable. Callables that capture mutable state will raise `Invariant`. Define callables at module level or use `Ractor.make_shareable`.
+
+- **Model Validation Timing (Breaking)**: Runtime now validates model Ractor-shareability **immediately after Init returns**, not just during the Update cycle. This catches mutable models earlier, enforcing immutability at startup. Models must be frozen (`.freeze`) or use immutable data structures (`Data.define`). This is a good breaking change that prevents subtle concurrency bugs.
+
+- **CancellationToken Replaced (Breaking)**: Custom commands now receive `Concurrent::Cancellation` instead of `CancellationToken`. The method to check cancellation changes from `token.cancelled?` (British) to `token.canceled?` (American).
+
+- **Outlet Accepts Channel (Breaking)**: `Outlet.new` now accepts a `Concurrent::Promises::Channel` instead of `Thread::Queue`.
+
+- **Outlet#put (Breaking)**: `out.put(msg)`, the common case now sends `msg` directly instead of `[msg]`; `out.put(a, b, c)` sends `[a, b, c]`. Previously all calls wrapped arguments in an array. Update functions that matched `when Array` may need adjustment.
+
+- **Command.all Output (Breaking)**: `Command.all` now emits `Message::All` objects instead of raw arrays. Previously emitted `[:tag, [results]]` (nested) or `[:tag, result1, result2]` (variadic). Now emits `Message::All` with `envelope`, `results`, and `nested` fields. Use hash pattern matching: `in { type: :all, envelope:, results:, nested: }`.
+
+### Fixed
+
+- **Streaming Command Data Loss**: Fixed race condition where fast commands (e.g., `echo hello`) could lose stdout/stderr messages. The streaming reader threads were being killed immediately after the child process exited, before they could finish reading buffered output. Now the runtime joins the reader threads to ensure all data is processed before sending `:complete`.
+
+### Removed
+
+- **CancellationToken Class**: Removed in favor of `Concurrent::Cancellation` from concurrent-ruby-edge.
+- **CancellationToken::NONE**: Removed. Use `Command.uncancellable` factory instead.
+
+## [0.3.1] - 2026-01-11
+
+### Added
+
+- **CancellationToken**: Cooperative cancellation mechanism for long-running custom commands. Commands check `cancelled?` periodically and stop gracefully when `cancel!` is called. Includes `CancellationToken::NONE` null object for commands that ignore cancellation.
+
+- **Command::Custom Mixin**: Include in your class to mark it as a custom command. Provides `rooibos_command?` brand predicate and `rooibos_cancellation_grace_period` (default 2.0 seconds) for configuring cleanup time after cancellation.
+
+- **Command::Outlet**: Messaging gateway for custom commands. Use `put(tag, *payload)` to send results back to the update function. Validates Ractor-shareability in debug mode.
+
+- **Custom Command Dispatch**: Runtime now dispatches custom commands (objects with `rooibos_command?` returning true) in background threads. Commands receive an `Outlet` for messaging and a `CancellationToken` for cooperative shutdown.
+
+- **Command.custom Factory**: Wraps lambdas/procs to give them unique identity for dispatch tracking. Each `Command.custom(callable)` call produces a distinct wrapper, enabling targeted cancellation. Accepts optional `grace_period:` to override the default 2.0 second cleanup window.
+
+- **Command.cancel Factory**: Request cancellation of a running command. Returns a `Command::Cancel` sentinel that the runtime routes to the appropriate command's CancellationToken.
+
+- **Runtime Cancellation Dispatch**: The runtime now handles `Command::Cancel` by signaling the target command's `CancellationToken`, enabling cooperative cancellation of long-running commands. Respects `rooibos_cancellation_grace_period`: waits for the grace period, then force-kills unresponsive threads. Use `Float::INFINITY` to never force-kill.
+
+- **Graceful Shutdown**: On exit, runtime signals all active commands then respects each command's grace period. Commands with `Float::INFINITY` grace are waited on indefinitely (user has SIGKILL). Final queue messages are processed before returning.
+
+- **Automatic Error Propagation**: Custom commands that raise unhandled exceptions now produce a `Command::Error` message instead of corrupting the TUI display. The runtime catches exceptions and pushes `Command::Error.new(command:, exception:)` to the queue. Pattern match on `Command::Error` in your update function to handle failures uniformly. Factory method `Command.error(command, exception)` is available for testing.
+
+- **Command::System Cancellation**: Streaming shell commands now respect cooperative cancellation. When cancelled, sends `SIGTERM` for graceful shutdown, then `SIGKILL` if the child process doesn't exit. Prevents orphaned child processes from lingering after app exit.
+
+### Changed
+
+### Fixed
+
+- **Ractor Enforcement is Debug-Only**: The Ractor-shareability check now only runs in debug mode (and automated tests). Production skips this check for performance, matching the original specification. Previously, the check ran unconditionally.
+
+### Removed
+
+## [0.3.0] - 2026-01-08
+
+### Added
+
+- **Router DSL**: New `Rooibos::Router` module provides declarative routing for Fractal Architecture:
+  - `route :prefix, to: ChildBag` — declares a child bag route
+  - `keymap { key "q", -> { Command.exit } }` — declares keyboard handlers
+  - `keymap { key "x", handler, when: -> (m) { m.ready? } }` — guards (also: `if:`, `only:`, `guard:`, `unless:`, `except:`, `skip:`)
+  - `keymap { only when: guard do ... end }` — nested guard blocks apply to all keys within (also: `skip when: ...`)
+  - `mousemap { click -> (x, y) { ... } }` — declares mouse handlers
+  - `action :name, handler` — declares reusable actions for key/mouse handlers
+  - `from_router` — generates an UPDATE lambda from routes and handlers
+
+- **Composition Helpers**: New helper methods for Fractal Architecture reduce boilerplate:
+  - `Rooibos.route(command, :prefix)` — wraps a command to route results to a child bag
+  - `Rooibos.delegate(message, :prefix, child_update, child_model)` — dispatches prefixed messages to child bags
+
+- **Command Mapping**: `Command.map(inner_command, &mapper)` wraps a child command and transforms its result message. Essential for parent bags routing child command results.
+
+- **Shortcuts Module**: `require "rooibos/shortcuts"` and `include Rooibos::Shortcuts` for short aliases:
+  - `Cmd.exit` — alias for `Command.exit`
+  - `Cmd.sh(command, tag)` — alias for `Command.system`
+  - `Cmd.map(command, &block)` — alias for `Command.map`
+
+- **Sync Event Integration**: Runtime now handles `Event::Sync` from `RatatuiRuby::SyntheticEvents`. When a Sync event is received, the runtime waits for all pending async threads and processes their results before continuing. Use `inject_sync` in tests for deterministic async verification.
+
+- **Streaming Command Output**: `Command.system` now accepts a `stream:` keyword argument. When `stream: true`, the runtime sends incremental messages (`[:tag, :stdout, line]`, `[:tag, :stderr, line]`) as output arrives, followed by `[:tag, :complete, {status:}]` when the command finishes. Invalid commands send `[:tag, :error, {message:}]`. Default behavior (`stream: false`) remains unchanged.
+
+- **Custom Shell Modal Example**: Added `examples/app_fractal_dashboard/bags/custom_shell_modal.rb` demonstrating a 3-bag fractal architecture for a modal that runs arbitrary shell commands with streaming output. Features interleaved stdout/stderr, exit status indication, and Ractor-safe implementation using `tui.overlay` for opaque rendering.
+
+### Changed
+
+- **Command Module Rename (Breaking)**: The `Cmd` module is now `Command` with Rubyish naming:
+  - `Cmd::Quit` → `Command::Exit` (use `Command.exit` factory)
+  - `Cmd::Exec` → `Command::System` (use `Command.system(cmd, tag)` factory)
+
+### Fixed
+
+### Removed
+
+## [0.2.0] - 2026-01-08
+
+### Added
+
+- **The Elm Architecture (TEA)**: Implemented the core Model-View-Update (MVU) runtime. Use `Rooibos.run(model, view: ..., update: ...)` to start an interactive application with predictable state management.
+- **Async Command System**: Side effects (database, HTTP, shell) are executed asynchronously in a thread pool. Results are dispatched back to the main loop as messages, ensuring the UI never freezes.
+- **Ractor Safety Enforcement**: The runtime strictly enforces that all `Model` and `Message` objects are Ractor-shareable (deeply frozen). This guarantees thread safety by design and prepares for future parallelism.
+- **Flexible Update Returns**: The `update` function supports multiple return signatures for developer ergonomics:
+  - `[Model, Cmd]` — Standard tuple.
+  - `Model` — Implicitly `[Model, Cmd::None]`.
+  - `Cmd` — Implicitly `[CurrentModel, Cmd]`.
+- **Startup Commands**: `Rooibos.run` accepts an `init:` parameter to dispatch an initial command immediately after startup, useful for loading initial data without blocking the first render.
+- **View Validation**: The `view` function must return a valid widget. Returning `nil` raises `RatatuiRuby::Error::Invariant` to catch bugs early.
+
+
+## [0.1.0] - 2026-01-07
+
+### Added
+
+- **First Release**: Empty release of `rooibos`, a Ruby implementation of The Elm Architecture (TEA) for `ratatui_ruby`. Scaffolding generated by `ratatui_ruby-devtools`.
+
+[Unreleased]: https://git.sr.ht/~kerrick/rooibos/refs/HEAD
+[0.5.0]: https://git.sr.ht/~kerrick/rooibos/refs/v0.5.0
+[0.4.0]: https://git.sr.ht/~kerrick/rooibos/refs/v0.4.0
+[0.3.1]: https://git.sr.ht/~kerrick/rooibos/refs/v0.3.1
+[0.3.0]: https://git.sr.ht/~kerrick/rooibos/refs/v0.3.0
+[0.2.0]: https://git.sr.ht/~kerrick/rooibos/refs/v0.2.0
+[0.2.0]: https://git.sr.ht/~kerrick/rooibos/refs/v0.2.0
+[0.1.0]: https://git.sr.ht/~kerrick/rooibos/refs/v0.1.0