ratatui_ruby-tea 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 98c01a74284a7bef17c45bd1fa409f9821f7a792e7803017dc4b33907bb41cbd
-  data.tar.gz: 1b850234318bd7a69c06f765661afe659c8d8f7c04b14b7ef36a41031e84965f
+  metadata.gz: d10ee51cb79e58e9b24dbf78e696dcbc901ddedac44dce824c4cf8817e8b07a3
+  data.tar.gz: 1043f33f9e3804748ea3fdd5eef4783b7af3a81ed51b10ce88f3447953e1874e
 SHA512:
-  metadata.gz: 50f75f3c72061a42b4349f259974b0d6a0815c401a324726a50e786c573ae4c668b28a06f294c7f6627ab39fcbb7f2218f76b30f67467d6ca2785073182d8b68
-  data.tar.gz: 7cd6873a151748dec33118de12c056878557648ec1561070a4c5a46c043d2d8b8e380d1657e78bc6f394bf4d73005ad5d5a6bc460b51b4788b4e2cd11fda0bc2
+  metadata.gz: e25205b29e1654964c88455f9a9fed89ee3464aacbecc458e128baae8bf0a788196e9c1fbdee9cea3549b0e9f60cf1bef5c48c870baa57af453759ad4625453b
+  data.tar.gz: 121c207a7c82109eafbcdbe7ebae838cccb33f54a0f6ff96c75832294e07496284c26c89fdf7bf0f871883959951414ab52582d209c52b1fb00249a0b009ab9f

data/.builds/ruby-3.2.yml

@@ -1,5 +1,5 @@
 # SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: AGPL-3.0-or-later
+# SPDX-License-Identifier: LGPL-3.0-or-later
 
 image: archlinux
 packages:
@@ -13,9 +13,10 @@ packages:
   - gdbm
   - ncurses
   - libffi
+  - clang
   - git
 artifacts:
-  - ratatui_ruby-tea/pkg/ratatui_ruby-tea-0.1.0.gem
+  - ratatui_ruby-tea/pkg/ratatui_ruby-tea-0.2.0.gem
 sources:
   - https://git.sr.ht/~kerrick/ratatui_ruby-tea
 tasks:
@@ -25,6 +26,7 @@ tasks:
       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

data/.builds/ruby-3.3.yml

@@ -1,5 +1,5 @@
 # SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: AGPL-3.0-or-later
+# SPDX-License-Identifier: LGPL-3.0-or-later
 
 image: archlinux
 packages:
@@ -13,9 +13,10 @@ packages:
   - gdbm
   - ncurses
   - libffi
+  - clang
   - git
 artifacts:
-  - ratatui_ruby-tea/pkg/ratatui_ruby-tea-0.1.0.gem
+  - ratatui_ruby-tea/pkg/ratatui_ruby-tea-0.2.0.gem
 sources:
   - https://git.sr.ht/~kerrick/ratatui_ruby-tea
 tasks:
@@ -25,6 +26,7 @@ tasks:
       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

data/.builds/ruby-3.4.yml

@@ -1,5 +1,5 @@
 # SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: AGPL-3.0-or-later
+# SPDX-License-Identifier: LGPL-3.0-or-later
 
 image: archlinux
 packages:
@@ -13,9 +13,10 @@ packages:
   - gdbm
   - ncurses
   - libffi
+  - clang
   - git
 artifacts:
-  - ratatui_ruby-tea/pkg/ratatui_ruby-tea-0.1.0.gem
+  - ratatui_ruby-tea/pkg/ratatui_ruby-tea-0.2.0.gem
 sources:
   - https://git.sr.ht/~kerrick/ratatui_ruby-tea
 tasks:
@@ -25,6 +26,7 @@ tasks:
       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

data/.builds/ruby-4.0.0.yml

@@ -1,5 +1,5 @@
 # SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: AGPL-3.0-or-later
+# SPDX-License-Identifier: LGPL-3.0-or-later
 
 image: archlinux
 packages:
@@ -13,9 +13,10 @@ packages:
   - gdbm
   - ncurses
   - libffi
+  - clang
   - git
 artifacts:
-  - ratatui_ruby-tea/pkg/ratatui_ruby-tea-0.1.0.gem
+  - ratatui_ruby-tea/pkg/ratatui_ruby-tea-0.2.0.gem
 sources:
   - https://git.sr.ht/~kerrick/ratatui_ruby-tea
 tasks:
