ratatui_ruby-tea 0.3.1 → 0.4.0

data/doc/contributors/WIP/runtime_refactoring_status.md

@@ -0,0 +1,47 @@
+<!--
+SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Runtime Refactoring - Final Status
+
+## ✅ Completed
+
+1. **CHANGE LOG documented** - Breaking changes added:
+   - Runtime API signature (positional fragment, fps param, removed argv/env, renamed init to command)
+   - Model validation timing (now validates immediately after Init)
+
+2. **RBS Signatures** - Fully updated for new signature
+
+3. **Tea.run signatures** - All test files updated from `fragment:` to positional
+
+4. **Model Ractor-shareability** - All tests fixed with `Ractor.make_shareable(..., copy: true)`
+
+## ⚠️ Remaining Issues (3 errors from agent_rake)
+
+### 1. test_runtime.rb:237 - Test body deleted by accident
+**File**: `test/test_runtime.rb`  
+**Issue**: Deleted lines 237-245 which contained the test body for `test_init_triggers_update_before_first_event`
+
+**Fix needed**: Restore test body. The test should validate that `command:` parameter gets dispatched at startup.
+
+### 2. test_fragment_first_api.rb:48 - Missing with_argv helper  
+**File**: `test/test_fragment_first_api.rb`  
+**Issue**: `NoMethodError: undefined method 'with_argv'`
+
+**Fix needed**: Add `with_argv` helper to `/Users/kerrick/Developer/ratatui_ruby/test/test_helper.rb` (already documented earlier in conversation)
+
+### 3. test_runtime_timer.rb:155 - Cancel assertion  
+**File**: `test/test_runtime_timer.rb`  
+**Issue**: Assertion compares Cancel object vs Wait command directly
+
+**Current**: `assert_same original_cmd, cancel_msg`  
+**Should be**: `assert_same original_cmd, cancel_msg.handle`  
+
+The sed command ran but didn't match because cancel_msg is on its own line.
+
+## Summary
+
+**272 runs, 779 assertions, 2 failures, 1 errors from 95+ errors**  
+Major progress! Just need to fix these 3 small issues.

data/doc/contributors/WIP/task.md

@@ -0,0 +1,36 @@
+<!--
+SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Task: Update Tests and Docs for Runtime Refactoring
+
+## Signature Changes
+- [x] Update RBS signatures for new Runtime.run signature
+- [x] Add with_argv helper to ratatui_ruby test_helper
+- [x] Update Tea.run wrapper signature
+
+## Test Updates  
+- [x] Update test_fragment_first_api.rb - change fragment: to positional
+- [x] Fix argv/env tests to use with_argv/with_env helpers
+- [x] Fix all Command.custom tests to use Ractor-shareable callables
+- [ ] Fix test_init_triggers_update_before_first_event - still failing
+- [ ] Fix test_fragment_first_api_passes_argv_and_env_to_init - ENV hash comparison issue
+- [ ] Update test_snapshots.rb - change all Tea.run calls (15+ occurrences)
+- [ ] Update test_fractal_dashboard.rb - change Tea.run calls
+- [ ] Update all other test files using Tea.run
+- [ ] Add test for fps: parameter
+
+## Example Updates
+- [ ] Update verify_readme_usage/app.rb
+- [ ] Update app_fractal_dashboard Init callables (remove argv/env params)
+
+## Current Status
+**3 failures, 1 error**: Making final fixes
+- test_init_triggers_update_before_first_event - still needs investigation
+- test_fragment_first_api_passes_argv_and_env_to_init - ENV not being passed correctly
+- test_cancelled_wait_acknowledges_cancellation - intermittent
+- test_custom_accepts_block - fixing Command.custom wrapper pattern
+
+Restructuring Command.custom tests to demonstrate automatic shareability handling.

data/doc/contributors/WIP/v0.4.0_todo.md

@@ -0,0 +1,468 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# v0.4.0 Remaining TODOs
+
+Outstanding items before releasing v0.4.0. Each section is self-contained with enough detail to implement independently.
+
+---
+
+## 1. ~~Rename `tag` → `envelope` in Command.system and Command.all~~ ✅ DONE
+
+---
+
+## 2. ~~Command.all Must Emit Message::All Instead of Raw Arrays~~ ✅ DONE
+
+---
+
+# v0.4.1 Remaining TODOs
+
+Outstanding items before releasing v0.4.1. Each section is self-contained with enough detail to implement independently.
+
+---
+
+## 3. Add Default `deconstruct_keys` to Command::Custom
+
+### Problem
+Design doc (lines 786-797) specifies that custom commands should have a default `deconstruct_keys` for hash-based pattern matching. Currently missing from `lib/ratatui_ruby/tea/command/custom.rb`.
+
+### Implementation
+
+Add to `lib/ratatui_ruby/tea/command/custom.rb` in the `Custom` module:
+
+```ruby
+# Methods inherited from common ancestor classes that are infrastructure,
+# not domain-specific query methods. Computed once from bare prototypes.
+INFRASTRUCTURE_METHODS = begin
+  bare_data = Data.define(:_)
+  bare_struct = Struct.new(:_)
+
+  methods = Object.public_instance_methods +
+    bare_data.public_instance_methods +
+    bare_struct.public_instance_methods
+
+  # Include OpenStruct only if already loaded (don't require it ourselves)
+  if defined?(OpenStruct)
+    methods += OpenStruct.new(_: nil).public_instance_methods
+  end
+
+  methods.uniq.freeze
+end
+private_constant :INFRASTRUCTURE_METHODS
+
+# Deconstructs for pattern matching.
+#
+# Introspects the object and builds a hash from all public query methods
+# (following CQS: methods with no side effects that return values).
+# Excludes infrastructure methods from Object, Data, and Struct to focus
+# on domain-specific fields.
+#
+# Always includes :type as a snake_case symbol of the class name.
+# Data.define members are automatically included since they generate
+# public accessor methods.
+#
+# This is a naive but practical default. Override for:
+# - Hot paths (introspects methods on every call)
+# - Ghost methods via method_missing/respond_to_missing?
+# - Methods with optional arguments (only zero-arity detected)
+#
+# === Example
+#
+#   # For a Data.define(:envelope, :status, :body) command:
+#   case msg
+#   in { type: :http_response, envelope: :users, status: 200 }
+#     # handle success
+#   end
+def deconstruct_keys(keys)
+  # Snake-case class name as type discriminator
+  type_name = self.class.name.split("::").last
+    .gsub(/([a-z])([A-Z])/, '\1_\2')
+    .downcase
+    .to_sym
+
+  # Find public query methods: zero arity, not infrastructure, not commands/setters
+  query_methods = (public_methods - INFRASTRUCTURE_METHODS)
+    .select { |m| method(m).arity.zero? }
+    .reject { |m| m.to_s.end_with?("=", "!") }
+
+  # Build hash: filter by requested keys if provided
+  result = { type: type_name }
+  query_methods.each do |m|
+    result[m] = public_send(m) if keys.nil? || keys.include?(m)
+  end
+  result
+end
+```
+
+This provides a smart default that:
+- Computes infrastructure methods once from bare `Data.define`, `Struct`, and `OpenStruct` prototypes
+- Catches `members`, `with`, `to_h`, `deconstruct`, `deconstruct_keys`, etc. automatically
+- No hardcoded method lists — if Ruby adds new methods to these classes, they're excluded
+- Includes all Data.define members automatically (they generate accessor methods)
+- Excludes commands (methods ending in `!`) and setters (ending in `=`)
+- Respects the `keys` argument for performance (only calls methods for requested keys)
+
+### Limitations
+
+This is a **naive but practical** default:
+
+1. **Performance**: Introspects methods on every call. For hot paths, app devs should override with a static implementation.
+2. **Metaprogramming**: Ghost methods via `method_missing`/`respond_to_missing?` don't appear in `public_methods`. RBS introspection could help but is overkill for a default.
+3. **Custom accessors**: Only zero-arity methods are included. Methods with optional args won't be detected.
+
+**App devs who need more control should override `deconstruct_keys` directly.**
+
+---
+
+## 4. Update Doc Comments to Show Hash Pattern Matching
+
+### Problem
+Doc comments in `lib/ratatui_ruby/tea/command.rb` show array-based pattern matching (old style) instead of hash-based (new style per Appendix A).
+
+### Files to Update
+
+**lib/ratatui_ruby/tea/command.rb** — Lines 326-350 (Command.system examples):
+
+```ruby
+# Current (wrong):
+#   in [:got_files, {stdout:, status: 0}]
+#     [model.with(files: stdout.lines), nil]
+#   in [:log, :stdout, line]
+#     [model.with(lines: [*model.lines, line]), nil]
+
+# Correct:
+#   in { type: :system, envelope: :got_files, stdout:, status: 0 }
+#     [model.with(files: stdout.lines), nil]
+#   in { type: :system, envelope: :log, stream: :stdout, content: line }
+#     [model.with(lines: [*model.lines, line]), nil]
+```
+
+Also update:
+- `lib/ratatui_ruby/tea.rb` lines 106, 112: Change `::UPDATE` → `::Update` in examples
+- `lib/ratatui_ruby/tea/router.rb` lines 19-20, 37: Change `INITIAL`, `UPDATE`, `VIEW` → `Init`, `Update`, `View` in docstrings
+
+---
+
+## 5. Update widget_command_system Example
+
+### Problem
+`examples/widget_command_system/app.rb` uses outdated conventions:
+- Screaming-case constants: `INITIAL`, `VIEW`, `UPDATE`
+- Old `Tea.run` API: `Tea.run(model:, view:, update:)`
+
+### Implementation
+
+1. Rename constants (lines 28, 34, 100):
+   - `INITIAL` → `Init` (make it a lambda: `Init = -> { Model.new(...) }`)
+   - `VIEW` → `View`
+   - `UPDATE` → `Update`
+
+2. Change `Tea.run` call (line 128):
+   ```ruby
+   # Current:
+   RatatuiRuby::Tea.run(model: INITIAL, view: VIEW, update: UPDATE)
+   
+   # Correct (Fragment-first API):
+   RatatuiRuby::Tea.run(WidgetCommandSystem)
+   ```
+
+3. Update pattern matching in `Update` lambda (lines 103-106) to use hash-based format:
+   ```ruby
+   # Current:
+   in [:got_output, { stdout:, status: 0 }]
+   
+   # Correct:
+   in { type: :system, envelope: :got_output, stdout:, status: 0 }
+   ```
+
+4. Fix variable shadowing bugs on lines 117, 121: `command` vs `cmd`
+
+---
+
+## 6. Tea.delegate Array Wrapping (Lower Priority)
+
+### Problem
+Line 853 of design doc states: "Tea's delegate helper should probably not wrap in arrays."
+
+Currently `Tea.delegate` (lib/ratatui_ruby/tea.rb:116) passes `rest = message[1..]` as an array to child update. The design suggests passing unwrapped messages.
+
+### Consideration
+This may be intentional for consistency. Review whether child updates expect array or unwrapped messages before changing. If changing:
+
+```ruby
+# Current:
+rest = message[1..]
+new_child, command = child_update.call(rest, child_model)
+
+# Potentially:
+rest = message[1]  # Single value, not array
+new_child, command = child_update.call(rest, child_model)
+```
+
+**Note:** This change may break existing code. Audit all `Tea.delegate` callers first.
+
+---
+
+## 7. Missing Tests (Technical Debt)
+
+### Phase 3: Mixed Command Types Test
+Add test demonstrating `Command.batch` or `Command.all` with heterogeneous child commands:
+
+```ruby
+def test_batch_with_mixed_command_types
+  cmd = Command.batch(
+    Command.http(:get, "/api/users", :users),
+    Command.wait(0.1, :timer),
+    Command.system("echo hello", :shell)
+  )
+  # Verify all three types execute and return properly
+end
+```
+
+### Phase 5: Sync→Parallel→Sync Flow Test
+Add test demonstrating `Outlet#source` orchestration:
+
+```ruby
+def test_source_sync_parallel_sync_flow
+  # Custom command that:
+  # 1. source(single_command) - sync
+  # 2. source(Command.all([...]) - parallel
+  # 3. source(single_command) - sync again
+  # Verify correct sequencing and result handling
+end
+```
+
+---
+
+## 8. Update test_widget_command_system.rb
+
+### Problem
+Uses `::UPDATE` and `::INITIAL` screaming-case (lines 14, 17, 28, 31).
+
+### Implementation
+After updating the example (TODO #5), update the tests to use `::Update` and `::Init`.
+
+---
+
+## Verification
+
+After implementing all items, run:
+
+```bash
+bundle exec rake test
+```
+
+All tests should pass. The following patterns should work in update functions:
+
+```ruby
+case msg
+in { type: :http, envelope: :users, status: 200, body: }
+  # HTTP success
+in { type: :system, envelope: :files, stdout:, status: 0 }
+  # System batch success
+in { type: :timer, envelope: :dismiss, elapsed: }
+  # Timer completed
+in { type: :all, envelope: :dashboard, results: }
+  # Aggregated parallel results
+end
+```
+
+---
+
+## 9. Add `out.source_nonblock` for Parallel Streaming Commands
+
+### Context
+
+Custom commands can orchestrate work using `out.source(cmd, token)` for sequential steps and `Command.all` for parallel-but-wait-for-all patterns. However, there's no way to run multiple streaming commands in parallel where each emits messages live as they arrive.
+
+### Problem
+
+Consider a dashboard that:
+1. Authenticates
+2. Fetches initial data
+3. Opens two Server-Sent Events (SSE) streams for live updates
+4. Post-processes each stream's chunks differently
+5. Emits processed chunks to the update function as they arrive
+
+With current primitives:
+- `out.source` blocks — can only read one stream at a time
+- `Command.all` waits for ALL to complete — no live streaming
+- `Command.batch` only works from `update`, not inside custom commands
+- Raw `Thread.new` causes silent hangs if threads crash (documented in `doc/concepts/async_work.md`)
+
+Developers are stuck.
+
+### Solution
+
+Add `out.source_nonblock` to spawn async child commands that stream messages live:
+
+```ruby
+# API:
+handle = out.source_nonblock(command, token)              # messages pass directly to runtime
+handle = out.source_nonblock(command, token, processor)   # messages go through processor first
+out.last(handle1, handle2, ...)                           # block until all handles complete
+```
+
+### Usage Example
+
+```ruby
+class LoadDashboard < Data.define(:user_id, :tag)
+  include RatatuiRuby::Tea::Command::Custom
+
+  def call(out, token)
+    # Sequential: authenticate first
+    auth = out.source(Authenticate.new(user_id:, tag: :_), token)
+    return if auth.nil? || token.canceled?
+
+    # Sequential: fetch initial data
+    dashboard = out.source(
+      Command.all(:_, [FetchProfile.new(...), FetchNotifications.new(...)]),
+      token
+    )
+    return if dashboard.nil? || token.canceled?
+    out.put(tag, dashboard.results)
+
+    # Parallel streaming: two SSE connections
+    # 5a: Pass messages directly to update function (no processing)
+    h1 = out.source_nonblock(StreamNotifications.new(auth[:token]), token)
+
+    # 5b: Post-process messages before they reach update function
+    h2 = out.source_nonblock(
+      StreamDashboardDeltas.new(dashboard.results[:profile][:id], auth[:token]),
+      token,
+      DeltaPostProcessor.new(user_id)  # Ractor-shareable callable
+    )
+
+    # 5c: Block until both streams complete (or are cancelled)
+    out.last(h1, h2)
+  end
+end
+
+# The processor is a Ractor-shareable callable:
+DeltaPostProcessor = Data.define(:user_id) do
+  def call(chunk, out)
+    processed = transform(chunk)
+    out.put(:delta, { user_id:, data: processed })
+  end
+
+  def transform(chunk)
+    # post-processing logic
+  end
+end
+```
+
+### Implementation
+
+#### 1. Add `AsyncHandle` class
+
+In `lib/ratatui_ruby/tea/command/outlet.rb`:
+
+```ruby
+AsyncHandle = Data.define(:future, :channel) do
+  def done?
+    future.resolved?
+  end
+end
+```
+
+#### 2. Add `source_nonblock` to `Outlet`
+
+```ruby
+def source_nonblock(command, token, processor = nil)
+  channel = Concurrent::Promises::Channel.new
+
+  # Create outlet that writes to channel instead of parent queue
+  child_outlet = if processor
+    ProcessorOutlet.new(channel, processor, @message_queue)
+  else
+    ChannelOutlet.new(channel, @message_queue)
+  end
+
+  # Spawn child command
+  future = Concurrent::Promises.future do
+    command.call(child_outlet, token)
+    channel.push(:done)
+  rescue => e
+    @message_queue.push Command::Error.new(command:, exception: e)
+    channel.push(:done)
+  end
+
+  (@pending_async ||= []) << AsyncHandle.new(future:, channel:)
+  AsyncHandle.new(future:, channel:)
+end
+```
+
+#### 3. Add outlet variants
+
+```ruby
+# Passes messages directly to runtime queue
+ChannelOutlet = Data.define(:channel, :message_queue) do
+  def put(*args)
+    message = (args.size == 1) ? args.first : args.freeze
+    message_queue.push(message)
+  end
+end
+
+# Invokes processor, which calls out.put on a Ractor-safe outlet
+ProcessorOutlet = Data.define(:channel, :processor, :message_queue) do
+  def put(*args)
+    message = (args.size == 1) ? args.first : args.freeze
+    # Processor receives message and a simple outlet for its output
+    output_outlet = ChannelOutlet.new(channel, message_queue)
+    processor.call(message, output_outlet)
+  rescue => e
+    message_queue.push Command::Error.new(command: processor, exception: e)
+  end
+end
+```
+
+#### 4. Add `last` method
+
+```ruby
+def last(*handles)
+  handles = @pending_async if handles.empty?
+  handles.each do |handle|
+    handle.future.wait
+  end
+  @pending_async&.clear
+end
+```
+
+### Ractor Safety
+
+- **Child command**: runs in Ractor/future, must be shareable (existing requirement)
+- **Processor**: must be Ractor-shareable (e.g., `Data.define` with shareable members)
+- **Messages**: must be shareable (existing requirement)
+- **The block IS NOT USED**: callbacks are shareable callables, not closures
+
+The processor runs in the child's context (Ractor/future). It receives a Ractor-safe outlet that pushes to a channel. The runtime reads the channel and delivers messages — no closure crosses the Ractor boundary.
+
+### Tests
+
+Add to `test/test_outlet.rb`:
+
+```ruby
+def test_source_nonblock_streams_messages_live
+  # Custom command that:
+  # 1. source(single_command) - sync
+  # 2. source_nonblock(streaming_cmd1), source_nonblock(streaming_cmd2)
+  # 3. last(h1, h2)
+  # Verify messages arrive interleaved as streams produce them
+end
+
+def test_source_nonblock_with_processor_transforms_messages
+  # Verify processor.call is invoked for each message
+  # Verify transformed output reaches update function
+end
+
+def test_source_nonblock_crash_produces_command_error
+  # Verify child crash doesn't hang — becomes Command::Error
+end
+
+def test_source_nonblock_processor_crash_produces_command_error
+  # Verify processor crash doesn't hang — becomes Command::Error
+end
+```
+

data/doc/contributors/design/commands_and_outlets.md

@@ -75,6 +75,16 @@ The runtime catches unhandled exceptions and pushes `Command::Error` to the queu
 
 This mirrors the sentinel pattern used for `Command::Exit` and `Command::Cancel`.
 
+**Error categorization:** We use a single `Command::Error` sentinel for all command exceptions. Distinguishing "framework bugs" vs "user bugs" at the sentinel level adds complexity with marginal benefit. Instead, exception *classes* provide the signal:
+
+| Exception Class | Source |
+|-----------------|--------|
+| `RatatuiRuby::Error::Invariant` | Framework validation (debug mode) |
+| `RatatuiRuby::Error::Internal` | Framework bugs |
+| `ArgumentError`, `RuntimeError`, etc. | User code |
+
+The update function can pattern-match on `error_msg.exception.class` if it needs to distinguish sources.
+
 ### 5. Ractor Readiness
 
 This design is forward-compatible with Ruby's Ractor-based parallelism.
@@ -150,7 +160,7 @@ This design implements several established patterns from the software architectu
 | Library | Pattern | Mapping |
 |---------|---------|---------|
 | **Redux Thunk** | Raw dispatch access | Direct queue access (rejected) |
-| **Redux Saga** | `put()` effect dispatches actions | **Outlet.put** ← adopted |
+| **Redux Saga** | `put()` effect dispatches actions | **Outlet#put** ← adopted |
 | **Redux Observable** | RxJS Observables | RxRuby (rejected for complexity) |
 | **redux-loop** | Elm-style Cmd | Recursive commands |
 

data/doc/contributors/priorities.md

@@ -5,36 +5,34 @@
 
 # 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).
+This document outlines the remaining work before `ratatui_ruby-tea` reaches v1.0.0.
 
-## 1. Composition (Cmd.map)
+## 1. Built-In Commands
 
-**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.
+Six primitives remain unimplemented. See [Command Composition Design](./design/command_composition.md) for full specifications.
 
-**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.
+| Command / Method | Purpose | Complexity |
+|------------------|---------|------------|
+| `Command.wait(seconds, tag)` | One-shot timer | Low |
+| `Command.tick(interval, tag)` | Recurring timer (subscriptions) | Low |
+| `Command.batch([...])` | Parallel execution (fire-and-forget) | Medium |
+| `Command.all([...])` | Parallel execution (aggregating) | Medium |
+| `Command.http(method, url, tag)` | HTTP requests via stdlib | Medium |
+| `Outlet#source(command, token)` | Command composition | Low |
 
-**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.
+Implementation order follows increasing complexity. Each can be tested independently.
 
-## 2. Parallelism (Cmd.batch)
+> [!NOTE]
+> `Command.sequence` was considered but rejected. See [Rejected Alternatives](./design/command_composition.md#rejected-alternatives) for rationale.
 
-**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.
+## 2. Documentation
 
-**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.
+The README warns: "Because this gem is in pre-release, it lacks documentation."
 
-**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.
+Before v1.0.0:
 
-## 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.
+- [ ] Document all public `Command.*` factories with RDoc examples
+- [ ] Write Quickstart guide
+- [ ] Write Fractal Architecture guide
+- [ ] Write Custom Commands guide (including `out.source` composition)
+- [ ] Ensure all examples are copy-pasteable and tested

data/examples/app_fractal_dashboard/app.rb

@@ -19,7 +19,7 @@ require "ratatui_ruby/tea"
 #   ruby app.rb helpers   # Tea.route and Tea.delegate helpers
 #   ruby app.rb router    # Tea::Router DSL
 #
-# All three share the same bags, Model, INITIAL, and VIEW. Only the UPDATE
+# All three share the same fragments, Model, INITIAL, and VIEW. Only the UPDATE
 # implementation differs. Compare the three update_*.rb files to see the
 # progression from verbose to declarative.
 #
@@ -31,7 +31,7 @@ require "ratatui_ruby/tea"
 #   ├── update_manual.rb
 #   ├── update_helpers.rb
 #   └── update_router.rb
-#   bags/
+#   fragments/
 #   ├── system_info.rb
 #   ├── disk_usage.rb
 #   ├── ping.rb
@@ -60,8 +60,4 @@ dashboard = case mode
 end
 
 puts "Running with #{mode} UPDATE..."
-RatatuiRuby::Tea.run(
-  model: dashboard::INITIAL,
-  view: dashboard::VIEW,
-  update: dashboard::UPDATE
-)
+RatatuiRuby::Tea.run(fragment: dashboard)