@@ -25,6 +26,7 @@ tasks:
       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

data/.rubocop.yml

@@ -1,5 +1,5 @@
 # SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: AGPL-3.0-or-later
+# SPDX-License-Identifier: LGPL-3.0-or-later
 
 inherit_from:
   - ./vendor/goodcop/base.yml

data/AGENTS.md

@@ -15,22 +15,29 @@ Description: Part of the RatatuiRuby ecosystem.
 
 ### STRICT REQUIREMENTS
 
-- 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 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 `agent_rake` to ensure commit-readiness. See Tools for detailed instructions.
+- **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 `agent_rake`** (provided by the `ratatui_ruby-devtools` gem) for running tests, linting, or checking compilation.
+- **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): `agent_rake`
-    - Runs specific task: `agent_rake test:ruby` (for example)
+    - 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!**
 
+### Tea-Specific Vocabulary
+
+- **BANNED WORD: "component"** — Reserved for Kit.
+- **Avoid "widget" for Tea units** — "Widget" refers to Engine/Ratatui render primitives. In Tea, call them **bags**.
+- **Bag:** A module containing `Model`, `INITIAL`, `UPDATE`, and `VIEW` constants. Bags compose: parent bags delegate to child bags.
+- 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+).
@@ -50,7 +57,8 @@ Description: Part of the RatatuiRuby ecosystem.
 
 Before considering a task complete:
 
-1. **Default Rake Task Passes:** Run `agent_rake` (no args). Confirm it passes with ZERO errors.
+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.
 2. **Documentation Updated:** If public APIs changed, update relevant docs.
 3. **Changelog Updated:** If public APIs changed, update CHANGELOG.md's **Unreleased** section.
 4. **Commit Message Suggested:** Include a suggested commit message block.

data/CHANGELOG.md

@@ -15,4 +15,75 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- Initial release of ratatui_ruby-tea
+### Changed
+
+### Fixed
+
+### Removed
+
+## [0.3.0] - 2026-01-08
+
+### Added
+
+- **Router DSL**: New `Tea::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:
+  - `Tea.route(command, :prefix)` — wraps a command to route results to a child bag
+  - `Tea.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 "ratatui_ruby/tea/shortcuts"` and `include Tea::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 `RatatuiRuby::Tea.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**: `RatatuiRuby::Tea.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 `ratatui_ruby-tea`, a Ruby implementation of The Elm Architecture (TEA) for `ratatui_ruby`. Scaffolding generated by `ratatui_ruby-devtools`.
+
+[Unreleased]: https://git.sr.ht/~kerrick/ratatui_ruby-tea/refs/HEAD
+[0.3.0]: https://git.sr.ht/~kerrick/ratatui_ruby-tea/refs/v0.3.0
+[0.2.0]: https://git.sr.ht/~kerrick/ratatui_ruby-tea/refs/v0.2.0
+[0.2.0]: https://git.sr.ht/~kerrick/ratatui_ruby-tea/refs/v0.2.0
+[0.1.0]: https://git.sr.ht/~kerrick/ratatui_ruby-tea/refs/v0.1.0

data/README.md

@@ -80,7 +80,46 @@ gem install ratatui_ruby-tea
 
 ## Usage
 
-_Because this gem is in pre-release, it lacks documentation. Please check the source files.
+**ratatui_ruby-tea** uses the Model-View-Update (MVU) pattern. You provide an immutable model, a view function, and an update function.
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+<!-- SYNC:START:examples/verify_readme_usage/app.rb:mvu -->
+```ruby
+Model = Data.define(:text)
+MODEL = Model.new(text: "Hello, Ratatui! Press 'q' to quit.")
+
+VIEW = -> (model, tui) do
+  tui.paragraph(
+    text: model.text,
+    alignment: :center,
+    block: tui.block(
+      title: "My Ruby TUI App",
+      borders: [:all],
+      border_style: { fg: "cyan" }
+    )
+  )
+end
+
+UPDATE = -> (msg, model) do
+  if msg.q? || msg.ctrl_c?
+    RatatuiRuby::Tea::Command.exit
+  else
+    model
+  end
+end
+
+def run
+  RatatuiRuby::Tea.run(model: MODEL, view: VIEW, update: UPDATE)
+end
+```
+<!-- SYNC:END -->
+<!-- SPDX-SnippetEnd -->
+
+![Hello Ratatui](./doc/images/verify_readme_usage.png)
 
 For a full tutorial, see [the Quickstart](./doc/getting_started/quickstart.md). For an explanation of the application architecture, see [Application Architecture](./doc/concepts/application_architecture.md).
 
@@ -117,7 +156,7 @@ Want to help develop **ratatui_ruby-tea**? Check out the [contribution guide on
 
 The library is [LGPL-3.0-or-later](./LICENSES/LGPL-3.0-or-later.txt): you can use it in proprietary applications, but you must share changes you make to **ratatui_ruby-tea** itself. Documentation snippets and widget examples are [MIT-0](./LICENSES/MIT-0.txt): copy and use them without attribution.
 
-Documentation is [CC-BY-SA-4.0](./LICENSES/CC-BY-SA-4.0.txt). Build tooling and full app examples are [AGPL-3.0-or-later](./LICENSES/AGPL-3.0-or-later.txt). See each file's SPDX comment for specifics.
+Documentation is [CC-BY-SA-4.0](./LICENSES/CC-BY-SA-4.0.txt). Build tooling and full app examples are [LGPL-3.0-or-later](./LICENSES/LGPL-3.0-or-later.txt). See each file's SPDX comment for specifics.
 
 Some parts of this program are copied from other sources under appropriate reuse licenses, and the copyright belongs to their respective owners. See the [REUSE Specification – Version 3.3](https://reuse.software/spec-3.3/) for details.
 

data/REUSE.toml

@@ -1,5 +1,5 @@
 # SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: AGPL-3.0-or-later
+# SPDX-License-Identifier: LGPL-3.0-or-later
 
 version = 1
 
@@ -11,12 +11,12 @@ SPDX-License-Identifier = "CC0-1.0"
 [[annotations]]
 path = '**/snapshots/*.txt'
 SPDX-FileCopyrightText = "2026 Kerrick Long <me@kerricklong.com>"
-SPDX-License-Identifier = "AGPL-3.0-or-later"
+SPDX-License-Identifier = "LGPL-3.0-or-later"
 
 [[annotations]]
 path = '**/snapshots/*.ansi'
 SPDX-FileCopyrightText = "2026 Kerrick Long <me@kerricklong.com>"
-SPDX-License-Identifier = "AGPL-3.0-or-later"
+SPDX-License-Identifier = "LGPL-3.0-or-later"
 
 [[annotations]]
 path = 'doc/images/*'

data/Rakefile

@@ -2,7 +2,7 @@
 
 #--
 # SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: AGPL-3.0-or-later
+# SPDX-License-Identifier: LGPL-3.0-or-later
 #++
 
 require "bundler/gem_tasks"

data/Steepfile

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+
+target :lib do
+  signature "sig"
+  check "lib"
+
+  library "pathname"
+  library "fileutils"
+  library "minitest"
+end

data/doc/concepts/application_architecture.md

@@ -5,12 +5,191 @@
 
 # Application Architecture
 
-Architect robust TUI applications using core library patterns and API best practices.
+Build robust TUI applications with Tea patterns.
 
 ## Core Concepts
 
-_Because this gem is in pre-release, it lacks documentation. Please check the source files._
+_This section is incomplete. Check the source files._
 
 ## Thread and Ractor Safety
 
-_Because this gem is in pre-release, it lacks documentation. Please check the source files._
+### The Strategic Context
+
+Ruby 4.0 introduces [Ractors](https://docs.ruby-lang.org/en/4.0/Ractor.html)—
+true parallel actors that forbid shared mutable state. Code that passes
+mutable objects between threads crashes in a Ractor world.
+
+Tea prepares you today. The runtime enforces Ractor-shareability on every
+Model and Message *now*, using standard threads. Pass a mutable object,
+and it raises an error immediately. Write Ractor-safe code today; upgrade
+to Ruby 4.0 without changes tomorrow.
+
+Enforce immutability rules before you strictly need them, and the migration
+is invisible.
+
+### The Problem
+
+Ruby's Ractor model prevents data races by forbidding shared mutable state.
+Mutable objects cause runtime errors:
+
+```
+RatatuiRuby::Error::Invariant: Model is not Ractor-shareable.
+```
+
+### The Solution
+
+Use `Ractor.make_shareable`. It recursively freezes everything:
+
+```ruby
+Ractor.make_shareable(model.with(text: "#{model.text}#{char}"))
+```
+
+For constants, wrap INITIAL:
+
+```ruby
+INITIAL = Ractor.make_shareable(
+  Model.new(text: "", running: false, chunks: [])
+)
+```
+
+For collection updates:
+
+```ruby
+new_chunks = Ractor.make_shareable([*model.chunks, new_item])
+```
+
+### The Lightweight Alternative
+
+When you know exactly what's mutable, `.freeze` is shorter:
+
+```ruby
+[model.with(text: "#{model.text}#{char}".freeze), nil]
+```
+
+### Foot-Guns
+
+#### frozen_string_literal Only Affects Literals
+
+The magic comment freezes strings that appear directly in source code.
+Computed strings are mutable.
+
+```ruby
+# frozen_string_literal: true
+
+"literal"        # frozen ✓
+"#{var}"         # mutable ✗
+str.chop         # mutable ✗
+str + other      # mutable ✗
+```
+
+#### Data.define Needs Shareable Values
+
+`Data.define` creates frozen instances. The instance is Ractor-shareable
+only when all its values are shareable.
+
+### Quick Reference
+
+| Pattern | Code |
+|---------|------|
+| Make anything shareable | `Ractor.make_shareable(obj)` |
+| Freeze a string | `str.freeze` |
+| INITIAL constant | `Ractor.make_shareable(Model.new(...))` |
+| Array update | `Ractor.make_shareable([*old, new])` |
+
+### Debugging
+
+See this error?
+
+```
+RatatuiRuby::Error::Invariant: Model is not Ractor-shareable.
+```
+
+Wrap the returned model with `Ractor.make_shareable`.
+
+## Modals and Command Result Routing
+
+Modals capture keyboard input. They overlay the main UI and intercept keypresses until dismissed. But async commands keep running in the background. When their results arrive, they look like any other message.
+
+It's tempting to intercept *all* messages when the modal is active. This swallows those command results.
+
+### The Scenario
+
+1. User presses "u" to fetch uptime. The runtime dispatches an async command.
+2. User presses "c" to open a modal dialog.
+3. The uptime command completes. It sends `[:network, :uptime, { stdout:, ... }]`.
+4. The modal intercept sees the modal is active. It routes that message to the modal.
+5. The modal ignores it.
+6. The uptime panel never updates.
+
+### The Fix
+
+Route command results before modal interception. Modals intercept user input, not async results.
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```ruby
+# Wrong: modal intercepts everything
+UPDATE = lambda do |message, model|
+  if Modal.active?(model.modal)
+    # Swallows command results
+    return Modal::UPDATE.call(message, model.modal)
+  end
+
+  case message
+  in [:network, *rest]
+    # Never reached while modal is open
+  end
+end
+
+# Correct: route command results first
+UPDATE = lambda do |message, model|
+  # 1. Route async command results (always)
+  case message
+  in [:network, *rest]
+    return [model.with(network: new_network), command]
+  in [:stats, *rest]
+    return [model.with(stats: new_stats), command]
+  else
+    nil
+  end
+
+  # 2. Modal intercepts user input
+  if Modal.active?(model.modal)
+    return Modal::UPDATE.call(message, model.modal)
+  end
+
+  # 3. Handle other input
+  case message
+  in _ if message.q? then Command.exit
+  end
+end
+```
+<!-- SPDX-SnippetEnd -->
+
+### The Router DSL
+
+`Tea::Router` handles this correctly. Routes declared with `route :prefix, to: ChildModule` process before keymap handlers. Command results flow through even when guards block keyboard input.
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```ruby
+module Dashboard
+  include Tea::Router
+
+  route :stats, to: StatsPanel
+  route :network, to: NetworkPanel
+
+  keymap do
+    only when: MODAL_INACTIVE do
+      key "u", -> { Uptime.fetch_command }
+    end
+  end
+end
+```
+<!-- SPDX-SnippetEnd -->

data/doc/contributors/priorities.md

@@ -0,0 +1,40 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Feature Priorities
+
+This document outlines the critical next steps for `ratatui_ruby-tea`. Each item explains the context, the problem, and the solution, following our [Documentation Style](../ratatui_ruby/doc/contributors/documentation_style.md).
+
+## 1. Composition (Cmd.map)
+
+**Context:** Real applications grow. You start with a file picker. Then a modal. Then a sidebar. Each component has its own model and update function.
+
+**Problem:** The Tea architecture naturally isolates components. A parent model holds a child model. But when the child update function returns a message (like `:selected`), the parent `update` function only understands its own messages. It cannot "hear" the child. The architecture breaks at the boundary of the first file.
+
+**Solution:** Implement `Cmd.map(cmd) { |child_msg| ... }`. This wraps the child's effect. When the effect completes, the runtime passes the result through the block, transforming the child's message into a parent's message. This restores the flow of data up the tree.
+
+## 2. Parallelism (Cmd.batch)
+
+**Context:** Applications often need to do two things at once. You initialize the app. You need to load the config *and* fetch the latest data *and* start the tick timer.
+
+**Problem:** The `update` function returns a single tuple `[Model, Cmd]`. It cannot return `[Model, Cmd1, Cmd2]`. Without a way to group them, you are forced to sequence independent operations, making the UI feel slow and linear.
+
+**Solution:** Implement `Cmd.batch([cmd1, cmd2, ...])`. This command takes an array of commands and submits them all to the runtime. The runtime executes them in parallel (where possible) or concurrently.
+
+## 3. Serial Execution (Cmd.sequence)
+
+**Context:** Some effects depend on others. You cannot read a file until you have downloaded it. You cannot query the database until you have opened the connection.
+
+**Problem:** The Tea architecture relies on async messages. You send a command, and *eventually* you get a message. To chain actions, you must handle the first success message in `update`, then return the second command. This smears a single logical transaction across multiple independent `case` clauses, creating "callback hell" but in the shape of a state machine.
+
+**Solution:** Implement `Cmd.sequence([cmd1, cmd2, ...])`. This command executes the first command. If successful, it runs the next. If any fail, it stops. Note: This assumes commands have a standard "success/failure" result shape, or simply runs them blindly. (Design decision required: does `sequence` wait for the message, or just the execution?)
+
+## 4. Time (Cmd.tick)
+
+**Context:** Animations and real-time updates. A spinner rotating. A clock ticking. Evaluation metrics updating live.
+
+**Problem:** The runtime blocks on input. If the user doesn't type or click, the screen stays frozen. You cannot implement a simple "Loading..." spinner because the frame never updates.
+
+**Solution:** Implement `Cmd.tick(interval, tag)`. This command sleeps for the interval and then sends a message. The `update` function handles the message and returns the *same* tick command again. This creates a recursive loop, driving the frame rate independent of user input.

data/doc/custom.css

@@ -1,6 +1,6 @@
 /*
  * SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
- * SPDX-License-Identifier: AGPL-3.0-or-later
+ * SPDX-License-Identifier: LGPL-3.0-or-later
  */
 
 img {

data/examples/app_fractal_dashboard/README.md

@@ -0,0 +1,60 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Cmd.map Fractal Dashboard
+
+Demonstrates **Fractal Architecture** using `Cmd.map` for component composition.
+
+## Problem
+
+Without composition, a complex app needs one giant `case` statement handling every possible message from every child—the "God Reducer" anti-pattern. This doesn't scale.
+
+## Solution
+
+`Cmd.map` wraps child commands so their results route through parents:
+
+```ruby
+# Child produces [:system_info, {stdout:, ...}]
+child_cmd = SystemInfoWidget.fetch_cmd
+
+# Parent wraps to produce [:stats, :system_info, {...}]
+parent_cmd = Cmd.map(child_cmd) { |m| [:stats, *m] }
+```
+
+Each layer handles only its own messages. Parents pattern-match on the first element to route to the correct child.
+
+## Architecture
+
+```
+Dashboard (root)
+├── StatsPanel
+│   ├── SystemInfoWidget → Cmd.exec("uname -a", :system_info)
+│   └── DiskUsageWidget  → Cmd.exec("df -h", :disk_usage)
+└── NetworkPanel
+    ├── PingWidget       → Cmd.exec("ping -c 1 localhost", :ping)
+    └── UptimeWidget     → Cmd.exec("uptime", :uptime)
+```
+
+## Hotkeys
+
+| Key | Action |
+|-----|--------|
+| `s` | Fetch system info |
+| `d` | Fetch disk usage |
+| `p` | Ping localhost |
+| `u` | Fetch uptime |
+| `q` | Quit |
+
+## Key Concepts
+
+1. **Widget isolation**: Each widget has its own `Model`, `UPDATE`, and `fetch_cmd`. It knows nothing about parents.
+2. **Message routing**: Parents prefix child messages (`:stats`, `:network`) and pattern-match to route.
+3. **Recursive dispatch**: `Cmd.map` delegates inner command execution to the runtime, then transforms the result.
+
+## Usage
+
+```bash
+ruby examples/widget_cmd_map/app.rb
+```